zscript.txt b40 Preliminary

//Docs for 2.54 Beta
//Rev. 0.8.9
//for 2.54 b40
//16th December, 2016

Search for !#! to find areas that require completion.
?REFFFC? What is this?

//===================================================================================
//                 --- ZScript built-in functions and variables ---
//===================================================================================
/*
*   These functions are all INTERNAL to ZQuest. They require no header
*   or other import directives to work, and are all direct representations
*   of ZASM instructions.
*
*   These functions and commands are the BASIC BUILDING BLOCKS of ZScript:
*   While they require no other functions to work, ALL other functions
*   in headers (such as std.zh) RELY, and OPERATE using these functions.
*
*   Thus, it is essential to know what each of these does, how they work,
*   and how to use them.
*
*   For other included functions, that are not internal (i.e. external functions)
*   please read the documentation specific to  each header. These are individual
*   files (e.g. std.txt), however if you wish to view all the pre-packaged ZScript
*   functions, and commands, you may view the EXTENDED DOCUMENTATION, as
*   those documentation files contain all of the 'Essential ZScript' that
*   you will want to use.
*
*   Where possible, the ZASM instruction used by the functions, and the
*   commands detailed herein are listed inline with the entry for the related
*   function / command. Full (public) ZASM documentation is, sadly incomplete.
*
*   Note: Functions and variables other than global functions are properties
*   of **objects**. Objects are divided into NAMESPACEs and CLASSes, and the
*   the syntax for using them is:
*
*   [object name]->[property]
*
*   where "[object name]" is the object's name (e.g. Link, Game, Screen)/
*   and "[property]" is the function.
*
*   Example:
*   void GetCurDMap() is a Game property, and is called as:
*
*   Game->GetCurDMap();
*
*   "Link", "Screen" and "Game" are always available and don't need to be
*   instantiated, while you must initialise other classes, such as ffc, item,
*   and npc.
*
*   ZScript functions are of the types: int, float, bool, and void. Of these,
*   only void does not return a value. (The void type is normally used to run
*   a series of instructions, or to set values). The other types retrun values
*   appropriate to their type.
*
*   Note: In the following, "int" indicates that a parameter is truncated by a
*   function to an integer, or that the return value will always be an integer
*   however, ZScript itself makes no distinction between int and float types.
*/

/************************************************************************************************************/

//////////////////
/// ZASM Flags ///
//////////////////

ZASM uses a series of special flags, to determine how it should follow logical instructions,
including the following:

SCRIPT FLAGS
TRUEFLAG : A condition in the script, is true
MOREFLAG : Must be set manually with ZASM.
FALSEFLAG : Must be set namually with ZASM.
LESSFLAG : Must be set manually with ZASM.

Instructions
SETTRUE : Set the Script Flag TRUEFLAG.
    SETTRUE Sets a true condition for the Assembler, if a COMPARERV and COMPARER validate.
    This is used when making statements in ZScript.
SETFALSE: Set the Script Flag FALSEFLAG: ZScript does not do this.
SETMORE : Set the Script FLag MOREFLAG: ZScript does not do this.
SETLESS : Set the Script Flag LESSFLAG: ZScript does not do this.

These flags are used in evaluation instructions, to determine if an instruction should run.

Examples of these are as follows:

GOTOTRUE: Executes the GOTO instruction only if the Script Flag TRUEFLAG is enabled.
GOTOFALSE: Executes the GOTO instruction only if the Script Flag FALSEFLAG is enabled.
GOTOMORE: Executes the GOTO instruction only if the Script Flag MOREFLAG is enabled.
GOTOLESS: Executes the GOTO instruction only if the Script Flag LESSFLAG is enabled.

In contrast, GOTO/GOTOR ignore all flags, and conditions.

ZScript always compiles down to GOTO, GOTOR, and GOTOTRUE instructions.
The other FLAG-typed GOTO instruction types are valid only in ZASM, and serve no useful purpose.
GOTOLESS, GOTOMORE, and GOTOFALSE are effectively deprecated.

//=======================================================
//--- Instruction Processing Order and General Timing ---
=========================================================

1.     Instructions in Global script Init (if starting a new game)
2.     Instructions in Global Script OnContinue (is resuming a game)
3.     Instructions immediately inside the run() function of a global active script.
4.     Instructions in the global active script's infinite loop prior to Waitdraw,
       if (5) does not exist, or on the first frame of the game.
5.     Instructions from an ffc script positioned after (an illegal)
       Waitdraw() instruction in that script from the previous frame.
         Note: Requires being on at least the second frame of a game session.
6.     Instructions in the global active script prior to Waitdraw().
7.     Instructions in an ffc script, other than (5), excluding draw commands.
8.     Screen Scrolling (2.50.2, or later)
9.     Instructions from item scripts.
10.    Waitdraw() in a global active script.
11.    Engine writing to Link->Dir and Link->Tile.
12.    Instructions in the global active script, called after Waitdraw()
12(b). Screen Scrolling ( 2.50.0, and 2.50.1 )
13.    Drawing from FFCs
14.    Instructions in an OnExit script, if the game is exiting.
15.    Return to (5).


//=================
//--- Pointers ---
//=================

Global array pointers start at 4096 (when traced). These are added in escalating value, but in the reverse-order
of declaration. e.g. The last declared array will be ID 4096.

/************************************************************************************************************/


////////////////////////
/// Operator Symbols ///
////////////////////////

ZScript supports value input as decimal, hexidecimal, and binary.

To input hexidecimal values, preface them with '0x'. Thus, '0x0F' for '16'.
To input binary balues, end them with a lowercase 'b'. Thus, '11b' for '3'.

Name        Sign    ZASM (R)    ZASM (V)    Definition
PLUS        +   ADDR<><>    ADDV<><>    Adds a value a + b, a + 3
MINUS       -   SUBR<><>    SUBV<><>    Subtracts a value a - b, a - 2
INCREMENT   ++                      Increments a value by '1'
DECREMENT   --                      Decreases a value by '1'
MULTIPLY    *   MULTR<><>   MULTV<><>   Multiplies values a * b
DIVIDE      /   DIVR<><>    DIVV<><>    Divides values a / b
MODULUS     %                   Returns the remainder of integer division of 4 % 2
NOT     !   NOT<>               Inverse logic boolean operator.
                            if ( !var1 == 0 ) returns true if var1 is zero,
                            and false if var1 is non-zero
EQUALS      =   SETR<><>    SETV<><>    Sets a value to another value a = 4
EXACTLY EQUALS  ==                      Compares value a == b and returns if they match.
NOT EQUALS  !=                      Compares values a != b and returns if they do not match,
LESSTHAN    <                   Comapres a < b and returns if a is less then b.
MORETHAN    >                   Compares a > b and returns if a is more than b.
LOGICAL OR  ||                      Boolean logic, Or.
LOGICAL AND &&                      Boolean Logic And.

SET ADDRESS ARG     SETA1<><>
            SETA2<><>
GET ADDRESS ARG     GETA1<><>
            GETA2<><>

Note: LOGICAL XOR (^^) is not valid in ZScript, but you may simulate it with custom functions.


/////////////////////////
/// Bitwise Operators ///
/////////////////////////

Reminder: You may reference a binary value using a numeric sequence, ending in 'b':
    0100010b
    ('34' decimal)

Or  ZScript Symbol      ZASM Instructions:
    |           ORV<><>
                ORR<><>

And ZScript Symbol      ZASM Instructions:
    &           ANDR<><>
                ANDV<><>

Not ZScript Symbol      ZASM Instructions:
    ~           BITNOT<>

Left Shift:
    ZScript Symbol      ZASM Instructions
    <<          LSHIFTV<><>
                LSHIFTR<><>

Right Shift:
    ZScript Symbol      ZASM Instructions
    >>          RSHIFTV<><>
                RSHIFTR<><>

Xor     ZScript Symbol      ZASM Instructions:
    ^           XORV<><>
                XORR<><>

Nor ZScript Symbol      ZASM Instructions:
    ~|          NORV<><>
                NORR<><>

XNor    ZScript Symbol      ZASM Instructions:
    ~^          XNORV<><>
                XNORV<><>

Nand    ZScript Symbol      ZASM Instructions:
    ~&          NANDV<><>
                NANDR<><>

/************************************************************************************************************/


//========================
//--- Global Functions ---
//========================

/////////////////////////
/// General Functions ///
/////////////////////////


void Waitdraw();        ZASM Instruction:
                WAITDRAW
/**
* Halts execution of the script until ZC's internal code has been run (movement,
* collision detection, etc.), but before the screen is drawn. This can only
* be used in the active global script.
* Waitdraw() may only be called from the global active script; not from FFC scripts.
* The sequence of ZC actions is as follows:

* FFCs (in numerical sequence, from FFC 01, to FFC 32)
* Enemies
* EWeapons
* Link
* LWeapons
* Hookshot
* Collision Checking
* Store Link->Input / Link->Press
* Waitdraw()
* Drawing
* Rendering of the Screen
* Screen Scrolling
* Drawing from FFCs
*
* Note: Drawing from FFCs technically occurs with other Drawing, but as it is issued after Waitdraw(),
* it is offset (a frame late) and renders after screen scrolling, and after any other drawing in the same
* frame as draw instructions from ffcs are called. To ensure that drawing done by ffcs is in sync with
* other drawing, it is imperative to call it from your global script, using the ffc to trigger global
* conditions that cause global drawing instructions that are called before Waitdraw() in your global
* active script to evaluate true.
*
* Anything placed after Waitdraw() will not present graphical effects until the next frame.
* It is possible { ! CHECK } to read/store Link->Tile, Link->Dir and other variables *after* Waitdraw()
* in one frame, and then use these values to modify other pointer members so that they are drawn correctly
* at the next execution of Waitdraw().
*
*
*/ Example Use:

    Waitdraw();

//! Submit bug report that Link->Dir and Link->Tile are incorrect before Waitdraw.

*//////////////////////////////
* Waitdraw() in ffc scripts ///
* --------------------------///
* Althouth technically illegal, it is possible to call Waitdraw() in an *ffc script*. Doing this has the
* following effects, and/or consequences:
*
* 1. The Compiler will report an error, and print the error to Allegro log:
*   'Warning: Waitdraw() may only be used in global scripts.'
* 2. Any instruction sint he ffc script that are called before the Waitdraw() instruction in the ffc script
*    will run this frame, after Waitdraw() in your global active script.
* 3. Any instructions called *after* Waitdraw() in the ffc script, will run BEFORE BOTH Waitdraw() in your
*    global active script, and BEFORE any other instructions in your global active script's infinite loop.
*
* This behaviour may change in future versions of ZC, and using Waitdraw() in ffc scripts is not advised.

*///////////////////////////////
* Waitdraw() in item scripts ///
* ---------------------------///
* Althouth technically illegal, it is possible to call Waitdraw() in an item sctipt. Doing this has the
* following effects, and/or consequences:
*
* 1. The Compiler will report an error, and print the error to Allegro log:
*   'Warning: Waitdraw() may only be used in global scripts.'
* 2.
*
* This behaviour may change in future versions of ZC, and using Waitdraw() in item scripts is not advised.

/************************************************************************************************************/

void Waitframe();       ZASM Instruction:
                WAITFRAME
/**
* Temporarily halts execution of the current script. This function returns at
* the beginning of the next frame of gameplay.
* Slots 1, 3 and 4 Global scripts and item scripts only execute for one frame,
* so in those scripts Waitframe() is essentially Quit().
* It is safe to call Waitframe in the active global script.
* A Waitframe is required in all infinite loops (e.g. while(true) ) so that ZC may
* pause to break in order to advance to the next frame, then resume the loop from the start.
*
*/ Example Use:

    Waitframe();

*///////////////////////////////
* Waitdraw() in item scripts ///
* ---------------------------///
* Althouth technically legal, it is invalid to call Waitframe() in an item sctipt. Doing this has the
* following effects, and/or consequences:
*
* 1. The script will prematurely exit.
*
* Calling Waitframe() in an item script is effectively identical to calling Quit(), however this behaviour
* may change in future versions of ZC, and using Waitframe() in item scripts is not advised.

/************************************************************************************************************/

void Quit();            ZASM Instruction:
                QUIT
/**
* Terminates execution of the current script. Does not return.
* Caution: If called from a global script, the script itself exits.
*
*/ Example Use:

    Quit();

/************************************************************************************************************/

////////////////////
/// Modify Tiles ///
////////////////////


void CopyTile(int srctile, int desttile);       ZASM Instruction:
                            COPYTILERR d2,d3
                            COPYTILEVV
                            COPYTILERV
                            COPYTILEVR
/**
* Copies the tile specified by scrtile onto the tile space
* specified by desttile. The valid tile value range is 0 to 65519.
* This change is temporary within the quest file
* and not be retained when saving the game.
*
*/ Example Use:

    CopyTile(312,11614);
    Copies tile 312, to tile 11614. Tiles 312, and 11614 will be identical.

/** TIP **
* CopyTile may be used to change Link's tile, by copying a tile onto whatever tile ZC is
* using as a source for Link->Tile
* Thus, although you cannot write directly to Link->Tile, you can write to the actual tile
* that is being used for this Link attribute, and you can do this for any other game graphic
* that you need to change.
*
* When doing this, it is important to read Link->Dir or Link->Flip, *after* Waitdraw() and
* perform the CopyTile() operation immediately thereafter.
*/

/************************************************************************************************************/

void SwapTile(int firsttile, int secondtile);       ZASM Instruction:
                            SWAPTILERR d2,d3
                            SWAPTILEVV
                            SWAPTILEVR
                            SWAPTILERV
/**
* Swaps the two tiles specified by firsttile and secondtile.
* The valid tile value range is 0 to 65519.
* This change is *TEMPORARY* within the quest file
* and will not be retained when saving the game.
*
*/ Example Use:

SwapTile(312,11614);
Changes tile 11614 into tile 312; and tile 312 into tile 11614, transposing their positions.

/************************************************************************************************************/

void OverlayTile(int firsttile, int secondtile);        ZASM Instruction:
                                OVERLAYTILEVV
                                OVERLAYTILEVR
                                OVERLAYTILERV
                                OVERLAYTILERR
/**
* Overlays secondtile onto firsttile, ignoring all pixels of colour 0.
* The valid tile value range is 0 to 65519.
* This change is *TEMPORARY* within the quest file
* and will not be retained when saving the game.
*
*/ Example Use:


/************************************************************************************************************/

void ClearTile(int tileref);            ZASM Instruction:
                        CLEARTILER <d3>
                        CLEARTILEV
/**
* Erases the tile specified by tileref.
* This change is temporary within the quest file
* and will not be retained when saving the game.
* Tiles are not / are  (!check!) shifted upward to adjust for the cleared tile.
*
*/ Example Use:

    ClearTile(21362);
    Clears tile 21362 by ( blanking it to colour 0 ) | ( removing it and shifting all tiles
    thereafter upward ).

/************************************************************************************************************/

//Overlay Tile

//! Is there a ZScript equivalent of this?!
//! This instruction seems to be ***ZASM-specific***.
//! Game->overlayTile() and Screen->OverlayTile() both return an error (no such pointer).
//! Add this to the bytecode in a future build.
//! As far as I can tell, this should work from ZASM, but it was never added to the ZScript side. (11/July/2016: ZRPG)

void OverlayTile() ?

    OVERLAYTILEVV
    OVERLAYTILEVR
    OVERLAYTILERV
    OVERLAYTILERR

/************************************************************************************************************/

///////////////
/// Tracing ///
///////////////


void Trace(float val);      ZASM Instruction:
                TRACER d3
                TRACEV
/**
* Prints a line containing a string representation of val to allegro.log.
* Useful for debugging scripts. You may trace int, and float types.
* For b oolean values, see TraceB() below.
* Values printed to allegro.log no not incorporate any spacing, or carriage
* returns. You must manually add these into your commands.
* Int values are not truncated when printed, and will always have four leading
* zeros after the decimal point.
* To add new lines (carriange returns), see TraceNL() below.
*
*/ Example Use:

    int val = 4;
    Trace(val);
    Prints 4.000 to allegro.log

/************************************************************************************************************/

void TraceB(bool state);    ZASM Instruction:
                TRACE2R d3
                TRACE2V
/**
* Prints a boolean state to allegro.log. Works as trace() above, but prints 'true'
* or 'false' to allegro.log
*
*/ Example Use:

    bool test = true;
    TraceB(test);
    Prints 'true' to allegro.log.

/************************************************************************************************************/

void TraceToBase(   int val, int base,  ZASM Instruction:
            int mindigits   );  TRACE3
/**
* Prints a line in allegro.log representing 'val' in numerical base 'base',
* where 2 <= base <= 36, with minimum digits 'mindigits'.
* (Base must be at least base-2, and at most, base-36)
* Can be useful for checking hex values or flags ORed together, or just to trace
* an integer value, as Trace() always traces to four decimal places.
* mindigits specifies the minimum number of integer digits to print.
* Unlike Trace(), Decimal values are not printed. TraceToBase *does not* handle floats.
* If you specify a floating point value as arg 'val', it will be Floored before conversion.
*
*/ Example Use:

    TraceToBase(20,8,1);
    Converts (decimal) d20 to base-8 (o24 in base-8) and prints value '024' to allegro.log

    TraceToBase(50,16,1);
    Converts (decimal) d50 to base-16 (0x32 hexadecimal) and prints value '0x32' to allegro.log.

/************************************************************************************************************/

void ClearTrace();      ZASM Instruction:
                TRACE4
/**
* Clears allegro.log of all current traces and messages from Zelda Classic/ZQuest.
* Works on a per-quest, per-session basis. Values recorded from previous sessions are not erased.
*
*/ Example Use

    ClearTrace();

/************************************************************************************************************/

void TraceNL();     ZASM Instruction:
            TRACE5
/**
* Traces a newline to allegro.log
* This inserts a carriage return (as if pressing return/enter) into allegro.log
* and is useful for providing formatting to debugging.
*
*/ Example Use:

    TraceNL();
    Prints a carriage return to allegro.log.

/************************************************************************************************************/

void TraceS(int s[]);       ZASM Instruction:
                TRACE6 d3
/**
* Works as Trace() above, but prints a full string to allegro.log, using the array pointer
* (name) as its argument.
* Maximum 512 characters. Functions from string.zh can be used to split larger strings.
*
*/ Example Use:

    int testString[]="This is a string.";
    TraceS(testString);
    Prints 'This is a string.' to allegro.log.

/************************************************************************************************************/

///////////////////////
/// Array Functions ///
///////////////////////


int SizeOfArray(int array[]);       ZASM Instruction:
                    ARRAYSIZE d2
/**
* Returns the index size of the array pointed by 'array'.
* Works only on int, and float type arrays. Boolean arrays are not supported.
* Useful in for loops.
*
*/ Example Use:

    int isAnArray[216];
    int x;
    x = SizeOfArray(isAnArray);
    The value of x becomes 216.

/************************************************************************************************************/

//////////////////////////////
/// Mathematical Functions ///
//////////////////////////////

int Rand(int n);        ZASM Instruction:
                RNDR<><> d2,d3
                RNDV<><>

/**
* Computes and returns a random integer from 0 to n-1,
* or a negative value between n+1 and 0 if 'n' is negative.
*
* Note: The paramater 'n' is an integer, and any floating point (ZScript float)
*       value passed to it will be truncated (floored) to the nearest integer.
*       Rand(3.75) is identical to Rand(3).
*/ Example Use:

    Rand(40);
    Produces a random number between 0 and 39.
    Rand(-20);
    produces a random number between -19 and 0.


/************************************************************************************************************/

float Sin(float deg);       ZASM Instruction:
                SINR<><> d2,d3
                SINV<><>

/**
* Returns the trigonometric sine of the parameter, which is interpreted
* as a degree value.
*
*/ Example Use:

    float x = Sin(32);
    x = 0.5299

/************************************************************************************************************/

float Cos(float deg);       ZASM Instruction:
                COSR<><> d2,d3
                COSV<><>

/**
* Returns the trigonometric cosine of the parameter, which is
* interpreted as a degree value.
*
*/ Example Usage:

    float x = Cos(40);
    x = 0.7660

/************************************************************************************************************/

float Tan(float deg);       ZASM Instruction:
                TANR<><> d2,d3
                TANV<><>

/**
* Returns the trigonometric tangent of the parameter, which is
* interpreted as a degree value. The return value is undefined if
* deg is of the form 90 + 180n for an integral value of n.
*
*/ Example Use:

    float x = Tan(100);
    x = -5.6712

/************************************************************************************************************/

//!Sources: OMultImmediate, OArcSinRegister
//Is there a direct ZASM instruction equivalent, or does this function run as a routine?

float RadianSin(float rad);
/**
* Returns the trigonometric sine of the parameter, which is interpreted
* as a radian value.
*
*/ Example Use:

/************************************************************************************************************/

//!Sources: OMultImmediate, OCosRegister
//Is there a direct ZASM instruction equivalent, or does this function run as a routine?

float RadianCos(float rad);
/**
* Returns the trigonometric cosine of the parameter, which is
* interpreted as a radian value.
*
*/ Example Use:

/************************************************************************************************************/

//!Sources: OMultImmediate, OTanRegister
//Is there a direct ZASM instruction equivalent, or does this function run as a routine?

float RadianTan(float rad);
/**
* Returns the trigonometric tangent of the parameter, which is
* interpreted as a radian value. The return value is undefined for
* values of rad near (pi/2) + n*pi, for n an integer.
*
*/ Example Use:

/************************************************************************************************************/

float ArcTan(int x, int y);     ZASM Instruction:
                    ARCTANR<>
                    (Does ARCTANV exist?)
/**
* Returns the trigonometric arctangent of the coordinates, which is
* interpreted as a radian value.
*
*/ Example Use:

/************************************************************************************************************/

float ArcSin(float x);          ZASM Instruction:
                    ARCSINR<><>
                    ARCSINV<><> (Can't find this in the source code)
                            ffasm.cpp line 217
/**
* Returns the trigonometric arcsine of x, which is
* interpreted as a radian value.
*
*/ Example Use:

/************************************************************************************************************/

float ArcCos(float x);      ZASM Instruction:
                ARCCOSR<><>
                ARCCOSV<><>

/**
* Returns the trigonometric arccosine of x, which is
* interpreted as a radian value.
*
*/ Example Use:

/************************************************************************************************************/

float Max(float a, float b);    ZASM Instruction:
                MAXR<><>
                MAXV<><>
/**
* Returns the greater of a and b.
*
*/ Example Use:

/************************************************************************************************************/

float Min(float a, float b);    ZASM Instriction:
                MINR<><>
                MINV<><>
/**
* Returns the lesser of a and b.
*
*/ Example Use:

/************************************************************************************************************/

int Pow(int base, int exp); ZASM Instruction:
                POWERR<><>
                POWERV<><>
/**
* Returns base^exp. The return value is undefined for base=exp=0. Note
* also negative values of exp may not be useful, as the return value is
* truncated to the nearest integer.
*
*/ Example Use:

/************************************************************************************************************/

int InvPow(int base, int exp);      ZASM Instruction:
                    IPOWERR<><>
                    IPOWERV<><>
/**
* Returns base^(1/exp). The return value is undefined for exp=0, or
* if exp is even and base is negative. Note also that negative values
* of exp may not be useful, as the return value is truncated to the
* nearest integer.
*
*/ Example Use:

/************************************************************************************************************/

float Log10(float val);         ZASM Instruction:
                    LOG10<>
/**
* Returns the log of val to the base 10. Any value <= 0 will return 0.
*
*/ Example Use:

/************************************************************************************************************/

float Ln(float val);            ZASM Instruction:
                    LOGE<>

/**
* Returns the natural logarithm of val (to the base e). Any value <= 0 will return 0.
*
*/ Example Use:

/************************************************************************************************************/

int Factorial(int val);         ZASM Instruction:
                    FACTORIAL<>
/**
* Returns val!. val < 0 returns 0.
*
*/ Example Use:

/************************************************************************************************************/

float Abs(float val);           ZASM Instruction:
                    ABS<>
/**
* Return the absolute value of the parameter, if possible. If the
* absolute value would overflow the parameter, the return value is
* undefined.
*
*/ Example Use:

/************************************************************************************************************/

float Sqrt(float val);          ZASM Instruction:
                    SQROOTV<><>
                    SQROOTR<><>
/**
* Computes the square root of the parameter. The return value is
* undefined for val < 0.
* NOTE: Passing negative values to Sqrt() will return an error. See SafeSqrt() in std.zh
*/ Example Use:

    int x = Sqrt(16);
    x = 4

/************************************************************************************************************/
/************************************************************************************************************/



//====================================
//--- Game Functions and Variables ---
//====================================

                                        namespace Game



    int GetCurScreen();     ZASM Instruction:
                    CURSCR
    /**
    * Retrieves the number of the current screen within the current map.
    */ Example Use: !#!

/************************************************************************************************************/

    int GetCurDMapScreen();     ZASM Instruction:
                    CURDSCR
    /**
    * Retrieves the number of the current screen within the current DMap.
    */ Example Use: !#!

/************************************************************************************************************/

    int GetCurLevel();      ZASM Instruction:
                    CURLEVEL
    /**
    * Retrieves the number of the dungeon level of the current DMap. Multiple
    * DMaps can have the same dungeon level - this signifies that they share
    * a map, compass, level keys and such.
    */ Example Use: !#!

/************************************************************************************************************/

    int GetCurMap();        ZASM Instruction:
                    CURMAAP
    /**
    * Retrieves the number of the current map.
    */ Example Use: !#!

/************************************************************************************************************/

    int GetCurDMap();       ZASM Instruction:
                    CURDMAP
    /**
    * Returns the number of the current DMap.
    */ Example Use: !#!

/************************************************************************************************************/

    int DMapFlags[];        ZASM Instruction:
                    DMAPFLAGSD
    /**
    * An array of 512 integers, containing the DMap's flags ORed (|) together.
    * Use the 'DMF_' constants, or the 'DMapFlag()' functions from std.zh if you are not comfortable with binary.
    */ Example Use: !#!

/************************************************************************************************************/

    int DMapLevel[];        ZASM Instruction:
                    DMAPLEVELD
    /**
    * An array of 512 integers containing each DMap's level
    */ Example Use: !#!

/************************************************************************************************************/

    int DMapCompass[];      ZASM Instruction:
                    DMAPCOMPASSD
    /**
    * An array of 512 integers containing each DMap's compass screen
    */ Example Use: !#!

/************************************************************************************************************/

    int DMapContinue[];     ZASM Instruction:
                    DMAPCONTINUED
    /**
    * An array of 512 integers containing each DMap's continue screen
    */ Example Use: !#!

/************************************************************************************************************/

    int DMapMIDI[];         ZASM Instruction:
                    DMAPMIDID
    /**
    * An array of 512 integers containing each DMap's MIDI.
    * Positive numbers are for custom MIDIs, and negative values are used for
    * the built-in game MIDIs. Because of the way DMap MIDIs are handled
    * internally, however, built-in MIDIs besides the overworld, dungeon, and
    * level 9 songs won't match up with Game->PlayMIDI() and Game->GetMIDI().
    */ Example Use: !#!

/************************************************************************************************************/

    void GetDMapName(int DMap, int buffer[]);

                    ZASM Instruction:
                    GETDMAPNAME
    /**
    * Loads DMap with ID 'DMap's name into 'buffer'.
    * See std_constsnts.zh for appropriate buffer size.
    */ Example Use: !#!

/************************************************************************************************************/

    void GetDMapTitle(int DMap, int buffer[]);

                    ZASM Instruction:
                    GETDMAPTITLE
    /**
    * Loads DMap with ID 'DMap's title into 'buffer'.
    * See std_constants.zh for appropriate buffer size.
    */ Example Use: !#!

/************************************************************************************************************/

    void GetDMapIntro(int DMap, int buffer[]);

                    ZASM Instruction:
                    GETDMAPINTRO
    /**
    * Loads DMap with ID 'DMap's intro string into 'buffer'.
    * See std_constants.zh for appropriate buffer size.
    */ Example Use: !#!

/************************************************************************************************************/

    int DMapOffset[];       ZASM Instruction:
                    DMAPOFFSET
    /**
    * An array of 512 integers containing the X offset of each DMap.
    * Game->DMapOffset is read-only; while setting it is not syntactically
    * incorrect, it does nothing.
    */ Example Use: !#!

/************************************************************************************************************/

    int DMapMap[];          ZASM Instruction:
                    DMAPMAP

    /**
    * An array of 512 integers containing the map used by each DMap.
    * Game->DMapMap is read-only; while setting it is not syntactically
    * incorrect, it does nothing.
    */ Example Use: !#!

/************************************************************************************************************/

    int NumDeaths;          ZASM Instruction:
                    GAMEDEATHS
    /**
    * Returns or sets the number of times Link has perished during this quest.
    */ Example Use: !#!

/************************************************************************************************************/

    int Cheat;          ZASM Instruction:
                    GAMECHEAT
    /**
    * Returns, or sets the current cheat level of the quest player.
    * Valid values are 0, 1, 2, 3, and 4.
    */ Example Use: !#!

/************************************************************************************************************/

    bool CappedFPS;         ZASM Instruction:
                    GAMETHROTTLE
    /**
    * Returns if the user enabled an uncapped mode either with F1 or TILDE.
    * Returns 'true' is the game is capped to 60fps, or false otherwise.
    * At present, you may get (read), but NOT set (write to) this value.
    */ Example Use: !#!

/************************************************************************************************************/

    int Time            ZASM Instruction:
                    GAMETIME
    /**
    * Returns the time elapsed in this quest, in 60ths of a second. (i.e. in frames).
    * The return value is undefined if TimeValid is false (see below).
    */ Example Use: !#!

/************************************************************************************************************/

    bool TimeValid;         ZASM Instruction:
                    GAMETIMEVALID
    /**
    * True if the elapsed quest time can be determined for the current quest.
    */ Example Use: !#!

/************************************************************************************************************/

    bool HasPlayed;         ZASM Instruction:
                    GAMEHASPLAYED
    /**
    * This value is true if the current quest session was loaded from a saved
    * game, false if the quest was started fresh.
    */ Example Use: !#!

/************************************************************************************************************/

    bool Standalone;        ZASM Instruction:
                    GAMESTANDALONE
    /**
    * This value is true if the game is running in standalone mode, false if not.
    * Game->Standalone is read-only; while setting it is not syntactically
    * incorrect, it does nothing.
    *
    * Standalone mode is set by command line params when launching ZC.
    */ Example Use: !#!

/************************************************************************************************************/

    int GuyCount[];         ZASM Instruction:
                    GAMEGUYCOUNT
    /**
    * The number of NPCs (enemies and guys) on screen i of this map, where
    * i is the index used to access this array. This array is exclusively used
    * to determine which enemies had previously been killed, and thus won't
    * return, when you re-enter a screen.
    * Note: This is only a count of the enemies that remain on a screen; not their IDs.
    */ Example Use: !#!

/************************************************************************************************************/

    int ContinueDMap;       ZASM Instruction:
                    GAMECONTDMAP
    /**
    * Returns or sets the DMap where Link will be respawned after quitting and reloading the game.
    */ Example Use: !#!

/************************************************************************************************************/

    int ContinueScreen;     ZASM Instruction:
                    GAMECONTSCR
    /**
    * Returns or sets the map screen where Link will be respawned after quitting and reloading the game.
    */ Example Use: !#!

/************************************************************************************************************/

    int LastEntranceDMap;       ZASM Instruction:
                    GAMEENTRDMAP
    /**
    * Returns or sets the DMap where Link will be respawned after dying and continuing.
    */ Example Use: !#!

/************************************************************************************************************/

    int LastEntranceScreen;     ZASM Instruction:
                    GAMEENTRSCR
    /**
    * Returns or sets the map screen where Link will be respawned after dying and continuing.
    */ Example Use: !#!

/************************************************************************************************************/

    int Counter[];          ZASM Instruction:
                    GAMECOUNTERD
    /**
    * Returns of sets the current value of the game counters.
    * Use the CR_ constants in std.zh to index into this array.
    */ Example Use: !#!

/************************************************************************************************************/

    int MCounter[];         ZASM Instruction:
                    GAMEMCOUNTERD
    /**
    * Returns or sets the current maximum value of the game counters.
    * Use the CR_ constants in std.zh to index into this array.
    */ Example Use: !#!

/************************************************************************************************************/

    int DCounter[];         ZASM Instruction:
                    GAMEDCOUNTERD
    /**
    * Returns of sets the current value of the game drain counters.
    * Use the CR_ constants in std.zh to index into this array.
    * Note that if the player hasn't acquired the '1/2 Magic Upgrade' yet,
    * then setting the CR_MAGIC drain counter to a negative value will
    * drain the magic counter by 2 per frame rather than 1.
    */ Example Use: !#!

/************************************************************************************************************/

    int Generic[];          ZASM Instruction:
                    GAMEGENERICD
    /**
    * An array of miscellaneous game values, such as number of heart
    * containers and magic drain rate.
    * Use the GEN_ constants in std.zh to index into this array.
    */ Example Use: !#!

/************************************************************************************************************/

    int LItems          ZASM Instruction:
                    GAMELITEMSD
    /**
    * The exploration items (map, compass, boss key etc.) of dungeon level i
    * currently under the possession of the player, where i is
    * the index used to access this array. Each element of this
    * array consists of flags OR'd (|) together; use the LI_ constants in
    * std.zh to set or compare these values.
    */ Example Use: !#!

/************************************************************************************************************/

    int LKeys[];            ZASM Instruction:
                    GAMELKEYSD
    /**
    * The number of level keys of level i currently under the possession of
    * the player, where i is the index used to access this array.
    */ Example Use: !#!

/************************************************************************************************************/

    int GetScreenFlags(int map, int screen, int flagset);

                    ZASM Instruction:
                    GETSCREENFLAGS
    /**
    * Returns the screen flags from screen 'screen' on map 'map',
    * interpreted in the same way as Screen->Flags
    */ Example Use: !#!


    Game->LKeys[3]+=4; //Gives the player four keys to Level 3.


/************************************************************************************************************/

    int GetScreenEFlags(int map, int screen, int flagset);

                    ZASM Instruction:
                    GETSCREENEFLAGS

    /**
    * Returns the enemy flags from screen 'screen' on map 'map',
    * interpreted in the same way as Screen->EFlags
    */ Example Use: !#!

/************************************************************************************************************/

    bool GetScreenState(int map, int screen, int flag);

                    ZASM Instruction:
                    SCREENSTATEDD
    /**
    * As with State, but retrieves the miscellaneous flags of any screen,
    * not just the current one. This function is undefined if map is less
    * than 1 or greater than the maximum map number of your quest, or if
    * screen is greater than 127.
    * Note: Screen numbers in ZQuest are usually displayed in hexadecimal.
    * Use the ST_ constants in std.zh for the flag parameter.
    */ Example Use: !#!

/************************************************************************************************************/

    void SetScreenState(int map, int screen, int flag, bool value);

                    ZASM Instruction:
                    SCREENSTATEDD

    /**
    * As with State, but sets the miscellaneous flags of any screen, not
    * just the current one. This function is undefined if map is less than
    * 1 or greater than the maximum map number of your quest, or if
    * screen is greater than 127.
    * Note: Screen numbers in ZQuest are usually displayed in hexadecimal.
    * Use the ST_ constants in std.zh for the flag parameter.
    */ Example Use: !#!

/************************************************************************************************************/

    float GetScreenD(int screen, int reg);

                    ZASM Instruction:
                    SDDD
    /**
    * Retrieves the value of D[reg] on the given screen of the current
    * DMap.
    */ Example Use: !#!

/************************************************************************************************************/

    void SetScreenD(int screen, int reg, float value);

                    ZASM Instruction:
                    SDDD
    /**
    * Sets the value of D[reg] on the given screen of the current DMap.
    */ Example Use: !#!

/************************************************************************************************************/

    float GetDMapScreenD(int dmap, int screen, int reg);

                    ZASM Instruction:
                    SDDDD
    /**
    * Retrieves the value of D[reg] on the given screen of the given
    * DMap.
    */ Example Use: !#!

/************************************************************************************************************/

    void SetDMapScreenD(int dmap, int screen, int reg, float value

                    ZASM Instruction:
                    SDDDD
    /**
    * Sets the value of D[reg] on the given screen of the given DMap.
    */ Example Use: !#!

    itemdata LoadItemData(int item);
    LOADITEMDATAR
    LOADITEMDATAV
    /**
    * Retrieves the itemdata pointer corresponding to the given item.
    * Use the item pointer ID variable or I_ constants in std.zh as values.
    */  Example Use: !#!
        Game->LoadItemData[I_BRANG1]


/************************************************************************************************************/
    //! This compiles, but it is incomplete and returns 0.
    float GetDMapScreenDoor(int dmap, int screen, int door);

                    ZASM Instruction:
                    n/a
    /**
    * Retrieves the value of Screen->Door[door] on the given screen of the given
    * DMap.
    */ Example Use: !#!

/************************************************************************************************************/
    //! This compiles, but it is incomplete and returns 0.
    void SetDMapScreenDoor(int dmap, int screen, int door, float value

                    ZASM Instruction:
                    SDDDD
    /**
    * Sets the value of Screen->Door[door] on the given screen of the given DMap.
    */ Example Use: !#!


/************************************************************************************************************/
    //! This compiles, but it is incomplete and returns 0.
    bool GetDMapScreenState(int dmap, int screen, int index);

                    ZASM Instruction:
                    n/a
    /**
    * Retrieves the value of Screen->State[index] on the given screen of the given
    * DMap.
    */ Example Use: !#!

/************************************************************************************************************/
    //! This compiles, but it is incomplete and returns 0.
    void SetDMapScreenState(int dmap, int screen, int index, bool value

                    ZASM Instruction:
                    SDDDD
    /**
    * Sets the value of Screen->State[index] on the given screen of the given DMap.
    */ Example Use: !#!


/************************************************************************************************************/

    void PlaySound(int soundid);    ZASM Instruction:
                    PLAYSOUNDR
                    PLAYSOUNDV
    /**
    * Plays one of the quest's sound effects. Use the SFX_ constants in
    * std.zh as values of soundid.
    */ Example Use: !#!

/************************************************************************************************************/

    void PlayMIDI(int MIDIid);  ZASM Instruction:
                    PLAYMIDIR
                    PLAYMIDIV
    /**
    * Changes the current screen MIDI to MIDIid.
    * Will revert to the DMap (or screen) MIDI upon leaving the screen.
    */ Example Use: !#!

/************************************************************************************************************/

    int GetMIDI();          ZASM Instruction:
                    GETMIDI
    /**
    * Returns the current screen MIDI that is playing.
    * Positive numbers are for custom MIDIs, and negative values are used
    * for the built-in game MIDIs.
    */ Example Use: !#!

/************************************************************************************************************/

    bool PlayEnhancedMusic(int filename[], int track);

                    ZASM Instruction:
                    PLAYENHMUSIC
    /**
    * Play the specified enhanced music if it's available. If the music
    * cannot be played, the current music will continue. The music will
    * revert to normal upon leaving the screen.
    * Returns true if the music file was loaded successfully.
    * The filename cannot be more than 255 characters. If the music format
    * does not support multiple tracks, the track argument will be ignored.
    */ Example Use:

        int music[]="myfile.mp3"; // Make a string with the filename of the music to play.
        if ( !Game->PlayEnhancedMusic(music, 1) ) Game->PlayMIDI(midi_id);

        // Plays the enhanced music file 'myfle.mp3', track 1.
        // If the file is mssing, the game will instead play
        // the midi specified as midi_id.

/************************************************************************************************************/

    void GetDMapMusicFilename(int dmap, int buf[]);

                    ZASM Instruction:
                    GETMUSICFILE
    /**
    * Load the filename of the given DMap's enhanced music into buf.
    * buf should be at least 256 elements in size.
    */ Example Use: !#!

/************************************************************************************************************/

    int GetDMapMusicTrack(int dmap);

                    ZASM Instruction:
                    GETMUSICTRACK
    /**
    * Returns the given DMap's enhanced music track. This is valid but
    * meaningless if the music format doesn't support multiple tracks.
    */ Example Use: !#!

/************************************************************************************************************/

    void SetDMapEnhancedMusic(int dmap, int filename[], int track);

                    ZASM Instruction:
                    SETDMAPENHMUSIC
    /**
    * Sets the specified DMap's enhanced music to the given filename and
    * track number. If the music format does not support multiple tracks,
    * the track argument will be ignored. The filename must not be more
    * than 255 characters.
    */ Example Use: !#!

/************************************************************************************************************/

    int GetComboData(int map, int screen, int position);

                    ZASM Instruction:
                    COMBODDM
    /**
    * Grabs a particular combo reference from anywhere in the game
    * world, based on map (NOT DMap), screen number, and position.
    * Don't forget that the screen index should be in hexadecimal,
    * and that maps are counted from 1 upwards.
    * Position is considered an index, treated the same way as in
    * Screen->ComboD[], with a legal range of 0 to 175.
    */ Example Use: !#!

/************************************************************************************************************/

    void SetComboData(int map, int screen, int position, int value);

                    ZASM Instruction:
                    COMBODDM
    /**
    * Sets a particular combo reference anywhere in the game world,
    * based on map (NOT DMap), screen number, and position.
    * Don't forget that the screen index should be in hexadecimal,
    * and that maps are counted from 1 upwards.
    * Position is considered an index, treated the same way as in
    * Screen->ComboD[], with a legal range of 0 to 175.
    */ Example Use: !#!

/************************************************************************************************************/

    int GetComboCSet(int map, int screen, int position);

                    ZASM Instruction:
                    COMBOCDM
    /**
    * Grabs a particular combo's CSet from anywhere in the game
    * world, based on map (NOT DMap), screen number, and position.
    * Position is considered an index, treated the same way as in
    * Screen->ComboC[], with a legal range of 0 to 175.
    */ Example Use: !#!

/************************************************************************************************************/

    void SetComboCSet(int map, int screen, int position, int value);

                    ZASM Instruction:
                    COMBOCDM
    /**
    * Sets a particular combo's CSet anywhere in the game world,
    * based on map (NOT DMap), screen number, and position. Position
    * is considered an index, treated the same way as in Screen->ComboC[]
    * with a legal range of 0 to 175.
    */ Example Use: !#!

/************************************************************************************************************/

    int GetComboFlag(int map, int screen, int position);

                    ZASM Instruction:
                    COMBOFDM
    /**
    * Grabs a particular combo's placed flag from anywhere in the game
    * world, based on map (NOT DMap), screen number, and position.
    * Position is considered an index, treated the same way as in
    * Screen->ComboF[], with a legal range of 0 to 175.
    */ Example Use: !#!

/************************************************************************************************************/

    void SetComboFlag(int map, int screen, int position, int value);

                    ZASM Instruction:
                    COMBOFDM
    /**
    * Sets a particular combo's placed flag anywhere in the game world,
    * based on map (NOT DMap), screen number, and position. Position
    * is considered an index, treated the same way as in Screen->ComboF[]
    * with a legal range of 0 to 175.
    */ Example Use: !#!

/************************************************************************************************************/

    int GetComboType(int map, int screen, int position);

                    ZASM Instruction:
                    COMBOTDM
    /**
    * Grabs a particular combo's type from anywhere in the game
    * world, based on map (NOT DMap), screen number, and position.
    * Position is considered an index, treated the same way as in
    * Screen->ComboT[]. Note that you are grabbing an actual combo
    * attribute as referenced by the combo on screen you're
    * referring to.
    */ Example Use: !#!

/************************************************************************************************************/

    void SetComboType(int map, int screen, int position, int value);

                    ZASM Instruction:
                    COMBOTDM
    /**
    * Sets a particular combo's type anywhere in the game world,
    * based on map (NOT DMap), screen number, and position. Position
    * is considered an index, treated the same way as in Screen->ComboT[].
    * Note that you are grabbing an actual combo attribute as referenced
    * by the combo on screen you're referring to, which means that
    * setting this attribute will affect ALL references to this combo
    * throughout the quest.
    */ Example Use: !#!

/************************************************************************************************************/

    int GetComboInherentFlag(int map, int screen, int position);

                    ZASM Instruction:
                    COMBOIDM
    /**
    * Grabs a particular combo's inherent flag from anywhere in the game
    * world, based on map (NOT DMap), screen number, and position.
    * Position is considered an index, treated the same way as in
    * Screen->ComboI[]. Note that you are grabbing an actual combo
    * attribute as referenced by the combo on screen you're
    * referring to.
    */ Example Use: !#!

/************************************************************************************************************/

    void SetComboInherentFlag(int map, int screen, int position, int value);

                    ZASM Instruction:
                    COMBOIDM
    /**
    * Sets a particular combo's inherent flag anywhere in the game world,
    * based on map (NOT DMap), screen number, and position. Position
    * is considered an index, treated the same way as in Screen->ComboI[].
    * Note that you are grabbing an actual combo attribute as referenced
    * by the combo on screen you're referring to, which means that
    * setting this attribute will affect ALL references to this combo
    * throughout the quest.
    */ Example Use: !#!

/************************************************************************************************************/

    int GetComboSolid(int map, int screen, int position);

                    ZASM Instruction:
                    COMBOSDM
    /**
    * Grabs a particular combo's solidity flag from anywhere in the game
    * world, based on map (NOT DMap), screen number, and position.
    * Position is considered an index, treated the same way as in
    * Screen->ComboS[]. Note that you are grabbing an actual combo
    * attribute as referenced by the combo on screen you're
    * referring to.
    */ Example Use: !#!

/************************************************************************************************************/

    void SetComboSolid(int map, int screen, int position, int value);

                    ZASM Instruction:
                    COMBOSDM
    /**
    * Sets a particular combo's solidity anywhere in the game world,
    * based on map (NOT DMap), screen number, and position. Position
    * is considered an index, treated the same way as in Screen->ComboS[].
    * Note that you are grabbing an actual combo attribute as referenced
    * by the combo on screen you're referring to, which means that
    * setting this attribute will affect ALL references to this combo
    * throughout the quest.
    */ Example Use: !#!

/************************************************************************************************************/

    int ComboTile(int combo);   ZASM Instruction:
                    COMBOTILE
    /**
    * Returns the tile used by combo 'combo'
    */ Example Use: !#!

/************************************************************************************************************/

    void GetSaveName(int buffer[]);

                    ZASM Instruction:
                    GETSAVENAME
    /**
    * Loads the current save file's name into 'buffer'
    * Buffer should be at least 9 elements long
    */ Example Use: !#!

/************************************************************************************************************/

    void SetSaveName(int name[]);

                    ZASM Instruction:
                    SETSAVENAME
    /**
    * Sets the current file's save name to 'name'
    * Buffer should be no more than 9 elements
    */ Example Use: !#!

/************************************************************************************************************/

    void End();         ZASM Instruction:
                    GAMEEND
    /**
    * IMMEDIATELY ends the current game and returns to the file select screen
    */ Example Use: !#!

/************************************************************************************************************/

    void Save();            ZASM Instruction:
                    GAMESAVE
    /**
    * Saves the current game
    */ Example Use: !#!

/************************************************************************************************************/

    bool ShowSaveScreen();      ZASM Instruction:
                    SAVESCREEN
    /**
    * Displays the save screen. Returns true if the user chose to save, false otherwise.
    */ Example Use: !#!

/************************************************************************************************************/

    void ShowSaveQuitScreen();  ZASM Instruction:
                    SAVEQUITSCREEN
    /**
    * Displays the save and quit screen.
    */ Example Use: !#!

/************************************************************************************************************/

    void GetMessage(int string, int buffer[]);

                    ZASM Instruction:
                    GETMESSAGE
    /**
    * Loads 'string' into 'buffer'. Use the function from std.zh
    * or use string.zh to remove trailing ' ' characters whilst loading.
    */ Example Use: !#!

/************************************************************************************************************/

    int GetFFCScript(int name[]);   ZASM Instruction:
                    GETFFCSCRIPT
    /**
    * Returns the number of the script with the given name or -1 if there is
    * no such script. The script name should be passed as a string.
    * (!) This was added around 2.50.0 RC4. Earlier beta versions will not be able to perform this function.
    */ Example Use: !#!

/************************************************************************************************************/

    bool ClickToFreezeEnabled;  ZASM Instruction:
                    GAMECLICKFREEZE
    /**
    * If this is false, the "Click to Freeze" setting will not function, ensuring
    * that the script can use the mouse freely. This overrides the setting rather
    * than changing it, so remembering and restoring the initial value is unnecessary.
    */ Example Use: !#!

/************************************************************************************************************/
/************************************************************************************************************/

//======================================
//--- Screen Functions and Variables ---
//======================================

                                        namespace Screen

float D[];              ZASM Instruction:
                    SD
                    SDD


/**
* Each screen has 8 general purpose registers for use by script
* programmers. These values are recorded in the save file when the
* player saves their game. Do with these as you will.
* Note that these registers are tied to screen/DMap combinations.
* Encountering the same screen in a different DMap will result in a
* different D[] array.
*
* Values in Screen->D are preserved through game saving.
*
*/ Example Use: !#!

/************************************************************************************************************/

int Flags[];                ZASM Instruction:
                    SCREENFLAGSD
                    SCREENFLAGS

/**
* An array of ten integers containing the states of the flags in the
* 10 categories on the Screen Data tabs 1 and 2. Each flag is ORed into the
* Flags[x] value, starting with the top flag as the smallest bit.
* Use the SF_ constants as the array acces for this value, and the
* GetScreenFlags function if you are not comfortable with binary.
* This is read-only; while setting it is not syntactically incorrect, it does nothing.
*
*/ Example Use: !#!

/************************************************************************************************************/

int EFlags[];               ZASM Instruction:
                    SCREENEFLAGSD
                    SCREENEFLAGS

/**
* An array of 3 integers containing the states of the flags in the
* E.Flags tab of the Screen Data dialog. Each flag is ORed into the
* EFlags[x] value, starting with the top flag as the smallest bit.
* Use the SEF_ constants as the array acces for this value, and the
* GetScreenEFlags function if you are not comfortable with binary.
* This is read-only; while setting it is not syntactically incorrect, it does nothing.
*
*/ Example Use: !#!

/************************************************************************************************************/

int ComboD[];               ZASM Instruction:
                    CD###       COMBOD
                    COMBODD     COMBODDM
                    COMBODDM    COMBOSD

/**
* The combo ID of the ith combo on the screen, where i is the index
* used to access this array. Combos are counted left to right, top to
* bottom.
* Screen dimensions are 16 combos wide, by 11 combos high.
*
*/ Example Use: !#!

/************************************************************************************************************/

int ComboC[];               ZASM Instruction:
                    CC###       COMBOC
                    COMBOCD     COMBOCDM

/**
* The CSet of the tile used by the ith combo on the screen, where i is
* the index used to access this array. Combos are counted left to right,
* top to bottom.
* Screen dimensions are 16 combos wide, by 11 combos high.
*
*/ Example Use: !#!

/************************************************************************************************************/

int ComboF[];               ZASM Instruction:
                    CF###       COMBOF
                    COMBOFD     COMBOFDM

/**
* The placed flag of the ith combo on the screen, where i is the index
* used to access this array. Combos are counted left to right, top to
* bottom. Use the CF_ constants in std.zh to set or compare these values.
* Screen dimensions are 16 combos wide, by 11 combos high.
*
*/ Example Use: !#!

/************************************************************************************************************/

int ComboI[];               ZASM Instruction:
                    CI###       COMBOID
                            COMBOIDM


/**
* The inherent flag of the ith combo on the screen, where i is the index
* used to access this array. Combos are counted left to right, top to
* bottom. Use the CF_ constants in std.zh to set or compare these values.
* Screen dimensions are 16 combos wide, by 11 combos high.
*
*/ Example Use: !#!

/************************************************************************************************************/

int ComboT[];               ZASM Instruction:
                    CT###       COMBOTD
                            COMBOTDM


/**
* The combo type of the ith combo on the screen, where i is the index
* used to access this array. Combos are counted left to right, top to
* bottom. Use the CT_ constants in std.zh to set or compare these values.
* Screen dimensions are 16 combos wide, by 11 combos high.
*
*/ Example Use: !#!

/************************************************************************************************************/

int ComboS[];               ZASM Instruction:
                    CS###       COMBOSD
                            COMBOSDM


/**
* The walkability mask of the ith combo on the screen, where i is the
* index used to access this array. Combos are counted left to right, top
* to bottom. The least signficant bit is true if the top-left of the combo
* is solid, the second-least signficant bit is true if the bottom-left
* of the combo is is solid, the third-least significant bit is true if the
* top-right of the combo is solid, and the fourth-least significant bit is
* true if the bottom-right of the combo is solid.
* Screen dimensions are 16 combos wide, by 11 combos high.
*
*/ Example Use: !#!

/************************************************************************************************************/

int MovingBlockX;           ZASM Instruction:
                    PUSHBLOCKX


/**
* The X position of the current moving block. If there is no moving block
* on the screen, it will be -1. This is read-only; while setting it is not
* syntactically incorrect, it does nothing.
*
*/ Example Use: !#!

/************************************************************************************************************/

int MovingBlockY;           ZASM Instruction:
                    PUSHBLOCKY

/**
* The Y position of the current moving block. If there is no moving block
* on the screen, it will be -1. This is read-only; while setting it is not
* syntactically incorrect, it does nothing.
*
*/ Example Use: !#!

/************************************************************************************************************/

int MovingBlockCombo;           ZASM Instruction:
                    PUSHBLOCKCOMBO

/**
* The combo used by moving block. If there is no block moving, the value
* is undefined.
*
*/ Example Use: !#!

/************************************************************************************************************/

int MovingBlockCSet;            ZASM Instruction:
                    PUSHBLOCKCSET

/**
* The CSet used by moving block. If there is no block moving, the value
* is undefined.
*
*/ Example Use: !#!

/************************************************************************************************************/

int UnderCombo;             ZASM Instruction:
                    UNDERCOMBO

/**
* The current screen's under combo.
* !#! Is setting this legal?
*
*/ Example Use: !#!

/************************************************************************************************************/

int UnderCSet;              ZASM Instruction:
                    UNDERCSET

/**
* The current screen's under CSet.
* !#! Is setting this legal?
*
*/ Example Use: !#!

/************************************************************************************************************/

bool State[];               ZASM Instruction:
                    SCREENSTATED

/**
* An array of miscellaneous status data associated with the current
* screen.
* Screen states involve such things as permanent screen secrets, the
* status of lock blocks and treasure chest combos, and whether items have
* been collected.
* These values are recorded in the save file when the player saves their
* game. Use the ST_ constants in std.zh as indices into this array.
*
*/ Example Use: !#!

/************************************************************************************************************/

int Door[];             ZASM Instruction:
                    SCRDOORD
                    SCRDOOR

/**
* The door type for each of the four doors on a screen. Doors are counted
* using the first four DIR_ constants in std.zh. Use the D_ constants in
* std.zh to compare these values.
*
*/ Example Use: !#!

/************************************************************************************************************/

int RoomType;               ZASM Instruction:
                    ROOMTYPE

/**
* The type of room this screen is (Special Item, Bomb Upgrade, etc)
* This is currently read-only.
* Use the RT_* constants in std.zh
*
*/ Example Use: !#!

/************************************************************************************************************/

int RoomData;               ZASM Instruction:
                    ROOMDATA

/**
* This is the data associated with the room type above. What it means depends
* on the room type. For Special Item, it will be the item ID, for a Shop, it
* will be the Shop Number, etc.
* Basically, this is what's in the "Catch-all" menu item underneath Room Type.
* If the room type has no data (eg, Ganon's room), this will be undefined.
*
*/ Example Use: !#!

/************************************************************************************************************/

void TriggerSecrets();          ZASM Instruction:
                    SECRETS ? !#!

/**
* Triggers screen secrets temporarily. Set Screen->State[ST_SECRET]
* to true beforehand or afterward if you would like them to remain
* permanent.
*
*/ Example Use: Screen->TriggerSecrets();


/************************************************************************************************************/

void WavyIn();          ZASM Instruction:
                WAVYIN

/**
* Replicates the warping screen wave effect (inbound) from a tile warp.
*
*/ Example Use: !#!

/************************************************************************************************************/

void WavyOut();         ZASM Instruction:
                WAVYOUT

/**
* Replicates the warping screen wave effect (outbound) from a tile warp.
*
*/ Example Use: !#!

/************************************************************************************************************/

void ZapIn();           ZASM Instruction:
                ZAPIN

/**
* Replicates the warping screen zap effect (inbound) from a tile warp.
*
*/ Example Use: !#!

/************************************************************************************************************/

void ZapOut();          ZASM Instruction:
                ZAPOUT

/**
* Replicates the warping screen zap effect (outbound) from a tile warp.
*
*/ Example Use: !#!

/************************************************************************************************************/

void OpeningWipe();     ZASM Instruction:
                OPENWIPE

/**
* Replicates the opening wipe screen effect (using the quest rule for its type) from a tile warp.
*
*/ Example Use: !#!

/************************************************************************************************************/

bool Lit;               ZASM Instruction:
                    LIT

/**
* Whether or not the screen is lit. Setting this variable will change the
* lighting setting of the screen until you change screens.
*
*/ Example Use: !#!


/************************************************************************************************************/

int Wavy;               ZASM Instruction:
                    WAVY

/**
* The time, in frames, that the 'wave' screen effect will be in effect.
* This value is decremented once per frame. As the value of Wavy approaches 0,
* the intensity of the waves decreases.
*
*/ Example Use: !#!

/************************************************************************************************************/

int Quake;              ZASM Instruction:
                    QUAKE

/**
* The time, in frames, that the screen will shake. This value is decremented
* once per frame. As the value of Quake approaches 0, the intensity of the
* screen shaking decreases.
*
*/ Example Use: !#!

/************************************************************************************************************/

void SetSideWarp(int warp, int screen, int dmap, int type);     ZASM Instruction:
                                    SETSIDEWARP

/**
* Sets the current screen's side warp 'warp' to the destination screen,
* DMap and type. If any of the parameters screen, dmap or type are equal
* to -1, they will remain unchanged. If warp is not between 0 and 3, the
* function does nothing.

* Directions match DIR_* in std_constants.zh
* Use constants SIDEWARP_* in std_constants.zh
*
*/ Example Use: !#!

/************************************************************************************************************/

void SetTileWarp(int warp, int screen, int dmap, int type);     ZASM Instruction:
                                    SETTILEWARP

/**
* Sets the current screen's tile warp 'warp' to the destination screen,
* DMap and type. If any of the parameters screen, dmap or type are equal
* to -1, they will remain unchanged. If warp is not between 0 and 3, the
* function does nothing
*
* Warp-Tiles A, B, C, and D are 0, 1, 2, and 3 respectively.
* Use constants TILEWARP_* in std_constants.zh
*
*/ Example Use: !#!

/************************************************************************************************************/

int GetSideWarpDMap(int warp);          ZASM Instruction:
                        GETSIDEWARPDMAP

/**
* Returns the destination DMap of the given side warp on the current screen.
* Returns -1 if warp is not between 0 and 3.
*
* Side-Warp Directions match DIR_* in std_constants.zh
* Use constants SIDEWARP_* in std_constants.zh
*
*/ Example Use: !#!

/************************************************************************************************************/

int GetSideWarpScreen(int warp);        ZASM Instruction:
                        GETSIDEWARPSCR

/**
* Returns the destination screen of the given side warp on the current
* screen. Returns -1 if warp is not between 0 and 3.
*
* Directions match DIR_* in std_constants.zh
* Use constants SIDEWARP_* in std_constants.zh
*
*/ Example Use: !#!

/************************************************************************************************************/

int GetSideWarpType(int warp);          ZASM Instruction:
                        GETSIDEWARPTYPE

/**
* Returns the warp type of the given side warp on the current screen.
* Returns -1 if warp is not between 0 and 3.
*
* Directions match DIR_* in std_constants.zh
* Use constants SIDEWARP_* in std_constants.zh
*
*/ Example Use: !#!

/************************************************************************************************************/

int GetTileWarpDMap(int warp);          ZASM Instruction:
                        GETTILEWARPDMAP

/**
* Returns the destination DMap of the given tile warp on the current screen.
* Returns -1 if warp is not between 0 and 3.
*
* Warp-Tiles A, B, C, and D are 0, 1, 2, and 3 respectively.
* Use constants TILEWARP_* in std_constants.zh
*
*/ Example Use: !#!

/************************************************************************************************************/

int GetTileWarpScreen(int warp);        ZASM Instruction:
                        GETTILEWARPSCR

/**
* Returns the destination screen of the given tile warp on the current
* screen. Returns -1 if warp is not between 0 and 3.
*
* Warp-Tiles A, B, C, and D are 0, 1, 2, and 3 respectively.
* Use constants TILEWARP_* in std_constants.zh
*
*/ Example Use: !#!

/************************************************************************************************************/

int GetTileWarpType(int warp);          ZASM Instruction:
                        GETTILEWARPTYPE

/**
* Returns the warp type of the given tile warp on the current screen.
* Returns -1 if warp is not between 0 and 3.
*
* Warp-Tiles A, B, C, and D are 0, 1, 2, and 3 respectively.
* Use constants TILEWARP_* in std_constants.zh
*
*/ Example Use: !#!

/************************************************************************************************************/

int LayerMap(int n);            ZASM Instruction:
                    LAYERMAP

/**
* Returns the map of the screen currently being used as the nth layer.
* Values of n less than 1 or greater than 6, or layers that are not set up,
* returns -1.
*
*/ Example Use: !#!

/************************************************************************************************************/

int LayerScreen(int n);         ZASM Instruction:
                    LAYERSCREEN

/**
* Returns the number of the screen currently being used as the nth layer.
* Values of n less than 1 or greater than 6, or layers that are not set up,
* returns -1.
*
*/ Example Use: !#!

/************************************************************************************************************/

int NumItems();             ZASM Instruction:
                    ITEMCOUNT

/**
* Returns the number of items currently present on the screen. Screen
* items, shop items, and items dropped by enemies are counted; Link's
* weapons, such as lit bombs, or enemy weapons are not counted.
* Note that this value is only correct up until the next call to
* Waitframe().
*
*/ Example Use: !#!

/************************************************************************************************************/

item LoadItem(int num);         ZASM Instruction:
                    LOADITEMR
                    LOADITEMV

/**
* Returns a pointer to the numth item on the current screen. The return
* value is undefined unless 1 <= num <= NumItems().
*
* Attempting to return an invalid item pointer will print an error to allegro.log.
*
*/ Example Use: !#!

/************************************************************************************************************/

item CreateItem(int id);        ZASM Instruction:
                    CREATEITEMV
                    CREATEITEMR

/**
* Returns a pointer to the numth FFC on the current screen. The return
* value is undefined unless 1 <= num <= ffcs, where ffcs is the number
* of FFCs active on the screen.
*
*/ Example Use: !#!

/************************************************************************************************************/

ffc LoadFFC(int num);           ZASM Instruction:
                    GETFFCSCRIPT

/**
* Returns a pointer to the numth FFC on the current screen. The return
* value is undefined unless 1 <= num <= ffcs, where ffcs is the number
* of FFCs active on the screen.
*
*/ Example Use: !#!

/************************************************************************************************************/

int NumNPCs();              ZASM Instruction:
                    NPCCOUNT

/**
* Returns the number of NPCs (enemies and guys) on the screen.
* Note that this value is only correct up until the next call to
* Waitframe().
*
*/ Example Use: !#!

/************************************************************************************************************/

npc LoadNPC(int num);           ZASM Instruction:
                    LOADNPCR
                    LOADNPCV

/**
* Returns a pointer to the numth NPC on the current screen. The return
* value is undefined unless 1 <= num <= NumNPCs().
*
*/ Example Use: !#!

/************************************************************************************************************/

npc CreateNPC(int id);          ZASM Instruction:
                    CREATENPCR
                    CREATENPCV

/**
* Creates an npc of the given type at (0,0). Use the NPC_ constants in
* std.zh to pass into this method. The return value is a pointer to the
* new NPC.
* The maximum number of NPCs on any given screen is 255. ZC will report an
* error to allegro.log if you try to create NPCs after reaching that maximum.
*
*/ Example Use: !#!

/************************************************************************************************************/

int NumLWeapons();          ZASM Instruction:
                    LWPNCOUNT

/**
* Returns the number of Link weapon projectiles currently present on the screen.
* This includes things like Link's arrows, bombs, magic, etc. Note that this
* value is only correct up until the next call of Waitframe().
*
*/ Example Use: !#!

/************************************************************************************************************/

lweapon LoadLWeapon(int num);       ZASM Instruction:
                    LOADLWEAPONR
                    LOADLWEAPONV

/**
* Returns a pointer to the num-th lweapon on the current screen. The return
* value is undefined unless 1 <= num <= NumLWeapons().
*
*/ Example Use: !#!

/************************************************************************************************************/

lweapon CreateLWeapon(int type);    ZASM Instruction:
                    CREATELWEAPONR
                    CREATELWEAPONV

/**
* Creates an lweapon of the given type at (0,0). Use the LW_ constants in
* std.zh to pass into this method. The return value is a pointer to the
* new lweapon.
* The maximum number of lweapons on any given screen is 255. ZC will NOT report an
* error to allegro.log if you try to create lweapons after reaching that maximum.
* The maximum instances for lweapons, and eweapons are independent.
* This cap is of *all* lweapons, of any type. Mixing types will not increase this cap.
*
*/ Example Use: !#!

/************************************************************************************************************/

int NumEWeapons();          ZASM Instruction:
                    EWPNCOUNT

/**
* Returns the number of Enemy weapon projectiles currently present on the screen.
* This includes things like Enemy arrows, bombs, magic, etc. Note that this
* value is only correct up until the next call of Waitframe().
*
*/ Example Use: !#!

/************************************************************************************************************/

eweapon LoadEWeapon(int num);       ZASM Instruction:
                    LOADEWEAPONR
                    LOADEWEAPONV

/**
* Returns a pointer to the numth eweapon on the current screen. The return
* value is undefined unless 1 <= num <= NumEWeapons().
*
*/ Example Use: !#!

/************************************************************************************************************/

eweapon CreateEWeapon(int type);    ZASM Instruction:
                    CREATEEWEAPONR
                    CREATEEWEAPONV

/**
* Creates an eweapon of the given type at (0,0). Use the EW_ constants in
* std.zh to pass into this method. The return value is a pointer to the
* new lweapon.
* The maximum number of eweapons on any given screen is 255. ZC will NOT report an
* error to allegro.log if you try to create eweapons after reaching that maximum.
* The maximum instances for eweapons, and lweapons are independent.
* This cap is of *all* eweapons, of any type. Mixing types will not increase this cap.
*
*/ Example Use: !#!

/************************************************************************************************************/

bool isSolid(int x, int y);     ZASM Instruction:
                    ISSOLID

/**
* Returns true if the screen position (x, y) is solid - that is, if it
* is within the solid portion of a combo on layers 0, 1 or 2. If either
* x or y exceed the screen's bounds, then it will return false.
* It will also return false if the only applicable solid combo is a solid
* water combo that has recently been 'dried' by the whistle.
*
*/ Example Use: !#!

/************************************************************************************************************/

void ClearSprites(int spritelist);  ZASM Instruction:
                    CLEARSPRITESR
                    CLEARSPRITESV

/**
* Clears all of a certain kind of sprite from the screen. Use the SL_
* constants in std.zh to pass into this method.
*
*/ Example Use: !#!

/************************************************************************************************************/

void Message(int string);

                    ZASM Instruction:
                    MSGSTRR
                    MSGSTRV
/**
* Prints the message string with given ID onto the screen.
* If string is 0, the currently displayed message is removed.
* This method's behavior is undefined if string is less than 0
* or greater than the total number of messages in the quest.
*/ Example Use: !#!

/************************************************************************************************************/

                //===============================//
                //    SCRIPT DRAWING COMMANDS    //
                //===============================//

        /* These commands use the Allegro 4 drawing primitives to render drawn
            effects directly to the screen. You may draw to the screen immediately
            which is considered RT_SCREEN (see: Render Targets), or you may change
            to another render target (1 through 5) and issue your drawing commands,
            then render that back to the screen.

            All render targets have eight valid layers, 0 through 7.
            Drawing colour 0 to a layer of a bitmap render target erases a section of that,
            creating a transparent area on that layer. Any transparent area that extends
            through all layers will be drawn as transparent when rendered back to the screen
            if 'bool mask' is set true.

            Drawing colour 0 directly to a screen layer is undefined.

            Please note: For all draw primitives, if the quest rule 'Subscreen Appears
            Above Sprites' is set,passing the layer argument as 7 will allow drawing
            on top of the subscreen.

            Tha maximum number of script drawing instructions per frame is 1000.



void Rectangle(     int layer, int x, int y, int x2, int y2,
            int color, float scale,
            int rx, int ry, int rangle,
            bool fill, int opacity      );

                    ZASM Instruction:
                    RECTR
                    RECT

/**
* Draws a rectangle on the specified layer of the current screen, using args to set its properties:
*
* METRICS
* (x,y) as the top-left corner and (x2,y2) as the bottom-right corner.
*
* COLOUR
*
* SCALE AND ROTATION
*
* FILL AND OPACITY
*
* Then scales the rectangle uniformly about its center by the given
* factor.
* Lastly, a rotation, centered about the point (rx, ry), is performed
* counterclockwise using an angle of rangle degrees.
* A filled rectangle is drawn if fill is true; otherwise, this method
* draws a wireframe.
* The rectangle is drawn using the specified index into the entire
* 256-element palette: for instance, passing in a color of 17 would
* use color 1 of cset 1.
* Opacity controls how transparent the rectangle will be.
* You may use OP_TRANS (64) for a translucent (50%) image, or OP_OPAQUE (128)
* for an opaque (100%) image. Other values are **ignored**, and will be treated
* as translucent (OP_TRANS, or 64).
*
*/ Example Use: !#!

/************************************************************************************************************/

void Circle(    int layer, int x, int y, int radius,
        int color, float scale,
        int rx, int ry, int rangle,
        bool fill, int opacity  );


                    ZASM Instruction:
                    CIRCLE
                    CIRCLER

/**
* Draws a circle on the specified layer of the current screen with
* center (x,y) and radius scale*radius.
* Then performs a rotation counterclockwise, centered about the point
* (rx, ry), using an angle of rangle degrees.
* A filled circle is drawn if fill is true; otherwise, this method
* draws a wireframe.
* The circle is drawn using the specified index into the entire
* 256-element palette: for instance, passing in a color of 17 would
* use color 1 of cset 1.
* Opacity controls how transparent the circle will be.
* You may use OP_TRANS (64) for a translucent (50%) image, or OP_OPAQUE (128)
* for an opaque (100%) image. Other values are **ignored**, and will be treated
* as translucent (OP_TRANS, or 64).
*
*/ Example Use: !#!

/************************************************************************************************************/

void Arc(   int layer, int x, int y, int radius, int startangle, int endangle,
        int color, float scale,
        int rx, int ry, int rangle,
        bool closed, bool fill, int opacity );

                    ZASM Instruction:
                    ARC
                    ARCR

/**
* Draws an arc of a circle on the specified layer of the current
* screen. The circle in question has center (x,y) and radius
* scale*radius.
* The arc beings at startangle degrees counterclockwise from standard
* position, and ends at endangle degress counterclockwise from standard
* position. The behavior of this function is undefined unless
* 0 <= endangle-startangle < 360.
* The arc is then rotated about the point (rx, ry) using an angle of
* rangle radians.
* If closed is true, a line is drawn from the center of the circle to
* each endpoint of the arc, forming a sector of the circle. If fill
* is also true, a filled sector is drawn instead.
* The arc or sector is drawn using the specified index into the entire
* 256-element palette: for instance, passing in a color of 17 would
* use color 1 of cset 1.
* Opacity controls how transparent the arc will be.
* You may use OP_TRANS (64) for a translucent (50%) image, or OP_OPAQUE (128)
* for an opaque (100%) image. Other values are **ignored**, and will be treated
* as translucent (OP_TRANS, or 64).
*
*/ Example Use: !#!

/************************************************************************************************************/

void Ellipse(   int layer, int x, int y, int xradius, int yradius,
        int color, float scale,
        int rx, int ry, int rangle,
        bool fill, int opacity);



                    ZASM Instruction:
                    ELLIPSE2
                    ELLIPSER

/**
* Draws an ellipse on the specified layer of the current screen with
* center (x,y), x-axis radius xradius, and y-axis radius yradius.
* Then performs a rotation counterclockwise, centered about the point
* (rx, ry), using an angle of rangle degrees.
* A filled ellipse is drawn if fill is true; otherwise, this method
* draws a wireframe.
* The ellipse is drawn using the specified index into the entire
* 256-element palette: for instance, passing in a color of 17 would
* use color 1 of cset 1.
* Opacity controls how transparent the ellipse will be.
* You may use OP_TRANS (64) for a translucent (50%) image, or OP_OPAQUE (128)
* for an opaque (100%) image. Other values are **ignored**, and will be treated
* as translucent (OP_TRANS, or 64).
*
*/ Example Use: !#!

/************************************************************************************************************/

void Spline(    int layer, int x1, int y1, int x2, int y2, int x3, int y3,int x4, int y4,
        int color, int opacity);

                    ZASM Instruction:
                    SPLINER
                    SPLINE

/**
* Draws a cardinal spline on the specified layer of the current screen
* between (x1,y1) and (x4,y4)
* The spline is drawn using the specified index into the entire
* 256-element palette: for instance, passing in a color of 17 would
* use color 1 of cset 1.
* Opacity controls how transparent the ellipse will be.
* You may use OP_TRANS (64) for a translucent (50%) image, or OP_OPAQUE (128)
* for an opaque (100%) image. Other values are **ignored**, and will be treated
* as translucent (OP_TRANS, or 64).
*
*/ Example Use: !#!

/************************************************************************************************************/

void Line(  int layer, int x, int y, int x2, int y2,
        int color, float scale,
        int rx, int ry, int rangle,
        int opacity );

                    ZASM Instruction:
                    LINE
                    LINER
/**
* Draws a line on the specified layer of the current screen between
* (x,y) and (x2,y2).
* Then scales the line uniformly by a factor of scale about the line's
* midpoint.
* Finally, performs a rotation counterclockwise, centered about the
* point (rx, ry), using an angle of rangle degrees.
* The line is drawn using the specified index into the entire
* 256-element palette: for instance, passing in a color of 17 would
* use color 1 of cset 1.
* Opacity controls how transparent the line will be.
* You may use OP_TRANS (64) for a translucent (50%) image, or OP_OPAQUE (128)
* for an opaque (100%) image. Other values are **ignored**, and will be treated
* as translucent (OP_TRANS, or 64).
*
*/ Example Use: !#!

/************************************************************************************************************/

void PutPixel   (int layer, int x, int y,
        int color,
        int rx, int ry, int rangle,
        int opacity);

                    ZASM Instruction:
                    PUTPIXEL
                    PUTPIXELR
/**
* Draws a raw pixel on the specified layer of the current screen
* at (x,y).
* Then performs a rotation counterclockwise, centered about the point
* (rx, ry), using an angle of rangle degrees.
* The point is drawn using the specified index into the entire
* 256-element palette: for instance, passing in a color of 17 would
* use color 1 of cset 1.
* Opacity controls how transparent the point will be.
* You may use OP_TRANS (64) for a translucent (50%) image, or OP_OPAQUE (128)
* for an opaque (100%) image. Other values are **ignored**, and will be treated
* as translucent (OP_TRANS, or 64).
*
*/ Example Use: !#!

/************************************************************************************************************/

void DrawTile   (int layer, int x, int y,
        int tile, int blockw, int blockh,
        int cset, int xscale, int yscale,
        int rx, int ry, int rangle,
        int flip,
        bool transparency, int opacity);

                    ZASM Instruction:
                    DRAWTILE
                    DRAWTILER
/**
* Draws a block of tiles on the specified layer of the current screen,
* starting at (x,y), using the specified cset.
* Starting with the specified tile, this method copies a block of size
* blockh x blockw from the tile sheet to the screen. This method's
* behavior is undefined unless 1 <= blockh, blockw <= 20.
* Scale specifies the actual size in pixels! So scale 1 would mean it is
* only one pixel in size. To use the default sizes of block w,h you must
* set xscale and yscale to -1. These values are not independant of one another,
* so you cannot set xscale and leave yscale at -1.
* rx, ry : these work now, just like the other primitives.
* rangle performs a rotation clockwise using an angle of rangle degrees.
* Flip specifies how the tiles should be flipped when drawn:
* 0: No flip
* 1: Horizontal flip
* 2: Vertical flip
* 3: Both (180 degree rotation)
* If transparency is true, the tiles' transparent regions will be
* respected.
* Opacity controls how transparent the solid portions of the tiles will
* be.
* You may use OP_TRANS (64) for a translucent (50%) image, or OP_OPAQUE (128)
* for an opaque (100%) image. Other values are **ignored**, and will be treated
* as translucent (OP_TRANS, or 64).
*/ Example Use: !#!

/************************************************************************************************************/

void FastTile   (int layer, int x, int y,
        int tile, int cset,
        int opacity );

                    ZASM Instruction:
                    FASTTILER
/**
* Optimized and simpler version of DrawTile()
* Draws a single tile on the current screen much in the same way as DrawTile().
* See DrawTile() for an explanation on what these arguments do.
*/ Example Use: !#!

/************************************************************************************************************/

void DrawCombo  (int layer, int x, int y,
        int combo, int w, int h,
        int cset, int xscale, int yscale,
        int rx, int ry, int rangle,
        int frame, int flip,
        bool transparency, int opacity);

                    ZASM Instruction:
                    DRAWCOMBO
                    DRAWCOMBOR
/**
* Draws a combo on the specified layer of the current screen,
* starting at (x,y), using the specified cset.
* Starting with the specified tile referenced by the combo,
* this method copies a block of size
* blockh x blockw from the tile sheet to the screen. This method's
* behavior is undefined unless 1 <= blockh, blockw <= 20.
* Scale specifies the actual size in pixels! So scale 1 would mean it is
* only one pixel in size. To use the default sizes of block w,h you must
* set xscale and yscale to -1. These values are not independant of one another,
* so you cannot set xscale and leave yscale at -1.
* rx, ry : works now :
* rangle performs a rotation clockwise using an angle of rangle degrees.
* Flip specifies how the tiles should be flipped when drawn:
* 0: No flip
* 1: Horizontal flip
* 2: Vertical flip
* 3: Both (180 degree rotation)
* If transparency is true, the tiles' transparent regions will be
* respected.
* Opacity controls how transparent the solid portions of the tiles will
* be.
* You may use OP_TRANS (64) for a translucent (50%) image, or OP_OPAQUE (128)
* for an opaque (100%) image. Other values are **ignored**, and will be treated
* as translucent (OP_TRANS, or 64).
*/ Example Use: !#!

/************************************************************************************************************/

void FastCombo  (int layer, int x, int y,
        int combo, int cset,
        int opacity );

                    ZASM Instruction:
                    FASTCOMBOR
/**
* Optimized and simpler version of DrawCombo()
* Draws a single combo on the current screen much in the same way as DrawCombo().
* See DrawCombo() for an explanation on what these arguments do.
*/ Example Use: !#!

/************************************************************************************************************/

void DrawCharacter  (int layer, int x, int y,
            int font, int color, int background_color,
            int width, int height, int glyph,
            int opacity );

                    ZASM Instruction:
                    DRAWCHARR
/**
* Draws a single ASCII character 'glyph' on the specified layer of the current screen,
* using the specified font index (see std.zh for FONT_* list to pass to this method),
* starting at (x,y), using the specified color as the foreground color
* and background_color as the background color. * NOTE * Use -1 for a transparent background.
* The arguments width and height may be used to draw the glyph
* of any arbitrary size begining at 1 pixel up to 512 pixels large. (more than four times the size of the screen)
* Passing 0 or negative values to this will use the default fonts w and h.
* Opacity controls how transparent the is.
* You may use OP_TRANS (64) for a translucent (50%) image, or OP_OPAQUE (128)
* for an opaque (100%) image. Other values are **ignored**, and will be treated
* as translucent (OP_TRANS, or 64).
*/ Example Use: !#!

/************************************************************************************************************/

void DrawInteger    (int layer, int x, int y,
            int font, int color, int background_color,
            int width, int height, int number, int number_decimal_places,
            int opacity);


                    ZASM Instruction:
                    DRAWINTR
/**
* Draws a zscript 'int' or 'float' on the specified layer of the current screen,
* using the specified font index (see std.zh for FONT_* list to pass to this method),
* starting at (x,y), using the specified color as the foreground color
* and background_color as the background color. * NOTE * Use -1 for a transparent background.
* The arguments width and height may be used to draw the number
* of any arbitrary size begining at 1 pixel up to 512 pixels large.
* Passing 0 or negative values to this will use the default fonts w and h.
* The number can be rendered as type 'int' or 'float' by setting the argument
* "number_decimal_places", which is only valid if set to 0 or <= 4.
* Opacity controls how transparent the is.
* You may use OP_TRANS (64) for a translucent (50%) image, or OP_OPAQUE (128)
* for an opaque (100%) image. Other values are **ignored**, and will be treated
* as translucent (OP_TRANS, or 64).
*/ Example Use: !#!

/************************************************************************************************************/

void DrawString(    int layer, int x, int y,
            int font, int color, int background_color, int format,
            int ptr[],
            int opacity );

                    ZASM Instruction:
                    DRAWSTRINGR
/**
* Prints a NULL terminated string up to 256 characters from an int array
* containing ASCII data (*ptr) on the specified layer of the current screen,
* using the specified font index (see std.zh for FONT_* list to pass to this method),
* using the specified color as the foreground color
* and background_color as the background color. * NOTE * Use -1 for a transparent background.
* The array pointer should be passed as the argument for '*ptr', ie.
* int string[] = "Example String"; Screen->DrawString(l,x,y,f,c,b_c,fo,o,string);
* int format tells the engine how to format the string. (see std.zh for TF_* list to pass to this method)
* Opacity controls how transparent the message is.
* You may use OP_TRANS (64) for a translucent (50%) image, or OP_OPAQUE (128)
* for an opaque (100%) image. Other values are **ignored**, and will be treated
* as translucent (OP_TRANS, or 64).
*/ Example Use: !#!

/************************************************************************************************************/



    /////////////////////////
    // (Psuedo) 3D drawing //
    /////////////////////////

    //! When allocating a texture, the size (h,w) must be between 1 and 16, in powers of two.
    //! Thus, legal sizes are 1, 2, 4, 8, and 16.
    //! This applies to *all* the pseudo-3d and 3-D drawing functions.

    void Quad   ( int layer,
            int x1, int y1, int x2, int y2, int x3, int y3, int x4, int y4,
            int w, int h, int cset, int flip, int texture, int render_mode);

                    ZASM Instruction:
                    QUADR

    /**
    * Draws a quad on the specified layer with the corners x1,y1 through x4,y4.
    * Corners are drawn in a counterclockwise order starting from x1,y1. ( So
    * if you draw a "square" for example starting from the bottom-right corner
    * instead of the usual top-left, the the image will be textured onto the
    * quad so it appears upside-down. -yes, these are rotatable. )
    *
    * From there a single or block of tiles, combos **or a bitmap** is then texture mapped
    * onto the quad using the arguments w, h, cset, flip, and render_mode.
    * A positive vale in texture will draw the image from the tilesheet pages,
    * whereas a negative value will be drawn from the combo page. 0 will draw combo number 0.
    * Both w and h are undefined unless 1 <= blockh, blockw <= 16, and it is a power of
    * two. ie: 1, 2 are acceptable, but 2, 15 are not.
    *
    * To specify a bitmap as a texture, sum 65520 with the bitmap ID, or use the constant TEX_BITMAP + Bitmap
    * Example: Screen->Quad(6, 0, 0, 40, 25, 18, 50, 60, 110, 0, 0, 0, 0, TEX_BITMAP+RT_BITMAP0, PT_TEXTURE);
    *
    *
    * Flip specifies how the tiles/combos should be flipped when drawn:
    * 0: No flip
    * 1: Horizontal flip
    * 2: Vertical flip
    * 3: Both (180 degree rotation)
    *   (!)  See std.zh for a list of all available render_mode arguments.
    */ Example Use: !#!

    /************************************************************************************************************/

    void Triangle   ( int layer,
            int x1, int y1, int x2, int y2, int x3, int y3,
            int w, int h, int cset, int flip, int texture, int render_mode);

                    ZASM Instruction:
                    TRIANGLER

    /**
    * Draws a triangle on the specified layer with the corners x1,y1 through x4,y4.
    * Corners are drawn in a counterclockwise order starting from x1,y1.
    * From there a single or block of tiles or combos is then texture mapped
    * onto the triangle using the arguments w, h, cset, flip, and render_mode.
    *
    * A positive value in texture will draw the image from the tilesheet pages,
    * whereas a negative value will be drawn from the combo page. 0 will draw combo number 0.
    * Both w and h are undefined unless 1 <= blockh, blockw <= 16, and it is a power of
    * two. ie: 1, 2 are acceptable, but 2, 15 are not.
    *
    * Flip specifies how the tiles/combos should be flipped when drawn:
    * 0: No flip
    * 1: Horizontal flip
    * 2: Vertical flip
    * 3: Both (180 degree rotation)
    *   (!) See std.zh for a list of all available render_mode arguments.
    */ Example Use: !#!

    /************************************************************************************************************/

    void Triangle3D ( int layer,
            int pos[9], int uv[6], int csets[3], int size[2],
            int flip, int tile, int polytype );

                    ZASM Instruction:
                    TRIANGLE3DR
    /**
    * Draws a 3d triangle on the specified layer with the corners x1,y1 through x4,y4.
    * Corners are drawn in a counterclockwise order starting from x1,y1.
    * From there a single or block of tiles or combos is then texture mapped
    * onto the triangle using the arguments w, h, cset, flip, and render_mode.
    *
    * A positive value in texture will draw the image from the tilesheet pages,
    * whereas a negative value will be drawn from the combo page. 0 will draw combo number 0.
    * Both w and h are undefined unless 1 <= blockh, blockw <= 16, and it is a power of
    * two. ie: 1, 2 are acceptable, but 2, 15 are not.
    *
    * Arguments take the form of array pointers: Thus, you must declare arrays with the values that you wish to use
    * and pass their pointers to each of the following:
    *
    * [9]pos - x, y, z positions of the 3 corners.
    * [6]uv - x, y texture coordinates of the given texture.
    * [3]csets - of the corners to interpolate between.
    * [2]size - w, h, of the texture.
    *   w, and h must be in values of 1, 2, 4, 8, or 16.
    *
    *
    * Flip specifies how the tiles/combos should be flipped when drawn:
    * 0: No flip
    * 1: Horizontal flip
    * 2: Vertical flip
    * 3: Both (180 degree rotation)
    *   (!) See std.zh for a list of all available render_mode arguments.
    */ Example Use: !#!

    /************************************************************************************************************/

    void Quad3D ( int layer,
            int pos[], int uv[], int cset[], int size[],
            int flip, int texture, int render_mode );

                    ZASM Instruction:
                    QUAD3DR

    /**
    * Draws a Quad on the specified layer similar to Quad.
    * Arguments take the form of array pointers: Thus, you must declare arrays with the values that you wish to use
    * and pass their pointers to each of the following:
    *
    * [12]pos - x, y, z positions of the 4 corners.
    * [8]uv - x, y texture coordinates of the given texture.
    * [4]csets - of the corners to interpolate between.
    * [2]size - w, h, of the texture.
    *   w, and h must be in values of 1, 2, 4, 8, or 16.
    *   (!) See std.zh for a list of all available render_mode arguments.
    */ Example Use: !#!

    /************************************************************************************************************/

    void SetRenderTarget( int bitmap_id );

                    ZASM Instruction:
                    SETRENDERTARGET

    /**
    * Sets the target bitmap for all succesive drawing commands.
    * These can be directly to the screen or any one of the available off-screen bitmaps,
    * which are generally categorized as -1(screen) or 0-bitmapNumber(off-screen).
    *
    *   (!) See std.zh for a complete list of valid render targets (RT_*).
    */ Example Use: !#!

    /************************************************************************************************************/

    void DrawBitmap ( int layer,
            int bitmap_id,
            int source_x, int source_y, int source_w, int source_h,
            int dest_x, int dest_y, int dest_w, int dest_h,
            float rotation, bool mask);

                    ZASM Instruction:
                    BITMAPR

    /**
    * Draws a source rect from off-screen Bitmap with id of bitmap_id onto
    * an area of the screen described by dest rect at the given layer.
    *
    *   (!) Note* Script drawing functions are enqueued and executed in a frame-by-frame basis
    *   based on the order of which layer they need to be drawn to. Drawing to or from
    *   seperate render tagets or bitmaps is no exception! So keep in mind in order to
    *   eliminate unwanted drawing orders or bugs.
    */ Example Use:
            Screen->DrawBitmap( 6, myBitmapId, 0, 0, 16, 16, 79, 57, 32, 32, 0, true );
                This would draw a 16x16 area starting at the upper-left corner of source bitmap to
                layer 6 of the current screen at coordinates 79,57 with a width and height of



    // Screen/Layer Drawing
    */

    /************************************************************************************************************/

    void DrawBitmapEx   ( int layer,
            int bitmap_id,
            int source_x, int source_y, int source_w, int source_h,
            int dest_x, int dest_y, int dest_w, int dest_h,
            float rotation, int cx, int cy, int mode, int lit, bool mask);

            ZASM: BITMAPEXR

    /**
    *
    * As DrawBitmap(), except that it can do more things.
    *
    * The 'mode' parameter sets up drawing modes. AT PRESENT this supports normal opaque drawing as DrawBitmap()
    * AND it supports TRANSLUCENT MODE, which will allow drawing translucent bitmaps.
    * The translucent mode does not yet support rotation, and some other modes are temporarily suspended, pending
    * full implementation.
    *
    * See std_constants.zh, under BITDX_* (or possibly we'll change this to BMPDX_* later?) for a list of modes,
    * and more information
    *
    * Draws a source rect from off-screen Bitmap with id of bitmap_id onto
    * an area of the screen described by dest rect at the given layer.
    *
    *   (!) Note* Script drawing functions are enqueued and executed in a frame-by-frame basis
    *   based on the order of which layer they need to be drawn to. Drawing to or from
    *   seperate render tagets or bitmaps is no exception! So keep in mind in order to
    *   eliminate unwanted drawing orders or bugs.
    *
    * Set 'mode' to a value of '1' to draw a translucent bitmap.
    *
    * Note: Rotation does not work with translucent bitmaps at this time.
    *
    * cx, cy: Used for pivot
    * lit: used for lit colour in light table (may not work).
    *
    */ Example Use:
            Screen->DrawBitmapEx( 6, myBitmapId, 0, 0, 16, 16, 79, 57, 32, 32, 0, 1, true );
                This would draw a translucent 16x16 area starting at the upper-left corner of source
                bitmap to layer 6 of the current screen at coordinates 79,57 with a width and height of




    // Screen/Layer Drawing
    */

    /************************************************************************************************************/

    void DrawLayer  (int layer,
            int source_map, int source_screen, int source_layer,
            int x, int y, float rotation, int opacity);

                    ZASM Instruction:
                    DRAWLAYERR

    /**
    * Draws an entire Layer from source_screen on source_map on the specified layer of the current screen at (x,y).
    * If rotation is not zero, it(the entire layer) will rotate about its center.
    *
    * Opacity controls how transparent the solid portions of the tiles will
    * You may use OP_TRANS (64) for a translucent (50%) image, or OP_OPAQUE (128)
    * for an opaque (100%) image. Other values are **ignored**, and will be treated
    * as translucent (OP_TRANS, or 64).
    *
    * Also see ScreenToLayer() in std.zh
    */ Example Use:

    /************************************************************************************************************/

    void DrawScreen (int layer,
            int map, int source_screen,
            int x, int y, float rotation);

                    ZASM Instruction:
                    DRAWSCREENR

    /**
    * Draws an entire screen from screen on map on the specified layer of the current screen at (x,y).
    * If rotation is not zero, it(the entire screen) will rotate about its center.
    *
    */ Example Use:

/************************************************************************************************************/
/************************************************************************************************************/



//===================================
//--- FFC Functions and Variables ---
//===================================

                                            class ffc

/*
*   The following functions, and arrays are part of the ffc class.
*
*   Ordinarily, these are set when writing an ffc script, using the pointer
*       this->
*   Example: this->Data = 10;   Sets the Data variable for the present ffc
*                   to a value of '10'.
*
*   The 'this->' pointer is used in ffcs, and item scripts only. It references ffc
*   variables and arrays in an ffc script; and itemdata variables in an item script.
*
*   Changing ffc variables without 'this->':
*
*   You may change a variable, or array value of the ffc class by loading the ffc into a custom pointer
*   using Screen->LoadFFC(int number) as follows:
*
*   ffc f; //Declare a general ffc pointer.
*       //You must use the ffc token to declare the pointer, but you may use any
*       //name that you desire for it. 'f' here, is merely a short-name example.
*
*   f = Screen->LoadFFC(10); //Loads the data of ffc ID 10 for the present screen into the 'f' pointer.
*
*   f->Data = 15; //Sets the 'Data' variable of the ffc to a value of '15'.
*
*   f->X = 120; //Sets  the X-position of the ffc assigned to pointer 'f' to a value of '120'.
*/


Set Working FFC ID:         ZASM Instruction
                REFFFC

/************************************************************************************************************/


int Data;           ZASM Instruction:
                DATA<d3>

/**
* The number of the combo associated with this FFC.
*/ Example Use:

    f->Data = 10;
    Sets the ffc to Combo 10.

/************************************************************************************************************/

int Script;         ZASM Instruction:
                FFSCRIPT<d3>

/**
* The number of the script assigned to the FFC. This will be automatically
* set to 0 when the FFC's script halts. A script cannot change the script of
* the FFC running it; in other words, f->Script is read-only when f==this.
* When an FFC's script is changed, its arguments, Misc[], and registers will
* all be set to 0, and it will start running from the beginning. Set
* ffc->InitD[] after setting the script before the script starts running
* to pass arguments to it.
*
*/ Example Use:

    f->Script = 10;
    Sets the ffc to Combo 10.

/************************************************************************************************************/

int CSet;           ZASM Instruction:
                FCSET<d3>

/**
* The cset of the FFC.
*
*/ Example Use:

    f->CSet = 2;
    Sets the ffc to CSet 2.

/************************************************************************************************************/

int Delay;          ZASM Instruction:
                DELAY<d3>

/**
* The FFC's animation delay, in frames.
*
*/ Example Use:

    f->Delay = 120;
    120 frames will pass before the ffc animates.

/************************************************************************************************************/

float X;            ZASM Instruction:
                FX<d3>

/**
* The FFC's X position on the screen.
*
* Values outside the screen boundaries *are* legal.
*
*/ Example Use:

    f->X = 43;
    Sets the ffc at X-position 43; 43 pixels to the right of the leftmost screen edge.

/************************************************************************************************************/

float Y;            ZASM Instruction:
                FY<d3>

/**
* The FFC's Y position on the screen.
*
* Values outside the screen boundaries *are* legal.
* The Y value 0 is automatically offset to account for the passive subscreen.
* To place an ffc in the area of the passive subscreen, a negative value must be passed to Y.
*
*/ Example Use:

    f->X = 90;
    Sets the ffc at Y-position to 90; i.e. 90 pixels below the passive subscreen.

/************************************************************************************************************/

float Vx;           ZASM Instruction:
                XD<d3>

/**
* The FFC's velocity's X-component.
*
*
*/ Example Use:

    f->Vx = 20;
    The ffc will move by 20 pixels per second on the X avis.

/************************************************************************************************************/

float Vy;           ZASM Instruction:
                YD<d3>

/**
* The FFC's velocity's Y-component.
*
*
*/ Example Use:

    f->Vy = 20;
    The ffc will move by 20 pixels per second on the Y avis.

/************************************************************************************************************/

float Ax;           ZASM Instruction:
                XD2<d3>

/**
* The FFC's acceleration's X-component.
*
*
*/ Example Use:

    f->Vx = 1.03;
    Every frame, the velocity X-component will increase by 1.03.

/************************************************************************************************************/

float Ay;           ZASM Instruction:
                YD2<d3>

/**
* The FFC's acceleration's Y-component.
*
*
*/ Example Use:

    f->Vx = 0.2903;
    Every frame, the velocity Y-component will increase by 0.2903.

/************************************************************************************************************/

bool Flags[];           ZASM Instruction:
                FLAG<d3>
                FFFLAGSD


/**
* The FFC's set of flags. Use the FFCF_ constants in std.zh as the
* index to access a particular flag.
*
*/ Example Use: !#!

/************************************************************************************************************/

int TileWidth;          ZASM Instruction:
                FFTWIDTH<d3>
                WIDTH<>

/**
* The number of tile columns composing the FFC.
* The maximum value is '4'.
*
*/ Example Use: !#!

/************************************************************************************************************/

int TileHeight;         ZASM Instruction:
                FFTHEIGHT<d3>
                HEIGHT<>

/**
* The number of tile rows composing the FFC.
* The maximum value is '4'.
*
*/ Example Use: !#!

/************************************************************************************************************/

int EffectWidth;        ZASM Instruction:
                FFCWIDTH<d3>

/**
* The width (in pixels) of the area of effect of the combo associated with the FFC.
* The maximum value is '64'.
*
*/ Example Use: !#!

/************************************************************************************************************/

int EffectHeight;       ZASM Instruction:
                FFCHEIGHT<d3>

/**
* The width (in pixels) of the area of effect of the combo associated with the FFC.
* The maximum value is '64'.
*
*/ Example Use: !#!

/************************************************************************************************************/

int Link;           ZASM Instruction:
                FFLINK<d3>
                LINK<>

/**
* The number of the FFC linked to by this FFC.
*
*/ Example Use: !#!

/************************************************************************************************************/

float InitD[8];         ZASM Instruction:
                FFINITD<>
                FFINITDD<>?
                D<>

/**
* The original values of the FFC's 8 D input values as they are stored in
* the .qst file, regardless of whether they have been modified by ZScript.
*
*/ Example Use: !#!

/************************************************************************************************************/

float Misc[16];         ZASM Instruction:
                FFMISC
                FFMISCD

/**
* An array of 16 miscellaneous variables for you to use as you please.
* These variables are not saved with the ffc.
*
*/ Example Use: !#!

/************************************************************************************************************/

Address Argument        ZASM Instruction
                A<>

/************************************************************************************************************/
/************************************************************************************************************/





//====================================
//--- Link Functions and Variables ---
//====================================

                                            namespace Link


int X;              ZASM Instruction:
                LINKX

/**
* Link's X position on the screen, in pixels. Float values passed to this will be truncated to ints.
*
*/ Example Use: !#!

/************************************************************************************************************/

int Y;              ZASM Instruction:
                LINKY

/**
* Link's Y position on the screen, in pixels. Float values passed to this will be truncated to ints.
*
*/ Example Use: !#!

/************************************************************************************************************/

int Z;              ZASM Instruction:
                LINKZ

/**
* Link's Z position on the screen, in pixels. Float values passed to this will be truncated to ints.
*
*/ Example Use: !#!

/************************************************************************************************************/

bool Invisible;         ZASM Instruction:
                LINKINVIS

/**
* Whether Link is currently being draw to the screen. Set true to remove him from view.
*
*/ Example Use: !#!

/************************************************************************************************************/

bool CollDetection;     ZASM Instruction:
                LINKINVINC

/**
* If true, Link's collision detection with npcs and eweapons is currently turned off.
* This variable works on a different system to clocks and the level 4 cheat, so it will not
* necessarily return true if they are set.
*
*/ Example Use: !#!

/************************************************************************************************************/

int Jump;           ZASM Instruction:
                LINKJUMP

/**
* Link's upward velocity, in pixels. If negative, Link will fall.
* The downward acceleration of Gravity (in Init Data) modifies this value every frame.
*
* This value is intended to be in pixels, but appears to be in tiles. ?!
*
*/ Example Use: !#!

/************************************************************************************************************/

int SwordJinx;          ZASM Instruction:
                LINKSWORDJINX

/**
* The time, in frames, until Link regains use of his sword. -1 signifies
* a permanent loss of the sword caused by a Red Bubble.
*
*/ Example Use: !#!

/************************************************************************************************************/

int ItemJinx;           ZASM Instruction:
                LINKITEMJINX

/**
* The time, in frames, until Link regains use of his items. -1 signifies
* a permanent loss of his items. caused by a Red Bubble.
*
*/ Example Use: !#!

/************************************************************************************************************/

int Drunk;          ZASM Instruction:
                LINKDRUNK

/**
* The time, in frames, that Link will be 'drunk'. If positive, the player's
* controls are randomly interfered with, causing Link to move erratically.
* This value is decremented once per frame. As the value of Drunk approaches 0,
* the intensity of the effect decreases.
*
*/ Example Use: !#!

/************************************************************************************************************/

int Dir;            ZASM Instruction:
                LINKDIR

/**
* The direction Link is facing. Use the DIR_ constants in std.zh to set
* or compare this variable. Note: even though Link can move diagonally if the
* quest allows it, his sprite doesn't ever use any of the diagonal directions,
* which are intended for enemies only.
*
* Reading this value occurs after Waitdraw().
*
*/ Example Use: !#!

/************************************************************************************************************/

int HitDir;         ZASM Instruction:
                LINKHITDIR

/**
* The direction Link should bounce in when he is hit. This is mostly useful for
* simulating getting hit by setting Link->Action to LA_GOTHURTLAND.
*
* This value does nothing if Link->Action does not equal LA_GOTHURTLAND or LA_GOTHURTWATER.
* Forcing this value to -1 prevent Link from being knocked back when injured, or when touching any enemy.
*
*/ Example Use: !#!

/************************************************************************************************************/

int WarpEffect;         ZASM Instruction:
                WARPEFFECT

/**
* Sets a warp effect type prior to doing Screen->Warp
* These replicate the in-build effects for tile warps.
* see 'std_constants.zh' under WARPFX_* for a list of effects.
*
*/ Example Use: !#!

/************************************************************************************************************/

int WarpSound;          ZASM Instruction:
                LINKWARPSOUND

/**
* Setting this to a value other than '0' will play that sound when Link warps.
*
*/ Example Use: !#!

/************************************************************************************************************/

bool SideWarpSounds;        ZASM Instruction:
                PLAYWARPSOUND

/**
* By default, even if you set a warp sound, it will not play in sidewarps.
* If you enable this setting, the sound will play in side warps.
* At present, this does not disable playing the sound otherwise. Set Link->WarpSound = 0 to do that.
*
*/ Example Use: !#!

/************************************************************************************************************/

bool PitWarpSounds;     ZASM Instruction:
                PLAYPITWARPSFX

/**
* By default, even if you set a warp sound, it will not play in pit warps.
* If you enable this setting, the sound will play in a pit warp, one time.
* This value resets after the pit warp, so it is mandatory to re-set it each time tat you desire a pit warp
*   to play a sound. Do this before Waitdraw().
*
*/ Example Use: !#!

/************************************************************************************************************/

int UseWarpReturn;      ZASM Instruction:
                LINKRETSQUARE

/**
* Setting this to a value between 0 and 3 will change the target return square for Link->Warp
* Valid values are: 0 (A), 1 (B), 2 (C), and 3 (D). Other values will be clamed within this range.
*
*/ Example Use: !#!

/************************************************************************************************************/

int UsingItem;          ZASM Instruction:
                LINKUSINITEM

/**
* Returns the ID of an item used when Link uses an item.
* Returns -1 if Link is not using an item this frame.
* Does not work at present.
*
*/ Example Use: !#!

/************************************************************************************************************/

int UsingItemA;         ZASM Instruction:
                LINKUSINITEMA

/**
* Returns the ID of an item used when Link uses an item on button A.
* Returns -1 if Link is not using an item this frame.
* Does not work at present.
*
*/ Example Use: !#!

/************************************************************************************************************/

int UsingItemB;         ZASM Instruction:
                LINKUSINITEMB

/**
* Returns the ID of an item used when Link uses an item on button B.
* Returns -1 if Link is not using an item this frame.
* Does not work at present.
*
*/ Example Use: !#!

/************************************************************************************************************/

bool Diagonal;          ZASM Instruction:
                LINKDIAG

/**
* This corresponds to whether 'Diagonal Movement' is enabled, or not.
* This will initially return true, or false, based on the setting in Quest->Graphics->Sprites->Link.
* You may enable, or disable diagonal movement by writing to this value.
*
*/ Example Use: !#!

/************************************************************************************************************/

bool BigHitbox;         ZASM Instruction:
                LINKBIGHITBOX

/**
* This corresponds to whether 'Big Hitbox' is enabled, or not.
* This will initially return true, or false, based on the setting in Quest->Graphics->Sprites->Link.
* You may enable, or disable big hitbox, by writing to this value.
*
*/ Example Use: !#!

/************************************************************************************************************/

int HP;             ZASM Instruction:
                LINKHP

/**
* Link's current hitpoints, in 16ths of a heart.
*
*/ Example Use: !#!

/************************************************************************************************************/

int MP;             ZASM Instruction:
                LINKMP

/**
* Link's current amount of magic, in 32nds of a magic block.
*
*/ Example Use: !#!

/************************************************************************************************************/

int MaxHP;              ZASM Instruction:
                    LINKMAXHP

/**
* Link's maximum hitpoints, in 16ths of a heart.
*
*/ Example Use: !#!

/************************************************************************************************************/

int MaxMP;              ZASM Instruction:
                    LINKMAXMP

/**
* Link's maximum amount of magic, in 32nds of a magic block.
*
*/ Example Use: !#!

/************************************************************************************************************/

int Action;             ZASM Instruction:
                    LINKACTION<>

/**
* Link's current action. Use the LA_ constants in std.zh to set or
* compare this value.
* This value is read-write, but writing some actions are undefined in this
* version of ZC. The following are known to work if you write to them:
*
* LA_NONE
* LA_WALKING
* LA_ATTACKING
* LA_FROZEN //Verify
* LA_HOLD1LAND
* LA_HOLD2LAND
* LA_GOTHURTLAND
* LA_SWIMMING
* LA_GOTHURTWATER
* LA_HOLD1WATER
* LA_HOLD2WATER
* LA_CASTING
* LA_DROWNING
* LA_CHARGING  //Resets chargeclock?
* LA_SPINNING  //Resets spinclock?
* LA_DIVING    //Verify
*
*/ Example Use: !#!

/************************************************************************************************************/

int HeldItem;               ZASM Instruction:
                    LINKHELD<>

/**
* Link's current action. Use the LA_ constants in std.zh to set or
* The item that Link is currently holding up; reading or setting this
* field is undefined if Link's action is not current a hold action.
* Use the I_ constants in std.zh to specify the item, or -1 to show
* no item. Setting HeldItem to values other than -1 or a valid item
* ID is undefined.
*
*/ Example Use: !#!

/************************************************************************************************************/

int LadderX;                ZASM Instruction:
                    LINKLADDERX

/**
* The X position of Link's stepladder, or 0 if no ladder is onscreen.
* This is read-only; while setting it is not syntactically incorrect, it does nothing.
*
*/ Example Use: !#!

/************************************************************************************************************/

int LadderY;                ZASM Instruction:
                    LINKLADDERY

/**
* The Y position of Link's stepladder, or 0 if no ladder is onscreen.
* This is read-only; while setting it is not syntactically incorrect, it does nothing.
*
*/ Example Use: !#!

/************************************************************************************************************/



    *** Input Functions ***
    * The following Input* boolean values return true if the player is pressing
    * the corresponding button, analog stick, or key. Writing to this variable simulates
    * the press or release of that referenced button, analog stick, or key.
    */

    bool InputStart;        ZASM: INPUTSTART

    bool InputMap;          ZASM: INPUTMAP

    bool InputUp;           ZASM: INPUTUP

    bool InputDown;         ZASM: INPUTDOWN

    bool InputLeft;         ZASM: INPUTLEFT

    bool InputRight;        ZASM: INPUTRIGHT

    bool InputA;            ZASM: INPUTA

    bool InputB;            ZASM: INPUTB

    bool InputL;            ZASM: INPUTL

    bool InputR;            ZASM: INPUTR

    bool InputEx1           ZASM: INPUTEX1

    bool InputEx2           ZASM: INPUTEX2

    bool InputEx3           ZASM: INPUTEX3

    bool InputEx4           ZASM: INPUTEX4

    bool InputAxisUp;       ZASM: INPUTAXISUP

    bool InputAxisDown;     ZASM: INPUTAXISDOWN

    bool InputAxisLeft;     ZASM: INPUTAXISLEFT

    bool InputAxisRight;        ZASM: INPUTAXISRIGHT


    *** Press Functions ***
    /**
    * The following Press* boolean values return true if the player activated
    * the corresponding button, analog stick, or key this frame. Writing to this
    * variable simulates the press or release of that referenced button, analog stick,
    * or keys input press state.
    */


    bool PressStart;        ZASM: INPUTPRESSSTART

    bool PressMap;          ZASM: INPUTPRESSMAP

    bool PressUp;           ZASM: INPUTPRESSUP

    bool PressDown;         ZASM: INPUTPRESSDOWN

    bool PressLeft;         ZASM: INPUTPRESSLEFT

    bool PressRight;        ZASM: INPUTPRESSRIGHT

    bool PressA;            ZASM: INPUTPRESSA

    bool PressB;            ZASM: INPUTPRESSB

    bool PressL;            ZASM: INPUTPRESSL

    bool PressR;            ZASM: INPUTPRESSR

    bool PressEx1           ZASM: INPUTPRESSEX1

    bool PressEx2           ZASM: INPUTPRESSEX2

    bool PressEx3           ZASM: INPUTPRESSEX3

    bool PressEx4           ZASM: INPUTPRESSEX4

    bool PressAxisUp;       ZASM: PRESSAXISUP

    bool PressAxisDown;     ZASM: PRESSAXISDOWN

    bool PressAxisLeft;     ZASM: PRESSAXISLEFT

    bool PressAxisRight;        ZASM: PRESSAXISRIGHT

/************************************************************************************************************/

int InputMouseX;            ZASM Instruction:
                    INPUTMOUSEX

/**
* The mouse's in-game X position. This value is undefined if
* the mouse pointer is outside the Zelda Classic window.
*
*/ Example Use: !#!

/************************************************************************************************************/

int InputMouseY;            ZASM Instruction:
                    INPUTMOUSEY

/**
* The mouse's in-game Y position. This value is undefined if
* the mouse pointer is outside the Zelda Classic window.
*
*/ Example Use: !#!

/************************************************************************************************************/

int InputMouseB;            ZASM Instruction:
                    INPUTMOUSEB

/**
* Whether the left or right mouse buttons are pressed, as two flags OR'd (|) together;
* use the MB_ constants or the Input'X'Click functions in std.zh to check the button states.
* InputMouseB is read only; while setting it is not syntactically incorrect, it does nothing
* If you are not comfortable with binary, you can use the InputMouse'x' functions in std.zh
*
*/ Example Use: !#!

/************************************************************************************************************/

int InputMouseZ;            ZASM Instruction:
                    INPUTMOUSEB

/**
* The current state of the mouse's scroll wheel, negative for scrolling down and positive for scrolling up.
*
*/ Example Use: !#!

/************************************************************************************************************/

bool Item[256];             ZASM Instruction:
                    LINKITEMD

/**
* True if Link's inventory contains the item whose ID is the index of
* the array access. Use the I_ constants in std.zh as an index into this array.
*
*/ Example Use: !#!

/************************************************************************************************************/

int Equipment;              ZASM Instruction:
                    LINKEQUIP

/**
* Contains the item IDs of what is currently equiped to Link's A and B buttons.
* The first 8 bits contain the A button item, and the second 8 bits contain the B button item.
* If you are not comfortable with performing binary operations,
* you can use the functions GetEquipmentA() or GetEquipmentB() in std.zh.
*
*/ Example Use: !#!

/************************************************************************************************************/

int ItemA;              ZASM Instruction:
                    LINKITEMA

/**
* Contains the item IDs of what is currently equiped to Link's A button.
* Writing to this variable will set an item to the A-button.
* This will occur even if the item is not in inventory, and not on the subscreen.
* This will ignore if you have B+A or B-only subscreens, and force-set the item.
* The intent of this is to allow scriters to easily create scripted subscreens.
*
*/ Example Use: !#!

/************************************************************************************************************/

int ItemB;              ZASM Instruction:
                    LINKITEMB

/**
* Contains the item IDs of what is currently equiped to Link's B button.
* Writing to this variable will set an item to the A-button.
* This will occur even if the item is not in inventory, and not on the subscreen.
* The intent of this is to allow scriters to easily create scripted subscreens.
*
*/ Example Use: !#!

/************************************************************************************************************/
//! Untested
int SetItemSlot(int itm_id, bool a_button, bool force);
                    ZASM Instruction:
                    LINKITEMB

/**
* This allows you to set Link's button items without binary operations, and to decide whether to
* obey quest rules, or inventory.
*
* When using this, 'itm_id' is the ID number of the item.
* Set 'a_button' true to set this item to the A-button, false to set it to the B-button.
* Set' force' true to set the item even if Link does not have it, or if the Quest Rules disallow it.
*   Otherwise, set 'force' false, and the item will only be set if Link has it. Furthermore
*   it will only set to slot A if either it is a sword, or the B+A quest rule is enabled.
*
*/ Example Use: !#!

/************************************************************************************************************/

int Tile;               ZASM Instruction:
                    LINKTILE

/**
* The current tile associated with Link. The effect of writing to this variable is undefined.
* Because Link's tile is not determined until he is drawn, this will actually represent
* Link's tile in the previous frame.
*
*/ Example Use: !#!

/************************************************************************************************************/

int Flip;               ZASM Instruction:
                    LINKFLIP

/**
* The flip value of current tile associated with Link.
* The effect of writing to this variable is undefined (will do nothing).
* Because Link's tile is not determined until he is drawn, this will actually represent
* Link's tile flip in the previous frame.
*
*/ Example Use: !#!


/************************************************************************************************************/

int Eaten;              ZASM Instruction:
                    LINKEATEN

/**
* This stores a counter for how long Link has been inside a LikeLike, or similar enemy.
* It returns 0 if Link is not eaten, otherwise it returns the duration of him being eaten.
*
*/ Example Use: !#!

/************************************************************************************************************/

//Implemented, but does nothing. The opcodes are unfinished.
void SetTile(int sprite, int tile, int dir, int flip)
                    ZASM Instruction:
                    LINKSETTILE

/**
* Sets the tile for Link's various actions.
* 'sprite' is the action for the tile. See Quest->Graphics->Sprites->Link for a visual reference.
* 'tile is the base tile for the sequence. It uses the animation style set in the sprites editor.
* 'dir' is the direction for the tile.
* 'flip' is the flip attribute for the tile.
* See 'std_constants' entries under LSPR_* for a list of the various attributes for 'sprite'.
*/

/************************************************************************************************************/
//!Implemented, but the opcodes are unfinished, so it does not yet work as intended.
int GetLinkExtend(int sprite, int dir);
                    ZASM Instruction:
                    LINKGETEXTEND

/**
* Gets the extend value for one of Link's various actions.
* This is equivalent to the Extend value set in Quest->Graphics->Sprites->Link when selecting a tile.
* See 'std_constants' entries under LSPR_* for a list of the various attributes for 'sprite'.
*/

/************************************************************************************************************/
//!Implemented, but the opcodes are unfinished, so it does not yet work as intended.
void SetLinkExtend(int sprite, int dir, int extend);
                    ZASM Instruction:
                    LINKSETEXTEND

/**
* Sets the extend value for one of Link's various actions.
* This is equivalent to the Extend value set in Quest->Graphics->Sprites->Link when selecting a tile.
* See 'std_constants' entries under LSPR_* for a list of the various attributes for 'sprite'.
*/

/************************************************************************************************************/
//!Not implemented.
int GetTile(int sprite, int dir, int flip)
                    ZASM Instruction:
                    LINKGETTILE

/**
* Returns the tile for one of Link's various actions.
* 'sprite' is the action for the tile. See Quest->Graphics->Sprites->Link for a visual reference.
* 'dir' is the direction for the tile.
* 'flip' is the flip attribute for the tile.
* See 'std_constants' entries under LSPR_* for a list of the various attributes for 'sprite'.
*/

/************************************************************************************************************/

int Extend;             ZASM Instruction:
                    LINKEXTEND

/**
* Sets the extend value for all of Link's various actions.
* This is equivalent to the Extend value set in Quest->Graphics->Sprites->Link when selecting
* a tile, click on his sprites for any given action, and press the 'x' key.
* The options are 16x16, 16x32, and 32x32; which correspond to Extend values of ( 0, 1, and 2 )
* respectively.
*
* If used to check, this will return the value of the LSPR_NORMAL entry.
*/

/************************************************************************************************************/

int HitHeight;              ZASM Instruction:
                    LINKHYSZ

/**
* link's Hitbox height in pixels.
* This is not usable, as Link->Extend cannot be set.
* While setting it is not syntactically incorrect, it does nothing.
* You can read a value that you assign to this (e.g. for custom collision functions).
* This value is not preserved through sessions: Loading a saved game will reset it to the default.
*
*/ Example Use: !#!

/************************************************************************************************************/

int HitWidth;               ZASM Instruction:
                    LINKHXSZ

/**
* link's Hitbox width in pixels.
* This is not usable, as Link->Extend cannot be set.
* While setting it is not syntactically incorrect, it does nothing.
* You can read a value that you assign to this  (e.g. for custom collision functions).
* This value is not preserved through sessions: Loading a saved game will reset it to the default.
*
*/ Example Use: !#!

/************************************************************************************************************/

int TileWidth;              ZASM Instruction:
                    LINKTYSZ
/**
* Link's width, in tiles.
* This is not usable, as Link->Extend cannot be set.
* While setting it is not syntactically incorrect, it does nothing.
* You can read a value that you assign to this (e.g. for custom/proxy sprite drawing).
* This value is not preserved through sessions: Loading a saved game will reset it to the default.
*
*/ Example Use: !#!

/************************************************************************************************************/

int TileHeight;             ZASM Instruction:
                    LINKTXSZ

/**
* Link's height, in tiles.
* This is not usable, as Link->Extend cannot be set.
* While setting it is not syntactically incorrect, it does nothing.
* You can read a value that you assign to this (e.g. for custom/proxy sprite drawing).
* This value is not preserved through sessions: Loading a saved game will reset it to the default.
*
*/ Example Use: !#!

/************************************************************************************************************/

int HitZHeight;             ZASM Instruction:
                    LINKHZSZ

/**
* The Z-axis height of Link's hitbox, or collision rectangle.
* The lower it is, the lower a flying or jumping enemy must fly in order to hit Link.
* To jump over a sprite, you must be higher than its Z + HitZHeight.
* The values of DrawZOffset and HitZHeight are linked. Setting one, also sets the other.
* Writing to this is ignored unless Extend is set to values >=3.
* This is not usable, as Link->Extend cannot be set.
* While setting it is not syntactically incorrect, it does nothing.
* You can read a value that you assign to this (e.g. for custom collision functions).
* This value is not preserved through sessions: Loading a saved game will reset it to the default.
*
*/ Example Use: !#!

/************************************************************************************************************/

int HitXOffset;             ZASM Instruction:
                    LINKHXOFS

/**
* The X offset of Link's hitbox, or collision rectangle.
* Setting it to positive or negative values will move Link's hitbox left or right.
* Writing to this is ignored unless Extend is set to values >=3.
* This is not usable, as Link->Extend cannot be set.
* While setting it is not syntactically incorrect, it does nothing.
* You can read a value that you assign to this (e.g. for custom collision functions).
* This value is not preserved through sessions: Loading a saved game will reset it to the default.
*
*/ Example Use: !#!

/************************************************************************************************************/

int HitYOffset;             ZASM Instruction:
                    LINKHYOFS

/**
* The Y offset of Link's hitbox, or collision rectangle.
* Setting it to positive or negative values will move Link's hitbox up or down.
* Writing to this is ignored unless Extend is set to values >=3.
* This is not usable, as Link->Extend cannot be set.
* While setting it is not syntactically incorrect, it does nothing.
* You can read a value that you assign to this (e.g. for custom collision functions).
* This value is not preserved through sessions: Loading a saved game will reset it to the default.
*
*/ Example Use: !#!

/************************************************************************************************************/

int DrawXOffset;            ZASM Instruction:
                    LINKXOFS

/**
* The X offset of Link's sprite.
* Setting it to positive or negative values will move the sprite's tiles left or right relative to its position.
* Writing to this is ignored unless Extend is set to values >=3.
* This is not usable, as Link->Extend cannot be set.
* While setting it is not syntactically incorrect, it does nothing.
* You can read a value that you assign to this.
* This value is not preserved through sessions: Loading a saved game will reset it to the default.
*
*/ Example Use: !#!

/************************************************************************************************************/

int DrawYOffset;            ZASM Instruction:
                    LINKYOFS

/**
* The Y offset of Link's sprite.
* Setting it to positive or negative values will move the sprite's tiles up or down relative to its position.
* Writing to this is ignored unless Extend is set to values >=3.
* This is not usable, as Link->Extend cannot be set.
* While setting it is not syntactically incorrect, it does nothing.
* You can read a value that you assign to this.
* This value is not preserved through sessions: Loading a saved game will reset it to the default.
*
*/ Example Use: !#!

/************************************************************************************************************/

int DrawZOffset;            ZASM Instruction:
                    LINKZOFS

/**
* The Z offset of Link's sprite.
* Writing to this is ignored unless Extend is set to values >=3.
* The values of DrawZOffset and HitZHeight are linked. Setting one, also sets the other.
* This is not usable, as Link->Extend cannot be set.
* While setting it is not syntactically incorrect, it does nothing.
* You can read a value that you assign to this.
* This value is not preserved through sessions: Loading a saved game will reset it to the default.
*
*/ Example Use: !#!

/************************************************************************************************************/

float Misc[32];             ZASM Instruction:
                    LINKMISC
                    LINKMISCD

/**
* An array of 32 miscellaneous variables for you to use as you please.
* These variables are not saved with Link.
*
*/ Example Use: !#!

/************************************************************************************************************/

void Warp(int DMap, int screen);    ZASM Instruction:
                    WARP
                    WARPR

/**
* Warps link to the given screen in the given DMap, just like if he'd
* triggered an 'Insta-Warp'-type warp.
*
*/ Example Use: !#!

/************************************************************************************************************/

void PitWarp(int DMap, int screen); ZASM Instruction:
                    PITWARP
                    PITWARPR

/**
* This is identical to Warp, but Link's X and Y positions are preserved
* when he enters the destination screen, rather than being set to the
* Warp Return square.
*
*/ Example Use: !#!

/************************************************************************************************************/

SelectAWeapon(int dir);         ZASM Instruction:
                    !#!

/**
* Sets the A button item to the next one in the given direction based on
* the indices set in the subscreen. This will skip over items if A and B
* would be set to the same item.
* If the quest rule "Can Select A-Button Weapon On Subscreen" is disabled,
* this function does nothing.
*
*/ Example Use: !#!

/************************************************************************************************************/

SelectBWeapon(int dir);         ZASM Instruction:
                    !#!

/**
* Sets the B button item to the next one in the given direction based on
* the indices set in the subscreen. This will skip over items if A and B
* would be set to the same item.
*
*/ Example Use: !#!


/************************************************************************************************************/
/************************************************************************************************************/


//===================================
//--- NPC Functions and Variables ---
//===================================

                                            class npc


    bool isValid();         ZASM Instruction:
                    ISVALIDNPC
    /**
    * Returns whether or not this NPC pointer is still valid. A pointer
    * becomes invalid if the enemy dies or Link leaves the screen.
    * Trying to access any variable of an invalid NPC pointer prints
    * an error to allegro.log and does nothing.
    */

/************************************************************************************************************/

    void GetName(int buffer[]); ZASM Instruction:
                    NPCNAME
    /**
    * Loads the npc's name into 'buffer'. To load an NPC from an ID rather than a pointer,
    * use 'GetNPCName' from std.zh
    */

/************************************************************************************************************/

    int ID;             ZASM Instruction:
                    NPCID
    /**
    * The NPC's enemy ID number.
    * npc->ID is read-only; while setting it is not syntactically incorrect, it does nothing.
    */

/************************************************************************************************************/

    int Type;           ZASM Instruction:
                    NPCTYPE
    /**
    * The NPC's Type. Use the NPCT_ constants in std.zh to compare this value.
    * npc->Type is read-only; while setting it is not syntactically incorrect, it does nothing.
    */

/************************************************************************************************************/

    int X;              ZASM Instruction:
                    NPCX
    /**
    * The NPC's current X coordinate, in pixels. Float values passed to this will be cast to int.
    */

/************************************************************************************************************/

    int Y;              ZASM Instruction:
                    NPCY
    /**
    * The NPC's current Y coordinate, in pixels. Float values passed to this will be cast to int.
    */

/************************************************************************************************************/

    int Z;              ZASM Instruction:
                    NPCZ
    /**
    * The NPC's current Z coordinate, in pixels. Float values passed to this will be cast to int.
    */

/************************************************************************************************************/

    int Jump;           ZASM Instruction:
                    NPCJUMP
    /**
    * The NPC's upward velocity, in pixels. If negative, the NPC will fall.
    * The downward acceleration of Gravity (in Init Data) modifies this value every frame.
    */

/************************************************************************************************************/

    int Dir;            ZASM Instruction:
                    NPCDIR
    /**
    * The direction the NPC is facing. Use the DIR_ constants in std.zh to
    * set and compare this value.
    */

/************************************************************************************************************/

    int Rate;           ZASM Instruction:
                    NPCRATE
    /**
    * The rate at which the NPC changes direction. For a point of reference,
    * the "Octorok (Magic)" enemy has a rate of 16. The effect of writing to
    * this field is currently undefined.
    */

/************************************************************************************************************/

    int Haltrate;           ZASM Instruction:
                    NPCHALTRATE
    /**
    * The extent to which the NPC stands still while moving around the
    * screen. As a point of reference, the Zols and Gels have haltrate of
    * 16. The effect of writing to this field is currently undefined.
    */

/************************************************************************************************************/

    int Homing;         ZASM Instruction:
                    NPCHOMING
    /**
    * How likely the NPC is to move towards Link.
    * The effect of writing to this field is currently undefined.
    */

/************************************************************************************************************/

    int Hunger;         ZASM Instruction:
                    NPRCHUNGE
    /**
    * How likely the NPC is to move towards bait.
    * The effect of writing to this field is currently undefined.
    */

/************************************************************************************************************/

    int Step;           ZASM Instruction:
                    NPCSTEP
    /**
    * The NPC's movement speed. A Step of 100 usually means that
    * the enemy moves at approximately one pixel per animation frame.
    * As a point of reference, the "Octorok (Magic)" enemy has
    * a step of 200. The effect of writing to this field is
    * currently undefined.
    */

/************************************************************************************************************/

    bool CollDetection;     ZASM Instruction:
                    NPCCOLLDET
    /**
    * Whether the NPC will use the system's code to work out collisions with Link
    * Initialised as 'true'.
    */

/************************************************************************************************************/

    int ASpeed;         ZASM Instruction:
                    NPCFRAMERATE
    /**
    * The the NPC's animation frame rate, in screen frames. The effect of
    * writing to this field is currently undefined.
    */

/************************************************************************************************************/

    int DrawStyle;          ZASM Instruction:
                    NPCDRAWTYPE
    /**
    * The way the NPC is animated. Use the DS_ constants in std.zh to set or
    * compare this value. The effect of writing to this field is currently undefined.
    */

/************************************************************************************************************/

    int HP;             ZASM Instruction:
                    NPCHP
    /**
    * The NPC's current hitpoints. A weapon with a Power of 1 removes 2
    * hitpoints.
    */

/************************************************************************************************************/

    int Damage;         ZASM Instruction:
                    NPCDP
    /**
    * The amount of damage dealt to an unprotected Link when he touches this NPC, in
    * quarter-hearts.
    */

/************************************************************************************************************/

    int WeaponDamage;       ZASM Instruction:
                    NPCWDP
    /**
    * The amount of damage dealt to an unprotected Link by this NPC's weapon, in
    * quarter-hearts.
    */

/************************************************************************************************************/

    int Stun;           ZASM Instruction:
                    NPCSTUN
    /**
    * The time, in frames, that the NPC will be stunned. Some types of enemies cannot be stunned.
    */

/************************************************************************************************************/

    int OriginalTile;       ZASM Instruction:
                    NPCOTILE
    /**
    * The number of the starting tile used by this NPC.
    */

/************************************************************************************************************/

    int Tile;           ZASM Instruction:
                    NPCTILE
    /**
    * The current tile associated with this NPC. The effect of writing to this variable is undefined.
    */

/************************************************************************************************************/

    int Weapon;         ZASM Instruction:
                    NPCWEAPON
    /**
    * The weapon used by this enemy. Use the WPN_ constants (NOT the EW_ constants)
    * in std.zh to set or compare this value.
    */

/************************************************************************************************************/

    int ItemSet;            ZASM Instruction:
                    NPCITEMSET
    /**
    * The items that the NPC might drop when killed. Use the IS_ constants
    * in std.zh to set or compare this value.
    */

/************************************************************************************************************/

    int CSet;           ZASM Instruction:
                    NPCCSET
    /**
    * The CSet used by this NPC.
    */

/************************************************************************************************************/

    int BossPal;            ZASM Instruction:
                    NPCBOSSPAL
    /**
    * The boss pallete used by this NPC; this pallete is only used if CSet
    * is 14 (the reserved boss cset). Use the BPAL_ constants in std.zh to
    * set or compare this value.
    */

/************************************************************************************************************/

    int SFX;            ZASM Instruction:
                    NPCBGSFX
    /**
    * The sound effects emitted by the enemy. Use the SFX_ constants in
    * std.zh to set or compare this value.
    */

/************************************************************************************************************/

    int Extend;         ZASM Instruction:
                    NPCEXTEND
    /**
    * Whether to extend the sprite of the enemy.
    */

/************************************************************************************************************/

    int TileWidth;          ZASM Instruction:
                    NPCTXSZ
    /**
    * The number of tile columns composing the sprite.
    * Writing to this is ignored unless Extend is set to values >=3.
    */

/************************************************************************************************************/

    int TileHeight;         ZASM Instruction:
                    NPCTYSZ
    /**
    * The number of tile rows composing the sprite.
    * Writing to this is ignored unless Extend is set to values >=3.
    */

/************************************************************************************************************/

    int HitWidth;           ZASM Instruction:
                    NPCHXSZ
    /**
    * The width of the sprite's hitbox, or collision rectangle.
    */

/************************************************************************************************************/

    int HitHeight;          ZASM Instruction:
                    NPCHYSZ
    /**
    * The height of the sprite's hitbox, or collision rectangle.
    */

/************************************************************************************************************/

    int HitZHeight;         ZASM Instruction:
                    NPCHZSZ
    /**
    * The Z-axis height of the sprite's hitbox, or collision rectangle.
    * The greater it is, the higher Link must jump or fly over the sprite to avoid taking damage.
    * To jump over a sprite, you must be higher than its Z + HitZHeight.
    * The values of DrawZOffset and HitZHeight are linked. Setting one, also sets the other.
    */

/************************************************************************************************************/

    int HitXOffset;         ZASM Instruction:
                    NPCHXOFS
    /**
    * The X offset of the sprite's hitbox, or collision rectangle.
    * Setting it to positive or negative values will move the sprite's hitbox left or right.
    */

/************************************************************************************************************/

    int HitYOffset;         ZASM Instruction:
                    NPCHYOFS
    /**
    * The Y offset of the sprite's hitbox, or collision rectangle.
    * Setting it to positive or negative values will move the sprite's hitbox up or down.
    */

/************************************************************************************************************/

    int DrawXOffset;        ZASM Instruction:
                    NPCXOFS
    /**
    * The X offset of the sprite.
    * Setting it to positive or negative values will move the sprite's tiles left or right relative to its position.
    */

/************************************************************************************************************/

    int DrawYOffset;        ZASM Instruction:
                    NPCYOFS
    /**
    * The Y offset of the sprite. In non-sideview screens, this is usually -2.
    * Setting it to positive or negative values will move the sprite's tiles up or down relative to its position.
    */

/************************************************************************************************************/

    int DrawZOffset;        ZASM Instruction:
                    NPCZOFS
    /**
    * The Z offset of the sprite. This is ignored unless Extend is set to values >=3.
    * The values of DrawZOffset and HitZHeight are linked. Setting one, also sets the other.
    */

/************************************************************************************************************/

    int Defense[];          ZASM Instruction:
                    NPCDEFENSED
    /**
    * The npc's Defense values, as an array of 18 integers. Use the NPCD_ and NPCDT_ constants
    * in std.zh to set or compare these values.
    */

/************************************************************************************************************/

    int ScriptDefense[];        ZASM Instruction:
                    NPCSCRDEFENSED
    /**
    * The npc's Script Weapon Defense values, as an array of 10 integers. Use the NPCSD_ and NPCDT_ constants
    * in std.zh to set or compare these values.
    */

/************************************************************************************************************/

    int Attributes[];       ZASM Instruction:
                    NPCDD
    /**
    * The npc's Miscellaneous Attributes, as an array of ten integers.
    * They are read-only; while setting them is not syntactically incorrect, it does nothing.
    */

/************************************************************************************************************/

    int MiscFlags;          ZASM Instruction:
                    NPCMFLAGS
    /**
    * The npc's Misc. Flags as 14 bits ORed together, starting with 'Damaged by Power 0 Weapons',
    * and working down the flags in the order they are shown in the Enemy Editor.
    * npc->MiscFlags is read-only; while setting it is not syntactically incorrect, it does nothing.
    * If you are not comfortable with binary operations, you can use 'GetNPCMiscFlag' from std.zh
    */

/************************************************************************************************************/

    float Misc[32];         ZASM Instruction:
                    NPCMISCD
    /**
    * An array of 32 miscellaneous variables for you to use as you please.
    */

/************************************************************************************************************/

    void BreakShield();     ZASM Instruction:
                    BREAKSHIELD
    /**
    * Breaks the enemy's shield if it has one. This works even if the flag
    * "Hammer Can Break Shield" is not checked.
    */


/************************************************************************************************************/
/************************************************************************************************************/




//======================================
//--- Weapon Functions and Variables ---
//======================================

                                        class weapon


    //! ZScript supports two different weapon classes:
    //! The lweapon class is used for Link's weapons (that damage enemies, and trigger objects)
    //! while the eweapon class is used for enemy weapons, that can damage Link.
    //!
    //! Both the lweapon, and the eweapon class have all of the following atributes:

    bool isValid();         ZASM Instruction:
                    ISVALIDLWPN
                    ISVALIDEWPN

    /**
    * Returns whether this weapon pointer is still valid. A weapon pointer
    * becomes invalid when the weapon fades away or disappears
    * or Link leaves the screen. Accessing any variables using an
    * invalid weapon pointer prints an error message to allegro.log and
    * does nothing.
    */ Example Use: !#!

/************************************************************************************************************/

    void UseSprite(int id);     ZASM Instruction:
                    LWPNUSESPRITER, LWPNUSESPRITEV
                    EWPNUSESPRITER, EWPNUSESPRITEV

    /**
    * Reads a 'Weapons/Misc' sprite entry in your quest file, and assigns
    * the OriginalTile, Tile, OriginalCSet, CSet, FlashCSet, NumFrames,
    * Frame, ASpeed, Flip and Flash variables of this weapon based on
    * this entry's data. Passing negative values, and values greater than
    * 255, will do nothing.
    */ Example Use: !#!

/************************************************************************************************************/

    bool Behind;            ZASM Instruction:
                    LWPNBEHIND
                    EWPNBEHIND

    /**
    * Ensures that the weapon's graphic is drawn behind Link and enemies.
    */ Example Use: !#!

/************************************************************************************************************/

    int ID;             ZASM Instruction:
                    LWPNID
                    EWPNID

    /**
    * The weapon's ID number. Use the LW_ or EW_ constants to compare
    * this value. The effect of writing to this field is currently undefined.
    */ Example Use: !#!

/************************************************************************************************************/

    int X;              ZASM Instruction:
                    LWPNX
                    EWPNX

    /**
    * The weapon's X position on the screen, in pixels. Float values passed
    * to this will be cast to int.
    */ Example Use: !#!

/************************************************************************************************************/

    int Y;              ZASM Instruction:
                    LWPNY
                    EWPNY

    /**
    * The weapon's Y position on the screen, in pixels. Float values passed
    * to this will be cast to int.
    */ Example Use: !#!

/************************************************************************************************************/

    int Z;              ZASM Instruction:
                    LWPNZ
                    EWPNZ

    /**
    * The weapon's Z position on the screen, in pixels. Float values passed
    * to this will be cast to int.
    */ Example Use: !#!

/************************************************************************************************************/

    int Jump;           ZASM Instruction:
                    LWPNJUMP
                    EWPNJUMP

    /**
    * The weapon's falling speed on the screen. Bombs, Bait and
    * Fire obey gravity.
    */ Example Use: !#!

/************************************************************************************************************/

    int DrawStyle;          ZASM Instruction:
                    LWPNDRAWTYPE
                    EWPNDRAWTYPE

    /**
    * An integer representing how the weapon is to be drawn. Use one of the
    * DS_ constants in std.zh to set or compare this value.
    */ Example Use: !#!

/************************************************************************************************************/

    int Dir;            ZASM Instruction:
                    LWPNDIR
                    eWPNDIR

    /**
    * The direction that the weapon is facing. Used by certain weapon types
    * to determine movement, shield deflection and such.
    */ Example Use: !#!

/************************************************************************************************************/

    int OriginalTile;       ZASM Instruction:
                    LWPNOTILE
                    EWPNOTILE

    /**
    * The starting tile of the weapon's animation.
    */ Example Use: !#!

/************************************************************************************************************/

    int Tile;           ZASM Instruction:
                    LWPNTILE
                    EWPNTILE

    /**
    * The current tile associated with this weapon.
    */ Example Use: !#!

/************************************************************************************************************/

    int OriginalCSet;       ZASM Instruction:
                    LWPNOCSET
                    EWPNOCSET

    /**
    * The starting CSet of the weapon's animation.
    */ Example Use: !#!

/************************************************************************************************************/

    int CSet;           ZASM Instruction:
                    LWPNCSET
                    EWPNCSET

    /**
    * This weapon's current CSet.
    */ Example Use: !#!

/************************************************************************************************************/

    int FlashCSet;          ZASM Instruction:
                    LWPNFLASHCSET
                    EWPNFLASHCSET

    /**
    * The CSet used during this weapon's flash frames, if this weapon flashes.
    */ Example Use: !#!

/************************************************************************************************************/

    int NumFrames;          ZASM Instruction:
                    LWPNFRAMES
                    EWPNFRAMES

    /**
    * The number of frames in this weapon's animation.
    */ Example Use: !#!

/************************************************************************************************************/

    int Frame;          ZASM Instruction:
                    LWPNFRAME
                    EWPNFRAME

    /**
    * The weapon's current animation frame.
    */ Example Use: !#!

/************************************************************************************************************/

    int ASpeed;         ZASM Instruction:
                    LWPNASPEED
                    EWPNASPEED

    /**
    * The speed at which this weapon animates, in screen frames.
    */ Example Use: !#!

/************************************************************************************************************/

    int Damage;         ZASM Instruction:
                    LWPNPOWER
                    EWPNPOWER

    /**
    * The amount of damage that this weapon causes to Link/an enemy upon contact.
    */ Example Use: !#!

/************************************************************************************************************/

    int Step;           ZASM Instruction:
                    LWPNSTEP
                    EWPNSTEP

    /**
    * Usually associated with the weapon's velocity. A Step of 100
    * typically means that the weapon moves at approximately one pixel
    * per animation frame.
    */ Example Use: !#!

/************************************************************************************************************/

    int Angle;          ZASM Instruction:
                    LWPNANGLE
                    EWPNANGLE

    /**
    * The weapon's current angle in clockwise radians; used by certain weapon
    * types with angular movement. 0 = right, PI/2 = down, etc. Note: if you
    * want Link's shield to interact with the weapon correctly, you must set
    * its Dir to a direction that approximates this angle.
    */ Example Use: !#!

/************************************************************************************************************/

    bool Angular;           ZASM Instruction:
                    LWPNANGULAR
                    EWPNANGULAR

    /**
    * Specifies whether a weapon has angular movement.
    */ Example Use: !#!

/************************************************************************************************************/

    bool CollDetection;     ZASM Instruction:
                    LWPNCOLLDET
                    EWPNCOLLDET

    /**
    * Whether the weapon will use the system's code to work out collisions with
    * Link and/or enemies (depending on weapon type). Initialised as 'true'.
    */ Example Use: !#!

/************************************************************************************************************/

    int DeadState;          ZASM Instruction:
                    LWPNDEAD
                    EWPNDEAD

    /**
    * The current state of the weapon. Important to keep track of. A value of
    * -1 indicates that it is active, and moves according to the weapon's
    * Dir, Step, Angular, and Angle values. Use -1 if you want the engine to
    * handle movement and collision. Use any value below -1 if you want a
    * dummy weapon that you can control on your own.
    *
    * Given a deadstate value of -10, a weapon will turn of its collision
    * detection and movement. If it has a positive value, it will
    * decrement once per frame until it equals 0, whereupon the weapon is
    * removed. If you want to remove the weapon, write one of the WDS_
    * constants in std.zh (appropriate for the weapon) to this variable.
    *
    * Weapons with the type *_SPARKLE have a DeadState equal to the number
    * of frames in their sprite animation, when created.
    */ Example Use: !#!

/************************************************************************************************************/

    bool Flash;         ZASM Instruction:
                    LWPNFLASH
                    EWPNFLASH

    /**
    * Whether or not the weapon flashes. A flashing weapon alternates between
    * its CSet and its FlashCSet.
    */ Example Use: !#!

/************************************************************************************************************/

    int Flip;           ZASM Instruction:
                    LWPNFLIP
                    EWPNFLIP

    /**
    * Whether and how the weapon's tiles should be flipped.
    * 0: No flip
    * 1: Horizontal flip
    * 2: Vertical flip
    * 3: Both (180 degree rotation)
    */ Example Use: !#!

/************************************************************************************************************/

    int Extend;         ZASM Instruction:
                    LWPNEXTEND
                    EWPNEXTEND

    /**
    * Whether to extend the sprite of the weapon.
    */ Example Use: !#!

/************************************************************************************************************/

    int TileWidth;          ZASM Instruction:
                    LWPNTXSZ
                    EWPNTXSZ

    /**
    * The number of tile columns composing the sprite.
    * Writing to this is ignored unless Extend is set to values >=3.
    */ Example Use: !#!

/************************************************************************************************************/

    int TileHeight;         ZASM Instruction:
                    LWPNTYSZ
                    EWPNTYSZ

    /**
    * The number of tile rows composing the sprite.
    * Writing to this is ignored unless Extend is set to values >=3.
    */ Example Use: !#!

/************************************************************************************************************/

    int HitWidth;           ZASM Instruction:
                    LWPNHXSZ
                    EWPNHXSZ

    /**
    * The width of the sprite's hitbox, or collision rectangle.
    */ Example Use: !#!

/************************************************************************************************************/

    int HitHeight;          ZASM Instruction:
                    LWPNHYSZ
                    WEPNHYSZ

    /**
    * The height of the sprite's hitbox, or collision rectangle.
    */ Example Use: !#!

/************************************************************************************************************/

    int HitZHeight;         ZASM Instruction:
                    LWPNHZSZ
                    EWPNHZSZ

    /**
    * The Z-axis height of the sprite's hitbox, or collision rectangle.
    * The greater it is, the higher Link must jump or fly over the sprite
    * To jump over a sprite, you must be higher than its Z + HitZHeight.
    * The values of DrawZOffset and HitZHight are linked. Setting one, also sets the other.
    * to avoid taking damage.
    */ Example Use: !#!

/************************************************************************************************************/

    int HitXOffset;         ZASM Instruction:
                    LWPNHXOFS
                    EWPNHXOFS

    /**
    * The X offset of the sprite's hitbox, or collision rectangle.
    * Setting it to positive or negative values will move the sprite's
    * hitbox left or right.
    */ Example Use: !#!

/************************************************************************************************************/

    int HitYOffset;         ZASM Instruction:
                    LWPNHYOFS
                    EWPNHYOFS

    /**
    * The Y offset of the sprite's hitbox, or collision rectangle.
    * Setting it to positive or negative values will move the sprite's
    * hitbox up or down.
    */ Example Use: !#!

/************************************************************************************************************/

    int DrawXOffset;        ZASM Instruction:
                    LWPNXOFS
                    EWPNXOFS

    /**
    * The X offset of the sprite.
    * Setting it to positive or negative values will move the sprite's
    * tiles left or right relative to its position.
    */ Example Use: !#!

/************************************************************************************************************/

    int DrawYOffset;        ZASM Instruction:
                    LWPNYOFS
                    EWPNYOFS

    /**
    * The Y offset of the sprite.
    * Setting it to positive or negative values will move the sprite's
    * tiles up or down relative to its position.
    */ Example Use: !#!

/************************************************************************************************************/

    int DrawZOffset;        ZASM Instruction:
                    LWPNZOFS
                    EWPNZOFS

    /**
    * The Z offset of the sprite.
    * The values of DrawZOffset and HitZHeight are linked. Setting one, also sets the other.
    */ Example Use: !#!

/************************************************************************************************************/

    float Misc[32];         ZASM Instruction:
                    LWPNMISCD
                    EWPNMISCD

    /**
    * An array of 32 miscellaneous variables for you to use as you please.
    */ Example Use: !#!


/************************************************************************************************************/
/************************************************************************************************************/

//====================================
//--- Item Functions and Variables ---
//====================================

                                        class item


    bool isValid();         ZASM Instruction:
                    ISVALIDITEM

    /**
    * Returns whether this item pointer is still valid. An item pointer
    * becomes invalid when Link picks up the item, the item fades away,
    * or Link leaves the screen. Accessing any variables using an
    * invalid item pointer prints an error message to allegro.log and
    * does nothing.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int X;              ZASM Instruction:
                    ITEMX

    /**
    * The item's X position on the screen, in pixels. Float values passed to this will be cast to int.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int Y;              ZASM Instruction:
                    ITEMY
    /**
    * The item's Y position on the screen, in pixels. Float values passed to this will be cast to int.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int Jump            ZASM Instruction:
                    ITEMJUMP

    /**
    * The item's upward velocity, in pixels. If negative, the item will fall.
    * The downward acceleration of Gravity (in Init Data) modifies this value every frame.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int DrawStyle;          ZASM Instruction:
                    ITEMDRAWTYPE
    /**
    * An integer representing how the item is to be drawn. Use one of the
    * DS_ constants in std.zh to set or compare this value.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int ID;             ZASM Instruction:
                    ITEMID
    /**
    * This item's ID number. Use the I_ constants to compare this value. The effect of writing to this field is currently undefined.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int OriginalTile;       ZASM Instruction:
                    ITEMOTILE
    /**
    * The starting tile of the item's animation.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int Tile;           ZASM Instruction:
                    ITEMTILE
    /**
    * The current tile associated with this item.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int CSet;           ZASM Instruction:
                    ITEMCSET
    /**
    * This item's CSet.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int FlashCSet;          ZASM Instruction:
                    ITEMFLASHCSET
    /**
    * The CSet used during this item's flash frames, if this item flashes.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int NumFrames;          ZASM Instruction:
                    ITEMFRAMES
    /**
    * The number of frames in this item's animation.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int Frame;          ZASM Instruction:
                    ITEMFRAME
    /**
    * The tile that is this item's current animation frame.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int ASpeed;         ZASM Instruction:
                    ITEMASPEED
    /**
    * The speed at which this item animates, in screen frames.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int Delay;          ZASM Instruction:
                    ITEMDELAY
    /**
    * The amount of time the animation is suspended after the last frame,
    * before the animation restarts, in item frames. That is, the total
    * number of screen frames of extra wait is Delay*ASpeed.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    bool Flash;         ZASM Instruction:
                    ITEMFLASH
    /**
    * Whether or not the item flashes. A flashing item alternates between
    * its CSet and its FlashCSet.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int Flip;           ZASM Instruction:
                    ITEMFLIP

    /**
    * Whether and how the item's tiles should be flipped.
    * 0: No flip
    * 1: Horizontal flip
    * 2: Vertical flip
    * 3: Both (180 degree rotation)
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int Pickup;         ZASM Instruction:
                    ITEMPICKUP
    /**
    * The pickup flags of the item, which determine what happens when Link
    * picks up the item. Its value consists of flags OR'd (|) together; use
    * the IP_ constants in std.zh to set or compare these values.
    * A special note about IP_ENEMYCARRIED: if the Quest Rule "Hide Enemy-
    * Carried Items" is set, then an item carried by an enemy will have its
    * X and Y values set to -128 while the enemy is carrying it. If this
    * flag is removed from such an item, then it will be moved to the enemy's
    * on-screen location.
    * If you are not comfortable with performing binary operations, use the ItemPickup functions from std.zh.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int Extend;         ZASM Instruction:
                    ITEMEXTEND
    /**
    * Whether to extend the sprite of the item.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int TileWidth;          ZASM Instruction:
                    !
    /**
    * The number of tile columns composing the sprite.
    * Writing to this is ignored unless Extend is set to values >=3.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int TileHeight;         ZASM Instruction:
                    !
    /**
    * The number of tile rows composing the sprite.
    * Writing to this is ignored unless Extend is set to values >=3.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int HitWidth;           ZASM Instruction:
                    ITEMHSXZ
    /**
    * The width of the sprite's hitbox, or collision rectangle.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int HitHeight;          ZASM Instruction:
                    ITEMHYSZ
    /**
    * The height of the sprite's hitbox, or collision rectangle.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int HitZHeight;         ZASM Instruction:
                    ITEMHXSZ
    /**
    * The Z-axis height of the sprite's hitbox, or collision rectangle.
    * The greater it is, the higher Link must jump or fly over the sprite to avoid picking up the item.
    * To jump over a sprite, you must be higher than its Z + HitZHeight.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int HitXOffset;         ZASM Instruction:
                    ITEMHXOFS
    /**
    * The X offset of the sprite's hitbox, or collision rectangle.
    * Setting it to positive or negative values will move the sprite's hitbox left or right.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int HitYOffset;         ZASM Instruction:
                    ITEMHYOFS
    /**
    * The Y offset of the sprite's hitbox, or collision rectangle.
    * Setting it to positive or negative values will move the sprite's hitbox up or down.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int DrawXOffset;        ZASM Instruction:
                    ITEMXOFS
    /**
    * The X offset of the sprite.
    * Setting it to positive or negative values will move the sprite's tiles left or right relative to its position.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int DrawYOffset;        ZASM Instruction:
                    ITEMYOFS
    /**
    * The Y offset of the sprite.
    * Setting it to positive or negative values will move the sprite's tiles up or down relative to its position.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int DrawZOffset;        ZASM Instruction:
                    ITEMZOFS
    /**
    * The Z offset of the sprite.
    * The values of DrawZOffset and HitZHeight are linked. Setting one, also sets the other.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    float Misc[32];         ZASM Instruction:
                    ITEMMISCD
    /**
    * An array of 32 miscellaneous variables for you to use as you please.
    * Note that lweapons and eweapons possess exactly the same attributes,
    * although their designation affects how they are treated by the engine.
    * The values here correspond to both the lweapon and eweapon type.
    *
    */ Example Use: !#!


/************************************************************************************************************/
/************************************************************************************************************/


//=========================================
//--- Itemdata Functions and Variables ---
//=========================================

    //! You may reference itemdata variables via item scripts, using the 'this' pointer.

                                        class itemdata
    int ID;         ZASM Instruction:
                    IDATAID
    /**
    * Returns the item number of the item in question.
    * Can be called with this->ID in item scripts.
    */ Example Use: !#!

/************************************************************************************************************/

    int Modifier;           ZASM Instruction:
                    IDATALTM
    /**
    * The Link Tile Modifier
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int Tile;           ZASM Instruction:
                    IDATATILE
    /**
    * The tile used by the item.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int CSet;           ZASM Instruction:
                    IDATAID
    /**
    * The CSet of the tile used by the item.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int Flash;          ZASM Instruction:
                    IDATAFLASH
    /**
    * The Flash value for the CSet
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int AFrames;            ZASM Instruction:
                    IDATAFRAMES
    /**
    * The number of animation frames in the item's tile animation.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int ASpeed;         ZASM Instruction:
                    IDATAASPEED
    /**
    * The speed of the item's animation.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int Delay;          ZASM Instruction:
                    IDATADELAY
    /**
    * The Delay value, before the animation begins.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int Script;         ZASM Instruction:
                    IDATAID
    /**
    * The Action Script for the item.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int PScript;            ZASM Instruction:
                    IDATAID
    /**
    * The Pickup Script for the item.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int MagicCost;          ZASM Instruction:
                    IDATAID
    /**
    * The item's maic (or rupees, if this is set) cost.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int MinHearts;          ZASM Instruction:
                    IDATAID
    /**
    * The minimum number of hearts required to pick up the item.
    *
    */ Example Use: !#!

/************************************************************************************************************/

bool Combine;               ZASM Instruction:
                    IDATACOMBINE
    /**
    * Corresponds to 'Upgrade when collected twice'.
    *
    */ Example Use: !#!

/************************************************************************************************************/

bool Downgrade;             ZASM Instruction:
                    IDATADOWNGRADE
    /**
    * Corresponds to the 'Remove When Used' option on the Action tab of the item editor.
    *
    */ Example Use: !#!

/************************************************************************************************************/

bool KeepOld;               ZASM Instruction:
                    IDATAKEEPOLD
    /**
    * Corresponds to 'Keep lower level items on the Pickup tab of the item editor.
    * NOTE: Not to be confused with 'Keep', which corresponds to the 'Equipment Item' box.
    *
    */ Example Use: !#!

/************************************************************************************************************/

bool RupeeCost;             ZASM Instruction:
                    IDATARUPEECOST
    /**
    * Corresponds to the 'Use Rupees Instead of Magic' option on the item editor 'Action' tab.
    *
    */ Example Use: !#!

/************************************************************************************************************/

bool Edible;                ZASM Instruction:
                    IDATAEDIBLE
    /**
    * Corresponds to the 'Can be Eaten by Enemies' box on the Pickup tab of the item editor.
    *
    */ Example Use: !#!

/************************************************************************************************************/

bool GainLower;             ZASM Instruction:
                    IDATAGAINLOWER
    /**
    * Corresponds to the 'Gain All Lower Level Items' box on the Pickup tab of the item editor.
    *
    */ Example Use: !#!

/************************************************************************************************************/

bool Flag1;             ZASM Instruction:
                    IDATAFLAG1
    /**
    * Multipurpose Flag 1
    *
    * The properties of this flag change based on the item class (family).
    * This corresponds to the box directly below 'Equiment Item'.
    * For swords, this is 'B.H. is Percent'.
    * Scripted item classes may make use of this as a general-purpose 'Script 1' flag.
    * See 'zscript_itemdata.txt' for more information on what this flag does, based on the item class.
    *
    */ Example Use: !#!

/************************************************************************************************************/

bool Flag2;             ZASM Instruction:
                    IDATAFLAG2
    /**
    * Multipurpose Flag 2
    *
    * The properties of this flag change based on the item class (family).
    * This corresponds to the box directly below 'Flag 1, or two boxes down from 'Equiment Item'.
    * For swords, this is 'B.D. is Percent'.
    * Scripted item classes may make use of this as a general-purpose 'Script 2' flag.
    * See 'zscript_itemdata.txt' for more information on what this flag does, based on the item class.
    *
    */ Example Use: !#!

/************************************************************************************************************/

bool Flag3;             ZASM Instruction:
                    IDATAFLAG3
    /**
    * Multipurpose Flag 3
    *
    * The properties of this flag change based on the item class (family).
    * This corresponds to the box directly right of 'Equiment Item'.
    * For swords, this is 'B.  Penetrates Enemies'.
    * Scripted item classes may make use of this as a general-purpose 'Script 3' flag.
    * See 'zscript_itemdata.txt' for more information on what this flag does, based on the item class.
    *
    */ Example Use: !#!

/************************************************************************************************************/

bool Flag4;             ZASM Instruction:
                    IDATAFLAG4
    /**
    * Multipurpose Flag 4
    *
    * The properties of this flag change based on the item class (family).
    * This corresponds to the box directly right of 'Flag 2'.
    * For swords, this is 'Can Slash'.
    * Scripted item classes may make use of this as a general-purpose 'Script 4' flag.
    * See 'zscript_itemdata.txt' for more information on what this flag does, based on the item class.
    *
    */ Example Use: !#!

/************************************************************************************************************/

bool Flag5;             ZASM Instruction:
                    IDATAFLAG5
    /**
    * Multipurpose Flag 5
    *
    * The properties of this flag change based on the item class (family).
    * This corresponds to the box directly below 'Flag 4'.
    * For swords, this is '<Unused>', and greyed out.
    * Scripted item classes may make use of this as a general-purpose 'Script 5' flag.
    * See 'zscript_itemdata.txt' for more information on what this flag does, based on the item class.
    *
    */ Example Use: !#!

/************************************************************************************************************/

bool Unused;                ZASM Instruction:
                    IDATAFLAGUNUSED
    /**
    * ? - An extra script-only flag. It's a mystery to everyone.
    * Likely best left unused in the event that we need to reserve it.
    *
    */ Example Use: !#!

/************************************************************************************************************/

    float InitD[];          ZASM Instruction:
                    IDATAINITDD
    /**
    * The original values of the item's 8 'D#' input values are they are stored in the
    * .qst file, regardles of whether they have been modified by ZScript.
    */ Example Use: !#!

/************************************************************************************************************/

    void GetName(int buffer[]); ZASM Instruction:
                    !
    /**
    * Loads the item this itemdata is attributed to's name into 'buffer'
    */ Example Use: !#!

/************************************************************************************************************/

    int Family;         ZASM Instruction:
                    IDATAFAMILY
    /**
    * The kind of item to which this class belongs (swords, boomerangs,
    * potions, etc.) Use the IC_ constants in std.zh to set or compare this
    * value.
    */ Example Use: !#!

/************************************************************************************************************/

    int Level;          ZASM Instruction:
                    IDATALEVEL
    /**
    * The level of this item. Higher-level items replace lower-level items
    * when they are picked up.
    */ Example Use: !#!

/************************************************************************************************************/

    int Power;          ZASM Instruction:
                    IDATAPOWER
    /**
    * The item's power, for most items this is amount of damage dealt but is
    * used for other values in some items (ie. Roc's Feather)
    */ Example Use: !#!

/************************************************************************************************************/

    int Amount;         ZASM Instruction:
                    IDATAAMOUNT
    /**
    * Corresponds to the "Increase Amount" entry in the Item Editor.
    * The value of this data member can have two meanings:
    * If Amount & 0x8000 is 1, the drain counter for this item is set
    * to Amount & 0x3FFF. The game then slowly fills the counter of this item
    * (see Counter below) out of the drain counter. Gaining rupees uses the
    * drain counter, for example.
    * is set to Amount when the item is picked up.
    * If Amount & 0x8000 is 0, the counter of this item is increased, if
    * Amount & 0x4000 is 1, or decreased, if Amount & 0x4000 is 0, by
    * Amount & 0x3FFF when the item is picked up.
    */ Example Use: !#!

/************************************************************************************************************/

    int Max;            ZASM Instruction:
                    IDATAMAX
    /**
    * Corresponds to the "Full Max" entry in the Item Editor.
    * In conjunction with MaxIncrement (see below) this value controls how
    * the maximum value of the counter of this item (see Counter below) is
    * modified when the item is picked up. If MaxIncrement is nonzero at that
    * time, the counter's new maximum value is at that time set to the
    * minimum of its current value plus MaxIncrement, Max.
    * If Max is less than the current maximum of the counter, Max is ignored
    * and that maximum is used instead.
    * Notice that as a special case, if Max = MaxIncrement, the counter's
    * maximum value will be forced equal to Max.
    */ Example Use: !#!

/************************************************************************************************************/

    int MaxIncrement;       ZASM Instruction:
                    IDATASETMAX
    /**
    * Corresponds to the "+Max" entry in the Item Editor.
    * In conjunction with Max (see above) this value controls how the
    * maximum value of the counter of this item (see Counter below) is
    * modified when the item is picked up. If MaxIncrement is nonzero at that
    * time, the counter's new maximum value is at that time set to the
    * minimum of its current value plus MaxIncrement, and Max.
    * If Max is less than the current maximum of the counter, Max is ignored
    * and that maximum is used instead.
    */ Example Use: !#!

/************************************************************************************************************/

    bool Keep;          ZASM Instruction:
                    IDATAKEEP
    /**
    * Corresponds to the "Equipment Item" checkbox in the Item Editor.
    * If true, Link will keep the item, and it will show up as an item or
    * equipment in the subscreen. If false, it may modify the current value
    * or maximum value of its counter (see Counter below), then disappear.
    * The White Sword and Raft, for instance, have Keep true, and keys and
    * rupees have Keep false.
    */ Example Use: !#!

/************************************************************************************************************/

    int Counter;            ZASM Instruction:
                    IDATACOUNTER
    /**
    * Corresponds to the "Counter Reference" entry in the Item Editor.
    * The game counter whose current and modified values might be modified
    * when the item is picked up (see Amount, Max, and MaxIncrement above.)
    * Use the CT_ constants in std.zh to set or compare this value.
    */ Example Use: !#!

/************************************************************************************************************/

    int UseSound;           ZASM Instruction:
                    IDATAUSESOUND

    /**
    * Corresponds to the "Sound" entry on the action tab in the Item Editor.
    */ Example Use: !#!


/************************************************************************************************************/
    int Misc1, Misc2, Misc3, Misc4, Misc5, Misc6, Misc7, Misc8, Misc9, Misc10;
                    ZASM Instructions:
                    IDATAMISC1, IDATAMISC2, IDATAMISC3, IDATAMISC4, IDATAMISC5
                    IDATAMISC6, IDATAMISC7, IDATAMISC8, IDATAMISC9, IDATAMISC10
    /**
    * These correspond to the pull-down options in the item editor 'Data' tab.
    *
    * Example: For a Sword Misc1 is 'Beam hearts', and Misc2 is 'Beam .
    *
    */ Example Use: !#!

/************************************************************************************************************/

    int Attribute1, Attribute2, Attribute3, Attribute4, Attribute5, Attribute6,
        Attribute7, Attribute8, Attribute9, Attribute10;
                    ZASM Instructions:
                    IDATAWPN, IDATAWPN2, IDATAWPN3, IDATAWPN4, IDATAWPN5
                    IDATAWPN6, IDATAWPN7, IDATAWPN8, IDATAWPN9, IDATAWPN10
    /**
    * These correspond to the pull-down options in the item editor 'Action' tab.
    *
    * Example: For a Sword Attribute1 is 'Sprite', Attribute 2 is 'Slash sprite'
    * and Attribute 3 is 'Beam sprite'.
    *
    */ Example Use: !#!

/************************************************************************************************************/
/************************************************************************************************************/


//////////////////////
/// Array Building ///
//////////////////////


//////////////////////////////////////
/// Poke, or Peek at Memory Values ///
/////////////////////////////////////////////////////////////////////////////////////////////////////////
/// The following functions are used by ZScript to build arrays, and move data between the registers  ///
/// that hold them, and generally interpret the values in registers for using arrays.                 ///
/////////////////////////////////////////////////////////////////////////////////////////////////////////
/// When an array is declared in ZScript, the following commands are used to create it,               ///
/// and store its values:                                                                             ///
///                                                                                                   ///
/// Creating arrays (global):                                                                         ///
///                                                                                                   ///
/// int arr[16];                                                                                      ///
/// int x;                                                                                            ///
///                                                                                                   ///
/// ZASM Output:                                                                                      ///
/// ALLOCATEGMEMV d2,16 : allocates 16 indices to d2                                                  ///
/// SETR gd1,d2 : assigns the register d2 to global register gd1                                      ///
/// SETV gd2,0                                                                                        ///
///                                                                                                   ///
/////////////////////////////////////////////////////////////////////////////////////////////////////////
/// When an array is accessed, and the value of an index read, these instructions:                    ///
///                                                                                                   ///
/// int x;                                                                                            ///
/// int arr[16];                                                                                      ///
/// x = arr[2];                                                                                       ///
///                                                                                                   ///
/// ZASM Output:                                                                                      ///
///                                                                                                   ///
/// SETV d2,0 : Clear expression axcumulator #1                                                       ///
/// PUSHR d3 : Push expression accumulator #2                                                         ///
/// SETR d4,SP : Stack frame pointer to stack pointer.                                                ///
/// SETR d2,gd1 : Set the value of arr[] to the expression accumulator #1.                            ///
/// PUSHR d2 : Push the expression accumulaor #1                                                      ///
/// SETV d2,2 : Store the index we're reading in the expression accumulator #1                        ///
/// POP d0 : Pop the array index accumulator                                                          ///
/// SETR d1,d2 : Store the expression accumulator #1 into the secondary array index accumulator.      ///
/// SETR d2,GLOBALRAM : Read the array values into the expression accumulator #1                      ///
/// SETR gd2,d2 : Store the value of the inex into x.                                                 ///
/// SETV d3,0 : Clear the secondary expression accumulator.                                           ///
///                                                                                                   ///
/////////////////////////////////////////////////////////////////////////////////////////////////////////
/// When the values in an array are modified, these instructions:                                     ///
///                                                                                                   ///
/// arr[2] = 6;                                                                                       ///
///                                                                                                   ///
/// ZASM Output:                                                                                      ///
///                                                                                                   ///
/// SETV d2,0 : Clear expression accumulator #1                                                       ///
/// PUSHR d3 : Push expression accumulator #2                                                         ///
/// SETR d4,SP :  Stack frame pointer to stack pointer.                                               ///
/// SETV d2,6 : Set expression accumulator #1 to a value of 6                                         ///
/// SETR d0,gd1 : Prep the array index accumulator with the array stored in gd1                       ///
/// SETR d5,d2 : Sink the value in d2                                                                 ///
/// PUSHR d0 : Push the array index accumulator.                                                      ///
/// SETV d2,2 : Store the index to modify in The expression accumulator #1                            ///
/// POP d0 : Pop off the array index accumulator                                                      ///
/// SETR d1,d2 : Assign the value of the expression accumulator #1 to the                             ///
///        : secondary array index accumulator.                                                   ///
/// SETR GLOBALRAM,d5 : Store the value.                                                              ///
/// SETV d3,0 : Clear the expression accumulaTor #2                                                   ///
/////////////////////////////////////////////////////////////////////////////////////////////////////////
/// Using these, it would be possible to generate your own array handling routines.                   ///
/////////////////////////////////////////////////////////////////////////////////////////////////////////
/// Global arrays are allocated in the REVERSE order of DECLARATION!                                  ///
/////////////////////////////////////////////////////////////////////////////////////////////////////////

// Peek at RAM value in a global address.

void GetGlobalRAM(int register)     ZASM Instruction:
                    GLOBALRAMD
Example Use:
    Game->GetGlobalRAM(10)
    Returns the value in gd10

/************************************************************************************************************/

// POKE value into Global address

void SetGlobalRAM(int register, int value)  ZASM Instruction:
                        GLOBALRAMD<><>
Example Use:
    Game->SetGlobalRAM(10,6)
    Sets gd10 to a value of '6'.

/************************************************************************************************************/

//Peek at register value of specific script address.
void GetScriptRAM(int register)         ZASM Instruction:
                        SCRIPTRAMD<>
Example Use:
    Game->GetScriptRAM(4)
    Returns the value of Script RAM register 4.

/************************************************************************************************************/

//POKE Vakue into Script RAM address
void SetScriptRAM(int register, int value)  ZASM Instruction:
                        SCRIPTRAMD<><>
Example Use:
    Game->SetScriptRAM(4,12)
    Sets script RAM register 4 to a value of '12'

/************************************************************************************************************/


///////////////////////////////////////
/// Misc ZASM-Specific Instructions ///
///////////////////////////////////////

GOTO<><>
GOTOTRUE<><>
GOTOFALSE<><>
GOTOLESS<><>
GOTOMORE<><>
POP<>
PUSHR<>
PUSHV<>
ENQUEUER<><>
ENQUEUEV<><>
DEQUEUE<>
GOTOR<>
LOADI<><>
STOREI<><>
LOOP<><>
MODR<><>
MODV<><>
CHECKTRIG
COMPOUNDR<>
COMPOUNDV<>
FLIPROTTILEVV<><>
FLIPROTTILERR<><>
FLIPROTTILERV<><>
FLIPROTTILEVR<><>

/* These may not be implemented.
    GETTILEPIXELV<>
    GETTILEPIXELR<>
    SETTILEPIXELV<>
    SETTILEPIXELC<>

    SHIFTTILEVV<><>
    SHIFTTILEVR<><>
    SHIFTTILERR<><>
    SHIFTTILERV<><>
*/


/* Handles array data allocation.
    ALLOCATEMEMR<><>
    ALLOCATEMEMV<><>
    ALLOCATEMGEMR<><>
    ALLOCATEMGEMV<><>
*/

/************************************************************************************************************/

ZASM Register Reservations

Name        Register        Use
SP
    stack pointer
D4
    stack frame pointer
D6
    stack frame offset accumulator
D2
    expression accumulator #1
D3
    expression accumulator #2
D0
    array index accumulator
D1
    secondary array index accumulator
D5
    pure SETR sink


//Unimplemented ZASM Instructions
GETTILEPIXEL
SETTILEPIXEL
FLIPROTATETILE
SHIFTTILE

//partially Implemented ZASM

OVERLAYTILE : Supports 8-bit mode tiles only. May support 4-bit only in CSet 0

************************************
Misc ZASM

LOADI   LoadIndirect
STOREI  StoreIndirect


////////////////////
/// Undocumented ///
////////////////////

The following are unsupported, and unfinished ZScript functions.
 * While calling them is not while setting it is not syntactically incorrect, it does nothing.

void SetColorBuffer(    int amount, int offset,     ZASM Instruction:
            int stride, int *ptr )      SETCOLORB

Opcode: OSetColorBufferRegister()
Example Use:

/************************************************************************************************************/

void GetColorBuffer(    int amount, int offset,     ZASM Instruction:
            int stride, int *ptr )      GETCOLORB

Opcode: OGetColorBufferRegister();
Exaple Use:

/************************************************************************************************************/

void SetDepthBuffer(    int amount, int offset,     ZASM Instruction:
            int stride, int *ptr )      SETDEPTHB

Opcode: OSetDepthBufferRegister();
Example Use:

/************************************************************************************************************/

void GetDepthBuffer(    int amount, int offset,     ZASM Instruction:
            int stride, int *ptr )      GETDEPTHB

Opcode: OGetDepthBufferRegister();
Example use:

/************************************************************************************************************/

Undocumented / ZASM Exclusive

FLOODFILL

//////////////////////////////////////////////
/// System Limitations, Minimums, Maximums ///
//////////////////////////////////////////////

     Maximum numeric literal: 214747.9999

Ints, Floats, Arrays

    Maximum float: -214747.9999 to 214747.9999
    Maximum int -214747 to 214747
    Maximum array size (number of indices): 214747

    * This further includes arrays with a type of npc, leweapon, eweapon, item, and itemdata.
    Maximum value in an array index: Same as float, or int; based on type declaration.
    Maximum size of string index: 214747
    Maximum string length: 214747
    Maximum simultaneous arrays in operation: 4095

Counters, Tiles, Combos, Strings

    Maximum Tiles: 65519
    Maximum Combos: 65279
    Maximum Counter Value: 0 to 32767
    Maximum strings in string editor: ( 65519 )

    Largest tile ID (ZQ Editors): 32767 ?

    The largest value that can be referenced in the ZQ item, enemy, and other editors.

                --> I seem to remember a problem calling high values.

Pointers and Objects

    Maximum number of item pointers (on-screen items) at any one time: 255
    Maximum number of lweapon pointers (on-screen lweapons) at any one time: 255
    Maximum number of eweapon pointers (on-screen eweapons) at any one time: 255
    Maximum number of npc pointers (on-screen NPCs) at any one time: 255
    Maximum number of ffc (on-screen FFCs) pointers at any one time: 32
    Array Pointers (maximum number of arrays in operation): 4095

    Maximum total (cumulative) number of 'object' pointers at any one time: 1020
        * 255 each, npc, lweapon, eweapon, item + 32 (ffcs)

    --> ZC separates pointers by class. All pointers are stored in vectors, with pointer IDs ranging from 1 to 255.

    Maximum Z Height of a Screen Object (npc, weapon, item) or Link: 32767. Values above this wrap to -32767, which is reset to 0 every frame.

Compiler

    Maximum constants (any scope): Unlimited. (Constants are converted to their true value at compilation, and are not preserved by name.)
    Maximum global variables: 255*
    Maximum global functions: 4,294,967,295 (2^32-1).
        Note that this is limited by the filesystem, as each function requires its ASCII size in bytes,
        and is stored in the quest file. Many filesystems have a file size limit, that restricts it.
        At the smallest function size, max functions would use ~40GB of space.
        It is further restricted by the maximum buffer size at between 18MB and 22MB.

Script Drawing

    Maximum number of drawing commands per frame: 1000
    Maximum distance (x,y) for drawing, including off-screen areas (and bitmaps): -214747.9999 to 214747.9999 (X and Y)
    Maximum Z Height for 3D Drawing: 214747.9999

        --> Negative Z Height is effectively '0'.

Stack Operation

    Maximum number of concurrent stacks: ?
        --> Essentially, the maximum number of concurrent scripts; except that item scripts share one stack.

    Maximum variables in operation at any given time: 255* (gd1-gd255)
    Maximum variables per script: 255*
    Maximum function calls per script ( 127* )
    *Note: 255 variables will compile, but fail to run. A safe maximum is closer to 245, to allow instructions and function calls on the stack
    *Note: Both variables, and function calls share registers (global variables are gd registers), and thus cumulatively count against their combined caps (within a register type). See: ZASM_Registers
                --> How are these tabulated at compilation, and is there a strict ratio ( function call:variable ) ?
                --> Script-scope variables use gd registers. Thus, you need to retain free registers for scripts to run.

    Maximum script buffer size: ~18MB, including code imported with the 'import' directive.
                --> Maximum line count is also limited, but it is restricted by being a signed int.
                --> Thus, max line-count is somewhere around 2,147,483,647 lines, however,
                    this is still restricted by the 18MB buffer size.

    Maximum number of instructions: 2^32-1 * Max Scripts
    Maximum instructions per script: 4,294,967,295 (2^31 - 1)
    Maximum instructions per frame: Effectively unlimited, save by instructions per script.

    Maximum number of scripts ?
    Max ffc scripts at compilation ?
    Max Item scripts at compilation ?
    Max global scripts at compilation ?
                --> I know this is unlikely to ever be reached.

    Maximum function calls per script: Limited by maximum instructions, and available gd registers.
    Maximum local functions per script: ? Effectively unlimited, and tied to maximum functions (see above).

Maximum Values (Binary, Hex) for Use as Flags

    The largest literal that you can use as a flag, binary, is: 110100011010111101
        ( dec. 214717, hex 0x346BD )

    The largest true binary value (all ones) is 11111111111111111
        ( dec. 131071, hex 0x1FFFF )

    While these are certainly possible, the largest absolutely useful value, that maximises all places in
    both binary, and hex, and thus is the true flag maximum is: 65535 (decimal).
    This becomes 1111111111111111b, or 0XFFFF, which means that you may use each place to its full potential,
    at all times.

    Thus, the maximum useful flags are a width of 16-bit, and are represented below.

        Max Flag

        Binary               Hexadecimal    Decimal
        1111111111111111b    0XFFFF         65535


//! A list of all known system limitations.

################################
## COMPILER ERROR DEFINITIONS ##
################################
These errors are generated by the parser, during compilation.

Error codes are broken down by type:
P** Preprocessing errors.
S** Symbol table errors.
T** Type-checking errors.
G** Code Generation Errors
** Array Errors ---We need to change these to A**

Errors of each class are given unique numerical identifiers, ranging from 00 to 41, such as P01, or G33.
The letter code will give you an indication of the type of error, and the full code will give you specific details.

In ZQuest v2.50.2 and later, the compiler will report name of the script that generated (where possible).
This applies only to errors caused by scripts, and not errors at a 'global' level, such as global functions.
Thus, if you are using 2.50.2, or later, an error without a script name is likely to be caused at global scope.

#####################
## Specific Errors ##
##  Preprocessing  ##
#####################

P00: Can't open or parse input file!

Your script file contains illegal characters, or is not plain ASCII Text.

Otherwise, it is possible that the compiler is unable to write to the disk, that the disk is out of space.

Last, your file may be bad, such as a file in the qrong encoding format (not ASCII text).

P01: Failure to parse imported file foo.

Generally means that you are trying to call a file via the import directive that does not exist; or that
you have a typo in the filename, or path.


P02: Recursion limit of x hit while preprocessing.

Caused by attempting to import a file recursively. For example:

If you declare: import "script.z" ... and ... the file 'script.z' has the line: ' import "script.z" ' inside it.

This error should no longer exist! Recursive imports should resolve as duplicate finction/variable/script declarations.

Error P03: You may only place import statements at file scope.

Import directives ( import "file.z" ) may only be declared at a global scope, not within
a function, statement, or script.

P35: There is already a constant with name 'foo' defined.
You attempted to define the same constant more than once.
The identifier (declared name) of all constants MUST be UNIQUE.


#####################
## Specific Errors ##
##  Symbol Table   ##
#####################

S04: Function 'foo' was already declared with that type signature.

You attempted to declare a function with the same parameters twice, int he same scope.
This can occur when using different types, if the compiler cannot resolve a difference between the signatures.

To fix this, remove one function,or change its signature (the arguments inside the parens) so that each is unique or;
If you declare a functiona t a global scope, and the same at a local scope, remove one of the two.

Note that return type is NOT enough to distinguish otherwise identical function declarations and that 'int' and 'float'
types are the same type internally, so int/float is identical insofar as the signature is concerned.

If two function type signatures are identical except that one has a parameter of type float where the other has the
same parameter of type int, you will have a conflict.

There are two additional subtle situations where you might get a conflict:

1. A function declared at file scope might conflict with a function that's implicitly added to file scope
by the preprocessor because of an import statement.
2. A function might conflict with one already reserved by the ZScript standard library (std.zh).

S05: Function parameter 'foo' cannot have void type.

You cannot set a parameter (argument of a function) as a void type. e.g.:
int foo(void var){ return var+1; }

This is illegal, and the param 'var' muct be changed to a legal type.

S06: Duplicate script with name 'foo' already exists.

Script names must be wholly unique. For example, if there's already an ffc script named 'my_script' you cannot
declare an item script with the name 'my_script'.

S07: Variable 'foo' can't have type void.

Variables at any scope may not have a void type. Only functions may have this type.

S08: There is already a variable with name 'foo' defined in this scope.

Variable identifiers must be unique at any given scope. Thus, this is illegal:

ffc script my_ffc(){
    void run(int x){
        int v = 1;
        int w = 10;
        int x = 0.5;
        int y = 13;
        int z = v+w+x+y;
        Trace(z);
    }
}

As the variable 'x' is declared in the params of the run() function, it cannot be declared inside the function with
the same identifier (name).


S09: Variable 'foo' is undeclared.

You attempted to reference a variable identifier (namme) that has not been declared.
Usually this is due to a typo:

int var;
if ( val > 0 ) Link->X += var;

Here, 'val' will return this error, as it was not declared.

A variable with the give name could not be found in the current or any enclosing scope. Keep in mind the following subtleties:
1. To access a different script's global variables, or to access a global variable from within a function delcared at file scope,
you must use the dot operator: scriptname.varname.
2. To access the data members of the ffc or item associated with a script, you must use the this pointer: this->varname.
3. ZScript uses C++-style for loop scoping rules, so variables declared in the header part of the for loop cannot be
accessed outside the loop:

Code:

for(int i=0; i<5;i++);
i = 2; //NOT legal

S10: Function 'foo' is undeclared.

You attempted to call a function that was not declared. This is usually due to either a typo in your code, or failing
to import a mandatory header. Check that you are importing 'std.zh' as well, as failing to do this will result in a slew
of this error type.

S11: Script 'foo' must implement void run().

Every script must implement run() function call. The signature may be empty, or contain arguments.
Zelda Classic uses all the code inside the run() function when executing the script, so a script without
this function would do nothing, and will return an error.

S12: Script 'foo's' run() must have return type void.

Is this error even implemented? The run() function is automatic, and never declared by type, unless the user tries to declare
a separate run(params) function with a different type.

S26: Pointer types (ffc, etc) cannot be declared as global variables.

/* It is illegal to declare a global variable (that is, a variable in script scope) or any type other than int, float, and bool.
Why? Recall that global variables are permanent; they persist from frame to frame, screen to screen.
Pointer types, on the other hand, reference ffcs or items that are transitory; they become stale after a single WAITFRAME,
so it makes no sense to try to store them for the long term.
*/

This explanation may no longer be true, as pointers may no longer be dereferenced by Waitframe(),
and global pointers may also be implemented in a future version.


S30: Script foo may have only one run method.

You may not call a run() function more than once per script.
Your run method may have any type signature, but because of this flexibility, the compiler cannot
determine which run script it the "real" entry point of the script if multiple run methods are declared.

S32: Script foo is of illegal type.

The only legal script tokens are: global, ffc, and item. You cannot declare other types (such as itemdata script).

S38: Script-scope global variable declaration syntax is deprecated; put declarations at file scope instead.
You cannot declare a global variable in a global script, outside the run function.

Example:

global script active{
    int x;
    void run(){
        x = 16;
    }
}

This is ILLEGAL. The declaration of variable 'x' must either be at a global scope, or at the scope of the
run function. Do this, instead:

int x;
global script active{
    void run(){
        x = 16;
    }
}

This creates a global variable at the file scope.

S39: Array 'foo' can't have type void.
Arrays may be types of int, float, bool, ffc, item, itemdata, npc, lweapon, or eweapon; but arrays
with a void type are illegal.

S40: Pointer types (ffc, etc) cannot be declared as global arrays.
As of 2.50.2, global array declarations may only have the following types:
int, float, bool
Any other type is illegal.

S41: There is already an array with name 'foo' defined in this scope.
As with variables, and functions, arrays must have unique identifiers within the same scope.

###################
## LEXING ERRORS ##
###################
L24: Too many global variables.

The assembly language to which ZScript is compiled has a built-in maximum of 256 global variables. ZScript can't do anything if you exceed this limit.

#####################
## Specific Errors ##
##  Type Checking  ##
#####################

T13: Script 'foo' has id that's not an integer.

/* I do not know what can cause this error, or if it ever occurs. */

T14: Script 'foo's' id must be between 0 and 255.

Occurs if you try to load more than 256 scripts of any given type at any given time.
/* The maximum number of concurrent scripts (of any given type?) is 256. */

T15: Script 'foo's' id is already in use.
You attempted to laod two scripts into the same slot.
/* I do not know if this is EVER possible. */

T16: Cast from foo to bar.

The only "safe" implicit casts are from int to float and vice-versa (since they are the same type),
and from int (or float) to bool (0 becomes false, anything else true).
The results of any other kind of cast are unspecified.

/*
Is this error still in effect? Casting from npc to itemdata, or others, usually results in a different error code.
Further, Cannot cast from wtf to int, is a thing.
*/

Explicit casts are unimplemented and unnecessary.

T17: Cannot cast from foo to bar.

You attempted to typecast illegally, such as tyring to typecast from bool to float.

T18: Operand is void.
Occurs if you try to use a void type value in an operation.
/* I do not know if this is EVER possible. */

T19: Constant division by zero.

While constant-folding, the compiler has detected a division by zero

    Example:
    const int MY_CONSTANT = 0;
    ffc script foo{
        void run(){
            int x = 6;
            Link->Jump = x / MY_CONSTANT;
        }
    }

Correct the value of your constant. Perhaps you meant to use a variable?

Note that only division by a CONSTANT zero can be detected at compile time.
The following code, for instance, compiles with no errors but will generate script errors during execution.

    Example:

    int x = 0;
    int y;
    y = 1/x;




T20: Truncation of constant x.

Constants can only be specified to four places of decimal precision, withing the legal range of values.
Any extra digits are simply ignored by the compiler, which then issues this warning.

Any values greater than MAX_CONSTANT, or less then MIN_CONSTANT will result in this error.

## Applies to variables, but does not throw an error:
Both floats and ints can only be specified to four places of decimal precision.
Any extra digits are simply ignored by the compiler, which then issues this warning.

Any values greater than MAX_VARIABLE, or less then MIN_VARIABLE will result in this error.

########

T21: Could not match type signature 'foo'.

When calling a function, you used the wrong number, or types, of parameters.
The compiler can determine no way of casting the parameters of a function call so that they
match the type signature of a declared function.

For instance, in the following snippet
Code:

int x = Sin(true);

since true cannot be cast to a float, this function call cannot be matched to the library function Sin, triggering this error.


T22: Two or more functions match type signature 'foo'.

If there is ambiguity as to which function declaration a function call should matched to,
the compiler will attempt to determine the "best fit."
These measures are however occasionally still not enough. Consider for instance the following snippet:
Code:

void foo(int x, bool y) {}
void foo(bool x, int y) {}
foo(1,1);

matching either of the two foo declarations requires one cast, so no match can be made.
In contrast, the following code has no error:
Code:

void foo(int x, bool y) {}
void foo(bool x, bool y) {}
foo(1,1);

(The first foo function is matched.)

It is best to design functions so that noambiguity is possible, by addign extra params, to change the signature or by using
different identifiers (function names) when using more params is not desirable.

T23: This function must return a value.

All return statements must be followed by an expression if the enclosing function returns a value.
Note that the compiler does NOT attempt to verify that all executions paths of a function with non-void
return type actually returns a value; if you fail to return a value, the return value is undefined.
For instace, the following is a legal (though incorrect) ZScript program:

int foo() {}

/* I don't believe anythign ever returns this error.
I've seen functions with int/float/bool types, and no returns compile, without errors.
Perhaps we should fix this, and issue a warning during compilation? */

T25: Constant bitshift by noninteger amount; truncating to nearest integer.

The bitshift operators (<< and >>) require that their second parameters be whole integers.

T27: Left of the arrow (->) operator must be a pointer type (ffc, etc).

It makes no sense to write "x->foo" if x is of type int.
You may only use the dereference (->) operator on pointer types.

T28: That pointer type does not have a function 'foo'.

You tried to use the dereference operator (->) to call a function that does not exist for the pointer type being dereferenced.
Check the list of member variables and functions and verify you have not mistyped the function you are trying to call.

This generally occurs when calling internal functions, using the incorrect class, or namespace, such as:

Game->Rectangle() instead of Screen->Rectangle()

The extra std.zh component 'shortcuts.zh' assists in preventing this error type.


T29: That pointer type does not have a variable 'foo'.

You tried to use the dereference operator (->) to call a member variable that does not exist for the pointer type being dereferenced.
Check the list of member variables and verify you have not mistyped the variable you are trying to call.

This generally occurs when calling internal variables, using the incorrect class, or namespace, such as:

Link->D[] instead of Screen->D[]

/* The extra std.zh component 'shortcuts.zh' assists in preventing this error type.
Probaby not, as this requires silly amounts of functions to handle variables with identical identifiers.
C'est la vie. perhaps we'll do it, but I really am not fond of the idea. */

As above, but the member variable you tried to access does not exist.

Error T31: The index of 'foo' must be an integer.

/* This has been deprecated, so who cares? */


T36: Cannot change the value of constant variable 'foo'.

You cannot assign a CONSTANT to another value.

T37: Global variables can only be initialized to constants or globals declared in the same script.
You cannot (directly) simultaneously declare, and initialise a global value using the value of a variable at
the scope of another script, or function.

Example:
int x = script.a;
ffc script foo{
    int a = 6;
    void run(){
        for ( int q = 9; q < Rand(15); q++ ) a++;
    }
}

This is ILLEGAL. You cannot initialise the value of the global variable 'x' using the local value
of 'a' in the ffc script 'foo'.

/* I believe this is deprecated, as I do not believe that script level declarations remain legal */

T45 (old version, T38): Arrays can only be initialized to numerical values
You attempted to declare an array using a floating point value (e.g. 10.5), constant or equation,
rather than a numeric literal.


    Consider that you want to declare an array with an explicit size of '40':
    These are ILLEGAL:
        int my_arr[26+14];
        const int CONSTANT = 30;
        int my_arr[CONSTANT];
        int my_arr[CONSTANT/2+20]

    YOu must declare an arrray with a numeric literal:
        int my_array[40];
        This is the only legal way to declare the size of an array as of 2.50.2.


#####################
## Specific Errors ##
##   @Generation   ##
#####################


G33: Break must lie inside of an enclosing for or while loop.

The 'break' keyword aborts the loop (in a for, while, or do statement) in which it is called.
You must be in a loop to break out of one, so calling 'break' outside of a loop is illegal.


G34: Continue must lie inside of an enclosing for or while loop.

The 'continue' keyword halts a loop, and repeats the loop from its head (in a for, while, or do statement) in which it is called.
You must be in a loop to continue one, so calling 'continue' outside of a loop is illegal.

As the above error, but with the continue keyword. Continue aborts the current iteration of the loop and skips to the next iteration.


##################
## Array Errors ##
##################

Error A42 (old, Error O1): Array is too small. ( Converting to A42 in 2.50.3 )
You attempted to declare an array, with a set of values, where the number of values in the set
exceeds an explicit array size declaration:

int foo[4]={1,2,3,4,5};
The declared size is '4', but you tried to initialise it with five elements.

/* THis doesn't seem right, as this seems to be covered by Err 02. Check the source to see what causes this. */

Error O2: Array initializer larger than specified dimensions. ( Converting to A43 in 2.50.3)
You attempted to initialise an array, with a set of values, where the number of values in the set
exceeds an explicit array size declaration:

int foo[4]={1,2,3,4,5};
The declared size is '4', but you tried to initialise it with five elements.

Error O3: String array initializer larger than specified dimensions, space must be allocated for NULL terminator.
( Convering to A44 in 2.50.3 )
YOu attempted to seclare a QUOTEDSTRING of an explicit size, but you didn;t add space
for the NULL terminator; or you used more chars than you allocated:

int my_string[17]="This is a string.";
    THis allocates only enough indices for the chars, but not for the NULL terminator.
    The array size here needs to be 18.
int my_string[12]="THis is a string.";
    You tried to initialise a QUOTEDSTRING that is longer than the array size.
    The minimum array size for this is '18'.

    It is generally best either to declare strings with an implicit size (set by the initialiser):
        int my_string[]="This is a string";
            This reads the nuber of chars, adds one to the count (for NULL), and sizes the array to 18.
    ...or...
    Declare the string with an arbitrarily large size:
        int my_string[256]="This is a string";
            This reserves 256 chars. Only 18 are used, and the rest of the indices
            are initialised as '0' (NULL). YOu may later populate the unused space, if desired.


#################
## Misc Errors ##
#################

FATAL FATAL ERROR I0: bad internal error code
A fallback error if no other type matches the problem.

/* I have no idea what causes this. Be afraid, very afraid. */

/* OTHER ERRORS
Document any further error codes here.
We need to convert the array errors from raw numeric, to A** codes.
*/

########################
## OPERATIONAL ERRORS ##
###################################################################################################
## These errors occur only during the operation of script execution (i.e. when running a script, ##
## in Zelda Classic while playing a quest).                                                      ##
## --------------------------------------------------------------------------------------------- ##
## In ZC versions 2.50.2, and later, operational script errors will return the ID of the script  ##
## from which they were generated.                                                               ##
###################################################################################################

//! These errors will be reported to allegro.log (or the ZConsole) when scripts run.



////////////////////
/// Stack Errors ///
////////////////////

    "Stack over or underflow, stack pointer = %ld\n"

* !? How should I describe this, and give examples?

    "Invalid ZASM command %ld reached\n"

Stack instruction countber reached, or exceeded. The stack counter is an unsigned int, so it's maximum value is 65536.
You have isused more instructiosn this frame than the instructon counter can ahndle. Look through your code for
something that may be doing this.

////////////////////
/// Array Errors ///
////////////////////

    "Invalid value (%i) passed to '%s'\n"
    "Invalid index (%ld) to local array of size %ld\n"

You attempted to reference an array index that is either too small, or too large.
Check the size of your array, and try again.
Perhaps you have a for loop, or other loop that is parsing the array, and trying to read beyond its index ranges.


    "Invalid pointer (%i) passed to array (don't change the values of your array pointers)\n"

Array pointers values in operation are 1 through 4095, ( and 4096 to 8164? as declared global pointers ?).
An array may not have a pointer of '0', nor may you reference an array for which a pointer does not exist.
Often, this error is caused by attempting to reference an array that you created, without updating the saved game slot
as the old save does not have the array allocated, but the script is attempting to reference its global ID.

    "Script tried to deallocate memory at invalid address %ld\n"
    "Script tried to deallocate memory that was not allocated at address %ld\n"

/* Script attempted to change the value of an array index // that does not exist // due to the inability to declare an array
because too many registers are in use?


    "You were trying to reference an out-of-bounds array index for a screen's D[] array (%ld); valid indices are from 0 to 7.\n"
You attempted to read, or write to a Screen->D[register] that was less than 1, or greater than 10.
Check for loops, and vriables that read/write to Screen->D for any that can fall outside the legal range.

    "Array initialized to invalid size of %d\n"
You attempted to init array to a size less than 1, or a size greater than 214747, or;
You attempted to init array with a constant, a variable, a formula, or with a floating point value.
Arrays may ONLY be initialised with numeric literals (integers only) between 1 and 214747.

    "%d local arrays already in use, no more can be allocated\n", MAX_ZCARRAY_SIZE-1);
The maximum number of arrays in operation at one time is 4095.

"Invalid pointer value of %ld passed to global allocate\n"
    !

/////////////////////////////
/// Object Pointer Errors ///
/////////////////////////////

    "Invalid NPC with UID %ld passed to %s\nNPCs on screen have UIDs "
    "Invalid item with UID %ld passed to %s\nItems on screen have UIDs "
    "Invalid lweapon with UID %ld passed to %s\nLWeapons on screen have UIDs "
    "Invalid eweapon with UID %ld passed to %s\nEWeapons on screen have UIDs "

    "Script attempted to reference a nonexistent NPC!\n"
    "You were trying to reference the %s of an NPC with UID = %ld; NPC on screen are UIDs "

    "Script attempted to reference a nonexistent item!\n"
    "You were trying to reference an item with UID = %ld; Items on screen are UIDs: "

    "Script attempted to reference a nonexistent LWeapon!\n"
    "You were trying to reference the %s of an LWeapon with UID = %ld; LWeapons on screen are UIDs "

    "Script attempted to reference a nonexistent EWeapon!\n"
    "You were trying to reference the %s of an EWeapon with UID = %ld; EWeapons on screen are UIDs "

You attempted to reference a game object that has a maximum legal range of 1 to 255.
It is possible that you tried to read outside that range, or that the pointer that you were loading is not valid.
Check NumItems(), NumLWeapons(), NumEWeapons(0, and NumNPCs() before referencing them; and verify that the object ->IsValid()
Check for loops that may attempt ro reference items outside of the range that actually exist.
Look for any for loops that access these objects, that start, or end at zero.

The best way to ensure this does not occur, is to make a for loop as follows:

    for ( int q = 1; q < Screen->NumLWeapons; q++ )

            //or//

    for ( int q = Screen->NumLWeapons(); q > 0; q-- )

...replacing NumLWeapons() withthe appropriate type that you are attempting to load.

You may be attempting to refrence a pointer that has fallen out of scope.
You may be attempting to reference a pointer that is no longer valid, or has been removed.
Check ( pinter->IsValid() ) by itself, to ensure this does not occur:

        if ( pointer->IsValid ) {
            if ( pointer->ID == LW_FIRE ) //Do things.
        }

This helps to prevent loading invalid pointers.

////////////////////////////////
/// Maths and Logical Errors ///
////////////////////////////////

"Script attempted to divide %ld by zero!\n"
"Script attempted to modulo %ld by zero!\n"

"Script attempted to pass %ld into ArcSin!\n"
"Script attempted to pass %ld into ArcCos!\n"
"Script tried to calculate log of 0\n"
"Script tried to calculate log of %f\n"
"Script tried to calculate ln of 0\n"
"Script tried to calculate ln of %f\n"
"Script attempted to calculate 0 to the power 0!\n"
"Script attempted to calculate square root of %ld!\n"

Look for scripts that pass a variable into these functions, or use a variable in a mathematical operation, that
may be zero at any point, and correct it to ensure that it is never zero, or that it is never illegal for the type of
mathematical operation you wish to perform.

Chweck for any hardcoded values, or constants that are in use with these functions that may be illegal, or irrational.

////////////////////////////////
/// System Limitation Errors ///
////////////////////////////////

"Couldn't create lweapon %ld, screen lweapon limit reached\n"
"Couldn't create eweapon %ld, screen eweapon limit reached\n"
"Couldn't create item \"%s\", screen item limit reached\n"
"Couldn't create NPC \"%s\", screen NPC limit reached\n"

You may create a maximum of 255 of any one object type on the screen at any one time.
Look for anything that is generating extra pointers, and add a statement such as:
    if ( Screen->NumNPCs() < 255 )

    "Max draw primitive limit reached\n"
The maximum number of drawing function calls, per frame, is 1,000.

/////////////////////
/// String Errors ///
/////////////////////

    "Array supplied to 'Game->GetDMapMusicFilename' not large enough\n"
    "Array supplied to 'Game->GetSaveName' not large enough\n"
    "String supplied to 'Game->GetSaveName' too large\n"
    "Array supplied to 'Game->GetMessage' not large enough\n"
    "Array supplied to 'Game->GetDMapName' not large enough\n"
    "Array supplied to 'Game->GetDMapTitle' not large enough\n"
    "Array supplied to 'Game->GetDMapIntro' not large enough\n"
    "Array supplied to 'itemdata->GetName' not large enough\n"
    "Array supplied to 'npc->GetName' not large enough\n"

The buffer for these actions must be equal to the size of the text to load into it, plus one, for NULL.

If you wish to load a game name, with Game->LoadSaveName(), and the name on the file select is FOO, you must
supply a buffer with a size of [4] to hold it. (Three chars in the name, plus one for NULL.)

////////////////////
/// Misc. Errors ///
////////////////////

    "Waitdraw can only be used in the active global script\n"
You attempted to call Waitdrw() in an ffc script, or an item script; or in your global OnContinue,
global OnExit, or ~Init scripts.
You may only use the Waitdraw() function from a global active script.

    "No other scripts are currently supported\n"
? You should never see this. May indicate that you have attempted to load more scripts than ZC can handle.


    "Invalid value (%i) passed to '%s'\n"
!? WHat should we put here?

    "Global scripts currently have no A registers\n"
This error can only occur if you are coding ZASM, and attempt to utilise an Address register with a global script.

////////////////////////
/// Script Reporting ///
////////////////////////

    //Events that will be recorded if Quest Rule 'Log Game Events to Allegro.log' is enabled:

"Script created lweapon %ld with UID = %ld\n"
"Script created eweapon %ld with UID = %ld\n"
"Script created item \"%s\" with UID = %ld\n"
"Script created NPC \"%s\" with UID = %ld\n"

When any new game object is generated by script, and reporting is enabled, the lweapon, and the name of the
script that generated it, will be reported to allegro.log.


///////////////////////////
/// Documentation Staff ///
///////////////////////////

ZScript documentation generated, and maintained by:
DarkDragon (retired)
Gleeok
Saffith
ZoriaRPG