summer-engine 3.8.0 → 4.0.0

package/library/skills/concept-to-level/references/technical-rules.md

@@ -0,0 +1,150 @@
+# concept-to-level: technical rules in detail
+
+Each rule says what to do, why, and what went wrong without it. They come
+from one long 3D arena build in Summer Engine with several agents working
+on one map.
+
+## The live editor
+
+**Do not run heavy or reloading scripts in the live editor.** Recoding a
+shader, reloading a scene, or instantiating and freeing a scene that an open
+tab uses can hang the editor's main thread or crash it. We lost the editor
+twice to a clearance checker run inside it, and once more to a script that
+re-set shader code to refresh the cache ("Attempted to free invalid ID"
+spam, main thread stuck). Use the editor for small property edits and
+saves. Build meshes, bake data and run checks headless (see
+`headless-scripting`), then let the editor import the named files.
+
+**The editor keeps old shaders cached.** After a shader file changes on
+disk, the open editor may still draw the old version. Do not force a reload
+there; render from a fresh process instead.
+
+**Edit an open scene only through the live editor.** If you text-edit the
+`.tscn` on disk while it is open, the editor overwrites your change on its
+next save, or saves its stale copy over yours. The reverse also happens:
+pressing Play can save a stale open tab and resurrect deleted nodes. Close
+tabs you are not editing.
+
+**The editor rewrites some files on its own** (the project settings file,
+some scenes and resources it touches on load). Check `git diff` before every
+commit and stage only what you meant to change. To change one line of such a
+file, build the commit content from the last commit plus that line rather
+than staging the editor's whole rewrite.
+
+## Rendering previews
+
+**Render from a separate, short-lived engine process** that loads the map
+from disk, takes the frames, and exits. It sees the current shaders and
+meshes, cannot disturb the editor, and frees its memory when done.
+
+**Call `RenderingServer.force_draw()` before reading the viewport image.**
+Without it, later frames can come back identical to an earlier one when the
+window stops drawing in the background.
+
+**Watch for in-game UI covering the camera.** A level script may open a menu
+(class select, lobby) that hides the scene. Render the scene with that
+script disabled, or from an isolated viewport.
+
+**Fixed angles.** Keep a small set of saved cameras per map: overview, eye
+level from each spawn, each hero element close, from above. Reuse them so
+before and after renders are comparable.
+
+## Load
+
+One heavy process at a time across all agents (imports, Blender, headless
+runs, renders), at low priority. The machine overheating or the editor
+freezing during a demo costs more than the time saved. See
+`bounded-engine-runs` for time limits and muted runs.
+
+## Online constraints
+
+Check what the online build does to a map scene before designing effects.
+In our project the online client rebuilt the map's visuals, turned any node
+whose type contains "Particles" into a plain node, and ran no map scripts.
+Consequences:
+
+- Fire, sparks, smoke, motes: camera-facing mesh layers driven by shaders,
+  with soft depth fades. No particle nodes.
+- Animated set pieces (a statue floating against taut chains): bake the
+  motion into a vertex animation texture and play it in the vertex shader.
+  Set `custom_aabb` so the moving mesh is not culled. Zero CPU.
+- Dynamic events: the server owns the state (timings, collision on or off);
+  a client presenter drives the shader parameters from that state. Write the
+  spec for the server with timings in ticks and the exact collision bodies.
+- Lights survive, so cheap flickering lights are fine.
+
+## Baked versus procedural
+
+Bake what only needs to loop (statue, cloth idle). Make procedural what must
+aim or react: god hands that point their beams at a moving target need an
+aim layer (look-at or two-bone IK with damped, slightly overshooting motion)
+on top of the base pose, with one API all events call.
+
+## Fallbacks
+
+When you swap an experimental asset into the map (the floating statue), keep
+the previous scene file and say how to swap back. Do not swap untested
+assets in right before a demo unless the user asks.
+
+## Generated and third-party assets
+
+Generated 3D models need cleanup: decimate to a budget, check normals and
+inside-out meshes, merge or split parts deliberately, ground them on their
+support, give every surface a real material (a chain that rendered white
+had lost its material on import). Record each in the notices file with the
+tool named and its terms marked "not confirmed" until checked.
+
+Every third-party texture: source page, author, licence, download date,
+what was changed. Never guess a licence.
+
+## Modular kits
+
+After every kit rebuild check: zero coplanar overlapping faces, all seams
+welded (no gaps where pieces meet), a see-through scan with rays from inside
+the play space, and the collision against the visible faces (within a few
+cm). Rebuilds can change random block tones and baked shading on pieces you
+did not mean to change: compare against the committed version and restore.
+
+When splitting a kit piece out (to make it removable), copy its triangles
+out of the exported files instead of regenerating it, prove the split looks
+identical, and install the new pieces and the scene that uses them together.
+Overwriting a repo piece first made parts of the live map vanish.
+
+## Moving things
+
+Moving a room or structure moves the job, not one node. Re-run or re-check
+everything placed relative to it: decals (snap to the actual surface, drop
+what no longer fits), banners and their hooks, backdrop rock under it,
+spawn markers, collision, lights. Re-measure clearances, including cloth at
+full sway against the floor below.
+
+## Gameplay sync
+
+After a collider, spawn or zone change: recompile the server's collision
+artifact, update tests that hard-code positions, run the rules tests and the
+contract check, and read their PASS lines. Spawns: centred on the axis,
+mirrored exactly between teams (an exact 180 degree turn, not 180.56),
+evenly spaced, facing the play space.
+
+## Render cost
+
+Count early and after each lane: vertices, triangles, mesh instances, draw
+calls, shadow-casting surfaces, lights (and which cast shadows), decals.
+Know the biggest offenders by group. In our map, eight decorative figures
+seen only through bars were a quarter of all triangles; the fix was a
+low-end note to hide them and a planned decimation. Typical cuts: decimate
+hidden detail, merge kit pieces into fewer draws, no shadows on small
+props, shorter sun shadow distance, half-resolution post effects.
+
+## Dynamic events
+
+- Agree the feel first: scale, speed, how long it stays, what the warning
+  reveals. Big things move slowly, with anticipation and a held impact.
+- Telegraph fairly but not too precisely: a warning that draws the exact
+  path is too easy to dodge.
+- Check the event never makes the play space impassable and never kills
+  without warning.
+- Make what the player sees match what happens: a hole that is open in the
+  collision but painted over by a glow reads as solid floor.
+- In a showcase or demo loop, reset destroyed pieces so the effect can be
+  watched again.

package/library/skills/concept-to-level/resource.yaml

@@ -0,0 +1,44 @@
+id: skill/concept-to-level
+kind: skill
+version: 1.0.0
+summary: Take a 3D map from concept art to a polished, shippable level, with the questions to ask the user, owned lanes, render checks and collision kept in step.
+use_when:
+  - polishing a 3D map or arena from concept art to shipping quality, with real materials, props, sky and effects
+  - reworking a level's theme and art while keeping its gameplay layout, with several agents working on one map
+  - deciding which questions to ask the user before building or polishing a level
+do_not_use_when:
+  - a quick 2D or playable scene from one reference image — skill/scene-to-level
+  - designing layout, pacing and encounters on paper — skill/design-level
+  - generating a single prop or kit — skill/prop-model or skill/environment-kit
+facets:
+  lifecycle:
+    - build
+  domains:
+    - level-design
+    - 3d
+    - world-building
+    - agent-workflow
+  modalities:
+    - scenes
+    - assets
+    - shaders
+    - docs
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/concept-art
+    - skill/art-direction
+    - skill/design-level
+    - skill/scene-to-level
+    - skill/environment-kit
+    - skill/fabricating-assets
+    - skill/headless-scripting
+    - skill/bounded-engine-runs
+    - skill/verifying-scenes
+    - skill/tune-performance
+    - skill/dispatching-parallel-agents
+source: official
+license: MIT
+status: preview
+recommended: false

package/library/skills/create-asset-sheet/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: create-asset-sheet
-description: "Generate a pack of 2D game assets from one prompt — tile sheet, UI kit, character pack, or biome set — sliced, classified, and saved as one pack ArtAsset."
+description: "Generate a pack of 2D assets from one prompt (tile sheet, UI kit, character pack, biome), sliced."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 2d-assets
 user-invocable: true
-allowed-tools: Read Grep Glob Write Edit summer_get_studio_workflow summer_generate_image summer_slice_asset_sheet summer_search_assets summer_import_asset_by_id summer_import_from_url
+allowed-tools: Read Grep Glob Write Edit summer_assets_generate_image summer_assets_slice_sheet summer_assets_search summer_import_asset_by_id summer_import_from_url summer_import_from_url_batch summer_call
 paths: ["assets/**", "art/**", "sprites/**"]
 ---
 
@@ -42,7 +42,7 @@ Categories the classifier outputs (used to route into downstream pipelines):
 
 ## The cleanest path: the studio wizard
 
-The most reliable way to run this flow is the **Create Asset Sheet** wizard in Summer Studio's guided workflows. Open it for the user with `summer open workflows` (or `summer_open`) if they're working in the browser. The wizard:
+The most reliable way to run this flow is the **Create Asset Sheet** wizard in Summer Studio's guided workflows. Open it for the user with `summer open workflows` (or `studio.open`) if they're working in the browser. The wizard:
 
 - Offers a 2D / 3D mode toggle (2D is the slice flow described here; 3D is a soft pointer to `concept-art` + per-asset image-to-3D for now)
 - Surfaces six prompt templates (tile sheet, UI kit, menu, character pack, biome, freeform)
@@ -58,31 +58,32 @@ calls the same server-side slicer as the Studio wizard.
 ## Programmatic path (chat / agent driving the engine)
 
 1. **Load the exact current recipe.** Call
-   `summer_get_studio_workflow({workflowId: "asset-pack"})`. Follow its ordered
+   `summer_call({op: "docs.workflows", input: {workflowId: "asset-pack"}})`. Follow its ordered
    steps and report any `manual` handoff instead of pretending it ran.
 
-2. **Generate the sheet.** Call `summer_generate_image` with a prompt like:
+2. **Generate the sheet.** Call `assets.generate_image` with a prompt like:
 
    ```
    <theme> asset sheet: <comma-separated list of items>. Each item isolated with empty space around it, transparent or neutral background.
    ```
 
    - Pick model by style: pixel art → `grok-imagine`, painterly / illustrative / structured grids → `gpt-image-2`.
-   - 1024x1024 is the sweet spot. Larger sheets fragment in the slicer when individual assets get below ~64px.
+   - Square (`aspectRatio: "1:1"`, the default, about 1024x1024) is the sweet spot. Larger sheets fragment in the slicer when individual assets get below ~64px.
    - Keep the asset list to 6–20 items per sheet. Past 20, model attention degrades and slices get muddy.
 
 3. **Slice, remove background, detect, name, classify, crop, and save.** Pass
    the returned image asset id to:
 
    ```
-   summer_slice_asset_sheet({ assetId: "<generated asset id>" })
+   assets.slice_sheet({ assetId: "<generated asset id>" })
    ```
 
-   This is the same cloud slicing pipeline used by the Studio flow. Keep the
-   returned slice ids/names/categories; do not reimplement the vision boxes
-   locally.
+   This is the same cloud slicing pipeline used by the Studio flow. It answers
+   `slices` (each with `url`, `name`, `category`, `bbox`) and `source`; keep the
+   names and categories, and do not reimplement the vision boxes locally. Slicing
+   spends credits: `dryRun: true` shows how many.
 
-4. **Optional upscale.** The Studio wizard has per-slice HD upscale. Over MCP, for any crop where the longest side is under 256px, call `summer_generate_image` with the slice as `referenceImageUrl` and this prompt:
+4. **Optional upscale.** The Studio wizard has per-slice HD upscale. Over MCP, for any crop where the longest side is under 256px, call `assets.generate_image` with the slice `url` as `referenceImageUrl` and this prompt:
 
    ```
    Recreate this exact <name> at high resolution. Preserve every detail, the exact pose, the exact style. Sharper edges, more detail. Transparent background. Single isolated asset, no scene.
@@ -90,8 +91,9 @@ calls the same server-side slicer as the Studio wizard.
 
    - Don't upscale everything: each upscale is a paid generation, and large slices gain little.
 
-5. **Import what the game needs.** Use the returned asset ids with
-   `summer_import_asset_by_id`. Keep the source pack in My Assets so the agent
+5. **Import what the game needs.** The slices are image URLs, not assets: import
+   them with `summer_import_from_url_batch` (upscaled ones by their `assetId` with
+   `summer_import_asset_by_id`). Keep the source pack in My Assets so the agent
    and the human Studio session see the same result.
 
 ## Prompt patterns that work
@@ -137,6 +139,10 @@ calls the same server-side slicer as the Studio wizard.
 | Upscaled slice looks invented | Source was too small / too ambiguous | Don't upscale slices below ~32×32. Or accept the hallucination and edit |
 | Detection returns wrong category | Model misjudged context | User can override in the review step; not a blocker |
 
+## Without Summer Engine
+
+In a session without Summer Engine tools (the assets profile; the `summer-assets` skill has the whole loop), the studio wizard path works as written. On the programmatic path, stop after `assets.slice_sheet` and skip `summer_import_asset_by_id`: save each piece where the person asked with `assets.get` and `out` (the `summer-assets` skill says how), and tell them the paths.
+
 ## What this skill does NOT do (yet)
 
 - Per-asset planning and individual generation, where each asset is generated separately at full resolution.

package/library/skills/create-asset-sheet/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/create-asset-sheet
 kind: skill
 version: 1.0.3
-summary: Generate a pack of 2D game assets from one prompt — tile sheet, UI kit, character pack, or biome set — sliced, classified, and saved as one pack ArtAsset.
+summary: "Generate a pack of 2D assets from one prompt (tile sheet, UI kit, character pack, biome), sliced."
 use_when:
   - generating a pack of 2D game assets from a single prompt — a tile sheet, UI kit, menu screen, character pack, or biome set
   - many matching sprites, tiles, or UI pieces are needed in one consistent style at once

package/library/skills/debug/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debug
-description: "Disciplined bug/crash/error loop for Summer projects — script errors, console, debugger, hypothesis, fix, verify — before making code or scene changes."
+description: "Disciplined bug, crash and error loop: script errors, console, debugger, hypothesis, fix, verify."
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
 category: debugging
@@ -143,7 +143,7 @@ Surface the proposed fix in plain language and ask permission. Two patterns:
 
 - For GDScript edits: `Read` the 20–40 lines around the error, `Edit` the exact change. Don't read the whole file. Don't reformat. Don't rename other things.
 - For scene edits: use the appropriate `summer_*` tool (`summer_add_node`, `summer_set_prop`, `summer_replace_node`). Group multi-step changes in `summer_batch` for one undo step.
-- **Nested resource properties:** `summer_set_resource_property` works against inline `sub_resource` targets too — pass `nodePath`, `resourceProperty`, and `subProperty` (there is no dotted `"mesh.size"` form). Structural failures (`node not found`, `property is not a resource`, `resource is null`) are explicit errors; a bad value shape is not — a JSON object instead of an engine literal string, a misspelled `key`/`subProperty`, or a wrong-typed value returns `ok:true` yet silently no-ops or coerces destructively on current engines (dict → material cleared; dict → `Color(0,0,0,1)`; newer engines reject these with `unknown_property` / `bad_value_shape` / `type_mismatch`). Pass class names and `Color(...)`/`Vector3(...)` strings, and confirm the fix in the saved `.tscn` or a snapshot diff, never from `ok` alone. See `../../references/mcp-tools-reference/mcp-tools-reference.md`.
+- **Nested resource properties:** `summer_set_resource_property` works against inline `sub_resource` targets too — pass `nodePath`, `resourceProperty`, and `subProperty` (there is no dotted `"mesh.size"` form). Structural failures (`node not found`, `property is not a resource`, `resource is null`) are explicit errors; a bad value shape is not — a JSON object instead of an engine literal string, a misspelled `key`/`subProperty`, or a wrong-typed value returns `ok:true` yet silently no-ops or coerces destructively on current engines (dict → material cleared; dict → `Color(0,0,0,1)`; newer engines reject these with `unknown_property` / `bad_value_shape` / `type_mismatch`). Pass class names and `Color(...)`/`Vector3(...)` strings, and confirm the fix in the saved `.tscn` or a snapshot diff, never from `ok` alone. See `summer_docs_read` id `reference/mcp-tools-reference`.
 
 ### 6. Verify — re-run the diagnostic that found it
 

package/library/skills/debug/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/debug
 kind: skill
 version: 1.0.4
-summary: Disciplined bug/crash/error loop for Summer projects — script errors, console, debugger, hypothesis, fix, verify — before making code or scene changes.
+summary: "Disciplined bug, crash and error loop: script errors, console, debugger, hypothesis, fix, verify."
 use_when:
   - the user reports a bug, crash, error, or unexpected behavior in a Summer project, before making code or scene changes
   - the player falls through the floor or clips through walls

package/library/skills/debugging-game-feel/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debugging-game-feel
-description: "Debug features that work but feel wrong — floaty jumps, mushy combat, sluggish camera — subjective bugs living in tuning, timing, and feedback layers."
+description: "Debug features that work but feel wrong: floaty jumps, mushy combat, sluggish camera."
 ---
 
 # Debugging Game Feel

package/library/skills/debugging-game-feel/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/debugging-game-feel
 kind: skill
 version: 1.0.3
-summary: Debug features that work but feel wrong — floaty jumps, mushy combat, sluggish camera — subjective bugs living in tuning, timing, and feedback layers.
+summary: "Debug features that work but feel wrong: floaty jumps, mushy combat, sluggish camera."
 use_when:
   - a gameplay feature works correctly but feels wrong — floaty jumps, mushy combat, sluggish camera, weightless impacts
   - tuning jump height, gravity, camera lag, hit-stop, or impact feedback until controls feel right

package/library/skills/design-level/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: design-level
-description: "Design a single level — layout, pacing, encounters, secrets, reward gating — outputs a level design doc and a node-tree skeleton for summer_create_scene."
+description: "Design one level (layout, pacing, encounters, secrets) as a design doc plus a node-tree skeleton."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: level-design
 user-invocable: true
-allowed-tools: Read Grep Glob Write Edit summer_get_scene_tree summer_create_scene summer_open_scene summer_add_node summer_set_prop summer_save_scene summer_get_script_errors
+allowed-tools: Read Grep Glob Write Edit summer_get_scene_tree summer_create_scene summer_open_scene summer_run_script summer_add_node summer_set_prop summer_save_scene summer_get_script_errors
 paths: ["**/*.tscn", "**/*.gd", ".summer/**", "levels/**"]
 ---
 
@@ -148,44 +148,32 @@ Show the skeleton. Ask:
 
 ### 8. Scaffold via MCP
 
-**Preferred (Summer MCP):**
+**Preferred (Summer MCP):** create the scene, then build the whole skeleton in one script.
 
-`summer_create_scene` takes `path`, `rootName`, and a mandatory safety gate.
-There is no `root_type` or `root_name` argument. The tool refuses to run unless
-`allow_temporary_scene_mutation` is explicitly true, because of how it works: it
-opens the currently-open scene (or the project's main scene) as a template,
-removes every child, renames the root, saves-as to the new path, then reopens
-the original. Ask the user before setting the flag.
-
-The consequence to plan around: **the new scene's root node type is copied from
-the template's root**, not chosen by you. Create levels from a scene whose root
-is already `Node3D`, or fix the root afterwards in the editor.
+`summer_create_scene` takes `path`, `rootName` and `rootType` (default `Node3D`) and writes the new scene to disk without opening it. `summer_run_script` with that `scenePath` opens it, runs, and gives the user their tab back; the run is one undo step, so one Ctrl+Z removes the skeleton.
 
 ```
-summer_create_scene(path="res://levels/level_01.tscn", rootName="World", allow_temporary_scene_mutation=true)
-summer_add_node(scenePath="res://levels/level_01.tscn", parent="./World", type="Node3D", name="Geometry")
-summer_add_node(parent="./World/Geometry", type="Node3D", name="IntroAtrium")
-summer_add_node(parent="./World/Geometry", type="Node3D", name="Corridor")
-summer_add_node(parent="./World/Geometry", type="Node3D", name="PeakArena")
-summer_add_node(parent="./World/Geometry", type="Node3D", name="BossChamber")
-summer_add_node(parent="./World", type="Node3D", name="Spawns")
-summer_add_node(parent="./World/Spawns", type="Node3D", name="PlayerSpawn")
-summer_add_node(parent="./World/Spawns", type="Node3D", name="E1_Spawn")
-# ... and so on
-summer_add_node(parent="./World", type="Node3D", name="Triggers")
-summer_add_node(parent="./World/Triggers", type="Area3D", name="E2_GateTrigger")
-# ... etc.
-summer_add_node(parent="./World", type="Node3D", name="Lighting")
-summer_add_node(parent="./World/Lighting", type="WorldEnvironment", name="WorldEnvironment")
-summer_add_node(parent="./World/Lighting", type="DirectionalLight3D", name="Sun")
-summer_save_scene(scenePath="res://levels/level_01.tscn")
+summer_create_scene(path="res://levels/level_01.tscn", rootName="World", rootType="Node3D")
+summer_run_script(scenePath="res://levels/level_01.tscn", source="""
+func run(ctx):
+    var skeleton = {
+        "Geometry": [["Node3D", "IntroAtrium"], ["Node3D", "Corridor"], ["Node3D", "PeakArena"], ["Node3D", "BossChamber"]],
+        "Spawns": [["Node3D", "PlayerSpawn"], ["Node3D", "E1_Spawn"], ["Node3D", "E2_Spawn"], ["Node3D", "E3_Wave_Spawns"], ["Node3D", "MiniBoss_Spawn"]],
+        "Triggers": [["Area3D", "E2_GateTrigger"], ["Area3D", "PeakWaveTrigger"], ["Area3D", "BossDoorTrigger"]],
+        "Pickups": [["Node3D", "HealAfterE2"], ["Node3D", "CurrencyS1"]],
+        "Secrets": [["StaticBody3D", "S1_BreakableWall"], ["StaticBody3D", "S2_ParryLedge"], ["StaticBody3D", "S3_LockedDoor"]],
+        "Lighting": [["WorldEnvironment", "WorldEnvironment"], ["DirectionalLight3D", "Sun"]],
+    }
+    for group in skeleton:
+        var parent = ctx.add_node("Node3D", group)
+        for child in skeleton[group]:
+            ctx.add_node(child[0], child[1], parent)
+    ctx.report("skeleton", ctx.summary())
+    ctx.save_scene()
+""")
 ```
 
-Every `summer_add_node` above takes the same required
-`scenePath="res://levels/level_01.tscn"`; it is elided after the first line only
-to keep the tree readable. A call without `scenePath` is rejected by the tool
-schema. Better still, send the whole block as one `summer_batch(scenePath=...,
-ops=[...])` so the user can undo the skeleton with a single Ctrl+Z.
+Compare the `skeleton` report (node counts by class) with the tree you showed the user, then `summer_get_scene_tree` on the new scene.
 
 This is a **skeleton, not playable geometry**. Markers and Area3Ds, no meshes, no enemy scripts. Implementation in subsequent sessions / templates.
 

package/library/skills/design-level/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/design-level
 kind: skill
 version: 1.0.3
-summary: Design a single level — layout, pacing, encounters, secrets, reward gating — outputs a level design doc and a node-tree skeleton for summer_create_scene.
+summary: "Design one level (layout, pacing, encounters, secrets) as a design doc plus a node-tree skeleton."
 use_when:
   - designing a single level — layout, pacing, encounters, secrets, reward gating
   - turning a level idea into a layout with a critical path, encounters, secrets, and pacing beats

package/library/skills/design-mechanic/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design-mechanic
-description: "Design one game mechanic in detail — input, response, feedback, failure modes, depth, tunables — outputs a design doc, node-graph sketch, GDScript stub."
+description: "Design one mechanic in detail (input, feedback, failure modes, tunables) as a doc plus a script stub."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: gameplay-mechanics

package/library/skills/design-mechanic/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/design-mechanic
 kind: skill
 version: 1.0.2
-summary: Design one game mechanic in detail — input, response, feedback, failure modes, depth, tunables — outputs a design doc, node-graph sketch, GDScript stub.
+summary: "Design one mechanic in detail (input, feedback, failure modes, tunables) as a doc plus a script stub."
 use_when:
   - designing one specific game mechanic in detail — input, response, feedback, failure modes, depth, tunables
   - add a grappling hook, dash, double jump, wall run, or parry

package/library/skills/design-npc/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: design-npc
-description: "Design enemy/NPC/boss/companion behavior — perception, personality, intent, action state machine, telegraphs — outputs a GDScript stub plus node tree."
+description: "Design enemy, NPC, boss or companion behavior: perception, state machine, telegraphs, script stub."
 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
+allowed-tools: Read Grep Edit Write summer_get_scene_tree summer_inspect_node summer_run_script 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"]
 ---
 
@@ -179,31 +179,31 @@ Identify where the NPC will live (an `Enemies` parent, or directly under World).
 
 **Preferred (Summer MCP):**
 
-Every tool below takes a required `scenePath` naming the exact `res://` scene;
-it is written out on the first line and elided after for readability. Better
-still, send the whole block as one `summer_batch(scenePath=..., ops=[...])` so
-the user can undo the enemy with a single Ctrl+Z.
+One script builds the whole enemy; `scenePath` names the exact `res://` scene,
+and the run is one undo step, so one Ctrl+Z removes the enemy:
 
 ```
-summer_add_node(scenePath="res://main.tscn", 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)")
+summer_run_script(scenePath="res://main.tscn", source="""
+func run(ctx):
+    var enemy = ctx.add_node("CharacterBody3D", "Enemy", ctx.find("Enemies"))
+    ctx.add_node("CollisionShape3D", "Body", enemy, {"shape": CapsuleShape3D.new()})
+    ctx.add_node("MeshInstance3D", "Mesh", enemy, {"mesh": CapsuleMesh.new()})
+    var vision = ctx.add_node("Area3D", "Vision", enemy)
+    var sight_sphere = SphereShape3D.new()
+    sight_sphere.radius = 12.0
+    ctx.add_node("CollisionShape3D", "VisionShape", vision, {"shape": sight_sphere})
+    ctx.add_node("RayCast3D", "Sight", enemy, {"enabled": true, "target_position": Vector3(0, 0, -12)})
+    ctx.save_scene()
+""")
 ```
 
-Give the Vision area its sphere. Either form works — a class-name string embeds
-the resource in the scene, a `res://` path reuses a shared one. Prefer the shared
-`.tres` when several enemy archetypes want the same sight radius:
+The script embeds the sight sphere in the scene. When several enemy archetypes
+want the same sight radius, share one file instead:
+`{"shape": load("res://shapes/vision_sphere.tres")}`. Tuning one value later is
+one call:
 
 ```
-summer_set_prop(scenePath="res://main.tscn", path="./World/Enemies/Enemy/Vision/VisionShape", key="shape", value="res://shapes/vision_sphere.tres")
-# or, embedded, then tune it:
-summer_set_prop(scenePath="res://main.tscn", path="./World/Enemies/Enemy/Vision/VisionShape", key="shape", value="SphereShape3D")
-summer_set_resource_property(scenePath="res://main.tscn", nodePath="./World/Enemies/Enemy/Vision/VisionShape", resourceProperty="shape", subProperty="radius", value="12.0")
+summer_set_resource_property(scenePath="res://main.tscn", nodePath="./World/Enemies/Enemy/Vision/VisionShape", resourceProperty="shape", subProperty="radius", value="14.0")
 ```
 
 `summer_set_resource_property` works against scene-embedded (`[sub_resource]`)
@@ -224,9 +224,7 @@ summer_connect_signal(scenePath="res://main.tscn", emitter="./World/Enemies/Enem
 ```
 
 The parameters are `scenePath`, `emitter`, `signal`, `receiver`, `method`. There
-is no `from` / `to`; those spellings fail schema validation. The same required
-`scenePath` applies to `summer_add_node`, `summer_set_prop` and
-`summer_save_scene` in the block above.
+is no `from` / `to`; those spellings fail schema validation.
 
 **Fallback (no MCP):** write the scene as `.tscn` text. Ask the user to paste their existing scene first, then propose a unified diff.
 

package/library/skills/design-npc/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/design-npc
 kind: skill
 version: 1.0.2
-summary: Design enemy/NPC/boss/companion behavior — perception, personality, intent, action state machine, telegraphs — outputs a GDScript stub plus node tree.
+summary: "Design enemy, NPC, boss or companion behavior: perception, state machine, telegraphs, script stub."
 use_when:
   - designing an enemy, NPC, boss, companion, civilian, or wave-spawned mob's behavior — perception, intent, state machine, telegraphs, defeat handling
   - enemies that patrol, chase, attack, or flee when they see the player (line of sight)

package/library/skills/diagnosing-perf-regressions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: diagnosing-perf-regressions
-description: "Find why frame rate, frame time, or load time got worse since a known-good state — regression hunting, not general performance tuning."
+description: "Find why frame rate, frame time or load time got worse since a known-good state."
 ---
 
 # Diagnosing Performance Regressions

package/library/skills/diagnosing-perf-regressions/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/diagnosing-perf-regressions
 kind: skill
 version: 1.0.3
-summary: Find why frame rate, frame time, or load time got worse since a known-good state — regression hunting, not general performance tuning.
+summary: "Find why frame rate, frame time or load time got worse since a known-good state."
 use_when:
   - frame rate, frame time, or load time has gotten worse since a known-good state — 'it used to run at 60, now it's at 30'
   - bisecting recent scene, script, or asset changes to find which one slowed frame time or loading

package/library/skills/driving-the-editor-ui/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: driving-the-editor-ui
-description: "Drive the editor UI by name: invoke actions, clear blocking dialogs, switch the main screen, read a dock — and route scene work to the scene tools instead."
+description: "Drive the editor UI by name: run actions, clear blocking dialogs, switch screens, read a dock."
 ---
 
 # Driving the Editor UI

package/library/skills/driving-the-editor-ui/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/driving-the-editor-ui
 kind: skill
 version: 1.0.0
-summary: "Drive the editor UI by name: invoke actions, clear blocking dialogs, switch the main screen, read a dock — and route scene work to the scene tools instead."
+summary: "Drive the editor UI by name: run actions, clear blocking dialogs, switch screens, read a dock."
 use_when:
   - an editor-workflow step a human would do with the mouse — open the Import dock, switch the 2D/3D/Script main screen, toggle a bottom panel, open an editor dialog by name
   - a dialog or popup is blocking the editor and tool calls come back modal_open — see it (summer_ui_tree root dialogs) and clear it (summer_ui_activate action dismiss_dialog)