summer-engine 1.3.1 → 1.3.2

package/skills/scene-and-project/brainstorm-game/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: brainstorm-game
+description: Use when the user wants help deciding what game to make, scoping a new project, or turning a vague idea into a buildable plan. Walks through genre, scope, core loop, mechanics, and art direction, then writes a 1-page brief to `.summer/GameSoul.md`. Trigger on "brainstorm a game", "what should I make", "I want to make a game", "help me scope", "new game idea".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: scene-and-project
+user-invocable: true
+allowed-tools: Read Grep Glob Write Edit summer_get_project_context summer_get_scene_tree
+paths: [".summer/**", "project.godot", "**/*.md"]
+---
+
+# /brainstorm-game — Decide What Game to Build
+
+## Overview
+
+Most game projects fail because they were never scoped. This skill turns "I want to make a game" into a 1-page brief that names the pitch, the core loop, three mechanics max, the art direction, and the scope (jam / vertical slice / full game). The brief lands at `.summer/GameSoul.md` — the file Summer's onboarding pipeline and every future `summer:` skill reads on first turn.
+
+**Core principle:** Constrain ruthlessly. A buildable bad idea beats an un-buildable great idea. Three mechanics, one art direction, one scope. Anything else gets parked in a "Later" list.
+
+## Steps
+
+### 1. Open with the one question
+
+Ask exactly this and wait:
+
+> One sentence — what kind of game do you want to make?
+
+Don't pre-pitch genres. Don't list options. Read what they say. The first sentence is signal.
+
+If they freeze ("I don't know"), offer 4 reference points only:
+
+> No worries. Pick the one that pulls you most: a) something cozy and exploratory (Stardew, A Short Hike), b) something tight and skill-based (Celeste, Hades), c) something story-led (Disco Elysium, Citizen Sleeper), d) something silly and short (Goat Sim, Untitled Goose). Or describe a different vibe.
+
+### 2. Branch on genre signal
+
+Read their answer for a genre anchor and pick **one** branch. Don't ask multiple questions in parallel.
+
+| Anchor word(s) | Branch |
+|---|---|
+| "shooter", "FPS", "TPS", "combat" | Action-Combat branch |
+| "platformer", "metroidvania", "souls-like" | Skill-Platforming branch |
+| "RPG", "story", "narrative", "dialogue" | Narrative branch |
+| "roguelike", "deckbuilder", "auto-battler" | Run-Based branch |
+| "sim", "cozy", "farming", "city-builder" | Sim branch |
+| "puzzle", "physics", "sandbox" | Puzzle branch |
+| "horror", "atmospheric" | Horror branch |
+| "multiplayer", "PvP", "co-op" | Multiplayer branch (forces the multiplayer-or-not call before scope) |
+
+If unclear, ask the smallest disambiguating question:
+
+> Tighter on this — is it more "tense and dangerous" or "calm and exploratory"?
+
+### 3. Pin the core loop
+
+A core loop is what the player does for 30 seconds, repeated. State a candidate and ask them to refine. Examples per branch:
+
+| Branch | Candidate core loop |
+|---|---|
+| Action-Combat | "Enter room, read enemy patterns, kill, loot, advance." |
+| Skill-Platforming | "See obstacle, attempt, fail, learn, retry, clear, next." |
+| Narrative | "Walk to character, choose dialogue, see consequence, walk to next." |
+| Run-Based | "Pick a card/weapon/build, fight, die, unlock, repeat with edge." |
+| Sim | "Plan day, execute, harvest reward, plan next day." |
+| Puzzle | "See state, form theory, test, observe, solve or rethink." |
+| Horror | "Hear cue, locate threat, hide or flee, advance space." |
+
+State your candidate. Ask:
+
+> The 30-second loop I'm hearing: <candidate>. Does that match what you have in your head, or is the actual moment-to-moment different?
+
+### 4. Constrain to three mechanics maximum
+
+Force the trade. State the rule:
+
+> Three mechanics, no more. What are the three things this game has that other games in this genre don't?
+
+If they pitch five, push back. Not "we'll add it later" — actually cut. Two examples for them to react to:
+
+> Hades has three: dash-attack-cast, room reward choice, and run-end conversation. Everything else (mirror upgrades, weapon variants, bosses) is content built on those three. What are yours?
+
+Common new-dev mistake: listing features ("inventory, crafting, quests") instead of mechanics ("a single resource that's both currency and ammo"). Push them toward verbs and decisions, not nouns and systems.
+
+### 5. Pick an art direction in one phrase
+
+Not a paragraph. Examples to anchor:
+
+- "Lo-fi PS1 polygons + dithered shader"
+- "Hand-drawn 2D, single bold outline, 4-color palette"
+- "Toon-shaded Nintendo-bright, no realistic lighting"
+- "Pixel art, 16x16 tiles, GameBoy 4-shade green"
+
+Ask:
+
+> One phrase for the look. If a stranger asked your screenshot's style in 6 words, what do you say?
+
+Don't go deeper here — `/summer:art-direction` is where the bible gets built. This is one phrase to seed it.
+
+### 6. Pin the scope
+
+State the choices flat:
+
+> Scope. Pick one: (a) a 4-hour jam-sized prototype — one mechanic, one level, one art direction, ships in a weekend. (b) a vertical slice — 30-60 minutes of polished play that proves the core loop, ships in 2-4 weeks. (c) a full game — 4-20 hours of content, ships in 6+ months.
+
+If they flinch at (c), recommend (b). New devs almost always overestimate scope. Default recommendation if they're unsure: **vertical slice**.
+
+### 7. Sanity-check the combination
+
+Do this in your head, not out loud unless something fails:
+
+- Is the core loop achievable with the three mechanics + the chosen art direction in the chosen scope? If not, name what has to flex (usually scope down or merge two mechanics into one).
+- Is there a hidden multiplayer requirement? ("4-player" or "co-op" anywhere = stop, multiplayer is its own scope explosion.)
+- Is the art direction generatable / sourceable for a solo dev? (Photoreal 3D for a 4-week vertical slice is a red flag.)
+
+If you spot a problem, raise it once, plainly:
+
+> One concern: <X>. Suggest <flex Y>. OK or do you want to push through anyway?
+
+### 8. Draft the brief
+
+Compose the 1-page brief. Format:
+
+```markdown
+# <Game Name or "Untitled">
+
+**Pitch:** <One sentence the player would tell a friend.>
+
+**Core loop (30s):** <What the player does, repeated.>
+
+**Three mechanics:**
+1. <Verb-led: "Parry to convert damage into mana"  not "Combat system">
+2. <…>
+3. <…>
+
+**Art direction (one phrase):** <…>
+
+**Scope:** <Jam | Vertical slice | Full game>
+
+**Win condition:** <How the player knows they succeeded — ending? Score? Unlock?>
+
+**One thing this is NOT:** <Define by negation. Cuts scope creep later.>
+
+**Inspirations:** <2-4 specific games, films, or images.>
+
+**Parked for later:** <Things they pitched that didn't make the three.>
+```
+
+### 9. Ask permission and write
+
+**Preferred (Summer MCP + host file write):**
+
+> May I create `.summer/GameSoul.md` with this brief?
+
+On yes, use `Write` (host file tool) — `.summer/GameSoul.md` is plain markdown, no engine import needed:
+
+```
+Write .summer/GameSoul.md
+```
+
+If `.summer/GameSoul.md` already exists, read it first, show what would change, ask:
+
+> `.summer/GameSoul.md` already exists. May I overwrite it, or merge into a "Revision 2" section below the existing brief?
+
+**Fallback (no host write tool — agent is read-only):**
+
+Print the full brief to the user with the explicit instruction:
+
+> Save this as `.summer/GameSoul.md` in your project root. Every Summer skill reads it.
+
+### 10. Route to the next step
+
+End every successful brainstorm with a routing question:
+
+> Brief saved. Next step:
+> - `/summer:design-mechanic` — design the core loop in detail (recommended for vertical slice).
+> - `/summer:design-level` — sketch level 1 / the tutorial.
+> - `/summer:art-direction` — turn the one-phrase look into an art bible.
+> - Or pick up `/summer:make-game` to start scaffolding the project.
+
+Don't auto-pick. Let them decide.
+
+## Anti-patterns (don't do these)
+
+| Anti-pattern | Why it fails |
+|---|---|
+| Asking 6 questions in a row before any branching | User feels interviewed, not collaborated with. Branch after each answer. |
+| Letting them list 5+ mechanics | Three is the constraint. Without the constraint, the brief is useless. |
+| Skipping the "one thing this is NOT" line | This is the single best scope-protection in the brief. Future "let's add X" gets compared against it. |
+| Writing the brief without showing it first | They have to react to it. They'll catch their own bad fits when they read it back. |
+| Defaulting to "full game" scope | New devs overestimate. Default to vertical slice; let them upgrade if they push. |
+| Pitching a genre they didn't ask for | The first sentence they typed is signal. Don't override it. |
+| Including art direction details | One phrase. Bible-building is `/summer:art-direction`. |
+| Saving without asking | Always ask "May I create `.summer/GameSoul.md`?" — see collaborative-protocol. |
+
+## Collaborative protocol
+
+This skill writes one file (`.summer/GameSoul.md`). Always ask before writing. Always show the brief inline before saving so the user can react. See `_shared/collaborative-protocol.md`.
+
+## Want a working starter?
+
+No template — this is a workflow that produces the brief that drives template selection later. Once `.summer/GameSoul.md` exists, `/summer:make-game` can match it against `_shared/template-registry.md`.
+
+## See also
+
+- `_shared/collaborative-protocol.md` — "May I write?" pattern
+- `_shared/template-registry.md` — templates the brief will be matched against later
+- `gameplay-mechanics/design-mechanic/SKILL.md` — design the core loop in detail
+- `level-design/design-level/SKILL.md` — sketch level 1
+- `rendering-and-lighting/art-direction/SKILL.md` — turn the one-phrase look into a full bible
+- `audio/audio-direction/SKILL.md` — sonic identity
+- `scene-and-project/make-game/SKILL.md` — scaffold the project once the brief is locked

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