summer-engine 3.3.0 → 3.4.0

package/library/references/mcp-tools-reference/mcp-tools-reference.md

@@ -17,7 +17,7 @@
 
 **Rule of thumb:** project reads/writes go through Summer; live hierarchy/inspector changes use scene tools; process-level work remains with the host.
 
-## Tool surface (104 tools)
+## Tool surface (105 tools)
 
 ### Project files (4)
 
@@ -237,7 +237,7 @@ Preview. One fast, read-only call that walks every node of a 3D scene and lists
 | `summer_get_project_context` | Project, scene, and `.summer` memory summary — call at start of session. Binds the session to the open project and surfaces a `capabilitySkewWarning` when the engine build and CLI have drifted; tools whose op the engine provably lacks return a structured `engine_lacks_op` result instead of running. Compact by default (a few KB: `sceneSummary`, scalar `health` with capability counts); `include:['scene_tree','capabilities','settings']` adds the heavy blocks, `omitted` says how. |
 | `summer_get_agent_playbook` | Daily operating contract (observe-first loop, content routing, invariants, verification ritual) — call at start of session. Also served natively as the `summer_agent_playbook` MCP prompt. |
 
-### Creator platform (5)
+### Creator platform (7)
 
 | Tool | Use |
 |---|---|
@@ -247,6 +247,7 @@ Preview. One fast, read-only call that walks every node of a 3D scene and lists
 | `summer_creator_publish` | **Deprecated** (use the two tools above). Compute the exact `.pck` digest and size, require user confirmation, then run versioned prepare → write-once upload → finalize. The server independently verifies `publish` scope, ownership, bytes, and review state. |
 | `summer_creator_releases` | List real creator-owned releases from `summer.creator.v1`, with opaque cursor pagination. |
 | `summer_creator_config` | Read or confirm updates to the shared non-secret `~/.summer/config.json`. It never accepts or returns tokens. |
+| `summer_capture_gameplay` | Real gameplay frames without a running editor: starts the game (main scene or `scene`) in the engine's offscreen verify instance (`--summer-verify`, real renderer, window parked offscreen, no focus) at `resolution` (default `1920x1080`), waits `waitSeconds`, saves `frames` PNGs (HUD included) to `<project>/.summer/captures/<time>/`. Imports the project first when `.godot/` is missing. Returns each path with its real width and height; warns when the stretch settings render another size. For store screenshots. |
 
 ### Library search (2)
 

package/library/skills/README.md

@@ -1,6 +1,6 @@
 # Summer skills
 
-> 116 skills, grouped by their primary domain. **Generated** by `npm run generate:registry` from each skill's `resource.yaml`; `--check` fails when this file and the library disagree. Do not edit by hand.
+> 118 skills, grouped by their primary domain. **Generated** by `npm run generate:registry` from each skill's `resource.yaml`; `--check` fails when this file and the library disagree. Do not edit by hand.
 
 The folder is flat on purpose (`docs/design/DECISIONS.md`, D3): a skill usually belongs to several domains, so categories live in each skill's `facets.domains` and this index is rendered from them. The first domain listed is the primary one. `summer skills list --by-domain` prints the same grouping; `summer skills info <slug>` shows one skill.
 
@@ -10,7 +10,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 
 - [2d](#2d) (10)
 - [3d](#3d) (6)
-- [agent-workflow](#agent-workflow) (17)
+- [agent-workflow](#agent-workflow) (18)
 - [ai](#ai) (2)
 - [animation](#animation) (7)
 - [assets](#assets) (3)
@@ -24,7 +24,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 - [multiplayer](#multiplayer) (16)
 - [navigation](#navigation) (1)
 - [performance](#performance) (1)
-- [rendering](#rendering) (5)
+- [rendering](#rendering) (6)
 - [runtime](#runtime) (1)
 - [scenes](#scenes) (12)
 - [scripting](#scripting) (2)
@@ -62,6 +62,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 
 | skill | when to use | also |
 |---|---|---|
+| [*bounded-engine-runs*](./bounded-engine-runs/SKILL.md) ★ (preview) | Run Summer headless or offscreen safely from an agent: time limits, one engine per project, muted runs, import passes, tests that fail on crashes. | headless, verification |
 | [brainstorming](./brainstorming/SKILL.md) ★ | Explore user intent, requirements, and design before implementation — must run before any creative work: features, components, mechanics, behavior. | game-design |
 | [debugging-game-feel](./debugging-game-feel/SKILL.md) | Debug features that work but feel wrong — floaty jumps, mushy combat, sluggish camera — subjective bugs living in tuning, timing, and feedback layers. | gameplay |
 | [diagnosing-perf-regressions](./diagnosing-perf-regressions/SKILL.md) | Find why frame rate, frame time, or load time got worse since a known-good state — regression hunting, not general performance tuning. | performance |
@@ -152,7 +153,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 | [*celeste-momentum-platforming*](./celeste-momentum-platforming/SKILL.md) (preview) | Celeste-style 2D precision platformer movement — momentum running, coyote time, variable jumps, dash, wall jump/slide, climb stamina, pixel corner correction. | character-controller, game-design |
 | [*combat-basics*](./combat-basics/SKILL.md) (preview) | Damage in Summer Engine: hitbox and hurtbox Areas on opposing layers, a reusable Health component, damage signals, knockback, hit feedback, projectiles. | scripting, game-design |
 | [design-mechanic](./design-mechanic/SKILL.md) ★ | Design one game mechanic in detail — input, response, feedback, failure modes, depth, tunables — outputs a design doc, node-graph sketch, GDScript stub. | game-design |
-| [*in-game-purchases*](./in-game-purchases/SKILL.md) (preview) | Sell items for Sparks and let short players buy Sparks in game via the Summer purchase sheet: checkout, Sparks purchase, results, testing, store policy. | scripting, game-design |
+| [*in-game-purchases*](./in-game-purchases/SKILL.md) (preview) | Sell items for Sparks in a game shop via the Summer purchase sheet: checkout, results, not enough Sparks, inventory unlocks, authority grants, store policy. | scripting, game-design |
 | [*web-and-touch-input*](./web-and-touch-input/SKILL.md) ★ (preview) | Input for the browser and phones: the first-click rule for sound and mouse capture, focus, and touch buttons or a virtual stick on the same actions. | ui |
 
 ## level-design
@@ -201,6 +202,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 |---|---|---|
 | [3d-lighting](./3d-lighting/SKILL.md) ★ | Set up 3D scene lighting — DirectionalLight3D vs Omni vs Spot, WorldEnvironment, sky, shadow tuning, ambient — per current Summer conventions. | lighting |
 | [art-direction](./art-direction/SKILL.md) ★ | Define the game's visual style — references, palette, mood, lighting plan, post-processing, do/don't list — output as an art bible at .summer/art-bible.md. | lighting |
+| [*compatibility-renderer-traps*](./compatibility-renderer-traps/SKILL.md) ★ (preview) | Make a Forward+ Summer game also look right on the Compatibility renderer: instance-uniform budget, black MultiMesh colors, sRGB vertex colors. | performance |
 | [*psx-retro-rendering*](./psx-retro-rendering/SKILL.md) (preview) | Hardware-informed PlayStation 1 rendering in Godot 4 — low-res output, RGB5 and exact dither, affine textures, vertex snapping, blend modes, fog; limits named. | 3d |
 | [*realtime-wet-surfaces*](./realtime-wet-surfaces/SKILL.md) (preview) | Real-time wetness on existing Godot 4 materials without losing their values — value-copying wet shader, geometry-driven wet mask, instance-uniform wet amount. | vfx |
 | [*web-compatibility-look*](./web-compatibility-look/SKILL.md) ★ (preview) | Make a web or browser game look high-end in the Compatibility renderer (WebGL 2): what works, what to avoid, 2D and 3D recipes, web performance. | 2d, 3d |

package/library/skills/bounded-engine-runs/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: bounded-engine-runs
+description: "Run Summer headless or offscreen safely from an agent: time limits, one engine per project, muted runs, import passes, tests that fail on crashes."
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: workflow
+user-invocable: true
+allowed-tools: Read Grep Glob Edit Write Bash
+paths: ["project.godot", "tests/**/*.gd", "tools/**/*.gd"]
+---
+
+# Bounded engine runs for agents
+
+Agents verify games by running the engine many times: imports, tests, captures, multiplayer bots. Each run
+that hangs, overlaps another, makes noise or hides an error costs time and trust. These rules come from a
+day of several agents sharing one project on one Mac.
+
+## 1. Every run is bounded, muted and alone
+
+- **Bound it.** macOS has no `timeout`. Wrap runs so the engine itself gets killed:
+  ```sh
+  perl -e 'alarm shift; exec @ARGV' 180 <summer> --headless --path . -s res://tests/run_tests.gd
+  ```
+  `alarm` survives `exec`; exit code 142 means the limit hit.
+- **One engine per project at a time.** Two engines writing the same `.godot/` import cache corrupt it or
+  freeze each other's captures. Serialize with a lock file held by the engine process:
+  ```sh
+  perl -e 'use Fcntl qw(:flock); $^F=255; open(my $l,">>",shift) or die; flock($l,LOCK_EX); alarm shift; exec @ARGV' \
+    <project>/.engine.lock 180 <summer> ...
+  ```
+  Put this in one wrapper script and make every agent use it.
+- **Cap its memory.** A time limit does not stop a run from eating all memory first. One day of several agents
+  running builds, renders and a browser load of a large web export at once kernel-panicked the Mac
+  (compressor full, swap unable to grow). The wrapper should run the command as a child, sum the resident
+  memory of its whole process tree (browsers spawn GPU/renderer helpers), kill the tree past a cap (e.g.
+  3 GB), and also stop when system free memory falls low (`sysctl -n kern.memorystatus_level` < 15 on macOS),
+  because GPU memory on Apple Silicon is system memory but is not counted in RSS. Refuse to start when the
+  system is already short (< 35).
+- **Mute it.** `--audio-driver Dummy`. Someone is working next to you.
+- **Render only when you must, and offscreen.** `--headless` for logic (no pixels). For visual checks use
+  `--summer-offscreen` with a fixed `--resolution` and a capture script that saves PNGs and quits. Visible
+  windows only when a human asked to watch.
+
+## 2. Imports and parse errors
+
+- New `class_name` scripts are unknown to `-s` scripts until an import pass registers them:
+  `<summer> --headless --audio-driver Dummy --path . --import`.
+- The first import may rewrite `project.godot` (reorder keys, add a `[summer]` section; one trial saw a
+  hand-written `[rendering]` section dropped). Check `git diff project.godot` after it, and pass renderer
+  choices on the command line (`--rendering-method ...`) when a run depends on them.
+- One broken `class_name` script cascades into "Could not parse global class" and dozens of unrelated
+  "cannot infer type" errors. Get the real line with:
+  `<summer> --headless --path . --check-only -s res://path/to/file.gd`
+- Compile every script before booting the game: a tiny `SceneTree` script that `load()`s each `.gd` under
+  a folder and reports `can_instantiate()` failures, exit code = failures.
+
+## 3. Tests that can't lie
+
+- A runtime script error inside a test does not fail it by default; the test just stops and counts as
+  passed. Register a logger and fail the test when its error count rises:
+  ```gdscript
+  class ErrorCounter extends Logger:
+  	var script_errors := 0
+  	func _log_error(_f: String, file: String, _line: int, _c: String, _r: String, _n: bool, type: int, _bt: Array[ScriptBacktrace]) -> void:
+  		if type == Logger.ERROR_TYPE_SCRIPT or file.ends_with(".gd"):
+  			script_errors += 1
+  	func _log_message(_m: String, _e: bool) -> void:
+  		pass
+  # in the runner: OS.add_logger(counter); compare counter.script_errors before and after each test
+  ```
+- Exit 0 is not success. Always grep the log for `SCRIPT ERROR`, `Parse Error` and `ERROR:`, and print
+  one explicit success line (`TESTS passed=N failed=0`) you can check for.
+
+## 4. Typed GDScript traps agents hit repeatedly
+
+- `var x := dict["k"]` cannot infer a type (Dictionary values are Variant). Write `var x: int = dict["k"]`.
+- A loop variable that shadows an outer variable is a parse error that takes the whole class down.
+- Don't name a class after an engine class (`SummerSession`); the error only says it "hides a native class".
+
+## 5. Web exports on a dev machine
+
+- Check the `.pck` size before opening it in a browser; the browser holds all of it in memory. A project that
+  exports every imported asset of a large scene can pass 250 MB. Ship only what the game uses first.
+- Load it in a browser only under the same memory-capped wrapper, one at a time, never next to other engine runs.
+
+## 6. Captures you can trust
+
+- Read every PNG you produce. If several files are identical (`md5 -r *.png`), the run froze; rerun alone.
+- Keep evidence outside the project (logs, PNGs) so imports never pick it up. If it must live inside, put an
+  empty `.gdignore` file in that folder so the editor and imports skip it.
+
+## See also
+
+- `headless-scripting` (writing the SceneTree scripts these runs execute)
+- `multiplayer-testing` (Local Play bot runs)
+- `compatibility-renderer-traps` (dual-renderer captures)

package/library/skills/bounded-engine-runs/resource.yaml

@@ -0,0 +1,29 @@
+id: skill/bounded-engine-runs
+kind: skill
+version: 1.0.0
+summary: "Run Summer headless or offscreen safely from an agent: time limits, one engine per project, muted runs, import passes, tests that fail on crashes."
+use_when:
+  - running the engine from a shell or agent for tests, imports, captures or bots
+  - several agents or processes share one project
+  - a run hangs, a capture freezes, or errors cascade across unrelated scripts
+facets:
+  lifecycle:
+    - build
+  domains:
+    - agent-workflow
+    - headless
+    - verification
+  modalities:
+    - project
+    - scripts
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/headless-scripting
+    - skill/multiplayer-testing
+    - skill/compatibility-renderer-traps
+source: official
+license: MIT
+status: preview
+recommended: true

package/library/skills/compatibility-renderer-traps/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: compatibility-renderer-traps
+description: "Make a Forward+ Summer game also look right on the Compatibility renderer: instance-uniform budget, black MultiMesh colors, sRGB vertex colors."
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: rendering-and-lighting
+user-invocable: true
+allowed-tools: Read Grep Glob Edit Write summer_project_setting summer_get_script_errors
+paths: ["**/*.gdshader", "**/*.gdshaderinc", "**/*.gd", "project.godot"]
+---
+
+# Forward+ and Compatibility without surprises
+
+Games built on Forward+ can end up on the Compatibility renderer (OpenGL): phones where Metal/Vulkan is
+unavailable, weak GPUs, or a project that picks it for battery. The failures are silent: no error, just
+black fruit, pale colors, or objects that stop animating after the first few hundred. These are the traps
+that cost real renders in a shipped-quality game, each with the fix and the reason.
+
+## 1. Know which renderer you actually got
+
+- Phones use `rendering/renderer/rendering_method.mobile`, which defaults to `mobile`, not Forward+.
+  Set it explicitly.
+- A device can fall back to another renderer when it lacks a capability. Trust the renderer name printed
+  at startup (or `RenderingServer.get_current_rendering_method()`), not the project setting.
+- Preview Compatibility on your computer:
+  `<summer> --path . --rendering-method gl_compatibility`.
+
+## 2. The traps
+
+| Symptom on Compatibility | Cause | Fix |
+|---|---|---|
+| Objects past roughly the 250th stop growing, lose color or read as default | GLES3 reserves 16 `instance uniform` slots per instance out of 4096, so only about 256 instances in the whole scene can use them. Beyond that, values silently read 0. | Don't use `instance uniform` for anything numerous. Put per-instance state in a one-instance MultiMesh's `INSTANCE_CUSTOM` (a vec4), or bake it into mesh vertex colors. |
+| Fruit/flowers render solid black | GLES3 multiplies `COLOR` by the MultiMesh instance color, which is 0 when `use_colors` is off. | Enable `use_colors` and set every instance color to white, or don't read `COLOR` in that path. |
+| Everything looks pastel on Forward+ (saturated on Compatibility) | Forward+ shades in linear space, Compatibility in sRGB. Colors you bake into vertex `COLOR` or hard-code into `ALBEDO` are usually sRGB. | Convert once, only where needed: `if (!OUTPUT_IS_SRGB) col = to_linear(col);` with the helper below (the shading language has no built-in `srgb_to_linear`). Or pass colors as `uniform vec3 c : source_color`, which converts for you. |
+| Whole scene pale/lime on Compatibility while Forward+ looks right | Tonemap, glow and ambient respond differently. | Keep a Compatibility branch of your lighting profile (lower ambient and exposure) and check both. |
+| Foliage glows white | Glow threshold too low for bright leaves. | Raise the glow HDR threshold (~1.5) and keep bloom near 0. |
+
+Everything the player must see (ripe crop, enemy, pickup) must stay readable without glow, SSR,
+volumetric fog or other Forward+-only effects: use shape, color and icons too.
+
+The helper (standard sRGB curve):
+
+```glsl
+vec3 to_linear(vec3 c) {
+	return mix(pow((c + vec3(0.055)) * (1.0 / 1.055), vec3(2.4)), c * (1.0 / 12.92), lessThan(c, vec3(0.04045)));
+}
+```
+
+## 3. Keep one shader path
+
+Write shaders in plain spatial math: vertex-color ramps, simple rim terms, no custom `light()` unless
+you test it on both renderers. One path for both renderers means one set of bugs and no drift.
+
+## 4. Verify, don't assume
+
+1. Render the same scene on Forward+ and `gl_compatibility` offscreen:
+   `<summer> --audio-driver Dummy --summer-offscreen --path . --resolution 1600x900 -s res://tools/capture.gd -- --out=<dir>`
+   (add `--rendering-method gl_compatibility` for the second run).
+2. Read both images side by side, and include a stress shot with many instances (the 256 limit only shows
+   at scale).
+3. Grep the log for `SCRIPT ERROR`, `SHADER ERROR` and `ERROR:`. A shader that fails to compile still lets
+   the capture exit 0 and draws the object untextured, so a missing grep hides the failure.
+4. If later captures repeat the same frame, the offscreen run froze (it happens when another engine
+   renders at the same time). Check with `md5 -r *.png` and rerun alone.
+
+## Common mistakes
+
+- Checking only the project setting and calling it "Forward+ on phones".
+- Using `instance uniform` for per-plant or per-tile state.
+- Reading `COLOR` from a MultiMesh without instance colors.
+- Testing Compatibility with ten objects when the game shows five hundred.
+- Budgeting one run per fix: every look change needs two captures (one per renderer). Plan runs in pairs.
+
+## See also
+
+- `web-compatibility-look` (a finished look when the game only runs on Compatibility, as on the web)
+- `3d-lighting` (lighting profiles)
+- `bounded-engine-runs` (safe offscreen capture runs)

package/library/skills/compatibility-renderer-traps/resource.yaml

@@ -0,0 +1,28 @@
+id: skill/compatibility-renderer-traps
+kind: skill
+version: 1.0.0
+summary: "Make a Forward+ Summer game also look right on the Compatibility renderer: instance-uniform budget, black MultiMesh colors, sRGB vertex colors."
+use_when:
+  - a game must run on phones or weak GPUs that may use the Compatibility or Mobile renderer
+  - objects render black, pale or stop animating on one renderer but not another
+  - writing shaders for many instances (crops, foliage, tiles) that must work everywhere
+facets:
+  lifecycle:
+    - build
+  domains:
+    - rendering
+    - performance
+  modalities:
+    - shaders
+    - scripts
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/web-compatibility-look
+    - skill/3d-lighting
+    - skill/bounded-engine-runs
+source: official
+license: MIT
+status: preview
+recommended: true

package/library/skills/concept-art/SKILL.md

@@ -77,7 +77,7 @@ summer_generate_image(
 
 `style: "none"` is intentional, but be precise about why: only `cartoon` and `anime` append anything to the prompt, `realistic` and `none` append nothing, and any other value is coerced to `none`. So the preset cannot override the prompt's stylistic direction — it just contributes nothing, which is what concept art wants. All four variants' divergence has to come from the prompt.
 
-There is no `image_size` argument, and `options` only recognizes Nano Banana provider keys plus `removeBackground` — an unrecognized key is dropped without an error. Every MCP image comes back at the server's 1:1 default. For wide key art, ask for "wide cinematic framing" in the prompt and accept the square canvas, or generate in the Summer dashboard where aspect ratio is exposed. Since these are exploration images the user reacts to and throws away, square is usually fine.
+For a shape other than square, pass `aspectRatio` (`"16:9"`, `"9:16"`, ...) or `width` + `height`; the result reports the real width and height and the model that ran. Exploration images are thrown away, so square is usually fine.
 
 ### 5. Present the batch
 
@@ -121,7 +121,7 @@ The structure: **subject + axis variant + "concept art" + lighting/atmosphere**.
 
 - **User says "just one" after you propose 4.** That's a `character-portrait` job. Hand off.
 - **User wants 8+ variants.** Generate 4 first; if the user wants more on the same axis, generate 4 more. Don't dump 8 at once — overload paralyzes choice.
-- **Subject is a fully described scene, not an asset.** You're producing key art, not asset reference. Ask for wide cinematic framing in the prompt and bias toward atmospheric — you cannot set an aspect ratio over MCP.
+- **Subject is a fully described scene, not an asset.** You're producing key art, not asset reference. Pass `aspectRatio: "16:9"` (or `width: 1920, height: 1080` for store key art) and bias toward atmospheric.
 - **User wants the final to be 3D.** After they pick a direction, route to `asset-strategy` — concept-art images are not 3D-ready references (they have backgrounds, scene context, dramatic lighting baked in). The 3D pipeline needs its own clean white-background reference.
 
 ## Fallback (no MCP)

package/library/skills/export-and-ship/SKILL.md

@@ -293,6 +293,8 @@ Per platform, point the user at the correct upload path:
 
 - **summer.games:** `summer_export_game` writes the summer.games `.zip`; `summer_publish_build` uploads it to the game's store listing after the user confirms the exact game, file and version (needs `summer login --store`). If it answers `store_auth_refused`, the user uploads the `.zip` in Studio instead.
   - Per platform, the store takes: iPhone, Android, macOS and Windows in the Summer apps = one summer.games bundle (`summer_export_game` `targets`, format `bundle`; no template, no signing; a game without a server targets `ios`/`android` only). Web = an HTML5 `.zip` on Summer's WebGPU Forward+ template (`targets:["web"]`; the project must render with Forward+ or Mobile). A macOS or Windows download for the store page = `targets:["macos"]` or `["windows"]` with format `download`. Download exports need the template: `summer_export_templates` `install` fetches it from Summer's CDN.
+  - Hosted games: if `summer_export_game` fails with "… is in the source graph's authority_engine domain, which the client pack leaves out", an authority root in `source-domains.json` holds a file the client loads (often the composition `.tres`). Narrow that root to the server-only files, or move the shared file under a `shared` path, then export again. Every exporter message is in the `multiplayer-publish` skill's export-errors.md; the folder rules are in `multiplayer-project`.
+  - Store page art: key art, covers and icons carry no text, logos or UI (the store page shows the title). Screenshots are real gameplay and may show the game's own HUD; add no captions, logos or overlays. Capture them with `summer_capture_gameplay` (offscreen, no editor needed; `resolution` `1920x1080`, or `1080x1920` for portrait; pass the gameplay `scene` when the main scene is a title menu), or `summer_screenshot` target `game` while the editor runs the game.
 - **Steam:** `steamcmd` + Steam Pipe (`builder_app_xxx.vdf`). Set up depots first in Steamworks.
 - **itch.io:** `butler push <path> <user>/<game>:<channel>` (e.g. `butler push build/win <user>/mygame:windows`).
 - **Web (itch hosted):** zip + drop into itch upload UI as "playable in browser".

package/library/skills/headless-scripting/resource.yaml

@@ -18,6 +18,7 @@ compatibility:
 related:
   skills:
     - skill/scene-scripting
+    - skill/bounded-engine-runs
 source: official
 license: MIT
 status: stable