> For the complete documentation index, see [llms.txt](https://docs.myarc.icu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.myarc.icu/en/menu-configuration/menus/conditions.md).

# Conditions

A single button often needs to respond differently depending on whether a player is a regular member or a VIP, or whether they can afford an item. By configuring `condition`, you can make interactive regions, specific click types, menu events, or individual actions decide what to run dynamically based on the player's permissions, stored variables, or PlaceholderAPI values.

## Where to place conditions

From broadest to narrowest scope, there are four places where you can attach conditions:

### 1. Whole interactive region

Placing `condition` directly under a backend interactive region applies it as a prerequisite for all click types in that region, as well as cursor `on-hover` and `on-leave` events:

```yaml
backend:
  vip-area:
    x: 0
    y: 0
    width: 80
    height: 24
    condition: 'perm myserver.menu.vip'
    deny:
      - 'tell: &eThis feature requires VIP membership.'
    actions:
      right: 'open: vip-services'
```

When a player has the `myserver.menu.vip` permission, right-clicking opens `vip-services` and hover or leave actions run normally. Without that permission, clicking the region runs the actions under `deny` instead, while `on-hover` and `on-leave` are skipped quietly so moving the cursor across the button does not spam the `deny` message.

### 2. A specific click type

To restrict right-clicking while leaving left-click or Shift+right-click unconditional, place `condition`, `actions`, and `deny` under that specific click key:

```yaml
actions:
  right:
    condition: 'perm myserver.menu.member'
    actions:
      - 'tell: &aWelcome to member services.'
    deny:
      - 'tell: &eBecome a member to use this feature.'
  shift-right: close
```

### 3. Priority branch lists

When a button needs to route players through several different tiers or states, write the click actions (or `events.open`, `events.close`, `on-hover`, `on-leave`) as a list of conditional branches:

```yaml
actions:
  right:
    - priority: 0
      condition: 'perm myserver.menu.vip'
      actions:
        - 'tell: &aWelcome, VIP!'
        - return
    - priority: 10
      actions:
        - 'tell: &aWelcome to the server!'
```

* **`priority`**: Integer value where **smaller** numbers run first. If omitted or tied, branches are evaluated from top to bottom in written order. (Note: An interactive region's own `priority` gives higher numbers precedence when regions overlap, whereas action branch `priority` runs from lowest to highest.)
* **Branching with `return`**: ArcMenu evaluates each branch in order. Without `return`, a VIP player who matches the first branch would also run the unconditional fallback branch below it. Adding `return` at the end of the first branch stops execution as soon as that branch finishes.

(In conditional branch maps, `condition` also accepts the aliases `require` and `requirement`, `actions` accepts `list`, `click`, and `execute`, and `deny` accepts `deny-list` and `deny-actions`.)

### 4. Inline condition on a single action

If only one line in an action list needs a condition, append `{condition=expression}` to the end of that action string:

```yaml
actions:
  right:
    - 'tell: &aHere is an extra greeting for members. {condition=perm myserver.vip}'
    - 'sound: UI_BUTTON_CLICK-1-1'
```

To restrict access to an **entire menu**, set `permission: permission-node` at the top level of the menu file, optionally paired with `permission-denied-menu: menu-id` to redirect players without permission to an introduction page; see [Menu document structure](/en/menu-configuration/menus.md).

## Writing condition expressions

A `condition` value is a single- or double-quoted string. Before evaluating the expression, ArcMenu replaces any placeholders inside it (such as `%player_name%`, `{data:key}`, or `{meta:key}`) with the current player's actual values.

| Check type               | Example expression                                                                | Meaning and valid inputs                                                                                                                                                                  |
| ------------------------ | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Permission check         | <p><code>perm myserver.vip</code><br><code>permission myserver.vip</code></p>     | Checks whether the player has the specified permission node (placeholders are supported inside the node name).                                                                            |
| Negation                 | <p><code>not (perm myserver.vip)</code><br><code>!perm myserver.vip</code></p>    | Inverts the following condition, passing when the inner condition is false.                                                                                                               |
| Equality and inequality  | <p><code>%player\_name% == Alex</code><br><code>%player\_name% != Alex</code></p> | Checks whether the two sides are equal or unequal (`==` can also be written as `is`, and `!=` as `is not`).                                                                               |
| Substring match          | `%player_name% contains Alex`                                                     | Treats both sides as text and checks whether the left side contains the right side (case-insensitive).                                                                                    |
| Numeric comparison       | `%player_y% >= 64`                                                                | Supports `>`, `>=`, `<`, and `<=`, comparing numeric values or calculated math expressions.                                                                                               |
| Variable existence check | `{data:preferred-world} != null`                                                  | Unset `{meta:...}`, `{data:...}`, and `{globaldata:...}` placeholders expand to `null`; compare against `null` to check whether a value has been saved.                                   |
| Boolean and truthy check | `'true'`, `'false'`, `'%vault_eco_balance%'`                                      | Writing `true` or `false` directly always passes or fails. Writing a standalone placeholder passes when it expands to `true`, `yes`, `on` (case-insensitive), or any **non-zero number**. |

(If you are migrating older configurations, comparisons prefixed with `check`, such as `check %player_level% >= 10`, remain directly compatible.)

### Text and numeric comparison rules

* **Text containing spaces**: If either side of a comparison contains spaces, wrap that operand in backticks (`` ` ``), single quotes, or double quotes, such as `` {data:title} == `Survival Pioneer` ``.
* **Case sensitivity and type detection**: With `==` and `!=`, if both sides can be parsed as numbers or math expressions, ArcMenu compares their calculated numeric values (for example, `1.0 == 1` is true). Otherwise, it compares them as case-insensitive plain text. `contains` always compares operands as case-insensitive text.
* **Ordering comparisons**: With `>`, `>=`, `<`, and `<=`, whenever one side is a number or math expression, the other side must also evaluate to a valid number. If the other side is an unset `null` value or non-numeric text, the condition fails.

## Using math expressions in conditions

You can write arithmetic formulas and functions directly on either side of a comparison operator—for example, checking whether a player's balance covers `unit price × quantity` before a shop purchase:

```yaml
condition: '%vault_eco_balance% >= {meta:input-x} * 24'
```

Note: ArcMenu does not have a built-in balance variable named `money`. Use the PlaceholderAPI placeholder provided by your economy plugin (such as `%vault_eco_balance%`), or a fixed number like `1000 >= {meta:input-x} * 24` when testing.

Expressions support `+`, `-`, `*`, `/`, `%` (remainder), `^` (exponentiation), parentheses `()`, and the functions `abs`, `min`, `max`, `floor`, `ceil`, and `round`. If you want to compare a string like `3*4` literally without multiplying it, wrap the operand in backticks, such as ``condition: '`3*4` == `3*4`'``. For full syntax details, see [Math expressions](/en/menu-configuration/menus/math-expressions.md).

If a math expression in a condition divides by zero, contains a syntax error, or tries to calculate with an unset `null` value, ArcMenu logs the exact location and reason to the console and evaluates the condition as **false** (even if wrapped in `not (...)`, a broken expression never becomes true).

## Combining multiple conditions

To require multiple conditions at once or any one of several conditions, combine them with `&&` (all must pass), `||` (any may pass), and parentheses `()`:

```yaml
condition: 'perm myserver.member && (perm myserver.vip || %player_y% >= 64)'
```

At the same nesting level, `||` splits the expression into OR branches first, and `&&` requires every check within a branch to pass. Use parentheses to group checks in any order you need.

You can also use the aggregate syntax `all [condition1; condition2]` (all must pass) and `any [condition1; condition2]` (any may pass), separating items inside the square brackets with semicolons (`;`) or commas (`,`):

```yaml
condition: 'all [perm myserver.member; any [perm myserver.vip; %player_y% >= 64]]'
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.myarc.icu/en/menu-configuration/menus/conditions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.