Skip to main content
The RollingQuest scripting system lets you extend any level you build with custom gameplay logic written in Lua. You attach scripts directly to game entities — the level itself, individual blocks, sides, items, enemies, and balls — and the game automatically calls specific functions in those scripts whenever something interesting happens. Whether you want to show a welcome message when a level starts, destroy a block when the ball rolls over it, or build an elaborate sequence of events triggered by signals, scripts are how you make it happen.

​
What you can do

The scripting API gives you control over many parts of the game:
  • Hooks — React to game events (level start, ball death, item collected, projectile hit, and more) by defining named functions the engine calls automatically.
  • Signals — Send named messages between scripts attached to different entities, so one entity’s script can trigger behavior in another.
  • Level control — Complete or fail the level, manage lives and score, manipulate the hourglass timer, save checkpoints, and query game state through the Level namespace.
  • Dialog — Display on-screen messages using Dialog.createTemporary, Dialog.createCloseable, or Dialog.createManual for full control over when messages appear and disappear.
  • Projectiles — Spawn and configure projectiles at runtime with Level.createProjectile, complete with custom speed, homing behavior, and collision callbacks.
  • Flyby camera — Script cinematic fly-through sequences that play when the level loads.
  • Campaign data — Read and write persistent data across levels in a campaign using Level.campaignGlobalData.
  • Element lookup — Find any block, ball, item, enemy, or decoration in the level by position, tag, or index using Level.getBlock, Level.getBalls, and related functions.
  • Data storage — Store per-entity values between hook calls using localData on any entity.
  • OOP helpers — Define your own Lua classes with class(), new(), and instanceof() for more structured scripting.

​
Where to start

Lua Basics

New to programming? Start here for a gentle introduction to the Lua language.

Script Editor

Learn how to open the built-in editor, attach scripts to entities, and run your first script.

Hooks

Understand how hooks work and which events each entity type exposes.

Signals

Learn how to send messages between scripts on different entities.

Dialog Messages

Show temporary, closeable, and manually controlled messages in your levels.

Level Namespace

Full API reference for the Level namespace — the central hub for game-state control.

​
How it works

The scripting system is built around three ideas that work together. Scripts are attached to entities. Every game entity — the level, a block, a side, an item, an enemy, a ball — can have its own Lua script file. Scripts are independent of each other by default, which keeps things tidy as your level grows. The game calls hook functions automatically. Inside each script you define functions with specific names, called hooks. When the corresponding event happens in the game, the engine finds your function and calls it, passing the relevant entity as the first argument. For example, if you define OnStart in a level script, the engine calls it the moment the level begins: 
function OnStart(self)
  Dialog.createTemporary("Welcome to my level!", 3)
end
You don’t need to register or connect anything — just give the function the right name and the engine does the rest. Scripts call API namespaces to affect the game. Beyond reacting to events, your scripts can actively change the game. Namespaces like Level, Dialog, and Logger are available as global tables in every script. Call their functions to query or modify game state, display messages, spawn projectiles, and more.
You don’t need any programming experience to get started. The Lua Basics page walks through everything you need to know about the language from the ground up before you write your first hook.