Screen (ZScript)

From ZCWiki
Jump to: navigation, search

The Screen object allows quest designers to modify and inspect various properties of the screen that is currently displayed in a Zelda Classic game.

Syntax

The Screen object (or a pointer to it, more specifically) is automatically made available to ZScript scripts; you do not need to declare a Screen variable or instantiate it in any way.

The syntax for accessing the methods and properties associated with the Screen is as follows:

Screen->method-or-property

where method-or-property is one of the methods or properties listed below. As with any expression, you can use Screen methods or properties as the evaluation criteria in control loops, if statements, and so forth.

Methods and Properties

Methods

CreateItem

The CreateItem method creates an item of the given type at position (0,0) on the current screen. The return value is a pointer to the new item.

Introduced in Version
2.5 (beta)
Prototype and Arguments
item CreateItem(int id)
  • int id: An integer indicating the type of item to create. Use the IT_ constants defined in std.zh.
Example
// Create a Rupee and then move it to position 16, 16.
item NewItem;
NewItem = Screen->CreateItem(IT_RUPEE);
NewItem->X = 16;
NewItem->Y = 16;

NumItems

The NumItems method 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, as they are classed as weapon sprites. Note that this value is only correct up until the next call to Waitframe().

Introduced in Version
2.5 (beta)
Prototype and Arguments
int NumItems()
  • This method does not use any arguments.
Example
// Get the number of items on the screen.
int TotalItems;
TotalItems = Screen->NumItems();

LoadItem

The LoadItem method returns a pointer to an item on the current screen.

Introduced in Version
2.5 (beta)
Prototype and Arguments
item LoadItem(int num)
  • int num: An integer specifying which item on the screen to point to. A valid pointer will be returned only if 1 <= num <= NumItems() and NumItems() >= 1.
Example
// Get a reference to the first Item on the screen.
item SomeItem;
SomeItem = Screen->LoadItem(1);

CreateNPC

The CreateNPC method creates a non-playing character (such as an enemy or guy) of the given type at position (0,0) on the current screen.

Introduced in Version
2.5 (beta)
Prototype and Arguments
npc CreateNPC(int id)
  • int id: An integer indicating the type of NPC to create. Use the NPC_ constants defined in std.zh.
Example
// Create an Octorok and then move it to position 16, 16.
npc NewNPC;
NewNPC = Screen->CreateNPC(NPC_OCTOROCK1F);
NewNPC->X = 16;
NewNPC->Y = 16;

NumNPCs

The NumNPCs method 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().

Introduced in Version
2.5 (beta)
Prototype and Arguments
int NumNPCs()
  • This method does not use any arguments.
Example
// Get the number of NPCs on the screen.
int TotalNPCs;
TotalNPCs = Screen->NumNPCs();

LoadNPC

The LoadNPC method returns a pointer to an NPC on the current screen.

Introduced in Version
2.5 (beta)
Prototype and Arguments
npc LoadNPC(int num)
  • int num: An integer specifying which NPC on the screen to point to. A valid pointer will be returned only if 1 <= num <= NumNPCs() and NumNPCs() >= 1.
Example
// Get a reference to the first NPC on the screen.
npc SomeNPC;
SomeNPC = Screen->LoadNPC(1);

NumLWeapons

Returns the number of Link weapon projectiles currently present on the screen. This includes things like Link's arrows, bombs, magic, etc. Note that this value is only correct up until the next call of Waitframe().

Introduced in Version
2.5 (beta)
Prototype and Arguments
lweapon NumLWeapons()

LoadLWeapon

Returns a pointer to an lweapon on the current screen. The return value is undefined unless 1 <= num <= NumLWeapons().

Introduced in Version
2.5 (beta)
Prototype and Arguments
lweapon LoadLWeapon(int num)

CreateLWeapon

Creates an lweapon of the given type at (0,0). The return value is a pointer to the new lweapon.

Introduced in Version
2.5 (beta)
Prototype and Arguments
lweapon CreateLWeapon(int id)
  • int id: The type of weapon to create. Use the LW_ constants in std.zh. Note that the weapon that is created depends on the level of the weapon that Link currently has. For example, if Link has obtained silver arrows, CreateLWeapon(LW_ARROW) will spawn a silver arrow. If Link only has wooden arrows (or no arrows at all) a wooden arrow will be created, etc.

NumEWeapons

Returns the number of Enemy weapon projectiles currently present on the screen. This includes things like Enemy arrows, bombs, magic, etc. Note that this value is only correct up until the next call of Waitframe().

Introduced in Version
2.5 (beta)
Prototype and Arguments
eweapon NumEWeapons()

LoadEWeapon

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

Introduced in Version
2.5 (beta)
Prototype and Arguments
eweapon LoadEWeapon(int num)

CreateEWeapon

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

Introduced in Version
2.5 (beta)
Prototype and Arguments
eweapon CreateEWeapon(int id)

Arc

The Arc method draws an arc of a circle on the specified layer of the current screen.

Introduced in Version
2.5 (beta)
Prototype and Arguments
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)
  • int layer: The layer on which to draw the arc. Valid values are 0 through 6 (inclusive).
  • int x, int y: The center of the arc will be at the point (x,y) (that is, all points on the arc will be a distance of radius * scale away from point (x,y).
  • int radius: The base radius of the arc. The overall radius of the arc will be radius * scale.
  • int startangle, int endangle: The starting and ending angles of the arc, where 0 degrees is to the right, 90 degrees is up, and so on. The behavior of this function is undefined unless 0 <= endangle-startangle < 360.
  • int color: The color of the arc (and its fill, if selected). color is an index into the entire 256-element palette: for instance, passing in a color of 17 would use color 1 of cset 1.
  • float scale: A value by which to scale the radius of the arc.
  • int rx, int ry, int rangle: The arc can be rotated about the point (rx, ry), by rangle radians (not degrees!).
  • bool closed: If true, a line is drawn from the center of the circle to each endpoint of the arc, forming a sector of the circle.
  • bool fill: If true, a filled sector is drawn instead.
  • int opacity: controls how transparent the arc will be. Values other than 128 (solid) and 64 (translucent) are currently undefined.

Circle

Draws a circle on the specified layer of the current screen.

Introduced in Version
2.5 (beta)
Prototype and Arguments
void Circle(int layer, int x, int y, int radius,
            int color, float scale, int rx, int ry,
            int rangle, bool fill, int opacity)
  • int layer: The layer on which to draw the circle. Valid values are 0 through 6 (inclusive).
  • int x, int y: The center of the circle will be at the point (x,y).
  • int radius: The base radius of the circle. The overall radius of the circle will be radius * scale.
  • int color: The color of the circle (and its fill, if selected). color is an index into the entire 256-element palette: for instance, passing in a color of 17 would use color 1 of cset 1.
  • float scale: A value by which to scale the radius of the circle. A scale > 1 makes the circle larger, while a scale < 1 makes the circle smaller.
  • int rx, int ry, int rangle: The circle can be rotated about the point (rx, ry), by rangle degrees.
  • bool fill: If true, the circle is filled in with color.
  • int opacity: controls how transparent the circle will be. Values other than 128 (solid) and 64 (translucent) are currently undefined.

ClearSprites

Clears all of a certain kind of sprite from the screen.

Introduced in Version
2.5 (beta)
Prototype and Arguments
void ClearSprites(int spritelist)
  • int spritelist: The type of sprite to clear. Use the SL_ constants in std.zh.

DrawCharacter

Draws a single ASCII character on the specified layer of the current screen.

Introduced in Version
2.5 (beta 1065)
Prototype and Arguments
void DrawCharacter(int layer, int x, int y, int font,
             int color, int background_color,
             int width, int height, int glyph, int opacity)
  • int layer: The layer on which to draw the character. Valid values are 0 through 6 (inclusive).
  • int x, int y: Screen coordinates top-left corner of the glyph.
  • int font: The font to use. Pass in FONT_* values from std.zh.
  • int color: Color to draw the glyph.
  • int background_color: Color to draw behind the glyph. Use -1 for a transparent background.
  • int width, int height: the width and hight to draw the glyph. Values can be 1 through 512; using a 0 or negative number uses the font's default value.
  • int glyph: The ASCII value of the character to draw.
  • int opacity: controls how transparent the ellipse will be. Values other than 128 (solid) and 64 (translucent) are currently undefined.

DrawCombo

Draws a combo on the specified layer of the current screen, starting at (x,y), using the specified cset starting with the tile specified by the combo.

Introduced in Version
2.5 (beta)
Prototype and Arguments
void DrawTile(int layer, int x, int y,
              int combo, int blockw, int blockh,
              int cset, int xscale, int yscale,
              int rx, int ry, int rangle,
              int frame, int flip,
              bool transparency, int opacity)
  • int layer: The layer on which to draw the combo. Valid values are 0 through 6 (inclusive).
  • int x, int y: The top-left corner of the combo will be at the point (x,y).
  • int combo: The combo to draw on the screen, as identified by its combo number in the combo sheet. If a block is drawn, the tile referenced by this combo will be the tile in the top-left corner of the block.
  • int blockw, int blockh: The width and height of the block to draw. Must be between 1 and 20 (inclusive). Note that the block will be drawn using the tiles adjacent to the tile referenced by the combo, not the combos adjacent to the combo itself.
  • int cset: The CSet in which to draw the combo.
  • int xscale, int yscale: Width and height in pixels to scale the combo to. Set to -1 to use the default values.
  • int rx, int ry: The point on the screen about which to rotate the combo.
  • int rangle: The angle to rotate the combo.
  • int frame: The frame of the combo to draw.
  • int flip: Specifies how the combo should be flipped when drawn:
    • 0: No flip
    • 1: Vertical flip
    • 2: Horizontal flip
    • 3: Rotate 180 degrees
    • 4: Rotate clockwise 90 degrees
    • 7: Rotate counter-clockwise 90 degrees
  • bool transparency: If true, the combo's transparent regions will be respected..
  • int opacity: controls how transparent the solid portion of the combo will be. Values other than 128 (solid) and 64 (translucent) are currently undefined.

DrawTile

Draws a block of tiles on the specified layer of the current screen, starting at (x,y), using the specified cset.

Introduced in Version
2.5 (beta)
Prototype and Arguments
void DrawTile(int layer, int x, int y,
              int tile, int blockw, int blockh,
              int cset, int xscale, int yscale,
              int rx, int ry, int rangle,
              int flip, bool transparency, int opacity)
  • int layer: The layer on which to draw the tiles. Valid values are 0 through 6 (inclusive).
  • int x, int y: The top-left corner of the block of tiles will be at the point (x,y).
  • int tile: The tile to draw on the screen, as identified by its tile number in the tile sheet. If a block of tiles is drawn, this tile will be the tile in the top-left corner of the block.
  • int blockw, int blockh: The width and height of the block of tiles to draw. Must be between 1 and 20 (inclusive).
  • int cset: The CSet in which to draw the tile(s).
  • int xscale, int yscale: Width and height in pixels to scale the block of tiles to. Set to -1 to use the default values.
  • int rx, int ry: The point on the screen about which to rotate the tiles.
  • int rangle: The angle to rotate the tiles.
  • int flip: Specifies how the tiles should be flipped when drawn:
    • 0: No flip
    • 1: Vertical flip
    • 2: Horizontal flip
    • 3: Rotate 180 degrees
    • 4: Rotate clockwise 90 degrees
    • 7: Rotate counter-clockwise 90 degrees
  • bool transparency: If true, the tiles' transparent regions will be respected..
  • int opacity: controls how transparent the solid portion of the tile(s) will be. Values other than 128 (solid) and 64 (translucent) are currently undefined.

Ellipse

Draws an ellipse on the specified layer of the current screen.

Introduced in Version
2.5 (beta)
Prototype and Arguments
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)
  • int layer: The layer on which to draw the ellipse. Valid values are 0 through 6 (inclusive).
  • int x, int y: The center of the ellipse will be at the point (x,y).
  • int xradius: The base radius of the ellipse parallel to the x-axis. The overall x-radius of the ellipse will be xradius * scale.
  • int yradius: The base radius of the ellipse parallel to the y-axis. The overall y-radius of the ellipse will be yradius * scale.
  • int color: The color of the ellipse (and its fill, if selected). color is an index into the entire 256-element palette: for instance, passing in a color of 17 would use color 1 of cset 1.
  • float scale: A value by which to scale the xradius and yradius of the ellipse. A scale > 1 makes the ellipse larger, while a scale < 1 makes the ellipse smaller.
  • int rx, int ry, int rangle: The ellipse can be rotated about the point (rx, ry), by rangle degrees.
  • bool fill: If true, the ellipse is filled in with color.
  • int opacity: controls how transparent the ellipse will be. Values other than 128 (solid) and 64 (translucent) are currently undefined.

FastCombo

An Optimized and simpler version of DrawCombo().

Introduced in Version
2.5 (beta 1119)
Prototype and Arguments
void FastCombo(int layer, int x, int y,
             int combo, int cset, int opacity)
  • int layer: The layer on which to draw the combo. Valid values are 0 through 6 (inclusive).
  • int x, int y: The top-left corner of the combo will be at the point (x,y).
  • int combo: The combo to draw on the screen, as identified by its combo number in the combo sheet.
  • int cset: The CSet in which to draw the combo.
  • int opacity: controls how transparent the solid portion of the combo will be. Values other than 128 (solid) and 64 (translucent) are currently undefined.

FastTile

An Optimized and simpler version of DrawTile().

Introduced in Version
2.5 (beta 1119)
Prototype and Arguments
void FastTile(int layer, int x, int y,
             int Tile, int cset, int opacity)
  • int layer: The layer on which to draw the tile. Valid values are 0 through 6 (inclusive).
  • int x, int y: The top-left corner of the tile will be at the point (x,y).
  • int combo: The tile to draw on the screen, as identified by its tile number in the tile sheet.
  • int cset: The CSet in which to draw the tile.
  • int opacity: controls how transparent the solid portion of the tile will be. Values other than 128 (solid) and 64 (translucent) are currently undefined.

IsSolid

Returns true if the screen positon (x,y) is solid (is within the unwalkable portion of a combo on layer 0, 1 , or 2). If (x,y) is outside of the screen bounds, it will return false.

Introduced in Version
2.5 (beta 961)
Prototype and Arguments
bool IsSolid(int x, int y)
  • int x, int y: the screen coordinates to check for solidity.

LayerMap

Returns the map being used for the nth layer on the screen.

Introduced in Version
2.5 beta 979
Prototype and Arguments
void LayerMap(int n)
  • int n: the layer to check. Values <1 or >6, or layers that have not been set up, return -1

LayerScreen

Returns the screen being used for the nth layer on the screen.

Introduced in Version
2.5 beta 979
Prototype and Arguments
void LayerScreen(int n)
  • int n: the layer to check. Values <1 or >6, or layers that have not been set up, return -1

Line

Draws a line on the specified layer of the current screen.

Introduced in Version
2.5 (beta)
Prototype and Arguments
void Line(int layer, int x, int y, int x2, int y2,
          int color, float scale,
          int rx, int ry, int rangle, int opacity)
  • int layer: The layer on which to draw the line. Valid values are 0 through 6 (inclusive).
  • int x, int y, int x2, int y2: The line will be drawn from the point (x,y) to the point (x2,y2).
  • int color: The color of the line. color is an index into the entire 256-element palette: for instance, passing in a color of 17 would use color 1 of cset 1.
  • float scale: A value by which to scale the line about its midpoint. A scale > 1 makes the line longer, while a scale < 1 makes the line shorter.
  • int rx, int ry, int rangle: The line can be rotated about the point (rx, ry), by rangle degrees.
  • int opacity: controls how transparent the line will be. Values other than 128 (solid) and 64 (translucent) are currently undefined.

LoadFFC

Returns a pointer to an FFC on the current screen. You can then use FFC methods and properties to monitor and control the FFC.

Introduced in Version
2.5 (beta)
Prototype and Arguments
ffc LoadFFC(int num)
  • int num: The ID, as specified in the FFC Editor, of the FFC to load.

Message

Prints the message string with given ID onto the screen.

Introduced in Version
2.5 (beta)
Prototype and Arguments
void Message(int string)
  • int string: The ID (as shown in the String Editor) of the string to display. This method's behavior is undefined if string is less than 1 or greater than the total number of messages in the quest.

PutPixel

Draws a raw pixel on the specified layer of the current screen at (x,y).

Introduced in Version
2.5 (beta)
Prototype and Arguments
void PutPixel(int layer, int x, int y, int color,
              int rx, int ry, int rangle, int opacity)
  • int layer: The layer on which to draw the pixel. Valid values are 0 through 6 (inclusive).
  • int x, int y: The pixel will be at the point (x,y).
  • int color: The color of the pixel. color is an index into the entire 256-element palette: for instance, passing in a color of 17 would use color 1 of cset 1.
  • int rx, int ry, int rangle: The pixel can be rotated about the point (rx, ry), by rangle degrees.
  • int opacity: controls how transparent the pixel will be. Values other than 128 (solid) and 64 (translucent) are currently undefined.

Rectangle

Draws a rectangle on the specified layer of the current screen.

Introduced in Version
2.5 (beta)
Prototype and Arguments
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)
  • int layer: The layer on which to draw the rectangle. Valid values are 0 through 6 (inclusive).
  • int x, int y: The top-left corner of the rectangle will be at point (x,y).
  • int x2, int y2: The bottom-right corner of the rectangle will be at point (x2,y2).
  • int color: The color of the rectangle (and its fill, if selected). color is an index into the entire 256-element palette: for instance, passing in a color of 17 would use color 1 of cset 1.
  • float scale: A value by which to scale the rectangle. The rectangle is scaled about its center (where its diagonals would cross). A scale > 1 makes the rectangle larger, while a scale < 1 makes the rectangle smaller.
  • int rx, int ry, int rangle: The rectangle can be rotated about the point (rx, ry), by rangle degrees.
  • bool fill: If true, the rectangle is filled in with color.
  • int opacity: controls how transparent the rectangle will be. Values other than 128 (solid) and 64 (translucent) are currently undefined.

TriggerSecrets

Introduced in Version
2.5 beta 1071
Prototype and Arguments
void TriggerSecrets()

Temporarily triggers screen secrets. To make secrets permanent, also set Screen->State[ST_SECRET] to true.


Properties

Although all combo properties are referenced using their position 'i' on the screen, it should be noted that (x,y) pixel coordinates can be converted to the combo location 'i' using the 'ComboAt(int x, int y)' utility routine, as shown in std.zh. This routine will take the (x,y) coordinates of a combo on the screen and convert them to a value that ComboX[i] can use.

It should also be noted that writing to ComboX[i] will function as expected.

int ComboC[i]

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

To get or set combo cset data for a combo anywhere in the game, use the Game->GetComboCSet and Game->SetComboCSet methods.

int ComboD[i]

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

To get or set ID information for combos on layers 1 through 6, use the GetLayerComboD and SetLayerComboD functions included in std.zh.

To get or set ID information for a combo anywhere in the game, use the Game->GetComboData and Game->SetComboData methods.

int ComboF[i]

The secret flag of the ith combo on the current screen (Layer 0), 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.

To get or set flag information for combos on layers 1 through 6, use the GetLayerComboF and SetLayerComboF functions included in std.zh.

To get or set combo flag information for a combo anywhere in the game, use the Game->GetComboFlag and Game->SetComboFlag methods.

int ComboI[i]

The inherent flag of the ith combo on the current screen (Layer 0), 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.

To get or set a combo inherent flag for a combo anywhere in the game, use the Game->GetComboInherentFlag and Game->SetComboInherentFlag methods.

int ComboS[i]

The solidity (walkability) mask of the ith combo on the current screen (Layer 0), where i is the index used to access this array. Combos are counted left to right, top to bottom.

To get or set solidity for combos on layers 1 through 6, use the GetLayerComboS and SetLayerComboS functions included in std.zh.

To get or set combo solidity for a combo anywhere in the game, use the Game->GetComboSolid and Game->SetComboSolid methods.

The value for solidity returned by these properties/methods is a "map" defining which of the four sections of a combo are solid. 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.

Use the bitwise AND operator to determine which portions of the combo are walkable. See Determining Combo Walkability.

See walkability for additional details on how the use of layers impacts solidity.

int ComboT[i]

The combo type of the ith combo on the current screen (Layer 0), 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.

To get or set combo type information for combos on layers 1 through 6, use the GetLayerComboT and SetLayerComboT functions included in std.zh.

To get or set combo type information for a combo anywhere in the game, use the Game->GetComboType and Game->SetComboType methods.

float D[i]

Each screen has 8 general purpose registers for use by script programmers. Do with these as you will. Note that these registers are tied to screen/DMap combinations. Encountering the same screen in a different DMap will result in a different D[] array.

int Door[i]

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.

int Flags[i]

The screen flags that the current screen has activated. Use the SF_ constants in std.zh to get the particular category, and then use bitwise operators to determine which flags within that category are activated.

bool Lit

Whether or not the screen is lit. Writing to this variable will change the lighting setting of the screen until you change screens.

int Wavy

The time, in frames, that the 'wave' screen effect will be in effect. This value is decremented once per frame. As the value of Wavy approaches 0, the intensity of the waves decreases.

int Quake

The time, in frames, that the screen will shake. This value is decremented once per frame. As the value of Quake approaches 0, the intensity of the screen shaking decreases.