Vehicle Engine True Globals

function init(path, initData)           -- Entry point on vehicle spawn
function initSystems()                  -- Internal boot, called after init
function onVehicleLoaded()              -- Called when physics initialization is complete

function updateGFX(dt)                  -- Called every graphics frame (UI rate)
function onGraphicsStep(dtSim)          -- Called every graphics step

function onPhysicsStep(dtPhys)          -- High-frequency physics step (must enable first)
function enablePhysicsStepHook()        -- Enable 2000Hz physics hook
function updateCorePhysicsStepEnabled() -- Check if any module needs physics step

function onDebugDraw(x, y, z)           -- Called when debug drawing is enabled

function onCallEvent(name, data)        -- Generic event dispatcher hook
function onSettingsChanged()            -- Called when game settings change

function onBeamBroke(id, energy)        -- Called when a beam breaks
function onBeamDeformed(id, ratio)      -- Called when a beam deforms
function onTorsionbarBroken(id)         -- Called when a torsion bar breaks
function onDynamicBeamAdded(id)         -- Called when a dynamic beam is created
function onDynamicBeamDeleted(id)       -- Called when a dynamic beam is removed
function onDynamicBeamBroke(id, energy) -- Called when a dynamic beam breaks

function onCouplerFound(cid, obj2id, coupler2cid)  -- Called when a coupler is found
function onCouplerAttached(cid, obj2id, coupler2cid) -- Called when couplers attach
function onCouplerDetached(cid, obj2id, coupler2cid, breakForce) -- Called when couplers detach

function onVehicleReset()               -- Called when vehicle is reset (R key)
function onDespawnObject()              -- Called before vehicle is removed
function onNodeCollision(p)             -- Called when a node collides

function exportPersistentData()         -- Return data to persist across resets
function importPersistentData(data)     -- Restore data from previous session

-- Position & Orientation
obj:getPosition()                       -- Returns vec3 world position
obj:getPositionXYZ()                    -- Returns x, y, z numbers
obj:getRotation()                       -- Returns quat world rotation
obj:getVelocity()                       -- Returns vec3 world velocity
obj:getVelocityXYZ()                    -- Returns vx, vy, vz numbers
obj:getAngularVelocity()                -- Returns vec3 angular velocity
obj:getDirectionVector()                -- Returns forward unit vector
obj:getDirectionVectorUp()              -- Returns up unit vector
obj:getRollPitchYaw()                   -- Returns roll, pitch, yaw angles
obj:getGroundSpeed()                    -- Returns speed relative to ground (m/s)
obj:getAltitude()                       -- Returns height above sea level
obj:calcCenterOfGravity()               -- Returns COG world position

-- Physics Control
obj:setPhysicsStepEnabled(enabled)      -- Toggle 2000Hz physics hook
obj:getPhysicsDt()                      -- Get physics step duration
obj:applyForce(node1, node2, magnitude) -- Apply force between nodes (N)
obj:applyForceVector(nodeId, vector)    -- Apply force vector to node
obj:applyForceTime(n1, n2, mag, dur)    -- Apply force for duration
obj:applyTorqueAxisCouple(mag, n1, n2, n3) -- Apply torque via 3 nodes

-- Node Access
obj:getNodePosition(cid)                -- Get node position relative to ref
obj:getAbsNodePosition(cid)             -- Get node position in world space
obj:getNodeMass(cid)                    -- Get node mass (kg)
obj:setNodeMass(cid, mass)              -- Set node mass dynamically
obj:getNodeVelocityVector(cid)          -- Get node velocity vector
obj:getNodeForceVector(cid)             -- Get force on node
obj:getNodeCluster(cid)                 -- Get cluster ID for node

-- Beam State
obj:beamIsBroken(cid)                   -- Check if beam is broken
obj:getBeamLength(cid)                  -- Get current beam length
obj:getBeamRefLength(cid)               -- Get beam rest length
obj:getBeamStress(cid)                  -- Get beam stress ratio
obj:setBeam(cid, id1, id2, str, spr, damp, ...) -- Modify beam properties
obj:breakBeam(cid)                      -- Manually break a beam

-- Environment
obj:getEnvTemperature()                 -- Get ambient temperature (Kelvin)
obj:getEnvPressure()                    -- Get ambient pressure
obj:getGroupPressure(groupId)           -- Get pressure group pressure
obj:inWater(cid)                        -- Check if node is submerged

-- Audio
obj:createSFXSource(sample, profile, desc, nodeId, flags)  -- Create sound source
obj:playSFX(handle)                     -- Play persistent sound
obj:stopSFX(handle)                     -- Stop persistent sound
obj:playSFXOnce(sample, nodeId, vol, pitch) -- Play one-shot sound

-- Inter-VM Communication (GE Bridge)
obj:queueGameEngineLua(cmd)             -- Execute code in GE context
obj:queueObjectLuaCommand(targetId, cmd) -- Send command to another vehicle
obj:getId() / obj:getID()               -- Get vehicle object ID

-- Management
obj:requestReset(mode)                  -- Request physics reset
obj:setGhostEnabled(enabled)            -- Toggle collision ghosting
obj:setLoadComponent(name, bool)        -- Toggle C++ components
obj:finishLoading()                     -- Finalize JBeam initialization

v.data                                  -- Compiled JBeam structure (nodes, beams, triangles)
v.config                                -- Part configuration and variables
v.data.nodes                            -- Table of all nodes (indexed by CID)
v.data.beams                            -- Table of all beams (indexed by CID)
v.data.triangles                        -- Aerodynamic collision triangles
v.data.refNodes                         -- Reference nodes for orientation
v.data.variables                        -- JBeam variables ($fuel, $tirepressure, etc.)
v.data.powertrain                       -- Powertrain configuration
v.data.energyStorage                    -- Energy storage configuration
v.data.controller                       -- Controller definitions
v.data.electrics                        -- Electrics mappings
v.data.information                      -- Vehicle metadata (name, brand, author)
v.loadVehicleStage2(initData)           -- Internal vehicle loader
v.getPartConfig()                       -- Returns current part configuration

-- Messaging
guihooks.message(msg, ttl, category, icon)     -- Display UI notification toast
-- Example: guihooks.message("Alert!", 5, "safety", "warning")

-- Event Triggering
guihooks.trigger(hookName, ...)                -- Trigger JavaScript event
-- Example: guihooks.trigger("MyEvent", {value = 1})

-- Data Streaming (High Frequency)
guihooks.queueStream(key, value)               -- Queue data for UI sync
guihooks.sendStreams()                         -- Transmit cached stream data
-- Example: guihooks.queueStream("custom_data", 42)

guihooks.triggerStream(streamName, streamData) -- Immediate stream transmission

-- Graphing
guihooks.graph(a, ...)                         -- Send data to Generic Graph app
-- Example: guihooks.graph({"RPM", 3000, 1, "rpm"})

-- Reset
guihooks.reset()                               -- Reset UI state (called on vehicle reset)

-- Loading & Unloading
extensions.load(moduleName)                    -- Load and initialize an extension
extensions.unload(moduleName)                  -- Disable and unload an extension
extensions.reload(moduleName)                  -- Hot-reload an extension from disk
extensions.destroy()                           -- Unload all extensions

-- Hooking (Event Dispatch)
extensions.hook(funcName, ...)                 -- Call function on all loaded extensions
-- Example: extensions.hook("onReset") -- triggers onReset() in all extensions

-- Querying
extensions.isExtensionLoaded(extName)          -- Check if extension is active
extensions.getLoadedExtensionsNames(excludeVirtual) -- Get list of active extensions

-- Module Paths
extensions.addModulePath(directory)            -- Add folder to require() search path

-- Serialization
extensions.deserialize(data, filter)           -- Restore extension states
-- In your extension file (lua/vehicle/extensions/myExt.lua):
local M = {}

function M.onInit()                    -- Called when extension loads
function M.onVehicleLoaded()           -- Called when vehicle physics ready
function M.updateGFX(dt)               -- Called every graphics frame
function M.onPhysicsStep(dt)           -- Called every physics step (if enabled)
function M.onReset()                   -- Called on vehicle reset
function M.onDespawnObject()           -- Called before vehicle removal
function M.onBeamBroke(id, energy)     -- Called when beam breaks

return M

electrics.values                        -- Master table of all electrical values
electrics.disabledState                 -- Table of disabled/overridden values
-- User Inputs (smoothed)
electrics.values.throttle               -- 0 to 1
electrics.values.brake                  -- 0 to 1
electrics.values.clutch                 -- 0 to 1
electrics.values.steering               -- -1 to 1
electrics.values.parkingbrake           -- 0 to 1

-- Engine & Powertrain
electrics.values.rpm                    -- Engine RPM
electrics.values.maxrpm                 -- Max RPM
electrics.values.gear                   -- Gear name ("N", "1", "D", etc.)
electrics.values.gearIndex             -- Gear number
electrics.values.wheelspeed            -- Wheel speed (m/s)
electrics.values.airspeed              -- Air speed (m/s)

-- Vehicle State
electrics.values.ignitionLevel         -- 0=Off, 1=Acc, 2=On, 3=Start
electrics.values.engineRunning         -- 0 or 1
electrics.values.fuel                  -- Fuel level 0 to 1
electrics.values.oiltemp               -- Oil temperature (°C)
electrics.values.watertemp              -- Water temperature (°C)

-- Lights & Signals
electrics.values.signal_L               -- Left turn signal
electrics.values.signal_R               -- Right turn signal
electrics.values.hazard                -- Hazard lights
electrics.values.highbeam              -- High beams
electrics.values.lowbeam               -- Low beams
electrics.values.lightbar              -- Emergency light state
electrics.init()                        -- Initialize electrics module
electrics.reset()                       -- Reset to defaults
electrics.updateGFX(dt)                 -- Update electrics (called by engine)
electrics.setIgnitionLevel(level)      -- Set ignition (0-3)
electrics.horn(state)                  -- Control horn (true/false)
-- Signal controls
electrics.set_left_signal(state, autoCancel)
electrics.set_right_signal(state, autoCancel)
electrics.set_warn_signal(value)
electrics.stop_turn_signal()
-- Light controls
electrics.setLightsState(newval)       -- 0=Off, 1=Low, 2=High
electrics.set_fog_lights(state)
electrics.light_flash_highbeams(enabled)
-- Toggles
electrics.toggle_lights()
electrics.toggle_highbeams()
electrics.toggle_left_signal()
electrics.toggle_right_signal()
electrics.toggle_warn_signal()
electrics.toggle_fog_lights()
electrics.toggle_lightbar_signal()

powertrain.init()                       -- Initialize powertrain
powertrain.reset()                      -- Reset powertrain state
powertrain.update()                     -- Physics update (2000Hz)
powertrain.updateGFX(dt)                -- Graphics update

-- Device Access
powertrain.getDevice(name)              -- Get device by name
-- Example: local engine = powertrain.getDevice("mainEngine")

-- Device Tree Traversal
powertrain.getChild(device, port)       -- Get child device at output port
powertrain.getParent(device)            -- Get parent device

-- Torque Calculation
powertrain.calculateWantedEngineTorque(device, throttle)

-- Device Lists
powertrain.getDevicesByType(type)       -- Get devices by type
powertrain.getDevicesByCategory(cat)    -- Get devices by category

-- Properties
powertrain.engine                       -- Reference to main engine device
powertrain.deviceMap                    -- Map of all devices by name
powertrain.torqueConverter              -- Reference to torque converter (if present)

sounds.init()
sounds.reset()
sounds.updateGFX(dt)
sounds.setSoundParameter(name, value)   -- Set sound effect parameter

props.init()
props.reset()
props.updateGFX(dt)
props.setPropValue(propName, value)     -- Set prop animation value

HighPerfTimer()                         -- Create a high-precision timer
-- Usage: local timer = HighPerfTimer(); ...; local ms = timer:stopAndReset()

tableFromHeaderTable(entry)               -- Convert JBeam header table to dictionary
-- Converts JBeam's {["header1"]=1, ["header2"]=2} format to standard Lua table

saveCompiledJBeam(data, filename, lvl)    -- Write compiled JBeam to file
-- For debugging JBeam compilation

getContrastColor(i, a)                    -- Generate contrasting colors
-- Returns color table for UI/graphing use

createCurve(points, returnArray)          -- Create a spline curve
-- Returns a function that interpolates along the curve

PSItoPascal(psi)                          -- Convert PSI to Pascals
-- Pressure unit conversion utility

-- Physics & Position
obj:getPosition()                       -- vec3 world position
obj:getVelocity()                       -- vec3 velocity (m/s)
obj:getID()                             -- Vehicle ID

-- Vehicle Data
v.data.nodes[cid]                       -- Access node data
v.data.beams[cid]                       -- Access beam data

-- Signals (Data Bus)
electrics.values.rpm                    -- Engine RPM
electrics.values.throttle               -- Throttle input
electrics.values.wheelspeed            -- Speed (m/s)
electrics.values.gear                   -- Current gear

-- Powertrain
powertrain.getDevice("mainEngine")     -- Get engine device
powertrain.getDevice("gearbox")        -- Get gearbox device

-- UI Communication
guihooks.message("Text", 5)             -- Show toast message
guihooks.trigger("Event", data)         -- Trigger UI event
guihooks.queueStream("key", value)      -- Stream to UI

-- Extensions
extensions.hook("onReset")              -- Call hook on all extensions
extensions.isExtensionLoaded("name")   -- Check if extension loaded

-- Debug
print("Debug message")                  -- Log to console