常见问题
LyGalaxyRune 用于为可刻印装备提供符文库、符文槽位、符文镶嵌、拆卸、槽位解锁、槽位升级和属性统计功能。符文数据保存在 SQLite 或 MySQL 中，装备本身只保存对应的符文库标识。
插件支持哪些 Minecraft 版本？
项目提供以下服务端版本适配：
| Minecraft 版本 | 适配版本 |
|---|---|
| 1.7.10 | V1_7_R4 |
| 1.8.8 | V1_8_R3 |
| 1.11.2 | V1_11_R1 |
| 1.12.2 | V1_12_R1 |
| 1.13.2 | V1_13_R2 |
| 1.14.4 | V1_14_R1 |
| 1.15.2 | V1_15_R1 |
| 1.16.5 | V1_16_R3 |
| 1.17.1 | V1_17_R1 |
| 1.18.2 | V1_18_R2 |
| 1.19.2 | V1_19_R1 |
| 1.19.4 | V1_19_R3 |
| 1.20.1 | V1_20_R1 |
| 1.20.2 | V1_20_R2 |
| 1.20.3 | V1_20_R3 |
必须安装哪些前置？
| 前置 | 类型 | 用途 |
|---|---|---|
| ProtocolLib | 必须 | 支持物品序列化和相关物品处理功能。 |
| Vault | 可选 | 使用 eco 金币条件时提供经济服务。还需要存在可用的经济插件。 |
| PlayerPoints | 可选 | 使用 point 点券条件时检查、扣除或返还点券。 |
| PlaceholderAPI | 可选 | 使用 papi 条件或带 PlaceholderAPI 变量的表达式时展开变量。 |
| 属性插件 | 按需选择 | attribute-plugin 支持 AttributePlus、AttributeSystem、SX-Attribute 和 ItemLoreOrigin。 |
| 数据库连接前置 | MySQL 模式必须安装 | 启用 MySQL 存储时必须安装，并且必须成功连接数据库；否则符文库相关功能不会生效。 |
SQLite 和 MySQL 有什么区别？
mysql.enable 为 false 时使用插件数据目录下的 SQLite 数据库文件 rune.db。
mysql.enable 为 true 时使用 MySQL 连接。此模式必须安装 数据库连接前置，并正确填写以下配置：
| 配置项 | 作用 |
|---|---|
mysql.ip | MySQL 服务地址。 |
mysql.port | MySQL 服务端口。 |
mysql.databasename | 数据库名称。 |
mysql.username | 数据库用户名。 |
mysql.password | 数据库密码。 |
只有数据库连接成功后，符文库读取、保存、镶嵌、拆卸、槽位升级、槽位解锁和备份恢复等依赖数据库的功能才会正常工作。
为什么打开界面后提示符文数据不可用？
常见原因包括：
- ProtocolLib 未安装、未启用或版本不匹配。
- MySQL 模式未安装 数据库连接前置。
- MySQL 地址、端口、数据库名称、用户名或密码填写错误。
- MySQL 数据库连接失败。
- 配置校验失败，插件没有加载可用配置。
SQLite 模式下请确认插件数据目录可读写；MySQL 模式下请先确认数据库连接已经成功。
插件有哪些命令？
| 命令 | 用途 | 执行要求 |
|---|---|---|
/lgr | 查看帮助。 | 只有管理员会看到帮助内容。 |
/lgr open | 打开符文刻印界面。 | 必须由玩家执行。 |
/lgr reload | 重载配置和符文界面。 | 需要管理员权限。 |
/lgr restore | 恢复手持物品对应的备份符文库。 | 需要管理员权限，且必须由玩家手持相关物品执行。 |
项目没有在配置中声明独立的权限节点，命令权限按管理员身份判断。
为什么装备不能放入界面？
装备需要同时满足以下条件：
- 物品数量必须为 1。
- 装备 Lore 中必须存在与
unload-rune-lore完全相同的一整行。 - 物品必须能够被识别为可刻印装备。
玩家在界面打开时点击背包中的装备即可自动放入。自动生成的符文数量和符文名称 Lore 带有隐藏定位标记，不要手动删除或修改这些标记。
为什么符文不能镶嵌？
符文物品的 Lore 中必须存在与 rune-item-lore 完全相同的一整行。除此之外，还需要满足以下条件：
- 当前已经放入可刻印装备。
- 当前页面存在已解锁且为空的符文槽位。
- 符文的等级要求不高于目标槽位当前等级。
- 玩家背包中的符文数量足够扣除。
点击背包中的符文时，插件会按当前页面的槽位顺序自动寻找可用位置。每页最多匹配 27 个符文槽位；没有可用槽位或没有满足等级要求的槽位时，不会继续镶嵌。
rune-level-key 如何限制符文等级？
rune-level-key 用于从符文 Lore 中识别最低槽位等级。模板必须包含且只能包含一个 {value}，识别出的值必须是 0 或正整数。
将该配置留空时，不检查符文等级。配置不为空时，符文 Lore 必须存在符合模板的整行文字；目标槽位当前等级低于符文要求时，符文不能镶嵌。
符文槽位如何解锁和升级？
| 配置段 | 作用 |
|---|---|
unlock-config | 配置解锁后的槽位数量和解锁条件。 |
slot-level-config | 配置槽位目标等级、展示 Lore、升级条件和属性增幅公式。 |
范围键表示目标结果，而不是当前状态。例如，unlock-config 中的 1-4 表示解锁第 1 至第 4 个槽位时使用同一段规则；slot-level-config 中的 2-5 表示升级到 2 至 5 级时使用同一段规则。
槽位解锁后的初始等级由 slot-level-config.1 决定。1 级只负责初始属性和界面展示，可以使用空的 condition；升级条件从目标等级 2 开始检查。
范围不能重叠，也不能出现断层。最后一个有效范围的最大数字决定可达到的最高槽位数量或最高等级。
槽位升级和解锁支持哪些条件？
配置条件支持以下类型：
| 条件类型 | 作用 | 前置 |
|---|---|---|
papi | 使用 PlaceholderAPI 表达式检查条件。 | 使用变量时需要 PlaceholderAPI。 |
permission | 检查玩家权限。 | 不需要额外前置。 |
item | 检查并扣除指定显示名称和数量的物品。 | 不需要额外前置。 |
point | 检查并扣除点券。 | PlayerPoints。 |
eco | 检查并扣除金币。 | Vault 和可用经济服务。 |
所有条件满足后，只有数据库保存成功才会正式扣除物品、点券或金币。保存失败时不会消耗这些资源。
为什么升级或解锁后没有立即写入？
界面中的升级和解锁操作先写入当前 GUI 草稿。取下装备或关闭界面时，插件才统一保存草稿并处理资源扣除。
玩家退出服务器时，尚未提交的界面草稿允许丢失；已经进入持久化操作流程的物品和资源操作会通过操作记录进行恢复处理。
界面中的左右键分别有什么作用？
| 点击位置 | 左键 | 右键 |
|---|---|---|
| 已镶嵌符文的槽位 | 升级槽位等级，鼠标必须为空。 | 拆卸符文。 |
| 已解锁的空槽位 | 升级槽位等级。 | 升级槽位等级。 |
| 未解锁槽位 | 解锁槽位。 | 解锁槽位。 |
| 装备槽位 | 取下装备或处理待交付装备。 | 取下装备或处理待交付装备。 |
启用 disassemble-need-item-enable 后，拆卸已镶嵌符文必须手持名称与 disassemble-item-name 完全相同的拆卸道具。disassemble-return-rune 决定拆卸成功后是否返还原符文。
为什么拆卸时提示需要工具？
当 disassemble-need-item-enable 为 true 时，必须将拆卸道具放在鼠标光标上，并点击已镶嵌符文的槽位。道具显示名称必须与 disassemble-item-name 完全相同，颜色代码也会参与识别。
当该配置为 false 时，拆卸不要求专用道具。
为什么符文属性没有生效？
符文属性必须符合 atttribute-increase-lore 中的 Lore 白名单。只有匹配白名单的 Lore 行才会参与属性统计。
| 配置项 | 作用 |
|---|---|
attribute-plugin | 选择属性处理插件，只支持 AttributePlus、AttributeSystem、SX-Attribute、ItemLoreOrigin。 |
atttribute-increase-lore | 配置可识别的属性 Lore 模板，必须包含且只能包含一个 {value}。 |
atttribute-increase-formula | 计算槽位等级带来的属性增幅，支持四则运算和 {level}。 |
attribute-refresh-interval | 设置属性变化检查间隔，单位为 tick；20 tick 约等于 1 秒。 |
界面中的属性统计会计算已镶嵌符文的实际属性，并计入槽位等级增幅。符文库内容、装备、主副手、背包或玩家状态变化后，插件会重新刷新属性。
槽位等级属性增幅如何计算？
atttribute-increase-formula 中的 {level} 会替换为目标槽位等级，公式结果表示属性增幅比例。公式结果为 0.15 时表示增加 15%。
槽位等级显示由 show-lore 控制，支持以下变量：
| 变量 | 含义 |
|---|---|
{current_level} | 当前等级。 |
{next_level} | 下一等级。 |
{max_level} | 最高等级。 |
{current_attribute_increase} | 当前属性增幅。 |
{next_attribute_increase} | 下一等级属性增幅。 |
达到最高等级后显示 max-level-show-lore 的内容。
为什么装备 Lore 没有显示符文数量？
请检查以下配置：
rune-lore中是否配置了数量展示文本。- 文本中的
{now}和{max}是否使用正确。 - 装备原本是否存在可刻印标识 Lore。
- 是否手动删除了插件生成的隐藏定位标记。
{now} 表示当前已镶嵌符文数量，{max} 表示当前已经解锁的槽位数量。将 enable-show-slot 设为 true 时，还会根据 show-slot-format 展示已镶嵌符文的名称。
为什么背包空间不足时物品没有消失？
符文拆卸产物或保存后的装备无法立即交付时，插件会保留待交付状态，不会直接删除物品。玩家需要清理背包空间，之后重新登录或再次点击对应界面位置领取。
待交付物品会被阻止丢弃、被漏斗移动或作为死亡掉落，避免恢复记录与实际物品重复。
复制装备后符文是否共用？
是。装备只保存符文库标识，复制出的装备如果指向同一个符文库，就会共用该符文库中的符文、槽位等级和其他数据。修改共享符文库后，正在使用该库的玩家会刷新符文属性。
是否兼容旧版符文数据？
当前项目使用纯 V2 数据结构，不读取、迁移或兼容旧版符文数据。旧版符文数据不能直接作为当前版本数据使用。
符文库会被删除吗？
自动归档默认关闭，由 library-gc.enable 控制。启用后采用两阶段策略：符文库先进入未访问观察期，经过 grace-days 后才移动到备份表，不会直接删除。
| 配置项 | 作用 |
|---|---|
library-gc.interval-hours | 归档扫描间隔，单位为小时。 |
library-gc.inactive-days | 连续未访问多少天后进入观察期。 |
library-gc.grace-days | 进入观察期后继续等待的天数。 |
library-gc.batch-size | 每次扫描最多处理的符文库数量。 |
管理员可以手持带有有效符文库标识的装备执行 /lgr restore，恢复对应的备份符文库。
为什么镶嵌或拆卸后需要等待？
operation-cooldown-ms 控制成功镶嵌或拆卸后的操作冷却时间，单位为毫秒。默认值为 200，设置为 0 时关闭冷却，允许范围为 0 到 60000。
该冷却只限制符文镶嵌和拆卸操作，不代表数据库保存周期。
为什么保存操作有时会等待几秒？
普通符文库和槽位保存使用单写入队列批量处理：最多等待约 5 秒触发，队列达到 32 个任务时会提前触发；高峰期有积压时会连续处理。
5 秒是最迟触发窗口，不是固定每 5 秒只保存一批。读取使用独立的有界线程池，写入仍由单写入队列处理，以降低数据库锁竞争。
如何确认配置是否有效？
执行 /lgr reload 后，插件会重新加载并校验配置。重点检查以下内容：
unlock-config和slot-level-config的范围格式、重叠和断层。atttribute-increase-lore是否每行只有一个{value}。rune-level-key是否为空或只包含一个{value}。- 槽位等级公式是否能计算出有限的非负数。
- 启用 MySQL 时连接参数是否完整。
- 启用符文库归档时，扫描周期、期限和批量大小是否有效。
配置校验失败时会保留当前可用配置，不会将错误配置用于符文操作。