Merge pull request #6 from BlackMATov/dev

Dev

README.md

@@ -29,9 +29,16 @@
 ```
 TAG :: fragment
 NAME :: fragment
+
+UNIQUE :: fragment
+EXPLICIT :: fragment
+
 DEFAULT :: fragment
 DUPLICATE :: fragment
 
+PREFAB :: fragment
+DISABLED :: fragment
+
 INCLUDES :: fragment
 EXCLUDES :: fragment
 
@@ -48,8 +55,6 @@ EXECUTE :: fragment
 PROLOGUE :: fragment
 EPILOGUE :: fragment
 
-DISABLED :: fragment
-
 DESTROY_POLICY :: fragment
 DESTROY_POLICY_DESTROY_ENTITY :: id
 DESTROY_POLICY_REMOVE_FRAGMENT :: id
@@ -66,17 +71,20 @@ unpack :: id -> integer, integer
 defer :: boolean
 commit :: boolean
 
-is_alive :: chunk | entity -> boolean
+spawn :: <fragment, component>? -> entity
-is_alive_all :: chunk | entity... -> boolean
+clone :: entity -> <fragment, component>? -> entity
-is_alive_any :: chunk | entity... -> boolean
 
-is_empty :: chunk | entity -> boolean
+alive :: entity -> boolean
-is_empty_all :: chunk | entity... -> boolean
+alive_all :: entity... -> boolean
-is_empty_any :: chunk | entity... -> boolean
+alive_any :: entity... -> boolean
 
-has :: chunk | entity, fragment -> boolean
+empty :: entity -> boolean
-has_all :: chunk | entity, fragment... -> boolean
+empty_all :: entity... -> boolean
-has_any :: chunk | entity, fragment... -> boolean
+empty_any :: entity... -> boolean
+
+has :: entity, fragment -> boolean
+has_all :: entity, fragment... -> boolean
+has_any :: entity, fragment... -> boolean
 
 get :: entity, fragment...  -> component...
 
@@ -85,67 +93,84 @@ remove :: entity, fragment... -> ()
 clear :: entity... -> ()
 destroy :: entity... -> ()
 
-multi_set :: entity, fragment[], component[]? -> ()
-multi_remove :: entity, fragment[] -> ()
-
 batch_set :: query, fragment, component -> ()
 batch_remove :: query, fragment... -> ()
 batch_clear :: query... -> ()
 batch_destroy :: query... -> ()
 
-batch_multi_set :: query, fragment[], component[]? -> ()
-batch_multi_remove :: query, fragment[] -> ()
-
-chunk :: fragment, fragment... -> chunk, entity[], integer
-
-entities :: chunk -> entity[], integer
-fragments :: chunk -> fragment[], integer
-components :: chunk, fragment... -> component[]...
-
 each :: entity -> {each_state? -> fragment?, component?}, each_state?
 execute :: query -> {execute_state? -> chunk?, entity[]?, integer?}, execute_state?
 
 process :: system... -> ()
 
-spawn_at :: chunk?, fragment[]?, component[]? -> entity
-spawn_as :: entity?, fragment[]?, component[]? -> entity
-spawn_with :: fragment[]?, component[]? -> entity
-
 debug_mode :: boolean -> ()
 collect_garbage :: ()
 ```
 
+## Chunk
+
+```
+chunk :: fragment, fragment... -> chunk, entity[], integer
+
+chunk:alive :: boolean
+chunk:empty :: boolean
+
+chunk:has :: fragment -> boolean
+chunk:has_all :: fragment... -> boolean
+chunk:has_any :: fragment... -> boolean
+
+chunk:entities :: entity[], integer
+chunk:fragments :: fragment[], integer
+chunk:components :: fragment... -> component[]...
+```
+
 ## Builder
 
 ```
 builder :: builder
+
+builder:spawn :: entity
+builder:clone :: entity -> entity
+
 builder:has :: fragment -> boolean
 builder:has_all :: fragment... -> boolean
 builder:has_any :: fragment... -> boolean
+
 builder:get :: fragment... -> component...
+
 builder:set :: fragment, component -> builder
 builder:remove :: fragment... -> builder
 builder:clear :: builder
+
 builder:tag :: builder
 builder:name :: string -> builder
-builder:prefab :: entity -> builder
+
-builder:single :: component -> builder
+builder:unique :: builder
+builder:explicit :: builder
+
 builder:default :: component -> builder
 builder:duplicate :: {component -> component} -> builder
+
+builder:prefab :: builder
+builder:disabled :: builder
+
 builder:include :: fragment... -> builder
 builder:exclude :: fragment... -> builder
+
 builder:on_set :: {entity, fragment, component, component?} -> builder
 builder:on_assign :: {entity, fragment, component, component} -> builder
 builder:on_insert :: {entity, fragment, component} -> builder
 builder:on_remove :: {entity, fragment} -> builder
+
 builder:group :: system -> builder
+
 builder:query :: query -> builder
 builder:execute :: {chunk, entity[], integer} -> builder
+
 builder:prologue :: {} -> builder
 builder:epilogue :: {} -> builder
-builder:disabled :: builder
+
 builder:destroy_policy :: id -> builder
-builder:build :: boolean -> entity
 ```
 
 ## [License (MIT)](./LICENSE.md)

ROADMAP.md

@@ -2,10 +2,6 @@
 
 ## Backlog
 
-- builders should be rewritten :/
-- add PREFAB entity trait
-- is/has_all/any for lists?
-
 ## After first release
 
 - cached queries

develop/all.lua

@@ -5,5 +5,11 @@ require 'develop.usbench'
 
 local basics = require 'develop.basics'
 
+print '----------------------------------------'
 basics.describe_fuzz 'develop.fuzzing.destroy_fuzz'
+print '----------------------------------------'
 basics.describe_fuzz 'develop.fuzzing.batch_destroy_fuzz'
+print '----------------------------------------'
+basics.describe_fuzz 'develop.fuzzing.explicit_fuzz'
+print '----------------------------------------'
+basics.describe_fuzz 'develop.fuzzing.unique_fuzz'

develop/example.lua

@@ -17,28 +17,28 @@ local function vector2(x, y)
     return { x = x, y = y }
 end
 
-local groups = {
+local consts = {
-    awake = evo.builder():build(),
+    delta_time = 0.016,
-    physics = evo.builder():build(),
+    physics_gravity = vector2(0, 9.81),
-    graphics = evo.builder():build(),
-    shutdown = evo.builder():build(),
 }
 
-local singles = {
+local groups = {
-    delta_time = evo.builder():single(0.016):build(),
+    awake = evo.spawn(),
-    physics_gravity = evo.builder():single(vector2(0, 9.81)):build(),
+    physics = evo.spawn(),
+    graphics = evo.spawn(),
+    shutdown = evo.spawn(),
 }
 
 local fragments = {
-    force = evo.builder():build(),
+    force = evo.spawn(),
-    position = evo.builder():build(),
+    position = evo.spawn(),
-    velocity = evo.builder():build(),
+    velocity = evo.spawn(),
 }
 
 local queries = {
     physics_bodies = evo.builder()
         :include(fragments.force, fragments.position, fragments.velocity)
-        :build(),
+        :spawn(),
 }
 
 local awake_system = evo.builder()
@@ -49,20 +49,18 @@ local awake_system = evo.builder()
             :set(fragments.force, vector2(0, 0))
             :set(fragments.position, vector2(0, 0))
             :set(fragments.velocity, vector2(0, 0))
-            :build()
+            :spawn()
-    end):build()
+    end):spawn()
 
 local integrate_forces_system = evo.builder()
     :group(groups.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),
+            consts.delta_time, consts.physics_gravity
-            evo.get(singles.physics_gravity, singles.physics_gravity)
 
         ---@type evolved.vector2[], evolved.vector2[]
-        local forces, velocities = evo.components(chunk,
+        local forces, velocities = chunk:components(
             fragments.force, fragments.velocity)
 
         for i = 1, entity_count do
@@ -71,18 +69,17 @@ local integrate_forces_system = evo.builder()
             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()
+    end):spawn()
 
 local integrate_velocities_system = evo.builder()
     :group(groups.physics)
     :query(queries.physics_bodies)
     :execute(function(chunk, entities, entity_count)
-        ---@type number
         local delta_time =
-            evo.get(singles.delta_time, singles.delta_time)
+            consts.delta_time
 
         ---@type evolved.vector2[], evolved.vector2[], evolved.vector2[]
-        local forces, positions, velocities = evo.components(chunk,
+        local forces, positions, velocities = chunk:components(
             fragments.force, fragments.position, fragments.velocity)
 
         for i = 1, entity_count do
@@ -94,14 +91,14 @@ local integrate_velocities_system = evo.builder()
             force.x = 0
             force.y = 0
         end
-    end):build()
+    end):spawn()
 
 local graphics_system = evo.builder()
     :group(groups.graphics)
     :query(queries.physics_bodies)
     :execute(function(chunk, entities, entity_count)
         ---@type evolved.vector2[]
-        local positions = evo.components(chunk,
+        local positions = chunk:components(
             fragments.position)
 
         for i = 1, entity_count do
@@ -111,14 +108,14 @@ local graphics_system = evo.builder()
                 '|-> {entity %d} at {%.4f, %.4f}',
                 entity, position.x, position.y))
         end
-    end):build()
+    end):spawn()
 
 local shutdown_system = evo.builder()
     :group(groups.shutdown)
     :epilogue(function()
         print '-= | Shutdown | =-'
         evo.batch_destroy(queries.physics_bodies)
-    end):build()
+    end):spawn()
 
 do
     evo.process(groups.awake)

develop/fuzzing/batch_destroy_fuzz.lua

@@ -81,7 +81,7 @@ end
 
 do
     local r = math.random(1, 2)
-    local q = evo.builder():include(__table_unpack(destroying_include_list)):build()
+    local q = evo.builder():include(__table_unpack(destroying_include_list)):spawn()
 
     if r == 1 then
         evo.batch_destroy(q)
@@ -98,17 +98,17 @@ end
 ---
 ---
 
-local all_chunk_query = evo.builder():build()
+local all_chunk_query = evo.spawn()
 
 for chunk in evo.execute(all_chunk_query) do
-    assert(not evo.has_any(chunk, __table_unpack(should_be_destroyed_entity_list)))
+    assert(not chunk:has_any(__table_unpack(should_be_destroyed_entity_list)))
-    for _, fragment in ipairs(evo.fragments(chunk)) do
+    for _, fragment in ipairs(chunk:fragments()) do
         assert(not evo.has_all(fragment, __table_unpack(destroying_include_list)))
     end
 end
 
 for _, destroyed_entity in ipairs(should_be_destroyed_entity_list) do
-    assert(not evo.is_alive(destroyed_entity))
+    assert(not evo.alive(destroyed_entity))
 end
 
 ---

develop/fuzzing/destroy_fuzz.lua

@@ -102,19 +102,19 @@ end
 ---
 ---
 
-local all_chunk_query = evo.builder():build()
+local all_chunk_query = evo.spawn()
 
 for chunk in evo.execute(all_chunk_query) do
-    assert(not evo.has_any(chunk, __table_unpack(destroying_entity_list)))
+    assert(not chunk:has_any(__table_unpack(destroying_entity_list)))
-    assert(not evo.has_any(chunk, __table_unpack(should_be_destroyed_entity_list)))
+    assert(not chunk:has_any(__table_unpack(should_be_destroyed_entity_list)))
 end
 
 for _, destroying_entity in ipairs(destroying_entity_list) do
-    assert(not evo.is_alive(destroying_entity))
+    assert(not evo.alive(destroying_entity))
 end
 
 for _, destroyed_entity in ipairs(should_be_destroyed_entity_list) do
-    assert(not evo.is_alive(destroyed_entity))
+    assert(not evo.alive(destroyed_entity))
 end
 
 ---

develop/fuzzing/explicit_fuzz.lua

@@ -0,0 +1,81 @@
+local evo = require 'evolved'
+
+evo.debug_mode(true)
+
+---
+---
+---
+---
+---
+
+local __table_unpack = (function()
+    ---@diagnostic disable-next-line: deprecated
+    return table.unpack or unpack
+end)()
+
+---
+---
+---
+---
+---
+
+local all_entity_list = {} ---@type evolved.entity[]
+
+for i = 1, math.random(1, 10) do
+    local entity = evo.id()
+    all_entity_list[i] = entity
+end
+
+for _, entity in ipairs(all_entity_list) do
+    for _ = 0, math.random(0, #all_entity_list) do
+        local fragment = all_entity_list[math.random(1, #all_entity_list)]
+        evo.set(entity, fragment)
+    end
+
+    if math.random(1, 5) == 1 then
+        evo.set(entity, evo.EXPLICIT)
+    end
+end
+
+---
+---
+---
+---
+---
+
+for _ = 1, 100 do
+    local include_set = {} ---@type table<evolved.entity, integer>
+    local include_list = {} ---@type evolved.entity[]
+    local include_count = 0
+
+    for _ = 1, math.random(1, #all_entity_list) do
+        local include = all_entity_list[math.random(1, #all_entity_list)]
+
+        if not include_set[include] then
+            include_count = include_count + 1
+            include_set[include] = include_count
+            include_list[include_count] = include
+        end
+    end
+
+    local q = evo.builder():include(__table_unpack(include_list)):spawn()
+
+    for chunk in evo.execute(q) do
+        local fragment_list, fragment_count = chunk:fragments()
+        for i = 1, fragment_count do
+            local fragment = fragment_list[i]
+            assert(include_set[fragment] or not evo.has(fragment, evo.EXPLICIT))
+        end
+    end
+
+    evo.destroy(q)
+end
+
+---
+---
+---
+---
+---
+
+evo.destroy(__table_unpack(all_entity_list))
+evo.collect_garbage()

develop/fuzzing/unique_fuzz.lua

@@ -0,0 +1,67 @@
+local evo = require 'evolved'
+
+evo.debug_mode(true)
+
+---
+---
+---
+---
+---
+
+local __table_unpack = (function()
+    ---@diagnostic disable-next-line: deprecated
+    return table.unpack or unpack
+end)()
+
+---
+---
+---
+---
+---
+
+local all_entity_list = {} ---@type evolved.entity[]
+
+for i = 1, math.random(1, 10) do
+    local entity = evo.id()
+    all_entity_list[i] = entity
+end
+
+for _, entity in ipairs(all_entity_list) do
+    for _ = 0, math.random(0, #all_entity_list) do
+        local fragment = all_entity_list[math.random(1, #all_entity_list)]
+        evo.set(entity, fragment)
+    end
+
+    if math.random(1, 5) == 1 then
+        evo.set(entity, evo.UNIQUE)
+    end
+end
+
+---
+---
+---
+---
+---
+
+for _, entity in ipairs(all_entity_list) do
+    local entity_clone = evo.clone(entity)
+
+    for fragment in evo.each(entity_clone) do
+        assert(not evo.has(fragment, evo.UNIQUE))
+    end
+
+    for fragment in evo.each(entity) do
+        assert(evo.has(entity_clone, fragment) or evo.has(fragment, evo.UNIQUE))
+    end
+
+    evo.destroy(entity_clone)
+end
+
+---
+---
+---
+---
+---
+
+evo.destroy(__table_unpack(all_entity_list))
+evo.collect_garbage()

develop/unbench.lua

@@ -6,7 +6,7 @@ local evo = require 'evolved'
 local N = 1000
 local B = evo.builder()
 local F1, F2, F3, F4, F5 = evo.id(5)
-local Q1 = evo.builder():include(F1):build()
+local Q1 = evo.builder():include(F1):spawn()
 
 print '----------------------------------------'
 
@@ -440,11 +440,11 @@ basics.describe_bench(string.format('create and destroy %d entities with 1 compo
     ---@param entities evolved.id[]
     function(entities)
         local set = B.set
-        local build = B.build
+        local spawn = B.spawn
 
         for i = 1, N do
             set(B, F1)
-            entities[i] = build(B)
+            entities[i] = spawn(B)
         end
 
         evo.batch_destroy(Q1)
@@ -456,12 +456,12 @@ basics.describe_bench(string.format('create and destroy %d entities with 2 compo
     ---@param entities evolved.id[]
     function(entities)
         local set = B.set
-        local build = B.build
+        local spawn = B.spawn
 
         for i = 1, N do
             set(B, F1)
             set(B, F2)
-            entities[i] = build(B)
+            entities[i] = spawn(B)
         end
 
         evo.batch_destroy(Q1)
@@ -473,13 +473,13 @@ basics.describe_bench(string.format('create and destroy %d entities with 3 compo
     ---@param entities evolved.id[]
     function(entities)
         local set = B.set
-        local build = B.build
+        local spawn = B.spawn
 
         for i = 1, N do
             set(B, F1)
             set(B, F2)
             set(B, F3)
-            entities[i] = build(B)
+            entities[i] = spawn(B)
         end
 
         evo.batch_destroy(Q1)
@@ -491,14 +491,14 @@ basics.describe_bench(string.format('create and destroy %d entities with 4 compo
     ---@param entities evolved.id[]
     function(entities)
         local set = B.set
-        local build = B.build
+        local spawn = B.spawn
 
         for i = 1, N do
             set(B, F1)
             set(B, F2)
             set(B, F3)
             set(B, F4)
-            entities[i] = build(B)
+            entities[i] = spawn(B)
         end
 
         evo.batch_destroy(Q1)
@@ -510,7 +510,7 @@ basics.describe_bench(string.format('create and destroy %d entities with 5 compo
     ---@param entities evolved.id[]
     function(entities)
         local set = B.set
-        local build = B.build
+        local spawn = B.spawn
 
         for i = 1, N do
             set(B, F1)
@@ -518,7 +518,7 @@ basics.describe_bench(string.format('create and destroy %d entities with 5 compo
             set(B, F3)
             set(B, F4)
             set(B, F5)
-            entities[i] = build(B)
+            entities[i] = spawn(B)
         end
 
         evo.batch_destroy(Q1)
@@ -528,15 +528,15 @@ basics.describe_bench(string.format('create and destroy %d entities with 5 compo
 
 print '----------------------------------------'
 
-basics.describe_bench(string.format('create and destroy %d entities with 1 components / multi-set', N),
+basics.describe_bench(string.format('create and destroy %d entities with 1 components / spawn', N),
     ---@param entities evolved.id[]
     function(entities)
-        local set = evo.multi_set
+        local spawn = evo.spawn
+
+        local components = { [F1] = true }
 
         for i = 1, N do
-            local e = evo.id()
+            entities[i] = spawn(components)
-            set(e, { F1 })
-            entities[i] = e
         end
 
         evo.batch_destroy(Q1)
@@ -544,15 +544,15 @@ basics.describe_bench(string.format('create and destroy %d entities with 1 compo
         return {}
     end)
 
-basics.describe_bench(string.format('create and destroy %d entities with 2 components / multi-set', N),
+basics.describe_bench(string.format('create and destroy %d entities with 2 components / spawn', N),
     ---@param entities evolved.id[]
     function(entities)
-        local set = evo.multi_set
+        local spawn = evo.spawn
+
+        local components = { [F1] = true, [F2] = true }
 
         for i = 1, N do
-            local e = evo.id()
+            entities[i] = spawn(components)
-            set(e, { F1, F2 })
-            entities[i] = e
         end
 
         evo.batch_destroy(Q1)
@@ -560,15 +560,15 @@ basics.describe_bench(string.format('create and destroy %d entities with 2 compo
         return {}
     end)
 
-basics.describe_bench(string.format('create and destroy %d entities with 3 components / multi-set', N),
+basics.describe_bench(string.format('create and destroy %d entities with 3 components / spawn', N),
     ---@param entities evolved.id[]
     function(entities)
-        local set = evo.multi_set
+        local spawn = evo.spawn
+
+        local components = { [F1] = true, [F2] = true, [F3] = true }
 
         for i = 1, N do
-            local e = evo.id()
+            entities[i] = spawn(components)
-            set(e, { F1, F2, F3 })
-            entities[i] = e
         end
 
         evo.batch_destroy(Q1)
@@ -576,15 +576,15 @@ basics.describe_bench(string.format('create and destroy %d entities with 3 compo
         return {}
     end)
 
-basics.describe_bench(string.format('create and destroy %d entities with 4 components / multi-set', N),
+basics.describe_bench(string.format('create and destroy %d entities with 4 components / spawn', N),
     ---@param entities evolved.id[]
     function(entities)
-        local set = evo.multi_set
+        local spawn = evo.spawn
+
+        local components = { [F1] = true, [F2] = true, [F3] = true, [F4] = true }
 
         for i = 1, N do
-            local e = evo.id()
+            entities[i] = spawn(components)
-            set(e, { F1, F2, F3, F4 })
-            entities[i] = e
         end
 
         evo.batch_destroy(Q1)
@@ -592,15 +592,15 @@ basics.describe_bench(string.format('create and destroy %d entities with 4 compo
         return {}
     end)
 
-basics.describe_bench(string.format('create and destroy %d entities with 5 components / multi-set', N),
+basics.describe_bench(string.format('create and destroy %d entities with 5 components / spawn', N),
     ---@param entities evolved.id[]
     function(entities)
-        local set = evo.multi_set
+        local spawn = evo.spawn
+
+        local components = { [F1] = true, [F2] = true, [F3] = true, [F4] = true, [F5] = true }
 
         for i = 1, N do
-            local e = evo.id()
+            entities[i] = spawn(components)
-            set(e, { F1, F2, F3, F4, F5 })
-            entities[i] = e
         end
 
         evo.batch_destroy(Q1)
@@ -610,18 +610,16 @@ basics.describe_bench(string.format('create and destroy %d entities with 5 compo
 
 print '----------------------------------------'
 
-basics.describe_bench(string.format('create and destroy %d entities with 1 components / spawn_at', N),
+
+basics.describe_bench(string.format('create and destroy %d entities with 1 components / clone', N),
     ---@param entities evolved.id[]
     function(entities)
-        local spawn_at = evo.spawn_at
+        local clone = evo.clone
 
-        local fragments = { F1 }
+        local prefab = evo.spawn({ [F1] = true })
-        local components = { true }
-
-        local chunk = evo.chunk(F1)
 
         for i = 1, N do
-            entities[i] = spawn_at(chunk, fragments, components)
+            entities[i] = clone(prefab)
         end
 
         evo.batch_destroy(Q1)
@@ -629,18 +627,15 @@ basics.describe_bench(string.format('create and destroy %d entities with 1 compo
         return {}
     end)
 
-basics.describe_bench(string.format('create and destroy %d entities with 2 components / spawn_at', N),
+basics.describe_bench(string.format('create and destroy %d entities with 2 components / clone', N),
     ---@param entities evolved.id[]
     function(entities)
-        local spawn_at = evo.spawn_at
+        local clone = evo.clone
 
-        local fragments = { F1, F2 }
+        local prefab = evo.spawn({ [F1] = true, [F2] = true })
-        local components = { true, true }
-
-        local chunk = evo.chunk(F1, F2)
 
         for i = 1, N do
-            entities[i] = spawn_at(chunk, fragments, components)
+            entities[i] = clone(prefab)
         end
 
         evo.batch_destroy(Q1)
@@ -648,18 +643,15 @@ basics.describe_bench(string.format('create and destroy %d entities with 2 compo
         return {}
     end)
 
-basics.describe_bench(string.format('create and destroy %d entities with 3 components / spawn_at', N),
+basics.describe_bench(string.format('create and destroy %d entities with 3 components / clone', N),
     ---@param entities evolved.id[]
     function(entities)
-        local spawn_at = evo.spawn_at
+        local clone = evo.clone
 
-        local fragments = { F1, F2, F3 }
+        local prefab = evo.spawn({ [F1] = true, [F2] = true, [F3] = true })
-        local components = { true, true, true }
-
-        local chunk = evo.chunk(F1, F2, F3)
 
         for i = 1, N do
-            entities[i] = spawn_at(chunk, fragments, components)
+            entities[i] = clone(prefab)
         end
 
         evo.batch_destroy(Q1)
@@ -667,18 +659,15 @@ basics.describe_bench(string.format('create and destroy %d entities with 3 compo
         return {}
     end)
 
-basics.describe_bench(string.format('create and destroy %d entities with 4 components / spawn_at', N),
+basics.describe_bench(string.format('create and destroy %d entities with 4 components / clone', N),
     ---@param entities evolved.id[]
     function(entities)
-        local spawn_at = evo.spawn_at
+        local clone = evo.clone
 
-        local fragments = { F1, F2, F3, F4 }
+        local prefab = evo.spawn({ [F1] = true, [F2] = true, [F3] = true, [F4] = true })
-        local components = { true, true, true, true }
-
-        local chunk = evo.chunk(F1, F2, F3, F4)
 
         for i = 1, N do
-            entities[i] = spawn_at(chunk, fragments, components)
+            entities[i] = clone(prefab)
         end
 
         evo.batch_destroy(Q1)
@@ -686,207 +675,18 @@ basics.describe_bench(string.format('create and destroy %d entities with 4 compo
         return {}
     end)
 
-basics.describe_bench(string.format('create and destroy %d entities with 5 components / spawn_at', N),
+basics.describe_bench(string.format('create and destroy %d entities with 5 components / clone', N),
     ---@param entities evolved.id[]
     function(entities)
-        local spawn_at = evo.spawn_at
+        local clone = evo.clone
 
-        local fragments = { F1, F2, F3, F4, F5 }
+        local prefab = evo.spawn({ [F1] = true, [F2] = true, [F3] = true, [F4] = true, [F5] = true })
-        local components = { true, true, true, true, true }
-
-        local chunk = evo.chunk(F1, F2, F3, F4, F5)
 
         for i = 1, N do
-            entities[i] = spawn_at(chunk, fragments, components)
+            entities[i] = clone(prefab)
         end
 
         evo.batch_destroy(Q1)
     end, function()
         return {}
     end)
-
-print '----------------------------------------'
-
-basics.describe_bench(string.format('create and destroy %d entities with 1 components / spawn_as', N),
-    ---@param entities evolved.id[]
-    function(entities)
-        local spawn_as = evo.spawn_as
-
-        local fragments = { F1 }
-        local components = { true }
-
-        local prefab = evo.spawn_with(fragments, components)
-
-        for i = 1, N do
-            entities[i] = spawn_as(prefab, fragments, components)
-        end
-
-        evo.batch_destroy(Q1)
-    end, function()
-        return {}
-    end)
-
-basics.describe_bench(string.format('create and destroy %d entities with 2 components / spawn_as', N),
-    ---@param entities evolved.id[]
-    function(entities)
-        local spawn_as = evo.spawn_as
-
-        local fragments = { F1, F2 }
-        local components = { true, true }
-
-        local prefab = evo.spawn_with(fragments, components)
-
-        for i = 1, N do
-            entities[i] = spawn_as(prefab, fragments, components)
-        end
-
-        evo.batch_destroy(Q1)
-    end, function()
-        return {}
-    end)
-
-basics.describe_bench(string.format('create and destroy %d entities with 3 components / spawn_as', N),
-    ---@param entities evolved.id[]
-    function(entities)
-        local spawn_as = evo.spawn_as
-
-        local fragments = { F1, F2, F3 }
-        local components = { true, true, true }
-
-        local prefab = evo.spawn_with(fragments, components)
-
-        for i = 1, N do
-            entities[i] = spawn_as(prefab, fragments, components)
-        end
-
-        evo.batch_destroy(Q1)
-    end, function()
-        return {}
-    end)
-
-basics.describe_bench(string.format('create and destroy %d entities with 4 components / spawn_as', N),
-    ---@param entities evolved.id[]
-    function(entities)
-        local spawn_as = evo.spawn_as
-
-        local fragments = { F1, F2, F3, F4 }
-        local components = { true, true, true, true }
-
-        local prefab = evo.spawn_with(fragments, components)
-
-        for i = 1, N do
-            entities[i] = spawn_as(prefab, fragments, components)
-        end
-
-        evo.batch_destroy(Q1)
-    end, function()
-        return {}
-    end)
-
-basics.describe_bench(string.format('create and destroy %d entities with 5 components / spawn_as', N),
-    ---@param entities evolved.id[]
-    function(entities)
-        local spawn_as = evo.spawn_as
-
-        local fragments = { F1, F2, F3, F4, F5 }
-        local components = { true, true, true, true, true }
-
-        local prefab = evo.spawn_with(fragments, components)
-
-        for i = 1, N do
-            entities[i] = spawn_as(prefab, fragments, components)
-        end
-
-        evo.batch_destroy(Q1)
-    end, function()
-        return {}
-    end)
-
-print '----------------------------------------'
-
-basics.describe_bench(string.format('create and destroy %d entities with 1 components / spawn_with', N),
-    ---@param entities evolved.id[]
-    function(entities)
-        local spawn_with = evo.spawn_with
-
-        local fragments = { F1 }
-        local components = { true }
-
-        for i = 1, N do
-            entities[i] = spawn_with(fragments, components)
-        end
-
-        evo.batch_destroy(Q1)
-    end, function()
-        return {}
-    end)
-
-basics.describe_bench(string.format('create and destroy %d entities with 2 components / spawn_with', N),
-    ---@param entities evolved.id[]
-    function(entities)
-        local spawn_with = evo.spawn_with
-
-        local fragments = { F1, F2 }
-        local components = { true, true }
-
-        for i = 1, N do
-            entities[i] = spawn_with(fragments, components)
-        end
-
-        evo.batch_destroy(Q1)
-    end, function()
-        return {}
-    end)
-
-basics.describe_bench(string.format('create and destroy %d entities with 3 components / spawn_with', N),
-    ---@param entities evolved.id[]
-    function(entities)
-        local spawn_with = evo.spawn_with
-
-        local fragments = { F1, F2, F3 }
-        local components = { true, true, true }
-
-        for i = 1, N do
-            entities[i] = spawn_with(fragments, components)
-        end
-
-        evo.batch_destroy(Q1)
-    end, function()
-        return {}
-    end)
-
-basics.describe_bench(string.format('create and destroy %d entities with 4 components / spawn_with', N),
-    ---@param entities evolved.id[]
-    function(entities)
-        local spawn_with = evo.spawn_with
-
-        local fragments = { F1, F2, F3, F4 }
-        local components = { true, true, true, true }
-
-        for i = 1, N do
-            entities[i] = spawn_with(fragments, components)
-        end
-
-        evo.batch_destroy(Q1)
-    end, function()
-        return {}
-    end)
-
-basics.describe_bench(string.format('create and destroy %d entities with 5 components / spawn_with', N),
-    ---@param entities evolved.id[]
-    function(entities)
-        local spawn_with = evo.spawn_with
-
-        local fragments = { F1, F2, F3, F4, F5 }
-        local components = { true, true, true, true, true }
-
-        for i = 1, N do
-            entities[i] = spawn_with(fragments, components)
-        end
-
-        evo.batch_destroy(Q1)
-    end, function()
-        return {}
-    end)
-
-print '----------------------------------------'

develop/usbench.lua

@@ -40,9 +40,9 @@ basics.describe_bench(string.format('Evolved Entity Cycle (Defer): %d entities',
     function(a, b, A, B)
         evo.defer()
         do
-            for chunk, entities in evo.execute(A) do
+            for chunk, _, entity_count in evo.execute(A) do
-                local as = evo.components(chunk, a)
+                local as = chunk:components(a)
-                for i = 1, #entities do
+                for i = 1, entity_count do
                     evo.set(evo.id(), b, as[i])
                 end
             end
@@ -54,11 +54,11 @@ basics.describe_bench(string.format('Evolved Entity Cycle (Defer): %d entities',
         local a, b = evo.id(2)
 
         for i = 1, N do
-            evo.builder():set(a, i):build()
+            evo.builder():set(a, i):spawn()
         end
 
-        local A = evo.builder():include(a):build()
+        local A = evo.builder():include(a):spawn()
-        local B = evo.builder():include(b):build()
+        local B = evo.builder():include(b):spawn()
 
         return a, b, A, B
     end, function(_, _, A, _)
@@ -68,15 +68,17 @@ basics.describe_bench(string.format('Evolved Entity Cycle (Defer): %d entities',
 basics.describe_bench(string.format('Evolved Entity Cycle (Manual): %d entities', N),
     function(a, b, A, B)
         local to_create = {}
+        local to_create_count = 0
 
-        for chunk, entities in evo.execute(A) do
+        for chunk, _, entity_count in evo.execute(A) do
-            local as = evo.components(chunk, a)
+            local as = chunk:components(a)
-            for i = 1, #entities do
+            for i = 1, entity_count do
-                to_create[#to_create + 1] = as[i]
+                to_create_count = to_create_count + 1
+                to_create[to_create_count] = as[i]
             end
         end
 
-        for i = 1, #to_create do
+        for i = 1, to_create_count do
             local e = evo.id()
             evo.set(e, b, to_create[i])
         end
@@ -86,11 +88,11 @@ basics.describe_bench(string.format('Evolved Entity Cycle (Manual): %d entities'
         local a, b = evo.id(2)
 
         for i = 1, N do
-            evo.builder():set(a, i):build()
+            evo.builder():set(a, i):spawn()
         end
 
-        local A = evo.builder():include(a):build()
+        local A = evo.builder():include(a):spawn()
-        local B = evo.builder():include(b):build()
+        local B = evo.builder():include(b):spawn()
 
         return a, b, A, B
     end, function(_, _, A, _)
@@ -143,23 +145,23 @@ basics.describe_bench(string.format('Evolved Simple Iteration: %d entities', N),
     ---@param CD evolved.query
     ---@param CE evolved.query
     function(a, b, c, d, e, AB, CD, CE)
-        for chunk, entities in evo.execute(AB) do
+        for chunk, _, entity_count in evo.execute(AB) do
-            local as, bs = evo.components(chunk, a, b)
+            local as, bs = chunk:components(a, b)
-            for i = 1, #entities do
+            for i = 1, entity_count do
                 as[i], bs[i] = bs[i], as[i]
             end
         end
 
-        for chunk, entities in evo.execute(CD) do
+        for chunk, _, entity_count in evo.execute(CD) do
-            local cs, ds = evo.components(chunk, c, d)
+            local cs, ds = chunk:components(c, d)
-            for i = 1, #entities do
+            for i = 1, entity_count do
                 cs[i], ds[i] = ds[i], cs[i]
             end
         end
 
-        for chunk, entities in evo.execute(CE) do
+        for chunk, _, entity_count in evo.execute(CE) do
-            local cs, es = evo.components(chunk, c, e)
+            local cs, es = chunk:components(c, e)
-            for i = 1, #entities do
+            for i = 1, entity_count do
                 cs[i], es[i] = es[i], cs[i]
             end
         end
@@ -167,15 +169,15 @@ basics.describe_bench(string.format('Evolved Simple Iteration: %d entities', N),
         local a, b, c, d, e = evo.id(5)
 
         for i = 1, N do
-            evo.builder():set(a, i):set(b, i):build()
+            evo.builder():set(a, i):set(b, i):spawn()
-            evo.builder():set(a, i):set(b, i):set(c, i):build()
+            evo.builder():set(a, i):set(b, i):set(c, i):spawn()
-            evo.builder():set(a, i):set(b, i):set(c, i):set(d, i):build()
+            evo.builder():set(a, i):set(b, i):set(c, i):set(d, i):spawn()
-            evo.builder():set(a, i):set(b, i):set(c, i):set(e, i):build()
+            evo.builder():set(a, i):set(b, i):set(c, i):set(e, i):spawn()
         end
 
-        local AB = evo.builder():include(a, b):build()
+        local AB = evo.builder():include(a, b):spawn()
-        local CD = evo.builder():include(c, d):build()
+        local CD = evo.builder():include(c, d):spawn()
-        local CE = evo.builder():include(c, e):build()
+        local CE = evo.builder():include(c, e):spawn()
 
         return a, b, c, d, e, AB, CD, CE
     end, function(_, _, _, _, _, AB, CD, CE)
@@ -239,37 +241,37 @@ basics.describe_bench(string.format('Evolved Packed Iteration: %d entities', N),
     ---@param D evolved.query
     ---@param E evolved.query
     function(a, b, c, d, e, A, B, C, D, E)
-        for chunk, entities in evo.execute(A) do
+        for chunk, _, entity_count in evo.execute(A) do
-            local as = evo.components(chunk, a)
+            local as = chunk:components(a)
-            for i = 1, #entities do
+            for i = 1, entity_count do
                 as[i] = as[i] * 2
             end
         end
 
-        for chunk, entities in evo.execute(B) do
+        for chunk, _, entity_count in evo.execute(B) do
-            local bs = evo.components(chunk, b)
+            local bs = chunk:components(b)
-            for i = 1, #entities do
+            for i = 1, entity_count do
                 bs[i] = bs[i] * 2
             end
         end
 
-        for chunk, entities in evo.execute(C) do
+        for chunk, _, entity_count in evo.execute(C) do
-            local cs = evo.components(chunk, c)
+            local cs = chunk:components(c)
-            for i = 1, #entities do
+            for i = 1, entity_count do
                 cs[i] = cs[i] * 2
             end
         end
 
-        for chunk, entities in evo.execute(D) do
+        for chunk, _, entity_count in evo.execute(D) do
-            local ds = evo.components(chunk, d)
+            local ds = chunk:components(d)
-            for i = 1, #entities do
+            for i = 1, entity_count do
                 ds[i] = ds[i] * 2
             end
         end
 
-        for chunk, entities in evo.execute(E) do
+        for chunk, _, entity_count in evo.execute(E) do
-            local es = evo.components(chunk, e)
+            local es = chunk:components(e)
-            for i = 1, #entities do
+            for i = 1, entity_count do
                 es[i] = es[i] * 2
             end
         end
@@ -277,14 +279,14 @@ basics.describe_bench(string.format('Evolved Packed Iteration: %d entities', N),
         local a, b, c, d, e = evo.id(5)
 
         for i = 1, N do
-            evo.builder():set(a, i):set(b, i):set(c, i):set(d, i):set(e, i):build()
+            evo.builder():set(a, i):set(b, i):set(c, i):set(d, i):set(e, i):spawn()
         end
 
-        local A = evo.builder():include(a):build()
+        local A = evo.builder():include(a):spawn()
-        local B = evo.builder():include(b):build()
+        local B = evo.builder():include(b):spawn()
-        local C = evo.builder():include(c):build()
+        local C = evo.builder():include(c):spawn()
-        local D = evo.builder():include(d):build()
+        local D = evo.builder():include(d):spawn()
-        local E = evo.builder():include(e):build()
+        local E = evo.builder():include(e):spawn()
 
         return a, b, c, d, e, A, B, C, D, E
     end, function(_, _, _, _, _, A, _, _, _, _)
@@ -334,16 +336,16 @@ basics.describe_bench(string.format('Evolved Fragmented Iteration: %d entities',
     ---@param Data evolved.query
     ---@param Last evolved.query
     function(data, last, Data, Last)
-        for chunk, entities in evo.execute(Data) do
+        for chunk, _, entity_count in evo.execute(Data) do
-            local ds = evo.components(chunk, data)
+            local ds = chunk:components(data)
-            for i = 1, #entities do
+            for i = 1, entity_count do
                 ds[i] = ds[i] * 2
             end
         end
 
-        for chunk, entities in evo.execute(Last) do
+        for chunk, _, entity_count in evo.execute(Last) do
-            local ls = evo.components(chunk, last)
+            local ls = chunk:components(last)
-            for i = 1, #entities do
+            for i = 1, entity_count do
                 ls[i] = ls[i] * 2
             end
         end
@@ -359,16 +361,14 @@ basics.describe_bench(string.format('Evolved Fragmented Iteration: %d entities',
 
         for _, char in ipairs(chars) do
             for i = 1, N do
-                evo.builder():set(char, i):set(data, i):build()
+                evo.builder():set(char, i):set(data, i):spawn()
             end
         end
 
-        local Data = evo.builder():include(data):build()
+        local Data = evo.builder():include(data):spawn()
-        local Last = evo.builder():include(chars[#chars]):build()
+        local Last = evo.builder():include(chars[#chars]):spawn()
 
         return data, chars[#chars], Data, Last
     end, function(_, _, Data, _)
         evo.batch_destroy(Data)
     end)
-
-print '----------------------------------------'