LyGalaxyRune
LyGalaxyRune 是一个服务端符文刻印插件。玩家可以把符文镶嵌到符合条件的装备中，通过解锁槽位和升级槽位等级提高符文属性，并在符文界面中查看、镶嵌、升级和拆卸符文。
项目证据中未发现客户端 MOD 模块，因此这是纯服务端插件，不要求玩家额外安装客户端 MOD。
用途与玩法
- 使用装备 Lore 识别可以刻印符文的装备。
- 使用符文 Lore 识别可镶嵌的符文物品。
- 通过六行九列的符文界面管理装备符文。
- 每页显示最多 27 个符文槽位，支持翻页。
- 解锁符文槽位后，可以在对应槽位中镶嵌符文。
- 已镶嵌槽位支持升级和拆卸。
- 槽位等级可以提供配置中的属性增幅。
- 符文属性会提交给配置指定的属性插件。
- 符文库使用 SQLite 或 MySQL 保存，装备可以引用共享符文库。
- 长期未访问的符文库可以进入观察期并归档到备份数据中。
依赖与兼容版本
服务端依赖
| 依赖 | 类型 | 用途 |
|---|---|---|
| ProtocolLib | 必需依赖 | 插件启动所需的服务端协议支持。 |
| PlayerPoints | 可选依赖 | point 条件以及点券扣除。未安装时，使用点券条件的解锁或升级无法完成。 |
| Vault | 可选依赖 | eco 条件以及金币扣除。未安装或没有可用经济服务时，使用金币条件的操作无法完成。 |
| PlaceholderAPI | 可选依赖 | papi 条件和配置中的 PlaceholderAPI 变量替换。使用相关条件时必须可用。 |
| 属性插件 | 按配置选择 | 支持 AttributePlus、AttributeSystem、SX-Attribute、ItemLoreOrigin。 |
| 数据库连接前置 | MySQL 模式必需 | 启用 MySQL 后必须安装，并且数据库连接成功后相关功能才会生效。 |
SQLite 模式默认使用插件数据目录中的 rune.db。MySQL 模式由 mysql.enable 控制；数据库连接失败时，符文相关功能不会正常初始化。
服务端版本
项目包含以下 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 |
符文界面
默认界面标题为 &6符文刻印，布局为六行九列。
| 组件 | 默认字符 | 功能 |
|---|---|---|
| 装备槽位 | E | 放入或查看当前装备。 |
| 属性统计 | A | 统计所有已镶嵌符文的实际属性，并计入槽位等级增幅。 |
| 符文槽位 | R | 显示空槽位、已镶嵌符文或槽位升级信息。 |
| 上一页 | < | 切换到上一页符文槽位。 |
| 下一页 | > | 切换到下一页符文槽位。 |
| 关闭 | X | 关闭符文界面。 |
符文界面支持以下操作：
- 点击背包中的可刻印装备，自动放入装备槽位。
- 点击背包中的符文，自动尝试放入当前页可用的符文槽位。
- 已镶嵌槽位左键升级，右键拆卸。
- 已解锁的空槽位左右键均可尝试升级。
- 未解锁槽位左右键均可尝试解锁。
- 拆卸时按照配置决定是否需要拆卸工具，以及是否返还原符文。
- 取下装备或关闭界面时，界面中的草稿内容统一提交。
- 界面操作成功后，资源会按照配置条件处理；数据库保存失败时会执行资源补偿流程。
- 取下装备不会自动关闭界面。
默认布局如下：
yaml
layout:
- '####E####'
- '###A#####'
- 'RRRRRRRRR'
- 'RRRRRRRRR'
- 'RRRRRRRRR'
- '<###X###>'指令
plugin.yml 中注册的命令名为 lgfw，本文按照注册证据使用 /lgfw。
| 指令 | 功能 |
|---|---|
/lgfw open | 打开符文界面。 |
/lgfw reload | 重载插件配置和符文界面配置。 |
/lgfw restore | 由玩家手持物品恢复对应的备份符文库。 |
项目证据没有提供具体权限节点名称，因此本文不填写未经确认的权限字符串。备份恢复限制为管理员操作；备份恢复还必须由玩家手持物品执行。
配置总览
主配置文件为 config.yml，界面配置文件为 gui/符文界面.yml。配置键必须保持原名称，包括 atttribute-increase-lore 和 atttribute-increase-formula 中已有的拼写。
基础配置
| 配置键 | 默认值 | 说明 |
|---|---|---|
attribute-plugin | AttributePlus | 选择属性处理插件。支持 AttributePlus、AttributeSystem、SX-Attribute、ItemLoreOrigin。 |
attribute-refresh-interval | 20 | 检查符文属性变化的间隔，单位为 tick。20 tick 约为 1 秒。 |
operation-cooldown-ms | 200 | 镶嵌或拆卸成功后的操作冷却，单位为毫秒。填写 0 表示关闭冷却。 |
condition-true-text | &a✔ | 条件满足时，{status} 使用的文字。 |
condition-false-text | &c✘ | 条件不满足时，{status} 使用的文字。 |
yaml
attribute-plugin: 'AttributePlus'
attribute-refresh-interval: 20
operation-cooldown-ms: 200
condition-true-text: '&a✔'
condition-false-text: '&c✘'数据库配置
yaml
mysql:
enable: false
ip: '127.0.0.1'
port: 3306
databasename: 'mc2'
username: 'mc2'
password: 'mc1234'| 配置键 | 说明 |
|---|---|
mysql.enable | false 使用 SQLite，true 使用 MySQL。 |
mysql.ip | MySQL 地址。 |
mysql.port | MySQL 端口。 |
mysql.databasename | 数据库名称。 |
mysql.username | 数据库用户名。 |
mysql.password | 数据库密码。 |
启用 MySQL 时，必须安装 数据库连接前置，并确保数据库连接成功。只有连接成功后，符文库、槽位数据和相关存储功能才会生效。
调试与归档
yaml
debug:
storage: false
library-gc:
enable: false
interval-hours: 12
inactive-days: 180
grace-days: 30
batch-size: 50| 配置键 | 说明 |
|---|---|
debug.storage | 是否输出符文库读取、保存和归档扫描的调试信息，默认关闭。数据库错误提示不受影响。 |
library-gc.enable | 是否启用长期未访问符文库的自动归档。 |
library-gc.interval-hours | 归档扫描的最短间隔，单位为小时。 |
library-gc.inactive-days | 符文库连续未访问达到该天数后进入观察期。 |
library-gc.grace-days | 进入观察期后继续等待的天数，期间再次访问会取消归档标记。 |
library-gc.batch-size | 单次归档扫描最多处理的符文库数量。 |
归档是两阶段流程，归档数据会移动到备份表，不会直接删除。归档功能默认关闭。
玩家消息
message 配置用于界面操作反馈，主要键包括：
| 配置键 | 用途 |
|---|---|
unlock-slot-success | 槽位解锁成功。 |
unlock-slot-fail | 槽位解锁失败。 |
slot-level-upgrade-success | 槽位升级成功。 |
slot-level-upgrade-max | 槽位已经达到最高等级。 |
slot-level-upgrade-config-fail | 槽位升级规则不可用。 |
slot-level-upgrade-condition-fail | 槽位升级条件不满足。 |
slot-level-upgrade-cost-fail | 升级资源不足。 |
slot-level-upgrade-state-fail | 界面状态已经变化。 |
equipment-amount-one | 装备数量不是一件。 |
item-not-equipment | 物品不是可刻印装备。 |
rune-loading | 符文正在加载。 |
attribute-loading | 符文属性正在计算。 |
attribute-retry | 属性读取失败后的提示。 |
rune-no-available-slot | 没有空闲槽位。 |
rune-level-no-match | 没有符合符文等级要求的槽位。 |
rune-source-not-enough | 当前符文已经全部预留。 |
cursor-item-not-out-item | 手持物品不是正确的拆卸工具。 |
out-rune-need-item | 拆卸时需要先手持拆卸工具。 |
rune-upgrade-empty-cursor | 升级槽位时手上必须为空。 |
disassemble-inventory-full | 背包空间不足，无法取出符文。 |
operation-delivery-pending | 物品暂时无法返还，等待后续领取。 |
equipment-takeoff-pending | 装备暂时无法取出。 |
operation-cooldown | 操作仍在冷却。 |
gui-draft-pending | 操作成功，取下装备后生效。 |
gui-draft-cost-fail | 草稿操作所需资源不足。 |
gui-draft-state-fail | 草稿状态已经变化。 |
database-message 负责数据库不可用、备份恢复和相关提示，支持的键包括 unavailable、missing、restore-loading、restore-success、restore-active、restore-missing、restore-failed、restore-no-library、restore-no-permission 和 restore-player-only。
装备与符文识别
yaml
rune-lore:
- '&6已刻印 &a{now}/{max} &6个符文'
enable-show-slot: true
show-slot-format: '&7已刻印 >> &6{rune}'
unload-rune-lore: '&6可刻印符文'
rune-item-lore: '&7类型: &a符文'
rune-level-key: '&f符文等级: {value}'| 配置键 | 说明 |
|---|---|
rune-lore | 装备成功镶嵌符文后写入的 Lore 列表。 |
enable-show-slot | 是否展开 {show_slot}，逐个显示已镶嵌符文名称。 |
show-slot-format | 单个符文名称的显示格式，{rune} 会替换为符文显示名称。 |
unload-rune-lore | 可刻印装备必须包含的整行 Lore。默认值为 &6可刻印符文。 |
rune-item-lore | 符文物品必须包含的识别 Lore。默认值为 &7类型: &a符文。 |
rune-level-key | 符文等级限制的 Lore 模板。留空表示不限制等级。 |
装备识别 Lore 必须与配置内容完全匹配。符文识别会匹配配置指定的 Lore 文本，并处理颜色码和首尾空格差异。rune-level-key 只能使用一个 {value}，数值必须为 0 或正整数。
拆卸配置
yaml
disassemble-need-item-enable: true
disassemble-item-name: '&6符文蜕印石'
disassemble-return-rune: true| 配置键 | 说明 |
|---|---|
disassemble-need-item-enable | 是否必须手持拆卸工具。 |
disassemble-item-name | 拆卸工具的显示名称，必须完全匹配。 |
disassemble-return-rune | 拆卸成功后是否返还原符文。 |
属性与槽位等级
yaml
atttribute-increase-lore:
- '&f物理伤害 +{value}'
max-level-show-lore: '&6已满级'atttribute-increase-lore 是属性 Lore 白名单。只有与列表模板匹配的符文 Lore 才会参与属性统计。{value} 表示属性数值，也支持例如 10-20 这样的范围值。
槽位等级配置的键表示目标等级范围。默认规则如下：
yaml
slot-level-config:
1:
atttribute-increase-formula: '{level} * 0.05'
show-lore:
- '&7当前等级: &e{current_level}/{max_level} 级'
- '&7当前属性增幅: &e{current_attribute_increase}'
- '&7下级属性增幅: &e{next_attribute_increase}'
condition: []
2-5:
atttribute-increase-formula: '{level} * 0.05'
show-lore:
- '&7当前等级: &e{current_level}/{max_level} 级'
- '&7当前属性增幅: &e{current_attribute_increase}'
- '&7下级属性增幅: &e{next_attribute_increase}'
condition:
- 'item:{&6符文槽位升级石#{level}}| &6{item}x{amount} {status}'
- 'eco:{{level} * 100}| &7金币x{amount} {status}'
6-10:
atttribute-increase-formula: '{level} * 0.05'
show-lore:
- '&7当前等级: &e{current_level}/{max_level} 级'
- '&7当前属性增幅: &e{current_attribute_increase}'
- '&7下级属性增幅: &e{next_attribute_increase}'
condition:
- 'item:{&6高级符文槽位升级石#{level}}| &6{item}x{amount} {status}'
- 'eco:{{level} * 200}| &7金币x{amount} {status}'1 级是新解锁槽位的初始等级，默认每级增加 5% 属性。升级条件从目标等级 2 开始检查。范围键不能重叠或断档，最后一个范围的最大值决定最高等级。
槽位解锁
yaml
unlock-config:
1-4:
show-lore:
- '&7当前槽位数量: &e{current_slot} / {max_slot}&7 个'
condition:
- 'papi:{%player_level% > 0}| &7需要玩家等级大于0级 {status}'
- 'item:{&6符文破印石#{slot}}| &6{item}x{amount} {status}'
- 'eco:{ (%player_level%+{slot}) * 5 }| &7金币x{amount} {status}'
5-10:
show-lore:
- '&7当前槽位数量: &e{current_slot} / {max_slot}&7 个'
condition:
- 'papi:{%player_level% > 0}| &7需要玩家等级大于0级 {status}'
- 'item:{&6符文破印石#{slot}}| &6{item}x{amount} {status}'
- 'eco:{ (%player_level%+{slot}) * 10 }| &7金币x{amount} {status}'范围键表示解锁完成后的槽位数量。例如 1-4 表示解锁第 1 至第 4 个槽位时使用同一组规则。默认最多解锁 10 个槽位。
条件类型
条件格式为：
text
实际条件|界面显示文字| 类型 | 格式 | 功能 |
|---|---|---|
papi | papi:{表达式} | 使用 PlaceholderAPI 变量计算逻辑表达式。 |
permission | permission:{权限节点} | 检查玩家是否拥有指定权限。 |
item | item:{显示名称#数量表达式} | 检查并扣除背包中显示名称匹配的物品。 |
point | point:{数量表达式} | 检查并扣除 PlayerPoints 点券。 |
eco | eco:{数量表达式} | 检查并扣除 Vault 经济余额。 |
升级或解锁的所有条件都满足，并且数据库保存成功后，物品、点券和金币才会正式扣除。保存失败时会执行退款或保留待补偿记录。
运行时变量
装备 Lore 变量
| 变量 | 所在配置 | 含义 |
|---|---|---|
{now} | rune-lore | 当前已经镶嵌的符文数量。 |
{max} | rune-lore | 当前已经解锁的槽位数量。 |
{show_slot} | rune-lore | 展开逐个符文显示行。 |
{rune} | show-slot-format | 符文的显示名称。 |
{value} | rune-level-key、atttribute-increase-lore | 符文等级或属性数值。 |
槽位和解锁变量
| 变量 | 所在配置 | 含义 |
|---|---|---|
{level} | 槽位等级条件、属性公式 | 当前目标等级。 |
{slot} | 槽位解锁条件 | 当前目标槽位编号。 |
{current_level} | 槽位展示 Lore | 当前槽位等级。 |
{next_level} | 槽位展示 Lore | 下一等级。 |
{max_level} | 槽位展示 Lore | 最高等级。 |
{current_attribute_increase} | 槽位展示 Lore | 当前属性增幅。 |
{next_attribute_increase} | 槽位展示 Lore | 下一等级属性增幅。 |
{current_slot} | 解锁展示 Lore | 当前已解锁槽位数量。 |
{next_slot} | 解锁展示 Lore | 下一次解锁后的槽位数量。 |
{max_slot} | 解锁展示 Lore、装备模板 | 最大可解锁槽位数量。 |
{item} | 条件显示文字 | 条件要求的物品名称。 |
{amount} | 条件显示文字 | 条件要求的数量。 |
{status} | 条件显示文字 | 条件满足或不满足的状态文字。 |
GUI 变量
| 变量 | 所在配置 | 含义 |
|---|---|---|
{unlocked} | 装备模板 | 当前已经解锁的槽位数量。 |
{attribute} | 属性统计按钮 | 所有已镶嵌符文的属性统计结果。 |
{level} | 已解锁槽位模板 | 当前槽位等级。 |
{current_stage} | 槽位 Lore | 当前等级阶段的展示内容。 |
{next_stage} | 槽位 Lore | 下一等级阶段的展示内容。 |
{upgrade_condition} | 槽位和解锁 Lore | 下一次升级或解锁的条件显示内容。 |
{current_condition} | 未解锁槽位 Lore | 当前解锁阶段的展示内容。 |
{library_id} | database-message.restore-success | 恢复成功的符文库 ID。 |
运行时变量统一使用 {变量} 格式。PlaceholderAPI 表达式仍使用 PlaceholderAPI 自身的变量格式，例如默认配置中的 %player_level%。
属性机制
插件会按照 atttribute-increase-lore 过滤符文属性 Lore，并将统计结果应用到 attribute-plugin 指定的属性插件。
支持的属性插件名称为：
AttributePlusAttributeSystemSX-AttributeItemLoreOrigin
属性刷新默认每 20 tick 检查一次。玩家退出、插件停用或配置重载时，会清理本插件提交的属性来源。属性插件未安装、未启动、接口不匹配或配置名称错误时，属性不会正常提交。
常见问题
装备无法放入界面
检查装备 Lore 是否包含与 unload-rune-lore 完全相同的一整行文字。默认值为 &6可刻印符文。装备数量必须为 1。
符文无法镶嵌
检查符文 Lore 是否包含与 rune-item-lore 对应的识别文字，并确认目标槽位已经解锁且等级满足 rune-level-key 的要求。
槽位无法解锁
检查当前目标槽位是否落在 unlock-config 的有效范围内，再检查 PlaceholderAPI 条件、物品数量、金币余额和其它配置条件。默认第 1 至第 4 个槽位与第 5 至第 10 个槽位使用不同的金币公式。
槽位无法升级
检查目标等级是否配置在 slot-level-config 的有效范围内，并确认升级材料和金币足够。1 级是新解锁槽位的初始等级，升级条件从目标等级 2 开始。
拆卸按钮没有反应
当 disassemble-need-item-enable 为 true 时，必须手持显示名称与 disassemble-item-name 完全一致的拆卸工具。默认工具名称为 &6符文蜕印石。
属性没有生效
确认 attribute-plugin 填写的是支持的名称，并确认对应属性插件已经启动。符文 Lore 还必须匹配 atttribute-increase-lore 白名单。属性刷新默认最多等待约 20 tick。
MySQL 模式启动后功能不可用
确认已经安装 数据库连接前置，mysql.enable 已设置为 true，并检查地址、端口、数据库名、用户名和密码。只有数据库成功连接后，符文库和相关功能才会生效。
点券或金币条件无法完成
点券条件需要可用的 PlayerPoints，金币条件需要可用的 Vault 经济服务。使用 papi 条件时还需要 PlaceholderAPI 正常运行。
关闭界面后修改没有立即写入
界面操作会先记录在当前界面草稿中，取下装备或关闭界面时统一提交。数据库保存失败时不会将未完成的修改当作成功结果。
归档后的符文库如何处理
启用 library-gc 后，长期未访问的符文库会先进入观察期，之后移动到备份表。管理员可以使用手持带有效符文库引用的物品执行 /lgfw restore，恢复对应的备份数据。