Introduction

So, you want to learn how to tap into the ley-lines of the universe, and wield power beyond anything possible before? Well, you're looking at the wrong tutorial. However, if you want to learn ZScript, so you can make your game more interactive and unique, you're in the right place!

Using ZScript, you can do anything from creating cutscenes to new items, custom 1x1 Octorok variants to huge, animated bosses. The sky is the limit, and your imagination is your key. But, not if you don't know what you're doing, of course :)

If you have a background in another language, especially C or C++, you're already ahead of the game! You should still read over these tutorials, however, as there are some important differences from other language.

If you're fresh to the world of programming, then never fear. I'll go slowly, and explain each step of the way, and help you understand. Learning ZScript is actually pretty easy; it's the creativity which is the hard part :)

The Beginning

ZScript is based on the language C. This means, in a nut shell, that your code will be liberally sprinkled with semicolons (;) and curly braces ({ and }). Get to know these characters, and make peace with them. Anyone with a background in BASIC is at a slight disadvantage here, but I'm sure you'll cope.

There are two types of code in ZScript. There's executable code, which are the bits of code that actually do something, and everything else (also known as structural code to pedants), which don't do anything themselves, but support the executable bits.

As always, I believe in a philosophy of teaching with (note: not by, mind you) examples, so lets pick apart a simple script:

Show/Hide < code block hidden >

import "std.zh";
ffc script heartmaker {
void run() {
//need this variable to loop
int i;
//play the sound effect
Game->PlaySound(SFX_SECRET);
//60 ticks = 1 second
for(i=0;i < 60; i++) {
WaitFrame();
}
//create the heart
item heart = Screen->CreateItem(IT_HEART);
//place it just north of Link
heart->X = Link->X;
heart->Y = Link->Y - 16;
//End the script
Quit();
}
}

This script, when run, will play the "Secret" sound effect (i.e. the one that plays when finding a secret, not an actual sound effect that is, itself, secret), wait one second, and then create a heart pickup on the tile directly above wherever Link is. If you don't know C or any similar language, then you're probably ab it confused as to how this works. Let's go over it line-by-line (or so), and see how it works.

import "std.zh";

Every script file you make should start with that line. import is the same as C's #INCLUDE, or PHP's include() function, replacing the line with the entire contents of the named file.

The file name (std.zh) is wrapped in quotes ("), to distinguish it from any other random file or keyword. That is called a string, and the import line is the only time you'll ever use strings in ZScript (for now!)

std.zh is a standard header file included with ZQuest, and specifies a whole bunch of constants (numbers with special names you can refer to them by) and other goodies. It's invaluable when writing your scripts. Everyone should take a look at it at some point...

ffc script heartmaker {

This is the first real line of the script. ffc is the type of script. There are three types of scripts currently: "ffc", which can be attached to Freeform combos (used for custom bosses, cutscenes, you name it. The most common type), "item", which can be attached to items for extra effects when they're used, and "global", which run constantly in the background, amongst other things.

Next, is the keyword script. This always comes next, and tells the compiler that what its looking at is, in fact, a script.

Then there is heartmaker, which is a custom name for the script that I randomly chose, based on what the script does. You can choose any name you want, as long as it follows the following rules:

it must be all one word (no spaces). Wrong example: "my script"
it must start with a letter. Wrong example: "1stscript"
it may have more characters after the first, which may be letters, numbers, or the underscore ( _ ) (but nothing else). Wrong example: "my%!#@script"
it must be globally unique (you can't have two scripts with the same name in your game)

For your own sake, you should usually name your scripts with all lower case characters, as they are case sensitive. That is, "myscript", "MyScript" and "mYsCrIpT" are all different.

Lastly, there is an opening curly brace ( { ). Braces are used to define "blocks". A block of code is a logical unit of code that is grouped together in some way. In this case, the outer-most block is the script as a whole.

A good way to visualize blocks is to think of it as a folder. You wrote the name of the script on the folder, and then stuffed the contents of the script into it. The script is everything between the opening flap ( { ) and the closing flap ( } ).

void run() {