mirror of
https://github.com/Reuh/ubiquitousse.git
synced 2025-10-27 09:09:30 +00:00
1736 lines
52 KiB
HTML
1736 lines
52 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/input.html">input</a></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, e, c, 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.component">System.component</a></td>
|
|
<td class="summary">Name of the system component.</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 (e, c) <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 (e, c) <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 (e, c, 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 (e, c) <sup><em>[callback]</em></sup></a></td>
|
|
<td class="summary">Called when drawing the system, for every entity the system contains.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System:onUpdateEnd">System:onUpdateEnd (dt) <sup><em>[callback]</em></sup></a></td>
|
|
<td class="summary">Called after updating the system.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name" nowrap><a href="#System:onDrawEnd">System:onDrawEnd () <sup><em>[callback]</em></sup></a></td>
|
|
<td class="summary">Called after drawing the system.</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:get">System:get (i)</a></td>
|
|
<td class="summary">Get the <code>i</code>th entity in the system.</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. </p>
|
|
|
|
<p> When suspending and resuming the scene, the <code>onSuspend</code> and <code>onResume</code> events will be emitted on the ECS world.</p>
|
|
|
|
<p> Note that since <code>uqt.scene</code> use <a href="https://www.lua.org/manual/5.1/manual.html#pdf-require">require</a> to load the scenes, the scenes files will be cached – including variables defined in them.
|
|
So if you store the entity list directly in a variable in the scene file, it will be reused every time the scene is entered, and will thus
|
|
be shared among the different execution of the scene. This may be problematic if an entity is modified by one scene instance, as it will affect others
|
|
(this should not be a problem with systems due to system instanciation). To avoid this issue, instead you would typically define entities through a
|
|
function that will recreate the entities on every scene load.
|
|
|
|
<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/function</a></span>
|
|
list of systems to add to the world. If it is a function, it will be executed every time we enter the scene and returns the list of systems.
|
|
(<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/function</a></span>
|
|
list of entities to add to the world. If it is a function, it will be executed every time we enter the scene and returns the list of entities.
|
|
(<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 is named like <a href="../modules/ecs.html#System.component">System.component</a> (or <a href="../modules/ecs.html#System.name">System.name</a> if it is not set). Though there’s no problem if there’s no system
|
|
component or if it doesn’t exist in the entity.
|
|
</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, entity, component)
|
|
<span class="comment">-- component == entity.sprite
|
|
</span> draw(component)
|
|
<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, entity, component)
|
|
<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, entity, component, 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 <a href="../modules/ecs.html#System.component">System.component</a> is not set.
|
|
If not set, the system will not appear in <code>world.s</code>.</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.component"></a>
|
|
<strong>System.component</strong>
|
|
</dt>
|
|
<dd>
|
|
Name of the system component.
|
|
Used to determine the associated system component.
|
|
If not set, this will fall back to <a href="../modules/ecs.html#System.name">System.name</a>. If this is also not set, then we will give <code>nil</code> instead of the system component in callbacks.
|
|
|
|
</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.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 component 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 <a href="../modules/ecs.html#all">ecs.all</a>.</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 (e, c) <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">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">c</span>
|
|
<span class="types"><a class="type" href="../modules/ecs.html#Entity.Component">Component</a></span>
|
|
the entity’s system component, if any
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:onRemove"></a>
|
|
<strong>System:onRemove (e, c) <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">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">c</span>
|
|
<span class="types"><a class="type" href="../modules/ecs.html#Entity.Component">Component</a></span>
|
|
the entity’s system component, if any
|
|
</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.
|
|
Called before any call to <a href="../modules/ecs.html#System:process">System:process</a> or call to subsystems.
|
|
|
|
</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.
|
|
Called before any call to <a href="../modules/ecs.html#System:draw">System:draw</a> or call to subsystems.
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:process"></a>
|
|
<strong>System:process (e, c, 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, and before any call to subsystems.
|
|
|
|
</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>
|
|
the entity table
|
|
</li>
|
|
<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, if any
|
|
</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 (e, c) <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, and before any call to subsystems.
|
|
|
|
</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>
|
|
the entity table
|
|
</li>
|
|
<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, if any
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
|
|
</dd>
|
|
<dt>
|
|
<a name = "System:onUpdateEnd"></a>
|
|
<strong>System:onUpdateEnd (dt) <sup><em>[callback]</em></sup></strong>
|
|
</dt>
|
|
<dd>
|
|
Called after updating the system.
|
|
Called after <a href="../modules/ecs.html#System:onDraw">System:onDraw</a>, <a href="../modules/ecs.html#System:process">System:process</a> and calls to subsystems.
|
|
|
|
</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:onDrawEnd"></a>
|
|
<strong>System:onDrawEnd () <sup><em>[callback]</em></sup></strong>
|
|
</dt>
|
|
<dd>
|
|
Called after drawing the system.
|
|
Called after <a href="../modules/ecs.html#System:onUpdate">System:onUpdate</a>, <a href="../modules/ecs.html#System:render">System:render</a> and calls to subsystems.
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</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:get"></a>
|
|
<strong>System:get (i)</strong>
|
|
</dt>
|
|
<dd>
|
|
Get the <code>i</code>th entity in the system.
|
|
This is a simple wrapper around <a href="../modules/ecs.html#System:iter">iter</a>; it <em>will</em> iterate over all the entities in the system in order until we reach the desired one.
|
|
Complexity: O(i)
|
|
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
</ul>
|
|
|
|
<h3>Parameters:</h3>
|
|
<ul>
|
|
<li><span class="parameter">i</span>
|
|
<span class="types"><span class="type">number</span></span>
|
|
the index of the entity
|
|
</li>
|
|
</ul>
|
|
|
|
<h3>Returns:</h3>
|
|
<ol>
|
|
|
|
<span class="types"><a class="type" href="../modules/ecs.html#Entity_objects">Entity</a></span>
|
|
the entity; <code>nil</code> if there is no such entity in the 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(e, c, …)</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 2022-09-16 20:07:07 </i>
|
|
</div> <!-- id="about" -->
|
|
</div> <!-- id="container" -->
|
|
</body>
|
|
</html>
|