《游戏引擎实现原理》3.2 状态机与混合树

// file: src/subsys/anim/blend.ts
// tier: L1
// verify: npx vitest run src/subsys/anim/state-machine.test.ts
//
// helio 子系统卷 3.2：姿态混合。两件事——两段姿态按权重交叉淡化（cross-fade），
// 以及一维混合树按参数把 N 段姿态加权求和。平移/缩放逐分量线性插值，旋转走 slerp。

import type { PoseBuffer } from './pose.ts';
import { slerpInto } from './evaluator.ts';

/** 线性插值。 */
export function lerp(a: number, b: number, t: number): number {
  return a + (b - a) * t;
}

/**
 * 把 a、b 两段姿态按 w 混合进 out（w=0 取 a，w=1 取 b）。
 * touched 取并集：任一侧驱动过该节点，结果就视为被驱动。
 */
export function blendPose(a: PoseBuffer, b: PoseBuffer, w: number, out: PoseBuffer): void {
  if (a.count !== b.count || a.count !== out.count) {
    throw new RangeError('混合的姿态缓冲节点数必须一致');
  }
  const t = Math.min(1, Math.max(0, w));
  for (let i = 0; i < out.count; i++) {
    const t3 = i * 3;
    const r4 = i * 4;
    for (let k = 0; k < 3; k++) {
      out.translation[t3 + k] = lerp(a.translation[t3 + k]!, b.translation[t3 + k]!, t);
      out.scale[t3 + k] = lerp(a.scale[t3 + k]!, b.scale[t3 + k]!, t);
    }
    slerpInto(
      out.rotation, r4,
      a.rotation[r4]!, a.rotation[r4 + 1]!, a.rotation[r4 + 2]!, a.rotation[r4 + 3]!,
      b.rotation[r4]!, b.rotation[r4 + 1]!, b.rotation[r4 + 2]!, b.rotation[r4 + 3]!,
      t,
    );
    out.touched[i] = a.touched[i]! | b.touched[i]!;
  }
}

/** 一维混合树：把参数 x 定位到相邻两段之间的权重。 */
export interface Blend1D {
  readonly i0: number;
  readonly i1: number;
  readonly w: number;
}

/**
 * 在一串升序阈值里定位参数 x：返回左右两段的下标与右段的权重 w。
 * x 不高于首阈值时两下标都指向首段（w=0）；不低于末阈值时都指向末段。
 */
export function blendWeights1D(thresholds: readonly number[], x: number): Blend1D {
  const n = thresholds.length;
  if (n === 0) throw new RangeError('混合树至少要有一个阈值');
  if (n === 1 || x <= thresholds[0]!) return { i0: 0, i1: 0, w: 0 };
  if (x >= thresholds[n - 1]!) return { i0: n - 1, i1: n - 1, w: 0 };
  for (let j = 0; j < n - 1; j++) {
    const lo = thresholds[j]!;
    const hi = thresholds[j + 1]!;
    if (x >= lo && x < hi) {
      const span = hi - lo;
      return { i0: j, i1: j + 1, w: span > 0 ? (x - lo) / span : 0 };
    }
  }
  return { i0: n - 1, i1: n - 1, w: 0 };
}

/**
 * 一维混合树求值：poses[i] 对应 thresholds[i]（均已各自求值完毕），
 * 按参数 x 混合出 out。典型用法是「速度参数驱动 走→跑」这类连续过渡。
 */
export function blendTree1D(
  poses: readonly PoseBuffer[],
  thresholds: readonly number[],
  x: number,
  out: PoseBuffer,
): void {
  if (poses.length !== thresholds.length) {
    throw new RangeError('姿态数与阈值数必须一致');
  }
  const { i0, i1, w } = blendWeights1D(thresholds, x);
  if (i0 === i1) {
    blendPose(poses[i0]!, poses[i0]!, 0, out);
    return;
  }
  blendPose(poses[i0]!, poses[i1]!, w, out);
}

// file: src/subsys/anim/state-machine.ts
// tier: L1
// verify: npx vitest run src/subsys/anim/state-machine.test.ts
//
// helio 子系统卷 3.2：参数驱动的动画状态机。状态持有一段剪辑，转移由「参数条件」
// 触发，跨越转移时按 duration 做交叉淡化。支持 exitTime（等当前剪辑播到某比例再走）、
// any-state 转移（'*'），以及一次性 trigger（被某次转移消费后自动复位）。

import type { Clip, LoopMode } from './clip.ts';
import { wrapTime } from './evaluator.ts';

export type ParamValue = number | boolean;
export type Comparator = '>' | '<' | '>=' | '<=' | '==' | '!=';

export interface Condition {
  readonly param: string;
  readonly op: Comparator;
  readonly threshold: number;
}

export interface Transition {
  readonly from: string;
  readonly to: string;
  readonly conditions: readonly Condition[];
  readonly duration: number;
  readonly exitTime?: number;
}

export interface AnimState {
  readonly name: string;
  readonly clip: Clip;
  readonly loop: LoopMode;
  readonly speed: number;
}

/** 每帧求值结果：两条状态各自的剪辑时间与混合权重。 */
export interface MachineOutput {
  readonly fromState: string;
  readonly toState: string;
  readonly fromTime: number;
  readonly toTime: number;
  readonly weight: number;
  readonly transitioning: boolean;
}

interface ActiveTransition {
  readonly from: string;
  readonly to: string;
  elapsed: number;
  duration: number;
  toTime: number;
}

export class AnimStateMachine {
  readonly #states: Map<string, AnimState>;
  readonly #transitions: readonly Transition[];
  readonly #params = new Map<string, ParamValue>();
  readonly #triggers = new Set<string>();
  #current: string;
  #currentTime = 0;
  #trans: ActiveTransition | null = null;

  constructor(states: readonly AnimState[], transitions: readonly Transition[], initial: string) {
    this.#states = new Map(states.map((s) => [s.name, s]));
    if (!this.#states.has(initial)) throw new RangeError(`初始状态 ${initial} 不存在`);
    this.#transitions = transitions;
    this.#current = initial;
  }

  get currentState(): string { return this.#current; }
  get isTransitioning(): boolean { return this.#trans !== null; }

  setParam(name: string, value: ParamValue): void { this.#params.set(name, value); }

  getParam(name: string): ParamValue {
    if (this.#triggers.has(name)) return true;
    return this.#params.get(name) ?? false;
  }

  /** 触发一次性参数；它被某次转移的任一条件消费后自动复位。 */
  setTrigger(name: string): void { this.#triggers.add(name); }

  #stateOf(name: string): AnimState {
    const s = this.#states.get(name);
    if (!s) throw new RangeError(`状态 ${name} 不存在`);
    return s;
  }

  /** 当前剪辑的归一化进度 [0, 1]，用于 exitTime 判断。 */
  #normalizedProgress(): number {
    const dur = this.#stateOf(this.#current).clip.duration;
    if (!(dur > 0)) return 1;
    return wrapTime(this.#currentTime, dur, this.#stateOf(this.#current).loop) / dur;
  }

  #conditionMet(c: Condition): boolean {
    const raw = this.getParam(c.param);
    const num = typeof raw === 'boolean' ? (raw ? 1 : 0) : raw;
    switch (c.op) {
      case '>': return num > c.threshold;
      case '<': return num < c.threshold;
      case '>=': return num >= c.threshold;
      case '<=': return num <= c.threshold;
      case '==': return num === c.threshold;
      case '!=': return num !== c.threshold;
    }
  }

  #findTransition(): Transition | null {
    const progress = this.#normalizedProgress();
    for (const tr of this.#transitions) {
      if (tr.from !== this.#current && tr.from !== '*') continue;
      if (tr.to === this.#current) continue;
      if (tr.exitTime !== undefined && progress < tr.exitTime) continue;
      if (tr.conditions.every((c) => this.#conditionMet(c))) return tr;
    }
    return null;
  }

  #startTransition(tr: Transition): void {
    this.#trans = { from: this.#current, to: tr.to, elapsed: 0, duration: tr.duration, toTime: 0 };
    // 消费本转移条件引用到的一次性 trigger
    for (const c of tr.conditions) this.#triggers.delete(c.param);
  }

  /** 推进 dt 秒，返回本帧的混合结果。 */
  update(dt: number): MachineOutput {
    const cur = this.#stateOf(this.#current);
    this.#currentTime += dt * cur.speed;

    if (this.#trans) {
      const to = this.#stateOf(this.#trans.to);
      this.#trans.toTime += dt * to.speed;
      this.#trans.elapsed += dt;
      const w = this.#trans.duration > 0 ? Math.min(1, this.#trans.elapsed / this.#trans.duration) : 1;
      if (w >= 1) {
        this.#current = this.#trans.to;
        this.#currentTime = this.#trans.toTime;
        this.#trans = null;
        return { fromState: this.#current, toState: this.#current, fromTime: this.#currentTime, toTime: this.#currentTime, weight: 1, transitioning: false };
      }
      return { fromState: this.#trans.from, toState: this.#trans.to, fromTime: this.#currentTime, toTime: this.#trans.toTime, weight: w, transitioning: true };
    }

    const tr = this.#findTransition();
    if (tr) {
      this.#startTransition(tr);
      return { fromState: tr.from === '*' ? this.#current : tr.from, toState: tr.to, fromTime: this.#currentTime, toTime: 0, weight: 0, transitioning: true };
    }
    return { fromState: this.#current, toState: this.#current, fromTime: this.#currentTime, toTime: this.#currentTime, weight: 1, transitioning: false };
  }
}

$ npx vitest run src/subsys/anim/state-machine.test.ts
 ✓ src/subsys/anim/state-machine.test.ts (10 tests)
 Test Files  1 passed (1)
      Tests  10 passed (10)