lookup api and basic tests

README.md

@@ -1496,6 +1496,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, ... -> ()
 
@@ -2001,6 +2004,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,110 @@
+local evo = require 'evolved'
+
+evo.debug_mode(true)
+
+do
+    local e1, e2, e3 = evo.id(3)
+
+    do
+        assert(evo.lookup('hello') == nil)
+        assert(evo.lookup('world') == nil)
+
+        do
+            local entity_list, entity_count = evo.multi_lookup('hello')
+            assert(entity_list and #entity_list == 0 and entity_count == 0)
+        end
+
+        do
+            local entity_list, entity_count = evo.multi_lookup('world')
+            assert(entity_list and #entity_list == 0 and entity_count == 0)
+        end
+    end
+
+    evo.set(e1, evo.NAME, 'hello')
+
+    do
+        assert(evo.lookup('hello') == e1)
+        assert(evo.lookup('world') == nil)
+
+        do
+            local entity_list, entity_count = evo.multi_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('world')
+            assert(entity_list and #entity_list == 0 and entity_count == 0)
+        end
+    end
+
+    evo.set(e2, evo.NAME, 'hello')
+    evo.set(e3, evo.NAME, 'hello')
+
+    do
+        assert(evo.lookup('hello') == e3)
+        assert(evo.lookup('world') == nil)
+
+        do
+            local entity_list, entity_count = evo.multi_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, 'world')
+
+    do
+        assert(evo.lookup('hello') == e3)
+        assert(evo.lookup('world') == e2)
+
+        do
+            local entity_list, entity_count = evo.multi_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('world')
+            assert(entity_list and #entity_list == 1 and entity_count == 1)
+            assert(entity_list[1] == e2)
+        end
+    end
+
+    evo.set(e3, evo.NAME, 'world')
+
+    do
+        assert(evo.lookup('hello') == e1)
+        assert(evo.lookup('world') == e3)
+
+        do
+            local entity_list, entity_count = evo.multi_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('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('hello') == nil)
+        assert(evo.lookup('world') == e3)
+
+        do
+            local entity_list, entity_count = evo.multi_lookup('hello')
+            assert(entity_list and #entity_list == 0 and entity_count == 0)
+        end
+
+        do
+            local entity_list, entity_count = evo.multi_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

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)