The Game Programmer’s Guide to

The Game Programmer’s Guide to Torque Under the Hood of the Torque

A GarageGames Book

Edward F. Maurina III

A K Peters, Ltd. Wellesley, Massachusetts CRC Press Taylor & Francis Group 6000 Broken Sound Parkway NW, Suite 300 Boca Raton, FL 33487-2742 © 2006 by Taylor & Francis Group, LLC CRC Press is an imprint of Taylor & Francis Group, an Informa business

No claim to original U.S. Government works Version Date: 20110714

International Standard Book Number-13: 978-1-4398-7115-7 (eBook - PDF)

This book contains information obtained from authentic and highly regarded sources. Reasonable efforts have been made to publish reliable data and information, but the author and publisher cannot assume responsibility for the validity of all materials or the consequences of their use. The authors and publishers have attempted to trace the copyright holders of all material reproduced in this publication and apologize to copyright holders if permission to publish in this form has not been obtained. If any copyright material has not been acknowledged please write and let us know so we may rectify in any future reprint.

Except as permitted under U.S. Copyright Law, no part of this book may be reprinted, reproduced, transmitted, or uti- lized in any form by any electronic, mechanical, or other means, now known or hereafter invented, including photocopy- ing, microfilming, and recording, or in any information storage or retrieval system, without written permission from the publishers.

For permission to photocopy or use material electronically from this work, please access www.copyright.com (http://www. copyright.com/) or contact the Copyright Clearance Center, Inc. (CCC), 222 Rosewood Drive, Danvers, MA 01923, 978- 750-8400. CCC is a not-for-profit organization that provides licenses and registration for a variety of users. For organiza- tions that have been granted a photocopy license by the CCC, a separate system of payment has been arranged.

Trademark Notice: Product or corporate names may be trademarks or registered trademarks, and are used only for identi- fication and explanation without intent to infringe. Visit the Taylor & Francis Web site at http://www.taylorandfrancis.com and the CRC Press Web site at http://www.crcpress.com This book is dedicated to my wife Teresa, for her encouragement, her advice, and most of all for her tolerance of the odd hours I kept while locked away in my office writing this book.

I must give special thanks to Jerry for acting as an idea bouncing-board and for listening patiently as I discussed chapter ideas over, and over, and . . . .

Of course, I must also thank the many members of the GarageGames community for their unfailing interest in the guide and their encouragement.

Lastly, I would like to thank the GarageGames staff for making the publication of this book possible, giving specific thanks to the “draft reviewers”—Josh Williams, Matt Fairfax, Ben Garney, Matt Langley, and Justin Dujardin.

v

Contents

Preface ...... ix

I Introduction 1 Introduction ...... 3

II Engine Overview 2 Torque from 10,000 Feet ...... 13 3 Torque Tools ...... 35 4 Introduction to TorqueScript ...... 97

III Game Elements 5 Torque Core Classes ...... 143 6 Basic Game Classes ...... 157 7 Gameplay Classes ...... 201 8 Mission Objects ...... 263 9 Game Setup Scripting ...... 347 10 Gameplay Scripting ...... 383 11 Special Effects ...... 419 12 Standard Torque Game Engine GUI Controls ...... 455 13 Game Interfaces ...... 539

IV Making the Game 14 Putting it All Together ...... 571

Index ...... 599

vii

Preface

So, you want to make a game? You may be standing in a bookstore holding this book in your hands, or you may be reading this online. Whatever the case may be, some or all of the following thoughts and questions are probably run- ning through your mind: • I want to make a game, but can I do it on my own or with a small team? Making a game is great fun, and a very rewarding experience. You can defi nitely make a game alone or with a small team as long as you have the right tools available to you. One of those tools is the Torque Game Engine (TGE) and the other is Game Programmer’s Guide to Torque (GPGT). Using TGE and GPGT, you can create any game that your imagination can encom- pass and that your skills will allow. • TGE sounds good, but will GPGT tell me what I need to know to make my particular game? TGE is a powerful and fl exible game engine that can be used to make any number of different and unique games. You may choose to make single-player or multiplayer games. The game can be a shooter, an adventures, or a role-playing-game, to name just a few. Game Programmer’s Guide to Torque will teach you the Torque skills you need to create these game types. (See section 1.1, “About the Torque Game Engine,” and section 1.2, “What This Guide Contains,” to learn more.) • Can I get up to speed fast enough to make my game? Like any other complex and powerful piece of , Torque can be hard or easy to learn. Everything depends on your approach to the task and whether you have the right resources available to you. With Game Programmer’s Guide to Torque, with the hundreds of samples that come on the accompanying disk, and with the experience of making the sample game we write while reading this book, you will be able to ramp up very quickly and to move on to your goal—namely, making your own game. Having been down the path you are just now starting upon, I know how hard it can be to get started and how hard it is to stay motivated in the face of the many challenges involved with learning to use Torque along with the other skills you will need to acquire. I decided to write this guide so that others would not have to struggle to learn Torque. In closing, this guide is the result of my own need for a better reference and my desire to help other learn about the powerful and fl exible Torque Game Engine. It is the culmination of my own game-writing and Torque-using journey. I sincerely hope that it provides you a pleasant beginning to your own game-making adventures. ix

Introduction Part I

Chapter 1 Introduction

1.1 About the Torque Game Engine 1.1.1 What Is Torque? The Torque Game Engine (TGE) is a AAA 3D game engine made available to the indie games community by GarageGames. It is the product of many years of dedicated work and interactive design and development by the staff of Dynamix, a well-known game development company which the founders of GarageGames previously started. As Dynamix made games, they would reuse and refi ne, taking the best parts of their work to the next generation of the engine. With this engine, they produced games like Earthsiege, Starsiege, Tribes, and eventually . All in all, it is safe to say that the code in this engine has its roots in code written as far back as 1995 and perhaps even earlier. In summary, the Torque Game Engine is a product with man-centuries of development done by proven experts who time and time again used this engine to produce stellar titles. As far as I know, there is no other game engine like this on the market at any price.

1.1.2 Why Should I Use Torque? Educational: One of the best ways to learn programming is to read code written by other developers. If you are going to read code, you might as well have fun and read game code and learn a few tricks in the process. Resume Building: Mod (modify) the engine to show off your skills to future employers. MOD Makers: How many times have you gotten stuck trying to mod other engines because they did not support feature X? Now you have the source and can easily add any features you want and truly differentiate your mod from the rest. To Make Great Games! That’s what we all live for, so do it. This is an unprecedented opportunity to build your game using an industry-proven game engine that rocks! —GarageGames Site One of the beauties of the Torque Game Engine is that you don’t have to use it to make games. “What’s that, you say?” I repeat, you do not have to use the Torque Game Engine to make games. With the features included in this engine, you can just as easily make a variety of professional, educational, or “your category here” products. 3 Part I Introduction

Of course, you must abide by the end user license agreement (EULA), but once you have licensed the engine, the terms of the agreement are pretty free about what you can create. The only real limitation is your own imagination.

1.1.3 Not Just First-Person Shooters Some people, examining the Torque Game Engine for the fi rst time, may be under the impression that it is only for making fi rst-person shooters (FPS). Nothing could be further from the truth. Yes, it is well suited to the FPS genre, but it can and has been used to make a variety of different game types.

Current Titles

Action Games

Marble Blast GOLD Think Tanks

Lore Orbz

4 Introduction Chapter 1

Sports

RocketBowl Plus Golden Fairway

Educational

3-D Language Spain

Upcoming Titles

Racing / Driving

dRacer

5 Part I Introduction

Role Playing Games

Minions Of Mirth

1.2 What This Guide Contains By the end of this book, you will understand how to use Torque, and we will even make our own little game in the process. This book aims to fi ll the following needs. • Learning guide. The guide is designed to quickly walk you through the concepts and learning required to get started on your own games. To that end, it comes with a lesson kit containing complete sets of ready-to-run sample scripts (from discussions) and sample lessons covering all topics discussed. • Reference guide. To make this guide useful even after your preliminary learning experience is complete, the guide is formatted in a way that facili- tates looking up specifi c topics. Also, it comes with quick-reference guides covering all TGE console classes, scripting, script functions and methods, GUI (graphical user interface) controls, etc. • Prototyping help. This guide and the accompanying lesson kit in combi- nation with the resources that come with TGE itself should provide all the materials you will need to create your own game prototypes. • Teaching aid. The guide and associated kit have also been designed with the classroom in mind. The contents are suitable to support game-design courses. A specialized kit is included containing many ready-made les- sons/samplers in the following categories: scripts, GUI controls, interfaces, HUDs (heads-up displays), and all of the major 3D/engine topics discussed in the guides. All lessons can be extended, and new lessons can be added with relatively little effort.

1.2.1 Summary This book is intended as a starting point for the completely new user, but it is also suitable for the user who is moderately experienced with Torque already. 6 Introduction Chapter 1

It has the following chapters: • Part I: Introduction • Chapter 1: Introduction • Part II: Engine Overview • Chapter 2: Torque From 10,000 Feet. This chapter gives the ten-minute description of Torque and introduces the new user to important con- cepts and terminology. • Chapter 3: Torque Tools. Here, we discuss all of the built-in tools and establish an understanding of how to use the TGE kit in editing mode. • Chapter 4: Introduction to TorqueScript. Here, we introduce the em- bedded scripting language that comes with TGE. This chapter covers the complete syntax and the major concepts required to work with this scripting language. • Part III: Game Elements • Chapter 5: Torque Core Classes. This chapter examines the core script- ed classes and their importance in the hierarchy, structure, and behavior of the engine. • Chapter 6: Basic Game Classes. Here we cover the basic classes used to represent shapes, images, and interiors. • Chapter 7: Gameplay Classes. This chapter reviews the classes through which we implement game interactions that defi ne the gameplay. We also introduce important game-design concepts like the inventory. • Chapter 8: Mission Objects. TGE provides a myriad of object classes. In this chapter, we discuss all of the mission/game/level placeable objects that have not yet been discussed, excluding special effects. • Chapter 9: Game-Setup Scripting. Here we work through in-depth dis- cussions of critical scripting classes and features that are associated with setting up and maintaining a game. • Chapter 10: Gameplay Scripting. In this last scripting chapter, we ex- amine a variety of scripting functions, examining how they work and providing the context in which they contribute to gameplay. • Chapter 11: Special Effects. This chapter splits out several classes used for audio and visual special effects. • Chapter 12: Standard TGE GUI Controls. In this chapter, we discuss the 32 most important GUI controls. • Chapter 13: Game Interfaces. This follow-on chapter builds on the last chapter and walks through the creation of two sets of themed game in- terfaces. Each set includes a splash screen, a main menu, and a credits screen. We also specify and design three types of HUD to show that complex HUDs can readily be created from basic TGE controls. 7 Part I Introduction

• Part IV: Making The Game • Chapter 14: Putting It All Together. Here, we build a complete single- player game prototype. We plan the game; accumulate many of the exam- ple scripts, shapes, interiors, and interfaces created in the prior chapters; and glue them all together with a small set of gameplay-specifi c scripts. • Appendices. In order to facilitate the learning process and to fi ll the role of reference, an extensive set of appendices is included in electronic form. These appendices include complete references of game class fi elds and methods, console functions, callbacks, and GUI controls, to name a few.

1.3 What This Guide Does Not Contain This guide obviously does not contain the answer to every question that every person who uses Torque can come up with. My hope is that it contains enough information and is accessible enough that you can learn how to answer these unanswered questions on your own. However, sometimes that just isn’t going to happen, so a “Getting Help” appendix has been included to assist you. First, though, let’s determine what you should know before starting.

1.4 What You Should Know Before Reading This Guide Ah, the fateful question, “What do you, the reader, need to know?” First, understand that this guide is here to help you, but you are going to have to do some real work to learn what it has to tell you. TANSTAAFL: There ain’t no such thing as a free lunch. —Robert Heinlein Second, since this guide is aimed at a broad audience, I have created a pseudo-matrix below listing topics you should at least be passingly familiar with based on your role in your team.

Who Are You? Some Stuff You Ought To Know

I’m like, the artist, dude. • Basic modeling and animation concepts: convex vs. concave, skeletal animations, texture (IFL) animations, blended animations. • At least one modeling tool in this list: MilkShape 3D (MS3D), 3ds Max, Maya, or gameSpace/trueSpace. (Yes, there are other options; see appendix.) • If the only tool (in the prior list) you know is MS3D, then be sure to add QuArK, Cartography Shop, or Hammer to your list. • More? Sorry, this isn’t an art guide. In fact, you probably know more about art than I do! 8 Introduction Chapter 1

Who Are You? Some Stuff You Ought To Know

I’m the programmer, man. • C/C++ You got any Dewsky? • Scripting in Perl, TCL, or perhaps another game-engine scripting language. • Math. If you fl inch when I say algebra, geometry, trigonometry, vectors, matrices, or Cauchy-Schwartz inequality (OK, you can fl inch on that last one), MathWorld (http://mathworld.wolfram.com/) is your friend. • If you are familiar with client-server architectures and simulation concepts, you will have a great head start.

I am the game designer. • The limitations of your target system(s) as well as Enter my world . . . the limit on the speed of light. Sure, your team can probably make a 4096-player RFMMOTTTG (really freakin’ massively multiplayer online tick-tack-toe game), but you probably don’t want to. I’m only partly joking here. If this is your fi rst game and you are the idea guy or gal, keep it realistic. There is real work in making a game. • The limits of the tools your team’s programmers, artists, and other folks use to implement your ideas.

Me da boss. • What the . . . ? Why are you reading this . . . er, I mean you should know of course, Sir/Madam/Other, every member on your team will need two copies of this guide. One for work and one for home. We can’t have people getting hernias carrying these back and forth.

Jack of all trades (JOAT), • This guide is specifi cally written for you (and for small AKA lone wolf. teams). You will need to know everything on the list above (excluding da boss). Also, be sure to look at the reference appendix and get your hands on some of those books and resources. You’ve got a real challenge ahead of you, but you can do it!

1.5 How To Obtain Torque (Licensing Torque) OK, so you’re sold. You’ve bought this book (please tell me you’re not standing in the bookstore still deciding . . .). Whatever the case, you have decided that this Torque thing sounds like a good deal. To get your hands on this state-of-the-art engine, simply do the following: 1. Visit the GarageGames website: http://www.garagegames.com/. 2. Follow the links to the products page. 3. Add Torque to your cart. 4. Click the “Buy Now” button and follow the instructions. 9 Part I Introduction

1.6 Getting Started, One Step at a Time . . . On fi rst picking up the Torque Game Engine, you may be somewhat overwhelmed. If asked, most GarageGames members will probably admit that they were, too, and so was I. The fact is, this engine and all the associated fi les are massive. Just doing a quick count on the current version of the code brings up the following metrics (counts may vary): • 2329 source fi les containing 593,930 lines (~325k lines of code and ~167k lines of comments), • 322 script fi les containing 49,856 lines of script (~37k lines of of script, and ~7k lines of comments), and • this guide comes with a kit that adds another 187 script fi les containing 19,566 lines of script (~11k lines of script, and ~5k lines of comments). No matter how you twist it, turn it, chop it, or sort it, Torque is big. Big not only in raw size but in features. However, approached with an inquisitive mind, and with the understanding that nothing is free, especially an understanding of the ins and outs of this engine, you can master Torque.

1.7 The GarageGames Community and Resources I’ve stated this in more than one forum, and I must state it here: the GarageGames community is excellent. I continue to be impressed on a daily basis by how well attended the forums are and how quickly people give answers to questions. The GarageGames site provides several resources. • Forums. These are areas where you can post questions, ideas, general complaints, etc. To date, there have been tens of thousands of posts. At last count (not including forums dedicated to released games), there were 12 major forum categories containing 64 subcategories. • Resources. These are community submitted items including scripts, code, web links, books that are good to read, accumulated references, and more. These resources are organized by date and rating (among other catego- ries). • News. The GarageGames site has a news page and a newsletter. Very cool.

1.8 Conventions Throughout the guide, I will attempt to align my naming conventions and terminology with those you will encounter in the offi cial Torque SDK (software development kit) documents and elsewhere on the GarageGames site. In the cases where this is not possible, I will make it clear that the names/terms in 10 use are of my own invention. Introduction Chapter 1

1.8.1 Icons Legend: Warnings, Notes, and Expert Tips Throughout this guide, you will be presented with side notes of various forms. Some of these will be warnings of odd or misleading behavior, others will be notes on interesting bits or facts, and some will be expert tips for those who want to explore the edges of Torque’s behaviors. You will be able to recognize these side notes by looking for the following icons.

Warning Note Expert Tip

1.8.2 Game-Building Lessons Throughout the guide, you will fi nd sections marked as one of the following: 1. Maze Runner Lesson #123 (90 Percent Step). If you intend to make the game at the end of the guide, you must complete these lessons. They con- struct game elements without which the game will not function. 2. Maze Runner Lesson #123 (10 Percent Step). These lessons are consid- ered optional when making the initial version of the game. If you should choose to skip them, the game will still be playable but may be a bit rough around the edges. These lessons will be largely independent of each other, but if a lesson depends on another lesson, the numeric ID of the lesson, as well as the chapter it is in, will be referenced.

Combined Lessons Appendix For those who want the entire lesson set in one place, all of the lessons from the printed chapters, up to but not including Chapter 14, are included in the “Combined Lessons” electronic appendix.

Skip Ahead! To learn about the motivation for the above lesson titles, and to learn what the game will be, please skip ahead to Chapter 14. There, you should read Section 14.1, “Maze Runner: A Simple Single-Player Game,” which includes the following. 11 Part I Introduction

• Game Elements. Here, we will briefl y discuss the concept of a game element. • Game Goals, Rules, and Mechanics. Next, we will explore the motivation for planning a game’s goals, rules, and mechanics before we write the game. Then, we will do this planning for our game. • Setting up our workspace. Before we can start working on the lessons, we need to set up a workspace. In this section, I will instruct you on what steps are required to prepare for the lessons. • 90 Percent or 10 Percent? Lastly, I will give you an overview of the 90 percent versus the 10 percent steps and why these ideas matter. So, skip ahead; it’s OK. When you’re done, you can come back and start learning about Torque!

12