ZScript Docs | ZeldaClassic.com

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 Sept. 5th, 2021 for 2.55 A96 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.

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.

No Shadow
Basic shadow, no text
'U' shadow, no text
Full outline shadow, no text
'+' outline shadow, no text
'X' outline shadow, no text
Basic shadow, behind text
'U' shadow, behind text
Full outline shadow, behind text
'+' outline shadow, behind text
'X' outline shadow, behind text

Values representing various warp transition effects.

WARPEFFECT_NONE
WARPEFFECT_ZAP
WARPEFFECT_WAVE
WARPEFFECT_INSTANT
WARPEFFECT_OPENWIPE

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.

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:

RTC_YEAR: Returns the year
RTC_MONTH: Returns the month, with 1 = January
RTC_DAYOFMONTH: Returns the day of the month, 1-31
RTC_DAYOFWEEK: Returns the day of the week, 1 = Sunday
RTC_HOUR: Returns the current hour, 0-23
RTC_MINUTE: Returns the current minute, 0-59
RTC_SECOND: Returns the current second, 0-60 (only 60 for leap seconds on certain systems)
RTC_DAYOFYEAR: Returns the day of the year, 0-365
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.

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. Note that this does not affect the active output console window at this time, though it may in the future.

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.

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.

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.

MSGFLAG_WRAP: If the text wraps around the bounding box
MSGFLAG_CONT: If the message is a continuation of the previous one
MSGFLAG_FULLTILE: If the background is 'Full Tiled'
MSGFLAG_TRANS_BG: If the background is transparent
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().

TODO: Shadow effects are not yet accessible!

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:

Invalid
Item Shop
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.

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.

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 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.

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 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.

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.

bool SpawnScreenEnemies();

TODO: Currently only available on Screen->. May be added to mapdata-> later! Immediately spawns the 10 screen enemies, using the screen's pattern. Returns true if successful. Fails if enemies are still entering from the sides, or if the screen's pattern is PATTERN_NO_SPAWNING.

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.

Secret Combos

Secret combos are the combos that replace certain screen flags when secretsUnder Construction! 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[].

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.

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 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.

TINT_NONE
TINT_GREY
TINT_RED
TINT_GREEN
TINT_BLUE
TINT_VIOLET
TINT_TEAL
TINT_AMBER
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];

MOUSE_X: the X position of the mouse
MOUSE_Y: the Y position of the mouse
MOUSE_Z: the Z position of the mouse (scrollwheel)
MOUSE_LEFT: bool, true if the left mouse button is down.
MOUSE_RIGHT: bool, true if the right mouse button is down.
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.