Procedural models (`models.yaml`)

models.yaml defines simple 3D models built from boxes, with material slots and box colliders. Studio uses them to preview actors (preview.model), in the Model viewer and in the Model Animation editor. The game engine doesn't load them automatically; your BT code can read the file to build its own meshes, as the starter FPS sample does.

Example

models:
  - name: gun
    material_slots:
      - name: body
        material: fps.blue
      - name: barrel
        material: fps.metal
    primitives:
      - name: body
        shape: box
        material_slot: body
        position: [0.0, 0.0, 0.0]
        scale: [0.28, 0.30, 0.72]
      - name: barrel
        shape: box
        material_slot: barrel
        parent: body
        position: [0.0, 0.01, -0.6]
        scale: [0.14, 0.14, 0.58]
    colliders:
      - name: hitbox
        shape: box
        position: [0.0, -0.2, -0.26]
        size: [0.27, 0.77, 1.38]

Fields

Field	Type	Default	Description
`format`	map	none	Optional file format version; see File format versions.
`models`	list	empty	Your models.

models[]

Field	Type	Default	Description
`name`	string	`Model N`	Name used by actors (`preview.model`), rigs and motion clips. Must be unique.
`material_slots`	list	empty	Named materials the parts use.
`primitives`	list	empty	The visible parts.
`colliders`	list	empty	Collision boxes.

material_slots[]

Field	Type	Default	Description
`name`	string	`Slot N`	Slot name, unique within the model.
`material`	string	—	Required. Material asset name.

primitives[]

Field	Type	Default	Description
`name`	string	`Part N`	Part name, unique within the model. Motion clips animate parts by this name.
`shape`	string	`box`	Only `box` is supported; other shapes are skipped with a warning.
`parent`	string	none	Another part. This part then moves with it, and its transform is relative to the parent.
`material_slot`	string	none	Slot from `material_slots`.
`palette`	integer	`0`	Preview color (0–5) Studio uses when the part has no material.
`position`	`[x, y, z]`	`[0, 0, 0]`	Position.
`rotation`	`[x, y, z]`	`[0, 0, 0]`	Rotation in radians.
`scale`	`[x, y, z]`	`[1, 1, 1]`	Box size.

colliders[]

Field	Type	Default	Description
`name`	string	`Collider N`	Name, unique within the model.
`shape`	string	`box`	`box`.
`parent`	string	none	A part the collider follows.
`position`	`[x, y, z]`	`[0, 0, 0]`	Center.
`rotation`	`[x, y, z]`	`[0, 0, 0]`	Rotation in radians.
`size`	`[x, y, z]`	`[1, 1, 1]`	Box size.

Write vectors as one-line lists ([x, y, z]) so Studio can edit them. Studio's edits keep your comments, ordering and extra keys.

Errors

Studio shows these in the model view or in Problems:

Message	Cause
models.yaml: `version: 1` is no longer used	Delete the `version` line (an older file).
`models.yaml uses format version X; this cTurtle reads format …`	The file was written for a newer cTurtle; see File format versions.
`Duplicate part name: X`	Two parts share a name, or a part has no name.
`Missing parent part: X`, `Missing collider parent: X`	`parent` names a part that doesn't exist.
Parent cycle or more than 128 levels	Parts are parented in a loop or too deep.
Duplicate model, slot or collider names	Make names unique.
Missing material	A slot names a material that isn't registered.
Missing material slot	A part names a slot that doesn't exist.

Example​

Fields​

models[]​

material_slots[]​

primitives[]​

colliders[]​

Errors​

See also​