Builder Manual Chap. 05

Testing your Game
If you've been following this manual you have already briefly used the Test mode in the last chapter. The test mode is an essential component of the builder, and one that you will use often, especially as your game begins to take shape.

The test mode is pretty self explanatory, it will run your scene and the scene script (and other scripts if they are loaded in the scene script). The most important thing to understand about test mode is that it runs off of the local files on your local folder. So if you make a change to a script, or a texture, or a sound in your local directory and hit "Refresh" on your browser, it will begin test mode again, but it will use the newly changed resources.

Understanding how the Test mode works will greatly increase your productivity, because constantly going back to the builder and starting the test mode again when you change a resource can be time consuming. The only time you need to close and re-open the test mode is if you want to make changes to a Scene Object within the builder.

In addition to running the game out of your local files, the Test Mode also contains a Debug Console, which is an essential programming aid, and is described below.

Using the Debugger
The Debugger (or Debug Console) is a programmers best friend. You have access to the debugger while in test mode and in the builder itself. To access the debugger on the builder you can click "Debug -> Debug Console" or click the Debug tab on the right side of the screen (docking the debugger on the bottom area of the builder is a favorite layout here at the office). The debugger will start opened and docked in test mode. There are several things the debugger is good for, but by far the most important is to display Lua Error Messages.

When the developer makes a syntax error (a command that Lua doesn't understand), an error message will be printed in the Debug Console, as well as a file name, and line number where the error occurred. These errors aren't always very descriptive, so you might have to stare at the source of the problem and use trial and error until it goes away.

The function "print" outputs its text into the Debug Console as well, which can be an extremely powerful problem solving aid, more on that below.

The Debugger is also a fully functional Lua interpreter. So you can type Lua commands in the lower box and hit Execute (or Shift+Enter) to run the code. For example typing "print(Camera.getEye)" in the console will display the position of the camera.

Solving Physics Problems
When working with the engine's physics system it's important to have a good understanding of the way everything works. If you're having problems getting objects to move, or if they don't collide with each other, or if they push each other apart when they shouldn't, then the first thing you should do is read the entire [http://wildpockets.com/manual/chap-08-physics Chap. 08 - Physics] [16] of the programming manual.

A lot of the physics related problems you might encounter will be due to the fact that the object you are using doesn't have a collision volume. To verify that, you should click "View -> View Collisions" in the menu toolbar. If you don't see red squares or spheres around your object then it doesn't have collision volumes. If that's the case then you should find another object that has collisions in the Library, or if you created and exported the model yourself, then you need to go back and add the collision volumes.

There is also another set of tools that can be extremely helpful with trying to solve physics problems. Gizmos are boxes, spheres and lines that are rendered on top of every object. These are easily created in code and you can move them around like every other object. You can see an example of using Gizmos for debugging purposes in the Super Penguin game [17] (press D to toggle debug information).

Visit [http://wildpockets.com/manual/chap-12-gizmos Chap. 12 - Gizmos] [18] on the programming manual for more information, and instructions on how to create and use these Gizmos.

Solving Programming Problems
Solving programming problems (or debugging - where the term comes from) is a complicated and time consuming chore.

Lua syntax errors are usually pretty descriptive and by looking at where they occur, you can usually figure out what is wrong (if not, stare at it for a while, and then ask your fellow programmers over at the Support Forums [19]). A Lua syntax error looks like this:

Error: attempt to index global 'someClass' (a nil value) IN Debug Console line 1 The "Error:" contains a description of the error that occurred, and the "IN" contains a file location, as well as a line number of where the error occurred.

Logic errors are much more complicated though. How can you tell which functions execute first? How can you tell if a function gets called at all? How can you tell if your function does what you think it does? And the answer is: print.

Inserting print statements on top of functions lets you know when they get called. Inserting print statements before a return call lets you know what value your function is returning. There are lots of situations where print statements can help you understand what is going on within your code. However, doing several print statements per frame has a big impact on game performance, so it's a good idea to comment them out, or delete them once you know that your code works the way you intended it to. You can do that or have a super global variable that tells your game whether it's running in debug mode or not. Consider the following code:

-- Define a super global variable, visible in ALL scripts, called _debug GLOBAL["_debug"] = true;

-- Execute Initialization Functions function onSceneStart -- Check if the _debug variable has been set to true, if so print out which function we're in. if(_debug) then print("*** SCENE INITIALIZING ***") end initializeSceneObjects; setUpControls; setUpCoroutines; -- Set up GUI rendering routine. GuiManager.call("paintGUI", paintGUI, 1);

-- Check if the _debug variable has been set to true, if so turn on debug information, otherwise skip it. if(_debug) then toggleDebugInformation end end To learn more about super global variables and other scope levels refer to the bottom of [http://wildpockets.com/manual/chap-07a-module-system Chap. 07A --- The Module System] [12] in the programming manual.

Upgrading Builder Version
If you are using an old version of the engine (ex: 1.5 or 1.4) and you want to use the newest features of the builder you can change the version that the Pocket is associated with. Click here [20] for more information.