Merge branch 'feature/lookup' into dev

Author: BlackMATov

README.md

@@ -53,6 +53,7 @@
     - [Internal Fragments](#internal-fragments)
     - [Shared Components](#shared-components)
     - [Fragment Requirements](#fragment-requirements)
+    - [Id Names](#id-names)
     - [Destruction Policies](#destruction-policies)
     - [Custom Component Storages](#custom-component-storages)
   - [Garbage Collection](#garbage-collection)
@@ -64,6 +65,7 @@
     - [Chunk](#chunk)
     - [Builder](#builder)
 - [Changelog](#changelog)
+  - [vX.Y.Z](#vxyz)
   - [v1.9.0](#v190)
   - [v1.8.0](#v180)
   - [v1.7.0](#v170)
@@ -1161,6 +1163,41 @@ local enemy = evolved.builder()
 assert(evolved.has_all(enemy, position, velocity))
 ```
 
+#### Id 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)
+```
+
 #### Destruction Policies
 
 Typically, fragments remain alive for the entire lifetime of the program. However, in some cases, you might want to destroy fragments when they are no longer needed. For example, you can use some runtime entities as fragments for other entities. In this case, you might want to destroy such fragments even while they are still attached to other entities. Since entities cannot have destroyed fragments, a destruction policy must be applied to resolve this. By default, the library will remove the destroyed fragment from all entities that have it.
@@ -1496,6 +1533,9 @@ execute :: query -> {execute_state? -> chunk?, entity[]?, integer?}, execute_sta
 
 locate :: entity -> chunk?, integer
 
+lookup :: string -> entity?
+multi_lookup :: string -> entity[], integer
+
 process :: system... -> ()
 process_with :: system, ... -> ()
 
@@ -1585,6 +1625,10 @@ builder_mt:destruction_policy :: id -> builder
 
 ## Changelog
 
+### vX.Y.Z
+
+- Added the new [`evolved.lookup`](#evolvedlookup) and [`evolved.multi_lookup`](#evolvedmulti_lookup) functions that allow finding ids by their names
+
 ### v1.9.0
 
 - Performance improvements of the [`evolved.destroy`](#evolveddestroy) and [`evolved.batch_destroy`](#evolvedbatch_destroy) functions
@@ -2001,6 +2045,25 @@ 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.process`
 
 ```lua

develop/all.lua

@@ -4,6 +4,7 @@ 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/testing/lookup_tests.lua

@@ -0,0 +1,176 @@
+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

evolved.d.tl

@@ -208,6 +208,9 @@
 
     locate: function(entity: Entity): Chunk | nil, integer
 
+    lookup: function(name: string): Entity | nil
+    multi_lookup: function(name: string): { Entity }, integer
+
     process: function(...: System)
     process_with: function(system: System, ...: any)