Global functions (Event Handlers)

In your global script file, some functions will have been automatically added when you created your game. These are global event handlers, and these functions are called when particular events occur. There are also some optional event handlers, which you can add if you would like specific additional events to be processed.

dialog_request

dialog_request (int parameter)

Called when a dialog script line "run-script" is processed. PARAMETER is the value of the number following the "run-script" on that line of the dialog script.


game_start

game_start ()

Called at the start of the game, before the first room is loaded. You would typically use this to set up the initial positions of characters, and to modify initial visibility of GUIs.

Note: When this function is called it is too early to run animations or do anything else which relies on a room being loaded


interface_click

(This function is now obsolete)

interface_click (int interface, int button)

Called when the player clicks on a button on a GUI which has its action set as "Run script". INTERFACE is the number of the GUI which they clicked on. BUTTON is the object number of the button within this GUI.


on_event

on_event (EventType event, int data)

Called whenever certain game events occur. The value of DATA depends on which event has occurred. The possible values of event are:

eEventEnterRoomBeforeFadein
      called just before the room's 'Player Enters Room' event occurs
      DATA = new room number
eEventLeaveRoom
      called just after the room's 'Player Leaves Room' event occurs
      DATA = room number they are leaving
eEventGotScore
      called whenever the player's score changes
      DATA = number of points they've received
eEventGUIMouseDown
      called when a mouse button is pressed down over a GUI
      DATA = GUI number
eEventGUIMouseUp
      called when a mouse button is released over a GUI
      DATA = GUI number
eEventAddInventory
      called when the player has just added an inventory item
      DATA = inventory item number that was added
eEventLoseInventory
      called when the player has just lost an inventory item
      DATA = inventory item number that was lost
eEventRestoreGame
      called after a saved game has been restored
      DATA = save slot number

on_key_press

on_key_press (eKeyCode keycode)

Called whenever a key is pressed on the keyboard. KEYCODE holds the ASCII value of the key. A list of these values is available here.

The on_key_press function can also be defined in individual room scripts. This allows the room script to intercept a key-press first, and then decide whether to pass it on to the global script or not. See the ClaimEvent function for more details.


on_mouse_click

on_mouse_click (MouseButton button)

Called when the player clicks a mouse button. BUTTON is either eMouseLeft, eMouseRight, or eMouseMiddle, depending on which button was clicked. The mouse.x and mouse.y global variables contain the mouse's position.

If 'Handle inventory clicks in script' is enabled in the game options, this function can also be called with eMouseLeftInv, eMouseMiddleInv or eMouseRightInv, which indicate a left, middle or right click on an inventory item, respectively.

If 'Enable mouse wheel support' is enabled, this function can also be called with eMouseWheelNorth or eMouseWheelSouth, which indicate the user moving the mouse wheel north or south, respectively.

The on_mouse_click function can also be defined in individual room scripts. This allows the room script to intercept a mouse-click first, and then decide whether to pass it on to the global script or not. See the ClaimEvent function for more details.


repeatedly_execute

repeatedly_execute()

Called every game cycle (normally 40 times per second). Additional information is available here.


repeatedly_execute_always

repeatedly_execute_always()

Called every game cycle, even when a blocking routine (e.g speech or cutscene) is in progress. You cannot call any blocking functions from this event handler. repeatedly_execute_always is called before the game entities (characters, rooms, etc) get updated. Additional information is available here.


late_repeatedly_execute_always

late_repeatedly_execute_always()

Called every game cycle, even when a blocking routine (e.g. speech or cutscene) is in progress. You cannot call any blocking functions from this event handler. late_repeatedly_execute_always is called after the game entities (characters, rooms, etc) have been updated, but before the game screen is redrawn.


unhandled_event

unhandled_event (int what, int type)

Called when an event occurs, but no corresponding event handler has been configured. This is typically used to display a default "I can't do that" type response in-order to avoid having to add unique messages for all in-game interactions. The values of WHAT and TYPE tell you what the player did. The possible values are listed below:

WHAT TYPE Description
1 1 Look at hotspot
1 2 Interact with hotspot
1 3 Use inventory on hotspot
1 4 Talk to hotspot
1 7 Pick up hotspot
1 8 Cursor Mode 8 on hotspot
1 9 Cursor Mode 9 on hotspot
2 0 Look at object
2 1 Interact with object
2 2 Talk to object
2 3 Use inventory on object
2 5 Pick up object
2 6 Cursor Mode 8 on object
2 7 Cursor Mode 9 on object
3 0 Look at character
3 1 Interact with character
3 2 Speak to character
3 3 Use inventory on character
3 5 Pick up character
3 6 Cursor Mode 8 on character
3 7 Cursor Mode 9 on character
4 1 Look at nothing (i.e. no hotspot)
4 2 Interact with nothing
4 3 Use inventory with nothing
4 4 Talk to nothing
5 0 Look at inventory
5 1 Interact with inventory (currently not possible)
5 2 Speak to inventory
5 3 Use an inventory item on another
5 4 Other click on inventory

Note: the "Character stands on hotspot" event does not trigger this function, nor will it be triggered if there is an "Any click" event handler defined, nor if the player clicks on nothing (hotspot 0)


on_call

on_call (int value)

This callback can only be declared on Room Script.

It's called after the function CallRoomScript(value) is executed, but not immediately. You can read an arbitrary integer value passed from CallRoomScript. Additional information is available here.