In AGS certain types of game objects may have individual events, that is - events that are run for a particular object when something happens to it. These events do not have predefined functions, unlike Global event handlers. Instead each object has an event table, where you may connect a script function to some event.
In the Editor the event tables may be found in the "Events" section of the Properties Window (when clicking the lightning bolt icon).
It's important to note that each event type corresponds to its own function type, which defines function arguments. To give an example, Button's OnClick event demands a function that looks like:
function ButtonName_Click(GUIControl *control, MouseButton button)
If two or more events have same function type, then it is also possible to connect one function to all of them. Similarily, it is possible to connect one function to events from multiple objects. This may be useful in case you prefer to have a generic behavior for them. In such case the function arguments may usually be used to tell which object and which event called the function.
For example, if multiple Buttons are connected to the same Click function, mentioned above, then you may use control argument to refer to the button that was clicked, and button argument to know which mouse button performed the click.
Following is a list of events per game object type.
Enters room before fade-in
function room_Load()
Occurs just after the room is loaded into memory. This event occurs every time the player enters the screen, and it happens BEFORE the screen has faded in, which allows you to change object graphics and do other things to the screen which the player won't notice.
NOTE: This event is ONLY meant for adjusting things such as object and character placement. Do NOT use this event for any sort of automated intro to the room - use the "Enters Room After Fade In" event for that instead.
Enters room after fade-in
function room_AfterFadeIn()
Occurs every time the player enters the room, AFTER the screen has faded-in. Suitable for playing cutscenes.
First time enters room
function room_FirstLoad()
Occurs the first time the player enters the room. This event occurs AFTER the screen has faded in, and right before the "Player enters room (after fade-in)" event.
Leaves room before fade out
function room_Leave()
Occurs when the player leaves the screen, just BEFORE the screen fades out.
Leaves room after fade out
function room_Unload()
Occurs when the player leaves the screen, AFTER the screen has faded-out. This event is suitable for stopping room music and deleting temporary resources, such as Dynamic Sprites.
Repeatedly execute
function room_RepExec()
Occurs repeatedly on every game cycle, at a frequency defined by the game speed (for example if game speed is 40, then this event will occur 40 times per second, about every 25 milliseconds). This event is a equivalent of a global repeatedly_execute callback, as repeatedly_execute is not run in room scripts.
Walk off left edge
function room_LeaveLeft()
occurs when the player character walks off the left Room Edge.
Walk off right edge
function room_LeaveRight()
occurs when the player walks off the right Room Edge.
Walk off bottom edge
function room_LeaveBottom()
occurs when the player character walks off the bottom Room Edge.
Walk off top edge
function room_LeaveTop()
occurs when the player character walks off the top Room Edge.
Look at character
function cChar_Look(Character *theCharacter, CursorMode mode)
Occurs when the player clicks on a character while in the "look" mode.
Interact character
function cChar_Look(Character *theCharacter, CursorMode mode)
Occurs when the player clicks on a character while in the "interact" mode.
Talk to character
function cChar_Talk(Character *theCharacter, CursorMode mode)
Occurs when the player clicks on a character while in the "talk" mode.
Pick up character
function cChar_PickUp(Character *theCharacter, CursorMode mode)
Occurs when the player clicks on a character while in the "pick up" mode.
Use inventory on character
function cChar_UseInv(Character *theCharacter, CursorMode mode)
Occurs when the player uses an inventory object on a character. This
event could be used to allow the player to give items to characters.
You can use the player.ActiveInventory property
to distinguish which item they used.
Usermode1 character
function cChar_Mode8(Character *theCharacter, CursorMode mode)
Occurs when the player clicks on a character while in the "usermode1" mode.
Usermode2 character
function cChar_Mode9(Character *theCharacter, CursorMode mode)
Occurs when the player clicks on a character while in the "usermode2" mode.
Any click on character
function cChar_AnyClick(Character *theCharacter, CursorMode mode)
Occurs when the player clicks on the character in any mode. It's run right after the specific mode event, except if there was a room change command. This allows you to process custom modes like smell, taste, push, pull, and so on.
Look at object
function cObject_Look(Object *theObject, CursorMode mode)
Occurs when the player clicks on a object while in the "look" mode.
Interact object
function cObject_Look(Object *theObject, CursorMode mode)
Occurs when the player clicks on a object while in the "interact" mode.
Talk to object
function cObject_Talk(Object *theObject, CursorMode mode)
Occurs when the player clicks on a object while in the "talk" mode.
Pick up object
function cObject_PickUp(Object *theObject, CursorMode mode)
Occurs when the player clicks on a object while in the "pick up" mode.
Use inventory on object
function cObject_UseInv(Object *theObject, CursorMode mode)
Occurs when the player uses an inventory object on a object.
You can use the player.ActiveInventory property
to distinguish which item they used.
Usermode1 object
function cObject_Mode8(Object *theObject, CursorMode mode)
Occurs when the player clicks on a object while in the "usermode1" mode.
Usermode2 object
function cObject_Mode9(Object *theObject, CursorMode mode)
Occurs when the player clicks on a object while in the "usermode2" mode.
Any click on object
function cObject_AnyClick(Object *theObject, CursorMode mode)
Occurs when the player clicks on the object in any mode. It's run right after the specific mode event, except if there was a room change command. This allows you to process custom modes like smell, taste, push, pull, and so on.
Look at hotspot
function cHotspot_Look(Hotspot *theHotspot, CursorMode mode)
Occurs when the player clicks on a hotspot while in the "look" mode.
Interact hotspot
function cHotspot_Look(Hotspot *theHotspot, CursorMode mode)
Occurs when the player clicks on a hotspot while in the "interact" mode.
Talk to hotspot
function cHotspot_Talk(Hotspot *theHotspot, CursorMode mode)
Occurs when the player clicks on a hotspot while in the "talk" mode.
Pick up hotspot
function cHotspot_PickUp(Hotspot *theHotspot, CursorMode mode)
Occurs when the player clicks on a hotspot while in the "pick up" mode.
Use inventory on hotspot
function cHotspot_UseInv(Hotspot *theHotspot, CursorMode mode)
Occurs when the player uses an inventory hotspot on a hotspot.
You can use the player.ActiveInventory property
to distinguish which item they used.
Usermode1 hotspot
function cHotspot_Mode8(Hotspot *theHotspot, CursorMode mode)
Occurs when the player clicks on a hotspot while in the "usermode1" mode.
Usermode2 hotspot
function cHotspot_Mode9(Hotspot *theHotspot, CursorMode mode)
Occurs when the player clicks on a hotspot while in the "usermode2" mode.
Any click on hotspot
function cHotspot_AnyClick(Hotspot *theHotspot, CursorMode mode)
Occurs when the player clicks on the hotspot in any mode. It's run right after the specific mode event, except if there was a room change command. This allows you to process custom modes like smell, taste, push, pull, and so on.
Stands on hotspot
function hHotspot_WalkOn(Hotspot *theHotspot)
Occurs repeatedly while the player character is standing on the hotspot.
Mouse moves over hotspot
function hHotspot_MouseMove(Hotspot *theHotspot)
Pccurs repeatedly while the mouse cursor is over the hotspot. You can use this to highlight the cursor, and for other various effects.
Look at inventory item
function iInvItem_Look(InventoryItem *theItem, CursorMode mode)
Occurs when the player clicks on the inventory item while in the "look" mode.
Interact inventory item
function iInvItem_Interact(InventoryItem *theItem, CursorMode mode)
Currently, because the Interact mode selects the inventory item, this event can only be triggered by manually calling the InventoryItem.RunInteraction script function (i.e. you have to use the Handle Inv Clicks in Script option).
Talk to inventory item
function iInvItem_Talk(InventoryItem *theItem, CursorMode mode)
Only applies to the LucasArts-style inventory, occurs when the player clicks the Talk icon on the inventory item.
Use inventory on this item
function iInvItem_UseInv(InventoryItem *theItem, CursorMode mode)
Occurs when the player uses another inventory object on this one. You
can use the
player.ActiveInventory property
to distinguish which item they used.
This event allows the player to combine items, and so on. For example, if they had picked up a laptop computer and a battery separately, then you could use this to allow them to insert the battery into the computer.
Other click on inventory
function iInvItem_OtherClick(InventoryItem *theItem, CursorMode mode)
Occurs when the player clicks any other cursor mode (apart from the ones listed above) on the item.
Walks onto region
function region_WalksOff(Region *theRegion)
Occurs when the player moves from another region onto this one. Will also activate on whichever region they start on when they enter the screen.
Walks off region
function region_WalksOnto(Region *theRegion)
Occurs when the player leaves the current region. Does not occur if they go to a different room.
While standing on region
function region_Standing(Region *theRegion)
Occurs repeatedly while the player character stands on this region.