坐骑 LyRide
LyRide 是一款自定义坐骑插件。玩家可通过指定槽位中的物品名称匹配坐骑，再使用萌芽引擎或龙之核心按键召唤、骑乘和收回坐骑。
插件提供陆行与飞行两种移动模式，支持八方向移动、多段跳、攀升、飞行升降、世界限高、动态移动速度、骑乘属性、循环动作和事件技能。管理员也可以通过指令让指定玩家骑乘坐骑，或模拟玩家切换骑乘状态。
插件信息
| 项目 | 内容 |
|---|---|
| 插件名 | LyRide |
| 插件版本 | 1.0.4 |
| 作者 | 离渊 |
| Java 版本 | Java 8 |
| 支持服务端 | CraftBukkit v1_7_R4、v1_12_R1，对应项目中的 Minecraft 1.7.10 与 1.12.2 适配 |
| 坐骑实体类型 | pig、dragon |
| 主命令 | /lyzq |
| 数据目录 | plugins/LyRide/ride/ |
插件通过 NMS 桥接层自动选择 v1_7_R4 或 v1_12_R1 实现。其他服务端内部版本没有对应桥接实现，启动时会被判定为不支持。
依赖与兼容
plugin.yml 中登记的软依赖如下：
| 插件 | 用途 |
|---|---|
ProtocolLib | 监听载具方向、跳跃和下马输入，驱动坐骑移动控制 |
GermPlugin | 注册萌芽按键、读取萌芽槽位、播放玩家或坐骑模型动作 |
DragonCore | 注册龙核按键、读取龙核槽位、播放玩家或坐骑模型动作 |
PlaceholderAPI | 解析移动速度属性变量，以及事件指令中的 PAPI 变量 |
MythicMobs | 让事件配置中的 mythic-skill 由骑乘玩家释放 |
Vault | 已登记为软依赖，现有代码中未发现直接调用 |
按键监听会优先使用 GermPlugin；未启用萌芽时再使用 DragonCore。至少需要按实际功能安装对应的槽位、按键、变量、技能或属性插件。
骑乘属性支持以下插件标识：
attribute-plugin 值 | 对接插件 |
|---|---|
AttributePlus2 | AttributePlus 2 |
AttributePlus3 | AttributePlus 3 |
SX-Attribute2 | SX-Attribute 2 |
SX-Attribute3 | SX-Attribute 3 |
| 空字符串 | 不添加或移除骑乘属性 |
切换到 SX-Attribute2 或 SX-Attribute3 后需要重启服务器，使对应 API 完成初始化。
坐骑识别
玩家触发召唤按键时，插件会读取 config.yml 中 ride-slot 指定的槽位，并取得槽位物品名称。物品名称包含某个坐骑配置的 match-name 时，插件会使用该配置创建坐骑。
支持的槽位格式如下：
| 类型 | 格式 | 说明 |
|---|---|---|
| 龙之核心槽位 | DragonCore#槽位名 | 读取 DragonCore 槽位 |
| 萌芽引擎槽位 | GermPlugin#槽位名 | 读取 GermPlugin 槽位 |
| 梦星桐背包槽位 | APInventory#分页id#槽位id | 槽位编号范围为 0 至 53 |
| 离渊背包槽位 | LyInventory#背包id#类型 | 按背包、类型读取物品 |
| 主手 | Origin#MainHand | 读取玩家主手物品 |
| 副手 | Origin#OffHand | 读取玩家副手物品 |
| 头盔 | Origin#Helmet | 读取头盔槽位 |
| 胸甲 | Origin#ChestPlate | 读取胸甲槽位 |
| 护腿 | Origin#Legging | 读取护腿槽位 |
| 靴子 | Origin#Boots | 读取靴子槽位 |
| 原版背包槽位 | Minecraft#槽位id | 槽位编号范围为 0 至 36 |
匹配使用的是包含判断，不要求物品名称与 match-name 完全相同。配置中的 & 颜色代码会转换为 Minecraft 颜色字符后参与匹配。
玩法机制
上下坐骑
玩家按下配置的召唤键后：
- 当前没有骑乘时，插件读取坐骑槽位并匹配坐骑。
- 当前已经骑乘时，再次按键会结束骑乘。
- 玩家必须站在地面上才能创建坐骑。
anti-ride-world中任意文本被当前世界名包含时，禁止创建坐骑。- 普通按键召唤与
/lyzq try受riding-cooldown限制。 /lyzq riding会忽略骑乘冷却，但仍会经过世界、坐骑 ID 和落地状态检查。
玩家主动离开载具、发送下马输入、退出服务器、传送或切换世界时，插件会结束骑乘并移除坐骑实体。重载插件时，所有正在骑乘的玩家也会被强制下坐骑。
陆行移动
陆行坐骑支持：
- 使用前进、后退、左移和右移控制八方向移动。
- 对斜向输入进行归一化，避免斜向移动速度高于直线移动。
- 按
jump-power、jump-tick和jump-count控制跳跃力度、持续时间与段数。 - 使用
rise-power检测前方障碍并执行攀升。 - 骑乘期间免疫玩家摔落伤害。
- 松开移动键后触发停止移动事件，再次移动时触发前进事件。
飞行移动
将坐骑配置的 fly 设为 true 后启用飞行模式：
- 平视移动时保持当前高度。
- 抬头时根据
up-power的角度区间向上移动。 - 低头时根据
down-power的角度区间向下移动。 - 按住空格会持续刷新上升状态，使用跳跃力度和上升配置计算垂直速度。
world-fly-limit可以按完整世界名限制最高飞行 Y 坐标。- 飞行过程可分别触发上升、下降和平飞事件。
移动速度
每个坐骑通过 move-speed 设置基础速度。插件还可以读取 PlaceholderAPI 变量，并通过公式计算最终速度：
yaml
move-speed-attribute: ''
move-speed-attribute-max: 100
move-speed-formula: '{speed_base}*(1+({speed_attribute}*0.01))'| 内容 | 说明 |
|---|---|
{speed_base} | 当前坐骑配置的 move-speed |
{speed_attribute} | move-speed-attribute 解析出的数值，并限制在 0 至 move-speed-attribute-max 之间 |
未填写 move-speed-attribute 时，属性值按 0 处理。公式为空、结果不是有效数字或结果为无穷值时，插件会回退到坐骑基础速度。
玩家开始骑乘后，插件会立即刷新速度属性，并在前 30 秒内每秒重新读取一次。玩家关闭背包时也会刷新该数值。
骑乘属性
坐骑配置中的 riding-attribute 会在开始骑乘时添加给玩家，并在结束骑乘时移除。
yaml
riding-attribute:
- '物理伤害10'属性文本格式由 attribute-plugin 指定的属性插件决定。未配置属性插件时，该列表不会产生属性效果。
伤害与结束条件
每个坐骑可以独立控制受伤行为：
| 配置项 | 作用 |
|---|---|
ride-can-damaged | 是否允许坐骑实体受到伤害 |
ride-or-player-damaged-end-riding | 玩家或可受伤坐骑受到伤害时是否结束骑乘 |
player-attack-end-riding | 骑乘玩家主动造成伤害时是否结束骑乘 |
坐骑受到允许的伤害时会触发 damaged 事件。若坐骑不可受伤，实体伤害会被取消；此时玩家自身受伤仍可能按照结束骑乘配置处理。
坐骑动作
riding-animation 用于在骑乘期间循环播放玩家动作，自动匹配萌芽引擎或龙之核心。
yaml
riding-animation:
- '待机动作:1500'
- 'delay:2000'
- '骑乘动作:1200'支持以下格式：
| 格式 | 说明 |
|---|---|
动作名 | 播放动作；未指定时长时，循环任务默认等待 1000 毫秒 |
动作名:毫秒 | 播放动作，并等待指定毫秒数后处理下一项 |
delay:毫秒 | 不播放动作，仅延迟指定时间 |
事件技能成功触发时，骑乘循环动作会暂停 1 秒并从列表开头重新播放。事件中的 player-action 与 ride-action 同样支持 动作名 和 动作名:毫秒 格式。
事件技能
每个坐骑配置都可以在 event 节点下定义多组事件。每组事件可设置触发条件、触发概率、冷却、MythicMobs 技能、成功或失败消息、成功或失败指令，以及玩家和坐骑动作。
支持的触发类型如下：
trigger-type | 触发时机 |
|---|---|
start-riding | 开始骑乘 |
end-riding | 结束骑乘 |
fly-up | 飞行上升 |
fly-down | 飞行下降 |
fly-move | 飞行平移 |
rising | 陆行坐骑攀升 |
forward | 从停止状态进入移动状态 |
cease | 松开方向输入并停止移动 |
damaged | 坐骑受到未被取消的伤害 |
second | 骑乘期间每秒产生一次检测机会 |
right | 骑乘玩家右键 |
left | 骑乘玩家左键 |
事件冷却在概率判断前写入，因此无论本次触发成功还是失败，都会进入冷却。每次创建新的骑乘实例时，事件冷却从可触发状态开始；结束骑乘后，本次骑乘实例及其冷却记录会被移除。
事件指令支持以下执行前缀：
| 前缀 | 执行身份 |
|---|---|
[console] | 控制台 |
[op] | 玩家临时获得 OP 后执行，完成后恢复原状态 |
[player] | 玩家自身 |
| 无前缀 | 玩家自身 |
指令会先解析 PlaceholderAPI 变量，并支持 eval:{公式}、ceil:{公式}、floor:{公式} 数值表达式。表达式可以使用 ~ 指定数值格式，例如 eval:{1+1~%.1f}。
完整事件配置请查看 事件技能。
指令
所有已实现的管理指令都要求命令发送者为 OP。项目中没有声明独立权限节点。
| 指令 | 说明 |
|---|---|
/lyzq | OP 执行时显示插件指令帮助 |
/lyzq reload | 重载 config.yml 和 ride/ 中的坐骑配置，重新注册按键，并强制结束现有骑乘 |
/lyzq riding [玩家] [坐骑id] | 强制指定在线玩家骑乘指定坐骑，忽略骑乘冷却 |
/lyzq try [玩家] | 模拟指定在线玩家切换骑乘状态；上坐骑时从其配置槽位匹配坐骑 |
[玩家] 必须是在线玩家名称，[坐骑id] 必须与某个坐骑配置中的 id 一致。
功能总览
| 功能 | 说明 |
|---|---|
| 多来源槽位 | 支持龙核、萌芽、梦星桐背包、离渊背包和原版装备或背包槽位 |
| 名称匹配 | 按物品显示名称包含 match-name 的方式识别坐骑 |
| 多坐骑文件 | 递归读取 plugins/LyRide/ride/ 下所有 .yml 文件 |
| 两种实体 | 支持 pig 与 dragon 自定义骑乘实体 |
| 双版本 NMS | 自动选择 v1_7_R4 或 v1_12_R1 桥接实现 |
| 八向移动 | 支持前后左右及斜向移动，并统一斜向速度 |
| 陆行能力 | 支持多段跳、障碍攀升和空中移动衰减 |
| 飞行能力 | 支持抬头上升、低头下降、平飞、空格上升和世界限高 |
| 动态速度 | 使用 PAPI 数值、属性上限和自定义公式计算最终移动速度 |
| 骑乘属性 | 对接 AttributePlus 2/3 与 SX-Attribute 2/3 |
| 循环动作 | 骑乘期间按顺序循环播放玩家动作和延迟配置 |
| 事件系统 | 支持骑乘、移动、飞行、伤害、点击和定时触发 |
| 技能联动 | 成功触发时可释放 MythicMobs 技能 |
| 指令联动 | 成功或失败时可执行控制台、临时 OP 或玩家指令 |
| 动作联动 | 成功触发时可播放玩家动作和坐骑动作 |
| 状态清理 | 下马、退出、传送、切换世界、重载和停服时清理骑乘状态 |
注意事项
- 示例坐骑文件在每次执行重载时都会由插件资源重新保存，直接修改
ride/示例坐骑.yml可能被覆盖。正式坐骑应使用其他文件名。 id用于指令和内部索引，同一个id不应在多个文件中重复。type目前只接受pig或dragon，其他值无法创建坐骑实体。- 源配置建议使用
pig套模型；示例文件注明dragon可能存在朝向问题。 - 玩家不在地面时不会创建坐骑。
- 禁止世界使用包含匹配，而飞行限高使用完整世界名作为配置键。
PlaceholderAPI、MythicMobs、动作插件和属性插件只会让对应功能生效，不应填写服务器中不存在的变量、技能、动作或属性格式。- PlaceholderAPI 扩展标识为
lyzq，但现有扩展代码没有实现可用的 LyRide 自定义变量，不应假设存在%lyzq_...%变量。
页面索引
| 页面 | 内容 |
|---|---|
| 配置说明 | config.yml 的属性插件、速度公式、槽位、按键、世界限制、冷却和消息 |
| 坐骑配置 | ride/ 文件中的实体类型、名称匹配、移动、跳跃、飞行、属性和动作 |
| 事件技能 | 触发类型、概率、冷却、MythicMobs 技能、消息、指令和动作 |
| 常见问题 | 坐骑无法召唤、无法移动、版本不兼容、动作或属性不生效等问题排查 |
| 更新日志 | 文档整理记录 |