API ReferenceGE Extensionsgameplay
Speed Trap Leaderboards
Reference for `gameplay_speedTrapLeaderboards`, which manages per-level speed trap leaderboard storage. Tracks the top 10 fastest runs through each speed trap trigger in freeroam mode.
Reference for gameplay_speedTrapLeaderboards, which manages per-level speed trap leaderboard storage. Tracks the top 10 fastest runs through each speed trap trigger in freeroam mode.
Module Exports (M)
| Function | Signature | Description |
|---|---|---|
loadLeaderboards | (folderPath?) | Loads all leaderboard JSON files from disk |
saveLeaderboards | (folderPath?, forceOverwrite?) | Saves dirty leaderboards to disk |
addRecord | (speedTrapData, playerSpeed, overSpeed, veh) → bool, table | Adds a record if it qualifies; returns isNewBest + leaderboard |
getLeaderboards | () → table | Returns the full leaderboards table |
Hooks (Event Handlers)
| Hook | Description |
|---|---|
onClientPostStartMission | Auto-loads leaderboards in freeroam |
onClientEndMission | Auto-saves leaderboards in freeroam |
onBeforeCareerActivate | Saves leaderboards before career starts |
onSerialize | Persists state (non-career only) |
onDeserialized | Restores state |
M.addRecord | (speedTrapData, playerSpeed, overSpeed, veh) |
M.getLeaderboards | () |
M.loadLeaderboards | (folderPath) |
M.onBeforeCareerActivate | () |
M.onClientEndMission | () |
M.onClientPostStartMission | (levelPath) |
M.onDeserialized | (data) |
M.onSerialize | () |
M.saveLeaderboards | (folderPath, forceOverwrite) |
Internals
- Save folder:
settings/cloud/speedTrapLeaderboards/ - Leaderboard size: 10 entries max per speed trap
- Dirty tracking: Only levels with new records get saved (
dirtyLevelsmap) - Career guard: Leaderboards are only active outside career mode
Record Entry Format
{
speed = 45.3, -- m/s
modelName = "pickup", -- JBeam model name
date = "2024-01-15T..." -- ISO 8601 UTC timestamp
}How It Works
- On freeroam start,
loadLeaderboards()reads all.jsonfiles from the save folder - When a speed trap fires,
addRecord()checks if the speed qualifies (top 10 or beats slowest entry) - Entries are kept sorted by speed (descending)
- On mission end or career activation, dirty leaderboards are written back to disk
Usage Example
-- Add a speed trap result
local isNewBest, leaderboard = gameplay_speedTrapLeaderboards.addRecord(
{triggerName = "speedTrap1"},
45.3, -- player speed in m/s
10.1, -- over speed limit
veh -- vehicle object
)
-- Read all leaderboards
local boards = gameplay_speedTrapLeaderboards.getLeaderboards()
local currentLevel = getCurrentLevelIdentifier()
local trapBoard = boards[currentLevel] and boards[currentLevel]["speedTrap1"]See Also
- Gameplay Achievement - Related reference
- Gameplay City - Related reference
- discover - Discover / Experience System - Related reference
- Gameplay Systems Guide - Guide
Gameplay Skidpad Test
Simple extension that runs an automated skidpad test - teleports a vehicle to a spawn point and has the AI drive a circular route.
Speed Traps and Cameras
Reference for `gameplay_speedTraps`, which handles speed trap and red light camera trigger events. Fires visual flash effects and dispatches hooks when vehicles exceed speed limits.