游戏客户端架构 / 系统课时
用移动测试场景验证控制器
用移动测试场景验证控制器
角色在平地上移动正常,不代表控制器已经可靠。墙角可能卡住,坡道可能产生滑动,台阶可能无法跨越,移动平台还可能让角色意外漂移。本课使用 Unity 2022.3 LTS 和 CharacterController 搭建六类测试区域,建立可重复执行、可记录结果的移动验证基线。
学习目标
- 搭建覆盖平地、墙角、坡道、台阶、窄门和移动平台的测试场景。
- 编写最小可运行的测试控制器,并理解关键碰撞参数。
- 使用固定测试步骤、观察指标和回归记录定位移动异常。
规划测试场景与验收条件
创建一个名为 MovementTest 的 Unity 3D 场景,约定世界坐标 Y 轴向上,地面位于 Y=0 附近,所有静态障碍均配置有效 Collider。场景采用独立测试区,避免一次移动同时触发多个问题。
| 测试区域 | 建议布置 | 重点验证 |
|---|---|---|
| 平地 | 12m × 12m 水平地面 | 匀速、斜向输入、停止响应 |
| 墙角 | 两面垂直墙体 | 碰撞阻挡、沿墙滑动、角落卡滞 |
| 坡道 | 20°、40°、50° 三段坡面 | 上坡能力、坡度限制、下坡接地 |
| 台阶 | 0.15m、0.30m、0.45m 高度 | 自动跨越高度与阻挡边界 |
| 窄门 | 0.9m、1.2m 两种净宽 | 胶囊碰撞体通行和侧面刮碰 |
| 移动平台 | 水平往返移动 3m | 角色承载、跟随与离开平台 |
这些尺寸是测试输入,而不是所有游戏都应采用的通用标准。实际验收需要结合角色碰撞体尺寸、移动速度及设计允许的坡度重新确定。

创建场景与配置角色碰撞体
在 Unity 中创建 Plane 或 Cube 作为平地,其他障碍使用 Cube 组合。将坡道立方体绕 X 轴旋转到指定角度,并使用其顶部表面作为行走面。每个区域保留独立出生点,便于重复试验。
创建名为 Player 的空对象,添加 CharacterController,建议初始配置如下:
| 参数 | 初始值 | 验证作用 |
|---|---|---|
| Height | 2 | 胶囊体总高度 |
| Radius | 0.4 | 水平占用空间 |
| Center | (0, 1, 0) | 胶囊体相对对象原点的位置 |
| Slope Limit | 45 | 最大允许爬坡角度 |
| Step Offset | 0.3 | 可尝试跨越的台阶高度 |
| Skin Width | 0.04 | 接触碰撞时允许的微小穿入容差 |
| Min Move Distance | 0 | 不忽略微小移动 |
将 Player 原点放在地面高度,使胶囊体底部接近地面。不要额外给角色添加用于移动的非运动学 Rigidbody;这里使用 CharacterController 自身处理移动碰撞。
坡度限制与台阶高度并非保证通行的绝对阈值。碰撞形状、接近方向、角色速度和几何边缘都可能影响实际结果。窄门测试还应注意角色半径对应的约 0.8m 胶囊体直径,以及碰撞余量。
实现可观测的基础移动控制器
创建 TestCharacterMover.cs,挂载到 Player。脚本使用 Unity 传统输入管理器的 Horizontal 和 Vertical 轴,调用 CharacterController.Move 执行移动,并主动施加重力。使用此脚本前,确认项目的 Active Input Handling 支持 Input Manager;如果项目只启用新 Input System,需要改用项目现有的输入适配层。
using UnityEngine;
[RequireComponent(typeof(CharacterController))]
public class TestCharacterMover : MonoBehaviour
{
[SerializeField] private float moveSpeed = 4f;
[SerializeField] private float gravity = -20f;
private CharacterController controller;
private float verticalSpeed;
private void Awake()
{
controller = GetComponent<CharacterController>();
}
private void Update()
{
// 归一化二维输入,避免斜向移动比直线更快。
Vector2 input = new Vector2(
Input.GetAxisRaw("Horizontal"),
Input.GetAxisRaw("Vertical"));
input = Vector2.ClampMagnitude(input, 1f);
Vector3 horizontal = new Vector3(input.x, 0f, input.y)
* moveSpeed;
// 接地时保留轻微向下速度,减少离地抖动。
if (controller.isGrounded && verticalSpeed < 0f)
verticalSpeed = -2f;
verticalSpeed += gravity * Time.deltaTime;
Vector3 motion = horizontal + Vector3.up * verticalSpeed;
CollisionFlags flags = controller.Move(motion * Time.deltaTime);
if ((flags & CollisionFlags.Above) != 0 && verticalSpeed > 0f)
verticalSpeed = 0f;
Debug.Log($"Grounded={controller.isGrounded}, " +
$"Flags={flags}, Position={transform.position:F2}");
}
}预期结果:进入 Play 模式后,使用 WASD 或方向键可以在世界 XZ 平面移动;靠近墙体时无法直接穿墙,沿墙输入可能产生滑动。Console 会持续输出接地状态、碰撞标志和坐标,例如以下示意,具体数值取决于场景位置与当前帧:
Grounded=True, Flags=Below, Position=(0.00, 0.00, 1.20)CollisionFlags 是本次 Move 返回的碰撞方向信息,可能包含 Sides、Above、Below 或它们的组合。isGrounded 表示最近一次 Move 是否接地,不能直接当作完整地面检测方案。此脚本是测试基线,不包含跳跃、角色朝向旋转和移动平台跟随功能。
按固定动作验证六类地形
测试前统一角色初始坐标、朝向、参数和输入方式。建议每个测试执行三次,并分别记录冷启动、连续移动以及停止后重新移动的表现。
- 平地:沿 X 轴移动约 3 秒,再同时按下两个方向键。检查直线与斜向速度是否符合预期,并确认松开按键后水平移动立即停止。
- 墙角:正面靠墙,再沿墙斜向移动,最后向直角夹角持续输入。检查是否穿透、抖动、卡住或异常弹开。
- 坡道:分别从坡底向上和坡顶向下通过 20°、40°、50° 坡面。记录能否上坡、何时失去接地,以及是否出现反常的爬升或下滑。
- 台阶:从正面接近 0.15m、0.30m、0.45m 台阶,重复慢速与常规速度输入。区分正常跨越、被阻挡和边缘卡滞。
- 窄门:从门洞中心直行,再从偏左和偏右位置尝试通过。检查碰撞体是否在门框附近被阻挡或产生异常侧移。
- 移动平台:让平台水平往返运动,角色先静止站立,再主动行走并离开平台。记录未输入时角色是否跟随平台、是否滑落以及离开后是否保留异常位移。
移动平台测试必须特别区分控制器现有能力和目标产品需求:CharacterController.Move 不会自动提供完整的平台承载、位移继承和接触速度传递。本课的最小脚本未实现平台跟随,因此站上移动平台后发生相对滑动,并不能直接判定 Unity 的碰撞求解错误,而是明确暴露出尚未实现的功能。
为了让动态平台测试可重复,可以新建 TestMovingPlatform.cs,挂在带 Collider 的平台对象上,不添加 Rigidbody。下例让平台沿世界 X 轴以固定周期往返运动:
using UnityEngine;
public class TestMovingPlatform : MonoBehaviour
{
[SerializeField] private float distance = 3f;
[SerializeField] private float frequency = 0.2f;
private Vector3 origin;
private void Start()
{
// 保留平台初始坐标,保证运动围绕固定起点展开。
origin = transform.position;
}
private void Update()
{
// Sin 产生连续往返位移;该脚本仅用于测试运动轨迹。
float offset = Mathf.Sin(Time.time * frequency * Mathf.PI * 2f)
* distance * 0.5f;
transform.position = origin + Vector3.right * offset;
}
}预期结果:平台会以约 5 秒为周期沿 X 轴往返,运动两端间距约为 3m。这里直接改变 Transform,仅适合简单测试;如果正式项目涉及 Rigidbody 物理交互,应使用合适的运动学刚体和物理更新策略,并重新验证接触行为。

记录测试结果并形成回归基线
测试不能只写通过或失败,还应留下复现信息。同一个问题至少记录场景版本、起点、角色参数、输入序列、预期行为、实际行为以及复现次数。
| 用例 | 预期结果 | 失败时优先检查 |
|---|---|---|
| 平地斜向 | 速度不超过单方向设定值 | 输入向量是否限幅 |
| 墙角斜推 | 不穿透且不出现持续抖动 | Collider 缝隙、Skin Width、移动方向 |
| 坡道通行 | 按设计坡度范围通行 | Slope Limit、坡面法线、接地逻辑 |
| 台阶跨越 | 可跨越设计允许的高度 | Step Offset、胶囊尺寸、接近角度 |
| 窄门穿行 | 通过净宽足够的门洞 | Radius、门框 Collider、碰撞余量 |
| 平台承载 | 达到项目约定的跟随行为 | 平台位移继承、接触判定、更新顺序 |
例如,针对墙角抖动,可以在固定起点按住 W+D 三秒,记录 Console 的碰撞标志与角色坐标,并截取 Game 视图。修复后再次执行完全相同的动作,比较是否还有连续的位置震荡。若开启了逐帧 Debug.Log,日志量可能很大,完成诊断后应关闭或限制采样频率。
完成基线后,建议保存固定测试场景及用例记录,并在调整移动速度、Collider 尺寸、Slope Limit、Step Offset 或接地逻辑后重新执行六类测试。这样可以将移动异常从主观手感转化为可复现、可比较、可回归验证的工程问题。