 |
 About debugging
While writing scripts for your games, you often find yourself in need to fix something that doesn't work right.
Sometimes it can be easy, like when you misspelling the name of a function, or forget a bracket.
The engine will inform you about it, by displaying a message box with the error and the place where it occured (file and line number).
You will just have to edit that file, fix the problem and try again.
But sometimes, the problem is not very obvious, and you have to dig for it.
To help you in the process of debugging your code, the DizzyAGE engine offers the benefit of a developer console and a few debug keys.
They become available in developer mode, that is if you start the game with the dev option set to 1 in the configuration file, dizzy.ini
The developer mode, is also noted in the top left corner of the game's window, when active.
The devtools came with this option activated by default, but it's important you remove it completely, from the configuration file,
when you release your game.
The debug console
During the game, press the [`] key (or [F2]) to open the debug console.
It moves the game's screen in the top left corner of the application window and it shows the log information below it.
You may want to start the game in a higher resolution, to see more debug information.
Use [ctrl+add] and [ctrl+sub] keys to resize the game's screen.
The console uses the [page up], [page down] (also combined with [shift]),
[home] and [end] keys to scroll information.
The log messages are text information, dumped from the engine, or from the scripts with the
println command.
This can be very helpful in displaying the content of some variables or properties values that you inspect while debugging.
You can also use it to track the flow of execution, by displaying dummy messages that tell you if the execution reaches that part of code.
You must remove all unnecessary debug messages from the scripts, when you release your game.
The log messages are also dumped in the dizzy.log file and players
can enable or disable it, by setting the log option to 1 or to 0, in the configuration file.
Request this log file from players that report difficulties in running your game on their PC, or from those who report bugs.
On the bottom lines of the console, there are displayed information about the player's position, the current room and the
current execution callstack of the latent virtual machine.
You can see in the image above, that, while the inventory menu
is opened, the latent code from the RunDialogSelect() function is running, being called from the OpenDialogInventory(), that was
called from the Action() function. This Action function was requested from the action handler when the action key was pressed.
The console also allows you to enter script commands during gameplay.
Press the [insert] key and observe the flashing currsor, above the bottom information lines.
Write a simple GS9 command, like println("test"); and hit [enter] to accept it.
See how both the command and it's result are dumped as log messages.
Try to display the player's position, with the println(PlayerGet(P_X)); command.
This technique is very usefull while debugging, to view or change properties values for different objects, to move the player,
or even to call previous prepared functions, for debug purposes.
The input line supports [left] and [right] arrows,
or [ctrl+left], [ctrl+right] for horizontal move of the cursor
The [up] and [down] keys are used for previous entered commands
and [backspace], [del] and [ctrl+del] to delete text.
An autocomplete feature is also supported. Start writing a command (like prin) and press the [tab] a few times,
until the function or the define name you need is displayed.
Another feature of the console are the debug slots.
These are 16 texts displayed on the right side of the screen.
The user can set anything he wants in these texts with the DebugData.
For example they can be used to watch the proprty value of a specific object, like it's position or it's status.
The setting is usually made per frame, on the HandlerDebug handler.
Remove all these debug settings in the release version of the game.
You can see in the image above, that, while the inventory menu
is opened, the latent code from the RunDialogSelect() function is running, being called from the OpenDialogInventory(), that was
called from the Action() function. This Action function was requested from the action handler when the action key was pressed.
The debug keys
While in developer mode, the folowing keys are available:
|
|
[`] or [F2]
Opens or closes the console view.
[ctrl+add], [ctrl+sub]
Resizes the game's screen, similar to the scale option.
[ctrl+arrows]
Moves the player in the next room (left, right, up, down).
[shift+arrows]
Moves the player with 4 pixes (left, right, up, down).
[F4]
Toggles material and density views.
[F5]
Reloads scripts during gameplay. Use it to avoid restart (when possible).
[F6]
Reloads game map during gameplay. Use it to avoid restart (when possible).
|
There are also other menus, like the save or open game menu, or like the credits menu.
These are called as the result of selecting their options, in the menus noted above.
Users should adjust the OpenDialogCredits menu, according to their needs.
Homework
Play a little with the debug settings presented above to learn how and when to use them.
Use the input command line to move the player at a specific postion, during gameplay.
Try to display the player's P_STATUS property, on a debug slot and see how it's changed as you move and jump arround.
Uncomment the print commands from the beginning of the handler functions in the handlers.gs file and see when each of them is called,
by watching the log messages dumped in the console.
Use dummy messages to track the execution flow of the action event, from it's handler, up to an action or use object callback.
To learn more about debug from the reference chapters:
Engine exported debug functions
Config file options
|
|
|
