Skip to main content

mErCS and ecr

How mErCS 1.3.0 differs from ecr 0.9.0, a sparse-set ECS for Luau inspired by EnTT: the design, the behaviour, the four basic benchmarks of jecs measured in both, and how to move code over.

Contents​

Design​

ecr keeps a pool per component type: a sparse array from the entity to an index, and dense arrays of the entities and of the values. Adding or removing a component is a swap inside one pool; a view walks the smallest pool of its components and checks the others for each entity; a group (registry:group(A, B)) reorders the pools of its components so that the entities that have all of them come first, in the same order, and its loop reads one dense range. A component belongs to at most one group.

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 reads the values of the matches by slot.

ecr 0.9.0mErCS 1.3.0
storage of a componenta pool: sparse array, dense entities, dense valuesa bitset and value pages by entity slot
add / remove a componenta swap inside the pool: O(1)a bit and a value: O(1)
a loop over several componentsthe smallest pool, the others checked per entity; a group: one dense rangethe bitsets ANDed 32 entities at a time
entities alive at onceat most 65 5352^24 slots
component typesdeclared before the registry, shared by all registriesworld:component() per world, or ecs.component() before the worlds
relationshipsnone (an entity id may be stored as a value)pairs, wildcards, ChildOf, Exclusive, cleanup policies

Differences in behaviour​

  • registry:get raises an error when the entity lacks the component (try_get returns nil); world:get returns nil.
  • A component value cannot be nil in ecr; world:set(e, C, nil) keeps the component without a value in mErCS, and world:add(e, C) adds it without one.
  • The listeners of ecr (on_add, on_change, on_remove) cannot change the registry or disconnect other listeners. The hooks and listeners of mErCS may change the world, other entities and the entity of their event; every addition and removal is notified once (see Hooks and signals).
  • During a loop over a view or a group, adding or removing components of other entities may invalidate the iterator in ecr. A query loop of mErCS may change the current entity and others (see Queries).
  • An observer of ecr (registry:track) returns the entities whose components were added or changed since its previous loop, and clears itself after the loop. mErCS tracks additions, changes and removals per tick (world:track, world:tick, the filters :added, :changed, :removed, and :created for new entities), and a query monitor reports the entities that enter or leave a query.
  • registry:clear(C) removes a component from every entity, registry:clear() destroys every entity; world:remove_all(C) removes an id from every entity, and the batch operations of a query (add_all, set_all, remove_all, delete_all, toggle_all) change its matches.
  • A component type of ecr is created before the registry and is the same in every registry; the ids of mErCS belong to their world, and pre-registered components (ecs.component()) are the same ids in every world made after them.
  • ecr has handles (registry:handle), a context entity, queues (ecr.queue) and helpers that pack ids into buffers; mErCS has none of them.

Beyond ecr​

  • Relationships: pairs (R, T) with data, wildcards (R, *) and (*, T), ChildOf with its cascade, Exclusive, cleanup policies (OnDelete, OnDeleteTarget).
  • Hooks and listeners that may change the world, query monitors.
  • Change tracking by ticks, with the history of the last 7 ticks for systems that run less often.
  • Batch operations on the matches of a query, world:toggle, OR terms (query:any), ecs.Disabled.
  • Slot pools (world:pool()), explicit ids and id ranges for networked worlds (world:entity(id), world:range).
  • The API of jecs: code written for jecs, its test suite and the jabby debugger work with mErCS (see jecs).

When ecr is the better choice​

  • A loop over a fixed set of components that a group serves: the group keeps the members in one dense range of every pool, which is the layout a loop reads fastest.
  • Code built on EnTT idioms: registries, views, groups, handles, observers, queues.
  • Networking that sends entity ids in buffers with the helpers of ecr.
  • Worlds that never need relationships, hooks that change the world or change tracking by ticks.

Performance​

The four basic benchmarks that jecs ships with, in the luau CLI (bench/basic.luau, Luau 0.740, measured on 2026-11-07): every library in a process of its own, five times in each mode, the order of the libraries rotated; a case makes 300 calls, and a cell is the median of the five medians of a call. Cells read "interpreter / native": -O2 / -O2 --codegen. The ratio is the time of mErCS divided by that of ecr; lower is better.

Benchmarkecr 0.9.0mErCS 1.3.0jecs 0.11.0mErCS / ecr
spawn: 1000 entities with 4 components874 / 373 µs667 / 406 µs867 / 733 µs0.76× / 1.09×
despawn: 1000 entities with 4 components and a tag896 / 353 µs496 / 256 µs376 / 380 µs0.55× / 0.73×
insertion: 8 components into 500 entities645 / 308 µs692 / 439 µs930 / 814 µs1.07× / 1.43×
query: 10 passes of a 4-component query over 4096 entities1.76 / 1.58 ms118 / 107 µs107 / 90.8 µs0.07× / 0.07×
the same, query:each—61.8 / 35.3 µs—0.04× / 0.02×
  • In native code ecr makes entities and gives them components faster: a component added is an append to the dense arrays of its pool, where mErCS sets a bit, a value in a page and the signature of the entity.
  • mErCS deletes faster, and its query takes a fifteenth of the time of an ecr view: a view walks the smallest pool and checks the other pools for each of its entities, where mErCS ANDs the bitsets 32 entities at a time.

The complete measurements include the ranges and the raw samples. The same four benchmarks in Roblox Studio are on Benchmarker. There ecr runs as bytecode: Roblox compiles a script to native code only when it has the --!native comment, which the module of ecr 0.9.0 does not have and those of jecs and mErCS do; the CLI compiles all three with --codegen.

Migrating from ecr​

ecrmErCS
ecr.registry()ecs.world()
local Health = ecr.component<<number>>()local Health = world:component() :: ecs.Component<number> (or ecs.component() before the worlds)
local Stunned = ecr.tag()local Stunned = world:entity(): any entity is a tag
registry:create(), registry:create(id)world:entity(), world:entity(id)
registry:destroy(id)world:delete(id)
registry:contains(id)world:contains(id)
registry:set(id, C, value)world:set(id, C, value)
registry:add(id, C) (with a constructor)world:set(id, C, constructor()); a tag: world:add(id, Tag)
registry:patch(id, C, fn)world:set(id, C, fn(world:get(id, C)))
registry:has(id, A, B)world:has(id, A, B) (up to 8 ids; world:has_all for more)
registry:get(id, A, B), registry:try_get(id, C)world:get(id, A, B), world:get(id, C): nil for a missing component
registry:remove(id, A, B)world:remove(id, A), world:remove(id, B)
registry:clear(C)world:remove_all(C)
registry:has_none(id)#world:ids(id) == 0
registry:view(A, B):exclude(C)world:query(A, B):without(C)
#registry:view(A)world:query(A):count()
registry:group(A, B)world:query(A, B): a query is shared and keeps its matches
registry:track(A) (an observer)world:track(A) once, world:query(A):added(A) / :changed(A), world:tick() every frame
registry:on_add(C):connect(fn)world:added(C, fn); on_change: world:changed, on_remove: world:removed
registry:find(C, value)a loop over world:query(C)
registry:storage(C)world:column(C) with query:spans() for the hottest loops
ecr.name(components)world:set(C, ecs.Name, "Health")

The listeners of mErCS run after the change for additions and before it for removals, like those of ecr; they may change the world, so the work that ecr defers out of a listener (into a queue or a later system) may stay in it.