Sovereignty/jecs
1
0
Fork 0
mirror of https://github.com/Ukendio/jecs.git synced 2025-04-24 17:10:03 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Add EcsOnDelete support

Browse source
This commit is contained in:
Ukendio 2024-08-30 03:23:10 +02:00
parent 5cade93cbd
commit 1fb1ed56c4
3 changed files with 144 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

113
docs/learn/concepts/component-traits.md Normal file
View file

@ -0,0 +1,113 @@
# Component Traits
Component traits are ID 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)

36
src/init.luau
View file

@ -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 EcsDelete = HI_COMPONENT_ID + 8
local EcsTag = HI_COMPONENT_ID + 9
local EcsRest = HI_COMPONENT_ID + 10
local EcsOnDelete = HI_COMPONENT_ID + 7
local EcsOnDeleteTarget = HI_COMPONENT_ID + 8
local EcsDelete = HI_COMPONENT_ID + 9
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_HAS_HOOKS = 0b0010
--local EcsIdExclusive = 0b0100
local ECS_ID_IS_TAG = 0b1000
local ECS_ID_DELETE = 0b00000001
local ECS_ID_HAS_HOOKS = 0b00000010
local ECS_ID_IS_TAG = 0b00000100
local ECS_ID_MASK = 0b00000000
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
flags = bit32.bor(flags, ECS_ID_HAS_DELETE)
local cleanup_policy = world_target(world, relation, EcsOnDelete)
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,

10
test/tests.luau
View file

@ -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"