Prefab

Prefab is a scene object that places and loads a reusable group of objects from a prefab file.

The Prefab object stores the placement transform and the file reference. The prefab file stores the child objects.

For the prefab file layout, see the Prefab format documentation.

Basic example

A simple Prefab entry in items.level.json:

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

Important fields

filename

filename points to the prefab file:

"filename": "/levels/example/art/prefabs/gas_station.prefab.json"

Modern prefab files usually use:

*.prefab.json

Older content may use:

*.prefab

loadMode

Supported values:

Most level content should use:

"loadMode": "Automatic"

Transform behavior

The Prefab transform is applied to the child objects loaded from the prefab file.

This lets a reusable object group be placed multiple times with different position, rotation, or scale.

For most content, keep:

"useGlobalTranslation": false

Use useGlobalTranslation only when matching existing content or a tool-specific workflow that expects it.

Relationship with prefab files

The class and the file format have different responsibilities:

Do not duplicate all child objects in the level item file if they are meant to live inside the prefab file.

Tool notes

For tools that create or modify prefabs:

• Preserve filename paths and keep them portable.
• Preserve the Prefab transform separately from child object transforms.
• Use Prefab for reusable object groups, not for single static meshes.
• Use TSStatic or Forest for individual or repeated mesh placement where prefab grouping is not needed.
• Keep prefab file structure documented in the prefab format page.

Common issues

• Prefab does not appear because filename is wrong or missing.
• Prefab loads at the wrong location because child transforms and prefab transform were both baked.
• Multiple prefab instances conflict because child object names are not handled correctly by the prefab workflow.
• Manual loadMode is used but no script/tool loads the prefab.

Validation criteria

• filename points to an existing prefab file.
• loadMode is intentional.
• Child objects appear in the expected world position.
• Moving or rotating the Prefab object moves children as expected.
• The prefab file itself validates against the prefab format rules.

See also: TSStatic , SimGroup .