常见问题

插件的主要用途是什么

LyGuideReload 是一个图鉴收集插件。玩家可以通过击杀生物、使用物品、管理员指令或其他插件调用 API 增加图鉴收集次数，并获得收藏分、图鉴属性和套装属性。

插件包含以下主要功能：

图鉴套装总览、指定套装和套装分类界面。
图鉴收集次数与最大收集次数。
前置图鉴、反向图鉴、权限、反权限和 PlaceholderAPI 表达式条件。
首次击杀、累计击杀和使用物品收集方法。
图鉴收藏分、套装收藏分、总收藏分、收藏分称号与收藏分属性。
单图鉴属性、套装属性和属性缓存刷新。
YAML 或 MySQL 玩家数据储存。
PlaceholderAPI 变量和 Java API。

当前项目版本为 1.0.6。

插件必须安装哪些前置

插件将以下插件声明为软依赖：

插件	用途
PlaceholderAPI	注册 `%tjr_...%` 变量、解析指令变量和处理 `papi` 收集条件
MythicMobs	监听 MythicMobs 4.x 或 5.x 怪物击杀
AttributePlus	应用图鉴或套装属性
SX-Attribute	对接 `SX-Attribute2` 或 `SX-Attribute3`
AttributeSystem	可在属性插件配置中选择
ItemLoreOrigin	通过虚拟 Lore 物品提供属性
LyMySQLCore	启用 MySQL 储存时提供玩家数据库加载与保存事件

这些插件不是全部都必须安装，应根据实际启用的功能选择。

如果启用了 MySQL，必须安装 LyMySQLCore，并确保 LyMySQLCore 已成功连接数据库后，MySQL 相关功能才会生效。

如果需要使用插件变量、papi:{...} 条件或指令中的 PlaceholderAPI 变量，则必须安装并启用 PlaceholderAPI。

打开界面时没有反应

先确认指令由玩家执行，并检查参数中的 id：

指令	使用条件
`/tjr opent`	必须由玩家执行；无需 OP
`/tjr opens <套装id>`	必须由玩家执行；套装 id 必须存在
`/tjr class <分类id>`	必须由玩家执行；分类 id 必须在 `suit-class` 中存在

控制台不能直接打开玩家界面。

继续检查以下内容：

套装文件是否成功加载。
guide 列表中填写的是否为图鉴 id，而不是文件名或显示名称。
分类中的套装 id 是否与套装文件的 id 完全一致。
图鉴或套装图标的材质名是否有效。
控制台中是否出现图鉴、套装或分类加载异常。

图鉴界面的点击事件会被插件取消，这是正常行为。点击套装会进入对应套装界面，点击图鉴则执行该图鉴的 click-command。

图鉴没有被收集

按以下顺序检查：

当前版本是否真正注册了所填写的 collect-methods。
收集方法格式是否以正确的方法名开头，并以 } 结尾。
参数之间是否使用英文分号 ; 分隔，每个参数是否包含 =。
collect-condition 是否全部满足。
图鉴当前次数是否已经达到 max-collect-count。
怪物 id、物品名称、Lore 或数字 id 是否与事件中取得的内容完全一致。
玩家数据是否已经加载。
图鉴 id 是否唯一，套装、指令和变量是否使用同一个 id。

收集方法解析器会直接按 参数=值 拆分。缺少 =、多写分隔符或使用错误格式可能导致该图鉴加载失败，而不只是忽略当前收集方法。

收集条件应该怎么填写

图鉴的 collect-condition 是同时满足关系。任意一条条件失败，本次普通收集都会停止。

条件	作用
`guide:{图鉴id}`	玩家至少收集过指定图鉴一次
`noguide:{图鉴id}`	玩家没有收集过指定图鉴
`permission:{权限节点}`	玩家拥有指定权限
`nopermission:{权限节点}`	玩家没有指定权限
`papi:{表达式}`	解析 PlaceholderAPI 变量后判断表达式

配置示例：

yaml

collect-condition:
  - 'guide:{前置图鉴id}'
  - 'noguide:{禁止拥有的图鉴id}'
  - 'permission:{example.collect}'
  - 'nopermission:{example.blocked}'
  - 'papi:{%player_level% >= 10}'

/tjr give 直接增加图鉴次数，不检查 collect-condition。/tjr try 和事件收集会检查这些条件。

`papi` 条件支持哪些表达式

papi:{...} 会先使用 PlaceholderAPI 替换变量，再计算表达式。

支持的逻辑和比较运算符如下：

类型	运算符
或	`
与	`&&`
大于、小于	`>`、`<`
大于等于、小于等于	`>=`、`<=`
相等、不相等	`==`、`!=`
数学运算	`+`、`-`、`*`、`/`、`()`

数值判断示例：

yaml

collect-condition:
  - 'papi:{%player_level% >= 10 && %player_level% < 50}'

字符串相等判断需要给两侧字符串加单引号或双引号：

yaml

collect-condition:
  - "papi:{'%player_world%' == 'world'}"

注意事项：

必须安装并启用 PlaceholderAPI。
表达式替换后的内容必须能够被解析。
只有没有比较运算符的 true 会被直接视为真。
复杂字符串中如果包含 && 或 ||，仍可能被当作逻辑运算符拆分。

首次击杀没有触发

首次击杀的配置格式为：

yaml

collect-methods:
  - 'first_kill{name=怪物id;chance=1}'

但是，当前 1.0.6 项目代码存在明确的执行顺序问题：击杀发生后，监听器会先写入 first_kill_<怪物id> 记录，随后在判断 first_kill 收集方法时，只要该记录已经存在就会跳过。因此，当前代码中的首次击杀收集无法正常进入概率判定。

该问题同时存在于：

原版或普通实体击杀监听。
MythicMobs 4.x 击杀监听。
MythicMobs 5.x 击杀监听。
/tjr addkill 的触发检查。

仅修改怪物名称或概率不能解决该实现问题，需要使用已修复该判断顺序的插件构建。

虽然图鉴不会因此正常获得，但首次击杀记录仍会被写入，所以 %tjr_trigger_first_kill_<怪物id>% 可能已经返回 1。

累计击杀次数没有增加

累计击杀使用以下格式：

yaml

collect-methods:
  - 'kill{name=怪物id;amount=100;chance=1}'

参数	作用
`name`	监听到的怪物名称或 MythicMobs 内部 id
`amount`	每累计到该次数的整数倍时进行收集判定
`chance`	判定概率，通常填写 `0` 到 `1`

原版实体死亡监听由以下配置控制：

yaml

enable-bukkit-death-event: true

设置为 false 后，插件不会注册普通实体死亡监听。MythicMobs 监听由 MythicMobs 是否启用决定，不受此开关影响。

普通实体的目标名称按以下方式取得：

一般实体使用实体类型名称。
类型名称为 MOD_CUSTOM 时可以使用实体自定义名称。
CUSTOMNPCS_CUSTOMNPC 会通过服务端实体名称取得目标名称。
MythicMobs 使用怪物内部 id，不使用显示名称。

插件会根据 MythicMobs 插件版本是否以 4 开头，选择 MythicMobs 4.x 或 5.x 监听器。

`kill` 达到次数后仍没有获得图鉴

kill 只有在当前累计击杀数是 amount 的整数倍时才会增加图鉴次数。例如 amount=100 时，会在第 100、200、300 次击杀进行判定。

检查以下内容：

amount 是否为有效正整数。
chance 是否为有效数字。
怪物名称是否完全一致，大小写也应保持一致。
图鉴收集条件是否全部满足。
图鉴是否达到最大收集次数。
玩家数据是否已经加载。
普通实体监听是否被 enable-bukkit-death-event: false 关闭。

概率判定发生在整数倍检查之前。即使当前次数达到整数倍，chance 判定失败也不会获得图鉴。

如何手动增加击杀计数

管理员可以使用：

text

/tjr addkill <玩家> <怪物id> <次数>

该指令要求：

执行者是 OP。
目标玩家在线。
目标玩家数据已经加载。
次数能够解析为整数。

负数次数会被改为 0。指令会：

在不存在首次击杀记录时写入 first_kill_<怪物id>。
增加 kill_<怪物id> 计数。
异步检查匹配的击杀收集方法。

由于当前版本的首次击杀判断问题，addkill 不能正常触发 first_kill 图鉴，但仍可以用于验证 kill 累计击杀收集。

拾取物品没有触发

示例配置和监听器中存在以下拾取方法设计：

收集方法	设计用途
`pickup_name`	物品显示名称完全匹配
`pickup_lore`	物品 Lore 中存在完全匹配的行
`pickup_id`	物品数字 id 和耐久值完全匹配

示例格式：

yaml

collect-methods:
  - 'pickup_name{name=&6测试物品;chance=1}'
  - 'pickup_lore{lore=&6测试Lore;chance=1}'
  - 'pickup_id{id=260:0;chance=1}'

但是，当前项目中的 GuideData 只注册了 first_kill、kill 和三种 use_* 方法，没有解析或注册任何 pickup_* 方法。拾取监听器虽然存在，但无法从图鉴配置中取得已注册的拾取收集方法。

因此，在当前 1.0.6 项目代码中，仅向图鉴文件加入 pickup_name、pickup_lore 或 pickup_id 不会触发收集。需要使用已经补充拾取方法注册逻辑的插件构建。

使用物品没有触发

使用物品支持以下方法：

收集方法	匹配内容
`use_name`	主手物品显示名称完全匹配
`use_lore`	主手物品 Lore 中存在完全匹配的行
`use_id`	主手物品数字 id 和耐久值完全匹配

配置示例：

yaml

collect-methods:
  - 'use_name{name=&6测试物品;chance=1}'
  - 'use_lore{lore=&6测试Lore;chance=1}'
  - 'use_id{id=260:0;chance=1}'

检查以下内容：

玩家执行的是右键空气或右键方块。
目标物品位于玩家主手。
物品存在 ItemMeta。
use_name 的显示名称完全一致。
use_lore 的 Lore 中存在完全一致的一整行。
use_id 使用旧版数字 id 与耐久值格式，例如 260:0。
图鉴收集条件全部满足。
图鉴尚未达到最大收集次数。
玩家数据已经加载。

名称和 Lore 配置中的 & 会在比较时转换为 § 颜色代码。

使用物品失败后为什么仍然扣除了物品

这是当前实现的正常执行顺序。

use_name、use_lore 和 use_id 匹配成功并通过收集条件后，会先扣除主手物品一个，再执行 chance 概率判定。因此，即使概率判定失败，物品也不会返还。

失败提示由以下配置控制：

yaml

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

不需要失败提示时，可以将该值设置为空字符串：

yaml

message:
  use-item-failed: ''

物品 id 应该怎么填写

图鉴图标、套装图标和 GUI 物品支持英文材质名，也包含旧版数字 id 兼容处理。

yaml

item: 'APPLE'

或：

yaml

item: '260:0'

use_id 和设计中的 pickup_id 不是通过材质兼容表匹配，而是直接比较物品的数字类型 id 与耐久值，因此必须填写数字格式：

yaml

collect-methods:
  - 'use_id{id=260:0;chance=1}'

无效图标材质可能回退为石头，不能据此判断收集方法中的 id 是否正确。

图鉴属性没有生效

先检查主配置中的属性插件选择：

yaml

attribute-plugin: 'AttributePlus'

项目配置和代码中出现的属性系统包括：

AttributePlus
SX-Attribute2
SX-Attribute3
AttributeSystem
ItemLoreOrigin

修改 attribute-plugin 后需要重启服务器。

图鉴属性按当前收集次数匹配单个次数键或次数区间，并且只会采用一个匹配结果：

yaml

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

继续检查：

属性插件是否已经启用。
attribute-plugin 是否与实际属性插件对应。
属性文本格式是否符合对应属性插件要求。
当前收集次数是否落在已配置的次数键或区间内。
图鉴 Lore 是否包含 {attribute}，用于在界面中显示属性。

没有匹配到当前次数时，插件取得的属性文本为“无”。界面显示属性不代表属性插件一定已经成功应用，应同时检查控制台中的属性前置加载信息。

属性公式应该怎么填写

示例图鉴中的属性公式格式为：

yaml

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

其中：

{count} 表示图鉴收集次数。
+、-、*、/ 和括号可用于数学计算。
~%.0f 表示按格式输出结果，示例中的 %.0f 表示不保留小数位。

图鉴还提供隐藏配置 attribute-addition-placeholder，用于让属性公式中的数字获得额外变量加成：

yaml

attribute-addition-placeholder: ''

该配置为空或被删除时不生效。项目示例明确标注此功能不推荐使用，应在确认属性结果符合预期后再启用。

修改收集次数后属性没有刷新

玩家关闭插件记录的图鉴界面时，插件会刷新该玩家的属性缓存。

项目帮助中还提供：

text

/tjr update <玩家>

但当前 ServerCommand 实现存在参数数量错误：代码只在参数数量为 1 时进入 update 分支，却又读取第二个参数。正常输入 /tjr update 玩家名 时参数数量为 2，不会进入该分支；只输入 /tjr update 又可能因读取不存在的参数而报错。

因此，当前 1.0.6 项目代码中的 update 指令不能可靠使用。可以暂时让玩家打开并关闭插件图鉴界面触发属性刷新，或使用已经修复参数判断的插件构建。

ItemLoreOrigin 属性多久刷新一次

检测到 ItemLoreOrigin 后，插件会建立异步属性更新任务，为在线玩家重新提交汇总后的 Lore 属性。

任务间隔读取：

yaml

ilo-update-task: 20

默认值为 20 tick。该键没有出现在默认 config.yml 中，但代码会在缺少配置时使用默认值。

玩家退出后，插件会移除内存中的 ItemLoreOrigin 图鉴属性数据。

套装没有激活

套装的 guide 必须填写图鉴配置中的 id：

yaml

guide:
  - 'test'

不能填写图鉴文件名、图鉴显示名称或套装名称。

套装相关条件包括：

配置键	作用
`guide`	套装包含的图鉴 id 列表
`point`	全部图鉴至少完成一次后提供的套装收藏分
`effective-attribute-need-count`	套装内全部图鉴累计收集次数要求
`effective-attribute-point`	套装属性要求的最低收藏分
`attribute`	满足条件后提供的套装属性
`collected-command`	首次集齐套装时执行的指令

套装属性不是只配置 attribute 就会无条件生效。玩家需要先完成套装包含的图鉴，并达到配置的累计次数和收藏分要求。

套装完成指令没有执行

套装首次集齐指令配置在：

yaml

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

检查以下内容：

guide 中的每个图鉴 id 是否存在。
玩家是否已经在之前完成过该套装。
指令文本是否适用于玩家身份执行。
PlaceholderAPI 是否已启用，相关变量是否能够解析。

套装完成指令用于首次集齐逻辑，不会在每次刷新属性或打开界面时重复执行。

套装总收藏分不正确

套装收藏分变量为：

text

%tjr_suit_point_<套装id>%

尖括号中的内容需要替换为套装文件的实际 id。

套装的 point 是全部完成该套装后提供的收藏分，不等同于套装内单个图鉴的 base-point。单个图鉴收藏分通常由收集次数乘以基础收藏分计算，套装分则属于完成套装后的额外分值。

还应检查：

套装 id 是否完全一致。
guide 中是否引用了正确图鉴。
玩家数据是否已经加载。
PlaceholderAPI 是否已启用。

分类界面没有显示套装

分类由主配置的 suit-class 定义：

yaml

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

使用以下指令打开：

text

/tjr class <分类id>

分类加载时只会加入已经存在于套装数据中的 id。不存在的套装 id 会被忽略。

检查以下内容：

分类 id 是否与 suit-class 下的键完全一致。
套装 id 是否与套装文件中的 id 完全一致。
套装文件是否成功加载。
分类列表是否为空。
执行者是否为玩家。

如果分类在重载后提示不存在，应检查配置是否成功保存，以及分类引用的套装是否在分类数据建立前成功载入。

图鉴点击指令没有执行

图鉴点击指令配置在：

yaml

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

当前代码支持的执行方式如下：

写法	执行者
`[console]指令`	控制台
`[op]指令`	玩家临时获得 OP 后执行，执行后恢复原状态
不写前缀	玩家

示例文件注释中提到 [player]，但当前指令执行代码不会移除 [player] 前缀。因此不要写 [player]，需要玩家执行时直接省略前缀。

指令执行前会调用 PlaceholderAPI 解析变量。没有安装 PlaceholderAPI 时，点击和获取指令的执行代码也可能无法正常工作。

获取图鉴后指令没有执行

获取指令配置在 get-command，支持单次次数键和次数区间：

yaml

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

检查以下内容：

本次收集后的次数是否被某个键覆盖。
次数区间是否使用 最小值-最大值 格式。
指令前缀是否正确。
指令本身是否可以正常执行。
PlaceholderAPI 是否已启用。
玩家数据是否已经加载。

未匹配到次数键时，插件取得的指令列表为空，不会执行任何指令。

变量显示为空、原样显示或数值不正确

插件变量通过 PlaceholderAPI 注册。首先确认：

PlaceholderAPI 已安装并启用。
控制台显示 LyGuideReload 已启动 PlaceholderAPI 前置。
变量中的图鉴 id、套装 id、怪物 id、名称或 Lore 与数据完全一致。
玩家数据已经加载。

变量参数中的尖括号只是文档占位符，实际使用时必须替换。例如：

text

%tjr_collect_count_test%

而不是：

text

%tjr_collect_count_<图鉴id>%

收藏分变量

变量	返回内容
`%tjr_all_point%`	玩家已获得的全部收藏分
`%tjr_suit_point_<套装id>%`	指定套装及其子图鉴相关收藏分
`%tjr_guide_point_<图鉴id>%`	指定图鉴的总收藏分
`%tjr_tag_point%`	当前总收藏分匹配到的称号

击杀变量

变量	返回内容
`%tjr_trigger_kill_<怪物id>%`	指定怪物累计击杀次数
`%tjr_trigger_first_kill_<怪物id>%`	是否存在首次击杀记录，返回 `0` 或 `1`

拾取变量

变量	返回内容
`%tjr_trigger_pickup_name_<物品名>%`	是否记录过指定名称物品的成功拾取收集
`%tjr_trigger_pickup_lore_<物品Lore>%`	是否记录过指定 Lore 物品的成功拾取收集
`%tjr_trigger_pickup_id_<物品id>%`	是否记录过指定数字 id 物品的成功拾取收集

当前代码没有注册 pickup_* 收集方法，因此这些拾取记录在当前构建中通常不会由图鉴配置产生。

使用变量

变量	返回内容
`%tjr_trigger_use_name_<物品名>%`	指定名称物品成功获得图鉴的次数
`%tjr_trigger_use_lore_<物品Lore>%`	指定 Lore 物品成功获得图鉴的次数
`%tjr_trigger_use_id_<物品id>%`	指定数字 id 物品成功获得图鉴的次数

使用物品概率失败时虽然会扣除物品，但不会增加对应的 use_* 记录。

图鉴和套装次数变量

变量	返回内容
`%tjr_collect_count_<图鉴id>%`	指定图鉴当前收集次数
`%tjr_collect_max_<图鉴id>%`	指定图鉴最大收集次数
`%tjr_collect_suit_<套装id>%`	套装内全部图鉴累计收集次数
`%tjr_attribute_<图鉴id>_<次数>_<行数>%`	指定次数对应的属性文本行，行数从 `0` 开始
`%tjr_attribute_<图鉴id>_now_<行数>%`	当前次数对应的属性文本行，行数从 `0` 开始
`%tjr_attribute_<图鉴id>_next_<行数>%`	当前次数加一对应的属性文本行，行数从 `0` 开始

MySQL 数据没有保存

启用 MySQL 时必须满足以下条件：

已安装 LyMySQLCore。
LyMySQLCore 已成功连接数据库。
mysql.enable 设置为 true。
数据库地址、端口、数据库名、用户名和密码正确。
修改数据库开关后已经重启服务器。

配置示例：

yaml

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

必须安装 LyMySQLCore 且成功连接数据库后，MySQL 相关功能才会生效。

MySQL 模式通过 LyMySQLCore 的玩家加载和保存事件处理数据，玩家被踢出时也会执行保存。数据库连接或表初始化失败时，应先检查控制台中的连接失败和初始化失败信息。

数据库连接地址会附加 UTF-8 字符集、UTC 时区并关闭 SSL。数据库服务端仍需允许填写的账号从服务器所在地址连接。

切换 MySQL 后为什么必须重启

玩家数据监听器只会在插件核心启动时根据 mysql.enable 注册：

true 注册 MySQL 数据监听器。
false 注册 YAML 数据监听器。

执行 /tjr reload 不会重新注册这组监听器。因此，修改 mysql.enable 后必须重启服务器，不能只执行重载。

YAML 数据没有保存

未启用 MySQL 时，插件使用 YAML 保存玩家数据：

yaml

mysql:
  enable: false

YAML 模式的主要数据时机为：

玩家加入后异步加载。
玩家正常退出时异步保存。
玩家被踢出时异步保存。
自动保存任务按配置间隔保存。

自动保存间隔单位为秒：

yaml

auto-save-interval: 3

如果刚进服时立即执行管理员指令并提示“数据未加载”，应等待异步加载完成后再执行。

玩家 YAML 文件损坏后会怎样

当前项目使用安全 YAML 写入逻辑：

使用 UTF-8 无 BOM 将数据写入唯一的临时文件。
将旧主文件移动到 .bak 备份位置。
使用原子移动替换主文件；文件系统不支持原子移动时回退到普通替换。
保存失败且主文件缺失时，尝试恢复备份。

加载时如果主文件无法解析，或文件中包含 NUL 字符，插件会：

输出玩家数据文件损坏警告。
删除损坏的主文件。
尝试读取同名 .bak 备份。
备份有效时恢复主文件并返回备份数据。
备份也损坏时删除损坏备份并返回空配置。

插件还会清理数据目录中遗留的 .tmp 临时文件。

不要在服务器运行期间手动修改玩家数据，也不要让多个服务端进程同时使用同一数据目录。

重载后配置没有变化

重载指令为：

text

/tjr reload

该指令要求执行者是 OP。

如果配置没有变化，检查：

YAML 缩进和语法是否正确。
图鉴或套装 id 是否重复。
修改的是否为插件实际数据目录中的文件。
是否修改了需要重启的配置，例如 mysql.enable 或 attribute-plugin。
控制台是否显示图鉴、套装和分类重新载入。

默认示例图鉴和示例套装会在每次重载时被覆盖，不应直接作为长期配置文件修改。

重载后默认图鉴或套装被覆盖

项目中的默认示例文件明确标注：每次 reload 都会覆盖。

正确处理方式：

复制示例图鉴或示例套装文件。
修改复制文件的文件名。
修改其中的 id，保证全局唯一。
再修改名称、图标、条件、方法、属性和指令。
不再直接编辑默认示例文件。

主配置还提供：

yaml

load-default-config: true

该键用于控制是否读取默认示例配置。如果仍启用默认配置，应避免让自定义文件与默认示例使用相同 id。

指令无法执行

插件只注册了主命令 tjr。项目没有声明独立的命令权限节点，管理员指令通过 OP 状态判断。

指令	OP 要求	玩家要求	说明
`/tjr reload`	需要	不限制	重载插件配置
`/tjr update <玩家>`	需要	不限制	当前代码存在参数判断问题
`/tjr addkill <玩家> <怪物id> <次数>`	需要	不限制	增加击杀数并检查击杀收集
`/tjr give <玩家> <图鉴id> <次数>`	需要	不限制	增加图鉴次数，忽略收集条件
`/tjr take <玩家> <图鉴id> <次数>`	需要	不限制	扣除图鉴次数
`/tjr set <玩家> <图鉴id> <次数>`	需要	不限制	设置图鉴次数
`/tjr try <玩家> <图鉴id> <几率>`	需要	不限制	按概率尝试收集并检查条件
`/tjr opent`	不需要	必须	打开套装总览
`/tjr class <分类id>`	不需要	必须	打开套装分类
`/tjr opens <套装id>`	不需要	必须	打开指定套装

give、take、set、try 和 addkill 都要求目标玩家在线且玩家数据已经加载。涉及图鉴 id 的指令还要求该图鉴存在。

手动修改图鉴次数有什么区别

指令	行为
`/tjr give <玩家> <图鉴id> <次数>`	直接增加图鉴收集次数，不检查 `collect-condition`
`/tjr take <玩家> <图鉴id> <次数>`	直接扣除图鉴收集次数
`/tjr set <玩家> <图鉴id> <次数>`	直接设置图鉴收集次数
`/tjr try <玩家> <图鉴id> <几率>`	检查 `collect-condition` 后按概率增加一次

次数参数必须是整数。当前指令层没有限制 give、take 或 set 只能填写正数，实际结果还会受到玩家数据方法内部处理影响。管理时应只填写符合预期的非负数。

直接修改次数不会伪造对应的击杀、拾取或使用物品记录。如果玩法或变量依赖 kill_*、pickup_*、use_* 触发记录，需要通过相应事件或专用接口维护。

`try` 指令没有获得图鉴

指令格式：

text

/tjr try <玩家> <图鉴id> <几率>

检查以下内容：

执行者是 OP。
目标玩家在线。
玩家数据已经加载。
图鉴 id 存在。
几率能够解析为数字。
图鉴的 collect-condition 全部满足。

大于 1 的几率会被限制为 1。建议始终填写 0 到 1，例如 0.25 表示约四分之一概率。

该指令按项目帮助说明不会发送普通尝试提示。概率失败或条件失败时，指令也不会说明具体是哪一项条件未满足。

为什么 `give` 可以绕过前置条件

示例图鉴明确说明，指令给予图鉴时无视 collect-condition。/tjr give 直接调用玩家数据的增加次数逻辑，没有执行 GuideData.isCollectCondition。

如果需要保留前置条件，应使用：

text

/tjr try <玩家> <图鉴id> 1

几率填写 1 时仍会检查图鉴的收集条件。需要注意，try 的 API 实现只负责条件与概率判断，管理员仍应避免对已经完成的图鉴重复调用。

属性、变量、条件或指令变量完全不可用

优先检查 PlaceholderAPI。

PlaceholderAPI 用于：

注册全部 %tjr_...% 变量。
解析 papi:{...} 收集条件。
解析 click-command 中的变量。
解析 get-command 中的变量。
解析其他通过插件指令工具执行的命令变量。

虽然 plugin.yml 将 PlaceholderAPI 声明为软依赖，但部分代码会直接调用 PlaceholderAPI 类。实际使用时建议安装并启用 PlaceholderAPI，避免变量功能不可用或相关流程出现异常。

声音配置后出现异常

获取图鉴和点击界面的声音分别由以下配置控制：

yaml

get-guide-sound: 'ORB_PICKUP'
click-sound: 'ORB_PICKUP'

声音名称会通过当前服务端的 Sound.valueOf 解析，不存在自动跨版本转换。不同 Minecraft 版本的声音枚举可能不同，例如默认配置注释中说明：

1.7 可使用 ORB_PICKUP。
1.12 可使用 ENTITY_EXPERIENCE_ORB_PICKUP。

如果声音名称不属于当前服务端版本，可能抛出枚举解析异常。完全不需要声音时，可以将对应值设置为空字符串。

已收集图鉴没有附魔效果

检查主配置：

yaml

guide-enchant: true

该配置用于控制已收集图鉴在界面中是否显示附魔效果。它只影响 GUI 展示，不代表图鉴属性是否已经生效。

如果收藏状态文本不正确，还应检查：

yaml

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

这两个键的默认名称与文本含义看起来相反，但应以实际界面结果为准。修改后可执行 /tjr reload 重新加载。

常见问题 ​

插件的主要用途是什么 ​

插件必须安装哪些前置 ​

打开界面时没有反应 ​

图鉴没有被收集 ​

收集条件应该怎么填写 ​

papi 条件支持哪些表达式 ​

首次击杀没有触发 ​

累计击杀次数没有增加 ​

kill 达到次数后仍没有获得图鉴 ​

如何手动增加击杀计数 ​

拾取物品没有触发 ​

使用物品没有触发 ​

使用物品失败后为什么仍然扣除了物品 ​

物品 id 应该怎么填写 ​

图鉴属性没有生效 ​

属性公式应该怎么填写 ​

修改收集次数后属性没有刷新 ​

ItemLoreOrigin 属性多久刷新一次 ​

套装没有激活 ​

套装完成指令没有执行 ​

套装总收藏分不正确 ​

分类界面没有显示套装 ​

图鉴点击指令没有执行 ​

获取图鉴后指令没有执行 ​

变量显示为空、原样显示或数值不正确 ​

收藏分变量 ​

击杀变量 ​

拾取变量 ​

使用变量 ​

图鉴和套装次数变量 ​

MySQL 数据没有保存 ​

切换 MySQL 后为什么必须重启 ​

YAML 数据没有保存 ​

玩家 YAML 文件损坏后会怎样 ​

重载后配置没有变化 ​

重载后默认图鉴或套装被覆盖 ​

指令无法执行 ​

手动修改图鉴次数有什么区别 ​

try 指令没有获得图鉴 ​

为什么 give 可以绕过前置条件 ​

属性、变量、条件或指令变量完全不可用 ​

声音配置后出现异常 ​

已收集图鉴没有附魔效果 ​

常见问题

插件的主要用途是什么

插件必须安装哪些前置

打开界面时没有反应

图鉴没有被收集

收集条件应该怎么填写

`papi` 条件支持哪些表达式

首次击杀没有触发

累计击杀次数没有增加

`kill` 达到次数后仍没有获得图鉴

如何手动增加击杀计数

拾取物品没有触发

使用物品没有触发

使用物品失败后为什么仍然扣除了物品

物品 id 应该怎么填写

图鉴属性没有生效

属性公式应该怎么填写

修改收集次数后属性没有刷新

ItemLoreOrigin 属性多久刷新一次

套装没有激活

套装完成指令没有执行

套装总收藏分不正确

分类界面没有显示套装

图鉴点击指令没有执行

获取图鉴后指令没有执行

变量显示为空、原样显示或数值不正确

收藏分变量

击杀变量

拾取变量

使用变量

图鉴和套装次数变量

MySQL 数据没有保存

切换 MySQL 后为什么必须重启

YAML 数据没有保存

玩家 YAML 文件损坏后会怎样

重载后配置没有变化

重载后默认图鉴或套装被覆盖

指令无法执行

手动修改图鉴次数有什么区别

`try` 指令没有获得图鉴

为什么 `give` 可以绕过前置条件

属性、变量、条件或指令变量完全不可用

声音配置后出现异常

已收集图鉴没有附魔效果