Drag Race Phases
Reference for `gameplay_drag_utils`, which provides all phase functions (`stage`, `countdown`, `race`, `stop`, `emergencyStop`), racer position tracking, tree light processing, win conditions, and bou
Reference for gameplay_drag_utils, which provides all phase functions (stage, countdown, race, stop, emergencyStop), racer position tracking, tree light processing, win conditions, and boundary checking.
Dependencies
gameplay_drag_general
Exports
Core Utilities
| Function | Signature | Description |
|------
| M.dependencies | table | {'gameplay_drag_general'} |----|-----------|-------------|
| onExtensionLoaded | () | Fetch drag data reference |
| updateRacer | (racer) | Refresh position, speed, wheel positions, tree lights |
| getFrontWheelDistanceFromStagePos | (racer) → number | Signed distance from stage line |
| calculateDistanceOfAllWheelsFromStagePos | (racer) | Compute per-axle distances |
| isRacerInsideBoundary | (racer) → bool | OBB containment check |
Race Management
| Function | Signature | Description |
|---|---|---|
generateWinData | () → table | Determine winner, trigger winner light |
changeRacerPhase | (racer) | Advance racer to next phase |
changeAllPhases | () | Advance all racers (dependency phases) |
startRaceFromTree | (vehId) | Mark countdown complete, add AI delay |
setDialsData | (data) | Calculate dial offsets for staggered starts |
Phase Functions
| Function | Signature | Description |
|---|---|---|
stage | (phase, racer, dtSim) | Drive AI to stage line; check player staging |
countdown | (phase, racer, dtSim) | Activate tree, arm AI (transbrake/two-step/NOS) |
race | (phase, racer, dtSim) | Launch AI, track times, check boundaries/DQ |
stop | (phase, racer, dtSim) | Decelerate to < 15 m/s |
emergencyStop | (phase, racer, dtSim) | Full stop to < 0.01 m/s |
Win Conditions
| Drag Type | Function | Logic |
|---|---|---|
headsUpDrag / headsUpRace / dragPracticeRace | headsUpWin() | Lowest time_1_4 wins; DQ'd racers last |
bracketRace | bracketWin() | Closest positive dialDiff wins; negative (breakout) penalised; DQ'd last |
-- Bracket win calculation per racer:
dialDiff = (time_1_4 + reactionTime) - dial
-- Positive dialDiff = slower than dial (valid)
-- Negative dialDiff = faster than dial (breakout, penalised)
-- Sorted: positive ascending, then negative by abs ascending, then DQ'dTree Light Processing
-- Pre-stage and stage lights are controlled by front wheel distance:
-- preStage zone: [-0.356m, 0m) (±0.178m around -0.178m)
-- stage zone: [-0.178m, +0.178m) (±0.178m around 0m)
-- exit zone: > 0.4m from 0processTreeLights compares distance against thresholds and fires preStageLightOn/Off and stageLightOn/Off hooks when state changes.
AI Vehicle Control
During stage phase, AI vehicles:
veh:queueLuaCommand('ai.setSpeedMode("limit")')
veh:queueLuaCommand('ai.setSpeed(5)')
veh:queueLuaCommand('ai.setTarget("endLine_1")')During countdown phase, AI arms launch systems:
-- Activate transbrake (or freeze if unavailable)
-- Activate two-step rev limiter
-- Arm nitrous oxide injection
-- Set throttle override to 0.8During race phase, AI launches:
-- Release transbrake/freeze
-- Clear throttle override
-- Activate JATO if available
-- Set AI to full speed toward end lineDisqualification Checks
| Check | Condition | Reason |
|---|---|---|
stageJump | Front wheels outside ±0.178m during countdown | "jumping" |
outOfBounds | Outside lane boundary OBB or distance < -0.33m | "outOfLane" |
stationaryTooLong | Speed < 1 m/s for > 5 seconds during race | "stationaryTooLong" |
Key Behaviors
updateRacertransforms wheel offsets from local to world space using vehicle rotation, then calculates per-axle distances from stagesetDialsDatawith 2 racers computes staggered offset: slower racer gets0, faster getsabs(dial1 - dial2)- AI vehicles get a random 0–0.5s reaction delay via
randomDelayTimeron green light - Player staging requires 1 second hold at the stage line with wheels parallel (dot product ≥ 0.70)
- Timeslip is auto-sent to UI when finish is reached outside of a formal mission
Module Variables
| Variable | Type | Description |
|---|---|---|
M.dependencies | table | {'gameplay_drag_general'} |
M.calculateDistanceOfAllWheelsFromStagePos | (racer) | - |
M.changeAllPhases | () | - |
M.changeRacerPhase | (racer) | - |
M.countdown | (phase, racer, dtSim) | - |
M.emergencyStop | (phase, racer, dtSim) | - |
M.generateWinData | () | - |
M.getFrontWheelDistanceFromStagePos | (racer) | - |
M.isRacerInsideBoundary | (racer) | - |
M.onExtensionLoaded | () | - |
M.race | (phase, racer, dtSim) | - |
M.setDialsData | (data) | - |
M.stage | (phase, racer, dtSim) | - |
M.startRaceFromTree | (vehId) | - |
M.stop | (phase, racer, dtSim) | - |
M.updateRacer | (racer) | - |
See Also
- drag/debug - Drag Race Debug Menu - Related reference
- drag/display - Christmas Tree & Display Signs - Related reference
- drag/dragBridge - Flowgraph / External API Bridge - Related reference
- Gameplay Systems Guide - Guide
Drag Race Timing
Reference for `gameplay_drag_times`, which tracks all distance-based, velocity-based, and time-based measurements during a drag race.
Bracket Drag Race
Reference for `gameplay_drag_dragTypes_bracketRace`, which implements the bracket-style drag race where racers have a dial-in time and staggered starts.