Add EcsOnDelete support (#111)

* Add EcsOnDelete support

* Shrink mask

* Add indentation for flags

* Rename page

* Add page to items

* IDs should be plural

* Polish changelog

* Cleanup action Remove is default

CHANGELOG.md

@@ -9,15 +9,22 @@ The format is based on [Keep a Changelog][kac], and this project adheres to
 [semver]: https://semver.org/spec/v2.0.0.html
 
 ## [Unreleased]
+- `[traits]`:
+    - Added cleanup condition `jecs.OnDelete` for when the entity or component is deleted
+    - Added cleanup action `jecs.Remove` which removes instances of the specified (component) id from all entities
+        - This is the default cleanup action
+    - Added component trait `jecs.Tag` which allows for zero-cost components used as tags
+        - Setting data to a component with this trait will do nothing
 - `[luau]`:
-    - Exported Query
+    - Exported `world:contains()`
-    - Improved types for the hooks `OnAdd`, `OnSet`, `OnRemove`
+    - Exported `query:drain()`
-    - Expose `world:contains()` in `World` type and expose `query:drain()` in `Query` type
+    - Exported `Query`
-    - Allow functions to accept any ID including pairs in type parameters
+    - Improved types for the hook `OnAdd`, `OnSet`, `OnRemove`
+    - Changed functions to accept any ID including pairs in type parameters
       - Applies to `world:add()`, `world:set()`, `world:remove()`, `world:get()`, `world:has()` and `world:query()`
       - New exported type `Id<T = nil> = Entity<T> | Pair`
-    - Make `world:contains()` return a `boolean` instead of an entity which may or may not exist
+    - Changed `world:contains()` to return a `boolean` instead of an entity which may or may not exist
-    - Fix `world:has()` to explicitly take in an entity (new: `(self: World, entity: Entity, ...id) -> boolean`, old: `(self: World, ...Id) -> boolean`)
+    - Fixed `world:has()` to take the correct parameters
 
 ## [0.2.2] - 2024-07-07
 

docs/.vitepress/config.mts

@@ -38,6 +38,7 @@ export default defineConfig({
                         { text: 'Entities and Components', link: '/learn/concepts/entities-and-components' },
                         { text: 'Queries', link: '/learn/concepts/queries' },
                         { text: 'Relationships', link: '/learn/concepts/relationships' },
+                        { text: 'Builtin Component Traits', link: 'learn/concepts/builtin-component-traits' }
                     ]
                 },
                 {

docs/learn/concepts/builtin-component-traits.md

@@ -0,0 +1,114 @@
+# Builtin Component Traits
+
+Component traits are IDs and pairs that can be added to components to modify their behavior. This manual contains an overview of all component traits supported by Jecs.
+
+
+# Cleanup Traits
+
+When entities that are used as tags, components, relationships or relationship targets are deleted, cleanup traits ensure that the store does not contain any dangling references. Any cleanup policy provides this guarantee, so while they are configurable, games cannot configure traits that allows for dangling references.
+
+We also want to specify this per relationship. If an entity has `(Likes, parent)` we may not want to delete that entity, meaning the cleanup we want to perform for `Likes` and `ChildOf` may not be the same.
+
+This is what cleanup traits are for: to specify which action needs to be executed under which condition. They are applied to entities that have a reference to the entity being deleted: if I delete the `Archer` tag I remove the tag from all entities that have it.
+
+To configure a cleanup policy for an entity, a `(Condition, Action)` pair can be added to it. If no policy is specified, the default cleanup action (`Remove`) is performed.
+
+There are two cleanup actions:
+
+- `Remove`: removes instances of the specified (component) id from all entities (default)
+- `Delete`: deletes all entities with specified id
+
+There are two cleanup conditions:
+
+- `OnDelete`: the component, tag or relationship is deleted
+- `OnDeleteTarget`: a target used with the relationship is deleted
+
+## Examples
+
+The following examples show how to use cleanup traits
+
+### (OnDelete, Remove)
+
+::: code-group
+
+```luau [luau]
+local Archer = world:component()
+world:add(Archer, pair(jecs.OnDelete, jecs.Remove))
+
+local e = world:entity()
+world:add(e, Archer)
+
+-- This will remove Archer from e
+world:delete(Archer)
+```
+
+```typescript [typescript]
+const Archer = world.component()
+world.add(Archer, pair(jecs.OnDelete, jecs.Remove))
+
+const e = world:entity()
+world.add(e, Archer)
+
+// This will remove Archer from e
+world.delete(Archer)
+```
+
+:::
+
+### (OnDelete, Delete)
+::: code-group
+
+```luau [luau]
+local Archer = world:component()
+world:add(Archer, pair(jecs.OnDelete, jecs.Remove))
+
+local e = world:entity()
+world:add(e, Archer)
+
+-- This will remove Archer from e
+world:delete(Archer)
+```
+
+```typescript [typescript]
+const Archer = world.component()
+world.add(Archer, pair(jecs.OnDelete, jecs.Remove))
+
+const e = world:entity()
+world.add(e, Archer)
+
+// This will remove Archer from e
+world.delete(Archer)
+```
+
+:::
+
+### (OnDeleteTarget, Delete)
+
+::: code-group
+
+```luau [luau]
+local ChildOf = world:component()
+world:add(ChildOf, pair(jecs.OnDeleteTarget, jecs.Delete))
+
+local parent = world:entity()
+local child = world:entity()
+world:add(child, pair(ChildOf, parent))
+
+-- This will delete both parent and child
+world:delete(parent)
+```
+
+```typescript [typescript]
+const Archer = world.component()
+world.add(Archer, pair(jecs.OnDelete, jecs.Remove))
+
+const e = world:entity()
+world.add(e, Archer)
+
+// This will delete e
+world.delete(Archer)
+```
+
+:::
+
+This page takes wording and terminology directly from Flecs [documentation](https://www.flecs.dev/flecs/md_docs_2ComponentTraits.html)

src/init.luau

@@ -65,20 +65,22 @@ local EcsOnSet 				= HI_COMPONENT_ID + 3
 local EcsWildcard 			= HI_COMPONENT_ID + 4
 local EcsChildOf 			= HI_COMPONENT_ID + 5
 local EcsComponent  		= HI_COMPONENT_ID + 6
-local EcsOnDeleteTarget     = HI_COMPONENT_ID + 7
+local EcsOnDelete           = HI_COMPONENT_ID + 7
-local EcsDelete             = HI_COMPONENT_ID + 8
+local EcsOnDeleteTarget     = HI_COMPONENT_ID + 8
-local EcsTag                = HI_COMPONENT_ID + 9
+local EcsDelete             = HI_COMPONENT_ID + 9
-local EcsRest 				= HI_COMPONENT_ID + 10
+local EcsRemove             = HI_COMPONENT_ID + 10
+local EcsTag                = HI_COMPONENT_ID + 11
+local EcsRest 				= HI_COMPONENT_ID + 12
 
 local ECS_PAIR_FLAG 		= 0x8
 local ECS_ID_FLAGS_MASK 	= 0x10
 local ECS_ENTITY_MASK 		= bit32.lshift(1, 24)
 local ECS_GENERATION_MASK 	= bit32.lshift(1, 16)
 
-local ECS_ID_HAS_DELETE     = 0b0001
+local ECS_ID_DELETE         = 0b0001
 local ECS_ID_HAS_HOOKS      = 0b0010
---local EcsIdExclusive   = 0b0100
+local ECS_ID_IS_TAG         = 0b0100
-local ECS_ID_IS_TAG         = 0b1000
+local ECS_ID_MASK           = 0b0000
 
 local NULL_ARRAY = table.freeze({})
 
@@ -427,11 +429,15 @@ local function id_record_ensure(
 	local idr = componentIndex[id]
 
 	if not idr then
-	    local flags = 0b0000
+	    local flags = ECS_ID_MASK
 		local relation = ECS_ENTITY_T_HI(id)
-		local cleanup_policy = world_target(world, relation, EcsOnDeleteTarget)
+
-		if cleanup_policy == EcsDelete then
+		local cleanup_policy = world_target(world, relation, EcsOnDelete)
-            flags = bit32.bor(flags, ECS_ID_HAS_DELETE)
+		local cleanup_policy_target = world_target(world, relation,
+		    EcsOnDeleteTarget)
+
+		if cleanup_policy == EcsDelete or cleanup_policy_target == EcsDelete then
+            flags = bit32.bor(flags, ECS_ID_DELETE)
 		end
 
 		if world_has_any(world, relation,
@@ -818,7 +824,7 @@ local function archetype_delete(world: World,
             end
         end
         local flags = idr.flags
-        if bit32.band(flags, ECS_ID_HAS_DELETE) ~= 0 then
+        if bit32.band(flags, ECS_ID_DELETE) ~= 0 then
             for _, child in children do
                 -- Cascade deletion to children
                 world_delete(world, child)
@@ -880,7 +886,7 @@ local function archetype_delete(world: World,
 
                 if id_record then
                     local flags = id_record.flags
-                    if bit32.band(flags, ECS_ID_HAS_DELETE) ~= 0 then
+                    if bit32.band(flags, ECS_ID_DELETE) ~= 0 then
                         for _, child in children do
                             -- Cascade deletions of it has Delete as component trait
                             world_delete(world, child)
@@ -1600,8 +1606,10 @@ return {
 	Component = EcsComponent :: Entity,
 	Wildcard = EcsWildcard :: Entity,
 	w = EcsWildcard :: Entity,
+	OnDelete = EcsOnDelete :: Entity,
 	OnDeleteTarget = EcsOnDeleteTarget :: Entity,
 	Delete = EcsDelete :: Entity,
+	Remove = EcsRemove :: Entity,
 	Tag = EcsTag :: Entity,
 	Rest = EcsRest :: Entity,
 

test/tests.luau

@@ -769,7 +769,7 @@ TEST("world:delete", function()
 		world:set(id1, Health, 50)
 
 		world:delete(id)
-
+		CHECK(not world:contains(id))
 		CHECK(world:get(id, Poison) == nil)
 		CHECK(world:get(id, Health) == nil)
 
@@ -781,6 +781,7 @@ TEST("world:delete", function()
         local world = jecs.World.new()
 
 		local Health = world:entity()
+		world:add(Health, pair(jecs.OnDelete, jecs.Delete))
 		local Poison = world:component()
 
 		local id = world:entity()
@@ -794,8 +795,15 @@ TEST("world:delete", function()
 		CHECK(world:has(id1, Poison, Health))
 		world:delete(Poison)
 
+		CHECK(world:contains(id))
 		CHECK(not world:has(id, Poison))
 		CHECK(not world:has(id1, Poison))
+
+		world:delete(Health)
+		CHECK(not world:contains(id))
+		CHECK(not world:contains(id1))
+		CHECK(not world:has(id, Health))
+		CHECK(not world:has(id1, Health))
 	end
 
 	do CASE "delete children"