update changelog

README.md

@@ -45,7 +45,8 @@
     - [Batch Operations](#batch-operations)
   - [Systems](#systems)
     - [Processing Payloads](#processing-payloads)
-  - [Predefined Traits](#predefined-traits)
+  - [Predefined Fragments](#predefined-fragments)
+    - [Entity Names](#entity-names)
     - [Fragment Tags](#fragment-tags)
     - [Fragment Hooks](#fragment-hooks)
     - [Unique Fragments](#unique-fragments)
@@ -64,6 +65,8 @@
     - [Chunk](#chunk)
     - [Builder](#builder)
 - [Changelog](#changelog)
+  - [vX.Y.Z](#vxyz)
+  - [v1.10.0](#v1100)
   - [v1.9.0](#v190)
   - [v1.8.0](#v180)
   - [v1.7.0](#v170)
@@ -489,6 +492,7 @@ When you need to spawn multiple entities with identical fragments, use `multi_sp
 ---@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
 
 ---@param entity_count integer
@@ -497,6 +501,7 @@ function evolved.multi_spawn(entity_count, component_table, component_mapper) en
 ---@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
 ```
 
@@ -527,6 +532,36 @@ end)
 
 Of course, you can use `evolved.multi_clone` in the same way. Builders can also be used for multi-entity spawning and cloning by calling the corresponding methods on the builder object.
 
+Also, for all `multi_` functions, the library provides [`_nr`](#evolvedmulti_spawn_nr) and [`_to`](#evolvedmulti_spawn_to) suffix variants that allow you to perform these operations without returning the list of spawned entities or by copying the spawned entities to your own table, which can be more efficient because it avoids the overhead of allocating and returning a new table.
+
+```lua
+local evolved = require 'evolved'
+
+local position_x, position_y = evolved.id(2)
+
+do
+    -- we don't interest in the list of spawned entities,
+    -- so we use the _nr variant of the multi_spawn function
+
+    evolved.multi_spawn_nr(100, {
+        [position_x] = 0,
+        [position_y] = 0,
+    })
+end
+
+do
+    -- store spawned entities in our own table starting at index 1,
+    -- so we use the _to variant of the multi_spawn function
+
+    local entity_list = {}
+
+    evolved.multi_spawn_to(entity_list, 1, 100, {
+        [position_x] = 0,
+        [position_y] = 0,
+    })
+end
+```
+
 ### Access Operations
 
 The library provides all the necessary functions to access entities and their components. I'm not going to cover all the accessor functions here, because they are pretty straightforward and self-explanatory. You can check the [API Reference](#api-reference) for all of them. Here are some of the most important ones:
@@ -981,7 +1016,42 @@ evolved.process_with(physics_system, delta_time)
 
 `delta_time` in this example is passed as a processing payload to the system's execution callback. Payloads can be of any type and can be multiple values. Also, payloads are passed to prologue and epilogue callbacks if they are defined. Every subsystem in a group will receive the same payload when the group is processed with [`evolved.process_with`](#evolvedprocess_with).
 
-### Predefined Traits
+### Predefined Fragments
+
+#### Entity Names
+
+The library provides a way to assign names to any id using the [`evolved.NAME`](#evolvedname) fragment. This is useful for debugging and development purposes, as it allows you to identify entities or fragments by their names instead of their identifiers. The name of an entity can be retrieved using the [`evolved.name`](#evolvedname-1) function.
+
+```lua
+local evolved = require 'evolved'
+
+local player = evolved.builder()
+    :name('Player')
+    :build()
+
+assert(evolved.name(player) == 'Player')
+```
+
+Names are not unique, so multiple entities can have the same name. Also, the name of an entity can be changed at any time by setting a new name using the [`evolved.NAME`](#evolvedname) fragment as a usual component.
+
+You can find entities by their names using the [`evolved.lookup`](#evolvedlookup) and [`evolved.multi_lookup`](#evolvedmulti_lookup) functions. The [`evolved.lookup`](#evolvedlookup) function returns the first entity with the specified name, while the [`evolved.multi_lookup`](#evolvedmulti_lookup) function returns a list of all entities with the specified name.
+
+```lua
+local evolved = require 'evolved'
+
+local player1 = evolved.builder()
+    :name('Player')
+    :build()
+
+local player2 = evolved.builder()
+    :name('Player')
+    :build()
+
+assert(evolved.lookup('Player') == player1)
+
+local player_list, player_count = evolved.multi_lookup('Player')
+assert(player_count == 2 and player_list[1] == player1 and player_list[2] == player2)
+```
 
 #### Fragment Tags
 
@@ -1463,9 +1533,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
@@ -1496,6 +1570,10 @@ execute :: query -> {execute_state? -> chunk?, entity[]?, integer?}, execute_sta
 
 locate :: entity -> chunk?, integer
 
+lookup :: string -> entity?
+multi_lookup :: string -> entity[], integer
+multi_lookup_to :: entity[], integer, string -> integer
+
 process :: system... -> ()
 process_with :: system, ... -> ()
 
@@ -1529,12 +1607,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
@@ -1585,6 +1669,17 @@ builder_mt:destruction_policy :: id -> builder
 
 ## Changelog
 
+### vX.Y.Z
+
+- Slightly improved performance of modifying operations for fragments with [`ON_INSERT`](#evolvedon_insert) and [`ON_REMOVE`](#evolvedon_remove) hooks
+- Slightly improved performance of queries with [`EXPLICIT`](#evolvedexplicit) fragments
+
+### v1.10.0
+
+- Added the new [`evolved.lookup`](#evolvedlookup) and [`evolved.multi_lookup`](#evolvedmulti_lookup) functions that allow finding ids by their names
+- Added a non-shrinking version of the [`evolved.collect_garbage`](#evolvedcollect_garbage) function that only collects garbage without shrinking storages
+- Added [`_nr`](#evolvedmulti_spawn_nr) and [`_to`](#evolvedmulti_spawn_to) variants of the [`evolved.multi_spawn`](#evolvedmulti_spawn) and [`evolved.multi_clone`](#evolvedmulti_clone) functions that provide more efficient ways to spawn or clone entities in some cases
+
 ### v1.9.0
 
 - Performance improvements of the [`evolved.destroy`](#evolveddestroy) and [`evolved.batch_destroy`](#evolvedbatch_destroy) functions
@@ -1790,9 +1885,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
@@ -1812,9 +1929,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
@@ -2001,6 +2142,35 @@ function evolved.execute(query) end
 function evolved.locate(entity) end
 ```
 
+### `evolved.lookup`
+
+```lua
+---@param name string
+---@return evolved.entity? entity
+---@nodiscard
+function evolved.lookup(name) end
+```
+
+### `evolved.multi_lookup`
+
+```lua
+---@param name string
+---@return evolved.entity[] entity_list
+---@return integer entity_count
+---@nodiscard
+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
@@ -2143,9 +2313,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
@@ -2161,9 +2353,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
@@ -2181,9 +2393,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/all.lua

@@ -1,9 +1,11 @@
 require 'develop.testing.build_tests'
+require 'develop.testing.cached_hooks_tests'
 require 'develop.testing.cancel_tests'
 require 'develop.testing.clone_tests'
 require 'develop.testing.depth_tests'
 require 'develop.testing.destroy_tests'
 require 'develop.testing.locate_tests'
+require 'develop.testing.lookup_tests'
 require 'develop.testing.main_tests'
 require 'develop.testing.mappers_tests'
 require 'develop.testing.multi_spawn_tests'

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/cached_hooks_tests.lua

@@ -0,0 +1,203 @@
+local evo = require 'evolved'
+
+evo.debug_mode(true)
+
+do
+    local f1, f2 = evo.id(2)
+
+    local insert_hook_calls = 0
+
+    if f1 < f2 then
+        evo.set(f1, evo.ON_INSERT, function()
+            insert_hook_calls = insert_hook_calls + 1
+        end)
+    else
+        evo.set(f2, evo.ON_INSERT, function()
+            insert_hook_calls = insert_hook_calls + 1
+        end)
+    end
+
+    do
+        insert_hook_calls = 0
+        local e = evo.spawn { [f1] = 42, [f2] = 'hello' }
+        assert(insert_hook_calls == 1)
+        evo.destroy(e)
+    end
+
+    evo.remove(f1, evo.ON_INSERT)
+    evo.remove(f2, evo.ON_INSERT)
+
+    do
+        insert_hook_calls = 0
+        local e = evo.spawn { [f1] = 42, [f2] = 'hello' }
+        assert(insert_hook_calls == 0)
+        evo.destroy(e)
+    end
+
+    if f1 < f2 then
+        evo.set(f1, evo.ON_INSERT, function()
+            insert_hook_calls = insert_hook_calls + 2
+        end)
+    else
+        evo.set(f2, evo.ON_INSERT, function()
+            insert_hook_calls = insert_hook_calls + 2
+        end)
+    end
+
+    do
+        insert_hook_calls = 0
+        local e = evo.spawn { [f1] = 42, [f2] = 'hello' }
+        assert(insert_hook_calls == 2)
+        evo.destroy(e)
+    end
+end
+
+do
+    local f1, f2 = evo.id(2)
+
+    local insert_hook_calls = 0
+
+    if f1 > f2 then
+        evo.set(f1, evo.ON_INSERT, function()
+            insert_hook_calls = insert_hook_calls + 1
+        end)
+    else
+        evo.set(f2, evo.ON_INSERT, function()
+            insert_hook_calls = insert_hook_calls + 1
+        end)
+    end
+
+    do
+        insert_hook_calls = 0
+        local e = evo.spawn { [f1] = 42, [f2] = 'hello' }
+        assert(insert_hook_calls == 1)
+        evo.destroy(e)
+    end
+
+    evo.remove(f1, evo.ON_INSERT)
+    evo.remove(f2, evo.ON_INSERT)
+
+    do
+        insert_hook_calls = 0
+        local e = evo.spawn { [f1] = 42, [f2] = 'hello' }
+        assert(insert_hook_calls == 0)
+        evo.destroy(e)
+    end
+
+    if f1 > f2 then
+        evo.set(f1, evo.ON_INSERT, function()
+            insert_hook_calls = insert_hook_calls + 2
+        end)
+    else
+        evo.set(f2, evo.ON_INSERT, function()
+            insert_hook_calls = insert_hook_calls + 2
+        end)
+    end
+
+    do
+        insert_hook_calls = 0
+        local e = evo.spawn { [f1] = 42, [f2] = 'hello' }
+        assert(insert_hook_calls == 2)
+        evo.destroy(e)
+    end
+end
+
+do
+    local f1, f2 = evo.id(2)
+
+    local remove_hook_calls = 0
+
+    if f1 < f2 then
+        evo.set(f1, evo.ON_REMOVE, function()
+            remove_hook_calls = remove_hook_calls + 1
+        end)
+    else
+        evo.set(f2, evo.ON_REMOVE, function()
+            remove_hook_calls = remove_hook_calls + 1
+        end)
+    end
+
+    do
+        remove_hook_calls = 0
+        local e = evo.spawn { [f1] = 42, [f2] = 'hello' }
+        evo.destroy(e)
+        assert(remove_hook_calls == 1)
+    end
+
+    evo.remove(f1, evo.ON_REMOVE)
+    evo.remove(f2, evo.ON_REMOVE)
+
+    do
+        remove_hook_calls = 0
+        local e = evo.spawn { [f1] = 42, [f2] = 'hello' }
+        evo.destroy(e)
+        assert(remove_hook_calls == 0)
+    end
+
+    if f1 < f2 then
+        evo.set(f1, evo.ON_REMOVE, function()
+            remove_hook_calls = remove_hook_calls + 2
+        end)
+    else
+        evo.set(f2, evo.ON_REMOVE, function()
+            remove_hook_calls = remove_hook_calls + 2
+        end)
+    end
+
+    do
+        remove_hook_calls = 0
+        local e = evo.spawn { [f1] = 42, [f2] = 'hello' }
+        evo.destroy(e)
+        assert(remove_hook_calls == 2)
+    end
+end
+
+do
+    local f1, f2 = evo.id(2)
+
+    local remove_hook_calls = 0
+
+    if f1 > f2 then
+        evo.set(f1, evo.ON_REMOVE, function()
+            remove_hook_calls = remove_hook_calls + 1
+        end)
+    else
+        evo.set(f2, evo.ON_REMOVE, function()
+            remove_hook_calls = remove_hook_calls + 1
+        end)
+    end
+
+    do
+        remove_hook_calls = 0
+        local e = evo.spawn { [f1] = 42, [f2] = 'hello' }
+        evo.destroy(e)
+        assert(remove_hook_calls == 1)
+    end
+
+    evo.remove(f1, evo.ON_REMOVE)
+    evo.remove(f2, evo.ON_REMOVE)
+
+    do
+        remove_hook_calls = 0
+        local e = evo.spawn { [f1] = 42, [f2] = 'hello' }
+        evo.destroy(e)
+        assert(remove_hook_calls == 0)
+    end
+
+    if f1 > f2 then
+        evo.set(f1, evo.ON_REMOVE, function()
+            remove_hook_calls = remove_hook_calls + 2
+        end)
+    else
+        evo.set(f2, evo.ON_REMOVE, function()
+            remove_hook_calls = remove_hook_calls + 2
+        end)
+    end
+
+    do
+        remove_hook_calls = 0
+        local e = evo.spawn { [f1] = 42, [f2] = 'hello' }
+        evo.destroy(e)
+        assert(remove_hook_calls == 2)
+    end
+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

@@ -0,0 +1,195 @@
+local evo = require 'evolved'
+
+evo.debug_mode(true)
+
+do
+    local e1, e2, e3 = evo.id(3)
+
+    do
+        assert(evo.lookup('lookup_hello') == nil)
+        assert(evo.lookup('lookup_world') == nil)
+
+        do
+            local entity_list, entity_count = evo.multi_lookup('lookup_hello')
+            assert(entity_list and #entity_list == 0 and entity_count == 0)
+        end
+
+        do
+            local entity_list, entity_count = evo.multi_lookup('lookup_world')
+            assert(entity_list and #entity_list == 0 and entity_count == 0)
+        end
+    end
+
+    evo.set(e1, evo.NAME, 'lookup_hello')
+
+    do
+        assert(evo.lookup('lookup_hello') == e1)
+        assert(evo.lookup('lookup_world') == nil)
+
+        do
+            local entity_list, entity_count = evo.multi_lookup('lookup_hello')
+            assert(entity_list and #entity_list == 1 and entity_count == 1)
+            assert(entity_list[1] == e1)
+        end
+
+        do
+            local entity_list, entity_count = evo.multi_lookup('lookup_world')
+            assert(entity_list and #entity_list == 0 and entity_count == 0)
+        end
+    end
+
+    evo.set(e2, evo.NAME, 'lookup_hello')
+    evo.set(e3, evo.NAME, 'lookup_hello')
+
+    do
+        assert(evo.lookup('lookup_hello') == e1)
+        assert(evo.lookup('lookup_world') == nil)
+
+        do
+            local entity_list, entity_count = evo.multi_lookup('lookup_hello')
+            assert(entity_list and #entity_list == 3 and entity_count == 3)
+            assert(entity_list[1] == e1 and entity_list[2] == e2 and entity_list[3] == e3)
+        end
+    end
+
+    evo.set(e2, evo.NAME, 'lookup_world')
+
+    do
+        assert(evo.lookup('lookup_hello') == e1)
+        assert(evo.lookup('lookup_world') == e2)
+
+        do
+            local entity_list, entity_count = evo.multi_lookup('lookup_hello')
+            assert(entity_list and #entity_list == 2 and entity_count == 2)
+            assert(entity_list[1] == e1 and entity_list[2] == e3)
+        end
+
+        do
+            local entity_list, entity_count = evo.multi_lookup('lookup_world')
+            assert(entity_list and #entity_list == 1 and entity_count == 1)
+            assert(entity_list[1] == e2)
+        end
+    end
+
+    evo.set(e3, evo.NAME, 'lookup_world')
+
+    do
+        assert(evo.lookup('lookup_hello') == e1)
+        assert(evo.lookup('lookup_world') == e2)
+
+        do
+            local entity_list, entity_count = evo.multi_lookup('lookup_hello')
+            assert(entity_list and #entity_list == 1 and entity_count == 1)
+            assert(entity_list[1] == e1)
+        end
+
+        do
+            local entity_list, entity_count = evo.multi_lookup('lookup_world')
+            assert(entity_list and #entity_list == 2 and entity_count == 2)
+            assert(entity_list[1] == e2 or entity_list[1] == e3)
+        end
+    end
+
+    evo.remove(e1, evo.NAME)
+
+    do
+        assert(evo.lookup('lookup_hello') == nil)
+        assert(evo.lookup('lookup_world') == e2)
+
+        do
+            local entity_list, entity_count = evo.multi_lookup('lookup_hello')
+            assert(entity_list and #entity_list == 0 and entity_count == 0)
+        end
+
+        do
+            local entity_list, entity_count = evo.multi_lookup('lookup_world')
+            assert(entity_list and #entity_list == 2 and entity_count == 2)
+            assert(entity_list[1] == e2 or entity_list[1] == e3)
+        end
+    end
+end
+
+do
+    local e1, e2, e3 = evo.id(3)
+
+    evo.set(e1, evo.NAME, 'lookup_e')
+
+    do
+        local entity_list, entity_count = evo.multi_lookup('lookup_e')
+        assert(entity_list and #entity_list == 1 and entity_count == 1)
+        assert(entity_list[1] == e1)
+    end
+
+    evo.set(e2, evo.NAME, 'lookup_e')
+
+    do
+        local entity_list, entity_count = evo.multi_lookup('lookup_e')
+        assert(entity_list and #entity_list == 2 and entity_count == 2)
+        assert(entity_list[1] == e1 and entity_list[2] == e2)
+    end
+
+    evo.set(e3, evo.NAME, 'lookup_e')
+
+    do
+        local entity_list, entity_count = evo.multi_lookup('lookup_e')
+        assert(entity_list and #entity_list == 3 and entity_count == 3)
+        assert(entity_list[1] == e1 and entity_list[2] == e2 and entity_list[3] == e3)
+    end
+
+    evo.clear(e1, e2, e3)
+
+    do
+        local entity_list, entity_count = evo.multi_lookup('lookup_e')
+        assert(entity_list and #entity_list == 0 and entity_count == 0)
+    end
+
+    evo.set(e3, evo.NAME, 'lookup_e')
+
+    do
+        local entity_list, entity_count = evo.multi_lookup('lookup_e')
+        assert(entity_list and #entity_list == 1 and entity_count == 1)
+        assert(entity_list[1] == e3)
+    end
+
+    evo.set(e2, evo.NAME, 'lookup_e')
+
+    do
+        local entity_list, entity_count = evo.multi_lookup('lookup_e')
+        assert(entity_list and #entity_list == 2 and entity_count == 2)
+        assert(entity_list[1] == e3 and entity_list[2] == e2)
+    end
+
+    evo.set(e1, evo.NAME, 'lookup_e')
+
+    do
+        local entity_list, entity_count = evo.multi_lookup('lookup_e')
+        assert(entity_list and #entity_list == 3 and entity_count == 3)
+        assert(entity_list[1] == e3 and entity_list[2] == e2 and entity_list[3] == e1)
+    end
+
+    evo.destroy(e3, e2, e1)
+
+    do
+        local entity_list, entity_count = evo.multi_lookup('lookup_e')
+        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/main_tests.lua

@@ -2928,8 +2928,8 @@ do
         last_insert_entity, last_insert_component = 0, 0
         local e = evo.spawn({ [f2] = 21, [f1] = true })
         assert(set_count == 2 and insert_count == 2)
-        assert(last_set_entity == e and last_set_component == 21)
-        assert(last_insert_entity == e and last_insert_component == 21)
+        assert(last_set_entity == e and (last_set_component == 21 or last_set_component == true))
+        assert(last_insert_entity == e and (last_insert_component == 21 or last_insert_component == true))
     end
 
     do
@@ -2948,8 +2948,8 @@ do
         last_insert_entity, last_insert_component = 0, 0
         local e = evo.spawn({ [f3] = 33, [f2] = 22 })
         assert(set_count == 2 and insert_count == 2)
-        assert(last_set_entity == e and last_set_component == nil)
-        assert(last_insert_entity == e and last_insert_component == nil)
+        assert(last_set_entity == e and (last_set_component == nil or last_set_component == 22))
+        assert(last_insert_entity == e and (last_insert_component == nil or last_insert_component == 22))
     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
@@ -208,6 +268,10 @@
 
     locate: function(entity: Entity): Chunk | nil, integer
 
+    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)
 

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[]

rockspecs/evolved.lua-1.10.0-0.rockspec

@@ -0,0 +1,34 @@
+rockspec_format = "3.0"
+package = "evolved.lua"
+version = "1.10.0-0"
+source = {
+   url = "git://github.com/BlackMATov/evolved.lua",
+   tag = "v1.10.0",
+}
+description = {
+   homepage = "https://github.com/BlackMATov/evolved.lua",
+   summary = "Evolved ECS (Entity-Component-System) for Lua",
+   detailed = [[
+      `evolved.lua` is a fast and flexible ECS (Entity-Component-System) library for Lua.
+      It is designed to be simple and easy to use, while providing all the features needed to create complex systems with blazing performance.
+   ]],
+   license = "MIT",
+   labels = {
+      "ecs",
+      "entity",
+      "entities",
+      "component",
+      "components",
+      "entity-component",
+      "entity-component-system",
+   },
+}
+dependencies = {
+   "lua >= 5.1",
+}
+build = {
+   type = "builtin",
+   modules = {
+      evolved = "evolved.lua",
+   }
+}