ue-testing-debugging
Use when writing or running Unreal Engine tests, adding logging, or profiling a build. Also use when the user mentions 'UE_LOG', 'log category', 'DEFINE_LOG_CATEGORY', 'UE_LOGFMT', 'verbosity', 'check', 'ensure', 'ensureMsgf', 'verify', 'IMPLEMENT_SIMPLE_AUTOMATION_TEST', 'automation test', 'TEST_CLASS', 'CQTest', 'AFunctionalTest', 'latent command', 'Unreal Insights', 'TRACE_CPUPROFILER_EVENT_SCOPE', 'TRACE_BOOKMARK', 'stat unit', 'SCOPE_CYCLE_COUNTER', 'memreport', 'DrawDebugLine', 'UE_VLOG', 'gameplay debugger', 'ShowDebug', 'console command', 'CVar', or 'why is my frame time bad'. For module and target wiring, see ue-module-build-system; for editor tooling, see ue-editor-tools.
quodsoler · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add quodsoler/unreal-engine-skills --skill ue-testing-debugging技能说明
name: ue-testing-debugging description: "Use when writing or running Unreal Engine tests, adding logging, or profiling a build. Also use when the user mentions 'UE_LOG', 'log category', 'DEFINE_LOG_CATEGORY', 'UE_LOGFMT', 'verbosity', 'check', 'ensure', 'ensureMsgf', 'verify', 'IMPLEMENT_SIMPLE_AUTOMATION_TEST', 'automation test', 'TEST_CLASS', 'CQTest', 'AFunctionalTest', 'latent command', 'Unreal Insights', 'TRACE_CPUPROFILER_EVENT_SCOPE', 'TRACE_BOOKMARK', 'stat unit', 'SCOPE_CYCLE_COUNTER', 'memreport', 'DrawDebugLine', 'UE_VLOG', 'gameplay debugger', 'ShowDebug', 'console command', 'CVar', or 'why is my frame time bad'. For module and target wiring, see ue-module-build-system; for editor tooling, see ue-editor-tools." metadata: version: "2.0.0" engine: "5.8"
UE Testing, Logging & Profiling
Target engine: UE 5.8. APIs below are verified against the 5.8 headers; older forms are listed under "Deprecated — do not use".
This skill owns logging, assertions, automation/functional testing, console commands and performance profiling for the repo. Logging, assertions, stats, trace and CVars live in Core (Logging/, Misc/AssertionMacros.h, Stats/Stats.h, ProfilingDebugging/, HAL/IConsoleManager.h). Debug drawing, the Visual Logger and AHUD::ShowDebug live in Engine. Test frameworks are the developer modules AutomationController, CQTest, FunctionalTesting and AutomationDriver; the Gameplay Debugger is the runtime module GameplayDebugger.
Context
Read .agents/ue-project-context.md if it exists (module names, conventions, enabled plugins, GAS/networking setup). Do not stop if it is missing. Identify the area from the request and the codebase; ask only when two plausible readings would produce different code.
| Request is about… | Go to |
|---|---|
UE_LOG, categories, verbosity, structured logging | Logging |
check, ensure, verify, crash on bad state | Assertions |
Unit tests, IMPLEMENT_SIMPLE_AUTOMATION_TEST, specs, latent commands | Automation Tests |
TEST_CLASS, ASSERT_THAT, fixture-style tests | CQTest |
Tests placed in a map, AFunctionalTest | Functional Tests |
Insights, stat, cycle counters, CSV, memory, hitches | Profiling |
DrawDebug*, UE_VLOG, Gameplay Debugger, ShowDebug | Debug Visualization |
Exec functions, FAutoConsoleCommand, CVars | Console Commands and CVars |
Logging
Declaring categories
#include "Logging/LogMacros.h"
// MyGameLogging.h — DECLARE_LOG_CATEGORY_EXTERN(Name, DefaultVerbosity, CompileTimeVerbosity)
DECLARE_LOG_CATEGORY_EXTERN(LogMyGame, Log, All);
DEFINE_LOG_CATEGORY(LogMyGame); // MyGameLogging.cpp
| Macro | Where | Scope |
|---|---|---|
DECLARE_LOG_CATEGORY_EXTERN(Name, Default, CompileTime) | header | the module and everything that includes it |
DEFINE_LOG_CATEGORY(Name) | one .cpp | pairs with the EXTERN form |
DEFINE_LOG_CATEGORY_STATIC(Name, Default, CompileTime) | one .cpp | that translation unit only |
DECLARE_LOG_CATEGORY_CLASS(Name, Default, CompileTime) | class body | class static; pair with DEFINE_LOG_CATEGORY_CLASS(Class, Name) |
DefaultVerbosity must be <= CompileTimeVerbosity or the static_assert inside the category macro fires. Anything above CompileTimeVerbosity is deleted by the compiler, so DECLARE_LOG_CATEGORY_EXTERN(LogMyGame, Log, Log) removes every Verbose/VeryVerbose call site. Monolithic builds can cap all categories at once by defining COMPILED_IN_MINIMUM_VERBOSITY.
Verbosity levels
| Level | Console | File | Notes |
|---|---|---|---|
Fatal | yes | yes | crashes the process, even when logging is disabled |
Error | yes | yes | collected by commandlets and the editor; fails a commandlet |
Warning | yes | yes | can be promoted to an error |
Display | yes | yes | use this when the user must see the line |
Log | no | yes | file only — the default for development messages |
Verbose | no | yes | only once the category is raised to Verbose |
VeryVerbose | no | yes | only once the category is raised to VeryVerbose |
ELogVerbosity::All is an alias for VeryVerbose and is the usual CompileTimeVerbosity argument.
Emitting
UE_LOG(LogMyGame, Display, TEXT("Player %s spawned"), *PlayerName);
UE_LOG(LogMyGame, Warning, TEXT("Inventory full, dropped %s"), *ItemName);
UE_LOG(LogMyGame, Error, TEXT("Failed to load asset %s"), *AssetPath);
UE_LOG(LogMyGame, Fatal, TEXT("Save data unrecoverable")); // crashes
// Condition and arguments are evaluated only when the category is active.
UE_CLOG(Health <= 0.f, LogMyGame, Warning, TEXT("%s has zero health"), *GetName());
Wrap an expensive report in if (UE_LOG_ACTIVE(LogMyGame, Verbose)) { … } so the work itself is skipped, not just the formatting.
Structured logging
UE_LOGFMT emits named fields that survive into Insights and log analysis; use {Name} placeholders, not %s.
#include "Logging/StructuredLog.h"
// Named fields: order is irrelevant, extra fields are allowed.
UE_LOGFMT(LogMyGame, Warning, "Loading '{Name}' failed with error {Error}",
("Name", AssetName), ("Error", ErrorCode), ("Flags", LoadFlags));
// Positional fields: the values must match the placeholders exactly.
UE_LOGFMT(LogMyGame, Display, "Spawned {Count} actors in {Seconds}s", SpawnCount, Elapsed);
UE_CLOGFMT(bFailed, LogMyGame, Error, "Retry {Attempt} failed", ("Attempt", Attempt));
Field names must match [A-Za-z0-9_]+ and be unique per event; values serialize through SerializeForLog or operator<<(FCbWriter&, T). UE_LOGFMT takes at most 16 fields — use UE_LOGFMT_EX with UE_LOGFMT_FIELD / UE_LOGFMT_VALUE beyond that.
Shipping and Test builds
NO_LOGGING is !USE_LOGGING_IN_SHIPPING in both Test and Shipping, a