插件变量

LyTag 通过 PlaceholderAPI 注册变量扩展，变量标识为 ltag。这些变量用于读取玩家的显示称号、属性称号和称号拥有状态。

使用变量前，服务器必须安装并启用 PlaceholderAPI。LyTag 仅在检测到 PlaceholderAPI 已启用时注册变量；PlaceholderAPI 未安装或未启用时，不影响 LyTag 基础加载，但所有 %ltag_...% 变量均不可用。

变量列表

变量	说明	返回值
%ltag_show_tag_分类ID%	获取玩家在指定分类中佩戴的显示称号。	已佩戴并且称号已注册时返回称号配置中的 title，否则返回未佩戴文本。
%ltag_attribute_tag_分类ID%	获取玩家在指定分类中佩戴的属性称号。	已佩戴并且称号已注册时返回称号配置中的 title，否则返回未佩戴文本。
%ltag_has_tag_称号ID%	判断玩家是否拥有指定称号。	称号已拥有且已注册时返回 true，否则返回 false。

变量中的参数按原内容匹配，区分以下两种标识：

• 分类ID：config.yml 中 tag-class 下的分类名称。
• 称号ID：tag 文件夹内称号配置的顶层键名。

称号配置文件中的 title 是变量返回的显示内容，不是称号 ID。

显示称号变量

%ltag_show_tag_分类ID%

该变量读取玩家在指定分类中当前佩戴的显示称号，并返回对应称号配置中的 title。

例如，配置中存在以下分类：

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

对应变量为：

%ltag_show_tag_普通称号%
%ltag_show_tag_示例称号分类%

只有同时满足以下条件时，变量才会返回称号的 title：

1. 玩家数据已经加载。
2. 玩家在指定分类中佩戴了显示称号。
3. 该称号存在于 LyTag 已加载的称号数据中。
4. 该称号已经成功注册到分类。

玩家没有在指定分类中佩戴有效显示称号时，变量返回未佩戴文本。返回顺序如下：

1. placeholder.not-tag-分类ID
2. placeholder.not-tag

属性称号变量

%ltag_attribute_tag_分类ID%

该变量读取玩家在指定分类中当前佩戴的属性称号，并返回对应称号配置中的 title。

例如：

%ltag_attribute_tag_普通称号%
%ltag_attribute_tag_示例称号分类%

显示称号与属性称号相互独立。同一个分类可以分别佩戴一个显示称号和一个属性称号，因此两个变量可能返回不同内容。

只有同时满足以下条件时，变量才会返回属性称号的 title：

1. 玩家数据已经加载。
2. 玩家在指定分类中佩戴了属性称号。
3. 该称号存在于 LyTag 已加载的称号数据中。
4. 该称号已经成功注册到分类。

玩家没有在指定分类中佩戴有效属性称号时，变量返回分类专用或通用的未佩戴文本，规则与显示称号变量相同。

称号拥有状态变量

%ltag_has_tag_称号ID%

该变量用于判断玩家是否拥有指定称号。

例如：

%ltag_has_tag_离渊插件牛逼%
%ltag_has_tag_示例称号%

返回值	含义
true	玩家数据中拥有该称号，并且该称号存在且已经成功注册到分类。
false	玩家没有该称号、称号不存在，或称号没有注册到任何分类。

仅在 tag 文件夹中创建称号配置并不足以使用该称号。称号还必须加入 config.yml 的 tag-class 分类列表并成功注册，否则 %ltag_has_tag_称号ID% 仍会返回 false。

未佩戴文本

显示称号变量和属性称号变量共用以下配置：

placeholder:
  not-tag: '&7无'
  not-tag-普通称号: '&7暂无普通称号'

配置项	说明	优先级
placeholder.not-tag	所有分类默认使用的未佩戴文本。	低
placeholder.not-tag-分类ID	指定分类使用的未佩戴文本。	高

分类专用配置键由固定前缀 placeholder.not-tag- 与实际分类 ID 直接拼接。例如分类 ID 为 普通称号 时，配置键为：

placeholder:
  not-tag-普通称号: '&7暂无普通称号'

当玩家未佩戴指定分类的显示称号或属性称号时，LyTag 会优先读取该分类的专用文本；不存在时读取通用的 placeholder.not-tag。

这些文本支持使用 & 颜色代码，解析变量时会转换为 Minecraft 颜色格式。称号配置中的 title 也支持使用 & 颜色代码。

玩家数据要求

LyTag 会先读取玩家数据，再解析变量。以下情况会直接返回空文本：

• 变量请求没有可用的玩家对象。
• LyTag 尚未加载该玩家的数据。

玩家数据加载完成后，变量才会读取玩家的拥有称号、显示称号和属性称号。

如果启用了 MySQL 存储，必须安装 LyMySQLCore，并确保数据库已经成功连接。数据库连接完成前，LyTag 会阻止玩家进入服务器；相关玩家数据无法加载，玩家变量也无法正常使用。

返回规则

情况	返回结果
没有可用的玩家对象	空文本
玩家数据尚未加载	空文本
显示称号有效且已注册	对应称号配置中的 title
属性称号有效且已注册	对应称号配置中的 title
未佩戴对应分类的显示称号	分类专用或通用未佩戴文本
未佩戴对应分类的属性称号	分类专用或通用未佩戴文本
%ltag_has_tag_称号ID% 对应称号已拥有且已注册	true
%ltag_has_tag_称号ID% 对应称号未拥有或未注册	false
使用 LyTag 不支持的变量参数	红色的 错误 文本

不支持的参数包括未定义的变量前缀，或不符合 show_tag_、attribute_tag_、has_tag_ 格式的内容。

称号注册与有效性

变量判断的是 LyTag 当前已经加载并注册的称号，而不是单独存在于文件中的称号配置。

称号需要经过以下流程才会对变量生效：

1. 在 tag 文件夹内创建称号配置。
2. 在 config.yml 的 tag-class 中加入称号 ID。
3. LyTag 加载称号文件并注册分类。
4. 称号成功归入一个分类。

同一个称号不能成功注册到多个分类。若称号已经被其他分类注册，后续分类中的重复注册会失败，此时相关变量不会将其视为当前分类的有效称号。

数据变化

限时称号到期后，LyTag 会从玩家拥有称号数据中移除该称号；如果玩家此前佩戴了该称号的显示称号或属性称号，对应佩戴数据也会被清理。因此，相关变量会按照更新后的玩家数据返回未佩戴文本或 false。

玩家的显示称号、属性称号和拥有称号数据会根据当前存储方式保存。LyTag 支持 YAML 存储和 MySQL 存储；使用 MySQL 存储时，必须安装 LyMySQLCore 且数据库连接成功后，相关玩家数据和变量功能才会生效。

使用位置

这些变量可以交给支持 PlaceholderAPI 的其他插件解析，例如聊天、计分板、TAB、菜单或其他文本配置。具体显示位置和解析方式由使用变量的其他插件决定。