65 lines
2.3 KiB
Markdown
65 lines
2.3 KiB
Markdown
# The Steward — Food Storage and Transactions
|
|
|
|
## First complete food loop
|
|
|
|
```text
|
|
ResourceStateRecord (berry bush)
|
|
-> gather_food extracts actual yield
|
|
-> SimNPC inventory carries food
|
|
-> deposit_food targets village_pantry
|
|
-> StorageStateRecord receives food
|
|
-> hungry NPC selects withdraw_food
|
|
-> pantry transfers one food into NPC inventory
|
|
-> eat consumes carried food and reduces hunger
|
|
```
|
|
|
|
Food is conserved across source, carried inventory, and pantry. It leaves the
|
|
world only when consumed.
|
|
|
|
## Authority
|
|
|
|
- `StorageStateRecord` owns pantry contents and capacity.
|
|
- `SimNPC.inventory` owns carried item amounts.
|
|
- `SimulationManager` performs deposit, withdrawal, and consumption
|
|
transactions.
|
|
- `village.food` is a synchronized aggregate view used by the existing UI,
|
|
priorities, and utility scoring. It is not a second mutation path.
|
|
- `StorageNode` supplies the active-world interaction position and presentation
|
|
for deposit, withdrawal, eating, and current player pantry interaction.
|
|
|
|
The village pantry has stable ID `village_pantry`. Storage and NPC inventory
|
|
are included in versioned state and deterministic checksums.
|
|
|
|
Successful extraction, deposit, withdrawal, and consumption also append
|
|
structured economic facts. See [the economic event stream](ECONOMIC_EVENTS.md).
|
|
Active NPCs display a small food sack while their authoritative inventory
|
|
contains food; this is presentation derived from state, not a second inventory.
|
|
|
|
## Failure behavior
|
|
|
|
Transactions apply the amount actually available:
|
|
|
|
- extraction cannot exceed the source;
|
|
- deposit cannot exceed storage capacity;
|
|
- withdrawal cannot exceed pantry contents;
|
|
- eating succeeds only when the NPC carries one food.
|
|
|
|
If another NPC empties the pantry first, withdrawal returns zero and the NPC
|
|
replans on its next idle tick.
|
|
|
|
## Deliberate limits
|
|
|
|
This slice contains one authored pantry and one carried item type. It does not
|
|
yet add:
|
|
|
|
- player inventory;
|
|
- storage reservations or access capacity;
|
|
- multiple households or ownership;
|
|
- spoilage, item quality, weight, or stack definitions.
|
|
|
|
Economic transfer events exist, but event retention, denial/depletion facts,
|
|
witnesses, and social interpretation are deliberately deferred.
|
|
|
|
Those should extend the transaction boundary rather than mutate counters
|
|
directly.
|