JBeam-Lua Integration Guide

A deep dive into how JBeam data structures and Lua logic communicate in BeamNG.drive.

1. JBeam Variables to Lua

Variables defined in JBeam (e.g., in variables or options) are compiled and accessible in Lua.

• Accessing compiled variables: v.data.variables["$myVar"]
• Accessing active config: v.config.vars["$myVar"]
• Difference: v.data is the final processed structure, while v.config reflects the user's specific part selections.

2. Loading Lua Controllers via JBeam

To load a custom script into a vehicle, use the controller section in your JBeam file.

"controller": [
    ["fileName"],
    ["myCustomScript", {"name": "myLogicInstance", "manualOrder": 100}]
]

• Lua Path: This loads lua/vehicle/controller/myCustomScript.lua.
• Instance Access: You can then access it via controller.getController("myLogicInstance").

3. Connecting JBeam Triggers to Lua

You can fire Lua events based on physical deformation using deformationTriggerRatio.

• JBeam Side:

  "beams": [
      ["id1:", "id2:"],
      {"deformationTriggerRatio": 0.01, "name": "hood_latch_trigger"},
      ["h1", "h2"]
  ]

• Lua Side: Hook into onBeamDeformed(id, ratio) and check if the beam ID matches your trigger.

4. Powertrain Device Mapping

Custom powertrain devices defined in JBeam automatically link to their Lua implementations in lua/vehicle/powertrain/.

"powertrain": [
    ["type", "name", "inputName", "inputIndex"],
    ["combustionEngine", "mainEngine", "dummy", 0]
]

• Instantiation: The engine looks for powertrain/combustionEngine.lua.
• Configuration: Any extra JBeam keys in the device definition are passed to the new(jbeamData) function in Lua.

5. Visual Props (props)

Props are the primary way JBeam meshes react to Lua data.

• func: Links to an entry in electrics.values (e.g., "rpm", "throttle").
• Update Cycle: props.lua runs every frame (onGraphicsStep), mapping the electrics value to mesh rotation/translation.

Summary Workflow

1. Define values or structures in JBeam.
2. Access or Override them in a Lua Controller.
3. Output data to electrics.values.
4. Visualize via JBeam props or glowmaps.

See Also

• AI Module Reference - Related reference
• Backwards Compatibility Module Reference - Related reference
• Bdebug Module Reference - Related reference
• Vehicle Environment Overview - Guide