Merge pull request #25 from yangruihan/master

fix README.md example error

.travis.yml

@@ -0,0 +1,39 @@
+language: c
+
+env:
+  global:
+    - LUAROCKS_BASE=luarocks-3.2.1
+  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

LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2015 Calvin Rose
+Copyright (c) 2016 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:
 

README.md

@@ -1,27 +1,34 @@
 # tiny-ecs #
 
-[![License](http://img.shields.io/badge/Licence-MIT-brightgreen.svg)](LICENSE)
+## NOTE
 
-Tiny-ecs is an Entity Component System for lua that's simple, flexible, and useful.
+Although there have been almost no commits in several years, this
-Because of lua's tabular nature, Entity Component Systems are a natural choice
+project is not abandoned. tiny-ecs is, for most intents and
+purposes, finished, and no bugs have been brought to my attention in a while.
+New issues on GitHub will be addressed.
+
+[![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 object-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.
+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
+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.
+demo branch, specifically the systems and entities subdirectories.
 
 ## Overview ##
 Tiny-ecs has four important types: Worlds, Filters, Systems, and Entities.
-Entities, however, can be any lua table, and Filters are just functions that
+Entities, however, can be any Lua table, and Filters are just functions that
 take an Entity as a parameter.
 
 ### Entities ###
-Entities are simply lua tables of data that gets processed by Systems. Entities
+Entities are simply Lua tables of data that gets processed by Systems. Entities
-should contain primarily data rather than code, as it is the Systems's job to
+should contain primarily data rather than code, as it is the System's job to
 do logic on data. Henceforth, a key-value pair in an Entity will
 be referred to as a Component.
 
@@ -37,7 +44,7 @@ provides functions for creating Systems easily, as well as creating Systems that
 can be used in an object oriented fashion.
 
 ### Filters ###
-Filters are used to select Entities. Filters can be any lua function, but
+Filters are used to select Entities. Filters can be any Lua function, but
 tiny-ecs provides some functions for generating common ones, like selecting
 only Entities that have all required components.
 
@@ -49,7 +56,7 @@ local talkingSystem = tiny.processingSystem()
 talkingSystem.filter = tiny.requireAll("name", "mass", "phrase")
 function talkingSystem:process(e, dt)
     e.mass = e.mass + dt * 3
-    print(e.name .. ", who weighs " .. e.mass .. " pounds, says, \"" .. e.phrase .. "\"")
+    print(("%s who weighs %d pounds, says %q."):format(e.name, e.mass, e.phrase))
 end
 
 local joe = {
@@ -68,17 +75,16 @@ 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
+please use a tagged release or use LuaRocks.
-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
+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.
+[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

config.ld

@@ -5,7 +5,7 @@ backtick_references = true
 format = 'discount'
 title = "tiny-ecs API"
 one = true
-dir = doc
+dir = "doc"
 style = '!fixed'
 package = 'tiny-ecs'
 not_luadoc = true

init.lua

@@ -0,0 +1,6 @@
+-- Helper Lua file for easy require if tiny-ecs is used as a git submodule or
+-- folder. Not needed in many cases, including luarocks distribution.
+
+local args = {...}
+local directory = args[1]
+return require(directory .. '.tiny')

rockspecs/tiny-ecs-1.0-2.rockspec

@@ -2,7 +2,7 @@ package = "tiny-ecs"
 version = "1.0-2"
 source = {
     url = "git://github.com/bakpakin/tiny-ecs",
-    tag = "1.0-2"
+    tag = version
 }
 description = {
     summary = "Entity Component System for Lua.",

rockspecs/tiny-ecs-1.1-1.rockspec

@@ -2,7 +2,7 @@ package = "tiny-ecs"
 version = "1.1-1"
 source = {
     url = "git://github.com/bakpakin/tiny-ecs",
-    tag = "1.1-1"
+    tag = version
 }
 description = {
     summary = "Entity Component System for Lua.",

rockspecs/tiny-ecs-1.1-2.rockspec

@@ -2,7 +2,7 @@ package = "tiny-ecs"
 version = "1.1-2"
 source = {
     url = "git://github.com/bakpakin/tiny-ecs",
-    tag = "1.1-2"
+    tag = version
 }
 description = {
     summary = "Entity Component System for Lua.",

rockspecs/tiny-ecs-1.1-3.rockspec

@@ -2,7 +2,7 @@ package = "tiny-ecs"
 version = "1.1-3"
 source = {
     url = "git://github.com/bakpakin/tiny-ecs",
-    tag = "1.1-3"
+    tag = version
 }
 description = {
     summary = "Entity Component System for Lua.",

rockspecs/tiny-ecs-1.1-4.rockspec

@@ -2,7 +2,7 @@ package = "tiny-ecs"
 version = "1.1-4"
 source = {
     url = "git://github.com/bakpakin/tiny-ecs",
-    tag = "1.1-4"
+    tag = version
 }
 description = {
     summary = "Entity Component System for 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 = version
+}
+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 = version
+}
+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 = version
+}
+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 = version
+}
+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.3-1.rockspec

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

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

@@ -0,0 +1,24 @@
+package = "tiny-ecs"
+version = "1.3-3"
+source = {
+   url = "git://github.com/bakpakin/tiny-ecs",
+   tag = version
+}
+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)
@@ -85,6 +90,49 @@ describe('tiny-ecs:', function()
 
         end)
 
+        it("Can use functions as subfilters", function()
+
+            local f1 = tiny.requireAny('a', 'b', 'c')
+            local f2 = tiny.requireAll('x', 'y', 'z')
+            local f = tiny.requireAll(f1, f2)
+
+            assert.truthy(f(nil, {
+                x = true, y = true, z = true, a = true, b = true, c = true
+            }))
+            assert.truthy(f(nil, {
+                x = true, y = true, z = true, a = true
+            }))
+            assert.falsy(f(nil, {
+                x = true, y = true, a = true
+            }))
+            assert.falsy(f(nil, {
+                x = true, y = true, z = true
+            }))
+
+        end)
+
+        it("Can use string filters", function()
+
+            local f = tiny.filter('a|b|c')
+
+            assert.truthy(f(nil, {
+                a = true, b = true, c = true
+            }))
+            assert.truthy(f(nil, {
+                a = true
+            }))
+            assert.truthy(f(nil, {
+                b = true
+            }))
+            assert.truthy(f(nil, {
+                c = true
+            }))
+            assert.falsy(f(nil, {
+                x = true, y = true, z = true
+            }))
+
+        end)
+
     end)
 
     describe('World:', function()
@@ -115,6 +163,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)
@@ -180,9 +233,11 @@ describe('tiny-ecs:', function()
         end)
 
         it("Remove Entities Multiple Times", function()
+            assert.equals(3, world:getEntityCount())
             world:update(1)
             world:remove(entity1, entity2, entity3)
             world:update(2)
+            assert.equals(0, world:getEntityCount())
             world:remove(entity1, entity2, entity3)
             world:update(2)
             assert.equals(2, world:getSystemCount())
@@ -191,7 +246,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 +256,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,23 +266,58 @@ 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")
+            sortsys.filter = tiny.filter("vel|xform")
             function sortsys:compare(e1, e2)
                 return e1.vel.x < e2.vel.x
             end
             world:add(sortsys)
-            world:update(0)
+            world:refresh()
             assert.equals(sortsys.entities[1], entity2)
             assert.equals(sortsys.entities[2], entity3)
             assert.equals(sortsys.entities[3], entity1)
         end)
 
+        it("Runs preWrap and postWrap for systems.", function()
+            local str = ""
+            local sys1 = tiny.system()
+            local sys2 = tiny.system()
+            function sys1:preWrap(dt)
+                str = str .. "<"
+            end
+            function sys2:preWrap(dt)
+                str = str .. "{"
+            end
+            function sys1:postWrap(dt)
+                str = str .. ">"
+            end
+            function sys2:postWrap(dt)
+                str = str .. "}"
+            end
+            world:add(sys1, sys2)
+            world:update(1)
+            assert.equals(str, "{<>}")
+        end)
+
+    end)
+
+    it("Doesn't pollute the global namespace", function()
+        assert.are.same(_G, GLOBALS)
+    end)
+
+    it("Can set system indices", function()
+        local world = tiny.world()
+        local systemA = tiny.system()
+        local systemB = tiny.system()
+        world:addSystem(systemA)
+        world:addSystem(systemB)
+        world:setSystemIndex(systemA, 1)
+        assert(true)
     end)
 
 end)

test.lua

@@ -0,0 +1,8 @@
+local tiny = require('tiny')
+
+local world = tiny.world()
+local systemA = tiny.system()
+local systemB = tiny.system()
+world:addSystem(systemA)
+world:addSystem(systemB)
+world:setSystemIndex(systemA, 1)

tiny.lua

@@ -1,5 +1,5 @@
 --[[
-Copyright (c) 2015 Calvin Rose
+Copyright (c) 2016 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
@@ -22,14 +22,13 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 --- @module tiny-ecs
 -- @author Calvin Rose
 -- @license MIT
--- @copyright 2015
+-- @copyright 2016
-local tiny = { _VERSION = "1.1-4" }
+local tiny = {}
 
 -- Local versions of standard lua functions
 local tinsert = table.insert
 local tremove = table.remove
 local tsort = table.sort
-local pairs = pairs
 local setmetatable = setmetatable
 local type = type
 local select = select
@@ -42,12 +41,13 @@ local tiny_addSystem
 local tiny_add
 local tiny_removeEntity
 local tiny_removeSystem
-local tiny_remove
 
 --- Filter functions.
 -- A Filter is a function that selects which Entities apply to a System.
 -- Filters take two parameters, the System and the Entity, and return a boolean
--- value indicating if the Entity should be processed by the System.
+-- value indicating if the Entity should be processed by the System. A truthy
+-- value includes the entity, while a falsey (nil or false) value excludes the
+-- entity.
 --
 -- 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
@@ -85,88 +85,125 @@ local tiny_remove
 --
 -- @section Filter
 
+-- A helper function to compile filters.
+local filterJoin
+
+-- A helper function to filters from string
+local filterBuildString
+
+do
+
+    local loadstring = loadstring or load
+    local function getchr(c)
+        return "\\" .. c:byte()
+    end
+    local function make_safe(text)
+        return ("%q"):format(text):gsub('\n', 'n'):gsub("[\128-\255]", getchr)
+    end
+
+    local function filterJoinRaw(prefix, seperator, ...)
+        local accum = {}
+        local build = {}
+        for i = 1, select('#', ...) do
+            local item = select(i, ...)
+            if type(item) == 'string' then
+                accum[#accum + 1] = ("(e[%s] ~= nil)"):format(make_safe(item))
+            elseif type(item) == 'function' then
+                build[#build + 1] = ('local subfilter_%d_ = select(%d, ...)')
+                    :format(i, i)
+                accum[#accum + 1] = ('(subfilter_%d_(system, e))'):format(i)
+            else
+                error 'Filter token must be a string or a filter function.'
+            end
+        end
+        local source = ('%s\nreturn function(system, e) return %s(%s) end')
+            :format(
+                table.concat(build, '\n'),
+                prefix,
+                table.concat(accum, seperator))
+        local loader, err = loadstring(source)
+        if err then error(err) end
+        return loader(...)
+    end
+
+    function filterJoin(...)
+        local state, value = pcall(filterJoinRaw, ...)
+        if state then return value else return nil, value end
+    end
+
+    local function buildPart(str)
+        local accum = {}
+        local subParts = {}
+        str = str:gsub('%b()', function(p)
+            subParts[#subParts + 1] = buildPart(p:sub(2, -2))
+            return ('\255%d'):format(#subParts)
+        end)
+        for invert, part, sep in str:gmatch('(%!?)([^%|%&%!]+)([%|%&]?)') do
+            if part:match('^\255%d+$') then
+                local partIndex = tonumber(part:match(part:sub(2)))
+                accum[#accum + 1] = ('%s(%s)')
+                    :format(invert == '' and '' or 'not', subParts[partIndex])
+            else
+                accum[#accum + 1] = ("(e[%s] %s nil)")
+                    :format(make_safe(part), invert == '' and '~=' or '==')
+            end
+            if sep ~= '' then
+                accum[#accum + 1] = (sep == '|' and ' or ' or ' and ')
+            end
+        end
+        return table.concat(accum)
+    end
+
+    function filterBuildString(str)
+        local source = ("return function(_, e) return %s end")
+            :format(buildPart(str))
+        local loader, err = loadstring(source)
+        if err then
+            error(err)
+        end
+        return loader()
+    end
+
+end
+
 --- Makes a Filter that selects Entities with all specified Components and
 -- Filters.
 function tiny.requireAll(...)
-    local components = {...}
+    return filterJoin('', ' and ', ...)
-    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 false
-                end
-            elseif e[c] == nil then
-                return false
-            end
-        end
-        return true
-    end
 end
 
 --- Makes a Filter that selects Entities with at least one of the specified
 -- Components and Filters.
 function tiny.requireAny(...)
-    local components = {...}
+    return filterJoin('', ' or ', ...)
-    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 true
-                end
-            elseif e[c] ~= nil then
-                return true
-            end
-        end
-        return false
-    end
 end
 
 --- Makes a Filter that rejects Entities with all specified Components and
 -- Filters, and selects all other Entities.
 function tiny.rejectAll(...)
-    local components = {...}
+    return filterJoin('not', ' and ', ...)
-    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 = {...}
+    return filterJoin('not', ' or ', ...)
-    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
+
+--- Makes a Filter from a string. Syntax of `pattern` is as follows.
+--
+--   * Tokens are alphanumeric strings including underscores.
+--   * Tokens can be separated by |, &, or surrounded by parentheses.
+--   * Tokens can be prefixed with !, and are then inverted.
+--
+-- Examples are best:
+--    'a|b|c' - Matches entities with an 'a' OR 'b' OR 'c'.
+--    'a&!b&c' - Matches entities with an 'a' AND NOT 'b' AND 'c'.
+--    'a|(b&c&d)|e - Matches 'a' OR ('b' AND 'c' AND 'd') OR 'e'
+-- @param pattern
+function tiny.filter(pattern)
+    local state, value = pcall(filterBuildString, pattern)
+    if state then return value else return nil, value end
 end
 
 --- System functions.
@@ -187,6 +224,23 @@ 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.
+--   * `function system:preWrap(dt)` - Called on each system before update is
+-- called on any system.
+--   * `function system:postWrap(dt)` - Called on each system in reverse order
+-- after update is called on each system. The idea behind `preWrap` and
+-- `postWrap` is to allow for systems that modify the behavior of other systems.
+-- Say there is a DrawingSystem, which draws sprites to the screen, and a
+-- PostProcessingSystem, that adds some blur and bloom effects. In the preWrap
+-- method of the PostProcessingSystem, the System could set the drawing target
+-- for the DrawingSystem to a special buffer instead the screen. In the postWrap
+-- method, the PostProcessingSystem could then modify the buffer and render it
+-- to the screen. In this setup, the PostProcessingSystem would be added to the
+-- World after the drawingSystem (A similar but less flexible behavior could
+-- be accomplished with a single custom update function in the DrawingSystem).
 --
 -- 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 +260,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
@@ -219,6 +276,16 @@ end
 -- in the next update, if it has one. This is usually managed by tiny-ecs, so
 -- users should mostly ignore this, too.
 --
+-- There is another option to (hopefully) increase performance in systems that
+-- have items added to or removed from them often, and have lots of entities in
+-- them.  Setting the `nocache` field of the system might improve performance.
+-- It is still experimental. There are some restriction to systems without
+-- caching, however.
+--
+--   * There is no `entities` table.
+--   * Callbacks such onAdd, onRemove, and onModify will never be called
+--   * Noncached systems cannot be sorted (There is no entities list to sort).
+--
 -- @section System
 
 -- Use an empty table as a key for identifying Systems. Any table that contains
@@ -232,31 +299,41 @@ 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 len = #entities
+        if system.nocache then
-        for i = 1, len do
+            local entities = system.world.entities
-            entity = entities[i]
+            local filter = system.filter
+            if filter then
+                for i = 1, #entities do
+                    local entity = entities[i]
+                    if filter(system, entity) then
                         process(system, entity, dt)
                     end
                 end
+            end
+        else
+            local entities = system.entities
+            for i = 1, #entities do
+                process(system, entities[i], dt)
+            end
+        end
+    end
 
     if postProcess then
         postProcess(system, dt)
     end
 end
 
--- Sorts Systems by a function system.sort(entity1, entity2) on modify.
+-- Sorts Systems by a function system.sortDelegate(entity1, entity2) on modify.
-local function sortedSystemOnModify(system, dt)
+local function sortedSystemOnModify(system)
     local entities = system.entities
     local indices = system.indices
     local sortDelegate = system.sortDelegate
@@ -269,8 +346,7 @@ local function sortedSystemOnModify(system, dt)
     end
     tsort(entities, sortDelegate)
     for i = 1, #entities do
-        local entity = entities[i]
+        indices[entities[i]] = i
-        indices[entity] = i
     end
 end
 
@@ -286,11 +362,11 @@ end
 -- Systems process each entity individual, and are usually what is needed.
 -- Processing Systems have three extra callbacks besides those inheritted from
 -- vanilla Systems.
---     * `function system:preProcess(entities, dt)` - Called before iterating
+--
--- over each Entity.
+--     function system:preProcess(dt) -- Called before iteration.
---     * `function system:process(entities, dt)` - Called for each Entity in
+--     function system:process(entity, dt) -- Process each entity.
--- the System.
+--     function system:postProcess(dt) -- Called after iteration.
---     * `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
@@ -342,16 +418,17 @@ 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 = {},
 
         -- List of Entities to remove
         entitiesToRemove = {},
 
+        -- List of Entities to change
+        entitiesToChange = {},
+
         -- List of Entities to add
         systemsToAdd = {},
 
@@ -361,48 +438,43 @@ function tiny.world(...)
         -- Set of Entities
         entities = {},
 
-        -- Number of Entities in World.
+        -- List of Systems
-        entityCount = 0,
+        systems = {}
 
-        -- List of System Data. A data element is a table with 4
+    }, worldMetaTable)
-        -- keys: system, indices, entities, and active.
-        systems = {},
-
-        -- Table of Systems to System Indices
-        systemIndices = {}
-    }
 
     tiny_add(ret, ...)
     tiny_manageSystems(ret)
     tiny_manageEntities(ret)
 
-    return setmetatable(ret, worldMetaTable)
+    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)
-    local e2a = world.entitiesToAdd
+    local e2c = world.entitiesToChange
-    e2a[#e2a + 1] = entity
+    e2c[#e2c + 1] = entity
-    if world.entities[entity] then
+    return entity
-        tiny_removeEntity(world, entity)
-    end
 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 +483,32 @@ function tiny.add(world, ...)
             end
         end
     end
+    return ...
 end
 tiny_add = tiny.add
 
---- Removes an Entity to the World.
+--- Removes an Entity from 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,8 +517,8 @@ function tiny.remove(world, ...)
             end
         end
     end
+    return ...
 end
-tiny_remove = tiny.remove
 
 -- Adds and removes Systems that have been marked from the World.
 function tiny_manageSystems(world)
@@ -453,29 +529,30 @@ function tiny_manageSystems(world)
         return
     end
 
-        local systemIndices = world.systemIndices
+    world.systemsToAdd = {}
-        local entities = world.entities
+    world.systemsToRemove = {}
+
+    local worldEntityList = 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 and not system.nocache then
-                if onRemove then
+            local entityList = system.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]] = j
+            systems[j].index = j
         end
+        local onRemoveFromWorld = system.onRemoveFromWorld
+        if onRemoveFromWorld then
+            onRemoveFromWorld(system, world)
         end
         s2r[i] = nil
 
@@ -483,32 +560,41 @@ 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 or 0] ~= system then
-                entityList = {}
+            if not system.nocache then
-                entityIndices = {}
+                system.entities = {}
-                system.entities = entityList
+                system.indices = {}
-                system.indices = entityIndices
+            end
             if system.active == nil then
                 system.active = true
             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
+            if not system.nocache then
-                filter = system.filter
+                local entityList = system.entities
+                local entityIndices = system.indices
+                local onAdd = system.onAdd
+                local filter = system.filter
                 if filter then
-                    for entity in pairs(entities) do
+                    for j = 1, #worldEntityList do
+                        local entity = worldEntityList[j]
                         if filter(system, entity) then
-                            entityIndex = #entityList + 1
+                            local entityIndex = #entityList + 1
                             entityList[entityIndex] = entity
                             entityIndices[entity] = entityIndex
                             if onAdd then
@@ -518,88 +604,126 @@ function tiny_manageSystems(world)
                     end
                 end
             end
+        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 e2r = world.entitiesToRemove
+    local e2c = world.entitiesToChange
 
     -- Early exit
-    if #e2a == 0 and #e2r == 0 then
+    if #e2r == 0 and #e2c == 0 then
         return
     end
 
+    world.entitiesToChange = {}
+    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
+        -- Add if needed
-            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
+            local index = #entities + 1
-
+            entities[entity] = index
+            entities[index] = entity
+        end
         for j = 1, #systems do
-                system = systems[j]
+            local system = systems[j]
-                ses = system.entities
+            if not system.nocache then
-                seis = system.indices
+                local ses = system.entities
-                filter = system.filter
+                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
+                        local onAdd = system.onAdd
-                    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]
+        e2r[i] = nil
+        local listIndex = entities[entity]
+        if listIndex then
+            -- Remove Entity from world state
+            local lastEntity = entities[#entities]
+            entities[lastEntity] = listIndex
+            entities[entity] = nil
+            entities[listIndex] = lastEntity
+            entities[#entities] = nil
+            -- Remove from cached systems
+            for j = 1, #systems do
+                local system = systems[j]
+                if not system.nocache then
+                    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
+        end
     end
-        e2a[i] = nil
 end
 
-    -- Update Entity count
+--- Manages Entities and Systems marked for deletion or addition. Call this
-    world.entityCount = entityCount
+-- 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)
+    local systems = world.systems
+    for i = #systems, 1, -1 do
+        local system = systems[i]
+        if system.active then
+            local onModify = system.onModify
+            if onModify and system.modified then
+                onModify(system, 0)
+            end
+            system.modified = false
+        end
+    end
 end
 
 --- Updates the World by dt (delta time). Takes an optional parameter, `filter`,
@@ -612,31 +736,39 @@ 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]
-        if system.active and ((not filter) or filter(world, system)) then
 
+    -- Iterate through Systems IN REVERSE ORDER
+    for i = #systems, 1, -1 do
+        local system = systems[i]
+        if system.active 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
+            local preWrap = system.preWrap
+            if preWrap and
+                ((not filter) or filter(world, system)) then
+                preWrap(system, dt)
+            end
+        end
+    end
+
+    --  Iterate through Systems IN ORDER
+    for i = 1, #systems do
+        local system = systems[i]
+        if system.active and ((not filter) or filter(world, system)) then
 
             -- 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
                         bufferedTime = bufferedTime - interval
-                        if update then
                         update(system, interval)
                     end
-                    end
                     system.bufferedTime = bufferedTime
                 else
                     update(system, dt)
@@ -646,12 +778,24 @@ function tiny.update(world, dt, filter)
             system.modified = false
         end
     end
+
+    -- Iterate through Systems IN ORDER AGAIN
+    for i = 1, #systems do
+        local system = systems[i]
+        local postWrap = system.postWrap
+        if postWrap and system.active and
+            ((not filter) or filter(world, system)) then
+            postWrap(system, dt)
+        end
+    end
+
 end
 
 --- Removes all Entities from the World.
 function tiny.clearEntities(world)
-    for e in pairs(world.entities) do
+    local el = world.entities
-        tiny_removeEntity(world, e)
+    for i = 1, #el do
+        tiny_removeEntity(world, el[i])
     end
 end
 
@@ -665,34 +809,31 @@ end
 
 --- Gets number of Entities in the World.
 function tiny.getEntityCount(world)
-    return world.entityCount
+    return #world.entities
 end
 
 --- Gets number of Systems in World.
 function tiny.getSystemCount(world)
-    return #(world.systems)
+    return #world.systems
-end
-
---- Gets the index of a System in the World. Lower indexed Systems are processed
--- before higher indexed systems.
-function tiny.getSystemIndex(world, system)
-    return world.systemIndices[system]
 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
+    tiny_manageSystems(world)
-    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
@@ -707,14 +848,17 @@ worldMetaTable = {
         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()
+        return "<tiny-ecs_World>"
+    end
 }
 
 return tiny