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 (new_16 Introduced in stage config v0.5.0 (Rolled Out! v0.6.0)).

new_16 Introduced in stage config v0.2.0 (Rolled Out! v0.4.5.5)

No

60

bonus

Boolean

Whether this stage is a bonus stage

new_16 Introduced in stage config v0.5.0 (Rolled Out! v0.6.0)

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?

Default

x

Float

X scalar

Yes

y

Float

Y scalar

Yes

z

Float

Z scalar

Yes

Quat Object

Key

Value type

Description

Req?

Default

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

edit_16 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.

new_16 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

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.

new_16 Introduced in stage config v0.5.0 (Rolled Out! v0.6.0)

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

new_16 Introduced in stage config v0.3.0 (Rolled Out! v0.5.0)

No

[]

  • touches_enabled: del_16 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” warning_16 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

warning_16 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?

Default

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?

Default

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

new_16 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

new_16 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

new_16 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.

new_16 Introduced in stage config v0.3.0 (Rolled Out! v0.5.0)

No

false

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

  • nodes: del_16 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

new_16 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