图鉴重置版 LyGuideReload

MySQL 前置要求

启用 MySQL 存储时，必须安装 LyMySQLCore，并确认它已成功连接数据库。否则本插件的 MySQL 数据读取、保存、同步和相关记录不会生效。

LyGuideReload 是一款 Minecraft 图鉴收集插件。管理员可以配置图鉴、图鉴套装、收集条件、收集次数、收藏分、属性和奖励指令，玩家通过击杀怪物、使用物品或管理指令增加图鉴收集进度。

插件提供图鉴套装总览、套装详情、套装分类和分页界面，可用于怪物图鉴、装备收藏、材料消耗、成就进度、收藏分阶段奖励和套装属性等玩法。

插件信息

项目	内容
插件名	`LyGuideReload`
插件版本	`1.0.6`
作者	`Liyuan`
主命令	`/tjr`
Bukkit API 版本	`1.13`
Java 编译版本	Java 8
图鉴目录	`plugins/LyGuideReload/guide`
套装目录	`plugins/LyGuideReload/suit`
YAML 数据目录	`plugins/LyGuideReload/data`

项目的 plugin.yml 声明 Bukkit API 版本为 1.13，构建配置使用 Java 8。项目文件没有提供更具体的 Minecraft 服务端版本范围，安装前应根据实际服务端和依赖插件版本进行兼容性测试。

依赖与软依赖

插件在 plugin.yml 中将下列插件声明为软依赖。插件本体可以在部分软依赖缺失时加载，但对应功能不会生效。

插件	用途	使用要求
`LyMySQLCore`	MySQL 玩家数据存储	启用 `mysql.enable` 时必须安装，并确认数据库连接成功
`PlaceholderAPI`	插件变量、界面变量、Lore 变量和 `papi` 收集条件	未安装时，相关变量和变量条件不可用
`AttributePlus`	应用图鉴、套装和收藏分属性	`attribute-plugin` 设置为 `AttributePlus`
`SX-Attribute`	SX-Attribute 2 或 3 属性适配	`attribute-plugin` 设置为 `SX-Attribute2` 或 `SX-Attribute3`
`AttributeSystem`	属性插件选项	当前项目中的实际属性写入代码被注释，不能确认属性会生效
`ItemLoreOrigin`	通过虚拟物品 Lore 提供属性	`attribute-plugin` 设置为 `ItemLoreOrigin`
`MythicMobs`	MythicMobs 怪物击杀监听	插件会根据 MythicMobs 主版本注册 4.x 或 5.x 监听器

PlaceholderAPI 不只是变量扩展。图鉴条件、图鉴 Lore、套装 Lore和收藏分界面也会调用 PlaceholderAPI，因此使用相关内容时应安装该插件。

核心功能

功能	说明
独立图鉴配置	每个图鉴拥有 ID、名称、Lore、图标、基础收藏分和最大收集次数
图鉴收集条件	支持已有图鉴、未拥有图鉴、权限、反权限和 PlaceholderAPI 表达式
多次收集	同一图鉴可以重复收集，收集次数不会超过 `max-collect-count`
概率收集	收集方式和 `/tjr try` 支持 `0` 到 `1` 的概率
怪物击杀记录	保存怪物累计击杀次数和首次击杀记录
物品使用收集	可按主手物品名称、Lore 行或数字物品 ID 匹配，匹配后消耗一个物品
图鉴收藏分	按基础收藏分乘以当前收集次数计算
收藏分阶段	根据总收藏分选择已达到的最高阶段称号和属性
图鉴属性	可按单独次数或次数范围配置属性文本，并支持公式计算
属性额外加成	可通过 PlaceholderAPI 变量按百分比放大图鉴属性公式结果
图鉴套装	多个图鉴组成套装，集齐后获得收藏分并执行一次套装指令
套装属性	可要求累计收集次数、总收藏分和全部部件已收集
套装分类	可将多个套装归入分类，并打开指定分类界面
图鉴界面	支持套装总览、套装分类、套装详情和每页 45 项的分页浏览
图鉴点击指令	点击套装详情中的图鉴图标时执行该图鉴的 `click-command`
已收集标记	已收集图鉴可添加耐久附魔效果，并在套装列表显示次数和上限
获得提示	增加图鉴次数时可以显示标题和副标题
数据存储	支持本地 YAML 文件和 MySQL 两种模式
自动保存	按配置间隔异步保存发生过数据变更的在线玩家
YAML 备份恢复	正常保存玩家 YAML 数据时使用安全写入与备份恢复工具
PlaceholderAPI	提供收藏分、称号、收集次数、属性和触发记录变量
开发者 API	提供增加、扣除、设置、读取和概率尝试收集的方法
指令补全	支持子命令、在线玩家、图鉴 ID、套装 ID、分类 ID、次数和概率补全

图鉴玩法机制

收集次数

每个图鉴通过 max-collect-count 设置最大收集次数。增加或设置次数时，插件会把结果限制在 0 到最大收集次数之间。

增加图鉴收集次数时会执行以下处理：

更新玩家的图鉴收集次数。
执行当前次数对应的 get-command。
显示获得图鉴的标题和副标题。
检查相关套装是否首次集齐。
重新计算玩家的图鉴、套装和收藏分属性。
将玩家数据标记为需要自动保存。

扣除或直接设置图鉴次数不会执行图鉴获得指令和获得提示，但仍会检查套装状态并刷新属性。

收集前置条件

图鉴的 collect-condition 支持以下条件：

条件格式	判定规则
`guide:{图鉴ID}`	玩家已经收集过指定图鉴
`noguide:{图鉴ID}`	玩家尚未收集指定图鉴
`permission:{权限}`	玩家拥有指定权限
`nopermission:{权限}`	玩家没有指定权限
`papi:{表达式}`	PlaceholderAPI 替换后，表达式结果为真

所有条件必须同时满足。papi 表达式的实现支持 &&、||、>=、<=、==、!=、> 和 < 等判断。

通过 /tjr give 或开发者 API 的增加方法直接发放图鉴时，不检查 collect-condition。通过 /tjr try 或 API 的概率尝试方法收集时，会先检查这些条件。

收集方式

项目配置示例列出了以下收集方式：

收集方式	参数	设计用途
`first_kill`	`name`、`chance`	首次击杀指定怪物时尝试收集
`kill`	`name`、`amount`、`chance`	对指定怪物累计击杀，每达到对应倍数时尝试收集
`pickup_name`	`name`、`chance`	拾取显示名称完全匹配的物品时尝试收集
`pickup_lore`	`lore`、`chance`	拾取包含完全匹配 Lore 行的物品时尝试收集
`pickup_id`	`id`、`chance`	拾取数字物品 ID 和数据值匹配的物品时尝试收集
`use_name`	`name`、`chance`	右键使用显示名称完全匹配的主手物品
`use_lore`	`lore`、`chance`	右键使用包含完全匹配 Lore 行的主手物品
`use_id`	`id`、`chance`	右键使用数字物品 ID 和数据值匹配的主手物品

kill 会记录 kill_怪物ID，只有当前累计次数是 amount 的整数倍时才进行概率判定。原版怪物监听使用实体类型名称；MythicMobs 监听使用 MythicMobs 内部 ID。

use_name、use_lore 和 use_id 在物品匹配且前置条件通过后，会先扣除主手中的一个物品，再进行概率判定。概率失败时物品不会返还，并会发送 message.use-item-failed。

当前版本实现限制

项目中的 GuideData 只注册了 first_kill、kill、use_name、use_lore 和 use_id。虽然存在拾取监听器和拾取配置示例，但 pickup_name、pickup_lore、pickup_id 没有在图鉴加载阶段注册，按当前代码无法触发。

首次击杀监听会先写入 first_kill_怪物ID，随后又在图鉴判断中因该记录已存在而跳过，因此 first_kill 按当前代码也无法正常触发。需要使用当前构建实测，或改用 kill、use_*、/tjr try 和 /tjr give。

怪物监听

类型	行为
Bukkit 实体	`enable-bukkit-death-event: true` 时注册 `EntityDeathEvent` 监听
普通实体	默认使用 Bukkit 实体类型名称作为怪物 ID
自定义名称实体	特定实体类型下可能使用实体自定义名称
CustomNPCs 实体	检测到对应实体类型时读取实体名称
MythicMobs 4	监听 MythicMobs 4 的怪物死亡事件，使用内部 ID
MythicMobs 5	监听 MythicMobs 5 的怪物死亡事件，使用内部 ID

关闭 enable-bukkit-death-event 只会关闭 Bukkit 原版实体死亡监听，不会阻止已安装的 MythicMobs 监听注册。

收藏分与属性

图鉴收藏分

图鉴收藏分按照以下规则计算：

text

图鉴收藏分 = base-point × 当前收集次数

例如图鉴的 base-point 为 5，玩家收集了 3 次，该图鉴提供 15 点收藏分。

套装收藏分

套装内所有有效图鉴至少收集一次后，套装视为完成，并提供套装文件中 point 配置的收藏分。

玩家总收藏分由以下内容相加：

text

总收藏分 = 所有图鉴收藏分 + 所有已完成套装收藏分

同一个图鉴可以同时属于多个套装。图鉴自身收藏分只会在总收藏分中计算一次，但每个已完成套装的套装收藏分会分别计入。

收藏分阶段

主配置的 point 节点可以按总收藏分配置称号和属性。玩家同时达到多个阶段时，插件选择数值最高且已达到的阶段，不会叠加多个阶段的属性。

对应称号可以通过 %tjr_tag_point% 获取，阶段属性会加入玩家的总属性列表。

图鉴属性

图鉴的 attribute 节点支持单独次数和次数范围：

yaml

attribute:
  1:
    - '§a攻击力 +5'
  2-9:
    - '§a攻击力 +<{count}*1~%.0f>'
  10:
    - '§a攻击力 +10'

写法	说明
`1`	收集次数等于 `1` 时使用
`2-9`	收集次数在 `2` 到 `9` 之间时使用
`{count}`	当前图鉴收集次数
`<公式~格式>`	计算公式，并用指定数字格式输出

公式计算支持数字、括号以及 +、-、*、/。未提供格式时默认使用 %.0f。

attribute-addition-placeholder 可以填写一个 PlaceholderAPI 变量。变量结果大于 0 时，会按百分比增加公式结果。例如变量返回 20，公式最终结果乘以 1.2。该加成只影响尖括号公式，不会修改普通文本中的数字。

套装属性

套装属性必须同时满足以下条件：

套装内所有有效图鉴至少收集一次。
套装内所有图鉴的累计收集次数不低于 effective-attribute-need-count。
玩家总收藏分不低于 effective-attribute-point。

套装首次集齐时会记录到玩家数据的 enabled-suit，并执行一次 collected-command。该记录用于防止套装集齐指令重复执行。

图鉴界面

插件使用 54 格箱子界面，其中前 45 格用于展示内容，最后一行用于翻页、填充和收藏分信息。

界面	打开方式	显示内容
套装总览	`/tjr opent`	所有已加载套装
套装分类	`/tjr class <分类ID>`	分类中存在且已加载的套装
套装详情	`/tjr opens <套装ID>` 或点击套装	套装中的图鉴条目

套装总览和分类界面会在套装 Lore 后追加各图鉴的收集状态。套装详情会处理图鉴 Lore 中的以下内容：

内容	替换结果
`{count}`	当前收集次数
`{max}`	最大收集次数
`{base_point}`	图鉴基础收藏分
`{result_point}`	当前图鉴收藏分
`{attribute}`	当前收集次数对应的属性列表
PlaceholderAPI 变量	当前玩家对应的变量结果

玩家点击套装详情中的图鉴图标时，会执行该图鉴的 click-command。关闭插件界面时，插件会刷新玩家属性缓存。

数据存储

YAML 模式

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

text

plugins/LyGuideReload/data/玩家UUID.yml

保存内容包括：

数据节点	内容
`collected-guide`	各图鉴的收集次数
`trigger-list`	击杀、拾取和使用行为的触发记录
`enabled-suit`	已执行过首次集齐指令的套装 ID

玩家加入时异步读取数据，正常退出或被踢出服务器时异步保存数据。正常的 YAML 保存流程使用安全写入工具，并支持从备份恢复读取。

MySQL 模式

当 mysql.enable 为 true 时，插件通过 LyMySQLCore 提供的安全加载和保存事件处理玩家数据，并将序列化后的 YAML 数据写入以插件名称命名的数据库表。

警告

MySQL 模式必须安装 LyMySQLCore，并确保它已经成功连接数据库。只填写 mysql 节点但未安装或未连接 LyMySQLCore，不会得到可用的 MySQL 玩家数据功能。

插件以玩家名称查询和更新数据库记录，而本地 YAML 模式使用玩家 UUID 作为文件名。

自动保存

auto-save-interval 以秒为单位。自动保存任务会异步扫描在线玩家，只保存已被标记为发生过数据变更的玩家。

插件重载时会停止旧的自动保存任务，重新载入配置、图鉴、套装和分类，然后重新启动任务。重载期间已打开的图鉴界面会被强制关闭。

指令

主命令为 /tjr。项目没有在 plugin.yml 中声明独立权限节点，管理指令直接通过 OP 状态判断。

指令	使用者	说明
`/tjr`	OP	显示插件指令帮助
`/tjr reload`	OP	重载主配置、图鉴、套装和套装分类
`/tjr update <玩家>`	OP	刷新指定在线玩家的图鉴属性缓存
`/tjr opent`	玩家	打开图鉴套装总览
`/tjr class <分类ID>`	玩家	打开指定套装分类
`/tjr opens <套装ID>`	玩家	打开指定图鉴套装
`/tjr addkill <玩家> <怪物ID> <次数>`	OP	增加怪物击杀记录，并判断对应的击杀图鉴
`/tjr give <玩家> <图鉴ID> <次数>`	OP	增加图鉴收集次数，并执行获得效果
`/tjr take <玩家> <图鉴ID> <次数>`	OP	扣除图鉴收集次数，不执行获得效果
`/tjr set <玩家> <图鉴ID> <次数>`	OP	直接设置图鉴收集次数，不执行获得效果
`/tjr try <玩家> <图鉴ID> <概率>`	OP	检查收集条件后，按概率尝试增加一次图鉴收集次数

<玩家>、<怪物ID>、<图鉴ID>、<套装ID> 和 <分类ID> 是实际参数，使用时不输入尖括号。

指令行为

give、take、set、try 和 addkill 只接受在线且数据已经加载的玩家。
give、take 和 set 会验证图鉴 ID 是否存在。
give 不检查图鉴的 collect-condition。
try 会检查 collect-condition，大于 1 的概率会被限制为 1。
take 和 set 不执行图鉴 get-command，但会刷新套装状态和属性。
give 会执行图鉴 get-command、获得标题和套装首次集齐检查。
reload 会覆盖插件内置的示例图鉴和示例套装文件。

/tjr update 已知问题

帮助文本和参数补全要求使用 /tjr update <玩家>，但当前命令代码只在参数数量为 1 时进入该分支，随后又读取第二个参数。按当前代码，该指令存在参数判断错误，不能正常使用。

指令补全

插件提供以下 Tab 补全：

参数位置	补全内容
一级子命令	根据是否为 OP 和是否为玩家显示可用子命令
管理指令的玩家参数	当前在线玩家名称
`give`、`take`、`set`、`try` 的图鉴参数	已加载的图鉴 ID
`opens` 的套装参数	已加载的套装 ID
`class` 的分类参数	已加载的分类 ID
次数参数	`1`、`10`、`64`、`100`
概率参数	`0`、`0.1`、`0.5`、`1`

addkill 的怪物 ID 补全只提供静态示例值，不代表服务器实际存在这些怪物。

PlaceholderAPI 变量

插件注册的变量标识符为 tjr。完整参数规则和返回值见插件变量。

变量	说明
`%tjr_all_point%`	玩家全部收藏分
`%tjr_tag_point%`	当前收藏分阶段称号
`%tjr_guide_point_图鉴ID%`	指定图鉴提供的收藏分
`%tjr_suit_point_套装ID%`	指定套装及其子图鉴提供的总收藏分
`%tjr_collect_count_图鉴ID%`	指定图鉴当前收集次数
`%tjr_collect_max_图鉴ID%`	指定图鉴最大收集次数
`%tjr_collect_suit_套装ID%`	指定套装内全部图鉴的累计收集次数
`%tjr_trigger_kill_怪物ID%`	指定怪物的累计击杀次数
`%tjr_trigger_first_kill_怪物ID%`	指定怪物的首次击杀记录
`%tjr_trigger_pickup_name_物品名%`	按名称成功拾取收集的记录
`%tjr_trigger_pickup_lore_物品Lore%`	按 Lore 成功拾取收集的记录
`%tjr_trigger_pickup_id_物品ID%`	按数字 ID 成功拾取收集的记录
`%tjr_trigger_use_name_物品名%`	按名称成功使用收集的次数
`%tjr_trigger_use_lore_物品Lore%`	按 Lore 成功使用收集的次数
`%tjr_trigger_use_id_物品ID%`	按数字 ID 成功使用收集的次数
`%tjr_attribute_图鉴ID_次数_行数%`	指定收集次数下的属性行
`%tjr_attribute_图鉴ID_now_行数%`	当前收集次数下的属性行
`%tjr_attribute_图鉴ID_next_行数%`	下一收集次数下的属性行

属性变量的行数从 0 开始。玩家数据尚未加载时，插件变量返回空字符串。

开发者 API

插件客户端模块公开 LyGuideReloadAPI 接口，运行时由核心模块设置实现。主要方法如下：

方法	说明
`giveGuideCollectedCount(Player player, String id, int count)`	增加指定图鉴的收集次数
`takeGuideCollectedCount(Player player, String id, int count)`	扣除指定图鉴的收集次数
`setGuideCollectedCount(Player player, String id, int count)`	设置指定图鉴的收集次数
`getGuideCollectedCount(Player player, String id)`	获取指定图鉴的收集次数
`tryGiveGuide(Player player, String id, double chance)`	检查前置条件后，按概率尝试增加一次收集次数

API 只处理已经存在于玩家数据缓存中的玩家。玩家数据未加载时，增加、扣除和设置方法不会执行，读取方法返回 0。

giveGuideCollectedCount 会触发图鉴获得指令、获得标题、套装首次集齐检查和属性刷新。收集次数仍受图鉴最大收集次数限制。

调用 tryGiveGuide 前应先确认图鉴 ID 存在。该方法本身直接读取图鉴对象，没有处理不存在的 ID。

已知实现差异

以下内容由当前 1.0.6 项目代码确认：

项目	当前行为
拾取收集方式	存在监听器和示例配置，但图鉴加载器没有注册 `pickup_*` 方法
首次击杀	监听器先写入首次击杀记录，再检查记录，导致 `first_kill` 被跳过
属性插件 `AttributeSystem`	配置选项存在，但实际属性调用代码被注释
`/tjr update`	参数数量判断和参数读取不一致
获得图鉴音效	默认配置键为 `get-guide-sound`，增加图鉴时读取的却是 `get-suit-sound`
示例文件	每次重载都会以覆盖模式保存内置示例文件

建议不要直接修改 示例图鉴.yml 和 示例套装.yml。应复制为其他文件名后再配置，并通过 load-default-config: false 跳过加载默认示例。

配置与扩展页面

页面	内容
主配置说明	`config.yml` 的属性插件、自动保存、怪物监听、MySQL、提示、界面、分类和收藏分配置
图鉴配置	`guide` 目录下图鉴文件的字段、条件、收集方式、属性和指令
插件变量	PlaceholderAPI 变量格式、参数和返回值
常见问题	依赖、数据存储、收集触发、属性和界面问题排查
更新日志	插件和文档更新记录

图鉴重置版 LyGuideReload ​

插件信息 ​

依赖与软依赖 ​

核心功能 ​

图鉴玩法机制 ​

收集次数 ​

收集前置条件 ​

收集方式 ​

怪物监听 ​

收藏分与属性 ​

图鉴收藏分 ​

套装收藏分 ​

收藏分阶段 ​

图鉴属性 ​

套装属性 ​

图鉴界面 ​

数据存储 ​

YAML 模式 ​

MySQL 模式 ​

自动保存 ​

指令 ​

指令行为 ​

指令补全 ​

PlaceholderAPI 变量 ​

开发者 API ​

已知实现差异 ​

配置与扩展页面 ​

图鉴重置版 LyGuideReload

插件信息

依赖与软依赖

核心功能

图鉴玩法机制

收集次数

收集前置条件

收集方式

怪物监听

收藏分与属性

图鉴收藏分

套装收藏分

收藏分阶段

图鉴属性

套装属性

图鉴界面

数据存储

YAML 模式

MySQL 模式

自动保存

指令

指令行为

指令补全

PlaceholderAPI 变量

开发者 API

已知实现差异

配置与扩展页面