summer-engine 1.3.0 → 1.3.2

package/skills/_tests/specs/vfx.md

@@ -0,0 +1,98 @@
+# Skill Spec: /vfx
+
+## Fixture
+
+- Godot 4.5 / Summer Engine project, main scene with `World/Player` (CharacterBody3D + Camera3D) and `World/Enemy` (CharacterBody3D + MeshInstance3D + a `damaged` signal on a script).
+- Summer MCP tools available (engine running on localhost:6550).
+- Host file tools available (Read, Edit, Write).
+
+## Case 1: Happy Path — combat hits feel flat
+
+**Input:** "My combat feels flat. Add some juice."
+
+**Expected behavior:**
+
+1. Skill asks one focused question: "What feels flat? combat hits / movement / pickups / damage / explosions / spell casts."
+2. User says "combat hits".
+3. Skill calls `summer_get_scene_tree`, then `summer_inspect_node "./World/Enemy"` to confirm a MeshInstance3D and a `damaged` signal exist.
+4. Skill proposes hit flash + camera shake bundle: "I'm about to add HitFlash on `./World/Enemy`, attach `scripts/hit_flash.gd`, attach `scripts/camera_shake.gd` to `./World/Player/Camera3D`, and connect the `damaged` signal. OK?"
+5. After user OK:
+   - `summer_add_node(parent="./World/Enemy", type="Node", name="HitFlash")`
+   - `Write scripts/hit_flash.gd`
+   - `Write scripts/camera_shake.gd`
+   - `summer_connect_signal(from="./World/Enemy", signal="damaged", to="./World/Enemy/HitFlash", method="flash")`
+   - `summer_save_scene`
+   - `summer_get_script_errors`
+
+**Assertions:**
+
+- [ ] Skill asks the "what feels flat?" question before any tool call.
+- [ ] Skill reads the scene tree and inspects the relevant node before adding nodes.
+- [ ] Skill explicitly states the bundle of changes and asks "May I" / "OK?" before mutation.
+- [ ] HitFlash script uses Tween + `set_surface_override_material`, NOT a polled timer in `_process`.
+- [ ] CameraShake uses quadratic falloff (`_trauma * _trauma`), NOT linear.
+- [ ] Skill never calls `summer_set_resource_property` on an inline sub_resource (e.g. ParticleProcessMaterial).
+- [ ] Skill ends with `summer_save_scene` then `summer_get_script_errors`.
+- [ ] Final hit flash duration is 0.06–0.12 sec (NOT 0.3 sec).
+
+## Case 2: Failure Path — no Camera3D in scene
+
+**Fixture:** `World/Player` exists but has no Camera3D child. User asks for screen shake.
+
+**Input:** "Add screen shake when I take damage."
+
+**Expected behavior:**
+
+- Skill calls `summer_get_scene_tree` and `summer_inspect_node "./World/Player"`, sees no Camera3D.
+- Skill does NOT silently spawn a Camera3D — it asks: "I don't see a Camera3D under `./World/Player`. Should I add one (and risk conflicting with an existing camera elsewhere), or do you have a camera node I should target?"
+- Waits for the answer.
+
+**Assertions:**
+
+- [ ] Skill detects the missing Camera3D and stops to ask.
+- [ ] Skill does NOT add a Camera3D unilaterally.
+- [ ] Skill names a concrete next-step path (point to existing camera OR add new one explicitly).
+
+## Case 3: Edge Case — user wants "all the juice"
+
+**Fixture:** Same as Case 1.
+
+**Input:** "Add all the VFX. Make it feel like Hades."
+
+**Expected behavior:**
+
+- Skill resists the temptation to stack 5 recipes at once.
+- Anchors on combat hits first (per skill's own guidance: "loudest perceived improvement per minute spent").
+- Says: "I'd rather land hit-flash + screen-shake first so we can see them work, then stack pickups/explosions next. Sound good?"
+- Does NOT propose a single bundle of 5 recipes.
+
+**Assertions:**
+
+- [ ] Skill explicitly chooses ONE recipe to start with, not all.
+- [ ] Skill names "combat hits" as the anchor.
+- [ ] Skill defers other recipes to a follow-up pass.
+
+## Case 4: No Summer MCP — file-edit fallback
+
+**Fixture:** Same as Case 1, but Summer MCP is unavailable (Cursor in a project where the engine is not connected).
+
+**Input:** "Add a hit flash to my enemy."
+
+**Expected behavior:**
+
+- Skill detects MCP unavailable.
+- Asks the user to paste the relevant `.tscn` snippet (the Enemy node + its children) so the skill can write the right node-path references.
+- Writes `scripts/hit_flash.gd` directly via host file tools.
+- Provides a `.tscn` patch (or step-by-step manual editor instructions) for adding the HitFlash node and connecting the signal — does NOT blindly call `summer_*` tools.
+- Still asks "May I write `scripts/hit_flash.gd`?" before each file write.
+
+**Assertions:**
+
+- [ ] Skill identifies MCP is unavailable and adapts.
+- [ ] Generated GDScript is syntactically valid Godot 4 GDScript with type hints.
+- [ ] Skill asks the user to paste the `.tscn` snippet for accurate node paths.
+- [ ] Skill still applies the "May I write …" protocol on file writes.
+
+---
+
+This spec runs via `/skill-test vfx spec` (see `_meta/skill-test/SKILL.md`).

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

@@ -0,0 +1,343 @@
+---
+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".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: ai-and-npcs
+user-invocable: true
+allowed-tools: Read Grep Edit Write summer_get_scene_tree summer_inspect_node summer_add_node summer_set_prop summer_set_resource_property summer_connect_signal summer_save_scene summer_get_script_errors summer_input_map_bind
+paths: ["**/*.gd", "**/*.tscn"]
+---
+
+# /design-npc — Design an NPC's Behavior End-to-End
+
+## 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.
+
+**Core principle:** behavior is what the player *sees*, not what the code does. Every state needs a tell.
+
+## Steps
+
+### 1. Pick the NPC archetype
+
+Open with the question. Wait.
+
+> What's the NPC for? Pick the closest:
+> - **Basic enemy** (melee/ranged grunt, dies in 1–3 hits)
+> - **Boss** (named, scripted phases, 30–120 sec fight)
+> - **Quest-giver** (talks, gives objectives, doesn't fight)
+> - **Friendly companion** (follows player, helps in combat)
+> - **Civilian / ambient** (reacts to events, no combat AI)
+> - **Wave-spawned mob** (cheap, many at once, simple behavior)
+
+Each archetype maps to a different complexity budget:
+
+| Archetype | States | Perception | Decision logic | Tells per state |
+|---|---|---|---|---|
+| 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 |
+
+### 2. Sketch the four design pillars
+
+Walk them in order. Don't skip.
+
+#### a) Perception — what does this NPC *sense*?
+
+Pick the minimum. Over-perception = unfair AI. Common sensors:
+
+| 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 |
+
+Recommended setup for a basic enemy:
+
+```
+Enemy (CharacterBody3D)
+├── MeshInstance3D
+├── CollisionShape3D
+├── Vision (Area3D)        # sphere shape, radius = sight range
+│   └── CollisionShape3D
+└── Sight (RayCast3D)      # confirms line-of-sight when target in Vision area
+```
+
+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.
+
+#### b) Decision logic — state machine vs behavior tree
+
+**Strong recommendation:** start with a state machine. Always.
+
+| | State machine | Behavior tree |
+|---|---|---|
+| 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 |
+
+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).
+
+For everything else: FSM. See `scripting-patterns/state-machine-patterns/SKILL.md`.
+
+#### c) Escalation — tells per state
+
+Every state must have at least one *tell* the player can read. List them up front:
+
+| 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 |
+
+**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".
+
+#### d) Defeat handling — 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.
+
+### 3. 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.
+
+### 4. 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?
+
+### 5. Build it
+
+**Preferred (Summer MCP):**
+
+```
+summer_add_node(parent="./World/Enemies", type="CharacterBody3D", name="Enemy")
+summer_add_node(parent="./World/Enemies/Enemy", type="CollisionShape3D", name="Body")
+summer_add_node(parent="./World/Enemies/Enemy", type="MeshInstance3D", name="Mesh")
+summer_add_node(parent="./World/Enemies/Enemy", type="Area3D", name="Vision")
+summer_add_node(parent="./World/Enemies/Enemy/Vision", type="CollisionShape3D", name="VisionShape")
+summer_add_node(parent="./World/Enemies/Enemy", type="RayCast3D", name="Sight")
+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 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:
+
+```
+summer_connect_signal(from="./World/Enemies/Enemy/Vision", signal="body_entered", to="./World/Enemies/Enemy", method="_on_target_seen")
+```
+
+**Fallback (no MCP):** write the scene as `.tscn` text. Ask user to paste their existing scene first, then propose a unified diff.
+
+### 6. Drop the script
+
+`scripts/enemy_ai.gd` (FSM stub):
+
+```gdscript
+class_name EnemyAI
+extends CharacterBody3D
+
+enum State { IDLE, ALERT, ATTACK, DEAD }
+
+@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
+
+@onready var sight: RayCast3D = $Sight
+@onready var vision: Area3D = $Vision
+@onready var anim: AnimationPlayer = $AnimationPlayer
+
+signal died(position: Vector3)
+
+var _state: State = State.IDLE
+var _target: Node3D = null
+var _health: int = 30
+
+func _ready() -> void:
+    _health = max_health
+    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
+    move_and_slide()
+
+func _process_idle(_delta: float) -> void:
+    velocity = Vector3.ZERO
+    # transition handled by _on_body_entered
+
+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 _process_attack(_delta: float) -> void:
+    velocity = Vector3.ZERO
+    # attack handled in _change_state via async telegraph
+
+func _change_state(new_state: State) -> void:
+    if _state == new_state:
+        return
+    _state = new_state
+    match new_state:
+        State.IDLE:
+            anim.play("idle")
+        State.ALERT:
+            anim.play("alert")
+        State.ATTACK:
+            _execute_attack()
+        State.DEAD:
+            anim.play("death")
+            died.emit(global_position)
+            await get_tree().create_timer(2.0).timeout
+            queue_free()
+
+func _execute_attack() -> void:
+    anim.play("attack_windup")
+    await get_tree().create_timer(attack_telegraph).timeout
+    if _state != State.ATTACK or _target == null:
+        return
+    if global_position.distance_squared_to(_target.global_position) < (attack_range * 1.2) ** 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 _has_line_of_sight(target: Node3D) -> bool:
+    sight.target_position = sight.to_local(target.global_position)
+    sight.force_raycast_update()
+    if not sight.is_colliding():
+        return true
+    return sight.get_collider() == target
+
+func _on_body_entered(body: Node3D) -> void:
+    if body.is_in_group("player") and _state == State.IDLE:
+        _target = body
+        _change_state(State.ALERT)
+
+func take_damage(amount: int) -> void:
+    if _state == State.DEAD:
+        return
+    _health -= amount
+    if _health <= 0:
+        _change_state(State.DEAD)
+```
+
+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.
+
+### 7. Verify
+
+```
+summer_save_scene
+summer_get_script_errors
+summer_play
+# user tests
+summer_stop
+```
+
+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.
+
+## 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 |
+| `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 |
+| `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 |
+
+## Anti-patterns
+
+- **"AI that dodges everything."** Enemies that 100% dodge feel cheap. Random 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.
+
+## Collaborative protocol
+
+This skill writes scenes and scripts. Always ask before each step. Group related writes into one ask. See `_shared/collaborative-protocol.md`.
+
+## Want a working starter?
+
+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`.
+
+## See also
+
+- `_shared/mcp-tools-reference.md` — full MCP tool list
+- `_shared/godot-version.md` — Godot 4.5 API notes
+- `_shared/collaborative-protocol.md` — "May I write" pattern
+- `_shared/gd-style.md` — typed GDScript conventions
+- `ai-and-npcs/state-machine-npc/SKILL.md` — FSM pattern deep dive
+- `ai-and-npcs/behavior-trees/SKILL.md` — when complexity demands a BT
+- `ai-and-npcs/perception-sight-and-hearing/SKILL.md` — sensor patterns
+- `ai-and-npcs/navmesh-pathfinding/SKILL.md` — NavigationAgent3D for movement
+- `ai-and-npcs/llm-driven-dialogue/SKILL.md` — Summer's wedge for talking NPCs
+- `ai-and-npcs/boss-patterns/SKILL.md` — phase transitions, mechanics
+- `visual-effects/vfx/SKILL.md` — hit flash and death VFX recipes
+- `scripting-patterns/state-machine-patterns/SKILL.md` — generic FSM patterns

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

@@ -4,6 +4,7 @@ description: Decision guide for how to create different game asset types — gen
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: asset-pipeline
+user-invocable: false
 allowed-tools: Read Grep summer_search_assets summer_import_asset summer_generate_image summer_generate_3d summer_generate_audio summer_import_from_url
 ---