From 86373c98de69e7ef0349512bc0df9fe6a12bac14 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89tienne=20Reuh=20Fildadut?= Date: Mon, 27 Dec 2021 13:16:08 +0100 Subject: [PATCH] ecs: always pass entity as first arguments in callback for consistency, add System.component to set system component name independently from System.name --- docs/index.html | 2 +- docs/modules/asset.html | 2 +- docs/modules/ecs.html | 99 ++++++++++++++++++++++------------ docs/modules/ldtk.html | 6 +-- docs/modules/scene.html | 2 +- docs/modules/signal.html | 2 +- docs/modules/timer.html | 2 +- docs/modules/ubiquitousse.html | 2 +- docs/modules/util.html | 2 +- docs/topics/LICENSE.html | 2 +- docs/topics/README.md.html | 2 +- ecs/ecs.can | 62 ++++++++++++--------- 12 files changed, 113 insertions(+), 72 deletions(-) diff --git a/docs/index.html b/docs/index.html index bb97875..01d644d 100644 --- a/docs/index.html +++ b/docs/index.html @@ -108,7 +108,7 @@
generated by LDoc 1.4.6 -Last updated 2021-12-27 12:20:29 +Last updated 2021-12-27 13:15:05
diff --git a/docs/modules/asset.html b/docs/modules/asset.html index 49f12be..d7c9892 100644 --- a/docs/modules/asset.html +++ b/docs/modules/asset.html @@ -334,7 +334,7 @@
generated by LDoc 1.4.6 -Last updated 2021-12-27 12:20:29 +Last updated 2021-12-27 13:15:05
diff --git a/docs/modules/ecs.html b/docs/modules/ecs.html index 3801842..ca2ed1e 100644 --- a/docs/modules/ecs.html +++ b/docs/modules/ecs.html @@ -92,7 +92,7 @@ local ecs = require("ubiquitousse.ecs") local talkingSystem = { filter = { "name", "mass", "phrase" }, - process = function(self, c, e, dt) + 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 @@ -166,6 +166,10 @@ end The system and its subsystems will only draw if this is true. + System.component + Name of the system component. + + System.default Defaults value to put into the entities’s system component when they are added. @@ -181,11 +185,11 @@ end Called when adding an entity to this system determining its order. - System:onAdd (c, e) [callback] + System:onAdd (e, c) [callback] Called when adding an entity to the system. - System:onRemove (c, e) [callback] + System:onRemove (e, c) [callback] Called when removing an entity from the system. @@ -213,11 +217,11 @@ end Called when drawing the system. - System:process (c, e, dt) [callback] + System:process (e, c, dt) [callback] Called when updating the system, for every entity the system contains. - System:render (c, e) [callback] + System:render (e, c) [callback] Called when drawing the system, for every entity the system contains. @@ -459,7 +463,8 @@ whatever you want, and ideally each component should store the data for so you are free to handle them as you want in your systems or elsewhere.

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). +that is, the component in the entity that is named like System.component (or System.name 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.

@@ -486,9 +491,9 @@ that is, the component in the entity that has the same name as the system (if it filter = "sprite", -- process entities that have a "sprite" component -- systems callbacks that are called per-entity often give you the system component as an argument -- the system component is the component with the same name as the system, thus here the sprite component - render = function(self, component, entity) + render = function(self, entity, component) -- component == entity.sprite - component:draw() + draw(component) end } @@ -532,12 +537,12 @@ avoid repeating your filters or allow controlling several system from a single p systems = { animated }, -- subsystems: they only operate on entities already filtered by this system (on top of their own filtering) -- Called when an entity is added to this system. - onAdd = function(self, component, entity) + onAdd = function(self, entity, component) print("Added an entity, entity count in the system:", self.entityCount) -- self refer to the instancied system end, -- Called when the system is updated, for every entity the system - process = function(self, component, entity, dt) + process = function(self, entity, component, dt) -- processing... end } @@ -583,8 +588,8 @@ avoid repeating your filters or allow controlling several system from a single p
Name of the system. - Used to create a field with the system’s name in world.s and determine the associated system component. - If not set, the system will not appear in world.s and gives nil instead of the system component in callbacks.

+ Used to create a field with the system’s name in world.s and determine the associated system component if System.component is not set. + If not set, the system will not appear in world.s.

Do not change after system instanciation. @@ -694,6 +699,30 @@ avoid repeating your filters or allow controlling several system from a single p +

+
+ + System.component +
+
+ Name of the system component. + Used to determine the associated system component. + If not set, this will fall back to System.name. If this is also not set, then we will give nil instead of the system component in callbacks. + + +

Type:

+
    +
  • string
    • +
  • nil if no name
    • +
+ + + + + + + +
@@ -706,7 +735,7 @@ avoid repeating your filters or allow controlling several system from a single p Metatables will be preserved during the copy but not copied themselves.

Changing this will not affect entities already in the system. - Doesn’t have any effect if the system doesn’t have a name. + Doesn’t have any effect if the system doesn’t have a component name.

Type:

@@ -825,7 +854,7 @@ avoid repeating your filters or allow controlling several system from a single p
- System:onAdd (c, e) [callback] + System:onAdd (e, c) [callback]
Called when adding an entity to the system. @@ -837,14 +866,14 @@ avoid repeating your filters or allow controlling several system from a single p

Parameters:

    -
  • c - Component - the entity’s system component -
  • e Entity the entity table
    • +
  • c + Component + the entity’s system component, if any +
@@ -854,7 +883,7 @@ avoid repeating your filters or allow controlling several system from a single p
- System:onRemove (c, e) [callback] + System:onRemove (e, c) [callback]
Called when removing an entity from the system. @@ -866,14 +895,14 @@ avoid repeating your filters or allow controlling several system from a single p

Parameters:

    -
  • c - Component - the entity’s system component -
  • e Entity the entity table
    • +
  • c + Component + the entity’s system component, if any +
@@ -1012,7 +1041,7 @@ avoid repeating your filters or allow controlling several system from a single p
- System:process (c, e, dt) [callback] + System:process (e, c, dt) [callback]
Called when updating the system, for every entity the system contains. Called after System:onUpdate was called on the system. @@ -1024,14 +1053,14 @@ avoid repeating your filters or allow controlling several system from a single p

Parameters:

    -
  • c - Component - the entity’s system component -
  • e Entity the entity table
    • +
  • c + Component + the entity’s system component, if any +
  • dt number delta-time since last update @@ -1045,7 +1074,7 @@ avoid repeating your filters or allow controlling several system from a single p
- System:render (c, e) [callback] + System:render (e, c) [callback]
Called when drawing the system, for every entity the system contains. Called after System:onDraw was called on the system. @@ -1057,14 +1086,14 @@ avoid repeating your filters or allow controlling several system from a single p

Parameters:

    -
  • c - Component - the entity’s system component -
  • e Entity the entity table
    • +
  • c + Component + the entity’s system component, if any +
@@ -1493,7 +1522,7 @@ avoid repeating your filters or allow controlling several system from a single p
Trigger a custom callback on a single entity.

-

This will call the System:name(c, e, …) method in this system and its subsystems, +

This will call the System:name(e, c, …) method in this system and its subsystems, if the method exists and the entity is in the system. c is the system component associated with the current system, and e is the Entity.

@@ -1597,7 +1626,7 @@ its sibling systems (i.e. completely stop the propagation of the event).
generated by LDoc 1.4.6 -Last updated 2021-12-27 12:20:29 +Last updated 2021-12-27 13:15:05
diff --git a/docs/modules/ldtk.html b/docs/modules/ldtk.html index 259ab81..1557a66 100644 --- a/docs/modules/ldtk.html +++ b/docs/modules/ldtk.html @@ -1754,7 +1754,7 @@ end Level background.

If there is a background image, background.image contains a table {image=image, x=number, y=number, sx=number, sy=number} - where image is the LÖVE image (or image filepath if LÖVE not available) x and y are the top-left position, + where image is the LÖVE image (or image filepath if LÖVE not available) x and y are the top-left position, and sx and sy the horizontal and vertical scale factors. @@ -1829,7 +1829,7 @@ end

  • Enum are converted into a Lua string giving the currently selected enum value.
  • Filepath are converted into a Lua string giving the file path.
  • Arrays are converted into a Lua table with the elements in it as a list.
    • -
  • Points are converted into a Lua table with the fields x and y: { x=number, y=number }.
    • +
  • Points are converted into a Lua table with the fields x and y: { x=number, y=number }.
  • Colors are converted into a Lua table with the red, green and blue components in [0-1] as a list: {r,g,b}.
    • @@ -1855,7 +1855,7 @@ end
    generated by LDoc 1.4.6 -Last updated 2021-12-27 12:20:29 +Last updated 2021-12-27 13:15:05
    diff --git a/docs/modules/scene.html b/docs/modules/scene.html index 90c755f..0747b3c 100644 --- a/docs/modules/scene.html +++ b/docs/modules/scene.html @@ -702,7 +702,7 @@
    generated by LDoc 1.4.6 -Last updated 2021-12-27 12:20:29 +Last updated 2021-12-27 13:15:05
    diff --git a/docs/modules/signal.html b/docs/modules/signal.html index 2dd7a3f..4508ac2 100644 --- a/docs/modules/signal.html +++ b/docs/modules/signal.html @@ -414,7 +414,7 @@
    generated by LDoc 1.4.6 -Last updated 2021-12-27 12:20:29 +Last updated 2021-12-27 13:15:05
    diff --git a/docs/modules/timer.html b/docs/modules/timer.html index 1195cda..f79896b 100644 --- a/docs/modules/timer.html +++ b/docs/modules/timer.html @@ -1153,7 +1153,7 @@
    generated by LDoc 1.4.6 -Last updated 2021-12-27 12:20:29 +Last updated 2021-12-27 13:15:05
    diff --git a/docs/modules/ubiquitousse.html b/docs/modules/ubiquitousse.html index 407cc98..ec9254b 100644 --- a/docs/modules/ubiquitousse.html +++ b/docs/modules/ubiquitousse.html @@ -362,7 +362,7 @@
    generated by LDoc 1.4.6 -Last updated 2021-12-27 12:20:29 +Last updated 2021-12-27 13:15:05
    diff --git a/docs/modules/util.html b/docs/modules/util.html index 5a882df..1a0545c 100644 --- a/docs/modules/util.html +++ b/docs/modules/util.html @@ -784,7 +784,7 @@
    generated by LDoc 1.4.6 -Last updated 2021-12-27 12:20:29 +Last updated 2021-12-27 13:15:05
    diff --git a/docs/topics/LICENSE.html b/docs/topics/LICENSE.html index f5f93a0..7ba8a24 100644 --- a/docs/topics/LICENSE.html +++ b/docs/topics/LICENSE.html @@ -64,7 +64,7 @@
    generated by LDoc 1.4.6 -Last updated 2021-12-27 12:20:29 +Last updated 2021-12-27 13:15:05
    diff --git a/docs/topics/README.md.html b/docs/topics/README.md.html index a769017..995714e 100644 --- a/docs/topics/README.md.html +++ b/docs/topics/README.md.html @@ -71,7 +71,7 @@
    generated by LDoc 1.4.6 -Last updated 2021-12-27 12:20:29 +Last updated 2021-12-27 13:15:05
    diff --git a/ecs/ecs.can b/ecs/ecs.can index 6890056..55761ff 100644 --- a/ecs/ecs.can +++ b/ecs/ecs.can @@ -28,7 +28,7 @@ local ecs = require("ubiquitousse.ecs") local talkingSystem = { filter = { "name", "mass", "phrase" }, - process = function(self, c, e, dt) + 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 @@ -74,7 +74,8 @@ This library does not do any kind of special processing by itself on the entity so you are free to handle them as you want in your systems or elsewhere. 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). +that is, the component in the entity that is named like `System.component` (or `System.name` 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. @doc Component @usage @@ -90,9 +91,9 @@ local sprite = { filter = "sprite", -- process entities that have a "sprite" component -- systems callbacks that are called per-entity often give you the system component as an argument -- the system component is the component with the same name as the system, thus here the sprite component - render = function(self, component, entity) + render = function(self, entity, component) -- component == entity.sprite - component:draw() + draw(component) end } ]]-- @@ -187,12 +188,12 @@ local sprite = { systems = { animated }, -- subsystems: they only operate on entities already filtered by this system (on top of their own filtering) -- Called when an entity is added to this system. - onAdd = function(self, component, entity) + onAdd = function(self, entity, component) print("Added an entity, entity count in the system:", self.entityCount) -- self refer to the instancied system end, -- Called when the system is updated, for every entity the system - process = function(self, component, entity, dt) + process = function(self, entity, component, dt) -- processing... end } @@ -221,8 +222,8 @@ let system_mt = { -- @doc modifiable --- Name of the system. - -- Used to create a field with the system's name in `world.s` and determine the associated system component. - -- If not set, the system will not appear in `world.s` and gives `nil` instead of the system component in callbacks. + -- Used to create a field with the system's name in `world.s` and determine the associated system component if `System.component` is not set. + -- If not set, the system will not appear in `world.s`. -- -- Do not change after system instanciation. -- @ftype string @@ -251,13 +252,19 @@ let system_mt = { -- @ftype boolean visible = true, + --- Name of the system component. + -- Used to determine the associated system component. + -- If not set, this will fall back to `System.name`. If this is also not set, then we will give `nil` instead of the system component in callbacks. + -- @ftype string + -- @ftype nil if no name + component = nil, --- Defaults value to put into the entities's system component when they are added. -- -- If this is table, will recursively fill missing values. -- Metatables will be preserved during the copy but not copied themselves. -- -- Changing this will not affect entities already in the system. - -- Doesn't have any effect if the system doesn't have a name. + -- Doesn't have any effect if the system doesn't have a component name. -- @ftype any -- @ftype nil if no default default = nil, @@ -297,14 +304,14 @@ let system_mt = { --- Called when adding an entity to the system. -- @callback - -- @tparam Component c the entity's system component -- @tparam Entity e the entity table - onAdd = :(c, e) end, + -- @tparam Component c the entity's system component, if any + onAdd = :(e, c) end, --- Called when removing an entity from the system. -- @callback - -- @tparam Component c the entity's system component -- @tparam Entity e the entity table - onRemove = :(c, e) end, + -- @tparam Component c the entity's system component, if any + onRemove = :(e, c) end, --- Called when the system is instancied, before any call to `System:onAddToWorld` (including other systems in the world). -- @callback onInstance = :() end, @@ -328,15 +335,15 @@ let system_mt = { onDraw = :() end, --- Called when updating the system, for every entity the system contains. Called after `System:onUpdate` was called on the system. -- @callback - -- @tparam Component c the entity's system component -- @tparam Entity e the entity table + -- @tparam Component c the entity's system component, if any -- @number dt delta-time since last update - process = :(c, e, dt) end, + process = :(e, c, dt) end, --- Called when drawing the system, for every entity the system contains. Called after `System:onDraw` was called on the system. -- @callback - -- @tparam Component c the entity's system component -- @tparam Entity e the entity table - render = :(c, e) end, + -- @tparam Component c the entity's system component, if any + render = :(e, c) end, --- Read-only fields. -- @@ -395,8 +402,8 @@ let system_mt = { add = :(e, ...) if e ~= nil and not @_previous[e] and @filter(e) then -- copy default system component - if @name and @default then - copy({ [@name] = @default }, e) + if @component and @default then + copy({ [@component] = @default }, e) end -- add to linked list if @_first == nil then @@ -426,7 +433,7 @@ let system_mt = { end -- notify addition @entityCount += 1 - @onAdd(e[@name], e) + @onAdd(e, e[@component]) -- add to subsystems (if it wasn't immediately removed in onAdd) if @_previous[e] then for _, s in ipairs(@systems) do @@ -477,7 +484,7 @@ let system_mt = { -- notify removal @_previous[e] = nil @entityCount -= 1 - @onRemove(e[@name], e) + @onRemove(e, e[@component]) end end if ... then @@ -613,7 +620,7 @@ let system_mt = { @onUpdate(dt) if @process ~= system_mt.process then for e in @iter() do - @process(e[@name], e, dt) + @process(e, e[@component], dt) end end for _, s in ipairs(@systems) do @@ -632,7 +639,7 @@ let system_mt = { @onDraw() if @render ~= system_mt.render then for e in @iter() do - @render(e[@name], e) + @render(e, e[@component]) end end for _, s in ipairs(@systems) do @@ -642,7 +649,7 @@ let system_mt = { end, --- Trigger a custom callback on a single entity. -- - -- This will call the `System:name(c, e, ...)` method in this system and its subsystems, + -- This will call the `System:name(e, c, ...)` method in this system and its subsystems, -- if the method exists and the entity is in the system. `c` is the system [component](#Entity.Component) -- associated with the current system, and `e` is the `Entity`. -- @@ -653,7 +660,7 @@ let system_mt = { callback = :(name, e, ...) -- call callback if @_previous[e] and @[name] then - @[name](@, e[@name], e, ...) + @[name](@, e, e[@component], ...) end -- callback on subsystems (if it wasn't removed during the callback) if @_previous[e] then @@ -732,6 +739,7 @@ let recInstanciateSystems = (world, systems) end end }) + -- create filter if type(s.filter) == "string" then system.filter = (_, e) return e[s.filter] ~= nil end elseif type(s.filter) == "table" then @@ -743,6 +751,10 @@ let recInstanciateSystems = (world, systems) system.filter = alwaysFalse end end + -- system component fallback on system name + if not s.component and s.name then + s.component = s.name + end -- add system table.insert(t, system) if s.name then