游戏客户端架构 / 系统课时

把引擎依赖压缩到适配层

把引擎依赖压缩到适配层

当状态直接拿着 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 中。

ts
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();

预期输出

text
animation=run
velocityX=2.00
dt=0.0167

真正接入某个引擎时,只替换适配器内部的调用。例如输入适配器可以把“MoveX”动作映射到键盘、手柄或触屏;状态本身不需要知道动作由哪种设备产生。

防止适配层再次泄漏引擎

适配层的目标不是把所有 API 包一层同名方法。如果接口叫 setAnimatorTrigger、getNodeByPath,状态仍然被引擎概念绑住,只是多了一次转发。

更稳妥的命名应围绕游戏意图,例如 playAnimation("run")、readMoveX()、setHorizontalVelocity()。对于节点树和实体查询,优先让适配器返回业务能力或不可变数据,而不是把 Node、GameObject、组件指针继续传回状态。

用可替换性验收边界

检查边界时,可以暂时拿掉真实引擎,给端口放入内存实现。如果状态仍能完成切换判断、冷却计算和移动决策,说明核心逻辑已经与平台解耦;如果测试仍必须创建场景树、动画控制器或输入设备,边界里还有泄漏。

验收时重点看三件事:状态文件是否导入任何引擎命名空间;端口方法是否描述游戏语义而非 API 名称;切换引擎或测试后端时是否只需替换适配器。做到这三点,状态机才能保持稳定,而平台变化被限制在一圈可控的边界内。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

把引擎依赖压缩到适配层

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通