Rijad Zuzo
107 lines
4.4 KiB
Markdown
107 lines
4.4 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, and completion remain separate; NPC and player
|
|
completion both use `AnimalCareSystem`'s same pantry-to-animal transaction.
|
|
`SimulationIds` also names Dunja's shelter and pasture anchors. These IDs are
|
|
saved routine vocabulary; their loaded positions 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 two proven opportunity types,
|
|
`restock_empty_pantry` and `supply_missing_wood`, 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 were extracted only after the
|
|
food and wood consumers proved those fields. Their evidence, care, resolution,
|
|
and invalidation rules remain explicit branches. Do not add a generic quest-
|
|
definition registry until real acceptance, assignment, reward, or dialogue
|
|
consumers establish a second shared contract.
|
|
|
|
## 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.
|