Drag Race Timing

Reference for `gameplay_drag_times`, which tracks all distance-based, velocity-based, and time-based measurements during a drag race.

Reference for gameplay_drag_times, which tracks all distance-based, velocity-based, and time-based measurements during a drag race.

Overview

Runs every frame to accumulate timer values for each racer. Uses distance interpolation between frames for sub-frame accuracy on distance triggers (reaction time, 60ft, 330ft, 1/8 mile, 1000ft, 1/4 mile). Also tracks trap speeds at 1/8 and 1/4 mile, 0-60 mph time, and braking G-force during emergency stop.

Exports

Function	Signature	Description
`onExtensionLoaded`	`()`	Fetches `dragData`, calls `reset()`
`onUpdate`	`(dtReal, dtSim, dtRaw)`	Main timer update loop
`reset`	`()`	Reset all timer values and frame histories
`preStageStarted`	`()`	Empty hook placeholder
`dragRaceStarted`	`(vehId)`	Enables timer tracking for a racer
`resetDragRaceValues`	`()`	Alias for `reset()`

Timer Types

Type	Trigger	Example Timers
`distanceTimer`	`distanceFromOrigin >= timer.distance`	`reactionTime`, `time_60`, `time_330`, `time_1_8`, `time_1000`, `time_1_4`
`velocity`	`distanceFromOrigin >= timer.distance`	`velAt_1_8`, `velAt_1_4`
`timeToVelocity`	`vehSpeed > timer.velocity`	`time_0_60` (0-60 mph)
`brakingG`	During `emergencyStop` phase after 0.4s	`brakingG`
`M.dragRaceStarted`	`(vehId)`	-
`M.onExtensionLoaded`	`()`	-
`M.onUpdate`	`(dtReal, dtSim, dtRaw)`	-
`M.preStageStarted`	`()`	-
`M.reset`	`()`	-
`M.resetDragRaceValues`	`()`	-

How It Works

-- Timer activation flow:
-- 1. dragRaceStarted(vehId) sets racer.timersStarted = true
-- 2. Each frame, onUpdate increments timer.value by dtSim
-- 3. For each distance-based timer:
--    a. When distance crosses threshold, interpolate exact crossing time:
--       t = inverseLerp(prevDistance, currentDistance, threshold)
--       timer.value = timerValue - (1-t) * dtSim
--    b. For velocity timers, interpolate speed at crossing:
--       timer.value = lerp(prevSpeed, currentSpeed, t)
-- 4. When reactionTime is set, subtract it from the running timer
--    (so all subsequent times are relative to car movement, not tree)

Sub-Frame Accuracy

The system uses inverseLerp between previous and current distances to find the exact fraction of the frame where the distance threshold was crossed:

local t = inverseLerp(prevDistance, distanceFromOrigin, timer.distance)
timer.value = timerValue - (1 - t) * dtSim
-- t=0 means crossed at start of frame, t=1 at end

Braking G Measurement

During the emergencyStop phase:

Wait 0.4 seconds for braking to stabilise
Record start time, distance, and speed
After deltaTime (1s) or vehicle stops, calculate deceleration

Frame History Debug

Timers listed in addFrameHistoryDebug (currently only reactionTime) store per-frame debug strings:

timer.frameHistory[n] = "Racer: 42 Frame 15: 0.15000s after start. Distance: 0.1234m ..."

Key Behaviors

All timers start at 0 and only accumulate when racer.timersStarted is true
Reaction time is subtracted from the running clock so subsequent times measure from car movement
Timer updates skip completed races (dragData.isCompleted)
The onExtensionLoaded hook initialises frameHistory for debug-tracked timers

Overview

Exports

Function	Signature	Description
`onExtensionLoaded`	`()`	Fetches `dragData`, calls `reset()`
`onUpdate`	`(dtReal, dtSim, dtRaw)`	Main timer update loop
`reset`	`()`	Reset all timer values and frame histories
`preStageStarted`	`()`	Empty hook placeholder
`dragRaceStarted`	`(vehId)`	Enables timer tracking for a racer
`resetDragRaceValues`	`()`	Alias for `reset()`

Timer Types

Type	Trigger	Example Timers
`distanceTimer`	`distanceFromOrigin >= timer.distance`	`reactionTime`, `time_60`, `time_330`, `time_1_8`, `time_1000`, `time_1_4`
`velocity`	`distanceFromOrigin >= timer.distance`	`velAt_1_8`, `velAt_1_4`
`timeToVelocity`	`vehSpeed > timer.velocity`	`time_0_60` (0-60 mph)
`brakingG`	During `emergencyStop` phase after 0.4s	`brakingG`
`M.dragRaceStarted`	`(vehId)`	-
`M.onExtensionLoaded`	`()`	-
`M.onUpdate`	`(dtReal, dtSim, dtRaw)`	-
`M.preStageStarted`	`()`	-
`M.reset`	`()`	-
`M.resetDragRaceValues`	`()`	-

How It Works

-- Timer activation flow:
-- 1. dragRaceStarted(vehId) sets racer.timersStarted = true
-- 2. Each frame, onUpdate increments timer.value by dtSim
-- 3. For each distance-based timer:
--    a. When distance crosses threshold, interpolate exact crossing time:
--       t = inverseLerp(prevDistance, currentDistance, threshold)
--       timer.value = timerValue - (1-t) * dtSim
--    b. For velocity timers, interpolate speed at crossing:
--       timer.value = lerp(prevSpeed, currentSpeed, t)
-- 4. When reactionTime is set, subtract it from the running timer
--    (so all subsequent times are relative to car movement, not tree)

Sub-Frame Accuracy

The system uses inverseLerp between previous and current distances to find the exact fraction of the frame where the distance threshold was crossed:

local t = inverseLerp(prevDistance, distanceFromOrigin, timer.distance)
timer.value = timerValue - (1 - t) * dtSim
-- t=0 means crossed at start of frame, t=1 at end

Braking G Measurement

During the emergencyStop phase:

Wait 0.4 seconds for braking to stabilise
Record start time, distance, and speed
After deltaTime (1s) or vehicle stops, calculate deceleration

Frame History Debug

Timers listed in addFrameHistoryDebug (currently only reactionTime) store per-frame debug strings:

timer.frameHistory[n] = "Racer: 42 Frame 15: 0.15000s after start. Distance: 0.1234m ..."

Key Behaviors

All timers start at 0 and only accumulate when racer.timersStarted is true
Reaction time is subtracted from the running clock so subsequent times measure from car movement
Timer updates skip completed races (dragData.isCompleted)
The onExtensionLoaded hook initialises frameHistory for debug-tracked timers

Drag Race Timing

Overview

Exports

Timer Types

How It Works

Sub-Frame Accuracy

Braking G Measurement

Frame History Debug

Key Behaviors

See Also

On this page

Drag Race Timing

Overview

Exports

Timer Types

How It Works

Sub-Frame Accuracy

Braking G Measurement

Frame History Debug

Key Behaviors

See Also

On this page