# Engine iterations

Every Virtual Matter world runs on one engine iteration, such as iteration076. An
iteration is a release branch of the engine: within one iteration a world picks up
newer builds as they ship, and those keep the Lua API the same. Moving to a new
iteration can change the Lua API, the shaders and the network protocol, so a world
only moves when its maker, or the platform with notice, moves it.

## See which iteration a world runs

- The project page shows the editor's iteration next to Engine, and each play server's
  iteration on its own row. A warning appears when they differ, or when the running
  engine is still on an older build than the one the world is set to.
- `npx virtualmatter status` prints the same, and so does the `play_server_status`
  MCP tool.
- In Lua, `AE:GetVersion()` returns the running engine's version: 76.x is iteration076.
- The boot log names it on its first lines: `Version (Major.Minor.Revision.Build): 76.0...`
  and `Git branch: release/iteration076`.

## Move a world

1. On the project page, press Update next to Engine and pick the build. Leave "Also
   update base prefabs" on unless you changed the SDK's own scripts: it refreshes the
   stock SDK files to the new iteration and saves your files to GitHub first.
2. The editor restarts on the new iteration. Check `npx virtualmatter errors` and the
   boot log, and play it.
3. Publish (Update play servers, or `npx virtualmatter publish`). This moves the play
   servers to the editor's iteration too: until then they keep running the old one.

To try an iteration without risking the live world, remix the project (Remix on its
page), move the copy, and test there. The original and its play servers stay where they
are.

When the platform moves worlds to a new iteration, the maker is told before it happens:
on the project page, in `npx virtualmatter status`, and by email.

The desktop app plays worlds of its own iteration only. `npx virtualmatter open`
downloads the client that matches the world, and keeps one client per iteration.

## iteration076

Changes since iteration073 (iteration075 lived for a few days in between; the only API
difference from 075 is the sky). A world moving from 073 hits the first group straight
away, usually inside `pcall`, where the failure is silent.

Moved or now takes an Asset instead of a path:

- `VoxelData.receiveTransform` moved to `Object.receiveTransform` (on the object, not
  its voxel component). Writing an unknown field on an engine object throws.
- `Audio:PlaySound` and `Audio:PlaySoundRelative` take a sound Asset, not a path string.
- `Object:AddScript` takes a LuaFile Asset, not a file name.
- `Server:PreloadVDRsForPrefab` takes a prefab Asset, not a name.
- `UI:AddWindow` takes a name or a Lua Asset, not the old save flag.
- `VoxelEdit.imageColor` and `VoxelEdit.imageNormal` accept an Asset or AssetLink;
  `VoxelEdit:GetImageResource` is gone.

Removed:

- The `Sky` component and `Object:AddSkybox`. The sky is now set on the client:
  `Client:SetSky`, `Client:SetSkyLook`, `Client:SetSunDirection`, `Client:SetSkyEnabled`,
  `Client:ClearSky` and the matching getters.
- `Script.file`, `Object.voxelRenderer`, `Object.preserveOnLuaReset`.
- `Scene:CreateMaterial`, `Scene.voxelDataResourceTemplateSizeThreshold`.
- Init mode: `Server:EnterInitMode`, `Server:EnterLiveMode`, `Server:IsInitMode`,
  `Client:IsInitMode`, and `Client:ConnectToServer`.
- `Client.platform` and `Client.sysInfo`.
- `UI:SaveUI`, `UI.showUI`, `Widget.save`, `Window.noHide` and the Window asset list
  (`Window:AddAsset`, `Window:GetAsset`, `Window:GetAssets` and the rest).
- The `Mat3x4` type.
- The debug triggers `TriggerCrash`, `TriggerCriticalError`, `TriggerException`.

Changed behaviour:

- `Scene:CloneObject(obj, name, setSaveToFalse)`: the third argument used to be
  `keepPrefabLink`.
- `Server:SaveToPlayScene(enterSession)` takes an argument.
- `Scene:GetObjectByName`, `Scene:GetObjectById`, `Scene:GetActiveCamera` and
  `UI:CloneWidget` can return nil; `Scene:MoveObject` and its siblings return whether
  the move happened.
- Brush and voxel-edit callbacks receive more: `OnFinished` gets the result info,
  `VoxelEdit.onError` gets the reason and the op count, `VoxelEdit.onFinished` gets a status.
- `UI:LoadUI()` takes no path; `UI:AddWidget` lost its save argument.

New: shader errors (`Client:GetShaderErrors`, `Client:RequestReloadShaders`,
`Client:SetVPuzzleShaderDefines`), Lua GC mode (`AE:SetLuaGCMode`), video and vsync modes,
`Vox:flushEdits` and `Vox:pendingEdits`, `OpBase:Batch`, script metadata
(`AE:GetScriptMetadata`), `Client:IsInitialAssetSyncDone`, and the `util.whenAssetsReady`
and `util.whenAssetsSynced` helpers for assets a client is still downloading.

Shaders: a world's own copies under `Shaders/` override the engine's by asset id. At
boot the engine refreshes copies you never edited and keeps edited ones, logging one
line: `Montage shader overrides ... maker-edited kept`. An edited copy keeps working
only if it still matches the engine's inputs, so diff your edited shaders against the
new iteration's stock ones after a move.

Network: a 076 client speaks a newer scene and voxel stream protocol than 073, so a
desktop app of one iteration cannot join a world of the other.