23. TEMPLATE REFERENCE
defines and functions






Action,
FindPickupObject,
FindActionObject,
PickupObject,
DoPickupObject,
UseObject,
DropObject,
DoDropObject,
ActionObject


O_WAYPOINTSPEED,
O_WAYPOINTFLIP,
O_BUBBLESPEED,
O_BUBBLETIME,
AIUpdateTrain,
AIUpdateChainLink,
AIUpdateSpider,
AIUpdateBubbles


GAME_SCRW,
GAME_SCRH,
AIR_LEVEL,
STUN_LEVEL,
DIZ_HURT,
WINDPOW,
DIZ_POW,
DIZ_STEP,
JUMPFIXPOW,
JUMPPROPOW,
FLIPX,
FLIPY,
FLIPR,
PTILE_IDLE,
PTILE_WALK,
PTILE_UP,
PTILE_JUMP,
PTILE_STUN,
PTILE_DEAD,
PTILE_NOAIR1,
PTILE_NOAIR2,
PTILE_NOAIR3,
PTILE_EAT,
PTILE_SWIM,
PTILE_SWIMUP,
PTILE_SWIMJUMP,
PTILE_DRAWN,
EMOTION_NOAIR1,
EMOTION_NOAIR2,
EMOTION_NOAIR3,
MAT_AIR,
MAT_WATER,
MAT_HURT,
MAT_KILL,
MAT_CLOUD,
MAT_CLIMB,
MAT_WIND,
MAT_BLOCK,
MAT_JUMPFIX,
MAT_JUMPPRO,
CLASS_NONE,
CLASS_ACTION,
CLASS_HURT,
CLASS_KILL,
CLASS_ITEM,
CLASS_COIN,
CLASS_FOOD,
CLASS_LIFE,
CLASS_WAYPOINT,
COLOR_BLACK,
COLOR_BLUE,
COLOR_RED,
COLOR_MAGENTA,
COLOR_GREEN,
COLOR_CYAN,
COLOR_YELLOW,
COLOR_WHITE,
COLOR_DIALOG,
G_SHAKE,
G_RUMBLE,
G_COVER,
G_MUSICSAFE,
G_MUSICPOSSAFE,
G_GAME,
G_STATIC,
G_RESTART,


DialogPush,
DialogPop,
DialogPopAll,
DialogCount,
DialogSetPos,
DialogSetSize,
DialogSetColor,
DialogSetFont,
DialogSetText,
DialogTextW,
DialogTextH,
DialogDraw,
DialogFitAt,
DialogFitCenter,
DialogRun,
RunDialogSelect,
OpenDialogMessage,
OpenDialogQuestion,
DialogQuestion




LoadGame,
SaveGame,
LoadBrush,
SaveBrush,
LoadStaticBrushes,
SaveStaticBrushes


RoomsSetNames,
ObjectsSetNames,
RoomSetCustomText,
PlayerDeathMessage,
SaveUserData,
LoadUserData,
BeginNewGame


GAME_AUTHOR,
GAME_TITLE,
GAME_WEBSITE,
GAME_ID,
MAXCREDITS,
MAXCOINS,
MAXINVENTORY,
LOADINGTIME,
MUSIC_DEFAULT,
FONT_DEFAULT,
MAINMENU_ATTRACT,
PLAYER_MAINMENUX,
PLAYER_MAINMENUY,
PLAYER_LAYER,
PLAYER_BEGINX,
PLAYER_BEGINY,
PLAYER_BUBBLES,
SUPPORT_WATERPLAY,
SUPPORT_JUMPUP,
ID_SCUBA,
ID_FLIPPERS,
ID_BUBBLES,


HandlerGameInit,
HandlerGameStart,
HandlerGameUpdate,
HandlerGameAfterUpdate,
HandlerRoomOpen,
HandlerRoomClose,
HandlerRoomOut,
HandlerCollision,
HandlerFall,
HandlerJump,
HandlerPlayerUpdate,
HandlerAction,
HandlerMenu,
HandlerDrawHud,
HandlerMusicLoop,
HandlerDebug,
HandlerReloadMap,
HandlerReloadScript


InventoryCount,
InventoryAdd,
InventorySub,
InventoryClear,
InventoryFind,
InventoryGet,
InventoryHasItem


MainMenu,
OpenDialogMainMenu,
DialogMainMenu,
OpenDialogGameMenu,
DialogGameMenu,
OpenDialogOptions,
DialogOptions,
OpenDialogControls,
OpenDialogCredits,
OpenDialogFiles,
DialogFiles,
OpenDialogFinish,
DialogFinish,
OpenDialogInventory,
DialogInventory


Message,
MessageNext,
MessagePop,
Message0,
Message1,
Message2


CM_STEPX,
CM_STEPY,
CM_STEPYMAX,
CM_BOXW,
CM_BOXH,
MIN,
CM_Update,
CM_EnterIdle,
CM_EnterWalk,
CM_EnterJump,
CM_EnterFall,
CM_EnterRoll,
CM_EnterJumper,
CM_EnterSpin,
CM_EnterKeyState,
CM_UpdateIdle,
CM_UpdateWalk,
CM_UpdateJump,
CM_UpdateFall,
CM_UpdateScripted,
CM_CheckWalkX,
CM_CheckJumpX,
CM_CheckJumpY,
CM_CheckFallX,
CM_CheckFallY,
CM_CheckCollision,
CM_CheckJumper,
CM_CheckCollidersSnap,
CM_ComputeFrame


IsPlayerUpdate,
IsMaterialInsidePlayer,
IsMaterialUnderPlayer,
IsPlayerSafe,
IsPlayerStable,
PlayerTouchRect,
PlayerTouchObject,
PlayerTouchObjectInRoom,
PlayerEnterIdle,
PlayerEnterWalk,
PlayerEnterJump,
PlayerEnterFall,
PlayerEnterSpin,
PlayerEnterScripted,
PlayerSetPos,
PlayerPlayAnim,
PlayerPlayAnimFrames,
PlayerPlayStun,
PlayerPlayDead,
PlayerPlayDeadWater,
PlayerLoseLife,
PlayerRespawn,
PlayerHurt,
PlayerEmotion,
PlayerUpdateWaterPlay,
PlayerCanSwim,
PlayerSwim


ROOM_NAMESFILE,
ROOM_PROPSFILE,
ROOM_TEXTSFILE,
RoomsLoadNames,
RoomsLoadTexts,
RoomsLoadProps,
LoadRoomProperties,
SaveRoomProperties


MUSIC_NONE,
MUSIC_A,
MUSIC_B,
MUSIC_C,
FX_SUCCESS,
FX_STUN,
FX_DEATH,
FX_RESPAWN,
FX_COIN,
FX_HURT,
FX_JUMP,
FX_BEEP1,
FX_BEEP2,


GameStartLoad


WaitFrames,
WaitFramesClearKeys,
WaitTime,
GetKey,
GetKeyHit,
SetKey,
SetKeyHit,
ClearKeys,
UseUpForJump,
IsUpdate,
GamePause,
ObjIsPickup,
ObjIsAction,
ObjPlayAnim,
ObjPlayAnimFrames,
DoRumble,
DoShake,
ApplyShake,
UpdateShakeAndRumble,
MusicStore,
MusicRestore




Action( )
This is the main latent action function requested by the action handler.
First it tries "pickup" on a pickable object, if found.
If not, it tries "action" on an action object, if found.
If not, it opens the inventory and let you use/drop an item.
Called by HandlerAction(), see PickupObject(), ActionObject(), UseObject().

int FindPickupObject( )
OUTintobject index or -1 if not found
Finds the first pickable object that the player stands in front of.
Called by Action(), see PlayerTouchObject().

int FindActionObject( )
OUTintobject index or -1 if not found
Finds the first action object that the player stands in front of.
Called by Action(), see PlayerTouchObject().

PickupObject( idx )
INintidxobject index
Picks up an object considering the object class (item, coin, food, life).
If available, it calls the pickup callback "PickupObject_ID" insteed.
Called by Action(), see DoPickupObject().

DoPickupObject( idx )
INintidxobject index
Does pick up an object considering the object class (item, coin, food, life),
without calling the pickup callback, so it may be used from it.
Called by PickupObject().

UseObject( idx )
INintidxobject index
Use an object from the inventory.
If player stands in front of an action object (action class), the "UseObject_ID" callback is called.
If not, the item is simply dropped down.
Called by Action() and ActionObject(), see DropObject().

DropObject( idx )
INintidxobject index
Drops an object from the inventory.
The object is placed on the player's current position.
If available, it calls the drop object callback "DropObject_ID" insteed.
Do not call it back, from inside the drop object callback!
Called by UseObject(), see DoDropObject().

DoDropObject( idx )
INintidxobject index
Does drop the object, enableing and placing it on the player's current position,
without calling the drop object callback, so it can be used inside this callback.
Called by DropObject().

ActionObject( idx )
INintidxobject index
Action performed on the object the player stands in front of.
If available, it calls the action callback "ActionObject_ID".
If not, opens inventory and allows use /drop of the selected item.
Called by Action(), see UseObject().



O_WAYPOINTSPEED 32
speed value for class waypoint, used in AIUpdateTrain()

O_WAYPOINTFLIP 33
flip value for class waypoint, used in AIUpdateTrain()

O_BUBBLESPEED 32
bubble moving speed, set at spawn time, used in AIUpdateBubbles()

O_BUBBLETIME 33
bubble life time, growing each cycle, used in AIUpdateBubbles()

AIUpdateTrain( idx )
INintidxobject index
Train AI
Those are objects that move from a waypoint to another.
Can be used for elevators, moving platforms or a walking creature, like a rat.
Uses a target waypoint from where it takes speed (O_WAYPOINTSPEED) and flip (O_WAYPOINTFLIP).
When target waypoint is reached, it gets a new target from the waypoint.
O_TARGET = id of the current target waypoint
O_STATUS = enable state, 1=moves, 0=stays
Waypoint object:
O_USER = speed value (O_WAYPOINTSPEED)
O_USER+1 = flip value (O_WAYPOINTFLIP)

AIUpdateChainLink( idx )
INintidxobject index
ChainLink AI
Updates chain's height, down to the target's y position.
Used for elevator's chains or spiders wires.
O_TARGET = target object's id

AIUpdateSpider( idx )
INintidxobject index
Spider AI
Moves up and down between two positions.
Used for classic Dizzy spiders.
O_USER = upper y value
O_USER+1 = lower y value
O_STATUS = direction 0=up, 1=down

AIUpdateBubbles( id, count, debit, speed, life )
INintidfirst bubble object's id
INintcountmaximum number of bubble objects, with ids starting from id, id+1, id+2, etc
INintdebitthe spawning debit delay factor, higher values means rare spawns, 0 means stopped
INintspeedthe moving speed factor of bubbles (with some random variation)
INintlifethe number of cycles a bubble lives, until respawned (with some random variation)
This is used to manage the air bubbles the player spawns, while in water.
O_DISABLE = if bubble is active or not (default must be disabled)
O_USER+0 = bubble particular speed value (O_BUBBLESPEED)
O_USER+1 = bubble life timer (O_BUBBLETIME)
User can call it from player update.
Make sure all bubbles are disabled by default !



GAME_SCRW 256
screen's width (fixed by engine to Z80 screen size)

GAME_SCRH 192
screen's height (fixed by engine to Z80 screen size)

AIR_LEVEL 100
player's air critical level

STUN_LEVEL 20
player's stun critical level

DIZ_HURT 4
default hurt level for "hurt" materials

WINDPOW 2
default wind power

DIZ_POW 7
player's jump power (for default movement)

DIZ_STEP 4
player's walk step (for default movement)

JUMPFIXPOW 16
fix jumper power

JUMPPROPOW 16
pro jumper power limit

FLIPX 1
flip x (bit value)

FLIPY 2
flip y (bit value)

FLIPR 4
flip rotate (bit value)

PTILE_IDLE 10
default player's idle tile id

PTILE_WALK 11
default player's walk tile id

PTILE_UP 12

PTILE_JUMP 13

PTILE_STUN 14

PTILE_DEAD 15

PTILE_NOAIR1 16

PTILE_NOAIR2 17

PTILE_NOAIR3 18

PTILE_EAT 19

PTILE_SWIM 20

PTILE_SWIMUP 21

PTILE_SWIMJUMP 22

PTILE_DRAWN 23

EMOTION_NOAIR1 6
player's emotion offset for no air1

EMOTION_NOAIR2 7
player's emotion offset for no air2

EMOTION_NOAIR3 8
player's emotion offset for no air3

MAT_AIR 0
void

MAT_WATER 1
water (void); player can drawn in water

MAT_HURT 2
hurt (void); player gets hurt

MAT_KILL 3
kill (void); player gets killed

MAT_CLOUD 4
clouds (medium); player sinks on clouds

MAT_CLIMB 5
stairs (medium); player stands on

MAT_WIND 6
winds (medium); player is pushed up

MAT_BLOCK 7
ground, walls (hard); blocks the player

MAT_JUMPFIX 8
jumper fix (hard)

MAT_JUMPPRO 9
jumper progressive (hard)

CLASS_NONE 0
default

CLASS_ACTION 1
those objects can be used with action

CLASS_HURT 2
used for objects that should hurt you (no automation implemented)

CLASS_KILL 3
used for objects that should kill you (no automation implemented)

CLASS_ITEM 4
those objects can be picked up in the inventory

CLASS_COIN 5
those objects can be collected as coins

CLASS_FOOD 6
those objects can eaten to grow the life

CLASS_LIFE 7
those objects gives a credit when picked up.

CLASS_WAYPOINT 8
used for dummy waypoints (no automation implemented)

COLOR_BLACK 0xff000000

COLOR_BLUE 0xff0000ff

COLOR_RED 0xffff0000

COLOR_MAGENTA 0xffff00ff

COLOR_GREEN 0xff00ff00

COLOR_CYAN 0xff00ffff

COLOR_YELLOW 0xffffff00

COLOR_WHITE 0xffffffff

COLOR_DIALOG 0xff00ff00
dialog default border color

G_SHAKE 64
shake frames counter

G_RUMBLE 65
rumble frames counter

G_COVER 66
if cover screen is painted

G_MUSICSAFE 67
store music for player respawn

G_MUSICPOSSAFE 68
store music pos for player respawn

G_GAME 100
globals representing game logic are recomended to start from this index up to 200 (add them in gamedef.gs)

G_STATIC 240
the rest of the global variables, starting with this one, are not reseted on restart, see HandlerGameStart()

G_RESTART 240
true after first start, false after that, see GameStartLoad()



DialogPush( )
Open one dialog, same as DlgPush(). Also sets the default font.

DialogPop( )
Close one dialog, same as DlgPop().

DialogPopAll( )
Close all dialogs, same as DlgPopAll().

DialogCount( )
Returns the number of opened dialogs, same as DlgCount().

DialogSetPos( x, y )
INintxhorizontal coordinate in pixels
INintyvertical coordinate in pixels
Set position of the topmost dialog

DialogSetSize( w, h )
INintwdialog width in pixels
INinthdialog height in pixels
Set size of the topmost dialog

DialogSetColor( color )
INintcolordialog border color
Set border color of the topmost dialog

DialogSetFont( fontid )
INintfontiddialog font
Set the font of the topmost dialog, used in painting dialog texts

DialogSetText( text )
INstrtextdialog text
Set text content of the topmost dialog

int DialogTextW( )
OUTintdialog width in pixels
Get width of the topmost dialog

int DialogTextH( )
OUTintdialog height in pixels
Get height of the topmost dialog

DialogDraw( idx )
INintidxdialog index
Draw a dialog with border and text.
Should be called only from HandlerDrawHud().
Do NOT abuse it !

DialogFitAt( x, y )
INintxhorizontal coordinate in pixels
INintyverical coordinate in pixels
Sets position of the last dialog.
Auto sets the dialog size to contain all the text.
It prevents the dialog from getting out of the screen, if possible, by adjusting the dialog position.

DialogFitCenter( )
Auto sets position of the last dialog in the center of the screen.
Auto sets the dialog size to contain all the text.

DialogRun( )
Runs a simple dialog, waiting until the MENU key or the ACTION key are pressed.
Latent function.

int RunDialogSelect( fid_dialog, count, default=0, norefuse=0 )
INintfid_dialogid of the dialog function that creates a dialog
INintcounthow many selections are available in the dialog
[IN]intdefault=0default selection when the dialog is opened
[IN]intnorefuse=0if the dialog can be closed without choosing a selection
OUTintselection index or -1 if dialog was refused and nothing was choosed
Runs a multi-selection dialog.
Uses LEFT and RIGHT (or UP and DOWN) keys to navigate and ACTION key to select.
If norefuse, you can't press MENU key to close without selecting something.
The dialog creation function (fid_dialog) receives the current selection index as a parameter.
Latent function.

OpenDialogMessage( text, color=COLOR_DIALOG )
INstrtextmessage text
[IN]intcolor=COLOR_DIALOGborder color
Opens a simple message dialog and runs it, waiting for MENU or ACTION key to be pressed.

int OpenDialogQuestion( text, default=0 )
INstrtextquestion text
[IN]intdefault=0default selected answer, 0=yes, 1=no
OUTintselected answer, 0=yes, 1=no
Opens a simple question yes/no dialog.
Uses DialogQuestion() function for dialog creation.

DialogQuestion( select )
INintselectcurrent selection index 0=yes, 1=no
Dialog creation function used by OpenDialogQuestion().





int LoadGame( file )
INstrfilefile name
OUTint0=fail, 1=success
Loads a game and display the result message.
Loads static brushes with IDs. See LoadStaticBrushes().
Restores old music and handle objects present.
Latent function.

int SaveGame( file )
INstrfilefile name
OUTint0=fail, 1=success
Saves a game and display the result message.
Saves static brushes with IDs. See SaveStaticBrushes().
Stores current music.
Latent function.

int LoadBrush( file, id )
INintfilefile handler
INintidbrush id
OUTint0=fail, 1=success
Loads a brush from a file.

int SaveBrush( file, id )
INintfilefile handler
INintidbrush id
OUTint0=fail, 1=success
Saves a brush into a file.

int LoadStaticBrushes( file )
INintfilefile handler
OUTint0=fail, 1=success
Loads brushes from the brushes ids file exported from editor in the dizzy.brs file.
Called from the LoadGame() function.

int SaveStaticBrushes( file )
INintfilefile handler
OUTint0=fail, 1=success
Saves brushes from the brushes ids file exported from editor in the dizzy.brs file.
Called from the SaveGame() function.



RoomsSetNames( )
Sets room names (non-latent)
By default it loads them from the dizzy.nam file, using the RoomsLoadNames() function.
You can also set the names for each room, by hand, with RoomSetName().
Ex: RoomSetName( 1,1, "PRESS ACTION TO START" );

ObjectsSetNames( )
Sets names to object items (non-latent)
All items tht you might pick up and view in the inventory, must have names set.
Use the ID you specified for the object in the map editor, to find the object.
See ObjSetName() and ObjFind().
Ex: ObjSetName(ObjFind(100),"BUCKET");

RoomSetCustomText( rx, ry, idx, strref )
INintrxroom x coordinate
INintryroom y coordinate
INintidxroom custom text index (0-3)
INrefstrrefstring reference to the custom text
Sets custom texts for each room (non-latent)
There are 4 custom texts per room, that can be set from the map editor.
They are saved by default in the ROOM_TEXTSFILE file (dizzy.rt)
Each game receives these texts through this callback when the map is loaded
and it can interpret them as it wants, for example to fill custom structures
per each room, like ambient sounds, or any other things.
Only non-empty strings are saved from the editor.
This function uses string reference for speed.

PlayerDeathMessage( death )
INintdeathcause of death
Returns the player death message. Called by PlayerLoseLife().
Declare more death defines in gamedef.gs (like DEATH_INFIRE, or DEATH_BATS)
and set them to hurt and kill objects or just set them in the player's
P_DEATH property, then return specific messages in this callback,
for each cacuse of death .

int SaveUserData( file )
INintfilefile handler
OUTintreturn 0 if something has failed, or 1 if operation was successful
Saves additional user data.
Users can save here the additional data (like global GS9 variables) they might need to place in the saved game file.
Called from SaveGame(). See LoadUserData().
Ex: if(!gs_filewriteint(g_myvariable,file)) return 0;

int LoadUserData( file )
INintfilefile handler
OUTintreturn 0 if something has failed, or 1 if operation was successful
Load additional user data.
Users can load here the additional data (like global GS9 variables) they saved before.
They can also set various things, that depends on the just loaded data.
For example, since the room's or object's names are not stored in the saved game,
if such a name is changed as the result of a solved puzzle, when the game is loaded,
it must be changed again, accordingly to the status of the puzzle.
Called from LoadGame(). See SaveUserData().
Ex: if(!gs_filereadint(&g_myvariable, file)) return 0;

BeginNewGame( )
This function is called from MainMenu when a new game begins.
Users must write here whatever they need their game to do, when it's started.
For example here can be placed or called an intro sequence.
In the end, the game must be unpaused, the player must be positioned where he must start, game music can be played, etc.
In the Default Template this also opens a "Hello World!" message.
Latent function.



GAME_AUTHOR "ALEXANDRU SIMION"
game's author name (for the credits dialog)

GAME_TITLE "DizzyAGE Default Template"
game's title (for the window title)

GAME_WEBSITE "http:
www.yolkfolk.com/dizzyage" // game's website (for the final dialog)

GAME_ID "DT080127"
game's id text, used in saved games - change this when you release a new version, to prevent old saved games to be loaded.

MAXCREDITS 3
max number of credits

MAXCOINS 4
max number of coins or diamonds to find (set it to the number of coins you added in your map)

MAXINVENTORY 3
max number of inventory items ( max 10 items )

LOADINGTIME 1
minimum number of seconds to wait on the loading page

MUSIC_DEFAULT 1
id of the default music, for more details see the sound.gs file

FONT_DEFAULT 4
id of the default font

MAINMENU_ATTRACT 0
set to 1 if you want attract mode in MainMenu (check mainmenu.gs)

PLAYER_MAINMENUX 400
set the player's position x in the mainmenu room (attract mode room)

PLAYER_MAINMENUY 246
set the player's position y in the mainmenu room (attract mode room)

PLAYER_LAYER 5
set the player's layer in the game (player gets painted last in it's layer)

PLAYER_BEGINX 640
set the starting positon x of the player in map (when a new game begins)

PLAYER_BEGINY 246
set the starting positon y of the player in map (when a new game begins)

PLAYER_BUBBLES 12
set this to the count of air bubble objects you placed in the map. used in WaterPlay

SUPPORT_WATERPLAY 0
set to 1 if player can enter in water, swim, etc, or to 0 otherwise

SUPPORT_JUMPUP 1
set to 1 if player can jump by pressing the up key, or to 0 otherwise

ID_SCUBA -1
set scuba item's id if you have a scuba in your game and you want to wear it as a costume for WaterPlay

ID_FLIPPERS -1
set flipers item's id if you have any flippers in your game and you want to swim in WaterPlay (or you can set the id of the scuba if no flippers item)

ID_BUBBLES -1
set this to the first valid bubble object. the rest of the PLAYER_BUBBLES bubbles have consecutive ids. used in WaterPlay



HandlerGameInit( )
Handler GameInit
This handler is called only once, when the application starts.
Users should initialize game materials or other things that never change during the game.

HandlerGameStart( )
Handler GameStart
This handler is called each time the game starts (or restarts).
Users should reset game and player variables, stop sounds, and request loading.
By default, the game is paused (G_PAUSE=1) and player has folowing data set:
P_LAYER=7, P_DELAY=3, P_X=0, P_Y=0, P_DISABLE=1, P_LIFE=100, P_CREDUTS=3 etc.
The load sequence can be latent to allow drawing of a loading screen. See GameStartLoad().
Usually the tiles are loaded only once (check the G_RESTART static variable)
Map should be loaded on each restart, to reset objects and brushes properties.
Then an Intro or MainMenu sequence may be opened.

HandlerGameUpdate( )
Handler GameUpdate
This handler is called once every game cycle.
Used to update dynamic objects and other stuff like that.
By default it calls UpdateRoom_RX_RY callback, if found (RX and RY the current room coordinates).
Do NOT abuse this handler !

HandlerGameAfterUpdate( )
Handler GameAfterUpdate
This handler is called once every game cycle after all was updated.
Here, everything is just in place before draw.
Do NOT abuse this handler !

HandlerRoomOpen( )
Handler RoomOpen
This handler is called when a room is opened (set as current).
It is supposed to initialize room data.
By default it calls OpenRoom_RX_RY callback.

HandlerRoomClose( )
Handler RoomClose
This handler is called when a room is closed (a new one is about to be opened).
It is supposed to deinitialize room data.
By default it calls CloseRoom_RX_RY callback.

HandlerRoomOut( )
Handler RoomOut
This handler is called each time the player wants to exit current room.
It is supposed to set player's new position if special behaviour is needed.
By default it calls OutRoom_RX_RY callback.

HandlerCollision( )
Handler Collision
This handler is called when the player collides with an object that requests collision.
All collisions are called just before the player update handler.
Receives the following handler data:
0 = index of the object (not object id)
1 = collision mode (0=exit,1=enter, 2=touch)
It is supposed to handle the collision event depending on the colliding object.
The collision mode values:
0 = just exiting from previous collision
1 = just entering in collision
2 = standing in collision (continuing to collide)
By default it calls CollideObject_ID_MODE callback.

HandlerFall( )
Handler Fall
This handler is called when the player falls down (and stops rolling).
It is supposed to handle the stun event, if stunlevel is high, or other similar stuff.

HandlerJump( )
Handler Jump
This handler is called when the player wants to jump or falls on a jumper material.
Receive in handler data[0] the -1 value, if player pressed jump key,
or the material index, if he felt on a jumping material.
It must send back the jump power, in handler data[1].
If the returned power is greater than 0 then the jump is performed.

HandlerPlayerUpdate( )
Handler PlayerUpdate
This handler is called each player update (depending on P_DELAY value).
It is supposed to customise player behaviour and respond to life lose.
It may check materials inside player's bound or under it and deal with wind, clouds, water, hurting or killing.
It is called before keys are checked and player updated by engine.

HandlerAction( )
Handler Action
This handler is called when the player hits the action button.
It is supposed to handle the action event: interact with characters, pick up items, open inventory, etc.
See Action().

HandlerMenu( )
Handler Menu
This handler is called when the player hits the menu button.
It is supposed to handle the menu event: pause game, open game menu, etc.

HandlerDrawHud( )
Handler DrawHud
This handler is called once every frame cycle to draw hud menus and dialogs.
It is called after all updates are done.
Draw functions are allowed inside it.
Constants are used instead of view or room real sizes, for faster code.
Do NOT abuse this handler !

HandlerMusicLoop( )
Handler Music Loop
This handler is called when the current music reaches it's end and is about to loop from the beginning.
Users can stop the music here, or request another one.
The handler will not be called if the music is already fading out.

HandlerDebug( )
Handler Debug
This handler is called every game cycle if engine was started with developer option.
It can be used by developers to display debug informations in the console data slots.
It is common to edit this during runtime to show some information and reload the script (F5).
You can use DebugData( slot, text ) to display info in the debug slots.

HandlerReloadMap( )
Handler ReloadMap
This handler is called after reloading map in debug purposes.
Developers can reload the map during runtime by pressing F6 (in developer mode).
Reset rooms and objects names, because they are lost on map load.

HandlerReloadScript( )
Handler ReloadScript
This handler is called after reloading script for debug purposes.
Global script variables have been lost, so user may need to restore them.



int InventoryCount( )
OUTintitems count
Returns the current number of items from the inventory.

int InventoryAdd( idx )
INintidxobject index
OUTint0=no slots available in inventory, 1=success
Adds an item to the inventory, if possible.

int InventorySub( idx )
INintidxobject index
OUTint0=object not found in inventory, 1=success
Removes an item from the inventory.

InventoryClear( )
Removes all items from the inventory.

int InventoryFind( idx )
INintidxobject index
OUTintinventory slot or -1 if object not found in inventory
Returns the coresponding inventory position for an item.

int InventoryGet( slot )
INintslotinventory slot position
OUTintobject index or -1 if slot is empty
Returns the index of an item object placed on a specified inventory slot.

int InventoryHasItem( id )
INintiditem object's id
OUTint0=not in inventory, 1=prezent in the inventory
Tells if an item, specified by it's object's id, is currently prezent in the inventory or not.



MainMenu( )
MainMenu
For classic game menu, with cover screen and optional attract mode.
Uses KEY_ACTION to begin game and KEY_MENU to open dialog menu.
Set MAINMENU_ATTRACT to 1 in gamedef.gs if you want to allow attract mode.
For attract mode, your mainmenu room must have some valid content.

OpenDialogMainMenu( )
Opens the MainMenu dialog.
Uses DialogMainMenu() function for dialog creation.
Returns 1 if game must start with intro, 2 if game was loaded, 0 otherwise

DialogMainMenu( select )
INintselectdefault selection
Dialog creation function used by OpenDialogMainMenu().

OpenDialogGameMenu( )
Opens the GameMenu dialog.
Uses DialogGameMenu() function for dialog creation.

DialogGameMenu( select )
INintselectdefault selection
Dialog creation function used by OpenDialogGameMenu().

OpenDialogOptions( )
Opens the Options dialog.
Uses DialogOptions() function for dialog creation.

DialogOptions( select )
INintselectdefault selection
Dialog creation function used by OpenDialogOptions().

OpenDialogControls( )
Opens the Controls dialog.

OpenDialogCredits( )
Opens the Credits dialog with the authors information.

OpenDialogFiles( mode )
INintmode0=load mode, 1=save mode
Opens the game files dialog for load or for save.
Uses DialogFiles() function for dialog creation.
Returns 1 if game was loaded or saved, 0 otherwise

DialogFiles( select )
INintselectdefault selection
Dialog creation function used by OpenDialogFiles().

OpenDialogFinish( )
Opens the Finish dialog
Uses DialogFinish() function for dialog creation.

DialogFinish( select )
INintselectdefault selection
Dialog creation function used by OpenDialogFinish().

int OpenDialogInventory( defaultexit=0 )
[IN]intdefaultexit=0default selection, 0=top item (last picked), 1=exit without dropping
OUTintobject's index, or -1 for exiting without selecting an item
Opens the Inventory dialog and allows the player to choose one item for use (or drop).
Internally, the selection goes from [0 to InventoryCount()] (last selection means return without dropping).
Uses DialogInventory() function for dialog creation.

DialogInventory( select )
INintselectdefault selection
Dialog creation function used by OpenDialogInventory().



Message( x, y, text, colorink, colorborder )
INintxhorizontal coordinate in characters, multiple of 8 pixels [0,30)
INintyvertical coordinate in characters, multiple of 8 pixels [0,17)
INstrtextmessage text
INintcolorinkthe text color
INintcolorborderthe border color
Stores x, y, and colors, for use with the MessageNext() function.
This does not closes the dialog. Needs DialogPop(), DialogPopAll(), or usually MessagePop().

MessageNext( text, stepx=1, stepy=1 )
INstrtextmessage text
[IN]intstepx=1horizontal offset from the last dialog's position, in characters, multiple of 8 pixels
[IN]intstepy=1vertical offset from the last dialog's position, in characters, multiple of 8 pixels
Opens another dialog message in cascade, using the position and the colors of the last message.
This does not closes the dialog. Needs DialogPop(), DialogPopAll(), or usually MessagePop(). See Message().

MessagePop( )
Closes all opened messages, same as DialogPopAll().

Message0( x, y, text )
INintxhorizontal coordinate in characters, multiple of 8 pixels
INintyvertical coordinate in characters, multiple of 8 pixels
INstrtextmessage text
quick call for Message() with story teller color settings

Message1( x, y, text )
INintxhorizontal coordinate in characters, multiple of 8 pixels
INintyvertical coordinate in characters, multiple of 8 pixels
INstrtextmessage text
quick call for Message() with player color settings

Message2( x, y, text, color=COLOR_WHITE )
INintxhorizontal coordinate in characters, multiple of 8 pixels
INintyvertical coordinate in characters, multiple of 8 pixels
INstrtextmessage text
[IN]intcolor=COLOR_WHITEtext color
quick call for Message() with other characters color settings



CM_STEPX 4
move step x

CM_STEPY 4
move step y; used in adjustments

CM_STEPYMAX 7
move step y; used in jumps and falls

CM_BOXW 16
collision box width

CM_BOXH 20
collision box height

MIN( )

CM_Update( )
Custom Move - main update function

CM_EnterIdle( )

CM_EnterWalk( )

CM_EnterJump( )

CM_EnterFall( )

CM_EnterRoll( )

CM_EnterJumper( )

CM_EnterSpin( )

CM_EnterKeyState( )

CM_UpdateIdle( )

CM_UpdateWalk( )

CM_UpdateJump( )

CM_UpdateFall( )

CM_UpdateScripted( )

CM_CheckWalkX( )
check side, only above 8 bottom pixels. if bottom is blocked it will step-up on it

CM_CheckJumpX( )

CM_CheckJumpY( )
check material above the box and see how far can it go

CM_CheckFallX( )

CM_CheckFallY( )
check material under the box and see how far can it go

CM_CheckCollision( )
collision inside box bottom will rise dizzy up with maximum CM_STEPY

CM_CheckJumper( )
return material if jumper or -1 if not

CM_CheckCollidersSnap( )

CM_ComputeFrame( )
return clamped and animated frame



int IsPlayerUpdate( )
OUTint0/1
Tests if player should update this frame.
It can also be used to syncronize the update of other objects with the update of the player.

int IsMaterialInsidePlayer( mat )
INintmatmaterial
OUTint0/1
Tests if the specified material is found inside player's bounding box.

int IsMaterialUnderPlayer( mat )
INintmatmaterial
OUTint0/1
Tests if the material is found just under player's bounding box.

int IsPlayerSafe( )
OUTint0/1
Tests if player's position is considered safe for respawning or dropping objects.

int IsPlayerStable( )
OUTint0/1
Tests if player's position is considered stable for respawning or dropping objects.

int PlayerTouchRect( x1, y1, x2, y2 )
INintx1left
INinty1top
INintx2right
INinty2bottom
OUTint0/1
Tests if player touches a rectangle (bounding boxes intersect)

int PlayerTouchObject( idx )
INintidxobject index
OUTint0/1
Tests if player touches an object (bounding boxes intersect)

int PlayerTouchObjectInRoom( idx )
INintidxobject index
OUTint0/1
Tests if player touches an object that's visible in the current room (bounding boxes intersect)

PlayerEnterIdle( )
Set player in idle state

PlayerEnterWalk( dir )
INintdirdirection -1=left, 1=right
Set player in walk state

PlayerEnterJump( dir, pow )
[IN]intdirdirection -1=left, 0=up
INintpowjump power
Set player in walk state

PlayerEnterFall( )
Set player in fall state

PlayerEnterSpin( dir )
[IN]intdirdirection -1=left, 0=up
Set player in fall state

PlayerEnterScripted( )
Set player in scripted state

PlayerSetPos( x, y )
INintxhorizontal coordinate in world
INintyvertical coordinate in world
Set player's position

PlayerPlayAnim( tile )
INinttiletile id
Player plays all frames from the tile's animation.
Latent function.

PlayerPlayAnimFrames( tile, frames )
INinttiletile id
INtabframeslist of frames to play
Players plays all the frames specified in the table.
Optional value for breaking the animation if player dies during it.
Latent function.

PlayerPlayStun( )
Stun event requested by HandlerFall() when falling from too high.
Latent function.

PlayerPlayDead( )
Dead event requested by HandlerPlayerUpdate when player died on ground.
Latent function.

PlayerPlayDeadWater( )
Dead in water event requested by HandlerPlayerUpdate() when player died in water.
Latent function.

PlayerLoseLife( )
Lose life event.
Test P_DEATH to request the death message from the PlayerDeathMessage callback.
Calls PlayerRespawn_DEATH callback, if available
Latent function.

PlayerRespawn( )
Default player respawn
Can also be called at the beginning of the PlayerRespawn_DEATH respawn callbacks,
since it resets some general properties

PlayerHurt( damage )
INintdamageamount of damage
Player hurt event (non-latent).
Just take some energy and play a hurt sound.

PlayerEmotion( emotion )
INintemotiontile id offest
Change player's emotion and apply frame

PlayerUpdateWaterPlay( )
Update water stuff, called from HandlerPlayerUpdate(), if your game supports WaterPlay (non-latent).

int PlayerCanSwim( )
OUTint0/1
Return 1 if player can swim in water, or 0 if not
Users can test if flippers item is in the inventory (or other options)

PlayerSwim( )
Player swim update, called while in water, from PlayerUpdateWaterPlay() (non-latent).



ROOM_NAMESFILE "Data\\Map\\dizzy.nam"

ROOM_PROPSFILE "Data\\Map\\dizzy.rp"

ROOM_TEXTSFILE "Data\\Map\\dizzy.rt"

RoomsLoadNames( filename )
INstrfilenamefile name, usually dizzy.nam
Loads rooms names saved from the editor
Each line in the file has the folowing format: ROOMX; ROOMY; ROOMNAME

RoomsLoadTexts( filename )
INstrfilenamefile name, usually dizzy.rt
Loads rooms custom texts saved from the editor
Each line in the file has the folowing format: ROOMX; ROOMY; TEXT0; TEXT1; TEXT2; TEXT3
It calls the RoomSetCustomText(rx,ry,idx,refstr), for each non-empty text loaded

RoomsLoadProps( filename )
INstrfilenamefile name, usually dizzy.rp
Loads rooms numeric properties saved from the editor
Each line in the file has the folowing format: ROOMX; ROOMY; INT0; INT1; INT2; ... INT7
The engine exports the max number properties per room in R_MAX (8)

int LoadRoomProperties( file )
INintfilefile handler
OUTint0=fail, 1=success
Loads room numeric properties from the saved game
Called from the LoadGame() function.

int SaveRoomProperties( file )
INintfilefile handler
OUTint0=fail, 1=success
Saves room numeric properties in the saved game
Called from the SaveGame() function.



MUSIC_NONE -1

MUSIC_A 1

MUSIC_B 2

MUSIC_C 3

FX_SUCCESS 1

FX_STUN 2

FX_DEATH 3

FX_RESPAWN 4

FX_COIN 5

FX_HURT 6

FX_JUMP 7

FX_BEEP1 8

FX_BEEP2 9



GameStartLoad( )
Game Start latent function requested by the HandlerGameStart().
Should loads tiles and sound (usually only once) and map (each time).
Also sets rooms and objects names since they may have changed during gameplay.
Then, it calls the MainMenu().
Latent function.



WaitFrames( frames )
INintframesnumber of game cycles to wait
Waits a specified number of game cycles.
Latent function. Call only from latent functions.

WaitFramesClearKeys( frames )
INintframesnumber of game cycles to wait
Waits a specified number of game cycles and clear input keys.
Latent function. Call only from latent functions.

WaitTime( seconds )
INintsecondsnumber of seconds to wait
Waits a specified number of seconds.
Latent function. Call only from latent functions.

int GetKey( key )
INintkeykey index [0..6]
OUTint0/1
Tests if a key is pressed down.
KEY_LEFT, KEY_RIGHT, KEY_UP, KEY_DOWN, KEY_JUMP, KEY_ACTION, KEY_MENU

int GetKeyHit( key )
INintkeykey index [0..6]
OUTint0/1
Tests if a key has just been pressed (hit).
The hit test is compares the key state with the state from the previous game cycle.
KEY_LEFT, KEY_RIGHT, KEY_UP, KEY_DOWN, KEY_JUMP, KEY_ACTION, KEY_MENU

SetKey( key )
INintkeykey index [0..6]
Overwrites a key value.
Can be used to simulate player's input.
KEY_LEFT, KEY_RIGHT, KEY_UP, KEY_DOWN, KEY_JUMP, KEY_ACTION, KEY_MENU

SetKeyHit( key )
INintkeykey index [0..6]
Overwrites a key hit value.
Can be used to simulate player's input.
KEY_LEFT, KEY_RIGHT, KEY_UP, KEY_DOWN, KEY_JUMP, KEY_ACTION, KEY_MENU

ClearKeys( )
Clears key values.
Can be used after closing menus, to prevent them from reopening.

UseUpForJump( )
Call this in GameUpdate handler to allow jumping with the up key.
It sets the 'jump' key if the 'up' key is pressed.

int IsUpdate( delay )
INintdelaynumber of frames
OUTint0/1
Test if it's time for an object's update, once each delay frames.
Usually delay is object's O_DELAY.

GamePause( on )
INinton0=unpause, 1=pause
Pauses or unpauses the game.

int ObjIsPickup( idx )
INintidxobject index
OUTint0/1
Tests if object is pickable, by class.

int ObjIsAction( idx )
INintidxobject index
OUTint0/1
Tests if object is action, by class.

ObjPlayAnim( idx )
INintidxobject index
Object plays all frames from the current tile's animation.

ObjPlayAnimFrames( idx, frames )
INintidxobject index
INtabframeslist with frames to play
Object plays all the frames specified in the table from the current tile.
Waits object's O_DELAY game cycles between each frame.

DoRumble( frames )
INintframesnumber of game cycles to rumble
Request rumble for a number of frames

DoShake( frames )
INintframesnumber of game cycles to shake
Request shake for a number of frames

ApplyShake( magnitudex, frequencyx, magnitudey, frequencyy )
INintmagnitudexshake horizontal magnitude
INintfrequencyxshake horizontal frequency
INintmagnitudeyshake vertical magnitude
INintfrequencyyshake vertical frequency
Set shake offsets using sine courves

UpdateShakeAndRumble( )
Updates shake and rumble - call in GameUpdate handler

MusicStore( )
Stores music id and music position to use when player dies and gets respawned

MusicRestore( )
Restores and play music, used when player gets respawned