summer-engine 3.8.0 → 4.0.0

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

@@ -1,6 +1,6 @@
 ---
 name: verification-before-completion
-description: "Run verification commands and confirm output before claiming work complete, fixed, or passing — evidence before assertions, always."
+description: "Run verification and read its output before claiming work done, fixed or passing: evidence first."
 ---
 
 # Verification Before Completion

package/library/skills/verification-before-completion/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/verification-before-completion
 kind: skill
 version: 1.0.3
-summary: Run verification commands and confirm output before claiming work complete, fixed, or passing — evidence before assertions, always.
+summary: "Run verification and read its output before claiming work done, fixed or passing: evidence first."
 use_when:
   - about to claim work is complete, fixed, or passing, before committing or creating PRs
   - about to report a test, build, or fix as passing without having run the command and read its output

package/library/skills/verifying-scenes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: verifying-scenes
-description: "Prove scene work landed (snapshot, diff, screenshots, runtime reads), audit 3D scenes for holes and misplacement, review them with shot sheets and zooms."
+description: "Prove scene work landed: snapshot, diff, screenshots, runtime reads, 3D audits, shot sheets and zooms."
 ---
 
 # Verifying Scenes
@@ -153,7 +153,7 @@ When the next step depends on the engine reaching a moment — the game booting
 - NEVER describe an image you did not receive. A failed capture is a result — report it and climb down (scene → viewport) or ask the user.
 - Preset-framing scene renders are static (t=0), synthetic-camera, flat-environment: no claims about animation, particles, lighting, or mood from them.
 - Pass structured failures (`failure_reason`, `terminalState`) through verbatim — never soften them into "it didn't work".
-- After the result is verified, record the outcome with `summer_library_feedback` (worked / worked with fixes / wrong / outdated / incomplete + a short note). Optional and fire-and-forget; if telemetry is off, move on.
+- After the result is verified, record the outcome with `summer_call` `{"op":"docs.feedback"}` (worked / worked with fixes / wrong / outdated / incomplete + a short note). Optional and fire-and-forget; if telemetry is off, move on.
 
 ## Red Flags — STOP
 

package/library/skills/verifying-scenes/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/verifying-scenes
 kind: skill
 version: 1.5.0
-summary: 'Prove scene work landed (snapshot, diff, screenshots, runtime reads), audit 3D scenes for holes and misplacement, review them with shot sheets and zooms.'
+summary: "Prove scene work landed: snapshot, diff, screenshots, runtime reads, 3D audits, shot sheets and zooms."
 use_when:
   - after any mutation batch, asset import, or lighting change, before claiming it worked
   - during a playtest, to read live runtime state (spawned nodes, actual stats) without stopping the game

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

@@ -1,6 +1,6 @@
 ---
 name: vfx-dissolve
-description: "Dissolve effect — a mesh disintegrating with a glowing burning edge, driven by a noise-threshold ShaderMaterial overriding the target's material."
+description: "Dissolve effect: a mesh burns away with a glowing edge, from a noise-threshold ShaderMaterial."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
@@ -256,7 +256,7 @@ material, no play-mode round-trip:
 
 ```gdscript
 func run(ctx):
-    var mat := ctx.make_shader("<section 2 source>", {"threshold": 0.4})
+    var mat = ctx.make_shader("<section 2 source>", {"threshold": 0.4})
     ctx.apply_material(ctx.find("TestDummy"), mat)   # eyeball it with summer_screenshot
 ```
 

package/library/skills/vfx-dissolve/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/vfx-dissolve
 kind: skill
 version: 1.0.3
-summary: Dissolve effect — a mesh disintegrating with a glowing burning edge, driven by a noise-threshold ShaderMaterial overriding the target's material.
+summary: "Dissolve effect: a mesh burns away with a glowing edge, from a noise-threshold ShaderMaterial."
 use_when:
   - authoring a dissolve effect — an object disintegrating with a glowing burning edge (disintegrate, burn away, vanish into ash)
   - a defeated unit, teleport exit, or removed object should burn away with a glowing edge instead of vanishing

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

@@ -1,6 +1,6 @@
 ---
 name: vfx-fire
-description: "Fire effect — animated flames built with a particle shader, GPUParticles3D, and a noise-based color ramp — torches, campfires, candles."
+description: "Fire effect: animated flames from GPUParticles3D, a particle shader and a noise color ramp."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
@@ -285,50 +285,21 @@ apply here — a draw pass mesh carries its material in `Mesh.material`.
 
 Add an OmniLight3D as a sibling (parented to the same anchor as the GPUParticles3D, NOT under it) for proper light cast. Recommended: `light_color = Color(1.0, 0.6, 0.25)`, `light_energy = 1.6`, `omni_range = 6.0`. Pulse it lightly via the controller for free atmosphere.
 
-### 6. Wire it in (MCP calls)
+### 6. Wire it in
 
-Every scene-mutating call takes an explicit `scenePath`. `summer_set_prop` uses `key`
-(not `property`) and only accepts a string, number, or boolean.
+Write the three files, then wire everything in ONE `summer_run_script` call with
+an explicit `scenePath` — transactional (rollback on a mid-script error), no
+`.tres` sidecar files needed because the script builds the resources directly:
 
 ```
 summer_write_file(path="res://addons/vfx/_building-blocks/noise-3d-fbm.gdshaderinc", content="<from this skill>", create_only=true)
 summer_write_file(path="res://addons/vfx/fire/fire.gdshader", content="<section 2>", create_only=true)
 summer_write_file(path="res://addons/vfx/fire/fire_controller.gd", content="<section 4>", create_only=true)
 
-summer_add_node(scenePath="res://main.tscn", parent="./World/Torch", type="GPUParticles3D", name="Fire")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Torch/Fire", key="script", value="res://addons/vfx/fire/fire_controller.gd")
-
-# ParticleProcessMaterial is a Material, not a Node — you cannot summer_add_node it.
-# Assign the resource by path; the controller configures it on _ready().
-summer_set_prop(scenePath="res://main.tscn", path="./World/Torch/Fire", key="process_material", value="res://addons/vfx/fire/process_mat.tres")
-
-summer_set_prop(scenePath="res://main.tscn", path="./World/Torch/Fire", key="draw_pass_1", value="res://addons/vfx/fire/quad.tres")
-# quad.tres is a QuadMesh with size (1,1) and material = fire_material.tres (ShaderMaterial wrapping fire.gdshader)
-summer_set_resource_property(scenePath="res://main.tscn", nodePath="./World/Torch/Fire", resourceProperty="draw_pass_1", subProperty="size", value="Vector2(1, 1)")
-
-summer_set_prop(scenePath="res://main.tscn", path="./World/Torch/Fire", key="flame_height", value=1.2)
-summer_set_prop(scenePath="res://main.tscn", path="./World/Torch/Fire", key="flame_radius", value=0.35)
-summer_set_prop(scenePath="res://main.tscn", path="./World/Torch/Fire", key="particle_count", value=96)
-
-summer_add_node(scenePath="res://main.tscn", parent="./World/Torch", type="OmniLight3D", name="FireLight")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Torch/FireLight", key="light_color", value="Color(1.0, 0.6, 0.25)")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Torch/FireLight", key="light_energy", value=1.6)
-summer_set_prop(scenePath="res://main.tscn", path="./World/Torch/FireLight", key="omni_range", value=6.0)
-
-summer_save_scene(scenePath="res://main.tscn")
-```
-
-### 6a. One-script wiring (summer_run_script)
-
-On engines with `summer_run_script` (see `scene-scripting`), everything after
-the `summer_write_file` calls above is ONE ctx script — transactional (rollback on a
-mid-script error), no `.tres` sidecar files needed because the script builds the
-resources directly:
-
-```gdscript
+summer_run_script(scenePath="res://main.tscn", source="""
 func run(ctx):
-    var anchor := ctx.find("Torch")
-    var fire := ctx.add_node("GPUParticles3D", "Fire", anchor)
+    var anchor = ctx.find("Torch")
+    var fire = ctx.add_node("GPUParticles3D", "Fire", anchor)
     fire.set_script(load("res://addons/vfx/fire/fire_controller.gd"))
     fire.process_material = ParticleProcessMaterial.new()   # controller configures it on _ready
     var quad := QuadMesh.new()
@@ -343,13 +314,16 @@ func run(ctx):
     ctx.add_node("OmniLight3D", "FireLight", anchor, {
         "light_color": Color(1.0, 0.6, 0.25), "light_energy": 1.6, "omni_range": 6.0})
     ctx.save_scene()
+""")
 ```
 
-`ctx.add_node` sets owners for you. Take a `summer_world_snapshot` before, and verify
-after with `summer_snapshot_diff` (exactly `Fire` + `FireLight` added) plus a
-`summer_screenshot` — flames are pixels, judge them as pixels.
+`ParticleProcessMaterial` is a Material, not a Node: the script assigns it to
+`process_material`, it is never a child. `ctx.add_node` sets owners for you. Take
+a `summer_world_snapshot` before, and verify after with `summer_snapshot_diff`
+(exactly `Fire` + `FireLight` added) plus a `summer_screenshot` — flames are
+pixels, judge them as pixels.
 
-### 6b. Verify
+### 6a. Verify
 
 Every file this recipe writes is compiled code. Check it before claiming the fire works.
 

package/library/skills/vfx-fire/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/vfx-fire
 kind: skill
 version: 1.0.3
-summary: Fire effect — animated flames built with a particle shader, GPUParticles3D, and a noise-based color ramp — torches, campfires, candles.
+summary: "Fire effect: animated flames from GPUParticles3D, a particle shader and a noise color ramp."
 use_when:
   - authoring a fire visual effect — torch, campfire, bonfire, flame, burning object, candle
   - adding fire to props, hazards, or projectiles — torches, braziers, burning wreckage, a fireball or flame jet

package/library/skills/vfx-hit-spark/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vfx-hit-spark
-description: "Hit-spark effect — a one-shot burst of additive billboard particles oriented to a surface normal, fired on impact."
+description: "Hit-spark effect: a one-shot burst of additive particles oriented to the surface, fired on impact."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects

package/library/skills/vfx-hit-spark/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/vfx-hit-spark
 kind: skill
 version: 1.0.2
-summary: Hit-spark effect — a one-shot burst of additive billboard particles oriented to a surface normal, fired on impact.
+summary: "Hit-spark effect: a one-shot burst of additive particles oriented to the surface, fired on impact."
 use_when:
   - authoring a hit-spark effect — impact spark, bullet hit, sword clash, ricochet, sparks at a hit point
   - melee hits, bullet impacts, or ricochets have no visual feedback at the contact point

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

@@ -1,6 +1,6 @@
 ---
 name: vfx-lightning
-description: "Lightning bolt effect — procedural jagged path drawn via ImmediateMesh, glow shader, sparks at endpoints, screen shake."
+description: "Lightning bolt effect: a jagged procedural path with a glow shader, end sparks and screen shake."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
@@ -222,31 +222,22 @@ Recommended: register one `LightningCaster` as an autoload (`/root/Lightning`) s
 
 Place one `LightningCaster` per "world" (or autoload it), then call from gameplay code.
 
-Every scene-mutating call takes an explicit `scenePath`. `summer_set_prop` uses `key`
-(not `property`) and only accepts a string, number, or boolean.
+Write the two files, then place the caster with ONE `summer_run_script` call
+with an explicit `scenePath` — one transactional run, and several casters or
+anything computed is a loop in the same script:
 
 ```
 summer_write_file(path="res://addons/vfx/lightning/lightning.gdshader", content="<section 2>", create_only=true)
 summer_write_file(path="res://addons/vfx/lightning/lightning_caster.gd", content="<section 3>", create_only=true)
 
-summer_add_node(scenePath="res://main.tscn", parent="./World", type="Node3D", name="LightningCaster")
-summer_set_prop(scenePath="res://main.tscn", path="./World/LightningCaster", key="script", value="res://addons/vfx/lightning/lightning_caster.gd")
-summer_set_prop(scenePath="res://main.tscn", path="./World/LightningCaster", key="bolt_color", value="Color(0.55, 0.75, 1.0)")
-summer_set_prop(scenePath="res://main.tscn", path="./World/LightningCaster", key="trauma_amount", value=0.6)
-summer_save_scene(scenePath="res://main.tscn")
-```
-
-Or, on engines with `summer_run_script` (see `scene-scripting`), the two node
-calls collapse into one transactional ctx script — worth it when placing several
-casters or anything computed:
-
-```gdscript
+summer_run_script(scenePath="res://main.tscn", source="""
 func run(ctx):
-    var caster := ctx.add_node("Node3D", "LightningCaster", null)
+    var caster = ctx.add_node("Node3D", "LightningCaster", ctx.find("World"))
     caster.set_script(load("res://addons/vfx/lightning/lightning_caster.gd"))
     caster.set("bolt_color", Color(0.55, 0.75, 1.0))
     caster.set("trauma_amount", 0.6)
     ctx.save_scene()
+""")
 ```
 
 Then verify — the caster `preload`s its own shader, so a shader that failed to write

package/library/skills/vfx-lightning/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/vfx-lightning
 kind: skill
 version: 1.0.3
-summary: Lightning bolt effect — procedural jagged path drawn via ImmediateMesh, glow shader, sparks at endpoints, screen shake.
+summary: "Lightning bolt effect: a jagged procedural path with a glow shader, end sparks and screen shake."
 use_when:
   - authoring a lightning bolt effect — chain lightning, electric attack, tesla coil, shock spell, energy beam
   - a spell, weapon, or hazard needs a jagged electric arc with glow, endpoint sparks, and camera shake

package/library/skills/vfx-magic-glow/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vfx-magic-glow
-description: "Magic-glow effect — a pulsing OmniLight3D plus drifting additive motes plus optional emission shader on the source mesh."
+description: "Magic-glow effect: a pulsing OmniLight3D, drifting additive motes and an optional emission shader."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
@@ -195,42 +195,16 @@ Node3D ("MagicGlow") [script: magic_glow.gd]
 
 ### 4. Wire it in (MCP calls)
 
-For an enchanted sword:
-
-Every scene-mutating call takes an explicit `scenePath`. `summer_set_prop` uses `key`
-(not `property`) and only accepts a string, number, or boolean.
+Write the script once, then wire each glow with ONE `summer_run_script` call
+with an explicit `scenePath` — one transactional run instead of a chain of
+`summer_set_prop` calls. For an enchanted sword:
 
 ```
 summer_write_file(path="res://addons/vfx/magic-glow/magic_glow.gd", content="<section 2>", create_only=true)
 
-summer_add_node(scenePath="res://main.tscn", parent="./Player/Hand/Sword", type="Node3D", name="Glow")
-summer_set_prop(scenePath="res://main.tscn", path="./Player/Hand/Sword/Glow", key="script", value="res://addons/vfx/magic-glow/magic_glow.gd")
-summer_set_prop(scenePath="res://main.tscn", path="./Player/Hand/Sword/Glow", key="glow_color", value="Color(0.55, 0.85, 1.0)")
-summer_set_prop(scenePath="res://main.tscn", path="./Player/Hand/Sword/Glow", key="light_energy_base", value=1.2)
-summer_set_prop(scenePath="res://main.tscn", path="./Player/Hand/Sword/Glow", key="light_energy_amplitude", value=0.6)
-summer_set_prop(scenePath="res://main.tscn", path="./Player/Hand/Sword/Glow", key="mote_count", value=16)
-summer_set_prop(scenePath="res://main.tscn", path="./Player/Hand/Sword/Glow", key="mote_radius", value=0.20)
-summer_set_prop(scenePath="res://main.tscn", path="./Player/Hand/Sword/Glow", key="pulse_source_mesh", value="../Blade")
-summer_save_scene(scenePath="res://main.tscn")
-```
-
-For a soul gem on a pedestal:
-
-```
-summer_add_node(scenePath="res://main.tscn", parent="./World/Pedestal/SoulGem", type="Node3D", name="Glow")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Pedestal/SoulGem/Glow", key="glow_color", value="Color(0.85, 0.45, 1.0)")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Pedestal/SoulGem/Glow", key="pulse_hz", value=0.4)
-summer_set_prop(scenePath="res://main.tscn", path="./World/Pedestal/SoulGem/Glow", key="mote_count", value=32)
-summer_set_prop(scenePath="res://main.tscn", path="./World/Pedestal/SoulGem/Glow", key="mote_radius", value=0.30)
-```
-
-Either wiring block is also ONE ctx script on engines with `summer_run_script`
-(see `scene-scripting`) — the eight `summer_set_prop` calls become one
-transactional run, and computed placement (a glow per gem in a ring) becomes a loop:
-
-```gdscript
+summer_run_script(scenePath="res://main.tscn", source="""
 func run(ctx):
-    var glow := ctx.add_node("Node3D", "Glow", ctx.find("Sword"))
+    var glow = ctx.add_node("Node3D", "Glow", ctx.find("Sword"))
     glow.set_script(load("res://addons/vfx/magic-glow/magic_glow.gd"))
     glow.set("glow_color", Color(0.55, 0.85, 1.0))
     glow.set("light_energy_base", 1.2)
@@ -239,6 +213,23 @@ func run(ctx):
     glow.set("mote_radius", 0.20)
     glow.set("pulse_source_mesh", NodePath("../Blade"))
     ctx.save_scene()
+""")
+```
+
+For a soul gem on a pedestal (computed placement, such as a glow per gem in a
+ring, is a loop in the same script):
+
+```
+summer_run_script(scenePath="res://main.tscn", source="""
+func run(ctx):
+    var glow = ctx.add_node("Node3D", "Glow", ctx.find("SoulGem"))
+    glow.set_script(load("res://addons/vfx/magic-glow/magic_glow.gd"))
+    glow.set("glow_color", Color(0.85, 0.45, 1.0))
+    glow.set("pulse_hz", 0.4)
+    glow.set("mote_count", 32)
+    glow.set("mote_radius", 0.30)
+    ctx.save_scene()
+""")
 ```
 
 Judge the pulse with `summer_screenshot framing:"camera"` — emissive glow does not

package/library/skills/vfx-magic-glow/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/vfx-magic-glow
 kind: skill
 version: 1.0.2
-summary: Magic-glow effect — a pulsing OmniLight3D plus drifting additive motes plus optional emission shader on the source mesh.
+summary: "Magic-glow effect: a pulsing OmniLight3D, drifting additive motes and an optional emission shader."
 use_when:
   - authoring a magic-glow effect — enchanted item, soul gem, pulsing aura, rune glow, magical orb, wisp
   - an item, altar, or portal should read as magical or important with a pulsing light and drifting motes

package/library/skills/vfx-muzzle-flash/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vfx-muzzle-flash
-description: "Muzzle-flash effect — a one-shot ~80 ms burst at a gun barrel built with a particle one-shot or a flashing quad with a star-burst shader."
+description: "Muzzle-flash effect: a one-shot ~80 ms burst at a gun barrel, from particles or a star-burst quad."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
@@ -201,54 +201,39 @@ Node3D ("MuzzleFlash") [script: muzzle_flash.gd]
 
 Place the node at the **barrel tip** of the weapon. If your gun model has a `BarrelTip` Marker3D, parent there directly.
 
-Every scene-mutating call takes an explicit `scenePath`. `summer_set_prop` uses `key`
-(not `property`) and only accepts a string, number, or boolean.
+Write the two files, then mount the flash with ONE `summer_run_script` call with
+an explicit `scenePath` — one transactional run, and mounting a flash on every
+weapon in the scene is a loop instead of a chain of calls per gun:
 
 ```
 summer_write_file(path="res://addons/vfx/muzzle-flash/muzzle_flash.gdshader", content="<section 2>", create_only=true)
 summer_write_file(path="res://addons/vfx/muzzle-flash/muzzle_flash.gd", content="<section 3>", create_only=true)
 
-summer_add_node(scenePath="res://main.tscn", parent="./Player/Weapon/BarrelTip", type="Node3D", name="MuzzleFlash")
-summer_set_prop(scenePath="res://main.tscn", path="./Player/Weapon/BarrelTip/MuzzleFlash", key="script", value="res://addons/vfx/muzzle-flash/muzzle_flash.gd")
-summer_set_prop(scenePath="res://main.tscn", path="./Player/Weapon/BarrelTip/MuzzleFlash", key="flash_size", value=0.6)
-summer_set_prop(scenePath="res://main.tscn", path="./Player/Weapon/BarrelTip/MuzzleFlash", key="flash_duration", value=0.08)
-summer_set_prop(scenePath="res://main.tscn", path="./Player/Weapon/BarrelTip/MuzzleFlash", key="light_energy", value=4.0)
-summer_save_scene(scenePath="res://main.tscn")
-```
-
-Then in your weapon script, on `fire()`:
-
-```gdscript
-$BarrelTip/MuzzleFlash.fire()
-```
-
-Or connect the weapon's `fired` signal in the scene:
-
-```
-summer_connect_signal(scenePath="res://main.tscn", emitter="./Player/Weapon", signal="fired", receiver="./Player/Weapon/BarrelTip/MuzzleFlash", method="fire")
-```
-
-### 5a. One-script wiring (summer_run_script)
-
-On engines with `summer_run_script` (see `scene-scripting`), the node calls
-above are ONE transactional ctx script — and mounting a flash on every weapon in the
-scene becomes a loop instead of a CRUD chain per gun:
-
-```gdscript
+summer_run_script(scenePath="res://main.tscn", source="""
 func run(ctx):
-    var tip := ctx.find("BarrelTip")
-    var flash := ctx.add_node("Node3D", "MuzzleFlash", tip)
+    var tip = ctx.find("BarrelTip")
+    var flash = ctx.add_node("Node3D", "MuzzleFlash", tip)
     flash.set_script(load("res://addons/vfx/muzzle-flash/muzzle_flash.gd"))
     flash.set("flash_size", 0.6)
     flash.set("flash_duration", 0.08)
     flash.set("light_energy", 4.0)
-    var weapon := ctx.find("Weapon")
+    var weapon = ctx.find("Weapon")
     weapon.connect("fired", Callable(flash, "fire"), CONNECT_PERSIST)
-    # CONNECT_PERSIST is required — a bare connect() works live but is NOT saved
+    # CONNECT_PERSIST is required: a bare connect() works live but is NOT saved
     ctx.save_scene()
+""")
 ```
 
-### 5b. Verify
+Then in your weapon script, on `fire()`:
+
+```gdscript
+$BarrelTip/MuzzleFlash.fire()
+```
+
+The script above already connects the weapon's `fired` signal to the flash; the
+one-call form is `summer_connect_signal(scenePath="res://main.tscn", emitter="./Player/Weapon", signal="fired", receiver="./Player/Weapon/BarrelTip/MuzzleFlash", method="fire")`.
+
+### 5a. Verify
 
 `muzzle_flash.gd` `preload`s its own shader, so a shader that failed to write takes
 the script down at parse time. Check before firing a shot.

package/library/skills/vfx-muzzle-flash/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/vfx-muzzle-flash
 kind: skill
 version: 1.0.3
-summary: Muzzle-flash effect — a one-shot ~80 ms burst at a gun barrel built with a particle one-shot or a flashing quad with a star-burst shader.
+summary: "Muzzle-flash effect: a one-shot ~80 ms burst at a gun barrel, from particles or a star-burst quad."
 use_when:
   - authoring a muzzle-flash effect — gun fire, weapon flash, barrel flash, spell-cast burst at a hand
   - a gun or spell-casting hand shoots with no visible flash at the barrel or palm

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

@@ -1,6 +1,6 @@
 ---
 name: vfx-smoke
-description: "Smoke effect — a slow-rising column or puff of soft particles built with a noise + density falloff shader on a quad mesh, GPUParticles3D."
+description: "Smoke effect: a rising column or puff of soft particles with a noise and density falloff shader."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
@@ -228,42 +228,19 @@ child nodes, and `ParticleProcessMaterial` is a `Material` — you cannot
 
 ### 5. Wire it in (MCP calls)
 
-Every scene-mutating call takes an explicit `scenePath`. `summer_set_prop` uses `key`
-(not `property`) and only accepts a string, number, or boolean.
-
-For chimney smoke or fire pairing, parent the Smoke just above the heat source:
+Write the three files, then wire the emitter with ONE `summer_run_script` call
+with an explicit `scenePath` — transactional, and it builds the QuadMesh +
+ShaderMaterial resources directly instead of `.tres` sidecars. For chimney
+smoke, parent the Smoke just above the heat source:
 
 ```
 summer_write_file(path="res://addons/vfx/_building-blocks/noise-3d-fbm.gdshaderinc", content="<from this skill>", create_only=true)
 summer_write_file(path="res://addons/vfx/smoke/smoke.gdshader", content="<section 2>", create_only=true)
 summer_write_file(path="res://addons/vfx/smoke/smoke_controller.gd", content="<section 3>", create_only=true)
 
-summer_add_node(scenePath="res://main.tscn", parent="./World/Cottage/Chimney", type="GPUParticles3D", name="Smoke")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Cottage/Chimney/Smoke", key="script", value="res://addons/vfx/smoke/smoke_controller.gd")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Cottage/Chimney/Smoke", key="position", value="Vector3(0, 0.3, 0)")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Cottage/Chimney/Smoke", key="rise_height", value=4.0)
-summer_set_prop(scenePath="res://main.tscn", path="./World/Cottage/Chimney/Smoke", key="particle_count", value=48)
-summer_set_prop(scenePath="res://main.tscn", path="./World/Cottage/Chimney/Smoke", key="wind_direction", value="Vector3(0.4, 0, 0.1)")
-summer_save_scene(scenePath="res://main.tscn")
-```
-
-For pairing with a fire:
-
-```
-summer_add_node(scenePath="res://main.tscn", parent="./World/Campfire", type="GPUParticles3D", name="Smoke")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Campfire/Smoke", key="position", value="Vector3(0, 1.5, 0)")  # above flame top
-summer_set_prop(scenePath="res://main.tscn", path="./World/Campfire/Smoke", key="rise_height", value=3.0)
-```
-
-### 5a. One-script wiring (summer_run_script)
-
-On engines with `summer_run_script` (see `scene-scripting`), the node wiring
-above is ONE ctx script — transactional, and it builds the QuadMesh + ShaderMaterial
-resources directly instead of `.tres` sidecars:
-
-```gdscript
+summer_run_script(scenePath="res://main.tscn", source="""
 func run(ctx):
-    var smoke := ctx.add_node("GPUParticles3D", "Smoke", ctx.find("Chimney"))
+    var smoke = ctx.add_node("GPUParticles3D", "Smoke", ctx.find("Chimney"))
     smoke.set_script(load("res://addons/vfx/smoke/smoke_controller.gd"))
     smoke.process_material = ParticleProcessMaterial.new()
     var quad := QuadMesh.new()
@@ -277,11 +254,16 @@ func run(ctx):
     smoke.set("particle_count", 48)
     smoke.set("wind_direction", Vector3(0.4, 0, 0.1))
     ctx.save_scene()
+""")
 ```
 
+For pairing with a fire, run the same script with `ctx.find("Campfire")` as the
+parent, `position = Vector3(0, 1.5, 0)` (above the flame top) and
+`rise_height` 3.0.
+
 Verify with `summer_snapshot_diff` (exactly one node added) and a `summer_screenshot`.
 
-### 5b. Verify
+### 5a. Verify
 
 The shader and the controller are compiled code. Check them before tuning anything.
 

package/library/skills/vfx-smoke/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/vfx-smoke
 kind: skill
 version: 1.0.2
-summary: Smoke effect — a slow-rising column or puff of soft particles built with a noise + density falloff shader on a quad mesh, GPUParticles3D.
+summary: "Smoke effect: a rising column or puff of soft particles with a noise and density falloff shader."
 use_when:
   - authoring a smoke effect — smoke trail, puff, chimney smoke, steam, fog cloud, explosion smoke
   - a chimney, campfire, explosion, or vent needs a rising smoke column or puff in a 3D scene

package/library/skills/vfx-water-ripple/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vfx-water-ripple
-description: "Water-ripple effect — animated normal-distortion ripples on a water plane (or as a Decal) triggered by impacts."
+description: "Water-ripple effect: animated normal-distortion ripples on a water plane or Decal, set off by impacts."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
@@ -221,54 +221,35 @@ MeshInstance3D ("Water") [script: water_ripple_surface.gd]
 
 ### 5. Wire it in (MCP calls)
 
-Every scene-mutating call takes an explicit `scenePath`. `summer_set_prop` uses `key`
-(not `property`); `summer_set_resource_property` always needs a `subProperty` and is
-for reaching *into* a resource, not for assigning one.
+Write the two files, then wire the surface with ONE `summer_run_script` call
+with an explicit `scenePath` — transactional, and it builds the subdivided
+PlaneMesh directly, so no `plane.tres` sidecar is needed:
 
 ```
 summer_write_file(path="res://addons/vfx/water-ripple/water_ripple.gdshader", content="<section 2>", create_only=true)
 summer_write_file(path="res://addons/vfx/water-ripple/water_ripple_surface.gd", content="<section 3>", create_only=true)
 
-summer_add_node(scenePath="res://main.tscn", parent="./World", type="MeshInstance3D", name="Puddle")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Puddle", key="script", value="res://addons/vfx/water-ripple/water_ripple_surface.gd")
-summer_set_prop(scenePath="res://main.tscn", path="./World/Puddle", key="position", value="Vector3(0, 0.01, 0)")
-
-# Whole resources are assigned by path with summer_set_prop.
-summer_set_prop(scenePath="res://main.tscn", path="./World/Puddle", key="mesh", value="res://addons/vfx/water-ripple/plane.tres")
-# `normal_texture` is an exported script property on the controller, not a
-# MeshInstance3D property — MeshInstance3D has no `normal_texture`.
-summer_set_prop(scenePath="res://main.tscn", path="./World/Puddle", key="normal_texture", value="res://addons/vfx/water-ripple/water_normals.png")
-
-# subProperty is required — this is how you reach into the PlaneMesh itself.
-summer_set_resource_property(scenePath="res://main.tscn", nodePath="./World/Puddle", resourceProperty="mesh", subProperty="subdivide_width", value=32)
-summer_set_resource_property(scenePath="res://main.tscn", nodePath="./World/Puddle", resourceProperty="mesh", subProperty="subdivide_depth", value=32)
-
-summer_save_scene(scenePath="res://main.tscn")
-```
-
-### 5a. One-script wiring (summer_run_script)
-
-On engines with `summer_run_script` (see `scene-scripting`), the node and
-resource wiring is ONE transactional ctx script — and it builds the subdivided
-PlaneMesh directly, so the `plane.tres` sidecar disappears:
-
-```gdscript
+summer_run_script(scenePath="res://main.tscn", source="""
 func run(ctx):
-    var puddle := ctx.add_node("MeshInstance3D", "Puddle", null)
+    var puddle = ctx.add_node("MeshInstance3D", "Puddle", ctx.find("World"))
     var plane := PlaneMesh.new()
     plane.subdivide_width = 32
     plane.subdivide_depth = 32
     puddle.mesh = plane
     puddle.position = Vector3(0, 0.01, 0)
     puddle.set_script(load("res://addons/vfx/water-ripple/water_ripple_surface.gd"))
+    # normal_texture is an exported property of the controller script, not of MeshInstance3D
     puddle.set("normal_texture", load("res://addons/vfx/water-ripple/water_normals.png"))
     ctx.save_scene()
+""")
 ```
 
 Set the mesh BEFORE the script if the controller reads it in `_ready`; either way,
-`ctx.add_node` has already owned the node, so it survives the save.
+`ctx.add_node` has already owned the node, so it survives the save. Tuning one
+mesh value later is one `summer_set_resource_property` call (`resourceProperty="mesh"`,
+`subProperty="subdivide_width"`): it reaches into a resource, it never assigns one.
 
-### 5b. Verify
+### 5a. Verify
 
 The shader and the controller are compiled code, and the controller `preload`s the
 shader — a shader that failed to write takes the script down at parse time.

package/library/skills/vfx-water-ripple/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/vfx-water-ripple
 kind: skill
 version: 1.0.2
-summary: Water-ripple effect — animated normal-distortion ripples on a water plane (or as a Decal) triggered by impacts.
+summary: "Water-ripple effect: animated normal-distortion ripples on a water plane or Decal, set off by impacts."
 use_when:
   - authoring a water-ripple effect — raindrop ripples, splash ripples, footstep in a puddle, fish jumps
   - rain, footsteps, or falling objects should disturb a water surface with spreading ripples