summer-engine 1.2.1 → 1.3.1

package/skills/debugging/debug/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: debug
+description: Use when the user reports their game is broken, crashing, behaving unexpectedly, or says "debug", "fix", "something's wrong", or "it's not working". Triages the bug end-to-end via Summer Engine's diagnostic tools (console, debugger errors, script errors), locates the offending code, proposes a fix, and verifies the fix.
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: debugging
+user-invocable: true
+allowed-tools: Read Grep Glob Edit summer_get_console summer_get_debugger_errors summer_get_script_errors summer_get_diagnostics summer_clear_console summer_play summer_stop summer_is_running summer_get_scene_tree summer_inspect_node
+paths: ["**/*.gd", "**/*.tscn", "**/*.cs"]
+---
+
+# /debug — Triage and Fix a Bug
+
+## Overview
+
+A bug in a Godot/Summer game can hide in three places: scripts (GDScript/C# compile or runtime errors), the engine console (printed messages, warnings), or the scene/resource state (wrong property, missing collider, broken signal connection). This skill walks all three before guessing.
+
+**Core principle:** read what the engine actually saw, not what the code looks like it does.
+
+## Steps
+
+### 1. Get the user's description first
+
+Ask one short question:
+
+> What's happening? Briefly: when does it go wrong, and what do you expect vs. what you see?
+
+Wait for the answer before doing anything else. Don't start grepping code yet — the user's words narrow the search 10x.
+
+### 2. Read the engine's actual error state
+
+Always do this in order. Each tool answers a different question.
+
+**Preferred (Summer MCP):**
+
+```
+summer_get_script_errors        # Compile errors? (cheapest, do first)
+summer_get_console              # Print() output, warnings, info
+summer_get_debugger_errors      # Runtime errors with stack traces
+summer_get_diagnostics          # Aggregated count + summary
+```
+
+If the bug is reproducible only at runtime and the engine isn't currently playing:
+
+```
+summer_clear_console            # Clean slate
+summer_play                     # Run it
+                                # (let the user reproduce the bug)
+summer_get_debugger_errors      # Now read what blew up
+summer_stop                     # When done
+```
+
+**Fallback (no MCP — engine isn't connected):**
+
+Ask the user to copy-paste the engine's Output panel and Debugger errors. Inspect manually.
+
+### 3. Locate the offending code
+
+For each error, follow the stack trace to the file + line. Use host file tools:
+
+```
+Read <file>:<line-near-error>
+```
+
+Read 20–40 lines around the error site. Don't open the whole file unless you need to — context budget matters.
+
+If the error mentions a node path (e.g. `./World/Player/Camera`), inspect it:
+
+```
+summer_inspect_node "./World/Player/Camera"
+```
+
+### 4. Form a hypothesis and propose the fix
+
+State it in one sentence:
+
+> The error happens because <root cause>. The fix is <one-line summary>.
+
+Then ask:
+
+> May I edit `<file>` to <do exactly this>?
+
+Don't guess at multiple fixes at once. Pick one. If wrong, the next iteration is cheap.
+
+### 5. Apply the fix
+
+On user yes, edit the file with host tools (`Edit`/`Write`). Single focused change.
+
+### 6. Verify
+
+Re-run the relevant check:
+
+```
+summer_get_script_errors        # If it was a compile error
+summer_play → summer_get_debugger_errors → summer_stop   # If runtime
+```
+
+Report:
+
+> Fixed. <One-line description of what changed.>
+
+If still broken: go back to step 4 with the new error state. State explicitly that the first hypothesis was wrong.
+
+## Common bug patterns and how to spot them
+
+| Symptom | Likely cause | First check |
+|---|---|---|
+| `Invalid set index 'X' (on base: Nil)` | Node path resolved to null | `summer_inspect_node` the path |
+| `Identifier not declared` (script error) | Missing `class_name` or wrong scope | `summer_get_script_errors` |
+| Game runs but sprite doesn't appear | Node added but not visible (transform / parent / layer) | `summer_get_scene_tree` + inspect parent |
+| Signal handler never fires | Connection not made, or connected to wrong instance | `summer_inspect_node` of emitter, check connections |
+| Player falls through floor | CollisionShape3D has no shape, or shape is inline sub_resource | `summer_inspect_resource` on the CollisionShape |
+| Mouse capture stuck | `Input.set_mouse_mode` not paired with release on focus loss | `summer_get_console` for warnings |
+| Game hangs on start | Infinite loop in `_ready()` or `_process()` | `summer_get_debugger_errors` after a forced stop |
+
+## Anti-patterns (don't do these)
+
+- **Don't** start by reading the user's whole codebase. The error tells you where to look.
+- **Don't** propose a sweeping refactor for a single bug. One file, one change, verify.
+- **Don't** call `summer_set_resource_property` on an inline `sub_resource` — it silently fails. See `_shared/mcp-tools-reference.md` § "Trap".
+- **Don't** call `summer_play` without `summer_clear_console` first if you want clean output to read.
+- **Don't** skip the user's description in step 1. "What were you trying to do" beats "what does the code do" 9/10 times.
+
+## Collaborative protocol
+
+This skill writes files. Always ask before each edit step. See `_shared/collaborative-protocol.md`.
+
+## Want a working starter?
+
+No template — this is a workflow, not a project scaffold. It works against any Godot/Summer project that has Summer MCP wired up.
+
+## See also
+
+- `_shared/mcp-tools-reference.md` — full tool list
+- `_shared/godot-version.md` — engine version + LLM cutoff risks
+- `scripting-patterns/gdscript-patterns/SKILL.md` — what good GDScript looks like
+- `scene-and-project/play/SKILL.md` — running the game

package/skills/{3d-lighting → rendering-and-lighting/3d-lighting}/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: 3d-lighting
-description: Lighting setup, environment, sky, and shadows for 3D scenes. Use when setting up a 3D scene, adding lights, configuring WorldEnvironment, or adjusting shadows.
+description: Lighting setup, WorldEnvironment, sky, and shadows for 3D scenes. Use when setting up a 3D scene, adding lights, configuring environment, or adjusting shadows. Trigger on "lighting", "shadows", "WorldEnvironment", "sun", "ambient".
 license: MIT
-compatibility:
-  - Cursor
-  - Claude Code
-  - Windsurf
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: rendering-and-lighting
+user-invocable: false
+allowed-tools: Read Grep summer_add_node summer_set_prop summer_set_resource_property summer_save_scene
+paths: ["**/*.tscn", "**/*.tres"]
 ---
 
 # 3D Lighting for Summer Engine

package/skills/{make-game → scene-and-project/make-game}/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: make-game
-description: End-to-end game creation workflow. Use when the user wants to build a complete game, start a new project, or says "make me a game". Orchestrates project setup, asset creation, scene building, scripting, and testing.
+description: End-to-end game creation workflow that orchestrates project setup, asset creation, scene building, scripting, and testing. Use when the user wants to build a complete game from scratch or says "make me a game". Trigger on "make a game", "build me a game", "create a new game".
 license: MIT
-compatibility:
-  - Cursor
-  - Claude Code
-  - Windsurf
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: scene-and-project
+user-invocable: false
+allowed-tools: Read Grep Glob Write Edit summer_get_project_context summer_get_agent_playbook summer_create_scene summer_open_scene summer_save_scene summer_add_node summer_set_prop summer_set_resource_property summer_instantiate_scene summer_play summer_stop summer_get_diagnostics
+paths: ["**/*.gd", "**/*.tscn", "**/project.godot"]
 ---
 
 # Make a Game with Summer Engine

package/skills/scene-and-project/play/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: play
+description: Use when the user says "play", "run it", "test it", "let me see it", or "start the game". Runs the project in Summer Engine, briefly waits, then reports what's happening — clean run, errors, or warnings.
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: scene-and-project
+user-invocable: true
+allowed-tools: summer_is_running summer_play summer_stop summer_clear_console summer_get_console summer_get_debugger_errors summer_get_script_errors summer_get_diagnostics
+paths: ["**/project.godot", "**/*.tscn"]
+---
+
+# /play — Run the Game
+
+## Overview
+
+Press play. Watch what happens. Report it back.
+
+## Steps
+
+### 1. Check if it's already running
+
+```
+summer_is_running
+```
+
+If running:
+> The game is already playing. Stop and restart, or leave it?
+
+Wait for the user. Don't unilaterally stop.
+
+If not running, continue.
+
+### 2. Pre-check for compile errors
+
+Cheapest call. If the script won't compile, play will fail with a noisy error — better to surface that clearly first.
+
+```
+summer_get_script_errors
+```
+
+If errors found:
+> Won't run yet — there's a script error: `<one-line summary>`. Want me to /debug it?
+
+Stop here on user's no.
+
+### 3. Clear and play
+
+```
+summer_clear_console
+summer_play
+```
+
+### 4. Brief wait, then read state
+
+Wait ~2 seconds (so the engine has time to process at least one frame). Then:
+
+```
+summer_get_diagnostics
+summer_get_debugger_errors
+```
+
+### 5. Report
+
+Three outcomes:
+
+**Clean:** `summer_get_diagnostics` shows zero errors and zero warnings.
+
+> Running. No errors or warnings. Tell me what you see and I'll dig in if needed.
+
+**Warnings only:**
+
+> Running. <N> warnings — `<one-line summary of the most important one>`. Want me to look at them?
+
+**Runtime error:**
+
+> Crashed: `<error class>` at `<file>:<line>` — `<message>`. Want me to /debug?
+
+### 6. Don't auto-stop
+
+Leave the game running. The user wants to play it. Stop only on explicit ask.
+
+## Common patterns
+
+| Situation | Right move |
+|---|---|
+| User says "play" with no context | Steps 1–5 above |
+| User says "play and watch it for me" | After step 5, set a timer / poll `summer_get_debugger_errors` every few seconds for the duration the user specifies |
+| User says "play the boss fight scene" | Open the specific scene first (`summer_open_scene "scenes/boss_fight.tscn"`), then steps 1–5 |
+| Game is already running and user says "play" again | Step 1's check covers it — ask before restarting |
+
+## Anti-patterns
+
+- **Don't** auto-stop a running game just because the user said "play". They probably mean "make sure it's playing", not "stop and restart".
+- **Don't** call `summer_get_console` instead of `summer_get_debugger_errors` for runtime errors. Console has print() output and warnings; debugger errors has the stack traces.
+- **Don't** report "no errors" before waiting for the engine to actually run a frame. A 0-frame snapshot is meaningless.
+
+## Collaborative protocol
+
+This skill mutates engine state (clearing console, starting play). It's a read-side workflow with one safe write (`summer_play`). No "May I" needed — this is what the user asked for. Do confirm before stopping a running game.
+
+## Want a working starter?
+
+No template — works against any Godot/Summer project that has a main scene set in `project.godot`.
+
+## See also
+
+- `_shared/mcp-tools-reference.md` — full tool list
+- `debugging/debug/SKILL.md` — what to do when /play surfaces an error

package/skills/{scene-composition → scene-and-project/scene-composition}/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: scene-composition
-description: How to structure scenes, when to use sub-scenes, and node hierarchy conventions. Use when building scenes, organizing nodes, or creating reusable prefabs.
+description: How to structure scenes, when to use sub-scenes, node hierarchy conventions, and reusable prefabs. Use when building scenes, organizing nodes, or creating instanced prefabs. Trigger on "scene", "sub-scene", "instance", "prefab", "node hierarchy".
 license: MIT
-compatibility:
-  - Cursor
-  - Claude Code
-  - Windsurf
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: scene-and-project
+user-invocable: false
+allowed-tools: Read Grep summer_create_scene summer_open_scene summer_get_scene_tree summer_add_node summer_instantiate_scene summer_save_scene
+paths: ["**/*.tscn"]
 ---
 
 # Scene Composition for Summer Engine

package/skills/{gdscript-patterns → scripting-patterns/gdscript-patterns}/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: gdscript-patterns
-description: Common GDScript idioms, signals, exports, and type hints. Use when writing GDScript, attaching scripts to nodes, connecting signals, or defining exported variables.
+description: Common GDScript idioms — type hints, signals, exports, onready, lifecycle methods, naming conventions. Use when writing GDScript, attaching scripts, or refactoring untyped code. Trigger on "GDScript", "script", "signals", "exports".
 license: MIT
-compatibility:
-  - Cursor
-  - Claude Code
-  - Windsurf
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: scripting-patterns
+user-invocable: false
+allowed-tools: Read Grep summer_get_script_errors
+paths: ["**/*.gd"]
 ---
 
 # GDScript Patterns for Summer Engine

package/skills/{ui-basics → ui-and-ux/ui-basics}/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: ui-basics
-description: HUD, menus, health bars, and responsive UI layout. Use when building menus, HUDs, health bars, or Control-based UI in Summer Engine.
+description: HUD, menus, health bars, progress bars, and Control-based UI layout. Use when building menus, HUDs, health bars, or any Control-tree UI. Trigger on "UI", "HUD", "menu", "health bar", "Control".
 license: MIT
-compatibility:
-  - Cursor
-  - Claude Code
-  - Windsurf
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: ui-and-ux
+user-invocable: false
+allowed-tools: Read Grep summer_add_node summer_set_prop summer_connect_signal summer_save_scene
+paths: ["**/*.tscn", "**/*.gd"]
 ---
 
 # UI Basics for Summer Engine