Implement survival mechanics in the god simulator

- Added survival loop in `survival.py` to manage hunger, resources, and beast interactions.
- Integrated survival mechanics into the world tick process in `tick.py`, ensuring survival actions are prioritized.
- Enhanced NPC spawning in `spawning.py` to include resource nodes and beasts based on survival configuration.
- Created unit tests in `test_survival_loop.py` to validate survival mechanics, including hunger growth, beast targeting, and resource gathering.
- Ensured that invalid actions do not disrupt the simulation flow.

config/game.llm.local.json

@@ -3,7 +3,8 @@
     "width": 80,
     "depth": 80,
     "terrain": "plain_green",
-    "seed": 42
+    "seed": 42,
+    "survival": true
   },
   "npcs": {
     "count": 10

config/game.local.json

@@ -3,7 +3,8 @@
     "width": 80,
     "depth": 80,
     "terrain": "plain_green",
-    "seed": 42
+    "seed": 42,
+    "survival": true
   },
   "npcs": {
     "count": 10

config/game.modal.a10.local.json

@@ -3,7 +3,8 @@
     "width": 80,
     "depth": 80,
     "terrain": "plain_green",
-    "seed": 42
+    "seed": 42,
+    "survival": true
   },
   "npcs": {
     "count": 10

config/game.modal.b200.local.json

@@ -3,7 +3,8 @@
     "width": 80,
     "depth": 80,
     "terrain": "plain_green",
-    "seed": 42
+    "seed": 42,
+    "survival": true
   },
   "npcs": {
     "count": 10

config/game.modal.local.json

@@ -3,7 +3,8 @@
     "width": 80,
     "depth": 80,
     "terrain": "plain_green",
-    "seed": 42
+    "seed": 42,
+    "survival": true
   },
   "npcs": {
     "count": 10

config/game.modal.t4.local.json

@@ -3,7 +3,8 @@
     "width": 80,
     "depth": 80,
     "terrain": "plain_green",
-    "seed": 42
+    "seed": 42,
+    "survival": true
   },
   "npcs": {
     "count": 10

frontend/src/components/AgentPanel.tsx

@@ -24,6 +24,7 @@ function AgentDetails({ entity }: { entity: EntitySnapshot }) {
   return (
     <>
       <AgentReadout entity={entity} />
+      <SurvivalReadout entity={entity} />
       {entity.state.god_directive ? (
         <div className="directiveBanner">
           <span>Directive</span>
@@ -35,6 +36,30 @@ function AgentDetails({ entity }: { entity: EntitySnapshot }) {
   );
 }
 
+function SurvivalReadout({ entity }: { entity: EntitySnapshot }) {
+  const { hunger, fear, goal, inventory } = entity.state;
+  if (hunger === undefined && fear === undefined && goal === undefined && !inventory) {
+    return null;
+  }
+
+  const inventoryLabel = inventory
+    ? `food ${inventory.food} · herbs ${inventory.herbs} · wood ${inventory.wood} · wpn ${inventory.weapon}`
+    : "—";
+
+  return (
+    <div className="agentReadout">
+      {hunger !== undefined ? (
+        <TooltipLabel className="readoutCell" value={`Hunger ${hunger.toFixed(0)}`} />
+      ) : null}
+      {fear !== undefined ? (
+        <TooltipLabel className="readoutCell" value={`Fear ${fear.toFixed(0)}`} />
+      ) : null}
+      {goal ? <TooltipLabel className="readoutCell" value={goal} /> : null}
+      <TooltipLabel className="readoutCell" value={inventoryLabel} />
+    </div>
+  );
+}
+
 function AgentReadout({ entity }: { entity: EntitySnapshot }) {
   const selectedHealth = `${entity.state.health} / ${entity.state.max_health} HP`;
   const selectedAttackDamage = `DMG ${entity.state.attack_damage}`;

frontend/src/types.ts

@@ -17,6 +17,13 @@ export type TerrainSnapshot = {
   };
 };
 
+export type InventorySnapshot = {
+  food: number;
+  herbs: number;
+  wood: number;
+  weapon: number;
+};
+
 export type EntitySnapshot = {
   id: string;
   kind: "npc";
@@ -31,6 +38,10 @@ export type EntitySnapshot = {
     personality: string;
     god_directive: string | null;
     is_alive: boolean;
+    hunger?: number;
+    fear?: number;
+    goal?: string;
+    inventory?: InventorySnapshot;
     memory_count: number;
     memory_summary: string | null;
     memories: MemorySnapshot[];
@@ -48,6 +59,23 @@ export type MemorySnapshot = {
   text: string;
 };
 
+export type ResourceNodeSnapshot = {
+  id: string;
+  type: "food" | "herbs" | "wood" | "weapon" | string;
+  position: Vec3;
+  amount: number;
+  max_amount?: number;
+};
+
+export type BeastSnapshot = {
+  id: string;
+  position: Vec3;
+  health: number;
+  max_health: number;
+  state: "hunting" | "attacking" | "retreating" | "dead" | string;
+  target_npc_id: string | null;
+};
+
 export type WorldSnapshot = {
   schema_version: 1;
   tick: number;
@@ -59,6 +87,8 @@ export type WorldSnapshot = {
   };
   terrain: TerrainSnapshot;
   entities: EntitySnapshot[];
+  resource_nodes?: ResourceNodeSnapshot[];
+  beasts?: BeastSnapshot[];
 };
 
 export type ModelStatusSnapshot = {

src/god_simulator/config.py

@@ -16,6 +16,7 @@ class WorldConfig:
     depth: int
     terrain: TerrainKind
     seed: int
+    survival: bool = False
 
 
 @dataclass(frozen=True, slots=True)
@@ -89,6 +90,7 @@ def parse_game_config(raw: dict[str, Any]) -> GameConfig:
             depth=_required_positive_int(world, "depth"),
             terrain=terrain,
             seed=_required_int(world, "seed"),
+            survival=_optional_bool(world, "survival", default=False),
         ),
         npcs=NpcConfig(count=_required_non_negative_int(npcs, "count")),
         simulation=SimulationConfig(tick_ms=_required_positive_int(simulation, "tick_ms")),

src/god_simulator/domain.py

@@ -84,6 +84,35 @@ class Npc:
     emotions: CitizenEmotions = field(default_factory=CitizenEmotions)
     current_goal: CitizenGoal | None = None
     mode: CitizenMode = "routine"
+    # Survival core-loop state (deterministic, engine-owned).
+    hunger: float = 25.0
+    fear: float = 0.0
+    survival_goal: str = "routine_life"
+    inventory_food: int = 0
+    inventory_herbs: int = 0
+    inventory_wood: int = 0
+    inventory_weapon: int = 0
+
+
+@dataclass(slots=True)
+class ResourceNode:
+    id: str
+    resource_type: str  # "food" | "herbs" | "wood" | "weapon"
+    position: Vec3
+    amount: int
+    max_amount: int = 0  # regrowth cap; 0 means "no regrowth" (set to amount at spawn)
+
+
+@dataclass(slots=True)
+class Beast:
+    id: str
+    position: Vec3
+    health: float = 100.0
+    damage: float = 25.0
+    attack_range: float = 1.5  # in tiles (one tile == one terrain block)
+    speed: float = 1.0  # in tiles per tick
+    target_npc_id: str | None = None
+    state: str = "hunting"  # hunting | attacking | retreating | dead
 
 
 @dataclass(slots=True)
@@ -102,6 +131,8 @@ class WorldState:
     npcs: list[Npc]
     last_tick_source: str = "initial"
     last_action_debug: list[dict[str, Any]] = field(default_factory=list)
+    resource_nodes: list[ResourceNode] = field(default_factory=list)
+    beasts: list[Beast] = field(default_factory=list)
 
     def to_dict(self) -> dict[str, Any]:
         return asdict(self)

src/god_simulator/rendering/claw3d_contract.py

@@ -51,6 +51,15 @@ def to_claw3d_snapshot(
                     "personality": npc.personality,
                     "god_directive": npc.god_directive,
                     "is_alive": is_alive(npc),
+                    "hunger": round(npc.hunger, 1),
+                    "fear": round(npc.fear, 1),
+                    "goal": npc.survival_goal,
+                    "inventory": {
+                        "food": npc.inventory_food,
+                        "herbs": npc.inventory_herbs,
+                        "wood": npc.inventory_wood,
+                        "weapon": npc.inventory_weapon,
+                    },
                     "memory_count": len(npc.memory),
                     "memory_summary": npc.memory_summary,
                     "memories": [
@@ -70,4 +79,33 @@ def to_claw3d_snapshot(
             }
             for npc in world.npcs
         ],
+        "resource_nodes": [
+            {
+                "id": node.id,
+                "type": node.resource_type,
+                "position": {
+                    "x": node.position.x,
+                    "y": node.position.y,
+                    "z": node.position.z,
+                },
+                "amount": node.amount,
+                "max_amount": node.max_amount,
+            }
+            for node in world.resource_nodes
+        ],
+        "beasts": [
+            {
+                "id": beast.id,
+                "position": {
+                    "x": beast.position.x,
+                    "y": beast.position.y,
+                    "z": beast.position.z,
+                },
+                "health": round(beast.health, 1),
+                "max_health": 100,
+                "state": beast.state,
+                "target_npc_id": beast.target_npc_id,
+            }
+            for beast in world.beasts
+        ],
     }

src/god_simulator/simulation/connectors/base.py

@@ -18,7 +18,18 @@ SemanticActionKind: TypeAlias = Literal[
     "move_to_target",
     "attack_back",
 ]
-ActionKind: TypeAlias = EngineActionKind | SemanticActionKind
+SurvivalActionKind: TypeAlias = Literal[
+    "gather",
+    "eat",
+    "heal",
+    "move_to_resource",
+    "move_to",
+    "trade",
+    "steal",
+    "find_food",
+    "find_herbs",
+]
+ActionKind: TypeAlias = EngineActionKind | SemanticActionKind | SurvivalActionKind
 
 
 @dataclass(frozen=True, slots=True)

src/god_simulator/simulation/connectors/deterministic.py

@@ -5,12 +5,18 @@ import random
 from god_simulator.domain import Vec3, WorldState
 from god_simulator.simulation.connectors.base import NpcDirective, TickPlan
 from god_simulator.simulation.mechanics import BLOCK_SIZE, is_alive
+from god_simulator.simulation.survival import propose_survival_tick
 
 
 class DeterministicWorldSimulator:
     name = "deterministic"
 
     def propose_tick(self, world: WorldState, next_tick: int) -> TickPlan:
+        # Survival worlds get the deterministic survival planner so the core
+        # loop (flee/fight/gather/eat/heal) is visible without any LLM.
+        if world.beasts or world.resource_nodes:
+            return propose_survival_tick(world, next_tick)
+
         half_width = world.terrain.width / 2
         half_depth = world.terrain.depth / 2
         directives: list[NpcDirective] = []

src/god_simulator/simulation/connectors/openai_compatible.py

@@ -29,9 +29,17 @@ from god_simulator.simulation.mechanics import (
     distance_between,
     has_hostile_intent,
     is_alive,
+    vec_distance,
 )
 from god_simulator.simulation.memory import recent_meaningful_memories
 from god_simulator.simulation.perception import CitizenPerception
+from god_simulator.simulation.survival import (
+    GOAL_ACTIONS,
+    is_survival_world,
+    nearest_beast,
+    survival_directive_for,
+)
+from god_simulator.simulation.survival import select_goal as select_survival_goal
 
 ChatCompleter = Callable[[dict[str, Any]], dict[str, Any]]
 
@@ -227,7 +235,11 @@ class OpenAICompatibleWorldSimulator:
                 f"LLM connector returned unusable action for {npc.id}; using safe fallback: {exc}",
                 flush=True,
             )
-            return [_safe_fallback_directive(world, npc, reason="model output was unusable")]
+            return [
+                _safe_fallback_directive(
+                    world, npc, next_tick, reason="model output was unusable"
+                )
+            ]
 
         directives = [
             directive
@@ -235,7 +247,9 @@ class OpenAICompatibleWorldSimulator:
             if directive.npc_id == npc.id
         ]
         if not directives:
-            return [_safe_fallback_directive(world, npc, reason="model omitted this NPC")]
+            return [
+                _safe_fallback_directive(world, npc, next_tick, reason="model omitted this NPC")
+            ]
         return directives
 
     def _build_request(
@@ -245,13 +259,22 @@ class OpenAICompatibleWorldSimulator:
         npc: Npc,
     ) -> dict[str, Any]:
         assert self._config.model is not None
-        perception, goal = refresh_citizen_motivation(world, npc)
-        action_mask = build_action_mask(world, npc, perception, goal)
+
+        if is_survival_world(world):
+            survival_goal = select_survival_goal(npc, world)
+            allowed = GOAL_ACTIONS.get(survival_goal) or ["observe"]
+            messages = _build_survival_messages(world, next_tick, npc, survival_goal, allowed)
+            tools = _action_tools(cast(list[ActionKind], allowed))
+        else:
+            perception, goal = refresh_citizen_motivation(world, npc)
+            action_mask = build_action_mask(world, npc, perception, goal)
+            messages = _build_messages(world, next_tick, npc, perception, action_mask)
+            tools = _action_tools(action_mask.allowed_actions)
 
         request: dict[str, Any] = {
             "model": self._config.model,
-            "messages": _build_messages(world, next_tick, npc, perception, action_mask),
-            "tools": _action_tools(action_mask.allowed_actions),
+            "messages": messages,
+            "tools": tools,
             "temperature": self._config.temperature,
             "top_p": self._config.top_p,
             "max_tokens": self._config.max_tokens,
@@ -364,6 +387,73 @@ def _build_messages(
     ]
 
 
+def _build_survival_messages(
+    world: WorldState,
+    next_tick: int,
+    npc: Npc,
+    goal: str,
+    allowed_actions: Sequence[str],
+) -> list[dict[str, str]]:
+    """Compact survival prompt: state in, one allowed action out."""
+    beast = nearest_beast(world, npc.position)
+    if beast is not None:
+        threat = f"Beast {beast.id} is {vec_distance(npc.position, beast.position):.1f} tiles away!"
+    else:
+        threat = "No threat"
+
+    nearby_nodes = sorted(
+        world.resource_nodes,
+        key=lambda node: vec_distance(npc.position, node.position),
+    )[:2]
+    resources = [
+        f"{node.id}:{node.resource_type} dist {vec_distance(npc.position, node.position):.0f} "
+        f"(x{node.amount})"
+        for node in nearby_nodes
+    ]
+    people = [
+        f"{other.name} ({'armed' if other.inventory_weapon > 0 else 'unarmed'})"
+        for other in world.npcs
+        if other.id != npc.id
+        and is_alive(other)
+        and vec_distance(npc.position, other.position) <= 4 * BLOCK_SIZE
+    ]
+
+    payload = {
+        "npc_id": npc.id,
+        "status": {
+            "health": round(npc.health),
+            "hunger": round(npc.hunger),
+            "fear": round(npc.fear),
+        },
+        "inventory": {
+            "food": npc.inventory_food,
+            "herbs": npc.inventory_herbs,
+            "wood": npc.inventory_wood,
+            "weapon": npc.inventory_weapon,
+        },
+        "goal": goal,
+        "threat": threat,
+        "nearby_resources": resources,
+        "nearby_people": people,
+        "allowed_actions": list(allowed_actions),
+    }
+
+    return [
+        {
+            "role": "system",
+            "content": (
+                f"You are {npc.name}, surviving in a dangerous world. "
+                "Choose exactly ONE action with a single choose_action tool call. "
+                "Pick only from allowed_actions. No prose, no reasoning."
+            ),
+        },
+        {
+            "role": "user",
+            "content": json.dumps(payload, ensure_ascii=False),
+        },
+    ]
+
+
 def _npc_context(
     world: WorldState,
     npc: Npc,
@@ -533,6 +623,16 @@ def _action_kind(raw: object) -> ActionKind | None:
         "search_target",
         "move_to_target",
         "attack_back",
+        # Survival actions (resolved by the survival engine in survival worlds).
+        "gather",
+        "eat",
+        "heal",
+        "move_to_resource",
+        "move_to",
+        "trade",
+        "steal",
+        "find_food",
+        "find_herbs",
     ):
         return cast(ActionKind, raw)
     return None
@@ -636,7 +736,16 @@ def _missing_npcs(npcs: Sequence[Npc], directives: Sequence[NpcDirective]) -> li
     return [npc for npc in npcs if npc.id not in npc_ids_with_directives]
 
 
-def _safe_fallback_directive(world: WorldState, npc: Npc, *, reason: str) -> NpcDirective:
+def _safe_fallback_directive(
+    world: WorldState,
+    npc: Npc,
+    next_tick: int,
+    *,
+    reason: str,
+) -> NpcDirective:
+    if is_survival_world(world):
+        return survival_directive_for(world, npc, next_tick)
+
     perception, goal = refresh_citizen_motivation(world, npc)
     action_mask = build_action_mask(world, npc, perception, goal)
     action = action_mask.fallback_action

src/god_simulator/simulation/mechanics.py

@@ -21,6 +21,71 @@ def distance_between(first: Npc, second: Npc) -> float:
     return math.hypot(first.position.x - second.position.x, first.position.z - second.position.z)
 
 
+def vec_distance(first: Vec3, second: Vec3) -> float:
+    """Planar distance between two world positions (x/z plane)."""
+    return math.hypot(first.x - second.x, first.z - second.z)
+
+
+def move_toward(
+    origin: Vec3,
+    destination: Vec3,
+    step: float,
+    *,
+    half_width: float | None = None,
+    half_depth: float | None = None,
+) -> Vec3:
+    """Move ``origin`` up to ``step`` world units toward ``destination``."""
+    delta_x = destination.x - origin.x
+    delta_z = destination.z - origin.z
+    distance = math.hypot(delta_x, delta_z)
+    if distance == 0 or distance <= step:
+        target_x, target_z = destination.x, destination.z
+    else:
+        scale = step / distance
+        target_x = origin.x + (delta_x * scale)
+        target_z = origin.z + (delta_z * scale)
+    return _bounded_vec(target_x, target_z, half_width=half_width, half_depth=half_depth)
+
+
+def move_away(
+    origin: Vec3,
+    threat: Vec3,
+    step: float,
+    *,
+    half_width: float | None = None,
+    half_depth: float | None = None,
+) -> Vec3:
+    """Move ``origin`` up to ``step`` world units directly away from ``threat``."""
+    delta_x = origin.x - threat.x
+    delta_z = origin.z - threat.z
+    distance = math.hypot(delta_x, delta_z)
+    if distance == 0:
+        delta_x = -1.0 if origin.x > 0 else 1.0
+        delta_z = 0.0
+        distance = 1.0
+    scale = step / distance
+    return _bounded_vec(
+        origin.x + (delta_x * scale),
+        origin.z + (delta_z * scale),
+        half_width=half_width,
+        half_depth=half_depth,
+    )
+
+
+def _bounded_vec(
+    x: float,
+    z: float,
+    *,
+    half_width: float | None,
+    half_depth: float | None,
+) -> Vec3:
+    if half_width is not None:
+        x = _clamp(x, -half_width, half_width)
+    if half_depth is not None:
+        z = _clamp(z, -half_depth, half_depth)
+    return Vec3(x=round(x, 3), y=0.0, z=round(z, 3))
+
+
 _HOSTILE_KEYWORDS = frozenset(
     {
         "attack",

src/god_simulator/simulation/spawning.py

@@ -3,7 +3,15 @@ from __future__ import annotations
 import random
 
 from god_simulator.config import GameConfig
-from god_simulator.domain import MemoryEntry, Npc, Terrain, Vec3, WorldState
+from god_simulator.domain import (
+    Beast,
+    MemoryEntry,
+    Npc,
+    ResourceNode,
+    Terrain,
+    Vec3,
+    WorldState,
+)
 from god_simulator.simulation.mechanics import BLOCK_SIZE, GRID_BLOCKS
 
 _NAMES = [
@@ -47,6 +55,8 @@ def create_world(config: GameConfig) -> WorldState:
             _spawn_npc(index=index, config=config, rng=rng)
             for index in range(config.npcs.count)
         ],
+        resource_nodes=_spawn_resource_nodes(config),
+        beasts=_spawn_beasts(config),
     )
 
 
@@ -59,7 +69,7 @@ def _spawn_npc(*, index: int, config: GameConfig, rng: random.Random) -> Npc:
     x = _random_block_center(rng, half_width=half_width)
     z = _random_block_center(rng, half_width=half_depth)
 
-    return Npc(
+    npc = Npc(
         id=f"npc-{index + 1:03d}",
         name=name,
         role=role,
@@ -68,6 +78,45 @@ def _spawn_npc(*, index: int, config: GameConfig, rng: random.Random) -> Npc:
         memory=[MemoryEntry(tick=0, text=f"{name} arrived as a {role}.")],
     )
 
+    if config.world.survival:
+        # Independent per-NPC RNG so survival inventory never perturbs the shared
+        # position/damage stream (keeps non-survival spawning deterministic).
+        inv_rng = random.Random(config.world.seed + index)
+        npc.inventory_food = inv_rng.randint(0, 2)
+        npc.inventory_herbs = inv_rng.randint(0, 1)
+        npc.inventory_weapon = 1 if index % 3 == 0 else 0
+
+    return npc
+
+
+def _spawn_resource_nodes(config: GameConfig) -> list[ResourceNode]:
+    if not config.world.survival:
+        return []
+    # Spread across the whole 80x80 map so foragers disperse instead of clumping.
+    spec = [
+        ("res_food_1", "food", -12.0, -12.0, 5),
+        ("res_food_2", "food", 16.0, 8.0, 5),
+        ("res_food_3", "food", -24.0, -4.0, 5),
+        ("res_food_4", "food", 20.0, -20.0, 5),
+        ("res_herbs_1", "herbs", 4.0, -16.0, 4),
+        ("res_herbs_2", "herbs", -20.0, 12.0, 4),
+        ("res_herbs_3", "herbs", 28.0, 20.0, 4),
+        ("res_wood_1", "wood", 8.0, 4.0, 6),
+        ("res_wood_2", "wood", -30.0, -24.0, 6),
+        ("res_weapon_1", "weapon", -4.0, 8.0, 2),
+        ("res_weapon_2", "weapon", 24.0, -8.0, 2),
+    ]
+    return [
+        ResourceNode(node_id, kind, Vec3(x=x, y=0.0, z=z), amount=amount, max_amount=amount)
+        for node_id, kind, x, z, amount in spec
+    ]
+
+
+def _spawn_beasts(config: GameConfig) -> list[Beast]:
+    if not config.world.survival:
+        return []
+    return [Beast("beast_1", Vec3(x=6.0, y=0.0, z=6.0))]
+
 
 def _random_block_center(rng: random.Random, *, half_width: float) -> float:
     first_center = -half_width + (BLOCK_SIZE / 2)

src/god_simulator/simulation/survival.py

@@ -0,0 +1,664 @@
+"""Deterministic survival core loop: hunger, resources, and a hunting beast.
+
+This is an additive layer on top of the existing NPC-vs-NPC social pipeline. It
+owns environment truth (hunger, beasts, resource nodes) and resolves a small set
+of survival actions. The LLM never mutates health/position/inventory directly;
+everything flows through :func:`apply_survival_tick` and :func:`apply_action_effects`.
+
+Distances in this module are in world units. The task design is expressed in
+"tiles"; one tile is one terrain block (``BLOCK_SIZE`` world units), so tile-based
+thresholds are scaled by ``TILE`` below.
+"""
+
+from __future__ import annotations
+
+import math
+import random
+
+from god_simulator.domain import Beast, Npc, ResourceNode, Vec3, WorldState
+from god_simulator.simulation.connectors.base import NpcDirective, TickPlan
+from god_simulator.simulation.mechanics import (
+    BLOCK_SIZE,
+    TALK_RADIUS,
+    is_alive,
+    move_away,
+    move_toward,
+    vec_distance,
+)
+from god_simulator.simulation.memory import remember
+
+TILE = BLOCK_SIZE
+
+# Hunger / health economy.
+HUNGER_RATE = 2.0
+HUNGER_DAMAGE = 3
+STARVATION_THRESHOLD = 80.0
+HUNGER_CAP = 150.0
+HEAL_GOAL_HEALTH = 40  # health < this (with herbs) -> heal_self
+FIND_HERBS_HEALTH = 50  # health < this (without herbs) -> find_herbs
+
+# Awareness radii (world units).
+BEAST_ALERT_RADIUS = 6 * TILE
+ALLY_RADIUS = 5 * TILE
+WITNESS_RADIUS = 5 * TILE
+FEAR_DECAY_RADIUS = 8 * TILE
+GATHER_RADIUS = 2 * TILE
+TRADE_RADIUS = 2 * TILE
+
+# Fear dynamics.
+FEAR_ON_ATTACK = 40.0
+FEAR_ON_WITNESS = 20.0
+FEAR_DECAY = 5.0
+
+# Movement / combat (world units).
+NPC_MOVE_STEP = 1 * TILE
+FLEE_STEP = 2 * TILE
+NPC_MELEE_REACH = 2 * TILE
+BASE_NPC_DAMAGE = 15
+WEAPON_DAMAGE_BONUS = 10
+BEAST_RETREAT_HEALTH = 20.0
+
+# Resource regrowth: every node regrows +1 toward its cap on this cadence, so the
+# settlement is sustainable instead of starving once nodes are first depleted.
+RESOURCE_REGEN_INTERVAL = 2
+RESOURCE_REGEN_AMOUNT = 1
+# How many of the nearest non-empty nodes foragers spread across (anti-clumping).
+SPREAD_NODE_CHOICES = 3
+# Minimum surplus food before an NPC is willing to share with a needier neighbor.
+SHARE_FOOD_SURPLUS = 2
+
+# Goal -> allowed survival actions (the deterministic planner and any LLM both
+# choose from these sets; effects are resolved by the engine).
+GOAL_ACTIONS: dict[str, list[str]] = {
+    "survive_threat_fight": ["attack", "defend", "call_for_help"],
+    "survive_threat_flee": ["flee", "call_for_help", "defend"],
+    "heal_self": ["heal"],
+    "eat_food": ["eat"],
+    "find_food": ["move_to_resource", "gather", "trade", "steal"],
+    "find_herbs": ["move_to_resource", "gather", "trade"],
+    "routine_life": ["gather", "trade", "move_to", "talk"],
+    "dead": [],
+}
+
+# Every action the survival resolver knows how to execute.
+VALID_SURVIVAL_ACTIONS = frozenset(
+    {action for actions in GOAL_ACTIONS.values() for action in actions}
+    | {"move_to_resource", "find_food", "find_herbs", "idle"}
+)
+
+
+# --------------------------------------------------------------------------- #
+# Spatial queries
+# --------------------------------------------------------------------------- #
+def nearest_beast(world: WorldState, position: Vec3) -> Beast | None:
+    living = [beast for beast in world.beasts if beast.state != "dead"]
+    if not living:
+        return None
+    return min(living, key=lambda beast: (vec_distance(position, beast.position), beast.id))
+
+
+def nearest_beast_distance(world: WorldState, npc: Npc) -> float:
+    beast = nearest_beast(world, npc.position)
+    if beast is None:
+        return float("inf")
+    return vec_distance(npc.position, beast.position)
+
+
+def find_nearest_alive_npc(
+    world: WorldState,
+    position: Vec3,
+    *,
+    exclude_id: str | None = None,
+) -> Npc | None:
+    candidates = [
+        npc
+        for npc in world.npcs
+        if is_alive(npc) and npc.id != exclude_id
+    ]
+    if not candidates:
+        return None
+    return min(candidates, key=lambda npc: (vec_distance(position, npc.position), npc.id))
+
+
+def nearest_alive_npc(
+    world: WorldState,
+    npc: Npc,
+    *,
+    max_dist: float,
+    require_food: bool = False,
+) -> Npc | None:
+    candidates = [
+        other
+        for other in world.npcs
+        if other.id != npc.id
+        and is_alive(other)
+        and vec_distance(npc.position, other.position) <= max_dist
+        and (not require_food or other.inventory_food > 0)
+    ]
+    if not candidates:
+        return None
+    return min(candidates, key=lambda other: (vec_distance(npc.position, other.position), other.id))
+
+
+def nearest_resource(
+    world: WorldState,
+    position: Vec3,
+    *,
+    resource_type: str | None = None,
+    max_dist: float | None = None,
+    require_amount: bool = True,
+) -> ResourceNode | None:
+    candidates = [
+        node
+        for node in world.resource_nodes
+        if (resource_type is None or node.resource_type == resource_type)
+        and (not require_amount or node.amount > 0)
+        and (max_dist is None or vec_distance(position, node.position) <= max_dist)
+    ]
+    if not candidates:
+        return None
+    return min(candidates, key=lambda node: (vec_distance(position, node.position), node.id))
+
+
+def npcs_in_radius(
+    world: WorldState,
+    position: Vec3,
+    radius: float,
+    *,
+    exclude_id: str | None = None,
+) -> list[Npc]:
+    return [
+        npc
+        for npc in world.npcs
+        if is_alive(npc)
+        and npc.id != exclude_id
+        and vec_distance(position, npc.position) <= radius
+    ]
+
+
+def count_alive_npcs_in_radius(world: WorldState, position: Vec3, radius: float) -> int:
+    return sum(
+        1
+        for npc in world.npcs
+        if is_alive(npc) and vec_distance(position, npc.position) <= radius
+    )
+
+
+# --------------------------------------------------------------------------- #
+# Deterministic environment tick (no LLM)
+# --------------------------------------------------------------------------- #
+def apply_survival_tick(world: WorldState) -> None:
+    """Advance hunger, the beast, fear, and starvation deaths for one tick.
+
+    No-op for worlds without survival entities, so the existing social-only
+    pipeline and its tests are unaffected.
+    """
+    if not world.beasts and not world.resource_nodes:
+        return
+
+    half_width = world.terrain.width / 2
+    half_depth = world.terrain.depth / 2
+
+    if world.tick % RESOURCE_REGEN_INTERVAL == 0:
+        for node in world.resource_nodes:
+            if node.max_amount > 0 and node.amount < node.max_amount:
+                node.amount = min(node.max_amount, node.amount + RESOURCE_REGEN_AMOUNT)
+
+    for npc in world.npcs:
+        if not is_alive(npc):
+            continue
+        npc.hunger = min(HUNGER_CAP, npc.hunger + HUNGER_RATE)
+        if npc.hunger > STARVATION_THRESHOLD:
+            npc.health -= HUNGER_DAMAGE
+
+    for beast in world.beasts:
+        if beast.state == "dead":
+            continue
+        target = find_nearest_alive_npc(world, beast.position)
+        if target is None:
+            continue
+        beast.target_npc_id = target.id
+
+        distance = vec_distance(beast.position, target.position)
+        step = beast.speed * TILE
+        reach = beast.attack_range * TILE
+
+        if beast.health < BEAST_RETREAT_HEALTH:
+            beast.state = "retreating"
+            beast.position = move_away(
+                beast.position,
+                target.position,
+                step,
+                half_width=half_width,
+                half_depth=half_depth,
+            )
+            continue
+
+        if distance <= reach:
+            beast.state = "attacking"
+            target.health -= int(beast.damage)
+            target.fear = min(100.0, target.fear + FEAR_ON_ATTACK)
+            remember(target, world.tick, f"Beast {beast.id} attacked me at tick {world.tick}.")
+            if not is_alive(target):
+                target.intention = "dead"
+                remember(target, world.tick, "You were killed by the beast.")
+            for witness in npcs_in_radius(world, beast.position, WITNESS_RADIUS, exclude_id=target.id):
+                witness.fear = min(100.0, witness.fear + FEAR_ON_WITNESS)
+                remember(witness, world.tick, f"The beast attacked {target.name} nearby.")
+        else:
+            beast.state = "hunting"
+            beast.position = move_toward(
+                beast.position,
+                target.position,
+                step,
+                half_width=half_width,
+                half_depth=half_depth,
+            )
+
+    for npc in world.npcs:
+        if not is_alive(npc):
+            npc.survival_goal = "dead"
+            continue
+        if nearest_beast_distance(world, npc) > FEAR_DECAY_RADIUS:
+            npc.fear = max(0.0, npc.fear - FEAR_DECAY)
+        # Keep the live goal current for the snapshot, even when planning ran on a
+        # deep-copied world (the HTTP server path).
+        npc.survival_goal = select_goal(npc, world)
+
+
+# --------------------------------------------------------------------------- #
+# Goal selection + action mask
+# --------------------------------------------------------------------------- #
+def select_goal(npc: Npc, world: WorldState) -> str:
+    if not is_alive(npc):
+        return "dead"
+
+    beast_nearby = nearest_beast_distance(world, npc) < BEAST_ALERT_RADIUS
+    has_weapon = npc.inventory_weapon > 0
+    allies_nearby = count_alive_npcs_in_radius(world, npc.position, ALLY_RADIUS) > 1
+
+    if beast_nearby and has_weapon and allies_nearby:
+        return "survive_threat_fight"
+    if beast_nearby:
+        return "survive_threat_flee"
+    if npc.health < HEAL_GOAL_HEALTH and npc.inventory_herbs > 0:
+        return "heal_self"
+    if npc.hunger > STARVATION_THRESHOLD and npc.inventory_food > 0:
+        return "eat_food"
+    if npc.hunger > STARVATION_THRESHOLD:
+        return "find_food"
+    if npc.health < FIND_HERBS_HEALTH and npc.inventory_herbs == 0:
+        return "find_herbs"
+    return "routine_life"
+
+
+def allowed_actions_for_goal(goal: str) -> list[str]:
+    return list(GOAL_ACTIONS.get(goal, []))
+
+
+def validate_survival_action(npc: Npc, action: str, world: WorldState) -> str:
+    """Return a safe, executable action, repairing impossible requests."""
+    if action == "gather":
+        node = nearest_resource(world, npc.position, max_dist=GATHER_RADIUS)
+        if node is None or node.amount <= 0:
+            return "move_to_resource"
+        return "gather"
+    if action == "eat":
+        return "eat" if npc.inventory_food > 0 else "find_food"
+    if action == "heal":
+        return "heal" if npc.inventory_herbs > 0 else "find_herbs"
+    if action == "attack":
+        beast = nearest_beast(world, npc.position)
+        if beast is None:
+            return "defend"
+        return "attack"  # apply_action_effects approaches when out of melee reach
+    if action == "steal":
+        partner = nearest_alive_npc(world, npc, max_dist=TRADE_RADIUS, require_food=True)
+        return "steal" if partner is not None else "move_to_resource"
+    if action in VALID_SURVIVAL_ACTIONS:
+        return action
+    return "idle"
+
+
+# --------------------------------------------------------------------------- #
+# Effect resolver (engine owns all state changes)
+# --------------------------------------------------------------------------- #
+def apply_action_effects(
+    npc: Npc,
+    action: str,
+    world: WorldState,
+    *,
+    destination: Vec3 | None = None,
+) -> str:
+    """Apply one validated survival action; return a short intention summary."""
+    half_width = world.terrain.width / 2
+    half_depth = world.terrain.depth / 2
+
+    if action == "eat":
+        if npc.inventory_food > 0:
+            npc.inventory_food -= 1
+            npc.hunger = max(0.0, npc.hunger - 40.0)
+            npc.health = min(100, npc.health + 5)
+            return "eating food"
+        return "searching for food"
+
+    if action == "heal":
+        if npc.inventory_herbs > 0:
+            npc.inventory_herbs -= 1
+            npc.health = min(100, npc.health + 25)
+            return "healing with herbs"
+        return "searching for herbs"
+
+    if action == "gather":
+        node = nearest_resource(world, npc.position, max_dist=GATHER_RADIUS)
+        if node is not None and node.amount > 0:
+            node.amount -= 1
+            _add_to_inventory(npc, node.resource_type)
+            remember(npc, world.tick, f"You gathered {node.resource_type}.")
+            return f"gathering {node.resource_type}"
+        return "searching for resources"
+
+    if action in ("move_to_resource", "find_food", "find_herbs"):
+        dest = destination or _resource_destination(world, npc, action)
+        if dest is not None:
+            npc.position = move_toward(
+                npc.position, dest, NPC_MOVE_STEP, half_width=half_width, half_depth=half_depth
+            )
+            return "heading to resources"
+        return "wandering"
+
+    if action == "move_to":
+        # Free wander in a deterministic-but-varied direction (anti-clumping).
+        rng = random.Random(f"{world.seed}:{world.tick}:{npc.id}:wander")
+        angle = rng.uniform(0.0, 2.0 * math.pi)
+        dest = Vec3(
+            x=npc.position.x + math.cos(angle) * NPC_MOVE_STEP * 3,
+            y=0.0,
+            z=npc.position.z + math.sin(angle) * NPC_MOVE_STEP * 3,
+        )
+        npc.position = move_toward(
+            npc.position, dest, NPC_MOVE_STEP, half_width=half_width, half_depth=half_depth
+        )
+        return "wandering"
+
+    if action == "flee":
+        beast = nearest_beast(world, npc.position)
+        if beast is not None:
+            npc.position = move_away(
+                npc.position,
+                beast.position,
+                FLEE_STEP,
+                half_width=half_width,
+                half_depth=half_depth,
+            )
+            return "fleeing the beast"
+        return "looking around"
+
+    if action == "attack":
+        beast = nearest_beast(world, npc.position)
+        if beast is None:
+            return "defending"
+        if vec_distance(npc.position, beast.position) <= NPC_MELEE_REACH:
+            damage = BASE_NPC_DAMAGE + (WEAPON_DAMAGE_BONUS if npc.inventory_weapon > 0 else 0)
+            beast.health -= damage
+            remember(npc, world.tick, f"You struck {beast.id} for {damage} damage.")
+            if beast.health <= 0:
+                beast.state = "dead"
+                remember(npc, world.tick, f"You killed {beast.id}!")
+                return "killed the beast"
+            return "fighting the beast"
+        npc.position = move_toward(
+            npc.position,
+            beast.position,
+            NPC_MOVE_STEP,
+            half_width=half_width,
+            half_depth=half_depth,
+        )
+        return "charging the beast"
+
+    if action == "trade":
+        # Share food from whoever has a surplus with the neediest nearby neighbour,
+        # so food flows from haves to have-nots instead of people starving alone.
+        partner = _neediest_food_neighbor(world, npc)
+        if (
+            partner is not None
+            and npc.inventory_food >= SHARE_FOOD_SURPLUS
+            and partner.inventory_food < npc.inventory_food
+        ):
+            npc.inventory_food -= 1
+            partner.inventory_food += 1
+            remember(npc, world.tick, f"Gave food to {partner.name}.")
+            remember(partner, world.tick, f"Received food from {npc.name}.")
+            return f"sharing food with {partner.name}"
+        return "looking for someone to trade with"
+
+    if action == "steal":
+        partner = nearest_alive_npc(world, npc, max_dist=TRADE_RADIUS, require_food=True)
+        if partner is not None and partner.inventory_food > 0:
+            partner.inventory_food -= 1
+            npc.inventory_food += 1
+            remember(npc, world.tick, f"Stole food from {partner.name}.")
+            remember(partner, world.tick, f"{npc.name} stole food from you.")
+            return f"stealing from {partner.name}"
+        return "looking to steal"
+
+    if action == "call_for_help":
+        for ally in npcs_in_radius(world, npc.position, WITNESS_RADIUS, exclude_id=npc.id):
+            ally.fear = min(100.0, ally.fear + 5.0)
+        return "calling for help"
+
+    if action == "defend":
+        return "defending"
+
+    if action == "talk":
+        partner = nearest_alive_npc(world, npc, max_dist=TALK_RADIUS)
+        if partner is not None:
+            line = _small_talk_line(npc, partner)
+            remember(npc, world.tick, f"You talked with {partner.name}: {line}")
+            remember(partner, world.tick, f"{npc.name} talked with you: {line}")
+            return f"talking to {partner.name}"
+        return "wandering"
+
+    return "idle"
+
+
+def _add_to_inventory(npc: Npc, resource_type: str) -> None:
+    if resource_type == "food":
+        npc.inventory_food += 1
+    elif resource_type == "herbs":
+        npc.inventory_herbs += 1
+    elif resource_type == "wood":
+        npc.inventory_wood += 1
+    elif resource_type == "weapon":
+        npc.inventory_weapon += 1
+
+
+def _resource_destination(world: WorldState, npc: Npc, action: str) -> Vec3 | None:
+    if action == "find_food":
+        resource_type: str | None = "food"
+    elif action == "find_herbs":
+        resource_type = "herbs"
+    else:
+        resource_type = None
+    node = nearest_resource(world, npc.position, resource_type=resource_type)
+    if node is None:
+        node = nearest_resource(world, npc.position)
+    return node.position if node is not None else None
+
+
+def _spread_resource(
+    world: WorldState,
+    npc: Npc,
+    index: int,
+    *,
+    resource_type: str | None = None,
+) -> ResourceNode | None:
+    """Pick one of the nearest non-empty nodes, fanned out by NPC index.
+
+    Spreading foragers across several nearby nodes stops the whole settlement from
+    piling onto a single node and then starving together.
+    """
+    nodes = sorted(
+        (
+            node
+            for node in world.resource_nodes
+            if node.amount > 0 and (resource_type is None or node.resource_type == resource_type)
+        ),
+        key=lambda node: (vec_distance(npc.position, node.position), node.id),
+    )
+    if not nodes and resource_type is not None:
+        nodes = sorted(
+            (node for node in world.resource_nodes if node.amount > 0),
+            key=lambda node: (vec_distance(npc.position, node.position), node.id),
+        )
+    if not nodes:
+        return None
+    return nodes[index % min(SPREAD_NODE_CHOICES, len(nodes))]
+
+
+def _neediest_food_neighbor(world: WorldState, npc: Npc) -> Npc | None:
+    candidates = [
+        other
+        for other in world.npcs
+        if other.id != npc.id
+        and is_alive(other)
+        and vec_distance(npc.position, other.position) <= TRADE_RADIUS
+    ]
+    if not candidates:
+        return None
+    return min(candidates, key=lambda other: (other.inventory_food, -other.hunger, other.id))
+
+
+def _small_talk_line(npc: Npc, partner: Npc) -> str:
+    if npc.fear > 30:
+        return "stay alert, the beast is near"
+    if npc.hunger > 60:
+        return "I'm getting hungry"
+    if npc.inventory_food >= SHARE_FOOD_SURPLUS:
+        return "I have food to spare if you need it"
+    if npc.inventory_weapon > 0:
+        return "keep close, I'm armed"
+    return "how are you holding up?"
+
+
+# --------------------------------------------------------------------------- #
+# Deterministic survival planner + resolver
+# --------------------------------------------------------------------------- #
+def is_survival_world(world: WorldState) -> bool:
+    return bool(world.beasts or world.resource_nodes)
+
+
+def survival_directive_for(world: WorldState, npc: Npc, next_tick: int) -> NpcDirective:
+    """Deterministic survival directive for a single NPC (used as a safe fallback)."""
+    goal = select_goal(npc, world)
+    index = next((i for i, candidate in enumerate(world.npcs) if candidate.id == npc.id), 0)
+    return _plan_directive(world, npc, goal, next_tick, index)
+
+
+def propose_survival_tick(world: WorldState, next_tick: int) -> TickPlan:
+    """Deterministic survival plan: one survival action per living NPC."""
+    directives: list[NpcDirective] = []
+    for index, npc in enumerate(world.npcs):
+        if not is_alive(npc):
+            continue
+        goal = select_goal(npc, world)
+        directives.append(_plan_directive(world, npc, goal, next_tick, index))
+    return TickPlan(source="survival", directives=directives)
+
+
+def apply_survival_plan(
+    world: WorldState,
+    next_tick: int,
+    plan: TickPlan,
+) -> list[dict[str, object]]:
+    """Resolve a survival plan onto the live world. Returns debug traces."""
+    debug: list[dict[str, object]] = []
+    npcs_by_id = {npc.id: npc for npc in world.npcs}
+
+    for directive in plan.directives:
+        npc = npcs_by_id.get(directive.npc_id)
+        if npc is None:
+            continue
+        if not is_alive(npc):
+            npc.intention = "dead"
+            continue
+        action = validate_survival_action(npc, directive.action, world)
+        summary = apply_action_effects(npc, action, world, destination=directive.target)
+        npc.intention = summary
+        debug.append(
+            {
+                "npc_id": npc.id,
+                "goal": npc.survival_goal,
+                "requested_action": directive.action,
+                "action": action,
+                "summary": summary,
+            }
+        )
+
+    for npc in world.npcs:
+        if not is_alive(npc):
+            npc.intention = "dead"
+
+    return debug
+
+
+def _plan_directive(
+    world: WorldState,
+    npc: Npc,
+    goal: str,
+    next_tick: int,
+    index: int,
+) -> NpcDirective:
+    npc.survival_goal = goal
+
+    def directive(action: str, *, target: Vec3 | None = None) -> NpcDirective:
+        return NpcDirective(
+            npc_id=npc.id,
+            action=action,
+            target=target,
+            intent=f"survival:{goal}",
+        )
+
+    if goal == "survive_threat_fight":
+        if (next_tick + index) % 3 == 0:
+            return directive("call_for_help")
+        return directive("attack")
+
+    if goal == "survive_threat_flee":
+        if (next_tick + index) % 4 == 0:
+            return directive("call_for_help")
+        return directive("flee")
+
+    if goal == "heal_self":
+        return directive("heal")
+
+    if goal == "eat_food":
+        return directive("eat")
+
+    if goal in ("find_food", "find_herbs"):
+        resource_type = "food" if goal == "find_food" else "herbs"
+        node = _spread_resource(world, npc, index, resource_type=resource_type)
+        if node is not None:
+            if vec_distance(npc.position, node.position) <= GATHER_RADIUS:
+                return directive("gather")
+            return directive("move_to_resource", target=node.position)
+        return directive("move_to")  # nothing to gather right now -> wander, don't freeze
+
+    # routine_life: socialise, share, forage, or wander -- and spread out.
+    neighbor = nearest_alive_npc(world, npc, max_dist=TALK_RADIUS)
+    phase = (next_tick + index) % 4
+    if (
+        neighbor is not None
+        and npc.inventory_food >= SHARE_FOOD_SURPLUS
+        and neighbor.inventory_food < npc.inventory_food
+        and phase == 0
+    ):
+        return directive("trade")
+    if neighbor is not None and phase == 1:
+        return directive("talk")
+    node = _spread_resource(world, npc, index)
+    if node is not None and vec_distance(npc.position, node.position) <= GATHER_RADIUS:
+        return directive("gather")
+    if node is not None and phase != 3:
+        return directive("move_to_resource", target=node.position)
+    return directive("move_to")  # wander to disperse

src/god_simulator/simulation/tick.py

@@ -35,6 +35,11 @@ from god_simulator.simulation.mechanics import (
 )
 from god_simulator.simulation.memory import remember
 from god_simulator.simulation.perception import CitizenPerception, nearby_threat_npc
+from god_simulator.simulation.survival import (
+    apply_survival_plan,
+    apply_survival_tick,
+    is_survival_world,
+)
 
 
 def advance_world(world: WorldState, simulator: WorldSimulator | None = None) -> WorldState:
@@ -57,6 +62,19 @@ def plan_world_tick(
 
 def apply_tick_plan(world: WorldState, next_tick: int, plan: TickPlan) -> None:
     """Commit an already computed tick plan into the live world state."""
+    # Deterministic survival environment (hunger, beast, fear) runs first and is
+    # a no-op for worlds without survival entities.
+    apply_survival_tick(world)
+
+    # In a survival world all directives (deterministic or LLM) resolve through
+    # the survival resolver so the engine owns hunger/health/position/inventory.
+    if plan.source.startswith("survival") or is_survival_world(world):
+        debug = apply_survival_plan(world, next_tick, plan)
+        world.tick = next_tick
+        world.last_tick_source = plan.source
+        world.last_action_debug = debug
+        return
+
     plan, traces = validate_tick_plan(world, plan)
     traces_by_npc_id = {trace.npc_id: trace for trace in traces}
     resolved_traces: list[ActionDebugTrace] = []

tests/test_survival_loop.py

@@ -0,0 +1,301 @@
+from __future__ import annotations
+
+from god_simulator.config import (
+    GameConfig,
+    NpcConfig,
+    ServerConfig,
+    SimulationConfig,
+    WorldConfig,
+)
+import json
+from typing import Any
+
+from god_simulator.config import ConnectorConfig
+from god_simulator.domain import Beast, Npc, ResourceNode, Terrain, Vec3, WorldState
+from god_simulator.simulation.connectors.base import NpcDirective, TickPlan
+from god_simulator.simulation.connectors.deterministic import DeterministicWorldSimulator
+from god_simulator.simulation.connectors.openai_compatible import OpenAICompatibleWorldSimulator
+from god_simulator.simulation.spawning import create_world
+from god_simulator.simulation.survival import (
+    GOAL_ACTIONS,
+    apply_action_effects,
+    apply_survival_tick,
+    select_goal,
+    validate_survival_action,
+)
+from god_simulator.simulation.tick import advance_world, apply_tick_plan
+
+
+def _npc(npc_id: str = "npc-001", name: str = "Ada", *, x: float = 0.0, z: float = 0.0,
+         role: str = "farmer", **state: object) -> Npc:
+    return Npc(id=npc_id, name=name, role=role, position=Vec3(x=x, y=0.0, z=z), **state)  # type: ignore[arg-type]
+
+
+def _world(
+    npcs: list[Npc],
+    *,
+    beasts: list[Beast] | None = None,
+    resource_nodes: list[ResourceNode] | None = None,
+    tick: int = 0,
+) -> WorldState:
+    return WorldState(
+        tick=tick,
+        seed=42,
+        terrain=Terrain(kind="plain_green", width=80, depth=80),
+        npcs=npcs,
+        resource_nodes=resource_nodes or [],
+        beasts=beasts or [],
+    )
+
+
+def _survival_config(*, npc_count: int = 6) -> GameConfig:
+    return GameConfig(
+        world=WorldConfig(width=80, depth=80, terrain="plain_green", seed=42, survival=True),
+        npcs=NpcConfig(count=npc_count),
+        simulation=SimulationConfig(tick_ms=500),
+        server=ServerConfig(host="127.0.0.1", port=8000),
+    )
+
+
+# 1. hunger grows every tick
+def test_hunger_increases_each_tick() -> None:
+    npc = _npc(hunger=25.0)
+    world = _world([npc], resource_nodes=[ResourceNode("r", "food", Vec3(30.0, 0.0, 30.0), 5)])
+
+    apply_survival_tick(world)
+    assert npc.hunger == 27.0
+
+    apply_survival_tick(world)
+    assert npc.hunger == 29.0
+
+
+# 2. hunger > 80 + food in inventory -> goal = eat_food
+def test_high_hunger_with_food_selects_eat_food() -> None:
+    npc = _npc(hunger=85.0, inventory_food=1)
+    assert select_goal(npc, _world([npc])) == "eat_food"
+
+
+# 3. hunger > 80 + no food -> goal = find_food
+def test_high_hunger_without_food_selects_find_food() -> None:
+    npc = _npc(hunger=85.0, inventory_food=0)
+    assert select_goal(npc, _world([npc])) == "find_food"
+
+
+# 4. health < 40 + herbs -> goal = heal_self
+def test_low_health_with_herbs_selects_heal_self() -> None:
+    npc = _npc(health=30, inventory_herbs=1)
+    assert select_goal(npc, _world([npc])) == "heal_self"
+
+
+# 5. beast picks the nearest living NPC
+def test_beast_targets_nearest_alive_npc() -> None:
+    near = _npc("npc-001", "Ada", x=8.0, z=0.0)
+    far = _npc("npc-002", "Boris", x=30.0, z=0.0)
+    beast = Beast("beast_1", Vec3(0.0, 0.0, 0.0))
+    world = _world([far, near], beasts=[beast])
+
+    apply_survival_tick(world)
+
+    assert beast.target_npc_id == "npc-001"
+
+
+# 6. beast in range attacks and lowers health
+def test_beast_in_range_attacks_and_reduces_health() -> None:
+    victim = _npc(x=4.0, z=0.0, health=100)
+    beast = Beast("beast_1", Vec3(0.0, 0.0, 0.0))  # damage 25, reach 1.5 tiles == 6 units
+    world = _world([victim], beasts=[beast])
+
+    apply_survival_tick(world)
+
+    assert victim.health == 75
+    assert beast.state == "attacking"
+
+
+# 7. NPC attacked by beast gains fear >= 40
+def test_attacked_npc_gains_fear() -> None:
+    victim = _npc(x=4.0, z=0.0)
+    beast = Beast("beast_1", Vec3(0.0, 0.0, 0.0))
+    world = _world([victim], beasts=[beast])
+
+    apply_survival_tick(world)
+
+    assert victim.fear >= 40
+
+
+# 8. NPC near a beast gets a survive_threat goal
+def test_nearby_beast_triggers_survive_threat_goal() -> None:
+    npc = _npc(x=8.0, z=0.0)
+    beast = Beast("beast_1", Vec3(0.0, 0.0, 0.0))
+
+    goal = select_goal(npc, _world([npc], beasts=[beast]))
+
+    assert goal.startswith("survive_threat")
+
+
+# 9. armed NPC with allies -> survive_threat_fight
+def test_armed_npc_with_allies_fights() -> None:
+    fighter = _npc("npc-001", "Ada", x=8.0, z=0.0, inventory_weapon=1)
+    ally = _npc("npc-002", "Boris", x=10.0, z=0.0)
+    beast = Beast("beast_1", Vec3(0.0, 0.0, 0.0))
+
+    assert select_goal(fighter, _world([fighter, ally], beasts=[beast])) == "survive_threat_fight"
+
+
+# 10. unarmed loner -> survive_threat_flee
+def test_unarmed_loner_flees() -> None:
+    npc = _npc(x=8.0, z=0.0, inventory_weapon=0)
+    beast = Beast("beast_1", Vec3(0.0, 0.0, 0.0))
+
+    assert select_goal(npc, _world([npc], beasts=[beast])) == "survive_threat_flee"
+
+
+# 11. gather requires a nearby resource node with amount > 0
+def test_gather_requires_nearby_nonempty_resource() -> None:
+    npc = _npc(x=0.0, z=0.0)
+    node = ResourceNode("r1", "food", Vec3(2.0, 0.0, 0.0), amount=3)
+    world = _world([npc], resource_nodes=[node])
+    assert validate_survival_action(npc, "gather", world) == "gather"
+
+    empty = ResourceNode("r2", "food", Vec3(2.0, 0.0, 0.0), amount=0)
+    npc_empty = _npc(x=0.0, z=0.0)
+    assert validate_survival_action(npc_empty, "gather", _world([npc_empty], resource_nodes=[empty])) == (
+        "move_to_resource"
+    )
+
+    far = ResourceNode("r3", "food", Vec3(40.0, 0.0, 0.0), amount=3)
+    npc_far = _npc(x=0.0, z=0.0)
+    assert validate_survival_action(npc_far, "gather", _world([npc_far], resource_nodes=[far])) == (
+        "move_to_resource"
+    )
+
+    # The gather effect consumes one unit and fills the right inventory slot.
+    apply_action_effects(npc, "gather", world)
+    assert npc.inventory_food == 1
+    assert node.amount == 2
+
+
+# 12. invalid action from the model does not break the tick (safe fallback)
+def test_invalid_action_does_not_break_tick() -> None:
+    npc = _npc(x=0.0, z=0.0)
+    world = _world([npc], resource_nodes=[ResourceNode("r", "food", Vec3(40.0, 0.0, 40.0), 5)])
+    plan = TickPlan(
+        source="survival",
+        directives=[NpcDirective(npc_id=npc.id, action="banana_dance")],  # type: ignore[arg-type]
+    )
+
+    apply_tick_plan(world, 1, plan)  # must not raise
+
+    assert world.tick == 1
+    assert npc.intention == "idle"
+    assert validate_survival_action(npc, "banana_dance", world) == "idle"
+
+
+# Extra: end-to-end deterministic survival loop runs through the public tick path.
+def test_survival_world_advances_and_produces_events() -> None:
+    world = create_world(_survival_config(npc_count=6))
+    assert world.beasts and world.resource_nodes
+
+    starting_hunger = [npc.hunger for npc in world.npcs]
+    for _ in range(30):
+        advance_world(world)
+
+    assert world.tick == 30
+    assert world.last_tick_source == "survival"
+    # Every survival goal in GOAL_ACTIONS is a recognised key for the mask.
+    assert all(npc.survival_goal in GOAL_ACTIONS for npc in world.npcs)
+    # Hunger economy and beast pursuit both did something observable.
+    assert any(npc.hunger != start for npc, start in zip(world.npcs, starting_hunger, strict=True))
+    assert world.beasts[0].position != Vec3(6.0, 0.0, 6.0) or world.beasts[0].state != "hunting"
+
+
+# Sustainability: resource nodes regrow toward their cap so the settlement does
+# not starve to death once nodes are first depleted.
+def test_resource_nodes_regrow_over_time() -> None:
+    node = ResourceNode("r", "food", Vec3(40.0, 0.0, 40.0), amount=1, max_amount=5)
+    world = _world([_npc(x=0.0, z=0.0)], resource_nodes=[node], tick=0)
+
+    apply_survival_tick(world)  # tick 0 % 2 == 0 -> +1
+    assert node.amount == 2
+
+    world.tick = 2
+    apply_survival_tick(world)  # -> +1
+    assert node.amount == 3
+
+    node.amount = 5
+    world.tick = 4
+    apply_survival_tick(world)  # never exceeds the cap
+    assert node.amount == 5
+
+
+# Interaction: talk records a real memory on BOTH participants.
+def test_talk_exchanges_memory_between_npcs() -> None:
+    ada = _npc("npc-001", "Ada", x=0.0, z=0.0)
+    boris = _npc("npc-002", "Boris", x=2.0, z=0.0)
+    world = _world([ada, boris], resource_nodes=[ResourceNode("r", "food", Vec3(40.0, 0.0, 40.0), 5)])
+
+    summary = apply_action_effects(ada, "talk", world)
+
+    assert summary == "talking to Boris"
+    assert any("talked" in m.text for m in ada.memory)
+    assert any("Ada talked with you" in m.text for m in boris.memory)
+
+
+# Cooperation: a surplus holder shares food with a needier neighbour.
+def test_trade_shares_food_with_needier_neighbor() -> None:
+    giver = _npc("npc-001", "Ada", x=0.0, z=0.0, inventory_food=3)
+    taker = _npc("npc-002", "Boris", x=2.0, z=0.0, inventory_food=0)
+    world = _world([giver, taker])
+
+    summary = apply_action_effects(giver, "trade", world)
+
+    assert summary == "sharing food with Boris"
+    assert giver.inventory_food == 2
+    assert taker.inventory_food == 1
+    assert any("Gave food to Boris" in m.text for m in giver.memory)
+    assert any("Received food from Ada" in m.text for m in taker.memory)
+
+
+# Extra: the LLM connector gets a compact survival prompt and its chosen survival
+# action resolves through the engine without breaking the tick.
+def test_llm_connector_drives_survival_actions() -> None:
+    captured: list[dict[str, Any]] = []
+
+    def fake_chat_completer(request: dict[str, Any]) -> dict[str, Any]:
+        payload = json.loads(request["messages"][1]["content"])
+        captured.append(payload)
+        action = payload["allowed_actions"][0] if payload["allowed_actions"] else "idle"
+        return {
+            "choices": [
+                {
+                    "message": {
+                        "tool_calls": [
+                            {
+                                "type": "function",
+                                "function": {
+                                    "name": "choose_action",
+                                    "arguments": json.dumps(
+                                        {"npc_id": payload["npc_id"], "action": action}
+                                    ),
+                                },
+                            }
+                        ]
+                    }
+                }
+            ]
+        }
+
+    world = create_world(_survival_config(npc_count=4))
+    simulator = OpenAICompatibleWorldSimulator(
+        ConnectorConfig(type="openai_compatible", base_url="http://llm.local/v1", model="test"),
+        fallback=DeterministicWorldSimulator(),
+        chat_completer=fake_chat_completer,
+    )
+
+    advance_world(world, simulator)
+
+    assert world.tick == 1
+    assert captured  # the compact survival prompt was built and sent
+    # Every captured prompt is the compact survival shape, not the social payload.
+    assert all("allowed_actions" in payload and "goal" in payload for payload in captured)
+    assert all("status" in payload and "inventory" in payload for payload in captured)
+    assert "openai_compatible" in world.last_tick_source