04 - 日志

本文主要说明了UE5中有关日志UE_LOG和UE_LOGFMT的基本用法，方便输出一些调试信息。日志是一种非常实用的调试工具，可以详细说明代码当前的执行逻辑

UE_LOG

UE_LOG是一个将格式化消息记录到日志文件中的宏，它的使用如下：

UE_LOG(LogTemp, Warning, TEXT("Hello World"));

其中：

第一个输入参数 LogTemp 是提供给 DEFINE_LOG_CATEGORY 宏的类别名称。你可以在位于 CoreGlobals.h 的引擎中找到这些类别。此外，还能自行创建自定义日志记录类别。
第二个输入参数 Warning 是一个日志详细级别，用于将警告打印到控制台和日志文件中。除了可以设置不同的日志详细级别，还能调整日志的换行模式，设置日志的文本颜色等。
第三个输入参数 Text 是C语言库函数printf()样式中字符串文字的格式。

枚举类ELogVerbosity定义日志的详细级别和用于调整日志换行、输出文本颜色的其他枚举值：

枚举	说明	文本颜色
致命（Fatal）	始终将致命错误打印到控制台和日志文件，即使禁用日志记录，也会出现崩溃。	不适用
错误（Error）	将错误打印到控制台和日志文件。Commandlet和编辑器会收集并报告错误。错误消息导致commandlet故障。	红色
警告（Warning）	将警告打印到控制台和日志文件。Commandlet和编辑器会收集并报告警告。	黄色
显示（Display）	将消息打印到控制台和日志文件。	灰色
日志（Log）	将消息打印到日志文件，但不打印到控制台。	灰色
冗长（Verbose）	如果为给定类别启用了冗长日志记录，则将冗长消息打印到日志文件。这通常用于详细日志记录。	不适用
极其冗长（VeryVerbose）	将冗长消息打印到日志文件。如果启用了极其冗长日志记录，则这将用于详细日志记录，否则将产生垃圾信息输出。可使用日志掩码（`VerbosityMask`）和特殊枚举值设置文本颜色（`SetColor`）。	不适用

日志还支持通过C风格printf()的方式将变量一同输出：

UE_LOG(LogTemp, Warning, TEXT("An Actor's name is %s"), *ExampleActor->GetName());

数据类型和它的特定语法格式如下：

数据类型	特定语法格式
`FString`	`%s`
布尔	`( bExampleBool ? TEXT("true"): TEXT("false") )`
整型	`%d`
浮点	`%f`
高级数据类型	实现`ToString()`或类似方法，以`FString`形式输出

除了使用默认的日志类别外，还可以自行定义它们以满足个性化需求。

首先，在相关的头文件中，在#include指令下添加以下内容：

DECLARE_LOG_CATEGORY_EXTERN(<数据类别名称>, <日志详细级别>, All);

然后，在相关的C++文件中，在#include指令下添加以下内容：

DEFINE_LOG_CATEGORY(<数据类别名称>);

最后，就能使用此类别了：

UE_LOG(<数据类别名称>, <日志详细级别>, TEXT("TEST..."));

UE_LOGFMT是 UE5.2 版本新增的结构化日志输出宏，支持使用 位置( Positional ) 或 具名( Named ) 参数（不能同时使用两种），需要包含头文件 Logging/StructuredLog.h。

使用位置参数时，字段值必须与格式引用的字段顺序完全匹配，例如：

UE_LOGFMT(LogCore, Warning, "Loading `{Name}` failed with error {Error}", Package->GetName(),  ErrorCode);

使用具名参数时，字段值必须包含格式引用的每个字段。顺序无关紧要，而且允许使用额外字段，例如：

UE_LOGFMT(LogCore, Warning, "Loading `{Name}` failed with error {Error}",("Name", Package->GetName()), ("Error", ErrorCode),("Flags", LoadFlags));

使用上述参数的要求如下：

屏幕调试消息也能起到很好的信息传递作用，可以使用以下代码添加屏幕调试消息：

if (GEngine)
{
    GEngine->AddOnScreenDebugMessage(-1, 5.f, FColor::White, TEXT("This is an Example on-screen debug message."));
}

其中：