Scenery - A dead simple Love2D Scene/State Manager

Scenery is a dead simple Scene/State Manager for Love2D.

Scenes (or States) are a very popular organising system for games. Scenery is a simple to use and lightweight implementation of the system for Love2D.

Installation

Just grab the scenery.lua from this repository and require it in you main.lua file.

Usage

After initialization of Scenery (described in detail below) just call the used callbacks in corresponding Love2D callbacks.

For example:

local SceneryInit = require("path.to.scenery")
local scenery = SceneryInit(...)

function love.load()
    scenery:load()
end

function love.draw()
    scenery:draw()
end

function love.update(dt)
    scenery:update(dt)
end

Also, the scenery instance has a hook method on it, which will do the boilerplate for you. The above example can be shortened as:

local SceneryInit = require("path.to.scenery")
local scenery = SceneryInit(...)
scenery:hook(lua)

Scenery supports all Love2D 11.5 callbacks.

The hook method optionally accepts a second argument, a table, with the callbacks which will be hooked. eg { "load", "draw", "update" }

Scenes

Scenes are, in Scenery, just tables returned by a file. Each scene must have a separate file for itself and return a table containing all the callback methods. Scene callbacks methods are exactly the same as Love callback methods, except load, which has an optional argument containing data transferred by other scenes.

An Example Scene:

local game = {}

function game:load()
    print("Scenery is awesome")
end

function game:draw()
    love.graphics.print("Scenery makes life easier", 200, 300)
end

function game:update(dt)
    print("You agree, don't you?")
end

return game

Loading the Scenes

Automatic Loading

Scenery can automatically load your scenes for you. scenery.lua returns a function that accepts a default scene as first parameter and path to the folder containing scenes as an optional second parameter. If no path is supplied Scenery will look into scenes folder from the folder containing your main.lua file for scenes.

Example:

local SceneryInit = require("path.to.scenery")
local scenery = SceneryInit("scene", "path/to/scenes")

The filename of the file (without the extension) containing scene will be considered the scene key.

⚠️ If your file name has periods (.) before the file extension (eg game.scene.lua) then only the string before the first period (ie game in the above case) will be considered the scene key.

Manual Loading

Scenery can also manually load you scenes. The function returned by scenery.lua can accept multiple tables, each for one scene. You can have the following properties in the table:

Property	Description
`path`	The path to the file returning a table structured in the form a scene table.
`key`	A unique string identifying the scene.
`default` (optional)	A boolean value representing the default scene. Must not be `true` on more than one scene. If omitted the first scene in the arguments will be considered default.

Example:

local SceneryInit = require("path.to.scenery")
local scenery = SceneryInit(
    { path = "path.to.scene1"; key = "scene1"; default = "true" },
    { path = "path.to.scene2"; key = "scene2"; }
)

Changing Scenes

Changing scenes in Scenery is very simple. Scenery creates a setScene method on the scene table to change scenes. The function accepts scene key as first parameter and an optional argument which will be passed to the load callback of the new scene. It is as simple as:

function scene1:load()
    self.setScene("scene2", { score = 52 })
end

Then you can access the score in menu scene by:

function scene2:load(args)
    print(args.score) -- prints 52
end

Contributing

If you have found a bug or have any suggestion, feel free to open an issue. If you fixed a bug or added a new feature, add a pull request.

License

The project is licensed under the MIT License. A copy of the license can be found in the repository by the name of LICENSE.txt

paltze/scenery