Global Command: registerEventHandler

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: "ENTER" "LEAVE"
	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: "LoadingSavegameSuccess"
	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: eEvtKeyDown (1): This event can be fired multiple times when pressing a key. eEvtKeyUp (2): This event will only fire once when pressing a key. eEvtKeyTextInput (3): This event can be fired multiple times when pressing a key. Use it to keep track of the user entering more complex unicode characters, where multiple keys have to be pressed to generate a single character (e. g. Chinese characters). eEvtControllerKeyDown (4) eEvtControllerKeyUp (5) eEvtControllerAxis (6)	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: eKeyBackspace (8) eKeyTab (9) eKeyReturn (13) eKeyEscape (27) eKeySpace (32)
	modifiers (int)	The currently active key modifiers (only valid for "eEvtKeyDown" and "eEvtKeyUp" events): eKeyModLShift (1) eKeyModRShift (2) eKeyModShift (3) eKeyModLCtrl (64) eKeyModCtrl (192) eKeyModRCtrl (128) eKeyModLAlt (256) eKeyModRAlt (512) eKeyModAlt (768) eKeyModLGui (1024) eKeyModRGui (2048) eKeyModGui (3072) eKeyModNum (4096) eKeyModCaps (8192) eKeyModMode (16384)
"mainLoop"	none
"mouseEvent"	eventType (int)	The mouse event which triggered the function. Supported values: eEvtMouseMove (1) eEvtMouseLeftButtonDoubleClick (2) eEvtMouseLeftButtonDown (3) eEvtMouseLeftButtonUp (4) eEvtMouseLeftButtonHold (5) eEvtMouseLeftButtonHolding (6) eEvtMouseRightButtonDoubleClick (7) eEvtMouseRightButtonDown (8) eEvtMouseRightButtonUp (9) eEvtMouseMiddleButtonDown (10) eEvtMouseMiddleButtonUp (11) eEvtMouseWheelUp (12) eEvtMouseWheelDown (13) eEvtMultiGesture (14) eEvtDollarGesture (15) eEvtTouchDown (16) eEvtTouchUp (17) eEvtTouchMove (18)
	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: for "eEvtMultiGesture": the amount that the fingers pinched during the motion for "eEvtDollarGesture": the difference between the gesture template and the actual performed gesture (a lower error is a better match)
	fingers2 (int)	Only valid for "eEvtMultiGesture" and "eEvtDollarGesture" events: for "eEvtMultiGesture": the amount that the fingers rotated during the motion, in radians for "eEvtDollarGesture": the number of fingers used in the gesture
	fingers3 (int)	Only valid for "eEvtMultiGesture" and "eEvtDollarGesture" events: for "eEvtMultiGesture": the number of fingers used in the gesture for "eEvtDollarGesture": the unique id of the closest gesture to the performed stroke
"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")