Levels

Level discovery, metadata, and loading system. Scans `/levels/` for available maps, enriches data with previews/spawn points/mod info, and provides the API for starting levels.

Level discovery, metadata, and loading system. Scans /levels/ for available maps, enriches data with previews/spawn points/mod info, and provides the API for starting levels.

Public Functions

Function	Signature	Description
`M.getList`	`() → table`	Returns cached array of all level info objects
`M.getListWithStats`	`() → {levels, uiStats}`	Returns levels with UI stats from `freeroam_levelStats`
`M.getLevelNames`	`() → table`	Returns array of level name strings
`M.getSimpleList`	`() → table`	Alias for `getLevelNames` (backward compat)
`M.getLevelByName`	`(levelName) → info`	Finds a level by name (case-insensitive)
`M.getLevelTitle`	`(levelName) → string`	Returns the display title (cached)
`M.getLevelPreview`	`(levelName) → string`	Returns the first preview image path (cached)
`M.getTimeOfDayOptions`	`(levelName) → table`	Returns time-of-day presets for a level
`M.getLevelPaths`	`() → table`	Returns array of level directory paths
`M.startLevel`	`(levelPath, delayedStart, customLoadFn, spawnVehicle)`	Loads a level with optional vehicle spawn
`M.expandMissionFileName`	`(missionFileName) → string`	Resolves `.mis`/`.level.json` file paths
`M.getLevelName`	`(path) → string`	Extracts level name from a file path
`M.requestData`	`()`	Sends level list to UI via `onLevelsChanged`
`M.maybeSpawnDefaultVehicle`	`()`	Spawns the default or requested vehicle after level load
`M.onFilesChanged`	`(files)`	Invalidates cache when level files change
`M.onClientPostStartMission`	`()`	Regenerates DecalRoads after mission start
`M.onGetRawPoiListForLevel`	`(levelId, elements)`	Provides spawn point POIs for the bigmap
`M.dependencies`	Table. Required extensions: `{'freeroam_levelStats'}`
`M.levelsDir`	String. Levels directory path (`'/levels/'`). Backward compatibility.

Level Info Object

Field	Type	Description
`levelName`	string	Directory name of the level
`dir`	string	Full directory path
`fullfilename`	string	Entry point file path
`title`	string	Display name
`previews`	table	Array of preview image paths
`spawnPoints`	table	Array of spawn point definitions
`modID`	string	Mod identifier (nil for official)
`official`	boolean	Whether the level is official content
`supportsTraffic`	boolean	Traffic support (default `true`)
`supportsTimeOfDay`	boolean	Time-of-day support (default `true`)

Module State

Variable	Type	Default
`dependencies`	`table`	`{ "freeroam_levelStats" }`

Usage Example

-- Get all levels
local levels = core_levels.getList()
for _, level in ipairs(levels) do
  print(level.levelName .. ": " .. (level.title or "untitled"))
end

-- Find a specific level
local gridmap = core_levels.getLevelByName("gridmap")
if gridmap then
  print("Found: " .. gridmap.dir)
end

-- Start a level with default vehicle
core_levels.startLevel("levels/gridmap/main/", false, nil, nil)

-- Start a level without spawning a vehicle
core_levels.startLevel("levels/utah/main/", false, nil, false)

Dependencies

freeroam_levelStats - Provides UI stats for getListWithStats

Notes

Levels with both .mis and .level.json formats automatically prefer the JSON version.
The cache is invalidated when any file under /levels/ changes.
Spawn points can be filtered by career discovery status.
levelsDir is exposed as /levels/ for backward compatibility.

Public Functions

Function	Signature	Description
`M.getList`	`() → table`	Returns cached array of all level info objects
`M.getListWithStats`	`() → {levels, uiStats}`	Returns levels with UI stats from `freeroam_levelStats`
`M.getLevelNames`	`() → table`	Returns array of level name strings
`M.getSimpleList`	`() → table`	Alias for `getLevelNames` (backward compat)
`M.getLevelByName`	`(levelName) → info`	Finds a level by name (case-insensitive)
`M.getLevelTitle`	`(levelName) → string`	Returns the display title (cached)
`M.getLevelPreview`	`(levelName) → string`	Returns the first preview image path (cached)
`M.getTimeOfDayOptions`	`(levelName) → table`	Returns time-of-day presets for a level
`M.getLevelPaths`	`() → table`	Returns array of level directory paths
`M.startLevel`	`(levelPath, delayedStart, customLoadFn, spawnVehicle)`	Loads a level with optional vehicle spawn
`M.expandMissionFileName`	`(missionFileName) → string`	Resolves `.mis`/`.level.json` file paths
`M.getLevelName`	`(path) → string`	Extracts level name from a file path
`M.requestData`	`()`	Sends level list to UI via `onLevelsChanged`
`M.maybeSpawnDefaultVehicle`	`()`	Spawns the default or requested vehicle after level load
`M.onFilesChanged`	`(files)`	Invalidates cache when level files change
`M.onClientPostStartMission`	`()`	Regenerates DecalRoads after mission start
`M.onGetRawPoiListForLevel`	`(levelId, elements)`	Provides spawn point POIs for the bigmap
`M.dependencies`	Table. Required extensions: `{'freeroam_levelStats'}`
`M.levelsDir`	String. Levels directory path (`'/levels/'`). Backward compatibility.

Level Info Object

Field	Type	Description
`levelName`	string	Directory name of the level
`dir`	string	Full directory path
`fullfilename`	string	Entry point file path
`title`	string	Display name
`previews`	table	Array of preview image paths
`spawnPoints`	table	Array of spawn point definitions
`modID`	string	Mod identifier (nil for official)
`official`	boolean	Whether the level is official content
`supportsTraffic`	boolean	Traffic support (default `true`)
`supportsTimeOfDay`	boolean	Time-of-day support (default `true`)

Module State

Variable	Type	Default
`dependencies`	`table`	`{ "freeroam_levelStats" }`

Usage Example

-- Get all levels
local levels = core_levels.getList()
for _, level in ipairs(levels) do
  print(level.levelName .. ": " .. (level.title or "untitled"))
end

-- Find a specific level
local gridmap = core_levels.getLevelByName("gridmap")
if gridmap then
  print("Found: " .. gridmap.dir)
end

-- Start a level with default vehicle
core_levels.startLevel("levels/gridmap/main/", false, nil, nil)

-- Start a level without spawning a vehicle
core_levels.startLevel("levels/utah/main/", false, nil, false)

Dependencies

freeroam_levelStats - Provides UI stats for getListWithStats

Notes

Levels with both .mis and .level.json formats automatically prefer the JSON version.
The cache is invalidated when any file under /levels/ changes.
Spawn points can be filtered by career discovery status.
levelsDir is exposed as /levels/ for backward compatibility.

Levels

Public Functions

Level Info Object

Module State

Usage Example

Dependencies

Notes

See Also

On this page

Levels

Public Functions

Level Info Object

Module State

Usage Example

Dependencies

Notes

See Also

On this page