JBeam-Lua Integration Guide

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

1. JBeam Variables to Lua (#jbeam #core)

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 (#electronics #logic)

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 (#damage #logic)

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 (#powertrain #torque)

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) (#ui #ctrl_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.