《Cocos 游戏开发入门》8.1 帧动画与精灵表播放

// 每帧时长 frameDuration = 1 / fps
const frameIndex = Math.floor(t / frameDuration);

// src/anim/frame-clip.ts
export type WrapMode = 'once' | 'loop' | 'pingpong';

export interface FrameClip {
  /** 依次引用的帧名，对应图集里的 frame.name */
  frames: string[];
  /** 播放帧率：每秒切换多少张图 */
  fps: number;
  /** 播放模式 */
  wrapMode: WrapMode;
  /** 事件帧：在第几帧触发，触发什么 */
  events?: FrameEvent[];
}

export interface FrameEvent {
  /** 帧下标（0 基） */
  frame: number;
  /** 事件名，交给上层处理 */
  name: string;
}

// src/anim/wrap.ts
import { WrapMode } from './frame-clip';

export interface WrappedFrame {
  index: number;
  /** 是否已到达终点（仅 once 有意义） */
  finished: boolean;
}

export function wrapFrameIndex(
  rawIndex: number,
  frameCount: number,
  mode: WrapMode,
): WrappedFrame {
  if (frameCount <= 1) {
    return { index: 0, finished: true };
  }
  if (mode === 'once') {
    if (rawIndex >= frameCount) {
      return { index: frameCount - 1, finished: true };
    }
    return { index: Math.max(0, rawIndex), finished: false };
  }
  if (mode === 'loop') {
    // 取模保证非负
    return { index: ((rawIndex % frameCount) + frameCount) % frameCount, finished: false };
  }
  // pingpong：2N-2 的周期，回程不含两个端点
  const period = frameCount * 2 - 2;
  const phase = ((rawIndex % period) + period) % period;
  const index = phase < frameCount ? phase : period - phase;
  return { index, finished: false };
}

// 每帧推进的时间不是 deltaTime，而是 deltaTime * speed
this.elapsed += deltaTime * this.speed;

const rawIndex = Math.floor(this.elapsed * clip.fps);

// src/anim/frame-player.ts
import { FrameClip, FrameEvent } from './frame-clip';
import { wrapFrameIndex } from './wrap';

export type FrameEventListener = (event: FrameEvent) => void;

export class FramePlayer {
  clip: FrameClip;
  speed = 1;
  /** 已累计的播放时间（秒） */
  private elapsed = 0;
  private prevIndex = 0;
  private listeners: FrameEventListener[] = [];

  constructor(clip: FrameClip) {
    this.clip = clip;
  }

  onEvent(fn: FrameEventListener): void {
    this.listeners.push(fn);
  }

  get finished(): boolean {
    const { finished } = wrapFrameIndex(
      Math.floor(this.elapsed * this.clip.fps),
      this.clip.frames.length,
      this.clip.wrapMode,
    );
    return finished;
  }

  /** 当前应显示的帧名 */
  get frameName(): string {
    const raw = Math.floor(this.elapsed * this.clip.fps);
    const { index } = wrapFrameIndex(raw, this.clip.frames.length, this.clip.wrapMode);
    return this.clip.frames[index];
  }

  reset(): void {
    this.elapsed = 0;
    this.prevIndex = 0;
  }

  update(deltaTime: number): void {
    if (this.finished) return;
    this.elapsed += deltaTime * this.speed;
    const raw = Math.floor(this.elapsed * this.clip.fps);
    const { index } = wrapFrameIndex(raw, this.clip.frames.length, this.clip.wrapMode);
    this.fireEvents(this.prevIndex, index);
    this.prevIndex = index;
  }

  private fireEvents(prev: number, cur: number): void {
    const events = this.clip.events;
    if (!events) return;
    for (const ev of events) {
      if (this.crossed(prev, cur, ev.frame)) {
        for (const fn of this.listeners) fn(ev);
      }
    }
  }

  private crossed(prev: number, cur: number, target: number): boolean {
    if (cur >= prev) return target > prev && target <= cur;
    return target < prev && target >= cur;
  }
}

// src/scene/animated-sprite-node.ts
import { SpriteNode } from './sprite-node';
import { AtlasData, AtlasFrame } from '../render/atlas';
import { FramePlayer } from '../anim/frame-player';

export class AnimatedSpriteNode extends SpriteNode {
  private frameMap: Map<string, AtlasFrame>;
  private player: FramePlayer;

  constructor(frameMap: Map<string, AtlasFrame>, player: FramePlayer) {
    const first = frameMap.get(player.frameName);
    if (!first) throw new Error('首帧缺失');
    super({} as never, first.x, first.y, first.w, first.h);
    this.frameMap = frameMap;
    this.player = player;
  }

  update(deltaTime: number): void {
    this.player.update(deltaTime);
    const frame = this.frameMap.get(this.player.frameName);
    if (frame) {
      this.sprite.sx = frame.x;
      this.sprite.sy = frame.y;
      this.sprite.sw = frame.w;
      this.sprite.sh = frame.h;
    }
  }
}

// assets/scripts/HeroAnim.ts
import { _decorator, Component, Animation, AnimationState, AnimationClip } from 'cc';
const { ccclass, property } = _decorator;

@ccclass('HeroAnim')
export class HeroAnim extends Component {
  @property(AnimationClip)
  runClip: AnimationClip | null = null;

  private anim: Animation | null = null;

  onLoad() {
    this.anim = this.getComponent(Animation);
    if (this.anim && this.runClip) {
      const state: AnimationState = this.anim.createState(this.runClip, 'run');
      state.speed = 1.5;
      state.wrapMode = AnimationClip.WrapMode.Loop;
    }
  }

  playRun() {
    this.anim?.play('run');
  }
}