高级特性

骑乘系统、根运动、石化、子模型、分段行为等进阶能力。

骑乘系统

控制器类型

控制器	移动方式	下马方式	垂直控制
walking	地面行走	潜行下马	跳跃
force_walking	地面行走	不可主动下马	跳跃
flying	空中飞行	潜行下马	跳跃上升 / 潜行下降
force_flying	空中飞行	不可主动下马	跳跃上升 / 潜行下降

控制器上下文

ModelEntityMountControllerContext 提供骑乘控制的完整 API：

方法	说明
syncRiderPosition()	同步骑手位置到座位
syncOwnerLookFromRider()	同步坐骑朝向为骑手视角
moveOwnerWalking()	地面移动
moveOwnerFlying()	飞行移动
jumpOwner()	跳跃
nullifyOwnerFallDistance()	清除摔落距离
requestDismount()	请求下马
isOwnerOnGround()	是否着地
ownerSpeed()	当前速度
seatPosition()	座位世界坐标

骑乘流程

根运动

根运动（Root Motion）从动画曲线中提取位移数据，驱动实体在世界中移动。

工作原理

采样逻辑

• 从活跃动画中采样根骨骼的位置曲线
• 计算帧间位移差（delta）
• 循环动画自动处理时间回绕
• 支持 emptyZero 模式（无根运动曲线时贡献零位移）
• 多动画贡献按 Override/Additive 语义合并

配置参数

参数	类型	说明
weight	Double	根运动权重（0.0 ~ 1.0）
baseWeight	Double	基础权重
override	Boolean	是否覆盖现有配置

手动根运动

除动画驱动外，还支持通过 animateModel mechanic 的手动骨骼变换产生根运动：

手动变换 → queueManualRootTransform() → 帧间 delta → 实体移动

石化

石化（Petrify）将模型冻结为静态姿态，停止所有动画和交互。

效果

• 冻结当前骨骼姿态
• 停止动画采样
• 可选视觉效果（材质变化）
• 客户端专用渲染层处理石化外观

使用

Skills:
  - petrify{modelId=my_model;duration=100}

子模型

子模型（SubModel）允许在主模型的骨骼上挂载额外的 Bedrock 模型。

架构

特性

• 子模型继承挂载骨骼的世界变换
• 独立的动画状态（可单独播放动画）
• 独立的渲染层
• 支持嵌套（子模型上再挂子模型）

使用

Skills:
  - subModel{modelId=main_model;subModelId=weapon;bone=right_hand}

分段行为

分段行为（Segment）将模型的骨骼链拆分为独立控制的段，用于蛇形/链式运动。

工作原理

• 定义骨骼链（如脊椎骨骼序列）
• 每段独立跟随前一段的位置
• 产生自然的蛇形/波浪运动
• 服务端计算 + 客户端渲染

使用

Skills:
  - segment{modelId=snake_model;config=...}

Adyeshach 集成

支持将模型挂载到 Adyeshach NPC（虚拟实体）：

• 通过 AdyeshachModelEntityBridge 适配
• NPC 作为 ModelEntity 的 Owner
• 支持所有模型特性（动画、碰撞箱、骑乘等）
• 无需真实服务端实体

碰撞箱系统

主碰撞箱

• 替代原版 Entity AABB
• 尺寸由模型 Manifest 定义
• 支持缩放（hitboxScale）
• 用于伤害判定和交互

子碰撞箱

• 绑定到特定骨骼
• 跟随骨骼世界变换
• 独立的伤害判定区域
• 通过 bindHitbox mechanic 配置

观察者管理

模型实体支持精细的观察者控制：

能力	说明
强制可见	forcedViewers — 无视距离/遮挡强制显示
强制隐藏	hiddenViewers — 对特定玩家隐藏
追踪开关	viewerTrackingEnabled — 启用/禁用观察者追踪
可视半径	viewRadius — 自定义可视距离
LOD	基于距离的细节级别
自我可见	viewSelf — 第一人称是否可见自身模型