插件变量
LyGuideReload 会在服务器安装并启用 PlaceholderAPI 后，注册标识符为 tjr 的 PlaceholderAPI 变量扩展。变量用于读取玩家的图鉴收集次数、收藏分、套装进度、击杀与物品触发记录，以及图鉴属性文本。
变量只能为已经加载玩家数据的在线玩家计算。玩家对象为空或玩家数据尚未加载时，变量返回空文本。
使用说明
- 所有变量均以
%tjr_开头、以%结尾。 - 表格中的“图鉴 ID”对应图鉴配置的
id。 - 表格中的“套装 ID”对应套装配置的
id。 - 表格中的“怪物 ID”对应击杀监听记录中的实体名称或 MythicMobs 内部 ID。
- 属性变量的行号从
0开始。 - 属性变量使用下划线分割参数，因此图鉴 ID 不应包含下划线。
- 变量读取的是当前服务器内存中的玩家数据，不需要等待下一次自动保存。
收藏分变量
| 变量 | 返回内容 |
|---|---|
%tjr_all_point% | 玩家的全部收藏分，包括图鉴收藏分和已集齐套装提供的收藏分 |
%tjr_suit_point_套装ID% | 指定套装以及套装内全部图鉴的收藏分总和 |
%tjr_guide_point_图鉴ID% | 指定图鉴的收藏分 |
%tjr_tag_point% | 当前收藏分阶段对应的称号 |
收藏分计算规则
指定图鉴的收藏分按照以下规则计算：
text
图鉴收藏分 = 当前收集次数 × 图鉴的 base-point%tjr_suit_point_套装ID% 包含以下内容：
- 套装内所有图鉴产生的收藏分。
- 玩家至少收集过套装内每一个图鉴后，套装配置
point提供的收藏分。
套装配置的 point 只有在套装内全部图鉴的收集次数都大于 0 时才计入。
%tjr_all_point% 会累计全部图鉴收藏分，以及所有已经集齐套装提供的套装收藏分。
%tjr_tag_point% 会从 config.yml 的 point 节点中选择不高于玩家当前总收藏分的最高阶段，并返回该阶段的 tag。返回结果会将 & 颜色代码转换为 Minecraft 颜色符号。没有可用阶段时返回空文本。
图鉴收集变量
| 变量 | 返回内容 | 无效 ID 时 |
|---|---|---|
%tjr_collect_count_图鉴ID% | 指定图鉴当前收集次数 | 0 |
%tjr_collect_max_图鉴ID% | 指定图鉴配置中的最大收集次数 | 0 |
%tjr_collect_suit_套装ID% | 指定套装内全部图鉴当前收集次数的总和 | 0 |
%tjr_collect_suit_套装ID% 返回的是套装内各图鉴收集次数之和，不是完成百分比，也不包含套装是否已经集齐的判断。
例如，一个套装包含两个图鉴，玩家分别收集了 3 次和 2 次，则变量返回 5。
击杀触发变量
| 变量 | 返回内容 | 无记录时 |
|---|---|---|
%tjr_trigger_kill_怪物ID% | 指定怪物的累计击杀触发记录 | 0 |
%tjr_trigger_first_kill_怪物ID% | 指定怪物的首次击杀触发记录 | 0 |
击杀监听会将数据保存为以下记录：
text
kill_怪物ID
first_kill_怪物ID其中，kill_怪物ID 会在每次符合监听条件的击杀事件中累计；first_kill_怪物ID 用于记录首次击杀状态，通常返回 1。
怪物参数的来源取决于击杀监听类型：
| 监听来源 | 使用的怪物参数 |
|---|---|
| Bukkit 原版实体 | 实体类型名称，例如实体的 Bukkit 类型名 |
| 带自定义名称的特定实体 | 实体自定义名称 |
| CustomNPCs 实体 | 插件读取到的 NPC 名称 |
| MythicMobs 4 | MythicMobs 内部怪物 ID |
| MythicMobs 5 | MythicMobs 内部怪物 ID |
/tjr addkill | 指令中填写的怪物 ID |
%tjr_trigger_kill_怪物ID% 和 %tjr_trigger_first_kill_怪物ID% 读取的是玩家数据中的触发记录。对应记录不存在时返回 0。
当启用 enable-bukkit-death-event 时，插件会监听 Bukkit 实体死亡事件；该配置关闭后，Bukkit 原版实体击杀监听不会注册。若服务器启用了 MythicMobs，插件会根据 MythicMobs 主版本注册对应的击杀监听。
拾取触发变量
| 变量 | 返回内容 | 无记录时 |
|---|---|---|
%tjr_trigger_pickup_name_物品名% | 按物品显示名称成功触发图鉴收集的累计次数 | 0 |
%tjr_trigger_pickup_lore_物品Lore% | 按物品 Lore 行成功触发图鉴收集的累计次数 | 0 |
%tjr_trigger_pickup_id_物品ID% | 按物品数字 ID 与附加值成功触发图鉴收集的累计次数 | 0 |
拾取记录只有在以下条件全部满足后才会增加：
- 物品符合对应的名称、Lore 或数字 ID 条件。
- 图鉴收集前置条件通过。
- 图鉴当前收集次数未达到
max-collect-count。 chance概率判断成功。- 图鉴收集次数成功增加。
名称匹配使用物品的完整显示名称，并将配置参数中的 & 转换为 Minecraft 颜色符号后进行匹配。
Lore 匹配会检查物品 Lore 中是否存在与配置参数完全相同的 Lore 行。配置参数中的 & 会转换为 Minecraft 颜色符号后再匹配。
物品 ID 使用旧版数字 ID 与附加值格式，例如：
text
167:0这些变量表示成功触发图鉴收集的记录，不表示玩家拾取该物品的全部次数。
使用物品触发变量
| 变量 | 返回内容 | 无记录时 |
|---|---|---|
%tjr_trigger_use_name_物品名% | 按物品显示名称成功触发图鉴收集的累计次数 | 0 |
%tjr_trigger_use_lore_物品Lore% | 按物品 Lore 行成功触发图鉴收集的累计次数 | 0 |
%tjr_trigger_use_id_物品ID% | 按物品数字 ID 与附加值成功触发图鉴收集的累计次数 | 0 |
使用物品触发只处理玩家主手持有的物品，以及以下两种右键操作：
- 右键空气。
- 右键方块。
名称、Lore 和数字 ID 的匹配规则与拾取触发变量相同。只有匹配图鉴收集条件、通过概率判断并成功增加图鉴收集次数时，对应的 trigger_use 记录才会增加。
使用物品触发时，符合条件的主手物品会先扣除 1 个。即使后续 chance 判断失败，已扣除的物品也不会返还；概率失败时不会增加对应的 trigger_use 记录，并可能发送 config.yml 中 message.use-item-failed 配置的消息。
这些变量表示成功触发图鉴收集的使用记录，不表示玩家所有右键使用次数。
属性预览变量
| 变量 | 返回内容 |
|---|---|
%tjr_attribute_图鉴ID_次数_行号% | 指定图鉴在指定收集次数下的属性行 |
%tjr_attribute_图鉴ID_now_行号% | 指定图鉴在玩家当前收集次数下的属性行 |
%tjr_attribute_图鉴ID_next_行号% | 指定图鉴在玩家当前收集次数加一后的属性行 |
参数说明
| 参数 | 说明 |
|---|---|
图鉴ID | 图鉴配置中的 id，不能包含下划线 |
次数 | 用于选择图鉴 attribute 节点的整数收集次数 |
now | 使用玩家当前的图鉴收集次数 |
next | 使用玩家当前收集次数加一 |
行号 | 属性列表的索引，从 0 开始 |
图鉴属性支持单独次数和次数区间配置，例如：
yaml
attribute:
1:
- '§a攻击力 +5'
2-9:
- '§a攻击力 +<{count}*1~%.0f>'
10:
- '§a攻击力 +10'属性变量返回指定次数对应的属性列表中的一行。属性文本会处理以下内容：
- 将
{count}替换为当前计算使用的收集次数。 - 计算属性文本中由尖括号包裹的数字公式。
- 支持使用
~指定格式化字符串，例如~%.0f。 - 图鉴配置了
attribute-addition-placeholder时，根据该 PlaceholderAPI 变量的数值计算额外加成。
attribute-addition-placeholder 的返回值会作为百分比加成参与公式计算。例如返回正数时，属性公式会按额外比例计算。
指定图鉴不存在、属性行号超出范围，或使用固定次数变量时次数不符合属性配置时，变量返回空文本。图鉴存在但该次数对应的属性配置为空时，底层属性读取可能返回默认的 §7无 文本。
变量与玩家数据
玩家数据中主要保存以下内容：
| 数据类别 | 保存内容 |
|---|---|
| 图鉴收集数据 | 各图鉴当前收集次数 |
| 触发记录 | 击杀、首次击杀、拾取和使用物品等触发次数 |
| 套装状态 | 已激活的套装 ID |
玩家数据默认保存为插件数据目录下按玩家 UUID 命名的 YAML 文件。启用 MySQL 存储后，数据改为保存到数据库。
返回规则
| 情况 | 返回结果 |
|---|---|
| 玩家对象为空 | 空文本 |
| 玩家数据尚未加载 | 空文本 |
| 不存在的触发记录 | 0 |
| 不存在的图鉴收集记录 | 0 |
| 不存在的图鉴最大次数 | 0 |
| 不存在的套装累计次数 | 0 |
| 不存在的属性行 | 空文本 |
| 图鉴存在但属性内容返回默认值 | §7无 |
| 无法识别的变量名称 | §c错误 |
变量读取的是当前服务器内存中的玩家数据。玩家数据发生变化后，插件会按照 auto-save-interval 配置的间隔自动保存；变量读取本身不要求等待下一次保存。
前置与注意事项
PlaceholderAPI是变量功能的必要前置。未安装或未启用时，插件不会注册%tjr_...%变量。- 配置中的图鉴 ID、套装 ID、怪物 ID、物品名称和 Lore 参数必须与插件实际读取到的内容一致。
- 属性变量的次数和行号必须填写整数，行号从
0开始。 - 属性变量中的图鉴 ID 不应包含下划线，否则会影响参数拆分。
%tjr_collect_suit_套装ID%是套装内各图鉴收集次数之和，不是套装收藏分；套装收藏分应使用%tjr_suit_point_套装ID%。%tjr_trigger_pickup_...%与%tjr_trigger_use_...%读取成功触发记录，不等同于物品的实际拾取次数或右键次数。- 玩家刚进入服务器、数据仍在异步加载时，变量可能暂时返回空文本。
- 启用 MySQL 存储后，必须安装
LyMySQLCore，并确保LyMySQLCore已成功连接数据库；否则玩家数据无法正常加载，相关变量也不会正常返回。 - MySQL 存储开关通过
config.yml的mysql.enable控制，切换数据库模式后需要重启服务器。