《Cocos 游戏开发入门》9.1 音频播放与音效池

const a = new Audio('/sfx/coin.wav');
a.volume = 0.6;
a.play();

// mini2d/audio/play-handle.ts
export interface PlayHandle {
  /** 音效标识，用于按名停止同类声音 */
  readonly name: string;
  /** 播放该实例的起始时间戳（毫秒），抢占策略据此判断「最旧」 */
  readonly startedAt: number;
  /** 当前音量（0~1），抢占策略据此判断「最轻」 */
  readonly volume: number;
  stop(): void;
  setVolume(v: number): void;
}

// mini2d/audio/audio-pool.ts
import type { PlayHandle } from './play-handle';

interface PooledSlot {
  el: HTMLAudioElement;
  busy: boolean;
  name: string;
  startedAt: number;
  volume: number;
}

export class AudioPool {
  private readonly slots: PooledSlot[] = [];
  private readonly srcCache = new Map<string, string>();

  /** 预热：预先创建 N 个空槽位，避免首次播放时的构造抖动 */
  constructor(private readonly capacity = 12) {
    for (let i = 0; i < capacity; i++) {
      this.slots.push(this.createSlot());
    }
  }

  private createSlot(): PooledSlot {
    const el = new Audio();
    el.preload = 'auto';
    return { el, busy: false, name: '', startedAt: 0, volume: 1 };
  }
}

  /** 取一个可用槽位；返回 null 表示当前无法播放（被丢弃） */
  acquire(name: string, now: number): PooledSlot | null {
    let slot = this.slots.find((s) => !s.busy);
    if (!slot) slot = this.steal(name, now);
    if (!slot) return null; // 池满且不允许抢占

    slot.busy = true;
    slot.name = name;
    slot.startedAt = now;
    return slot;
  }

  private steal(name: string, now: number): PooledSlot | null {
    const busy = this.slots.filter((s) => s.busy);
    if (busy.length === 0) return null;

    // 第一优先级：播放时长最久
    busy.sort((a, b) => a.startedAt - b.startedAt);
    const oldest = busy[0];
    // 仅当候选确实「老」（超过 1.5 秒）才允许抢占，保护刚起步的重要音效
    if (now - oldest.startedAt < 1500) return null;

    oldest.el.pause();
    oldest.busy = false;
    return oldest;
  }

// mini2d/audio/audio-system.ts
import { AudioPool } from './audio-pool';
import type { PlayHandle } from './play-handle';

export class AudioSystem {
  private readonly pool = new AudioPool(12);

  play(name: string, volume = 1): PlayHandle | null {
    const now = performance.now();
    const slot = this.pool.acquire(name, now);
    if (!slot) return null; // 池满且不可抢占，静默丢弃

    const src = this.pool.srcOf(name);
    if (slot.el.src !== src) slot.el.src = src;
    slot.el.currentTime = 0;
    slot.el.volume = volume;
    slot.volume = volume;
    void slot.el.play();
    return this.makeHandle(slot);
  }
}

  /** 停止所有同类音效，例如离开关卡时清掉全部脚步 */
  stopByName(name: string): void {
    for (const slot of this.pool.busySlots()) {
      if (slot.name === name) {
        slot.el.pause();
        this.pool.release(slot);
      }
    }
  }

  /** 批量调音量，例如滑杆拖动时实时生效 */
  setVolumeByName(name: string, v: number): void {
    const clamped = Math.max(0, Math.min(1, v));
    for (const slot of this.pool.busySlots()) {
      if (slot.name === name) {
        slot.el.volume = clamped;
        slot.volume = clamped;
      }
    }
  }

// game/scenes/level.ts
const audio = new AudioSystem();

function onCoinCollected(): void {
  audio.play('coin', 0.7);
}

function onJump(): void {
  audio.play('jump', 0.5);
}

function onPlayerHurt(): void {
  audio.stopByName('jump'); // 受伤时掐掉未播完的跳跃音，避免叠加
  audio.play('hurt', 0.9);
}

import { _decorator, Component, AudioSource, AudioClip } from 'cc';
const { ccclass, property } = _decorator;

@ccclass('SfxPlayer')
export class SfxPlayer extends Component {
  @property(AudioSource)
  source: AudioSource | null = null;

  @property(AudioClip)
  coinClip: AudioClip | null = null;

  onCoinCollected(): void {
    if (!this.source || !this.coinClip) return;
    // 短音效用 playOneShot：不打断当前播放，可叠加多路
    this.source.playOneShot(this.coinClip, 0.7);
  }
}