# 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/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 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.