福利·ZF符文复刻版 LyZFRunes

LyZFRunes 是一个符文镶嵌插件。插件通过装备 Lore 中的符文槽位标记识别可用槽位，将符文属性记录到装备 NBT，并在符文界面中提供装备放入、符文镶嵌、符文拆卸和分页查看功能。

功能概览

• 配置并注册多个符文物品。
• 为符文设置物品名称、Lore、材质、附魔显示和属性文本。
• 通过装备 Lore 中的空槽位标记判断装备是否可以镶嵌指定符文。
• 镶嵌符文后，将空槽位标记替换为已镶嵌标记。
• 将符文数据保存到装备 NBT 的 rune_data 字段。
• 在符文界面中查看装备已经镶嵌的符文。
• 支持从装备中拆卸指定符文，并返还对应符文物品。
• 支持 36 个符文显示槽位和多页符文列表。
• 支持装备放入、取下、镶嵌成功、镶嵌失败、拆卸成功和拆卸失败动作。
• 支持属性插件读取已镶嵌符文的 stats-list 属性文本。
• 支持将 ZF-Runes 的符文配置转换为 LyZFRunes 配置。
• 支持通过指令向在线玩家发放已注册的符文。

依赖与兼容说明

基础依赖

插件自身的 plugin.yml 将以下插件声明为软依赖。未配置对应功能时，不一定需要安装：

插件	用途
PlaceholderAPI	项目中存在 PlaceholderAPI 接入类，但当前核心初始化流程未启用该注册逻辑。
AttributePlus	将符文的 stats-list 属性文本交给 AttributePlus。
SX-Attribute	支持 SX-Attribute 2.x 或 3.x 接入。
AttributeSystem	将符文属性文本交给 AttributeSystem。
ItemLoreOrigin	作为属性系统接入选项。

可选槽位来源

attribute-slot 中配置了对应槽位来源时，插件会从该位置读取装备和符文数据。使用某个扩展槽位前，需要安装并正确启用对应插件：

槽位来源	配置格式
DragonCore	DragonCore#槽位名
GermPlugin	GermPlugin#槽位名
APInventory	APInventory#分页ID#槽位ID
LyInventory	LyInventory#背包ID#类型
LyInventoryReload	LyInventoryReload#背包ID#类型
PXRPG	PXRPG#类型#背包ID#槽位
YeeJewelry	YeeJewelry#背包ID#类型
原版背包	Minecraft#槽位ID
主手	Origin#MainHand
旧版主手	Origin2#MainHand
副手	Origin#OffHand
头盔	Origin#Helmet
胸甲	Origin#ChestPlate
护腿	Origin#Legging
靴子	Origin#Boots

支持版本

项目提供了以下 Minecraft 服务端 NMS 实现：

Minecraft 版本
1.7.10
1.8.8
1.11.2
1.12.2
1.13.2
1.14.4
1.15.2
1.16.5
1.17.1
1.18.2
1.19.2
1.19.4
1.20.1
1.20.2
1.20.3

项目证据未提供其他 Minecraft 版本的 NMS 实现。未列出的版本不能根据当前项目文件确认兼容。

命令

主命令为 /lzr。权限判断由插件直接使用 OP 状态完成，项目未定义独立权限节点。

命令	使用者	说明
/lzr	OP	显示管理命令帮助。
/lzr reload	OP	重载 config.yml，重新加载符文文件和属性任务。
/lzr open	玩家	打开符文镶嵌界面。该命令要求执行者是玩家。
/lzr load	OP	转换 plugins/ZF-Runes/RunesItem 下的 ZF-Runes 配置，并保存到 LyZFRunes 的 RunesItem/ZF-Runes 子目录。
/lzr give <玩家> <符文ID> <数量>	OP	向在线玩家发放指定数量的已注册符文。

give 命令支持的参数补全包括在线玩家名、已加载的符文 ID，以及数量提示 1、16 和 64。

符文界面

符文界面是一个 54 格容器：

• 前 36 格用于显示装备已经镶嵌的符文。
• 第 45 格为上一页按钮。
• 第 49 格为装备槽位。
• 第 53 格为下一页按钮。
• 第 40 格为使用说明按钮。
• 界面关闭时，第 49 格中的装备会返还给玩家。
• 界面内的拖拽操作会被禁止。
• 界面内的分页按钮只在存在上一页或下一页时生效。
• 点击背包中的第一个物品时，如果界面装备槽为空，插件会将该物品作为待处理装备放入第 49 格。
• 已放入装备后，点击带有符文 NBT 标识的符文物品会尝试镶嵌。
• 点击已镶嵌符文可以尝试拆卸对应符文。

镶嵌机制

装备槽位标记

每个符文使用两个槽位显示文本：

• use-slot-name：镶嵌前需要在装备 Lore 中存在的空槽位文本。
• slot-name：镶嵌后写入装备 Lore 的已占用槽位文本。

插件会使用 Distinguish.Prefix 和 Distinguish.Suffix 包裹这两个文本。默认格式为：

&f【槽位文本&f】

镶嵌时，插件只替换装备 Lore 中找到的第一个匹配空槽位；拆卸时，插件只还原找到的第一个匹配已占用槽位。

符文数据

符文物品会写入 rune_id NBT 字段，用于识别符文配置。装备镶嵌符文后，会在 rune_data NBT 字段中保存每个符文条目，包括符文 ID、已占用槽位文本和原空槽位文本。

如果符文物品没有 rune_id，或者该 ID 没有在当前已加载配置中注册，镶嵌会失败。

如果装备不存在对应空槽位，镶嵌会失败，装备不会被修改。

拆卸时，如果装备中不存在对应的符文记录或已占用槽位，拆卸会失败，装备不会被修改。

属性机制

插件会按 attribute-slot 配置读取玩家指定位置的装备，读取装备中已经保存的符文，并将这些符文的 stats-list 内容合并为属性文本列表。

支持的属性插件配置值如下：

attribute-plugin 值	对接方式
AttributePlus	调用 AttributePlus 的属性接口。
SX-Attribute2	调用 SX-Attribute 2.x 接口。
SX-Attribute3	调用 SX-Attribute 3.x 接口。
AttributeSystem	调用 AttributeSystem 属性接口。
ItemLoreOrigin	作为 ItemLoreOrigin 属性接入选项。
空值或其他值	不执行上述属性插件接入。

属性刷新任务会定时处理等待刷新的玩家。玩家关闭容器、切换副手或触发对应版本的快捷栏切换事件后，会加入属性刷新队列。

属性系统只读取 attribute-slot 配置指定位置的装备，不会自动读取所有背包物品。

配置文件

插件主要使用以下文件：

文件	作用
config.yml	属性接入、属性装备槽位、界面、符文前后缀、动作和消息配置。
RunesItem/*.yml	符文定义文件。插件会递归加载该目录下的所有 .yml 文件。
RunesItem/Default.yml	插件首次运行时保存的默认符文示例。

attribute-plugin

attribute-plugin: ''

用于选择属性插件。可填写：

• AttributePlus
• SX-Attribute2
• SX-Attribute3
• AttributeSystem
• ItemLoreOrigin

attribute-slot

attribute-slot:
  - 'Origin#MainHand'

列表中的每一项表示一个需要读取的装备槽位。插件会遍历列表，读取其中存在的装备，并累加装备上已镶嵌符文的 stats-list。

类型	格式	说明
DragonCore	DragonCore#槽位名	读取 DragonCore 槽位。
GermPlugin	GermPlugin#槽位名	读取 GermPlugin 槽位。
APInventory	APInventory#分页ID#槽位ID	槽位 ID 范围为 0 到 53。
LyInventory	LyInventory#背包ID#类型	读取 LyInventory 背包槽位。
LyInventoryReload	LyInventoryReload#背包ID#类型	读取 LyInventory 重置版背包槽位。
PXRPG	PXRPG#类型#背包ID#槽位	读取 PXRPG 装备容器槽位。
YeeJewelry	YeeJewelry#背包ID#类型	读取 YeeJewelry 槽位。
Minecraft	Minecraft#槽位ID	读取原版背包槽位。
Origin	Origin#MainHand	读取主手。也支持 OffHand、Helmet、ChestPlate、Legging 和 Boots。
Origin2	Origin2#MainHand	读取旧版主手。

gui

gui:
  title: '&0符文'
  fill-item: '160:0'
  fill-name: '&7封锁'
  last-item: '341:0'
  last-name: '&6上一页'
  next-item: '341:0'
  next-name: '&6下一页'
  empty-item: '166:0'
  empty-name: '&7'
  info-item: '61:0'
  info-name: '&7使用说明'
  info-lore:
    - ''
    - '&7先点击装备, 即可将装备放置到下方槽位中.'
    - '&7然后点击背包内的符文即可尝试刻印符文'
    - '&7或者点击上方符文即可尝试拆卸符文'

配置键	作用
gui.title	符文界面标题。
gui.fill-item	界面填充物品。支持数字材质格式，例如 160:0。
gui.fill-name	界面填充物品名称。
gui.last-item	上一页按钮物品。
gui.last-name	上一页按钮名称。
gui.next-item	下一页按钮物品。
gui.next-name	下一页按钮名称。
gui.empty-item	空槽位显示物品。
gui.empty-name	空槽位显示名称。
gui.info-item	使用说明按钮物品。
gui.info-name	使用说明按钮名称。
gui.info-lore	使用说明按钮 Lore。

文本中的 & 颜色代码会转换为 Minecraft 颜色代码。

Distinguish

Distinguish:
  Prefix: '&f【'
  Suffix: '&f】'

配置键	作用
Distinguish.Prefix	符文槽位文本前缀。
Distinguish.Suffix	符文槽位文本后缀。

action

动作配置使用 Aviator 表达式执行。当前项目提供的内置动作函数为 方法.音效，参数必须是服务端当前版本存在的 Bukkit Sound 名称。

action:
  put-in-equip:
    - "方法.音效('BLOCK_CLOTH_PLACE')"
  take-down-equip:
    - "方法.音效('BLOCK_CLOTH_PLACE')"
  inlay-success:
    - "方法.音效('ORB_PICKUP')"
    - "方法.音效('ENTITY_EXPERIENCE_ORB_PICKUP')"
  inlay-failed: []
  disassemble-success:
    - "方法.音效('ORB_PICKUP')"
    - "方法.音效('ENTITY_EXPERIENCE_ORB_PICKUP')"
  disassemble-failed: []

配置键	触发时机
action.put-in-equip	装备放入界面时。
action.take-down-equip	装备从界面取下时。
action.inlay-success	符文镶嵌成功时。
action.inlay-failed	符文镶嵌失败时。
action.disassemble-success	符文拆卸成功时。
action.disassemble-failed	符文拆卸失败时。

动作列表为空时，不执行动作。音效名称不存在时，音效动作会执行失败并输出错误信息。

message

message:
  not-rune: '&7你点击的物品不是符文, 无法进行刻印.'
  not-slot: '&7你点击的符文在该装备上没有对应的符文孔.'
  inlay-success: '&7刻印成功!'
  disassemble-success: '&7拆卸成功!'

配置键	作用
message.not-rune	点击的物品不是已注册符文时发送的消息。
message.not-slot	装备没有对应空槽位时发送的消息。
message.inlay-success	镶嵌成功时发送的消息。
message.disassemble-success	拆卸成功时发送的消息。

镶嵌失败的动作会执行 action.inlay-failed。拆卸失败的动作会执行 action.disassemble-failed。部分拆卸失败情况使用代码中的固定提示，不经过 message 配置。

符文文件格式

插件会读取 plugins/LyZFRunes/RunesItem 目录及其子目录中所有扩展名为 .yml 的文件。每个顶级键都是一个符文 ID。

示例符文1:
  name: '&c狂暴之嗜血符文'
  enchant: true
  id: '351:1'
  lore:
    - '&c镶嵌后增加攻击及吸血'
  stats-list:
    - '攻击力: 10 - 20'
    - '吸血几率: +10%'
    - '吸血倍率: +20%'
  use-slot-name: '&f○'
  slot-name: '&4Æ'

配置键	类型	说明
<符文ID>	节点名	符文的唯一配置 ID，也是 /lzr give 使用的符文 ID。
name	字符串	符文物品名称。
enchant	布尔值	为 true 时给生成的符文物品添加 1 级 LUCK 附魔，用于显示附魔效果。
id	字符串	符文物品材质或物品 ID，例如 351:1。
lore	字符串列表	符文物品 Lore，可省略。
stats-list	字符串列表	镶嵌后提供给属性插件的属性文本，可省略。
use-slot-name	字符串	镶嵌前装备 Lore 中需要存在的空槽位文本。
slot-name	字符串	镶嵌后替换到装备 Lore 中的已占用槽位文本。

符文生成后会写入 rune_id NBT 字段。stats-list 只是属性文本列表，具体属性解析由所选属性插件负责。

ZF-Runes 配置转换

执行 /lzr load 后，插件会读取：

plugins/ZF-Runes/RunesItem

转换时使用以下旧字段：

ZF-Runes 字段	LyZFRunes 字段
ID	id
Name	name
Lore	lore
Enchant	enchant
StatsList	stats-list
UseSlotName	use-slot-name
SlotName	slot-name

转换结果保存到：

plugins/LyZFRunes/RunesItem/ZF-Runes

转换过程会输出到控制台。转换任务正在执行时，重复执行 /lzr load 不会同时启动第二个转换任务。

变量

项目中存在 PlaceholderAPI 扩展标识 lzr 的代码，但当前核心初始化流程中注册 PlaceholderAPI 扩展的代码处于注释状态，项目证据未确认可用的 LyZFRunes PlaceholderAPI 变量，因此不提供可用变量列表。

API 与数据标识

项目使用装备 NBT 保存符文信息：

NBT 字段	用途
rune_id	写入符文物品，用于识别符文配置。
rune_data	写入已镶嵌符文的装备，用于保存符文条目。
LyZFRunes	在部分版本的 NBT 实现中作为插件数据分组。

不同 Minecraft 版本使用对应的 NMS 实现读写 NBT。符文配置加载后会以符文 ID 建立内存数据，重载时会清空并重新加载所有 .yml 符文文件。

常见问题

为什么符文无法镶嵌？

检查以下内容：

• 点击的物品是否是由 LyZFRunes 注册并生成的符文物品。
• 符文物品是否包含有效的 rune_id。
• rune_id 是否存在于当前已加载的符文配置中。
• 装备 Lore 中是否存在由 Distinguish.Prefix、use-slot-name 和 Distinguish.Suffix 组成的完整空槽位文本。
• 符文配置和装备 Lore 中的颜色代码、前缀、后缀及字符是否完全一致。

为什么属性没有生效？

检查以下内容：

• attribute-plugin 是否填写了实际使用的属性插件名称。
• 对应属性插件是否已安装并成功启用。
• attribute-slot 是否配置了实际存放装备的槽位。
• 使用的扩展槽位插件是否已安装并成功启用。
• 符文配置中是否填写了 stats-list。
• 玩家是否在装备变化、关闭容器或切换相关槽位后等待属性刷新任务处理。

为什么 /lzr open 无法由控制台执行？

open 仅接受玩家执行，控制台不能打开玩家界面。

为什么 /lzr give 提示玩家不存在？

该命令只查找在线玩家。玩家必须在线，并且命令格式为：

/lzr give <玩家> <符文ID> <数量>

重载会加载哪些内容？

/lzr reload 会重新读取 config.yml，重新加载 RunesItem 目录下的符文文件，并重新创建属性刷新任务。