Drag Strip Save System

Reference for `gameplay_drag_saveSystem`, which handles loading drag strip data from JSON, converting legacy formats, managing dial times / race history, and spawning prefabs.

Reference for gameplay_drag_saveSystem, which handles loading drag strip data from JSON, converting legacy formats, managing dial times / race history, and spawning prefabs.

Overview

Central persistence layer for drag racing. Loads strip definitions from level directories, converts between legacy and modular JSON formats, saves/loads dial times with full race history, and manages Christmas tree / display sign / decoration prefabs.

Exports

Data Loading

| Function | Signature | Description | |--------- | M.saveWaypoint | (waypoint, filePath) | boolean | saveWaypoint | | M.saveLane | (lane, filePath) | boolean | saveLane | | M.saveStrip | (strip, filePath) | boolean | saveStrip |-| | M.onCareerActive | onCareerActive handler |-----------|-------------| | loadCompleteDragRaceData | (stripId) → table\|nil | Load and construct complete race data from strip JSON | | loadDragStripData | (filepath) → table\|nil | Load strip (new modular or legacy with auto-conversion) | | convertLegacyData | (legacyData) → table\|nil | Convert old-format data to current structure | | getCurrentLevelDragPath | () → string\|nil | /levels/<level>/dragstrips/ | | loadDriftData | - | Not present; drift uses separate saveLoad |

Mission Data

Function	Signature	Description
`createMissionData`	`(stripId, dragType, context, phases, prefabs, canBeReseted, canBeTeleported) → table`	Build mission reference structure

Dial Times & History

Function	Signature	Description
`saveDialTimes`	`(dragData, timeslip?)`	Save best times + append history per config hash
`getDialTimes`	`() → table`	`{configHash = {time_1_4 = number}}`
`generateHashFromFile`	`(vehicleId?) → string`	Hash vehicle's `.pc` config file via `FS:hashFile`
`getHistory`	`(id?) → {history = table}`	Get race history, optionally filtered by facility/strip ID
`saveDialFile`	`(dir) → bool`	Copy dial times to a specific directory
`getCurrentSavePath`	`() → string`	Career save path
`onSaveCurrentSaveSlot`	`(path)`	Hook to persist dial data on career save
`onCareerActive`	`()`	Career activation hook (empty)

Prefab Management

Function	Signature	Description
`loadPrefabs`	`(data)`	Spawn Christmas tree, display sign, decorations, paths
`unloadPrefabs`	`(data)`	Delete spawned prefab objects

Editor Functions

Function	Signature	Description
`getAllFacilities`	`() → table`	Scan for `*.facility.json` in drag path
`getAllStrips`	`() → table`	Scan for `*.strip.json`
`getAllLanes`	`() → table`	Extract lanes from all strips
`getAllWaypoints`	`() → table`	Extract waypoints from all lanes
`saveFacility/Strip/Lane/Waypoint`	`(data, path) → bool`	Write JSON
`saveFacilities`	`(facilities, path) → bool`	Batch save

Complete Data Structure

loadCompleteDragRaceData constructs:

{
  strip = {
    id = "...", name = "...", description = "...",
    lanes = {
      {
        id, shortName, longName, color, laneOrder,
        waypoints = {
          stage = {transform = {position, rotation, scale, pos, rot, scl, x, y, z}},
          endLine = {...}, spawn = {...}
        },
        boundary = {transform = {position, rotation, scale}},
        stageToEndNormalized = vec3  -- computed direction vector
      }
    }
  },
  phases = {
    {name="stage", dependency=true},
    {name="countdown", dependency=true},
    {name="race", dependency=false},
    {name="stop", dependency=false}
  },
  prefabs = {
    christmasTree = {isUsed=false, treeType=".400"},
    displaySign = {isUsed=false},
    paths = {isUsed=false},
    decorations = {isUsed=false}
  },
  dragType = "dragPracticeRace",
  context = "freeroam",
  racers = {}
}

How It Works

-- Load a strip and get complete data
local data = gameplay_drag_saveSystem.loadCompleteDragRaceData("/levels/west_coast_usa/dragstrips/main.strip.json")

-- Hash the player's current config for dial lookup
local hash = gameplay_drag_saveSystem.generateHashFromFile(be:getPlayerVehicleID(0))

-- Get their best time
local times = gameplay_drag_saveSystem.getDialTimes()
local best = times[hash] and times[hash].time_1_4 or 10

Key Behaviors

Dial times are saved to settings/dragDialTimes.json with structure {configHash: {time_1_4, history: [...]}}
generateHashFromFile uses FS:hashFile on the vehicle's .pc config file for unique identification
History entries contain full timeslip data plus config hashes per racer
Legacy format detection: if JSON contains stripId field, it's treated as modular; otherwise legacy conversion runs
Prefabs are spawned at origin ("0 0 0") - their internal transforms position them correctly
getHistory(id) supports facility IDs (resolves strip IDs via facility's stripIds array) and direct strip ID matching

Function	Signature	Returns	Description
`M.onCareerActive`	`()`	nil	onCareerActive
`M.saveStrip`	`(strip, filePath)`	nil	saveStrip
`M.saveLane`	`(lane, filePath)`	nil	saveLane
`M.saveWaypoint`	`(waypoint, filePath)`	nil	saveWaypoint
`M.convertLegacyData`	`(legacyData)`	-	convertLegacyData handler
`M.createMissionData`	`(stripId, dragType, context, phases, prefabs, canBeReseted, canBeTeleported)`	-	Mission data structure (minimal, references facility data)
`M.generateHashFromFile`	`(vehicleId)`	-	generateHashFromFile handler
`M.getAllFacilities`	`()`	-	Editor compatibility functions (for drag race editor)
`M.getAllLanes`	`()`	-	Returns AllLanes
`M.getAllStrips`	`()`	-	Returns AllStrips
`M.getAllWaypoints`	`()`	-	Returns AllWaypoints
`M.getCurrentLevelDragPath`	`()`	-	Returns CurrentLevelDragPath
`M.getCurrentSavePath`	`()`	-	Additional functions expected by general.lua
`M.getDialTimes`	`()`	-	Returns DialTimes
`M.getHistory`	`(id)`	-	Returns History
`M.loadCompleteDragRaceData`	`(stripId)`	-	loadCompleteDragRaceData handler
`M.loadDragStripData`	`(filepath)`	-	Compatibility functions for old format
`M.loadPrefabs`	`(data)`	-	Prefab management functions
`M.onSaveCurrentSaveSlot`	`(currentSavePath)`	-	Callback for SaveCurrentSaveSlot event
`M.saveDialFile`	`(dir)`	-	saveDialFile handler
`M.saveDialTimes`	`(dragData, timeslip)`	-	saveDialTimes handler
`M.saveFacilities`	`(facilities, filePath)`	-	saveFacilities handler
`M.saveFacility`	`(facility, filePath)`	-	saveFacility handler
`M.unloadPrefabs`	`(data)`	-	unloadPrefabs handler

Function	Signature	Description
`createMissionData`	`(stripId, dragType, context, phases, prefabs, canBeReseted, canBeTeleported) → table`	Build mission reference structure

Dial Times & History

Function	Signature	Description
`saveDialTimes`	`(dragData, timeslip?)`	Save best times + append history per config hash
`getDialTimes`	`() → table`	`{configHash = {time_1_4 = number}}`
`generateHashFromFile`	`(vehicleId?) → string`	Hash vehicle's `.pc` config file via `FS:hashFile`
`getHistory`	`(id?) → {history = table}`	Get race history, optionally filtered by facility/strip ID
`saveDialFile`	`(dir) → bool`	Copy dial times to a specific directory
`getCurrentSavePath`	`() → string`	Career save path
`onSaveCurrentSaveSlot`	`(path)`	Hook to persist dial data on career save
`onCareerActive`	`()`	Career activation hook (empty)

Prefab Management

Function	Signature	Description
`loadPrefabs`	`(data)`	Spawn Christmas tree, display sign, decorations, paths
`unloadPrefabs`	`(data)`	Delete spawned prefab objects

Editor Functions

Function	Signature	Description
`getAllFacilities`	`() → table`	Scan for `*.facility.json` in drag path
`getAllStrips`	`() → table`	Scan for `*.strip.json`
`getAllLanes`	`() → table`	Extract lanes from all strips
`getAllWaypoints`	`() → table`	Extract waypoints from all lanes
`saveFacility/Strip/Lane/Waypoint`	`(data, path) → bool`	Write JSON
`saveFacilities`	`(facilities, path) → bool`	Batch save

Complete Data Structure

loadCompleteDragRaceData constructs:

{
  strip = {
    id = "...", name = "...", description = "...",
    lanes = {
      {
        id, shortName, longName, color, laneOrder,
        waypoints = {
          stage = {transform = {position, rotation, scale, pos, rot, scl, x, y, z}},
          endLine = {...}, spawn = {...}
        },
        boundary = {transform = {position, rotation, scale}},
        stageToEndNormalized = vec3  -- computed direction vector
      }
    }
  },
  phases = {
    {name="stage", dependency=true},
    {name="countdown", dependency=true},
    {name="race", dependency=false},
    {name="stop", dependency=false}
  },
  prefabs = {
    christmasTree = {isUsed=false, treeType=".400"},
    displaySign = {isUsed=false},
    paths = {isUsed=false},
    decorations = {isUsed=false}
  },
  dragType = "dragPracticeRace",
  context = "freeroam",
  racers = {}
}

How It Works

-- Load a strip and get complete data
local data = gameplay_drag_saveSystem.loadCompleteDragRaceData("/levels/west_coast_usa/dragstrips/main.strip.json")

-- Hash the player's current config for dial lookup
local hash = gameplay_drag_saveSystem.generateHashFromFile(be:getPlayerVehicleID(0))

-- Get their best time
local times = gameplay_drag_saveSystem.getDialTimes()
local best = times[hash] and times[hash].time_1_4 or 10

Key Behaviors

Dial times are saved to settings/dragDialTimes.json with structure {configHash: {time_1_4, history: [...]}}
generateHashFromFile uses FS:hashFile on the vehicle's .pc config file for unique identification
History entries contain full timeslip data plus config hashes per racer
Legacy format detection: if JSON contains stripId field, it's treated as modular; otherwise legacy conversion runs
Prefabs are spawned at origin ("0 0 0") - their internal transforms position them correctly
getHistory(id) supports facility IDs (resolves strip IDs via facility's stripIds array) and direct strip ID matching

Function	Signature	Returns	Description
`M.onCareerActive`	`()`	nil	onCareerActive
`M.saveStrip`	`(strip, filePath)`	nil	saveStrip
`M.saveLane`	`(lane, filePath)`	nil	saveLane
`M.saveWaypoint`	`(waypoint, filePath)`	nil	saveWaypoint
`M.convertLegacyData`	`(legacyData)`	-	convertLegacyData handler
`M.createMissionData`	`(stripId, dragType, context, phases, prefabs, canBeReseted, canBeTeleported)`	-	Mission data structure (minimal, references facility data)
`M.generateHashFromFile`	`(vehicleId)`	-	generateHashFromFile handler
`M.getAllFacilities`	`()`	-	Editor compatibility functions (for drag race editor)
`M.getAllLanes`	`()`	-	Returns AllLanes
`M.getAllStrips`	`()`	-	Returns AllStrips
`M.getAllWaypoints`	`()`	-	Returns AllWaypoints
`M.getCurrentLevelDragPath`	`()`	-	Returns CurrentLevelDragPath
`M.getCurrentSavePath`	`()`	-	Additional functions expected by general.lua
`M.getDialTimes`	`()`	-	Returns DialTimes
`M.getHistory`	`(id)`	-	Returns History
`M.loadCompleteDragRaceData`	`(stripId)`	-	loadCompleteDragRaceData handler
`M.loadDragStripData`	`(filepath)`	-	Compatibility functions for old format
`M.loadPrefabs`	`(data)`	-	Prefab management functions
`M.onSaveCurrentSaveSlot`	`(currentSavePath)`	-	Callback for SaveCurrentSaveSlot event
`M.saveDialFile`	`(dir)`	-	saveDialFile handler
`M.saveDialTimes`	`(dragData, timeslip)`	-	saveDialTimes handler
`M.saveFacilities`	`(facilities, filePath)`	-	saveFacilities handler
`M.saveFacility`	`(facility, filePath)`	-	saveFacility handler
`M.unloadPrefabs`	`(data)`	-	unloadPrefabs handler

Drag Strip Save System

Overview

Exports

Data Loading

Mission Data

Dial Times & History

Prefab Management

Editor Functions

Complete Data Structure

How It Works

Key Behaviors

See Also

On this page

Drag Strip Save System

Overview

Exports

Data Loading

Mission Data

Dial Times & History

Prefab Management

Editor Functions

Complete Data Structure

How It Works

Key Behaviors

See Also

On this page