gamedev-the-steward/docs/SIMULATION_DEFINITIONS.md

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.