常见问题

插件的作用是什么？

LyGemSoulRing 会读取玩家指定装备槽位中的宝石 ID，并根据 soulring 目录下的魂环配置，为匹配到的宝石显示对应的 DragonCore 世界贴图。

魂环可以通过以下方式展开或收回：

• 执行 /lgsr show。
• 使用配置中的 show-soulring-key 按键。

玩家退出服务器时，插件会清理该玩家的魂环贴图。其他玩家加入服务器后，也会同步当前已经展开的魂环。

插件需要哪些前置？

必须安装并启用 DragonCore。插件使用 DragonCore 的按键、世界贴图和贴图发送接口；DragonCore 未启动时，魂环功能无法正常工作。

读取宝石时，还需要根据 gem-plugin 的配置安装对应的宝石插件：

gem-plugin	对应插件
LyGemReload	LyGemReload
YeeGem	YeeGem

plugin.yml 中声明了 PlaceholderAPI 和 LyGemReload 为软依赖。PlaceholderAPI 主要用于执行魂环展开或收回指令时解析变量。

支持哪些服务器版本？

插件声明的 Bukkit API 版本为 1.13，项目使用 Java 8 兼容配置。项目证据未进一步限定具体 Minecraft 版本，实际兼容性还取决于 DragonCore、宝石插件及其对应服务端版本。

/lgsr 有哪些指令？

指令	作用	使用限制
/lgsr	显示帮助内容	仅管理员身份执行时显示帮助
/lgsr show	展开或收回当前玩家的魂环	需要玩家执行
/lgsr reload	重载配置和魂环文件	需要管理员身份

插件没有在 plugin.yml 中声明独立的权限节点，代码通过 Bukkit 管理员身份判断 /lgsr 和 /lgsr reload 的使用权限。

输入 /lgsr show 没有魂环

按以下顺序检查：

1. 确认 gem-plugin 与服务器实际使用的宝石插件一致，只支持 LyGemReload 和 YeeGem。
2. 确认 plugin-slot 写的是玩家实际装备宝石的槽位。
3. 确认槽位中的物品存在，并且物品具有物品元数据。
4. 确认魂环配置文件中的顶层 ID 与宝石插件返回的宝石 ID 完全一致。
5. 确认对应魂环文件位于 plugins/LyGemSoulRing/soulring 目录及其子目录中，并且 YAML 格式正确。
6. 确认魂环配置中存在对应的贴图配置。

如果没有匹配到任何有效魂环，玩家会收到“你没有魂环!”提示。

plugin-slot 应该怎么填写？

plugin-slot 支持列表配置，可以同时读取多个槽位。常用格式如下：

槽位来源	格式
DragonCore	DragonCore#槽位名
LyInventory	LyInventory#背包文件#槽位
LyInventoryReload	LyInventoryReload#背包文件#槽位
YeeJewelry	YeeJewelry#背包文件#槽位
原版物品栏	Minecraft#槽位编号
主手	Origin#MainHand
副手	Origin#OffHand
头盔	Origin#Helmet
胸甲	Origin#ChestPlate
护腿	Origin#Legging
靴子	Origin#Boots

示例：

plugin-slot:
  - 'Origin#MainHand'
  - 'Origin#OffHand'

原版物品栏槽位使用 0 到 35 的编号。槽位来源必须与服务器实际使用的背包或装备插件一致，否则插件可能正常运行，但无法读取到物品。

修改 plugin-slot 后仍然读取不到宝石

plugin-slot 读取的是物品槽位，不是宝石 ID。插件会先从配置的槽位读取物品，再由 gem-plugin 对该物品解析宝石 ID。

请分别确认：

• 槽位格式正确，分隔符使用 #。
• 对应背包插件已安装并启用。
• gem-plugin 与物品中的宝石数据格式一致。
• 物品确实包含宝石，并且物品具有元数据。
• 魂环文件的顶层名称与宝石 ID 一致。

魂环配置文件放在哪里？

插件会递归读取 plugins/LyGemSoulRing/soulring 目录及其子目录中的所有 .yml 文件。

每个 YAML 顶层键都是一个宝石 ID，例如：

朱雀宝石:
  path: '魂环/h2.png'
  width: 3
  height: 3

顶层键必须与宝石插件解析出的宝石 ID 一致。修改或新增魂环文件后，执行 /lgsr reload 重新载入。

新增魂环后没有显示

确认以下内容：

• 文件扩展名是 .yml。
• 文件放在 soulring 目录或其子目录中。
• 顶层键与宝石 ID 一致。
• path 指向有效的贴图路径。
• width 和 height 使用了有效数值。
• animationList 中只填写支持的动画名称：ScaleAnimation、RotateAnimation、TranslateAnimation。
• 修改后执行了 /lgsr reload。

魂环文件载入失败时，插件会在控制台输出对应的载入失败信息。

按键没有反应

先确认 show-soulring-key 与玩家客户端实际触发的按键一致。插件会在重载时尝试向 DragonCore 注册该按键，注册失败时控制台会输出失败信息。

还可以执行 /lgsr show 测试其他功能：

• 指令可以展开魂环，说明主要功能正常，应继续检查按键注册或按键冲突。
• 指令也无法展开魂环，应继续检查前置、槽位、宝石 ID 和魂环文件。

配置示例：

show-soulring-key: 'Z'

玩家更换装备后，已经展开的魂环不会自动收回；需要再次使用按键或 /lgsr show 才会切换显示状态。

不想使用按键怎么办？

可以不使用按键，改为通过 /lgsr show 切换魂环。

配置中的按键值为空或填写无法注册的按键时，插件可能无法注册有效的 DragonCore 按键。若只使用指令，重点是确保管理员或玩家能够执行 /lgsr show。

玩家提示冷却中

show-soulring-cooldown 只限制展开魂环的操作，单位是毫秒。

例如：

show-soulring-cooldown: 10000

10000 毫秒等于 10 秒。冷却期间再次展开会发送 show-soulring-cooldown-message 配置的提示，并将 {time} 替换为剩余秒数，保留一位小数。

收回魂环不受冷却限制，玩家可以随时收回已经展开的魂环。

魂环数量太多

使用 max-soulring 限制单个玩家最多显示的魂环数量：

max-soulring: 10

插件会按照匹配到的魂环顺序显示，达到该数量后停止创建更多魂环贴图。

魂环大小逐层增加，如何调整？

soulring-scale 用于计算不同魂环之间的宽高递增值。每个魂环的基础大小来自魂环文件中的 width 和 height，后续魂环会在此基础上按序号增加尺寸。

soulring-scale: 4

如果魂环整体或层间差距过大，可以降低该值。需要调整基础大小时，修改对应魂环文件中的 width 和 height。

魂环展开太快或太慢

show-soulring-delay 控制逐个出现魂环时的间隔，单位为自定义 tick：

show-soulring-delay: 5

数值越大，魂环逐个出现的间隔越长。该配置只影响展开时的逐层显示节奏，不改变魂环贴图本身的动画时长。

动画太夸张或不明显

魂环文件通过 animationList 选择动画，支持以下三种动画：

• ScaleAnimation：缩放动画。
• RotateAnimation：旋转动画。
• TranslateAnimation：上下位移动画。

可以从全局配置中调整动画参数：

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

调整建议：

• 降低 TranslateAnimation.distance，减少上下移动幅度。
• 降低 ScaleAnimation.fromScale，减少初始缩放差距。
• 调整 ScaleAnimation.toScale，改变动画结束时的缩放比例。
• 增大 duration，让动画播放更慢。
• 减小 duration，让动画播放更快。
• 从魂环配置的 animationList 中移除不需要的动画。

修改动画配置后没有生效

动画参数在插件重载时读取。修改 RotateAnimation、TranslateAnimation 或 ScaleAnimation 后，执行：

/lgsr reload

如果魂环已经展开，建议先收回再重新展开，以便重新发送贴图和动画数据。

魂环位置或朝向不正确

位置和朝向属于单个魂环文件的配置。常用字段如下：

配置项	作用
translateX	X 轴坐标偏移
translateY	Y 轴坐标偏移
translateZ	Z 轴坐标偏移
translateEntityFront	相对实体前后位移
translateEntityRight	相对实体左右位移
rotateX	X 轴旋转角度
rotateY	Y 轴旋转角度
rotateZ	Z 轴旋转角度
followEntityDirection	是否跟随玩家视角方向旋转

例如：

translateX: 0
translateY: 2.2
translateZ: 0
translateEntityFront: 0
translateEntityRight: 0
rotateX: 90
rotateY: 0
rotateZ: 0
followEntityDirection: false

修改后执行 /lgsr reload，再重新展开魂环查看效果。

魂环穿过地形或被地形遮挡

使用魂环配置中的 through 控制是否穿透地形：

through: false

设置为 true 后允许魂环穿透地形，设置为 false 时不穿透地形。实际显示效果仍受客户端和 DragonCore 渲染行为影响。

魂环距离太近或太远

使用魂环配置中的 distance 调整显示距离：

distance: 64

该字段控制魂环的显示距离。调整后需要重载配置，并重新展开魂环。

魂环不够亮或透明度不合适

使用以下配置项调整显示效果：

配置项	作用
alpha	图片透明度
glow	是否发光

示例：

alpha: 1
glow: true

展开或收回时执行指令

插件支持分别配置展开和收回时执行的指令：

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

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

支持的执行方式如下：

前缀	执行方式
[console]	由控制台执行
[op]	临时以管理员身份执行
无前缀	由玩家执行

指令会经过 PlaceholderAPI 变量解析。未配置指令时，不会执行额外操作。

玩家更换装备后魂环没有自动变化

插件在展开时读取指定槽位中的物品和宝石，并创建当前魂环贴图。玩家更换装备后，已经展开的魂环不会自动收回，也不会在换装时自动重新读取。

需要更新显示内容时，先使用 /lgsr show 收回，再次使用 /lgsr show 重新读取当前装备中的宝石。

玩家加入后看不到其他玩家的魂环

插件会在玩家加入时尝试同步其他已展开玩家的魂环。请确认：

• DragonCore 已安装并启用。
• 当前玩家已正常加载客户端功能。
• 其他玩家确实处于魂环展开状态。
• 魂环配置和贴图路径有效。

如果是刚修改配置，先执行 /lgsr reload，再重新展开魂环测试。

重载后魂环文件没有变化

/lgsr reload 会重新读取主配置、动画配置和 soulring 目录中的所有 .yml 文件。

检查以下问题：

• 修改的是实际运行目录中的 plugins/LyGemSoulRing/config.yml 或 soulring 文件。
• YAML 缩进正确。
• 文件扩展名为 .yml。
• 顶层 ID 没有重复。
• 修改后由管理员执行了 /lgsr reload。

如果文件载入失败，请查看服务器控制台中的载入失败信息和异常堆栈。

为什么控制台提示 DragonCore 或 LyGemReload 未启动？

插件启动检查会分别检测 DragonCore 和 LyGemReload，并在控制台输出对应状态。

即使 gem-plugin 配置为 YeeGem，DragonCore 仍然是魂环显示所需的核心前置；宝石读取则应确保 YeeGem 已正确安装并启用。若使用 LyGemReload，则必须确保 LyGemReload 已启动。

修改 gem-plugin 后需要做什么？

将 gem-plugin 修改为 LyGemReload 或 YeeGem 后：

1. 安装并启用对应宝石插件。
2. 检查 plugin-slot 是否能读取该插件使用的物品槽位。
3. 检查魂环文件顶层 ID 是否匹配对应插件返回的宝石 ID。
4. 执行 /lgsr reload。
5. 收回并重新展开魂环。

示例：

gem-plugin: 'YeeGem'

插件会保存玩家的魂环状态吗？

项目代码只在运行期间保存在线玩家的魂环显示状态和当前魂环 ID，没有看到将该状态写入文件或数据库的实现。

玩家退出后，插件会移除其魂环贴图并清理运行时数据；重新加入后不会自动恢复上一次的展开状态。