ZScript Language Reference

From ZCWiki
Jump to: navigation, search

NOTE: This page is no longer maintained. The content in this page has been broken into multiple new pages. Please see the main ZScript page for links to the new content. The new pages will be maintained from this point on. ScaryBinary 15:27, 27 April 2008 (PDT)


Version-2.50.png The information below describes features introduced in Zelda Classic version 2.50.


Note: In the following, int indicates that a parameter is truncated by a function to an integer, or that the return value will always be an integer. ZScript itself makes no distinction between int and float.

Contents

Global Functions

float Abs(float val)

Return the absolute value of the parameter, if possible. If the absolute value would overflow the parameter, the return value is undefined.

float Cos(int deg)

Returns the trigonometric cosine of the parameter, which is interpreted as a degree value.

int Factorial(int val)

Returns val!. The return value is undefined for val <= 0 (despite the convention 0! = 1.)

int InvPow(int base, int exp)

Returns base^(1/exp). The return value is undefined for exp=0, or if exp is even and base is negative. Note also that negative values of exp may not be useful, as the return value is truncated to the nearest integer.

float Max(float a, float b)

Returns the greater of a and b.

float Min(float a, float b)

Returns the lesser of a and b.

int Pow(int base, int exp)

Returns base^exp. The return value is undefined for base=exp=0. Note also negative values of exp may not be useful, as the return value is truncated to the nearest integer.

void Quit()

Terminates execution of the current script. Does not return.

float RadianCos(float rad)

Returns the trigonometric cosine of the parameter, which is interpreted as a radian value.

float RadianSin(float rad)

Returns the trigonometric sine of the parameter, which is interpreted as a radian value.

float RadianTan(float rad)

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

int Rand(int maxvalue)

Computes and returns a random integer i such that 0 <= i < maxvalue. The return value is undefined if maxvalue is 0 or negative.

float Sin(int deg)

Returns the trigonometric sine of the parameter, which is interpreted as a degree value.

float Sqrt(float val)

Computes the square root of the parameter. The return value is undefined for val < 0.

float Tan(int deg)

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

void Trace(float val)

Prints a line containing a string representation of val to allegro.log. Useful for debugging scripts.

void Waitframe()

Temporarily halts execution of the current script. This function returns at the beginning of the next frame of gameplay. Global scripts and item pickup scripts only execute for one frame, so in those scripts Waitframe() is essentially Quit().

FFC Functions and Variables

float Ax

The FFC's acceleration's X-component.

float Ay

The FFC's acceleration's Y-component.

int CSet

The cset of the FFC.

int Data

The number of the combo associated with this FFC.

int Delay

The FFC's animation delay, in frames.

int EffectHeight

The height of the area of effect of the combo associated with the FFC, in pixels.

int EffectWidth

The width of the area of effect of the combo associated with the FFC, in pixels.

bool Flags[]

The FFC's set of flags. Use the FFCF_ constants in std.zh as the index to access a particular flag.

int Link

The number of the FFC linked to by this FFC.

int TileHeight

The number of tile rows composing the FFC.

int TileWidth

The number of tile columns composing the FFC.

float Vx

The FFC's velocity's X-component, in pixels per frame.

float Vy

The FFC's velocity's Y-component, in pixels per frame.

bool WasTriggered()

Returns true if and only if the FFC was triggered by a secret.

float X

The FFC's X position on the screen.

float Y

The FFC's Y position on the screen.

Link Functions and Variables

int Action

Link's current action. Use the LA_ constants in std.zh to set or compare this value.

int Dir

The direction Link is facing. Use the DIR_ constants in std.zh to set or compare this variable.

int HP

Link's current hitpoints, in 16ths of a heart.

int HeldItem

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

bool InputA

True iff the player is pressing the A key. Writing to this variable simulates the press or release of the A key.

bool InputB

True iff the player is pressing the B key. Writing to this variable simulates the press or release of the B key.

bool InputDown

True iff the player is pressing the down arrow. Writing to this variable simulates the press or release of the down arrow.

bool InputL

True iff the player is pressing the L key. Writing to this variable simulates the press or release of the L key.

bool InputLeft

True iff the player is pressing the left arrow. Writing to this variable simulates the press or release of the left arrow.

bool InputR

True iff the player is pressing the R key. Writing to this variable simulates the press or release of the R key.

bool InputRight

True iff the player is pressing the right arrow. Writing to this variable simulates the press or release of the right arrow.

bool InputStart

True iff the player is pressing the start button. Writing to this variable simulates the press or release of the start button.

bool InputUp

True iff the player is pressing the up arrow. Writing to this variable simulates the press or release of the up arrow.

int ItemJinx

The time, in frames, until Link regains use of his items. -1 signfies a permanent loss of his items.

bool Item[]

True iff Link's inventory contains the item whose ID is the index of the array access. Use the IT_ constants in std.zh as an index into this array.

int Jump

Link's upward velocity, in 1/20ths of a Roc's Feather jump. Undefined for values outside of -20 <= Jump <= 20.

int MP

Link's current amount of magic, in 32nds of a magic block.

int MaxHP

Link's maximum hitpoints, in 16ths of a heart.

int MaxMP

Link's maximum amount of magic, in 32nds of a magic block.

void PitWarp(int dmap, int screen)

Warps link to the given screen in the given dmap, just like if he'd triggered a pit warp.

int SwordJinx

The time, in frames, until Link regains use of his sword. -1 signfies a permanent loss of the sword.

void Warp(int dmap, int screen)

Warps link to the given screen in the given dmap, just like if he'd triggered a side warp.

int X

Link's X position on the screen, in pixels.

int Y

Link's Y position on the screen, in pixels.

int Z

Link's Z position on the screen, in pixels.

Screen Functions and Variables

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

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

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

Draws a circle on the specified layer of the current screen with center (x,y) and radius scale*radius. Then performs a rotation counterclockwise, centered about the point (rx, ry), using an angle of rangle degrees. A filled circle is drawn if fill is true; otherwise, this method draws a wireframe. The circle is drawn using the specified index into the entire 256-element palette: for instance, passing in a color of 17 would use color 1 of cset 1. Opacity controls how transparent the circle will be. Values other than 128 (solid) and 64 (translucent) are currently undefined.

void ClearSprites(int spritelist)

Clears all of a certain kind of sprite from the screen. Use the SL_ constants in std.zh to pass into this method.

int ComboC[]

The CSet of the tile used by the ith combo on the screen, where i is the index used to access this array. Combos are counted left to right, top to bottom.

int ComboD[]

The combo ID of the ith combo on the screen, where i is the index used to access this array. Combos are counted left to right, top to bottom.

int ComboF[]

The secret flag of the ith combo on the screen, where i is the index used to access this array. Combos are counted left to right, top to bottom. Use the CF_ constants in std.zh to set or compare these values.

int ComboI[]

The inherent flag of the ith combo on the screen, where i is the index used to access this array. Combos are counted left to right, top to bottom. Use the CF_ constants in std.zh to set or compare these values.

int ComboS[]

The walkability mask of the ith combo on the screen, where i is the index used to access this array. Combos are counted left to right, top to bottom. The least signficant bit is true if the top-left of the combo is solid, the second-least signficant bit is true if the bottom-left of the combo is is solid, the third-least significant bit is true if the top-right of the combo is solid, and the fourth-least significant bit is true if the bottom-right of the combo is solid.

int ComboT[]

The combo type of the ith combo on the screen, where i is the index used to access this array. Combos are counted left to right, top to bottom. Use the CT_ constants in std.zh to set or compare these values.

item CreateItem(int id)

Creates an item of the given type at (0,0). Use the IT_ constants in std.zh to pass into this method. The return value is a pointer to the new item.

npc CreateNPC(int id)

Creates an npc of the given type at (0,0). Use the NPC_ constants in std.zh to pass into this method. The return value is a pointer to the new NPC.

float D[]

Each screen has 8 general purpose registers for use by script programmers. Do with these as you will.

int Door[]

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

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

Draws a block of tiles on the specified layer of the current screen, starting at (x,y), using the specified cset. Starting with the specified tile, this method copies a block of size blockh x blockw from the tile sheet to the screen. This method's behavior is undefined unless 1 <= blockh, blockw <= 20. The scaling and rotation parameters are reserved for the future, and not currently implemented. This method's behavior is undefined unless rx=ry=rangle=0 and scale=1. Flip specifies how the tiles should be flipped when drawn: 0: No flip 1: Vertical flip 2: Horizontal flip 3: Both (180 degree rotation) If transparency is true, the tiles' transparent regions will be respected. Opacity controls how transparent the solid portions of the tiles will be. Values other than 128 (solid) and 64 (translucent) are currently undefined.

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

Draws an ellipse on the specified layer of the current screen with center (x,y), x-axis radius xradius, and y-axis radius yradius. Then performs a rotation counterclockwise, centered about the point (rx, ry), using an angle of rangle degrees. A filled ellipse is drawn if fill is true; otherwise, this method draws a wireframe. The ellipse is drawn using the specified index into the entire 256-element palette: for instance, passing in a color of 17 would use color 1 of cset 1. Opacity controls how transparent the ellipse will be. Values other than 128 (solid) and 64 (translucent) are currently undefined.

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

Draws a line on the specified layer of the current screen between (x,y) and (x2,y2). Then scales the line uniformly by a factor of scale about the line's midpoint. Finally, performs a rotation counterclockwise, centered about the point (rx, ry), using an angle of rangle degrees. The line is drawn using the specified index into the entire 256-element palette: for instance, passing in a color of 17 would use color 1 of cset 1. Opacity controls how transparent the line will be. Values other than 128 (solid) and 64 (translucent) are currently undefined.

ffc LoadFFC(int num)

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

item LoadItem(int num)

Returns a pointer to the numth item on the current screen. The return value is undefined unless 1 <= num <= NumItems().

npc LoadNPC(int num)

Returns a pointer to the numth NPC on the current screen. The return value is undefined unless 1 <= num <= NumNPCs().

void Message(int string)

Prints the message string with given ID onto the screen. This method's behavior is undefined if string is less than 1 or greater than the total number of messages in the quest.

int NumItems()

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

int NumNPCs()

Returns the number of NPCs (enemies and guys) on the screen. Note that this value is only correct up until the next call to Waitframe().

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

Draws a raw pixel on the specified layer of the current screen at (x,y). Then performs a rotation counterclockwise, centered about the point (rx, ry), using an angle of rangle degrees. The point is drawn using the specified index into the entire 256-element palette: for instance, passing in a color of 17 would use color 1 of cset 1. Opacity controls how transparent the point will be. Values other than 128 (solid) and 64 (translucent) are currently undefined.

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

Draws a rectangle on the specified layer of the current screen, using (x,y) as the top-left corner and (x2,y2) as the bottom-right corner. Then scales the rectangle uniformly about its center by the given factor. Lastly, a rotation, centered about the point (rx, ry), is performed counterclockwise using an angle of rangle degrees. A filled rectangle is drawn if fill is true; otherwise, this method draws a wireframe. The rectangle is drawn using the specified index into the entire 256-element palette: for instance, passing in a color of 17 would use color 1 of cset 1. Opacity controls how transparent the rectangle will be. Values other than 128 (solid) and 64 (translucent) are currently undefined.

Item Functions and Variables

int ASpeed

The speed at which this item animates, in screen frames.

int CSet

This item's CSet.

itemclass Class

The class (the type of item) to which this item belongs.

int Delay

The amount of time the animation is suspended after the last frame, before the animation restarts, in item frames. That is, the total number of screen frames of extra wait is Delay*ASpeed.

int DrawStyle

An integer representing how the item is to be drawn. Use one of the DS_ constants in std.zh to set or compare this value.

int Extend

The item's link tile modifier.

bool Flash

Whether or not the item flashes. A flashing item alternates between its CSet and its FlashCSet.

int FlashCSet

The CSet used during this item's flash frames, if this item flashes.

int Flip

Whether and how the item's tiles should be flipped. 0: No flip 1: Vertical flip 2: Horizontal flip 3: Both (180 degree rotation)

int Frame

The tile that is this item's current animation frame.

int NumFrames

The number of frames in this item's animation.

int Tile

The tile associated with this item.

int X

The item's X position on the screen, in pixels.

int Y

The item's Y position on the screen, in pixels.

ItemClass Functions and Variables

int Amount

The value of this data member can have two meanings: If Amount & 0x8000 is 1, the drain counter for this item is set to Amount & 0x3FFF. The game then slowly fills the counter of this item (see Counter below) out of the drain counter. Gaining rupees uses the drain counter, for example. is set to Amount when the item is picked up. If Amount & 0x8000 is 0, the counter of this item is increased, if Amount & 0x4000 is 1, or decreased, if Amount & 0x4000 is 0, by Amount & 0x3FFF when the item is picked up.

int Counter

The game counter whose current and modified values might be modified when the item is picked up (see Amount, Max, and MaxIncrement above.) Use the CT_ constants in std.zh to set or compare this value.

int Family

The kind of item to which this class belongs (swords, boomerangs, potions, etc.) Use the IC_ constants in std.zh to set or compare this value.

bool Keep

If true, Link will keep the item, and it will show up as an item or equipment in the subscreen. If false, it may modify the current value or maximum value of its counter (see Counter below), then disappear. The White Sword and Raft, for instance, have Keep true, and keys and rupees have Keep false.

int Level

The level of this item. Higher-level items replace lower-level items when they are picked up.

int Max

In conjunction with MaxIncrement (see below) this value controls how the maximum value of the counter of this item (see Counter below) is modified when the item is picked up. If MaxIncrement is nonzero at that time, the counter's new maximum value is at that time set to the minimum of its current value plus MaxIncrement, Max. If Max is less than the current maximum of the counter, Max is ignored and that maximum is used instead. Notice that as a special case, if Max = MaxIncrement, the counter's maximum value will be forced equal to Max.

int MaxIncrement

In conjunction with Max (see above) this value controls how the maximum value of the counter of this item (see Counter below) is modified when the item is picked up. If MaxIncrement is nonzero at that time, the counter's new maximum value is at that time set to the minimum of its current value plus MaxIncrement, and Max. If Max is less than the current maximum of the counter, Max is ignored and that maximum is used instead.

Game Functions and Variables

int Cheat

The current cheat level of the quest player.

int ContinueDMap

The dmap containing the screen that will be used when Link dies and continues.

int ContinueScreen

The screen in the continue dmap (see ContinueDMap below) that will be used when Link dies and continues.

int Counter[]

The current value of the game counters. Use the CT_ constants in std.zh to index into this array.

bool CurMapFlag[]

An array of miscellaneous flags data associated with the current map. Use the MF_ constants in std.zh as indices into this array.

int DCounter[]

The current value of the game drain counters. Use the CT_ constants in std.zh to index into this array.

int Generic[]

An array of miscellaneous game values, such as number of heart containers and magic drain rate. Use the GEN_ constants in std.zh to index into this array.

int GetCurDMap()

Returns the number of the current dmap.

int GetCurDMapScreen()

Retrieves the number of the current screen within the current dmap.

int GetCurMap()

Retrieves the number of the current map.

int GetCurScreen()

Retrieves the number of the current screen within the current map.

bool GetMapFlag(int map, int screen, int flag)

As with CurMapFlag, but retrieves the miscellaneous flags of any map, not just the current one. This function is undefined if map is less than 1 or greater than the maximum map number of your quest, or if screen is greater than 135. Note: Screen numbers in ZQuest are usually displayed in hexadecimal. Use the MF_ constants in std.zh for the flag parameter.

float GetScreenD(int screen, int reg)

Retrieves the value of SD[reg] on the given screen of the current dmap.

int GuyCount[]

The number of NPCs (enemies and guys) on screen i of this map, where i is the index used to access this array.

bool HasPlayed

This value is true if the current quest session was loaded from a saved game, false if the quest was started fresh.

int LItems[]

The level items of level i currently under the posession of the player, where i is the index used to access this array. Each element of this array consists of flags ORed (|) together; use the LI_ constants in std.zh to set or compare these values.

int LKeys[]

The number of level keys of level i currently under the possession of the player, where i is the index used to access this array.

itemclass LoadItemClass(int family)

Retrieves the itemclass pointer corresponding to the given item family. Use the IC_ constants in std.zh as values of family.

int MCounter[]

The current maximum value of the game counters. Use the CT_ constants in std.zh to index into this array.

int NumDeaths

The number of times Link has perished during this quest.

void PlaySound(int soundid)

Plays one of the quest's sound effects. Use the SFX_ constants in std.zh as values of soundid.

void SetMapFlag(int map, int screen, int flag, bool value)

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

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

Sets the value of SD[reg] on the given screen of the current dmap.

int Time

Returns the time elapsed in this quest, in 60ths of a second. The return value is undefined if TimeValid is false (see below).

bool TimeValid

True if the elapsed quest time can be determined for the current quest.

NPC Functions and Variables

int ASpeed

The speed of the NPC's animation, in screen frames.

int BossPal

The boss pallete used by this NPC; this pallete is only used if CSet is 14 (the reserved boss cset). Use the BPAL_ constants in std.zh to set or compare this value.

int CSet

The CSet used by this NPC.

int Damage

The amount of damage dealt to a naked Link when he touches this NPC, in quarter-hearts.

int Dir

The direction the NPC is facing. Use the DIR_ constants in std.zh to set and compare this value.

int DrawStyle

The way the NPC is animated. Use the DS_ constants in std.zh to set or compare this value.

int Extend

Whether to extend the sprite of an item or enemy, as with extended Link tile modifiers. Not currently implemented.

int HP

The NPC's current hitpoints. Each swing of the wooden sword removes 2 hitpoints.

int Haltrate

The extent to which the NPC stands still while moving around the screen. As a point of reference, the Zols and Gels have haltrate of 16.

int ItemSet

The items that the NPC might drop when killed. Use the IS_ constants in std.zh to set or compare this value.

int Rate

The rate at which the NPC changes direction. For a point of reference, the Octorok on Crack has a rate of 16.

int SFX

The sound effects emitted by the enemy. Use the SFX_ constants in std.zh to set or compare this value.

int Step

The NPC's movement rate. As a point of reference, the Octorok on Crack has a step of 200.

int Tile

The number of the starting tile used by this NPC.

int Weapon

The weapon used by this enemy. Use the WPN_ constants in std.zh to set or compare this value. Note that it typically only makes sense to assign weapons labelled as enemy weapons (WPN_ENEMY) (with the exception of WPN_NONE) to this value.

int WeaponDamage

The amount of damage dealt to a naked Link by this NPC's weapon, in quarter-hearts.

int X

The NPC's current X coordinate, in pixels.

int Y

The NPC's current Y coordinate, in pixels.

Utility Routines

Included with the std.zh are also 6 utility routines, for general usage whilst writing scripts.

Floor

The Floor routine will truncate a decimal to an integer, in that it will be rounded down, even if the decimal is > .49 It is used with the command 'Floor(i)', where i is replaced with the value to be truncated.

Ceiling

The Ceiling routine will round a decimal to the next integer, even if the decimal is < .5 It is used with the command 'Ceiling(i)', where i is replaced witht the value to be increased.

Div

The Div routine will divide the first number entered by the second. It is used with the command 'Div(i,j)', where i is replaced with the numerator and j with the denominator.

ComboAt

The ComboAt routine allows ZScript to take the coordinates of a pixel on the screen, rather than counting a value across the screen. It is used the command 'ComboAt(i,j)', where i is replaced with the x coordinate of the pixel, and j is replaced with the y coordinate of the pixel.

Waitframes

The Waitframes routine allows more than one Waitframe to be entered without extra commands. It is used with the command 'Waitframes(i)', where i is replaced with the number of frames for the script to be paused for.

Distance

The Distance command works out the distance between two (x,y) pixel coordinates, using Pythagoras' Theorm. It is used with the command 'Distance(i,j,k,l)', where (i,j) forms the first (x,y) pixel coordinate, and (k,l) forms the second.