3.8 KiB
Architecture
The editor and MCP mutate one serializable project through ProjectStore. The runtime loads a copy; stopping playback restores the editor scene. Project content and behaviours remain in project files.
| Module | Responsibility |
|---|---|
engine/schema.ts |
Project format, validation, IDs, transforms and references |
engine/store.ts |
Atomic transactions, revisions, undo/redo and request receipts |
engine/geometry.ts |
Procedural geometry and compound models |
engine/runtime.ts |
Babylon rendering, model loading, animation, physics, input and worker bridge |
engine/two-d.ts, engine/image-import.ts |
2D document validation, frames, tile tools and image import |
engine/graphics2d.ts, engine/view2d.ts |
Shared-scene sprites, animation, batched tiles and XY editor controls |
engine/physics2d.ts |
Independent Rapier2D world, controller, sensors, collision filters and joints |
engine/template2d.ts |
Empty XY project and original runnable platformer example |
engine/character.ts |
Fixed-step Rapier character movement and contacts |
engine/script-worker.js |
Project behaviour lifecycle and command output |
engine/templates.ts |
Blank project construction |
engine/archive.ts, engine/build-kit.ts |
Portable projects, web output and application build kits |
editor/ |
React editor, inspector, file mode and IndexedDB draft storage |
server/index.ts |
Local HTTP service, project persistence, events and runtime bridge |
server/mcp.ts, server/stdio.ts |
MCP tools, resources, prompts and stdio adapter |
server/builds.ts |
Build queue, immutable snapshots, logs and artifacts |
native/ |
Optional application wrappers and packaging tools |
scripts/build-local.mjs |
Reproducible editor/player bundles and build-kit resources |
Document and runtime
Transforms are local to an entity's parent. Reparenting preserves local coordinates unless a transform is supplied. Duplicate and prefab operations remap internal parent, camera target, 2D joint target and typed entity-property references; external references remain unchanged.
Transactions apply atomically. A stale expectedRevision fails instead of overwriting intervening edits. Repeating a transaction with the same requestId can reuse the recorded result. History and receipts are held in memory, while the project document is persisted.
Runtime loading, playback, stopping and spawning are serialized. Physics advances at a fixed 1/60-second step. A worker receives copied state and returns commands; it does not own the editor document. A behaviour error disables that behaviour. An unresponsive worker is terminated after its watchdog timeout. This protects responsiveness, not against malicious project code.
Local service
The Node server listens on loopback and checks Host and Origin. MCP requests require a bearer token. Files are written atomically, imported paths are constrained to the project directory, and static resources come from the engine's public directory. The service is intended for one user and one server process per project folder.
The browser performs rendering, simulation and scripting. Runtime MCP tools need an open editor tab; the first connected tab handles runtime requests. File-only mode can edit projects without the Node service, but local MCP and application build jobs then are unavailable.
Distribution
npm run build generates browser bundles from source and copies the native build-kit templates. These generated directories are not tracked. A standalone web export contains the runtime, project and resources, and needs neither the React editor nor MCP.
Native outputs wrap the web runtime in Electron or Android WebView. Native toolchains and user projects are separate from the engine repository. No hosted-site deployment configuration or hosted account is required.