Skip to content

archetype_destroy keeps three references to the destroyed archetype and under-counts wildcard record sizes - #340

Merged
Ukendio merged 1 commit into
Ukendio:mainfrom
dubalda:archetype-destroy-fix
Sep 17, 2026
Merged

Ukendio merged 1 commit into
Ukendio:mainfrom
dubalda:archetype-destroy-fix

Conversation

@dubalda

@dubalda dubalda commented Sep 16, 2026

Copy link
Copy Markdown
Contributor

When an archetype is destroyed (world:cleanup(), or world:delete() of an entity used as a component or pair target), three structures still point at it afterwards:

  1. world.archetype_edges[archetype.id] - the edge table is emptied but its key is never removed, so every destroyed archetype leaves one empty table behind.
  2. componentrecord.cache - archetype_append_to_records appends the archetype id to the cache list of every component record of the archetype (including the (R, *) and (*, T) wildcard records), and nothing ever removes it. world:delete walks this list for pairs targeting the deleted entity and skips ids of dead archetypes, so the stale entries are harmless functionally, but the list grows by one entry per component per created archetype for the whole life of the world.
  3. componentrecord.wildcard_pairs of a (R, *) record keeps the record of every pair (R, T) ever seen; when a pair record leaves component_index (its size reached zero) it stays referenced from wildcard_pairs.
  4. size of the wildcard records (R, *) and (*, T) drifts upwards. archetype_create does idr_r.size += 1 / idr_t.size += 1 once per pair in the archetype, so an archetype with (R, T1) and (R, T2) adds 2 to (R, *), but archetype_destroy iterates columns_map, where (R, *) is a single key, and subtracts 1. After such an archetype is destroyed the wildcard record keeps size >= 1 with an empty records map and is never removed from component_index.

Item 4 is not just a leak. The stale (R, *) record survives world:delete(R) together with its flags (ECS_ID_DELETE, ECS_ID_IS_TAG, ECS_ID_IS_EXCLUSIVE) and hooks. Pair ids are built from the entity index only, so when the index of R is recycled, id_record_ensure hands the stale record to the new entity: an entity R2 that has no (OnDelete, Delete) trait at all inherits the cascade policy of the dead R, and world:delete(R2) deletes every entity that holds an (R2, *) pair instead of just removing the pair. The same happens for (*, T) records when the index of a target is recycled. Repro:

local world = jecs.world()
local R = world:entity()
world:add(R, jecs.pair(jecs.OnDelete, jecs.Delete))
local t1, t2 = world:entity(), world:entity()
local e = world:entity()
world:add(e, jecs.pair(R, t1))
world:add(e, jecs.pair(R, t2))       -- (R, *).size == 3 for two live archetypes
world:delete(e)
world:cleanup()                       -- both archetypes destroyed, (R, *).size == 1, records == {}
world:delete(R)                       -- (R, *) record survives, still flagged ECS_ID_DELETE

local R2 = world:entity()             -- reuses the index of R, so pair(R2, *) == pair(R, *)
local f = world:entity()
world:add(f, jecs.pair(R2, t1))       -- attaches to the stale record
world:delete(R2)
print(world:contains(f))              -- false; expected true, R2 has no OnDelete policy

With a single (R, T) pair on e (no drift) the record is dropped on world:delete(R) and f survives. A minimal fix is idr.size -= idr.counts[archetype_id] in archetype_destroy (counts[archetype_id] is exactly how many times archetype_create incremented size for that archetype), done before counts[archetype_id] is cleared.

In a world where entities are built component by component and empty archetypes are reclaimed periodically, the same intermediate archetypes are created and destroyed over and over (we measured ~250 archetype creations per second in a 30-NPC combat scene), and the process memory of the world grew by 5–9 MB per minute with a flat entity count: component_index.*.cache reached 776 000 numbers in 141 s, archetype_edges had one key per archetype ever created.


jecs@0.11.0

@Ukendio Ukendio left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the contribution. There are some things that I am going to change for the major release. But I will be merging this to keep the change indexable

@Ukendio
Ukendio merged commit 0ca7a3b into Ukendio:main Sep 17, 2026
2 checks passed
@dubalda
dubalda deleted the archetype-destroy-fix branch September 17, 2026 14:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants