Prefabs (.prefab and .prefab.json)

This document describes BeamNG prefab files and how they are loaded by the engine.

Prefabs are reusable groups of scene objects. They allow several objects to be stored in a separate file and placed into a level as a single object.

BeamNG supports two prefab formats:

• Legacy TorqueScript .prefab
• Modern JSON .prefab.json prefabs

Overview

A prefab is represented in the level by a Prefab object. The Prefab object points to an external file using its filename field. When loaded, the prefab reads that file and creates a child SimGroup containing the objects stored inside.

Typical use cases:

• Reusable buildings
• Roadside prop groups
• Repeated scenery pieces
• Mission objects
• Groups of static meshes
• Spawn setups
• Vehicle showcase setups

Example level object:

{
  "class": "Prefab",
  "name": "gas_station_prefab",
  "filename": "/levels/example/prefabs/gas_station.json",
  "position": [100, 200, 0],
  "rotationMatrix": [1,0,0,0,1,0,0,0,1],
  "scale": [1, 1, 1],
  "loadMode": "Automatic"
}

File roles

Prefab object fields

loadMode

Supported values:

Modern JSON prefabs

Modern JSON prefabs are loaded when the filename contains .json.

A JSON prefab must create a root SimGroup. The engine expects one of the objects in the file to be a SimGroup, and that group becomes the prefab child group.

Minimal JSON prefab

{"class":"SimGroup","name":"example_prefab_group"}
{"class":"TSStatic","name":"example_prop","shapeName":"/levels/example/art/shapes/prop.dae","position":[0,0,0],"rotationMatrix":[1,0,0,0,1,0,0,0,1],"scale":[1,1,1]}

JSON prefab layout

JSON prefabs are commonly stored as line-based JSON object data, similar to level main object files. Each object is serialized as a JSON object.

A typical prefab contains:

1. A root SimGroup
2. One or more scene objects
3. Optional nested groups
4. Optional vehicles or other supported objects

Example:

{"class":"SimGroup","name":"garage_prefab_group"}
{"class":"TSStatic","name":"garage_building","shapeName":"/levels/example/art/shapes/garage.dae","position":[0,0,0],"rotationMatrix":[1,0,0,0,1,0,0,0,1],"scale":[1,1,1]}
{"class":"PointLight","name":"garage_light","position":[0,2,3],"rotationMatrix":[1,0,0,0,1,0,0,0,1],"scale":[1,1,1],"intensity":800}

Root SimGroup

The root SimGroup acts as the container for all prefab objects.

When the prefab is loaded:

• The engine finds the SimGroup
• Removes it from any incorrect parent if needed
• Assigns it as the prefab child group
• Applies prefab transform to all child SceneObjects
• Tracks child objects as belonging to the prefab

For JSON prefabs, the root group may be renamed automatically to match the prefab name.

Example:

{"class":"SimGroup","name":"garage_group"}

noAutoReload

A root SimGroup can contain noAutoReload.

{"class":"SimGroup","name":"garage_group","noAutoReload":true}

If noAutoReload is true, the prefab file is not tracked for automatic reload.

This can be useful when working with generated or special-purpose prefabs that should not reload automatically when the file changes.

Child transforms

Prefab children are stored with transforms relative to the prefab.

When the prefab is moved, rotated, or scaled, the child objects are updated.

The default behavior:

child final transform = prefab transform x stored child transform
child final scale = stored child scale x prefab scale

This allows the whole prefab to be moved as one object.

useGlobalTranslation

The useGlobalTranslation option changes how child transforms are applied.

When enabled, the prefab can use a groupPosition data field from the child group and apply child transforms more globally rather than purely relative to the prefab transform.

This is mainly a compatibility/special-case option. Most prefabs should leave it disabled.

Automatic file reload

When a prefab is loaded, the engine can track the prefab file for changes. If the file changes, the prefab reloads:

1. Existing children are removed
2. The prefab file is loaded again
3. New children are created
4. Transforms are reapplied

This helps when editing prefab files externally.

noAutoReload on the root SimGroup disables this behavior.

Recursive prefab protection

The engine prevents infinite recursion when loading prefabs.

For example, this is invalid:

Prefab A loads Prefab B
Prefab B loads Prefab A

If a prefab file is already in the active prefab loading stack, loading is stopped and an error is logged.

Legacy .prefab files

Legacy .prefab files are TorqueScript-based.

They are loaded by executing the file:

exec("path/to/file.prefab");

The file must create a SimGroup and assign it to $ThisPrefab.

Example:

$ThisPrefab = new SimGroup(GaragePrefabGroup) {
   new TSStatic(garage_building) {
      shapeName = "/levels/example/art/shapes/garage.dae";
      position = "0 0 0";
      rotationMatrix = "1 0 0 0 1 0 0 0 1";
      scale = "1 1 1";
   };
};

If $ThisPrefab is not set or does not point to a valid SimGroup, the prefab fails to load.

JSON prefabs and vehicles

When loading JSON prefabs, the engine performs special handling for BeamNGVehicle objects.

If a vehicle object specifies a jBeam/jbeam but does not specify partConfig, the engine attempts to load the vehicle’s info.json and use the default part configuration.

It may also fill in missing default paint data:

• color
• metallicPaintData

Example:

{
  "class": "BeamNGVehicle",
  "name": "display_vehicle",
  "jBeam": "vivace",
  "position": [0,0,0],
  "rotationMatrix": [1,0,0,0,1,0,0,0,1],
  "scale": [1,1,1]
}

If the vehicle has a valid default configuration, missing fields may be completed automatically during load.

Valid and invalid prefab children

Not all objects are valid inside prefabs.

Valid objects are generally normal scene objects, static shapes, lights, groups, and similar placeable content.

Invalid or discouraged objects

The engine rejects or warns about several object types:

SimPath is explicitly allowed.

Exploding a prefab

A prefab can be “exploded” or unpacked into normal scene objects.

When exploded:

• The child group is moved into the mission/group hierarchy
• Child transforms are applied
• The objects are no longer controlled by the prefab
• Metadata is added to the resulting group

The resulting group may receive fields such as:

This allows tools to know that the group came from a prefab.

Converting to PrefabV2

The engine includes support for converting older prefabs to a newer prefab representation (PrefabV2).

The conversion process roughly:

1. Loads/explodes the old prefab
2. Collects object IDs
3. Packs them into a PrefabV2
4. Saves the result back to the prefab file

This is mostly handled by tools and editor workflows.

Saving prefabs

When saving a legacy prefab, the prefab saves its child SimGroup to the target file.

Legacy saving commonly uses a prefix such as:

$ThisPrefab =

This ensures that loading the .prefab file can recover the created root group.

For JSON workflows, prefer editor tools that serialize objects in the expected JSON format.

Loading process

When a Prefab object is added to the scene:

1. The prefab object is created.
2. If loadMode is Automatic, load() is called.
3. The engine checks the filename.
4. If the filename contains .json, JSON prefab loading is used.
5. Otherwise, legacy TorqueScript prefab loading is used.
6. A root SimGroup is found.
7. Child objects are registered and linked to the prefab.
8. Child transforms are updated relative to the prefab.
9. The prefab bounds are updated from child object bounds.
10. File change tracking is enabled unless disabled.

Minimal examples

JSON prefab object in level

{
  "class": "Prefab",
  "name": "garage_prefab",
  "filename": "/levels/example/prefabs/garage.json",
  "loadMode": "Automatic",
  "position": [100, 200, 0],
  "rotationMatrix": [1,0,0,0,1,0,0,0,1],
  "scale": [1,1,1]
}

JSON prefab file

{"class":"SimGroup","name":"garage_group"}
{"class":"TSStatic","name":"garage_building","shapeName":"/levels/example/art/shapes/garage.dae","position":[0,0,0],"rotationMatrix":[1,0,0,0,1,0,0,0,1],"scale":[1,1,1]}
{"class":"PointLight","name":"garage_light","position":[0,2,3],"rotationMatrix":[1,0,0,0,1,0,0,0,1],"scale":[1,1,1],"intensity":800}

Legacy .prefab

$ThisPrefab = new SimGroup(GaragePrefabGroup) {
   new TSStatic(garage_building) {
      shapeName = "/levels/example/art/shapes/garage.dae";
      position = "0 0 0";
      rotationMatrix = "1 0 0 0 1 0 0 0 1";
      scale = "1 1 1";
   };
};

Best practices

• Prefer JSON prefabs for new content.
• Always include a root SimGroup.
• Avoid circular prefab references.
• Keep prefabs self-contained and reusable.
• Do not include level-global objects such as TerrainBlock, LevelInfo, or TimeOfDay.
• Use relative child transforms so the prefab can be moved easily.
• Use Automatic load mode for normal level content.
• Use Manual only when a tool or script controls loading.
• Avoid placing very large/global systems in prefabs.
• Use clear names for prefab files and root groups.

Common issues

Prefab does not load

Possible causes:

• Invalid filename
• File does not exist
• JSON parse error
• Missing root SimGroup
• Legacy .prefab does not set $ThisPrefab

Prefab loads recursively

A prefab references itself directly or indirectly. Remove the circular reference.

Child objects are in the wrong position

Possible causes:

• Incorrect prefab transform
• Incorrect child transform
• Unexpected useGlobalTranslation
• Incorrect groupPosition data field

Prefab reloads unexpectedly

The file is being tracked for changes. Use noAutoReload on the root SimGroup if automatic reload should be disabled.

Object cannot be added to prefab

The object may be invalid for prefabs, such as TerrainBlock, LevelInfo, TimeOfDay, Player, or a global-bounds object.

Summary

Prefabs are reusable object groups stored outside the main level file.

Modern JSON prefabs contain a root SimGroup and one or more child objects. The Prefab scene object loads the file, manages child transforms, updates children when moved, and can reload when the file changes.

Legacy .prefab files are still supported, but new content should use JSON prefab workflows where possible.