Rijad Zuzo
121 lines
5.3 KiB
Markdown
121 lines
5.3 KiB
Markdown
# 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.
|
|
|
|
## 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.
|