summer-engine 3.5.1 → 3.6.0

package/dist/mcp/provider-safe-schema.js

@@ -0,0 +1,96 @@
+import { ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+/** String formats OpenAI strict mode accepts; other providers accept no more. */
+export const STRICT_PROVIDER_FORMATS = new Set(["date-time", "time", "date", "duration", "email", "hostname", "ipv4", "ipv6", "uuid"]);
+// Where a schema holds subschemas: one, a list, or a name -> schema map.
+const SCHEMA_KEYS = new Set(["items", "additionalItems", "additionalProperties", "contains", "not", "if", "then", "else", "propertyNames", "unevaluatedItems", "unevaluatedProperties"]);
+const SCHEMA_LIST_KEYS = new Set(["anyOf", "oneOf", "allOf", "prefixItems"]);
+const SCHEMA_MAP_KEYS = new Set(["properties", "patternProperties", "dependentSchemas", "$defs", "definitions"]);
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function resolvePointer(root, ref) {
+    let node = root;
+    for (const raw of ref.slice(2).split("/")) {
+        if (raw === "")
+            continue;
+        const key = raw.replace(/~1/g, "/").replace(/~0/g, "~");
+        if (Array.isArray(node))
+            node = node[Number(key)];
+        else if (isObject(node))
+            node = node[key];
+        else
+            return undefined;
+    }
+    return node;
+}
+function uniqueSchemas(schemas) {
+    const seen = new Map();
+    for (const schema of schemas)
+        seen.set(JSON.stringify(schema), schema);
+    return [...seen.values()];
+}
+function rewrite(schema, root, expanding) {
+    if (!isObject(schema))
+        return schema;
+    const child = (value) => rewrite(value, root, expanding);
+    const { $ref, ...rest } = schema;
+    if (typeof $ref === "string" && ($ref === "#" || $ref.startsWith("#/"))) {
+        // A recursive shape cannot be inlined; accept any value there and let zod validate it.
+        const target = expanding.includes($ref) ? {} : rewrite(resolvePointer(root, $ref), root, [...expanding, $ref]);
+        return { ...(isObject(target) ? target : {}), ...child(rest) };
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(schema)) {
+        if (key === "additionalItems" || key === "prefixItems")
+            continue;
+        if (SCHEMA_KEYS.has(key))
+            out[key] = Array.isArray(value) ? value.map(child) : child(value);
+        else if (SCHEMA_LIST_KEYS.has(key) && Array.isArray(value))
+            out[key] = value.map(child);
+        else if (SCHEMA_MAP_KEYS.has(key) && isObject(value))
+            out[key] = Object.fromEntries(Object.entries(value).map(([name, sub]) => [name, child(sub)]));
+        else
+            out[key] = value;
+    }
+    if (Array.isArray(schema.type) && !("anyOf" in out)) {
+        delete out.type;
+        out.anyOf = schema.type.map((type) => ({ type }));
+    }
+    if (typeof out.format === "string" && !STRICT_PROVIDER_FORMATS.has(out.format))
+        delete out.format;
+    if (isObject(out.propertyNames) && Object.keys(out.propertyNames).length === 1 && out.propertyNames.type === "string")
+        delete out.propertyNames;
+    const tuple = Array.isArray(schema.prefixItems) ? schema.prefixItems : Array.isArray(schema.items) ? schema.items : null;
+    if (tuple) {
+        const extra = Array.isArray(schema.prefixItems) ? schema.items : schema.additionalItems;
+        const open = extra !== undefined && extra !== false;
+        const members = uniqueSchemas([...tuple, ...(isObject(extra) ? [extra] : [])].map(child));
+        out.items = members.length === 1 ? members[0] : members.length === 0 ? {} : { anyOf: members };
+        out.minItems ??= tuple.length;
+        if (!open)
+            out.maxItems ??= tuple.length;
+    }
+    return out;
+}
+export function providerSafeSchema(schema) {
+    const out = rewrite(schema, schema, []);
+    if (isObject(out)) {
+        // Every local $ref is inlined, so the definition tables are dead weight.
+        delete out.definitions;
+        delete out.$defs;
+    }
+    return out;
+}
+/**
+ * Wrap the SDK's tools/list so every tool's inputSchema leaves the server in
+ * the provider-safe form. Call after the first registerTool (the SDK installs
+ * its tools/list handler then).
+ */
+export function serveProviderSafeToolSchemas(server) {
+    const handlers = server.server._requestHandlers;
+    const listTools = handlers.get("tools/list");
+    if (!listTools)
+        return;
+    server.server.setRequestHandler(ListToolsRequestSchema, async (request, extra) => {
+        const result = await listTools(request, extra);
+        return { ...result, tools: result.tools.map((tool) => ({ ...tool, inputSchema: providerSafeSchema(tool.inputSchema) })) };
+    });
+}

package/dist/mcp/server.js

@@ -27,6 +27,7 @@ import { registerLibraryTools } from "./tools/library-tools.js";
 import { getCachedBootDriftNotice as getCachedNotice, setCachedBootDriftNotice, } from "./boot-notice.js";
 import { appendMcpLogEvent } from "../core/mcp-log.js";
 import { prepareHostedMount } from "./hosted-mount.js";
+import { serveProviderSafeToolSchemas } from "./provider-safe-schema.js";
 import { buildBootDriftNotice, fetchLatestRegistryVersion, } from "../installer/version-check.js";
 import { TOOLKIT_VERSION as version } from "../core/version.js";
 let processDiagnosticsInstalled = false;
@@ -329,6 +330,8 @@ export function createMcpServer() {
     // The playbook is also an MCP prompt so prompt-surfacing hosts get it
     // natively (same content as the summer_get_agent_playbook tool).
     registerPlaybookPrompt(server);
+    // Strict providers (Kimi, OpenAI strict) reject tuple and $ref schemas.
+    serveProviderSafeToolSchemas(server);
     return { server, getRegisteredToolCount };
 }
 export async function startMcpServer(options = {}) {

package/dist/mcp/tools/generate-tools.js

@@ -2,6 +2,8 @@ import { z } from "zod";
 import { BOARD_ENDPOINT, boardArgsSchema, boardContent, boardQuery } from "../../core/capabilities/board.js";
 import { IMAGE_GENERATION_TIMEOUT_MS, imageGenerationArgsSchema, saveGeneratedImage } from "../../core/capabilities/image-generation.js";
 import { buildMotionRequestBody, motionErrorHint, motionGenerationArgsSchema, motionJobFailureHint, } from "../../core/capabilities/motion-generation.js";
+import { MAX_CHOICES_WAIT_SECONDS, defaultCanOpenBrowser, generateSfxChoices, getChoices, getChoicesArgsSchema, openInStudioTab, sfxChoicesArgsSchema, SFX_CHOICES_ENDPOINT, } from "../../core/capabilities/sfx-choices.js";
+import open from "open";
 import { getAuthToken } from "../../core/auth.js";
 import { resolveGatewayUrl } from "../../core/config.js";
 import { readJsonResponse } from "../../core/util/http.js";
@@ -10,6 +12,7 @@ import { TOOLKIT_VERSION as CLI_VERSION } from "../../core/version.js";
 const TOOL_BY_ENDPOINT = {
     "/api/mcp/generate/image": "summer_generate_image",
     "/api/mcp/generate/audio": "summer_generate_audio",
+    [SFX_CHOICES_ENDPOINT]: "summer_generate_sfx_choices",
     "/api/mcp/generate/3d": "summer_generate_3d",
     "/api/mcp/generate/video": "summer_generate_video",
     "/api/mcp/generate/motion": "summer_generate_motion",
@@ -356,10 +359,21 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
 
 Capabilities:
   - "text_to_speech" — Convert text to spoken audio. Requires 'text'. Optional 'voiceId'.
-  - "sound_effects" — Generate sound effects from description. Requires 'text'. Optional 'durationSeconds'.
+  - "sound_effects" — Generate sound effects from description. Requires 'text'. Optional 'durationSeconds', 'modelId', 'loop'.
   - "music" — Generate background music. Requires 'prompt'. Optional 'durationSeconds'.
   - "text_to_dialogue" — Multi-voice dialogue. Requires 'inputs' array of {text, voiceId} objects.
 
+Sound-effect models (modelId; omit it to use the person's approved default,
+else ElevenLabs):
+  - "eleven_text_to_sound_v2" — ElevenLabs SFX v2. Strong all-rounder, 0.5-30 s,
+    the only one that makes seamless loops (loop: true).
+  - "sonilo-sfx-1.1" — Sonilo SFX 1.1. Strong all-rounder, >= 0.5 s.
+  - "stable-audio-3-sfx" — Stable Audio 3 SFX. Sometimes best on fast movement
+    (swings, whooshes), less consistent; >= 1 s.
+The best model changes a lot from one sound to the next. For the first sound
+effect in a chat, offer the person three versions to pick from by ear:
+summer_generate_sfx_choices.
+
 The 'options' object is spread into the ElevenLabs SDK call at the TOP level, so
 only keys the SDK accepts there have any effect. Voice tuning is NOT top-level and
 is NOT snake_case: pass it as options.voiceSettings with camelCase keys —
@@ -388,11 +402,16 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
         modelId: z
             .string()
             .optional()
-            .describe("ElevenLabs model ID (e.g. 'eleven_multilingual_v2')"),
+            .describe("Model id. text_to_speech: an ElevenLabs model (e.g. 'eleven_multilingual_v2'). " +
+            "sound_effects: eleven_text_to_sound_v2, sonilo-sfx-1.1 or stable-audio-3-sfx; omit to use the person's approved default"),
         durationSeconds: z
             .number()
             .optional()
             .describe("Duration in seconds for SFX or music"),
+        loop: z
+            .boolean()
+            .optional()
+            .describe("sound_effects only: ask for a seamless loop (eleven_text_to_sound_v2 only)"),
         inputs: z
             .array(z.object({ text: z.string(), voiceId: z.string() }))
             .optional()
@@ -403,7 +422,7 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
             .describe("Provider params, spread at the SDK's top level. Voice tuning goes in " +
             "options.voiceSettings with camelCase keys (stability, similarityBoost, " +
             "style, speed, useSpeakerBoost); flat snake_case is silently ignored."),
-    }, async ({ capability, text, prompt, voiceId, modelId, durationSeconds, inputs, options }) => {
+    }, async ({ capability, text, prompt, voiceId, modelId, durationSeconds, loop, inputs, options }) => {
         const body = { capability };
         if (text)
             body.text = text;
@@ -415,6 +434,8 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
             body.modelId = modelId;
         if (durationSeconds)
             body.durationSeconds = durationSeconds;
+        if (loop !== undefined)
+            body.loop = loop;
         if (inputs)
             body.inputs = inputs;
         if (options)
@@ -426,6 +447,52 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
         return successResult(result.data);
     });
     // ========================================================================
+    // summer_generate_sfx_choices + summer_get_choices
+    // Shared implementation: core/capabilities/sfx-choices.ts
+    // ========================================================================
+    const sfxChoicesDeps = {
+        post: (endpoint, body, timeoutMs) => mcpGenerate(endpoint, body, timeoutMs),
+        get: (endpoint, params, timeoutMs) => mcpGet(endpoint, params, timeoutMs),
+        studioOpen: (path, reviewUrl) => openInStudioTab(path, reviewUrl),
+        openUrl: (url) => open(url),
+        canOpenBrowser: () => defaultCanOpenBrowser(),
+    };
+    server.tool("summer_generate_sfx_choices", `Make one sound effect with several models (default three) and show the
+versions to the person on a Summer Studio page, where they listen and approve
+one or more. The approved model becomes their default for sound effects.
+
+Use it for the first sound effect in a chat after the person said yes to
+"three versions to pick from", or whenever they want to compare. The page
+opens in their open Summer Studio tab when there is one (needs the store
+sign-in), else in the browser; open:false only returns reviewUrl.
+
+Then tell the person the returned "say" text and call summer_get_choices
+with the choiceSetId. Do not pick for them.
+
+Models: eleven_text_to_sound_v2 (0.5-30 s, loops), sonilo-sfx-1.1 (>= 0.5 s),
+stable-audio-3-sfx (>= 1 s; give durationSeconds >= 1 when it is included).
+Each version is a billed generation.
+
+Cloud tool — runs on Summer's servers and works WITHOUT the Summer Engine app open.
+Requires authentication: run 'npx -y summer-engine@latest login' first.`, sfxChoicesArgsSchema.shape, async (args) => {
+        const result = await generateSfxChoices(sfxChoicesArgsSchema.parse(args), sfxChoicesDeps);
+        return result.ok ? successResult(result) : errorResult(String(result.error), result);
+    });
+    server.tool("summer_get_choices", `Read a sound-effect choice set from summer_generate_sfx_choices: whether the
+person decided ("pending" or "decided"), which versions they approved (with
+audioUrl, assetId and their note) and their default sound-effect model.
+
+waitSeconds (max ${MAX_CHOICES_WAIT_SECONDS}) waits for the decision before answering; call again
+while status is "pending". Import each approved clip with
+summer_import_from_url (url: audioUrl, path: res://audio/sfx/<name>.<fileExtension>)
+or summer_import_asset_by_id (assetId), then wire it.
+
+Cloud tool — runs on Summer's servers and works WITHOUT the Summer Engine app open.
+Requires authentication: run 'npx -y summer-engine@latest login' first.`, getChoicesArgsSchema.shape, async (args) => {
+        const result = await getChoices(getChoicesArgsSchema.parse(args), sfxChoicesDeps);
+        return result.ok ? successResult(result) : errorResult(String(result.error), result);
+    });
+    // ========================================================================
     // summer_generate_3d
     // ========================================================================
     server.tool("summer_generate_3d", `Generate a 3D model via Summer Engine Studio.

package/gemini-extension.json

@@ -1,7 +1,7 @@
 {
   "_generated": "GENERATED from integrations/gemini — do not edit; npm run generate:registry",
   "name": "summer",
-  "version": "3.5.1",
+  "version": "3.6.0",
   "description": "Agent tooling for Summer Engine: MCP bridge, context primer, and game-dev skills. Use with the npm CLI for skill files on disk.",
   "contextFileName": "GEMINI.md",
   "mcpServers": {
@@ -93,6 +93,7 @@
     "./library/skills/psx-retro-rendering/",
     "./library/skills/publish-your-game/",
     "./library/skills/realtime-wet-surfaces/",
+    "./library/skills/release-readiness/",
     "./library/skills/remote-deploy/",
     "./library/skills/retarget/",
     "./library/skills/running-in-the-cloud/",

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 (105 tools)
+## Tool surface (107 tools)
 
 ### Project files (4)
 
@@ -211,13 +211,15 @@ Preview. One fast, read-only call that walks every node of a 3D scene and lists
 | `summer_import_hdri` | Search Poly Haven's CC0 HDRIs (public API, no Summer login), import the `.hdr`/`.exr` into `res://sky/`, and get the exact `summer_run_script` snippet that wires it as the WorldEnvironment sky. |
 | `summer_slice_asset_sheet` | Detect and crop every distinct asset from a generated sheet image into named individual assets (works without the engine; import the results afterwards). |
 
-### Asset generation (5 — metered)
+### Asset generation (7 — metered)
 
 | Tool | Use |
 |---|---|
 | `summer_generate_image` | AI image gen. |
 | `summer_generate_3d` | Image-to-3D. |
-| `summer_generate_audio` | SFX / music gen. |
+| `summer_generate_audio` | SFX / music gen. Sound effects: `modelId` picks ElevenLabs SFX v2, Sonilo SFX 1.1 or Stable Audio 3 SFX; omitted = the person's approved default. |
+| `summer_generate_sfx_choices` | One sound effect from several models, shown on a Summer Studio page where the person approves one or more. |
+| `summer_get_choices` | Read which sound-effect versions the person approved (audioUrl, assetId, note). |
 | `summer_generate_video` | Video gen. |
 | `summer_generate_motion` | Generate/apply 3D skeletal motion from a rigged asset. |
 

package/library/references/mcp-tools-reference/resource.yaml

@@ -1,6 +1,6 @@
 id: reference/mcp-tools-reference
 kind: reference
-version: 1.4.0
+version: 1.4.1
 summary: Canonical reference for which Summer MCP tool to call — skills should reference tool names exactly as written here.
 use_when:
   - choosing between Summer MCP tools and host tools for an operation

package/library/skills/README.md

@@ -1,6 +1,6 @@
 # Summer skills
 
-> 122 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.
+> 123 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.
 
@@ -18,7 +18,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 - [character-controller](#character-controller) (2)
 - [creator](#creator) (4)
 - [debug](#debug) (1)
-- [deployment](#deployment) (2)
+- [deployment](#deployment) (3)
 - [editor](#editor) (1)
 - [gameplay](#gameplay) (6)
 - [level-design](#level-design) (2)
@@ -117,7 +117,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 | [ambient-bed](./ambient-bed/SKILL.md) | Generate a long looping location ambience — forest, dungeon, city, spaceship, cave — a looping AudioStreamPlayer on the Ambient bus with a seamless loop. | assets |
 | [audio-direction](./audio-direction/SKILL.md) ★ | Define the game's sonic identity — music style, instruments, SFX vocabulary, dynamic music plan — output as an audio bible at .summer/audio-bible.md. | game-design |
 | [music-track](./music-track/SKILL.md) ★ | Generate a looped or cinematic music track — loops authored at >=30s with a marked loop point, cinematic tracks at >=60s linear. | assets |
-| [sound-effect](./sound-effect/SKILL.md) ★ | Generate short SFX one-shots — footsteps, weapon swings, UI clicks, hit impacts — wired as AudioStreamPlayer/2D/3D that auto-frees on finished. | assets |
+| [sound-effect](./sound-effect/SKILL.md) ★ | Make SFX one-shots and timed sequences (swings, hits, whooshes, reloads, UI) - offer three model versions to pick from, then wire them as AudioStreamPlayers. | assets |
 | [voice-line](./voice-line/SKILL.md) ★ | Generate TTS voice lines — NPC barks, narrator, dialogue — with voice-id sourcing, a character-to-voice decision tree, and multi-line dialogue support. | assets |
 
 ## character-controller
@@ -147,6 +147,7 @@ Status: **stable** unless marked; *preview* = not yet exercised in-engine by the
 | skill | when to use | also |
 |---|---|---|
 | [export-and-ship](./export-and-ship/SKILL.md) ★ | Assess and prepare a game export: inventory installed templates and targets, validate release assets and config, produce supported builds after approval. | project |
+| [*release-readiness*](./release-readiness/SKILL.md) (preview) | Before releasing a Summer game version, prove players can play it: server scene, online join, progress, Game ID, released Summer, packed files, app version. | multiplayer, playtest |
 | [remote-deploy](./remote-deploy/SKILL.md) ★ | Run or test the game on a real device — phone, tablet, another computer — via the Remote Deploy button, runnable export presets, and on-device debugging. | project |
 
 ## editor

package/library/skills/ambient-bed/SKILL.md

@@ -103,13 +103,15 @@ If the user wants a busier bed (market, party), still prevent foreground events:
 ```
 summer_generate_audio(
   capability: "sound_effects",
+  modelId: "eleven_text_to_sound_v2",
+  loop: true,
   text: "forest at dawn, gentle wind through leaves, distant bird calls every 6 seconds, soft creaking branches, no music, no human sound, 22s seamless loop",
   durationSeconds: 22
 )
 // Then: summer_import_from_url(url: "<fileUrl>", path: "res://audio/ambient/forest_dawn.wav")
 ```
 
-`sound_effects` reads from **`text`**, not `prompt` — passing `prompt` is a 400 `text_required`. (`prompt` is the `music` capability's field.) The clip comes back as WAV, so a `.wav` target path is correct.
+Name `modelId: "eleven_text_to_sound_v2"` with `loop: true`: it is the only sound-effect model that makes seamless loops, and without a `modelId` the person's default sound-effect model runs, which may not loop. `sound_effects` reads from **`text`**, not `prompt` — passing `prompt` is a 400 `text_required`. (`prompt` is the `music` capability's field.) The clip comes back as WAV, so a `.wav` target path is correct.
 
 22s is the SFX ceiling. Always generate at the ceiling for ambient — longer cycle means less recognized repetition.
 

package/library/skills/ambient-bed/resource.yaml

@@ -1,6 +1,6 @@
 id: skill/ambient-bed
 kind: skill
-version: 1.0.2
+version: 1.0.3
 summary: Generate a long looping location ambience — forest, dungeon, city, spaceship, cave — a looping AudioStreamPlayer on the Ambient bus with a seamless loop.
 use_when:
   - generating a long looping location ambience — forest at dawn, dungeon air, city street, spaceship hum, cave drip — non-melodic and low-energy

package/library/skills/audio-direction/SKILL.md

@@ -203,15 +203,15 @@ Ask:
 
 ### 10. Optional — generate first SFX seeds
 
-If the user wants to start generating, propose 3-5 SFX seeds aligned with the vocabulary. These are starting points, not finals.
+If the user wants to start generating, propose 3-5 SFX seeds aligned with the vocabulary. These are starting points, not finals. Generate them with the `sound-effect` skill: the first sound effect in a chat starts with its question (three versions from three models, picked by ear in Summer Studio), and its prompt shape is the one that tested well.
 
 ```
-summer_generate_audio(capability="sound_effects", text="soft woody UI click, 80ms, no reverb, neutral pitch", durationSeconds=0.5)
-summer_generate_audio(capability="sound_effects", text="warm major-third coin pickup, 300ms, light reverb", durationSeconds=0.5)
-summer_generate_audio(capability="sound_effects", text="punchy low-mid player damage hit, slight detune, 200ms, no tail", durationSeconds=0.5)
+summer_generate_audio(capability="sound_effects", text="Foley one-shot: a fingertip taps a small wooden button, soft woody click, no tail, close-mic, dry, no reverb, no music, no voices.", durationSeconds=0.5)
+summer_generate_audio(capability="sound_effects", text="Foley one-shot: a small gold coin drops onto a wooden table, bright metallic ting with a short ring, close-mic, dry, no music, no voices.", durationSeconds=0.5)
+summer_generate_audio(capability="sound_effects", text="Foley one-shot: a fist hits a padded leather vest, low-mid thump, no tail, close-mic, dry, no reverb, no music, no voices.", durationSeconds=0.5)
 ```
 
-`capability` is required; `sound_effects` reads from `text` (not `prompt`), and the length argument is `durationSeconds` (not `duration`) with a floor of 0.5 s. Ask for the character you want inside the text and let the player only use the front of the clip — you cannot request 80 ms.
+`capability` is required; `sound_effects` reads from `text` (not `prompt`), and the length argument is `durationSeconds` (not `duration`) with a floor of 0.5 s (1 s for Stable Audio 3 SFX). Leave out `modelId` so the person's approved default model runs. Ask for the character you want inside the text and let the player only use the front of the clip — you cannot request 80 ms.
 
 Ask first:
 

package/library/skills/audio-direction/resource.yaml

@@ -1,6 +1,6 @@
 id: skill/audio-direction
 kind: skill
-version: 1.0.6
+version: 1.0.7
 summary: Define the game's sonic identity — music style, instruments, SFX vocabulary, dynamic music plan — output as an audio bible at .summer/audio-bible.md.
 use_when:
   - defining the sonic identity — music style, instruments, SFX vocabulary, dynamic music plan

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

@@ -298,6 +298,10 @@ 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`.
+  - Every summer.games bundle: export with the released Summer editor from the download page, never a development build, and export again after updating Summer. Otherwise its scripts can fail to compile on players' devices and the game opens to an empty window, though every upload check passes. `release-readiness` check 7 proves it.
+  - Every file the game reads by path at run time (`FileAccess`, `DirAccess`, `load_from_file`) that Summer doesn't import, such as a `.bin` or `.json`, must match the **summer.games** preset's own `include_filter` (Resources > Filters to export non-resource files/folders); a filter on another preset doesn't carry over. A left-out file is no export error, it is just missing on players' devices. Never use `SystemFont` for phone text: on iPhone it draws every glyph as a box. `release-readiness` check 8 lists the pack.
+  - iPhone and Android bundles: the Summer Games apps start only exports on their Summer version line (same MAJOR.MINOR, patch no newer). Export with the current Summer release and export again after every Summer minor update, or players see "The game could not start" on phones while desktop works. `release-readiness` check 9.
+  - Hosted games, before the upload: a clean export does not prove players can join. Run `release-readiness` on the `.zip`: the bundle's `server.pck`, started with no scene, must load the authority scene (the server preset needs the `summer_authority` custom feature), and `Summer.initialize` must pass no hard-coded Game ID. Otherwise every online join fails with `world_start_timeout`.
   - 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; get past a title menu with the game's own flags in `args`, e.g. `["--autostart"]`, or `steps` such as `[{"press":"Play"},{"wait":3000},{"shot":true}]`), 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`).

package/library/skills/make-game/SKILL.md

@@ -47,6 +47,7 @@ These rules from the playbooks apply to every genre:
 - **2D scales to the viewport.** Set `display/window/stretch/mode = canvas_items` and `stretch/aspect = expand`; UI uses Control anchors; code-positioned nodes compute from `get_viewport_rect().size`. Never hardcode 1920x1080.
 - **Playable slice, not tech demo.** Name the core loop in one sentence; every input gets feedback (tween, sound, particle, flash, shake); progression is visible; a restart exists. The bar is "feels good for 30 seconds".
 - **Fast first draft when someone is waiting.** The first playable version uses shapes, the palette and any template art, plus at most one or two generated assets the person specifically asked for; generation takes minutes, so it never blocks the first play. Say plainly that it is a first draft to get a feel for the game, that the art is not final, and ask if this is the direction they want. Generate the rest of the art in later passes.
+- **A way back to the title.** From inside play, a pause menu or a **Leave** button returns to the title screen without quitting the app.
 - **Text the default font can show.** No emoji or symbols (▲ ◀ ★ ♥ ✓) in UI text: they render as boxes with hex codes. Use words or icons; see `ui-basics`.
 
 ## The Pipeline
@@ -95,6 +96,12 @@ This phase doesn't have a dedicated skill yet — do it inline. Read `.summer/Ga
 2. **Core mechanics** — ranked, max 3 (the brief enforces this; respect it)
 3. **Cut list** — what's explicitly NOT in scope
 
+If the game has online play, the plan also fixes three product defaults; each one was missed by a real release:
+
+- **Online play is reachable by default.** A new player gets to it from the title without changing a setting. Hiding it behind a setting or a grown-ups gate is the owner's explicit decision, recorded in the plan, and it means someone joins online before every release.
+- **Progress is saved by the server.** Online progress goes through authority player data (`summer-player-data`), not only the player's local files.
+- **A way back to the title** from inside an online and an offline session.
+
 Save the plan to `.summer/build-plan.md`. Format:
 
 ```markdown
@@ -236,8 +243,10 @@ Only if `summer_get_diagnostics` flags rendering or physics hotspots. Don't opti
 1. `play` from main scene.
 2. Walk every mechanic from the plan.
 3. Hit the win condition (or lose condition).
-4. `summer_get_diagnostics` clean.
-5. `debug` until clean if not.
+4. Return to the title from inside play, then start again.
+5. Online games: run Local Play (`multiplayer-testing`) and reach online play from the title as a new player, with default settings.
+6. `summer_get_diagnostics` clean.
+7. `debug` until clean if not.
 
 **Don't skip this even if every mechanic worked individually.** Integration bugs hide between mechanics.
 
@@ -249,6 +258,14 @@ Skill: export-and-ship
 
 Pre-flight checklist (icon, store banners, build config) before producing release builds for the targets in the brief.
 
+Before any version reaches players, run:
+
+```
+Skill: release-readiness
+```
+
+It checks the file you upload, not the editor: a hosted game's `server.pck` starts its authority scene, `Summer.initialize` passes no hard-coded Game ID, online play is reachable, progress is saved by the server, and players can get back to the title. Then, after publishing, the user joins online with the released version. Report each check as pass, fail, not applicable or not run. Hosted games publish through `multiplayer-publish`; store pages through `publish-your-game`.
+
 If the brief said "jam" or "prototype", skip this phase. If the brief said "game I want to release", run it.
 
 ## Anti-Patterns
@@ -260,6 +277,8 @@ If the brief said "jam" or "prototype", skip this phase. If the brief said "game
 | Stack art direction on top of unfinished mechanics | Art changes are reversible only if the underlying scene structure is stable. Get mechanics done first. |
 | Treat "polish" as required | If the brief says "jam in 2 days", polish is a cut item. Respect the brief. |
 | Run all phases without confirming | The user owns scope. Stop at every checkpoint. |
+| Ship online play behind a setting nobody changes | Hosted join is never exercised, so it breaks without anyone noticing. Reachable by default, or the owner joins online before every release. |
+| Hard-code a Game ID in `Summer.initialize` | The summer.games bundle has no `gameId`; a different ID fails on the hosted server and every online join times out. Pass no ID. |
 | Build a fully featured menu before there's a playable mechanic | Menu work is endless polish; player-loop work is the actual game. Mechanics first. |
 | Fall back to "let me try a few things" mid-pipeline | If you don't know what to do, name the phase and ask the user, don't improvise around the structure. |
 

package/library/skills/make-game/resource.yaml

@@ -21,6 +21,7 @@ related:
   skills:
     - skill/audio-direction
     - skill/export-and-ship
+    - skill/release-readiness
     - skill/design-mechanic
     - skill/tune-performance
     - skill/art-direction

package/library/skills/multiplayer/SKILL.md

@@ -84,7 +84,7 @@ the sender's verified Session. Events are fire-and-forget.
 
 | Word | Meaning |
 |---|---|
-| Game | Your game on Summer; its id is `gameId` in `summer.build.json` and the argument to `Summer.initialize` |
+| Game | Your game on Summer; its id is `gameId` in `summer.build.json`. `Summer.initialize()` takes no ID: Summer knows which game is running |
 | World | One running match or shared place, simulated by one authority |
 | WorldDefinition | `world.json`: which scenes run the client and the authority, lifetime, persistence |
 | Queue | How players find a World; declared in `summer.build.json` |
@@ -109,6 +109,8 @@ Each skill continues the same small game, so their code fits together:
    what a passing run must show.
 5. **`multiplayer-publish`**: export the summer.games bundle and upload it as
    a Build.
+6. **`release-readiness`**: before players get a version, prove the server
+   starts its authority scene and a real online join works.
 
 ## Add Summer services
 

package/library/skills/multiplayer/resource.yaml

@@ -25,6 +25,7 @@ related:
     - skill/multiplayer-state
     - skill/multiplayer-testing
     - skill/multiplayer-publish
+    - skill/release-readiness
     - skill/summer-matchmaking
     - skill/summer-player-data
 source: official

package/library/skills/multiplayer-movement/SKILL.md

@@ -176,7 +176,7 @@ func _ready() -> void:
 	spawner.entity_spawned.connect(_on_player_spawned)
 	spawner.command_received.connect(_on_command)
 	world.session_left.connect(_on_session_left)
-	var initialized: SummerResult = await Summer.initialize(Game.GAME_ID).get_result_or_completed_signal()
+	var initialized: SummerResult = await Summer.initialize().get_result_or_completed_signal()
 	if not initialized.ok:
 		push_error(initialized.message)
 		return

package/library/skills/multiplayer-movement/files.md

@@ -26,7 +26,7 @@ func _ready() -> void:
 	spawner.entity_spawned.connect(_on_player_spawned)
 	spawner.command_received.connect(_on_command)
 	world.session_left.connect(_on_session_left)
-	var initialized: SummerResult = await Summer.initialize(Game.GAME_ID).get_result_or_completed_signal()
+	var initialized: SummerResult = await Summer.initialize().get_result_or_completed_signal()
 	if not initialized.ok:
 		push_error(initialized.message)
 		return
@@ -141,7 +141,7 @@ func _ready() -> void:
 	# Connect before joining, or the first values arrive unseen.
 	spawner.state_group_created.connect(_on_group_created)
 	spawner.entity_spawned.connect(_on_entity_spawned)
-	var initialized: SummerResult = await Summer.initialize(Game.GAME_ID).get_result_or_completed_signal()
+	var initialized: SummerResult = await Summer.initialize().get_result_or_completed_signal()
 	if not initialized.ok:
 		push_error(initialized.message)
 		return
@@ -440,7 +440,6 @@ occurrence_streams = Array[SummerNetworkOccurrenceStream]([SubResource("Commands
 extends RefCounted
 ## Shared by the client and the authority: ids, streams and shared rules.
 
-const GAME_ID := "game_courtyard"
 const QUEUE := &"courtyard"
 const MOTION := &"courtyard.motion"
 const CMD := &"courtyard.cmd"

package/library/skills/multiplayer-project/SKILL.md

@@ -74,7 +74,14 @@ textures/vram_compression/import_etc2_astc=true
 ```
 
 The `.summer_client` and `.summer_authority` overrides tell each exported pack
-which scene to start. Leave the `[summer] version` line the editor writes.
+which scene to start. Summer starts the hosted server with no scene
+argument, so `run/main_scene.summer_authority` is the only thing that makes
+`server.pck` start the authority. It applies only when the server export
+preset carries the custom feature `summer_authority` (`multiplayer-publish`).
+Without it the server starts the client scene, never reports ready, and every
+online join fails with `world_start_timeout`. Local Play names the scene
+itself, so it works either way. Leave the `[summer] version` line the editor
+writes.
 
 ## 4. The declarations
 
@@ -116,6 +123,9 @@ starts. Summer rejects unknown fields, so copy the shape exactly.
 }
 ```
 
+- `gameId` is the game's id in Summer Studio, for your publishing tools. The
+  summer.games export leaves it out of the bundle, so game code never reads
+  it: both sides call `Summer.initialize()` with no ID (sections 7 and 8).
 - `queues[].minPlayers` / `maxPlayers` bound a match. `worldDefinition` names
   the `definition_id` in `world.json`.
 - `server.exportPreset` names the server export preset (`multiplayer-publish`).
@@ -250,7 +260,6 @@ on both sides:
 extends RefCounted
 ## Shared by the client and the authority: ids, streams and shared rules.
 
-const GAME_ID := "game_courtyard"
 const QUEUE := &"courtyard"
 const CMD := &"courtyard.cmd"
 const MAX_PLAYERS := 8
@@ -321,7 +330,7 @@ func _ready() -> void:
 	spawner.entity_spawned.connect(_on_player_spawned)
 	spawner.command_received.connect(_on_command)
 	world.session_left.connect(_on_session_left)
-	var initialized: SummerResult = await Summer.initialize(Game.GAME_ID).get_result_or_completed_signal()
+	var initialized: SummerResult = await Summer.initialize().get_result_or_completed_signal()
 	if not initialized.ok:
 		push_error(initialized.message)
 		return
@@ -379,6 +388,11 @@ func _on_session_left(session: SummerSession, reason: String) -> void:
 
 `authority/main.tscn` is a plain `Node` with that script ([files.md](files.md)).
 
+- `Summer.initialize()` takes no Game ID. Summer takes the game's identity
+  from where it runs: Local Play, the hosted server or the Summer Games app.
+  Never pass a literal, a placeholder or a fallback ID: any ID that differs
+  from the hosted one fails with `game_identity_mismatch`, and the authority
+  stops before it reports ready.
 - **Never** read who sent a Command from its payload: `request.get_session()`
   is verified. Don't name your own classes `SummerSession`, `SummerWorld` or
   other engine class names.
@@ -426,7 +440,7 @@ func _ready() -> void:
 	spawner = Game.build_network(self, PlayerArchetype)
 	# Connect signals like state_group_created here, before joining, or values
 	# that arrive during the join go unseen (multiplayer-movement adds them).
-	var initialized: SummerResult = await Summer.initialize(Game.GAME_ID).get_result_or_completed_signal()
+	var initialized: SummerResult = await Summer.initialize().get_result_or_completed_signal()
 	if not initialized.ok:
 		push_error(initialized.message)
 		return
@@ -510,6 +524,8 @@ warning yourself.
 | `@rpc`, `MultiplayerSynchronizer`, `ENetMultiplayerPeer` | The Spawner, State groups and Commands | Unverified peers, no late join, no Summer hosting |
 | `if multiplayer.is_server()` in one shared scene | Separate `client/` and `authority/` scenes | The engine starts the right scene on each side |
 | Load an `authority/` file from client or shared code | Move what both sides need into `network/` | The export leaves `authority/` out of the players' pack |
+| `Summer.initialize("game_…")`, or a fallback ID when `gameId` is missing | `Summer.initialize()` | The bundle has no `gameId`; a different ID fails hosted with `game_identity_mismatch` |
+| Set `run/main_scene.summer_authority` and stop there | Also give the server preset the `summer_authority` feature | Without the feature the hosted server starts the client scene |
 | Build the composition differently on each side | One `network/composition.tres`, loaded by both | Different compositions refuse each other |
 | Send a Command right after `join` succeeds | Await `spawner.network_ready` first | The authority does not know the client's network until then |
 | Free a player's things on `session_disconnected` | Free them on `session_left` | A disconnected player keeps their seat and may reconnect |