Stage config spec v0.6.0¶

Description ¶

Stage configs are JSON files that describe the objects, animations, metadata, materials, and other information about a stage. A config may be placed anywhere within the game stages directory (including in nested subdirectories), but must be named config.json.

Root Object ¶

Key	Value type	Description	Req?	Default
config_version	SemVer String	The config format version that this file adheres to	Yes
metadata	Metadata Object	Data that can be indexed/searched for about the stage, and to uniquely identify the stage	Yes
background_map	String	The name of the background map to load in while playing the stage See the Worlds page for a list of background map names	No	“”
timer_seconds	Int32, Null	The number of seconds the player has to complete the stage If null, stage time is unlimited and no time bonus points will be awarded ( Introduced in stage config v0.5.0 (Rolled Out! v0.5.6)). Introduced in stage config v0.2.0 (Rolled Out! v0.4.5.5)	No	60
bonus	Boolean	Whether this stage is a bonus stage Introduced in stage config v0.5.0 (Rolled Out! v0.5.6)	No	false
model_files	Array[File Object]	A list of model files to load in, that can contain multiple meshes that can be placed arbitrarily Model files must live within the game’s stages directory, otherwise the game will refuse to load it The only supported model format is .obj	No	[]
texture_files	Array[File Object]	A list of texture files to load in, that can be referenced in materials Texture files must live within the game’s stages directory, otherwise the game will refuse to load it Supported texture extensions are .png, .jpg, .jpeg, and .bmp	No	[]
spawns	Array[Spawn Object]	A list of spawn points, to place player balls on game start - must have at least one element	Yes
scene_graph	Array[Scene node Object]	A list of child scene nodes for the root of the scene graph	Yes
animations	Array[Identifier String]	A list of animation names that can be applied to nodes in the scene graph	No	[]
float_curves	Array[Float curve Object]	A list of floating point curves that can be used in animations, or accessed in scripts	No	[]
quaternion_curves	Array[Quat curve Object]	A list of quaternion curves that can be used in animations, or accessed in scripts	No	[]
materials	Array[Material Object]	A list of materials that can be applied to mesh actors	No	[]
touch_platform_groups	Array[Touch platform group Object]	A list of touch platform groups; each group a list of animations that can be activated when touching meshes	No	[]

SemVer String ¶

A SemVer (Semantic Version) string is a string that follows the format Major.Minor.Patch.

“1.2.7” is an example of a string that would match the pattern.
Additional labels to the format (Such as “1.2.7-beta3”) are not supported and will result in a parsing error.

Metadata Object ¶

Key	Value type	Description	Req?	Default
uuid	UUID String	The unique identifier for this stage	Yes
name	Translatable string Object	The stage name	Yes
description	Translatable string Object	The stage description	No	No description provided
creator_uuid	UUID String	The user UUID of the stage owner	Yes
difficulty	Int32	The stage difficulty, as judged by the creator	Yes
tags	Array[Tag String]	A list of tags for this stage	No	[]

UUID String ¶

A UUID string is a string representing a UUID (Universally Unique Identifier).

UUID version 4 should be preferred.
UUIDs must be formatted with hyphens between characters, without surrounding brackets (Eg: “2cef261a-11fb-4d4d-acb9-a77115ab5ad5”).
- This is done for intercompatibility with other tools.
- Using a different UUID format that can be understood by the game will still result in a parsing error.

Translatable string Object ¶

A JSON object containing translatable text

An example of such an object would be…

{
  "fallback": "Colorful test stage",
  "en-GB": "Colourful test stage",
  "en-CA": "Colourful test stage",
  "en-AU": "Colourful test stage",
  "ja": "カラフルなテストレベル"
}

A “fallback” key must be given otherwise a parsing error will be given
- The fallback is used as the text for cultures that don’t have their own dedicated key/value pair.
Culture keys can consist of one or two parts, separated by a hyphen.
- A two-letter ISO 639-1 language code (such as “zh”).
- An optional two-letter ISO 3166-1 country code (such as “CN”).
In the case that multiple keys match the current locale, the most specific one will be favored.
- Eg: if both en and en-GB culture keys exist, and the active locale is en-GB, en-GB will be preferred over en.

Difficulty ¶

The difficulty integer will be interpreted as a fixed-point value, with one decimal place. It must be greater than or equal to 0.

As an example, a difficulty of 10 will be displayed as “1.0”, and 25 as “2.5”.

File Object ¶

Key	Value type	Description	Req?	Default
name	Identifier String	An identifier for the file	Yes
file_path	File path String	A path to the file	Yes

Identifier String ¶

A string used to uniquely identify an element in the config.

Must be all lowercase
Cannot be empty
Must be unique throughout all other identifiers in the config

File path String ¶

A string that can contain an absolute or relative path to a file

Paths starting with // are relative, otherwise paths are treated as absolute
Paths must use the forward slash / as the separator as opposed to the backslash \, even on Windows, otherwise a parse error will be given
Paths should be treated as case sensitive, even if the underlying filesystem is case-insensitive (This is such that custom levels authored on a case-insensitive filesystem still work on case-sensitive filesystems, as it common in the Linux world)
Absolute paths should be avoided for anything other than testing purposes

Tag String ¶

Tag strings must match the regex ^[a-z][a-z-]*[a-z]+$, otherwise a parsing error will be given
- Lowercase Latin chars or hyphens only
- A tag must be 2 chars or longer
- Tags may not start with a hyphen
- Tags may not end with a hyphen
- Tags may not consist only of hyphens
In addition (because screw figuring out regex), tags must not contain two or more consecutive hyphens
Words in tags should be separated by a hyphen

Spawn Object ¶

Key	Value type	Description	Req?	Default
name	Identifier String	An identifier for this spawn	Yes
transform_noscale	Transform without scale Object	The position and rotation the ball should be when spawned	Yes
gravity_vector	Vector3 Object	The direction of gravity when the ball is spawned	No	{“x”: 0.0, “y”: 0.0, “z”: -1.0}

Transform without scale Object ¶

Key	Value type	Description	Req?	Default
position	Vector3 Object	A point in the world	No	{“x”: 0.0, “y”: 0.0, “z”: 0.0}
rotation	Quat Object	A rotation	No	{“x”: 0.0, “y”: 0.0, “z”: 0.0, “w”: 0.0}

Vector3 Object ¶

Key	Value type	Description	Req?
x	Float	X scalar	Yes
y	Float	Y scalar	Yes
z	Float	Z scalar	Yes

Quat Object ¶

Key	Value type	Description	Req?
x	Float	X scalar	Yes
y	Float	Y scalar	Yes
z	Float	Z scalar	Yes
w	Float	W scalar	Yes

Scene node Object ¶

Key	Value type	Description	Req?	Default
name	Identifier String	The identifier for this node	Yes
type	Node type enum String	The type of this node	Yes
node_data	Typed node data Object	Additional data associated with the node of the specified type The type of this object will vary depending on the `type` field. Examples include Mesh node data Object, Switch node data Object, etc.	No	{}
transform	Transform Object	The transform of the node relative to its parent	No	{}
animations	Array[Identifier String]	A list of animation names to apply to this node	No	[]
children	Array[Scene node Object]	Nodes who will be parented to this node	No	[]

Node type enum String ¶

A string that can contain any of the following values

“scene_node”
“mesh_node”
“goal_node”
“bumper_node”
“collectable_node”
“wormhole_node”
“switch_node”

Transform Object ¶

Key	Value type	Description	Req?	Default
position	Vector3 Object	A translation	No	{“x”: 0.0, “y”: 0.0, “z”: 0.0}
rotation	Quat Object	A rotation	No	{“x”: 0.0, “y”: 0.0, “z”: 0.0, “w”: 0.0}
scale	Vector3 Object	A scale	No	{“x”: 0.0, “y”: 0.0, “z”: 0.0}

Scene node data Object ¶

A scene node does not have any additional data attached to it. node_data should be left empty for a plain scene node.

Mesh node data Object ¶

Key	Value type	Description	Req?	Default
mesh_reference	Mesh reference Object	The mesh to use for this node	Yes
gravity_surface	Boolean	Whether this mesh should affect a player’s gravity vector	No	false
ice_surface	Boolean	Whether this mesh acts as an ice surface	No	false
quicksand_surface	Boolean	Whether this mesh acts as a quicksand surface	No	false
gravity_line_trace_enabled	Boolean	If this node is a gravity surface, line traces to this node don’t affect gravity	No	true
seesaw_surface	Boolean	Whether this mesh acts as a seesaw	No	false
collision_enabled	Boolean	Whether the ball will collide with the mesh node	No	true
rotation_axis	Axis String	The axis the seesaw should rotate about in the seesaw’s local space	No	“y”
seesaw_sensitivity	Float	How strongly the seesaw should be affected by the ball touching it	No	0.0
seesaw_springiness	Float	How hard the spring tries to return to its original rotation	No	0.0
seesaw_friction	Float	How rapidly the seesaw slows itself down	No	0.0
spring	Boolean	Whether this mesh acts as a spring	No	false
spring_impulse	Vector3 Object	Velocity (in node-local space) applied to ball on contact	No	{“x”: 0.0, “y”: 0.0, “z”: 0.0}
conveyor	Boolean	Whether this mesh acts as a conveyor	No	false
conveyor_local_velocity	Vector3 Object	Simulated velocity of the mesh if it is a conveyor, relative to the object’s local coordinates Changed in stage config v0.3.0 (Rolled Out! v0.5.0): Renamed `conveyor_velocity` to `conveyor_local_velocity`	No	{“x”: 0.0, “y”: 0.0, “z”: 0.0}
conveyor_uv_velocity	Vector2 Object	Simulated velocity of the mesh if it is a conveyor, relative to the UV coordinates of where the player ball hit. Introduced in stage config v0.3.0 (Rolled Out! v0.5.0)	No	{“x”: 0.0, “y”: 0.0}
wind_volume	Boolean	Whether this mesh acts as a wind volume	No	false
wind_velocity	Vector3 Object	Velocity (in node-local space) of the wind of this is a wind volume	No	{“x”: 0.0, “y”: 0.0, “z”: 0.0}
sticky_surface	Boolean	Whether this mesh acts as a sticky floor	No	false
fallout_volume	Boolean	Whether this mesh acts as a fallout volume On entering a fallout volume, the player will fail the level for falling out of the stage	No	false
goal_volume	Boolean	Whether this mesh acts as a goal volume On entering a goal volume, the player will complete the stage Introduced in stage config v0.6.0 (Rolled Out! v0.5.7)	No	false
warp_distance	Int32	How many stages forward the goal should take you in a course, if this mesh is a goal volume. Introduced in stage config v0.6.0 (Rolled Out! v0.5.7)	No	1
gravity_volume	Boolean	Whether this mesh acts as a gravity volume On entering a gravity volume, the player’s dravity direction will be changed permanently to `gravity_dir` Introduced in stage config v0.6.0 (Rolled Out! v0.5.7)	No	false false
gravity_dir	Vector3 Object	The direction of gravity to set, if this mesh is a gravity volume. Introduced in stage config v0.6.0 (Rolled Out! v0.5.7)	No	{“x”: 0.0, “y”: 0.0, “z”: -1.0}
trigger_volume	Boolean	Whether this mesh acts as a trigger volume, even if `wind_volume` and `fallout_volume` are unset. This can be used in conjunction with `activate_touch_platform_groups` to activate animations when entering a trigger volume. Introduced in stage config v0.5.0 (Rolled Out! v0.5.6)	No	false
material_slots	Array[Identifier String]	A list of material names to apply to each material slot in the mesh	No	[]
activate_touch_platform_groups	Array[Identifier String]	A list of touch platform groups that should be triggered when the player ball touches this mesh Introduced in stage config v0.3.0 (Rolled Out! v0.5.0)	No	[]

touches_enabled: Removed since stage config v0.3.0 (Rolled Out! v0.5.0)

Axis String ¶

A string that can contain any of the following values

“none” Deprecated since stage config v0.4.0 (Rolled Out! v0.5.4.2) - The “none” axis works identically to the “y” axis
“x”
“y”
“z”

Mesh reference Object ¶

Key	Value type	Description	Req?	Default
mesh_file_name	Identifier String	The file identifier to pull the mesh from	Yes
mesh_object_name	String	The name of the object in the file to use as the mesh	Yes

Goal node data Object ¶

Key	Value type	Description	Req?	Default
warp_distance	Int32	How many stages forward the goal should take you in a course.	No	1

Wormhole node data Object ¶

Key	Value type	Description	Req?	Default
link	Identifier String	Name of node to teleport the ball to when entering this wormhole. Need not be a wormhole node	Yes
gravity_align_self	Boolean	Whether to align the ball’s gravity to the local down direction of this wormhole upon exit	No	false
gravity_align_link	Boolean	Whether to align the ball’s gravity to the linked node’s local down direction upon entry. Useful for when the linked node is not a wormhole	No	false

Switch node data Object ¶

Key	Value type	Description	Req?	Default
initially_pressed	Boolean	Whether the switch should be initially pressed when the stage is loaded	No	false
playback_speed	Float	The playback speed to set the given link nodes to when the switch is pressed	No	0.0
link_nodes	Array[Identifier String]	List of node names to be affected by the switch when pressed. Unlike touch platform groups, nodes may be shared by multiple switches Deprecated since stage config v0.2.0 (Rolled Out! v0.4.5.5): Ideally switches should be linked to animations, not to other scene nodes	No	[]
button_visual	Button Visual String	Visual button to show in-game	No	“”

Button Visual String ¶

One of:

“pause”
“forward”
“backward”
“fast_forward”
“fast_backward”

Collectable node data Object ¶

Key	Value type	Description	Req?	Default
amount	Int32	How many collectables the pickup should give you (usually 1, 5, or 10)	No	1

Bumper node data Object ¶

A bumper node does not have any additional data attached to it. node_data should be left empty for a bumper node.

Animation Object ¶

Key	Value type	Description	Req?	Default
name	Identifier String	The unique name for this animation	Yes
float_channels	Object[Data path String, Float animation channel Object]	The properties to animated (with keys that refer to a float property on an object, such as `transform.position.x`)	No	{}
quaternion_channels	Object[Data path String, Quat animation channel Object]	The properties to animated (with keys that refer to a quat property on an object, such as `transform.rotation`)	No	{}
initial_time_scale	Float	The playback timescale of the animation when the stage begins (1.0 = play, 0.0 = pause, 2.0 = ff, -1.0 = rev)	No	1.0
loop_zone	Loop zone Object	If specified, the animation will start looping once it enters the zone	No	No loop

Loop zone Object ¶

Key	Value type	Description	Req?	Default
start_time	Float	The start of the animation loop zone (if playing backwards and we go past this point, the animation teleports to the end time)	No	0.0
end_time	Float	The end of the animation loop zone (if playing forwards and we go past this point, the animation teleports to the start time)	Yes

Data path String ¶

A string representing a property of an object
Eg: “transform.position.x”

See the scene node properties for some example valid data paths for scene nodes, or look at the base material reference for the material parameters.

Float animation channel Object ¶

Key	Value type	Description	Req?	Default
float_curve	Identifier String	The name of the float curve for this channel	Yes
transform_curves	Transform curve Object	Transforms to apply when evaluating the curve	No	{}

Quat animation channel Object ¶

Key	Value type	Description	Req?	Default
quaternion_curve	Identifier String	The name of the quat curve for this channel	Yes
transform_curves	Transform curve Object	Transforms to apply when evaluating the curve (Y axis transforms are ignored for quaternion animations)	No	{}

Transform curve Object ¶

Key	Value type	Description	Req?	Default
position	Vector2 Object	The time/value (x/y) offsets for the curve	No	{“x”: 0.0, “y”: 0.0}
scale	Vector2 Object	The time/value (x/y) scale for the curve	No	{“x”: 0.0, “y”: 0.0}

Vector2 Object ¶

Key	Value type	Description	Req?	Default
x	Float	X scalar	Yes
y	Float	Y scalar	Yes

Float curve Object ¶

Key	Value type	Description	Req?	Default
name	Identifier String	The unique name for this curve	Yes
keyframes	Array[Float keyframe Object]	The keyframes on this curve	Yes

Float keyframe Object ¶

Key	Value type	Description	Req?
interpolation	Interpolation Object	The interpolation options to use between this keyframe and the next	Yes
left_handle	Handle Object	The position and type of the left handle for this keyframe	Yes
control_point	Float control point Object	The position of this keyframe	Yes
right_handle	Handle Object	The position and type of the right handle for this keyframe	Yes

Quat curve Object ¶

Key	Value type	Description	Req?	Default
name	Identifier String	The unique name for this curve	Yes
keyframes	Array[Quat keyframe Object]	The keyframes on this curve	Yes

Quat keyframe Object ¶

Key	Value type	Description	Req?
interpolation	Interpolation Object	The interpolation options to use between this keyframe and the next	Yes
left_handle	Handle Object	The position and type of the left handle for this keyframe	Yes
control_point	Quat control point Object	The position of this keyframe	Yes
right_handle	Handle Object	The position and type of the right handle for this keyframe	Yes

Interpolation Object ¶

Key	Value type	Description	Req?	Default
type	Interpolation type String	What method should be used to calculate points between this keyframe and the next	Yes

Interpolation type String ¶

A string that can contain any of the following values

“cubic_bezier”
“linear”
“constant”

Handle Object ¶

Key	Value type	Description	Req?	Default
position	Vector2 Object	The position of this handle	Yes
type	Handle type String	The type of this handle	Yes

Handle type String ¶

A string that can contain any of the following values

“auto_clamped”
“free”
“vector”

The handle type does not affect how the stage plays out - it’s only for the in-game editor.

Float control point Object ¶

Key	Value type	Description	Req?	Default
position	Vector2 Object	The position of this control point	Yes

Quat control point Object ¶

Key	Value type	Description	Req?	Default
position	Quat at time Object	The position of this control point	Yes

Quat at time Object ¶

Key	Value type	Description	Req?	Default
x	Float	The time of the keyframe	Yes
y	Quat Object	The keyframe rotation	Yes

Touch platform group Object ¶

Key	Value type	Description	Req?	Default
name	Identifier String	The identifier for this touch platform group Introduced in stage config v0.3.0 (Rolled Out! v0.5.0)	Yes
animations	Array[Identifier String]	Array of animation names which should be set to the `playback_speed` when the touch platform is activated Introduced in stage config v0.3.0 (Rolled Out! v0.5.0)	No	[]
playback_speed	Float	The playback speed animations should be set to when activated Introduced in stage config v0.3.0 (Rolled Out! v0.5.0)	No	1.0
ping_pong	Boolean	For non-looping animations, `ping_pong` will make activations of the touch platform group toggle between positive and negative the `playback_speed`. Introduced in stage config v0.3.0 (Rolled Out! v0.5.0)	No	false

playback_type: Removed since stage config v0.3.0 (Rolled Out! v0.5.0)
nodes: Removed since stage config v0.3.0 (Rolled Out! v0.5.0)

Material Object ¶

Key	Value type	Description	Req?	Default
name	Identifier String	The identifier for this material	Yes
base_material	String	Which base material to use as a starting point for this material See the Base materials page for a list of base materials	Yes
parameter_overrides	Object[String, Material parameter override Object]	The parameters this material customizes from the base material See the Base materials page for a list overridable parameters for each base material	No	{}
animations	Array[Identifier String]	A list of animation names that can be applied to material Introduced in stage config v0.3.0 (Rolled Out! v0.5.0)	No	[]

Material parameter override Object ¶

Key

Value type

Description

Req?

Default

type

Material parameter type String

The type of the parameter we’re overriding

Yes

value

Float or Vector2 Object or Vector3 Object or Identifier String

The value to override with, the type of which specified by the type field

texture2d parameters will use the identifying name of a texture here.

Yes

Material parameter type String ¶

A string that can contain any of the following values

“scalar”: Represents a number
“vector2”: Represents a Vector2 Object
“vector3”: Represents a Vector3 Object
“texture2d”: Represents an Identifier String containing the name of the texture defined in /texture_files