原创 工具 [1.12~1.21] 墨菜单 | 支持游戏内GUI编辑的菜单插件 1.0.0

[MD] ### 🎮 插件交流群 [/MD]
点击加入【墨系列插件交流群】

[MD] # 墨菜单 MoMenu 使用手册 墨菜单（MoMenu）插件，支持可视化编辑与 YAML 配置两种方式创建多页菜单。提供指令执行、菜单跳转、延时关闭等点击动作，支持 PlaceholderAPI 变量解析与快捷打开物品，兼容 1.12 ~ 1.21.x 全版本。 --- ## 1. 兼容版本 | 版本 | 状态 | 说明 | |------|------|------| | 1.12.2 | ✅ 完全兼容 | 编译目标版本，原生支持 | | 1.13 ~ 1.21.x | ✅ 完全兼容 | 内置材质自动映射，无需手动修改配置 | > 配置文件**统一使用 1.12 材质名**，插件运行时自动转换为当前服务器版本的正确材质。无论在哪个版本之间迁移，配置文件无需修改。 --- ## 2. 安装 1. 将 `MoMenuPlugin-1.0.0.jar` 放入服务器的 `plugins/` 目录 2. 启动服务器，插件会自动生成 `plugins/MoMenu/` 目录及默认配置文件 3. （可选）安装 [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) 以启用变量解析 安装后的目录结构： ``` plugins/MoMenu/ ├── config.yml # 主配置文件 ├── menu/ │ ├── main.yml # 默认主菜单 │ └── teleport.yml # 默认传送菜单 └── (自定义菜单).yml ``` --- ## 3. 命令 | 命令 | 说明 | 权限 | |------|------|------| | `/mmenu` | 查看帮助 | `mmenu.use` | | `/mmenu open <菜单名> [玩家]` | 打开指定菜单 | `mmenu.use` / `mmenu.admin` | | `/mmenu create <菜单名> <行数>` | 创建新菜单并进入编辑模式 | `mmenu.admin` | | `/mmenu list` | 列出所有已加载菜单 | `mmenu.use` | | `/mmenu reload` | 重载所有配置文件 | `mmenu.admin` | 别名：`/mm`、`/menu` --- ## 4. 权限 | 权限节点 | 说明 | 默认 | |----------|------|------| | `mmenu.use` | 使用菜单相关命令 | 所有人 | | `mmenu.admin` | 管理菜单（创建、重载、为他人打开） | OP | | `mmenu.open.<菜单名>` | 打开指定菜单的权限 | OP | --- ## 5. 菜单配置文件 菜单配置存放在 `plugins/MoMenu/menu/` 目录下，每个 `.yml` 文件对应一个菜单，文件名即为菜单名。 ### 5.1 基本结构 ```yaml # 菜单标题（显示在 GUI 顶部，支持颜色代码 &） title: "&8&l我的菜单" # 菜单行数（1 ~ 6） rows: 3 # 占位物品（没有放置按钮的空白格子显示什么） placeholder: material: STAINED_GLASS_PANE # 材质名 name: "&7" # 显示名称 lore: # 物品描述 - "&8装饰" # 按钮配置 buttons: "<槽位号>": material: DIAMOND # 材质名 amount: 1 # 数量 name: "&b&l按钮名称" # 显示名称 lore: # 物品描述（支持多行） - "&7第一行描述" - "&7第二行 &a%player_name%" click-actions: # 点击后执行的动作 - type: command # 动作类型 value: "say 你好！" # 动作参数 op: false # 是否以 OP 身份执行 async: true # 是否异步执行 ``` ### 5.2 槽位编号 GUI 槽位从 **0** 开始计数，按行排列： ``` 第一行: 0 1 2 3 4 5 6 7 8 第二行: 9 10 11 12 13 14 15 16 17 第三行: 18 19 20 21 22 23 24 25 26 第四行: 27 28 29 30 31 32 33 34 35 第五行: 36 37 38 39 40 41 42 43 44 第六行: 45 46 47 48 49 50 51 52 53 ``` ### 5.3 点击动作 支持三种动作类型，可同时配置多个（按顺序依次执行）： #### 1. command — 执行指令 ```yaml click-actions: - type: command value: "say 你好 %player_name%" op: false # true = 以 OP 身份执行 async: true # true = 关闭菜单后异步执行（适合打开其他插件 GUI） ``` #### 2. open-menu — 打开其他菜单 ```yaml click-actions: - type: open-menu value: "teleport" # 目标菜单名 async: false ``` #### 3. close — 关闭菜单 ```yaml click-actions: - type: close value: "" async: false ``` #### 关于 `async` 参数 - **`async: false`** — 同步执行，菜单保持打开状态，适合发送消息、给自己指令等 - **`async: true`** — 异步执行，先关闭菜单，延迟 1 tick 后执行，适合打开其他插件的 GUI（避免菜单冲突） #### 关于 `op` 参数 - **`op: true`** — 临时授予 OP 权限后执行，执行完毕后恢复原权限状态 - **`op: false`** — 以玩家自身身份执行 ### 5.4 材质命名规范 配置文件**统一使用 1.12 材质名**，插件会自动适配当前服务器版本： | 1.12 材质名（在 YAML 中使用） | 1.13+ 自动映射为 | |------------------------------|-----------------| | `STAINED_GLASS_PANE` | `BLACK_STAINED_GLASS_PANE` | | `GRASS` | `GRASS_BLOCK` | | `BOOK_AND_QUILL` | `WRITABLE_BOOK` | | `INK_SACK` | `INK_SAC` | | `WORKBENCH` | `CRAFTING_TABLE` | | `ENDER_STONE` | `END_STONE` | | `ENCHANTMENT_TABLE` | `ENCHANTING_TABLE` | | `WOOD` | `OAK_PLANKS` | | `LEAVES` | `OAK_LEAVES` | | `LOG` | `OAK_LOG` | | ... | （共 100+ 条映射） | > 也可以直接使用 1.13+ 的材质名（如 `DIAMOND`、`STONE` 等未在扁平化中改名的材质），两种命名均可正确识别。 --- ## 6. 主配置文件 主配置文件 `config.yml` 位于 `plugins/MoMenu/` 下。 ### 6.1 快捷打开物品 玩家手持指定物品右键即可打开菜单，无需输入指令： ```yaml quick-open: enabled: true # 是否启用快捷打开 items: - material: DIAMOND # 手持物品材质 name: "&b菜单" # 物品显示名称（可选，不填则只看材质） lore: # 物品描述（可选） - "&7右键打开菜单" menu: "main" # 目标菜单名 async: false # 是否异步打开 ``` 可以配置多个物品，配合不同的 `name` / `lore` 区分，绑定到不同菜单。 --- ## 7. PlaceholderAPI 支持 安装 PlaceholderAPI 后，以下位置自动支持变量解析： - 菜单标题（`title`） - 占位物品 (`placeholder`) 的 `name`、`lore` - 按钮的 `name`、`lore` - 点击动作中 `command` 的 `value` **无需任何额外配置**，插件启动时自动检测。常用 PAPI 变量示例： ``` %player_name% 玩家名 %player_health% 生命值 %player_level% 等级 %server_online% 在线人数 %server_tps_1% 服务器TPS %player_world% 玩家所在世界 ``` --- ## 8. 创建菜单 ### 8.1 命令创建 + 可视化编辑 ``` /mmenu create demo 3 ``` 执行后： 1. 自动生成 `plugins/MoMenu/menu/demo.yml` 配置文件 2. 打开一个空白编辑界面（3行） 3. 将背包中的物品拖入 GUI 对应槽位 4. 关闭 GUI 自动保存物品配置 ### 8.2 手动配置点击效果 编辑保存后，需要手动打开配置文件添加 `click-actions`： ```yaml buttons: "11": material: DIAMOND amount: 1 name: "&b&l示例按钮" lore: [] click-actions: - type: command value: "say 点击了按钮" op: false async: false ``` 保存后执行 `/mmenu reload` 即可生效。 --- ## 9. 完整示例 ### 主菜单 `main.yml` ```yaml title: "&8&l墨菜单 - 主菜单" rows: 3 placeholder: material: STAINED_GLASS_PANE name: "&7" lore: [] buttons: "0": material: DIAMOND amount: 1 name: "&b&l玩家信息" lore: - "&7点击查看玩家信息" - "&7在线人数: &a%server_online%" click-actions: - type: command value: "say 玩家 %player_name% 查看了信息" op: false async: true "1": material: COMPASS amount: 1 name: "&e&l传送菜单" lore: - "&7点击打开传送菜单" click-actions: - type: open-menu value: "teleport" async: false "13": material: GRASS amount: 1 name: "&a&l服务器状态" lore: - "&7TPS: &a%server_tps_1%" - "&7在线: &e%server_online%" click-actions: - type: command value: "broadcast &e%player_name% 查看了服务器状态" op: true async: true "26": material: BARRIER amount: 1 name: "&c&l关闭" lore: - "&7点击关闭此菜单" click-actions: - type: close value: "" async: false ``` ### 传送菜单 `teleport.yml` ```yaml title: "&8&l墨菜单 - 传送菜单" rows: 3 placeholder: material: STAINED_GLASS_PANE name: "&7" lore: [] buttons: "10": material: ENDER_PEARL amount: 1 name: "&d&l随机传送" lore: - "&7点击随机传送" click-actions: - type: command value: "randomtp" op: false async: true "11": material: BOOK_AND_QUILL amount: 1 name: "&6&l领地传送" lore: - "&7点击传送至领地" click-actions: - type: command value: "warp home" op: false async: true "15": material: BEACON amount: 1 name: "&a&l出生点" lore: - "&7点击传送至出生点" click-actions: - type: command value: "spawn" op: false async: true "16": material: ARROW amount: 1 name: "&e&l返回主菜单" lore: - "&7点击返回" click-actions: - type: open-menu value: "main" async: false "26": material: BARRIER amount: 1 name: "&c&l关闭" lore: - "&7点击关闭" click-actions: - type: close value: "" async: false ``` --- ## 10. 常见问题 ### Q: 菜单显示一堆空气/物品不显示？ A: 检查 YAML 中的 `material` 材质名是否正确。建议使用 1.12 命名（如 `STAINED_GLASS_PANE` 而非 `BLACK_STAINED_GLASS_PANE`）。 ### Q: 点击按钮没反应？ A: 检查 `click-actions` 是否已配置。使用 `/mmenu create` 创建的菜单默认只有物品，需要手动编辑 YAML 添加点击动作。 ### Q: 打开其他插件菜单后冲突/黑屏？ A: 将 `async` 设为 `true`，这样会先关闭墨菜单再打开目标菜单。 ### Q: 某些指令需要权限执行不了？ A: 将对应点击动作的 `op` 设为 `true`，指令将以 OP 身份执行。 ### Q: PlaceholderAPI 变量无法解析？ A: 确保已安装 PlaceholderAPI 插件，重启服务器后生效。插件通过反射自动调用，无需额外依赖。 ### Q: 修改配置文件后不生效？ A: 执行 `/mmenu reload` 重载配置，或重启服务器。 ### Q: 如何在 1.13+ 服务器迁移旧配置文件？ A: 无需迁移。配置文件使用 1.12 材质名编写，插件会自动映射到当前服务器版本的材质。 [/MD]