Script declaration (ZScript)

From ZCWiki
Jump to: navigation, search

Syntax

The general syntax for declaring a script is as follows:

script-type script script-name{

  void run(run-arguments){
    // local declarations and
    // statements for the run function.
  }

  // Other function declarations
  // for this script
}

The qualifier script-type must be one of the following values:

  • global: Identifies the script as a global script.
  • ffc: Identifies the script as a freeform combo script, to be "attached" to a freeform combo.
  • item: Identifies the script as an item script, to be attached to an item.

script-name is the user-defined name of the script. This is the name that will show up in the assignment dialogs when you are assigning scripts to slots and items or freeform combos.

Note that every script must contain the run() function declaration, or the script will not compile. Additionally, scripts of type item and ffc require the run() function. For these script types, the run() function is the main "hook" into the script - it is the function Zelda Classic calls when the script is supposed to be executed. Depending on how you use them, global scripts may or may not call the run() function, but it must be present or the script will not compile.

Usage

ffc Scripts

ffc scripts are assigned to freeform combos. A ffc script will be executed when its associated freeform combo is rendered on a screen.

While you might use a ffc script to control only its associated freeform combo, the script has access to every ZScript object, method, and property, so you can do much more with a ffc script than just manipulate freeform combos. For instance, you can monitor Link's position on the screen, spawn/destroy enemies, or even trigger secrets under certain conditions (with a few work-arounds). For this reason, many quest developers create transparent freeform combos and place them on the screen simply so they can perform other activities using the script. The freeform combo itself might never come into play, but it launches the script which could be used to do all kinds of things.

item Scripts

item scripts are assigned to existing or custom items. For each item you can assign two scripts: one will get called when the item is first obtained (such as picking up a sword for the first time), the other will get called every time the item is used (such as attacking with a sword).

global Scripts

global scripts have a few purposes. ZQuest allows you to assign two global scripts to two particular events in the game (one script per event). Without going into great detail here (see Assigning scripts) this means you can setup Zelda Classic to run a script when a quest loads, and when Link dies. When writing scripts for these purposes, you must put the code you want to be executed in the script's run() function.

In a more general sense, you can use global scripts to create re-usable "utility" routines. If you create a global script with several associated functions in it, you can then call these functions from your other scripts, by prefacing the function with the name of the script and a period. See the example below. With this approach, you must still declare the run() function, but you do not need to include anything in it.

// Using a global script to create utility functions.  Include
// these utility functions in your main script file by adding
//    import "utility.z"
// at the top of the main script file (assuming you
// name this file utility.z.)
global script utility{
 
 // We must declare run() so the script compiles.
 // However, it will never get called, so we can
 // just leave it empty.
 void run(){
   // Don't do anything.  Just include an
   // empty statement.
   ;
 }

 // Utility functions start here.  You can
 // call this function, for instance, from
 // another script as follows:
 //  
 //     utility.IncreaseLinksHearts(3);
 //  
 void IncreaseLinksHearts(int AddHeartsToLink){
   // Each of Link's hearts is 16 hitpoints.
   Link->HP = Link->HP + (AddHeartsToLink * 16);
 }

 // Other functions...  
}

See Also