Skip to content

Home

Jump to bottom
Erik Roberts edited this page Aug 31, 2025 · 1 revision

JSON Schema Documentation

The games schema defines a structure for managing servers and their list of games that appear in Quickplay menus. Each game can have different actions and conditions tied to it. Folder hierarchies for the games list are supported.

Table of Contents

Root Object

Type: object
Additional properties: not allowed

Properties

  • $schema — string (optional)
    A URL referencing this schema definition.

  • servers — array of Server (optional)
    A list of Minecraft servers for which a list of games is available.

  • conditions — object (optional)
    A map of named conditions for reuse.

    • Each key is an identifier (e.g., "isRanked").
    • Each value is an object that must include:

Definitions

Server

Represents a Minecraft server which players connect to in their Minecraft client. Each Server has a regular expression which is checked against the server address the client connected to, and a list of games to display if the regular expression matches.

Type: object
Required: addressRegex, games, enabled
Additional properties: not allowed

Properties

  • addressRegex — string
    Regular expression that matches the server address that a client is connecting to.

  • games — array of Folder
    Top level of the games list.

  • enabled — boolean
    Whether this Minecraft server configuration is available. When false, it should not be displayed to or usable by users of the client.

Folder

A container for a Sequence of Actions the client takes when clicked/activated, or a list of other Folders to display when clicked/activated.

Type: object
Required: name, children, identifier
Additional properties: not allowed

Properties

  • if — ConditionStatement, optional
    Gate for showing/using this folder.

  • elseMessage — string, optional
    A custom message to display if this Folder is activated (e.g. by keybind) when it is not available. Otherwise, a generic error message will be displayed saying that the action is not currently available.

  • name — string
    English display name of the Folder.

  • identifier — string
    Internal, unique identifier for the Folder. Never re-use identifiers, as clients can apply their own settings and customizations upon them.

  • image — string, optional
    URL to an image to display for this Folder. The image should have a 1:1 aspect ratio.

  • children — array (required)
    Either:

    • An array of child Folders, or
    • A Sequence

Sequence

An ordered series of actions the client should take when activated.

Type: object
Required: steps
Additional properties: not allowed

Properties

  • steps — array of step objects
    Each step:
    • if — ConditionStatement, optional
      If present, controls whether the action runs.
    • action — Action, required
      Primary operation to perform.
    • else — Action, optional
      Fallback operation when if evaluates to false.

Condition

A comparison statement which can be evaluated to true or false. These can then be used within CompoundConditions or ConditionStatements, which are ultimately used in the if-then-else statements of Sequences and/or Folders. Conditions can compare a set of pre-defined properties recognized by the client. They currently are all values only available the Hypixel Network. Conditions can be formed in an invalid, non-sensical manner (e.g. checking if the boolean isInParty contains the string "Hello"). If a condition is invalid or unavailable, the client will always evaluate it as true.

Type: object
Required: property, state, value
Additional properties: not allowed

Properties

  • property — enum
    One of:
    serverName, serverType, mode, map, lobbyName, proxyName, environment, isInParty, partyRole, playerRank, packageRank, monthlyPackageRank

  • state — enum
    One of: ==, >, >=, <, <=, !=, contains, notContains

  • value — string | number | boolean
    The value to compare against.

CompoundCondition

A collection of one or more ConditionStatements that are combined using logical AND or OR operators.

Type: object
Required: gate, conditions
Additional properties: not allowed

Properties

  • gate — enum
    "&&" (logical AND) or "||" (logical OR)

  • conditions — array of ConditionStatement; minItems: 1
    The list of conditions to combine.

ConditionReference

A reference to a ConditionStatement defined in the root conditions object. This allows for common conditions to be reused.

Type: object
Required: ref
Additional properties: not allowed

Properties

  • ref — string
    Name of a condition defined at root conditions.

  • invert — boolean, optional
    Whether to invert this condition to require it to evaluate to false instead of true. Defaults to false if not present.

ConditionStatement

A containerized conditional statement after operators and/or evaluations have been applied to it.

One of:

Action

A chat action for the client to execute, either by displaying a message or running a command.

Type: object
Required: type, value
Additional properties: not allowed

Properties

  • type — enum
    "command" or "message"

  • value — string
    Command to run or message to display. Commands do not have to begin with a / character, but can.

Examples

Minimal Example

{
  "$schema": "./games.schema.json",
  "servers": [
    {
      "addressRegex": "(?:.*)?\\.hypixel\\.net(?::\\d{1,5})?",
      "enabled": true,
      "games": [
        {
          "name": "Main Lobby",
          "unlocalizedName": "mainLobby",
          "image": "https://quickplay.ecr.dev/static/images/games/platform-pc-256.png",
          "children": [
            {
              "name": "Go to Lobby",
              "unlocalizedName": "goToLobby",
              "steps": [
                {
                  "action": {
                    "type": "command",
                    "value": "l main"
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Conditionals Example

{
  "$schema": "./games.schema.json",
  "servers": [
    {
      "addressRegex": "(?:.*)?\\.hypixel\\.net(?::\\d{1,5})?",
      "enabled": true,
      "games": [
        {
          "name": "SkyBlock",
          "image": "https://hypixel.net/styles/hypixel-v2/images/game-icons/SkyBlock-64.png",
          "children": [
            {
              "name": "Go to Island",
              "children": {
                "steps": [
                  {
                    "if": { "ref": "isInSkyblock", "invert": true },
                    "action": { "type": "command", "value": "/skyblock" }
                  },
                  {
                    "action": { "type": "command", "value": "/home" }
                  }
                ]
              }
            }
          ]
        },
        {
          "name": "Create Private Game",
          "if": { "ref": "isInPartyAndMvpPlusPlus" },
          "children": {
            "steps": [
              {
                "action": { "type": "command", "value": "/p private" }
              }
            ]
          },
          "elseMessage": "You aren't MVP++ or aren't in a party."
        }
      ]
    }
  ],
  "conditions": {
    "isInSkyblock": {
      "condition": {
        "property": "mode",
        "state": "==",
        "value": "SKYBLOCK"
      }
    },
    "isMvpPlusPlus": {
      "condition": {
        "property": "monthlyPackageRank",
        "state": "==",
        "value": "SUPERSTAR"
      }
    },
    "isInPartyAndMvpPlusPlus": {
      "condition": {
        "gate": "&&",
        "conditions": [
          { "property": "isInParty", "state": "==", "value": true },
          { "ref": "isMvpPlusPlus" }
        ]
      }
    }
  }
}
Clone this wiki locally