Skip to main content

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​

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.0mErCS 1.3.0
add / remove a componentmoves the entity, copies all its columns: O(components)sets a bit and a value: O(1)
new combination of componentscreates an archetype (kept until world:cleanup())nothing to create
pair with many targetsan archetype per targetone small record per pair, freed when unused (in batches) or with its target
ids per get / has call48, any number with get_list / has_all
memory per entity with 4 components320 B131 B
deep hierarchiesthe cascade recurses: stack overflow at about 6000 levelsany 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 ids ArchetypeCreate / ArchetypeDelete do not exist (there is nothing for them to do), hooks do not get an oldarchetype argument: the fourth argument of an OnChange hook and of a world:changed listener 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() and is_tag are 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 / has take up to 8 ids positionally (jecs: 4).
  • The iteration order is ascending by entity slot, not by archetype.
  • Builtin ids after Name have other numbers: Exclusive is 268 (jecs: 270), Disabled (not in jecs) 269, Rest 270 (jecs: 271).
  • The jecs addon modules/OB reads archetypes and does not work here. Its monitors are query:monitor(), which returns the same added / 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:contains is 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:each and world:children return 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 Component trait 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, and ecs.pair(ecs.Wildcard, T) every pair with the target T; add and set raise 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, and world: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 without nil; when there is no value, an error that names the entity and the id instead of nil.
  • Change tracking by ticks: world:track, world:tick, the :added / :changed / :removed filters, and new entities with world:track_created and :created.
  • ecs.Disabled: entities hidden from queries without removing their components.
  • Slot pools: world:pool() and pool: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() with world: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/OB calls back for every add or value change of an id of a query on an entity that matches it. In mErCS a signal with query:has does that; the monitors of the addon are query:monitor().
  • Archetypes as an API: query:archetypes() with the columns of each archetype, the ids ArchetypeCreate / ArchetypeDelete, and the tools that read them (the entity visualiser of jecs, for one). mErCS gives the value pages of a query through query:spans() and world: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.

CasejecsmErCSmErCS / jecs
Cached queries over scattered entities, memory per query5803 B263 KiB46.37×
Sparse components: 8 on 1 entity in 64, memory per entity170 B660 B3.90×
Eight kinds created in turn, 3 values readrows of each kind stay togethervalues follow slot layoutfor-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 relationremove one archetype rowclear the bit of each pair record2.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:each against 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, Run toggled 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 / queriesjecs 0.11.0mErCS 1.3.01.3.0 / jecs
interpreter, inline queries6.1 ms2.54 ms0.42×
interpreter, cached queries5.75 ms2.54 ms0.44×
native, inline queries5.31 ms1.76 ms0.33×
native, cached queries4.94 ms1.78 ms0.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:

ModeFramejecs 0.11.0jecs 0.11.0 + cleanup every 600 framesmErCS 1.3.0
interpreter1000+3.57 MiB, 0.222 ms+3.60 MiB, 0.207 ms+0.33 MiB, 0.094 ms
interpreter3000+8.98 MiB, 0.223 ms+8.80 MiB, 0.219 ms+0.32 MiB, 0.094 ms
interpreter5000+15.38 MiB, 0.221 ms+15.66 MiB, 0.223 ms+0.32 MiB, 0.093 ms
native1000+3.57 MiB, 0.193 ms+3.60 MiB, 0.188 ms+0.33 MiB, 0.064 ms
native3000+8.98 MiB, 0.203 ms+8.80 MiB, 0.199 ms+0.32 MiB, 0.062 ms
native5000+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:

Casejecs 0.11.0mErCS 1.3.01.3.0 / jecs
Scattered after recycling128 / 109 µs93 / 66.1 µs0.73× / 0.61×
Churn on a queried tag, 1 toggle per pass346 / 302 µs297 / 214 µs0.86× / 0.71×
Churn on a queried tag, 100 toggles per pass259 / 227 µs277 / 196 µs1.07× / 0.86×
Read 4 components1.92 / 1.5 ms1.35 ms / 679 µs0.70× / 0.45×
(*, T) with churn804 / 712 µs543 / 335 µs0.68× / 0.47×
Usually empty68.9 / 62.7 ns43.3 / 28.3 ns0.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 with Velocity; the query of both without Stunned, Stunned toggled 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 of Health and (*, T). The query reads the values of (*, T) from a mirror (see The strengths of jecs).
  • Usually empty: 100 000 entities, each with Stunned or Invulnerable; 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:

Passjecs 0.11.0mErCS 1.3.01.3.0 / jecsmErCS 1.3.0, poolpool / jecs
Alive creatures, nothing changed6.5 / 5.95 µs5.76 / 4.31 µs0.89× / 0.72×6.94 / 4.16 µs1.07× / 0.70×
Alive creatures, Dead added to one and removed7.39 / 6.81 µs7.53 / 5.46 µs1.02× / 0.80×7.43 / 4.42 µs1.00× / 0.65×
Running creatures, Run toggled on one3.57 / 3.33 µs4.88 / 3.62 µs1.37× / 1.09×2.93 / 1.89 µs0.82× / 0.57×
A tag added to one creature, a pass, removed, a pass1.27 / 1.18 µs2.09 / 1.42 µs1.64× / 1.20×1.71 / 1.05 µs1.34× / 0.89×
A tag nobody has69.8 / 65.1 ns45.1 / 30.1 ns0.65× / 0.46×45.5 / 30.5 ns0.65× / 0.47×
All with Model (creatures and corpses)22.5 / 20.3 µs20 / 14.9 µs0.89× / 0.74×15.9 / 9.13 µs0.71× / 0.45×
A skill changes state, 10 queries over skills in Cast141 / 128 µs112 / 71.7 µs0.79× / 0.56×118 / 71.6 µs0.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 queriesjecs 0.11.0mErCS 1.3.01.3.0 / jecs
10 skills change state53.3 / 46.7 µs40.7 / 24.7 µs0.76× / 0.53×
200 skills change state161 / 142 µs165 / 97.8 µs1.03× / 0.69×
800 skills change state498 / 435 µs369 / 221 µs0.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:

#Casejecs 0.11.0mErCS 1.3.01.3.0 / jecs
1(*, T) values, 32 data relations, a pass over 20 000759 / 623 µs552 / 318 µs0.73× / 0.51×
2(R, *) values, 8 targets, a pass over 20 000761 / 620 µs546 / 317 µs0.72× / 0.51×
315 cached queries over scattered entities, per query301 / 253 µs754 / 334 µs2.51× / 1.32×
the same, memory per query5803 B263 KiB46.38×
4usually empty, 20 swaps per pass (100 000 entities)17 / 16.3 µs14.1 / 7.62 µs0.83× / 0.47×
5 queries, 100 matches each, 40 toggles per frame52.2 / 47.8 µs33.6 / 17.8 µs0.64× / 0.37×
520 small queries, a shared tag toggled on 30 per frame21.8 / 18.1 µs22.7 / 14.9 µs1.04× / 0.82×
6query(A, pair(ChildOf, parent)) per parent (1000 × 5)968 / 876 ns594 / 498 ns0.61× / 0.57×
2 inline queries per new caster1.91 / 1.89 µs4.43 / 3.74 µs2.31× / 1.98×
the same, memory per caster0 B377 Binf×
7world:each over 100 000, per entity28.6 / 25 ns31.7 / 24.8 ns1.11× / 0.99×
world:children, 1000 children, per child29 / 25.4 ns32.9 / 25.8 ns1.14× / 1.02×
88 kinds in turn, 3 values, for-in, per match42.6 / 34 ns87.7 / 83 ns2.06× / 2.44×
the same, each42.6 / 34 ns64.8 / 54.7 ns1.52× / 1.61×
the same, each, the kind from a slot pool42.6 / 34 ns37.3 / 21.2 ns0.88× / 0.62×
9delete entities with 100 targets, per pair29.8 / 30.3 ns64.8 / 46.4 ns2.18× / 1.53×
108 components on 1 entity in 64 of 131 072, memory per entity170 B661 B3.90×
the same, time per entity2.77 / 2.15 µs2.49 / 1.56 µs0.90× / 0.73×
  1. (*, T) values. jecs reads the column of the first pair of T in 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 of T): the world of this case with its query takes 255 B per entity (jecs: 315 B).
  2. (R, *) values: the same mirror; the world with its query takes 158 B per entity (jecs: 312 B).
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. world:each and world:children collect 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.
  8. 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.
  9. 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.
  10. 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:column exposes; 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:

Casejecs 0.11.0 + OBmErCS 1.3.01.3.0 / jecs
a tag of the query added and removed, per cycle (an entry and an exit)656 / 608 ns803 / 541 ns1.23× / 0.89×
members of the query deleted, per entity538 / 549 ns675 / 395 ns1.26× / 0.72×
children moved to another parent, (ChildOf, *) monitored, per move512 / 428 ns738 / 453 ns1.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​

Scenariojecs 0.11.0mErCS 1.3.01.3.0 / jecs
create an entity182 / 162 ns43.3 / 28.6 ns0.24× / 0.18×
delete an entity with 4 components376 / 365 ns451 / 240 ns1.20× / 0.66×

Components​

Scenariojecs 0.11.0mErCS 1.3.01.3.0 / jecs
add a first component127 / 99.3 ns172 / 109 ns1.36× / 1.10×
set an existing component65 / 59.1 ns61.8 / 36.7 ns0.95× / 0.62×
remove a component185 / 165 ns118 / 59.7 ns0.64× / 0.36×
add when the entity has 5366 / 285 ns127 / 61.8 ns0.35× / 0.22×
remove when the entity has 6367 / 324 ns116 / 59 ns0.31× / 0.18×
add when the entity has 201.46 / 1.2 µs125 / 63.1 ns0.09× / 0.05×
remove when the entity has 211.47 / 1.27 µs116 / 59.4 ns0.08× / 0.05×
add when the entity has 402.75 / 2.36 µs123 / 60.2 ns0.04× / 0.03×
remove when the entity has 412.79 / 2.41 µs116 / 58.9 ns0.04× / 0.02×

Tags​

Scenariojecs 0.11.0mErCS 1.3.01.3.0 / jecs
add a tag337 / 272 ns95 / 52.7 ns0.28× / 0.19×
remove a tag336 / 305 ns109 / 64.2 ns0.32× / 0.21×
toggle a tag on 10 % of the entities per frame1.06 µs / 645 ns178 / 96.4 ns0.17× / 0.15×

Access​

Scenariojecs 0.11.0mErCS 1.3.01.3.0 / jecs
get 1 id61 / 53.3 ns47.1 / 28.2 ns0.77× / 0.53×
get 2 ids69.2 / 58.3 ns59.1 / 33.7 ns0.85× / 0.58×
get 4 ids87.2 / 65.6 ns89.7 / 44.9 ns1.03× / 0.68×
get 8 ids (jecs: at most 4)—244 / 112 ns—
has 1 id59.5 / 41.4 ns51.4 / 31.7 ns0.86× / 0.76×
has 4 ids73.9 / 47.6 ns101 / 44.9 ns1.37× / 0.94×
has 8 ids (jecs: at most 4)—186 / 72.5 ns—

Pairs​

Scenariojecs 0.11.0mErCS 1.3.01.3.0 / jecs
pair(R, T)20.7 / 9.07 ns22.9 / 8.95 ns1.10× / 0.99×
add a pair271 / 186 ns278 / 172 ns1.03× / 0.92×
set the value of an existing pair74.6 / 67.4 ns68.3 / 45.3 ns0.92× / 0.67×
remove a pair236 / 213 ns201 / 112 ns0.85× / 0.53×
target (4 pairs)158 / 140 ns62.6 / 36.1 ns0.40× / 0.26×
ChildOf children, per child (10 000 parents × 5)168 / 155 ns140 / 101 ns0.83× / 0.65×
add a pair with a target of its own6.7 / 6.35 µs3.16 / 2.85 µs0.47× / 0.45×
delete a target: Remove (1000 × 100 sources, per source)182 / 182 ns154 / 83.2 ns0.85× / 0.46×
delete a parent: ChildOf cascade (per child)303 / 304 ns401 / 238 ns1.33× / 0.78×

Queries (per entity or match)​

Scenariojecs 0.11.0mErCS 1.3.01.3.0 / jecs
for-in, 4 values, 8192 entities per archetype43.5 / 35.6 ns51.1 / 35.2 ns1.17× / 0.99×
query:each, the same (ratio: against the jecs for-in)—32.1 / 16.1 ns0.70× / 0.45×
manual loop (spans / jecs archetypes), the same18.5 / 5.01 ns14.2 / 5.12 ns0.77× / 1.02×
for-in, 4 values, 256 entities per archetype47.8 / 38.6 ns54.5 / 36.7 ns1.14× / 0.95×
query:each, the same (against the jecs for-in)—35.3 / 17.6 ns0.73× / 0.48×
manual loop, the same20.4 / 7.2 ns17.4 / 6.51 ns0.85× / 0.90×
for-in, 4 values, 16 entities per archetype66.2 / 53.8 ns70.8 / 41.9 ns1.07× / 0.78×
query:each, the same (against the jecs for-in)—49.2 / 21.5 ns0.72× / 0.37×
manual loop, the same50.1 / 30.1 ns32 / 9.88 ns0.64× / 0.33×
for-in, 4 values, 1 entity per archetype262 / 172 ns76.6 / 46.1 ns0.29× / 0.27×
query:each, the same (against the jecs for-in)—54.3 / 26.6 ns0.19× / 0.15×
manual loop, the same175 / 101 ns37.5 / 14.5 ns0.21× / 0.14×
a query created and iterated once43.3 / 34.3 ns51.8 / 35.8 ns1.20× / 1.04×
for-in, 1 value of an entity with 433.1 / 29 ns40.1 / 29.2 ns1.21× / 1.01×
for-in with without (half excluded)33.1 / 28.5 ns37.4 / 30.9 ns1.13× / 1.09×
query:each, the same (against the jecs for-in)—22 / 13.2 ns0.64× / 0.48×
for-in over a sparse match (1 %)39.4 / 33.7 ns65.9 / 57.3 ns1.67× / 1.70×
query:each, the same (against the jecs for-in)—45 / 30.8 ns1.01× / 0.87×
the first loop of a new query (2000 archetypes), per query121 / 122 µs421 / 339 ns0.003× / 0.003×
a small query created on every call (15 of 1000), per query1.33 / 1.21 µs1.21 / 1.06 µs0.91× / 0.88×
a query of a concrete pair created on every call (15 of 1000), per query1.39 / 1.31 µs1.05 µs / 881 ns0.76× / 0.67×
the same, nothing matches (0 of 1000)336 / 308 ns169 / 149 ns0.50× / 0.48×
an entity used as a term in 4 inline queries, then deleted, per entity1.93 / 1.76 µs5.82 / 5.27 µs3.01× / 3.00×
a query with 10 terms95.6 / 68.6 ns103 / 60.6 ns1.07× / 0.88×

Batch operations (per match; jecs: a collect-and-change loop)​

Scenariojecs 0.11.0mErCS 1.3.01.3.0 / jecs
add a tag to the matches (half of the entities)297 / 249 ns37.7 / 13.5 ns0.13× / 0.05×
set a component on the matches301 / 253 ns72.2 / 27.5 ns0.24× / 0.11×
remove a component from the matches284 / 269 ns38.6 / 12.8 ns0.14× / 0.05×
delete the matches441 / 436 ns487 / 246 ns1.11× / 0.56×
count the matches32.5 / 28.4 ns7.16 / 2.49 ns0.22× / 0.09×

Churn (per cycle)​

Scenariojecs 0.11.0mErCS 1.3.01.3.0 / jecs
spawn and despawn (10 components, 2 tags)4.15 / 3.86 µs2.43 / 1.19 µs0.59× / 0.31×
a hierarchy of 1 + 5 ChildOf, spawned and deleted22 / 20.8 µs11 / 7.31 µs0.50× / 0.35×

Memory and garbage​

Bytes kept per unit after full GC. Equal interpreter/native medians are shown once:

Kept per unitjecs 0.11.0mErCS 1.3.0
an empty entity240 B32 B
an entity with 4 components320 B131 B
an entity with 10 components and 5 tags417 B236 B
a ChildOf child (10 000 parents × 5)726 B344 B
an entity with a tag of its own1630 B978 B
a pair with a target of its own2264 B1457 B
a component of 1000 on 100 entities each, per add398 B162 B
growth per hierarchy spawn / despawn cycle218 B0 B
an entity used in 4 inline queries, then deleted0 B1 B

Net heap growth per warmed loop over 200 entities, measured across 1000 loops after full GC:

Loopjecs 0.11.0mErCS 1.3.0
Inline two-component query921 B80 B
Stored query0 B0 B
world:each288 B152 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​

  1. 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):

    jecsmErCS
    jecs.World.new()jecs.world()
    jecs.wjecs.Wildcard
    jecs.bulk_insert(world, e, ids, values)world:set(e, ids[i], values[i]) for each id
    jecs.bulk_remove(world, e, ids)world:remove(e, id) for each id
    jecs.new(world)world:entity()
    jecs.new_w_id(world, id)world:entity(), then world:add(e, id)
    jecs.new_low_id(world)world:entity(): a low id is not faster here
    for e, a in query:iter() do, local step = query:iter()for e, a in query do (or query: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 of e: 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 the ECS_* 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).

  2. Rewrite what reads archetypes: loops over query:archetypes() with columns / columns_map become query:each(fn) (or query:spans() with world:column(id) for the hottest loops); hooks that use oldarchetype read the entity with world:get / world:has (the fourth argument of an OnChange hook or a changed listener is the value that the change replaced, not an archetype).

  3. 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 and world:each(ecs.pair(Event, caster)) need no query state (see Queries). Replace OB.monitor(query) of the addon modules/OB with query:monitor(), and its observers with signals and a check of the query (Query monitors) or with world:track and the :added / :changed / :removed filters.

  4. 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 (Disabled hides entities from queries without removing anything).

  5. Code that depends on the iteration order of archetypes, or on the numbers of builtin ids after Name (jecs.Rest is 270 here), needs a look (see the differences above).