summer-engine 2.6.6 → 2.8.0

package/skills/visual-effects/recipes/lightning/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
 user-invocable: true
-allowed-tools: Read Write Edit summer_add_node summer_set_prop summer_set_resource_property summer_inspect_node summer_save_scene
+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
 paths: ["**/*.tscn", "**/*.gd", "**/*.gdshader", "addons/vfx/**"]
 ---
 
@@ -27,7 +27,9 @@ A lightning bolt is a noisy line from A to B, drawn for ~150 ms with a glow shad
 - The user wants a continuous beam that holds (e.g., laser sniper holding the trigger) — use the same shader on a `MeshInstance3D` cylinder with continuous emission, not the `ImmediateMesh` one-shot pattern. (See variants for `held-beam`.)
 - The user wants ambient electricity *on* an object (Frankenstein arcs) — use a custom shader on the mesh with screen-space arcs; this recipe is for two-point bolts.
 - The user wants a 2D lightning effect on UI — `canvas_item` shader, not this.
-- The user wants a tracer line for a bullet — use a simple `Line3D`/`ImmediateMesh` without the noise displacement; skip this recipe.
+- The user wants a tracer line for a bullet — use a simple `ImmediateMesh`
+  without noise displacement; skip this recipe. The current Summer build has no
+  `Line3D` (`ClassDB.class_exists("Line3D")` is `false`); `Line2D` is 2D-only.
 
 ## Recipe
 
@@ -56,8 +58,7 @@ uniform float flicker_rate  : hint_range(0.0, 60.0) = 30.0;
 
 void vertex() {
     // Billboard each segment toward the camera around its own forward axis.
-    vec3 right = INV_VIEW_MATRIX[0].xyz;
-    vec3 up    = INV_VIEW_MATRIX[1].xyz;
+    vec3 up = INV_VIEW_MATRIX[1].xyz;
     VERTEX += UV.y > 0.5 ? up * thickness * 0.5 : -up * thickness * 0.5;
 }
 
@@ -76,8 +77,10 @@ void fragment() {
     vec3 col = mix(bolt_color.rgb, core_color.rgb, core);
     float a = (core + halo * 0.4) * intensity * flick;
 
-    ALBEDO = col;
-    EMISSION = col * emission_boost * intensity * flick * (core + halo * 0.5);
+    // `render_mode unshaded` outputs ALBEDO and discards EMISSION entirely
+    // (scene_forward_clustered.glsl:2962 — `frag_color = vec4(albedo, alpha)`
+    // under MODE_UNSHADED), so the bloom boost has to live in ALBEDO.
+    ALBEDO = col * emission_boost * flick * (core + halo * 0.5);
     ALPHA = clamp(a, 0.0, 1.0);
 }
 ```
@@ -117,14 +120,14 @@ func cast_lightning(from: Vector3, to: Vector3, intensity_scale: float = 1.0) ->
         _spawn_sparks(from)
         _spawn_sparks(to)
 
-    if Engine.has_singleton("CameraShake") or _has_autoload("CameraShake"):
-        var cs := Engine.get_main_loop().root.get_node_or_null("/root/CameraShake")
-        if cs and cs.has_method("add_trauma"):
-            cs.add_trauma(trauma_amount * intensity_scale)
-
-func _has_autoload(name: String) -> bool:
-    var root := Engine.get_main_loop().root
-    return root and root.has_node("/root/" + name)
+    # An autoload is a node at /root/<Name>, not an engine singleton:
+    # Engine.has_singleton("CameraShake") is always false for one (measured).
+    # get_node_or_null returns null when nothing is registered — that is the guard.
+    # (MainLoop has no `root`, so `var root := Engine.get_main_loop().root` is a
+    # parse error that takes the entire script down with it.)
+    var cs := get_node_or_null(^"/root/CameraShake")
+    if cs and cs.has_method("add_trauma"):
+        cs.add_trauma(trauma_amount * intensity_scale)
 
 func _build_bolt_node(from: Vector3, to: Vector3, intensity_scale: float) -> Node3D:
     var holder := Node3D.new()
@@ -193,7 +196,10 @@ func _draw_polyline(mesh: ImmediateMesh, points: PackedVector3Array) -> void:
 func _spawn_sparks(at: Vector3) -> void:
     if not ResourceLoader.exists(spark_scene_path):
         return
-    var sparks := load(spark_scene_path).instantiate()
+    # `var sparks := load(...).instantiate()` is a parse error — load() has no
+    # static return type, so `:=` cannot infer. Annotate both steps.
+    var packed: PackedScene = load(spark_scene_path)
+    var sparks: Node3D = packed.instantiate()
     add_child(sparks)
     sparks.global_position = at
     if sparks.has_method("restart"):
@@ -216,12 +222,28 @@ 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.
+
 ```
-summer_add_node(parent="./World", type="Node3D", name="LightningCaster")
-summer_set_prop(path="./World/LightningCaster", property="script", value="res://addons/vfx/lightning/lightning_caster.gd")
-summer_set_prop(path="./World/LightningCaster", property="bolt_color", value="Color(0.55, 0.75, 1.0)")
-summer_set_prop(path="./World/LightningCaster", property="trauma_amount", value=0.6)
-summer_save_scene
+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")
+```
+
+Then verify — the caster `preload`s its own shader, so a shader that failed to write
+takes the whole script down at parse time:
+
+```
+summer_get_script_errors          # lightning_caster.gd parsed?
+summer_play
+summer_get_debugger_errors        # shader compile errors surface here at runtime
+summer_stop
 ```
 
 Then from the spell code:
@@ -319,18 +341,21 @@ trauma_amount = 0.0  # no shake on a held beam
 
 ## Anti-patterns
 
-- **Drawing the bolt as a `Line3D`.** Line3D doesn't billboard or accept the additive shader cleanly. Use `ImmediateMesh` triangle strip with the billboard vertex shader.
+- **Reaching for a `Line3D`.** The current Summer build has no such class
+  (`ClassDB.class_exists("Line3D")` is `false`); `Line2D` is 2D-only. Use an
+  `ImmediateMesh` triangle strip with the billboard vertex shader.
 - **Animating the path frame-by-frame.** A bolt is one shape, on screen for 150 ms. You don't see the inside detail moving. One generation per cast.
 - **Forgetting `blend_add`.** A bolt that doesn't bloom looks like a curved metal stick.
-- **No camera shake.** Lightning without screen shake feels weightless. Always call `CameraShake.add_trauma`.
+- **No camera shake.** Lightning without screen shake feels weightless. Always call `add_trauma` on the `/root/CameraShake` autoload.
+- **Gating the shake on `Engine.has_singleton("CameraShake")`.** That is always `false` for an autoload (measured) — the shake would never fire. Autoloads are nodes at `/root/<Name>`; look them up with `get_node_or_null`.
 - **Spawning lightning every frame for a "continuous" beam.** Use the `plasma-laser` variant pattern instead — one mesh, updated per-frame transform, never re-instantiated.
 - **`SEGMENTS` too low (< 6).** Bolt looks like a zigzag triangle. Default 18 is right.
 - **`DISPLACEMENT` proportional to total length without falloff.** Endpoints drift away from `from`/`to`. The included code uses `sin(t * PI)` falloff so endpoints meet cleanly.
 
 ## Performance notes
 
-- One bolt: ~36 verts, one draw call, freed after 150 ms. Effectively free.
-- Chain lightning with 5 segments: still under 0.05 ms.
+- One bolt at `SEGMENTS = 18`: 19 path points × 2 verts = 38 verts for the trunk, plus 2 × (`SEGMENTS / 3` + 1) = 14 verts per forked branch. One draw call, freed after 150 ms. Effectively free.
+- Chain lightning with 5 segments stays in the same negligible band — that is an order-of-magnitude expectation, not a measurement.
 - Endpoint sparks (instantiated `hit-spark` scenes) are the bigger cost — 64 particles × 2 = 128 particles per cast. Throttle for storms (see edge cases).
 - The shader's flicker uses `floor(TIME * flicker_rate)`, so it ages with `TIME` not particle time — flicker is consistent across all bolts in flight.
 
@@ -341,16 +366,23 @@ trauma_amount = 0.0  # no shake on a held beam
 - **Bolt origin and target at the same point.** Falloff goes to zero; `_generate_path` returns a degenerate strip. Add a guard: if `(to - from).length() < 0.01`, skip.
 - **Underwater bolt.** Tint blue-green, drop `emission_boost` to 5.0; underwater bloom is muted.
 - **First-person caster (player's hand).** The bolt starts inside the player's view and reads as a flash. Use a `held-beam` variant or shorten `LIFETIME` to 0.08.
-- **No `CameraShake` autoload registered.** The script's `_has_autoload` guard prevents a crash; the bolt fires without shake. Suggest `_building-blocks/trauma-shake-snippet.md` to wire it.
+- **No `CameraShake` autoload registered.** `get_node_or_null("/root/CameraShake")` returns null and the `if cs` check skips the call; the bolt fires without shake. Suggest `_building-blocks/trauma-shake-snippet.md` to wire it.
 
 ## Fallback (no MCP)
 
-VFX is code, no MCP required:
+Section 5 is fully automatable — `summer_write_file` writes the shader and the
+caster, `summer_add_node` + `summer_set_prop` + `summer_save_scene` place it, and
+`summer_project_setting` registers the autoload. Do not hand these steps to the user
+when the MCP tools are available.
+
+Without the MCP connection there is no engine to drive, so the user does it
+manually in Summer Engine:
 
 1. Create `addons/vfx/lightning/` and write the three files above.
-2. In Godot, add a `Node3D`, attach `lightning_caster.gd`. Optionally autoload as `Lightning`.
+2. Add a `Node3D`, attach `lightning_caster.gd`. Optionally autoload as `Lightning`.
 3. From any spell script, call `Lightning.cast_lightning(from_pos, to_pos)`.
 4. Wire the `CameraShake` autoload from `_building-blocks/trauma-shake-snippet.md` for the punch.
+5. Check the Errors dock — `lightning_caster.gd` `preload`s the shader, so a broken shader path fails the script too.
 
 ## Handoff
 

package/skills/visual-effects/recipes/magic-glow/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
 user-invocable: true
-allowed-tools: Read Write Edit summer_add_node summer_set_prop summer_set_resource_property summer_inspect_node summer_save_scene
+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
 paths: ["**/*.tscn", "**/*.gd", "**/*.gdshader", "addons/vfx/**"]
 ---
 
@@ -85,6 +85,7 @@ var _motes: GPUParticles3D
 var _source_mesh: MeshInstance3D
 var _source_mat: BaseMaterial3D
 var _t: float = 0.0
+var _intensity: float = 1.0
 
 func _ready() -> void:
     _build_light()
@@ -127,7 +128,9 @@ func _build_motes() -> void:
 
     var mesh := QuadMesh.new()
     mesh.size = Vector2.ONE
-    var bm := BaseMaterial3D.new()
+    # BaseMaterial3D is abstract ("Native class "BaseMaterial3D" cannot be
+    # constructed as it is abstract"); StandardMaterial3D is the concrete subclass.
+    var bm := StandardMaterial3D.new()
     bm.transparency = BaseMaterial3D.TRANSPARENCY_ALPHA
     bm.blend_mode = BaseMaterial3D.BLEND_MODE_ADD
     bm.shading_mode = BaseMaterial3D.SHADING_MODE_UNSHADED
@@ -160,14 +163,17 @@ func _process(delta: float) -> void:
         phase = pulse_easing.sample(phase)
 
     if _light:
-        _light.light_energy = light_energy_base + light_energy_amplitude * phase
+        _light.light_energy = (light_energy_base + light_energy_amplitude * phase) * _intensity
     if _source_mat:
-        _source_mat.emission_energy_multiplier = source_emission_base + source_emission_amplitude * phase
+        _source_mat.emission_energy_multiplier = (source_emission_base + source_emission_amplitude * phase) * _intensity
 
 func set_intensity(scale: float) -> void:
     ## Scale all visible cues 0..1+ (e.g., charge-up: tween from 0 to 1 over a second).
-    light_energy_base *= scale
-    light_energy_amplitude *= scale
+    ## Held as a separate factor rather than multiplied into light_energy_base /
+    ## light_energy_amplitude: a multiplying version (`light_energy_base *= scale`)
+    ## pins both fields to 0.0 forever after set_intensity(0.0), so the charge-up
+    ## tween from 0 to 1 never brings the glow back.
+    _intensity = scale
     if _motes:
         _motes.amount_ratio = scale
 
@@ -191,26 +197,40 @@ Node3D ("MagicGlow") [script: magic_glow.gd]
 
 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.
+
 ```
-summer_add_node(parent="./Player/Hand/Sword", type="Node3D", name="Glow")
-summer_set_prop(path="./Player/Hand/Sword/Glow", property="script", value="res://addons/vfx/magic-glow/magic_glow.gd")
-summer_set_prop(path="./Player/Hand/Sword/Glow", property="glow_color", value="Color(0.55, 0.85, 1.0)")
-summer_set_prop(path="./Player/Hand/Sword/Glow", property="light_energy_base", value=1.2)
-summer_set_prop(path="./Player/Hand/Sword/Glow", property="light_energy_amplitude", value=0.6)
-summer_set_prop(path="./Player/Hand/Sword/Glow", property="mote_count", value=16)
-summer_set_prop(path="./Player/Hand/Sword/Glow", property="mote_radius", value=0.20)
-summer_set_prop(path="./Player/Hand/Sword/Glow", property="pulse_source_mesh", value="../Blade")
-summer_save_scene
+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(parent="./World/Pedestal/SoulGem", type="Node3D", name="Glow")
-summer_set_prop(path="./World/Pedestal/SoulGem/Glow", property="glow_color", value="Color(0.85, 0.45, 1.0)")
-summer_set_prop(path="./World/Pedestal/SoulGem/Glow", property="pulse_hz", value=0.4)
-summer_set_prop(path="./World/Pedestal/SoulGem/Glow", property="mote_count", value=32)
-summer_set_prop(path="./World/Pedestal/SoulGem/Glow", property="mote_radius", value=0.30)
+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)
+```
+
+Then verify — this recipe is one script, so a parse error is the whole effect:
+
+```
+summer_get_script_errors          # magic_glow.gd parsed?
+summer_play
+summer_get_debugger_errors
+summer_stop
 ```
 
 For a charge-up before casting:
@@ -313,11 +333,12 @@ mote_drift_up        = 0.0
 
 ### charge-up (paired with lightning/muzzle-flash)
 
-Starts at 0 intensity, ramped via `set_intensity`. Set initial values for fully-charged state.
+Author the **fully-charged** values here; `set_intensity(0.0 → 1.0)` scales them at
+runtime. Leaving `light_energy_base` at 0.0 means the fully-charged glow is also 0.0.
 
 ```
 glow_color           = Color(0.55, 0.75, 1.0)
-light_energy_base    = 0.0     # script tweens this up
+light_energy_base    = 1.5     # fully-charged value; set_intensity scales it
 light_energy_amplitude = 2.0
 pulse_hz             = 2.5     # buzzing
 mote_count           = 24
@@ -334,11 +355,16 @@ mote_drift_up        = 0.5
 - **Forgetting to enable the source mesh's emission before assigning the glow color.** The shader's emission stays black. The controller's `_resolve_source_mesh` enables it.
 - **`pulse_hz` too high.** Above 3 Hz it strobes — accessibility issue (photosensitivity). Default 0.7 is calm.
 - **Generating an "aura" PNG and using as a billboard sprite.** The misroute. The procedural light + motes are alive and scale to any item.
+- **`BaseMaterial3D.new()` for the mote material.** `BaseMaterial3D` is abstract — that line is a parse error and takes the whole script down. Instantiate `StandardMaterial3D`; keep using the `BaseMaterial3D.*` enum constants.
+- **A multiplicative `set_intensity` (`light_energy_base *= scale`).** One `set_intensity(0.0)` pins the field to 0.0 permanently, so the charge-up tween from 0 to 1 does nothing. Hold the scale in its own variable and apply it where the energy is written.
 
 ## Performance notes
 
-- One glow = 1 light + 16–32 particles. ~0.05 ms total. Cheap.
-- N glowing items in a scene: budget ~12 active `OmniLight3D`s before you should consider `LightOccluder3D` culling. Motes scale linearly to ~512 across all glows.
+- One glow = 1 light + 16–32 particles. Sub-millisecond — an order-of-magnitude expectation, not a measurement.
+- N glowing items in a scene: budget ~12 active `OmniLight3D`s before you start
+  culling. The current Summer build has no `LightOccluder3D`
+  (`ClassDB.class_exists` is `false`; `LightOccluder2D` is 2D-only). Cull with
+  `distance_fade_enabled` / `distance_fade_begin` or a smaller `omni_range`.
 - Mobile: drop `mote_count` to 8, `light_range` × 0.5, `light_shadow_enabled = false` always.
 - LOD: in `_process`, scale `_motes.amount_ratio` and `_light.light_energy` by `clamp(1.5 - dist_to_camera / 20.0, 0.10, 1.0)`. Past 20 m, drop motes entirely; keep light.
 
@@ -352,11 +378,18 @@ mote_drift_up        = 0.5
 
 ## Fallback (no MCP)
 
-VFX is code, no MCP required:
+Section 4 is fully automatable — `summer_write_file` writes the controller,
+`summer_add_node` + `summer_set_prop` attach and tune it, and `summer_create_scene` +
+`summer_save_scene` produce `magic_glow.tscn`. Do not hand these steps to the user
+when the MCP tools are available.
+
+Without the MCP connection there is no engine to drive, so the user does it
+manually in Summer Engine:
 
 1. Create `addons/vfx/magic-glow/` with the two files above.
-2. In Godot, add a `Node3D` child to the glowing object, attach `magic_glow.gd`. Save as `magic_glow.tscn` if you want a scene to instantiate.
+2. Add a `Node3D` child to the glowing object, attach `magic_glow.gd`. Save as `magic_glow.tscn` if you want a scene to instantiate.
 3. Tune the exported parameters in the inspector or via script.
+4. Check the Errors dock before tuning anything.
 
 ## Handoff
 

package/skills/visual-effects/recipes/muzzle-flash/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
 user-invocable: true
-allowed-tools: Read Write Edit summer_add_node summer_set_prop summer_set_resource_property summer_inspect_node summer_save_scene
+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
 paths: ["**/*.tscn", "**/*.gd", "**/*.gdshader", "addons/vfx/**"]
 ---
 
@@ -25,7 +25,9 @@ A muzzle flash is on screen for 60–100 ms. Long enough to read, too short to a
 
 - The user wants a *continuous* flame (flamethrower) — use `fire`, not muzzle-flash.
 - The user wants the impact spark on the wall the bullet hit — that's `hit-spark`.
-- The user wants a tracer line from barrel to target — use a `Line3D`/`ImmediateMesh` recipe, not this. (Or pair this with `lightning` for an energy weapon.)
+- The user wants a tracer line from barrel to target — use an `ImmediateMesh`
+  recipe, not this. The current Summer build has no `Line3D`
+  (`ClassDB.class_exists("Line3D")` is `false`).
 - The user wants a slow-glowing spell charge-up — use `magic-glow` for the buildup, then this for the release frame.
 
 ## Recipe
@@ -55,12 +57,19 @@ uniform float ray_sharpness  : hint_range(0.5, 32.0) = 8.0;
 uniform float random_seed    : hint_range(0.0, 6.2831) = 0.0;    // rotates the star per shot
 
 void vertex() {
+    // Billboard toward the camera. The bare mat4(INV_VIEW_MATRIX[0..2], MODEL_MATRIX[3])
+    // form discards the node's scale, so the per-shot `flash_size` randomisation in
+    // fire() would never reach the screen — normalize the basis and re-apply scale.
     MODELVIEW_MATRIX = VIEW_MATRIX * mat4(
-        INV_VIEW_MATRIX[0],
-        INV_VIEW_MATRIX[1],
-        INV_VIEW_MATRIX[2],
-        MODEL_MATRIX[3]
-    );
+        normalize(INV_VIEW_MATRIX[0]),
+        normalize(INV_VIEW_MATRIX[1]),
+        normalize(INV_VIEW_MATRIX[2]),
+        MODEL_MATRIX[3]) * mat4(
+        vec4(length(MODEL_MATRIX[0].xyz), 0.0, 0.0, 0.0),
+        vec4(0.0, length(MODEL_MATRIX[1].xyz), 0.0, 0.0),
+        vec4(0.0, 0.0, length(MODEL_MATRIX[2].xyz), 0.0),
+        vec4(0.0, 0.0, 0.0, 1.0));
+    MODELVIEW_NORMAL_MATRIX = mat3(MODELVIEW_MATRIX);
 }
 
 void fragment() {
@@ -81,9 +90,11 @@ void fragment() {
     // Mix core color (white-hot) into flash color at the very center.
     vec3 col = mix(flash_color.rgb, core_color.rgb, pow(core, 4.0));
 
-    ALBEDO   = col;
-    EMISSION = col * emission_boost * intensity;
-    ALPHA    = mask * intensity;
+    // `render_mode unshaded` outputs ALBEDO and discards EMISSION entirely
+    // (scene_forward_clustered.glsl:2962 — `frag_color = vec4(albedo, alpha)`
+    // under MODE_UNSHADED), so the bloom boost has to live in ALBEDO.
+    ALBEDO = col * emission_boost * intensity;
+    ALPHA  = mask * intensity;
 }
 ```
 
@@ -98,6 +109,8 @@ extends Node3D
 
 ## Spawn one of these as a child of the gun's barrel tip and call `fire()` on each shot.
 
+const SPARK_SCENE := "res://addons/vfx/hit-spark/hit_spark.tscn"
+
 @export var flash_color: Color = Color(1.0, 0.85, 0.45)
 @export_range(0.02, 0.30) var flash_duration: float = 0.08  ## seconds visible
 @export_range(0.10, 4.0)  var flash_size: float = 0.6      ## meters across
@@ -134,8 +147,12 @@ func _ready() -> void:
     _light.shadow_enabled = false
     add_child(_light)
 
-    if spawn_sparks:
-        _sparks = preload("res://addons/vfx/hit-spark/hit_spark.tscn").instantiate() if ResourceLoader.exists("res://addons/vfx/hit-spark/hit_spark.tscn") else null
+    # preload() resolves at PARSE time, so a runtime ResourceLoader.exists() check
+    # cannot guard it — "Parse Error: Preload file ... does not exist" takes the
+    # whole script down when hit-spark hasn't been installed. Use load().
+    if spawn_sparks and ResourceLoader.exists(SPARK_SCENE):
+        var packed: PackedScene = load(SPARK_SCENE)
+        _sparks = packed.instantiate() as GPUParticles3D
         if _sparks:
             _sparks.one_shot = true
             _sparks.emitting = false
@@ -184,13 +201,19 @@ 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.
+
 ```
-summer_add_node(parent="./Player/Weapon/BarrelTip", type="Node3D", name="MuzzleFlash")
-summer_set_prop(path="./Player/Weapon/BarrelTip/MuzzleFlash", property="script", value="res://addons/vfx/muzzle-flash/muzzle_flash.gd")
-summer_set_prop(path="./Player/Weapon/BarrelTip/MuzzleFlash", property="flash_size", value=0.6)
-summer_set_prop(path="./Player/Weapon/BarrelTip/MuzzleFlash", property="flash_duration", value=0.08)
-summer_set_prop(path="./Player/Weapon/BarrelTip/MuzzleFlash", property="light_energy", value=4.0)
-summer_save_scene
+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()`:
@@ -199,10 +222,22 @@ Then in your weapon script, on `fire()`:
 $BarrelTip/MuzzleFlash.fire()
 ```
 
-Or connect a signal:
+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")
+```
+
+### 5b. 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.
 
-```gdscript
-weapon.fired.connect($BarrelTip/MuzzleFlash.fire)
+```
+summer_get_script_errors          # muzzle_flash.gd parsed?
+summer_play
+summer_get_debugger_errors        # shader compile errors surface here at runtime
+summer_stop
 ```
 
 ### 6. Parameters to tune
@@ -283,11 +318,12 @@ ray_sharpness  = 18.0
 - **OmniLight3D with shadows enabled.** A 60 ms shadow pass costs more than the flash itself. `shadow_enabled = false`.
 - **Flash duration > 150 ms.** Reads as a flamethrower or a stuck animation. Stay under 100 ms unless intentional.
 - **Spawning a new MuzzleFlash each shot and freeing it.** Rapid-fire weapons leak. Reuse one anchored to the barrel and call `fire()`.
+- **`preload`ing the optional hit-spark scene.** `preload()` resolves at parse time, so wrapping it in a runtime `ResourceLoader.exists()` check does nothing — the script fails to load entirely when hit-spark isn't installed. Use `load()` behind the check.
 - **Generating an animated flash sprite.** That's the misroute this skill exists to prevent. The procedural shader rotates per shot for free, and you can recolor without regenerating.
 
 ## Performance notes
 
-- One quad + one light + ~8 sparks = under 0.02 ms. Safe at any rate of fire.
+- One quad + one light + ~8 sparks is negligible — safe at any rate of fire. That is an order-of-magnitude expectation, not a measurement.
 - The `OmniLight3D` snapping on/off per shot will trigger a shadow re-bake on lights with `shadow_enabled = true` — keep it off, always.
 - For full-auto weapons (10+ shots/sec), consider raising `flash_duration` to 0.10 and dropping `intensity` to 0.6 so consecutive flashes blend instead of strobe.
 
@@ -297,16 +333,23 @@ ray_sharpness  = 18.0
 - **Weapon visible in a mirror / scope.** The additive quad will appear in reflections only if the reflection probe captures it; for scope ADS, render the flash into the scope's separate viewport.
 - **Underwater shooting.** Tint the flash blue-green via `flash_color`, drop `light_range` to 30%.
 - **Silenced weapon.** `flash_size = 0.10`, `light_energy = 0.5`, `flash_duration = 0.04`. Just a wink at the barrel.
-- **Suppressed flash with a tracer.** Pair this with a `Line3D` tracer from barrel to hit point, fired in the same call.
+- **Suppressed flash with a tracer.** Pair this with an `ImmediateMesh` tracer from barrel to hit point, fired in the same call.
 
 ## Fallback (no MCP)
 
-VFX is code, no MCP required:
+Section 5 is fully automatable — `summer_write_file` writes the shader and the
+controller, `summer_add_node` + `summer_set_prop` place it, and
+`summer_connect_signal` wires `fired` → `fire`. Do not hand these steps to the user
+when the MCP tools are available.
+
+Without the MCP connection there is no engine to drive, so the user does it
+manually in Summer Engine:
 
 1. Create `addons/vfx/muzzle-flash/` and write the three files above.
-2. In Godot, add a `Node3D` child to your weapon's barrel tip Marker3D.
+2. Add a `Node3D` child to your weapon's barrel tip Marker3D.
 3. Attach `muzzle_flash.gd` as the script. The runtime builds the quad + light.
 4. In your weapon's fire code: `$BarrelTip/MuzzleFlash.fire()`.
+5. Check the Errors dock — `muzzle_flash.gd` `preload`s the shader, so a broken shader path fails the script too.
 
 ## Handoff