mirror of
https://github.com/Reuh/ubiquitousse.git
synced 2025-10-27 09:09:30 +00:00
Étienne Reuh Fildadut
9d2e886609
The component methods system was awkward and didn't give much benefit compared to just using methods on Systems. Plus now we really only have data in entities. Since we don't have component methods, the callback system had to be replaced; I integrated it with the default System methods since it's a relatively common behavior.
1604 lines
47 KiB
HTML
1604 lines
47 KiB
HTML
<!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>Ubiquitousse reference</title>
|
|
<link rel="stylesheet" href="../ldoc_new.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>Ubiquitousse</h1>
|
|
|
|
|
|
<ul>
|
|
<li><a href="../index.html">Index</a></li>
|
|
</ul>
|
|
|
|
<h2>Contents</h2>
|
|
<ul>
|
|
<li><a href="#Functions">Functions</a></li>
|
|
<li><a href="#Entity_objects">Entity objects </a></li>
|
|
<li><a href="#System_objects">System objects </a></li>
|
|
</ul>
|
|
|
|
|
|
<h2>Modules</h2>
|
|
<ul class="nowrap">
|
|
<li><a href="../modules/ubiquitousse.html">ubiquitousse</a></li>
|
|
<li><a href="../modules/asset.html">asset</a></li>
|
|
<li><strong>ecs</strong></li>
|
|
<li><a href="../modules/ldtk.html">ldtk</a></li>
|
|
<li><a href="../modules/scene.html">scene</a></li>
|
|
<li><a href="../modules/signal.html">signal</a></li>
|
|
<li><a href="../modules/timer.html">timer</a></li>
|
|
<li><a href="../modules/util.html">util</a></li>
|
|
</ul>
|
|
<h2>Topics</h2>
|
|
<ul class="">
|
|
<li><a href="../topics/README.md.html">README</a></li>
|
|
<li><a href="../topics/LICENSE.html">LICENSE</a></li>
|
|
</ul>
|
|
|
|
</div>
|
|
|
|
<div id="content">
|
|
|
|
<h1>Module <code>ecs</code></h1>
|
|
<p>ECS (<a href="https://en.wikipedia.org/wiki/Entity_component_system">entity compenent system</a>) library for Lua.</p>
|
|
<p>Entity Component System library, inspired by the excellent <a href="https://github.com/bakpakin/tiny-ecs/tree/master">tiny-ecs</a> by bakpakin.
|
|
Main differences include:</p>
|
|
|
|
<ul>
|
|
<li>ability to nest systems (more organisation potential);</li>
|
|
<li>instanciation of systems for each world (no shared state) (several worlds can coexist at the same time easily);</li>
|
|
<li>adding and removing entities is done instantaneously (no going isane over tiny-ecs cache issues);</li>
|
|
<li>ability to add and remove components from entities after they were added to the world (more dynamic entities).</li>
|
|
</ul>
|
|
|
|
|
|
<p>And a fair amount of other quality-of-life features.</p>
|
|
|
|
<p>The goals of this library are similar in spirit to tiny-ecs: simple to use, flexible, and useful.
|
|
The more advanced features it provides relative to tiny-ecs are made so that you can completely ignore them
|
|
if you don’t use them.</p>
|
|
|
|
<p>The module returns a table that contains several functions, <a href="../modules/ecs.html#world">world</a> or <a href="../modules/scene.html#">scene</a> are starting points
|
|
to create your world.</p>
|
|
|
|
<p>No mandatory dependency.
|
|
Optional dependency: <a href="../modules/ubiquitousse.html#scene">ubiquitousse.scene</a>, to allow quick creation of ECS-based scenes (<a href="../modules/ecs.html#scene">ecs.scene</a>).</p>
|
|
<h3>Usage:</h3>
|
|
<ul>
|
|
<pre class="example">-- Same example as tiny-ecs', for comparaison purposes
|
|
|
|
local ecs = require("ubiquitousse.ecs")
|
|
|
|
local talkingSystem = {
|
|
filter = { "name", "mass", "phrase" },
|
|
process = function(self, c, e, dt)
|
|
e.mass = e.mass + dt * 3
|
|
print(("%s who weighs %d pounds, says %q."):format(e.name, e.mass, e.phrase))
|
|
end
|
|
}
|
|
|
|
local joe = {
|
|
name = "Joe",
|
|
phrase = "I'm a plumber.",
|
|
mass = 150,
|
|
hairColor = "brown"
|
|
}
|
|
|
|
local world = ecs.world(talkingSystem)
|
|
world:add(joe)
|
|
|
|
for i = 1, 20 do
|
|
world:update(1)
|
|
end
|
|
</pre>
|
|
</ul>
|
|
|
|
|
|
<h2><a href="#Functions">Functions</a></h2>
|
|
<table class="function_list">
|
|
<tr>
|
|
<td class="name" nowrap><a href="#world">world (...)</a></td>
|
|
<td class="summary">Create and returns a world system based on a list of systems.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#all">all (...)</a></td>
|
|
<td class="summary">Returns a filter that returns <code>true</code> if, for every argument, a field with the same name exists in the entity.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#any">any (...)</a></td>
|
|
<td class="summary">Returns a filter that returns <code>true</code> if one of the arguments if the name of a field in the entity.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#scene">scene (name[, systems={}[, entities={}]])</a></td>
|
|
<td class="summary">If <code>uqt.scene</code> is available, returns a new scene that will consist of a ECS world with the specified systems and entities.</td>
|
|
</tr>
|
|
</table>
|
|
<h2><a href="#Entity_objects">Entity objects </a></h2>
|
|
<table class="function_list">
|
|
</table>
|
|
<h3 class="doc-title"><a href="#Entity.Component">Components.</a></h3>
|
|
<table class="function_list">
|
|
</table>
|
|
<h2><a href="#System_objects">System objects </a></h2>
|
|
<table class="function_list">
|
|
</table>
|
|
<h3 class="doc-title"><a href="#System.modifiable">Modifiable fields.</a></h3>
|
|
<table class="function_list">
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System.name">System.name</a></td>
|
|
<td class="summary">Name of the system.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System.systems">System.systems</a></td>
|
|
<td class="summary">List of subsystems.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System.interval">System.interval</a></td>
|
|
<td class="summary">If not <code>false</code>, the system will only update every interval seconds.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System.active">System.active</a></td>
|
|
<td class="summary">The system and its susbsystems will only update if this is <code>true</code>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System.visible">System.visible</a></td>
|
|
<td class="summary">The system and its subsystems will only draw if this is <code>true</code>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System.default">System.default</a></td>
|
|
<td class="summary">Defaults value to put into the entities’s system component when they are added.</td>
|
|
</tr>
|
|
</table>
|
|
<h3 class="doc-title"><a href="#System.callbacks">Callbacks.</a></h3>
|
|
<table class="function_list">
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System:filter">System:filter (e) <sup><em>[callback]</em></sup></a></td>
|
|
<td class="summary">Called when checking if an entity should be added to this system.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System:compare">System:compare (e1, e2) <sup><em>[callback]</em></sup></a></td>
|
|
<td class="summary">Called when adding an entity to this system determining its order.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System:onAdd">System:onAdd (c, e) <sup><em>[callback]</em></sup></a></td>
|
|
<td class="summary">Called when adding an entity to the system.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System:onRemove">System:onRemove (c, e) <sup><em>[callback]</em></sup></a></td>
|
|
<td class="summary">Called when removing an entity from the system.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System:onInstance">System:onInstance () <sup><em>[callback]</em></sup></a></td>
|
|
<td class="summary">Called when the system is instancied, before any call to <a href="../modules/ecs.html#System:onAddToWorld">System:onAddToWorld</a> (including other systems in the world).</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System:onAddToWorld">System:onAddToWorld (world) <sup><em>[callback]</em></sup></a></td>
|
|
<td class="summary">Called when the system is added to a world.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System:onRemoveFromWorld">System:onRemoveFromWorld (world) <sup><em>[callback]</em></sup></a></td>
|
|
<td class="summary">Called when the system is removed from a world (i.e., the world is destroyed).</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System:onDestroy">System:onDestroy () <sup><em>[callback]</em></sup></a></td>
|
|
<td class="summary">Called when the world is destroyed, after every call to <a href="../modules/ecs.html#System:onRemoveFromWorld">System:onRemoveFromWorld</a> (including other systems in the world).</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System:onUpdate">System:onUpdate (dt) <sup><em>[callback]</em></sup></a></td>
|
|
<td class="summary">Called when updating the system.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System:onDraw">System:onDraw () <sup><em>[callback]</em></sup></a></td>
|
|
<td class="summary">Called when drawing the system.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System:process">System:process (c, e, dt) <sup><em>[callback]</em></sup></a></td>
|
|
<td class="summary">Called when updating the system, for every entity the system contains.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System:render">System:render (c, e) <sup><em>[callback]</em></sup></a></td>
|
|
<td class="summary">Called when drawing the system, for every entity the system contains.</td>
|
|
</tr>
|
|
</table>
|
|
<h3 class="doc-title"><a href="#System.ro">Read-only fields.</a></h3>
|
|
<table class="function_list">
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System.world">System.world <sup><em>[read-only]</em></sup></a></td>
|
|
<td class="summary">The world the system belongs to.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System.w">System.w <sup><em>[read-only]</em></sup></a></td>
|
|
<td class="summary">Shortcut to <a href="../modules/ecs.html#System.world">System.world</a>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System.entityCount">System.entityCount <sup><em>[read-only]</em></sup></a></td>
|
|
<td class="summary">Number of entities in the system.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System.s">System.s <sup><em>[read-only]</em></sup></a></td>
|
|
<td class="summary">Map of all named systems in the world (not only subsystems).</td>
|
|
</tr>
|
|
</table>
|
|
<h3 class="doc-title"><a href="#System.smethods">Methods.</a></h3>
|
|
<table class="function_list">
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System:add">System:add (e, ...)</a></td>
|
|
<td class="summary">Add entities to the system and its subsystems.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System:remove">System:remove (e, ...)</a></td>
|
|
<td class="summary">Remove entities from the system and its subsystems.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System:refresh">System:refresh (e, ...)</a></td>
|
|
<td class="summary">Refresh an entity’s systems.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System:reorder">System:reorder (e, ...)</a></td>
|
|
<td class="summary">Reorder an entity.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System:has">System:has (e, ...)</a></td>
|
|
<td class="summary">Returns <code>true</code> if all these entities are in the system.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System:iter">System:iter ()</a></td>
|
|
<td class="summary">Returns an iterator that iterate through the entties in this system, in order.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System:clear">System:clear ()</a></td>
|
|
<td class="summary">Remove every entity from the system and its subsystems.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System:update">System:update (dt)</a></td>
|
|
<td class="summary">Try to update the system and its subsystems.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System:draw">System:draw ()</a></td>
|
|
<td class="summary">Try to draw the system and its subsystems.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System:callback">System:callback (name, e, ...)</a></td>
|
|
<td class="summary">Trigger a custom callback on a single entity.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System:emit">System:emit (name, ...)</a></td>
|
|
<td class="summary">Emit an event on the system.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System:destroy">System:destroy ()</a></td>
|
|
<td class="summary">Remove all the entities and subsystems in this system.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<br/>
|
|
<br/>
|
|
|
|
|
|
<h2 class="section-header "><a name="Functions"></a>Functions</h2>
|
|
|
|
<dl class="function">
|
|
<dt>
|
|
<a name = "world"></a>
|
|
<strong>world (...)</strong>
|
|
</dt>
|
|
<dd>
|
|
Create and returns a world system based on a list of systems.
|
|
The systems will be instancied for this world.
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
<h3>Parameters:</h3>
|
|
<ul>
|
|
<li><span class="parameter">...</span>
|
|
<span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table,...</a></span>
|
|
list of (uninstancied) systems
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>Returns:</h3>
|
|
<ol>
|
|
|
|
<span class="types"><a class="type" href="../modules/ecs.html#System_objects">System</a></span>
|
|
the world system
|
|
</ol>
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "all"></a>
|
|
<strong>all (...)</strong>
|
|
</dt>
|
|
<dd>
|
|
Returns a filter that returns <code>true</code> if, for every argument, a field with the same name exists in the entity.
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
<h3>Parameters:</h3>
|
|
<ul>
|
|
<li><span class="parameter">...</span>
|
|
<span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string,...</a></span>
|
|
list of field names that must be in entity
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>Returns:</h3>
|
|
<ol>
|
|
|
|
<span class="types"><span class="type">function(e)</span></span>
|
|
that returns <code>true</code> if e has all the fields
|
|
</ol>
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "any"></a>
|
|
<strong>any (...)</strong>
|
|
</dt>
|
|
<dd>
|
|
Returns a filter that returns <code>true</code> if one of the arguments if the name of a field in the entity.
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
<h3>Parameters:</h3>
|
|
<ul>
|
|
<li><span class="parameter">...</span>
|
|
<span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string,...</a></span>
|
|
list of field names that may be in entity
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>Returns:</h3>
|
|
<ol>
|
|
|
|
<span class="types"><span class="type">function(e)</span></span>
|
|
that returns <code>true</code> if e has at leats one of the fields
|
|
</ol>
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "scene"></a>
|
|
<strong>scene (name[, systems={}[, entities={}]])</strong>
|
|
</dt>
|
|
<dd>
|
|
If <code>uqt.scene</code> is available, returns a new scene that will consist of a ECS world with the specified systems and entities.
|
|
|
|
<h3>Requires:</h3>
|
|
<ul>
|
|
ubiquitousse.scene
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
<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>
|
|
the name of the new scene
|
|
</li>
|
|
<li><span class="parameter">systems</span>
|
|
<span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
|
|
list of systems to add to the world
|
|
(<em>default</em> {})
|
|
</li>
|
|
<li><span class="parameter">entities</span>
|
|
<span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
|
|
list of entities to add to the world
|
|
(<em>default</em> {})
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>Returns:</h3>
|
|
<ol>
|
|
|
|
<span class="types"><a class="type" href="../modules/ecs.html#scene">scene</a></span>
|
|
the new scene
|
|
</ol>
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
</dl>
|
|
<h2 class="section-header has-description"><a name="Entity_objects"></a>Entity objects </h2>
|
|
|
|
<div class="section-description">
|
|
Entities are regular tables that get processed by <a href="../modules/ecs.html#System_objects">System</a>s. </p>
|
|
|
|
<p> The idea is that entities <em>should</em> only contain data and no code; it’s the systems that are responsible for the actual processing
|
|
(but it’s your game, do as you want).</p>
|
|
|
|
<p> This data is referred to, and organized in, “components”.
|
|
</div>
|
|
<dl class="function">
|
|
</dl>
|
|
<h3 class="doc-title"><a name = "Entity.Component"></a>Components.</h3>
|
|
<div class="doc-description">
|
|
Entities are Lua tables, and thus contain key-values pairs: each one of these pairs is called a “component”. The data can be
|
|
whatever you want, and ideally each component <em>should</em> store the data for one singular aspect of the entity, for example its position, name, etc.</p>
|
|
|
|
<p>This library does not do any kind of special processing by itself on the entity tables and take them as is (no metatable, no methamethods, etc.),
|
|
so you are free to handle them as you want in your systems or elsewhere.</p>
|
|
|
|
<p>Since it’s relatively common for systems to only operate on a single component, as a shortcut the library often consider what it calls the “system component”:
|
|
that is, the component in the entity that has the same name as the system (if it exists).
|
|
</div>
|
|
<dl class="function">
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
<h3>Usage:</h3>
|
|
<ul>
|
|
<pre class="example"><span class="comment">-- example entity
|
|
</span><span class="keyword">local</span> entity = {
|
|
position = { x = <span class="number">0</span>, y = <span class="number">52</span> }, <span class="comment">-- a "position" component
|
|
</span> sprite = newSprite(<span class="string">"awesomeguy.png"</span>) <span class="comment">-- a "sprite" component
|
|
</span>}
|
|
|
|
<span class="comment">-- example "sprite" system
|
|
</span><span class="keyword">local</span> sprite = {
|
|
name = <span class="string">"sprite"</span>,
|
|
filter = <span class="string">"sprite"</span>, <span class="comment">-- process entities that have a "sprite" component
|
|
</span> <span class="comment">-- systems callbacks that are called per-entity often give you the system component as an argument
|
|
</span> <span class="comment">-- the system component is the component with the same name as the system, thus here the sprite component
|
|
</span> render = <span class="keyword">function</span>(self, component, entity)
|
|
<span class="comment">-- component == entity.sprite
|
|
</span> component:draw()
|
|
<span class="keyword">end</span>
|
|
}</pre>
|
|
</ul>
|
|
|
|
</dd>
|
|
</dl>
|
|
<h2 class="section-header has-description"><a name="System_objects"></a>System objects </h2>
|
|
|
|
<div class="section-description">
|
|
Systems and Worlds.
|
|
Systems are what do the processing on your entities. A system contains a list of entities; the entities in this list are selected
|
|
using a <a href="../modules/ecs.html#System:filter">filter</a>, and the system will only operate on those filtered entities.</p>
|
|
|
|
<p>A system can also be created that do not accept any entity (<code>filter = false</code>, this is the default): such a system can still be
|
|
used to do processing that don’t need to be done per-entity but still behave like other systems (e.g. to do some static calculation each update).</p>
|
|
|
|
<p>The system also contains <a href="../modules/ecs.html#System.callbacks">callbacks</a>, these define the actual processing done on the system and its entities and you will want to redefine
|
|
at least one of them to make your system actually do something.</p>
|
|
|
|
<p>Then you can call <a href="../modules/ecs.html#System:update">System:update</a>, <a href="../modules/ecs.html#System:draw">System:draw</a>, <a href="../modules/ecs.html#System:emit">System:emit</a> or <a href="../modules/ecs.html#System:callback">System:callback</a> at appropriate times and the system will call the
|
|
associated callbacks on itself and its entities, and then pass it to its subsystems. In practise you would likely only call these on
|
|
the world system, so the callbacks are correctly propagated to every single system in the world.</p>
|
|
|
|
<p>Systems are defined as regular tables with all the fields and methods you need in it. However, when a system is added to
|
|
a world, the table you defined is not used directly, but we use what we call an “instancied system”: think of it of an instance of your system
|
|
like if it were a class.
|
|
The instancied system will have a metatable set that gives it some methods and fields defined by the library on top of what you defined.
|
|
Modifying the instancied system will only modify this instance and not the original system you defined, so several instances of your system
|
|
can exist in different worlds (note that the original system is not copied on instancing; if you reference a table in the original system it will use the
|
|
original table directly).</p>
|
|
|
|
<p>Systems can have subsystems; that is a system that behave as an extension of their parent system. They only operates on the entities already
|
|
present in their parent subsystem, only update when their parent system updates, etc. You can thus organize your systems in a hierarchy to
|
|
avoid repeating your filters or allow controlling several system from a single parent system.</p>
|
|
|
|
<p>The top-level system is called the “world”; it behaves in exactly the same way as other systems, and accept every entity by default.
|
|
</div>
|
|
<h3>Usage:</h3>
|
|
<pre class="example"><span class="keyword">local</span> sprite = {
|
|
filter = { <span class="string">"sprite"</span>, <span class="string">"position"</span> }, <span class="comment">-- only operate on entities with "sprite" and "position" components
|
|
</span> systems = { animated }, <span class="comment">-- subsystems: they only operate on entities already filtered by this system (on top of their own filtering)
|
|
</span>
|
|
<span class="comment">-- Called when an entity is added to this system.
|
|
</span> onAdd = <span class="keyword">function</span>(self, component, entity)
|
|
<span class="global">print</span>(<span class="string">"Added an entity, entity count in the system:"</span>, self.entityCount) <span class="comment">-- self refer to the instancied system
|
|
</span> <span class="keyword">end</span>,
|
|
|
|
<span class="comment">-- Called when the system is updated, for every entity the system
|
|
</span> process = <span class="keyword">function</span>(self, component, entity, dt)
|
|
<span class="comment">-- processing...
|
|
</span> <span class="keyword">end</span>
|
|
}
|
|
|
|
<span class="keyword">local</span> world = ecs.world(system) <span class="comment">-- instanciate a world with the sprite system (and all its subsystems)
|
|
</span>
|
|
<span class="comment">-- Add an entity: doesn't pass the filtering, so nothing happens
|
|
</span>world:add {
|
|
name = <span class="string">"John"</span>
|
|
}
|
|
|
|
<span class="comment">-- Added to the sprite system! Call sprite:onAdd, and also try to add it to its subsystems
|
|
</span>world:add {
|
|
sprite = newSprite(<span class="string">"example.png"</span>),
|
|
position = { x=<span class="number">5</span>, y=<span class="number">0</span> }
|
|
}
|
|
|
|
<span class="comment">-- Trigger sprite:onUpdate and sprite:process callbacks
|
|
</span>world:update(dt)</pre>
|
|
<dl class="function">
|
|
</dl>
|
|
<h3 class="doc-title"><a name = "System.modifiable"></a>Modifiable fields.</h3>
|
|
<div class="doc-description">
|
|
Every field defined below is optional and can be accessed or redefined at any time, unless written otherwise. Though you would typically set them
|
|
before instanciating your systems.
|
|
</div>
|
|
<dl class="function">
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System.name"></a>
|
|
<strong>System.name</strong>
|
|
</dt>
|
|
<dd>
|
|
Name of the system.
|
|
Used to create a field with the system’s name in <code>world.s</code> and determine the associated system component.
|
|
If not set, the system will not appear in <code>world.s</code> and gives <code>nil</code> instead of the system component in callbacks.</p>
|
|
|
|
<p> Do not change after system instanciation.
|
|
|
|
</ul>
|
|
<h3>Type:</h3>
|
|
<ul>
|
|
<li><code>string</code></li>
|
|
<li><code>nil</code> if no name</li>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System.systems"></a>
|
|
<strong>System.systems</strong>
|
|
</dt>
|
|
<dd>
|
|
List of subsystems.
|
|
On a instancied system, this is a list of the same subsystems, but instancied for this world.</p>
|
|
|
|
<p> Do not change after system instanciation.
|
|
|
|
</ul>
|
|
<h3>Type:</h3>
|
|
<ul>
|
|
<li><code>table</code></li>
|
|
<li><code>nil</code> if no subsystem</li>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System.interval"></a>
|
|
<strong>System.interval</strong>
|
|
</dt>
|
|
<dd>
|
|
If not <code>false</code>, the system will only update every interval seconds.
|
|
<code>false</code> by default.
|
|
|
|
</ul>
|
|
<h3>Type:</h3>
|
|
<ul>
|
|
<li><code>number</code> interval of time between each update</li>
|
|
<li><code>false</code> to disable</li>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System.active"></a>
|
|
<strong>System.active</strong>
|
|
</dt>
|
|
<dd>
|
|
The system and its susbsystems will only update if this is <code>true</code>.
|
|
<code>true</code> by default.
|
|
|
|
</ul>
|
|
<h3>Type:</h3>
|
|
<ul>
|
|
<code>boolean</code>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System.visible"></a>
|
|
<strong>System.visible</strong>
|
|
</dt>
|
|
<dd>
|
|
The system and its subsystems will only draw if this is <code>true</code>.
|
|
<code>true</code> by default.
|
|
|
|
</ul>
|
|
<h3>Type:</h3>
|
|
<ul>
|
|
<code>boolean</code>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System.default"></a>
|
|
<strong>System.default</strong>
|
|
</dt>
|
|
<dd>
|
|
Defaults value to put into the entities’s system component when they are added. </p>
|
|
|
|
<p> If this is table, will recursively fill missing values.
|
|
Metatables will be preserved during the copy but not copied themselves.</p>
|
|
|
|
<p> Changing this will not affect entities already in the system.
|
|
Doesn’t have any effect if the system doesn’t have a name.
|
|
|
|
</ul>
|
|
<h3>Type:</h3>
|
|
<ul>
|
|
<li><code>any</code></li>
|
|
<li><code>nil</code> if no default</li>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
</dl>
|
|
<h3 class="doc-title"><a name = "System.callbacks"></a>Callbacks.</h3>
|
|
<div class="doc-description">
|
|
Functions that are called when something happens in the system.
|
|
Redefine them to change system behaviour.
|
|
</div>
|
|
<dl class="function">
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:filter"></a>
|
|
<strong>System:filter (e) <sup><em>[callback]</em></sup></strong>
|
|
</dt>
|
|
<dd>
|
|
Called when checking if an entity should be added to this system.
|
|
Returns <code>true</code> if the entity should be added to this system (and therefore its subsystems).</p>
|
|
|
|
<p> If this is a string or a table, it will be converted to a filter function on instanciation using ecs.any.</p>
|
|
|
|
<p> If this <code>true</code>, will accept every entity; if <code>false</code>, reject every entity.</p>
|
|
|
|
<p> Will only test entities when they are added; changing this after system creation will not affect entities already in the system.</p>
|
|
|
|
<p> By default, rejects everything.
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
<h3>Parameters:</h3>
|
|
<ul>
|
|
<li><span class="parameter">e</span>
|
|
<span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span>
|
|
entity table to check
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>Returns:</h3>
|
|
<ol>
|
|
|
|
<span class="types"><span class="type">boolean</span></span>
|
|
<code>true</code> if entity should be added
|
|
</ol>
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:compare"></a>
|
|
<strong>System:compare (e1, e2) <sup><em>[callback]</em></sup></strong>
|
|
</dt>
|
|
<dd>
|
|
Called when adding an entity to this system determining its order.
|
|
Returns <code>true</code> if <code>e1 <=</code> e2 (i.e., if <code>e1</code> should be processed before <code>e2</code> in this system). e1 and e2 are two entities.</p>
|
|
|
|
<p> Used to place the entity in the sorted entity list when it is added; changing this after system creation
|
|
will not change the order of entities already in the system.</p>
|
|
|
|
<p> By default, new entities are added at the start of the list.
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
<h3>Parameters:</h3>
|
|
<ul>
|
|
<li><span class="parameter">e1</span>
|
|
<span class="types"><a class="type" href="../modules/ecs.html#Entity_objects">Entity</a></span>
|
|
entity table to check for inferiority
|
|
</li>
|
|
<li><span class="parameter">e2</span>
|
|
<span class="types"><a class="type" href="../modules/ecs.html#Entity_objects">Entity</a></span>
|
|
entity table to check for superiority
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>Returns:</h3>
|
|
<ol>
|
|
|
|
<span class="types"><span class="type">boolean</span></span>
|
|
<code>true</code> if e1 <= e2
|
|
</ol>
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:onAdd"></a>
|
|
<strong>System:onAdd (c, e) <sup><em>[callback]</em></sup></strong>
|
|
</dt>
|
|
<dd>
|
|
Called when adding an entity to the system.
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
<h3>Parameters:</h3>
|
|
<ul>
|
|
<li><span class="parameter">c</span>
|
|
<span class="types"><a class="type" href="../modules/ecs.html#Entity.Component">Component</a></span>
|
|
the entity’s system component
|
|
</li>
|
|
<li><span class="parameter">e</span>
|
|
<span class="types"><a class="type" href="../modules/ecs.html#Entity_objects">Entity</a></span>
|
|
the entity table
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:onRemove"></a>
|
|
<strong>System:onRemove (c, e) <sup><em>[callback]</em></sup></strong>
|
|
</dt>
|
|
<dd>
|
|
Called when removing an entity from the system.
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
<h3>Parameters:</h3>
|
|
<ul>
|
|
<li><span class="parameter">c</span>
|
|
<span class="types"><a class="type" href="../modules/ecs.html#Entity.Component">Component</a></span>
|
|
the entity’s system component
|
|
</li>
|
|
<li><span class="parameter">e</span>
|
|
<span class="types"><a class="type" href="../modules/ecs.html#Entity_objects">Entity</a></span>
|
|
the entity table
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:onInstance"></a>
|
|
<strong>System:onInstance () <sup><em>[callback]</em></sup></strong>
|
|
</dt>
|
|
<dd>
|
|
Called when the system is instancied, before any call to <a href="../modules/ecs.html#System:onAddToWorld">System:onAddToWorld</a> (including other systems in the world).
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:onAddToWorld"></a>
|
|
<strong>System:onAddToWorld (world) <sup><em>[callback]</em></sup></strong>
|
|
</dt>
|
|
<dd>
|
|
Called when the system is added to a world.
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
<h3>Parameters:</h3>
|
|
<ul>
|
|
<li><span class="parameter">world</span>
|
|
<span class="types"><a class="type" href="../modules/ecs.html#System_objects">System</a></span>
|
|
world system
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:onRemoveFromWorld"></a>
|
|
<strong>System:onRemoveFromWorld (world) <sup><em>[callback]</em></sup></strong>
|
|
</dt>
|
|
<dd>
|
|
Called when the system is removed from a world (i.e., the world is destroyed).
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
<h3>Parameters:</h3>
|
|
<ul>
|
|
<li><span class="parameter">world</span>
|
|
<span class="types"><a class="type" href="../modules/ecs.html#System_objects">System</a></span>
|
|
world system
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:onDestroy"></a>
|
|
<strong>System:onDestroy () <sup><em>[callback]</em></sup></strong>
|
|
</dt>
|
|
<dd>
|
|
Called when the world is destroyed, after every call to <a href="../modules/ecs.html#System:onRemoveFromWorld">System:onRemoveFromWorld</a> (including other systems in the world).
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:onUpdate"></a>
|
|
<strong>System:onUpdate (dt) <sup><em>[callback]</em></sup></strong>
|
|
</dt>
|
|
<dd>
|
|
Called when updating the system.
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
<h3>Parameters:</h3>
|
|
<ul>
|
|
<li><span class="parameter">dt</span>
|
|
<span class="types"><span class="type">number</span></span>
|
|
delta-time since last update
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:onDraw"></a>
|
|
<strong>System:onDraw () <sup><em>[callback]</em></sup></strong>
|
|
</dt>
|
|
<dd>
|
|
Called when drawing the system.
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:process"></a>
|
|
<strong>System:process (c, e, dt) <sup><em>[callback]</em></sup></strong>
|
|
</dt>
|
|
<dd>
|
|
Called when updating the system, for every entity the system contains. Called after <a href="../modules/ecs.html#System:onUpdate">System:onUpdate</a> was called on the system.
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
<h3>Parameters:</h3>
|
|
<ul>
|
|
<li><span class="parameter">c</span>
|
|
<span class="types"><a class="type" href="../modules/ecs.html#Entity.Component">Component</a></span>
|
|
the entity’s system component
|
|
</li>
|
|
<li><span class="parameter">e</span>
|
|
<span class="types"><a class="type" href="../modules/ecs.html#Entity_objects">Entity</a></span>
|
|
the entity table
|
|
</li>
|
|
<li><span class="parameter">dt</span>
|
|
<span class="types"><span class="type">number</span></span>
|
|
delta-time since last update
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:render"></a>
|
|
<strong>System:render (c, e) <sup><em>[callback]</em></sup></strong>
|
|
</dt>
|
|
<dd>
|
|
Called when drawing the system, for every entity the system contains. Called after <a href="../modules/ecs.html#System:onDraw">System:onDraw</a> was called on the system.
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
<h3>Parameters:</h3>
|
|
<ul>
|
|
<li><span class="parameter">c</span>
|
|
<span class="types"><a class="type" href="../modules/ecs.html#Entity.Component">Component</a></span>
|
|
the entity’s system component
|
|
</li>
|
|
<li><span class="parameter">e</span>
|
|
<span class="types"><a class="type" href="../modules/ecs.html#Entity_objects">Entity</a></span>
|
|
the entity table
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
</dl>
|
|
<h3 class="doc-title"><a name = "System.ro"></a>Read-only fields.</h3>
|
|
<div class="doc-description">
|
|
Fields available on instancied systems. Don’t modify them unless you like broken things.
|
|
</div>
|
|
<dl class="function">
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System.world"></a>
|
|
<strong>System.world <sup><em>[read-only]</em></sup></strong>
|
|
</dt>
|
|
<dd>
|
|
The world the system belongs to.
|
|
|
|
</ul>
|
|
<h3>Type:</h3>
|
|
<ul>
|
|
<code>System</code> world
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System.w"></a>
|
|
<strong>System.w <sup><em>[read-only]</em></sup></strong>
|
|
</dt>
|
|
<dd>
|
|
Shortcut to <a href="../modules/ecs.html#System.world">System.world</a>.
|
|
|
|
</ul>
|
|
<h3>Type:</h3>
|
|
<ul>
|
|
<code>System</code> world
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System.entityCount"></a>
|
|
<strong>System.entityCount <sup><em>[read-only]</em></sup></strong>
|
|
</dt>
|
|
<dd>
|
|
Number of entities in the system.
|
|
|
|
</ul>
|
|
<h3>Type:</h3>
|
|
<ul>
|
|
<code>integer</code>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System.s"></a>
|
|
<strong>System.s <sup><em>[read-only]</em></sup></strong>
|
|
</dt>
|
|
<dd>
|
|
Map of all named systems in the world (not only subsystems). Same for every system from the same world.
|
|
|
|
</ul>
|
|
<h3>Type:</h3>
|
|
<ul>
|
|
<code>table</code> {[system.name]=instanciedSystem, ...}
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
</dl>
|
|
<h3 class="doc-title"><a name = "System.smethods"></a>Methods.</h3>
|
|
<div class="doc-description">
|
|
Methods available on instancied systems.
|
|
</div>
|
|
<dl class="function">
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:add"></a>
|
|
<strong>System:add (e, ...)</strong>
|
|
</dt>
|
|
<dd>
|
|
Add entities to the system and its subsystems. </p>
|
|
|
|
<p> Will skip entities that are already in the system.</p>
|
|
|
|
<p> Entities are added to subsystems after they were succesfully added to their parent system.</p>
|
|
|
|
<p> If this is called on a subsystem instead of the world, be warned that this will bypass all the parent’s systems filters.
|
|
If you do that, since <a href="../modules/ecs.html#System:remove">System:remove</a> will not search for entities in systems where they should have been filtered out, the added entities will not be removed
|
|
when calling <a href="../modules/ecs.html#System:remove">System:remove</a> on a parent system or the world. The entity can be removed by calling <a href="../modules/ecs.html#System:remove">System:remove</a> on the system <a href="../modules/ecs.html#System:add">System:add</a> was called on.</p>
|
|
|
|
<p> Complexity: O(1) per unordered system, O(entityCount) per ordered system.
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
<h3>Parameters:</h3>
|
|
<ul>
|
|
<li><span class="parameter">e</span>
|
|
<span class="types"><a class="type" href="../modules/ecs.html#Entity_objects">Entity</a></span>
|
|
entity to add
|
|
</li>
|
|
<li><span class="parameter">...</span>
|
|
<span class="types"><span class="type">Entity...</span></span>
|
|
other entities to add
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>Returns:</h3>
|
|
<ol>
|
|
|
|
<span class="types"><a class="type" href="../modules/ecs.html#Entity_objects">Entity,...</a></span>
|
|
<code>e,…</code> the function arguments
|
|
</ol>
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:remove"></a>
|
|
<strong>System:remove (e, ...)</strong>
|
|
</dt>
|
|
<dd>
|
|
Remove entities from the system and its subsystems. </p>
|
|
|
|
<p> Will skip entities that are not in the system.</p>
|
|
|
|
<p> Entities are removed from subsystems before they are removed from their parent system.</p>
|
|
|
|
<p> If you intend to call this on a subsystem instead of the world, please read the warning in <a href="../modules/ecs.html#System:add">System:add</a>.</p>
|
|
|
|
<p> Complexity: O(1) per system.
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
<h3>Parameters:</h3>
|
|
<ul>
|
|
<li><span class="parameter">e</span>
|
|
<span class="types"><a class="type" href="../modules/ecs.html#Entity_objects">Entity</a></span>
|
|
entity to remove
|
|
</li>
|
|
<li><span class="parameter">...</span>
|
|
<span class="types"><span class="type">Entity...</span></span>
|
|
other entities to remove
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>Returns:</h3>
|
|
<ol>
|
|
|
|
<span class="types"><a class="type" href="../modules/ecs.html#Entity_objects">Entity,...</a></span>
|
|
<code>e,…</code> the function arguments
|
|
</ol>
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:refresh"></a>
|
|
<strong>System:refresh (e, ...)</strong>
|
|
</dt>
|
|
<dd>
|
|
Refresh an entity’s systems. </p>
|
|
|
|
<p> Behave similarly to <a href="../modules/ecs.html#System:add">System:add</a>, but if the entity is already in the system, instead of skipping it, it
|
|
will check for new and removed components and add and remove from (sub)systems accordingly.</p>
|
|
|
|
<p> Complexity: O(1) per system + add/remove complexity.
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
<h3>Parameters:</h3>
|
|
<ul>
|
|
<li><span class="parameter">e</span>
|
|
<span class="types"><a class="type" href="../modules/ecs.html#Entity_objects">Entity</a></span>
|
|
entity to refresh
|
|
</li>
|
|
<li><span class="parameter">...</span>
|
|
<span class="types"><span class="type">Entity...</span></span>
|
|
other entities to refresh
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>Returns:</h3>
|
|
<ol>
|
|
|
|
<span class="types"><a class="type" href="../modules/ecs.html#Entity_objects">Entity,...</a></span>
|
|
<code>e,…</code> the function arguments
|
|
</ol>
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:reorder"></a>
|
|
<strong>System:reorder (e, ...)</strong>
|
|
</dt>
|
|
<dd>
|
|
Reorder an entity. </p>
|
|
|
|
<p> Will recalculate the entity position in the entity list for this system and its subsystems.
|
|
Will skip entities that are not in the system.</p>
|
|
|
|
<p> Complexity: O(entityCount) per system.
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
<h3>Parameters:</h3>
|
|
<ul>
|
|
<li><span class="parameter">e</span>
|
|
<span class="types"><a class="type" href="../modules/ecs.html#Entity_objects">Entity</a></span>
|
|
entity to reorder
|
|
</li>
|
|
<li><span class="parameter">...</span>
|
|
<span class="types"><span class="type">Entity...</span></span>
|
|
other entities to reorder
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>Returns:</h3>
|
|
<ol>
|
|
|
|
<span class="types"><a class="type" href="../modules/ecs.html#Entity_objects">Entity,...</a></span>
|
|
<code>e,…</code> the function arguments
|
|
</ol>
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:has"></a>
|
|
<strong>System:has (e, ...)</strong>
|
|
</dt>
|
|
<dd>
|
|
Returns <code>true</code> if all these entities are in the system. </p>
|
|
|
|
<p> Complexity: O(1).
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
<h3>Parameters:</h3>
|
|
<ul>
|
|
<li><span class="parameter">e</span>
|
|
<span class="types"><a class="type" href="../modules/ecs.html#Entity_objects">Entity</a></span>
|
|
entity that may be in the system
|
|
</li>
|
|
<li><span class="parameter">...</span>
|
|
<span class="types"><span class="type">Entity...</span></span>
|
|
other entities that may be in the system
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>Returns:</h3>
|
|
<ol>
|
|
|
|
<span class="types"><span class="type">boolean</span></span>
|
|
<code>true</code> if every entity is in the system
|
|
</ol>
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:iter"></a>
|
|
<strong>System:iter ()</strong>
|
|
</dt>
|
|
<dd>
|
|
Returns an iterator that iterate through the entties in this system, in order.
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
|
|
<h3>Returns:</h3>
|
|
<ol>
|
|
|
|
<span class="types"><span class="type">iterator</span></span>
|
|
iterator over the entities in this system
|
|
</ol>
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:clear"></a>
|
|
<strong>System:clear ()</strong>
|
|
</dt>
|
|
<dd>
|
|
Remove every entity from the system and its subsystems.
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:update"></a>
|
|
<strong>System:update (dt)</strong>
|
|
</dt>
|
|
<dd>
|
|
Try to update the system and its subsystems. Should be called on every game update.</p>
|
|
|
|
<p> Subsystems are updated after their parent system.
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
<h3>Parameters:</h3>
|
|
<ul>
|
|
<li><span class="parameter">dt</span>
|
|
<span class="types"><span class="type">number</span></span>
|
|
delta-time since last update
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:draw"></a>
|
|
<strong>System:draw ()</strong>
|
|
</dt>
|
|
<dd>
|
|
Try to draw the system and its subsystems. Should be called on every game draw.</p>
|
|
|
|
<p> Subsystems are drawn after their parent system.
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:callback"></a>
|
|
<strong>System:callback (name, e, ...)</strong>
|
|
</dt>
|
|
<dd>
|
|
Trigger a custom callback on a single entity. </p>
|
|
|
|
<p> This will call the <code>System:name(c, e, …)</code> method in this system and its subsystems,
|
|
if the method exists and the entity is in the system. <code>c</code> is the system <a href="#Entity.Component">component</a>
|
|
associated with the current system, and <code>e</code> is the <a href="../modules/ecs.html#Entity_objects">Entity</a>.</p>
|
|
|
|
<p> Think of it as a way to perform custom callbacks issued from an entity event, similar to <a href="../modules/ecs.html#System:onAdd">System:onAdd</a>.
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
<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 callback
|
|
</li>
|
|
<li><span class="parameter">e</span>
|
|
<span class="types"><a class="type" href="../modules/ecs.html#Entity_objects">Entity</a></span>
|
|
the entity to perform the callback on
|
|
</li>
|
|
<li><span class="parameter">...</span>
|
|
other arguments to pass to the callback
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:emit"></a>
|
|
<strong>System:emit (name, ...)</strong>
|
|
</dt>
|
|
<dd>
|
|
Emit an event on the system. </p>
|
|
|
|
<p> This will call the <code>System:name(…)</code> method in this system and its subsystems,
|
|
if the method exists.</p>
|
|
|
|
<p> Think of it as a way to perform custom callbacks issued from a general event, similar to <a href="../modules/ecs.html#System:onUpdate">System:onUpdate</a>.</p>
|
|
|
|
<p> The called methods may return a string value to affect the event propagation behaviour:</p>
|
|
|
|
<ul>
|
|
<li>if a callback returns <code>"stop"</code>, the event will not be propagated to the subsystems.</li>
|
|
<li>if a callback returns <code>"capture"</code>, the event will not be propagated to the subsystems <em>and</em>
|
|
its sibling systems (i.e. completely stop the propagation of the event).</li>
|
|
</ul>
|
|
|
|
|
|
<p> <code>"stop"</code> would be for example used to disable some behaviour in the system and its subsystems (like <code>active = false</code> can
|
|
disable <a href="../modules/ecs.html#System:onUpdate">System:onUpdate</a> behaviour on the system and its subsystems).</p>
|
|
|
|
<p> <code>"capture"</code> would be for example used to prevent other systems from handling the event (for example to make sure an
|
|
input event is handled only once by a single system).
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
<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 callback
|
|
</li>
|
|
<li><span class="parameter">...</span>
|
|
other arguments to pass to the callback
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:destroy"></a>
|
|
<strong>System:destroy ()</strong>
|
|
</dt>
|
|
<dd>
|
|
Remove all the entities and subsystems in this system.
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</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 2021-12-26 18:43:30 </i>
|
|
</div> <!-- id="about" -->
|
|
</div> <!-- id="container" -->
|
|
</body>
|
|
</html>
|