Rijad Zuzo
73 lines
2.8 KiB
Markdown
73 lines
2.8 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 and woodpile contents and capacity.
|
|
- `SimNPC.inventory` owns carried item amounts.
|
|
- `VillageEconomy` performs deposit, withdrawal, consumption, and
|
|
definition-backed completion-cost transactions.
|
|
- `SimulationManager` coordinates action lifecycle and exposes the transaction
|
|
results to presentation.
|
|
- `village.food` and `village.wood` are synchronized aggregate views used by
|
|
the existing UI, priorities, and utility scoring. They are not second
|
|
mutation paths.
|
|
- `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`; the woodpile has stable ID
|
|
`village_woodpile`. Storage and NPC inventory are included in versioned state
|
|
and deterministic checksums. Patrol and study require one wood on completion:
|
|
the effect is applied only when that unit can be withdrawn, and selection does
|
|
not choose those actions while the woodpile is empty.
|
|
|
|
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;
|
|
- player extraction is limited to storage capacity until player inventory
|
|
exists, so overflow remains at the source;
|
|
- 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.
|