游戏客户端架构 / 系统课时
引擎适配层应该隔离什么
引擎适配层应该隔离什么
统一音频服务真正难的不是“包一层接口”,而是决定哪些变化必须挡在引擎边界之外。本文用一个最小播放服务说明:上层只表达业务意图,Unity、Unreal、Godot 的组件、句柄和生命周期规则全部留在适配层。
学习目标
- 判断哪些能力属于业务音频接口,哪些只能出现在引擎适配层
- 设计不会泄漏 Unity、Unreal、Godot 类型的统一播放边界
- 用最小示例验证更换底层实现时上层业务代码无需修改
先划清适配层的边界
上层业务最关心的是“播放什么、以什么业务语义播放、如何停止”,而不是底层到底创建了 AudioSource、AudioComponent 还是 AudioStreamPlayer。因此,适配层首先要隔离引擎对象类型,其次隔离资源定位方式、实例句柄和生命周期差异。
适合放在统一接口里的概念应当稳定,例如事件 ID、音量、是否循环、空间模式和停止句柄。引擎专属组件、节点路径、场景对象引用、混音器对象以及底层回调参数则不应越过边界。

一个实用的检查方法是:如果把项目从 Unity 换成 Godot,上层接口中的类型名是否需要跟着改?如果答案是“需要”,说明适配边界还不够干净。
统一接口只保留业务语义
下面的完整示例可在 .NET 6+/C# 10 环境运行。IAudioBackend 表示引擎适配边界,业务层只持有 AudioService,测试时则用 FakeBackend 代替真实引擎。
using System;
public readonly record struct AudioRequest(
string EventId,
float Volume,
bool Loop
);
public readonly record struct AudioHandle(int Value);
public interface IAudioBackend
{
AudioHandle Play(AudioRequest request);
void Stop(AudioHandle handle);
}
public sealed class AudioService
{
private readonly IAudioBackend backend;
public AudioService(IAudioBackend backend)
{
this.backend = backend;
}
public AudioHandle PlayUiConfirm()
{
// 业务层只表达“播放确认音”,不接触任何引擎组件。
return backend.Play(new AudioRequest("ui.confirm", 1.0f, false));
}
public void Stop(AudioHandle handle)
{
backend.Stop(handle);
}
}
public sealed class FakeBackend : IAudioBackend
{
private int nextId = 1;
public AudioHandle Play(AudioRequest request)
{
var handle = new AudioHandle(nextId++);
Console.WriteLine($"PLAY {request.EventId} -> {handle.Value}");
return handle;
}
public void Stop(AudioHandle handle)
{
Console.WriteLine($"STOP {handle.Value}");
}
}
public static class Program
{
public static void Main()
{
var audio = new AudioService(new FakeBackend());
var handle = audio.PlayUiConfirm();
audio.Stop(handle);
}
}预期输出:
PLAY ui.confirm -> 1
STOP 1这个示例的关键不在 FakeBackend,而在依赖方向:AudioService 依赖抽象接口,具体引擎适配器实现接口。以后替换实际后端时,PlayUiConfirm() 不需要知道底层组件叫什么。
哪些内容必须留在引擎侧
引擎适配层通常承担四类变化。第一类是资源解析,例如 Unity 的音频资源引用、Unreal 的声音资产、Godot 的音频流对象;第二类是播放实例的创建、复用和销毁;第三类是场景卸载、节点销毁等引擎生命周期;第四类是把底层播放完成、失败等回调转换成统一事件。
统一句柄最好只是稳定 ID 或受控包装。停止、暂停、调参等动作仍通过统一服务完成,这样才能集中检查句柄是否失效,并在切场景、对象池回收等情况下保持一致行为。
不要过度抽象所有引擎差异
适配层的目标不是强行让三个引擎拥有完全相同的能力,而是提供业务真正需要的公共语义。某个引擎特有的高级空间音频、原生混音图或平台插件,如果不是核心业务能力,可以放入扩展接口或能力查询,而不是不断膨胀基础接口。
新增能力时可以先判断两个问题:它是否会被多个业务模块长期依赖?不同引擎是否都能提供接近的业务语义?两个答案都偏“是”时,再提升到统一接口更稳妥。
最终应达到一个明确的验收结果:替换 IAudioBackend 的实现时,角色、UI、战斗等业务代码无需引入任何 Unity、Unreal 或 Godot 类型,只有适配器模块负责处理引擎细节。