gamedev-the-steward/docs/FEATURE_ENTITIES_COMBAT_ANIMALS.md

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