`setSpawnpoint` - Default Spawn Point Persistence

Manages per-level default spawn point selection. Saves and loads the player's chosen spawn point to/from settings/cloud/game-state.json.

Exports

Fields

How It Works

Saving a Default Spawn Point

setDefaultSP writes the chosen spawn point name into the cloud-synced game-state file, keyed by level name:

-- User picks "garage_spawn" on "west_coast_usa"
setSpawnpoint.setDefaultSP("garage_spawn", "west_coast_usa")

-- Resulting JSON structure:
-- {
--   "lastLevelName": "west_coast_usa",
--   "levels": {
--     "west_coast_usa": {
--       "defaultSpawnPointName": "garage_spawn"
--     }
--   }
-- }

The level name is always lowercased. If no level name is provided, it falls back to core_levels.getLevelName(getMissionFilename()).

Loading the Default Spawn Point

loadDefaultSpawnpoint reads the saved spawn point name and validates it:

1. Reads the level's info.json via path.getPathLevelInfo(levelName)
2. Iterates levelInfo.spawnPoints looking for a match with the saved name
3. Confirms the object exists in the scene tree via scenetree.findObject()
4. Returns the name if valid, otherwise falls back to levelInfo.defaultSpawnPointName or ""

-- Get the default spawn point for the current level
local spName = setSpawnpoint.loadDefaultSpawnpoint()
if spName ~= "" then
  local sp = scenetree.findObject(spName)
  -- use sp:getPosition(), sp:getRotation()
end

-- Or for a specific level
local spName = setSpawnpoint.loadDefaultSpawnpoint("italy")

Getting Last Level

local lastLevel = setSpawnpoint.getLastLevelName()
-- Returns nil if no game-state file or no lastLevelName recorded

Internals

• Storage format: JSON file at settings/cloud/game-state.json, cloud-synced across sessions
• Validation: The saved spawn point is validated against both the level's info.json spawn point list AND the live scene tree - if the object doesn't exist in the mission, it falls back gracefully
• Level name normalization: Always lowercased via levelName:lower()

Typical Usage

This module is primarily used by spawn.pickSpawnPoint(), which calls loadDefaultSpawnpoint() to determine where to place the player vehicle when loading a level. The UI calls setDefaultSP() when the player selects a spawn point from the level menu.

-- In spawn.lua's pickSpawnPoint():
local defaultSpawnPoint = setSpawnpoint.loadDefaultSpawnpoint()
if defaultSpawnPoint then
  local spawnPoint = scenetree.findObject(defaultSpawnPoint)
  if spawnPoint then
    return spawnPoint
  end
end

Additional Exports