summer-engine 2.7.0 → 2.8.0

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
 

package/skills/visual-effects/recipes/smoke/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/**"]
 ---
 
@@ -36,11 +36,16 @@ Smoke is the same particle pattern as fire — billboard quads emitted from a sm
 ### 1. Files to create
 
 ```
+addons/vfx/_building-blocks/noise-3d-fbm.gdshaderinc   # copy from this skill FIRST
 addons/vfx/smoke/smoke.gdshader
 addons/vfx/smoke/smoke_controller.gd
 addons/vfx/smoke/smoke.tscn
 ```
 
+`smoke.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. Shader code
 
 `addons/vfx/smoke/smoke.gdshader`:
@@ -59,20 +64,41 @@ uniform float noise_speed       : hint_range(0.0, 2.0) = 0.5;
 uniform float soft_edge         : hint_range(0.01, 0.5) = 0.30;
 uniform float depth_fade        : hint_range(0.0, 4.0) = 1.0;  // soft against geometry behind
 
+// INSTANCE_CUSTOM is vertex-stage only, so carry what fragment() needs across.
+varying float age;
+varying float seed;
+
 void vertex() {
-    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() {
-    float age = CUSTOM.x;
-
     // Distort UVs with slow noise.
-    vec3 np = vec3(UV * noise_scale, TIME * noise_speed + CUSTOM.y * 10.0);
+    vec3 np = vec3(UV * noise_scale, TIME * noise_speed + seed * 10.0);
     float n = fbm3(np);
 
     // Soft round mask, modulated by noise so the silhouette is wispy not circular.
@@ -162,6 +188,10 @@ func _apply() -> void:
 
 func _make_scale_curve(end_mult: float) -> CurveTexture:
     var c := Curve.new()
+    # Curve clamps every sample to max_value, which defaults to 1.0. Without this
+    # line every end multiplier above 1.0 is silently flattened back to 1.0 and the
+    # whole cookbook's growth numbers do nothing.
+    c.max_value = maxf(1.0, end_mult)
     c.add_point(Vector2(0.0, 0.4))
     c.add_point(Vector2(0.3, 1.0))
     c.add_point(Vector2(1.0, end_mult))
@@ -188,30 +218,52 @@ func stop_smoke(fade_seconds: float = 1.5) -> void:
 ```
 GPUParticles3D ("Smoke") [script: smoke_controller.gd]
   ├── process_material: ParticleProcessMaterial
-  └── draw_pass_1: QuadMesh (size 1.0 × 1.0)
-        └── surface_material_override[0]: ShaderMaterial (shader: smoke.gdshader)
+  └── draw_pass_1: QuadMesh (size Vector2(1, 1))
+        └── material: ShaderMaterial (shader: smoke.gdshader)
 ```
 
+`process_material` and `draw_pass_1` are resource properties on the one node, not
+child nodes, and `ParticleProcessMaterial` is a `Material` — you cannot
+`summer_add_node` it.
+
 ### 5. Wire it in (MCP calls)
 
+Every scene-mutating call takes an explicit `scenePath`. `summer_set_prop` uses `key`
+(not `property`) and only accepts a string, number, or boolean.
+
 For chimney smoke or fire pairing, parent the Smoke just above the heat source:
 
 ```
-summer_add_node(parent="./World/Cottage/Chimney", type="GPUParticles3D", name="Smoke")
-summer_set_prop(path="./World/Cottage/Chimney/Smoke", property="script", value="res://addons/vfx/smoke/smoke_controller.gd")
-summer_set_prop(path="./World/Cottage/Chimney/Smoke", property="position", value="Vector3(0, 0.3, 0)")
-summer_set_prop(path="./World/Cottage/Chimney/Smoke", property="rise_height", value=4.0)
-summer_set_prop(path="./World/Cottage/Chimney/Smoke", property="particle_count", value=48)
-summer_set_prop(path="./World/Cottage/Chimney/Smoke", property="wind_direction", value="Vector3(0.4, 0, 0.1)")
-summer_save_scene
+summer_write_file(path="res://addons/vfx/_building-blocks/noise-3d-fbm.gdshaderinc", content="<from this skill>", create_only=true)
+summer_write_file(path="res://addons/vfx/smoke/smoke.gdshader", content="<section 2>", create_only=true)
+summer_write_file(path="res://addons/vfx/smoke/smoke_controller.gd", content="<section 3>", create_only=true)
+
+summer_add_node(scenePath="res://main.tscn", parent="./World/Cottage/Chimney", type="GPUParticles3D", name="Smoke")
+summer_set_prop(scenePath="res://main.tscn", path="./World/Cottage/Chimney/Smoke", key="script", value="res://addons/vfx/smoke/smoke_controller.gd")
+summer_set_prop(scenePath="res://main.tscn", path="./World/Cottage/Chimney/Smoke", key="position", value="Vector3(0, 0.3, 0)")
+summer_set_prop(scenePath="res://main.tscn", path="./World/Cottage/Chimney/Smoke", key="rise_height", value=4.0)
+summer_set_prop(scenePath="res://main.tscn", path="./World/Cottage/Chimney/Smoke", key="particle_count", value=48)
+summer_set_prop(scenePath="res://main.tscn", path="./World/Cottage/Chimney/Smoke", key="wind_direction", value="Vector3(0.4, 0, 0.1)")
+summer_save_scene(scenePath="res://main.tscn")
 ```
 
 For pairing with a fire:
 
 ```
-summer_add_node(parent="./World/Campfire", type="GPUParticles3D", name="Smoke")
-summer_set_prop(path="./World/Campfire/Smoke", property="position", value="Vector3(0, 1.5, 0)")  # above flame top
-summer_set_prop(path="./World/Campfire/Smoke", property="rise_height", value=3.0)
+summer_add_node(scenePath="res://main.tscn", parent="./World/Campfire", type="GPUParticles3D", name="Smoke")
+summer_set_prop(scenePath="res://main.tscn", path="./World/Campfire/Smoke", key="position", value="Vector3(0, 1.5, 0)")  # above flame top
+summer_set_prop(scenePath="res://main.tscn", path="./World/Campfire/Smoke", key="rise_height", value=3.0)
+```
+
+### 5b. Verify
+
+The shader and the controller are compiled code. Check them before tuning anything.
+
+```
+summer_get_script_errors          # smoke_controller.gd parsed?
+summer_play
+summer_get_debugger_errors        # shader compile errors surface here at runtime
+summer_stop
 ```
 
 For a rocket trail (smoke follows the rocket):
@@ -323,13 +375,15 @@ color_old      = Color(0.65, 0.68, 0.75)
 - **Forgetting `cull_disabled`.** Billboarded quads disappear at certain camera angles otherwise.
 - **`puff_lifetime < 1.0`.** Smoke needs time to spread out and dilute. Short-lifetime smoke looks like spray.
 - **No scale curve.** Smoke that doesn't grow looks like a row of identical balls. The controller's `_make_scale_curve` ramps from 0.4× → 1.0× → end_mult.
+- **A scale curve built without raising `Curve.max_value`.** `Curve` defaults to `max_value = 1.0` and silently clamps, so every `end_scale_multiplier` above 1.0 is inert and the smoke never grows. Set `c.max_value` before adding the points.
+- **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`.
 - **`emission_energy > 0` on the shader's quad material.** Smoke isn't bright. Keep `unshaded` and let `ALBEDO` carry the look. (The shader as written has no EMISSION line — correct.)
 - **Smoke local-space when paired with a moving emitter (rocket).** Set `local_coords = false` so puffs stay where they were emitted.
-- **Skipping the angular velocity.** Static-rotation smoke looks weird. The controller adds ±25 deg/s for organic tumbling.
+- **Skipping the angular velocity.** Static-rotation smoke looks weird. The controller adds ±25 deg/s for organic tumbling — but that only reaches the screen if the vertex billboard applies the `INSTANCE_CUSTOM.x` rotation, which is why section 2 uses the full block rather than the bare `VIEW_MATRIX * mat4(INV_VIEW_MATRIX[0..2], MODEL_MATRIX[3])` form.
 
 ## Performance notes
 
-- Default 48 particles per smoke source: ~0.03 ms on desktop.
+- Default 48 particles per smoke source is sub-millisecond on desktop. That is an order-of-magnitude expectation, not a measurement — profile your own scene.
 - Heavy `density` at high count (128 particles, density 0.85) gets fillrate-bound — overdraw on a screen full of smoke. Budget ~256 smoke particles total visible at once.
 - Mobile: drop default to 24, drop `puff_lifetime` to 2.5, drop `density` to 0.35.
 - LOD: scale `amount_ratio` by `clamp(1.5 - dist_to_camera / 40.0, 0.10, 1.0)` for distant chimneys.
@@ -356,13 +410,20 @@ ALPHA *= clamp(d * depth_fade, 0.0, 1.0);
 
 ## Fallback (no MCP)
 
-VFX is code, no MCP required:
+Section 5 is fully automatable — `summer_write_file` writes the shader and the
+controller, `summer_create_scene` + `summer_add_node` + `summer_set_prop` +
+`summer_save_scene` build and save `smoke.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/smoke/` with the three files.
-2. In Godot, add a `GPUParticles3D`, attach `smoke_controller.gd`.
+1. Create `addons/vfx/_building-blocks/` and `addons/vfx/smoke/` with the files above.
+2. Add a `GPUParticles3D`, attach `smoke_controller.gd`.
 3. Set `process_material` to a new `ParticleProcessMaterial` (script configures it).
-4. Set `draw_pass_1` to a new `QuadMesh` with `surface_material_override[0]` = `ShaderMaterial(smoke.gdshader)`.
+4. Set `draw_pass_1` to a new `QuadMesh` with its `material` = `ShaderMaterial(smoke.gdshader)`.
 5. Save as `smoke.tscn`; instantiate at every smoke source.
+6. Check the Errors dock — a missing `.gdshaderinc` fails the whole shader.
 
 ## Handoff