JBeam

JBeam

From BeamNG

Overview

JBeam is the file format that defines the physics skeleton in the BeamNG engine. It is called JBeam as it is based on JSON (with some exceptions) in order to define node/beam constructs.

Just about everything is case sensitive, and it is not at all friendly to syntax errors, so be careful! You create and edit jbeam files using a program such as Notepad++.

Difference to JSON

We modified the JSON parser a bit to make the life of the vehicle authors easier:

  • Comments: C-style, multi-line, and single-line comments are supported: //... and /* ... */
  • Commas: All commas are optional, but it is advised to only omit the commas at the end of lines.

General Structure

{
"vehicle": {
	"refNodes":[
		["ref:", "back:", "left:", "up:"]
		["f3r", "f5r", "f4l", "f8r"]
	],
	"cameraExternal":{
		"distance":6.7,
		"distanceMin":9,
		"offset":{"x":0.43, "y":0.11, "z":0.55},
		"fov":77,
	},
}
}

General Concepts

There are two types of data in a .JBeam file - lists and dictionaries. Lists simply contain values separated by commas within brackets, while dictionaries contain key values within braces. It is possible to have lists within lists, or lists within dictionaries, or any combination of the two. Dictionaries are placed anywhere in a section to set certain attributes, such as beamSpring or nodeWeight.

It is important to reset certain attributes when they're no longer needed, like breakGroup or group. This can be done by setting the value to an empty string:

//reset breakGroup since we no longer need it
{"breakGroup":""}

Example Usage

//this is a list
["value", 1, 123.457, "foobar"],
//this is a dictionary
{"key":"value", "key2":1234.5234, "key3":"blub"},

You are free to format this as you like, i.e.:

[
     "value",
     1,
     123.459,
     "foobar"
],
{
     "key":"value",
     "key2":1234.5234,
     "key3":"blub"
},
// you can also omit the comma at the end of lines:
{
     "key": "value"
     "key2": 1234.5634
     "key3": "blub"
}

Macro Structure

The sections in a file are in fact tables which are expanded when loaded.

	 "SectionName": [
		 // first row: always a list of the columns
		 ["id", "posX", "posY", "posZ"],
		 // afterwards: the row values if a list, if a dict, additional options
		 {"group":"body"},
		 ["f1rr", -0.90, -0.93, 0.23],
		 ["f1r", -0.33, -0.95, 0.23],
		 ["f1l", 0.33, -0.95, 0.23],
		 ["f1ll", 0.90, -0.93, 0.23],		 
	],

Table Headers

The table headers can have a special linking associated to them depending on the column name:

  • Columns with a ":" in it will link to other sections.
    • "nodeID:" will link the values in this column to the associated node. Notice that, for simplicity reasons, you can leave the "nodes". I.e. "nodeID:nodes" is the same as "nodeID:"
    • "beamID:beams" will link the values in this column to the associated beam.

Global Modifiers

There are a few variables that can be set anywhere in the main "vehicle" dictionary which affect the .JBeam globally. This is an example of a few. The most useful of these are the various scales. If the vehicle is slightly too stiff, heavy, or isn't crumpling up enough, only one value needs to be changed to globally scale certain values and correct such problems.

{
"vehicle": {
	// [...]
	 "selfCollisionThickness":0.02,
	 "remoteCollisionThickness":0.06,
	 "scalenodeWeight":0.95,
	 "scalebeamSpring":0.75,
	 "scalebeamDamp":0.73,
	 "scalebeamDeform":0.42,
	 "scalebeamStrength":0.65,
	 "zeroOutSelfCollision":false,
	 // [...]
}
}

Sections

Every .JBeam file is made up of many sections, all of which serve different purposes. Some sections are required, while others are optional.