Course config spec v0.2.0 ========================= .. contents:: :local: Description ----------- Course configs are JSON files that describe the metadata and stage list for an arcade course. The config may be placed anywhere within the game courses directory (including in nested subdirectories), but must be named ``course.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 course, and to uniquely identify the course | Yes | | +----------------------+-----------------------------------------------------+---------------------------------------------------------------------------------------------+--------+-----------+ | stages | Array[`Stage String`_] | A list of stages the course has | Yes | | +----------------------+-----------------------------------------------------+---------------------------------------------------------------------------------------------+--------+-----------+ | stage\_random\_pools | Object[`Identifier String`_, `Random pool Object`_] | A list of random pools the course has, which may be referneced in the stages list | 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 course | Yes | | +-----------------+-------------------------------+--------------------------------------------------+--------+---------------------------+ | name | `Translatable string Object`_ | The course name | Yes | | +-----------------+-------------------------------+--------------------------------------------------+--------+---------------------------+ | description | `Translatable string Object`_ | The course description | No | No description provided | +-----------------+-------------------------------+--------------------------------------------------+--------+---------------------------+ | creator\_uuid | `UUID String`_ | The user UUID of the course owner | Yes | | +-----------------+-------------------------------+--------------------------------------------------+--------+---------------------------+ | difficulty | Int32 | The course difficulty, as judged by the creator | Yes | | +-----------------+-------------------------------+--------------------------------------------------+--------+---------------------------+ | tags | Array[`Tag String`_] | A list of tags for this course | No | [] | +-----------------+-------------------------------+--------------------------------------------------+--------+---------------------------+ Stage String ------------ A stage string is either a `UUID String`_ or a `Random pool String`_. 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. Random pool String ------------------ A random pool string is ``randompool:pool_name``, where ``pool_name`` is the name of a random pool. 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 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". 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 Random pool Object ------------------ +--------+------------------------------------+-----------------------------------+------+---------+ | Key | Value type | Description | Req? | Default | +========+====================================+===================================+======+=========+ | stages | Array[`Random pool stage Object`_] | List of stages in the random pool | Yes | | +--------+------------------------------------+-----------------------------------+------+---------+ Random pool stage Object ------------------------ +--------+----------------+-----------------------------------------------------------+--------+---------+ | Key | Value type | Description | Req? | Default | +========+================+===========================================================+========+=========+ | uuid | `UUID String`_ | The stage UUID | Yes | | +--------+----------------+-----------------------------------------------------------+--------+---------+ | weight | Int32 | How likely this stage is to be drawn from the random pool | No | 1 | +--------+----------------+-----------------------------------------------------------+--------+---------+