> ## Documentation Index
> Fetch the complete documentation index at: https://docs.summerengine.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Release readiness skill for AI agents

> Before releasing a Summer game version, prove players can play it: server, online join, progress, files. A Summer Engine skill for AI agents.

`release-readiness` is a skill from the [Summer skill library](/mcp/skills): a guide your AI agent reads when the task matches, so it builds the good version on the first try. Before releasing a Summer game version, prove players can play it: server, online join, progress, files.

| | |
| - | - |
| Status | Preview: not yet exercised in-engine by the Summer team |
| Domains | Deployment, Multiplayer, Playtest |
| Version | `1.0.0` |
| Engine version | `>=4.6` |
| Recommended set | No, installed by `--all` or by name |

## When your agent uses it

* Before uploading, promoting or releasing a new version to players: is it ready to release
* Every online join fails with world\_start\_timeout, or the hosted server's log is empty, while Local Play works
* Summer.initialize fails with game\_identity\_mismatch: the initialized Game ID does not match hosted runtime context
* Checking that a hosted game's server.pck starts the authority scene and not the title screen
* Players get a blank or black screen when they open the released game, but it runs in the editor: client scripts fail with Parse Error or Failed to load script
* Text shows as boxes on iPhone but looks fine on desktop: a font or other file read with FileAccess is missing from the pack, or SystemFont is used
* The Summer Games phone app says the game could not start, but it works on desktop: the game's Summer version line differs from the app's
* The game closes about a minute into play with Play paused or That link can't be opened, and the player is signed out
* A game release failed for players and the check that would have caught it needs adding

## Install

`summer setup` installs every skill for your agent. To add only this one:

```bash theme={null}
npx -y summer-engine@latest skills install release-readiness --agent claude-code
```

Swap `claude-code` for your agent, such as `codex` or `cursor`. See [Skills](/mcp/skills#quick-start) for every option.

## The skill

Summer checks every upload: platforms, packs, and the files they name. Those
checks prove the export is well formed. They can't prove that a player who
presses **Play online** gets into a game. Each check below exists because a
real release passed every upload check and still failed for its players.

The creator docs have the same checklist, with the same numbers:
[https://docs.summerengine.com/publishing/release-readiness](https://docs.summerengine.com/publishing/release-readiness) (fetch it as `.md`).

## When to run it

* Before you upload a new Build of a game that will go to players.
* Before you promote or release a version.
* After a release fails for players, to find the cause, and then to add the
  check that would have caught it (see the last section).

For a jam build or a prototype nobody else plays, skip it.

## How to report

Run every check that applies. Each check needs **evidence**: a command's
output or something you saw in the running game. Reading the project and
deciding it looks right is not evidence.

Report one line per check:

* **pass**, with the evidence;
* **fail**, with what you saw;
* **not applicable**, with the reason (for example, no server);
* **not run**, with what is still needed (for example, "needs a real online
  join after publishing").

A check that was not run is not a pass. Show the list to the user before you
change anything; the user decides what to fix and whether to release with a
check still open.

## Test the file you upload

Run the checks on the summer.games `.zip`, not on something close to it.
Export the bundle (in the editor: **Project > Export**, preset
**summer.games**, **Export Project**; from an agent: `summer_export_game`; or
from a terminal), then take the server pack and the packaged build file out
of it:

```sh theme={null}
<summer> --headless --path . --import
<summer> --headless --path . --export-release "summer.games" build/<game>.summer.zip
mkdir -p build/bundle
unzip -o build/<game>.summer.zip server.pck client.pck summer-bundle.json config/summer.build.json -d build/bundle
```

A game without a server has no `server.pck` or `config/`; `unzip` then
warns about the missing names and extracts the rest.

`<summer>` is the Summer Engine executable. Two look-alikes hide real
failures:

* **A server pack exported on its own** with your server preset
  (`--export-pack`) is not the bundle's `server.pck`. For example, it keeps
  `gameId`, which the bundle leaves out, so it can pass check 6 while the
  uploaded `.zip` fails it.
* **Local Play** always starts the authority scene by name, so it can't catch
  check 1. It also runs without a hosted identity, so it can't catch check 6.

## The checks

Checks 1 and 2 apply to every game with a server (`summer.build.json` names
a `server.exportPreset`). Checks 3 and 4 apply to every game with online
play. Checks 5 to 8 and 10 apply to every game. Check 9 applies to every
bundle for iPhone or Android.

### 1. The server pack starts the authority scene

**Why.** Summer starts a hosted World's `server.pck` with no scene argument,
so the pack's own main scene decides what runs. The server preset must carry
the custom feature `summer_authority`, and `project.godot` must set that
feature's main scene:

```ini theme={null}
[application]

run/main_scene="res://client/main.tscn"
run/main_scene.summer_client="res://client/main.tscn"
run/main_scene.summer_authority="res://authority/main.tscn"
```

```ini theme={null}
# export_presets.cfg, the server preset
platform="Linux"
dedicated_server=true
custom_features="summer_authority"
```

Without the feature, `run/main_scene.summer_authority` never applies and
the server starts the players' main scene, usually the title screen. That
scene never restores the World or tells Summer it is ready, so **every
online join fails with `world_start_timeout`**. The bundle manifest still
names the authority scene as the server's main scene, so reading the
manifest proves nothing.

**Check it.** Start the bundle's `server.pck` the way Summer does, with no
scene argument, and stop it after a few seconds:

```sh theme={null}
perl -e 'alarm shift; exec @ARGV' 15 <summer> --headless --verbose --main-pack build/bundle/server.pck
```

Find the first `Completed load for: 'res://….tscn'` line. It must be the
authority scene: the `entry_point` of the `headless_engine` component in
`world.json`. Later lines may complain that there is no hosted World; that
is expected in a local run. Then confirm the source too: the server preset in
`export_presets.cfg` has `summer_authority` in `custom_features`, and
`project.godot` sets `run/main_scene.summer_authority`.

**Fix.** Add `summer_authority` to the server preset's **Features > Custom**,
set `application/run/main_scene.summer_authority` to the authority scene,
export again and rerun the check. If your Summer version's export refuses a
server pack that starts the wrong scene, that refusal is this check failing;
run the check anyway, because older versions don't refuse it.

### 2. Join online with the version you release

**Why.** Check 1 runs on your computer. Players use a hosted server, and some
failures, such as check 6, only show up there.

**Check it.** Right after you publish or promote the version, open the game
in a Summer Games app as a player, join online and play until you are in the
game. Do it before you tell players about the update. An agent can't do this
step; report it as **not run** and ask the user to do it, then record what
they saw. If the join fails, see [Troubleshooting](#troubleshooting).

### 3. Players can find online play

**Why.** If nobody, including you, reaches online play, nobody notices when
it breaks. A game hid online play behind a grown-ups setting, so its hosted
join was never tried before release, and it failed for every player who
found it.

**Check it.** Start the client as a new player and follow the default path
to online play. List every gate on that path: settings, parental or age
gates, debug toggles. A new player should reach online play without
changing a setting. If online play is off by default on purpose, the user
must confirm that decision, and then check 2 must run before every release.

### 4. The server saves online progress

**Why.** Progress kept only in the player's local files is lost on
reinstall or a new device, and players can edit it.

**Check it.** In code, the authority loads each player's progress when they
join (`Summer.authority.player_data.load(session)`) and saves it with
`commit_public` or `commit_secret` (`summer-player-data`). Then play online,
earn something, leave, and join again from a fresh install or another
device. The progress must still be there. Local Play stores player data on
disk; only hosted play proves it lasts.

### 5. Players can get back to the title

**Why.** A player with no way out of a session has to kill the app.

**Check it.** Play into a session, online and offline, and find the way
back: a pause menu or a **Leave** button. Use it, then start a new session
from the title. In online play, leaving should call
`Summer.client.leave()` before the title loads.

### 6. The game doesn't hard-code its Game ID

**Why.** The summer.games export is portable: the bundle's
`summer.build.json` has no `gameId`. Summer takes the game's identity from
wherever it runs: the Summer Games app, the hosted server or Local Play.
Any other ID fails on the hosted server with `game_identity_mismatch`, "The
initialized Game ID does not match hosted runtime context." The authority
then stops before it restores the World or reports ready, and every online
join ends in `world_start_timeout`, even though check 1 passes. The Summer
Games app refuses a mismatched ID the same way.

**Check it.**

1. Find every call: `grep -rn "Summer.initialize" --include=*.gd .`
2. For each, trace the argument back to where it comes from. It must be
   nothing (`Summer.initialize()`) or an ID the game got from Summer. It must
   never be a literal, a placeholder, or a fallback such as
   `"game.my-game"` used when `gameId` is missing.
3. `cat build/bundle/config/summer.build.json`: it has no `gameId`, so
   anything the game reads from this file at run time comes back empty.

Local Play and the local run in check 1 have no hosted identity, so a wrong
ID passes there. Only check 2 proves this one.

**Fix.** Call `Summer.initialize()` with no ID (Summer 0.7.1 and later), on
the client and on the authority.

### 7. Export with a released Summer, and its scripts compile on the players' runtime

**Why.** The export records which Summer made it, in the client pack's
`.summer/export.json` and under `export` in the bundle's
`summer-bundle.json`: `summerVersion` and `engineSha`. Players' apps run the
game on a released Summer runtime with the same MAJOR.MINOR and a patch at
least the stamped one. A development build of Summer
can stamp a version that is already released while it has APIs that release
lacks. Scripts that use them then fail to compile on every player's device,
and the game opens to an empty or black window. Summer doesn't compile
scripts when you upload, so every upload check passes.

**Check it.**

1. Read the stamp: `cat build/bundle/summer-bundle.json`. The export log
   shows it too: `Exported by Summer <version> (engine <sha>)`.
2. `summerVersion` must be a released Summer version, and `engineSha` must
   equal that release's `engineSha` in
   `downloads.summer.games/engine-templates/<summerVersion>/manifest.json`
   (published for Summer 0.7.1 and later). If it differs, or that address has
   nothing for the version, a development build made the export.
3. Run the client pack on that released Summer, and fail on any compile
   error. The run exits normally even when a script fails, so the grep is the
   check:

```sh theme={null}
   perl -e 'alarm shift; exec @ARGV' 60 <released-summer> --headless --verbose --main-pack build/bundle/client.pck --quit-after 600 > build/client-run.log 2>&1
   grep -E 'SCRIPT ERROR|Parse Error|Failed to load script' build/client-run.log
```

`<released-summer>` is the Summer executable of the stamped version from
the download page, not the development build that made the export. The
grep must print nothing. The run compiles the scripts that the main
scene and autoloads load; a script that loads only later in play compiles
when play reaches it, so check 2 still matters for online games.

**Fix.** Ask the user to install the current Summer release from
[https://summerengine.com/download](https://summerengine.com/download) (or, with their OK, run
`summer install --yes`). Export again with it, and rerun this check on the
new `.zip` before you upload it.

### 8. Every file the game reads at run time is in the pack

**Why.** The export packs scenes, scripts and imported assets. A file the
game opens itself by path (`FileAccess`, `DirAccess`, `load_from_file`,
`FontFile.load_dynamic_font`, `ConfigFile.load`) that has no `.import`
beside it, such as a `.bin`, `.json` or `.txt`, is a non-resource file. It
goes into the pack only when the preset's `include_filter` (**Resources >
Filters to export non-resource files/folders**) matches it and
`exclude_filter` doesn't. Each preset has its own filters: the summer.games
preset doesn't inherit one set on another preset. A file left out is not an
export error; on players' devices `FileAccess` just returns nothing and the
game's fallback runs. Fonts show it first: in the Summer Games app on iPhone
a `SystemFont` has no system fonts to use, so every glyph draws as a box,
while the editor, Local Play and desktop find a system font and look right.
A real release shipped this way: its font file was missing from the
uploaded pack, and every letter on iPhone was a box.

**Check it.**

1. Find every read by path:
   `grep -rn -E 'FileAccess\.|DirAccess\.|load_from_file|load_dynamic_font|ConfigFile' --include=*.gd .`
   Note each `res://` file or folder they read; skip `user://` (saves). A
   file is raw when no `<file>.import` sits beside it.
2. Check the filters:
   `grep -n -E '^name=|^include_filter=|^exclude_filter=' export_presets.cfg`.
   The summer.games preset's `include_filter` must match each raw file the
   client reads, and its `exclude_filter` must not. Do the same on the
   server preset for files the authority reads.
3. List the pack. Save this script **outside** the project, for example as
   `~/list_pack.gd`:

```gdscript theme={null}
   extends SceneTree
   # Prints one "PACK res://..." line per file in the pack mounted with --main-pack.
   func _init() -> void:
       _walk("res://")
       quit()

   func _walk(dir: String) -> void:
       var d := DirAccess.open(dir)
       if d == null:
           return
       d.include_hidden = true
       for f in d.get_files():
           print("PACK ", dir.path_join(f))
       for s in d.get_directories():
           _walk(dir.path_join(s))
```

```sh theme={null}
   perl -e 'alarm shift; exec @ARGV' 60 <summer> --headless --main-pack build/bundle/client.pck --script ~/list_pack.gd > build/client-pack.txt 2>&1
   grep -Fx 'PACK res://fonts/MyFont.bin' build/client-pack.txt   # once per raw file from step 1
```

Every raw file must print its line. No line means the file is not in the
pack, whatever the preset says. List `server.pck` the same way for files
the authority reads.
4\. `grep -rn SystemFont --include=*.gd --include=*.tscn --include=*.tres .`
must find nothing on a path phone players reach, fallbacks included.
5\. After publishing, open the game on an iPhone in the Summer Games app and
look at the title and one menu: letters, not boxes. An agent can't do
this step; report it as **not run** and ask the user.

**Fix.** Add each missing file to the summer.games preset's non-resource
filter (for example `fonts/*.bin`), or import it as a resource instead.
Ship the font in the project (an imported `.ttf`/`.otf`, or raw bytes that
step 3 proves are packed) and fall back to `ThemeDB.fallback_font`, Summer's
built-in font, never to `SystemFont`. Export again and rerun steps 3 and 5.

### 9. Export with the Summer version line the Summer Games apps run

**Why.** The Summer Games apps for iPhone and Android carry Summer inside
the app and download none. An app starts a game only when the export's
`summerVersion` has the app's MAJOR.MINOR (for example `0.7`) and a patch no
newer than the app's. A `0.6.x` export doesn't start in an app that carries
`0.7`: the player sees **The game could not start**. The desktop app fetches
the right Summer for each game, so the game can run on Mac and Windows and
still fail on every phone. The upload checks don't catch it.

**Check it.**

1. Read the stamp and platforms:
   `python3 -c 'import json; b=json.load(open("build/bundle/summer-bundle.json")); print(b["export"]["summerVersion"], b["client"]["targetPlatforms"])'`
2. If `targetPlatforms` lists `ios` or `android`, the first two numbers of
   `summerVersion` must match the current Summer release, shown on
   [https://summerengine.com/download](https://summerengine.com/download) and in Help > About after updating.
3. After publishing, open the game on a phone in the Summer Games app, as in
   check 2. "The game could not start" there, while desktop works, is this
   check failing.

**Fix.** Ask the user to update Summer to the current release (or, with
their OK, run `summer install --yes`). Export again, upload it as a new
version and promote it. Do this again after every Summer minor update
(0.6 to 0.7), because the apps move to the new line.

### 10. A signed-in player keeps playing for three minutes

**Why.** While the game runs, it calls Summer services for the signed-in
player: analytics, player data, the store. A short test can end before the
first of those calls. A real release closed for every player about a minute
in, with "That link can't be opened", and left them signed out: a Summer
service refused the player's sign-in, and the app ended play. The fault was
Summer's, not the game's, and no check on the game's files could see it.

**Check it.** After publishing, sign in to a Summer Games app on a phone,
open the released version and play it for at least 3 minutes, through at
least one analytics event. The game must not close, and the player must
still be signed in afterwards. Do it in each Summer Games app the game
targets. An agent can't do this step; report it as **not run** and ask the
user, then record what they saw.

**Fix.** Nothing in the game. Ask the user to report it to Summer with the
game's name, the app and the time it happened.

## Troubleshooting

### Every online join fails with `world_start_timeout`, but Local Play works

Most likely, in this order:

1. The server pack starts the wrong scene. Run check 1.
2. The game passes a fixed Game ID. Run check 6.

After the fix, export a new `.zip`, upload it, promote it and run check 2.

### The game opens to a blank window for every player

The game works in your editor, but every player sees an empty or black
window. Running the client pack as in check 7 prints
`Parse Error: Static function "…" not found` and
`Failed to load script "res://…"`. A development build of Summer made the
export, and the scripts use something the released version doesn't have.
Re-export with the current Summer release, upload the new version and
promote it.

### Text shows as boxes on iPhone

Every letter draws as an empty box in the Summer Games app on iPhone, while
the game looks right on desktop. The game most likely reads a font file that
isn't in the pack and falls back to `SystemFont`. Run check 8.

### "The game could not start" on iPhone or Android

The game works on desktop, but the phone app says "The game could not
start". The `.zip` most likely comes from a Summer version line the app
doesn't carry. Run check 9, then export again with the current Summer
release, upload and promote.

### The game closes after about a minute and the player is signed out

The Summer Games app closes the game 20 to 60 seconds into play with "Play
paused" or "That link can't be opened", and the player finds they are signed
out. A Summer service refused the player's sign-in while the game played.
This is Summer's fault, not the game's: see check 10, and ask the user to
report it with the time it happened.

### The game server's log is empty

An empty server log is not proof that the server hung or never started. A
release server holds back what the game prints until it exits when it isn't
attached to a terminal, so its log can look empty while the title scene
runs. Don't debug from the empty log; run check 1 on your own computer to
see which scene starts.

## Add a check after every incident

The list grows from real failures. When a release fails in a way no check
here would have caught:

1. Fix the game, and record the cause in the project's `.summer/memory/`.
2. Write the check that would have caught it: **Why**, **Check it** (a
   command to run or something to observe, against the real summer.games
   `.zip`), and **Fix**.
3. Propose it for this skill and for the docs page
   (`/publishing/release-readiness`), with the same number in both, through
   a pull request to summerengine/summer and to the docs. Until it lands,
   keep it in the project's memory so the next release runs it.

## Checklist

* [ ] Ran the checks on the summer.games `.zip` you upload, not a separately exported pack.
* [ ] 1\. The bundle's `server.pck`, run with no scene, loads the authority scene first.
* [ ] 2\. A real online join with the released version reaches the game (or is reported as not run).
* [ ] 3\. A new player reaches online play without changing a setting, or the user confirmed it is off on purpose.
* [ ] 4\. Online progress is loaded and committed through authority player data, and survives a fresh install.
* [ ] 5\. Players can get back to the title from inside a session, online and offline.
* [ ] 6\. Every `Summer.initialize` passes no ID, or an ID the game got from Summer.
* [ ] 7\. The export stamp names a released Summer and its `engineSha`, and `client.pck` run on that released Summer prints no `SCRIPT ERROR`, `Parse Error` or `Failed to load script`.
* [ ] 8\. Every file the game reads by path has a `PACK res://…` line in the listing of `client.pck` (or `server.pck`), no phone text uses `SystemFont`, and text shows as letters on an iPhone (or is reported as not run).
* [ ] 9\. For an iPhone or Android bundle, `summerVersion` has the current Summer release's MAJOR.MINOR.
* [ ] 10\. A signed-in player played the released version for 3 minutes in each Summer Games app, through an analytics event, without the game closing or being signed out (or it is reported as not run).
* [ ] One line per check reported to the user before anything is changed.

## From a shell

No Summer MCP tools in this session? Run each one as a command; when `summer --version` is missing or below 4.0, use `npx -y summer-engine@latest` in place of `summer`. Fields are flags in kebab-case (`--scene-path res://main.tscn`) or one `--input '<json>'`, and `summer ops describe <op>` prints the exact input. The `summer-cli` skill has the rest.

| In this skill | Command |
| - | - |
| `summer_export_game` | `summer engine export-game` |
| `summer_get_diagnostics` | `summer engine get-diagnostics` |
| `summer_read_file` | `summer engine read-file` |

## Related skills

* [`multiplayer`](/skills/multiplayer): Start here for Summer multiplayer: how authority, clients, Worlds and Sessions fit, and what comes next.
* [`multiplayer-publish`](/skills/multiplayer-publish): Ship a hosted Summer multiplayer game: the bundle, server preset, pre-upload checks, a new Build.
* [`multiplayer-testing`](/skills/multiplayer-testing): Test a Summer multiplayer game with Local Play: several players, bad network, bots, a passing run.
* [`multiplayer-project`](/skills/multiplayer-project): Set up a Summer multiplayer project: entry scenes, World and queue files, joining, a first Local Play.
* [`summer-player-data`](/skills/summer-player-data): Save a player's progress so it follows them to every match: authority load and commit, autosave, safe retries.
* [`publish-your-game`](/skills/publish-your-game): Publish a game on Summer Games through MCP: store page, art, build upload, submit, owner approval link.
* [`export-and-ship`](/skills/export-and-ship): Prepare a game export: check templates and targets, validate release assets, build after approval.
* [`make-game`](/skills/make-game): Orchestrate 'make me a game': brainstorm, plan, scaffold, mechanics, art, audio, polish, verify, ship.
* [`bounded-engine-runs`](/skills/bounded-engine-runs): Run Summer headless or offscreen safely: time limits, one engine per project, import passes, crash checks.

***

Source: [`library/skills/release-readiness/SKILL.md`](https://github.com/SummerEngine/summer/blob/main/library/skills/release-readiness/SKILL.md), rendered from `summer-engine@4.3.0` on npm.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.