OwofGames.GodotLogger 0.1.5

Godot Logger Provider

This project serves as a base to hook Microsoft's logging infrastructure to the Godot console.

Use this project if you have C# components that rely on ILogger / ILoggerProvider / etc... and want them to output their logs to the Godot console, or you want to take advantage of the fine-grained, extensible architecture of Microsoft's logging system.

Quickstart

Add the NuGet package OwofGames.GodotLogger and Microsoft.Extensions.Logging to the Godot C# Project.

Then, during the initialization of your game, create the logger factory with something like this:

// Create the logger factory.
var loggerFactory = LoggerFactory.Create(builder => builder
    // This is the line that actually adds the Godot logger provider.
    // The argument is optional, but allows you to change the defaults.
    .AddGodot(configuration => configuration
        .SetLogLevelColor(LogLevel.Critical, Colors.MediumPurple)
        .SetLogLevelBold(LogLevel.Critical, true))
    // Further configuration, where you can add more logger providers or define logging rules.
    .SetMinimumLevel(LogLevel.Trace)
    .AddFilter("YourNamespace", LogLevel.Warning)
    .AddFilter("OtherNamespace", LogLevel.Trace)
);

Once you have this, you can inject the created logger factory in your DI container, expose it some other way, or use it directly:

var myLogger = loggerFactory.CreateLogger<MyClass>()

If you now print some stuff, like:

myLogger.LogTrace("This is a trace.");
myLogger.LogDebug("This is a debug.");
myLogger.LogInformation("This is an information.");
myLogger.LogWarning("This is a warning.");
myLogger.LogError("This is an error.");
myLogger.LogCritical("This is critical.");

You will see something like this in console

And something like this in the Debugger ⇒ Errors tab:

Note well: for filtering purposes, the logger provider has been assigned the "Godot" alias too.

Configuration

When adding the Godot logger to the factory builder, you can configure the way logs are produced on it:

var loggerFactory = LoggerFactory.Create(builder => builder 
    // ...
    .AddGodot(configuration => configuration
        .SetLogLevelColor(LogLevel.Critical, Colors.MediumPurple)
        .SetLogLevelBold(LogLevel.Critical, true)
        // more settings...
    )
    // ...
);

What follows is the API supported by GodotLoggerConfiguration (the configuration object above).

SetLogLevelColor(LogLevel logLevel, Color color), SetLogLevelBold(LogLevel logLevel, bool isBold),

SetLogLevelItalic(LogLevel logLevel, bool isItalic)

These methods overwrite the default color, bold or italic status for a specific log level.

Default values are:

SetGodotLoggerMessageFormatter

This method provides two overloads to format the message string. If no formatter is provided, the format will be a simple category - message. The output on the Debugger tab always has this format and cannot be changed.

SetMessageFormatter(SimpleGodotLoggerMessageFormatter messageFormatter)

This overload uses an interpolated string to describe the log message format. For example:

using E = OwofGames.GodotLogger.SimpleGodotLoggerMessageFormatterElement;

// ...

configuration
    .SetMessageFormatter($"[ {E.Timestamp,17:yy/MM/dd HH.mm.ss} | {E.LogLevel,11} ] {E.Category} - {E.Message}");

Which would produce log lines like these:

[ 26/07/05 15.07.13 | Information ] LoggingButton - Writing an information message - 0
[ 26/07/05 15.07.13 | Information ] LoggingButton - Writing an information message - 1
[ 26/07/05 15.07.14 |       Trace ] LoggingButton - Writing a trace message - 2
[ 26/07/05 15.07.15 |       Debug ] LoggingButton - Writing a debug message - 3

The interpolated parts of this string must be elements of the enum OwofGames.GodotLogger.SimpleGodotLoggerMessageFormatterElement. Each of these elements can be formatted using the tools of C# string formatting, according to the type of the corresponding log element:

• LogLevel: enum
• Category, Message: string
• EventId, State, Exception: object
• TimeStamp: DateTime

Note well: if your IDE offers some kind of autocompletion for the formatting of these elements, they could always be aligned to what "enum" supports, which is generally wrong.

SetGodotLoggerMessageFormatter(IGodotLoggerMessageFormatter messageFormatter)

Define the logging format by explicitly providing an IGodotLoggerMessageFormatter. The object must implement the given interface, which requires a single method:

void Format<TState>(
    StringBuilder stringBuilder,
    DateTime timestamp,
    LogLevel logLevel,
    string category,
    EventId eventId,
    TState state,
    Exception? exception,
    Func<string> getMessage 
);

This method must write the message in the string builder passed as the first argument. All the information about the method is passed in the following parameters.

The actual log message is computed by the getMessage parameter.