Changelog
v1.3.0 — 2026-11-07
Changed behavior
What the calls return and in which order stay those of 1.2.0, except for two things: what a loop
over the bitsets of a query returns for an entity that its body deleted ahead of it, and the
arguments of OnChange hooks and world:changed listeners.
- A loop over the bitsets skips an entity that its body deleted ahead of it. A for-in loop of
a query that passes over the bitsets (a query written inline whose smallest term spans more
than 2 048 slots; a stored or cached query whose matches are dense, or changed much since its
previous loop) reads the current run of matching slots, or the matches left in a 32-slot word,
before its body runs.
- Before (1.0.0–1.2.0): an entity of that word that the body deleted came back as a negative
number (the mark of the free slot,
-1 -the next id of the slot), the id of no entity. In a run of full words (32 matching slots in a row, within one value page of 256 slots) the loop did not end: it went on from slot 2 and returned every slot up to the end of the run, the ids of components and entities without the ids of the query included (they passworld:contains), and came to the freed slot again. - After: the loop skips the slot, as it did when the deleted entity lay in another word. An
entity that took the slot during the loop is returned in its place, whatever its ids. The
match list of a stored query and the matches that a small query gathers first return the
dead id once, as before, with the values that its slot holds when the loop reaches it (those
of an entity that took the slot, if it has them);
query:eachover the bitsets skipped such a slot already. - The check costs a comparison per returned entity in these loops only (see Performance).
- Before (1.0.0–1.2.0): an entity of that word that the body deleted came back as a negative
number (the mark of the free slot,
OnChangehooks andworld:changedlisteners get the value that the change replaced, as a fourth argument:world:changed(Stats, function(entity, id, stats, previous) end).- Before:
(entity, id, value). - After:
(entity, id, value, previous), fromworld:setandquery:set_all, for components and data pairs.previousis nil when the entity had the id without a value (afterworld:set(e, id, nil)); a table changed in place and set again is the same value before and after. In an exclusive replacement whose removal hook set the new pair, it is the value that the hook gave. A listener with three parameters gets what it got; code that reads...orselect("#", ...)sees four values, and a hook written for jecs, whose fourth argument isoldarchetype, gets the replaced value instead. - Types:
ecs.OnChangeisComponent<(entity: Entity, id: Id, value: any?, previous: any?) -> ()>and the listener ofworld:changedis(entity: Entity, id: Id<T>, value: T, previous: T?) -> (); listeners with fewer parameters type-check as before.OnAdd,OnRemove,world:addedandworld:removedkeep their arguments. - The value is the one that the set reads anyway; an id without an
OnChangehook or listener reads nothing more.
- Before:
Tests and tools
test/cases/workload.luau, loops: a query loop that deletes matches ahead of it ends, returns no id twice and no id that never matched, and returns every match of the start that the body did not delete with its own values: queries written inline over runs of full words (0, 1, 2 and 9 returned values), stored and cached queries after loops that matched nothing, partial words, a stored query with a match list and a small query, each with and without entities made in the loop. 1.2.0 fails 16 of its 20 loops.test/loops_fuzz.luau: blocks of adjacent entities that have every component and tag (runs of full words), changes of entities a few places ahead of the current one, and an inline query of a shape of its own in every round (a pass over the bitsets); every loop must end and return only entity ids that matched at the start or that the loop touched or made. 1.2.0 fails it with each of the seeds 1–10.test/cases/hooks.luau: the value that a change replaced, given to anOnChangehook and achangedlistener: a component (an addition gives none, a set of nil gives the old value, the next set gives nil),set_all, a data pair through the hook and the listener of its relation, a set from a listener, and an exclusive replacement whose removal hook set the new pair.test/types.luau:OnChangehooks andchangedlisteners with three and four parameters;test/typecheck/errors.luau: a listener whoseprevioushas another type is rejected.tools/generate.pygenerates the step of the loops over the bitsets that skips a freed slot.
Documentation
- The guide, the API reference (
Query,World:changed,World:set,ecs.OnChange) and the jecs page say what a loop returns for an entity deleted ahead of it (it is skipped, or returned once as a dead id with the values that its slot holds when the loop reaches it:world:containsis the test, and a loop that also makes entities checks the values it reads), and describe the fourth argument ofOnChangehooks andchangedlisteners; the jecs page notes it among the differences and in the migration (it is notoldarchetype). - The comparison pages, the README and the page of the previous release carry the measurements of 1.3.0.
Performance on the reference workload
Both versions are measured with the reference workload model of this release on Luau 0.740,
-O2, in the interpreter and native code, with Roblox Studio and the Roblox player open on the
machine (their load widens the noise of every row). The
full report and
raw samples contain 232
comparison rows from 520 isolated processes: the release run, and 15 more repeats of the stored
queries at their periods (P4) and the frame model (P7) in the interpreter at the four scales of
the server. The release run flagged P4 at the target scale without owned entities in the
interpreter (1.049×); with all repeats it takes 1.041×, within the noise, and no timing row is
slower than the noise. The loops whose step this release changes cost a little more in the
interpreter, within the noise of each row: P4 takes 1.025–1.041× and P7 1.015–1.025× of the time of
1.2.0 at the four scales of the server. In native code, which runs the server, the frame model
takes 1.003–1.027× (1.014× at the target scale) and the lifecycle events of P6 0.95–1.07×, within
the noise; the client profile (P4, usually empty queries; P7, its frame) takes 1.03× / 1.00× and
1.01× / 1.00× (interpreter / native). A build that tested e > 0 instead of e >= s in the step
was measured first: with 20 repeats its P4 at the target scale without owned entities took 1.065×
in the interpreter, beyond the noise; the comparison of two registers takes one instruction less
there. In a loop that only iterates (66 000–100 000 matches, an empty body), a returned entity
costs 3–6 % more in native code and 5–7 % more in the interpreter (1–4 ns). The release improves
no test: the row smaller beyond the noise (P8 bytes per distinct pair at the small scale in the
interpreter, 0.9985×) is one step of the resolution. µs, medians [min–max] of each version's two
control columns:
| Mode | Scale | P7, µs/frame: 1.2.0 → 1.3.0 | P6, the removal of a retained agent, µs: 1.2.0 → 1.3.0 |
|---|---|---|---|
| native | small | 99.34 [97.25–101.30] → 102.03 [98.46–111.24] | 48.57 [44.00–56.45] → 52.15 [49.60–56.80] |
| native | target | 338.89 [331.14–342.11] → 343.71 [338.49–361.42] | 1042.7 [1020.8–1148.6] → 1048.6 [1029.7–1073.7] |
| native | small-empty-retained | 100.18 [96.29–104.14] → 101.16 [99.27–106.58] | 16.35 [14.80–19.55] → 15.57 [14.30–21.35] |
| native | target-empty-retained | 324.88 [316.72–383.50] → 325.89 [316.38–343.18] | 22.5 [20.7–29.5] → 23.2 [20.7–25.6] |
| interpreter | small | 158.06 [155.05–179.14] → 160.41 [156.68–182.35] | 73.25 [70.55–79.10] → 75.47 [67.70–82.65] |
| interpreter | target | 496.31 [485.18–529.37] → 508.52 [489.84–541.46] | 1570.1 [1541.4–1648.4] → 1563.2 [1515.2–1646.0] |
| interpreter | small-empty-retained | 157.12 [154.62–161.79] → 159.71 [155.88–229.24] | 23.50 [21.25–27.25] → 22.57 [21.65–27.50] |
| interpreter | target-empty-retained | 485.89 [474.93–509.91] → 496.10 [484.60–742.41] | 33.1 [29.5–36.5] → 32.2 [30.3–35.7] |
Single operations (1.3.0 and 1.2.0,
measured with the comparison with jecs) have a median ratio of 1.00× in both modes over 95 rows.
The for-in loops of queries over dense matches pay the comparison per returned entity: one value
of an entity with 4 components takes 40.1 / 29.2 instead of 36.9 / 27.9 ns per match (1.09× /
1.05×, interpreter / native), four values 1.04–1.06× in the interpreter and 0.98–1.04× in native
code, a query created and iterated once 1.06× / 1.06×; query:each and the loops over a match
list or a sparse match take the time of 1.2.0. The matrix and the synthetic frame were measured
fifteen times in each mode. The
complete measurements
also compare this campaign with that of 1.2.0, on the same machine: the same code took 0.97–1.07
of its time there.
Memory
A new world takes 56 586 bytes in both versions (200 worlds kept alive), a debug world 60 216: 1.3.0 adds no field and no closure to a world (the dispatcher of the listeners of a change is made when the first of them connects, the function that reads a replaced value is a function of the module), and no per-entity, per-pair or per-query field. The heap of the target world (P8) is 137.63 MB after it is built and 138.57 MB after 100 lifecycle rounds in both versions, a distinct pair with its holder takes 1 527.8 bytes and a holder of a pair 37.1 bytes in both; a loop over a stored query allocates nothing, and the frame model grows the heap by the bytes of 1.2.0 (P9). The rows of bytes per distinct pair move by steps of one KiB over the pairs of a scale: one is flagged, the small scale in native code (+1.72 bytes, one step over its 594 pairs), and the same row of the interpreter moved one step down. A world of the client profile takes the bytes of 1.2.0 to within the 16–32 bytes by which two measurements of one build differ, 182 592 bytes after 6 000 and after 9 000 frames in both: nothing accumulates.
v1.2.0 — 2026-10-18
Changed behavior
What the calls return, in which order, and what a loop sees stay those of 1.1.0. The changes
are in the errors: which ones are raised (by a debug world, by the change filters of untracked
ids, by ecs.pair), their text, and the line they point at.
-
A debug world checks the arguments of every method that takes entities or ids. In a world made with
ecs.world(true), the methods that read raise an error for an entity or an id that is not a number:world:queryand the terms of a query (with,without,any),get,has,get_list,has_all,expect,each,children,target,targets,parent,contains,exists,ids,column,remove_all,track, the signalsadded,changedandremoved,world:entitygiven an id,query:hasand the change filtersquery:added,changedandremoved. The error names the method and the argument, and points at the line of the call. Such a value is usually a nil read from a table of ids by a name that the table does not have.- Before: the nil reached the internals of the method, in a debug world as in any other:
src/init.luau:9506: attempt to compare nil < numberfor an id of a query or of a term,attempt to compare number < nilforget,hasandexpect,attempt to perform arithmetic (mod) on nil and numberfor an entity; or nothing happened:world:each(nil)visited nothing,world:remove_all(nil)removed nothing,world:entity(nil)made a new entity. - After:
world:query: id 1 is nil,query:with: id 2 is nil,world:get: the entity is nil,world:target: the relation is nil,world:each: the id is a string, not a number. - These methods still do not check whether an id is alive: a dead id reads nothing, as in any
world. A world without debug checks nothing and keeps the errors of 1.1.0, except for the
line they point at, the change filters of untracked ids and
ecs.pair(below).
- Before: the nil reached the internals of the method, in a debug world as in any other:
-
A nil after the last id of
getandhasis an error in a debug world.world:get(e, A, missing)returned the value ofAalone andworld:has(e, A, missing)checkedAalone (world:has(e, A, missing, B)was true withoutB); a debug world raisesworld:get: id 2 is nil, and the same forworld:query(A, missing)and the terms of a query. A world without debug reads such a call as before. -
The errors of the checks of changes in a debug world name the method.
entity 4194561 is not alive: an outdated handle or a deleted entityis nowworld:set: entity 4194561 is not alive: …(andworld:delete: …,world:toggle: …),id 271 is not alive: …isworld:add: id 271 is not alive: …(andquery:add_all: …),wildcard pairs can only be used in queries and removeisworld:set: wildcard pairs …,an element of the pair is not aliveisworld:remove: an element of the pair is not alive. An argument that is not a number readsworld:set: the id is nil(wasid nil is not a number) andworld:set: the entity is nil(wasentity nil is not alive: an outdated handle or a deleted entity). -
A change filter of an id that is not tracked raises its error at every use, in any world.
- Before:
query:hasreturned false, also for:created()withoutworld:track_created(). A loop,each,countand the batch operations raised the error once per tick: the error marked the ticks as seen, so the next use in the same tick found nothing (countreturned 0). And a query whose earlier filter had no changes returned nothing without checking the later ones:world:query(A):added(A):changed(B)withBuntracked raised the error only in the ticks whenAwas added. - After: every use raises
change filters need a tracked id: call world:track(id) first(orthe created filter needs world:track_created() first) at the line of the call, whatever the entity, the changes and the previous uses.
- Before:
-
ecs.pairrefuses a nil element, in any world.ecs.pair(R, missing)raisedsrc/init.luau:1559: attempt to perform arithmetic (mod) on nil and numberinside the library, also as an argument of a call of a debug world (the pair is made before the call); it raisesecs.pair: the target is nil(orthe relation is nil) at the line of the call. Other values that are not numbers stay as in 1.1.0: the arithmetic error of Luau, and a string of digits makes a pair. The test costs about 2 ns per call in the interpreter and nothing measurable in native code (see Performance). -
Errors point at the line that called the library, in any world. An error raised for a mistake of the caller names the line of that call, whatever the depth of the library function that finds it; in a hook or a listener, the line in the hook. The messages stay the same; the position in front of them changes. Before:
- in a debug world, the error for an entity that is not alive (
set,add,remove,delete,clear,toggle) named the line of the caller of the caller, or no line when that was a C function such aspcall: the compiler inlined the check, and its error level was counted from the method. The errors thatsetraises itself (a value set on a tag or on a tag pair) named a line ofsrc/init.luau: the check of the debug world was one frame more; - in any world, these named a line of
src/init.luau:setandaddof a wildcard pair whose relation had no pair yet, and of a pair whose relation or target has a free slot; a change filter of an id that is not tracked, and the created filter withoutworld:track_created(), in aforloop;world:entity()beyond the end ofworld:range;ecs.component()beyond 256 ids; - these had no line at all: the
Componenttrait added to an id used already or removed from it, theExclusivetrait added to a relation that an entity has with several targets, and the hooks that keep a delete going (hooks keep giving an id to entities while it is deletedand the like).
The function that raises them (
fail) finds the first frame of the stack outside the library, so the line does not depend on helpers, on the checks of a debug world or on what the compiler inlines; it runs only when an error is raised. - in a debug world, the error for an entity that is not alive (
The cost of the checks of a debug world
A debug world checks the arguments of every call; a world without debug makes no check, and its
methods run the code of 1.1.0 but for the paths that raise errors. One call per entity over 700
entities, ns per call, the median of three processes of 7 rounds each, Luau 0.740 -O2:
| Call of a debug world | interpreter: 1.1.0 → 1.2.0 | native: 1.1.0 → 1.2.0 |
|---|---|---|
get(e, A) | 56.4 → 81.8 | 38.8 → 59.4 |
get(e, A, B) | 68.9 → 110.9 | 42.5 → 67.2 |
has(e, T) | 70.0 → 97.4 | 50.6 → 68.1 |
contains(e) | 35.9 → 54.0 | 23.9 → 34.5 |
expect(e, A) | 56.0 → 76.1 | 32.0 → 43.2 |
set(e, A, 1) (checked in 1.1.0 already) | 123.0 → 127.8 | 72.4 → 76.6 |
query(A):with(T) written inline, a loop left at its first match | 2 386 → 2 551 | 2 127 → 2 098 |
| a cached query, a loop left at its first match | 2 193 → 2 204 | 1 848 → 1 823 |
A read costs 11–25 ns more in native code (get and has, which take any number of ids, the
most); the call of a query costs the same within a few percent, and its loops nothing more. The
same calls of a world without debug take 0.97–1.03× of the time of 1.1.0 in these runs.
Tests and tools
test/lib.luau: every check of the arguments of a debug world with its message and the line it points at (each method; a nil in the first, a middle and the last place; values of other types; the changes with their method names), the calls with numbers working as in a world without debug, and a test that every error a call raises for a mistake of its caller points at the line of the call, in a world with and without debug checks (values on tags and tag pairs, wildcard pairs, pairs with a free slot,ecs.pairwith a nil element, too many ids, queries without terms wherever they are used, change filters of untracked ids at every use and whatever the entity and the changes, monitors, signals of pairs, ranges, pools, traits,expect, an error inside a hook, hooks that keep a delete going).test/cases/workload.luau, debugging aids: a debug world names a nil id given to a query, to a term of a query, togetor tohas, at the line of the call;ecs.pairnames a nil target.
Documentation
- The API reference (
ecs.world,ecs.pair,World) and the guide describe the checks of a debug world, the errors ofecs.pairand of the change filters of untracked ids, and the line that errors point at; the jecs page lists the checks among the features beyond jecs and in the migration. - The comparison pages, the README and the page of the previous release carry the measurements of 1.2.0.
Performance on the reference workload
Both versions are measured with the reference workload model of this release on Luau 0.740,
-O2, in the interpreter and native code. The
full report and
raw samples contain 232
comparison rows from 460 isolated processes: the release run; 15 more repeats of the client
profile in the interpreter, whose two rows it flagged (P4, 15 usually empty marker queries,
1.03× at first and with all repeats; P7, the client frame, 1.05× at first and 1.01× with all
repeats; within the noise); and 15 more repeats of P6 and P7 at the target scale in both modes,
whose columns had split between two levels of time in both versions (with all repeats the frame
of the model takes 0.99× of the time of 1.1.0 in native code). No timing row is slower than the
noise; the memory rows that the report flags are the constant heap of a world and the
resolution of the measurement (see Memory). 1.2.0 changes in the code that the suite runs only
the paths that raise errors, which the suite does not take, and the test of nil of ecs.pair,
and improves no test: the rows smaller beyond the noise (P8 bytes per distinct pair at the small
scale without owned entities, 0.9987×: one step of the resolution) are not claimed as a gain.
The frame model (P7) and the lifecycle events of P6 stay within the noise (µs, medians [min–max]
of each version's two control columns); in the interpreter at the target scale the lifecycle
events take 1.02–1.04× with all repeats, and 10 more processes of each version side by side
give 1.00–1.01×:
| Mode | Scale | P7, µs/frame: 1.1.0 → 1.2.0 | P6, the removal of a retained agent, µs: 1.1.0 → 1.2.0 |
|---|---|---|---|
| native | small | 101.26 [93.07–113.86] → 97.30 [92.27–113.36] | 49.43 [40.45–71.00] → 54.58 [43.75–70.45] |
| native | target | 358.23 [313.90–428.92] → 355.60 [326.02–518.40] | 1051.8 [971.4–1205.2] → 1034.6 [955.4–1566.1] |
| native | small-empty-retained | 104.37 [91.59–142.23] → 97.09 [92.08–121.39] | 19.50 [13.95–23.70] → 19.05 [15.55–26.45] |
| native | target-empty-retained | 321.44 [311.49–388.56] → 325.70 [305.53–412.91] | 21.7 [18.2–30.0] → 21.4 [18.7–38.8] |
| interpreter | small | 154.41 [147.00–180.29] → 158.73 [147.39–173.52] | 71.95 [61.95–101.85] → 76.72 [64.40–97.10] |
| interpreter | target | 491.59 [464.84–830.87] → 510.14 [465.45–656.87] | 1503.1 [1446.0–2165.8] → 1566.2 [1444.1–1997.1] |
| interpreter | small-empty-retained | 160.07 [151.65–215.78] → 156.85 [149.44–174.69] | 27.10 [19.20–34.45] → 23.78 [19.10–39.70] |
| interpreter | target-empty-retained | 506.51 [473.74–546.77] → 490.06 [468.67–537.55] | 32.1 [29.4–49.7] → 30.0 [28.4–38.9] |
Single operations (1.2.0 and 1.1.0,
measured with the comparison with jecs) have a median ratio of 1.00× in both modes over 99 rows.
ecs.pair pays its test of nil in the interpreter: pair(R, T) takes 22.7 instead of 20.8 ns
(1.09×); in native code its 9.67 against 8.73 ns lie within the range of the row (8.41–11.3 ns),
and the two modules side by side (8 processes each) take 12.7 ns per call each, loop included.
The other rows that move beyond a few percent move both ways within their ranges (in the
interpreter a usually empty query with 20 swaps per pass, 1.30×, and
query(A, pair(ChildOf, parent)) per parent, 1.11×). The matrix and the synthetic frame were
measured fifteen times in each mode: in the first five the median frame of a library varied from
process to process by 10–77 %, and 38 of the 214 rows of the matrix that compare the two
releases moved by more than 5 % with the next ten. The
complete measurements
also compare this campaign with that of 1.1.0, on the same machine: the same code took 0.86–1.00
of its time there.
Memory
A new world takes 589 bytes more: 56 586 instead of 55 997 bytes (200 worlds kept alive): the closures of the world that raise errors for the mistakes of their callers keep the function that raises them as an upvalue, and the closure that takes the ticks of the change filters keeps the function that checks their ids (30 of the 589 bytes). The table of the world keeps its fields, and there is no new per-entity, per-pair or per-query field: the heap of the target world (P8) is 137.63 MB after it is built and 138.57 MB after 100 lifecycle rounds in both versions, a distinct pair with its holder takes 1 527.8 bytes and a holder of a pair 37.1 bytes in both. The rows of P8 measure the heap in whole KiB, rounded down before and after, so this constant moves the heap rows by 0, 1 or 2 KiB, and the bytes per distinct pair move by steps of 1 KiB over the pairs of a scale. Three rows are flagged: two heap rows at +2 KiB (interpreter: the client after 9 000 frames, the target scale without owned entities after 3 000 frames) and the bytes per distinct pair of the small scale in the interpreter (+1.72 bytes, one step over its 594 pairs; the small scale without owned entities moved one step down in both modes). To the byte, a world of the client profile takes 560 bytes more after it is built and after 3 000 frames, and 592 after 6 000 and after 9 000 frames: nothing accumulates. A debug world takes 60 216 bytes instead of 56 474 (the checks of its methods).
v1.1.0 — 2026-10-13
Changed behavior
None: what the calls of 1.0.1 return, in which order, what a loop sees and which errors are raised stay those of 1.0.1. The release adds a method.
Added
-
world:expect(entity, id): the value of an id that the entity must have (a component set when the entity is created and never removed). It reads likeworld:getof one id; its value is typed withoutnil(<T>(self: World, entity: Id<any>, id: Id<T>) -> T), and instead ofnilit raises an error that names the entity and the id by theirName, else by their number, and says what is missing:entity "Goblin" (#4194561) has no Health;entity "Goblin" (#4194561) has Health without a value: a component added without a value (world:add), or set tonil;entity "Goblin" (#4194561): Frozen is a tag, it has no value, also for a pair whose relation and target are tags;entity "Goblin" (#4194561) has no #300 (the id is not alive);entity #4194561 is not alive: an outdated handle or a deleted entity (expect Health).
The error points at the line that called
expect, in a world with or without debug checks. A wildcard pair reads as inget: the value of the pair with the lowest target slot for(R, *), with the lowest relation slot for(*, T). A read takes 26.6 ns in native code, wheregetof one id takes 32.7 ns (it takes up to 8 ids) and a method overgetwritten in Luau that checks fornil46.2 ns; 54.2 ns in the interpreter (get53.6 ns, the method 67.3 ns): one read per call over 700 entities, the median of 6 processes, Luau 0.740-O2. The message is built only for the error. The method is a field of the world: it takes no register of the function that builds a world.
Tests and tools
test/lib.luau:world:expectin a world with and without debug checks: the value of a component (falsetoo), of a data pair and of both wildcards, and each error with its text and the line it points at.test/types.luau: the value ofworld:expectis typed withoutnil, also for a data pair;test/typecheck/errors.luau: reading it as another type is rejected.
Documentation
- The API reference and the guide describe
world:expect; the jecs page lists it beyond jecs. - The comparison pages, the README and the page of the previous release carry the measurements of 1.1.0.
Performance on the reference workload
Both versions are measured with the reference workload model of this release on Luau 0.740,
-O2, in the interpreter and native code. The
full report and
raw samples contain 232
comparison rows from 280 isolated processes: no timing regression beyond the measured control
noise; the memory row that the report flags is the constant heap of a world (see Memory). 1.1.0
changes no path that the suite measures and improves no test: the two rows faster beyond the
noise (native code, target scale, retained agents without owned entities: P2 with one stored
query per system tag 0.93×, P5 messages on average 0.89×) run code that this release does not
change. The frame model (P7) and the lifecycle events of P6 stay within the noise (µs, medians
[min–max] of each version's two control columns):
| Mode | Scale | P7, µs/frame: 1.0.1 → 1.1.0 | P6, the removal of a retained agent, µs: 1.0.1 → 1.1.0 |
|---|---|---|---|
| native | small | 108.88 [101.65–125.30] → 105.90 [99.28–122.02] | 57.60 [50.15–75.45] → 53.95 [51.50–68.75] |
| native | target | 366.83 [349.42–466.06] → 359.42 [345.75–408.82] | 1108.9 [1055.0–1188.1] → 1095.4 [1069.3–1190.4] |
| native | small-empty-retained | 104.30 [102.02–119.51] → 107.23 [103.30–117.07] | 17.52 [14.80–21.00] → 19.10 [14.90–25.20] |
| native | target-empty-retained | 355.92 [333.93–415.20] → 342.58 [324.46–367.51] | 27.2 [24.8–29.4] → 24.6 [22.2–28.6] |
| interpreter | small | 172.42 [162.41–187.42] → 168.66 [159.70–195.57] | 89.55 [74.40–119.70] → 84.15 [72.30–105.65] |
| interpreter | target | 564.54 [520.22–827.88] → 531.89 [503.52–655.72] | 1829.5 [1565.5–2006.5] → 1652.0 [1590.6–2008.9] |
| interpreter | small-empty-retained | 165.47 [159.51–195.98] → 170.18 [156.58–185.36] | 28.48 [23.60–52.30] → 27.12 [22.90–45.05] |
| interpreter | target-empty-retained | 531.90 [486.56–616.10] → 527.34 [495.73–632.36] | 36.0 [33.6–64.9] → 37.4 [33.7–47.0] |
Single operations (1.1.0 and 1.0.1,
measured with the comparison with jecs) have a median ratio of 0.99× in both modes over 113
rows. 1.1.0 does not change their code, and the rows that move beyond a few percent move both
ways: in native code get of one id (0.72×) and target (0.79×) are faster in these runs, 15
cached queries over scattered entities (1.20×) and query(A, pair(ChildOf, parent)) per parent
(1.24×) slower.
Memory
A new world takes 1 131 bytes more: 55 992 instead of 54 861 bytes (200 worlds kept alive), the
closure of world:expect (about 100 bytes) and its field: the table of a world had 32 fields,
and the 33rd doubles its hash part (1 024 bytes). There is no new per-entity, per-pair or
per-query field: the heap of the target world (P8) is 137.63 MB after it is built and 138.57 MB
after 100 lifecycle rounds in both versions, a distinct pair with its holder takes 1 527.8 bytes
and a holder of a pair 37.1 bytes. The heap rows of P8 measure whole worlds in KiB, so this
constant moves them by 1 or 2 KiB; one row is flagged (native, small-empty-retained, the heap
after 6000 more frames: +2 KiB), and nothing accumulates over the lifecycle rounds and the long
sessions.
v1.0.1 — 2026-10-02
Changed behavior
None: what a call returns, in which order, what a loop sees and which errors are raised are those of 1.0.0.
Performance
-
A delete whose entities have removal hooks or listeners costs, in native code, what it cost in 0.2.4 again. 1.0.0 had made it slower with the bookkeeping that keeps nested removals and clears of an entity from notifying an id twice: the cascade over the 500 owned entities of an agent, each with a removal listener, took 261 µs in 0.2.4 and 292 µs in 1.0.0; it takes 262 µs now (the median of 8 processes per version, 121 deletes in each). The bookkeeping and the behavior of nested removals stay those of 1.0.0; the way a delete reaches them changed:
- an entity with one hooked id, whose removal no running hook concerns, has its hook run without the loops of the general case;
- the words of the signatures that have hooked ids are counted, and the loops over them stop at the count: a read past the end of a list takes the slow path of a table read in native code;
- after the removal hooks of a deleted entity, the flag that tells whether the entity is used as an id is read again only when a hook marked an entity used meanwhile;
- a clear reads the signature words beyond the shared tables only in a world that has such words (more than 256 ids), and a delete reads the changes recorded for its slot only in a world that tracks an id;
- the signal dispatcher of an id without a hook keeps
falseas its hook, so that a dispatch reads a field that is there.
In the interpreter part of the cost of 1.0.0 stays, the most where the deleted entities have several hooked ids: the same cascade takes 437 µs in 0.2.4, 463 µs in 1.0.0 and 442 µs in 1.0.1 with one hooked id per entity, and 529, 574 and 558 µs with three (native code: 335, 375 and 337 µs).
-
Adds, sets and clears read only the fields that a record has: a component or a tag has its
on_addhook (falsewithout one) and its value pages (falsefor a tag), a pair without values itson_add, and an add of a pair without a value does not read its pages. A missing field of a table takes the slow path of a table read in native code; the records keep the size they had (16 fields at most for a pair).
Tests and tools
- P6 has a case of its own: the cascade of the removal of an agent, in a world of its own (500
owned entities at the target scale, 15 at the small one, a removal listener on the state value
of each and on two ids of the agent), where the rest of the event does not dilute its cost.
tools/workload.pyexpects its row. test/lib.luau: a word of the shared signature tables whose last hooked id loses its hook (deletes and clears after that, and a hook set again);set_allof a value on a tag raises the error of a value on a tag.- The Python bytecode of
tools/(__pycache__/) is no longer in the repository and is ignored: every run of the tools rewrote it.
Internals
- The helpers of
world_newthat use no state of a world (the presence bits and change journals of a record, value pages, the pairs of a slot, the loops over match lists and the query objects) are defined before it. A Luau function has at most 200 registers;world_newhad used them all, and 22 are free now.
Performance on the reference workload
Both versions are measured with the reference workload model of this release on Luau 0.740,
-O2, in the interpreter and native code. The
full report and
raw samples contain 232
comparison rows from 280 isolated processes: 4 improvements beyond the measured control noise and
no timing regression beyond it; the memory row that the report flags is the constant heap of a
world (see Memory).
The improvements are rows of the new P6 case, the cascade of the removal of an agent alone: at the target scale in both modes and in native code in the small-empty-retained profile; its other rows are faster within the noise (µs per event, pooled medians [min–max] of each version's two control columns):
| Mode | Scale | 1.0.0 → 1.0.1 |
|---|---|---|
| native | target | 294.8 [287.6–316.9] → 260.0 [249.0–261.6] |
| native | target-empty-retained | 297.8 [292.2–399.4] → 255.7 [252.8–268.9] |
| native | small | 11.05 [10.70–11.40] → 10.00 [9.30–12.00] |
| native | small-empty-retained | 11.00 [10.70–11.30] → 9.80 [9.40–10.30] |
| interpreter | target | 467.2 [457.4–507.5] → 441.0 [424.9–566.6] |
| interpreter | target-empty-retained | 462.2 [444.0–469.7] → 439.6 [415.9–448.0] |
| interpreter | small | 17.45 [16.40–18.70] → 16.60 [15.90–29.70] |
| interpreter | small-empty-retained | 17.25 [16.60–20.00] → 16.65 [16.00–17.40] |
The other rows stay within the noise, the frame model (P7) and the lifecycle events of P6 included:
| Mode | Scale | P7, µs/frame: 1.0.0 → 1.0.1 | P6, the removal of a retained agent, µs: 1.0.0 → 1.0.1 |
|---|---|---|---|
| native | small | 97.78 [94.07–106.50] → 95.45 [92.48–97.42] | 51.63 [42.40–69.00] → 44.10 [40.05–50.95] |
| native | target | 336.23 [321.08–450.26] → 332.83 [324.37–377.05] | 1039.9 [1010.7–1274.0] → 1026.4 [982.9–1123.0] |
| native | small-empty-retained | 98.36 [93.63–105.78] → 95.44 [92.60–106.73] | 15.45 [13.10–20.90] → 13.65 [12.90–21.65] |
| native | target-empty-retained | 327.58 [315.20–404.65] → 313.93 [306.59–340.39] | 22.7 [18.2–31.3] → 23.3 [17.6–27.7] |
| interpreter | small | 149.31 [145.53–180.86] → 151.80 [147.78–163.85] | 72.05 [65.80–85.50] → 70.72 [65.80–83.10] |
| interpreter | target | 480.73 [473.96–515.11] → 483.99 [472.49–530.27] | 1612.4 [1553.8–1790.8] → 1596.0 [1554.0–1976.2] |
| interpreter | small-empty-retained | 148.78 [145.93–161.07] → 148.29 [144.98–156.25] | 20.63 [19.75–29.15] → 22.23 [20.40–29.75] |
| interpreter | target-empty-retained | 469.91 [463.22–508.19] → 465.49 [459.35–482.31] | 28.3 [25.9–33.9] → 28.2 [26.2–36.8] |
Single operations (1.0.1 and 1.0.0,
measured with the comparison with jecs) mostly stay within a few percent of 1.0.0, both ways.
Deletes and removals are faster in native code: a member of a monitored query 0.92× / 0.85×, a
ChildOf cascade 1.02× / 0.89× per child, a tag removed 0.98× / 0.92× (interpreter / native);
the cost of an OnRemove hook on a delete is 190 / 103 ns instead of 205 / 127 ns. The
interpreter rows of the eight kinds created in turn vary between the processes of one version
(1.19× in the campaign, 1.02× with 24 more processes of each).
Memory
A new world takes 318 bytes more: 54 856 instead of 54 538 bytes (200 worlds kept alive), the two counters that the deletes read and the closures that capture them. There is no new per-entity, per-pair or per-query field: a record keeps its size, and the bytes per distinct pair and per holder of P8 are unchanged. The heap rows of P8 measure whole worlds in KiB, so this constant moves them by 0 to 2 KiB; one row is flagged (native, target, the heap of the world after it is built: +2 KiB), and nothing accumulates over the lifecycle rounds and the long sessions.
v1.0.0 — 2026-10-01
Changed behavior
- A query whose terms select no entity — excluded ids alone, as
world:query():without(A)— raises an error when it is used: a loop,each,count,has,cached, a monitor or a batch operation. In 0.2.4 it matched nothing. A query selects through a returned or required id, an OR term (any) or a change filter; a query object that is not used is not an error. - A removal that the hooks of the same removal start again — the same id removed from the same
entity, also by a delete or a clear of the entity — does nothing: the running removal
completes it. In 0.2.4 the
OnRemovehook ran again, so a relation kept in sync by its hooks (each side removing the pair of the other) recursed until the stack overflowed when either side removed, replaced (an exclusive relation) or was deleted, and a removal hook that deleted its entity ran twice, the second time withdeletingtrue. Now each runs once. - The
Componenttrait is given to an id before its first use: added to an id used already (as an id, a relation or a target), or removed from a used one byworld:removeorworld:clear, it raises an error and changes nothing. In 0.2.4 the add succeeded andworld:has(id, ecs.Component)was true, but the id stayed a tag (world:setraised the error that told to add the trait); a removal left the values of a component whose trait was gone. A used component is deleted as before. - A clear or a delete runs the
OnRemovehooks (and the removal listeners) once per id of the entity: not again for an id that a later hook removes, which 0.2.4 notified a second time (that removal now does nothing: the clear removes the id). An id that these hooks give the entity still goes with the others, without its hooks, as in 0.2.4. world:tick()drops what an error raised by a hook or a listener left in the world — a removal, a clear or a cascade that did not finish, the target being cleaned up, the pair an exclusive relation was replacing — and deletes the entities that the stopped cascade had queued; a debug world reports it. In 0.2.4 such an error left the world unable, for the rest of its life, to run the hooks of that entity in a clear or a delete, to finish cascades deeper than 100 levels, and to keep the(*, T)query of the target up to date. Callworld:tick()between frames, outside hooks, listeners and loops.world:range(first, last): the new ids stay inside the range also afterworld:entity(id)made an id outside it alive. In 0.2.4 the slot of a deleted id below the range went to the next new entity, and an id above the range made the next new ids come from the slots skipped below it (4999afterworld:entity(5000)inrange(1000, 2000), not1001).- After
world:entity(id)above the highest slot, new ids take the skipped slots in ascending order (0.2.4: from the highest down). world:entity(id)of an older generation of a slot than its newest one: after that id is deleted, the next entity of the slot takes the generation after the newest one, also when the slot left the range of the world and came back. In 0.2.4 it took the generation afterid, so the ids of the newer generations came alive again (their old handles were valid, and their listeners and hooks ran for the new entity).Exclusivegiven to a relation that an entity has with several targets already raises an error and is not added. In 0.2.4 it was added and the entity kept its targets.
New
world:toggle(entity, id)adds an id that the entity does not have and removes one that it has, with the hooks, signals, monitors and change tracking ofaddandremove, and returns true when it added the id.query:toggle_all(id)does it for every match: 32 entities at a time for a component or tag without hooks, entity by entity otherwise.- Creation tracking:
world:track_created()records the entities made from then on (world:entity, a slot pool,world:entity(id)making an id alive), and the change filterquery:created()returns those made since the previous iteration of the query, with the ticks of the other change filters. A world that does not track creations pays a test per new entity.
Fixes
world:eachandworld:childrenover a sparse id of a small world whose members move between words: the sorted keys of the record are used only while its emptied words are no more than the non-empty ones, otherwise the levels of the bitset. 4 members among 1 500 entities after 40 moves: 0.585 → 0.447 µs per loop in native code (23.6 % less), 0.826 → 0.663 µs in the interpreter (19.7 % less).- Types:
ECS_ID,ECS_GENERATION,ECS_PAIR_FIRSTandECS_PAIR_SECONDtake an id of any data type, also straight from a call:ecs.ECS_ID(world:entity())was reported as an error. - An exclusive relation whose removal hook adds another target while a target is replaced: the
outer add wins (a
setwith its value, also when the hook set the same pair), the other target is added and replaced in turn (with its hooks), and the entity keeps one target. In 0.2.4 the hooks recursed until the stack overflowed. - Deleting an id: the entities that its removal hooks give it while it is cleaned up are cleaned
up too (they lose it, or are deleted under a delete policy). In 0.2.4 they kept the dead id,
and
world:idsof such an entity raised an error. - Deleting an entity that its own removal hooks use as an id for the first time: that use is cleaned up. In 0.2.4 the other entity kept the dead id, and a query of it returned that entity.
- Deleting an entity: the uses that hooks make while its cascade runs — the entity used as an id
for the first time, a pair with it as the relation or the target — are cleaned up as well. In
0.2.4 they stayed, with a dead id (
world:idsof the other entity listed it). - Monitors: an entity enters when a listener adds a term of the query while
Disabledor an excluded id is being removed from it. In 0.2.4 the monitor missed that entry. - Change tracking: an entity deleted by a listener of the change no longer passes the change to
the new entity in its slot. In 0.2.4, when the id was tracked after the listener was
connected,
added,changedorremovedreturned the new entity. - Monitors: an excluded id that a listener of its add removes again leaves the monitor as it was. In 0.2.4 the monitor reported an exit while the entity still matched, and then missed its real exit.
world:rangebounds the pools made before it: they take new blocks inside the range, and their slots outside it are not given again. In 0.2.4 such a pool went on giving the slots of its block.world:add,world:setandworld:toggleof an id that is not alive do nothing in a world without debug, as the guide says. In 0.2.4 the entity got the deleted id:world:hasand the queries of the id returned it.- A loop over a query with change filters (
added,changed,removed,created) returns every change also when the query cannot gather its matches first: a driving record of more than 64 words (more than 2 048 entities) or more terms. In 0.2.4 such a loop returned nothing, whilecount,eachand a cached query returned the changes. add_all,set_allandtoggle_allstop when a hook deletes their id (or the relation or the target of their pair): the rest of the matches do not get it. In 0.2.4 they went on and gave the rest the deleted id (world:hasand the queries of the id returned them), andset_allof a deleted component raised an error.world:entity(id)over a live entity whose removal hooks make a new entity in the freed slot: that entity is deleted too, before the slot goes toid. In 0.2.4idtook the slot with the values of that entity, which stayed on its holders as a dead id.- Deleting an id (or the target of a pair): a holder that the cleanup has passed reads no
value of the id, and a hook that sets the id on it again adds it (
added, thenremovedwhen the cleanup removes it again). In 0.2.4 the old value stayed readable, and the set changed it in place (changed) without giving the id back. - Deleting an id whose removal hook deletes it and makes a new entity in its slot: the cleanup stops at the old id, and the pairs of the new entity (as the relation or the target) and their holders stay. In 0.2.4 the cleanup went on with the records of the new entity: it removed its pairs and, under a delete policy, deleted their holders.
- An id that lives again (
world:entity(id), or the same id when the 16-bit generations of its slot have gone round) has none of the hooks of its old components, also when it has signal listeners: the hooks go when the id is deleted. In 0.2.4 the deletedOnAdd,OnChangeorOnRemovehook of the id ran again. - Monitors: an entity that a listener deletes while a term of the query is being removed, and a new entity that takes its slot at once, leave and enter: the monitor reports the exit of the old entity (when its slot is freed) and the entry of the new one. It took the new entity for the member that left, missed its entry and then dropped it.
Tests and tools
- The behavior specification:
test/behavior.luauruns the cases oftest/cases/, one module per subject (changes,queries,loops,hooks,relations,tracking,batches,worlds,workload), 339 cases. Named groups run alone, and a module path runs the same cases on a saved release, which shows the changed behavior between two releases.test/edge_cases.luauandtest/workload_cases.luauare groups of it now. - New cases: the terms of a query on five entities through every way of reading it;
world:eachandworld:childrenreturn disabled members (Disabledhides an entity from queries only); what one tick of change tracking records, batch operations on tracked ids and the depth of the history; relations kept in sync by their own hooks (one to one, two relations, one to many, many to many); batch operations whose matches cascade or leave the query; two worlds in one process;world:entity(id)over a live slot; an old id of a slot that a new entity took;world:rangewith ids of another world; listeners disconnected after the list changed; disconnected listeners and monitors that nothing keeps; several excluded ids; listeners that give a changing relation or a deleted id new uses, that delete the entity of their own event (a removal, a tracked change) or take back an excluded id (a monitor); theComponenttrait after the first use of an id; a pool made beforeworld:range; whatworld:tick()restores after an error raised by a hook; clears and deletes that notify every id once; monitors and the changes made while an id is removed; uses that hooks make during a cascade; batch operations whose hooks delete their id;world:entity(id)whose delete makes a new entity in the slot; holders of a deleted id that its hooks read or set; ids made alive again, also an older generation of a slot and an id whose slot went round its generations; monitors and the cleanups of ids whose slot a listener gives to a new entity; what hooks and listeners see (the new value in an OnChange hook, the additions of an id used before as a tag and a relation), deletes of relations and targets (a relation in the slot of a deleted one, cascades in any order of creation, the other components of a survivor, re-parenting to an entity in the slot of a deleted parent), explicit ids and new entities, values after a component is set, removed and set again. test/reentrant_fuzz.luaumakes hooks, listeners and monitor callbacks change the world while it changes (also batch operations with ids and pairs that the callbacks delete, explicit ids over live entities, deleted ids made alive again, new entities in a slot freed a moment before, components used as ids), and checks the world against itself after every operation: every addition and removal heard once (but for the ids that hooks give an entity during its own clear or delete), no dead id on a live entity, one target of an exclusive relation, queries,world:each, counts and monitors in agreement, change filters returning only changes of the tick. It found the faults of 0.2.4 fixed above; CI runs three seeds.test/behavior.luau -a debugruns every case with debug worlds (tools/test.shruns the specification both ways).test/typecheck/errors.luauholds 21 misuses of the public types, each marked with the error it must get;tools/typecheck.py(run bytools/check.sh) requires exactly these errors.test/types.luauadds optional and union components, a typed wrapper, a pair of a tag relation, mixed lists of ids, toggles and creation tracking. The Python tests aretools/test_*.py.- The model of the reference workload follows it more closely: the states out of idle hold a few members each (the busiest one, a passing one that the intersection walks go over, four more), the messages come at their averages, P5 adds a burst of activity and P2 a stress case of 80 members; P1 adds a small world (4 members among 1 500 entities, moved 40 and 3 000 times).
tools/check.shandtools/workload.shrunpythonwherepython3does not run.bench/basic.luauruns the four basic benchmarks of jecs (spawn, despawn, insertion, query) for mErCS, jecs and ecr in the CLI; ecr 0.9.0 is a Wally dev dependency, and the Benchmarker files of the same four benchmarks (bench/visual/) time ecr as well.tools/workload.pytakes a difference of exactly one step of the heap resolution as noise (the rounding of a float subtraction made it a change).
Documentation
- The documentation site has a Comparison section next to the docs, the API and the changelog: the Benchmarker screenshots (captured again with 1.0.0, and with ecr in the four basic benchmarks), 1.0.0 against 0.2.4 (the reference workload and the matrix of single operations), and the pages of jecs and ecr. The comparison with jecs was measured again on 1.0.0 (the measurements); the page of ecr is new: the design, the differences, the four basic benchmarks and the migration from ecr.
- The comparison with jecs no longer says that jecs has at most 256 components:
world:component()gives the first 256 ids, and jecs makes further components withworld:entity()and theComponenttrait. - The guide describes the
Componenttrait, the nested changes from hooks (clears and deletes that notify every id once, exclusive relations, monitors, batch operations whose hooks delete their id,Exclusivegiven late) and whatworld:tick()restores after an error raised by a hook; a pair with a free slot raises an error in any world;world:entity(id): an id made alive again starts without its old components and hooks, and the generations of its slot (16 bits) keep going after the newest one.
Performance on the reference workload
Both versions are measured with the reference workload model of this release on Luau 0.740,
-O2, in the interpreter and native code. The
full report and
raw samples contain 224
comparison rows from 320 isolated processes: 2 improvements beyond the measured control noise and
no timing regression beyond it; the memory rows that the report flags are the constant heap of a
world (see Memory). Each build and its control have five repeats per profile and mode; the target
profile in native code has ten additional repeats (a row that the first run flagged, within the
noise with all its samples). All samples remain in the combined report, with the same
baseline-only noise rule.
The table gives pooled medians [min–max] for each version's two control columns. Full-frame time (P7, the client profile included) and frame heap growth (P9) stay within the noise at both scales, and so do the lifecycle events (P6), which run the reworked removal hooks:
| Mode | Scale | P7, µs/frame: 0.2.4 → 1.0.0 | P9, bytes/frame: 0.2.4 → 1.0.0 |
|---|---|---|---|
| native | small | 102.11 [98.35–116.80] → 99.88 [95.28–109.30] | 4266.7 [4078.9–4403.2] → 4266.7 [4061.9–4386.1] |
| native | target | 354.48 [319.45–527.89] → 349.23 [320.94–622.74] | 7321.6 [5990.4–7714.1] → 7321.6 [6007.5–7731.2] |
| native | small-empty-retained | 100.09 [93.38–115.22] → 98.29 [94.48–107.09] | 4437.3 [4266.7–4522.7] → 4437.3 [4249.6–4522.7] |
| native | target-empty-retained | 325.38 [312.98–385.92] → 320.19 [309.75–379.06] | 6126.9 [5751.5–6963.2] → 6126.9 [5734.4–6963.2] |
| interpreter | small | 153.51 [148.23–161.19] → 153.57 [149.46–161.11] | 4266.7 [4078.9–4386.1] → 4266.7 [4078.9–4386.1] |
| interpreter | target | 490.63 [466.34–502.69] → 481.62 [468.92–556.86] | 7321.6 [6502.4–7714.1] → 7321.6 [6502.4–7714.1] |
| interpreter | small-empty-retained | 154.46 [151.01–158.54] → 155.82 [150.42–185.22] | 4437.3 [4266.7–4522.7] → 4437.3 [4249.6–4522.7] |
| interpreter | target-empty-retained | 485.27 [473.61–506.39] → 490.41 [474.40–506.29] | 6126.9 [5751.5–6963.2] → 6126.9 [5734.4–6963.2] |
| Mode | P6 target, µs per event: 0.2.4 → 1.0.0 | |
|---|---|---|
| native | a new agent with its owned entities | 1010.8 [952.9–1384.9] → 1010.3 [941.9–1438.0] |
| native | the end of the activity of an agent | 56.8 [52.3–75.0] → 54.0 [49.8–82.7] |
| native | the removal of a retained agent (cascade) | 1127.5 [1055.8–1483.8] → 1089.8 [1029.8–1545.9] |
| interpreter | a new agent with its owned entities | 1550.2 [1529.6–1570.0] → 1558.0 [1522.4–1613.7] |
| interpreter | the end of the activity of an agent | 85.9 [81.7–93.1] → 85.0 [79.9–89.4] |
| interpreter | the removal of a retained agent (cascade) | 1553.0 [1511.2–1610.0] → 1530.2 [1478.1–1623.1] |
The small world of P1 (4 members among 1 500 entities, after 40 transitions) improves from 0.585
to 0.447 µs per loop in native code (23.6 %) and from 0.826 to 0.663 µs in the interpreter
(19.7 %), the fix of world:each above. Other timing changes remain within the noise; the report
includes the dense loops, the stress cases and both retained-agent variants.
Single operations (1.0.0 and 0.2.4,
measured with the comparison with jecs) mostly stay within a few percent of 0.2.4. Deletes cost
more where the fixes of nested hooks and of monitors added work (interpreter / native): an entity
with four components 1.05× / 1.06×, a ChildOf cascade 1.05× / 1.11× per child, an entity with
an OnRemove hook 1.12× / 1.19×, a member of a monitored query 1.21× / 1.33×, a child moved
under a monitor 1.12× / 1.06×. The lifecycle events of the workload (P6), which delete hundreds
of entities with listeners, stay within the noise.
Memory
A new world takes 2 529 bytes more: 54 533 instead of 52 004 bytes (200 worlds kept alive), the closures and small tables of the new features and fixes (toggles, creation tracking, the bookkeeping of removal hooks and monitors, the floors of generations). There is no new per-entity, per-pair or per-query field. The heap rows of P8 measure whole worlds at a resolution of 1 KiB, so this constant shows in them as +2 or +3 KiB, and in the bytes per distinct pair of the small scale (+1.7 bytes: the heap divided by the pairs of a small world); the bytes per holder are unchanged, and nothing accumulates over the lifecycle rounds and the long sessions.
Target-world P8 medians [min–max] (MiB means 1024² bytes; pair and holder costs are incremental benchmark measurements):
| Mode | P8 target | 0.2.4 → 1.0.0 |
|---|---|---|
| native | the heap of the world after it is built | 137.64 [137.62–145.61] → 137.64 [137.62–145.61] |
| native | the heap after 100 lifecycle rounds | 138.58 [138.56–146.58] → 138.58 [138.56–146.58] |
| native | bytes per distinct pair (and its holder) | 1528.320 [1526.272–1529.344] → 1527.808 [1526.272–1528.832] |
| native | bytes per holder of a pair | 37.139 [35.090–37.395] → 37.139 [35.090–37.395] |
| interpreter | the heap of the world after it is built | 137.63 [137.62–145.61] → 137.63 [137.62–145.61] |
| interpreter | the heap after 100 lifecycle rounds | 138.56 [138.56–146.55] → 138.57 [138.56–146.55] |
| interpreter | bytes per distinct pair (and its holder) | 1528.320 [1527.808–1529.344] → 1528.320 [1527.808–1528.832] |
| interpreter | bytes per holder of a pair | 37.139 [37.139–37.395] → 37.139 [36.882–37.395] |
v0.2.4 — 2026-09-30
Changed behavior
- Deleting a pair's target or relation no longer calls
OnRemovea second time for a holder whose pair an earlier callback removed, or for a holder that callback deleted. In 0.2.3 the cleanup snapshot dispatched again before checking whether the membership still existed. - A removal listener that disconnects the last listener and connects a replacement during target/relation cleanup now gives subsequent holders' events to the replacement. 0.2.3 kept the old dispatcher for the whole cleanup and missed these events. The listener list of the event already in progress still stays fixed.
Iteration
- The module's
each/childrenpool retains at most 16 buffers and 262 144 charged array slots (4 MiB of array values, plus table overhead). A buffer's charge follows its largest snapshot, rounded up to include the terminating slot; reusing it for a smaller snapshot cannot hide its retained storage. Oversized or excess buffers, and abandoned loops, are left to GC. Live snapshots are not capped; a loop whose buffer exceeds the pool budget allocates that buffer again on its next run. The reference dense case has 100 000 members and fits the budget. - Pool bookkeeping moved out of each iterator closure. Reusing a buffer now needs about 152 bytes per iterator instead of 176. No fields were added per entity, pair or query.
- Records with at most 64 word keys, including emptied words, can use sorted non-empty keys to collect a snapshot. Previously any emptied word forced the bitset hierarchy walk.
Tests and measurements
- 27 boundary and reentrant-operation cases cover full-generation snapshots, word/page boundaries, more than 16 held iterators across worlds, messages changed by hooks, overlapping cascades, nested batches, signal replacement and query arities 0/1/3/8/9 with nil/false values. Three cases fail on 0.2.3 and pass with the two cleanup fixes.
- An independent snapshot model holds
each/childreniterators across mutations, cascades and slot reuse. CI runs three seeds for 2 000 rounds in both modes. The test runner now counts the actual shared-query warning, and the workload runner has eight validation tests. - Reference measurements load each build and control in a fresh process from a verified tag or candidate snapshot. Reports preserve raw samples, seeds, source/tool hashes, medians and ranges; incomplete release runs fail. The type-check script now preserves analyzer failures even when no diagnostic text is printed.
- The suite adds a client profile, retained agents without owned entities, sparse records after an emptied word, longer memory checkpoints and buffers retained after world GC. P1 uses the exact advertised member counts. Expiry refreshes keep at most three pairs per group; the former model added new targets every frame and grew beyond the reference workload. A regression test checks this bound during lifecycle churn.
- P9 reports net heap growth with a weak GC witness, including a warmed frame and the first large snapshot. This is an allocation proxy: it does not count all allocator traffic or rule out an incomplete incremental collection.
Performance on the reference workload
Both versions are measured with the corrected suite on Luau 0.740, -O2, in the interpreter
and native code. Historical 0.2.3 figures below used a different model and are not the baseline
for this comparison. The full report
and raw samples contain
194 comparison rows from 440 isolated processes: 20 improvements beyond the measured control
noise and no regressions beyond it. Each build and its control have five repeats per profile
and mode; P1 and the two small interpreter profiles have ten additional repeats. All initial
flags and samples remain in the combined report, with the same baseline-only noise rule.
The table gives pooled medians [min–max] for each version's two control columns. Full-frame time (P7), including the client profile, stays within noise. Frame heap growth (P9) falls by 9.2% / 9.4% at the small scale (native / interpreter) and 8.6% at the target scale; the empty-retained variants improve by 8.9–9.2%. These are heap-growth proxies, not counters of total allocator traffic.
| Mode | Scale | P7, µs/frame: 0.2.3 → 0.2.4 | P9, bytes/frame: 0.2.3 → 0.2.4 |
|---|---|---|---|
| native | small | 149.45 [123.72–161.60] → 152.18 [125.03–156.72] | 7048.5 [6946.1–7185.1] → 6400.0 [6280.5–6519.5] |
| native | target | 710.09 [642.27–763.08] → 721.77 [680.12–792.42] | 11315.2 [11025.1–11758.9] → 10342.4 [10035.2–10769.1] |
| native | small-empty-retained | 151.32 [139.13–157.79] → 148.82 [139.55–161.03] | 7270.4 [7185.1–7475.2] → 6604.8 [6519.5–6809.6] |
| native | target-empty-retained | 658.02 [600.08–699.29] → 670.73 [555.99–790.87] | 11144.5 [10820.3–11332.3] → 10154.7 [9830.4–10359.5] |
| interpreter | small | 208.18 [193.50–281.97] → 204.93 [191.45–267.45] | 7099.7 [6946.1–7287.5] → 6434.1 [6280.5–6621.9] |
| interpreter | target | 932.97 [881.16–966.59] → 934.41 [877.55–1044.82] | 11315.2 [11025.1–11758.9] → 10342.4 [10035.2–10769.1] |
| interpreter | small-empty-retained | 210.24 [195.06–263.97] → 210.03 [196.40–322.20] | 7287.5 [7185.1–7475.2] → 6638.9 [6519.5–6809.6] |
| interpreter | target-empty-retained | 928.02 [820.41–1154.70] → 902.27 [860.63–1019.31] | 11144.5 [10820.3–11332.3] → 10154.7 [9830.4–10359.5] |
P1 with 16 members after an emptied word improves from 1.628 to 1.361 µs in native code
(16.4%) and from 2.379 to 1.899 µs in the interpreter (20.2%). Reused world:each iterators
need about 24 fewer bytes at both server scales. Other timing changes remain within noise;
the report includes dense loops, lifecycle events and both retained-agent variants.
Memory
After 17 concurrent snapshots of 100 000 members are exhausted and their world is collected, the module retains approximately 4.00 MiB instead of 32.00 MiB (87.5% less). The first snapshot still needs its array; the budget applies to returned buffers. There is no new per-entity, per-pair or per-query field. Long-session diagnostics also count live entities and allocated slots so population changes are visible alongside heap measurements.
Target-world P8 medians [min–max] are unchanged to the precision below in both versions. MiB means 1024² bytes; pair/holder costs are incremental benchmark measurements. The 100-lifecycle checkpoint follows the preceding benchmark phases and 100 additional rounds.
| Target metric | Native, both versions | Interpreter, both versions |
|---|---|---|
| Heap after build, MiB | 137.86 [137.84–145.82] | 137.86 [137.84–145.82] |
| Heap after 100 lifecycle rounds, MiB | 138.57 [138.48–146.49] | 138.57 [138.48–146.49] |
| Heap after 3 000 more frames, MiB | 139.47 [139.42–147.41] | 139.47 [139.42–147.41] |
| Heap after 6 000 more frames, MiB | 140.16 [140.09–148.10] | 140.16 [140.09–148.10] |
| Heap after 9 000 more frames, MiB | 140.62 [140.54–148.57] | 140.62 [140.54–148.57] |
| Bytes per distinct pair with one holder | 1528.83 [1526.78–1530.88] | 1528.83 [1526.78–1530.37] |
| Bytes per additional holder | 168.53 [168.02–176.47] | 168.53 [168.02–176.47] |
A separate 60 000-frame diagnostic (target/native, seed 1001, one run per build) has matching live-entity counts and heap checkpoints within 1 KiB. Allocated slots stop growing after 10 000 frames at 354 819; the heap fluctuates between 147.12 and 149.50 MiB after warm-up and returns to 147.68 MiB at frame 60 000. Thus the early rise through the P8 checkpoints does not continue monotonically over this session. The full report includes every checkpoint and distinguishes this diagnostic from the repeated suite. No new retained-memory growth was observed in the candidate over this interval.
Validation covers the full CLI test suite in both modes, extended fuzz runs, formatting, linting, type analysis and the Rojo/Wally/documentation builds. A fresh full Roblox Studio run remains pending; no new Studio timing claim is made for this release.
v0.2.3 — 2026-09-29
The reference workload is the priority from this release on: a
performance suite models it (the tests P1–P9 of bench/workload.luau), and the behavior it
relies on is a set of tests (test/workload_cases.luau). world:each and world:children
return the members of the id at the start of the loop again, and faster than 0.2.2 did: a
frame of the model at the target scale takes 10 % less in native code and 12 % less in the
interpreter, and allocates 60 % less. Also: the listeners of deleted ids, and what signals
and monitors cost once they are gone.
Changed behavior
world:eachandworld:childrenreturn the members of the id when the loop starts, for every id. 0.2.2 walked the bitsets of an id whose members lay in more than two words (beyond 64 slots): it skipped an entity that lost the id or was deleted before the loop reached it, and visited an entity that got the id during the loop when its slot lay ahead of the loop in a word with members (not in a word, or a block of 1024 slots, without members). Now an entity that gets the id during the loop is not visited, one that loses it is visited, and one deleted before the loop reaches it comes as a dead id.- A listener of a deleted id (a signal, change tracking, a query monitor with the id as a term) hears nothing until the id is made alive again; 0.2.2 ran it for the pairs of the relation that took the slot of the id (see Fixed).
Fixed
- A signal listener (or change tracking) connected to a deleted id ran for the pairs of the
relation that took the slot of the id (a pair keeps only the slots of its elements), and so
did a query monitor with the deleted id as a term; the listeners of a deleted id also took
the hook of the entity in its slot. A deleted id now gives its dispatcher to no record: its
listeners hear nothing until the id is made alive again (
world:entity(id)). The problem was in 0.2.2.
Iteration
world:eachandworld:childrencollect the members of the id into a buffer taken from a pool of the module, and the loop reads the buffer, which goes back to the pool when the loop ends (a loop left withbreakleaves it to the collector); an id with one member needs no buffer. The words of an id with at most 64 words of members are taken with their keys sorted (a sparse id, the holders of a pair, the children of a parent); a larger id is walked through the levels of its bitset, a full word copied at once. A loop allocates its iterator only (176 bytes instead of 736), and a frame of the model allocates 60 % less. The loops are faster than the walk of 0.2.2 on sparse and dense ids alike: 16 / 256 / 2 048 / 16 384 members spread among 350 000 entities (the test P1) take 1.12 / 14.1 / 97 / 571 µs per loop in native code (0.2.2: 2.29 / 25.9 / 171 / 910 µs) and 1.61 / 27.1 / 177 / 1 133 µs in the interpreter (0.2.2: 3.24 / 42.1 / 270 / 1 499 µs).
Signals
- The last listener of an id that disconnects (a signal, or the listeners of a query monitor) removes the dispatcher of the id, and its records call the hook of the id (or nothing) again. 0.2.2 kept the dispatcher, and every add or remove of the id then cost 27–35 ns more: a tag added or removed after its monitor disconnected takes 103 / 65 ns instead of 134 / 91 ns (interpreter / native), as much as a tag that never had a listener.
Query monitors
- A world without monitors pays nothing for them: the only code of the monitors on the
operations of the world, around the removal of the old pair when an exclusive relation
replaces a pair (
ChildOfmoved to another parent), runs only while a monitor exists. A child moved to another parent takes 408 / 250 ns instead of 420 / 260 ns, as much as without that code (402 / 247 ns).
Tests and benchmarks
bench/workload.luauwithbench/workload_model.luau, andtools/workload.sh: the performance suite of the reference workload (P1–P9) against the previous release and the library twice (the noise), in the interpreter and in native code, at the small and the target scale, medians and ranges of 5 runs (see the development guide).test/workload_cases.luau: the behavior cases of the reference workload (ids and liveness, hooks and signals, relations, loops, among them the members ofworld:eachandworld:childrenat the start of the loop for every layout, debugging aids);tools/test.shruns it.test/lib.luau: loops over large records return the members of their start, and the buffers of the loops (nested loops over one id, loops left withbreak, an iterator called after its end, the buffer of a large loop reused by a smaller one); the last listener of an id that disconnects (the hook of the id, set before or while listeners were connected, the pairs of a relation,OnRemoveand deletes, change tracking, the internal hook ofExclusive, a relation deleted before its listener disconnects and whose slot another relation took), and a listener connected to a deleted relation (the relation in its slot, the id made alive again).- The comparison with jecs
gives the numbers of 0.2.3 beside 0.2.2 and jecs 0.11.0, each implementation measured in a
process of its own (in one process, the implementations that run first change the timings of
the later ones by up to 30 % in some rows); its tables add the queries of a concrete pair built
per call, an entity used as a term in 4 inline queries and the group
state tags.
Performance on the reference workload
The suite of bench/workload.luau (bash tools/workload.sh), luau 0.740. The small scale has
about 120 agents with 12 owned entities each, the target scale 700 agents with 500 (350 000
entities); P1 has worlds of its own. No test is worse than on 0.2.2 beyond the noise: the
events of P6 (a millisecond each at the target scale) move by up to 10 % between two runs of
the suite, in both directions.
Native code: 0.2.2 → 0.2.3, the median and the range of 5 runs, the ratio, and the median of the second run of 0.2.3 (the noise):
| Test | Case | Unit | Small | Target |
|---|---|---|---|---|
| P1 | 16 members spread (world:each) | µs per loop | — | 2.29 (2.15–2.39) → 1.12 (1.07–1.19), 0.49× (again 1.11) |
| P1 | 256 members spread (world:each) | µs per loop | — | 25.9 (25.1–26.2) → 14.1 (14.0–14.3), 0.54× (again 14.3) |
| P1 | 2048 members spread (world:each) | µs per loop | — | 171 (163–176) → 97.1 (95.1–98.9), 0.57× (again 96.7) |
| P1 | 16384 members spread (world:each) | µs per loop | — | 910 (896–927) → 571 (564–593), 0.63× (again 580) |
| P1 | 2048 members in runs of 8 | µs per loop | — | 103 (102–105) → 72.7 (71.3–73.7), 0.71× (again 72.8) |
| P1 | 100 000 of 100 000 (dense) | µs per loop | — | 3265 (3234–3274) → 2530 (2516–2604), 0.77× (again 2562) |
| P8 | the heap of the world after it is built | MB | 2.80 (2.73–2.81) → 2.80 (2.73–2.81), 1.00× (again 2.80) | 138 (138–146) → 138 (138–146), 1.00× (again 138) |
| P3 | world:each over (Trigger_k, agent) | ns per call | 435 (349–600) → 337 (293–438), 0.77× (again 309) | 5411 (5178–6349) → 3264 (3090–4379), 0.60× (again 3519) |
| P2 | 10 walks: world:each with a check | µs per frame | 17.1 (16.0–20.5) → 10.6 (9.43–11.3), 0.62× (again 10.7) | 124 (99.4–132) → 83.7 (67.7–98.7), 0.68× (again 81.6) |
| P2 | 10 walks: one stored query per system tag | µs per frame | 5.23 (5.07–5.46) → 5.22 (4.92–5.43), 1.00× (again 5.19) | 13.5 (11.1–14.8) → 12.2 (10.7–13.1), 0.90× (again 11.8) |
| P4 | 25 stored queries at their periods | µs per frame | 25.1 (24.3–25.3) → 24.9 (24.5–25.8), 0.99× (again 25.7) | 116 (112–119) → 110 (106–121), 0.95× (again 116) |
| P5 | messages and deferred messages | µs per frame | 24.3 (23.7–25.0) → 23.1 (21.3–24.8), 0.95× (again 21.3) | 204 (184–219) → 161 (155–182), 0.79× (again 171) |
| P7 | a frame with the lifecycle events | µs per frame | 141 (136–144) → 130 (122–134), 0.92× (again 131) | 664 (633–718) → 600 (585–622), 0.90× (again 615) |
| P7 | the ECS work per second (60 frames) | ms per second | 8.45 (8.14–8.61) → 7.77 (7.33–8.02), 0.92× (again 7.84) | 39.8 (38.0–43.1) → 36.0 (35.1–37.3), 0.90× (again 36.9) |
| P9 | allocated by a frame | bytes | 16196 (16060–17033) → 7407 (7083–7646), 0.46× (again 7407) | 26146 (25890–26402) → 10121 (9830–10359), 0.39× (again 10172) |
| P9 | allocated by a loop over a stored query | bytes | 0.00 (0.00–0.00) → 0.00 (0.00–0.00), — (again 0.00) | 0.00 (0.00–0.00) → 0.00 (0.00–0.00), — (again 0.00) |
| P9 | allocated by a loop over world:each | bytes | 735 (735–736) → 176 (175–176), 0.24× (again 176) | 736 (735–736) → 176 (176–176), 0.24× (again 176) |
| P6 | the end of the activity of an agent | µs per event | 12.2 (10.1–13.1) → 11.7 (10.9–16.4), 0.96× (again 13.6) | 71.7 (63.8–80.3) → 67.9 (66.0–77.4), 0.95× (again 71.8) |
| P6 | the removal of a retained agent (cascade) | µs per event | 45.4 (42.0–60.1) → 45.2 (40.4–71.2), 1.00× (again 57.0) | 1125 (1057–1221) → 1100 (1068–1208), 0.98× (again 1127) |
| P6 | a new agent with its owned entities | µs per event | 46.0 (44.4–50.5) → 46.5 (43.4–56.6), 1.01× (again 49.9) | 1021 (980–1068) → 1010 (971–1031), 0.99× (again 1025) |
| P8 | the heap after 100 lifecycle rounds | MB | 3.24 (3.21–3.30) → 3.24 (3.21–3.30), 1.00× (again 3.24) | 139 (139–147) → 139 (139–147), 1.00× (again 139) |
| P8 | the heap after 3 000 more frames | MB | 3.80 (3.78–3.86) → 3.80 (3.77–3.86), 1.00× (again 3.80) | 140 (140–148) → 140 (140–148), 1.00× (again 140) |
| P8 | bytes per distinct pair (and its holder) | bytes | 1186 (1181–1189) → 1184 (1183–1189), 1.00× (again 1184) | 1235 (1234–1236) → 1235 (1234–1236), 1.00× (again 1235) |
| P8 | bytes per holder of a pair | bytes | 58.7 (58.7–58.7) → 58.7 (58.7–58.7), 1.00× (again 58.7) | 103 (103–103) → 103 (102–103), 1.00× (again 103) |
Interpreter: 0.2.2 → 0.2.3, the median and the range of 5 runs, the ratio, and the median of the second run of 0.2.3 (the noise):
| Test | Case | Unit | Small | Target |
|---|---|---|---|---|
| P1 | 16 members spread (world:each) | µs per loop | — | 3.24 (3.15–3.53) → 1.61 (1.57–1.63), 0.50× (again 1.60) |
| P1 | 256 members spread (world:each) | µs per loop | — | 42.1 (41.7–42.2) → 27.1 (26.8–28.0), 0.64× (again 27.6) |
| P1 | 2048 members spread (world:each) | µs per loop | — | 270 (265–272) → 177 (177–179), 0.66× (again 174) |
| P1 | 16384 members spread (world:each) | µs per loop | — | 1499 (1481–1548) → 1133 (1110–1168), 0.76× (again 1155) |
| P1 | 2048 members in runs of 8 | µs per loop | — | 153 (151–154) → 124 (123–125), 0.81× (again 123) |
| P1 | 100 000 of 100 000 (dense) | µs per loop | — | 3821 (3790–3834) → 3111 (3093–3159), 0.81× (again 3091) |
| P8 | the heap of the world after it is built | MB | 2.80 (2.73–2.81) → 2.80 (2.73–2.81), 1.00× (again 2.80) | 138 (138–146) → 138 (138–146), 1.00× (again 138) |
| P3 | world:each over (Trigger_k, agent) | ns per call | 458 (442–648) → 399 (385–463), 0.87× (again 462) | 6451 (6157–7437) → 5171 (4702–6418), 0.80× (again 4991) |
| P2 | 10 walks: world:each with a check | µs per frame | 21.9 (21.5–30.8) → 15.2 (14.3–16.8), 0.69× (again 14.8) | 184 (149–201) → 141 (108–153), 0.77× (again 137) |
| P2 | 10 walks: one stored query per system tag | µs per frame | 8.08 (7.64–8.57) → 7.90 (7.68–8.39), 0.98× (again 7.78) | 18.2 (15.5–19.3) → 19.1 (15.8–19.5), 1.05× (again 18.5) |
| P4 | 25 stored queries at their periods | µs per frame | 36.6 (35.6–41.5) → 36.7 (35.9–37.5), 1.00× (again 36.0) | 159 (155–182) → 154 (149–160), 0.97× (again 159) |
| P5 | messages and deferred messages | µs per frame | 32.5 (30.1–34.6) → 29.8 (28.0–34.5), 0.92× (again 28.5) | 291 (254–305) → 248 (241–288), 0.85× (again 238) |
| P7 | a frame with the lifecycle events | µs per frame | 210 (208–211) → 195 (192–205), 0.93× (again 194) | 1011 (982–1023) → 889 (875–911), 0.88× (again 895) |
| P7 | the ECS work per second (60 frames) | ms per second | 12.6 (12.5–12.6) → 11.7 (11.5–12.3), 0.93× (again 11.6) | 60.7 (58.9–61.4) → 53.3 (52.5–54.7), 0.88× (again 53.7) |
| P9 | allocated by a frame | bytes | 16196 (16077–17033) → 7407 (7083–7646), 0.46× (again 7441) | 26146 (25890–26385) → 10121 (9830–10394), 0.39× (again 10172) |
| P9 | allocated by a loop over a stored query | bytes | 0.00 (0.00–0.00) → 0.00 (0.00–0.00), — (again 0.00) | 0.00 (0.00–0.00) → 0.00 (0.00–0.00), — (again 0.00) |
| P9 | allocated by a loop over world:each | bytes | 735 (735–736) → 176 (175–176), 0.24× (again 176) | 736 (735–736) → 176 (175–176), 0.24× (again 176) |
| P6 | the end of the activity of an agent | µs per event | 19.4 (17.9–19.8) → 19.8 (15.6–20.7), 1.02× (again 18.8) | 110 (101–116) → 109 (105–120), 0.99× (again 122) |
| P6 | the removal of a retained agent (cascade) | µs per event | 67.7 (61.8–84.6) → 70.2 (64.9–78.5), 1.04× (again 63.9) | 1603 (1573–1675) → 1593 (1559–1619), 0.99× (again 1851) |
| P6 | a new agent with its owned entities | µs per event | 65.2 (64.8–71.1) → 69.0 (67.5–71.6), 1.06× (again 66.2) | 1543 (1523–1556) → 1564 (1553–1591), 1.01× (again 1606) |
| P8 | the heap after 100 lifecycle rounds | MB | 3.24 (3.21–3.30) → 3.24 (3.21–3.30), 1.00× (again 3.24) | 139 (139–147) → 139 (139–147), 1.00× (again 139) |
| P8 | the heap after 3 000 more frames | MB | 3.80 (3.78–3.86) → 3.80 (3.77–3.86), 1.00× (again 3.80) | 140 (140–148) → 140 (140–148), 1.00× (again 140) |
| P8 | bytes per distinct pair (and its holder) | bytes | 1184 (1181–1189) → 1184 (1183–1189), 1.00× (again 1184) | 1235 (1234–1236) → 1235 (1234–1235), 1.00× (again 1235) |
| P8 | bytes per holder of a pair | bytes | 58.7 (58.7–58.7) → 58.7 (57.8–58.7), 1.00× (again 58.7) | 103 (103–103) → 103 (102–103), 1.00× (again 103) |
Memory
- The heap of the world of the model at the target scale is the one of 0.2.2: 138 MB after it is built, 139 MB after 100 lifecycle rounds, 140 MB after 3 000 more frames (with the lists of the model); 1 235 bytes per distinct pair with a new target and its holder, 103 bytes per holder of a pair.
- New: the pool of the buffers of
world:eachandworld:childrenkeeps up to 16 buffers, each of the size of the largest loop that gave it back (16 bytes per member): a loop takes the buffer the previous one gave back, only nested loops hold more than one.
v0.2.2 — 2026-09-29
The strengths of jecs: ten cases where an archetype ECS is at its best and jecs 0.11.0 was far
ahead of mErCS 0.2.1 (the group jecs strengths of the benchmarks). Wildcards that return
values, queries over large terms that change and inline queries with a pair are now faster
than in jecs, the other cases are closer; the rest of the benchmarks is on par with 0.2.1
(see the table below and
the comparison).
New: query monitors, callbacks for the entities that enter and leave a query, in place of the
monitors of the jecs addon modules/OB.
Fixed
(*, T)returned the value of a pair picked by the iteration order of a hash table when an entity had several pairs ofT, an order that changes with the pairs of other entities. It is now the pair with the lowest relation slot, the order of jecs (the first pair in the type of an archetype);(R, *)keeps the pair with the lowest target slot.world:eachandworld:childrenreturned the members of an id out of ascending slot order when they lay in words of its bitset in different blocks of 1024 slots (the order of a hash table); they are now in ascending slot order, like queries.- An id deleted inside its own
world:eachloop kept the loop returning all its members: a freed record kept its bitsets. They are cleared now, asremove_allclears them. world:setof a value on a tag (or on a tag pair) raises an error and leaves the tag added; itsOnAddhook, the signals, the monitors and change tracking did not see that add. The hooks run now (without the value) before the error.
Query monitors
query:monitor()returnsadded(fn),removed(fn)anddisconnect(): callbacks at the change that makes an entity enter or leave the query (an id of the query added or removed, an excluded id removed or added,Disabled,clear,delete, cleanup cascades, batch operations), oneaddedper entry and oneremovedper exit.removedruns before the ids are removed, so the values of the entity can still be read. An exclusive relation that replaces a pair (ChildOfmoved to another parent) makes no exit and no entry in a query with the relation and any target. A monitor listens to the signals of the ids of its query; a term(*, T)and change filters raise an error. A monitor keeps the terms of the query as they are when it is made (modifiers called on the query afterwards do not change it). It still listens to a deleted relation of a pair term, whose slot another entity may take (the query then matches the pairs of that entity): a new monitor is needed then.- The object has the shape of the monitors of the jecs addon
modules/OB:OB.monitor(query)becomesquery:monitor(), and the 42 monitor cases of the tests of the addon pass (test/jecs_compat/ob.luau). The observers of the addon are signals withquery:has(see the guide). - A delete runs the listener of one required id of a monitor; the others are quiet then (the delete of a member makes one check, not one per id).
Hooks
- Deleting or clearing an entity whose ids have
OnRemovehooks or signals costs less: the entities whose hooks run are a short stack instead of a table keyed by the entity, the first word of the signature with hooked ids is read once, the hooked records of the shared signature tables are collected inline (a relation with one pair of the entity without a new table), and the bit of each hooked id is tested inline. A delete of an entity with two components, one of them hooked, takes 460–490 / 260–275 ns instead of 525 / 330 ns (interpreter / native); with a hook onChildOf, 625–670 / 400–420 ns instead of 710 / 500 ns. - A removal that runs an
OnRemovehook tests the bit of the entity again without a call.
Queries
- Queries with a pair of an entity target (
world:query(A, pair(ChildOf, parent)),:with(pair(Likes, bob))) are shared by shape like the other queries, from the second request of the shape, and their shapes go when the target is deleted, as the shapes of an entity used as a term (those of(*, T)too). A pair whose target is not alive is not shared. 0.2.1 built a new state for such a query on every call. A query of a concrete pair per call takes 1.01 µs / 895 ns instead of 4.37 / 3.15 µs (15 matches of 1000; jecs: 1.43 / 1.31 µs), 167 / 149 ns when nothing matches (0.2.1: 963 / 822 ns; jecs: 367 / 353 ns), andquery(A, pair(ChildOf, parent))per parent 580 / 516 ns (0.2.1: 1.97 / 1.58 µs; jecs: 885 / 821 ns). A shared shape keeps about 3.2 KB while its target lives, and the shapes of pairs share the 1024 shared states of a world with the others. - A query whose smallest required term has few words tests those words against the changed bits of each word, gathered once for all the queries, instead of each changed slot against its terms: small queries that share a large term which changes often pay a few word tests whatever the number of changes. 20 small queries over a tag toggled on 30 entities per frame take 22.0 / 14.7 µs (0.2.1: 120 / 61.4 µs; jecs: 19.3 / 15.9 µs).
- A query shape is shared from its second request. The first request gets a light state of
its own and only marks the shape; kept and used again (a second loop, a modifier,
cached()), it becomes the shared state. A query requested once (an entity used as a term) keeps no shared state: 2 inline queries per new caster keep 376 B instead of 3156 B, and take less than half the time. - A cached query patches its match list while that costs less than a pass over the bitsets: up to a quarter of the list or half of the words of its smallest term (at least 32, at most 1024 slots; 0.2.1: a quarter of the list). The noted slots of a record with more than 8 changes are dropped at once when one of the three smallest required terms, whose own changes are re-checked, does not have them, and the queries that saw the same versions of a record read its changes from the journal once.
- A small query that is not cached (up to 4 required terms and 2 excluded ones, the smallest term in at most 64 words of its bitset) gathers its matches in one loop over those words before the loop of the caller: the first request of a shape, the inline queries of a new entity.
- The arrays of a match list have their exact size (30 % less memory per list), and the first list of a query is built from the spans that the choice of its iteration mode found, without a second pass over the bitsets.
Relationships
- A wildcard whose values a query returns keeps a mirror: value pages with the value of one
pair of each member, updated by every change of its pairs, which the queries read like the
column of a component (and
gettoo). 0.2.1 looked for the pair of every match on every loop. A mirror takes about 17 B per member and goes when no pair of the wildcard holds data. - Deleting an entity clears the pairs of each of its relations in one inline loop.
- An entity with many pairs of one relation: a new pair goes to the end of the list of the pairs of the relation (ordered by target slot) when its target is the highest one, as when targets are added in the order they were created, and any other one finds its place by a binary search; a removal searches the same way beyond 16 pairs. 0.2.1 read the list from its start. 1000 targets of one relation on one entity: 1.49 / 1.02 µs per add instead of 7.25 / 4.33 µs (in the order of creation), 0.97 / 0.67 µs per remove instead of 2.95 / 2.87 µs (in the reverse order).
Iteration
world:eachandworld:childrenwalk the bitsets of the id instead of collecting its members first, and allocate only their iterator. An entity that loses the id or is deleted before the loop reaches it is skipped (0.2.1 returned it, a deleted one as a dead id); an entity that gets the id during the loop is visited only when its slot lies ahead of the loop and existed when the loop started. The members of an id in at most two words of its bitset (up to 64, like the children of a parent created together) are still collected first.
Tests and benchmarks
test/lib.luau: wildcard values through mirrors (the transitions of a slot between one and several pairs of a target), match lists that skip the changes outside their smallest term,world:eachandworld:childrenover large records (changes during the loop, the order of the members), the sharing of query shapes from their second request, queries that are not cached and gather their matches first, queries that share a changing tag, and query monitors (every kind of term, exclusive relations, an exclusive replacement whose new pair is not added, clear, delete, cascades, batch operations, disconnect, callbacks that change the world, the terms that are refused).test/jecs_compat/ob.luau: the tests of the jecs addonmodules/OBagainst the monitors (tools/test.shruns them).test/monitors_fuzz.luau: random queries and changes of the world; the members that each monitor reports must be the matches of its query (tools/test.shruns five seeds).test/queries_fuzz.luau: random queries (wildcard values, OR terms, pairs,Disabled, cached and inline, loops left early and nested) against brute force after bursts of changes;test/loops_fuzz.luau: loops that change the world (no entity twice, the untouched ones once).- The documentation of change tracking says 7 finished ticks (it said 8: the ring of 8 ticks
holds the current one), and
world:range(first, last)givesfirst + 1first, as in jecs. test/fuzz.luau: pairs of a third relation with the anchor as the target (slots with several pairs of one target), stored queries of(R3, *)and(*, anchor), the values of(*, t)checked against the model, every query shape requested twice, and the flagmonitors(monitors of the stored queries and of an exclusive relation,ChildOfandDisabled, checked against the model; CI runs it with the flags of the debug world).test/lib.luau: queries with a pair shared by shape and dropped with its target (the room of the shared states, a target made anew in the slot of a deleted one, the pair of a slot that no entity had), many targets of a relation added and removed in any order, and small queries that share a large term changed many times between loops (a debug world). The tests that need a query that is not shared give it a dead id among its excluded ids.test/fuzz.luau: the flagshapesalso checks queries with a pair whose target is an entity of the model.test/monitors_fuzz.luau: every third query is not shared (a dead id), so that a modifier after its monitor changes its state in place.bench/strengths.luau: the groupjecs strengthsofbench/run.luau.bench/monitors.luau: the groupquery monitors, against jecs with its addonmodules/OB(thejecs_obalias of.luaurc).
Performance
The group jecs strengths in the luau 0.740 CLI, cells read "interpreter / native", the
median of 5 runs of the minimum of 3; memory is what a unit keeps:
| jecs 0.11.0 | mErCS 0.2.1 | mErCS 0.2.2 | |
|---|---|---|---|
(*, T) values, 32 data relations, a pass over 20 000 | 722 / 601 µs | 16.0 / 7.46 ms | 539 / 310 µs |
(R, *) values, 8 targets, a pass over 20 000 | 722 / 590 µs | 4.19 / 3.20 ms | 530 / 305 µs |
| 15 cached queries over scattered entities, per query | 280 / 238 µs, 5.7 KB | 843 / 584 µs, 374 KB | 714 / 335 µs, 263 KB |
| a query that is usually empty, 20 swaps per pass | 16.4 / 16.5 µs | 224 / 80.9 µs | 14.5 / 8.74 µs |
| 5 queries with 100 matches each, 40 toggles per frame | 46.8 / 44.3 µs | 968 / 328 µs | 30.6 / 17.7 µs |
| 20 small queries, a shared tag toggled on 30 per frame | 19.3 / 15.9 µs | 120 / 61.4 µs | 22.0 / 14.7 µs |
query(A, pair(ChildOf, parent)) per parent | 885 / 821 ns | 1.97 / 1.58 µs | 580 / 516 ns |
| 2 inline queries per new caster | 2.32 / 2.24 µs, 0 B | 10.7 / 9.50 µs, 3156 B | 4.67 / 4.25 µs, 377 B |
world:each over 100 000, per entity | 27.7 / 24.7 ns | 61.5 / 36.2 ns | 38.6 / 31.5 ns |
world:children, 1000 children, per child | 28.1 / 25.0 ns | 57.3 / 32.6 ns | 39.3 / 32.5 ns |
| 8 kinds created in turn, a pass over one, for-in, per match | 41.3 / 33.0 ns | 119 / 106 ns | 114 / 103 ns |
the same, each | 41.9 / 33.3 ns | 90.8 / 78.1 ns | 63.1 / 47.1 ns |
the same, each, the kind from a slot pool | 40.2 / 32.7 ns | 35.9 / 20.1 ns | 36.1 / 20.4 ns |
| delete entities with 100 targets, per pair | 29.2 / 29.4 ns | 83.5 / 52.3 ns | 62.2 / 44.1 ns |
| 8 components on 1 entity in 64, per entity | 2.85 / 2.26 µs, 170 B | 2.53 / 1.73 µs, 660 B | 2.50 / 1.71 µs, 660 B |
Query monitors (the group query monitors), jecs 0.11.0 with its addon modules/OB against
query:monitor(), 10 000 entities, medians of 5 runs:
| jecs 0.11.0 + OB | mErCS 0.2.2 | |
|---|---|---|
| a tag of the query added and removed, per cycle | 658 / 602 ns | 739 / 509 ns |
| members of the query deleted, per entity | 526 / 534 ns | 595 / 344 ns |
children moved to another parent, (ChildOf, *) monitored, per move | 517 / 449 ns | 649 / 427 ns |
Three rows of the matrix gain: a query of a concrete pair per call takes 1.01 µs / 895 ns
with 15 matches of 1000 (0.2.1: 4.37 / 3.15 µs, jecs: 1.43 / 1.31 µs) and 167 / 149 ns when
nothing matches (0.2.1: 963 / 822 ns, jecs: 367 / 353 ns), an entity used in 4 inline queries
and then deleted 5.61 / 5.04 µs (0.2.1: 10.6 / 10.6 µs, jecs: 2.22 / 1.97 µs). The
other rows of the matrix, the synthetic frame (bench/frame.luau) and the long session
(bench/leak.luau: 0.08–0.09 ms per frame, +0.33 MB) are within the noise of the runs (±10 %)
of 0.2.1.
v0.2.1 — 2026-09-28
Fixes and memory for games that moved to 0.2.0: the shared query shapes of deleted entities,
match lists that change by many entities between loops, queries that are not shared, and the
(*, T) records of targets.
Fixed
- The shared query shapes of entity ids were never freed. A query with an entity id as a term
(
world:query(Skill):with(caster)) is shared by shape like any other, but its path in the tree of shapes (created even when no state was cached) and its state stayed after the entity was deleted, and such shapes used up the 1024 shared states: every new shape of the world, of components too, then built a new state on everyworld:querycall (~3 µs instead of ~0.2 µs), with no warning. 20 000 deleted entities with 4 such queries each kept +8 MB. Now the path of a shape is created with its state only, the shapes of an entity leave the tree when it is deleted (also the ones that its own hooks make while it is deleted; a handle that keeps one keeps a working query, whose modifiers return queries of their own), and a shape with an entity id that is not alive is not shared. The problem was also in 0.1.2.
Queries
- A cached query patches its match list only while the changes noted since its previous loop are at most a quarter of the list (and at least 32, at most 1024). After more, the loop passes over the bitsets, and the list is built again at a loop after fewer changes. 0.2.0 rebuilt the list on every such loop, which took longer than the scan of 0.1.2 (the long session and the synthetic frame were slower than in 0.1.2). A journal no longer grows for more changes than the query that reads it patches.
- A query that is not shared (a pair with a concrete target, change filters, a shape beyond the 1024 shared ones) reuses the iteration contexts of the world instead of building its iterator on every call.
Relationships
- A
(*, T)record has 8 fields and no presence tables until a query,has,world:eachorremovereads it: a pair with a target of its own keeps 1457 B instead of 1809 B, aChildOfchild (10 000 parents with 5 children) 344 B instead of 414 B.
Debug worlds
ecs.world(true)warns once (warnin Roblox,printin the luau CLI) when the 1024 shared query states of the world are in use and a new shape cannot be shared.
Tests and benchmarks
test/lib.luau: the shared shapes of deleted entities (memory, the count of the shared states, kept handles, ids made alive again, a debug world at the limit), queries that are not cached (nested loops,break, errors in callbacks), match lists after many changes, and(*, T)records before their first read.test/fuzz.luau: the flagshapes(queries with the entities of the model as terms, and handles kept after their entity is deleted); CI runs it with the flags of the debug world.bench/shapes.luau: the groupstate tags(1200 skills in 5 state tags; 10, 200 or 800 of them change state between the loops of 5 inline queries).bench/scenarios.luau: a query of a concrete pair per call, and the memory of inline queries on deleted entities.
Performance
mErCS 0.2.0 and 0.2.1 in the luau 0.740 CLI (bench/run.luau, bench/leak.luau); cells read
"interpreter / native", memory is what a unit keeps:
| mErCS 0.2.0 | mErCS 0.2.1 | |
|---|---|---|
| 1200 skills, 200 change state between the loops of 5 inline queries, per frame | 208 / 124 µs | 171 / 100 µs |
| the same, 800 change state | 430 / 266 µs | 363 / 233 µs |
| a query of a concrete pair per call, 15 matches of 1000 | 5.45 / 4.16 µs | 4.16 / 2.92 µs |
| the same, nothing matches | 1.86 / 1.71 µs | 612 / 510 ns |
| an entity used in 4 inline queries, then deleted | 18.1 / 15.8 µs, 492 B | 9.66 / 9.58 µs, 0 B |
| a pair with a target of its own | 3.56 / 3.24 µs, 1809 B | 3.21 / 2.84 µs, 1457 B |
a ChildOf child (10 000 parents × 5) | 820 / 657 ns, 414 B | 720 / 567 ns, 344 B |
| the long session, per frame (interpreter) | 0.10–0.11 ms, +0.40 MB | 0.09–0.10 ms, +0.33 MB |
The synthetic frame (bench/frame.luau) is on par with 0.1.2 again: 0.93–0.98× of 0.1.2 in
the interpreter and 1.02–1.04× in native code, medians of 3 runs (0.2.0 was 1–15 % slower).
The state tags with 200 or 800 changes per frame still take 1.06–1.15× the time of 0.1.2: the
changes themselves cost more (the journals of the observed tags, the third level of bits),
the queries take the time of 0.1.2 again. The other rows of the matrix are within the noise
of the runs (±10 %).
v0.2.0 — 2026-09-28
Queries after small changes, empty queries and (*, T) wildcards (the query cases where an
archetype ECS is expected to be at its best), plus slot pools. In native code (the Roblox
server) mErCS 0.2.0 is faster than jecs 0.11.0 in every query case; in the interpreter one case
is on par (see the tables below and
the comparison).
Queries
- A cached query keeps its match list after small changes. A record that a cached query
observes notes the slots it changes in a journal; before its next loop the query re-checks
only those slots and inserts or removes them in its list, instead of scanning its bitsets
and building the list again. Each journal entry carries the version it belongs to, so a
change that is not noted (a batch operation,
remove_all) or was overwritten makes the query scan again: a missed change costs a scan, never a stale result. - The match list is grouped by value page; a group of one match (an entity alone in its page) is read without its array.
- A query that matches nothing keeps an empty list: a loop costs a check of its ids, and nothing more while one of its required ids has no entity at all.
- A loop of a cached query uses its list without checking its records when, since its previous loop, no record that a cached query observes changed and no record was created or freed in the world (a stamp that every such change advances): a loop over an unchanged list, empty or not, starts with one comparison. A loop over an empty list takes 41 / 26 ns (interpreter / native; jecs: 64 / 59 ns).
- A for-in loop left with
breakno longer makes every later update of the list copy it (in 0.1.2 every rebuild of the list allocated new tables): the list is copied once, at the next update, and a loop that is still running keeps the copy it started with. query:cached()prepares a query that has not been iterated yet (it picks how it iterates and builds its list), as jecs matches its archetypes there; the first loop of a new cached query no longer pays for it.- A third level of presence bits (one bit per 32 768 slots): a scan skips the empty parts of a large world.
- Up to two excluded ids (
without,Disabled) are tested inline in the bitset scan.
Relationships
ecs.pair(ecs.Wildcard, T)is built from the pairs ofTthe first time a query,has,world:eachorremovereads it, and kept up to date from then on (with a count for the entities that have several pairs ofT). Before, every change of a pair ofTrebuilt it from all the pairs ofT, and a query that returned it read every pair ofTfor every entity even when no pair held data.- Deleting a target no longer updates its own
(*, T)record, which is freed right after. - The records of pairs that no entity has any more are freed in batches, once there are more
than 256 of them and they are more than a quarter of all pair records (a pair added again
before that keeps its record, so switching the target of a relation allocates nothing);
a
(*, T)record goes with the last pair record ofT. Before, a pair record lived until its relation or its target was deleted: adding and removing 20 000 pairs with live targets kept 33 MB, now under 1 MB.
Structural changes
- A tag added and removed on scattered entities no longer makes the bitset of its record rehash: an emptied word stays in the table as 0 until the emptied words outnumber the non-empty ones (Luau tables rehash all their keys when keys are removed and others added). Adding and removing a tag on a random creature of a world of 350 000 entities took 960 ns and takes 260 ns.
- Freeing a record no longer assigns nil to missing keys of the internal tables of ids: in Luau such an assignment inserts the key and can make the table rehash all its keys.
Slot pools
world:pool()makes a slot pool, andpool:entity()an entity with a slot from blocks of 256 slots reserved for the pool; a deleted pool entity gives its slot back to the pool. A kind of entities created among many others (creatures among their skills) stays dense, so a query over it reads a few words instead of a word per entity. Pool entities are ordinary entities. New type:ecs.Pool.
Debug worlds
ecs.world(true)also checks every match list that a cached query updates after a change against a scan of its bitsets, and a loop that uses its list without checking its records checks them and raises an error when one changed (a library bug).
Tests, benchmarks and tools
test/lib.luau: patched match lists, empty queries, groups of one match,(*, T), slot pools, large worlds and scattered members, and lists used as they are after every kind of change.test/lib.luau: the fixes below, and pair records freed in batches (with a model of pairs with many targets in a debug world).test/fuzz.luau: the flagssparse(entities spread over many pages and every bitset level),pool,verify(a debug world) andchurn(pair records freed in batches between and inside the operations of the model); CI runs them.bench/query_cases.luau: five query cases where an archetype ECS is expected to be at its best, jecs for-in loops againstquery:each.bench/shapes.luau: the groupsquery casesandsparse worldof the matrix.- The benchmarks print the versions they compare (
bench/versions.luau) and take the previous release whentools/previous.shhas extracted it from its git tag intotmp/previous. bench/visual/query_*.bench.luaufor the Benchmarker plugin, whose functions are now named with the versions, and the Rojo templatebenchmarker.project.json: a place with only the libraries and the bench files.- The toolchain uses
luau0.740.
Fixed
The fixed problems were also in 0.1.2.
OnRemovehooks ran twice onworld:deleteandworld:clearwhen the entity had ids with hooks both among the first 256 records of the world and beyond them (a world with more than 256 components, tags and relations).- A cascade of deletes deeper than 100 levels through a tag or a relation with
(OnDelete, Delete)raised an error (attempt to index nil with 'kind') and left the rest of the cascade alive. The entities queued past 100 levels now lose the deleted id before its record is freed (itsOnRemoveruns for them withdeleting = true); the children queued in aChildOfcascade no longer keep a reference to the freed pair of their parent. - A hook, a listener or tracking on
Exclusive,OnAdd,OnChangeorOnRemovereplaced the internal hook of the library for that id:Exclusivestopped acting on a relation that already had pairs, and hooks set afterwards did not reach the ids that already had records. - An entity that took the slot of another inside an
OnRemovehook of that entity, and was deleted or cleared there, skipped its ownOnRemovehooks. world:set(e, pair, value)with a tag pair thatealready had ignored the value; it now raises the error it raises for a new tag pair and for a tag.world:query():has(e)(a query without terms) returned true for every entity, while the query matches nothing.
Changed behaviour
world:exists(e)is also true for a slot reserved by a pool and not handed out yet.- A record observed by a cached query keeps a journal of 16 to 512 entries (0.5 to 16 KB).
world:added,world:changed,world:removedandworld:trackraise an error for a pair: they take a component, a tag or a relation (which covers all its pairs). Before, a pair was accepted, but its listeners never ran when the pair had no record yet, and replaced the hook of the relation for that pair when it had one.- The builtin
Disabledis named"mercs.Disabled"like the other builtins (it was"Disabled").
Performance
jecs 0.11.0, mErCS 0.1.2 and mErCS 0.2.0 in the luau 0.740 CLI; cells read "interpreter / native", the minimum of 18 runs in each mode.
The query cases (bench/query_cases.luau and the query cases group of bench/run.luau),
time of one pass:
| Case | jecs 0.11.0 | mErCS 0.1.2 | mErCS 0.2.0 | 0.2.0 / jecs |
|---|---|---|---|---|
| Scattered after recycling | 124 / 103 µs | 80.3 / 60.3 µs | 87.2 / 62.9 µs | 0.70× / 0.61× |
| Churn on a queried tag, 1 toggle per pass | 306 / 258 µs | 702 / 465 µs | 257 / 188 µs | 0.84× / 0.73× |
| Churn on a queried tag, 100 toggles per pass | 230 / 197 µs | 536 / 355 µs | 235 / 167 µs | 1.02× / 0.85× |
| Read 4 components | 1.92 / 1.42 ms | 1.22 ms / 643 µs | 1.28 ms / 662 µs | 0.67× / 0.47× |
(*, T) with churn | 796 / 689 µs | 14.5 / 13.2 ms | 528 / 341 µs | 0.66× / 0.50× |
| Usually empty | 64 / 59 ns | 194 / 67.3 µs | 41 / 26 ns | 0.64× / 0.44× |
A world of 700 creatures with 500 skills each (the sparse world group), one pass after the
change a game makes before it:
| Pass | jecs 0.11.0 | mErCS 0.1.2 | mErCS 0.2.0 | 0.2.0 / jecs | mErCS 0.2.0, pool | pool / jecs |
|---|---|---|---|---|---|---|
| Alive creatures, nothing changed | 6.18 / 5.54 µs | 6.07 / 4.37 µs | 5.42 / 3.96 µs | 0.88× / 0.71× | 7.00 / 3.95 µs | 1.13× / 0.71× |
Alive creatures, Dead added to one and removed | 7.08 / 6.36 µs | 94.5 / 60.4 µs | 7.28 / 4.91 µs | 1.03× / 0.77× | 7.47 / 4.32 µs | 1.06× / 0.68× |
Running creatures, Run toggled on one | 3.46 / 3.09 µs | 22.5 / 16.1 µs | 4.74 / 3.37 µs | 1.37× / 1.09× | 2.73 / 1.78 µs | 0.79× / 0.58× |
| A tag added to one creature, a pass, removed, a pass | 1.21 / 1.09 µs | 8.24 / 6.36 µs | 2.10 / 1.34 µs | 1.74× / 1.23× | 1.59 / 1.02 µs | 1.31× / 0.94× |
| A tag nobody has | 65 / 60 ns | 246 / 216 ns | 44 / 31 ns | 0.67× / 0.51× | 44 / 31 ns | 0.68× / 0.51× |
All with Model (creatures and corpses) | 21.2 / 18.6 µs | 21.2 / 14.8 µs | 18.8 / 13.2 µs | 0.89× / 0.71× | 15.7 / 8.82 µs | 0.74× / 0.47× |
A skill changes state, 10 queries over skills in Cast | 152 / 117 µs | 309 / 196 µs | 105 / 66.2 µs | 0.69× / 0.56× | 108 / 68.1 µs | 0.71× / 0.58× |
Without a pool, a change of one creature before a pass costs an edit of the match list that jecs does not have (it moves the creature to another archetype instead); with a pool every pass is faster than in jecs in native code. In the interpreter three rows of the pool stay at 1.06–1.3× of jecs: the alive creatures (with and without a change) and a tag on one of them.
The synthetic game frame (bench/frame.luau, the median frame time, the middle one of 3 runs):
| jecs 0.11.0 | mErCS 0.1.2 | mErCS 0.2.0 | 0.2.0 / jecs | |
|---|---|---|---|---|
| interpreter, inline queries | 6.70 ms | 3.11 ms | 3.16 ms | 0.47× |
| interpreter, cached queries | 6.24 ms | 3.18 ms | 3.20 ms | 0.51× |
| native, inline queries | 5.78 ms | 2.22 ms | 2.33 ms | 0.40× |
| native, cached queries | 5.43 ms | 2.12 ms | 2.46 ms | 0.45× |
A query whose entities change by many (dozens to hundreds) before every loop updates its match
list, which costs more than the scan of 0.1.2: the synthetic frame takes 1–15 % longer than in
0.1.2, and the long session of bench/leak.luau 0.11 ms per frame against 0.09 ms (jecs
0.11.0: 0.23 ms).
Installation
- Wally:
mercs = "dubalda/mercs@0.2.0". - Roblox model:
mercs.rbxm, attached to this release.
v0.1.2 — 2026-09-26
Fixed
- Deleting an entity whose cascade runs hooks that write into it (a child whose
OnRemovehook sets a component of its parent while the parent is deleted) no longer leaves those ids on the freed slot: the deleted entity stayed in queries as a dead id, and the next entity that reused the slot inherited the ids.
Installation
- Wally:
mercs = "dubalda/mercs@0.1.2". - Roblox model:
mercs.rbxm, attached to this release.
v0.1.1 — 2026-09-26
The Wally package gets a description, a homepage and a repository link; the code is the same as in v0.1.0.
Installation
- Wally:
mercs = "dubalda/mercs@0.1.1". - Roblox model:
mercs.rbxm, attached to this release.
v0.1.0 — 2026-09-26
The first release of mErCS, an entity component system for Luau and Roblox built on inverted bitsets. Every component, tag and pair keeps a bitset of the entities that have it, and the values sit in pages indexed by the entity slot: adding or removing a component sets a bit and a value, never moves the entity and never creates anything per combination of components. The API follows jecs.
Highlights
- O(1) structural changes. Tags for states, relationships, spawning and despawning cost the same whatever the entity has; memory does not grow with the number of component combinations, and there is nothing to clean up.
- The jecs feature set. Worlds, entities, components and tags, pairs and wildcards,
Exclusive, cleanup policies (OnDelete/OnDeleteTargetwithDelete/Remove),ChildOfhierarchies, hooks (OnAdd,OnChange,OnRemove), signals (world:added/changed/removed),Name, pre-registered ids. - Beyond jecs.
query:each(fn), the fastest loop, andquery:any(...)OR terms.- Batch operations on the matches of a query:
count,add_all,set_all,remove_all,delete_all, plusworld:remove_all(id). - Change tracking by ticks:
world:track,world:tick, and the query filtersadded,changed,removed. - The
Disabledtag, hierarchies of any depth, no limit on the number of components. get/haswith up to 8 ids (get_list/has_allfor more), a fast path over the raw columns (query:spans,world:column), and debug worlds that raise errors for dead entities and ids.
- Typed API.
Component<T>carries the data type intoget,setand queries; the module is--!strictand--!native. - jabby. The debugger connects through the adapter
mErCS.jabby, a child module that the library itself never requires.
Performance
Measured against jecs 0.11; time of mErCS relative to jecs, lower is better.
| Benchmark | jecs | mErCS | Ratio |
|---|---|---|---|
| Synthetic game frame, interpreter (luau CLI) | 5.22 ms | 2.46 ms | 0.47× |
| Synthetic game frame, native (luau CLI) | 4.58 ms | 1.62 ms | 0.35× |
| Spawn 1000 entities with 4 components (Roblox Studio, Benchmarker) | 1.116 ms | 0.589 ms | 0.53× |
| Remove one of 5 components from 1000 entities (Benchmarker) | 356 µs | 60 µs | 0.17× |
| Hierarchy with relationships, then delete the parents (Benchmarker) | 7.971 ms | 1.762 ms | 0.22× |
| Add and remove a tag on 1000 query matches (Benchmarker, batch operations) | 496 µs | 49 µs | 0.10× |
- A long session with changing relationship targets: the heap stays flat (+0.4 MB), while jecs grows by 15 MB in 5000 frames.
- An entity with 4 components takes 130 bytes (jecs: 320).
- Still slower than jecs: a for-in over sparse matches (about 1.2–1.5×;
query:eachis faster than the jecs loop),haswith 4 ids in the interpreter, and many pairs of one relation with scattered targets.
All numbers, the benchmark sources and the Benchmarker screenshots are in the comparison with jecs.
Coming from jecs
- 125 of the 125 applicable cases of the jecs test suite pass.
- A few jecs calls are not provided because they would do nothing here or only repeat native
calls:
World.new,w,bulk_insert/bulk_remove,new/new_w_id/new_low_id,world:cleanup(),query:fini(),ArchetypeCreate/ArchetypeDelete. query:iter(),query:archetypes(),world.entity_index,entity_index_try_getandis_tagexist only in the jabby adapter.- The builtin ids after
Namehave other numbers:Exclusiveis 268 (jecs: 270),Restis 270 (jecs: 271). - The migration guide lists what to write instead of each call.
Installation
- Wally:
mErCS = "dubalda/mercs@0.1.0". - Roblox model:
mercs.rbxm, attached to this release. - Or copy
src/init.luauinto a ModuleScript (src/jabby.luauis the optional jabby adapter).
Documentation
- Documentation site: the API reference and the guide.
- Guide in the repository.
Status
Pre-release (0.x): the API may still change. Tested with the standalone luau 0.703 CLI (the
interpreter and native code generation), in CI on Linux, and in Roblox Studio with the
Benchmarker plugin and the jabby debugger. A full check in a running Roblox place (server and
client) is still pending.