tiny-ecs/tiny.lua

559 lines
16 KiB
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