summer-engine 2.7.0 → 2.8.1

package/skills/visual-effects/_building-blocks/additive-billboard-particles.md

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

package/skills/visual-effects/_building-blocks/trauma-shake-snippet.md

@@ -22,8 +22,7 @@ func _process(delta: float) -> void:
         if camera == null:
             return
     if trauma > 0.0:
-        var s = trauma * trauma     // perceived intensity grows quadratically
-        var t = Time.get_ticks_msec() * 0.01
+        var s := trauma * trauma  # perceived intensity grows quadratically
         camera.h_offset = max_offset.x * s * (randf() * 2.0 - 1.0)
         camera.v_offset = max_offset.y * s * (randf() * 2.0 - 1.0)
         camera.rotation.x += max_pitch * s * (randf() * 2.0 - 1.0) * 0.1
@@ -37,7 +36,10 @@ func add_trauma(amount: float) -> void:
     trauma = clamp(trauma + amount, 0.0, 1.0)
 ```
 
-Register `CameraShake` as autoload in Project Settings.
+Register `CameraShake` as autoload in Project Settings. An autoload is a node at
+`/root/CameraShake`, not an engine singleton — reach it with
+`get_node_or_null("/root/CameraShake")`. `Engine.has_singleton("CameraShake")` is
+always `false` for an autoload (measured), so never gate the call on it.
 
 ## Usage
 

package/skills/visual-effects/game-feel/SKILL.md

@@ -1,17 +1,22 @@
 ---
 name: game-feel
-description: Use when the user says the game "feels flat", "lacks impact", "needs juice", "needs punch", or asks for hit feedback, screen shake, camera shake, audio ducking, or general "game feel". Walks the user through the canonical Godot 4.5 game-feel stack — hit-flash + trauma camera shake + audio ducking — wired together so a single hit fires all three. Trigger on "vfx", "juice", "punch", "feels flat", "game feel", "hit flash", "screen shake", "camera shake", "ducking".
+description: Use when a Summer game "feels flat", "lacks impact", "needs juice", or "needs punch", or the user asks for hit feedback, screen shake, camera shake, audio ducking, or general game feel. Walks through Summer Engine's hit-flash, trauma camera shake, and audio-ducking stack, wired so one hit fires all three. Trigger on "vfx", "juice", "punch", "feels flat", "game feel", "hit flash", "screen shake", "camera shake", "ducking".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects
 user-invocable: true
-allowed-tools: Read Grep Edit Write summer_get_scene_tree summer_inspect_node summer_inspect_resource summer_add_node summer_set_prop summer_set_resource_property summer_connect_signal summer_save_scene summer_get_script_errors summer_play summer_stop
+allowed-tools: Read Grep Edit Write summer_write_file summer_read_file summer_get_scene_tree summer_inspect_node summer_inspect_resource summer_add_node summer_set_prop summer_set_resource_property summer_connect_signal summer_project_setting summer_save_scene summer_get_script_errors summer_get_debugger_errors summer_play summer_stop
 paths: ["**/*.gd", "**/*.tscn", "**/*.tres"]
 ---
 
 # /vfx — The Trio That Makes Games Feel Punchy
 
-Particles don't make a game feel good. Screen shake alone doesn't either. What makes a hit *land in the body* is three systems firing on the same frame: a sub-frame **hit flash** on the body that got hit, **trauma-based camera shake** with quadratic falloff so big hits saturate, and **audio ducking** that briefly squashes Music/Ambient so the impact SFX punches through. Skip any one and the game drops back to "tech demo". This skill installs the canonical Godot 4.5 stack — three small, self-contained systems wired to a single signal — so one `hit()` call fires all three.
+Particles do not make a game feel good. Screen shake alone does not either.
+What makes a hit land is three systems firing on the same frame: a sub-frame
+**hit flash** on the body that got hit, **trauma-based camera shake** with
+quadratic falloff so big hits saturate, and **audio ducking** that briefly
+squashes Music/Ambient so the impact SFX punches through. This skill installs
+the canonical Summer Engine stack as three small systems wired to one signal.
 
 ## Step 1 — Ask what feels flat
 
@@ -62,13 +67,15 @@ World/
     HitFlash (Node)              # holds the script, no transform
 ```
 
-**MCP path:**
+**MCP path** (every scene-mutating call takes an explicit `scenePath`):
 
 ```
-summer_add_node(parent="./World/Enemy", type="Node", name="HitFlash")
+summer_add_node(scenePath="res://levels/world.tscn", parent="./World/Enemy", type="Node", name="HitFlash")
+summer_set_prop(scenePath="res://levels/world.tscn", path="./World/Enemy/HitFlash", key="script", value="res://scripts/vfx/hit_flash.gd")
 ```
 
-Then write `scripts/vfx/hit_flash.gd`:
+Then write `scripts/vfx/hit_flash.gd` (via `summer_write_file`, which requires exactly
+one of `create_only` or `expected_sha256`):
 
 ```gdscript
 class_name HitFlash
@@ -110,7 +117,7 @@ func flash() -> void:
 
 **Tunable knobs:** `duration` 0.06–0.12s — under 0.06 reads as a flicker, over 0.12 looks slow. `emission_energy_multiplier` 1.5–3.0.
 
-> CRITICAL: do NOT inline a `StandardMaterial3D` as a `sub_resource` via `summer_set_prop`. Build it in script (as above) or save it to `materials/flash.tres`. Inline sub_resources break `summer_set_resource_property` silently — see `references/mcp-tools-reference.md` § "Trap".
+> CRITICAL: do NOT inline a `StandardMaterial3D` as a `sub_resource` via `summer_set_prop`. Build it in script (as above) or save it to `materials/flash.tres`. Inline sub_resources break `summer_set_resource_property` silently — see `../../../references/mcp-tools-reference.md` § "Trap".
 
 ## Step 5 — Install Section 2 (Trauma Camera Shake)
 
@@ -121,8 +128,8 @@ func flash() -> void:
 **Node tree:** the script attaches to the existing `./World/Player/Camera3D`. No new nodes.
 
 ```
-summer_inspect_node "./World/Player/Camera3D"
-# attach scripts/vfx/camera_shake.gd
+summer_inspect_node(path="./World/Player/Camera3D")
+summer_set_prop(scenePath="res://levels/world.tscn", path="./World/Player/Camera3D", key="script", value="res://scripts/vfx/camera_shake.gd")
 ```
 
 `scripts/vfx/camera_shake.gd`:
@@ -138,6 +145,11 @@ extends Camera3D
 var _trauma: float = 0.0
 var _shake_offset: Vector3 = Vector3.ZERO
 
+func _ready() -> void:
+    # Node has no `groups` property, so there is nothing to set from the outside.
+    # Joining the group here is how any actor finds this camera later.
+    add_to_group(&"player_camera")
+
 func add_trauma(amount: float) -> void:
     _trauma = clamp(_trauma + amount, 0.0, 1.0)
 
@@ -236,12 +248,9 @@ func duck(amount: float, duration: float = 0.5) -> void:
         var drop_db := -24.0 * amount * weight
         var target_db := base_db + drop_db
 
-        var seq := create_tween()
-        seq.tween_property(AudioServer, "bus_volume_db", target_db, attack).set_trans(Tween.TRANS_QUAD).set_ease(Tween.EASE_OUT)\
-            .from(base_db)
-        # NOTE: AudioServer doesn't expose bus volume as an animatable
-        # property — use a method tween instead. See actual call below.
-        # (The simpler, real implementation:)
+        # AudioServer exposes bus volume through a method, not an animatable
+        # property, so tween_method is the only form that works here.
+        # `tween_property(AudioServer, "bus_volume_db", ...)` errors at runtime.
         _tween.tween_method(_set_bus_db.bind(idx), base_db, target_db, attack)\
             .set_trans(Tween.TRANS_QUAD).set_ease(Tween.EASE_OUT)
         _tween.tween_method(_set_bus_db.bind(idx), target_db, base_db, release)\
@@ -255,9 +264,12 @@ func _set_bus_db(idx: int, db: float) -> void:
 Register it as an autoload:
 
 ```
-Project Settings → Autoload → Add scripts/vfx/audio_ducker.gd as "AudioDucker"
+summer_project_setting(...)   # autoload/AudioDucker = "*res://scripts/vfx/audio_ducker.gd"
 ```
 
+(Equivalently, by hand: Project Settings → Autoload → Add `scripts/vfx/audio_ducker.gd`
+as `AudioDucker`.)
+
 **Calling it:**
 
 ```gdscript
@@ -290,25 +302,27 @@ func _on_damaged(amount: float) -> void:
     # 1. Hit flash on this body.
     _hit_flash.flash()
     # 2. Camera shake on the player's camera, scaled by hit weight.
-    var trauma := clamp(0.2 + amount * 0.05, 0.2, 0.9)
+    # clampf(), not clamp(): clamp() returns Variant, and inferring a variable from
+    # a Variant is an error under Godot's default warning settings.
+    var trauma := clampf(0.2 + amount * 0.05, 0.2, 0.9)
     if _player_camera:
         _player_camera.add_trauma(trauma)
     # 3. Audio duck, scaled by hit weight.
-    var duck_amount := clamp(0.3 + amount * 0.04, 0.3, 1.0)
+    var duck_amount := clampf(0.3 + amount * 0.04, 0.3, 1.0)
     AudioDucker.duck(duck_amount, 0.45)
 ```
 
-Add the camera to a group so any actor can find it:
-
-```
-summer_add_node(...)   # ./World/Player/Camera3D already exists
-summer_set_prop(path="./World/Player/Camera3D", key="groups", value='["player_camera"]')
-```
+The camera joins `player_camera` from its own `_ready()` (Step 5). `Node` has no
+`groups` property, so `summer_set_prop(key="groups", ...)` cannot do this — and
+`summer_set_prop` only accepts a string, number, or boolean anyway, never an array.
+The two ways that do work are the `add_to_group()` call in `_ready()` or a `groups =
+["player_camera"]` line written into the `.tscn` node header.
 
-Or wire the signal explicitly via MCP if you prefer:
+Or wire the signal explicitly via MCP if you prefer (`emitter`/`receiver`, not
+`from`/`to`, and `scenePath` is required):
 
 ```
-summer_connect_signal(from="./World/Enemy", signal="damaged", to="./World/Enemy/HitFlash", method="flash")
+summer_connect_signal(scenePath="res://levels/world.tscn", emitter="./World/Enemy", signal="damaged", receiver="./World/Enemy/HitFlash", method="flash")
 ```
 
 ## Step 8 — Scaling intensity per hit weight
@@ -328,10 +342,11 @@ Because trauma is squared inside the camera, the *felt* difference between 0.35
 ## Step 9 — Verify
 
 ```
-summer_save_scene
-summer_get_script_errors
+summer_save_scene(scenePath="res://levels/world.tscn")
+summer_get_script_errors          # all three scripts parsed?
 summer_play
 # user reproduces a hit
+summer_get_debugger_errors        # runtime errors from the tweens / bus lookups
 summer_stop
 ```
 
@@ -355,10 +370,12 @@ Tune one knob at a time:
 | Equal pitch/yaw shake | `yaw_factor ≤ 0.5` | Eyes are sensitive to vertical motion; equal axes feel mechanical |
 | `Engine.time_scale` for every hit | Reserve hit-stop for big events only (boss hits, deaths) | Time-scale dips on every hit feel laggy, not impactful |
 | Inline `StandardMaterial3D` sub_resource via `summer_set_prop` | Build in script or save standalone `.tres` | Inline sub_resources silently break `summer_set_resource_property` |
+| `summer_set_prop(key="groups", value='["player_camera"]')` | `add_to_group(&"player_camera")` in `_ready()`, or a `groups = [...]` line in the `.tscn` | `Node` has no `groups` property, and `summer_set_prop` takes only string/number/boolean — never an array |
+| `BaseMaterial3D.new()` | `StandardMaterial3D.new()` | `BaseMaterial3D` is abstract; constructing it is a parse error that kills the whole script |
 
 ## Collaborative protocol
 
-This skill writes 3 GDScript files and adds 1 node + 1 autoload entry. Always ask before each section is applied. Group related writes into one ask: "I'm about to add HitFlash + CameraShake + AudioDucker autoload, wire one signal. OK?" See `references/collaborative-protocol.md`.
+This skill writes 3 GDScript files and adds 1 node + 1 autoload entry. Always ask before each section is applied. Group related writes into one ask: "I'm about to add HitFlash + CameraShake + AudioDucker autoload, wire one signal. OK?" See `../../../references/collaborative-protocol.md`.
 
 ## When NOT to use this skill
 
@@ -369,10 +386,11 @@ This skill writes 3 GDScript files and adds 1 node + 1 autoload entry. Always as
 
 ## See also
 
-- `references/mcp-tools-reference.md` — full MCP tool list, especially the inline-sub_resource trap
-- `references/godot-version.md` — Godot 4.5 API notes
-- `references/collaborative-protocol.md` — "May I write" pattern
-- `references/gd-style.md` — typed GDScript conventions
+- `../../../references/mcp-tools-reference.md` — full MCP tool list, especially the inline-sub_resource trap
+- `../../../references/godot-version.md` — Summer compatibility and
+  version-sensitive API notes
+- `../../../references/collaborative-protocol.md` — "May I write" pattern
+- `../../../references/gd-style.md` — typed GDScript conventions
 - `audio/audio-direction/SKILL.md` — bus layout setup (prerequisite for ducking)
 - `post-processing/screen-shake/SKILL.md` — deeper trauma variants (Perlin noise, stacked sources)
 - `visual-effects/gpuparticles-3d-basics/SKILL.md` — particles to layer on top of the trio

package/skills/visual-effects/recipes/dissolve/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_inspect_node summer_inspect_resource summer_get_script_errors summer_get_debugger_errors summer_play summer_stop
 paths: ["**/*.tscn", "**/*.gd", "**/*.gdshader", "addons/vfx/**"]
 ---
 
@@ -36,12 +36,17 @@ The dissolve shader samples 3D noise per fragment and clips pixels whose noise v
 ### 1. Files to create
 
 ```
+addons/vfx/_building-blocks/noise-3d-fbm.gdshaderinc   # copy from this skill FIRST
 addons/vfx/dissolve/dissolve.gdshader
 addons/vfx/dissolve/dissolve_controller.gd
 ```
 
 No `.tscn` needed — this overrides materials on existing meshes.
 
+`dissolve.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/dissolve/dissolve.gdshader`:
@@ -68,8 +73,16 @@ uniform vec3  noise_offset                            = vec3(0.0);
 uniform bool  use_object_space                        = true;
 
 void fragment() {
-    // Sample noise in object space so the dissolve pattern stays attached to the mesh.
-    vec3 npos = (use_object_space ? (inverse(MODEL_MATRIX) * vec4(VERTEX, 1.0)).xyz : VERTEX) * noise_scale + noise_offset;
+    // In fragment(), VERTEX is in VIEW space — not world, not object. Undo the view
+    // transform first, then the model transform, or neither branch samples where it
+    // claims to (`inverse(MODEL_MATRIX) * vec4(VERTEX, 1.0)` alone is object-space
+    // noise driven by camera-relative coordinates, which slides with the camera).
+    vec3 wpos = (INV_VIEW_MATRIX * vec4(VERTEX, 1.0)).xyz;
+    vec3 opos = (inverse(MODEL_MATRIX) * vec4(wpos, 1.0)).xyz;
+
+    // Object space keeps the dissolve pattern attached to the mesh; world space
+    // keeps it fixed in the level and lets the mesh move through it.
+    vec3 npos = (use_object_space ? opos : wpos) * noise_scale + noise_offset;
     float n = fbm3(npos);
 
     // Discard everything below the threshold.
@@ -204,7 +217,15 @@ No new nodes added. The recipe overrides the `material_override` on every `MeshI
 
 ### 5. Wire it in (MCP calls)
 
-This recipe is mostly script-driven, no scene mutation needed. Just create the files (Write tool) and call from gameplay code.
+This recipe is script-driven — no scene mutation. Write the two files with
+`summer_write_file` (one of `create_only` or `expected_sha256` is required), plus the
+`.gdshaderinc`, then call from gameplay code.
+
+```
+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/dissolve/dissolve.gdshader", content="<section 2>", create_only=true)
+summer_write_file(path="res://addons/vfx/dissolve/dissolve_controller.gd", content="<section 3>", create_only=true)
+```
 
 ```gdscript
 # When the enemy dies:
@@ -225,6 +246,20 @@ DissolveController.dissolve_object(target, 1.2, Color(1, 0.55, 0.1), 6.0, false)
 DissolveController.materialize_object(target, 0.8)
 ```
 
+### 5b. Verify
+
+Both files are compiled code. Check them before claiming the dissolve works.
+
+```
+summer_get_script_errors          # dissolve_controller.gd parsed?
+summer_play
+summer_get_debugger_errors        # shader compile errors surface here at runtime
+summer_stop
+```
+
+A missing `noise-3d-fbm.gdshaderinc` fails the whole shader, and the mesh then
+renders with the fallback material rather than dissolving.
+
 ### 6. Parameters to tune
 
 | Parameter | Range | Effect |
@@ -234,7 +269,7 @@ DissolveController.materialize_object(target, 0.8)
 | `edge_color` | Color | rim glow tint; orange = fire, blue = magic, green = poison, white = holy |
 | `edge_emission` | 0.0–16.0 | rim bloom strength; needs Bloom in WorldEnvironment |
 | `noise_scale` | 0.5–12.0 | small = big patches dissolving; large = fine pixel-grain dust |
-| `use_object_space` | bool | true = pattern attached to mesh; false = pattern stays in world (cool for moving objects) |
+| `use_object_space` | bool | true = pattern attached to mesh; false = pattern stays in world (cool for moving objects). Both branches derive their position from `INV_VIEW_MATRIX * vec4(VERTEX, 1.0)`, because `VERTEX` in `fragment()` is view space |
 
 ## Cookbook — named variants
 
@@ -304,13 +339,15 @@ noise_scale    = 4.0
 - **Dissolving a particle system (e.g., torch flame).** The shader is `spatial`, not `particles`. Stop the particles, don't try to dissolve them.
 - **Forgetting to seed `noise_offset` per instance.** Two enemies dissolving at the same frame use identical patterns → they look like clones. The included controller randomizes per-instance.
 - **Using world-space noise on a moving target.** The dissolve pattern slides over the surface as the mesh moves. Use `use_object_space = true` (default).
+- **Treating `VERTEX` in `fragment()` as world space.** It is view space. Sampling noise from it directly makes the pattern slide as the *camera* moves, and `inverse(MODEL_MATRIX) * vec4(VERTEX, 1.0)` is not object space either. Go through `INV_VIEW_MATRIX` first, as section 2 does.
 - **Skipping the texture inheritance.** The mesh dissolves but goes white because `base_color` defaults to white and no texture is set. The controller pulls from the original `BaseMaterial3D`; if your mesh uses a custom shader, manually wire the textures.
 - **Dissolving a `Skeleton3D` directly.** It's not a mesh — recurse into `MeshInstance3D` children. The controller's `_collect_meshes` does this.
 
 ## Performance notes
 
-- Per fragment: one FBM noise call + one branch. ~0.05 ms per dissolving object at 1080p covering 10% of the screen. Cheap.
-- Multiple meshes on a character (head, body, weapon, cape): each gets its own override. ~5 materials × 0.05 ms = 0.25 ms during the dissolve. Still fine.
+- Per fragment: one FBM noise call (4 octaves, 8 hashes each) + one branch + two 4×4 inversions. Sub-millisecond per dissolving object at 1080p covering 10% of the screen — an order-of-magnitude expectation, not a measurement. Profile if you need a number.
+- Multiple meshes on a character (head, body, weapon, cape): each gets its own override, and the cost scales with the number of materials. Still fine for a handful.
+- `inverse(MODEL_MATRIX)` runs per fragment. If you are dissolving a large screen-filling mesh and profiling says this hurts, hoist the object-space position into a `varying` computed in `vertex()`.
 - `discard` defeats early-Z. For a screen full of dissolving enemies, consider `cull_back` (already enabled) and avoid stacking 20+ dissolves at once.
 - Mobile: drop `noise_scale` to a value the FBM can compute in 1–2 octaves, or replace the `fbm3` include with a single-octave noise.
 
@@ -324,11 +361,16 @@ noise_scale    = 4.0
 
 ## Fallback (no MCP)
 
-VFX is code, no MCP required:
+Section 5 is fully automatable — `summer_write_file` writes all three files and
+`summer_get_script_errors` proves they parsed. 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 themselves:
 
-1. Create `addons/vfx/dissolve/` and write the two files above.
+1. Create `addons/vfx/_building-blocks/` and `addons/vfx/dissolve/` and write the three files above.
 2. From any gameplay script, call `DissolveController.dissolve_object(target_node)`.
 3. The controller handles material override, texture inheritance, tween, and freeing.
+4. Check the Errors dock — a missing `.gdshaderinc` fails the whole shader.
 
 ## Handoff