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 <noreply@anthropic.com>
2026-03-09 21:46:10 +00:00
parent 219f02d7d6
commit d66db04832
1 changed files with 47 additions and 0 deletions
@@ -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