How to debug
Console and debugger
When games made with Escoria need testing, some errors and warnings may appear in the console. This information can be very useful when debugging issues.
If Escoria encounters an error or a crash, it will stop the execution of the game and return to the editor, showing you the line that broke. Usually, this line will be located in Escoria’s logger class, as this class is in charge of showing the errors before stopping execution.
Godot also shows the debugger panel but it is advised to check the output log first.
The console shows many lines, the verbosity of which depends on the log level defined in Project Settings. In order from most to least granular:
(The default logging level for Escoria is ERROR.)
In the example above, the error is explained in the line starting with
(“E” for “Error”, “D” for “Debug”, “I” for “Info”, “T” for “Trace”). The reason
for this error is that Escoria attempted to load a non-existant file. The
(E)rror line provides the path to the file that was expected. At this point,
fixing the issue is easy: Either create the missing file or remove any
references to this non-existant file in the scenes that use it.
This example is straightforward, of course. Sometimes, the issue can be trickier. In this next case, the Debugger panel will be of use.
We will not cover the use of the debugger panel in this documentation (information can be found on the official Debugger panel documentation page). The Stack Frames can be used to go back to the line that initiated the crash.
Finding the current state of the data held by Escoria during the execution of the game or at the moment of a crash is often necessary. These data can be easily accessed which can be helpful in understanding why the game is not behaving the way it is supposed to.
Find current Escoria data during the game execution
While the game is running, switch to the Godot Engine editor. In the “Scene”
tab, the “Remote” button reveals the actual state of the scene tree in the game
currently being executed. The
escoria object is located under the root
node where it can be selected.
Find current Escoria data when a crash occurs
In case of a crash, the
escoria object can easily be accessed in the
bottom-right corner of the debugger panel by clicking the
in the “Globals” section (framed in yellow in the following screenshot):
Access managers from the Escoria object
escoria object is selected in the Remote scene tree or in the
debugger panel, its contents are displayed in the Inspector:
Each manager object can be accessed by clicking the “Object ID” button next to its label. As an example, here is the result for the Objects Manager:
From there, every object can be accessed and checked. Same for the Globals Manager:
Escoria game crash management
Escoria comes with auto logfile and emergency savegame generation when a crash occurs. When that happens, it is notified in the console and in a crash popup.
As soon as the crash popup is closed, the game will terminate.
Hide or define a custom crash popup
By default, Escoria displays a simple
AcceptDialog with the content of
escoria/debug/crash_message variable as shown above. It
is automatically filled with the generated log and savegame paths.
If displaying the popup is not desired, it is then required to override the
show_crash_popup() function in the game script. For the popup not to show, this
function simply needs
If however a specifially themed popup needs to be displayed, then it can be
created in its own scene. The overriden
show_crash_popup() function can
then instance it and add it as child to the game scene. The text of the popup
needs to be manually constructed using Project Settings’
escoria/debug/crash_message variable and the
files: Array parameter of
the function that contains paths to all generated files when the crash
Whatever the way this function is implemented, it needs to finally emit the
crash_popup_confirmed when it closes: this signal is connected to an
internal function that terminates the game.