ZScript Documentation (WIP)

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

Quest Rules

Quest Rules are global settings configurable in ZQuest. Scripts can read and modify these settings using Game->FFRules. To find a QR by name, go to Quest->Options->Search QRs in ZQuest.

TODO: Add IC_ constant infopage

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.

This section is dedicated to the underlying mechanics of ZScript. This section will cover everything from the basics of if, else, while, for, etc all the way up to class, namespace, etc. TODO: Under construction!

The Debug-> pointer holds some internal debug variables. You probably won't need to use it.

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: LoadNPC, CreateNPC

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 is checked, these values can include up to 4 decimal places; otherwise values are truncated.

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.

Weapon Pointers

lweapon, eweapon These pointers represent weapon objects on screen. lweapon pointers represent the player's weapons, while eweapon pointers represent enemy weapons. See: LoadLWeapon, CreateLWeapon, LoadEWeapon, CreateEWeapon

EWeapon Exclusive

npc Parent;

The npc pointer to the parent NPC.

LWeapon Exclusive

int Parent;

The item ID of the parent item.

int Weapon;

The UseWeapon property for this weapon. If set to a value greater than 0, this value will be used instead of the weapon's type when interacting with npcs and triggers. Uses LW_ constants.

int Defense;

The default defense of the weapon. If set to a value greater than 0, this defense will be used instead of the (None) defense when hitting enemies. Uses NPCDT_ constants.

int Special;

The special info for the lweapon. Used by wind lweapons, instead of Level, to determine their effects.

int ID; int Type; int Family;

The weapon type of the weapon. Some types have hardcoded behaviors.

bool isValid();

Returns true if this pointer points to a valid weapon. If this returns false, using any other value of this pointer will error.

int Level;

For lweapons, the level of the weapon. For eweapons, bitwise. The 1 bit represents it being a "boss" weapon (ex. 'boss fireball')

int Dir;

The weapon's direction.

float Angle; float DegAngle;

The angle of the weapon, in radians for Angle or degrees for DegAngle. Has no real effect if the weapon is not Angular.

bool Angular;

If the weapon is angular (instead of directional)

void MakeAngular();

If the weapon is not Angular, makes it Angular, and sets its' Angle based on its' Dir.

void MakeDirectional();

If the weapon is Angular, makes it not Angular, and sets its' Dir based on its' Angle.

float Vx; float Vy;

The velocity on the X or Y axis. Setting these will make the weapon Angular if it isn't already, and will adjust the weapon's Angle and Step speed.

bool Animation;

If the engine should animate the weapon's graphics.

int X; int Y; int Z;

Read/Write; These values store the weapon's position on each of the three axes. If the quest rule Sprite Coordinates are Float is checked, these values can include up to 4 decimal places; otherwise values are truncated.

int Jump;

The weapon's upward velocity, in pixels per frame. Affected by gravity each frame, if gravity is enabled for this weapon.

bool Gravity;

True by default. If false, gravity will no longer affect this weapon.

bool MoveFlags[];

The movement flags of the weapon. See WPNMV_ constants.

int FakeZ;

The position of the weapon on the FakeZ axis.

int FakeJump;

The velocity of the weapon in the FakeZ axis.

int Max();

Returns the max number of itemsprites currently allowed.

void Max(int newmax);

Sets the max number of itemsprites allowed to a new value. Range 1-1024.

int OriginalTile;

The starting tile of the weapon's animation.

int Tile;

The currently displaying tile of the weapon's animation. Set by the engine each frame if animation is enabled.

int OriginalCSet;

The starting cset of the weapon.

int CSet;

The CSet of the weapon.

int NumFrames;

The number of frames in the weapon's animation.

int Frame;

The current frame number that the animation is on.

int ASpeed;

The speed of the animation, in frames per frame.

bool Flash;

If the weapon is flashing or not. When flashing, it changes between its' CSet and FlashCSet.

int FlashCSet;

The secondary CSet used for flashing.

int Flip;

The flip status of the weapon's tile. Uses the FLIP_FLIP_NONE = 0 FLIP_HORIZONTAL = 1 FLIP_VERTICAL = 2 FLIP_HV = 3 FLIP_VH = 3 FLIP_BOTH = 3 //rotation and flip ROT_CW = 4 ROT_CW_FLIP = 5 ROT_CCW_FLIP = 6 ROT_CCW = 7 constants.

void UseSprite(int spriteid);

Loads the graphical information from the spritedata indicated by spriteid to the weapon.

int ScriptTile;

-1 by default. If this is set > -1, this tile will be displayed by the engine, regardless of the normal engine animation. Set back to -1 to restore engine animation.

int ScriptFlip;

-1 by default. If this is set > -1, this flip value will be used instead of the normal 'Flip' value. Set back to -1 to restore normal flip.

int ShadowXOffset; int ShadowYOffset;

The x/y offset of the sprite's shadow.

int ShadowSprite;

The spritedata sprite ID to use for the item's shadow.

int DrawStyle;

The mode for the sprite's draws, using the DS_ constants.

float Rotation;

A rotation of the sprite draw, in degrees.

float Scale;

A scale of the sprite draw, as a multiplier.

bool AutoRotate;

If true, the weapon's 'Rotation' will be automatically set based on its' Angle.

int LightShape;

The shape of light emitted by this sprite. Uses the LIGHT_ constants.

int LightRadius;

The size of the light emitted by this sprite, in pixels.

int Extend;

If the item sprite should be extended (large). Set to 3 to extend, 0 otherwise.

int HitWidth; int HitHeight;

The width/height of the hitbox, in pixels.

int HitZHeight;

The height of the hitbox in the Z-axis, in pixels.

int TileWidth; int TileHeight;

The width/height of the sprite's graphic, in tiles.

int DrawXOffset; int DrawYOffset;

The visual offset, in pixels.

int TotalDYOffset;

Read-only, the weapon's total visual Y-offset.

int DrawZOffset;

The Z offset, in pixels.

int HitXOffset; int HitYOffset;

The hitbox offset, in pixels.

int Script;

The weapon script running on this weapon.

int InitD[8];

The 8 InitD[] arguments for the weapon script.

int Misc[32];

An array of misc values for script use.

int Falling;

The timer indicating how long left the sprite will be falling. If 0, the sprite is not falling. Max value of 70, which is the value at the start of falling.

int FallCombo;

The pitfall combo the sprite is falling into, if it is falling.

int Drowning;

The timer indicating how long left the sprite will be drowning. If 0, the sprite is not drowning. Max value of 64, which is the value at the start of drowning.

int DrownCombo;

The liquid combo the sprite is drowning in, if it is drowning.

bool SwitchHooked;

If the sprite is currently being switch-hooked.

bool Switch(int effect);

Switch the player with this sprite. Use the SW_EFF_ constants for 'effect' to select a visual style for the switch. Returns true if it succeeds, and false otherwise.

void Explode(int mode);

Creates an explosion particle effect in mode 0, 1, or 2 of the sprite.

void Remove();

Instantly deletes the weapon.

int DeadState;

The deadstate of the weapon, denoted by the WDS_ constants.

int Step;

The movement speed of the weapon, in 100th's/pixel per frame.

int Power; int Damage;

The amount of damage the weapon deals.

bool Behind;

If true, the weapon's sprite will draw behind the player and enemies.

int Unblockable;

A bitwise flagset of unblockable flags, using the UNBLOCK_ constants.

bool CollDetection;

If the weapon's collision is enabled. Set to false to disable collision entirely.

bool Flags[1];

A set of weapon flags. Use the WFLAG_ constants as indexes.

ComboData Pointers

combodata These pointers represent a combo ID, and all its' associated attributes. See: LoadComboData

int ID;

Read-only, the combo ID this combodata points to.

int Script;

The combo script that this combo runs.

untyped InitD[2];

The 2 InitD[] values for the combo script.

int Tile;

The tile currently being displayed by the combo. This is automatically overwritten each frame by the engine.

int Frame;

The current animation frame the combo is on in its' animation. Set to 0 to reset to start of animation.

int AClk;

The animation clock of the combo. Set to 0 to reset the timer.

int OriginalTile;

The 'Original Tile' of the combo, used as the start of its' animation.

int Frames;

The number of frames in the combo animation before it loops.

int ASpeed;

The combo animation speed.

int SkipAnimX;

The number of extra tiles to move horizontally between each frame.

int SkipAnimY;

The number of extra tiles to move vertically, when the horizontal movement goes past the end of a tile row.

int AnimFlags;

Bitwise access to the combo's animation flags. Use the AF_ constantsBitwise values used to access combodata->AnimFlags

• AF_FRESH: Refresh Animation on Room Entry
• AF_CYCLE: Refresh Animation When Cycled To
• AF_CYCLENOCSET: Cycle ignores CSet
• AF_TRANSPARENT: Toggle Transparent

to access.

int Flip;

The combo's flip value. Use the FLIP_ or ROT_ constants from std_constants.zh for this value.

int CSet2;

The CSet2 offset for this combo.

int CSet2Flags;

Bitwise access to the 4 corners of the cset2 square. TODO: Untested!

These attributes are ONLY usable on the this pointer in a combodata script.

int X; int Y; int Layer; int Pos;

Read-only. Gives the X, Y, Layer, and Combo Pos of the combo running this script.

int Walk;

The solidity bitmask of the combo (same as Screen->ComboS[])

int Effect;

The effect bitmask of the combo (same as Screen->ComboE[])

int Type;

The combo typeUnder Construction! of the combo. Use the CT_ constants from std_constants.zh.

int Flag;

The inherent flagUnder Construction! of the combo. Use the CF_ constants from std_constants.zh.

int NextData;

If > 0, cycling is enabled for this combo. When the combo's animation would normally loop, instead the combo will change to the NextData combo.

int NextCSet;

If the animation flag AF_CYCLENOCSET is NOT set, the combo will change to this cset when it cycles.

untyped Attribytes[8];

The 8 combo attribytes. These have a byte-sized range, 0 to 255. Their effect depends on the combo type.

untyped Attrishorts[8];

The 8 combo attrishorts. These have a short-sized range, -32768 to 32767. Their effect depends on the combo type.

untyped Attributes[4];

The 4 combo attributes. These have a full range (all zscript values, including decimal). Their effect depends on the combo type.

bool Flags[16];

The 16 combo flags. Their effect depends on the combo type.

bool GenFlags[];

The combo generic flags, specified by the GENFLAG_ constantsIndexes for combodata->GenFlags[]

0. GENFLAG_HOOKSHOTTABLE: Hook-Grabbable
1. GENFLAG_SWITCHHOOKABLE: Switch-Hookable

.

bool TrigFlags[];

The combo's Trigger Flags, accessed with the TRIGFLAG_ constants.

bool TriggerButton[];

Which buttons

0. INTBTN_A
1. INTBTN_B
2. INTBTN_L
3. INTBTN_R
4. INTBTN_EX1
5. INTBTN_EX2
6. INTBTN_EX3
7. INTBTN_EX4

will trigger this combo (Which directions this works from is determined by TRIGFLAG_BTN_ triggerflags)

int TriggerLevel;

The min level (or max, if TRIGFLAG_INVERT_MIN_MAX is set) of Weapon that can trigger this combo.

int TriggerItem;

Note: This is a Trigger RequirementThis condition does not trigger the combo itself- instead, when something tries to trigger this combo, it must ALSO pass this condition. To make this act as a trigger in itself, combine with the 'Always Triggered' (TRIGFLAG_AUTO) flag., not a trigger. The required item ID for triggering the combo. If 0, no item is required. If TRIGFLAG_INVERT_ITEMREQ is set, the item must NOT be owned to trigger instead. If TRIGFLAG_CONSUME_ITEMREQ is set, the item will be consumed upon triggering.

int TriggerTimer;

The trigger timer. If > 0, the combo triggers every this many frames.

int TriggerSFX;

The SFX to play when triggering the combo.

int TriggerChange;

The amount the combo will change by when triggered.

int TrigCSetChange;

The amount the cset will change by when triggered.

int TriggerProximity;

Note: This is a Trigger RequirementThis condition does not trigger the combo itself- instead, when something tries to trigger this combo, it must ALSO pass this condition. To make this act as a trigger in itself, combine with the 'Always Triggered' (TRIGFLAG_AUTO) flag., not a trigger. The combo will only trigger if the player's distance from the combo is <= this distance. If 0, proximity requirement is disabled. If TRIGFLAG_INVERT_PROXIMITY is set, the player's distance must be > this distance instead.

int TriggerLightBeam;

The light beam ID that this combo interacts with. 0 interacts with all beams, 1 to 32 interact only with matching beams. This only has any effect if TRIGFLAG_LIGHTON or TRIGFLAG_LIGHTOFF is set.

int TriggerCounter;

The counter used for counter-based trigger flags.

int TriggerCtrAmount;

The counter amount used for counter-based trigger flags.

int TrigCooldown;

The combo (assuming it does not change on trigger) will be unable to trigger again for this many frames after triggering.

int TrigCopycat;

If > 0, when this combo is triggered, it will trigger all other combos on screen with the same TrigCopycat value.

int TrigExState;

If > -1, the ExState this combo is linked to.

int TrigSpawnEnemy;

If > 0, this enemy ID will be spawned when the combo triggers.

int TrigSpawnItem;

If > 0, this item ID will be spawned when the combo triggers. If < 0, an item from this dropset ID will be chosen to be spawned when the combo triggers.

int TrigSpawnItemPickup;

The ->Pickup flags for the spawned item. Only IP_HOLDUP, IP_TIMEOUT, IP_TRIGGERSECRETS, and IP_ALWAYSGRAB are valid.

int LiftGFXType;

What GFX to use to display the lifted object.

int LiftGFXCombo; int LiftGFXCSet;

The GFX combo/cset used to display the object, if 'Other Combo GFX' is the GFX mode. The combo's CSet is used instead if LF_NOWPNCMBCSET is set.

int LiftGFXSprite;

The GFX sprite used to display the object, if 'Sprite Data GFX' is the GFX mode.

int LiftBreakSprite;

The Sprite Data sprite displayed when the object breaks.

int LiftUnderCombo; int LiftUnderCSet;

The combo/cset that will be left behind when this combo is lifted. If LF_NOUCSET is set, the undercset will not be used, instead leaving the combo's cset.

int LiftDamage;

The weapon damage of the thrown object.

int LiftLevel;

The minimum lift glove level required to lift this object.

int LiftItem;

If > 0, drops this item ID. Drops the item upon breaking, unless LF_DROPONLIFT is set, in which case it drops upon lifting. If LF_DROPSET is set, this number is a dropset to choose an item from, instead of an item ID. If LF_SPECIALITEM is set, this item is treated as the room's Special Item.

int LiftSFX;

The SFX played on lifting.

int LiftBreakSFX;

The SFX played on breaking.

int LiftHeight;

The height above the player's head to lift the object.

int LiftTime;

The number of frames it takes to lift the object to its' full height.

int LiftFlags[];

The combo lift flags.

DMapData Pointers

dmapdata These pointers represent a dmap and all its' associated attributes. See: LoadDMapData

void GetName(char32[] bufAt least size 21);

Fills the buffer with the dmap's name.

void SetName(char32[] bufAt most 20 characters);

Sets the DMap's name to the buffer contents.

void GetTitle(char32[] bufAt least size 21);

Fills the buffer with the dmap's title.

void SetTitle(char32[] bufAt most 20 characters);

Sets the DMap's title to the buffer contents.

void GetIntro(char32[] bufAt least size 73);

Fills the buffer with the dmap's intro.

void SetIntro(char32[] bufAt most 72 characters);

Sets the DMap's intro to the buffer contents.

void GetMusic(char32[] bufAt least size 56);

Fills the buffer with the dmap's enhanced music filename. See MusicTrack.

void SetMusic(char32[] bufAt most 55 characters);

Sets the DMap's enhanced music filename to the buffer contents. See MusicTrack.

int ID;

Read-Only. The DMap's ID number.

int Map;

Which map this DMap is associated with.

int Level;

The Level Number of this dmap.

int Compass; int Continue;

The compass marker and continue screen numbers.

int Offset;

The DMap offset.

int Type;

The type of the dmap, using the DMAP_

0. DMAP_DUNGEON
1. DMAP_OVERWORLD
2. DMAP_CAVE
3. DMAP_BSOVERWORLD

constants.

int Palette;

The level palette to use for this DMap

int MIDI;

The MIDI set to play on this dmap.

int MusicTrack;

The track number to use for enhanced music. See GetMusic/SetMusic.

int Script;

The dmapdata script to run on this dmap.

untyped InitD[8];

The 8 InitD values for the active dmap script.

int ActiveSubscreen;

Which engine active subscreen to use on this dmap.

int PassiveSubscreen;

Which engine passive subscreen to use on this dmap.

int ASubScript;

Which dmapdata script to use as a replacement for the engine active subscreen (0 for none).

int PSubScript;

Which dmapdata script to run for passive subscreen draws.

untyped SubInitD[8];

The 8 InitD values shared by the Active and Passive Subscreen Scripts.

int MapScript;

Which dmapdata script to use as a replacement for the engine fullscreen map (0 for none).

untyped MapInitD[8];

The 8 InitD values used by the Map Script.

int Grid[8];

Bitwise values representing the state of the map grid. Make use of the functions in std_zh/dmapgrid.zh to access these values.

int Charted[128];

Stores the large map exploration data for each screen on the dmap. TODO: Test if works on overworld dmaps. Data is stored in a bitwise format. Access each index using the CHRT_CHRT_VISITED = 10000000b CHRT_UP = 00000001b CHRT_DOWN = 00000010b CHRT_LEFT = 00000100b CHRT_RIGHT = 00001000b constants

int MapTile[2];

The tile used for the engine subscreen Large Map. The [0] index tile is used without the dungeon map, and the [1] index with the dungeon map. If a tile is '0', the default background is used. TODO: What's the default here?

int MapCSet[2];

The csets used for the engine subscreen Large Map, to go along with the MapTile[].

int MiniMapTile[2];

The tile used for the engine subscreen Small Map. The [0] index tile is used without the dungeon map, and the [1] index with the dungeon map. If a tile is '0', the default background is used. The default is set in 'Graphics->Map Styles' in ZQuest.

int MiniMapCSet[2];

The csets used for the engine subscreen Small Map, to go along with the MiniMapTile[].

bool DisabledItems[NUM_ITEMDATA];

If each item on the dmap is disabled.

int MirrorDMap;

The DMap ID that using a Mirror will take you to. If this is '-1', Mirrors will not be able to warp you to another dmap. If the flag 'Mirror Continues instead of Warping' is set, the mirror dmap setting is not used.

bool Sideview;

If true, the dmap is treated as sideview by default; screens with the sideview flag enabled will toggle sideview back *off*.

bool Flagset[DMFS_MAX];

The flags for the dmap. Uses the DMFS_ constants.

ItemData Pointers

itemdata These pointers represent an inventory item and all its' associated attributes. See: LoadItemData

int ID;

Read-only, the item ID this itemdata is associated with.

bool EquipmentItem;

If the item is an equipment item or not. Items which are not equipment items cannot be "owned" by the player or put on buttons.

int Family; int Type;

The type (itemclass) of the item. Uses the IC_ constants.

int Level;

The level of the item.

int Power; int Damage;

The item power. Usage depends on itemclass.

untyped Attributes[10];

The 10 item attributes.

void GetName(char32 buf[]);

Fills the buffer with the item's Name.

int Amount;

The amount of the 'Counter' to increase when this item is picked up. Range -9999 to 16383.

bool Gradual;

The 'Gradual' flag.

int Counter;

The counter to increase when this item is picked up.

int MaxIncrement;

How much to increase the max of the 'Counter' by

int Max;

The '...But not above' field- the amount the max of 'Counter' will not be increased above.

int PickupSound;

The sound to play when the item is picked up.

int MinHearts;

The number of max hearts required to pick up the item.

bool KeepOld;

The 'Keep Lower Level Items' flag

bool GainLower;

The 'Gain All Lower Level Items' flag

bool Combine;

The 'Upgrade When Collected Twice' flag

int PString; int PickupString;

The message string to display upon picking up the item.

int PickupStringFlags;

The flags associated with the pickup string, as bitwise flags. Use the IPSTR_ constants to access this.

int UseSound;

The item's usage sound. If/how this is used depends on itemclass.

int UseSound2;

The item's second usage sound. If/how this is used depends on itemclass.

bool Downgrade;

The 'Remove Item When Used' flag.

int Cost; int Cost2;

The 'Use Cost'/'Use Cost 2' of the item.

int CostCounter; int CostCounter2;

The counter for the 'Use Cost'/'Use Cost 2' of the item.

int CostTimer; int CostTimer2;

The timer for the 'Use Cost'/'Use Cost 2' of the item.

bool Validate; bool Validate2;

The 'Only Validate Cost'/'Only Validate Cost 2' checkboxes

int Script;

The item's Action Script

int PScript;

The item's Pickup Script

int SpriteScript;

The item's ItemSprite Script

untyped InitD[8];

The 8 InitD values shared by the item's Action, Pickup, and Sprite scripts.

void RunScript(int mode = ISCR_RUN);

Runs or ends the item script, depending on the mode:

int WeaponScript;

The item's lweapon script

untyped WeaponInitD[8];

The 8 InitD values for the weapon script.

bool Flags[16];

The 16 item flags. Flags[0] through Flags[14] change depending on the item type; Flags[15] is the Constant Script flag.

bool Edible;

The Can Be Eaten By Enemies flag.

bool ConstantScript;

The Constant Script flag.

bool SideSwimDisabled;

The Disabled In Sideview Water flag.

bool BunnyUsable;

The Usable as a Bunny flag.

bool JinxImmune;

The Immune to jinxes flag.

bool JinxSwapped;

The Uses Other Jinx flag.

int Pickup;

The item pickup flags, as a bitwise flagset. Use the IP_ constants to access. Take care when using any INTERNAL flags.

int PickupType;

How the pickup flags are applied to items upon item creation.

int Tile;

The starting tile of the item's animation

int CSet;

The CSet the item sprite uses

int MiscFlags

Misc flags for the item graphics, bitwise flagset. Use the IMISC_ constants to access. TODO: Item editor can't flip the tile?

int AFrames;

The number of frames in the animation

int ASpeed;

The speed of the animation, in frames per frame.

int Delay;

The number of delay frames at the start of the animation.

int TileMod;

The Player Tile Modifier associated with this item.

int Sprites[10];

The 10 sprites used by the item. How they are used depends on the item type.

int SizeFlags;

A bitwise flagset representing all the checkboxes for which sizes to apply from the itemdata. Use the SZFLAG_ constants to access.

int TileWidth; int TileHeight;

The visual size of the sprite, in tiles.

int HitWidth; int HitHeight;

The hitbox size of the sprite, in pixels.

int HitZHeight;

The Z-Height of the hitbox, in pixels.

int DrawXOffset; int DrawYOffset;

The visual offset of the sprite, in pixels.

int HitXOffset; int HitYOffset;

The hitbox offset of the sprite, in pixels.

int WeaponSizeFlags;

A bitwise flagset representing all the checkboxes for which sizes to apply from the itemdata. Use the SZFLAG_ constants to access.

int WeaponTileWidth; int WeaponTileHeight;

The visual size of the sprite, in tiles.

int WeaponHitWidth; int WeaponHitHeight;

The hitbox size of the sprite, in pixels.

int WeaponHitZHeight;

The Z-Height of the hitbox, in pixels.

int WeaponDrawXOffset; int WeaponDrawYOffset;

The visual offset of the sprite, in pixels.

int WeaponHitXOffset; int WeaponHitYOffset;

The hitbox offset of the sprite, in pixels.

int Weapon;

The overrided weapon type that the weapon will act like.

int Defense;

The default defense of the weapon.

Itemsprite Pointers

itemsprite These pointers represent item objects on screen. These may be screen items, enemy drops, shop items, etc; or you may create your own items via script. See: LoadItem, CreateItem

int ID;

The item ID to give when the item is collected.

bool isValid();

Returns true if this pointer points to a valid itemsprite. If this returns false, using any other value of this pointer will error.

int Type; int Family;

The type (itemclass) of the item. Uses the IC_ constants.

int Level;

The item's level

int Dir;

The item's direction

bool Animation;

If the engine should animate the item's graphics

int X; int Y; int Z;

Read/Write; These values store the itemsprite's position on each of the three axes. If the quest rule Sprite Coordinates are Float is checked, these values can include up to 4 decimal places; otherwise values are truncated.

int Jump;

The itemsprite's upward velocity, in pixels per frame. Affected by gravity each frame, if gravity is enabled for this itemsprite.

bool Gravity;

True by default. If false, gravity will no longer affect this itemsprite.

bool MoveFlags[];

The movement flags of the itemsprite. See ITEMMV_ constants.

int FakeZ;

The position of the itemsprite on the FakeZ axis.

int FakeJump;

The velocity of the itemsprite in the FakeZ axis.

int Max();

Returns the max number of itemsprites currently allowed.

void Max(int newmax);

Sets the max number of itemsprites allowed to a new value. Range 1-1024.

int OriginalTile;

The starting tile of the itemsprite's animation.

int Tile;

The currently displaying tile of the itemsprite's animation. Set by the engine each frame if animation is enabled.

int CSet;

The CSet of the itemsprite.

int NumFrames;

The number of frames in the itemsprite's animation.

int Frame;

The current frame number that the animation is on.

int ASpeed;

The speed of the animation, in frames per frame.

int AClock;

The timer that ASpeed is used with.

int Delay;

The number of delay frames at the start of the itemsprite's animation.

bool Flash;

If the itemsprite is flashing or not. When flashing, it changes between its' CSet and FlashCSet.

int FlashCSet;

The secondary CSet used for flashing.

int Flip;

The flip status of the itemsprite's tile. Uses the FLIP_FLIP_NONE = 0 FLIP_HORIZONTAL = 1 FLIP_VERTICAL = 2 FLIP_HV = 3 FLIP_VH = 3 FLIP_BOTH = 3 //rotation and flip ROT_CW = 4 ROT_CW_FLIP = 5 ROT_CCW_FLIP = 6 ROT_CCW = 7 constants.

int ScriptTile;

-1 by default. If this is set > -1, this tile will be displayed by the engine, regardless of the normal engine animation. Set back to -1 to restore engine animation.

int ScriptFlip;

-1 by default. If this is set > -1, this flip value will be used instead of the normal 'Flip' value. Set back to -1 to restore normal flip.

int ShadowXOffset; int ShadowYOffset;

The x/y offset of the sprite's shadow.

int ShadowSprite;

The spritedata sprite ID to use for the item's shadow.

int DrawStyle;

The mode for the sprite's draws, using the DS_ constants.

float Rotation;

A rotation of the sprite draw, in degrees.

float Scale;

A scale of the sprite draw, as a multiplier.

int LightShape;

The shape of light emitted by this sprite. Uses the LIGHT_ constants.

int LightRadius;

The size of the light emitted by this sprite, in pixels.

int Extend;

If the item sprite should be extended (large). Set to 3 to extend, 0 otherwise.

int HitWidth; int HitHeight;

The width/height of the hitbox, in pixels.

int HitZHeight;

The height of the hitbox in the Z-axis, in pixels.

int TileWidth; int TileHeight;

The width/height of the sprite's graphic, in tiles.

int DrawXOffset; int DrawYOffset;

The visual offset, in pixels.

int DrawZOffset;

The Z offset, in pixels.

int HitXOffset; int HitYOffset;

The hitbox offset, in pixels.

int Pickup;

The item pickup flags, as a bitwise flagset. Use the IP_ constants to access. Take care when using any INTERNAL flags.

int PickupString;

The message string to display upon picking up the item.

int PickupStringFlags;

The flags associated with the pickup string, as bitwise flags. Use the IPSTR_ constants to access this.

int Script;

The itemsprite script running on this itemsprite.

int InitD[8];

The 8 InitD[] arguments for the itemsprite script.

int Misc[32];

An array of misc values for script use.

int Falling;

The timer indicating how long left the sprite will be falling. If 0, the sprite is not falling. Max value of 70, which is the value at the start of falling.

int FallCombo;

The pitfall combo the sprite is falling into, if it is falling.

int Drowning;

The timer indicating how long left the sprite will be drowning. If 0, the sprite is not drowning. Max value of 64, which is the value at the start of drowning.

int DrownCombo;

The liquid combo the sprite is drowning in, if it is drowning.

bool SwitchHooked;

If the sprite is currently being switch-hooked.

bool Switch(int effect);

Switch the player with this sprite. Use the SW_EFF_ constants for 'effect' to select a visual style for the switch. Returns true if it succeeds, and false otherwise.

void Explode(int mode);

Creates an explosion particle effect in mode 0, 1, or 2 of the sprite.

void Remove();

Instantly deletes the itemsprite.

int DroppedBy;

The dropset that this item was dropped by. Will be set for engine-dropped items, can be written by scripts as well.

bool ForceGrab;

If set to true, the item will automatically be collected by the player as soon as possible.

The ZInfo-> pointer allows accessing zinfo strings. TODO: add more getter functions to ZInfo->

void GetItemClass(char32 buf[]256 chars, int itemclass_id);

Copies the name of the specified itemclass (use IC_ constants) into the buffer.

SpriteData Pointers

spritedata These pointers represent the Quest->Graphics->Sprites->Sprite Data sprite information. See: LoadSpriteData

int ID;

Read-only. The sprite ID this spritedata is associated with.

int Tile;

The tile of the sprite.

int CSet;

The cset of the sprite.

int FlashCSet;

The flash cset of the sprite.

int Frames;

The frame count of the sprite.

int Speed;

The speed of the sprite, in frames per frame

bool Flags[5];

The sprite's flags. Use the SPRFL_ constants as indexes.

int Type;

The 'Type' field of the sprite.

The Game-> pointer holds many general internal functions and variables.

int CurScreen; int GetCurScreen();

Returns the screen the player is currently on.

int CurDMapScreen; int CurDMScreen; int GetCurDMapScreen();

Returns the screen the player is currently on, offset by the current dmap offset.

int CurMap; int GetCurMap();

Returns the map the player is currently on.

int CurDMap; int GetCurDMap();

Returns the dmap the player is currently on.

int CurLevel; int GetCurLevel();

Returns the level the player is currently on.

int Counter[NUM_COUNTERS];

The value of each of the game's counters (using CR_

-1. CR_NONE
0. CR_LIFE
1. CR_RUPEES
2. CR_BOMBS
3. CR_ARROWS
4. CR_MAGIC
5. CR_KEYS
6. CR_SBOMBS
7. CR_CUSTOM1
8. CR_CUSTOM2
9. CR_CUSTOM3
10. CR_CUSTOM4
11. CR_CUSTOM5
12. CR_CUSTOM6
13. CR_CUSTOM7
14. CR_CUSTOM8
15. CR_CUSTOM9

16. CR_CUSTOM10
17. CR_CUSTOM11
18. CR_CUSTOM12
19. CR_CUSTOM13
20. CR_CUSTOM14
21. CR_CUSTOM15
22. CR_CUSTOM16
23. CR_CUSTOM17
24. CR_CUSTOM18
25. CR_CUSTOM19
26. CR_CUSTOM20
27. CR_CUSTOM21
28. CR_CUSTOM22
29. CR_CUSTOM23
30. CR_CUSTOM24
31. CR_CUSTOM25

constants). Values 0 to 65535.

int MCounter[NUM_COUNTERS];

The max value of each of the game's counters (using CR_

-1. CR_NONE
0. CR_LIFE
1. CR_RUPEES
2. CR_BOMBS
3. CR_ARROWS
4. CR_MAGIC
5. CR_KEYS
6. CR_SBOMBS
7. CR_CUSTOM1
8. CR_CUSTOM2
9. CR_CUSTOM3
10. CR_CUSTOM4
11. CR_CUSTOM5
12. CR_CUSTOM6
13. CR_CUSTOM7
14. CR_CUSTOM8
15. CR_CUSTOM9

16. CR_CUSTOM10
17. CR_CUSTOM11
18. CR_CUSTOM12
19. CR_CUSTOM13
20. CR_CUSTOM14
21. CR_CUSTOM15
22. CR_CUSTOM16
23. CR_CUSTOM17
24. CR_CUSTOM18
25. CR_CUSTOM19
26. CR_CUSTOM20
27. CR_CUSTOM21
28. CR_CUSTOM22
29. CR_CUSTOM23
30. CR_CUSTOM24
31. CR_CUSTOM25

constants). Values 0 to 65535.

int DCounter[NUM_COUNTERS];

The value of each of the game's drain counters (using CR_

-1. CR_NONE
0. CR_LIFE
1. CR_RUPEES
2. CR_BOMBS
3. CR_ARROWS
4. CR_MAGIC
5. CR_KEYS
6. CR_SBOMBS
7. CR_CUSTOM1
8. CR_CUSTOM2
9. CR_CUSTOM3
10. CR_CUSTOM4
11. CR_CUSTOM5
12. CR_CUSTOM6
13. CR_CUSTOM7
14. CR_CUSTOM8
15. CR_CUSTOM9

16. CR_CUSTOM10
17. CR_CUSTOM11
18. CR_CUSTOM12
19. CR_CUSTOM13
20. CR_CUSTOM14
21. CR_CUSTOM15
22. CR_CUSTOM16
23. CR_CUSTOM17
24. CR_CUSTOM18
25. CR_CUSTOM19
26. CR_CUSTOM20
27. CR_CUSTOM21
28. CR_CUSTOM22
29. CR_CUSTOM23
30. CR_CUSTOM24
31. CR_CUSTOM25

constants). Values -32768 to 32767. These will approach 0 each frame, adding or subtracting from the matching Counter[].

untyped Misc[32]; untyped Misc2[256]; untyped Misc3[256];

3 misc data arrays.

itemdata LoadItemData (int item_id);

npcdataUnder Construction! LoadNPCData (int npc_id);

combodata LoadComboData (int combo_id);

spritedata LoadSpriteData (int misc_spr_id);

shopdata LoadShopData (int shop_id);

shopdata LoadInfoShopData (int shop_id);

messagedata LoadMessageData (int string_id);

dmapdata LoadDMapData (int dmap_id);

dropsetdata LoadDropset (int dropset_id);

bottledata LoadBottleData (int bottle_type_id);

bottleshopdata LoadBottleShopData (int bottleshop_id);

genericdata LoadGenericData (int generic_script_id);

These functions load the specified pointer, returning NULL on a failure.

mapdata LoadMapData(int map, int screen);

Loads the mapdata pointer for the screen at (map,screen). Edits to these pointers do not persist through quest exit. Edits to these pointers will NOT affect the "current screen", even if the current map/screen is supplied; see LoadTempScreen() below for that.

mapdata LoadTempScreen(int layer);

Loads the temp mapdata pointer for the specified layer. LoadTempScreen(0) gives a pointer that works mostly the same as Screen->, while passing 1 through 6 will give equal access to the other layers of the screen. Modifications to these pointers are reset when the screen changes.

mapdata LoadScrollingScreen(int layer);

Loads the temp mapdata pointer for the specified layer's *scrolling screen*. This is only used during scrolling, for drawing the screen you just came from during the scrolling animation. Writing to this at any time other than during scrolling will have no effect.

bitmap CreateBitmap(int width = 256, int height = 256);

Allocates a new bitmap pointer, creating a width by height canvas (cleared to color 0). Be sure to Free() it when you are done, or Own() it to attach it to a script! If "Old Args for CreateBitmap and bitmap->Create()"at "ZScript->Quest Script Settings->Instructions" is enabled, then width and height are swapped with each other.

bitmap AllocateBitmap();

Allocates a new bitmap pointer, but does not create a canvas on it. bitmap->Create() can later be used to create a canvas on the pointer. Be sure to Free() it when you are done, or Own() it to attach it to a script!

bitmap LoadBitmapID(int render_targetRT_ constants);

Loads a bitmap pointer for one of the old-style render target RT_ bitmaps. TODO: Unsure if these have been tested to work properly?

randgen LoadRNG();

Loads an unused randgen pointer. Be sure to Free() it when you are done, or Own() it to attach it to a script!

stack LoadStack();

Loads an unused stack pointer. Be sure to Free() it when you are done, or Own() it to attach it to a script!

int GetFFCScript(char32 name[]);

int GetComboScript(char32 name[]);

int GetItemScript(char32 name[]);

int GetNPCScript(char32 name[]);

int GetLWeaponScript(char32 name[]);

int GetEWeaponScript(char32 name[]);

int GetPlayerScript(char32 name[]);

int GetGlobalScript(char32 name[]);

int GetDMapScript(char32 name[]);

int GetScreenScript(char32 name[]);

int GetItemSpriteScript(char32 name[]);

int GetGenericScript(char32 name[]);

Gets the script of the specified type with a name exactly matching name. If no such script exists, returns -1.

int GetNPC(char32 name[]);

int GetItem(char32 name[]);

int GetCombo(char32 name[]);

int GetDMap(char32 name[]);

Gets the ID of the npc/item/combo/dmap whose name exactly matches name. If no such object exists, returns -1.

int Version;

Read-only. The current version of ZC that the quest is being played in (ex: "2.55" for 2.55)

int Build;

Read-only. The current Build ID of ZC that the quest is being played in.

int Beta;

Read-only. The current detailed version; this can be the current Alpha, Beta, Gamma, or Release number, depending on the version of the program. For nightlies, returns a half-measure; ex. "Nightly A111/A112" would return "111.5".

int BetaType;

Read-only. What type of detailed version the program is in. 0 = Alpha, 1 = Beta, 2 = Gamma, 3 = Release, -1 = error.

int ZScriptVersion;

The ZScript version number the quest was last compiled in.

int LKeys[NUM_LEVELS];

How many level-specific keys are owned for each level.

int LItems[NUM_LEVELS];

Contains a bitwise flagset of the "Level Items".

• LI_TRIFORCE = 0x01
• LI_MAP = 0x02
• LI_COMPASS = 0x04
• LI_BOSS = 0x08
• LI_BOSSKEY = 0x10

long LSwitches[NUM_LEVELS];

The level-specific switch states for each level. Each level has a single long, representing 32 bitwise states. Ex: (Game->LSwitches[Game->CurLevel] & (1Lb << (5))) will get the switch state indexed '5'.

int GSwitch[256];

The 256 global switch timers. A value of 0 represents an "off" switch. A value of -1 represents an "on" switch. A value > 0 represents a "timed" switch, which will remain on for that many more frames.

int MiscSprites[MISCSPR_MAX]

The Quest->Graphics->Sprites->Misc Sprites values, accessed with the MISCSPR_ constants.

int MiscSFX[MISCSFX_MAX]

The Quest->Audio->Misc SFX values, accessed with the MISCSFX_ constants.

int BottleState[256]

The contents of the player's fillable bottles. Use bottle type IDs for the values, and slots (set in the bottle item's attributes) as the indexes.

int Scrolling[5]

Read-only; values related to scrolling.

int Gravity[3]

Values related to gravity.

untyped Generic[GEN_MAX]

Generic values related to the game.

bool Suspend[susptLAST]

An array of suspend states, all false by default. By writing these true, certain game operations may be paused until the state is written false again.

bool FFRules[qr_MAX];

The values of all Quest Rules. Access this array using the qr_ constants in include/std_zh/ffrules.zh. Accessing indexes that do not have constants is undefined.

untyped EventData[];

A variably-sized array containing information about the current event. This should be accessed from Generic Scripts after returning from WaitEvent(). Depending on what event WaitEvent() returns, a different set of constants should be used to access this array. Valid events and their index constants:

void Save();

Saves the game. Can only run once per script per frame.

void End();

Closes the quest, returning to the title screen.

void Reload();

Exits the quest without saving, then reloads the previous save.

void Continue();

Continue's the quest, as 'F6->Continue'.

void SaveAndQuit();

Saves the game, then exits.

void SaveAndContinue();

Saves the game, then continues.

bool ShowSaveScreen();

Displays the Save screen, as Save Point combos use. Returns true if the player saved, false otherwise.

void ShowSaveQuitScreen();

Displays the Save/Quit screen.

void ShowContinueScreen();

Displays the engine Continue/Save/Retry screen.

int MaxNPCs(); int MaxLWeapons(); int MaxEWeapons(); int MaxItemsprites();

Returns the current max sprite count for each sprite type.

void MaxNPCs(int newmax); void MaxLWeapons(int newmax); void MaxEWeapons(int newmax); void MaxItemsprites(int newmax);

Sets the max sprite count for a sprite type to the given new value. Max must be between 1 and 1024, inclusive.

int LastEntranceScreen; int LastEntranceDMap;

The last entrance point the player used, and will be reset to by some mechanics.

int ContinueScreen; int ContinueDMap;

The continue point the player will be reset to when continuing.

int MaxCheat;

The highest cheat level that is enabled for the player. The player can change their cheat level in the cheat menu to any value <= this value (range 0-4). Updates when the player enters a cheat code.

int Cheat;

The current activated cheat level. (range 0-4)

int NumDeaths;

The number of times the player has died.

bool HasPlayed;

Read-only. Returns true if the current save file was loaded, false if it was a freshly created save.

bool TimeValid;

If 'false', Game->Time does not contain accurate time information.

long Time;

The number of frames passed on the save file, as a long. include/time.zh has several functions that help manage this value.

bool Standalone;

True if the game is running in Standalone mode.

void GetSaveName(char32 buf[]);

Loads the save file name into the buffer.

void SetSaveName(char32 buf[]);

Sets the save file name to the contents of the buffer, limit 8 characters.

int SubscreenSpeed;

Speed multiplier for the engine subscreen rise/fall. Default 1. Max 85.

bool TypingMode;

If true, keyboard input is disabled except for scripts reading it.

bool ClickToFreezeEnabled;

Writing this to 'false' forcibly disables the "Click To Freeze" setting, allowing the user to click without pausing the game (ex. for scripted mouse interaction)

bool SkipCredits;

If true, the end credits will not be shown.

bool SkipF6;

If true, the F6 menu will not appear when F6 is pressed. The prompt to exit the game will still be shown.

bool DisableActiveSubscreen;

If true, pressing the Start button will no longer open the active subscreen.

void IncrementQuest();

Ends the current quest in victory, resetting to the title screen (without showing the normal end credits), and if this quest is part of a module, increment to the next quest in the module.

untyped GetScreenD(int screen, int reg);

Gets the Screen->D[reg] for the screen screen on the current dmap.

untyped SetScreenD(int screen, int reg, untyped val);

Sets the Screen->D[reg] for the screen screen on the current dmap to val.

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

Gets the Screen->D[reg] for the screen screen on the specified dmap.

untyped SetDMapScreenD(int dmap, int screen, int reg, untyped val);

Sets the Screen->D[reg] for the screen screen on the specified dmap to val.

int GuyCount[256];

The count of enemies remaining alive for each screen on the current map.

bool DisabledItem[NUM_ITEMDATA];

Whether each item is disabled or not on the current dmap.

int MapCount();

The number of maps in the quest.

int NumMessages;

The number of message strings in the quest.

int GetMidi();

Returns the current MIDI playing.

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 WaitTo(int timing, bool at_least = false);

Can only be used in a passively-running Generic Script. Waits until it is the specified timing. If 'at_least == true', will not wait if it is already past that timing for the frame.

int WaitEvent();

Can only be used in a passively-running Generic Script. Is only used in conjunction with 'EventListen[]'. Waits until any event the script is listening to via EventListen[] = true occurs. When such an event occurs, the function will return the event type, and Game->EventData[] will be filled with information about the current event, much of which is modifiable.

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!

void OwnObject([Object] obj);

Takes an ObjectUnder Construction! parameter. Grants ownership of the object to the currently running script. When the owning script dies, the owned object will be deleted. Note: Objects are already owned by the script that created them automatically, without needing to call this function.

void GlobalObject([Object] obj);

Takes an ObjectUnder Construction! parameter. Globalizes the object, making it no longer owned by any script. Globalized objects will be saved to the save file, and remain intact upon reloading. Calling 'OwnObject()' on a globalized object will undo this, returning it to script ownership.

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.

untyped Min(...untyped argsTakes 2+ untyped args);

Returns the lowest parameter.

untyped Max(...untyped argsTakes 2+ untyped args);

Returns the highest parameter.

untyped Choose(...untyped argsTakes 1+ untyped args);

Returns a random parameter, using the global RandGen.

int Pow(int base, int exp);

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

int LPow(long base, long exp);

Returns 'base^exp', with '0⁰==1'. Negative values of 'exp' work, though may not be useful, as the return value is truncated to the nearest long.

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); void Trace(long val);

Prints the passed value to the output console. Includes a newline character after the value. If a long val is passed, it prints the number with no decimal place (long format). Otherwise, it prints the number with 4 decimal places.

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+ 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'.
• '%b' or '%B': Inserts the value in Binary. 'b' has no decimal included, while 'B' uses all 32 bits as a long.
• '%a?': Inserts an array. Must be followed by another letter from this list, which will be used as the format for each element in the array. Ex: '%aB' inserts an array, where each index is inserted in long binary. '%04ad' inserts an array, where each element is a number of at least 4 digits.
• '%%': 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. The max number of digits is 10, except in Binary ('%b','%B'), where it is 32. 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+ 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.

void OwnArray(untyped[] arr);

Grants ownership of the target array to the currently running script. If this array is not a local array, nothing happens. If it is a local array, the array will no longer be destroyed when it reaches the end of its' declaring scope- it will last until the owning script ends, at which point it will be freed.

void DestroyArray(untyped[] arr);

If 'arr' is a local array, destroys it immediately. Otherwise does nothing.

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: LoadFFC

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.

GenericData Pointers

genericdata genericdata pointers allow interacting with and running generic scripts. See: LoadGenericData, WaitTo, WaitEvent

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

bool EventListen[GENSCR_NUMEVENT];

Array of event listener conditions. When WaitEvent() is called, the script will wait until any event which has a value of 'true' in this array occurs. Defaults to all false. See: WaitEvent, EventData Available states:

0. GENSCR_EVENT_INITWhen loading from a save or starting a new quest
1. GENSCR_EVENT_CONTINUEWhen 'F6->Continue' occurs, before conditions have been reset.
2. GENSCR_EVENT_FFC_PRELOADThe 'FFC runs on Screen Init' timing
3. GENSCR_EVENT_CHANGE_SCREENWhen the screen changes
4. GENSCR_EVENT_CHANGE_DMAPWhen the dmap changes
5. GENSCR_EVENT_CHANGE_LEVELWhen the level changes
6. GENSCR_EVENT_HERO_HIT_1When the player is hit, before ring defense is applied
7. GENSCR_EVENT_HERO_HIT_2When the player is hit, after ring defense is applied
8. GENSCR_EVENT_COLLECT_ITEMWhen an item is collected
9. GENSCR_EVENT_ENEMY_DROP_ITEM_1When an enemy drops an item, before it creates an item
10. GENSCR_EVENT_ENEMY_DROP_ITEM_2When an enemy drops an item, after the item is created (only if 'Nothing' isn't chosen)
11. GENSCR_EVENT_ENEMY_DEATHAn enemy dies
12. GENSCR_EVENT_ENEMY_HIT1When an enemy is hit, before defenses
13. GENSCR_EVENT_ENEMY_HIT2When an enemy is hit, after defenses

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 = -1, int pos = 0);

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 = -1, int pos = 0);

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 = -1, int pos = 0);

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 = -1, int pos = 0);

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 = -1, int pos = 0);

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 = -1, int pos = 0);

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 = false);

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 HitDir;

The direction the Hero is currently being knocked back, if they are being knocked back.

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.

bool Standing;

Read-only. Returns true if the Hero is standing on the ground.

int CoyoteTime;

The number of frames the Hero has been off the ground, max 65535. If the Hero jumps, immediately sets this value to 65535. If this value is not 65535 and is less than a Feather item's Coyote Time value, that feather can be used to jump, even in mid-air.

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: LoadRNG

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(long bound);

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

long LRand(long bound1, long 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: LoadStack

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: LoadBottleData

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: LoadBottleShopData 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: LoadDropset TODO: Name getter/setter, Create(x,y,z=0)

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: LoadMessageData

void Get(char32[] str);

Loads the message into the provided string buffer.

void Set(char32[] str);

Sets the message to the provided string.

int Length;

The length, in characters, of the message. Read-only.

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 DrawString 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: LoadShopData, LoadInfoShopData

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.

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(); int NumFFCs();

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

itemsprite CreateItem(int id); npc CreateNPC(int id); lweapon CreateLWeapon(int id); eweapon 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().

itemsprite LoadItem(int n); npc LoadNPC(int n); lweapon LoadLWeapon(int n); eweapon 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 <= MAX_FFC. Used to access ffcs that currently exist on the screen.

itemsprite Items[]; npc NPCs[]; lweapon LWeapons[]; eweapon EWeapons[]; ffc FFCs[];

Internal Array pointersUnder Construction! to arrays containing all of each respective type of object on the screen. These arrays are 0-indexed.

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.

untyped D[8];

A set of 8 misc values for each screen.

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.

bool TriggerCombo(int layer, int pos);

Attempts to trigger the combo at 'layer,pos'. Returns true on success, false on failure. Fails in special cases depending on the combo, as well as if either layer or pos is invalid. If no 'Triggers' tab behaviors are set, won't do anything.

int GetRenderTarget(); void SetRenderTarget(int rt);

Gets/sets the current "Render Target". Most times this should be 'RT_SCREEN', though versions older than 2.55 required using this for bitmap drawing. 2.55's bitmap pointers effectively obsolete the render target system, and should be used instead of this. Uses the constants RT_SCREEN for the screen, and RT_BITMAP0 through RT_BITMAP6 for the 6 old-style bitmap targets.

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

Draws an area from the old-style render target bitmap indicated by bitmap_id to the current render target.

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

Similar to 'DrawBitmap', but offers some extra mode options- using the 'BITDX_' constants.

Array Drawing Functions

These take a repeating-array of parameters.

void PutPixels(int layer, int arr[]);

Puts multiple pixels to the screen in one function call. PutPixels() expects an array as its arg, with the array in the format of repeating blocks of { x, y, color, trans }.

void DrawTiles(int layer, int arr[]);

Similar to FastTile(), but it draws multiple tiles in one call. The array arg should be an array with repeating sets of {x,y,tile,color,opacity}

void DrawCombos(int layer, int arr[]);

Similar to FastCombo(), but it draws multiple combos in one call. The array arg should be an array with repeating sets of {x,y,combo,color,opacity}

void Lines(int layer, int arr[]);

Similar to Line(), but it draws multiple lines in one call. The array arg should be an array with repeating sets of {x,y,x2,y2,color,scale,rx,ry,rangle,opacity}

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 screen, a temporary scrolling screen, or a permanent screen. Many parts of mapdata are shared with Screen->. See: LoadTempScreen, LoadScrollingScreen, LoadMapData

int Map;

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

int Screen;

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

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

Access various properties of the FFCs on the screen, remotely. See ffc for more information on each value. For int FFCFlags[];, 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 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[].

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.

bool ExState[32];

The 32 'Extra States' used for this screen.

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.

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: CreateBitmap, Create

int Width; int Height;

Read-only. The width/height of the bitmap *at the start of this frame* in pixels.

bool isAllocated();

Returns true if the bitmap pointer has been allocated for use.

bool isValid();

Returns true if the bitmap pointer has been created to be drawn to.

void Free();

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

void Own();

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

void Read(int layer, char32 filename[]);

Reads from the specified image file into the bitmap. Read() will fail if:

• The file is corrupt:
• PNG, JPEG, or other 'compressed' formats may abort if the file is corrupt.
• Formats such as .BMP or .TGA may read up until missing data, as they are linear.
• The file is missing.
• The filename is incorrect. Remember that POSIX filesystems are Case-SenSitive.

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.

void Write(int layer, char32 filename[], bool allow_overwrite = false);

Writes from the bitmap to the specified image file. Requires one of: .png,.gif,pcx,.tgx,.bmp. Fails otherwise. Will not replace an existing file, unless allow_overwrite is true. Will automatically create missing directories on the specified path. 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.

void WriteTile(int layer, int x, int y, int tile, bool is8bit = true, bool mask = false);

Writes a 16x16 area from the bitmap to the tile tile. The tile's 8-bit status will be set to the value of is8bit. If mask is true, the draw will be an Overlay- otherwise it will overwrite.

void Create(int layer = 0, int width = 256, int height = 256);

Creates a bitmap on the pointer of width by height, destroying any data that was previously on the pointer. If "Old Args for CreateBitmap and bitmap->Create()"at "ZScript->Quest Script Settings->Instructions" is enabled, then width and height are swapped with each other.

void Clear(int layer = 0);

Clears the bitmap to color 0 on the specified layer timing.

void ClearToColor(int layer, int color);

Clears the bitmap to the specified color on the specified layer timing.

int GetPixel(int x, int y);

Returns the palette index at the given position on the bitmap *at the start of the frame*. This does not account for this frame's draws that have yet to happen.

int CountColor(bitmap mask, int x, int y, int checkColor, int maskColor = -1);

Checks the area of this bitmap specified by the area on the mask bitmap which matches the maskColor. For a maskColor of -1, all non-zero values will match. Returns the number of pixels in said area that match the checkColor on this bitmap. For a checkColor of -1, all non-zero values will match. The area checked is from x,y to x+mask->Width,y+mask->Height. If this goes out of bounds, the out of bounds area is ignored. This does not account for this frame's draws that have yet to happen.

void Dither(int layer, bitmap mask, int color, int ditherType, int ditherArg);

Draws color onto the bitmap on pixels that are non-color-0 on the mask bitmap, based on the ditherTypeDITH_ constants

void MaskedDraw(int layer, bitmap mask, int color); void MaskedDraw(int layer, bitmap mask, int color, int maskColor); void MaskedDraw(int layer, bitmap mask, int color, int startMaskColor, int endMaskColor);

Draws color to this bitmap, in the area specified by the mask. Any pixel on the mask which matches the maskColor will be drawn. If no maskColor is specified, all non-zero pixels will be considered matching. If a startMaskColor+endMaskColor are defined, colors between them, inclusive, will be considered matching.

void MaskedBlit(int layer, bitmap mask, bitmap pattern, bool repeatPattern); void MaskedBlit(int layer, bitmap mask, bitmap pattern, bool repeatPattern, int maskColor); void MaskedBlit(int layer, bitmap mask, bitmap pattern, bool repeatPattern, int startMaskColor, int endMaskColor);

Same as MaskedDraw, except instead of drawing a specified color to this bitmap, it draws from a pattern bitmap. If repeatPattern is false, the area from 0,0 to pattern->Width-1,pattern->Height-1 will be drawn. If repeatPattern is true, the entire bitmap will be drawn, repeating the pattern both horizontally and vertically tiled.

void ReplaceColors(int layer, int color, int startCol, int endCol);

Replaces colors that are >= startCol and <= endCol with color.

void ShiftColors(int layer, int shift, int startCol, int endCol);

Shifts colors that are >= startCol and <= endCol by adding shift to them.

void Blit(int layer, bitmap target, int sx, int sy, int sw, int sh, int dx, int dy, int dw, int dh, float rotation = 0Degrees, int cx = 0, int cy = 0, int mode = 0BITDX_ constants, int lit = 0, bool mask = true);

Draws an area specified by the (sx,sy,sw,sh) from this bitmap to the destination area (dx,dy,dw,dh) of the target bitmap. If 'rotation' is non-zero, rotates the draw around the (cx,cy) point. 'lit', if non-zero, will attempt to tint the draw based on that palette index. If 'mask' is false, color 0 will draw as color 0 instead of transparent.

void BlitTo(int layer, bitmap source, int sx, int sy, int sw, int sh, int dx, int dy, int dw, int dh, float rotation = 0Degrees, int cx = 0, int cy = 0, int mode = 0BITDX_ constants, int lit = 0, bool mask = true);

As Blit(), but draws from (sx,sy,sw,sh) of the source bitmap to (dx,dy,dw,dh) of this bitmap.

void DrawPlane(int layer, bitmap src, int sx, int sy, int dx, int dy, int dw, int dh, int space_z, int horizon, float scale_x = 1, float scale_y = 1, bool mask = true);

Draws a scaled 'Mode 7' style effect, line-by-line, where each raster is scaled down toward a horizon point.

void DrawScreenSolid(int layer, int map, int source_screen, int x, int y, float rotation = 0);

Draws the solidity mask entire screen from screen on map on the specified layer of the bitmap at (x,y) in colour index 1. If rotation is not zero, it(the entire screen) will rotate about its center.

void DrawScreenSolidity(int layer, int map, int source_screen, int x, int y, float rotation = 0);

Draws the solidity value for each combo position of an entire screen from screen on map on the specified layer of the bitmap at (x,y). Each combo position will be drawn in the palette index equal to its value as ComboS[]. If rotation is not zero, it(the entire screen) will rotate about its center.

void DrawScreenComboTypes(int layer, int map, int source_screen, int x, int y, float rotation = 0);

Draws the combo type value for each combo position of an entire screen from screen on map on the specified layer of the bitmap at (x,y). Each combo position will be drawn in the palette index equal to its value as ComboT[]. If rotation is not zero, it(the entire screen) will rotate about its center.

void DrawScreenComboIFlags(int layer, int map, int source_screen, int x, int y, float rotation = 0);

As DrawScreenComboTypes, but ComboI[] instead of ComboT[]

void DrawScreenComboFlags(int layer, int map, int source_screen, int x, int y, float rotation = 0);

As DrawScreenComboTypes, but ComboF[] instead of ComboT[]

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.

void Rectangle(int layer, int x, int y, int x2, int y2, int color, float scale = 1, int rx = 0, int ry = 0, int rangle = 0Degrees, bool fill = true, int opacity = OP_OPAQUE);

Draws a rectangle from the (x,y) corner to the (x2,y2) corner. If 'fill' is true, the rectangle will be filled with the color, otherwise it will be a 1-pixel outline of the color. If scale is not '1', it will scale the size of the rectangle. If 'rangle' is not 0, it will rotate the draw around the (rx,ry) point.

void Circle(int layer, int x, int y, int radius, int color, float scale = 1, int rx = 0, int ry = 0, int rangle = 0Degrees, bool fill = true, int opacity = OP_OPAQUE);

Draws a circle of radius radius centered on the point (x,y). If 'fill' is true, the circle will be filled with the color, otherwise it will be a 1-pixel outline of the color. If scale is not '1', it will scale the size of the circle. If 'rangle' is not 0, it will rotate the draw around the (rx,ry) point.

void Arc(int layer, int x, int y, int radius, int startangle, int endangleDegrees, int color, float scale = 1, int rx = 0, int ry = 0, int rangle = 0Degrees, bool closed = true, bool fill = true, int opacity = OP_OPAQUE);

Draws an arc from 'startangle' to 'endangle' degrees of a circle of radius radius centered on the point (x,y). If 'closed' is true, the ends of the arc will be connected to the point (x,y), creating a slice of a pie chart shape. If 'fill' is true, the arc will be filled with the color, otherwise it will be a 1-pixel outline of the color. This function is undefined unless 0 <= (endangle-startangle) < 360. If scale is not '1', it will scale the size of the arc. If 'rangle' is not 0, it will rotate the draw around the (rx,ry) point.

void Ellipse(int layer, int x, int y, int xradius, int yradius, int color, float scale = 1, int rx = 0, int ry = 0, int rangle = 0Degrees, bool fill = true, int opacity = OP_OPAQUE);

Draws an ellipse of radii xradius, yradius centered on the point (x,y). If 'fill' is true, the ellipse will be filled with the color, otherwise it will be a 1-pixel outline of the color. If scale is not '1', it will scale the size of the ellipse. If 'rangle' is not 0, it will rotate the draw around the (rx,ry) point.

void Line(int layer, int x, int y, int x2, int y2, int color, float scale = 1, int rx = 0, int ry = 0, int rangle = 0Degrees, int opacity = OP_OPAQUE);

Draws a line from the (x,y) point to the (x2,y2) point. If scale is not '1', it will scale the size of the line. If 'rangle' is not 0, it will rotate the draw around the (rx,ry) point.

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

Draws a cardinal spline on the screen.

void PutPixel(int layer, int x, int y, int x2, int y2, int color, int rx = 0, int ry = 0, int rangle = 0Degrees, int opacity = OP_OPAQUE);

Draws a pixel at (x,y). If 'rangle' is not 0, it will rotate the draw around the (rx,ry) point.

void DrawInteger(int layer, int x, int y, int font, int color, int background_color, int width, int height, int val, int num_decimal_places = 0, int opacity = OP_OPAQUE);

Draws a number, in the font specified using FONT_ constants, with the top-left at (x,y). The number will be exactly width by height pixels, in the color. If background_color is not -1, it will be drawn behind the number in a rectangle. Up to 'num_decimal_places' places after the decimal point will be shown.

void DrawCharacter(int layer, int x, int y, int font, int color, int background_color, int width, int height, char32 char, int opacity = OP_OPAQUE);

Draws a single character, in the font specified using FONT_ constants, with the top-left at (x,y). The character will be exactly width by height pixels, in the color. If background_color is not -1, it will be drawn behind the character in a rectangle.

void DrawString(int layer, int x, int y, int font, int color, int format, int background_color, char32 str[], int opacity = OP_OPAQUE);

Draws a string, in the font specified using FONT_ constants, in the 'color'. If background_color is not -1, it will be drawn behind the string in a rectangle. Where the string is drawn depends on the format:

• TF_NORMAL: Top-left of string is at (x,y)
• TF_CENTERED: Top-center of string is at (x,y)
• TF_RIGHT: Top-right of string is at (x,y)

void DrawString(int layer, int x, int y, int font, int color, int format, int background_color, char32 str[], int opacity, int shadow_type, int shadow_color);

Same as the above version of DrawString(), except the string is drawn with a shadow. The shadow's style is defined as SHD_ constants, and the shadow will be drawn in the specified shadow_color.

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

Draws the specified tile in the specified cset, with the upper-left at (x,y).

void DrawTile(int layer, int x, int y, int tile, int blockw, int blockh, int cset, int xscale = -1, int yscale = -1, int rx = 0, int ry = 0, int rangle = 0Degrees, int flip = 0, bool transparency = true, int opacity = OP_OPAQUE);

Draws a block of tiles starting from the specified tile, in the specified cset, with the upper-left at (x,y). The size of the tile block is determined by blockw and blockh, which must be integers from 1 to 20 inclusive. If xscale and yscale are both >0, the draw will be stretched to be xscale by yscale pixels. Otherwise, the draw will be 16*blockw by 16*blockh pixels. If transparency is false, color 0 in the tile will be drawn as color 0 instead of transparent. The draw will be flipped based on flip, using the FLIP_ constants. If 'rangle' is not 0, it will rotate the draw around the (rx,ry) point.

void DrawTileCloaked(int layer, int x, int y, int tile, int blockw, int blockh, int flip = 0);

Similar to DrawTile(), but draws with a "cloaked" effect. This means that it does not actually draw the tiles, but instead it distorts the destination bitmap in the draw area based on the pixels in the tiles.

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

As FastTile(), for the current tile of combo.

void DrawCombo(int layer, int x, int y, int combo, int blockw, int blockh, int cset, int xscale = -1, int yscale = -1, int rx = 0, int ry = 0, int rangle = 0Degrees, int flip = 0, bool transparency = true, int opacity = OP_OPAQUE);

As DrawTile(), but for the current tile of the combos.

void DrawComboCloaked(int layer, int x, int y, int combo, int blockw, int blockh, int flip = 0);

As DrawTileCloaked(), but for the current tile of the combos.

void Quad(int layer, int x1, int y1, int x2, int y2, int x3, int y3, int x4, int y4, int w, int h, int cset, int flip, int texture, int render_modePT_ constants, bitmap render_source = NULL);

NOTE: the bitmap render_source parameter is only available for bitmap->Quad(), not Screen->Quad(). Draws a quad with the 4 specified corners, drawn counterclockwise from (x1,y1). The texture is mapped from a tile or tile block if texture > 0, or a combo/combo block if texture <= 0. (Ex: texture = -32 will use combo 32 as a texture). w, h must be values from 1 to 16, and must be powers of 2. For bitmap->Quad(), if render_source is a valid bitmap, a section of it (based on w, h) will be used as the texture instead.

void Triangle(int layer, int x1, int y1, int x2, int y2, int x3, int y3, int w, int h, int cset, int flip, int texture, int render_modePT_ constants, bitmap render_source = NULL);

NOTE: the bitmap render_source parameter is only available for bitmap->Triangle(), not Screen->Triangle(). Draws a triangle with the 3 specified corners, drawn counterclockwise from (x1,y1). The texture is mapped from a tile or tile block if texture > 0, or a combo/combo block if texture <= 0. (Ex: texture = -32 will use combo 32 as a texture). w, h must be values from 1 to 16, and must be powers of 2. For bitmap->Triangle(), if render_source is a valid bitmap, a section of it (based on w, h) will be used as the texture instead.

void Quad3D(int layer, int pos[12], uv[8], csets[4], size[2], int flip, int texture, int render_modePT_ constants, bitmap render_source = NULL);

NOTE: the bitmap render_source parameter is only available for bitmap->Quad3D(), not Screen->Quad3D(). Draws a 3d quad with the 4 corners specified in pos as {x1,y1,z1,x2,y2,z2,x3,y3,z3,x4,y4,z4}. uv specifies texture coordinates as {x1,y1,x2,y2,x3,y3,x4,y4}. size specifies the texture's {w,h}. The texture is mapped from a tile or tile block if texture > 0, or a combo/combo block if texture <= 0. (Ex: texture = -32 will use combo 32 as a texture). For bitmap->Quad3D(), if render_source is a valid bitmap, a section of it (based on {w, h} in size) will be used as the texture instead.

void Triangle3D(int layer, int pos[9], uv[6], csets[3], size[2], int flip, int texture, int render_modePT_ constants, bitmap render_source = NULL);

NOTE: the bitmap render_source parameter is only available for bitmap->Triangle3D(), not Screen->Triangle3D(). Draws a 3d quad with the 4 corners specified in pos as {x1,y1,z1,x2,y2,z2,x3,y3,z3}. uv specifies texture coordinates as {x1,y1,x2,y2,x3,y3}. size specifies the texture's {w,h}. The texture is mapped from a tile or tile block if texture > 0, or a combo/combo block if texture <= 0. (Ex: texture = -32 will use combo 32 as a texture). For bitmap->Triangle3D(), if render_source is a valid bitmap, a section of it (based on {w, h} in size) will be used as the texture instead.

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

Draws the entire layer source_layer from the screen source_map, source_screen. If rotation isn't 0, the layer will be rotated around its' centerpoint.

void DrawScreen(int layer, int source_map, int source_screen, int source_layer, int x, int y, float rotation = 0);

Draws the entire screen source_map, source_screen. If rotation isn't 0, the screen will be rotated around its' centerpoint.

void DrawFrame(int layer, int x, int y, int tile, int cset, int width, int height, bool overlay = true, int opacity = OP_OPAQUE);

Draws a frame using a 2x2 block of tiles, the upper-left tile specified as tile. This works the same way as the default "blue frame" on engine subscreens. width, height indicate how many 8x8 pixel squares the frame is wide/high- so 4,4 would give a 32x32 pixel frame. If overlay is false, color 0 in the frame tiles will be drawn as color 0 instead of transparent.

void Polygon(int layer, int num_points, int vertices[], int colour, int opacity = OP_OPAQUE);

Draws a polygon, where vertices is an array, of which the first num_points*2 indexes are made up of num_points x,y pairs. (ex for num_points = 4, vertices = {x1,y1,x2,y2,x3,y3,x4,y4}).

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 'DrawString' would draw it.

int MessageWidth(int msg);

Returns the width of the messagedata 'msg', as 'DrawString' 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 = true);

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)

int GetPixel(bitmap b, int x, int y);

Same as 'b->GetPixel(x,y)'

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.

paldata CreatePalData(); paldata CreatePalData(rgb color);

Creates a new paldata. If 'color' is specified, fills the palette with that rgb color.

rgb MixColor(rgb start, rgb end, float percent, int color_space = CSPACE_RGB);

Interpolates a color between start and end and then returns the resulting rgb. The value of percent should range from 0-1, with 0 representing the starting color. Color space specifies a color space to interpolate through, changing the resulting average.

0. CSPACE_RGB
1. CSPACE_CMYK
2. CSPACE_HSV
3. CSPACE_HSV_CW
4. CSPACE_HSV_CCW
5. CSPACE_HSL
6. CSPACE_HSL_CW
7. CSPACE_HSL_CCW
8. CSPACE_LAB
9. CSPACE_LCH
10. CSPACE_LCH_CW
11. CSPACE_LCH_CCW

rgb CreateRGB(int r, int g, int b); rgb CreateRGB(long hexcode);

Takes either an (r,g,b) ranging 0 <= n <= 63, or takes a long hexcode (0xRRGGBBL), with each rgb section 0 <= n <= 255. Converts whichever is passed into an 'rgb' value, representing a color with 0-63 rgb values, which is used by paldata functions.

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.

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.