Getting Started

Creating log entries with data

Simply installing GoLogger will not log any entries or data. This plugin is a framework for you to define your own log entries in your code as you develop your project. Entries are simple strings, meaning any data that can be converted to a string by using str(data) can be added to an entry. When creating a log entry, you only need to create a string and concatenate any data you need/want.

Managing log categories

GoLogger will create directories for each category in the dock's "category" tab. By default, a "game" category is added for you but you can add, remove or rename them to fit your needs. When you run your project, folders are created with the name of each category within the base_directory and ones a session is started, .log file is created for each category. You can also reorder categories by their index.

Note that category folders are not deleted from the directory when deleting a log category in the dock to prevent accidental data data loss. When you delete a log category, it's good practice to manually delete category folders.

Example usage of the main functions:

Concatenating data and strings can be done though many ways, and creating strings for log entries are no different. Use your preferred method, but below are some examples of how to use the main methods of this framework.

# General use, simply starts the session. Hotkey:  Ctrl + Shift + O
Log.start_session()
# Starts session 1.2 seconds after the call. Requires the use of 'await'.
await Log.start_session(1.2)

# No category_index defined > defaults to category 0("game" category by default).
Log.entry(str("Current game time: ", game_time), "game")
# Resulting entry : [19:17:27] Current game time: 16.30

# Logs into category 1("player" category by default). 3 ways to format the same string.
func _on_player_damage_taken(damage: float) -> void:
Log.entry("Player took " + str(damage) + " damage - " + str(current_health) + "/" + str(max_health), "player")
# Resulting entry: [19:17:27] Player took 28.0 damage - 74/100

# Copy session anytime the "player_death" signal is emitted. Hotkey:  Ctrl + Shift + U
func _on_player_death() -> void:
  Log.save_copy()

# Stops an active session. Hotkey:  Ctrl + Shift + P
Log.stop_session() 

The index of every category is shown in the "Categories" tab of the dock at the top left of each category.

Saving separate copies of the active session:

In addition to start_session() and stop_session(), you can also use save_copy(_name: String) so you can save a separate log file without the need of stopping and restarting a new session. The idea behind this feature is to be able to save a copy of the current session in case something happens that you want to save in a separate log file that isn't deleted automatically. These files are saved with the name you pass in, followed by a date and timestamp. These files are stored in a subfolder of your normal .log files, and as such. They're excluded from being automatically deleted/overwritten by any log management feature.

When you save a copy, all categories you've setup will save a snapshot of the active session in their sub folders located in user://GoLogger/*Your_Category*/saved_logs. All of them have the same name and timestamp across all categories for easy identification.

---

Conditionally save copies programmatically:

For example, if you want to save a log session every time your player dies, a bug occurs or some unexpected value was used or returned. You can easily setup a way for a copy to be created automatically.

# Signal example - On player death
func _on_player_death(source: Enemy, damage: float) -> void:
    Log.save_copy("PlayerDeath")

# Unexpected value example - HP out of range
var current_hp: float = 100:
    set(value):
        current_hp = value
        if current_hp > max_hp:
            Log.save_copy("PlayerHPBug")

---

Manually save copies with hotkey:

Simply press Ctrl + Shift + U(by default) which brings up a popup for you to manually enter a name. Any session timer or log management method is paused during the time the popup is active.