Global Command: registerEventHandler
From The Official Visionaire Studio: Adventure Game Engine Wiki
Registering an event handler allows you to run custom functions on specific engine events.
| Related functions | unregisterEventHandler |
Syntax
registerEventHandler(eventtype, handler [, flags])
Parameters
| Parameter | Type | Supported values | Description | |
|---|---|---|---|---|
| eventtype | string | "actionArea" | Event fires when a character enters or leaves an action area. | The type of event which triggers the event handler to be called. |
| "animationStarted" | Event fires when an animation gets started. | |||
| "animationStopped" | Event fires when an animation gets stopped. | |||
| "engineEvent" | Event fires on certain engine events. | |||
| "keyEvent" | Event fires when the user presses a key on the keyboard or gamepad. | |||
| "mainLoop" | Event fires continuously about 60 times per second. | |||
| "mouseEvent" | Event fires when the user uses the mouse or fingers/gestures on touch devices. | |||
| "textStarted" | Event fires when a text gets displayed. | |||
| "textStopped" | Event fires when a text display ends. | |||
| handler | string | The name of the function which is called when the event occurs. See the table below for the arguments the function takes. | ||
| flags | table of integers | see the list of mouse events in the table below | A list of mouse events upon which the event handler is called. Only applicable if eventtype = "mouseEvent". If no mouse event is specified, the event handler is registered for all mouse events. | |
Event handler function
Depending on the event type, the event handler function takes different arguments.
| Event type | Arguments | Description | |
|---|---|---|---|
| "actionArea" | movement (str) | The event which triggered the function. Supported values:
| |
| actionArea (TVisObj) | The action area that triggered the event. | ||
| character (TVisObj) | The character that triggered the event. | ||
| "animationStarted" | animation (TVisObj) | The animation which gets started. | |
| "animationStopped" | animation (TVisObj) | The animation which gets stopped. | |
| "engineEvent" | event (str) | The engine event which triggered the function. Supported values:
| |
| path (str) | The full path to the loaded savegame file.
Example (Windows): "C:\Users\USERNAME\AppData\Local/DEVELOPER/GAME/Savegames/savegame00.dat" | ||
| "keyEvent" | eventType (int) | The key event which triggered the function. Supported values:
|
The function must return a boolean. If true the key event will not be handled by the engine. |
| character (str) | The text input of the pressed key. This parameter only contains printable characters. | ||
| keycode (int) | Unicode/ASCII keycode of the pressed key (only valid for "eEvtKeyDown" and "eEvtKeyUp" events). Use it to query special keys like the following:
| ||
| modifiers (int) | The currently active key modifiers (only valid for "eEvtKeyDown" and "eEvtKeyUp" events):
| ||
| "mainLoop" | none | ||
| "mouseEvent" | eventType (int) | The mouse event which triggered the function. Supported values:
| |
| position (t_point) | The mouse position or the normalized center of the gesture (for "eEvtMultiGesture" and "eEvtDollarGesture" events), respectively. A table (associative array) containing the elements x (int) and y (int). | ||
| fingers1 (int) | Only valid for "eEvtMultiGesture" and "eEvtDollarGesture" events:
| ||
| fingers2 (int) | Only valid for "eEvtMultiGesture" and "eEvtDollarGesture" events:
| ||
| fingers3 (int) | Only valid for "eEvtMultiGesture" and "eEvtDollarGesture" events:
| ||
| "textStarted" | text (TVisObj) | The text object which gets displayed. | |
| "textStopped" | text (TVisObj) | The text object which gets stopped displaying. | |
Return values
none
Examples
Example 1: Register an event handler function for the main loop, printing a text to the log file continuously.
function onMainLoop()
print("I am still alive!")
end
registerEventHandler("mainLoop", "onMainLoop")
Example 2: Register an event handler function for mouse events which is called when the user uses the scroll wheel.
function onMouseEvent(eventType, position)
if eventType == eEvtMouseWheelUp then
print("User scrolled up.")
elseif eventType == eEvtMouseWheelDown then
print("User scrolled down.")
end
end
registerEventHandler("mouseEvent", "onMouseEvent", {eEvtMouseWheelUp, eEvtMouseWheelDown})
Example 3: Register an event handler function for key events.
function keyboardHandler(eventType, character, keycode, modifiers)
-- Two different ways of checking for the 0 key (by "character" or by "keycode" argument)
if eventType == eEvtKeyDown then
if character == "0" then
print("0 pressed")
end
elseif eventType == eEvtKeyUp then
if keycode == 48 then
print("0 released")
end
end
-- disable the "Esc" key (cutscenes can't be skipped)
if keycode == eKeyEscape then
-- return true to prevent the engine from handling the key event
return true
end
-- return false to let the engine handle the key event, too
return false
end
registerEventHandler("keyEvent", "keyboardHandler")
Example 4: Register an event handler function which gets executed after loading a savegame (be aware that this is only an example; the "read_ini()" function doesn't exist unless you created it).
function onEngineEvent(event, path)
if event == "LoadingSavegameSuccess" then
read_ini()
end
end
registerEventHandler("engineEvent", "onEngineEvent")
Example 5: Register an event handler function for the "textStarted" event. It keeps the user from skipping texts accidentally.
function delaySkipText(text)
if not text.Background then
-- Prevent text skipping
game.AlwaysAllowSkipText = false
-- Allow skipping again after 300ms have passed; create a non-skippable cutscene for
-- that period of time by hiding the cursor, if no cutscene is currently active
if game.HideCursor == false and game.CutsceneAction:isEmpty() then
game.HideCursor = true
setDelay(300, function() game.AlwaysAllowSkipText = true; game.HideCursor = false end)
else
setDelay(300, function() game.AlwaysAllowSkipText = true end)
end
end
end
registerEventHandler("textStarted", "delaySkipText")
