配置说明

LyGuideReload 的配置文件分为主配置、图鉴配置、套装配置和玩家数据。

路径	用途
`plugins/LyGuideReload/config.yml`	数据保存、属性处理、提示、界面、套装分类和收藏分阶段配置
`plugins/LyGuideReload/guide/*.yml`	定义图鉴名称、图标、收集条件、收集方式、属性和指令
`plugins/LyGuideReload/suit/*.yml`	定义套装包含的图鉴、收藏分、属性门槛和集齐指令
`plugins/LyGuideReload/data/*.yml`	未启用 MySQL 时生成的玩家数据，不是管理员配置文件

guide 和 suit 目录会递归读取全部 .yml 文件，可以使用子目录整理配置。图鉴 ID 和套装 ID 应分别保持唯一。

主配置 `config.yml`

属性插件

yaml

attribute-plugin: 'AttributePlus'

attribute-plugin 决定图鉴属性、套装属性和收藏分阶段属性的处理方式。该配置在插件启动时读取，修改后需要重启服务器，不能只执行重载。

值	处理方式
`AttributePlus`	调用 AttributePlus 写入玩家属性
`SX-Attribute2`	使用 SX-Attribute 2.x 接口写入属性
`SX-Attribute3`	使用 SX-Attribute 3.x 接口写入属性
`ItemLoreOrigin`	将属性行整理为虚拟物品 Lore，交给 ItemLoreOrigin 处理
`AttributeSystem`	配置值可以被识别，但当前版本没有实际写入属性的代码

使用对应属性模式时，需要安装并成功加载对应属性插件。插件声明的软依赖包括 AttributePlus、SX-Attribute、AttributeSystem 和 ItemLoreOrigin。

使用 ItemLoreOrigin 时，可以配置属性刷新任务周期：

yaml

ilo-update-task: 20

配置项	默认值	说明
`ilo-update-task`	`20`	ItemLoreOrigin 属性刷新任务的周期，单位为 Tick。默认配置文件未写出此项，插件会使用代码默认值。

自动保存

yaml

auto-save-interval: 3

配置项	默认值	说明
`auto-save-interval`	`3`	自动保存检查周期，单位为秒。

自动保存任务会遍历在线玩家，仅保存已经发生数据变化的玩家。无论使用本地 YAML 还是 MySQL，都会使用此配置的周期。

原版生物死亡监听

yaml

enable-bukkit-death-event: true

值	说明
`true`	注册 Bukkit `EntityDeathEvent`，处理原版实体及兼容实体的击杀收集。
`false`	不注册 Bukkit 原版死亡监听。使用 MythicMobs 时可以关闭，以减少不需要的事件处理。

此配置只控制 Bukkit 原版死亡事件，不控制 MythicMobs 监听。服务器检测到 MythicMobs 已启用后，会根据版本注册 MythicMobs 4 或 MythicMobs 5 的死亡监听。

MySQL 存储

MySQL 前置要求

启用 MySQL 存储时，必须安装 LyMySQLCore，并确认 LyMySQLCore 已成功连接数据库。只有前置正常加载、数据库连接成功并触发对应安全读写事件后，玩家数据加载、保存和同步才会生效。

yaml

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

配置项	默认值	说明
`mysql.enable`	`false`	是否启用 MySQL 存储。切换后需要重启服务器。
`mysql.databasename`	`mc2`	数据库名称。
`mysql.username`	`mc2`	数据库用户名。
`mysql.password`	`mc1234`	数据库密码。
`mysql.port`	`3306`	数据库端口。
`mysql.ip`	`127.0.0.1`	数据库地址。

启用后，插件通过 HikariCP 建立连接池，并创建名为 LyGuideReload 的数据表。表中根据玩家名称查询数据，玩家的图鉴次数、触发记录和已激活套装会序列化保存到 data 字段。

未启用 MySQL 时，玩家数据保存到：

text

plugins/LyGuideReload/data/玩家UUID.yml

本地数据结构如下：

yaml

collected-guide:
  test: 1
trigger-list:
  kill_example_mob: 10
enabled-suit:
  - '示例套装'

节点	说明
`collected-guide`	图鉴 ID 与玩家已收集次数。
`trigger-list`	击杀、拾取和使用物品等触发记录。
`enabled-suit`	已经首次集齐并执行过集齐指令的套装 ID。

默认示例配置

yaml

load-default-config: true

插件执行重载时，会覆盖写出以下两个内置示例文件：

text

plugins/LyGuideReload/guide/示例图鉴.yml
plugins/LyGuideReload/suit/示例套装.yml

load-default-config 只控制读取时是否跳过内置示例文件，不控制示例文件是否生成。

值	说明
`true`	读取 `示例图鉴.yml` 和 `示例套装.yml`。
`false`	读取目录时跳过这两个固定文件，但重载时仍然覆盖生成它们。

不要直接在内置示例文件中编写正式内容。应复制文件并改名后再编辑，否则执行重载时内容会被覆盖。

获取图鉴提示

yaml

get-guide-title: '&6{guide}x{count}'
get-guide-sub-title: '&7恭喜你获得了图鉴!'
get-guide-sound: 'ORB_PICKUP'

配置项	可用内容	说明
`get-guide-title`	`{guide}`、`{count}`、`&` 颜色代码	获得图鉴时显示的标题。
`get-guide-sub-title`	`{guide}`、`{count}`、`&` 颜色代码	获得图鉴时显示的副标题。
`get-guide-sound`	Bukkit 音效名称	默认文件中的获取音效配置。

标题和副标题必须同时存在才会发送获取提示。删除其中任意一项后，获得图鉴时不会发送标题。

获取音效的实际读取键

当前版本的获得图鉴代码实际读取 get-suit-sound，而不是默认配置中的 get-guide-sound。如果需要修改获得图鉴音效，应额外配置以下键：

yaml

get-suit-sound: 'ORB_PICKUP'

音效名称必须与服务器版本支持的 Bukkit 音效名称一致。

已收集图鉴附魔光效

yaml

guide-enchant: true

值	说明
`true`	玩家已收集过的图鉴在套装详情界面显示耐久附魔光效。
`false`	不显示附魔光效。

此配置只影响界面显示，不改变图鉴次数、收藏分或属性。

界面点击音效

yaml

click-sound: 'ORB_PICKUP'

翻页、打开套装或点击图鉴时播放该音效。配置为空字符串时不播放音效。

套装分类

yaml

suit-class:
  分类1:
    - '套装1'
    - '套装2'

suit-class 的直属节点是分类 ID，每个分类节点下保存套装 ID 列表。

部分	说明
`分类1`	分类 ID，用于分类界面命令的参数。
列表内容	已在 `suit/*.yml` 中定义的套装 ID。

分类只保存套装引用，不支持单独设置分类名称、图标或 Lore。引用不存在的套装 ID 时，该项会被忽略。分类中的套装按照列表顺序显示。

自定义消息

yaml

message:
  use-item-failed: '&c获取图鉴失败, 本次使用没有获得该图鉴.'

配置项	触发时机
`message.use-item-failed`	`use_name`、`use_lore` 或 `use_id` 匹配成功、物品已被消耗，但概率判定失败时发送。

设置为空字符串可以关闭该消息。使用类收集方式会先扣除主手中的一个物品，再进行概率判定，概率失败时不会返还物品。

GUI 界面

yaml

gui:
  total-title: '图鉴系统'
  suit-title: '图鉴套装: {suit}'
  fill-item: '160:9'
  fill-name: '&7封锁'
  next-item1: '341:0'
  next-name1: '&6上一页'
  next-item2: '341:0'
  next-name2: '&6下一页'
  info-item: '116:0'
  info-name: '&6图鉴收藏分'
  info-lore:
    - ''
    - '&7当前总图鉴收藏分: &6%tjr_all_point%'
    - '&7收藏分称号: %tjr_tag_point%'
    - '&7收藏分属性:'
    - '{attribute}'
    - ''

配置项	说明
`gui.total-title`	套装总览和套装分类界面的标题。
`gui.suit-title`	套装详情界面的标题，支持 `{suit}`。
`gui.fill-item`	底部空位使用的填充物品。
`gui.fill-name`	填充物品名称。
`gui.next-item1`	上一页按钮物品。
`gui.next-name1`	上一页按钮名称。
`gui.next-item2`	下一页按钮物品。
`gui.next-name2`	下一页按钮名称。
`gui.info-item`	收藏分信息物品。
`gui.info-name`	收藏分信息物品名称。
`gui.info-lore`	收藏分、称号和当前收藏分阶段属性的 Lore。

每页前 45 个槽位用于显示套装或图鉴，第 46 格用于上一页按钮，第 54 格用于下一页按钮，第 50 格用于收藏分信息。

物品可以使用英文材质名称，也可以使用旧版数字 ID 格式：

yaml

fill-item: 'STAINED_GLASS_PANE'
next-item1: '341:0'

gui.info-lore 会经过 PlaceholderAPI 解析。单独一行 {attribute} 会替换为玩家当前收藏分阶段的属性列表。

套装成员状态 Lore

yaml

guide-collected-lore: '{guide}      &7>> 未收集'
guide-not-collected-lore: '{guide}      &a>> 已收集&6{count}/{max}&a次'

配置名称与实际显示条件相反，应按照实际条件配置：

配置项	实际显示条件	可用内容
`guide-collected-lore`	图鉴收集次数为 `0`	`{guide}`
`guide-not-collected-lore`	图鉴收集次数大于 `0`	`{guide}`、`{count}`、`{max}`

这些文本会追加到套装总览和分类界面的套装 Lore 底部。

收藏分阶段

yaml

point:
  1:
    tag: '&7无名小卒'
    attribute:
      - '&a攻击力 +5'
  10:
    tag: '&f初出茅庐'
    attribute:
      - '&a攻击力 +12'
  100:
    tag: '&a初露锋芒'
    attribute:
      - '&a攻击力 +32'

配置部分	说明
阶段数字	生效所需的最低总收藏分，必须是整数。
`tag`	当前阶段称号，可通过 `%tjr_tag_point%` 读取。
`attribute`	当前阶段提供的属性行。

玩家达到多个阶段时，只使用满足条件的最高阶段属性，不会叠加所有低阶段属性。总收藏分由全部图鉴收藏分和已集齐套装奖励分相加得到。

图鉴配置 `guide/*.yml`

每个 .yml 文件定义一个图鉴。目录会递归读取，全部图鉴的 id 必须唯一。

基础信息

yaml

id: 'test'
name: '&6示例图鉴'
lore:
  - '&7该图鉴已收集 &a{count}/{max} &7次'
  - '&7每次收集可获得 &6{base_point}&7 点收藏分'
  - '&7当前收藏分: &6{result_point}'
  - '&7收集属性:'
  - '{attribute}'
item: 'APPLE'
max-collect-count: 10
base-point: 1

配置项	默认值	说明
`id`	无	图鉴唯一 ID，用于套装引用、变量和 API。
`name`	无	图鉴显示名称，支持 `&` 颜色代码。
`lore`	空列表	套装详情界面中的图鉴说明。
`item`	`APPLE`	图鉴图标，可以使用英文材质名称或旧版 `数字ID:子ID` 格式。
`max-collect-count`	`1`	玩家最多可以收集的次数。
`base-point`	`0`	每次收集增加的收藏分。

单个图鉴提供的收藏分为：

text

已收集次数 × base-point

图鉴 Lore 支持以下内部替换内容：

内容	说明
`{count}`	当前已收集次数。
`{max}`	最大收集次数。
`{base_point}`	单次收集提供的收藏分。
`{result_point}`	当前图鉴已经提供的收藏分。
`{attribute}`	当前次数对应的属性列表，必须单独占一行。

图鉴 Lore 还会交给 PlaceholderAPI 处理。安装 PlaceholderAPI 后，可以在 Lore 中使用其他插件提供的变量。

收集前置条件

yaml

collect-condition:
  - 'guide:{test1}'
  - 'noguide:{test2}'
  - 'permission:{test.1}'
  - 'nopermission:{test.2}'
  - 'papi:{%player_level% >= 0}'

格式	条件
`guide:{图鉴ID}`	玩家已经收集过指定图鉴。
`noguide:{图鉴ID}`	玩家尚未收集指定图鉴。
`permission:{权限节点}`	玩家拥有指定权限。
`nopermission:{权限节点}`	玩家没有指定权限。
`papi:{判断式}`	PlaceholderAPI 解析后的结果满足判断式。

所有条件必须同时满足，事件收集和尝试收集才会成功。直接修改次数的 API 和 give、take、set 指令不会检查这些条件。

papi 条件依赖 PlaceholderAPI。插件会先解析玩家变量，再移除空格并计算判断式。

次数属性

yaml

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

节点格式	说明
`1`	仅在收集次数等于 `1` 时使用。
`2-9`	在收集次数为 `2` 至 `9` 时使用。

次数属性只选择一个匹配节点，不会把多个节点的属性累计叠加。没有匹配节点时，界面会显示 §7无，玩家属性缓存不会获得该图鉴的有效属性。

属性行支持 {count}。尖括号内可以编写数字、括号以及 +、-、*、/ 运算，~ 后面填写 Java 数字格式：

yaml

attribute:
  1-10:
    - '&a攻击力 +<{count}*1.5~%.1f>'

属性额外倍率

yaml

attribute-addition-placeholder: ''

该配置会把 PlaceholderAPI 变量解析结果作为百分比加成，应用到尖括号公式的计算结果。

值	行为
空字符串	不增加额外倍率。
正数	按百分比增加公式结果，例如 `20` 会使结果乘以 `1.2`。
负数	直接参与倍率计算。

该倍率只影响尖括号公式中的数值，不会修改普通属性文本中的数字。配置非空变量时需要安装 PlaceholderAPI，并确保变量结果可以转换为数字。

收集方法

yaml

collect-methods:
  - 'kill{name=example_mob;amount=100;chance=1}'
  - 'use_name{name=&6测试图鉴;chance=1}'

参数使用分号分隔，参数名和值之间使用等号。每个方法必须使用完整的 方法名{参数} 格式。

当前版本的图鉴加载器实际注册以下方法：

方法	参数	说明
`first_kill`	`name`、`chance`	设计为首次击杀指定实体时尝试收集。
`kill`	`name`、`amount`、`chance`	击杀计数达到指定倍数时尝试收集。
`use_name`	`name`、`chance`	右键使用显示名完全匹配的主手物品。
`use_lore`	`lore`、`chance`	右键使用包含完全匹配 Lore 行的主手物品。
`use_id`	`id`、`chance`	右键使用旧版数字 ID 和子 ID 均匹配的主手物品。

参数	说明
`name`	实体内部名称或物品完整显示名称。
`lore`	需要完全匹配的一行物品 Lore。
`id`	旧版物品格式，例如 `167:0`。
`amount`	每累计多少次击杀进行一次收集判定，未填写时按 `1` 处理。
`chance`	成功概率，通常填写 `0` 至 `1`，未填写时按 `0` 处理。

kill 同时支持 Bukkit 生物死亡监听和 MythicMobs 4/5。MythicMobs 使用怪物内部 ID；原版实体通常使用实体类型名称。

use_name、use_lore 和 use_id 匹配成功后，会先从玩家主手扣除一个物品，再进行概率判定。概率失败时会发送 message.use-item-failed。

拾取方法当前不支持写入 collect-methods

项目中存在拾取事件监听和 pickup_name、pickup_lore、pickup_id 的处理代码，但当前图鉴配置加载器只注册 first_kill、kill、use_name、use_lore 和 use_id。因此在 collect-methods 中填写拾取方法时，不会被加载为有效收集方法。

first_kill 当前流程限制

击杀监听会先写入 first_kill_实体名称 触发记录，再检查该记录是否存在，因此当前流程下 first_kill 不能正常触发。需要稳定使用首次击杀收集时，应改用 kill，并将 amount 设置为 1。

点击指令

yaml

click-command:
  - '[console]tell %player_name% 你点击了一下图鉴'

玩家在套装详情界面点击图鉴时执行列表中的指令。

前缀	执行身份
`[console]`	控制台执行。
`[op]`	临时以管理员身份执行。
`[player]`	玩家本人执行。

指令可以使用 PlaceholderAPI 变量，内容不要包含开头的 /。

获取指令

yaml

get-command:
  1:
    - '[console]tell %player_name% 你首次获得了图鉴'
  2-10:
    - '[console]tell %player_name% 你获得了图鉴 {count}'

get-command 支持单次数值和次数区间。图鉴次数增加后，插件会执行新次数对应的指令组。

内容	说明
`{count}`	增加后的图鉴收集次数。
`{name}`	图鉴显示名称。

通过事件、API 增加方法、give 指令或 try 指令获得图鉴时，会执行获取指令。扣除和直接设置次数不会执行获取指令。

套装配置 `suit/*.yml`

每个套装可以引用任意数量的图鉴。同一个图鉴可以同时属于多个套装。

基础信息与排序

yaml

id: '示例套装'
index: 1000
name: '&6示例图鉴套装'
lore:
  - '&7这是一个示例套装'
item: 'APPLE'
guide:
  - 'test'

配置项	默认值	说明
`id`	无	套装唯一 ID，用于分类、变量、指令和玩家数据。
`index`	`1000`	总览界面排序值，数字越小越靠前。
`name`	空字符串	套装显示名称。
`lore`	空列表	套装总览中的说明，会经过 PlaceholderAPI 解析。
`item`	`APPLE`	套装图标。
`guide`	空列表	套装包含的图鉴 ID 列表。

套装至少需要引用一个有效图鉴才能在详情界面显示内容。不存在的图鉴 ID 会在界面生成时跳过。

集齐收藏分

yaml

point: 10

玩家将套装内全部有效图鉴至少收集一次后，套装提供 point 设置的收藏分。套装收藏分只计算一次，不会随套装内图鉴收集次数增加。

%tjr_suit_point_套装ID% 返回套装奖励分与套装内全部图鉴收藏分的总和。

套装属性门槛

yaml

effective-attribute-need-count: 0
effective-attribute-point: 0
attribute:
  - '攻击力+5'

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

套装内每个图鉴至少收集一次。
套装内全部图鉴的收集次数总和不低于 effective-attribute-need-count。
玩家的全部收藏分不低于 effective-attribute-point。

配置项	默认值	说明
`effective-attribute-need-count`	`0`	套装内全部图鉴收集次数总和的最低要求。
`effective-attribute-point`	`0`	玩家全部收藏分的最低要求。
`attribute`	空列表	满足全部条件后提供的属性行。

套装属性会和图鉴属性、收藏分阶段属性合并后，交给 attribute-plugin 指定的属性系统处理。

首次集齐指令

yaml

collected-command:
  - 'bc %player_name% 集齐了示例套装'

玩家第一次将套装内全部图鉴收集至少一次时执行。执行后，套装 ID 会写入玩家数据的 enabled-suit，后续再次满足条件时不会重复执行。

指令可以使用 PlaceholderAPI 玩家变量，内容不要包含开头的 /。套装指令按照项目示例使用普通指令格式。

玩家数据结构

未启用 MySQL 时，每名玩家对应一个本地 YAML 文件。启用 MySQL 时，以下内容会序列化到数据库表的 data 字段中。

yaml

collected-guide:
  图鉴ID: 2
trigger-list:
  kill_实体名称: 10
  first_kill_实体名称: 1
  pickup_name_物品名称: 1
  pickup_lore_物品Lore: 1
  pickup_id_物品ID: 1
  use_name_物品名称: 1
  use_lore_物品Lore: 1
  use_id_物品ID: 1
enabled-suit:
  - '套装ID'

节点	保存内容
`collected-guide`	各图鉴当前收集次数。
`trigger-list`	击杀、首次击杀、拾取和使用物品等触发计数。
`enabled-suit`	已执行过首次集齐指令的套装 ID。

重载行为

执行 /tjr reload 时，插件会：

保存并重新读取 config.yml。
覆盖生成 guide/示例图鉴.yml 和 suit/示例套装.yml。
停止自动保存任务。
根据当前 mysql.enable 配置重新初始化数据库连接。
关闭正在打开的图鉴界面。
递归读取 guide 和 suit 目录中的全部 .yml 文件。
根据 load-default-config 决定是否跳过两个内置示例文件。
按 index 重新排序图鉴和套装。
根据 suit-class 重建套装分类。
重新启动自动保存任务。

attribute-plugin 在插件启动阶段初始化，修改后需要重启服务器。MySQL 存储监听同样在启动阶段根据 mysql.enable 选择，切换本地 YAML 与 MySQL 时必须重启服务器。

配置说明 ​

主配置 config.yml ​

属性插件 ​

自动保存 ​

原版生物死亡监听 ​

MySQL 存储 ​

默认示例配置 ​

获取图鉴提示 ​

已收集图鉴附魔光效 ​

界面点击音效 ​

套装分类 ​

自定义消息 ​

GUI 界面 ​

套装成员状态 Lore ​

收藏分阶段 ​

图鉴配置 guide/*.yml ​

基础信息 ​

收集前置条件 ​

次数属性 ​

属性额外倍率 ​

收集方法 ​

点击指令 ​

获取指令 ​

套装配置 suit/*.yml ​

基础信息与排序 ​

集齐收藏分 ​

套装属性门槛 ​

首次集齐指令 ​

玩家数据结构 ​

重载行为 ​

配置说明

主配置 `config.yml`

属性插件

自动保存

原版生物死亡监听

MySQL 存储

默认示例配置

获取图鉴提示

已收集图鉴附魔光效

界面点击音效

套装分类

自定义消息

GUI 界面

套装成员状态 Lore

收藏分阶段

图鉴配置 `guide/*.yml`

基础信息

收集前置条件

次数属性

属性额外倍率

收集方法

点击指令

获取指令

套装配置 `suit/*.yml`

基础信息与排序

集齐收藏分

套装属性门槛

首次集齐指令

玩家数据结构

重载行为