Freeroam Configurator

Manages the freeroam configuration screen - level/spawn point selection, vehicle selection, and gameplay options. Persists configuration to disk and provides tile data for the UI.

Internal State

Field	Type	Description
`M.dependencies`	varies	Assigned as `{}`

Public API

Function	Signature	Returns	Description
`M.getConfiguration`	`()`	`table`	Returns current config with options, spawn point tile, vehicle tile
`M.getButtons`	`()`	`table`	Returns the primary action button (Start Freeroam)
`M.triggerButton`	`(buttonId, ...)`	`nil`	Saves config, applies options, executes button action
`M.updateOption`	`(key, value)`	`nil`	Updates a configuration option
`M.setSpawnPoint`	`(levelName, spawnPointName, key?)`	`nil`	Sets level and spawn point, caches tile
`M.setVehicle`	`(model, config, additionalData?, key?)`	`nil`	Sets vehicle choice, caches tile
`M.getCurrentVehicle`	`()`	`table`	Returns `{model, config, additionalData}`
`M.getCurrentSpawnPointTile`	`()`	`table\|nil`	Returns cached spawn point tile with validation
`M.getCurrentVehicleTile`	`()`	`table\|nil`	Returns cached vehicle tile with validation
`M.onSpawnPointTileClick`	`()`	`nil`	Opens level/spawn selector UI
`M.onVehicleTileClick`	`()`	`nil`	Opens vehicle selector UI
`M.startFreeroam`	`(configuration)`	`nil`	Launches freeroam with the given configuration
`M.validateFiles`	`(validationFiles)`	`boolean`	Checks if all referenced files/dirs still exist

| M.doubleClickOverride | (item) | - | | M.onDeserialized | (data) | - | | M.onSerialize | () | - |

Configuration Structure

{
  levelName = "west_coast_usa",
  spawnPointName = "spawns_industrial",
  options = {
    traffic_trafficMode = "disabled",
    environment_timeOfDay = "default",
    environment_timePlay = "disabled"
  },
  vehicle = {
    model = "pickup",
    config = "d15_4wd_A",
    additionalData = { paint = "Sea Blue", ... }
  },
  spawnPointTile = { ... }, -- cached UI tile data
  vehicleTile = { ... },   -- cached UI tile data
}

How It Works

Load: On first access, reads settings/freeroamConfigurator.json; falls back to defaults (pickup or ETK800 depending on license)
Options: Gathers options from all extensions in configuratorOptions/ via onFreeroamConfiguratorGetOptions hook
Tile Caching: Spawn point and vehicle tiles are fetched once and cached; validated on read against validationFiles
Save: Dirty configs are saved on serialize or button trigger
Start: Resolves vehicle paints by name, calls freeroam_freeroam.startFreeroamByName()

Hooks

Hook	Purpose
`onFreeroamConfiguratorGetOptions`	Gathers option groups from option providers
`onFreeroamConfiguratorApplyOptions`	Applies selected options before start
`onFreeroamConfiguratorOverrideStartButton`	Allows overriding the start button

Notes

Config file: settings/freeroamConfigurator.json with version checking
Default vehicle differs between tech license (ETK800) and drive license (pickup)
Default tiles loaded from configuratorOptions/defaultTiles.json
Dependencies auto-discovered from configuratorOptions/*.lua files

Internal State

Field	Type	Description
`M.dependencies`	varies	Assigned as `{}`

Public API

Function	Signature	Returns	Description
`M.getConfiguration`	`()`	`table`	Returns current config with options, spawn point tile, vehicle tile
`M.getButtons`	`()`	`table`	Returns the primary action button (Start Freeroam)
`M.triggerButton`	`(buttonId, ...)`	`nil`	Saves config, applies options, executes button action
`M.updateOption`	`(key, value)`	`nil`	Updates a configuration option
`M.setSpawnPoint`	`(levelName, spawnPointName, key?)`	`nil`	Sets level and spawn point, caches tile
`M.setVehicle`	`(model, config, additionalData?, key?)`	`nil`	Sets vehicle choice, caches tile
`M.getCurrentVehicle`	`()`	`table`	Returns `{model, config, additionalData}`
`M.getCurrentSpawnPointTile`	`()`	`table\|nil`	Returns cached spawn point tile with validation
`M.getCurrentVehicleTile`	`()`	`table\|nil`	Returns cached vehicle tile with validation
`M.onSpawnPointTileClick`	`()`	`nil`	Opens level/spawn selector UI
`M.onVehicleTileClick`	`()`	`nil`	Opens vehicle selector UI
`M.startFreeroam`	`(configuration)`	`nil`	Launches freeroam with the given configuration
`M.validateFiles`	`(validationFiles)`	`boolean`	Checks if all referenced files/dirs still exist

| M.doubleClickOverride | (item) | - | | M.onDeserialized | (data) | - | | M.onSerialize | () | - |

Configuration Structure

{
  levelName = "west_coast_usa",
  spawnPointName = "spawns_industrial",
  options = {
    traffic_trafficMode = "disabled",
    environment_timeOfDay = "default",
    environment_timePlay = "disabled"
  },
  vehicle = {
    model = "pickup",
    config = "d15_4wd_A",
    additionalData = { paint = "Sea Blue", ... }
  },
  spawnPointTile = { ... }, -- cached UI tile data
  vehicleTile = { ... },   -- cached UI tile data
}

How It Works

Load: On first access, reads settings/freeroamConfigurator.json; falls back to defaults (pickup or ETK800 depending on license)
Options: Gathers options from all extensions in configuratorOptions/ via onFreeroamConfiguratorGetOptions hook
Tile Caching: Spawn point and vehicle tiles are fetched once and cached; validated on read against validationFiles
Save: Dirty configs are saved on serialize or button trigger
Start: Resolves vehicle paints by name, calls freeroam_freeroam.startFreeroamByName()

Hooks

Hook	Purpose
`onFreeroamConfiguratorGetOptions`	Gathers option groups from option providers
`onFreeroamConfiguratorApplyOptions`	Applies selected options before start
`onFreeroamConfiguratorOverrideStartButton`	Allows overriding the start button

Notes

Config file: settings/freeroamConfigurator.json with version checking
Default vehicle differs between tech license (ETK800) and drive license (pickup)
Default tiles loaded from configuratorOptions/defaultTiles.json
Dependencies auto-discovered from configuratorOptions/*.lua files

Freeroam Configurator

Internal State

Public API

Configuration Structure

How It Works

Hooks

Notes

See Also

On this page

Freeroam Configurator

Internal State

Public API

Configuration Structure

How It Works

Hooks

Notes

See Also

On this page