常见问题

插件支持哪些 Minecraft 版本？

项目提供 v1_7_R4 和 v1_12_R1 两套 NMS 适配实现，启动时会根据服务器的 CraftBukkit 包名自动选择对应实现。

如果服务器版本不属于这两个适配版本，插件会抛出不支持当前 CraftBukkit 版本的错误，坐骑实体无法正常创建。

插件需要哪些前置？

插件在 plugin.yml 中声明了以下软依赖：

前置插件	用途
PlaceholderAPI	读取移速属性变量，以及解析事件指令中的变量
MythicMobs	释放坐骑事件配置中的 MythicMobs 技能
Vault	项目声明的软依赖，当前提供的证据中未显示具体调用位置
GermPlugin	注册召唤按键、读取萌芽槽位、监听按键和播放萌芽动作
DragonCore	注册召唤按键、读取龙核槽位、监听按键和播放龙核动作
ProtocolLib	读取骑乘期间的载具控制数据，处理移动、跳跃和下马

GermPlugin 和 DragonCore 用于不同的按键、槽位和动作适配。插件注册事件时优先使用已启用的 GermPlugin，否则使用已启用的 DragonCore。

按键无法上下坐骑

先检查 spawn-ride-key 的格式：

• GermPlugin 使用萌芽按键枚举名称，例如 KEY_T。
• DragonCore 使用按键名，例如 T。

还要检查以下内容：

1. 已安装并启用了对应的 GermPlugin 或 DragonCore。
2. ride-slot 使用了对应槽位插件支持的格式。
3. 槽位中的物品存在显示名称。
4. 物品显示名称包含坐骑文件中的 match-name。
5. 玩家当前没有处于骑乘状态；按键在未骑乘时尝试上坐骑，已骑乘时执行下马。
6. 玩家站在地面上。插件不会在玩家不落地时创建坐骑。
7. 当前世界不在 anti-ride-world 的禁止匹配范围内。

ride-slot 支持哪些格式？

插件会根据 ride-slot 第一个 # 前的类型读取物品显示名称，当前代码中支持以下格式：

类型	格式	说明
DragonCore	DragonCore#槽位名	读取龙核槽位
GermPlugin	GermPlugin#槽位名	读取萌芽槽位
APInventory	APInventory#分页id#槽位id	槽位编号为 0 至 53
LyInventory	LyInventory#背包id#类型	读取离渊背包槽位
LyInventoryReload	LyInventoryReload#背包id#类型	读取另一套离渊背包接口
Minecraft	Minecraft#槽位id	读取原版背包槽位
Origin	Origin#Mainhand	读取主手
Origin	Origin#Offhand	读取副手
Origin	Origin#Helmet	读取头盔栏
Origin	Origin#ChestPlate	读取胸甲栏
Origin	Origin#Legging	读取护腿栏
Origin	Origin#Boots	读取靴子栏

物品必须拥有显示名称。插件只匹配物品显示名称，不匹配物品材质或物品 ID。

物品有名称但仍然无法识别坐骑

坐骑文件通过 match-name 匹配槽位物品的显示名称，判断条件是显示名称包含配置文本，而不是完全相等。

检查以下内容：

• 颜色代码是否一致。配置中的 & 颜色代码会转换为 Minecraft 颜色代码。
• match-name 是否写在正确的坐骑 YAML 文件中。
• 坐骑文件是否位于插件目录的 ride 文件夹或其子目录中。
• 坐骑配置中的 id 是否重复。重载时后加载的同名坐骑可能覆盖前面的数据。
• 修改坐骑文件后是否执行了 /lyzq reload。

当前世界不能骑乘

检查 anti-ride-world。插件会判断当前世界名称是否包含列表中的文本，只要包含任意一项就会禁止骑乘。

例如：

anti-ride-world:
  - 'antirideworld'

这不是完整匹配。配置为 world 时，名称包含 world 的世界都会被禁止骑乘。

玩家不在地面时无法上坐骑

创建坐骑前会检查玩家是否在地面上。玩家处于跳跃、下落或其他非落地状态时，插件会直接跳过创建坐骑。

这是上坐骑时的限制，不影响已经开始的飞行坐骑移动。

飞行坐骑高度受限

检查 world-fly-limit。配置键下的世界名需要完整匹配当前世界名称，值为允许的最高 Y 坐标。

world-fly-limit:
  world: 150

当飞行坐骑达到配置的高度后，向上的移动力度会被设置为 0。该限制只影响向上飞行，不会直接结束骑乘。

飞行坐骑无法上升或下降

飞行方向由玩家视角和跳跃输入共同决定：

• 按住跳跃键时，飞行坐骑持续上升。
• 视角向上或向下时，会根据 up-power 或 down-power 计算垂直移动力度。
• 视角接近水平时，飞行坐骑保持水平移动。
• world-fly-limit 会限制向上移动。

检查坐骑文件中的以下配置：

配置项	作用
fly	是否启用飞行模式
up-power	不同俯仰角下的上升力度
down-power	不同俯仰角下的下降力度
jump-power	基础跳跃或飞行上升力度
jump-tick	跳跃或持续上升的持续时间

up-power 和 down-power 的角度键必须按照示例使用负数角度配置，插件读取时会转换为内部角度值。

陆行坐骑无法跨越方块

陆行坐骑会根据 rise-power 检测前方障碍物，并尝试自动攀升。该配置只对 fly: false 的坐骑生效。

rise-power: 2

数值过低时无法跨越较高障碍；数值过高时会提高可攀爬高度。坐骑仍会受到前方方块检测结果影响。

跳跃次数不符合预期

检查以下配置：

配置项	作用
jump-power	每次跳跃使用的基础力度
jump-tick	跳跃持续时间，单位为 tick，最低建议使用 1
jump-count	陆行模式下允许的跳跃段数

陆行坐骑只有在存在方向输入、当前跳跃状态结束，并且累计跳跃次数小于 jump-count 时，才会增加跳跃次数。

飞行坐骑按住跳跃键时会持续刷新上升计时，不按陆行坐骑的多段跳逻辑处理。

骑乘速度与配置的 move-speed 不一致

坐骑最终速度可能会经过属性加成和公式计算。检查主配置中的：

配置项	作用
attribute-plugin	选择属性插件
move-speed-attribute	读取玩家移速属性的变量表达式
move-speed-attribute-max	限制参与计算的属性值上限
move-speed-formula	根据基础速度和属性值计算最终速度

公式支持以下两个变量：

变量	含义
{speed_base}	坐骑文件中的 move-speed
{speed_attribute}	读取并限制后的玩家属性值

示例默认公式为：

move-speed-formula: '{speed_base}*(1+({speed_attribute}*0.01))'

如果 move-speed-attribute 为空，玩家属性值按 0 参与计算。属性插件名称支持 AttributePlus2、AttributePlus3、SX-Attribute2 和 SX-Attribute3。

骑乘后立刻下马

检查以下配置：

配置项	触发情况
ride-or-player-damaged-end-riding	玩家或坐骑受到伤害时结束骑乘。若坐骑无视伤害，则玩家受伤仍可能结束骑乘
player-attack-end-riding	玩家造成伤害时结束骑乘

此外，以下情况也会结束骑乘：

• 玩家主动下马。
• 玩家传送。
• 玩家切换世界。
• 玩家退出服务器。
• 玩家打开背包时会暂停移动输入，但不会直接结束骑乘。
• 插件执行重载或关闭流程时，会安全移除当前坐骑。

坐骑无法受到伤害

检查坐骑文件中的 ride-can-damaged：

ride-can-damaged: false

当值为 false 时，坐骑受到的伤害会被取消。该设置不会阻止玩家受到伤害，因此如果 ride-or-player-damaged-end-riding 为 true，玩家受伤仍可能结束骑乘。

骑乘时摔落伤害没有生效

玩家正在骑乘时，插件会取消玩家的摔落伤害。该行为与坐骑文件中的 ride-can-damaged 无关。

骑乘属性没有生效

检查坐骑文件中的 riding-attribute 和主配置中的 attribute-plugin：

riding-attribute:
  - '物理伤害10'

只有配置了受支持的属性插件名称时，骑乘属性才会调用对应属性插件接口：

• AttributePlus2
• AttributePlus3
• SX-Attribute2
• SX-Attribute3

属性会在开始骑乘后添加，在结束骑乘、主动下马、传送、切换世界、退出服务器或插件关闭时移除。修改 attribute-plugin 后需要重启插件或服务器，配置注释明确要求切换为 SX 属性插件时重启。

骑乘动画不播放

骑乘循环动作需要启用 GermPlugin 或 DragonCore。动作播放会根据已启用的前置自动选择对应实现。

检查坐骑文件中的 riding-animation：

riding-animation:
  - '动作1:1500'
  - 'delay:2000'
  - '动作2:1200'

支持以下写法：

写法	作用
动作名	播放动作，未指定时长时使用默认循环间隔
动作名:毫秒	播放动作并等待指定毫秒数后播放下一条
delay:毫秒	暂停指定毫秒数，不播放动作

技能触发时，骑乘循环动作会暂停 1000 毫秒，并在恢复后从动作列表开头重新播放。

事件技能不触发

检查事件配置是否位于坐骑文件的 event 节点下，并确认 trigger-type 拼写正确。

当前支持的触发类型如下：

trigger-type	触发时机
start-riding	开始骑乘
end-riding	结束骑乘
fly-up	飞行上升
fly-down	飞行下降
fly-move	飞行直线移动
rising	陆行坐骑攀爬时
forward	按住前进移动时
cease	松开前进键并悬停或停止移动时
damaged	坐骑受到伤害时
second	骑乘期间每秒检查
right	玩家骑乘时点击右键
left	玩家骑乘时点击左键

事件触发还会受到以下条件影响：

• chance 是 0 到 1 的随机成功概率，默认值为 1。
• cooldown 单位是毫秒，默认值为 1000。
• 技能进入冷却后，即使本次随机判定失败，也会等待冷却结束。
• 坐骑结束时，本次骑乘实例中的技能冷却会随实例一起清除。
• second 可以通过 cooldown 控制检查间隔。

MythicMobs 技能不释放，但消息或指令正常执行

确认 mythic-skill 填写的是 MythicMobs 中已存在的技能 ID，并且 MythicMobs 已启用。

当 mythic-skill 为空时，插件不会释放 MythicMobs 技能，但成功或失败消息、成功或失败指令以及动作仍可继续执行。

如果技能 ID 不存在，插件会向玩家发送技能不存在的提示，之后不会释放该技能。

事件成功率如何配置？

chance 使用 0 到 1 的小数：

chance: 0.5

插件使用随机数与该值比较，随机判定成功时执行成功消息、成功指令、MythicMobs 技能和动作；判定失败时执行失败消息和失败指令。

事件指令没有按预期执行

事件指令支持以下前缀：

前缀	执行身份
[console]	控制台
[op]	临时给予玩家 OP 后，以玩家身份执行，执行结束后恢复原状态
[player]	以玩家身份执行
无前缀	默认以玩家身份执行

指令会先处理 PlaceholderAPI 变量，再处理数值表达式，最后将 & 颜色代码转换为 Minecraft 颜色代码。

支持的数值表达式格式包括：

• eval:{表达式}：计算表达式。
• ceil:{表达式}：向上取整。
• floor:{表达式}：向下取整。
• ~格式：指定数值格式。

例如，表达式必须放在成对的大括号中。指令执行还会受到具体指令插件自身权限和参数校验影响。

重载后骑乘状态消失

这是插件的既定行为。执行 /lyzq reload 时会：

1. 强制结束当前所有玩家的骑乘。
2. 重新读取主配置。
3. 重新保存并读取 ride/示例坐骑.yml。
4. 递归读取 ride 文件夹及子目录中的 YAML 坐骑文件。
5. 重新注册召唤按键。
6. 重新读取 ride-slot。
7. 重新加载 ProtocolLib 的移动数据监听。

因此修改坐骑配置后需要重新上坐骑，不能保持原来的骑乘实例。

/lyzq reload 无法执行

插件命令注册名为 lyzq。命令处理器只对 OP 执行管理操作：

命令	作用	使用条件
/lyzq	显示管理命令帮助	OP
/lyzq reload	重载插件配置和坐骑文件	OP
/lyzq riding <玩家> <坐骑id>	强制指定玩家骑乘指定坐骑，无视骑乘冷却	OP
/lyzq try <玩家>	模拟指定玩家按键上下坐骑，使用其配置槽位中的坐骑	OP

项目证据中未声明独立权限节点，实际权限判断使用的是发送者是否为 OP。

强制骑乘命令仍然失败

使用 /lyzq riding <玩家> <坐骑id> 时检查：

• 玩家在线。
• 坐骑 id 已被插件读取。
• 坐骑 type 为当前支持的 pig 或 dragon。
• 玩家当前不在骑乘状态。
• 当前世界没有被 anti-ride-world 禁止。
• 玩家处于地面状态。
• 当前服务器版本属于已提供的 NMS 适配版本。

该命令只会跳过骑乘冷却，不会跳过世界限制、玩家状态、坐骑 ID 或坐骑类型检查。

/lyzq try <玩家> 与普通按键有什么区别？

try 命令会模拟玩家的上下坐骑操作：

• 玩家未骑乘时，读取 ride-slot 中的物品名称并匹配坐骑。
• 玩家已骑乘时，结束当前骑乘。

它不会直接指定坐骑 ID，也不会绕过普通召唤流程中的槽位匹配。

坐骑类型无法创建

当前 NMS 桥接层只根据 type 创建两种坐骑：

type	实体
pig	猪型坐骑实体
dragon	龙型坐骑实体

其他类型会被判定为不存在的坐骑类型，无法创建骑乘实体。示例配置建议套模型时优先使用 pig，因为 dragon 可能存在朝向问题。

玩家传送或切换世界后坐骑没有保留

这是插件的既定机制。玩家传送和切换世界事件都会调用结束骑乘逻辑，并移除坐骑实体。

玩家需要在新的位置重新召唤坐骑。

打开背包后坐骑停止移动

打开背包时插件会清除坐骑的前进、后退、左移和右移输入，防止打开界面期间继续移动。关闭背包时会重新刷新移速属性，但不会自动恢复之前的移动输入。

如何确认坐骑事件是否被触发？

插件提供以下自定义事件，事件对象包含玩家、坐骑实体和坐骑数据：

• StartRidingEvent
• EndRidingEvent
• RideDamagedEvent
• RideFlyUpEvent
• RideFlyDownEvent
• RideFlyMoveEvent
• RideMoveForwardEvent
• RideMoveCeaseEvent
• RideRisingEvent
• RideSecondEvent

其中开始骑乘、结束骑乘、坐骑受伤和攀爬事件提供取消状态接口；项目证据中未提供这些事件的完整注册示例。

为什么修改配置后必须重启？

主配置和坐骑文件可以通过 /lyzq reload 重新读取，但以下情况需要注意：

• attribute-plugin 的注释明确要求切换为 SX 属性插件时重启。
• NMS 适配实现会在启动时根据 CraftBukkit 包名选择，并注册坐骑实体。
• 修改服务器版本或 NMS 适配相关内容后，应重启服务器，而不是只重载配置。

插件启动后提示实体注册失败

插件启动时会自动注册猪和龙两种坐骑实体，并根据当前 NMS 版本选择实现。

如果注册失败，重点检查：

• 当前服务器是否为 v1_7_R4 或 v1_12_R1。
• 服务端是否为对应版本的 CraftBukkit/兼容实现。
• 是否存在与当前服务端版本不匹配的 NMS 类。
• 是否重复加载了其他修改原版实体注册表的插件。

不支持的 CraftBukkit 版本不会被自动兼容。

骑乘冷却如何计算？

riding-cooldown 的单位是毫秒，默认值为 5000。普通召唤成功后会记录冷却；冷却期间再次召唤会显示剩余秒数。

riding-cooldown: 5000

/lyzq riding <玩家> <坐骑id> 使用强制骑乘接口，会跳过该冷却检查，但仍会执行其他创建条件检查。

骑乘消息中的 {ride} 和 {time} 不显示

插件只在固定消息位置替换这两个文本：

占位文本	使用位置	含义
{ride}	message.start-riding	当前坐骑名称，对应坐骑文件的 name
{time}	message.riding-cooldown	剩余冷却时间，单位为秒，保留一位小数

如果将占位文本写在其他消息或事件消息中，项目证据未显示会自动替换。

PlaceholderAPI 变量没有生效

PlaceholderAPI 用于以下位置：

• move-speed-attribute：读取玩家移速属性。
• 事件指令：替换指令中的 PlaceholderAPI 变量。

检查 PlaceholderAPI 是否已启用，以及变量是否能被 PlaceholderAPI 正常解析。项目中注册了标识符为 lyzq 的 PlaceholderAPI 扩展，但当前实现没有提供具体变量返回值。

插件重载后按键失效

重载时插件会先注销旧按键，再根据新的 spawn-ride-key 注册按键。检查：

• 按键名称是否符合对应前置插件的格式。
• GermPlugin 或 DragonCore 是否实际启用。
• 服务器控制台是否出现重新注册召唤键位的提示。
• 是否同时启用了两个按键前置。插件的监听注册逻辑优先使用 GermPlugin，未启用时才使用 DragonCore。

仍然无法定位问题

建议先查看服务器控制台中的以下信息：

• 坐骑文件是否出现“载入坐骑”提示。
• 坐骑事件是否出现“载入坐骑技能”提示。
• 当前前置插件是否显示为已启动。
• 坐骑实体是否注册成功。
• 执行重载时是否出现配置解析或实体注册异常。

项目证据未提供更详细的错误码、日志等级或远程诊断方式，因此不能根据未列出的日志内容推断具体原因。