PDA

View Full Version : Finally, some documentation



DarkDragon
09-30-2006, 04:22 AM
I've received many requests for better ZScript documentation, so here you go.
Pressing F1 in the ZScript editor of b15 now also will bring up this text.


Note that the following will be accurate as of b15, some of these were not implemented or were not implemented correctly in b14.



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.


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

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.


void Quit()
* Terminates execution of the current script. Does not return.

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

void Trace(float val)
* Prints a line containing a string representation of val to
* allegro.log. Useful for debugging scripts.

float Sin(int deg)
* Returns the trigonometric sine of the parameter, which is interpreted
* as a degree value.

float Cos(int deg)
* Returns the trigonometric cosine of the parameter, which is
* interpreted as a degree value.

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.

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

float RadianCos(float rad)
* Returns the trigonometric cosine 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.

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.

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.

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

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 Sqrt(float val)
* Computes the square root of the parameter. The return value is
* undefined for val < 0.


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

int Data
* The number of the combo associated with this FFC.

int CSet
* The cset of the FFC.

int Delay
* The FFC's animation delay, in frames.

float X
* The FFC's X position on the screen.

float Y
* The FFC's Y position on the screen.

float Vx
* The FFC's velocity's X-component.

float Vy
* The FFC's velocity's Y-component.

float Ax
* The FFC's acceleration's X-component.

float Ay
* The FFC's acceleration's Y-component.

bool WasTriggered()
* Returns true if and only if the FFC was triggered by a secret.

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

int TileWidth
* The number of tile columns composing the FFC.

int TileHeight
* The number of tile rows composing the FFC.

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

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

int Link
* The number of the FFC linked to by this FFC.


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

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

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

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

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

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.

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.

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.

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 InputLeft
* True iff the player is pressing the left arrow. Writing to this
* variable simulates the press or release of the left arrow.

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 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 InputL
* True iff the player is pressing the L key. Writing to this variable
* simulates the press or release of the L key.

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


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

float D[]
* Each screen has 8 general purpose registers for use by script
* programmers. Do with these as you will.

int ComboD[]
* 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 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 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 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.

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 tile
* is walkable, the second-least signficant bit is true if the top-right
* of the tile is is walkable, and so on for the following two bits.

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

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

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.

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.

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

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

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.


====================================
--- Item Functions and Variables ---
====================================

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

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

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.

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

int Tile
* The tile associated with this item.

int CSet
* This item's CSet.

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

int NumFrames
* The number of frames in this item's animation.

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

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

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.

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

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 Extend
* The item's link tile modifier.


=========================================
--- ItemClass Functions and Variables ---
=========================================

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.

int Level
* The level of this item. For instance, the wooden sword is level 1,
* the white sword level 2, and so on.

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

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


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

int GetCurScreen()
* Retrieves the number of the current screen within the current map.

int GetCurMap()
* Retrieves the number of the current map.

int GetCurDMap()
* Returns the number of the current dmap.

int NumDeaths
* The number of times Link has perished during this quest.

int Cheat
* The current cheat level of the quest player.

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 HasPlayed
* This value is true if the current quest session was loaded from a saved
* game, false if the quest was started fresh.

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

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.

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

int ContinueDMap
* The dmap containing the screen 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.

int MCounter[]
* The current maximum value of the game counters. Use the CT_ constants
* in std.zh to index 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 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.

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.

bool GetMapFlag(int dmap, int flag)
* As with CurMapFlag, but retrieves the miscellaneous flags of any dmap,
* not just the current one. Use the MF_ constants in std.zh for the
* flag parameter.

void SetMapFlag(int dmap, int flag, bool value)
* As with CurMapFlag, but sets the miscellaneous flags of any dmap, not
* just the current one. 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.

void SetScreenD(int screen, int reg, float value)
* Sets the value of SD[reg] on the given screen of the current dmap.

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.

void PlaySound(int soundid)
* Plays one of the quest's sound effects. Use the SFX_ constants in
* std.zh as values of soundid.


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

int X
* The NPC's current X coordinate, in pixels.

int Y
* The NPC's current Y coordinate, in pixels.

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

int Rate
* The NPC's movement rate. For a point of reference, the Octorok on Crack
* has a rate of 16.

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

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 DrawStyle
* The way the NPC is animated. Use the DS_ constants in std.zh to set or
* compare this value.

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

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

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

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 ItemSet
* The items that the NPC might drop when killed. Use the IS_ constants
* in std.zh to set or compare this value.

int CSet
* The CSet used by this NPC.

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 SFX
* The sound effects emitted by the enemy. Use the SFX_ constants in
* std.zh to set or compare this value.

int Extend
* I have actually no idea. I would have thought the NPC's link tile
* modifier, but that makes no sense ;)


I've MASSIVELY updated std.zh to go along with the above documentation. _L_ also did some extensive cleanup. AGN won't let me post it here (too long) but it'll be included in b15.

jman2050
09-30-2006, 10:20 AM
Extend refers to whether to extend the sprite of an item or enemy, same as with Link. Unforunately, that doesn't work correctly yet.

Tygore
10-01-2006, 05:38 PM
Yay, solid documentation! This makes me happy!

I also can't help but notice obvious references to enemy and item scripts. Makes me wonder what we'll see come b15's release...

DarkDragon
10-04-2006, 08:38 AM
jman, feel free to edit and correct any mistakes in the above; in particular I'm not very confident of the item-> documentation as I was a bit confused by the getitem() code.

Moresco
12-16-2006, 11:17 PM
How does GetCurScreen work? Or GetCurMap? I can't get either of them to work how I thought they might...

Nevermind with some help from eXodus I have solved the problem.

GetCurScreen returns a float of 0.xxxx Where xxxx is the screen number you're on, converted from Hex to Decimal. For example if your screen is 46, then it will be 70 in decimal but will be returned by GetCurScreen as 0.0070. If your screen is 2B, then it will be 43 in decimal and returned as 0.0043.

GetCurMap also uses a float of style 0.xxxx but the maps are not returned as expected. Map 1 is actually 0.0000. Map 2, would be 0.0001. 0 counts as 1, and 1 counts as the next map, or map 2. I believe that's how it works anyway.

How I discovered this was by using the Trace() routine, which for some reason I overlooked. VERY useful routine if you're not sure what's going on with your code.

DarkDragon
12-18-2006, 08:00 AM
How does GetCurScreen work? Or GetCurMap? I can't get either of them to work how I thought they might...

Nevermind with some help from eXodus I have solved the problem.

GetCurScreen returns a float of 0.xxxx Where xxxx is the screen number you're on, converted from Hex to Decimal. For example if your screen is 46, then it will be 70 in decimal but will be returned by GetCurScreen as 0.0070. If your screen is 2B, then it will be 43 in decimal and returned as 0.0043.

GetCurMap also uses a float of style 0.xxxx but the maps are not returned as expected. Map 1 is actually 0.0000. Map 2, would be 0.0001. 0 counts as 1, and 1 counts as the next map, or map 2. I believe that's how it works anyway.

How I discovered this was by using the Trace() routine, which for some reason I overlooked. VERY useful routine if you're not sure what's going on with your code.

Good catch; post that in the bug forum and I'll fix it when I get a chance. There's no reason these values should be cryptic floats instead of integers.

DarkDragon
11-17-2007, 05:20 PM
I'm unstickying this thread, as the above documentation is out of date.

zscript.txt (or hit F1 in the script editor) contains the absolute newest documentation. Once 2.5 is done, the 2.5 ZScript documentation will also be found at the ZC Wiki.