本文档详细介绍 Unreal Engine 5.6 GameplayCameras 插件的调试功能、控制台命令、调试器界面以及自定义调试扩展方法。
目录
1. 调试系统概述
1.1 架构设计
GameplayCameras 的调试系统采用调试块 (Debug Block) 架构,每个相机节点、服务和评估结果都可以生成独立的调试信息块。
┌─────────────────────────────────────────────────────────────────┐
│ FRootCameraDebugBlock │
├─────────────────────────────────────────────────────────────────┤
│ ├── FCategoryTitleDebugBlock (DirectorTree) │
│ │ └── FCameraDirectorTreeDebugBlock │
│ ├── FCategoryTitleDebugBlock (NodeTree) │
│ │ └── FCameraNodeEvaluatorDebugBlock (per node) │
│ │ └── FCameraPoseDebugBlock │
│ ├── FCategoryTitleDebugBlock (Services) │
│ │ └── FCameraEvaluationServiceDebugBlock (per service) │
│ ├── FCategoryTitleDebugBlock (PoseStats) │
│ │ └── FCameraNodeEvaluationResultDebugBlock │
│ └── FViewfinderDebugBlock │
└─────────────────────────────────────────────────────────────────┘
### 1.2 调试开关宏
```cpp
// 源码位置: Public/GameplayCameras.h
#ifndef UE_GAMEPLAY_CAMERAS_DEBUG
#if UE_ENABLE_DEBUG_DRAWING
#define UE_GAMEPLAY_CAMERAS_DEBUG 1
#else
#define UE_GAMEPLAY_CAMERAS_DEBUG 0
#endif
#endif
注意: 调试功能仅在 Debug 和 Development 构建中可用,Shipping 构建会自动移除所有调试代码。
2. 启用调试功能
2.1 基本启用方式
方式一:控制台命令
GameplayCameras.Debug.Enable 1
方式二:编辑器工具栏
在 Camera Debugger 工具栏点击 "Debug Info Enabled" 按钮切换。
2.2 绑定到相机系统实例
当场景中存在多个相机系统时,需要指定调试哪个实例:
# 自动绑定到当前视口目标
GameplayCameras.Debug.SystemID 0
# 绑定到指定 ID 的相机系统
GameplayCameras.Debug.SystemID 1
# 显示所有相机系统的调试信息
GameplayCameras.Debug.SystemID -1
2.3 选择调试类别
# 显示单个类别
GameplayCameras.Debug.Categories nodetree
# 显示多个类别(逗号分隔)
GameplayCameras.Debug.Categories nodetree,blendstacks,posestats
3. Camera Debugger 编辑器工具
3.1 打开调试器
菜单路径: Tools > Debug > Camera Debugger
或者使用 Tab 菜单: 在任意 Tab 栏右键 > Misc > Camera Debugger
3.2 调试器界面布局
┌─────────────────────────────────────────────────────────────────┐
│ [MenuBar] │
├─────────────────────────────────────────────────────────────────┤
│ [Toolbar] │
│ ├── [Debug Info Enabled] ← 切换调试显示 │
│ ├── [Bind to...] ← 选择绑定的相机系统 │
│ └── [Debug Categories] ← 切换调试类别标签 │
├─────────────────────────────────────────────────────────────────┤
│ │
│ [Debug Panel Content] │
│ ← 当前选中类别的专用控制面板 │
│ │
├─────────────────────────────────────────────────────────────────┤
│ [General Options] (可折叠) │
│ ├── Top margin / Left margin / Inner margin │
│ ├── Indent size │
│ └── Color scheme │
└─────────────────────────────────────────────────────────────────┘
3.3 工具栏功能详解
| 按钮 | 功能 |
|---|---|
| Debug Info Enabled | 全局开关,启用/禁用调试信息显示 |
| Bind to... | 选择要调试的相机系统实例 |
| NodeTree | 显示相机节点树调试信息 |
| DirectorTree | 显示导演树调试信息 |
| BlendStacks | 显示混合栈调试信息 |
| Services | 显示评估服务调试信息 |
| PoseStats | 显示相机姿态统计信息 |
| Viewfinder | 显示取景器覆盖层 |
3.4 绑定相机系统
点击 "Bind to..." 下拉菜单可以看到:
- Auto-bind to the current view target: 自动跟随当前玩家控制器的视口目标
- 相机系统列表: 显示所有已注册的相机系统实例及其 ID
4. 控制台命令参考
4.1 核心调试命令
| 命令 | 默认值 | 说明 |
|---|---|---|
GameplayCameras.Debug.Enable |
0 |
启用调试显示 |
GameplayCameras.Debug.SystemID |
-1 |
指定调试的相机系统 ID |
GameplayCameras.Debug.Categories |
nodetree |
要显示的调试类别 |
GameplayCameras.Debug.Trace |
0 |
启用追踪记录 |
4.2 布局命令
| 命令 | 默认值 | 说明 |
|---|---|---|
GameplayCameras.Debug.TopMargin |
10 |
顶部边距(像素) |
GameplayCameras.Debug.LeftMargin |
10 |
左侧边距(像素) |
GameplayCameras.Debug.RightMargin |
10 |
右侧边距(像素) |
GameplayCameras.Debug.InnerMargin |
5 |
内部间距(像素) |
GameplayCameras.Debug.Indent |
20 |
缩进宽度(像素) |
4.3 卡片布局命令
| 命令 | 默认值 | 说明 |
|---|---|---|
GameplayCameras.Debug.CardWidth |
200 |
调试卡片宽度(像素) |
GameplayCameras.Debug.CardHeight |
250 |
调试卡片高度(像素) |
GameplayCameras.Debug.CardGap |
10 |
卡片间距(像素) |
GameplayCameras.Debug.MaxCardColumns |
2 |
最大卡片列数 |
4.4 视觉效果命令
| 命令 | 默认值 | 说明 |
|---|---|---|
GameplayCameras.Debug.DrawBackground |
1 |
绘制背景 |
GameplayCameras.Debug.BackgroundOpacity |
0.85 |
背景透明度 |
GameplayCameras.Debug.BackgroundDepthSortKey |
1 |
背景深度排序键 |
GameplayCameras.Debug.ColorScheme |
SolarizedDark |
颜色方案名称 |
4.5 3D 绘制命令
| 命令 | 默认值 | 说明 |
|---|---|---|
GameplayCameras.Debug.DefaultCameraSize |
50 |
相机图标大小 |
GameplayCameras.Debug.DefaultCoordinateSystemAxesLength |
100 |
坐标轴长度 |
4.6 节点树命令
| 命令 | 默认值 | 说明 |
|---|---|---|
GameplayCameras.Debug.NodeTree.Filter |
"" |
节点名称过滤器 |
4.7 混合栈命令
| 命令 | 默认值 | 说明 |
|---|---|---|
GameplayCameras.Debug.BlendStack.ShowUnchanged |
0 |
显示未改变的属性 |
GameplayCameras.Debug.BlendStack.ShowVariableIDs |
0 |
显示变量 ID |
4.8 姿态统计命令
| 命令 | 默认值 | 说明 |
|---|---|---|
GameplayCameras.Debug.PoseStats.ShowUnchanged |
0 |
显示未改变的属性 |
GameplayCameras.Debug.PoseStats.ShowVariableIDs |
0 |
显示变量 ID |
4.9 上下文初始结果命令
| 命令 | 默认值 | 说明 |
|---|---|---|
GameplayCameras.Debug.ContextInitialResult.ShowUnchanged |
0 |
显示未改变的属性 |
4.10 方向初始化服务命令
| 命令 | 默认值 | 说明 |
|---|---|---|
GameplayCameras.Debug.OrientationInitialization.ShowLastTargetPreservation |
0 |
显示上次目标保持 |
4.11 玩家控制旋转服务命令
| 命令 | 默认值 | 说明 |
|---|---|---|
GameplayCameras.ControlRotation.DebugArrowLength |
200 |
调试箭头长度 |
4.12 取景器命令
| 命令 | 默认值 | 说明 |
|---|---|---|
GameplayCameras.Debug.Viewfinder.ReticleSizeFactor |
0.5 |
十字线大小因子 |
GameplayCameras.Debug.Viewfinder.ReticleInnerSizeFactor |
0.25 |
十字线内部大小因子 |
GameplayCameras.Debug.Viewfinder.ReticleNumSides |
4 |
十字线边数 |
GameplayCameras.Debug.Viewfinder.GuidesGapFactor |
0.1 |
引导线间距因子 |
4.13 图表命令
| 命令 | 默认值 | 说明 |
|---|---|---|
GameplayCameras.Debug.Graph.Padding |
10 |
图表内边距 |
GameplayCameras.Debug.Graph.DefaultHistoryTime |
3 |
默认历史时间(秒) |
4.14 时钟命令
| 命令 | 默认值 | 说明 |
|---|---|---|
GameplayCameras.Debug.Clock.Padding |
10 |
时钟内边距 |
GameplayCameras.Debug.Clock.ArrowThickness |
3 |
指针粗细 |
5. 调试类别详解
5.1 NodeTree (节点树)
显示当前激活的相机节点树结构及每个节点的评估状态。
显示内容:
- 节点名称和类型
- 节点参数值
- 子节点层级关系
- 节点评估结果(位置、旋转、FOV 等)
过滤节点:
GameplayCameras.Debug.NodeTree.Filter BoomArm
5.2 DirectorTree (导演树)
显示相机导演的评估信息。
显示内容:
- 当前激活的导演
- 激活/停用请求
- 上下文栈状态
- 初始结果信息
5.3 BlendStacks (混合栈)
显示四层混合栈的状态信息。
显示内容:
- Base Layer: 基础层相机装备
- Main Layer: 主层相机装备及混合进度
- Global Layer: 全局效果层
- Visual Layer: 视觉效果层
专用选项:
- Show unchanged properties: 显示未改变的属性值
- Show variable IDs: 显示变量表的变量 ID
5.4 Services (服务)
显示评估服务的状态。
显示内容:
- CameraShakeService: 相机震动状态
- CameraModifierService: 相机修饰符
- ParameterSetterService: 参数设置器
- OrientationInitializationService: 方向初始化
5.5 PoseStats (姿态统计)
显示最终评估的相机姿态详细信息。
显示内容:
- Location (位置)
- Rotation (旋转)
- Field of View (视场角)
- Target Distance (目标距离)
- 物理相机参数
- 变量表值
5.6 Viewfinder (取景器)
在视口中叠加显示取景器 UI。
显示内容:
- 画面中心十字线
- 安全区域框
- 构图引导线
6. 调试可视化元素
6.1 3D 调试绘制
调试系统支持在 3D 空间中绘制以下元素:
// 绘制方法 (FCameraDebugRenderer)
void DrawLine(Start, End, Color, Thickness); // 线条
void DrawBox(Center, Size, Color, Thickness); // 盒子
void DrawSphere(Center, Radius, Segments, Color); // 球体
void DrawDirectionalArrow(Start, End, ArrowSize); // 方向箭头
void DrawCamera(Transform, FOV, AspectRatio); // 相机图标
void DrawCoordinateSystem(Location, Rotation); // 坐标系
void DrawText(WorldPosition, Text, Color); // 3D 文字
6.2 2D 调试绘制
在屏幕空间中绘制:
void Draw2DPointCross(Location, Size, Color); // 十字点
void Draw2DLine(Start, End, Color); // 2D 线条
void Draw2DBox(Position, Size, Color); // 2D 盒子
void Draw2DCircle(Center, Radius, Color); // 2D 圆形
6.3 文本墙 (Text Wall)
屏幕左侧的文本信息显示区域:
// 文本墙操作
Renderer.AddText("Text content"); // 添加文本
Renderer.NewLine(); // 换行
Renderer.AddIndent(); // 增加缩进
Renderer.RemoveIndent(); // 减少缩进
Renderer.SetTextColor(Color); // 设置颜色
6.4 调试卡片 (Debug Cards)
屏幕右侧的卡片式信息展示:
- 调试时钟 (Clock): 显示角度或 2D 向量
- 调试图表 (Graph): 显示数值变化曲线
7. 颜色方案配置
7.1 内置颜色方案
SolarizedDark (默认):
Title: #268bd2 (蓝色)
Default: #eee8d5 (浅色)
Passive: #93a1a1 (灰色)
Highlighted: #fdf6e3 (亮白)
Notice: #2aa198 (青色)
Notice2: #d33682 (品红)
Good: #859900 (绿色)
Warning: #b58900 (黄色)
Error: #dc322f (红色)
Background: #002b36 (深蓝黑)
SolarizedLight:
Title: #268bd2 (蓝色)
Default: #586e75 (深灰)
Passive: #657b83 (灰色)
Highlighted: #002b36 (深色)
Notice: #2aa198 (青色)
Notice2: #d33682 (品红)
Good: #859900 (绿色)
Warning: #b58900 (黄色)
Error: #dc322f (红色)
Background: #fdf6e3 (浅白)
7.2 切换颜色方案
GameplayCameras.Debug.ColorScheme SolarizedLight
7.3 代码中注册自定义颜色方案
FCameraDebugColors MyColorScheme;
MyColorScheme.Title = FColor::Cyan;
MyColorScheme.Default = FColor::White;
MyColorScheme.Passive = FColor::Gray;
MyColorScheme.Warning = FColor::Yellow;
MyColorScheme.Error = FColor::Red;
MyColorScheme.Background = FColor(30, 30, 30);
FCameraDebugColors::RegisterColorScheme(TEXT("MyScheme"), MyColorScheme);
8. 自定义调试扩展
8.1 创建自定义调试块
// MyDebugBlock.h
#pragma once
#include "Debug/CameraDebugBlock.h"
#if UE_GAMEPLAY_CAMERAS_DEBUG
namespace UE::Cameras
{
// 方式一:简单调试块(使用宏自动序列化)
UE_DECLARE_CAMERA_DEBUG_BLOCK_START(MYMODULE_API, FMyDebugBlock)
UE_DECLARE_CAMERA_DEBUG_BLOCK_FIELD(float, MyFloatValue)
UE_DECLARE_CAMERA_DEBUG_BLOCK_FIELD(bool, MyBoolValue)
UE_DECLARE_CAMERA_DEBUG_BLOCK_FIELD(FVector3d, MyVectorValue)
UE_DECLARE_CAMERA_DEBUG_BLOCK_END()
// 方式二:完全自定义调试块
class FMyCustomDebugBlock : public FCameraDebugBlock
{
UE_DECLARE_CAMERA_DEBUG_BLOCK(MYMODULE_API, FMyCustomDebugBlock)
public:
// 数据成员
float Speed = 0.f;
FVector3d TargetLocation = FVector3d::ZeroVector;
FString StatusText;
protected:
virtual void OnDebugDraw(const FCameraDebugBlockDrawParams& Params,
FCameraDebugRenderer& Renderer) override;
virtual void OnSerialize(FArchive& Ar) override;
};
} // namespace UE::Cameras
#endif
8.2 实现调试绘制
// MyDebugBlock.cpp
#include "MyDebugBlock.h"
#if UE_GAMEPLAY_CAMERAS_DEBUG
namespace UE::Cameras
{
// 简单调试块实现
UE_DEFINE_CAMERA_DEBUG_BLOCK_WITH_FIELDS(FMyDebugBlock)
// 自定义调试块实现
UE_DEFINE_CAMERA_DEBUG_BLOCK(FMyCustomDebugBlock)
void FMyCustomDebugBlock::OnDebugDraw(
const FCameraDebugBlockDrawParams& Params,
FCameraDebugRenderer& Renderer)
{
// 检查类别是否激活
if (!Params.ActiveCategories.Contains(TEXT("MyCategory")))
{
return;
}
// 绘制文本信息
Renderer.AddText(TEXT("My Custom Debug Info"));
Renderer.AddIndent();
Renderer.SetTextColor(FCameraDebugColors::Get().Notice);
Renderer.AddText(TEXT("Speed: %f"), Speed);
Renderer.NewLine();
Renderer.AddText(TEXT("Status: %s"), *StatusText);
Renderer.RemoveIndent();
Renderer.NewLine();
// 绘制 3D 元素
Renderer.DrawSphere(TargetLocation, 20.f, 12, FLinearColor::Green);
Renderer.DrawCoordinateSystem(TargetLocation, FRotator3d::ZeroRotator, 50.f);
}
void FMyCustomDebugBlock::OnSerialize(FArchive& Ar)
{
FCameraDebugBlock::OnSerialize(Ar);
Ar << Speed;
Ar << TargetLocation;
Ar << StatusText;
}
} // namespace UE::Cameras
#endif
8.3 在节点评估器中构建调试块
void FMyCameraNodeEvaluator::OnRun(
const FCameraNodeEvaluationParams& Params,
FCameraNodeEvaluationResult& OutResult)
{
// ... 节点评估逻辑 ...
#if UE_GAMEPLAY_CAMERAS_DEBUG
// 构建调试块(调试构建中执行)
if (FCameraDebugBlockBuilder* DebugBuilder = Params.DebugBuilder)
{
FMyCustomDebugBlock& DebugBlock =
DebugBuilder->StartChildDebugBlock<FMyCustomDebugBlock>();
DebugBlock.Speed = CurrentSpeed;
DebugBlock.TargetLocation = TargetPos;
DebugBlock.StatusText = bIsActive ? TEXT("Active") : TEXT("Inactive");
DebugBuilder->EndChildDebugBlock();
}
#endif
}
8.4 注册自定义调试类别
// 在模块启动时注册
void FMyModule::StartupModule()
{
#if UE_GAMEPLAY_CAMERAS_DEBUG
IGameplayCamerasEditorModule* CamerasEditorModule =
FModuleManager::GetModulePtr<IGameplayCamerasEditorModule>(
TEXT("GameplayCamerasEditor"));
if (CamerasEditorModule)
{
FCameraDebugCategoryInfo MyCategory;
MyCategory.Name = TEXT("MyCategory");
MyCategory.DisplayText = LOCTEXT("MyCategory", "My Category");
MyCategory.ToolTipText = LOCTEXT("MyCategoryTooltip", "My custom debug category");
MyCategory.IconImage = FSlateIcon("MyModuleStyle", "DebugIcon");
CamerasEditorModule->RegisterDebugCategory(MyCategory);
}
#endif
}
8.5 创建自定义调试面板
// SMyDebugPanel.h
class SMyDebugPanel : public SCompoundWidget
{
public:
SLATE_BEGIN_ARGS(SMyDebugPanel) {}
SLATE_END_ARGS()
void Construct(const FArguments& InArgs);
};
// SMyDebugPanel.cpp
void SMyDebugPanel::Construct(const FArguments& InArgs)
{
using namespace UE::Cameras;
ChildSlot
[
SNew(SVerticalBox)
+ SVerticalBox::Slot()
.AutoHeight()
[
// 使用工具方法创建控制台变量复选框
SDebugWidgetUtils::CreateConsoleVariableCheckBox(
LOCTEXT("MyOption", "Enable My Debug Option"),
TEXT("GameplayCameras.Debug.MyOption"))
]
+ SVerticalBox::Slot()
.AutoHeight()
[
// 使用工具方法创建控制台变量数值输入框
SDebugWidgetUtils::CreateConsoleVariableSpinBox(
TEXT("GameplayCameras.Debug.MyValue"))
]
];
}
9. 调试最佳实践
9.1 调试流程建议
1. 启动 PIE (Play In Editor)
2. 打开 Camera Debugger 工具
3. 点击 "Debug Info Enabled" 启用调试
4. 使用 "Bind to..." 选择目标相机系统
5. 切换到需要的调试类别标签
6. 根据需要调整 General Options
9.2 性能考虑
- Shipping 构建: 所有调试代码会被编译器移除,零运行时开销
- Development 构建: 调试代码存在,但仅在启用时执行
- 启用调试时: 会有一定的性能开销,不建议在性能测试时启用
9.3 常用调试命令组合
完整调试信息:
GameplayCameras.Debug.Enable 1
GameplayCameras.Debug.Categories nodetree,blendstacks,posestats,services
GameplayCameras.Debug.PoseStats.ShowUnchanged 1
仅节点树调试:
GameplayCameras.Debug.Enable 1
GameplayCameras.Debug.Categories nodetree
GameplayCameras.Debug.NodeTree.Filter BoomArm
混合栈调试:
GameplayCameras.Debug.Enable 1
GameplayCameras.Debug.Categories blendstacks
GameplayCameras.Debug.BlendStack.ShowUnchanged 1
GameplayCameras.Debug.BlendStack.ShowVariableIDs 1
9.4 调试相机切换问题
- 启用 DirectorTree 类别查看激活请求
- 启用 BlendStacks 类别查看混合进度
- 检查过渡配置是否正确
- 确认相机装备的 Layer 设置
9.5 调试相机位置/旋转问题
- 启用 NodeTree 类别
- 检查每个节点的输出
- 确认节点执行顺序
- 查看 PoseStats 中的最终结果
10. 常见问题排查
10.1 调试信息不显示
可能原因:
- 调试未启用 → 运行
GameplayCameras.Debug.Enable 1 - 相机系统未绑定 → 检查 "Bind to..." 设置
- 类别未激活 → 检查 Categories 设置
- 构建类型不对 → 确保使用 Debug 或 Development 构建
10.2 找不到相机系统
解决方案:
- 确保 UGameplayCameraComponent 已正确添加到 Actor
- 检查相机组件是否激活
- 确认 Camera Asset 已设置
10.3 调试信息显示位置不对
调整方法:
GameplayCameras.Debug.TopMargin 50
GameplayCameras.Debug.LeftMargin 50
10.4 文字看不清
解决方案:
- 切换颜色方案:
GameplayCameras.Debug.ColorScheme SolarizedLight - 调整背景透明度:
GameplayCameras.Debug.BackgroundOpacity 0.9
10.5 调试卡片太小/太大
调整方法:
GameplayCameras.Debug.CardWidth 300
GameplayCameras.Debug.CardHeight 350
附录 A: 调试相关源码文件
| 文件 | 说明 |
|---|---|
Debug/CameraDebugBlock.h |
调试块基类 |
Debug/CameraDebugRenderer.h |
调试渲染器 |
Debug/CameraDebugCategories.h |
调试类别定义 |
Debug/CameraDebugColors.h |
颜色方案 |
Debug/CameraDebugGraph.h |
调试图表 |
Debug/CameraDebugClock.h |
调试时钟 |
Debug/RootCameraDebugBlock.h |
根调试块 |
Debug/CameraSystemDebugRegistry.h |
相机系统注册表 |
Debug/CameraNodeEvaluatorDebugBlock.h |
节点调试块 |
Debug/CameraPoseDebugBlock.h |
姿态调试块 |
Debug/BlendStacksCameraDebugBlock.h |
混合栈调试块 |
Debugger/SGameplayCamerasDebugger.h |
调试器界面 |
附录 B: 调试宏速查
// 声明调试块
UE_DECLARE_CAMERA_DEBUG_BLOCK(ApiSpec, ClassName)
UE_DECLARE_CAMERA_DEBUG_BLOCK_EX(ApiSpec, ClassName, BaseClassName)
// 定义调试块
UE_DEFINE_CAMERA_DEBUG_BLOCK(ClassName)
// 简单调试块宏(带字段)
UE_DECLARE_CAMERA_DEBUG_BLOCK_START(ApiSpec, ClassName)
UE_DECLARE_CAMERA_DEBUG_BLOCK_FIELD(Type, Name)
UE_DECLARE_CAMERA_DEBUG_BLOCK_END()
UE_DEFINE_CAMERA_DEBUG_BLOCK_WITH_FIELDS(ClassName)
本文档基于 Unreal Engine 5.6 GameplayCameras 插件源码编写
最后更新: 2026-02-26