Rijad Zuzo
90 lines
3.7 KiB
Markdown
90 lines
3.7 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.
|
|
|
|
Animal care extends the same ownership chain without a parallel counter:
|
|
|
|
```text
|
|
village_pantry
|
|
-> feed_animal pickup moves one food into exact caretaker inventory
|
|
-> existing carried-food prop derives from that inventory
|
|
-> delivery consumes caretaker inventory into exact named animal
|
|
```
|
|
|
|
## 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, including exact
|
|
all-or-nothing animal-care pickup and inventory removal.
|
|
- `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.
|
|
NPC animal care therefore uses the same visible prop between pantry pickup and
|
|
the claimed goat.
|
|
|
|
## 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;
|
|
- animal-care pickup succeeds only when the complete missing cost is available;
|
|
- eating succeeds only when the NPC carries one food.
|
|
|
|
If another caretaker empties the pantry first, animal-care pickup records the
|
|
definition-backed shortfall, transfers nothing, releases only the losing
|
|
caretaker's exact animal claim, and replans. A caretaker that already carries
|
|
the unit never consults pantry stock again before delivery.
|
|
|
|
## Deliberate limits
|
|
|
|
The current bounded economy has one authored pantry and one woodpile with
|
|
simple food/wood stacks. It does not yet add:
|
|
|
|
- player inventory;
|
|
- storage reservations or access capacity;
|
|
- multiple households or ownership;
|
|
- spoilage, item quality, weight, or stack definitions.
|
|
|
|
Objective event history, depletion and blocked-task facts, bounded per-NPC
|
|
knowledge, proximity witnesses, and the first social consequences now exist.
|
|
Long-run event archival, generalized denial facts, wider witness models, and
|
|
broader social interpretation remain deferred.
|
|
|
|
Those should extend the transaction boundary rather than mutate counters
|
|
directly.
|