Events¶
Unlike other APIs, events are special functions that you define inside of
menu/main.lua and hud/main.lua, which are called when various
corresponding events happen in game, such as a frame starting or ending.
If the player is playing a level, then the HUD script will recieve all events. Otherwise, the main menu script is used, since that will usually always be loaded.
Many functions can return a boolean indicating if the normal call to the
function should be cancelled so that it is no longer called. For example, when
returning true (or any truthy value) from onHitSomething, the call to
Level::hitSomething() that would normally be done after your event handler
is not made.
Tip
Since release 23, there is exprimental support for specifying event handlers as tables of functions, thus allowing you to have more than one event handler per type of event. This is most useful for libraries that want to hook into events without overriding the user’s own event handlers.
This is also supported for the built-in functions, like draw, frame,
and handleCommand, though you may need to fix parts of the script where
those functions are called directly.
Be aware, however, that an event being cancelled in one function will cause the rest of the event handlers not to run.
- onFrameStart()¶
Called before any call to
Game::frame().
- onFrameEnd()¶
Called after any call to
Game::frame().
-
onHandleInput():
boolean¶ Called before any call to
Level::handleInput().- Returns:
A boolean indicating if the call to
Level::handleInput()should be cancelled
-
onHitSomething(playerId:
integer):boolean¶ Called before any call to
Level::hitSomething(), which is called on every frame the player intersects with an obstacle.- Parameters:
playerId – Relevant player ID
- Returns:
A boolean indicating if the call to
Level::hitSomething()should be cancelled
-
onStreakInc(playerId:
integer):boolean¶ Called before any call to
Level::streakInc(), which is called whenever the player hits a crystal.- Parameters:
playerId – Relevant player ID
- Returns:
A boolean indicating if the call to
Level::streakInc()should be cancelled
-
onStreakAbort(playerId:
integer):boolean¶ Called before any call to
Level::streakAbort(), which is called any time the current streak needs to be reset to zero (such as on crashing).- Parameters:
playerId – Relevant player ID
- Returns:
A boolean indicating if the call to
Level::streakAbort()should be cancelled
-
onEnterRoom(type:
string)¶ Called before any call to
Level::enterRoom(), which is called when entering a room.- Parameters:
type – Type of the room (e.g.
cave/narrow)
-
onLoadCheckpoint(index:
integer):boolean¶ Called before any call to
Player::loadCheckpoint(), which is called to load checkpoint balls and streak data.- Parameters:
index – Checkpoint index
- Returns:
A boolean indicating if the call to
Player::loadCheckpoint()should be cancelled
-
onReportCheckpoint(index:
integer):boolean¶ Called before any call to
Player::reportCheckpoint(), which is called to save checkpoint balls and streak data.- Parameters:
index – Checkpoint index
- Returns:
A boolean indicating if the call to
Player::reportCheckpoint()should be cancelled