> 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/wen-zi-ge-shi/text-placeholders.md).

# 占位符与文字格式

占位符可以把玩家的实时状态、打开菜单时传入的参数、保存的变量以及数学计算结果动态填入文字中。无论是前端文本节点、悬停提示框、动态图片路径，还是动作参数与条件判断，都可以使用同一套占位符与颜色格式。

## 内置玩家与偏好占位符

ArcMenu 原生提供以下玩家基础信息与个人指针偏好占位符，无需额外安装扩展即可直接使用：

| 占位符                                    | 说明                                                       |
| -------------------------------------- | -------------------------------------------------------- |
| `%player_name%`                        | 玩家名称。                                                    |
| `%player_uuid%`                        | 玩家的 UUID 字符串。                                            |
| `%player_world%`                       | 玩家当前所在的世界名称。                                             |
| `%player_x%`、`%player_y%`、`%player_z%` | 玩家当前坐标，自动保留两位小数。                                         |
| `%arcmenu_sensitivity%`                | 玩家个人的鼠标灵敏度倍率（保留最多四位小数，如 `1`、`1.4142`）。                   |
| `%arcmenu_sensitivity_level%`          | 玩家个人的鼠标灵敏度档位，范围 `1` 到 `9`（默认为 `5`）。                      |
| `%arcmenu_cursor_scale%`               | 玩家个人的光标缩放倍率（保留最多四位小数）。                                   |
| `%arcmenu_cursor_scale_level%`         | 玩家个人的光标缩放档位，范围 `1` 到 `9`（默认为 `5`）。                       |
| `%arcmenu_lang_<键名>%`                  | 读取当前玩家语言对应的多语言文本，例如 `%arcmenu_lang_samples.main.title%`。 |

指针偏好占位符同时支持别名 `%arcmenu_privatepointersensitivity%`、`%arcmenu_privatepointerscale%` 及其 `_level` 形式；当服务器安装了 PlaceholderAPI 时，这些偏好占位符也可以在其他插件中使用。

在前端文本、图片或后端提示框中，你可以通过 `update` 字段控制占位符的刷新频率：

```yaml
frontend:
  player-info:
    type: text
    content: '&f%player_name% &7位于 %player_world% (%player_x%, %player_z%)'
    size: 4
    update: 20
```

`update` 可填写 `-1` 或正整数（单位为服务端 Tick）：

* 填 `-1`（默认值）：仅在打开菜单或调用刷新接口时解析一次，平时保持静态。
* 填正整数（如 `20`）：每隔对应 Tick 自动重新解析占位符（`20` Tick 约为 1 秒）。

## 状态数据、菜单参数与会话绑定

ArcMenu 支持三类内置数据作用域、菜单位置参数，以及由附属插件提供的会话级绑定数据：

| 推荐花括号写法              | 百分号等价写法                                  | 简写别名                  | 内容说明                                 |
| -------------------- | ---------------------------------------- | --------------------- | ------------------------------------ |
| `{meta:键名}`          | `%arcmenu_meta_键名%`                      | `{m:键名}`              | 玩家的临时内存数据，在显式删除或服务器关闭/重启后清空。         |
| `{data:键名}`          | `%arcmenu_data_键名%`                      | `{d:键名}`              | 玩家的持久化数据，保存在存档或数据库中。                 |
| `{globaldata:键名}`    | `%arcmenu_globaldata_键名%`                | `{gdata:键名}`、`{g:键名}` | 全服共享的持久化数据。                          |
| `{0}`、`{1}`、`{2}`... | `%arcmenu_args_0%`、`%arcmenu_args_1%`... | —                     | 打开菜单时传入的第 1 个、第 2 个位置参数（从 `0` 开始编号）。 |
| `{session:命名空间:键名}`  | —                                        | —                     | 附属插件通过 API 绑定到当前精确会话的数据。             |

### 参数与输入值的读取规则

* **菜单参数**：当使用动作 `open: world-info survival hard` 打开菜单时，`{0}` 的值为 `survival`，`{1}` 的值为 `hard`。在菜单内部也可以通过 `set-args` 动作修改当前参数列表。如果引用了未传入的位置参数，花括号写法 `{2}` 会保留原样，而 `%arcmenu_args_2%` 会返回 `null`。
* **状态数据默认值**：当读取尚未设置的 `meta`、`data` 或 `globaldata` 键名时，解析结果为字符串 `null`。写入与删除这些数据的方法请参考[进阶动作](/cai-dan-pei-zhi/menus/advanced-actions.md)。
* **文本输入结果**：使用聊天捕获器（`catcher`）输入后，可通过 `{meta:input}` 或 `{meta:input-阶段ID}` 读取；使用 [Arcitx 文本输入](/gong-neng-pei-zhi/arcitx.md)提交后，可通过 `{meta:input}` 或 `{meta:input-编辑区ID}` 读取。

## PlaceholderAPI 扩展支持

当服务器安装了 PlaceholderAPI 并加载了对应的扩展（Expansion）后，你可以在菜单文本、提示框、条件和动作中直接使用任何第三方插件的占位符，例如经济余额 `%vault_eco_balance%`、点券 `%playerpoints_points%` 或等级属性。

除了文本内容外，前端的动态图片路径与物品头颅材质同样支持占位符替换：

* 动态图片：`source: '/ranks/%vault_rank%.png'`（引用的占位符结果需构成合法的小写相对路径）。
* 玩家头颅：`material: '<head:%player_name%>'`。

## 数学计算占位符 `{math: ...}`

当需要在界面上实时展示价格汇总、折扣换算或属性加成时，可以使用 `{math: 表达式}` 进行数值计算：

```yaml
frontend:
  total-price:
    type: text
    content: '&f折后总价：&e{math: round({meta:amount} * 24 * 0.95, 2)} 金币'
    size: 4
    update: 20
```

### 解析顺序与使用要点

1. **先展开变量，再执行计算**：ArcMenu 会先将表达式内部的 `{session:...}`、语言占位符、`{meta:...}`/`{data:...}`、菜单参数 `{0}`、内置玩家占位符以及 PlaceholderAPI 占位符替换为实际文本，然后再计算 `{math: ...}`。
2. **支持嵌套**：计算占位符可以多层嵌套，内层的 `{math: ...}` 会先算出结果并代入外层表达式。
3. **输出格式**：计算结果会自动去除小数末尾多余的 `0`，并以最多 15 位有效数字输出（例如 `3 * 24.0` 输出为 `72`）。
4. **确保变量已初始化为有效数字**：未设置的 `{meta:amount}` 会被解析为 `null`，导致数学表达式无法求值并保留原始文本。建议在打开菜单的入口动作或菜单的 `events.open` 中先赋予初始数值（例如 `set-meta: amount 1`）。

在动作中写入数据或执行命令时同样可以使用 `{math: ...}`。例如 `set-meta: total 3 * 24` 会把字面字符串 `3 * 24` 存入变量，而 `set-meta: total {math: 3 * 24}` 才会存入计算后的结果 `72`。完整的运算符与函数列表请参考[数学表达式](/cai-dan-pei-zhi/menus/math-expressions.md)。

## 颜色代码与文字样式

菜单中的文字支持传统 `&` 颜色格式码以及十六进制 RGB 颜色码：

| 写法                        | 效果说明                                                           |
| ------------------------- | -------------------------------------------------------------- |
| `&0` \~ `&9`、`&a` \~ `&f` | 标准 Minecraft 16 色（例如 `&f` 白色、`&7` 灰色、`&a` 绿色、`&e` 黄色、`&c` 红色）。 |
| `&#RRGGBB`                | 自定义十六进制 RGB 颜色，例如 `c73ff`（6 位十六进制字符）。                       |
| `&l`                      | **粗体**。                                                        |
| `&o`                      | *斜体*。                                                          |
| `&n`                      | 下划线。                                                           |
| `&m`                      | ~~删除线~~。                                                       |
| `&k`                      | 随机跳动字符。                                                        |
| `&r`                      | 重置当前位置之后的颜色与字体样式。                                              |

```yaml
content: 'c73ff&l欢迎来到服务器！ &r&7请选择下方的一项功能。'
```

### 字体与其他元素的颜色格式

* **自定义字体**：在前端 `text` 节点中设置 `font: 命名空间:路径`（默认为 `minecraft:default`）。只要客户端加载的资源包中包含该字体定义即可生效。文本的字号、对齐方式与自动换行宽度配置见[前端元素类型](/cai-dan-pei-zhi/menus/frontend.md)。
* **几何图形与图片着色**：
  * 前端 `rectangle`、`line`、`frame` 的 `color` 字段填写带引号的 6 位十六进制颜色 `'#RRGGBB'`（如 `'#182031'`），透明度通过独立的 `opacity`（`0` 到 `255`）设置。
  * 前端 `image`、`gif` 的可选染色字段 `color` 支持 `'#RRGGBB'` 或 `'&#RRGGBB'`，不透明度同样使用 `opacity`（`0` 到 `255`）。
  * `tooltip.yml` 中的普通提示框背景色与边框色使用带 Alpha 通道的 8 位十六进制格式 `'#AARRGGBB'`。
* **富文本聊天消息**：如果你需要在点击按钮后向聊天栏发送带点击事件或悬停提示的富文本消息，可以在动作中使用 `tellraw: <JSON文本>`。


---

# 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/wen-zi-ge-shi/text-placeholders.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.