v3.0

📚 Repository 📚 User Guide 💬 Loggie Discord - Support & Development

🌟 Features

Message Presets

Message Presets are the flagship feature of Loggie 3.0, reducing verbosity and taking customizability to the next level!

They allow you to define a set of styles and settings that should be used on a message, and save them under an ID, then reuse those modifications (however many of them there are) with a single method call!

# Create a preset that applies various styles and settings:
Loggie.preset("GiantPinkNotification").color("pink").bold().italic().suffix("🦩").channel("FlamingoChat").preprocessed(true)

# Use it later:
Loggie.msg("Nothin' threatenin' here, I'm just a flamingah!").preset("GiantPinkNotification").info()

Check out the related documentation to dive into presets and start using this new powerful addition to Loggie.

Flamingo time!! 🦩

Hyperlinks

A new msg.link(url) modifier now lets us quickly make a message a hyperlink to the given URL.

Loggie.msg("Visit godot's website!").link("https://godotengine.org/").info()

Optionally, we can make it a different color directly through the link() modifier to omit appending the color() modifier :

Loggie.msg("Visit godot's website!").link("https://godotengine.org/", "blue").info() # A blue link

Enforce a Strict Message Type

A new msg.type('type') modifier now lets us easily separate the type of the message from the log level we want to output it on, making something like this easily doable:

## An ERROR TYPE message that gets sent at the DEBUG LEVEL.
Loggie.msg("Error only for devs").type("error").debug()

More info in the Message Types article.

Technically, you could've done this before, but with the addition of this new modifier, you can now do it quicker and less verbose. Before, the log level and message type were largely coupled through commonly used wrappers (e.g. Loggie.info, etc.), and changing it was too verbose or required the creation of third-party wrappers.

Output Only In Selected Environment

A new modifier now brings @tool script developers a small but important quality of life option.
You can now set whether messages should be output only in-engine, only ingame, or both.

@tool
Loggie.msg("Hello from ingame only.").env(LoggieEnums.MsgEnvironment.RUNTIME).info()
Loggie.msg("Hello from tool script only.").env(LoggieEnums.MsgEnvironment.ENGINE).info()

Optionally Prevent Emission of Loggie.log_attempted signal

Sometimes, especially during specific debugging or tooling scenarios, it might be desirable to prevent a LoggieMsg from emitting the Loggie.log_attempted signal, regardless of the result of the output.
If you want a specific message to avoid emitting this signal from Loggie, you can now use the no_signal() modifier:

Loggie.msg("Hello.").no_signal().info()

Added LoggieMsg.last_outputted_at_log_level

Whenever the LoggieMsg.output method outputs a message successfully to some channel at any given log level, it now saves the integer value of the log level that was used in the new variable LoggieMsg.last_outputted_at_log_level.

This will be a helpful addition for users who want to know at which log level a message was sent to a channel.

I considered adding this as a new parameter to LoggieChannel.send, but I didn't want to further modify the signature of this function to avoid breaking already created third-party plugins and channels that rely on the signature being as it already is.

More format variables for Timestamps

(Thanks to @Baweimu)

Several new variables are now available for use in Timestamp settings.
These are not used by default, but if you wish to include them in your timestamp format, you can:

Variable	Description
{milisecond}	The milisecond when the message was logged. (000-999)
{startup_hour}	Hours elapsed since the application started. (00-23)
{startup_minute}	Minutes elapsed since the application started. (00-59)
{startup_second}	Seconds elapsed since the application started. (00-59)
{startup_millisecond}	Milliseconds elapsed since the application started. (000-999)

---

🛑 Breaking Changes

LoggieMsg.get_preprocessed fn signature changed.

This function's signature has been changed, since now, alongside the level parameter, it takes a type parameter.
The level parameter is currently unused in the original method, but it may come handy later, and it has also been left in there for anyone who may have already depended on it via custom code, just renamed to _level to avoid the Godot unused parameter warning.

Before:

func get_preprocessed(flags : int, level : LoggieEnums.LogLevel) -> String

Now:

func get_preprocessed(flags : int, _level : LoggieEnums.LogLevel, type : LoggieEnums.MsgType) -> String

Who this affects?

Anyone who has written any custom code using the get_preprocessed function.

LoggieEnums.MsgType keys and values changed.

LoggieEnums.MsgType and LoggieEnums.LogLevel serve different purposes, hence still warrant existing separately, but there was really no reason for them to have fundamental differences like LoggieEnums.MsgType.STANDARD merging both INFO and NOTICE levels into its meaning. These two enums have now been brought more in line with each other by adjusting MsgType to have the same types (and even key names) as LogLevel, and rearranging the order of values so that they match the ones in LogLevel.

• 🛑 LoggieEnums.MsgType.STANDARD has been removed (was at value 0).
• ⚙️ LoggieEnums.MsgType.ERROR has shifted from 1 to 0.
• 🛑 LoggieEnums.MsgType.WARNING has been renamed to WARN and moved from value 2 to 1.
• 🆕 LoggieEnums.MsgType.NOTICE has been added to value 2.
• 🆕 LoggieEnums.MsgType.INFO has been added to value 3.
• ⚙️ LoggieEnums.MsgType.DEBUG has shifted from value 3 to 4.
• The Terminal channel has been adjusted to accommodate this change.

Before:

enum MsgType {STANDARD, ERROR, WARNING, DEBUG}

After:

enum MsgType {ERROR, WARN, NOTICE, INFO, DEBUG}

Who this affects?

• Anyone who has written custom LoggieMsgChannels that make use of the msg_type parameter of the method send.
• Anyone who has depended on LoggieMsg.output using LoggieEnums.MsgType.STANDARD as the default MsgType for LogLevel.INFO and LogLevel.NOTICE messages.
• Anyone else who used LoggieEnums.MsgType.STANDARD or LoggieEnums.MsgType.WARNING for something.
• Anyone who depended on the enum values of the msg types evaluating to a specific integer.

If you have any custom code or channels interacting with these Loggie features, it should be enough to replace LoggieEnums.MsgType.STANDARD with either LoggieEnums.MsgType.INFO or LoggieEnums.MsgType.NOTICE, and replace LoggieEnums.MsgType.WARNING with LoggieEnums.MsgType.WARN.

---

🔨 Fixes

• Fixed an issue where sending a message to multiple channels simultaneously would emit the Loggie.log_attempted signal once for each channel it was sent to.

---

⚙️ Adjustments

• Made a slight optimization to the initialization of each LoggieMsg that avoids executing unnecessary work with initial args conversion when possible.
• Updated several methods in LoggieMsg that were missing a type-hint for their return value.
• The plugin now adds the Loggie singleton during _enable_plugin instead of _enter_tree, fixing an issue where the Godot editor would behave as if there is new unsaved work every time you open it freshly with Loggie enabled. (Thanks to @gruntmoon)

---

🖥️ Developers

New testing suite!

Before, testing Loggie features was done in a very crude way. I just crammed a bunch of stuff that I wanted to see printed in the console in the test.tscn/test.gd script, then scrolled through a sea of output to verify that everything looks correct. No more.

Introducing a new dedicated testing suite, which features both automated and visual tests.

While this doesn't cover all Loggie features, nor can it tell you with 100% accuracy if something within the plugin is broken, it can at least help ensure that the key Loggie features are working as expected.

Automated tests usually finish within a couple of seconds, while manual visual testing may take up to a minute.
All developers should, for good measure, run the test suite at least once before pushing a PR from now on, to securely confirm that their changes haven't altered the expected behavior of Loggie functionalities in an undesirable way.

Developers are also invited to write their own tests for their features, or for existing features which still don't have test coverage.

Read more here.

Moving the project to Godot 4.5

It must be noted that in this update, I've migrated the project to Godot 4.5.

For those pulling this version, this will create the .uid files for all included resources and editing the project should no longer prompt you to auto-generate or commit them.
For regular users, it's business as usual, these files will be pulled with the new version and should be committed to project repositories, like any other .uid files.

Notably, between 4.3 and 4.5, GDscript received significant quality of life upgrades, such as typed dictionaries, but for the time being, I'd advise against using these features in PRs if they break backwards-compatibility with older 4.X versions. Loggie should be available and error-free for all 4.X versions.

Additionally:

• When disabling the Loggie plugin in the Loggie godot project, Loggie project settings are no longer removed by default. Improves developer experience.