游戏引擎 / 系统课时
用日志定位Gameplay故障
用日志定位Gameplay故障
Gameplay 出现“按键有响应但伤害没发生”“服务器正常而客户端失败”时,最有效的做法不是一次打印所有状态,而是沿执行链逐段证明代码到底走到了哪里。本节使用自定义日志分类、关键上下文和成对入口/出口日志,把故障范围缩小到具体阶段。
学习目标
- 为 Gameplay 建立可过滤的日志分类,而不是长期依赖
LogTemp。 - 记录 Actor、Authority、关键输入与状态变化,判断故障发生在哪一段。
- 用日志级别和二分式加点方法减少噪声,并在修复后复核完整执行链。
先沿执行链缩小范围
假设“攻击命中后没有扣血”,不要先猜伤害公式。先把链路拆成可证明的阶段:输入是否触发、攻击逻辑是否执行、命中检测是否得到目标、服务器是否拥有 Authority、伤害函数是否进入、生命值是否真正变化。

定位时只需要找“最后一条出现的预期日志”和“第一条缺失的预期日志”。如果 Hit Result 已出现而 Damage Function 没出现,调查范围就从整套战斗系统缩小到了命中结果之后、伤害调用之前。
建立可过滤的日志分类
长期调试应使用自定义分类,这样 Output Log、命令行日志和配置文件都可以只显示当前系统。片段示例:以下代码依赖已有 UE5 C++ 项目,需作为一个 Actor 类加入项目并放入测试关卡;它定义 LogGameplayDebug,并在关卡开始后主动执行一次伤害探针。
// GameplayLogProbe.h
#pragma once
#include "CoreMinimal.h"
#include "GameFramework/Actor.h"
#include "GameplayLogProbe.generated.h"
DECLARE_LOG_CATEGORY_EXTERN(LogGameplayDebug, Log, All);
UCLASS()
class MYGAME_API AGameplayLogProbe : public AActor
{
GENERATED_BODY()
public:
AGameplayLogProbe();
protected:
virtual void BeginPlay() override;
private:
float Health = 100.0f;
void ApplyDamageProbe(float Damage);
};// GameplayLogProbe.cpp
#include "GameplayLogProbe.h"
DEFINE_LOG_CATEGORY(LogGameplayDebug);
AGameplayLogProbe::AGameplayLogProbe()
{
PrimaryActorTick.bCanEverTick = false;
}
void AGameplayLogProbe::BeginPlay()
{
Super::BeginPlay();
UE_LOG(
LogGameplayDebug,
Display,
TEXT("BeginPlay Actor=%s Authority=%s Health=%.1f"),
*GetName(),
HasAuthority() ? TEXT("true") : TEXT("false"),
Health
);
ApplyDamageProbe(25.0f);
}
void AGameplayLogProbe::ApplyDamageProbe(float Damage)
{
UE_LOG(
LogGameplayDebug,
Display,
TEXT("Enter ApplyDamageProbe Actor=%s Damage=%.1f"),
*GetName(),
Damage
);
if (!HasAuthority())
{
UE_LOG(
LogGameplayDebug,
Warning,
TEXT("Reject ApplyDamageProbe: Actor=%s has no authority"),
*GetName()
);
return;
}
const float Before = Health;
Health = FMath::Clamp(Health - Damage, 0.0f, 100.0f);
UE_LOG(
LogGameplayDebug,
Display,
TEXT("Exit ApplyDamageProbe Actor=%s Health %.1f -> %.1f"),
*GetName(),
Before,
Health
);
}把该 Actor 放进单机 PIE 关卡并运行。Actor 实例编号属于动态值,因此以下用 <ID> 表示。
预期输出
LogGameplayDebug: Display: BeginPlay Actor=GameplayLogProbe_<ID> Authority=true Health=100.0
LogGameplayDebug: Display: Enter ApplyDamageProbe Actor=GameplayLogProbe_<ID> Damage=25.0
LogGameplayDebug: Display: Exit ApplyDamageProbe Actor=GameplayLogProbe_<ID> Health 100.0 -> 75.0如果在客户端副本上直接执行同一函数,入口日志仍会出现,但随后应出现 has no authority 警告并提前返回。这个差异能直接证明问题是“调用到了错误网络角色”,而不是扣血计算本身失效。
记录能解释故障的上下文
一条有价值的 Gameplay 日志通常回答四个问题:哪个对象、在哪个网络上下文、带着什么输入、状态从什么变成什么。不要只打印“进入函数”,因为多人 PIE 时多个 Actor 会产生几乎相同的输出。
对于攻击、交互、拾取这类链路,建议优先记录 GetName()、HasAuthority()、目标对象、关键数值和结果状态。指针为空时不要直接解引用;先输出目标是否有效,再在确认有效后记录名称或属性。
用级别和过滤控制噪声
把“每帧都会发生”的细节放到 Verbose 或 VeryVerbose,把关键状态变化放到 Display 或 Log,可恢复异常放到 Warning,真正破坏执行前提的问题再使用 Error。不要把正常分支长期标成 Error,否则真正故障会淹没在红色日志里。
运行时可以在控制台使用 Log LogGameplayDebug VeryVerbose 临时提高该分类的详细程度;排查结束后再降低级别。对于高频 Tick、移动或网络同步日志,还应增加条件,只在值变化、阈值越界或特定 Actor 上输出。
用相邻日志验证修复
修复后不要只验证“结果看起来正常”,还要重新跑一遍完整链路。预期至少能看到入口、关键判定和最终状态三类日志,并确认它们来自正确 Actor 与正确 Authority。
如果日志在某两个检查点之间断开,就继续在这一区间增加一个新的检查点,而不是把整个函数每行都打印一次。这种二分式加点可以快速缩小故障范围,同时保持日志可读;等根因确认后,删除临时高频日志,只保留对线上诊断仍有价值的分类和关键状态变化。