From TDN

Contents 1 Introduction 2 What's in the script? 2.1 Engine vs. TorqueScript 2.2 Control of the Engine with TorqueScript 3 What has already been done for me? 3.1 Directory Structure 3.2 Main.cs 3.3 The Game Folder 3.4 The Common Folder 3.5 Engine Functions 4 Where do I start? 4.1 Modifying the Game Folder 4.2 Building from the Ground Up 5 What else should I know? 6 Final Thoughts

Introduction

Now that you've downloaded the engine, played with the examples provided and poked around in the "example" folder - chances are you are a little lost. To help with your understanding, this article has 3 aims:

• To get you familiar with the scripting portion of your game.
• To understand what's given to you already.
• To understand what you need to work on and where to look.

These issues will be discussed in a non-technical way.

Although it's not technically a requirement, this article also assumes that you've already read the TorqueScript overview, or at least have a basic knowledge of the TorqueScript language.

What's in the script?

This is probably the first question that crosses the mind of a developer new to Torque. Virtually all game logic is in the script. This includes placement and orientation of all objects in the game, how fast your player moves, what happens when the player gets hit, and a long list of other gameplay features. Besides gameplay, included in the example are editors such as the Mission Editor, GUI Editor, Particle Editor, and other tools all written in script to help with your development.

Engine vs. TorqueScript

Some game logic falls into the actual code of the engine. Unfortunately, to get a good feel for what exactly is and isn't available in script you need to go into the example and find out yourself. The process of finding out exactly what you're looking for in script isn't nearly as difficult as it seems. Generally, when you can't find a particular game feature you want in your game, if it's not in the script, it's in the engine. 90 percent of the time it's in the script if it concerns game functionality. If you need a reminder as to why so much of the gameplay functionality is found in script, check out this link. It's impossible to make a complete list in terms of gameplay and technical values to show what is in script and what's in the engine. There are many reasons for this, one of them being you can technically choose to have as much or as little as you want in script. This is because you have the complete source to TGE. However, the "example" is a very good demonstration of the script that typically is, or isn't found in a Torque-made game.

Will I have to modify the engine? You can build your game only coding with TorqueScript. Indeed this is what people did before the Torque (or V12) engine was released, making a modification or a total conversion of Tribes 2 entirely within TorqueScript. Depending on how similar in design you game is compared to Tribes 2, there's a chance that you will eventually want to make a change in the engine when working with TGE. If you do, help can be found here.

Control of the Engine with TorqueScript

It's important in a scripting language for a engine to be able to communicate with the script and vice-versa. For this reason, a lot of important engine functionality can be found "in the script". The engine exposes parts of itself to TorqueScript to allow you to control a great deal. You help steer the engine with tools given to you such as calling engine functions, defining functions in script called by the engine, setting client and server preferences, and using special objects (RootGroup, ClientGroup), among other things.

As an advanced warning, because you have so much control over what the engine does you can muck things up a little. Problems could stem from improper use of "special" SimGroups (or $instantGroup confusion), mixing up Server and Client, etc. However, these topics are much more advanced and are out of the scope of this article.

What has already been done for me?

Everyone wants to make their game with as little effort as possible. This section will give you a good idea as to what you don't need to do for your game. The structure of the example will be discussed first, giving you a better idea what is where and how it all comes together.

Directory Structure

*Note: This directory structure does not correspond to the directory structure found in Torque 1.4. The "common" folder is divided into the folders "creator" and "common". The "creator" folder essentially contains all the "common" sub-folders relating to the tools used for your game. This picture is kept as a reference to those who are still developing with a 1.3 codebase.

Not all of the files in the example are listed here, and the diagram doesn't exactly match what's in the "example" folder. However, this diagram does demonstrate the file structure of a general "game". Throughout the rest of the article the "game" folder will refer the game you would be working on or playing with, such as "starter.fps". The diagram above also demonstrates another important point; to load any of the example "game"s in the folder, you need at least that game folder, and the common folder. The reason for this will become apparent shortly.

The Game folder refers to the current game you would be loading (e.g. starter.fps). When Torque starts up in your example folder only one of the "game" folders is chosen to start up. The Common folder contains script functions and the tools that would be used for all "game"s. This includes the editors, tools, and frequently used functions. Both the common and game folders contain their own main.cs file. Don't confuse these with the main.cs in the same directory as your executable. The main.cs files contained in the Common and Game folder contain functions that are packaged and then activated.

So what about all of those different file types? The three to pay the most attention to in terms of scripting are your .cs, .gui, and .mis files. These files are regular script files. Why have a different file extension for files that all contain script? Catagorization and organization of script is important - you'll tend to find mission related scripts in the .mis files, GUI (Graphical User Interface) related scripts in the .gui file, and all of the rest of the scripting in the .cs files. Each file can contain whatever scripting you want. You can, for example, contain all of your game scripting in your .gui files, and all of your GUI related scripts in your .cs files. You may find some GUI files may contain a function definition here or there, but it usually relates to the GUI itself. It's your own call when it comes to what goes where. But it helps to keep things organized as your project grows!

DSOs There will be files in your folder which also contain .dso extension. This extension will be found at the end of your script extension (e.g. .cs.dso). A DSO is simply the compiled version of your script code. It's important to note that if you get a compile error, the engine will simply use the last working .dso when running your game.

Main.cs

When you run your example, the executable searches for this file - arguably the most important file in TorqueScript. Located in the same directory as your Torque executable, this is the entry point for execution of your script, and therefore your game. In the example given, this script file's job is to load the appropriate folders and their resources into memory. This depends on which game you chose. You can choose your game either by using the command line or just loading the default game. This involves engine function calls (such as loading or "exec()"uting other script files) and other script function calls that initiate and drive the game.

What? No function main()? If you program in other languages such as C/C++ or Java you may be used to finding a "main" function or method. This is not the case in TorqueScript. All script that isn't contained within a block is executed in order. In the example provided, Main.cs is the only file that makes function calls not contained within another function. At the end of the file a single function call of "onStart();" (defined in main.cs of the Game folder) starts a long chain of initialization routines.

The Game Folder

The game folder is the folder of the game you are currently loading up (such as starter.fps, or demo). In the example provided, main.cs decides which game to load by loading the appropriate folder and it's resources (via SetModsPath). The Game folder contains all of the game related scripting. When you're scripting for your game this is where you'll be spending most of your time editing, creating, and tweaking script. You'll also notice the two folders "Server" and "Client". These two folders help organize information for server and client scripts respectively. This topic is so important that it deserves its own article. For now, realize both folders are there and that both are related to your game. The only folder within the Game folder left to discuss is the "Data" folder. This (as you may have already guessed) contains all of the media content of your game. All artwork and sound is in this folder along with a few script files. Notice that the .mis files are found inside. Remember, these files are script, and get "exec()"ed just like all of the others, so you can open it up with your editor, type away, add functions, comments, etc. Generally speaking, you'd only find information pertinent to the missions in these files. There are a few .cs files in there as well, but they contain functions calls, or structure definitions relevent to the data in the folder. An example is the player.cs, which contains information on the player shape (or DTS) itself - nothing else.

What are these MODs loading? You may have noticed when looking around the script, or just looking at the console output during or after the game loads up, that there's a lot of mention of the term "MOD". A MOD is shortform for modification. If you've ever installed a mod for one of your favorite games (like Tribes 2), you probably remember copying over a folder containing the mod, then loading it up with a console parameter such as "-game modgoeshere". In fact, this is how you load up the other "MOD"s in your folder such as "demo", "starter.racing", or "tutorial.base". Your MOD is your game (and you would probably make it the default one). When your "game" folder loads up, technically you aren't modifying anything except possibly redefining and therefore overwriting functions (see TorqueScript functions). The functions you would be overwriting would be found in the Common folder, discussed next.

The Common Folder

The Common folder could be referred to as the "script engine" portion of your game. This folder was designed to be the multi-purpose tool for scripting for games of all kinds. It contains tons of scripting functions that are specifically designed to make the whole process of scripting easier. Just a brief look at the file structure can give you a good feel as to what has already been done.

The subfolders "Editor" and "Help" contain scripts and files for the Mission, GUI, and Particle editor and their appropriate help files (which can be loaded in game). The lighting folder contains commonly used bitmaps for lighting. The UI (User Interface) folder contains commonly used GUIs (including "MessageBox"es, and tons of GUI default definitions all of which you can find in the GUI editor). The Client and Server contain common routines used in your Client and Server portion of your "Game" scripts respectively. The discussion of the Server vs. Client can be found in this article.

A complete listing of what functions the common folder contains doesn't exist - yet. Some common functions used in the "common" folder are simple functions such as initClient(), initServer(), or createServer(). Take a while browsing through all of the stuff written for you, you'll be amazed at how much you don't need to do (or worry about).

Engine Functions

Remember, you do have the ability to make engine function calls from in-script. Your game will contain at least a few engine function calls.

The complete list of commands (or exposed engine functions) can be found here.

Another important way to interface with the engine is defining functions that are called (whether you like it or not) by the engine. The list of script functions called from within the engine is made up almost entirely of methods (member functions) and only a few function calls. A complete list of functions called into the script from engine doesn't exist yet.

For the more C++ inclined, to get a good idea of what is called by the engine, search around in the engine files for "executef()"; if there's an object as it's first parameter, it's a method, otherwise it's a straight up function call.

Where do I start?

So now that you have a base knowledge of the scripting language (and if you don't, start with the TorqueScript overview) and you have a good idea as to what you already have to work with, how do you start making your game? There are two typical approaches taken by the GarageGames community: Modifying the Game folder and building your Game folder from the ground up.

Modifying the Game Folder

This seems to be the more popular approach when it comes to first working with Torque, and the popular "game" folder to modify is starter.fps. For example this is how Marble Blast by GarageGames started. They modified the FPS starter kit (starter.fps) just like many other developers in the GarageGames community. This method has its benefits. The most important of which is fast prototyping (see sidebar). Try experimenting with the different values found in player.cs (but not the "Data" version), and you'll see how easy it is to start tweaking and modifying your game right away. By modifying the starter.fps folder, you have an already-working game to modify. This means getting your game idea up and running ASAP without having to worry about a lot of script technicalities in the early stages.

What is "prototyping"? "Prototyping" means getting a mockup of your game done ASAP when developing your game. This entails leaving your artwork and other content as filler at best and hammering out gameplay first. Continually refine your design as fast as possible. It's an awful situation to be in when you have so much code, artwork, music and sound committed to a game that isn't fun. Save yourself effort and make sure the game is fun to play before committing content. GarageGames stands by the notion that prototyping is key to the success of any development. Gameplay first, content later.

Building from the Ground Up

With the excellent method shown above, why go through the bother of writing the script for your game from the ground up?

Building from the ground up provides an excellent way of learning all of the ins and outs of the scripting side of your game from the get go. All things being equal, using this approach will increase your knowledge of the scripting technicalities much faster than the previous approach. You'll be spending a great deal of your time looking at the other "game" folders given and looking for scripting examples. When you do manage to get your game up and running you'll have a completely stripped down version of a game and you will know exactly what is and isn't being put into your game - less cleaning up later. It will take noticibly longer for you to get to your prototyping stage, but it will also provide a more hands-on learning experience.

This approach is not as extreme as it may seem. If you choose to write from the ground up, you will want to consider (then reconsider, twice) using the common folder. It will save you tons of time in development and since it contains common routines for each game, you're better off using it. You shouldn't have to re-write the mission or GUI editors unless you have an exceptional reason. Remember - fast prototyping is key, getting your game up and running is first and foremost.

Is it worth the effort? The choice is yours.

What else should I know?

To understand and to develop with Torque properly and well, it's important to have at least a base knowledge of how Torque works. This means understanding the networking model, differences between Client and Server, various "Torque"ish terms used frequently like SimObjects, "Ghosting", and Control Objects. Read up on these topics and others on TDN.

Why would you want to learn how the engine works? If you look around in your example code you'll find funny sounding comments and function calls such as "setControlObject()" or stuff about "transmitting client ghosts". Understanding the terminology and the technical aspects of the engine gives you a much better clue as to how everything comes together in your game. Check out the "Essential TorqueScript Articles". Even if you're not experienced in a language like C/C++, it couldn't hurt to try and poke around in here and see if you can grasp some understanding.

Final Thoughts

You've now probably got some undestanding of what's given to you already and what you need to know and work on. One of the best ways to learn is by going into the script and working with it yourself as best as you can. You will get stumped, confused, and maybe completely lost. This is okay, here's how to deal with it.

• Learn from the "example" given - Just reading through the script gives you an idea of what's what. Use "Find in files" or "Find in Project" liberally. Try your best to investigate what you're looking for.

• Search and read articles here on TDN - A no-brainer. Chances are someone has already had the same problem you have, and they may have submitted an article about it here on TDN. This is definately your first stop when looking for any Torque related answers.

• Search the Forums - then use them - Forums. Search them first! Someone may have already asked your question. Save everyone some time: use the google miniapp and search. If you still can't find the answer to your problem, post it. Take your time when writing your question or describing your problem, often just writing out the problem can lead to sudden insights and figuring it out for yourself. If you do post, make sure you ask your questions the smart way. This will increase your chances of getting the answer you were looking for.

You have a lot of work to do! So get to it, make your game, and have fun!