fix readme formatting

.luacov

@@ -0,0 +1,5 @@
+modules = {
+    ['evolved'] = 'evolved.lua'
+}
+reporter = 'html'
+reportfile = 'luacov.report.html'

README.md

@@ -35,6 +35,7 @@
     - [Spawning Entities](#spawning-entities)
     - [Entity Builders](#entity-builders)
   - [Access Operations](#access-operations)
+  - [Iterating Over Fragments](#iterating-over-fragments)
   - [Modifying Operations](#modifying-operations)
   - [Debug Mode](#debug-mode)
   - [Queries](#queries)
@@ -53,6 +54,7 @@
   - [Aliases](#aliases)
   - [Predefs](#predefs)
   - [Functions](#functions)
+  - [Relations](#relations)
   - [Classes](#classes)
     - [Chunk](#chunk)
     - [Builder](#builder)
@@ -94,7 +96,7 @@ luarocks install evolved.lua
 
 ## Quick Start
 
-To get started with `evolved.lua`, read the [Overview](#overview) section to understand the basic concepts and how to use the library. After that, check the [Example](develop/example.lua), which demonstrates complex usage of the library. Finally, refer to the [Cheat Sheet](#cheat-sheet) for a quick reference of all the functions and classes provided by the library.
+To get started with `evolved.lua`, read the [Overview](#overview) section to understand the basic concepts and how to use the library. After that, check the [Samples](develop/samples), which demonstrate complex usage of the library. Finally, refer to the [Cheat Sheet](#cheat-sheet) for a quick reference of all the functions and classes provided by the library.
 
 ## Overview
 
@@ -146,14 +148,18 @@ function evolved.alive_any(...) end
 Sometimes (for debugging purposes, for example), it is necessary to extract the index and version from an identifier or to pack them back into an identifier. The [`evolved.pack`](#evolvedpack) and [`evolved.unpack`](#evolvedunpack) functions can be used for this purpose.
 
 ```lua
----@param index integer
----@param version integer
+---@param primary integer
+---@param secondary integer
+---@param options? integer
 ---@return evolved.id id
-function evolved.pack(index, version) end
+---@nodiscard
+function evolved.pack(primary, secondary, options) end
 
 ---@param id evolved.id
----@return integer index
----@return integer version
+---@return integer primary
+---@return integer secondary
+---@return integer options
+---@nodiscard
 function evolved.unpack(id) end
 ```
 
@@ -405,7 +411,7 @@ evolved.set(enemy1, stamina, 42)
 
 #### Entity Builders
 
-Another way to avoid structural changes when spawning entities is to use the [`evolved.builder`](#evolvedbuilder) fluid interface. The [`evolved.builder`](#evolvedbuilder) function returns a builder object that allows you to spawn entities with a specific set of fragments and components without the necessity of setting them one by one with structural changes for each change.
+Another way to avoid structural changes when spawning entities is to use the [`evolved.builder`](#evolvedbuilder) fluent interface. The [`evolved.builder`](#evolvedbuilder) function returns a builder object that allows you to spawn entities with a specific set of fragments and components without the necessity of setting them one by one with structural changes for each change.
 
 ```lua
 local evolved = require 'evolved'
@@ -447,6 +453,35 @@ The [`evolved.alive`](#evolvedalive) function checks whether an entity is alive.
 
 All of these functions can be safely called on non-alive entities and non-alive fragments. Also, they do not cause any structural changes, because they do not modify anything.
 
+### Iterating Over Fragments
+
+Sometimes, you may need to iterate over all fragments attached to an entity. You can use the [`evolved.each`](#evolvedeach) function for this purpose.
+
+```lua
+local evolved = require 'evolved'
+
+local health = evolved.builder()
+    :name('health')
+    :spawn()
+
+local stamina = evolved.builder()
+    :name('stamina')
+    :spawn()
+
+local player = evolved.builder()
+    :set(health, 100)
+    :set(stamina, 50)
+    :spawn()
+
+for fragment, component in evolved.each(player) do
+    print(string.format('Fragment (%s) has value %d',
+        evolved.name(fragment), component))
+end
+```
+
+> [!NOTE]
+> [Structural changes](#structural-changes) are not allowed during iteration. If you want to spawn new entities or insert/remove fragments while iterating, defer these operations until the iteration is complete. See the [Deferred Operations](#deferred-operations) section for more details.
+
 ### Modifying Operations
 
 The library provides a classic set of functions for modifying entities. These functions are used to insert, override, and remove fragments from entities.
@@ -1015,19 +1050,26 @@ remove_hook :: {entity, fragment, component}
 
 each_state :: implementation-specific
 execute_state :: implementation-specific
+primaries_state :: implementation-specific
+secondaries_state :: implementation-specific
 
 each_iterator :: {each_state? -> fragment?, component?}
 execute_iterator :: {execute_state? -> chunk?, entity[]?, integer?}
+primaries_iterator :: {primaries_state? -> fragment?, component?}
+secondaries_iterator :: {secondaries_state? -> fragment?, component?}
 ```
 
 ### Predefs
 
 ```
+ANY :: fragment
+
 TAG :: fragment
 NAME :: fragment
 
 UNIQUE :: fragment
 EXPLICIT :: fragment
+INTERNAL :: fragment
 
 DEFAULT :: fragment
 DUPLICATE :: fragment
@@ -1061,9 +1103,10 @@ DESTRUCTION_POLICY_REMOVE_FRAGMENT :: id
 
 ```
 id :: integer? -> id...
+name :: id... -> string...
 
-pack :: integer, integer -> id
-unpack :: id -> integer, integer
+pack :: integer, integer, integer? -> id
+unpack :: id -> integer, integer, integer
 
 defer :: boolean
 commit :: boolean
@@ -1104,6 +1147,25 @@ debug_mode :: boolean -> ()
 collect_garbage :: ()
 ```
 
+### Relations
+
+```
+pair :: id, id -> id
+unpair :: id -> id, id
+
+is_pair :: id -> boolean
+is_wildcard :: id -> boolean
+
+primary :: entity, fragment, integer? -> fragment?, component?
+secondary :: entity, fragment, integer? -> fragment?, component?
+
+primaries :: entity, fragment -> {primaries_state? -> fragment?, component?}, primaries_state?
+secondaries :: entity, fragment -> {secondaries_state? -> fragment?, component?}, secondaries_state?
+
+primary_count :: entity, fragment -> integer
+secondary_count :: entity, fragment -> integer
+```
+
 ### Classes
 
 #### Chunk
@@ -1146,6 +1208,7 @@ builder_mt:name :: string -> builder
 
 builder_mt:unique :: builder
 builder_mt:explicit :: builder
+builder_mt:internal :: builder
 
 builder_mt:default :: component -> builder
 builder_mt:duplicate :: {component -> component} -> builder
@@ -1192,6 +1255,8 @@ builder_mt:destruction_policy :: id -> builder
 
 ## Predefs
 
+### `evolved.ANY`
+
 ### `evolved.TAG`
 
 ### `evolved.NAME`
@@ -1200,6 +1265,8 @@ builder_mt:destruction_policy :: id -> builder
 
 ### `evolved.EXPLICIT`
 
+### `evolved.INTERNAL`
+
 ### `evolved.DEFAULT`
 
 ### `evolved.DUPLICATE`
@@ -1238,7 +1305,7 @@ builder_mt:destruction_policy :: id -> builder
 
 ### `evolved.DESTRUCTION_POLICY_REMOVE_FRAGMENT`
 
-## Functions
+## Core Functions
 
 ### `evolved.id`
 
@@ -1249,22 +1316,33 @@ builder_mt:destruction_policy :: id -> builder
 function evolved.id(count) end
 ```
 
+### `evolved.name`
+
+```lua
+---@param ... evolved.id ids
+---@return string... names
+---@nodiscard
+function evolved.name(...) end
+```
+
 ### `evolved.pack`
 
 ```lua
----@param index integer
----@param version integer
+---@param primary integer
+---@param secondary integer
+---@param options? integer
 ---@return evolved.id id
 ---@nodiscard
-function evolved.pack(index, version) end
+function evolved.pack(primary, secondary, options) end
 ```
 
 ### `evolved.unpack`
 
 ```lua
 ---@param id evolved.id
----@return integer index
----@return integer version
+---@return integer primary
+---@return integer secondary
+---@return integer options
 ---@nodiscard
 function evolved.unpack(id) end
 ```
@@ -1496,6 +1574,112 @@ function evolved.debug_mode(yesno) end
 function evolved.collect_garbage() end
 ```
 
+## Relation Functions
+
+### `evolved.pair`
+
+```lua
+---@param primary evolved.id
+---@param secondary evolved.id
+---@return evolved.id pair
+---@nodiscard
+function evolved.pair(primary, secondary) end
+```
+
+### `evolved.unpair`
+
+```lua
+---@param pair evolved.id
+---@return evolved.id primary
+---@return evolved.id secondary
+---@nodiscard
+function evolved.unpair(pair) end
+```
+
+### `evolved.is_pair`
+
+```lua
+---@param id evolved.id
+---@return boolean
+---@nodiscard
+function evolved.is_pair(id) end
+```
+
+### `evolved.is_wildcard`
+
+```lua
+---@param id evolved.id
+---@return boolean
+---@nodiscard
+function evolved.is_wildcard(id) end
+```
+
+### `evolved.primary`
+
+```lua
+---@param entity evolved.entity
+---@param secondary evolved.fragment
+---@param index? integer
+---@return evolved.fragment? primary
+---@return evolved.component? component
+---@nodiscard
+function evolved.primary(entity, secondary, index) end
+```
+
+### `evolved.secondary`
+
+```lua
+---@param entity evolved.entity
+---@param primary evolved.fragment
+---@param index? integer
+---@return evolved.fragment? secondary
+---@return evolved.component? component
+---@nodiscard
+function evolved.secondary(entity, primary, index) end
+```
+
+### `evolved.primaries`
+
+```lua
+---@param entity evolved.entity
+---@param secondary evolved.fragment
+---@return evolved.primaries_iterator iterator
+---@return evolved.primaries_state? iterator_state
+---@nodiscard
+function evolved.primaries(entity, secondary) end
+```
+
+### `evolved.secondaries`
+
+```lua
+---@param entity evolved.entity
+---@param primary evolved.fragment
+---@return evolved.secondaries_iterator iterator
+---@return evolved.secondaries_state? iterator_state
+---@nodiscard
+function evolved.secondaries(entity, primary) end
+```
+
+### `evolved.primary_count`
+
+```lua
+---@param entity evolved.entity
+---@param secondary evolved.fragment
+---@return integer
+---@nodiscard
+function evolved.primary_count(entity, secondary) end
+```
+
+### `evolved.secondary_count`
+
+```lua
+---@param entity evolved.entity
+---@param primary evolved.fragment
+---@return integer
+---@nodiscard
+function evolved.secondary_count(entity, primary) end
+```
+
 ## Classes
 
 ### Chunk
@@ -1696,6 +1880,13 @@ function evolved.builder_mt:unique() end
 function evolved.builder_mt:explicit() end
 ```
 
+#### `evolved.builder_mt:internal`
+
+```lua
+---@return evolved.builder builder
+function evolved.builder_mt:internal() end
+```
+
 #### `evolved.builder_mt:default`
 
 ```lua

ROADMAP.md

@@ -2,10 +2,19 @@
 
 ## Backlog
 
-## After first release
-
-- cached queries
+- Improve the performance of required fragments by caching first-level required chunks.
+- Improve the performance of builders that are used multiple times by caching hint chunks.
+- Queries can cache major chunks to avoid finding them every time.
+- Add multi-spawn to the builder to spawn multiple entities at once.
+- Add a function to shrink storages to free unused memory.
 - observers and events
 - add INDEX fragment trait
 - use compact prefix-tree for chunks
 - optional ffi component storages
+- add EXCLUSIVE fragment trait
+
+## Thoughts
+
+- We can return deferred status from modifying operations and spawn/clone methods.
+- Should we make one builder:build method instead of :spawn and :clone?
+- Should we cache the result of without_unique_fragments to clone faster?

develop/all.lua

@@ -1,9 +1,13 @@
-require 'develop.example'
-require 'develop.untests'
+require 'develop.samples.relations'
+require 'develop.samples.systems'
 
+require 'develop.testing.name_tests'
+require 'develop.testing.pairs_tests'
 require 'develop.testing.requires_fragment_tests'
 require 'develop.testing.system_as_query_tests'
 
+require 'develop.untests'
+
 require 'develop.unbench'
 require 'develop.usbench'
 
@@ -21,3 +25,5 @@ print '----------------------------------------'
 basics.describe_fuzz 'develop.fuzzing.requires_fuzz'
 print '----------------------------------------'
 basics.describe_fuzz 'develop.fuzzing.unique_fuzz'
+print '----------------------------------------'
+basics.describe_fuzz 'develop.fuzzing.wildcard_fuzz'

develop/basics.lua

@@ -1,5 +1,13 @@
 local basics = {}
 
+local MIN_FUZZ_SECS = 0.5
+local MIN_BENCH_SECS = 0.1
+local MIN_WARMUP_SECS = 0.1
+
+local MIN_FUZZ_ITERS = 100
+local MIN_BENCH_ITERS = 100
+local MIN_WARMUP_ITERS = 100
+
 local __table_pack = (function()
     ---@diagnostic disable-next-line: deprecated
     return table.pack or function(...)
@@ -23,8 +31,13 @@ end
 
 ---@param modname string
 function basics.describe_fuzz(modname)
+    basics.unload('evolved')
+
     print(string.format('| %s ... |', modname))
 
+    collectgarbage('collect')
+    collectgarbage('stop')
+
     do
         local iters = 0
 
@@ -36,7 +49,7 @@ function basics.describe_fuzz(modname)
                 iters = iters + 1
                 basics.unload(modname)
                 require(modname)
-            until os.clock() - start_s > 0.5
+            until iters >= MIN_FUZZ_ITERS and os.clock() - start_s >= MIN_FUZZ_SECS
         end)
 
         local finish_s = os.clock()
@@ -52,6 +65,9 @@ function basics.describe_fuzz(modname)
             print('|-- FUZZ FAIL: ' .. result)
         end
     end
+
+    collectgarbage('restart')
+    collectgarbage('collect')
 end
 
 ---@param name string
@@ -59,17 +75,22 @@ end
 ---@param init? fun(): ...
 ---@param fini? fun(...): ...
 function basics.describe_bench(name, loop, init, fini)
+    basics.unload('evolved')
+
     print(string.format('| %s ... |', name))
 
     local state = init and __table_pack(init()) or {}
 
     do
+        local iters = 0
+
         local warmup_s = os.clock()
 
         local success, result = pcall(function()
             repeat
+                iters = iters + 1
                 loop(__table_unpack(state))
-            until os.clock() - warmup_s > 0.1
+            until iters >= MIN_WARMUP_ITERS and os.clock() - warmup_s > MIN_WARMUP_SECS
         end)
 
         if not success then
@@ -91,7 +112,7 @@ function basics.describe_bench(name, loop, init, fini)
             repeat
                 iters = iters + 1
                 loop(__table_unpack(state))
-            until os.clock() - start_s > 0.1
+            until iters >= MIN_BENCH_ITERS and os.clock() - start_s > MIN_BENCH_SECS
         end)
 
         local finish_s = os.clock()

develop/fuzzing/batch_destroy_fuzz.lua

@@ -117,5 +117,12 @@ end
 ---
 ---
 
+if math.random(1, 2) == 1 then
+    evo.collect_garbage()
+end
+
 evo.destroy(__table_unpack(all_entity_list))
-evo.collect_garbage()
+
+if math.random(1, 2) == 1 then
+    evo.collect_garbage()
+end

develop/fuzzing/destroy_fuzz.lua

@@ -123,5 +123,12 @@ end
 ---
 ---
 
+if math.random(1, 2) == 1 then
+    evo.collect_garbage()
+end
+
 evo.destroy(__table_unpack(all_entity_list))
-evo.collect_garbage()
+
+if math.random(1, 2) == 1 then
+    evo.collect_garbage()
+end

develop/fuzzing/explicit_fuzz.lua

@@ -77,5 +77,12 @@ end
 ---
 ---
 
+if math.random(1, 2) == 1 then
+    evo.collect_garbage()
+end
+
 evo.destroy(__table_unpack(all_entity_list))
-evo.collect_garbage()
+
+if math.random(1, 2) == 1 then
+    evo.collect_garbage()
+end

develop/fuzzing/pack_unpack_fuzz.lua

@@ -9,12 +9,39 @@ evo.debug_mode(true)
 ---
 
 for _ = 1, 1000 do
-    local initial_index = math.random(1, 0xFFFFF)
-    local initial_version = math.random(1, 0xFFFFF)
+    local initial_primary = math.random(1, 2 ^ 20 - 1)
+    local initial_secondary = math.random(1, 2 ^ 20 - 1)
 
-    local packed_id = evo.pack(initial_index, initial_version)
-    local unpacked_index, unpacked_version = evo.unpack(packed_id)
+    local packed_id = evo.pack(initial_primary, initial_secondary)
+    local unpacked_primary, unpacked_secondary, unpacked_options = evo.unpack(packed_id)
 
-    assert(initial_index == unpacked_index)
-    assert(initial_version == unpacked_version)
+    assert(initial_primary == unpacked_primary)
+    assert(initial_secondary == unpacked_secondary)
+    assert(0 == unpacked_options)
+end
+
+for _ = 1, 1000 do
+    local initial_primary = math.random(1, 2 ^ 20 - 1)
+    local initial_secondary = math.random(1, 2 ^ 20 - 1)
+    local initial_options = math.random(1, 2 ^ 12 - 1)
+
+    local packed_id = evo.pack(initial_primary, initial_secondary, initial_options)
+    local unpacked_primary, unpacked_secondary, unpacked_options = evo.unpack(packed_id)
+
+    assert(initial_primary == unpacked_primary)
+    assert(initial_secondary == unpacked_secondary)
+    assert(initial_options == unpacked_options)
+end
+
+for _ = 1, 1000 do
+    local initial_primary = math.random(1, 2 ^ 31 - 1)
+    local initial_secondary = math.random(1, 2 ^ 31 - 1)
+    local initial_options = math.random(1, 2 ^ 31 - 1)
+
+    local packed_id = evo.pack(initial_primary, initial_secondary, initial_options)
+    local unpacked_primary, unpacked_secondary, unpacked_options = evo.unpack(packed_id)
+
+    assert(initial_primary % 2 ^ 20 == unpacked_primary)
+    assert(initial_secondary % 2 ^ 20 == unpacked_secondary)
+    assert(initial_options % 2 ^ 12 == unpacked_options)
 end

develop/fuzzing/requires_fuzz.lua

@@ -108,6 +108,24 @@ end
 ---
 ---
 
-evo.destroy(__table_unpack(all_entity_list))
-evo.destroy(__table_unpack(all_fragment_list))
-evo.collect_garbage()
+if math.random(1, 2) == 1 then
+    evo.collect_garbage()
+end
+
+if math.random(1, 2) == 1 then
+    evo.destroy(__table_unpack(all_entity_list))
+    if math.random(1, 2) == 1 then
+        evo.collect_garbage()
+    end
+    evo.destroy(__table_unpack(all_fragment_list))
+else
+    evo.destroy(__table_unpack(all_fragment_list))
+    if math.random(1, 2) == 1 then
+        evo.collect_garbage()
+    end
+    evo.destroy(__table_unpack(all_entity_list))
+end
+
+if math.random(1, 2) == 1 then
+    evo.collect_garbage()
+end

develop/fuzzing/unique_fuzz.lua

@@ -63,5 +63,12 @@ end
 ---
 ---
 
+if math.random(1, 2) == 1 then
+    evo.collect_garbage()
+end
+
 evo.destroy(__table_unpack(all_entity_list))
-evo.collect_garbage()
+
+if math.random(1, 2) == 1 then
+    evo.collect_garbage()
+end

develop/fuzzing/wildcard_fuzz.lua

@@ -0,0 +1,254 @@
+local evo = require 'evolved'
+
+evo.debug_mode(true)
+
+---
+---
+---
+---
+---
+
+local __table_unpack = (function()
+    ---@diagnostic disable-next-line: deprecated
+    return table.unpack or unpack
+end)()
+
+---
+---
+---
+---
+---
+
+local all_entity_list = {} ---@type evolved.entity[]
+local all_fragment_list = {} ---@type evolved.fragment[]
+
+for i = 1, math.random(1, 5) do
+    local fragment_builder = evo.builder()
+
+    if math.random(1, 3) == 1 then
+        fragment_builder:explicit()
+    end
+
+    if math.random(1, 3) == 1 then
+        if math.random(1, 2) == 1 then
+            fragment_builder:destruction_policy(evo.DESTRUCTION_POLICY_DESTROY_ENTITY)
+        else
+            fragment_builder:destruction_policy(evo.DESTRUCTION_POLICY_REMOVE_FRAGMENT)
+        end
+    end
+
+    all_fragment_list[i] = fragment_builder:spawn()
+end
+
+for i = 1, math.random(50, 100) do
+    local entity_builder = evo.builder()
+
+    for _ = 0, math.random(0, #all_fragment_list) do
+        if math.random(1, 2) == 1 then
+            local fragment = all_fragment_list[math.random(1, #all_fragment_list)]
+            entity_builder:set(fragment)
+        else
+            local primary = all_fragment_list[math.random(1, #all_fragment_list)]
+            local secondary = all_fragment_list[math.random(1, #all_fragment_list)]
+            entity_builder:set(evo.pair(primary, secondary))
+        end
+    end
+
+    all_entity_list[i] = entity_builder:spawn()
+end
+
+---
+---
+---
+---
+---
+
+for _ = 1, math.random(1, 100) do
+    local query_builder = evo.builder()
+
+    local query_include_set = {} ---@type table<evolved.fragment, integer>
+    local query_include_list = {} ---@type evolved.entity[]
+    local query_include_count = 0 ---@type integer
+
+    local query_exclude_set = {} ---@type table<evolved.fragment, integer>
+    local query_exclude_list = {} ---@type evolved.entity[]
+    local query_exclude_count = 0 ---@type integer
+
+    for _ = 1, math.random(0, 2) do
+        if math.random(1, 2) == 1 then
+            local fragment = all_fragment_list[math.random(1, #all_fragment_list)]
+
+            query_builder:include(fragment)
+
+            if not query_include_set[fragment] then
+                query_include_count = query_include_count + 1
+                query_include_set[fragment] = query_include_count
+                query_include_list[query_include_count] = fragment
+            end
+        else
+            local primary = all_fragment_list[math.random(1, #all_fragment_list)]
+            local secondary = all_fragment_list[math.random(1, #all_fragment_list)]
+
+            if math.random(1, 3) == 1 then
+                primary = evo.ANY
+            end
+
+            if math.random(1, 3) == 1 then
+                secondary = evo.ANY
+            end
+
+            local pair = evo.pair(primary, secondary)
+
+            query_builder:include(pair)
+
+            if not query_include_set[pair] then
+                query_include_count = query_include_count + 1
+                query_include_set[pair] = query_include_count
+                query_include_list[query_include_count] = pair
+            end
+        end
+    end
+
+    for _ = 1, math.random(0, 2) do
+        if math.random(1, 2) == 1 then
+            local fragment = all_fragment_list[math.random(1, #all_fragment_list)]
+
+            query_builder:exclude(fragment)
+
+            if not query_exclude_set[fragment] then
+                query_exclude_count = query_exclude_count + 1
+                query_exclude_set[fragment] = query_exclude_count
+                query_exclude_list[query_exclude_count] = fragment
+            end
+        else
+            local primary = all_fragment_list[math.random(1, #all_fragment_list)]
+            local secondary = all_fragment_list[math.random(1, #all_fragment_list)]
+
+            if math.random(1, 3) == 1 then
+                primary = evo.ANY
+            end
+
+            if math.random(1, 3) == 1 then
+                secondary = evo.ANY
+            end
+
+            local pair = evo.pair(primary, secondary)
+
+            query_builder:exclude(pair)
+
+            if not query_exclude_set[pair] then
+                query_exclude_count = query_exclude_count + 1
+                query_exclude_set[pair] = query_exclude_count
+                query_exclude_list[query_exclude_count] = pair
+            end
+        end
+    end
+
+    local query_entity_set = {} ---@type table<evolved.entity, integer>
+    local query_entity_count = 0 ---@type integer
+
+    do
+        local query = query_builder:spawn()
+
+        for chunk, entity_list, entity_count in evo.execute(query) do
+            if not chunk:has(evo.INTERNAL) then
+                for i = 1, entity_count do
+                    local entity = entity_list[i]
+                    assert(not query_entity_set[entity])
+                    query_entity_count = query_entity_count + 1
+                    query_entity_set[entity] = query_entity_count
+                end
+            end
+        end
+
+        if query_entity_set[query] then
+            query_entity_set[query] = nil
+            query_entity_count = query_entity_count - 1
+        end
+
+        evo.destroy(query)
+    end
+
+    do
+        local expected_entity_count = 0
+
+        for _, entity in ipairs(all_entity_list) do
+            local is_entity_expected =
+                not evo.empty(entity) and
+                evo.has_all(entity, __table_unpack(query_include_list)) and
+                not evo.has_any(entity, __table_unpack(query_exclude_list))
+
+            for fragment in evo.each(entity) do
+                if evo.has(fragment, evo.EXPLICIT) then
+                    local is_fragment_included =
+                        query_include_set[fragment] ~= nil or
+                        query_include_set[evo.pair(fragment, evo.ANY)] ~= nil
+
+                    if not is_fragment_included then
+                        is_entity_expected = false
+                        break
+                    end
+                end
+            end
+
+            if is_entity_expected then
+                assert(query_entity_set[entity])
+                expected_entity_count = expected_entity_count + 1
+            else
+                assert(not query_entity_set[entity])
+            end
+        end
+
+        for _, entity in ipairs(all_fragment_list) do
+            local is_entity_expected =
+                not evo.empty(entity) and
+                evo.has_all(entity, __table_unpack(query_include_list)) and
+                not evo.has_any(entity, __table_unpack(query_exclude_list))
+
+            for fragment in evo.each(entity) do
+                if evo.has(fragment, evo.EXPLICIT) then
+                    is_entity_expected = is_entity_expected and
+                        (query_include_set[fragment] ~= nil) or
+                        (evo.is_pair(fragment) and query_include_set[evo.pair(fragment, evo.ANY)] ~= nil)
+                end
+            end
+
+            if is_entity_expected then
+                assert(query_entity_set[entity])
+                expected_entity_count = expected_entity_count + 1
+            else
+                assert(not query_entity_set[entity])
+            end
+        end
+
+        assert(query_entity_count == expected_entity_count)
+    end
+end
+
+---
+---
+---
+---
+---
+
+if math.random(1, 2) == 1 then
+    evo.collect_garbage()
+end
+
+if math.random(1, 2) == 1 then
+    evo.destroy(__table_unpack(all_entity_list))
+    if math.random(1, 2) == 1 then
+        evo.collect_garbage()
+    end
+    evo.destroy(__table_unpack(all_fragment_list))
+else
+    evo.destroy(__table_unpack(all_fragment_list))
+    if math.random(1, 2) == 1 then
+        evo.collect_garbage()
+    end
+    evo.destroy(__table_unpack(all_entity_list))
+end
+
+if math.random(1, 2) == 1 then
+    evo.collect_garbage()
+end

develop/samples/relations.lua

@@ -0,0 +1,79 @@
+---@diagnostic disable: unused-local
+
+local evo = require 'evolved'
+
+evo.debug_mode(true)
+
+local fragments = {
+    planet = evo.builder()
+        :name('planet')
+        :tag()
+        :spawn(),
+    spaceship = evo.builder()
+        :name('spaceship')
+        :tag()
+        :spawn(),
+}
+
+local relations = {
+    docked_to = evo.builder()
+        :name('docked_to')
+        :tag()
+        :spawn(),
+}
+
+local planets = {
+    mars = evo.builder()
+        :name('Mars')
+        :set(fragments.planet)
+        :spawn(),
+    venus = evo.builder()
+        :name('Venus')
+        :set(fragments.planet)
+        :spawn(),
+}
+
+local spaceships = {
+    falcon = evo.builder()
+        :name('Millennium Falcon')
+        :set(fragments.spaceship)
+        :set(evo.pair(relations.docked_to, planets.mars))
+        :spawn(),
+    enterprise = evo.builder()
+        :name('USS Enterprise')
+        :set(fragments.spaceship)
+        :set(evo.pair(relations.docked_to, planets.venus))
+        :spawn(),
+}
+
+local queries = {
+    all_docked_spaceships = evo.builder()
+        :include(fragments.spaceship)
+        :include(evo.pair(relations.docked_to, evo.ANY))
+        :spawn(),
+    docked_spaceships_to_mars = evo.builder()
+        :include(fragments.spaceship)
+        :include(evo.pair(relations.docked_to, planets.mars))
+        :spawn(),
+
+}
+
+print '-= | All Docked Spaceships | =-'
+
+for chunk, entity_list, entity_count in evo.execute(queries.all_docked_spaceships) do
+    for i = 1, entity_count do
+        local entity = entity_list[i]
+        local planet = evo.secondary(entity, relations.docked_to)
+        print(string.format('%s is docked to %s', evo.name(entity), evo.name(planet)))
+    end
+end
+
+print '-= | Docked Spaceships to Mars | =-'
+
+for chunk, entity_list, entity_count in evo.execute(queries.docked_spaceships_to_mars) do
+    for i = 1, entity_count do
+        local entity = entity_list[i]
+        local planet = evo.secondary(entity, relations.docked_to)
+        print(string.format('%s is docked to %s', evo.name(entity), evo.name(planet)))
+    end
+end

develop/testing/name_tests.lua

@@ -0,0 +1,43 @@
+local evo = require 'evolved'
+
+do
+    local id = evo.id()
+
+    local index, version, options = evo.unpack(id)
+    assert(evo.name(id) == string.format('$%d#%d:%d:%d', id, index, version, options))
+
+    evo.set(id, evo.NAME, 'hello')
+    assert(evo.name(id) == 'hello')
+
+    evo.set(id, evo.NAME, 'world')
+    assert(evo.name(id) == 'world')
+
+    evo.destroy(id)
+    assert(evo.name(id) == string.format('$%d#%d:%d:%d', id, index, version, options))
+end
+
+do
+    local id1, id2, id3, id4, id5 = evo.id(5)
+
+    evo.set(id1, evo.NAME, 'id1')
+    evo.set(id2, evo.NAME, 'id2')
+    evo.set(id3, evo.NAME, 'id3')
+    evo.set(id4, evo.NAME, 'id4')
+    evo.set(id5, evo.NAME, 'id5')
+
+    do
+        local id1_n, id3_n, id5_n = evo.name(id1, id3, id5)
+        assert(id1_n == 'id1')
+        assert(id3_n == 'id3')
+        assert(id5_n == 'id5')
+    end
+
+    do
+        local id1_n, id2_n, id3_n, id4_n, id5_n = evo.name(id1, id2, id3, id4, id5)
+        assert(id1_n == 'id1')
+        assert(id2_n == 'id2')
+        assert(id3_n == 'id3')
+        assert(id4_n == 'id4')
+        assert(id5_n == 'id5')
+    end
+end

develop/untests.lua

@@ -6325,3 +6325,36 @@ do
         assert(not chunk and not entity_list and not entity_count)
     end
 end
+
+do
+    local function v2(x, y) return { x = x or 0, y = y or 0 } end
+    local function v2_clone(v) return { x = v.x, y = v.y } end
+
+    local v2_default = v2(1, 2)
+
+    do
+        local f = evo.builder():default(v2_default):spawn()
+
+        local b = evo.builder()
+
+        b:set(f)
+        evo.remove(f, evo.DEFAULT)
+
+        local e = b:spawn()
+        assert(evo.has(e, f) and evo.get(e, f).x == 1 and evo.get(e, f).y == 2)
+        assert(evo.get(e, f) == v2_default)
+    end
+
+    do
+        local f = evo.builder():default(v2_default):duplicate(v2_clone):spawn()
+
+        local b = evo.builder()
+
+        b:set(f)
+        evo.remove(f, evo.DEFAULT, evo.DUPLICATE)
+
+        local e = b:spawn()
+        assert(evo.has(e, f) and evo.get(e, f).x == 1 and evo.get(e, f).y == 2)
+        assert(evo.get(e, f) ~= v2_default)
+    end
+end