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. The only need to be mindful of specifying the category_index which depends on the categories you use. If you for example want to log the current time in your game and the players current position in two separate entries when you've loaded your game(also assuming you have the default categories). See the Example Usage of the main functions paragraph for real world examples of how entries can be made.

Without defining a category_index when creating log entries(i.e. Log.entry("This is a log entry.")). Entries are logged into the category with the index 0.

Managing log categories

GoLogger will create directories for each category in the dock's "category" tab. By default, a "game" and a "player" category is added for you but you can add, remove or rename them to fit your needs. The top-left number of each category is the category_index which you use whenever you create log entries in your code. When your project runs, folders are created with the name of each category within the base_directory and ones a session is started. A .log file is created for each category and is stored in the category's folder.

Notes:

• Locked categories are deleted when using the Reset button. The lock button just disables the text field, apply and delete buttons.
• Folders for categories created by the plugin aren't deleted when you delete a category in the dock. This is to prevent accidental deletion of log files. It's best to open the directory using the "Open" button and manually delete the corresponding folder of any deleted category. !*
  
  

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: ", time_of_day))
# 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.
Log.entry("Current Player health: " + str(current_health) + "/" + str(max_health), 1)
Log.entry(str("Current Player health: ", current_health, "/", max_health), 1)
Log.entry(str("Current Player health: %s/%s" % current_health, max_health), 1)
# Resulting entry: [19:17:27] Current Player health: 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.