RollingQuest Lua Hooks: Full Reference by Entity Type

Hooks are the foundation of RollingQuest scripting. When the game detects an event — the level starting, the ball rolling onto a block, an enemy dying — it looks for a matching global function in your script and calls it automatically. You don’t register listeners or subscribe to events; you simply define the function with the right name, and the game does the rest.

What Is a Hook?

A hook is a global Lua function whose name matches one of the game’s predefined event names. The game calls your function when the corresponding event fires, passing in contextual data as parameters. For example, a Level script that prints a message when play begins looks like this:

function OnStart(self)
    print("Level started!")
end

The function name OnStart is the hook name. The game recognises it and calls it at the right moment.

The `self` Parameter

Every hook receives self as its first argument. The value of self depends on which entity type the script is attached to:

Script attached to	`self` type
Level	`Level`
Ball	`Ball`
Block	`Block`
Side	`Side`
Item	`Item`
Enemy	`Enemy`

Use self to read properties of the entity and call methods on it from within the hook.

Hooks by Entity Type

Level Hooks

Hooks available in a script attached to the level itself.

Hook	Signature	Description
`OnStart`	`function OnStart(self)`	Called once when the level begins.
`OnUpdate`	`function OnUpdate(self, deltaTime)`	Called every frame; `deltaTime` is the elapsed time in seconds since the last frame.
`OnWon`	`function OnWon(self)`	Called when the player successfully completes the level.
`OnLost`	`function OnLost(self)`	Called when the player loses the level.
`OnSignal`	`function OnSignal(self)`	Called when the level receives an inbound signal.

---@param self Level
---@param deltaTime number
function OnUpdate(self, deltaTime)
    -- runs every frame
end

Ball Hooks

Hooks available in a script attached to a ball entity.

Hook	Signature	Description
`OnSpawn`	`function OnSpawn(self)`	Called when the ball first spawns into the level.
`OnUpdate`	`function OnUpdate(self, deltaTime)`	Called every frame while the ball is alive.
`OnBallRoll`	`function OnBallRoll(self, rollIn, side)`	Called when the ball rolls onto or off of a side; `rollIn` is `true` when rolling on, `false` when rolling off.
`OnProjectileCollide`	`function OnProjectileCollide(self, projectile)`	Called when the ball is hit by a projectile.
`OnExit`	`function OnExit(self)`	Called when the ball exits the level.
`OnDeath`	`function OnDeath(self)`	Called when the ball dies.
`OnSignal`	`function OnSignal(self, signal)`	Called when the ball receives a signal.
`OnDestroy`	`function OnDestroy(self)`	Called just before the ball is removed from the level.

Block Hooks

Hooks available in a script attached to a block entity.

Hook	Signature	Description
`SpawnCondition`	`function SpawnCondition(self) → boolean`	Called before the block spawns; return `false` to prevent it from appearing.
`OnSpawn`	`function OnSpawn(self)`	Called when the block spawns into the level.
`OnUpdate`	`function OnUpdate(self, deltaTime)`	Called every frame.
`OnBallRoll`	`function OnBallRoll(self, rollIn, side, ball)`	Called when the ball rolls onto or off of one of the block’s sides.
`OnProjectileCollide`	`function OnProjectileCollide(self, projectile)`	Called when a projectile strikes the block.
`OnDestroy`	`function OnDestroy(self)`	Called just before the block is removed.
`OnSignal`	`function OnSignal(self, signal)`	Called when the block receives a signal.
`OnCustomEvent`	`function OnCustomEvent(self, event)`	Called when a custom game event is dispatched to the block.

Side Hooks

Hooks available in a script attached to a side (one face of a block).

Hook	Signature	Description
`OnSpawn`	`function OnSpawn(self)`	Called when the side spawns.
`OnUpdate`	`function OnUpdate(self, deltaTime)`	Called every frame.
`OnBallRoll`	`function OnBallRoll(self, rollIn, ball)`	Called when the ball rolls onto or off of this side specifically.
`OnProjectileCollide`	`function OnProjectileCollide(self, projectile)`	Called when a projectile hits this side.
`OnDestroy`	`function OnDestroy(self)`	Called just before the side is removed.
`OnSignal`	`function OnSignal(self, signal)`	Called when the side receives a signal.
`OnCustomEvent`	`function OnCustomEvent(self, event)`	Called when a custom event targets this side.

Item Hooks

Hooks available in a script attached to an item entity.

Hook	Signature	Description
`SpawnCondition`	`function SpawnCondition(self) → boolean`	Return `false` to prevent the item from spawning.
`OnSpawn`	`function OnSpawn(self)`	Called when the item spawns.
`OnUpdate`	`function OnUpdate(self, deltaTime)`	Called every frame while the item is active.
`OnCollect`	`function OnCollect(self, ball)`	Called when the ball collects this item.
`OnProjectileCollide`	`function OnProjectileCollide(self, projectile)`	Called when a projectile hits the item.
`OnDestroy`	`function OnDestroy(self)`	Called just before the item is removed.
`OnSignal`	`function OnSignal(self, signal)`	Called when the item receives a signal.
`OnCustomEvent`	`function OnCustomEvent(self, event)`	Called when a custom event targets this item.

Enemy Hooks

Hooks available in a script attached to an enemy entity.

Hook	Signature	Description
`SpawnCondition`	`function SpawnCondition(self) → boolean`	Return `false` to prevent the enemy from spawning.
`OnSpawn`	`function OnSpawn(self)`	Called when the enemy spawns.
`OnUpdate`	`function OnUpdate(self, deltaTime)`	Called every frame while the enemy is alive.
`OnProjectileCollide`	`function OnProjectileCollide(self, projectile)`	Called when a projectile hits the enemy.
`OnDeath`	`function OnDeath(self)`	Called when the enemy dies.
`OnDestroy`	`function OnDestroy(self)`	Called just before the enemy is removed.
`OnSignal`	`function OnSignal(self, signal)`	Called when the enemy receives a signal.
`OnCustomEvent`	`function OnCustomEvent(self, event)`	Called when a custom event targets this enemy.

Special Hooks

SpawnCondition

SpawnCondition is a hook that applies to Block, Item, and Enemy scripts. The game calls it before the entity is placed in the level, and your return value decides whether the entity actually appears. Return true (or nothing) to allow the spawn. Return false to suppress it.

---@param self Block
---@return boolean
function SpawnCondition(self)
    -- Only spawn this block if campaign progress flag is set
    return Level.campaignGlobalData:getBool("bridge_unlocked", false)
end

SpawnCondition is called very early in level setup. Avoid referencing other entities that may not exist yet.

OnCustomEvent

OnCustomEvent is available on Block, Side, Item, and Enemy scripts. It fires when a concrete sub-class of the parent entity emits one of its own built-in events — for example, a SideButton emits a pressed event when the ball rolls over it, and a BlockBreaking emits break when it shatters. The event set is fixed per sub-class. The base Block, Side, Item, and Enemy types themselves emit no custom events; only their typed sub-classes do. Inside the hook, inspect the CustomEvent argument to dispatch on event name and read any parameters the sub-class sent with it.

CustomEvent shape

Field	Type	Description
`name`	`string`	The event identifier (e.g. `"pressed"`, `"break"`, `"teleport"`).
`parameters`	`table`	Named parameters sent with the event. Keys depend on the sub-class and event.
`params`	`table`	Alias for `parameters`.

Signature

---@param self Block|Side|Item|Enemy
---@param event CustomEvent
function OnCustomEvent(self, event)
    if event.name == "pressed" then
        -- self is a SideButton
        print("Button pressed!")
    elseif event.name == "ballBreak" then
        -- self is a BlockBreaking; event.parameters.ball is the ball that broke it
        local ball = event.parameters.ball
        print(ball.name .. " broke the block")
    end
end

Events emitted by Block sub-classes

Sub-class	Event	Parameters	Fired when
`BlockToggle`	`activate`	—	The block becomes activated.
`BlockToggle`	`deactivate`	—	The block becomes deactivated.
`BlockBreaking`	`break`	—	The block breaks for any reason.
`BlockBreaking`	`ballBreak`	`ball: Ball`	A ball causes the block to break.
`BlockBreaking`	`enemyBreak`	`enemy: Enemy`	An enemy causes the block to break.
`BlockCounter`	`break`	—	The counter reaches zero and the block breaks.
`BlockCounter`	`ballBreak`	`ball: Ball`	A ball triggers the final break.
`BlockCounter`	`enemyBreak`	`enemy: Enemy`	An enemy triggers the final break.
`BlockCounter`	`timesChange`	`oldTimes: integer`, `newTimes: integer`	The remaining count changes.
`BlockTrigger`	`enter`	`ball: Ball`	A ball enters the trigger volume.
`BlockBlinking`	`appear`	—	The block becomes solid in the blink cycle.
`BlockBlinking`	`disappear`	—	The block becomes intangible in the blink cycle.

Events emitted by Side sub-classes

Sub-class	Event	Parameters	Fired when
`SideButton`	`pressed`	—	The button is pressed.
`SideSwitch`	`pressed`	—	The switch is pressed.
`SideSwitch`	`released`	—	The switch is released.
`SideSwitch`	`stateSwitch`	—	The switch toggles its on/off state.
`SidePressurePlate`	`pressed`	—	The plate is depressed by weight.
`SidePressurePlate`	`released`	—	The plate is released.
`SidePressurePlate`	`stateSwitch`	—	The plate toggles its state.
`SideCheckpoint`	`activated`	`firstTime: boolean`	The checkpoint is activated. `firstTime` is `true` on first contact.
`SideCheckpoint`	`deactivated`	—	The checkpoint is deactivated.
`SideExit`	`open`	—	The exit opens.
`SideExit`	`close`	—	The exit closes.
`SideTeleport`	`activate`	—	The teleporter activates.
`SideTeleport`	`deactivate`	—	The teleporter deactivates.
`SideTeleport`	`teleportBall`	`ball: Ball`	A ball is teleported.
`SideTeleport`	`teleportEnemy`	`enemy: Enemy`	An enemy is teleported.
`SideLaser`	`activate`	—	The laser turns on.
`SideLaser`	`deactivate`	—	The laser turns off.
`SideLaser`	`electrocuteEnemy`	`enemy: Enemy`	An enemy is killed by the laser beam.
`SideTeslaCoil`	`activate`	—	The coil powers up.
`SideTeslaCoil`	`deactivate`	—	The coil powers down.
`SideTeslaCoil`	`electrocuteEnemy`	`enemy: Enemy`	An enemy is electrocuted.
`SideSensorSpikes`	`activate`	—	Spikes extend.
`SideSensorSpikes`	`deactivate`	—	Spikes retract.
`SideSensorSpikes`	`catchBall`	`ball: Ball`	The spikes catch a ball.
`SideSensorSpikes`	`catchEnemy`	`enemy: Enemy`	The spikes catch an enemy.
`SideStaticSpikes`	`catchBall`	`ball: Ball`	The spikes catch a ball.
`SideStaticSpikes`	`catchEnemy`	`enemy: Enemy`	The spikes catch an enemy.
`SideRetractableSpike`	`in`	—	The spikes retract.
`SideRetractableSpike`	`out`	—	The spikes extend.
`SideRetractableSpike`	`spikeEnemy`	`enemy: Enemy`	An enemy is impaled.
`SidePatternSpike`	`in`	—	Spikes retract for this pattern step.
`SidePatternSpike`	`out`	—	Spikes extend for this pattern step.
`SidePatternSpike`	`spikeEnemy`	`enemy: Enemy`	An enemy is impaled.
`SideSawblades`	`activate`	—	The blades start spinning.
`SideSawblades`	`deactivate`	—	The blades stop.
`SideSawblades`	`catchBall`	`ball: Ball`	The blades catch a ball.
`SideSawblades`	`catchEnemy`	`enemy: Enemy`	The blades catch an enemy.
`SideRotator`	`rotateBall`	`ball: Ball`	A ball is rotated.
`SideRotator`	`rotateEnemy`	`enemy: Enemy`	An enemy is rotated.
`SideMagnet`	`stateChanged`	`state: integer`	The magnet changes mode.
`SideMagnet`	`catchBall`	`ball: Ball`	The magnet catches a ball.
`SideMagnet`	`catchEnemy`	`enemy: Enemy`	The magnet catches an enemy.
`SideJumpPad`	`farJump`	`ball: Ball`	A ball is launched in a long jump.
`SideJumpPad`	`highJump`	`ball: Ball`	A ball is launched in a high jump.
`SideLightSensor`	`ballDetect`	`ball: Ball`	A ball is detected by the sensor.
`SideLightSensor`	`enemyDetect`	`enemy: Enemy`	An enemy is detected by the sensor.

Events emitted by Item sub-classes

Sub-class	Event	Parameters	Fired when
`ItemPortalEntrance`	`teleport`	`ball: Ball`	A ball enters the portal and is teleported.

Events emitted by Enemy sub-classes

The base Enemy hook supports OnCustomEvent, but none of the built-in Enemy sub-classes currently emit custom events.

Complete Example

Below is a full Block script that uses four hooks together: it conditionally spawns, sets up state on spawn, reacts to the ball rolling across it, and cleans up when destroyed.

-- Block script: a fragile platform that breaks after one roll

local hasBeenRolled = false

---@param self Block
---@return boolean
function SpawnCondition(self)
    -- Only spawn if the player hasn't already broken it this session
    return not Level.localData:getBool("fragile_broken_" .. self.name, false)
end

---@param self Block
function OnSpawn(self)
    hasBeenRolled = false
    print(self.name .. " fragile platform ready.")
end

---@param self Block
---@param rollIn boolean
---@param side Side
---@param ball Ball
function OnBallRoll(self, rollIn, side, ball)
    if rollIn and not hasBeenRolled then
        hasBeenRolled = true
        print("Ball rolled on! Scheduling destruction...")
        -- Give the player half a second to move off before it breaks
        Level.delayAction(0.5, function()
            self:disable()
        end)
    end
end

---@param self Block
function OnDestroy(self)
    -- Persist that this block was broken so SpawnCondition suppresses it on respawn
    Level.localData:setBool("fragile_broken_" .. self.name, true)
    print(self.name .. " has been destroyed.")
end

You only need to define the hooks you actually use. The game silently ignores any hook that isn’t present in your script.

Get Started

Core Concepts

Recipes

RollingQuest Lua Hooks: Full Reference by Entity Type

What Is a Hook?

The `self` Parameter

Hooks by Entity Type

Level Hooks

Ball Hooks

Block Hooks

Side Hooks

Item Hooks

Enemy Hooks

Special Hooks

SpawnCondition

OnCustomEvent

CustomEvent shape

Signature

Events emitted by Block sub-classes

Events emitted by Side sub-classes

Events emitted by Item sub-classes

Events emitted by Enemy sub-classes

Complete Example

​What Is a Hook?

​The self Parameter

​Hooks by Entity Type

​Level Hooks

​Ball Hooks

​Block Hooks

​Side Hooks

​Item Hooks

​Enemy Hooks

​Special Hooks

​SpawnCondition

​OnCustomEvent

​CustomEvent shape

​Signature

​Events emitted by Block sub-classes

​Events emitted by Side sub-classes

​Events emitted by Item sub-classes

​Events emitted by Enemy sub-classes

​Complete Example

What Is a Hook?

The `self` Parameter

Hooks by Entity Type

Level Hooks

Ball Hooks

Block Hooks

Side Hooks

Item Hooks

Enemy Hooks

Special Hooks

SpawnCondition

OnCustomEvent

CustomEvent shape

Signature

Events emitted by Block sub-classes

Events emitted by Side sub-classes

Events emitted by Item sub-classes

Events emitted by Enemy sub-classes

Complete Example