summer-engine 1.3.1 → 1.3.2

package/skills/performance/tune-performance/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: tune-performance
+description: Use when the user reports the game is slow, drops framerate, stutters, takes forever to start, or runs poorly on specific hardware. Profiles the running game via summer_get_diagnostics, identifies hotspots (rendering / physics / scripting), and proposes specific fixes with before/after metric expectations. Trigger on "slow", "lag", "fps drop", "stuttering", "performance", "optimize", "profile", "framerate".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: performance
+user-invocable: true
+allowed-tools: Read Grep Glob Edit summer_get_diagnostics summer_get_console summer_get_scene_tree summer_inspect_node summer_inspect_resource summer_play summer_stop summer_is_running summer_clear_console summer_set_prop summer_project_setting
+paths: ["**/*.gd", "**/*.tscn", "**/*.tres", "project.godot"]
+---
+
+# /tune-performance — Profile, Diagnose, Fix
+
+## Overview
+
+Performance tuning without measurement is gambling. This skill enforces a measure-first loop: read diagnostics, identify the dominant cost (rendering / physics / scripting / startup), drill into the specific pattern, propose one fix, verify the metric moved. No shotgun optimization.
+
+**Core principle:** the engine's diagnostics tell you which subsystem is bleeding. Don't optimize a different subsystem.
+
+## Steps
+
+### 1. Get the user's symptom precisely
+
+> What's slow? Pick the closest: framerate drops in scene X / startup is long / freezes for a moment / runs fine on my machine but bad on hardware Y.
+
+Wait. The answer narrows the fix domain by 5x:
+
+| Symptom | Likely subsystem |
+|---|---|
+| Framerate drops as more enemies spawn | Scripting (`_process` per-instance) or physics |
+| Framerate is fine standing still, drops looking at level X | Rendering (overdraw, draw calls, lights) |
+| Stutter every N seconds | GC pause, autoload loop, or async load |
+| Long startup | Asset import, autoload `_ready` work, shader compilation |
+| Runs fine on dev machine, bad on user machine | Resolution, GPU features (compute, GI), shadow quality |
+
+### 2. Take a baseline measurement
+
+Don't guess. Read the engine's actual numbers.
+
+**Preferred (Summer MCP):**
+
+```
+summer_clear_console
+summer_play
+# user reproduces the slowdown for 5–10 seconds
+summer_get_diagnostics
+summer_get_console               # check for warnings (e.g. "shader compilation hot-path")
+summer_stop
+```
+
+`summer_get_diagnostics` returns the aggregate metrics. Note (write down before fixing anything):
+
+- Average FPS during the slow section
+- Frame time (ms) — anything over 16.67 ms = below 60 fps
+- Draw calls per frame
+- Active physics bodies
+- Active GPUParticles instances
+- Script time vs. physics time vs. render time
+
+**Fallback (no MCP):** ask the user to enable Godot's built-in monitor (`Debug → Monitor` or in-game with `Performance.get_monitor`) and paste numbers. At minimum: FPS, frame time, draw calls, physics active objects.
+
+### 3. Identify the dominant cost
+
+The biggest number wins your attention. Don't optimize the second-biggest — that's a 5% win when 30% is sitting next to it.
+
+Decision tree:
+
+- **Render time > 50% frame budget** → rendering hotspot (Step 4a)
+- **Physics time > 30% frame budget** → physics hotspot (Step 4b)
+- **Script time > 30% frame budget** → GDScript hotspot (Step 4c)
+- **Frame time spikes (jitter) but average is fine** → GC / shader compile / async (Step 4d)
+- **FPS is fine but startup is slow** → import / autoload (Step 4e)
+
+### 4a. Rendering hotspot
+
+Common Godot 4.5 rendering costs, ordered by frequency:
+
+| Pattern | Symptom | Fix |
+|---|---|---|
+| Too many MeshInstance3D | Draw calls > 1000 | MultiMeshInstance3D for repeated meshes (foliage, debris). 5000 trees = 1 draw call. |
+| Overdraw (transparent stacked) | Render time spikes when looking at particles/glass/UI | Reduce particle `amount`, disable `transparent` on opaque materials, check Compositor settings |
+| Real-time lights > 4 visible | Frame time doubles in well-lit rooms | Bake static lighting (`LightmapGI`), make distant lights `shadow_enabled = false` |
+| Shadow map size too high | Render time spikes near light sources | DirectionalLight3D `directional_shadow_max_distance` lower, OmniLight3D shadow_bias up, shadow size 2048 → 1024 |
+| No occlusion culling | Far rooms drawn through walls | OccluderInstance3D + bake. Painful but high-impact for indoor scenes. |
+| Missing LOD on complex meshes | Drop in framerate when far away | MeshInstance3D `visibility_range_begin` + manual LOD swaps |
+
+To inspect a suspect node:
+
+```
+summer_inspect_node "./World/Enemy"
+summer_inspect_resource "./World/Enemy"   # for mesh/material/shape details
+```
+
+### 4b. Physics hotspot
+
+Top patterns:
+
+| Pattern | Fix |
+|---|---|
+| 100+ active RigidBody3D | Sleep them when idle (`can_sleep = true`), or convert to Area3D where collision response isn't needed |
+| Concave collision shapes on dynamic bodies | Convert to ConvexPolygonShape3D or compound primitives (sphere/capsule/box). Concave costs 5–20x more. |
+| Physics tick at 120 Hz default | Lower `physics/common/physics_ticks_per_second` to 60 if visual smoothness allows |
+| Per-frame raycast in `_physics_process` | Cache the result, raycast every N frames, or use ShapeCast3D |
+| Hundreds of overlap queries | Use Area3D with `monitoring = true` only on the bodies that need to detect — turn it off on environment |
+
+### 4c. GDScript hotspot
+
+Per-frame work in `_process` is the #1 GDScript cost. Read the script, look for:
+
+```gdscript
+# BAD — runs every frame
+func _process(delta: float) -> void:
+    var enemies = get_tree().get_nodes_in_group("enemies")  # tree walk!
+    for enemy in enemies:
+        var dist = global_position.distance_to(enemy.global_position)
+        if dist < 10.0:
+            ...
+```
+
+Fixes:
+
+- Cache the group lookup in `_ready()` if the group composition is stable.
+- Move per-frame work to a timer at 10 Hz (`_on_timer_timeout`), not 60 Hz.
+- Replace `distance_to` with `distance_squared_to` in comparisons (no sqrt).
+- Push hot loops to a `@tool`-able C# script or GDExtension if it's truly per-frame.
+
+### 4d. Frame time spikes (jitter)
+
+If FPS is good but frame time spikes:
+
+- **Shader compilation**: precompile shaders during loading screen via `RenderingServer.shader_compile_from_code` or by warming up the scene off-screen.
+- **GC / object allocation**: `var x := []` inside `_process` allocates each frame. Pre-allocate.
+- **Async resource load**: ensure `ResourceLoader.load_threaded_request` is finished before referencing.
+
+Check `summer_get_console` for shader-compile warnings.
+
+### 4e. Startup time
+
+```
+summer_clear_console
+summer_play
+# stop after first scene loads
+summer_stop
+summer_get_console
+```
+
+Look for:
+
+- Long autoload `_ready()` work (move to `call_deferred` or background thread).
+- Asset import on first run (cache `.import` files in source control).
+- `preload()` of huge scenes at script-parse time — switch to `load()` on demand.
+
+### 5. Propose ONE fix with a metric expectation
+
+Don't bundle five fixes. Pick the highest-leverage one.
+
+> The dominant cost is **rendering** at 14.2 ms / frame (85% of budget). The biggest source is 240 individual MeshInstance3D for foliage. Replacing them with one MultiMeshInstance3D should drop render time to ~3 ms (estimate: 5–7 ms). May I refactor `./World/Foliage` to use MultiMeshInstance3D?
+
+Format the proposal as: (a) what the dominant cost is, (b) the specific source, (c) the fix, (d) the expected metric movement, (e) the ask.
+
+### 6. Apply, re-measure, report
+
+After the user approves:
+
+```
+# apply the fix (Edit / summer_add_node / summer_set_prop / etc)
+summer_save_scene
+summer_clear_console
+summer_play
+# user reproduces the same scenario
+summer_get_diagnostics
+summer_stop
+```
+
+Compare: was the metric movement at least 50% of what was promised? If yes, ship it. If no, the hypothesis was wrong — go back to step 3 with the new numbers.
+
+> Before: 14.2 ms render / 22 fps. After: 4.1 ms render / 58 fps. Shipped.
+
+## Common mistakes
+
+| Don't | Do | Why |
+|---|---|---|
+| Optimize without baseline metrics | Always `summer_get_diagnostics` before and after | "Felt faster" is not a measurement |
+| Fix the second-biggest cost | Fix the biggest first, re-measure, re-prioritize | Amdahl's law — the small win evaporates next to the big one |
+| Bundle 5 fixes into one PR | One fix at a time, verify each | Bundles hide regressions. Hard to attribute the win or the loss. |
+| `_process` for everything | 10 Hz timer for AI / distance checks / range polls | 60 Hz AI is wasted CPU |
+| `distance_to` in hot loop | `distance_squared_to` in comparisons | sqrt is expensive at scale |
+| 200 RigidBody3D for debris | MultiMeshInstance3D + manual physics, or bake | Each rigid body = solver work every tick |
+| Real-time GI everywhere | Bake static lighting; real-time only for movable lights | Real-time GI is a per-frame budget killer |
+| Shadow map at 4096 on every light | 4096 for sun, 1024 or off for fillers | Shadow map writes are hidden render passes |
+| Concave shape on dynamic body | Compound primitives (sphere + box + capsule) | Concave shape physics is 5–20x slower |
+| `get_nodes_in_group` every frame | Cache once in `_ready()` | Tree walks aren't free |
+
+## Anti-patterns from the field
+
+- **"Just disable VSync to see real FPS."** Disabling VSync helps you measure, but performance work targets perceived smoothness (16.7 ms, locked). Re-enable before shipping.
+- **Premature C++ rewrite.** A GDScript hotpath at 5% of frame time isn't the bottleneck. Profile first.
+- **"It's slow on user machines, must be the GPU."** Often it's resolution scale + shadow quality + GI settings. Add a quality preset switcher first.
+- **Threading gameplay code.** Godot's gameplay layer isn't thread-safe. Threading is for asset load, network, AI compute — not `_physics_process`.
+
+## Collaborative protocol
+
+This skill makes scene/resource/code changes. Always ask before each fix is applied. See `_shared/collaborative-protocol.md`.
+
+## Want a working starter?
+
+No template — this is a workflow. Performance tuning is project-specific by definition.
+
+## See also
+
+- `_shared/mcp-tools-reference.md` — full MCP tool list
+- `_shared/godot-version.md` — Godot 4.5 renderer notes (Compositor, RenderSceneBuffers churn)
+- `_shared/collaborative-protocol.md` — "May I write" pattern
+- `_shared/gd-style.md` — GDScript conventions (avoid bare types, use `:=`)
+- `performance/profiling-godot/SKILL.md` — deeper Godot profiler usage
+- `performance/draw-call-batching/SKILL.md` — MultiMeshInstance3D patterns
+- `performance/lod-and-culling/SKILL.md` — LOD setup
+- `debugging/debug/SKILL.md` — bug triage (related but different)
+- `rendering-and-lighting/baked-vs-realtime-lighting/SKILL.md` — bake decisions

package/skills/rendering-and-lighting/art-direction/SKILL.md

@@ -0,0 +1,284 @@
+---
+name: art-direction
+description: Use when defining the visual style of the game — references, palette, mood, lighting plan, post-processing, do/don't list. Outputs an art bible at `.summer/art-bible.md`. Trigger on "art direction", "art bible", "visual style", "color palette", "what should it look like", "the look".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: rendering-and-lighting
+user-invocable: true
+allowed-tools: Read Grep Glob Write Edit summer_get_project_context summer_project_setting summer_inspect_node summer_set_prop
+paths: [".summer/**", "project.godot", "**/*.tscn"]
+---
+
+# /art-direction — Define the Visual Style
+
+## Overview
+
+A consistent art direction is what makes a low-budget game *look* like a finished game. Most solo devs lose this fight by mixing styles — a toon-shaded character on a photoreal terrain, a pixel UI over a smooth 3D world. This skill builds an art bible the rest of the project obeys: references, palette, mood, lighting plan, post-processing, and a do/don't list. It writes to `.summer/art-bible.md` — the file every rendering / shader / lighting / VFX skill reads later.
+
+**Core principle:** Constraint produces style. A game with **15 colors total** looks more intentional than a game with infinite-color textures. Pick the constraint, then defend it.
+
+## Steps
+
+### 1. Open with references
+
+Ask exactly this:
+
+> Two or three references — games, films, art books, anything visual. What's the vibe?
+
+Don't suggest. Listen. References are the single most reliable signal of what they actually want. If they say one game, ask for one more — single-reference art bibles converge into a clone of that game.
+
+If they freeze, offer 4 axes (not games):
+
+> Pick the one that feels right: a) painterly + warm + handcrafted (Sable, Tunic), b) crisp + saturated + toon (Hi-Fi Rush, Splatoon), c) dark + moody + grounded (Dishonored, Inside), d) lo-fi + nostalgic + crunchy (Dusk, Faith).
+
+### 2. Read the brief if it exists
+
+```
+Read .summer/GameSoul.md
+```
+
+Brief might say "horror" — that constrains palette and lighting. Brief might say "cozy" — that *forbids* harsh contrast. Quote it back:
+
+> Brief is "cozy farming sim". That rules out harsh shadows and saturated reds. Confirming.
+
+### 3. Pin the rendering technique
+
+This is the technique question, not the mood question. Force a choice:
+
+| Technique | When | Pro | Con |
+|---|---|---|---|
+| Toon / cel-shaded | Stylized 3D, expressive characters | Forgiving on textures, ages well | Can feel generic without strong palette |
+| PBR realistic | Grounded sim, horror, military | Lighting does the work | Asset cost is brutal solo |
+| Lo-fi PS1 | Nostalgia, horror, indie cred | Tiny assets, fast iteration | Niche audience appeal |
+| Flat / matte | Minimalist puzzle, casual | Cheapest to author | Limited mood range |
+| Painterly (textured-shaded) | Story-led, fantasy | Distinctive | Requires consistent texture authoring |
+| 2D pixel | Retro, platformer, RPG | Mature pipeline | Animation cost scales fast |
+| 2D hand-drawn | Narrative, indie | Distinctive, expressive | Animation cost extreme |
+
+Ask:
+
+> One technique. Which is it?
+
+If they pick more than one ("PBR characters in a toon world"), name the conflict and force a hierarchy:
+
+> Mixed techniques rarely cohere. If you mean "stylized PBR with toon outlines" — that's one technique (PBR + post-process outline). If you mean "toon characters in a PBR world" — that's two, and they'll fight. Pick one as primary.
+
+### 4. Build the palette
+
+A palette is **6-15 colors** total. Not a vibe, not "warm tones" — actual hex codes. Force it.
+
+Walk:
+
+```
+Primary background — what color does the screen mostly read as?
+Secondary background — second most common?
+Accent — what does the player's eye go to?
+Warning / damage — what reads as bad?
+Reward / pickup — what reads as good?
+UI base — text, frames
+UI emphasis — buttons, callouts
+Skin / character — if applicable
+```
+
+State candidates as hex. For a "cozy farming" game:
+
+```
+#3a4a3a   primary BG (deep moss green)
+#5e6f4f   secondary BG (sage)
+#e6c068   accent (golden wheat)
+#a83e3e   warning (warm red, not pure red)
+#c8a268   reward (warm tan)
+#1f1a16   UI base (warm near-black, NOT pure black)
+#f4ecdf   UI text (cream, NOT pure white)
+#e3b08a   skin warm
+#a8784f   skin cool
+```
+
+Pure white (#ffffff) and pure black (#000000) are almost always wrong — they break the palette. Flag it if the user pitches them.
+
+Ask:
+
+> Palette above. Adjust any, or lock it?
+
+### 5. Define the mood adjectives
+
+Three to five adjectives. Concrete, not vague.
+
+Bad: "cool, atmospheric, immersive."
+Good: "soft, hand-warmed, slightly melancholic, golden-hour."
+
+Ask:
+
+> Three to five adjectives that aren't 'cool' or 'atmospheric'. Pick from concrete sensory words.
+
+### 6. Write the lighting plan
+
+State the plan in one block. For Godot 4.5:
+
+```
+Sun: DirectionalLight3D, color #fff2d9, energy 0.9, angle ~30° (warm low-angle)
+Sky: ProceduralSkyMaterial, sky_top_color #6b88a3, sky_horizon_color #d8b88e
+Ambient: AmbientLight #4a5570, energy 0.15
+Indoor fills: OmniLight3D color #ffd9a8, energy 0.6, range 4m
+NEVER: pure-white DirectionalLight, no ambient, hard cube shadows
+```
+
+For 2D:
+
+```
+Base: CanvasModulate #f4ecdf, gentle warm wash
+Accent: PointLight2D for fireflies / lanterns, color from accent palette
+NEVER: full-bright modulation, no soft falloff
+```
+
+### 7. Define post-processing rules
+
+Godot 4.5 post stack: Glow, SDFGI, SSAO, SSR, Adjustments, Color Correction (LUT). State opinions, not options.
+
+```
+Glow: ON, threshold 0.9, intensity 0.5  (soft bloom on highlights only)
+SDFGI: OFF for vertical-slice scope (perf cost; bake light probes later)
+SSAO: ON, light_affect 0.3 (just enough for grounding)
+SSR: OFF unless we have wet/glass surfaces
+Color correction: Filmic tonemap, slight S-curve LUT toward warm
+Vignette (custom shader): ON, subtle, 0.15 strength
+Chromatic aberration: OFF (overused, looks cheap)
+Film grain: ON only if mood adjective is "lo-fi" or "vintage"
+```
+
+Make these calls. Don't enumerate options.
+
+### 8. Build the do / don't list
+
+This is the contract. Five do's, five don'ts. Specific, enforceable.
+
+```markdown
+## DO
+- All colors come from the palette. New asset? Pick the closest existing color, don't invent.
+- Outline shader on character + interactable props (no outline on environment).
+- Soft shadows (DirectionalLight3D shadow_blur 1.5).
+- Warm key + cool fill — never both warm or both cool.
+- Texture filter: Linear with mipmaps OFF for crunchy near-pixel feel.
+
+## DON'T
+- No pure white (#ffffff). Use #f4ecdf.
+- No pure black (#000000). Use #1f1a16.
+- No realistic photo-textures. All textures must read as "painted" at 1m distance.
+- No procedural sky shaders mid-day with full sun — too generic. Always angle the sun.
+- No chromatic aberration / lens flare / motion blur — they're cheap and date-fast.
+```
+
+### 9. Apply Godot project-level settings
+
+Some art-direction calls translate to `project.godot` settings. Apply them.
+
+**Preferred (Summer MCP):**
+
+```
+summer_project_setting(key="rendering/textures/canvas_textures/default_texture_filter", value="2")  # Linear no mipmaps if pixel-art-ish
+summer_project_setting(key="rendering/environment/defaults/default_clear_color", value="Color(0.227, 0.290, 0.227)")  # palette primary
+summer_project_setting(key="rendering/anti_aliasing/quality/msaa_3d", value="2")  # MSAA 2x for clean edges
+```
+
+If a `WorldEnvironment` node is in the main scene, set its environment defaults to match the lighting plan:
+
+```
+summer_inspect_node(path="./World/WorldEnvironment")
+summer_set_prop(path="./World/WorldEnvironment/...", key="...", value="...")
+```
+
+Ask before each:
+
+> May I update `project.godot`'s default clear color to the palette primary, and enable MSAA 2x?
+
+**Fallback (no MCP):** print the `project.godot` snippet for the user to paste.
+
+### 10. Save the art bible
+
+Always write the bible. Path: `.summer/art-bible.md`.
+
+```markdown
+# Art Bible — <Game Name>
+
+**References:** <2-3 specific games / films>
+**Technique:** <one of the 7 above>
+**Mood:** <3-5 concrete adjectives>
+
+## Palette
+| Hex | Role |
+|---|---|
+| #3a4a3a | Primary BG |
+| #5e6f4f | Secondary BG |
+| ... | ... |
+
+## Lighting plan
+- Sun: DirectionalLight3D, color #fff2d9, energy 0.9
+- Sky: ProceduralSkyMaterial top #6b88a3, horizon #d8b88e
+- Ambient: #4a5570 energy 0.15
+- Indoor fills: OmniLight3D color #ffd9a8 range 4m
+- NEVER: pure-white sun, no ambient
+
+## Post-processing
+- Glow: ON, threshold 0.9
+- SDFGI: OFF (vertical-slice scope)
+- SSAO: ON, 0.3
+- SSR: OFF
+- Tonemap: Filmic
+- Vignette: subtle 0.15
+- Chromatic aberration: OFF
+
+## DO
+- ...
+
+## DON'T
+- ...
+```
+
+Ask:
+
+> May I create `.summer/art-bible.md` with this bible?
+
+### 11. Route to the next step
+
+End with:
+
+> Bible saved. Next:
+> - `/summer:audio-direction` to define the sonic identity that pairs with this look.
+> - `/summer:vfx` to design particle / hit-feedback styles within the palette.
+> - Open the project's `WorldEnvironment` node and dial in the lighting plan.
+> - Or generate first-pass concept assets via `summer_generate_image` using the palette + mood as the prompt prefix.
+
+## Common mistakes
+
+| Mistake | Fix |
+|---|---|
+| Vague palette ("warm tones") | Hex codes only. 6-15 of them. Locked. |
+| Pure white / pure black | Off-white (#f4ecdf) and off-black (#1f1a16). Pure values blow out the palette. |
+| Single reference | At least two references. Single = clone. |
+| Mixing techniques | Toon characters in a PBR world fight. Pick one technique, stick to it. |
+| No "DON'T" list | The DON'T list is the actual contract. The DO is aspirational. |
+| Chromatic aberration / motion blur | Cheap, overused, date-fast. Off by default. |
+| Procedural skybox without angle | Mid-day sun + uniform fog reads generic. Always angle the sun. |
+| Skipping the lighting plan | Lighting *is* art direction in 3D. Without a plan, every level looks different. |
+| Adopting "AAA realism" at vertical-slice scope | Asset cost is brutal solo. Stylized always wins. |
+| Calling SetResourceProperty on inline sub_resources | Silent fail. See `_shared/mcp-tools-reference.md` § Trap. |
+
+## Collaborative protocol
+
+This skill writes one design doc (`.summer/art-bible.md`) and may modify `project.godot` settings + the main scene's `WorldEnvironment`. Always ask. See `_shared/collaborative-protocol.md`.
+
+## Want a working starter?
+
+No template — this is a workflow that produces the bible the rest of the project obeys. After the bible exists, every `summer:` rendering / lighting / shader / VFX skill reads it.
+
+## See also
+
+- `_shared/collaborative-protocol.md`
+- `_shared/godot-version.md` — Godot 4.5 rendering API notes (Compositor moved in 4.4 / 4.5)
+- `_shared/mcp-tools-reference.md`
+- `scene-and-project/brainstorm-game/SKILL.md` — produces the brief that anchors the bible
+- `audio/audio-direction/SKILL.md` — the sonic counterpart
+- `rendering-and-lighting/3d-lighting/SKILL.md` — implements the lighting plan
+- `shaders/shader-basics/SKILL.md` — for outline / toon shaders
+- `post-processing/bloom-and-glow/SKILL.md` — implements the glow rule
+- `post-processing/color-grading/SKILL.md` — implements the LUT and tonemap call