在 Unreal Engine…

为 UE C++ 项目提供测试框架、日志、断言、调试绘制、控制台命令与性能分析的完整可执行做法。

适用场景

解决思路

1. 先阅读 `.agents/ue-project-context.md` 获取引擎版本、已有日志分类、测试基础设施（自动化模块、测试地图）和项目约定，再给出建议。
2. 若用户需求不明确，先确认属于哪一类：自动化测试、功能测试、日志、断言、调试绘制、控制台命令还是性能分析。
3. 自动化测试放在独立模块（如 `MyGameTests`）中，依赖 `"AutomationController"`；在编辑器 target 通过 `ExtraModuleNames` 引入，在游戏 target 通过 `if (bWithAutomationTests)` 条件引入。
4. 用 `IMPLEMENT_SIMPLE_AUTOMATION_TEST` 编写简单测试，必须指定一个 application context flag 且恰好一个 filter flag（如 `EditorContext | ProductFilter`），在 `RunTest` 中用 `TestEqual`/`TestTrue`/`TestFalse`/`TestNotNull` 等断言并返回 true。
5. 用 `IMPLEMENT_COMPLEX_AUTOMATION_TEST` 编写参数化测试：重写 `GetTests()` 填充 `OutBeautifiedNames` 与 `OutTestCommands`，`RunTest(Parameters)` 逐个接收参数执行。
6. 使用测试断言方法：`TestEqual`（支持 int32/int64/float/double/FVector/FRotator/FTransform/FColor/FLinearColor/FString/FStringView/FText/FName，float 有容差重载）、`TestTrue`/`TestFalse`、`TestNotNull`/`TestNull`/`TestValid`、`AddError`/`AddWarning` 自定义失败信息、`UE_RETURN_ON_ERROR` 失败即返回。
7. 测试 flag 选择：`EditorContext` 编辑器进程、`ClientContext` 游戏客户端、`ServerContext` 专用服务器、`SmokeFilter` 快速 CI、`ProductFilter` 项目级测试。
8. 异步测试用 latent command：用 `DEFINE_LATENT_AUTOMATION_COMMAND_ONE_PARAMETER` 定义命令，`Update()` 返回 true 表示完成、false 表示下一帧重试，在 `RunTest` 内用 `ADD_LATENT_AUTOMATION_COMMAND` 入队，命令在 `RunTest` 返回后顺序执行。
9. 功能测试用 `AFunctionalTest` actor 放在测试地图中，重写 `StartTest()` 并在完成时调用 `FinishTest()`；在 `PrepareTest()` 中设置 `TimeLimit`（秒，0 表示无超时）实现自动失败超时。
10. 功能测试 actor 放在 `Maps/Test_MyFeature.umap`，通过 `RunAutomationTest "MyGame.Functional.MyFeature"` 或 Session Frontend 运行。
11. 声明日志分类：模块级用 `DECLARE_LOG_CATEGORY_EXTERN(LogMyModule, Log, All)` 配合 `DEFINE_LOG_CATEGORY(LogMyModule)`；单文件静态用 `DEFINE_LOG_CATEGORY_STATIC(LogMyHelper, Warning, All)`。
12. 使用 `UE_LOG(CategoryName, Verbosity, Format, ...)` 输出日志；用 `UE_CLOG(condition, ...)` 做条件日志（仅当分类/详细级别激活时才求值条件）。
13. 按严重程度选择 verbosity：`Fatal` 崩溃级、`Error` 操作失败、`Warning` 可恢复异常、`Display` 用户可见、`Log` 常规开发信息、`Verbose` 每帧/每次调用细节、`VeryVerbose` 追踪级高频。
14. UE 5.2+ 用结构化日志 `UE_LOGFMT(LogMyModule, Warning, "...{Name}...{Error}", ("Name", AssetName), ("Error", ErrorCode))`，字段顺序无关且可超出格式串字段。
15. 运行时过滤日志：命令行 `-LogCmds="LogMyModule Verbose, LogAI Warning"`；控制台 `Log LogMyModule Verbose`、`Log LogAI Warning`、`Log reset` 恢复默认。
16. 断言选型：类不变量/程序员错误用 `check`/`checkf`；可恢复且想继续用 `ensure`/`ensureMsgf`；表达式有必须始终求值的副作用用 `verify`/`verifyf`；Debug 构建的重验证用 `checkSlow`；用户输入校验用显式 if/return 而非断言。
17. `check`/`checkf` 在 Debug/Development/Test 生效，Shipping 中被移除（表达式不求值）；`checkNoEntry()` 标记不可达路径，`checkNoReentry()` 标记只执行一次。
18. `ensure`/`ensureMsgf` 非致命，记录调用栈并提交崩溃报告后继续执行，但每个调用点每会话只触发一次；需要每次都报告用 `ensureAlways`/`ensureAlwaysMsgf`。
19. `verify`/`verifyf` 表达式始终求值（含 Shipping），仅在非 Shipping 中中止。
20. 调试绘制用 `DrawDebugHelpers.h`：`DrawDebugLine`/`DrawDebugSphere`/`DrawDebugBox`/`DrawDebugCapsule`/`DrawDebugPoint`/`DrawDebugDirectionalArrow`/`DrawDebugString`，Duration>0 为可见秒数，0 或 -1 只显示一帧；用 `FlushPersistentDebugLines` 清除持久几何；持久绘制用 `#if ENABLE_DRAW_DEBUG` 包裹。
21. 控制台命令：在 `PlayerController`/`Pawn`/`HUD`/`GameMode`/`GameState`/`CheatManager`/`GameInstance` 上用 `UFUNCTION(Exec)` 定义可在控制台（~）执行的函数。
22. 用 `FAutoConsoleCommand`（静态初始化注册，无需 world 上下文）、`FAutoConsoleCommandWithWorldAndArgs`（PIE 安全，推荐用于 gameplay 命令）、`TAutoConsoleVariable<float>`（CVar，在 .cpp 中声明避免 ODR 问题，用 `GetValueOnGameThread()` 读取）、`FAutoConsoleVariableRef`（绑定已有变量）。
23. 运行时注册命令用 `IConsoleManager::Get().RegisterConsoleCommand(...)`（在 StartupModule/Initialize/BeginPlay 调用），并在对象销毁时用 `UnregisterConsoleObject(Cmd)` 注销。
24. 自定义 stat 与性能标记：用 `DECLARE_STATS_GROUP` 和 `DECLARE_CYCLE_STAT` 声明，用 `SCOPE_CYCLE_COUNTER` 包裹代码；用 `SCOPED_NAMED_EVENT` 在 Insights 中显示彩色块；用 `CSV_DEFINE_CATEGORY` 和 `CSV_SCOPED_TIMING_STAT` 做 CSV 性能分析（输出到 Saved/Profiling/CSVStats/）。
25. 调试技巧：用 Visual Logger（`UE_VLOG_SPHERE`/`UE_VLOG_SEGMENT`/`UE_VLOG`，Window > Visual Logger 查看）；在 PIE 中按 `'` 打开 Gameplay Debugger，用 `IGameplayDebugger::Get().RegisterCategory` 注册自定义分类。
26. IDE 断点调试：将 Visual Studio 或 Rider 附加到 `UnrealEditor` 进程，使用 `DebugGame` 或 `Debug` 配置以获得完整符号；在 `FDebug::AssertFailed`、`FDebug::EnsureFailed`、`FDebug::OptionallyLogFormattedEnsureMessageReturningFalse` 上设断点以在断言失败前中断。
27. 崩溃分析：minidump 在 `Saved/Crashes/`，用 WinDbg 或 Rider 配合 `UnrealEditor-Win64-DebugGame` PDB 打开；用 `FDebug::DumpStackTraceToLog(ELogVerbosity::Error)` 打印调用栈。
28. 网络调试：`-NetTrace` 抓取复制数据，`stat net` 查看实时带宽，`net.ListActorChannels` 查看 actor 通道。
29. 性能分析命令：`stat startfile`/`stat stopfile`（.uestats 供 Insights）、`stat gpu`/`ProfileGPU`（GPU 计时）、`stat memoryplatform`/`memreport -full`（内存）、`-trace=cpu,gpu,frame,memory`（Insights 启动参数）。
30. 避免常见错误：不要把必需逻辑放进 `check()` 表达式（Shipping 中被移除）；`ensure` 每调用点只触发一次，需要每次都报告用 `ensureAlways`；DrawDebug 在 Shipping 中不存在，持久绘制用 `#if ENABLE_DRAW_DEBUG` 包裹；`UE_LOG` 使用的分类必须在当前翻译单元可见否则链接错误；每个 `IMPLEMENT_SIMPLE_AUTOMATION_TEST` 必须恰好有一个 filter flag；latent command 必须在 `return true;` 之前入队；多人游戏中用 `GetWorld()->GetNetMode()` 或 `UE_CLOG(HasAuthority(), ...)` 减少日志噪音。

适用边界 · 注意事项

• 项目未使用 Unreal Engine 或不是 UE C++ 项目时不适用。
• 只需要纯 C++ 日志模式而不涉及 UE 宏系统时，应参考 ue-cpp-foundations。
• 测试模块的构建与 target 引入配置应参考 ue-module-build-system。