2.3.3 模型运行时驾驶座 - LiPet 文档

为缺少原生驾驶骨的 ModelEngine 宠物补充运行时虚拟驾驶座，避免隐藏原版载体时仍走 Bukkit 载体骑乘、产生乘客绑定找不到载具的问题。已有模型驾驶骨保持原样；继续保留主驾驶选择、取消下马时拒绝换乘以及主人和等级检查。

适用范围

普通 ModelEngine 外观与 MythicMobs 自行挂载的 ModelEngine 模型均按实际模型容器识别。只有完全没有原生驾驶骨时才使用补充座位；不修改 .bbmodel、模型动画、原版载体可见性或 Bukkit 隐身状态。模型原本已有驾驶骨时，以模型作者提供的座位为准，本节偏移不会改动它。

运行时座位采用 ModelEngine 的虚拟座位与驾驶控制。它修复无驾驶骨模型缺少可绑定载具的问题；不能保证任意模型自动获得准确的背部坐姿，也不表示所有 Folia 动画采样错相已经消除。原版无模型宠物继续使用原版骑乘。

准备座位期间，快速重复点击只提交最新请求；玩家已换乘、离线、跨区或宠物已回收时，不会由旧回调强制挂回。准备完成到实际挂载之间会复核实际模型实例，避免 MythicMobs 更换模型后使用旧座位就绪结果。MM 延后添加模型、先进入原版骑乘的情况会转入模型座位准备流程。

原版载具的下马事件被其他插件取消时，保留原挂载并拒绝转入模型座位；以实际载具关系是否解除作为继续换乘的条件，避免原版与虚拟座位同时绑定骑手。LiPet 上马入口及 MM/ME 直接上马事件都执行这一保护。

补充座位后采用 ModelEngine 标准驾驶控制。飞行坐骑使用跳跃键上升、空中潜行键下降；座位开关不会自动把地面宠物变成飞行坐骑，仍需符合宠物的骑乘类型和等级条件。

全局与单宠配置

pet-types.yml 新增 riding.model-seat，旧配置自动补齐缺失项与中文注释，已有值和管理员注释保留：

riding:
  model-seat:
    # true 为无原生驾驶骨的 ME 模型补座位；false 关闭补充，不替代骑乘权限和等级检查。
    enabled: true
    # 目标模型真实 ID；空时只选唯一模型或唯一主碰撞箱模型，有歧义则拒绝骑乘。
    model: ""
    # 父骨真实 ID，区分大小写；空时使用载体参考点，不自动猜测 body、chest 等名称。
    parent-bone: ""
    # 模型缩放前的方块坐标，各轴均须是 -64 到 64 的有限数值。
    x: 0.0
    # 初始高度 1.0，需按具体模型的体型和预期坐姿调整。
    y: 1.0
    # 父骨非空时，座位随该骨骼变换；旋转后的偏移方向也随之改变。
    z: 0.0

原生 LiPet 类型文件在 types.<类型ID>.behavior.model-seat 逐项覆盖；省略的项继续继承全局。MCPets 格式文件在根节点使用 behavior.model-seat，其余 Id、MythicMob、Mountable 等字段继续按原规则读取，原文件不会被转换或展开。

例如，只为一个已存在的类型调整高度，可将下面的 behavior 节点合并进该类型。不要另建重复的类型 ID：

behavior:
  model-seat:
    # 示例高度，单位为模型缩放前的方块；允许 -64 到 64，按实际模型调整。
    y: 1.5

parent-bone 必须填写目标模型中的真实骨 ID，填写不存在的 ID 会拒绝准备座位。model 留空且多个模型无法唯一选定时，也会拒绝，不按加载顺序猜选。关闭补充座位后，无原生驾驶骨的模型不会再通过隐藏载体回退强行上马；原有驾驶骨与无模型宠物不受这个开关影响。

坐标不是 Blockbench 像素：默认模型单位换算下 16 像素对应 1 方块，模型运行时缩放会继续影响座位；带父骨旋转的模型还需核对局部方向。默认 parent-bone: "" 不保证跟随身体骨骼的独立摇摆。希望座位跟随背部动画时，请指定真实背部或躯干骨，再调整局部偏移。

修改后先执行 /lipet reload 读取配置，再收回并重新召唤宠物。活动模型已有的运行时座位不会因普通配置重载被反复重建。换 Jar 仍需要正常重启。

升级步骤

正常停服，备份 plugins/LiPet、数据库、恢复台账及相关 ME/MM 配置。
将旧 LiPet Jar 移出 plugins 扫描目录，只放入 LiPet-2.3.3.jar，保留旧配置和存档。
正常启动，确认 Enabling LiPet v2.3.3。本次不改数据库结构，也不要求重新制作或分发已有资源包。
重新召唤模型宠物，从骑手与旁观者视角检查上马、转向、移动、下马、换乘及动画中的座位位置。
对需要微调的模型配置单宠座位；确认自己的模型 ID 和骨 ID，不照抄其他模型的名称。

验证记录

最终 LiPet 2.3.3 成品通过 884 项单元测试（失败、错误、跳过均为 0）。同一 Jar 在 Paper 26.2 与 Folia 26.2 隔离服完成 1832 项运行与输出包检查、2128 个采样；覆盖 6 份原模型、5 类生物、两平台各 8 个基础/载体缩放用例，16 个用例均单独检查骑手实际随载体向四个方向移动，14 次直接换乘保留旧挂载直至切换。原版隐藏载体缺少出生包的旧回退路径不再作为模型骑乘使用。

本轮每平台 8 个主用例中，同一采样点的运动修正残差最大值为 Paper 0.551 方块、Folia 0.623 方块；采样包含实体与模型更新阶段的相位差，不是客户端视觉误差或网络延迟。额外带旋转 body 父骨、2 倍缩放的测试在突然转向 90° 后，Folia 首个运动采样残差为 4.301164 方块；匹配前一个采样时为 0，这说明采样阶段差异仍需保留解释，不能据此宣称视觉偏移全部为零或流畅度已经通过。

最终 Jar SHA-256：042c14eadf755a8f16757a46f93e05c6fa4eff953e922d2677f995f47e3fb0f9。历史验证不计入本轮数字。

服务端挂载、真实 ModelEngine 输出包结构与真实客户端渲染是不同层面的证据。没有真人客户端与客户实际资源包的画面，不声明录像中的紫色龙已经完成视觉验收。