summer-engine 1.3.1 → 1.4.0

package/skills/gameplay-mechanics/design-mechanic/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: design-mechanic
+description: Use when designing one specific game mechanic in detail — input, response, feedback, failure modes, depth, tunables. Outputs a design doc and a scaffolding-ready node-graph sketch + GDScript stub. Trigger on "design a mechanic", "how should X work", "design the parry", "design the dash", "design the inventory", "the loop is broken".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: gameplay-mechanics
+user-invocable: true
+allowed-tools: Read Grep Glob Write Edit summer_get_scene_tree summer_inspect_node summer_add_node summer_set_prop summer_input_map_bind summer_save_scene summer_get_script_errors
+paths: ["**/*.gd", "**/*.tscn", ".summer/**"]
+---
+
+# /design-mechanic — Design One Mechanic in Detail
+
+## Overview
+
+A "mechanic" is a verb the player performs that produces a meaningful response from the world. Not a system. Not a feature. A verb with feedback. This skill walks the five layers of a real mechanic: **input → response → feedback → failure modes → depth** — then drops a node-graph sketch + GDScript stub into the project so the next session can implement it.
+
+**Core principle:** a mechanic is only as good as its weakest feedback layer. A perfect parry with no audio cue is broken. A great audio cue with floaty input is broken. Walk all five layers before scaffolding.
+
+## Steps
+
+### 1. Pin which mechanic
+
+Ask exactly one question and wait:
+
+> Which mechanic? (e.g., "double-jump", "parry", "stamina-dash", "pickup", "lock-on", "crafting-recipe-craft").
+
+If the user gives a system name ("inventory", "combat"), push back:
+
+> Inventory is a system, not a mechanic. The mechanics inside it are: pickup, equip, drop, use, swap. Which one?
+
+### 2. Read context if available
+
+If `.summer/GameSoul.md` exists, read it. The mechanic should fit the game brief, not exist in isolation.
+
+```
+Read .summer/GameSoul.md
+```
+
+Quote the relevant constraint back at the user:
+
+> Brief says core loop is "see obstacle, attempt, fail, learn, retry". A double-jump only matters if it changes which obstacles are reachable. Confirm that's what we're solving.
+
+### 3. Walk the five layers — one at a time
+
+**Layer 1: Input.** Exactly what does the player press, hold, release, time?
+
+State a candidate, ask for refinement:
+
+> Input candidate: tap Space mid-air. Or: hold-and-release for variable height? Or: requires direction + Space? Pick one.
+
+**Layer 2: Response.** What changes in the world the moment the input fires?
+
+State the deltas. For double-jump:
+
+> Response: vertical velocity set to (jump_velocity * 0.85). `_can_double_jump` flag flips false. Visual rig plays "jump_2" anim. Audio cue. Particle burst at feet.
+
+**Layer 3: Feedback** — and this is where most amateur designs collapse. Three sub-channels, all required:
+
+| Channel | Question to answer | Bad example | Good example |
+|---|---|---|---|
+| Visual | Can a player who can't hear tell it worked? | "It just jumps." | "GPUParticles3D burst at feet, 0.1s slow-mo on apex, after-image trail behind." |
+| Audio | Can a player who can't see tell it worked? | "Plays jump.wav." | "Layered: short whoosh on input, ambient pitch-up while airborne, soft thud on second jump start." |
+| Mechanical | Does the input feel different from a single-jump? | "Same jump, just twice." | "Second jump has tighter air control, slightly lower height, different particle color." |
+
+Force the user to answer all three. If they hand-wave one, name it:
+
+> You named visual and audio. Mechanical-feel is missing — what makes the second jump feel different from the first beyond just being a second one?
+
+**Layer 4: Failure modes.** What happens when the input fires but conditions aren't met?
+
+For double-jump:
+
+- Already used? → no input registered? Or denied with a UI shake? Or a small audio cue?
+- During wall-slide? → does it count as airborne or grounded?
+- During cutscene? → is input gated entirely?
+- Spammed input? → buffered or ignored?
+
+State the rules, ask:
+
+> Failure rules: (a) already-used → silent ignore. (b) during wall-slide → counts as airborne, can double-jump off wall. (c) cutscene → input fully gated. (d) spam → input buffer of 0.1s. OK?
+
+**Layer 5: Depth.** What makes this mechanic interesting after 5 minutes of play?
+
+This is the hardest layer. State the depth-vector explicitly:
+
+> Depth: double-jump becomes interesting when level design forces a *choice* — jump now to clear obstacle A, or save it to escape enemy B coming at you. Without that choice, it's just a longer jump. The level-design implication: every double-jump gap should pair with a near-future threat that also wants the resource.
+
+If the user can't articulate depth, the mechanic might not be needed. Say it:
+
+> If the only purpose is "can reach higher platforms", that's just a higher-jumping single-jump. Either change the input shape (give it a cost), or cut it.
+
+### 4. List the tunables
+
+Every mechanic has 3-7 numbers a designer will tweak. Name them. For double-jump:
+
+```
+@export var double_jump_velocity: float = 4.0      # vertical speed of second jump
+@export var double_jump_air_control: float = 0.7   # multiplier vs ground control
+@export var input_buffer_time: float = 0.1         # window to register early input
+@export var ground_grace_period: float = 0.05      # coyote time before lockout
+@export var slow_mo_on_apex: float = 0.0           # 0 = off, 0.05 = brief
+```
+
+These become `@export` vars in the stub. The user tunes in the inspector, no recompile.
+
+### 5. Sketch the node graph
+
+Describe what nodes the mechanic touches in the existing scene. Don't add yet — sketch first.
+
+```
+World/Player (CharacterBody3D)               # existing
+├── CollisionShape3D                          # existing
+├── Camera3D                                  # existing
+├── DoubleJumpFX (GPUParticles3D)             # NEW — particles on second jump
+├── JumpAudio (AudioStreamPlayer3D)           # NEW — input + apex cues
+└── (script: player_controller.gd, modify)    # MODIFY — add _can_double_jump state
+```
+
+Show this to the user. Ask:
+
+> Node-graph plan above. May I add `DoubleJumpFX` and `JumpAudio` to `./World/Player`, and modify `player_controller.gd` to add the double-jump logic?
+
+### 6. Scaffold via MCP
+
+**Preferred (Summer MCP):**
+
+```
+summer_get_scene_tree                       # confirm Player exists where expected
+summer_add_node(parent="./World/Player", type="GPUParticles3D", name="DoubleJumpFX")
+summer_set_prop("./World/Player/DoubleJumpFX", "emitting", "false")
+summer_add_node(parent="./World/Player", type="AudioStreamPlayer3D", name="JumpAudio")
+summer_input_map_bind(name="jump", events=[{type:"key", key:"Space"}])  # idempotent
+summer_save_scene
+summer_get_script_errors
+```
+
+**Fallback (no MCP):** Print the `.tscn` snippet for the user to paste:
+
+```
+[node name="DoubleJumpFX" type="GPUParticles3D" parent="Player"]
+emitting = false
+amount = 16
+lifetime = 0.4
+
+[node name="JumpAudio" type="AudioStreamPlayer3D" parent="Player"]
+```
+
+### 7. Write the GDScript stub
+
+Stub only — implementation is the next session. Use `_shared/gd-style.md` conventions. For double-jump:
+
+```gdscript
+class_name PlayerController
+extends CharacterBody3D
+
+# Tunables
+@export var jump_velocity: float = 4.5
+@export var double_jump_velocity: float = 4.0
+@export var double_jump_air_control: float = 0.7
+@export var input_buffer_time: float = 0.1
+
+# State
+var _can_double_jump: bool = false
+var _input_buffer_t: float = 0.0
+
+@onready var fx: GPUParticles3D = $DoubleJumpFX
+@onready var audio: AudioStreamPlayer3D = $JumpAudio
+
+signal jumped
+signal double_jumped
+
+func _physics_process(delta: float) -> void:
+    _input_buffer_t = max(0.0, _input_buffer_t - delta)
+
+    if Input.is_action_just_pressed("jump"):
+        _input_buffer_t = input_buffer_time
+
+    if _input_buffer_t > 0.0:
+        if is_on_floor():
+            velocity.y = jump_velocity
+            _can_double_jump = true
+            _input_buffer_t = 0.0
+            jumped.emit()
+        elif _can_double_jump:
+            velocity.y = double_jump_velocity
+            _can_double_jump = false
+            _input_buffer_t = 0.0
+            fx.emitting = true
+            audio.play()
+            double_jumped.emit()
+
+    move_and_slide()
+```
+
+Ask:
+
+> May I write `scripts/player_controller.gd` (or merge into the existing script if one is attached)?
+
+### 8. Save the design doc
+
+Always write the design doc — it's the artifact the next session reads. Path: `.summer/mechanics/<mechanic-name>.md`.
+
+```markdown
+# Mechanic: Double-Jump
+
+**Input:** Tap Space mid-air. Buffered 0.1s before ground.
+**Response:** velocity.y = double_jump_velocity. `_can_double_jump` flag false.
+**Feedback:**
+- Visual: GPUParticles3D burst, 0.1s slow-mo on apex
+- Audio: short whoosh on input
+- Mechanical: 70% air control on second jump
+**Failure modes:**
+- Already used → silent ignore
+- During wall-slide → counts as airborne
+- Cutscene → input gated
+- Spam → buffered (0.1s window)
+**Depth:**
+- Resource the player chooses when to spend
+- Level design pairs every gap with a near-future threat
+**Tunables:** see @export vars in player_controller.gd
+**Open questions:** <list any the user couldn't answer>
+```
+
+Ask:
+
+> May I create `.summer/mechanics/double-jump.md` with this design doc?
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Designing the system, not the verb | "Combat" is a system. "Parry" is a mechanic. Pick the verb. |
+| Skipping mechanical-feel in feedback | Visual + audio alone produce hollow mechanics. Mechanical difference is required. |
+| No failure modes | Players spam, edge into states you didn't plan for, and find the hole. Plan the failure cases up front. |
+| Hand-wave depth | "Players will use it strategically" is not depth. Name the choice the player makes. |
+| Tunables hard-coded as `const` | Use `@export` so designers tune in the inspector. |
+| Adding the mechanic without the FX/audio nodes | Without nodes for feedback, the mechanic ships feeling cheap. Scaffold the nodes alongside the script. |
+| Setting `position` for movement instead of `velocity` | Physics objects use `velocity` in `_physics_process`. See `_shared/gd-style.md`. |
+| Calling SetResourceProperty on inline sub_resources | Silent fail. See `_shared/mcp-tools-reference.md` § Trap. |
+
+## Collaborative protocol
+
+This skill writes scene nodes and one or more files (`.gd`, `.summer/mechanics/<name>.md`). Group writes into one ask per phase. See `_shared/collaborative-protocol.md`.
+
+## Want a working starter?
+
+For full character mechanics in a runnable starter:
+
+- FPS variant → `template-id: template-3d-fps` (https://github.com/SummerEngine/FPS-template-Summer-Engine)
+- Platformer → `template-id: template-3d-platformer` (TBD)
+
+This skill is a workflow that designs and scaffolds — the templates are runnable bases the mechanic plugs into.
+
+## See also
+
+- `_shared/collaborative-protocol.md`
+- `_shared/mcp-tools-reference.md`
+- `_shared/gd-style.md` — GDScript conventions
+- `_shared/godot-version.md` — Godot 4.5 API notes
+- `scene-and-project/brainstorm-game/SKILL.md` — produces `.summer/GameSoul.md` this skill reads
+- `level-design/design-level/SKILL.md` — design the levels that exercise the mechanic
+- `character-controllers/fps-controller/SKILL.md` — FPS movement scaffolding
+- `scripting-patterns/state-machine-patterns/SKILL.md` — state machines for complex mechanics
+- `audio/audio-direction/SKILL.md` — defines the SFX vocabulary the mechanic draws from

package/skills/level-design/design-level/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: design-level
+description: Use when designing a single level — layout, pacing, encounters, secrets, reward gating. Outputs a level design doc and a concrete node-tree skeleton for `summer_create_scene`. Trigger on "design a level", "design level 1", "tutorial level", "boss arena", "design the encounter", "make a level layout".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: level-design
+user-invocable: true
+allowed-tools: Read Grep Glob Write Edit summer_get_scene_tree summer_create_scene summer_open_scene summer_add_node summer_set_prop summer_save_scene summer_get_script_errors
+paths: ["**/*.tscn", "**/*.gd", ".summer/**", "levels/**"]
+---
+
+# /design-level — Design One Level
+
+## Overview
+
+A level is a controlled sequence of player experiences in physical space. Layout, pacing, encounters, secrets, and reward gating must work together — a "fun layout" with a flat pacing curve still feels boring. This skill walks the six design beats of a single level and drops a node-tree skeleton ready for `summer_create_scene`.
+
+**Core principle:** A level has a *pacing curve* and a *teaching arc*. If you can't draw the tension graph and name what the player learned by the end, the level isn't designed yet.
+
+## Steps
+
+### 1. Pin the level type
+
+Ask exactly one question:
+
+> What kind of level? Pick one: tutorial / hub / combat encounter / boss / exploration / puzzle / stealth / platforming-challenge / mixed.
+
+Each type has different beats. Don't blend types in v1 — a "boss room with stealth and puzzles" is three levels poorly squeezed into one.
+
+### 2. Read context
+
+If `.summer/GameSoul.md` exists, read it. The level must serve the brief's core loop and the three mechanics.
+
+```
+Read .summer/GameSoul.md
+```
+
+If `.summer/mechanics/` exists, list the mechanics. Quote them back:
+
+> Brief says mechanics are: dash, parry, double-jump. This level should *exercise* at least one and ideally combine two.
+
+### 3. Define the teaching / experience goal
+
+Ask plain:
+
+> What does the player know by the end of this level that they didn't at the start?
+
+Tutorial-level answer: "How to dash." Combat-encounter answer: "That parrying converts damage to mana, and that big enemies need parry, not dodge." Exploration answer: "That this region's secrets are hidden behind double-jumpable gaps."
+
+If the user can't answer, the level has no purpose. Say it:
+
+> If there's no answer to that question, the level is filler. Either give it a teaching goal, give it a *failure-state* goal (the player must die here to progress), or merge it into the next level.
+
+### 4. Sketch the pacing curve
+
+Draw it as text. Five beats, intensity 0-10:
+
+```
+Intro    Build    Peak    Release    Hook
+ 2  →    5    →   8   →    3      →   6
+```
+
+For a 5-minute encounter level:
+
+| Beat | Duration | Intensity | Player feels | Designer plants |
+|---|---|---|---|---|
+| Intro | 30s | 2 | Calm, oriented | Visual landmark for the goal direction |
+| Build | 90s | 5 | Tension rising, small pressure | First weak enemy / first puzzle clue |
+| Peak | 60s | 8 | Stakes high, mistakes hurt | Main encounter / hardest fight |
+| Release | 60s | 3 | Catharsis, loot | Reward + breath room |
+| Hook | 30s | 6 | Curiosity for next | Visible-but-locked secret or path |
+
+Show the curve. Ask:
+
+> Pacing above. Does the peak land where you want, or does the level need a second wave?
+
+### 5. List encounters and secrets
+
+Encounters = explicit player tests (combat, puzzle, platforming). Secrets = optional rewards that respect the pacing curve.
+
+State them flat. For a combat encounter level:
+
+```
+Encounters (in player-traversal order):
+1. E1 — Tutorial enemy (1 weak grunt) at 0:30, in the open atrium. Teaches the basic attack.
+2. E2 — Forced parry (mid-tier enemy with telegraphed wind-up) at 1:30, in a corridor with no dodge room. Teaches parry.
+3. E3 — Mixed wave (2 grunts + 1 parry-required) at 3:00, in the peak arena. Tests both.
+4. E4 — Mini-boss at 4:00 in the chamber. Combines.
+
+Secrets (3 total — one per beat after intro):
+- S1 (build beat): Behind a breakable wall in the corridor, holds 50 currency. Teaches "walls can break".
+- S2 (peak beat): Visible from the arena, accessible only via parrying off an enemy. Rewards mastery.
+- S3 (hook beat): Locked door, key in a future level. Plants curiosity for next level.
+```
+
+### 6. Define reward gating
+
+What's behind which gate? Levels feel cheap when they hand out rewards without respecting the difficulty curve.
+
+| Reward | Gate | Why |
+|---|---|---|
+| Heal pickup | After E2 | Player just learned parry; reward + safety net before the peak |
+| New ability unlock | After mini-boss | Mastery-pinned; player demonstrates parry before getting upgrade |
+| Currency cache | Behind S1 (breakable wall) | Optional; rewards observation |
+| Story note | At the calm intro | Free; orients the player to the level's narrative |
+
+Ask:
+
+> Reward gating above. Anything missing or mis-placed?
+
+### 7. Define the layout primitives
+
+Every level is built from a small vocabulary of spaces. Name them. Most levels need 4-6 distinct spaces, no more.
+
+For a combat-encounter level:
+
+```
+Spaces (node-tree skeleton):
+World (Node3D)
+├── Geometry (Node3D)
+│   ├── IntroAtrium (Node3D)         # open, calm, well-lit
+│   ├── Corridor (Node3D)            # tight, forces parry
+│   ├── PeakArena (Node3D)           # large, multiple cover, exit visible
+│   └── BossChamber (Node3D)         # contained, single exit, dramatic lighting
+├── Spawns (Node3D)
+│   ├── PlayerSpawn (Node3D)         # marker
+│   ├── E1_Spawn (Node3D)
+│   ├── E2_Spawn (Node3D)
+│   ├── E3_Wave_Spawns (Node3D)
+│   └── MiniBoss_Spawn (Node3D)
+├── Triggers (Node3D)
+│   ├── E2_GateTrigger (Area3D)      # locks door behind player on entry
+│   ├── PeakWaveTrigger (Area3D)
+│   └── BossDoorTrigger (Area3D)
+├── Pickups (Node3D)
+│   ├── HealAfterE2 (Node3D)
+│   └── CurrencyS1 (Node3D)
+├── Secrets (Node3D)
+│   ├── S1_BreakableWall (StaticBody3D)
+│   ├── S2_ParryLedge (StaticBody3D)
+│   └── S3_LockedDoor (StaticBody3D)
+└── Lighting (Node3D)                # WorldEnvironment + DirectionalLight3D
+```
+
+Show the skeleton. Ask:
+
+> Tree above. May I create the level scene `levels/<level-name>.tscn` with this skeleton?
+
+### 8. Scaffold via MCP
+
+**Preferred (Summer MCP):**
+
+```
+summer_create_scene(path="res://levels/level_01.tscn", root_type="Node3D", root_name="World")
+summer_add_node(parent="./World", type="Node3D", name="Geometry")
+summer_add_node(parent="./World/Geometry", type="Node3D", name="IntroAtrium")
+summer_add_node(parent="./World/Geometry", type="Node3D", name="Corridor")
+summer_add_node(parent="./World/Geometry", type="Node3D", name="PeakArena")
+summer_add_node(parent="./World/Geometry", type="Node3D", name="BossChamber")
+summer_add_node(parent="./World", type="Node3D", name="Spawns")
+summer_add_node(parent="./World/Spawns", type="Node3D", name="PlayerSpawn")
+summer_add_node(parent="./World/Spawns", type="Node3D", name="E1_Spawn")
+# ... and so on
+summer_add_node(parent="./World", type="Node3D", name="Triggers")
+summer_add_node(parent="./World/Triggers", type="Area3D", name="E2_GateTrigger")
+# ... etc.
+summer_add_node(parent="./World", type="Node3D", name="Lighting")
+summer_add_node(parent="./World/Lighting", type="WorldEnvironment", name="WorldEnvironment")
+summer_add_node(parent="./World/Lighting", type="DirectionalLight3D", name="Sun")
+summer_save_scene
+```
+
+This is a **skeleton, not playable geometry**. Markers and Area3Ds, no meshes, no enemy scripts. Implementation in subsequent sessions / templates.
+
+**Fallback (no MCP):** Print the `.tscn` file contents for the user to save manually.
+
+### 9. Save the level design doc
+
+Always write the design doc — it's the artifact that drives implementation. Path: `.summer/levels/<level-name>.md`.
+
+```markdown
+# Level: <Name>
+
+**Type:** combat encounter
+**Duration target:** 5 min
+**Teaching goal:** Player learns parry and that parrying mid-tier enemies is required, not optional.
+
+**Pacing curve:** 2 → 5 → 8 → 3 → 6
+**Beats:** Intro (30s) | Build (90s) | Peak (60s) | Release (60s) | Hook (30s)
+
+## Encounters
+- E1 — Tutorial grunt @ 0:30 (IntroAtrium)
+- E2 — Forced parry @ 1:30 (Corridor)
+- E3 — Mixed wave @ 3:00 (PeakArena)
+- E4 — Mini-boss @ 4:00 (BossChamber)
+
+## Secrets
+- S1 — Breakable wall (Corridor) → 50 currency
+- S2 — Parry-ledge (PeakArena) → cosmetic
+- S3 — Locked door (BossChamber) → next level
+
+## Reward Gating
+- Heal pickup after E2
+- Ability unlock after mini-boss
+
+## Spaces
+1. IntroAtrium — open, calm
+2. Corridor — tight, forces parry
+3. PeakArena — large with cover
+4. BossChamber — contained, dramatic
+
+## Open questions
+<list anything the user couldn't answer>
+```
+
+Ask:
+
+> May I create `.summer/levels/<level-name>.md` with this design doc?
+
+### 10. Route to the next step
+
+End with:
+
+> Skeleton + design doc saved. Next:
+> - `/summer:design-mechanic` to design any mechanics this level requires that aren't designed yet.
+> - `/summer:design-npc` to design the enemies (E1-E4) in detail.
+> - `/summer:art-direction` if the visual style isn't pinned yet.
+> - Or open `levels/<level-name>.tscn` and start blocking out geometry.
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| No teaching goal | Every level teaches something or fails. State it explicitly. |
+| Flat pacing curve | If intensity stays at 5 the whole time, you have a hallway, not a level. |
+| Too many spaces | 4-6 distinct spaces max. More fragments the player's mental map. |
+| Encounters not tied to mechanics | E2 should *require* parry, not just allow it. Forced use teaches; optional use doesn't. |
+| Secrets ignore the pacing curve | Don't put a major secret in the calm intro — players aren't curious yet. |
+| Reward gating too generous | Free heals before the peak deflate the peak. Gate them after the test. |
+| Blending level types | Stealth + puzzle + boss in one level = three half-baked levels. Pick one. |
+| Building geometry before the skeleton | Skeleton-first lets you iterate on layout cheaply. Geometry comes after the design is locked. |
+| Calling SetResourceProperty on inline sub_resources | Silent fail. See `_shared/mcp-tools-reference.md` § Trap. |
+
+## Collaborative protocol
+
+This skill creates a new scene file (`.tscn`) and a design doc (`.md`). Group writes per phase. Always ask before `summer_create_scene`. See `_shared/collaborative-protocol.md`.
+
+## Want a working starter?
+
+This is a workflow that produces a skeleton scene. For runnable level examples, see:
+
+- `template-id: template-3d-fps` (https://github.com/SummerEngine/FPS-template-Summer-Engine) ships a sample arena.
+- `template-id: template-3d-platformer` (TBD) for jump-based level samples.
+
+The skeleton this skill produces is meant to be filled in via `/summer:design-mechanic`, gridmap blockout, or a template merge.
+
+## See also
+
+- `_shared/collaborative-protocol.md`
+- `_shared/mcp-tools-reference.md`
+- `_shared/godot-version.md` — Godot 4.5 API notes
+- `scene-and-project/brainstorm-game/SKILL.md` — produces `.summer/GameSoul.md`
+- `gameplay-mechanics/design-mechanic/SKILL.md` — designs the verbs the level exercises
+- `ai-and-npcs/design-npc/SKILL.md` — designs the enemies the encounters reference
+- `rendering-and-lighting/3d-lighting/SKILL.md` — sets the lighting in `WorldEnvironment` + lights
+- `rendering-and-lighting/art-direction/SKILL.md` — defines the visual style the level expresses