# Opinionated Firearms

Project Zomboid B42 patch mod + tooling for managing `GaelGunStore` firearm/attachment/magazine spawn distribution.

## Workflow

1. Use CLI `extract` to build a JSON catalog from GGS source (`loot.lua` + scripts).
2. Load that catalog JSON in the webapp.
3. In the webapp, choose per item:
- spawn enabled/disabled
- where it should spawn (distribution list)
- spawn rate weight
4. Export a profile JSON from the webapp.
5. Use CLI `apply` to convert the profile JSON into `OFSpawnProfile.lua`.
6. Start Project Zomboid with this mod + `GaelGunStore_ALPHA`.

## CLI

Script: `tools/ggs-dist-cli.js`

### Extract catalog

```powershell
node tools/ggs-dist-cli.js extract --ggs-root source/GaelGunStore/42 --out data/ggs-spawn-catalog.json
```

Output contains:

- all firearms/attachments from GGS scripts
- magazines from GGS loot distribution data
- where they spawn (`list`)
- base spawn weight (`weight`)
- sandbox key (`sv`) used by GGS spawn multipliers

### Apply webapp profile

```powershell
node tools/ggs-dist-cli.js apply --profile data/of-spawn-profile.json --out common/media/lua/shared/OFSpawnProfile.lua
```

This writes the Lua profile the mod reads at runtime.

## Webapp

Path: `webapp/index.html`

Serve locally (recommended):

```powershell
python -m http.server 8080
# open http://localhost:8080/webapp/
```

Features:

- import extracted catalog JSON
- import existing profile JSON
- filter/search full item list
- toggle per-item spawn enabled
- edit per-list placements and weights
- export profile JSON for CLI `apply`

## Runtime mod behavior

Main patcher: `42/media/lua/server/distribution/OFDistributionBlocker.lua`

- loads block rules (`OFBlockConfig`) and spawn profile (`OFSpawnProfile`)
- removes blocked/managed entries from distributions
- removes disabled attachment entries from weapon auto-upgrade attachment pools
- removes disabled magazine entries from weapon auto-upgrade attachment pools
- re-adds managed item placements with chosen weights from spawn profile
- reparses ItemPicker after patching

## Files

- `mod.info`
- `42/mod.info`
- `42/media/lua/server/distribution/OFDistributionBlocker.lua`
- `common/media/lua/shared/OFSpawnProfile.lua`
- `common/media/lua/shared/OFBlockConfig.lua`
- `common/media/lua/shared/OFBlockRules_Default.lua`
- `common/media/lua/shared/OFBlockRules_User.lua`
- `common/media/lua/shared/OFSourceCatalog.lua`
- `tools/ggs-dist-cli.js`
- `webapp/index.html`
- `webapp/styles.css`
- `webapp/app.js`