Gameplay Statistics

Reference for `gameplay_statistic`, the central metrics engine that records, persists, and reports gameplay statistics. Supports both global and career-scoped data with timers, callbacks, and a schedu

Reference for gameplay_statistic, the central metrics engine that records, persists, and reports gameplay statistics. Supports both global and career-scoped data with timers, callbacks, and a scheduling system for per-frame stat modules.

Module Exports (M)

Metrics

Function	Signature	Description
`metricAdd`	`(name, value, aggregate?)`	Adds `value` to the metric (cumulative). Optional aggregate tracks min/max/count/last
`metricSet`	`(name, value, aggregate?)`	Sets metric to `value`. Optional aggregate tracks min/max/count
`metricGet`	`(name, career?)` → table\|nil	Returns a deep copy of the metric entry. Pass `true` for career data

Timers

Function	Signature	Description
`timerStart`	`(name, increment?, aggregate?, useSimTime?)`	Starts a named timer. `increment=true` adds to existing value
`timerStop`	`(name)` → number	Stops the timer and writes elapsed time as a metric
`forceTimerUpdate`	`()`	Flushes all active timers to their metrics

Callbacks

Function	Signature	Description
`callbackRegister`	`(name, trigger, func, career?)`	Registers a callback when metric `name` reaches `trigger` value
`callbackRemove`	`(name, trigger, func, career?)` → bool	Removes a registered callback

Schedule

Function	Signature	Description
`addSchedule`	`(fn)`	Adds a per-frame workload function (called round-robin)
`removeSchedule`	`(fn)` → bool	Removes a scheduled function

UI & Debug

Function	Signature	Description
`sendGUIState`	`()`	Sends all stats to UI via `StatisticData` guihook
`setDebug`	`(bool)`	Opens/closes the ImGui debug window

Hooks / Lifecycle

Function	Description
`onInit`	Loads global stats from JSON
`onExit`	Flushes timers and saves
`onExtensionUnloaded`	Flushes timers and saves
`onExtensionLoaded`	Loads statistic submodules
`onSerialize`	Saves data and returns state for hot-reload
`onDeserialized`	Restores state after hot-reload
`onSaveCurrentSaveSlot`	Saves career stats into save slot
`onCareerActive`	Loads/unloads career-specific stats
`onClientStartMission`	Starts activity timer for current level
`onClientEndMission`	Ends current activity timer
`onClientPostStartMission`	Starts activity and loads submodules
`onWorldReadyState`	World ready callback (currently unused)
`onEditorActivated`	Starts editor timer
`onEditorDeactivated`	Stops editor timer
`onScenarioLoaded`	Restarts activity tracking
`onScenarioFinished`	Records scenario completion metric
`onScenarioRestarted`	Records scenario restart metric
`onUpdate`	Increments timers, runs scheduled workloads, renders debug UI
`onVehicleSwitched`	Tracks player vehicle change, records switch metric
`onVehicleResetted`	Records vehicle reset metric
`onVehicleDestroyed`	Clears player vehicle reference
`onGameStateUpdate`	Restarts activity tracking on game state change
`M.addSchedule`	`(fn)`
`M.callbackRegister`	`(name, trigger, callbackFunction, career)`
`M.callbackRemove`	`(name, trigger, callbackFunction, career)`
`M.dependencies`	value
`M.forceTimerUpdate`	`()`
`M.metricAdd`	`(name,value,aggregate)`
`M.metricGet`	`(name, carreer)`
`M.metricSet`	`(name,value,aggregate)`
`M.onCareerActive`	`(active)`
`M.onClientEndMission`	`(levelPath)`
`M.onClientPostStartMission`	`(levelPath)`
`M.onClientStartMission`	`(levelPath)`
`M.onDeserialized`	`(data)`
`M.onEditorActivated`	`()`
`M.onEditorDeactivated`	`()`
`M.onExit`	`()`
`M.onExtensionLoaded`	`()`
`M.onExtensionUnloaded`	`()`
`M.onGameStateUpdate`	`(newState)`
`M.onInit`	`()`
`M.onSaveCurrentSaveSlot`	`(currentSavePath)`
`M.onScenarioFinished`	`(scenario)`
`M.onScenarioLoaded`	`(scenario)`
`M.onScenarioRestarted`	`(scenario)`
`M.onSerialize`	`()`
`M.onUpdate`	`(dtReal, dtSim, dtRaw)`
`M.onVehicleDestroyed`	`(vid)`
`M.onVehicleResetted`	`(vid)`
`M.onVehicleSwitched`	`(oldid, newid, player)`
`M.onWorldReadyState`	`(worldReadyState)`
`M.removeSchedule`	`(fn)`
`M.sendGUIState`	`()`
`M.setDebug`	`(newValue)`
`M.timerStart`	`(name, increment, aggregate, useSimTime)`
`M.timerStop`	`(name)`

Internals

Save file (global): /settings/cloud/gameplay_stat.json
Save file (career): <saveslot>/career/gameplay_stat.json
Format: {version = 1, entries = {[name] = {value, count?, min?, max?, last?}}}
Dual storage: Every metricAdd/metricSet call writes to both global and career data (if career active)
Scheduling: Submodules from gameplay/statisticModules/ are loaded dynamically; their workload function is called round-robin each frame (one module per frame)

Metric Entry Format

{
  value = 42.5,     -- accumulated/current value
  last = 2.1,       -- last added value (aggregate only)
  count = 10,       -- number of additions (aggregate only)
  min = 0.5,        -- minimum value seen (aggregate only)
  max = 8.3         -- maximum value seen (aggregate only)
}

How It Works

On init, loads global stats from JSON file
On career activation, loads career-specific stats from save slot
onClientPostStartMission starts activity timers and loads submodules
onUpdate increments real/sim timers and calls one scheduled workload per frame
Activity tracking auto-categorizes time by mode (freeroam/career/scenario) and level
Callbacks fire when a metric reaches a threshold; one-shot callbacks auto-remove

Usage Example

-- Track a gameplay event
gameplay_statistic.metricAdd("vehicle/burnout.time", dtSim, true)

-- Read a stat
local data = gameplay_statistic.metricGet("vehicle/jturn", true) -- career
if data then
  log("I", "", "J-turns in career: " .. data.value)
end

-- Timer usage
gameplay_statistic.timerStart("myMod/lapTime", false, false, true) -- sim time, non-increment
-- ... later ...
local elapsed = gameplay_statistic.timerStop("myMod/lapTime")

-- Register a callback
gameplay_statistic.callbackRegister("vehicle/rollover", 5, function(name, old, new)
  log("I", "", "5 rollovers reached!")
end, true) -- career-scoped

Module Exports (M)

Metrics

Function	Signature	Description
`metricAdd`	`(name, value, aggregate?)`	Adds `value` to the metric (cumulative). Optional aggregate tracks min/max/count/last
`metricSet`	`(name, value, aggregate?)`	Sets metric to `value`. Optional aggregate tracks min/max/count
`metricGet`	`(name, career?)` → table\|nil	Returns a deep copy of the metric entry. Pass `true` for career data

Timers

Function	Signature	Description
`timerStart`	`(name, increment?, aggregate?, useSimTime?)`	Starts a named timer. `increment=true` adds to existing value
`timerStop`	`(name)` → number	Stops the timer and writes elapsed time as a metric
`forceTimerUpdate`	`()`	Flushes all active timers to their metrics

Callbacks

Function	Signature	Description
`callbackRegister`	`(name, trigger, func, career?)`	Registers a callback when metric `name` reaches `trigger` value
`callbackRemove`	`(name, trigger, func, career?)` → bool	Removes a registered callback

Schedule

Function	Signature	Description
`addSchedule`	`(fn)`	Adds a per-frame workload function (called round-robin)
`removeSchedule`	`(fn)` → bool	Removes a scheduled function

UI & Debug

Function	Signature	Description
`sendGUIState`	`()`	Sends all stats to UI via `StatisticData` guihook
`setDebug`	`(bool)`	Opens/closes the ImGui debug window

Hooks / Lifecycle

Function	Description
`onInit`	Loads global stats from JSON
`onExit`	Flushes timers and saves
`onExtensionUnloaded`	Flushes timers and saves
`onExtensionLoaded`	Loads statistic submodules
`onSerialize`	Saves data and returns state for hot-reload
`onDeserialized`	Restores state after hot-reload
`onSaveCurrentSaveSlot`	Saves career stats into save slot
`onCareerActive`	Loads/unloads career-specific stats
`onClientStartMission`	Starts activity timer for current level
`onClientEndMission`	Ends current activity timer
`onClientPostStartMission`	Starts activity and loads submodules
`onWorldReadyState`	World ready callback (currently unused)
`onEditorActivated`	Starts editor timer
`onEditorDeactivated`	Stops editor timer
`onScenarioLoaded`	Restarts activity tracking
`onScenarioFinished`	Records scenario completion metric
`onScenarioRestarted`	Records scenario restart metric
`onUpdate`	Increments timers, runs scheduled workloads, renders debug UI
`onVehicleSwitched`	Tracks player vehicle change, records switch metric
`onVehicleResetted`	Records vehicle reset metric
`onVehicleDestroyed`	Clears player vehicle reference
`onGameStateUpdate`	Restarts activity tracking on game state change
`M.addSchedule`	`(fn)`
`M.callbackRegister`	`(name, trigger, callbackFunction, career)`
`M.callbackRemove`	`(name, trigger, callbackFunction, career)`
`M.dependencies`	value
`M.forceTimerUpdate`	`()`
`M.metricAdd`	`(name,value,aggregate)`
`M.metricGet`	`(name, carreer)`
`M.metricSet`	`(name,value,aggregate)`
`M.onCareerActive`	`(active)`
`M.onClientEndMission`	`(levelPath)`
`M.onClientPostStartMission`	`(levelPath)`
`M.onClientStartMission`	`(levelPath)`
`M.onDeserialized`	`(data)`
`M.onEditorActivated`	`()`
`M.onEditorDeactivated`	`()`
`M.onExit`	`()`
`M.onExtensionLoaded`	`()`
`M.onExtensionUnloaded`	`()`
`M.onGameStateUpdate`	`(newState)`
`M.onInit`	`()`
`M.onSaveCurrentSaveSlot`	`(currentSavePath)`
`M.onScenarioFinished`	`(scenario)`
`M.onScenarioLoaded`	`(scenario)`
`M.onScenarioRestarted`	`(scenario)`
`M.onSerialize`	`()`
`M.onUpdate`	`(dtReal, dtSim, dtRaw)`
`M.onVehicleDestroyed`	`(vid)`
`M.onVehicleResetted`	`(vid)`
`M.onVehicleSwitched`	`(oldid, newid, player)`
`M.onWorldReadyState`	`(worldReadyState)`
`M.removeSchedule`	`(fn)`
`M.sendGUIState`	`()`
`M.setDebug`	`(newValue)`
`M.timerStart`	`(name, increment, aggregate, useSimTime)`
`M.timerStop`	`(name)`

Internals

Save file (global): /settings/cloud/gameplay_stat.json
Save file (career): <saveslot>/career/gameplay_stat.json
Format: {version = 1, entries = {[name] = {value, count?, min?, max?, last?}}}
Dual storage: Every metricAdd/metricSet call writes to both global and career data (if career active)
Scheduling: Submodules from gameplay/statisticModules/ are loaded dynamically; their workload function is called round-robin each frame (one module per frame)

Metric Entry Format

{
  value = 42.5,     -- accumulated/current value
  last = 2.1,       -- last added value (aggregate only)
  count = 10,       -- number of additions (aggregate only)
  min = 0.5,        -- minimum value seen (aggregate only)
  max = 8.3         -- maximum value seen (aggregate only)
}

How It Works

On init, loads global stats from JSON file
On career activation, loads career-specific stats from save slot
onClientPostStartMission starts activity timers and loads submodules
onUpdate increments real/sim timers and calls one scheduled workload per frame
Activity tracking auto-categorizes time by mode (freeroam/career/scenario) and level
Callbacks fire when a metric reaches a threshold; one-shot callbacks auto-remove

Usage Example

-- Track a gameplay event
gameplay_statistic.metricAdd("vehicle/burnout.time", dtSim, true)

-- Read a stat
local data = gameplay_statistic.metricGet("vehicle/jturn", true) -- career
if data then
  log("I", "", "J-turns in career: " .. data.value)
end

-- Timer usage
gameplay_statistic.timerStart("myMod/lapTime", false, false, true) -- sim time, non-increment
-- ... later ...
local elapsed = gameplay_statistic.timerStop("myMod/lapTime")

-- Register a callback
gameplay_statistic.callbackRegister("vehicle/rollover", 5, function(name, old, new)
  log("I", "", "5 rollovers reached!")
end, true) -- career-scoped

Gameplay Statistics

Module Exports (M)

Metrics

Timers

Callbacks

Schedule

UI & Debug

Hooks / Lifecycle

Internals

Metric Entry Format

How It Works

Usage Example

See Also

On this page

Gameplay Statistics

Module Exports (M)

Metrics

Timers

Callbacks

Schedule

UI & Debug

Hooks / Lifecycle

Internals

Metric Entry Format

How It Works

Usage Example

See Also

On this page