From 6de6d25bf5868a88d17a9eeb4bb50e0fa23aacd4 Mon Sep 17 00:00:00 2001 From: Rijad Zuzo Date: Tue, 11 Aug 2026 20:51:57 +0200 Subject: [PATCH] docs: record combat, wolves, factions, and tribe war systems --- docs/ARCHITECTURE_OVERVIEW.md | 6 ++++++ docs/ECONOMIC_EVENTS.md | 13 +++++++++++++ docs/LEARNING_ROADMAP.md | 15 +++++++++++++++ docs/PROJECT_CONTEXT.md | 21 ++++++++++++++++++--- docs/SIMULATION_DEFINITIONS.md | 21 +++++++++++++++++++++ docs/SIMULATION_STATE_SCHEMA.md | 21 ++++++++++++++++++--- 6 files changed, 91 insertions(+), 6 deletions(-) diff --git a/docs/ARCHITECTURE_OVERVIEW.md b/docs/ARCHITECTURE_OVERVIEW.md index 512a61f..69b1f5b 100644 --- a/docs/ARCHITECTURE_OVERVIEW.md +++ b/docs/ARCHITECTURE_OVERVIEW.md @@ -45,6 +45,12 @@ would otherwise obscure that lifecycle: `PlayerStateRecord` (hunger, energy, carried inventory), deterministic needs advancement, and the player's carry/deposit/eat transactions through the same storage and event contract as NPCs; +- `simulation/conflict/ConflictSystem.gd` owns combatants (health, weapons, + factions, hostility), village/tribe faction records, wolf hostility, the + tribe war motivation decision (desire + victory confidence), raid spawning, + deterministic battle resolution, and war consequences. It emits combat and + war narrative facts and spawn/death signals that presentation binds to + `HostileCombatant` visuals; - `simulation/events/SimulationEventLog.gd` owns ordered event identity, history queries, and rate calculations; - `simulation/knowledge/EventKnowledgeSystem.gd` owns per-NPC references to diff --git a/docs/ECONOMIC_EVENTS.md b/docs/ECONOMIC_EVENTS.md index 03c371d..9797dee 100644 --- a/docs/ECONOMIC_EVENTS.md +++ b/docs/ECONOMIC_EVENTS.md @@ -13,6 +13,12 @@ item_consumed animal_fed villager_weak home_damaged +combatant_hurt +combatant_killed +raid_started +war_resolved +war_aborted +wolf_hunt ``` Each record contains a monotonically increasing event ID, event type, @@ -42,6 +48,13 @@ marks a starving, low-energy villager who cannot feed themselves from an empty pantry, and `home_damaged` marks a villager who slept through critically low safety. Both are knowable by their actor and nearby witnesses. +Conflict facts are narrative events emitted by `ConflictSystem`: `combatant_hurt` +and `combatant_killed` carry the combatant ID as the source and the actor's NPC +ID (or a hostile sentinel) as the actor; `raid_started`, `war_resolved`, and +`war_aborted` narrate the tribe conflict lifecycle; `wolf_hunt` marks a wolf +attack. These are objective history but intentionally not knowable facts, so +they never gate NPC memory or relationships directly. + Events are immutable facts about completed transfers. They do not perform the transaction and are not replayed to reconstruct current state. Resource, inventory, and storage records remain authoritative. diff --git a/docs/LEARNING_ROADMAP.md b/docs/LEARNING_ROADMAP.md index 1159d4c..a25f0f7 100644 --- a/docs/LEARNING_ROADMAP.md +++ b/docs/LEARNING_ROADMAP.md @@ -998,6 +998,21 @@ trust toward the player. The opportunity family grew to four types cold season halves gather yields and pauses regrowth to create recurring scarcity. +The first conflict systems slice is also complete. `ItemDefinition` + +`SimulationItems` establish the extensible weapon/inventory contract. +`ConflictSystem` owns deterministic combatant records (health, weapons, +factions, hostility), the village and hill-tribe faction records, wolf hunger +attacks, the tribe war-motivation decision (tribe hunger + village surplus -> +desire; tribe strength vs NPC-derived village defence -> victory confidence; +watch one interval, then raid, plan, or abort), raid spawning, battle +resolution, and war consequences. Strong villagers automatically defend during +a raid. The player fights with an equipped sword and dash through a +`PlayerCombatController`, and `CombatPresentation` binds hostile raider/wolf +visuals to the authoritative combatants. Headless tests cover combat +determinism, wolf attacks, war motivation (raid only when confident, abort when +the village is strong), raid-to-resolution chains, player kills, and +save/restore. + Recently completed: - `Jajce Villager Field Note 12`: a separate player-facing note selects the diff --git a/docs/PROJECT_CONTEXT.md b/docs/PROJECT_CONTEXT.md index 55b675b..778be22 100644 --- a/docs/PROJECT_CONTEXT.md +++ b/docs/PROJECT_CONTEXT.md @@ -242,6 +242,14 @@ plugin content, not game architecture. - The world runs a deterministic four-day seasonal cycle: the cold day halves gather yields and pauses berry regrowth, surfacing a recurring shortage the player and villagers can address. +- Combat is playable: the player swings an equipped sword (left click) and + dashes (Shift) with cooldowns; hits land against hostile raiders and wolves + through a deterministic simulation `ConflictSystem`. Wolves hunt hungry + nearby villagers, and the hill tribe raids the village when it is short of + food while the village holds plenty — unless the tribe reads the village's + strength (strong NPCs who can swap to defence) and judges victory unlikely, + in which case it plans or aborts. Strong villagers automatically defend + during a raid. - `Escape` releases captured mouse input. ### Village simulation @@ -640,9 +648,16 @@ These are expected prototype constraints, not necessarily isolated bugs: gathering use `ResourceNode` instances with no fallback, food transfer uses the typed pantry `StorageNode`, and patrol/study/rest use `ActivitySite`. - Current NPC, village, resource, storage, animal, event, knowledge, - relationship, opportunity, clock, RNG, and player-citizen state serialize - through world schema v13. F5/F9 provide one validated local quicksave; a save - menu, metadata, and player-transform persistence remain deferred. + relationship, opportunity, clock, RNG, player-citizen, combatant, and + faction state serialize through world schema v14. F5/F9 provide one validated + local quicksave; a save menu, metadata, and player-transform persistence + remain deferred. +- Combatants and factions are deterministic simulation records. NPC defenders, + tribe raiders, and wolves carry health and equipped weapons; the village and + hill-tribe factions drive an emergent war cycle gated by tribe hunger, village + food surplus, and a victory-confidence check against the NPC-derived village + defence. Combatant positions and faction food are quantized to binary-exact + steps so JSON round-trips preserve continuation checksums. - The player is a first-class citizen with persisted hunger, energy, and carried inventory. Gathering moves yield into carried inventory, depositing restocks the typed pantry or woodpile, and eating eases hunger from carried diff --git a/docs/SIMULATION_DEFINITIONS.md b/docs/SIMULATION_DEFINITIONS.md index 0853a58..55161a8 100644 --- a/docs/SIMULATION_DEFINITIONS.md +++ b/docs/SIMULATION_DEFINITIONS.md @@ -83,6 +83,27 @@ carried-inventory holder in economic events. Player-performed pantry food supply is witnessed by nearby villagers and can raise their directed trust toward the player, with the player as a relationship subject. +## Item and weapon vocabulary + +`ItemDefinition` is the editor-readable resource contract for items, and +`SimulationItems` is the current registry. Weapons carry `damage`, `reach`, +and `attack_cooldown` and fill the `hand` equip slot, so the same contract can +later host non-weapon items (food sacks, tools, armour) in a full inventory. +The current weapons are `item_sword` (the player's equipped blade) and +`item_claw` (wolf bites and unarmed defenders). NPC guards are equipped with +swords; other villagers fight with claws, which feeds the village-defense +derivation. + +## Conflict vocabulary + +`CombatantStateRecord` and `FactionStateRecord` use stable IDs. Combatant kinds +are `npc`, `raider`, `wolf`, and `player`; NPC combatants reference their +`SimNPC` by stable ID. Factions are `faction_village` and `faction_tribe`, with +`neutral`/`hostile` stances and `none`/`planned`/`raiding`/`aborted` war plans. +Combat, raid, and war narrative facts use the stable event types +`combatant_hurt`, `combatant_killed`, `raid_started`, `war_resolved`, +`war_aborted`, and `wolf_hunt`. + ## Validation The registry rejects: diff --git a/docs/SIMULATION_STATE_SCHEMA.md b/docs/SIMULATION_STATE_SCHEMA.md index caaa624..3b99293 100644 --- a/docs/SIMULATION_STATE_SCHEMA.md +++ b/docs/SIMULATION_STATE_SCHEMA.md @@ -3,7 +3,7 @@ ## Current contract `SimulationStateRecord` is the versioned JSON boundary for the current -simulation. The current world schema is v13 and captures: +simulation. The current world schema is v14 and captures: - simulation seed, tick interval, tick count, clock remainder, and elapsed clock ticks; @@ -28,14 +28,18 @@ simulation. The current world schema is v13 and captures: deterministic invalidation reason and close tick; - a player record holding the player-citizen's hunger, energy, and carried inventory. The player's world position remains presentation-owned and is - intentionally not serialized. + intentionally not serialized; +- combatant records (health, weapon, faction, position, hostility) for NPC + defenders and standalone raiders/wolves; +- faction records (food, warriors, aggression, morale, stance, war plan) for + the village and the hill tribe. The top-level identity is: ```json { "schema": "the_steward.simulation", - "schema_version": 13 + "schema_version": 14 } ``` @@ -233,6 +237,17 @@ stable. Resource records also migrate to v4, adding `max_amount` and `regrow_rate`; legacy v3 resources keep their current amount as the cap and gain no regrowth. +SimulationStateRecord v14 adds the top-level `combatants` and `factions` +arrays. `CombatantStateRecord` v1 tracks health, equipped weapon, faction, +hostile flag, and position for NPC defenders, tribe raiders, and wolves. +`FactionStateRecord` v1 tracks food, warriors, aggression, morale, stance, and +the tribe's war plan with its confidence. World schemas v13 and earlier migrate +to empty combatant lists plus default village/tribe factions; the manager +registers living NPC combatants on restore. Combatant positions are quantized +to a binary-exact grid and faction food to a binary-exact step so that +arbitrary world floats round-trip through JSON without breaking deterministic +continuation checksums. + Current-schema parsing requires unique animal IDs that do not collide with resource or storage IDs. An animal reservation must belong to an existing NPC whose active feed task targets that exact animal. Every `animal_fed` event