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)They route through the currently configured logger and safely no-op when logging is unavailable.
Configure or replace the logger
For most games, configure PlacementDebugSettings through your normal placement bundle/session resources.
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 code that can run every frame or for many placement candidates, use the logger's throttled/once helpers rather than printing repeatedly. This keeps diagnostics useful without flooding the Godot output.
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 repo's TestLoggerFixture helpers instead of duplicating logger setup/teardown.