summer-engine 1.5.0 → 2.2.0

package/skills/3d-assets/prop-model/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: prop-model
+description: Use when generating a single static 3D prop — sword, barrel, chest, lantern, throne, statue, crate, key, potion, banner. One isolated object, no rigging, wired into the scene as a MeshInstance3D. Trigger on "make a sword", "generate a chest", "I need a barrel", "add a lantern model", "give me a treasure prop", "create a statue".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: 3d-assets
+user-invocable: true
+allowed-tools: Read Grep summer_search_assets summer_generate_3d summer_generate_image summer_import_from_url summer_add_node summer_set_prop summer_inspect_node summer_get_scene_tree summer_save_scene
+paths: ["assets/models/**", "**/*.tscn", "**/*.gd"]
+---
+
+# Prop Model — Generate One Static 3D Prop and Wire It
+
+One prop, one mesh, one MeshInstance3D. This is the bread-and-butter call of the 3D-asset family — most game-world objects are static props. The skill exists to keep two things tight: the **prompt shape** that produces a clean isolated mesh on the first try, and the **wire-in pattern** that gets the asset into the scene without leaving orphans in `res://assets/models/`.
+
+The backing tool is `summer_generate_3d`. Default model is `hunyuan` (Hunyuan 3D v3.1 Pro — best quality). Use `trellis` when speed matters (Trellis 2 is ~2× faster, slightly lower fidelity). `meshy` is the legacy fallback — only pick it if the user asks by name.
+
+## When to use
+
+- "Make me a treasure chest."
+- "Generate a viking axe."
+- "I need a wooden barrel for the cellar."
+- "Create a sci-fi crate."
+- Any single, static, non-character, non-modular object the player will see in 3D space.
+
+## When NOT to use
+
+- Character / humanoid → `summer:3d-assets/character-model` (needs T-pose + rig pass).
+- A set of matching pieces (walls, floors, doors, pillars) → `summer:3d-assets/environment-kit` (style-locked family).
+- Trees, rocks, foliage → `summer:3d-assets/organic-model` (organic forgives AI artifacts; cheaper recipe).
+- Cars, ships, mechs → `summer:3d-assets/vehicle-model` (hard-surface specifics).
+- Walls / floors / repeating geometry → `summer:asset-pipeline/asset-strategy` Pipeline 2 (textures + CSG).
+- "I just need a placeholder" → propose a primitive (`BoxMesh` / `CylinderMesh`) instead. Generation is metered.
+
+## Steps
+
+### 1. Search before generating
+
+```
+summer_search_assets(query="<prop name>", filter={ kind: "model" })
+```
+
+If a fitting model exists, propose reuse:
+
+> Found `assets/models/treasure_chest_01.glb`. Reuse this, or generate fresh?
+
+### 2. Pick a polycount target
+
+| Use case | Tris | Pass via |
+|---|---|---|
+| Hero prop (sword on hip, key item) | 3k–8k | `options: { target_polycount: 5000 }` |
+| Background prop (crate, barrel, sack) | 200–800 | `options: { target_polycount: 600 }` |
+| Mid-range interactive (chest, lantern) | 1k–3k | `options: { target_polycount: 2000 }` |
+| Cinematic showcase (throne, statue) | 10k–30k | `options: { target_polycount: 20000 }` |
+
+Default if you don't pass it: provider picks (~10k–30k). For most game-world props, that's overkill — pass a target.
+
+### 3. Build the prompt
+
+Pattern: `<object> + <material> + <silhouette/details> + isolated-object suffix`.
+
+| Goal | Prompt that works |
+|---|---|
+| Treasure chest | `A wooden treasure chest with iron bands and a heavy padlock, lid slightly ajar, gold coins spilling. Game asset, centered, stylized, white background, isolated object.` |
+| Viking axe | `A two-handed viking battle axe, weathered iron head with rune etchings, leather-wrapped wooden haft. Game asset, centered, stylized, white background, isolated object.` |
+| Lantern | `A medieval brass lantern with stained glass panels and a hooked handle, candle inside. Game asset, centered, stylized, white background, isolated object.` |
+| Throne | `An ornate stone throne carved with serpent motifs, red velvet cushion, tall pointed back. Game asset, centered, stylized, white background, isolated object.` |
+| Sci-fi crate | `A weathered sci-fi cargo crate, metal panels with yellow hazard stripes, recessed handles. Game asset, centered, stylized, white background, isolated object.` |
+| Potion bottle | `A glass potion bottle with a cork stopper, glowing purple liquid inside, leather strap around the neck. Game asset, centered, stylized, white background, isolated object.` |
+
+The `isolated object` and `white background` clauses are load-bearing — without them you get scene context (table, ground plane) baked into the mesh.
+
+### 4. Confirm and call
+
+> About to generate `viking_axe` via `hunyuan`, target ~5k tris. ~$0.50, ~60s. OK?
+
+```
+summer_generate_3d(
+  prompt="A two-handed viking battle axe, weathered iron head with rune etchings, leather-wrapped wooden haft. Game asset, centered, stylized, white background, isolated object.",
+  model="hunyuan",
+  options={ target_polycount: 5000 },
+  wait=true
+)
+```
+
+Returns `{ asset: { fileUrl }, ... }`.
+
+### 5. Import and wire
+
+```
+summer_import_from_url(url="<fileUrl>", path="res://assets/models/viking_axe.glb")
+summer_add_node(parent="./World/Props", type="MeshInstance3D", name="VikingAxe")
+summer_set_prop(path="./World/Props/VikingAxe", property="mesh", value="res://assets/models/viking_axe.glb")
+summer_save_scene
+```
+
+For interactive props (chest the player opens, lantern the player picks up), wrap the MeshInstance3D in a `StaticBody3D` (or `RigidBody3D` for physics props) with a `CollisionShape3D` sibling — see `summer:scene-composition` for the parent-shape pattern.
+
+## Anti-patterns
+
+- **Scene context in the prompt.** "A sword lying on a wooden table" → the table becomes geometry. Always say `isolated object`.
+- **Multi-object prompts.** "A sword and a shield" → fused single mesh. Generate separately.
+- **Skipping `target_polycount` for background props.** A 30k-tri barrel in the background tanks frame rate when the level has 50 of them.
+- **Forgetting to import.** `fileUrl` from `summer_generate_3d` is a remote URL — you MUST `summer_import_from_url` before referencing it as `res://...`.
+- **Generating before searching.** Reuse beats regenerate every time.
+- **Picking `meshy` by default.** It's legacy. `hunyuan` is better; `trellis` is faster.
+
+## Edge cases
+
+- **Transparent objects (glass, ice, gem).** AI 3D gen makes these opaque. Generate the mesh, then assign a `StandardMaterial3D` with `transparency = ALPHA` and a low `albedo_color.a` in the editor.
+- **Long thin props (spear, staff, banner pole).** Hunyuan sometimes thickens the shaft. Trellis handles thin geometry better — try it as the second attempt.
+- **Concave interior (open chest, hollow vase).** Specify "lid open" or "hollow inside" — Hunyuan defaults to closed solids.
+- **Symmetrical prop comes back asymmetric.** Add `symmetric, mirrored` to the prompt and regenerate.
+
+## Fallback (no MCP)
+
+The user can run the same prompt at the Summer dashboard (or directly via the Hunyuan / Trellis web UIs), download the `.glb`, drop it into `res://assets/models/`, and Godot's import dock will pick it up. Then add a MeshInstance3D manually in the Godot editor and assign the mesh.
+
+## Handoff
+
+After the prop is wired:
+
+> `viking_axe.glb` imported and placed at `./World/Props/VikingAxe`. Next:
+> - For physics (player can knock it over), wrap in `RigidBody3D` + `CollisionShape3D` — see `summer:scene-composition`.
+> - For pickup interaction, see `summer:design-mechanic` for the pickup pattern.
+> - For matching props in the same style (chest → barrel → crate as a treasure-room kit), use `summer:3d-assets/environment-kit` with this prop as the style anchor.
+
+## See also
+
+- `summer:asset-pipeline/asset-strategy` — the meta-router that decides between this skill and Pipeline 2 (textures).
+- `summer:3d-assets/character-model` — for humanoids.
+- `summer:3d-assets/environment-kit` — for style-locked sets.
+- `_shared/mcp-tools-reference.md` — `summer_generate_3d` parameter schema.

package/skills/3d-assets/vehicle-model/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: vehicle-model
+description: Use when generating a hard-surface vehicle — car, motorcycle, spaceship, hover bike, boat, mech, tank, helicopter. Static mesh, optional secondary detail-texture pass, wired as Vehicle3D (player-driven) or MeshInstance3D (background). Trigger on "make a car", "spaceship model", "generate a mech", "I need a vehicle", "hover bike", "tank model", "racing car".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: 3d-assets
+user-invocable: true
+allowed-tools: Read Grep summer_search_assets summer_generate_3d summer_generate_image summer_import_from_url summer_add_node summer_set_prop summer_inspect_node summer_inspect_resource summer_get_scene_tree summer_save_scene
+paths: ["assets/vehicles/**", "assets/models/**", "**/*.tscn", "**/*.gd"]
+---
+
+# Vehicle Model — Hard-Surface 3D Generation
+
+Vehicles are the hardest 3D-gen category. Hard surfaces (flat panels, sharp edges, symmetrical bodies) expose every flaw the AI mesher has — smoothing-group artifacts on flat panels, asymmetric headlights, melted door seams. This skill exists to push the success rate up by giving the model **multi-angle reference**, picking the right backend, and using a **secondary detail-texture pass** to recover crispness on the body panels.
+
+Backing tool: `summer_generate_3d`. Default model is `hunyuan` (best general quality). For pure hard-surface (clean spaceship, F1 car), try `trellis` first — it tends to preserve panel edges better.
+
+## When to use
+
+- "Make me a player car for a racing game."
+- "Generate a sci-fi fighter spaceship."
+- "I need a hover bike for the desert level."
+- "Create a mech for the boss fight."
+- "Background traffic — generate three civilian sedans."
+
+## When NOT to use
+
+- Character driving the vehicle → that's `summer:3d-assets/character-model`. Generate them separately and parent the character to the vehicle's seat.
+- Vehicle interior (cockpit, dashboard) as a first-person view → generate as a separate "interior" prop via `summer:3d-assets/prop-model` with first-person framing.
+- A scenery vehicle that never moves and is far from camera (parked truck in the distance) → `summer:3d-assets/prop-model` is fine; vehicle-model's overhead isn't worth it.
+- Procedural / customizable vehicles (modular ship parts) → use `summer:3d-assets/environment-kit` to generate a vehicle-parts kit instead.
+
+## Polycount targets
+
+| Use case | Tris | Pass via |
+|---|---|---|
+| Player vehicle (close camera, lots of screen time) | 15k–30k | `target_polycount: 25000` |
+| Hero showpiece (cinematic, garage view) | 30k–60k | `target_polycount: 50000` |
+| Background traffic (mid-range, multiple onscreen) | 2k–5k | `target_polycount: 4000` |
+| Distant flyby / parked scenery | 1k–2k | `target_polycount: 1500` |
+
+Vehicles benefit more from polycount than props — flat panels need edge density to look right. Don't go below 2k for anything the camera will get close to.
+
+## Multi-angle reference — the single biggest quality lever
+
+Vehicles are highly view-dependent. A front-only reference produces a mesh with great front detail and a melted rear. The fix: generate a **front + 3/4 side composite reference** before the 3D pass.
+
+```
+summer_generate_image(
+  prompt="A sleek red sports car, front view AND 3/4 rear-side view side by side, two angles in one image, white background, studio lighting, clean references for 3D modeling, isolated, no scenery."
+)
+```
+
+Most image models will produce a two-view composite. Then feed it to image-to-3D:
+
+```
+summer_generate_3d(
+  kind="image-to-3d",
+  imageUrl="<composite reference url>",
+  model="hunyuan",
+  options={ target_polycount: 25000 }
+)
+```
+
+If the user has reference images already (concept art, photos), prefer those — composite them into a single image first if they aren't already.
+
+## Steps
+
+### 1. Search before generating
+
+```
+summer_search_assets(query="<vehicle type>", filter={ kind: "model" })
+```
+
+### 2. Pick model and polycount
+
+For hard-edged vehicles (spaceships, F1, mechs), try `trellis` first — sharper panel edges. For organic-curved vehicles (muscle cars, motorcycles, classic boats), `hunyuan` handles the curves better.
+
+### 3. Build the prompt
+
+Pattern: `<vehicle type> + <silhouette / era / style> + <materials> + <surface state> + isolated suffix`.
+
+| Goal | Prompt that works |
+|---|---|
+| Player race car | `A sleek modern Formula 1 race car, aerodynamic carbon-fiber bodywork, large rear wing, exposed wheels, racing livery in red and white. Front and 3/4 side views. Game asset, stylized, clean white background, isolated vehicle.` |
+| Sci-fi fighter | `A sleek single-seat sci-fi space fighter, swept-forward wings, twin engine nacelles, glass cockpit canopy, painted matte gray with cyan trim. Front and 3/4 side views. Game asset, stylized hard-surface, white background, isolated vehicle.` |
+| Hover bike | `A rusted desert hover bike, exposed engine block, single seat, handlebars, no wheels (hover thrusters underneath), weathered orange paint. Front and 3/4 side views. Game asset, stylized, white background, isolated vehicle.` |
+| Mech | `A 4 meter tall bipedal combat mech, blocky armored torso, articulated arms with rifle and missile pod, thick legs with hydraulic pistons, painted olive drab with hazard stripes. Front and 3/4 side views. Game asset, hard-surface stylized, white background, isolated vehicle.` |
+| Background sedan | `A generic 90s civilian sedan, four doors, beige paint, slightly worn. Front and 3/4 side views. Game asset, low-detail stylized, white background, isolated vehicle.` |
+
+The phrase `front and 3/4 side views` is what triggers the multi-angle composite reference internally.
+
+### 4. Confirm and call
+
+> About to generate `red_race_car` via `hunyuan`, target ~25k tris, multi-angle ref. ~$0.60, ~90s. OK?
+
+```
+summer_generate_3d(
+  prompt="A sleek modern Formula 1 race car, ...",
+  model="hunyuan",
+  options={ target_polycount: 25000 },
+  wait=true
+)
+summer_import_from_url(url="<fileUrl>", path="res://assets/vehicles/race_car.glb")
+```
+
+### 5. Inspect for hard-surface artifacts
+
+```
+summer_inspect_resource(path="res://assets/vehicles/race_car.glb")
+```
+
+Open the import preview. Look for:
+- **Smoothing-group artifacts on flat panels** (visible as banding under light) → fix in step 6 with a detail texture, or re-import with `Generate Tangents = on` and a custom shader.
+- **Asymmetric headlights / wheels** → regenerate with `symmetric, mirrored bilateral` added to the prompt.
+- **Melted door seams / panel gaps** → run the detail-texture pass (step 6).
+
+### 6. Optional: secondary detail-texture pass
+
+For hero vehicles, run a texture-only pass to recover panel-line crispness without re-meshing:
+
+```
+summer_generate_3d(
+  kind="texture",
+  imageUrl="<original front-view reference>",
+  model="hunyuan",
+  options={ target_polycount: 25000 }  // matched to existing mesh
+)
+```
+
+This re-textures the existing mesh with sharper detail — panel lines, decals, weathering. Cheaper than re-meshing. Apply via material override in the editor.
+
+### 7. Wire into the scene
+
+| Use case | Parent type | Notes |
+|---|---|---|
+| Player-driven (car, bike, hover) | `VehicleBody3D` (Godot 4.5 wheeled) or `RigidBody3D` (free physics) | Add `VehicleWheel3D` children for wheeled vehicles |
+| Player-driven (spaceship, mech) | `RigidBody3D` or `CharacterBody3D` | Custom thrust / walk code, see `summer:character-controllers` |
+| Background scenery (parked, flyby) | `MeshInstance3D` under a `Node3D` | No physics, no collision needed for distant traffic |
+| Background traffic (moving but not interactive) | `Node3D` + `AnimationPlayer` driving the position | Cheap, no physics overhead |
+
+**Player car wiring:**
+
+```
+summer_add_node(parent="./World", type="VehicleBody3D", name="RaceCar")
+summer_add_node(parent="./World/RaceCar", type="MeshInstance3D", name="Body")
+summer_set_prop(path="./World/RaceCar/Body", property="mesh", value="res://assets/vehicles/race_car.glb")
+summer_add_node(parent="./World/RaceCar", type="CollisionShape3D", name="Collider")
+# Add a BoxShape3D resource matched to the AABB
+# Add VehicleWheel3D children at each wheel position
+summer_save_scene
+```
+
+**Background scenery wiring:**
+
+```
+summer_add_node(parent="./World/Street", type="MeshInstance3D", name="ParkedSedan")
+summer_set_prop(path="./World/Street/ParkedSedan", property="mesh", value="res://assets/vehicles/sedan.glb")
+summer_save_scene
+```
+
+## Anti-patterns
+
+- **Single-angle reference for a hero vehicle.** Front-only → melted rear. Always go multi-angle for anything the player gets close to.
+- **Flat-shaded prompt for hard surfaces.** "Smooth shading", "rounded edges" → loses the panel-line crispness that defines vehicles. Prefer "hard-surface", "panel-lined", "crisp edges".
+- **Skipping symmetry callouts.** Vehicles are bilaterally symmetric — without `symmetric, mirrored` you get one headlight bigger than the other 30% of the time.
+- **Asking the mesh pass to invent decals / liveries.** It can't — the mesh has the silhouette but the decals get geometry-baked weirdly. Use the texture pass for liveries.
+- **Wrapping a background sedan in VehicleBody3D.** Wastes physics for a parked car. Use MeshInstance3D under Node3D.
+- **Picking `meshy` (legacy).** Worse hard-surface fidelity than hunyuan or trellis.
+
+## Edge cases
+
+- **Tracked vehicle (tank).** AI mesh-gen handles the hull but the tracks come back as a fused ring. Generate the hull only, then add tracks as a separate `summer:3d-assets/prop-model` (or use a tiled texture on a torus). For animation, scroll the track texture's UV.
+- **Articulated vehicle (mech with shoulders, hips, knees).** The mesh is one piece — joints aren't separated. For animated mechs, treat as a humanoid: generate as `summer:3d-assets/character-model` with the rig pass, then animate via `summer:animation/generate-motion` (custom backend, prompt as "mech walks heavily").
+- **Vehicle with rotor (helicopter, drone).** Generate without rotor, then add the rotor as a separate `summer:3d-assets/prop-model` and parent it. Spin via code in `_process`.
+- **Open-top vehicle (convertible, jeep).** Specify "open top, no roof" — defaults often add a roof.
+- **The user wants the cockpit interior visible.** Generate exterior here, then a separate `summer:3d-assets/prop-model` for the interior, and switch meshes when the camera enters first-person view.
+
+## Fallback (no MCP)
+
+1. Generate the multi-angle reference at the Summer dashboard (or Midjourney / nano-banana web).
+2. Upload to Hunyuan or Trellis web playground → image-to-3D → download `.glb`.
+3. Drop into `res://assets/vehicles/`.
+4. Wire as VehicleBody3D / MeshInstance3D in the Godot editor manually.
+
+## Handoff
+
+After the vehicle is wired:
+
+> `race_car.glb` placed at `./World/RaceCar` as a VehicleBody3D. Next:
+> - **Vehicle controls:** WASD steering / accel — see `summer:character-controllers` for the vehicle controller pattern (or write directly with `engine_force`, `steering`, and `brake` on VehicleBody3D).
+> - **Driver character:** generate via `summer:3d-assets/character-model` and parent to the seat position.
+> - **Engine sound + tire screech:** `summer:audio/sound-effect` for one-shots, `summer:audio/ambient-bed` for the engine loop.
+> - **Particles:** exhaust smoke, dust trail, sparks on collision — `summer:vfx/particles` (when available) or built-in GPUParticles3D.
+
+## See also
+
+- `summer:3d-assets/character-model` — for the driver/pilot.
+- `summer:3d-assets/prop-model` — for separable parts (rotors, decals as decals, modular kit pieces).
+- `summer:asset-pipeline/asset-strategy` — meta-router.
+- `summer:character-controllers` — for player-driven vehicle input wiring.
+- `_shared/mcp-tools-reference.md` — `summer_generate_3d` schema, including `kind: "texture"` for the secondary detail pass.

package/skills/README.md

@@ -2,7 +2,7 @@
 
 The canonical agent-readable game-dev knowledge source for Claude Code, Cursor, Codex, and Windsurf.
 
-When an agent is asked to make a game in Godot, this is what it reads to learn how.
+When an agent is asked to make a game in Summer Engine, this is what it reads to learn how.
 
 ## Layout
 

package/skills/_meta/skill-create/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skill-create
-description: Bootstrap a new Summer skill with the canonical folder structure, frontmatter, and stub sections. Use when adding a new skill to the library. Trigger on "create skill", "add skill", "new skill".
+description: Use when a contributor wants to add a new skill to the Summer library — bootstraps the canonical folder structure, frontmatter, and stub sections. Trigger on "create skill", "add skill", "new skill", "scaffold a skill".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: _meta

package/skills/_meta/skill-improve/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skill-improve
-description: Iterate on an existing Summer skill using a parallel-eval harness — run the skill against a behavioral spec with and without proposed changes, compare outputs, ship the version that wins. Use to upgrade a skill that's underperforming. Trigger on "improve skill", "iterate on skill", "make this skill better".
+description: Use when a contributor wants to upgrade a Summer skill that is underperforming or to fix a regression — runs the skill against a behavioral spec with and without proposed changes via parallel-eval harness and ships the version that wins. Trigger on "improve skill", "iterate on skill", "make this skill better".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: _meta

package/skills/_meta/skill-test/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: skill-test
-description: Validate a Summer skill against static structural rules and per-skill behavioral specs. Use to lint a skill before commit, audit the whole library, or check a behavioral spec assertion. Trigger on "skill test", "lint skill", "validate skill".
+description: Use when a contributor wants to lint a Summer skill before commit, audit the whole library, or check a behavioral spec assertion — validates against static structural rules and per-skill behavioral specs. Trigger on "skill test", "lint skill", "validate skill".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: _meta

package/skills/_meta/using-summer/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: using-summer
+description: Use when starting any conversation in a Summer Engine project — establishes how to find and use Summer skills and the summer-engine MCP, requiring Skill tool invocation before ANY response including clarifying questions.
+license: MIT
+compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode, Factory, Copilot]
+category: _meta
+user-invocable: false
+---
+
+<SUBAGENT-STOP>
+If you were dispatched as a subagent to execute a specific task, skip this skill. The parent agent has already loaded it.
+</SUBAGENT-STOP>
+
+<EXTREMELY-IMPORTANT>
+If you think there is even a 1% chance a Summer skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.
+
+IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
+
+This is not negotiable. This is not optional. You cannot rationalize your way out of this.
+</EXTREMELY-IMPORTANT>
+
+## Instruction Priority
+
+Summer skills override default model behavior, but **user instructions always win**:
+
+1. **User's explicit instructions** (CLAUDE.md, GEMINI.md, AGENTS.md, direct requests) — highest priority.
+2. **Summer skills** — override default agent behavior where they conflict.
+3. **Default system prompt** — lowest priority.
+
+If `CLAUDE.md` says "skip the brainstorm, just build it" and a skill says "always brainstorm first" — follow the user. The user is in control.
+
+## What Summer Is
+
+**Summer Engine** is an AI-native game engine — editor, scene graph, asset pipeline, and runtime are all instrumented for programmatic control by AI agents. **Summer** (this skill set + MCP server) is how your coding agent talks to it.
+
+Two layers:
+
+- **Skills** — discipline guides that fire on specific situations: brainstorming a game, designing a mechanic, building an FPS controller, debugging a crash, shipping a build. Each one is a SKILL.md you load via the Skill tool.
+- **MCP tools** — `summer_*` tools that talk to the running Summer Engine on `localhost:6550`. Scene mutation (`summer_add_node`, `summer_set_prop`), inspection (`summer_get_scene_tree`, `summer_inspect_node`), play/diagnostics (`summer_play`, `summer_get_diagnostics`), asset import/generation (`summer_import_from_url`, `summer_generate_3d`), and 30+ more.
+
+**Scripting language:** Summer Engine is compatible with Godot 4.5. You can write game code in either:
+
+- **GDScript** (`.gd`) — the default. Best supported by Summer skills (see `summer:gdscript-patterns`). Use this unless the user has explicitly chosen C#.
+- **C#** (`.cs`) — fully supported by the engine. There is no `summer:csharp-patterns` skill yet — when writing C#, use the Godot 4.5 C# API from first principles. The patterns are different (different lifecycle method names, different signal API, different export attributes), so don't blindly translate GDScript idioms. Confirm with the user that they want C# before producing it; switching languages mid-project is painful.
+
+Scenes are always `.tscn`/`.scn`. Resources are always `.tres`/`.res`. Drive the engine through `summer_*` tools — do not hand-edit `.tscn` files; the editor holds in-memory state that diverges from disk.
+
+The engine must be running for MCP tools that touch scenes or diagnostics. If it isn't, the tool returns an error pointing the user at `summer run`.
+
+## How to Access Skills
+
+**Claude Code / Cursor / Codex / Copilot CLI:** Use the `Skill` tool. When you invoke a skill, its content loads — follow it directly. Never use `Read` on a skill file.
+
+**Gemini CLI:** Use `activate_skill`.
+
+**OpenCode:** Skills are auto-discovered from the registered directory; load via OpenCode's native skill mechanism.
+
+## The Rule
+
+**Invoke the relevant skill BEFORE any response or action.** Even a 1% chance a skill might apply means you check. If the loaded skill turns out not to fit, you don't have to follow it — but you do have to load it first to know.
+
+```
+User message arrives.
+  │
+  ├── Does any Summer skill match?  ── No  ──▶  Respond directly.
+  │                                  │
+  │                                 Yes
+  │                                  │
+  ├── Invoke the Skill tool.
+  ├── Announce: "Using summer:<skill> to <purpose>."
+  ├── If the skill has a checklist, create a todo per item.
+  └── Follow the skill exactly.
+```
+
+## Red Flags (You Are Rationalizing — Stop)
+
+These thoughts mean STOP. Check skills first.
+
+| Thought | Reality |
+|---|---|
+| "This is just a quick fix" | Quick fixes break games. Check the skill. |
+| "I know how to add a node, I'll just call the MCP" | The skill encodes the order of operations. Check it. |
+| "The user just wants me to start" | Most "just build it" requests still benefit from the brainstorm-game skill. Offer it. |
+| "I can read the .tscn file directly" | `summer_get_scene_tree` and `summer_inspect_node` are authoritative. Files lag the editor's in-memory state. |
+| "I'll skip the soul file" | `.summer/GameSoul.md` is what every other skill reads. Honor it. |
+| "I don't need to brainstorm — they said FPS" | Even with the genre named, brainstorm-game scopes mechanics, art direction, and the cut list. Skip only if explicitly told to. |
+| "I'll write the GDScript myself, no skill" | `gdscript-patterns` encodes idioms that Claude/Codex/Cursor regularly get wrong (signal connection, type hints, `_ready` vs `_process`). |
+| "The engine isn't running, I'll just edit files" | Editing scene files directly while the engine is running silently overwrites in-memory state. Check the skill. |
+| "I remember this skill" | Skills evolve. Re-read the current version. |
+
+## Skill Priority
+
+When multiple Summer skills could apply, run them in this order:
+
+1. **Process skills first** — `brainstorm-game`, `debug`, `play`. These determine HOW to approach the task.
+2. **Discipline skills second** — `gdscript-patterns`, `scene-composition`, `art-direction`, `audio-direction`. These shape the content.
+3. **Build skills third** — `fps-controller`, `design-mechanic`, `design-level`, `setup-multiplayer`. These produce the artifacts.
+
+> "I want to make a game" → `brainstorm-game` first, then build skills.
+> "Fix this crash" → `debug` first, then domain skills.
+> "Add an FPS controller" → check `scene-composition` first, then `fps-controller`.
+
+## Skill Types
+
+- **Rigid skills** (`debug`, `gdscript-patterns`): follow exactly. Don't adapt away the discipline.
+- **Flexible skills** (`art-direction`, `design-mechanic`): adapt the principles to the project.
+
+The skill itself tells you which. Default to rigid when unsure.
+
+## When the Engine Isn't Running
+
+If an MCP tool returns "Summer Engine is not running":
+
+1. Tell the user: `summer run` to start it (or open Summer Engine and load the project).
+2. While waiting, do non-MCP work — read code, plan the next steps, draft GDScript.
+3. Retry the tool. The MCP server lazy-reconnects on the next call.
+
+Do NOT fall back to editing `.tscn` files directly. The engine reads them on disk but holds in-memory state that diverges, and saving from the editor will overwrite your file edits.
+
+## When the User Hasn't Set Up Summer
+
+If skills aren't found or the MCP server fails to start:
+
+1. Check whether `summer` is on PATH: `which summer` / `where summer`.
+2. If not, point them at: `npm install -g summer-engine` then `summer setup <agent> --yes`.
+3. If `summer doctor` is available, run it: `summer doctor` reports auth, engine, port, and skill state.
+
+## User Instructions Trump Everything
+
+A direct user instruction ("skip the brainstorm", "just write the code", "don't use the MCP, edit files") overrides this skill. Surface the trade-off in one sentence ("Skipping brainstorm — heads up, scope creep is the most common reason game projects die.") and proceed as instructed.

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

@@ -481,5 +481,7 @@ For a fully-rigged enemy with anim controller + loot drop:
 - `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
+- `visual-effects/recipes/hit-spark/SKILL.md` — hit flash recipe
+- `visual-effects/recipes/dissolve/SKILL.md` — death dissolve recipe
+- `visual-effects/game-feel/SKILL.md` — screen-feel discipline (camera shake, hit-stop)
 - `scripting-patterns/state-machine-patterns/SKILL.md` — generic FSM patterns