Skip to content

Debugging and Logging

Decision (Aug 2025): simplify plugin debugging for users and contributors.

  • Single debug level setting via GBDebugSettings.level: NONE, ERROR, WARNING, INFO, VERBOSE
  • Verbose mode controls visual debug drawing; no per-frame console spam
  • Use GBLogger exclusively for messages (no push_error/push_warning in gameplay code)

Levels and usage

  • ERROR: Failures preventing correct behavior
  • WARNING: Recoverable issues or suspicious states
  • INFO: High-level milestones (rare in runtime). Prefer editor-time or one-time messages
  • VERBOSE: Detailed diagnostics; visuals on indicators; keep console output minimal

Current logger API

  • log_error(sender, message)
  • log_warning(sender, message)
  • log_verbose(sender, message)
  • log_verbose_once(sender, key, message) to avoid repeating the same message
  • log_verbose_throttled(sender, key, message) to rate-limit messages

Note: Use log_verbose_once/log_verbose_throttled for anything that could trigger every frame.

Visual debug policy

  • Indicator debug drawing is QUIET by default
  • Visuals display when either:
  • GBDebugSettings.level >= VERBOSE, or
  • GBDebugSettings.draw_rule_check_indicator_debug == true
  • Avoid printing per-indicator information each frame. Prefer visuals over console text

Where to configure

  • Resource: GBSettings.debug : GBDebugSettings
  • Defaults:
  • level = ERROR (quiet)
  • draw_rule_check_indicator_debug = false

Examples

Enable verbose visuals without console spam:

var logger := GBLogger.new(my_settings.debug)
my_settings.debug.level = GBDebugSettings.DebugLevel.VERBOSE
# Draws visuals; console stays quiet unless you explicitly call logger

Avoid per-frame spam:

# Bad: called every _physics_process
# logger.log_verbose(self, "checking collisions...")

# Good: once or throttled
logger.log_verbose_once(self, "init", "starting collision checks")
logger.log_verbose_throttled(self, "collision", "still overlapping")

Do / Don’t

  • Do: route all logs through GBLogger
  • Do: use visuals for continuous feedback; logs for events
  • Don’t: emit per-frame logs from indicators or rules
  • Don’t: change engine-level print behavior; use logger helpers instead

Compatibility notes

  • Extra console toggles were removed; the single source of truth is GBDebugSettings.level
  • Indicator visuals are controlled by level (VERBOSE) or the explicit indicator toggle