安装与启动

本页面面向服主和管理员，说明 ItemMaster 的基础部署流程，以及首次启动后应该检查什么。

安装前确认

• 服务端核心建议使用 Paper 或兼容的 Spigot 生态核心。
• Java 版本、Minecraft 版本要和你的整服环境统一。
• 如果要用到 MythicMobs、NeigeItems、PlaceholderAPI、Vault、CraftX、LyShop、SoulRingX、LyWarehouse 等联动，先把这些前置插件装好。
• 第一次部署建议先在测试服跑通，再上正式服。

安装步骤

1. 停止服务器。
2. 将 ItemMaster 插件文件放入 plugins/ 目录。
3. 启动服务器，等待插件自动生成默认配置与示例文件。
4. 检查控制台，确认没有缺依赖、版本不兼容或配置读取失败的报错。
5. 关闭服务器后再修改配置，首次建议优先确认 config.yml 与 recipes/ 目录是否已正常生成。

首次启动后会生成什么

plugins/ItemMaster/
├── config.yml             # 主配置
├── recipes/               # 配方（GUI 配置）目录
│   ├── enhance.yml        # 示例：强化
│   ├── reforge.yml        # 示例：洗练
│   ├── forge.yml          # 示例：锻造
│   └── devour.yml         # 示例：吞噬
├── modules/               # 可复用的配置模块
│   ├── gui/               # GUI 布局模块
│   ├── logic/             # 逻辑模块
│   └── effects/           # 效果模块
├── offline-sessions/      # 离线会话数据（插件自动维护）
│   └── {玩家UUID}.yml
├── vault/                 # 物品存储库
└── docs/                  # 文档目录

如果以上目录没有生成，优先检查：

• 插件是否真的启用成功。
• 文件写入权限是否足够。
• 编码或路径中是否有异常字符。

配方文件规则

recipes/ 目录下每个 .yml 文件就是一个配方，文件名即配方 ID：

recipes/enhance.yml   →  配方 ID: enhance
recipes/reforge.yml   →  配方 ID: reforge
recipes/子目录/abc.yml →  配方 ID: abc

后续在玩家命令、外部触发或 effect.open("xxx") 中都使用这个 ID。

建议的接入顺序

推荐按下面的顺序完成接入：

1. 先让默认的示例配方能正常打开。
2. 复制示例配方改成自己的 GUI，把标题、布局改成你需要的样子。
3. 补齐 match 匹配条件，让正确的物品能放进来。
4. 加上 conditions 前置检查和 execute 主脚本。
5. 最后再叠加预览槽位、onchange 实时反馈、模块复用与外部联动。

首次检查清单

• 能通过配置的命令或绑定入口打开 GUI。
• 玩家放入物品时匹配提示正确。
• 按钮点击能触发脚本，消息正常回显。
• 消耗的材料、金币和物品数量正确。
• 关闭 GUI 时未锁定的物品会全部归还玩家背包。
• 如果使用了 session_timeout > 0，玩家重新打开 GUI 能看到正确的后台状态。

常见启动问题

启动后没有生成目录

先看控制台报错。常见原因：

• 插件并没有真正加载成功（被前置插件阻断，或版本不兼容）。
• 数据目录没有写入权限。
• 文件系统编码异常导致中文目录生成失败。

GUI 打开立刻报错 / 布局错乱

• 先检查 rows 的值：必须在 1–6 之间。
• layout 每行必须是 9 个字符。
• slots 中用到的字符必须是 layout 里出现过的字符。
• 如果键是纯数字（如 1、2），在 YAML 中必须加引号："1": ...。

匹配总是不通过

• 复制一行装备 Lore 到 match 里的 lore.contains('...')，注意不要带颜色码。
• 如果 lore 中带冒号或特殊字符，请参考 YAML 注意事项。
• 可以在 onchange 里加一行 effect.message("debug: " + @input.type) 来验证物品是否真的进入了对应槽位。

物品莫名其妙丢了

• 先确认槽位是否被 slot.lock 锁住——锁定槽位不会归还物品，这是抽奖转盘等动画场景的预期行为，但配错了容易误伤玩家装备。
• 如果开启了 session_timeout > 0，玩家关闭 GUI 后物品会保留到下次打开或超时。
• 服务器崩溃（kill -9）会导致内存中未持久化的物品丢失，贵重物品请用 vault.store 存入物品库。

更多崩溃/服务器重启场景下的物品归还行为见 会话与物品安全。