Log.gd, a Godot pretty printer

Log.gd provides a drop-in replacement for GDScript's print(...) function.

It colors the output based on the value passed in, and adds a prefix based on the call-site's file and line number.

This makes Godot's Output buffer much more readable!

TLDR

• Log.pr(...) is a prints(...) replacement (includes spaces between args)
• Log.prn(...) is the same, but includes newlines + tabs when printing arrays and dictionaries
• Both add prefix with the calling filename and line number (e.g. [Player:34])
• Both color the output values based on the value's type
• Log.debug(...), Log.info(...), Log.warn(...), Log.error(...) offer differing log levels

Features

Colorized output

The colorized output really shines when showing nested data structures (Arrays and Dictionaries), but it's also very useful for other gdscript primitives, like Vectors, NodePaths, and StringNames. Support for more types is easily added, feel free to create an issue!

Call-site prefixes

Log's print functions will prefix the output with the name of the script the log comes from, including the line number.

NOTE: This call-site feature is really nice, but it is not yet available everywhere! Recent Godot builds (4.5-dev3) provide the call-stack to more enviroments, and I need to do some testing to confirm whether this now works in production builds.

Objects and to_pretty()

You can opt-in to pretty-printing in your classes by implementing to_pretty(), which Log will pickup via duck-typing.

class_name ExampleClass

func to_pretty():
    return {val=12}

func _ready():_
    Log.pr(self) # colorized `{"val": 12}`

Type Handler Overwrites

You can 'register' handlers for built-in or otherwise 'closed' classes with something like:

Log.register_type_overwrite(some_obj.get_class(),
  func(val): return {name=val.name, level=val.level})

Bring Your Own Color Theme!

As of v0.0.9 you can create your own LogColorTheme and set it via the Project > Settings > Log.gd.

Log ships with an initial dark and light theme - feel free to duplicate and customize as you would. I'd love to provide more themes out of the box, feel free to share them via PR or otherwise.

Log Levels!

Log.gd supports four log levels, DEBUG, INFO, WARN, and ERROR. These levels have matching logger functions for ease of use: Log.debug(), Log.info(), Log.warn(), and Log.error(). For convenience, Log.err() is available.

Log.todo() is treated as a WARN-level log by default, but can be changed to an INFO-level log in Project Settings or via Log.disable_warn_todo().

Optionally Customizable Timestamps!

Log.gd can prepend timestamps to log lines if needed.

The timestamp options available are a Unix timestamp, the ticks in microseconds or nanoseconds, and human readable in 12 or 24 hour time.

Public API

Print functions

• Log.pr(...), Log.debug(...), Log.info(...)
  • pretty-print without newlines
• Log.prn(...), Log.prnn(...), Log.prnnn(...)
  • pretty-print with limited newlines
• Log.warn(...)
  • pretty-print without newlines
  • push a warning via push_warning
• Log.err(...), Log.error(...)
  • pretty-print without newlines
  • push a error via push_error
• Log.todo(...)
  • pretty-print without newlines
  • optionally push a warning via push_warning

These functions all take up to 7 args. We could support more, but you can also pass an Array or a Dictionary if you need more args right away.

Log.warn() and Log.err() are nice because push_warning and push_error on their own do not let you see warnings/errors in the same context as your usual print() statements.

Returning a string

• Log.to_pretty(msg: Variant, opts: Dictionary = {}) -> String

Log.to_pretty(val) can be used to get a bb-code wrapped string, maybe to be passed into a RichTextLabel.

Toggling features

A few functions I use to tweak things at run time (e.g. when running tests).

• Log.enable_colors()
• Log.disable_colors()
• Log.set_colors_termsafe()
• Log.set_colors_pretty()
• Log.enable_newlines()
• Log.disable_newlines()
• Log.set_newline_max_depth(new_depth: int)
• Log.reset_newline_max_depth()
• Log.set_log_level()
• Log.disable_warn_todo()
• Log.enable_warn_todo()
• Log.show_timestamps()
• Log.hide_timestamps()
• Log.use_timestamp_type(timestamp_type: Log.TimestampTypes)
• Log.use_timestamp_format(timestamp_format: String)

Type Handlers

You can 'register' handlers for built-in classes with the below functions.

• register_type_overwrite(key: String, handler: Callable)
  • the handler should be like val: Variant -> Variant
• register_type_overwrites(overwrites: Dictionary)
  • Overwrites is a dictionary like {obj.get_class(): handler_func}
• clear_type_overwrites()

Timestamp Format

The default timestamp format is {hour}:{minute}:{second}. The supported fields are year, month, day, weekday, hour, minute, second, meridiem and dst.`

Both minute and second have preceeding zeroes for both 12- and 24-hour time. hour only has a preceeding zero when using 24-hour time. Both month and day also have preceeding zeroes for both 12- and 24-hour time.

Settings

There are a few Log.gd options available in Project Settings.

It was pointed out to me that some of these should probably live as Editor Settings instead of Project-wide ones. I'll be moving things around soon!

• max_array_size (20)
  • How many array elements to print.
• dictionary_skip_keys ([layer_0/tile_data])
  • Dictionary keys that are _always_ ignored (i.e. never printed.)
• disable_colors (false)
  • Disables colors at game startup.
• color_theme (PRETTY_DARK_V1)
  • A text string name that aligns with (currently hard-coded) color themes.
• use_newlines (true)
  • Setting to false disables newlines in Log.prn(), Log.warn(), Log.todo(), Log.err(), and Log.error().
• use_newlines (false)
  • Setting to true enables newlines across all log functions.
• newline_max_depth (-1)
  • Limits the object depth where newlines are printed. Negative values don't limit object depth.
• log_level (Info)
  • Sets the project-wide, minimum level to log.
• warn_todo (true)
  • Setting true causes Log.todo() to be treated as a WARN-level log, false and it gets treated as an INFO-level log.
• show_timestamps (false)
  • Setting to true prepends timestamps for log lines.
• timestamp_type (HUMAN_12HR)
  • Select the type of timestamp printed in the logs. Options are UNIX, TICKS_MSEC, TICKS_USEC, HUMAN_12HR, and HUMAN_24HR.
• human_readable_timestamp_format ({hour}:{minute}:{second})
  • Custom format string for human-readable timestamps. meridiem is only available when using 12-hour time.