Logging

The engine has a built-in logger that allows you to trace execution of your game by creating log entries when needed.

The window allows you to select the severity of the messages that will be put in the window:

• Info+ will show all messages with Info, Warning, Error severities.
• Warning+ will show all messages with Warning and Error severities.
• Error will show all messages with only Error severity.

Each log entry can be copied to the clipboard by right-clicking on it and pressing Copy in the context menu. You can also clear the log using Clear button.

Setting up the logging

By default, the engine does not write to the log until you call one of the following methods:

#![allow(unused)]
fn main() {
    // It is possible to specify the file name for the logger output.
    Log::set_file_name("my_game.log");

    // The more precise control over the file can be achieved by creating
    // the log file manually:
    let file = File::create("my_game.log").unwrap();
    Log::set_file(Some(file));

    // The logging to a file can be disabled at any time by calling:
    Log::set_file(None);

    // By default, the logger also prints into stdout stream. This can
    // be disabled as well if not needed:
    Log::enable_writing_to_stdout(false);
}

Keep in mind, every project generated by the project manager has logging turned on. It can be disabled (or modified) in one of the executors for target platforms (check executor, executor-wasm, executor-android crates in the generated projects).

Writing to the log

There are three macros that can be used for writing to the log: info!, warn!, err!. Alternatively, you can use one of Log::info, Log::warn, Log::err methods, or use Log::writeln with severity specified.

#![allow(unused)]
fn main() {
    info!("This is some info. {}", 123);
    warn!("This is some warning. {}", 321);
    err!("This is some error. {}", 42);

    // The same can be achieved by direct function calls and format! macro.
    Log::info(format!("This is some info. {}", 123));
    Log::warn(format!("This is some warning. {}", 321));
    Log::err(format!("This is some error. {}", 42));
}

It is also possible to write only once to the log per some event that may occur in a loop by using macros/functions with the suffix _once:

#![allow(unused)]
fn main() {
    for _ in 0..10 {
        info_once!(0, "This info message will be printed only once.");
        warn_once!(1, "This warning message will be printed only once.");
        err_once!(2, "This error message will be printed only once.");
    }
}

The functions accept the message id as the first argument, it must be unique per the event type.

Verbosity Level

It is also possible to select the desired verbosity level of logging:

#![allow(unused)]
fn main() {
    // All these lines will be printed.
    info!("This is some info");
    warn!("This is some warning");
    err!("This is some error");

    Log::set_verbosity(MessageKind::Warning);

    info!("This is some info"); // This won't be printed.
    warn!("This is some warning");
    err!("This is some error");
}