游戏客户端架构 / 系统课时
让状态不直接依赖引擎对象
让状态不直接依赖引擎对象
状态对象一旦直接持有 Character、Animator、Node 或 Actor,状态逻辑就会和具体引擎生命周期、测试环境绑死。更稳妥的做法是让状态只依赖小而明确的能力接口,再由适配层持有真正的引擎对象并完成调用翻译。
学习目标
- 识别状态类直接依赖引擎对象带来的耦合问题。
- 用端口接口把状态逻辑与引擎 API 隔离。
- 明确适配层应该承担和不应该承担的职责。
依赖方向要反过来
核心状态逻辑应该定义自己需要的能力,例如“读取是否着地”“设置垂直速度”“播放动作”,而不是接收一个功能庞大的引擎角色对象。这样依赖方向就变成“状态 → 抽象端口 ← 引擎适配器”。

如果状态接口里直接返回 Transform、Node 或 Actor,只是把引擎类型换了个入口,隔离并没有真正发生。端口应暴露游戏逻辑真正需要的最小能力。
用端口切断引擎类型
下面的完整 C# 示例不依赖任何游戏引擎。JumpState 只认识 ICharacterPort,测试时用 FakeCharacterAdapter;接入真实引擎时,只需再实现一个适配器并在内部调用引擎 API。
using System;
public interface ICharacterPort
{
bool IsGrounded { get; }
void SetVerticalVelocity(float value);
void PlayAnimation(string name);
}
public sealed class JumpState
{
private readonly ICharacterPort character;
public JumpState(ICharacterPort character)
{
this.character = character;
}
public void Enter()
{
// 规则判断留在状态层,引擎调用通过端口完成。
if (!character.IsGrounded)
{
return;
}
character.SetVerticalVelocity(8f);
character.PlayAnimation("jump");
}
}
public sealed class FakeCharacterAdapter : ICharacterPort
{
public bool IsGrounded => true;
public void SetVerticalVelocity(float value)
{
Console.WriteLine($"velocityY={value:0}");
}
public void PlayAnimation(string name)
{
Console.WriteLine($"animation={name}");
}
}
public static class Program
{
public static void Main()
{
var state = new JumpState(new FakeCharacterAdapter());
state.Enter();
}
}预期输出
velocityY=8
animation=jump真实项目中,Unity 适配器可以在内部持有角色控制器与动画组件,Godot 适配器可以持有角色节点与动画播放器,Unreal 适配器可以持有角色或相关组件。状态类不需要知道这些对象的具体类型。
适配层只负责翻译
适配层的职责是把稳定能力映射到引擎 API,例如把 PlayAnimation("jump") 翻译为当前引擎的动画播放调用,把 IsGrounded 翻译为碰撞或移动组件的查询结果。
业务规则不要反向塞进适配器。像“空中不能二段跳”“受击时禁止攻击”这类判断应留在状态或领域规则中,否则切换引擎时会把规则一起搬走,测试也会重新依赖运行时环境。
防止引擎依赖再次泄漏
常见泄漏方式包括:接口参数直接使用引擎向量类型、事件回调把引擎对象原样传给状态、状态内部查询场景树或组件容器。出现这些情况时,应把值转换成普通数据或领域类型后再跨边界。
最终边界很简单:状态决定规则,适配器执行引擎动作。只要状态可以在普通单元测试里用假实现运行,而不需要启动场景、Actor 或节点树,就说明这层隔离基本成立。