Merge branch 'dev'

README.md

@@ -33,6 +33,15 @@ ON_SET :: fragment
 ON_ASSIGN :: fragment
 ON_INSERT :: fragment
 ON_REMOVE :: fragment
+
+PHASE :: fragment
+AFTER :: fragment
+
+QUERY :: fragment
+EXECUTE :: fragment
+
+PROLOGUE :: fragment
+EPILOGUE :: fragment
 ```
 
 ## Functions
@@ -82,7 +91,9 @@ chunk :: fragment... -> chunk?, entity[]?
 select :: chunk, fragment... -> component[]...
 
 each :: entity -> {each_state? -> fragment?, component?}, each_state?
-execute :: query -> {execute_state? -> chunk?, entity[]?}, execute_state?
+execute :: query -> {execute_state? -> chunk?, entity[]?, integer?}, execute_state?
+
+process :: phase... -> ()
 ```
 
 ```
@@ -116,4 +127,20 @@ query_builder:exclude :: fragment... -> query_builder
 query_builder:build :: query, boolean
 ```
 
+```
+phase :: phase_builder
+phase_builder:build :: phase, boolean
+```
+
+```
+system :: system_builder
+system_builder:phase :: phase -> system_builder
+system_builder:after :: system... -> system_builder
+system_builder:query :: query -> system_builder
+system_builder:execute :: {chunk, entity[], integer} -> system_builder
+system_builder:prologue :: {} -> system_builder
+system_builder:epilogue :: {} -> system_builder
+system_builder:build :: system, boolean
+```
+
 ## [License (MIT)](./LICENSE.md)

ROADMAP.md

@@ -2,12 +2,19 @@
 
 ## Backlog
 
-- INDEX fragment trait
-- phase/pipeline addon
+- add destroing policies (fragments, phases, systems)
+
+## Known issues
+
+- destroying of fragments leave chunks with dead fragments (destroing policies)
+- destroying of systems can leave dead systems in the library state (destroying policies)
+- destroying of phases can leave dead phases in the library state (destroying policies)
 
 ## After first release
 
+- add system groups
 - auto chunk count reducing
+- add INDEX fragment trait
 - add REQUIRES fragment trait
 - use compact prefix-tree for chunks
 - set/assign/insert/remove/clear/destroy for lists

develop/example.lua

@@ -1 +1,131 @@
+---@diagnostic disable: unused-local
+
 local evo = require 'evolved'
+
+---@class evolved.vector2
+---@field x number
+---@field y number
+
+---@param x number
+---@param y number
+---@return evolved.vector2
+---@nodiscard
+local function vector2(x, y)
+    ---@type evolved.vector2
+    return { x = x, y = y }
+end
+
+local phases = {
+    awake = evo.phase():build(),
+    physics = evo.phase():build(),
+    graphics = evo.phase():build(),
+    shutdown = evo.phase():build(),
+}
+
+local singles = {
+    delta_time = evo.fragment():single(0.016):build(),
+    physics_gravity = evo.fragment():single(vector2(0, 9.81)):build(),
+}
+
+local fragments = {
+    force = evo.fragment():build(),
+    position = evo.fragment():build(),
+    velocity = evo.fragment():build(),
+}
+
+local queries = {
+    physics_bodies = evo.query()
+        :include(fragments.force, fragments.position, fragments.velocity)
+        :build(),
+}
+
+local awake_system = evo.system()
+    :phase(phases.awake)
+    :prologue(function()
+        print '-= | Awake | =-'
+        evo.entity()
+            :set(fragments.force, vector2(0, 0))
+            :set(fragments.position, vector2(0, 0))
+            :set(fragments.velocity, vector2(0, 0))
+            :build()
+    end):build()
+
+local integrate_forces_system = evo.system()
+    :phase(phases.physics)
+    :query(queries.physics_bodies)
+    :execute(function(chunk, entities, entity_count)
+        ---@type number, evolved.vector2
+        local delta_time, physics_gravity =
+            evo.get(singles.delta_time, singles.delta_time),
+            evo.get(singles.physics_gravity, singles.physics_gravity)
+
+        ---@type evolved.vector2[], evolved.vector2[]
+        local forces, velocities = evo.select(chunk,
+            fragments.force, fragments.velocity)
+
+        for i = 1, entity_count do
+            local force, velocity = forces[i], velocities[i]
+
+            velocity.x = velocity.x + (physics_gravity.x + force.x) * delta_time
+            velocity.y = velocity.y + (physics_gravity.y + force.y) * delta_time
+        end
+    end):build()
+
+local integrate_velocities_system = evo.system()
+    :phase(phases.physics)
+    :after(integrate_forces_system)
+    :query(queries.physics_bodies)
+    :execute(function(chunk, entities, entity_count)
+        ---@type number
+        local delta_time =
+            evo.get(singles.delta_time, singles.delta_time)
+
+        ---@type evolved.vector2[], evolved.vector2[], evolved.vector2[]
+        local forces, positions, velocities = evo.select(chunk,
+            fragments.force, fragments.position, fragments.velocity)
+
+        for i = 1, entity_count do
+            local force, position, velocity = forces[i], positions[i], velocities[i]
+
+            position.x = position.x + velocity.x * delta_time
+            position.y = position.y + velocity.y * delta_time
+
+            force.x = 0
+            force.y = 0
+        end
+    end):build()
+
+local graphics_system = evo.system()
+    :phase(phases.graphics)
+    :query(queries.physics_bodies)
+    :execute(function(chunk, entities, entity_count)
+        ---@type evolved.vector2[]
+        local positions = evo.select(chunk,
+            fragments.position)
+
+        for i = 1, entity_count do
+            local entity, position = entities[i], positions[i]
+
+            print(string.format(
+                '|-> {entity %d} at {%.4f, %.4f}',
+                entity, position.x, position.y))
+        end
+    end):build()
+
+local shutdown_system = evo.system()
+    :phase(phases.shutdown)
+    :epilogue(function()
+        print '-= | Shutdown | =-'
+        evo.batch_destroy(queries.physics_bodies)
+    end):build()
+
+do
+    evo.process(phases.awake)
+
+    for _ = 1, 10 do
+        evo.process(phases.physics)
+        evo.process(phases.graphics)
+    end
+
+    evo.process(phases.shutdown)
+end

develop/untests.lua

@@ -2524,7 +2524,8 @@ do
     ---@return evolved.entity[]
     local function collect_entities(q)
         local entities = {}
-        for _, es in evo.execute(q) do
+        for _, es, es_count in evo.execute(q) do
+            assert(#es == es_count)
             for _, e in ipairs(es) do
                 entities[#entities + 1] = e
             end
@@ -6525,3 +6526,23 @@ do
         assert(evo.has(f, f) and evo.get(f, f) == 42)
     end
 end
+
+do
+    local s1 = evo.system():build()
+    do
+        local after = evo.get(s1, evo.AFTER)
+        assert(after == nil)
+    end
+
+    local s2 = evo.system():after(s1):build()
+    do
+        local after = evo.get(s2, evo.AFTER)
+        assert(#after == 1 and after[1] == s1)
+    end
+
+    local s3 = evo.system():after(s1, s2):build()
+    do
+        local after = evo.get(s3, evo.AFTER)
+        assert(#after == 2 and after[1] == s1 and after[2] == s2)
+    end
+end