Stage config spec v0.6.0 ======================== .. contents:: :local: 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 | No | "" | | | | | | | | | | See the :ref:`worlds` page for a list of background map names | | | +---------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------+--------+-----------+ | timer\_seconds | Int32, Null | The number of seconds the player has to complete the stage | No | 60 | | | | | | | | | | If null, stage time is unlimited and no time bonus points will be awarded (|since_stage_config_v0_5_0|). | | | | | | | | | | | | |since_stage_config_v0_2_0| | | | +---------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------+--------+-----------+ | bonus | Boolean | Whether this stage is a bonus stage | No | false | | | | | | | | | | |since_stage_config_v0_5_0| | | | +---------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------+--------+-----------+ | model\_files | Array[`File Object`_] | A list of model files to load in, that can contain multiple meshes that can be placed arbitrarily | No | [] | | | | | | | | | | 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 | | | +---------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------+--------+-----------+ | texture\_files | Array[`File Object`_] | A list of texture files to load in, that can be referenced in materials | No | [] | | | | | | | | | | 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 | | | +---------------------------+---------------------------------------+-------------------------------------------------------------------------------------------------------------+--------+-----------+ | 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 :ref:`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... .. code:: json { "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". .. _stage_file_object: 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 | No | {} | | | | | | | | | | The type of this object will vary depending on the ``type`` field. Examples include `Mesh node data Object`_, `Switch node data Object`_, etc. | | | +--------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+--------+-----------+ | 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} | +------------+-------------------+------------------------+--------+--------------------------------------------+ .. _stage_scene_node_data: 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. .. _stage_mesh_node_data: 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 | No | {"x": 0.0, "y": 0.0, "z": 0.0} | | | | | | | | | | |changed_stage_config_v0_3_0|: Renamed ``conveyor_velocity`` to ``conveyor_local_velocity`` | | | +-----------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------+--------+----------------------------------+ | 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. | No | {"x": 0.0, "y": 0.0} | | | | | | | | | | |since_stage_config_v0_3_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 | No | false | | | | | | | | | | On entering a fallout volume, the player will fail the level for falling out of the stage | | | +-----------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------+--------+----------------------------------+ | goal\_volume | Boolean | Whether this mesh acts as a goal volume | No | false | | | | | | | | | | On entering a goal volume, the player will complete the stage | | | | | | | | | | | | |since_stage_config_v0_6_0| | | | +-----------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------+--------+----------------------------------+ | warp\_distance | Int32 | How many stages forward the goal should take you in a course, if this mesh is a goal volume. | No | 1 | | | | | | | | | | |since_stage_config_v0_6_0| | | | +-----------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------+--------+----------------------------------+ | gravity\_volume | Boolean | Whether this mesh acts as a gravity volume | No | false | | | | | | | | | | On entering a gravity volume, the player's dravity direction will be changed permanently to ``gravity_dir`` | | false | | | | | | | | | | |since_stage_config_v0_6_0| | | | +-----------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------+--------+----------------------------------+ | gravity\_dir | `Vector3 Object`_ | The direction of gravity to set, if this mesh is a gravity volume. | No | {"x": 0.0, "y": 0.0, "z": -1.0} | | | | | | | | | | |since_stage_config_v0_6_0| | | | +-----------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------+--------+----------------------------------+ | trigger\_volume | Boolean | Whether this mesh acts as a trigger volume, even if ``wind_volume`` and ``fallout_volume`` are unset. | No | false | | | | | | | | | | This can be used in conjunction with ``activate_touch_platform_groups`` to activate animations when entering a trigger volume. | | | | | | | | | | | | |since_stage_config_v0_5_0| | | | +-----------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------+--------+----------------------------------+ | 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 | No | [] | | | | | | | | | | |since_stage_config_v0_3_0| | | | +-----------------------------------+-----------------------------+--------------------------------------------------------------------------------------------------------------------------------+--------+----------------------------------+ - ``touches_enabled``: |removed_stage_config_v0_3_0| Axis String ----------- A string that can contain any of the following values - "none" |deprecated_stage_config_v0_4_0| - 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 | | +----------------------+----------------------+---------------------------------------------------------+--------+-----------+ .. _stage_goal_node_data: 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 | +------------------+--------------+-----------------------------------------------------------------+--------+-----------+ .. _stage_wormhole_node_data: 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 | +------------------------+----------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+--------+-----------+ .. _stage_switch_node_data: 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 | No | [] | | | | | | | | | | |deprecated_stage_config_v0_2_0|: Ideally switches should be linked to animations, not to other scene nodes | | | +----------------------+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------+--------+-----------+ | button\_visual | `Button Visual String`_ | Visual button to show in-game | No | "" | +----------------------+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------+--------+-----------+ Button Visual String -------------------- One of: - "pause" - "forward" - "backward" - "fast\_forward" - "fast\_backward" .. _stage_collectable_node_data: 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 | +----------+--------------+------------------------------------------------------------------------+--------+-----------+ .. _stage_bumper_node_data: 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. .. _stage_animation: 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 | | +---------------+--------------+----------------------------------------------------------------------------------------------------------------------------------+--------+-----------+ .. _stage_data_path: Data path String ---------------- - A string representing a property of an object - Eg: "transform.position.x" See :ref:`the scene node properties ` for some example valid data paths for scene nodes, or look at :ref:`the base material reference ` for the material parameters. .. _stage_float_animation_channel: 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 | | +-------+--------------+---------------+--------+-----------+ .. _stage_float_curve: 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 | | +------------------+------------------------------+-----------------------------------------------------------------------+--------+-----------+ .. _stage_interpolation: 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 | Yes | | | | | | | | | | | |since_stage_config_v0_3_0| | | | +------------------+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+--------+-----------+ | animations | Array[`Identifier String`_] | Array of animation names which should be set to the ``playback_speed`` when the touch platform is activated | No | [] | | | | | | | | | | |since_stage_config_v0_3_0| | | | +------------------+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+--------+-----------+ | playback\_speed | Float | The playback speed animations should be set to when activated | No | 1.0 | | | | | | | | | | |since_stage_config_v0_3_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``. | No | false | | | | | | | | | | |since_stage_config_v0_3_0| | | | +------------------+-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------+--------+-----------+ - ``playback_type``: |removed_stage_config_v0_3_0| - ``nodes``: |removed_stage_config_v0_3_0| .. _stage_material: 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 | Yes | | | | | | | | | | | See the :ref:`base_materials` page for a list of base materials | | | +---------------------------+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------+--------+-----------+ | parameter\_overrides | Object[String, `Material parameter override Object`_] | The parameters this material customizes from the base material | No | {} | | | | | | | | | | See the :ref:`base_materials` page for a list overridable parameters for each base material | | | +---------------------------+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------+--------+-----------+ | animations | Array[`Identifier String`_] | A list of :ref:`animation ` names that can be applied to material | No | [] | | | | | | | | | | |since_stage_config_v0_3_0| | | | +---------------------------+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------+--------+-----------+ 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 | Yes | | | | | | | | | | | ``texture2d`` parameters will use the identifying name of a texture here. | | | +---------------------------+-------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------+--------+-----------+ 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 :ref:`the name of the texture ` defined in ``/texture_files``