Using Log Files To Debug Godot Game Engine Apps

Silocoder
Silocoder
Nov 5 · 5 min read
Godot Game Engine
Godot Game Engine

Debugging a Godot game app, sometimes requires using old school, log file output. This article will show you how to setup to do just that.

The instructions in the article were tested on Mac OS X. It should work similarly for Godot on Linux and Windows .

Problem

You have tested and debugged your game app using Godot’s impressive IDE and you finally export the app (click here) to an executable. But after you install and run it, you find that the game is misbehaving, even though it runs fine in the Godot IDE. You try to solve by single stepping and by modifying your code adding controls to dump output over the game. But that may not be enough. Games are sensitive to user inputs affecting game play. Besides scratching your head, what else should you do? Read on.

Log Files To The Rescue

One of the tools you should consider is the use of log files to print the state of your game. The log files contain Godot messages including errors and warnings along with the print() commands you added, to help isolate the problem.

How-To Setup For Logs

For logging to occur, you must check Enable File Logging in Project Settings as in the screen shot below.

Godot Project Logging Settings

There is also a default Log Path setting (user://logs/log.txt) that you may change. This file is created in the Project Data Folder of your device (see Tips). Max Log Files is the total number of logs that will be created before the older one is wiped to prevent system overflow with log files. log.txt is created once at every game start.

Tip: You can find the location of your logs by looking it up in Project > Open Project Data Folder.

View Project Data Folder Path

Tip: The Project Data Folder path is set in your Project Settings > Config as pictured below depending if you checked Use Custom User Dir and Name or if left it blank, it will use the default values of your OS.

Enable System Data Folder

Note: See more about Godot data paths here.

One final check, before you export and run your application, is to make sure you have the Export With Debug flag checked when exporting your app. If you don’t, you may not get any logs. This checkbox is found on the Save a File dialog that pops up after you click the Export Project button:

Check Export With Debug in Save Dialog

Once you export and install your Godot app, run it and check the log files as described above. The file log.txt is the the most recent and the rest are time stamped older ones.

Live Monitor The Logs

If need be, you can live monitor the logs on the terminal/console as you try different scenarios. On Mac/Linux the easiest way to do this is to open a Terminal, navigate to the logs file path and use the tail command to watch the the logs live.

Example: On Mac/Linux you would do something like this:

# navigate to data path
cd <Project Data Dir>/logs
# create an empty log.txt file if one doesn’t exist.
touch log.txt
# watch and display the log file changes.
tail -f log.txt

This will allow you to live watch the output of the log file while you test.

Note: For Windows you need to use a different tool to live monitor logs. Notepad++, a popular editor, has a plugin for watching file changes and probably something you would want for development anyway. Click here for a description.

Debugging with print()

Debugging strategies using print() are beyond the scope of this article, but you may want at minimum a time stamp along with the message. As such you can include a global script using the Autoload feature of Godot to customize the output.

Example: Create a script log_print.gd and add the following code example which adds a timestamp to a custom print() method:

log_print.gd

In Project Settings on the Autoload tab, choose the path of the script, give it a node name and click Add as pictured below:

Add An Autoload Script

Because the node Log becomes globally accessible, to use, all you have to do is reference the name and method:

Log.print("Value of x=%s, y=%s" % [x, y])

The output will include a time stamp. E.g.

19:57:58 Value of x=1,y=2.

Use assert() if you want the Log.print() statements to be removed when you go to release. This way they remain as part of your code, but have no effect in your final app.

# When Export With Debug is unchecked, asserts are removed 
# from exported code. This works because Log.print() returns
# always true.
assert(Log.print("Value of x=%s, y=%s" % [x, y]))

Of course you can add more sophisticated functions to the Autoload script. Godot has a variety of print functions. More info on Autoload can be found here.

Caveats

Keep in mind that debugging can affect code behavior (E.g. print() usage of CPU cycles, side effects of function calls, introduction of bugs, log file size). Test on all devices you plan to support.

Wrap Up

We have seen how to setup a Godot project to generate log files to use in debugging. The advantage to this method is that it is in the background, not normally interfering with game play, but yet allows you to track activity in a persistent file. Of course log output can be used for many other purposes as part of your application, so long as you are aware these files have to be managed to not clog the user’s device.

This is my first article on Medium. I hope it helps. Please let me know what you think. Thanks!

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade