AdvancedHelp - Custom /Help pages with GUI! - AdvancedHelp - 自定义帮助页面与GUI

AdvancedHelp 是一款完全可自定义的服务器帮助命令插件，能够替代默认的 /help 指令，为玩家提供清晰、美观且高度定制化的帮助信息。你可以创建分类、设计 GUI 界面，并支持多种扩展功能，让服务器的帮助系统焕然一新。

💡核心特性

• 无限页面与文本：创建任意数量的帮助页面和文本内容。
• 自定义分类：按主题（如 Factions、Skyblock）组织帮助信息。
• GUI 支持：创建美观的图形化帮助界面，支持无限数量的 GUI。
• 多版本兼容：支持 1.7 至最新版本。
• 扩展支持：支持 PlaceholderAPI (PAPI)、HeadDataBase、JSON 文本、十六进制颜色代码及多语言。
• BungeeCord 支持：集成 /server 命令。
• 智能标签补全：输入分类名时提供标签补全。
• 权限控制：可精细控制每个分类和 GUI 的访问权限。

🎮命令与权限

命令列表

• /help – 打开默认帮助信息。
• /help <页码> – 打开指定的帮助页码。
• /help <分类名> – 打开指定的帮助分类。
• /help <分类名> <页码> – 打开指定分类的特定页码。
• /help <GUI名称> – 打开指定的 GUI（需在设置中启用 cmd-priority.gui）。
• /ahelp reload – 重载插件配置。
• 注：也可使用 /? 或 /ehelp 作为 /help 的替代命令。

权限节点

• help.use – 允许玩家使用 /help 基础命令。
• help.reload – 允许管理员重载配置。
• help.<分类名> – 允许玩家查看特定分类（仅当该分类的 default 设为 false 时需要）。
• help.<GUI名> – 允许玩家查看特定 GUI（仅当该 GUI 的 default 设为 false 时需要）。
• help.override – 使用 /? 时显示 Bukkit 原版帮助而非 AdvancedHelp 帮助。

🔧GUI 界面详解

运行类型 (Run Types)

GUI 中的每个物品都可以执行不同的操作，通过 run 字段定义：

• GUI – 打开另一个 AdvancedHelp GUI。

  run: GUI
  value: <gui名称>

• CATEGORY – 显示一个 AdvancedHelp 分类。

  run: CATEGORY
  value: <分类名> <可选页码>

• PAGE – 显示一个 AdvancedHelp 帮助页面（页码）。

  run: PAGE
  value: <页码>

• MESSAGE – 向玩家发送消息（支持多行、JSON、PAPI、HEX）。

  run: MESSAGE
  value:
    - "第一行消息"
    - "第二行消息"

• PLAYER-CMD – 以玩家身份执行命令。

  run: PLAYER-CMD
  value:
    - "feed"

• CONSOLE-CMD – 以控制台身份执行命令。

  run: CONSOLE-CMD
  value:
    - "heal %player%"

• COSMETIC – 仅作装饰，无功能。

  run: COSMETIC

• SERVER – 执行 BungeeCord 的 /server 命令。

  run: SERVER
  value: <服务器名称>

物品材质说明

• 1.12 及以下版本：必须使用 1.13+ 的方块 ID 名称（如 polished_granite），不能使用数字 ID（如 1:2）。无效材质将显示为 BARRIER。
• 玩家头颅：
• 显示当前查看 GUI 的玩家头颅：item-material: PLAYER
• 显示指定玩家头颅：item-material: PLAYER[玩家名]
• HeadDataBase 支持：若安装了 HeadDataBase，可使用 item-material: HDB[物品ID] 来使用其中的头颅。
• 多槽位物品：一个物品可占据多个槽位。

  item-slot: [1,2,5,6]

私有 GUI

将 GUI 的 default 设为 false 可使其变为私有，玩家需要权限 help.<GUI名> 才能打开。

gui:
  factions:
    title: '&c&lFactions Help'
    slots: 45
    default: false
    # 玩家需要 help.factions 权限才能打开

✨分类配置

分类用于组织文本帮助信息，配置于 categories.yml。

创建分类

• 在 categories.yml 中按格式创建分类。
• 分类名应保持小写。
• 设置 default: true 允许所有玩家访问，设为 false 则需权限 help.<分类名>。

**格式示例**

categories:
  factions:
    default: true
    1:
      - "&e&m---&e Factions Help &e&m---"
      - "  第一行帮助文本"
      - "  支持所有颜色和样式代码 &l&n等"
    2:
      - "&e&m---&e Factions Help Page2 &e&m---"
      - "  第二页内容"
  skyblock:
    default: true
    1:
      - "这是 Skyblock 分类的帮助内容"

重要：确保每页下的行对齐，避免 YAML 格式错误。

⭐占位符与 JSON 支持

内置占位符

• %player% – 玩家名称。
• %time% – 当前时间（格式可在 settings.yml 中设置）。

PlaceholderAPI (PAPI)

• 安装 PlaceholderAPI。
• 下载所需的扩展：/papi ecloud download <扩展名>。
• 重载 PAPI：/papi reload。
• 在 AdvancedHelp 的任何文本中使用 %placeholder% 格式的占位符。

JSON 文本

支持 JSON 格式的交互式聊天文本（可点击、悬停、改变样式等）。在配置中写入 JSON 时，需在引号前添加反斜杠 \ 进行转义。

**示例**

- " {\"text\":\"点击访问网站\",\"color\":\"green\",\"clickEvent\":{\"action\":\"open_url\",\"value\":\"https://example.com\"}}"

❓配置文件示例

help.yml

pages:
  '1':
    - '第一页内容'
    - '{"text":"支持 JSON 文本"}'
  '2':
    - "第二页内容"

categories.yml

categories:
  example:
    default: true
    '1':
      - '这是一个示例分类'

settings.yml

messages:
  category-not-found: '&b未找到该分类！'
  page-not-found: '&b未找到该页面！'
  no-permission: '&c你没有权限执行此操作！'
  prefix: '&7[&bAdvancedHelp&7]'
dateFormat: HH:mm:ss dd-MM-yyyy
gui:
  enabled: true
  hide-attributes: true
  close-page:
    enabled: true
    item-name: '&c&l关闭'
    item-material: BARRIER
  home-page:
    enabled: true
    item-name: '&c&l返回主页'
    item-material: BARRIER
cmd-priority:
  gui: true
  refresh-guis: false

gui.yml

详细示例请参考插件文档中的完整 gui.yml 示例，其中定义了多个 GUI 及其物品、槽位和操作。

🔧常见问题 (FAQ)

• Q: CMI 与 AdvancedHelp 冲突？
• A: 目前需在 CMI 中创建自定义别名，将 /ehelp 映射为 /help。首先尝试在服务器中使用 /ehelp，若可行则设置别名；若不行，请私信联系开发者。

• Q: 配置修改后未保存/重载无效？
• A: 这通常是由于 YAML 语法错误导致，如缺少引号、多余引号或缩进不正确。请对照示例检查配置，并使用 YAML 校验工具排查。

• Q: 分类不显示？
• A: 请确保分类名在配置中为小写，并检查缩进和引号是否正确。

• Q: 如何访问原版/Essentials 的 /help？
• A: 拥有 help.override 权限的玩家可使用 /? 查看原版帮助。建议在权限插件中添加 -bukkit.command.help 负权限节点以限制普通玩家。

遇到问题？ 请在 GitHub Issues 提交报告，或在讨论区、Discord 联系开发者。请勿在未沟通的情况下直接留下差评。

喜欢这个插件吗？别忘了在发布页留下评分和评论！