summer-engine 2.7.0 → 2.8.0

package/skills/visual-effects/recipes/fire/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_inspect_resource summer_save_scene summer_get_script_errors summer_get_debugger_errors summer_play summer_stop
 paths: ["**/*.tscn", "**/*.gd", "**/*.gdshader", "addons/vfx/**"]
 ---
 
@@ -35,12 +35,17 @@ Fire in games is almost never a video clip and never an AI-generated sprite. It'
 ### 1. Files to create
 
 ```
+addons/vfx/_building-blocks/noise-3d-fbm.gdshaderinc   # copy from this skill FIRST
 addons/vfx/fire/fire.gdshader              # spatial shader for the visual quad
 addons/vfx/fire/fire_process.gdshader      # particle shader for the simulation
 addons/vfx/fire/fire_controller.gd          # parameter dials + lifetime
 addons/vfx/fire/fire.tscn                   # reusable scene (instantiate per torch)
 ```
 
+`fire.gdshader` `#include`s the FBM noise file. A missing include is a hard compile
+error, so copy `_building-blocks/noise-3d-fbm.gdshaderinc` from this skill into
+`res://addons/vfx/_building-blocks/` before writing the shader.
+
 ### 2. Visual shader code
 
 `addons/vfx/fire/fire.gdshader`:
@@ -62,22 +67,41 @@ uniform float distortion      : hint_range(0.0, 0.6)  = 0.20;
 uniform float emission_energy : hint_range(0.0, 8.0)  = 3.5;
 uniform float soft_edge       : hint_range(0.01, 0.5) = 0.20;
 
+// INSTANCE_CUSTOM is vertex-stage only, so carry what fragment() needs across.
+varying float age;
+varying float seed;
+
 void vertex() {
-    // Billboard the quad toward the camera (view-space).
-    MODELVIEW_MATRIX = VIEW_MATRIX * mat4(
-        INV_VIEW_MATRIX[0],
-        INV_VIEW_MATRIX[1],
-        INV_VIEW_MATRIX[2],
-        MODEL_MATRIX[3]
-    );
+    // Billboard toward the camera, keeping per-particle rotation (INSTANCE_CUSTOM.x)
+    // and per-particle scale. The bare `VIEW_MATRIX * mat4(INV_VIEW_MATRIX[0..2],
+    // MODEL_MATRIX[3])` form throws both away — this mirrors what Godot's own
+    // BILLBOARD_PARTICLES generator emits (scene/resources/material.cpp:1313-1334).
+    mat4 mat_world = mat4(
+        normalize(INV_VIEW_MATRIX[0]),
+        normalize(INV_VIEW_MATRIX[1]),
+        normalize(INV_VIEW_MATRIX[2]),
+        MODEL_MATRIX[3]);
+    mat_world = mat_world * mat4(
+        vec4(cos(INSTANCE_CUSTOM.x), -sin(INSTANCE_CUSTOM.x), 0.0, 0.0),
+        vec4(sin(INSTANCE_CUSTOM.x),  cos(INSTANCE_CUSTOM.x), 0.0, 0.0),
+        vec4(0.0, 0.0, 1.0, 0.0),
+        vec4(0.0, 0.0, 0.0, 1.0));
+    MODELVIEW_MATRIX = VIEW_MATRIX * mat_world * 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);
+
+    // CUSTOM.x is the rotation angle, NOT the age. The age lives in CUSTOM.y
+    // (it counts up by DELTA/LIFETIME) and CUSTOM.w holds the lifetime scale.
+    age  = clamp(INSTANCE_CUSTOM.y / max(INSTANCE_CUSTOM.w, 0.0001), 0.0, 1.0);
+    seed = fract(sin(float(INSTANCE_ID) * 12.9898) * 43758.5453);
 }
 
 void fragment() {
-    // CUSTOM.x is particle age 0..1 (set by the process material).
-    float age = CUSTOM.x;
-
     // Distort UVs with scrolling 3D noise so the flame writhes.
-    vec3 np = vec3(UV * noise_scale, TIME * noise_speed);
+    vec3 np = vec3(UV * noise_scale, TIME * noise_speed + seed * 10.0);
     float n = fbm3(np);
     vec2 uv = UV + vec2(n - 0.5) * distortion;
 
@@ -99,8 +123,10 @@ void fragment() {
     // Add the noise as a brightness modulation so flames flicker.
     float flicker = mix(0.6, 1.2, n);
 
-    ALBEDO = col.rgb * flicker;
-    EMISSION = col.rgb * flicker * emission_energy * (1.0 - age);
+    // `render_mode unshaded` outputs ALBEDO and discards EMISSION entirely
+    // (scene_forward_clustered.glsl:2962 — `frag_color = vec4(albedo, alpha)`
+    // under MODE_UNSHADED), so the HDR boost that drives glow lives in ALBEDO.
+    ALBEDO = col.rgb * flicker * emission_energy * (1.0 - age * 0.5);
     ALPHA = col.a * mask * (1.0 - age * age);
 }
 ```
@@ -118,36 +144,61 @@ uniform float rise_speed   : hint_range(0.1, 6.0) = 1.8;
 uniform float spread_angle : hint_range(0.0, 1.5) = 0.35;
 uniform float lifetime_var : hint_range(0.0, 1.0) = 0.25;
 
+// `rand_from_seed()` is generated into ParticleProcessMaterial's own shader; it is
+// NOT a built-in you can call from a hand-written particles shader
+// ("SHADER ERROR: No matching function found for: 'rand_from_seed'"). Supply one.
+uint hash_u(uint x) {
+    x ^= x >> 16u;
+    x *= 0x7feb352du;
+    x ^= x >> 15u;
+    x *= 0x846ca68bu;
+    x ^= x >> 16u;
+    return x;
+}
+
+float rnd(uint s) {
+    return float(hash_u(s) & 0x00ffffffu) / 16777216.0;
+}
+
 void start() {
+    uint s = RANDOM_SEED + INDEX * 747796405u;
+
     // Random spawn within a small disc.
-    float r  = sqrt(rand_from_seed(RANDOM_SEED + uint(7))) * 0.18;
-    float th = rand_from_seed(RANDOM_SEED + uint(11)) * 6.2831853;
+    float r  = sqrt(rnd(s + 7u)) * 0.18;
+    float th = rnd(s + 11u) * 6.2831853;
     TRANSFORM[3].xyz = vec3(cos(th) * r, 0.0, sin(th) * r);
 
     // Initial velocity: mostly up, slight cone.
     vec3 dir = vec3(
-        (rand_from_seed(RANDOM_SEED + uint(13)) - 0.5) * spread_angle,
+        (rnd(s + 13u) - 0.5) * spread_angle,
         1.0,
-        (rand_from_seed(RANDOM_SEED + uint(17)) - 0.5) * spread_angle
+        (rnd(s + 17u) - 0.5) * spread_angle
     );
     VELOCITY = normalize(dir) * rise_speed;
 
-    // Stagger lifetimes for variety.
-    LIFETIME = LIFETIME * (1.0 + (rand_from_seed(RANDOM_SEED + uint(19)) - 0.5) * 2.0 * lifetime_var);
-
-    CUSTOM.x = 0.0; // age
-    CUSTOM.y = rand_from_seed(RANDOM_SEED + uint(23)); // per-particle seed
+    // LIFETIME is read-only ("SHADER ERROR: Constants cannot be modified") and there
+    // is no TOTAL_LIFETIME. Stagger lifetimes the way ParticleProcessMaterial does:
+    // keep a per-particle lifetime scale in CUSTOM.w and retire the particle when
+    // the age in CUSTOM.y passes it.
+    CUSTOM = vec4(0.0);
+    CUSTOM.w = 1.0 + (rnd(s + 19u) - 0.5) * 2.0 * lifetime_var;
+    CUSTOM.z = rnd(s + 23u); // per-particle seed
 }
 
 void process() {
+    // CUSTOM.x = rotation angle, .y = age, .z = per-particle seed, .w = lifetime scale.
+    CUSTOM.y += DELTA / LIFETIME;
+    if (CUSTOM.y > CUSTOM.w) {
+        ACTIVE = false;
+    }
+    float age = clamp(CUSTOM.y / max(CUSTOM.w, 0.0001), 0.0, 1.0);
+
     // Rise + small horizontal sway.
     VELOCITY.y += DELTA * 0.6;
-    VELOCITY.x += sin(TIME * 2.0 + CUSTOM.y * 6.28) * DELTA * 0.4;
-    VELOCITY.z += cos(TIME * 2.3 + CUSTOM.y * 6.28) * DELTA * 0.4;
+    VELOCITY.x += sin(TIME * 2.0 + CUSTOM.z * 6.28) * DELTA * 0.4;
+    VELOCITY.z += cos(TIME * 2.3 + CUSTOM.z * 6.28) * DELTA * 0.4;
 
     // Shrink as it ages.
-    float age = clamp(1.0 - LIFETIME / TOTAL_LIFETIME, 0.0, 1.0);
-    CUSTOM.x = age;
     float scale = mix(1.0, 0.35, age);
     TRANSFORM[0].xyz = vec3(scale, 0.0, 0.0);
     TRANSFORM[1].xyz = vec3(0.0, scale, 0.0);
@@ -224,36 +275,63 @@ func extinguish(fade_seconds: float = 0.5) -> void:
 ```
 GPUParticles3D ("Fire") [script: fire_controller.gd]
   ├── process_material: ParticleProcessMaterial (or ShaderMaterial w/ fire_process.gdshader)
-  └── draw_pass_1: QuadMesh (size 1.0 × 1.0)
-        └── surface_material_override[0]: ShaderMaterial (shader: fire.gdshader)
+  └── draw_pass_1: QuadMesh (size Vector2(1, 1))
+        └── material: ShaderMaterial (shader: fire.gdshader)
 ```
 
+`process_material` and `draw_pass_1` are resource properties on the one node, not
+child nodes. `surface_material_override` belongs to `MeshInstance3D` and does not
+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)
 
+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/Torch", type="GPUParticles3D", name="Fire")
-summer_set_prop(path="./World/Torch/Fire", property="script", value="res://addons/vfx/fire/fire_controller.gd")
+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(parent="./World/Torch/Fire", type="ParticleProcessMaterial", name="ProcessMat")
-summer_set_resource_property(nodePath="./World/Torch/Fire", resourceProperty="process_material", value="res://addons/vfx/fire/process_mat.tres")
+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")
 
-summer_set_resource_property(nodePath="./World/Torch/Fire", resourceProperty="draw_pass_1", value="res://addons/vfx/fire/quad.tres")
-# quad.tres is a QuadMesh with size (1,1) and surface_material_override[0] = fire_material.tres (ShaderMaterial wrapping fire.gdshader)
+# 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(path="./World/Torch/Fire", property="flame_height", value=1.2)
-summer_set_prop(path="./World/Torch/Fire", property="flame_radius", value=0.35)
-summer_set_prop(path="./World/Torch/Fire", property="particle_count", value=96)
+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_add_node(parent="./World/Torch", type="OmniLight3D", name="FireLight")
-summer_set_prop(path="./World/Torch/FireLight", property="light_color", value="Color(1.0, 0.6, 0.25)")
-summer_set_prop(path="./World/Torch/FireLight", property="light_energy", value=1.6)
-summer_set_prop(path="./World/Torch/FireLight", property="omni_range", value=6.0)
+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_save_scene
+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")
 ```
 
+### 6b. Verify
+
+Every file this recipe writes is compiled code. Check it before claiming the fire works.
+
+```
+summer_get_script_errors          # fire_controller.gd parsed?
+summer_play
+summer_get_debugger_errors        # shader compile errors surface here at runtime
+summer_stop
+```
+
+A missing `noise-3d-fbm.gdshaderinc` and an un-copied shader both show up as compile
+errors, not as an invisible flame. Read the errors before tuning any dial.
+
 ### 7. Parameters to tune
 
 | Parameter | Range | Effect |
@@ -337,12 +415,14 @@ OmniLight3D: light_color = Color(0.40, 0.65, 1.0), light_energy = 2.4
 - **Missing `cull_disabled`.** Particles billboard toward camera; if you cull backfaces, the flame disappears at certain angles.
 - **`depth_draw_opaque` on the visual material.** You'll z-fight with anything inside the flame (the torch handle). Use `depth_draw_never`.
 - **OmniLight3D parented under the GPUParticles3D.** The particles emit in local space; the light moves with them. Sibling, not child.
-- **Procedural noise computed in world space without a per-instance seed.** Every particle pulses identically, looking like a strobe. The included shader uses `CUSTOM.y` as a per-particle seed.
+- **Procedural noise computed in world space without a per-instance seed.** Every particle pulses identically, looking like a strobe. The included shader hashes `INSTANCE_ID` into a per-particle seed in `vertex()` and passes it to `fragment()` via a varying.
+- **Reading `CUSTOM` in `fragment()`.** In a `spatial` shader `CUSTOM` does not exist at all ("SHADER ERROR: Unknown identifier in expression: 'CUSTOM'"). The particle built-in is `INSTANCE_CUSTOM`, it is vertex-stage only, and `INSTANCE_CUSTOM.x` is the rotation angle — the age is in `.y`.
+- **Hand-rolling the billboard as `VIEW_MATRIX * mat4(INV_VIEW_MATRIX[0..2], MODEL_MATRIX[3])`.** That form discards per-particle scale *and* rotation, so `flame_radius`'s per-particle scale never reaches the screen. Use the full block in section 2.
 - **Generating a fire image and using it as the particle texture.** That's the misroute this skill exists to prevent. The shader-driven look is more alive and trivially recolorable.
 
 ## Performance notes
 
-- Default 96 particles per fire: ~0.05 ms on desktop GPU, scales linearly. Budget ~512 fire particles total in a scene before you should think about LOD.
+- Default 96 particles per fire is sub-millisecond on a desktop GPU and scales linearly with count. That is an order-of-magnitude expectation, not a measurement — profile your own scene before budgeting. Budget ~512 fire particles total in a scene before you should think about LOD.
 - Mobile: drop default to 48, disable the `OmniLight3D` shadow cast, and use a 64×64 noise texture instead of FBM if FPS dips.
 - LOD: in the controller's `_process`, scale `amount_ratio` by `clamp(1.0 - dist_to_camera / 30.0, 0.05, 1.0)`. Past 30 m, drop to a single billboard quad with the same shader (no particles).
 - The OmniLight3D shadow is the expensive part. Disable shadows on torches that aren't doing dramatic work.
@@ -358,13 +438,20 @@ OmniLight3D: light_color = Color(0.40, 0.65, 1.0), light_energy = 2.4
 
 ## Fallback (no MCP)
 
-VFX is code, no MCP required. The user can:
+Section 6 is fully automatable — `summer_write_file` writes the shaders and the
+controller, `summer_create_scene` + `summer_add_node` + `summer_set_prop` +
+`summer_save_scene` build and save `fire.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 the four files at `addons/vfx/fire/` with the contents above.
-2. In Godot, add a `GPUParticles3D` node, attach `fire_controller.gd`.
+1. Create the files at `addons/vfx/_building-blocks/` and `addons/vfx/fire/` with the contents above.
+2. Add a `GPUParticles3D` node, attach `fire_controller.gd`.
 3. Set `process_material` to a new `ParticleProcessMaterial` (the script configures it on `_ready`).
-4. Set `draw_pass_1` to a new `QuadMesh` (size 1×1), with `surface_material_override[0]` set to a `ShaderMaterial` whose shader is `fire.gdshader`.
+4. Set `draw_pass_1` to a new `QuadMesh` (size 1×1), with the mesh's `material` set to a `ShaderMaterial` whose shader is `fire.gdshader`.
 5. Save as `fire.tscn` and instantiate at every torch / brazier.
+6. Check the Errors dock — a missing `.gdshaderinc` fails the whole shader.
 
 ## Handoff
 

package/skills/visual-effects/recipes/hit-spark/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_replace_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/**"]
 ---
 
@@ -39,7 +39,7 @@ addons/vfx/hit-spark/hit_spark.gd
 addons/vfx/hit-spark/hit_spark.tscn
 ```
 
-No custom shader — uses the canonical additive billboard material (see `_building-blocks/additive-billboard-particles.md`). The default `BaseMaterial3D` with the right flags is enough.
+No custom shader — uses the canonical additive billboard material (see `_building-blocks/additive-billboard-particles.md`). A `StandardMaterial3D` with the right flags is enough. (`BaseMaterial3D` is abstract: `BaseMaterial3D.new()` is a parse error. Its enum constants are still the right names to use.)
 
 ### 2. GDScript controller
 
@@ -101,7 +101,9 @@ func _ensure_material() -> void:
     if draw_pass_1 == null:
         var mesh := QuadMesh.new()
         mesh.size = Vector2(0.08, 0.30) if stretch_to_velocity else Vector2(0.10, 0.10)
-        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
@@ -137,7 +139,12 @@ static func spawn_hit_spark(
     if not ResourceLoader.exists(scene_path):
         push_error("HitSpark: scene missing at %s" % scene_path)
         return null
+    # `var inst := load(...).instantiate()` cannot infer a type; the `as HitSpark`
+    # cast is what gives this one a static type.
     var inst := load(scene_path).instantiate() as HitSpark
+    if inst == null:
+        push_error("HitSpark: %s is not a HitSpark scene" % scene_path)
+        return null
     parent.add_child(inst)
     inst.global_position = position
     # Orient local +Y (cone direction) to the surface normal.
@@ -167,11 +174,34 @@ The script builds material and process material on `_ready` if missing, so the `
 
 ### 4. Wire it in (MCP calls)
 
-This recipe is a `.tscn` you instantiate per impact, not added once to the scene. After writing the files, the rest is gameplay code:
+This recipe is a `.tscn` you instantiate per impact, not added once to the open scene.
+Building that `.tscn` is itself an MCP job — `summer_create_scene` makes it,
+`summer_set_prop` attaches the script, `summer_save_scene` writes it out. Every
+scene-mutating call takes an explicit `scenePath`, and `summer_set_prop` uses `key`
+(not `property`).
 
 ```
-# No scene mutation — just create the .tscn at addons/vfx/hit-spark/hit_spark.tscn
-# with one root GPUParticles3D node, script attached, and save it.
+summer_write_file(path="res://addons/vfx/hit-spark/hit_spark.gd", content="<section 2>", create_only=true)
+
+summer_create_scene(path="res://addons/vfx/hit-spark/hit_spark.tscn", rootName="HitSpark", allow_temporary_scene_mutation=true)
+# The .tscn root must be a GPUParticles3D, since hit_spark.gd extends it.
+# Inspect what summer_create_scene produced and convert the root if it isn't one:
+summer_inspect_node(path="HitSpark")
+summer_replace_node(scenePath="res://addons/vfx/hit-spark/hit_spark.tscn", path=".", type="GPUParticles3D")
+summer_set_prop(scenePath="res://addons/vfx/hit-spark/hit_spark.tscn", path=".", key="script", value="res://addons/vfx/hit-spark/hit_spark.gd")
+summer_save_scene(scenePath="res://addons/vfx/hit-spark/hit_spark.tscn")
+```
+
+### 4b. Verify
+
+`hit_spark.gd` is the whole recipe — if it did not parse, every `spawn_hit_spark`
+call is a no-op.
+
+```
+summer_get_script_errors          # hit_spark.gd parsed?
+summer_play
+summer_get_debugger_errors        # e.g. a wrong root type on the .tscn shows up here
+summer_stop
 ```
 
 Then from any impact handler:
@@ -284,6 +314,7 @@ emission_boost = 9.0
 - **Skipping the surface-normal orientation.** Sparks always shoot upward regardless of impact direction. The `spawn_hit_spark` helper handles `look_at` + the −90° rotate-around-X (because `look_at` uses −Z as forward).
 - **Spawning the spark scene as a child of the impacted object.** If the object moves or frees, the sparks vanish. Spawn under the scene tree root.
 - **`BLEND_MODE_MIX` instead of `BLEND_MODE_ADD`.** Sparks don't bloom; they look like flat orange triangles.
+- **`BaseMaterial3D.new()`.** `BaseMaterial3D` is abstract — that line is a parse error and takes the whole script down. Instantiate `StandardMaterial3D`; keep using the `BaseMaterial3D.*` enum constants.
 - **Forgetting to free.** The `spawn_hit_spark` helper creates a `Timer`-equivalent via `get_tree().create_timer` to free after lifetime. Otherwise spent emitters accumulate forever.
 - **`spark_lifetime > 1.0` for sharp impacts.** Sparks lingering for a full second look like fairy dust. Keep ≤ 0.5 s for snappy hits.
 
@@ -305,11 +336,17 @@ emission_boost = 9.0
 
 ## Fallback (no MCP)
 
-VFX is code, no MCP required:
+Section 4 is fully automatable — `summer_write_file` writes the controller and
+`summer_create_scene` + `summer_set_prop` + `summer_save_scene` build `hit_spark.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/hit-spark/` with the two files above.
-2. In Godot, add a `GPUParticles3D` to a new scene, attach `hit_spark.gd`. Save as `hit_spark.tscn`.
+2. Add a `GPUParticles3D` to a new scene, attach `hit_spark.gd`. Save as `hit_spark.tscn`.
 3. From any impact handler: `HitSpark.spawn_hit_spark(get_tree().root, position, normal)`.
+4. Check the Errors dock before wiring the first impact.
 
 ## Handoff
 

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