福利·称号 LyTag

MySQL 前置要求

启用 MySQL 存储时，必须安装 LyMySQLCore，并确认它已成功连接数据库。否则玩家数据无法正常读取、保存和同步，相关功能不会生效。

LyTag 是一款 Minecraft 称号插件。管理员可以创建称号并按分类注册，玩家可以在 GUI 中查看已拥有或未拥有的称号，分别设置每个分类的显示称号和属性称号。称号支持永久时间、限时时间、收集属性、佩戴属性、药水效果，以及按点击或定时触发的动作。

兼容信息

项目	说明
项目版本	`1.0.4`
插件名称	`LyTag`
编译 API	Paper API `1.16.5-R0.1-SNAPSHOT`
版本兼容处理	项目包含旧版数字物品 ID、英文物品 ID 和新版本材质名的兼容处理；完整支持范围以实际服务端测试结果为准
主命令	`/ltag`

功能

使用 YAML 文件或 MySQL 保存玩家称号数据。
支持递归读取 plugins/LyTag/tag 目录下的 .yml 称号文件。
支持称号分类；称号文件中的称号必须在 config.yml 的 tag-class 中注册后才能使用。
每个分类最多显示前 9 个分类按钮。
支持永久称号和限时称号。
支持每个分类分别设置显示称号和属性称号。
支持称号收集属性；获得称号后自动计算并接入已选择的属性插件。
支持称号佩戴属性；玩家右键佩戴属性称号后生效。
支持按称号配置药水效果，属性称号生效期间持续刷新。
支持左键点击、右键点击和定时 tick 触发动作。
支持动作触发概率和毫秒级冷却时间。
支持发送消息、释放 MythicMobs 技能、执行控制台指令、以玩家身份执行指令和以 OP 身份执行指令。
GUI 支持分页、切换称号分类和筛选已拥有、未拥有、全部称号。
支持 PlaceholderAPI 变量。
支持从旧插件 LegendTitle 的部分 YAML 玩家数据转换为 LyTag 数据。

依赖

依赖	是否必需	用途与条件
PlaceholderAPI	可选	注册 LyTag 变量；动作中的 `command_console`、`command_op` 和 `command` 结果也会使用 PlaceholderAPI 解析变量
LyMySQLCore	MySQL 模式必需	`mysql.enable: true` 时负责 MySQL 玩家数据加载与保存事件；必须成功连接数据库后才会生效
AttributePlus	属性接入可选	当 `attribute-plugin` 设置为 `AttributePlus` 时接入称号属性
SX-Attribute	属性接入可选	当 `attribute-plugin` 设置为 `SX-Attribute2` 或 `SX-Attribute3` 时使用；对应版本必须与配置匹配
AttributeSystem	属性接入可选	当 `attribute-plugin` 设置为 `AttributeSystem` 时接入称号属性
ItemLoreOrigin	属性接入可选	当 `attribute-plugin` 设置为 `ItemLoreOrigin` 时接入称号属性
MythicMobs	按功能需要	称号动作配置使用 `mmskill:` 结果时需要；未使用该结果类型时不需要用于称号动作

命令

命令	使用者限制	说明
`/ltag`	OP	显示管理员帮助；验证完成后显示完整命令帮助
`/ltag reload`	OP	重载 `config.yml`、称号文件、分类和相关运行任务；MySQL 开关或属性插件配置修改需要重启
`/ltag open`	玩家	打开称号界面；界面默认进入第一个已注册分类
`/ltag give <玩家> <称号ID> <时间:秒>`	OP	给在线玩家发放已注册称号；时间为 `0` 时保存为永久称号，其他时间按秒转换为毫秒
`/ltag remove <玩家> <称号ID>`	OP	移除在线玩家的已注册称号
`/ltag LegendTitle`	OP	执行旧 `LegendTitle` 数据转换，将 `plugins/LegendTitle/data` 下的玩家数据转换到 LyTag 的 YAML 数据格式

give 和 remove 只能操作已经在 tag-class 中注册的称号。玩家必须在线且已完成 LyTag 数据加载。

数据保存

YAML

当 mysql.enable 为 false 时，玩家数据保存到：

text

plugins/LyTag/data/<玩家UUID>.yml

数据结构包含以下部分：

节点	说明
`attribute-tag.<分类ID>`	每个分类当前佩戴的属性称号 ID
`show-tag.<分类ID>`	每个分类当前显示的称号 ID
`all-tag.<称号ID>`	玩家拥有的称号及到期时间；`0` 表示永久

玩家加入、退出或被踢出时会读取或保存数据。玩家数据发生变化后，也会进行异步自动保存。

MySQL

当 mysql.enable 为 true 时，LyTag 会通过 LyMySQLCore 的安全玩家加载和保存事件处理数据，并在数据库中使用 LyTag 表保存玩家名称和 YAML 序列化数据。

必须同时满足以下条件：

安装 LyMySQLCore。
正确填写 mysql 配置。
LyMySQLCore 成功连接数据库。
LyTag 成功初始化数据库表。

如果数据库未连接完成，玩家登录会被阻止，直到数据库连接可用。

GUI 交互

LyTag 使用 54 格称号界面：

位置	功能
顶部前 9 格	切换称号分类
中间 27 格	显示当前分类的称号
底部第 1 格	上一页
底部第 5 格	切换筛选模式
底部第 9 格	下一页
底部第 4 格	当前显示称号；点击可卸除
底部第 6 格	当前属性称号；点击可卸除

称号筛选模式按照以下顺序循环：

text

已拥有 -> 未拥有 -> 全部 -> 已拥有

在称号物品上：

左键：设置为当前分类的显示称号。
右键：设置为当前分类的属性称号。
未拥有的称号不能佩戴，也不能设置为显示称号或属性称号。

称号过期后会从玩家拥有列表中清理；对应的显示称号和属性称号也会被自动移除。

称号文件

称号文件放置在：

text

plugins/LyTag/tag/

插件会递归读取该目录下所有 .yml 文件。一个文件可以包含多个称号，顶层键名就是称号 ID。

称号字段

配置键	类型	说明
`<称号ID>.title`	字符串	玩家佩戴显示称号时使用的文本；未配置时使用称号 ID
`<称号ID>.info`	字符串列表	称号介绍，可在 GUI lore 中通过 `{info}` 显示
`<称号ID>.collect-attribute`	字符串列表	玩家拥有该称号后获得的收集属性
`<称号ID>.attribute`	字符串列表	玩家佩戴该称号为属性称号后获得的属性
`<称号ID>.effect`	键值映射	属性称号生效期间持续施加的药水效果；值为药水等级，代码使用的等级从 `0` 开始
`<称号ID>.action`	映射	属性称号生效期间的触发动作配置

称号示例

yaml

# 称号 ID，用于指令和 config.yml 的 tag-class
离渊插件牛逼:
  # 佩戴显示称号时显示的文本
  title: '&7[&6离渊福利插件&7]'
  info:
    - '&7这个称号确实牛逼'
  # 获得称号后获得的收集属性
  collect-attribute:
    - '攻击力+1'
  # 佩戴属性称号后获得的属性
  attribute:
    - '攻击力+1'
  action:
    left:
      chance: 0.1
      cooldown: 5000
      result:
        - 'mmskill:技能'
        - 'tell:你触发了左键技能'
        - 'command_console:tell %player_name% 执行控制台指令'
        - 'command_op:tell %player_name% 执行OP指令'
        - 'command:tell %player_name% 执行玩家指令'

示例称号:
  title: '&7[&a示例称号&7]'
  info:
    - '&7这个称号属实牛逼'
  collect-attribute:
    - '攻击力+1'
  attribute:
    - '攻击力+1'
  effect:
    SPEED: 0

称号写入文件后，还必须在 config.yml 的 tag-class 中注册。例如：

yaml

tag-class:
  普通称号:
    - '离渊插件牛逼'
  示例称号分类:
    - '示例称号'

同一个称号不能重复注册到多个分类。配置最多支持 9 个分类按钮，因为 GUI 顶部第一行只有 9 个分类位置。

动作机制

动作必须配置在称号的 action 节点下，并且只有玩家将该称号设置为属性称号后才会检查。

触发类型

类型	触发条件
`left`	玩家左键点击空气或方块
`right`	玩家右键点击空气或方块
`tick`	定时检查；运行任务每 10 tick 检查一次符合条件的属性称号

动作字段

配置键	类型	说明
`chance`	小数	触发概率；代码使用随机数与该值比较
`cooldown`	整数	冷却时间，单位为毫秒；未配置时默认 `1000`
`result`	字符串列表	触发后依次执行的结果

结果类型

前缀	说明
`tell:`	向玩家发送消息，支持 `&` 颜色代码
`mmskill:`	由玩家释放指定 MythicMobs 技能
`command_console:`	由控制台执行指令；执行前解析 PlaceholderAPI 变量
`command_op:`	以玩家身份执行指令，并临时给予 OP 权限；执行前解析 PlaceholderAPI 变量
`command:`	以玩家身份执行普通指令；执行前解析 PlaceholderAPI 变量

cooldown 的时间单位是毫秒，不是秒。chance 未配置时默认为 0，动作不会触发。

药水效果

药水效果写在称号的 effect 节点中，键名使用 Bukkit 药水效果名称，例如：

yaml

effect:
  SPEED: 0
  NIGHT_VISION: 0

药水效果只有在该称号作为属性称号佩戴时生效。插件会定时刷新属性称号提供的药水效果；同一种药水效果同时来自多个称号时，使用等级较高的配置。

可使用的效果名称以当前服务端 Bukkit API 支持的 PotionEffectType 名称为准。项目示例中使用了以下名称：

text

SPEED
FAST_DIGGING
SLOW_DIGGING
INCREASE_DAMAGE
HEAL
HARM
JUMP
CONFUSION
REGENERATION
DAMAGE_RESISTANCE
FIRE_RESISTANCE
WATER_BREATHING
INVISIBILITY
BLINDNESS
NIGHT_VISION
HUNGER
WEAKNESS
POISON
WITHER
HEALTH_BOOST
ABSORPTION
SATURATION
FIRE

配置文件

主配置文件为：

text

plugins/LyTag/config.yml

修改 MySQL 开关和属性插件配置后需要重启插件或服务器；原配置注释明确标记这两项需要重启。

`mysql`

配置键	默认值	说明
`mysql.enable`	`false`	是否启用 MySQL 存储；启用后必须安装并连接 `LyMySQLCore`
`mysql.databasename`	`mc2`	数据库名称
`mysql.username`	`mc2`	数据库用户名
`mysql.password`	`mc1234`	数据库密码
`mysql.port`	`3306`	数据库端口
`mysql.ip`	`127.0.0.1`	数据库地址

配置示例：

yaml

mysql:
  enable: false
  databasename: mc2
  username: mc2
  password: mc1234
  port: 3306
  ip: 127.0.0.1

`attribute-plugin`

配置键	可用值	说明
`attribute-plugin`	空字符串	不接入属性插件
`attribute-plugin`	`AttributePlus`	接入 AttributePlus
`attribute-plugin`	`SX-Attribute2`	接入 SX-Attribute 2 属性接口
`attribute-plugin`	`SX-Attribute3`	接入 SX-Attribute 3 属性接口
`attribute-plugin`	`AttributeSystem`	接入 AttributeSystem
`attribute-plugin`	`ItemLoreOrigin`	通过物品 Lore 属性接口接入 ItemLoreOrigin

示例：

yaml

attribute-plugin: ''

该配置只决定称号属性的接入方式，不会改变称号收集、显示和 GUI 功能。选择某个属性插件时，服务端必须安装对应前置。

`placeholder`

配置键	默认值	说明
`placeholder.not-tag`	`&7无`	没有显示称号或属性称号时的默认变量返回值
`placeholder.not-tag-<分类ID>`	未固定	指定分类没有称号时的变量返回值；存在时覆盖 `placeholder.not-tag`
`placeholder.forever-tag-format`	`&7到期时间: &6永久`	永久称号在 GUI 中显示的时间文本
`placeholder.limited-time-tag-format`	`&7到期时间: &b{time}`	限时称号在 GUI 中显示的时间文本；`{time}` 会替换为 `yyyy-MM-dd HH:mm:ss`

`tag-class`

tag-class 用于注册称号分类。键名是分类 ID，列表内容是称号 ID。

配置键	类型	说明
`tag-class.<分类ID>`	字符串列表	注册到该分类的称号 ID；只有注册后的称号才能被玩家使用

示例：

yaml

tag-class:
  普通称号:
    - '离渊插件牛逼'
  示例称号分类:
    - '示例称号'

`gui`

配置键	默认值	说明
`gui.title`	`&0当前分类: &n&l{class}`	GUI 标题；`{class}` 替换为当前分类 ID
`gui.fill-item`	`160:0`	填充物品
`gui.fill-name`	`&7封锁`	填充物品名称
`gui.last-item`	`341:0`	上一页物品
`gui.last-name`	`&6上一页`	上一页名称
`gui.next-item`	`341:0`	下一页物品
`gui.next-name`	`&6下一页`	下一页名称
`gui.class-button-item`	`332:0`	分类按钮物品
`gui.class-button-name`	`&e{class}`	分类按钮名称；`{class}` 替换为分类 ID
`gui.tag-item`	`403:0`	已拥有称号物品
`gui.tag-name`	`&7称号: &f{tag}`	已拥有称号名称；`{tag}` 替换为称号显示文本
`gui.tag-lore`	字符串列表	已拥有称号 lore；支持 `{info}`、`{collect_attribute}`、`{attribute}`、`{time}` 和 `{tag}`
`gui.not-collected-tag-item`	`340:0`	未拥有称号物品
`gui.not-collected-tag-name`	`&7称号: &f{tag}`	未拥有称号名称
`gui.not-collected-tag-lore`	字符串列表	未拥有称号 lore；支持 `{info}`、`{collect_attribute}`、`{attribute}` 和 `{tag}`
`gui.show-tag-item`	`403:0`	当前显示称号物品
`gui.show-tag-name`	`&7当前显示称号: {tag}`	当前显示称号名称
`gui.show-tag-lore`	字符串列表	当前显示称号 lore；支持 `{info}`、`{collect_attribute}`、`{attribute}`、`{time}` 和 `{tag}`
`gui.attribute-tag-item`	`403:0`	当前属性称号物品
`gui.attribute-tag-name`	`&7当前属性称号: {tag}`	当前属性称号名称
`gui.attribute-tag-lore`	字符串列表	当前属性称号 lore；支持 `{info}`、`{collect_attribute}`、`{attribute}`、`{time}` 和 `{tag}`
`gui.not-show-tag-item`	`330:0`	没有显示称号时的物品
`gui.not-show-tag-name`	`&7当前显示称号: 无`	没有显示称号时的名称
`gui.not-attribute-tag-item`	`330:0`	没有属性称号时的物品
`gui.not-attribute-tag-name`	`&7当前属性称号: 无`	没有属性称号时的名称
`gui.filter-switch-item`	`339:0`	筛选按钮物品
`gui.filter-owned-name`	`&a筛选: 已拥有`	已拥有筛选模式名称
`gui.filter-unowned-name`	`&c筛选: 未拥有`	未拥有筛选模式名称
`gui.filter-all-name`	`&e筛选: 全部`	全部筛选模式名称
`gui.filter-switch-lore`	字符串列表	筛选按钮 lore

GUI lore 中的特殊占位符：

占位符	说明
`{info}`	插入称号的 `info` 列表
`{collect_attribute}`	插入称号的收集属性列表
`{attribute}`	插入称号的佩戴属性列表
`{time}`	插入永久或限时到期文本
`{tag}`	插入称号的 `title` 文本
`{class}`	插入当前分类 ID，仅用于 `gui.title` 和 `gui.class-button-name`

物品值支持项目内的旧版数字 ID 和 ID:数据值 格式，例如 160:0、341:0。

`message`

配置键	默认值	触发时机
`message.tag-end-time`	`&7您的 {tag} &7称号已过期!`	称号过期时发送；`{tag}` 替换为称号显示文本
`message.set-show-tag`	`&7成功佩戴显示称号: {tag}`	成功设置显示称号时发送
`message.set-attribute-tag`	`&7成功佩戴属性称号: {tag}`	成功设置属性称号时发送
`message.cancel-show-tag`	`&7已取消佩戴显示称号.`	卸除显示称号时发送
`message.cancel-attribute-tag`	`&7已取消佩戴属性称号.`	卸除属性称号时发送

PlaceholderAPI 变量

变量标识符为 ltag，完整变量格式如下：

变量	返回值
`%ltag_show_tag_<分类ID>%`	指定分类当前显示称号的 `title`；没有时返回 `placeholder.not-tag` 或对应分类的 `placeholder.not-tag-<分类ID>`
`%ltag_attribute_tag_<分类ID>%`	指定分类当前属性称号的 `title`；没有时返回 `placeholder.not-tag` 或对应分类的 `placeholder.not-tag-<分类ID>`
`%ltag_has_tag_<称号ID>%`	玩家是否拥有指定且已注册称号；拥有返回 `true`，否则返回 `false`

PlaceholderAPI 未安装时，LyTag 不会注册这些变量。

属性机制

玩家数据更新时，LyTag 会重新计算属性：

所有已拥有称号的 collect-attribute 会加入属性列表。
每个分类当前佩戴的属性称号的 attribute 会加入属性列表。
属性列表会根据 attribute-plugin 配置接入对应属性系统。
未配置 attribute-plugin 时，称号数据仍可正常保存、展示和管理，但不会接入这些属性插件。

FAQ

为什么称号文件写好了，但 GUI 中没有显示？

检查称号文件是否位于 plugins/LyTag/tag 目录或其子目录，并确认顶层称号 ID 已写入 config.yml 的 tag-class。只写称号文件而不注册分类，称号不会进入可用数据。

为什么 MySQL 模式下玩家无法进入服务器？

MySQL 模式启用后，LyTag 会在数据库连接未完成时阻止玩家登录。确认已经安装 LyMySQLCore，检查 mysql.ip、mysql.port、mysql.databasename、mysql.username 和 mysql.password，并确认 LyMySQLCore 已成功连接数据库。

为什么收集属性或佩戴属性没有生效？

检查 attribute-plugin 是否填写了正确的属性插件名称，并确认对应前置已安装。可用值为 AttributePlus、SX-Attribute2、SX-Attribute3、AttributeSystem 和 ItemLoreOrigin。修改该配置后需要重启。

为什么动作没有触发？

确认以下内容：

该称号已被玩家拥有。
该称号已在 tag-class 注册。
该称号当前被设置为属性称号。
动作类型使用的是 left、right 或 tick。
chance 大于 0。
cooldown 尚未结束。
使用 mmskill: 时已安装 MythicMobs，并且技能名称存在。

`give` 的时间单位是什么？

/ltag give 的时间参数单位是秒。插件会将输入值乘以 1000 转换为毫秒；输入 0 表示永久称号。

为什么限时称号过期后仍然显示？

称号到期会在玩家数据更新时清理。插件会定时更新在线玩家数据，关闭 GUI、修改称号或保存数据时也会触发更新。清理后对应的显示称号和属性称号会一并移除。

为什么 GUI 筛选默认显示已拥有？

打开界面时默认使用“已拥有”筛选模式。点击底部筛选按钮后，会依次切换为“未拥有”和“全部”。

福利·称号 LyTag ​

兼容信息 ​

功能 ​

依赖 ​

命令 ​

数据保存 ​

YAML ​

MySQL ​

GUI 交互 ​

称号文件 ​

称号字段 ​

称号示例 ​

动作机制 ​

触发类型 ​

动作字段 ​

结果类型 ​

药水效果 ​

配置文件 ​

mysql ​

attribute-plugin ​

placeholder ​

tag-class ​

gui ​

message ​

PlaceholderAPI 变量 ​

属性机制 ​

FAQ ​

为什么称号文件写好了，但 GUI 中没有显示？ ​

为什么 MySQL 模式下玩家无法进入服务器？ ​

为什么收集属性或佩戴属性没有生效？ ​

为什么动作没有触发？ ​

give 的时间单位是什么？ ​

为什么限时称号过期后仍然显示？ ​

为什么 GUI 筛选默认显示已拥有？ ​

福利·称号 LyTag

兼容信息

功能

依赖

命令

数据保存

YAML

MySQL

GUI 交互

称号文件

称号字段

称号示例

动作机制

触发类型

动作字段

结果类型

药水效果

配置文件

`mysql`

`attribute-plugin`

`placeholder`

`tag-class`

`gui`

`message`

PlaceholderAPI 变量

属性机制

FAQ

为什么称号文件写好了，但 GUI 中没有显示？

为什么 MySQL 模式下玩家无法进入服务器？

为什么收集属性或佩戴属性没有生效？

为什么动作没有触发？

`give` 的时间单位是什么？

为什么限时称号过期后仍然显示？

为什么 GUI 筛选默认显示已拥有？