From ebf70a711ad08e31bfb22e811a445472193c5993 Mon Sep 17 00:00:00 2001 From: Rijad Zuzo Date: Sun, 5 Jul 2026 17:57:33 +0200 Subject: [PATCH] docs: document food storage transaction loop --- docs/BUILD_IN_PUBLIC_PLAN.md | 2 +- docs/FOOD_STORAGE_ARCHITECTURE.md | 58 +++++++++++++++++++++++++++++++ docs/LEARNING_ROADMAP.md | 17 ++++++--- docs/PROJECT_CONTEXT.md | 13 ++++--- docs/README.md | 1 + docs/RESOURCE_NODE_MIGRATION.md | 4 +++ docs/SIMULATION_DEFINITIONS.md | 6 ++-- docs/SIMULATION_STATE_SCHEMA.md | 5 +++ 8 files changed, 92 insertions(+), 14 deletions(-) create mode 100644 docs/FOOD_STORAGE_ARCHITECTURE.md diff --git a/docs/BUILD_IN_PUBLIC_PLAN.md b/docs/BUILD_IN_PUBLIC_PLAN.md index 02558ce..7dfa229 100644 --- a/docs/BUILD_IN_PUBLIC_PLAN.md +++ b/docs/BUILD_IN_PUBLIC_PLAN.md @@ -95,7 +95,7 @@ Main │ │ ├── BerryBush instances │ │ └── Tree instances │ ├── LegacyActivityMarkers temporary non-resource activities -│ │ ├── FoodZone +│ │ ├── PantryMarker │ │ ├── GuardZone │ │ ├── StudyZone │ │ └── RestZone diff --git a/docs/FOOD_STORAGE_ARCHITECTURE.md b/docs/FOOD_STORAGE_ARCHITECTURE.md new file mode 100644 index 0000000..d66511f --- /dev/null +++ b/docs/FOOD_STORAGE_ARCHITECTURE.md @@ -0,0 +1,58 @@ +# 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. +- `PantryMarker` supplies the active-world interaction position 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. + +## 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 pantry and one carried item type. It does not yet add: + +- visible carried props; +- player inventory; +- storage reservations or access capacity; +- multiple households or ownership; +- spoilage, item quality, weight, or stack definitions; +- structured transaction/history events; +- an authored StorageNode scene beyond the current pantry marker. + +Those should extend the transaction boundary rather than mutate counters +directly. diff --git a/docs/LEARNING_ROADMAP.md b/docs/LEARNING_ROADMAP.md index d328dd9..70aef51 100644 --- a/docs/LEARNING_ROADMAP.md +++ b/docs/LEARNING_ROADMAP.md @@ -633,14 +633,21 @@ Completed foundations: The practical next sequence is: -1. Build location-based food storage, inventory, and transactions. -2. Emit structured economic events while making one NPC visibly gather, carry, +Completed after the architecture gate: + +- location-based pantry state, NPC-carried food, and explicit + deposit/withdraw/consume transactions; +- a headless conservation scenario covering the complete food loop. + +The practical next sequence is: + +1. Emit structured economic events while making one NPC visibly gather, carry, store, retrieve, and eat food. -3. Add save-slot persistence and explicit schema migrations before schedules +2. Add save-slot persistence and explicit schema migrations before schedules or social state expand. -4. Resume Terrain3D sculpting, runtime integration, and the simulation-garden +3. Resume Terrain3D sculpting, runtime integration, and the simulation-garden beauty pass. -5. Add stylized character and profession readability plus the reason +4. Add stylized character and profession readability plus the reason inspector. This order strengthens the simulation while regularly producing visible diff --git a/docs/PROJECT_CONTEXT.md b/docs/PROJECT_CONTEXT.md index 69ca223..4a3ff65 100644 --- a/docs/PROJECT_CONTEXT.md +++ b/docs/PROJECT_CONTEXT.md @@ -468,6 +468,7 @@ NpcVisual navigates through the active world │ ├── action_system_boundaries_test.gd │ ├── deterministic_simulation_test.gd │ ├── flat_map_baseline_test.gd +│ ├── food_storage_loop_test.gd │ ├── jajce_world_scaffold_test.gd │ ├── npc_visual_lifecycle_test.gd │ ├── resource_node_player_parity_test.gd @@ -511,7 +512,8 @@ These are expected prototype constraints, not necessarily isolated bugs: continuation checks, player-parity/resource-contention, flat-map, and Jajce scaffold scenarios; broader gameplay coverage is still missing. - Resources are global floating-point counters rather than items in locations - and inventories. + and inventories, except food, which now moves through sources, NPC inventory, + and the village pantry. - NPCs do not have homes, schedules, possessions, memories, relationships, goals, or social knowledge. - NPC reasoning is logged but not presented through an in-game inspector. @@ -735,10 +737,11 @@ architecture gate are complete: - authoritative active position and persisted travel destinations; - checksum-invariant NPC visual unload/reload with reservation preservation. -The next systems milestone is a complete location-based food loop: storage, -inventory, carrying, depositing, withdrawing, and eating through transactions. -Bounded Terrain3D look-development can resume, but runtime terrain integration -should remain coordinated with that visible systems slice. +The location-based food loop is now complete at simulation level: gathering +creates carried food, depositing fills the pantry, withdrawal retrieves one +unit, and eating consumes it. The next systems milestone is structured +transaction events and visible carrying/readability. Bounded Terrain3D +look-development can resume alongside that presentation work. The coherent visual slice can then aim for: diff --git a/docs/README.md b/docs/README.md index e8ccff5..f4d5609 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,6 +16,7 @@ sources of truth. migration plan. Phases 1–4 are complete; its Phase 5 hands world placement to the visual-slice plan. 5. [`ACTION_SYSTEM_ARCHITECTURE.md`](ACTION_SYSTEM_ARCHITECTURE.md), + [`FOOD_STORAGE_ARCHITECTURE.md`](FOOD_STORAGE_ARCHITECTURE.md), [`SIMULATION_DEFINITIONS.md`](SIMULATION_DEFINITIONS.md), and [`SIMULATION_STATE_SCHEMA.md`](SIMULATION_STATE_SCHEMA.md) document the current data contracts. diff --git a/docs/RESOURCE_NODE_MIGRATION.md b/docs/RESOURCE_NODE_MIGRATION.md index c9fc747..4b02c7e 100644 --- a/docs/RESOURCE_NODE_MIGRATION.md +++ b/docs/RESOURCE_NODE_MIGRATION.md @@ -527,6 +527,10 @@ nodes have been deleted from `main.tscn`. The surviving nodes live under mapping still exists for eating, rest, study, and patrol, so this phase is not complete. +The former `FoodZone` is now `PantryMarker` backed by simulation-owned +`StorageStateRecord` state and explicit deposit/withdraw transactions. A +dedicated authored StorageNode presentation is still pending. + **Exit:** temporary activity markers and task-to-marker mapping are deleted, not merely unused. diff --git a/docs/SIMULATION_DEFINITIONS.md b/docs/SIMULATION_DEFINITIONS.md index b752c80..b6ada51 100644 --- a/docs/SIMULATION_DEFINITIONS.md +++ b/docs/SIMULATION_DEFINITIONS.md @@ -22,9 +22,9 @@ Each executable action definition contains: - target type: resource, activity, or free movement; - resource action ID when the action targets a ResourceNode. -The current actions are gather food, gather wood, patrol, study, eat, rest, and -wander. Idle and dead are stable state sentinels, not executable action -definitions. +The current actions are gather food, gather wood, deposit food, withdraw food, +patrol, study, eat, rest, and wander. Idle and dead are stable state sentinels, +not executable action definitions. SimNPC reads default duration and preferred-profession metadata from these definitions. WorldViewManager reads target type and resource-action metadata diff --git a/docs/SIMULATION_STATE_SCHEMA.md b/docs/SIMULATION_STATE_SCHEMA.md index e58978b..1096838 100644 --- a/docs/SIMULATION_STATE_SCHEMA.md +++ b/docs/SIMULATION_STATE_SCHEMA.md @@ -57,6 +57,11 @@ active. Nested v1 NPC records migrate explicitly with no invented active destination. This allows a reloaded visual to resume travel without changing target selection or deterministic RNG state. +NPCStateRecord v3 adds carried inventory. SimulationStateRecord v2 adds +StorageStateRecord entries; world-schema v1 migrates legacy village food into +the stable `village_pantry` record. Parsed storage values are canonicalized so +save/restore continuation retains byte-stable checksums. + ## Resource authority `SimulationManager` owns `ResourceStateRecord` instances independently of the