JBeam Reference
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 hierarchy 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":{ "authors":"example", "name":"Example", "value":5000000000000000, }, "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:"], ], "quads": [ ["id1:", "id2:", "id3:", "id4:"], ], }, }
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 hierarchy.
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:
|
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/buoyancy 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/buoyancy 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":""}, ],
example of a triangles section with a Group:
"triangles": [ ["id1:", "id2:", "id3:"], {"dragCoef":10}, {"group":"door_r_st"}, ["n1","n2","n3"], {"group":""}, ],
example of a triangles section with {"groundModel":"metal"},:
"triangles": [ ["id1:", "id2:", "id3:"], {"groundModel":"metal"}, {"dragCoef":10}, {"group":"door_r_st"}, ["n1","n2","n3"], {"group":""}, ],
example of a triangles section with {"triangleType":"NONCOLLIDABLE"}, section:
"triangles": [ ["id1:", "id2:", "id3:"], {"triangleType":"NONCOLLIDABLE"}, ["n1","n2","n3"], {"triangleType":"NORMALTYPE"}, ], ],
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 |
stallAngle | number | optional | Defines (in radians) the angle where the lift will begin to stall | |
groundModel | string | optional | asphalt | Ground model of the triangle. Determines friction behavior. Possible values:
--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:
"quads": [ ["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)
Vehicle Creation | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Get started: Introduction to Vehicle Creation | ||||||||||||||||
| ||||||||||||||||
See also: JBeam Examples • JBeam Physics Theory |