ZScript Concepts

From ZCWiki
Revision as of 20:42, 17 February 2008 by ScaryBinary (talk | contribs) (→‎Statements: Added a little more info on the assignment operator.)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search

If you've never written code before, scripting can be a little intimidating. A ZScript is basically a set of instructions for the Zelda Classic game. A single instruction is called a statement. These instructions (statements) are organized into functions, which are in turn organized via different scopes into scripts. Within a function, different statements can be executed by using control loops, which make a decision based on information you specify, and form the scopes. You can declare variables to store information, such as important numbers, for later use, as well as referencing user-specific FFCs and NPCs, and declaring your own voids.

An Analogy

Let's start with an analogy. The English language (and most likely your own native language if it's not English) has a particular grammar that is followed. For instance, with a few basic elements, like nouns, verbs, and articles, you can create a sentence. Combine a few sentences that have a common theme, and you have a paragraph. A few paragraphs and you get a chapter; a few chapters, and you have a book.

ZScript has a similar hierarchy as well as a grammar that must be followed. Once you understand the basic building blocks of the ZScript language, you'll be able to create all sorts of scripts.

Operators, Operands, Expressions, and Statements

Operators and Operands

The nouns and verbs of the ZScript language are operators and operands. You're probably familiar with operators: these are things like + (plus), - (minus), = (equals), > (greater than), and so forth. They are called operators because they "operate" on one or more numbers or values. The numbers and values that operators "operate" on are called operands. See the following example.

5 + 6

In the preceding example, the + is the operator, while 5 and 6 are the operands.

For a more complete list of operators, and their purpose, see Operators. Most of the operators use two operands, though a few use only one.


A combination of operators and operands is called an expression. Note that an expression always has a value, as noted in the examples below. Also note than an expression can contain more than one operator.

5 + 6      has a value of 11
x = 2 + 3  has a value of 5, which is stored in a variable named x
5 > 4      has a value of true, because 5 is indeed greater than 4
2 + 7 < 3  has a value of false, because 2 + 7 is 9, which is not less than 3
Link->HP   has a value of Link's current number of hitpoints


An expression all by itself has a few uses (for instance, you'll see expressions in if statements) but for the most part ZScript expects something more. Just like you need to put a period at the end of a sentence, so you know where one sentence ends and the next begins, you must end your ZScript "sentences" with some sort of punctuation. In ZScript, that punctuation is the semicolon ";". When you've ended your sentence with a semicolon, you've turned your expression into a statement.

As noted above, a statement is an instruction for the Zelda Classic game. For example, the expression


doesn't do much all by itself. But the statement

Link->HP = 16;

actually commands the Zelda Classic game to set Link's hitpoints to a value of 16 (which is 1 heart).

The assignment operator, "=", deserves some special attention here. It will be discussed further in the Variables section, but for now understand that the assignment operator assigns the value of the right-hand operand to the item on the left-hand side. For instance, in the statement

x = 2 + 3;

the assignment operator's right-hand operand is the expression "2 + 3", which has a value of 5. Thus, the assignment operator assigns a value of 5 to the variable named x. Assignment is always from right to left. For instance, the following is not valid:

5 = x;

The above statement will not assign a value of 5 to x. In this case, you are essentially telling the script to assign whatever value x has to the number 5...but obviously 5 always has a value of 5, so the assignment operation fails (in fact, the ZScript compiler won't even compile such a statement).

Also take care not to confuse the assignement operator "=" with the equivalence operator "==". This is a common mistake with beginning programmers, especially when writing if statements.

To this point some fairly simple expressions and statements have been presented. Obviously, to build a great quest you'll need to do more than add numbers! Now that you understand the basic grammar of ZScript, let's introduce some other important concepts.


A variable is used to store a value. It's called a "variable" because you can change its value whenever you need to; its value can vary. The concept is somewhat similar to basic algebra, in which the letter "x" or "y" stands for some value.

In ZScript, you can name your variables whatever you want to, with the exceptions that you cannot use illegal characters (for instance, you can't have spaces or quotes in your variable names) and you cannot use words that already mean something else in ZScript (you can't name your variable "int" or "float", for example, since these are reserved for use by the ZScript compiler).

When you want to use the value you have stored in a variable, you simply use the variable's name in your expression. For instance, if the variable "Major_Damage" has a value of 64, then to subtract that value from Link's current hitpoints you would write:

Link->HP = Link->HP - Major_Damage;

The script would first subtract the value of Major_Damage from Link's hitpoints (shown as Link->HP above), and then assign that new value back to Link's hitpoints.

In essence, the above statement is the same as:

Link->HP = Link->HP - 64;

The important difference is that you can change the value stored in a variable. If later on in the script you want to change the value of Major_Damage, you can write:

Major_Damage = 48;

From that point on, Major_Damage will have a value of 48. Note that changing the value of a variable does not effect statements that were processed prior to the change.

There is another important thing to note here: variables can appear on both sides of the assignment operator. Let's consider the following example, assuming the variable Major_Damage has a value of 64.

Major_Damage = Major_Damage - 16;

This may seem odd at first, but remember that the assignment operator takes the value on the right-hand side of the operator and assigns it to the left-hand side. In this case, the right-hand side is the expression

Major_Damage - 16

We noted above that the current value of Major_Damage is 64; so the right-hand expression is 64 - 16, which is 48. Substituting that value for the right-hand side of the original statement yields

Major_Damage = 48;

Thus tells the game to save the value of 48 in the variable Major_Damage. From this point on, if Major_Damage appears in the right-hand side of an assignment operation, the value 48 will be substituted.

Before a variable can be used, you have to tell ZScript what type of value it will store. You do this by using a variable declaration, as shown below.

int Major_Damage;

In this case, you are telling ZScript you'd like create a variable named "Major_Damage", which will store integer numbers (indicated by the int above). There are several different data types you can use to create variables. For more information, see variable declaration. Again, you cannot use a variable in an expression or statement until after you've declared it.


A function is a bunch of statements, bundled together so they can be easily executed later. Typically a function will return a value. In this case, think of a function as a vending machine: you put a dollar bill in and you get a bag of chips out. Where are the chips stored in the vending machine? What picks them up and puts them where you can get them? It doesn't matter - all you need to know about the whole process is that you put a dollar in and get chips out. In this example, the "function" input is a dollar, and the function output is a bag of chips.

Similarly to how you use a variable, you use a function by including its name in an expression or statement. In this case, though, the function must always be on the right-hand side of the assignment operator, when the assignment operator is used; you cannot assign a value to a function.

A good example of a function is ZScript's built-in square root function, named Sqrt. It returns the square root of the number you give it. Just as you give a vending machine a dollar, you give Sqrt a number. Just as the vending machine returns a bag of chips, Sqrt returns the square root of your number. And just as you don't really know what's going on inside the vending machine, you don't know how Sqrt figures out what the square root is.

The following example shows how to store the square root of a number in a variable:

X = Sqrt(16);

Here, the square root of 16 would be stored in the variable named X. When you use a function, you put any inputs you give it in parenthesis, as shown above. Multiple inputs are separated by commas.

If you are writing your own functions, you must define them before you can use them (note that some functions, like Sqrt are already defined for you - take a look at the std.zh and zscript.txt files in your Zelda Classic directory). This is done with a function declaration. A function declaration tells ZScript (and other script developers!) how many inputs the function uses, what types of data those inputs are, and what the function returns. The following is a simple example function. The function Cube accepts one input, named NumberToCube, which is a floating point number (a number that has a decimal point in it). The function returns the cube of that number.

float Cube(float NumberToCube){
  return NumberToCube * NumberToCube * NumberToCube;

Now that you've defined the function, you can use it just as we used the Sqrt function:

X = Cube(2);

Here, the variable X would get set to Cube(2), which would be 8 (2 * 2 * 2). You can now call Cube whenever you want to, however many times you need to. Obviously this is a very simple example, but you can see how you can extend this concept to do more complex things.

See Also