游戏客户端架构 / 系统课时
Unreal的Action与Axis怎么接入
Unreal的Action与Axis怎么接入
Unreal 的输入映射可以把键盘、鼠标和手柄操作转换为游戏动作,但如果角色逻辑直接依赖具体按键或映射名称,跨引擎迁移就会变得困难。本课用 Action、Axis 和统一玩法命令建立适配层,并说明如何扩展到 Enhanced Input。
学习目标
- 区分传统 Action、Axis 与 Enhanced Input 的输入概念。
- 使用 Unreal 输入绑定接收移动与跳跃操作。
- 将输入值转换为独立于引擎设备 API 的玩法命令。
Action 与 Axis 分别负责什么
在 Unreal 传统输入系统中,Action Mapping 通常表示离散操作,例如跳跃、开火、交互;Axis Mapping 表示连续数值,例如前后移动、左右移动和镜头转向。
传统 Axis 映射允许给按键配置缩放值。例如前进键使用 1.0,后退键使用 -1.0,最终形成带方向的输入轴值。
| 输入类型 | 典型动作 | 传递的数据 |
|---|---|---|
| Action | Jump、Interact | 按下与释放事件 |
| Axis | MoveForward | 浮点数轴值 |
| Axis | MoveRight | 浮点数轴值 |
Unreal 5 的 Enhanced Input 则采用 Input Action、Input Mapping Context、Input Modifier 和 Input Trigger 等概念。它的 Input Action 不局限于布尔值,还可以承载一维、二维或三维输入值。
因此,跨引擎抽象不应照搬传统 Action 和 Axis 两个分类,而应按照玩法意图定义命令和数据类型。
从输入映射到玩法命令
建议把设备映射、Unreal 适配器和玩法执行拆成三个边界。传统 Action 或 Enhanced Input 的回调只负责产生输入意图,角色行为由后续业务逻辑决定。

例如,通用层只需要 Move(Vector2) 和 JumpPressed 两种语义。无论输入来自键盘 WASD、手柄摇杆,还是 Enhanced Input 的二维 Action,玩法都接收相同的数据。
移动是持续状态,适合按帧读取并统一处理;跳跃通常是边沿事件,适合在按下时提交一次请求。这两类命令不能简单地使用相同的触发策略。
配置传统 Action 与 Axis 映射
下面使用 Unreal Engine 的传统输入映射演示最小接入方式。该方案适合维护旧项目,也能清楚展示输入映射和业务逻辑之间的接口关系。新建项目通常应优先考虑 Enhanced Input。
在 Edit > Project Settings > Input 中,可以添加 Action 和 Axis 映射。也可以通过配置文件声明映射。
以下是 Config/DefaultInput.ini 的片段示例,依赖传统 PlayerInput 映射机制。若已有同名映射,应检查是否重复,不要无条件追加。
[/Script/Engine.InputSettings]
+ActionMappings=(ActionName="Jump",bShift=False,bCtrl=False,bAlt=False,bCmd=False,Key=SpaceBar)
+AxisMappings=(AxisName="MoveForward",Scale=1.000000,Key=W)
+AxisMappings=(AxisName="MoveForward",Scale=-1.000000,Key=S)
+AxisMappings=(AxisName="MoveRight",Scale=1.000000,Key=D)
+AxisMappings=(AxisName="MoveRight",Scale=-1.000000,Key=A)配置含义很直接:W 和 S 影响前后移动轴,A 和 D 影响左右移动轴,空格键触发 Jump。Axis 同时接受多个绑定的贡献,因此对角移动或多键同时按下时,应在玩法层定义自己的归一化规则。
预期生效行为:角色拥有有效输入接收能力并完成绑定后,按 WASD 会产生相应轴值,空格键会产生一次按下事件。仅写入映射配置不会自动让角色移动。
使用 C++ 适配为统一命令
下面建立一个最小 Pawn,将传统输入 API 转换为引擎内部的通用命令结构。示例不直接实现物理移动,而是通过日志验证输入语义,便于把适配器与玩法行为分离。
创建 C++ Pawn 类 InputBridgePawn。头文件 InputBridgePawn.h 内容如下:
#pragma once
#include "CoreMinimal.h"
#include "GameFramework/Pawn.h"
#include "InputBridgePawn.generated.h"
// 通用命令数据:玩法层不依赖传统映射名称。
struct FGameInputCommand
{
FVector2D Move = FVector2D::ZeroVector;
bool bJumpPressed = false;
};
UCLASS()
class AInputBridgePawn : public APawn
{
GENERATED_BODY()
public:
AInputBridgePawn();
virtual void Tick(float DeltaTime) override;
virtual void SetupPlayerInputComponent(
UInputComponent* PlayerInputComponent) override;
private:
FGameInputCommand CurrentCommand;
void OnMoveForward(float Value);
void OnMoveRight(float Value);
void OnJumpPressed();
};FGameInputCommand 是项目自定义数据结构,而不是 Unreal 内置的通用输入协议。跨引擎迁移时,只需要在其他引擎中实现相同的逻辑字段和行为语义。
实现文件 InputBridgePawn.cpp:
#include "InputBridgePawn.h"
#include "Components/InputComponent.h"
AInputBridgePawn::AInputBridgePawn()
{
PrimaryActorTick.bCanEverTick = true;
AutoPossessPlayer = EAutoReceiveInput::Player0;
}
void AInputBridgePawn::SetupPlayerInputComponent(
UInputComponent* PlayerInputComponent)
{
Super::SetupPlayerInputComponent(PlayerInputComponent);
PlayerInputComponent->BindAxis(
TEXT("MoveForward"), this,
&AInputBridgePawn::OnMoveForward);
PlayerInputComponent->BindAxis(
TEXT("MoveRight"), this,
&AInputBridgePawn::OnMoveRight);
PlayerInputComponent->BindAction(
TEXT("Jump"), IE_Pressed, this,
&AInputBridgePawn::OnJumpPressed);
}
void AInputBridgePawn::OnMoveForward(float Value)
{
CurrentCommand.Move.Y = Value;
}
void AInputBridgePawn::OnMoveRight(float Value)
{
CurrentCommand.Move.X = Value;
}
void AInputBridgePawn::OnJumpPressed()
{
// 离散事件先缓存,统一在 Tick 中消费。
CurrentCommand.bJumpPressed = true;
}
void AInputBridgePawn::Tick(float DeltaTime)
{
Super::Tick(DeltaTime);
FVector2D Move = CurrentCommand.Move.GetClampedToMaxSize(1.0f);
if (!Move.IsNearlyZero())
{
UE_LOG(LogTemp, Log, TEXT("Move X=%.1f Y=%.1f"),
Move.X, Move.Y);
}
if (CurrentCommand.bJumpPressed)
{
UE_LOG(LogTemp, Log, TEXT("Jump requested"));
CurrentCommand.bJumpPressed = false;
}
}这里的适配关系是:BindAxis 接收连续浮点数,写入 Move;BindAction 接收一次按下事件,转换为 bJumpPressed。后续可以把 CurrentCommand 传递给独立的角色运动或命令处理模块。
GetClampedToMaxSize(1.0f) 用于防止同时按两个方向键时二维移动向量长度超过 1。它不会自动补偿不同游戏设计中的加速度和移动速度。
预期日志示例:按下 W 时,Output Log 可以出现以下信息。
LogTemp: Move X=0.0 Y=1.0按下空格键时可以出现:
LogTemp: Jump requested实际日志可能包含时间戳、类别或其他前缀;持续移动时会多次记录移动值。本例没有调用实际移动函数,因此 Pawn 不会因为这些输入自行产生位移。
接入 Enhanced Input 的方式
Enhanced Input 使用输入资源与 Mapping Context 组织绑定,不再要求把所有动作拆成传统 Action 和 Axis 映射。
在启用了 Enhanced Input 的项目中,可以建立 IA_Move 和 IA_Jump 两个 Input Action 资源:
- 将
IA_Move的 Value Type 设为Axis2D,用于输出二维移动向量。 - 将
IA_Jump的 Value Type 设为Boolean,用于表示跳跃按钮动作。 - 创建
IMC_Gameplay,把 WASD、手柄摇杆等输入映射到对应 Action。 - 对 WASD 的一维按键输入配置合适的 Swizzle、Negate 等 Modifier,使它们形成正确的二维方向。
- 为本地玩家添加
IMC_Gameplay,然后通过UEnhancedInputComponent绑定 Action 回调。
核心适配逻辑可以写成下面的片段。它依赖项目已启用 Enhanced Input 模块、相关 Action 资源已绑定,并且类中已经声明 CurrentCommand。
#include "InputActionValue.h"
// 片段示例:由 Enhanced Input 回调调用。
void HandleEnhancedMove(const FInputActionValue& Value)
{
CurrentCommand.Move = Value.Get<FVector2D>();
}这个片段表达的关键关系是,Enhanced Input 的二维动作值直接进入通用命令结构。完整项目仍需要实现对应类成员函数,并在输入组件中完成资源绑定。
还需要区分 Started、Triggered 和 Completed 等触发事件:跳跃按下可以根据需求使用 Started,移动通常使用 Triggered 或连续状态读取。具体选择应依据 Action 的 Trigger 配置,而不是机械地把所有输入都绑定到同一个阶段。
验证迁移边界与典型问题
将 InputBridgePawn 放入关卡或配置为当前游戏模式的默认 Pawn,确认它由玩家控制,然后进入 Play 模式测试 WASD 与空格键。传统输入系统需要确保相应映射确实存在且未被其他配置覆盖。
如果没有任何日志,优先检查 Pawn 是否被 Possess、映射名称是否一致,以及项目是否正在使用预期输入系统。如果存在移动日志但没有跳跃日志,应检查 Jump Action Mapping 和按下事件绑定。
对于 Enhanced Input,如果 Action 回调始终不执行,应检查对应 Mapping Context 是否添加到正确的本地玩家,以及 Action 和事件阶段是否匹配。仅创建 Input Action 资源并不会自动激活键位映射。
跨引擎迁移时,还应明确二维移动轴的方向约定,例如 X 表示左右、Y 表示前后。Unity 和 Unreal 的设备输入可以映射到同一逻辑坐标,但角色世界坐标变换应交由玩法层负责。
最终的验收标准不是两套引擎 API 看起来相似,而是替换输入来源时,玩法层仍接收相同的 Move 向量和 JumpPressed 命令。这样才能在引擎升级、控制器重绑定或多平台迁移时保持游戏行为稳定。