separate unique/explicit traits instead hidden

README.md

@@ -31,7 +31,9 @@ TAG :: fragment
 NAME :: fragment
 PREFAB :: fragment
 
-HIDDEN :: fragment
+UNIQUE :: fragment
+EXPLICIT :: fragment
+
 DEFAULT :: fragment
 DUPLICATE :: fragment
 

develop/all.lua

@@ -9,3 +9,7 @@ print '----------------------------------------'
 basics.describe_fuzz 'develop.fuzzing.destroy_fuzz'
 print '----------------------------------------'
 basics.describe_fuzz 'develop.fuzzing.batch_destroy_fuzz'
+print '----------------------------------------'
+basics.describe_fuzz 'develop.fuzzing.explicit_fuzz'
+print '----------------------------------------'
+basics.describe_fuzz 'develop.fuzzing.unique_fuzz'

develop/fuzzing/explicit_fuzz.lua

@@ -33,7 +33,7 @@ for _, entity in ipairs(all_entity_list) do
     end
 
     if math.random(1, 5) == 1 then
-        evo.set(entity, evo.HIDDEN)
+        evo.set(entity, evo.EXPLICIT)
     end
 end
 
@@ -64,7 +64,7 @@ for _ = 1, 100 do
         local fragment_list, fragment_count = chunk:fragments()
         for i = 1, fragment_count do
             local fragment = fragment_list[i]
-            assert(include_set[fragment] or not evo.has(fragment, evo.HIDDEN))
+            assert(include_set[fragment] or not evo.has(fragment, evo.EXPLICIT))
         end
     end
 

develop/fuzzing/unique_fuzz.lua

@@ -0,0 +1,67 @@
+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[]
+
+for i = 1, math.random(1, 10) do
+    local entity = evo.id()
+    all_entity_list[i] = entity
+end
+
+for _, entity in ipairs(all_entity_list) do
+    for _ = 0, math.random(0, #all_entity_list) do
+        local fragment = all_entity_list[math.random(1, #all_entity_list)]
+        evo.set(entity, fragment)
+    end
+
+    if math.random(1, 5) == 1 then
+        evo.set(entity, evo.UNIQUE)
+    end
+end
+
+---
+---
+---
+---
+---
+
+for _, entity in ipairs(all_entity_list) do
+    local entity_clone = evo.clone(entity)
+
+    for fragment in evo.each(entity_clone) do
+        assert(not evo.has(fragment, evo.UNIQUE))
+    end
+
+    for fragment in evo.each(entity) do
+        assert(evo.has(entity_clone, fragment) or evo.has(fragment, evo.UNIQUE))
+    end
+
+    evo.destroy(entity_clone)
+end
+
+---
+---
+---
+---
+---
+
+evo.destroy(__table_unpack(all_entity_list))
+evo.collect_garbage()

develop/untests.lua

@@ -6160,8 +6160,8 @@ end
 do
     local f1, f2, f3 = evo.id(3)
 
-    evo.set(f2, evo.HIDDEN)
+    evo.set(f2, evo.UNIQUE)
-    evo.set(f3, evo.HIDDEN)
+    evo.set(f3, evo.UNIQUE)
 
     do
         local p = evo.spawn { [f1] = 11, [f2] = 22 }
@@ -6239,7 +6239,7 @@ end
 do
     local f1, f2, f3 = evo.id(3)
 
-    evo.set(f2, evo.HIDDEN)
+    evo.set(f2, evo.UNIQUE)
 
     do
         local p = evo.spawn { [f1] = 11, [f2] = 22, [f3] = 33 }
@@ -6275,7 +6275,7 @@ do
 
         for c in evo.execute(q) do
             local fs, fc = c:fragments()
-            for i = 1, fc do assert(not evo.has(fs[i], evo.HIDDEN)) end
+            for i = 1, fc do assert(not evo.has(fs[i], evo.EXPLICIT)) end
         end
     end
 
@@ -6284,7 +6284,7 @@ do
 
         for c in evo.execute(q) do
             local fs, fc = c:fragments()
-            for i = 1, fc do assert(not evo.has(fs[i], evo.HIDDEN)) end
+            for i = 1, fc do assert(not evo.has(fs[i], evo.EXPLICIT)) end
         end
     end
 end
@@ -6292,7 +6292,7 @@ end
 do
     local f1, f2 = evo.id(2)
 
-    evo.set(f2, evo.HIDDEN)
+    evo.set(f2, evo.EXPLICIT)
 
     local e1 = evo.builder():set(f1, 11):spawn()
     local e2 = evo.builder():set(f1, 11):set(f2, 22):spawn()

evolved.lua

@@ -124,9 +124,12 @@ local __query_sorted_excludes = {} ---@type table<evolved.query, evolved.assoc_l
 ---@field package __has_assign_hooks boolean
 ---@field package __has_insert_hooks boolean
 ---@field package __has_remove_hooks boolean
----@field package __has_hidden_major boolean
+---@field package __has_unique_major boolean
----@field package __has_hidden_minors boolean
+---@field package __has_unique_minors boolean
----@field package __has_hidden_fragments boolean
+---@field package __has_unique_fragments boolean
+---@field package __has_explicit_major boolean
+---@field package __has_explicit_minors boolean
+---@field package __has_explicit_fragments boolean
 local __chunk_mt = {}
 __chunk_mt.__index = __chunk_mt
 
@@ -626,7 +629,7 @@ local function __execute_iterator(execute_state)
             local chunk_child_fragment = chunk_child.__fragment
 
             local is_chunk_child_matched =
-                (not chunk_child.__has_hidden_major) and
+                (not chunk_child.__has_explicit_major) and
                 (not exclude_set or not exclude_set[chunk_child_fragment])
 
             if is_chunk_child_matched then
@@ -658,7 +661,9 @@ local __TAG = __acquire_id()
 local __NAME = __acquire_id()
 local __PREFAB = __acquire_id()
 
-local __HIDDEN = __acquire_id()
+local __UNIQUE = __acquire_id()
+local __EXPLICIT = __acquire_id()
+
 local __DEFAULT = __acquire_id()
 local __DUPLICATE = __acquire_id()
 
@@ -1018,9 +1023,13 @@ local function __new_chunk(chunk_parent, chunk_fragment)
     local has_remove_hooks = (chunk_parent ~= nil and chunk_parent.__has_remove_hooks)
         or __evolved_has(chunk_fragment, __ON_REMOVE)
 
-    local has_hidden_major = __evolved_has(chunk_fragment, __HIDDEN)
+    local has_unique_major = __evolved_has(chunk_fragment, __UNIQUE)
-    local has_hidden_minors = chunk_parent ~= nil and chunk_parent.__has_hidden_fragments
+    local has_unique_minors = chunk_parent ~= nil and chunk_parent.__has_unique_fragments
-    local has_hidden_fragments = has_hidden_major or has_hidden_minors
+    local has_unique_fragments = has_unique_major or has_unique_minors
+
+    local has_explicit_major = __evolved_has(chunk_fragment, __EXPLICIT)
+    local has_explicit_minors = chunk_parent ~= nil and chunk_parent.__has_explicit_fragments
+    local has_explicit_fragments = has_explicit_major or has_explicit_minors
 
     ---@type evolved.chunk
     local chunk = __lua_setmetatable({
@@ -1045,9 +1054,12 @@ local function __new_chunk(chunk_parent, chunk_fragment)
         __has_assign_hooks = has_assign_hooks,
         __has_insert_hooks = has_insert_hooks,
         __has_remove_hooks = has_remove_hooks,
-        __has_hidden_major = has_hidden_major,
+        __has_unique_major = has_unique_major,
-        __has_hidden_minors = has_hidden_minors,
+        __has_unique_minors = has_unique_minors,
-        __has_hidden_fragments = has_hidden_fragments,
+        __has_unique_fragments = has_unique_fragments,
+        __has_explicit_major = has_explicit_major,
+        __has_explicit_minors = has_explicit_minors,
+        __has_explicit_fragments = has_explicit_fragments,
     }, __chunk_mt)
 
     if chunk_parent then
@@ -1235,16 +1247,16 @@ end
 ---@param chunk? evolved.chunk
 ---@return evolved.chunk?
 ---@nodiscard
-local function __chunk_without_hidden_fragments(chunk)
+local function __chunk_without_unique_fragments(chunk)
     if not chunk then
         return nil
     end
 
-    if not chunk.__has_hidden_fragments then
+    if not chunk.__has_unique_fragments then
         return chunk
     end
 
-    while chunk and chunk.__has_hidden_major do
+    while chunk and chunk.__has_unique_major do
         chunk = chunk.__parent
     end
 
@@ -1257,7 +1269,7 @@ local function __chunk_without_hidden_fragments(chunk)
         for i = 1, chunk_fragment_count do
             local fragment = chunk_fragment_list[i]
 
-            if not __evolved_has(fragment, __HIDDEN) then
+            if not __evolved_has(fragment, __UNIQUE) then
                 new_chunk = __chunk_with_fragment(new_chunk, fragment)
             end
         end
@@ -1702,7 +1714,7 @@ local function __clone_entity(entity, prefab, components)
     local prefab_place = __entity_places[prefab_index]
 
     local chunk = __chunk_with_components(
-        __chunk_without_hidden_fragments(prefab_chunk),
+        __chunk_without_unique_fragments(prefab_chunk),
         components)
 
     if not chunk then
@@ -4369,14 +4381,14 @@ function __evolved_execute(query)
                 (query_exclude_count == 0 or not __chunk_has_any_fragment_list(
                     major_chunk, query_exclude_list, query_exclude_count))
 
-            if is_major_chunk_matched and major_chunk.__has_hidden_minors then
+            if is_major_chunk_matched and major_chunk.__has_explicit_minors then
                 local major_chunk_fragment_list = major_chunk.__fragment_list
                 local major_chunk_fragment_count = major_chunk.__fragment_count
 
                 for major_chunk_fragment_index = 1, major_chunk_fragment_count - 1 do
                     local major_chunk_fragment = major_chunk_fragment_list[major_chunk_fragment_index]
 
-                    if not query_include_set[major_chunk_fragment] and __evolved_has(major_chunk_fragment, __HIDDEN) then
+                    if not query_include_set[major_chunk_fragment] and __evolved_has(major_chunk_fragment, __EXPLICIT) then
                         is_major_chunk_matched = false
                         break
                     end
@@ -4391,7 +4403,7 @@ function __evolved_execute(query)
     elseif query_exclude_count > 0 then
         for root_fragment, root_chunk in __lua_next, __root_chunks do
             local is_root_chunk_matched =
-                not root_chunk.__has_hidden_major and
+                not root_chunk.__has_explicit_major and
                 not query_exclude_set[root_fragment]
 
             if is_root_chunk_matched then
@@ -4402,7 +4414,7 @@ function __evolved_execute(query)
     else
         for _, root_chunk in __lua_next, __root_chunks do
             local is_root_chunk_matched =
-                not root_chunk.__has_hidden_major
+                not root_chunk.__has_explicit_major
 
             if is_root_chunk_matched then
                 chunk_stack_size = chunk_stack_size + 1
@@ -4945,8 +4957,13 @@ function __builder_mt:prefab()
 end
 
 ---@return evolved.builder builder
-function __builder_mt:hidden()
+function __builder_mt:unique()
-    return self:set(__HIDDEN)
+    return self:set(__UNIQUE)
+end
+
+---@return evolved.builder builder
+function __builder_mt:explicit()
+    return self:set(__EXPLICIT)
 end
 
 ---@param default evolved.component
@@ -5099,18 +5116,26 @@ local function __update_chunk_caches_trace(chunk)
     local has_remove_hooks = (chunk_parent ~= nil and chunk_parent.__has_remove_hooks)
         or __evolved_has(chunk_fragment, __ON_REMOVE)
 
-    local has_hidden_major = __evolved_has(chunk_fragment, __HIDDEN)
+    local has_unique_major = __evolved_has(chunk_fragment, __UNIQUE)
-    local has_hidden_minors = chunk_parent ~= nil and chunk_parent.__has_hidden_fragments
+    local has_unique_minors = chunk_parent ~= nil and chunk_parent.__has_unique_fragments
-    local has_hidden_fragments = has_hidden_major or has_hidden_minors
+    local has_unique_fragments = has_unique_major or has_unique_minors
+
+    local has_explicit_major = __evolved_has(chunk_fragment, __EXPLICIT)
+    local has_explicit_minors = chunk_parent ~= nil and chunk_parent.__has_explicit_fragments
+    local has_explicit_fragments = has_explicit_major or has_explicit_minors
 
     chunk.__has_setup_hooks = has_setup_hooks
     chunk.__has_assign_hooks = has_assign_hooks
     chunk.__has_insert_hooks = has_insert_hooks
     chunk.__has_remove_hooks = has_remove_hooks
 
-    chunk.__has_hidden_major = has_hidden_major
+    chunk.__has_unique_major = has_unique_major
-    chunk.__has_hidden_minors = has_hidden_minors
+    chunk.__has_unique_minors = has_unique_minors
-    chunk.__has_hidden_fragments = has_hidden_fragments
+    chunk.__has_unique_fragments = has_unique_fragments
+
+    chunk.__has_explicit_major = has_explicit_major
+    chunk.__has_explicit_minors = has_explicit_minors
+    chunk.__has_explicit_fragments = has_explicit_fragments
 
     return true
 end
@@ -5202,7 +5227,11 @@ local function __update_fragment_tags(fragment)
     __trace_fragment_chunks(fragment, __update_chunk_tags_trace, fragment)
 end
 
-local function __update_fragment_hiddens(fragment)
+local function __update_fragment_uniques(fragment)
+    __trace_fragment_chunks(fragment, __update_chunk_caches_trace, fragment)
+end
+
+local function __update_fragment_explicits(fragment)
     __trace_fragment_chunks(fragment, __update_chunk_caches_trace, fragment)
 end
 
@@ -5219,8 +5248,11 @@ end
 __evolved_set(__TAG, __ON_INSERT, __update_fragment_tags)
 __evolved_set(__TAG, __ON_REMOVE, __update_fragment_tags)
 
-__evolved_set(__HIDDEN, __ON_INSERT, __update_fragment_hiddens)
+__evolved_set(__UNIQUE, __ON_INSERT, __update_fragment_uniques)
-__evolved_set(__HIDDEN, __ON_REMOVE, __update_fragment_hiddens)
+__evolved_set(__UNIQUE, __ON_REMOVE, __update_fragment_uniques)
+
+__evolved_set(__EXPLICIT, __ON_INSERT, __update_fragment_explicits)
+__evolved_set(__EXPLICIT, __ON_REMOVE, __update_fragment_explicits)
 
 __evolved_set(__DEFAULT, __ON_INSERT, __update_fragment_defaults)
 __evolved_set(__DEFAULT, __ON_REMOVE, __update_fragment_defaults)
@@ -5238,7 +5270,9 @@ __evolved_set(__TAG, __NAME, 'TAG')
 __evolved_set(__NAME, __NAME, 'NAME')
 __evolved_set(__PREFAB, __NAME, 'PREFAB')
 
-__evolved_set(__HIDDEN, __NAME, 'HIDDEN')
+__evolved_set(__UNIQUE, __NAME, 'UNIQUE')
+__evolved_set(__EXPLICIT, __NAME, 'EXPLICIT')
+
 __evolved_set(__DEFAULT, __NAME, 'DEFAULT')
 __evolved_set(__DUPLICATE, __NAME, 'DUPLICATE')
 
@@ -5273,10 +5307,16 @@ __evolved_set(__DESTROY_POLICY_REMOVE_FRAGMENT, __NAME, 'DESTROY_POLICY_REMOVE_F
 __evolved_set(__TAG, __TAG)
 
 __evolved_set(__PREFAB, __TAG)
-__evolved_set(__PREFAB, __HIDDEN)
+__evolved_set(__PREFAB, __UNIQUE)
+__evolved_set(__PREFAB, __EXPLICIT)
 
-__evolved_set(__HIDDEN, __TAG)
+__evolved_set(__UNIQUE, __TAG)
-__evolved_set(__HIDDEN, __HIDDEN)
+__evolved_set(__UNIQUE, __UNIQUE)
+__evolved_set(__UNIQUE, __EXPLICIT)
+
+__evolved_set(__EXPLICIT, __TAG)
+__evolved_set(__EXPLICIT, __UNIQUE)
+__evolved_set(__EXPLICIT, __EXPLICIT)
 
 __evolved_set(__INCLUDES, __DEFAULT, {})
 __evolved_set(__INCLUDES, __DUPLICATE, __list_copy)
@@ -5408,7 +5448,9 @@ evolved.TAG = __TAG
 evolved.NAME = __NAME
 evolved.PREFAB = __PREFAB
 
-evolved.HIDDEN = __HIDDEN
+evolved.UNIQUE = __UNIQUE
+evolved.EXPLICIT = __EXPLICIT
+
 evolved.DEFAULT = __DEFAULT
 evolved.DUPLICATE = __DUPLICATE