> 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/pei-zhi-yu-guan-li/configuration-files.md).

# 配置文件说明

ArcMenu 的所有配置、菜单、资源和自动生成内容都存放在 `plugins/ArcMenu/` 目录下。了解这些文件和文件夹的分工，在日常修改设置、管理资源或备份项目时会轻松很多。

## 目录结构

| 文件或目录                | 用途                                                    |
| -------------------- | ----------------------------------------------------- |
| `config.yml`         | 全局配置文件，管理语言、快捷键、输入模式、光标参数、客户端播放优化、菜单市场及版本检查。          |
| `offset.yml`         | 控制触控模式与 Mouse/Vision 模式下的全局屏幕距离和坐标偏移。                 |
| `menus/`             | 存放所有菜单的 YAML 配置文件，包含前端画面元素、后端点击区域和交互动作。               |
| `images/`            | 存放菜单使用的 PNG 图片、GIF 动图、鼠标光标贴图（`images/mouse/`）和提示框背景图。 |
| `templates/`         | 存放可在多个菜单中复用的前端组件模板。                                   |
| `animations.yml`     | 配置普通菜单的进入、切换、退出过渡，以及内部元素的动画轨道。                        |
| `animations/`        | 存放通过 ArcPack 菜单包安装的独立菜单动画文件。                          |
| `tooltip.yml`        | 配置悬浮提示框（Tooltip）的尺寸、边距、位置与九宫格背景外观。                    |
| `languages/`         | 存放插件提示与示例文本的语言文件。                                     |
| `effects/`           | 存放 Effect 过场动画的场景配置和时间线文件。                            |
| `effects/assets/`    | 存放 Effect 播放时使用的 OGG 音频与 NBS 音乐文件。                    |
| `packs/`             | 存放本地导入或下载的 `.arcpack` 包文件及安装记录。                       |
| `backup-menu/`       | 使用可视化编辑器保存菜单前自动生成的历史备份。                               |
| `workspace-backups/` | 在项目管理器中执行导入、安装或删除等操作时自动生成的工作区备份。                      |
| `generated/`         | 插件自动生成的资源包文件（如手动分发所用的 ZIP 包）。                         |

## 核心配置（config.yml）

`config.yml` 集中了插件运行时的各项全局设置。你可以按模块查看并填写对应的值。

### 语言与快捷键

```yaml
language:
  default: zh_CN
  follow-player-locale: true

shortcuts:
  shift-f: true
  close-on-shift-f: true
  close-on-space: true
```

* **`language.default`**：填写 `plugins/ArcMenu/languages/` 下对应的语言文件名（不含扩展名），默认值为 `zh_CN`，内置支持 `zh_CN` 和 `en_US`。控制台日志以及未匹配到客户端语言时的提示都会使用这里设置的语言。
* **`language.follow-player-locale`**：可填 `true` 或 `false`。设为 `true` 时，插件发给玩家的消息会自动匹配玩家客户端当前使用的语言。
* **`shortcuts.shift-f`**：可填 `true` 或 `false`。设为 `true` 时，玩家在未打开界面时按 Shift+F（潜行+副手交换键）可直接打开设置了 `main-menu: true` 的主菜单。
* **`shortcuts.close-on-shift-f`**：可填 `true` 或 `false`，默认 `true`。控制玩家在打开普通菜单或第三方应用时，能否按 Shift+F 将其关闭。这个开关与 `shift-f` 相互独立，即使关闭了 Shift+F 打开主菜单，依然可以保留按 Shift+F 退出界面的操作。
* **`shortcuts.close-on-space`**：可填 `true` 或 `false`，默认 `true`。控制按跳跃键（默认为空格键 Space）是否关闭当前运行的菜单或应用。

两个关闭快捷键只作用于普通的运行期菜单和应用，不会打断可视化编辑器、Arcitx 文本输入或 Effect 过场动画的正常操作。

### 输入模式与鼠标光标

```yaml
mouse:
  policy: player-choice
  default: touch
  assume-resource-pack-loaded: true
  sample-rate: 40
  cursor:
    interpolation-ticks: 0
    sensitivity-x: 2.0
    sensitivity-y: 2.0
    clamp-margin: 3.0
    size: 5.0
    z: 5.0
```

* **`mouse.policy`**：控制服务器允许的交互方式。可填写以下三个值：
  * `player-choice`：允许玩家通过 `/arcmenu mode` 自行在 `touch`、`mouse` 和 `vision` 之间切换（同时兼容旧配置名 `crosshair` 和 `cursor`）。
  * `force-touch`：全服固定使用触控模式（兼容旧名 `force-crosshair`）。
  * `force-mouse`：强制使用光标操作（兼容旧名 `force-cursor`），支持 Mouse 模式，也允许安装了配套 ArcMenu Editor 模组的玩家启用 Vision 模式。
* **`mouse.default`**：玩家首次进入服务器、尚未主动切换模式时的默认操作方式，可填 `touch`、`mouse` 或 `vision`。其中 Vision 需要玩家在客户端安装对应游戏版本的 ArcMenu Editor 模组。
* **`mouse.assume-resource-pack-loaded`**：布尔值，可填 `true` 或 `false`，默认 **`true`**。
  * 设为 **`true`** 时，插件默认信任客户端已经安装了配套的 ArcMenu 资源包，无需等待服务端收到资源包加载成功的回执，就会直接启用 Mouse 模式的平面光照、菜单深度、固定 FOV、客户端本地光标以及符合条件的本地 GIF 播放。这非常适合让玩家把生成的资源包当成本地材质包手动放进客户端使用。
  * 设为 **`false`** 时，插件会严格等待服务端确认资源包加载成功后再启用上述 Mouse 特性；如果在菜单运行期间发现资源包未就绪，依赖这些特性的 Mouse 菜单会安全关闭，待加载完成后重新打开即可。
  * 无论设为哪个值，客户端都需要实际安装匹配的 ArcMenu 资源包。这个开关只作用于 Mouse 模式，不会影响触控模式、Vision 模式、编辑器的独立预览或 Effect 播放。
* **`mouse.cursor.sensitivity-x` / `sensitivity-y`**：填写 `0.05` 到 `50` 之间的数字，默认均为 `2.0`，分别控制鼠标光标在水平和垂直方向的基础移动灵敏度。
* **`mouse.cursor.clamp-margin`**：填写大于或等于 `0` 的数字（默认 `3.0`），控制光标在画布边缘允许活动的边界余量。
* **`mouse.cursor.size`**：填写正数（默认 `5.0`），控制光标在画布上的逻辑高度。光标贴图固定读取 `images/mouse/mouse.png`（默认状态）与 `images/mouse/choose.png`（悬停可点击区域状态）。
* **`mouse.cursor.z`**：填写数字（默认 `5.0`），控制光标所在的 Z 轴图层深度，确保光标显示在菜单元素前方。
* **`mouse.sample-rate`** 与 **`mouse.cursor.interpolation-ticks`**：供未使用本地光标的旧版发包光标使用。`sample-rate` 填写 `20` 到 `60` 之间的整数（默认 `40`），控制每秒采样次数；`interpolation-ticks` 填写 `0`、`1` 或 `2`（默认 `0`），控制插值平滑帧数。当前主流的本地光标与 Vision 光标直接在客户端即时渲染，不需要轮询发包。

### 客户端播放与菜单市场

```yaml
client-playback:
  local-gifs: true
  linear-offsets: true

marketplace:
  url: 'https://market.myarc.icu:10051'
  certificate-sha256: ''
```

* **`client-playback.local-gifs`**：可填 `true` 或 `false`，默认 `true`。开启后，Mouse 模式下符合条件的 GIF 动图会直接利用客户端原生动态材质播放，播放期间服务端实现 0 发包。
* **`client-playback.linear-offsets`**：可填 `true` 或 `false`，默认 `true`。开启后，动画时间线中符合条件的线性位移片段会交给客户端原版展示实体插值处理，画面更顺滑且节省网络带宽。
* **`marketplace.url`**：填写菜单市场的 HTTPS 地址（默认 `'https://market.myarc.icu:10051'`），供可视化编辑器浏览市场以及服务端下载 ArcPack 使用。如果留空 `''`，则会关闭远程市场请求；本地开发调试时也支持填写 `http://127.0.0.1:<端口>`。
* **`marketplace.certificate-sha256`**：使用自建私有 HTTPS 市场且未配置公共 CA 证书时，可在此填写证书的 SHA-256 指纹；使用默认官方市场时保持留空 `''` 即可。

关于这些功能的更多细节，可以延伸阅读[触控、鼠标与 Vision 输入](/gong-neng-pei-zhi/input-modes.md)、[GIF 动图](/gong-neng-pei-zhi/gif.md)和[ArcPack 与菜单市场](/gong-neng-pei-zhi/arcpack.md)。

### 用量统计与版本更新提醒

```yaml
metrics:
  enabled: true

update-check:
  enabled: true
  url: 'https://market.myarc.icu:10051/arcmenu/updates/premium.json'
  notify-on-join: true
```

* **`metrics.enabled`**：可填 `true` 或 `false`，默认 `true`。用于控制是否开启 bStats 匿名统计（付费版服务 ID 为 **34690**，社区版为 **34691**）。服务器全局的 `plugins/bStats/config.yml` 开关同样会生效。
* **`update-check.enabled`**：可填 `true` 或 `false`，默认 `true`。开启后，服务端会在后台定期（默认每 6 小时）读取公开的版本清单，检查是否有新版本发布。更新检查只对比并提醒版本号，不会自动下载或替换插件文件。
* **`update-check.url`**：填写版本清单的 JSON 地址，保持默认即可。
* **`update-check.notify-on-join`**：可填 `true` 或 `false`，默认 `true`。开启后，当检测到新版本时，拥有 `arcmenu.admin` 权限的管理员进入服务器会收到版本提醒。管理员也可以随时通过 `/arcmenu update` 手动触发检查。

## 让修改生效与资源重建

在可视化编辑器中点击保存时，修改后的菜单会自动应用并更新到服务器。如果你是手动编辑了 YAML 菜单文件、`animations.yml` 或 `config.yml`，保存文件后执行 `/arcmenu reload` 即可生效。

如果新增或修改了 `images/` 中的图片、GIF、提示框贴图、光标设置或模板文件，则需要重新生成资源包：

1. 先执行 `/arcmenu resources` 或 `/arcmenu reload all` 重建 ArcMenu 资源。
2. 如果服务器安装了自定义物品插件，接着按你所使用的插件执行对应的打包重载命令：
   * **CraftEngine**：执行 `/ce reload pack`（或 `/ce reload all`）
   * **Nexo**：执行 `/nexo reload pack`
   * **ItemsAdder**：执行 `/iazip`
3. 如果没有使用上述插件，可以直接从 `plugins/ArcMenu/generated/` 目录中获取生成的资源包 ZIP 文件进行分发。

## 配置自动补全与首次安装默认文件

插件启动或重载时，会自动检查 `config.yml`。如果版本升级带来了新的配置项，插件会在不改动你现有配置值（包括显式填写的 `false`、`0`、空字符串或空列表）、自定义键和原有注释的前提下，自动把缺失的默认字段补齐。

首次安装 ArcMenu Premium 时，插件会自动释放一套开箱即用的默认菜单与示例资源，包括主菜单 `main`、引导菜单 `start`、个人光标与灵敏度设置菜单 `cursor-setting`、完整的 `shop/` 商店分类菜单、传送菜单 `teleport`，以及 `rtp-overworld`、`rtp-nether` 和 `rtp-end` 三个随机传送 Effect 过场动画示例，同时配套提供 `images/arcmenu.gif` 引导动图和 `animations.yml` 轨道。默认菜单中的文本通过 `%arcmenu_lang_samples.<键名>%` 引用语言文件，会自动跟随服务器和玩家的语言设置切换中英文。两张鼠标光标贴图则会作为基础运行资源一直保留。

这套示例资源只在第一次初始化安装时释放。如果你在后续使用中删除了不需要的示例菜单、图片、模板或动画，重启、重载或升级插件时都会尊重你的改动，不会把已删除的示例文件重新恢复出来。


---

# 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/pei-zhi-yu-guan-li/configuration-files.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.