summer-engine 2.6.6 → 2.8.0

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
 

package/skills/visual-effects/recipes/water-ripple/SKILL.md

@@ -5,13 +5,13 @@ 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/**"]
 ---
 
 # water-ripple — Impact Ripples on a Water Plane
 
-Concentric expanding rings on a water surface, normal-distorted so the ripple actually refracts the reflection. The shader keeps a small ring buffer of (origin, time, amplitude) tuples and renders all of them simultaneously over a base water plane. GDScript exposes `add_ripple(world_pos, amplitude)` so any system (rain, footsteps, projectile impacts, fish) can spawn one with a single call. Tested in BotW-style stylized water and in flat-puddle FPS scenes.
+Concentric expanding rings on a water surface, normal-distorted so the ripple actually refracts the reflection. The shader keeps a small ring buffer of (origin, time, amplitude) tuples and renders all of them simultaneously over a base water plane. GDScript exposes `add_ripple(world_pos, amplitude)` so any system (rain, footsteps, projectile impacts, fish) can spawn one with a single call.
 
 ## When to use
 
@@ -60,6 +60,12 @@ uniform sampler2D normal_map : hint_normal;
 // Per-ripple data: (origin.xz, start_time, amplitude * (1 if active else 0))
 uniform vec4 ripples[MAX_RIPPLES];
 
+// Ripple ages run off the controller's own clock, pushed here every frame. They
+// cannot run off TIME: shader TIME wraps at
+// rendering/limits/time/time_rollover_secs (3600 by default, verified), which
+// would send every live ripple to a negative age once an hour of uptime.
+uniform float now = 0.0;
+
 uniform float ripple_speed       : hint_range(0.5, 8.0)  = 2.5;   // m/s expansion
 uniform float ripple_wavelength  : hint_range(0.05, 1.0) = 0.20;  // distance between crests
 uniform float ripple_lifetime    : hint_range(0.5, 6.0)  = 2.5;   // seconds visible
@@ -72,7 +78,7 @@ void vertex() {
     for (int i = 0; i < MAX_RIPPLES; i++) {
         vec4 r = ripples[i];
         if (r.w <= 0.0) continue;
-        float age = TIME - r.z;
+        float age = now - r.z;
         if (age < 0.0 || age > ripple_lifetime) continue;
         float dist = length(wpos.xz - r.xy);
         float front = age * ripple_speed;
@@ -95,7 +101,7 @@ void fragment() {
     for (int i = 0; i < MAX_RIPPLES; i++) {
         vec4 r = ripples[i];
         if (r.w <= 0.0) continue;
-        float age = TIME - r.z;
+        float age = now - r.z;
         if (age < 0.0 || age > ripple_lifetime) continue;
         vec2 d = wpos.xz - r.xy;
         float dist = length(d);
@@ -108,7 +114,11 @@ void fragment() {
         ripple_glow += ring * fade * r.w * 0.5;
     }
 
-    NORMAL_MAP = normalize(base_n + vec3(ripple_n.xy, 0.0));
+    // NORMAL_MAP is decoded by the engine (scene_forward_clustered.glsl:1427 —
+    // `normal_map.xy = normal_map.xy * 2.0 - 1.0`), so hand it the RAW [0,1] texel
+    // encoding. Assigning an already-decoded +/-1 vector makes a flat surface read
+    // as permanent maximum tilt.
+    NORMAL_MAP = normalize(base_n + vec3(ripple_n.xy, 0.0)) * 0.5 + 0.5;
     NORMAL_MAP_DEPTH = 0.6;
 
     // Fresnel-tinted color.
@@ -142,6 +152,7 @@ const MAX_RIPPLES := 16
 var _ripples: Array[Vector4] = []
 var _next_slot: int = 0
 var _mat: ShaderMaterial
+var _time: float = 0.0
 
 func _ready() -> void:
     _ripples.resize(MAX_RIPPLES)
@@ -168,21 +179,33 @@ func _apply() -> void:
 ## Spawn a ripple at a world position.
 ##   amplitude: 0..1 (raindrop ~0.2, footstep ~0.5, body splash ~1.0)
 func add_ripple(world_pos: Vector3, amplitude: float = 0.5) -> void:
-    var local := global_transform.affine_inverse() * world_pos
-    var t := float(Time.get_ticks_msec()) / 1000.0 - _shader_time_origin()
-    _ripples[_next_slot] = Vector4(world_pos.x, world_pos.z, t, clamp(amplitude, 0.0, 1.0))
+    # Stamp with our own clock, not Time.get_ticks_msec(): the shader compares
+    # against the same `now` uniform, so the two only line up if one source drives both.
+    _ripples[_next_slot] = Vector4(world_pos.x, world_pos.z, _time, clamp(amplitude, 0.0, 1.0))
     _next_slot = (_next_slot + 1) % MAX_RIPPLES
     _push()
 
+## True when `world_pos` is over this surface (XZ against the mesh's local AABB).
+## Use this rather than a containment method on the caller — there isn't one.
+func contains_point(world_pos: Vector3) -> bool:
+    if mesh == null:
+        return false
+    var local := to_local(world_pos)
+    var box := mesh.get_aabb()
+    return local.x >= box.position.x and local.x <= box.end.x \
+        and local.z >= box.position.z and local.z <= box.end.z
+
 func _push() -> void:
     if _mat == null: return
     _mat.set_shader_parameter("ripples", _ripples)
 
-func _shader_time_origin() -> float:
-    # Shader's TIME starts at scene load; align our timestamps to it.
-    return 0.0
-
-func _process(_delta: float) -> void:
+func _process(delta: float) -> void:
+    # Drive ripple age from this clock and push it every frame. Using the shader's
+    # TIME instead would silently kill every ripple after
+    # rendering/limits/time/time_rollover_secs (3600 s default) of uptime.
+    _time += delta
+    if _mat:
+        _mat.set_shader_parameter("now", _time)
     # Re-push so editor updates pick up changes; cheap.
     if Engine.is_editor_hint():
         _push()
@@ -198,20 +221,48 @@ MeshInstance3D ("Water") [script: water_ripple_surface.gd]
 
 ### 5. Wire it in (MCP calls)
 
+Every scene-mutating call takes an explicit `scenePath`. `summer_set_prop` uses `key`
+(not `property`); `summer_set_resource_property` always needs a `subProperty` and is
+for reaching *into* a resource, not for assigning one.
+
+```
+summer_write_file(path="res://addons/vfx/water-ripple/water_ripple.gdshader", content="<section 2>", create_only=true)
+summer_write_file(path="res://addons/vfx/water-ripple/water_ripple_surface.gd", content="<section 3>", create_only=true)
+
+summer_add_node(scenePath="res://main.tscn", parent="./World", type="MeshInstance3D", name="Puddle")
+summer_set_prop(scenePath="res://main.tscn", path="./World/Puddle", key="script", value="res://addons/vfx/water-ripple/water_ripple_surface.gd")
+summer_set_prop(scenePath="res://main.tscn", path="./World/Puddle", key="position", value="Vector3(0, 0.01, 0)")
+
+# Whole resources are assigned by path with summer_set_prop.
+summer_set_prop(scenePath="res://main.tscn", path="./World/Puddle", key="mesh", value="res://addons/vfx/water-ripple/plane.tres")
+# `normal_texture` is an exported script property on the controller, not a
+# MeshInstance3D property — MeshInstance3D has no `normal_texture`.
+summer_set_prop(scenePath="res://main.tscn", path="./World/Puddle", key="normal_texture", value="res://addons/vfx/water-ripple/water_normals.png")
+
+# subProperty is required — this is how you reach into the PlaneMesh itself.
+summer_set_resource_property(scenePath="res://main.tscn", nodePath="./World/Puddle", resourceProperty="mesh", subProperty="subdivide_width", value=32)
+summer_set_resource_property(scenePath="res://main.tscn", nodePath="./World/Puddle", resourceProperty="mesh", subProperty="subdivide_depth", value=32)
+
+summer_save_scene(scenePath="res://main.tscn")
 ```
-summer_add_node(parent="./World", type="MeshInstance3D", name="Puddle")
-summer_set_prop(path="./World/Puddle", property="script", value="res://addons/vfx/water-ripple/water_ripple_surface.gd")
-summer_set_prop(path="./World/Puddle", property="position", value="Vector3(0, 0.01, 0)")
-summer_set_resource_property(nodePath="./World/Puddle", resourceProperty="mesh", value="res://addons/vfx/water-ripple/plane.tres")
-summer_set_resource_property(nodePath="./World/Puddle", resourceProperty="normal_texture", value="res://addons/vfx/water-ripple/water_normals.png")
-summer_save_scene
+
+### 5b. Verify
+
+The shader and the controller are compiled code, and the controller `preload`s the
+shader — a shader that failed to write takes the script down at parse time.
+
+```
+summer_get_script_errors          # water_ripple_surface.gd parsed?
+summer_play
+summer_get_debugger_errors        # shader compile errors surface here at runtime
+summer_stop
 ```
 
 Then trigger ripples from any system. Footstep:
 
 ```gdscript
 # In your character controller's footstep callback:
-if puddle and puddle.is_in_water(global_position):
+if puddle and puddle.contains_point(global_position):
     puddle.add_ripple(global_position, 0.5)
 ```
 
@@ -295,13 +346,15 @@ ripple_wavelength= 0.40
 - **Spawning more than 16 ripples per surface.** The shader has a fixed array. Older ripples get overwritten — fine for rain (they were fading anyway), bad if you spawn 50 in one frame. Either raise `MAX_RIPPLES` (and the GLSL `MAX_RIPPLES`) together, or throttle spawns.
 - **Ripple position in local instead of world space.** The shader expects world XZ. Always convert in the GDScript before pushing.
 - **No normal map assigned.** The surface looks like flat-shaded plastic. Always assign a tileable water normals texture (any blue noise normals will do).
+- **Writing a decoded ±1 vector into `NORMAL_MAP`.** The engine decodes it again (`normal_map.xy = normal_map.xy * 2.0 - 1.0`), so a flat surface reads as permanent maximum tilt. Re-encode with `* 0.5 + 0.5` before assigning, as section 2 does.
+- **Timing ripples against shader `TIME`.** `TIME` wraps at `rendering/limits/time/time_rollover_secs` (3600 s default) and is not `Time.get_ticks_msec() / 1000`. Push your own accumulated clock as a uniform and compare against that; otherwise every ripple silently vanishes after an hour of uptime.
 - **PlaneMesh too low-res.** The vertex displacement needs ~2–4 verts per meter or the silhouette wobble looks blocky. Use `subdivide_width = 32, subdivide_depth = 32` minimum on a 10×10 plane.
 - **`depth_draw_disabled` on the water material.** You'll see the bottom of the puddle through the water at every angle. Use `depth_draw_opaque`.
 - **Triggering ripples in `_process` without spacing.** Spamming 60/sec floods the buffer. Throttle to ~5 ripples/sec for rain unless tuned.
 
 ## Performance notes
 
-- Cost is O(MAX_RIPPLES × pixels_drawn × 2). With 16 ripples on a 5×5 m puddle visible at 1080p: ~0.15 ms. Cheap.
+- Cost is O(MAX_RIPPLES × pixels_drawn) in the fragment loop plus O(MAX_RIPPLES × verts) in the vertex loop. 16 ripples on a 5×5 m puddle at 1080p is cheap — an order-of-magnitude expectation, not a measurement. Profile if you need a number.
 - The vertex displacement loop runs per vertex; raising plane subdivision past 64 starts to hurt. 32×32 is plenty.
 - For lakes (large planes), don't apply this shader to the entire lake — split the lake into chunks and only apply ripples to the chunk near impacts. Or use a `Decal` projection instead (see edge cases).
 - Mobile: drop `MAX_RIPPLES` to 8, disable vertex displacement (set `ripple_height = 0` and skip the vertex loop), and rely on normal-only ripples.
@@ -316,12 +369,19 @@ ripple_wavelength= 0.40
 
 ## Fallback (no MCP)
 
-VFX is code, no MCP required:
+Section 5 is fully automatable — `summer_write_file` writes the shader and the
+controller, and `summer_add_node` + `summer_set_prop` +
+`summer_set_resource_property` + `summer_save_scene` build the plane including its
+subdivision. 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/water-ripple/` and write the three files above.
-2. In Godot, add a `MeshInstance3D` with a high-subdivision `PlaneMesh`.
+2. Add a `MeshInstance3D` with a high-subdivision `PlaneMesh` (32×32 minimum).
 3. Attach `water_ripple_surface.gd` and assign a tileable water normals texture.
 4. From your trigger code, call `$Puddle.add_ripple(impact_pos, amplitude)`.
+5. Check the Errors dock — the controller `preload`s the shader, so a broken shader path fails the script too.
 
 ## Handoff
 

package/skills/workflow/brainstorming/SKILL.md

@@ -161,4 +161,4 @@ A browser-based companion for showing mockups, diagrams, and visual options duri
 A question about a UI topic is not automatically a visual question. "What does personality mean in this context?" is a conceptual question — use the terminal. "Which wizard layout works better?" is a visual question — use the browser.
 
 If they agree to the companion, read the detailed guide before proceeding:
-`skills/brainstorming/visual-companion.md`
+`skills/workflow/brainstorming/visual-companion.md`

package/skills/workflow/debugging-game-feel/SKILL.md

@@ -11,7 +11,7 @@ description: Use when a gameplay feature works correctly but feels wrong — flo
 
 **Core principle:** Game-feel bugs are tuning bugs, not logic bugs. Treat them with discipline — isolate one variable, compare to a reference, measure what you can, feel what you can't.
 
-This skill is for the diagnostic phase. The polish-and-juice layer (screen shake, hit-stop, particles, sound design) is `summer:visual-effects/game-feel` — go there once you've identified WHICH variable is wrong.
+This skill is for the diagnostic phase. The polish-and-juice layer (screen shake, hit-stop, particles, sound design) is `summer:game-feel` — go there once you've identified WHICH variable is wrong.
 
 ## When To Use
 
@@ -80,16 +80,36 @@ Two compare modes:
 
 **Feel:** subjective. The user (or you, if you have eyes on the screen) reports "warmer" or "colder." This is fine. Most game-feel work is felt, not measured.
 
-**Measure:** objective. When the feel is ambiguous, drop down to frame counts.
+**Measure:** objective. When the feel is ambiguous, drop down to frame counts — and take them yourself with a `RunVerification` probe rather than asking the user to eyeball anything. The probe presses the input, samples per frame, and hands back an array.
 
 | Question | Measurement |
 |---|---|
-| "Does the jump peak too fast?" | `print` the y-velocity in `_physics_process`, count frames from launch to peak |
-| "Is the camera too laggy?" | `print` `camera.global_position - target.global_position` per frame |
-| "Is the input dead?" | Log input event frame and resulting state-machine transition frame; subtract |
-| "Is the hit-stop too short?" | Log frame at hit + frame at unfreeze |
+| "Does the jump peak too fast?" | Probe: `press("jump")`, sample `player.velocity.y` every `process_frame`, count frames to the sign flip |
+| "Is the camera too laggy?" | Probe: sample `camera.global_position - target.global_position` per frame while driving movement |
+| "Is the input dead?" | Probe: report the frame input was injected and the frame the state machine changed; subtract |
+| "Is the hit-stop too short?" | Probe: report frame at hit and frame at unfreeze |
+
+Sketch:
+
+```gdscript
+extends SummerProbeBase
+func _ready() -> void:
+    await super._ready()
+    await get_tree().process_frame
+    var p := get_tree().root.find_child("Player", true, false)
+    var trace: Array = []
+    await press("jump", 100)
+    for i in 40:
+        await get_tree().process_frame
+        trace.append(p.velocity.y)
+    report("vel_y_per_frame", trace)
+    save_frame("apex")
+    finish()
+```
+
+Send it with `summer_batch ops:[{"op":"RunVerification","probe_source":"<the probe>","max_seconds":20}]`.
 
-The point of measurement is to ground the conversation in numbers when "feels off" stops being useful. You do not need to measure most tweaks — only the ambiguous ones.
+The point of measurement is to ground the conversation in numbers when "feels off" stops being useful. You do not need to measure most tweaks — only the ambiguous ones. **The verdict on whether it now feels right stays with the user** — that part is genuinely subjective, and it is the only part of this loop you hand over.
 
 ### 5. Decide
 
@@ -144,7 +164,7 @@ These are diagnostic tools, not lecture material. When the user says "feels weig
 | "The user said floaty so I'm jacking gravity" | "Floaty" can also mean weak air control, slow terminal velocity, or too-long apex hang. Confirm before tweaking. |
 | Skipping the play step ("I'll just bump the number and trust the feel") | Game feel is felt, not predicted. Play every tweak. |
 | Adding "while I'm here" tweaks to unrelated features | Game feel debugging is a focused activity. Stay on the one feature. |
-| Going to `summer:visual-effects/game-feel` before identifying the broken variable | Juice on top of a broken tuning makes the bug louder. Fix tuning first. |
+| Going to `summer:game-feel` before identifying the broken variable | Juice on top of a broken tuning makes the bug louder. Fix tuning first. |
 | Spending >30 minutes on one variable without progress | The anchor is wrong, or the variable is wrong. Step back, re-anchor. |
 
 ## Rationalization Prevention
@@ -161,7 +181,7 @@ These are diagnostic tools, not lecture material. When the user says "feels weig
 
 After diagnosis pins down which variable(s) are wrong, the tuning is done — but the feature may still want polish. Hand off to:
 
-- `summer:visual-effects/game-feel` — for the screen-shake, hit-stop, particle, sound layer once tuning is locked.
+- `summer:game-feel` — for the screen-shake, hit-stop, particle, sound layer once tuning is locked.
 - `summer:debug` — if mid-debug you discover an actual error (signal not firing, node freed) hiding under the feel issue.
 
 ## The Bottom Line

package/skills/workflow/diagnosing-perf-regressions/SKILL.md

@@ -42,21 +42,40 @@ You cannot fix a regression you have not measured. Eyeballing "feels laggy" is n
 
 ### 1. Measure now
 
+Measure in a `RunVerification` probe, not by eye. It spawns a hidden, disposable game instance with a real renderer, so `Performance.get_monitor(...)` returns the game's actual numbers and the user's editor session is untouched.
+
+```
+summer_batch ops:[{"op":"RunVerification","probe_source":"<probe>","max_seconds":20}]
 ```
-  summer_play  (on the scene that's slow)
-  ── wait 5-10 seconds of normal play ──
-  summer_get_diagnostics
-  summer_get_console
-  summer_stop
+
+```gdscript
+extends SummerProbeBase
+func _ready() -> void:
+    await super._ready()
+    await get_tree().process_frame
+    var samples: Array = []
+    for i in 30:                                  # ~5 s at 60 fps, sampled over time
+        await get_tree().create_timer(0.16).timeout
+        samples.append(Performance.get_monitor(Performance.TIME_FPS))
+    report("fps_samples", samples)                # spike pattern lives here
+    report("draw_calls", Performance.get_monitor(Performance.RENDER_TOTAL_DRAW_CALLS_IN_FRAME))
+    report("bodies_3d", Performance.get_monitor(Performance.PHYSICS_3D_ACTIVE_OBJECTS))
+    report("objects", Performance.get_monitor(Performance.RENDER_TOTAL_OBJECTS_IN_FRAME))
+    dump_tree()
+    finish()
 ```
 
 What to capture:
 
 | Metric | Source | Why |
 |---|---|---|
-| Avg FPS / frame time | `summer_get_diagnostics` or in-game perf monitor | Headline number |
-| Spike pattern | `summer_get_console` if user has frame-time prints, else in-game monitor | Steady 30 vs intermittent stutters → different causes |
-| Scene complexity | `summer_get_scene_tree` (root counts) | Establishes baseline for instance/body count cliffs |
+| Avg FPS / frame time | `Performance.TIME_FPS` / `TIME_PROCESS` sampled in the probe | Headline number |
+| Spike pattern | the per-sample FPS array above | Steady 30 vs intermittent stutters → different causes |
+| Scene complexity | probe `dump_tree()` for the live tree; `summer_get_scene_tree` for the edited scene | Establishes baseline for instance/body count cliffs |
+
+`summer_get_diagnostics` does **not** report performance. It returns counts of console errors, debugger errors, debugger warnings and script errors. Use it to confirm the slow run isn't also throwing, never as a source of FPS or draw-call numbers.
+
+Discard every sample from the first second — `TIME_FPS` is a per-second average and reads exactly `1.0` until it has a second of history. A leading run of `1.0` in the array is warm-up, not a stall.
 
 Write the bad-state number down. "Scene `Level3` runs at 31fps avg, drops to 12fps when 5+ enemies are on screen."
 
@@ -96,7 +115,7 @@ Read the list. Group commits into suspects:
 
 If a single commit is the obvious suspect (e.g. "Added 200 enemies to spawner"), test it first. Otherwise actually `git bisect` — check out the midpoint, measure FPS, repeat. Don't theorize through it; the bisect is fast and definitive.
 
-### 4. Match to one of the four Godot perf cliffs
+### 4. Match to one of the four Summer Engine performance cliffs
 
 Godot 4.x regressions cluster heavily into four categories. Knowing them shortens diagnosis to minutes.
 
@@ -127,13 +146,7 @@ If no → that wasn't it. Restore. Try the next suspect.
 
 The fix is not done until the same measurement that found the regression returns the good number. Same scene, same play duration, same warm-up.
 
-```
-  summer_clear_console
-  summer_play
-  ── 5-10 seconds of play ──
-  summer_get_diagnostics
-  summer_stop
-```
+Re-run the identical probe from step 1 — same scene, same sample count, same drive sequence. A number taken a different way is not a comparison.
 
 State the result with the number: "Reverted the per-frame `get_tree().get_nodes_in_group()` call in `enemy_manager.gd`. Level3 back to 58fps avg." Not "should be faster now."
 
@@ -156,7 +169,9 @@ State the result with the number: "Reverted the per-frame `get_tree().get_nodes_
 | Skipping the known-good measurement | Without a baseline, you don't know when you're done. |
 | Reading the slow scene's code top-to-bottom looking for inefficiency | The regression is in what changed, not in what was already there. |
 | Adding caching / pooling / LOD before identifying the cause | These are tuning moves. They can hide the regression instead of fixing it. |
-| Trusting editor FPS as ground truth | Editor runs `@tool` scripts, debug overlays, and a different render pipeline. Measure in a built or `--game` run when possible. |
+| Trusting editor FPS as ground truth | Editor runs `@tool` scripts, debug overlays, and a different render pipeline. Measure in a `RunVerification` probe or a built binary. |
+| Profiling with `--headless` | No renderer: draw calls read `0.0` and the FPS figure is a bare loop rate. The verify instance is windowed-offscreen for exactly this reason. |
+| Quoting FPS from `summer_get_diagnostics` | It returns error/warning counts only. That number did not come from where you said it did. |
 | "Maybe it's just a Tuesday thing" | Performance does not regress randomly. There is a cause. |
 
 ## Rationalization Prevention
@@ -171,11 +186,21 @@ State the result with the number: "Reverted the per-frame `get_tree().get_nodes_
 
 ## When The Engine Isn't Running
 
-If `summer_play` is unavailable:
+If the MCP tools report the engine isn't running:
+
+1. **Get it running.** `summer run` starts it and restores the probe route. That is one command, and it is almost always the right answer — do not degrade to interviewing the user because a tool returned "not running" once.
+2. **If you have shell access, you can run a probe without the editor at all.** The same verify instance is a plain flag on the Summer binary:
+
+   ```bash
+   "<summer-binary>" --path <project-dir> \
+     --summer-verify <abs/path/probe.gd> \
+     --summer-verify-out <abs/out-dir> \
+     --summer-verify-max 20
+   ```
 
-1. Ask the user for an in-game perf overlay screenshot (FPS, frame time, draw call count).
-2. Walk the bisect logically with them: "Run on commit X, tell me the FPS. Run on commit Y, tell me the FPS."
-3. Do not claim a fix is verified from code reading alone.
+   Then read `<out-dir>/results.json` (`reports`, `frames`, `errors_seen`, `duration_ms`). Locate the binary rather than guessing a path — on macOS it is the executable inside the installed `Summer.app` bundle. The probe file must extend the probe base; when you invoke the binary directly, write the base alongside it and `extends` it by path.
+3. Only if neither is possible: ask the user for an in-game perf overlay reading (FPS, frame time, draw call count) and walk the bisect with them — "run on commit X, tell me the FPS; run on commit Y, tell me the FPS."
+4. Do not claim a fix is verified from code reading alone.
 
 ## The Bottom Line
 

package/skills/workflow/gameskill/SKILL.md

@@ -17,9 +17,18 @@ This is the meta-skill: the loop that turns ad-hoc fixes into reusable expertise
 
 Three repos, one ecosystem:
 
-1. **SummerEngine repo** — the desktop engine (Godot fork in C++) plus the canonical CLI. Engine source: `editor/`, `core/`, and the Summer-specific module at `modules/1summer_engine/`. CLI source: `tools/summer-cli/`. The CLI ships as `npm i -g summer-engine`. It does install/login/create/run for the engine, plus `summer skills install --agent claude-code` which writes a curated subset of skills into `~/.claude/skills/` for any agent to auto-discover.
+1. **SummerEngine repo** — the Summer Engine desktop source plus the canonical
+   CLI. The C++ engine is maintained against the upstream Godot Engine codebase;
+   the Summer-owned module lives at `modules/1summer_engine/`. CLI source lives
+   at `tools/summer-cli/` and is normally invoked with
+   `npx -y summer-engine@latest`. It installs, signs in, creates, and runs Summer
+   projects and can install the current Summer skill bundle for supported
+   agents.
 2. **PublicSummerEngine repo** — the web app at summerengine.com. Has its own AI skill stores at `src/lib/ai/skills/bundled/` and `public/knowledge/summer/skills/` for the in-browser chat agent. Also has its own consumers of the engine API in `src/lib/bridge/direct-executor.ts` and `src/lib/ai/tools/run-and-verify.ts` which call the same engine endpoints the CLI does.
-3. **The active game project** — usually `~/development/<game-name>` (Godot 4.6) or whatever game you were just working on. Real working code in this repo is the gold standard for examples.
+3. **The active Summer game project** — usually
+   `~/development/<game-name>` or whatever game you were just working on. The
+   live compatibility line comes from Summer Engine, not this prompt. Real
+   working code in this repo is the gold standard for examples.
 
 The skill system is the value flywheel. Every game shipped teaches lessons. Lessons become skills. Next user starts smarter. Your job here is to close that loop for what you just did.