Actors

An actor file defines one kind of game object, such as the player ship or an enemy: its sprite, health, collision size and default spawn position. You register each actor in the asset registry and place it in scenes by name.

The engine reads the fields on this page. Add your own fields (weapons, AI, inventory) to the same file and read them in your code.

Example

name: PlayerShip
role: player
preview:
  model: PlayerShipProxy
sprite:
  image: player_ship
  animation: player_ship_flight
  material: player_ship_material
  size: [100, 100]
  pivot: [50, 50]
  rotation_degrees: 90
  layer: -1
  preview_clip: 1
physics:
  health: 100
  radius: 40
spawn:
  position: [100, 0]

# Your own fields; the engine ignores them
weapons:
  - art: laser-cannon

Fields

Field	Type	Default	Description
format	map	none	Optional file format version; see File format versions.
name	string	—	Required. Actor name; must match its registry entry. Up to 127 characters.
role	string	—	Required. Free-form label such as player or enemy. Shown in Studio; your game decides what it means.
sprite.image	string	—	Required. Image asset name.
sprite.animation	string	none	Animation asset name.
sprite.material	string	none	Material asset name.
sprite.size	[w, h]	—	Required. Sprite size in world units.
sprite.pivot	[x, y]	center	Point the sprite rotates around, in sprite units.
sprite.rotation_degrees	number	0	Rotates the artwork, for example 90 if it faces up but the actor faces right.
sprite.layer	number	0	Draw order.
sprite.preview_clip	integer	0	Animation clip Studio shows.
physics.health	number	—	Required. Starting health; greater than 0.
physics.radius	number	—	Required. Collision radius; greater than 0.
spawn.position	[x, y] or [x, y, z]	none	Default position. A scene entity's position overrides it.
preview.model	string	none	A procedural model Studio draws for this actor.

Vectors are written as in scenes; see Scene: Vectors. Asset names aren't checked when the actor loads; a wrong name shows up when the asset is used.

Using actors in BT

• worldSceneActors() lists the actors placed in the scene, with each one's name and position (scene position, else spawn.position, else the origin).
• yaml_decode_asset("PlayerShip", target) decodes the actor file, including your own fields, into a BT object. See Reading assets from BT.

Errors

Errors stop the game at startup and look like actor '<path>': <message>.

Message	Cause
actor file: `version: 1` is no longer used	Delete the version line (an older file).
actor file uses format version X; this cTurtle reads format …	The file was written for a newer cTurtle; see File format versions.
could not parse actor YAML	Unsupported YAML, or a key path longer than 127 characters.
actor requires a non-empty name	Missing or too-long name.
actor 'X' requires a non-empty role	Missing role.
actor 'X' requires sprite.image	Missing sprite.image.
actor 'X' requires positive sprite.size	Missing or invalid size.
actor 'X' has invalid sprite.pivot (or rotation_degrees, layer, preview_clip, spawn.position)	Malformed value.
actor 'X' requires positive physics.health / physics.radius	Missing or not greater than 0.
actor asset 'X' contains actor named 'Y'	Registry name and name differ.

See also

• Asset registry
• Scene
• Procedural models