> 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/advanced-actions.md).

# 进阶动作

除了发消息、跑命令和切页面，菜单还经常需要记住玩家刚才点选了哪个选项、扣除金币发放商品，或者让玩家在聊天栏里输入一段文字。这一页介绍用于数据存储、经济结算、物品操作和聊天输入捕获的进阶动作。它们同样写在按钮点击或菜单事件中，基础格式与[动作与导航](/cai-dan-pei-zhi/menus/actions.md)完全一致。

## 保存与删除数据

ArcMenu 提供了三种不同作用范围的数据存储，不需要额外安装变量插件就能在菜单里存取状态：

| 数据类型   | 写入动作              | 删除动作                 | 读取占位符             | 适用场景与生命周期                                                |
| ------ | ----------------- | -------------------- | ----------------- | -------------------------------------------------------- |
| 玩家临时数据 | `set-meta`        | `remove-meta`        | `{meta:名称}`       | 保存在内存中，适合记录当前购买数量、选中的分类标签等临时状态（别名：`set-temp`、`set-var`）。 |
| 玩家保存数据 | `set-data`        | `remove-data`        | `{data:名称}`       | 绑定在玩家身上并持久化保存，服务器正常重启后依然保留，适合存个人偏好或领奖记录。                 |
| 全服共享数据 | `set-global-data` | `remove-global-data` | `{globaldata:名称}` | 全服所有玩家共用并持久化保存，适合记录全服活动开关、公共计数等（别名：`set-g-data`）。        |

### 写入数据

写入格式统一为 `动作名称: 键名 值`，键名和值之间用空格隔开。值会按文本保存，内部可以包含空格；如果需要在一条动作里同时写入多个键值，可以用分号 `;` 隔开。再次写入同一个键名会覆盖旧值，从未设置过的键名通过占位符读取时会得到 `null`。

```yaml
actions:
  right:
    - 'set-data: preferred-world survival'
    - 'tell: &a已保存你的首选世界：{data:preferred-world}'
    - refresh
  shift-right:
    - 'remove-data: preferred-world'
```

如果你希望把一段算式的计算结果存进变量，请用 `{math: ...}` 包住算式，例如：

```yaml
- 'set-meta: total {math: {meta:input-x} * 24}'
```

如果直接写 `set-meta: total 3 * 24`，菜单会原样把字符串 `3 * 24` 存进去，而不会算出 `72`。

### 删除数据

删除动作的参数接收**完整匹配的正则表达式**。写固定名称（如 `remove-data: preferred-world`）会精准删除该项；写正则模式（如 `remove-data: preference-.*`）则会一次性清空当前玩家所有以 `preference-` 开头的保存数据。多个匹配模式之间同样可以用分号 `;` 隔开。

## 调整当前菜单参数

除了在 `open: 菜单ID 参数1 参数2` 跳转时传入参数，你也可以在当前页面内直接修改或清空参数列表：

```yaml
actions:
  right:
    - 'set-args: survival `生存世界`'
    - 'tell: &a世界ID：{0}，名称：{1}'
  shift-right: clear-args
```

* **`set-args: 参数列表`**（别名：`set-arg`、`set-arguments`）：用新的参数列表替换当前页面的参数。多个参数以空格分隔，包含空格的单个参数用反引号 `` ` `` 包围。设置后即可通过 `{0}`、`{1}` 等编号占位符读取。
* **`clear-args`**（别名：`clear-arg`、`del-args`）：不带参数，清空当前页面的所有菜单参数。

## 余额与点数结算

当服务器安装了 Vault（配合任意经济插件）或 PlayerPoints 时，可以直接用内置动作增减玩家的金币余额或点券：

| 操作类型  | Vault 金币动作                                       | PlayerPoints 点券动作                                   | 参数要求                            |
| ----- | ------------------------------------------------ | --------------------------------------------------- | ------------------------------- |
| 增加    | `give-money`（别名 `add-money`、`deposit-money`）     | `give-points`（别名 `add-points`、`deposit-points`）     | 大于 `0` 的数值或算式；金币支持小数，点券需为整数。    |
| 扣除    | `take-money`（别名 `remove-money`、`withdraw-money`） | `take-points`（别名 `remove-points`、`withdraw-points`） | 大于 `0` 的数值或算式；余额不足时扣款失败并中止后续动作。 |
| 设为指定值 | `set-money`（别名 `modify-money`）                   | `set-points`（别名 `modify-points`）                    | 大于 `0` 的数值或算式。                  |

这六种动作的参数都支持直接填写[数学表达式](/cai-dan-pei-zhi/menus/math-expressions.md)，不需要在外层套 `{math: ...}`：

```yaml
actions:
  right:
    - 'take-money: round({meta:input-x} * 24 * 0.95, 2)'
    - 'give-item: material:DIAMOND,amount:{meta:input-x}'
```

点券要求最终计算结果为整数，如果算式中包含折扣小数，建议套一层 `floor(...)`、`ceil(...)` 或 `round(...)` 明确取整方式。

当玩家余额不足、经济插件未就绪或算式无效时，该条动作会执行失败并自动停止当前动作列表（相当于触发了 `return`），因此排在扣款动作后面的 `give-item` 发货动作不会被误触发。不过在这条扣款动作**之前**已经执行过的动作不会回滚，所以编写商店购买流程时，请把 `take-money` / `take-points` 放在发货动作之前，或者先用[条件](/cai-dan-pei-zhi/menus/conditions.md)检查余额。

## 背包物品操作

### 发放与扣除物品

`give-item`（别名 `add-item`）和 `take-item`（别名 `remove-item`）用于向玩家背包发放或扣除原版及自定义模型物品：

```yaml
actions:
  right:
    - 'give-item: material:DIAMOND,amount:1,name:&b菜单奖励'
  shift-right:
    - 'take-item: material:DIAMOND,amount:1,name:&b菜单奖励'
```

单件物品的各个属性用英文逗号 `,` 隔开，属性名与值之间用冒号 `:` 或等号 `=` 连接（属性名中的下划线 `_` 与连字符 `-` 等效）；如果要一次操作多件不同物品，可以用分号 `;` 隔开多组配置。在 `take-item` 中，除 `amount` 外的属性名前还可以加感叹号 `!` 表示反向匹配（例如 `!material:DIRT` 表示匹配材质不是泥土的物品）。可用属性如下：

| 属性键与可用别名                                                 | 必填/可选 | 取值与匹配说明                                                                                               |
| -------------------------------------------------------- | ----- | ----------------------------------------------------------------------------------------------------- |
| `material`（别名：`materials`、`mat`、`mats`）                  | 可选    | 原版物品材质名称（如 `DIAMOND`、`PLAYER_HEAD`）。`give-item` 不填时默认发放 `BEDROCK`；`take-item` 不填时则不限制材质，仅按你填写的其他属性匹配。 |
| `amount`（别名：`amounts`、`amt`、`amts`）                      | 可选    | 数量，填 `1` 到 `99` 之间的整数，不填默认为 `1`。                                                                      |
| `name`（别名：`names`）                                       | 可选    | 物品显示名称，支持 `&` 颜色代码。发放时设为物品名；扣除时只要求背包物品名称（转换 `&` 颜色后忽略大小写）**包含**这段文字即可匹配。                              |
| `lore`（别名：`lores`）                                       | 可选    | 物品描述文字。发放时可用 `\n` 分成多行；扣除时只要背包物品的**任意一行** Lore（转换 `&` 颜色后忽略大小写）包含所填子串即视为匹配。                           |
| `model-data`（别名：`model-datas`、`modeldata`、`modeldatas`）  | 可选    | CustomModelData 整数值。扣除时要求物品带有 CustomModelData 且数值严格相等。                                                |
| `data`（别名：`datas`）                                       | 可选    | 整数，表示物品损耗值（耐久消耗量）。发放时小于 `0` 会按 `0` 处理；扣除时要求损耗值相等。                                                     |
| `head`（别名：`heads`、`skull`、`skulls`、`texture`、`textures`） | 可选    | 当物品为玩家头颅（`PLAYER_HEAD`）时，填入玩家名称以设置或按名称（忽略大小写）匹配头颅主人。                                                  |

发放物品时，如果玩家背包已满，放不下的部分会自动掉落在玩家脚下。扣除物品时，系统会按顺序遍历玩家背包储物格（不含护甲栏与副手）并依次扣除匹配的物品堆；若背包内匹配物品总数不足，已扣除的部分不会回滚，系统会向玩家发送物品不足提示，随后继续执行列表中的后续动作。如果你希望只在物品充足时才继续执行发货等后续步骤，请先配合[条件](/cai-dan-pei-zhi/menus/conditions.md)检查玩家持有的物品。

### 修复、附魔与刷新物品栏

* **`repair-item: 槽位`**（别名 `repair-items`）：将指定位置上的可损耗物品耐久度完全修满。多个目标槽位之间用分号 `;` 隔开（如 `repair-item: hand;armor`）。
* **`enchant-item: 槽位 附魔ID 等级`**（别名 `enchant-items`）：为指定槽位的物品添加附魔。槽位、附魔 ID 和等级三个参数**均须填写**，彼此之间用空格或英文逗号 `,` 隔开；如果要一次执行多组附魔，多组之间用分号 `;` 隔开。附魔 ID 支持原版名称（如 `minecraft:unbreaking` 或 `unbreaking`）；等级必须填写大于或等于 `1` 的正整数，或写成正整数范围 `1-3` 让系统随机抽选一级。
* **`reload-inventory`**（别名 `reload-inv`）：不带参数，主动向客户端同步刷新一次玩家背包显示。

`repair-item` 和 `enchant-item` 的**槽位**参数支持填入以下值：

* 手部与护甲：`hand` / `mainhand`（主手）、`offhand`（副手）、`helmet`（头盔）、`chestplate`（胸甲）、`leggings`（护腿）、`boots`（靴子）、`armor`（全部四件护甲）。
* 批量范围：`all` / `inv`（玩家物品栏中的全部非空物品）。
* 指定格号：直接填数字槽位编号（如 `0` 代表快捷栏第一格）。

## 聊天栏输入捕获（Catcher）

除了使用菜单内的 [Arcitx 文本输入组件](/gong-neng-pei-zhi/arcitx.md)，你也可以用结构化的 `catcher` 动作暂时收起菜单，引导玩家在聊天栏里输入一段或多段文字（例如自定义昵称、称号或转账备注）。

`catcher` 使用 YAML 键值映射编写，里面可以定义一个或多个按书写顺序依次执行的输入阶段：

```yaml
actions:
  right:
    - catcher:
        nickname:
          type: CHAT
          start:
            - 'tell: &e请在聊天栏输入新昵称，输入 cancel 可取消。'
          cancel:
            - 'tell: &7已取消修改昵称。'
          end:
            - 'set-data: nickname {meta:input-nickname}'
            - 'tell: &a昵称已保存为：{data:nickname}'
```

每个阶段（上例中的 `nickname` 就是自定义的阶段名称）包含以下字段：

* **`type`**：固定填写 `CHAT`（不填时默认也是 `CHAT`）。
* **`start`**（或 `before`）：进入该输入阶段时执行的动作列表，通常用来提示玩家该输入什么。
* **`cancel`**：玩家主动取消输入时执行的动作列表。玩家在聊天栏输入 `cancel`、`quit`、`end` 或 `q`（不区分大小写）即可触发取消。
* **`end`**（或 `after`）：玩家在聊天栏发出正常文字后执行的动作列表（支持带条件的动作分支）。

### 读取输入内容与重新输入

玩家在捕获期间发出的聊天消息会被菜单拦截，不会公开刷到公屏上。捕获到的文字会自动存入玩家的临时数据（meta）中：

* **`{meta:input}`**：读取刚刚完成的这一阶段输入的文字。
* **`{meta:input-阶段名称}`**：读取指定阶段输入的文字（例如 `{meta:input-nickname}`）。当你在 `catcher` 下连续定义了多个阶段（比如先输收款人、再输金额）时，可以在最后一个阶段的 `end` 里同时读取前面各个阶段的内容。
* **`retype`**（别名 `repeat`、`re-enter`）：放在 `end` 分支的动作列表中。当你在 `end` 里用条件检查发现玩家的输入不符合要求时，执行 `retype` 可以让玩家留在当前阶段重新输入一遍，并再次触发 `start` 提示。


---

# 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/advanced-actions.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.