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, animal, or free movement;
- resource action ID when the action targets a ResourceNode;
- optional completion-cost resource ID and amount.

The current actions are gather food, gather wood, feed animal, deposit food,
deposit wood, withdraw food, patrol, study, eat, rest, sleep, 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. ActionSelectionSystem and
SimulationManager share the same completion-cost metadata, so patrol and study
both require one stored wood without duplicating that rule.

`feed_animal` is the first animal-targeted action. Its definition prefers the
farmer profession and declares an exact one-food completion cost. Selection,
animal target reservation, supply pickup, and completion remain separate. NPC
care pays that definition cost from carried inventory after a real pantry
pickup; player care pays it directly from the pantry while player inventory is
deferred. Both paths use `AnimalCareSystem` and mutate only the exact target.
`SimulationIds` names Dunja and Zora, their private shelter anchors, and the
shared pasture anchor. These IDs are saved routine vocabulary; their loaded
positions and private/shared ownership come from `AnimalRoutineSite` rather
than entering an action definition or resource registry.

## Current profession contract

Each profession definition contains a stable `profession_id`, display name,
body color, and prop color. 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.

## Opportunity vocabulary

`SimulationIds` defines the four proven opportunity types,
`restock_empty_pantry`, `supply_missing_wood`, `feed_weak_villager`, and
`repair_home_roof`, plus the stable `open`, `resolved`, and `invalidated`
statuses. Invalidation reasons currently distinguish `interested_died` from
`evidence_stale`. These are serialized vocabulary, not editor-authored quest
definitions. Dynamic trigger, interested NPC, storage/resource goal, progress,
exact resolution-event identity, and close reason belong to
`OpportunityStateRecord` and `VillageOpportunitySystem`.

The shared record and lifecycle collaborator was extracted only after the
food and wood consumers proved those fields. Their evidence, care, resolution,
and invalidation rules remain explicit branches. `feed_weak_villager` opens on
a `villager_weak` fact when a starving low-energy villager cannot eat and
resolves only when that same villager actually consumes food; `repair_home_roof`
opens on a `home_damaged` fact when a villager sleeps through low safety and
resolves through the real wood-deposit path. Do not add a generic quest-
definition registry until real acceptance, assignment, reward, or dialogue
consumers establish a second shared contract.

## Player actor vocabulary

`SimulationIds.PLAYER_ACTOR_ID` (`-1`) is the stable event actor for
player-performed actions, and `SimulationIds.PLAYER_INVENTORY_ID` names the
carried-inventory holder in economic events. Player-performed pantry food
supply is witnessed by nearby villagers and can raise their directed trust
toward the player, with the player as a relationship subject.

## Item and weapon vocabulary

`ItemDefinition` is the editor-readable resource contract for items, and
`SimulationItems` is the current registry. Weapons carry `damage`, `reach`,
and `attack_cooldown` and fill the `hand` equip slot, so the same contract can
later host non-weapon items (food sacks, tools, armour) in a full inventory.
The current weapons are `item_sword` (the player's equipped blade) and
`item_claw` (wolf bites and unarmed defenders). NPC guards are equipped with
swords; other villagers fight with claws, which feeds the village-defense
derivation.

## Conflict vocabulary

`CombatantStateRecord` and `FactionStateRecord` use stable IDs. Combatant kinds
are `npc`, `raider`, `wolf`, and `player`; NPC combatants reference their
`SimNPC` by stable ID. Factions are `faction_village` and `faction_tribe`, with
`neutral`/`hostile` stances and `none`/`planned`/`raiding`/`aborted` war plans.
Combat, raid, and war narrative facts use the stable event types
`combatant_hurt`, `combatant_killed`, `raid_started`, `war_resolved`,
`war_aborted`, and `wolf_hunt`.

## 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;
- incomplete, non-positive, or unknown completion-cost resources;
- 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, including the patrol/study completion-cost contract. They do not
yet own:

- utility thresholds and consideration curves;
- general preconditions beyond stored-resource completion costs;
- completion effects;
- interruption and failure policy;
- reservation strategy;
- detailed target-selection policy beyond current resource/activity/free
  metadata;
- richer presentation hints beyond the current profession palette.

Selection, execution, target resolution, and visual travel are now separate
responsibilities. The remaining concerns should move into definitions only
when the action-system implementations prove a stable, reusable contract.