From d66db048321bdeeafb20618c208007458070e0e2 Mon Sep 17 00:00:00 2001 From: root Date: Mon, 9 Mar 2026 21:46:10 +0000 Subject: [PATCH] docs: carry capacity and dropoff priority design NPCs never drop off gathered resources due to missing continue statement in npcBrainSystem. Design adds strength-based carry capacity and fixes dropoff goal priority. Co-Authored-By: Claude Opus 4.6 --- ...026-03-09-carry-capacity-dropoff-design.md | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 docs/plans/2026-03-09-carry-capacity-dropoff-design.md diff --git a/docs/plans/2026-03-09-carry-capacity-dropoff-design.md b/docs/plans/2026-03-09-carry-capacity-dropoff-design.md new file mode 100644 index 0000000..77b0293 --- /dev/null +++ b/docs/plans/2026-03-09-carry-capacity-dropoff-design.md @@ -0,0 +1,47 @@ +# Carry Capacity & Dropoff Priority Design + +## Problem + +NPCs gather resources but never drop them off at stockpiles. They walk around carrying logs and water indefinitely, and the resources tab shows empty stockpiles. + +**Root cause:** In `npcBrainSystem.ts`, the dropoff goal preservation block (lines 122-135) is missing a `continue` statement. Unlike the pickup block (which has `continue`), the dropoff block falls through to the needs-based goal reassignment, which overwrites `'dropoff'` with `'gather'` because productivity is still low after gathering. + +## Design + +### Carry Capacity + +- Formula: `floor(getEffectiveStat(world, entity, 'strength') / 3)` +- Range: 1 (STR 3) to 6 (STR 18), average ~3 +- New helper `getCarryCapacity(world, entity)` in `statHelpers.ts` +- New helper `getTotalItemCount(inv)` in `inventoryHelpers.ts` — sums all Map values + +### npcBrainSystem Goal Priority (revised) + +``` +1. Sleep (energy < 20, or nighttime + energy < 60) +2. Eat (hunger < 30) +3. Dropoff (inventory total >= carry capacity) ← NEW +4. Gather (productivity < 40) +5. Dropoff (any items, about to wander) ← NEW +6. Wander +``` + +- At-capacity dropoff sits above gather — NPCs won't keep gathering when full +- "Cleanup" dropoff before wandering — NPCs empty inventory before idling +- Existing dropoff goal preserved with `continue` (bug fix) +- Critical needs (sleep/eat) still override dropoff + +### gatheringSystem Changes + +After gathering completes: +- If inventory total >= carry capacity → set `'dropoff'` +- Else → stay on `'gather'` (brain picks new resource target next tick) +- Remove the productivity-threshold wander check (brain system handles transitions) + +### Files Changed + +- `server/src/systems/statHelpers.ts` — add `getCarryCapacity()` +- `server/src/industry/inventoryHelpers.ts` — add `getTotalItemCount()` +- `server/src/systems/npcBrainSystem.ts` — fix dropoff `continue`, add capacity-based dropoff priority +- `server/src/systems/gatheringSystem.ts` — use carry capacity check instead of productivity check +- Tests for new helpers and updated behavior