obj (Vehicle C++ Object) The `obj` global is a C++ binding to the `Vehicle` object in the engine. It provides direct access to the vehicle's physical state and low-level physics modifications. This is the primary interface fo
The obj global is a C++ binding to the Vehicle object in the engine. It provides direct access to the vehicle's physical state and low-level physics modifications. This is the primary interface for vehicle-side Lua to interact with the C++ physics core.
Variable Description obj.debugDrawProxyA userdata proxy used for custom C++ level debug visualizations.
Function Signature Description obj:getId() / obj:getID()Returns the unique vehicle object ID assigned by the engine. obj:finishLoading()Finalizes JBeam structural initialization. This must be called if nodes or beams are manually modified during the init sequence. obj:commitLoad()Commits the currently loaded JBeam structural data to the C++ physics engine. obj:requestReset(mode)Triggers a vehicle reset. obj:respawnWithPartConfig(config)Respawns the vehicle instance with a new part configuration. obj:initLuaCallbacks()Re-initializes the Lua callback triggers for the vehicle object.
Function Signature Description obj:getPosition() / obj:getPositionXYZ()Returns the vehicle's world position. getPositionXYZ returns three numbers (x, y, z) for better performance in tight loops. obj:getRotation()Returns the vehicle's world rotation as a quaternion. obj:getVelocity() / obj:getVelocityXYZ()Returns the vehicle's world velocity vector. obj:getDirectionVector() / obj:getDirectionVectorUp() / obj:getDirectionVectorRight()Returns the forward, up, or right unit vectors relative to the vehicle's orientation. obj:getForwardVector()Alias for getDirectionVector. obj:getRollPitchYaw() / obj:getRollPitchYawRad()Returns the roll, pitch, and yaw angles of the vehicle in degrees or radians. obj:getRollPitchYawAngularVelocity()Returns the angular velocity vector for the vehicle's primary axes. obj:getPitchAngularVelocity() / obj:getRollAngularVelocity() / obj:getYawAngularVelocity()Returns specific angular velocity rates for pitch, roll, or yaw. obj:getAltitude()Returns the vehicle's height above sea level (Z coordinate). obj:getGroundSpeed() / obj:getAirSpeed()Returns the vehicle's scalar speed relative to the ground surface or the surrounding air. obj:getAirflowSpeed() / obj:getFrontAirflowSpeed()Returns airflow speeds measured generally or at the vehicle's front plane. obj:getFrontPosition() / obj:getFrontPositionRelative()Returns the world or local relative position of the vehicle's front center point. obj:getCenterPosition() / obj:getObjectCenterPosition()Returns the world position of the vehicle's physical center. obj:getCornerPosition(idx)Returns the world position of a specific corner of the vehicle's bounding box. obj:calcCenterOfGravity() / obj:calcCenterOfGravityRel()Calculates the real-time position of the Center of Gravity (COG) in world or relative coordinates. obj:getInitialHeight() / obj:getInitialLength() / obj:getInitialWidth()Returns the dimensions of the vehicle as originally defined in the JBeam files. obj:getInitialQuaternion()Returns the vehicle's rotation at the moment of spawning. obj:getCameraPosition()Returns the world position of the currently active camera attached to this vehicle.
local x, y, z = obj : getPositionXYZ () local rot = obj : getRotation () Function Signature Description obj:getGravity() / obj:getGravityVector() / obj:setGravity(val)Accesses or overrides the gravity strength or vector affecting this vehicle. obj:getWind() / obj:setWind(x, y, z)Gets or sets the ambient wind velocity vector affecting aerodynamics. obj:getEnvTemperature() / obj:getEnvPressure()Returns the ambient temperature (Kelvin) and atmospheric pressure (Pa) at the vehicle's location. obj:getAirDensity() / obj:getAirDensityAtSeaLevel() / obj:getRelativeAirDensity()Returns air density data used for drag and engine performance calculations. obj:getTerrainHeight(x, y) / obj:getTerrainNormal(x, y)Queries the map's terrain height or surface normal vector at specific coordinates. obj:getTerrainDrivability(x, y)Returns the "drivability" coefficient (grip/roughness) defined for the ground model at that location. obj:getDistanceFromTerrain() / obj:getDistanceFromTerrainPoint(x, y, z)Returns the vertical distance from the vehicle (or point) to the ground surface. obj:getSurfaceHeightBelow(x, y, z)Returns the height of the first physical surface detected below the specified point. obj:inWater(cid) / obj:setWaterFlow(x, y, z)Checks if a node is below the water plane or sets the global water current velocity. obj:getFlow()Returns the combined water/air flow vector currently acting on the vehicle body. obj:setPlanets(count)Internal setting for planetary gravity simulation nodes.
Function Signature Description obj:getPhysicsDt() / obj:getPhysicsFPS()getPhysicsDt returns the fixed time step (default 0.0005s for 2000Hz). getPhysicsFPS returns the actual calculation rate.obj:getSimTime() / obj:getSimulationTimeScale() / obj:setSimulationTimeScale(scale)Manages the total simulation time elapsed and the speed of physics (slow-motion). obj:getRealdt()Returns the actual real-world time delta since the last frame, regardless of time scale. obj:getGraphicsStepCount()Returns the total count of rendered frames. obj:setPhysicsStepEnabled(enabled)Enables or disables the high-frequency onPhysicsStep callback. Use only for essential 2000Hz logic. obj:setSleepingEnabled(enabled)Toggles physics optimization where stationary vehicles consume less CPU. obj:getGhostEnabled() / obj:setGhostEnabled(enabled)Controls collision ghosting (visual-only vehicle). obj:applyForce(nodeId, x, y, z) / obj:applyForceTime(...)Applies a raw force vector to a single JBeam node. obj:applyForceVector(nodeId, vector) / obj:applyForceVectorTime(...)Applies a directional force vector to a node. obj:applyTorqueAxisCouple(magnitude, n1, n2, n3)Applies a torque couple using three nodes to define the torque plane. obj:calcCenterOfPressureRel()Calculates the relative position of the vehicle's Center of Pressure for aerodynamic forces. obj:calcTotalAeroForces() / obj:calcTotalAeroTorque()Returns the sum of all aerodynamic drag, lift, and side forces/torques. obj:setAerodynamicsMode(mode) / obj:getAerodynamicsMode()Configures the fidelity of the aerodynamic simulation.
Function Signature Description obj:getNodeCount()Returns the total number of physical nodes in the JBeam structure. obj:getNodePosition(cid) / obj:getAbsNodePosition(cid)Returns the node's position relative to reference nodes or in world space. obj:getNodePositionRelativeXYZ(cid)Returns the x, y, z coordinates of the node relative to the vehicle's reference nodes. obj:setNodePosition(cid, x, y, z)Forcibly teleports a JBeam node to a specific world position. obj:getNodeMass(cid) / obj:setNodeMass(cid, mass)Gets or dynamically overrides the physical mass of a node. obj:getNodeVelocity(cid) / obj:getNodeVelocityVector(cid)Returns the current world velocity vector of a node. obj:getNodeForce(cid) / obj:getNodeForceVector(cid)Returns the instantaneous physical force magnitude or vector acting on a node. obj:getNodeReactionForce(cid)Returns the reaction force generated by collisions at this node. obj:getNodeTemperature(cid)Returns the current temperature of a specific node. obj:getDensityAtNode(cid)Returns the atmospheric density at the node's current location. obj:getNodeFrictionCoef(cid) / obj:setNodeFrictionSlidingCoefs(cid, f, s)Manages surface friction properties for an individual node. obj:isNodeColliding(cid)Returns true if the node is currently in physical contact with another object or terrain. obj:getNodeCluster(cid) / obj:inSameNodeCluster(n1, n2)Checks physical node cluster assignments (used for deformation and optimization).
Function Signature Description obj:getBeamCount()Returns the total number of physical beams in the structure. obj:getBeamLength(cid) / obj:getBeamRestLength(cid) / obj:getBeamRefLength(cid)Returns the current, rest, or reference length of a structural beam. obj:getBeamForce(cid) / obj:getBeamStress(cid)Returns the current physical force or internal stress value of a beam. obj:getBeamDeformation(cid) / obj:getBeamDebugDeformation(cid)Returns the permanent deformation ratio (strain residue) of a beam. obj:beamIsBroken(cid) / obj:breakBeam(cid)Boolean status check or manual structural breakage of a beam. obj:setBeam(cid, ...) / obj:setBeamSpringDamp(cid, s, d) / obj:setBeamStrength(cid, s)Dynamically overrides physical properties of a structural beam. obj:setPrecompressionRatio(cid, r)Sets the precompression target for a beam (used for active suspension or structural tension). obj:actuateBeam(cid, ...)Directly actuates a beam (e.g., hydraulic pistons).
Function Signature Description obj:addDynamicBeamNode(n1, n2, ...)Creates a new physical beam at runtime between two existing nodes. obj:deleteDynamicBeam(id) / obj:deleteAllDynamicBeam()Removes dynamically created structural beams.
Function Signature Description obj:getTriangleCount() / obj:isTriangleBroken(tid) / obj:breakCollisionTriangle(tid)Manages collision and aerodynamic triangles. obj:addRail(id, ...) / obj:addRailLink(id, ...) / obj:breakRails(id)Manages physical paths (rails) used by slidenodes.
Function Signature Description obj:addSlidenode(id, ...) / obj:attachSlidenode(id, ...) / obj:detachSlidenode(id)Manages nodes that are constrained to slide along predefined physical rails. obj:attachCoupler(id, ...) / obj:detachCoupler(id) / obj:stopLatching()Manages structural coupling/uncoupling logic (e.g., trailers, doors). obj:externalCouplerCount()Returns the total count of active external structural connections.
Function Signature Description obj:getWheel(idx)Returns a handle to the C++ Wheel object for specialized physics queries. obj:getWheelAvgTemperature(idx) / obj:getWheelCoreTemperature(idx)Returns the current averaged or core temperature of the tire. obj:setWheelTorqueAndBrakeTorque(idx, t, b)Directly overrides the torques applied to a specific wheel. obj:wheelTurnRadius(wid)Returns the current calculated steering turn radius for a specific wheel. obj:setSlipTireMarkThreshold(t)Sets the wheel slip energy level required to trigger skid mark rendering.
Function Signature Description obj:switchMaterial(msc, mat) / obj:resetMaterials(msc)Swaps material states for visual effects (glowmaps, cracked glass). obj:getSwitchableMaterial(msc)Returns the name of the material currently active on a specific JBeam material switch. obj:setMaterialEmissiveFactor(msc, color)Controls the intensity and color of emissive materials (e.g., dashboards, headlights). obj:setPropLight(id, b, s, c)Configures point light and flare properties for moving JBeam props. obj:addDecal(pos, normal, ...) / obj:addParticle(pos, vel, ...)Spawns world decals (skid marks, mud) or physical particles (smoke, sparks).
Function Signature Description obj:createSFXSource(s, p, d, n, f)Creates a persistent 3D sound source handle attached to a vehicle node. obj:playSFX(id) / obj:stopSFX(id) / obj:isPlayingSFX(id)Controls persistent audio playback. obj:playSFXOnce(sample, node, v, p)Triggers a non-looping 3D sound effect at a node's location. obj:setSFXparameter(id, name, val) / obj:setVolumePitch(id, v, p)Real-time updates for active sound sources.
Function Signature Description obj:createWebView(w, h) / obj:queueWebViewJS(id, js)Manages high-performance in-game web textures used for digital dashboards. obj:sendRPMLeds(rpm, min, max)Updates hardware LED indicators on supported peripherals. obj:setDebugString(str)Overlays text on the screen for vehicle-specific debug logging.
Function Signature Description obj:queueLuaCommand(cmd)Schedules code to run in the Vehicle context during the next update cycle. obj:queueGameEngineLua(cmd)Sends code to the Game Engine (GE) Lua context for world-level execution. obj:queueObjectLuaCommand(id, cmd)Sends code to be executed in the context of another vehicle instance . obj:sendForceFeedback(type, mag)Sends torque feedback signals to the player's hardware controller.
Function Signature Description obj:getTorsionbarAngle(id) / obj:torsionbarIsBroken(id)Accesses the physical state of torsional spring components. obj:setTorsionbarAngle(id, a)Manually sets the target twist angle for a torsion bar.
Function Signature Description obj:getSensorVectorRaw(name)Returns raw vector data from high-frequency C++ sensors. obj:getSensorX() / obj:getSensorY() / obj:getSensorZ()Returns G-force/accelerometer sensor components. obj:getSensorsFFI()Returns an FFI pointer for the most efficient possible sensor data access.
Function Signature Description obj:getGroupPressure(group) / obj:setGroupPressure(group, p)Manages absolute internal pressure for JBeam pressure groups (e.g., tires). obj:deflatePressureGroup(group)Triggers immediate and rapid pressure loss for a group.