Roomy

Roomy is a scene management library for LÖVE. It helps organize game code by the different "screens" in the game, such as the title screen, gameplay screen, and pause screen.

Installation

To use Roomy, place roomy.lua in your project, and then require it in each file where you need to use it:

local roomy = require 'roomy' -- if your roomy.lua is in the root directory
local roomy = require 'path.to.roomy' -- if it's in subfolders

Usage

Defining scenes

A scene is defined as a table with functions for each event it should respond to. For example, a gameplay scene may look like this:

local gameplay = {}

function gameplay:enter(previous, ...)
	-- set up the level
end

function gameplay:update(dt)
	-- update entities
end

function gameplay:leave(next, ...)
	-- destroy entities and cleanup resources
end

function gameplay:draw()
	-- draw the level
end

A scene table can contain anything, but it will likely have some combination of functions corresponding to LÖVE callbacks and Roomy events.

Creating a scene manager

local manager = roomy.new()

Creates a new scene manager. You can create as many scene managers as you want, but you'll most likely want one global manager for the main scenes of your game.

Switching scenes

manager:enter(scene, ...)

Changes the currently active scene.

Pushing/popping scenes

manager:push(scene, ...)
manager:pop()

Managers use a stack to hold scenes. You can push a scene onto the top of the stack, making it the currently active scene, and then pop it, resuming the previous state where it left off. This is useful for implementing pause screens, for example:

local pause = {}

function pause:keypressed(key)
	if key == 'escape' then
		manager:pop()
	end
end

local game = {}

function game:keypressed(key)
	if key == 'escape' then
		manager:push(pause)
	end
end

Emitting events

manager:emit(event, ...)

Calls scene:[event] on the active scene if that function exists. Additional arguments are passed to scene.event.

Hooking into LÖVE callbacks

manager:hook(options)

Adds code to the LÖVE callbacks to emit events for each callback (previously defined behavior will be preserved). options is an optional table with the following keys:

include - a list of callbacks to hook into. If this is defined, only these callbacks will be overridden.
exclude - a list of callbacks not to hook into. If this is defined, all of the callbacks except for these ones will be overridden.

As an example, the following code will cause the scene manager to hook into every callback except for keypressed and mousepressed.

manager:hook {
	exclude = {'keypressed', 'mousepressed'},
}

Note: because this function overrides the LOVE callbacks, you'll want to call this after you've defined them. I recommend using this function in the body of love.load, like this:

function love.load()
	manager:hook()
	manager:enter(gameplay)
end

Scene callbacks

Scenes have a few special callbacks that are called when a scene is switched, pushed, or popped.

function scene:enter(previous, ...) end

Called when a manager switches to this scene or if this scene is pushed on top of another scene.

previous - the previously active scene, or false if there was no previously active scene
... - additional arguments passed to manager.switch or manager.push

function scene:leave(next, ...) end

Called when a manager switches away from this scene or if this scene is popped from the stack.

next - the scene that will be active next
... - additional arguments passed to manager.switch or manager.pop

function scene:pause(next, ...) end

Called when a scene is pushed on top of this scene.

next - the scene that was pushed on top of this scene
... - additional arguments passed to manager.push

function scene:resume(previous, ...) end

Called when a scene is popped and this scene becomes active again.

previous - the scene that was popped
... - additional arguments passed to manager.pop

gtco/roomy