Logging System: spdlog-Based Diagnostics in the Unified SDK

The Half-Life Unified SDK uses spdlog to handle logging across all new systems. Every named logger can have its log level configured independently, output can be directed to a rotating daily log file, and because the logging system is implemented at the SDK level — not inside the engine — separate instances run for the client and the server. All console commands are therefore prefixed with either cl_ or sv_ to disambiguate which side they target.

Output Formats

Log messages are written to two destinations: the in-game console and, optionally, a log file on disk. Console output identifies the library side, the logger, and the level:

[short_library_prefix] [logger_name] [log_level] message

short_library_prefix is cl for the client and sv for the server. File output replaces the library prefix with a full timestamp:

[2022-06-02 14:27:17.148] [logger_name] [log_level] message

When file logging is enabled, log files are created under logs/<short_library_prefix>/. The filename follows this pattern:

<BaseFileName>_YYYY_MM_DD.log

For example, with BaseFileName set to Unified on the server side, today’s log file would be named Unified_2024_06_02.log inside logs/sv/.

Log Levels

Levels run from most verbose to least verbose. Setting a logger to a given level enables that level and everything less verbose than it. Setting a logger to off silences it entirely.

Level	Description
`trace`	Extremely detailed diagnostic output
`debug`	Debug-build diagnostic output
`info`	Normal operational messages
`warning`	Conditions that may indicate a problem
`error`	Errors that affect functionality
`critical`	Severe errors (used by the `assert` logger in debug builds)
`off`	No output

List of Loggers

The logging system itself uses the logger named logging. All other named loggers are listed below.

Name	Purpose
`angelscript`	AngelScript scripting support
`assert`	In debug builds, logs debug assertion messages at the `critical` level
`bot`	Bot system
`conditional_evaluation`	AngelScript conditional evaluation
`cvar`	Console command system
`ent`	General entity info
`ent.ai`	NPC info
`ent.ai.script`	NPC scripted behavior (`scripted_sequence`, `aiscripted_sequence`, `scripted_sentence`)
`ent.classify`	Entity classifications
`ent.io`	Entity I/O related to `target` and `killtarget`
`ent.template`	Entity templates
`ent.weapons`	Weapon state info
`game`	General game events related to map loading and initialization
`gamecfg`	Game configuration system
`gamerules`	Game mode events, including output previously routed to the server log file
`json`	JSON system
`logging`	The logging system itself
`mapcycle`	Map cycle
`materials`	Material system
`net_data`	Network data system
`nodegraph`	Node graph debug output — produces heavy output at `trace` level
`precache`	Every call to model, sound, and generic precache functions (engine-precached assets are not included)
`replacementmap`	Replacement map system
`saverestore`	Errors that occur during saving and loading
`sentences`	Diagnostics, warnings, and errors during `sentences.json` file loading
`skill`	Skill configuration system
`sound`	Diagnostics, warnings, and errors during sound playback
`sound.cache`	Client-side sound cache
`sound.sentences`	Client-side sentences system
`ui`	Client-side user interface systems
`ui.campaign`	Campaign selection system
`voice`	Server-side voice system

Error Handling

If spdlog itself encounters an internal error, a message is printed to the console in this form:

[sv|cl] [spdlog] [error]: <error message>

This should only occur if a mistake was made in the game’s C++ code. A developer should investigate and fix these errors — they are not expected during normal gameplay.

Configuration File

Logger settings are loaded from cfg/logging.json, a JSON file that configures log levels for individual loggers and controls file logging.

Keys

Reset (boolean)

If true, all previous settings — including those set on the command line — are reset to their defaults before the rest of the configuration is applied.

Defaults (object)

Default values applied to every logger unless overridden by a LoggerConfigurations entry.

Key	Type	Purpose
`LogLevel`	string	Default log level for all loggers

LoggerConfigurations (array)

A list of per-logger configuration objects.

Key	Type	Purpose
`Name`	string	The name of the logger (use `log_listloggers` to see all names)
`LogLevel`	string	The log level for this specific logger

LogFile (object)

Controls file logging behaviour.

Key	Type	Purpose
`Enabled`	boolean	Whether file logging is active
`BaseFileName`	string	Base name for the log file. Defaults to `L`
`MaxFiles`	integer	Maximum number of contiguous daily log files to keep before older files are deleted

Example Configuration

// Configuration file for Half-Life Unified SDK logging system.
{
    // If set to true, all previous logging settings will be reset before this
    // configuration is applied. This will reset command line settings.
    "Reset": false,

    // Default logger configuration. Used for every logger unless overridden.
    "Defaults": {
        "LogLevel": "info"
    },

    // Logger-specific configuration.
    "LoggerConfigurations": [
        // Sample configuration. Use the sv_log_list_loggers command to get a list of logger names.
        // {
        //     "Name": "logging",
        //     "LogLevel": "trace"
        // }
    ],

    // Configuration for logging to a file.
    "LogFile": {
        "Enabled": false,
        "BaseFileName": "Unified",
        "MaxFiles": 8
    }
}

This configuration inherits any existing settings, sets the default log level for all loggers to info, and disables file logging.

Console Commands

All commands exist in both a client-prefixed (cl_) and a server-prefixed (sv_) form. For example, sv_log_listloggers and cl_log_listloggers are both valid.

Command	Syntax	Description
`log_listloglevels`	`log_listloglevels`	Prints all available log levels from most to least verbose
`log_listloggers`	`log_listloggers`	Prints all registered logger names
`log_setlevel`	`log_setlevel <logger_name> [log_level]`	With only a name: prints the current level. With a level: sets the logger to that level
`log_setalllevels`	`log_setalllevels <log_level>`	Sets all loggers to the given level
`log_setentlevels`	`log_setentlevels <log_level>`	Sets all `ent.*` loggers plus `nodegraph`, `saverestore`, `gamerules`, and `voice` to the given level — equivalent to the `developer` cvar’s effect on logging
`log_file`	`log_file <on \| off>`	Without arguments: prints the current file-logging state. With `on` or `off`: enables or disables file logging

log_setentlevels is the modern replacement for the developer cvar when it comes to entity and gameplay log output. Setting it to debug or trace gives equivalent verbosity to what developer 1 previously produced.

Command Line Parameters

These parameters are evaluated at startup before cfg/logging.json is loaded. The configuration file will override them.

`-log_startup_level`

-log_startup_level <log_level>

Sets the default log level during startup. Useful for debugging early startup code before the configuration file has been read. If not specified, the startup level is determined by the developer cvar: debug if developer is greater than zero, otherwise info. The only way to set developer this early is with the -dev command line parameter.

`-log_file_on`

-log_file_on

Enables file logging on startup. The configuration file will override this setting once it is loaded.

Configuration

Engine Systems

Gameplay Systems

Entities

Logging System: spdlog-Based Diagnostics in the Unified SDK

Output Formats

Log Levels

List of Loggers

Error Handling

Configuration File

Keys

Example Configuration

Console Commands

Command Line Parameters

`-log_startup_level`

`-log_file_on`

Build docs developers (and LLMs) love

Configuration

Engine Systems

Gameplay Systems

Entities

Documentation Index

​Output Formats

​Log Levels

​List of Loggers

​Error Handling

​Configuration File

​Keys

​Example Configuration

​Console Commands

​Command Line Parameters

​-log_startup_level

​-log_file_on

Build docs developers (and LLMs) love

Output Formats

Log Levels

List of Loggers

Error Handling

Configuration File

Keys

Example Configuration

Console Commands

Command Line Parameters

`-log_startup_level`

`-log_file_on`