JBeam Reference

JBeam Reference

From BeamNG

This page is the basic reference book to get started building JBeam files. It covers the required and optional settings in every section, along with a quick description of what the settings do, and when available, links to more in depth explanations.

Parts

The jbeam system is designed to split the vehicle up into different parts. Each part is a block of jbeam that is read and loaded together. One can think of a part just like the part of a car; a door, fender, hood, etc. Any object that exists as a part of the vehicle can be a part in jbeam. Parts are organized into a hierarchy by use of the slot system. It does not matter which .jbeam file the part is contained in, or what the name of the .jbeam file is, as long as it is in the vehicle folder. This heirarchy design is important so that, for example, you can only load a wheel once you have loaded the suspension that it would connect to.

In jbeam, a part looks like this:

{
    "example_part": {
        "information":{
        }
        "slotType" : "main",
        "slots": [
            ["type", "default", "description"]
        ],
        "refNodes":[
            ["ref:", "back:", "left:", "up:"]
        ],
        "flexbodies": [
             ["mesh", "[group]:", "nonFlexMaterials"],
        ],
        "nodes": [
            ["id", "posX", "posY", "posZ"],
        ],
        "beams": [
            ["id1:", "id2:"],
        ],    
        "triangles": [
            ["id1:","id2:","id3:"],
        ],
    }
}

The very first and last curly brackets {} define the start and end of the file. Inside of these is another set of curly brackets. Within those, one can see a single part, with a part name "example_part". All of the data inside of the second set of curly brackets is read as a single part and given that name. In the above example part, there are a bunch of "sections" shown empty, except for a single line called the "header". All of the data of a part is placed within these sections.

Basic sections of a part

information

The information section defines some basic information about the part itself

example of an information section:

"information":{
    "authors":"BeamNG",
    "name":"Frame",
    "value":10000,
}
Name Type Optional Default Value Description
name string optional "" Defines the name of the part
authors string optional "" Defines the authors of the part
value number optional n/a Defines the value (cost) of the part

slots

Slots provide a way to create a hierarchy of parts and allow different configurations for a vehicle. The slot hierarchy in jbeam corresponds directly to the hierarchy in the game's part selector or garage menus. The "slots" section tells the game to look for any other parts with a "slotType" which matches "type", and then allow any of those matching parts to be loaded after the current part, in a lower place in the heirarchy.

example of a slots section:

"slots": [
    ["type", "default", "description"]
    ["coupe_steer","coupe_steer_airbag", "Steering Wheel", {"nodeOffset":{"x":0, "y":0, "z":0}}],
    ["coupe_glass","coupe_glass", "Glass", {"coreSlot":true}],
    ["coupe_fender_R","coupe_fender_R", "Right Fender"],
    ["coupe_fender_L","coupe_fender_L", "Left Fender"],
],
Name Type Optional Default Value Description
type string required n/a Defines the "type" for this slot. The game will look for parts with a "slotType" which matches "type", and allow those matching parts to be loaded
default string required n/a The name of the default part to be loaded if one has not been chosen by a configuration file or by the parts selector/garage
description string optional type The description of this part, shown as description text in the parts selector/garage
nodeOffset float3 optional 0,0,0 The offset of nodes and flexbodies of this slot
coreSlot string optional n/a If enabled, the choice to have the part empty is removed from the part selector/garage

refNodes

Example of reference nodes:

    "refNodes":[
        ["ref:", "back:", "left:", "up:", "leftCorner:", "rightCorner:"]
        ["fr9", "fr10", "fr9l", "fr11", "f7ll", "f7rr"]
    ],

This section defines a coordinate system from the vehicle nodes, so that the game can know the location and rotation of the vehicle. This reference is used by the cameras, the A.I, vehicle spawning, and also to trigger checkpoints in scenarios.

It is mandatory to have this section on the vehicle at all times!

Name Type Optional Default Value Description
ref string required n/a A node near the center and lowest point of the vehicle body (it doesn't need to be in the 0,0,0 node position, but usually is close to it)
back string required n/a A node directly behind the ref node (y axis)
left string required n/a A node directly left of the ref node (x axis)
up string required n/a A node directly above the ref node (z axis)
leftCorner string required n/a A node at the front left corner of the vehicle Used to trigger checkpoints.
rightCorner string required n/a A node at the front right corner of the vehicle. Used to trigger checkpoints.

nodes

Nodes are the core of BeamNG physics. Everything revolves around these mass points. A node itself is a dimensionless (infinitely small) mass point in 3D space

example of a basic nodes section:

"nodes" :[
    ["id", "posX", "posY", "posZ"],
    ["n1rr", -0.90, -0.93, 0.23],
],

example of a nodes section with some properties:

"nodes" :[
    ["id", "posX", "posY", "posZ"],
    {"collision":true},
    {"selfCollision":true},
    {"nodeWeight":35},
    {"nodeMaterial":"|NM_PLASTIC"},
    {"group":"body"},
    ["n1rr", -0.90, -0.93, 0.23],
    ["n1ll", 0.90, -0.93, 0.23],
    {"group":""},
],
Name Type Optional Default Value Description
id string required n/a Defines the node name
posX number required n/a The X (left/right) position in 3D space
posY number required n/a The Y (forward/back) position in 3D space
posZ number required n/a The Z (up/down) position in 3D space
nodeWeight number optional options.nodeWeight The weight of the node (kg)
collision boolean optional true If the node can collide with the world
selfCollision boolean optional false If the node can collide with the vehicle
group string optional n/a Groups a select set of nodes into a group
frictionCoef number optional 1.0 Friction coefficient of the node
nodeMaterial string/bitmask optional options.nodeMaterial Material of the node. Affects particles, skidmarks and sounds. Values used: "|NM_RUBBER", "|NM_METAL", "|NM_PLASTIC", "|NM_GLASS"
fixed boolean optional false Set to true to create a node that is locked in 3D space using its absolute coordinates
surfaceCoef number optional 0.1 Makes a node have more or less drag area in ground models with depth
volumeCoef number optional 0.1 Makes a node more or less buoyant in ground models with depth
pairedNode number / node ID optional null This can be used to i.e. link double tires together

beams

Beams are an important structural element of a JBeam structure. Beams are springs connections between nodes.

Example of a beams section:

"beams": [
      ["id1:", "id2:"],
      {"breakGroupType":1},
      {"breakGroup":"frame"},
      {"beamSpring":1251000,"beamDamp":250},
      {"beamDeform":16000,"beamStrength":24000},
      ["f1rr","f1r"],
      ["f1r","f1l"],
      ["f1l","f1ll"],
      {"breakGroupType":0},
      {"breakGroup":""},
],

The following table shows parameters that can be applied to all beams:

Name Type Optional Default Value Description
id1 string required n/a Name of the first node
id2 string required n/a Name of the second node
beamType string/bitmask optional NORMALTYPE Sets the type of the beam. Possible values:
  • NORMALTYPE
  • BEAM_HYDRO
  • BEAM_ANISOTROPIC
  • BEAM_BOUNDED
  • BEAM_PRESSURED
  • BEAM_SUPPORT
  • BEAM_BROKEN
  • BEAM_LBEAM
beamStrength number optional options.beamStrength Strength of the beam. How much force the beam can resist before breaking (N).
beamSpring number optional options.beamSpring Spring of the beam. How much a beam will change length when a force is applied (N/m).

Analogous to terms such as stiffness, rigidity, or modulus.

beamDamp number optional options.beamDamp Damp of the beam. How much energy is dissipated as a beam changes length (N/m/s).

Damping causes vibration in the beam to fade out over time.

beamDeform number optional options.beamDeform Deform of the beam. How much force the beam can resist before it deforms permanently (N).
beamPrecompression number optional 1.0 Pre-compression of the beam. How much longer or shorter the beam will try to become as soon as it spawns.

2.0 would be twice the length, 0.5 would be half the length.

breakGroup string optional "" The breakGroup of this beam. Breakgroups are used to make sure a group of beams breaks together. Useful to allow parts to fall off easily when only some beams are damaged, or for beams to act as triggers for other events.
breakGroupType number optional 0 This sets the breakGroup behaviour. if set to 0, this beam will break others in the breakGroup. if set to 1, this beam will NOT break others in the breakGroup, but will be broken by the group.

Anisotropic

Anisotropic beams have a special non linear behavior allowing different spring and damp if the beam is expanded or contracted. Special parameters are as follows:

Name Type Optional Default Value Description
springExpansion number optional options.beamSpring Spring of the beam when the beam has expanded beyond spawned length (N/m).
dampExpansion number optional options.beamDamp Damp of the beam when the beam has expanded beyond spawned length (N/m/s).
beamLongBound number optional infinity
transitionZone number optional 0 This defines a range where the spring and damp move to springExpansion and dampExpansion.

By default, the beam properties change instantly beyond spawned length, but adding transitionZone causes the values to ramp up over a zone. 0.1 would create a zone of 10% of beam spawned length.

Bounded

Bounded beams are a special type of beam that can change spring and damping depending on length and velocity. They are primarily used for shock absorbers and collision limiters. Once a bounded beam has reached a bound, its properties begin to change from the basic property to the limit property over a 1m distance. Use of bounded beams should be minimized since their advanced properties come with a performance cost. Special parameters are as follows:

Name Type Optional Default Value Description
beamLongBound number optional 1.0 How far the beam can expand before limit properties begin to apply.

0.0 would mean that the limit properties begin to apply as soon as the beam expands.

0.5 would mean that the beam can expand to 150% of its spawned length before limit properties begin to apply.

1.0 would mean that the beam can expand to 200% of its spawned length before limit properties begin to apply.

beamShortBound number optional 1.0 How short the beam can go before limit properties begin to apply.

0.0 would mean that the limit properties begin to apply as soon as the beam contracts.

0.5 would mean that the beam can contract to 50% of its spawned length limit properties begin to apply.

1.0 would mean that the beam can contract its entire length before limit properties begin to apply.

beamLimitSpring number optional 1.0 The spring that begins to be applied when the beam length reaches longBound or shortBound (N/m).
beamLimitDamp number optional 1.0 The damping that begins to be applied when the beam length reaches longBound or shortBound (N/m/s).
beamLimitDampRebound number optional 1.0 The damping that begins to be applied when the beam length reaches longBound or shortBound (N/m/s), but only when rate of expansion is > 0.

beamLimitDamp will continue to affect the beam when rate of contraction is > 0 and the beam has reached a bound.

beamDampRebound number optional beamDamp The damping value applied only when the beam's rate of expansion is > 0 (N/m/s).

beamDamp will continue to affect the beam when rate of contraction is > 0.

beamDampFast number optional beamDamp The damping value for the beam when the beam's rate of contraction or expansion is > beamDampVelocitySplit (N/m/s).
beamDampReboundFast number optional beamDampRebound The rebound damping value for the beam when the beam's rate of expansion is > beamDampVelocitySplit (N/m/s).

beamDampFast will continue to affect the beam when rate of contraction is > beamDampVelocitySplit.

beamDampVelocitySplit number optional infinity The rate (m/s) of contraction/expansion over which beamDampFast and beamDampReboundFast take effect (m/s).

Support

Support beams are a special type of beam that can only resist compression. They can also break automatically at a set length. Primarily used for collision limiters. Special parameters are as follows:

Name Type Optional Default Value Description
beamLongBound number optional 1.0 When this bound is exceeded, the beam automatically breaks.

0.0 would mean the beam breaks if it expands at all. 0.5 would mean the beam breaks after expanding to 150% of its spawned length. 1.0 would mean the beam breaks after expanding to 200% of its spawned length.

Pressured

Pressured beams are mainly used in the hubWheel tire model to simulate air pressure with beams. Special parameters are as follows:

Name Type Optional Default Value Description
pressure number optional
surface number optional 1.0
volumeCoef number optional 1.0
maxPressure number optional

L-Beam

L-Beams are primarily used in pressureWheels since 0.5.2.0. They are a type of beam that acts like an angular spring between two other beams. Special note: L-beams do not have deform or strength properties, but can break when either of the beams that form the "L" break. Special parameters are as follows:

Name Type Optional Default Value Description
id3 string required n/a Name of the third node. The third node must already be connected to nodes [id1] and [id2] with beams.

Any change in angle between beams [id1,id3] and [id2,id3] is then resisted by the L-Beam from [id1,id2]. Example L-Beam definition: ["node_id1","node_id2",{"id3:":"node_id3"}],

flexbodies

Flexbodies are the meshes that are mapped to your nodes. Without them, there's nothing to look at.

example of a basic flexbodies section:

"flexbodies": [
     ["mesh", "[group]:", "nonFlexMaterials"],
     ["barstow_trunk", ["barstow_trunk"]],
     ["barstow_lettering_barstow", ["barstow_trunk"]],
],

example of a flexbodies section with positioning:

"flexbodies": [
     ["mesh", "[group]:", "nonFlexMaterials"],
     //Rims
     ["offroadwheel_01a_17x9", ["wheel_FR","wheelhub_a_FR","wheelhub_b_FR"], [], {"pos":{"x":-0.8375, "y":-1.463, "z":0.46}, "rot":{"x":0, "y":0, "z":180}, "scale":{"x":1, "y":1, "z":1}}],
     ["offroadwheel_01a_17x9", ["wheel_FL","wheelhub_a_FL","wheelhub_b_FL"], [], {"pos":{"x": 0.8375, "y":-1.463, "z":0.46}, "rot":{"x":0, "y":0, "z":0}, "scale":{"x":1, "y":1, "z":1}}],
     //Tires
     ["offroadtire_01a_17x9_33", ["wheel_FR","wheelhub_a_FR","wheelhub_b_FR"], [], {"pos":{"x":-0.8375, "y":-1.463, "z":0.46}, "rot":{"x":0, "y":0, "z":0}, "scale":{"x":1, "y":1, "z":1}}],
     ["offroadtire_01a_17x9_33", ["wheel_FL","wheelhub_a_FL","wheelhub_b_FL"], [], {"pos":{"x": 0.8375, "y":-1.463, "z":0.46}, "rot":{"x":0, "y":0, "z":0}, "scale":{"x":1, "y":1, "z":1}}],
],
Name Type Optional Default Value Description
mesh string required n/a Name of the mesh (as named in the .dae file)
group array required n/a Array of node groups this flexbody will bind to
nonFlexMaterials array optional nonFlexMaterials is a deprecated legacy feature that is not used or usable anymore
pos float3 optional 0,0,0 The position offset of the flexbody
rot float3 optional 0,0,0 The rotation of the flexbody
scale float3 optional 1,1,1 The scale offset of the flexbody

triangles

Triangles are a type of surface with collision, drag/lift, and pressure/bouyancy effects. A triangle is defined between three nodes. The order the nodes are defined (clockwise or counterclockwise) determines which direction the triangle faces, important for collision and pressure/bouyancy behavior.

example of a basic triangles section:

"triangles": [
      ["id1:", "id2:", "id3:"],
      {"dragCoef":10},
      {"liftCoef":100},
      ["n1","n2","n3"],
],

example of a triangles section with a pressureGroup:

"triangles": [
      ["id1:", "id2:", "id3:"],
      {"dragCoef":10},
      {"pressureGroup":"hull"},
      {"pressurePSI":0},
      ["n1","n2","n3"],
      {"pressureGroup":""},
],
Name Type Optional Default Value Description
id1 string required n/a Name of the first node
id2 string required n/a Name of the second node
id3 string required n/a Name of the third node
dragCoef number optional 10 Drag coefficient of the triangle as a percentage of a flat plate of the same size.
liftCoef number optional dragCoef Lift coefficient of the triangle as a percentage of a flat plate of the same size. By default this value is equal to dragCoef
groundModel string optional asphalt Ground model of the triangle. Determines friction behavior. Possible values:
  • asphalt
  • dirt
  • rock
  • metal
  • grass
  • sand
  • rockydirt
  • dirt_grass
  • ice
  • snow
  • mud
  • kickplate

--see art/groundmodels.json for more possibilities

pressureGroup string optional Pressure group of the triangle
pressurePSI number optional Sets the pressureGroup pressure in PSI
pressure number optional Sets the pressureGroup pressure in Pascal
breakGroup string optional Used to trigger triangles to break in a group, triggered by any beams in that same group. Broken beams can trigger triangles to break, but broken triangles cannot trigger beams to break.

quads

Quads are meant to simplify the creation of triangles. All parameters from triangles (dragCoef, pressureGroup, etc) are also supported on quads. The way a quad is created, is by creating two triangles. One between node1->node2->node3, and one between node3->node4->node1.

example of a basic quads section:

"triangles": [
      ["id1:", "id2:", "id3:", "id4:"],
      {"dragCoef":10},
      {"liftCoef":100},
      ["n1","n2","n3","n4"],
],
Name Type Optional Default Value Description
id1 string required n/a Name of the first node
id2 string required n/a Name of the second node
id3 string required n/a Name of the third node
id4 string required n/a Name of the fourth node

Quads also share the properties of triangles


Comments in JBeam

1] //
This is for commenting out single lines of JBeam. Example below:

            //["f1rr","f1r"],

2] /* */
This is for commenting out blocks of JBeam. The /* begins the comment, and this */ ends the comment. Example below:

            /*
            {"beamSpring":1251000,"beamDamp":250},
            {"beamDeform":16000,"beamStrength":24000},
            ["f1rr","f1r"],
            ["f1r","f1l"],
            ["f1l","f1ll"],
            */

Take note that it isn't allowed to have a disabled section within a disabled section. Although a disabled line within a disabled section is allowed:

            /*
            {"beamSpring":1251000,"beamDamp":250},
            {"beamDeform":16000,"beamStrength":24000},

            /*//THIS IS NOT ALLOWED AND WILL CAUSE ERRORS
            ["f1rr","f1r"],
            ["f1r","f1l"],
            ["f1l","f1ll"],
            */
            */

3] [optional = TRUE]

It is also possible to make beams or triangles 'optional'. This means that if a beam or triangle cannot be generated when the vehicle loads (for ex, if a required node is missing) it doesn't show up with warnings in the console. By hiding intentionally missing beams, it makes it easier to notice an accidental missing beam or triangle if there is a typo or some other problem.

            {"optional":true}
            {"breakGroup":["sunburst_doorhinge_a_FR","sunburst_doorhinge_b_FR","sunburst_fender_a_R"]},
            ["d7r", "fe3r", "fe7r"],
            ["d7r", "d4r", "fe3r"],
            ["d4r", "d1r", "fe3r"],
            ["fe3r", "d1r", "fe1r"],
            {"optional":false}

Tdev (talk) 03:05, 6 February 2016 (CET)