tiny-ecs/README.md

tiny-ecs

Tiny-ecs is an Entity Component System for lua that's simple, flexible, and useful. Because of lua's tabular nature, Entity Component Systems are a natural choice for simulating large and complex systems. For more explanation on Entity Component Systems, here is some basic info.

Tiny-ecs also works well with Objected Oriented programming in lua because Systems and Entities do not use metatables. This means you can subclass your Systems and Entities, and use existing lua class frameworks with tiny-ecs, no problem.

Overview

Tiny-ecs has four important types: Worlds, Filters, Systems, and Entities. Entities, however, can be any lua table, and Filters are just functions that take an Entity as a parameter.

Entities

Entities are simply lua tables of data that gets processed by Systems. Entities should contain primarily data rather than code, as it is the Systems's job to do logic on data. Henceforth, a key-value pair in an Entity will be referred to as a Component.

Worlds

Worlds are the outermost containers in tiny-ecs that contain both Systems and Entities. In typical use, only one World is used at a time.

Systems

Systems in tiny-ecs describe how to update Entities. Systems select certain Entities using a Filter, and then only update those select Entities. Some Systems don't update Entities, and instead just act as function callbacks every update. Tiny-ecs provides functions for creating Systems easily, as well as creating Systems that can be used in an Object Orientented fashion.

Filters

Filters are used to select Entities. Filters can be any lua function, but tiny-ecs provides some functions for generating common ones, like selecting only Entities that have all required components.

Example

local tiny = require("tiny")

local talkingSystem = tiny.processingSystem()
talkingSystem.filter = tiny.requireAll("name", "mass", "phrase")
function talkingSystem:process(e, dt)
    e.mass = e.mass + dt * 3
    print(e.name .. ", who weighs " .. e.mass .. " pounds, says, \"" .. e.phrase .. "\"")
end

local joe = {
    name = "Joe",
    phrase = "I'm a plumber.",
    mass = 150,
    hairColor = "brown"
}

local world = tiny.world(talkingSystem, joe)

for i = 1, 20 do
    world:update(1)
end

Use It

Copy paste tiny.lua into your source folder. For stability and consistent API, please use a tagged release or use luarocks. Tagged releases will have a version number in tiny._VERSION, while other commits will just have the string 'dev'.

Luarocks

Tiny-ecs is also on Luarocks and can be installed with luarocks install tiny-ecs.

Demo

Check out the demo, a game originally written for Ludum Dare 32 with the theme 'An Unconventional Weapon'. The demo uses LOVE, an amazing game framework for lua.

Testing

Tiny-ecs uses busted for testing. Install and run busted from the command line to test.

Documentation

See API here. Documentation can be generated locally with LDoc.

TODO

• More testing
• Performance testing / optimization
• Add more System types
• Improve Documentation