Events

An event is a message sent to a handler of a specified AI. It can be between the AI of 2 objects of the game, between a user and an object, between 2 users (for instance in a multiplayer game), or triggered inside the same AI by another function. Events can also be sent from the AI of an entity to another AI of the same entity, and finally to the same AI on the same entity.

Events can also be sent from a HUD action to any User AI.

Events trigger event handlers. Such event handlers can be:

• custom handlers: Triggered manually by events defined in your scripts.
• predefined handlers: Triggered automatically by events defined by the engine, such as sensor collision, AI Model initialization, mouse clicks etc.

Universal Handlers

Both User AIModels and Object AIModels can use Universal Handlers.

• onInit: Executed when AI is initialized. Use it to initialize all your variables, object handles, and so forth, to make them ready for all the other functions in the AIModel.
• onEnterFrame: Executed every frame. All code that changes over time (moving the object, change its size, color, etc) should be placed in here. This event is very important, because this is the place where you usually animate the object attached to the AI instance.

Note: objects can also be animated in the 'onLoop' handler of the AI states, as it is also called every frame.

User Handlers

User Handlers can only be used in User AIModels, as only users (real-world physical players) can cause the events these handlers capture, like pressing a button, moving the mouse, exiting the application, etc.

• Application-related Handlers: onApplicationWillQuit, onApplicationWillPause, onApplicationHasResumed, etc
• Input-related Handlers: onMouseMove, onKeyboardKeyDown, onJoypadMove, etc.

Please refer to the dedicated Handler section on these API pages to learn more about all available eventhandlers. There are also some user handlers dedicated to multiplayer games, like "onUserEnterSession" or "onUserEnterScene". These events are sent by the Engine to the user AIs (not to the object AIs).

Object Handlers

Object Handlers can only be used in Object AIModels, as only objects (in-game 3d objects) can cause the events these handlers capture, like colliding with sensors, getting deactivated, etc.

Object Handlers include: onSenserCollision, onActivate, onDeactivate, etc

Please refer to the dedicated Handler section on these API pages to learn more about all available eventhandlers.

Custom Handlers

By clicking on "Custom...", a custom handler can be created. Such handlers must be called manually in the code, using the functions

• user.sendEvent / user.postEvent if the recipient AI is a user AI, and
• object.sendEvent / object.postEvent if the recipient AI is an object AI.

postEvent is the same as sendEvent, but includes a delay.

Custom handlers are functions, so you can add custom parameters like with normal functions.

Sending Custom Events

You can trigger events by using sendEvent/postEvent. It is important to know whether the target AI is carried by a user or an object.

Sending to User AIs

user.sendEvent ( hUser, sAIModel, sHandler, ... )
user.postEvent ( hUser, nDelay, sAIModel, sHandler, ... )

hUser points to the user holding the AI, it needs to be obtained at runtime.

-- in object AImodel:
local hUser = application.getCurrentUser ( )

-- in user  AIModel:
local hUser = this.getUser ( )
  
-- in multiplayer game:
local hUser = scene.getUserAt ( hScene, nIndex ) --OR
local hUser = application.getUser ( nID ) --OR
local hUser = application.getUserAt ( nIndex )

In most cases, the game will be only local, so for now, just remember application.getCurrentUser ( ) and this.getUser ( ).

Sending to Object AIs

object.sendEvent ( hObject, sAIModel, sHandler, ... )
object.postEvent ( hObject, nDelay, sAIModel, sHandler, ... )

hObject points to the object holding the AI, it needs to be obtained at runtime.

-- if the target handler is in the same AIModel:
local hObject = this.getObject ( )

--if the target handler is in another object that carries a scene tag:
local hObject = application.getCurrentUserSceneTaggedObject ( sObjectTag )

--if the target handler is in another object that carries a scene tag in another scene:
local hObject = scene.getTaggedObject ( hScene, sObjectTag )

--if the target handler is in another object that you know by its object handle:
local hObject = scene.getObjectAt ( hScene, nIndex )

You can send custom parameters for your custom handlers with send/postEvent after sHandler.

Event Queue

When you are sending an event, it is not immediately executed. Events are stored in a queue, and they will be executed after the currently executed function.

Furthermore, this.sendEvent ( "onMyEvent" ) and this.postEvent ( 0, "onMyEvent" ) are different. The sendEvent function will be executed in the current frame if possible, whereas the postEvent with a delay of 0 seconds will be executed at the next frame.

There is a function in the API to pause the scene: scene.setPaused ( bPaused ). If at some time in the game the scene is paused, all the objects of the scene will be paused, including their AIs, that means when the scene is paused, only user AIs are running.