summer-engine 1.4.0 → 2.0.0

package/skills/ai-and-npcs/design-npc/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design-npc
-description: Use when the user wants to design an enemy, NPC, boss, companion, civilian, or wave-spawned mob's behavior. Walks perception, decision logic, escalation states, animation/audio tells, and defeat handling — outputs a state-machine GDScript stub plus the recommended node tree. Trigger on "enemy", "NPC", "boss", "companion", "AI", "behavior", "mob", "perception", "design enemy".
+description: Use when the user wants to design an enemy, NPC, boss, companion, civilian, or wave-spawned mob's behavior. Walks perception, personality knobs, intent layer, action state machine, telegraphs, defeat handling, and group emergence — outputs a state-machine GDScript stub plus the recommended node tree. Trigger on "enemy", "NPC", "boss", "companion", "AI", "behavior", "mob", "perception", "design enemy".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: ai-and-npcs
@@ -13,9 +13,11 @@ paths: ["**/*.gd", "**/*.tscn"]
 
 ## Overview
 
-A good NPC is legible: the player can read its mood, predict its next move, and feel the consequence of theirs. This skill walks the design from the inside out — what does the NPC perceive, how does it decide, what tells signal each state, and how does it die or leave the scene. Output: a state-machine GDScript stub plus the scene tree.
+A good NPC is legible and *alive*. The player can read its mood, predict its next move, and feel the consequence of theirs — and the four enemies in a patrol squad don't all behave like clones of one designer-authored script. This skill walks the canonical NPC AI pattern from the inside out: what the NPC perceives, what it *wants* (intent), what it *does* (action), what tells signal each state, and how it dies.
 
-**Core principle:** behavior is what the player *sees*, not what the code does. Every state needs a tell.
+**Core principle:** behavior is what the player *sees*. Two layers separate doing from wanting: an action state machine the body runs, and an intent layer above it that reads perception + personality and tells the action SM what to aim at.
+
+**Second principle:** identical NPCs are predictable, and predictable is boring. Every spawned instance jitters its personality knobs so a squad of four grunts produces emergent variety with zero designer authoring.
 
 ## Steps
 
@@ -33,30 +35,29 @@ Open with the question. Wait.
 
 Each archetype maps to a different complexity budget:
 
-| Archetype | States | Perception | Decision logic | Tells per state |
+| Archetype | Action states | Intents | Perception | Personality range |
 |---|---|---|---|---|
-| Basic enemy | 4 (idle / alert / attack / dead) | Sight cone | State machine | Animation + 1 sound |
-| Boss | 6–10 (per phase) | Sight + hearing + scripted | Behavior tree or hand-coded FSM | Full anim suite + VO |
-| Quest-giver | 2 (idle / talking) | Trigger area | None / dialogue tree | Idle anim + greet |
-| Companion | 5 (follow / combat / wait / heal / dead) | Sight + group awareness | State machine + utility scoring | Anim + voice |
-| Civilian | 3 (wander / panic / dead) | Hearing (loud events) | Simple FSM | Anim + scream |
-| Wave mob | 2 (charge / dead) | Direct line to player | None | Anim + impact |
+| Basic enemy | 4 (calm / alert / aggressive / defeated) | 5 (idle / investigate / hunt / kill / retreat) | Sight cone + LOS raycast | Wide |
+| Boss | 6–10 (per phase) | 5–7 incl. `RESCUE_ALLY` | Sight + hearing + scripted | Narrow, biased high |
+| Quest-giver | 2 (idle / talking) | 1 (idle) | Trigger area | None — fixed |
+| Companion | 5 | 4 (follow / support / engage / retreat) | Sight + group | Narrow, biased low aggression |
+| Civilian | 3 (wander / panic / dead) | 2 (idle / retreat) | Hearing | Caution biased high |
+| Wave mob | 2 (charge / dead) | 1 (kill) | Direct line to player | None |
 
-### 2. Sketch the four design pillars
+### 2. Walk the design pillars
 
-Walk them in order. Don't skip.
+Walk them in order. Don't skip. The pillars are **Perception → Personality → Intent → Action → Telegraph → Defeat**.
 
-#### a) Perception — what does this NPC *sense*?
+#### a) Perception — what does this NPC sense?
 
-Pick the minimum. Over-perception = unfair AI. Common sensors:
+Pick the minimum. Over-perception = unfair AI.
 
 | Sensor | Node | Cost | Use case |
 |---|---|---|---|
 | Sight cone | RayCast3D + dot product check | Cheap | Standard enemy |
 | Sphere proximity | Area3D with sphere shape | Cheap | "Felt your presence" / aggro range |
-| Hearing event | Signal from world events (gunshot, footstep) | Cheapest (event-driven) | Alert nearby NPCs |
-| Group awareness | Shared signal bus (autoload) | Cheap | Pack tactics |
-| Scripted scripted (boss) | Manual state changes | Free | Phase transitions |
+| Hearing event | Signal from world events | Cheapest | Alert nearby NPCs |
+| Group awareness | Shared signal bus (autoload) | Cheap | Pack tactics, rescue intent |
 
 Recommended setup for a basic enemy:
 
@@ -66,68 +67,115 @@ Enemy (CharacterBody3D)
 ├── CollisionShape3D
 ├── Vision (Area3D)        # sphere shape, radius = sight range
 │   └── CollisionShape3D
-└── Sight (RayCast3D)      # confirms line-of-sight when target in Vision area
+└── Sight (RayCast3D)      # confirms LOS for candidates inside Vision
 ```
 
-The two-step (Area3D for proximity, RayCast3D for line-of-sight) is the right default. Don't raycast every frame to every potential target — first filter by Area3D overlap, then raycast only the candidates.
+Two-step (Area3D filter, then RayCast LOS) is the right default. Don't raycast to every potential target every frame.
+
+#### b) Personality — four floats that make this NPC *not* a clone
+
+Every NPC instance gets **four knobs**, each in `[0.0, 1.0]`, declared as `@export_range` so designers can tune the *base* per archetype, then **randomized per-instance at `_ready`** so spawned siblings differ.
+
+| Knob | What it controls | High value reads as | Low value reads as |
+|---|---|---|---|
+| `aggression` | How fast the intent layer escalates to `KILL`; shorter pre-attack hesitation | Berserker that closes distance | Cautious skirmisher that waits |
+| `patience` | How long the NPC stays in `INVESTIGATE` before giving up; tolerance for circling without attacking | Will hunt the player across the level | Loses interest quickly, returns to patrol |
+| `caution` | How eagerly it breaks line-of-sight when hurt; how often it backs off after a hit trade | Kites and uses cover | Trades blows recklessly |
+| `punishment` | Probability of swapping intent to `KILL` when the player is recovering, reloading, healing | Punishes whiffs and animation locks | Lets the player breathe |
+
+**Threshold mapping** (used inside the intent layer): `engage_threshold = 2.0 - aggression` (higher aggression = engage faster), `search_duration = 4.0 + patience * 6.0` (patient NPC searches up to 10s), `break_los_chance = caution * (1 - hp_ratio)` (cautious AND hurt = break LOS), and `should_punish() = randf() < punishment` (rolled when the player is recovering / reloading).
 
-#### b) Decision logic — state machine vs behavior tree
+Declare the knobs as `@export_range(0.0, 1.0)` so each archetype scene tunes them per-instance, and jitter them by `+/- personality_jitter` (default 0.15) inside `_ready` — same script + same archetype scene produces NPCs whose feel is shaped by four numbers alone. Full example in the script stub at step 7.
 
-**Strong recommendation:** start with a state machine. Always.
+#### c) Intent layer — what the NPC is *trying* to do
 
-| | State machine | Behavior tree |
+The intent layer sits **above** the action SM. It runs each tick, reads perception + personality + group state, and writes a single `current_intent`. The action SM reads `current_intent` to pick its transitions; it never sets intent itself. See `_decide_intent` in the stub (step 7) for the canonical priority order: `RESCUE_ALLY` > `RETREAT` (low HP + caution) > `KILL` (pressure built) > `INVESTIGATE` (lost LOS, within memory) > `HUNT` (LOS, out of range) > `PATROL` / `IDLE`.
+
+Five-to-seven intents is the sweet spot:
+
+| Intent | When | Effect on action SM |
 |---|---|---|
-| Best for | < 10 states, scripted bosses, basic enemies | Reactive complex AI, branching priorities |
-| Author cost | Low — read top to bottom | High — tree structure has its own learning curve |
-| Debug | Print current state | Tree visualizer needed |
-| Common failure | State explosion at ~15 states | Premature complexity |
+| `IDLE` | No target, no patrol route | Action SM stays in `Calm` |
+| `PATROL` | No target, route exists | `Calm`, walks the path |
+| `INVESTIGATE` | Lost LOS, within memory window | `Alert`, moves to last-known position |
+| `HUNT` | LOS, out of attack range | `Alert/Aggressive`, closes distance |
+| `KILL` | LOS, in attack range, pressure built | `Aggressive`, executes attack |
+| `RETREAT` | Low HP and high caution, OR over-extended | `Alert`, moves away, breaks LOS |
+| `RESCUE_ALLY` | Allied NPC emitted `needs_help` | `Alert`, moves to ally |
 
-Use a behavior tree when:
-- You have 10+ states with priority interactions.
-- You want designers (not coders) editing logic.
-- The NPC has simultaneous goals (hunt + survive + cover).
+The action SM's job is now narrow: given an intent, what locomotion + animation + hitbox state matches?
 
-For everything else: FSM. See `scripting-patterns/state-machine-patterns/SKILL.md`.
+#### d) Action SM — what the body is *currently doing*
 
-#### c) Escalation — tells per state
+Four states is plenty for a basic enemy. They are the visible mood, not the goal.
 
-Every state must have at least one *tell* the player can read. List them up front:
+```gdscript
+enum State { CALM, ALERT, AGGRESSIVE, DEFEATED }
+```
 
-| State | Animation tell | Audio tell | VFX tell |
-|---|---|---|---|
-| Idle | Breathing loop, occasional look | Ambient (snore, hum) | None |
-| Alert | Head turn toward target, posture change | "Huh?" / radio chatter | Eye glow / aggro line |
-| Aggressive | Combat pose, weapon raised | Battle cry | Muzzle flash / windup glow |
-| Attacking | Strike anim with telegraph | Swing/shoot sound | Particle trail |
-| Hurt | Stagger anim | Pain sound | Hit flash (see `vfx`) |
-| Defeated | Death anim + ragdoll | Death sound | Loot drop / dissolve |
+| State | Reads intent | Animation | Audio | VFX |
+|---|---|---|---|---|
+| `CALM` | `IDLE`, `PATROL` | Breathing loop, look-around | Ambient | None |
+| `ALERT` | `INVESTIGATE`, `HUNT`, `RETREAT`, `RESCUE_ALLY` | Posture up, head tracks target | "Huh?" / radio | Eye glow |
+| `AGGRESSIVE` | `KILL` | Combat pose, weapon raised, swing windup | Battle cry | Muzzle flash / windup glow |
+| `DEFEATED` | (terminal) | Death anim → ragdoll | Death sound | Loot drop / dissolve |
 
-**Telegraph is non-negotiable for boss/heavy attacks:** 0.3–0.7 sec of windup the player can react to. Faster than 0.3 sec = "unfair"; slower than 0.7 sec = "boring".
+Action transitions are computed from `current_intent` and a few action-local conditions (HP, animation locks). The intent layer does not transition action states directly — it sets the *goal*, action follows.
 
-#### d) Defeat handling — what happens when it dies?
+#### e) Telegraph — every aggressive action has a tell
+
+**Telegraph is non-negotiable for any attack.** 0.3–0.7 sec of windup the player can react to. Faster than 0.3 = "unfair"; slower than 0.7 = "boring". Personality bleeds into telegraph length:
+
+```gdscript
+func attack_windup_time() -> float:
+    # high aggression = shorter hesitation, but never below 0.25
+    return maxf(0.25, attack_telegraph * (1.5 - aggression))
+```
+
+Every aggressive action has at least one of: animation windup, audio cue, VFX glow, particle trail, hitbox preview. Cheap mobs can collapse all three into one anim — but the windup *must* exist.
+
+#### f) Defeat — what happens when it dies
 
 Plan it. "It just disappears" is bad. Choices:
 
 - **Death animation** plays, body stays for N sec, then `queue_free`.
-- **Ragdoll**: switch CollisionShape from KinematicBody to RigidBody. Adds weight to the kill.
-- **Loot drop**: spawn a pickup at death position.
-- **Cleanup**: remove from group, disconnect signals, free children. Otherwise leak.
-- **Score / quest hook**: emit a `died` signal the gameplay layer listens for.
+- **Ragdoll**: switch CollisionShape from CharacterBody3D to RigidBody3D for weight.
+- **Loot drop**: spawn pickup at death position.
+- **Cleanup**: leave any group, disconnect signals, free children.
+- **Score / quest hook**: emit `died(global_position)` for the gameplay layer.
+- **Group signal**: emit `ally_defeated` so squadmates can update their `RESCUE_ALLY` checks (or panic).
+
+### 3. Group emergence — varied personality across a squad
+
+When you spawn a squad of four with the same archetype but personality jittered per-instance, you get behavioral roles for free.
+
+Worked example — four basic_grunts with `aggression` after jitter at `0.3 / 0.5 / 0.7 / 0.9`:
+
+| Instance | aggression | Emergent role | Why |
+|---|---|---|---|
+| 1 | 0.3 | Sniper | Slow to engage, stays at range, builds pressure slowly |
+| 2 | 0.5 | Anchor | Holds the line, neither rushes nor retreats |
+| 3 | 0.7 | Flanker | Closes mid-fight, looks for openings |
+| 4 | 0.9 | Berserker | Rushes immediately, short windups |
 
-### 3. Read the scene to find an attach point
+No designer authored "the sniper". The jitter on a single knob produced a four-role squad. Stack `caution` and `patience` on top and you get richer roles (a high-caution / low-aggression NPC reads as "the careful one who hangs back and supports"). The squad feels coordinated even though each NPC is making local decisions.
+
+**Implementation note:** spawners should call `randomize()` once at `_ready` and let each NPC's own `_ready` handle the jitter. Don't try to author roles centrally — the variation *is* the design.
+
+### 4. Read the scene to find an attach point
 
 ```
 summer_get_scene_tree
 summer_inspect_node "./World"
 ```
 
-Identify where the NPC will live (a `Enemies` parent, or directly under World). Confirm the player exists for line-of-sight.
+Identify where the NPC will live (an `Enemies` parent, or directly under World). Confirm the player exists for line-of-sight.
 
-### 4. Propose the bundle
+### 5. Propose the bundle
 
-> I'm about to design a basic patrol-and-chase enemy. Scene tree: Enemy (CharacterBody3D) + Vision Area3D + Sight RayCast3D + CollisionShape3D + MeshInstance3D. Script `scripts/enemy_ai.gd` with 4 states (idle / alert / attack / dead). Sight cone radius 12m, line-of-sight raycast. Telegraph: 0.5 sec windup before attack. Drop loot on death. May I create the scene + script?
+> I'm about to design a basic patrol-and-chase enemy with the personality + intent layer. Scene tree: Enemy (CharacterBody3D) + Vision Area3D + Sight RayCast3D + CollisionShape3D + MeshInstance3D. Script `scripts/enemy_ai.gd` with personality knobs (aggression / patience / caution / punishment), intent enum (IDLE / PATROL / INVESTIGATE / HUNT / KILL / RETREAT / RESCUE_ALLY), action SM (Calm / Alert / Aggressive / Defeated). Telegraph 0.3–0.7 sec, scaled by aggression. Drop loot on death, emit `died` signal. May I create the scene + script?
 
-### 5. Build it
+### 6. Build it
 
 **Preferred (Summer MCP):**
 
@@ -142,113 +190,180 @@ summer_set_prop(path="./World/Enemies/Enemy/Sight", key="enabled", value="true")
 summer_set_prop(path="./World/Enemies/Enemy/Sight", key="target_position", value="Vector3(0, 0, -12)")
 ```
 
-Set the vision shape to a SphereShape3D with `radius = 12`. Save as standalone `.tres` (do NOT inline sub_resource — see `_shared/mcp-tools-reference.md` § "Trap"):
+Save the Vision sphere as standalone `.tres` (do NOT inline sub_resource — see `_shared/mcp-tools-reference.md` § "Trap"):
 
 ```
-# Save shape resource externally, then:
 summer_set_prop(path="./World/Enemies/Enemy/Vision/VisionShape", key="shape", value="res://shapes/vision_sphere.tres")
 ```
 
-Connect the area signal:
+Connect signals:
 
 ```
-summer_connect_signal(from="./World/Enemies/Enemy/Vision", signal="body_entered", to="./World/Enemies/Enemy", method="_on_target_seen")
+summer_connect_signal(from="./World/Enemies/Enemy/Vision", signal="body_entered", to="./World/Enemies/Enemy", method="_on_body_entered")
 ```
 
-**Fallback (no MCP):** write the scene as `.tscn` text. Ask user to paste their existing scene first, then propose a unified diff.
+**Fallback (no MCP):** write the scene as `.tscn` text. Ask the user to paste their existing scene first, then propose a unified diff.
 
-### 6. Drop the script
+### 7. Drop the script
 
-`scripts/enemy_ai.gd` (FSM stub):
+`scripts/enemy_ai.gd`:
 
 ```gdscript
 class_name EnemyAI
 extends CharacterBody3D
 
-enum State { IDLE, ALERT, ATTACK, DEAD }
+enum State { CALM, ALERT, AGGRESSIVE, DEFEATED }
+enum Intent { IDLE, PATROL, INVESTIGATE, HUNT, KILL, RETREAT, RESCUE_ALLY }
 
+# Tuning
 @export var move_speed: float = 3.5
 @export var attack_range: float = 2.0
 @export var attack_telegraph: float = 0.5
 @export var attack_damage: int = 10
 @export var max_health: int = 30
+@export var memory_duration: float = 8.0
+
+# Personality (base, jittered at spawn)
+@export_range(0.0, 1.0) var aggression: float = 0.5
+@export_range(0.0, 1.0) var patience: float = 0.5
+@export_range(0.0, 1.0) var caution: float = 0.3
+@export_range(0.0, 1.0) var punishment: float = 0.5
+@export var personality_jitter: float = 0.15
 
 @onready var sight: RayCast3D = $Sight
 @onready var vision: Area3D = $Vision
 @onready var anim: AnimationPlayer = $AnimationPlayer
 
 signal died(position: Vector3)
+signal needs_help(who: Node3D)
+signal ally_defeated(who: Node3D)
 
-var _state: State = State.IDLE
+var _state: State = State.CALM
+var current_intent: Intent = Intent.IDLE
 var _target: Node3D = null
+var _last_seen_pos: Vector3 = Vector3.ZERO
+var _memory_timer: float = 0.0
+var _intent_timer: float = 0.0
+var _aggression_buildup: float = 0.0
+var _retreat_desire: float = 0.0
 var _health: int = 30
 
 func _ready() -> void:
     _health = max_health
+    aggression = clampf(aggression + randf_range(-personality_jitter, personality_jitter), 0.0, 1.0)
+    patience   = clampf(patience   + randf_range(-personality_jitter, personality_jitter), 0.0, 1.0)
+    caution    = clampf(caution    + randf_range(-personality_jitter, personality_jitter), 0.0, 1.0)
+    punishment = clampf(punishment + randf_range(-personality_jitter, personality_jitter), 0.0, 1.0)
     vision.body_entered.connect(_on_body_entered)
 
 func _physics_process(delta: float) -> void:
-    match _state:
-        State.IDLE:
-            _process_idle(delta)
-        State.ALERT:
-            _process_alert(delta)
-        State.ATTACK:
-            _process_attack(delta)
-        State.DEAD:
-            pass
+    if _state == State.DEFEATED:
+        return
+    _update_memory(delta)
+    _update_intent(delta)
+    _update_action(delta)
     move_and_slide()
 
-func _process_idle(_delta: float) -> void:
-    velocity = Vector3.ZERO
-    # transition handled by _on_body_entered
+# --- Intent layer (above action SM) -----------------------------------------
 
-func _process_alert(_delta: float) -> void:
-    if _target == null:
-        _change_state(State.IDLE)
-        return
-    if not _has_line_of_sight(_target):
-        _change_state(State.IDLE)
-        _target = null
-        return
-    var dir := (_target.global_position - global_position).normalized()
-    velocity = dir * move_speed
-    look_at(_target.global_position, Vector3.UP)
-    if global_position.distance_squared_to(_target.global_position) < attack_range * attack_range:
-        _change_state(State.ATTACK)
+func _update_intent(delta: float) -> void:
+    _intent_timer += delta
+    if _state == State.AGGRESSIVE:
+        _aggression_buildup += delta * (1.0 - patience) * 0.5
+    else:
+        _aggression_buildup = maxf(_aggression_buildup - delta * 0.3, 0.0)
+    _retreat_desire = maxf(_retreat_desire - delta * 0.4, 0.0)
 
-func _process_attack(_delta: float) -> void:
-    velocity = Vector3.ZERO
-    # attack handled in _change_state via async telegraph
+    var prev: Intent = current_intent
+    current_intent = _decide_intent()
+    if current_intent != prev:
+        _intent_timer = 0.0
 
-func _change_state(new_state: State) -> void:
+func _decide_intent() -> Intent:
+    if _target == null:
+        return Intent.IDLE
+    var dist: float = global_position.distance_squared_to(_target.global_position)
+    var attack_sq: float = attack_range * attack_range
+    if _retreat_desire > 0.5:
+        return Intent.RETREAT
+    if _aggression_buildup > (2.0 - aggression) and dist < attack_sq:
+        return Intent.KILL
+    if not _has_line_of_sight(_target):
+        return Intent.INVESTIGATE if _intent_timer < (4.0 + patience * 6.0) else Intent.IDLE
+    if dist < attack_sq * 4.0:
+        return Intent.HUNT
+    return Intent.HUNT
+
+# --- Action SM (reads intent) -----------------------------------------------
+
+func _update_action(delta: float) -> void:
+    match current_intent:
+        Intent.IDLE, Intent.PATROL:
+            _enter_state(State.CALM)
+            velocity = Vector3.ZERO
+        Intent.INVESTIGATE:
+            _enter_state(State.ALERT)
+            _move_toward(_last_seen_pos, delta)
+        Intent.HUNT:
+            _enter_state(State.ALERT)
+            if _target != null:
+                _move_toward(_target.global_position, delta)
+        Intent.KILL:
+            _enter_state(State.AGGRESSIVE)
+            velocity = Vector3.ZERO
+            _try_attack()
+        Intent.RETREAT:
+            _enter_state(State.ALERT)
+            if _target != null:
+                _move_toward(global_position * 2.0 - _target.global_position, delta)
+        Intent.RESCUE_ALLY:
+            _enter_state(State.ALERT)
+            # locomotion handled by ally-position lookup elsewhere
+
+func _enter_state(new_state: State) -> void:
     if _state == new_state:
         return
     _state = new_state
     match new_state:
-        State.IDLE:
+        State.CALM:
             anim.play("idle")
         State.ALERT:
             anim.play("alert")
-        State.ATTACK:
-            _execute_attack()
-        State.DEAD:
+        State.AGGRESSIVE:
+            anim.play("ready")
+        State.DEFEATED:
             anim.play("death")
             died.emit(global_position)
-            await get_tree().create_timer(2.0).timeout
-            queue_free()
+            ally_defeated.emit(self)
+
+# --- Helpers ----------------------------------------------------------------
+
+func _move_toward(target_pos: Vector3, _delta: float) -> void:
+    var dir: Vector3 = (target_pos - global_position).normalized()
+    velocity = dir * move_speed
+    look_at(target_pos, Vector3.UP)
 
-func _execute_attack() -> void:
+func _try_attack() -> void:
+    if _state != State.AGGRESSIVE or _target == null:
+        return
     anim.play("attack_windup")
-    await get_tree().create_timer(attack_telegraph).timeout
-    if _state != State.ATTACK or _target == null:
+    var windup: float = maxf(0.25, attack_telegraph * (1.5 - aggression))
+    await get_tree().create_timer(windup).timeout
+    if _state != State.AGGRESSIVE or _target == null:
         return
-    if global_position.distance_squared_to(_target.global_position) < (attack_range * 1.2) ** 2:
+    if global_position.distance_squared_to(_target.global_position) < (attack_range * 1.2) * (attack_range * 1.2):
         if _target.has_method("take_damage"):
             _target.take_damage(attack_damage)
     anim.play("attack_recover")
-    await anim.animation_finished
-    _change_state(State.ALERT)
+
+func _update_memory(delta: float) -> void:
+    if _target != null and _has_line_of_sight(_target):
+        _last_seen_pos = _target.global_position
+        _memory_timer = memory_duration
+    else:
+        _memory_timer = maxf(_memory_timer - delta, 0.0)
+        if _memory_timer <= 0.0:
+            _target = null
 
 func _has_line_of_sight(target: Node3D) -> bool:
     sight.target_position = sight.to_local(target.global_position)
@@ -258,26 +373,49 @@ func _has_line_of_sight(target: Node3D) -> bool:
     return sight.get_collider() == target
 
 func _on_body_entered(body: Node3D) -> void:
-    if body.is_in_group("player") and _state == State.IDLE:
+    if body.is_in_group("player") and _state == State.CALM:
         _target = body
-        _change_state(State.ALERT)
+        _last_seen_pos = body.global_position
+        _memory_timer = memory_duration
 
 func take_damage(amount: int) -> void:
-    if _state == State.DEAD:
+    if _state == State.DEFEATED:
         return
     _health -= amount
+    var hp_ratio: float = float(_health) / float(max_health)
+    if randf() < caution * (1.0 - hp_ratio):
+        _retreat_desire = 1.0
     if _health <= 0:
-        _change_state(State.DEAD)
+        _enter_state(State.DEFEATED)
+        await get_tree().create_timer(2.0).timeout
+        queue_free()
 ```
 
 Key design notes embedded above:
-- Telegraph (`attack_telegraph`) is a parameter — designers can tune feel.
-- `take_damage` is the public hook the player's weapon calls.
-- `died` signal is the gameplay-layer hook (loot, score, quest progress).
-- `distance_squared_to` for comparisons (no sqrt cost).
-- LOS check uses `force_raycast_update` for one-shot precision.
+- `aggression`, `patience`, `caution`, `punishment` are tuned per-archetype and jittered per-instance.
+- Intent SM (`_update_intent` / `_decide_intent`) sits above the action SM (`_update_action`).
+- Action SM reads `current_intent`. It does not write intent.
+- Telegraph length scales with aggression — angrier NPCs swing faster.
+- Damage triggers a `caution * (1 - hp_ratio)` chance to set `_retreat_desire`, so cautious + hurt = back off.
+- `died` signal is the gameplay-layer hook; `ally_defeated` is the squad hook.
 
-### 7. Verify
+### 8. Tunable matrices — concrete ranges per archetype
+
+These are the *base* values; the spawn-time `personality_jitter` (default 0.15) widens them further.
+
+| Archetype | aggression | patience | caution | punishment | Notes |
+|---|---|---|---|---|---|
+| `basic_grunt` | 0.5–0.7 | 0.3–0.5 | 0.2–0.4 | 0.4–0.6 | Wants to engage; not too smart |
+| `ranged_skirmisher` | 0.3–0.5 | 0.5–0.7 | 0.6–0.8 | 0.5–0.7 | Kites, breaks LOS, punishes reload |
+| `heavy_brute` | 0.7–0.9 | 0.2–0.4 | 0.1–0.3 | 0.6–0.8 | Closes fast, low retreat |
+| `boss` | 0.7–0.9 | 0.7–0.9 | 0.5–0.7 | 0.8–1.0 | Patient, punishing, never panics |
+| `wave_mob` | 0.9–1.0 | 0.0–0.1 | 0.0 | 0.0 | Single intent: KILL |
+| `civilian` | 0.0 | 0.8–1.0 | 0.7–0.9 | 0.0 | Retreat-only |
+| `companion` | 0.4–0.6 | 0.6–0.8 | 0.5–0.7 | 0.3–0.5 | Supports, doesn't over-commit |
+
+Set base values via `@export` in the scene's inspector, not hard-coded in script. That keeps the same `enemy_ai.gd` reusable across archetypes.
+
+### 9. Verify
 
 ```
 summer_save_scene
@@ -291,28 +429,34 @@ If the enemy doesn't aggro, common causes:
 - Player isn't in `player` group.
 - Vision Area3D's sphere shape is inline sub_resource (silent fail).
 - Sight RayCast3D `enabled = false` or `collide_with_areas = true` blocking on its own Vision area.
+- Personality jitter pushed `aggression` close to 0 — check inspector values.
 
 ## Common mistakes
 
 | Don't | Do | Why |
 |---|---|---|
 | 360° perception | Sight cone or sphere with raycast LOS | "Sees through walls" feels unfair |
-| Instant attack | 0.3–0.7 sec telegraph | Player needs to read the swing |
-| Behavior tree for a grunt | State machine with 4 states | BT overhead unjustified at low complexity |
-| Per-frame `get_tree().get_first_node_in_group("player")` | Cache target on aggro | Tree walks aren't free |
+| Instant attack | 0.3–0.7 sec telegraph, scaled by aggression | Player needs to read the swing |
+| All NPCs identical at spawn | Jitter personality knobs in `_ready` | Identical NPCs are predictable; predictable is boring |
+| Action SM writes intent | Intent layer writes intent, action reads | Tangled SMs are unmaintainable |
+| One enum for action + intent | Two enums, two SMs | Different time scales, different inputs |
+| Hard-coded role per spawn ("this is the sniper") | Let personality variation produce roles | Squad emergence comes for free; authored roles fight the system |
+| Behavior tree for a grunt | Action SM with 4 states + intent layer | BT overhead unjustified at this complexity |
+| Per-frame group lookup | Cache target on aggro, listen for `ally_defeated` | Tree walks aren't free |
 | `distance_to` in `_physics_process` | `distance_squared_to` for comparisons | Square root costs at scale |
-| Same animation in all states | Distinct animations per state | The state machine is invisible; animations make it visible |
+| Same animation in all states | Distinct anim per action state | The state machine is invisible; animation makes it visible |
 | `queue_free()` instantly on death | Death anim → 2 sec → free | Instant despawn breaks immersion + skips loot drops |
 | Inline SphereShape3D for Vision Area3D | Standalone `.tres` | Inline sub_resources break SetResourceProperty |
-| 100+ enemies with full FSM | Wave-mob archetype (2 states, no LOS) | Cheap mobs need cheap brains |
-| No `died` signal | Emit on death | Gameplay layer needs the hook |
+| 100+ enemies with full FSM | Wave-mob archetype (no intent layer, single KILL intent) | Cheap mobs need cheap brains |
+| No `died` / `ally_defeated` signals | Emit both | Gameplay + squad logic both need hooks |
 
 ## Anti-patterns
 
-- **"AI that dodges everything."** Enemies that 100% dodge feel cheap. Random reaction time (50–250 ms) reads as skill, not aimbot.
+- **"AI that dodges everything."** Enemies that 100% dodge feel cheap. A `caution` knob plus randomized reaction time (50–250 ms) reads as skill, not aimbot.
 - **Boss with 12 unique mechanics.** Cap at 4–6 distinct mechanics across phases. Players can't track more.
 - **Companion that walks through doors.** NavigationAgent3D with proper navmesh. Don't fake it with raw `move_toward`.
 - **Civilian that screams forever.** Add a calm-down state on a 5–10 sec timer.
+- **Setting `current_intent` from inside an action callback.** Intent is computed by the intent layer from inputs (perception + personality + group). Letting action callbacks write intent inverts the architecture.
 
 ## Collaborative protocol
 
@@ -323,9 +467,7 @@ This skill writes scenes and scripts. Always ask before each step. Group related
 For a fully-rigged enemy with anim controller + loot drop:
 
 → **template-id**: `template-3d-fps` — ships with a sample patrol enemy
-→ **Repo**: https://github.com/SummerEngine/FPS-template-Summer-Engine
-
-For higher-complexity AI (boss with phases, behavior trees), defer to `ai-and-npcs/behavior-trees/SKILL.md`.
+→ For higher-complexity AI (boss with phases, behavior trees), defer to `ai-and-npcs/behavior-trees/SKILL.md`.
 
 ## See also
 

package/skills/asset-pipeline/asset-strategy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: asset-strategy
-description: Decision guide for how to create different game asset types — generated 3D, library search, AI textures, or primitives. Use when planning asset creation, picking an asset pipeline, or writing image-to-3D prompts. Trigger on "assets", "3D models", "textures", "art pipeline".
+description: Use when planning asset creation, picking an asset pipeline, or writing image-to-3D prompts — decision guide for whether to generate 3D, search the library, generate AI textures, or use primitives. Includes prompt templates for the AI image-to-3D pipeline. Trigger on "assets", "3D models", "textures", "art pipeline", "make a model", "generate asset".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: asset-pipeline

package/skills/catalog.yaml

@@ -146,6 +146,20 @@ skills:
     recommended: true
     user-invocable: true
     last-tested: 2026-05-05
+  - name: new-project
+    category: scene-and-project
+    status: HAVE
+    public: true
+    recommended: true
+    user-invocable: true
+    last-tested: 2026-05-09
+  - name: browse-templates
+    category: scene-and-project
+    status: HAVE
+    public: true
+    recommended: true
+    user-invocable: true
+    last-tested: 2026-05-09
   - name: scene-composition
     category: scene-and-project
     status: HAVE
@@ -163,8 +177,9 @@ skills:
     category: scene-and-project
     status: HAVE
     public: true
-    recommended: false
-    last-tested: 2026-05-05
+    recommended: true
+    user-invocable: true
+    last-tested: 2026-05-09
   - name: godot-project-conventions
     category: scene-and-project
     status: NEXT
@@ -437,16 +452,18 @@ skills:
     last-tested: 2026-05-05
   - name: peer-to-peer-multiplayer
     category: multiplayer-and-networking
-    status: NEXT
+    status: HAVE
     public: true
     recommended: true
     user-invocable: true
+    last-tested: 2026-05-05
   - name: host-authoritative-state
     category: multiplayer-and-networking
-    status: NEXT
+    status: HAVE
     public: true
     recommended: true
     user-invocable: true
+    last-tested: 2026-05-05
   - name: multiplayerapi-basics
     category: multiplayer-and-networking
     status: NEXT