> 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/cai-dan-pei-zhi/menus/conditions.md).
# 条件
同一个按钮，面对普通玩家和 VIP 玩家、余额充足和余额不足的玩家，往往需要给出不同的反馈。通过配置 `condition`（条件），你可以让交互区域、某种点击方式、菜单事件甚至单独某一条动作根据玩家当前的权限、变量或 PlaceholderAPI 占位符动态决定要执行什么。
## 在哪里配置条件
根据控制范围从大到小，条件有四种常见的放置位置：
### 1. 整个交互区域的条件
直接写在后端交互区域下的 `condition`，会同时作为这个区域所有点击类型以及准星移入（`on-hover`）、移出（`on-leave`）事件的前置条件：
```yaml
backend:
vip-area:
x: 0
y: 0
width: 80
height: 24
condition: 'perm myserver.menu.vip'
deny:
- 'tell: &e这项功能需要会员权限。'
actions:
right: 'open: vip-services'
```
当玩家拥有 `myserver.menu.vip` 权限时，右键会打开 `vip-services`，悬停与移出动作也会正常触发；没有权限时，点击该区域会转为执行区域 `deny` 下的提示动作，而 `on-hover` 和 `on-leave` 则会直接跳过，不会在准星滑过时触发 `deny`。
### 2. 某一种点击方式的条件
如果只想限制右键，而让左键或 Shift+右键保持无条件执行，可以把 `condition`、`actions` 和 `deny` 写进对应的点击键下面：
```yaml
actions:
right:
condition: 'perm myserver.menu.member'
actions:
- 'tell: &a欢迎来到会员服务。'
deny:
- 'tell: &e开通会员后即可使用。'
shift-right: close
```
### 3. 多分支优先级列表
当一个按钮需要根据不同档位的身份或状态分流到多套逻辑时，可以把点击动作（或 `events.open`、`events.close`、`on-hover`、`on-leave`）写成条件分支列表：
```yaml
actions:
right:
- priority: 0
condition: 'perm myserver.menu.vip'
actions:
- 'tell: &a欢迎，尊贵的 VIP！'
- return
- priority: 10
actions:
- 'tell: &a欢迎来到服务器！'
```
* **`priority`**：填写整数，数值**越小**越先执行；如果不填或数值相同，则按从上到下的书写顺序依次判断。（注意：交互区域本身的 `priority` 是数值越大越优先命中，而这里的动作分支 `priority` 是从小到大依次执行。）
* **配合 `return` 分流**：系统会按顺序检查每一个分支。如果不加 `return`，满足第一个分支的 VIP 玩家跑完第一段后，还会继续跑下面没有写 `condition` 的默认分支。在第一个分支末尾加上 `return` 即可在命中后直接结束流程。
（在条件分支映射中，`condition` 也可以写为别名 `require` / `requirement`，`actions` 可写为 `list` / `click` / `execute`，`deny` 可写为 `deny-list` / `deny-actions`。）
### 4. 单条动作的行尾条件
如果一整串动作里只有某一行需要按条件触发，直接在动作字符串末尾加上 `{condition=表达式}` 即可：
```yaml
actions:
right:
- 'tell: &a这是额外送给会员的问候。 {condition=perm myserver.vip}'
- 'sound: UI_BUTTON_CLICK-1-1'
```
另外，如果你需要限制**整个菜单**的打开资格，请在菜单顶层配置 `permission: 权限节点`，并可搭配 `permission-denied-menu: 引导菜单ID` 在无权限时自动跳转到介绍页面，详见[菜单文档结构](/cai-dan-pei-zhi/menus.md)。
## 条件表达式写法
`condition` 的值是一段用单引号或双引号包起来的字符串。执行前，系统会先把里面的占位符（如 `%player_name%`、`{data:键名}`、`{meta:键名}`）替换成当前玩家的实际值，然后再做判断。
| 判断类型 | 表达式示例 | 含义与可填值说明 |
| -------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| 权限检查 | perm myserver.vip
permission myserver.vip
| 检查玩家是否拥有指定权限节点（权限节点中支持包含占位符）。 |
| 取反判断 | not (perm myserver.vip)
!perm myserver.vip
| 对后面的条件取反，原条件不成立时通过。 |
| 相等与不等 | %player\_name% == Alex
%player\_name% != Alex
| 判断两边的值是否相等或不相等（`==` 也可写为 `is`，`!=` 也可写为 `is not`）。 |
| 包含子串 | `%player_name% contains Alex` | 按文本判断左侧内容是否包含右侧文字（忽略大小写）。 |
| 数值大小比较 | `%player_y% >= 64` | 支持 `>`、`>=`、`<`、`<=`，按数值或算式计算结果比较大小。 |
| 检查变量是否存在 | `{data:preferred-world} != null` | 未设置过的 `{meta:...}`、`{data:...}`、`{globaldata:...}` 会展开为 `null`，与 `null` 比较即可判断玩家是否设置过该项。 |
| 布尔与真值判断 | `'true'`、`'false'`、`'%vault_eco_balance%'` | 直接写 `true` 或 `false` 表示固定通过或不通过；直接写一个占位符时，展开结果为 `true`、`yes`、`on`（忽略大小写）或任意**非零数字**均视为通过。 |
（如果你在迁移旧配置，条件比较前带有 `check` 前缀如 `check %player_level% >= 10` 也是直接兼容的。）
### 文本比较与数值比较的规则
* **包含空格的文本**：如果比较的一侧包含空格，请用反引号 `` ` ``、单引号或双引号把那一侧单独包起来，例如 `` {data:title} == `生存先锋` `` 。
* **大小写与类型识别**：使用 `==` 或 `!=` 时，如果两边都能解析为数字或数学表达式，会按计算后的数值大小判断是否相等（例如 `1.0 == 1` 为真）；否则按忽略大小写的普通文本进行比较。`contains` 则始终按忽略大小写的文本处理。
* **大小比较要求**：使用 `>`、`>=`、`<`、`<=` 时，只要有一侧是数字或算式，另一侧也必须能算出有效数字；如果另一侧是未设置的 `null` 或普通字母文本，该条件会直接判为不通过。
## 在条件中使用数学表达式
在比较运算符两侧，你可以直接编写带加减乘除和函数的算式，比如在商店购买前核对“当前余额是否够付 单价 × 数量”：
```yaml
condition: '%vault_eco_balance% >= {meta:input-x} * 24'
```
注意：ArcMenu 没有名为 `money` 的内置余额变量，判断余额时请填入你服务器上经济插件提供的 PlaceholderAPI 占位符（例如 `%vault_eco_balance%`），或者在测试时填入具体数字（如 `1000 >= {meta:input-x} * 24`）。
算式支持 `+`、`-`、`*`、`/`、`%`（取余）、`^`（乘方）、圆括号 `()`，以及 `abs`、`min`、`max`、`floor`、`ceil`、`round` 函数。如果你想把形如 `3*4` 的内容纯粹当作普通字符串来比对、不让系统去算乘法，用反引号把它包起来即可，例如 ``condition: '`3*4` == `3*4`'``。完整的算式语法见[数学表达式](/cai-dan-pei-zhi/menus/math-expressions.md)。
当条件里的算式出现除以零、语法错误或未赋值的 `null` 参与运算时，系统会在后台输出一条包含具体位置和原因的日志，并将该条件判为**不通过**（即使外层套了 `not (...)`，出错的算式也不会变成通过）。
## 组合多个条件
需要同时满足多个条件，或者满足其中任意一个条件时，可以使用逻辑运算符 `&&`（全部满足）、`||`（任一满足）以及圆括号 `()` 来组合：
```yaml
condition: 'perm myserver.member && (perm myserver.vip || %player_y% >= 64)'
```
在同一个层级中，`||` 会先将条件切分为多个“或”分支，每个分支内部再按 `&&` 要求全部满足；加上圆括号可以自由控制组合顺序。
除了 `&&` 和 `||`，你也可用聚合语法 `all [条件1; 条件2]`（全部满足）和 `any [条件1; 条件2]`（任一满足），方括号内的多项条件可用分号 `;` 或逗号 `,` 分隔：
```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/cai-dan-pei-zhi/menus/conditions.md?ask=&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.