游戏引擎 / 系统课时
配置 Input Actions 输入映射
配置 Input Actions 输入映射
本课将为第三人称动作角色建立一套同时支持键鼠与手柄的输入映射。完成后,WASD 和左摇杆都能产生 Move 向量,鼠标和右摇杆都能产生 Look 向量,跳跃、攻击、交互也能通过统一的 Action 名称读取,并在运行时验证设备切换是否正确。
学习目标
- 创建包含 Move、Look、Jump、Attack、Interact 的 Input Actions 资源,正确设置动作类型和设备绑定。
- 配置 Keyboard&Mouse、Gamepad 控制方案,并将 Gameplay Action Map 接入 PlayerInput。
- 使用 C# 验证连续输入、按键边沿和不同设备的统一游戏语义。
检查输入系统并创建资源
以下以 Unity 6.3 和 Input System 1.17 的编辑器界面为例。Input System 是独立软件包,项目实际安装版本以 Package Manager 为准;其他兼容的 1.x 版本可能存在少量界面名称或布局差异。
- 打开
Window > Package Manager,在包来源中选择Unity Registry,搜索Input System。未安装时点击Install,已安装则确认版本及依赖状态。 - 打开
Edit > Project Settings > Player > Other Settings,将Active Input Handling设置为Input System Package (New)。如果已有旧输入代码必须兼容,可以暂时选Both。出现重启提示时确认并重新打开编辑器。 - 在 Project 窗口的
Assets下新建Input文件夹,执行Assets > Create > Input Actions,把资源命名为PlayerControls.inputactions。 - 双击资源打开 Input Actions Editor,在左侧
Action Maps面板新建Gameplay。如果使用默认模板创建,删除或重命名不需要的动作,避免同时保留两套同名语义。
Input Actions 资源负责描述输入规则,不负责角色实际移动。一个 Action Map 表示一种输入上下文,例如 Gameplay、UI 或 Vehicle。当前关卡先只启用 Gameplay,后续打开菜单时再考虑切换到 UI。
建立五个游戏动作和设备绑定
在 Gameplay 中添加以下五个 Action。Move 和 Look 是持续变化的二维值,应使用 Value;其余三个是离散触发操作,使用 Button。
| Action | Action Type / Control Type | 键鼠绑定 | 手柄绑定 |
|---|---|---|---|
| Move | Value / Vector2 | WASD,2D Vector Composite | <Gamepad>/leftStick |
| Look | Value / Vector2 | <Mouse>/delta |
<Gamepad>/rightStick |
| Jump | Button | <Keyboard>/space |
<Gamepad>/buttonSouth |
| Attack | Button | <Mouse>/leftButton |
<Gamepad>/rightTrigger |
| Interact | Button | <Keyboard>/e |
<Gamepad>/buttonWest |
其中 buttonSouth 表示手柄下方的主要面键,并不依赖某个品牌的按钮字母。右扳机虽然提供模拟量,也可以绑定到 Button Action,由 Input System 按按钮按下阈值判断触发。
配置 Move 的二维复合绑定
- 选中
Move,在属性面板将Action Type设置为Value、Control Type设置为Vector2。 - 点击该 Action 的添加按钮,选择
2D Vector Composite,部分版本显示为Add Up/Down/Left/Right Composite。 - 将四个子绑定分别设置为
Up = <Keyboard>/w、Down = <Keyboard>/s、Left = <Keyboard>/a、Right = <Keyboard>/d。 - Composite 的模式保持
Digital Normalized,避免同时按下 W 和 D 时得到长度约为 1.414 的移动输入。 - 再为 Move 添加普通 Binding,路径设为
<Gamepad>/leftStick。摇杆直接提供二维值,不需要再套一层 2D Vector Composite。
数字方向采用归一化模式时,W 对应 (0, 1),D 对应 (1, 0),W+D 对应约 (0.707, 0.707),松开后恢复 (0, 0)。实际角色速度由后续移动逻辑决定,不应在绑定阶段把数值直接当成世界坐标位移。

配置 Look 和离散动作
Look 添加两条普通 Binding:<Mouse>/delta 和 <Gamepad>/rightStick。两者虽然都返回 Vector2,但物理含义不同:鼠标 Delta 通常表示当前输入更新周期内的位移量,右摇杆表示持续偏转方向和幅度。后续实现镜头旋转时,应分别处理灵敏度与时间缩放,不能直接给两种输入套用完全相同的每秒旋转公式。
Jump、Attack、Interact 分别添加表中的键鼠与手柄绑定,不需要建立三个不同设备专用的动作。这里暂时保留默认按钮交互行为,不添加 Hold、Tap 等 Interaction;持续按住 Jump 不应反复产生新的跳跃请求。
完成后保存 Input Actions 资源。检查每个 Action 的 Binding 列表,确保没有遗留空路径和错误的设备类型。
设置控制方案并连接 PlayerInput
Control Scheme 用来描述一组可用设备及其绑定集合。建议建立两个控制方案:
| Control Scheme | Required Devices | 绑定分组 |
|---|---|---|
| Keyboard&Mouse | Keyboard、Mouse | 键盘与鼠标的 Binding |
| Gamepad | Gamepad | 所有手柄 Binding |
具体操作如下:
- 在 Input Actions Editor 左上角打开 Control Schemes 下拉菜单,添加
Keyboard&Mouse,在设备列表中把Keyboard和Mouse都设为必需设备。 - 再添加
Gamepad,要求Gamepad设备。编辑各条 Binding 的属性,将键鼠绑定分配到Keyboard&Mouse,手柄绑定分配到Gamepad。2D Vector Composite 的四个按键子绑定也要归入键鼠方案。 - 选中场景中的玩家对象,例如
Player,在 Inspector 中点击Add Component,搜索并添加Player Input。 - 将
Actions选择为使用 Actions Asset,并指定PlayerControls.inputactions;设置Default Map = Gameplay。 Default Scheme可以优先选择Keyboard&Mouse,它只是初始尝试的方案,不表示永久禁用手柄。将Behavior设为Invoke CSharp Events,方便后续使用 C# 事件;下面的验证代码直接轮询 Action,不依赖通知模式。
注意,Unity 6.3 对应版本的 Inspector 常使用 Default Map 和 Default Scheme,部分旧版文档或界面则称为 Default Action Map、Default Control Scheme,它们对应相同的配置概念。
在单个 PlayerInput 的本地单玩家场景中,PlayerInput 会根据可用设备和输入活动选择匹配的 Control Scheme,并自动管理当前 Action Map 的启用状态。不要再给同一套动作额外调用全局启用逻辑,否则会让输入归属和状态判断变得混乱。
使用 C# 验证统一的输入语义
创建 Assets/Scripts/InputActionProbe.cs,将以下完整脚本挂到拥有 PlayerInput 的同一个玩家对象上。脚本只读取动作并打印诊断信息,不移动角色,也不旋转摄像机,因此可以先独立验证输入资源是否正确。
using UnityEngine;
using UnityEngine.InputSystem;
[RequireComponent(typeof(PlayerInput))]
public sealed class InputActionProbe : MonoBehaviour
{
private PlayerInput playerInput;
private InputAction move, look, jump, attack, interact;
private float nextReportTime;
private void Start()
{
// 从当前玩家自己的 Actions 实例获取动作,避免绕过设备配对。
playerInput = GetComponent<PlayerInput>();
var map = playerInput.actions.FindActionMap("Gameplay", true);
move = map.FindAction("Move", true);
look = map.FindAction("Look", true);
jump = map.FindAction("Jump", true);
attack = map.FindAction("Attack", true);
interact = map.FindAction("Interact", true);
Debug.Log("Input map=" + playerInput.currentActionMap?.name);
}
private void Update()
{
Vector2 movement = move.ReadValue<Vector2>();
Vector2 cameraInput = look.ReadValue<Vector2>();
// 连续值每0.25秒最多打印一次,避免Console被逐帧日志淹没。
if (Time.unscaledTime >= nextReportTime &&
(movement.sqrMagnitude > 0.01f || cameraInput.sqrMagnitude > 0.01f))
{
Debug.Log($"Move={movement}, Look={cameraInput}");
nextReportTime = Time.unscaledTime + 0.25f;
}
// 按键只在按下边沿触发,长按不会逐帧重复打印。
if (jump.WasPressedThisFrame()) Debug.Log("Jump");
if (attack.WasPressedThisFrame()) Debug.Log("Attack");
if (interact.WasPressedThisFrame()) Debug.Log("Interact");
}
}进入 Play 模式,点击 Game 视图以确保窗口获得键鼠焦点。按顺序执行 W、Space、鼠标左键和 E,并打开 Window > General > Console 查看日志。
预期输出示例:
Input map=Gameplay
Move=(0.00, 1.00), Look=(0.00, 0.00)
Jump
Attack
Interact第一行确认 Gameplay 已启用。Move 和 Look 的数值会随设备、操作幅度及采样时刻变化,日志也可能包含 Unity Console 自己显示的时间或对象信息。静止时没有连续值日志属于正常行为。
随后接入手柄,推动左摇杆、右摇杆,再按下方主要面键、右扳机和西侧面键。Console 应分别出现 Move、Look、Jump、Attack、Interact 对应的日志,其中 Jump、Attack、Interact 的文本应与键鼠触发时相同。
这里使用 playerInput.actions 而不是 InputSystem.actions,因为 PlayerInput 可能为每名玩家维护独立的 Action 实例和设备配对信息。对于本课的单玩家验证,也无需手动调用 map.Enable();Default Map = Gameplay 已由 PlayerInput 负责激活。
验收设备切换与排查无响应
运行时选中 Player 对象,在 PlayerInput 的 Debug 区域查看当前 Control Scheme、用户编号和已配对设备。先使用键鼠,再操作手柄,检查单玩家配置是否能够识别对应方案。
建议按以下条件逐项验收:
- 按 W 得到正 Y 的 Move,按 D 得到正 X 的 Move;W+D 的向量长度不超过 1,松开恢复零值。
- 移动鼠标和推动右摇杆都能产生 Look 数值;没有实际输入时不应出现持续的异常大值。
- Space 与手柄下方面键均输出 Jump;鼠标左键与右扳机均输出 Attack;E 与手柄西侧面键均输出 Interact。
- 连续按住 Jump 不应每帧重复输出 Jump;松开再按应再次触发。
- 在只有一个 PlayerInput、控制方案完整的测试环境中,键鼠与手柄切换后,五个 Action 仍可用相同名称读取。
如果输入没有响应,按下面的顺序定位,比直接修改角色移动代码更有效:
| 故障现象 | 优先检查 | 修正方法 |
|---|---|---|
| 所有输入都没反应 | Active Input Handling、Default Map | 启用新输入系统,确认 Gameplay 已激活 |
| WASD 没反应但摇杆正常 | 2D Vector Composite、绑定分组 | 检查四个子绑定路径及 Keyboard&Mouse 方案 |
| 键鼠正常但手柄无响应 | 设备连接、Gamepad Scheme、PlayerInput Debug | 确认手柄被识别且分配给该玩家 |
| 向量读取类型异常 | Action Type、Control Type | Move 和 Look 改为 Value / Vector2 |
| 有输入但未触发脚本 | 对象是否激活、脚本编译状态、Action 名称 | 确认 Probe 与 PlayerInput 同对象,名称大小写一致 |
验证完成后可以暂时保留 InputActionProbe 作为开发诊断组件,正式运行时禁用或移除它,避免 Console 被连续输入日志填满。此时 PlayerControls.inputactions、Gameplay Action Map 和 PlayerInput 已经组成一套可供角色移动、跟随镜头及战斗交互共同使用的输入入口。