From TDN

Contents 1 Creating and Debugging “Hello, world!” with Torque Game Builder 2 Hello, world! 3 TGB Start Up 4 Updating Main.cs 5 Creating a New Project in Torsion 6 Writing Your First Program 6.1 Packages 6.2 onStart’s implementation of “Hello, world!” 6.3 Global Script 6.4 Save Your Source Code 6.5 Save Your Project File 7 Time to Fire up the Debugger 8 Conclusion

Creating and Debugging “Hello, world!” with Torque Game Builder

 

Jason “TGB Boy” Cahill

February 26, 2006

 

Hello, friends! Well, it’s time to start exploring the path to gaming goodness. This article is aimed at starting you down that path and teaching you how to create your own Torque Script-based games and debug them within the Torsion environment. The project we are going to build is incredibly trivial, but equally important: “Hello, world!”

Hello, world!

Why is it always “Hello, world!”? Well, if you don’t have the background to answer this question, then your first step should be a trip over to Wikipedia to read the history of Hello world. The bottom line is: this sample is considered the simplest possible “game” running within the Torque Game Builder environment. Our goal at the end of this tutorial is for you to learn and master every line of code that is running within the project. We hope you are up for the challenge, because there’s a whopping 15 lines of code!

Depending on your experience level and what you’ve looked at since making your purchase of Torque Game Builder, trying to figure out where to start a new game can be very daunting. A quick browse of the C:\TGB\Latest\games folder that we setup in our previous article contains over 500 files and 88 folders… yikes! That’s a lot stuff to piece together by yourself. Fortunately, you won’t have to.

So, let’s get going, shall we?

TGB Start Up

TGB is sold as a “game builder” or “game engine” instead of an SDK. The difference is subtle, but important. A game engine is a fully compiled piece of software that you run, while an SDK is simply a collection of source code / helper functions you can use when building your own game executable. Because you don’t ever need to modify the source code of TGB to build a game, TGB needs to know where your “game” is and how to start it when you double-click T2D.exe. The secret to how your game comes to life is in the main.cs file that lives in the C:\TGB\Latest\games folder. This is the only piece of source code you are allowed to ship when you release a TGB game, and unless you want to make modifications to the underlying TGB engine source, this file is required.

So, what does it do? Simple: It launches “games.” That’s it. Nothing else. It provides a couple of command line options to let you customize which game it launches, but otherwise there’s nothing but basic initialization stuff happening in there.

Updating Main.cs

Now that we’ve told you very briefly what the purpose of main.cs is, it’s time to tell you that we need to tweak it. Unfortunately, this first step is a necessary evil. It’s also housekeeping that we will need for future samples and articles, so it’s good to get this out of the way now. Our basic mantra throughout all of the samples we will present is that you should just be able to drop in the source from one of our samples into your games folders and see the results working. Unfortunately, as TGB ships in this writing (TGB 1.1 Beta 1.1), the main.cs file that starts the execution of every game is lacking a few minor details. We’ve fixed these and have included this file here.

 

Download the updated main.cs file here

 

Click on the link above, and when prompted with what to do, click “Save” and save this over C:\TGB\Latest\games\main.cs. Once you’ve updated this file, we are in business!

Creating a New Project in Torsion

Now we are ready to have some fun! Let’s start by firing up our handy-dandy Torque Script editor and debugger: Torsion. When it loads up, you should see:

 

 

Our first step will be to create a new Torsion project. This is a set of files and settings used by Torsion to help remember what you are working on, where TGB is installed, and to make syntax highlighting and automatic as-you-type syntax completion work. I’m sure there are different schools of thought on this, but I’ve found I only have ever needed one Torsion project, regardless of how many game projects I’m working on. To begin, select the File menu, then select New, and then Project…

 

 

Once you do this, Torsion will pop up a New Project dialog as shown here:

 

 

In this dialog, you will type a couple of pieces of information. The first is the name of this project file. Because this project will be used for all of the samples we create together, I’ve typed in Samples as the name. Next, Torsion wants to know where the base directory of TGB is located. For this, we will type C:\TGB\Latest\games, as that’s where T2D_DEBUG.exe lives. Finally, we need to create a config, to debug our game. Click on the New button and another dialog will appear:

 

 

The Config dialog is the place where you can set all of the settings necessary to run your game under the Torsion script debugger. It requires three pieces of information: the name of this config, the executable file (TGB), and the arguments to pass when we execute TGB. For the Name, we’ve specified debug. For the Executable, we selected the debug build of TGB, T2D_DEBUG.exe. If you don’t have a debug build of TGB, then it’s time to go back and review our previous article and create one. Lastly, we need to specify some arguments.

Remember in the previous section we talked about how TGB starts? Remember that we mentioned that the main.cs file is the key to starting? Well, when main.cs fires up and starts executing, a big piece of its job is to parse any command line arguments that were passed to it. For this program, because it is the simplest possible TGB sample, we don’t want main.cs to load many of its default capabilities. As TGB ships, the games folder contains a large directory of “common code” that is used by all of the shipping samples like spacescroller and fish, it also loads a bunch of default editors like the level editor, GUI editor, and particle editor. For now, we don’t need or want any of those services. In later articles we will look at those, but for now, we want to keep it super simple! You’ll notice that the parameters we’ve specified are:

-nocommon -notools -game sample-001-console_hello_world

What the heck does this mean? It tells TGB (via the main.cs file) that when it loads, it shouldn’t load any common code or tools. Instead, it should just run the “game” stored in the folder sample-001-console_hello_world. Where’s that, you ask? We’re about to go and create it.

When you’ve entered all of these settings, click OK.

 

 

Now, click OK on the New Project dialog. As soon as you do this, you will get an ugly error-like dialog. It’s telling you that Torsion needs to run T2D_DEBUG.exe and export all of the information for automatic syntax highlighting and completion. This usually just takes a few seconds.

 

 

When it’s all done, Torsion will now have an explorer on the left hand side full of all the files and directories under C:\TGB\Latest\games as shown here:

 

 

OK, now there’s just one more thing before we start writing code: we have to create a file folder for it. Unfortunately, as of this writing, there is a bug in Torsion (version 1.0.357) such that right-clicking on Samples and selecting New Folder doesn’t appear to do anything. Dang. So, instead, let’s head over to My Computer and do the work. Click on your Start menu, then My Computer and navigate to C:\TGB\Latest\games:

 

 

If you’ve been following along through all of these articles thus far, your folder should look just like the one above. Click on the link entitled Make a new folder. Name the folder sample-001-console_hello_world.

 

 

This explains that –game setting we gave Torsion a few steps back. Closing this window and switching back to Torsion reveals that it has properly found the folder and it now appears in the explorer pane:

 

 

Writing Your First Program

Ready to write some code? Me too. Let’s get to it. Click on the File menu, then click on New, then click on Script.

 

 

When you are done, a new, blank script window will appear for you to type into. Click in the Script1 window and type the following source code (we’ll analyze and explain all of it in a minute):

package HelloWorldSample
{

   function parseArgs()
   {
   }

   function onStart()
   {
      EnableWinConsole(true);
      echo("Hello, World!");
   }

   function onExit()
   {
   }

};

activatePackage(HelloWorldSample);

When you are finished, your editor should look like this:

 

 

Before we start getting into the nitty-gritty of what all this stuff is, take a second to pat yourself on the back. You’ve just written your first complete Torque Script “game.” Granted it has pretty low playability, but I bet your mom would be proud of it. Anyway, let’s understand what this code does.

Packages

The first thing you see at the top of the file is a construct called a package. In Torque Script, discrete pieces of functionality are encapsulated within a package. Torque Script defines three special functions within the interface of a package:

• parseArgs() – a function that gets called as soon as your package is activated and allows you to look at and evaluate the command line arguments passed into your game (in our case they would be: -nocommon –notools –game sample-001-console_hello_world). Because our program doesn’t care about these arguments (they were already handled for us automatically by the root-level main.cs file that we updated), we didn’t write any code in this function. If you wanted to have a custom command line parameter and do something interesting with it (which I wouldn’t necessarily recommend), you could handle that here.




• onStart() – this function is kind of like main() in the C++ world. This is the place where you get to place your code when your package fires up. I say that it’s like main(), though, because unlike C++, when we run all of the code in onStart() and exit this function, TGB does not automatically shut down. TGB is a game engine and as such, run until it is told to shut down. If your code doesn’t explicitly tell it to stop, it will keep humming along merrily until to the end of time, or you decide to go and surf “streaming media” on the web, which ever comes first. The point is: this function is a place to initialize work that needs to get done, and then when you exit this function, the TGB main loop kicks in and runs until it is told to stop.




• onExit() – this function is called when TGB is finally told “STOP!” This is your chance to clean up anything you’ve created before TGB shuts down and exits. Because “Hello, world!” is such a simple program, we don’t do anything fancy here.

onStart’s implementation of “Hello, world!”

The only “interesting” piece of code in this entire file are the two lines of code inside the onStart() function:

   EnableWinConsole(true);
   echo("Hello, World!");

The first line of code shows the TGB console window as an ugly command line-looking window (we’ll see more of this later when we actually run the program). Generally, TGB-based games are graphical, using all sorts of pretty scrolling backgrounds, sprites, and tile maps. This sample doesn’t use any of that functionality… instead, we’ll introduce that functionality in a future article. So, because we aren’t going to create a graphical window, we still need a way to interact with the user. This console window does just the trick!

The second line of script will print the string Hello, World! to our text-based console. Pretty simple, right?

Global Script

Now that we’ve defined our “game” inside this package, it will just start up and run, right? You might think so, but you’d be wrong. Code within Torque Script, much like within other scripting languages, like JavaScript, has another layer: global script. Global script is code that gets executed immediately when parsed. Any code not contained within a function or a package is automatically run as soon as it is loaded. Within our source file, there is a single line of code in global script:

   activatePackage(HelloWorldSample);

This line of code will run immediately when it is loaded and will tell TGB to load the HelloWorldSample package. It will register the onStart method into TGB and it will get executed shortly. In a future article, we will look at package loading and unloading in more detail, for now just know that activatePackage is required to make your code run.

Save Your Source Code

OK, it’s about time to save our work, wouldn’t you say? Click on the File menu, then click on the Save as… menu. The Save as dialog will appear:

 

 

Make sure you save your file in the C:\TGB\Latest\games\sample-001-console_hello_world folder. Save your file as main.cs. This is the required name for your file. Naming it anything else will prevent your “game” for working.

Save Your Project File

The next thing we need to do is save our project file. This is the file that keeps track of all of those settings we typed in earlier. Click on the Save All button on the toolbar (or File | Save All from the menus):

 

 

This will bring up yet another Save as dialog, but this one is for your Torsion project file. Unlike your source file, save the project file in the C:\TGB\Latest\games folder and use the name Samples.torsion.

 

 

Time to Fire up the Debugger

OK, let’s see this thing run. Before we do, let’s add a breakpoint. If you’ve never debugged a program before, a breakpoint is a “stop sign” within your script where TGB will stop and let you look at the values of variables. Click on line 10 “EnableWinConsole…” and press F9. You should see a small red circle appear in the gutter next to line number 10 as shown below:

 

 

This means that when we run our program, TGB will automatically stop and return control to Torsion when it is about to execute line 10. Next stop: a running program! Press F5 (or click the small Play button on the toolbar) to begin executing your game.

 

 

After a second, a debug connection window will appear as TGB starts up. When this window disappears, TGB is running… and your code!

 

 

In a couple of seconds Torsion should regain focus and a small yellow arrow should appear inside your breakpoint:

 

 

Guess what? TGB was just about to run that line of code, saw your breakpoint, and stopped. In the Output window, you can see that TGB has loaded and parsed all of the command line arguments. It is now in the process of running onStart. Press F10 to execute the EnableWinConsole function and proceed to the next statement. You should notice a momentary flash as this window appears:

 

 

There’s the console! Woo hoo! Our code is running! Press F10 again to step over the next line of code (the echo statement):

 

 

There it is… Hello to you, my fine TGB program! Looking back at Torsion, we see:

 

 

TGB is about to exit our onStart() function and enter the main loop. Once in the main loop, TGB will run forever until told to stop. Notice that the output of the console window is also shown in the Output window in Torsion. That’s handy! When you are ready to proceed, press F5 to stop single stepping and run at full speed. The console window should come to the foreground.

 

 

Excellent. The last statement “T2D engine…” is letting you know that TGB has reached the main loop and is now awaiting further commands. This window is actually the in-engine console and you can type any valid Torque Script command here and it will execute. For example, type: echo(“So long, TGB!”); and press Enter. Look what you just did!

When you are ready to exit this program, go ahead and type: quit(); then press Enter.

 

 

Once TGB closes down, you will be back to Torsion just as before:

 

 

Great work!

Conclusion

Well, we’ve completed everything we set out to do in this sample. We created a brand new “game” within Torsion, wrote the code, and debugged it. To make it run faster, you can remove the breakpoint (by pressing F9 on line 10) and running it again. You can also play around with the other tabs in the bottom pane. In particular, the Watch window can be used to view the values of any Torque Script statement as you are stepping through code. Torsion is a really powerful Torque Script development environment!

Looking ahead, it may seem like we’ve got an awful long way to go to get to a video game from “Hello, World!” but surprisingly it won’t be. The skills you’ve learned in this article are going to pay you huge dividends as we move forward and start building on the fundamentals we’ve started. Great work, once again!