update teal definitions

README.md

@@ -1500,9 +1500,13 @@ cancel :: boolean
 
 spawn :: component_table?, component_mapper? -> entity
 multi_spawn :: integer, component_table?, component_mapper? -> entity[], integer
+multi_spawn_nr :: integer, component_table?, component_mapper? -> ()
+multi_spawn_to :: entity[], integer, integer, component_table?, component_mapper? -> ()
 
 clone :: entity, component_table?, component_mapper? -> entity
 multi_clone :: integer, entity, component_table?, component_mapper? -> entity[], integer
+multi_clone_nr :: integer, entity, component_table?, component_mapper? -> ()
+multi_clone_to :: entity[], integer, integer, entity, component_table?, component_mapper? -> ()
 
 alive :: entity -> boolean
 alive_all :: entity... -> boolean
@@ -1535,6 +1539,7 @@ locate :: entity -> chunk?, integer
 
 lookup :: string -> entity?
 multi_lookup :: string -> entity[], integer
+multi_lookup_to :: entity[], integer, string -> integer
 
 process :: system... -> ()
 process_with :: system, ... -> ()
@@ -1569,12 +1574,18 @@ builder :: builder
 
 builder_mt:build :: entity?, component_mapper? -> entity
 builder_mt:multi_build :: integer, entity?, component_mapper? -> entity[], integer
+builder_mt:multi_build_nr :: integer, entity?, component_mapper? -> ()
+builder_mt:multi_build_to :: entity[], integer, integer, entity?, component_mapper? -> ()
 
 builder_mt:spawn :: component_mapper? -> entity
 builder_mt:multi_spawn :: integer, component_mapper? -> entity[], integer
+builder_mt:multi_spawn_nr :: integer, component_mapper? -> ()
+builder_mt:multi_spawn_to :: entity[], integer, integer, component_mapper? -> ()
 
 builder_mt:clone :: entity, component_mapper? -> entity
 builder_mt:multi_clone :: integer, entity, component_mapper? -> entity[], integer
+builder_mt:multi_clone_nr :: integer, entity, component_mapper? -> ()
+builder_mt:multi_clone_to :: entity[], integer, integer, entity, component_mapper? -> ()
 
 builder_mt:has :: fragment -> boolean
 builder_mt:has_all :: fragment... -> boolean
@@ -1835,9 +1846,31 @@ function evolved.spawn(component_table, component_mapper) end
 ---@param component_mapper? evolved.component_mapper
 ---@return evolved.entity[] entity_list
 ---@return integer entity_count
+---@nodiscard
 function evolved.multi_spawn(entity_count, component_table, component_mapper) end
 ```
 
+### `evolved.multi_spawn_nr`
+
+```lua
+---@param entity_count integer
+---@param component_table? evolved.component_table
+---@param component_mapper? evolved.component_mapper
+function evolved.multi_spawn_nr(entity_count, component_table, component_mapper) end
+```
+
+### `evolved.multi_spawn_to`
+
+```lua
+---@param out_entity_list evolved.entity[]
+---@param out_entity_first integer
+---@param entity_count integer
+---@param component_table? evolved.component_table
+---@param component_mapper? evolved.component_mapper
+function evolved.multi_spawn_to(out_entity_list, out_entity_first,
+                                entity_count, component_table, component_mapper) end
+```
+
 ### `evolved.clone`
 
 ```lua
@@ -1857,9 +1890,33 @@ function evolved.clone(prefab, component_table, component_mapper) end
 ---@param component_mapper? evolved.component_mapper
 ---@return evolved.entity[] entity_list
 ---@return integer entity_count
+---@nodiscard
 function evolved.multi_clone(entity_count, prefab, component_table, component_mapper) end
 ```
 
+### `evolved.multi_clone_nr`
+
+```lua
+---@param entity_count integer
+---@param prefab evolved.entity
+---@param component_table? evolved.component_table
+---@param component_mapper? evolved.component_mapper
+function evolved.multi_clone_nr(entity_count, prefab, component_table, component_mapper) end
+```
+
+### `evolved.multi_clone_to`
+
+```lua
+---@param out_entity_list evolved.entity[]
+---@param out_entity_first integer
+---@param entity_count integer
+---@param prefab evolved.entity
+---@param component_table? evolved.component_table
+---@param component_mapper? evolved.component_mapper
+function evolved.multi_clone_to(out_entity_list, out_entity_first,
+                                entity_count, prefab, component_table, component_mapper) end
+```
+
 ### `evolved.alive`
 
 ```lua
@@ -2065,6 +2122,16 @@ function evolved.lookup(name) end
 function evolved.multi_lookup(name) end
 ```
 
+### `evolved.multi_lookup_to`
+
+```lua
+---@param out_entity_list evolved.entity[]
+---@param out_entity_first integer
+---@param name string
+---@return integer entity_count
+function evolved.multi_lookup_to(out_entity_list, out_entity_first, name) end
+```
+
 ### `evolved.process`
 
 ```lua
@@ -2207,9 +2274,31 @@ function evolved.builder_mt:build(prefab, component_mapper) end
 ---@param component_mapper? evolved.component_mapper
 ---@return evolved.entity[] entity_list
 ---@return integer entity_count
+---@nodiscard
 function evolved.builder_mt:multi_build(entity_count, prefab, component_mapper) end
 ```
 
+### `evolved.builder_mt:multi_build_nr`
+
+```lua
+---@param entity_count integer
+---@param prefab? evolved.entity
+---@param component_mapper? evolved.component_mapper
+function evolved.builder_mt:multi_build_nr(entity_count, prefab, component_mapper) end
+```
+
+### `evolved.builder_mt:multi_build_to`
+
+```lua
+---@param out_entity_list evolved.entity[]
+---@param out_entity_first integer
+---@param entity_count integer
+---@param prefab? evolved.entity
+---@param component_mapper? evolved.component_mapper
+function evolved.builder_mt:multi_build_to(out_entity_list, out_entity_first,
+                                           entity_count, prefab, component_mapper) end
+```
+
 #### `evolved.builder_mt:spawn`
 
 ```lua
@@ -2225,9 +2314,29 @@ function evolved.builder_mt:spawn(component_mapper) end
 ---@param component_mapper? evolved.component_mapper
 ---@return evolved.entity[] entity_list
 ---@return integer entity_count
+---@nodiscard
 function evolved.builder_mt:multi_spawn(entity_count, component_mapper) end
 ```
 
+#### `evolved.builder_mt:multi_spawn_nr`
+
+```lua
+---@param entity_count integer
+---@param component_mapper? evolved.component_mapper
+function evolved.builder_mt:multi_spawn_nr(entity_count, component_mapper) end
+```
+
+#### `evolved.builder_mt:multi_spawn_to`
+
+```lua
+---@param out_entity_list evolved.entity[]
+---@param out_entity_first integer
+---@param entity_count integer
+---@param component_mapper? evolved.component_mapper
+function evolved.builder_mt:multi_spawn_to(out_entity_list, out_entity_first,
+                                           entity_count, component_mapper) end
+```
+
 #### `evolved.builder_mt:clone`
 
 ```lua
@@ -2245,9 +2354,31 @@ function evolved.builder_mt:clone(prefab, component_mapper) end
 ---@param component_mapper? evolved.component_mapper
 ---@return evolved.entity[] entity_list
 ---@return integer entity_count
+---@nodiscard
 function evolved.builder_mt:multi_clone(entity_count, prefab, component_mapper) end
 ```
 
+#### `evolved.builder_mt:multi_clone_nr`
+
+```lua
+---@param entity_count integer
+---@param prefab evolved.entity
+---@param component_mapper? evolved.component_mapper
+function evolved.builder_mt:multi_clone_nr(entity_count, prefab, component_mapper) end
+```
+
+#### `evolved.builder_mt:multi_clone_to`
+
+```lua
+---@param out_entity_list evolved.entity[]
+---@param out_entity_first integer
+---@param entity_count integer
+---@param prefab evolved.entity
+---@param component_mapper? evolved.component_mapper
+function evolved.builder_mt:multi_clone_to(out_entity_list, out_entity_first,
+                                           entity_count, prefab, component_mapper) end
+```
+
 #### `evolved.builder_mt:has`
 
 ```lua

develop/benchmarks/clone_bmarks.lua

@@ -307,11 +307,11 @@ print '----------------------------------------'
 basics.describe_bench(
     string.format('Clone Benchmarks: Multi Clone | %d entities with 1 component', N),
     function()
-        local multi_clone = evo.multi_clone
+        local multi_clone_nr = evo.multi_clone_nr
 
         local prefab = evo.spawn { [F1] = true }
 
-        multi_clone(N, prefab)
+        multi_clone_nr(N, prefab)
 
         evo.batch_destroy(QF1)
     end)
@@ -319,12 +319,12 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Clone Benchmarks: Multi Defer Clone | %d entities with 1 component', N),
     function()
-        local multi_clone = evo.multi_clone
+        local multi_clone_nr = evo.multi_clone_nr
 
         local prefab = evo.spawn { [F1] = true }
 
         evo.defer()
-        multi_clone(N, prefab)
+        multi_clone_nr(N, prefab)
         evo.commit()
 
         evo.batch_destroy(QF1)
@@ -333,11 +333,11 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Clone Benchmarks: Multi Clone With Defaults | %d entities with 1 component', N),
     function()
-        local multi_clone = evo.multi_clone
+        local multi_clone_nr = evo.multi_clone_nr
 
         local prefab = evo.spawn { [D1] = true }
 
-        multi_clone(N, prefab)
+        multi_clone_nr(N, prefab)
 
         evo.batch_destroy(QD1)
     end)
@@ -345,11 +345,11 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Clone Benchmarks: Multi Clone | %d entities with 3 components', N),
     function()
-        local multi_clone = evo.multi_clone
+        local multi_clone_nr = evo.multi_clone_nr
 
         local prefab = evo.spawn { [F1] = true, [F2] = true, [F3] = true }
 
-        multi_clone(N, prefab)
+        multi_clone_nr(N, prefab)
 
         evo.batch_destroy(QF1)
     end)
@@ -357,12 +357,12 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Clone Benchmarks: Multi Defer Clone | %d entities with 3 components', N),
     function()
-        local multi_clone = evo.multi_clone
+        local multi_clone_nr = evo.multi_clone_nr
 
         local prefab = evo.spawn { [F1] = true, [F2] = true, [F3] = true }
 
         evo.defer()
-        multi_clone(N, prefab)
+        multi_clone_nr(N, prefab)
         evo.commit()
 
         evo.batch_destroy(QF1)
@@ -371,11 +371,11 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Clone Benchmarks: Multi Clone With Defaults | %d entities with 3 components', N),
     function()
-        local multi_clone = evo.multi_clone
+        local multi_clone_nr = evo.multi_clone_nr
 
         local prefab = evo.spawn { [D1] = true, [D2] = true, [D3] = true }
 
-        multi_clone(N, prefab)
+        multi_clone_nr(N, prefab)
 
         evo.batch_destroy(QD1)
     end)
@@ -383,11 +383,11 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Clone Benchmarks: Multi Clone | %d entities with 5 components', N),
     function()
-        local multi_clone = evo.multi_clone
+        local multi_clone_nr = evo.multi_clone_nr
 
         local prefab = evo.spawn { [F1] = true, [F2] = true, [F3] = true, [F4] = true, [F5] = true }
 
-        multi_clone(N, prefab)
+        multi_clone_nr(N, prefab)
 
         evo.batch_destroy(QF1)
     end)
@@ -395,12 +395,12 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Clone Benchmarks: Multi Defer Clone | %d entities with 5 components', N),
     function()
-        local multi_clone = evo.multi_clone
+        local multi_clone_nr = evo.multi_clone_nr
 
         local prefab = evo.spawn { [F1] = true, [F2] = true, [F3] = true, [F4] = true, [F5] = true }
 
         evo.defer()
-        multi_clone(N, prefab)
+        multi_clone_nr(N, prefab)
         evo.commit()
 
         evo.batch_destroy(QF1)
@@ -409,11 +409,11 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Clone Benchmarks: Multi Clone With Defaults | %d entities with 5 components', N),
     function()
-        local multi_clone = evo.multi_clone
+        local multi_clone_nr = evo.multi_clone_nr
 
         local prefab = evo.spawn { [D1] = true, [D2] = true, [D3] = true, [D4] = true, [D5] = true }
 
-        multi_clone(N, prefab)
+        multi_clone_nr(N, prefab)
 
         evo.batch_destroy(QD1)
     end)
@@ -423,11 +423,11 @@ print '----------------------------------------'
 basics.describe_bench(
     string.format('Clone Benchmarks: Multi Clone | %d entities with 1 required component', N),
     function()
-        local multi_clone = evo.multi_clone
+        local multi_clone_nr = evo.multi_clone_nr
 
         local prefab = evo.spawn { [RF1] = true }
 
-        multi_clone(N, prefab)
+        multi_clone_nr(N, prefab)
 
         evo.batch_destroy(QF1)
     end)
@@ -435,12 +435,12 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Clone Benchmarks: Multi Defer Clone | %d entities with 1 required component', N),
     function()
-        local multi_clone = evo.multi_clone
+        local multi_clone_nr = evo.multi_clone_nr
 
         local prefab = evo.spawn { [RF1] = true }
 
         evo.defer()
-        multi_clone(N, prefab)
+        multi_clone_nr(N, prefab)
         evo.commit()
 
         evo.batch_destroy(QF1)
@@ -449,11 +449,11 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Clone Benchmarks: Multi Clone With Defaults | %d entities with 1 required component', N),
     function()
-        local multi_clone = evo.multi_clone
+        local multi_clone_nr = evo.multi_clone_nr
 
         local prefab = evo.spawn { [RD1] = true }
 
-        multi_clone(N, prefab)
+        multi_clone_nr(N, prefab)
 
         evo.batch_destroy(QD1)
     end)
@@ -461,11 +461,11 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Clone Benchmarks: Multi Clone | %d entities with 3 required components', N),
     function()
-        local multi_clone = evo.multi_clone
+        local multi_clone_nr = evo.multi_clone_nr
 
         local prefab = evo.spawn { [RF123] = true }
 
-        multi_clone(N, prefab)
+        multi_clone_nr(N, prefab)
 
         evo.batch_destroy(QF1)
     end)
@@ -473,12 +473,12 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Clone Benchmarks: Multi Defer Clone | %d entities with 3 required components', N),
     function()
-        local multi_clone = evo.multi_clone
+        local multi_clone_nr = evo.multi_clone_nr
 
         local prefab = evo.spawn { [RF123] = true }
 
         evo.defer()
-        multi_clone(N, prefab)
+        multi_clone_nr(N, prefab)
         evo.commit()
 
         evo.batch_destroy(QF1)
@@ -487,11 +487,11 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Clone Benchmarks: Multi Clone With Defaults | %d entities with 3 required components', N),
     function()
-        local multi_clone = evo.multi_clone
+        local multi_clone_nr = evo.multi_clone_nr
 
         local prefab = evo.spawn { [RD123] = true }
 
-        multi_clone(N, prefab)
+        multi_clone_nr(N, prefab)
 
         evo.batch_destroy(QD1)
     end)
@@ -499,11 +499,11 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Clone Benchmarks: Multi Clone | %d entities with 5 required components', N),
     function()
-        local multi_clone = evo.multi_clone
+        local multi_clone_nr = evo.multi_clone_nr
 
         local prefab = evo.spawn { [RF12345] = true }
 
-        multi_clone(N, prefab)
+        multi_clone_nr(N, prefab)
 
         evo.batch_destroy(QF1)
     end)
@@ -511,12 +511,12 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Clone Benchmarks: Multi Defer Clone | %d entities with 5 required components', N),
     function()
-        local multi_clone = evo.multi_clone
+        local multi_clone_nr = evo.multi_clone_nr
 
         local prefab = evo.spawn { [RF12345] = true }
 
         evo.defer()
-        multi_clone(N, prefab)
+        multi_clone_nr(N, prefab)
         evo.commit()
 
         evo.batch_destroy(QF1)
@@ -525,11 +525,11 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Clone Benchmarks: Multi Clone With Defaults | %d entities with 5 required components', N),
     function()
-        local multi_clone = evo.multi_clone
+        local multi_clone_nr = evo.multi_clone_nr
 
         local prefab = evo.spawn { [RD12345] = true }
 
-        multi_clone(N, prefab)
+        multi_clone_nr(N, prefab)
 
         evo.batch_destroy(QD1)
     end)

develop/benchmarks/common_bmarks.lua

@@ -54,7 +54,7 @@ basics.describe_bench(string.format('Common Benchmarks: Evolved Entity Cycle | %
         local prefab_a = evo.builder():prefab():set(world):set(a, 0):spawn()
         local prefab_b = evo.builder():prefab():set(world):set(b, 0):spawn()
 
-        evo.multi_clone(N, prefab_a)
+        evo.multi_clone_nr(N, prefab_a)
 
         evo.builder()
             :set(world):group(world):query(query_a)
@@ -129,10 +129,10 @@ basics.describe_bench(string.format('Common Benchmarks: Evolved Simple Iteration
         local query_cd = evo.builder():set(world):include(c, d):spawn()
         local query_ce = evo.builder():set(world):include(c, e):spawn()
 
-        evo.multi_spawn(N, { [world] = true, [a] = 0, [b] = 0 })
-        evo.multi_spawn(N, { [world] = true, [a] = 0, [b] = 0, [c] = 0 })
-        evo.multi_spawn(N, { [world] = true, [a] = 0, [b] = 0, [c] = 0, [d] = 0 })
-        evo.multi_spawn(N, { [world] = true, [a] = 0, [b] = 0, [c] = 0, [e] = 0 })
+        evo.multi_spawn_nr(N, { [world] = true, [a] = 0, [b] = 0 })
+        evo.multi_spawn_nr(N, { [world] = true, [a] = 0, [b] = 0, [c] = 0 })
+        evo.multi_spawn_nr(N, { [world] = true, [a] = 0, [b] = 0, [c] = 0, [d] = 0 })
+        evo.multi_spawn_nr(N, { [world] = true, [a] = 0, [b] = 0, [c] = 0, [e] = 0 })
 
         evo.builder()
             :set(world):group(world):query(query_ab)
@@ -223,7 +223,7 @@ basics.describe_bench(string.format('Common Benchmarks: Evolved Packed Iteration
         local query_d = evo.builder():set(world):include(d):spawn()
         local query_e = evo.builder():set(world):include(e):spawn()
 
-        evo.multi_spawn(N, { [world] = true, [a] = 0, [b] = 0, [c] = 0, [d] = 0, [e] = 0 })
+        evo.multi_spawn_nr(N, { [world] = true, [a] = 0, [b] = 0, [c] = 0, [d] = 0, [e] = 0 })
 
         evo.builder()
             :set(world):group(world):query(query_a)
@@ -317,7 +317,7 @@ basics.describe_bench(string.format('Common Benchmarks: Evolved Fragmented Itera
         local query_z = evo.builder():set(world):include(chars[#chars]):spawn()
 
         for i = 1, #chars do
-            evo.multi_spawn(N, { [world] = true, [chars[i]] = i, [data] = i })
+            evo.multi_spawn_nr(N, { [world] = true, [chars[i]] = i, [data] = i })
         end
 
         evo.builder()

develop/benchmarks/process_bmarks.lua

@@ -20,7 +20,7 @@ basics.describe_bench(string.format('Process Benchmarks: Evolved AoS Processing
         local pf = evo.builder():set(wf):spawn()
         local vf = evo.builder():set(wf):spawn()
 
-        evo.multi_spawn(N, {
+        evo.multi_spawn_nr(N, {
             [wf] = true,
             [pf] = { x = 0, y = 0, z = 0, w = 0 },
             [vf] = { x = 0, y = 0, z = 0, w = 0 },
@@ -67,7 +67,7 @@ basics.describe_bench(string.format('Process Benchmarks: Evolved SoA Processing
         local vzf = evo.builder():set(wf):spawn()
         local vwf = evo.builder():set(wf):spawn()
 
-        evo.multi_spawn(N, {
+        evo.multi_spawn_nr(N, {
             [wf] = true,
             [pxf] = 0,
             [pyf] = 0,

develop/benchmarks/spawn_bmarks.lua

@@ -536,11 +536,11 @@ print '----------------------------------------'
 basics.describe_bench(
     string.format('Spawn Benchmarks: Multi Spawn | %d entities with 1 component', N),
     function()
-        local multi_spawn = evo.multi_spawn
+        local multi_spawn_nr = evo.multi_spawn_nr
 
         local components = { [F1] = true }
 
-        multi_spawn(N, components)
+        multi_spawn_nr(N, components)
 
         evo.batch_destroy(QF1)
     end)
@@ -548,12 +548,12 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Spawn Benchmarks: Multi Defer Spawn | %d entities with 1 component', N),
     function()
-        local multi_spawn = evo.multi_spawn
+        local multi_spawn_nr = evo.multi_spawn_nr
 
         local components = { [F1] = true }
 
         evo.defer()
-        multi_spawn(N, components)
+        multi_spawn_nr(N, components)
         evo.commit()
 
         evo.batch_destroy(QF1)
@@ -562,11 +562,11 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Spawn Benchmarks: Multi Spawn With Defaults | %d entities with 1 component', N),
     function()
-        local multi_spawn = evo.multi_spawn
+        local multi_spawn_nr = evo.multi_spawn_nr
 
         local components = { [D1] = true }
 
-        multi_spawn(N, components)
+        multi_spawn_nr(N, components)
 
         evo.batch_destroy(QD1)
     end)
@@ -574,11 +574,11 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Spawn Benchmarks: Multi Spawn | %d entities with 3 components', N),
     function()
-        local multi_spawn = evo.multi_spawn
+        local multi_spawn_nr = evo.multi_spawn_nr
 
         local components = { [F1] = true, [F2] = true, [F3] = true }
 
-        multi_spawn(N, components)
+        multi_spawn_nr(N, components)
 
         evo.batch_destroy(QF1)
     end)
@@ -586,12 +586,12 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Spawn Benchmarks: Multi Defer Spawn | %d entities with 3 components', N),
     function()
-        local multi_spawn = evo.multi_spawn
+        local multi_spawn_nr = evo.multi_spawn_nr
 
         local components = { [F1] = true, [F2] = true, [F3] = true }
 
         evo.defer()
-        multi_spawn(N, components)
+        multi_spawn_nr(N, components)
         evo.commit()
 
         evo.batch_destroy(QF1)
@@ -600,11 +600,11 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Spawn Benchmarks: Multi Spawn With Defaults | %d entities with 3 components', N),
     function()
-        local multi_spawn = evo.multi_spawn
+        local multi_spawn_nr = evo.multi_spawn_nr
 
         local components = { [D1] = true, [D2] = true, [D3] = true }
 
-        multi_spawn(N, components)
+        multi_spawn_nr(N, components)
 
         evo.batch_destroy(QD1)
     end)
@@ -612,11 +612,11 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Spawn Benchmarks: Multi Spawn | %d entities with 5 components', N),
     function()
-        local multi_spawn = evo.multi_spawn
+        local multi_spawn_nr = evo.multi_spawn_nr
 
         local components = { [F1] = true, [F2] = true, [F3] = true, [F4] = true, [F5] = true }
 
-        multi_spawn(N, components)
+        multi_spawn_nr(N, components)
 
         evo.batch_destroy(QF1)
     end)
@@ -624,12 +624,12 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Spawn Benchmarks: Multi Defer Spawn | %d entities with 5 components', N),
     function()
-        local multi_spawn = evo.multi_spawn
+        local multi_spawn_nr = evo.multi_spawn_nr
 
         local components = { [F1] = true, [F2] = true, [F3] = true, [F4] = true, [F5] = true }
 
         evo.defer()
-        multi_spawn(N, components)
+        multi_spawn_nr(N, components)
         evo.commit()
 
         evo.batch_destroy(QF1)
@@ -638,11 +638,11 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Spawn Benchmarks: Multi Spawn With Defaults | %d entities with 5 components', N),
     function()
-        local multi_spawn = evo.multi_spawn
+        local multi_spawn_nr = evo.multi_spawn_nr
 
         local components = { [D1] = true, [D2] = true, [D3] = true, [D4] = true, [D5] = true }
 
-        multi_spawn(N, components)
+        multi_spawn_nr(N, components)
 
         evo.batch_destroy(QD1)
     end)
@@ -652,11 +652,11 @@ print '----------------------------------------'
 basics.describe_bench(
     string.format('Spawn Benchmarks: Multi Spawn | %d entities with 1 required component', N),
     function()
-        local multi_spawn = evo.multi_spawn
+        local multi_spawn_nr = evo.multi_spawn_nr
 
         local components = { [F1] = true }
 
-        multi_spawn(N, components)
+        multi_spawn_nr(N, components)
 
         evo.batch_destroy(QF1)
     end)
@@ -664,12 +664,12 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Spawn Benchmarks: Multi Defer Spawn | %d entities with 1 required component', N),
     function()
-        local multi_spawn = evo.multi_spawn
+        local multi_spawn_nr = evo.multi_spawn_nr
 
         local components = { [F1] = true }
 
         evo.defer()
-        multi_spawn(N, components)
+        multi_spawn_nr(N, components)
         evo.commit()
 
         evo.batch_destroy(QF1)
@@ -678,11 +678,11 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Spawn Benchmarks: Multi Spawn With Defaults | %d entities with 1 required component', N),
     function()
-        local multi_spawn = evo.multi_spawn
+        local multi_spawn_nr = evo.multi_spawn_nr
 
         local components = { [D1] = true }
 
-        multi_spawn(N, components)
+        multi_spawn_nr(N, components)
 
         evo.batch_destroy(QD1)
     end)
@@ -690,11 +690,11 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Spawn Benchmarks: Multi Spawn | %d entities with 3 required components', N),
     function()
-        local multi_spawn = evo.multi_spawn
+        local multi_spawn_nr = evo.multi_spawn_nr
 
         local components = { [RF123] = true }
 
-        multi_spawn(N, components)
+        multi_spawn_nr(N, components)
 
         evo.batch_destroy(QF1)
     end)
@@ -702,12 +702,12 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Spawn Benchmarks: Multi Defer Spawn | %d entities with 3 required components', N),
     function()
-        local multi_spawn = evo.multi_spawn
+        local multi_spawn_nr = evo.multi_spawn_nr
 
         local components = { [RF123] = true }
 
         evo.defer()
-        multi_spawn(N, components)
+        multi_spawn_nr(N, components)
         evo.commit()
 
         evo.batch_destroy(QF1)
@@ -716,11 +716,11 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Spawn Benchmarks: Multi Spawn With Defaults | %d entities with 3 required components', N),
     function()
-        local multi_spawn = evo.multi_spawn
+        local multi_spawn_nr = evo.multi_spawn_nr
 
         local components = { [RD123] = true }
 
-        multi_spawn(N, components)
+        multi_spawn_nr(N, components)
 
         evo.batch_destroy(QD1)
     end)
@@ -728,11 +728,11 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Spawn Benchmarks: Multi Spawn | %d entities with 5 required components', N),
     function()
-        local multi_spawn = evo.multi_spawn
+        local multi_spawn_nr = evo.multi_spawn_nr
 
         local components = { [RF12345] = true }
 
-        multi_spawn(N, components)
+        multi_spawn_nr(N, components)
 
         evo.batch_destroy(QF1)
     end)
@@ -740,12 +740,12 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Spawn Benchmarks: Multi Defer Spawn | %d entities with 5 required components', N),
     function()
-        local multi_spawn = evo.multi_spawn
+        local multi_spawn_nr = evo.multi_spawn_nr
 
         local components = { [RF12345] = true }
 
         evo.defer()
-        multi_spawn(N, components)
+        multi_spawn_nr(N, components)
         evo.commit()
 
         evo.batch_destroy(QF1)
@@ -754,11 +754,11 @@ basics.describe_bench(
 basics.describe_bench(
     string.format('Spawn Benchmarks: Multi Spawn With Defaults | %d entities with 5 required components', N),
     function()
-        local multi_spawn = evo.multi_spawn
+        local multi_spawn_nr = evo.multi_spawn_nr
 
         local components = { [RD12345] = true }
 
-        multi_spawn(N, components)
+        multi_spawn_nr(N, components)
 
         evo.batch_destroy(QD1)
     end)

develop/testing/clone_tests.lua

@@ -397,3 +397,165 @@ do
         end
     end
 end
+
+do
+    local f1, f2 = evo.id(2)
+    local p = evo.spawn { [f1] = 42, [f2] = 'hello' }
+
+    do
+        local entity_list, entity_count = {}, 2
+        evo.multi_clone_to(entity_list, 1, entity_count, p)
+        assert(evo.has_all(entity_list[1], f1, f2))
+        assert(evo.has_all(entity_list[2], f1, f2))
+        assert(evo.get(entity_list[1], f1) == 42 and evo.get(entity_list[1], f2) == 'hello')
+        assert(evo.get(entity_list[2], f1) == 42 and evo.get(entity_list[2], f2) == 'hello')
+    end
+
+    do
+        local entity_list, entity_count = {}, 2
+        evo.multi_clone_to(entity_list, 2, entity_count, p)
+        assert(evo.has_all(entity_list[2], f1, f2))
+        assert(evo.has_all(entity_list[3], f1, f2))
+        assert(evo.get(entity_list[2], f1) == 42 and evo.get(entity_list[2], f2) == 'hello')
+        assert(evo.get(entity_list[3], f1) == 42 and evo.get(entity_list[3], f2) == 'hello')
+    end
+
+    do
+        local entity_list, entity_count = {}, 2
+        evo.defer()
+        evo.multi_clone_to(entity_list, 1, entity_count, p)
+        assert(entity_list[1] and entity_list[2])
+        assert(evo.empty_all(entity_list[1], entity_list[2]))
+        evo.commit()
+        assert(evo.has_all(entity_list[1], f1, f2))
+        assert(evo.has_all(entity_list[2], f1, f2))
+        assert(evo.get(entity_list[1], f1) == 42 and evo.get(entity_list[1], f2) == 'hello')
+        assert(evo.get(entity_list[2], f1) == 42 and evo.get(entity_list[2], f2) == 'hello')
+    end
+
+    do
+        local entity_list, entity_count = {}, 2
+        evo.defer()
+        evo.multi_clone_to(entity_list, 2, entity_count, p)
+        assert(entity_list[2] and entity_list[3])
+        assert(evo.empty_all(entity_list[2], entity_list[3]))
+        evo.commit()
+        assert(evo.has_all(entity_list[2], f1, f2))
+        assert(evo.has_all(entity_list[3], f1, f2))
+        assert(evo.get(entity_list[2], f1) == 42 and evo.get(entity_list[2], f2) == 'hello')
+        assert(evo.get(entity_list[3], f1) == 42 and evo.get(entity_list[3], f2) == 'hello')
+    end
+end
+
+do
+    local f1, f2 = evo.id(2)
+    local q12 = evo.builder():include(f1, f2):build()
+    local p = evo.spawn { [f1] = 42, [f2] = 'hello' }
+
+    do
+        assert(select('#', evo.multi_clone_nr(2, p)) == 0)
+
+        do
+            local entity_count = 0
+
+            for chunk in evo.execute(q12) do
+                local _, chunk_entity_count = chunk:entities()
+                entity_count = entity_count + chunk_entity_count
+            end
+
+            assert(entity_count == 3)
+        end
+    end
+
+    do
+        local b = evo.builder():set(f1, 42):set(f2, 'hello')
+
+        assert(select('#', b:multi_clone_nr(2, p)) == 0)
+
+        do
+            local entity_count = 0
+
+            for chunk in evo.execute(q12) do
+                local _, chunk_entity_count = chunk:entities()
+                entity_count = entity_count + chunk_entity_count
+            end
+
+            assert(entity_count == 5)
+        end
+    end
+
+    do
+        local b = evo.builder():set(f1, 42):set(f2, 'hello')
+
+        assert(select('#', b:multi_build_nr(2, p)) == 0)
+
+        do
+            local entity_count = 0
+
+            for chunk in evo.execute(q12) do
+                local _, chunk_entity_count = chunk:entities()
+                entity_count = entity_count + chunk_entity_count
+            end
+
+            assert(entity_count == 7)
+        end
+    end
+end
+
+do
+    local f1, f2 = evo.id(2)
+    local q12 = evo.builder():include(f1, f2):build()
+    local p = evo.spawn { [f1] = 42, [f2] = 'hello' }
+
+    do
+        local entity_list = {}
+        assert(select('#', evo.multi_clone_to(entity_list, 1, 2, p)) == 0)
+
+        do
+            local entity_count = 0
+
+            for chunk in evo.execute(q12) do
+                local _, chunk_entity_count = chunk:entities()
+                entity_count = entity_count + chunk_entity_count
+            end
+
+            assert(entity_count == 3)
+        end
+    end
+
+    do
+        local b = evo.builder():set(f1, 42):set(f2, 'hello')
+
+        local entity_list = {}
+        assert(select('#', b:multi_clone_to(entity_list, 1, 2, p)) == 0)
+
+        do
+            local entity_count = 0
+
+            for chunk in evo.execute(q12) do
+                local _, chunk_entity_count = chunk:entities()
+                entity_count = entity_count + chunk_entity_count
+            end
+
+            assert(entity_count == 5)
+        end
+    end
+
+    do
+        local b = evo.builder():set(f1, 42):set(f2, 'hello')
+
+        local entity_list = {}
+        assert(select('#', b:multi_build_to(entity_list, 1, 2, p)) == 0)
+
+        do
+            local entity_count = 0
+
+            for chunk in evo.execute(q12) do
+                local _, chunk_entity_count = chunk:entities()
+                entity_count = entity_count + chunk_entity_count
+            end
+
+            assert(entity_count == 7)
+        end
+    end
+end

develop/testing/lookup_tests.lua

@@ -174,3 +174,22 @@ do
         assert(entity_list and #entity_list == 0 and entity_count == 0)
     end
 end
+
+do
+    local e1, e2 = evo.id(2)
+
+    evo.set(e1, evo.NAME, 'lookup_e')
+    evo.set(e2, evo.NAME, 'lookup_e')
+
+    do
+        local entity_list = {}
+        local entity_count = evo.multi_lookup_to(entity_list, 1, 'lookup_e')
+        assert(entity_count == 2 and entity_list[1] == e1 and entity_list[2] == e2)
+    end
+
+    do
+        local entity_list = {}
+        local entity_count = evo.multi_lookup_to(entity_list, 2, 'lookup_e')
+        assert(entity_count == 2 and entity_list[2] == e1 and entity_list[3] == e2)
+    end
+end

develop/testing/multi_spawn_tests.lua

@@ -607,3 +607,164 @@ do
         end
     end
 end
+
+do
+    local f1, f2 = evo.id(2)
+
+    do
+        local entity_list, entity_count = {}, 2
+        evo.multi_spawn_to(entity_list, 1, entity_count, { [f1] = 42, [f2] = "hello" })
+        assert(evo.has_all(entity_list[1], f1, f2))
+        assert(evo.has_all(entity_list[2], f1, f2))
+        assert(evo.get(entity_list[1], f1) == 42 and evo.get(entity_list[1], f2) == "hello")
+        assert(evo.get(entity_list[2], f1) == 42 and evo.get(entity_list[2], f2) == "hello")
+    end
+
+    do
+        local entity_list, entity_count = {}, 2
+        evo.multi_spawn_to(entity_list, 2, entity_count, { [f1] = 42, [f2] = "hello" })
+        assert(evo.has_all(entity_list[2], f1, f2))
+        assert(evo.has_all(entity_list[3], f1, f2))
+        assert(evo.get(entity_list[2], f1) == 42 and evo.get(entity_list[2], f2) == "hello")
+        assert(evo.get(entity_list[3], f1) == 42 and evo.get(entity_list[3], f2) == "hello")
+    end
+
+    do
+        local entity_list, entity_count = {}, 2
+        evo.defer()
+        evo.multi_spawn_to(entity_list, 1, entity_count, { [f1] = 42, [f2] = "hello" })
+        assert(entity_list[1] and entity_list[2])
+        assert(evo.empty_all(entity_list[1], entity_list[2]))
+        evo.commit()
+        assert(evo.has_all(entity_list[1], f1, f2))
+        assert(evo.has_all(entity_list[2], f1, f2))
+        assert(evo.get(entity_list[1], f1) == 42 and evo.get(entity_list[1], f2) == "hello")
+        assert(evo.get(entity_list[2], f1) == 42 and evo.get(entity_list[2], f2) == "hello")
+    end
+
+    do
+        local entity_list, entity_count = {}, 2
+        evo.defer()
+        evo.multi_spawn_to(entity_list, 2, entity_count, { [f1] = 42, [f2] = "hello" })
+        assert(entity_list[2] and entity_list[3])
+        assert(evo.empty_all(entity_list[2], entity_list[3]))
+        evo.commit()
+        assert(evo.has_all(entity_list[2], f1, f2))
+        assert(evo.has_all(entity_list[3], f1, f2))
+        assert(evo.get(entity_list[2], f1) == 42 and evo.get(entity_list[2], f2) == "hello")
+        assert(evo.get(entity_list[3], f1) == 42 and evo.get(entity_list[3], f2) == "hello")
+    end
+end
+
+do
+    local f1, f2 = evo.id(2)
+    local q12 = evo.builder():include(f1, f2):spawn()
+
+    do
+        assert(select('#', evo.multi_spawn_nr(2, { [f1] = 42, [f2] = "hello" })) == 0)
+
+        do
+            local entity_count = 0
+
+            for chunk in evo.execute(q12) do
+                local _, chunk_entity_count = chunk:entities()
+                entity_count = entity_count + chunk_entity_count
+            end
+
+            assert(entity_count == 2)
+        end
+    end
+
+    do
+        local b = evo.builder():set(f1, 42):set(f2, "hello")
+
+        assert(select('#', b:multi_spawn_nr(2)) == 0)
+
+        do
+            local entity_count = 0
+
+            for chunk in evo.execute(q12) do
+                local _, chunk_entity_count = chunk:entities()
+                entity_count = entity_count + chunk_entity_count
+            end
+
+            assert(entity_count == 4)
+        end
+    end
+
+    do
+        local b = evo.builder():set(f1, 42):set(f2, "hello")
+
+        assert(select('#', b:multi_build_nr(2)) == 0)
+
+        do
+            local entity_count = 0
+
+            for chunk in evo.execute(q12) do
+                local _, chunk_entity_count = chunk:entities()
+                entity_count = entity_count + chunk_entity_count
+            end
+
+            assert(entity_count == 6)
+        end
+    end
+end
+
+do
+    local f1, f2 = evo.id(2)
+    local q12 = evo.builder():include(f1, f2):spawn()
+
+    do
+        local entity_list = {}
+        assert(select('#', evo.multi_spawn_to(entity_list, 1, 2, { [f1] = 42, [f2] = "hello" })) == 0)
+
+        do
+            local entity_count = 0
+
+            for chunk in evo.execute(q12) do
+                local _, chunk_entity_count = chunk:entities()
+                entity_count = entity_count + chunk_entity_count
+            end
+
+            assert(entity_count == 2)
+        end
+    end
+
+    do
+        local b = evo.builder():set(f1, 42):set(f2, "hello")
+
+
+        local entity_list = {}
+        assert(select('#', b:multi_spawn_to(entity_list, 1, 2)) == 0)
+
+        do
+            local entity_count = 0
+
+            for chunk in evo.execute(q12) do
+                local _, chunk_entity_count = chunk:entities()
+                entity_count = entity_count + chunk_entity_count
+            end
+
+            assert(entity_count == 4)
+        end
+    end
+
+    do
+        local b = evo.builder():set(f1, 42):set(f2, "hello")
+
+
+        local entity_list = {}
+        assert(select('#', b:multi_build_to(entity_list, 1, 2)) == 0)
+
+        do
+            local entity_count = 0
+
+            for chunk in evo.execute(q12) do
+                local _, chunk_entity_count = chunk:entities()
+                entity_count = entity_count + chunk_entity_count
+            end
+
+            assert(entity_count == 6)
+        end
+    end
+end

evolved.d.tl

@@ -40,6 +40,18 @@
             prefab?: Entity,
             component_mapper?: function(Chunk, integer, integer)): { Entity }, integer
 
+        multi_build_nr: function(self: Builder,
+            entity_count: integer,
+            prefab?: Entity,
+            component_mapper?: function(Chunk, integer, integer))
+
+        multi_build_to: function(self: Builder,
+            out_entity_list: { Entity },
+            out_entity_first: integer,
+            entity_count: integer,
+            prefab?: Entity,
+            component_mapper?: function(Chunk, integer, integer))
+
         spawn: function(self: Builder,
             component_mapper?: function(Chunk, integer)): Entity
 
@@ -47,6 +59,16 @@
             entity_count: integer,
             component_mapper?: function(Chunk, integer, integer)): { Entity }, integer
 
+        multi_spawn_nr: function(self: Builder,
+            entity_count: integer,
+            component_mapper?: function(Chunk, integer, integer))
+
+        multi_spawn_to: function(self: Builder,
+            out_entity_list: { Entity },
+            out_entity_first: integer,
+            entity_count: integer,
+            component_mapper?: function(Chunk, integer, integer))
+
         clone: function(self: Builder,
             prefab: Entity,
             component_mapper?: function(Chunk, integer)): Entity
@@ -56,6 +78,18 @@
             prefab: Entity,
             component_mapper?: function(Chunk, integer, integer)): { Entity }, integer
 
+        multi_clone_nr: function(self: Builder,
+            entity_count: integer,
+            prefab: Entity,
+            component_mapper?: function(Chunk, integer, integer))
+
+        multi_clone_to: function(self: Builder,
+            out_entity_list: { Entity },
+            out_entity_first: integer,
+            entity_count: integer,
+            prefab: Entity,
+            component_mapper?: function(Chunk, integer, integer))
+
         has: function(self: Builder, fragment: Fragment): boolean
         has_all: function(self: Builder, ...: Fragment): boolean
         has_any: function(self: Builder, ...: Fragment): boolean
@@ -164,6 +198,18 @@
         component_table?: { Fragment: any },
         component_mapper?: function(Chunk, integer, integer)): { Entity }, integer
 
+    multi_spawn_nr: function(
+        entity_count: integer,
+        component_table?: { Fragment: any },
+        component_mapper?: function(Chunk, integer, integer))
+
+    multi_spawn_to: function(
+        out_entity_list: { Entity },
+        out_entity_first: integer,
+        entity_count: integer,
+        component_table?: { Fragment: any },
+        component_mapper?: function(Chunk, integer, integer))
+
     clone: function(
         prefab: Entity,
         component_table?: { Fragment: any },
@@ -175,6 +221,20 @@
         component_table?: { Fragment: any },
         component_mapper?: function(Chunk, integer, integer)): { Entity }, integer
 
+    multi_clone_nr: function(
+        entity_count: integer,
+        prefab: Entity,
+        component_table?: { Fragment: any },
+        component_mapper?: function(Chunk, integer, integer))
+
+    multi_clone_to: function(
+        out_entity_list: { Entity },
+        out_entity_first: integer,
+        entity_count: integer,
+        prefab: Entity,
+        component_table?: { Fragment: any },
+        component_mapper?: function(Chunk, integer, integer))
+
     alive: function(entity: Entity): boolean
     alive_all: function(...: Entity): boolean
     alive_any: function(...: Entity): boolean
@@ -210,6 +270,7 @@
 
     lookup: function(name: string): Entity | nil
     multi_lookup: function(name: string): { Entity }, integer
+    multi_lookup_to: function(out_entity_list: { Entity }, out_entity_first: integer, name: string): integer
 
     process: function(...: System)
     process_with: function(system: System, ...: any)

evolved.lua

@@ -1149,11 +1149,6 @@ local __DESTRUCTION_POLICY_REMOVE_FRAGMENT = __acquire_id()
 ---
 
 local __safe_tbls = {
-    __EMPTY_ENTITY_LIST = __lua_setmetatable({}, {
-        __tostring = function() return 'empty entity list' end,
-        __newindex = function() __error_fmt 'attempt to modify empty entity list' end
-    }) --[=[@as evolved.id[]]=],
-
     __EMPTY_FRAGMENT_SET = __lua_setmetatable({}, {
         __tostring = function() return 'empty fragment set' end,
         __newindex = function() __error_fmt 'attempt to modify empty fragment set' end
@@ -1184,9 +1179,13 @@ local __evolved_cancel
 
 local __evolved_spawn
 local __evolved_multi_spawn
+local __evolved_multi_spawn_nr
+local __evolved_multi_spawn_to
 
 local __evolved_clone
 local __evolved_multi_clone
+local __evolved_multi_clone_nr
+local __evolved_multi_clone_to
 
 local __evolved_alive
 local __evolved_alive_all
@@ -1221,6 +1220,7 @@ local __evolved_locate
 
 local __evolved_lookup
 local __evolved_multi_lookup
+local __evolved_multi_lookup_to
 
 local __evolved_process
 local __evolved_process_with
@@ -2681,10 +2681,11 @@ end
 
 ---@param chunk? evolved.chunk
 ---@param entity_list evolved.entity[]
+---@param entity_first integer
 ---@param entity_count integer
 ---@param component_table? evolved.component_table
 ---@param component_mapper? evolved.component_mapper
-function __multi_spawn_entity(chunk, entity_list, entity_count, component_table, component_mapper)
+function __multi_spawn_entity(chunk, entity_list, entity_first, entity_count, component_table, component_mapper)
     if __defer_depth <= 0 then
         __error_fmt('spawn entity operations should be deferred')
     end
@@ -2732,7 +2733,7 @@ function __multi_spawn_entity(chunk, entity_list, entity_count, component_table,
         local entity_places = __entity_places
 
         for place = b_place, e_place do
-            local entity = entity_list[place - b_place + 1]
+            local entity = entity_list[place - b_place + entity_first]
             chunk_entity_list[place] = entity
 
             local entity_primary = entity % 2 ^ 20
@@ -2980,10 +2981,11 @@ end
 
 ---@param prefab evolved.entity
 ---@param entity_list evolved.entity[]
+---@param entity_first integer
 ---@param entity_count integer
 ---@param component_table? evolved.component_table
 ---@param component_mapper? evolved.component_mapper
-function __multi_clone_entity(prefab, entity_list, entity_count, component_table, component_mapper)
+function __multi_clone_entity(prefab, entity_list, entity_first, entity_count, component_table, component_mapper)
     if __defer_depth <= 0 then
         __error_fmt('clone entity operations should be deferred')
     end
@@ -2999,7 +3001,9 @@ function __multi_clone_entity(prefab, entity_list, entity_count, component_table
     end
 
     if not prefab_chunk or not prefab_chunk.__without_unique_fragments then
-        return __multi_spawn_entity(nil, entity_list, entity_count, component_table, component_mapper)
+        return __multi_spawn_entity(nil,
+            entity_list, entity_first, entity_count,
+            component_table, component_mapper)
     end
 
     local chunk = component_table
@@ -3048,7 +3052,7 @@ function __multi_clone_entity(prefab, entity_list, entity_count, component_table
         local entity_places = __entity_places
 
         for place = b_place, e_place do
-            local entity = entity_list[place - b_place + 1]
+            local entity = entity_list[place - b_place + entity_first]
             chunk_entity_list[place] = entity
 
             local entity_primary = entity % 2 ^ 20
@@ -4379,10 +4383,10 @@ function __defer_spawn_entity(chunk, entity, component_table, component_mapper)
 end
 
 __defer_ops[__defer_op.spawn_entity] = function(bytes, index)
-    local chunk = bytes[index + 0]
-    local entity = bytes[index + 1]
-    local component_table2 = bytes[index + 2]
-    local component_mapper = bytes[index + 3]
+    local chunk = bytes[index + 0] ---@type evolved.chunk
+    local entity = bytes[index + 1] ---@type evolved.entity
+    local component_table2 = bytes[index + 2] ---@type evolved.component_table?
+    local component_mapper = bytes[index + 3] ---@type evolved.component_mapper?
 
     __evolved_defer()
     do
@@ -4399,15 +4403,16 @@ end
 
 ---@param chunk? evolved.chunk
 ---@param entity_list evolved.entity[]
+---@param entity_first integer
 ---@param entity_count integer
 ---@param component_table? evolved.component_table
 ---@param component_mapper? evolved.component_mapper
-function __defer_multi_spawn_entity(chunk, entity_list, entity_count, component_table, component_mapper)
+function __defer_multi_spawn_entity(chunk, entity_list, entity_first, entity_count, component_table, component_mapper)
     ---@type evolved.entity[]
     local entity_list2 = __acquire_table(__table_pool_tag.entity_list)
 
     __lua_table_move(
-        entity_list, 1, entity_count,
+        entity_list, entity_first, entity_first + entity_count - 1,
         1, entity_list2)
 
     ---@type evolved.component_table?
@@ -4435,15 +4440,17 @@ function __defer_multi_spawn_entity(chunk, entity_list, entity_count, component_
 end
 
 __defer_ops[__defer_op.multi_spawn_entity] = function(bytes, index)
-    local chunk = bytes[index + 0]
-    local entity_count = bytes[index + 1]
-    local entity_list2 = bytes[index + 2]
-    local component_table2 = bytes[index + 3]
-    local component_mapper = bytes[index + 4]
+    local chunk = bytes[index + 0] ---@type evolved.chunk
+    local entity_count = bytes[index + 1] ---@type integer
+    local entity_list2 = bytes[index + 2] ---@type evolved.entity[]
+    local component_table2 = bytes[index + 3] ---@type evolved.component_table?
+    local component_mapper = bytes[index + 4] ---@type evolved.component_mapper?
 
     __evolved_defer()
     do
-        __multi_spawn_entity(chunk, entity_list2, entity_count, component_table2, component_mapper)
+        __multi_spawn_entity(chunk,
+            entity_list2, 1, entity_count,
+            component_table2, component_mapper)
 
         if entity_list2 then
             __release_table(__table_pool_tag.entity_list, entity_list2, false, true)
@@ -4487,10 +4494,10 @@ function __defer_clone_entity(prefab, entity, component_table, component_mapper)
 end
 
 __defer_ops[__defer_op.clone_entity] = function(bytes, index)
-    local prefab = bytes[index + 0]
-    local entity = bytes[index + 1]
-    local component_table2 = bytes[index + 2]
-    local component_mapper = bytes[index + 3]
+    local prefab = bytes[index + 0] ---@type evolved.entity
+    local entity = bytes[index + 1] ---@type evolved.entity
+    local component_table2 = bytes[index + 2] ---@type evolved.component_table?
+    local component_mapper = bytes[index + 3] ---@type evolved.component_mapper?
 
     __evolved_defer()
     do
@@ -4507,15 +4514,16 @@ end
 
 ---@param prefab evolved.entity
 ---@param entity_list evolved.entity[]
+---@param entity_first integer
 ---@param entity_count integer
 ---@param component_table? evolved.component_table
 ---@param component_mapper? evolved.component_mapper
-function __defer_multi_clone_entity(prefab, entity_list, entity_count, component_table, component_mapper)
+function __defer_multi_clone_entity(prefab, entity_list, entity_first, entity_count, component_table, component_mapper)
     ---@type evolved.entity[]
     local entity_list2 = __acquire_table(__table_pool_tag.entity_list)
 
     __lua_table_move(
-        entity_list, 1, entity_count,
+        entity_list, entity_first, entity_first + entity_count - 1,
         1, entity_list2)
 
     ---@type evolved.component_table?
@@ -4543,15 +4551,17 @@ function __defer_multi_clone_entity(prefab, entity_list, entity_count, component
 end
 
 __defer_ops[__defer_op.multi_clone_entity] = function(bytes, index)
-    local prefab = bytes[index + 0]
-    local entity_count = bytes[index + 1]
-    local entity_list2 = bytes[index + 2]
-    local component_table2 = bytes[index + 3]
-    local component_mapper = bytes[index + 4]
+    local prefab = bytes[index + 0] ---@type evolved.entity
+    local entity_count = bytes[index + 1] ---@type integer
+    local entity_list2 = bytes[index + 2] ---@type evolved.entity[]
+    local component_table2 = bytes[index + 3] ---@type evolved.component_table?
+    local component_mapper = bytes[index + 4] ---@type evolved.component_mapper?
 
     __evolved_defer()
     do
-        __multi_clone_entity(prefab, entity_list2, entity_count, component_table2, component_mapper)
+        __multi_clone_entity(prefab,
+            entity_list2, 1, entity_count,
+            component_table2, component_mapper)
 
         if entity_list2 then
             __release_table(__table_pool_tag.entity_list, entity_list2, false, true)
@@ -4922,9 +4932,47 @@ end
 ---@param component_mapper? evolved.component_mapper
 ---@return evolved.entity[] entity_list
 ---@return integer entity_count
+---@nodiscard
 function __evolved_multi_spawn(entity_count, component_table, component_mapper)
     if entity_count <= 0 then
-        return __safe_tbls.__EMPTY_ENTITY_LIST, 0
+        return {}, 0
+    end
+
+    local entity_list = __lua_table_new(entity_count)
+
+    __evolved_multi_spawn_to(
+        entity_list, 1, entity_count,
+        component_table, component_mapper)
+
+    return entity_list, entity_count
+end
+
+---@param entity_count integer
+---@param component_table? evolved.component_table
+---@param component_mapper? evolved.component_mapper
+function __evolved_multi_spawn_nr(entity_count, component_table, component_mapper)
+    if entity_count <= 0 then
+        return
+    end
+
+    local entity_list = __acquire_table(__table_pool_tag.entity_list)
+
+    __evolved_multi_spawn_to(
+        entity_list, 1, entity_count,
+        component_table, component_mapper)
+
+    __release_table(__table_pool_tag.entity_list, entity_list, false, true)
+end
+
+---@param out_entity_list evolved.entity[]
+---@param out_entity_first integer
+---@param entity_count integer
+---@param component_table? evolved.component_table
+---@param component_mapper? evolved.component_mapper
+function __evolved_multi_spawn_to(out_entity_list, out_entity_first,
+                                  entity_count, component_table, component_mapper)
+    if entity_count <= 0 then
+        return
     end
 
     if __debug_mode then
@@ -4938,27 +4986,27 @@ function __evolved_multi_spawn(entity_count, component_table, component_mapper)
         end
     end
 
-    local entity_list = __lua_table_new(entity_count)
-
-    for entity_index = 1, entity_count do
-        entity_list[entity_index] = __acquire_id()
+    for entity_index = out_entity_first, out_entity_first + entity_count - 1 do
+        out_entity_list[entity_index] = __acquire_id()
     end
 
     if not component_table or not __lua_next(component_table) then
-        return entity_list, entity_count
+        return
     end
 
     if __defer_depth > 0 then
-        __defer_multi_spawn_entity(nil, entity_list, entity_count, component_table, component_mapper)
+        __defer_multi_spawn_entity(nil,
+            out_entity_list, out_entity_first, entity_count,
+            component_table, component_mapper)
     else
         __evolved_defer()
         do
-            __multi_spawn_entity(nil, entity_list, entity_count, component_table, component_mapper)
+            __multi_spawn_entity(nil,
+                out_entity_list, out_entity_first, entity_count,
+                component_table, component_mapper)
         end
         __evolved_commit()
     end
-
-    return entity_list, entity_count
 end
 
 ---@param prefab evolved.entity
@@ -5003,9 +5051,49 @@ end
 ---@param component_mapper? evolved.component_mapper
 ---@return evolved.entity[] entity_list
 ---@return integer entity_count
+---@nodiscard
 function __evolved_multi_clone(entity_count, prefab, component_table, component_mapper)
     if entity_count <= 0 then
-        return __safe_tbls.__EMPTY_ENTITY_LIST, 0
+        return {}, 0
+    end
+
+    local entity_list = __lua_table_new(entity_count)
+
+    __evolved_multi_clone_to(
+        entity_list, 1, entity_count,
+        prefab, component_table, component_mapper)
+
+    return entity_list, entity_count
+end
+
+---@param entity_count integer
+---@param prefab evolved.entity
+---@param component_table? evolved.component_table
+---@param component_mapper? evolved.component_mapper
+function __evolved_multi_clone_nr(entity_count, prefab, component_table, component_mapper)
+    if entity_count <= 0 then
+        return
+    end
+
+    local entity_list = __acquire_table(__table_pool_tag.entity_list)
+
+    __evolved_multi_clone_to(
+        entity_list, 1, entity_count,
+        prefab, component_table, component_mapper)
+
+    __release_table(__table_pool_tag.entity_list, entity_list, false, true)
+end
+
+---@param out_entity_list evolved.entity[]
+---@param out_entity_first integer
+---@param entity_count integer
+---@param prefab evolved.entity
+---@param component_table? evolved.component_table
+---@param component_mapper? evolved.component_mapper
+function __evolved_multi_clone_to(out_entity_list, out_entity_first,
+                                  entity_count, prefab, component_table, component_mapper)
+    if entity_count <= 0 then
+        return
     end
 
     if __debug_mode then
@@ -5024,23 +5112,23 @@ function __evolved_multi_clone(entity_count, prefab, component_table, component_
         end
     end
 
-    local entity_list = __lua_table_new(entity_count)
-
-    for entity_index = 1, entity_count do
-        entity_list[entity_index] = __acquire_id()
+    for entity_index = out_entity_first, out_entity_first + entity_count - 1 do
+        out_entity_list[entity_index] = __acquire_id()
     end
 
     if __defer_depth > 0 then
-        __defer_multi_clone_entity(prefab, entity_list, entity_count, component_table, component_mapper)
+        __defer_multi_clone_entity(prefab,
+            out_entity_list, out_entity_first, entity_count,
+            component_table, component_mapper)
     else
         __evolved_defer()
         do
-            __multi_clone_entity(prefab, entity_list, entity_count, component_table, component_mapper)
+            __multi_clone_entity(prefab,
+                out_entity_list, out_entity_first, entity_count,
+                component_table, component_mapper)
         end
         __evolved_commit()
     end
-
-    return entity_list, entity_count
 end
 
 ---@param entity evolved.entity
@@ -6165,13 +6253,26 @@ end
 ---@return integer entity_count
 ---@nodiscard
 function __evolved_multi_lookup(name)
+    local entity_list = {}
+    local entity_count = __evolved_multi_lookup_to(entity_list, 1, name)
+    return entity_list, entity_count
+end
+
+---@param out_entity_list evolved.entity[]
+---@param out_entity_first integer
+---@param name string
+---@return integer entity_count
+function __evolved_multi_lookup_to(out_entity_list, out_entity_first, name)
     do
         local named_entities = __named_entities[name]
         local named_entity_list = named_entities and named_entities.__item_list
         local named_entity_count = named_entities and named_entities.__item_count or 0
 
         if named_entity_count > 0 then
-            return __list_fns.dup(named_entity_list, named_entity_count), named_entity_count
+            __lua_table_move(
+                named_entity_list, 1, named_entity_count,
+                out_entity_first, out_entity_list)
+            return named_entity_count
         end
     end
 
@@ -6179,11 +6280,12 @@ function __evolved_multi_lookup(name)
         local named_entity = __named_entity[name]
 
         if named_entity then
-            return { named_entity }, 1
+            out_entity_list[out_entity_first] = named_entity
+            return 1
         end
     end
 
-    return __safe_tbls.__EMPTY_ENTITY_LIST, 0
+    return 0
 end
 
 ---@param ... evolved.system systems
@@ -6531,6 +6633,7 @@ end
 ---@param component_mapper? evolved.component_mapper
 ---@return evolved.entity[] entity_list
 ---@return integer entity_count
+---@nodiscard
 function __builder_mt:multi_build(entity_count, prefab, component_mapper)
     if prefab then
         return self:multi_clone(entity_count, prefab, component_mapper)
@@ -6539,6 +6642,31 @@ function __builder_mt:multi_build(entity_count, prefab, component_mapper)
     end
 end
 
+---@param entity_count integer
+---@param prefab? evolved.entity
+---@param component_mapper? evolved.component_mapper
+function __builder_mt:multi_build_nr(entity_count, prefab, component_mapper)
+    if prefab then
+        self:multi_clone_nr(entity_count, prefab, component_mapper)
+    else
+        self:multi_spawn_nr(entity_count, component_mapper)
+    end
+end
+
+---@param out_entity_list evolved.entity[]
+---@param out_entity_first integer
+---@param entity_count integer
+---@param prefab? evolved.entity
+---@param component_mapper? evolved.component_mapper
+function __builder_mt:multi_build_to(out_entity_list, out_entity_first,
+                                     entity_count, prefab, component_mapper)
+    if prefab then
+        self:multi_clone_to(out_entity_list, out_entity_first, entity_count, prefab, component_mapper)
+    else
+        self:multi_spawn_to(out_entity_list, out_entity_first, entity_count, component_mapper)
+    end
+end
+
 ---@param component_mapper? evolved.component_mapper
 ---@return evolved.entity entity
 function __builder_mt:spawn(component_mapper)
@@ -6579,9 +6707,41 @@ end
 ---@param component_mapper? evolved.component_mapper
 ---@return evolved.entity[] entity_list
 ---@return integer entity_count
+---@nodiscard
 function __builder_mt:multi_spawn(entity_count, component_mapper)
     if entity_count <= 0 then
-        return __safe_tbls.__EMPTY_ENTITY_LIST, 0
+        return {}, 0
+    end
+
+    local entity_list = __lua_table_new(entity_count)
+
+    self:multi_spawn_to(entity_list, 1, entity_count, component_mapper)
+
+    return entity_list, entity_count
+end
+
+---@param entity_count integer
+---@param component_mapper? evolved.component_mapper
+function __builder_mt:multi_spawn_nr(entity_count, component_mapper)
+    if entity_count <= 0 then
+        return
+    end
+
+    local entity_list = __acquire_table(__table_pool_tag.entity_list)
+
+    self:multi_spawn_to(entity_list, 1, entity_count, component_mapper)
+
+    __release_table(__table_pool_tag.entity_list, entity_list, false, true)
+end
+
+---@param out_entity_list evolved.entity[]
+---@param out_entity_first integer
+---@param entity_count integer
+---@param component_mapper? evolved.component_mapper
+function __builder_mt:multi_spawn_to(out_entity_list, out_entity_first,
+                                     entity_count, component_mapper)
+    if entity_count <= 0 then
+        return
     end
 
     local chunk = self.__chunk
@@ -6598,27 +6758,27 @@ function __builder_mt:multi_spawn(entity_count, component_mapper)
         end
     end
 
-    local entity_list = __lua_table_new(entity_count)
-
-    for entity_index = 1, entity_count do
-        entity_list[entity_index] = __acquire_id()
+    for entity_index = out_entity_first, out_entity_first + entity_count - 1 do
+        out_entity_list[entity_index] = __acquire_id()
     end
 
     if not component_table or not __lua_next(component_table) then
-        return entity_list, entity_count
+        return
     end
 
     if __defer_depth > 0 then
-        __defer_multi_spawn_entity(chunk, entity_list, entity_count, component_table, component_mapper)
+        __defer_multi_spawn_entity(chunk,
+            out_entity_list, out_entity_first, entity_count,
+            component_table, component_mapper)
     else
         __evolved_defer()
         do
-            __multi_spawn_entity(chunk, entity_list, entity_count, component_table, component_mapper)
+            __multi_spawn_entity(chunk,
+                out_entity_list, out_entity_first, entity_count,
+                component_table, component_mapper)
         end
         __evolved_commit()
     end
-
-    return entity_list, entity_count
 end
 
 ---@param prefab evolved.entity
@@ -6663,9 +6823,43 @@ end
 ---@param component_mapper? evolved.component_mapper
 ---@return evolved.entity[] entity_list
 ---@return integer entity_count
+---@nodiscard
 function __builder_mt:multi_clone(entity_count, prefab, component_mapper)
     if entity_count <= 0 then
-        return __safe_tbls.__EMPTY_ENTITY_LIST, 0
+        return {}, 0
+    end
+
+    local entity_list = __lua_table_new(entity_count)
+
+    self:multi_clone_to(entity_list, 1, entity_count, prefab, component_mapper)
+
+    return entity_list, entity_count
+end
+
+---@param entity_count integer
+---@param prefab evolved.entity
+---@param component_mapper? evolved.component_mapper
+function __builder_mt:multi_clone_nr(entity_count, prefab, component_mapper)
+    if entity_count <= 0 then
+        return
+    end
+
+    local entity_list = __acquire_table(__table_pool_tag.entity_list)
+
+    self:multi_clone_to(entity_list, 1, entity_count, prefab, component_mapper)
+
+    __release_table(__table_pool_tag.entity_list, entity_list, false, true)
+end
+
+---@param out_entity_list evolved.entity[]
+---@param out_entity_first integer
+---@param entity_count integer
+---@param prefab evolved.entity
+---@param component_mapper? evolved.component_mapper
+function __builder_mt:multi_clone_to(out_entity_list, out_entity_first,
+                                     entity_count, prefab, component_mapper)
+    if entity_count <= 0 then
+        return
     end
 
     local component_table = self.__component_table
@@ -6686,23 +6880,23 @@ function __builder_mt:multi_clone(entity_count, prefab, component_mapper)
         end
     end
 
-    local entity_list = __lua_table_new(entity_count)
-
-    for entity_index = 1, entity_count do
-        entity_list[entity_index] = __acquire_id()
+    for entity_index = out_entity_first, out_entity_first + entity_count - 1 do
+        out_entity_list[entity_index] = __acquire_id()
     end
 
     if __defer_depth > 0 then
-        __defer_multi_clone_entity(prefab, entity_list, entity_count, component_table, component_mapper)
+        __defer_multi_clone_entity(prefab,
+            out_entity_list, out_entity_first, entity_count,
+            component_table, component_mapper)
     else
         __evolved_defer()
         do
-            __multi_clone_entity(prefab, entity_list, entity_count, component_table, component_mapper)
+            __multi_clone_entity(prefab,
+                out_entity_list, out_entity_first, entity_count,
+                component_table, component_mapper)
         end
         __evolved_commit()
     end
-
-    return entity_list, entity_count
 end
 
 ---@param fragment evolved.fragment
@@ -7660,9 +7854,13 @@ evolved.cancel = __evolved_cancel
 
 evolved.spawn = __evolved_spawn
 evolved.multi_spawn = __evolved_multi_spawn
+evolved.multi_spawn_nr = __evolved_multi_spawn_nr
+evolved.multi_spawn_to = __evolved_multi_spawn_to
 
 evolved.clone = __evolved_clone
 evolved.multi_clone = __evolved_multi_clone
+evolved.multi_clone_nr = __evolved_multi_clone_nr
+evolved.multi_clone_to = __evolved_multi_clone_to
 
 evolved.alive = __evolved_alive
 evolved.alive_all = __evolved_alive_all
@@ -7695,6 +7893,7 @@ evolved.locate = __evolved_locate
 
 evolved.lookup = __evolved_lookup
 evolved.multi_lookup = __evolved_multi_lookup
+evolved.multi_lookup_to = __evolved_multi_lookup_to
 
 evolved.process = __evolved_process
 evolved.process_with = __evolved_process_with

example/main.lua

@@ -52,7 +52,7 @@ evolved.builder()
     :name('SYSTEMS.STARTUP')
     :group(STAGES.ON_SETUP)
     :prologue(function()
-        evolved.multi_clone(500, PREFABS.CIRCLE, nil, function(chunk, b_place, e_place)
+        evolved.multi_clone_nr(500, PREFABS.CIRCLE, nil, function(chunk, b_place, e_place)
             local screen_width, screen_height = love.graphics.getDimensions()
 
             ---@type number[], number[]