docs: mark simulation definitions phase complete

2026-07-05 13:35:42 +02:00
parent f816f3976a
commit 81df7b5939
8 changed files with 118 additions and 25 deletions
@@ -0,0 +1,74 @@
+# The Steward — Simulation Definitions
+
+## Purpose
+
+Stable IDs and immutable definitions now form the vocabulary shared by
+simulation state, systems, world adapters, scenes, tests, and future save
+migrations.
+
+`SimulationIds` is the canonical source for code-facing `StringName` IDs.
+`ActionDefinition` and `ProfessionDefinition` are editor-readable custom
+resources. `SimulationDefinitions` loads, resolves, and validates the complete
+prototype set.
+
+## Current action contract
+
+Each executable action definition contains:
+
+- stable `action_id`;
+- display name;
+- default duration;
+- optional preferred profession ID;
+- 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.
+
+SimNPC reads default duration and preferred-profession metadata from these
+definitions. WorldViewManager reads target type and resource-action metadata
+instead of maintaining a separate gather-action map.
+
+## Current profession contract
+
+Each profession definition contains a stable `profession_id` and display name.
+The current professions are farmer, woodcutter, guard, scholar, and wanderer.
+
+NPC generation chooses from the registry's stable IDs. NPC state stores and
+restores those IDs as `StringName`, and rejects records that reference an
+unknown profession or executable action.
+
+## Validation
+
+The registry rejects:
+
+- missing or duplicate IDs;
+- empty display names;
+- non-positive action durations;
+- invalid target types;
+- resource actions without a resource-action ID;
+- references to unknown professions or resource actions;
+- definition resources that fail to load.
+
+`tests/simulation_definitions_test.gd` verifies registry integrity,
+definition-backed behavior, unknown-ID rejection, and serialization
+round-tripping.
+
+## Deliberate boundary
+
+Definitions currently own identity and the static metadata already proven by
+the prototype. They do not yet own:
+
+- utility thresholds and consideration curves;
+- preconditions or costs;
+- completion effects;
+- interruption and failure policy;
+- reservation strategy;
+- target resolution implementation;
+- presentation hints beyond target type.
+
+Those concerns move during the next architecture phase, which separates action
+selection, execution, target resolution, and visual travel. Keeping this first
+definition contract small avoids encoding the existing manager's mixed
+responsibilities as permanent data architecture.