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

Finds the first pickable object that the player stands in front of.
Called by Action(), see PlayerTouchObject().

Finds the first action object that the player stands in front of.
Called by Action(), see PlayerTouchObject().

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

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

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

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

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

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

speed value for class waypoint, used in AIUpdateTrain()

flip value for class waypoint, used in AIUpdateTrain()

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

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

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)

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

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

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 !

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

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

player's air critical level

player's stun critical level

default hurt level for "hurt" materials

default wind power

player's jump power (for default movement)

player's walk step (for default movement)

fix jumper power

pro jumper power limit

flip x (bit value)

flip y (bit value)

flip rotate (bit value)

default player's idle tile id

default player's walk tile id

player's emotion offset for no air1

player's emotion offset for no air2

player's emotion offset for no air3

void

water (void); player can drawn in water

hurt (void); player gets hurt

kill (void); player gets killed

clouds (medium); player sinks on clouds

stairs (medium); player stands on

winds (medium); player is pushed up

ground, walls (hard); blocks the player

jumper fix (hard)

jumper progressive (hard)

default

those objects can be used with action

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

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

those objects can be picked up in the inventory

those objects can be collected as coins

those objects can eaten to grow the life

those objects gives a credit when picked up.

used for dummy waypoints (no automation implemented)

dialog default border color

shake frames counter

rumble frames counter

if cover screen is painted

store music for player respawn

store music pos for player respawn

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

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

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

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

Close one dialog, same as DlgPop().

Close all dialogs, same as DlgPopAll().

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

Set position of the topmost dialog

Set size of the topmost dialog

Set border color of the topmost dialog

Set the font of the topmost dialog, used in painting dialog texts

Set text content of the topmost dialog

Get width of the topmost dialog

Get height of the topmost dialog

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

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.

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

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

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.

Opens a simple message dialog and runs it, waiting for MENU or ACTION key to be pressed.

Opens a simple question yes/no dialog.
Uses DialogQuestion() function for dialog creation.

Dialog creation function used by OpenDialogQuestion().

Loads a game and display the result message.
Loads static brushes with IDs. See LoadStaticBrushes().
Restores old music and handle objects present.
Latent function.

Saves a game and display the result message.
Saves static brushes with IDs. See SaveStaticBrushes().
Stores current music.
Latent function.

Loads a brush from a file.

Saves a brush into a file.

Loads brushes from the brushes ids file exported from editor in the dizzy.brs file.
Called from the LoadGame() function.

Saves brushes from the brushes ids file exported from editor in the dizzy.brs file.
Called from the SaveGame() function.

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" );

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");

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.

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 .

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;

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;

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's author name (for the credits dialog)

game's title (for the window title)

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

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

max number of credits

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

max number of inventory items ( max 10 items )

minimum number of seconds to wait on the loading page

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

id of the default font

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

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

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

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

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

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

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

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

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

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

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)

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

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.

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.

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 !

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 !

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.

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.

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.

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.

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.

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.

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.

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

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.

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 !

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.

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.

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.

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.

Returns the current number of items from the inventory.

Adds an item to the inventory, if possible.

Removes an item from the inventory.

Removes all items from the inventory.

Returns the coresponding inventory position for an item.

Returns the index of an item object placed on a specified inventory slot.

Tells if an item, specified by it's object's id, is currently prezent in the inventory or not.

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.

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

Dialog creation function used by OpenDialogMainMenu().

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

Dialog creation function used by OpenDialogGameMenu().

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

Dialog creation function used by OpenDialogOptions().

Opens the Controls dialog.

Opens the Credits dialog with the authors information.

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

Dialog creation function used by OpenDialogFiles().

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

Dialog creation function used by OpenDialogFinish().

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.

Dialog creation function used by OpenDialogInventory().

Stores x, y, and colors, for use with the MessageNext() function.
This does not closes the dialog. Needs DialogPop(), DialogPopAll(), or usually MessagePop().

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

Closes all opened messages, same as DialogPopAll().

quick call for Message() with story teller color settings

quick call for Message() with player color settings

quick call for Message() with other characters color settings

move step x

move step y; used in adjustments

move step y; used in jumps and falls

collision box width

collision box height

Custom Move - main update function

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

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

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

collision inside box bottom will rise dizzy up with maximum CM_STEPY

return material if jumper or -1 if not

return clamped and animated frame

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.

Tests if the specified material is found inside player's bounding box.

Tests if the material is found just under player's bounding box.

Tests if player's position is considered safe for respawning or dropping objects.

Tests if player's position is considered stable for respawning or dropping objects.

Tests if player touches a rectangle (bounding boxes intersect)

Tests if player touches an object (bounding boxes intersect)

Tests if player touches an object that's visible in the current room (bounding boxes intersect)

Set player in idle state

Set player in walk state

Set player in walk state

Set player in fall state

Set player in fall state

Set player in scripted state

Set player's position

Player plays all frames from the tile's animation.
Latent function.

Players plays all the frames specified in the table.
Optional value for breaking the animation if player dies during it.
Latent function.

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

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

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

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

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

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

Change player's emotion and apply frame

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

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)

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

Loads rooms names saved from the editor
Each line in the file has the folowing format: ROOMX; ROOMY; ROOMNAME

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

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)

Loads room numeric properties from the saved game
Called from the LoadGame() function.

Saves room numeric properties in the saved game
Called from the SaveGame() function.

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.

Waits a specified number of game cycles.
Latent function. Call only from latent functions.

Waits a specified number of game cycles and clear input keys.
Latent function. Call only from latent functions.

Waits a specified number of seconds.
Latent function. Call only from latent functions.

Tests if a key is pressed down.
KEY_LEFT, KEY_RIGHT, KEY_UP, KEY_DOWN, KEY_JUMP, KEY_ACTION, KEY_MENU

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

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

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

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

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

Test if it's time for an object's update, once each delay frames.
Usually delay is object's O_DELAY.

Pauses or unpauses the game.

Tests if object is pickable, by class.

Tests if object is action, by class.

Object plays all frames from the current tile's animation.

Object plays all the frames specified in the table from the current tile.
Waits object's O_DELAY game cycles between each frame.

Request rumble for a number of frames

Request shake for a number of frames

Set shake offsets using sine courves

Updates shake and rumble - call in GameUpdate handler

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

Restores and play music, used when player gets respawned