游戏客户端架构 / 系统课时
把引擎依赖压缩到适配层
把引擎依赖压缩到适配层
当状态直接拿着 Animator、Actor、Node、输入对象和时间单例时,业务规则会被引擎 API 包围,迁移和测试都很困难。本节把这些平台对象收进适配层,让状态只依赖稳定的游戏语义,并用可替换实现验证边界是否干净。
学习目标
- 区分状态机需要的业务能力与引擎提供的具体对象。
- 用端口与适配器隔离动画、角色、节点、输入和时间系统。
- 通过替换适配器验证状态逻辑是否还能独立运行。
先划出状态机真正需要的能力
状态机不需要知道“这是 Unity 的 Animator”或“这是 Godot 的 Node”,它只需要知道当前要播放什么动作、读取什么输入、如何推动角色,以及本帧过去了多久。边界应从这些稳定语义出发,而不是照搬引擎类名。
| 平台依赖 | 状态真正关心的能力 | 不应跨过边界的细节 |
|---|---|---|
| Animator | 播放某个语义动画 | trigger、layer、hash |
| Actor / Character | 设置移动意图或速度 | 具体组件树、物理节点引用 |
| Node / GameObject | 访问受控能力 | 节点查找、场景路径 |
| 输入系统 | 读取抽象动作 | 键位、设备 ID、输入后端 |
| 时间系统 | 获取帧时间 | 全局单例、引擎静态 API |

把平台对象收进适配层
下面的示例让 MoveState 只依赖 StatePorts。示例里的 Animator、Actor、Input 和 Time 模拟引擎对象,但它们只会出现在 EngineAdapter 中。
interface StatePorts {
playAnimation(name: "idle" | "run"): void;
readMoveX(): number;
setHorizontalVelocity(value: number): void;
deltaSeconds(): number;
}
class MoveState {
constructor(private readonly ports: StatePorts) {}
update(): void {
const x = this.ports.readMoveX();
// 状态只表达游戏语义,不知道输入设备或动画控制器细节。
this.ports.playAnimation(Math.abs(x) > 0.01 ? "run" : "idle");
this.ports.setHorizontalVelocity(x * 4);
console.log(`dt=${this.ports.deltaSeconds().toFixed(4)}`);
}
}
class Animator {
play(name: string): void {
console.log(`animation=${name}`);
}
}
class Actor {
setVelocityX(value: number): void {
console.log(`velocityX=${value.toFixed(2)}`);
}
}
class Input {
axis(): number {
return 0.5;
}
}
class Time {
readonly delta = 1 / 60;
}
class EngineAdapter implements StatePorts {
constructor(
private readonly animator: Animator,
private readonly actor: Actor,
private readonly input: Input,
private readonly time: Time
) {}
playAnimation(name: "idle" | "run"): void {
this.animator.play(name);
}
readMoveX(): number {
return this.input.axis();
}
setHorizontalVelocity(value: number): void {
this.actor.setVelocityX(value);
}
deltaSeconds(): number {
return this.time.delta;
}
}
const ports = new EngineAdapter(
new Animator(),
new Actor(),
new Input(),
new Time()
);
new MoveState(ports).update();预期输出
animation=run
velocityX=2.00
dt=0.0167真正接入某个引擎时,只替换适配器内部的调用。例如输入适配器可以把“MoveX”动作映射到键盘、手柄或触屏;状态本身不需要知道动作由哪种设备产生。
防止适配层再次泄漏引擎
适配层的目标不是把所有 API 包一层同名方法。如果接口叫 setAnimatorTrigger、getNodeByPath,状态仍然被引擎概念绑住,只是多了一次转发。
更稳妥的命名应围绕游戏意图,例如 playAnimation("run")、readMoveX()、setHorizontalVelocity()。对于节点树和实体查询,优先让适配器返回业务能力或不可变数据,而不是把 Node、GameObject、组件指针继续传回状态。
用可替换性验收边界
检查边界时,可以暂时拿掉真实引擎,给端口放入内存实现。如果状态仍能完成切换判断、冷却计算和移动决策,说明核心逻辑已经与平台解耦;如果测试仍必须创建场景树、动画控制器或输入设备,边界里还有泄漏。
验收时重点看三件事:状态文件是否导入任何引擎命名空间;端口方法是否描述游戏语义而非 API 名称;切换引擎或测试后端时是否只需替换适配器。做到这三点,状态机才能保持稳定,而平台变化被限制在一圈可控的边界内。