3D Game Programming All In One (2004)

48 Chapter 2 ■ Introduction to Programming

Programming Concepts

For the rest of this chapter, we are going to explore basic programming techniques. We will be using Torque Script for all of our code examples and running our little programs in the Torque Engine to see what they do.

Now, we just covered the simple math problem in the previous section. I showed you what the program looked liked in binary machine language, hex machine language, assembly language, and finally C/C++. Well, here is one more version—Torque Script:

Notice the similarity to C/C++? Even the comments are done the same way!

As demonstrated, Torque Script is much like C/C++. There are a few exceptions, the most notable being that Torque Script is typeless and does not require forward declarations of variables. Also, as you can see for yourself in the preceding code, Torque Script requires scope prefixes (the percent signs) on its variable names.

Typeless? Forward Declarations? Huh?

In many languages, variables have a characteristic called type. In its simplest form, a type merely specifies how much memory is used to store the variable. Torque Script doesn't require you to specify what type your variable has. In fact, there is no way to do it!

Forward declarations are a construct whereby the programmer must first indicate, usually at the beginning of a file or a subroutine block, what variables will be used and what their types are. Torque Script also doesn't require this and again provides no mechanism for using forward declarations.

So now that you know what types and forward declarations are, you can forget about them!

The goal for you to achieve by the end of this chapter is the ability to put together simple programs to solve problems and have enough understanding of program techniques to make sensible decisions about the approaches to take.

How to Create and Run the Example Programs

There is an ancient and well-understood programming cycle called the Edit-Compile-Link- Run cycle. The same cycle applies with Torque, with the exception being that there is no link step. So for us, it can be thought of as the Edit-Compile-Run cycle. A further wrinkle to toss in is the fact that Torque will automatically compile a source file (that is, a program

Team LRN

file that ends with .cs) into the binary byte code file (ends with .cs.dso), if there is no binary version of the file, or if the source file has changed since the last binary was created.

So I guess my point is, for us the cycle can now be regarded as the Edit-Run cycle.

■Put all user programs in the folder C:\3DGPAi1\CH2 as filename.cs where "filename" is a name you've either made up yourself or one that I've suggested here in the book.

■Run from command shell tge -CH2 filename.cs.

Hello World

Our first program is somewhat of a tradition. Called the Hello World program, it is used as an early confidence builder and test program to make sure that the Gentle Reader (that would be you, if you are reading this book!) has everything in place on his computer to successfully edit, compile, and run a program.

So, assuming that you've installed both UltraEdit and the Torque Game Engine, use your newly learned UltraEdit skills to create a new file with the name HelloWorld.cs and save it in the folder C:\3DGPAi1\CH2. Type into the file these lines of code:

//========================================================================

//HelloWorld.cs

//

//This module is a program that prints a simple greeting on the screen.

//========================================================================

function main()

// ----------------------------------------------------

// Entry point for the program.

// ----------------------------------------------------

{

print("Hello World");

}

Save your work. Now, use the following procedure to run your program:

1.From your Windows Start menu select the Start, Run.

2.Type command in the edit box offered. This will open a Command window or MS-DOS Prompt window.

3.In the new window at the command prompt (the blinking cursor), type cd C:\3DGPAi1 and then press Enter.

Team LRN

50 Chapter 2 ■ Introduction to Programming

4.Next, type tge -ch2 HelloWorld.cs. A Torque window will open up, and you should see something like Figure 2.10, with "Hello World" in yellow at the upper left of the screen. Cool, huh?

t i p

If you don't get the expected result on your screen, then look in the log file, named console.log, located in the C:\3DGPAi1 folder. If there were any errors in your program, diagnostic information will be deposited there. It might be something as simple as a typo in the file name.

Let's have a closer look at the code. The first thing you will notice is this stuff:

//========================================================================

//HelloWorld.cs

//

//This module is a program that prints a simple greeting on the screen.

//===============================================================

This is the module header block. It is not executable code—it's what we call a comment. The double-slash operator ("//") tells the Torque Engine to ignore everything from the slashes to the end of the line.

So if the engine ignores it, why do we use it? Well, it's included in order to document what the module does so that later when we've completely forgotten the details, we can easily refresh our memory. It also is included to help other programmers who may come along and need to understand the module so they can add new features or fix bugs.

Team LRN

Then there is this part:

function main()

That is executable code. It is the declaration of the function block called main(). Following that, there is this:

// ----------------------------------------------------

// Entry point for the program.

// ----------------------------------------------------

This is the function header. The function header is included in order to describe the specifics of a function—what it does, how it does it, and so on. In this case it is fairly simple, but function headers can get to be quite descriptive, as you'll see later. Again, this is not executable code (note the double slash) and is not required to make your program work. The dashes could just as well be stars, equals signs, or nothing at all. It is good practice to always use function headers to describe your functions.

Finally comes this:

{

print("Hello World");

}

That would be the function body—the guts of the function where the work is done. The function body is also sometimes called a function block, and more generically (when used in other contexts that you'll see later) called a code block.

All sample programs in this chapter must have something called function main(). Don't worry about why that is for the moment—we'll get into that later. Just take it as a given that it is necessary for your programs to work properly.

It is important to note the way a function block is made. It always begins with the keyword function followed by one or more spaces and whatever name you want it to have. After the name comes the argument list (or parameter list). In this case there are no parameters. Then comes the opening, or left, brace (or curly bracket). After the opening brace comes the body of the function, followed by the closing, or right, brace.

All functions have this same structure. Some functions can be several pages long, so the structure may not be immediately obvious, but it's there.

The actual code that does anything interesting is a single line. As you know by now, the line simply prints the text "Hello World" in the Torque window.

Team LRN

52 Chapter 2 ■ Introduction to Programming

n o t e

Experienced C programmers will recognize the main function as the required initial entry point for a C program, although the syntax is slightly different. Torque doesn't require this organization for its scripts—it is purely for learning purposes.

Expressions

When we write program code, most of the lines, or statements, that we create can be evaluated. A statement can be a single Torque Script line of any kind terminated by a semicolon, or it can be a compound statement, which is a sequence of statements enclosed in left and right braces that acts as a single statement. A semicolon does not follow the closing right brace. Here is an example of a statement:

print("Hi there!");

Here is another example:

if (%tooBig == true) print("It's TOO BIG!");

And here is one final example of a valid statement:

{

print("Nah! It's only a little motorcycle.");

}

Statements that can be evaluated are called expressions. An expression can be a complete line of code or a fragment of a line, but the important fact is that it has a value. In Torque the value may be either a number or text (a string)—the difference is in how the value is used. Variables are explained in the next section, but I'll sneak a few in here without detailed coverage in order to illustrate expressions.

Here is an expression:

5 + 1

This expression evaluates to 6, the value you get when 5 and 1 are added.

Here is another expression:

%a = 67;

This is an assignment statement, but more importantly right now, it is an expression that evaluates to 67.

Another:

%isOpen = true;

Team LRN

This expression evaluates to 1. Why? Because true evaluates to the value 1 in Torque. Okay, so I hadn't told you that yet—sorry about that. Also, false evaluates to 0. We can say the statements evaluate to true or false, instead of 1 and 0. It really depends on whatever makes sense in the usage context. You'll notice that the evaluation of the statement is determined by whatever expression is to the right of the equal sign. This is a pretty hard- and-fast rule.

Consider this code fragment:

%a = 5;

if (%a > 1 )

What do you figure that the (%a > 1 ) evaluates to, if %a has been set to 5? That's right— it evaluates to true. We would read the line as "if %a is greater than 1." If it was written as (%a > 10 ), it would have been false, because 5 is not greater than 10.

Another way we could write the second line is like this:

if ( (%a > 1 ) == true )

It would be read as "if the statement that %a is greater than 1 is true." However, the Department of Redundancy Department could have written that example. The first way I showed you is more appropriate.

Just for your information, in the preceding examples, %a and %isOpen are variables, and that's what is coming up next.

Variables

Variables are chunks of memory where values are stored. A program that reads a series of numbers and totals them up will use a variable to represent each number when it's entered and another variable to represent the total. We assign names to these chunks of memory so that we can save and retrieve the data stored there. This is just like high school algebra, where we were taught to write something like "Let v stand for the velocity of the marble'' and so on. In that case v is the identifier (or name) of the variable. Torque Script identifier rules state that an identifier must do the following:

■It must not be a Torque Script keyword.

■It must start with an alphabetical character.

■It must consist only of alphanumeric characters or an underscore symbol ( _ ) .

A keyword is an otherwise valid identifier that has special significance to Torque. Table 2.3 gives a keyword list. For the purposes of Torque identifiers, the underscore symbol ( _ ) is considered to be an alphanumeric character. The following are valid variable identifiers:

Team LRN

54 Chapter 2 ■ Introduction to Programming

It's up to you as the programmer to choose the identifiers you want to use. You should choose them to be significant to your program and what it is doing. You should always try to use meaningful identifiers. You should note that Torque is not case-sensitive. Lowercase letters are not treated as distinct from uppercase letters.

You assign values to variables with an assignment statement:

$bananaCost = 1.15;

$appleCost = 0.55;

$numApples = 3;

$numBananas = 1;

Notice that each variable has a dollar sign ("$") preceding it. This is the scope prefix. This means that the variable has global scope—it can be accessed from anywhere in your program, inside any function, or even outside functions and in different program files.

There is another scope prefix—the percent sign ("%"). The scope of variables with this prefix is local. This means that the values represented by these variables are valid only

Team LRN

within a function, and only within the specific functions where they are used. We will delve into scoping in more detail later.

Using our fruit example, we can calculate the number of fruit as follows:

[$numFruit = $numBananas + $numApples;

And we can calculate the total cost of all the fruit like this:

$numPrice = ($numBananas * $bananaCost) + ($numApples * $appleCost);

Here is a complete small program you can use to try it out yourself.

//========================================================================

//Fruit.cs

//

//This module is a program that prints a simple greeting on the screen.

//This program adds up the costs and quantities of selected fruit types

//and outputs the results to the display

//========================================================================

function main()

// ----------------------------------------------------

// Entry point for the program.

// ----------------------------------------------------

{

$bananaCost=1.15;// initialize the value of our variables

print("Cost of Bananas(ea.):$"@$bananaCost);

//the value of $bananaCost gets concatenated to the end

//of the "Cost of Bananas:" string. Then the

//full string gets printed. same goes for the next 3 lines

print("Cost of Apples(ea.):$"@$appleCost); print("Number of Bananas:"@$numBananas); print("Number of Apples:"@$numApples);

$numFruit=$numBananas+$numApples; // add up the total number of fruits $total = ($numBananas * $bananaCost) +

($numApples * $appleCost); // calculate the total cost

Team LRN

56 Chapter 2 ■ Introduction to Programming

//(notice that statements can extend beyond a single line)

print("Total amount of Fruit:"@$numFruit); // output the results print("Total Price of Fruit:$"@$total@"0");// add a zero to the end

// to make it look better on the screen

}

Save the program in the same way you did the Hello World program. Use a name like fruit.cs and run it to see the results. Note that the asterisk ("*") is used as the multiplication symbol and the plus sign ("+") is used for addition. These operators—as well as the parentheses used for evaluation precedence—are discussed later in this chapter.

Arrays

When your Fruit program runs, a variable is accessed in expressions using the identifier associated with that variable. At times you will need to use long lists of values; there is a special kind of variable called an array that you can use for lists of related values. The idea is to just use a single identifier for the whole list, with a special mechanism to identify which specific value—or element—of the list you want to access. Each value has numerical position within the array, and we call the number used to specify the position the index of the array element in question.

Let us say you have a list of values and you want to get a total, like in the previous example. If you are only using a few values (no more than two or three), then a different identifier could be used for each variable, as we did in the Fruit program.

However, if you have a large list—more than two or three values—your code will start to get awkwardly large and hard to maintain. What we can do is use a loop, and iterate through the list of values, using the indices. We'll get into loops in detail later in this chapter. Here is a new version of the Fruit program that deals with more types of fruit. There are some significant changes in how we perform what is essentially the same operation. At first glance, it may seem to be more unwieldy than the Fruit program, but look again, especially in the computation section.

//========================================================================

//FruitLoopy.cs

//

//This module is a program that prints a simple greeting on the screen.

//This program adds up the costs and quantities of selected fruit types

//and outputs the results to the display. This module is a variation

//of the Fruit.cs module

//========================================================================

function main()

Team LRN

%mangoIdx=3;

%pearIdx=4;

%names[%bananaIdx] = "bananas"; // initialize the fruit name values %names[%appleIdx] = "apples";

%names[%orangeIdx] = "oranges"; %names[%mangoIdx] = "mangos"; %names[%pearIdx] = "pears";

%cost[%bananaIdx] = 1.15; // initialize the price values %cost[%appleIdx] = 0.55;

%cost[%orangeIdx] = 0.55; %cost[%mangoIdx] = 1.90; %cost[%pearIdx] = 0.68;

%quantity[%bananaIdx] = 1; // initialize the quantity values %quantity[%appleIdx] = 3;

%quantity[%orangeIdx] = 4; %quantity[%mangoIdx] = 1; %quantity[%pearIdx] = 2;

// Display the known statistics of the fruit collection

Team LRN