Release version 1.2-1.

Remove useless code in world metatable
Make tiny.world(...) return newworld, ...

.travis.yml

@@ -0,0 +1,39 @@
+language: erlang
+
+env:
+  global:
+    - LUAROCKS_BASE=luarocks-2.2.2
+  matrix:
+    - LUA=lua5.1 LUA_DEV=liblua5.1-dev LUA_VER=5.1 LUA_SFX=5.1 LUA_INCDIR=/usr/include/lua5.1
+    - LUA=lua5.2 LUA_DEV=liblua5.2-dev LUA_VER=5.2 LUA_SFX=5.2 LUA_INCDIR=/usr/include/lua5.2
+    - LUA=luajit LUA_DEV=libluajit-5.1-dev LUA_VER=5.1 LUA_SFX=jit LUA_INCDIR=/usr/include/luajit-2.0
+
+before_install:
+  - if [ $LUA = "luajit" ]; then
+      sudo add-apt-repository ppa:mwild1/ppa -y && sudo apt-get update -y;
+      sudo apt-get install lua5.1;
+      sudo apt-get install liblua5.1-dev;
+    fi
+  - sudo apt-get install $LUA
+  - sudo apt-get install $LUA_DEV
+  - lua$LUA_SFX -v
+  # Install a recent luarocks release
+  - wget http://luarocks.org/releases/$LUAROCKS_BASE.tar.gz
+  - tar zxvpf $LUAROCKS_BASE.tar.gz
+  - cd $LUAROCKS_BASE
+  - ./configure
+    --lua-version=$LUA_VER --lua-suffix=$LUA_SFX --with-lua-include="$LUA_INCDIR"
+  - sudo make
+  - sudo make install
+  - cd $TRAVIS_BUILD_DIR
+
+install:
+  - sudo -E luarocks install busted
+
+script:
+  - sudo -E busted -v
+
+notifications:
+  email:
+    on_success: change
+    on_failure: always

README.md

@@ -1,5 +1,7 @@
 # tiny-ecs #
 
+[![Build Status](https://travis-ci.org/bakpakin/tiny-ecs.png?branch=master)](https://travis-ci.org/bakpakin/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.

rockspecs/tiny-ecs-1.1-6.rockspec

@@ -0,0 +1,24 @@
+package = "tiny-ecs"
+version = "1.1-6"
+source = {
+    url = "git://github.com/bakpakin/tiny-ecs",
+    tag = "1.1-6"
+}
+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-7.rockspec

@@ -0,0 +1,24 @@
+package = "tiny-ecs"
+version = "1.1-7"
+source = {
+    url = "git://github.com/bakpakin/tiny-ecs",
+    tag = "1.1-7"
+}
+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.2-1.rockspec

@@ -0,0 +1,24 @@
+package = "tiny-ecs"
+version = "1.2-1"
+source = {
+    url = "git://github.com/bakpakin/tiny-ecs",
+    tag = "1.2-1"
+}
+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

@@ -1,3 +1,8 @@
+local GLOBALS = {}
+for k, v in pairs(_G) do
+    GLOBALS[k] = v
+end
+
 local tiny = require "tiny"
 
 local function deep_copy(x)
@@ -115,6 +120,11 @@ describe('tiny-ecs:', function()
             timePassed = 0
         end)
 
+        after_each(function()
+            world:clearSystems()
+            world:refresh()
+        end)
+
         it("Create World", function()
             assert.equals(world:getEntityCount(), 3)
             assert.equals(world:getSystemCount(), 2)
@@ -191,7 +201,7 @@ describe('tiny-ecs:', function()
 
         it("Add Systems Multiple Times", function()
             world:update(1)
-            world:add(moveSystem, oneTimeSystem)
+            assert.has_error(function() world:add(moveSystem, oneTimeSystem) end, "System already belongs to a World.")
             world:update(2)
             assert.equals(2, world:getSystemCount())
             assert.equals(3, world:getEntityCount())
@@ -201,7 +211,7 @@ describe('tiny-ecs:', function()
             world:update(1)
             world:remove(moveSystem)
             world:update(2)
-            world:remove(moveSystem)
+            assert.has_error(function() world:remove(moveSystem) end, "System does not belong to this World.")
             world:update(2)
             assert.equals(1, world:getSystemCount())
             assert.equals(3, world:getEntityCount())
@@ -211,8 +221,8 @@ describe('tiny-ecs:', function()
             world:update(1)
             world:setSystemIndex(moveSystem, 2)
             world:update(1)
-            assert.equals(2, world:getSystemIndex(moveSystem))
+            assert.equals(2, moveSystem.index)
-            assert.equals(1, world:getSystemIndex(oneTimeSystem))
+            assert.equals(1, oneTimeSystem.index)
         end)
 
         it("Sorts Entities in Sorting Systems", function()
@@ -230,4 +240,8 @@ describe('tiny-ecs:', function()
 
     end)
 
+    it("Doesn't pollute the global namespace", function()
+        assert.are.same(_G, GLOBALS)
+    end)
+
 end)

tiny.lua

@@ -23,7 +23,7 @@ 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-5" }
+local tiny = { _VERSION = "1.2-1" }
 
 -- Local versions of standard lua functions
 local tinsert = table.insert
@@ -187,6 +187,10 @@ end
 -- from the System.
 --   * `function system:onModify(dt)` - Called when the System is modified by
 -- adding or removing Entities from the System.
+--   * `function system:onAddToWorld(world)` - Called when the System is added
+-- to the World, before any entities are added to the system.
+--   * `function system:onRemoveFromWorld(world)` - Called when the System is
+-- removed from the world, after all Entities are removed 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
@@ -206,12 +210,15 @@ end
 --   * 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
+--   * 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 `index` field is the System's index in the World. Lower indexed
+-- Systems are processed before higher indices. The `index` is a read only
+-- field; to set the `index`, use `tiny.setSystemIndex(world, system)`.
 --   * 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
@@ -232,20 +239,19 @@ end
 
 -- Update function for all Processing Systems.
 local function processingSystemUpdate(system, dt)
-    local entities = system.entities
     local preProcess = system.preProcess
     local process = system.process
     local postProcess = system.postProcess
-    local entity
 
     if preProcess then
         preProcess(system, dt)
     end
 
     if process then
+        local entities = system.entities
         local len = #entities
         for i = 1, len do
-            entity = entities[i]
+            local entity = entities[i]
             process(system, entity, dt)
         end
     end
@@ -287,9 +293,9 @@ end
 -- Processing Systems have three extra callbacks besides those inheritted from
 -- vanilla Systems.
 --
---     function system:preProcess(entities, dt) -- Called before iteration.
+--     function system:preProcess(dt) -- Called before iteration.
---     function system:process(entities, dt) -- Process each entity.
+--     function system:process(entity, dt) -- Process each entity.
---     function system:postProcess(entity, dt) -- Called after iteration.
+--     function system:postProcess(dt) -- Called after iteration.
 --
 -- Processing Systems have their own `update` method, so don't implement a
 -- a custom `update` callback for Processing Systems.
@@ -342,9 +348,10 @@ end
 local worldMetaTable
 
 --- Creates a new World.
--- Can optionally add default Systems and Entities.
+-- Can optionally add default Systems and Entities. Returns the new World along
+-- with default Entities and Systems.
 function tiny.world(...)
-    local ret = {
+    local ret = setmetatable({
 
         -- List of Entities to add
         entitiesToAdd = {},
@@ -352,6 +359,9 @@ function tiny.world(...)
         -- List of Entities to remove
         entitiesToRemove = {},
 
+        -- List of Entities to change
+        entitiesToChange = {},
+
         -- List of Entities to add
         systemsToAdd = {},
 
@@ -361,48 +371,50 @@ function tiny.world(...)
         -- Set of Entities
         entities = {},
 
-        -- Number of Entities in World.
+        -- Number of Entities in World
         entityCount = 0,
 
-        -- List of System Data. A data element is a table with 4
+        -- List of Systems
-        -- keys: system, indices, entities, and active.
+        systems = {}
-        systems = {},
+    }, worldMetaTable)
-
-        -- Table of Systems to System Indices
-        systemIndices = {}
-    }
 
     tiny_add(ret, ...)
     tiny_manageSystems(ret)
     tiny_manageEntities(ret)
 
-    return setmetatable(ret, worldMetaTable)
+    return ret, ...
 end
 
 --- Adds an Entity to the world.
 -- Also call this on Entities that have changed Components such that they
--- match different Filters.
+-- match different Filters. Returns the Entity.
 function tiny.addEntity(world, entity)
+    if world.entities[entity] then
+        local e2c = world.entitiesToChange
+        e2c[#e2c + 1] = entity
+    else
         local e2a = world.entitiesToAdd
         e2a[#e2a + 1] = entity
-    if world.entities[entity] then
-        tiny_removeEntity(world, entity)
     end
+    return entity
 end
 tiny_addEntity = tiny.addEntity
 
---- Adds a System to the world.
+--- Adds a System to the world. Returns the System.
 function tiny.addSystem(world, system)
+    assert(system.world == nil, "System already belongs to a World.")
     local s2a = world.systemsToAdd
     s2a[#s2a + 1] = system
+    system.world = world
+    return system
 end
 tiny_addSystem = tiny.addSystem
 
---- Shortcut for adding multiple Entities and Systems to the World.
+--- Shortcut for adding multiple Entities and Systems to the World. Returns all
+-- added Entities and Systems.
 function tiny.add(world, ...)
-    local obj
     for i = 1, select("#", ...) do
-        obj = select(i, ...)
+        local obj = select(i, ...)
         if obj then
             if isSystem(obj) then
                 tiny_addSystem(world, obj)
@@ -411,28 +423,32 @@ function tiny.add(world, ...)
             end
         end
     end
+    return ...
 end
 tiny_add = tiny.add
 
---- Removes an Entity to the World.
+--- Removes an Entity to the World. Returns the Entity.
 function tiny.removeEntity(world, entity)
     local e2r = world.entitiesToRemove
     e2r[#e2r + 1] = entity
+    return entity
 end
 tiny_removeEntity = tiny.removeEntity
 
---- Removes a System from the world.
+--- Removes a System from the world. Returns the System.
 function tiny.removeSystem(world, system)
+    assert(system.world == world, "System does not belong to this World.")
     local s2r = world.systemsToRemove
     s2r[#s2r + 1] = system
+    return system
 end
 tiny_removeSystem = tiny.removeSystem
 
---- Shortcut for removing multiple Entities and Systems from the World.
+--- Shortcut for removing multiple Entities and Systems from the World. Returns
+-- all removed Systems and Entities
 function tiny.remove(world, ...)
-    local obj
     for i = 1, select("#", ...) do
-        obj = select(i, ...)
+        local obj = select(i, ...)
         if obj then
             if isSystem(obj) then
                 tiny_removeSystem(world, obj)
@@ -441,6 +457,7 @@ function tiny.remove(world, ...)
             end
         end
     end
+    return ...
 end
 tiny_remove = tiny.remove
 
@@ -453,29 +470,30 @@ function tiny_manageSystems(world)
         return
     end
 
-        local systemIndices = world.systemIndices
+    world.systemsToAdd = {}
+    world.systemsToRemove = {}
+
     local entities = world.entities
     local systems = world.systems
-        local system, index, filter
-        local entityList, entityIndices, entityIndex, onRemove, onAdd
 
     -- Remove Systems
     for i = 1, #s2r do
-            system = s2r[i]
+        local system = s2r[i]
-            index = systemIndices[system]
+        local index = system.index
-            if index then
+        local onRemove = system.onRemove
-                onRemove = system.onRemove
         if onRemove then
-                    entityList = system.entities
+            local entityList = system.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]] = j
+            systems[j].index = j
         end
+        local onRemoveFromWorld = system.onRemoveFromWorld
+        if onRemoveFromWorld then
+            onRemoveFromWorld(system, world)
         end
         s2r[i] = nil
 
@@ -483,14 +501,15 @@ function tiny_manageSystems(world)
         system.world = nil
         system.entities = nil
         system.indices = nil
+        system.index = nil
     end
 
     -- Add Systems
     for i = 1, #s2a do
-            system = s2a[i]
+        local system = s2a[i]
-            if not systemIndices[system] then
+        if systems[system.index] ~= system then
-                entityList = {}
+            local entityList = {}
-                entityIndices = {}
+            local entityIndices = {}
             system.entities = entityList
             system.indices = entityIndices
             if system.active == nil then
@@ -498,17 +517,21 @@ function tiny_manageSystems(world)
             end
             system.modified = true
             system.world = world
-                index = #systems + 1
+            local index = #systems + 1
-                systemIndices[system] = index
+            system.index = index
             systems[index] = system
+            local onAddToWorld = system.onAddToWorld
+            if onAddToWorld then
+                onAddToWorld(system, world)
+            end
 
             -- Try to add Entities
-                onAdd = system.onAdd
+            local onAdd = system.onAdd
-                filter = system.filter
+            local filter = system.filter
             if filter then
                 for entity in pairs(entities) do
                     if filter(system, entity) then
-                            entityIndex = #entityList + 1
+                        local entityIndex = #entityList + 1
                         entityList[entityIndex] = entity
                         entityIndices[entity] = entityIndex
                         if onAdd then
@@ -522,78 +545,114 @@ function tiny_manageSystems(world)
     end
 end
 
--- Adds and removes Entities that have been marked.
+-- Adds, removes, and changes Entities that have been marked.
 function tiny_manageEntities(world)
-    local e2a, e2r = world.entitiesToAdd, world.entitiesToRemove
+
+    local e2a = world.entitiesToAdd
+    local e2r = world.entitiesToRemove
+    local e2c = world.entitiesToChange
 
     -- Early exit
-    if #e2a == 0 and #e2r == 0 then
+    if #e2a == 0 and #e2r == 0 and #e2c == 0 then
         return
     end
 
+    world.entitiesToChange = {}
+    world.entitiesToAdd = {}
+    world.entitiesToRemove = {}
+
     local entities = world.entities
     local systems = world.systems
     local entityCount = world.entityCount
-    local entity, system, index
-    local onRemove, onAdd, ses, seis, filter, tmpEntity
 
-    -- Remove Entities
+    -- Change Entities
-    for i = 1, #e2r do
+    for i = 1, #e2c do
-        entity = e2r[i]
+        local entity = e2c[i]
         if entities[entity] then
-            entities[entity] = nil
-            entityCount = entityCount - 1
-
             for j = 1, #systems do
-                system = systems[j]
+                local system = systems[j]
-                ses = system.entities
+                local ses = system.entities
-                seis = system.indices
+                local seis = system.indices
-                index = seis[entity]
+                local index = seis[entity]
-
+                local filter = system.filter
-                if index then
+                if filter and filter(system, entity) then
+                    if not index then
                         system.modified = true
-                    tmpEntity = ses[#ses]
+                        index = #ses + 1
+                        ses[index] = entity
+                        seis[entity] = index
+                        local onAdd = system.onAdd
+                        if onAdd then
+                            onAdd(system, entity)
+                        end
+                    end
+                elseif index then
+                    system.modified = true
+                    local tmpEntity = ses[#ses]
                     ses[index] = tmpEntity
                     seis[tmpEntity] = index
                     seis[entity] = nil
                     ses[#ses] = nil
-                    onRemove = system.onRemove
+                    local onRemove = system.onRemove
                     if onRemove then
                         onRemove(system, entity)
                     end
                 end
-
+            end
+        end
+        e2c[i] = nil
     end
 
+    -- Remove Entities
+    for i = 1, #e2r do
+        local entity = e2r[i]
+        if entities[entity] then
+            entities[entity] = nil
+            entityCount = entityCount - 1
+            for j = 1, #systems do
+                local system = systems[j]
+                local ses = system.entities
+                local seis = system.indices
+                local index = seis[entity]
+                if index then
+                    system.modified = true
+                    local tmpEntity = ses[#ses]
+                    ses[index] = tmpEntity
+                    seis[tmpEntity] = index
+                    seis[entity] = nil
+                    ses[#ses] = nil
+                    local 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]
+        local entity = e2a[i]
         if not entities[entity] then
             entities[entity] = true
             entityCount = entityCount + 1
-
             for j = 1, #systems do
-                system = systems[j]
+                local system = systems[j]
-                ses = system.entities
+                local ses = system.entities
-                seis = system.indices
+                local seis = system.indices
-                filter = system.filter
+                local filter = system.filter
                 if filter and filter(system, entity) then
                     system.modified = true
-                    index = #ses + 1
+                    local index = #ses + 1
                     ses[index] = entity
                     seis[entity] = index
-                    onAdd = system.onAdd
+                    local onAdd = system.onAdd
                     if onAdd then
                         onAdd(system, entity)
                     end
                 end
-
             end
-
         end
         e2a[i] = nil
     end
@@ -602,6 +661,14 @@ function tiny_manageEntities(world)
     world.entityCount = entityCount
 end
 
+--- Manages Entities and Systems marked for deletion or addition. Call this
+-- before modifying Systems and Entities outside of a call to `tiny.update`.
+-- Do not call this within a call to `tiny.update`.
+function tiny.refresh(world)
+    tiny_manageSystems(world)
+    tiny_manageEntities(world)
+end
+
 --- Updates the World by dt (delta time). Takes an optional parameter, `filter`,
 -- which is a Filter that selects Systems from the World, and updates only those
 -- Systems. If `filter` is not supplied, all Systems are updated. Put this
@@ -612,23 +679,22 @@ function tiny.update(world, dt, filter)
     tiny_manageEntities(world)
 
     local systems = world.systems
-    local system, update, interval, onModify
 
     --  Iterate through Systems IN ORDER
     for i = 1, #systems do
-        system = systems[i]
+        local system = systems[i]
         if system.active and ((not filter) or filter(world, system)) then
 
             -- Call the modify callback on Systems that have been modified.
-            onModify = system.onModify
+            local onModify = system.onModify
             if onModify and system.modified then
                 onModify(system, dt)
             end
 
-            --Update Systems that have an update method (most Systems)
+            -- Update Systems that have an update method (most Systems)
-            update = system.update
+            local update = system.update
             if update then
-                interval = system.interval
+                local interval = system.interval
                 if interval then
                     local bufferedTime = (system.bufferedTime or 0) + dt
                     while bufferedTime >= interval do
@@ -673,26 +739,28 @@ function tiny.getSystemCount(world)
     return #(world.systems)
 end
 
---- Gets the index of a System in the World. Lower indexed Systems are processed
+--- Gets the index of the System in the World.
--- before higher indexed systems.
+-- A simpler alternative is `system.index`.
 function tiny.getSystemIndex(world, system)
-    return world.systemIndices[system]
+    return system.index
 end
 
 --- Sets the index of a System in the World, and returns the old index. Changes
 -- the order in which they Systems processed, because lower indexed Systems are
--- processed first.
+-- processed first. Returns the old system.index.
 function tiny.setSystemIndex(world, system, index)
-    local systemIndices = world.systemIndices
+    local oldIndex = system.index
-    local oldIndex = systemIndices[system]
     local systems = world.systems
-    local system = systems[oldIndex]
+
+    if index < 0 then
+        index = tiny.getSystemCount(world) + 1 + index
+    end
 
     tremove(systems, oldIndex)
     tinsert(systems, index, system)
 
     for i = oldIndex, index, index >= oldIndex and 1 or -1 do
-        systemIndices[systems[i]] = i
+        systems[i].index = i
     end
 
     return oldIndex
@@ -707,6 +775,7 @@ worldMetaTable = {
         remove = tiny.remove,
         removeEntity = tiny.removeEntity,
         removeSystem = tiny.removeSystem,
+        refresh = tiny.refresh,
         update = tiny.update,
         clearEntities = tiny.clearEntities,
         clearSystems = tiny.clearSystems,
@@ -714,7 +783,10 @@ worldMetaTable = {
         getSystemCount = tiny.getSystemCount,
         getSystemIndex = tiny.getSystemIndex,
         setSystemIndex = tiny.setSystemIndex
-    }
+    },
+    __tostring = function(self)
+        return "<tiny-ecs_World>"
+    end
 }
 
 return tiny