Update to version 1.1-4.

Remove tiny.getSystemEntityCount because it's useless and deprecation is for chumps.

README.md

@@ -1,4 +1,7 @@
 # tiny-ecs #
+
+[![License](http://img.shields.io/badge/Licence-MIT-brightgreen.svg)](LICENSE)
+
 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
@@ -8,6 +11,8 @@ Component Systems, here is some
 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.
+For an example on how to use tiny-ecs with object-oriented lua, take a look at the
+demo branch, specifically the systems and entities sub-directories.
 
 ## Overview ##
 Tiny-ecs has four important types: Worlds, Filters, Systems, and Entities.
@@ -29,7 +34,7 @@ Systems in tiny-ecs describe how to update Entities. Systems select certain Enti
 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.
+can be used in an object oriented fashion.
 
 ### Filters ###
 Filters are used to select Entities. Filters can be any lua function, but
@@ -64,7 +69,7 @@ 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'.
+number in `tiny._VERSION`, while other commits will just have the string 'scm'.
 
 ## Luarocks ##
 Tiny-ecs is also on [Luarocks](https://luarocks.org/) and can be installed with
@@ -73,7 +78,7 @@ Tiny-ecs is also on [Luarocks](https://luarocks.org/) and can be installed with
 ## Demo ##
 Check out the [demo](https://github.com/bakpakin/tiny-ecs/tree/demo-commandokibbles), a game
 originally written for Ludum Dare 32 with the theme 'An Unconventional Weapon'. The demo uses
-[LOVE](https://love2d.org/), an amazing game framework for lua.
+[LÖVE](https://love2d.org/), an amazing game framework for lua.
 
 ## Testing ##
 Tiny-ecs uses [busted](http://olivinelabs.com/busted/) for testing. Install and run
@@ -83,10 +88,4 @@ Tiny-ecs uses [busted](http://olivinelabs.com/busted/) for testing. Install and
 See API [here](http://bakpakin.github.io/tiny-ecs/doc/).
 For the most up-to-date documentation, read the source code, or generate the HTML
 locally with [LDoc](http://stevedonovan.github.io/ldoc/).
-
+See the original forum thread [here](https://love2d.org/forums/viewtopic.php?f=5&t=79937&p=182589).
-## TODO ##
-
-* More testing
-* Performance testing / optimization
-* Add more System types
-* Improve Documentation

config.ld

@@ -10,3 +10,4 @@ style = '!fixed'
 package = 'tiny-ecs'
 not_luadoc = true
 boilerplate = true
+no_return_or_parms = true

rockspecs/tiny-ecs-1.1-3.rockspec

@@ -0,0 +1,24 @@
+package = "tiny-ecs"
+version = "1.1-3"
+source = {
+    url = "git://github.com/bakpakin/tiny-ecs",
+    tag = "1.1-3"
+}
+description = {
+    summary = "Entity Component System for Lua.",
+    detailed = [[
+        Pure Lua implementation of an easy to use, compact, fast, and flexible
+        Entity Component System. Works well with Object Orientation.
+    ]],
+    homepage = "https://github.com/bakpakin/tiny-ecs",
+    license = "MIT"
+}
+dependencies = {
+    "lua >= 5.1"
+}
+build = {
+    type = "builtin",
+    modules = {
+        tiny = "tiny.lua"
+    }
+}

rockspecs/tiny-ecs-1.1-4.rockspec

@@ -0,0 +1,24 @@
+package = "tiny-ecs"
+version = "1.1-4"
+source = {
+    url = "git://github.com/bakpakin/tiny-ecs",
+    tag = "1.1-4"
+}
+description = {
+    summary = "Entity Component System for Lua.",
+    detailed = [[
+        Pure Lua implementation of an easy to use, compact, fast, and flexible
+        Entity Component System. Works well with Object Orientation.
+    ]],
+    homepage = "https://github.com/bakpakin/tiny-ecs",
+    license = "MIT"
+}
+dependencies = {
+    "lua >= 5.1"
+}
+build = {
+    type = "builtin",
+    modules = {
+        tiny = "tiny.lua"
+    }
+}

spec/tiny_spec.lua

@@ -215,6 +215,19 @@ describe('tiny-ecs:', function()
             assert.equals(1, world:getSystemIndex(oneTimeSystem))
         end)
 
+        it("Sorts Entities in Sorting Systems", function()
+            local sortsys = tiny.sortedProcessingSystem()
+            sortsys.filter = tiny.requireAll("vel")
+            function sortsys:compare(e1, e2)
+                return e1.vel.x < e2.vel.x
+            end
+            world:add(sortsys)
+            world:update(0)
+            assert.equals(sortsys.entities[1], entity2)
+            assert.equals(sortsys.entities[2], entity3)
+            assert.equals(sortsys.entities[3], entity1)
+        end)
+
     end)
 
 end)

tiny-ecs-scm-0.rockspec

@@ -0,0 +1,23 @@
+package = "tiny-ecs"
+version = "scm-0"
+source = {
+    url = "git://github.com/bakpakin/tiny-ecs",
+}
+description = {
+    summary = "Entity Component System for Lua.",
+    detailed = [[
+        Pure Lua implementation of an easy to use, compact, fast, and flexible
+        Entity Component System. Works well with Object Orientation.
+    ]],
+    homepage = "https://github.com/bakpakin/tiny-ecs",
+    license = "MIT"
+}
+dependencies = {
+    "lua >= 5.1"
+}
+build = {
+    type = "builtin",
+    modules = {
+        tiny = "tiny.lua"
+    }
+}

tiny.lua

@@ -23,14 +23,13 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 -- @author Calvin Rose
 -- @license MIT
 -- @copyright 2015
-local tiny = { _VERSION = "1.1-2" }
+local tiny = { _VERSION = "1.1-4" }
 
 -- Local versions of standard lua functions
 local tinsert = table.insert
 local tremove = table.remove
 local tsort = table.sort
 local pairs = pairs
-local ipairs = ipairs
 local setmetatable = setmetatable
 local type = type
 local select = select
@@ -51,8 +50,8 @@ local tiny_remove
 -- value indicating if the Entity should be processed by the System.
 --
 -- Filters must be added to Systems by setting the `filter` field of the System.
--- Filter's returned by `tiny.requireAll` and `tiny.requireAny` are immutable
+-- Filter's returned by tiny-ecs's Filter functions are immutable and can be
--- and can be used by multiple Systems.
+-- used by multiple Systems.
 --
 --    local f1 = tiny.requireAll("position", "velocity", "size")
 --    local f2 = tiny.requireAny("position", "velocity", "size")
@@ -88,7 +87,6 @@ local tiny_remove
 
 --- Makes a Filter that selects Entities with all specified Components and
 -- Filters.
--- @param ... List of required Components and other Filters.
 function tiny.requireAll(...)
     local components = {...}
     local len = #components
@@ -110,7 +108,6 @@ end
 
 --- Makes a Filter that selects Entities with at least one of the specified
 -- Components and Filters.
--- @param ... List of required Components and other Filters.
 function tiny.requireAny(...)
     local components = {...}
     local len = #components
@@ -132,7 +129,6 @@ end
 
 --- Makes a Filter that rejects Entities with all specified Components and
 -- Filters, and selects all other Entities.
--- @param ... List of required Components and other Filters.
 function tiny.rejectAll(...)
     local components = {...}
     local len = #components
@@ -154,7 +150,6 @@ end
 
 --- Makes a Filter that rejects Entities with at least one of the specified
 -- Components and Filters, and selects all other Entities.
--- @param ... List of required Components and other Filters.
 function tiny.rejectAny(...)
     local components = {...}
     local len = #components
@@ -183,10 +178,15 @@ end
 --
 -- There are also a few other optional callbacks:
 --
---   * `function system:filter(entity)`
+--   * `function system:filter(entity)` - Returns true if this System should
---   * `function system:onAdd(entity)`
+-- include this Entity, otherwise should return false. If this isn't specified,
---   * `function system:onRemove(entity)`
+-- no Entities are included in the System.
---   * `function system:onModify(dt)`
+--   * `function system:onAdd(entity)` - Called when an Entity is added to the
+-- System.
+--   * `function system:onRemove(entity)` - Called when an Entity is removed
+-- from the System.
+--   * `function system:onModify(dt)` - Called when the System is modified by
+-- adding or removing Entities from the System.
 --
 -- For Filters, it is convenient to use `tiny.requireAll` or `tiny.requireAny`,
 -- but one can write their own filters as well. Set the Filter of a System like
@@ -201,11 +201,17 @@ end
 -- system is added to the World. A few are important, and few should be less
 -- commonly used.
 --
+--   * The `world` field points to the World that the System belongs to. Useful
+-- for adding and removing Entities from the world dynamically via the System.
 --   * The `active` flag is whether or not the System is updated automatically.
 -- Inactive Systems should be updated manually or not at all via
 -- `system:update(dt)`. Defaults to true.
 --   * The 'entities' field is an ordered list of Entities in the System. This
 -- list can be used to quickly iterate through all Entities in a System.
+--   * The `interval` field is an optional field that makes Systems update at
+-- certain intervals using buffered time, regardless of World update frequency.
+-- For example, to make a System update once a second, set the System's interval
+-- to 1.
 --   * The `indices` field is a table of Entity keys to their indices in the
 -- `entities` list. Most Systems can ignore this.
 --   * The `modified` flag is an indicator if the System has been modified in
@@ -219,20 +225,11 @@ end
 -- this key is considered a System rather than an Entity.
 local systemTableKey = { "SYSTEM_TABLE_KEY" }
 
--- Check if tables are systems.
+-- Checks if a table is a System.
 local function isSystem(table)
     return table[systemTableKey]
 end
 
---- Creates a default System.
--- @param table A table to be used as a System, or `nil` to create a new System.
--- @return A new System or System class
-function tiny.system(table)
-    table = table or {}
-    table[systemTableKey] = true
-    return table
-end
-
 -- Update function for all Processing Systems.
 local function processingSystemUpdate(system, dt)
     local entities = system.entities
@@ -258,24 +255,45 @@ local function processingSystemUpdate(system, dt)
     end
 end
 
---- Creates a Processing System.
+-- Sorts Systems by a function system.sort(entity1, entity2) on modify.
---
+local function sortedSystemOnModify(system, dt)
--- A Processing System iterates through its Entities in no particluar order, and
+    local entities = system.entities
--- updates them individually. It has two important fields:
+    local indices = system.indices
---
+    local sortDelegate = system.sortDelegate
---   * `function system:process(entity, dt)`
+    if not sortDelegate then
---   * `function system:filter(entity)`
+        local compare = system.compare
---
+        sortDelegate = function(e1, e2)
--- There are also a few other optional callbacks, including the optional
+            return compare(system, e1, e2)
--- callbacks in `tiny.system`:
+        end
---
+        system.sortDelegate = sortDelegate
---   * `function system:preProcess(entities, dt)`
+    end
---   * `function system:postProcess(entities, dt)`
+    tsort(entities, sortDelegate)
---
+    for i = 1, #entities do
--- @param table A table to be used as a System, or `nil` to create a new
+        local entity = entities[i]
--- Processing System.
+        indices[entity] = i
+    end
+end
+
+--- Creates a new System or System class from the supplied table. If `table` is
+-- nil, creates a new table.
+function tiny.system(table)
+    table = table or {}
+    table[systemTableKey] = true
+    return table
+end
+
+--- Creates a new Processing System or Processing System class. Processing
+-- Systems process each entity individual, and are usually what is needed.
+-- Processing Systems have three extra callbacks besides those inheritted from
+-- vanilla Systems.
+--     * `function system:preProcess(entities, dt)` - Called before iterating
+-- over each Entity.
+--     * `function system:process(entities, dt)` - Called for each Entity in
+-- the System.
+--     * `function system:postProcess(entity, dt)` - Called after iteration.
+-- Processing Systems have their own `update` method, so don't implement a
+-- a custom `update` callback for Processing Systems.
 -- @see system
--- @return A new Processing System or Processing System class
 function tiny.processingSystem(table)
     table = table or {}
     table[systemTableKey] = true
@@ -283,45 +301,31 @@ function tiny.processingSystem(table)
     return table
 end
 
--- Sorts Systems by a function system.sort(entity1, entity2) on modify.
+--- Creates a new Sorted System or Sorted System class. Sorted Systems sort
-local function sortedSystemOnModify(system, dt)
+-- their Entities according to a user-defined method, `system:compare(e1, e2)`,
-    local entities = system.entities
+-- which should return true if `e1` should come before `e2` and false otherwise.
-    local entityIndices = system.entityIndices
+-- Sorted Systems also override the default System's `onModify` callback, so be
-    local sortDelegate = system.sortDelegate
+-- careful if defining a custom callback. However, for processing the sorted
-    if not sortDelegate then
+-- entities, consider `tiny.sortedProcessingSystem(table)`.
-        local compare = system.compare
+-- @see system
-        sortDelegate = function(e1, e2)
+function tiny.sortedSystem(table)
-            compare(system, e1, e2)
+    table = table or {}
-        end
+    table[systemTableKey] = true
-        system.sortDelegate = sortDelegate
+    table.onModify = sortedSystemOnModify
-    end
+    return table
-    tsort(entities, sortDelegate)
-    for i = 1, #entities do
-        local entity = entities[i]
-        entityIndices[entity] = i
-    end
 end
 
---- Creates a Sorted Processing System. A Sorted System iterates through its
+--- Creates a new Sorted Processing System or Sorted Processing System class.
--- Entities in a specific order, and updates them individually. It has three
+-- Sorted Processing Systems have both the aspects of Processing Systems and
--- important methods:
+-- Sorted Systems.
---
---   * `function system:process(entity, dt)`
---   * `function system:compare(entity1, entity2)`
---   * `function system:filter(entity)`
---
--- Sorted Systems have the same optitonal callbacks as ProcessingSystems.
--- @param table A table to be used as a System, or `nil` to create a new
--- Sorted System.
 -- @see system
 -- @see processingSystem
--- @return A new Sorted System or Sorted System class
+-- @see sortedSystem
-function tiny.sortedSystem(table)
+function tiny.sortedProcessingSystem(table)
     table = table or {}
     table[systemTableKey] = true
     table.update = processingSystemUpdate
     table.onModify = sortedSystemOnModify
-    table.sort = sortedSystemOnModify
     return table
 end
 
@@ -339,10 +343,7 @@ local worldMetaTable
 
 --- 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
@@ -376,14 +377,11 @@ function tiny.world(...)
     tiny_manageEntities(ret)
 
     return setmetatable(ret, worldMetaTable)
-
 end
 
 --- Adds an Entity to the world.
 -- Also call this on Entities that have changed Components such that they
 -- match different Filters.
--- @param world
--- @param entity
 function tiny.addEntity(world, entity)
     local e2a = world.entitiesToAdd
     e2a[#e2a + 1] = entity
@@ -394,8 +392,6 @@ end
 tiny_addEntity = tiny.addEntity
 
 --- Adds a System to the world.
--- @param world
--- @param system
 function tiny.addSystem(world, system)
     local s2a = world.systemsToAdd
     s2a[#s2a + 1] = system
@@ -403,10 +399,6 @@ end
 tiny_addSystem = tiny.addSystem
 
 --- Shortcut for adding multiple Entities and Systems to the World.
--- @param world
--- @param ... Systems and Entities
--- @see addEntity
--- @see addSystem
 function tiny.add(world, ...)
     local obj
     for i = 1, select("#", ...) do
@@ -423,8 +415,6 @@ end
 tiny_add = tiny.add
 
 --- Removes an Entity to the World.
--- @param world
--- @param entity
 function tiny.removeEntity(world, entity)
     local e2r = world.entitiesToRemove
     e2r[#e2r + 1] = entity
@@ -432,8 +422,6 @@ end
 tiny_removeEntity = tiny.removeEntity
 
 --- Removes a System from the world.
--- @param world
--- @param system
 function tiny.removeSystem(world, system)
     local s2r = world.systemsToRemove
     s2r[#s2r + 1] = system
@@ -441,10 +429,6 @@ end
 tiny_removeSystem = tiny.removeSystem
 
 --- Shortcut for removing multiple Entities and Systems from the World.
--- @param world
--- @param ... Systems and Entities
--- @see removeEntity
--- @see removeSystem
 function tiny.remove(world, ...)
     local obj
     for i = 1, select("#", ...) do
@@ -462,7 +446,6 @@ tiny_remove = tiny.remove
 
 -- Adds and removes Systems that have been marked from the World.
 function tiny_manageSystems(world)
-
         local s2a, s2r = world.systemsToAdd, world.systemsToRemove
 
         -- Early exit
@@ -495,6 +478,11 @@ function tiny_manageSystems(world)
                 end
             end
             s2r[i] = nil
+
+            -- Clean up System
+            system.world = nil
+            system.entities = nil
+            system.indices = nil
         end
 
         -- Add Systems
@@ -505,8 +493,11 @@ function tiny_manageSystems(world)
                 entityIndices = {}
                 system.entities = entityList
                 system.indices = entityIndices
+                if system.active == nil then
                     system.active = true
+                end
                 system.modified = true
+                system.world = world
                 index = #systems + 1
                 systemIndices[system] = index
                 systems[index] = system
@@ -529,12 +520,10 @@ function tiny_manageSystems(world)
             end
             s2a[i] = nil
         end
-
 end
 
 -- Adds and removes Entities that have been marked.
 function tiny_manageEntities(world)
-
     local e2a, e2r = world.entitiesToAdd, world.entitiesToRemove
 
     -- Early exit
@@ -580,7 +569,6 @@ function tiny_manageEntities(world)
         e2r[i] = nil
     end
 
-
     -- Add Entities
     for i = 1, #e2a do
         entity = e2a[i]
@@ -612,25 +600,24 @@ function tiny_manageEntities(world)
 
     -- Update Entity count
     world.entityCount = entityCount
-
 end
 
---- Updates the World.
+--- Updates the World by dt (delta time). Takes an optional parameter, `filter`,
--- Put this in your main loop.
+-- which is a Filter that selects Systems from the World, and updates only those
--- @param world
+-- Systems. If `filter` is not supplied, all Systems are updated. Put this
--- @param dt Delta time
+-- function in your main loop.
-function tiny.update(world, dt)
+function tiny.update(world, dt, filter)
 
     tiny_manageSystems(world)
     tiny_manageEntities(world)
 
     local systems = world.systems
-    local system, update, onModify, entities
+    local system, update, interval, onModify
 
     --  Iterate through Systems IN ORDER
     for i = 1, #systems do
         system = systems[i]
-        if system.active then
+        if system.active and ((not filter) or filter(world, system)) then
 
             -- Call the modify callback on Systems that have been modified.
             onModify = system.onModify
@@ -641,8 +628,20 @@ function tiny.update(world, dt)
             --Update Systems that have an update method (most Systems)
             update = system.update
             if update then
+                interval = system.interval
+                if interval then
+                    local bufferedTime = (system.bufferedTime or 0) + dt
+                    while bufferedTime >= interval do
+                        bufferedTime = bufferedTime - interval
+                        if update then
+                            update(system, interval)
+                        end
+                    end
+                    system.bufferedTime = bufferedTime
+                else
                     update(system, dt)
                 end
+            end
 
             system.modified = false
         end
@@ -650,7 +649,6 @@ function tiny.update(world, dt)
 end
 
 --- Removes all Entities from the World.
--- @param world
 function tiny.clearEntities(world)
     for e in pairs(world.entities) do
         tiny_removeEntity(world, e)
@@ -658,7 +656,6 @@ function tiny.clearEntities(world)
 end
 
 --- Removes all Systems from the World.
--- @param world
 function tiny.clearSystems(world)
     local systems = world.systems
     for i = #systems, 1, -1 do
@@ -667,35 +664,24 @@ function tiny.clearSystems(world)
 end
 
 --- Gets number of Entities in the World.
--- @param world
--- @return An integer
 function tiny.getEntityCount(world)
     return world.entityCount
 end
 
 --- Gets number of Systems in World.
--- @param world
--- @return An integer
 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
--- @return An integer between 1 and world:getSystemCount() inclusive
 function tiny.getSystemIndex(world, system)
     return world.systemIndices[system]
 end
 
---- Sets the index of a System in the World. Changes the order in
+--- Sets the index of a System in the World, and returns the old index. Changes
--- which they Systems processed, because lower indexed Systems are processed
+-- the order in which they Systems processed, because lower indexed Systems are
--- first.
+-- processed first.
--- @param world
--- @param system
--- @param index
--- @return Old index
 function tiny.setSystemIndex(world, system, index)
     local systemIndices = world.systemIndices
     local oldIndex = systemIndices[system]
@@ -720,6 +706,7 @@ worldMetaTable = {
         addSystem = tiny.addSystem,
         remove = tiny.remove,
         removeEntity = tiny.removeEntity,
+        removeSystem = tiny.removeSystem,
         update = tiny.update,
         clearEntities = tiny.clearEntities,
         clearSystems = tiny.clearSystems,