remove legacy spawn_at / spawn_as

README.md

@@ -29,6 +29,7 @@
 ```
 TAG :: fragment
 NAME :: fragment
+
 DEFAULT :: fragment
 DUPLICATE :: fragment
 
@@ -98,8 +99,8 @@ process :: system... -> ()
 spawn :: <fragment, component>? -> entity
 clone :: entity -> <fragment, component>? -> entity
 
-spawn_at :: chunk?, fragment[]?, component[]? -> entity
+spawn_single :: component, <fragment, component>? -> entity
-spawn_as :: entity?, fragment[]?, component[]? -> entity
+clone_single :: entity -> component -> <fragment, component>? -> entity
 
 debug_mode :: boolean -> ()
 collect_garbage :: ()
@@ -140,9 +141,6 @@ builder:clear :: builder
 builder:tag :: builder
 builder:name :: string -> builder
 
-builder:prefab :: entity -> builder
-builder:single :: component -> builder
-
 builder:default :: component -> builder
 builder:duplicate :: {component -> component} -> builder
 
@@ -166,7 +164,11 @@ builder:disabled :: builder
 
 builder:destroy_policy :: id -> builder
 
-builder:build :: boolean -> entity
+builder:spawn :: entity
+builder:clone :: entity -> entity
+
+builder:spawn_single :: component -> entity
+builder:clone_single :: entity -> component -> entity
 ```
 
 ## [License (MIT)](./LICENSE.md)

develop/all.lua

@@ -5,5 +5,7 @@ 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'

develop/example.lua

@@ -18,27 +18,27 @@ local function vector2(x, y)
 end
 
 local groups = {
-    awake = evo.builder():build(),
+    awake = evo.spawn(),
-    physics = evo.builder():build(),
+    physics = evo.spawn(),
-    graphics = evo.builder():build(),
+    graphics = evo.spawn(),
-    shutdown = evo.builder():build(),
+    shutdown = evo.spawn(),
 }
 
 local singles = {
-    delta_time = evo.builder():single(0.016):build(),
+    delta_time = evo.spawn_single(0.016),
-    physics_gravity = evo.builder():single(vector2(0, 9.81)):build(),
+    physics_gravity = evo.spawn_single(vector2(0, 9.81)),
 }
 
 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,8 +49,8 @@ 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)
@@ -71,7 +71,7 @@ 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)
@@ -94,7 +94,7 @@ 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)
@@ -111,14 +111,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,7 +98,7 @@ 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 chunk:has_any(__table_unpack(should_be_destroyed_entity_list)))

develop/fuzzing/destroy_fuzz.lua

@@ -102,7 +102,7 @@ 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 chunk:has_any(__table_unpack(destroying_entity_list)))

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)
@@ -690,199 +690,3 @@ basics.describe_bench(string.format('create and destroy %d entities with 5 compo
     end, function()
         return {}
     end)
-
-print '----------------------------------------'
-
-basics.describe_bench(string.format('create and destroy %d entities with 1 components / spawn_at', N),
-    ---@param entities evolved.id[]
-    function(entities)
-        local spawn_at = evo.spawn_at
-
-        local fragments = { F1 }
-        local components = { true }
-
-        local chunk = evo.chunk(F1)
-
-        for i = 1, N do
-            entities[i] = spawn_at(chunk, 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_at', N),
-    ---@param entities evolved.id[]
-    function(entities)
-        local spawn_at = evo.spawn_at
-
-        local fragments = { F1, F2 }
-        local components = { true, true }
-
-        local chunk = evo.chunk(F1, F2)
-
-        for i = 1, N do
-            entities[i] = spawn_at(chunk, 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_at', N),
-    ---@param entities evolved.id[]
-    function(entities)
-        local spawn_at = evo.spawn_at
-
-        local fragments = { F1, F2, F3 }
-        local components = { true, true, true }
-
-        local chunk = evo.chunk(F1, F2, F3)
-
-        for i = 1, N do
-            entities[i] = spawn_at(chunk, 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_at', N),
-    ---@param entities evolved.id[]
-    function(entities)
-        local spawn_at = evo.spawn_at
-
-        local fragments = { F1, F2, F3, F4 }
-        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)
-        end
-
-        evo.batch_destroy(Q1)
-    end, function()
-        return {}
-    end)
-
-basics.describe_bench(string.format('create and destroy %d entities with 5 components / spawn_at', N),
-    ---@param entities evolved.id[]
-    function(entities)
-        local spawn_at = evo.spawn_at
-
-        local fragments = { F1, F2, F3, F4, F5 }
-        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)
-        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 { [F1] = true }
-
-        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 { [F1] = true, [F2] = true }
-
-        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 { [F1] = true, [F2] = true, [F3] = true }
-
-        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 { [F1] = true, [F2] = true, [F3] = true, [F4] = true }
-
-        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 { [F1] = true, [F2] = true, [F3] = true, [F4] = true, [F5] = true }
-
-        for i = 1, N do
-            entities[i] = spawn_as(prefab, 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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 = 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 '----------------------------------------'