A Filter is a function that selects which Entities apply to a System. Filters take two parameters, the System and the Entity, and return a boolean - value indicating if the Entity should be processed by the System.
+ value indicating if the Entity should be processed by the System. A truthy + value includes the entity, while a falsey (nil or false) value excludes the + entity.Filters must be added to Systems by setting the filter field of the System. Filter's returned by tiny-ecs's Filter functions are immutable and can be @@ -292,12 +290,12 @@ filter = tiny.requireAll("image", tiny.rejectAny("Player", "Enemy"))
Examples are best:
-'a|b|c' - Matches entities with an 'a' component OR a 'b' component or a 'c' component.
-'a&!b&c' - Matches entities with an 'a' component AND NOT a 'b' component AND a 'c' component.
+'a|b|c' - Matches entities with an 'a' OR 'b' OR 'c'.
+'a&!b&c' - Matches entities with an 'a' AND NOT 'b' AND 'c'.
'a|(b&c&d)|e - Matches 'a' OR ('b' AND 'c' AND 'd') OR 'e'
@@ -313,9 +311,7 @@ filter = tiny.requireAll("image", tiny.rejectAny("Player", "Enemy"))
System functions
-
-
- A System is a wrapper around function callbacks for manipulating Entities.
+ A System is a wrapper around function callbacks for manipulating Entities.
Systems are implemented as tables that contain at least one method;
an update function that takes parameters like so:
@@ -339,12 +335,25 @@ filter = tiny.requireAll("image", tiny.rejectAny("Player", "Enemy"))
to the World, before any entities are added to the system.
function system:onRemoveFromWorld(world) - Called when the System is
removed from the world, after all Entities are removed from the System.function system:preWrap(dt) - Called on each system before update is
+ called on any system.function system:postWrap(dt) - Called on each system in reverse order
+ after update is called on each system. The idea behind preWrap and
+ postWrap is to allow for systems that modify the behavior of other systems.
+ Say there is a DrawingSystem, which draws sprites to the screen, and a
+ PostProcessingSystem, that adds some blur and bloom effects. In the preWrap
+ method of the PostProcessingSystem, the System could set the drawing target
+ for the DrawingSystem to a special buffer instead the screen. In the postWrap
+ method, the PostProcessingSystem could then modify the buffer and render it
+ to the screen. In this setup, the PostProcessingSystem would be added to the
+ World after the drawingSystem (A similar but less flexible behavior could
+ be accomplished with a single custom update function in the DrawingSystem). For Filters, it is convenient to use tiny.requireAll or tiny.requireAny,
+
For Filters, it is convenient to use tiny.requireAll or tiny.requireAny,
but one can write their own filters as well. Set the Filter of a System like
so:
-system.filter = tiny.requireAll("a", "b", "c")
+system.filter = tiny.requireAll("a", "b", "c")
or
function system:filter(entity)
@@ -357,29 +366,35 @@ end
commonly used.
- - The world field points to the World that the System belongs to. Useful
+
- The
world field points to the World that the System belongs to. Useful
for adding and removing Entities from the world dynamically via the System.
- The active flag is whether or not the System is updated automatically.
+ The active flag is whether or not the System is updated automatically.
Inactive Systems should be updated manually or not at all via
- system:update(dt). Defaults to true.
- The entities field is an ordered list of Entities in the System. This
+ system:update(dt). Defaults to true.
+ The entities field is an ordered list of Entities in the System. This
list can be used to quickly iterate through all Entities in a System.
- The interval field is an optional field that makes Systems update at
+ The interval field is an optional field that makes Systems update at
certain intervals using buffered time, regardless of World update frequency.
- For example, to make a System update once a second, set the System's interval
+ For example, to make a System update once a second, set the System's interval
to 1.
- The index field is the System's index in the World. Lower indexed
- Systems are processed before higher indices. The index is a read only
- field; to set the index, use tiny.setSystemIndex(world, system).
- The indices field is a table of Entity keys to their indices in the
- entities list. Most Systems can ignore this.
- The modified flag is an indicator if the System has been modified in
- the last update. If so, the onModify callback will be called on the System
+ The index field is the System's index in the World. Lower indexed
+ Systems are processed before higher indices. The index is a read only
+ field; to set the index, use tiny.setSystemIndex(world, system).
+ The indices field is a table of Entity keys to their indices in the
+ entities list. Most Systems can ignore this.
+ The modified flag is an indicator if the System has been modified in
+ the last update. If so, the onModify callback will be called on the System
in the next update, if it has one. This is usually managed by tiny-ecs, so
users should mostly ignore this, too.
-
+ There is another option to (hopefully) increase performance in systems that
+ have items added to or removed from them often, and have lots of entities in
+ them. Setting the
nocache' field of the system might improve performance.
+ It is still experimental. There are some restriction to systems without
+ caching, however. * There is no entities table. * Callbacks such onAdd,
+ onRemove, and onModify will never be called * Noncached systems cannot be
+ sorted (There is no entities list to sort).
-
@@ -549,7 +564,7 @@ end
tiny.removeEntity (world, entity)
-
- Removes an Entity to the World. Returns the Entity.
+ Removes an Entity from the World. Returns the Entity.
@@ -675,21 +690,6 @@ end
-
- -
-
- tiny.getSystemIndex (world, system)
-
- -
- Gets the index of the System in the World.
- A simpler alternative is
system.index.
-
-
-
-
-
-
-
-
@@ -714,7 +714,7 @@ end
generated by LDoc 1.4.3
-Last updated 2016-03-05 16:37:42
+Last updated 2016-08-10 21:34:56