Drift System

Reference for `gameplay_drift_general`, which is the central manager for the drift subsystem. Controls extension loading/unloading, context switching, debug state, freeze/pause logic, and coordinates

Reference for gameplay_drift_general, which is the central manager for the drift subsystem. Controls extension loading/unloading, context switching, debug state, freeze/pause logic, and coordinates all drift sub-extensions.

Dependencies

gameplay_drift_drift, gameplay_drift_scoring, gameplay_drift_statistics, gameplay_drift_saveLoad, gameplay_util_groundContact

Exports

State Management

Function	Signature	Description
`setContext`	`(newContext)`	Switch context, triggers extension updates
`getContext`	`() → string`	Current context
`setChallengeMode`	`(mode)`	Set challenge mode, update extensions
`getChallengeMode`	`() → string`	Current challenge mode
`setPaused`	`(bool)`	Pause scoring/detection
`getPaused`	`() → bool`	Paused state
`getFrozen`	`() → bool`	Frozen state (out of bounds / wrong way)
`setDebug`	`(bool)`	Enable/disable ImGui debug windows
`getGeneralDebug`	`() → bool`	Debug enabled
`getExtensionDebug`	`(extName) → bool`	Debug enabled for specific extension
`getIsThereAnyDriftUIAppDisplayed`	`() → bool`	Any drift app visible

Lifecycle

Function	Signature	Description
`onUpdate`	`()`	Check frozen state, manage sound extension
`onExtensionLoaded`	`()`	Scan for drift extension files
`onVehicleResetted`	`(vid)`	Hook `onDriftPlVehReset` for player vehicle
`onAnyMissionChanged`	`(status, mission)`	Context switching on mission start/stop
`reset`	`()`	Reset all loaded extensions
`clear`	`()`	Reset + clear stunt zones
`onSerialize` / `onDeserialized`	`(data)`	Persist debug state
`onDriftAppMounted` / `onDriftAppUnmounted`	`()`	Track UI app mount state

Context System

Context	Description
`inFreeroam`	Default; drift spots enabled, cruising enabled
`inChallenge`	Formal drift mission; scoreboard, stunt zones
`inFreeroamChallenge`	Freeroam drift spot challenge; bounds, destination
`inAnotherMissionType`	Non-drift mission active; drift detection disabled

Variable Extension Loading

Extensions are loaded/unloaded based on context and challenge mode:

variableExtensions = {
  gameplay_drift_display     = {contexts = {"inChallenge", "inFreeroamChallenge", "inFreeroam"}},
  gameplay_drift_bounds      = {contexts = {"inChallenge", "inFreeroamChallenge"}},
  gameplay_drift_destination = {challengeModes = {"A to B", ...}, contexts = {"inFreeroamChallenge"}},
  gameplay_drift_stuntZones  = {contexts = {"inChallenge"}},
  gameplay_drift_quickMessages = {contexts = {"inFreeroam", "inChallenge", "inFreeroamChallenge"}},
  gameplay_drift_scoreboard  = {contexts = {"inChallenge"}},
  gameplay_drift_freeroam_driftSpots = {contexts = {"inFreeroam", "inFreeroamChallenge"}},
  gameplay_drift_freeroam_cruising   = {contexts = {"inFreeroam"}},
  gameplay_drift_stallingSystem      = {challengeModes = {"Gymkhana"}},
  gameplay_drift_sounds      = {manualLoad = true},  -- loaded by sound check
}

Freeze Logic

-- Checked every frame via checkFrozen():
frozen = outOfBounds or goingWrongWay or isInConcludingPhase
-- When frozen: scoring stops, drift detection data not cleared
-- Frozen state is consumed by scoring and display systems

Sound Extension Management

-- Sound loads when drift UI app is displayed
-- Sound unloads when drift UI app is hidden
-- Prevents audio resources being held when not drifting

Challenge Modes

Mode	Description
`None`	Default (freeroam)
`A to B`	Start-to-finish with destination tracking
`A to B with stunt zones`	A-to-B plus stunt zone bonuses
`Gymkhana`	Enclosed area with stalling system
`Competition`	(Reserved)

Key Behaviors

First onUpdate call runs init() which sets context to "inFreeroam" and resets
When a non-drift mission starts, context switches to "inAnotherMissionType" and crash detection is removed
Context changes fire extensions.hook("onDriftContextChanged", context, oldContext)
All loaded drift extensions are tracked in loadedExtensions table with debug info
checkLoadedExtensions() scans all .lua files under gameplay/drift/ to build the extension registry

Public API

Function	Signature	Returns	Description
`M.getDriftDebugInfo`	`()`	nil	getDriftDebugInfo

Module Variables

Variable	Type	Description
`M.dependencies`	`table`	{"gameplay_drift_drift", "gameplay_drift_scoring", "gameplay_drift_statistics",
`M.clear`	`()`	-
`M.getChallengeMode`	`()`	-
`M.getContext`	`()`	-
`M.getExtensionDebug`	`(extName)`	-
`M.getFrozen`	`()`	-
`M.getGeneralDebug`	`()`	-
`M.getIsThereAnyDriftUIAppDisplayed`	`()`	-
`M.getPaused`	`()`	-
`M.onAnyMissionChanged`	`(status, mission)`	-
`M.onDeserialized`	`(data)`	-
`M.onDriftAppMounted`	`()`	-
`M.onDriftAppUnmounted`	`()`	-
`M.onExtensionLoaded`	`()`	-
`M.onSerialize`	`()`	-
`M.onUpdate`	`()`	-
`M.onVehicleResetted`	`(vid)`	-
`M.reset`	`()`	-
`M.setChallengeMode`	`(newChallengeMode)`	-
`M.setContext`	`(newContext)`	-
`M.setDebug`	`(value)`	-
`M.setPaused`	`(newPaused)`	-

Function	Signature	Description
`setContext`	`(newContext)`	Switch context, triggers extension updates
`getContext`	`() → string`	Current context
`setChallengeMode`	`(mode)`	Set challenge mode, update extensions
`getChallengeMode`	`() → string`	Current challenge mode
`setPaused`	`(bool)`	Pause scoring/detection
`getPaused`	`() → bool`	Paused state
`getFrozen`	`() → bool`	Frozen state (out of bounds / wrong way)
`setDebug`	`(bool)`	Enable/disable ImGui debug windows
`getGeneralDebug`	`() → bool`	Debug enabled
`getExtensionDebug`	`(extName) → bool`	Debug enabled for specific extension
`getIsThereAnyDriftUIAppDisplayed`	`() → bool`	Any drift app visible

Lifecycle

Function	Signature	Description
`onUpdate`	`()`	Check frozen state, manage sound extension
`onExtensionLoaded`	`()`	Scan for drift extension files
`onVehicleResetted`	`(vid)`	Hook `onDriftPlVehReset` for player vehicle
`onAnyMissionChanged`	`(status, mission)`	Context switching on mission start/stop
`reset`	`()`	Reset all loaded extensions
`clear`	`()`	Reset + clear stunt zones
`onSerialize` / `onDeserialized`	`(data)`	Persist debug state
`onDriftAppMounted` / `onDriftAppUnmounted`	`()`	Track UI app mount state

Context System

Context	Description
`inFreeroam`	Default; drift spots enabled, cruising enabled
`inChallenge`	Formal drift mission; scoreboard, stunt zones
`inFreeroamChallenge`	Freeroam drift spot challenge; bounds, destination
`inAnotherMissionType`	Non-drift mission active; drift detection disabled

Variable Extension Loading

Extensions are loaded/unloaded based on context and challenge mode:

variableExtensions = {
  gameplay_drift_display     = {contexts = {"inChallenge", "inFreeroamChallenge", "inFreeroam"}},
  gameplay_drift_bounds      = {contexts = {"inChallenge", "inFreeroamChallenge"}},
  gameplay_drift_destination = {challengeModes = {"A to B", ...}, contexts = {"inFreeroamChallenge"}},
  gameplay_drift_stuntZones  = {contexts = {"inChallenge"}},
  gameplay_drift_quickMessages = {contexts = {"inFreeroam", "inChallenge", "inFreeroamChallenge"}},
  gameplay_drift_scoreboard  = {contexts = {"inChallenge"}},
  gameplay_drift_freeroam_driftSpots = {contexts = {"inFreeroam", "inFreeroamChallenge"}},
  gameplay_drift_freeroam_cruising   = {contexts = {"inFreeroam"}},
  gameplay_drift_stallingSystem      = {challengeModes = {"Gymkhana"}},
  gameplay_drift_sounds      = {manualLoad = true},  -- loaded by sound check
}

Freeze Logic

-- Checked every frame via checkFrozen():
frozen = outOfBounds or goingWrongWay or isInConcludingPhase
-- When frozen: scoring stops, drift detection data not cleared
-- Frozen state is consumed by scoring and display systems

Sound Extension Management

-- Sound loads when drift UI app is displayed
-- Sound unloads when drift UI app is hidden
-- Prevents audio resources being held when not drifting

Challenge Modes

Mode	Description
`None`	Default (freeroam)
`A to B`	Start-to-finish with destination tracking
`A to B with stunt zones`	A-to-B plus stunt zone bonuses
`Gymkhana`	Enclosed area with stalling system
`Competition`	(Reserved)

Key Behaviors

First onUpdate call runs init() which sets context to "inFreeroam" and resets
When a non-drift mission starts, context switches to "inAnotherMissionType" and crash detection is removed
Context changes fire extensions.hook("onDriftContextChanged", context, oldContext)
All loaded drift extensions are tracked in loadedExtensions table with debug info
checkLoadedExtensions() scans all .lua files under gameplay/drift/ to build the extension registry

Public API

Function	Signature	Returns	Description
`M.getDriftDebugInfo`	`()`	nil	getDriftDebugInfo

Module Variables

Variable	Type	Description
`M.dependencies`	`table`	{"gameplay_drift_drift", "gameplay_drift_scoring", "gameplay_drift_statistics",
`M.clear`	`()`	-
`M.getChallengeMode`	`()`	-
`M.getContext`	`()`	-
`M.getExtensionDebug`	`(extName)`	-
`M.getFrozen`	`()`	-
`M.getGeneralDebug`	`()`	-
`M.getIsThereAnyDriftUIAppDisplayed`	`()`	-
`M.getPaused`	`()`	-
`M.onAnyMissionChanged`	`(status, mission)`	-
`M.onDeserialized`	`(data)`	-
`M.onDriftAppMounted`	`()`	-
`M.onDriftAppUnmounted`	`()`	-
`M.onExtensionLoaded`	`()`	-
`M.onSerialize`	`()`	-
`M.onUpdate`	`()`	-
`M.onVehicleResetted`	`(vid)`	-
`M.reset`	`()`	-
`M.setChallengeMode`	`(newChallengeMode)`	-
`M.setContext`	`(newContext)`	-
`M.setDebug`	`(value)`	-
`M.setPaused`	`(newPaused)`	-

Drift System

Dependencies

Exports

State Management

Lifecycle

Context System

Variable Extension Loading

Freeze Logic

Sound Extension Management

Challenge Modes

Key Behaviors

Public API

Module Variables

See Also

On this page

Drift System

Dependencies

Exports

State Management

Lifecycle

Context System

Variable Extension Loading

Freeze Logic

Sound Extension Management

Challenge Modes

Key Behaviors

Public API

Module Variables

See Also

On this page