游戏引擎 / 系统课时

用日志定位Gameplay故障

用日志定位Gameplay故障

Gameplay 出现“按键有响应但伤害没发生”“服务器正常而客户端失败”时,最有效的做法不是一次打印所有状态,而是沿执行链逐段证明代码到底走到了哪里。本节使用自定义日志分类、关键上下文和成对入口/出口日志,把故障范围缩小到具体阶段。

学习目标

  • 为 Gameplay 建立可过滤的日志分类,而不是长期依赖 LogTemp。
  • 记录 Actor、Authority、关键输入与状态变化,判断故障发生在哪一段。
  • 用日志级别和二分式加点方法减少噪声,并在修复后复核完整执行链。

先沿执行链缩小范围

假设“攻击命中后没有扣血”,不要先猜伤害公式。先把链路拆成可证明的阶段:输入是否触发、攻击逻辑是否执行、命中检测是否得到目标、服务器是否拥有 Authority、伤害函数是否进入、生命值是否真正变化。

Gameplay日志缩小故障范围的定位流程

定位时只需要找“最后一条出现的预期日志”和“第一条缺失的预期日志”。如果 Hit Result 已出现而 Damage Function 没出现,调查范围就从整套战斗系统缩小到了命中结果之后、伤害调用之前。

建立可过滤的日志分类

长期调试应使用自定义分类,这样 Output Log、命令行日志和配置文件都可以只显示当前系统。片段示例:以下代码依赖已有 UE5 C++ 项目,需作为一个 Actor 类加入项目并放入测试关卡;它定义 LogGameplayDebug,并在关卡开始后主动执行一次伤害探针。

cpp
// 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);
};
cpp
// 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> 表示。

预期输出

text
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。

如果日志在某两个检查点之间断开,就继续在这一区间增加一个新的检查点,而不是把整个函数每行都打印一次。这种二分式加点可以快速缩小故障范围,同时保持日志可读;等根因确认后,删除临时高频日志,只保留对线上诊断仍有价值的分类和关键状态变化。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用日志定位Gameplay故障

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通