宝石魂环 LyGemSoulRing

LyGemSoulRing 用于读取玩家装备中的宝石，并通过 DragonCore 世界贴图将匹配到的宝石显示为环绕玩家的魂环。

玩家可以使用指令或 DragonCore 按键绽放、收回魂环。插件支持扫描多个装备槽位、限制显示数量、逐圈显示、递增魂环尺寸，并为魂环配置旋转、位移和缩放动画。

插件信息

项目	内容
插件名	`LyGemSoulRing`
版本	`1.0.3`
作者	`离渊`
主命令	`/lgsr`
Bukkit API 版本	`1.13`
构建使用的服务端 API	Paper `1.16.5`
Java 目标版本	Java 8
魂环显示方式	DragonCore 世界贴图
宝石来源	`LyGemReload`、`YeeGem`
声明的软依赖	`PlaceholderAPI`、`LyGemReload`

版本说明

项目文件能够确认插件声明 api-version: 1.13，并使用 Paper 1.16.5 API 构建，但没有提供完整的服务端兼容版本范围。

依赖与兼容插件

必需组件

组件	用途	说明
DragonCore	注册释放按键并向客户端发送魂环世界贴图	DragonCore 未启动时，魂环监听与显示功能不会注册
宝石插件	从装备中读取宝石 ID	`gem-plugin` 当前支持 `LyGemReload` 或 `YeeGem`

可选组件

组件	用途
PlaceholderAPI	解析绽放、收回魂环时执行的指令变量
LyGemReload	默认宝石数据来源，也可以提供装备中的宝石 ID
YeeGem	可作为 `LyGemReload` 之外的宝石数据来源
DragonCore	提供 `DragonCore#槽位名` 类型的装备槽位
GermPlugin	提供 `GermPlugin#槽位名` 类型的装备槽位
LyInventory	提供旧版离渊背包槽位
LyInventoryReload	提供离渊背包重置版槽位
YeeJewelry	提供清守饰品背包槽位

插件会直接调用所选宝石插件和对应槽位插件的接口。使用某种宝石来源或扩展槽位前，需要安装对应插件。

玩法说明

插件将宝石 ID 与 plugins/LyGemSoulRing/soulring 目录内的魂环配置节点名称进行匹配。

玩家绽放魂环时，插件会依次完成以下处理：

按照 plugin-slot 的顺序读取一个或多个装备槽位。
使用 gem-plugin 指定的宝石插件提取装备中的宝石 ID。
只保留已经在魂环配置文件中定义的宝石 ID。
根据 max-soulring 限制显示数量。
将魂环绑定到玩家实体，并发送给全部在线玩家。
按照 show-soulring-delay 逐圈显示魂环。
根据魂环序号和 soulring-scale 递增贴图宽度与高度。

如果装备中没有能够匹配魂环配置的宝石，插件会取消显示状态并提示“你没有魂环!”。

核心功能

功能	说明
多槽位扫描	`plugin-slot` 支持列表，可同时读取多个装备槽位
旧配置兼容	仍兼容将 `plugin-slot` 写成单个字符串的旧配置
双宝石来源	支持从 `LyGemReload` 或 `YeeGem` 读取宝石 ID
自定义魂环	每个宝石 ID 可以配置独立贴图、尺寸、位置、角度和显示参数
魂环数量限制	使用 `max-soulring` 限制单次最多显示的魂环数量
尺寸递增	后续魂环会在配置宽高基础上按 `soulring-scale` 逐层增大
延迟展开	使用 `show-soulring-delay` 控制每一圈魂环出现的间隔
按键切换	监听 DragonCore 按键释放事件，切换魂环显示状态
冷却限制	绽放魂环受冷却限制，收回魂环不受冷却限制
指令动作	绽放、收回时可以执行玩家、临时 OP 或控制台指令
PAPI 变量	动作指令会先经过 PlaceholderAPI 变量解析
动画控制	支持旋转、上下位移和缩放三种 DragonCore 贴图动画
全服可见	魂环贴图会发送给当前全部在线玩家，而不是只发送给魂环拥有者
加入同步	新玩家加入时，会收到其他在线玩家当前已经展开的魂环
退出清理	玩家退出时，插件会从在线玩家客户端移除该玩家的魂环贴图
旧贴图清理	收回或退出时会同时清理当前贴图编号和旧版本贴图编号
热重载	重载主配置、动画配置、魂环文件并重新注册按键

支持的装备槽位

plugin-slot 中每一项使用 类型#参数 格式。需要多个参数的槽位继续使用 # 分隔。

槽位类型	写法	说明
DragonCore	`DragonCore#槽位名`	读取 DragonCore 缓存槽位
GermPlugin	`GermPlugin#槽位名`	读取萌芽槽位
LyInventory	`LyInventory#背包ID#槽位名`	读取旧版离渊背包槽位
LyInventoryReload	`LyInventoryReload#背包ID#槽位名`	读取离渊背包重置版槽位
YeeJewelry	`YeeJewelry#背包ID#槽位ID`	读取清守饰品背包槽位
Minecraft	`Minecraft#槽位ID`	读取玩家背包中的原版槽位，代码按数字槽位读取
原版主手	`Origin#MainHand`	读取主手物品
原版副手	`Origin#OffHand`	读取副手物品
原版头盔	`Origin#Helmet`	读取头盔
原版胸甲	`Origin#ChestPlate`	读取胸甲
原版护腿	`Origin#Legging`	读取护腿
原版靴子	`Origin#Boots`	读取靴子

默认配置只扫描主手：

yaml

plugin-slot:
  - 'Origin#MainHand'

魂环文件

魂环配置文件存放在：

text

plugins/LyGemSoulRing/soulring

插件重载时会递归读取该目录及子目录中的全部 .yml 文件。每个顶层节点都是一个宝石 ID，节点名称必须与宝石插件读取到的宝石 ID 一致。

yaml

朱雀宝石:
  path: '魂环/h2.png'
  width: 3
  height: 3
  translateX: 0
  translateY: 2.2
  translateZ: 0
  translateEntityFront: 0
  translateEntityRight: 0
  rotateX: 90
  rotateY: 0
  rotateZ: 0
  through: false
  distance: 64
  alpha: 1
  glow: true
  followEntityDirection: false
  animationList:
    - 'ScaleAnimation'
    - 'RotateAnimation'
    - 'TranslateAnimation'

示例文件能够确认以下魂环字段：

配置项	说明
`path`	魂环贴图路径
`width`	基础宽度
`height`	基础高度
`translateX`	X 轴坐标偏移
`translateY`	Y 轴坐标偏移
`translateZ`	Z 轴坐标偏移
`translateEntityFront`	相对实体前后位移
`translateEntityRight`	相对实体左右位移
`rotateX`	X 轴旋转角度
`rotateY`	Y 轴旋转角度
`rotateZ`	Z 轴旋转角度
`through`	是否穿透地形显示
`distance`	显示距离
`alpha`	图片透明度
`glow`	是否发光
`followEntityDirection`	是否跟随玩家视角方向旋转
`animationList`	应用到该魂环的动画名称列表

除 animationList 外，魂环节点中的配置键会尝试映射到 DragonCore WorldTexture 的同名字段。不存在的字段会被忽略；能够转换为目标基础类型的值会写入世界贴图。

动画

每个魂环可以通过 animationList 选择动画。当前代码只识别以下名称：

动画名称	效果	主要配置
`RotateAnimation`	旋转动画	延迟、角度、持续时间、循环次数、固定状态、重置时间
`TranslateAnimation`	位移动画	延迟、距离、持续时间、循环次数、固定状态
`ScaleAnimation`	缩放动画	延迟、循环次数、固定状态、起始缩放、结束缩放、持续时间

旋转动画和位移动画的方向在代码中固定为 z。

指令

指令	执行者	权限要求	说明
`/lgsr`	控制台或玩家	OP	查看插件指令提示
`/lgsr reload`	控制台或玩家	OP	重载主配置、动画、魂环文件和按键注册
`/lgsr show`	玩家	无独立权限节点	绽放或收回自己的魂环

项目没有声明独立权限节点。reload 和无参数帮助通过是否为 OP 判断，show 只要求执行者为玩家。

Tab 补全只会向 OP 提供 reload，不会补全 show。

绽放与收回规则

规则	说明
状态切换	`/lgsr show` 和配置按键调用同一套显示切换逻辑
装备读取时机	只在绽放魂环时重新读取配置槽位中的装备
装备变化	魂环展开后更换装备不会自动收回或刷新，需要再次切换状态
冷却起点	成功进入绽放流程时记录时间
冷却范围	冷却只限制绽放，不限制收回
无有效魂环	取消显示状态并向玩家发送“你没有魂环!”
显示范围	贴图发送给全部在线玩家，具体可见距离由魂环的 `distance` 控制
最大显示数	实际创建和同步的魂环不会超过 `max-soulring`
清理范围	收回或退出时固定尝试清理编号 `0` 至 `19` 的贴图

动作指令

show-soulring-command 和 hide-soulring-command 支持以下执行方式：

写法	执行方式
普通指令	由玩家身份执行
`[op]指令`	临时给予玩家 OP 后执行，完成后恢复原状态
`[console]指令`	由控制台执行

动作指令会先调用 PlaceholderAPI 解析玩家变量。项目示例使用 %player_name%，但可用变量范围由服务器安装的 PlaceholderAPI 扩展决定。

yaml

show-soulring-command:
  - '[console]tell %player_name% 你释放了魂环'

hide-soulring-command:
  - '[console]tell %player_name% 你收回了魂环'

重要配置

配置项	默认配置值	说明
`gem-plugin`	`LyGemReload`	选择宝石读取插件，可填写 `LyGemReload` 或 `YeeGem`
`plugin-slot`	`Origin#MainHand`	需要扫描的装备槽位列表
`show-soulring-key`	`Z`	DragonCore 魂环切换按键
`show-soulring-cooldown`	`10000`	绽放冷却，单位为毫秒
`show-soulring-cooldown-message`	`&c魂环绽放冷却中，还需{time}秒!`	冷却提示，`{time}` 会替换为剩余秒数
`show-soulring-command`	空列表	绽放魂环时执行的指令
`hide-soulring-command`	空列表	收回魂环时执行的指令
`max-soulring`	`10`	单次最多显示的魂环数量
`soulring-scale`	`4`	后续每层魂环在基础宽高上增加的数值
`show-soulring-delay`	`5`	每圈魂环出现的间隔，作为 Bukkit Tick 使用

show-soulring-cooldown-message 会直接发送给玩家。代码没有对该消息执行颜色符号转换，因此项目文件只能确认 {time} 替换行为。

数据与 API

插件的魂环显示状态保存在内存中，包括玩家当前是否展开魂环、已显示的魂环 ID 和上次绽放时间。玩家退出后对应数据会被移除。

项目中存在空的 APIServer 类，但没有能够确认的公开方法、事件、服务注册或开发者 API，因此当前版本没有可记录的公共 API。

项目代码没有使用 MySQL 存储魂环数据，也没有提供数据库配置项。

页面索引

页面	内容
配置说明	主配置、槽位格式、魂环文件和动画参数
显示规则	宝石读取、显示顺序、同步、冷却与清理机制
常见问题	依赖、槽位、宝石匹配、按键和显示问题排查
更新日志	版本与文档变更记录

宝石魂环 LyGemSoulRing ​

插件信息 ​

依赖与兼容插件 ​

必需组件 ​

可选组件 ​

玩法说明 ​

核心功能 ​

支持的装备槽位 ​

魂环文件 ​

动画 ​

指令 ​

绽放与收回规则 ​

动作指令 ​

重要配置 ​

数据与 API ​

页面索引 ​

宝石魂环 LyGemSoulRing

插件信息

依赖与兼容插件

必需组件

可选组件

玩法说明

核心功能

支持的装备槽位

魂环文件

动画

指令

绽放与收回规则

动作指令

重要配置

数据与 API

页面索引