【UE5 学习笔记】第一人称模板项目解析（一）：项目结构与核心逻辑

在第一人称游戏中，玩家从其所扮演角色的视点来查看游戏。一些第一人称游戏会显示角色模型的某部分，例如角色的手臂或武器。这与第三人称游戏不同，在后者中，你可以从角色背后略上方的位置看到角色动作。

1. 项目概览

可以看到Content目录下有如下四个文件夹：

下面我们来逐一分析每一个文件夹的内部结构

1.1 ⭐ 角色 `Characters`

角色文件夹里面只有一个角色Mannequins，意为"模特"，可以理解为其他角色的基础类 。Mannequins包含五个文件夹，如下所示：

`Anims`：存放角色的动画序列

可以看到，不同的动画被分门别类，放在不同的文件夹里

我们选择其中的Unarmed（未手持武器）的动画集合为例进行分析，可以发现，该文件夹下有三种不同的文件：

动画蓝图： 连接游戏逻辑和所有动画资源（动画序列、混合空间），根据游戏状态输出最终的角色动画
混合空间： 基于指定参数（如速度、转向角度），自动平滑混合多个相似动画序列的资源，解决多个动画之间卡顿切换的问题
动画序列： 存储单一、独立动画动作的基础资源，相当于动作片段，是角色动画的原材料

如果你需要修改模型的行走动画，比如将摆臂的幅度加大，你可以修改对应的动画序列文件，但这是游戏美术需要考虑的事情。

`Materials`：存放角色的材质

文件夹Manny/Quinn：分别对应默认的两个人体模特（男性/女性）的专属材质资源
M_Mannequin：是人体模特的基础材质（或材质实例），直接控制人体模特的视觉表现（比如默认的灰白纹理外观）

Q：材质和材质实例的区别是什么？

A：Material是材质的母版 ，可以编辑Shader网络、设置基础渲染属性（比如是否透明、光照响应方式）；而Material Instance是基于基础材质创建的子资源，继承基础材质的所有属性，但可以单独修改部分参数（比如颜色、纹理、粗糙度），不用重新做整个材质，能大幅提升资源复用和调整效率。

`Mesh`：角色的网格图形

Mesh存储了物体的顶点、面、法线等几何数据，决定了角色在游戏里呈现出的形状。

可以看到Mesh文件夹里面有两种文件：

Skeleton ：角色的动画骨架,定义了角色能活动的关节逻辑
Skeletal Mesh ：这是绑定了骨骼的Mesh，既包含角色的几何形状，又和骨骼资源关联，能驱动骨骼动画

`Rigs`：角色的动画控制与物理交互辅助

可以看到Rigs里包含两类核心资源：

Control Rig：可视化的骨骼控制工具，负责调整角色姿态、补全动画细节；
Physical Asset：绑定骨骼的碰撞配置资源，负责处理角色的物理碰撞、受力反馈。

我们对文件夹里的每个文件进行解析：

CR_Mannequin_Body ：身体控制，调整角色身体各关节的姿态，也能给现有动画叠加细节，让动画更生动
CR_Mannequin_FootIK ：脚部IK控制，解决动画穿模问题，让脚部自动贴合地面，使移动动画更真实自然
CR_Mannequin_Procedural ：程序化控制，根据角色的运动状态自动调整肢体细节，不用手动逐帧编辑动画，提升动画制作效率
PA_Mannequin ：角色物理资产，给角色骨骼绑定了对应的碰撞体，让角色能和场景物体产生碰撞、受到物理力时产生反馈等

`Textures`：角色的纹理

可以看到该文件夹下有三个子文件夹，其作用也很清晰：

Manny：男性模特的专属纹理文件夹
Quinn：女性模特的专属纹理文件夹
Shared：两个模特共用的纹理文件夹，比如通用的布料底色、金属装饰纹理等

至此，我们已经分析了角色文件夹Characters内的所有内容，可以看到这是一个UE官方给出的功能相对完善的角色基础模板，我们后续可以在其基础上拓展出不同类型的角色。

1.2 输入配置 `Input`

先通览一下Input文件夹内的内容：

输入映射上下文 是输入的核心文件，IMC_Default/IMC_MouseLook用来切换不同的输入规则（比如IMC_Default是默认全操作，IMC_MouseLook是仅允许鼠标控制视角的简化操作）。
Actions是动作输入的映射库 ，包含"操作------游戏动作"的具体绑定配置，把玩家的按键或操作对应到具体的游戏功能
- IA_Jump：触发角色跳跃
- IA_Move：控制角色移动
- IA_Look/IA_MouseLook：绑定视角操作并转动角色视角
Touch是触屏设备的专属输入配置
- UI_Thumbstick：虚拟摇杆控件，对应手柄左摇杆（触屏时拖动摇杆控制移动）
- BP_TouchInterface：触摸交互的逻辑蓝图，管理触屏操作的识别规则
- UI_TouchSimple：简单触摸按钮配置

举个例子，为了给角色加入一个瞄准动作，我需要做如下操作：

新建一个IA_Aim动作
将鼠标右键点击事件绑定到IA_Aim动作
在角色蓝图中添加相关事件的处理逻辑，如更改FOV、减少抖动等

1.3 关卡原型 `LevelPrototyping`

可以看到，这个文件夹专门用于存放搭建测试关卡所需的资源

Interactable：关卡原型的交互物体库，存放关卡中能和玩家产生互动的物体资源（比如可拾取的道具、可触发的机关、可打开的门）
Materials：关卡原型的基础材质包
Meshes：关卡原型的场景几何体
Textures：关卡原型的简化纹理素材

基于这些原型资源，开发者可以快速搭建出供测试用的地图以验证核心玩法，无需等待美术资源全部制作完毕，大大提高了开发效率。

1.4 ⭐ 第一人称模板 `FirstPerson`

这是本节的重中之重，包含了第一人称角色的控制相关的功能，先来看一下目录结构：

可以看到根目录下有两个独立文件：

Lvl_FirstPerson是第一人称玩法的演示场景，已经搭好适配第一人称视角的基础关卡（比如简单的房间、可交互的道具），可以直接用来测试第一人称的移动、交互等核心玩法
MI_FirstPersonColorway是第一人称可见物体（比如武器、手臂模型）的外观配置资源，能单独调整这些元素的颜色、质感（比如把武器改成黄色、调整手臂模型的光泽度），不用修改基础材质就能快速切换外观风格

Anims文件夹用于存放角色的动画序列，相比基础模特，这里的动画序列多了以下两个：

ABP_FP_Copy（动画蓝图） ：负责接收第一人称的操作输入，调用对应的动画资源，输出最终的第一人称动画表现
CtrlRig_FPWarp（Control Rig） ：负责精细调整第一人称可见部分的姿态，让动作更真实自然

Blueprints文件夹下有四个蓝图文件，这四个蓝图是支撑第一人称玩法的核心功能模块，分工覆盖了 角色实体、操作控制、视角管理、关卡规则。

BP_FirstPersonCharacter（角色蓝图）
- 处理移动、跳跃等基础动作逻辑
- 管理角色的状态（如生命值、交互状态）
- 绑定第一人称视角下的可见元素（如手臂、手持道具）
BP_FirstPersonPlayerController（玩家控制器蓝图）
- 接收玩家的输入并传递给角色蓝图
- 管理第一人称视角的控制逻辑
- 传递UI与角色之间的交互指令
BP_FP_CameraManager（相机管理器蓝图）
- 控制相机的跟随规则
- 实现视角的动态效果
- 限制视角的转动范围
GM_FirstPerson（游戏模式蓝图）
- 定义关卡的核心规则
- 管理关卡内的资源刷新、敌人配置等全局逻辑

classDiagram class GM_FirstPerson { +定义关卡的核心规则 +管理关卡内的资源刷新、敌人配置等全局逻辑 } class BP_FirstPersonPlayerController { +接收玩家的输入并传递给角色蓝图 +管理第一人称视角的控制逻辑 +传递UI与角色之间的交互指令 } class BP_FirstPersonCharacter { +处理移动、跳跃等基础动作逻辑 +管理角色的状态（如生命值、交互状态） +绑定第一人称视角下的可见元素（如手臂、手持道具） } class BP_FP_CameraManager { +控制相机的跟随规则 +实现视角的动态效果 +限制视角的转动范围 } GM_FirstPerson <|-- BP_FirstPersonPlayerController : 使用 BP_FirstPersonPlayerController --> BP_FirstPersonCharacter : 控制/Possess BP_FirstPersonCharacter --> BP_FP_CameraManager : 包含/使用 BP_FirstPersonCharacter --> ABP_FP_Copy : 使用动画蓝图 BP_FirstPersonCharacter --> CtrlRig_FPWarp : 使用Control Rig

至此，我们基本了解了这个示例项目的结构，接下来我们将对程序的核心------FirstPerson文件夹下的四个蓝图进行分析，了解游戏核心逻辑是如何编写的。

2. `FirstPerson` 核心逻辑分析

2.1 ⭐ `BP_FirstPersonCharacter`

先对该蓝图所拥有的组件进行概览：

胶囊体组件 (CollisionCylinder) ：角色根组件，用于处理基本碰撞检测 和防止角色穿透世界物体
箭头组件 (Arrow) ：可视化方向箭头，用于在编辑器中表示角色朝向，便于调试和定位
网格体 (CharacterMesh0) ：第三人称视图下的完整角色骨骼网格（Skeletal Mesh），在第一人称模式下通常隐藏，仅他人可见
FirstPersonMesh ：第一人称视图下的手臂/武器骨骼网格，仅拥有玩家可见，随相机移动
FirstPersonCamera ：第一人称相机组件，提供玩家视角 视图，并控制头部转动
角色移动 (CharMoveComp) ：CharacterMovementComponent的简称，负责处理角色移动、跳跃、重力、碰撞响应等物理逻辑

有了这些组件，我们就可以编写具体的控制逻辑。逻辑写在蓝图的事件图表中，我们将这个复杂的流程拆解成以下几个部分：

流程入口

在Pawn被任何Controller（玩家或 AI）接管时触发，用于区分玩家控制（PlayerController）与 AI 控制（AIController），以执行不同逻辑（如仅玩家可见的 UI、输入映射、相机设置等）。

跨平台输入自适应

根据当前运行平台有条件地添加一个专门用于鼠标瞄准的输入映射上下文（IMC_MouseLook），同时在移动平台上创建并显示一个触摸UI控件（Target Touch UI），以避免鼠标输入与触摸输入冲突。

如果不是触摸设备，则添加瞄准映射上下文，否则鼠标输入会干扰触摸操作。如果想在 Windows 上测试触摸 UI，可以开启"Use mouse for touch"选项，并将 Windows 分支设置为创建触摸 UI。

视角控制

这是一套典型的处理视角输入的蓝图逻辑，与上文跨平台输入的适配完美配合，我们可以用一个表格来描述逻辑要点：

输入来源	输入动作/事件	X轴 →	Y轴 →	最终处理函数
鼠标（PC）	IA_Look（Triggered）	Yaw（左右）	Pitch（上下）	Aim
鼠标（备用/补充）	IA_MouseLook（Triggered）	Yaw	Pitch	Aim
触摸右摇杆（移动端）	Event Secondary Thumbstick	Yaw	Pitch	Aim

这一套逻辑有以下几个优点：

无论鼠标还是触摸摇杆，最终都调用同一个Aim函数，可以确保视角控制逻辑一致
完美配合了前一张图的逻辑------移动端弹出触摸UI并触发此事件，PC端使用鼠标输入动作。
所有输入都通过Input Action定义，便于在Project Settings中统一绑定键位、调整曲线、添加修饰器（如死区、灵敏度）。

移动控制

实现了键盘与触摸摇杆的统一移动控制，两种输入源的X/Y轴值都汇入Move函数，驱动第一人称角色的前后左右平移。

同样我们使用一个表格来诠释这一套逻辑：

输入来源	输入动作/事件	X轴 →	Y轴 →	最终处理函数
键盘（PC）	IA_Move（Triggered）	Left/Right	Forward/Backward	Move
触摸左摇杆（移动端）	Event Primary Thumbstick	Left/Right	Forward/Backward	Move

跳跃控制

这段蓝图实现了键盘与触摸按钮的统一跳跃控制。

使用一个表格来诠释这一套逻辑：

输入来源	跳跃开始（Jump）	跳跃结束（Stop Jumping）
键盘/手柄（PC）	IA_Jump Started	IA_Jump Completed
触摸按钮（移动端）	Event Touch Jump Start	Event Touch Jump End

另外，这个蓝图中还有两个重要的函数：Move和Aim，以下两张图分别展示了这两个函数的核心逻辑：

这些函数封装了角色移动 和视角转换的API，使开发者执行这两个操作变得极其简单。

使用伪代码描述逻辑链：

scss 复制代码

// BP_FirstPersonCharacter - 输入处理部分

// 视角控制（Camera Input）
On Enhanced Input Action IA_Look Triggered(ValueX, ValueY)
    Aim(Yaw = ValueX, Pitch = ValueY)

On Enhanced Input Action IA_MouseLook Triggered(ValueX, ValueY)
    Aim(Yaw = ValueX, Pitch = ValueY)

On Event Secondary Thumbstick From Touch Interface(AxisX, AxisY)
    Aim(Yaw = AxisX, Pitch = AxisY)

// 移动控制（Movement Input）
On Enhanced Input Action IA_Move Triggered(ValueX, ValueY)
    Move(LeftRight = ValueX, ForwardBackward = ValueY)

On Event Primary Thumbstick From Touch Interface(AxisX, AxisY)
    Move(LeftRight = AxisX, ForwardBackward = AxisY)

// 跳跃控制（Jump Input）
On Enhanced Input Action IA_Jump Started
    Jump()

On Enhanced Input Action IA_Jump Completed
    Stop Jumping()

On Event Touch Jump Start From Touch Interface
    Jump()

On Event Touch Jump End From Touch Interface
    Stop Jumping()

// 内部函数（通常在蓝图函数中实现）
Function Aim(Yaw, Pitch)
    Add Controller Yaw Input(Yaw * MouseSensitivity)
    Add Controller Pitch Input(Pitch * MouseSensitivity)

Function Move(LeftRight, ForwardBackward)
    Add Movement Input(Get Actor Forward Vector(), ForwardBackward)
    Add Movement Input(Get Actor Right Vector(), LeftRight)

2.2 `BP_FirstPersonPlayerController`

作为第一人称项目的玩家控制器，负责管理玩家输入系统的初始化、跨平台适配、触摸UI的创建与显示，以及其他玩家专属逻辑（如 HUD、输入模式切换）。

它主要与之前的BP_FirstPersonCharacter配合：Character处理移动/视角/跳跃的具体实现，PlayerController处理输入映射和UI的平台差异。

使用伪代码描述逻辑链：

csharp 复制代码

// BP_FirstPersonPlayerController - Event Graph (主要在 Event BeginPlay 中执行)

Event BeginPlay()
{
    // 获取当前本地玩家的 Enhanced Input 子系统
    EnhancedInputSubsystem = Get Enhanced Input Local Player Subsystem()

    // 添加基础输入映射上下文（包含移动、视角、跳跃等所有 Input Action）
    EnhancedInputSubsystem.Add Mapping Context(IMC_Default, Priority = 0)

    // 获取当前运行平台名称（返回字符串，如 "Windows"、"Android"、"iOS" 等）
    PlatformName = Get Platform Name()

    // 根据平台进行分支判断
    Switch (PlatformName)
    {
        Case "Windows":
            // PC 平台：仅使用键盘鼠标，无需触摸 UI
            // 不执行任何额外操作（鼠标输入已由 IMC_Default 覆盖）
            Break

        Case "Android":
        Case "iOS":
            // 移动平台：创建并显示虚拟触摸控件 UI
            TouchUIWidget = Create Widget(Class = TargetTouchUI, OwningPlayer = Self)
            if (TouchUIWidget != null)
            {
                TouchUIWidget.Add To Viewport()  // 添加到屏幕视口，使其可见
                // 可选：设置输入模式为 Game and UI，允许触摸按钮接收输入
                Set Input Mode Game And UI()
                Show Mouse Cursor(false)  // 通常隐藏鼠标光标
            }
            Break

        Default:
            // 其他平台（如 Editor 测试、Console 等）：默认同 PC 处理
            // 不创建触摸 UI
            Break
    }
}

2.3 `GM_FirstPerson`

这是一个纯数据的蓝图，定义了游戏的运行模式，以下展示了几个重要的设置：

我们只需要在世界场景设置中选择该蓝图，即可应用对应的游戏模式：

2.4 `BP_FP_CameraManager`

可用于自定义玩家相机行为 ，用于增强第一人称体验。标准第一人称模板中通常不需要重度自定义，我们之后可以将其用于实现相机抖动 、瞄准时FOV变化 、头部鲍勃或其他平滑相机效果。

至此，我们分析了这个项目的结构以及核心逻辑（四个蓝图），在下一节中，我们将对项目结构进行进一步优化，便于我们后续的拓展开发。

【UE5 学习笔记】第一人称模板项目解析（一）：项目结构与核心逻辑