Live2D桌宠实现

摘要：Live2D 以参数驱动骨骼与变形器，在 2D 素材上实现伪 3D 的立体感与部位级交互，是陪伴型桌宠的甜点方案。本文说明其渲染原理与参数契约，给出 TS 语义接口与依赖清单，覆盖载入、视线跟随、点击互动、动作与表情切换。

Live2D 与帧动画、Lottie 的本质区别：后两者烘焙「结果」，Live2D 烘焙「结构」。美术在 Cubism 编辑器中把 PSD 分层图拆解为部件，为部件绑定骨骼（Bone）与变形器（Deformer），并建立参数（Parameter）到部件变形的映射；导出的 .moc3 模型连同纹理贴图，由 SDK 在 WebGL 上实时变形渲染。因此运行时拿到的不是帧，而是一个可被任意参数组合驱动的活模型——这正是「能应」层的来源。

参数是美术与代码之间的契约，也是 Live2D 交互的全部入口。三类参数构成核心：角度类（ParamAngleX/Y/Z）驱动头颈旋转，用于视线跟随；开合类（ParamEyeLOpen/R、ParamMouthOpen）驱动眼嘴开合，用于眨眼与说话；动作类（ParamBodyAngleX 等）驱动躯干姿态。SDK 对参数做插值平滑，代码只需持续写入目标值即可获得自然过渡，无需关心中间帧。

Live2D 的 TS 语义接口如下。依赖建议选封装层而非裸 SDK：pixi-live2d-display（基于 pixi.js）提供 DOM 式生命周期与事件，底层仍是 Cubism SDK。

// 依赖：pixi.js + pixi-live2d-display（底层为 Cubism Core / WebGL）
interface Live2DPet {
  /** 载入模型：.moc3 文件、贴图列表与可选 physics/motion 清单 */
  load(model: { moc3: string; textures: string[]; physics?: string }): Promise<void>;
  /** 写入参数值，weight 用于多源参数混合（如视线与点头叠加） */
  setParam(id: string, value: number, weight?: number): void;
  /** 视线跟随：由鼠标/指针坐标映射为 ParamAngleX/Y 的归一化向量 */
  trackPointer(x: number, y: number): void;
  /** 点击互动：未命中指定部位时触发默认反应 */
  tap(hit?: { part: string }): void;
  /** 播放动作组中的指定动作（motion3.json 声明） */
  setMotion(group: string, index: number): void;
  /** 切换表情（expressions 清单，如 normal/happy/angry） */
  setExpression(name: string): void;
  /** 口型驱动：按音频响度写 ParamMouthOpen，需外部节律源 */
  setMouthOpen(amount: number): void;
  destroy(): void;
}

三条核心交互的实现思路：视线跟随即把指针坐标做视口归一化，映射为 ParamAngleX（左右）与 ParamAngleY（上下），并叠加微小的 ParamEyeBallX/Y 让眼球独立转动；说话即在音频播放期间按响度节律写 ParamMouthOpen，停顿间隙回落到 0；点击互动则先经 SDK 命中测试判断点击落在哪个部件（头、手、身体），再按部位触发对应 setMotion 或 setExpression。三者均可独立驱动，互不阻塞，这正是 Live2D 相比前两方案的核心收益。

注意点：模型与动作清单（model3.json 引用的 motion3.json、expressions）应随模型一并预载并缓存；trackPointer 需做阻尼平滑（如低通滤波）避免视线抖动；多参数同帧写入时依赖 SDK 的插值队列，无需自行补间。展望：换装可映射为同骨骼结构的多套纹理热切换；参数 ID 应由美术在 Cubism 中统一命名并以文档固化，作为前后端协作的契约文件；若需要骨骼级自由控制或物理模拟，则应升级至 3D 方案。