mErCS and jecs
How mErCS 1.3.0 differs from jecs 0.11.0: the design, the behaviour, when jecs is the better choice, the numbers, and how to move code over. The comparison of 1.3.0 with the previous release is on its own page, the Benchmarker screenshots on Benchmarker.
Contents
- Design
- Compatibility
- Differences in behaviour
- Beyond jecs
- When jecs is the better choice
- Performance
- Migrating from jecs
Design
An archetype ECS (jecs, flecs) stores the entities with the same set of components together. That makes iteration fast, but every add or remove moves the entity to another archetype and copies all its columns, every new combination of components creates an archetype that lives until someone cleans it up, and relationships to many targets create an archetype per target.
mErCS keeps, for every component, tag or pair, a bitset of the entities that have it, and the values in pages indexed by the entity slot. A query ANDs the bitsets 32 entities at a time and walks the set bits.
| jecs 0.11.0 | mErCS 1.3.0 | |
|---|---|---|
| add / remove a component | moves the entity, copies all its columns: O(components) | sets a bit and a value: O(1) |
| new combination of components | creates an archetype (kept until world:cleanup()) | nothing to create |
| pair with many targets | an archetype per target | one small record per pair, freed when unused (in batches) or with its target |
ids per get / has call | 4 | 8, any number with get_list / has_all |
| memory per entity with 4 components | 320 B | 131 B |
| deep hierarchies | the cascade recurses: stack overflow at about 6000 levels | any depth (past 100 levels the rest is queued) |
Compatibility
The API follows jecs: worlds, entities, components, tags, pairs, wildcards, Exclusive,
cleanup policies, hooks, signals, Name, pre-registration (jecs.component() /
jecs.tag() / jecs.meta()), the ECS_* helpers and the builtin ids.
The 1.3.0 CLI check passes the jecs test suite (test/jecs_compat/) in both modes:
125 of 125 applicable cases pass (its bulk_insert / bulk_remove come from a test shim, as loops of set /
remove). The cases that inspect jecs internals (archetype records, edges, the entity
visualiser) are not applicable and are listed in test/jecs_compat/README.md.
Differences in behaviour
- No archetypes:
world:cleanup(),query:fini()and the idsArchetypeCreate/ArchetypeDeletedo not exist (there is nothing for them to do), hooks do not get anoldarchetypeargument: the fourth argument of anOnChangehook and of aworld:changedlistener is the value that the change replaced. - The jecs helpers
World.new,w,bulk_insert/bulk_remove,new/new_w_id/new_low_id,query:iter()andis_tagare not provided: they would only repeat native calls (see Migrating from jecs). - jecs internals (
query:archetypes(),world.entity_index,entity_index_try_get) are not provided either; the jabby adapter gives the debugger what it reads. - An uncached query can be iterated again (jecs drains it after the first loop).
get/hastake up to 8 ids positionally (jecs: 4).- The iteration order is ascending by entity slot, not by archetype.
- Builtin ids after
Namehave other numbers:Exclusiveis 268 (jecs: 270),Disabled(not in jecs) 269,Rest270 (jecs: 271). - The jecs addon
modules/OBreads archetypes and does not work here. Its monitors arequery:monitor(), which returns the sameadded/removed/disconnect(the 42 monitor cases of the tests of the addon pass,test/jecs_compat/ob.luau), and its observers are signals with a check of the query (see the guide). A monitor of mErCS does not make an entity leave and enter a query with an exclusive relation and any target when the relation replaces a pair; it takes no term(*, T). - Setting a hook after connecting signals keeps the signals (in jecs the hook replaces them),
and
world:get(id, ecs.OnAdd)returns the hook, not the signal dispatcher. - A signal listener that disconnects itself while it runs does not make the next listener miss the event (in jecs it does).
- Signals and change tracking take a component, a tag or a relation (for all its pairs); a pair raises an error (jecs does not support pairs there either).
- Changing the world during a loop: the current entity may be changed or deleted in both.
jecs may visit an entity twice when others are removed from its archetype; here an entity
deleted ahead of the loop is skipped or returned once as a dead id (
world:containsis false), with the values that its slot holds when the loop reaches it. query:cached()on a query that has not been iterated yet prepares it (picks how it iterates and builds its match list), as jecs matches its archetypes there; on a shared query (world:query(...)without change filters) it does nothing else: such a query is cached already. A query shape is shared from its second request; the first request gets a state of its own, which becomes the shared one when it is used again (a second loop, a modifier,cached()).- A wildcard returns the value of one pair of each entity:
(R, *)the pair with the lowest target slot,(*, T)the pair with the lowest relation slot (jecs: the first such pair in the type of the archetype, which is sorted by id). world:eachandworld:childrenreturn the members of the id when the loop starts, in ascending slot order: an entity that gets the id during the loop is not visited, and one deleted before the loop reaches it is returned as a dead id (jecs walks the rows of its archetypes backwards).world:exists(e)is also true for a slot reserved by a slot pool and not handed out yet.- A query with excluded ids alone (
world:query():without(A)) raises an error when it is used: it would match nothing. A query needs a returned or required id, an OR term or a change filter. - A removal that the hooks of the same removal start again (the same id removed from the same entity) does nothing, so a relation kept in sync by its hooks runs the hook of each side once (in jecs such hooks remove the pair back and forth until the stack overflows).
- The
Componenttrait added to an id used already, or removed from a used one, raises an error and changes nothing. jecs also decides at the first use of an id whether it holds data, and keeps that decision without an error when the trait changes later. world:remove(e, ecs.pair(R, ecs.Wildcard))removes every pair(R, *)of the entity, andecs.pair(ecs.Wildcard, T)every pair with the targetT;addandsetraise an error for a wildcard pair. jecs forbids a wildcard pair in all three:jecs.world(true)raises an error, and a world without the check leaves the pairs in place and breaks the row of the entity in its archetype.
Beyond jecs
query:each(fn)— a callback per match; see the measured query loops.query:any(...)— OR terms.- Batch operations:
query:count,add_all,set_all,remove_all,delete_all,toggle_all, andworld:remove_all(id). world:toggle(e, id): adds an absent id, removes a present one, and tells which it did.world:expect(e, id): the value of an id that the entity must have, typed withoutnil; when there is no value, an error that names the entity and the id instead ofnil.- Change tracking by ticks:
world:track,world:tick, the:added/:changed/:removedfilters, and new entities withworld:track_createdand:created. ecs.Disabled: entities hidden from queries without removing their components.- Slot pools:
world:pool()andpool:entity()keep a kind of entities created among many others (creatures among their skills) in slots of its own, so the bitsets and value pages of what only they have stay dense. world:ids(e), a debug world (ecs.world(true): every call checks its arguments, and the error names the method and the argument,world:query: id 2 is nil; the match lists of cached queries are checked against their bitsets),query:spans()withworld:column(id).
When jecs is the better choice
jecs keeps the entities of one set of ids together, in the rows of an archetype; mErCS keeps a bitset per id and the values in pages indexed by the entity slot. Each layout has cases that the other cannot match. The numbers compare jecs 0.11.0 and mErCS 1.3.0: the time or memory of mErCS divided by that of jecs, "interpreter / native" (see Performance).
What only jecs has
- roblox-ts: jecs has TypeScript declarations (
@rbxts/jecs); mErCS is a Luau module only. - An observer object: the observer of the addon
modules/OBcalls back for every add or value change of an id of a query on an entity that matches it. In mErCS a signal withquery:hasdoes that; the monitors of the addon arequery:monitor(). - Archetypes as an API:
query:archetypes()with the columns of each archetype, the idsArchetypeCreate/ArchetypeDelete, and the tools that read them (the entity visualiser of jecs, for one). mErCS gives the value pages of a query throughquery:spans()andworld:column(id). - The original of the API: the documentation and examples of jecs, and the tools made for it, apply to it as they are. mErCS follows the API, runs the jecs test suite and adapts jabby, with the differences listed in Differences in behaviour.
Where jecs has a layout advantage
These measurements expose costs of the layouts. A slot pool helps when entities of a kind can be allocated together. Ratios are interpreter / native; memory medians agree across modes.
| Case | jecs | mErCS | mErCS / jecs |
|---|---|---|---|
| Cached queries over scattered entities, memory per query | 5803 B | 263 KiB | 46.37× |
| Sparse components: 8 on 1 entity in 64, memory per entity | 170 B | 660 B | 3.90× |
| Eight kinds created in turn, 3 values read | rows of each kind stay together | values follow slot layout | for-in 2.24× / 2.21×; each 1.52× / 1.49×; each with a pool 0.86× / 0.61× |
| Delete entities with 100 targets of a relation | remove one archetype row | clear the bit of each pair record | 2.08× / 1.49× |
Where jecs is faster than mErCS 1.3.0
The cases below compare measured medians. Consult the ranges in the full report for small differences; these ratios do not establish a statistically significant difference on their own.
- Two inline queries per new caster: 2.31× / 1.98×; memory retained per caster: 377 B in mErCS, 0 B in jecs. Four inline queries using an entity term followed by its deletion: 3.01× / 3.00×.
- A cached query over scattered entities, built and passed once: 2.51× / 1.32×.
- For-in over a sparse match (1%): 1.67× / 1.70×;
query:eachagainst the jecs for-in: 1.14× / 0.92×. - For-in with
without: 1.13× / 1.09×. - Adding the first component: 1.36× / 1.10×.
- Moving a child to another parent without a monitor: 1.51× / 1.18×.
- In the sparse world without a slot pool,
Runtoggled before a pass: 1.37× / 1.09×; a tag added and removed around passes: 1.64× / 1.20×.
Other interpreter costs, including multi-id access, entity deletion and query monitors,
are listed in the operation tables. Queries with a reused shape avoid the cost of a new
entity term: a concrete pair per call is 0.76× / 0.67×,
and query(A, pair(ChildOf, parent)) per parent is
0.61× / 0.57×.
When to choose jecs
- A roblox-ts project.
- Code built on
query:archetypes()or on tools that read archetypes. - Dozens of cached queries over entities whose composition rarely changes, with a tight memory budget: the query caches of jecs stay small whatever the number of entities.
- Many kinds of entities created together (a creature with its skills and items) when a slot pool per kind does not fit the code, and the systems loop with for-in.
- Components on a small share of the entities of a very large world, when memory matters more than the cost of adding and removing them.
- Queries built on every call with new entities as terms (a query per new entity), when they take a large part of the frame.
For the measured trade-offs in structural changes, relationships, long sessions and memory per entity, see Design, Beyond jecs and Performance.
Performance
Benchmarks in bench/, measured on 2026-11-07 with Luau 0.740: jecs 0.11.0 (the pinned
Wally dev package) and mErCS 1.3.0. Cells read "interpreter / native": -O2 / -O2 --codegen.
Ratios are the median time of mErCS divided by that of jecs; lower is better.
Each library runs in its own process, five times in each mode (fifteen for the matrix and the synthetic frame), with the order rotated. The tables show medians of those runs. A matrix run takes the minimum of three timed repetitions and the median retained-memory delta after full GC. The synthetic-frame helper runs three batches per query style and returns the frame median from the batch with the lowest minimum frame time. Small differences between medians should be read with their ranges. The same code took 0.97–1.07 of its time in the campaign of 1.2.0 on the same machine (the complete measurements compare the two campaigns; Roblox Studio and the Roblox player were open during these runs): the tables compare the libraries within one campaign.
The complete measurements include min–max ranges, hashes, commands and raw samples, with the previous release, 1.2.0, measured in the same runs (see 1.3.0 and 1.2.0). The screenshots of the Benchmarker plugin in Roblox Studio are on Benchmarker.
A synthetic game frame
bench/frame.luau: 3000 units with 2 attachments each follow their parents, 60 projectiles
spawn and expire per frame, damage uses a one-frame tag, 5 % of the units switch AI state
tags; plain for-in loops, the same code for all three. The median frame time; the queries are
written inline in every frame, or created once and :cached() (the recommended jecs style):
| Mode / queries | jecs 0.11.0 | mErCS 1.3.0 | 1.3.0 / jecs |
|---|---|---|---|
| interpreter, inline queries | 6.1 ms | 2.54 ms | 0.42× |
| interpreter, cached queries | 5.75 ms | 2.54 ms | 0.44× |
| native, inline queries | 5.31 ms | 1.76 ms | 0.33× |
| native, cached queries | 4.94 ms | 1.78 ms | 0.36× |
A long session
bench/leak.luau: 5 of 200 enemies die and respawn every frame, 10 % of 500 units retarget
a living enemy through a pair (Targeting, enemy) and switch a state tag. Each cell is the
median of five isolated runs: heap growth since the start, and time per frame in the preceding
1000-frame window (including checkpoint GC). Both execution modes are measured:
| Mode | Frame | jecs 0.11.0 | jecs 0.11.0 + cleanup every 600 frames | mErCS 1.3.0 |
|---|---|---|---|---|
| interpreter | 1000 | +3.57 MiB, 0.222 ms | +3.60 MiB, 0.207 ms | +0.33 MiB, 0.094 ms |
| interpreter | 3000 | +8.98 MiB, 0.223 ms | +8.80 MiB, 0.219 ms | +0.32 MiB, 0.094 ms |
| interpreter | 5000 | +15.38 MiB, 0.221 ms | +15.66 MiB, 0.223 ms | +0.32 MiB, 0.093 ms |
| native | 1000 | +3.57 MiB, 0.193 ms | +3.60 MiB, 0.188 ms | +0.33 MiB, 0.064 ms |
| native | 3000 | +8.98 MiB, 0.203 ms | +8.80 MiB, 0.199 ms | +0.32 MiB, 0.062 ms |
| native | 5000 | +15.38 MiB, 0.204 ms | +15.66 MiB, 0.208 ms | +0.32 MiB, 0.063 ms |
The jecs heap continues to grow in this 5000-frame session, including with cleanup every 600 frames. The mErCS heap remains near its warmed checkpoint values. This describes the measured session; it is not a guarantee for every entity layout or duration.
Query cases
Five cases where an archetype ECS is expected to be at its best (bench/query_cases.luau,
and the query cases group of bench/run.luau). jecs runs for-in loops over cached queries;
mErCS builds the same worlds and runs the same loops through query:each, which replaces a
for-in loop fully when it does not break early. Time of one pass:
| Case | jecs 0.11.0 | mErCS 1.3.0 | 1.3.0 / jecs |
|---|---|---|---|
| Scattered after recycling | 128 / 109 µs | 93 / 66.1 µs | 0.73× / 0.61× |
| Churn on a queried tag, 1 toggle per pass | 346 / 302 µs | 297 / 214 µs | 0.86× / 0.71× |
| Churn on a queried tag, 100 toggles per pass | 259 / 227 µs | 277 / 196 µs | 1.07× / 0.86× |
| Read 4 components | 1.92 / 1.5 ms | 1.35 ms / 679 µs | 0.70× / 0.45× |
(*, T) with churn | 804 / 712 µs | 543 / 335 µs | 0.68× / 0.47× |
| Usually empty | 68.9 / 62.7 ns | 43.3 / 28.3 ns | 0.63× / 0.45× |
- Scattered after recycling: 50 000 entities with random subsets of 8 components, then 100 000 deletes and respawns; a pass of a 4-component query (3125 matches).
- Churn on a queried tag: 70 000 entities with
Position, every 7th withVelocity; the query of both withoutStunned,Stunnedtoggled on 1 or 100 movers before each pass. The query re-checks the changed slots only; list edits and the cost of the toggles are both included in the measurements above. - Read 4 components: 80 000 entities, the fourth component on half of them.
(*, T)with churn: 20 000 entities with one of 64 pairs(R, T); a pair toggled before each pass ofHealthand(*, T). The query reads the values of(*, T)from a mirror (see The strengths of jecs).- Usually empty: 100 000 entities, each with
StunnedorInvulnerable; the query of both. The query keeps an empty list, and a pass after which nothing changed costs a comparison.
luau -O2 --codegen bench/query_cases.luau runs the same cases with the test kit of jecs:
one run per case, first loops included.
A sparse world
The shape of a game with many entities per creature (bench/run.luau, group sparse world):
700 creatures (200 alive, 500 dead), each created right before its 500 skills, 350 000
entities in all; a pass of each query of a frame after the changes the game makes. A
creature sits alone in its value page, so a query over creatures reads a word per creature;
in the "pool" columns the creatures come from a slot pool (world:pool()), which keeps them
together. Time of one pass:
| Pass | jecs 0.11.0 | mErCS 1.3.0 | 1.3.0 / jecs | mErCS 1.3.0, pool | pool / jecs |
|---|---|---|---|---|---|
| Alive creatures, nothing changed | 6.5 / 5.95 µs | 5.76 / 4.31 µs | 0.89× / 0.72× | 6.94 / 4.16 µs | 1.07× / 0.70× |
Alive creatures, Dead added to one and removed | 7.39 / 6.81 µs | 7.53 / 5.46 µs | 1.02× / 0.80× | 7.43 / 4.42 µs | 1.00× / 0.65× |
Running creatures, Run toggled on one | 3.57 / 3.33 µs | 4.88 / 3.62 µs | 1.37× / 1.09× | 2.93 / 1.89 µs | 0.82× / 0.57× |
| A tag added to one creature, a pass, removed, a pass | 1.27 / 1.18 µs | 2.09 / 1.42 µs | 1.64× / 1.20× | 1.71 / 1.05 µs | 1.34× / 0.89× |
| A tag nobody has | 69.8 / 65.1 ns | 45.1 / 30.1 ns | 0.65× / 0.46× | 45.5 / 30.5 ns | 0.65× / 0.47× |
All with Model (creatures and corpses) | 22.5 / 20.3 µs | 20 / 14.9 µs | 0.89× / 0.74× | 15.9 / 9.13 µs | 0.71× / 0.45× |
A skill changes state, 10 queries over skills in Cast | 141 / 128 µs | 112 / 71.7 µs | 0.79× / 0.56× | 118 / 71.6 µs | 0.84× / 0.56× |
Without a pool, a change of one creature before a pass (Run toggled, a tag added and
removed) costs a list edit: the creature is a group of its own in the match list of the query,
and the group is inserted or removed. jecs moves the creature to another archetype, and its
pass costs nothing more.
State tags
The group state tags of bench/run.luau (bench/shapes.luau): 1200 skills in 5 state tags;
10, 200 or 800 of them move to the next state, then 5 queries written inline pass over the
skills of each state (query:each in mErCS, for-in in jecs). Time per frame:
| Frame of 1200 skills, 5 inline queries | jecs 0.11.0 | mErCS 1.3.0 | 1.3.0 / jecs |
|---|---|---|---|
| 10 skills change state | 53.3 / 46.7 µs | 40.7 / 24.7 µs | 0.76× / 0.53× |
| 200 skills change state | 161 / 142 µs | 165 / 97.8 µs | 1.03× / 0.69× |
| 800 skills change state | 498 / 435 µs | 369 / 221 µs | 0.74× / 0.51× |
The strengths of jecs
Ten cases where an archetype ECS is at its best, in time or in memory (the group
jecs strengths of bench/run.luau, bench/strengths.luau). An archetype keeps the entities
of one set of ids together, a query caches the archetypes it matches, and a wildcard pair is
resolved per archetype, while a bitset ECS pays per entity, per changed slot or per value page.
Time of one pass or per unit; memory is what a unit keeps:
| # | Case | jecs 0.11.0 | mErCS 1.3.0 | 1.3.0 / jecs |
|---|---|---|---|---|
| 1 | (*, T) values, 32 data relations, a pass over 20 000 | 759 / 623 µs | 552 / 318 µs | 0.73× / 0.51× |
| 2 | (R, *) values, 8 targets, a pass over 20 000 | 761 / 620 µs | 546 / 317 µs | 0.72× / 0.51× |
| 3 | 15 cached queries over scattered entities, per query | 301 / 253 µs | 754 / 334 µs | 2.51× / 1.32× |
| the same, memory per query | 5803 B | 263 KiB | 46.38× | |
| 4 | usually empty, 20 swaps per pass (100 000 entities) | 17 / 16.3 µs | 14.1 / 7.62 µs | 0.83× / 0.47× |
| 5 queries, 100 matches each, 40 toggles per frame | 52.2 / 47.8 µs | 33.6 / 17.8 µs | 0.64× / 0.37× | |
| 5 | 20 small queries, a shared tag toggled on 30 per frame | 21.8 / 18.1 µs | 22.7 / 14.9 µs | 1.04× / 0.82× |
| 6 | query(A, pair(ChildOf, parent)) per parent (1000 × 5) | 968 / 876 ns | 594 / 498 ns | 0.61× / 0.57× |
| 2 inline queries per new caster | 1.91 / 1.89 µs | 4.43 / 3.74 µs | 2.31× / 1.98× | |
| the same, memory per caster | 0 B | 377 B | inf× | |
| 7 | world:each over 100 000, per entity | 28.6 / 25 ns | 31.7 / 24.8 ns | 1.11× / 0.99× |
world:children, 1000 children, per child | 29 / 25.4 ns | 32.9 / 25.8 ns | 1.14× / 1.02× | |
| 8 | 8 kinds in turn, 3 values, for-in, per match | 42.6 / 34 ns | 87.7 / 83 ns | 2.06× / 2.44× |
the same, each | 42.6 / 34 ns | 64.8 / 54.7 ns | 1.52× / 1.61× | |
the same, each, the kind from a slot pool | 42.6 / 34 ns | 37.3 / 21.2 ns | 0.88× / 0.62× | |
| 9 | delete entities with 100 targets, per pair | 29.8 / 30.3 ns | 64.8 / 46.4 ns | 2.18× / 1.53× |
| 10 | 8 components on 1 entity in 64 of 131 072, memory per entity | 170 B | 661 B | 3.90× |
| the same, time per entity | 2.77 / 2.15 µs | 2.49 / 1.56 µs | 0.90× / 0.73× |
(*, T)values. jecs reads the column of the first pair ofTin each archetype. mErCS keeps a mirror for a wildcard whose values a query returns: value pages with the value of one pair of each entity (the lowest relation slot for(*, T), the lowest target slot for(R, *)), updated by every change of its pairs; the query reads it like the column of a component. A mirror keeps about 17 B per member (a(*, T)mirror also notes the pair that gives the value of a slot with several pairs ofT): the world of this case with its query takes 255 B per entity (jecs: 315 B).(R, *)values: the same mirror; the world with its query takes 158 B per entity (jecs: 312 B).- The memory of cached queries. A query of an archetype ECS keeps a list of archetypes; a cached query of mErCS over scattered matches keeps a list of its matches (the entity and its index in the value page), which keeps its loops fast over scattered matches. The arrays of the list have their exact size, and the first list of a query is built from the spans that the choice of its iteration mode found. A list of words or of one number per match would take less memory, but would change the iteration cost; those alternatives are not measured here.
- Queries over two large terms after more than a few changes of a term: a query re-checks the noted slots while that costs less than a pass, up to half of the words of the smallest term, and drops at once a slot that an unchanged required term does not have.
- Twenty small queries that share a changing tag: every query re-checks the changes of the tag (jecs moves the entity between archetypes once, at the change). The queries that saw the same versions of a record read its changes from the journal once, and each drops the slots that an unchanged required term does not have; a query whose smallest term has few words tests those words against the changed bits of each word, gathered once for all the queries, so that its cost does not grow with the number of changes.
- Inline queries built per call. A query shape is shared from its second request: the first request gets a light state of its own and only marks the shape, so a query requested once (an entity used as a term) keeps no shared state. A query that is not cached and whose smallest term lies in at most 64 words gathers its matches in one loop over those words before the loop of the caller, instead of a call of the span generator per match. The queries with a pair of an entity target are shared by shape as well and go with the target; the queries of a new caster stay slower, as their shape is new on every call.
world:eachandworld:childrencollect the members of the id at the start of the loop into a buffer from the module pool: records with at most 64 word keys, including emptied words, use sorted non-empty keys; larger records use the levels of their bitsets. The pool retains at most 16 buffers and 4 MiB of charged array storage, plus table overhead. A buffer larger than the budget is collected and allocated again on its next use.- Entities of several kinds created in turn: a kind lies in one slot of eight, so its values
sit in the hash parts of their pages and its queries keep match lists; jecs stores each kind
in an archetype of its own. A slot pool (
world:pool()) keeps a kind dense and makes it faster than jecs. - Deleting entities with many pairs of one relation: every pair record clears its bit (jecs removes the row of the entity from one archetype); the pairs of a relation are cleared in one inline loop.
- Sparse components in a large world: a component on one entity in 64 keeps, per entity, a
word of its bitset and a quarter of a value page of 256 slots, where jecs keeps a row of an
archetype. This is the cost of the page layout that
world:columnexposes; adding the components is faster than in jecs.
Query monitors
The group query monitors of bench/run.luau (bench/monitors.luau): jecs 0.11.0 with the
monitors of its addon modules/OB against query:monitor() of mErCS, 10 000 entities:
| Case | jecs 0.11.0 + OB | mErCS 1.3.0 | 1.3.0 / jecs |
|---|---|---|---|
| a tag of the query added and removed, per cycle (an entry and an exit) | 656 / 608 ns | 803 / 541 ns | 1.23× / 0.89× |
| members of the query deleted, per entity | 538 / 549 ns | 675 / 395 ns | 1.26× / 0.72× |
children moved to another parent, (ChildOf, *) monitored, per move | 512 / 428 ns | 738 / 453 ns | 1.44× / 1.06× |
The monitor measurements include both the underlying changes and listener dispatch. For comparison, a child moved without a monitor takes 433 / 252 ns in mErCS and 287 / 213 ns in jecs (1.51× / 1.18×).
A separate probe deletes entities with four components, with and without one OnRemove
hook. The median additional cost is 172 / 108 ns in mErCS
and 4.8 / 14.6 ns in jecs. Each sample subtracts two minima
of nine batches, so small differences in this probe are sensitive to timing noise. The hook of
mErCS runs inside a frame that the hooks it starts consult (clears and removals of the same
entity), which jecs does not keep.
Single operations
bench/run.luau, 131 072 entities. jecs has no query:each: its rows compare each with the
jecs for-in loop over the same world.
Entities
| Scenario | jecs 0.11.0 | mErCS 1.3.0 | 1.3.0 / jecs |
|---|---|---|---|
| create an entity | 182 / 162 ns | 43.3 / 28.6 ns | 0.24× / 0.18× |
| delete an entity with 4 components | 376 / 365 ns | 451 / 240 ns | 1.20× / 0.66× |
Components
| Scenario | jecs 0.11.0 | mErCS 1.3.0 | 1.3.0 / jecs |
|---|---|---|---|
| add a first component | 127 / 99.3 ns | 172 / 109 ns | 1.36× / 1.10× |
| set an existing component | 65 / 59.1 ns | 61.8 / 36.7 ns | 0.95× / 0.62× |
| remove a component | 185 / 165 ns | 118 / 59.7 ns | 0.64× / 0.36× |
| add when the entity has 5 | 366 / 285 ns | 127 / 61.8 ns | 0.35× / 0.22× |
| remove when the entity has 6 | 367 / 324 ns | 116 / 59 ns | 0.31× / 0.18× |
| add when the entity has 20 | 1.46 / 1.2 µs | 125 / 63.1 ns | 0.09× / 0.05× |
| remove when the entity has 21 | 1.47 / 1.27 µs | 116 / 59.4 ns | 0.08× / 0.05× |
| add when the entity has 40 | 2.75 / 2.36 µs | 123 / 60.2 ns | 0.04× / 0.03× |
| remove when the entity has 41 | 2.79 / 2.41 µs | 116 / 58.9 ns | 0.04× / 0.02× |
Tags
| Scenario | jecs 0.11.0 | mErCS 1.3.0 | 1.3.0 / jecs |
|---|---|---|---|
| add a tag | 337 / 272 ns | 95 / 52.7 ns | 0.28× / 0.19× |
| remove a tag | 336 / 305 ns | 109 / 64.2 ns | 0.32× / 0.21× |
| toggle a tag on 10 % of the entities per frame | 1.06 µs / 645 ns | 178 / 96.4 ns | 0.17× / 0.15× |
Access
| Scenario | jecs 0.11.0 | mErCS 1.3.0 | 1.3.0 / jecs |
|---|---|---|---|
get 1 id | 61 / 53.3 ns | 47.1 / 28.2 ns | 0.77× / 0.53× |
get 2 ids | 69.2 / 58.3 ns | 59.1 / 33.7 ns | 0.85× / 0.58× |
get 4 ids | 87.2 / 65.6 ns | 89.7 / 44.9 ns | 1.03× / 0.68× |
get 8 ids (jecs: at most 4) | — | 244 / 112 ns | — |
has 1 id | 59.5 / 41.4 ns | 51.4 / 31.7 ns | 0.86× / 0.76× |
has 4 ids | 73.9 / 47.6 ns | 101 / 44.9 ns | 1.37× / 0.94× |
has 8 ids (jecs: at most 4) | — | 186 / 72.5 ns | — |
Pairs
| Scenario | jecs 0.11.0 | mErCS 1.3.0 | 1.3.0 / jecs |
|---|---|---|---|
pair(R, T) | 20.7 / 9.07 ns | 22.9 / 8.95 ns | 1.10× / 0.99× |
| add a pair | 271 / 186 ns | 278 / 172 ns | 1.03× / 0.92× |
| set the value of an existing pair | 74.6 / 67.4 ns | 68.3 / 45.3 ns | 0.92× / 0.67× |
| remove a pair | 236 / 213 ns | 201 / 112 ns | 0.85× / 0.53× |
target (4 pairs) | 158 / 140 ns | 62.6 / 36.1 ns | 0.40× / 0.26× |
ChildOf children, per child (10 000 parents × 5) | 168 / 155 ns | 140 / 101 ns | 0.83× / 0.65× |
| add a pair with a target of its own | 6.7 / 6.35 µs | 3.16 / 2.85 µs | 0.47× / 0.45× |
delete a target: Remove (1000 × 100 sources, per source) | 182 / 182 ns | 154 / 83.2 ns | 0.85× / 0.46× |
delete a parent: ChildOf cascade (per child) | 303 / 304 ns | 401 / 238 ns | 1.33× / 0.78× |
Queries (per entity or match)
| Scenario | jecs 0.11.0 | mErCS 1.3.0 | 1.3.0 / jecs |
|---|---|---|---|
| for-in, 4 values, 8192 entities per archetype | 43.5 / 35.6 ns | 51.1 / 35.2 ns | 1.17× / 0.99× |
query:each, the same (ratio: against the jecs for-in) | — | 32.1 / 16.1 ns | 0.70× / 0.45× |
manual loop (spans / jecs archetypes), the same | 18.5 / 5.01 ns | 14.2 / 5.12 ns | 0.77× / 1.02× |
| for-in, 4 values, 256 entities per archetype | 47.8 / 38.6 ns | 54.5 / 36.7 ns | 1.14× / 0.95× |
query:each, the same (against the jecs for-in) | — | 35.3 / 17.6 ns | 0.73× / 0.48× |
| manual loop, the same | 20.4 / 7.2 ns | 17.4 / 6.51 ns | 0.85× / 0.90× |
| for-in, 4 values, 16 entities per archetype | 66.2 / 53.8 ns | 70.8 / 41.9 ns | 1.07× / 0.78× |
query:each, the same (against the jecs for-in) | — | 49.2 / 21.5 ns | 0.72× / 0.37× |
| manual loop, the same | 50.1 / 30.1 ns | 32 / 9.88 ns | 0.64× / 0.33× |
| for-in, 4 values, 1 entity per archetype | 262 / 172 ns | 76.6 / 46.1 ns | 0.29× / 0.27× |
query:each, the same (against the jecs for-in) | — | 54.3 / 26.6 ns | 0.19× / 0.15× |
| manual loop, the same | 175 / 101 ns | 37.5 / 14.5 ns | 0.21× / 0.14× |
| a query created and iterated once | 43.3 / 34.3 ns | 51.8 / 35.8 ns | 1.20× / 1.04× |
| for-in, 1 value of an entity with 4 | 33.1 / 29 ns | 40.1 / 29.2 ns | 1.21× / 1.01× |
for-in with without (half excluded) | 33.1 / 28.5 ns | 37.4 / 30.9 ns | 1.13× / 1.09× |
query:each, the same (against the jecs for-in) | — | 22 / 13.2 ns | 0.64× / 0.48× |
| for-in over a sparse match (1 %) | 39.4 / 33.7 ns | 65.9 / 57.3 ns | 1.67× / 1.70× |
query:each, the same (against the jecs for-in) | — | 45 / 30.8 ns | 1.01× / 0.87× |
| the first loop of a new query (2000 archetypes), per query | 121 / 122 µs | 421 / 339 ns | 0.003× / 0.003× |
| a small query created on every call (15 of 1000), per query | 1.33 / 1.21 µs | 1.21 / 1.06 µs | 0.91× / 0.88× |
| a query of a concrete pair created on every call (15 of 1000), per query | 1.39 / 1.31 µs | 1.05 µs / 881 ns | 0.76× / 0.67× |
| the same, nothing matches (0 of 1000) | 336 / 308 ns | 169 / 149 ns | 0.50× / 0.48× |
| an entity used as a term in 4 inline queries, then deleted, per entity | 1.93 / 1.76 µs | 5.82 / 5.27 µs | 3.01× / 3.00× |
| a query with 10 terms | 95.6 / 68.6 ns | 103 / 60.6 ns | 1.07× / 0.88× |
Batch operations (per match; jecs: a collect-and-change loop)
| Scenario | jecs 0.11.0 | mErCS 1.3.0 | 1.3.0 / jecs |
|---|---|---|---|
| add a tag to the matches (half of the entities) | 297 / 249 ns | 37.7 / 13.5 ns | 0.13× / 0.05× |
| set a component on the matches | 301 / 253 ns | 72.2 / 27.5 ns | 0.24× / 0.11× |
| remove a component from the matches | 284 / 269 ns | 38.6 / 12.8 ns | 0.14× / 0.05× |
| delete the matches | 441 / 436 ns | 487 / 246 ns | 1.11× / 0.56× |
| count the matches | 32.5 / 28.4 ns | 7.16 / 2.49 ns | 0.22× / 0.09× |
Churn (per cycle)
| Scenario | jecs 0.11.0 | mErCS 1.3.0 | 1.3.0 / jecs |
|---|---|---|---|
| spawn and despawn (10 components, 2 tags) | 4.15 / 3.86 µs | 2.43 / 1.19 µs | 0.59× / 0.31× |
a hierarchy of 1 + 5 ChildOf, spawned and deleted | 22 / 20.8 µs | 11 / 7.31 µs | 0.50× / 0.35× |
Memory and garbage
Bytes kept per unit after full GC. Equal interpreter/native medians are shown once:
| Kept per unit | jecs 0.11.0 | mErCS 1.3.0 |
|---|---|---|
| an empty entity | 240 B | 32 B |
| an entity with 4 components | 320 B | 131 B |
| an entity with 10 components and 5 tags | 417 B | 236 B |
a ChildOf child (10 000 parents × 5) | 726 B | 344 B |
| an entity with a tag of its own | 1630 B | 978 B |
| a pair with a target of its own | 2264 B | 1457 B |
| a component of 1000 on 100 entities each, per add | 398 B | 162 B |
| growth per hierarchy spawn / despawn cycle | 218 B | 0 B |
| an entity used in 4 inline queries, then deleted | 0 B | 1 B |
Net heap growth per warmed loop over 200 entities, measured across 1000 loops after full GC:
| Loop | jecs 0.11.0 | mErCS 1.3.0 |
|---|---|---|
| Inline two-component query | 921 B | 80 B |
| Stored query | 0 B | 0 B |
world:each | 288 B | 152 B |
A weak GC witness rejects a completed collection during the interval. This measures net heap
growth, not all allocator traffic; a partial incremental collection may not clear the witness.
The heap counter has 1 KiB resolution, or about 1 byte per loop in this batch; the 152 bytes of
world:each are its iterator, its buffer being reused.
Migrating from jecs
-
Point the jecs require at this module (
local jecs = require(path.to.mErCS)) and change the jecs calls that do not exist here (the type checker points at them):jecs mErCS jecs.World.new()jecs.world()jecs.wjecs.Wildcardjecs.bulk_insert(world, e, ids, values)world:set(e, ids[i], values[i])for each idjecs.bulk_remove(world, e, ids)world:remove(e, id)for each idjecs.new(world)world:entity()jecs.new_w_id(world, id)world:entity(), thenworld:add(e, id)jecs.new_low_id(world)world:entity(): a low id is not faster herefor e, a in query:iter() do,local step = query:iter()for e, a in query do(orquery:each(fn))jecs.is_tag(world, id)not world:has(id, jecs.Component)(for a pair: neither element has it)jecs.entity_index_try_get(world.entity_index, e)world:contains(e); the ids ofe:world:ids(e)world:cleanup(),query:fini()delete the call: there is nothing to release jecs.ArchetypeCreate,jecs.ArchetypeDeletedelete: there are no archetypes jabby needs the adapter instead of the plain module.
Then run the game: the world API, pairs, wildcards, hooks, signals, cleanup policies,
Name,jecs.component()/jecs.tag()/jecs.meta()and theECS_*helpers keep their meaning. A debug world,ecs.world(true), raises errors for dead entities and ids on every change while you migrate, and names an argument that is nil or not a number on every call (an id read from a table by a name that it does not have). -
Rewrite what reads archetypes: loops over
query:archetypes()withcolumns/columns_mapbecomequery:each(fn)(orquery:spans()withworld:column(id)for the hottest loops); hooks that useoldarchetyperead the entity withworld:get/world:has(the fourth argument of anOnChangehook or achangedlistener is the value that the change replaced, not an archetype). -
Remove most
:cached()calls: shared queries are cached already (see Coming from jecs). A query with an entity as a term, directly or as the target of a pair (query:with(caster),query(A, pair(ChildOf, parent))), shares a state per entity, up to 1024 shapes per world: for lookups over many live entities, a pair andworld:each(ecs.pair(Event, caster))need no query state (see Queries). ReplaceOB.monitor(query)of the addonmodules/OBwithquery:monitor(), and its observers with signals and a check of the query (Query monitors) or withworld:trackand the:added/:changed/:removedfilters. -
Replace "collect the matches, then change them" loops with batch operations (
query:add_all,set_all,remove_all,delete_all,count), and state flags stored as components with tags (Disabledhides entities from queries without removing anything). -
Code that depends on the iteration order of archetypes, or on the numbers of builtin ids after
Name(jecs.Restis 270 here), needs a look (see the differences above).