游戏客户端架构 / 系统课时
为什么要返回播放句柄
为什么要返回播放句柄
统一播放服务如果只提供 play(eventId),调用方只能发起播放,却无法准确控制刚刚创建的那个声音实例。返回播放句柄后,停止、暂停、恢复、渐变和状态查询都可以绑定到具体实例,即使多个相同事件同时播放,也不会误操作其他声音。
学习目标
- 理解事件标识与播放实例之间的区别
- 使用播放句柄精确控制某一次播放
- 识别句柄生命周期以及实例结束后的失效语义
事件标识不能代表具体实例
假设玩家连续触发两次 engine.loop。事件标识只能说明它们属于同一种声音,却不能区分第一次创建的实例和第二次创建的实例。如果停止接口仍然写成 stop("engine.loop"),实现只能选择停止全部、停止最近一个或停止某个匹配实例,语义都不够精确。
播放句柄的职责就是保存“这一次播放”的身份。它内部可以关联实例 ID、voice、channel 或中间件实例,但业务层只依赖统一控制接口,不需要知道底层音频对象是什么。

句柄应该提供哪些控制能力
实用的播放句柄通常包含 stop、pause、resume、fadeTo 和 getState。这些方法的共同点是只作用于当前实例,而不是再次通过事件名搜索目标。
下面的 TypeScript 示例模拟两个相同事件同时播放,并用不同句柄分别控制它们。为了让示例保持可运行,fadeTo 只记录目标音量,不模拟真实的逐帧渐变;实际后端可以把同一调用映射到引擎的淡入淡出能力。
type PlaybackState = "playing" | "paused" | "stopped";
class PlaybackHandle {
private state: PlaybackState = "playing";
private volume = 1.0;
constructor(private readonly id: number) {}
pause(): void {
if (this.state === "playing") this.state = "paused";
}
resume(): void {
if (this.state === "paused") this.state = "playing";
}
fadeTo(targetVolume: number): void {
// 示例省略时间插值,仅保留句柄对单个实例的控制语义。
if (this.state !== "stopped") this.volume = targetVolume;
}
stop(): void {
this.state = "stopped";
}
getState(): PlaybackState {
return this.state;
}
describe(): string {
return `${this.id} ${this.state} volume=${this.volume}`;
}
}
class AudioService {
private nextId = 1;
play(_eventId: string): PlaybackHandle {
return new PlaybackHandle(this.nextId++);
}
}
const audio = new AudioService();
const first = audio.play("engine.loop");
const second = audio.play("engine.loop");
first.pause();
first.fadeTo(0.4);
second.stop();
console.log(first.describe());
console.log(second.describe());预期输出:
1 paused volume=0.4
2 stopped volume=1如果接口不返回句柄,这两个实例只能依赖事件名、对象名或其他旁路信息再次查找。实例数量一多,就容易出现误停、误暂停以及业务代码直接保存底层声道对象的问题。
渐变和状态查询为什么也属于句柄
渐变本质上仍然是对某个实例随时间修改参数。例如玩家进入室内时,可以让室外环境声实例淡出,同时让室内环境声实例淡入。两个句柄分别持有两个实例,渐变链路天然互不干扰。
状态查询同样重要。业务逻辑有时需要判断声音仍在播放、已经暂停还是已经结束。由句柄返回统一的 playing、paused、stopped 等状态,比把不同平台和中间件自己的枚举暴露给上层更稳定。
句柄不要承担业务决策
播放句柄负责控制实例,不负责决定应该播放什么。随机选音、材质匹配、并发限制、优先级淘汰等仍应属于播放服务或规则层。否则一个原本轻量的控制对象会逐渐承担资源选择和业务规则,边界会越来越难维护。
统一播放服务采用“播放请求创建实例并返回句柄,句柄只控制该实例”的边界后,同类声音可以安全并发,业务层能够精确暂停、停止和渐变某一次播放,同时底层引擎对象仍然被完整封装在服务内部。