ECS Framework
The renderer-agnostic Entity-Component-System framework that powers BJSM games — install with @babylonjsmarket/ecs
Sections
Features
- Learn How Real Games Are Structured
- Bet on the Pattern, Not the Tool
- Test Your Game Logic Without a Browser
- Read the Source, Not a Tutorial
- Race Detection in Development
- Distribute by URL
CLI Tools
Documentation
10 sections walk through everything ECS Framework ships with. Each one starts with a quick read; click through when you need depth.
01Installation
Learn more →@babylonjsmarket/ecsships as a single ESM-only npm package. The core has zero runtime dependencies — renderer adapters and physics engines are optional peer dependencies that you install only when you need them.
02Quick Start
Learn more →A minimal example: a player capsule, a directional light, and a Movement system that ticks every frame. All in one file.
03Component
Learn more →A
Componentis data attached to an entity. Extend the base class, add fields, you're done.
04Entity
Learn more →An
Entityis a container with a unique ID that holds Components and tags. You don't construct entities directly — the World does.
05System
Learn more →A
Systemis logic that processes entities matching a query. OverrideonUpdate(dt)for per-frame work. OverrideonEntityAdded/onEntityRemovedfor setup and teardown when entities enter or leave the query.
06World
Learn more →The
Worldis the orchestrator. It owns the entities, the systems, the EventBus, the SceneLoader, the renderer adapter, and the per-frame tick. Everything else in the framework flows through it.
07EventBus
Learn more →The
EventBusis pub/sub for Systems. It's how Systems coordinate without referencing each other.- 08
Renderers
Learn more →The framework defines
RendererAdapter, an interface every renderer must implement. Three concrete adapters ship in the package:BabylonAdapter,ThreeAdapter, andMockRendererAdapter. Pick whichever fits your project — your game code works under all three. - 09
SceneLoader
Learn more →SceneLoaderparses JSON scene files into entities. It's renderer-agnostic — same JSON, same loading, whether your renderer is Babylon, Three, or Mock. - 10
Testing
Learn more →The biggest practical win of an ECS: your game logic runs in vitest. No headless browser, no WebGL stub, no Puppeteer. Game code that runs in vitest is game code that runs anywhere.
Learn How Real Games Are Structured
Every shipped commercial game is ECS-shaped underneath — Unity, Unreal, Bevy, custom engines. This is the architecture you'd reinvent in year three. Skip the detour. Components are data, Systems are logic, the World runs them, and that's the whole mental model.
Bet on the Pattern, Not the Tool
The same code runs under BabylonJS with full Havok physics, Three.js with a pluggable physics core, or zero renderer at all in vitest. Pick a backend per project. Switch later. Never rewrite your gameplay because you outgrew your engine.
Test Your Game Logic Without a Browser
Game code that runs in vitest is game code that runs anywhere. Use the MockRendererAdapter to assert physics ticks, AI decisions, scoring logic — all in milliseconds, all deterministic. Reproduce a bug in one test instead of replaying a 10-minute scenario.
Read the Source, Not a Tutorial
The whole framework fits in your head. World, Component, Entity, System, EventBus, SceneLoader, RaceDetector — every file is small enough to read in a sitting. No black boxes, no plugins-of-plugins, no abandoned forum threads. When something surprises you, find out why in a minute.
Race Detection in Development
Pass `detectRaces: true` and the renderer adapter is wrapped in a Proxy that records every handle mutation. When two systems write to the same mesh in the same frame, you get a stack trace pointing at the conflict. The kind of bug that takes a weekend to reproduce — caught the first time it happens.
Distribute by URL
No app stores. No installers. No platform review queues. Your game is a link. Players are playing inside the time it takes to download a YouTube thumbnail. Pure web, pure TypeScript, pure JavaScript at runtime. The same package that powers babylonjsmarket.com games is the one you install.
