Beamstate Module Reference
Module defined in `lua/vehicle/beamstate.lua`. This module manages the vehicle's structural integrity, including beam breakage and deformation, couplers (towing/attachment), breakgroups, and tire defl
Module defined in lua/vehicle/beamstate.lua. This module manages the vehicle's structural integrity, including beam breakage and deformation, couplers (towing/attachment), breakgroups, and tire deflation.
| Variable | Type | Description |
|---|
damage | number | Total damage score (physics energy + external damage). |
damageExt | number | Manual damage accumulator for non-physics events (e.g., punctures). |
monetaryDamage | number | Estimated repair cost based on part damage values. |
lowpressure | boolean | True if any tire on the vehicle has lost pressure. |
activeParts | table | List of all currently installed/active part names. |
deformedBeams | table | Tracks the current deformation ratio of structural beams. |
attachedCouplers | table | Maps local nodes to remote vehicle/node connection info. |
nodeNameMap | table | Maps JBeam node names (strings) to physical IDs (e.g., f15 = 143). |
deformGroupDamage | table | Tracks normalized damage (0-1) for every defined deformGroup. |
deformGroupsTriggerBeam | table | Maps deformGroups to the CID of the first beam that triggered them. |
couplerCache | table | Metadata for all available couplers (name, strength, tags, etc.). |
tagBeamMap | table | Maps JBeam tags to lists of associated beam IDs. |
linkTagBeamMap | table | Maps linkTags to lists of associated beam IDs. |
| Function | Signature | Description |
|---|
beamstate.init | () / reset() | Module initialization and state clearing. Rebuilds caches for beams, groups, and couplers. |
beamstate.load | (filename) / save(filename) | Restores or serializes the vehicle's physical state (damage, broken beams) to a JSON file. |
beamstate.update | (dt) | Handles time-based precompression logic during initialization. |
beamstate.updateGFX | (dt) | Main frame update. Ticks planet TTL timers, recalculates total damage score from dissipated energy + external damage, computes monetary damage from part damage coefficients, sends skeleton state updates to UI when beam damage changes, handles auto-coupling retry logic, and transmits electrics/input data across coupled vehicle links. |
| Function | Signature | Description |
|---|
beamstate.addDamage | (val) | Manually adds to the vehicle's external damage score (damageExt). |
beamstate.beamBroken | (id, energy) | Engine callback for beam snaps. Triggers breakgroups and punctures. |
beamstate.onBeamDeformed | (id, ratio) | Engine callback for permanent beam deformation. Triggers deformgroups. |
beamstate.torsionBarBroken | (id, energy) | Callback for torsional spring failure. |
beamstate.isTriangleBroken | (triId) | Checks if a specific collision/aerodynamic triangle has been destroyed. |
| Function | Signature | Description |
|---|
beamstate.breakBreakGroup | (name) / breakAllBreakgroups() | Forces a specific group (or all groups) of beams to snap simultaneously. |
beamstate.breakHinges | () | Convenience function to break all breakgroups containing "hinge" or "latch". |
beamstate.triggerDeformGroup | (name) | Manually triggers the visual effects (glass cracks, light damage) for a group. |
| Function | Signature | Description |
|---|
beamstate.activateAutoCoupling | (tag) / disableAutoCoupling() | Enables/disables automatic attachment to nearby compatible couplers. |
beamstate.attachCouplers | (tag) / detachCouplers(tag, forceLocked, forceWelded) | Manually triggers attachment or detachment for couplers, optionally filtered by tag. |
beamstate.toggleCouplers | (tag) | Cycles through coupler states (Attach -> Auto -> Detach). |
beamstate.couplerExists | (tag) / hasCouplers() | Checks for existence of specific coupler tags or any couplers on the vehicle. Returns boolean. |
beamstate.getCouplerOffset | (tag) | Returns the relative position of couplers compared to the reference node. |
beamstate.setCouplerVisiblityExternal | (id, visible) | Remote call to highlight specific coupler tags. |
beamstate.exportCouplerData | (nodeId, data) / importCouplerData(...) | Logic for transmitting and receiving data (electrics/input) across a coupled link. |
| Function | Signature | Description |
|---|
beamstate.deflateTire | (wheelIndex) / deflateTires() | Triggers immediate pressure loss for specific or all tires. |
beamstate.deflateRandomTire | () | Selects a random inflated tire and triggers a puncture. |
| Function | Signature | Description |
|---|
beamstate.getPartCondition | (partId, partTypeData) | Evaluates the physical condition of a part by checking its breakgroups and beam damage. Determines if the part needs replacement based on thresholds for broken beams, deformed beams, and broken breakgroups. Returns partCondition (table with integrityValue, integrityState, visualValue, visualState), canProvideCondition (boolean)`. |
beamstate.setPartCondition | (partId, partTypeData, odometer, integrity, visual) | Intended to restore part condition from saved data. Currently a partial stub - accepts and normalizes parameters but does not apply physical changes. |
beamstate.getPartDamageData | () / exportPartDamageData() | Exports a map of damage coefficients for every installed part. |
beamstate.requestSkeleton | () / requestSkeletonState() | Triggers UI events to render the vehicle's beam structure and damage state. |
beamstate.getVehicleState | () | Returns a summary table of high-level state (position, direction, condition). |
| Function | Signature | Description |
|---|
beamstate.addPlanet | (center, radius, mass, ttl) / delPlanet(...) | Manages point-gravity sources ("planets") that affect the vehicle's nodes. |
beamstate.setPlanets | (table) | Bulk-sets multiple gravity sources. |
| Function | Signature | Description |
|---|
beamstate.debugDraw | (dt) | Renders coupler ranges and tags when coupler debug is enabled. |
beamstate.updateRemoteElectrics | (retain) | Merges electrics data received from coupled vehicles into local state. |
module.onCouplerAttached | (nodeId, obj2id, obj2nodeId, attachSpeed, attachEnergy) | check if we are dealing with couplers within the same vehicle |
module.isPhysicsStepUsed | () | Checks if physics step used. Returns M.update == update. |