Overall doc improvements

.github/workflows/doc.yml

@@ -29,7 +29,7 @@ jobs:
       run: luarocks show ldoc
 
     - name: Build docs
-      run: ldoc .
+      run: lua scripts/build-docs.lua
 
     - name: Deploy
       uses: JamesIves/github-pages-deploy-action@4.1.5

.gitignore

@@ -40,4 +40,7 @@ luac.out
 *.hex
 
 # VSCode
-.vscode/
+.vscode/
+
+# LDoc preprocess output
+.ldoc-guides/

README.md

@@ -17,13 +17,13 @@ local Concord = require("path.to.concord")
 
 ## Documentation
 
-Start with **[Get Started](docs/Get%20Started.md)**. It covers Worlds, Components, Entities, Filters, Systems, and Events.
+Start with **[Getting Started](docs/index.html)**. It covers Worlds, Components, Entities, Filters, Systems, and Events.
 
 ### Guides
 
-- [Why ECS?](docs/Why%20ECS.md) — when Concord (and ECS in general) is a good fit
-- [Custom Pools](docs/Custom%20Pools.md) — using a different data structure than the default Pool list
-- [Pool Flushing and Timing](docs/Pool%20Flushing%20and%20Timing.md) — when Filters update, and how that interacts with Events
+- [Why ECS?](docs/guides/Why-ECS.md.html) — when Concord (and ECS in general) is a good fit
+- [Custom Pools](docs/guides/Custom-Pools.md.html) — using a different data structure than the default Pool list
+- [Pool Flushing and Timing](docs/guides/Pool-Flushing-and-Timing.md.html) — when Filters update, and how that interacts with Events
 
 API reference is generated with LDoc and published on the [GitHub page](https://keyslam-group.github.io/Concord/).
 

concord/builtins/key.lua

@@ -1,3 +1,7 @@
+--- Built-in Component that assigns a unique key to an Entity in its World.
+-- The Entity must belong to a World. Calling the Component returns the key value.
+-- @builtin key
+
 local PATH = (...):gsub('%.builtins%.[^%.]+$', '')
 
 local Component = require(PATH..".component")
@@ -18,14 +22,21 @@ local Key = Component("key", function (self, key)
   self.value = getKey(self, key)
 end)
 
+--- Assigns a key from serialized data.
+-- @param data Previously serialized key value
 function Key:deserialize (data)
   self.value = getKey(self, data)
 end
 
+--- Returns the key value.
+-- @function Key
+-- @treturn string|number The Entity's key
 function Key.__mt:__call()
   return self.value
 end
 
+--- Callback: Clears the World key when the Component is removed (not replaced).
+-- @tparam boolean replaced True when the Component is being overwritten
 function Key:removed (replaced)
   if not replaced then
     local entity = self.__entity

concord/builtins/serializable.lua

@@ -1,9 +1,16 @@
+--- Built-in marker Component. Entities with this Component are included in World:serialize.
+-- The Component itself is not serialized.
+-- @builtin serializable
+
 local PATH = (...):gsub('%.builtins%.[^%.]+$', '')
 
 local Component = require(PATH..".component")
 
 local Serializable = Component("serializable")
 
+--- Callback: When the Component gets serialized as part of an Entity.
+-- Returns nil so this marker is not written to serialized data.
+-- @treturn nil
 function Serializable:serialize ()
   -- Don't serialize this Component
   return nil

concord/component.lua

@@ -11,8 +11,9 @@ Component.__mt = {
    __index = Component,
 }
 
---- Creates a new ComponentClass.
--- @tparam function populate Function that populates a Component with values
+--- Creates a new ComponentClass and registers it by name.
+-- @string name Unique name of the ComponentClass
+-- @tparam[opt] function populate Function that populates a Component with values
 -- @treturn Component A new ComponentClass
 function Component.new(name, populate)
    if (type(name) ~= "string") then
@@ -51,11 +52,13 @@ end
 function Component:__populate() -- luacheck: ignore
 end
 
--- Callback: When the Component gets removed or replaced in an Entity.
-function Component:removed() -- luacheck: ignore
+--- Callback: When the Component gets removed or replaced in an Entity.
+-- @tparam boolean replaced True when the Component is being overwritten, false when it is being removed
+function Component:removed(replaced) -- luacheck: ignore
 end
 
--- Callback: When the Component gets serialized as part of an Entity.
+--- Callback: When the Component gets serialized as part of an Entity.
+-- @treturn table|nil Serialized data, or nil to omit this Component
 function Component:serialize()
    local data = Utils.shallowCopy(self, {})
 
@@ -68,7 +71,8 @@ function Component:serialize()
    return data
 end
 
--- Callback: When the Component gets deserialized from serialized data.
+--- Callback: When the Component gets deserialized from serialized data.
+-- @tparam table data Serialized data to copy onto this Component
 function Component:deserialize(data)
    Utils.shallowCopy(data, self)
 end
@@ -95,7 +99,7 @@ end
 function Component:__initialize(entity, ...)
    local component = self:__new(entity)
 
-   ---@diagnostic disable-next-line: redundant-parameter
+   -- LuaLS: redundant-parameter (varargs forwarded to populate)
    self.__populate(component, ...)
 
    return component

concord/components.lua

@@ -6,7 +6,7 @@ local Components = {}
 Components.__REJECT_PREFIX = "!"
 Components.__REJECT_MATCH = "^(%"..Components.__REJECT_PREFIX.."?)(.+)"
 
---- Returns true if the containter has the ComponentClass with the specified name
+--- Returns true if the container has the ComponentClass with the specified name
 -- @string name Name of the ComponentClass to check
 -- @treturn boolean
 function Components.has(name)
@@ -27,10 +27,10 @@ end
 --- Returns true and the ComponentClass if one was registered with the specified name
 -- or false and an error otherwise
 -- @string name Name of the ComponentClass to check
--- @boolean acceptRejected Whether to accept names prefixed with the Reject Prefix.
--- @treturn boolean
--- @treturn Component or error string
--- @treturn true if acceptRejected was true and the name had the Reject Prefix, false otherwise.
+-- @tparam[opt] boolean acceptRejected Whether to accept names prefixed with the Reject Prefix.
+-- @treturn boolean ok
+-- @treturn Component|string ComponentClass on success, or an error string on failure
+-- @treturn string|boolean On success: the stripped Component name if the name had the Reject Prefix, otherwise false
 function Components.try(name, acceptRejected)
    if type(name) ~= "string" then
       return false, "ComponentsClass name is expected to be a string, got "..type(name)..")"
@@ -54,7 +54,7 @@ end
 
 --- Returns the ComponentClass with the specified name
 -- @string name Name of the ComponentClass to get
--- @treturn Component
+-- @treturn Component The registered ComponentClass
 function Components.get(name)
    local ok, value = Components.try(name)
 

concord/entity.lua

@@ -13,6 +13,7 @@ local Builtins   = require(PATH..".builtins.init") --luacheck: ignore
 -- Builtins is unused but the require already registers the Components
 
 local Entity = {
+   --- If true, new Entities are given a "serializable" Component.
    SERIALIZE_BY_DEFAULT = true,
 }
 
@@ -20,7 +21,8 @@ Entity.__mt = {
    __index = Entity,
 }
 
---- Creates a new Entity. Optionally adds it to a World.
+--- Creates a new Entity. Optionally queues it to be added to a World.
+-- If Entity.SERIALIZE_BY_DEFAULT is true, the Entity is given a "serializable" Component.
 -- @tparam[opt] World world World to add the entity to
 -- @treturn Entity A new Entity
 function Entity.new(world)
@@ -121,25 +123,25 @@ local function removeComponent(e, name)
 end
 
 --- Gives an Entity a Component.
--- If the Component already exists, it's overridden by this new Component
--- @tparam Component componentClass ComponentClass to add an instance of
--- @param ... additional arguments to pass to the Component's populate function
+-- If the Component already exists, it's overridden by this new Component.
+-- @tparam string|Component name Name of the ComponentClass, or a Component instance to copy onto the Entity
+-- @param ... additional arguments to pass to the Component's populate function (ignored when copying a Component)
 -- @treturn Entity self
 function Entity:give(name, ...)
    return giveComponent(self, false, name, ...)
 end
 
---- Ensures an Entity to have a Component.
--- If the Component already exists, no action is taken
--- @tparam Component componentClass ComponentClass to add an instance of
--- @param ... additional arguments to pass to the Component's populate function
+--- Ensures an Entity has a Component.
+-- If the Component already exists, no action is taken.
+-- @tparam string|Component name Name of the ComponentClass, or a Component instance to copy onto the Entity
+-- @param ... additional arguments to pass to the Component's populate function (ignored when copying a Component)
 -- @treturn Entity self
 function Entity:ensure(name, ...)
    return giveComponent(self, true, name, ...)
 end
 
 --- Removes a Component from an Entity.
--- @tparam Component componentClass ComponentClass of the Component to remove
+-- @string name Name of the ComponentClass to remove
 -- @treturn Entity self
 function Entity:remove(name)
    local ok, componentClass = Components.try(name)
@@ -168,8 +170,8 @@ function Entity:assemble(assemblage, ...)
 end
 
 --- Destroys the Entity.
--- Removes the Entity from its World if it's in one.
--- @return self
+-- Queues removal from its World if it's in one. The Entity stays in the World until the next flush.
+-- @treturn Entity self
 function Entity:destroy()
    if self.__world then
       self.__world:removeEntity(self)
@@ -189,7 +191,7 @@ function Entity:__dirty()
 end
 
 --- Returns true if the Entity has a Component.
--- @tparam Component componentClass ComponentClass of the Component to check
+-- @string name Name of the ComponentClass to check
 -- @treturn boolean
 function Entity:has(name)
    local ok, componentClass = Components.try(name)
@@ -202,8 +204,8 @@ function Entity:has(name)
 end
 
 --- Gets a Component from the Entity.
--- @tparam Component componentClass ComponentClass of the Component to get
--- @treturn table
+-- @string name Name of the ComponentClass to get
+-- @treturn Component|nil The Component, or nil if the Entity does not have it
 function Entity:get(name)
    local ok, componentClass = Components.try(name)
 
@@ -214,10 +216,11 @@ function Entity:get(name)
    return self[name]
 end
 
---- Returns a table of all Components the Entity has.
--- Warning: Do not modify this table.
--- Use Entity:give/ensure/remove instead
--- @treturn table Table of all Components the Entity has
+--- Returns a shallow copy of the Entity's fields, excluding __world and __isEntity.
+-- This is primarily the Entity's Components. Extra non-component fields are also copied.
+-- Mutating a copied Component still mutates the Entity's Component.
+-- @tparam[opt] table output Table to copy into. A new table is created if omitted.
+-- @treturn table
 function Entity:getComponents(output)
    output = output or {}
    local components = Utils.shallowCopy(self, output)
@@ -227,7 +230,8 @@ function Entity:getComponents(output)
    return components
 end
 
---- Returns true if the Entity is in a World.
+--- Returns true if the Entity has been assigned a World.
+-- True as soon as addition is queued, and remains true until removal is flushed.
 -- @treturn boolean
 function Entity:inWorld()
    return self.__world and true or false
@@ -239,6 +243,10 @@ function Entity:getWorld()
    return self.__world
 end
 
+--- Serializes the Entity's Components.
+-- Components that return nil from serialize are omitted.
+-- @tparam[opt] boolean ignoreKey If true, the key Component is omitted
+-- @treturn table Serialized Entity data
 function Entity:serialize(ignoreKey)
    local data = {}
 
@@ -262,6 +270,8 @@ function Entity:serialize(ignoreKey)
    return data
 end
 
+--- Deserializes Components onto the Entity.
+-- @tparam table data Serialized Entity data
 function Entity:deserialize(data)
    for i = 1, #data do
       local componentData = data[i]

concord/filter.lua

@@ -16,9 +16,12 @@ Filter.__mt = {
 }
 
 --- Validates a Filter Definition to make sure every component is valid.
--- @string name Name for the Filter.
--- @tparam table definition Table containing the Filter Definition
--- @tparam onComponent Optional function, called when a component is valid.
+-- Also checks that def.constructor is callable when present, unless onComponent is provided.
+-- @int errorLevel Extra stack level added to error reports
+-- @tparam[opt] string name Name for the Filter. If omitted, errors refer to a World:query filter.
+-- @tparam table def Table containing the Filter Definition
+-- @tparam[opt] function onComponent Called with (component, reject) when a component is valid.
+-- reject is the stripped Component name when the entry had the Reject Prefix, otherwise false.
 function Filter.validate (errorLevel, name, def, onComponent)
    local filter = "World:query filter"
    if name then
@@ -46,13 +49,12 @@ function Filter.validate (errorLevel, name, def, onComponent)
    end
 end
 
---- Parses the Filter Defintion into two tables
--- required: An array of all the required component names.
--- rejected: An array of all the components that will be rejected.
--- @string name Name for the Filter.
--- @tparam table definition Table containing the Filter Definition
--- @treturn table required
--- @treturn table rejected
+--- Parses a Filter Definition into a single interleaved table.
+-- Entries are stored as name, required pairs: {name, true, name, false, ...}
+-- where true means the Component is required and false means it is rejected.
+-- @tparam[opt] string name Name for the Filter.
+-- @tparam table def Table containing the Filter Definition
+-- @treturn table Parsed filter
 function Filter.parse (name, def)
    local filter = {}
 
@@ -69,6 +71,10 @@ function Filter.parse (name, def)
    return filter
 end
 
+--- Returns true if the Entity matches a parsed Filter.
+-- @tparam Entity e Entity to check
+-- @tparam table filter Parsed filter from Filter.parse
+-- @treturn boolean
 function Filter.match (e, filter)
    for i=#filter, 2, -2 do
       local match = filter[i - 0]
@@ -83,6 +89,10 @@ end
 local REQUIRED_METHODS = {"add", "remove", "has", "clear"}
 local VALID_POOL_TYPES = {table=true, userdata=true, lightuserdata=true, cdata=true}
 
+--- Checks that a custom Pool implements add, remove, has, and clear as callables.
+-- The Pool may be a table, userdata, lightuserdata, or cdata.
+-- @string name Name of the Filter / Pool
+-- @param pool Pool returned by a custom constructor
 function Filter.isValidPool (name, pool)
    local poolType = type(pool)
    --Check that pool is not nil
@@ -99,8 +109,9 @@ function Filter.isValidPool (name, pool)
 end
 
 --- Creates a new Filter
+-- If definition.constructor is set, it is called with the definition to create the Pool.
 -- @string name Name for the Filter.
--- @tparam table definition Table containing the Filter Definition
+-- @tparam table def Table containing the Filter Definition
 -- @treturn Filter The new Filter
 -- @treturn Pool The associated Pool
 function Filter.new (name, def)
@@ -134,6 +145,10 @@ function Filter:eligible(e)
    return Filter.match(e, self.__filter)
 end
 
+--- Evaluates an Entity against this Filter and updates the Pool.
+-- Adds the Entity if it became eligible, removes it if it no longer is.
+-- @tparam Entity e Entity to evaluate
+-- @treturn Filter self
 function Filter:evaluate (e)
    local has  = self.pool:has(e)
    local eligible = self:eligible(e)
@@ -148,9 +163,9 @@ function Filter:evaluate (e)
 end
 
 
--- Adds an Entity to the Pool, if it passes the Filter.
--- @param e Entity to add
--- @param bypass Whether to bypass the Filter or not.
+--- Adds an Entity to the Pool, if it passes the Filter.
+-- @tparam Entity e Entity to add
+-- @tparam[opt] boolean bypass Whether to bypass the Filter or not.
 -- @treturn Filter self
 -- @treturn boolean Whether the entity was added or not.
 function Filter:add (e, bypass)
@@ -163,24 +178,25 @@ function Filter:add (e, bypass)
    return self, true
 end
 
--- Remove an Entity from the Pool associated to this Filter.
--- @param e Entity to remove
+--- Removes an Entity from the Pool associated to this Filter.
+-- @tparam Entity e Entity to remove
 -- @treturn Filter self
 function Filter:remove (e)
    self.pool:remove(e)
    return self
 end
 
--- Clear the Pool associated to this Filter.
--- @param e Entity to remove
+--- Clears the Pool associated to this Filter.
+-- Arguments are forwarded to the Pool's clear method.
+-- @param e Forwarded to pool:clear
 -- @treturn Filter self
 function Filter:clear (e)
    self.pool:clear(e)
    return self
 end
 
--- Check if the Pool bound to this System contains the passed Entity
--- @param e Entity to check
+--- Checks if the Pool associated to this Filter contains the passed Entity.
+-- @tparam Entity e Entity to check
 -- @treturn boolean Whether the Entity exists.
 function Filter:has (e)
    return self.pool:has(e)

concord/init.lua

@@ -1,5 +1,11 @@
----
+--- A feature-complete ECS library.
 -- @module Concord
+-- @field Entity Entity class
+-- @field Component Component class
+-- @field Components Registry of ComponentClasses
+-- @field System System class
+-- @field World World class
+-- @field utils Utility functions
 
 local PATH = (...):gsub("%.init$", "")
 

concord/list.lua

@@ -1,4 +1,4 @@
---- Data structure that allows for fast removal at the cost of containing order.
+--- Data structure that allows for fast removal at the cost of order.
 -- @classmod List
 
 local List = {}
@@ -32,7 +32,7 @@ end
 
 --- Removes an object from the List.
 -- @param obj Object to remove
--- @treturn List self
+-- @treturn List|nil self, or nil if the object was not in the List
 function List:remove(obj)
    local index = self[obj]
    if not index then return end
@@ -57,6 +57,7 @@ function List:remove(obj)
 end
 
 --- Clears the List completely.
+-- Does not call onRemoved.
 -- @treturn List self
 function List:clear()
    for i = 1, self.size do
@@ -86,6 +87,7 @@ function List:get(i)
 end
 
 --- Returns the index of an object in the List.
+-- Errors if the object is not in the List.
 -- @param obj Object to get index of
 -- @treturn number index of object in the List.
 function List:indexOf(obj)
@@ -98,7 +100,7 @@ end
 
 --- Sorts the List in place, using the order function.
 -- The order function is passed to table.sort internally so documentation on table.sort can be used as reference.
--- @param order Function that takes two Entities (a and b) and returns true if a should go before than b.
+-- @param order Function that takes two items (a and b) and returns true if a should go before b.
 -- @treturn List self
 function List:sort(order)
    table.sort(self, order)
@@ -115,7 +117,7 @@ end
 function List:onAdded (obj) --luacheck: ignore
 end
 
---- Callback for when an item is removed to the List.
+--- Callback for when an item is removed from the List.
 -- @param obj Object that was removed
 function List:onRemoved (obj) --luacheck: ignore
 end

concord/system.lua

@@ -1,5 +1,5 @@
---- Iterates over Entities. From these Entities its get Components and modify them.
--- A System contains 1 or more Pools.
+--- Iterates over Entities. From these Entities it gets Components and modifies them.
+-- A System contains 0 or more Pools.
 -- A System is contained by 1 World.
 -- @classmod System
 
@@ -25,9 +25,9 @@ System.mt = {
          __isSystemClass = false, -- Overwrite value from systemClass
       }, systemClass)
 
-      -- Optimization: We deep copy the System class into our instance of a system.
+      -- Optimization: We shallow copy the System class into our instance of a system.
       -- This grants slightly faster access times at the cost of memory.
-      -- Since there (generally) won't be many instances of worlds this is a worthwhile tradeoff
+      -- Since there (generally) won't be many instances of systems this is a worthwhile tradeoff
       if (System.ENABLE_OPTIMIZATION) then
          Utils.shallowCopy(systemClass, system)
       end
@@ -45,8 +45,8 @@ System.mt = {
    end,
 }
 --- Creates a new SystemClass.
--- @string name Name of the System
--- @tparam table definition A table containing filters (name = {components...})
+-- @tparam[opt] string name Name of the System. If omitted, or if a table is passed first, the first argument is the definition.
+-- @tparam[opt] table definition A table containing filters (name = {components...})
 -- @treturn System A new SystemClass
 function System.new(name, definition)
    if type(name) == "table" then
@@ -74,9 +74,9 @@ function System.new(name, definition)
    }, System.mt)
    systemClass.__index = systemClass
 
-   -- Optimization: We deep copy the World class into our instance of a world.
+   -- Optimization: We shallow copy the System class into the SystemClass.
    -- This grants slightly faster access times at the cost of memory.
-   -- Since there (generally) won't be many instances of worlds this is a worthwhile tradeoff
+   -- Since there (generally) won't be many instances of systems this is a worthwhile tradeoff
    if (System.ENABLE_OPTIMIZATION) then
       Utils.shallowCopy(System, systemClass)
    end
@@ -118,7 +118,7 @@ function System:__clear()
    return self
 end
 
---- Sets if the System is enabled
+--- Sets whether the System is enabled.
 -- @tparam boolean enable
 -- @treturn System self
 function System:setEnabled(enable)
@@ -133,7 +133,7 @@ function System:setEnabled(enable)
    return self
 end
 
---- Returns is the System is enabled
+--- Returns whether the System is enabled.
 -- @treturn boolean
 function System:isEnabled()
    return self.__enabled

concord/type.lua

@@ -1,8 +1,11 @@
---- Type
--- Helper module to do easy type checking for Concord types
+--- Helper module to do easy type checking for Concord types
+-- @module Type
 
 local Type = {}
 
+--- Returns true if the value is a function or has a __call metamethod.
+-- @param t Object to check
+-- @treturn boolean
 function Type.isCallable(t)
    if type(t) == "function" then return true end
 

concord/utils.lua

@@ -1,15 +1,20 @@
---- Utils
--- Helper module for misc operations
+--- Helper module for misc operations
+-- @module Utils
 
 local Utils = {}
 
+--- Raises a formatted error.
+-- @int level Error level passed to error(), plus one
+-- @string str Format string
+-- @param ... Format arguments
 function Utils.error(level, str, ...)
     error(string.format(str, ...), level + 1)
 end
 
---- Does a shallow copy of a table and appends it to a target table.
--- @param orig Table to copy
--- @param target Table to append to
+--- Copies keys from orig into target. Existing keys in target are overwritten.
+-- @tparam table orig Table to copy from
+-- @tparam table target Table to copy into
+-- @treturn table target
 function Utils.shallowCopy(orig, target)
    for key, value in pairs(orig) do
       target[key] = value
@@ -18,12 +23,14 @@ function Utils.shallowCopy(orig, target)
    return target
 end
 
---- Requires files and puts them in a table.
--- Accepts a table of paths to Lua files: {"path/to/file_1", "path/to/another/file_2", "etc"}
--- Accepts a path to a directory with Lua files: "my_files/here"
--- @param pathOrFiles The table of paths or a path to a directory.
--- @param namespace A table that will hold the required files
--- @treturn table The namespace table
+--- Requires files and stores them in a namespace table.
+-- Accepts a table of require paths: {"path/to/file_1", "path/to/another/file_2", "etc"}
+-- Accepts a path to a directory of Lua files: "my_files/here"
+-- Directory loading uses love.filesystem and requires LÖVE.
+-- If namespace is omitted, files are still required and this function returns nil.
+-- @param pathOrFiles A directory path or a table of require paths
+-- @tparam[opt] table namespace Table that will hold the required files
+-- @treturn table|nil The namespace table
 function Utils.loadNamespace(pathOrFiles, namespace)
    if type(pathOrFiles) ~= "string" and type(pathOrFiles) ~= "table" then
        Utils.error(2, "bad argument #1 to 'loadNamespace' (string/table of strings expected, got %s)", type(pathOrFiles))

concord/world.lua

@@ -1,7 +1,6 @@
 --- A collection of Systems and Entities.
--- A world emits to let Systems iterate.
--- A World contains any amount of Systems.
--- A World contains any amount of Entities.
+-- A World emits events so Systems can iterate their Pools.
+-- A World contains any amount of Systems and Entities, plus optional named resources.
 -- @classmod World
 
 local PATH = (...):gsub('%.[^%.]+$', '')
@@ -57,7 +56,7 @@ function World.new()
       __flushing = false,
    }, World.__mt)
 
-   -- Optimization: We deep copy the World class into our instance of a world.
+   -- Optimization: We shallow copy the World class into our instance of a world.
    -- This grants slightly faster access times at the cost of memory.
    -- Since there (generally) won't be many instances of worlds this is a worthwhile tradeoff
    if (World.ENABLE_OPTIMIZATION) then
@@ -67,7 +66,9 @@ function World.new()
    return world
 end
 
---- Adds an Entity to the World.
+--- Queues an Entity to be added to the World.
+-- The Entity's world is set immediately. The Entity is not in getEntities()
+-- and is not evaluated by Systems until the next flush.
 -- @tparam Entity e Entity to add
 -- @treturn World self
 function World:addEntity(e)
@@ -85,12 +86,20 @@ function World:addEntity(e)
    return self
 end
 
---- Creates a new Entity and adds it to the World.
+--- Creates a new Entity and queues it to be added to the World.
 -- @treturn Entity e the new Entity
 function World:newEntity()
    return Entity(self)
 end
 
+--- Queries flushed Entities against a Filter definition.
+-- Pending (not yet flushed) additions are not included. Component changes on
+-- already flushed Entities are visible immediately.
+-- If onMatch is a callable it is invoked for each match and nothing is returned.
+-- Otherwise matches are appended to onMatch when it is a table, or to a new table.
+-- @tparam table def Filter definition (component names, with ! prefix to reject)
+-- @tparam[opt] function|table onMatch Callback for each match, or a table to fill
+-- @treturn table|nil The list of matches, or nil if onMatch was a callback
 function World:query(def, onMatch)
    local filter = Filter.parse(nil, def)
 
@@ -112,7 +121,9 @@ function World:query(def, onMatch)
    return list
 end
 
---- Removes an Entity from the World.
+--- Queues an Entity to be removed from the World.
+-- If the Entity has a key Component, it is removed first.
+-- The Entity remains in the World until the next flush.
 -- @tparam Entity e Entity to remove
 -- @treturn World self
 function World:removeEntity(e)
@@ -149,8 +160,8 @@ function World:canFlush()
    return not self.__flushing
 end
 
---- Flushes all changes to Entities.
--- This processes all entities. Adding and removing entities, as well as reevaluating dirty entities.
+--- Applies queued Entity additions, removals, and dirty reevaluations.
+-- Only the queued buffers are processed, not every Entity in the World.
 -- @treturn World self
 function World:flush()
    if not self:canFlush() then
@@ -221,7 +232,8 @@ function World:flush()
    return self
 end
 
--- These functions won't be seen as callbacks that will be emitted to.
+-- Callback names that should not be registered as World events.
+-- This table is an array, so lookup by callback name never matches.
 local blacklistedSystemFunctions = {
    "init",
    "onEnabled",
@@ -269,8 +281,8 @@ local tryAddSystem = function (world, systemClass)
 end
 
 --- Adds a System to the World.
--- Callbacks are registered automatically
--- Entities added before are added to the System retroactively
+-- Functions on the SystemClass are registered as event listeners.
+-- Entities already in the World are evaluated against the System's Filters.
 -- @see World:emit
 -- @tparam System systemClass SystemClass of System to add
 -- @treturn World self
@@ -285,7 +297,7 @@ function World:addSystem(systemClass)
 end
 
 --- Adds multiple Systems to the World.
--- Callbacks are registered automatically
+-- Functions on each SystemClass are registered as event listeners.
 -- @see World:addSystem
 -- @see World:emit
 -- @param ... SystemClasses of Systems to add
@@ -303,7 +315,7 @@ function World:addSystems(...)
    return self
 end
 
---- Returns if the World has a System.
+--- Returns whether the World has a System.
 -- @tparam System systemClass SystemClass of System to check for
 -- @treturn boolean
 function World:hasSystem(systemClass)
@@ -326,9 +338,11 @@ function World:getSystem(systemClass)
 end
 
 --- Emits a callback in the World.
--- Calls all functions with the functionName of added Systems
+-- Calls all functions with the functionName of added Systems.
 -- Automatically flushes before forwarding the event, unless this emit is nested
 -- or a flush is already in progress.
+-- If beforeEmit exists and returns a truthy value, listeners are skipped.
+-- afterEmit is called after listeners when present.
 -- @string functionName Name of functions to call.
 -- @param ... Parameters passed to System's functions
 -- @treturn World self
@@ -391,7 +405,9 @@ function World:emitNoFlush(functionName, ...)
    return self
 end
 
---- Removes all entities from the World
+--- Removes all Entities from the World and flushes.
+-- Entities that were queued to be added are detached immediately without
+-- onEntityRemoved. Already flushed Entities are removed through the normal flush.
 -- @treturn World self
 function World:clear()
    for i = 1, self.__entities.size do
@@ -409,14 +425,22 @@ function World:clear()
    return self
 end
 
+--- Returns the List of flushed Entities in the World.
+-- @treturn List
 function World:getEntities()
    return self.__entities
 end
 
+--- Returns the List of Systems in the World.
+-- @treturn List
 function World:getSystems()
    return self.__systems
 end
 
+--- Serializes serializable Entities in the World.
+-- Flushes first. Only Entities with a serializable Component are included.
+-- @tparam[opt] boolean ignoreKeys If true, Entity keys are omitted
+-- @treturn table Serialized world data
 function World:serialize(ignoreKeys)
    self:flush()
 
@@ -434,6 +458,11 @@ function World:serialize(ignoreKeys)
    return data
 end
 
+--- Deserializes Entities into the World.
+-- @tparam table data Serialized world data
+-- @tparam[opt] boolean startClean If true, existing Entities are cleared first
+-- @tparam[opt] boolean ignoreGenerator If true, the World's key generator state is left unchanged
+-- @treturn World self
 function World:deserialize(data, startClean, ignoreGenerator)
    if startClean then
       self:clear()
@@ -468,6 +497,10 @@ function World:deserialize(data, startClean, ignoreGenerator)
    return self
 end
 
+--- Sets the function used to generate Entity keys.
+-- @tparam function generator Callable that receives the current state and returns key, newState
+-- @param initialState Initial state passed to the generator
+-- @treturn World self
 function World:setKeyGenerator(generator, initialState)
    if not Type.isCallable(generator) then
       Utils.error(2, "bad argument #1 to 'World:setKeyGenerator' (function expected, got %s)", type(generator))
@@ -479,6 +512,7 @@ function World:setKeyGenerator(generator, initialState)
    return self
 end
 
+-- Internal: Clears the key assigned to an Entity.
 function World:__clearKey(e)
    local key = self.__hash.keys[e]
 
@@ -490,6 +524,10 @@ function World:__clearKey(e)
    return self
 end
 
+-- Internal: Assigns a key to an Entity, generating one if needed.
+-- @param e Entity to assign a key to
+-- @param key Optional explicit key
+-- @return The assigned key
 function World:__assignKey(e, key)
    local hash = self.__hash
 
@@ -512,6 +550,9 @@ function World:__assignKey(e, key)
    return key
 end
 
+--- Gets an Entity by its key.
+-- @param key Key to look up
+-- @treturn Entity|nil
 function World:getEntityByKey(key)
    return self.__hash.entities[key]
 end
@@ -526,25 +567,25 @@ end
 function World:onEntityRemoved(e) -- luacheck: ignore
 end
 
---- Sets a named resource in the world
+--- Sets a named resource in the World.
 -- @string name Name of the resource
--- @tparam Any resource Resource to set
+-- @param resource Resource to set
 -- @treturn World self
 function World:setResource(name, resource)
   self.__resources[name] = resource
   return self
 end
 
---- Gets a named resource from the world
+--- Gets a named resource from the World.
 -- @string name Name of the resource
--- @treturn Any resource
+-- @return The resource, or nil if none was set
 function World:getResource(name)
   return self.__resources[name]
 end
 
 return setmetatable(World, {
    __call = function(_, ...)
-      ---@diagnostic disable-next-line: redundant-parameter
+      -- LuaLS: redundant-parameter (World.new takes no arguments)
       return World.new(...)
    end,
 })

config.ld

@@ -1,4 +1,21 @@
 project = 'Concord'
 description = 'A feature-complete ECS library'
-file = {'concord', exclude = {}}
+file = {'concord', exclude = {'concord/init.lua', 'concord/builtins/init.lua'}}
 dir = 'docs'
+
+format = 'markdown'
+use_markdown_titles = true
+
+new_type("builtin", "Builtins", true)
+kind_names = {topic = 'Guides'}
+
+-- Preprocessed by scripts/build-docs.lua
+readme = {
+  '.ldoc-guides/Get-Started.md',
+  '.ldoc-guides/Why-ECS.md',
+  '.ldoc-guides/Custom-Pools.md',
+  '.ldoc-guides/Pool-Flushing-and-Timing.md',
+}
+
+style = '.'
+

docs/builtins/key.html

@@ -0,0 +1,170 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
+<head>
+    <title>Reference</title>
+    <link rel="stylesheet" href="../ldoc.css" type="text/css" />
+</head>
+<body>
+
+<div id="container">
+
+<div id="product">
+	<div id="product_logo"></div>
+	<div id="product_name"><big><b></b></big></div>
+	<div id="product_description"></div>
+</div> <!-- id="product" -->
+
+
+<div id="main">
+
+
+<!-- Menu -->
+
+<div id="navigation">
+<br/>
+<h1>Concord</h1>
+
+
+<ul>
+  <li><a href="../index.html">Getting Started</a></li>
+</ul>
+
+<h2>Contents</h2>
+<ul>
+<li><a href="#Functions">Functions</a></li>
+</ul>
+
+
+<h2>Builtin Components</h2>
+<ul class="nowrap">
+  <li><strong>key</strong></li>
+  <li><a href="../builtins/serializable.html">serializable</a></li>
+</ul>
+<h2>Modules</h2>
+<ul class="nowrap">
+  <li><a href="../modules/Components.html">Components</a></li>
+  <li><a href="../modules/Type.html">Type</a></li>
+  <li><a href="../modules/Utils.html">Utils</a></li>
+</ul>
+<h2>Classes</h2>
+<ul class="nowrap">
+  <li><a href="../classes/Component.html">Component</a></li>
+  <li><a href="../classes/Entity.html">Entity</a></li>
+  <li><a href="../classes/Filter.html">Filter</a></li>
+  <li><a href="../classes/List.html">List</a></li>
+  <li><a href="../classes/System.html">System</a></li>
+  <li><a href="../classes/World.html">World</a></li>
+</ul>
+<h2>Guides</h2>
+<ul class="nowrap">
+  <li><a href="../index.html">Getting Started</a></li>
+  <li><a href="../guides/Why-ECS.md.html">Why ECS? Why Concord?</a></li>
+  <li><a href="../guides/Custom-Pools.md.html">Custom Pools</a></li>
+  <li><a href="../guides/Pool-Flushing-and-Timing.md.html">Pool Flushing and Timing</a></li>
+</ul>
+
+</div>
+
+<div id="content">
+
+<h1>Builtin <code>key</code></h1>
+<p>Built-in Component that assigns a unique key to an Entity in its World.</p>
+<p> The Entity must belong to a World. Calling the Component returns the key value.</p>
+
+
+<h2><a href="#Functions">Functions</a></h2>
+<table class="function_list">
+	<tr>
+	<td class="name" nowrap><a href="#Key:deserialize">Key:deserialize (data)</a></td>
+	<td class="summary">Assigns a key from serialized data.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#Key">Key ()</a></td>
+	<td class="summary">Returns the key value.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#Key:removed">Key:removed (replaced)</a></td>
+	<td class="summary">Callback: Clears the World key when the Component is removed (not replaced).</td>
+	</tr>
+</table>
+
+<br/>
+<br/>
+
+
+    <h2 class="section-header "><a name="Functions"></a>Functions</h2>
+
+    <dl class="function">
+    <dt>
+    <a name = "Key:deserialize"></a>
+    <strong>Key:deserialize (data)</strong>
+    </dt>
+    <dd>
+    Assigns a key from serialized data.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">data</span>
+         Previously serialized key value
+        </li>
+    </ul>
+
+
+
+
+
+</dd>
+    <dt>
+    <a name = "Key"></a>
+    <strong>Key ()</strong>
+    </dt>
+    <dd>
+    Returns the key value.
+
+
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a> or <span class="type">number</span></span>
+        The Entity's key
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "Key:removed"></a>
+    <strong>Key:removed (replaced)</strong>
+    </dt>
+    <dd>
+    Callback: Clears the World key when the Component is removed (not replaced).
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">replaced</span>
+            <span class="types"><span class="type">boolean</span></span>
+         True when the Component is being overwritten
+        </li>
+    </ul>
+
+
+
+
+
+</dd>
+</dl>
+</div> <!-- id="content" -->
+</div> <!-- id="main" -->
+<div id="about">
+<i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
+<i style="float:right;">Last updated 2026-09-06 21:32:30 </i>
+</div> <!-- id="about" -->
+</div> <!-- id="container" -->
+</body>
+</html>

docs/builtins/serializable.html

@@ -0,0 +1,125 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
+<head>
+    <title>Reference</title>
+    <link rel="stylesheet" href="../ldoc.css" type="text/css" />
+</head>
+<body>
+
+<div id="container">
+
+<div id="product">
+	<div id="product_logo"></div>
+	<div id="product_name"><big><b></b></big></div>
+	<div id="product_description"></div>
+</div> <!-- id="product" -->
+
+
+<div id="main">
+
+
+<!-- Menu -->
+
+<div id="navigation">
+<br/>
+<h1>Concord</h1>
+
+
+<ul>
+  <li><a href="../index.html">Getting Started</a></li>
+</ul>
+
+<h2>Contents</h2>
+<ul>
+<li><a href="#Functions">Functions</a></li>
+</ul>
+
+
+<h2>Builtin Components</h2>
+<ul class="nowrap">
+  <li><a href="../builtins/key.html">key</a></li>
+  <li><strong>serializable</strong></li>
+</ul>
+<h2>Modules</h2>
+<ul class="nowrap">
+  <li><a href="../modules/Components.html">Components</a></li>
+  <li><a href="../modules/Type.html">Type</a></li>
+  <li><a href="../modules/Utils.html">Utils</a></li>
+</ul>
+<h2>Classes</h2>
+<ul class="nowrap">
+  <li><a href="../classes/Component.html">Component</a></li>
+  <li><a href="../classes/Entity.html">Entity</a></li>
+  <li><a href="../classes/Filter.html">Filter</a></li>
+  <li><a href="../classes/List.html">List</a></li>
+  <li><a href="../classes/System.html">System</a></li>
+  <li><a href="../classes/World.html">World</a></li>
+</ul>
+<h2>Guides</h2>
+<ul class="nowrap">
+  <li><a href="../index.html">Getting Started</a></li>
+  <li><a href="../guides/Why-ECS.md.html">Why ECS? Why Concord?</a></li>
+  <li><a href="../guides/Custom-Pools.md.html">Custom Pools</a></li>
+  <li><a href="../guides/Pool-Flushing-and-Timing.md.html">Pool Flushing and Timing</a></li>
+</ul>
+
+</div>
+
+<div id="content">
+
+<h1>Builtin <code>serializable</code></h1>
+<p>Built-in marker Component.</p>
+<p> Entities with this Component are included in World:serialize.
+ The Component itself is not serialized.</p>
+
+
+<h2><a href="#Functions">Functions</a></h2>
+<table class="function_list">
+	<tr>
+	<td class="name" nowrap><a href="#Serializable:serialize">Serializable:serialize ()</a></td>
+	<td class="summary">Callback: When the Component gets serialized as part of an Entity.</td>
+	</tr>
+</table>
+
+<br/>
+<br/>
+
+
+    <h2 class="section-header "><a name="Functions"></a>Functions</h2>
+
+    <dl class="function">
+    <dt>
+    <a name = "Serializable:serialize"></a>
+    <strong>Serializable:serialize ()</strong>
+    </dt>
+    <dd>
+    Callback: When the Component gets serialized as part of an Entity.
+ Returns nil so this marker is not written to serialized data.
+
+
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><span class="type">nil</span></span>
+
+
+
+    </ol>
+
+
+
+
+</dd>
+</dl>
+</div> <!-- id="content" -->
+</div> <!-- id="main" -->
+<div id="about">
+<i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
+<i style="float:right;">Last updated 2026-09-06 21:32:30 </i>
+</div> <!-- id="about" -->
+</div> <!-- id="container" -->
+</body>
+</html>

docs/classes/Assemblage.html

@@ -1,204 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html>
-<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
-<head>
-    <title>Reference</title>
-    <link rel="stylesheet" href="../ldoc.css" type="text/css" />
-</head>
-<body>
-
-<div id="container">
-
-<div id="product">
-	<div id="product_logo"></div>
-	<div id="product_name"><big><b></b></big></div>
-	<div id="product_description"></div>
-</div> <!-- id="product" -->
-
-
-<div id="main">
-
-
-<!-- Menu -->
-
-<div id="navigation">
-<br/>
-<h1>Concord</h1>
-
-<ul>
-  <li><a href="../index.html">Index</a></li>
-</ul>
-
-<h2>Contents</h2>
-<ul>
-<li><a href="#Methods">Methods</a></li>
-</ul>
-
-
-<h2>Classes</h2>
-<ul class="nowrap">
-  <li><strong>Assemblage</strong></li>
-  <li><a href="../classes/Component.html">Component</a></li>
-  <li><a href="../classes/Entity.html">Entity</a></li>
-  <li><a href="../classes/List.html">List</a></li>
-  <li><a href="../classes/Pool.html">Pool</a></li>
-  <li><a href="../classes/System.html">System</a></li>
-  <li><a href="../classes/World.html">World</a></li>
-</ul>
-<h2>Modules</h2>
-<ul class="nowrap">
-  <li><a href="../modules/Assemblages.html">Assemblages</a></li>
-  <li><a href="../modules/Components.html">Components</a></li>
-  <li><a href="../modules/Concord.html">Concord</a></li>
-  <li><a href="../modules/Systems.html">Systems</a></li>
-  <li><a href="../modules/type.html">type</a></li>
-  <li><a href="../modules/utils.html">utils</a></li>
-  <li><a href="../modules/worlds.html">worlds</a></li>
-</ul>
-
-</div>
-
-<div id="content">
-
-<h1>Class <code>Assemblage</code></h1>
-<p>Gives an entity a set of components.</p>
-<p></p>
-
-
-<h2><a href="#Methods">Methods</a></h2>
-<table class="function_list">
-	<tr>
-	<td class="name" nowrap><a href="#Assemblage:new">Assemblage:new (assemble)</a></td>
-	<td class="summary">Creates a new Assemblage.</td>
-	</tr>
-	<tr>
-	<td class="name" nowrap><a href="#Assemblage:assemble">Assemblage:assemble (e, ...)</a></td>
-	<td class="summary">Assembles an Entity.</td>
-	</tr>
-	<tr>
-	<td class="name" nowrap><a href="#Assemblage:hasName">Assemblage:hasName ()</a></td>
-	<td class="summary">Returns true if the Assemblage has a name.</td>
-	</tr>
-	<tr>
-	<td class="name" nowrap><a href="#Assemblage:getName">Assemblage:getName ()</a></td>
-	<td class="summary">Returns the name of the Assemblage.</td>
-	</tr>
-</table>
-
-<br/>
-<br/>
-
-
-    <h2 class="section-header "><a name="Methods"></a>Methods</h2>
-
-    <dl class="function">
-    <dt>
-    <a name = "Assemblage:new"></a>
-    <strong>Assemblage:new (assemble)</strong>
-    </dt>
-    <dd>
-    Creates a new Assemblage.
-
-
-    <h3>Parameters:</h3>
-    <ul>
-        <li><span class="parameter">assemble</span>
-            <span class="types"><span class="type">function</span></span>
-         Function that assembles an Entity
-        </li>
-    </ul>
-
-    <h3>Returns:</h3>
-    <ol>
-
-           <span class="types"><a class="type" href="../classes/Assemblage.html#">Assemblage</a></span>
-        A new assemblage
-    </ol>
-
-
-
-
-</dd>
-    <dt>
-    <a name = "Assemblage:assemble"></a>
-    <strong>Assemblage:assemble (e, ...)</strong>
-    </dt>
-    <dd>
-    Assembles an Entity.
-
-
-    <h3>Parameters:</h3>
-    <ul>
-        <li><span class="parameter">e</span>
-            <span class="types"><a class="type" href="../classes/Entity.html#">Entity</a></span>
-         Entity to assemble
-        </li>
-        <li><span class="parameter">...</span>
-         additional arguments to pass to the assemble function
-        </li>
-    </ul>
-
-    <h3>Returns:</h3>
-    <ol>
-
-           <span class="types"><a class="type" href="../classes/Assemblage.html#">Assemblage</a></span>
-        self
-    </ol>
-
-
-
-
-</dd>
-    <dt>
-    <a name = "Assemblage:hasName"></a>
-    <strong>Assemblage:hasName ()</strong>
-    </dt>
-    <dd>
-    Returns true if the Assemblage has a name.
-
-
-
-    <h3>Returns:</h3>
-    <ol>
-
-           <span class="types"><span class="type">boolean</span></span>
-
-    </ol>
-
-
-
-
-</dd>
-    <dt>
-    <a name = "Assemblage:getName"></a>
-    <strong>Assemblage:getName ()</strong>
-    </dt>
-    <dd>
-    Returns the name of the Assemblage.
-
-
-
-    <h3>Returns:</h3>
-    <ol>
-
-           <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
-
-    </ol>
-
-
-
-
-</dd>
-</dl>
-
-
-</div> <!-- id="content" -->
-</div> <!-- id="main" -->
-<div id="about">
-<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-01-04 10:27:07 </i>
-</div> <!-- id="about" -->
-</div> <!-- id="container" -->
-</body>
-</html>

docs/classes/Component.html

@@ -26,8 +26,9 @@
 <br/>
 <h1>Concord</h1>
 
+
 <ul>
-  <li><a href="../index.html">Index</a></li>
+  <li><a href="../index.html">Getting Started</a></li>
 </ul>
 
 <h2>Contents</h2>
@@ -40,17 +41,28 @@
 <ul class="nowrap">
   <li><strong>Component</strong></li>
   <li><a href="../classes/Entity.html">Entity</a></li>
+  <li><a href="../classes/Filter.html">Filter</a></li>
   <li><a href="../classes/List.html">List</a></li>
-  <li><a href="../classes/Pool.html">Pool</a></li>
   <li><a href="../classes/System.html">System</a></li>
   <li><a href="../classes/World.html">World</a></li>
 </ul>
+<h2>Builtin Components</h2>
+<ul class="nowrap">
+  <li><a href="../builtins/key.html">key</a></li>
+  <li><a href="../builtins/serializable.html">serializable</a></li>
+</ul>
 <h2>Modules</h2>
 <ul class="nowrap">
   <li><a href="../modules/Components.html">Components</a></li>
-  <li><a href="../modules/Concord.html">Concord</a></li>
-  <li><a href="../modules/type.html">type</a></li>
-  <li><a href="../modules/utils.html">utils</a></li>
+  <li><a href="../modules/Type.html">Type</a></li>
+  <li><a href="../modules/Utils.html">Utils</a></li>
+</ul>
+<h2>Guides</h2>
+<ul class="nowrap">
+  <li><a href="../index.html">Getting Started</a></li>
+  <li><a href="../guides/Why-ECS.md.html">Why ECS? Why Concord?</a></li>
+  <li><a href="../guides/Custom-Pools.md.html">Custom Pools</a></li>
+  <li><a href="../guides/Pool-Flushing-and-Timing.md.html">Pool Flushing and Timing</a></li>
 </ul>
 
 </div>
@@ -59,21 +71,35 @@
 
 <h1>Class <code>Component</code></h1>
 <p>A pure data container that is contained by a single entity.</p>
-<p></p>
+<p>
+
+</p>
 
 
 <h2><a href="#Methods">Methods</a></h2>
 <table class="function_list">
 	<tr>
-	<td class="name" nowrap><a href="#Component:new">Component:new (populate)</a></td>
-	<td class="summary">Creates a new ComponentClass.</td>
+	<td class="name" nowrap><a href="#component:new">component:new (name[, populate])</a></td>
+	<td class="summary">Creates a new ComponentClass and registers it by name.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#Component:hasName">Component:hasName ()</a></td>
+	<td class="name" nowrap><a href="#component:removed">component:removed (replaced)</a></td>
+	<td class="summary">Callback: When the Component gets removed or replaced in an Entity.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#component:serialize">component:serialize ()</a></td>
+	<td class="summary">Callback: When the Component gets serialized as part of an Entity.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#component:deserialize">component:deserialize (data)</a></td>
+	<td class="summary">Callback: When the Component gets deserialized from serialized data.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#component:hasName">component:hasName ()</a></td>
 	<td class="summary">Returns true if the Component has a name.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#Component:getName">Component:getName ()</a></td>
+	<td class="name" nowrap><a href="#component:getName">component:getName ()</a></td>
 	<td class="summary">Returns the name of the Component.</td>
 	</tr>
 </table>
@@ -86,18 +112,23 @@
 
     <dl class="function">
     <dt>
-    <a name = "Component:new"></a>
-    <strong>Component:new (populate)</strong>
+    <a name = "component:new"></a>
+    <strong>component:new (name[, populate])</strong>
     </dt>
     <dd>
-    Creates a new ComponentClass.
+    Creates a new ComponentClass and registers it by name.
 
 
     <h3>Parameters:</h3>
     <ul>
+        <li><span class="parameter">name</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
+         Unique name of the ComponentClass
+        </li>
         <li><span class="parameter">populate</span>
             <span class="types"><span class="type">function</span></span>
          Function that populates a Component with values
+         (<em>optional</em>)
         </li>
     </ul>
 
@@ -113,8 +144,70 @@
 
 </dd>
     <dt>
-    <a name = "Component:hasName"></a>
-    <strong>Component:hasName ()</strong>
+    <a name = "component:removed"></a>
+    <strong>component:removed (replaced)</strong>
+    </dt>
+    <dd>
+    Callback: When the Component gets removed or replaced in an Entity.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">replaced</span>
+            <span class="types"><span class="type">boolean</span></span>
+         True when the Component is being overwritten, false when it is being removed
+        </li>
+    </ul>
+
+
+
+
+
+</dd>
+    <dt>
+    <a name = "component:serialize"></a>
+    <strong>component:serialize ()</strong>
+    </dt>
+    <dd>
+    Callback: When the Component gets serialized as part of an Entity.
+
+
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a> or <span class="type">nil</span></span>
+        Serialized data, or nil to omit this Component
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "component:deserialize"></a>
+    <strong>component:deserialize (data)</strong>
+    </dt>
+    <dd>
+    Callback: When the Component gets deserialized from serialized data.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">data</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span>
+         Serialized data to copy onto this Component
+        </li>
+    </ul>
+
+
+
+
+
+</dd>
+    <dt>
+    <a name = "component:hasName"></a>
+    <strong>component:hasName ()</strong>
     </dt>
     <dd>
     Returns true if the Component has a name.
@@ -126,6 +219,8 @@
 
            <span class="types"><span class="type">boolean</span></span>
 
+
+
     </ol>
 
 
@@ -133,8 +228,8 @@
 
 </dd>
     <dt>
-    <a name = "Component:getName"></a>
-    <strong>Component:getName ()</strong>
+    <a name = "component:getName"></a>
+    <strong>component:getName ()</strong>
     </dt>
     <dd>
     Returns the name of the Component.
@@ -144,7 +239,9 @@
     <h3>Returns:</h3>
     <ol>
 
-           <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
+           <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
+
+
 
     </ol>
 
@@ -153,13 +250,11 @@
 
 </dd>
 </dl>
-
-
 </div> <!-- id="content" -->
 </div> <!-- id="main" -->
 <div id="about">
-<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-08-18 15:20:32 </i>
+<i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
+<i style="float:right;">Last updated 2026-09-06 21:32:30 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/classes/Entity.html

@@ -26,12 +26,14 @@
 <br/>
 <h1>Concord</h1>
 
+
 <ul>
-  <li><a href="../index.html">Index</a></li>
+  <li><a href="../index.html">Getting Started</a></li>
 </ul>
 
 <h2>Contents</h2>
 <ul>
+<li><a href="#Fields">Fields</a></li>
 <li><a href="#Methods">Methods</a></li>
 </ul>
 
@@ -40,17 +42,28 @@
 <ul class="nowrap">
   <li><a href="../classes/Component.html">Component</a></li>
   <li><strong>Entity</strong></li>
+  <li><a href="../classes/Filter.html">Filter</a></li>
   <li><a href="../classes/List.html">List</a></li>
-  <li><a href="../classes/Pool.html">Pool</a></li>
   <li><a href="../classes/System.html">System</a></li>
   <li><a href="../classes/World.html">World</a></li>
 </ul>
+<h2>Builtin Components</h2>
+<ul class="nowrap">
+  <li><a href="../builtins/key.html">key</a></li>
+  <li><a href="../builtins/serializable.html">serializable</a></li>
+</ul>
 <h2>Modules</h2>
 <ul class="nowrap">
   <li><a href="../modules/Components.html">Components</a></li>
-  <li><a href="../modules/Concord.html">Concord</a></li>
-  <li><a href="../modules/type.html">type</a></li>
-  <li><a href="../modules/utils.html">utils</a></li>
+  <li><a href="../modules/Type.html">Type</a></li>
+  <li><a href="../modules/Utils.html">Utils</a></li>
+</ul>
+<h2>Guides</h2>
+<ul class="nowrap">
+  <li><a href="../index.html">Getting Started</a></li>
+  <li><a href="../guides/Why-ECS.md.html">Why ECS? Why Concord?</a></li>
+  <li><a href="../guides/Custom-Pools.md.html">Custom Pools</a></li>
+  <li><a href="../guides/Pool-Flushing-and-Timing.md.html">Pool Flushing and Timing</a></li>
 </ul>
 
 </div>
@@ -63,67 +76,101 @@
  contains components which are processed by systems.</p>
 
 
+<h2><a href="#Fields">Fields</a></h2>
+<table class="function_list">
+	<tr>
+	<td class="name" nowrap><a href="#entity.SERIALIZE_BY_DEFAULT">entity.SERIALIZE_BY_DEFAULT</a></td>
+	<td class="summary">If true, new Entities are given a "serializable" Component.</td>
+	</tr>
+</table>
 <h2><a href="#Methods">Methods</a></h2>
 <table class="function_list">
 	<tr>
-	<td class="name" nowrap><a href="#Entity:new">Entity:new ([world])</a></td>
+	<td class="name" nowrap><a href="#entity:new">entity:new ([world])</a></td>
 	<td class="summary">Creates a new Entity.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#Entity:give">Entity:give (componentClass, ...)</a></td>
+	<td class="name" nowrap><a href="#entity:give">entity:give (name, ...)</a></td>
 	<td class="summary">Gives an Entity a Component.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#Entity:ensure">Entity:ensure (componentClass, ...)</a></td>
-	<td class="summary">Ensures an Entity to have a Component.</td>
+	<td class="name" nowrap><a href="#entity:ensure">entity:ensure (name, ...)</a></td>
+	<td class="summary">Ensures an Entity has a Component.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#Entity:remove">Entity:remove (componentClass)</a></td>
+	<td class="name" nowrap><a href="#entity:remove">entity:remove (name)</a></td>
 	<td class="summary">Removes a Component from an Entity.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#Entity:assemble">Entity:assemble (assemblage, ...)</a></td>
+	<td class="name" nowrap><a href="#entity:assemble">entity:assemble (assemblage, ...)</a></td>
 	<td class="summary">Assembles an Entity.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#Entity:destroy">Entity:destroy ()</a></td>
+	<td class="name" nowrap><a href="#entity:destroy">entity:destroy ()</a></td>
 	<td class="summary">Destroys the Entity.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#Entity:has">Entity:has (componentClass)</a></td>
+	<td class="name" nowrap><a href="#entity:has">entity:has (name)</a></td>
 	<td class="summary">Returns true if the Entity has a Component.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#Entity:get">Entity:get (componentClass)</a></td>
+	<td class="name" nowrap><a href="#entity:get">entity:get (name)</a></td>
 	<td class="summary">Gets a Component from the Entity.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#Entity:getComponents">Entity:getComponents ()</a></td>
-	<td class="summary">Returns a table of all Components the Entity has.</td>
+	<td class="name" nowrap><a href="#entity:getComponents">entity:getComponents ([output])</a></td>
+	<td class="summary">Returns a shallow copy of the Entity's fields, excluding __world and __isEntity.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#Entity:inWorld">Entity:inWorld ()</a></td>
-	<td class="summary">Returns true if the Entity is in a World.</td>
+	<td class="name" nowrap><a href="#entity:inWorld">entity:inWorld ()</a></td>
+	<td class="summary">Returns true if the Entity has been assigned a World.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#Entity:getWorld">Entity:getWorld ()</a></td>
+	<td class="name" nowrap><a href="#entity:getWorld">entity:getWorld ()</a></td>
 	<td class="summary">Returns the World the Entity is in.</td>
 	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#entity:serialize">entity:serialize ([ignoreKey])</a></td>
+	<td class="summary">Serializes the Entity's Components.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#entity:deserialize">entity:deserialize (data)</a></td>
+	<td class="summary">Deserializes Components onto the Entity.</td>
+	</tr>
 </table>
 
 <br/>
 <br/>
 
 
+    <h2 class="section-header "><a name="Fields"></a>Fields</h2>
+
+    <dl class="function">
+    <dt>
+    <a name = "entity.SERIALIZE_BY_DEFAULT"></a>
+    <strong>entity.SERIALIZE_BY_DEFAULT</strong>
+    </dt>
+    <dd>
+    If true, new Entities are given a "serializable" Component.
+
+
+
+
+
+
+
+</dd>
+</dl>
     <h2 class="section-header "><a name="Methods"></a>Methods</h2>
 
     <dl class="function">
     <dt>
-    <a name = "Entity:new"></a>
-    <strong>Entity:new ([world])</strong>
+    <a name = "entity:new"></a>
+    <strong>entity:new ([world])</strong>
     </dt>
     <dd>
-    Creates a new Entity.  Optionally adds it to a World.
+    Creates a new Entity.  Optionally queues it to be added to a World.
+ If Entity.SERIALIZE<em>BY</em>DEFAULT is true, the Entity is given a "serializable" Component.
 
 
     <h3>Parameters:</h3>
@@ -147,22 +194,22 @@
 
 </dd>
     <dt>
-    <a name = "Entity:give"></a>
-    <strong>Entity:give (componentClass, ...)</strong>
+    <a name = "entity:give"></a>
+    <strong>entity:give (name, ...)</strong>
     </dt>
     <dd>
     Gives an Entity a Component.
- If the Component already exists, it's overridden by this new Component
+ If the Component already exists, it's overridden by this new Component.
 
 
     <h3>Parameters:</h3>
     <ul>
-        <li><span class="parameter">componentClass</span>
-            <span class="types"><a class="type" href="../classes/Component.html#">Component</a></span>
-         ComponentClass to add an instance of
+        <li><span class="parameter">name</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a> or <a class="type" href="../classes/Component.html#">Component</a></span>
+         Name of the ComponentClass, or a Component instance to copy onto the Entity
         </li>
         <li><span class="parameter">...</span>
-         additional arguments to pass to the Component's populate function
+         additional arguments to pass to the Component's populate function (ignored when copying a Component)
         </li>
     </ul>
 
@@ -178,22 +225,22 @@
 
 </dd>
     <dt>
-    <a name = "Entity:ensure"></a>
-    <strong>Entity:ensure (componentClass, ...)</strong>
+    <a name = "entity:ensure"></a>
+    <strong>entity:ensure (name, ...)</strong>
     </dt>
     <dd>
-    Ensures an Entity to have a Component.
- If the Component already exists, no action is taken
+    Ensures an Entity has a Component.
+ If the Component already exists, no action is taken.
 
 
     <h3>Parameters:</h3>
     <ul>
-        <li><span class="parameter">componentClass</span>
-            <span class="types"><a class="type" href="../classes/Component.html#">Component</a></span>
-         ComponentClass to add an instance of
+        <li><span class="parameter">name</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a> or <a class="type" href="../classes/Component.html#">Component</a></span>
+         Name of the ComponentClass, or a Component instance to copy onto the Entity
         </li>
         <li><span class="parameter">...</span>
-         additional arguments to pass to the Component's populate function
+         additional arguments to pass to the Component's populate function (ignored when copying a Component)
         </li>
     </ul>
 
@@ -209,8 +256,8 @@
 
 </dd>
     <dt>
-    <a name = "Entity:remove"></a>
-    <strong>Entity:remove (componentClass)</strong>
+    <a name = "entity:remove"></a>
+    <strong>entity:remove (name)</strong>
     </dt>
     <dd>
     Removes a Component from an Entity.
@@ -218,9 +265,9 @@
 
     <h3>Parameters:</h3>
     <ul>
-        <li><span class="parameter">componentClass</span>
-            <span class="types"><a class="type" href="../classes/Component.html#">Component</a></span>
-         ComponentClass of the Component to remove
+        <li><span class="parameter">name</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
+         Name of the ComponentClass to remove
         </li>
     </ul>
 
@@ -236,8 +283,8 @@
 
 </dd>
     <dt>
-    <a name = "Entity:assemble"></a>
-    <strong>Entity:assemble (assemblage, ...)</strong>
+    <a name = "entity:assemble"></a>
+    <strong>entity:assemble (assemblage, ...)</strong>
     </dt>
     <dd>
     Assembles an Entity.
@@ -266,18 +313,19 @@
 
 </dd>
     <dt>
-    <a name = "Entity:destroy"></a>
-    <strong>Entity:destroy ()</strong>
+    <a name = "entity:destroy"></a>
+    <strong>entity:destroy ()</strong>
     </dt>
     <dd>
     Destroys the Entity.
- Removes the Entity from its World if it's in one.
+ Queues removal from its World if it's in one. The Entity stays in the World until the next flush.
 
 
 
     <h3>Returns:</h3>
     <ol>
 
+           <span class="types"><a class="type" href="../classes/Entity.html#">Entity</a></span>
         self
     </ol>
 
@@ -286,8 +334,8 @@
 
 </dd>
     <dt>
-    <a name = "Entity:has"></a>
-    <strong>Entity:has (componentClass)</strong>
+    <a name = "entity:has"></a>
+    <strong>entity:has (name)</strong>
     </dt>
     <dd>
     Returns true if the Entity has a Component.
@@ -295,9 +343,9 @@
 
     <h3>Parameters:</h3>
     <ul>
-        <li><span class="parameter">componentClass</span>
-            <span class="types"><a class="type" href="../classes/Component.html#">Component</a></span>
-         ComponentClass of the Component to check
+        <li><span class="parameter">name</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
+         Name of the ComponentClass to check
         </li>
     </ul>
 
@@ -306,6 +354,8 @@
 
            <span class="types"><span class="type">boolean</span></span>
 
+
+
     </ol>
 
 
@@ -313,8 +363,8 @@
 
 </dd>
     <dt>
-    <a name = "Entity:get"></a>
-    <strong>Entity:get (componentClass)</strong>
+    <a name = "entity:get"></a>
+    <strong>entity:get (name)</strong>
     </dt>
     <dd>
     Gets a Component from the Entity.
@@ -322,17 +372,17 @@
 
     <h3>Parameters:</h3>
     <ul>
-        <li><span class="parameter">componentClass</span>
-            <span class="types"><a class="type" href="../classes/Component.html#">Component</a></span>
-         ComponentClass of the Component to get
+        <li><span class="parameter">name</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
+         Name of the ComponentClass to get
         </li>
     </ul>
 
     <h3>Returns:</h3>
     <ol>
 
-           <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
-
+           <span class="types"><a class="type" href="../classes/Component.html#">Component</a> or <span class="type">nil</span></span>
+        The Component, or nil if the Entity does not have it
     </ol>
 
 
@@ -340,21 +390,31 @@
 
 </dd>
     <dt>
-    <a name = "Entity:getComponents"></a>
-    <strong>Entity:getComponents ()</strong>
+    <a name = "entity:getComponents"></a>
+    <strong>entity:getComponents ([output])</strong>
     </dt>
     <dd>
-    Returns a table of all Components the Entity has.
- Warning: Do not modify this table.
- Use Entity:give/ensure/remove instead
+    Returns a shallow copy of the Entity's fields, excluding __world and __isEntity.
+ This is primarily the Entity's Components. Extra non-component fields are also copied.
+ Mutating a copied Component still mutates the Entity's Component.
 
 
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">output</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span>
+         Table to copy into. A new table is created if omitted.
+         (<em>optional</em>)
+        </li>
+    </ul>
 
     <h3>Returns:</h3>
     <ol>
 
-           <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
-        Table of all Components the Entity has
+           <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span>
+
+
+
     </ol>
 
 
@@ -362,11 +422,12 @@
 
 </dd>
     <dt>
-    <a name = "Entity:inWorld"></a>
-    <strong>Entity:inWorld ()</strong>
+    <a name = "entity:inWorld"></a>
+    <strong>entity:inWorld ()</strong>
     </dt>
     <dd>
-    Returns true if the Entity is in a World.
+    Returns true if the Entity has been assigned a World.
+ True as soon as addition is queued, and remains true until removal is flushed.
 
 
 
@@ -375,6 +436,8 @@
 
            <span class="types"><span class="type">boolean</span></span>
 
+
+
     </ol>
 
 
@@ -382,8 +445,8 @@
 
 </dd>
     <dt>
-    <a name = "Entity:getWorld"></a>
-    <strong>Entity:getWorld ()</strong>
+    <a name = "entity:getWorld"></a>
+    <strong>entity:getWorld ()</strong>
     </dt>
     <dd>
     Returns the World the Entity is in.
@@ -395,20 +458,70 @@
 
            <span class="types"><a class="type" href="../classes/World.html#">World</a></span>
 
+
+
     </ol>
 
 
 
 
+</dd>
+    <dt>
+    <a name = "entity:serialize"></a>
+    <strong>entity:serialize ([ignoreKey])</strong>
+    </dt>
+    <dd>
+    Serializes the Entity's Components.
+ Components that return nil from serialize are omitted.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">ignoreKey</span>
+            <span class="types"><span class="type">boolean</span></span>
+         If true, the key Component is omitted
+         (<em>optional</em>)
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span>
+        Serialized Entity data
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "entity:deserialize"></a>
+    <strong>entity:deserialize (data)</strong>
+    </dt>
+    <dd>
+    Deserializes Components onto the Entity.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">data</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span>
+         Serialized Entity data
+        </li>
+    </ul>
+
+
+
+
+
 </dd>
 </dl>
-
-
 </div> <!-- id="content" -->
 </div> <!-- id="main" -->
 <div id="about">
-<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-08-18 15:20:32 </i>
+<i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
+<i style="float:right;">Last updated 2026-09-06 21:32:30 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/classes/Filter.html

@@ -0,0 +1,508 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
+<head>
+    <title>Reference</title>
+    <link rel="stylesheet" href="../ldoc.css" type="text/css" />
+</head>
+<body>
+
+<div id="container">
+
+<div id="product">
+	<div id="product_logo"></div>
+	<div id="product_name"><big><b></b></big></div>
+	<div id="product_description"></div>
+</div> <!-- id="product" -->
+
+
+<div id="main">
+
+
+<!-- Menu -->
+
+<div id="navigation">
+<br/>
+<h1>Concord</h1>
+
+
+<ul>
+  <li><a href="../index.html">Getting Started</a></li>
+</ul>
+
+<h2>Contents</h2>
+<ul>
+<li><a href="#Methods">Methods</a></li>
+</ul>
+
+
+<h2>Classes</h2>
+<ul class="nowrap">
+  <li><a href="../classes/Component.html">Component</a></li>
+  <li><a href="../classes/Entity.html">Entity</a></li>
+  <li><strong>Filter</strong></li>
+  <li><a href="../classes/List.html">List</a></li>
+  <li><a href="../classes/System.html">System</a></li>
+  <li><a href="../classes/World.html">World</a></li>
+</ul>
+<h2>Builtin Components</h2>
+<ul class="nowrap">
+  <li><a href="../builtins/key.html">key</a></li>
+  <li><a href="../builtins/serializable.html">serializable</a></li>
+</ul>
+<h2>Modules</h2>
+<ul class="nowrap">
+  <li><a href="../modules/Components.html">Components</a></li>
+  <li><a href="../modules/Type.html">Type</a></li>
+  <li><a href="../modules/Utils.html">Utils</a></li>
+</ul>
+<h2>Guides</h2>
+<ul class="nowrap">
+  <li><a href="../index.html">Getting Started</a></li>
+  <li><a href="../guides/Why-ECS.md.html">Why ECS? Why Concord?</a></li>
+  <li><a href="../guides/Custom-Pools.md.html">Custom Pools</a></li>
+  <li><a href="../guides/Pool-Flushing-and-Timing.md.html">Pool Flushing and Timing</a></li>
+</ul>
+
+</div>
+
+<div id="content">
+
+<h1>Class <code>Filter</code></h1>
+<p>Used to filter Entities with specific Components
+ A Filter has an associated Pool that can contain any amount of Entities.</p>
+<p>
+
+</p>
+
+
+<h2><a href="#Methods">Methods</a></h2>
+<table class="function_list">
+	<tr>
+	<td class="name" nowrap><a href="#filter:validate">filter:validate (errorLevel[, name], def[, onComponent])</a></td>
+	<td class="summary">Validates a Filter Definition to make sure every component is valid.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#filter:parse">filter:parse ([name], def)</a></td>
+	<td class="summary">Parses a Filter Definition into a single interleaved table.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#filter:match">filter:match (e, filter)</a></td>
+	<td class="summary">Returns true if the Entity matches a parsed Filter.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#filter:isValidPool">filter:isValidPool (name, pool)</a></td>
+	<td class="summary">Checks that a custom Pool implements add, remove, has, and clear as callables.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#filter:new">filter:new (name, def)</a></td>
+	<td class="summary">Creates a new Filter
+ If definition.constructor is set, it is called with the definition to create the Pool.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#filter:eligible">filter:eligible (e)</a></td>
+	<td class="summary">Checks if an Entity fulfills the Filter requirements.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#filter:evaluate">filter:evaluate (e)</a></td>
+	<td class="summary">Evaluates an Entity against this Filter and updates the Pool.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#filter:add">filter:add (e[, bypass])</a></td>
+	<td class="summary">Adds an Entity to the Pool, if it passes the Filter.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#filter:remove">filter:remove (e)</a></td>
+	<td class="summary">Removes an Entity from the Pool associated to this Filter.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#filter:clear">filter:clear (e)</a></td>
+	<td class="summary">Clears the Pool associated to this Filter.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#filter:has">filter:has (e)</a></td>
+	<td class="summary">Checks if the Pool associated to this Filter contains the passed Entity.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#filter:getName">filter:getName ()</a></td>
+	<td class="summary">Gets the name of the Filter</td>
+	</tr>
+</table>
+
+<br/>
+<br/>
+
+
+    <h2 class="section-header "><a name="Methods"></a>Methods</h2>
+
+    <dl class="function">
+    <dt>
+    <a name = "filter:validate"></a>
+    <strong>filter:validate (errorLevel[, name], def[, onComponent])</strong>
+    </dt>
+    <dd>
+    Validates a Filter Definition to make sure every component is valid.
+ Also checks that def.constructor is callable when present, unless onComponent is provided.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">errorLevel</span>
+            <span class="types"><span class="type">integer</span></span>
+         Extra stack level added to error reports
+        </li>
+        <li><span class="parameter">name</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
+         Name for the Filter. If omitted, errors refer to a World:query filter.
+         (<em>optional</em>)
+        </li>
+        <li><span class="parameter">def</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span>
+         Table containing the Filter Definition
+        </li>
+        <li><span class="parameter">onComponent</span>
+            <span class="types"><span class="type">function</span></span>
+         Called with (component, reject) when a component is valid.
+ reject is the stripped Component name when the entry had the Reject Prefix, otherwise false.
+         (<em>optional</em>)
+        </li>
+    </ul>
+
+
+
+
+
+</dd>
+    <dt>
+    <a name = "filter:parse"></a>
+    <strong>filter:parse ([name], def)</strong>
+    </dt>
+    <dd>
+    Parses a Filter Definition into a single interleaved table.
+ Entries are stored as name, required pairs: {name, true, name, false, ...}
+ where true means the Component is required and false means it is rejected.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">name</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
+         Name for the Filter.
+         (<em>optional</em>)
+        </li>
+        <li><span class="parameter">def</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span>
+         Table containing the Filter Definition
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span>
+        Parsed filter
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "filter:match"></a>
+    <strong>filter:match (e, filter)</strong>
+    </dt>
+    <dd>
+    Returns true if the Entity matches a parsed Filter.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">e</span>
+            <span class="types"><a class="type" href="../classes/Entity.html#">Entity</a></span>
+         Entity to check
+        </li>
+        <li><span class="parameter">filter</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span>
+         Parsed filter from Filter.parse
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><span class="type">boolean</span></span>
+
+
+
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "filter:isValidPool"></a>
+    <strong>filter:isValidPool (name, pool)</strong>
+    </dt>
+    <dd>
+    Checks that a custom Pool implements add, remove, has, and clear as callables.
+ The Pool may be a table, userdata, lightuserdata, or cdata.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">name</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
+         Name of the Filter / Pool
+        </li>
+        <li><span class="parameter">pool</span>
+         Pool returned by a custom constructor
+        </li>
+    </ul>
+
+
+
+
+
+</dd>
+    <dt>
+    <a name = "filter:new"></a>
+    <strong>filter:new (name, def)</strong>
+    </dt>
+    <dd>
+    Creates a new Filter
+ If definition.constructor is set, it is called with the definition to create the Pool.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">name</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
+         Name for the Filter.
+        </li>
+        <li><span class="parameter">def</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span>
+         Table containing the Filter Definition
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+        <li>
+           <span class="types"><a class="type" href="../classes/Filter.html#">Filter</a></span>
+        The new Filter</li>
+        <li>
+           <span class="types"><span class="type">Pool</span></span>
+        The associated Pool</li>
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "filter:eligible"></a>
+    <strong>filter:eligible (e)</strong>
+    </dt>
+    <dd>
+    Checks if an Entity fulfills the Filter requirements.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">e</span>
+            <span class="types"><a class="type" href="../classes/Entity.html#">Entity</a></span>
+         Entity to check
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><span class="type">boolean</span></span>
+
+
+
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "filter:evaluate"></a>
+    <strong>filter:evaluate (e)</strong>
+    </dt>
+    <dd>
+    Evaluates an Entity against this Filter and updates the Pool.
+ Adds the Entity if it became eligible, removes it if it no longer is.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">e</span>
+            <span class="types"><a class="type" href="../classes/Entity.html#">Entity</a></span>
+         Entity to evaluate
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><a class="type" href="../classes/Filter.html#">Filter</a></span>
+        self
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "filter:add"></a>
+    <strong>filter:add (e[, bypass])</strong>
+    </dt>
+    <dd>
+    Adds an Entity to the Pool, if it passes the Filter.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">e</span>
+            <span class="types"><a class="type" href="../classes/Entity.html#">Entity</a></span>
+         Entity to add
+        </li>
+        <li><span class="parameter">bypass</span>
+            <span class="types"><span class="type">boolean</span></span>
+         Whether to bypass the Filter or not.
+         (<em>optional</em>)
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+        <li>
+           <span class="types"><a class="type" href="../classes/Filter.html#">Filter</a></span>
+        self</li>
+        <li>
+           <span class="types"><span class="type">boolean</span></span>
+        Whether the entity was added or not.</li>
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "filter:remove"></a>
+    <strong>filter:remove (e)</strong>
+    </dt>
+    <dd>
+    Removes an Entity from the Pool associated to this Filter.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">e</span>
+            <span class="types"><a class="type" href="../classes/Entity.html#">Entity</a></span>
+         Entity to remove
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><a class="type" href="../classes/Filter.html#">Filter</a></span>
+        self
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "filter:clear"></a>
+    <strong>filter:clear (e)</strong>
+    </dt>
+    <dd>
+    Clears the Pool associated to this Filter.
+ Arguments are forwarded to the Pool's clear method.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">e</span>
+         Forwarded to pool:clear
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><a class="type" href="../classes/Filter.html#">Filter</a></span>
+        self
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "filter:has"></a>
+    <strong>filter:has (e)</strong>
+    </dt>
+    <dd>
+    Checks if the Pool associated to this Filter contains the passed Entity.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">e</span>
+            <span class="types"><a class="type" href="../classes/Entity.html#">Entity</a></span>
+         Entity to check
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><span class="type">boolean</span></span>
+        Whether the Entity exists.
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "filter:getName"></a>
+    <strong>filter:getName ()</strong>
+    </dt>
+    <dd>
+    Gets the name of the Filter
+
+
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
+
+
+
+    </ol>
+
+
+
+
+</dd>
+</dl>
+</div> <!-- id="content" -->
+</div> <!-- id="main" -->
+<div id="about">
+<i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
+<i style="float:right;">Last updated 2026-09-06 21:32:30 </i>
+</div> <!-- id="about" -->
+</div> <!-- id="container" -->
+</body>
+</html>

docs/classes/List.html

@@ -26,8 +26,9 @@
 <br/>
 <h1>Concord</h1>
 
+
 <ul>
-  <li><a href="../index.html">Index</a></li>
+  <li><a href="../index.html">Getting Started</a></li>
 </ul>
 
 <h2>Contents</h2>
@@ -40,17 +41,28 @@
 <ul class="nowrap">
   <li><a href="../classes/Component.html">Component</a></li>
   <li><a href="../classes/Entity.html">Entity</a></li>
+  <li><a href="../classes/Filter.html">Filter</a></li>
   <li><strong>List</strong></li>
-  <li><a href="../classes/Pool.html">Pool</a></li>
   <li><a href="../classes/System.html">System</a></li>
   <li><a href="../classes/World.html">World</a></li>
 </ul>
+<h2>Builtin Components</h2>
+<ul class="nowrap">
+  <li><a href="../builtins/key.html">key</a></li>
+  <li><a href="../builtins/serializable.html">serializable</a></li>
+</ul>
 <h2>Modules</h2>
 <ul class="nowrap">
   <li><a href="../modules/Components.html">Components</a></li>
-  <li><a href="../modules/Concord.html">Concord</a></li>
-  <li><a href="../modules/type.html">type</a></li>
-  <li><a href="../modules/utils.html">utils</a></li>
+  <li><a href="../modules/Type.html">Type</a></li>
+  <li><a href="../modules/Utils.html">Utils</a></li>
+</ul>
+<h2>Guides</h2>
+<ul class="nowrap">
+  <li><a href="../index.html">Getting Started</a></li>
+  <li><a href="../guides/Why-ECS.md.html">Why ECS? Why Concord?</a></li>
+  <li><a href="../guides/Custom-Pools.md.html">Custom Pools</a></li>
+  <li><a href="../guides/Pool-Flushing-and-Timing.md.html">Pool Flushing and Timing</a></li>
 </ul>
 
 </div>
@@ -58,40 +70,54 @@
 <div id="content">
 
 <h1>Class <code>List</code></h1>
-<p>Data structure that allows for fast removal at the cost of containing order.</p>
-<p></p>
+<p>Data structure that allows for fast removal at the cost of order.</p>
+<p>
+
+</p>
 
 
 <h2><a href="#Methods">Methods</a></h2>
 <table class="function_list">
 	<tr>
-	<td class="name" nowrap><a href="#List:new">List:new ()</a></td>
+	<td class="name" nowrap><a href="#list:new">list:new ()</a></td>
 	<td class="summary">Creates a new List.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#List:add">List:add (obj)</a></td>
+	<td class="name" nowrap><a href="#list:add">list:add (obj)</a></td>
 	<td class="summary">Adds an object to the List.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#List:remove">List:remove (obj)</a></td>
+	<td class="name" nowrap><a href="#list:remove">list:remove (obj)</a></td>
 	<td class="summary">Removes an object from the List.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#List:clear">List:clear ()</a></td>
+	<td class="name" nowrap><a href="#list:clear">list:clear ()</a></td>
 	<td class="summary">Clears the List completely.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#List:has">List:has (obj)</a></td>
+	<td class="name" nowrap><a href="#list:has">list:has (obj)</a></td>
 	<td class="summary">Returns true if the List has the object.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#List:get">List:get (i)</a></td>
+	<td class="name" nowrap><a href="#list:get">list:get (i)</a></td>
 	<td class="summary">Returns the object at an index.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#List:indexOf">List:indexOf (obj)</a></td>
+	<td class="name" nowrap><a href="#list:indexOf">list:indexOf (obj)</a></td>
 	<td class="summary">Returns the index of an object in the List.</td>
 	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#list:sort">list:sort (order)</a></td>
+	<td class="summary">Sorts the List in place, using the order function.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#list:onAdded">list:onAdded (obj)</a></td>
+	<td class="summary">Callback for when an item is added to the List.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#list:onRemoved">list:onRemoved (obj)</a></td>
+	<td class="summary">Callback for when an item is removed from the List.</td>
+	</tr>
 </table>
 
 <br/>
@@ -102,8 +128,8 @@
 
     <dl class="function">
     <dt>
-    <a name = "List:new"></a>
-    <strong>List:new ()</strong>
+    <a name = "list:new"></a>
+    <strong>list:new ()</strong>
     </dt>
     <dd>
     Creates a new List.
@@ -122,13 +148,13 @@
 
 </dd>
     <dt>
-    <a name = "List:add"></a>
-    <strong>List:add (obj)</strong>
+    <a name = "list:add"></a>
+    <strong>list:add (obj)</strong>
     </dt>
     <dd>
     Adds an object to the List.
  Object must be of reference type
- Object may not be the string 'size'
+ Object may not be the string 'size', 'onAdded' or 'onRemoved'
 
 
     <h3>Parameters:</h3>
@@ -150,8 +176,8 @@
 
 </dd>
     <dt>
-    <a name = "List:remove"></a>
-    <strong>List:remove (obj)</strong>
+    <a name = "list:remove"></a>
+    <strong>list:remove (obj)</strong>
     </dt>
     <dd>
     Removes an object from the List.
@@ -167,8 +193,8 @@
     <h3>Returns:</h3>
     <ol>
 
-           <span class="types"><a class="type" href="../classes/List.html#">List</a></span>
-        self
+           <span class="types"><a class="type" href="../classes/List.html#">List</a> or <span class="type">nil</span></span>
+        self, or nil if the object was not in the List
     </ol>
 
 
@@ -176,11 +202,12 @@
 
 </dd>
     <dt>
-    <a name = "List:clear"></a>
-    <strong>List:clear ()</strong>
+    <a name = "list:clear"></a>
+    <strong>list:clear ()</strong>
     </dt>
     <dd>
     Clears the List completely.
+ Does not call onRemoved.
 
 
 
@@ -196,8 +223,8 @@
 
 </dd>
     <dt>
-    <a name = "List:has"></a>
-    <strong>List:has (obj)</strong>
+    <a name = "list:has"></a>
+    <strong>list:has (obj)</strong>
     </dt>
     <dd>
     Returns true if the List has the object.
@@ -215,6 +242,8 @@
 
            <span class="types"><span class="type">boolean</span></span>
 
+
+
     </ol>
 
 
@@ -222,8 +251,8 @@
 
 </dd>
     <dt>
-    <a name = "List:get"></a>
-    <strong>List:get (i)</strong>
+    <a name = "list:get"></a>
+    <strong>list:get (i)</strong>
     </dt>
     <dd>
     Returns the object at an index.
@@ -248,11 +277,12 @@
 
 </dd>
     <dt>
-    <a name = "List:indexOf"></a>
-    <strong>List:indexOf (obj)</strong>
+    <a name = "list:indexOf"></a>
+    <strong>list:indexOf (obj)</strong>
     </dt>
     <dd>
     Returns the index of an object in the List.
+ Errors if the object is not in the List.
 
 
     <h3>Parameters:</h3>
@@ -272,15 +302,80 @@
 
 
 
+</dd>
+    <dt>
+    <a name = "list:sort"></a>
+    <strong>list:sort (order)</strong>
+    </dt>
+    <dd>
+    Sorts the List in place, using the order function.
+ The order function is passed to table.sort internally so documentation on table.sort can be used as reference.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">order</span>
+         Function that takes two items (a and b) and returns true if a should go before b.
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><a class="type" href="../classes/List.html#">List</a></span>
+        self
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "list:onAdded"></a>
+    <strong>list:onAdded (obj)</strong>
+    </dt>
+    <dd>
+    Callback for when an item is added to the List.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">obj</span>
+         Object that was added
+        </li>
+    </ul>
+
+
+
+
+
+</dd>
+    <dt>
+    <a name = "list:onRemoved"></a>
+    <strong>list:onRemoved (obj)</strong>
+    </dt>
+    <dd>
+    Callback for when an item is removed from the List.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">obj</span>
+         Object that was removed
+        </li>
+    </ul>
+
+
+
+
+
 </dd>
 </dl>
-
-
 </div> <!-- id="content" -->
 </div> <!-- id="main" -->
 <div id="about">
-<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-08-18 15:20:32 </i>
+<i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
+<i style="float:right;">Last updated 2026-09-06 21:32:30 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/classes/Pool.html

@@ -1,257 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html>
-<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
-<head>
-    <title>Reference</title>
-    <link rel="stylesheet" href="../ldoc.css" type="text/css" />
-</head>
-<body>
-
-<div id="container">
-
-<div id="product">
-	<div id="product_logo"></div>
-	<div id="product_name"><big><b></b></big></div>
-	<div id="product_description"></div>
-</div> <!-- id="product" -->
-
-
-<div id="main">
-
-
-<!-- Menu -->
-
-<div id="navigation">
-<br/>
-<h1>Concord</h1>
-
-<ul>
-  <li><a href="../index.html">Index</a></li>
-</ul>
-
-<h2>Contents</h2>
-<ul>
-<li><a href="#Methods">Methods</a></li>
-</ul>
-
-
-<h2>Classes</h2>
-<ul class="nowrap">
-  <li><a href="../classes/Component.html">Component</a></li>
-  <li><a href="../classes/Entity.html">Entity</a></li>
-  <li><a href="../classes/List.html">List</a></li>
-  <li><strong>Pool</strong></li>
-  <li><a href="../classes/System.html">System</a></li>
-  <li><a href="../classes/World.html">World</a></li>
-</ul>
-<h2>Modules</h2>
-<ul class="nowrap">
-  <li><a href="../modules/Components.html">Components</a></li>
-  <li><a href="../modules/Concord.html">Concord</a></li>
-  <li><a href="../modules/type.html">type</a></li>
-  <li><a href="../modules/utils.html">utils</a></li>
-</ul>
-
-</div>
-
-<div id="content">
-
-<h1>Class <code>Pool</code></h1>
-<p>Used to iterate over Entities with a specific Components
- A Pool contain a any amount of Entities.</p>
-<p></p>
-
-
-<h2><a href="#Methods">Methods</a></h2>
-<table class="function_list">
-	<tr>
-	<td class="name" nowrap><a href="#Pool:new">Pool:new (name, filter)</a></td>
-	<td class="summary">Creates a new Pool</td>
-	</tr>
-	<tr>
-	<td class="name" nowrap><a href="#Pool:eligible">Pool:eligible (e)</a></td>
-	<td class="summary">Checks if an Entity is eligible for the Pool.</td>
-	</tr>
-	<tr>
-	<td class="name" nowrap><a href="#Pool:evaluate">Pool:evaluate (e)</a></td>
-	<td class="summary">Evaluate whether an Entity should be added or removed from the Pool.</td>
-	</tr>
-	<tr>
-	<td class="name" nowrap><a href="#Pool:getName">Pool:getName ()</a></td>
-	<td class="summary">Gets the name of the Pool</td>
-	</tr>
-	<tr>
-	<td class="name" nowrap><a href="#Pool:getFilter">Pool:getFilter ()</a></td>
-	<td class="summary">Gets the filter of the Pool.</td>
-	</tr>
-	<tr>
-	<td class="name" nowrap><a href="#Pool:onEntityAdded">Pool:onEntityAdded (e)</a></td>
-	<td class="summary">Callback for when an Entity is added to the Pool.</td>
-	</tr>
-</table>
-
-<br/>
-<br/>
-
-
-    <h2 class="section-header "><a name="Methods"></a>Methods</h2>
-
-    <dl class="function">
-    <dt>
-    <a name = "Pool:new"></a>
-    <strong>Pool:new (name, filter)</strong>
-    </dt>
-    <dd>
-    Creates a new Pool
-
-
-    <h3>Parameters:</h3>
-    <ul>
-        <li><span class="parameter">name</span>
-            <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
-         Name for the Pool.
-        </li>
-        <li><span class="parameter">filter</span>
-            <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
-         Table containing the required BaseComponents
-        </li>
-    </ul>
-
-    <h3>Returns:</h3>
-    <ol>
-
-           <span class="types"><a class="type" href="../classes/Pool.html#">Pool</a></span>
-        The new Pool
-    </ol>
-
-
-
-
-</dd>
-    <dt>
-    <a name = "Pool:eligible"></a>
-    <strong>Pool:eligible (e)</strong>
-    </dt>
-    <dd>
-    Checks if an Entity is eligible for the Pool.
-
-
-    <h3>Parameters:</h3>
-    <ul>
-        <li><span class="parameter">e</span>
-            <span class="types"><a class="type" href="../classes/Entity.html#">Entity</a></span>
-         Entity to check
-        </li>
-    </ul>
-
-    <h3>Returns:</h3>
-    <ol>
-
-           <span class="types"><span class="type">boolean</span></span>
-
-    </ol>
-
-
-
-
-</dd>
-    <dt>
-    <a name = "Pool:evaluate"></a>
-    <strong>Pool:evaluate (e)</strong>
-    </dt>
-    <dd>
-    Evaluate whether an Entity should be added or removed from the Pool.
-
-
-    <h3>Parameters:</h3>
-    <ul>
-        <li><span class="parameter">e</span>
-         Entity to add or remove
-        </li>
-    </ul>
-
-    <h3>Returns:</h3>
-    <ol>
-
-           <span class="types"><a class="type" href="../classes/Pool.html#">Pool</a></span>
-        self
-    </ol>
-
-
-
-
-</dd>
-    <dt>
-    <a name = "Pool:getName"></a>
-    <strong>Pool:getName ()</strong>
-    </dt>
-    <dd>
-    Gets the name of the Pool
-
-
-
-    <h3>Returns:</h3>
-    <ol>
-
-           <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
-
-    </ol>
-
-
-
-
-</dd>
-    <dt>
-    <a name = "Pool:getFilter"></a>
-    <strong>Pool:getFilter ()</strong>
-    </dt>
-    <dd>
-    Gets the filter of the Pool.
- Warning: Do not modify this filter.
-
-
-
-    <h3>Returns:</h3>
-    <ol>
-
-        Filter of the Pool.
-    </ol>
-
-
-
-
-</dd>
-    <dt>
-    <a name = "Pool:onEntityAdded"></a>
-    <strong>Pool:onEntityAdded (e)</strong>
-    </dt>
-    <dd>
-    Callback for when an Entity is added to the Pool.
-
-
-    <h3>Parameters:</h3>
-    <ul>
-        <li><span class="parameter">e</span>
-            <span class="types"><a class="type" href="../classes/Entity.html#">Entity</a></span>
-         Entity that was added.
-        </li>
-    </ul>
-
-
-
-
-
-</dd>
-</dl>
-
-
-</div> <!-- id="content" -->
-</div> <!-- id="main" -->
-<div id="about">
-<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-08-18 15:20:32 </i>
-</div> <!-- id="about" -->
-</div> <!-- id="container" -->
-</body>
-</html>

docs/classes/System.html

@@ -26,8 +26,9 @@
 <br/>
 <h1>Concord</h1>
 
+
 <ul>
-  <li><a href="../index.html">Index</a></li>
+  <li><a href="../index.html">Getting Started</a></li>
 </ul>
 
 <h2>Contents</h2>
@@ -41,17 +42,28 @@
 <ul class="nowrap">
   <li><a href="../classes/Component.html">Component</a></li>
   <li><a href="../classes/Entity.html">Entity</a></li>
+  <li><a href="../classes/Filter.html">Filter</a></li>
   <li><a href="../classes/List.html">List</a></li>
-  <li><a href="../classes/Pool.html">Pool</a></li>
   <li><strong>System</strong></li>
   <li><a href="../classes/World.html">World</a></li>
 </ul>
+<h2>Builtin Components</h2>
+<ul class="nowrap">
+  <li><a href="../builtins/key.html">key</a></li>
+  <li><a href="../builtins/serializable.html">serializable</a></li>
+</ul>
 <h2>Modules</h2>
 <ul class="nowrap">
   <li><a href="../modules/Components.html">Components</a></li>
-  <li><a href="../modules/Concord.html">Concord</a></li>
-  <li><a href="../modules/type.html">type</a></li>
-  <li><a href="../modules/utils.html">utils</a></li>
+  <li><a href="../modules/Type.html">Type</a></li>
+  <li><a href="../modules/Utils.html">Utils</a></li>
+</ul>
+<h2>Guides</h2>
+<ul class="nowrap">
+  <li><a href="../index.html">Getting Started</a></li>
+  <li><a href="../guides/Why-ECS.md.html">Why ECS? Why Concord?</a></li>
+  <li><a href="../guides/Custom-Pools.md.html">Custom Pools</a></li>
+  <li><a href="../guides/Pool-Flushing-and-Timing.md.html">Pool Flushing and Timing</a></li>
 </ul>
 
 </div>
@@ -60,50 +72,42 @@
 
 <h1>Class <code>System</code></h1>
 <p>Iterates over Entities.</p>
-<p> From these Entities its get Components and modify them.
- A System contains 1 or more Pools.
+<p> From these Entities it gets Components and modifies them.
+ A System contains 0 or more Pools.
  A System is contained by 1 World.</p>
 
 
 <h2><a href="#Methods">Methods</a></h2>
 <table class="function_list">
 	<tr>
-	<td class="name" nowrap><a href="#System:new">System:new (table)</a></td>
+	<td class="name" nowrap><a href="#system:new">system:new ([name[, definition]])</a></td>
 	<td class="summary">Creates a new SystemClass.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#System:setEnabled">System:setEnabled (enable)</a></td>
-	<td class="summary">Sets if the System is enabled</td>
+	<td class="name" nowrap><a href="#system:setEnabled">system:setEnabled (enable)</a></td>
+	<td class="summary">Sets whether the System is enabled.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#System:isEnabled">System:isEnabled ()</a></td>
-	<td class="summary">Returns is the System is enabled</td>
+	<td class="name" nowrap><a href="#system:isEnabled">system:isEnabled ()</a></td>
+	<td class="summary">Returns whether the System is enabled.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#System:getWorld">System:getWorld ()</a></td>
+	<td class="name" nowrap><a href="#system:getWorld">system:getWorld ()</a></td>
 	<td class="summary">Returns the World the System is in.</td>
 	</tr>
-	<tr>
-	<td class="name" nowrap><a href="#System:hasName">System:hasName ()</a></td>
-	<td class="summary">Returns true if the System has a name.</td>
-	</tr>
-	<tr>
-	<td class="name" nowrap><a href="#System:getName">System:getName ()</a></td>
-	<td class="summary">Returns the name of the System.</td>
-	</tr>
 </table>
 <h2><a href="#Callbacks">Callbacks </a></h2>
 <table class="function_list">
 	<tr>
-	<td class="name" nowrap><a href="#System:init">System:init (world)</a></td>
+	<td class="name" nowrap><a href="#system:init">system:init (world)</a></td>
 	<td class="summary">Callback for system initialization.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#System:onEnabled">System:onEnabled ()</a></td>
+	<td class="name" nowrap><a href="#system:onEnabled">system:onEnabled ()</a></td>
 	<td class="summary">Callback for when a System is enabled.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#System:onDisabled">System:onDisabled ()</a></td>
+	<td class="name" nowrap><a href="#system:onDisabled">system:onDisabled ()</a></td>
 	<td class="summary">Callback for when a System is disabled.</td>
 	</tr>
 </table>
@@ -116,8 +120,8 @@
 
     <dl class="function">
     <dt>
-    <a name = "System:new"></a>
-    <strong>System:new (table)</strong>
+    <a name = "system:new"></a>
+    <strong>system:new ([name[, definition]])</strong>
     </dt>
     <dd>
     Creates a new SystemClass.
@@ -125,8 +129,15 @@
 
     <h3>Parameters:</h3>
     <ul>
-        <li><span class="parameter">table</span>
-         filters A table containing filters (name = {components...})
+        <li><span class="parameter">name</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
+         Name of the System. If omitted, or if a table is passed first, the first argument is the definition.
+         (<em>optional</em>)
+        </li>
+        <li><span class="parameter">definition</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span>
+         A table containing filters (name = {components...})
+         (<em>optional</em>)
         </li>
     </ul>
 
@@ -142,11 +153,11 @@
 
 </dd>
     <dt>
-    <a name = "System:setEnabled"></a>
-    <strong>System:setEnabled (enable)</strong>
+    <a name = "system:setEnabled"></a>
+    <strong>system:setEnabled (enable)</strong>
     </dt>
     <dd>
-    Sets if the System is enabled
+    Sets whether the System is enabled.
 
 
     <h3>Parameters:</h3>
@@ -154,6 +165,8 @@
         <li><span class="parameter">enable</span>
             <span class="types"><span class="type">boolean</span></span>
 
+
+
         </li>
     </ul>
 
@@ -169,11 +182,11 @@
 
 </dd>
     <dt>
-    <a name = "System:isEnabled"></a>
-    <strong>System:isEnabled ()</strong>
+    <a name = "system:isEnabled"></a>
+    <strong>system:isEnabled ()</strong>
     </dt>
     <dd>
-    Returns is the System is enabled
+    Returns whether the System is enabled.
 
 
 
@@ -182,6 +195,8 @@
 
            <span class="types"><span class="type">boolean</span></span>
 
+
+
     </ol>
 
 
@@ -189,8 +204,8 @@
 
 </dd>
     <dt>
-    <a name = "System:getWorld"></a>
-    <strong>System:getWorld ()</strong>
+    <a name = "system:getWorld"></a>
+    <strong>system:getWorld ()</strong>
     </dt>
     <dd>
     Returns the World the System is in.
@@ -202,46 +217,8 @@
 
            <span class="types"><a class="type" href="../classes/World.html#">World</a></span>
 
-    </ol>
 
 
-
-
-</dd>
-    <dt>
-    <a name = "System:hasName"></a>
-    <strong>System:hasName ()</strong>
-    </dt>
-    <dd>
-    Returns true if the System has a name.
-
-
-
-    <h3>Returns:</h3>
-    <ol>
-
-           <span class="types"><span class="type">boolean</span></span>
-
-    </ol>
-
-
-
-
-</dd>
-    <dt>
-    <a name = "System:getName"></a>
-    <strong>System:getName ()</strong>
-    </dt>
-    <dd>
-    Returns the name of the System.
-
-
-
-    <h3>Returns:</h3>
-    <ol>
-
-           <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
-
     </ol>
 
 
@@ -253,8 +230,8 @@
 
     <dl class="function">
     <dt>
-    <a name = "System:init"></a>
-    <strong>System:init (world)</strong>
+    <a name = "system:init"></a>
+    <strong>system:init (world)</strong>
     </dt>
     <dd>
     Callback for system initialization.
@@ -274,8 +251,8 @@
 
 </dd>
     <dt>
-    <a name = "System:onEnabled"></a>
-    <strong>System:onEnabled ()</strong>
+    <a name = "system:onEnabled"></a>
+    <strong>system:onEnabled ()</strong>
     </dt>
     <dd>
     Callback for when a System is enabled.
@@ -288,8 +265,8 @@
 
 </dd>
     <dt>
-    <a name = "System:onDisabled"></a>
-    <strong>System:onDisabled ()</strong>
+    <a name = "system:onDisabled"></a>
+    <strong>system:onDisabled ()</strong>
     </dt>
     <dd>
     Callback for when a System is disabled.
@@ -302,13 +279,11 @@
 
 </dd>
 </dl>
-
-
 </div> <!-- id="content" -->
 </div> <!-- id="main" -->
 <div id="about">
-<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-08-18 15:20:32 </i>
+<i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
+<i style="float:right;">Last updated 2026-09-06 21:32:30 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/classes/World.html

@@ -26,8 +26,9 @@
 <br/>
 <h1>Concord</h1>
 
+
 <ul>
-  <li><a href="../index.html">Index</a></li>
+  <li><a href="../index.html">Getting Started</a></li>
 </ul>
 
 <h2>Contents</h2>
@@ -40,17 +41,28 @@
 <ul class="nowrap">
   <li><a href="../classes/Component.html">Component</a></li>
   <li><a href="../classes/Entity.html">Entity</a></li>
+  <li><a href="../classes/Filter.html">Filter</a></li>
   <li><a href="../classes/List.html">List</a></li>
-  <li><a href="../classes/Pool.html">Pool</a></li>
   <li><a href="../classes/System.html">System</a></li>
   <li><strong>World</strong></li>
 </ul>
+<h2>Builtin Components</h2>
+<ul class="nowrap">
+  <li><a href="../builtins/key.html">key</a></li>
+  <li><a href="../builtins/serializable.html">serializable</a></li>
+</ul>
 <h2>Modules</h2>
 <ul class="nowrap">
   <li><a href="../modules/Components.html">Components</a></li>
-  <li><a href="../modules/Concord.html">Concord</a></li>
-  <li><a href="../modules/type.html">type</a></li>
-  <li><a href="../modules/utils.html">utils</a></li>
+  <li><a href="../modules/Type.html">Type</a></li>
+  <li><a href="../modules/Utils.html">Utils</a></li>
+</ul>
+<h2>Guides</h2>
+<ul class="nowrap">
+  <li><a href="../index.html">Getting Started</a></li>
+  <li><a href="../guides/Why-ECS.md.html">Why ECS? Why Concord?</a></li>
+  <li><a href="../guides/Custom-Pools.md.html">Custom Pools</a></li>
+  <li><a href="../guides/Pool-Flushing-and-Timing.md.html">Pool Flushing and Timing</a></li>
 </ul>
 
 </div>
@@ -59,66 +71,108 @@
 
 <h1>Class <code>World</code></h1>
 <p>A collection of Systems and Entities.</p>
-<p>
- A world emits to let Systems iterate.
- A World contains any amount of Systems.
- A World contains any amount of Entities.</p>
+<p> A World emits events so Systems can iterate their Pools.
+ A World contains any amount of Systems and Entities, plus optional named resources.</p>
 
 
 <h2><a href="#Methods">Methods</a></h2>
 <table class="function_list">
 	<tr>
-	<td class="name" nowrap><a href="#World:new">World:new ()</a></td>
+	<td class="name" nowrap><a href="#world:new">world:new ()</a></td>
 	<td class="summary">Creates a new World.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#World:addEntity">World:addEntity (e)</a></td>
-	<td class="summary">Adds an Entity to the World.</td>
+	<td class="name" nowrap><a href="#world:addEntity">world:addEntity (e)</a></td>
+	<td class="summary">Queues an Entity to be added to the World.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#World:removeEntity">World:removeEntity (e)</a></td>
-	<td class="summary">Removes an Entity from the World.</td>
+	<td class="name" nowrap><a href="#world:newEntity">world:newEntity ()</a></td>
+	<td class="summary">Creates a new Entity and queues it to be added to the World.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#World:addSystem">World:addSystem (systemClass)</a></td>
+	<td class="name" nowrap><a href="#world:query">world:query (def[, onMatch])</a></td>
+	<td class="summary">Queries flushed Entities against a Filter definition.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#world:removeEntity">world:removeEntity (e)</a></td>
+	<td class="summary">Queues an Entity to be removed from the World.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#world:canFlush">world:canFlush ()</a></td>
+	<td class="summary">Returns whether a Flush can currently be performed.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#world:flush">world:flush ()</a></td>
+	<td class="summary">Applies queued Entity additions, removals, and dirty reevaluations.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#world:addSystem">world:addSystem (systemClass)</a></td>
 	<td class="summary">Adds a System to the World.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#World:addSystems">World:addSystems (...)</a></td>
+	<td class="name" nowrap><a href="#world:addSystems">world:addSystems (...)</a></td>
 	<td class="summary">Adds multiple Systems to the World.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#World:hasSystem">World:hasSystem (systemClass)</a></td>
-	<td class="summary">Returns if the World has a System.</td>
+	<td class="name" nowrap><a href="#world:hasSystem">world:hasSystem (systemClass)</a></td>
+	<td class="summary">Returns whether the World has a System.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#World:getSystem">World:getSystem (systemClass)</a></td>
+	<td class="name" nowrap><a href="#world:getSystem">world:getSystem (systemClass)</a></td>
 	<td class="summary">Gets a System from the World.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#World:emit">World:emit (functionName, ...)</a></td>
+	<td class="name" nowrap><a href="#world:emit">world:emit (functionName, ...)</a></td>
 	<td class="summary">Emits a callback in the World.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#World:clear">World:clear ()</a></td>
-	<td class="summary">Removes all entities from the World</td>
+	<td class="name" nowrap><a href="#world:emitNoFlush">world:emitNoFlush (functionName, ...)</a></td>
+	<td class="summary">Emits a callback in the World without flushing.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#World:hasName">World:hasName ()</a></td>
-	<td class="summary">Returns true if the World has a name.</td>
+	<td class="name" nowrap><a href="#world:clear">world:clear ()</a></td>
+	<td class="summary">Removes all Entities from the World and flushes.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#World:getName">World:getName ()</a></td>
-	<td class="summary">Returns the name of the World.</td>
+	<td class="name" nowrap><a href="#world:getEntities">world:getEntities ()</a></td>
+	<td class="summary">Returns the List of flushed Entities in the World.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#World:onEntityAdded">World:onEntityAdded (e)</a></td>
+	<td class="name" nowrap><a href="#world:getSystems">world:getSystems ()</a></td>
+	<td class="summary">Returns the List of Systems in the World.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#world:serialize">world:serialize ([ignoreKeys])</a></td>
+	<td class="summary">Serializes serializable Entities in the World.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#world:deserialize">world:deserialize (data[, startClean[, ignoreGenerator]])</a></td>
+	<td class="summary">Deserializes Entities into the World.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#world:setKeyGenerator">world:setKeyGenerator (generator, initialState)</a></td>
+	<td class="summary">Sets the function used to generate Entity keys.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#world:getEntityByKey">world:getEntityByKey (key)</a></td>
+	<td class="summary">Gets an Entity by its key.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#world:onEntityAdded">world:onEntityAdded (e)</a></td>
 	<td class="summary">Callback for when an Entity is added to the World.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#World:onEntityRemoved">World:onEntityRemoved (e)</a></td>
+	<td class="name" nowrap><a href="#world:onEntityRemoved">world:onEntityRemoved (e)</a></td>
 	<td class="summary">Callback for when an Entity is removed from the World.</td>
 	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#world:setResource">world:setResource (name, resource)</a></td>
+	<td class="summary">Sets a named resource in the World.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#world:getResource">world:getResource (name)</a></td>
+	<td class="summary">Gets a named resource from the World.</td>
+	</tr>
 </table>
 
 <br/>
@@ -129,8 +183,8 @@
 
     <dl class="function">
     <dt>
-    <a name = "World:new"></a>
-    <strong>World:new ()</strong>
+    <a name = "world:new"></a>
+    <strong>world:new ()</strong>
     </dt>
     <dd>
     Creates a new World.
@@ -149,11 +203,13 @@
 
 </dd>
     <dt>
-    <a name = "World:addEntity"></a>
-    <strong>World:addEntity (e)</strong>
+    <a name = "world:addEntity"></a>
+    <strong>world:addEntity (e)</strong>
     </dt>
     <dd>
-    Adds an Entity to the World.
+    Queues an Entity to be added to the World.
+ The Entity's world is set immediately. The Entity is not in getEntities()
+ and is not evaluated by Systems until the next flush.
 
 
     <h3>Parameters:</h3>
@@ -176,11 +232,69 @@
 
 </dd>
     <dt>
-    <a name = "World:removeEntity"></a>
-    <strong>World:removeEntity (e)</strong>
+    <a name = "world:newEntity"></a>
+    <strong>world:newEntity ()</strong>
     </dt>
     <dd>
-    Removes an Entity from the World.
+    Creates a new Entity and queues it to be added to the World.
+
+
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><a class="type" href="../classes/Entity.html#">Entity</a></span>
+        e the new Entity
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "world:query"></a>
+    <strong>world:query (def[, onMatch])</strong>
+    </dt>
+    <dd>
+    Queries flushed Entities against a Filter definition.
+ Pending (not yet flushed) additions are not included. Component changes on
+ already flushed Entities are visible immediately.
+ If onMatch is a callable it is invoked for each match and nothing is returned.
+ Otherwise matches are appended to onMatch when it is a table, or to a new table.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">def</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span>
+         Filter definition (component names, with ! prefix to reject)
+        </li>
+        <li><span class="parameter">onMatch</span>
+            <span class="types"><span class="type">function</span> or <a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span>
+         Callback for each match, or a table to fill
+         (<em>optional</em>)
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a> or <span class="type">nil</span></span>
+        The list of matches, or nil if onMatch was a callback
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "world:removeEntity"></a>
+    <strong>world:removeEntity (e)</strong>
+    </dt>
+    <dd>
+    Queues an Entity to be removed from the World.
+ If the Entity has a key Component, it is removed first.
+ The Entity remains in the World until the next flush.
 
 
     <h3>Parameters:</h3>
@@ -203,13 +317,58 @@
 
 </dd>
     <dt>
-    <a name = "World:addSystem"></a>
-    <strong>World:addSystem (systemClass)</strong>
+    <a name = "world:canFlush"></a>
+    <strong>world:canFlush ()</strong>
+    </dt>
+    <dd>
+    Returns whether a Flush can currently be performed.
+ Flushing is forbidden while a Flush is already in progress
+ (for example from World:onEntityAdded / Pool:onAdded).
+
+
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><span class="type">boolean</span></span>
+
+
+
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "world:flush"></a>
+    <strong>world:flush ()</strong>
+    </dt>
+    <dd>
+    Applies queued Entity additions, removals, and dirty reevaluations.
+ Only the queued buffers are processed, not every Entity in the World.
+
+
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><a class="type" href="../classes/World.html#">World</a></span>
+        self
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "world:addSystem"></a>
+    <strong>world:addSystem (systemClass)</strong>
     </dt>
     <dd>
     Adds a System to the World.
- Callbacks are registered automatically
- Entities added before are added to the System retroactively
+ Functions on the SystemClass are registered as event listeners.
+ Entities already in the World are evaluated against the System's Filters.
 
 
     <h3>Parameters:</h3>
@@ -230,18 +389,18 @@
 
     <h3>See also:</h3>
     <ul>
-         <a href="../classes/World.html#World:emit">World:emit</a>
+         <a href="../classes/World.html#world:emit">World:emit</a>
     </ul>
 
 
 </dd>
     <dt>
-    <a name = "World:addSystems"></a>
-    <strong>World:addSystems (...)</strong>
+    <a name = "world:addSystems"></a>
+    <strong>world:addSystems (...)</strong>
     </dt>
     <dd>
     Adds multiple Systems to the World.
- Callbacks are registered automatically
+ Functions on each SystemClass are registered as event listeners.
 
 
     <h3>Parameters:</h3>
@@ -261,18 +420,18 @@
 
     <h3>See also:</h3>
     <ul>
-         <li><a href="../classes/World.html#World:addSystem">World:addSystem</a></li>
-         <li><a href="../classes/World.html#World:emit">World:emit</a></li>
+         <li><a href="../classes/World.html#world:addSystem">World:addSystem</a></li>
+         <li><a href="../classes/World.html#world:emit">World:emit</a></li>
     </ul>
 
 
 </dd>
     <dt>
-    <a name = "World:hasSystem"></a>
-    <strong>World:hasSystem (systemClass)</strong>
+    <a name = "world:hasSystem"></a>
+    <strong>world:hasSystem (systemClass)</strong>
     </dt>
     <dd>
-    Returns if the World has a System.
+    Returns whether the World has a System.
 
 
     <h3>Parameters:</h3>
@@ -288,6 +447,8 @@
 
            <span class="types"><span class="type">boolean</span></span>
 
+
+
     </ol>
 
 
@@ -295,8 +456,8 @@
 
 </dd>
     <dt>
-    <a name = "World:getSystem"></a>
-    <strong>World:getSystem (systemClass)</strong>
+    <a name = "world:getSystem"></a>
+    <strong>world:getSystem (systemClass)</strong>
     </dt>
     <dd>
     Gets a System from the World.
@@ -322,18 +483,22 @@
 
 </dd>
     <dt>
-    <a name = "World:emit"></a>
-    <strong>World:emit (functionName, ...)</strong>
+    <a name = "world:emit"></a>
+    <strong>world:emit (functionName, ...)</strong>
     </dt>
     <dd>
     Emits a callback in the World.
- Calls all functions with the functionName of added Systems
+ Calls all functions with the functionName of added Systems.
+ Automatically flushes before forwarding the event, unless this emit is nested
+ or a flush is already in progress.
+ If beforeEmit exists and returns a truthy value, listeners are skipped.
+ afterEmit is called after listeners when present.
 
 
     <h3>Parameters:</h3>
     <ul>
         <li><span class="parameter">functionName</span>
-            <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
          Name of functions to call.
         </li>
         <li><span class="parameter">...</span>
@@ -353,11 +518,47 @@
 
 </dd>
     <dt>
-    <a name = "World:clear"></a>
-    <strong>World:clear ()</strong>
+    <a name = "world:emitNoFlush"></a>
+    <strong>world:emitNoFlush (functionName, ...)</strong>
     </dt>
     <dd>
-    Removes all entities from the World
+    Emits a callback in the World without flushing.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">functionName</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
+         Name of functions to call.
+        </li>
+        <li><span class="parameter">...</span>
+         Parameters passed to System's functions
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><a class="type" href="../classes/World.html#">World</a></span>
+        self
+    </ol>
+
+
+    <h3>See also:</h3>
+    <ul>
+         <a href="../classes/World.html#world:emit">World:emit</a>
+    </ul>
+
+
+</dd>
+    <dt>
+    <a name = "world:clear"></a>
+    <strong>world:clear ()</strong>
+    </dt>
+    <dd>
+    Removes all Entities from the World and flushes.
+ Entities that were queued to be added are detached immediately without
+ onEntityRemoved. Already flushed Entities are removed through the normal flush.
 
 
 
@@ -373,18 +574,20 @@
 
 </dd>
     <dt>
-    <a name = "World:hasName"></a>
-    <strong>World:hasName ()</strong>
+    <a name = "world:getEntities"></a>
+    <strong>world:getEntities ()</strong>
     </dt>
     <dd>
-    Returns true if the World has a name.
+    Returns the List of flushed Entities in the World.
 
 
 
     <h3>Returns:</h3>
     <ol>
 
-           <span class="types"><span class="type">boolean</span></span>
+           <span class="types"><a class="type" href="../classes/List.html#">List</a></span>
+
+
 
     </ol>
 
@@ -393,18 +596,20 @@
 
 </dd>
     <dt>
-    <a name = "World:getName"></a>
-    <strong>World:getName ()</strong>
+    <a name = "world:getSystems"></a>
+    <strong>world:getSystems ()</strong>
     </dt>
     <dd>
-    Returns the name of the World.
+    Returns the List of Systems in the World.
 
 
 
     <h3>Returns:</h3>
     <ol>
 
-           <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
+           <span class="types"><a class="type" href="../classes/List.html#">List</a></span>
+
+
 
     </ol>
 
@@ -413,8 +618,132 @@
 
 </dd>
     <dt>
-    <a name = "World:onEntityAdded"></a>
-    <strong>World:onEntityAdded (e)</strong>
+    <a name = "world:serialize"></a>
+    <strong>world:serialize ([ignoreKeys])</strong>
+    </dt>
+    <dd>
+    Serializes serializable Entities in the World.
+ Flushes first. Only Entities with a serializable Component are included.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">ignoreKeys</span>
+            <span class="types"><span class="type">boolean</span></span>
+         If true, Entity keys are omitted
+         (<em>optional</em>)
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span>
+        Serialized world data
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "world:deserialize"></a>
+    <strong>world:deserialize (data[, startClean[, ignoreGenerator]])</strong>
+    </dt>
+    <dd>
+    Deserializes Entities into the World.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">data</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span>
+         Serialized world data
+        </li>
+        <li><span class="parameter">startClean</span>
+            <span class="types"><span class="type">boolean</span></span>
+         If true, existing Entities are cleared first
+         (<em>optional</em>)
+        </li>
+        <li><span class="parameter">ignoreGenerator</span>
+            <span class="types"><span class="type">boolean</span></span>
+         If true, the World's key generator state is left unchanged
+         (<em>optional</em>)
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><a class="type" href="../classes/World.html#">World</a></span>
+        self
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "world:setKeyGenerator"></a>
+    <strong>world:setKeyGenerator (generator, initialState)</strong>
+    </dt>
+    <dd>
+    Sets the function used to generate Entity keys.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">generator</span>
+            <span class="types"><span class="type">function</span></span>
+         Callable that receives the current state and returns key, newState
+        </li>
+        <li><span class="parameter">initialState</span>
+         Initial state passed to the generator
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><a class="type" href="../classes/World.html#">World</a></span>
+        self
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "world:getEntityByKey"></a>
+    <strong>world:getEntityByKey (key)</strong>
+    </dt>
+    <dd>
+    Gets an Entity by its key.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">key</span>
+         Key to look up
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><a class="type" href="../classes/Entity.html#">Entity</a> or <span class="type">nil</span></span>
+
+
+
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "world:onEntityAdded"></a>
+    <strong>world:onEntityAdded (e)</strong>
     </dt>
     <dd>
     Callback for when an Entity is added to the World.
@@ -434,8 +763,8 @@
 
 </dd>
     <dt>
-    <a name = "World:onEntityRemoved"></a>
-    <strong>World:onEntityRemoved (e)</strong>
+    <a name = "world:onEntityRemoved"></a>
+    <strong>world:onEntityRemoved (e)</strong>
     </dt>
     <dd>
     Callback for when an Entity is removed from the World.
@@ -453,15 +782,69 @@
 
 
 
+</dd>
+    <dt>
+    <a name = "world:setResource"></a>
+    <strong>world:setResource (name, resource)</strong>
+    </dt>
+    <dd>
+    Sets a named resource in the World.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">name</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
+         Name of the resource
+        </li>
+        <li><span class="parameter">resource</span>
+         Resource to set
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><a class="type" href="../classes/World.html#">World</a></span>
+        self
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "world:getResource"></a>
+    <strong>world:getResource (name)</strong>
+    </dt>
+    <dd>
+    Gets a named resource from the World.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">name</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
+         Name of the resource
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+        The resource, or nil if none was set
+    </ol>
+
+
+
+
 </dd>
 </dl>
-
-
 </div> <!-- id="content" -->
 </div> <!-- id="main" -->
 <div id="about">
-<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-08-18 15:20:32 </i>
+<i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
+<i style="float:right;">Last updated 2026-09-06 21:32:30 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/guides/Custom-Pools.md.html

@@ -0,0 +1,257 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
+<head>
+    <title>Reference</title>
+    <link rel="stylesheet" href="../ldoc.css" type="text/css" />
+</head>
+<body>
+
+<div id="container">
+
+<div id="product">
+	<div id="product_logo"></div>
+	<div id="product_name"><big><b></b></big></div>
+	<div id="product_description"></div>
+</div> <!-- id="product" -->
+
+
+<div id="main">
+
+
+<!-- Menu -->
+
+<div id="navigation">
+<br/>
+<h1>Concord</h1>
+
+
+<ul>
+  <li><a href="../index.html">Getting Started</a></li>
+</ul>
+
+<h2>Contents</h2>
+<ul>
+<li><a href="#Lists_upsides_and_downsides">Lists upsides and downsides </a></li>
+<li><a href="#List_Synchronization_Duplication">List Synchronization/Duplication </a></li>
+<li><a href="#Bring_your_own_data_structure">Bring your own data structure </a></li>
+</ul>
+
+
+<h2>Guides</h2>
+<ul class="nowrap">
+  <li><a href="../index.html">Getting Started</a></li>
+  <li><a href="../guides/Why-ECS.md.html">Why ECS? Why Concord?</a></li>
+  <li><strong>Custom Pools</strong></li>
+  <li><a href="../guides/Pool-Flushing-and-Timing.md.html">Pool Flushing and Timing</a></li>
+</ul>
+<h2>Builtin Components</h2>
+<ul class="nowrap">
+  <li><a href="../builtins/key.html">key</a></li>
+  <li><a href="../builtins/serializable.html">serializable</a></li>
+</ul>
+<h2>Modules</h2>
+<ul class="nowrap">
+  <li><a href="../modules/Components.html">Components</a></li>
+  <li><a href="../modules/Type.html">Type</a></li>
+  <li><a href="../modules/Utils.html">Utils</a></li>
+</ul>
+<h2>Classes</h2>
+<ul class="nowrap">
+  <li><a href="../classes/Component.html">Component</a></li>
+  <li><a href="../classes/Entity.html">Entity</a></li>
+  <li><a href="../classes/Filter.html">Filter</a></li>
+  <li><a href="../classes/List.html">List</a></li>
+  <li><a href="../classes/System.html">System</a></li>
+  <li><a href="../classes/World.html">World</a></li>
+</ul>
+
+</div>
+
+<div id="content">
+
+
+<h1>Custom Pools</h1>
+
+<p>This article details a escape hatch when the List used by Concord Pools is not enough for your System's need.</p>
+
+<p>First we need to understand why this escape hatch is needed so we discuss some upsides and downsides of Lists, we then discuss the solution based on onAdded/onRemoved that Pools provide, and finally look at the escape hatch and its benefits.</p>
+
+<p><a name="Lists_upsides_and_downsides"></a></p>
+<h2>Lists upsides and downsides</h2>
+
+<p>Pools in Concord by default use a List implementation that provides fast inserts, fast removals, fast search and fast iteration.</p>
+
+<p>These are all useful for Pools:</p>
+
+<ul>
+    <li>Pools need to check if an Entity is part of the List or not.</li>
+    <li>Pools need to add and remove Entities quickly</li>
+    <li>The user needs to be able to iterate through the Pool quickly.</li>
+</ul>
+
+<p>However these Lists have a few downsides:</p>
+
+<ul>
+    <li>They consume some extra memory because they need to keep a value -> key hashmap</li>
+    <li>They can't guarantee the order of their members</li>
+    <li>Sorting is expensive, since the hashmap needs to be regenerated</li>
+</ul>
+
+<p><a name="List_Synchronization_Duplication"></a></p>
+<h2>List Synchronization/Duplication</h2>
+
+<p>Sometimes you need to add your Entities to a different data structure like a Spatial Hash for Physics for example, when working with such a structure, you may end up with code that looks like this:</p>
+
+
+<pre>
+<span class="keyword">local</span> Physics = Concord.<span class="function-name">System</span>(<span class="string">"Physics"</span>, {
+  boxes = {<span class="string">"position"</span>, <span class="string">"size"</span>}
+})
+
+<span class="keyword">function</span> Physics:<span class="function-name">init</span> ()
+  <span class="comment">-- Create a new spatial hash
+</span>  <span class="keyword">local</span> spatialhash = <span class="function-name">spatialhash</span>()
+  self.spatialhash = spatialhash
+
+  <span class="comment">-- Whenever there is a new box added to the boxes list
+</span>  <span class="comment">-- Add the box to the spatial hash
+</span>  <span class="keyword">function</span> self.boxes:<span class="function-name">onAdded</span> (entity)
+    spatialhash:<span class="function-name">add</span>(entity)
+  <span class="keyword">end</span>
+
+  <span class="comment">-- Do the same when a box is removed
+</span>  <span class="keyword">function</span> self.boxes:<span class="function-name">onRemoved</span> (entity)
+    spatialhash:<span class="function-name">remove</span>(entity)
+  <span class="keyword">end</span>
+<span class="keyword">end</span>
+</pre>
+
+
+<p>Another fairly common example would be if you wanted a Sorted List for Rendering, and don't want the extra cost of sorting the List on each Event and instead would prefer to sort on insertion.</p>
+
+<p>As you can see we have duplication of data, our Spatial Hash has all the same Entities that our <code>boxes</code> List. And now the code to sync the List with the Spatial Hash lives inside of the Physics System, which makes it hard to share or reuse.</p>
+
+<p>So Concord offers an escape hatch out of this situation. If you only need the filtering part of a Pool and not the List part, you can bring your own data structure.</p>
+
+<p><a name="Bring_your_own_data_structure"></a></p>
+<h2>Bring your own data structure</h2>
+
+<p>This feature is called <strong>Custom Pools</strong></p>
+
+<p>The way to define a Custom Pool is fairly simple. You need to create a function that returns an object with 4 methods: <code>has</code>, <code>add</code>, <code>remove</code> and <code>clear</code></p>
+
+<p>We could redo our example above by creating a Custom Pool wrapper for our Spatial Hash (this is not always needed but may be helpful if the method names or their parameters don't match)</p>
+
+
+<pre>
+<span class="keyword">function</span> <span class="function-name">SpatialHashPool</span> ()
+  <span class="keyword">local</span> storage = {hash = <span class="function-name">spatialhash</span>()}
+
+  <span class="keyword">function</span> storage:<span class="function-name">clear</span>()
+    self.hash = <span class="function-name">spatialhash</span>()
+  <span class="keyword">end</span>
+
+  <span class="keyword">function</span> storage:<span class="function-name">add</span>(entity)
+    self.hash:<span class="function-name">add</span>(entity)
+  <span class="keyword">end</span>
+
+  <span class="keyword">function</span> storage:<span class="function-name">remove</span>(entity)
+    self.hash:<span class="function-name">remove</span>(entity)
+  <span class="keyword">end</span>
+
+  <span class="keyword">function</span> storage:<span class="function-name">has</span>(entity)
+    <span class="keyword">if</span> self.hash:<span class="function-name">search</span>(entity) &gt; <span class="number">0</span> <span class="keyword">then</span>
+      <span class="keyword">return</span> <span class="keyword">true</span>
+    <span class="keyword">else</span>
+      <span class="keyword">return</span> <span class="keyword">false</span>
+    <span class="keyword">end</span>
+  <span class="keyword">end</span>
+
+  <span class="keyword">return</span> storage
+<span class="keyword">end</span>
+</pre>
+
+
+<p>Then we can use this in any System like so</p>
+
+
+<pre>
+<span class="keyword">local</span> Physics = Concord.<span class="function-name">System</span>(<span class="string">"Physics"</span>, {
+  boxes = {<span class="string">"position"</span>, <span class="string">"size"</span>, constructor = SpatialHashPool}
+})
+</pre>
+
+
+<p>Please note that the code now lives outside of the Physics System and can now be reused by different Systems or even different projects. This abstraction helps us share and reuse code.</p>
+
+<h3>Additional Methods</h3>
+
+<p>The Storage we defined only exposes the methods needed by Concord which means that in order to iterate or perform other iterations you would need to use <code>self.boxes.hash</code> to access the Spatial Hash directly. However Concord does not enforce any limit on the methods exposed by your Pool other than those 4 required methods, so you could expose more utility functions that you need to access in your System's code.</p>
+
+<p>For example we could add</p>
+
+
+<pre>
+<span class="keyword">function</span> storage:<span class="function-name">query</span>(x, y, w, h)
+  <span class="keyword">return</span> self.hash:<span class="function-name">query</span>(x, y, w, h)
+<span class="keyword">end</span>
+</pre>
+
+
+<p>And use it in our System like so:</p>
+
+
+<pre>
+<span class="keyword">function</span> Physics:<span class="function-name">update</span>(dt)
+  <span class="keyword">local</span> visibleEntities = self.boxes:<span class="function-name">query</span>(<span class="number">0</span>, <span class="number">0</span>, <span class="number">800</span>, <span class="number">600</span>)
+
+  <span class="keyword">for</span> _, entity <span class="keyword">in</span> <span class="global">ipairs</span>(visibleEntities) <span class="keyword">do</span>
+    <span class="comment">-- Do something
+</span>  <span class="keyword">end</span>
+<span class="keyword">end</span>
+</pre>
+
+
+<h3>Pool definition</h3>
+
+<p>One advantage Custom Pools have is that when they are instantiated you get the complete Filter definition for the Pool as argument to the constructor function:</p>
+
+
+<pre>
+<span class="keyword">function</span> <span class="function-name">SpatialHashPool</span> (def)
+  <span class="global">print</span>(def) <span class="comment">-- {"position", "size"}
+</span>
+  <span class="comment">-- ...
+</span><span class="keyword">end</span>
+</pre>
+
+
+<p>This could be useful if you need some additional parameters to generate your storage for example</p>
+
+
+<pre>
+<span class="keyword">function</span> <span class="function-name">SpatialHashPool</span> (def)
+  <span class="keyword">local</span> storage = { hash = <span class="function-name">spatialhash</span>(def.width, def.height) }
+
+  <span class="comment">-- ...
+</span>
+  <span class="keyword">return</span> storage
+<span class="keyword">end</span>
+
+<span class="comment">-------
+</span>
+<span class="keyword">local</span> Physics = Concord.<span class="function-name">System</span>(<span class="string">"Physics"</span>, {
+  boxes = {<span class="string">"position"</span>, <span class="string">"size"</span>, constructor = SpatialHashPool, width = <span class="number">800</span>, height = <span class="number">600</span>}
+})
+</pre>
+</div> <!-- id="content" -->
+</div> <!-- id="main" -->
+<div id="about">
+<i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
+<i style="float:right;">Last updated 2026-09-06 21:32:30 </i>
+</div> <!-- id="about" -->
+</div> <!-- id="container" -->
+</body>
+</html>

docs/guides/Get-Started.md.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8"/>
+  <meta http-equiv="refresh" content="0; url=../index.html"/>
+  <link rel="canonical" href="../index.html"/>
+  <title>Getting Started</title>
+</head>
+<body>
+  <p><a href="../index.html">Getting Started</a></p>
+</body>
+</html>

docs/guides/Pool-Flushing-and-Timing.md.html

@@ -0,0 +1,225 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
+<head>
+    <title>Reference</title>
+    <link rel="stylesheet" href="../ldoc.css" type="text/css" />
+</head>
+<body>
+
+<div id="container">
+
+<div id="product">
+	<div id="product_logo"></div>
+	<div id="product_name"><big><b></b></big></div>
+	<div id="product_description"></div>
+</div> <!-- id="product" -->
+
+
+<div id="main">
+
+
+<!-- Menu -->
+
+<div id="navigation">
+<br/>
+<h1>Concord</h1>
+
+
+<ul>
+  <li><a href="../index.html">Getting Started</a></li>
+</ul>
+
+<h2>Contents</h2>
+<ul>
+<li><a href="#Synchronous_Operations">Synchronous Operations </a></li>
+<li><a href="#Asynchronous_Operations">Asynchronous Operations </a></li>
+</ul>
+
+
+<h2>Guides</h2>
+<ul class="nowrap">
+  <li><a href="../index.html">Getting Started</a></li>
+  <li><a href="../guides/Why-ECS.md.html">Why ECS? Why Concord?</a></li>
+  <li><a href="../guides/Custom-Pools.md.html">Custom Pools</a></li>
+  <li><strong>Pool Flushing and Timing</strong></li>
+</ul>
+<h2>Builtin Components</h2>
+<ul class="nowrap">
+  <li><a href="../builtins/key.html">key</a></li>
+  <li><a href="../builtins/serializable.html">serializable</a></li>
+</ul>
+<h2>Modules</h2>
+<ul class="nowrap">
+  <li><a href="../modules/Components.html">Components</a></li>
+  <li><a href="../modules/Type.html">Type</a></li>
+  <li><a href="../modules/Utils.html">Utils</a></li>
+</ul>
+<h2>Classes</h2>
+<ul class="nowrap">
+  <li><a href="../classes/Component.html">Component</a></li>
+  <li><a href="../classes/Entity.html">Entity</a></li>
+  <li><a href="../classes/Filter.html">Filter</a></li>
+  <li><a href="../classes/List.html">List</a></li>
+  <li><a href="../classes/System.html">System</a></li>
+  <li><a href="../classes/World.html">World</a></li>
+</ul>
+
+</div>
+
+<div id="content">
+
+
+<h1>Pool Flushing and Timing</h1>
+
+<p>This article will help you understand when the Pools' Filters get synchronized with the latest changes to Entities in the World, the relationship with Events, how it affects your game and how you can avoid the default behaviors.</p>
+
+<p><a name="Synchronous_Operations"></a></p>
+<h2>Synchronous Operations</h2>
+
+<p>Concord has a synchronous part and an asynchronous part. For the most part you'll be using the synchronous part, so whenever you make a change, most of the things update immediately, for example, giving a component, removing a component, getting a reference to an entity, sorting a  pool and many others are synchronous operations, they execute immediately when you perform them and you can see the effects in real time.</p>
+
+
+<pre>
+
+entity:<span class="function-name">give</span>(<span class="string">"position"</span>, <span class="number">10</span>, <span class="number">20</span>)
+
+entity.position <span class="comment">-- { x = 10, y = 20 }
+</span>
+entity.position.x = <span class="number">30</span>
+
+entity.position <span class="comment">-- { x = 30, y = 20 }
+</span>
+world:<span class="function-name">emit</span>(<span class="string">"update"</span>) <span class="comment">-- All Systems with an update listener are called immediately
+</span>                     <span class="comment">-- in the order you added them to the World
+</span>
+</pre>
+
+
+<p>As you can see most operations are immediate and you can see the results right after</p>
+
+<p><a name="Asynchronous_Operations"></a></p>
+<h2>Asynchronous Operations</h2>
+
+<p>There is one place however where we can't have immediate updates without introducing other sets of issues. That is Pools and Filters.</p>
+
+<p>As discussed in the in-depth Systems article, all Pools have an associated Filter, this Filter specified all the requirements Entities should have to be in the Pool. The one checking that Pools have all the Entities that meet their requirements is the World.</p>
+
+<h3>Syncing the Pools</h3>
+
+<p>In order to make sure that the Pools have the Entities they need, the World goes through all the necessary Entities and checks them against the filters of every Pool, one by one. This is a very expensive operation which we call Flush.</p>
+
+<p>You can actually trigger a Flush manually through <code>World:flush()</code> and you may sometimes want to do so. We will discuss the use cases later on.</p>
+
+<h3>When do we sync?</h3>
+
+<p>Entities change a lot, we often change multiple Components one after the other, add Entities in bulk, apply Assemblages that give multiple Components at once, delete a bunch of Entities that died simultaneously and so on.</p>
+
+<p>The World gets notified of ALL these changes, then keeps track of all the Entities that have been changed, removed, or added to the World, and waits until it's ready to perform a Flush.</p>
+
+<p>Flushes can be manually triggered as we previously discussed, but Concord also has a built-in mechanism for flushes to happen automatically.</p>
+
+<h3>When can the sync cause issues?</h3>
+
+<p>A sync performs additions and removals on Pools, so the biggest issue it can create is if you were iterating over one Pool, and suddenly the Entities inside were to shift around. This is not a problem with Concord, its List implementation or flushes, this also happens in regular Lua:</p>
+
+
+<pre>
+<span class="keyword">for</span> k, v <span class="keyword">in</span> <span class="global">ipairs</span>(t) <span class="keyword">do</span>
+  <span class="global">table</span>.<span class="function-name">insert</span>(t, <span class="number">1</span>, k) <span class="comment">-- This has undefined behavior and can cause an infinite loop
+</span>  <span class="global">print</span>(k, v)
+<span class="keyword">end</span>
+</pre>
+
+
+<p>So it's not a good idea to add or remove inside to the current Pool we are iterating on. So we should not flush while we iterate. These iterations generally happen inside event listeners inside your Systems, since that's where Pools live, so we shouldn't flush while a System's event listener is executing.</p>
+
+<h3><code>World:emit()</code></h3>
+
+<p>Concord tries to keep the list of Entities consistent through an entire <code>emit</code> event and won't automatically flush until the Event is over. This is so that if System A and System B handle the same event their Pools are consistent with each other, this assumption may be broken if <code>World:flush()</code> is called manually, but that's an explicit choice by the user.</p>
+
+<p>The best time for the automatic flush then is before the Event is forwarded to the Systems, it's a spot where no updates are being made, no iteration is going on, the World has complete control of the main thread.</p>
+
+<p>However <code>World:emit()</code> can be called from inside <code>World:emit()</code> so Concord makes sure that by default a nested <code>World:emit()</code> doesn't cause an automatic flush.</p>
+
+<p>If you wanted to emit an Event without causing a flush at all you can use <code>World:emitNoFlush()</code> as a replacement to <code>World:emit()</code>. This can be used to gain more control on when flushes happen.</p>
+
+
+<pre>
+love.update = <span class="keyword">function</span> (dt)
+  World:<span class="function-name">emit</span>(<span class="string">"update"</span>, dt) <span class="comment">-- Flushes before forwarding the event to the Systems
+</span><span class="keyword">end</span>
+
+love.draw = <span class="keyword">function</span> ()
+  World:<span class="function-name">emitNoFlush</span>(<span class="string">"draw"</span>) <span class="comment">-- Doesn't flush
+</span><span class="keyword">end</span>
+
+<span class="keyword">function</span> RenderSystem:<span class="function-name">update</span> ()
+  self:<span class="function-name">getWorld</span>():<span class="function-name">emit</span>(<span class="string">"prepareForRender"</span>) <span class="comment">-- Doesn't flush
+</span>
+  self:<span class="function-name">getWorld</span>():<span class="function-name">flush</span>() <span class="comment">-- This is a manual flush
+</span><span class="keyword">end</span>
+</pre>
+
+
+<h3><code>World:query()</code></h3>
+
+<p>This function is always executed against the most up to date version of the Entity list, it is not affected by flushes and it includes the latest updates at the time of executing the function.</p>
+
+
+<pre>
+<span class="keyword">local</span> myEntity = World:<span class="function-name">newEntity</span>():<span class="function-name">give</span>(<span class="string">"position"</span>, <span class="number">10</span>, <span class="number">20</span>)
+
+<span class="keyword">local</span> list = World:<span class="function-name">query</span>({<span class="string">"position"</span>}) <span class="comment">-- list contains myEntity even though there was no flush</span>
+</pre>
+
+
+<p>If you want to perform additions/removals of Entities, keep in mind you shouldn't use the <code>onMatch</code> function since that happens a loop. You can still use the list alternative.</p>
+
+
+<pre>
+<span class="comment">-- Don't do this
+</span>World:<span class="function-name">query</span>({<span class="string">"position"</span>}, <span class="keyword">function</span> (e)
+  World:<span class="function-name">newEntity</span>()
+  e:<span class="function-name">destroy</span>()
+<span class="keyword">end</span>)
+
+<span class="comment">-- Do this instead
+</span><span class="keyword">local</span> list = World:<span class="function-name">query</span>({<span class="string">"position"</span>})
+<span class="keyword">for</span> _, e <span class="keyword">in</span> <span class="global">ipairs</span>(list) <span class="keyword">do</span>
+  <span class="comment">-- This is safe because list is not mutated
+</span>  World:<span class="function-name">newEntity</span>()
+  e:<span class="function-name">destroy</span>()
+<span class="keyword">end</span>
+</pre>
+
+
+<h3>Forbidden Flush</h3>
+
+<p>There are a few places where flushing is forbidden the list is short though:</p>
+
+<ul>
+    <li><a href="../classes/World.html#world:onEntityAdded">World:onEntityAdded</a> / <a href="../classes/World.html#world:onEntityRemoved">World:onEntityRemoved</a></li>
+    <li><code>Pool:onAdded</code> / <code>Pool:onRemoved</code></li>
+</ul>
+
+<p>These callbacks happen during a flush, you can't flush during a flush since the buffers are in use.</p>
+
+<p>If your code performs a flush but may be called from inside of one of these callbacks you can use <code>World:canFlush()</code> to check if flushing is allowed, otherwise an error will be thrown.</p>
+
+
+<pre>
+<span class="keyword">if</span> World:<span class="function-name">canFlush</span>() <span class="keyword">then</span>
+  World:<span class="function-name">flush</span>()
+<span class="keyword">end</span>
+</pre>
+</div> <!-- id="content" -->
+</div> <!-- id="main" -->
+<div id="about">
+<i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
+<i style="float:right;">Last updated 2026-09-06 21:32:30 </i>
+</div> <!-- id="about" -->
+</div> <!-- id="container" -->
+</body>
+</html>

docs/guides/Why-ECS.md.html

@@ -0,0 +1,150 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html>
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
+<head>
+    <title>Reference</title>
+    <link rel="stylesheet" href="../ldoc.css" type="text/css" />
+</head>
+<body>
+
+<div id="container">
+
+<div id="product">
+	<div id="product_logo"></div>
+	<div id="product_name"><big><b></b></big></div>
+	<div id="product_description"></div>
+</div> <!-- id="product" -->
+
+
+<div id="main">
+
+
+<!-- Menu -->
+
+<div id="navigation">
+<br/>
+<h1>Concord</h1>
+
+
+<ul>
+  <li><a href="../index.html">Getting Started</a></li>
+</ul>
+
+<h2>Contents</h2>
+<ul>
+<li><a href="#It_s_a_trend">It's a trend </a></li>
+<li><a href="#It_doesn_t_rely_on_inheritance">It doesn't rely on inheritance </a></li>
+<li><a href="#It_s_faster">It's faster </a></li>
+<li><a href="#It_s_more_organized">It's more organized </a></li>
+</ul>
+
+
+<h2>Guides</h2>
+<ul class="nowrap">
+  <li><a href="../index.html">Getting Started</a></li>
+  <li><strong>Why ECS? Why Concord?</strong></li>
+  <li><a href="../guides/Custom-Pools.md.html">Custom Pools</a></li>
+  <li><a href="../guides/Pool-Flushing-and-Timing.md.html">Pool Flushing and Timing</a></li>
+</ul>
+<h2>Builtin Components</h2>
+<ul class="nowrap">
+  <li><a href="../builtins/key.html">key</a></li>
+  <li><a href="../builtins/serializable.html">serializable</a></li>
+</ul>
+<h2>Modules</h2>
+<ul class="nowrap">
+  <li><a href="../modules/Components.html">Components</a></li>
+  <li><a href="../modules/Type.html">Type</a></li>
+  <li><a href="../modules/Utils.html">Utils</a></li>
+</ul>
+<h2>Classes</h2>
+<ul class="nowrap">
+  <li><a href="../classes/Component.html">Component</a></li>
+  <li><a href="../classes/Entity.html">Entity</a></li>
+  <li><a href="../classes/Filter.html">Filter</a></li>
+  <li><a href="../classes/List.html">List</a></li>
+  <li><a href="../classes/System.html">System</a></li>
+  <li><a href="../classes/World.html">World</a></li>
+</ul>
+
+</div>
+
+<div id="content">
+
+
+<h1>Why ECS? Why Concord?</h1>
+
+<p>There are various reasons why people choose ECS for their projects, there is a very large <a href="https://github.com/SanderMertens/ecs-faq">FAQ for ECS</a> made by the author of <a href="https://github.com/SanderMertens/flecs">FLECS</a>, but we can go through some of the reasons here as a starting point:</p>
+
+<p><a name="It_s_a_trend"></a></p>
+<h2>It's a trend</h2>
+
+<p>Yeah it's a trend, most game engines are moving towards ECS as their pattern of choice, big names in the industry are using the pattern and more people are following this trend (<a href="https://unity.com/ecs">Unity</a>, <a href="https://dev.epicgames.com/community/learning/talks-and-demos/37Oz/large-numbers-of-entities-with-mass-in-unreal-engine-5">Unreal Engine</a>, <a href="https://www.youtube.com/watch?v=W3aieHjyNvw">Overwatch (video)</a>, etc).</p>
+
+<p>This is not a good reason to use Concord but it does help that more and more documentation is being written about ECS and how to use it to organize your game code.</p>
+
+<p>But this is also a downside, ECS is NOW being used by more game engines, but OOP has been the king for way longer and is more prevalent and used in this market.</p>
+
+<p>Concord isn't here as part of the trend, and doesn't intend to follow what other ECS frameworks do. It instead presents it's own interpretation of ECS and makes a heavy focus on the ease of use and development.</p>
+
+<p><a name="It_doesn_t_rely_on_inheritance"></a></p>
+<h2>It doesn't rely on inheritance</h2>
+
+<p>So to follow this discussion, a reason people choose ECS is so that they can get away from the ugly parts of OOP.</p>
+
+<p>The ugly part being <a href="https://en.wikipedia.org/wiki/Inheritance_(object-oriented_programming">inheritance and all the problems it comes with</a>. A possible solution would be mixins or decorators, but most people agree that the problems are still there.</p>
+
+<p>So that's when they start to consider <a href="https://en.wikipedia.org/wiki/Composition_over_inheritance">composition over inheritance</a>. This is a very common pattern in OOP where you <a href="https://en.wikipedia.org/wiki/Object_composition">put objects inside objects</a> instead of trying to define their behavior in term of inheritance. And ECS is very close to this pattern, remember how we put Components inside of our Entities? That's composition.</p>
+
+<p>But in "Composition over inheritance" we would still define our behaviors in our objects, and we would still need to <a href="https://en.wikipedia.org/wiki/Delegation_(object-oriented_programming">forward our events to each component</a>. So that's when people start to consider ECS, behaviors existing outside of the object/entity helps organize the code more neatly.</p>
+
+<p>Concord does make use of OOP and the <a href="https://en.wikipedia.org/wiki/Metaprogramming">metaprogramming</a> functionality in Lua, to help implements ECS, and does still allow you to work with Components and Systems as if they were objects. So if you are escaping from the "bad parts" of OOP, your OOP knowledge will not be wasted while using Concord.</p>
+
+<p><a name="It_s_faster"></a></p>
+<h2>It's faster</h2>
+
+<p>Well this is the argument most game engines make to sell you ECS as the best architecture.</p>
+
+<p>Remember our behaviors and data are stored separately? This helps keep our data small.
+Remember how we don't make distinction between entities and instead rely on filtering? This allows us to pack our entities close together in memory so that we don't have to jump around so much when looping through them in our systems.</p>
+
+<p>Unfortunately this doesn't apply to Concord because in Lua land we can't benefit from all of this, our representation of Components, Entities and Pools don't provide an advantage towards objects. Yeah Concord is fast for the majority of use cases, but this is not its selling point. You can probably write faster code without a library, and there are plenty alternatives that focus on speed.</p>
+
+<p>Lua although fast, is not used for optimization purposes, and the same applies to Concord. Concord tries to be reliable, easy to use and feature complete, it is not an optimization.</p>
+
+<p>We actually made <a href="https://github.com/Keyslam/Sniper">an experiment</a> making a super efficient ECS library, but it was awful to code with and one line of code could throw all the optimizations away. In our opinion, although it's possible to make a super-fast ECS library and speed does make a huge difference, it's not worth it when working in Lua where JIT optimization is hard</p>
+
+<h3>Reminds me of Functional Programming</h3>
+
+<p>If you have tried <a href="https://elmprogramming.com/elm-architecture-conclusion.html">"The Elm Architecture"</a> or <a href="https://redux.js.org/tutorials/fundamentals/part-2-concepts-data-flow#redux-application-data-flow">"Redux"</a> you may find the unidirectional data flow in ECS familiar.</p>
+
+<p>If we think about our Entities and Components as our Model or State, and Systems as our Update or Reducers.
+The only way to mutate our Model/State is through an Event processed by our Update/Reducer</p>
+
+<p>This <a href="https://en.wikipedia.org/wiki/Unidirectional_Data_Flow_%28computer_science%29">unidirectional data flow</a> and the concept of using <a href="https://en.wikipedia.org/wiki/Fold_%28higher-order_function%29">reducer functions</a> as a way to update state is a proven concept and widely used in Functional Programming.</p>
+
+<p>This mental model has worked really well for Front-end Web developers, and is a very good way to reason about how our systems update over time while keeping our state as our only source of truth and purely as data. If you are already familiar with these architecture you'll be able to pick up Concord and ECS in general, with relative ease.</p>
+
+<p>In addition to that, if we combine ECS with <a href="https://en.wikipedia.org/wiki/Persistent_data_structure">immutable data structures</a> for Components and Entities, then we wouldn't be too far away from "The Elm Architecture" and all its benefits like <a href="https://elm-lang.org/news/time-travel-made-easy">Time Traveling debugging</a>.</p>
+
+<p>Unfortunately immutable data structures aren't cheap and the Lua garbage collector is not tuned for them.
+Concord doesn't use immutable data structures, but if you treat your Components as just data, it does allow you to recover state through serialization and deserialization.</p>
+
+<p><a name="It_s_more_organized"></a></p>
+<h2>It's more organized</h2>
+
+<p>If you find this mental model intuitive and start to reason only through this paradigm you'll find yourself writing code in a more structured way. There are very specific ways to do things in ECS and Concord will push you towards these patterns.</p>
+
+<p>This is however at the expense of a higher learning curve with a big payoff in maintainability and reusability of your code. Concord keeps this risk low by allowing you to write code outside of Concord without extra hurdles.</p>
+
+<p>In the long run we hope you'll find yourself at home using Concord, without needing these escape hatches, in order to accomplish this we try to ease this learning curve through guides, documentation and tooling that will hopefully make working with Concord a great experience.</p>
+</div> <!-- id="content" -->
+</div> <!-- id="main" -->
+<div id="about">
+<i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
+<i style="float:right;">Last updated 2026-09-06 21:32:30 </i>
+</div> <!-- id="about" -->
+</div> <!-- id="container" -->
+</body>
+</html>

docs/index.html

@@ -27,21 +27,40 @@
 <h1>Concord</h1>
 
 
+<ul>
+  <li><strong>Getting Started</strong></li>
+</ul>
+
+<h2>Contents</h2>
+<ul>
+<li><a href="#Installation">Installation </a></li>
+</ul>
 
 
+<h2>Guides</h2>
+<ul class="nowrap">
+  <li><strong>Getting Started</strong></li>
+  <li><a href="guides/Why-ECS.md.html">Why ECS? Why Concord?</a></li>
+  <li><a href="guides/Custom-Pools.md.html">Custom Pools</a></li>
+  <li><a href="guides/Pool-Flushing-and-Timing.md.html">Pool Flushing and Timing</a></li>
+</ul>
+<h2>Builtin Components</h2>
+<ul class="nowrap">
+  <li><a href="builtins/key.html">key</a></li>
+  <li><a href="builtins/serializable.html">serializable</a></li>
+</ul>
 <h2>Modules</h2>
 <ul class="nowrap">
   <li><a href="modules/Components.html">Components</a></li>
-  <li><a href="modules/Concord.html">Concord</a></li>
-  <li><a href="modules/type.html">type</a></li>
-  <li><a href="modules/utils.html">utils</a></li>
+  <li><a href="modules/Type.html">Type</a></li>
+  <li><a href="modules/Utils.html">Utils</a></li>
 </ul>
 <h2>Classes</h2>
 <ul class="nowrap">
   <li><a href="classes/Component.html">Component</a></li>
   <li><a href="classes/Entity.html">Entity</a></li>
+  <li><a href="classes/Filter.html">Filter</a></li>
   <li><a href="classes/List.html">List</a></li>
-  <li><a href="classes/Pool.html">Pool</a></li>
   <li><a href="classes/System.html">System</a></li>
   <li><a href="classes/World.html">World</a></li>
 </ul>
@@ -51,63 +70,255 @@
 <div id="content">
 
 
-  <h2>A feature-complete ECS library</h2>
+<h1>Getting Started</h1>
 
-<h2>Modules</h2>
-<table class="module_list">
-	<tr>
-		<td class="name"  nowrap><a href="modules/Components.html">Components</a></td>
-		<td class="summary">Container for registered ComponentClasses</td>
-	</tr>
-	<tr>
-		<td class="name"  nowrap><a href="modules/Concord.html">Concord</a></td>
-		<td class="summary"></td>
-	</tr>
-	<tr>
-		<td class="name"  nowrap><a href="modules/type.html">type</a></td>
-		<td class="summary">Type
- Helper module to do easy type checking for Concord types</td>
-	</tr>
-	<tr>
-		<td class="name"  nowrap><a href="modules/utils.html">utils</a></td>
-		<td class="summary">Utils
- Helper module for misc operations</td>
-	</tr>
-</table>
-<h2>Classes</h2>
-<table class="module_list">
-	<tr>
-		<td class="name"  nowrap><a href="classes/Component.html">Component</a></td>
-		<td class="summary">A pure data container that is contained by a single entity.</td>
-	</tr>
-	<tr>
-		<td class="name"  nowrap><a href="classes/Entity.html">Entity</a></td>
-		<td class="summary">An object that exists in a world.</td>
-	</tr>
-	<tr>
-		<td class="name"  nowrap><a href="classes/List.html">List</a></td>
-		<td class="summary">Data structure that allows for fast removal at the cost of containing order.</td>
-	</tr>
-	<tr>
-		<td class="name"  nowrap><a href="classes/Pool.html">Pool</a></td>
-		<td class="summary">Used to iterate over Entities with a specific Components
- A Pool contain a any amount of Entities.</td>
-	</tr>
-	<tr>
-		<td class="name"  nowrap><a href="classes/System.html">System</a></td>
-		<td class="summary">Iterates over Entities.</td>
-	</tr>
-	<tr>
-		<td class="name"  nowrap><a href="classes/World.html">World</a></td>
-		<td class="summary">A collection of Systems and Entities.</td>
-	</tr>
-</table>
+<p>Concord is a feature complete library that allows you to use Entity - Component - System (ECS) model  to write and organize your Lua code.</p>
 
+<p>Concord puts a lot of effort on being easy to use and provide a great developer experience, while trying to be competitive in performance with alternative libraries.</p>
+
+<p><a name="Installation"></a></p>
+<h2>Installation</h2>
+
+<p>As a first step you will need to download this repository and add the <code>concord</code> folder to your project.</p>
+
+<p>In that folder you will find all the necessary files to use Concord.</p>
+
+<p>Once added you can import Concord in your code</p>
+
+
+<pre>
+<span class="keyword">local</span> Concord = <span class="global">require</span>(<span class="string">"path.to.concord"</span>)
+</pre>
+
+
+<aside class="callout callout-note">
+
+<p>Please note that the file imported should be <code>concord/init.lua</code>, some Lua runtimes will allow you to require <code>concord</code> but others will need <code>concord.init</code></p>
+
+</aside>
+
+<h3>World</h3>
+
+<p>The first thing you will define with Concord is a World.</p>
+
+<p>The World will provide a single interaction point for all our Systems, and will hold all our Entities.</p>
+
+<p>We will explain those concepts later, but first we need a World:</p>
+
+
+<pre>
+<span class="keyword">local</span> world = Concord.<span class="function-name">World</span>()
+</pre>
+
+
+<h3>Components</h3>
+
+<p>You can think of Components as the data and state that make up all of your game.
+Components themselves don't exist as part of our World, they instead are the pieces that build up Entities.</p>
+
+<p>Components have a name, and some arbitrary shape that you can define.
+For example if we wanted to store the Position of a given Entity, we would define a component called <code>position</code> with a shape that could be something like <code>{x: number, y: number}</code></p>
+
+<p>In Concord this would look like this:</p>
+
+
+<pre>
+Concord.<span class="function-name">Component</span>(<span class="string">"position"</span>, <span class="keyword">function</span> (component, x, y)
+  component.x = x
+  component.y = y
+<span class="keyword">end</span>)
+</pre>
+
+
+<p>The first argument is the name, and the second is what we call the <strong>populate</strong> function.
+Components start as empty tables and this <strong>populate</strong> function assigns the values for each of the Component properties.</p>
+
+<p>Sometimes you don't need to store data on the Component since the Component itself will act as a flag, in those cases you don't need to provide a <strong>populate</strong> function:</p>
+
+
+<pre>
+Concord.<span class="function-name">Component</span>(<span class="string">"terrestrial"</span>)
+</pre>
+
+
+<aside class="callout callout-note">
+
+<p>All Components are registered to Concord itself, not to a specific World.
+This is why all the Components you define, regardless of the World you use them in, MUST have different names, two different Components can't share a name.</p>
+
+</aside>
+
+<h3>Entities</h3>
+
+<p>In ECS everything that exists as part of the World is an Entity. An Entity could be a Player, an Enemy, a Crate, a Bullet, etc.</p>
+
+<p>Entities by themselves are empty packages with nothing on them, and they would all behave the same if we left them like that. To tell them appart and give unique data to each of them, we need to give them some Components.</p>
+
+<p>In Concord this is very simple:</p>
+
+
+<pre>
+<span class="keyword">local</span> Cat = world:<span class="function-name">newEntity</span>()
+<span class="comment">--local Cat = Concord.Entity(world) -- Alternative syntax
+</span>
+Cat:<span class="function-name">give</span>(<span class="string">"position"</span>, <span class="number">50</span>, <span class="number">50</span>)
+Cat:<span class="function-name">give</span>(<span class="string">"terrestrial"</span>)
+</pre>
+
+
+<p>Once you give a Component to an Entity, the Component will become a part of it:</p>
+
+
+<pre>
+<span class="global">print</span>(Cat.position.x, Cat.position.y) <span class="comment">-- Prints: 50, 50
+</span>
+<span class="keyword">if</span> Cat.terrestrial <span class="keyword">then</span> <span class="global">print</span>(<span class="string">"Walks!"</span>) <span class="keyword">end</span> <span class="comment">-- Prints: Walks! </span>
+</pre>
+
+
+<aside class="callout callout-note">
+
+<p>Any Component can be given to any Entity ONCE. You can't give a Component multiple times, giving the same Component one more time will override the previous instance of the Component.</p>
+
+</aside>
+
+<h3>Filters</h3>
+
+<p>The power of Concord and ECS in general comes from grouping a bunch of Entities based on rules. These rules acts as a Filter where we can ask the World for all Entities that have all the Components we required.</p>
+
+<p>For example we could ask the World for a list of all the Entities that are <code>terrestrial</code> and have a <code>position</code>, and that are not a <code>machine</code>:</p>
+
+
+<pre>
+<span class="keyword">local</span> animals = world:<span class="function-name">query</span>({ <span class="string">"terrestrial"</span>, <span class="string">"position"</span>, <span class="string">"!machine"</span> }) <span class="comment">-- The ! in front of machine indicates negation
+</span>
+<span class="keyword">for</span> i, entity <span class="keyword">in</span> <span class="global">ipairs</span>(animals) <span class="keyword">do</span>
+  <span class="global">print</span>(entity.position.x, entity.position.y)
+<span class="keyword">end</span>
+</pre>
+
+
+<details><summary>Side note on Filter rules</summary>
+
+<p>If we had another Entity like this one:</p>
+
+
+<pre>
+<span class="keyword">local</span> Parrot = world:<span class="function-name">newEntity</span>()
+
+Parrot:<span class="function-name">give</span>(<span class="string">"position"</span>, <span class="number">100</span>, <span class="number">100</span>)
+</pre>
+
+
+<p>It would not be part of our list above, since the filter required:</p>
+
+<p>_<code>terrestrial</code> and <code>position</code> and not <code>machine</code>_</p>
+
+<p>And although Parrot has <code>position</code> and doesn't have <code>machine</code>, it lacks the <code>terrestrial</code> Component.</p>
+
+</details>
+
+<p>This is great but the <a href="classes/World.html#world:query">World:query</a> operation is rather expensive, so Concord instead provides Pools.
+A Pool has an associated Filter and will be updated when Entities are added or modified in the World.</p>
+
+<p>In order to use pools however, we need to speak about Systems</p>
+
+<h3>Systems</h3>
+
+<p>In ECS, Components and Entities generally don't have behavior themselves, and instead rely on Systems that define how a group of Entities should behave.</p>
+
+<p>For example if we want all terrestrial animals to move 5 pixels to the right every time we receive a <code>move</code> event we would first create a System like:</p>
+
+
+<pre>
+<span class="keyword">local</span> Movement = Concord.<span class="function-name">System</span>(<span class="string">"Movement"</span>, {animals = { <span class="string">"terrestrial"</span>, <span class="string">"position"</span> }})
+</pre>
+
+
+<p>This system is called <code>Movement</code> and has a Pool called <code>animals</code> that contains all the Entities with <code>terrestrial</code> and <code>position</code> Components.</p>
+
+<p>We now want to receive all <code>move</code> events. To do that we define a callback in our System like so:</p>
+
+
+<pre>
+<span class="keyword">function</span> Movement:<span class="function-name">move</span> ()
+  <span class="keyword">for</span> i, entity <span class="keyword">in</span> <span class="global">ipairs</span>(self.animals) <span class="keyword">do</span>
+    entity.position.x = entity.position.x + <span class="number">5</span>
+  <span class="keyword">end</span>
+<span class="keyword">end</span>
+</pre>
+
+
+<p>Whenever we receive a <code>move</code> event in our World, this callback will execute, and the Movement System will iterate through the Pool of animals changing their position Components to move them 5 pixels to the right.</p>
+
+<h3>Events</h3>
+
+<p>In the previous section we defined a <code>move</code> callback, but we don't yet know how to execute that callback.</p>
+
+<p>To do that first the System needs to be added to our World</p>
+
+
+<pre>
+world:<span class="function-name">addSystem</span>(Movement)
+</pre>
+
+
+<aside class="callout callout-note">
+
+<p>You can add each System once to a given World.
+A System can be added to multiple Worlds (they will be different/separate instances of the System).</p>
+
+</aside>
+
+<p>Finally we need to fire the <code>move</code> event, to do that, we don't call the System directly, instead we emit the event to the World</p>
+
+
+<pre>
+world:<span class="function-name">emit</span>(<span class="string">"move"</span>)
+</pre>
+
+
+<p>Once emitted, all the Systems that define a <code>move</code> callback will be called in the order they were added to the World.</p>
+
+<p>You can also provide extra arguments to these events, for example if we had:</p>
+
+
+<pre>
+<span class="keyword">function</span> Movement:<span class="function-name">update</span>(dt)
+  <span class="comment">-- Do something here
+</span><span class="keyword">end</span>
+</pre>
+
+
+<p>You could provide the <code>dt</code> argument like so:</p>
+
+
+<pre>
+world:<span class="function-name">emit</span>(<span class="string">"update"</span>, <span class="number">5</span>) <span class="comment">--dt = 5</span>
+</pre>
+
+
+<h3>Summary</h3>
+
+<p>We defined a few big terms and how they are used in Concord, but to summarize them:</p>
+
+<ul>
+    <li><strong>World</strong>: This is where Entities and Systems live, it receives external and internal Events.</li>
+    <li><strong>Components</strong>: Data and state, each with a name and a shape. Each Component describes a specific aspect of an Entity.</li>
+    <li><strong>Entities</strong>: Everything that exists in the World. They are bundles of Components.</li>
+    <li><strong>Filters</strong>: A way to group Entities based on the Components they have or don't have.</li>
+    <li><strong>Systems</strong>: Behaviors that apply to groups of Entities and react to Events received by the World.</li>
+    <li><strong>Events</strong>: Signals that tell the World something happened or needs to happen, the World delegates the Events to all the Systems that can respond to it.</li>
+</ul>
+
+<p>These are Concord definitions, and although they may apply to other ECS libraries or frameworks, some differences may exist.</p>
+
+<p>With this we have covered the basics. With the API docs you would be ready to start working with Concord, but if you want to dig into more advanced concepts read some of our Guides instead.</p>
 </div> <!-- id="content" -->
 </div> <!-- id="main" -->
 <div id="about">
-<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-08-18 15:20:32 </i>
+<i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
+<i style="float:right;">Last updated 2026-09-06 21:32:30 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/ldoc.css

@@ -294,6 +294,7 @@ pre .library { color: #0e7c6b; }
 pre .marker { color: #512b1e; background: #fedc56; font-weight: bold; }
 pre .string { color: #8080ff; }
 pre .number { color: #f8660d; }
+pre .function-name { color: #60447f; }
 pre .operator { color: #2239a8; font-weight: bold; }
 pre .preprocessor, pre .prepro { color: #a33243; }
 pre .global { color: #800080; }
@@ -301,3 +302,56 @@ pre .user-keyword { color: #800080; }
 pre .prompt { color: #558817; }
 pre .url { color: #272fc2; text-decoration: underline; }
 
+
+/* Guide callouts and details */
+
+aside.callout {
+    margin: 1em 0;
+    padding: 0.75em 1em;
+    border-radius: 4px;
+    border-left: 4px solid #0969da;
+    background: #e7f1fb;
+}
+
+aside.callout-note { border-left-color: #0969da; background: #e7f1fb; }
+aside.callout-tip { border-left-color: #1a7f37; background: #e6f6eb; }
+aside.callout-important { border-left-color: #8250df; background: #f1e9fb; }
+aside.callout-warning { border-left-color: #9a6700; background: #fff4d1; }
+aside.callout-caution { border-left-color: #cf222e; background: #ffe8ea; }
+
+aside.callout::before {
+    display: block;
+    font-weight: bold;
+    margin-bottom: 0.35em;
+}
+
+aside.callout-note::before { content: "Note"; }
+aside.callout-tip::before { content: "Tip"; }
+aside.callout-important::before { content: "Important"; }
+aside.callout-warning::before { content: "Warning"; }
+aside.callout-caution::before { content: "Caution"; }
+
+aside.callout p {
+    margin: 0.4em 0 0 0;
+}
+
+aside.callout p:first-child {
+    margin-top: 0;
+}
+
+details {
+    margin: 1em 0;
+    padding: 0.75em 1em;
+    background: #f7f7f7;
+    border: 1px solid #c0c0c0;
+    border-radius: 4px;
+}
+
+details summary {
+    cursor: pointer;
+    font-weight: bold;
+}
+
+details[open] summary {
+    margin-bottom: 0.6em;
+}

docs/modules/Concord.html

@@ -1,76 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html>
-<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
-<head>
-    <title>Reference</title>
-    <link rel="stylesheet" href="../ldoc.css" type="text/css" />
-</head>
-<body>
-
-<div id="container">
-
-<div id="product">
-	<div id="product_logo"></div>
-	<div id="product_name"><big><b></b></big></div>
-	<div id="product_description"></div>
-</div> <!-- id="product" -->
-
-
-<div id="main">
-
-
-<!-- Menu -->
-
-<div id="navigation">
-<br/>
-<h1>Concord</h1>
-
-<ul>
-  <li><a href="../index.html">Index</a></li>
-</ul>
-
-
-
-<h2>Modules</h2>
-<ul class="nowrap">
-  <li><a href="../modules/Components.html">Components</a></li>
-  <li><strong>Concord</strong></li>
-  <li><a href="../modules/type.html">type</a></li>
-  <li><a href="../modules/utils.html">utils</a></li>
-</ul>
-<h2>Classes</h2>
-<ul class="nowrap">
-  <li><a href="../classes/Component.html">Component</a></li>
-  <li><a href="../classes/Entity.html">Entity</a></li>
-  <li><a href="../classes/List.html">List</a></li>
-  <li><a href="../classes/Pool.html">Pool</a></li>
-  <li><a href="../classes/System.html">System</a></li>
-  <li><a href="../classes/World.html">World</a></li>
-</ul>
-
-</div>
-
-<div id="content">
-
-<h1>Module <code>Concord</code></h1>
-<p></p>
-<p></p>
-
-
-
-<br/>
-<br/>
-
-
-
-
-</div> <!-- id="content" -->
-</div> <!-- id="main" -->
-<div id="about">
-<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-08-18 15:20:32 </i>
-</div> <!-- id="about" -->
-</div> <!-- id="container" -->
-</body>
-</html>

docs/modules/assemblages.html

@@ -1,182 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html>
-<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
-<head>
-    <title>Reference</title>
-    <link rel="stylesheet" href="../ldoc.css" type="text/css" />
-</head>
-<body>
-
-<div id="container">
-
-<div id="product">
-	<div id="product_logo"></div>
-	<div id="product_name"><big><b></b></big></div>
-	<div id="product_description"></div>
-</div> <!-- id="product" -->
-
-
-<div id="main">
-
-
-<!-- Menu -->
-
-<div id="navigation">
-<br/>
-<h1>Concord</h1>
-
-<ul>
-  <li><a href="../index.html">Index</a></li>
-</ul>
-
-<h2>Contents</h2>
-<ul>
-<li><a href="#Functions">Functions</a></li>
-</ul>
-
-
-<h2>Modules</h2>
-<ul class="nowrap">
-  <li><strong>Assemblages</strong></li>
-  <li><a href="../modules/Components.html">Components</a></li>
-  <li><a href="../modules/Concord.html">Concord</a></li>
-  <li><a href="../modules/Systems.html">Systems</a></li>
-  <li><a href="../modules/type.html">type</a></li>
-  <li><a href="../modules/utils.html">utils</a></li>
-  <li><a href="../modules/worlds.html">worlds</a></li>
-</ul>
-<h2>Classes</h2>
-<ul class="nowrap">
-  <li><a href="../classes/Assemblage.html">Assemblage</a></li>
-  <li><a href="../classes/Component.html">Component</a></li>
-  <li><a href="../classes/Entity.html">Entity</a></li>
-  <li><a href="../classes/List.html">List</a></li>
-  <li><a href="../classes/Pool.html">Pool</a></li>
-  <li><a href="../classes/System.html">System</a></li>
-  <li><a href="../classes/World.html">World</a></li>
-</ul>
-
-</div>
-
-<div id="content">
-
-<h1>Module <code>Assemblages</code></h1>
-<p>A container for registered <a href="../classes/Assemblage.html#">Assemblage</a>s</p>
-<p></p>
-
-
-<h2><a href="#Functions">Functions</a></h2>
-<table class="function_list">
-	<tr>
-	<td class="name" nowrap><a href="#register">register (name, assemblage)</a></td>
-	<td class="summary">Registers an Assemblage.</td>
-	</tr>
-	<tr>
-	<td class="name" nowrap><a href="#has">has (name)</a></td>
-	<td class="summary">Returns true if the containter has an Assemblage with the specified name</td>
-	</tr>
-	<tr>
-	<td class="name" nowrap><a href="#get">get (name)</a></td>
-	<td class="summary">Returns the Assemblage with the specified name</td>
-	</tr>
-</table>
-
-<br/>
-<br/>
-
-
-    <h2 class="section-header "><a name="Functions"></a>Functions</h2>
-
-    <dl class="function">
-    <dt>
-    <a name = "register"></a>
-    <strong>register (name, assemblage)</strong>
-    </dt>
-    <dd>
-    Registers an Assemblage.
-
-
-    <h3>Parameters:</h3>
-    <ul>
-        <li><span class="parameter">name</span>
-            <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
-         Name to register under
-        </li>
-        <li><span class="parameter">assemblage</span>
-            <span class="types"><a class="type" href="../classes/Assemblage.html#">Assemblage</a></span>
-         Assemblage to register
-        </li>
-    </ul>
-
-
-
-
-
-</dd>
-    <dt>
-    <a name = "has"></a>
-    <strong>has (name)</strong>
-    </dt>
-    <dd>
-    Returns true if the containter has an Assemblage with the specified name
-
-
-    <h3>Parameters:</h3>
-    <ul>
-        <li><span class="parameter">name</span>
-            <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
-         Name of the Assemblage to check
-        </li>
-    </ul>
-
-    <h3>Returns:</h3>
-    <ol>
-
-           <span class="types"><span class="type">boolean</span></span>
-
-    </ol>
-
-
-
-
-</dd>
-    <dt>
-    <a name = "get"></a>
-    <strong>get (name)</strong>
-    </dt>
-    <dd>
-    Returns the Assemblage with the specified name
-
-
-    <h3>Parameters:</h3>
-    <ul>
-        <li><span class="parameter">name</span>
-            <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
-         Name of the Assemblage to get
-        </li>
-    </ul>
-
-    <h3>Returns:</h3>
-    <ol>
-
-           <span class="types"><a class="type" href="../classes/Assemblage.html#">Assemblage</a></span>
-
-    </ol>
-
-
-
-
-</dd>
-</dl>
-
-
-</div> <!-- id="content" -->
-</div> <!-- id="main" -->
-<div id="about">
-<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-01-04 10:27:07 </i>
-</div> <!-- id="about" -->
-</div> <!-- id="container" -->
-</body>
-</html>

docs/modules/components.html

@@ -26,8 +26,9 @@
 <br/>
 <h1>Concord</h1>
 
+
 <ul>
-  <li><a href="../index.html">Index</a></li>
+  <li><a href="../index.html">Getting Started</a></li>
 </ul>
 
 <h2>Contents</h2>
@@ -39,19 +40,30 @@
 <h2>Modules</h2>
 <ul class="nowrap">
   <li><strong>Components</strong></li>
-  <li><a href="../modules/Concord.html">Concord</a></li>
-  <li><a href="../modules/type.html">type</a></li>
-  <li><a href="../modules/utils.html">utils</a></li>
+  <li><a href="../modules/Type.html">Type</a></li>
+  <li><a href="../modules/Utils.html">Utils</a></li>
+</ul>
+<h2>Builtin Components</h2>
+<ul class="nowrap">
+  <li><a href="../builtins/key.html">key</a></li>
+  <li><a href="../builtins/serializable.html">serializable</a></li>
 </ul>
 <h2>Classes</h2>
 <ul class="nowrap">
   <li><a href="../classes/Component.html">Component</a></li>
   <li><a href="../classes/Entity.html">Entity</a></li>
+  <li><a href="../classes/Filter.html">Filter</a></li>
   <li><a href="../classes/List.html">List</a></li>
-  <li><a href="../classes/Pool.html">Pool</a></li>
   <li><a href="../classes/System.html">System</a></li>
   <li><a href="../classes/World.html">World</a></li>
 </ul>
+<h2>Guides</h2>
+<ul class="nowrap">
+  <li><a href="../index.html">Getting Started</a></li>
+  <li><a href="../guides/Why-ECS.md.html">Why ECS? Why Concord?</a></li>
+  <li><a href="../guides/Custom-Pools.md.html">Custom Pools</a></li>
+  <li><a href="../guides/Pool-Flushing-and-Timing.md.html">Pool Flushing and Timing</a></li>
+</ul>
 
 </div>
 
@@ -59,17 +71,23 @@
 
 <h1>Module <code>Components</code></h1>
 <p>Container for registered ComponentClasses</p>
-<p></p>
+<p>
+
+</p>
 
 
 <h2><a href="#Functions">Functions</a></h2>
 <table class="function_list">
 	<tr>
 	<td class="name" nowrap><a href="#has">has (name)</a></td>
-	<td class="summary">Returns true if the containter has the ComponentClass with the specified name</td>
+	<td class="summary">Returns true if the container has the ComponentClass with the specified name</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#try">try (name)</a></td>
+	<td class="name" nowrap><a href="#reject">reject (name)</a></td>
+	<td class="summary">Prefix a component's name with the currently set Reject Prefix</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#try">try (name[, acceptRejected])</a></td>
 	<td class="summary">Returns true and the ComponentClass if one was registered with the specified name
  or false and an error otherwise</td>
 	</tr>
@@ -91,13 +109,13 @@
     <strong>has (name)</strong>
     </dt>
     <dd>
-    Returns true if the containter has the ComponentClass with the specified name
+    Returns true if the container has the ComponentClass with the specified name
 
 
     <h3>Parameters:</h3>
     <ul>
         <li><span class="parameter">name</span>
-            <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
          Name of the ComponentClass to check
         </li>
     </ul>
@@ -107,6 +125,37 @@
 
            <span class="types"><span class="type">boolean</span></span>
 
+
+
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "reject"></a>
+    <strong>reject (name)</strong>
+    </dt>
+    <dd>
+    Prefix a component's name with the currently set Reject Prefix
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">name</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
+         Name of the ComponentClass to reject
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
+
+
+
     </ol>
 
 
@@ -115,7 +164,7 @@
 </dd>
     <dt>
     <a name = "try"></a>
-    <strong>try (name)</strong>
+    <strong>try (name[, acceptRejected])</strong>
     </dt>
     <dd>
     Returns true and the ComponentClass if one was registered with the specified name
@@ -125,19 +174,27 @@
     <h3>Parameters:</h3>
     <ul>
         <li><span class="parameter">name</span>
-            <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
          Name of the ComponentClass to check
         </li>
+        <li><span class="parameter">acceptRejected</span>
+            <span class="types"><span class="type">boolean</span></span>
+         Whether to accept names prefixed with the Reject Prefix.
+         (<em>optional</em>)
+        </li>
     </ul>
 
     <h3>Returns:</h3>
     <ol>
         <li>
            <span class="types"><span class="type">boolean</span></span>
-        </li>
+        ok</li>
         <li>
-           <span class="types"><a class="type" href="../classes/Component.html#">Component</a></span>
-        or error string</li>
+           <span class="types"><a class="type" href="../classes/Component.html#">Component</a> or <a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
+        ComponentClass on success, or an error string on failure</li>
+        <li>
+           <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a> or <span class="type">boolean</span></span>
+        On success: the stripped Component name if the name had the Reject Prefix, otherwise false</li>
     </ol>
 
 
@@ -155,7 +212,7 @@
     <h3>Parameters:</h3>
     <ul>
         <li><span class="parameter">name</span>
-            <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
          Name of the ComponentClass to get
         </li>
     </ul>
@@ -164,7 +221,7 @@
     <ol>
 
            <span class="types"><a class="type" href="../classes/Component.html#">Component</a></span>
-
+        The registered ComponentClass
     </ol>
 
 
@@ -172,13 +229,11 @@
 
 </dd>
 </dl>
-
-
 </div> <!-- id="content" -->
 </div> <!-- id="main" -->
 <div id="about">
-<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-08-18 15:20:32 </i>
+<i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
+<i style="float:right;">Last updated 2026-09-06 21:32:30 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/modules/systems.html

@@ -1,181 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html>
-<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
-<head>
-    <title>Reference</title>
-    <link rel="stylesheet" href="../ldoc.css" type="text/css" />
-</head>
-<body>
-
-<div id="container">
-
-<div id="product">
-	<div id="product_logo"></div>
-	<div id="product_name"><big><b></b></big></div>
-	<div id="product_description"></div>
-</div> <!-- id="product" -->
-
-
-<div id="main">
-
-
-<!-- Menu -->
-
-<div id="navigation">
-<br/>
-<h1>Concord</h1>
-
-<ul>
-  <li><a href="../index.html">Index</a></li>
-</ul>
-
-<h2>Contents</h2>
-<ul>
-<li><a href="#Functions">Functions</a></li>
-</ul>
-
-
-<h2>Modules</h2>
-<ul class="nowrap">
-  <li><a href="../modules/Assemblages.html">Assemblages</a></li>
-  <li><a href="../modules/Components.html">Components</a></li>
-  <li><a href="../modules/Concord.html">Concord</a></li>
-  <li><strong>Systems</strong></li>
-  <li><a href="../modules/type.html">type</a></li>
-  <li><a href="../modules/utils.html">utils</a></li>
-  <li><a href="../modules/worlds.html">worlds</a></li>
-</ul>
-<h2>Classes</h2>
-<ul class="nowrap">
-  <li><a href="../classes/Assemblage.html">Assemblage</a></li>
-  <li><a href="../classes/Component.html">Component</a></li>
-  <li><a href="../classes/Entity.html">Entity</a></li>
-  <li><a href="../classes/List.html">List</a></li>
-  <li><a href="../classes/Pool.html">Pool</a></li>
-  <li><a href="../classes/System.html">System</a></li>
-  <li><a href="../classes/World.html">World</a></li>
-</ul>
-
-</div>
-
-<div id="content">
-
-<h1>Module <code>Systems</code></h1>
-<p>Container for registered SystemClasses</p>
-<p></p>
-
-
-<h2><a href="#Functions">Functions</a></h2>
-<table class="function_list">
-	<tr>
-	<td class="name" nowrap><a href="#register">register (name, systemClass)</a></td>
-	<td class="summary">Registers a SystemClass.</td>
-	</tr>
-	<tr>
-	<td class="name" nowrap><a href="#has">has (name)</a></td>
-	<td class="summary">Returns true if the containter has the SystemClass with the name</td>
-	</tr>
-	<tr>
-	<td class="name" nowrap><a href="#get">get (name)</a></td>
-	<td class="summary">Returns the SystemClass with the name</td>
-	</tr>
-</table>
-
-<br/>
-<br/>
-
-
-    <h2 class="section-header "><a name="Functions"></a>Functions</h2>
-
-    <dl class="function">
-    <dt>
-    <a name = "register"></a>
-    <strong>register (name, systemClass)</strong>
-    </dt>
-    <dd>
-    Registers a SystemClass.
-
-
-    <h3>Parameters:</h3>
-    <ul>
-        <li><span class="parameter">name</span>
-            <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
-         Name to register under
-        </li>
-        <li><span class="parameter">systemClass</span>
-            <span class="types"><a class="type" href="../classes/System.html#">System</a></span>
-         SystemClass to register
-        </li>
-    </ul>
-
-
-
-
-
-</dd>
-    <dt>
-    <a name = "has"></a>
-    <strong>has (name)</strong>
-    </dt>
-    <dd>
-    Returns true if the containter has the SystemClass with the name
-
-
-    <h3>Parameters:</h3>
-    <ul>
-        <li><span class="parameter">name</span>
-            <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
-         Name of the SystemClass to check
-        </li>
-    </ul>
-
-    <h3>Returns:</h3>
-    <ol>
-
-           <span class="types"><span class="type">boolean</span></span>
-
-    </ol>
-
-
-
-
-</dd>
-    <dt>
-    <a name = "get"></a>
-    <strong>get (name)</strong>
-    </dt>
-    <dd>
-    Returns the SystemClass with the name
-
-
-    <h3>Parameters:</h3>
-    <ul>
-        <li><span class="parameter">name</span>
-            <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
-         Name of the SystemClass to get
-        </li>
-    </ul>
-
-    <h3>Returns:</h3>
-    <ol>
-
-        SystemClass with the name
-    </ol>
-
-
-
-
-</dd>
-</dl>
-
-
-</div> <!-- id="content" -->
-</div> <!-- id="main" -->
-<div id="about">
-<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-01-04 10:27:07 </i>
-</div> <!-- id="about" -->
-</div> <!-- id="container" -->
-</body>
-</html>

docs/modules/type.html

@@ -26,8 +26,9 @@
 <br/>
 <h1>Concord</h1>
 
+
 <ul>
-  <li><a href="../index.html">Index</a></li>
+  <li><a href="../index.html">Getting Started</a></li>
 </ul>
 
 <h2>Contents</h2>
@@ -39,56 +40,76 @@
 <h2>Modules</h2>
 <ul class="nowrap">
   <li><a href="../modules/Components.html">Components</a></li>
-  <li><a href="../modules/Concord.html">Concord</a></li>
-  <li><strong>type</strong></li>
-  <li><a href="../modules/utils.html">utils</a></li>
+  <li><strong>Type</strong></li>
+  <li><a href="../modules/Utils.html">Utils</a></li>
+</ul>
+<h2>Builtin Components</h2>
+<ul class="nowrap">
+  <li><a href="../builtins/key.html">key</a></li>
+  <li><a href="../builtins/serializable.html">serializable</a></li>
 </ul>
 <h2>Classes</h2>
 <ul class="nowrap">
   <li><a href="../classes/Component.html">Component</a></li>
   <li><a href="../classes/Entity.html">Entity</a></li>
+  <li><a href="../classes/Filter.html">Filter</a></li>
   <li><a href="../classes/List.html">List</a></li>
-  <li><a href="../classes/Pool.html">Pool</a></li>
   <li><a href="../classes/System.html">System</a></li>
   <li><a href="../classes/World.html">World</a></li>
 </ul>
+<h2>Guides</h2>
+<ul class="nowrap">
+  <li><a href="../index.html">Getting Started</a></li>
+  <li><a href="../guides/Why-ECS.md.html">Why ECS? Why Concord?</a></li>
+  <li><a href="../guides/Custom-Pools.md.html">Custom Pools</a></li>
+  <li><a href="../guides/Pool-Flushing-and-Timing.md.html">Pool Flushing and Timing</a></li>
+</ul>
 
 </div>
 
 <div id="content">
 
-<h1>Module <code>type</code></h1>
-<p>Type
- Helper module to do easy type checking for Concord types</p>
-<p></p>
+<h1>Module <code>Type</code></h1>
+<p>Helper module to do easy type checking for Concord types</p>
+<p>
+
+</p>
 
 
 <h2><a href="#Functions">Functions</a></h2>
 <table class="function_list">
 	<tr>
-	<td class="name" nowrap><a href="#Type.isEntity">Type.isEntity (t)</a></td>
+	<td class="name" nowrap><a href="#isCallable">isCallable (t)</a></td>
+	<td class="summary">Returns true if the value is a function or has a __call metamethod.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#isEntity">isEntity (t)</a></td>
 	<td class="summary">Returns if object is an Entity.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#Type.isComponentClass">Type.isComponentClass (t)</a></td>
+	<td class="name" nowrap><a href="#isComponentClass">isComponentClass (t)</a></td>
 	<td class="summary">Returns if object is a ComponentClass.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#Type.isComponent">Type.isComponent (t)</a></td>
+	<td class="name" nowrap><a href="#isComponent">isComponent (t)</a></td>
 	<td class="summary">Returns if object is a Component.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#Type.isSystemClass">Type.isSystemClass (t)</a></td>
+	<td class="name" nowrap><a href="#isSystemClass">isSystemClass (t)</a></td>
 	<td class="summary">Returns if object is a SystemClass.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#Type.isSystem">Type.isSystem (t)</a></td>
+	<td class="name" nowrap><a href="#isSystem">isSystem (t)</a></td>
 	<td class="summary">Returns if object is a System.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#Type.isWorld">Type.isWorld (t)</a></td>
+	<td class="name" nowrap><a href="#isWorld">isWorld (t)</a></td>
 	<td class="summary">Returns if object is a World.</td>
 	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#isFilter">isFilter (t)</a></td>
+	<td class="summary">Returns if object is a Filter.</td>
+	</tr>
 </table>
 
 <br/>
@@ -99,8 +120,36 @@
 
     <dl class="function">
     <dt>
-    <a name = "Type.isEntity"></a>
-    <strong>Type.isEntity (t)</strong>
+    <a name = "isCallable"></a>
+    <strong>isCallable (t)</strong>
+    </dt>
+    <dd>
+    Returns true if the value is a function or has a __call metamethod.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">t</span>
+         Object to check
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><span class="type">boolean</span></span>
+
+
+
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "isEntity"></a>
+    <strong>isEntity (t)</strong>
     </dt>
     <dd>
     Returns if object is an Entity.
@@ -118,6 +167,8 @@
 
            <span class="types"><span class="type">boolean</span></span>
 
+
+
     </ol>
 
 
@@ -125,8 +176,8 @@
 
 </dd>
     <dt>
-    <a name = "Type.isComponentClass"></a>
-    <strong>Type.isComponentClass (t)</strong>
+    <a name = "isComponentClass"></a>
+    <strong>isComponentClass (t)</strong>
     </dt>
     <dd>
     Returns if object is a ComponentClass.
@@ -144,6 +195,8 @@
 
            <span class="types"><span class="type">boolean</span></span>
 
+
+
     </ol>
 
 
@@ -151,8 +204,8 @@
 
 </dd>
     <dt>
-    <a name = "Type.isComponent"></a>
-    <strong>Type.isComponent (t)</strong>
+    <a name = "isComponent"></a>
+    <strong>isComponent (t)</strong>
     </dt>
     <dd>
     Returns if object is a Component.
@@ -170,6 +223,8 @@
 
            <span class="types"><span class="type">boolean</span></span>
 
+
+
     </ol>
 
 
@@ -177,8 +232,8 @@
 
 </dd>
     <dt>
-    <a name = "Type.isSystemClass"></a>
-    <strong>Type.isSystemClass (t)</strong>
+    <a name = "isSystemClass"></a>
+    <strong>isSystemClass (t)</strong>
     </dt>
     <dd>
     Returns if object is a SystemClass.
@@ -196,6 +251,8 @@
 
            <span class="types"><span class="type">boolean</span></span>
 
+
+
     </ol>
 
 
@@ -203,8 +260,8 @@
 
 </dd>
     <dt>
-    <a name = "Type.isSystem"></a>
-    <strong>Type.isSystem (t)</strong>
+    <a name = "isSystem"></a>
+    <strong>isSystem (t)</strong>
     </dt>
     <dd>
     Returns if object is a System.
@@ -222,6 +279,8 @@
 
            <span class="types"><span class="type">boolean</span></span>
 
+
+
     </ol>
 
 
@@ -229,8 +288,8 @@
 
 </dd>
     <dt>
-    <a name = "Type.isWorld"></a>
-    <strong>Type.isWorld (t)</strong>
+    <a name = "isWorld"></a>
+    <strong>isWorld (t)</strong>
     </dt>
     <dd>
     Returns if object is a World.
@@ -248,6 +307,36 @@
 
            <span class="types"><span class="type">boolean</span></span>
 
+
+
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "isFilter"></a>
+    <strong>isFilter (t)</strong>
+    </dt>
+    <dd>
+    Returns if object is a Filter.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">t</span>
+         Object to check
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><span class="type">boolean</span></span>
+
+
+
     </ol>
 
 
@@ -255,13 +344,11 @@
 
 </dd>
 </dl>
-
-
 </div> <!-- id="content" -->
 </div> <!-- id="main" -->
 <div id="about">
-<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-08-18 15:20:32 </i>
+<i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
+<i style="float:right;">Last updated 2026-09-06 21:32:30 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/modules/utils.html

@@ -26,8 +26,9 @@
 <br/>
 <h1>Concord</h1>
 
+
 <ul>
-  <li><a href="../index.html">Index</a></li>
+  <li><a href="../index.html">Getting Started</a></li>
 </ul>
 
 <h2>Contents</h2>
@@ -39,39 +40,55 @@
 <h2>Modules</h2>
 <ul class="nowrap">
   <li><a href="../modules/Components.html">Components</a></li>
-  <li><a href="../modules/Concord.html">Concord</a></li>
-  <li><a href="../modules/type.html">type</a></li>
-  <li><strong>utils</strong></li>
+  <li><a href="../modules/Type.html">Type</a></li>
+  <li><strong>Utils</strong></li>
+</ul>
+<h2>Builtin Components</h2>
+<ul class="nowrap">
+  <li><a href="../builtins/key.html">key</a></li>
+  <li><a href="../builtins/serializable.html">serializable</a></li>
 </ul>
 <h2>Classes</h2>
 <ul class="nowrap">
   <li><a href="../classes/Component.html">Component</a></li>
   <li><a href="../classes/Entity.html">Entity</a></li>
+  <li><a href="../classes/Filter.html">Filter</a></li>
   <li><a href="../classes/List.html">List</a></li>
-  <li><a href="../classes/Pool.html">Pool</a></li>
   <li><a href="../classes/System.html">System</a></li>
   <li><a href="../classes/World.html">World</a></li>
 </ul>
+<h2>Guides</h2>
+<ul class="nowrap">
+  <li><a href="../index.html">Getting Started</a></li>
+  <li><a href="../guides/Why-ECS.md.html">Why ECS? Why Concord?</a></li>
+  <li><a href="../guides/Custom-Pools.md.html">Custom Pools</a></li>
+  <li><a href="../guides/Pool-Flushing-and-Timing.md.html">Pool Flushing and Timing</a></li>
+</ul>
 
 </div>
 
 <div id="content">
 
-<h1>Module <code>utils</code></h1>
-<p>Utils
- Helper module for misc operations</p>
-<p></p>
+<h1>Module <code>Utils</code></h1>
+<p>Helper module for misc operations</p>
+<p>
+
+</p>
 
 
 <h2><a href="#Functions">Functions</a></h2>
 <table class="function_list">
 	<tr>
-	<td class="name" nowrap><a href="#Utils.shallowCopy">Utils.shallowCopy (orig, target)</a></td>
-	<td class="summary">Does a shallow copy of a table and appends it to a target table.</td>
+	<td class="name" nowrap><a href="#error">error (level, str, ...)</a></td>
+	<td class="summary">Raises a formatted error.</td>
 	</tr>
 	<tr>
-	<td class="name" nowrap><a href="#Utils.loadNamespace">Utils.loadNamespace (pathOrFiles, namespace)</a></td>
-	<td class="summary">Requires files and puts them in a table.</td>
+	<td class="name" nowrap><a href="#shallowCopy">shallowCopy (orig, target)</a></td>
+	<td class="summary">Copies keys from orig into target.</td>
+	</tr>
+	<tr>
+	<td class="name" nowrap><a href="#loadNamespace">loadNamespace (pathOrFiles[, namespace])</a></td>
+	<td class="summary">Requires files and stores them in a namespace table.</td>
 	</tr>
 </table>
 
@@ -83,20 +100,25 @@
 
     <dl class="function">
     <dt>
-    <a name = "Utils.shallowCopy"></a>
-    <strong>Utils.shallowCopy (orig, target)</strong>
+    <a name = "error"></a>
+    <strong>error (level, str, ...)</strong>
     </dt>
     <dd>
-    Does a shallow copy of a table and appends it to a target table.
+    Raises a formatted error.
 
 
     <h3>Parameters:</h3>
     <ul>
-        <li><span class="parameter">orig</span>
-         Table to copy
+        <li><span class="parameter">level</span>
+            <span class="types"><span class="type">integer</span></span>
+         Error level passed to error(), plus one
         </li>
-        <li><span class="parameter">target</span>
-         Table to append to
+        <li><span class="parameter">str</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
+         Format string
+        </li>
+        <li><span class="parameter">...</span>
+         Format arguments
         </li>
     </ul>
 
@@ -106,29 +128,64 @@
 
 </dd>
     <dt>
-    <a name = "Utils.loadNamespace"></a>
-    <strong>Utils.loadNamespace (pathOrFiles, namespace)</strong>
+    <a name = "shallowCopy"></a>
+    <strong>shallowCopy (orig, target)</strong>
     </dt>
     <dd>
-    Requires files and puts them in a table.
- Accepts a table of paths to Lua files: {"path/to/file_1", "path/to/another/file_2", "etc"}
- Accepts a path to a directory with Lua files: "my_files/here"
+    Copies keys from orig into target.  Existing keys in target are overwritten.
 
 
     <h3>Parameters:</h3>
     <ul>
-        <li><span class="parameter">pathOrFiles</span>
-         The table of paths or a path to a directory.
+        <li><span class="parameter">orig</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span>
+         Table to copy from
         </li>
-        <li><span class="parameter">namespace</span>
-         A table that will hold the required files
+        <li><span class="parameter">target</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span>
+         Table to copy into
         </li>
     </ul>
 
     <h3>Returns:</h3>
     <ol>
 
-           <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
+           <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span>
+        target
+    </ol>
+
+
+
+
+</dd>
+    <dt>
+    <a name = "loadNamespace"></a>
+    <strong>loadNamespace (pathOrFiles[, namespace])</strong>
+    </dt>
+    <dd>
+    Requires files and stores them in a namespace table.
+ Accepts a table of require paths: {"path/to/file<em>1", "path/to/another/file</em>2", "etc"}
+ Accepts a path to a directory of Lua files: "my_files/here"
+ Directory loading uses love.filesystem and requires LÖVE.
+ If namespace is omitted, files are still required and this function returns nil.
+
+
+    <h3>Parameters:</h3>
+    <ul>
+        <li><span class="parameter">pathOrFiles</span>
+         A directory path or a table of require paths
+        </li>
+        <li><span class="parameter">namespace</span>
+            <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span>
+         Table that will hold the required files
+         (<em>optional</em>)
+        </li>
+    </ul>
+
+    <h3>Returns:</h3>
+    <ol>
+
+           <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a> or <span class="type">nil</span></span>
         The namespace table
     </ol>
 
@@ -137,13 +194,11 @@
 
 </dd>
 </dl>
-
-
 </div> <!-- id="content" -->
 </div> <!-- id="main" -->
 <div id="about">
-<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-08-18 15:20:32 </i>
+<i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
+<i style="float:right;">Last updated 2026-09-06 21:32:30 </i>
 </div> <!-- id="about" -->
 </div> <!-- id="container" -->
 </body>

docs/modules/worlds.html

@@ -1,181 +0,0 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html>
-<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
-<head>
-    <title>Reference</title>
-    <link rel="stylesheet" href="../ldoc.css" type="text/css" />
-</head>
-<body>
-
-<div id="container">
-
-<div id="product">
-	<div id="product_logo"></div>
-	<div id="product_name"><big><b></b></big></div>
-	<div id="product_description"></div>
-</div> <!-- id="product" -->
-
-
-<div id="main">
-
-
-<!-- Menu -->
-
-<div id="navigation">
-<br/>
-<h1>Concord</h1>
-
-<ul>
-  <li><a href="../index.html">Index</a></li>
-</ul>
-
-<h2>Contents</h2>
-<ul>
-<li><a href="#Functions">Functions</a></li>
-</ul>
-
-
-<h2>Modules</h2>
-<ul class="nowrap">
-  <li><a href="../modules/Assemblages.html">Assemblages</a></li>
-  <li><a href="../modules/Components.html">Components</a></li>
-  <li><a href="../modules/Concord.html">Concord</a></li>
-  <li><a href="../modules/Systems.html">Systems</a></li>
-  <li><a href="../modules/type.html">type</a></li>
-  <li><a href="../modules/utils.html">utils</a></li>
-  <li><strong>worlds</strong></li>
-</ul>
-<h2>Classes</h2>
-<ul class="nowrap">
-  <li><a href="../classes/Assemblage.html">Assemblage</a></li>
-  <li><a href="../classes/Component.html">Component</a></li>
-  <li><a href="../classes/Entity.html">Entity</a></li>
-  <li><a href="../classes/List.html">List</a></li>
-  <li><a href="../classes/Pool.html">Pool</a></li>
-  <li><a href="../classes/System.html">System</a></li>
-  <li><a href="../classes/World.html">World</a></li>
-</ul>
-
-</div>
-
-<div id="content">
-
-<h1>Module <code>worlds</code></h1>
-<p>Worlds
- Container for registered Worlds</p>
-<p></p>
-
-
-<h2><a href="#Functions">Functions</a></h2>
-<table class="function_list">
-	<tr>
-	<td class="name" nowrap><a href="#Worlds.register">Worlds.register (name, world)</a></td>
-	<td class="summary">Registers a World.</td>
-	</tr>
-	<tr>
-	<td class="name" nowrap><a href="#Worlds.has">Worlds.has (name)</a></td>
-	<td class="summary">Returns true if the containter has the World with the name</td>
-	</tr>
-	<tr>
-	<td class="name" nowrap><a href="#Worlds.get">Worlds.get (name)</a></td>
-	<td class="summary">Returns the World with the name</td>
-	</tr>
-</table>
-
-<br/>
-<br/>
-
-
-    <h2 class="section-header "><a name="Functions"></a>Functions</h2>
-
-    <dl class="function">
-    <dt>
-    <a name = "Worlds.register"></a>
-    <strong>Worlds.register (name, world)</strong>
-    </dt>
-    <dd>
-    Registers a World.
-
-
-    <h3>Parameters:</h3>
-    <ul>
-        <li><span class="parameter">name</span>
-            <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
-         Name to register under
-        </li>
-        <li><span class="parameter">world</span>
-         World to register
-        </li>
-    </ul>
-
-
-
-
-
-</dd>
-    <dt>
-    <a name = "Worlds.has"></a>
-    <strong>Worlds.has (name)</strong>
-    </dt>
-    <dd>
-    Returns true if the containter has the World with the name
-
-
-    <h3>Parameters:</h3>
-    <ul>
-        <li><span class="parameter">name</span>
-            <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
-         Name of the World to check
-        </li>
-    </ul>
-
-    <h3>Returns:</h3>
-    <ol>
-
-           <span class="types"><span class="type">boolean</span></span>
-
-    </ol>
-
-
-
-
-</dd>
-    <dt>
-    <a name = "Worlds.get"></a>
-    <strong>Worlds.get (name)</strong>
-    </dt>
-    <dd>
-    Returns the World with the name
-
-
-    <h3>Parameters:</h3>
-    <ul>
-        <li><span class="parameter">name</span>
-            <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span>
-         Name of the World to get
-        </li>
-    </ul>
-
-    <h3>Returns:</h3>
-    <ol>
-
-        World with the name
-    </ol>
-
-
-
-
-</dd>
-</dl>
-
-
-</div> <!-- id="content" -->
-</div> <!-- id="main" -->
-<div id="about">
-<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i>
-<i style="float:right;">Last updated 2020-01-04 10:27:07 </i>
-</div> <!-- id="about" -->
-</div> <!-- id="container" -->
-</body>
-</html>

guides/Get-Started.md

@@ -1,10 +1,10 @@
-# Concord
+# Getting Started
 
 Concord is a feature complete library that allows you to use Entity - Component - System (ECS) model  to write and organize your Lua code.
 
 Concord puts a lot of effort on being easy to use and provide a great developer experience, while trying to be competitive in performance with alternative libraries.
 
-## Getting Started
+## Installation
 
 As a first step you will need to download this repository and add the `concord` folder to your project.
 

ldoc.css

@@ -0,0 +1,357 @@
+/* BEGIN RESET
+
+Copyright (c) 2010, Yahoo! Inc. All rights reserved.
+Code licensed under the BSD License:
+http://developer.yahoo.com/yui/license.html
+version: 2.8.2r1
+*/
+html {
+    color: #000;
+    background: #FFF;
+}
+body,div,dl,dt,dd,ul,ol,li,h1,h2,h3,h4,h5,h6,pre,code,form,fieldset,legend,input,button,textarea,p,blockquote,th,td {
+    margin: 0;
+    padding: 0;
+}
+table {
+    border-collapse: collapse;
+    border-spacing: 0;
+}
+fieldset,img {
+    border: 0;
+}
+address,caption,cite,code,dfn,em,strong,th,var,optgroup {
+    font-style: inherit;
+    font-weight: inherit;
+}
+del,ins {
+    text-decoration: none;
+}
+li {
+    margin-left: 20px;
+}
+caption,th {
+    text-align: left;
+}
+h1,h2,h3,h4,h5,h6 {
+    font-size: 100%;
+    font-weight: bold;
+}
+q:before,q:after {
+    content: '';
+}
+abbr,acronym {
+    border: 0;
+    font-variant: normal;
+}
+sup {
+    vertical-align: baseline;
+}
+sub {
+    vertical-align: baseline;
+}
+legend {
+    color: #000;
+}
+input,button,textarea,select,optgroup,option {
+    font-family: inherit;
+    font-size: inherit;
+    font-style: inherit;
+    font-weight: inherit;
+}
+input,button,textarea,select {*font-size:100%;
+}
+/* END RESET */
+
+body {
+    margin-left: 1em;
+    margin-right: 1em;
+    font-family: arial, helvetica, geneva, sans-serif;
+    background-color: #ffffff; margin: 0px;
+}
+
+code, tt { font-family: monospace; font-size: 1.1em; }
+span.parameter { font-family:monospace; }
+span.parameter:after { content:":"; }
+span.types:before { content:"("; }
+span.types:after { content:")"; }
+.type { font-weight: bold; font-style:italic }
+
+body, p, td, th { font-size: .95em; line-height: 1.2em;}
+
+p, ul { margin: 10px 0 0 0px;}
+
+strong { font-weight: bold;}
+
+em { font-style: italic;}
+
+h1 {
+    font-size: 1.5em;
+    margin: 20px 0 20px 0;
+}
+h2, h3, h4 { margin: 15px 0 10px 0; }
+h2 { font-size: 1.25em; }
+h3 { font-size: 1.15em; }
+h4 { font-size: 1.06em; }
+
+a:link { font-weight: bold; color: #004080; text-decoration: none; }
+a:visited { font-weight: bold; color: #006699; text-decoration: none; }
+a:link:hover { text-decoration: underline; }
+
+hr {
+    color:#cccccc;
+    background: #00007f;
+    height: 1px;
+}
+
+blockquote { margin-left: 3em; }
+
+ul { list-style-type: disc; }
+
+p.name {
+    font-family: "Andale Mono", monospace;
+    padding-top: 1em;
+}
+
+pre {
+    background-color: rgb(245, 245, 245);
+    border: 1px solid #C0C0C0; /* silver */
+    padding: 10px;
+    margin: 10px 0 10px 0;
+    overflow: auto;
+    font-family: "Andale Mono", monospace;
+}
+
+pre.example {
+    font-size: .85em;
+}
+
+table.index { border: 1px #00007f; }
+table.index td { text-align: left; vertical-align: top; }
+
+#container {
+    margin-left: 1em;
+    margin-right: 1em;
+    background-color: #f0f0f0;
+}
+
+#product {
+    text-align: center;
+    border-bottom: 1px solid #cccccc;
+    background-color: #ffffff;
+}
+
+#product big {
+    font-size: 2em;
+}
+
+#main {
+    background-color: #f0f0f0;
+    border-left: 2px solid #cccccc;
+}
+
+#navigation {
+    float: left;
+    width: 14em;
+    vertical-align: top;
+    background-color: #f0f0f0;
+    overflow: visible;
+}
+
+#navigation h2 {
+    background-color:#e7e7e7;
+    font-size:1.1em;
+    color:#000000;
+    text-align: left;
+    padding:0.2em;
+    border-top:1px solid #dddddd;
+    border-bottom:1px solid #dddddd;
+}
+
+#navigation ul
+{
+    font-size:1em;
+    list-style-type: none;
+    margin: 1px 1px 10px 1px;
+}
+
+#navigation li {
+    text-indent: -1em;
+    display: block;
+    margin: 3px 0px 0px 22px;
+}
+
+#navigation li li a {
+    margin: 0px 3px 0px -1em;
+}
+
+#content {
+    margin-left: 14em;
+    padding: 1em;
+    width: 700px;
+    border-left: 2px solid #cccccc;
+    border-right: 2px solid #cccccc;
+    background-color: #ffffff;
+}
+
+#about {
+    clear: both;
+    padding: 5px;
+    border-top: 2px solid #cccccc;
+    background-color: #ffffff;
+}
+
+@media print {
+    body {
+        font: 12pt "Times New Roman", "TimeNR", Times, serif;
+    }
+    a { font-weight: bold; color: #004080; text-decoration: underline; }
+
+    #main {
+        background-color: #ffffff;
+        border-left: 0px;
+    }
+
+    #container {
+        margin-left: 2%;
+        margin-right: 2%;
+        background-color: #ffffff;
+    }
+
+    #content {
+        padding: 1em;
+        background-color: #ffffff;
+    }
+
+    #navigation {
+        display: none;
+    }
+    pre.example {
+        font-family: "Andale Mono", monospace;
+        font-size: 10pt;
+        page-break-inside: avoid;
+    }
+}
+
+table.module_list {
+    border-width: 1px;
+    border-style: solid;
+    border-color: #cccccc;
+    border-collapse: collapse;
+}
+table.module_list td {
+    border-width: 1px;
+    padding: 3px;
+    border-style: solid;
+    border-color: #cccccc;
+}
+table.module_list td.name { background-color: #f0f0f0; min-width: 200px; }
+table.module_list td.summary { width: 100%; }
+
+
+table.function_list {
+    border-width: 1px;
+    border-style: solid;
+    border-color: #cccccc;
+    border-collapse: collapse;
+}
+table.function_list td {
+    border-width: 1px;
+    padding: 3px;
+    border-style: solid;
+    border-color: #cccccc;
+}
+table.function_list td.name { background-color: #f0f0f0; min-width: 200px; }
+table.function_list td.summary { width: 100%; }
+
+ul.nowrap {
+    overflow:auto;
+    white-space:nowrap;
+}
+
+dl.table dt, dl.function dt {border-top: 1px solid #ccc; padding-top: 1em;}
+dl.table dd, dl.function dd {padding-bottom: 1em; margin: 10px 0 0 20px;}
+dl.table h3, dl.function h3 {font-size: .95em;}
+
+/* stop sublists from having initial vertical space */
+ul ul { margin-top: 0px; }
+ol ul { margin-top: 0px; }
+ol ol { margin-top: 0px; }
+ul ol { margin-top: 0px; }
+
+/* make the target distinct; helps when we're navigating to a function */
+a:target + * {
+  background-color: #FF9;
+}
+
+
+/* styles for prettification of source */
+pre .comment { color: #558817; }
+pre .constant { color: #a8660d; }
+pre .escape { color: #844631; }
+pre .keyword { color: #aa5050; font-weight: bold; }
+pre .library { color: #0e7c6b; }
+pre .marker { color: #512b1e; background: #fedc56; font-weight: bold; }
+pre .string { color: #8080ff; }
+pre .number { color: #f8660d; }
+pre .function-name { color: #60447f; }
+pre .operator { color: #2239a8; font-weight: bold; }
+pre .preprocessor, pre .prepro { color: #a33243; }
+pre .global { color: #800080; }
+pre .user-keyword { color: #800080; }
+pre .prompt { color: #558817; }
+pre .url { color: #272fc2; text-decoration: underline; }
+
+
+/* Guide callouts and details */
+
+aside.callout {
+    margin: 1em 0;
+    padding: 0.75em 1em;
+    border-radius: 4px;
+    border-left: 4px solid #0969da;
+    background: #e7f1fb;
+}
+
+aside.callout-note { border-left-color: #0969da; background: #e7f1fb; }
+aside.callout-tip { border-left-color: #1a7f37; background: #e6f6eb; }
+aside.callout-important { border-left-color: #8250df; background: #f1e9fb; }
+aside.callout-warning { border-left-color: #9a6700; background: #fff4d1; }
+aside.callout-caution { border-left-color: #cf222e; background: #ffe8ea; }
+
+aside.callout::before {
+    display: block;
+    font-weight: bold;
+    margin-bottom: 0.35em;
+}
+
+aside.callout-note::before { content: "Note"; }
+aside.callout-tip::before { content: "Tip"; }
+aside.callout-important::before { content: "Important"; }
+aside.callout-warning::before { content: "Warning"; }
+aside.callout-caution::before { content: "Caution"; }
+
+aside.callout p {
+    margin: 0.4em 0 0 0;
+}
+
+aside.callout p:first-child {
+    margin-top: 0;
+}
+
+details {
+    margin: 1em 0;
+    padding: 0.75em 1em;
+    background: #f7f7f7;
+    border: 1px solid #c0c0c0;
+    border-radius: 4px;
+}
+
+details summary {
+    cursor: pointer;
+    font-weight: bold;
+}
+
+details[open] summary {
+    margin-bottom: 0.6em;
+}

scripts/build-docs.lua

@@ -0,0 +1,318 @@
+-- Build LDoc docs with Markdown preprocess and HTML postprocess.
+-- Usage: lua scripts/build-docs.lua
+
+local function split_lines(text)
+   text = text:gsub("\r\n", "\n"):gsub("\r", "\n")
+   if text:sub(-1) ~= "\n" then
+      text = text .. "\n"
+   end
+   local lines = {}
+   for line in text:gmatch("(.-)\n") do
+      lines[#lines + 1] = line
+   end
+   return lines
+end
+
+local function join_lines(lines)
+   return table.concat(lines, "\n") .. "\n"
+end
+
+-- Strip one Markdown blockquote level inside <details>, so LDoc sees
+-- fenced code at column 0 and can emit highlighted <pre> blocks.
+local function unquote_details(text)
+   return text:gsub("(<details[^>]*>)([%s%S]-)(</details>)", function(open, body, close)
+      local lines = split_lines(body)
+      for i, line in ipairs(lines) do
+         lines[i] = line:match("^>%s?(.*)$") or line
+      end
+      return open .. join_lines(lines) .. close
+   end)
+end
+
+-- Turn GitHub-style callouts into HTML asides LDoc will pass through.
+--   > [!NOTE]
+--   > body
+local function convert_callouts(text)
+   local lines = split_lines(text)
+   local out = {}
+   local i = 1
+   while i <= #lines do
+      local kind, rest = lines[i]:match("^>%s*%[!(%u+)%]%s*(.*)$")
+      if kind then
+         local body = {}
+         if rest ~= "" then
+            body[#body + 1] = rest
+         end
+         i = i + 1
+         while i <= #lines do
+            local quoted = lines[i]:match("^>%s?(.*)$")
+            if quoted == nil then
+               break
+            end
+            body[#body + 1] = quoted
+            i = i + 1
+         end
+         local class = kind:lower()
+         out[#out + 1] = ('<aside class="callout callout-%s">'):format(class)
+         out[#out + 1] = ""
+         for _, line in ipairs(body) do
+            out[#out + 1] = line
+         end
+         out[#out + 1] = ""
+         out[#out + 1] = "</aside>"
+      else
+         out[#out + 1] = lines[i]
+         i = i + 1
+      end
+   end
+   return join_lines(out)
+end
+
+local function preprocess(text)
+   return convert_callouts(unquote_details(text))
+end
+
+-- LDoc puts the current kind first in the sidebar; keep a stable order.
+local SIDEBAR_KINDS = { "Modules", "Classes", "Builtins", "Topics", "Guides" }
+local SIDEBAR_LABELS = { Builtins = "Builtin Components", Topics = "Guides" }
+
+local function strip_getting_started(list)
+   list = list:gsub('<li><a href="[^"]+">Getting Started</a></li>%s*', "")
+   list = list:gsub('<li><strong>Getting Started</strong></li>%s*', "")
+   return list
+end
+
+local function reorder_sidebar(html)
+   return (html:gsub('<div id="navigation">([%s%S]-)</div>', function(nav)
+      local blocks = {}
+      for _, title in ipairs(SIDEBAR_KINDS) do
+         nav = nav:gsub('<h2>' .. title .. '</h2>%s*(<ul[%s%S]-</ul>)', function(list)
+            if title == "Topics" or title == "Guides" then
+               list = strip_getting_started(list)
+            end
+            blocks[title] = '<h2>' .. (SIDEBAR_LABELS[title] or title) .. '</h2>\n' .. list
+            return ""
+         end, 1)
+      end
+      local trimmed = nav:gsub("%s+$", "")
+      local parts = { trimmed }
+      for _, title in ipairs(SIDEBAR_KINDS) do
+         if blocks[title] then
+            parts[#parts + 1] = ""
+            parts[#parts + 1] = blocks[title]
+         end
+      end
+      parts[#parts + 1] = ""
+      return '<div id="navigation">' .. table.concat(parts, "\n") .. '</div>'
+   end, 1))
+end
+
+local HOME = "Getting Started"
+local HOME_TOPIC = "Get-Started.md.html"
+
+local function replace_home_link(html, path)
+   local item
+   if path:match("index%.html$") then
+      item = "<strong>" .. HOME .. "</strong>"
+   else
+      item = '<a href="../index.html">' .. HOME .. "</a>"
+   end
+   local home = "<ul>\n  <li>" .. item .. "</li>\n</ul>"
+   local replaced, n = html:gsub(
+      '<ul>%s*<li><a href="[^"]*index%.html">Index</a></li>%s*</ul>',
+      home,
+      1
+   )
+   if n == 0 then
+      replaced = html:gsub("(<h1>Concord</h1>)", "%1\n\n" .. home, 1)
+   end
+   return replaced
+end
+
+-- Getting Started lives at index.html; keep old topic URLs working.
+local function point_getting_started_at_index(html)
+   html = html:gsub('href="Get%-Started%.md%.html"', 'href="../index.html"')
+   html = html:gsub('href="%.%./guides/Get%-Started%.md%.html"', 'href="../index.html"')
+   html = html:gsub('href="%.%./topics/Get%-Started%.md%.html"', 'href="../index.html"')
+   html = html:gsub('href="guides/Get%-Started%.md%.html"', 'href="index.html"')
+   html = html:gsub('href="topics/Get%-Started%.md%.html"', 'href="index.html"')
+   return html
+end
+
+local function topic_home_to_index(html)
+   html = html:gsub('href="%.%./', 'href="')
+   html = html:gsub(
+      '<ul>%s*<li><a href="index%.html">' .. HOME .. "</a></li>%s*</ul>",
+      "<ul>\n  <li><strong>" .. HOME .. "</strong></li>\n</ul>",
+      1
+   )
+   return html
+end
+
+local HOME_REDIRECT = [[<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8"/>
+  <meta http-equiv="refresh" content="0; url=../index.html"/>
+  <link rel="canonical" href="../index.html"/>
+  <title>Getting Started</title>
+</head>
+<body>
+  <p><a href="../index.html">Getting Started</a></p>
+</body>
+</html>
+]]
+
+-- The index table uses topic filenames; the sidebar already has Markdown titles.
+local function retitle_index_topics(html)
+   local nav = html:match('<div id="navigation">([%s%S]-)</div>')
+   if not nav then
+      return html
+   end
+   local list = nav:match('<h2>Guides</h2>%s*<ul[^>]*>([%s%S]-)</ul>')
+      or nav:match('<h2>Topics</h2>%s*<ul[^>]*>([%s%S]-)</ul>')
+   if not list then
+      return html
+   end
+   local titles = {}
+   for href, title in list:gmatch('<a href="([^"]+)">([^<]+)</a>') do
+      titles[href] = title
+   end
+   return (html:gsub(
+      '<td class="name"%s+nowrap><a href="((?:guides|topics)/[^"]+)">([^<]+)</a></td>',
+      function(href, name)
+         return ('<td class="name"  nowrap><a href="%s">%s</a></td>'):format(
+            href,
+            titles[href] or name
+         )
+      end
+   ))
+end
+
+local INDEX_KINDS = { "Modules", "Classes", "Builtin Components", "Guides" }
+
+local function reorder_index_sections(html)
+   return (html:gsub('<div id="content">([%s%S]-)</div> <!%-%- id="content" %-%->', function(content)
+      local blocks = {}
+      for _, title in ipairs(INDEX_KINDS) do
+         content = content:gsub(
+            '<h2>' .. title .. '</h2>%s*(<table class="module_list">[%s%S]-</table>)',
+            function(table_html)
+               blocks[title] = '<h2>' .. title .. '</h2>\n' .. table_html
+               return ""
+            end,
+            1
+         )
+      end
+      local trimmed = content:gsub("%s+$", "")
+      local parts = { trimmed }
+      for _, title in ipairs(INDEX_KINDS) do
+         if blocks[title] then
+            parts[#parts + 1] = ""
+            parts[#parts + 1] = blocks[title]
+         end
+      end
+      parts[#parts + 1] = ""
+      return '<div id="content">' .. table.concat(parts, "\n") .. '</div> <!-- id="content" -->'
+   end, 1))
+end
+
+-- Markdown wraps some block-level HTML in <p>; unwrap those.
+local function postprocess(html, path)
+   html = html:gsub('<p>%s*(<aside[^>]*>)%s*</p>', '%1')
+   html = html:gsub('(<aside[^>]*>)%s*</p>', '%1')
+   html = html:gsub('<p>%s*(</aside>)%s*</p>', '%1')
+   html = html:gsub('<p>%s*(</aside>)', '%1')
+   html = html:gsub('(</aside>)%s*</p>', '%1')
+   html = html:gsub('<p>%s*(<details[%s%S]-</summary>)%s*</p>', '%1')
+   html = html:gsub('<p>%s*(</details>)%s*</p>', '%1')
+   -- Leftover callouts if a page was built without preprocess
+   html = html:gsub(
+      '<blockquote>%s*<p>%[!(%u+)%]%s*([%s%S]-)</p>%s*</blockquote>',
+      function(kind, body)
+         return ('<aside class="callout callout-%s"><p>%s</p></aside>'):format(
+            kind:lower(),
+            body
+         )
+      end
+   )
+   html = html:gsub('%s*<link rel="stylesheet" href="[^"]*ldoc%-custom%.css"[^>]*>', "")
+   html = retitle_index_topics(html)
+   html = html:gsub('<h2>Builtins</h2>', '<h2>Builtin Components</h2>')
+   html = html:gsub('<h2>Topics</h2>', '<h2>Guides</h2>')
+   html = html:gsub(
+      '<tr>%s*<td class="name"%s+nowrap><a href="[^"]+">Getting Started</a></td>%s*<td class="summary">[^<]*</td>%s*</tr>%s*',
+      ""
+   )
+   html = reorder_index_sections(html)
+   html = replace_home_link(html, path)
+   if path:sub(-#HOME_TOPIC) ~= HOME_TOPIC then
+      -- Keep the topic page's current-item markup so it can become index.html.
+      html = point_getting_started_at_index(html)
+   end
+   return html
+end
+
+local function read_file(path)
+   local f, err = io.open(path, "r")
+   if not f then
+      error("cannot read " .. path .. ": " .. tostring(err))
+   end
+   local text = f:read("*a")
+   f:close()
+   return text
+end
+
+local function write_file(path, text)
+   local f, err = io.open(path, "w")
+   if not f then
+      error("cannot write " .. path .. ": " .. tostring(err))
+   end
+   f:write(text)
+   f:close()
+end
+
+local function run(cmd)
+   local ok, why, code = os.execute(cmd)
+   if not ok then
+      error(cmd .. " failed (" .. tostring(why) .. " " .. tostring(code) .. ")")
+   end
+end
+
+local function list_html(dir)
+   local files = {}
+   local pipe = io.popen('find "' .. dir .. '" -name "*.html"')
+   for line in pipe:lines() do
+      files[#files + 1] = line
+   end
+   pipe:close()
+   return files
+end
+
+local root = arg[0]:match("^(.*)/scripts/build%-docs%.lua$") or "."
+if root == "" then
+   root = "."
+end
+
+run('mkdir -p "' .. root .. '/.ldoc-guides"')
+
+local pipe = io.popen('ls -1 "' .. root .. '/guides/"*.md')
+for path in pipe:lines() do
+   local name = path:match("([^/]+)$")
+   write_file(root .. "/.ldoc-guides/" .. name, preprocess(read_file(path)))
+end
+pipe:close()
+
+run('rm -rf "' .. root .. '/docs"')
+run('mkdir "' .. root .. '/docs"')
+run('cd "' .. root .. '" && ldoc --fatalwarnings .')
+
+for _, path in ipairs(list_html(root .. "/docs")) do
+   write_file(path, postprocess(read_file(path), path))
+end
+
+local topic_home = root .. "/docs/guides/" .. HOME_TOPIC
+write_file(root .. "/docs/index.html", topic_home_to_index(read_file(topic_home)))
+write_file(topic_home, HOME_REDIRECT)
+
+print("docs built in " .. root .. "/docs")