summer-engine 2.8.2 → 3.1.0

package/{skills/visual-effects/recipes/fire → library/skills/vfx-fire}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: fire
+name: vfx-fire
 description: Use when authoring a fire visual effect — animated flames built with a particle shader, GPUParticles3D, and a noise-based color ramp. Trigger on "torch", "campfire", "bonfire", "flame", "fire effect", "burning", "make this thing on fire", "candle".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
 user-invocable: true
-allowed-tools: Read Write Edit summer_write_file summer_read_file summer_create_scene summer_add_node summer_set_prop summer_set_resource_property summer_inspect_node summer_inspect_resource summer_save_scene summer_get_script_errors summer_get_debugger_errors summer_play summer_stop
+allowed-tools: Read Write Edit summer_write_file summer_read_file summer_create_scene summer_add_node summer_set_prop summer_set_resource_property summer_inspect_node summer_inspect_resource summer_save_scene summer_run_script summer_world_snapshot summer_snapshot_diff summer_screenshot summer_get_script_errors summer_get_debugger_errors summer_play summer_stop
 paths: ["**/*.tscn", "**/*.gd", "**/*.gdshader", "addons/vfx/**"]
 ---
 
@@ -318,6 +318,37 @@ summer_set_prop(scenePath="res://main.tscn", path="./World/Torch/FireLight", key
 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
+func run(ctx):
+    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()
+    quad.size = Vector2(1, 1)
+    var mat := ShaderMaterial.new()
+    mat.shader = load("res://addons/vfx/fire/fire.gdshader")
+    quad.material = mat
+    fire.draw_pass_1 = quad
+    fire.set("flame_height", 1.2)
+    fire.set("flame_radius", 0.35)
+    fire.set("particle_count", 96)
+    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.
+
 ### 6b. Verify
 
 Every file this recipe writes is compiled code. Check it before claiming the fire works.
@@ -457,18 +488,18 @@ manually in Summer Engine:
 
 After firing this recipe, suggest neighbors:
 
-- `summer:visual-effects/recipes/smoke` — every fire that lasts > 5 s wants smoke rising above. Spawn 0.5 m above the flame top.
-- `summer:visual-effects/recipes/dissolve` — if the user wants the *fuel* (logs, body, paper) to gradually disappear as it burns.
-- `summer:visual-effects/recipes/magic-glow` — for an `OmniLight3D` with proper sin-wave pulsing if the default is too constant.
-- `summer:visual-effects/game-feel` — for a slight camera flicker / thermal heat-haze post-process near very large fires.
-- `summer:audio/sound-effect` — generate `fire crackle, dry wood, soft pops, 2s loop` and wire to an `AudioStreamPlayer3D` on the same anchor.
+- `vfx-smoke` — every fire that lasts > 5 s wants smoke rising above. Spawn 0.5 m above the flame top.
+- `vfx-dissolve` — if the user wants the *fuel* (logs, body, paper) to gradually disappear as it burns.
+- `vfx-magic-glow` — for an `OmniLight3D` with proper sin-wave pulsing if the default is too constant.
+- `game-feel` — for a slight camera flicker / thermal heat-haze post-process near very large fires.
+- `sound-effect` — generate `fire crackle, dry wood, soft pops, 2s loop` and wire to an `AudioStreamPlayer3D` on the same anchor.
 
 ## See also
 
 - `_building-blocks/noise-3d-fbm.gdshaderinc` — the FBM noise this shader includes
 - `_building-blocks/additive-billboard-particles.md` — canonical additive material settings
-- `summer:visual-effects/recipes/smoke` — sister recipe for the column rising above
-- `summer:visual-effects/recipes/dissolve` — for objects burning away
-- `summer:visual-effects/recipes/magic-glow` — for the light source pulsing
-- `summer:visual-effects/game-feel` — non-particle game-feel pairings
-- `summer:gdscript-patterns` — for the controller's idioms (signals, exports, `@tool`)
+- `vfx-smoke` — sister recipe for the column rising above
+- `vfx-dissolve` — for objects burning away
+- `vfx-magic-glow` — for the light source pulsing
+- `game-feel` — non-particle game-feel pairings
+- `gdscript-patterns` — for the controller's idioms (signals, exports, `@tool`)

package/library/skills/vfx-fire/_building-blocks/noise-3d-fbm.gdshaderinc

@@ -0,0 +1,45 @@
+// 3D Fractal Brownian Motion noise — used by fire, dissolve, smoke, magic-glow.
+// Include with: #include "res://addons/vfx/_building-blocks/noise-3d-fbm.gdshaderinc"
+
+float hash3(vec3 p) {
+    p = fract(p * vec3(443.8975, 397.2973, 491.1871));
+    p += dot(p, p.yxz + 19.19);
+    return fract((p.x + p.y) * p.z);
+}
+
+float noise3(vec3 p) {
+    vec3 i = floor(p);
+    vec3 f = fract(p);
+    f = f * f * (3.0 - 2.0 * f);
+
+    float n000 = hash3(i + vec3(0.0, 0.0, 0.0));
+    float n100 = hash3(i + vec3(1.0, 0.0, 0.0));
+    float n010 = hash3(i + vec3(0.0, 1.0, 0.0));
+    float n110 = hash3(i + vec3(1.0, 1.0, 0.0));
+    float n001 = hash3(i + vec3(0.0, 0.0, 1.0));
+    float n101 = hash3(i + vec3(1.0, 0.0, 1.0));
+    float n011 = hash3(i + vec3(0.0, 1.0, 1.0));
+    float n111 = hash3(i + vec3(1.0, 1.0, 1.0));
+
+    float x00 = mix(n000, n100, f.x);
+    float x10 = mix(n010, n110, f.x);
+    float x01 = mix(n001, n101, f.x);
+    float x11 = mix(n011, n111, f.x);
+
+    float y0 = mix(x00, x10, f.y);
+    float y1 = mix(x01, x11, f.y);
+
+    return mix(y0, y1, f.z);
+}
+
+float fbm3(vec3 p) {
+    float v = 0.0;
+    float amp = 0.5;
+    float freq = 1.0;
+    for (int i = 0; i < 4; i++) {
+        v += amp * noise3(p * freq);
+        freq *= 2.0;
+        amp *= 0.5;
+    }
+    return v;
+}

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

@@ -0,0 +1,35 @@
+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.
+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
+facets:
+  lifecycle:
+    - build
+  domains:
+    - vfx
+    - rendering
+  modalities:
+    - scenes
+    - shaders
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/scene-scripting
+    - skill/sound-effect
+    - skill/game-feel
+    - skill/vfx-dissolve
+    - skill/vfx-hit-spark
+    - skill/vfx-magic-glow
+    - skill/vfx-muzzle-flash
+    - skill/vfx-smoke
+source: official
+license: MIT
+status: stable
+recommended: true
+aliases:
+  - skills/visual-effects/recipes/fire
+  - fire

package/{skills/visual-effects/recipes/hit-spark → library/skills/vfx-hit-spark}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: hit-spark
+name: vfx-hit-spark
 description: Use when authoring a hit-spark visual effect — a one-shot burst of additive billboard particles oriented to a surface normal, fired on impact. Trigger on "hit spark", "impact spark", "bullet hit", "sword clash", "metal-on-metal", "ricochet", "impact effect", "spawn sparks at hit point".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
@@ -192,6 +192,12 @@ summer_set_prop(scenePath="res://addons/vfx/hit-spark/hit_spark.tscn", path=".",
 summer_save_scene(scenePath="res://addons/vfx/hit-spark/hit_spark.tscn")
 ```
 
+Note on the script lane: `summer_run_script` operates on the **open** scene, and
+this recipe builds a standalone `hit_spark.tscn` — so the `summer_create_scene` /
+`summer_replace_node` chain above stays the right wiring here. Reach for
+`scene-scripting` only if you are placing many pre-spawned spark emitters
+into the open scene with computed positions.
+
 ### 4b. Verify
 
 `hit_spark.gd` is the whole recipe — if it did not parse, every `spawn_hit_spark`
@@ -352,16 +358,16 @@ manually in Summer Engine:
 
 After firing this recipe, suggest:
 
-- `summer:visual-effects/recipes/muzzle-flash` — pair on the gun side; this recipe handles the bullet-impact side.
-- `summer:visual-effects/recipes/lightning` — automatically calls this at endpoints.
-- `summer:visual-effects/recipes/water-ripple` — pair the `water-droplet` variant with a ripple ring at the impact for water surfaces.
-- `summer:visual-effects/game-feel` — `CameraShake.add_trauma(0.15)` on heavy hits, hit-stop for crit kills.
-- `summer:audio/sound-effect` — generate `metal-on-metal clang, sharp transient, short ring, 350ms` per spark variant.
+- `vfx-muzzle-flash` — pair on the gun side; this recipe handles the bullet-impact side.
+- `vfx-lightning` — automatically calls this at endpoints.
+- `vfx-water-ripple` — pair the `water-droplet` variant with a ripple ring at the impact for water surfaces.
+- `game-feel` — `CameraShake.add_trauma(0.15)` on heavy hits, hit-stop for crit kills.
+- `sound-effect` — generate `metal-on-metal clang, sharp transient, short ring, 350ms` per spark variant.
 
 ## See also
 
 - `_building-blocks/additive-billboard-particles.md` — canonical additive material settings (this recipe uses them)
-- `summer:visual-effects/recipes/muzzle-flash` — the gun-end companion
-- `summer:visual-effects/recipes/lightning` — caller; spawns sparks at bolt endpoints
-- `summer:visual-effects/recipes/water-ripple` — surface companion for water impacts
-- `summer:visual-effects/game-feel` — shake/hit-stop pairings
+- `vfx-muzzle-flash` — the gun-end companion
+- `vfx-lightning` — caller; spawns sparks at bolt endpoints
+- `vfx-water-ripple` — surface companion for water impacts
+- `game-feel` — shake/hit-stop pairings

package/library/skills/vfx-hit-spark/_building-blocks/additive-billboard-particles.md

@@ -0,0 +1,37 @@
+# Additive Billboard Particles — Canonical Material Settings
+
+Reusable material configuration for additive particle billboards (motes, sparks, glow, ash). Used by `magic-glow`, optionally substitutable in `hit-spark` and `fire` if a custom shader is overkill.
+
+`BaseMaterial3D` is abstract — `BaseMaterial3D.new()` is a parse error ("Native class
+"BaseMaterial3D" cannot be constructed as it is abstract"). Instantiate
+`StandardMaterial3D`; the `BaseMaterial3D.*` enum constants below are still the right
+way to name the values.
+
+## Settings
+
+```gdscript
+var bm := StandardMaterial3D.new()
+bm.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA
+bm.blend_mode = BaseMaterial3D.BLEND_MODE_ADD
+bm.shading_mode = BaseMaterial3D.SHADING_MODE_UNSHADED
+bm.billboard_mode = BaseMaterial3D.BILLBOARD_PARTICLES
+bm.emission_enabled = true
+bm.emission_energy_multiplier = 3.0   # 1.0–5.0 typical; bump for HDR bloom
+bm.disable_receive_shadows = true
+bm.shadow_to_opacity = false
+bm.no_depth_test = false              # true only if particles must read on TOP of opaque geometry
+bm.billboard_keep_scale = true        # BILLBOARD_PARTICLES drops per-particle scale without this
+bm.albedo_color = Color(R, G, B, 1.0)
+bm.emission = Color(R, G, B)          # usually same as albedo for single-color motes
+```
+
+## When to use this vs a custom shader
+
+- **Use this `StandardMaterial3D` config** when the effect is just a tinted soft-circle mote (magic glow, sparkles, dust). Less code, faster iteration, free Godot-managed billboard math.
+- **Per-particle color over age does NOT need a custom shader.** `ParticleProcessMaterial` has `color_ramp`, `color_initial_ramp`, `alpha_curve` and `emission_curve` (all verified present in 4.6) — those drive the particle's `COLOR` from age and feed straight into a plain `StandardMaterial3D`. Reach for a ramp before reaching for a shader.
+- **Use a custom `ShaderMaterial`** when you need per-fragment shape masks (muzzle flash star burst), noise-distorted UVs (fire, smoke), or anything that varies *within* the quad. Those are what `StandardMaterial3D` genuinely can't express.
+- If a custom shader does need the particle age, note that the age lives in `INSTANCE_CUSTOM.y` (normalized by `INSTANCE_CUSTOM.w`, the lifetime), that `INSTANCE_CUSTOM.x` is the rotation angle — not the age — and that `INSTANCE_CUSTOM` is **vertex-stage only**. Pass it to `fragment()` through a `varying`.
+
+## Performance note
+
+Additive overdraw is fillrate-bound. `draw_pass_1` is a `Mesh`, so the size dial is on the mesh: keep `QuadMesh.size` at or under `Vector2(0.2, 0.2)` for motes/sparks. Larger quads at full additive intensity destroy mobile fillrate budgets fast.

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

@@ -0,0 +1,34 @@
+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.
+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
+facets:
+  lifecycle:
+    - build
+  domains:
+    - vfx
+    - rendering
+  modalities:
+    - scenes
+    - shaders
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/scene-scripting
+    - skill/sound-effect
+    - skill/game-feel
+    - skill/vfx-fire
+    - skill/vfx-lightning
+    - skill/vfx-muzzle-flash
+    - skill/vfx-water-ripple
+source: official
+license: MIT
+status: stable
+recommended: false
+aliases:
+  - skills/visual-effects/recipes/hit-spark
+  - hit-spark

package/{skills/visual-effects/recipes/lightning → library/skills/vfx-lightning}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: lightning
+name: vfx-lightning
 description: Use when authoring a lightning bolt visual effect — procedural jagged path drawn via ImmediateMesh, glow shader, sparks at endpoints, screen shake. Trigger on "lightning bolt", "chain lightning", "electric attack", "tesla coil", "shock spell", "thunderbolt", "energy beam".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
 user-invocable: true
-allowed-tools: Read Write Edit summer_write_file summer_read_file summer_create_scene summer_add_node summer_set_prop summer_set_resource_property summer_inspect_node summer_save_scene summer_project_setting summer_get_script_errors summer_get_debugger_errors summer_play summer_stop
+allowed-tools: Read Write Edit summer_write_file summer_read_file summer_create_scene summer_add_node summer_set_prop summer_set_resource_property summer_inspect_node summer_save_scene summer_run_script summer_project_setting summer_get_script_errors summer_get_debugger_errors summer_play summer_stop
 paths: ["**/*.tscn", "**/*.gd", "**/*.gdshader", "addons/vfx/**"]
 ---
 
@@ -236,6 +236,19 @@ summer_set_prop(scenePath="res://main.tscn", path="./World/LightningCaster", key
 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
+func run(ctx):
+    var caster := ctx.add_node("Node3D", "LightningCaster", null)
+    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
 takes the whole script down at parse time:
 
@@ -388,17 +401,17 @@ manually in Summer Engine:
 
 After firing this recipe, suggest:
 
-- `summer:visual-effects/recipes/hit-spark` — automatically called at endpoints; tune the spark color to match `bolt_color`.
-- `summer:visual-effects/recipes/magic-glow` — for the wizard's hand glow during charge-up before the cast.
-- `summer:visual-effects/recipes/muzzle-flash` — for the brief bright flash at the casting hand on release frame.
-- `summer:visual-effects/game-feel` — `CameraShake.add_trauma` is already called; pair with hit-stop on the target for impact emphasis.
-- `summer:audio/sound-effect` — generate `electric crack thunder, sharp impact, rumble tail, 800ms` and play on cast.
+- `vfx-hit-spark` — automatically called at endpoints; tune the spark color to match `bolt_color`.
+- `vfx-magic-glow` — for the wizard's hand glow during charge-up before the cast.
+- `vfx-muzzle-flash` — for the brief bright flash at the casting hand on release frame.
+- `game-feel` — `CameraShake.add_trauma` is already called; pair with hit-stop on the target for impact emphasis.
+- `sound-effect` — generate `electric crack thunder, sharp impact, rumble tail, 800ms` and play on cast.
 
 ## See also
 
 - `_building-blocks/trauma-shake-snippet.md` — `CameraShake` autoload (REQUIRED for the shake call)
 - `_building-blocks/additive-billboard-particles.md` — for the endpoint sparks
-- `summer:visual-effects/recipes/hit-spark` — endpoint companion
-- `summer:visual-effects/recipes/magic-glow` — pre-cast charge-up
-- `summer:visual-effects/recipes/muzzle-flash` — for the cast-release flash
-- `summer:visual-effects/game-feel` — full game-feel pairing
+- `vfx-hit-spark` — endpoint companion
+- `vfx-magic-glow` — pre-cast charge-up
+- `vfx-muzzle-flash` — for the cast-release flash
+- `game-feel` — full game-feel pairing

package/library/skills/vfx-lightning/_building-blocks/additive-billboard-particles.md

@@ -0,0 +1,37 @@
+# Additive Billboard Particles — Canonical Material Settings
+
+Reusable material configuration for additive particle billboards (motes, sparks, glow, ash). Used by `magic-glow`, optionally substitutable in `hit-spark` and `fire` if a custom shader is overkill.
+
+`BaseMaterial3D` is abstract — `BaseMaterial3D.new()` is a parse error ("Native class
+"BaseMaterial3D" cannot be constructed as it is abstract"). Instantiate
+`StandardMaterial3D`; the `BaseMaterial3D.*` enum constants below are still the right
+way to name the values.
+
+## Settings
+
+```gdscript
+var bm := StandardMaterial3D.new()
+bm.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA
+bm.blend_mode = BaseMaterial3D.BLEND_MODE_ADD
+bm.shading_mode = BaseMaterial3D.SHADING_MODE_UNSHADED
+bm.billboard_mode = BaseMaterial3D.BILLBOARD_PARTICLES
+bm.emission_enabled = true
+bm.emission_energy_multiplier = 3.0   # 1.0–5.0 typical; bump for HDR bloom
+bm.disable_receive_shadows = true
+bm.shadow_to_opacity = false
+bm.no_depth_test = false              # true only if particles must read on TOP of opaque geometry
+bm.billboard_keep_scale = true        # BILLBOARD_PARTICLES drops per-particle scale without this
+bm.albedo_color = Color(R, G, B, 1.0)
+bm.emission = Color(R, G, B)          # usually same as albedo for single-color motes
+```
+
+## When to use this vs a custom shader
+
+- **Use this `StandardMaterial3D` config** when the effect is just a tinted soft-circle mote (magic glow, sparkles, dust). Less code, faster iteration, free Godot-managed billboard math.
+- **Per-particle color over age does NOT need a custom shader.** `ParticleProcessMaterial` has `color_ramp`, `color_initial_ramp`, `alpha_curve` and `emission_curve` (all verified present in 4.6) — those drive the particle's `COLOR` from age and feed straight into a plain `StandardMaterial3D`. Reach for a ramp before reaching for a shader.
+- **Use a custom `ShaderMaterial`** when you need per-fragment shape masks (muzzle flash star burst), noise-distorted UVs (fire, smoke), or anything that varies *within* the quad. Those are what `StandardMaterial3D` genuinely can't express.
+- If a custom shader does need the particle age, note that the age lives in `INSTANCE_CUSTOM.y` (normalized by `INSTANCE_CUSTOM.w`, the lifetime), that `INSTANCE_CUSTOM.x` is the rotation angle — not the age — and that `INSTANCE_CUSTOM` is **vertex-stage only**. Pass it to `fragment()` through a `varying`.
+
+## Performance note
+
+Additive overdraw is fillrate-bound. `draw_pass_1` is a `Mesh`, so the size dial is on the mesh: keep `QuadMesh.size` at or under `Vector2(0.2, 0.2)` for motes/sparks. Larger quads at full additive intensity destroy mobile fillrate budgets fast.

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

@@ -0,0 +1,33 @@
+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.
+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
+facets:
+  lifecycle:
+    - build
+  domains:
+    - vfx
+    - rendering
+  modalities:
+    - scenes
+    - shaders
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/scene-scripting
+    - skill/sound-effect
+    - skill/game-feel
+    - skill/vfx-hit-spark
+    - skill/vfx-magic-glow
+    - skill/vfx-muzzle-flash
+source: official
+license: MIT
+status: stable
+recommended: false
+aliases:
+  - skills/visual-effects/recipes/lightning
+  - lightning

package/{skills/visual-effects/recipes/magic-glow → library/skills/vfx-magic-glow}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: magic-glow
+name: vfx-magic-glow
 description: Use when authoring a magic-glow visual effect — a pulsing OmniLight3D plus drifting additive motes plus optional emission shader on the source mesh. Trigger on "magic glow", "enchanted item", "soul gem", "pulsing aura", "rune glow", "magical orb", "summon circle glow", "fairy", "wisp".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
 user-invocable: true
-allowed-tools: Read Write Edit summer_write_file summer_read_file summer_create_scene summer_add_node summer_set_prop summer_set_resource_property summer_inspect_node summer_save_scene summer_get_script_errors summer_get_debugger_errors summer_play summer_stop
+allowed-tools: Read Write Edit summer_write_file summer_read_file summer_create_scene summer_add_node summer_set_prop summer_set_resource_property summer_inspect_node summer_save_scene summer_run_script summer_screenshot summer_get_script_errors summer_get_debugger_errors summer_play summer_stop
 paths: ["**/*.tscn", "**/*.gd", "**/*.gdshader", "addons/vfx/**"]
 ---
 
@@ -224,6 +224,26 @@ summer_set_prop(scenePath="res://main.tscn", path="./World/Pedestal/SoulGem/Glow
 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
+func run(ctx):
+    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)
+    glow.set("light_energy_amplitude", 0.6)
+    glow.set("mote_count", 16)
+    glow.set("mote_radius", 0.20)
+    glow.set("pulse_source_mesh", NodePath("../Blade"))
+    ctx.save_scene()
+```
+
+Judge the pulse with `summer_screenshot framing:"camera"` — emissive glow does not
+survive the preset framings' substitute environment.
+
 Then verify — this recipe is one script, so a parse error is the whole effect:
 
 ```
@@ -395,16 +415,16 @@ manually in Summer Engine:
 
 After firing this recipe, suggest:
 
-- `summer:visual-effects/recipes/lightning` — perfect pre-cast charge-up. Use the `charge-up` variant and ramp `set_intensity(0→1)` then call `Lightning.cast_lightning`.
-- `summer:visual-effects/recipes/dissolve` — pair `summon-arrival` (materialize_object) with the `summoning-circle` variant.
-- `summer:visual-effects/recipes/fire` (the `magic-fire` variant) — for items that should glow AND flame.
-- `summer:visual-effects/game-feel` — slight time-dilation when picking up a pulsing quest item adds weight.
-- `summer:audio/sound-effect` — generate `magical hum, ethereal shimmer, 2s loop` and play on the same anchor.
+- `vfx-lightning` — perfect pre-cast charge-up. Use the `charge-up` variant and ramp `set_intensity(0→1)` then call `Lightning.cast_lightning`.
+- `vfx-dissolve` — pair `summon-arrival` (materialize_object) with the `summoning-circle` variant.
+- `vfx-fire` (the `magic-fire` variant) — for items that should glow AND flame.
+- `game-feel` — slight time-dilation when picking up a pulsing quest item adds weight.
+- `sound-effect` — generate `magical hum, ethereal shimmer, 2s loop` and play on the same anchor.
 
 ## See also
 
 - `_building-blocks/additive-billboard-particles.md` — canonical additive material settings (this recipe uses them for motes)
-- `summer:visual-effects/recipes/lightning` — pre-cast charge-up partner
-- `summer:visual-effects/recipes/dissolve` — for summon arrival pairing
-- `summer:visual-effects/recipes/fire` — for the `magic-fire` variant
-- `summer:gdscript-patterns` — for the controller idioms (signals, exports, `@tool`)
+- `vfx-lightning` — pre-cast charge-up partner
+- `vfx-dissolve` — for summon arrival pairing
+- `vfx-fire` — for the `magic-fire` variant
+- `gdscript-patterns` — for the controller idioms (signals, exports, `@tool`)

package/library/skills/vfx-magic-glow/_building-blocks/additive-billboard-particles.md

@@ -0,0 +1,37 @@
+# Additive Billboard Particles — Canonical Material Settings
+
+Reusable material configuration for additive particle billboards (motes, sparks, glow, ash). Used by `magic-glow`, optionally substitutable in `hit-spark` and `fire` if a custom shader is overkill.
+
+`BaseMaterial3D` is abstract — `BaseMaterial3D.new()` is a parse error ("Native class
+"BaseMaterial3D" cannot be constructed as it is abstract"). Instantiate
+`StandardMaterial3D`; the `BaseMaterial3D.*` enum constants below are still the right
+way to name the values.
+
+## Settings
+
+```gdscript
+var bm := StandardMaterial3D.new()
+bm.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA
+bm.blend_mode = BaseMaterial3D.BLEND_MODE_ADD
+bm.shading_mode = BaseMaterial3D.SHADING_MODE_UNSHADED
+bm.billboard_mode = BaseMaterial3D.BILLBOARD_PARTICLES
+bm.emission_enabled = true
+bm.emission_energy_multiplier = 3.0   # 1.0–5.0 typical; bump for HDR bloom
+bm.disable_receive_shadows = true
+bm.shadow_to_opacity = false
+bm.no_depth_test = false              # true only if particles must read on TOP of opaque geometry
+bm.billboard_keep_scale = true        # BILLBOARD_PARTICLES drops per-particle scale without this
+bm.albedo_color = Color(R, G, B, 1.0)
+bm.emission = Color(R, G, B)          # usually same as albedo for single-color motes
+```
+
+## When to use this vs a custom shader
+
+- **Use this `StandardMaterial3D` config** when the effect is just a tinted soft-circle mote (magic glow, sparkles, dust). Less code, faster iteration, free Godot-managed billboard math.
+- **Per-particle color over age does NOT need a custom shader.** `ParticleProcessMaterial` has `color_ramp`, `color_initial_ramp`, `alpha_curve` and `emission_curve` (all verified present in 4.6) — those drive the particle's `COLOR` from age and feed straight into a plain `StandardMaterial3D`. Reach for a ramp before reaching for a shader.
+- **Use a custom `ShaderMaterial`** when you need per-fragment shape masks (muzzle flash star burst), noise-distorted UVs (fire, smoke), or anything that varies *within* the quad. Those are what `StandardMaterial3D` genuinely can't express.
+- If a custom shader does need the particle age, note that the age lives in `INSTANCE_CUSTOM.y` (normalized by `INSTANCE_CUSTOM.w`, the lifetime), that `INSTANCE_CUSTOM.x` is the rotation angle — not the age — and that `INSTANCE_CUSTOM` is **vertex-stage only**. Pass it to `fragment()` through a `varying`.
+
+## Performance note
+
+Additive overdraw is fillrate-bound. `draw_pass_1` is a `Mesh`, so the size dial is on the mesh: keep `QuadMesh.size` at or under `Vector2(0.2, 0.2)` for motes/sparks. Larger quads at full additive intensity destroy mobile fillrate budgets fast.

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

@@ -0,0 +1,34 @@
+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.
+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
+facets:
+  lifecycle:
+    - build
+  domains:
+    - vfx
+    - rendering
+  modalities:
+    - scenes
+    - shaders
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/scene-scripting
+    - skill/sound-effect
+    - skill/game-feel
+    - skill/vfx-dissolve
+    - skill/vfx-fire
+    - skill/vfx-lightning
+    - skill/vfx-muzzle-flash
+source: official
+license: MIT
+status: stable
+recommended: false
+aliases:
+  - skills/visual-effects/recipes/magic-glow
+  - magic-glow

package/{skills/visual-effects/recipes/muzzle-flash → library/skills/vfx-muzzle-flash}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: muzzle-flash
+name: vfx-muzzle-flash
 description: Use when authoring a muzzle-flash visual 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. Trigger on "muzzle flash", "gun fire", "weapon flash", "barrel flash", "shoot a gun", "spell-cast burst at hand".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
 user-invocable: true
-allowed-tools: Read Write Edit summer_write_file summer_read_file summer_create_scene summer_add_node summer_set_prop summer_set_resource_property summer_connect_signal summer_inspect_node summer_save_scene summer_get_script_errors summer_get_debugger_errors summer_play summer_stop
+allowed-tools: Read Write Edit summer_write_file summer_read_file summer_create_scene summer_add_node summer_set_prop summer_set_resource_property summer_connect_signal summer_inspect_node summer_save_scene summer_run_script summer_get_script_errors summer_get_debugger_errors summer_play summer_stop
 paths: ["**/*.tscn", "**/*.gd", "**/*.gdshader", "addons/vfx/**"]
 ---
 
@@ -228,6 +228,26 @@ 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
+func run(ctx):
+    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")
+    weapon.connect("fired", Callable(flash, "fire"), CONNECT_PERSIST)
+    # CONNECT_PERSIST is required — a bare connect() works live but is NOT saved
+    ctx.save_scene()
+```
+
 ### 5b. Verify
 
 `muzzle_flash.gd` `preload`s its own shader, so a shader that failed to write takes
@@ -355,15 +375,15 @@ manually in Summer Engine:
 
 After firing this recipe, suggest:
 
-- `summer:visual-effects/recipes/hit-spark` — pair on the bullet impact end.
-- `summer:visual-effects/recipes/smoke` — for a small puff at the barrel after the flash for high-caliber weapons.
-- `summer:visual-effects/game-feel` — recoil camera kick + screen shake (`CameraShake.add_trauma(0.15)`) on every shot makes the flash feel 5× more powerful.
-- `summer:audio/sound-effect` — generate `9mm pistol shot, sharp crack, indoor, short tail, 400ms` and play in the same `fire()`.
+- `vfx-hit-spark` — pair on the bullet impact end.
+- `vfx-smoke` — for a small puff at the barrel after the flash for high-caliber weapons.
+- `game-feel` — recoil camera kick + screen shake (`CameraShake.add_trauma(0.15)`) on every shot makes the flash feel 5× more powerful.
+- `sound-effect` — generate `9mm pistol shot, sharp crack, indoor, short tail, 400ms` and play in the same `fire()`.
 
 ## See also
 
 - `_building-blocks/additive-billboard-particles.md` — canonical additive material reference
 - `_building-blocks/trauma-shake-snippet.md` — `CameraShake.add_trauma()` for the recoil punch
-- `summer:visual-effects/recipes/hit-spark` — companion impact effect
-- `summer:visual-effects/recipes/lightning` — for energy weapons (replace the flash with a beam)
-- `summer:visual-effects/game-feel` — recoil + hit-stop wiring
+- `vfx-hit-spark` — companion impact effect
+- `vfx-lightning` — for energy weapons (replace the flash with a beam)
+- `game-feel` — recoil + hit-stop wiring