For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /guide/editor/updating.md.

Updating a game to a newer editor

A game made with an older Cairn opens in a newer one. The editor brings the project's files up to date when it opens them, and everything you made keeps working: every asset keeps its ID, so nothing that uses one notices.

Before you open it

Commit the project, or copy its folder. The editor renames and rewrites files when it brings a project over, and a newer editor's files may not open in the older one again.

What the editor changes

When it opens the project, the editor does these by itself, and says in the console what it did:

  • Projects from Safi Studio. A .ssproject and its .ssscene, .ssmat, .ssprefab and .ssanimator files get the .cairn extensions, and scripts that name a file by its old extension are changed to match. See Projects from Safi Studio.
  • Prefabs become scenes. Each .cairnprefab file becomes a .cairnscene, and scripts that name one by path or use Field.Prefab are changed to match. See Placing scenes.
  • Code editor definitions. .cairn/api.d.lua and, in a TypeScript project, .cairn/api.d.ts are written again from the new engine, so completion shows what the new version has. Your tsconfig.json and .luarc.json are left as they are.
  • TypeScript. Every script is compiled again with the new editor. A script that no longer compiles is listed in the console, and the game keeps the Lua that compiled last.

If a new file name is taken already, the editor renames nothing and says which file is in the way. Move that file, then open the project again.

An older project can have a hidden .safistudio folder beside .cairn. Nothing reads it any more, and it can be deleted.

What to do yourself

  1. Open the project and read the console. Fix any script error it lists.
  2. Play every scene once. Names in the scripting API that were replaced still work, so an older script runs, but the releases page says what changed.
  3. Save each scene you open. Scene files are read in their old form, and saving writes the new one.
  4. Commit.

Export again

An exported game carries the runtime it was exported with, so a game exported before keeps the old engine. Export it again to give players the new one.

Cairn.app carries runtimes built with its own editor. If you build the engine yourself, the web runtime is a build of its own: run make web again after you update the engine, or a web export carries the old runtime, which may not read what the new editor wrote. The export warns when the web runtime in build-web/ is older than the engine's source. See Exporting a game.