22. ENGINE REFERENCE
defines and functions






G_FPS,
G_KEYS,
G_KEYSHIT,
G_ROOMX,
G_ROOMY,
G_ROOMW,
G_ROOMH,
G_MAPW,
G_MAPH,
G_VIEWX,
G_VIEWY,
G_PAUSE,
G_SHAKEX,
G_SHAKEY,
G_MAPCOLOR,
G_BORDERCOLOR,
G_FFMAGNITUDE,
G_FFPERIOD,
G_VIEWPORTMODE,
G_VIEWPORTX,
G_VIEWPORTY,
G_VIEWPORTFLIP,
G_FULLMATERIALMAP,
G_INVENTORY,
G_USER,
G_MAX,
CMD_START,
CMD_EXIT,
CMD_REFRESH,
GameFrame,
GameGet,
GameSet,
GameCommand,
GameSetName,
MapLoad


MAT_MAX,
MATD_VOID,
MATD_SOFT,
MATD_HARD,
MATD_JUMP,
MaterialGetDensity,
MaterialSetDensity,
MaterialGetColor,
MaterialSetColor,
MaterialRead,
MaterialDensityRead,
MaterialCheckFree,
MaterialGetFreeDist


TILE_ID,
TILE_W,
TILE_H,
TILE_FRAMES,
TILE_NAME,
TileFind,
TileCount,
TileGet,
TileLoad,
TileUnload


ScrGetHandlerData,
ScrSetHandlerData,
ScrGetRequest,
ScrGetRunning,
ScrRequest,
ScrKillLatent


B_LAYER,
B_X,
B_Y,
B_W,
B_H,
B_TILE,
B_FRAME,
B_MAP,
B_FLIP,
B_COLOR,
B_SHADER,
B_SCALE,
B_ID,
B_MATERIAL,
B_DRAW,
B_DELAY,
B_ANIM,
B_MAX,
BrushCount,
BrushFind,
BrushGet,
BrushSet


O_LAYER,
O_X,
O_Y,
O_W,
O_H,
O_TILE,
O_FRAME,
O_MAP,
O_FLIP,
O_COLOR,
O_SHADER,
O_SCALE,
O_ID,
O_MATERIAL,
O_DRAW,
O_DISABLE,
O_DELAY,
O_ANIM,
O_COLLIDER,
O_CLASS,
O_STATUS,
O_TARGET,
O_COLLISION,
O_USER,
O_MAX,
ObjCount,
ObjFind,
ObjGet,
ObjSet,
ObjGetName,
ObjSetName,
ObjPresent,
ObjPresentCount,
ObjPresentIdx,
ObjPresentGather,
ColliderSnapDistance


R_MAX,
RoomGet,
RoomSet,
RoomGetName,
RoomSetName


P_DISABLE,
P_STATUS,
P_DELAY,
P_LAYER,
P_X,
P_Y,
P_W,
P_H,
P_TILE,
P_FRAME,
P_ANIM,
P_FLIP,
P_COLOR,
P_SHADER,
P_EMOTION,
P_DIR,
P_POW,
P_COSTUNE,
P_TILEIDLE,
P_TILEWALK,
P_TILEUP,
P_TILEJUMP,
P_AIRLEVEL,
P_STUNLEVEL,
P_MATINSIDE,
P_MATUNDER,
P_MATCENTER,
P_LIFE,
P_CREDITS,
P_COINS,
P_XSAFE,
P_YSAFE,
P_SAFE,
P_CUSTOMMOVE,
P_DEATH,
P_USER,
P_MAX,
STATUS_IDLE,
STATUS_WALK,
STATUS_JUMP,
STATUS_FALL,
STATUS_SCRIPTED,
PlayerGet,
PlayerSet,
PlayerMakeBB,
PlayerMakeBBW


DLG_STYLE,
DLG_X,
DLG_Y,
DLG_W,
DLG_H,
DLG_COLOR,
DLG_FONT,
DLG_USER,
DLG_MAX,
DlgPush,
DlgPop,
DlgPopAll,
DlgCount,
DlgGet,
DlgSet,
DlgGetText,
DlgSetText


SOUND_VOICES,
SampleLoad,
SampleUnload,
SamplePlay,
SamplePlaying,
SampleStop,
SampleStopAll,
SampleVolume


MusicLoad,
MusicUnload,
MusicFade,
MusicPlay,
MusicPlaying,
MusicPosition,
MusicStop,
MusicVolume


SHADER_OPAQUE,
SHADER_BLEND,
SHADER_ADD,
SHADER_MOD,
SHADER_MOD2,
HudDrawTile,
HudDrawText,
HudGetTextWidth,
HudGetTextHeight,
HudGetTextRows,
HudGetTextColumns,
HudClipping,
HudFont,
HudShader,
HudColor


FontLoad,
FontUnload


KEY_LEFT,
KEY_RIGHT,
KEY_UP,
KEY_DOWN,
KEY_JUMP,
KEY_ACTION,
KEY_MENU,
KeyboardRead,
KeyboardStatus,
KeyboardCodeToChar,
KeyboardCharToCode,
JoystickStatus,
gsJoystickAxe


DebugData,
DebugCool,
DebugLog,
DebugDev,
DebugCallstack




G_FPS 0
Game property, fixed fps (default 36).
This tells how often the game is updated.
The default value ensures that, if the player is update once each three game cycles, it will go as fast as the original Dizzy games.

G_KEYS 1
Game property, input keys status values, on bits.
bit 0=KEY_LEFT
bit 1=KEY_RIGHT
bit 2=KEY_UP
bit 3=KEY_DOWN,
bit 4=KEY_JUMP
bit 5=KEY_ACTION
bit 6=KEY_MENU
As an example when this is 2 (binary 10), the right key is pressed down.
It is set by the engine, depending on which keys the player presses.
It can be overwriten in script, to cancel the user's input, or to simulate it.

G_KEYSHIT 2
Game property, input keys hit status values, on bits.
bit 0=KEY_LEFT
bit 1=KEY_RIGHT
bit 2=KEY_UP
bit 3=KEY_DOWN,
bit 4=KEY_JUMP
bit 5=KEY_ACTION
bit 6=KEY_MENU
Tells if the key has just been pressed down.
This means the previous frame it was up, and now it is down.
As an example when this is 2 (binary 10), the right key has just been pressed down.
It is set by the engine, depending on which keys the player presses.
It can be overwriten in script, to cancel the user's input, or to simulate it.

G_ROOMX 3
Game property, current room x coordinate.
These run from 0 (left) to GameGet(G_MAPW)-1 (right).
It is set by the engine, depending on the player's position.
Read only!

G_ROOMY 4
Game property, current room y coordinate.
These run from 0 (top) to GameGet(G_MAPH)-1 (bottom).
It is set by the engine, depending on the player's position.
Read only!

G_ROOMW 5
Game property, room width in pixels.
Set from the map, usually 240, for classic Dizzy games.
Read only!

G_ROOMH 6
Game property, room height in pixels.
Set from the map, usually 136, for classic Dizzy games.
Read only!

G_MAPW 7
Game property, width of the map in rooms (horizontal number of rooms).
This come from the map, as created in the editor.
Read only!

G_MAPH 8
Game property, height of the map in rooms (vertical number of rooms).
This come from the map, as created in the editor.
Read only!

G_VIEWX 9
Game property, horizontal position of the room's view, in pixels, as it's displayed on the screen.
It is usually set at game initialization.

G_VIEWY 10
Game property, vertical position of the room's view, in pixels, as it's displayed on the screen.
It is usually set at game initialization.

G_PAUSE 11
Game property, pause status, 0=not paused, 1=paused.

G_SHAKEX 12
Game property, horizontal offset of the room's view, in pixels, as it's displayed on the screen.
This can be used for shake effects.

G_SHAKEY 13
Game property, vertical offset of the room's view, in pixels, as it's displayed on the screen.
This can be used for shake effects.

G_MAPCOLOR 14
Game property, map background color, usually black (0xff000000).

G_BORDERCOLOR 15
Game property, window borders color, outside the game's screen, usually black (0xff000000).

G_FFMAGNITUDE 16
Game property, rumble (force feedback) magnitude [0..100].
Default 0=no rumble.

G_FFPERIOD 17
Game property, rumble (force feedback) period (miliseconds).
Default 50.

G_VIEWPORTMODE 18
Game property, viewport mode.
Set to 0 (normal) for classic games and to 1 (extended) for games that do scrolling.
In extended mode, 3x3 rooms are painted, with the current room in the center.
This property can be enabled and disabled at runtime if the game wants to
alternate scrolling with classic rooms.
The scrolling offsets can be applied in AfterUpdate handler as
viewportx = roomx*roomw - playerx + roomw/2
viewporty = roomy*roomh - playery + roomh/2
Default 0.
See G_VIEWPORTX, G_VIEWPORTY, G_VIEWPORTFLIP.

G_VIEWPORTX 19
Game property, viewport x offset.
Used in extended viewport mode for scrolling.
Default 0.
See G_VIEWPORTMODE.

G_VIEWPORTY 20
Game property, viewport y offset.
Used in extended viewport mode for scrolling.
Default 0.
See G_VIEWPORTMODE.

G_VIEWPORTFLIP 21
Game property, viewport flip option.
Used to invert the viewport image on vertical or/and horisontal.
Set to 0=no flip, 1=horizontal, 2=vertical, 3=both.
Default 0.
See G_VIEWPORTMODE.

G_FULLMATERIALMAP 22
Game property, size of the material map.
If set 0 brushes write their material in the material map for the current room
with a small borrder arround it. If set to 1 (full) the full material map will
be written. That is 3x3 rooms with the current room in the center.
The full material map may be needed for some games with scrolling and AI
using the material map outside the current room.
The property can be changed at runtime if needed and it will require a refresh
command to redraw the new material map.
Default 0.
See material access functions.

G_INVENTORY 50
Game property, inventory slots up to G_USER.
These are supposed to be used in the inventory implementation to store owned items.
In the default template, in these properties are stored the indexes of the owned item objects.
If a slot is free, the value of it's property is -1.

G_USER 64
Game property, user.
Starting with this one, users can store anything they need, up to G_MAX

G_MAX 256
Game property, dummy value, representing the number of game properties.

CMD_START 0
Game command define, used with the GameCommand() function.
Start game command is used to request the game to be restarted.
Use it when player dies or asks for restart in the game menu.

CMD_EXIT 1
Game command define, used with the GameCommand() function.
Exit command will close the game application.
Use it when quit is asked.

CMD_REFRESH 2
Game command define, used with the GameCommand() function.
Refresh command will instruct the engine to repaint the material map for the current room.
Use it after you changed some brushes that write in the material map.

int GameFrame( )
OUTintcurrent game frame
Returns the current game frame.
The game frame starts from 0 and it's incremented by the engine, on each game cycle.
You can use it to wait a number of frames, or in object's updates.

int GameGet( idx )
INintidxgame property index [0..G_MAX-1]
OUTintgame property value
Gets the value of a game property.
See G_FPS, G_KEYS, G_KEYSHIT, G_ROOMX, G_ROOMY, etc.

GameSet( idx, value )
INintidxgame property index [0..G_MAX-1]
INintvaluegame property value
Sets the value of a game property.
See G_FPS, G_KEYS, G_KEYSHIT, G_ROOMX, G_ROOMY, etc.

GameCommand( command )
INintcommandgame command index
Requests a game command from the engine.
See CMD_START, CMD_EXIT and CMD_REFRESH.

GameSetName( name )
INstrnamegame name
Sets the name of the game, that will appear in the window's title bar.

MapLoad( filename )
INstrfilenamegame map file
Loads the specified map file.
Path should be relative to the game's folder (ex: data\map\dizzy.map)



MAT_MAX 32
Dummy value, representing the maximum number of possible materials.
The materials values are defined in script.

MATD_VOID 0
Material void density.
Player falls through materials with void density.

MATD_SOFT 1
Material soft density.
Materials with soft density, stop the player's fall but keep him sinking through, like clouds.

MATD_HARD 2
Material hard density.
Materials with hard density, stop the player's fall and blocks his way, like ground or walls.

MATD_JUMP 3
Materials with jump density, stop the player's fall and make him jump.

int MaterialGetDensity( matidx )
INintmatidxmaterial index [0..MAT_MAX-1]
OUTintdensity value
Gets the material's density.

MaterialSetDensity( matidx, value )
INintmatidxmaterial index [0..MAT_MAX-1]
INintvaluematerial density value
Sets the material density.
Used it when the game is initialized, to prepare the game's materials.
See MAT_VOID, MAT_SOFT, MAT_HARD, MAT_JUMP

int MaterialGetColor( idx )
INintidxmaterial index [0..MAT_MAX-1]
OUTintmaterial color
Gets the material color, that is used to display the material map for debug purposes.

MaterialSetColor( idx, color )
INintidxmaterial index [0..MAT_MAX-1]
INintcolormaterial color
Sets the material color that is used to display the material map for debug purposes.
Used it when the game is initialized, to prepare the game's materials.

int MaterialRead( x, y, w, h )
INintxhorizontal coordinate in room [0..GameGet(G_ROOMW)-1]
INintyvertical coordinate in room [0..GameGet(G_ROOMH)-1]
INintwwidth
INinthheight
OUTintfound materials, on bits
Read materials found in a specified rectangle, in the material map.
The materials are returned on their coresponding bits.
Ex: if only material 0 (air) and 2 (hurt) are found, the result will be 5 (binary 101).
If G_FULLMATERIALMAP is enabled materials can be read an extanded range of 3x3 rooms:
[-GameGet(G_ROOMW)..2*GameGet(G_ROOMW)-1] x [-GameGet(G_ROOMH)..2*GameGet(G_ROOMH)-1]
Outside the material map material 0 is considered.

int MaterialDensityRead( x, y, w, h )
INintxhorizontal coordinate in room [0..GameGet(G_ROOMW)-1]
INintyvertical coordinate in room [0..GameGet(G_ROOMH)-1]
INintwwidth
INinthheight
OUTintfound densities on bits
Read materials densities found in a specified rectangle, in the material map.
The densities of the found materials are returned on the coresponding bits.
Ex: if only materials with void (0) and block (2) densities are found, the result will be 5 (binary 101).
See MaterialRead.

int MaterialCheckFree( x1, y1, x2, y2 )
INintx1left coordinate in room [0..GameGet(G_ROOMW)-1]
INinty1top coordinate in room [0..GameGet(G_ROOMH)-1]
INintx2right coordinate in room [0..GameGet(G_ROOMW)-1]
INinty2bottom coordinate in room [0..GameGet(G_ROOMH)-1]
OUTint0=blocked, 1=free
Read materials found in a specified rectangle, in the material map.
If at least one hard density material is found, 0 is returned.
Usefull for custom movements.
See MaterialRead.

int MaterialGetFreeDist( x1, y2, x2, y2, dir, hardonly )
INintx1left coordinate in room [0..GameGet(G_ROOMW)-1]
INinty2top coordinate in room [0..GameGet(G_ROOMH)-1]
INintx2right
INinty2bottom
INintdirdirection 0=top to bottom, 1=bottom to top
INinthardonlymaterials filter 0=stop on non-void, 1=stop only on hard
OUTintfree distance
Read materials found in a specified rectangle, in the material map.
Returns the free distance in the rectangle, on the specified direction, with respect to the hardonly option.
If the hardonly option is 1, all materials but hard ones, are considered free.
If the hardonly option is 0, only void materials are considered free.
For example, if the direction is 0, meaning top to bottom, this function
will scan from the top of the rectangle, down to the bottom, until a blocking material is found
and it will return the number of free scanned lines.
Usefull for custom movements.
See MaterialRead.



TILE_ID 0
Tile's ID property, as specified in the tile's file name.
See TileGet().

TILE_W 1
Tile's width property, representing the whole tile image width.
See TileGet().

TILE_H 2
Tile's height property.
See TileGet().

TILE_FRAMES 3
Tile's frames property.
See TileGet().

TILE_NAME 5
Tile's file name.
See TileGet().

int TileFind( id )
INintidtile id
OUTinttile index or -1 if not found
Finds a tile index based on it's ID.

int TileCount( )
OUTinttotal number of loaded tiles
Returns the total number of loaded tiles.

int|str TileGet( idx, prop )
INintidxtile index
INintproptile property to get
OUTint|strtile's property value
Gets a tile's property.
Returns an integer value, or, in the case of TILE_NAME, a string.
See: TILE_ID, TILE_W, TILE_H, TILE_FRAMES, TILE_NAME

int TileLoad( path, group=0 )
INstrpathtiles directory, relative to the game's path
[IN]intgroup=0resource group
OUTint1=success, 0=errors
Loads all tiles from the specified path and from the folders inside it.
The group can be used to later unload only some of the loaded resources.
Ex: data\tiles

TileUnload( group=0 )
[IN]intgroup=0resource group
Unloads all tiles from memory.
The group can be used to unload only some of the loaded resources.



int ScrGetHandlerData( idx )
INintidxhandler data slot
OUTinthandler data value
Gets handler data.
It is used in handler functions, to receive data send by the engine.
This is because the handler functions don't have parameters.
If available, the data and it's slots are specific to each handler.

ScrSetHandlerData( idx, value )
INintidxhandler data slot
INintvaluehandler data value
Sets handler data.
It is used in handler functions, to send data back to the engine.
If required, the data and it's slots are specific to each handler.

int ScrGetRequest( )
OUTintfunction id
Returns the function id requested with ScrRequest.
The request is valid only in the game cycle it was made.
After that it is used (if possible) and cleared with -1.
Use this to check if there were other requests made in this frame.

int ScrGetRunning( )
OUTintfunction id or -1
Returns the id of the root function (the one used in ScrRequest), if the latent virtual machine is busy.
If no latent script is running it returns -1.

ScrRequest( fid )
INintfidfunction id
Requests a function to be executed by the latent virtual machine.
The function's id can be obtained with the gs_fid() instruction.
The request is usually made fron non-latent functions.
If the latent machine is busy running another script when the request is processed, it will be ignored.

ScrKillLatent( )
Request engine to kill (stop) the running latent script, if any.
Like with ScrRequest, the action is not performed instantly.
It can be called from a latent code, too.
You can also use it to kill the current running script, before requesting another.
See ScrRequest().



B_LAYER 0
Brush property, layer index.

B_X 1
Brush property, horizontal coordinate in world (top left corner).

B_Y 2
Brush property, vertical coordinate in world (top left corner).

B_W 3
Brush property, width in pixels.

B_H 4
Brush property, height in pixels.

B_TILE 5
Brush property tile id.

B_FRAME 6
Brush property, starting animation frame.
In case of looping animations, this is the starting frame.
For not animated brushes this frame is always displayed.

B_MAP 7
Brush properties, mapping coordinates on the tile (4 properties).
The four mapping coordinates represent the top-left and bottom-right corners in pixels (x1,y1,x2,y2).
Use BrushGet(B_MAP) for x1, BrushGet(B_MAP+1) for y1 and so on.

B_FLIP 11
Brush property, flip option on bits.
bit 0=flip horizontal
bit 1=flip vertical
bit 2=rotate 90 degrees
Ex: 1=flip x, 3=flip both xy, 4=rotate, 5=rotate and flip x
This flips and rotates only the mapping, not the width and height of the brush.

B_COLOR 12
Brush property, color.

B_SHADER 13
Brush property, shader.
See: SHADER_OPAQUE, SHADER_BLEND, SHADER_ADD, SHADER_MOD, SHADER_MOD2

B_SCALE 14
Brush property, scale.
This doesn't scale the brush size, but the mapping inside it.

B_ID 17
Brush property, id.
The brush id can be used to access the brush from script.
Read only!
See BrushFind().

B_MATERIAL 18
Brush property, material
The material is written in the material map, if the B_DRAW property is set to do so.

B_DRAW 19
Brush property, draw mode.
Available draw modes for static brushes:
0=don't draw at all, used to hide the brush
1=draw in view and not in material map
2=draw in material map and not in view
3=draw both in view and in material map
Uses the material specified by B_MATERIAL to write in the material map.

B_DELAY 21
Brush property, frame delay.
This is the number of game cycles that are waited, between animation frames.
Higher values result in a lower animation speed.

B_ANIM 22
Brush property, animation mode.
0 = animation stopped
1 = not supported for brushes (same as stopped)
2 = animation loops (starts again, from the first frame)
Animation starts with the frame set in the B_FRAME property and this
can be used to syncronize or de-syncronize the animation of different
brushes, for example to avoid having all fire flames animated in the same way.

B_MAX 48
Brush property, dummy counter representing the total number of brush properties.

int BrushCount( )
OUTintnumber of brushes
Returns the total number of brushes (static brushes) in the map.

int BrushFind( id )
INintidbrush id
OUTintbrush index or -1 if brush not found
Finds a brush by it's id.
The returned brush index can be used to access the brush's properties.
See BrushGet() and BrushSet().

int BrushGet( brush index, brush property )
INintbrush index
INintbrush property
OUTintproperty value
Gets the property value of the specified brush.
Use BrushFind() to get the brush index.
See brush properties: B_LAYER, B_X, B_Y, etc.

BrushSet( idx, property, value )
INintidxbrush index
INintpropertybrush property
INintvalueproperty value
Sets the property value of the specified brush.
Use BrushFind() to get the brush index.
See brush properties: B_LAYER, B_X, B_Y, etc.



O_LAYER 0
Object property, layer index.

O_X 1
Object property, horizontal coordinate in world (top left corner).

O_Y 2
Object property, vertical coordinate in world (top left corner).

O_W 3
Object property, width in pixels.

O_H 4
Object property, height in pixels.

O_TILE 5
Object property, tile id

O_FRAME 6
Object property, current animation frame (starts with 0).
This gets incremented as the animation plays.
It is not limited by the number of frames of the tile.

O_MAP 7
Object properties, mapping coordinates on the tile (4 properties).
The four mapping coordinates represent the top-left and bottom-right corners in pixels (x1,y1,x2,y2).
Use ObjGet(O_MAP) for x1, ObjGet(O_MAP+1) for y1 and so on.

O_FLIP 11
Object property, flip option on bits.
bit 0=flip horizontal
bit 1=flip vertical
bit 2=rotate 90 degrees
Ex: 1=flip x, 3=flip both xy, 4=rotate, 5=rotate and flip x
This flips and rotates only the mapping, not the width and height of the object.

O_COLOR 12
Object property, color.

O_SHADER 13
Object property, shader.
See: SHADER_OPAQUE, SHADER_BLEND, SHADER_ADD, SHADER_MOD, SHADER_MOD2

O_SCALE 14
Object property, scale.
This doesn't scale the object size, but the mapping inside it.

O_ID 17
Object property, id.
The object id can be used to access the object from script.
Read only!
See ObjFind().

O_MATERIAL 18
Object property, material
This is not used, since objects can't write it in the material map.

O_DRAW 19
Object property, draw mode.
Available draw modes for objects:
0=don't draw, used to hide the object
1=draw, used to show the object
Objects don't draw in the material map, like the brushes, so only two values are valid for their draw mode.

O_DISABLE 20
Object property, disable.
Value 0=enable, 1=disable.
Disabled objects are to be ignored.
When an object is disabled it will not be painted, nor it's animation updated.
Disabled items will not be pickable until enabled again, and so on.

O_DELAY 21
Object property, frame delay.
This is the number of game cycles that are waited, between animation frames.
Higher values result in a lower animation speed.
Animation is not incremented if the object is disabled.

O_ANIM 22
Object property, animation mode.
0 = animation stopped
1 = animation play only once and stops on the last frame
2 = animation loops (starts again, from the first frame)
Animation is not playing if the object is disabled.

O_COLLIDER 23
Object property, collider mode.
0=none
1=call collider handler
2=hard collision, player tries to stand on these objects

O_CLASS 24
Object property, generic class.
The default template uses the object class to implement specific functionality.
Ex: CLASS_NONE, CLASS_ACTION, CLASS_HURT, CLASS_KILL, CLASS_ITEM, CLASS_COIN, etc

O_STATUS 25
Object property, generic status.
Used to store logic information about the status of the object, the progress of a puzzle, or anything the user needs.

O_TARGET 26
Object property, generic target.
Used to link or reffer to another object, using it's object id property.

O_COLLISION 27
Object property, collision with player (1 or 0).
It's used by the engine to store the status of the collision of this object with the player.
It's set for colliding objects only.
Read only!

O_USER 32
Object property, user data.
Starting with this property, users can store whatever they need, up to O_MAX property.
Some AI objects store in these properties information, used for their specific behaviours.

O_MAX 48
Object property, dummy counter representing the total number of object properties.

int ObjCount( )
OUTintnumber of objects
Returns the total number of objects (dynamic brushes) in the map.

int ObjFind( id )
INintidobject id
OUTintobject index or -1 if object not found
Finds an object by it's id.
The returned object index can be used to access the object's properties.
See ObjSet() and ObjGet().

int ObjGet( object index, object property )
INintobject index
INintobject property
OUTintproperty value
Gets the property value of the specified object.
Use ObjFind() to get the object index.
See object properties: O_LAYER, O_X, O_Y, etc.

ObjSet( idx, property, value )
INintidxobject index
INintpropertyobject property
INintvalueproperty value
Sets the property value of the specified object.
Use ObjFind() to get the object index.
See object properties: O_LAYER, O_X, O_Y, etc.

str ObjGetName( idx )
INintidxobject index
OUTstrname of the object
Gets the name of the object, as it was set before, from the script.
See ObjSetName().

ObjSetName( idx, name )
INintidxobject index
INstrnamename of the object
Sets the name of the object.
The name of an object is displayed in the inventory dialog, if the object is an item.
So, unless the game implements a different behaviour, you must set names only for item class objects.

ObjPresent( idx )
INintidxobject index
Inform the engine that the specified object is present in the current room.
When a room is entered, the engine sets all objects found inside it as present.
Later, if other objects are moved inside, they must be presented with this function.
Only objects present in the current room are painted and can be interacted with.

int ObjPresentCount( )
OUTintnumber of objects
Returns the number of objects present in the current room.

int ObjPresentIdx( presentidx )
INintpresentidxpresent index [0..ObjPresentCount()-1]
OUTintobject index
Returns the index of the present object, used to enumerate present objects.
Under some conditions, this may save a lot of CPU power by avoiding to iterate through all the objects in the map.

ObjPresentGather( )
Request the engine to refresh the list of objects present in the current room.
This may be used, when a lot of objects have been moved in the current room, and you didn't present each of them.
This action is performed by the engine each time a new room is entered.

int ColliderSnapDistance( x1, y1, x2, y2 )
INintx1left
INinty1top
INintx2right
INinty2bottom
OUTintdistance
Returns the distance from the bottom of the box, to the top of a hard collider object, if that is inside the given box.
It's used in player's movement, to snap it on top of hard colliding objects.



R_MAX 8
Room property, dummy counter representing the total number of room properties.

int RoomGet( rx, ry, idx )
INintrxroom horizontal coordinate in map [0..GameGet(G_MAPW)-1]
INintryroom vertical coordinate in map [0..GameGet(G_MAPH)-1]
INintidxroom property index [0..R_MAX-1]
OUTintroom's property
Gets a room property.

RoomSet( rx, ry, idx, val )
INintrxroom horizontal coordinate in map [0..GameGet(G_MAPW)-1]
INintryroom vertical coordinate in map [0..GameGet(G_MAPH)-1]
INintidxroom property index [0..R_MAX-1]
INintvalroom's property value
Sets a room property.

str RoomGetName( rx, ry )
INintrxroom horizontal coordinate in map [0..GameGet(G_MAPW)-1]
INintryroom vertical coordinate in map [0..GameGet(G_MAPH)-1]
OUTstrroom's name, that appears on the HUD.
Gets the room's name.

RoomSetName( rx, ry, name )
INintrxroom horizontal coordinate in map [0..GameGet(G_MAPW)-1]
INintryroom vertical coordinate in map [0..GameGet(G_MAPH)-1]
INstrnameroom's name, that appears on the HUD.
Sets the room's name.



P_DISABLE 0
Player property, disable.
Value 0=enabled, 1=disabled.
If disabled, no update and no draw for the player.

P_STATUS 1
Player property, status.
It stores the movement status.
See STATUS_IDLE, STATUS_WALK, etc.

P_DELAY 2
Player property, delay.
It's the number of game cycles allowed to pass, between player's updates.
Higher values result in a slower player animation and movement.
Default value is 3, coresponding to the player's speed in the original Dizzy games.
Here, this means that the player is updated from 3 to 3 game frames.
This can be used to syncronize the update of other objects with the player.

P_LAYER 3
Player property, layer.
This is the layer where the player is painted, after all other static or dynamic objects.
All the brushes from higher layers will be painted over the player, giving the senzation it moves behind them.

P_X 4
Player property, horizontal coordinate in the world.
The player's position is given in the center of the player's bounding box, not in the top-left corner, as for objects.
Also, the player's position determine the current room's coordinates.
So, by moving the player arround the map, the room will be changed by the engine to match the player's position.

P_Y 5
Player property, vertical coordinate in the world.
The player's position is given in the center of the player's bounding box,
not in the top-left corner, as for objects.
Also, the player's position determine the current room's coordinates.
So, by moving the player arround the map, the room will be changed by the engine to match the player's position.

P_W 6
Player property, width.
This is the width of the player's bounding box, that is centered in the player's position.
The bounding box is used to determine collision with the material map and with other objects.
It does NOT restrict the tile, as the width of brushes does. See also P_TILE.

P_H 7
Player property, height.
This is the height of the player's bounding box, that is centered in the player's position.
The bounding box is used to determine collision with the material map and with other objects.
It does NOT restrict the tile, as the width of brushes does. See also P_TILE.

P_TILE 8
Player property, tile.
The player's current animation frame is displayed at the player's position with an offset rule.
It is horizontally centered at the player's x coordinate.
On vertical, it is aligned with the bottom of the player's bounding box.
This makes it easy to use tiles with different sizes.

P_FRAME 9
Player property, the animation frame (starts with 0).
This gets incremented on each player's update and is not limited by the tile's number of frames.

P_ANIM 10
Player property, animation mode
0 = animation stopped
1 = animation play only once and stops on the last frame
2 = animation loops (starts again, from the first frame)

P_FLIP 11
Object property, flip option on bits.
bit 0=flip horizontal
bit 1=flip vertical
bit 2=rotate 90 degrees
Ex: 1=flip x, 3=flip both xy, 4=rotate, 5=rotate and flip x

P_COLOR 12
Player property, color

P_SHADER 13
Player property, shader
See: SHADER_OPAQUE, SHADER_BLEND, SHADER_ADD, SHADER_MOD, SHADER_MOD2

P_EMOTION 14
Player property, emotion tile.
This is an offset added to the tile id, specified by the P_TILEIDLE property.
It's used to achive various emotions while in idle state, like no air underwater, or eating food.
For example if the P_TILEIDLE specify the tile id 10, that is normally the
tile displayed when Dizzy is in STATUS_IDLE, and no emotion is set (0).
If we set the emotion property to 6 (no air), the id of the idle tile will be 10+6=16.
Defailt value is 0, for no emotion.

P_DIR 15
Player property, movement direction
-1=left
0=stop or up
1=right

P_POW 16
Player property, power for jump and fall.

P_COSTUNE 17
This is an offset used when calculate the tile id for the player.
The difference from the P_EMOTION offset is that this offest is applied to all animation states.
So it's very usefull for full sets of different tiles, like costumes.
You have a normal set of tiles, including all aimations, and then you can have
a similar set with scuba diving equipped, or another with a space suit.
See custom movement.gs file for detals.

P_TILEIDLE 18
Player property, tile id for idle status.
The tile displayed in idle, is this id plus the id offset from the P_EMOTION property.

P_TILEWALK 19
Player property, tile id for walk status.

P_TILEUP 20
Player property, tile id for jump up status.

P_TILEJUMP 21
Player property, tile id for jump side status.

P_AIRLEVEL 22
Player property, air level.
0 = normal air (full)
100 = critical AIR_LEVEL (empty)

P_STUNLEVEL 23
Player property, stun level
0 = normal stun (none)
STUN_LEVEL or above = critical (stunned)

P_MATINSIDE 24
Player property, materials inside player's box on bits.
This can be used to test if the player is moving through fire materials, or similar situations.

P_MATUNDER 25
Player property, materials right under player's box on bits.
This can be used to test on what kind of materials, the player stands on.

P_MATCENTER 26
Player property, material in center of player's box (at mouth point).
This can be used to test if player is in water material.

P_LIFE 27
Player property, life energy [0,100]
This is displayed on the HUD, as an energy bar.

P_CREDITS 28
Player property, life credits.
This is displayed on the HUD as small life eggs.

P_COINS 29
Player property, collected coins count.
This is displayed on the HUD.

P_XSAFE 30
Player property, last safe position x in world (stabil).
This is used to remember the last safe pozition of the player.
When he must be respawned, he is repositioned at this safe coordinates.

P_YSAFE 31
Player property, last safe position y in world (stabil).
This is used to remember the last safe pozition of the player.
When he must be respawned, he is repositioned at this safe coordinates.

P_SAFE 32
Player property, safe status.
This is used to know when the player is in a safe position, so it can be stored for later use.
Unstable positions, like water or hurt materials, or places where the player gets hurt, are not considered safe.

P_CUSTOMMOVE 33
Player property, custom movement.
It tells the engine if it should handle the default player's movement (0),
or if the user has implemented a custom movement for the player, in the script (1).

P_DEATH 34
Player property, cause of death.
This property is set from the script when a hurt or kill objects hits the player.
The value set is the one from the object's O_DEATH and it can be tested for a specific death message, or for a special respawn.
You can also set this value when you kill the player (set it's life to 0).

P_USER 64
Player property, user data.
Starting with this property, users are free to store anything they need, up to P_MAX

P_MAX 128
Player property, dummy value, representing the total number of player properties.

STATUS_IDLE 0
Player idle status. See P_STATUS.

STATUS_WALK 1
Player walk status. See P_STATUS.

STATUS_JUMP 2
Player jump status. See P_STATUS.

STATUS_FALL 3
Player fall status. See P_STATUS.

STATUS_SCRIPTED 4
Player scripted status. See P_STATUS.
In this status the movement does no tests and checks no keys.
This status is ment to allow users to move the player from the script, or to play static animations.

int PlayerGet( property )
INintpropertyplayer property
OUTintproperty value
Gets the value of the specified player's property.
See P_DISABLE, P_STATUS, P_DELAY, P_LAYER, P_X, P_Y, etc.

PlayerSet( property, value )
INintpropertyplayer property
INintvalueproperty value
Sets the value of the specified player's property.

PlayerMakeBB( x1, y1, x2, y2 )
INrefintx1left
INrefinty1top
INrefintx2right
INrefinty2bottom
Returns in the reference parameters, the values of the player's bounding box corners.
This takes in consideration the position, width and height of the player.
The bound is expressed in view coordinates, relative to the room's top left corner (0,0).

PlayerMakeBBW( x1, y1, x2, y2 )
INrefintx1left
INrefinty1top
INrefintx2right
INrefinty2bottom
Returns in the reference parameters, the values of the player's bounding box corners.
This takes in consideration the position, width and height of the player.
The bound is expressed in world coordinates, relative to the map's top left corner (0,0).



DLG_STYLE 0
Dialog custom style.
Users can interpret this as they want for their dialogs, to customize them.

DLG_X 1
Dialog x coordinate in pixels in screen [0..256)

DLG_Y 2
Dialog y coordinate in pixels in screen [0..192)

DLG_W 3
Dialog width in pixels.

DLG_H 4
Dialog height in pixels

DLG_COLOR 5
Dialog custom color, interpreted by the user when the dialog is painted.
In the default template this is used to as border color.

DLG_FONT 6
Dialog custom font, interpreted by the user when the dialog is painted.
In the default template this is used to paint and measure the dialog's text.

DLG_USER 8
Dialog user data, used to store specific information on each dialog, like border tile, font tile, etc.
Up to DLG_MAX (8 properties).

DLG_MAX 16
Dummy, representing the total number of dialog properties.

DlgPush( )
Creates a new dialog on the top of the dialogs stack.

DlgPop( )
Destroys the top dialog from the dialogs stack.

DlgPopAll( )
Destroys all dialogs from the dialogs stack.

int DlgCount( )
OUTintnumber of dialogs
Returns the current number of dialogs in the dialogs stack.

int DlgGet( idx, property )
INintidxdialog index in the dialog stack, top is last.
INintpropertydialog property
OUTintvalue
Gets the value of the specified dialog property.

DlgSet( idx, proprety, value )
INintidxdialog index in the dialog stack, top is last.
INintpropretydialog property
INintvalueproperty value
Sets the value of the specified dialog property.

str DlgGetText( idx )
INintidxdialog index in the dialog stack, top is last.
OUTstrdialog text
Gets the text of the specified dialog.

DlgSetText( idx, text )
INintidxdialog index in the dialog stack, top is last.
INstrtextdialog text
Sets the text of the specified dialog.



SOUND_VOICES 16
Maximum number of voices available for sound samples.

int SampleLoad( path, group=0 )
INstrpathpath to load sound samples form
[IN]intgroup=0resource group
OUTint1=success, 0=errors

SampleUnload( group=0 )
[IN]intgroup=0resource group
Unloads all sample sounds from memory.
The group can be used to unload only some of the loaded resources.

int SamplePlay( id, loop=0 )
INintidsample id
[IN]intloop=0if the sample is to be looped, until stopped by the user
OUTintvoice index or -1 if sample could not be played.
Plays the specified sample.
If no sample is found with the specified id, or all voices are already playing, -1 is returned.
Also, if the maximum number of instances set for the sample, are all playing, -1 is returned.

int SamplePlaying( voiceidx )
INintvoiceidxvoice index [0..SOUND_VOICES-1]
OUTintsample id or -1 if voice is free
Returns the id of the sample playing on the specified voice, or -1 if the voice is not playing.

SampleStop( voiceidx )
INintvoiceidxvoice index [0..SOUND_VOICES-1]
Stops a voice if it's playing, making it available.

SampleStopAll( )
Stops all voices.

SampleVolume( percent )
INintpercentvolume percent [0..100]
Sets the samples volume, 0=silent, 100=loud.



int MusicLoad( path, group=0 )
INstrpathpath to load musics form
[IN]intgroup=0resource group
OUTint1=success, 0=errors

MusicUnload( group=0 )
[IN]intgroup=0resource group
Unloads all musics from memory.
The group can be used to unload only some of the loaded resources.

MusicFade( fadeout, fadein )
INintfadeoutfade out interval in seconds
INintfadeinfade in interval in seconds
Sets fade options.
When a new music is played, the old one is stopped during the specified fade out interval.
The volume of the new music is fading in, during the specified fades in interval.

int MusicPlay( id, position=0 )
INintidmusic id or -1
[IN]intposition=0starting position in miliseconds
OUTint0=success, -1=failed
Plays a music, from a specified position.
Even if fade out option is set, after this call, this music is considered curently playing.
Call with the id=-1 if you want to stop the current music with the fade out option, without starting a new one.
See also MusicFade.

int MusicPlaying( )
OUTintmusic id
Returns the id of the currently playing music.
See also MusicPlay().

int MusicPosition( )
OUTintposition
Returns the position of the current playing music.

MusicStop( )
Immediately stops the curent playing song, without fadeing options.

MusicVolume( percent )
INintpercentvolume percent [0..100]
Sets the music volume, 0=silent, 100=loud.



SHADER_OPAQUE 0
Opaque shader ignores alpha channel, painting non-transparent tiles.

SHADER_BLEND 1
Blending shader uses alpha channel to blend transparent tiles.

SHADER_ADD 2
Additive shader adds tile's colors to the colors of the screen.
Usefull for light effects. Black (0) leaves screen unchanged.

SHADER_MOD 3
Modulative shader multiply tile's colors with the colors of the screen.
Usefull for shadow effects. White (255) leaves screen unchanged.

SHADER_MOD2 4
Modulative 2 shader multiply tile's colors with the colors of the screen in a special way.
Usefull for adding details or decals. Half gray (128) leaves screen unchanged.

HudDrawTile( tileid, x, y, w, h, mapx, mapy, mapw, maph, flip, frame )
INinttileidtile id
INintxhorizontal coordinate in pixels
INintyvertical coordinate in pixels
INintwwidth
INinthheight
INintmapxmapping x position in tile
INintmapymapping y position in tile
INintmapwmapping width in tile
INintmaphmapping height in tile
INintflipflip options ob bits
INintframeframe for animated tiles
Draws a tile in a rectangle on the screen (256x192) with specified tile mapping.
Call it ONLY inside draw handler (HandlerDrawHud)!

HudDrawText( tileid, x, y, w, h, text, align )
INinttileidfont tile id
INintxtext area x position in pixels
INintytext area y position in pixels
INintwtext area width
INinthtext area height
INstrtexttext to be displayed
[IN]intalignalign options -1=left, 0=center
Draws text in a rectangle on the screen (256x192) with specified font tile.
The text is displayed using the font format set through the HudFont function.
The text accepts special commands like:
{a:l}, {a:c}, {a:r} to change align mode to left, center or right
{c:ff0080} to change text color
{f:0}, {f:1} to set flashing color off or on
{t:10 16 18} to draw a tile with the id=10 at the 16,18 coordinates in the text area.
Call it ONLY inside draw handler (HandlerDrawHud)!
See HudFont()

int HudGetTextWidth( text )
INstrtexttext to measure
OUTinthorizontal size of the text, in pixels
Returns the width of the text in pixels, considering '/n' line separators and ignoring special commands.
The text is measured using the font format set through the HudFont function.
This is usefull to find the right size for the dialog that is about to show this text.
See HudFont()

int HudGetTextHeight( text )
INstrtexttext to measure
OUTintveritcal size of text, in pixels

int HudGetTextRows( text )
INstrtexttext to measure
OUTinthorizontal size of the text, in characters
Returns the number of columns of the text, considering '/n' line separators and ignoring special commands.

int HudGetTextColumns( text )
INstrtexttext to measure
OUTintveritcal size of text, in characters

HudClipping( x, y, w, h )
INintxhorizontal coordinate in pixels
INintyvertical coordinate in pixels
INintwwidth
INinthheight
Sets a clipping rectangular area to cut any outside painting.

HudFont( fontid )
INintfontidthe font format used in text functions
Sets the current font format used in hud text functions.
Consider that the font tile must match the font format.
So it's a good idea to match their ids too, even if this is not a requirement.
See FontLoad(), FontUnload(), HudDrawText(), HudGetTextWidth(), HudGetTextHeight()

HudShader( shader )
INintshaderthe shader used to paint
Sets the current shader used in hud functions.
See SHADER_OPAQUE, SHADER_BLEND, SHADER_ADD, SHADER_MOD, SHADER_MOD2

HudColor( color )
INintcolorhud color
Sets the current color used in hud functions.



int FontLoad( path, group=0 )
INstrpathpath to load fonts form
[IN]intgroup=0resource group
OUTint1=success, 0=errors

FontUnload( group=0 )
[IN]intgroup=0resource group
Unloads all fonts from memory.
The group can be used to unload only some of the loaded resources.



KEY_LEFT 0
Left key index.

KEY_RIGHT 1
Right key index.

KEY_UP 2
Up key index.

KEY_DOWN 3
Down key index.

KEY_JUMP 4
Jump key index.

KEY_ACTION 5
Action key index.

KEY_MENU 6
Menu key index.

int KeyboardRead( )
OUTintkeycode
Reads a key code, if any was pressed.
Can be used for input texts.

int KeyboardStatus( keycode )
INintkeycodekey scan code
OUTint0=not pressed, 1=pressed
Gets status of a key.

int KeyboardCodeToChar( keycode )
INintkeycodekey scan code
OUTintascii char, or 0 if not available
Gets key ascii character from the key scan code (if available)

int KeyboardCharToCode( char )
INintcharascii character
OUTintkey scan code
Gets key scan code from the key ascii character (if available)

int JoystickStatus( button [0..19] )
INintbutton [0..19]
OUTintstatus 0=not pressed, 1=pressed
Test for joystick buttons
The hat switch's four directional buttons are 16,17,18,19.
The game should consider the player's buttons mapping in dizzy.ini

gsJoystickAxe( )



DebugData( slot, data )
INintslotdebug slot
INstrdatatext data
Writes a text in a console data slot. Used for debug.

DebugCool( cool )
[IN]intcool0=cool off, 1=cool on
Sets engine cool flag. Use 0 to view real fps and 1 to cool the cpu.
If the parameter is not specified, the function returns the current state.

DebugLog( log )
INintlog0=log off, 1=log on
Sets engine log flag. Use 0 to stop displaying messages and 1 to let them be displayed.

DebugDev( dev )
[IN]intdev0=dev off, 1=dev on
Sets engine dev flag. Use 1 to enable developer mode.
If the parameter is not specified, the function returns the current state.

str DebugCallstack( )
OUTstrcallstack
Returns a string containing the latent virtual machine's execution callstack.
This info is also displayed in the console.