Skip to content

图鉴配置

图鉴文件放在插件目录的 guide 文件夹,套装文件放在 suit 文件夹。插件会递归读取这两个目录下的 .yml 文件,可以使用子目录整理配置。

  • 图鉴定义展示物品、收集次数、收藏分、前置条件、收集方式、属性和触发指令。
  • 套装引用多个图鉴,在全部成员至少收集一次后提供套装收藏分、属性和首次集齐指令。
  • 图鉴与套装通过 id 关联。所有 id 必须保持唯一,并与套装、分类、变量、指令和 API 中的参数完全一致。
  • 执行 /tjr reload 会重新读取主配置、图鉴、套装和套装分类,同时关闭玩家当前打开的图鉴界面。

默认的 示例图鉴.yml示例套装.yml 每次重载都会被覆盖。需要修改时,应先复制为其他文件,再编辑复制后的配置。

图鉴完整结构

单个图鉴文件直接从 id 开始,不需要额外添加顶层节点:

yaml
id: 'example'
name: '&a示例图鉴'
lore:
  - '&7当前已收集 &a{count}/{max} &7次'
  - '&7每次收集获得 &6{base_point} &7点收藏分'
  - '&7当前图鉴收藏分:&6{result_point}'
  - '&7当前属性:'
  - '{attribute}'
item: 'BOOK'

collect-condition:
  - 'permission:{guide.example}'
  - 'papi:{%player_level% >= 10}'

max-collect-count: 10
base-point: 1
attribute-addition-placeholder: ''

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

collect-methods:
  - 'kill{name=ZOMBIE;amount=100;chance=1}'

click-command:
  - '[player]say 我点击了图鉴'

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

图鉴基础配置

配置项类型默认值说明
id字符串图鉴唯一 ID,用于套装、指令、变量和 API。缺少该项时图鉴无法正常载入
name字符串图鉴显示名称,读取时会将 & 转换为颜色符号
lore字符串列表空列表图鉴在套装详情界面中的说明文本,可使用图鉴内容变量和 PlaceholderAPI 变量
item字符串APPLE图鉴图标,支持英文材质名或旧版 数字ID:子ID 格式
collect-condition字符串列表空列表事件收集和尝试收集时需要全部满足的前置条件
max-collect-count整数1最大收集次数。给予、扣除或设置次数后,最终结果会限制在 0 到该值之间
base-point整数0每次收集提供的基础收藏分,图鉴收藏分等于收集次数乘以该值
attribute-addition-placeholder字符串空字符串对属性公式结果追加百分比倍率的 PlaceholderAPI 变量
attribute节点按当前收集次数选择的属性列表
collect-methods字符串列表空列表图鉴的自动收集方式
click-command字符串列表空列表玩家在套装详情界面点击该图鉴时执行的指令
get-command节点增加图鉴收集次数后,按增加后的当前次数执行的指令

图鉴没有独立的 index 配置项。插件按读取文件时生成的顺序值排列图鉴,并在套装详情界面中按照套装 guide 列表的顺序展示成员。

图鉴 Lore 变量

以下内容变量由图鉴界面直接处理:

内容说明
{count}玩家当前收集次数
{max}图鉴最大收集次数
{base_point}每次收集提供的基础收藏分
{result_point}当前图鉴收藏分,即 base-point × 当前次数
{attribute}将这一整行替换为当前收集次数对应的全部属性

lore 中的 PlaceholderAPI 变量会按查看界面的玩家解析,例如 %player_level%。使用这类变量时,需要服务器安装并正常加载 PlaceholderAPI。

yaml
lore:
  - '&7玩家等级:&f%player_level%'
  - '&7收集进度:&a{count}/{max}'
  - '&7当前收藏分:&6{result_point}'
  - '&7生效属性:'
  - '{attribute}'

{attribute} 必须单独占据一行。插件只会在整行内容等于 {attribute} 时插入属性列表。

收集前置条件

collect-condition 中的条件需要全部通过,图鉴才会进入收集判断。

yaml
collect-condition:
  - 'guide:{前置图鉴ID}'
  - 'noguide:{互斥图鉴ID}'
  - 'permission:{guide.example}'
  - 'nopermission:{guide.blocked}'
  - 'papi:{%player_level% >= 10}'
条件格式说明
guide:{图鉴ID}玩家指定图鉴的收集次数必须大于 0
noguide:{图鉴ID}玩家指定图鉴的收集次数必须等于 0
permission:{权限节点}玩家必须拥有指定权限
nopermission:{权限节点}玩家不能拥有指定权限
papi:{判断表达式}先解析 PlaceholderAPI 变量,再判断表达式是否成立

配置时需要保留条件外层的大括号。例如应写成 permission:{guide.example},不能省略为 permission:guide.example

前置条件会用于以下收集入口:

  • 击杀收集。
  • 使用物品收集。
  • /tjr try 尝试收集。
  • API 的尝试收集方法。

管理员直接使用 /tjr give 增加图鉴次数时,不会检查这些条件。

PAPI 判断表达式

插件会先解析表达式中的 PlaceholderAPI 变量,再移除空格并执行判断。项目示例确认支持数值比较:

yaml
collect-condition:
  - 'papi:{%player_level% >= 10}'

不要在无法返回可比较结果的变量上使用数值表达式。PlaceholderAPI 未安装或变量无法正常解析时,相关条件无法按预期工作。

收集方式格式

收集方式写在 collect-methods 列表中,格式必须严格匹配:

text
方式名{参数名=参数值;参数名=参数值}

参数之间使用半角分号 ; 分隔,参数名与参数值之间使用半角等号 = 分隔。

yaml
collect-methods:
  - 'kill{name=ZOMBIE;amount=100;chance=1}'
  - 'use_name{name=&6图鉴碎片;chance=0.5}'

需要注意:

  • 方式名称、开头大括号和结尾大括号必须完整。
  • 每个参数都必须使用 参数名=参数值 格式。
  • 不要在参数值中加入额外的半角分号或等号。
  • chance01 配置,1 表示必定通过概率判断。
  • 未配置 chance 时,代码按 0 处理,不会通过概率判断。

击杀收集

yaml
collect-methods:
  - 'kill{name=ZOMBIE;amount=100;chance=1}'
参数默认值说明
name空字符串目标怪物 ID 或实体名称。原版实体通常使用 Bukkit 实体类型名,MythicMobs 使用内部 ID
amount1每次尝试收集所需的累计击杀次数
chance0达到次数时增加一次图鉴收集次数的概率,按 01 配置

插件会记录 kill_怪物ID 的累计次数。当累计次数能够被 amount 整除并通过概率判断时,增加一次图鉴收集次数。

插件能够处理以下击杀来源:

  • Bukkit 实体死亡事件。
  • CUSTOMNPCS_CUSTOMNPC 类型实体。
  • MythicMobs 4 的 MythicMob 死亡事件。
  • MythicMobs 5 的 MythicMob 死亡事件。

是否监听 Bukkit 实体死亡由主配置中的 enable-bukkit-death-event 控制。关闭后,普通实体和通过 Bukkit 死亡事件识别的 NPC 不再累计击杀;MythicMobs 使用独立监听。

MythicMobs 名称

MythicMobs 收集方式中的 name 使用 MythicMobs 内部 ID:

yaml
collect-methods:
  - 'kill{name=ForestBoss;amount=5;chance=1}'

服务器安装并启用 MythicMobs 时,插件会根据检测到的主版本注册 MythicMobs 4 或 MythicMobs 5 监听。

first_kill 当前限制

项目中保留了首次击杀格式:

yaml
collect-methods:
  - 'first_kill{name=ZOMBIE;chance=1}'

但当前击杀监听会先写入 first_kill_怪物ID 记录,再检查该记录。检查时记录已经存在,因此 first_kill 分支会被跳过。

当前版本不要将 first_kill 作为可靠的图鉴发放方式。首次击杀记录仍会写入玩家触发数据,对应 PlaceholderAPI 变量会返回记录值。

使用物品收集

玩家主手持有匹配物品并右键空气或方块时,可以尝试收集图鉴。

yaml
collect-methods:
  - 'use_name{name=&6图鉴碎片;chance=1}'
  - 'use_lore{lore=&7右键使用后尝试解锁图鉴;chance=0.5}'
  - 'use_id{id=167:0;chance=1}'
方式匹配参数说明
use_namename主手物品显示名称必须完全一致,配置中的 & 会转换为颜色符号后再比较
use_lorelore主手物品 Lore 中必须存在完全一致的一行,配置中的 & 会转换为颜色符号后再比较
use_idid主手物品的旧版 数字ID:子ID 必须完全一致

共同参数:

参数默认值说明
chance0扣除物品后成功增加一次图鉴收集次数的概率,按 01 配置

处理顺序如下:

  1. 检查玩家数据是否已经加载。
  2. 检查图鉴是否已经达到 max-collect-count
  3. 检查主手物品是否匹配。
  4. 检查 collect-condition 中的全部前置条件。
  5. 扣除主手中的一个物品。
  6. 执行概率判断。
  7. 成功时记录触发次数并增加一次图鉴收集次数。
  8. 失败时发送 message.use-item-failed 消息。

物品会在概率判断前扣除。即使概率判断失败,物品也不会退还。

使用成功时,插件会分别记录以下触发键:

收集方式触发键
use_nameuse_name_物品名
use_loreuse_lore_物品Lore
use_iduse_id_物品ID

这些记录可以通过 %tjr_trigger_触发键% 类型的 PlaceholderAPI 变量读取。

拾取物品配置限制

默认示例文件中说明了以下格式:

yaml
collect-methods:
  - 'pickup_name{name=&6图鉴碎片;chance=1}'
  - 'pickup_lore{lore=&7图鉴材料;chance=1}'
  - 'pickup_id{id=167:0;chance=1}'

项目中存在拾取事件监听,并且核心启动时也会注册该监听。但是当前图鉴配置解析器只会注册以下收集方式:

  • first_kill
  • kill
  • use_name
  • use_lore
  • use_id

pickup_namepickup_lorepickup_id 不会被加入图鉴的收集方式列表,因此拾取监听无法读取到这些配置。

当前版本不要将拾取方式作为可用的图鉴收集功能。配置文件中虽然保留了拾取变量和示例说明,但仅编写上述 pickup_* 配置不会触发图鉴收集。

图鉴属性

attribute 必须按收集次数分组。插件只会选择当前次数匹配的一组属性,不会累计叠加之前次数的分组。

yaml
attribute:
  1:
    - '&a攻击力 +5'
  2-9:
    - '&a攻击力 +<{count}*2~%.0f>'
    - '&a生命值 +<{count}*10~%.1f>'
  10:
    - '&a攻击力 +30'
键格式说明
1仅在第 1 次收集时使用
10仅在第 10 次收集时使用
2-9在第 2 至第 9 次收集时使用,包含两端

如果当前次数没有匹配的配置,界面预览会显示“无”。实际属性缓存只会在收集次数大于 0 时加入图鉴属性。

属性内容变量

属性行支持 {count}

yaml
attribute:
  1-10:
    - '&a攻击力 +{count}'

插件会将 {count} 替换为正在计算的收集次数。

属性公式

属性行可以使用公式:

yaml
attribute:
  1-10:
    - '&a攻击力 +<{count}*1~%.0f>'
    - '&a生命值 +<({count}+1)*2~%.1f>'

公式整体格式为:

text
<算式~格式>
部分说明
算式支持整数、小数、括号以及 +-*/ 运算
格式Java 数字格式,例如 %.0f 表示保留 0 位小数,%.1f 表示保留 1 位小数

格式部分可以省略,省略时默认使用 %.0f

yaml
attribute:
  1-10:
    - '&a攻击力 +<{count}*2>'

同一行可以包含多个公式。插件会持续处理该行中成对出现的尖括号,直到没有可计算的公式。

公式中的尖括号必须放在 YAML 代码块或行内代码中,避免文档系统将其识别为标签。

属性额外倍率

attribute-addition-placeholder 可以填写一个能够解析为数字的 PlaceholderAPI 变量:

yaml
attribute-addition-placeholder: '%player_level%'

插件会将解析结果按百分比转换为额外倍率,再作用于公式结果。例如变量返回 20 时,公式结果按 1.2 倍计算;返回 0 或配置为空时不增加倍率。

计算关系为:

text
最终公式结果 = 原公式结果 × (1 + 变量值 ÷ 100)

该倍率只影响尖括号公式中的数值,不会修改没有使用公式的普通属性文本。

该功能依赖 PlaceholderAPI,并要求变量最终返回能够转换为数字的内容。无法转换为数字的返回值可能导致属性计算失败,因此不建议填写文本类型变量。

属性来源

玩家最终属性缓存由以下内容共同组成:

  • 当前收集次数对应的图鉴属性。
  • 当前满足条件的套装属性。
  • 主配置 point 中当前收藏分档位对应的属性。

主配置中的 attribute-plugin 决定属性发送到哪个属性插件。修改属性插件类型后需要重启服务器。

点击指令

click-command 在玩家打开套装详情界面并点击图鉴物品时执行:

yaml
click-command:
  - '[player]say 我点击了图鉴'
  - '[console]tell %player_name% 你查看了示例图鉴'
前缀执行身份
[console]控制台执行
[op]临时以管理员身份执行
[player]玩家身份执行

点击图鉴不会自动增加收集次数,只会执行这里配置的指令。

获得指令

get-command 按增加后的当前收集次数选择指令组:

yaml
get-command:
  1:
    - '[console]tell %player_name% 你首次获得了图鉴'
  2-9:
    - '[console]tell %player_name% 你已收集该图鉴 {count} 次'
  10:
    - '[console]tell %player_name% 你已完成该图鉴'
键格式触发范围
1当前收集次数等于 1
10当前收集次数等于 10
2-9当前收集次数处于 29 之间

获得指令支持以下图鉴内容变量:

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

通过以下入口增加图鉴次数时,会进入获得处理并执行匹配的 get-command

  • 击杀收集。
  • 使用物品收集。
  • /tjr try
  • /tjr give
  • API 的增加方法。

/tjr take/tjr set 和 API 的扣除、设置方法不会执行获得指令。

增加后的次数会被限制在 0max-collect-count 之间。获得指令按照限制后的最终次数选择对应区间。

套装完整结构

单个套装文件直接从 id 开始:

yaml
id: 'example_suit'
index: 1000
name: '&b示例套装'
lore:
  - '&7收集套装中的全部图鉴后完成套装'
  - '&7套装与成员总收藏分:&6%tjr_suit_point_example_suit%'
item: 'CHEST'

guide:
  - 'example'
  - 'example_two'

point: 10
effective-attribute-need-count: 3
effective-attribute-point: 20

attribute:
  - '&a攻击力 +5'

collected-command:
  - '[console]say %player_name% 首次集齐了示例套装'

套装基础配置

配置项类型默认值说明
id字符串套装唯一 ID,用于界面、分类、变量和成员完成状态
index整数1000套装排序值,数字越小越靠前
name字符串空字符串套装显示名称,读取时会将 & 转换为颜色符号
lore字符串列表空列表套装说明,支持颜色代码和 PlaceholderAPI 变量
item字符串APPLE套装图标,支持英文材质名或旧版 数字ID:子ID 格式
guide字符串列表空列表套装包含的图鉴 ID
point整数0套装全部成员至少收集一次后提供的额外收藏分
effective-attribute-need-count整数0套装属性要求的成员累计收集次数
effective-attribute-point整数0套装属性要求的玩家全部收藏分
attribute字符串列表空列表满足套装属性条件后加入玩家属性缓存的属性
collected-command字符串列表空列表玩家首次集齐套装时执行的指令

套装排序

套装使用 index 排序,数字越小越靠前:

yaml
id: 'forest_suit'
index: 100
yaml
id: 'dungeon_suit'
index: 200

排序会影响套装总览中的顺序。套装分类中的展示顺序则按照主配置 suit-class 对应列表的顺序生成。

套装成员

guide 列表填写图鉴的 id

yaml
guide:
  - 'forest_zombie'
  - 'forest_skeleton'
  - 'forest_boss'

同一个图鉴可以同时属于多个套装。套装详情界面会按这里的顺序展示有效图鉴。

引用不存在的图鉴 ID 时:

  • 该图鉴不会在套装详情界面显示。
  • 套装完成检查仍会读取这个 ID 的玩家收集次数。
  • 不存在的图鉴通常没有可获得的收集次数,因此会导致套装无法正常完成。

套装完成条件是列表中的每个图鉴收集次数都大于 0,不要求每个图鉴达到最大收集次数。

套装收藏分

yaml
point: 10

套装全部成员至少收集一次后,point 会计入玩家总收藏分。

图鉴收藏分计算方式:

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

指定套装及其成员的总收藏分计算方式:

text
套装与成员总收藏分 = 套装完成奖励 + 每个成员图鉴的收藏分总和

玩家全部收藏分计算方式:

text
全部收藏分 = 所有已完成套装的奖励分 + 所有图鉴的收藏分

一个图鉴可以属于多个套装,但玩家全部收藏分中的图鉴收藏分只按全局图鉴列表计算一次。套装与成员总收藏分变量按指定套装单独统计,用于展示该套装相关进度。

套装属性生效条件

yaml
effective-attribute-need-count: 5
effective-attribute-point: 100
attribute:
  - '&a攻击力 +5'
  - '&a生命值 +20'

套装属性需要同时满足以下条件:

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

两个门槛配置为 0 时,仍然需要套装中的每个图鉴至少收集一次,套装属性才会加入属性缓存。

effective-attribute-point 判断的是玩家全部收藏分,不只是当前套装与成员的收藏分。

套装属性直接作为字符串列表加入属性缓存,不使用图鉴 attribute 的次数区间、{count} 替换和尖括号公式计算机制。

首次集齐指令

yaml
collected-command:
  - '[console]say %player_name% 首次集齐了示例套装'

当玩家第一次满足“套装内每个图鉴至少收集一次”时,插件会记录该套装已经激活,并执行 collected-command

套装完成检查会在以下操作后执行:

  • 增加图鉴收集次数。
  • 扣除图鉴收集次数。
  • 设置图鉴收集次数。

已经激活的套装会写入玩家数据的 enabled-suit 列表。之后即使管理员扣除或重设图鉴次数,再次集齐时也不会重复执行首次集齐指令。

enabled-suit 只用于阻止首次集齐指令重复执行。套装收藏分和套装属性在计算时仍会重新检查当前图鉴次数和属性门槛。

套装分类

套装分类不写在套装文件中,而是在主配置的 suit-class 节点中配置:

yaml
suit-class:
  森林图鉴:
    - 'forest_suit'
    - 'forest_boss_suit'
  地牢图鉴:
    - 'dungeon_suit'
内容说明
分类节点名分类 ID,用于 /tjr class 分类ID
分类列表内容已经存在的套装 id

分类加载时只会加入已经成功载入的套装。列表中不存在的套装 ID 会被跳过。

玩家可使用以下指令打开分类界面:

text
/tjr class 分类ID

分类界面的标题使用主配置中的 gui.total-title,套装详情界面标题使用 gui.suit-title

默认示例文件

插件每次重载都会以覆盖模式释放:

  • guide/示例图鉴.yml
  • suit/示例套装.yml

不要直接把正式内容长期保存在这两个默认文件中。应复制并重命名,例如:

text
guide/森林/僵尸图鉴.yml
suit/森林套装.yml

如果主配置设置:

yaml
load-default-config: false

插件读取配置时会跳过文件名完全为 示例图鉴.yml示例套装.yml 的默认示例,但重载时仍会覆盖释放这两个资源文件。

load-default-config 只控制是否载入默认示例,不会阻止默认文件被重新写入。

重载行为

执行以下指令会重新载入配置:

text
/tjr reload

重载过程会:

  1. 重新读取 config.yml
  2. 覆盖释放默认图鉴和默认套装文件。
  3. 停止当前自动保存任务。
  4. 将插件标记为重载状态,暂时阻止玩家打开界面。
  5. 在启用 MySQL 时重新执行数据库连接和数据表初始化。
  6. 强制关闭当前已打开的图鉴界面。
  7. 递归读取 guide 文件夹下的 .yml 文件。
  8. 递归读取 suit 文件夹下的 .yml 文件。
  9. 重新生成套装分类。
  10. 恢复界面打开并重新启动自动保存任务。

图鉴和套装内容可以通过重载更新。修改属性插件类型或 MySQL 存储模式后仍建议重启服务器,避免监听器和数据存储模式与新配置不一致。

MySQL 存储要求

启用 MySQL 的主配置示例:

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

启用 MySQL 时,必须安装 LyMySQLCore,并确保 LyMySQLCore 与 LyGuideReload 能够成功连接数据库。只有数据库连接和数据表初始化成功后,MySQL 玩家数据读取、保存和自动保存相关功能才会生效。

未启用 MySQL 时,玩家数据保存在插件的 data 文件夹中,文件名使用玩家 UUID。

玩家数据包含:

  • collected-guide:各图鉴的收集次数。
  • trigger-list:击杀、首次击杀和使用物品等触发记录。
  • enabled-suit:已经执行过首次集齐指令的套装 ID。

配置注意事项

  • 图鉴 id 与套装 id 都应保持唯一。
  • 套装 guide、分类列表、指令参数、变量和 API 中的 ID 必须与配置完全一致。
  • 图鉴文件没有可配置的独立排序值;套装可以使用 index 排序。
  • 收集方式必须严格使用 方式名{参数} 格式,否则不会被解析。
  • 收集方式的每个参数都必须包含半角等号。
  • chance01 配置,1 表示必定通过概率判断。
  • use_nameuse_lore 使用完全匹配,不是包含匹配。
  • 使用物品收集会先扣除物品,再判断概率。
  • pickup_namepickup_lorepickup_id 当前不会被图鉴解析器注册。
  • first_kill 当前存在处理顺序问题,不应作为可靠的收集方式。
  • 图鉴属性和获得指令都按当前次数选择单个匹配区间,不会把多个区间叠加执行。
  • 图鉴收集次数始终限制在 0max-collect-count 之间。
  • 属性公式中的尖括号应保留在 YAML 字符串内。
  • attribute-addition-placeholder 必须返回能够转换为数字的内容。
  • 套装完成只要求每个成员至少收集一次,不要求达到最大次数。
  • 套装首次集齐指令只执行一次,永久记录在玩家的 enabled-suit 数据中。
  • 修改图鉴或套装前先复制默认示例文件,避免重载时被覆盖。
  • 修改属性插件类型、MySQL 开关等主配置后应重启服务器。
  • 如果启用 MySQL,必须安装 LyMySQLCore,并确保数据库成功连接,否则 MySQL 玩家数据功能不会生效。