# 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`