HonorBadge

HonorBadge 是一款專為 Paper伺服器設計的稱號系統。管理員透過箱子介面建立、編輯與發放稱號，玩家在介面中點一下即可切換。本插件不直接搶佔 Tab 列表、頭頂名稱或聊天格式，而是提供 PlaceholderAPI 變數交給 TAB、LPC 等插件顯示，避免與既有插件互相覆蓋。

功能特性

• 箱子介面操作：
  • 玩家介面（/hb）只列出自己擁有的稱號，使用中的稱號會發光並標示「使用中」，支援分頁與一鍵卸下。
  • 管理介面可設定顯示名稱、圖示（主手物品）、說明（選填）與排序值，並提供即時預覽與聊天預覽。
  • 所有介面一律左鍵操作；右鍵、Shift、數字鍵、拖曳全部取消，物品無法被拿走。
  • 介面綁定專屬 InventoryHolder（clre20.honorBadge.gui.MenuHolder），按鈕物品帶有 honorbadge:gui 標籤，方便其他插件辨識來源。
• 完整顏色支援：
  • 同時支援 &a 傳統代碼、&#FF5555 HEX 與 MiniMessage（如 <gradient:red:gold>戰神</gradient>）。
  • PAPI 輸出會轉成 §x§R§R§G§G§B§B 格式，TAB 與 LPC 都能正確顯示漸層與 HEX。
• 「取代」顯示模式：
  • %honorbadge_display%：玩家有戴稱號時顯示稱號，沒戴時顯示備用文字（預設為 LuckPerms 前綴）。
  • 備用文字可依用途分組，例如 %honorbadge_display_admin%，讓管理員沒戴稱號時仍顯示原本的身分。
  • 只影響顯示，不影響 LuckPerms 群組與權限。
• 離線玩家支援：
  • give、remove、playerlist 可對曾經進過伺服器的離線玩家使用。
  • 刪除稱號時會從所有持有者身上移除，正在使用的玩家自動卸下。
• 效能與資料安全：
  • 線上玩家資料放在記憶體，變更以髒資料標記，定時批次寫入、離線與關服時存檔。
  • 檔案讀寫集中在單一 I/O 執行緒，更新檢查使用單一網路執行緒，不會無限制增加執行緒。
  • 寫檔採「先寫暫存檔再取代」，避免關服時寫到一半造成損毀。
• 設定檔自動補齊：
  • 啟動與 /hb reload 時，自動比對 config.yml 與 messages.yml，補上缺少的項目並保留原本的值；版本不同時先備份成 .bak。
  • 所有聊天訊息、介面標題、物品名稱與說明都在 messages.yml，可自由修改。
• 檢查更新：
  • 啟動時以非同步方式向 GitHub Releases 檢查，結果寫在主控台。
  • 有 honorbadge.version 權限的管理員登入 3 秒後，若有新版本會收到提醒。
  • 結果快取 10 分鐘、沒有定時輪詢，不會超過 GitHub 每小時 60 次的限制。兩項功能都可在 config.yml 的 update-checker 關閉。

指令與權限

本插件主指令為 /honorbadge。

指令別名：/hb 等同 /honorbadge；/hb delete 等同 /hb del。

honorbadge.admin：包含以上所有權限，預設 OP。

稱號 ID 只能使用小寫英文、數字與底線（a-z 0-9 _），顯示名稱在介面中另外設定。

PlaceholderAPI 變數

使用範例

1. 建立並發放稱號

1. 管理員在遊戲內執行：

   /hb create warlord
   

2. 在介面中點「設定顯示名稱」，於聊天欄輸入 <gradient:red:gold>戰神</gradient>；需要的話再設定圖示、說明與排序，最後點「確認儲存」。
3. 於控制台或遊戲內發給玩家（離線玩家也可以）：

   hb give warlord Steve
   

4. 玩家輸入 /hb，點一下稱號即可使用。

2. 搭配 TAB 顯示在 Tab 列表與頭頂

plugins/TAB/groups.yml：

_DEFAULT_:
  tabprefix: "%honorbadge_display%"
  tagprefix: "%honorbadge_display%"

plugins/TAB/config.yml 的 placeholder-refresh-intervals 加上：

  '%honorbadge_display%': 500

3. 搭配 LPC 顯示在聊天前面

plugins/LPC/config.yml：

chat-format: "&7%honorbadge_display%&f{name} &8» &f{message}"
group-formats:
  admin: "%honorbadge_display_admin%&f{name} &8» &f{message}"
  player: "%honorbadge_display_player%&f{name} &8» &f{message}"

沒戴稱號的管理員會顯示 display-fallback.admin 的內容，戴上後換成稱號。

4. 沒有 TAB／聊天插件的伺服器

將 config.yml 的 native-display 中 chat、tab、nametag 改為 true，由 HonorBadge 自己顯示稱號。已安裝 TAB 時請保持關閉，否則會被 TAB 的 anti-override 擋下。

檔案位置

相容性

• 伺服器：Paper 1.21.x ～ 26.x 與其分支（如 Purpur）；不支援 Spigot、Folia。
• Java：21 以上（26.x 伺服器需要 Java 25）。
• 選用依賴：PlaceholderAPI。
• 基岩版（Geyser）玩家可正常操作介面；HEX 與漸層會被轉成最接近的基本色。

HonorBadge

HonorBadge is a title (badge) system designed for Paper servers. Administrators create, edit, and grant titles through chest GUIs, and players switch titles with a single click. Instead of taking over the tab list, name tags, or chat format, the plugin exposes PlaceholderAPI placeholders so that plugins such as TAB and LPC can display titles without overriding each other.

Features

• Chest GUI Workflow:
  • The player GUI (/hb) lists only owned titles; the equipped title glows and is marked "in use", with pagination and a one-click unequip button.
  • The editor GUI sets the display name, icon (main-hand item), optional description, and sort value, with a live item preview and a chat preview.
  • Every GUI is left-click only; right-click, Shift, number keys, and dragging are cancelled, so items can never be taken.
  • GUIs are bound to a dedicated InventoryHolder (clre20.honorBadge.gui.MenuHolder) and button items carry an honorbadge:gui tag so other plugins can identify them.
• Full Color Support:
  • Legacy &a codes, &#FF5555 hex, and MiniMessage (e.g. <gradient:red:gold>Warlord</gradient>) all work together.
  • Placeholder output uses the §x§R§R§G§G§B§B format, so TAB and LPC render gradients and hex colors correctly.
• Replace Display Mode:
  • %honorbadge_display% shows the title when one is equipped, otherwise a fallback text (LuckPerms prefix by default).
  • Fallbacks can be grouped, e.g. %honorbadge_display_admin%, so staff keep their rank label when no title is equipped.
  • Display only — LuckPerms groups and permissions are never touched.
• Offline Player Support:
  • give, remove, and playerlist work for any player who has joined before.
  • Deleting a title removes it from every holder and unequips it automatically.
• Performance & Data Safety:
  • Online player data lives in memory; changes are flagged dirty and written in batches on a timer, on quit, and on shutdown.
  • All file I/O runs on a single I/O thread and update checks on a single network thread — no thread explosion.
  • Files are written to a temp file and then swapped in, so a crash mid-write cannot corrupt data.
• Automatic Config Completion:
  • On startup and /hb reload, missing keys in config.yml and messages.yml are added while keeping your values; a .bak backup is made when the version changes.
  • All chat messages, GUI titles, item names, and lore live in messages.yml.
• Update Checker:
  • Checks GitHub Releases asynchronously on startup and logs the result.
  • Admins with honorbadge.version get a reminder 3 seconds after joining when a newer version exists.
  • Results are cached for 10 minutes with no polling, staying well below GitHub's 60 requests/hour limit. Both features can be disabled under update-checker in config.yml.

Commands & Permissions

The primary command for this plugin is /honorbadge.

Command Alias: /hb is an alias for /honorbadge; /hb delete equals /hb del.

honorbadge.admin grants every permission above (default: OP).

Title IDs may only contain lowercase letters, digits, and underscores (a-z 0-9 _); the display name is set in the GUI.

PlaceholderAPI Placeholders

Compatibility

• Server: Paper 1.21.x – 26.x and forks (e.g. Purpur). Spigot and Folia are not supported.
• Java: 21+ (26.x servers require Java 25).
• Optional dependency: PlaceholderAPI.
• Bedrock (Geyser) players can use the GUIs; hex colors and gradients are shown as the nearest basic color.