Building a Rust Game Engine: Part 3 - Logging

Last time we set up engine-owned entry points. Now we can initialize, run, and shutdown applications. But how do we know what’s actually happening inside?

pub fn init() {
    println!("GGEngine initialized");
}

This works, but println! isn’t enough for a real engine. We need:

• Severity levels - Distinguish errors from info from debug noise
• Colors - Spot problems instantly in a wall of text
• Timestamps - Know when things happened
• Source tags - Know where messages came from (engine vs. app)
• Strippable in release - Zero overhead in distribution builds

Why Not Write Our Own?

We could write a logging library. But good string formatting-supporting arbitrary types, positional arguments, format specifiers-is substantial work. In Rust, the log crate is the standard facade, and there’s no reason to reinvent it.

We’ll use:

• log - The standard Rust logging API (macros like info!, warn!, error!)
• env_logger - A backend that outputs colored console logs

Setting Up Dependencies

# engine/Cargo.toml
[dependencies]
log = "0.4"
env_logger = "0.11"

Two Logger Categories

Like Hazel’s approach, we want two distinct loggers:

1. Core - Engine internal messages tagged [GGEngine]
2. Client - Application messages tagged [App]

This separation matters. When something breaks, you need to know if it’s your code or the engine.

The Log Module

// engine/src/log.rs
use env_logger::Builder;
use log::LevelFilter;
use std::io::Write;

pub fn init() {
    Builder::new()
        .filter_level(LevelFilter::Trace)
        .format(|buf, record| {
            use env_logger::fmt::style::{AnsiColor, Style};

            let level = record.level();
            let style = match level {
                log::Level::Error => Style::new().fg_color(Some(AnsiColor::Red.into())).bold(),
                log::Level::Warn => Style::new().fg_color(Some(AnsiColor::Yellow.into())),
                log::Level::Info => Style::new().fg_color(Some(AnsiColor::Green.into())),
                log::Level::Debug => Style::new().fg_color(Some(AnsiColor::Cyan.into())),
                log::Level::Trace => Style::new().fg_color(Some(AnsiColor::White.into())),
            };

            let tag = if record.target().starts_with("GGEngine") {
                "GGEngine"
            } else {
                "App"
            };

            writeln!(
                buf,
                "{style}[{timestamp}] [{tag}] {level}: {msg}",
                timestamp = buf.timestamp_millis(),
                tag = tag,
                level = level,
                msg = record.args(),
            )
        })
        .init();
}

The custom formatter gives us:

• Colored output based on severity
• Millisecond timestamps
• Tag based on the log target (we’ll set this with macros)

Core Logging Macros

For engine internals, we define macros that set the target to “GGEngine”:

// engine/src/lib.rs
#[macro_export]
macro_rules! core_trace {
    ($($arg:tt)*) => {
        ::log::trace!(target: "GGEngine", $($arg)*)
    };
}

#[macro_export]
macro_rules! core_info {
    ($($arg:tt)*) => {
        ::log::info!(target: "GGEngine", $($arg)*)
    };
}

// ... core_debug, core_warn, core_error similarly

The target: parameter tells the log system where this message originated. Our formatter checks for “GGEngine” and tags accordingly.

Client Logging

Client code uses the standard log macros, re-exported through a gg module for a clean namespace:

// engine/src/lib.rs
pub mod gg {
    pub use log::{debug, error, info, trace, warn};
}

Clients import use engine::gg and call gg::info!(), etc. These default to the calling module’s path as the target, which won’t start with “GGEngine”, so they get tagged [App].

Initialization Order

Logging must initialize before anything else:

// engine/src/lib.rs
pub fn init() {
    log::init();  // First!
    core_info!("GGEngine initialized");
}

pub fn shutdown() {
    core_info!("GGEngine shutdown");
}

Client Usage

Now applications get clean logging for free:

// sandbox/src/main.rs
use engine::gg;
use engine::Application;

struct Sandbox;

impl Application for Sandbox {
    fn new() -> Self {
        gg::info!("Sandbox created");

        let var = 5;
        gg::info!("Hello! var = {}", var);

        Sandbox
    }

    fn run(&mut self) {
        gg::trace!("This is a trace message");
        gg::debug!("This is a debug message");
        gg::info!("This is an info message");
        gg::warn!("This is a warning message");
        gg::error!("This is an error message");

        loop{
            
        }
    }
}

engine::entrypoint!(Sandbox);

Running this:

$ cargo xtask run --bin sandbox
[2024-01-25T12:00:00.123Z] [GGEngine] INFO: GGEngine initialized
[2024-01-25T12:00:00.123Z] [App] INFO: Sandbox created
[2024-01-25T12:00:00.123Z] [App] INFO: Hello! var = 5
[2024-01-25T12:00:00.124Z] [App] TRACE: This is a trace message
[2024-01-25T12:00:00.124Z] [App] DEBUG: This is a debug message
[2024-01-25T12:00:00.124Z] [App] INFO: This is an info message
[2024-01-25T12:00:00.124Z] [App] WARN: This is a warning message
[2024-01-25T12:00:00.124Z] [App] ERROR: This is an error message
[2024-01-25T12:00:00.124Z] [GGEngine] INFO: GGEngine shutdown

In a real terminal, errors are red, warnings are yellow, info is green. You can spot problems at a glance.

Stripping Logs in Release

The log crate supports compile-time level filtering. In Cargo.toml:

[features]
max_level_info = ["log/max_level_info"]  # Strip trace/debug in release
release_max_level_warn = ["log/release_max_level_warn"]  # Only warn+ in release

When enabled, trace and debug calls compile to nothing. Zero overhead.

Why This Approach?

1. Standard ecosystem - log is Rust’s blessed logging facade. Every Rust developer knows it.
2. Zero cost abstraction - Unused log levels compile away
3. Swappable backends - Could switch to tracing or file logging without changing call sites
4. Familiar API - Format strings work like println!

The Log Levels

• error! - Something went wrong, needs attention
• warn! - Something suspicious, might be a problem
• info! - Normal operation, useful for understanding flow
• debug! - Developer details, stripped in release
• trace! - Extremely verbose, usually disabled

What’s Next

We have entry points and logging. The engine can now communicate what it’s doing. Next, we need a build system that handles:

• Cross-platform builds (Windows, Mac, Linux)
• Automatic DLL copying in debug
• Asset bundling for distribution

---

This is part 3 of a series on building a game engine in Rust.