Controller Module Reference
Module defined in `lua/vehicle/controller.lua`. This module manages the vehicle's logical controllers, such as shift logic, electronic stability control (ESC), and specialized auxiliary systems. It ha
Module defined in lua/vehicle/controller.lua. This module manages the vehicle's logical controllers, such as shift logic, electronic stability control (ESC), and specialized auxiliary systems. It handles loading, ordering, and dispatching events to all active controllers.
See Also
- Electrics: For the shared data bus used by controllers.
- Controller Folder: List of all specific controllers.
- Main Controller: Deep dive into the primary vehicle control logic.
State Fields
| Variable | Description |
|---|---|
isFrozen | Indicates if the vehicle logic (and the main controller) is currently frozen. |
mainController | Reference to the vehicle's primary controller (e.g., vehicleController). |
nilController | A dummy table that safely handles any indexing or call attempts without erroring. Used as a safe fallback. |
Public API - Global
| Function | Signature | Description |
|---|---|---|
controller.getController | (name) | Returns the controller object with the specified name. |
controller.getControllerSafe | (name) | Returns the controller or nilController if not found. |
controller.getControllersByType | (typeName) | Returns an array of all loaded controllers of that type. |
controller.loadControllerExternal | (fileName, name, data) | Dynamically loads a controller at runtime. |
controller.unloadControllerExternal | (name) | Removes a dynamically loaded controller. |
controller.setFreeze | (mode) | Freezes or thaws all vehicle control logic. |
controller.publishStateEvent | (name, ...) | Directly triggers stateEvent on a specific controller. |
Public API - Lifecycle & Dispatch Hooks
These functions are typically called by the vehicle engine or internal events and dispatched to all active controllers.
| Function | Signature | Description |
|---|---|---|
controller.init | () / initSecondStage() / initLastStage() | Standard three-pass initialization sequence. |
controller.reset | () / resetSecondStage() / resetLastStage() | Standard three-pass reset sequence. |
controller.update | (dt) | Dispatches high-frequency physics update (2000Hz). |
controller.updateGFX | (dt) | Dispatches frame-rate graphics update. |
controller.updateWheelsIntermediate | (dt) | Specialized physics update for wheel-related logic. |
controller.beamBroke | (id, energy) / beamDeformed(id, ratio) | Dispatches structural damage events. |
controller.nodeCollision | (p) | Dispatches collision data packets. |
controller.onCouplerAttached | (...) / onCouplerDetached(...) / onCouplerFound(...) | Dispatches structural coupling events. |
The Main Controller (controller.mainController)
Typically vehicleController/vehicleController.lua. Manages throttle, braking, and gearbox logic.
Properties
throttle,brake,clutchRatio: Active control signals (0-1).drivingAggression: Current player aggression level (0-1).shiftingAggression: Gearbox aggressiveness.gearboxBehavior: Current mode ("arcade"or"realistic").isArcadeSwitched: Flag for arcade-style reverse switching.fireEngineTemperature: Simulated exhaust/engine heat for fire logic.
Public API - Methods
| Function | Signature | Description |
|---|---|---|
main:cycleGearboxModes | () | Cycles through available shifter behaviors. |
main:setGearboxMode | (mode) | Explicitly sets the shifting logic mode. |
main:setEngineIgnition | (enabled) | Toggles the primary engine ignition. |
main:setStarter | (enabled) | Engages or disengages the engine starter. |
main:shiftToGearIndex | (index) | Forces the gearbox to shift to a specific gear. |
main:shiftUpOnDown | () / shiftDownOnDown() | Handlers for shift input buttons (OnDown events). |
main:smartParkingBrake | (value) | Intelligent handbrake logic that toggles vs holds based on speed. |
main:setAggressionOverride | (val) | Manually overrides the driver aggression calculation. |
Public API - main.engineInfo Array
A packed array of performance data used by UI streams and internal logic.
idleRPMmaxRPMcurrentRPMgearName(string)maxGearIndexminGearIndexflywheelTorquegearboxTorqueairspeedfuelVolumefuelCapacitygearIndexengineRunning(0 or 1)engineLoad(0-1)wheelTorquewheelPowerflywheelPower
Hooks
| Function | Signature | Description |
|---|---|---|
module.initSounds | () | Initializes sound resources. |
module.resetSounds | () | Resets sound state. |
module.getAllControllers | (name) | Returns the all controllers. Returns loadedControllers. |
module.getControllersFromPath | (path) | Returns the controllers from path. Returns controllers. |
module.settingsChanged | () | Sets the tings changed. |
module.onDeserialize | (data) | Restores state from serialized data. |
module.onSerialize | () | Serializes state for saving. Returns data. |
module.getState | () | Returns the state. Returns tableIsEmpty(data) and nil or data. |
module.setState | (data) | Sets the state. |
module.getStateEvents | () | Returns the state events. Returns stateEvents. |
module.isPhysicsStepUsed | () | Check if any controller uses a function relevant to physics step Returns physicsUpdateCount > 0 or fixedStepUpdateCount > 0 or wheelsIntermediateUpdateCount > 0. |
Bullettime Module Reference
Module defined in `lua/vehicle/bullettime.lua`. Manages slow-motion (bullet time) effects for the vehicle by adjusting the simulation time scale. Used for dramatic replays, crash analysis, and cinematic moments.
DamageTracker Module Reference
Module defined in `lua/vehicle/damageTracker.lua`. This is the centralized system for reporting component damage and failure states. It handles update throttling to the UI and manages temporary damage