Logging and Observability (v6.0)

Overview

GridBuilding 6.0 uses a thin, engine-agnostic logging interface in its Core layer. The plugin itself does not own a Godot-specific logger. Instead, the host game (for example, Thistletide) is responsible for wiring logs into Godot or any other engine.

This guide explains:

How GridBuilding Core logs events.
How games should provide an ILogger implementation.
How to integrate with Chickensoft.Log and Chickensoft.Log.Godot on the Godot side.

Core Logging Contract

ILogger interface

Core code depends on GridBuilding.Core.Interfaces.ILogger:

Pure C# interface.
No Godot or engine-specific types.
Methods for debug/info/warning/error, with optional context.

Default Core implementation

Class: GridBuilding.Core.Services.Logging.Logger.
Backend: Chickensoft.Log (ILog, Log, ConsoleWriter, TraceWriter).
No engine dependencies.

Core systems (placement, manipulation, validation, etc.) receive an ILogger via DI or service composition. They never call GD.Print or GD.PushWarning directly.

Godot Integration – Game Responsibility

In a Godot game, logging is configured at the game level, not in the plugin. The recommended pattern is:

Add logging dependencies to the game
- Reference Chickensoft.Log (NuGet) from the game’s C# project.
- Optionally reference Chickensoft.Log.Godot to integrate with:
  - Godot debug console (via GDWriter).
  - Godot-side log files (via GDFileWriter).

Create a game-owned ILogger implementation

In your game, implement GridBuilding.Core.Interfaces.ILogger and route calls to a configured Chickensoft.Log.ILog instance:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
public sealed class GameGridBuildingLogger : GridBuilding.Core.Interfaces.ILogger {
    private readonly Chickensoft.Log.ILog _log;

    public GameGridBuildingLogger(Chickensoft.Log.ILog log) {
        _log = log;
    }

    public LogLevel LogLevel { get; set; } = LogLevel.Info;

    public void Log(LogLevel level, string message) {
        // Map GridBuilding.LogLevel -> Chickensoft.Log methods
    }

    // Implement LogDebug/Info/Warning/Error by delegating to Log(...)
}

Wire ILogger via DI/services
- During game startup, register the GameGridBuildingLogger in your DI container.
- Ensure that when GridBuilding Core asks for ILogger, it receives this implementation.
Front-end error messages
- Use GD.PushError / GD.PushWarning in Godot scripts only for user- or editor-facing errors.
- Treat infrastructure logging (ILogger + Chickensoft.Log) as the primary telemetry channel.

Deprecated: GodotLogger and GodotLog

GridBuilding previously shipped a Godot-specific logger:

GridBuilding.Godot.Logging.GodotLogger
GridBuilding.Godot.Logging.GodotLog

These types are now marked as [Obsolete] in code and should be considered legacy. New integrations should:

Resolve GridBuilding.Core.Interfaces.ILogger from the game’s DI container.
Implement it with a game-owned logger (for example, using Chickensoft.Log and Chickensoft.Log.Godot).

Existing projects may continue to use GodotLogger/GodotLog temporarily, but we recommend migrating toward the ILogger + game-owned implementation model.

Recommended Godot Backend: Chickensoft.Log.Godot

To adapt ILogger to the Godot front end, we recommend:

Use Chickensoft.Log.Godot as a convenient Godot logger backend.
- Add GDWriter / GDFileWriter to your ILog instances.
- Keep the GridBuilding plugin itself unaware of these engine-specific concerns.

This keeps GridBuilding Core reusable across engines while still providing rich logging and diagnostics in Godot games.