EN Team Upgrade Engine

Upgrading the engine of a hosted game

Français · Type: how-to · Audience: admin · Context: hosted Studio · Status: ready · Applies from: 4.2.3

The Studio Server (hosted team Studio) · contract: experimental · verified by CI (support matrix of 4.4.0, 2026-10-23): Postgres, S3 and Keycloak in CI; Chromium and Firefox (job studio-hosted); WebKit on macOS, by hand only · automated checks: jobs studio-hosted, studio-install-smoke; CI plan studioHosted; 3 test files · people's passes: studio-hosted not run (#149), studio-collab not run (#150), studio-preview not run (#166), studio-assets-hosted not run (#167), studio-mcp-remote not run (#196), studio-oidc-generic not run (#197) · known limits: engine-upgrade-scope

A game imported into a team Studio from an older project may still be written for an older engine: authoring schema 2 (a 4.1.x project that never ran quest-n-click migrate), or imports under the former name web-scumm/…. An owner upgrades it on the server, in one call, judged before anything is written.

This page is about the game's content. Upgrading the server to a new engine version is a redeploy: see Upgrading the server.

What you get

The hosted game at the current authoring schema (3, with stable ids), and its imports under the current name, as one or two revisions, or a refusal that leaves the head as it was.

Context and versions

A hosted Studio with its worker, from 4.2.3; the rename of the former name from 4.3.0 (D47). The code is studio-server/src/server/engine-upgrade.ts. A local Studio has no such route: run quest-n-click migrate in the project (see Upgrade).

In the 4.2.x line the content format is frozen (D40): the schema migration is for a game made on 4.1.x.

Prerequisites

• The owner role.
• A backup taken just before, as the way back (see Backups).
• An access token: npx quest-n-click-studio-server token --server <url> from the release archive, or npm run studio-server -- token --server <url> in the engine repository.
• defineGame({...}) written in game.ts (a game that defines it elsewhere is refused: migrate it locally).

Where to run the commands

On any machine where the CLI is logged in to the Studio (see The server's command line). There is no button in the Studio yet: the route is the way in.

Steps

1. Take a backup and note the revision (the header's "revision N").

2. Call the route as an owner:

   curl -X POST -H "Authorization: Bearer $(npx quest-n-click-studio-server token --server https://studio.example)" \
     https://studio.example/api/engine/migrate

3. Read the answer.
   • { "changed": 0, "schema": {…} }: the game was already at schema 3 (and under the current name); nothing was written.
   • { "revision", "changed", "paths", "schema": { "from", "to" } }: the migration was written as one revision, engine upgrade: authoring schema 2 → 3; paths are the files written. With renamed, the imports were renamed first, as a revision of their own.
   • A 422 with errors (and skipped, rev, possibly renamed): refused, nothing of the migration was written.

4. Replay the playtests after it: they are neither migrated nor judged (a session recorded at schema 2 may name the old positional keys).

What it does

• Exclusive. It runs under the owner's exclusive lease (*): nobody else writes meanwhile. Their writes get a 423 with the owner's name, their drafts stay with them, and they write again once it is done. One upgrade at a time (429).
• On the worker. The worker runs the same migration as quest-n-click migrate on the head's snapshot: the stable ids written into rooms/*.ts, rules.ts, items.ts and game.ts, the translation tables' keys renamed, ids.migration.json and ids.paths.json, then the three lines UPGRADING leaves to the author in game.ts (schemaVersion: 3, saveVersion + 1, migrations: [..., idsMigration] and its import: all three or none, said in skipped). Nothing is written yet, and nothing but those files: the Studio refuses an answer that names another file, or a file the game does not have (the game's code runs before the migration and could shape it).
• Judged before it is written. The migrated game is judged on the worker as the health judges a revision: the validator, then the solver from a new game, bounded in time. A game the migration would break (an id the tool could not write, a list built by code, a game that can no longer be finished), or that the solver cannot judge in time, is refused with a 422 (errors, skipped: what the tool could not write), and the head stays as it was.
• One revision. Otherwise the changed files are written as one operation, through the validation guard.

The former name

Applies from 4.3.0

A game that still imports web-scumm/… does not load on a 4.3.0 Studio or later (the aliases are gone): its health is not green and the guard refuses its writes (a 422: the game still does not load). The upgrade first renames those imports itself, in every TypeScript source of the head (no game code involved), as a revision of its own, engine upgrade: the former name's imports renamed, judged by the validator alone: the game must load after it and, if it loaded before, gain no error. The solver does not judge it, so a game that cannot be finished yet is never stuck. The schema's migration follows, judged as above; when it is refused, the answer's body.renamed says the rename was kept.

The rename is written without an undo (an undo would bring back imports that no longer resolve), so the owner's earlier history stays reachable; a backup taken before is the way back. A worker that refuses, times out or leaves no result while the guard asks never counts as the game not loading: the write fails (503) and the next one asks again.

Guarantee · engine-upgrade-judged-first · referenced · scope self-checked by the author (AI), not reviewed A game the migration would break is refused before anything is written, and the head stays intact.

Limit · engine-upgrade-scope The project's tsconfig.json (baseUrl, which quest-n-click migrate also fixes) is not part of a hosted game and is left alone. The playtests (playtests/) are neither migrated nor judged. A game whose defineGame is not in game.ts is refused: migrate it on a local Studio.

Expected result, and how to check it

The header shows the new revision(s); the history lists engine upgrade: …; the health turns green for the new head. A second call answers { "changed": 0 }.

Common errors

Symptom	Cause	Fix
422 refused: the migration would break the game (…); nothing was written	An id the tool could not write, a list built by code, a game that can no longer be finished	Migrate it on a local Studio (quest-n-click migrate, then npm run ids to see what is left) and import it again, or fix it first
422 refused: the migrated game cannot be judged (…); nothing was written	The solver ran out of time	The same: migrate locally
422 refused: the game still does not load once its imports are renamed (…)	Something else than the name keeps it from loading	Fix the game locally
422 refused: renaming the imports adds N validation error(s)	The rename would add errors	Fix them locally
429 the engine's upgrade is running: try again when it is done	Another upgrade runs	Wait
423 for the others while it runs	The exclusive lease	Expected; they write again once it ends
404 the engine's upgrade needs a hosted Studio with its processing worker	No worker, or a local server	Use quest-n-click migrate locally

Files or data changed

rooms/*.ts, rules.ts, items.ts, game.ts, the translation tables, ids.migration.json, ids.paths.json; for the former name, every TypeScript source that imported web-scumm/….

Recovery or going back

• The schema's migration: the owner's Undo takes it back as a new revision (409 if someone wrote one of its files since).
• The rename: not undoable; restore the backup taken before (see Restore drill).

References

• Upgrade, Upgrade notes: 4.3.
• tests/studio-engine-upgrade.test.ts.

---

Edit the source of this page · Report an error