summer-engine 1.3.1 → 1.4.0

package/skills/visual-effects/vfx/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: vfx
+description: Use when the user says the game "feels flat", "needs juice", "lacks impact", or asks for particles, hit feedback, screen shake, camera juice, muzzle flashes, explosions, or pickup effects. Walks the user through a guided 30-minute polish pass that adds visible feedback to combat, movement, pickups, damage, and casting. Trigger on "vfx", "juice", "feels flat", "polish", "particles", "screen shake", "hit flash", "feedback".
+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
+paths: ["**/*.gd", "**/*.tscn", "**/*.tres"]
+---
+
+# /vfx — Visible Polish in 30 Minutes
+
+A game with bad VFX feels like a tech demo. A game with good VFX feels alive even before the mechanics are deep. This skill is a guided polish pass: you ask the user *what feels flat*, then deliver one or two tight recipes that add immediately-visible feedback. No vague "add particles". Specific node, specific values, specific signal hookup, verified result.
+
+## Steps
+
+### 1. Ask which thing feels flat
+
+Open with one focused question. Wait for the answer.
+
+> What feels flat? Pick one to start: combat hits / movement / pickups / damage taken / explosions / spell casts / something else.
+
+If the user says "all of it", anchor on **combat hits** — it gives the loudest perceived improvement per minute spent.
+
+### 2. Read the current scene state
+
+Before adding anything, see what's there.
+
+**Preferred (Summer MCP):**
+
+```
+summer_get_scene_tree
+summer_inspect_node "./World/Player"   # or whichever node owns the action
+```
+
+You're looking for: where the trigger lives (e.g. `body_entered` signal on a Hurtbox), whether a Camera3D exists for shake, whether the target has a MeshInstance3D for a flash material override.
+
+**Fallback (no MCP):** ask the user to paste the relevant `.tscn` snippet or describe the parent of the actor.
+
+### 3. Pick the recipe and propose it explicitly
+
+Each recipe is a tight bundle of (node + property + signal + script). Don't mix recipes — add one, see it land, stack later.
+
+> I want to add a hit flash + 0.04s camera shake bound to the `damaged` signal on `./World/Enemy`. About 6 lines of GDScript and one Camera3D shake node. May I proceed?
+
+### 4. Apply the recipe
+
+See **Recipes** below. Each is end-to-end: node tree, property values, signal hookup, GDScript stub.
+
+### 5. Verify
+
+```
+summer_save_scene
+summer_get_script_errors
+summer_play
+# user reproduces the trigger
+summer_stop
+```
+
+If it doesn't read on screen, the values are wrong (flash too dim, shake too short, particle lifetime too long). Tune one knob at a time.
+
+## Recipes
+
+### Recipe A — Hit flash (mesh albedo flicker)
+
+**Goal:** when an enemy takes damage, the mesh flashes white for 80 ms. Single biggest-bang-for-buck VFX. Read instantly even at 60 fps.
+
+**Approach:** swap to a flash material via `material_override`, then back. Use Tween for the timing.
+
+**MCP path:**
+
+```
+summer_add_node(parent="./World/Enemy", type="Node", name="HitFlash")
+# attach script (see below) — script holds reference to MeshInstance3D and a flash StandardMaterial3D
+```
+
+Script (`scripts/hit_flash.gd`):
+
+```gdscript
+class_name HitFlash
+extends Node
+
+@export var mesh: MeshInstance3D
+@export var flash_color: Color = Color(1.0, 1.0, 1.0)
+@export var duration: float = 0.08
+
+var _flash_mat: StandardMaterial3D
+var _orig_mat: Material
+
+func _ready() -> void:
+    if mesh == null:
+        push_warning("HitFlash: mesh export not assigned")
+        return
+    _orig_mat = mesh.get_surface_override_material(0)
+    _flash_mat = StandardMaterial3D.new()
+    _flash_mat.albedo_color = flash_color
+    _flash_mat.emission_enabled = true
+    _flash_mat.emission = flash_color
+    _flash_mat.emission_energy_multiplier = 2.0
+
+func flash() -> void:
+    if mesh == null:
+        return
+    mesh.set_surface_override_material(0, _flash_mat)
+    var tween := create_tween()
+    tween.tween_interval(duration)
+    tween.tween_callback(func(): mesh.set_surface_override_material(0, _orig_mat))
+```
+
+Wire the trigger:
+
+```
+summer_connect_signal(from="./World/Enemy", signal="damaged", to="./World/Enemy/HitFlash", method="flash")
+```
+
+**Tunable knobs:** `duration` (0.06–0.12 sec — under 0.06 reads as a flicker, over 0.12 looks slow), `emission_energy_multiplier` (1.5–3.0).
+
+> CRITICAL: do NOT inline the StandardMaterial3D as a sub_resource via `summer_set_prop`. Build it in script (as above) or save it to `materials/flash.tres` and load. Inline sub_resources break `summer_set_resource_property` silently — see `_shared/mcp-tools-reference.md` § "Trap".
+
+### Recipe B — Screen shake (Camera3D wobble)
+
+**Goal:** punchy 40–80 ms camera shake on impact. Ties hits to the player's body.
+
+**Approach:** attach a shake script to the existing Camera3D. Don't spawn a new camera; reuse the player's.
+
+```
+summer_inspect_node "./World/Player/Camera3D"   # confirm the path
+```
+
+Script (`scripts/camera_shake.gd`):
+
+```gdscript
+class_name CameraShake
+extends Camera3D
+
+@export var trauma_decay: float = 5.0
+@export var max_offset: Vector2 = Vector2(0.15, 0.15)
+@export var max_roll: float = 0.05
+
+var _trauma: float = 0.0
+var _base_position: Vector3
+
+func _ready() -> void:
+    _base_position = position
+
+func add_trauma(amount: float) -> void:
+    _trauma = clamp(_trauma + amount, 0.0, 1.0)
+
+func _process(delta: float) -> void:
+    if _trauma <= 0.0:
+        position = _base_position
+        rotation.z = 0.0
+        return
+    var shake := _trauma * _trauma  # quadratic — feels punchy, not noisy
+    position = _base_position + Vector3(
+        randf_range(-max_offset.x, max_offset.x) * shake,
+        randf_range(-max_offset.y, max_offset.y) * shake,
+        0.0
+    )
+    rotation.z = randf_range(-max_roll, max_roll) * shake
+    _trauma = max(_trauma - trauma_decay * delta, 0.0)
+```
+
+Trigger from the player or any damage handler:
+
+```gdscript
+$Camera3D.add_trauma(0.5)   # 0.3 light hit, 0.5 normal, 0.8 heavy
+```
+
+**Tunable knobs:** `max_offset` (0.05 subtle, 0.2 punchy, 0.4 cinematic), `trauma_decay` (3 long, 5 standard, 8 snappy). Quadratic falloff is the trick — linear feels twitchy.
+
+### Recipe C — Pickup sparkle (GPUParticles3D one-shot)
+
+**Goal:** when a pickup is collected, emit a quick burst of particles where it disappeared.
+
+**Approach:** GPUParticles3D set to `one_shot = true`, `emitting = true` triggered from script. Particle material **must** be a standalone `.tres` (inline sub_resource trap).
+
+```
+summer_add_node(parent="./World/Pickup", type="GPUParticles3D", name="Sparkle")
+summer_set_prop(path="./World/Pickup/Sparkle", key="one_shot", value="true")
+summer_set_prop(path="./World/Pickup/Sparkle", key="amount", value="24")
+summer_set_prop(path="./World/Pickup/Sparkle", key="lifetime", value="0.5")
+summer_set_prop(path="./World/Pickup/Sparkle", key="explosiveness", value="0.95")
+```
+
+For the `process_material`, save a `ParticleProcessMaterial.tres` first (see `asset-pipeline/asset-strategy/SKILL.md` for the pattern), then:
+
+```
+summer_set_prop(path="./World/Pickup/Sparkle", key="process_material", value="res://materials/sparkle_particles.tres")
+```
+
+In the pickup's collection handler:
+
+```gdscript
+func _on_picked_up() -> void:
+    $Sparkle.restart()
+    $Sparkle.emitting = true
+    $Mesh.visible = false
+    await get_tree().create_timer(0.6).timeout
+    queue_free()
+```
+
+`explosiveness = 0.95` is the difference between a continuous trickle and a satisfying *poof*. `0.0` = constant emission, `1.0` = all particles spawn at frame zero.
+
+### Recipe D — Muzzle flash (light + sprite + sound)
+
+**Goal:** when a weapon fires, a brief OmniLight3D flash + Sprite3D billboard + audio cue. Sells the shot more than the projectile does.
+
+```
+summer_add_node(parent="./World/Player/Weapon", type="OmniLight3D", name="MuzzleLight")
+summer_set_prop(path="./World/Player/Weapon/MuzzleLight", key="light_color", value="Color(1.0, 0.85, 0.4)")
+summer_set_prop(path="./World/Player/Weapon/MuzzleLight", key="light_energy", value="0.0")
+summer_set_prop(path="./World/Player/Weapon/MuzzleLight", key="omni_range", value="2.5")
+```
+
+Trigger from the fire function:
+
+```gdscript
+func fire() -> void:
+    var light: OmniLight3D = $MuzzleLight
+    light.light_energy = 4.0
+    var tween := create_tween()
+    tween.tween_property(light, "light_energy", 0.0, 0.06)
+    $MuzzleSound.play()
+    $Camera3D.add_trauma(0.3)   # if camera shake recipe applied
+```
+
+Do NOT keep the light always-on at low energy — that costs a real-time light slot. Tween from 4.0 to 0.0 over 60 ms.
+
+### Recipe E — Explosion (5-element stack)
+
+**Goal:** one Big Boom, all senses. Stack five small effects on the same trigger.
+
+1. **Light flash:** OmniLight3D, `light_energy` 0 → 8 → 0 over 200 ms
+2. **Particles:** GPUParticles3D one-shot, `amount` 64, `lifetime` 0.8, `explosiveness` 1.0
+3. **Camera shake:** `add_trauma(0.8)`
+4. **Audio:** AudioStreamPlayer3D, layered explosion
+5. **Hit-stop:** `Engine.time_scale = 0.05` for 60 ms, then 1.0
+
+Hit-stop is the secret weapon. 60 ms of 0.05 time scale = the explosion lands. Use sparingly; once per "big" event. Reset with:
+
+```gdscript
+Engine.time_scale = 0.05
+await get_tree().create_timer(0.06).timeout
+Engine.time_scale = 1.0
+```
+
+## Anti-patterns
+
+| Don't | Do | Why |
+|---|---|---|
+| Inline sub_resource for ParticleProcessMaterial via `summer_set_prop` | Save standalone `.tres`, reference by path | `summer_set_resource_property` silently fails on inline sub_resources |
+| Hit flash for 0.3 sec | Hit flash for 0.06–0.12 sec | Anything over ~120 ms reads as a "stay" not a flash |
+| Camera shake with linear falloff | Quadratic falloff (`_trauma * _trauma`) | Linear feels jittery; quadratic feels weighty |
+| `OmniLight3D` always on at low energy | Tween from off → on → off in 60–80 ms | Real-time lights have hard count limits per frame |
+| GPUParticles3D `one_shot = false` for pickups | `one_shot = true`, `restart()` to fire | Otherwise particles trickle continuously and look wrong |
+| Tween every property at once | Tween one or two; let the others snap | Over-animated polish reads as noise |
+| `Engine.time_scale` < 0.1 for > 100 ms | `time_scale = 0.05` for 40–80 ms | Longer hit-stop feels broken, not satisfying |
+| Particles with `lifetime > 1.0` for hits | `lifetime = 0.3–0.6` | Hit feedback should resolve before the next swing |
+
+## Collaborative protocol
+
+This skill writes scripts and adds nodes. Always ask before each recipe is applied. Group related writes into one ask: "I'm about to add HitFlash + CameraShake + connect 2 signals. OK?" See `_shared/collaborative-protocol.md`.
+
+## Want a working starter?
+
+No template — this is a workflow that bolts onto any existing scene. For a project that already has these recipes pre-wired, see `template-3d-fps` (hit flash + muzzle flash) and `template-3d-platformer` (pickup sparkle).
+
+## See also
+
+- `_shared/mcp-tools-reference.md` — full MCP tool list, especially the inline-sub_resource trap
+- `_shared/godot-version.md` — Godot 4.5 API notes
+- `_shared/collaborative-protocol.md` — "May I write" pattern
+- `_shared/gd-style.md` — typed GDScript conventions
+- `post-processing/screen-shake/SKILL.md` — deeper camera-shake techniques (Perlin noise, trauma stacks)
+- `visual-effects/gpuparticles-3d-basics/SKILL.md` — particle setup details
+- `visual-effects/hit-impact-flashes/SKILL.md` — flash material variations
+- `visual-effects/muzzle-flashes/SKILL.md` — muzzle flash deep dive
+- `audio/sfx-pipeline/SKILL.md` — pairing audio with VFX