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

让状态不直接依赖引擎对象

让状态不直接依赖引擎对象

状态对象一旦直接持有 Character、Animator、Node 或 Actor,状态逻辑就会和具体引擎生命周期、测试环境绑死。更稳妥的做法是让状态只依赖小而明确的能力接口,再由适配层持有真正的引擎对象并完成调用翻译。

学习目标

  • 识别状态类直接依赖引擎对象带来的耦合问题。
  • 用端口接口把状态逻辑与引擎 API 隔离。
  • 明确适配层应该承担和不应该承担的职责。

依赖方向要反过来

核心状态逻辑应该定义自己需要的能力,例如“读取是否着地”“设置垂直速度”“播放动作”,而不是接收一个功能庞大的引擎角色对象。这样依赖方向就变成“状态 → 抽象端口 ← 引擎适配器”。

状态机与引擎对象之间的适配层

如果状态接口里直接返回 Transform、Node 或 Actor,只是把引擎类型换了个入口,隔离并没有真正发生。端口应暴露游戏逻辑真正需要的最小能力。

用端口切断引擎类型

下面的完整 C# 示例不依赖任何游戏引擎。JumpState 只认识 ICharacterPort,测试时用 FakeCharacterAdapter;接入真实引擎时,只需再实现一个适配器并在内部调用引擎 API。

csharp
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();
    }
}

预期输出

text
velocityY=8
animation=jump

真实项目中,Unity 适配器可以在内部持有角色控制器与动画组件,Godot 适配器可以持有角色节点与动画播放器,Unreal 适配器可以持有角色或相关组件。状态类不需要知道这些对象的具体类型。

适配层只负责翻译

适配层的职责是把稳定能力映射到引擎 API,例如把 PlayAnimation("jump") 翻译为当前引擎的动画播放调用,把 IsGrounded 翻译为碰撞或移动组件的查询结果。

业务规则不要反向塞进适配器。像“空中不能二段跳”“受击时禁止攻击”这类判断应留在状态或领域规则中,否则切换引擎时会把规则一起搬走,测试也会重新依赖运行时环境。

防止引擎依赖再次泄漏

常见泄漏方式包括:接口参数直接使用引擎向量类型、事件回调把引擎对象原样传给状态、状态内部查询场景树或组件容器。出现这些情况时,应把值转换成普通数据或领域类型后再跨边界。

最终边界很简单:状态决定规则,适配器执行引擎动作。只要状态可以在普通单元测试里用假实现运行,而不需要启动场景、Actor 或节点树,就说明这层隔离基本成立。

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

目录与阅读设置

阅读设置

17

记录一个想法

让状态不直接依赖引擎对象

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

登录哪都通