summer-engine 3.3.0 → 3.4.1

package/library/skills/summer-world-saves/SKILL.md

@@ -26,13 +26,13 @@ a move. A new authority then restores the World from its last save.
 | Keep | Use |
 |---|---|
 | What belongs to the place: built walls, chests, the coins left on the ground | **World save** (this skill) |
-| What belongs to a player: their coins, unlocks, level | **Player data** (`skill/summer-player-data`) |
+| What belongs to a player: their coins, unlocks, level | **Player data** (`summer-player-data`) |
 
 The engine never serializes nodes for you. The game decides what one save
 holds. It must be **one consistent cut**: if an item moves from a chest into
 an inventory, both sides go in the same save.
 
-This skill extends the Courtyard game from `skill/multiplayer-state`: its
+This skill extends the Courtyard game from `multiplayer-state`: its
 `match_doc` (the coins still on the ground, and the scoreboard) becomes the
 World's saved state.
 
@@ -238,7 +238,7 @@ Local Play runs a persistent World with an **in-memory** save store:
 - Nothing survives the run.
 
 ```
-summer_project_setting name="summer/local_play/players" value=2
+summer_project_setting key="summer/local_play/players" value=2
 summer_play
 summer_get_diagnostics
 summer_stop
@@ -278,7 +278,7 @@ Restoring after a real restart can only be proven hosted.
 
 ## See also
 
-- `skill/summer-player-data` — progress that follows a player
-- `skill/multiplayer-state` — the shared document this skill saves
-- `skill/multiplayer-project` — `world.json` and the authority scene
-- `skill/multiplayer-testing` — Local Play runs and markers
+- `summer-player-data` — progress that follows a player
+- `multiplayer-state` — the shared document this skill saves
+- `multiplayer-project` — `world.json` and the authority scene
+- `multiplayer-testing` — Local Play runs and markers

package/library/skills/text-to-motion/rigging-for-text-motion.md

@@ -3,7 +3,7 @@
 The motion model reads the skeleton's rest pose, hierarchy **and bone names**. Names carry
 meaning: a bone called `LeftArm` borrows everything the model learned from human arms.
 Rigs named like a human skeleton therefore animate far better than freeform names, even
-on non-humans. Measured on cartoon flowers (2026-09-29): with plant names (`Stem1`,
+on non-humans. Measured on cartoon flowers: with plant names (`Stem1`,
 `LeafL1`) most prompts barely moved; the same rig with human names nodded, bowed,
 gestured and looked around on cue.
 

package/library/skills/tileable-texture/SKILL.md

@@ -68,7 +68,7 @@ summer_generate_image(
 
 Two things about the arguments:
 
-- **There is no `image_size` and no `negative_prompt`.** `summer_generate_image` takes only `prompt`, `model`, `style`, `referenceImageUrl`, and `options`, and `options` only recognizes Nano Banana provider keys (`seed`, `outputFormat`, `safetyTolerance`, `syncMode`, `systemPrompt`, `limitGenerations`, `thinkingLevel`) plus `removeBackground`. Anything else is dropped without an error, so the call looks like it worked. Put the negations in the prompt text. Square is what you get regardless — MCP images come back at the server's 1:1 default, which is exactly what a tileable texture wants.
+- **There is no `image_size` and no `negative_prompt`.** `summer_generate_image` takes only `prompt`, `model`, `style`, `referenceImageUrl`, `removeBackground` and `options`, and `options` only recognizes Nano Banana provider keys (`seed`, `outputFormat`, `safetyTolerance`, `syncMode`, `systemPrompt`, `limitGenerations`, `thinkingLevel`). Anything else is dropped without an error, so the call looks like it worked. Put the negations in the prompt text. Square is what you get regardless — MCP images come back at the server's 1:1 default, which is exactly what a tileable texture wants.
 - **`style: "realistic"` is a no-op.** Only `cartoon` and `anime` append anything to the prompt; `realistic` and `none` append nothing, and any other value is coerced to `none`. The photographic look has to come from the prompt (`photographic detail`). Switching to `"none"` for stylized work likewise changes nothing on its own — change the prompt.
 
 ### 4. Import to project

package/library/skills/trailer-shot/SKILL.md

@@ -13,7 +13,7 @@ paths: ["assets/video/**", "trailers/**", "marketing/**"]
 
 A trailer shot is not a cutscene and not a loop. It is a single, deliberately-composed beat designed to live inside an edit — Steam capsule video, social cut, pitch-deck reel, Discord teaser, Twitter promo. Every shot has to earn its slot in 5 seconds or less because viewer attention drops past that. This skill produces those shots one at a time, with strong composition references and trailer-grade prompting, then hands the user off to a non-linear editor (DaVinci Resolve, Premiere, CapCut) to chain them. **Studio doesn't ship a video editor** — generation is the part this skill owns; the cutting is yours.
 
-If the user is generating a non-interactive narrative beat with dialogue, that's `video/cinematic-cutscene`. If they want a seamless background loop for a splash screen, that's `video/animated-loop`. This skill is for the punchy stuff — the kind of shot that ends up on the Steam page or in the first 10 seconds of a launch trailer.
+If the user is generating a non-interactive narrative beat with dialogue, that's `cinematic-cutscene`. If they want a seamless background loop for a splash screen, that's `animated-loop`. This skill is for the punchy stuff — the kind of shot that ends up on the Steam page or in the first 10 seconds of a launch trailer.
 
 ## When to use
 
@@ -26,9 +26,9 @@ If the user is generating a non-interactive narrative beat with dialogue, that's
 
 ## When NOT to use
 
-- Multi-shot story sequence with dialogue — `video/cinematic-cutscene`.
-- Seamless looping background — `video/animated-loop`.
-- Static marketing key art — `2d-assets/concept-art` then `2d-assets/character-portrait`.
+- Multi-shot story sequence with dialogue — `cinematic-cutscene`.
+- Seamless looping background — `animated-loop`.
+- Static marketing key art — `concept-art` then `character-portrait`.
 - Animated GIF of UI — that's a screen recording, not a generated video.
 - A literal Steam trailer (the assembled cut) — generate the shots here, then take them to your NLE.
 
@@ -69,13 +69,13 @@ For pure environment / abstract / VFX shots, you can skip this and prompt text-t
 
 The available models depend on whether you pass `imageUrl`. With a reference image (step 2) the call goes to the image-to-video route, which accepts only `ltx`, `kling`, and `minimax`; `kling-turbo` and `veo3` exist on the text-to-video route only, and pairing either with an `imageUrl` is a 400 `invalid_model`.
 
-| Model | Text-to-video | Image-to-video | Cost | Speed | When |
-|---|---|---|---|---|---|
-| `kling` | yes | yes | $0.50 | 2-4 min | Default for trailer hero shots — best motion + composition |
-| `ltx` | yes | yes | $0.10 | ~30s | B-roll, throwaway tests, blocking the composition before committing |
-| `minimax` | yes | yes | $0.25 | 2-3 min | Anime / stylized trailer looks |
-| `kling-turbo` | yes | **no** | $0.30 | 1-2 min | Same look as kling, faster, slight quality dip — but you lose `imageUrl` |
-| `veo3` | yes | **no** | $1.00 | 3-5 min | Pitch deck for investors, the one shot that has to be perfect — but you lose `imageUrl` |
+| Model | Text-to-video | Image-to-video | Speed | When |
+|---|---|---|---|---|
+| `kling` | yes | yes | 2-4 min | Default for trailer hero shots — best motion + composition |
+| `ltx` | yes | yes | ~30s | Cheapest. B-roll, throwaway tests, blocking the composition before committing |
+| `minimax` | yes | yes | 2-3 min | Anime / stylized trailer looks |
+| `kling-turbo` | yes | **no** | 1-2 min | Same look as kling, faster, slight quality dip — but you lose `imageUrl` |
+| `veo3` | yes | **no** | 3-5 min | Most expensive. Pitch deck for investors, the one shot that has to be perfect — but you lose `imageUrl` |
 
 Default: **`ltx` first to block the composition, then `kling` for the final**. For the *one* hero shot that drives the Steam page, escalate to `veo3` only if `kling` failed twice.
 
@@ -114,7 +114,7 @@ If "regenerate", revise *one* axis (camera move, lighting, or framing) — don't
 
 Trailer footage usually lives on the user's local disk and goes straight into the NLE, where the generated `.mp4` is exactly what you want.
 
-For shots that double as **in-engine** splash content, transcode first — Summer Engine has no MP4 or WebM loader, and `.ogv` (Ogg Theora) is the only video container it can open. `summer_import_from_url` runs Godot's import pipeline and rejects the file if it never becomes a loadable resource, so importing the `.mp4` fails outright rather than half-working.
+For shots that double as **in-engine** splash content, transcode first — Summer Engine has no MP4 or WebM loader, and `.ogv` (Ogg Theora) is the only video container it can open. `summer_import_from_url` runs the engine's import pipeline and rejects the file if it never becomes a loadable resource, so importing the `.mp4` fails outright rather than half-working.
 
 ```
 ffmpeg -i hero_boss_reveal.mp4 -c:v libtheora -q:v 8 -an hero_boss_reveal.ogv
@@ -133,24 +133,24 @@ Studio does not ship a video editor. After all the shots land, tell the user:
 > 3-5. Action beats (slow-mo combat, environmental destruction)
 > 6. Money shot (low-angle hero, ends on logo card)
 >
-> Score it with the music from `audio/music-track`. Add SFX hits on the cuts with `audio/sound-effect`.
+> Score it with the music from `music-track`. Add SFX hits on the cuts with `sound-effect`.
 
 ## Reference card — prompts that work
 
 Pattern: `<archetype framing> + <subject> + <action verb> + <camera move> + <lighting / time of day> + <stylistic anchor>`. Keep under 50 words. Anchor with a reference image whenever a specific character or asset appears.
 
-| Goal | Model | Prompt | Cost | Duration |
-|---|---|---|---|---|
-| Hero boss reveal | `kling` | `low-angle hero shot of an armored dragon turning toward camera, slow tilt-up, volcanic backlight, embers in air, cinematic, anamorphic flare, 16mm grain` | $0.50 | 5s |
-| Slow-mo combat impact | `kling` | `mid shot of a swordsman striking a parry, sparks fly, time-dilation slow motion, dust and motion blur, dramatic side-light, cinematic` | $0.50 | 5s |
-| Establishing kingdom wide | `kling` | `wide aerial of a clifftop fortress at golden hour, slow dolly forward, low sun raking the towers, cinematic, anamorphic, faint heat haze` | $0.50 | 5s |
-| Splash screen card | `kling` | `static composition of a lone hooded figure on a windswept ridge, only the cloak and grass moving, dusk, painterly cinematic, room for title text upper third` | $0.50 | 5s |
-| Whip pan reveal | `kling` | `whip pan from left to right across a battlefield at night, lands on the protagonist standing alone among bodies, torches flickering, cinematic` | $0.50 | 5s |
-| Detail dolly-in | `kling` | `slow dolly-in on a glowing rune-etched sword embedded in stone, motes of magic rising, blue-cold key light, shallow depth of field, cinematic` | $0.50 | 5s |
-| Vertical social hero | `kling` | `vertical close-up of a young witch raising hands, magical wind, hair flowing, candle-warm key, cinematic, framed for 9:16` | $0.50 | 5s |
-| Pitch-deck premium shot | `veo3` | `wide cinematic of a fleet of airships emerging through cloud cover at dawn, slow truck forward, golden god-rays, soaring orchestral cinematic` | $1.00 | 5s |
-| Cheap B-roll iteration | `ltx` | `mid shot of a knight walking through fog, slow truck backward, dawn light, cinematic` | $0.10 | 5s |
-| Anime style hero | `minimax` | `anime-style hero girl draws a katana in slow motion, sakura petals swirling, dramatic side-light, dynamic camera, Ghibli painterly` | $0.25 | 5s |
+| Goal | Model | Prompt | Duration |
+|---|---|---|---|
+| Hero boss reveal | `kling` | `low-angle hero shot of an armored dragon turning toward camera, slow tilt-up, volcanic backlight, embers in air, cinematic, anamorphic flare, 16mm grain` | 5s |
+| Slow-mo combat impact | `kling` | `mid shot of a swordsman striking a parry, sparks fly, time-dilation slow motion, dust and motion blur, dramatic side-light, cinematic` | 5s |
+| Establishing kingdom wide | `kling` | `wide aerial of a clifftop fortress at golden hour, slow dolly forward, low sun raking the towers, cinematic, anamorphic, faint heat haze` | 5s |
+| Splash screen card | `kling` | `static composition of a lone hooded figure on a windswept ridge, only the cloak and grass moving, dusk, painterly cinematic, room for title text upper third` | 5s |
+| Whip pan reveal | `kling` | `whip pan from left to right across a battlefield at night, lands on the protagonist standing alone among bodies, torches flickering, cinematic` | 5s |
+| Detail dolly-in | `kling` | `slow dolly-in on a glowing rune-etched sword embedded in stone, motes of magic rising, blue-cold key light, shallow depth of field, cinematic` | 5s |
+| Vertical social hero | `kling` | `vertical close-up of a young witch raising hands, magical wind, hair flowing, candle-warm key, cinematic, framed for 9:16` | 5s |
+| Pitch-deck premium shot | `veo3` | `wide cinematic of a fleet of airships emerging through cloud cover at dawn, slow truck forward, golden god-rays, soaring orchestral cinematic` | 5s |
+| Cheap B-roll iteration | `ltx` | `mid shot of a knight walking through fog, slow truck backward, dawn light, cinematic` | 5s |
+| Anime style hero | `minimax` | `anime-style hero girl draws a katana in slow motion, sakura petals swirling, dramatic side-light, dynamic camera, Ghibli painterly` | 5s |
 
 ### Bad prompts and why
 
@@ -166,7 +166,7 @@ Pattern: `<archetype framing> + <subject> + <action verb> + <camera move> + <lig
 
 - **Trying to chain shots inside one video generation.** Each clip is one beat. The cut between shots is the editor's job, not the model's. A 10s prompt with three actions returns mush.
 - **Skipping the reference image for the hero shot.** The boss in the Steam capsule must look like the boss in the game. Always lock identity with `imageUrl`.
-- **Using `veo3` for B-roll.** Burn $0.10 on `ltx` for blocking and B-roll; reserve `veo3` for the one shot that has to be perfect.
+- **Using `veo3` for B-roll.** Use `ltx` for blocking and B-roll; reserve `veo3` for the one shot that has to be perfect.
 - **Generating shots without composing the trailer first.** Make a 6-shot list before generating shot 1. Otherwise you'll generate shots that don't intercut.
 - **Assuming `aspectRatio="9:16"` reframed an image-to-video call.** It is ignored whenever `imageUrl` is set — the reference image decides the framing. Pillarboxed 16:9 on TikTok / Reels / Shorts reads as a desktop YouTube embed and gets demoted by the algorithm, so fix the reference, not the argument.
 - **Treating `summer_generate_video` as synchronous.** It returns `{ queued: true, jobId }` and no URL. Poll `summer_check_job` before handing the user a link.
@@ -176,7 +176,7 @@ Pattern: `<archetype framing> + <subject> + <action verb> + <camera move> + <lig
 ## Edge cases
 
 - **Steam capsule animated header (Steam asset).** Steam wants `.webm` at 616x353 or 1920x1080, ≤6s, 30fps, no audio, ≤4MB. Generate at 16:9, transcode in DaVinci, export `.webm` with VP9. The video model gives you the source; format conversion is on you.
-- **Pitch deck for investors.** One shot, `veo3`, money composition (low-angle hero or wide establishing). Worth the $1.00.
+- **Pitch deck for investors.** One shot, `veo3`, money composition (low-angle hero or wide establishing).
 - **Vertical for TikTok / Shorts.** The reference image must genuinely be portrait — `aspectRatio` is ignored once `imageUrl` is set. Frame the subject in the upper-middle so titles can sit at the bottom.
 - **Subject is a UGC environment the player built.** Take a screenshot of the in-engine view, run it through `summer_generate_image` as `referenceImageUrl` to "upgrade" the look, then use that as the video reference. The model can stylize a screenshot; it can't invent the user's level.
 - **Logo splash with motion graphics.** Generate a static logo card in `summer_generate_image` (or use the user's existing logo PNG), then prompt video as `static composition of <logo>, only background particles drifting, cinematic, room for title text` — keep the foreground motionless.
@@ -197,16 +197,16 @@ Once the shots are generated:
 
 > Generated 6 shots, ready for the cut. Next:
 > - Take them into DaVinci Resolve (free) or Premiere. Studio doesn't cut video.
-> - Score the trailer with `audio/music-track` — a 60-second trailer cue with a swell and a cold ending.
-> - Add hit SFX on the cuts with `audio/sound-effect` (impact whooshes between shots).
-> - For the title-card splash that ships in-engine, hand off to `video/animated-loop` with the established palette.
-> - For a narrative beat inside the trailer (a 10s "story" segment), hand off to `video/cinematic-cutscene`.
+> - Score the trailer with `music-track` — a 60-second trailer cue with a swell and a cold ending.
+> - Add hit SFX on the cuts with `sound-effect` (impact whooshes between shots).
+> - For the title-card splash that ships in-engine, hand off to `animated-loop` with the established palette.
+> - For a narrative beat inside the trailer (a 10s "story" segment), hand off to `cinematic-cutscene`.
 
 ## See also
 
-- `video/cinematic-cutscene` — narrative beats with dialogue.
-- `video/animated-loop` — seamless background clips for splash screens / title menus.
-- `audio/music-track` — trailer score.
-- `audio/sound-effect` — cut SFX (whooshes, impacts, stingers).
-- `2d-assets/concept-art` — generate the reference image axis when no asset exists yet.
+- `cinematic-cutscene` — narrative beats with dialogue.
+- `animated-loop` — seamless background clips for splash screens / title menus.
+- `music-track` — trailer score.
+- `sound-effect` — cut SFX (whooshes, impacts, stingers).
+- `concept-art` — generate the reference image axis when no asset exists yet.
 - `../../references/mcp-tools-reference/mcp-tools-reference.md` — `summer_generate_video` parameter schema and error codes.

package/library/skills/tune-performance/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: tune-performance
-description: "Profile a slow game via summer_get_diagnostics, identify rendering/physics/scripting hotspots, propose fixes with before/after metric expectations."
+description: "Profile a slow game with a measurement probe, identify rendering/physics/scripting hotspots, propose fixes with before/after metric expectations."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: performance
@@ -23,7 +23,7 @@ Performance tuning without measurement is gambling. This skill enforces a measur
 
 > What's slow? Pick the closest: framerate drops in scene X / startup is long / freezes for a moment / runs fine on my machine but bad on hardware Y.
 
-Wait. The answer narrows the fix domain by 5x:
+Wait for the answer. It narrows where to look:
 
 | Symptom | Likely subsystem |
 |---|---|
@@ -75,7 +75,7 @@ Write the returned numbers down before fixing anything. Drive the probe to the s
 
 **Never profile with `--headless`.** A headless instance has no renderer: `RENDER_TOTAL_DRAW_CALLS_IN_FRAME` and `RENDER_TOTAL_OBJECTS_IN_FRAME` read `0.0`, and the FPS figure is an uncapped loop rate, not the game's framerate. The verify instance is windowed-offscreen precisely so the numbers are real.
 
-**Genuine fallback (engine not running at all):** ask the user to enable Godot's built-in monitor (`Debug → Monitor`, or in-game with `Performance.get_monitor`) and paste numbers. At minimum: FPS, frame time, draw calls, physics active objects.
+**Fallback (engine not running at all):** ask the user to open the editor's built-in monitors (Debugger → Monitors) or print `Performance.get_monitor` values in game, and paste the numbers. At minimum: FPS, frame time, draw calls, physics active objects.
 
 ### 3. Identify the dominant cost
 
@@ -91,7 +91,7 @@ Decision tree:
 
 ### 4a. Rendering hotspot
 
-Common Godot 4.x rendering costs, ordered by frequency:
+Common rendering costs, ordered by frequency:
 
 | Pattern | Symptom | Fix |
 |---|---|---|
@@ -105,8 +105,8 @@ Common Godot 4.x rendering costs, ordered by frequency:
 To inspect a suspect node:
 
 ```
-summer_inspect_node "./World/Enemy"
-summer_inspect_resource "./World/Enemy"   # for mesh/material/shape details
+summer_inspect_node path:"./World/Enemy"
+summer_inspect_resource nodePath:"./World/Enemy" property:"mesh"   # mesh/material/shape details
 ```
 
 **Bakes: know which process can run them.** `LightmapGI.bake(from_node, image_data_path)` IS script-bound on this build — run it from `summer_run_script` in the live editor (the GPU lightmapper needs a real renderer: desktop editors have one, cloud containers need xvfb + GL per `running-in-the-cloud`, and pure-headless returns `BAKE_ERROR_NO_LIGHTMAPPER`). The `OccluderInstance3D` bake remains editor-button only — say so rather than reporting it as applied. Navmesh baking, collision-shape generation from meshes, and `ImporterMesh.generate_lods` are all scriptable and remain yours to do.
@@ -119,7 +119,7 @@ Top patterns:
 |---|---|
 | 100+ active RigidBody3D | Sleep them when idle (`can_sleep = true`), or convert to Area3D where collision response isn't needed |
 | Concave collision shapes on dynamic bodies | Convert to ConvexPolygonShape3D or compound primitives (sphere/capsule/box). Concave costs 5–20x more. |
-| Physics tick at 120 Hz default | Lower `physics/common/physics_ticks_per_second` to 60 if visual smoothness allows |
+| Physics tick rate raised above the 60 Hz default | Lower `physics/common/physics_ticks_per_second` back to 60 if visual smoothness allows |
 | Per-frame raycast in `_physics_process` | Cache the result, raycast every N frames, or use ShapeCast3D |
 | Hundreds of overlap queries | Use Area3D with `monitoring = true` only on the bodies that need to detect — turn it off on environment |
 
@@ -142,13 +142,13 @@ Fixes:
 - Cache the group lookup in `_ready()` if the group composition is stable.
 - Move per-frame work to a timer at 10 Hz (`_on_timer_timeout`), not 60 Hz.
 - Replace `distance_to` with `distance_squared_to` in comparisons (no sqrt).
-- Push hot loops to a `@tool`-able C# script or GDExtension if it's truly per-frame.
+- Move a truly per-frame hot loop to C# or a GDExtension.
 
 ### 4d. Frame time spikes (jitter)
 
 If FPS is good but frame time spikes:
 
-- **Shader compilation**: precompile shaders during loading screen via `RenderingServer.shader_compile_from_code` or by warming up the scene off-screen.
+- **Shader compilation**: warm shaders up during a loading screen by rendering each material once off-screen.
 - **GC / object allocation**: `var x := []` inside `_process` allocates each frame. Pre-allocate.
 - **Async resource load**: ensure `ResourceLoader.load_threaded_request` is finished before referencing.
 
@@ -217,7 +217,7 @@ Compare: was the metric movement at least 50% of what was promised? If yes, ship
 - **"Just disable VSync to see real FPS."** Disabling VSync helps you measure, but performance work targets perceived smoothness (16.7 ms, locked). Re-enable before shipping.
 - **Premature C++ rewrite.** A GDScript hotpath at 5% of frame time isn't the bottleneck. Profile first.
 - **"It's slow on user machines, must be the GPU."** Often it's resolution scale + shadow quality + GI settings. Add a quality preset switcher first.
-- **Threading gameplay code.** Godot's gameplay layer isn't thread-safe. Threading is for asset load, network, AI compute — not `_physics_process`.
+- **Threading gameplay code.** The scene tree isn't thread-safe. Threading is for asset load, network, AI compute — not `_physics_process`.
 
 ## Collaborative protocol
 
@@ -233,6 +233,6 @@ No template — this is a workflow. Performance tuning is project-specific by de
 - `../../references/godot-version/godot-version.md` — renderer API churn notes (Compositor, RenderSceneBuffers)
 - `../../references/collaborative-protocol/collaborative-protocol.md` — "May I write" pattern
 - `../../references/gd-style/gd-style.md` — GDScript conventions (avoid bare types, use `:=`)
-- `debugging/debug/SKILL.md` — bug triage (related but different)
-- `workflow/diagnosing-perf-regressions/SKILL.md` — when it *got* slow rather than always was
-- `rendering-and-lighting/3d-lighting/SKILL.md` — light setup and bake decisions
+- `debug` — bug triage (related but different)
+- `diagnosing-perf-regressions` — when it *got* slow rather than always was
+- `3d-lighting` — light setup and bake decisions

package/library/skills/tune-performance/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/tune-performance
 kind: skill
 version: 1.0.3
-summary: Profile a slow game via summer_get_diagnostics, identify rendering/physics/scripting hotspots, propose fixes with before/after metric expectations.
+summary: Profile a slow game with a measurement probe, identify rendering/physics/scripting hotspots, propose fixes with before/after metric expectations.
 use_when:
   - the game is slow, drops framerate, stutters, takes forever to start, or runs poorly on specific hardware
   - fps drops or stutter when many units, projectiles, or particles spawn at once and the hotspot is unknown

package/library/skills/ui-graphics/SKILL.md

@@ -77,7 +77,7 @@ Pattern:
 <asset class> of <subject>, game UI, <anchor style>, flat design, clean edges, transparent background, centered, isolated
 ```
 
-`isolated` is load-bearing. For the background, **do not rely on the prompt** — pass `options.removeBackground: true`, which runs a real background-removal pass after generation and returns a PNG with true alpha. That is the single highest-value argument in this skill, and it is the actual fix for the checkerboard failure listed below: models asked for a "transparent background" in text frequently paint the checkerboard.
+`isolated` is load-bearing. For the background, **do not rely on the prompt** — pass `removeBackground: true`, which runs a real background-removal pass after generation and returns a PNG with true alpha. That is the single highest-value argument in this skill, and it is the actual fix for the checkerboard failure listed below: models asked for a "transparent background" in text frequently paint the checkerboard.
 
 ### 5. Generate
 
@@ -87,11 +87,11 @@ summer_generate_image(
   prompt="ability icon for a fire spell, glowing flame in cupped hand, game UI, flat design with subtle gradient and soft inner shadow, 2px deep navy outline, gold and parchment palette, rounded square frame, centered, isolated on a plain background. Not photorealistic, no 3D render, no scene background, not busy, no multiple objects.",
   model="nano-banana-2",
   style="none",
-  options={ removeBackground: true }
+  removeBackground=true
 )
 ```
 
-`image_size` and `negative_prompt` do not exist on this tool and are dropped without an error — the negations have to live in the prompt text, and the size is fixed. `removeBackground` is the one `options` key here that does real work.
+`image_size` and `negative_prompt` do not exist on this tool and are dropped without an error — the negations have to live in the prompt text, and the size is fixed.
 
 **Button (3 states in 3 calls):**
 ```
@@ -164,7 +164,7 @@ If you generate a 4×4 grid of icons in one image, each icon becomes an `AtlasTe
 | Bad | Failure mode |
 |---|---|
 | `cool button` | No subject, no anchor. Returns a generic button on a card background. |
-| `transparent button with icon` | Model often renders a checkerboard "transparent" pattern as the actual fill. There is no negative-prompt argument to counter it — drop the word "transparent" from the prompt entirely and pass `options.removeBackground: true` instead. |
+| `transparent button with icon` | Model often renders a checkerboard "transparent" pattern as the actual fill. There is no negative-prompt argument to counter it — drop the word "transparent" from the prompt entirely and pass `removeBackground: true` instead. |
 | `8 ability icons in one image` | Inconsistent style across the 8. Generate one at a time with the same anchor. |
 | `realistic 3D rendered button` | Conflicts with flat-UI. Stay flat. |
 | `button with the word "Play"` on it | Models render text badly. Add text in Summer Engine via a `Label` over the button, not in the texture. |
@@ -175,7 +175,7 @@ If you generate a 4×4 grid of icons in one image, each icon becomes an `AtlasTe
 - **Letting the model render text.** Diffusion models cannot render reliable
   text. Always overlay text in Summer Engine with a `Label` node. The button
   texture is the frame; the label is the word.
-- **Forgetting `options.removeBackground: true`.** Default is opaque. Prompting for "transparent background" instead is what produces the painted-checkerboard failure below — the option runs a real alpha pass and does not.
+- **Forgetting `removeBackground: true`.** Default is opaque. Prompting for "transparent background" instead is what produces the painted-checkerboard failure below — the option runs a real alpha pass and does not.
 - **Expecting `style` to do the work.** Only `cartoon` and `anime` append anything; `realistic` and `none` append nothing, and any other value is coerced to `none`. `style: "none"` is right for UI, but "flat design" has to be in the prompt regardless.
 - **NinePatch with no border-vs-center distinction.** The 9-slice scaling smears the border into the center.
 - **Mipmaps on UI.** UI textures shouldn't mipmap — they're displayed at 1:1 or near it. Mipmaps waste memory and blur sharp edges.
@@ -187,7 +187,7 @@ If you generate a 4×4 grid of icons in one image, each icon becomes an `AtlasTe
   `STRETCH_KEEP_ASPECT_CENTERED` scales it down cleanly.
 - **User wants pixel-style UI.** Route to `pixel-art` — different prompt pattern, different filter, different anchor.
 - **User wants animated UI (spinning loading icon).** Generate the static frame here. Animate via `AnimationPlayer` rotating the `TextureRect`, not as a sprite sheet.
-- **Transparency comes back as a checkerboard pattern in the image.** The model rendered the checkerboard literally because the prompt asked for transparency. Remove every mention of transparency from the prompt, generate on a plain background, and pass `options.removeBackground: true` to cut the alpha server-side.
+- **Transparency comes back as a checkerboard pattern in the image.** The model rendered the checkerboard literally because the prompt asked for transparency. Remove every mention of transparency from the prompt, generate on a plain background, and pass `removeBackground: true` to cut the alpha server-side.
 - **Icons need to read at very small size (16-24px in a packed bar).** Bias prompts toward bold silhouette + minimal interior detail. Ornate detail is invisible at 16px and adds noise.
 
 ## Fallback (no MCP)
@@ -199,7 +199,7 @@ summer_generate_image(
   prompt="<asset + anchor>, isolated on a plain background. No scene background, not photorealistic, no 3D, not busy.",
   model="nano-banana-2",
   style="none",
-  options={ removeBackground: true }
+  removeBackground=true
 )
 ```
 

package/library/skills/use-widget-asset/SKILL.md

@@ -108,12 +108,12 @@ extends TextureProgressBar
 
 func _ready():
     var tex = load(slice_url)
-    # The base / "under" texture is the same image — Godot will mask it
+    # The base / "under" texture is the same image — the bar masks it
     # to whatever value 0-100 we set.
     texture_under  = tex
     texture_progress = tex
     fill_mode = TextureProgressBar.FILL_LEFT_TO_RIGHT if orientation == "horizontal" else TextureProgressBar.FILL_TOP_TO_BOTTOM
-    # The fill rect tells Godot which sub-region of the texture is the
+    # The fill rect tells the bar which sub-region of the texture is the
     # bar fill (vs the frame). Texture_progress_offset + stretch_margin_*
     # form the inset.
     var sw = tex.get_width()
@@ -160,7 +160,7 @@ In the pack, find the pair: `sliceMeta[currentIndex].pairWith` gives the other s
 
 ## Cut-offs and re-renders
 
-If the detected `frameMargins` are obviously wrong (the dashed overlay in the wizard's lightbox shows the center area clipping into a corner ornament), the user should hit **Recreate (HD)** on that slice. FLUX will regenerate it cleanly — but the *margins themselves* don't get re-detected after upscale. Margins live on the original detection. The user can also manually edit them in code via the `patch_margin_*` properties after instantiating.
+If the detected `frameMargins` are obviously wrong (the dashed overlay in the wizard's lightbox shows the center area clipping into a corner ornament), the user should hit **Recreate (HD)** on that slice. It regenerates cleanly — but the *margins themselves* don't get re-detected after upscale. Margins live on the original detection. The user can also manually edit them in code via the `patch_margin_*` properties after instantiating.
 
 ## Composite panels with sub-elements
 
@@ -171,16 +171,16 @@ When a slice has `parentSliceIndex` set, it came from a **Break-down** pass —
 
 Pick based on whether your game needs the panel to stretch as one unit or whether each control needs independent interaction.
 
-See **Composite Panels (Sliced Further)** below for the canonical fields the wizard now emits (`isComposite`, `zOrder`) and the consume recipe.
+See **Composite Panels (Sliced Further)** below for the fields the wizard emits (`isComposite`, `zOrder`) and the consume recipe.
 
 ## Composite Panels (Sliced Further)
 
-The wizard's Break-down pass produces two new per-slice fields the runtime must understand:
+The wizard's Break-down pass adds per-slice fields the runtime must understand:
 
 | Field | Type | Meaning |
 |---|---|---|
 | `isComposite` | boolean | True on the **parent** slice — the flat preview image of the assembled panel. NOT a runtime asset. Filter it out on import unless the caller explicitly wants the preview thumbnail. |
-| `zOrder` | number | Back-to-front paint order on children. Lower = behind. Matches Godot `z_index`, Unity `sortingOrder`, CSS `z-index`. |
+| `zOrder` | number | Back-to-front paint order on children. Lower = behind. Maps to `CanvasItem.z_index`. |
 | `parentSliceIndex` | number | Set on each child, points at the composite parent. Used to group children. |
 
 The table above lists every field this skill reads; treat any other field in the pack manifest as opaque.
@@ -201,7 +201,7 @@ For the full instantiation flow (op JSON, examples), use `instantiate-asset-pack
 
 ### Legacy compatibility
 
-Older packs (saved before the rename) used different field names. Always fall back:
+Older packs use different field names. Always fall back:
 
 ```
 const zOrder      = slice.zOrder      ?? slice.layerIndex   ?? packFileIndex;

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

@@ -36,14 +36,12 @@ If `CLAUDE.md` says "skip the brainstorm, just build it" and a skill says "alway
 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.
+- **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 the rest of the `summer_*` set.
 
 **Scripting language:** The user is making a Summer game with the Summer SDK.
-GDScript is the default creator language. Summer currently uses the 4.6.1
-upstream technical base, plans to adopt 4.7.1 next, and follows upstream
-continuously. Confirm version-sensitive behavior from the engine's own version
-string rather than turning that base into the product identity. You can write
-game code in either:
+GDScript is the default creator language. Summer Engine follows its upstream
+technical base continuously, so confirm version-sensitive behavior from the
+engine's own version string. You can write game code in either:
 
 - **GDScript** (`.gd`) — the default. Best supported by Summer skills (see `gdscript-patterns`). Use this unless the user has explicitly chosen C#.
 - **C#** (`.cs`) — supported by the shipped Mono build. The GDScript
@@ -150,7 +148,7 @@ Run `summer doctor` early in a fresh Summer session when setup, MCP tools, slash
 npx clear-npx-cache && npx -y summer-engine@latest setup <agent> --yes --force
 ```
 
-Use the dist-tag `summer doctor` recommends: `@latest` normally, `@next` (with `--channel next`) when this CLI was installed from the soaking release, otherwise the MCP server silently drops back to the older `latest`. Use the real agent slug from doctor or the current environment (`claude-code`, `codex`, `cursor`, `gemini`, `github-copilot`, `vscode-copilot`, `opencode`, etc.).
+Use the dist-tag `summer doctor` recommends: `@latest` normally, `@next` (with `--channel next`) when this CLI was installed from the soaking release, otherwise the MCP server silently drops back to the older `latest`. Use the real agent slug from doctor or the current environment (`claude-code`, `codex`, `cursor`, `antigravity`, `github-copilot`, `vscode-copilot`, `opencode`, etc.).
 
 Why this exact command matters:
 

package/library/skills/vehicle-model/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vehicle-model
-description: "Generate a hard-surface vehicle — car, spaceship, mech, boat, tank — static mesh with optional detail-texture pass, wired as Vehicle3D or MeshInstance3D."
+description: "Generate a hard-surface vehicle — car, spaceship, mech, boat, tank — static mesh with optional detail-texture pass, wired as VehicleBody3D or MeshInstance3D."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 3d-assets
@@ -101,7 +101,7 @@ Nothing in the prompt text "triggers" multi-view. The phrase `front and 3/4 side
 
 ### 4. Confirm and call
 
-> About to generate `red_race_car` via `hunyuan`, target ~25k tris, multi-angle ref. ~$0.60, ~90s. OK?
+> About to generate `red_race_car` via `hunyuan`, target ~25k tris, multi-angle ref. Uses credits, ~90s. OK?
 
 ```
 summer_generate_3d(
@@ -145,7 +145,7 @@ This re-textures the existing mesh with sharper detail — panel lines, decals,
 | Use case | Parent type | Notes |
 |---|---|---|
 | Player-driven (car, bike, hover) | `VehicleBody3D` (wheeled) or `RigidBody3D` (free physics) | Add `VehicleWheel3D` children for wheeled vehicles |
-| Player-driven (spaceship, mech) | `RigidBody3D` or `CharacterBody3D` | Custom thrust / walk code, see `fps-controller` |
+| Player-driven (spaceship, mech) | `RigidBody3D` or `CharacterBody3D` | Custom thrust / walk code (`character-movement` for walkers) |
 | 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 |
 
@@ -161,7 +161,7 @@ summer_set_resource_property(scenePath="res://main.tscn", nodePath="./World/Race
 summer_save_scene(scenePath="res://main.tscn")
 ```
 
-A `.glb` cannot be assigned to `MeshInstance3D.mesh` — an imported `.glb` is a scene, not a `Mesh` (`ResourceLoader.get_recognized_extensions_for_type("Mesh")` on the shipped 4.6.1 binary returns `["tres", "mesh", "res"]`, no `glb`). Instantiate it. Assigning a bare class name like `"BoxShape3D"` to a resource property auto-instantiates it, which is how you get a shape you can then size.
+A `.glb` cannot be assigned to `MeshInstance3D.mesh` — an imported `.glb` is a scene, not a `Mesh` (`ResourceLoader.get_recognized_extensions_for_type("Mesh")` on the shipped engine returns `["tres", "mesh", "res"]`, no `glb`). Instantiate it. Assigning a bare class name like `"BoxShape3D"` to a resource property auto-instantiates it, which is how you get a shape you can then size.
 
 Every scene-mutating tool takes an explicit `scenePath`; node paths are relative to that scene's root (`./`); `summer_set_prop`'s property argument is `key`; and `summer_set_resource_property` needs all five of `scenePath`, `nodePath`, `resourceProperty`, `subProperty`, `value`.
 
@@ -185,7 +185,7 @@ summer_save_scene(scenePath="res://main.tscn")
 ## 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 `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 `character-model` with the rig pass, then animate via `generate-motion` (custom backend, prompt as "mech walks heavily").
+- **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 `character-model` with the rig pass, then animate with `text-to-motion` (prompt "walks heavily").
 - **Vehicle with rotor (helicopter, drone).** Generate without rotor, then add the rotor as a separate `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 `prop-model` for the interior, and switch meshes when the camera enters first-person view.
@@ -202,7 +202,7 @@ summer_save_scene(scenePath="res://main.tscn")
 After the vehicle is wired:
 
 > `race_car.glb` placed at `./World/RaceCar` as a VehicleBody3D. Next:
-> - **Vehicle controls:** WASD steering / accel — see `fps-controller` for the vehicle controller pattern (or write directly with `engine_force`, `steering`, and `brake` on VehicleBody3D).
+> - **Vehicle controls:** WASD steering / accel — write them with `engine_force`, `steering`, and `brake` on VehicleBody3D.
 > - **Driver character:** generate via `character-model` and parent to the seat position.
 > - **Engine sound + tire screech:** `sound-effect` for one-shots, `ambient-bed` for the engine loop.
 > - **Particles:** exhaust smoke, dust trail, sparks on collision — `vfx-smoke` / `vfx-hit-spark` or built-in GPUParticles3D.
@@ -212,5 +212,4 @@ After the vehicle is wired:
 - `character-model` — for the driver/pilot.
 - `prop-model` — for separable parts (rotors, decals as decals, modular kit pieces).
 - `asset-strategy` — meta-router.
-- `fps-controller` — for player-driven vehicle input wiring.
 - `../../references/mcp-tools-reference/mcp-tools-reference.md` — `summer_generate_3d` schema, including `kind: "texture"` for the secondary detail pass.

package/library/skills/vehicle-model/resource.yaml

@@ -1,10 +1,10 @@
 id: skill/vehicle-model
 kind: skill
 version: 1.0.3
-summary: Generate a hard-surface vehicle — car, spaceship, mech, boat, tank — static mesh with optional detail-texture pass, wired as Vehicle3D or MeshInstance3D.
+summary: Generate a hard-surface vehicle — car, spaceship, mech, boat, tank — static mesh with optional detail-texture pass, wired as VehicleBody3D or MeshInstance3D.
 use_when:
   - generating a hard-surface vehicle — car, motorcycle, spaceship, hover bike, boat, mech, tank, helicopter
-  - a racing, flying, or combat game needs a hard-surface vehicle mesh as a Vehicle3D or MeshInstance3D
+  - a racing, flying, or combat game needs a hard-surface vehicle mesh as a VehicleBody3D or MeshInstance3D
 facets:
   lifecycle:
     - build

package/library/skills/verification-before-completion/SKILL.md

@@ -109,12 +109,11 @@ Bad: Trust agent report
 
 ## Why This Matters
 
-From 24 failure memories:
-- the user said "I don't believe you" - trust broken
-- Undefined functions shipped - would crash
-- Missing requirements shipped - incomplete features
-- Time wasted on false completion → redirect → rework
-- Violates: "Honesty is a core value. If you lie, you'll be replaced."
+False completion claims cost trust and time:
+- The user stops believing your reports.
+- Undefined functions ship and crash.
+- Missing requirements ship as incomplete features.
+- Time goes to redirecting and rework.
 
 ## When To Apply
 

package/library/skills/vfx-dissolve/SKILL.md

@@ -25,8 +25,8 @@ The dissolve shader samples 3D noise per fragment and clips pixels whose noise v
 
 ## When NOT to use
 
-- The user wants *fire* on the object that doesn't consume it — use `fire`, not dissolve. Dissolve makes the mesh disappear; fire just sits on top.
-- The user wants a particle-driven ash cloud as the object disappears — pair this with `smoke` (recolor to ash gray) spawned at the dissolving mesh's bounds.
+- The user wants *fire* on the object that doesn't consume it — use `vfx-fire`, not dissolve. Dissolve makes the mesh disappear; fire just sits on top.
+- The user wants a particle-driven ash cloud as the object disappears — pair this with `vfx-smoke` (recolor to ash gray) spawned at the dissolving mesh's bounds.
 - The user wants a fade-out via alpha (cheap, no shader) — set `transparency = TRANSPARENCY_ALPHA` and tween `albedo_color.a` to 0. Dissolve is better but more expensive.
 - The user wants the *world* to dissolve in for a level transition — that's a screen-space post-process, not this per-mesh recipe.
 - The character has skinned mesh + multiple materials — this works but you have to override every material slot. Confirm with user; consider a fade-out instead.
@@ -307,7 +307,7 @@ noise_scale    = 3.0
 
 ### thanos-snap
 
-Fast, fine grain, blue edge for the cosmic feel. Pair with `smoke` in pale gray for ash particles rising.
+Fast, fine grain, blue edge for the cosmic feel. Pair with `vfx-smoke` in pale gray for ash particles rising.
 
 ```
 duration       = 0.8
@@ -319,7 +319,7 @@ noise_scale    = 8.0
 
 ### holy-banish
 
-Slow, white edge, big halo. Add `magic-glow` underneath for a beam of light.
+Slow, white edge, big halo. Add `vfx-magic-glow` underneath for a beam of light.
 
 ```
 duration       = 2.5

package/library/skills/vfx-fire/SKILL.md

@@ -19,14 +19,14 @@ Fire in games is almost never a video clip and never an AI-generated sprite. It'
 - "Make a campfire / bonfire / hearth flame."
 - "Light the brazier."
 - "I need a candle flame on this candlestick."
-- "The dragon needs a flame breath" (use this for the persistent emitter; pair with a one-shot `muzzle-flash` for the burst).
+- "The dragon needs a flame breath" (use this for the persistent emitter; pair with a one-shot `vfx-muzzle-flash` for the burst).
 - The player set something on fire and you need a continuous, physically-anchored flame.
 
 ## When NOT to use
 
-- The user wants an object to *burn away* (mesh disintegrating with a fire edge) — route to `dissolve`. Fire is a separate effect; pair them.
-- The user wants smoke without flame — go straight to `smoke`. (Most fires want a smoke trail above; spawn this recipe and add `smoke` on top.)
-- The user wants a one-frame muzzle flash from a gun — that's `muzzle-flash`, not fire.
+- The user wants an object to *burn away* (mesh disintegrating with a fire edge) — route to `vfx-dissolve`. Fire is a separate effect; pair them.
+- The user wants smoke without flame — go straight to `vfx-smoke`. (Most fires want a smoke trail above; spawn this recipe and add `vfx-smoke` on top.)
+- The user wants a one-frame muzzle flash from a gun — that's `vfx-muzzle-flash`, not fire.
 - The user wants 2D fire on a UI element — use `canvas_item` shader; this recipe is `spatial`/`particles`.
 - The user wants stylized magic flame (blue, purple, ethereal) — use this recipe and load the `magic-fire` variant in the cookbook below.
 
@@ -397,7 +397,7 @@ OmniLight3D: light_energy = 1.6, omni_range = 6.0
 
 ### bonfire
 
-Wide, tall, hungry. Pair with `smoke` directly above.
+Wide, tall, hungry. Pair with `vfx-smoke` directly above.
 
 ```
 particle_count = 256
@@ -442,7 +442,7 @@ OmniLight3D: light_color = Color(0.40, 0.65, 1.0), light_energy = 2.4
 ## Anti-patterns
 
 - **Spatial-only shader on the visual quad.** It still works, but you forgot `blend_add` + `unshaded` and the flame looks like a flat orange triangle in shadow. Always: `render_mode unshaded, blend_add, depth_draw_never;`.
-- **Looping a one-shot emitter.** `one_shot = false` for fire (continuous). One-shot is for `muzzle-flash` and `hit-spark`.
+- **Looping a one-shot emitter.** `one_shot = false` for fire (continuous). One-shot is for `vfx-muzzle-flash` and `vfx-hit-spark`.
 - **Missing `cull_disabled`.** Particles billboard toward camera; if you cull backfaces, the flame disappears at certain angles.
 - **`depth_draw_opaque` on the visual material.** You'll z-fight with anything inside the flame (the torch handle). Use `depth_draw_never`.
 - **OmniLight3D parented under the GPUParticles3D.** The particles emit in local space; the light moves with them. Sibling, not child.