Concept Report: Flecs Semantics on Top of Koota¶

Status: draft v2, 2026-10-30

1. Summary¶

Recommendation: Depend on koota from npm, pinned to an exact version. Build the missing flecs features (scheduler, prefabs, relation traits/traversal, serialization, devtools) as small, independent @workspace/ecs-* packages that use only koota's public API. Specify each extension spec-first, using the flecs manuals and tests. Upstream generic improvements to koota when they fit its scope. Demos are React (+ react-three-fiber where useful) apps built on koota + extensions.

Why we switched from v1 to v2:

• Production-ready today. Koota already covers about 60% of the flecs feature surface we need, with tests, docs, and an active pmndrs maintainer team.
• React / R3F fit. Koota comes from pmndrs, the same collective as react-three-fiber, drei, and zustand. Its React hooks (useQuery, useTrait, useWorld, …) are its core strength.
• Focus. Our effort goes into the learning value (flecs concepts) and the demos instead of re-implementing storage and queries.
• Fallback. The v1 spec-driven process is kept, but applied to extensions instead of a full core.

Updated constraints:

2. Evaluation of the Original Plan ("Custom Bindings")¶

"Language bindings" for flecs (C#, Rust, Zig, Lua) all wrap the C core through native FFI. TypeScript has no native FFI in the browser, so a TS binding means compiling flecs to WebAssembly (emscripten or wasi-sdk) and writing a TS layer over the exported C API.

Weaknesses¶

1. Toolchain cost. C + emscripten builds, debugging across the WASM boundary, and keeping up with upstream flecs releases. The team does not want this.
2. Boundary overhead. Components live in WASM linear memory. JS systems have two choices: cross the boundary for every entity (slow), or map columns as typed-array views (fast, but limited to POD/numeric data, and the views break when memory grows).
3. Component data model mismatch. Idiomatic TS components are objects, strings, and arrays. Flecs stores raw bytes described by its meta addon. Strings, nested objects, and references need manual marshalling or a side-table on the JS side, which partly defeats the purpose.
4. Lifetimes and GC. Closures registered as systems/observers, plus JS-side handles, need explicit cleanup (FinalizationRegistry is not deterministic).
5. Multithreading. Running the flecs scheduler with threads in WASM requires pthreads + SharedArrayBuffer + COOP/COEP headers, which makes Node/Bun/Deno/browser deployment harder.
6. Low learning value. Most of the effort goes into FFI plumbing, not ECS concepts.
7. No existing reference. Flecs lists no maintained JS/TS binding, so there is nothing to build on. We would be first and alone.

When bindings would make sense¶

• You need the actual flecs runtime: Explorer/REST compatibility, Flecs Script, native-level performance with millions of entities.
• Most logic runs in C/WASM and TS mainly orchestrates and renders.

Neither applies here. Conclusion: not recommended.

3. Landscape: TypeScript ECS Libraries vs. flecs¶

The sources are in reference/ (koota 0.6.6, bitECS 0.4.0, becsy 0.16.1, miniplex 2.0, flecs 4.1).

Takeaways

• koota is the only candidate that combines relations, change detection, observers, active maintenance, and React. It is the best foundation for React/R3F apps.
• bitECS has the closest feature overlap with flecs and the best serializers. But its pair-per-bit design scales poorly with many relation targets, it has no React integration, and MPL-2.0 adds friction to forking. Use it for inspiration only (serializers, Cascade, relation-trait API).
• becsy has the best scheduler and change tracking, but fixed capacities, no relations, and threading that was never delivered. Use it for inspiration only (entitlements, before/after ordering).
• miniplex is a dormant project. Use it for inspiration only (declarative <Entity>/<Component> JSX with ref capture for R3F objects).

4. Koota vs. flecs: Gap Analysis¶

Koota's known limits that we accept:

• At most 16 worlds, ~1M entities per world, and an 8-bit generation (a stale handle can match again after 256 reuses of the same slot).
• It patches Number.prototype (entity.get() etc.).
• It uses new Function for accessors, so a strict CSP needs unsafe-eval.
• Destroying entities and non-exclusive relations scale linearly in places.
• It is pre-1.0. Deprecations are scheduled for 0.7.0.

5. Options¶

Recommendation: Option C.

• Revisit B only if hard requirements (threading, >16 worlds, CSP without unsafe-eval) come back.
• Avoid D. If an extension can't be built without internals, open an upstream PR or issue first. Use $internal only as a short-lived, version-pinned shim.

6. Extension Packages¶

Rules for all extensions:

• Use public koota API only (hooks, queries, relations, trait.schema). Do not monkey-patch.
• Each package is small, tree-shakeable, and has koota as a peerDependency.
• Each package is spec-first. A spec in docs/specs/<pkg>.md references the matching flecs manual and lists in/out of scope. Conformance tests are ported or adapted from flecs tests where possible.
• Anything generic and in koota's spirit is proposed upstream. Once it's merged upstream, delete our version.

Dependency graph:

flowchart TD
  koota[(koota)] --> schedule[ecs-schedule]
  koota --> prefab[ecs-prefab]
  koota --> relations[ecs-relations]
  koota --> serialize[ecs-serialize]
  serialize --> devtools[ecs-devtools]
  schedule -. introspection, hooks .-> devtools
  ui["@workspace/ui"] --> devtools
  template["apps/web template"] --> demos["demo-*"]
  devtools --> template

7. Spec-Driven Process (for Extensions)¶

7.1 Sources¶

• Flecs manuals (normative): Systems, Prefabs, Relationships, Component Traits, Hierarchies, Remote API.
• Flecs test suite (reference/flecs/test/): mine it for behaviour cases and port relevant tests.
• Koota internals and docs (reference/koota): learn the extension surface and what's planned upstream.
• bitECS / becsy / miniplex: inspiration as listed in section 3.

7.2 Workflow per feature¶

flowchart LR
  A[Flecs manual + tests] --> B[Spec doc<br/>docs/specs/*.md]
  B --> C[Conformance tests<br/>packages/ecs/tests]
  C --> D[Implementation]
  D --> E[Demo usage]
  E -->|API friction| B

1. Write a short spec in docs/specs/<pkg>.md. Include the flecs reference, scope (in/out), the TS API sketch, and edge cases.
2. Turn the spec into Vitest tests. Port flecs tests where useful.
3. Implement against koota's public API until the tests pass.
4. Use the feature in the driving demo. Feed any friction back into the spec. If the friction is caused by koota itself, open an upstream issue or PR.

7.3 Non-goals (for now)¶

Flecs Script, the REST protocol, wire compatibility with the flecs Explorer, multithreading, shared-storage prefab inheritance, and full query variables.

8. Demo → Feature Mapping¶

9. Risks and Mitigations¶

10. Repository Housekeeping¶

• reference/ holds the koota, bitECS, becsy, miniplex, and flecs sources for study. Keep it out of the pnpm workspace and the build.
• packages/ecs (tsdown starter, still named tsdown-starter) can be either:
• (a) a thin umbrella @workspace/ecs that re-exports koota + extensions, or
• (b) split into packages/ecs-schedule, packages/ecs-prefab, etc.

Recommended: (b) packages, plus (a) as a convenience re-export.

• TypeScript version mismatch: the root uses ~6.0.2, packages/ecs uses ^7.0.2. Align them. Koota uses TS 6.
• apps/web becomes the demo template.
• Add docs/specs/ for extension specs.