Drag Tree Display

Reference for `gameplay_drag_display`, which controls the visual Christmas tree lights and digital display signs on the drag strip, plus corresponding UI updates.

Reference for gameplay_drag_display, which controls the visual Christmas tree lights and digital display signs on the drag strip, plus corresponding UI updates.

Overview

Manages the physical scene objects (pre-stage, stage, countdown, winner lights) and numeric display digits on the drag strip. Also pushes light-state changes to the UI via guihooks so on-screen apps mirror the 3D tree. Supports both .400 (Pro) and .500 (Sportsman) tree countdown sequences.

Exports

| Function | Signature | Description | |--------- | M.stageLightOff | (vehId) | nil | stageLightOff | | M.preStageLightOff | (vehId) | nil | preStageLightOff |-|-----------|-------------| | onExtensionLoaded | () | Fetches dragData, initialises tree + display | | onUpdate | (dtReal, dtSim, dtRaw) | Drives countdown timers, blinks winner light | | clearAll | () | Hides all lights and display digits | | onBeforeDragUnloadAllExtensions | () | Alias for clearLights | | startDragCountdown | (vehId, dial) | Begin countdown for a racer with a dial offset | | setDisqualifiedLights | (vehId) | Turn red, hide green/amber, flash "False start" | | preStageLightOn / Off | (vehId) | Toggle pre-stage indicator | | stageLightOn / Off | (vehId) | Toggle stage indicator; blue light when all staged | | dragRaceStarted | (vehId) | (empty hook placeholder) | | dragRaceEndLineReached | (vehId) | Updates physical display with time/speed | | dragRaceVehicleStopped | () | Clears tree + display after vehicle stops | | resetDragRaceValues | () | Flash-all animation then clear | | onWinnerLightOn | (lane) | Illuminate winner + blinking driver light | | stoppingVehicleDrag | (vehId) | Flashes "Stop the vehicle!" for playable racer |

Internals

Symbol	Purpose
`createTreeLights(lane, prefabId)`	Builds per-lane table of scene-tree light refs
`initTree()`	Creates `treeLights` for every lane in `dragData.strip.lanes`
`initDisplay()`	Finds `display_time_N_r/l` and `display_speed_N_r/l` TSStatic objects
`handle400TreeLogic(…)`	Pro tree - all ambers flash at once, green after 0.4 s
`handle500TreeLogic(…)`	Sportsman tree - ambers cascade at 0.5 s intervals
`flashAllLightsAndDisplay()`	Double-flash ON/OFF/ON/OFF reset animation
`hasDisplayDigits()` / `hasTreeLights()`	Feature-detect scene objects
`sendTimesToUI(vehId)`	Pushes times to UI app when no physical sign exists
`updateTreeLightsUI(vehId, changes)`	Sends light state diff to `updateTreeLightApp`
`checkDisableTreeLightsUI()`	Hides UI tree if player is >10 m from stage in freeroam

How It Works

-- Countdown begins when both racers are staged
gameplay_drag_display.startDragCountdown(vehId, dialOffset)

-- Tree type determines countdown logic:
-- ".400" → all 3 ambers flash simultaneously, green after 0.4s
-- ".500" → ambers cascade every 0.5s, then green

-- Physical display updates after crossing the finish:
gameplay_drag_display.dragRaceEndLineReached(vehId)
-- Swaps TSStatic shapes to digit DAE files:
-- "art/shapes/quarter_mile_display/display_0.dae" .. "display_9.dae"

Key Behaviors

All light and digit objects are found via scenetree.findObject or prefab-scoped lookup
If no physical display digits exist in the scene, times are sent to UI via guihooks.trigger("updateDragRaceTimes", …)
Winner driver light blinks at 6 Hz until race ends
The blue "both staged" light activates when stagedAmount >= #treeLights
Flash messages use both direct guihooks.trigger('DragRaceTreeFlashMessage') and extensions.hook('onGameplayFlashMessage') for container routing

Function	Signature	Returns	Description
`M.preStageLightOff`	`(vehId)`	nil	preStageLightOff
`M.stageLightOff`	`(vehId)`	nil	stageLightOff
`M.clearAll`	`()`	-	clearAll handler
`M.dragRaceEndLineReached`	`(vehId)`	-	dragRaceEndLineReached handler
`M.dragRaceStarted`	`(vehId)`	-	dragRaceStarted handler
`M.dragRaceVehicleStopped`	`()`	-	dragRaceVehicleStopped handler
`M.onBeforeDragUnloadAllExtensions`	`()`	-	Callback for BeforeDragUnloadAllExtensions event
`M.onExtensionLoaded`	`()`	-	Callback for ExtensionLoaded event
`M.onUpdate`	`(dtReal, dtSim, dtRaw)`	-	Callback for Update event
`M.onWinnerLightOn`	`(lane)`	-	Callback for WinnerLightOn event
`M.preStageLightOn`	`(vehId)`	-	preStageLightOn handler
`M.resetDragRaceValues`	`()`	-	resetDragRaceValues handler
`M.setDisqualifiedLights`	`(vehId)`	-	Sets DisqualifiedLights
`M.stageLightOn`	`(vehId)`	-	stageLightOn handler
`M.startDragCountdown`	`(vehId, dial)`	-	HOOKS
`M.stoppingVehicleDrag`	`(vehId)`	-	stoppingVehicleDrag handler

Symbol	Purpose
`createTreeLights(lane, prefabId)`	Builds per-lane table of scene-tree light refs
`initTree()`	Creates `treeLights` for every lane in `dragData.strip.lanes`
`initDisplay()`	Finds `display_time_N_r/l` and `display_speed_N_r/l` TSStatic objects
`handle400TreeLogic(…)`	Pro tree - all ambers flash at once, green after 0.4 s
`handle500TreeLogic(…)`	Sportsman tree - ambers cascade at 0.5 s intervals
`flashAllLightsAndDisplay()`	Double-flash ON/OFF/ON/OFF reset animation
`hasDisplayDigits()` / `hasTreeLights()`	Feature-detect scene objects
`sendTimesToUI(vehId)`	Pushes times to UI app when no physical sign exists
`updateTreeLightsUI(vehId, changes)`	Sends light state diff to `updateTreeLightApp`
`checkDisableTreeLightsUI()`	Hides UI tree if player is >10 m from stage in freeroam

How It Works

-- Countdown begins when both racers are staged
gameplay_drag_display.startDragCountdown(vehId, dialOffset)

-- Tree type determines countdown logic:
-- ".400" → all 3 ambers flash simultaneously, green after 0.4s
-- ".500" → ambers cascade every 0.5s, then green

-- Physical display updates after crossing the finish:
gameplay_drag_display.dragRaceEndLineReached(vehId)
-- Swaps TSStatic shapes to digit DAE files:
-- "art/shapes/quarter_mile_display/display_0.dae" .. "display_9.dae"

Key Behaviors

All light and digit objects are found via scenetree.findObject or prefab-scoped lookup
If no physical display digits exist in the scene, times are sent to UI via guihooks.trigger("updateDragRaceTimes", …)
Winner driver light blinks at 6 Hz until race ends
The blue "both staged" light activates when stagedAmount >= #treeLights
Flash messages use both direct guihooks.trigger('DragRaceTreeFlashMessage') and extensions.hook('onGameplayFlashMessage') for container routing

Function	Signature	Returns	Description
`M.preStageLightOff`	`(vehId)`	nil	preStageLightOff
`M.stageLightOff`	`(vehId)`	nil	stageLightOff
`M.clearAll`	`()`	-	clearAll handler
`M.dragRaceEndLineReached`	`(vehId)`	-	dragRaceEndLineReached handler
`M.dragRaceStarted`	`(vehId)`	-	dragRaceStarted handler
`M.dragRaceVehicleStopped`	`()`	-	dragRaceVehicleStopped handler
`M.onBeforeDragUnloadAllExtensions`	`()`	-	Callback for BeforeDragUnloadAllExtensions event
`M.onExtensionLoaded`	`()`	-	Callback for ExtensionLoaded event
`M.onUpdate`	`(dtReal, dtSim, dtRaw)`	-	Callback for Update event
`M.onWinnerLightOn`	`(lane)`	-	Callback for WinnerLightOn event
`M.preStageLightOn`	`(vehId)`	-	preStageLightOn handler
`M.resetDragRaceValues`	`()`	-	resetDragRaceValues handler
`M.setDisqualifiedLights`	`(vehId)`	-	Sets DisqualifiedLights
`M.stageLightOn`	`(vehId)`	-	stageLightOn handler
`M.startDragCountdown`	`(vehId, dial)`	-	HOOKS
`M.stoppingVehicleDrag`	`(vehId)`	-	stoppingVehicleDrag handler

Drag Tree Display

Overview

Exports

Internals

How It Works

Key Behaviors

See Also

On this page

Drag Tree Display

Overview

Exports

Internals

How It Works

Key Behaviors

See Also

On this page