MapDisplay demo

src/main.moon

@@ -0,0 +1,57 @@
+import graphics from love
+import cos, sin, pi from math
+export t = 0
+tau = 2 * math.pi
+w, h = graphics.getDimensions!
+
+tiny = require "tiny"
+
+MapDisplay = tiny.sortedSystem {
+  compare: (a, b) =>
+    a.orbit.hierarchy < b.orbit.hierarchy
+  filter: tiny.requireAll "orbit"
+  draw: =>
+    graphics.translate w / 2, h / 2
+    for e in *@entities
+      entity = e.orbit
+      -- orbital period
+      --  real: T = 2pi * sqrt(a^3 / G*M)
+      --  sim:  T = 2pi * speed_parameter
+      entity.x = entity.radius * cos(t / entity.speed_parameter) + entity.offset
+      entity.y = entity.radius * sin(t / entity.speed_parameter) + entity.offset
+      if entity.parent
+        entity.x += entity.parent.x
+        entity.y += entity.parent.y
+      graphics.circle "fill", entity.x, entity.y, 5
+}
+
+world = tiny.world MapDisplay
+
+-- TEMP demo
+sun = {
+  x: 0,
+  y: 0,
+  orbit: { hierarchy: 0, radius: 0, offset: 0, speed_parameter: 1 }
+}
+
+planet = {
+  orbit: {
+    hierarchy: 1
+    radius: 20
+    parent: sun
+    offset: love.math.random!
+    speed_parameter: 0.5
+  }
+}
+
+world\add planet, sun
+
+love.update = (dt) ->
+  t += dt
+  world\update dt
+
+love.draw = ->
+  MapDisplay\draw!
+
+love.keypressed = (key) ->
+  if key == "escape" love.event.quit!

src/tiny.lua

@@ -0,0 +1,863 @@
+--[[
+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:
+
+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
+-- @license MIT
+-- @copyright 2016
+local tiny = {}
+
+-- Local versions of standard lua functions
+local tinsert = table.insert
+local tremove = table.remove
+local tsort = table.sort
+local setmetatable = setmetatable
+local type = type
+local select = select
+
+-- Local versions of the library functions
+local tiny_manageEntities
+local tiny_manageSystems
+local tiny_addEntity
+local tiny_addSystem
+local tiny_add
+local tiny_removeEntity
+local tiny_removeSystem
+
+--- 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. 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
+-- 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
+
+-- 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(...)
+    return filterJoin('', ' and ', ...)
+end
+
+--- Makes a Filter that selects Entities with at least one of the specified
+-- Components and Filters.
+function tiny.requireAny(...)
+    return filterJoin('', ' or ', ...)
+end
+
+--- Makes a Filter that rejects Entities with all specified Components and
+-- Filters, and selects all other Entities.
+function tiny.rejectAll(...)
+    return filterJoin('not', ' and ', ...)
+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(...)
+    return filterJoin('not', ' or ', ...)
+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.
+-- 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.
+--   * `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
+-- 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.
+--
+-- 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
+-- this key is considered a System rather than an Entity.
+local systemTableKey = { "SYSTEM_TABLE_KEY" }
+
+-- Checks if a table is a System.
+local function isSystem(table)
+    return table[systemTableKey]
+end
+
+-- Update function for all Processing Systems.
+local function processingSystemUpdate(system, dt)
+    local preProcess = system.preProcess
+    local process = system.process
+    local postProcess = system.postProcess
+
+    if preProcess then
+        preProcess(system, dt)
+    end
+
+    if process then
+        if system.nocache then
+            local entities = system.world.entityList
+            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.sortDelegate(entity1, entity2) on modify.
+local function sortedSystemOnModify(system)
+    local entities = system.entities
+    local indices = system.indices
+    local sortDelegate = system.sortDelegate
+    if not sortDelegate then
+        local compare = system.compare
+        sortDelegate = function(e1, e2)
+            return compare(system, e1, e2)
+        end
+        system.sortDelegate = sortDelegate
+    end
+    tsort(entities, sortDelegate)
+    for i = 1, #entities do
+        indices[entities[i]] = 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(dt) -- Called before iteration.
+--     function system:process(entity, dt) -- Process each entity.
+--     function system:postProcess(dt) -- Called after iteration.
+--
+-- Processing Systems have their own `update` method, so don't implement a
+-- a custom `update` callback for Processing Systems.
+-- @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. Typically, a
+-- program uses one World at a time.
+--
+-- 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
+
+-- Forward declaration
+local worldMetaTable
+
+--- Creates a new World.
+-- Can optionally add default Systems and Entities. Returns the new World along
+-- with default Entities and Systems.
+function tiny.world(...)
+    local ret = setmetatable({
+
+        -- List of Entities to remove
+        entitiesToRemove = {},
+
+        -- List of Entities to change
+        entitiesToChange = {},
+
+        -- List of Entities to add
+        systemsToAdd = {},
+
+        -- List of Entities to remove
+        systemsToRemove = {},
+
+        -- Set of Entities
+        entities = {},
+
+        -- List of Systems
+        systems = {}
+
+    }, worldMetaTable)
+
+    tiny_add(ret, ...)
+    tiny_manageSystems(ret)
+    tiny_manageEntities(ret)
+
+    return ret, ...
+end
+
+--- Adds an Entity to the world.
+-- Also call this on Entities that have changed Components such that they
+-- match different Filters. Returns the Entity.
+function tiny.addEntity(world, entity)
+    local e2c = world.entitiesToChange
+    e2c[#e2c + 1] = entity
+    return entity
+end
+tiny_addEntity = tiny.addEntity
+
+--- 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. Returns all
+-- added Entities and Systems.
+function tiny.add(world, ...)
+    for i = 1, select("#", ...) do
+        local obj = select(i, ...)
+        if obj then
+            if isSystem(obj) then
+                tiny_addSystem(world, obj)
+            else -- Assume obj is an Entity
+                tiny_addEntity(world, obj)
+            end
+        end
+    end
+    return ...
+end
+tiny_add = tiny.add
+
+--- Removes an Entity 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. 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. Returns
+-- all removed Systems and Entities
+function tiny.remove(world, ...)
+    for i = 1, select("#", ...) do
+        local obj = select(i, ...)
+        if obj then
+            if isSystem(obj) then
+                tiny_removeSystem(world, obj)
+            else -- Assume obj is an Entity
+                tiny_removeEntity(world, obj)
+            end
+        end
+    end
+    return ...
+end
+
+-- Adds and removes Systems that have been marked from the World.
+function tiny_manageSystems(world)
+    local s2a, s2r = world.systemsToAdd, world.systemsToRemove
+
+    -- Early exit
+    if #s2a == 0 and #s2r == 0 then
+        return
+    end
+
+    world.systemsToAdd = {}
+    world.systemsToRemove = {}
+
+    local worldEntityList = world.entities
+    local systems = world.systems
+
+    -- Remove Systems
+    for i = 1, #s2r do
+        local system = s2r[i]
+        local index = system.index
+        local onRemove = system.onRemove
+        if onRemove and not system.nocache then
+            local entityList = system.entities
+            for j = 1, #entityList do
+                onRemove(system, entityList[j])
+            end
+        end
+        tremove(systems, index)
+        for j = index, #systems do
+            systems[j].index = j
+        end
+        local onRemoveFromWorld = system.onRemoveFromWorld
+        if onRemoveFromWorld then
+            onRemoveFromWorld(system, world)
+        end
+        s2r[i] = nil
+
+        -- Clean up System
+        system.world = nil
+        system.entities = nil
+        system.indices = nil
+        system.index = nil
+    end
+
+    -- Add Systems
+    for i = 1, #s2a do
+        local system = s2a[i]
+        if systems[system.index or 0] ~= system then
+            if not system.nocache then
+                system.entities = {}
+                system.indices = {}
+            end
+            if system.active == nil then
+                system.active = true
+            end
+            system.modified = true
+            system.world = world
+            local index = #systems + 1
+            system.index = index
+            systems[index] = system
+            local onAddToWorld = system.onAddToWorld
+            if onAddToWorld then
+                onAddToWorld(system, world)
+            end
+
+            -- Try to add Entities
+            if not system.nocache then
+                local entityList = system.entities
+                local entityIndices = system.indices
+                local onAdd = system.onAdd
+                local filter = system.filter
+                if filter then
+                    for j = 1, #worldEntityList do
+                        local entity = worldEntityList[j]
+                        if filter(system, entity) then
+                            local entityIndex = #entityList + 1
+                            entityList[entityIndex] = entity
+                            entityIndices[entity] = entityIndex
+                            if onAdd then
+                                onAdd(system, entity)
+                            end
+                        end
+                    end
+                end
+            end
+        end
+        s2a[i] = nil
+    end
+end
+
+-- Adds, removes, and changes Entities that have been marked.
+function tiny_manageEntities(world)
+
+    local e2r = world.entitiesToRemove
+    local e2c = world.entitiesToChange
+
+    -- Early exit
+    if #e2r == 0 and #e2c == 0 then
+        return
+    end
+
+    world.entitiesToChange = {}
+    world.entitiesToRemove = {}
+
+    local entities = world.entities
+    local systems = world.systems
+
+    -- Change Entities
+    for i = 1, #e2c do
+        local entity = e2c[i]
+        -- Add if needed
+        if not entities[entity] then
+            local index = #entities + 1
+            entities[entity] = index
+            entities[index] = entity
+        end
+        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]
+                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
+                        local onAdd = system.onAdd
+                        if onAdd then
+                            onAdd(system, entity)
+                        end
+                    end
+                elseif index then
+                    system.modified = true
+                    local tmpEntity = ses[#ses]
+                    ses[index] = tmpEntity
+                    seis[tmpEntity] = index
+                    seis[entity] = nil
+                    ses[#ses] = nil
+                    local onRemove = system.onRemove
+                    if onRemove then
+                        onRemove(system, entity)
+                    end
+                end
+            end
+        end
+        e2c[i] = nil
+    end
+
+    -- Remove Entities
+    for i = 1, #e2r do
+        local entity = e2r[i]
+        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
+end
+
+--- Manages Entities and Systems marked for deletion or addition. Call this
+-- before modifying Systems and Entities outside of a call to `tiny.update`.
+-- Do not call this within a call to `tiny.update`.
+function tiny.refresh(world)
+    tiny_manageSystems(world)
+    tiny_manageEntities(world)
+    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`,
+-- which is a Filter that selects Systems from the World, and updates only those
+-- Systems. If `filter` is not supplied, all Systems are updated. Put this
+-- function in your main loop.
+function tiny.update(world, dt, filter)
+
+    tiny_manageSystems(world)
+    tiny_manageEntities(world)
+
+    local systems = world.systems
+
+    -- 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.
+            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)
+            local update = system.update
+            if update then
+                local interval = system.interval
+                if interval then
+                    local bufferedTime = (system.bufferedTime or 0) + dt
+                    while bufferedTime >= interval do
+                        bufferedTime = bufferedTime - interval
+                        update(system, interval)
+                    end
+                    system.bufferedTime = bufferedTime
+                else
+                    update(system, dt)
+                end
+            end
+
+            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)
+    local el = world.entities
+    for i = 1, #el do
+        tiny_removeEntity(world, el[i])
+    end
+end
+
+--- Removes all Systems from the World.
+function tiny.clearSystems(world)
+    local systems = world.systems
+    for i = #systems, 1, -1 do
+        tiny_removeSystem(world, systems[i])
+    end
+end
+
+--- Gets number of Entities in the World.
+function tiny.getEntityCount(world)
+    return #world.entities
+end
+
+--- Gets number of Systems in World.
+function tiny.getSystemCount(world)
+    return #world.systems
+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. Returns the old system.index.
+function tiny.setSystemIndex(world, system, index)
+    local oldIndex = system.index
+    local systems = world.systems
+
+    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
+        systems[i].index = i
+    end
+
+    return oldIndex
+end
+
+-- Construct world metatable.
+worldMetaTable = {
+    __index = {
+        add = tiny.add,
+        addEntity = tiny.addEntity,
+        addSystem = tiny.addSystem,
+        remove = tiny.remove,
+        removeEntity = tiny.removeEntity,
+        removeSystem = tiny.removeSystem,
+        refresh = tiny.refresh,
+        update = tiny.update,
+        clearEntities = tiny.clearEntities,
+        clearSystems = tiny.clearSystems,
+        getEntityCount = tiny.getEntityCount,
+        getSystemCount = tiny.getSystemCount,
+        setSystemIndex = tiny.setSystemIndex
+    },
+    __tostring = function()
+        return "<tiny-ecs_World>"
+    end
+}
+
+return tiny