Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/tesselode/roomy

Scene management for LÖVE.
https://github.com/tesselode/roomy

Last synced: 3 months ago
JSON representation

Scene management for LÖVE.

Lists

README 

        
# 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:



```lua

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:



```lua

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



```lua

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



```lua

manager:enter(scene, ...)

```



Changes the currently active scene.



### Pushing/popping scenes



```lua

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:



```lua

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



```lua

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



```lua

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`.



```lua

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:



```lua

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.



```lua

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.enter` or `manager.push`



```lua

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.enter` or `manager.pop`



```lua

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`



```lua

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`