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