> For the complete documentation index, see [llms.txt](https://simple.superiormc.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://simple.superiormc.cn/arcmenu-wen-dang/cai-dan-pei-zhi/menus/conditions.md).

# 条件

条件用于判断玩家是否可以执行某项菜单操作，例如检查权限、所在位置或已保存的选择。本页先介绍条件所在的配置层级，再说明判断语法与执行顺序。

Paper、Folia、Leaf 和 Spigot 均支持条件判断，但可用动作和占位符仍受平台限制。Spigot 支持权限判断及玩家名称、UUID、坐标占位符，不支持玩家数据、菜单参数或 PlaceholderAPI 占位符。

## 配置层级

| 配置位置                           | 作用范围            | 未通过时           |
| ------------------------------ | --------------- | -------------- |
| 菜单顶层 `permission`              | 是否允许打开整个菜单。     | 拒绝打开菜单。        |
| `backend` → 区域名称 → `condition` | 是否允许执行该区域的点击动作。 | 执行区域的 `deny`。  |
| 点击类型或事件中的条件分支 → `condition`    | 选择这一分支中的动作。     | 执行该分支的 `deny`。 |
| 单条动作中的 `{condition=...}`       | 是否执行这一条动作。      | 跳过该动作。         |

菜单顶层的 `permission` 填写权限节点，不是条件表达式。它与玩家使用菜单所需的 `arcmenu.use` 一同检查，具体说明见[菜单文档结构](/arcmenu-wen-dang/cai-dan-pei-zhi/menus.md#permission)。菜单顶层不支持 `condition` 或 `deny`。

## 区域条件

区域的 `condition`、`deny` 与 `actions` 同级，控制该区域所有点击类型。

```yaml
backend:
  vip-area:
    x: 0
    y: 0
    width: 80
    height: 24
    condition: 'perm myserver.menu.vip'
    deny:
      - 'tell: &cYou do not have permission.'
    actions:
      right:
        - 'tell: &aWelcome, VIP!'
      shift-right: close
```

没有 `myserver.menu.vip` 权限的玩家点击这个区域时，只会收到拒绝消息；Shift+右键也不会执行关闭动作。省略 `deny` 时，条件不满足不会执行拒绝动作。

区域条件在点击时判断，不会隐藏按钮或提示框，也不会将点击转交给下面重叠的区域。区域选择规则见[后端交互区域与点击事件](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/backend.md)。

## 点击动作中的条件分支

若只限制某一种点击，可在该点击类型下面填写分支。层级为：**区域名称 → `actions` → 点击类型 → 分支属性**。

```yaml
backend:
  member-area:
    x: 0
    y: 0
    width: 80
    height: 24
    actions:
      right:
        condition: 'perm myserver.menu.member'
        actions:
          - 'tell: &aMember access granted.'
        deny:
          - 'tell: &cMembership is required.'
      shift-right: close
```

这里外层的 `actions` 按点击类型组织操作，内层的 `actions` 是条件满足时执行的动作列表。权限条件只限制普通右键，Shift+右键仍可关闭菜单。

### 分支属性

| 属性          | 用途                   | 默认行为                                |
| ----------- | -------------------- | ----------------------------------- |
| `condition` | 本分支的判断表达式。           | 省略时直接执行 `actions`。                  |
| `actions`   | 条件满足时执行的动作。          | 无。                                  |
| `deny`      | 条件不满足时执行的动作。         | 无。                                  |
| `priority`  | 分支处理顺序，使用整数，较小数值先处理。 | 单个分支为 `0`；列表分支按位置依次为 `0`、`1`、`2`……。 |

每个分支至少需要 `actions` 或 `deny` 中的一项。不要将 `condition` 写成 YAML 列表；多个判断应组合成一个表达式。

### 多个分支与执行顺序

同一点击类型下的多个分支使用列表：

```yaml
backend:
  greeting-area:
    x: 0
    y: 0
    width: 80
    height: 24
    actions:
      right:
        - priority: 0
          condition: 'perm myserver.menu.vip'
          actions:
            - 'tell: &aWelcome, VIP!'
            - return
        - priority: 10
          actions:
            - 'tell: &aWelcome!'
```

分支不是“只执行第一个满足条件的分支”。每个分支都会依次判断：满足时执行 `actions`，不满足时执行自己的 `deny`，然后继续处理后续分支，除非动作结束了当前流程。

本例在 VIP 分支中使用 `return`，因此 VIP 玩家只收到专属消息；其他玩家继续执行通用分支。若删除 `return`，VIP 玩家会收到两条消息。

分支优先级数值相同时，按配置出现顺序处理。此处的 `priority` 只安排同一点击类型内部的分支顺序，与区域重叠优先级不同：区域选择是较大数值优先。`all`、`right` 等点击分组之间仍按配置顺序处理。

## 事件中的条件分支

`events.open` 和 `events.close` 也可使用条件分支。写法与点击类型下相同：

```yaml
events:
  open:
    condition: 'perm myserver.menu.vip'
    actions:
      - 'tell: &aVIP menu greeting.'
    deny:
      - 'tell: &7Menu greeting.'
```

这里的条件只选择打开事件中的消息，不会阻止菜单打开。打开权限应由菜单顶层的 `permission` 控制。

## 单条动作条件

在动作字符串中附加 `{condition=...}`，只限制该动作：

```yaml
backend:
  notice-area:
    x: 0
    y: 0
    width: 80
    height: 24
    actions:
      right:
        - 'tell: &aVIP notice. {condition=perm myserver.menu.vip}'
        - 'sound: UI_BUTTON_CLICK-1-1'
```

本例仅向 VIP 玩家发送消息，但所有点击者都会听到声音。单条动作条件失败时，不会触发区域或分支的 `deny`。

对整组操作设置共同要求时，应使用条件分支。若在“扣款”一条动作上设置条件、却让后面的奖励动作无条件执行，条件不会保护整组交易。

## 判断语法

`condition` 必须使用字符串，建议统一保留 YAML 引号。固定真假值也写作 `condition: 'true'` 或 `condition: 'false'`，不要写成 YAML 布尔值。

### 权限判断

`perm myserver.menu.vip` 判断玩家是否拥有指定权限；也可使用 `permission myserver.menu.vip`。写入真实权限节点，不会自动创建权限组或授予权限。

### 数值与文字比较

| 表达式                                  | 含义                                    |
| ------------------------------------ | ------------------------------------- |
| `%player_y% >= 64`                   | 玩家 Y 坐标大于或等于 `64`。                    |
| `%player_y% > 64`                    | 玩家 Y 坐标大于 `64`。                       |
| `%player_y% <= 64`                   | 玩家 Y 坐标小于或等于 `64`。                    |
| `%player_y% < 64`                    | 玩家 Y 坐标小于 `64`。                       |
| `%player_name% == Alex`              | 玩家名称等于 `Alex`。                        |
| `%player_name% != Alex`              | 玩家名称不等于 `Alex`。                       |
| `%player_name% contains Alex`        | 玩家名称包含 `Alex`。                        |
| `{data:preferred-world} == survival` | 已保存的世界偏好为 `survival`，仅适用于 Paper 系服务端。 |

两边都会先替换占位符。两边均为数字时按数值比较，否则按文字比较；文字比较不区分大小写。`is` 与 `is not` 也可分别表示等于和不等于。

含空格的比较值可用反引号包围，例如 `` {data:display-name} == `Survival World` `` 。未设置的数据会得到 `null`，可用 `{data:preferred-world} != null` 检查是否已设置。

数值条件应确认占位符实际返回数字。未解析的占位符不会自动变为 `0`，也不会自动使条件失败；不要直接将未核对的余额占位符用于交易判断。

### 组合判断

| 写法                                                       | 含义            |
| -------------------------------------------------------- | ------------- |
| `perm myserver.menu.member && %player_y% >= 64`          | 两项条件都满足。      |
| `perm myserver.menu.vip \|\| perm myserver.menu.staff`   | 任意一项条件满足。     |
| `not (perm myserver.menu.vip)`                           | 不拥有该权限。       |
| `!(perm myserver.menu.vip)`                              | 与上一项相同。       |
| `all [perm myserver.menu.member; %player_y% >= 64]`      | 方括号内所有条件都满足。  |
| `any [perm myserver.menu.vip; perm myserver.menu.staff]` | 方括号内至少一项条件满足。 |

`&&` 比 `||` 先组合；复杂表达式建议用括号明确范围。例如 `perm myserver.menu.member && (perm myserver.menu.vip || %player_y% >= 64)` 要求玩家先拥有会员权限，再满足括号内任意一项。

`all`、`any` 的方括号属于表达式文字，应将整个表达式放在 YAML 引号中，不要转换成 YAML 列表。

### 直接判断占位符

也可直接使用返回真假值的占位符作为条件，例如 `condition: '%arcmenu_meta_ready%'`。其值为 `true`、`yes`、`on` 或非零数字时通过，其余值不通过；这些文字不区分大小写。

此例使用玩家临时数据，仅适用于 Paper 系服务端。若要判断具体文字，应使用 `==`、`!=` 或 `contains`，不要把任意非空文字当作“通过”。

## 检查与加载

执行 `/arcmenu validate` 和 `/arcmenu reload` 后，通过正常菜单检查条件满足和不满足两种情况。特别确认：

* 普通玩家的权限判断与拒绝提示是否正确。
* 多个分支是否需要 `return`，避免同时执行专属与通用操作。
* 占位符是否返回预期文字或数字，所需插件是否已安装。
* 所选平台是否支持分支中的动作与占位符。

预览不会执行点击动作。条件也不会自动撤销已经完成的命令、扣款或物品操作；相关行为见[进阶动作](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/advanced-actions.md)。