中EN
概念页

Gameplay 调试器与可视化日志

Gameplay Debugger & Visual Logger

更新于 2026-10-11 约 3 分钟UE5调试Gameplay DebuggerVisual LoggerAI

Gameplay 调试器 (GDT) 用于在运行时实时查看玩法数据(Pawn、AIController、行为树与黑板、EQS、感知、导航网格),联网时客户端也能看,并且只复制已启用类别的数据。可视化日志 (Visual Logger) 则把 Actor 的状态和图形化信息录下来,之后在编辑器里按时间轴来回拖动查看,适合排查难以复现的 bug。

Gameplay 调试器:看「现在」

  • 能显示 Pawn 和 AIController 的基本数据、行为树与黑板、执行过的环境查询 (EQS)、感知系统信息,以及玩家或所选 Pawn 周围的导航网格(含链接和区域)。数据量很大,所以按类别限制屏幕上显示的内容;只复制已启用类别的数据,以节省复制通道带宽。默认有 5 个类别(Navmesh、Basic、Behavior Tree、EQS、Perception),另有 5 个类别留给项目使用,已有类别也可以扩展。(Using the Gameplay Debugger in Unreal Engine)
  • 默认按撇号键 '(或用 EnableGDT 作弊命令)激活;准星对准敌人时按 ' 选中它作为调试目标;用小键盘切换类别。PIE 和 Simulate 中都可以用。项目必须把 GameplayDebugger 模块加入依赖模块才能使用。(Using the Gameplay Debugger in Unreal Engine)
  • 它与 行为树与 StateTree、AI 感知、EQS 与导航 搭配使用效果最好;在联网游戏中,客户端看到的就是通过复制传过来的数据(复制机制见 网络复制与 RPC)。

Visual Logger:回看「过去」

  • 它创建并录制玩法状态的可视化表示,并提供在编辑器中回看的能力。官方例子:某个只变化了一帧的状态变量引起了异常的 AI 行为,录下来后可以在出 bug 的时刻前后逐帧拖动研究。从 Windows > Developer Tools > Visual Logger 打开。(Visual Logger in Unreal Engine)
  • 视口包含:记录过数据的 Actor 列表、所选 Actor 的状态快照、文本输出窗口,以及用于拖动的时间轴。(Visual Logger in Unreal Engine)
  • 写日志:UE_VLOG 宏输出文本,参数是关联的 Actor、日志类别和详细级别(用于过滤)以及文本。它在不支持 Visual Logging 的构建中会被自动编译掉,所以可以放心使用,不必包 ENABLE_VISUAL_LOG 检查。(Visual Logger in Unreal Engine)
  • 自定义快照:实现 IVisualLoggerDebugSnapshotInterface::GrabDebugSnapshot(FVisualLogEntry*),往 Snapshot->Status 里添加类别和键值对。因为它只应在启用 Visual Logging 的构建中运行,最好用 #if ENABLE_VISUAL_LOG 包起来。(Visual Logger in Unreal Engine)

怎么选

需求工具
实时看 AI 在想什么,包括在联网客户端上看Gameplay 调试器
bug 很少出现、事后才发现Visual Logger 录制后回看
性能问题(耗时、帧率)Unreal Insights,见 UE5 性能分析
想防止问题再次出现自动化测试

(表格是对上述两页及相关页面的归纳。)

  1. Using the Gameplay Debugger in Unreal Engine UE 5.8 文档
  2. Visual Logger in Unreal Engine UE 5.8 文档

相关页面

游戏开发 · UE5行为树与 StateTreeBehavior Tree & StateTreeUE 的 AI 决策有两套工具:行为树 (Behavior Tree) + 黑板 (Blackboard) 是事件驱动的,条件写成装饰器 (Decorator),用 Simple Parallel、Services 和 Observer Aborts 代替传统并行节点;StateTree 是结合了行为树选择器和状态机转换的通用分层状态机,只在转换触发时按需选择状态,激活路径上的任务并发运行,通过属性绑定传递数据,也是 Mass 的行为层。优先级抢占多的战斗 AI 适合行为树,状态显式、分层或大规模的场景适合 StateTree。游戏开发 · UE5AI 感知、EQS 与导航AI Perception, EQS & NavigationAI 的感官层由三块组成:AI 感知 (AI Perception) 组件挂在 AIController 上监听视觉/听觉/伤害等刺激并更新黑板;环境查询系统 (EQS) 用生成器产生候选项、先过滤后打分,回答「哪里最好」;导航系统从碰撞几何生成分瓦片的导航网格 (NavMesh),按多边形代价寻路,并提供 RVO 与 Detour Crowd 避让。它们为行为树/StateTree 提供输入。游戏开发 · UE5UE5 性能分析UE5 ProfilingUE5 性能分析的基本流程是:先用 stat unit 判断瓶颈在游戏线程、渲染线程还是 GPU,再用对应的 stat 组、profilegpu/GPU 统计或 Unreal Insights 的 Timing/Memory 等视图向下钻取;渲染特性(RDG、VSM、TSR)各自提供作用域和可视化。测量时要避开会扭曲数据的设置(调试构建、异步计算、可视化模式)。游戏开发 · UE5网络复制与 RPCNetwork Replication & RPCUE 采用服务器权威 (Server-Authoritative) 的客户端-服务器模型:游戏真正在服务器上进行,服务器把状态复制 (Replication) 给客户端,客户端通过远程过程调用 (Remote Procedure Call, RPC) 向服务器请求操作。开发者需要显式声明哪些 Actor、属性、函数要走网络,并借助所有权、网络角色、相关性、优先级控制“发给谁、发多少”。UE 5.8 提供通用复制系统、Replication Graph 和实验性的 Iris 三套复制系统。游戏开发 · UE5自动化测试Automation TestingUE 的自动化系统 (Automation System) 构建在功能测试框架之上,支持单元测试、功能测试、内容压力测试和截图对比,并借助 Unreal Message Bus 提高稳定性。测试按用途分为 Unit、Feature、Smoke(承诺 1 秒内完成)、Content Stress 和 Screenshot Comparison。它依赖引擎系统运行,所以不适合纯粹的单元测试;这种情况用 Low-Level Tests。跨进程的整局会话测试用 Gauntlet。游戏开发日志与调试绘制Logging & Debug Drawing几乎所有专业团队都会为引擎打造一套调试与开发工具。本页记录其中最基础的两类:日志与追踪(格式化调试输出、详细级别、通道、镜像到文件、崩溃报告)和调试绘制(在游戏世界或屏幕上画线、形状和文字以可视化数学计算)。(卷 I 第 10 章 引言、10.1–10.2 节)游戏开发游戏内调试工具In-Game Debugging Tools各子系统(渲染、动画、碰撞、物理、音频、网络、玩家机制、AI……)都有大量配置项,能在游戏运行时调整而无需改代码、重新编译链接再运行,可大幅节省调试和搭建关卡/玩法的时间。GEA 介绍支撑这一点的几类游戏内工具:游戏内菜单(及 Dear ImGui 等第三方 GUI)、游戏内控制台、调试摄像机与暂停/慢动作、作弊功能、截图与录像。(卷 I 10.3–10.7 节)

输入关键词开始搜索

滚轮或双指缩放 · 拖动平移 · 双击放大 / 还原