perf: hot-path optimizations across entity ops, relationships, and lifecycle (18 workloads +4-35% faster, 0 regressions)

[Pyseph]

Note

Authorship disclosure: these optimizations were researched, implemented, and benchmarked by Claude (Fable 5, Anthropic's model) running in Claude Code — including the failed experiments documented below. My role (@Pyseph) was direction, supervision, and independent verification: I ran every Studio benchmark round on real hardware and reviewed each round's results before the next began. Every commit carries a Co-Authored-By: Claude trailer. Flagging this up front so reviewers can calibrate scrutiny accordingly — though the work was held to the repo's own standard: nothing landed without surviving the full test suite, a >=80% win-rate A/B verdict, and a recompile confirmation.

Summary

Six self-contained performance commits to src/jecs.luau, developed and verified against this exact base commit (3087601). 18 benchmarked workloads get faster, 0 get slower, and behavior is bit-for-bit compatible — the full test suite (139 cases) passes after every individual commit, and luau-analyze stays clean throughout.

Final A/B numbers, measured in Roblox Studio under --!native --!optimize 2 (methodology below):

workload	faster by	won rounds
world:parent	+34.9%	100%
world:contains	+34.7%	100%
world:target	+32.8%	100%
remove a component from a 5-component entity	+24.8%	100%
world:delete (ChildOf child / plain 4-component)	+19.5% / +19.2%	100%
world:remove	+18.0%	100%
world:add (tag)	+16.4%	93%
world:children (16k parents × 4 children)	+15.0%	85%
world:add ChildOf (exclusive pair)	+14.4%	100%
add a 5th component to a 4-component entity	+14.0%	100%
world:has	+11.2%	90%
world:clear	+9.8%	100%
world:set (pair)	+8.9%	100%
world:get (4 comps / 1 comp)	+8.3% / +7.1%	97% / 82%
world:set (add / overwrite)	+6.2% / +4.2%	83% / 88%

Query iteration is deliberately untouched (byte-identical) — see "Failed experiments" for why that is a feature of this PR, not an omission.

Methodology

All numbers come from an A/B harness that loads the optimized copy and this base commit as two independent ModuleScripts and runs identical workloads against both, interleaved round-by-round with alternating order so GC/scheduler drift hits both sides equally. The reported time is the best-of-60-rounds (the run least disturbed by GC), and a result only counts as a win when the delta clears 1.5% and the optimized side wins ≥80% of paired rounds.

Two disciplines mattered more than expected:

• Per-build bias is real. Two independently compiled copies of byte-identical source showed stable ±2–3% deltas (occasionally more) from native code layout alone. Every claimed win was therefore confirmed across a forced recompile — a result that moves with the layout is an artifact, one that survives is real.
• Win-rate gates beat deltas. Allocation-heavy workloads (spawning, mass deletion) have best-of deltas that swing wildly with GC; the share-of-rounds-won is far more stable and is what separated real wins from noise.

Correctness was held to "bit-for-bit": beyond the test suite, the changes preserve pinned-but-obscure semantics — setting a value on a tag still errors after the tag was added (the frozen NULL_ARRAY write is the error mechanism), on_remove hooks may move the entity mid-remove and the operation re-reads record.archetype afterward, exclusive-pair replacement fires hooks on warm edge-cache hits, and generation arithmetic (including the wrap at 2^16) is value-identical for every input.

What each commit does

1. Inline hot-path helper calls in entity operations. Luau's -O2 inliner only handles simple local functions, so entity_index_try_get_unsafe, fetch, the new_entity/archetype_append/inner_archetype_move chain, and the pair-math helpers were real call frames on every get/has/set/add/remove — frequently costing more than the work they wrapped. The fused move also removes a duplicated dst_entities store the old chain made.
2. Per-transition move plans + target/parent inlining. Archetype moves resolved every column's destination through columns_map per entity; the first move along a (from → to) transition now caches a column-mapping plan that later moves replay with array reads. A gate keeps sources with <3 columns on the direct loop — without it, single-column removes regressed (measured, see below). world_parent becomes a specialized reader with the ChildOf wildcard id precomputed per world.
3. world_delete/world_targets inlining. The delete path dropped ~6 call frames, including the whole archetype_delete body and a value-identical unified form of ECS_GENERATION_INC.
4. world_contains inlining + each/children specialization. contains was three calls deep for a boolean.
5. Delete probe-skip + counts-lookup elimination + clear inlining. The biggest single idea, adapted from flecs: ordinary entities are never used as a component id, pair relation, or pair target, so world_delete's three wildcard component_index probes always miss for them. id_record_create (the only producer of such records) now marks referenced entities in world.entity_used_as; deleting unmarked entities skips the probes and pair arithmetic entirely, and the mark is cleared on delete so recycled ids start clean. Stale marks are safe (they just fall back to probe-and-miss); missing marks cannot occur. Separately, records[aid] exists iff counts[aid] ≥ 1, so target/parent's index-0 path drops a redundant hash lookup — this took target from +14.5% to +32.8%.
6. Fused liveness check (record.entity). Handle validation drops from a dependent two-load chain (record.dense → dense_array[dense] → compare) to a single field compare, maintained at every alive-making site. This lifted every operation a further +2–12% over commit 5.

Mistakes made and lessons learned

These cost real time and are worth recording for anyone optimizing this codebase later:

• Query iterator "improvements" measure slower under native codegen. Restructuring the per-entity next() closures to read the boxed row-counter upvalue once instead of three times (and to fold column reads into the return expression) looks strictly better in bytecode terms — and consistently measured slower for high arities (the 8-component case lost 100% of rounds). Native codegen schedules the original's up-front column loads better than the "cleverer" shape. The iterators in this PR are byte-identical to base because every alternative was tried and lost.
• Archetype list order affects iteration speed. Swapping query_archetypes from hash-walking idr.records to scanning the (cheaper) idr.cache array changed the order of compatible_archetypes — and cached-query iteration regressed 7% while wildcard queries regressed ~20%. The scan was never the cost; the order was. Reverted. (The table.create presizing in commit 5 keeps hash order exactly for this reason.)
• Cache fetches have to amortize. The move-plan cache as first written regressed single-column removes from +18% to +3.6% because the plan fetch (~4 reads) costs more than the one lookup it saves. The <3-column gate in commit 2 is load-bearing, not decoration.
• Table literal key order is a performance interface. Adding record.entity as the first constructor key reproducibly regressed the 4-component get path by 3–5% across recompiles — the insertion order shifted which keys win the record table's internal hash slots. Appending it last fixed it. If you add fields to hot record-shaped tables, append them.
• A microbenchmark can lie in both directions. A CLI harness (luau 0.724, --codegen) predicted Studio results case-for-case for five rounds, then showed a phantom −3.4% on one case in round 6 that Studio measured as +8.3%. Conversely, byte-identical code routinely read ±3% in either harness. Nothing here was landed on a single environment's say-so.

What was deliberately not done

• SoA entity records (parallel dense/row/archetype arrays instead of per-entity tables) is the largest remaining win — it would make world:entity() allocation-free — but it breaks the exported Record/jecs.record API shape, so it belongs in a design discussion rather than this PR.
• Iterator closure elimination in targets/each: every variant breaks the public directly-callable () -> Id contract or nested iteration.
• Spawn-path allocation: the per-entity record table is inherent to the current API and the workload is GC-jitter-dominated anyway.

Test plan

• luau test/tests.luau — 139/139 after each commit (also run with -O2).
• luau-analyze src/jecs.luau — clean after each commit.
• Studio A/B benchmark suite (29 workloads spanning reads, writes, archetype moves, relationships, hierarchy iteration, lifecycle): 18 FASTER / 0 SLOWER at the tip; the remainder are byte-identical code paths or documented GC-jitter cases reading as noise.

The benchmark harness itself (runner with interleaved best-of/win-rate verdicts plus the workload suite) lives in a separate repo and can be contributed too if there's interest.

🤖 Generated with Claude Code

[Ukendio]

To temper some expectations, I will not be accepting this PR as-is, however there are still many things that can be learned here that I think is valuable. We will keep this open to make it easy to index this in the future and iterate on the things that can be improved in jecs.

Some notes:

1. This seems overly eager at inlining things that is already done by luau. For simplicity sake, we will not be doing that.
2. The cached column pointers (move plans) present an interesting optimization but the problem is that the cost vs benefit has yet to be proven in real games outside of limited benchmarks that do not really test explosion of fragmentation and many different edges that archetypes. This also makes things more difficult to reclaim archetypes in the future if we want to do that as we generally do not like working with pointers too often. That said it is an interesting optimization we should at least give the benefit of the doubt to.
3. The entity_used_as map fragments the way we want to think of IDs which is that most are homogenously accessed through the component_index. Specializing those used for pairs is pretty counter to our goals.
4. I find the expansion of putting the entity in the record to be interesting, and generally a non-issue outside of expanding memory usage of entity records by 25% but that is ultimately insignificant. However, it does feel a bit tacky which I need to grumble on to articulate further.