Debug Tips
About 6 min
Debug Tips
VS连接编辑器
使用vs打开ue编辑器后,可以使用death process
关闭调试,后面需要调试就使用attach process
,这里需要选择Native Code
。
蓝图调试器
蓝图异常
自动中断
- 编辑器偏好设置->通用-实验性功能->蓝图->异常时中断蓝图
- DefaultEditorPerProjectUserSettings.ini:
- [/Script/UnrealEd.EditorExperimentalSettings]
- bBreakOnExceptions=True
显示蓝图脚本调用堆栈
- DefaultEngine.ini:[Kismet] ScriptStackOnWarnings=true
- 添加启动参数:-ScriptStackOnWarning
在编辑器中调用函数/事件
编辑器中调用
- 仅针对无形参的函数/事件有效
- C++ 函数在UFUNCTION声明中添加标记符
CallinEditor
UFUNCTION(BlueprintCallable, CallInEditor, Category = "Default")
void TestFunction();
编辑器工具控件 / 编辑器工具蓝图
- 蓝图函数库(BlueprintFunctionLibrary)
Python
打印字符串
固定屏幕打印字符串的位置:
- 使用Key属性替换HUD中已有的Log
- C++下:GEngine->AddOnScreenDebugMessage
- 仅非Shipping下有效果
画线
在需要进行射线碰撞的地方,使用 DrawDebugLine
函数来绘制射线:
#include "DrawDebugHelpers.h"
FVector StartLocation = PlayerCamera->GetComponentLocation();
FVector EndLocation = StartLocation + PlayerCamera->GetForwardVector() * MaxRaycastDistance;
// 绘制射线
DrawDebugLine(GetWorld(), StartLocation, EndLocation, FColor::Green, false, -1, 0, 1);
- GetWorld():获取当前场景的世界对象。
- StartLocation 和 EndLocation:射线的起点和终点。
- FColor::Green:指定绘制射线的颜色。
在 DrawDebugLine 函数中,你还可以设置其他的参数,例如绘制持续时间、线条宽度等。
日志
- 保存在
Saved/Logs
- 仅
Dev/Debug
下有效- Shipping开启:bUseLoggingInShipping=true (adb log中不显示)
- 启动参数
-log
:在命令行中显示日志 - 声明和定义日志类别:
- DECLARE_LOG_CATEGORY_EXTERN
- DEFINE_LOG_CATEGORY
- 控制台命令
log LogName NewVerbosity
:运行时修改日志的显示级别- 控制台命令:
log global error
- 配置文件参数:DefaultEngine.ini: [Core.log] global=error
- 启动参数:
-ini.Engine:[Core.Log]:global=error
- 控制台命令:
在VS中可以打开Unreal Engine Log
窗口:
需要安装VS对UE的支持模块:
可视化记录器(Visual Logger)
- 可视化记录器 是一款强大的调试工具,可以创建记录游戏状态的视觉表示,并提供子啊编辑器中查看此数据的功能。
https://www.unrealengine.com/zh-CN/blog/using-the-ue4-visual-logger
作弊管理器(Cheat Manager)
引擎提供了内置的作弊管理器对象
- 代码位于
CheatManager.h/cpp
- 使用
Exec
标记声明函数,例如:- UFUNCTION(exec,BlueprintCallable)
- ENGINE_API virtural void God();
- Shipping开启:UE_WITH_CHEAT_MANAGER=1
- 定义你自己的作弊管理器(Player Controller的成员)
调试相机(Debug Camera)
- 快捷键开启
- 默认快捷键为“分号”
- 可以在
BaseInput.ini
中修改默认快捷/或在UserInput.ini
中重载- [/Script/Engine.PlayerInput]
- +DebugExecBindings=(Key=Semicolon,Command="ToggleDebugCamera")
- +DebugExecBindings=(Key=Apostrophe,Command="ToggleForceDefaultMaterial")
- 控制台命令
ToggleDebugCamera
- 控制台命令
Teleport
: 将角色移动到debug
相机注视处 - 控制台命令
slomo 0.1
:所有运动逻辑放缓10倍
obj 命令
该命令最好在版本中运行,在编辑器下很多对象不会被释放。
- obj list package=X 查看
x资产内
所有的UObjects
- obj list outer=X 按
outer(直接)分组
查看所有UObjects
- obj mem class=X 查看
所有X类型对象
的内存占用 - obj dump /Path/To.Obj 打印一个对象的
所有 UPROPERTY
- obj refs name=/Path/To.Obj 列出该对象
被引用的堆栈
- obj gc 强制出发一次垃圾回收
- 更多查看
UEngine::HandleObjCommand
Viual Studio 配置
- 设置配置栏宽度
- 多个分支叫做 UE5.sln
- 设置环境变量
UE_NAME_PROJECT_AFTER_FOLDER=1
- 解决方案会被命名为
UE5_<文件夹名>.sln
- 该设置可在
\Engine\Source\Programs\UnrealBuildTool\ProjectFiles\ProjectFileGenerator.cs : GenerateProjectFiles
函数修改逻辑
- 设置环境变量
- 调试速度慢,单步执行耗时久
- 选项->调试->通用
- 关闭 “调试时启用诊断工具”(Enable Diagostic Tools while debugging)
- 关闭 “调试过程中显示运行时间”(Show elapsed time PerfTip while debugging)
- 选项->调试->通用
构建配置 (Build Configurations)
Debug | Development | Test | Shipping | |
---|---|---|---|---|
IDE中调试 | √ | √ | √ | √ |
代码优化 | × | √ | √ | √ |
调试符号 | √ | √ | √ | × (unless IncludeDebugFiles=true) |
控制台命令 | √ | √ | √ | × (unless ALLOW_CONSOLE_IN_SHIPPING=true) |
作弊管理器 | √ | √ | √ | × (unless UE_WITH_CHEAT_MANAGER=true) |
Insights&可视化日志 | √ | √ | √ | × (unless UE_TRACE_ENABLED=true) |
checks / ensures | Show & normal | Normal | × (unless bUseChecksInShpping=true) | × (unless bUseChecksInShpping=true) |
日志 | √ | √ | × (unless bUseLoggingInShpping=true) | × (unless bUseLoggingInShpping=true) |
绘制调试图形 | √ | √ | × (unless UE_ENABLE_DEBUG_DRAWING=1) | × (unless UE_ENABLE_DEBUG_DRAWING=1) |
DebugGame : 游戏模块使用 Debug
,引擎模块使用 Development
取消代码优化
独立的C++文件:
- Checkout(使用P4)或修改文件(使用git),C++文件会因为
adaptive unity build
的机制单独编译- BuildConfiguration.xml:
<BuildConfiguration><bAdaptiveUnityDisableOptimizations>true</..>
- Target.cs:
bAdaptiveUnityDisablesOptimizations = true;
- BuildConfiguration.xml:
- Checkout(使用P4)或修改文件(使用git),C++文件会因为
单个模块:
- BuildConfiguration.xml:
<ModuleConfiguration><DisableOptimizeCode><Item>ModuleName</..>
- Build.cs:
OptimizeCode = CodeOptimization.InShippingBuildsOnly
orCodeOptimization.Never
- Target.cs:
DisableOptimizeCodeForModules
数组
- BuildConfiguration.xml:
代码块:
UE_DISABLE_OPTIMIZATION
/UE_ENABLE_OPTIMIZATION
UE_ENABLE_OPTIMIZATION_SHIP
/UE_DISABLE_OPTIMIZATION_SHIP
(shipping)- Target.cs:
UE_CHECK_DISABLE_OPTIMIZATION=1
在打包机上设置,避免包含代码为优化 - PC:
#pragma optimize( "", off )
/#pragma optimize( "", on )
- Clang:
#pragma clang optimize off
/#pragma clang optimize on
条件断点
FString
条件断点
wcsstr((wchar_t*)MyString.Data.AllocatorInstance.Data,L"Search substring")
FName
条件断点
strstr(((FNameEntry&)GNameBlocksDebug[MyFName.DisplayIndex.Value >> FNameDebugVisualizer::OffsetBits][FNameDebugVisualizer::EntryStride * (MyFName.DisplayIndex.Value & FNameDebugVisualizer::OffsetMask)]).AnsiName,"Search substring")
查看全局变量
在监视窗口中使用ModuleName!VariableName
查看全局变量,在Monolithic builds
中可以省略ModuleName
- UnrealEditor-Core!GConfig
- UnrealEditor-Engine!GPlayInEditorContextString
- UnrealEditor-Core!GFrameCounter
Natvis
- Visual Studio Natvis 框架可以自定数据类型在调试器变量窗口中显示的方式
- Unreal 的Natvis实现:
Engine\Extras\VisualStudioDebugging\Unreal.Natvis
- 安装方法:将
Unreal.Natvis
复制到C:\Users\<user>\Documents\Visual Studio 2022\Visualizers\
- 修改立即生效
- 安装方法:将
启动参数
- 阻塞游戏进程直到调试器挂载:
-WaitForAttach
/-WaitForDebugger
- 从已有的打包程序中启动调试:
-basedir=E:\path\to\GameName\Binaries\Win64
- 使用
-ini
参数覆盖ini文件中的配置参数:ini:File:[SectionName]:Key=Value
- 使用
-DPCVars
覆盖DeviceProfile CVar:-DPCVars="r.cvarname=foo,anothercvar=bar
- 使用
-execcmds
在启动后自动执行控制台命令:-exccmds="log global error"
Cook确定性
- 未修改任何资源多次Cook产物不一致
- 第二次Cook时添加参数
-DiffOnly
内存分析
- 控制台命令:
memreport -full [-csv|-name=X]
- 生成完整内存报告,保存至
Engine/Saved/Profiling/MemReports
- 生成完整内存报告,保存至
- 启动参数:
-LLM -LLMcsv
- 生成LLM记录,保存至
Engine/Saved/Profiling/LLM
- CsvTools:
csvtosvg -csv xxx.csv -stats *
- 生成LLM记录,保存至
- 特定内存问题:
-stompmalloc
或ASAN
- Unreal Insights
崩溃分析
崩溃后游戏会创建一个文件
Saved/Crashes
- UEMinidump.dmp (MiniDumpWriteDump)
- CrashContext.runtime-xml: 额外上下文的信息(-CrashReproter)
- GameName.Log
模拟产生崩溃
- 控制台命令:
Debug Crash
- RenderCrash / ThreadCrash / GPUCrash /...
- Abort / Stall / OOM / StackOverflow / Sleep /...
- 控制台命令:
-将dmp和pdb文件放在同一个路径下 - 打包时隐藏符号:-nodebuginfo
调试工具
Unreal Insights
启动方式:
-trace=default,task,memory,cook -tracehost=127.0.0.1
-tracehost=127.0.0.1 -> -tracefile
文档: https://docs.unrealengine.com/5.3/zh-CN/unreal-insights-in-unreal-engine/
RenderDoc
启动方式:
- 开启RenderDoc软件
- 并在
项目设置->插件->RenderDoc
中勾选启动时自动附加
- 点击
Viewport
右上角图标/控制台命令Renderdoc.CaptureFrame
- 调试Shader额外操作:
- 修改
Engine/Config/ConsoleVariables.ini
- r.Shaders.Optimize=0
- r.Shaders.Symbols=1
- 默认RHI切换为
D3D11
- 修改
GPU调试 - PIX
GPU调试 - Xcode
- GPU Trace
- Instruments