tiny-ecs/tiny.lua

--- @module tiny-ecs
-- @author Calvin Rose
local tiny = { _VERSION = "1.0.2" }

-- Local versions of standard lua functions
local tinsert = table.insert
local tremove = table.remove
local pairs = pairs
local ipairs = ipairs
local setmetatable = setmetatable
local type = type

-- Local versions of the library functions
local tiny_manageEntities
local tiny_manageSystems
local tiny_addEntity
local tiny_addSystem
local tiny_add
local tiny_removeEntity
local tiny_removeSystem
local tiny_remove

--- Filter functions.
-- A Filter is a function that selects which Entities apply to a System.
-- @section Filter

--- Makes a Filter that filters Entities with specified Components.
-- An Entity must have all Components to match the filter.
-- @param ... List of Components
function tiny.requireAll(...)
    local components = {...}
    local len = #components
    return function(_, e)
        local c
        for i = 1, len do
            c = components[i]
            if type(c) == 'function' then
                if not c(_, e) then
                    return false
                end
            elseif e[c] == nil then
                return false
            end
        end
        return true
    end
end

--- Makes a Filter that filters Entities with specified Components.
-- An Entity must have at least one specified Component to match the filter.
-- @param ... List of Components
function tiny.requireOne(...)
    local components = {...}
    local len = #components
    return function(_, e)
        local c
        for i = 1, len do
            c = components[i]
            if type(c) == 'function' then
                if c(_, e) then
                    return true
                end
            elseif e[c] ~= nil then
                return true
            end
        end
        return false
    end
end

--- System functions.
-- A System is a wrapper around function callbacks for manipulating Entities.
-- @section System

-- Use an empty table as a key for identifying Systems. Any table that contains
-- this key is considered a System rather than an Entity.
local systemTableKey = { "SYSTEM_TABLE_KEY" }

-- Check if tables are systems.
local function isSystem(table)
    return table[systemTableKey]
end

--- Creates a System. Systems are tables that contain at least one field; 
-- an update function that takes parameters like so: 
-- `function system:update(entities, dt)`. `entities` is an unordered table of 
-- Entities with Entities as KEYS, and `dt` is the delta time. There are also a 
-- few other optional callbacks:
-- `function system:filter(entity)` - returns a boolean,
-- `function system:onAdd(entity)` - returns nil,
-- `function system:onRemove(entity)` - returns nil.
-- For Filters, it is conveient to use `tiny.requireAll` or `tiny.requireOne`,
-- but one can write their own filters as well.
-- @param table A table to be used as a System, or `nil` to create a new System.
function tiny.system(table)
    if table == nil then
        table = {}
    end
    table[systemTableKey] = true
    return table
end

-- Update function for all Processing Systems.
local function processingSystemUpdate(system, entities, dt)
    local preProcess = system.preProcess
    local process = system.process
    local postProcess = system.postProcess
    local entity

    if preProcess then
        preProcess(system, entities, dt)
    end

    if process then
        local len = #entities
        for i = 1, len do
            entity = entities[i]
            process(system, entity, dt)
        end
    end

    if postProcess then
        postProcess(system, entities, dt)
    end
end

--- Creates a Processing System. A Processing System iterates through its 
-- Entities in no particluar order, and updates them individually. It has two 
-- important fields, `function system:process(entity, dt)`, and `function 
-- system:filter(entity)`. `entities` is Entities, 
-- and `dt` is the delta time. There are also a few other 
-- optional callbacks:
-- `function system:preProcess(entities, dt)` - returns nil,
-- `function system:postProcess(entities, dt)` - returns nil,
-- `function system:onAdd(entity)` - returns nil,
-- `function system:onRemove(entity)` - returns nil.
-- For Filters, it is conveient to use `tiny.requireAll` or `tiny.requireOne`,
-- but one can write their own filters as well.
-- @param table A table to be used as a System, or `nil` to create a new 
-- Processing System.
function tiny.processingSystem(table)
    if table == nil then
        table = {}
    end
    table[systemTableKey] = true
    table.update = processingSystemUpdate
    return table
end

--- World functions.
-- A World is a container that manages Entities and Systems. The tiny-ecs module
-- is set to be the `__index` of all World tables, so the often clearer syntax of
-- World:method can be used for any function in the library. For example,
-- `tiny.add(world, e1, e2, e3)` is the same as `world:add(e1, e2, e3).`
-- @section World

local worldMetaTable = { __index = tiny }

--- Creates a new World.
-- Can optionally add default Systems and Entities.
-- @param ... Systems and Entities to add to the World
-- @return A new World
function tiny.world(...)

    local ret = {

        -- List of Entities to add
        entitiesToAdd = {},

        -- List of Entities to remove
        entitiesToRemove = {},

        -- List of Entities to add
        systemsToAdd = {},

        -- List of Entities to remove
        systemsToRemove = {},

        -- Set of Entities 
        entities = {},

        -- Number of Entities in World.
        entityCount = 0,

        -- List of System Data. A data element is a table with 4
        -- keys: system, indices, entities, and active.
        systems = {},

        -- Table of Systems to System Indices
        systemIndices = {}
    }

    tiny_add(ret, ...)
    tiny_manageSystems(ret)
    tiny_manageEntities(ret)

    return setmetatable(ret, worldMetaTable)

end

--- Adds an Entity to the world.
-- The new Entity will enter the world next time World:update is called.
-- Also call this on Entities that have changed Components such that it 
-- matches different systems.
-- @param world
-- @param entity
function tiny.addEntity(world, entity)
    local e2a = world.entitiesToAdd
    e2a[#e2a + 1] = entity
    if world.entities[entity] then
        tiny_removeEntity(world, entity)
    end
end
tiny_addEntity = tiny.addEntity

--- Adds a System to the world.
-- The new System will enter the world next time World:update is called.
-- @param world
-- @param system
function tiny.addSystem(world, system)
    local s2a = world.systemsToAdd
    s2a[#s2a + 1] = system
end
tiny_addSystem = tiny.addSystem

--- Shortcut for adding multiple Entities and Systems to the World.
-- New objects will enter the World the next time World:update(dt) is called.
-- Also call this method when an Entity has had its Components changed, such
-- that it matches different Filters.
-- @param world
-- @param ... Systems and Entities
function tiny.add(world, ...)
    local args = {...}
    for _, obj in ipairs(args) do
        if isSystem(obj) then
            tiny_addSystem(world, obj)
        else -- Assume obj is an Entity
            tiny_addEntity(world, obj)
        end
    end
end
tiny_add = tiny.add

--- Removes an Entity to the World.
-- The Entity will exit the World next time World:update is called.
-- Also call this on Entities that have changed Components such that it 
-- matches different systems.
-- @param world
-- @param entity
function tiny.removeEntity(world, entity)
    local e2r = world.entitiesToRemove
    e2r[#e2r + 1] = entity
end
tiny_removeEntity = tiny.removeEntity

--- Removes a System from the world.
-- The System will exit the World next time World:update is called.
-- @param world
-- @param system
function tiny.removeSystem(world, system)
    local s2r = world.systemsToRemove
    s2r[#s2r + 1] = system
end
tiny_removeSystem = tiny.removeSystem

--- Shortcut for removing multiple Entities and Systems from the World. 
-- Objects will exit the World the next time World:update(dt) is called.
-- @param world
-- @param ... Systems and Entities
function tiny.remove(world, ...)
    local args = {...}
    for _, obj in ipairs(args) do
        if isSystem(obj) then
            tiny_removeSystem(world, obj)
        else -- Assume obj is an Entity
           tiny_removeEntity(world, obj)
        end
    end
end
tiny_remove = tiny.remove

--- Updates a System.
-- @param world
-- @param system A System in the World to update
-- @param dt Delta time
function tiny.updateSystem(world, system, dt)
    local es = world.systemEntities[system]
    system:update(es, dt)
end

--- Adds and removes Systems that have been marked from the World.
-- The user of this library should seldom if ever call this.
-- @param world
function tiny.manageSystems(world)

        local s2a, s2r = world.systemsToAdd, world.systemsToRemove

        -- Early exit
        if #s2a == 0 and #s2r == 0 then
            return
        end

        local systemIndices = world.systemIndices
        local entities = world.entities
        local systems = world.systems

        local system, systemData, index, filter, entityList, entityIndices, entityIndex, onRemove, onAdd

        -- Remove Systems
        for i = 1, #s2r do
            system = s2r[i]
            index = systemIndices[system]
            if index then
                systemData = systems[index]
                onRemove = system.onRemove
                if onRemove then
                    entityList = systemData.entities
                    for j = 1, #entityList do
                        onRemove(system, entityList[j])
                    end
                end
                systemIndices[system] = nil
                tremove(systems, index)
                for j = index, #systems do
                    systemIndices[systems[j].system] = j
                end
            end
            s2r[i] = nil
        end

        -- Add Systems
        for i = 1, #s2a do
            system = s2a[i]
            if not systemIndices[system] then
                entityList = {}
                entityIndices = {}
                systemData = { system = system, entities = entityList, indices = entityIndices, active = true }
                index = #systems + 1
                systemIndices[system] = index
                systems[index] = systemData

                -- Try to add Entities
                onAdd = system.onAdd
                filter = system.filter
                if filter then
                    for entity in pairs(entities) do
                        if filter(system, entity) then
                            entityIndex = #entityList + 1
                            entityList[entityIndex] = entity
                            entityIndices[entity] = entityIndex
                            if onAdd then
                                onAdd(system, entity)
                            end
                        end
                    end
                end
            end
            s2a[i] = nil
        end

end
tiny_manageSystems = tiny.manageSystems

--- Adds and removes Entities that have been marked.
-- The user of this library should seldom if ever call this.
-- @param world
function tiny.manageEntities(world)

    local e2a, e2r = world.entitiesToAdd, world.entitiesToRemove

    -- Early exit
    if #e2a == 0 and #e2r == 0 then
        return
    end

    local entities = world.entities
    local systems = world.systems
    local entityCount = world.entityCount
    local entity, system, systemData, index, onRemove, onAdd, ses, seis, filter, tmpEntity

    -- Remove Entities
    for i = 1, #e2r do
        entity = e2r[i]
        if entities[entity] then
            entities[entity] = nil

            for j = 1, #systems do
                systemData = systems[j]
                system = systemData.system
                ses = systemData.entities
                seis = systemData.indices
                index = seis[entity]

                if index then
                    tmpEntity = ses[#ses]
                    ses[index] = tmpEntity
                    seis[tmpEntity] = index
                    seis[entity] = nil
                    ses[#ses] = nil
                    entityCount = entityCount - 1
                    onRemove = system.onRemove
                    if onRemove then
                        onRemove(system, entity)
                    end
                end

            end

        end
        e2r[i] = nil
    end


    -- Add Entities
    for i = 1, #e2a do
        entity = e2a[i]
        if not entities[entity] then
            entities[entity] = true

            for j = 1, #systems do
                systemData = systems[j]
                system = systemData.system
                ses = systemData.entities
                seis = systemData.indices
                filter = system.filter
                if filter and filter(system, entity) then
                    index = #ses + 1
                    ses[index] = entity
                    seis[entity] = index
                    entityCount = entityCount + 1
                    onAdd = system.onAdd
                    if onAdd then
                        onAdd(system, entity)
                    end
                end

            end

        end
        e2a[i] = nil
    end

    -- Update Entity count
    world.entityCount = entityCount

end
tiny_manageEntities = tiny.manageEntities

--- Updates the World.
-- Frees Entities that have been marked for freeing, adds
-- entities that have been marked for adding, etc.
-- @param world
-- @param dt Delta time
function tiny.update(world, dt)

    tiny_manageSystems(world)
    tiny_manageEntities(world)

    local systems = world.systems
    local systemData

    --  Iterate through Systems IN ORDER
    for i = 1, #systems do
        systemData = systems[i]
        if systemData.active then
            systemData.system:update(systemData.entities, dt)
        end
    end
end

--- Removes all Entities from the World.
-- When World:update(dt) is next called,
-- all Entities will be removed.
-- @param world
function tiny.clearEntities(world)
    for e in pairs(world.entities) do
        tiny_removeEntity(world, e)
    end
end

--- Removes all Systems from the World.
-- When World:update(dt) is next called,
-- all Systems will be removed.
-- @param world
function tiny.clearSystems(world)
    local systems = world.systems
    for i = #systems, 1, -1 do
        tiny_removeSystem(world, systems[i].system)
    end
end

--- Gets count of Entities in World.
-- @param world
function tiny.getEntityCount(world)
    return world.entityCount
end

--- Gets count of Systems in World.
-- @param world
function tiny.getSystemCount(world)
    return #(world.systems)
end

--- Gets the index of a System in the world. Lower indexed Systems are processed
-- before higher indexed systems.
-- @param world
-- @param system
function tiny.getSystemIndex(world, system)
    return world.systemIndices[system]
end

--- Sets the index of a System in the world. Changes the order in
-- which they Systems processed, because lower indexed Systems are processed 
-- first.
-- @param world
-- @param system
-- @param index
function tiny.setSystemIndex(world, system, index)
    local systemIndices = world.systemIndices
    local oldIndex = systemIndices[system]
    local systems = world.systems
    local systemData = systems[oldIndex]

    tremove(systems, oldIndex)
    tinsert(systems, index, systemData)

    for i = oldIndex, index, index >= oldIndex and 1 or -1 do
        systemIndices[systems[i].system] = i
    end
end

--- Activates Systems in the World.
-- Activated Systems will be update whenever tiny.update(world, dt) is called.
-- @param world
-- @param ... Systems to activate. The Systems must already be added to the
-- World.
function tiny.activate(world, ...)
    local args = {...}
    for _, system in ipairs(args) do
        world.systems[world.systemIndices[system]].active = true
    end
end

--- Deactivates Systems in the World.
-- Deactivated Systems must be update manually, and will not update when the
-- rest of World updates. They will, however, process new Entities added while
-- the System is deactivated.
-- @param world
-- @param ... Systems to deactivate. The Systems must already be added to the
-- World.
function tiny.deactivate(world, ...)
    local args = {...}
    for _, system in ipairs(args) do
        world.systems[world.systemIndices[system]].active = false
    end
end

return tiny