summer-engine 3.3.0 → 3.4.1

package/library/skills/vfx-fire/_building-blocks/additive-billboard-particles.md

@@ -1,6 +1,6 @@
 # Additive Billboard Particles — Canonical Material Settings
 
-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.
+Reusable material configuration for additive particle billboards (motes, sparks, glow, ash). Used by `vfx-magic-glow`, optionally substitutable in `vfx-hit-spark` and `vfx-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
@@ -27,8 +27,8 @@ bm.emission = Color(R, G, B)          # usually same as albedo for single-color
 
 ## When to use this vs a custom shader
 
-- **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 this `StandardMaterial3D` config** when the effect is just a tinted soft-circle mote (magic glow, sparkles, dust). Less code, faster iteration, free engine-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 present on the shipped engine) — 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`.
 

package/library/skills/vfx-hit-spark/SKILL.md

@@ -21,14 +21,14 @@ Tiny stretched additive billboards spraying outward from an impact point, orient
 - "Footstep sparks on stone for the heavy armor."
 - "Ricochet sparks when the projectile glances off."
 - "Mining: sparks fly when pickaxe hits rock."
-- Endpoint sparks on `lightning` and `muzzle-flash` recipes (they reference this).
+- Endpoint sparks on `vfx-lightning` and `vfx-muzzle-flash` recipes (they reference this).
 
 ## When NOT to use
 
-- The user wants a *flash* at the impact, not a spray of particles — use `muzzle-flash` (recolor it).
+- The user wants a *flash* at the impact, not a spray of particles — use `vfx-muzzle-flash` (recolor it).
 - The user wants debris chunks (rock pieces, splinters) — those are physics objects, not particles. Spawn `RigidBody3D` shards, then sparks on top.
-- The user wants water droplets at a water impact — recolor this recipe blue/white (it works) or pair with `water-ripple` for the ring on the surface.
-- The user wants persistent burning sparks that linger and cool down — that's a hybrid; use this for the burst, then tiny `fire` particles for residual embers.
+- The user wants water droplets at a water impact — recolor this recipe blue/white (it works) or pair with `vfx-water-ripple` for the ring on the surface.
+- The user wants persistent burning sparks that linger and cool down — that's a hybrid; use this for the burst, then tiny `vfx-fire` particles for residual embers.
 
 ## Recipe
 

package/library/skills/vfx-hit-spark/_building-blocks/additive-billboard-particles.md

@@ -1,6 +1,6 @@
 # Additive Billboard Particles — Canonical Material Settings
 
-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.
+Reusable material configuration for additive particle billboards (motes, sparks, glow, ash). Used by `vfx-magic-glow`, optionally substitutable in `vfx-hit-spark` and `vfx-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
@@ -27,8 +27,8 @@ bm.emission = Color(R, G, B)          # usually same as albedo for single-color
 
 ## When to use this vs a custom shader
 
-- **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 this `StandardMaterial3D` config** when the effect is just a tinted soft-circle mote (magic glow, sparkles, dust). Less code, faster iteration, free engine-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 present on the shipped engine) — 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`.
 

package/library/skills/vfx-lightning/SKILL.md

@@ -11,20 +11,20 @@ paths: ["**/*.tscn", "**/*.gd", "**/*.gdshader", "addons/vfx/**"]
 
 # lightning — Procedural Jagged Bolt
 
-A lightning bolt is a noisy line from A to B, drawn for ~150 ms with a glow shader, sparks at both endpoints, and camera shake on cast. The recipe builds the jagged path in GDScript (midpoint displacement on a polyline), feeds the verts into an `ImmediateMesh`, applies a `ShaderMaterial` for additive bloom + flicker, spawns `hit-spark` particles at each endpoint, and calls `CameraShake.add_trauma(0.6)` for the impact. Used for shock spells, tesla coils, weapon discharges, electric enemies.
+A lightning bolt is a noisy line from A to B, drawn for ~150 ms with a glow shader, sparks at both endpoints, and camera shake on cast. The recipe builds the jagged path in GDScript (midpoint displacement on a polyline), feeds the verts into an `ImmediateMesh`, applies a `ShaderMaterial` for additive bloom + flicker, spawns `vfx-hit-spark` particles at each endpoint, and calls `CameraShake.add_trauma(0.6)` for the impact. Used for shock spells, tesla coils, weapon discharges, electric enemies.
 
 ## When to use
 
 - "Cast a lightning bolt from the wizard's hand to the enemy."
 - "Chain lightning from one enemy to the next." (call `cast_lightning` per segment)
 - "Tesla coil firing at the player every 2 seconds."
-- "Energy weapon laser." (use the `laser-beam` variant)
+- "Energy weapon laser." (use the `plasma-laser` variant)
 - "Lightning strike from the sky."
 - The user wants a *short, dramatic* energy connection between two points.
 
 ## When NOT to use
 
-- The user wants a continuous beam that holds (e.g., laser sniper holding the trigger) — use the same shader on a `MeshInstance3D` cylinder with continuous emission, not the `ImmediateMesh` one-shot pattern. (See variants for `held-beam`.)
+- The user wants a continuous beam that holds (e.g., laser sniper holding the trigger) — use the same shader on a `MeshInstance3D` cylinder with continuous emission, not the `ImmediateMesh` one-shot pattern. (See the `plasma-laser` variant.)
 - The user wants ambient electricity *on* an object (Frankenstein arcs) — use a custom shader on the mesh with screen-space arcs; this recipe is for two-point bolts.
 - The user wants a 2D lightning effect on UI — `canvas_item` shader, not this.
 - The user wants a tracer line for a bullet — use a simple `ImmediateMesh`
@@ -369,7 +369,7 @@ trauma_amount = 0.0  # no shake on a held beam
 
 - One bolt at `SEGMENTS = 18`: 19 path points × 2 verts = 38 verts for the trunk, plus 2 × (`SEGMENTS / 3` + 1) = 14 verts per forked branch. One draw call, freed after 150 ms. Effectively free.
 - Chain lightning with 5 segments stays in the same negligible band — that is an order-of-magnitude expectation, not a measurement.
-- Endpoint sparks (instantiated `hit-spark` scenes) are the bigger cost — 64 particles × 2 = 128 particles per cast. Throttle for storms (see edge cases).
+- Endpoint sparks (instantiated `vfx-hit-spark` scenes) are the bigger cost — 64 particles × 2 = 128 particles per cast. Throttle for storms (see edge cases).
 - The shader's flicker uses `floor(TIME * flicker_rate)`, so it ages with `TIME` not particle time — flicker is consistent across all bolts in flight.
 
 ## Edge cases
@@ -378,7 +378,7 @@ trauma_amount = 0.0  # no shake on a held beam
 - **Bolt passes through a wall.** Visual only — the bolt shader doesn't depth test. If the user wants the bolt to be occluded by walls, set `depth_draw_opaque` and let the depth buffer cull it (loses the additive bloom in front of geometry).
 - **Bolt origin and target at the same point.** Falloff goes to zero; `_generate_path` returns a degenerate strip. Add a guard: if `(to - from).length() < 0.01`, skip.
 - **Underwater bolt.** Tint blue-green, drop `emission_boost` to 5.0; underwater bloom is muted.
-- **First-person caster (player's hand).** The bolt starts inside the player's view and reads as a flash. Use a `held-beam` variant or shorten `LIFETIME` to 0.08.
+- **First-person caster (player's hand).** The bolt starts inside the player's view and reads as a flash. Use the `plasma-laser` variant or shorten `LIFETIME` to 0.08.
 - **No `CameraShake` autoload registered.** `get_node_or_null("/root/CameraShake")` returns null and the `if cs` check skips the call; the bolt fires without shake. Suggest `_building-blocks/trauma-shake-snippet.md` to wire it.
 
 ## Fallback (no MCP)

package/library/skills/vfx-lightning/_building-blocks/additive-billboard-particles.md

@@ -1,6 +1,6 @@
 # Additive Billboard Particles — Canonical Material Settings
 
-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.
+Reusable material configuration for additive particle billboards (motes, sparks, glow, ash). Used by `vfx-magic-glow`, optionally substitutable in `vfx-hit-spark` and `vfx-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
@@ -27,8 +27,8 @@ bm.emission = Color(R, G, B)          # usually same as albedo for single-color
 
 ## When to use this vs a custom shader
 
-- **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 this `StandardMaterial3D` config** when the effect is just a tinted soft-circle mote (magic glow, sparkles, dust). Less code, faster iteration, free engine-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 present on the shipped engine) — 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`.
 

package/library/skills/vfx-lightning/_building-blocks/trauma-shake-snippet.md

@@ -1,6 +1,6 @@
 # Trauma Camera Shake — Reusable Snippet
 
-Variant of the canonical "trauma model" shake (see `visual-effects/game-feel/SKILL.md` for the full game-feel discipline). Lightning and explosion recipes call `add_trauma()` to chain visual impact with screen-level reaction.
+Variant of the canonical "trauma model" shake (the `game-feel` skill has the full game-feel discipline). Lightning and explosion recipes call `add_trauma()` to chain visual impact with screen-level reaction.
 
 ## Setup (autoload script)
 
@@ -15,18 +15,24 @@ var max_offset: Vector3 = Vector3(0.4, 0.4, 0.0)
 var max_yaw: float = 0.05
 var max_pitch: float = 0.05
 var camera: Camera3D
+var _rot_offset := Vector2.ZERO  # shake rotation applied last frame
 
 func _process(delta: float) -> void:
     if camera == null:
         camera = get_viewport().get_camera_3d()
         if camera == null:
             return
+    # Undo last frame's shake first, so the camera never drifts.
+    camera.rotation.x -= _rot_offset.x
+    camera.rotation.y -= _rot_offset.y
+    _rot_offset = Vector2.ZERO
     if trauma > 0.0:
         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
-        camera.rotation.y += max_yaw * s * (randf() * 2.0 - 1.0) * 0.1
+        _rot_offset = Vector2(max_pitch * s * (randf() * 2.0 - 1.0), max_yaw * s * (randf() * 2.0 - 1.0))
+        camera.rotation.x += _rot_offset.x
+        camera.rotation.y += _rot_offset.y
         trauma = max(0.0, trauma - trauma_decay * delta)
     else:
         camera.h_offset = 0.0

package/library/skills/vfx-magic-glow/SKILL.md

@@ -21,13 +21,13 @@ Three layered cues that together read as "magical": a pulsing `OmniLight3D` (sin
 - "Wisp / fairy / firefly companion."
 - "The summoning circle is active."
 - "Quest item glows so the player notices it."
-- Pre-charge phase before casting `lightning` or `muzzle-flash` (charge-up beam).
+- Pre-charge phase before casting `vfx-lightning` or `vfx-muzzle-flash` (charge-up beam).
 
 ## When NOT to use
 
 - The user wants a static, non-animated glow — just enable emission on the mesh's material; this recipe is overkill.
-- The user wants flames, not a glow — use `fire` (or `magic-fire` variant of `fire`).
-- The user wants a beam shooting out, not an aura — use `lightning` with the `plasma-laser` variant.
+- The user wants flames, not a glow — use `vfx-fire` (or `magic-fire` variant of `vfx-fire`).
+- The user wants a beam shooting out, not an aura — use `vfx-lightning` with the `plasma-laser` variant.
 - The user wants a screen-space bloom on the whole scene — that's `WorldEnvironment.glow_*`, not a per-object recipe.
 - The user wants a 2D glow on a UI sprite — use `canvas_item` shader with a radial gradient, not this 3D recipe.
 
@@ -415,7 +415,7 @@ manually in Summer Engine:
 
 After firing this recipe, suggest:
 
-- `vfx-lightning` — perfect pre-cast charge-up. Use the `charge-up` variant and ramp `set_intensity(0→1)` then call `Lightning.cast_lightning`.
+- `vfx-lightning` — pre-cast charge-up. Use this skill's `charge-up` variant, ramp `set_intensity(0→1)` then call `Lightning.cast_lightning`.
 - `vfx-dissolve` — pair `summon-arrival` (materialize_object) with the `summoning-circle` variant.
 - `vfx-fire` (the `magic-fire` variant) — for items that should glow AND flame.
 - `game-feel` — slight time-dilation when picking up a pulsing quest item adds weight.

package/library/skills/vfx-magic-glow/_building-blocks/additive-billboard-particles.md

@@ -1,6 +1,6 @@
 # Additive Billboard Particles — Canonical Material Settings
 
-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.
+Reusable material configuration for additive particle billboards (motes, sparks, glow, ash). Used by `vfx-magic-glow`, optionally substitutable in `vfx-hit-spark` and `vfx-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
@@ -27,8 +27,8 @@ bm.emission = Color(R, G, B)          # usually same as albedo for single-color
 
 ## When to use this vs a custom shader
 
-- **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 this `StandardMaterial3D` config** when the effect is just a tinted soft-circle mote (magic glow, sparkles, dust). Less code, faster iteration, free engine-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 present on the shipped engine) — 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`.
 

package/library/skills/vfx-muzzle-flash/SKILL.md

@@ -11,7 +11,7 @@ paths: ["**/*.tscn", "**/*.gd", "**/*.gdshader", "addons/vfx/**"]
 
 # muzzle-flash — One-Shot Star-Burst Flare
 
-A muzzle flash is on screen for 60–100 ms. Long enough to read, too short to animate. The recipe: a single billboarded quad with a star-burst gradient shader, fired by `restart()` on a weapon's `fired` signal, plus an `OmniLight3D` snapping on for 60 ms to light the room. Optional: a tiny GPUParticles3D one-shot for sparks. Doom Eternal does this. Half-Life 2 did this. Every shooter does this.
+A muzzle flash is on screen for 60–100 ms. Long enough to read, too short to animate. The recipe: a single billboarded quad with a star-burst gradient shader, fired by `restart()` on a weapon's `fired` signal, plus an `OmniLight3D` snapping on for 60 ms to light the room. Optional: a tiny GPUParticles3D one-shot for sparks. Most shooters use this pattern.
 
 ## When to use
 
@@ -23,12 +23,12 @@ A muzzle flash is on screen for 60–100 ms. Long enough to read, too short to a
 
 ## When NOT to use
 
-- 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 *continuous* flame (flamethrower) — use `vfx-fire`, not muzzle-flash.
+- The user wants the impact spark on the wall the bullet hit — that's `vfx-hit-spark`.
 - 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.
+- The user wants a slow-glowing spell charge-up — use `vfx-magic-glow` for the buildup, then this for the release frame.
 
 ## Recipe
 
@@ -377,7 +377,7 @@ After firing this recipe, suggest:
 
 - `vfx-hit-spark` — pair on the bullet impact end.
 - `vfx-smoke` — for a small puff at the barrel after the flash for high-caliber weapons.
-- `game-feel` — recoil camera kick + screen shake (`CameraShake.add_trauma(0.15)`) on every shot makes the flash feel 5× more powerful.
+- `game-feel` — recoil camera kick + screen shake (`CameraShake.add_trauma(0.15)`) on every shot makes the flash land much harder.
 - `sound-effect` — generate `9mm pistol shot, sharp crack, indoor, short tail, 400ms` and play in the same `fire()`.
 
 ## See also

package/library/skills/vfx-muzzle-flash/_building-blocks/additive-billboard-particles.md

@@ -1,6 +1,6 @@
 # Additive Billboard Particles — Canonical Material Settings
 
-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.
+Reusable material configuration for additive particle billboards (motes, sparks, glow, ash). Used by `vfx-magic-glow`, optionally substitutable in `vfx-hit-spark` and `vfx-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
@@ -27,8 +27,8 @@ bm.emission = Color(R, G, B)          # usually same as albedo for single-color
 
 ## When to use this vs a custom shader
 
-- **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 this `StandardMaterial3D` config** when the effect is just a tinted soft-circle mote (magic glow, sparkles, dust). Less code, faster iteration, free engine-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 present on the shipped engine) — 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`.
 

package/library/skills/vfx-muzzle-flash/_building-blocks/trauma-shake-snippet.md

@@ -1,6 +1,6 @@
 # Trauma Camera Shake — Reusable Snippet
 
-Variant of the canonical "trauma model" shake (see `visual-effects/game-feel/SKILL.md` for the full game-feel discipline). Lightning and explosion recipes call `add_trauma()` to chain visual impact with screen-level reaction.
+Variant of the canonical "trauma model" shake (the `game-feel` skill has the full game-feel discipline). Lightning and explosion recipes call `add_trauma()` to chain visual impact with screen-level reaction.
 
 ## Setup (autoload script)
 
@@ -15,18 +15,24 @@ var max_offset: Vector3 = Vector3(0.4, 0.4, 0.0)
 var max_yaw: float = 0.05
 var max_pitch: float = 0.05
 var camera: Camera3D
+var _rot_offset := Vector2.ZERO  # shake rotation applied last frame
 
 func _process(delta: float) -> void:
     if camera == null:
         camera = get_viewport().get_camera_3d()
         if camera == null:
             return
+    # Undo last frame's shake first, so the camera never drifts.
+    camera.rotation.x -= _rot_offset.x
+    camera.rotation.y -= _rot_offset.y
+    _rot_offset = Vector2.ZERO
     if trauma > 0.0:
         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
-        camera.rotation.y += max_yaw * s * (randf() * 2.0 - 1.0) * 0.1
+        _rot_offset = Vector2(max_pitch * s * (randf() * 2.0 - 1.0), max_yaw * s * (randf() * 2.0 - 1.0))
+        camera.rotation.x += _rot_offset.x
+        camera.rotation.y += _rot_offset.y
         trauma = max(0.0, trauma - trauma_decay * delta)
     else:
         camera.h_offset = 0.0

package/library/skills/vfx-smoke/SKILL.md

@@ -11,7 +11,7 @@ paths: ["**/*.tscn", "**/*.gd", "**/*.gdshader", "addons/vfx/**"]
 
 # smoke — Soft Particle Smoke Plume
 
-Smoke is the same particle pattern as fire — billboard quads emitted from a small disc, drifting upward — except the shader is dim, soft, low-emission, and tinted by depth instead of glowing. Slower spawn rate, longer lifetime, larger end scale. Pair it with `fire` for any campfire/torch/explosion. Used everywhere: chimney smoke, smoldering wreckage, smoke trails behind rockets, steam from vents, fog clouds.
+Smoke is the same particle pattern as fire — billboard quads emitted from a small disc, drifting upward — except the shader is dim, soft, low-emission, and tinted by depth instead of glowing. Slower spawn rate, longer lifetime, larger end scale. Pair it with `vfx-fire` for any campfire/torch/explosion. Used everywhere: chimney smoke, smoldering wreckage, smoke trails behind rockets, steam from vents, fog clouds.
 
 ## When to use
 
@@ -21,12 +21,12 @@ Smoke is the same particle pattern as fire — billboard quads emitted from a sm
 - "Steam from the vent."
 - "Smoke from the smoldering wreckage."
 - "Fog cloud at the cave entrance."
-- After spawning `fire`, smoke almost always belongs above it.
+- After spawning `vfx-fire`, smoke almost always belongs above it.
 
 ## When NOT to use
 
-- The user wants flames, not smoke — use `fire`.
-- The user wants a giant ground-hugging fog volume — use a `FogVolume` node with the `WorldEnvironment.volumetric_fog` shader, not a particle system. Particles don't scale to room-size fog.
+- The user wants flames, not smoke — use `vfx-fire`.
+- The user wants a giant ground-hugging fog volume — use a `FogVolume` node with volumetric fog enabled in the `WorldEnvironment`, not a particle system. Particles don't scale to room-size fog.
 - The user wants a 2D smoke effect — `canvas_item` shader, not this.
 - The user wants the smoke to physically interact with the player (pushed by movement) — particles are visual; use a `FogVolume` + script that follows the player.
 - The user wants thick black bonfire smoke that completely occludes — bump density way up, but consider a `FogVolume` for genuine visual occlusion.
@@ -334,7 +334,7 @@ color_old      = Color(0.55, 0.55, 0.55)
 
 ### black-fire-smoke
 
-Burning oil / tires. Pair with `fire` set to `bonfire`.
+Burning oil / tires. Pair with `vfx-fire` set to `bonfire`.
 
 ```
 particle_count = 96

package/library/skills/vfx-water-ripple/SKILL.md

@@ -24,9 +24,9 @@ Concentric expanding rings on a water surface, normal-distorted so the ripple ac
 
 ## When NOT to use
 
-- The user wants the *whole* water surface to wave (Gerstner / FFT ocean) — that's a separate `ocean-water` recipe; this is impact ripples on top.
+- The user wants the *whole* water surface to wave (Gerstner / FFT ocean) — that needs an ocean wave shader; this recipe adds impact ripples on top.
 - The user wants a 2D top-down ripple effect on a UI map — use `canvas_item` shader, not this `spatial` one.
-- The user wants splash particles flying upward on impact — pair this with `hit-spark` (recolor blue) for the droplets; this only handles the ring on the surface.
+- The user wants splash particles flying upward on impact — pair this with `vfx-hit-spark` (recolor blue) for the droplets; this only handles the ring on the surface.
 - The user wants the ripple to physically displace floating objects — this is visual only. Use `Area3D` impulses for the simulation side.
 
 ## Recipe

package/library/skills/vfx-water-ripple/_building-blocks/additive-billboard-particles.md

@@ -1,6 +1,6 @@
 # Additive Billboard Particles — Canonical Material Settings
 
-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.
+Reusable material configuration for additive particle billboards (motes, sparks, glow, ash). Used by `vfx-magic-glow`, optionally substitutable in `vfx-hit-spark` and `vfx-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
@@ -27,8 +27,8 @@ bm.emission = Color(R, G, B)          # usually same as albedo for single-color
 
 ## When to use this vs a custom shader
 
-- **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 this `StandardMaterial3D` config** when the effect is just a tinted soft-circle mote (magic glow, sparkles, dust). Less code, faster iteration, free engine-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 present on the shipped engine) — 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`.
 

package/library/skills/voice-line/SKILL.md

@@ -24,7 +24,7 @@ Then it generates one line (or a multi-turn dialogue) with the right stability /
 
 ## When NOT to use
 
-- Non-verbal vocal SFX (grunt, scream) → `audio/sound-effect` with prompt `male grunt of pain, mid-thirties, sharp, 400ms`.
+- Non-verbal vocal SFX (grunt, scream) → `sound-effect` with prompt `male grunt of pain, mid-thirties, sharp, 400ms`.
 - Pre-recorded voice from a real actor — import the .mp3 / .wav with `summer_import_from_url` and skip TTS.
 
 ## Steps
@@ -146,7 +146,7 @@ For a single line, the prompt is just the text. Punctuation and formatting matte
 
 - **Periods** = clear pauses (~300ms). Use them.
 - **Commas** = short pauses (~100ms).
-- **Em dashes** = sharp cut. (Note: avoid em dashes in user-facing UI copy per project standard, but they're fine in voice prompts as a delivery cue.)
+- **Em dashes** = sharp cut.
 - **All-caps word** = stress: `You SHALL not pass.`
 - **Ellipsis** = trailing pause: `I... I don't know what to say.`
 - **Parenthetical stage direction is ignored** — `(angrily)` is read as the word "angrily". Use stability/style instead.
@@ -230,7 +230,7 @@ Excited young hero:       18-28, high energy, mid-high pitch
 Cold villain:             30-50, neutral/theatrical, low-mid, slow with sharp consonants
 Mischievous trickster:    theatrical, light, fast cadence
 Calm scholar:             30-50, neutral, mid, even cadence
-Scared / breathy:         high stability=0.25, style=0.5
+Scared / breathy:         stability=0.25, style=0.5
 Robotic AI:               stability=1.0, style=0.0
 Narrator cinematic:       mid-deep, neutral/theatrical, even, very stable
 Narrator intimate:        warmer mid pitch, lower stability for breath
@@ -250,9 +250,9 @@ Narrator intimate:        warmer mid pitch, lower stability for breath
 
 ## Edge cases
 
-- **Line longer than ~1000 characters.** ElevenLabs caps per-call. Split at sentence boundaries, generate each, concatenate with `AudioStreamPlayer.queue` or chained `finished` signals.
+- **Line longer than ~1000 characters.** ElevenLabs caps per-call. Split at sentence boundaries, generate each, and play them in order by chaining the player's `finished` signal.
 - **Mispronunciation of a fictional word.** Spell it phonetically: `Caelthorne` → `KEL-thorn` or `KAYL-thorn`. Or use SSML if the model supports it.
-- **Voice drifts in long lines.** Increase `similarity_boost` toward 0.9; or split.
+- **Voice drifts in long lines.** Increase `similarityBoost` toward 0.9; or split.
 - **Need a non-English line.** `eleven_multilingual_v2` supports 29 languages. Just write in the target language; the same voice id works.
 - **User wants the line shorter on regen.** Edit the text first; don't try to compress with `speed` past 1.15 (artifacts).
 - **NPC bark variants.** Generate 3–5 variants of the same intent (`"They're at the gate!"`, `"Enemy approaching!"`, `"Look out!"`) and pick at random in code so the bark doesn't repeat.
@@ -266,10 +266,10 @@ Print the call (text, voice id, params, target path). User runs via the Summer d
 > Line `hodge_hold_the_line.mp3` wired to `NPC/VoiceLine` on the `Voice` bus. Cast bible updated. Next:
 > - Generate 3 bark variants of the same intent so the NPC doesn't sound like a recording.
 > - For the upcoming gate scene, run `/voice-line` with `text_to_dialogue` for the multi-turn exchange.
-> - Set up music ducking on the `Music` bus when `Voice` is active (one Tween or a `BusEffect Compressor` sidechained to `Voice`).
+> - Set up music ducking on the `Music` bus when `Voice` is active (one Tween, or an `AudioEffectCompressor` on `Music` with `sidechain` set to `Voice`).
 
 ## See also
 
-- `audio/audio-direction` — Voice bus and ducking rules
-- `audio/sound-effect` — non-verbal vocal SFX (grunt, scream)
-- `audio/adaptive-music` — ducking integration
+- `audio-direction` — Voice bus and ducking rules
+- `sound-effect` — non-verbal vocal SFX (grunt, scream)
+- `adaptive-music` — ducking integration

package/library/skills/web-compatibility-look/resource.yaml

@@ -24,6 +24,7 @@ related:
     - skill/art-direction
     - skill/tune-performance
     - skill/ui-basics
+    - skill/compatibility-renderer-traps
 source: official
 license: MIT
 status: preview

package/library/skills/world-building-3d/references/spatial-tools.md

@@ -17,7 +17,7 @@ Input is a candidate global position and global Euler rotation. The subject's cu
 
 Interpretation:
 
-- Physics overlap counts are lower bounds because Godot exposes no broadphase-completeness bit.
+- Physics overlap counts are lower bounds because the physics server exposes no broadphase-completeness bit.
 - Any known obstruction makes `fits: false`.
 - Zero known physics overlaps can still yield `fits: null`; never coerce it to success.
 - `grounded`, signed `floorGap`, and support evidence are independent of overlap certainty. Claim physics-grounded only when `floorEvidence` is `physics` and `supportQueryComplete` is true; otherwise label the evidence approximate or incomplete.
@@ -42,7 +42,7 @@ This is one-dimensional arrangement evidence. It does not prove clearance on the
 
 ## `summer_navigation_probe`
 
-Iteration 0 is unready; iteration 1 and later can be queried. Layer-filtered snapped endpoints and the reported snap distances define what Godot actually tested. `ready: false` means unknown, not unreachable.
+Iteration 0 is unready; iteration 1 and later can be queried. Layer-filtered snapped endpoints and the reported snap distances define what the engine actually tested. `ready: false` means unknown, not unreachable.
 
 Require both a reachable path and a small endpoint snap distance appropriate to the authored target.
 Probe every independent destination; one reachable subject does not validate the

package/library/skills/writing-plans/SKILL.md

@@ -66,9 +66,9 @@ This structure informs the task decomposition. Each task should produce self-con
 ### Task N: [Component Name]
 
 **Files:**
-- Create: `exact/path/to/file.py`
-- Modify: `exact/path/to/existing.py:123-145`
-- Test: `tests/exact/path/to/test.py`
+- Create: `exact/path/to/file.gd`
+- Modify: `exact/path/to/existing.gd:123-145`
+- Test: `tests/exact/path/to/test_file.gd`
 
 - [ ] **Step 1: Write the failing test**
 
@@ -103,7 +103,7 @@ Expected: PASS
 - [ ] **Step 5: Commit**
 
 ```bash
-git add tests/path/test.py src/path/file.py
+git add tests/unit/test_health.gd scripts/health.gd
 git commit -m "feat: add specific feature"
 ```
 ````

package/library/skills/writing-skills/SKILL.md

@@ -104,7 +104,7 @@ skills/
 
 ```markdown
 ---
-name: Skill-Name-With-Hyphens
+name: skill-name-with-hyphens
 description: Use when [specific triggering conditions and symptoms]
 ---
 
@@ -260,7 +260,7 @@ You: Searching...
 
 **Verification:**
 ```bash
-wc -w skills/path/SKILL.md
+wc -w library/skills/<slug>/SKILL.md
 # getting-started workflows: aim for <150 each
 # Other frequently-loaded: aim for <200 total
 ```
@@ -287,7 +287,7 @@ Use skill name only, with explicit requirement markers:
 
 **Check the skill exists before you point at it.** The registry of shipped skills is `registry/generated/skills-registry.json` (generated from `library/skills/`); `summer skills list` prints it. A `REQUIRED SUB-SKILL` pointing at a skill that was never shipped is worse than no cross-reference: the reader stops and looks for something that does not exist.
 
-**Why no @ links:** `@` syntax force-loads files immediately, consuming 200k+ context before you need them.
+**Why no @ links:** `@` syntax force-loads files immediately and spends context before you need them.
 
 ## Flowchart Usage
 
@@ -549,7 +549,7 @@ Run same scenarios WITH skill. Agent should now comply.
 
 Agent found new rationalization? Add explicit counter. Re-test until bulletproof.
 
-**Testing methodology:** See @testing-skills-with-subagents.md for the complete testing methodology:
+**Testing methodology:** See `testing-skills-with-subagents.md` in this directory for the complete testing methodology:
 - How to write pressure scenarios
 - Pressure types (time, sunk cost, authority, exhaustion)
 - Plugging holes systematically
@@ -633,10 +633,10 @@ Deploying untested skills = deploying untested code. It's a violation of quality
 How future Claude finds your skill:
 
 1. **Encounters problem** ("tests are flaky")
-3. **Finds SKILL** (description matches)
-4. **Scans overview** (is this relevant?)
-5. **Reads patterns** (quick reference table)
-6. **Loads example** (only when implementing)
+2. **Finds SKILL** (description matches)
+3. **Scans overview** (is this relevant?)
+4. **Reads patterns** (quick reference table)
+5. **Loads example** (only when implementing)
 
 **Optimize for this flow** - put searchable terms early and often.
 

package/library/tools/capture-gameplay/resource.yaml

@@ -0,0 +1,73 @@
+id: tool/capture-gameplay
+kind: tool
+version: 1.0.0
+summary: Capture real gameplay frames (PNG, HUD included) in Summer Engine's offscreen verify instance, without a running editor, e.g. store screenshots.
+use_when:
+  - '"take gameplay screenshots for my store page"'
+  - '"I need screenshots but the editor is not open"'
+  - '"capture a 1920x1080 frame of my game"'
+  - collecting real gameplay screenshots for summer_store_set_art desktop.screenshots or mobile.screenshots
+do_not_use_when:
+  - the editor is open and the game is running — tool/screenshot with target game shows the live game
+  - key art, covers or icons — those are generated art, not gameplay frames
+  - checking an interaction with inputs and assertions — RunVerification through tool/batch
+facets:
+  lifecycle:
+    - launch
+    - build
+  domains:
+    - creator
+    - headless
+compatibility:
+  engine: ">=4.6"
+source: official
+license: MIT
+status: preview
+aliases:
+  - summer_capture_gameplay
+implementation:
+  module: src/core/capabilities/capture-gameplay.ts
+  export: captureGameplay
+surfaces:
+  mcp:
+    tool_name: summer_capture_gameplay
+    remote: true
+input_schema:
+  type: object
+  properties:
+    project:
+      type: string
+      description: Project folder with project.godot. Defaults to the MCP's bound project, then the working directory.
+    scene:
+      type: string
+      description: Scene to start (res://... or uid://...). Default is the project's main scene, often a title menu; pass the gameplay scene for gameplay frames.
+    resolution:
+      type: string
+      description: Window size WIDTHxHEIGHT (default 1920x1080; 1080x1920 for portrait).
+    frames:
+      type: integer
+      minimum: 1
+      maximum: 10
+      description: Frames to save (default 1).
+    waitSeconds:
+      type: number
+      minimum: 0
+      maximum: 120
+      description: Seconds the game runs before the first frame (default 3).
+    intervalSeconds:
+      type: number
+      minimum: 0.1
+      maximum: 60
+      description: Seconds between frames (default 1).
+    out:
+      type: string
+      description: Output folder. Defaults to <project>/.summer/captures/<time>/ (ignored by git).
+  additionalProperties: false
+authority:
+  filesystem: true
+  editor_mutation: false
+  network: false
+  credentials: false
+  publish: false
+evidence_checks:
+  - none

package/library/tools/creator-publish/resource.yaml

@@ -1,12 +1,12 @@
 id: tool/creator-publish
 kind: tool
 version: 1.1.0
-summary: "Deprecated: publishes a .pck to the legacy Summercraft API. Use summer_export_game, then summer_publish_build, to upload to summer.games."
+summary: "Deprecated: publishes a .pck to the legacy creator API. Use summer_export_game, then summer_publish_build, to upload to summer.games."
 use_when:
-  - releasing a user-approved build to a Summercraft channel
-  - '"ship this exported build to the live channel"'
-  - '"release version 1.2.0 of my game"'
+  - an old project that still publishes a .pck to the legacy Summercraft creator channel with an sc_ creator token
+  - a ~/.summer/config.json that names a legacy creator projectId and channel
 do_not_use_when:
+  - releasing a version on summer.games — summer_publish_build, then summer_store_submit (the owner approves)
   - uploading to summer.games — summer_export_game, then summer_publish_build
   - the user has not approved the exact version, digest, and channel
   - the game is not exported yet — export the .pck first (skill/export-and-ship)