配置说明

LyGemSoulRing 的配置由两部分组成：

文件位置	用途
`plugins/LyGemSoulRing/config.yml`	设置宝石来源、装备槽位、释放方式、冷却、指令动作、显示数量和动画参数
`plugins/LyGemSoulRing/soulring/*.yml`	按宝石 ID 定义魂环贴图、尺寸、位置、旋转和动画列表

执行 /lgsr reload 可以重新读取主配置、动画配置和 soulring 目录中的全部 YAML 文件。该指令仅限管理员使用。

主配置

宝石来源

yaml

gem-plugin: 'LyGemReload'

gem-plugin 决定插件从装备物品中读取哪一种宝石数据。

值	说明
`LyGemReload`	通过 LyGemReload API 读取物品中的全部宝石 ID
`YeeGem`	通过 YeeGem API 读取物品中的宝石 ID

配置值不区分大小写。使用对应来源前，服务器必须安装并正常加载相应宝石插件。

魂环配置的顶层名称必须与宝石插件返回的宝石 ID 完全对应，否则该宝石不会生成魂环。

装备槽位

yaml

plugin-slot:
  - 'Origin#MainHand'

plugin-slot 用于设置需要扫描的装备位置。插件会按列表顺序读取每个槽位，将其中的宝石 ID 汇总后匹配魂环配置。

当前版本同时兼容旧版单字符串写法，但建议始终使用 YAML 列表：

yaml

plugin-slot:
  - 'Origin#MainHand'
  - 'Origin#Helmet'
  - 'DragonCore#戒指槽位'

格式	说明
`DragonCore#槽位名`	读取 DragonCore 缓存槽位
`GermPlugin#槽位标识`	读取萌芽引擎槽位
`LyInventory#背包ID#类型`	读取旧版 LyInventory 指定槽位
`LyInventoryReload#背包ID#类型`	读取 LyInventoryReload 指定槽位
`YeeJewelry#背包ID#槽位ID`	读取 YeeJewelry 指定槽位
`Minecraft#槽位ID`	读取原版玩家背包中的指定槽位
`Origin#MainHand`	读取原版主手物品
`Origin#OffHand`	读取原版副手物品
`Origin#Helmet`	读取原版头盔
`Origin#ChestPlate`	读取原版胸甲
`Origin#Legging`	读取原版护腿
`Origin#Boots`	读取原版靴子

Minecraft#槽位ID 的默认配置注释标明槽位范围为 0-35。

槽位格式必须包含对应数量的 # 分段。格式错误、槽位不存在、物品为空或物品没有物品元数据时，该槽位不会提供宝石数据。

释放按键

yaml

show-soulring-key: 'Z'

show-soulring-key 设置 DragonCore 客户端按键。插件监听按键释放事件，玩家松开对应按键后，会在绽放和收回魂环之间切换。

配置重载时会重新向 DragonCore 注册该按键。按键名称无效时，控制台会提示注册失败，但玩家仍可使用 /lgsr show 切换魂环。

魂环展开后不会因为玩家更换装备自动收回。再次按键或执行 /lgsr show 才会收回。

释放冷却

yaml

show-soulring-cooldown: 10000
show-soulring-cooldown-message: '&c魂环绽放冷却中，还需{time}秒!'

配置项	类型	默认值	说明
`show-soulring-cooldown`	整数	`10000`	再次绽放魂环需要等待的时间，单位为毫秒
`show-soulring-cooldown-message`	字符串	`&c魂环绽放冷却中，还需{time}秒!`	冷却未结束时发送给玩家的消息

冷却只限制绽放魂环，不限制收回魂环。冷却从成功开始绽放时计算。

占位符	说明
`{time}`	剩余冷却秒数，保留一位小数

释放与收回指令

yaml

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

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

配置项	触发时间
`show-soulring-command`	玩家成功读取到有效魂环并开始绽放时
`hide-soulring-command`	玩家主动收回已经展开的魂环时

每一项指令都会先经过 PlaceholderAPI 变量解析，再根据前缀决定执行身份。

写法	执行方式
`[console]指令`	由控制台执行
`[op]指令`	临时给予玩家管理员身份，以玩家身份执行，完成后恢复原状态
`指令`	直接以玩家身份执行

指令内容不需要填写开头的 /。玩家名可使用 PlaceholderAPI 提供的 %player_name% 等变量；项目代码没有为动作指令提供 {player} 占位符。

如果没有安装 PlaceholderAPI，动作指令的变量解析功能无法正常使用。plugin.yml 将 PlaceholderAPI 声明为软依赖。

当扫描结果中没有任何已配置的魂环时，插件会取消展开状态并向玩家发送“你没有魂环!”，此时不会执行 show-soulring-command。

数量、尺寸与显示间隔

yaml

max-soulring: 10
soulring-scale: 4
show-soulring-delay: 5

配置项	类型	默认读取值	说明
`max-soulring`	整数	`10`	单个玩家最多显示的魂环数量
`soulring-scale`	小数	`0.35`	后续每层魂环相对上一层增加的宽度和高度
`show-soulring-delay`	整数	`0`	定时展示魂环时两次处理之间的间隔，单位为服务器 Tick

soulring-scale 不是整体缩放倍率。插件会根据魂环序号计算尺寸：

text

最终宽度 = 配置宽度 + 魂环序号 × soulring-scale
最终高度 = 配置高度 + 魂环序号 × soulring-scale

第一个魂环序号为 0，因此保持配置文件中的基础宽高；后续魂环按顺序逐层增加。

show-soulring-delay 会直接作为 Bukkit 定时任务的周期参数使用。通常 20 Tick 约为 1 秒，实际速度会受到服务器运行状态影响。

当前实现会先向在线玩家发送匹配到的魂环贴图，同时再启动按 show-soulring-delay 处理的定时任务。因此该配置用于控制后续定时发送间隔，不代表首次显示前的等待时间。

动画配置

三组动画参数都位于 config.yml。魂环文件通过 animationList 选择需要应用的动画。

动画参数会在插件启动或执行 /lgsr reload 时重新创建并载入。

旋转动画

yaml

RotateAnimation:
  delay: 1000
  angle: 360.0
  duration: 3000
  cycleCount: 1
  fixed: true
  resetTime: 1

配置项	类型	默认读取值	说明
`RotateAnimation.delay`	整数	`0`	动画开始延迟
`RotateAnimation.angle`	小数	`360`	单次旋转角度
`RotateAnimation.duration`	整数	`6000`	单次旋转持续时间
`RotateAnimation.cycleCount`	整数	`1`	动画循环次数
`RotateAnimation.fixed`	布尔值	`true`	是否使用固定动画状态
`RotateAnimation.resetTime`	整数	`1`	动画重置时间参数

旋转方向由插件固定为 DragonCore 世界贴图动画的 z 方向，配置文件中没有单独的方向选项。

位移动画

yaml

TranslateAnimation:
  delay: 0
  distance: 2
  duration: 1000
  cycleCount: 1
  fixed: true

配置项	类型	默认读取值	说明
`TranslateAnimation.delay`	整数	`0`	动画开始延迟
`TranslateAnimation.distance`	小数	`1.1`	位移动画距离
`TranslateAnimation.duration`	整数	`3000`	单次位移动画持续时间
`TranslateAnimation.cycleCount`	整数	`1`	动画循环次数
`TranslateAnimation.fixed`	布尔值	`true`	是否使用固定动画状态

位移动画方向由插件固定为 DragonCore 世界贴图动画的 z 方向。

缩放动画

yaml

ScaleAnimation:
  delay: 0
  cycleCount: 1
  fixed: false
  fromScale: 10.0
  toScale: 1.0
  duration: 1000

配置项	类型	默认读取值	说明
`ScaleAnimation.delay`	整数	`0`	动画开始延迟
`ScaleAnimation.cycleCount`	整数	`1`	动画循环次数
`ScaleAnimation.fixed`	布尔值	`false`	是否使用固定动画状态
`ScaleAnimation.fromScale`	小数	`3.0`	动画开始时的缩放值
`ScaleAnimation.toScale`	小数	`1.0`	动画结束时的缩放值
`ScaleAnimation.duration`	整数	`3000`	单次缩放动画持续时间

表格中的“默认读取值”是配置项缺失时程序采用的回退值。插件自带 config.yml 中的实际初始值以对应 YAML 示例为准。

魂环文件

插件会递归读取以下目录及其子目录中的全部 .yml 文件：

text

plugins/LyGemSoulRing/soulring/

首次载入时，插件会释放 soulring/示例魂环.yml。目录中每个 YAML 顶层键都是一个宝石 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'

宝石 ID

yaml

朱雀宝石:

顶层键用于匹配宝石插件返回的宝石 ID。只有成功匹配的宝石才会被加入玩家的魂环列表。

如果多个扫描槽位返回相同的宝石 ID，当前代码不会主动去重，该魂环可能按扫描结果重复加入显示列表。

贴图与尺寸

配置项	示例	说明
`path`	`'魂环/h2.png'`	DragonCore 世界贴图使用的资源路径
`width`	`3`	魂环基础宽度
`height`	`3`	魂环基础高度

width 和 height 会作为第一层魂环的基础尺寸，后续层数再叠加 soulring-scale。

坐标偏移

配置项	示例	说明
`translateX`	`0`	X 轴显示偏移
`translateY`	`2.2`	Y 轴显示偏移
`translateZ`	`0`	Z 轴显示偏移
`translateEntityFront`	`0`	相对实体前后方向的位移
`translateEntityRight`	`0`	相对实体左右方向的位移

魂环贴图会绑定到释放魂环的玩家实体，不需要在配置中填写实体 UUID。

旋转角度

配置项	示例	说明
`rotateX`	`90`	X 轴旋转角度
`rotateY`	`0`	Y 轴旋转角度
`rotateZ`	`0`	Z 轴旋转角度

这些参数设置贴图的基础朝向，与 RotateAnimation 的动态旋转效果相互独立。

渲染参数

配置项	示例	说明
`through`	`false`	是否允许贴图穿透地形显示
`distance`	`64`	贴图显示距离
`alpha`	`1`	贴图透明度
`glow`	`true`	是否启用发光效果
`followEntityDirection`	`false`	是否跟随玩家实体方向旋转

这些键会映射到 DragonCore WorldTexture 中的同名字段。

动画列表

yaml

animationList:
  - 'ScaleAnimation'
  - 'RotateAnimation'
  - 'TranslateAnimation'

动画名称	对应配置段
`ScaleAnimation`	`config.yml` 中的 `ScaleAnimation`
`RotateAnimation`	`config.yml` 中的 `RotateAnimation`
`TranslateAnimation`	`config.yml` 中的 `TranslateAnimation`

动画名称匹配不区分大小写。列表顺序会作为动画加入世界贴图的顺序。

当前代码只识别以上三种动画名称。无法识别的名称会被忽略。

其他世界贴图字段

除 animationList 外，魂环节点中的键会尝试按名称映射到 DragonCore WorldTexture 的同名字段。插件支持将 YAML 数值、布尔值、字符串和 UUID 文本转换为对应的 Java 字段类型。

如果键名在当前 DragonCore WorldTexture 中不存在，或配置值无法转换为目标字段类型，该项会被忽略。因此新增字段时应使用当前服务端 DragonCore API 实际提供的字段名称和数据类型。

完整配置示例

yaml

# 使用的宝石插件：LyGemReload 或 YeeGem
gem-plugin: 'LyGemReload'

# 扫描的装备槽位
plugin-slot:
  - 'Origin#MainHand'
  - 'Origin#Helmet'

# DragonCore 释放按键
show-soulring-key: 'Z'

# 绽放冷却，单位为毫秒
show-soulring-cooldown: 10000
show-soulring-cooldown-message: '&c魂环绽放冷却中，还需{time}秒!'

# 绽放时执行的指令
show-soulring-command:
  - '[console]tell %player_name% 你释放了魂环'

# 收回时执行的指令
hide-soulring-command:
  - '[console]tell %player_name% 你收回了魂环'

# 最多显示的魂环数量
max-soulring: 10

# 后续魂环递增的宽度和高度
soulring-scale: 4

# 定时展示间隔，单位为服务器 Tick
show-soulring-delay: 5

RotateAnimation:
  delay: 1000
  angle: 360.0
  duration: 3000
  cycleCount: 1
  fixed: true
  resetTime: 1

TranslateAnimation:
  delay: 0
  distance: 2
  duration: 1000
  cycleCount: 1
  fixed: true

ScaleAnimation:
  delay: 0
  cycleCount: 1
  fixed: false
  fromScale: 10.0
  toScale: 1.0
  duration: 1000

修改配置后执行：

text

/lgsr reload

重载会重新读取 config.yml、重新创建三种动画对象，并重新载入 soulring 目录中的魂环定义。已经展开的魂环不会在重载时被主动收回；玩家再次切换魂环后会使用新配置重新生成贴图。

配置说明 ​

主配置 ​

宝石来源 ​

装备槽位 ​

释放按键 ​

释放冷却 ​

释放与收回指令 ​

数量、尺寸与显示间隔 ​

动画配置 ​

旋转动画 ​

位移动画 ​

缩放动画 ​

魂环文件 ​

宝石 ID ​

贴图与尺寸 ​

坐标偏移 ​

旋转角度 ​

渲染参数 ​

动画列表 ​

其他世界贴图字段 ​

完整配置示例 ​

配置说明

主配置

宝石来源

装备槽位

释放按键

释放冷却

释放与收回指令

数量、尺寸与显示间隔

动画配置

旋转动画

位移动画

缩放动画

魂环文件

宝石 ID

贴图与尺寸

坐标偏移

旋转角度

渲染参数

动画列表

其他世界贴图字段

完整配置示例