docs: add current developer feature index

2026-08-13 00:26:55 +02:00
parent 149e043f86
commit 9872b986b6
21 changed files with 1296 additions and 45 deletions
@@ -0,0 +1,84 @@
+# 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`