《Cocos 游戏联机实战》9.1 同步表现与插值动画

// sync/interpolate.ts —— 纯 TS 插值采样器，无 cc 依赖
export interface Snapshot {
  t: number; // 该快照对应的逻辑时刻（毫秒）
  x: number;
  y: number;
}

export interface RenderState {
  x: number;
  y: number;
  vx: number; // 当前区段速度，单位：像素 / 毫秒
  vy: number;
}

/** 在 renderTime 处对按 t 升序排列的快照做线性插值。 */
export function sampleAt(buffer: readonly Snapshot[], renderTime: number): RenderState {
  if (buffer.length === 0) return { x: 0, y: 0, vx: 0, vy: 0 };
  if (buffer.length === 1) {
    const only = buffer[0];
    return { x: only.x, y: only.y, vx: 0, vy: 0 };
  }
  if (renderTime <= buffer[0].t) {
    const first = buffer[0];
    return { x: first.x, y: first.y, vx: 0, vy: 0 };
  }
  const last = buffer[buffer.length - 1];
  if (renderTime >= last.t) {
    const prev = buffer[buffer.length - 2];
    const span = last.t - prev.t;
    const inv = span > 0 ? 1 / span : 0;
    return { x: last.x, y: last.y, vx: (last.x - prev.x) * inv, vy: (last.y - prev.y) * inv };
  }

  // 二分找到 renderTime 落在 [lo, hi)
  let lo = 0;
  let hi = buffer.length - 1;
  while (hi - lo > 1) {
    const mid = (lo + hi) >> 1;
    if (buffer[mid].t <= renderTime) lo = mid;
    else hi = mid;
  }
  const a = buffer[lo];
  const b = buffer[hi];
  const span = b.t - a.t;
  const alpha = span > 0 ? (renderTime - a.t) / span : 0;
  const inv = span > 0 ? 1 / span : 0;
  return {
    x: a.x + (b.x - a.x) * alpha,
    y: a.y + (b.y - a.y) * alpha,
    vx: (b.x - a.x) * inv,
    vy: (b.y - a.y) * inv,
  };
}

import { describe, expect, it } from 'vitest';
import { sampleAt, type Snapshot } from './interpolate';

const buf: Snapshot[] = [
  { t: 0, x: 0, y: 0 },
  { t: 100, x: 100, y: 0 },
  { t: 200, x: 200, y: 40 },
];

describe('sampleAt', () => {
  it('在两条快照之间线性插值', () => {
    const s = sampleAt(buf, 50);
    expect(s.x).toBeCloseTo(50);
    expect(s.y).toBeCloseTo(0);
  });

  it('速度取当前区段斜率，而非相邻帧差分', () => {
    const s = sampleAt(buf, 150);
    expect(s.vx).toBeCloseTo(1); // (200 - 100) / 100
    expect(s.vy).toBeCloseTo(0.4); // (40 - 0) / 100
  });

  it('早于首帧夹紧到首帧', () => {
    expect(sampleAt(buf, -10).x).toBe(0);
  });

  it('晚于末帧夹紧到末帧，速度沿用末段', () => {
    const s = sampleAt(buf, 999);
    expect(s.x).toBe(200);
    expect(s.vx).toBeCloseTo(1);
  });

  it('空缓冲返回原点', () => {
    expect(sampleAt([], 0)).toEqual({ x: 0, y: 0, vx: 0, vy: 0 });
  });
});

// assets/scripts/net/sync/RemotePlayerView.ts
import { _decorator, Animation, Component, Node, Vec3 } from 'cc';
import { sampleAt, type RenderState, type Snapshot } from '../sync/interpolate';

const { ccclass, property } = _decorator;

@ccclass('RemotePlayerView')
export class RemotePlayerView extends Component {
  @property(Node)
  target: Node | null = null;

  @property(Animation)
  anim: Animation | null = null;

  @property
  interpDelayMs = 100;

  @property
  runThreshold = 0.5;

  @property
  idleThreshold = 0.2;

  private readonly buffer: Snapshot[] = [];
  private readonly pos = new Vec3();
  private clockMs = 0;
  private state = '';

  /** 网络层收到一条服务端快照时调用。缓冲保持升序、只留插值窗口。 */
  pushSnapshot(t: number, x: number, y: number): void {
    this.buffer.push({ t, x, y });
    while (this.buffer.length > 16) this.buffer.shift();
  }

  update(dt: number): void {
    this.clockMs += dt * 1000;
    const renderTime = this.clockMs - this.interpDelayMs;
    const s = sampleAt(this.buffer, renderTime);
    this.pos.set(s.x, s.y, 0);
    this.target?.setPosition(this.pos);
    this.applyAnim(s);
  }

  private applyAnim(s: RenderState): void {
    const speed = Math.hypot(s.vx, s.vy);
    const next = this.nextState(speed);
    if (next === this.state) return;
    this.state = next;
    this.anim?.crossFade(next, 0.12);
  }

  private nextState(speed: number): string {
    if (this.state === 'run') return speed < this.idleThreshold ? 'idle' : 'run';
    return speed > this.runThreshold ? 'run' : 'idle';
  }
}

import { _decorator, Animation, AnimationState, Component } from 'cc';
const { ccclass, property } = _decorator;

@ccclass('FxPlayer')
export class FxPlayer extends Component {
  @property(Animation)
  anim: Animation | null = null;

  start(): void {
    // 正确：事件常量挂在 Animation 上，不是 AnimationState
    this.anim?.on(Animation.EventType.FINISHED, this.onDone, this);
  }

  private onDone(type: string, state: AnimationState): void {
    console.log('特效播完', type, state.name);
  }

  onDestroy(): void {
    this.anim?.off(Animation.EventType.FINISHED, this.onDone, this);
  }
}