Checkpoints & Snapshots

What snapshots are for

Snapshots are runtime checkpoints for map state. They are typically used at game level (save points, retries, respawn flows), even though the data they store is map-backed.

Main APIs:

• saveSnapshot([replaceSnapshotId])
• loadSnapshot(snapshotId)
• deleteSnapshot(snapshotId)

Snapshot scope

Snapshots store map state for the current logical level only — whichever level was last targeted by loadMapEntities or loadMapLayerEntities.

They include:

• level tiles
• map-node runtime state in that level

They do not include:

• inventory / story flags / custom globals
• script-spawned non-map entities
• anything outside the saved level scope

API behavior

• saveSnapshot([replaceSnapshotId])
  • returns a numeric snapshot id
  • if replaceSnapshotId is provided, overwrites that checkpoint id (rolling checkpoint pattern)
• loadSnapshot(snapshotId)
  • restores saved map state
  • respawns map Lua instances for the saved level
  • returns success and (on success) savedLevelIndex
• deleteSnapshot(snapshotId)
  • frees the snapshot from memory

Snapshot ids are runtime-memory ids; they are not stable across a full reload/new cart session.

Important interaction with map loading

loadMapEntities(level) always performs a fresh reset-from-cart + respawn for that level.

So:

• loadSnapshot(id) restores checkpoint state
• calling loadMapEntities(level) immediately after that will overwrite the restore with fresh cart defaults

Use one or the other based on intent:

• fresh restart of a level: loadMapEntities(level)
• resume from checkpoint: loadSnapshot(id)

Example checkpoint flow

Copy
local checkpointId = 0

function setCheckpoint()
  checkpointId = saveSnapshot(checkpointId ~= 0 and checkpointId or nil)
end

function respawnFromCheckpoint()
  if checkpointId == 0 then return false end
  local ok, savedLevel = loadSnapshot(checkpointId)
  if not ok then return false end
  -- optional: reset camera/UI based on savedLevel
  return true
end

function clearCheckpoint()
  if checkpointId ~= 0 then
    deleteSnapshot(checkpointId)
    checkpointId = 0
  end
end

Related pages

• Loading Map Entities
• API Reference / Maps