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

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 的回调只负责产生输入意图,角色行为由后续业务逻辑决定。

Unreal 输入映射到通用玩法命令的数据流图

例如,通用层只需要 Move(Vector2) 和 JumpPressed 两种语义。无论输入来自键盘 WASD、手柄摇杆,还是 Enhanced Input 的二维 Action,玩法都接收相同的数据。

移动是持续状态,适合按帧读取并统一处理;跳跃通常是边沿事件,适合在按下时提交一次请求。这两类命令不能简单地使用相同的触发策略。

配置传统 Action 与 Axis 映射

下面使用 Unreal Engine 的传统输入映射演示最小接入方式。该方案适合维护旧项目,也能清楚展示输入映射和业务逻辑之间的接口关系。新建项目通常应优先考虑 Enhanced Input。

在 Edit > Project Settings > Input 中,可以添加 Action 和 Axis 映射。也可以通过配置文件声明映射。

以下是 Config/DefaultInput.ini 的片段示例,依赖传统 PlayerInput 映射机制。若已有同名映射,应检查是否重复,不要无条件追加。

ini
[/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 内容如下:

cpp
#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:

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 可以出现以下信息。

text
LogTemp: Move X=0.0 Y=1.0

按下空格键时可以出现:

text
LogTemp: Jump requested

实际日志可能包含时间戳、类别或其他前缀;持续移动时会多次记录移动值。本例没有调用实际移动函数,因此 Pawn 不会因为这些输入自行产生位移。

接入 Enhanced Input 的方式

Enhanced Input 使用输入资源与 Mapping Context 组织绑定,不再要求把所有动作拆成传统 Action 和 Axis 映射。

在启用了 Enhanced Input 的项目中,可以建立 IA_Move 和 IA_Jump 两个 Input Action 资源:

  1. 将 IA_Move 的 Value Type 设为 Axis2D,用于输出二维移动向量。
  2. 将 IA_Jump 的 Value Type 设为 Boolean,用于表示跳跃按钮动作。
  3. 创建 IMC_Gameplay,把 WASD、手柄摇杆等输入映射到对应 Action。
  4. 对 WASD 的一维按键输入配置合适的 Swizzle、Negate 等 Modifier,使它们形成正确的二维方向。
  5. 为本地玩家添加 IMC_Gameplay,然后通过 UEnhancedInputComponent 绑定 Action 回调。

核心适配逻辑可以写成下面的片段。它依赖项目已启用 Enhanced Input 模块、相关 Action 资源已绑定,并且类中已经声明 CurrentCommand。

cpp
#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 命令。这样才能在引擎升级、控制器重绑定或多平台迁移时保持游戏行为稳定。

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

目录与阅读设置

阅读设置

17

记录一个想法

Unreal的Action与Axis怎么接入

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

登录哪都通