The Torque Build Environment Manual and Introduction to Torque for the Complete Newbie by Chris Calef

1. Introduction -- Who Should Read This Document

2. What The Heck Have I Gotten Myself Into?

3. What Is Torque?

4. What Is A Compiler?

5. What Is A Debugger?

6. What is an IDE?

7. What is the Torque Build Environment?

If you are reading this, it is assumed that you have purchased the Torque Engine from Garage Games. If you have not yet purchased Torque, and would like to do so, go to the above link and grab it.

If you have purchased Torque already, then you may be wondering, "what is a Build Environment?" If you are not wondering this, and already have experience as a C++ programmer, then you probably do not need this document or the TBE installer. If you have Microsoft Visual Studio and use that for your C++ work, then proceed to the Torque docs that came with your download, they already explain how to compile Torque using VC++. In general, if you are an accomplished C++ programmer under Windows, Mac, or Linux, then you can probably find all the help you need in the existing Torque docs or the online forums.

However, if you have no idea what I'm talking about, then you are in the right place, please keep reading.

If you don't want the lengthy explanation of exactly what is going on, and just want to get on with compiling the project, you can go straight to the readme file.

2. What The Heck Have I Gotten Myself Into?

If you're new to programming, and you've already starting looking at the Torque SDK code, or surfing the Garage Games website, and are starting to feel your heart pounding in your chest and the sweat breaking out on your brow, as the question "Oh my lord what have I done?" starts to form on your lips,
my first word of advice is:

It's going to be okay, really.

Making a game is a BIG project, but it can also be very interesting and a huge amount of fun. You've made a good choice in picking the Torque engine as a starting place. Torque is big and complicated, like any up-to-date 3D game technology has to be, but it has a great support team at Garage Games, as well as a large, friendly and supportive base of users who are there to help each other out. You are not alone! When you get into trouble, don't hesitate to go to the forums on the Garage Games site. Whatever problem you're having, odds are that a number of other people have already been there, and have probably already asked a question about it and had it answered. If the answer isn't there somewhere already, just go ahead and start a forum thread with your question. It might take a day or two, but somebody will probably pop up who knows the answer to your problem.

And whatever else happens, always remember this: games are about FUN. If you get too stressed out in the process of making your game, you should stop for a little while, do something else, and then come back to it. Sometimes that's all it takes, and the answer to your problem is sitting right in front of you.

3. What is Torque?

Since this is a guide for a complete newbie, it is my goal to explain every concept that anybody might have trouble understanding. This means that those readers with at least a partial clue as to what's going on will probably find this document a slow read. I apologize in advance, and will attempt to keep as many basic explanations as possible linked out from the main document to make it more readable, but if you get bored feel free to skip ahead.

So, to indeed start from the very top, what is Torque, exactly? I'm sure you know it is something called a "game engine" and have a general idea that you can make games with it, or else you probably would not have shelled out the money for it. But what is a game engine, and how does it work?

The short answer: A game engine is a computer program that is designed to be modified and customized by people like you, such that you can use it to make your own game. What Torque does is provides the framework for efficiently drawing a 2D or 3D environment, playing sounds, communicating over a network, and accomplishing the many other tasks that are necessary parts of most games. What Torque doesn't do is provide the ideas, logic, shapes, sounds, artwork, and whatever else it is that makes your game unique and different -- that's your job.

Computer Programs

This doesn't really explain how it works, however. Backing up a step, Torque is a computer program, as is a finished game, a word processor, a spreadsheet application, and anything else you can run on your computer. Most people have a general idea of what a computer program is, but I'm going to explain it here in a little more detail, just to make sure we're all on the same page.

Basically, a computer program is a sequence of instructions for your processor. I say "processor" rather than "computer", because the term "computer" usually refers to the entire collection of cards, chips, disk drives, cables, and miscellaneous components that are all stuffed into the metal case sitting on your desk. The processor is the actual chip that reads sets of instructions (computer programs) and tells everything else in the computer what to do.

Just so we all know what we're talking about, I should also mention that what I'm calling a "computer program" can go under a number of other names -- it is called an "application", an "executable file", or other names, but in any event it is a binary file (<<< major explanatory note) that is stored on your hard drive and contains instructions in machine code, which your processor knows how to read. Some of these instructions cause the processor to send information to different parts of your computer, like the hard drive (to save a file), the monitor, to show you a visual image, or the speakers, to play a sound for you.

A 3D game contains a LOT of different kinds of information going to different places. First, there is input from the player -- every time the user moves the mouse or hits a key on the keyboard, some information is generated that has to be handled by the game. If the mouse controls the view of the player, as is common in "first person shooter" games like Quake, Tribes, Half-Life, etc., then every time the mouse moves the game has to reorient the player's view direction in the 3D world. Similarly, when the player hits a key on the keyboard, that might trigger the game to call up a menu, drop the player's weapon, make the player jump, or do anything else, whatever you as the game programmer/designer decide is going to happen in response to that keystroke.

The Torque engine also handles many other kinds of information. Sound files are stored and replayed in response to events in the game world, such as the "twang" sound when the player fires his or her crossbow, and the "boom" sound when the missile hits the ground or another player and explodes. Network information is stored and passed back and forth from the server to all the clients, recording where each player is and what they are doing. Shapes of all the objects in the world, as well as the terrain and the buildings, are all stored in different formats and used to create the view you see on the screen.

Programming Languages

So, now we know a little bit about the kind of information that a computer can understand. Unfortunately (or not), most humans are not equipped with the kind of brains that can easily interpret a string of binary data. This is where programming languages come in.

Programming languages are more or less similar to English, and are written in plain text, so you can work with them in any text editor. (If you really wanted to, you could write an entire game in Notepad. This would get pretty tedious, however, which is why we'll be discussing code editing environments, or IDEs, very soon.) There are many programming languages out there, and many books dedicated to describing specific languages or comparing the differences between them. For now, the main things you should understand are that 1) all programming languages have a set of reserved key words (or commands) which make up the basic language, and 2) beyond those key words, most languages allow you to define "functions" or "methods" with which you can encapsulate commonly performed tasks and give them your own names.

Torque is written in a programming language called C++. At this point I'm going to battle back my urge to start teaching you C++ right here and now, because there are so many good books and tutorials out there which will do a far better job of it that I would. Do a Google search for "C++ Tutorial" and you'll find plenty to keep you busy!

4. What is a Compiler?

So, how does that (relatively) easy-to-read programming language turn into the actual executable file that your processor knows how to deal with? The answer is a special kind of program called a compiler. This program takes your "source code" and compiles it into binary, so you can run it. Each programming language has its own compiler, and often there are many different compilers out there for a single popular language. The two compiler programs that we will be discussing are both C++ compilers; one of them, Visual C++, is a commercial product sold by Microsoft. The other, GCC, is a free program that has its origins in the Unix operating system. GCC is the one we will be using in the Torque Build Environment.

Compilers can do a little extra work besides just turning your source code into an executable. Most of them contain logic to do varying degrees of "optimization" to your code (making it execute faster), and additionally they can add information to the program that helps with debugging, if and when you find problems in your code.

The main thing, though, is that you have a compiler that works and builds Torque. Once you have that running, you can start changing the code and making it into your own game!

5. What is a Debugger?

In a perfect world, you could just write code all day long, compile it, and watch the results of your hard work executing beautifully every time.

Unfortunately, the world we live in is far from perfect, and neither are most programmers. People tend to make mistakes. Programmers call their mistakes "bugs". Sometimes they aren't even your fault... you may find results that are weird because of a bug in the underlying operating system you are using, or some other software that is linked into your project.

But in the end, it's probably going to be you that has to fix it. And sometimes, the problem can be maddeningly difficult to solve. You might try to start your game and all you will see is a message about something called a "stack dump", and it closes immediately, for example. Or it might run fine most of the time, but for some apparently random reason it just crashes out of the blue at odd times. This is the when you find out whether or not you really have the patience to be a programmer...

But at times like this, you learn what a debugger is for. A debugger is a special program that can run your program, but under close supervision. You can go so far as to step through your code one line at a time. You can set a "watch" on different variables to see what the values are along the way or what they were at the time the program crashed. You can set "breakpoints" that stop execution at an arbitrary point so you can see what everything looks like before it crashes. In short, debuggers are very nice tools to have.

GCC has a complementary debugger called GDB, which is what you will be using with the Torque Build Environment.

6. What is an IDE?

Like I said before, if you really wanted to you could write your entire game in Notepad. There is nothing special about the files that make up your source code, they are just plain ordinary text that can be edited in any word processor program. They can't be saved as a Word document or any other more complicated format, of course, because then they won't be plain text anymore, they will be a document formatted for some particular application.

However, there are special text editing programs out there called IDEs, for "Integrated Development Environment", that are designed just for writing code in specific programming languages. Once you see what they do, you will always want to use one. Here are just a few of the common features of an IDE:

• Syntax Highlighting: Color-coding of your source files, so that you can easily distinguish reserved keywords from comments from text that is in quotes... this is probably the single biggest reason right here that nobody ever writes code in Notepad.
• Compiler/Debugger Access: The IDE will have controls built right in that compile and even execute your program for you, so you don't have to go out to a command line in order to call the compiler.
• Project/File Outline: Usually an IDE has an explorer-type window that lists all the files in the project, which makes it easy to jump between them without going out to Windows Explorer or anything like that, and also for each open file there is usually a window that displays all the functions and allows you to jump right where you need to go, quickly and easily.

7. What is the Torque Build Environment?

So, now that you have some idea what all these parts are for, let's revisit the Torque Build Environment. Most people presently using Torque have Microsoft Visual Studio as an IDE, with VC6 or VC7 as their compiler. However, this is a commercial product, meaning you have to buy it from Microsoft, and we can't give it away for free all set up to compile Torque "out of the box". Also, it costs money, which some Torque users don't necessarily have a lot of, and we don't want to see that as an obstacle to creating your game with Torque. Therefore, we've put together the TBE as a "one stop solution", designed to get anybody and everybody up and running as quickly and easily as possible.

The TBE consists of the following things:
MinGW/Msys -- These are collections of unix/linux utilities that run under Windows. They are very useful for a lot of things, but the main reason we need them right now is for three programs: GCC, GDB, and a great little utility called "make" which lets you compile just the parts of your project that have changed, rather than having to rebuild the entire thing every time.

Eclipse -- As discussed above, this is the IDE you will be using. It requires the Java Runtime Environment, so the TBE Installer checks to see if you have it, and if not, takes you to java.com to get it.

Torque files -- there are a couple little configuration files in the "mk" directory under Torque that need to be changed for Torque to compile with GCC under Windows. The installer goes and changes these files, saving the originals with an extension of ".bak".

For complete step-by-step installation instructions, go to the TBE readme file.