Logging

Logging uses Unreal Engine-style categories through the VS_LOG() family of macros. Every log message is tagged with a category name and a verbosity level, which lets you filter output per subsystem at runtime and strip debug noise at compile time.

Include Engine/Logging/LogCategories.h to get both the engine's log categories and the logging macros.

#include "Engine/Logging/LogCategories.h"
 
VS_LOG(LogLOD, Info, "Generated {} clusters in {} ms", clusterCount, timeMs);

Macros

VS_LOG(Category, Verbosity, Format, ...)

Logs one formatted message under the given category and verbosity.

Parameters:

• Category - A log category instance (e.g. LogLOD).
• Verbosity - A LogVerbosity level (Fatal, Error, Warning, Info, Debug, Verbose).
• Format - A std::format compatible format string.
• ... - Format arguments.

Example:

VS_LOG(LogTransfer, Warning, "ensureSize: RESIZING buffer='{}' from {} to {} bytes",
       debugName_, oldSize, newSize);

VS_LOG_SIMPLE(Category, Verbosity, Message)

Logs a plain string without format arguments. Slightly cheaper than VS_LOG() when the message has no placeholders.

Example:

VS_LOG_SIMPLE(LogLOD, Warning, "=== LOD DIAGNOSTIC: Error Value Analysis ===");

VS_CLOG(Condition, Category, Verbosity, Format, ...)

Logs only when Condition evaluates to true. Use it to keep noisy checks on one line.

Parameters:

• Condition - Boolean expression that gates the message.
• Category, Verbosity, Format, ... - Same as VS_LOG().

Example:

VS_CLOG(pendingDeletions > 16, LogTransfer, Warning,
        "Too many pending buffer deletions: {}", pendingDeletions);

VS_LOG_ONCE(Category, Verbosity, Format, ...)

Logs only the first time this line is executed in a run. Good for one-time warnings fired from hot loops.

Example:

VS_LOG_ONCE(LogMesh, Warning, "Mesh '{}' has no LOD hierarchy data", path);

Verbosity Convenience Macros

Shorter forms that bake in the verbosity level.

Macro	Equivalent to
VS_LOG_FATAL(Category, Format, ...)	VS_LOG(Category, Fatal, ...)
VS_LOG_ERROR(Category, Format, ...)	VS_LOG(Category, Error, ...)
VS_LOG_WARNING(Category, Format, ...)	VS_LOG(Category, Warning, ...)
VS_LOG_INFO(Category, Format, ...)	VS_LOG(Category, Info, ...)
VS_LOG_DEBUG(Category, Format, ...)	VS_LOG(Category, Debug, ...)
VS_LOG_VERBOSE(Category, Format, ...)	VS_LOG(Category, Verbose, ...)

Example:

VS_LOG_INFO(LogAssets, "Loaded asset '{}' with {} references", path, refCount);

Verbosity Levels

Levels are ordered from most to least severe. All aliases Verbose and Off aliases Fatal.

Level	Meaning
Fatal	Unrecoverable error, may crash
Error	Recoverable error
Warning	Potential issue
Info	Important state changes
Debug	Development debugging
Verbose	Detailed tracing

A message is emitted only if its verbosity is at most the category's configured level. Info logs everything down to Info; Verbose logs everything.

Log Categories

Categories are defined engine-wide in Engine/Logging/LogCategories.h. They follow Unreal naming with a Log prefix and are grouped by subsystem.

Category	Purpose
LogEngine	Engine lifecycle, initialization, shutdown
LogRenderer	Main render loop, frame timing
LogVulkan	Vulkan API calls, validation, resource management
LogLOD	Cluster LOD selection, hierarchy generation
LogMeshlet	Meshlet generation, culling, unpacking
LogRenderData	GPU buffer management, data uploads
LogTransfer	GPU buffer transfers, staging buffer operations
LogCompute	Compute shader dispatch, pipeline execution
LogAssets	Asset loading, caching, lifecycle
LogTexture	Texture loading, GPU upload, compression
LogMaterial	Material compilation, shader binding
LogMesh	Mesh/GLTF loading, geometry processing
LogXR	OpenXR session, runtime, layers
LogXRInput	VR input, controller tracking
LogPhysics	Physics simulation, collision detection
LogECS	Entity Component System operations
LogScene	Scene management, actor lifecycle
LogTemp	Temporary debugging (like UE's LogTemp), always verbose by default
LogFile	File I/O operations
LogConfig	Configuration loading, settings

Gameplay code can define its own categories with the macros in EngineCore::LogCategory:

// In a header:
DECLARE_LOG_CATEGORY_EXTERN(LogMySystem, Info, Verbose);
 
// In one source file:
DEFINE_LOG_CATEGORY(LogMySystem, Info, Verbose);

DEFINE_LOG_CATEGORY_STATIC(LogMySystem, Info, Verbose) creates a category usable only within a single file.

Runtime Filtering

Each category has a runtime verbosity that can be changed while the game runs. The thread-safe EngineCore::LogCategoryManager singleton holds all registered categories.

auto& mgr = EngineCore::LogCategoryManager::get();
mgr.setVerbosity("LogLOD", EngineCore::LogVerbosity::Verbose); // one category
mgr.setAllVerbosity(EngineCore::LogVerbosity::Debug);          // every category

Verbosity settings can be loaded from and saved to a JSON config file:

{
  "LogCategories": {
    "LogLOD": "Verbose",
    "LogRenderer": "Info",
    "Default": "Warning"
  }
}

Default applies to every category not explicitly listed. Unrecognized strings fall back to Info.

Compile-Time Filtering

Messages are also filtered at compile time so verbose logging can be stripped from Release builds entirely. The compile-time ceiling is VS_LOG_COMPILE_TIME_VERBOSITY:

• Debug builds default to Verbose (all messages compiled in).
• NDEBUG builds default to Info (Debug and Verbose calls compile out to nothing).

Define VS_LOG_COMPILE_TIME_VERBOSITY yourself to override, for example to build a profiling build that drops all logging:

#define VS_LOG_COMPILE_TIME_VERBOSITY ::EngineCore::LogVerbosity::Warning

The macro emits no code for verbosity levels above the ceiling, so VS_LOG_DEBUG() and VS_LOG_VERBOSE() become free in optimized builds.

Formatting

Format strings follow std::format. Use {} placeholders and standard format specifiers.

VS_LOG(LogLOD, Debug, "Group {}: err={:.6f} r={:.4f} | switchDist={:.2f}m", group, error, r, switchDist);
VS_LOG(LogRenderData, Debug, "markDirty(0x{:x}) called", dirtyFlags);
VS_LOG(LogRenderer, Verbose, "copy srcBuf={:p} dstBuf={:p}", src, dst);

Output

Logging routes through plog. Every message is prefixed with its category name, for example [LogLOD] Generated 42 clusters in 3.1 ms.

The engine writes to both a timestamped log file (GameLog_YYYY-MM-DD_HH-MM-SS.log) and a color console. EngineCore::initializePlog() sets this up and must be called at the very start of main() before any engine code runs, so even Vulkan validation layer messages are captured.

Source Files

• Engine/src/Engine/Logging/LogMacros.h - VS_LOG macro family
• Engine/src/Engine/Logging/LogCategory.h - LogVerbosity, LogCategory, LogCategoryManager
• Engine/src/Engine/Logging/LogCategory.cpp - manager and config load/save implementation
• Engine/src/Engine/Logging/LogCategories.h - engine category declarations
• Engine/src/Engine/Logging/LogCategories.cpp - engine category definitions
• Engine/src/Engine/Logging/PlogInit.h - plog initialization and appenders

Related Documentation

• EngineCore::LogCategory
• EngineCore::LogCategoryManager
• EngineCore::LogVerbosity