Logger Configuration

Grid Placement routes runtime diagnostics through PlacementLogger. Normal projects do not need to construct a logger manually; session composition initializes it from PlacementDebugSettings.

Use logging to understand setup and placement failures. Logging does not change placement outcomes.

Log levels

PlacementDebugSettings controls verbosity.

Level	Intended use
ERROR	Failures that need attention.
WARNING	Errors plus warnings.
INFO	Normal high-level lifecycle information.
DEBUG	Development diagnostics.
VERBOSE	Detailed setup/placement reports.
TRACE	Highest-volume diagnostics; use temporarily.

Keep production builds at the lowest level that gives you useful support information. Do not leave TRACE enabled just to compensate for missing game-side telemetry.

Writing plugin-aware diagnostics

When extending Grid Placement, prefer the static helpers:

PlacementLogger.info("Placement mode changed")
PlacementLogger.debug("Target cell:%s" % str(cell))
PlacementLogger.warn("Placement target map is missing")
PlacementLogger.error("Placement failed:%s" % reason)

debug, trace, info, and verbose emit only when a logger is configured and the level is enabled. warn and error use Godot's push_warning() and push_error() when no logger is configured; with a logger, they also follow its level setting.

Configure or replace the logger

For most games, configure PlacementDebugSettings through your normal placement bundle/session resources.

The production logger is shared across the plugin. Its first initialize() call sets the debug settings; later calls reuse that logger while it remains alive.

If your bootstrap needs to install a logger directly:

var debug_settings:= PlacementDebugSettings.new()
debug_settings.level= PlacementLogger.LogLevel.WARNING
var logger:= PlacementLogger.initialize(debug_settings)

You can redirect output to your own console/file/HUD sink:

logger.set_log_sink(func(level:int, context:String, message:String)-> void:
    game_log.append("[%s]%s" % [context, message])
)

When a custom sink is active, it becomes responsible for presenting or storing the routed messages.

High-frequency logging

For high-volume code, guard expensive trace messages before building them:

if PlacementLogger.trace_output_enabled():
    PlacementLogger.trace("Candidate details:%s" % build_candidate_details())

The old throttled and once helpers were removed in 6.2. An instance logger's log_at() also accepts a Callable, which it invokes only when that level is enabled.

Do not use logging as gameplay state or as the authority for whether placement succeeded. Consume the typed placement/action results for that.

Godot logging boundary

Plugin runtime code should normally use PlacementLogger. Direct print, push_warning, or push_error is appropriate only where the logger itself cannot safely be used, such as logger sinks, pre-runtime editor/resource validation, or narrow contract guards.

Tests

Grid Placement's own tests can push scoped logger overrides so a spy/muted logger does not replace the production root globally. This is test infrastructure, not something normal game integrations need to configure.

If you maintain plugin tests, use the plugin's TestLoggerFixture helpers instead of duplicating logger setup/teardown.

Related guides

• Troubleshooting
• Validation
• Composition & Injection