ZScript Documentation (Under Construction)

ZScript Web Documentation

Use the panel at the left to navigate.

Output Console

The term 'output console' can refer to multiple things. Generally, it refers to the actual zscript debugger console that can be opened in ZC via "ZC -> Show ZScript Debugger"; though it could also refer to the general log output, which is logged to "allegro.log". Errors and debug information are logged to the Output Console (some of which is only logged if certain quest rules are enabled), which the user can use to debug their scripts. Logging Functions can be used to directly output to the console.

Message Strings

Edited in 'Quest->Strings' in ZQuest, message strings represent messages that can be displayed on-screen to the player, including not only text, but also various formatting options, and String Control Codes. ZScript can use messagedata pointers to modify message strings directly.

String Control Codes

vRev July 17th, 2022 for 2.55 A107 Special effects can be created when message strings are displayed by inserting special control codes into the string. All valid codes are listed below.

Formatting Codes

These codes have formatting effects on the string being displayed, such as changing the font, text color, or inserting characters or tiles into the message.

Menu Codes

These codes relate to popping up a menu for the player to select a choice from.

Switch Codes

These codes change from the current string immediately to a different string. If you attempt to switch to a string that does not exist, it will instead act as though you switched to a string that is entirely empty.

Counter Mod Codes

These codes all center around modifying counter values.

Misc Codes

Global Pointers have a single global instance which can be referenced anywhere.

Data Pointers must be loaded before they can be used. Each has its' own pointer type of which variables can be declared.

Sprite objects are a subset of object types which share a variety of attributes. These include weapons, npcs, items, etc.

Managed Pointers all have a total maximum that can be in use at a time, and are only freed for re-use using Free() and Own() functions.

Global Functions

Global functions are a member of no pointer type, and instead are simply able to be called from anywhere.

Functions that don't fit a particular category.

void Quit();

Exits the current script entirely. Has the same effect as reaching the end of 'void run()', or 'return'ing from the 'void run()'.

void Waitframe();

When called, the script ends running for the current frame. The engine will proceed with one frame of gameplay before resuming this script at this position.

void Waitdraw();

When called the first time in a frame, the script ends running for a portion of time. The engine will proceed with part of a frame of gameplay, allowing other engine activities to occur, before resuming this script. If called again, the additional call will act as a call to 'Waitframe()', as it cannot wait any more of the frame without the frame ending.

void CopyTile(int src, int dest);

Copies tile 'src' to tile 'dest'.

void OverlayTile(int src, int dest); Since 2.53

Overlays tile 'src' over tile 'dest'.

void SwapTile(int a, int b);

Swaps the tiles 'a' and 'b'.

void ClearTile(int tile);

Clears the tile 'tile' to be blank.

Note

All tile modifications are temporary, and will be reset when the quest is exited.

float Distance(float x1, float y1, float x2, float y2);

float Distance(float x1, float y1, float x2, float y2, int scale);

Calculates the distance between two points, optionally using a scale divisor to handle distances that would otherwise overflow.

long LongDistance(long x1, long y1, long x2, long y2);

long LongDistance(long x1, long y1, long x2, long y2, long scale);

Same as 'Distance()', but takes distances as 'long' coordinates, returning a 'long' distance value.

int GetSystemTime(int index);

Returns information from the real-time clock of the system. Valid values:

0. RTC_YEAR: Returns the year
1. RTC_MONTH: Returns the month, with 1 = January
2. RTC_DAYOFMONTH: Returns the day of the month, 1-31
3. RTC_DAYOFWEEK: Returns the day of the week, 1 = Sunday
4. RTC_HOUR: Returns the current hour, 0-23
5. RTC_MINUTE: Returns the current minute, 0-59
6. RTC_SECOND: Returns the current second, 0-60 (only 60 for leap seconds on certain systems)
7. RTC_DAYOFYEAR: Returns the day of the year, 0-365
8. RTC_DAYLIGHTTIME: Returns a value based on DST. 0 indicates DST is not in effect, >0 indicates it is, and <0 indicates that the system does not know.

void SaveSRAM(char32[] filename.zcsram, int flags); void LoadSRAM(char32[] filename.zcsram, int flags);

Saves/loads internal data (which is normally temporarily altered by scripts) of the types specified in 'flags'. Flags:

• npcdata: 0x01
• itemdata: 0x02
• spritedata: 0x04
• combodata: 0x08
• dmapdata: 0x10
• mapdata: 0x20

Flags are OR'd together (ex. 0x01 | 0x02 | 0x04). Passing '0' will use ALL flags. Related: OnSaveLoadUnder Construction!, OnSaveUnder Construction!

These functions relate to various mathematical operations.

float Abs(float val);

Returns the absolute value of the parameter.

int Ceiling(float val);

Returns 'val' rounded up to the next higher integer.

int Floor(float val);

Returns 'val' rounded down to the next lower integer.

int Factorial(int val);

Returns 'val!'. Returns '0' for negative values.

float Log10(float val);

Returns the log₁₀ of the value. Values <= 0 return 0.

float Ln(float val);

Returns the natural log (log_e) of the value. Values <= 0 return 0.

float Min(float a, float b);

Returns a or b, whichever is lower.

float Max(float a, float b);

Returns a or b, whichever is higher.

int Pow(int base, int exp);

Returns 'base^exp', undefined for '0⁰'. Negative values of 'exp' work, though may not be useful, as the return value is truncated to the nearest integer.

int InvPow(int base, int exp);

Returns 'base^(1/exp)', undefined if 'exp' is 0, or if 'exp' is even and 'base' is negative. Negative values of 'exp' work, though may not be useful, as the return value is truncated to the nearest integer.

float Sqrt(float val);

Returns the square root of the value. Undefined for negative values, and will return an error.

float Sin(float deg); float Cos(float deg); float Tan(float deg);

Returns the trig Sin/Cos/Tan of the degree value given.

float RadianSin(float rad); float RadianCos(float rad); float RadianTan(float rad);

Returns the trig Sin/Cos/Tan of the radian value given.

float ArcSin(float x); float ArcCos(float x); float ArcTan(float x, float y);

Returns the trig ArcSin/ArcCos/ArcTan of the value(s) given.

float DegtoRad(float deg); float RadtoDeg(float rad);

Converts between degrees and radians.

These functions all relate to the Output Console, and printing data to it.

void Trace(untyped val);

Prints the passed value to the output console, as a number with 4 decimal places. Includes a newline character after the value.

void TraceB(untyped val);

Prints the passed value to the output console, as "true" if the value is nonzero, or "false" if the value is 0. Includes a newline character after the value.

void TraceS(char32[] string);

Prints the passed string to the output console. Does not include a newline character after the string.

void TraceNL();

Prints a newline character to the output console.

void TraceToBase(int val, int base, int mindigits);

Prints the passed value to the output console, in the specified base, where "2 <= base <= 36". Value will be floored before print, so decimal values are not printed. Will print at least 'mindigits' digits, using leading 0s as needed. Includes a newline character after the value.

void ClearTrace();

Clears the logs from allegro.log, and clears the output console.

void printf(char32[] format_string, ...untyped argsTakes 0 to 16 (inclusive) untyped args);

Prints the specified format_string to the output console, using the given args to fill in parts of the string that are specially marked. Does not include a newline character after the string. Valid patterns:

• '%i' or '%p': Inserts the value as an integer (no decimal places).
• '%f': Inserts the value as a float number (decimal places included)
• '%d': Acts as '%i' if all decimal places are '0', as '%f' otherwise.
• '%l': Inserts the value as a long (decimal places included, but no decimal point)
• '%s': Inserts the value as a string (must be a valid array pointer)
• '%c': Inserts the value as a character.
• '%x' or '%X': Inserts the value as a hexadecimal integer (no decimal places). Capitalization of letters matches the capitalization of the 'x'.
• '%%': Inserts a single '%', does not act as a pattern.

Also, by including numbers between the '%' and letter for patterns (excluding '%s', '%c', '%%'), it will take a minimum of that many digits, adding leading 0's as needed. Example: '%5i' given a value of '253' would display as '00253', filling up 5 digits of space. Related: sprintf()

These functions relate to the manipulation of strings.

char32[] utol(char32[] string); char32[] ltou(char32[] string); char32[] convcase(char32[] string);

Returns the string passed. Converts the capitalization of every letter in the string. Respectively, converting all to upper, all to lower, or inverting the case.

int ilen(char32[] string);

Returns the number of characters in the string that are taken up by a number (as would be read by atoi, including negative sign);

int itoacat(char32[] dest, int val);

Appends the value 'val' on the end of the 'dest' string; combining itoa with strcat

void sprintf(char32[] dest, char32[] format_string, ...untyped argsTakes 0 to 16 (inclusive); untyped args);

Acts exactly as printf, except instead of printing the result to the output console, it is instead placed in the 'dest' buffer.

char32[] strcat(char32[] dest, char32[] src);

Appends 'src' to the end of 'dest'. Returns 'dest'.

void strcpy(char32[] dest, char32[] src);

Copies the string 'src' to 'dest'.

int strcspn(char32[] str, char32[] chars);

Returns the length in 'str' before any character in 'chars' is found. Related: strspn

int strcmp(char32[] str1, char32[] str2); int strncmp(char32[] str1, char32[] str2, int num_chars); int stricmp(char32[] str1, char32[] str2); int strnicmp(char32[] str1, char32[] str2, int num_chars);

Compares the contents of the two strings. Returns '0' if the strings are equal. Otherwise, compares the first character that is different between the strings, returning >0 if it is larger in str1, and <0 if it is larger in str2. 'strncmp' and 'strnicmp' only compares the first 'num_chars' characters. 'stricmp' and 'strnicmp' compare case-insensitively.

int strchr(char32[] str, char32 c);

Returns the first index of 'str' that contains the character 'c'.

int strrchr(char32[] str, char32 c);

Returns the last index of 'str' that contains the character 'c'.

int strstr(char32[] str, char32[] tofind);

Returns the index of the first instance of the string 'tofind' within 'str'.

int atoi(char32[] str);

Converts a string containing a number to its' numeric value. Ex. atoi("0526"); == 526

int xtoi(char32[] str);

Converts a string containing a hexadecimal number to its' numeric value. Ex. xtoi("0x15"); == 21

int strlen(char32[] str);

Returns the length of the string in characters.

int strcspn(char32[] str, char32[] chars);

Returns the length in 'str' until any character NOT in 'chars' is found. Related: strcspn

int itoa(char32[] dest, int val);

Converts the value 'val' to a string, and places it in the 'dest'. Ex. itoa(dest, 72); leaves the buffer holding "72".

int xtoa(char32[] dest, int val);

Converts the value 'val' to a string, as hexadecimal, and places it in the 'dest'. Ex. xtoa(dest, 21); leaves the buffer holding "0x15".

These functions relate to arrays.

void ArrayCopy(untyped[] dest, untyped[] src);

Copies all data from 'src' to 'dest'. If the arrays are not the same size, the smaller size is used, and the excess in the larger array is ignored.

bool IsValidArray(untyped[] arr);

Returns true if the value 'arr' points to a valid array.

int SizeOfArray(untyped[] arr);

Returns the size of the array

void ResizeArray(untyped[] arr, int size);

Resizes the array 'arr' to size 'size'. If 'size' is <1, the array becomes size 1 instead.

FFC Pointers

ffc These pointers represent the 32 Freeform Combos on the current screen, and their various attributes and functions. Using these pointers, you can move them, change their combo, change their script, etc. See: LoadFFCUnder Construction!

int X; int Y;

Read/Write; These values store the ffc's position on each of the two axes; FFCs do not have a 'Z' position. Values may contain up to 4 decimal places, regardless of QRs.

int Data;

The combo used by the FFC for its' visuals and type.

int CSet;

The CSet the FFC displays in.

int TileHeight; int TileWidth;

The visual size, in tiles (1 to 4), of the FFC. The tile set by its' combo will be the upper-left tile, with the rest drawn as a tile block from there.

int EffectHeight; int EffectWidth;

The hitbox size, in pixels (1 to 64), of the FFC. Unless the FFC is Ethereal, the type of its' combo will affect this area. NOTE: Not all combo types function when placed on FFCs.

int Script;

The FFC script ID running on this FFC.

untyped InitD[8];

The 8 InitD[] parameters for the FFC's script.

untyped Misc[16];

A miscilaneous data array, for script use.

int Vx; int Vy;

The FFC's current X and Y axis velocities.

int Ax; int Ay;

The FFC's current X and Y axis accelerations.

int Delay;

The time in frames before the FFC will begin moving.

int Flags[14];

The FFC's flags. Values representing FFC flags:

0. FFCF_OVERLAYDraws between layers 4 and 5 if enabled
1. FFCF_TRANSDraws transparently if enabled
2. FFCF_SOLIDMakes the FFC behave as entirely solid. [NOT FULLY IMPLEMENTED
3. FFCF_CARRYOVERIf enabled, the FFC will carry between screens, replacing the FFC that is of the same index on any screen it is brought to.
4. FFCF_STATIONARYIgnores movement attributes if enabled.
5. FFCF_CHANGERChanges other FFCs that come into contact with this one
6. FFCF_PRELOADThe FFC's script will run for one frame before scrolling onto its' screen.
7. FFCF_LENSVISThe FFC is invisible unless you are using a Lens of Truth.
8. FFCF_RESETWhen the FFC is carried over to a new screen, its' script will restart.
9. FFCF_ETHEREALThe FFC will not apply its' combo's 'Type' effects, nor block the types of combos under it.
10. FFCF_IGNOREHOLDUPThe FFC continues to run while the player is holding an item up.
11. FFCF_IGNORECHANGERThe FFC will ignore changer FFCs.
12. FFCF_IMPRECISIONCHANGERThe FFC will collide with changer FFCs when it is on the same whole pixel to them, rather than requiring the exact same subpixel.
13. FFCF_LENSINVISThe FFC is invisible while using the lens of truth.

int Link;

Represents the ID of another FFC this one is 'linked' to.

int ID;

Read-only: the screen index of the FFC.

NPC Pointers

npc These pointers represent an enemy on the screen, and its' various attributes and functions. Using these pointers, you can move them, damage them, make them move, make them invincible, etc. See: LoadNPCUnder Construction!, CreateNPCUnder Construction!

int X; int Y; int Z;

Read/Write; These values store the enemy's position on each of the three axes. If the quest rule 'Sprite Coordinates are Float'at "ZScript->Quest Script Settings->Object" is checked, these values can include up to 4 decimal places; otherwise values are truncated to int.

NPC Movement

These functions relate to npc movement.

bool MoveXY(float dx, float dy, int special); bool CanMoveXY(float dx, float dy, int special);

Attempts to move the enemy by 'dx' in the x direction and 'dy' in the y direction, failing if it is blocked by something it cannot walk through. Use the 'SPW_' constants for 'int special'; i.e. 'SPW_FLOATER' to indicate a flying enemy. Returns true if the enemy moves the full distance, false if the enemy was blocked at all. The 'CanMoveXY' variant will not actually move the enemy at all, but will run the collision checks and return true if it CAN move the full distance, or false if it WOULD be blocked.

bool Move(int dir, float pxamnt, int special); bool CanMove(int dir, float pxamnt, int special);

Attempts to move the enemy by 'pxamnt' pixels in the 'dir' direction, failing if it is blocked by something it cannot walk through. Use the 'SPW_' constants for 'int special'; i.e. 'SPW_FLOATER' to indicate a flying enemy. Returns true if the enemy moves the full distance, false if the enemy was blocked at all. The 'CanMove' variant will not actually move the enemy at all, but will run the collision checks and return true if it CAN move the full distance, or false if it WOULD be blocked.

bool MoveAtAngle(float degrees, float pxamnt, int special); bool CanMoveAtAngle(float degrees, float pxamnt, int special);

Attempts to move the enemy by 'pxamnt' pixels in the 'degrees' angle, failing if it is blocked by something it cannot walk through. Use the 'SPW_' constants for 'int special'; i.e. 'SPW_FLOATER' to indicate a flying enemy. Returns true if the enemy moves the full distance, false if the enemy was blocked at all. The 'CanMoveAtAngle' variant will not actually move the enemy at all, but will run the collision checks and return true if it CAN move the full distance, or false if it WOULD be blocked.

bool MovePaused();

Returns true if the enemy is in a state in which it should not be allowed to move (ex. spawning, dying, stunned, time frozen by clock) Returns false otherwise.

bool Knockback(int time, int dir, int speed);

Attempt to knock back the npc in 'dir' direction, for 'time' frames, at a rate of 'speed' pixels per frame. Returns true if successful, false if the enemy could not be knocked back. Related: bool npc->NoScriptKnockback;

bool NoScriptKnockback;

False by default. If set to 'true', scripted knockback via 'npc->Knockback()' is ignored.

GenericData Pointers

genericdata genericdata pointers allow interacting with and running generic scripts. See: LoadGenericDataUnder Construction!, WaitToUnder Construction!

bool Running;

When read, returns true if the script is currently running passively. If written false, kills the script. If written true, launches (or restarts) the script.

bool RunFrozen();

Attempt to run the generic script in frozen mode. Returns true if successful, false otherwise. If successful, the script will run until it exits, with everything else in the engine frozen, including all other scripts.

bool ExitState[GENSCR_NUMST]; bool ReloadState[GENSCR_NUMST];

Arrays of exit and reload conditions. All states default to 'false'. If an exitstate is true, when the associated condition is met, the script will exit entirely. If a reloadstate is true, when the associated condition is met, the script will restart from the start if it was already running. Available states:

0. GENSCR_ST_RELOADWill exit or reload on starting from the title screen if true. NOTE: Even if reload is false, scripts will reload on this condition.
1. GENSCR_ST_CONTINUEWill exit or reload upon 'F6->Continue', or an effect which mimics 'F6->Continue'.
2. GENSCR_ST_CHANGE_SCREENWill exit or reload upon changing screens
3. GENSCR_ST_CHANGE_DMAPWill exit or reload upon changing dmaps
4. GENSCR_ST_CHANGE_LEVELWill exit or reload upon changing dmap levels

untyped InitD[8];

The 8 InitD[] parameters for the generic script. Shared by passive and frozen run modes.

int DataSize;

Read/write; the size of the script's Data array (see below). Writing this resizes the array, where any area above the previous maximum is cleared to '0'. Defaults to size '0'.

untyped Data[DataSize];

A misc data array, resizable by writing to DataSize (see above). All indexes are saved with the save file, including any resizing.

File Pointers

file file pointers allow directly interacting with files on the user's system. Each quest has a directory created at "[zc root]/files/[quest name]/", and ONLY files within this directory are accessible. All paths are relative to this directory. There is no 'LoadFile' function. To load a file, declare a variable of type 'file', and call Open(), Create(), or OpenMode() to open a file to it. General info about filesystem access: Files opened with 'Open()' or 'Create()', as well as some modes passed to 'OpenMode()', can be Read/Write. In a Read/Write mode, you must call one of a few certain functions between a read call and a write call. These functions will list this effect in their description. Writing to files does not write directly to disk, but to a buffer. It is guaranteed that the contents of this buffer will be written to disk upon a successful call to 'Flush()', or upon the closing of the file. Upon exiting the quest, all open files are closed. There is a limit of 256 file pointers. A pointer does not need to have a file open to count against this limit. Any pointer that returns true from 'isAllocated()' counts against this limit. Calling 'Free()' will deallocate a pointer, thus no longer counting against this limit. If you open many files without calling 'Free()', you may run out of pointers, and be unable to open further files (until you call 'Free()' on some existing pointers). Files are NOT automatically freed if they fall out of scope. You should be sure to manually call 'Free()' before this happens, or you may lose the pointer, and be unable to free it later. Using Own(), you can set a file pointer to automatically free when the calling script exits. Remember: POSIX filesystems are Case-SenSitive.

bool Open(char32[] "filepath"); bool Create(char32[] "filepath");

If the file pointer is not allocated, these will allocate it. Also closes any file that is already open on the pointer. Attempts to open "[zc root]/files/[questname]/[filepath]", in mode 'rb+' for 'Open()' or 'wb+' for 'Create()'. Open will fail if the file does not exist; Create will create it if it does not exist, and wipe the file clean if it does exist.

bool OpenMode(char32[] "filepath", char32[] "mode_string");

If the file pointer is not allocated, this will allocate it. Also closes any file that is already open on the pointer. Same as 'Open()', but the file is opened with the specified mode. Valid modes (details taken from http://www.cplusplus.com/reference/cstdio/fopen/): "r" | read: Open file for input operations. The file must exist. "w" | write: Create an empty file for output operations. If a file with the same name already exists, its contents are discarded and the file is treated as a new empty file. "a" | append: Open file for output at the end of a file. Output operations always write data at the end of the file, expanding it. Repositioning operations ('Seek()', 'Rewind()') are ignored. The file is created if it does not exist. "r+" | read/update: Open a file for update (both for input and output). The file must exist. "w+" | write/update: Create an empty file and open it for update (both for input and output). If a file with the same name already exists its contents are discarded and the file is treated as a new empty file. "a+" | append/update: Open a file for update (both for input and output) with all output operations writing data at the end of the file. Repositioning operations (fseek, fsetpos, rewind) affects the next input operations, but output operations move the position back to the end of file. The file is created if it does not exist. The letter "b" can be added to the end of any of these (or before the "+", for update modes) to specify a binary file mode. Not doing this will specify a text file mode. Text files are files containing sequences of lines of text. Depending on the environment where the application runs, some special character conversion may occur in input/output operations in text mode to adapt them to a system-specific text file format. Although on some environments no conversions occur and both text files and binary files are treated the same way, using the appropriate mode improves portability.

bool Remove();

Deletes the file. This will close it, as with Close(), and then delete it from the filesystem. Returns true if successful. The file will be closed, even if the removal fails.

bool Flush();

Flushes the buffer of the file being written to. Writes to a file do not actually write to the file immediately; they instead go to a buffer. Calling this function will force the buffer to be written to disk.

void Close();

Closes any open file connected to the file pointer (which also includes 'Flush()'). Does *NOT* deallocate the pointer, it is still reserved to open new files on.

void Free();

Closes any file as 'Close()', then deallocates the file pointer so it may be re-used.

void Own();

Grants 'Ownership' of the file pointer to the script that calls this function. When the script with 'Ownership' terminates (at the same time its' local arrays are deallocated), this file pointer will automatically be 'Free()'d.

bool isAllocated();

Returns true if this pointer is allocated. This does not necessarily mean a file is open, just that the pointer has a reserved ID.

bool isValid();

Returns true if a file is open on the pointer.

bool Allocate();

Attempts to allocate the file pointer. If it was already allocated, this will re-allocate it without freeing it! Returns true if successful, false if the max number of files is already allocated.

int ReadString(char32[] buf);

Reads a section of characters from the file. Will read either until 'buf' is full, an error occurs, End of File is reached, or a newline character is reached. If it ends due to reaching a newline character, the newline character will be included at the end of the string. Returns the length of the string read into 'buf'.

int ReadChars(char32[] buf, int count, int pos);

Reads a section of characters from the file. Starts placing characters at 'buf[pos]'. If 'pos' is negative, starts at 'buf[0]'. If 'count' is 0, does nothing and returns 0. If 'count' is negative, reads until it fills 'buf', an error occurs, or End of File is reached. If 'count' is positive, reads 'count' characters into 'buf'. Will always add a null character at the end of the read characters. Returns the number of characters read, excluding the added null character.

int ReadBytes(untyped[] buf, int count, int pos);

Reads a section of binary data from the file. Starts placing data at 'buf[pos]'. If 'pos' is negative, starts at 'buf[0]'. If 'count' is 0, does nothing and returns 0. If 'count' is negative, reads until it fills 'buf', an error occurs, or End of File is reached. If 'count' is positive, reads 'count' characters into 'buf'. The binary data read will be 8b; such that reading '1' will place '1' into buf. This means that the binary data cannot contain decimal places. Returns the number of bytes read.

int ReadInts(untyped[] buf, int count, int pos);

Reads a section of binary data from the file. Starts placing data at 'buf[pos]'. If 'pos' is negative, starts at 'buf[0]'. If 'count' is 0, does nothing and returns 0. If 'count' is negative, reads until it fills 'buf', an error occurs, or End of File is reached. If 'count' is positive, reads 'count' characters into 'buf'. The binary data read will be 32b; such that reading '1' will place '0.0001' into buf. This means that the binary data can contain decimal places. Returns the number of ints read.

char32 GetChar();

Reads and returns the next character in the file. Returns -1 if it fails; check 'EOF' and 'Error' to see why.

char32 UngetChar(char32 c);

Un-reads 'c' to the input stream. Returns -1 if it fails; otherwise returns 'c'. This is a READ operation, not a WRITE operation. The file will not actually be modified; but further read operations will find this as the next character to be read. Useful if you read a character, then realize you don't want it.

int WriteString(char32[] str);

Writes the string stored in 'str' to the file. Returns the number of characters successfully written.

int WriteChars(char32[] buf, int count, int pos);

Writes characters from 'buf' to file. Starts at 'buf[pos]'. If 'pos' is negative, starts at 'buf[0]'. If 'count' is 0, does nothing and returns 0. If 'count' is negative, writes from 'buf' until it finds a null character, or reaches the end of 'buf'. If 'count' is positive, writes 'count' characters from buf. Returns the number of characters successfully written.

int WriteBytes(untyped[] arr, int count, int pos);

Writes 8b binary data from 'arr' to file. The binary data written will be 8b; such that writing '1' will write '1' to file. This means that the binary data cannot contain decimal places. Starts at 'arr[pos]'. If 'pos' is negative, starts at 'arr[0]'. If 'count' is 0, does nothing and returns 0. If 'count' is negative, writes from 'arr' until it reaches the end of 'arr'. If 'count' is positive, writes 'count' ints from arr. Returns the number of bytes successfully written.

int WriteInts(untyped[] arr, int count, int pos);

Writes 32b binary data from 'arr' to file. The binary data written will be 32b; such that writing '1' will write '10000' to file. This means that the binary data can contain decimal places; writing '0.0001' will write '1' to file. Starts at 'arr[pos]'. If 'pos' is negative, starts at 'arr[0]'. If 'count' is 0, does nothing and returns 0. If 'count' is negative, writes from 'arr' until it reaches the end of 'arr'. If 'count' is positive, writes 'count' ints from arr. Returns the number of 32b integers successfully written.

char32 PutChar(char32 c);

Writes 'c' to file. Returns -1 if it fails; otherwise returns 'c'.

long Pos;

Read-only. This represents the current position in the file. In binary modes ('Open()', 'Create()', or 'OpenMode()' including "b"), this is the number of bytes into the file, as a long; i.e. '10L' == 10 bytes. In text modes ('OpenMode()' not including "b"), the numerical value may not be meaningful but can still be used to restore the position to the same position later using 'Seek()' (if there are characters put back using 'UngetChar()' still pending of being read, the behavior is undefined).

bool Seek(long pos, bool from_current);

Moves the current position of the file. 'pos' is a 32b value, where '1L' represents 1 byte; similar to 'Pos'. If 'from_current' is true, it moves forward from the current position. Otherwise, it moves so that 'Pos' is equal to 'pos'. Using 'from_current'==true in a file open in text mode ('OpenMode()' not including "b") is undefined. Returns true if successful, false otherwise. If successful, this function has the following side-effects:

• All previous calls to 'UngetChar()' are dropped.
• The 'EOF' indicator is set to false.
• Allows switching between reading and writing on a read/write file.

void Rewind();

Rewinds to the beginning of the file. This function has the following side-effects:

• All previous calls to 'UngetChar()' are dropped.
• The 'EOF' indicator is set to false.
• The 'Error' indicator is set to 0.
• Allows switching between reading and writing on a read/write file.

bool EOF;

Read-Only. Returns true if a read call attempted to read past the end of the file. If true, no further read calls will succeed until the position has been changed; i.e. 'Seek()' or 'Rewind()'.

int Error;

Read-Only. Returns 0 if the file has not enountered an error. If an error was encountered, returns an error code number.

void ClearError();

Clears the active EOF and Error indicators. i.e. this writes 'EOF = false;' and 'Error = 0;'.

void GetError(char32[] buf);

Stores a string describing the current error into the buffer provided. Stores an empty string if 'Error == 0'.

Directory Pointers

directory directory pointers allow interacting with directories on the user's system. Each quest has a directory created at "[zc root]/files/[quest name]/", and ONLY directories within this directory are accessible. All paths are relative to this directory. See: LoadDirectory

int Size;

Read-only. The number of files/folders contained in the directory.

bool GetFilename(int index, char32[] buf);

Loads the name of the 'index' file (0 <= index < Size) The name will be placed in the buffer Returns true if successful, false if it fails.

void Reload();

Refreshes the directory, updating the 'Size' and results of 'GetFilename()' to reflect any changes.

void Free();

This will deallocate the directory pointer, so that the pointer ID may be re-used. There is a limit to how many directory pointers may be allocated at once, so be sure to free them when you are no longer using them.

void Own();

Grants 'Ownership' of the directory pointer to the script that calls this function. When the script with 'Ownership' terminates (at the same time its' local arrays are deallocated), this directory pointer will automatically be 'Free()'d.

The Hero-> pointer holds various data and functions related to the player character. Player-> is an alternate token, which accesses the same functions.

int X; int Y; int Z;

Read/Write; These values store the player's position on each of the three axes. If the quest rule 'Sprite Coordinates are Float'at "ZScript->Quest Script Settings->Object" is checked, these values can include up to 4 decimal places; otherwise values are truncated to int.

int Jump;

The speed, in pixels per frame, that the Hero is moving upwards along the Z axis. Unless on the ground, the quest's Gravity is subtracted from this each frame (until it is lower than the terminal velocity value).

int Dir;

The direction the Hero is facing. The Hero may not face diagonally.

int Action;

Represents the Hero's current action state. Writing to this may cause various effects to occur, depending on what the value was previously, and what the new value is. Use the LA_ constants to access this.

int FakeZ;

The Hero's current FakeZ axis position. This value is treated as a second, separate Z axis; Sprites will be offset upwards by this amount when drawn just like the Z axis and shadows will draw if applicable; however, the sprite's hitbox will not be moved upwards into the Z Axis; instead it will be moved upwards on the Y axis, mimicking how Vires and Pols Voice worked in the original Zelda. This value is affected by 'FakeJump' instead of 'Jump'.

int FakeJump;

The current velocity on the FakeZ axis. This value is added to FakeZ every frame; and this value is decreased by the gravity value until it is lower than the terminal velocity value.

bool Climbing;

If true, the Hero is currently holding onto a Sideview Ladder.

bool JumpCount;

The number of jumps the player has jumped in mid-air since the last time they landed. If positive, resets to 0 when landing. Roc's Feathers allow you to jump in mid-air if this is less than the Extra Jumps count of the feather item.

int ItemA; int ItemB; int ItemX; int ItemY;

When reading these values, returns the item ID currently equipped to the given button. Returns '-1' if no item is equipped. When writing a value other than '-1', forcibly equips the given item to the given button (force-equip may or may not play nicely with engine active subscreens?). Writing '-1' will un-force-equip an item.

void SelectAWeapon(int dir); void SelectBWeapon(int dir); void SelectXWeapon(int dir); void SelectYWeapon(int dir);

Changes the item equipped to the given button, as though the engine subscreen selection was moved in the specified direction. DIR_RIGHT and DIR_LEFT for this work the same way as the engine's item quickswap right/left.

int SwordJinx; int ItemJinx;

Represents the duration of the Jinx status effects. The sword jinx prevents the Hero from using their sword, while the Item jinx prevents using all other items. If the value is '-1', the jinx is currently active, with no timer. If the value is '> 0', the jinx is currently active, with that many frames remaining until it wears off on its' own.

int Stun;

Represents the remaining duration of the Stun effect on the player. While stunned, the player cannot do almost anything.

int BunnyClk;

Represents the duration of the Bunny effect. If the value is '>0', the player is a Bunny for that many frames. If the value is '-1', the bunny effect is based on the current dmap being a bunny dmap, and the player not having a Pearl item. Values '-2' to '-99' are reserved for future engine use. If the value is '<= -100', the player will remain a bunny until a script changes this.

bool ClockActive;

If true, a 'Clock' item is active, rendering the player invincible and freezing all enemies.

int ClockTimer;

The remaining time on the 'Clock' effect. If this is 0, but 'ClockActive' is true, then the effect lasts until screen change.

int Drunk;

The value represents the duration of the Drunk status affect, and also affects the intensity of the effect. While active, messes with the players controls, randomly toggling their input (either pressing buttons they did not press, or un-pressing buttons they did press). The longer duration remaining, the higher the rate of input interference.

int Eaten;

The duration the player has been eaten (i.e. LikeLike) for, 0 if not eaten.

bool Grabbed;

True if the player has been grabbed (i.e. Wallmaster)

int HP; int MP; int MaxHP; int MaxMP;

Represents the Hero's health, magic, and the maxes for each of these.

int TileMod;

Read-only. Returns the current total 'Player Tile Modifier'. This is calculated by summing the PTM of all owned items'Active Use' shields only apply their PTM if they are in-use, instead applying a separate 'inactive PTM' if they are not in use. If the Hero is currently a Bunny, PTMs for items that are not 'Usable As Bunny' will not be applied, though the global 'Bunny PTM' will be..

int Tile;

The tile the engine animation has selected to display this frame for the player.

int Flip;

The flip value the engine animation has selected to display this frame for the player.

int CSet;

The cset value the engine animation has selected to display this frame for the player.

int ScriptTile;

If not '-1', this tile will override the engine's selected tile for the player.

int ScriptFlip;

If not '-1', this tile will override the engine's selected flip for the player.

int ScriptCSet;

If not '-1', this CSet will override the engine's selected cset for the player.

int Scale;

A scale that will be applied to the player's drawn size (does not affect hitbox)

int Rotation;

A rotation angle (in Degrees) that will be applied to the player's draw (does not affect hitbox)

int ShadowXOffset; int ShadowYOffset;

Offsets to the draw position of the Hero's shadow.

void Warp(int dmap, int screen);

Warps the player to the specified dmap/screen. Uses an 'Insta-Warp' type, and uses the 'A' return square.

void PitWarp(int dmap, int screen);

Same as 'Warp()', but instead of positioning the Hero at the 'A' return square, instead the Hero stays in the exact same position.

bool IsWarping;

Read-only, true if a warp is currently in progress.

void WarpEx(int[] ptr);

WarpEX takes an array pointer containing parameters, instead of a set of parameters. Valid parameter sets:

• Hero->WarpEx({type, dmap, screen, x, y, effect, sound, flags});
• Hero->WarpEx({type, dmap, screen, x, y, effect, sound, flags, forcedir});

Parameter descriptions:

• type: The warp type to use. Uses the WT_ constants. All insta-warp types act the same, and do not provide their warp effect.
• dmap / screen: the location to warp to
• x / y: These represent the position to spawn at, either using a return squareIf 'x < 0', use the `WARP_` constants for 'y' to specify one of the 4 return squares., pitwarpSetting both x and y '< 0', or 'x < 0' and 'y == 5', causes the player to stay in place., or coordinatesIf 'x > 0' and 'y > 0', the Hero will spawn on the new screen at those coordinates..
• effect: What warp effect to display (uses WARPEFFECT_Values representing various warp transition effects.
  0. WARPEFFECT_NONE
  1. WARPEFFECT_ZAP
  2. WARPEFFECT_WAVE
  3. WARPEFFECT_INSTANT
  4. WARPEFFECT_OPENWIPE
  constants)
• sound: An SFX to play during the warp.
• flags: See flag details below
• forcedir: If a direction is supplied for 'forcedir', the Hero will face that direction after the warp.

Warp flags use the WARP_FLAG_ constants, OR'd (|) together.

• WARP_FLAG_PLAYSOUNDSIf enabled, SFX will not be killed during the warp.
• WARP_FLAG_PLAYMUSICIf enabled, Music will not be killed during the warp.
• WARP_FLAG_SCRIPTDRAWIf enabled, script draws will remain during the warp.
• WARP_FLAG_SETENTRANCESCREENIf enabled, the 'last entrance screen' will be set by the warp.
• WARP_FLAG_SETENTRANCEDMAPIf enabled, the 'last entrance dmap' will be set by the warp.
• WARP_FLAG_SETCONTINUESCREENIf enabled, the 'continue screen' will be set by the warp.
• WARP_FLAG_SETCONTINUEDMAPIf enabled, the 'continue dmap' will be set by the warp.
• WARP_FLAG_DONTCLEARSPRITESIf enabled, sprite type objects (such as weapons, items, enemies) will not be destroyed, and will warp to the new screen with you.
• WARP_FLAG_CLEARITEMSClears items from the screen, even with WARP_FLAG_DONTCLEARSPRITES enabled.
• WARP_FLAG_CLEARGUYSClears enemies from the screen, even with WARP_FLAG_DONTCLEARSPRITES enabled.
• WARP_FLAG_CLEARLWEAPONSClears lweapons from the screen, even with WARP_FLAG_DONTCLEARSPRITES enabled.
• WARP_FLAG_CLEAREWEAPONSClears eweapons from the screen, even with WARP_FLAG_DONTCLEARSPRITES enabled.
• WARP_FLAG_CLEARHOOKSHOTClears hookshot weapons from the screen, even with WARP_FLAG_DONTCLEARSPRITES enabled.
• WARP_FLAG_CLEARDECORATIONSClears decorations from the screen, even with WARP_FLAG_DONTCLEARSPRITES enabled.
• WARP_FLAG_CLEARPARTICLESClears particles from the screen, even with WARP_FLAG_DONTCLEARSPRITES enabled.
• WARP_FLAG_NOSTEPFORWARDPrevents the 'step forward' animation that occurs on entering a dungeon screen from occurring after the warp.

void Explode(int mode);

Creates an effect of the Hero's sprite 'Exploding'. This creates a particle for each pixel of the Hero's visual sprite, which will move in a pattern based on the selected 'mode'. Modes:

0. Twilight
1. Sand of Hours
2. Farore's Wind

int InvFrames;

The number of frames the player is currently invulnerable (after being hit). Read/write.

bool InvFlicker;

If set false, the player with neither flash nor flicker when invincible.

int Defense[MAX_DEFENSE];

Represents the player's weapon defenses. Access using the 'NPCD_' constants for indexes, and the 'NPCDT_' constants for the values.

untyped HitBy[];

Access the following data indexes:

• HIT_BY_NPC - the Screen Index of the NPC that hit the player this frame.
• HIT_BY_NPC_UID - the UID of the NPC that hit the player this frame.
• HIT_BY_EWEAPON - the Screen Index of the EWEAPON that hit the player this frame.
• HIT_BY_EWEAPON_UID - the UID of the EWEAPON that hit the player this frame.
• HIT_BY_LWEAPON - the Screen Index of the LWEAPON that hit the player this frame.
• HIT_BY_LWEAPON_UID - the UID of the LWEAPON that hit the player this frame.

bool Item[NUM_ITEMDATA];

Access using Item IDs as indexes. Represents if the item is currently owned by the player. Read/Write.

int Step;

If the quest rule 'New Hero Movement'at "Quest->Options->Player" is enabled, this represents the move rate of the player, in 100ths pixel per frame (Default 150, i.e. 1.5 pixels per frame; changable in 'Init Data')

int Steps[8];

If the quest rule 'New Hero Movement'at "Quest->Options->Player" is NOT enabled, this array is used to move the player. When moving horizontally/vertically, the x/y modulo 8 determines which index is used, and that many pixels will be moved. Modifying this array requires care to actually accomplish anything, and it is highly recommended to enable the 'New Hero Movement' quest rule and use 'Hero->Step' above instead.

int HeldItem;

The item displayed above the Hero's head (requires them to be in an item holding Action).

int HealthBeep;

Normally between 70 and -1, representing the timer for a non-constant low health beep. Writing '-2' to this prevents the engine from stopping the SFX that is set as the health beep. Writing '-4' to this prevents the engine from both stopping and starting the SFX.

bool Invisible;

If set true, will prevent the player from being drawn.

bool NoStepForward;

If set true, prevents the 'step forward' that occurs when entering a dungeon room.

bool Animation;

If set false, disables the player's engine animation.

bool CollDetecton;

If set false, the player's engine collision will be disabled (i.e. player is invincible)

bool Diagonal;

If true, the Hero can move diagonally.

bool BigHitbox;

If true, the Hero's hitbox is 16x16 instead of 16x8.

bool Gravity;

If false, the player ignores gravity.

untyped Misc[32];

An array of 32 misc values for script use.

int LadderX; int LadderY;

The position the ladder is currently placed at.

int HurtSound;

The SFX played when the player is hurt.

int Pushing;

The number of frames the Hero has been pushing against something for.

int PitPullDir;

The direction the player is being pulled into a pit in.

int PitPullTimer;

The timer related to pit pulling

int Falling;

If >0, the player is falling down a pit. Decreases each frame. Max value 70.

int FallCombo;

The combo ID of the pit the player is currently falling into.

int Drowning;

TODO: needs docs

int DrownCombo;

The combo ID of the water the player is currently drowning in.

bool MoveFlags[];

Access the following flags:

• HEROMV_OBEYS_GRAVITY - If false, the player ignores gravity.
• HEROMV_CAN_PITFALL - If false, the player floats over pitfalls.
• HEROMV_NO_FAKE_Z - The player's Fake Z axis is disabled if true
• HEROMV_NO_REAL_Z - The player's Z axis is disabled if true

int RespawnX; int RespawnY; int RespawnDMap; int RespawnScreen;

The position, dmap, and screen that the player will respawn at when they drown or fall in a bottomless pit. Does nothing if 'Classic Respawn Points'at "Quest->Options->Combo" is enabled.

int SwitchTimer; int SwitchMaxTimer;

Timer values for the current switchhook effect. If 'SwitchTimer' is '>0', then a switchhook effect is currently active. When 'SwitchTimer' == 'SwitchMaxTimer / 2', the player will swap with the target object. Read-only.

bool SwitchCombo(int pos, int effect);

Switch the player with the given combo position. A hookable combo must be present at that position (on any valid layer) for this to succeed. Use the SW_EFF_ constants for 'effect' to select a visual style for the switch. Returns true if it succeeds, and false otherwise.

int Immortal;

If not 0, the player will not die, even when they have 0 hp. Effects such as bottled fairies will not trigger. If '>0', automatically decrements by 1 each frame. If this value becomes 0 while the player is at 0 hp, the death effect will trigger, including any bottled fairies.

void Kill(bool bypass_revive);

Immediately kills the player, setting their HP to 0, and ignoring 'Immortal'. If 'bypass_revive' is true, revival effects such as bottled fairies will not trigger, and the 'one frame before death' that scripts would use to revive will also be skipped.

RandGen Pointers

randgen randgen pointers reference specific random number generators. You can create and seed them yourself. Any randgen pointer with a value of NULL can be used to reference the engine's RNG. The global pointer RandGen-> is available as a null randgen pointer. See: LoadRNGUnder Construction!

int Rand();

Returns a random number -214748 to 214748, inclusive.

int Rand(int bound);

Returns a random number 0 to bound, inclusive.

int Rand(int bound1, int bound2);

Returns a random number bound1 to bound2, inclusive.

Note

All of these functions return integer values, with no decimal places.

long LRand();

Returns a random long number -2147483648L to 2147483647L, inclusive.

long LRand(int bound);

Returns a random long number 0L to bound, inclusive.

long LRand(int bound1, int bound2);

Returns a random long number bound1 to bound2, inclusive.

Note

All of these functions return long values. If you treat them as integer values, they will have decimal places.

void SRand(long seed);

Seeds the RNG with the given seed.

long SRand();

Seeds the RNG with a randomly-determined seed, based off of the system clock and the previous RNG. Returns the random seed.

void Free();

De-allocates this randgen pointer, so that its' pointer ID may be re-used. You may only have a limited number of randgen pointers active at a time; freeing them when you are done with them helps not reach the limit.

void Own();

Grants 'Ownership' of the randgen pointer to the script that calls this function. When the script with 'Ownership' terminates (at the same time its' local arrays are deallocated), this randgen pointer will automatically be 'Free()'d.

Stack Pointers

stack stack pointers allow storing and managing large sets of data, similar to arrays. The max storage of a stack is 2,147,483,647 elements, compared to arrays which have a maximum of 214,748 elements. Stacks also have various functions for accessing the data. See: LoadStackUnder Construction!

long Size;

Read-only. The size of the stack, given as a LONG. This means that a stack with 5 items will have a size of '5L'.

bool Full;

Read-only. Returns true if the stack cannot hold any more elements.

If the stack is full, Push functions will do nothing.

void PushBack(untyped val);

Adds the element 'val' to the end of the stack.

void PushFront(untyped val);

Adds the element 'val' to the beginning of the stack.

If the stack is empty, Pop and Peek functions will return '0', doing nothing else.

untyped PopBack();

Returns the last element in the stack, removing it from the stack in the process.

untyped PopFront();

Returns the first element in the stack, removing it from the stack in the process.

untyped PeekBack();

Returns the last element in the stack, without removing it.

untyped PeekFront();

Returns the first element in the stack, without removing it.

void Clear();

Removes every element from the stack.

untyped Get(long ind);

Returns the element at the index 'ind', which is a LONG value. This means that '0L' is the first element, '1L' is the second, etc. If an invalid index is given, '0' is returned.

void Set(long ind, untyped val);

Overwrites the element at the index 'ind' (which is a LONG value) with 'val'. This means that '0L' is the first element, '1L' is the second, etc. If an invalid index is given, nothing happens.

void Free();

De-allocates this stack pointer, so that its' pointer ID may be re-used. You may only have a limited number of stack pointers active at a time; freeing them when you are done with them helps not reach the limit.

void Own();

Grants 'Ownership' of the stack pointer to the script that calls this function. When the script with 'Ownership' terminates (at the same time its' local arrays are deallocated), this stack pointer will automatically be 'Free()'d.

BottleData Pointers

bottledata bottledata pointers allow accessing data relating to 'Bottle Types'. See: LoadBottleDataUnder Construction!

void GetName(char32[] str);

Loads the name of the bottledata into the provided string buffer.

void SetName(char32[] str);

Sets the name of the bottledata to the provided string.

int Counter[3];

The refill counters of this bottle type. Use the CR_ constants for these values.

int Amount[3];

The amount to refill each counter (0-65535)

bool IsPercent[3];

Whether the given counter refill is a percentage of max, instead of a direct value.

bool Flags[4];

A set of flags. Use the BTF_ constants to access this.

int NextType;

What bottle type will remain in the bottle after drinking the current type.

BottleShopData Pointers

bottleshopdata bottleshopdata pointers allow accessing data relating to 'Bottle Shop Types'. See: LoadBottleShopDataUnder Construction! Related: bottledata

void GetName(char32[] str);

Loads the name of the bottleshopdata into the provided string buffer.

void SetName(char32[] str);

Sets the name of the bottleshopdata to the provided string.

int Fill[3];

Which bottle type each index fills a bottle with. Related: bottledata

int Combo[3];

What combo to display as a visual for each index.

int CSet[3];

What CSet to use for the combo for each index.

int Price[3];

The price, in rupees (0-65535) to purchase each index.

int InfoString[3];

The message string to display upon purchasing each index.

DropsetData Pointers

dropsetdata dropsetdata pointers allow accessing dropsets, and using them to pick random items. See: LoadDropsetDataUnder Construction!

int Choose();

Randomly selects an item from the dropset, and returns its' ID. Returns -1 if nothing is chosen.

int Items[10];

The item IDs stored in this dropset.

int Chances[10];

The chances for each item to appear. These are not percentages, but weights; changing one will affect the odds of all of them.

int NothingChance;

The weighted value for no item being chosen at all.

MessageData Pointers

messagedata messagedata pointers allow accessing and editing message strings. See: LoadMessageDataUnder Construction!

void Get(char32[] str);

Loads the message into the provided string buffer.

void Set(char32[] str);

Sets the message to the provided string.

Note:

Message length is 72 characters maximum.

int X; int Y;

The X/Y position of the message box.

int Width; int Height;

The width/height of the message box, in pixels. If Old String Frame Width/Heightat Quest->Options->Compat is checked, the box will actually be 16 pixels wider and taller than is set here.

int Font;

The font to display the message in. Use the FONT_ constants for this value.

int VSpace; int HSpace;

The spacing between lines/characters, in pixels.

int Margins[4];

The margins, in pixels, from each edge of the text box. Use the DIR_ constants to access this. If Old String Marginsat Quest->Options->Compat is checked, these will not apply.

int Tile;

The tile used for the background. If the 'Full Tiled Background' flag is set, this is the top-left tile of a tile block the size of the message box. Otherwise, it is the top-left of a 2x2 square of tiles in a 'frame' style.

int CSet;

The CSet to draw the background in.

int PortraitTile;

The upper-left corner tile of the portrait. If set to 0, no portrait will be displayed.

int PortraitCSet;

The CSet to draw the portrait in

int PortraitX; int PortraitY;

The X/Y position of the portrait.

int PortraitTileWidth; int PortraitTileHeight;

The tile width/height of the portrait. Max 16 and 14 respectively. If either is '0', no portrait will be displayed.

int Next;

The 'next' message, which will be automatically displayed when this message finishes. If set to 0, no message will automatically follow this one.

int Sound;

The SFX to play when a new character is drawn (including spaces). If 0, no sound is played.

int ListPosition;

The list position of the messagedata as it is displayed in ZQ.

bool Flags[7];

A set of flags for the messagedata.

0. MSGFLAG_WRAP: If the text wraps around the bounding box
1. MSGFLAG_CONT: If the message is a continuation of the previous one
4. MSGFLAG_FULLTILE: If the background is 'Full Tiled'
5. MSGFLAG_TRANS_BG: If the background is transparent
6. MSGFLAG_TRANS_FG: If the text is transparent

int TextWidth(); int TextHeight();

Returns the width/height, in pixels, of the message text - not including line wrap / breaks. This is the width/height that would be used to call DrawStringUnder Construction! with this message string and font. TextHeight() is effectively the same as calling Text->FontHeight() using the message's font. TextWidth() is effectively the same as using messagedata->Get() to get the text into a ZScript string, and then passing that with the message's font to Text->StringWidth().

ShopData Pointers

shopdata shopdata pointers allow accessing data relating to 'Bottle Shop Types'. See: LoadShopDataUnder Construction!, LoadInfoShopDataUnder Construction!

int Type;

Read-only. Returns the type of the shop, where:

0. Invalid
1. Item Shop
2. Info Shop

int Item[3];

The 3 items available in the shop.

bool HasItem[3];

Whether a given position should have an item.

Note:

These values are only valid for item shops.

int Price[3];

The price, in rupees (0-65535) to purchase each index.

int String[3];

The message string to display upon purchasing each index.

MapData Pointers

mapdata mapdata pointers allow accessing data from any screen. Depending on how a mapdata pointer is loaded, it may represent a temporary current screenUnder Construction!, a temporary scrolling screenUnder Construction!, or a permanent screenUnder Construction!. Many parts of mapdata are shared with Screen->. See: LoadTempScreenUnder Construction!, LoadScrollingScreenUnder Construction!, LoadMapDataUnder Construction!

int Map;

Read-only. Returns the map this mapdata points to.

int Screen;

Read-only. Returns the screen this mapdata points to.

int FFCData[32]; int FFCCSet[32]; int FFCDelay[32]; int FFCX[32]; int FFCY[32]; int FFCVx[32]; int FFCVy[32]; int FFCAx[32]; int FFCAy[32]; int FFCFlags[32]; int FFCEffectWidth[32]; int FFCEffectHeight[32]; int FFCTileWidth[32]; int FFCTileHeight[32]; int FFCLink[32]; int FFCScript[32];

Access various properties of the 32 FFCs on the screen, remotely. See ffc for more information on each value. For int FFCFlags[32];, instead of being an array of boolean flags, each index is a bitwise flagset. To access, use bitwise operators and the FFCBF_ constants (which represent the same thing as their matching FFCF_ counterparts)

untyped GetFFCInitD(int ffc_index, int n); void SetFFCInitD(int ffc_index, int n, untyped value);

Access the InitD[n] for the specified FFC on the screen.

These functions and variables are shared between Screen-> and mapdata-> pointers. For Screen->, the 'current screen' is the screen the player is presently on, as a temporary screen. For mapdata->, it is whatever screen was loaded to create the mapdata pointer.

bool isSolid(int x, int y); bool isSolidLayer(int x, int y, int layer);

Returns true if the given x,y position on the screen is 'solid'. isSolid returns true if either layer 0,1, or 2 is solid isSolidLayer returns true only for the specified layer.

int ComboD[176];

The Combo ID placed at each position on the screen.

int ComboC[176];

The CSet of the combo placed at each position on the screen.

int ComboF[176];

The mapflag placed at each position on the screen.

int ComboI[176];

The inherent flag of the combo placed at each position on the screen. Writing to this changes the inherent flag for EVERY combo of that combo ID.

int ComboT[176];

The combo type of the combo placed at each position on the screen. Writing to this changes the combo type for EVERY combo of that combo ID.

int ComboS[176];

The solidity map of the combo placed at each position on the screen. Writing to this changes the solidity map for EVERY combo of that combo ID.

int ComboE[176];

The effect map of the combo placed at each position on the screen. Writing to this changes the effect map for EVERY combo of that combo ID.

Secret Combos

Secret combos are the combos that replace certain screen flags when secrets are triggered. When they replace, it replaces the Combo, Placed Flag, and CSet of the given location. Secret Combo data is indexed using the SECCMB_ constants.

int SecretCombo[SECCMB_MAX];

The combo that will be placed for each secret type.

int SecretCSet[SECCMB_MAX];

The cset that will be placed for each secret type.

int SecretFlags[SECCMB_MAX];

The screen flags that will be placed for each secret type.

Notes:

The index SECCMB_SECRETSNEXT is used for Secrets->Next flags, and does not make use of SecretCombo[] or SecretCSet[]; though it does make use of SecretFlags[].

int ItemSFX;

The SFX that will play when an item is held up on this screen.

int SecretSFX;

The SFX that will play when secrets are triggered on this screen.

int BossSFX;

The SFX for the boss roar on this screen.

int AmbientSFX;

The SFX for the ambient sound of the screen.

int MIDI;

The 'Screen MIDI' to play for this screen.

int Guy;

The screen guy.

int String;

The screen string.

int RoomType;

The screen room type. Use the RT_ constants for this value.

int Catchall;

The screen's 'catchall' value. This is the roomtype-specific data, such as the 'Special Item' in a 'Special Item' room.

int Item;

The item placed on the screen. -1 if no item placed.

int ItemX; int ItemY;

The X/Y position the screen's item spawns at.

Note:

Most of these arrays are indexed via the WARP_ constants; where WARP_A is 0, through WARP_D as 3.

int TileWarpType[4]; int SideWarpType[4];

The warp type of the given warp. Use the WT_ constants for these values.

bool TileWarpOverlay[4]; bool SideWarpOverlay[4];

The state of the Combos Carry Over checkbox for each warp.

int TileWarpDMap[4]; int TileWarpScreen[4]; int SideWarpDMap[4]; int SideWarpScreen[4];

The DMap and Screen that make up the destination of each warp.

int TileWarpReturnSquare[4]; int SideWarpReturnSquare[4];

The return square set as the destination for each warp. 0 = A, 3 = D.

int SideWarpID[4];

This array is indexed via the DIR_ constants, with the WARP_ constants as the values. Ex: SideWarpID[DIR_UP] = WARP_A; sets the Up sidewarp to use Side Warp A.

int WarpReturnX[4]; int WarpReturnY[4];

The X/Y coordinates of the 4 blue return squares

int WarpArrivalX; int WarpArrivalY;

The X/Y coordinates of the old green arrival square.

int TimedWarpTimer;

The timer used for executing a timed warp.

bool State[32];

The screen states used for this screen. Use the ST_ constants to access this.

int Script;

The screen script that runs on this screen.

untyped InitD[8];

The 8 script arguments for the script that runs on this screen.

int Palette;

The palette set in the F4 menu in ZQuest for this screen. Has no effect during play, but can be read and written.

int Door[4];

The 4 door states of the screen, indexed with the DIR_ constants. Use the D_ constants for the values.

int MazePath[4];

The four directions you must go for the maze path. Use the DIR_ constants for the values.

int Exitdir;

The direction that exits the maze path instantly. Use the DIR_ constants for the value.

int Enemy[10];

The 10 enemies that appear on this screen.

int Pattern;

The spawn pattern for the screen enemies. Use the PATTERN_ constants for the value. Related: Screen->SpawnScreenEnemies

int UnderCombo;

The screen's undercombo, which will appear as a result of various combo interactions, such as pushing blocks, awakening armos, etc.

int UnderCSet;

The CSet associated with the undercombo.

int CSensitive;

The value of damage combo sensitivity for the screen.

int NoReset;

The No Reset carryover flags.

int NoCarry;

The No Carry Over carryover flags.

int NextMap; int NextScreen;

The map and screen that screen states carry over to.

int LayerMap[7]; int LayerScreen[7];

The map and screen for each layer. Index [0] of these arrays does nothing, and is invalid to access.

int LayerOpacity[7];

The opacity value (OP_OPAQUE or OP_TRANS) for each layer. Index [0] does nothing, and is invalid to access.

bool LayerInvisible[7];

If true, the given layer is invisible and will not be drawn.

bool ScriptDraws[8];

If false, the given layer of script draws will be disabled on this screen.

bool Valid

Returns true if the screen is 'valid'. Screens that appear with the default blue background in ZQuest are 'invalid'. Modifying a combo on a screen makes it become 'valid'. If a layer is 'invalid', it will not be drawn.

int DoorComboSet;

The Door Set used for the NES dungeon doors on this screen.

int StairsX; int StairsY;

The X/Y position of the 'Stairs' secret on the screen.

untyped D[8];

A set of 8 misc values for each screen.

int Flags[];

Arrays containing flag data for each screen. To access these, use the following std_zh functions: int ScreenFlag(int category, int flag); int ScreenFlag(mapdata m, int category, int flag); Use the SF_ constants for category, and the matching set of either the SFR_, SFV_, SFS_, SFW_, SFI_, SFC_, SFSV_, SFF_, SFWH_, or SFM_ constants for flag.

int EFlags[];

Arrays containing flag data for each screen. To access these, use the following std_zh functions: int ScreenEFlag(int category, int flag); int ScreenEFlag(mapdata md, int category, int flag) Use the SEF_ constants for category, and the matching set of either the SEFSP_, SEFL1_, or SEFL2_ constants for flag.

int LensLayer;

Contains the special info for how the Lens of Truth affects layers of the screen. The lower 3 bits (LensLayer&111b) represent the layer, from 1 to 6, to affect. The 4th bit (LensLayer&1000b) indicates that the layer should be HIDDEN when the lens is active. The 5th bit (LensLayer&10000b) indicates that the layer should be HIDDEN when the lens is active.

Bitmap Pointers

bitmap bitmap pointers allow creating, manipulating, and storing visual data. A number of drawing commands from bitmap are shared with Screen->. See: CreateBitmapUnder Construction!, CreateUnder Construction!

These functions and variables are shared between Screen-> and bitmap-> pointers. For Screen->, draws go to the visible screen itself; while for bitmap->, draws go to the bitmap's stored pixels.

The Screen-> pointer holds various data pertaining to how each screen is made up, as well as various functions which draw to the screen, or create/load pointers to objects present on the screen.

bool Lit;

Whether or not the screen is 'lit'. Applies to Classic Darkrooms. Does nothing if 'New Dark Rooms'at "Quest->Options->Misc" is enabled.

int Wavy;

The remaining time, in frames, of the 'Wavy' visual effect. Decrements by 1 each frame. The wavy effect is more intense the higher the value is.

int Quake;

The remaining time, in frames, of the 'Quake' visual effect. Decrements by 1 each frame. The quake effect is more intense the higher the value is.

int NumItems(); int NumNPCs(); int NumLWeapons(); int NumEWeapons();

Returns the number of the given object type that are present on the current screen.

itemspriteUnder Construction! CreateItem(int id); npc CreateNPC(int id); lweaponUnder Construction! CreateLWeapon(int id); eweaponUnder Construction! CreateEWeapon(int id);

Creates a new sprite object, with the given ID. Use the LW_ and EW_ constants for CreateLWeapon()/CreateEWeapon(). Use the item editor IDs and enemy editor IDs for CreateItem()/CreateNPC().

itemspriteUnder Construction! LoadItem(int n); npc LoadNPC(int n); lweaponUnder Construction! LoadLWeapon(int n); eweaponUnder Construction! LoadEWeapon(int n);

Where 1 <= n <= NumObjects, returns a pointer to the nth object on the screen. Used to access itemsprites, npcs, lweapons, and eweapons that currently exist on the screen.

ffc LoadFFC(int n);

Returns a pointer to the nth FFC on the screen, where 1 <= n <= 32. Used to access ffcs that currently exist on the screen.

This data is all related to the current block being pushed on the screen.

int MovingBlockX; int MovingBlockY;

The X/Y position of the block. If no block is being moved, these will both return '-1'.

int MovingBlockLayer;

The layer of the block. Depending on some QRs, this may affect what combos the block interacts with. When the block 'clicks into place' after moving, it will be placed on this layer.

int MovingBlockCombo; int MovingBlockCSet;

The combo/cset used by the moving block. These affect how it is drawn during movement, and what combo/cset will be placed on the screen when movement ends.

void WavyIn(); void WavyOut();

Plays the warping screen 'wave' effect.

void ZapIn(); void ZapOut();

Plays the warping screen 'zap' effect.

void OpeningWipe(); void ClosingWipe();

Plays the warping screen 'wipe' effect, respecting the wipe-related QRs.

void OpeningWipe(int shape); void ClosingWipe(int shape);

Plays the warping screen 'wipe' effect with the specified shape, using the WIPE_ constants for the shape.

Related: messagedata, Message Strings

int ShowingMessage;

Read-only. The message ID of the messagestring currently showing on-screen. Reads 0 if no message is being displayed.

void Message(int msgID);

Displays the specified messagestring on the screen. If '0' is passed, closes any message that is already open on the screen.

bool SecretsTriggered();

Returns true if secrets have been triggered on this screen (including temp).

void TriggerSecrets();

Triggers secrets on this screen (temp only, write Screen->State[ST_SECRET] = true; to set the perm secret state) Does not play the screen's SecretSFX as part of the trigger.

void ClearSprites(int spritelist);

Kills all sprite objects of the specified type, using the SL_ constants. Ex: Screen->ClearSprites(SL_GUYS); will delete all enemies on the screen.

bool SpawnScreenEnemies();

Immediately attempts to spawn the screen's enemies, using the screen's pattern. Returns true on success, false on failure. Fails if enemies are still in the middle of entering from the sides, or if the screen's pattern is PATTERN_NO_SPAWNING.

The Audio-> pointer holds various functions relating to SFX, MIDI, and Enhanced Music.

void PlaySound(int sfx);

Plays the quest SFX 'sfx'.

void EndSound(int sfx);

If 'sfx' is playing, immediately stop it.

void PauseSound(int sfx);

If 'sfx' is playing, pause it (so that it may be resumed later).

void ResumeSound(int sfx); void ContinueSound(int sfx);

Resume 'sfx' from where it was paused.

void PlayMIDI(int midi);

Plays the MIDI 'midi'. Will revert upon changing screens.

void PauseCurMIDI();

Pauses the currently playing MIDI so that it may be resumed later.

void ResumeCurMIDI();

Resumes the previously paused MIDI.

bool PlayEnhancedMusic(char32[] filenameMax 255 characters Valid Extensions: ogg, mp3, spc, gbs, vgm, gym, nsf, it, xm, s3m, mod, int track);

Plays the specified enhanced music, if it's available. If the music format does not support tracks, the track argument is ignored. 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.

void AdjustMusicVolume(int percent);

Adjusts the music volume (MIDI and Enhanced Music) to 'percent'% of the user's setting.

void AdjustSFXVolume(int percent);

Adjusts the SFX volume to 'percent'% of the user's setting.

Note:

These set the volume relative to the user's original setting. If the user has a slider set to 0, no amount of calls will make it play sound. If the user has the slider at max, no amount of calls can make it any louder. Example: Assume the user has SFX volume at '32', and MIDI volume at '128'. Audio->AdjustSFXVolume(200); //SFX volume is now '64' Audio->AdjustMusicVolume(50); //MIDI volume is now '64' Audio->AdjustSFXVolume(150); //SFX volume is now '48' Audio->AdjustMusicVolume(100); //MIDI volume is now '128'

int PanStyle;

The audio panning style. Use the PAN_ constants for this value.

The FileSystem-> pointer holds misc functions related to files and directories. Paths are often relative to a 'quest specific directory', which is at "[zc root]/files/[quest name]/" Related: file, directory

bool FileExists(char32[] "filepath"); bool DirExists(char32[] "dirpath");

Returns true if the file/dir specified by the given path exists. If "All bitmap-> and FileSystem-> paths relative to quest 'Files' folder"at "ZScript->Quest Script Settings->Instructions" is enabled, paths are relative to the quest's specific directory; otherwise they are relative to the ZC folder.

bool Remove(char32[] "filepath");

Deletes the file pointed to by 'filepath'. Path is relative to the quest's specific directory.

directory LoadDirectory(char32[] dirpath);

Opens the directory pointed to by 'dirpath'

The Text-> pointer holds various functions relating to text/fonts.

int FontHeight(int font); int CharHeight(char32 c, int font); int StringHeight(char32[] s, int font);

Returns the height of 'font', in pixels. int MessageHeight(int msg); Returns the height of the font assigned to the 'msg' messagedata.

int CharWidth(char32 c, int font); int StringWidth(char32[] s, int font);

Returns the width of the character 'c' or string 's', in the given font, as 'DrawStringUnder Construction!' would draw it.

int MessageWidth(int msg);

Returns the width of the messagedata 'msg', as 'DrawStringUnder Construction!' would draw it.

The Graphics-> pointer holds various functions relating to visual effects.

void Tint(int red, int green, int blue); void MonochromeHue(int red, int green, int blue, bool distributed);

Tints the palette by adding red, green, and blue to the respective values of every palette swatch. Subsequent calls to these functions will SUM the tint with all previous tints. If MonochromeHue is used, the palette will be greyscaled (either via a uniform or distributed greyscale, based on the 'distributed' bool) before the tint is applied.

void ClearTint();

Clears all tint effects.

int NumDraws();

Returns the number of script drawing commands that are currently waiting in the draw queue.

int MaxDraws();

Returns the limit of the drawing queue. If NumDraws() returns the same as this, no further drawing commands will work until the queue has been cleared (i.e. the next frame)

void Wavy(bool style_in);

Creates a 'wave' effect, as a 'Wavy' warp type uses. There are both 'in' and 'out' styles; if style_in is true, then the 'in' style is used; else the 'out' style is used.

void Zap(bool style_in);

Creates a 'zap' effect, as a 'Zap' warp type uses. There are both 'in' and 'out' styles; if style_in is true, then the 'in' style is used; else the 'out' style is used.

bool IsBlankTile[214500];

Read-only. True if the given tile is entirely blank (all color 0).

void Greyscale(bool enable);

Enables or disables 'greyscale' mode. MonochromeHue() works similarly, but with more options.

void Monochrome(int preset);

Activates a monochrome preset.

0. TINT_NONE
1. TINT_GREY
2. TINT_RED
3. TINT_GREEN
4. TINT_BLUE
5. TINT_VIOLET
6. TINT_TEAL
7. TINT_AMBER
8. TINT_CYAN

To use a distributed monochrome mode, add TINT_MODE_DISTRIBUTED to the preset.

The Input-> pointer holds various values relating to button, mouse, and keyboard input.

int KeyBindings[14];

For each index (using CB_ constants to access), the keyboard key (KEY_ constants) that is bound to that button.

bool Button[CB_MAX]; bool Press[CB_MAX];

Whether the given button (CB_ constants) is down (or 'pressed'). 'Press' indicates this was the first frame the button is down, while 'Button' indicates only that the button is down, with no regard for how long it has been down. These are the same as the old Hero->InputBUTTON and Hero->PressBUTTON values, but as arrays.

bool Key[KEY_MAX];

Returns true if the respective key is down this frame (similar to Button[], but for keys instead of buttons).

bool KeyPress[KEY_MAX];

Returns true if the respective key was just pressed this frame (similar to Press[], but for keys instead of buttons).

int ModifierKeys;

Returns the modifier keys as a bitwise flagset.

bool KeyRaw[KEY_MAX];

Attempts to directly access the allegro keyboard. Usually using 'Key[]' and 'KeyPress[]' is safer, though in some edge cases this may be useful.

int Mouse[6];

0. MOUSE_X: the X position of the mouse
1. MOUSE_Y: the Y position of the mouse
2. MOUSE_Z: the Z position of the mouse (scrollwheel)
3. MOUSE_LEFT: bool, true if the left mouse button is down.
4. MOUSE_RIGHT: bool, true if the right mouse button is down.
5. MOUSE_MIDDLE: bool, true if the middle mouse button is down.

bool DisableButton[CB_MAX];

Whether a given button (CB_ constants) is disabled from having any in-engine effect.

bool DisableKey[KEY_MAX];

Whether a given keyboard key (KEY_ constants) is disabled from having any in-engine effect. Certain keys, such as F9 for reset system, will work regardless of this setting.