AI WORKFLOW

本博客由 AI 工作流自动管理，文章根据博主的个人笔记及与 GPT 的对话习惯自动整理，主要用于博主复习、整理与查阅。内容可能存在错误或 AI 幻觉，请结合可靠资料自行鉴别。

TPSGameplayDemo开发文档

此博客为AI工作流自动管理，由博主的个人笔迹与GPT对话习惯自动整理，为博主复习整理查阅，必有错误，请注意鉴别是否AI幻觉。

1. 项目说明

TPSGameplayDemo 是一个使用 Unreal Engine 5.6 与 C++ 制作的第三人称 Gameplay Demo。项目将角色移动、攀爬、射击、交互、对话、背包和宝箱等功能整合到同一个可运行场景中，同时完成角色、武器、动画、特效与环境资源的适配。

项目目前包含两类主要内容：

第三人称角色控制与动作射击；
场景交互、NPC 对话和物品管理。

2. 技术构成

引擎： Unreal Engine 5.6；
开发语言： C++，配合 Blueprint 完成资源引用和表现参数配置；
输入系统： Enhanced Input；
界面系统： CommonUI、UMG、Model-View-ViewModel；
Gameplay： Gameplay Tags、状态化角色移动与模块化交互；
特效： Niagara 与 Cascade Particle System；
动画： Animation Blueprint、Animation Montage 与骨架动画重定向；
验证方式： C++ Automation Test 与场景内功能验收。

3. 角色移动与体力

角色移动包含普通移动、Dash 和持续冲刺。Dash 触发时，角色会根据当前朝向获得一段瞬时位移，并播放对应动作；Dash 结束后，如果玩家仍保持移动，则继续进入冲刺状态，否则恢复普通移动。

冲刺期间会持续消耗体力，体力数值通过 ViewModel 传递到 UI。界面只负责显示变化，不直接保存角色状态，使移动逻辑和界面表现保持分离。

这部分主要使用了以下技术：

使用状态切换管理普通移动、Dash 和冲刺之间的衔接；
使用角色移动组件控制速度和瞬时位移；
使用计时与退出条件限制 Dash 和冲刺持续时间；
使用 MVVM 将体力数据同步到进度条。

4. 攀爬系统

角色向前移动时会检测前方表面。只有表面满足攀爬条件时，角色才会进入攀爬状态，避免普通墙面被错误识别。

进入攀爬后，角色根据墙面法线调整朝向，并使用角色的局部方向完成横向和纵向移动。头部前方的额外探测用于判断墙面是否已经到达顶部；满足登顶条件后，角色播放登顶动作并移动到预设落点。

为了适应不规则的环境模型，攀爬面和登顶落点使用独立的场景标记进行配置。这样可以在不直接修改大型环境网格的情况下，为指定区域补充稳定的攀爬能力。

5. 第三人称武器系统

武器系统包含放松、瞄准和换弹等战斗状态。玩家按住瞄准键后进入肩后视角，角色朝向跟随控制器；只有处于可开火状态时，射击输入才会生效。

瞄准

瞄准过程通过插值调整摄像机臂长度、镜头偏移和视野角度，使普通视角能够平滑过渡到肩后视角。武器使用独立的相对位置和旋转参数适配角色手部骨骼，避免武器模型自身轴向差异影响瞄准方向。

射击与命中

射击使用从玩家视点沿准星方向发出的射线完成命中检测。命中后，根据碰撞点和表面法线生成命中特效，并向目标应用伤害事件。

开火频率、换弹状态和当前战斗状态共同限制射击，防止在换弹或非瞄准状态下触发开火。枪口特效在开火时短暂激活，结束后自动关闭，避免粒子组件常驻播放。

动画

系统分别配置瞄准循环、射击动作、角色换弹和武器换弹。动画播放完成后，角色会恢复到瞄准姿态或普通移动动画。

命中检测与伤害逻辑不依赖动画是否成功播放。即使某段动画因为骨架兼容问题未能使用，射击功能仍可以单独验证。

6. NPC 交互与对话

角色进入交互范围后，系统会记录当前可交互对象。玩家触发交互时，通过统一接口调用对应对象的行为，因此 NPC、宝箱和其他交互物体可以使用相同的交互入口。

NPC 对话数据包含角色名称和台词内容。交互开始后，对话数据写入 ViewModel，再由 CommonUI 界面逐句显示。玩家继续操作时推进下一句，对话结束后关闭界面并恢复角色输入。

7. 背包与宝箱

玩家背包和宝箱分别保存自己的物品数据。宝箱可以在编辑器中配置初始物品及数量，玩家靠近宝箱后打开容器界面，并通过双击将单个物品转移到背包。

一次物品转移包含以下步骤：

检查来源槽位和目标背包是否有效；
向玩家背包加入一个物品单位；
从宝箱中扣除相同数量；
如果扣除失败，则撤销刚才的添加操作；
更新两侧容器界面。

当物品数量变为零时，对应槽位会被移除。关闭并再次打开宝箱后，未拾取的物品仍然保留。

宝箱距离检测使用组件包围盒而不是单一物体原点，从而适应模型原点偏移或资源迁移后产生的位置差异。

8. UI 与数据展示

项目使用 CommonUI 管理运行时界面。背包、宝箱和对话窗口作为可激活界面加入 Gameplay UI 层，由统一的界面栈处理打开、关闭和输入焦点。

体力、对话内容和物品列表通过 ViewModel 或数据事件更新。界面读取数据并显示结果，Gameplay 逻辑负责维护真实状态，避免把物品数量、角色体力或对话流程直接写在控件中。

当前运行界面保留以下必要信息：

体力条；
屏幕中心准星；
玩家背包与宝箱列表；
NPC 名称与对话内容。

9. 角色、武器与场景资源整合

角色、武器、动画和环境资源在迁移时保留原有目录关系，减少材质、骨架和动画引用丢失的问题。导入后分别检查 Skeleton、Animation Blueprint、Montage、Socket 和模型变换，再将资源接入 Gameplay 功能。

资源整合过程中主要处理了以下问题：

毛发与当前渲染设置不兼容时，选择显示稳定的角色版本；
武器轴向与手部骨骼方向不一致时，使用附着点和相对变换进行适配；
不同骨架之间的动画先进行兼容检查，必要时完成动画重定向；
场景模型不规则时，使用独立碰撞区域、攀爬面和登顶落点补充交互；
粒子组件通过明确的激活和关闭时机控制生命周期。

10. 测试与验证

项目为物品添加、宝箱初始化、单件物品转移和攀爬场景配置补充了自动化测试，用于降低数据调整和场景适配时的回归风险。

场景内主要验证以下内容：

地图能够正常加载，角色能够生成并响应输入；
普通移动、Dash、冲刺和体力显示能够正确衔接；
角色能够进入攀爬、横向移动并完成登顶；
瞄准、射击、枪口特效、命中特效和换弹能够正常运行；
NPC 对话可以逐句推进并正常退出；
宝箱物品可以转移到玩家背包，数量和界面能够同步更新。

11. 操作说明

WASD： 控制角色移动；
鼠标： 控制视角；
Dash Action： 触发 Dash，并在保持移动时衔接冲刺；
按住鼠标右键： 进入肩后瞄准；
鼠标左键： 在瞄准状态下射击；
R：换弹；
交互键： 与 NPC 等对象进行交互；
B：打开或关闭玩家背包；
F：打开或关闭附近宝箱；
双击宝箱物品： 将一个物品单位转移到玩家背包。

12. 项目总结

TPSGameplayDemo 使用 Unreal Engine 5.6 与 C++ 完成了一套可运行的第三人称 Gameplay 内容，并通过 Blueprint、CommonUI、MVVM、Gameplay Tags、动画系统和 Niagara 将角色移动、攀爬、射击、交互、对话与物品管理连接起来。

文档只记录 Demo 中已经接入并验证的技术与功能，不展开项目底层通用代码结构。