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

给控制器定义清晰的数据接口

给控制器定义清晰的数据接口

角色控制器经常因为输入、速度、接地和跳跃状态混在一起而变得难以维护。本课将这些信息整理成明确的数据接口,使用 Unity C# 建立可测试的控制器数据模型,让输入系统、移动逻辑、物理检测和动画系统能够各自读取需要的信息。

学习目标

  • 区分控制器配置、外部输入和运行时状态,明确各自的读写职责。
  • 定义移动方向、速度、接地状态和跳跃请求的数据接口。
  • 使用简单测试验证输入归一化、状态更新和跳跃请求消费行为。

控制器为什么需要数据边界

假设一个角色同时支持键盘、手柄、跳跃、冲刺和动画切换。如果所有模块都直接修改速度与接地标记,就容易出现动画认为角色落地、物理模块却认为角色在空中的问题。

解决方式是将控制器数据划分为三类:

数据类别 典型字段 写入者 使用者
配置数据 最大速度、加速度、跳跃速度 初始化或配置系统 移动计算模块
输入意图 二维移动输入、跳跃请求 输入适配层 控制器逻辑
运行时状态 实际速度、移动方向、是否接地 控制器或物理检测层 动画、音效、调试模块

这里最重要的是明确谁有权修改数据。例如,动画系统可以读取实际速度来切换跑步动画,但不应该为了播放落地动画而直接把 IsGrounded 改成 true。

角色控制器数据接口的读写关系

定义移动配置与输入意图

以下示例使用普通 C# 类编写,不依赖 MonoBehaviour 生命周期,因此可以单独测试。二维输入约定为:X 表示左右,Y 表示前后;速度采用 Unity 的 Vector3 世界空间向量。

新建 CharacterControllerData.cs:

csharp
using UnityEngine;

[System.Serializable]
public class CharacterMotionSettings
{
    [Min(0f)] public float MaxSpeed = 5f;
    [Min(0f)] public float Acceleration = 20f;
    [Min(0f)] public float JumpSpeed = 6f;
}

public struct CharacterInputIntent
{
    public Vector2 Move { get; }
    public bool JumpRequested { get; }

    public CharacterInputIntent(Vector2 move, bool jumpRequested)
    {
        // 限制最大输入幅度,避免斜向移动天然更快。
        Move = Vector2.ClampMagnitude(move, 1f);
        JumpRequested = jumpRequested;
    }
}

CharacterMotionSettings 保存设计参数,CharacterInputIntent 表示某次采样获得的玩家意图。它们都不负责判断角色最终能否移动或跳跃。

配置类使用公共字段便于 Unity 序列化和 Inspector 调整,但实际项目应在配置加载时额外校验范围。Min 特性主要约束 Inspector 编辑,并不能阻止所有代码赋值产生负数。

定义运行时状态与更新入口

运行时状态不应对外暴露可随意修改的字段。下面将状态修改集中在少量方法中,并为跳跃请求提供一次性消费接口。

将以下代码继续添加到同一个文件:

csharp
public sealed class CharacterMotionState
{
    public Vector3 Velocity { get; private set; }
    public Vector3 MoveDirection { get; private set; }
    public bool IsGrounded { get; private set; }
    public bool HasJumpRequest { get; private set; }

    public void SetInput(CharacterInputIntent input)
    {
        // 输入仅表达意图,不直接修改物理速度。
        MoveDirection = new Vector3(input.Move.x, 0f, input.Move.y);
        HasJumpRequest |= input.JumpRequested;
    }

    public void SetGrounded(bool grounded)
    {
        IsGrounded = grounded;
    }

    public void SetVelocity(Vector3 velocity)
    {
        Velocity = velocity;
    }

    public bool ConsumeJumpRequest()
    {
        bool requested = HasJumpRequest;
        HasJumpRequest = false;
        return requested;
    }
}

Velocity 是实际运动速度,MoveDirection 是期望方向,两者不能混用。角色松开方向键时,期望方向可以立即变成零,但实际速度可能由于惯性或加速度限制而逐渐减小。

HasJumpRequest 使用累积方式保存尚未处理的跳跃请求,避免输入采样与物理更新不在同一帧时立即丢失请求。不过该简单实现没有过期机制,长时间未消费的请求可能导致延迟跳跃。正式控制器可以进一步引入请求时间戳和输入缓冲窗口。

SetGrounded 与 SetVelocity 虽然是公共方法,但约定只能由控制器协调逻辑调用。更严格的项目可以通过程序集边界或内部接口限制写入权限。

验证接口的行为

创建 CharacterDataExample.cs,将脚本挂到场景中的任意 GameObject。运行场景后,脚本会模拟一次斜向移动输入和跳跃请求。

csharp
using UnityEngine;

public class CharacterDataExample : MonoBehaviour
{
    private void Start()
    {
        var state = new CharacterMotionState();
        var input = new CharacterInputIntent(new Vector2(1f, 1f), true);

        state.SetInput(input);
        state.SetGrounded(true);
        state.SetVelocity(new Vector3(2f, 0f, 2f));

        Debug.Log($"方向长度: {state.MoveDirection.magnitude:F2}");
        Debug.Log($"实际速度: {state.Velocity.magnitude:F2}");
        Debug.Log($"接地: {state.IsGrounded}");
        Debug.Log($"首次消费跳跃: {state.ConsumeJumpRequest()}");
        Debug.Log($"再次消费跳跃: {state.ConsumeJumpRequest()}");
    }
}

预期输出(Unity Console 中消息前缀可能包含额外上下文):

text
方向长度: 1.00
实际速度: 2.83
接地: True
首次消费跳跃: True
再次消费跳跃: False

验证重点不是角色是否真的移动,而是数据契约是否成立:斜向输入已限制为单位长度,实际速度与期望方向相互独立,跳跃请求只能成功消费一次。

这里的 MoveDirection 仍然是局部输入约定对应的水平向量。采用相机相对移动时,应由控制器将它转换为世界空间方向,并明确坐标空间;不要让调用方猜测接口中方向向量的含义。

如何把接口接入实际控制器

接入 Unity CharacterController 或 Rigidbody 时,可以按照下面的职责执行:

  1. 在 Update 中收集输入并调用 SetInput,保留本帧玩家意图。
  2. 使用物理检测结果更新 IsGrounded,再结合配置与状态判断能否跳跃。
  3. 通过 ConsumeJumpRequest 读取一次性跳跃请求,计算本次运动所需速度。
  4. 将运动结果同步到 Velocity,由动画、音效和调试模块只读访问。

具体运动计算时机取决于实现方式:使用 Rigidbody 的物理控制通常在 FixedUpdate 中完成;使用 CharacterController.Move 时则应建立统一的更新时序,避免在不同生命周期中重复应用位移。

还需要区分移动命令与物理结果。例如发生墙体碰撞后,期望速度可能仍朝向墙面,实际位移却被阻挡。若界面需要显示真实运动速度,应基于最终位移或物理组件报告的速度更新,而非直接复制输入计算出的目标速度。

一份稳定的数据接口,应让输入模块表达意图、控制器负责决策、物理层提供事实、表现层读取结果。后续增加冲刺、攀爬或网络同步时,优先扩展清晰的数据契约,而不是允许更多模块直接修改同一组状态。

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

目录与阅读设置

阅读设置

17

记录一个想法

给控制器定义清晰的数据接口

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

登录哪都通