Update to version 1.1-6.

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

.gitignore

@@ -3,3 +3,6 @@ doc/*
 index.html
 ldoc.css
 topics/*
+
+#Ignore generated rocks
+*.rock

README.md

@@ -1,16 +1,18 @@
 # 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
-## Use It ##
+demo branch, specifically the systems and entities sub-directories.
-Copy paste tiny.lua into your source folder.
 
 ## Overview ##
 Tiny-ecs has four important types: Worlds, Filters, Systems, and Entities.
@@ -32,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,17 +66,26 @@ for i = 1, 20 do
 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 'scm'.
+
+## Luarocks ##
+Tiny-ecs is also on [Luarocks](https://luarocks.org/) and can be installed with
+`luarocks install tiny-ecs`.
+
+## 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
+[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
 `busted` from the command line to test.
 
 ## Documentation ##
 See API [here](http://bakpakin.github.io/tiny-ecs/doc/).
-Documentation can be generated locally with [LDoc](http://stevedonovan.github.io/ldoc/).
+For the most up-to-date documentation, read the source code, or generate the HTML
-
+locally with [LDoc](http://stevedonovan.github.io/ldoc/).
-## TODO ##
+See the original forum thread [here](https://love2d.org/forums/viewtopic.php?f=5&t=79937&p=182589).
-
-* More testing
-* Performance testing / optimization
-* Improve Documentation
-* Add more complete examples

config.ld

@@ -2,6 +2,12 @@ file = "tiny.lua"
 project = "tiny-ecs"
 description = "Entity Component System for lua."
 backtick_references = true
-one = false
+format = 'discount'
+title = "tiny-ecs API"
+one = true
 dir = doc
-sort = true
+style = '!fixed'
+package = 'tiny-ecs'
+not_luadoc = true
+boilerplate = true
+no_return_or_parms = true

rockspecs/tiny-ecs-1.0-2.rockspec

@@ -21,4 +21,4 @@ build = {
     modules = {
         tiny = "tiny.lua"
     }
-}
+}

rockspecs/tiny-ecs-1.1-1.rockspec

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

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"
+    }
+}

spec/tiny_spec.lua

@@ -1,24 +1,15 @@
 local tiny = require "tiny"
 
--- Taken from answer at http://stackoverflow.com/questions/640642/how-do-you-copy-a-lua-table-by-value
+local function deep_copy(x)
-local function deep_copy(o, seen)
+    if type(x) == 'table' then
-  seen = seen or {}
+        local nx = {}
-  if o == nil then return nil end
+        for k, v in next, x, nil do
-  if seen[o] then return seen[o] end
+            nx[deep_copy(k)] = deep_copy(v)
-
+        end
-  local no
+        return nx
-  if type(o) == 'table' then
+    else
-    no = {}
+        return x
-    seen[o] = no
-
-    for k, v in next, o, nil do
-      no[deep_copy(k, seen)] = deep_copy(v, seen)
     end
-    setmetatable(no, deep_copy(getmetatable(o), seen))
-  else -- number, string, boolean, etc
-    no = o
-  end
-  return no
 end
 
 local entityTemplate1 = {
@@ -65,7 +56,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))
@@ -77,6 +75,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)
@@ -97,9 +103,9 @@ describe('tiny-ecs:', function()
 
         local timePassed = 0
         local oneTimeSystem = tiny.system()
-        function oneTimeSystem:update(entities, dt)
+        function oneTimeSystem:update(dt)
             timePassed = timePassed + dt
-        end 
+        end
 
         before_each(function()
             entity1 = deep_copy(entityTemplate1)
@@ -138,15 +144,19 @@ describe('tiny-ecs:', function()
             assert.equals(0, world:getSystemCount())
         end)
 
-        it("Disable and Enable Systems", function()
+        it("Deactivate and Activate Systems", function()
-            world:deactivate(moveSystem, oneTimeSystem)
+            moveSystem.active = false
+            oneTimeSystem.active = false
             world:update(1)
+            assert.equals(world:getSystemCount(), 2)
             assert.equals(timePassed, 0)
             assert.equals(entity1.xform.x, entityTemplate1.xform.x)
-            world:activate(moveSystem, oneTimeSystem)
+            moveSystem.active = true
+            oneTimeSystem.active = true
             world:update(1)
             assert.equals(timePassed, 1)
             assert.are_not.equal(entity1.xform.x, entityTemplate1.xform.x)
+            assert.equals(world:getSystemCount(), 2)
         end)
 
         it("Clear Entities", function()
@@ -201,8 +211,21 @@ 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()
+            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)

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

@@ -1,14 +1,38 @@
+--[[
+Copyright (c) 2015 Calvin Rose
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+]]
+
 --- @module tiny-ecs
 -- @author Calvin Rose
-local tiny = { _VERSION = "1.0-2" }
+-- @license MIT
+-- @copyright 2015
+local tiny = { _VERSION = "1.1-6" }
 
 -- 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
@@ -22,20 +46,56 @@ local tiny_remove
 
 --- Filter functions.
 -- A Filter is a function that selects which Entities apply to a System.
+-- Filters take two parameters, the System and the Entity, and return a boolean
+-- 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-ecs's Filter functions are immutable and can be
+-- used by multiple Systems.
+--
+--    local f1 = tiny.requireAll("position", "velocity", "size")
+--    local f2 = tiny.requireAny("position", "velocity", "size")
+--
+--    local e1 = {
+--        position = {2, 3},
+--        velocity = {3, 3},
+--        size = {4, 4}
+--    }
+--
+--    local entity2 = {
+--        position = {4, 5},
+--        size = {4, 4}
+--    }
+--
+--    local e3 = {
+--        position = {2, 3},
+--        velocity = {3, 3}
+--    }
+--
+--    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 filters Entities with specified Components.
+--- Makes a Filter that selects Entities with all specified Components and
--- An Entity must have all Components to match the filter.
+-- Filters.
--- @param ... List of Components
 function tiny.requireAll(...)
     local components = {...}
     local len = #components
-    return function(_, e)
+    return function(system, e)
         local c
         for i = 1, len do
             c = components[i]
             if type(c) == 'function' then
-                if not c(_, e) then
+                if not c(system, e) then
                     return false
                 end
             elseif e[c] == nil then
@@ -46,18 +106,17 @@ function tiny.requireAll(...)
     end
 end
 
---- Makes a Filter that filters Entities with specified Components.
+--- Makes a Filter that selects Entities with at least one of the specified
--- An Entity must have at least one specified Component to match the filter.
+-- Components and Filters.
--- @param ... List of Components
+function tiny.requireAny(...)
-function tiny.requireOne(...)
     local components = {...}
     local len = #components
-    return function(_, e)
+    return function(system, e)
         local c
         for i = 1, len do
             c = components[i]
             if type(c) == 'function' then
-                if c(_, e) then
+                if c(system, e) then
                     return true
                 end
             elseif e[c] ~= nil then
@@ -68,47 +127,122 @@ function tiny.requireOne(...)
     end
 end
 
+--- 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
+
+--- 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)` - 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.
+--
+-- 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
+--
+-- 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" }
 
--- Check if tables are systems.
+-- Checks if a table is a System.
 local function isSystem(table)
     return table[systemTableKey]
 end
 
---- Creates a System. Systems are tables that contain at least one field; 
--- an update function that takes parameters like so: 
--- `function system:update(entities, dt)`. `entities` is an unordered table of 
--- Entities with Entities as KEYS, and `dt` is the delta time. There are also a 
--- few other optional callbacks:
--- `function system:filter(entity)` - returns a boolean,
--- `function system:onAdd(entity)` - returns nil,
--- `function system:onRemove(entity)` - returns nil.
--- For Filters, it is conveient to use `tiny.requireAll` or `tiny.requireOne`,
--- but one can write their own filters as well.
--- @param table A table to be used as a System, or `nil` to create a new System.
-function tiny.system(table)
-    if table == nil then
-        table = {}
-    end
-    table[systemTableKey] = true
-    return table
-end
-
 -- Update function for all Processing Systems.
-local function processingSystemUpdate(system, entities, dt)
+local 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, entities, dt)
+        preProcess(system, dt)
     end
 
     if process then
@@ -120,48 +254,100 @@ local function processingSystemUpdate(system, entities, dt)
     end
 
     if postProcess then
-        postProcess(system, entities, dt)
+        postProcess(system, dt)
     end
 end
 
---- Creates a Processing System. A Processing System iterates through its 
+-- Sorts Systems by a function system.sort(entity1, entity2) on modify.
--- Entities in no particluar order, and updates them individually. It has two 
+local function sortedSystemOnModify(system, dt)
--- important fields, `function system:process(entity, dt)`, and `function 
+    local entities = system.entities
--- system:filter(entity)`. `entities` is Entities, 
+    local indices = system.indices
--- and `dt` is the delta time. There are also a few other 
+    local sortDelegate = system.sortDelegate
--- optional callbacks:
+    if not sortDelegate then
--- `function system:preProcess(entities, dt)` - returns nil,
+        local compare = system.compare
--- `function system:postProcess(entities, dt)` - returns nil,
+        sortDelegate = function(e1, e2)
--- `function system:onAdd(entity)` - returns nil,
+            return compare(system, e1, e2)
--- `function system:onRemove(entity)` - returns nil.
+        end
--- For Filters, it is conveient to use `tiny.requireAll` or `tiny.requireOne`,
+        system.sortDelegate = sortDelegate
--- but one can write their own filters as well.
--- @param table A table to be used as a System, or `nil` to create a new 
--- Processing System.
-function tiny.processingSystem(table)
-    if table == nil then
-        table = {}
     end
+    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.
+--
+--     function system:preProcess(entities, dt) -- Called before iteration.
+--     function system:process(entities, dt) -- Process each entity.
+--     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
+function tiny.processingSystem(table)
+    table = table or {}
     table[systemTableKey] = true
     table.update = processingSystemUpdate
     return table
 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 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
+-- @see sortedSystem
+function tiny.sortedProcessingSystem(table)
+    table = table or {}
+    table[systemTableKey] = true
+    table.update = processingSystemUpdate
+    table.onModify = sortedSystemOnModify
+    return table
+end
+
 --- World functions.
--- A World is a container that manages Entities and Systems. The tiny-ecs module
+-- A World is a container that manages Entities and Systems. Typically, a
--- is set to be the `__index` of all World tables, so the often clearer syntax of
+-- program uses one World at a time.
--- 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.
+-- Can optionally add default Systems and Entities. Returns the new World along
--- @param ... Systems and Entities to add to the World
+-- with default Entities and Systems.
--- @return A new World
 function tiny.world(...)
-
     local ret = {
 
         -- List of Entities to add
@@ -176,123 +362,98 @@ function tiny.world(...)
         -- List of Entities to remove
         systemsToRemove = {},
 
-        -- Set of Entities 
+        -- 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 = {},
-
-        -- Table of Systems to System Indices
-        systemIndices = {}
     }
 
     tiny_add(ret, ...)
     tiny_manageSystems(ret)
     tiny_manageEntities(ret)
 
-    return setmetatable(ret, worldMetaTable)
+    return setmetatable(ret, worldMetaTable), ...
-
 end
 
 --- Adds an Entity to the world.
--- The new Entity will enter the world next time World:update is called.
+-- Also call this on Entities that have changed Components such that they
--- Also call this on Entities that have changed Components such that it 
+-- match different Filters. Returns the Entity.
--- matches different systems.
--- @param world
--- @param entity
 function tiny.addEntity(world, entity)
     local e2a = world.entitiesToAdd
     e2a[#e2a + 1] = entity
     if world.entities[entity] then
         tiny_removeEntity(world, entity)
     end
+    return entity
 end
 tiny_addEntity = tiny.addEntity
 
---- Adds a System to the world.
+--- Adds a System to the world. Returns the System.
--- The new System will enter the world next time World:update is called.
--- @param world
--- @param system
 function tiny.addSystem(world, system)
     local s2a = world.systemsToAdd
     s2a[#s2a + 1] = system
+    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
--- New objects will enter the World the next time World:update(dt) is called.
+-- added Entities and Systems.
--- Also call this method when an Entity has had its Components changed, such
--- that it matches different Filters.
--- @param world
--- @param ... Systems and Entities
 function tiny.add(world, ...)
-    local args = {...}
+    local obj
-    for _, obj in ipairs(args) do
+    for i = 1, select("#", ...) do
-        if isSystem(obj) then
+        obj = select(i, ...)
-            tiny_addSystem(world, obj)
+        if obj then
-        else -- Assume obj is an Entity
+            if isSystem(obj) then
-            tiny_addEntity(world, obj)
+                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.
+--- Removes an Entity to the World. Returns the Entity.
--- The Entity will exit the World next time World:update is called.
--- Also call this on Entities that have changed Components such that it 
--- matches different systems.
--- @param world
--- @param entity
 function tiny.removeEntity(world, entity)
     local e2r = world.entitiesToRemove
     e2r[#e2r + 1] = entity
+    return entity
 end
 tiny_removeEntity = tiny.removeEntity
 
---- Removes a System from the world.
+--- Removes a System from the world. Returns the System.
--- The System will exit the World next time World:update is called.
--- @param world
--- @param system
 function tiny.removeSystem(world, system)
     local s2r = world.systemsToRemove
     s2r[#s2r + 1] = system
+    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
--- Objects will exit the World the next time World:update(dt) is called.
+-- all rmeove Systems and Entities
--- @param world
--- @param ... Systems and Entities
 function tiny.remove(world, ...)
-    local args = {...}
+    local obj
-    for _, obj in ipairs(args) do
+    for i = 1, select("#", ...) do
-        if isSystem(obj) then
+        obj = select(i, ...)
-            tiny_removeSystem(world, obj)
+        if obj then
-        else -- Assume obj is an Entity
+            if isSystem(obj) then
-           tiny_removeEntity(world, obj)
+                tiny_removeSystem(world, obj)
+            else -- Assume obj is an Entity
+               tiny_removeEntity(world, obj)
+            end
         end
     end
+    return ...
 end
 tiny_remove = tiny.remove
 
---- Updates a System.
+-- Adds and removes Systems that have been marked from the World.
--- @param world
+function tiny_manageSystems(world)
--- @param system A System in the World to update
--- @param dt Delta time
-function tiny.updateSystem(world, system, dt)
-    local es = world.systemEntities[system]
-    system:update(es, dt)
-end
-
---- Adds and removes Systems that have been marked from the World.
--- The user of this library should seldom if ever call this.
--- @param world
-function tiny.manageSystems(world)
-
         local s2a, s2r = world.systemsToAdd, world.systemsToRemove
 
         -- Early exit
@@ -300,44 +461,53 @@ function tiny.manageSystems(world)
             return
         end
 
-        local systemIndices = world.systemIndices
         local entities = world.entities
         local systems = world.systems
-
+        local system, index, filter
-        local system, systemData, index, filter, entityList, entityIndices, entityIndex, onRemove, onAdd
+        local entityList, entityIndices, entityIndex, onRemove, onAdd
 
         -- Remove Systems
         for i = 1, #s2r do
             system = s2r[i]
-            index = systemIndices[system]
+            index = system.index
-            if index then
+            if system.world == world then
-                systemData = systems[index]
                 onRemove = system.onRemove
                 if onRemove then
-                    entityList = systemData.entities
+                    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].system] = j
+                    systems[j].index = j
                 end
             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
+            if systems[system.index] ~= system then
                 entityList = {}
                 entityIndices = {}
-                systemData = { system = system, entities = entityList, indices = entityIndices, active = true }
+                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
+                system.index = index
-                systems[index] = systemData
+                systems[index] = system
 
                 -- Try to add Entities
                 onAdd = system.onAdd
@@ -357,15 +527,10 @@ function tiny.manageSystems(world)
             end
             s2a[i] = nil
         end
-
 end
-tiny_manageSystems = tiny.manageSystems
-
---- Adds and removes Entities that have been marked.
--- The user of this library should seldom if ever call this.
--- @param world
-function tiny.manageEntities(world)
 
+-- Adds and removes Entities that have been marked.
+function tiny_manageEntities(world)
     local e2a, e2r = world.entitiesToAdd, world.entitiesToRemove
 
     -- Early exit
@@ -376,28 +541,29 @@ function tiny.manageEntities(world)
     local entities = world.entities
     local systems = world.systems
     local entityCount = world.entityCount
-    local entity, system, systemData, index, onRemove, onAdd, ses, seis, filter, tmpEntity
+    local entity, system, index
+    local onRemove, onAdd, ses, seis, filter, tmpEntity
 
     -- Remove Entities
     for i = 1, #e2r do
         entity = e2r[i]
         if entities[entity] then
             entities[entity] = nil
+            entityCount = entityCount - 1
 
             for j = 1, #systems do
-                systemData = systems[j]
+                system = systems[j]
-                system = systemData.system
+                ses = system.entities
-                ses = systemData.entities
+                seis = system.indices
-                seis = systemData.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)
@@ -410,24 +576,23 @@ function tiny.manageEntities(world)
         e2r[i] = nil
     end
 
-
     -- Add Entities
     for i = 1, #e2a do
         entity = e2a[i]
         if not entities[entity] then
             entities[entity] = true
+            entityCount = entityCount + 1
 
             for j = 1, #systems do
-                systemData = systems[j]
+                system = systems[j]
-                system = systemData.system
+                ses = system.entities
-                ses = systemData.entities
+                seis = system.indices
-                seis = systemData.indices
                 filter = system.filter
                 if filter and filter(system, entity) then
+                    system.modified = true
                     index = #ses + 1
                     ses[index] = entity
                     seis[entity] = index
-                    entityCount = entityCount + 1
                     onAdd = system.onAdd
                     if onAdd then
                         onAdd(system, entity)
@@ -442,36 +607,55 @@ function tiny.manageEntities(world)
 
     -- Update Entity count
     world.entityCount = entityCount
-
 end
-tiny_manageEntities = tiny.manageEntities
 
---- Updates the World.
+--- Updates the World by dt (delta time). Takes an optional parameter, `filter`,
--- Frees Entities that have been marked for freeing, adds
+-- which is a Filter that selects Systems from the World, and updates only those
--- entities that have been marked for adding, etc.
+-- Systems. If `filter` is not supplied, all Systems are updated. Put this
--- @param world
+-- function in your main loop.
--- @param dt Delta time
+function tiny.update(world, dt, filter)
-function tiny.update(world, dt)
 
     tiny_manageSystems(world)
     tiny_manageEntities(world)
 
     local systems = world.systems
-    local systemData
+    local system, update, interval, onModify
 
     --  Iterate through Systems IN ORDER
     for i = 1, #systems do
-        systemData = systems[i]
+        system = systems[i]
-        if systemData.active then
+        if system.active and ((not filter) or filter(world, system)) then
-            systemData.system:update(systemData.entities, dt)
+
+            -- Call the modify callback on Systems that have been modified.
+            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
+            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
     end
 end
 
 --- Removes all Entities from the World.
--- When World:update(dt) is next called,
--- all Entities will be removed.
--- @param world
 function tiny.clearEntities(world)
     for e in pairs(world.entities) do
         tiny_removeEntity(world, e)
@@ -479,80 +663,63 @@ function tiny.clearEntities(world)
 end
 
 --- Removes all Systems from the World.
--- When World:update(dt) is next called,
--- all Systems will be removed.
--- @param world
 function tiny.clearSystems(world)
     local systems = world.systems
     for i = #systems, 1, -1 do
-        tiny_removeSystem(world, systems[i].system)
+        tiny_removeSystem(world, systems[i])
     end
 end
 
---- Gets count of Entities in World.
+--- Gets number of Entities in the World.
--- @param world
 function tiny.getEntityCount(world)
     return world.entityCount
 end
 
---- Gets count of Systems in World.
+--- Gets number of Systems in World.
--- @param world
 function tiny.getSystemCount(world)
     return #(world.systems)
 end
 
---- Gets the index of a System in the world. Lower indexed Systems are processed
+--- Gets the index of the System in the World.
--- before higher indexed systems.
+-- A simpler alternative is `system.index`.
--- @param world
--- @param system
 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
+--- 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. Returns the old system.index.
--- @param world
--- @param system
--- @param index
 function tiny.setSystemIndex(world, system, index)
-    local systemIndices = world.systemIndices
+    local oldIndex = system.index
-    local oldIndex = systemIndices[system]
     local systems = world.systems
-    local systemData = systems[oldIndex]
 
     tremove(systems, oldIndex)
-    tinsert(systems, index, systemData)
+    tinsert(systems, index, system)
 
     for i = oldIndex, index, index >= oldIndex and 1 or -1 do
-        systemIndices[systems[i].system] = i
+        systems[i].index = i
     end
+
+    return oldIndex
 end
 
---- Activates Systems in the World.
+-- Construct world metatable.
--- Activated Systems will be update whenever tiny.update(world, dt) is called.
+worldMetaTable = {
--- @param world
+    __index = {
--- @param ... Systems to activate. The Systems must already be added to the
+        add = tiny.add,
--- World.
+        addEntity = tiny.addEntity,
-function tiny.activate(world, ...)
+        addSystem = tiny.addSystem,
-    local args = {...}
+        remove = tiny.remove,
-    for _, system in ipairs(args) do
+        removeEntity = tiny.removeEntity,
-        world.systems[world.systemIndices[system]].active = true
+        removeSystem = tiny.removeSystem,
-    end
+        update = tiny.update,
-end
+        clearEntities = tiny.clearEntities,
-
+        clearSystems = tiny.clearSystems,
---- Deactivates Systems in the World.
+        getEntityCount = tiny.getEntityCount,
--- Deactivated Systems must be update manually, and will not update when the
+        getSystemCount = tiny.getSystemCount,
--- rest of World updates. They will, however, process new Entities added while
+        getSystemIndex = tiny.getSystemIndex,
--- the System is deactivated.
+        setSystemIndex = tiny.setSystemIndex
--- @param world
+    }
--- @param ... Systems to deactivate. The Systems must already be added to the
+}
--- World.
-function tiny.deactivate(world, ...)
-    local args = {...}
-    for _, system in ipairs(args) do
-        world.systems[world.systemIndices[system]].active = false
-    end
-end
 
 return tiny