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

# 进阶动作

本页介绍数据存取、菜单参数、余额、物品和聊天输入动作。动作的配置位置与基础写法见[动作与导航](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/actions.md)。

这些动作适用于 Paper、Folia、Leaf 等服务端，Spigot 不支持。余额与点数操作还需要对应插件；其余示例不要求安装额外插件。

## 数据存取

数据由名称和值组成。例如，`selected-world` 是名称，`survival` 是值。写入格式为 `动作名称: 名称 值`，再次写入同一名称会覆盖原值。

| 数据范围   | 写入动作              | 删除动作                 | 读取方式              | 保留范围               |
| ------ | ----------------- | -------------------- | ----------------- | ------------------ |
| 玩家临时数据 | `set-meta`        | `remove-meta`        | `{meta:名称}`       | 按玩家区分，不在插件重新启动后保留。 |
| 玩家保存数据 | `set-data`        | `remove-data`        | `{data:名称}`       | 按玩家保存，正常重启后仍可使用。   |
| 全服共享数据 | `set-global-data` | `remove-global-data` | `{globaldata:名称}` | 所有玩家共用，正常重启后仍可使用。  |

临时数据不会仅因关闭菜单而清除。适合在菜单间传递临时选择；需要长期记录的玩家设置应使用 `set-data`。

```yaml
backend:
  preference-area:
    x: 0
    y: 0
    width: 80
    height: 24
    actions:
      right:
        - 'set-meta: selected-world survival'
        - 'set-data: preferred-world survival'
        - 'tell: &aSaved world: {data:preferred-world}'
      shift-right:
        - 'remove-data: preferred-world'
        - 'tell: &7Preference removed.'
```

此片段保存玩家的世界偏好，不会传送玩家或创建世界。若要在前端文字中显示最新值，可在写入后使用 `refresh`，或为对应文字配置定时刷新。

### 值与读取

名称后面的内容作为值，可包含空格，例如 `set-data: display-name Survival World`。这些动作保存文字，不会将 `set-data: visits 1` 解释为“增加一次访问”。

同一写入动作可用分号分隔多组名称和值，因此值中的分号也会作为分隔符，不应作为普通文字使用。

读取未设置的数据时显示 `null`。数据占位符由 ArcMenu 提供，无需 PlaceholderAPI；完整说明见[占位符与文字格式](/arcmenu-wen-dang/wen-zi-ge-shi/text-placeholders.md)。

### 删除范围

删除动作的参数用于匹配数据名称，支持正则表达式。例如：

| 写法                                 | 删除内容                           |
| ---------------------------------- | ------------------------------ |
| `remove-meta: selected-world`      | 名为 `selected-world` 的玩家临时数据。   |
| `remove-data: preference-.*`       | 当前玩家名称以 `preference-` 开头的保存数据。 |
| `remove-global-data: event-status` | 全服共享的 `event-status` 数据。       |

匹配针对完整名称。普通名称建议使用字母、数字、下划线和连字符，避免将正则表达式符号误用于单个名称。删除共享数据会影响所有玩家读取的结果。

## 菜单参数

`open` 后传递的参数可供目标菜单使用。`set-args` 替换当前玩家的整组参数，`clear-args` 清空参数；它们不会切换菜单。

```yaml
backend:
  argument-area:
    x: 0
    y: 0
    width: 80
    height: 24
    actions:
      right:
        - 'set-args: survival `Survival World`'
        - 'tell: &aWorld ID: {0}'
        - 'tell: &7Display name: {1}'
      shift-right: clear-args
```

参数按 `0` 开始编号，本例的 `{0}` 为 `survival`，`{1}` 为 `Survival World`。使用反引号将含空格的内容合为一个参数。`set-args` 会替换已有参数，不是追加。

参数属于当前导航流程，不适合保存长期设置。需要在重启后保留的内容应使用玩家保存数据。

## 余额与点数

| 操作      | 余额动作             | 点数动作              |
| ------- | ---------------- | ----------------- |
| 增加      | `give-money: 10` | `give-points: 10` |
| 扣除      | `take-money: 10` | `take-points: 10` |
| 设置为指定数值 | `set-money: 100` | `set-points: 100` |

余额动作需要 Vault 和兼容的经济插件；点数动作需要 PlayerPoints。相关前提见[平台与插件兼容性](/arcmenu-wen-dang/pei-zhi-yu-guan-li/compatibility.md)。

数值必须大于 `0`。余额可使用小数，点数应使用整数。`set-money` 和 `set-points` 是设置总数，不是在现有数值上增加；不能使用这组动作设置为 `0`。

```yaml
backend:
  reward-area:
    x: 0
    y: 0
    width: 80
    height: 24
    actions:
      right:
        - 'give-money: 10'
```

此片段每次右键都会尝试增加 `10` 余额，没有限制领取次数。一次性奖励需要另行配置记录与条件。

扣款失败不会自动阻止后续发放物品或执行命令。交易菜单应先检查余额与购买资格，并配置拒绝提示；需要确保扣款与发放作为一笔完整交易完成时，应调用提供交易功能的插件命令。

## 物品操作

### 发放与扣除

`give-item` 发放物品，`take-item` 从玩家的背包储物格扣除符合条件的物品。它们使用 `属性:值`，多个属性以逗号分隔：

```yaml
backend:
  item-area:
    x: 0
    y: 0
    width: 80
    height: 24
    actions:
      right:
        - 'give-item: material:DIAMOND,amount:1,name:&bMenu Reward'
      shift-right:
        - 'take-item: material:DIAMOND,amount:1,name:&bMenu Reward'
```

普通右键发放一颗带名称的钻石，Shift+右键扣除一颗符合名称条件的钻石。这是操作示例，不包含购买、冷却或领取次数限制。

| 属性           | 用途                                        |
| ------------ | ----------------------------------------- |
| `material`   | 物品材质，例如 `DIAMOND` 或 `PLAYER_HEAD`。        |
| `amount`     | 数量，使用 `1` 至 `99` 的整数；省略时为 `1`。            |
| `name`       | 发放时设置显示名称；扣除时匹配名称中包含的文字，支持颜色代码。           |
| `lore`       | 发放时设置物品说明，使用 `\n` 分行；扣除时匹配某一行包含的文字。       |
| `model-data` | 自定义模型数据的整数值。                              |
| `data`       | 可损坏物品的损耗值，`0` 表示没有损耗。                     |
| `head`       | 玩家头颅对应的玩家名称；发放时配合 `material:PLAYER_HEAD`。 |

发放时应明确填写 `material`。扣除时，除 `amount` 外的属性共同决定哪些物品符合条件；数量可以从多个符合条件的物品堆中扣除。

多个物品规格可用分号分隔，例如 `give-item: material:DIAMOND,amount:1;material:EMERALD,amount:2`。属性值中的逗号和分号也会被当作分隔符，应避免用于名称或说明文字。

发放时背包无法容纳的物品会掉落在玩家所在位置。扣除只检查背包储物格，不包含穿戴装备与副手。

{% hint style="warning" %}
`take-item` 数量不足时，已经扣除的物品不会自动恢复，后续动作也不会自动停止。不要把它单独作为兑换资格检查。应先检查物品数量与条件；完整兑换可交由提供交易功能的插件处理。
{% endhint %}

### 修复与附魔

`repair-item: hand` 修复主手物品。`enchant-item: hand minecraft:unbreaking 3` 为主手物品添加三级耐久附魔。

两项动作的物品位置可使用：

| 位置                                       | 选择范围               |
| ---------------------------------------- | ------------------ |
| `hand`、`mainhand`                        | 主手物品。              |
| `offhand`                                | 副手物品。              |
| `armor`                                  | 当前穿戴的装备。           |
| `helmet`、`chestplate`、`leggings`、`boots` | 对应装备位置。            |
| `all`、`inv`                              | 玩家物品栏中的物品，包含装备与副手。 |

附魔参数依次为物品位置、附魔名称和等级。等级应为正整数；也可写范围，例如 `enchant-item: hand minecraft:unbreaking 1-3`，随机选择一级至三级。此动作允许超出正常附魔等级或物品适用范围，应由菜单作者确定允许的设置。

`reload-inventory` 刷新玩家物品栏显示，不会重新读取菜单文件，也不会补充或恢复物品。

## 聊天输入

`catcher` 用于接收玩家的下一条聊天输入。它使用嵌套配置，不能写成普通的 `catcher: 文字` 动作。目前仅支持 `type: CHAT`，不支持告示牌、铁砧或书本输入界面。

层级为：**点击类型 → 动作列表 → `catcher` → 阶段名称 → 阶段属性**。

```yaml
backend:
  input-area:
    x: 0
    y: 0
    width: 80
    height: 24
    actions:
      right:
        - catcher:
            nickname:
              type: CHAT
              start:
                - 'tell: &eEnter a nickname in chat, or type cancel.'
              cancel:
                - 'tell: &7Input cancelled.'
              end:
                - 'set-data: nickname {meta:input-nickname}'
                - 'tell: &aNickname saved: {data:nickname}'
```

### 阶段属性

| 属性       | 用途                           |
| -------- | ---------------------------- |
| `type`   | 输入方式，填写 `CHAT`；省略时也是 `CHAT`。 |
| `start`  | 开始等待本阶段输入时执行的动作。             |
| `cancel` | 玩家取消输入时执行的动作。                |
| `end`    | 收到正常输入后执行的动作。                |

`nickname` 是本例的阶段名称。可在 `catcher` 下配置多个阶段，按书写顺序逐一接收输入；每个阶段都有自己的提示和处理动作。

### 输入内容与取消

收到的内容可通过 `{meta:input}` 读取；指定阶段的输入通过 `{meta:input-阶段名称}` 读取，本例为 `{meta:input-nickname}`。这条聊天消息用于菜单输入，不会作为普通聊天广播。

玩家输入 `cancel`、`quit`、`end` 或 `q` 会取消流程并执行当前阶段的 `cancel`，这些词不区分大小写。关闭或切换菜单会结束等待，不会将其视为玩家提交取消词。

开始新的 `catcher` 会清除之前的 `input` 与 `input-...` 临时数据。需要保留的输入应在 `end` 中复制到自己的数据名称下，如上方示例的 `nickname`。

### 重新输入

在 `end` 中执行 `retype`，会重新开始当前阶段并再次执行 `start`。可配合条件对不合要求的输入发送提示，然后让玩家重新填写。

`retype` 不会立即停止其后的动作；应将保存有效结果与重新输入分别放入条件分支。`return` 用于结束输入处理流程，不应紧接在 `retype` 后作为重新输入的步骤。

聊天输入应作为数据处理。不要将未限制的输入直接拼接到 `console` 或 `op` 命令中；用于命令参数时，应先明确允许的内容。

## 检查与加载

修改后执行 `/arcmenu validate` 和 `/arcmenu reload`，再使用正常菜单检查数据写入、读取、物品数量及聊天输入。余额与点数应在对应插件已正常工作的服务器中核对实际变化。

配置检查可以检查动作结构，但不会替代交易条件或验证所有物品、附魔和第三方插件参数。条件写法见[条件](/arcmenu-wen-dang/cai-dan-pei-zhi/menus/conditions.md)。