Skip to main content

​
Menu States & Conditions

States allow a single menu definition to render differently based on runtime conditions. Instead of creating multiple menu entries, you define states with conditions and layer overrides.

​
State Architecture

​
Condition Types

​
Fact Operators

OperatorDescriptionExample
EQEqualcoins EQ 100
NEQNot equalrank NEQ 0
GTGreater thanlevel GT 10
LTLess thanhealth LT 20
GTEGreater than or equalkills GTE 50
LTELess than or equalmana LTE 100
CONTAINSString containstag CONTAINS vip
HAS_PERMISSIONPlayer has permissionessentials.fly HAS_PERMISSION

​
Layer Overrides

When a state is active, its layer overrides modify specific layers:

​
Overridable Properties

PropertyTypeDescription
visiblebooleanShow/hide the layer
srcstringChange the texture source
unicodestringChange the unicode character
textstringChange the text content
colorstringChange the color (hex)
x, ydoubleChange position
width, heightdoubleChange dimensions
opacitydoubleChange transparency (0.0-1.0)

​
Using the Overrides Editor

The Overrides Editor in the States panel provides a complete UI for configuring layer overrides:
  1. Select the target layer from the dropdown at the top
  2. Toggle each property on/off using the switch next to its name
  3. Edit the override value when enabled:
    • Visible: checkbox
    • Text, Color, Source: text fields
    • X, Y, Width, Height: number fields
    • Opacity: slider (0-100%)
  4. Remove an override with the “Remove this override” button at the bottom
  5. Add new overrides with the + button in the header
Properties that are not overridden keep their base layer value. Only overridden properties appear in the serialized state definition. Preview mode: Click the eye icon on any state card to see the canvas render with that state’s overrides applied in real-time.

​
Sub-States

Sub-states allow nested conditions within a parent state: Sub-states inherit the parent’s conditions and add their own. The most specific match wins.

​
Priority System

States are evaluated by priority (lowest first). The first matching state is applied:

​
Example: Shop Menu with Ranks

action:
  type: open_gui
  id: "premium_shop"
  guiType: CUSTOM
  size: "27"
  title: "<gold>Premium Shop"

  # Base layers — shown when no state matches
  _visual_layers:
    - id: "background"
      type: image
      src: "shop_bg"
      x: 0; y: 0; width: 176; height: 90
    - id: "lock_icon"
      type: image
      src: "lock"
      x: 70; y: 35; width: 18; height: 18
    - id: "status_text"
      type: text
      text: "<red>Premium required"
      x: 50; y: 55; width: 80; height: 12

  _gui_states:
    premium:
      name: "Premium"
      priority: 1
      conditions:
        - type: fact
          factKey: "rank"
          operator: "GTE"
          value: 2
      layerOverrides:
        lock_icon:
          visible: false
        status_text:
          text: "<green>Welcome, VIP!"
          color: "#00FF00"

    vip:
      name: "VIP"
      priority: 2
      conditions:
        - type: and
          conditions:
            - type: fact
              factKey: "rank"
              operator: "GTE"
              value: 3
            - type: fact
              factKey: "premium_time"
              operator: "GT"
              value: 0
      layerOverrides:
        lock_icon:
          visible: false
        status_text:
          text: "<gold>Legendary Member"
          color: "#FFD700"

​
Preview in Web Editor

The preview applies overrides in real-time so you can see exactly how the menu will look for players matching that state’s conditions.