45 lines
3.8 KiB
Markdown
45 lines
3.8 KiB
Markdown
# 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.
|