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,13 +1,20 @@
 # 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.
 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](http://en.wikipedia.org/wiki/Entity_component_system "Wikipedia").
 
-Tiny-ecs also works well with Objected Oriented programming in lua because
+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 +36,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 +71,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 +80,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
@@ -81,11 +88,6 @@ Tiny-ecs uses [busted](http://olivinelabs.com/busted/) for testing. Install and
 
 ## Documentation ##
 See API [here](http://bakpakin.github.io/tiny-ecs/doc/).
-Documentation can be generated locally with [LDoc](http://stevedonovan.github.io/ldoc/).
-
-## TODO ##
-
-* More testing
-* Performance testing / optimization
-* Add more System types
-* Improve Documentation
+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).

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-2.rockspec

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

rockspecs/tiny-ecs-1.1-5.rockspec

@@ -0,0 +1,24 @@
+package = "tiny-ecs"
+version = "1.1-5"
+source = {
+    url = "git://github.com/bakpakin/tiny-ecs",
+    tag = "1.1-5"
+}
+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-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)
@@ -56,7 +61,14 @@ describe('tiny-ecs:', function()
             local ftap = tiny.requireAll("spinalTap")
             local fvel = tiny.requireAll("vel")
             local fxform = tiny.requireAll("xform")
-            local fall = tiny.requireOne("spinalTap", "onlyTen", "littleMan")
+            local fall = tiny.requireAny("spinalTap", "onlyTen", "littleMan")
+
+            -- Only select Entities without "spinalTap"
+            local frtap = tiny.rejectAny("spinalTap")
+
+            -- Select Entities without all three: "spinalTap", "onlyTen", and
+            -- "littleMan"
+            local frall = tiny.rejectAll("spinalTap", "onlyTen", "littleMan")
 
             assert.truthy(fall(nil, entity1))
             assert.truthy(ftap(nil, entity1))
@@ -68,6 +80,14 @@ describe('tiny-ecs:', function()
             assert.truthy(fall(nil, entity2))
             assert.truthy(fall(nil, entity3))
 
+            assert.falsy(frtap(nil, entity1))
+            assert.truthy(frtap(nil, entity2))
+            assert.truthy(frtap(nil, entity3))
+
+            assert.truthy(frall(nil, entity1))
+            assert.truthy(frall(nil, entity2))
+            assert.truthy(frall(nil, entity3))
+
         end)
 
     end)
@@ -100,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)
@@ -176,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())
@@ -186,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())
@@ -196,10 +221,27 @@ describe('tiny-ecs:', function()
             world:update(1)
             world:setSystemIndex(moveSystem, 2)
             world:update(1)
-            assert.equals(2, world:getSystemIndex(moveSystem))
-            assert.equals(1, world:getSystemIndex(oneTimeSystem))
+            assert.equals(2, moveSystem.index)
+            assert.equals(1, oneTimeSystem.index)
         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)
+
+    it("Doesn't pollute the global namespace", function()
+        assert.are.same(_G, GLOBALS)
     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,16 +23,16 @@ 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-1" }
+local tiny = { _VERSION = "1.2-1" }
 
 -- 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
 
 -- Local versions of the library functions
 local tiny_manageEntities
@@ -50,11 +50,11 @@ 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.requireOne` are immutable
--- and can be used by multiple Systems.
+-- Filter's returned by tiny-ecs's Filter functions are immutable and can be
+-- used by multiple Systems.
 --
 --    local f1 = tiny.requireAll("position", "velocity", "size")
---    local f2 = tiny.requireOne("position", "velocity", "size")
+--    local f2 = tiny.requireAny("position", "velocity", "size")
 --
 --    local e1 = {
 --        position = {2, 3},
@@ -75,11 +75,18 @@ local tiny_remove
 --    print(f1(nil, e1), f1(nil, e2), f1(nil, e3)) -- prints true, false, false
 --    print(f2(nil, e1), f2(nil, e2), f2(nil, e3)) -- prints true, true, true
 --
+-- Filters can also be passed as arguments to other Filter constructors. This is
+-- a powerful way to create complex, custom Filters that select a very specific
+-- set of Entities.
+--
+--    -- Selects Entities with an "image" Component, but not Entities with a
+--    -- "Player" or "Enemy" Component.
+--    filter = tiny.requireAll("image", tiny.rejectAny("Player", "Enemy"))
+--
 -- @section Filter
 
 --- 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
@@ -101,8 +108,7 @@ 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.requireOne(...)
+function tiny.requireAny(...)
     local components = {...}
     local len = #components
     return function(system, e)
@@ -121,63 +127,131 @@ function tiny.requireOne(...)
     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]
+--- Makes a Filter that rejects Entities with all specified Components and
+-- Filters, and selects all other Entities.
+function tiny.rejectAll(...)
+    local components = {...}
+    local len = #components
+    return function(system, e)
+        local c
+        for i = 1, len do
+            c = components[i]
+            if type(c) == 'function' then
+                if not c(system, e) then
+                    return true
+                end
+            elseif e[c] == nil then
+                return true
+            end
+        end
+        return false
+    end
 end
 
---- Creates a System. Systems are tables that contain at least one method;
+--- Makes a Filter that rejects Entities with at least one of the specified
+-- Components and Filters, and selects all other Entities.
+function tiny.rejectAny(...)
+    local components = {...}
+    local len = #components
+    return function(system, e)
+        local c
+        for i = 1, len do
+            c = components[i]
+            if type(c) == 'function' then
+                if c(system, e) then
+                    return false
+                end
+            elseif e[c] ~= nil then
+                return false
+            end
+        end
+        return true
+    end
+end
+
+--- System functions.
+-- A System is a wrapper around function callbacks for manipulating Entities.
+-- Systems are implemented as tables that contain at least one method;
 -- an update function that takes parameters like so:
 --
 --   * `function system:update(dt)`.
 --
 -- There are also a few other optional callbacks:
 --
---   * `function system:filter(entity)`
---   * `function system:onAdd(entity)`
---   * `function system:onRemove(entity)`
---   * `function system:onModify(dt)`
+--   * `function system:filter(entity)` - Returns true if this System should
+-- include this Entity, otherwise should return false. If this isn't specified,
+-- no Entities are included in the System.
+--   * `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.
+--   * `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 conveient to use `tiny.requireAll` or `tiny.requireOne`,
--- but one can write their own filters as well. Set the Filter of your System
--- like so:
+-- 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
+-- so:
 --    system.filter = tiny.requireAll("a", "b", "c")
 -- or
 --    function system:filter(entity)
 --        return entity.myRequiredComponentName ~= nil
 --    end
 --
--- @param table A table to be used as a System, or `nil` to create a new System.
-function tiny.system(table)
-    table = table or {}
-    table[systemTableKey] = true
-    return table
+-- All Systems also have a few important fields that are initialized when the
+-- 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 `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
+-- the last update. If so, the `onModify` callback will be called on the System
+-- in the next update, if it has one. This is usually managed by tiny-ecs, so
+-- users should mostly ignore this, too.
+--
+-- @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" }
+
+-- Checks if a table is a System.
+local function isSystem(table)
+    return table[systemTableKey]
 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
@@ -187,22 +261,44 @@ 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)
+    local entities = system.entities
+    local indices = system.indices
+    local sortDelegate = system.sortDelegate
+    if not sortDelegate then
+        local compare = system.compare
+        sortDelegate = function(e1, e2)
+            return compare(system, e1, e2)
+        end
+        system.sortDelegate = sortDelegate
+    end
+    tsort(entities, sortDelegate)
+    for i = 1, #entities do
+        local entity = entities[i]
+        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.
 --
--- A Processing System iterates through its Entities in no particluar order, and
--- updates them individually. It has two important fields:
+--     function system:preProcess(dt) -- Called before iteration.
+--     function system:process(entity, dt) -- Process each entity.
+--     function system:postProcess(dt) -- Called after iteration.
 --
---   * `function system:process(entity, dt)`
---   * `function system:filter(entity)`
---
--- There are also a few other optional callbacks, including the optional
--- callbacks in `tiny.system`:
---
---   * `function system:preProcess(entities, dt)`
---   * `function system:postProcess(entities, dt)`
---
--- @param table A table to be used as a System, or `nil` to create a new
--- Processing System.
+-- Processing Systems have their own `update` method, so don't implement a
+-- a custom `update` callback for Processing Systems.
 -- @see system
 function tiny.processingSystem(table)
     table = table or {}
@@ -211,44 +307,31 @@ function tiny.processingSystem(table)
     return table
 end
 
--- Sorts Systems by a function system.sort(entity1, entity2) on modify.
-local function sortedSystemOnModify(system, dt)
-    local entities = system.entities
-    local entityIndices = system.entityIndices
-    local sortDelegate = system.sortDelegate
-    if not sortDelegate then
-        local compare = system.compare
-        sortDelegate = function(e1, e2)
-            compare(system, e1, e2)
-        end
-        system.sortDelegate = sortDelegate
-    end
-    tsort(entities, sortDelegate)
-    for i = 1, #entities do
-        local entity = entities[i]
-        entityIndices[entity] = i
-    end
+--- Creates a new Sorted System or Sorted System class. Sorted Systems sort
+-- their Entities according to a user-defined method, `system:compare(e1, e2)`,
+-- which should return true if `e1` should come before `e2` and false otherwise.
+-- Sorted Systems also override the default System's `onModify` callback, so be
+-- careful if defining a custom callback. However, for processing the sorted
+-- entities, consider `tiny.sortedProcessingSystem(table)`.
+-- @see system
+function tiny.sortedSystem(table)
+    table = table or {}
+    table[systemTableKey] = true
+    table.onModify = sortedSystemOnModify
+    return table
 end
 
---- Creates a Sorted Processing System. A Sorted System iterates through its
--- Entities in a specific order, and updates them individually. It has three
--- important methods:
---
---   * `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.
+--- Creates a new Sorted Processing System or Sorted Processing System class.
+-- Sorted Processing Systems have both the aspects of Processing Systems and
+-- Sorted Systems.
 -- @see system
 -- @see processingSystem
-function tiny.sortedSystem(table)
+-- @see sortedSystem
+function tiny.sortedProcessingSystem(table)
     table = table or {}
     table[systemTableKey] = true
     table.update = processingSystemUpdate
     table.onModify = sortedSystemOnModify
-    table.sort = sortedSystemOnModify
     return table
 end
 
@@ -256,21 +339,19 @@ end
 -- A World is a container that manages Entities and Systems. Typically, a
 -- program uses one World at a time.
 --
--- 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).`
+-- For all World functions except `tiny.world(...)`, object-oriented syntax can
+-- be used instead of the documented syntax. For example,
+-- `tiny.add(world, e1, e2, e3)` is the same as `world:add(e1, e2, e3)`.
 -- @section World
 
-local worldMetaTable = { __index = tiny }
+-- Forward declaration
+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
+-- 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 = {},
@@ -278,6 +359,9 @@ function tiny.world(...)
         -- List of Entities to remove
         entitiesToRemove = {},
 
+        -- List of Entities to change
+        entitiesToChange = {},
+
         -- List of Entities to add
         systemsToAdd = {},
 
@@ -287,103 +371,98 @@ 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
-        -- keys: system, indices, entities, and active.
-        systems = {},
-
-        -- Table of Systems to System Indices
-        systemIndices = {}
-    }
+        -- List of Systems
+        systems = {}
+    }, worldMetaTable)
 
     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.
--- @param world
--- @param entity
+-- 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.
--- @param world
--- @param system
+--- 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.
--- @param world
--- @param ... Systems and Entities
--- @see addEntity
--- @see addSystem
+--- Shortcut for adding multiple Entities and Systems to the World. Returns all
+-- added Entities and Systems.
 function tiny.add(world, ...)
-    local args = {...}
-    for _, obj in ipairs(args) do
+    for i = 1, select("#", ...) do
+        local obj = select(i, ...)
+        if obj then
             if isSystem(obj) then
                 tiny_addSystem(world, obj)
             else -- Assume obj is an Entity
                 tiny_addEntity(world, obj)
             end
         end
+    end
+    return ...
 end
 tiny_add = tiny.add
 
---- Removes an Entity to the World.
--- @param world
--- @param entity
+--- 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.
--- @param world
--- @param system
+--- 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.
--- @param world
--- @param ... Systems and Entities
--- @see removeEntity
--- @see removeSystem
+--- Shortcut for removing multiple Entities and Systems from the World. Returns
+-- all removed Systems and Entities
 function tiny.remove(world, ...)
-    local args = {...}
-    for _, obj in ipairs(args) do
+    for i = 1, select("#", ...) do
+        local obj = select(i, ...)
+        if obj then
             if isSystem(obj) then
                 tiny_removeSystem(world, obj)
             else -- Assume obj is an Entity
                 tiny_removeEntity(world, obj)
             end
         end
+    end
+    return ...
 end
 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
@@ -391,54 +470,68 @@ 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]
-            index = systemIndices[system]
-            if index then
-                onRemove = system.onRemove
+        local system = s2r[i]
+        local index = system.index
+        local 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
+
+        -- Clean up System
+        system.world = nil
+        system.entities = nil
+        system.indices = nil
+        system.index = nil
     end
 
     -- Add Systems
     for i = 1, #s2a do
-            system = s2a[i]
-            if not systemIndices[system] then
-                entityList = {}
-                entityIndices = {}
+        local system = s2a[i]
+        if systems[system.index] ~= system then
+            local entityList = {}
+            local entityIndices = {}
             system.entities = entityList
             system.indices = entityIndices
+            if system.active == nil then
                 system.active = true
+            end
             system.modified = true
-                index = #systems + 1
-                systemIndices[system] = index
+            system.world = world
+            local index = #systems + 1
+            system.index = index
             systems[index] = system
+            local onAddToWorld = system.onAddToWorld
+            if onAddToWorld then
+                onAddToWorld(system, world)
+            end
 
             -- Try to add Entities
-                onAdd = system.onAdd
-                filter = system.filter
+            local onAdd = system.onAdd
+            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
@@ -450,120 +543,171 @@ function tiny_manageSystems(world)
         end
         s2a[i] = nil
     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
-    for i = 1, #e2r do
-        entity = e2r[i]
+    -- Change Entities
+    for i = 1, #e2c do
+        local entity = e2c[i]
         if entities[entity] then
-            entities[entity] = nil
-
             for j = 1, #systems do
-                system = systems[j]
-                ses = system.entities
-                seis = system.indices
-                index = seis[entity]
-
-                if index then
-                    system.modified = true
-                    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
-                system = systems[j]
-                ses = system.entities
-                seis = system.indices
-                filter = system.filter
+                local system = systems[j]
+                local ses = system.entities
+                local seis = system.indices
+                local index = seis[entity]
+                local filter = system.filter
                 if filter and filter(system, entity) then
+                    if not index then
                         system.modified = true
                         index = #ses + 1
                         ses[index] = entity
                         seis[entity] = index
-                    entityCount = entityCount + 1
-                    onAdd = system.onAdd
+                        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
+                    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
+        local entity = e2a[i]
+        if not entities[entity] then
+            entities[entity] = true
+            entityCount = entityCount + 1
+            for j = 1, #systems do
+                local system = systems[j]
+                local ses = system.entities
+                local seis = system.indices
+                local filter = system.filter
+                if filter and filter(system, entity) then
+                    system.modified = true
+                    local index = #ses + 1
+                    ses[index] = entity
+                    seis[entity] = index
+                    local onAdd = system.onAdd
+                    if onAdd then
+                        onAdd(system, entity)
+                    end
+                end
+            end
         end
         e2a[i] = nil
     end
 
     -- Update Entity count
     world.entityCount = entityCount
-
 end
 
---- Updates the World.
--- Put this in your main loop.
--- @param world
--- @param dt Delta time
-function tiny.update(world, dt)
+--- 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
+-- function in your main loop.
+function tiny.update(world, dt, filter)
 
     tiny_manageSystems(world)
     tiny_manageEntities(world)
 
     local systems = world.systems
-    local system, update, onModify, entities
 
     --  Iterate through Systems IN ORDER
     for i = 1, #systems do
-        system = systems[i]
-        if system.active then
+        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 = system.update
+            -- Update Systems that have an update method (most Systems)
+            local update = system.update
             if update then
+                local 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
@@ -571,7 +715,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)
@@ -579,7 +722,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
@@ -587,44 +729,64 @@ function tiny.clearSystems(world)
     end
 end
 
---- Gets count of Entities in World.
--- @param world
+--- Gets number of Entities in the World.
 function tiny.getEntityCount(world)
     return world.entityCount
 end
 
---- Gets count of Systems in World.
--- @param world
+--- Gets number of Systems in 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
+--- Gets the index of the System in the World.
+-- 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. Changes the order in
--- which they Systems processed, because lower indexed Systems are processed
--- first.
--- @param world
--- @param system
--- @param index
+--- 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. Returns the old system.index.
 function tiny.setSystemIndex(world, system, index)
-    local systemIndices = world.systemIndices
-    local oldIndex = systemIndices[system]
+    local oldIndex = system.index
     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
 end
 
+-- Construct world metatable.
+worldMetaTable = {
+    __index = {
+        add = tiny.add,
+        addEntity = tiny.addEntity,
+        addSystem = tiny.addSystem,
+        remove = tiny.remove,
+        removeEntity = tiny.removeEntity,
+        removeSystem = tiny.removeSystem,
+        refresh = tiny.refresh,
+        update = tiny.update,
+        clearEntities = tiny.clearEntities,
+        clearSystems = tiny.clearSystems,
+        getEntityCount = tiny.getEntityCount,
+        getSystemCount = tiny.getSystemCount,
+        getSystemIndex = tiny.getSystemIndex,
+        setSystemIndex = tiny.setSystemIndex
+    },
+    __tostring = function(self)
+        return "<tiny-ecs_World>"
+    end
+}
+
 return tiny