Inital Commit

README.md

@@ -1,2 +1,84 @@
-# OpinionatedFirearms
+# Opinionated Firearms
 
+Project Zomboid B42 patch mod + tooling for managing `GaelGunStore` firearm/attachment 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
+- 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
+- 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`