TagsKeeper

插件

· 作者 DevAdvvy

基于标签且经过优化的最佳插件

0 本站下载 0 关注 更新于 4 个月前

需要前置:PlaceholderAPI

最新 1.4 · 26.2 · Bukkit / Paper

一键开服(送7天)
03071a6e14f91b869e37817354b29091ed2bfbcd_96

TagsKeepers

针对 1.20 及以上版本服务器的优化高效标签插件


目录


功能特性

  • 支持使用 & 代码和 HEX &#RRGGBB 进行彩色格式化的标签
  • 可视化的分页菜单,每个标签的槽位均可自定义配置
  • 通过 Vault 结合任意经济插件(如 EssentialsX、CMI 等)购买标签
  • Placeholder %tagskeeper_tag% 用于在聊天栏、Tab 列表或任何使用 PlaceholderAPI 的地方显示标签
  • 选择状态和购买记录按 UUID 保存在 data.yml 中(即使玩家更改名称也会保留)
  • 每个标签拥有独立权限 (tagskeeper.<id>),并兼容旧版权限 (alonsotags.tag.<id>)
  • 可自定义每种操作的声音效果(打开、选中、拒绝、已选中)
  • 标签 Lore 支持占位符:%preview%、%status%、%selected%、%price%
  • PlaceholderAPI 和 Vault 为软依赖:插件可在无它们的情况下运行,对应功能将自动禁用
  • 控制台参数:所有命令均无需额外参数即可执行

依赖项

依赖项 类型 用途
Paper 1.20.x 服务端 运行环境
PlaceholderAPI 插件 (软依赖) 提供 %tagskeeper_tag% 占位符
Vault + 经济提供商 插件 (软依赖) 支持付费标签购买功能

如果未安装 Vault,EconomyHook.setup() 会静默失败,且 EconomyHook.isEnabled() 返回 false。带有 price 设置的标签将不显示价格且无法购买。


安装

  1. 从 Releases 下载 JAR 文件
  2. 将其放入 plugins/ 文件夹
  3. 重启服务器
  4. 在 plugins/TagsKeepers/tags.yml 中配置标签
  5. 执行 /reloadtags 以应用更改而无需重启服务器

首次启动时,插件会生成默认配置文件:

  • config.yml(仅包含 storage.type: YAML)
  • messages.yml
  • menu.yml
  • tags.yml(附带 9 个示例标签)
  • data.yml(初始为空,随后自动填充)

命令与权限

命令

命令 别名 描述 控制台可用
/tags /tag 打开标签菜单(第 1 页) 否,仅在控制台返回 true 但无实际操作
/reloadtags -- 重载配置、消息、菜单和标签设置 是

/tags 不检查权限。任何玩家都可以打开菜单。各个标签由内部权限控制。

权限

节点 默认值 描述
tagskeeper.perms.reload op 访问 /reloadtags
tagskeeper.bypass.price op 获取付费标签时不扣除金钱
tagskeeper.<id> -- 访问具有该 ID 的标签(例如:tagskeeper.vip)
alonsotags.tag.<id> -- 遗留权限,作为前者的替代验证方式

标签配置

tags.yml 在 tags: 键下包含标签的定义。

格式

tags:
  <id>:
    tag: "<在聊天/记分板/标签列表中显示的名称>"
    menu-display: "<菜单中显示的名称>"
    preview: "<带有 {player} 的预览效果>"
    permission: "tagskeepers.example <所需权限>"
    material: "<材质>"
    page: <页码>
    slot: <物品栏中的槽位>
    price: <可选价格,无需引号:10000>
    lore:
      - "<描述文本行>"

### 卡姆波斯

| 字段 | 必填 | 默认值 | 类型 |
|---|---|---|---|
| `tag` | 是 | -- | String(颜色) |
| `menu-display` | 是 | -- | String(颜色) |
| `preview` | 是 | -- | String(颜色,必须包含 `{player}`) |
| `permission` | 是 | -- | String(权限节点) |
| `material` | 是 | -- | String(Bukkit 材质,例如:`NAME_TAG`、`DIAMOND`) |
| `slot` | 是 | -- | Integer(0-53,根据菜单大小而定) |
| `page` | 否 | `1` | Integer |
| `lore` | 是 | -- | 字符串列表 |
| `price` | 否 | `-1`(无价格) | Double |

### Lore 中的占位符

| 占位符 | 替换为 |
|---|---|
| `%preview%` | `preview` 字段,其中 `{player}` 被玩家名称替换 |
| `%status%` | 根据 `tag-status.unlocked` 或 `tag-status.locked` 在 `messages.yml` 中配置的消息 |
| `%selected%` | 根据 `tag-selection.selected` 或 `tag-selection.not-selected` 在 `messages.yml` 中配置的消息 |
| `%price%` | 如果标签有 `price` 且 Vault 处于激活状态,则由 Vault 格式化的价格;否则为空字符串 |

### 完整示例

```yaml
tags:
  vip:
    tag: "&8&#FFD700&lVIP&8"
    menu-display: "&f标签 &8&#FFD700&lVIP&8"
    preview: "&8&#FFD700&lVIP &f{玩家}"
    permission: "tagskeeper.vip"
    material: NAME_TAG
    page: 1
    slot: 10
    price: 10000
    lore:
      - ""
      - "&7预览:"
      - "&f%preview%"
      - ""
      - "&7状态: %status%"
      - "&7价格: &e%price%"
      - ""
      - "%selected%"

默认包含的标签

ID 页面 槽位 价格
campeon 1 10 --
mvp 1 11 --
elite 1 12 --
random 1 13 --
veterano 1 14 --
og 1 15 --
koth 1 16 --
emperor 2 13 --
king 3 13 --

所有默认标签均未包含 price。


菜单 GUI

配置位于 menu.yml。

页面

每个页面都定义为 menus.page-<数字>。插件自带 3 个预配置的页面。

menus:
  page-1:
    title: "<inventory title>"
    size: 36
    next-page-slot: 32
    previous-page-slot: <optional>
    remove-tag-slot: 31
Option Description
title Inventory title (supports HEX colors)
size Inventory size, must be a multiple of 9 (typical: 27, 36, 45, 54)
next-page-slot Slot where the next page arrow appears
previous-page-slot Slot where the previous page arrow appears
remove-tag-slot Item slot for removing the current tag

If a page does not have next-page-slot or previous-page-slot, that respective arrow will not be displayed.

Filler

menus:
  fill-empty-slots: true
  filler:
    material: BLACK_STAINED_GLASS_PANE
    name: " "

If fill-empty-slots is true, all slots (0 to size-1) are filled with the configured material before placing tags/navigation items. This prevents players from moving items into the inventory. Tag items overwrite the filler in their specific slots.

Sounds

menus:
  sounds:
    open: BLOCK_CHEST_OPEN
    select: ENTITY_PLAYER_LEVELUP
    denied: ENTITY_VILLAGER_NO
    already-selected: BLOCK_NOTE_BLOCK_BASS

Sounds play at volume 1.0 and pitch 1.0. The name must correspond to a value of org.bukkit.Sound. If the name is invalid, a warning is logged to the console and the sound is skipped.

Remove-tag item

menus:
  remove-tag:
    enabled: true
    active:
      material: PLAYER_HEAD
      basehead: "<base64>"
      name: "&fMenu &8» &8&#FFD700&ltags&8 &f"
      lore:
        - " &fCurrent Tag:"
        - "   %current_tag%"
        - " &8- &fClick to remove"
    inactive:
      material: GRAY_DYE
      name: "&fMenu &8» &8&#FFD700&ltags&8 &f"
      lore:
        - " &7You currently do not have"
        - " &7any active tag."

The active item is displayed when the player has a tag equipped. The inactive item is displayed when they do not. The %current_tag% placeholder in the lore is replaced by the formatted current tag, or "&7None" if the tag ID is not found in the registry.

Navigation

Navigation arrows are created using the ARROW material:

  • Next page: name "&aNext Page"
  • Previous page: name "&cPrevious Page"

(Texts in English, hardcoded in MenuManager.java.)


Economy System

Requirements

  • Vault installed on the server
  • An economy provider registered in Vault (EssentialsX, CMI, CosmicPvP, etc.)

Internal Operation

EconomyHook uses reflection to access net.milkbowl.vault.economy.Economy, so it does not require the VaultAPI during compilation. At runtime:

  1. EconomyHook.setup() is called from Main.onEnable()
  2. It checks that the Vault plugin exists on the server
  3. Retrieves the economy provider via Bukkit.getServicesManager().getRegistration()
  4. Stores the methods has(), withdrawPlayer(), format() via reflection
  5. If any step fails, isEnabled() returns false

Purchase Flow

When a player clicks on a tag for which they do not have permission:

  1. If the tag does not have a price (> 0) or the economy is not active: display no-permission message
  2. If the tag has a price and the economy is active:
    • If the player has tagskeeper.bypass.price: mark as purchased without charging, select the tag
    • If the player does not have sufficient funds: display tag-insufficient-funds message
    • If they have sufficient funds: execute withdraw(), mark as purchased in data.yml, select the tag

The purchase is saved in data.yml as:

purchased:
  <uuid>:
    <tag-id>: true

The purchased tag is permanently linked to the UUID. It does not expire.

Related Messages

Path Placeholders
tag-purchased %prefix%, %price%
tag-insufficient-funds %prefix%, %price%
tag-bypass-purchase %prefix%, %price%

PlaceholderAPI

If PlaceholderAPI is present on the server, the plugin registers the tagskeeper expansion with the following placeholder:

Placeholder Return Value
%tagskeeper_tag% The value of the tag field of the selected tag (with colors), or an empty string if no tag is selected or the ID does not exist

The expansion is registered in Main.onEnable() if PlaceholderAPI is detected as a loaded plugin.

Typical Usage

In plugins compatible with PlaceholderAPI (TAB, EssentialsXChat, CMI, DeluxeChat, etc.):

Format in config: %tagskeeper_tag%
Example in chat:   &8&#FFD700&lVIP &7DevAdvvy: Hello

HEX Colors

The plugin uses ColorUtil.java to convert the &#RRGGBB format to the equivalent BungeeCord ChatColor.

Format

&#RRGGBB

Where RR, GG, BB are hexadecimal values (00-FF).

Examples

&#FF0000  Red
&#00FF00  Green
&#0000FF  Blue
&#FFD700  Gold
&#E59500  Orange

Combination with formatting codes

&#FFD700&l   Gold + bold
&#FF6A00&l&o Orange + bold + italic
&8&#FFD700   Dark gray + Gold (no formatting)

Standard Minecraft & codes (0-9, a-f, k-o, r) work alongside HEX codes.

Where to use

  • tag in tags.yml
  • menu-display in tags.yml
  • preview in tags.yml
  • lore in tags.yml
  • title in menu.yml
  • All messages in messages.yml
  • name of the filler and remove-tag in menu.yml

Messages

messages.yml contains all texts sent by the plugin to players.

Global Placeholders

Placeholder Description
%prefix% Replaced by the value of prefix in messages.yml
%tag% (Only in tag-selected) The selected tag, with colors
%price% (Only in purchase messages) Price formatted by Vault

Full list of messages

prefix: "<插件前缀>"
no-permission: "%prefix% <无权限>"
tag-selected: "%prefix% <已选择标签:%tag%>"
tag-already-selected: "%prefix% <已选择>"
tag-removed: "%prefix% <标签已移除>"
no-tag-equipped: "%prefix% <未装备标签>"
reload-success: "%prefix% <已重载>"
tag-purchased: "%prefix% <以 %price% 购买>"

tag-insufficient-funds: "%prefix% <资金不足:需要 %price%>" tag-bypass-purchase: "%prefix% <已免费获取>"


数据循环

服务器启动时

  1. Main.onEnable() 会在文件不存在时保存默认的 YAML 文件
  2. ConfigManager 将 messages.yml 和 menu.yml 加载到内存中
  3. YAMLStorage 加载 data.yml(如果不存在则创建)
  4. TagManager 将 tags.yml 加载到内存中的 HashMap<String, Tag> 里
  5. PlayerDataManager 初始化一个空的缓存 Map<UUID, PlayerTagData>
  6. EconomyHook.setup() 尝试连接 Vault

当玩家加入游戏时

JoinListener.onJoin():

  1. 从 data.yml 中读取玩家选择的标签(通过 config.getString(uuid))
  2. 将其保存到 PlayerDataManager 的缓存中

当玩家选择标签时

InventoryListener.onClick():

  1. 在内存中更新 PlayerTagData.selectedTag
  2. 通过 YAMLStorage.saveTag(uuid, tagId) 将数据保存到 data.yml

执行 /reloadtags 时

ReloadCommand.onCommand():

  1. reloadConfig()(重新加载 config.yml)
  2. ConfigManager.reload()(重新加载 messages.yml 和 menu.yml)
  3. TagManager.loadTags()(清理并重新加载 tags.yml)
  4. 不会影响 data.yml 或 PlayerDataManager 的缓存

编译

git clone https://github.com/DevAdvvy/TagsKeepers.git
cd TagsKeepers
mvn clean package

JAR 文件将生成于 target/TagsKeepers-1.3.jar。

编译依赖

依赖项(Paper API、PlaceholderAPI、authlib)通过 pom.xml 中配置的 Maven 仓库进行解析。它们不会包含在最终的 JAR 包中(作用域为 provided)。


技术说明

  • 该插件不会自行修改聊天内容。标签通过 PlaceholderAPI 暴露,以便其他插件在适当位置显示。
  • 玩家数据按 UUID 存储,而非按名称。如果玩家更改了用户名,其标签和购买记录将保留不变。
  • data.yml 每次保存操作(save())时都会直接写入磁盘。没有缓冲或延迟写入机制。
  • TagManager 使用 HashMap<String, Tag> 存储标签,其中键为小写的 ID。
  • EconomyHook 使用 player.getLocation() 作为参数向 Vault 发起调用。Vault 接受 OfflinePlayer,而 Player 继承自 OfflinePlayer。
  • InventoryListener.onClick() 中的槽位验证使用 stream().anyMatch() 来检查点击的槽位是否对应当前页面中的某个标签,然后再进行搜索迭代。
  • 声音处理使用了 try-catch,以防配置的声音名称不匹配有效的 Sound。
  • 头颅的 Base64 编码通过正则表达式 [a-zA-Z0-9_\-]+ 对提取出的 texture ID 进行验证,以防止 SSRF 攻击指向非 textures.minecraft.net 域名。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源