Upgrade Spawnite

spawnite upgrade moves your game to the newest Spawnite release. It edits package.json and never your code: it sets every @spawnite package the game lists to that release together, installs them, and prints each change since your old release that needs an edit, with what to write instead. A game you published keeps running on the platform whether you upgrade or not, as What a release may change says.

What a release may change

Each engine release belongs to a compatibility line, the releases a published game moves between on its own. The lines are the ones npm’s ^ range draws:

• From 1.0.0 on, the line is the major: 1.2.0 and 1.9.0 share a line, and 2.0.0 starts the next.
• Below 1.0.0, the line is the major and the minor: 0.1.3 and 0.1.4 share a line, and 0.2.0 starts the next.
• A prerelease, such as a beta, is a line of its own.

A release inside a line never breaks the public API, the network messages of a running game, or the shape of a save. A change that does any of those starts the next line.

A published game follows its line. When the platform serves a newer release on the game’s line, the game’s next page load and next room run it, with no republish, so engine fixes and speed-ups reach a game nobody maintains. The next line never reaches a published game on its own: the game moves to it when you upgrade, build on it and publish.

What backs the promise

The following checks hold a release to its line:

• The engine’s public API is written down as a report, and every change to the engine is compared with it, so a change to a public name or signature is a reviewed difference, never an accident.
• A room refuses a client built on another version of the network protocol, so a client and a room that cannot understand each other never play together.
• spawnite publish refuses a version whose save is older than one players of the game already hold, as Publishing says.
• Before a release ships, the platform’s own games are built against it, booted in a browser and played.
• When three rooms in a row fail to start a version, it starts no more rooms, and the platform tries it again when it serves a newer release on its line.

These checks catch a broken name, a broken network message and a broken save. They do not prove that every game plays exactly as before: a fix to the engine can still change how a game feels, such as a jump’s arc. When that risk matters more to you than the fixes, pin the game.

Pin a game to its release

A pinned version runs the exact release it was built against, whatever the platform serves later. Publish with spawnite publish --pin, which writes spawnite.engine.pin into the game’s package.json so every later build is pinned too, and spawnite publish --no-pin to follow the line again. A pin costs every engine fix: speed-ups, device support and bug fixes stop reaching that version until you publish a new one. Pin a version to its release has the details.

Know when to upgrade

When your game is behind, every spawnite command ends with one line, and every tool of the Spawnite MCP server ends its reply with the same line. In the command’s own test, on two beta releases, it reads:

Spawnite 0.1.0-beta.9 is out, and this game has 0.1.0-beta.8. Run: spawnite upgrade

You do not have to wait for the line. To check now, run spawnite upgrade: it asks npm each time.

Upgrade, step by step

1. Commit your work, so you can see what the upgrade changes and go back if you need to:

   git add -A && git commit -m "before the upgrade"

2. In the game’s folder, run the upgrade:

   spawnite upgrade

   The command sets every @spawnite package in package.json to the newest version, installs them, and prints what changed. Its first line names the packages it moved and the two releases, such as Moved @spawnite/engine from 0.1.0-beta.8 to 0.1.0-beta.9. from its test. Then it prints What changed, oldest first. and one entry for each change that needs an edit: the release that made the change, what changed, and the code before and after. When no change needs an edit, it prints No change between them needs an edit to the game.

3. Make each edit the list names, from the top. The list runs oldest first, so a name that changed twice ends at its newest form. With an agent, give it the list: each entry says what to write instead.

4. Check the game:

   pnpm check
   pnpm test

   A type error names a line that still uses an old name. Find the old name in the list from step 2 and make its edit.

5. Play the game once with pnpm dev, or spawnite play start for a room game.

6. Publish the new version:

   spawnite publish

   Publishing covers the publish itself.

When the game already has the newest release, step 2 prints This game has Spawnite <release>, the newest. and changes nothing.

Fix an error

The following table lists each message the upgrade prints when it stops, what it means, and the fix:

The message	What it means	The fix
No game found: a game's package.json depends on @spawnite/engine	You ran the command outside the game’s folder.	Change to the game’s folder, or name it: spawnite upgrade --project <folder>.
lists @spawnite/engine as ... and has none installed, so no release replaces it	The game’s packages are not installed yet.	Run pnpm install, then spawnite upgrade.
lists @spawnite/engine as workspace:* ...	The game takes the engine from a folder or a workspace, not from npm.	Nothing to upgrade: update the folder the engine comes from.
could not read the newest version from https://registry.npmjs.org/...	npm did not answer. The message ends with the reason.	Check the connection and run the command again. Nothing changed.
package.json now names <release>, and pnpm install failed	The versions in package.json moved, and the install stopped. Its own error is above the line.	Fix what the install printed and run pnpm install. Then read the changes since your old version: the entries above it in node_modules/@spawnite/cli/migrations.json.
it has no @spawnite/cli installed, which carries the list of changes	The packages moved, and the game does not list the CLI, so nothing can print what changed.	Add @spawnite/cli at the new version to devDependencies, install, and read node_modules/@spawnite/cli/migrations.json.
A type error after the upgrade, such as Module "@spawnite/engine" has no exported member	The game still uses a name the release renamed or removed.	Find the name in the list the upgrade printed and make its edit. To print the list again, read node_modules/@spawnite/cli/migrations.json.
spawnite publish refuses the game after the upgrade	The publish checks the build, not the upgrade.	Read the refusal: it names what to fix. Publishing lists each one.

To go back to where you were, restore package.json and the lock file from the commit in step 1, and install again:

git checkout -- package.json pnpm-lock.yaml && pnpm install

When no line appears

The line is left out in the following cases:

• The command runs in CI, or NO_UPDATE_NOTIFIER is set. spawnite upgrade still works.
• npm could not be reached. The CLI asks npm at most once in 4 hours and waits at most 1.5 seconds. spawnite upgrade refuses until npm answers.
• The game takes the engine from a workspace or a folder. No release replaces it, so spawnite upgrade refuses.

Which release a game moves to

spawnite upgrade moves to the newest release, across lines: it is how your game’s source reaches the next line. A game on a full release moves to the newest full release and never to a prerelease. A game on a prerelease, such as a beta, moves to the newest prerelease of its kind, and to the full release once that ships. Every @spawnite package in a game has the same version, and the upgrade keeps them together.