游戏客户端架构 / 系统课时
给控制器定义清晰的数据接口
给控制器定义清晰的数据接口
角色控制器经常因为输入、速度、接地和跳跃状态混在一起而变得难以维护。本课将这些信息整理成明确的数据接口,使用 Unity C# 建立可测试的控制器数据模型,让输入系统、移动逻辑、物理检测和动画系统能够各自读取需要的信息。
学习目标
- 区分控制器配置、外部输入和运行时状态,明确各自的读写职责。
- 定义移动方向、速度、接地状态和跳跃请求的数据接口。
- 使用简单测试验证输入归一化、状态更新和跳跃请求消费行为。
控制器为什么需要数据边界
假设一个角色同时支持键盘、手柄、跳跃、冲刺和动画切换。如果所有模块都直接修改速度与接地标记,就容易出现动画认为角色落地、物理模块却认为角色在空中的问题。
解决方式是将控制器数据划分为三类:
| 数据类别 | 典型字段 | 写入者 | 使用者 |
|---|---|---|---|
| 配置数据 | 最大速度、加速度、跳跃速度 | 初始化或配置系统 | 移动计算模块 |
| 输入意图 | 二维移动输入、跳跃请求 | 输入适配层 | 控制器逻辑 |
| 运行时状态 | 实际速度、移动方向、是否接地 | 控制器或物理检测层 | 动画、音效、调试模块 |
这里最重要的是明确谁有权修改数据。例如,动画系统可以读取实际速度来切换跑步动画,但不应该为了播放落地动画而直接把 IsGrounded 改成 true。

定义移动配置与输入意图
以下示例使用普通 C# 类编写,不依赖 MonoBehaviour 生命周期,因此可以单独测试。二维输入约定为:X 表示左右,Y 表示前后;速度采用 Unity 的 Vector3 世界空间向量。
新建 CharacterControllerData.cs:
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 编辑,并不能阻止所有代码赋值产生负数。
定义运行时状态与更新入口
运行时状态不应对外暴露可随意修改的字段。下面将状态修改集中在少量方法中,并为跳跃请求提供一次性消费接口。
将以下代码继续添加到同一个文件:
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。运行场景后,脚本会模拟一次斜向移动输入和跳跃请求。
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 中消息前缀可能包含额外上下文):
方向长度: 1.00
实际速度: 2.83
接地: True
首次消费跳跃: True
再次消费跳跃: False验证重点不是角色是否真的移动,而是数据契约是否成立:斜向输入已限制为单位长度,实际速度与期望方向相互独立,跳跃请求只能成功消费一次。
这里的 MoveDirection 仍然是局部输入约定对应的水平向量。采用相机相对移动时,应由控制器将它转换为世界空间方向,并明确坐标空间;不要让调用方猜测接口中方向向量的含义。
如何把接口接入实际控制器
接入 Unity CharacterController 或 Rigidbody 时,可以按照下面的职责执行:
- 在
Update中收集输入并调用SetInput,保留本帧玩家意图。 - 使用物理检测结果更新
IsGrounded,再结合配置与状态判断能否跳跃。 - 通过
ConsumeJumpRequest读取一次性跳跃请求,计算本次运动所需速度。 - 将运动结果同步到
Velocity,由动画、音效和调试模块只读访问。
具体运动计算时机取决于实现方式:使用 Rigidbody 的物理控制通常在 FixedUpdate 中完成;使用 CharacterController.Move 时则应建立统一的更新时序,避免在不同生命周期中重复应用位移。
还需要区分移动命令与物理结果。例如发生墙体碰撞后,期望速度可能仍朝向墙面,实际位移却被阻挡。若界面需要显示真实运动速度,应基于最终位移或物理组件报告的速度更新,而非直接复制输入计算出的目标速度。
一份稳定的数据接口,应让输入模块表达意图、控制器负责决策、物理层提供事实、表现层读取结果。后续增加冲刺、攀爬或网络同步时,优先扩展清晰的数据契约,而不是允许更多模块直接修改同一组状态。