Torque Game Engine DocumentationVersion 1.3.x
| Torque Game Engine Documentation Version 1.3.x |
This chapter is adapted from Ed Maurina's outstanding Essential Guide to TGE. The full version of the EGTGE will be released soon, watch for it! In the mean time, a free preview version is available. Check it out, Ed's work is awesome, and EGTGE should be required reading for any serious Torque developer.
Table of Contents
This chapter offers an introduction to TorqueScript. You will not be a TorqueScript master after simply reading this chapter-- that takes time and practice. But you will walk away with a good feel for how TorqueScript is structured and how it works in general. You will be familiar with the set of tools TorqueScript offers to help you make your game. With this knowledge in hand, you will be ready to take off and start learning how to best use the tools TorqueScript gives you to work with. There are many additional documentation and tutorial resources to help you along after you finish this book. Check out the GarageGames Torque tutorials page for more information.
It is assumed in the below that you are familiar with some basic programming concepts. You do not need to be a guru, and you don't need to know the nitty-gritty specifics of a particular language like C++, but you should be familiar with the basics of computer programming to get the most from what is offered here.
As you probably know, all modern, complete game engines offer a method of programming game behavior via some sort of scripting language. But what exactly is a scripting language? What can you do with scripts? And why are they used so much in modern game development?
Scripting languages are just programming languages that do a good job of making code easy to write. If you look at the history of programming languages, you can see a rough progression from very low-level languages that are difficult to read and write, to higher-level languages that are much easier to work with. For example, Assembly language was available long before C++. Assembly is very hard for most people to read and write, and though you can write most any program in either C++ or Assembly, C++ is usually a better choice since it is much easier to write, test, debug and maintain. The down-side is that C++ code sometimes runs more slowly than assembly.
Likewise, scripting languages offer some advantages over older languages like C++, and can really be considered yet another step in the progression of programming languages. In fact, many scripting languages look very similar to C++, but allow you to write code without worrying about nitty-gritty details like data-types or memory management. Scripting languages also allow you to modify your program without having to re-compile code. This can be a major advantage. However, script code usually doesn't run as quickly as C++ code.
Given all of the above, it should be easy to see why scripting languages are used so heavily in modern games. Indeed, most modern game programmers now write code with the following point of view: if you have a given piece of functionality to write, start assuming you should write it in script, and only decide to write it in C++ if it is absolutely necessary. This is the same way programmers think about the difference between C++ and Assembly: between these two choices, most code should be in C++, and Assembly should only be used where absolutely necessary.
That's the general overview. Below are some more specific areas where the ease, flexibility, and rapidity of writing scripts can really be advantageous:
Prototyping- During the development of your game, you will often need to test out ideas. New gameplay features might come up, or features in the original design might not work as well as envisioned and will need to be modified or replaced. To be efficient, you will need the ability to quickly test all these ideas, so you can decide whether to keep or modify each of them. Creating these quick tests is called "prototyping". Scripts are great for prototyping because they are so quick to code with, test, and modify. After you prototype in script, performance-critical functionality can be ported over to C++ for final inclusion in the game.
Debugging- Scripts can be great for debugging too. Since scripts are easily modified on the fly, you can identify problems, change them, and re-test without having to re-compile. Scripts can also be used to quickly create test units which stress other pieces of code to identify problems.
Game customization and tweaking- The look and feel of a game's interface and many of its gameplay mechanics usually go through numerous tweaks and revisions during the course of development. Thus, it is best to place most code related to these areas in script. This helps to rapidly test different looks and gameplay behaviors, as mentioned in the point on prototyping, above. There is a side benefit to developing your game this way as well: having code related to your interface and gameplay in scripts allows your players to customize your game to their liking (but only to the extent you choose to allow them, when playing the official version of your game).
Also, these types of script changes are the basis of many partial game-mods. Partial-mods are very popular in games like Unreal, Quake, and Tribes. Taking Tribes 2 as an example, the War 2002, Renegades, and Team Aerial Combat are all script-based partial-mods. From a coding perspective, partial-mods can be very simple to implement when working with games that incorporate flexible scripting languages and use them for much of the game's code. Implementing your game in such a fashion can obviously be a big draw for potential players that are interested in playing or creating mods.
Total-Mods- Much like partial-mods, game total-mods are very popular and are usually also based on script coding. Total-mods completely change the way a game looks and plays, unlike partial-mods, which don't go as far. Both are more easily done in games which include robust scripting languages, however.
Writing non-performance-critical functionality - Really, any piece of functionality which won't have a big impact on performance can be coded in script. Writing render-pipelines in script isn't a good idea, but writing GUI responses and most gameplay functionality is.
Scripting makes sense in many more situations. The inclusion of scripting languages is a powerful feature of modern game engines, and developers are wise to leverage the advantages of scripting at every sensible opportunity.
If you accept that scripting is useful, what should you be looking for in a scripting language? What functionality should it provide? At minimum, a scripting language for use in a game should provide the following features:
Some other (very) nice features to have:
Familiar and consistent syntax- Ideally, the syntax of a scripting language is familiar, meaning it is similar to the syntax of a language many programmers are already familiar with, for example C or C++. Also ideal is that the syntax is consistent with the known language, meaning the same rules which apply to the familiar programming language also apply to the scripting language.
Object-oriented functionality - Object-oriented programming has been a revolution in the art and science of software engineering. Scripting languages which provide object-oriented functionality offer many benefits, including:
'On-demand' loading and scoping- Why have all the code in memory at once when it can be loaded it as needed? Besides saving memory, scripting languages which allow the dynamic loading and unloading of pieces of code also make it easy to over-ride a program's functionality on the fly.
Means of 'speeding-up' scripted code- Scripted code is usually not compiled- it is simply interpreted at run-time. A feature that many common scripting languages (PERL, TCL, VB Script, Java) provide is the ability to 'compile' scripts into pcode. This pcode is then 'executed' on a virtual machine. The benefits of this are size and speed. Pcode is (normally) smaller than and executes faster than interpreted code.
Alright, enough generalities. What is Torque's scripting language like? TorqueScript is a very powerful, flexible language with syntax similar to C++. It provides all of the features listed above, including those on the 'would be nice' list. The following sections will describe all of these features and provide examples to clarify concepts. Additionally, there are scripting references in the appendix.
The next few pages detail specific TorqueScript features. During the explanations, many examples are provided. Example code will be shown in one of two ways:
So, how do you see the console? Easy. First, start the Torque demo application, then hit the tilde key '~'. The console will come right up:
You'll be seeing a lot of the echo() command in this chapter. We use the echo() command for testing purposes- it prints values out to the console. Echo() has the following syntax:
echo(string0 [, string1 [,...,[string n]]]);
Throughout this chapter, statements which appear in a box like the following show lines of actual TorqueScript code. Single-line statements can be copied and pasted (CTRL + V) directly into the console. Try these:
echo("Torque Rocks");
echo (1+1);
If you enter this code into the console and hit enter, you'll see it print "Torque Rocks" and "2". Anything placed inside the parenthesis of the echo() command gets echoed back to in the console. Makes sense, ay? Again, this command is used often during the explanations below.