Rijad Zuzo
85 lines
4.0 KiB
Markdown
85 lines
4.0 KiB
Markdown
# Feature slice: reusable entity families
|
|
|
|
Resources, animals, enemies, items, and storage follow a common extension
|
|
pattern. A definition describes behavior; a state record owns mutable facts; a
|
|
factory/system creates or advances the instance; a presentation binding uses a
|
|
stable cue ID.
|
|
|
|
## Resources and storage
|
|
|
|
`ResourceDefinition` describes yielded item, gather action, capacity/yield,
|
|
regrowth, access policy, capability tags, and presentation cue. A placed
|
|
`ResourceNode` binds its unique ID to `ResourceStateRecord`; amount,
|
|
reservation, enabled state, risk, comfort, priority, and regrowth survive scene
|
|
unload. `LoadedResourceSpatialIndex` only accelerates loaded anchor queries.
|
|
|
|
`StorageDefinition` describes accepted items/tags, capacity, policy priority,
|
|
settlement scope, actions, and cue. `StorageNode` supplies interaction geometry;
|
|
`StorageStateRecord` owns quantities. The current authored storages are pantry,
|
|
woodpile, and apothecary.
|
|
|
|
## Animals
|
|
|
|
`AnimalDefinition` owns stable definition ID, species, feed capability,
|
|
behavior/routine profile, and presentation cue. `AnimalStateRecord` v3 stores
|
|
the mutable animal ID, definition ID, position, hunger, routine/travel target,
|
|
reservation, and feed history. `AnimalFactory` creates/restores by definition;
|
|
`AnimalCareSystem` advances needs, routines, claims, and exact feeding.
|
|
|
|
`AnimalNode` binds a loaded provider to the saved state and follows an
|
|
authoritative destination via navigation. `AnimalRoutineSite` handles private
|
|
resident shelters versus shared species context. The goat and sheep resources
|
|
prove two definitions can reuse the same grazer root without Dunja-specific
|
|
simulation branches.
|
|
|
|
## Enemies and combatants
|
|
|
|
`EnemyDefinition` carries enemy ID, behavior profile, faction, item/weapon
|
|
references, hostile flag, and cue. `CombatantFactory` owns per-prefix stable ID
|
|
allocation and rebuilds occupied IDs after restore. `CombatantStateRecord` v2
|
|
persists `enemy_definition_id`; legacy hostile kinds migrate to current raider
|
|
or wolf definitions.
|
|
|
|
`ConflictSystem` owns authoritative health, weapon readiness, factions,
|
|
hostility, raids, war motivation, damage, death, and conflict facts. It creates
|
|
combatants through the factory and exposes generic `spawn_enemy()` while keeping
|
|
compatibility wrappers for old wolf/raid callers. `HostileCombatant` is a
|
|
presentation specialization of `CreatureVisual`; it must not become the owner
|
|
of health or death authority.
|
|
|
|
The boar definition deliberately reuses `wolf_hunt` behavior. A new enemy that
|
|
needs a new decision pattern adds one bounded behavior strategy plus tests; it
|
|
does not add a switch in the manager or a duplicate combat system.
|
|
|
|
## Shared visual contract
|
|
|
|
`CreatureVisual` follows a simulation-owned target position, retargets only
|
|
when needed, rate-limits failed navigation retries, reports position/arrival,
|
|
and plays death presentation. NPC, animal, and hostile visuals use this
|
|
boundary. A visual may report local blockage, but it may not decide that
|
|
simulation travel completed or mutate combat/resource state.
|
|
|
|
## Adding an entity safely
|
|
|
|
1. Identify whether an existing definition/profile/root already expresses the
|
|
behavior.
|
|
2. Add the definition and presentation cue, then register it in a pack/catalog.
|
|
3. Add the mutable definition ID to the nested state record if it is not
|
|
already present, including a legacy migration.
|
|
4. Route creation/restoration through the factory/system and stable allocator.
|
|
5. Bind the presentation at the world boundary and test unload/reload.
|
|
6. Prove a third data-only consumer before generalizing a bespoke handler.
|
|
|
|
## Reference tests
|
|
|
|
- `tests/animal_definition_contract_test.gd`
|
|
- `tests/animal_feeding_vertical_slice_test.gd`
|
|
- `tests/animal_routine_vertical_slice_test.gd`
|
|
- `tests/animal_pair_vertical_slice_test.gd`
|
|
- `tests/unit/test_combatant_factory.gd`
|
|
- `tests/combat_patterns_test.gd`
|
|
- `tests/conflict_war_system_test.gd`
|
|
- `tests/creature_visual_path_retry_test.gd`
|
|
- `tests/resource_regrowth_test.gd`
|
|
- `tests/jajce_resource_presentation_state_test.gd`
|