Babylon Level Kit — Engine (Runtime) Documentation
The runtime half of the kit, current as of engine v0.31.1 · Blender add-on v0.32.0. Not sure where to start? Use Choose your path below. Or open subsystem diagrams for interactive maps, or Search to jump to a topic.
Choose your path
Chapter numbers are for reference — you do not need to read 01 through 14 in order.
| I want to… | Read this (in order) |
|---|---|
| Brand new — first level in ~15 minutes | Quickstart |
| Write a behavior with an LLM / MCP | LLM Playbook · route_task on bjs-mcp · Scripting context |
| Write or debug behavior scripts (human) | 02 — Runtime Basics → 14 — API Guide → 05 — Scripting |
| Understand how a level becomes a running game | 01 — Architecture (two files, GUIDs) → 04 — Load Pipeline → 02 — Runtime Basics (what happens each frame). |
| Hack on engine code or trace a bug | 01 — Architecture → 04 — Load Pipeline → pick a feature trace or trace-load for step-by-step source. |
| See if the kit supports something | 13 — Feature List → follow the trace link on that row. |
Doc types (quick glossary)
- Prose chapter (
01-ARCHITECTURE.html, …) — narrative explanation. Start here for concepts. - Subsystem diagram (
physics.html,load-pipeline.html, …) — clickable node graph for one slice of the engine. Good once you know the vocabulary. - Code trace (
trace-*.html) — step-by-step walkthrough with live source extracted at build time. Best when you need exact file and function names.
Many topics exist in all three forms — the subsystem map table below links them. Contributors: traces and diagrams are wired from PAGE_TOPICS; see BUILDING-DOCS.
What the runtime does
@bjs/engine (packages/engine/) loads the two artifacts Blender exports — level.glb (everything glTF can express) and level.scene.json (everything it can't) — and turns them into a live Level. LevelLoader.Load appends the glb, indexes nodes by GUID, builds an Entity per manifest entry, applies components through small subsystems (physics, lights, cameras, audio, …), then runs your Behavior scripts.
Subsystem map
| Subsystem | Engine diagram | Blender diagram | Prose |
|---|---|---|---|
| Architecture / two artifacts | architecture.html | export.html | 01 |
| Runtime loop | runtime-loop.html | — | 02 |
| Load pipeline | load-pipeline.html | — | 04 |
| Blender add-on | blender-addon.html | index.html | 03 |
| Data model / GUID | architecture.html | data-model.html | 01 |
| Export | workflow.html | export.html | 03 |
| Validation | workflow.html | validation.html | 09 |
| Live Link | workflow.html | livelink.html | 09 |
| Scripting | scripting.html | data-model.html | 05 |
| Input | input.html | input-actions.html | 12 |
| Physics | physics.html | data-model.html | 06 |
| Rendering / scene look | rendering.html | scene-settings.html | 07 |
| Audio & animation | audio-animation.html | export.html | 08 |
| UI (2D / 3D / particles) | ui.html | data-model.html | 11 |
| Prefabs (linked .blend) | workflow.html | PREFABS.html | 09 · 03 |
| Workflow / tooling | workflow.html | livelink.html | 09 |
The interactive pages
Subsystem diagrams: index.html (engine overview) · architecture.html (two artifacts) · runtime-loop.html (frame timeline) · load-pipeline.html · scripting.html · input.html · physics.html · rendering.html · audio-animation.html · ui.html · workflow.html · blender-addon.html (the editor, from the runtime's point of view).
Code traces (each node is a step; click for the explanation + the actual current TypeScript source): Load · Runtime loop · Lifecycle · Components · Physics · @exposed · Triggers · Constraints · Audio · Input · Live Link · 2D GUI · Particles · MSDF text · 3D GUI · Atmosphere · Lights · Cameras · Shadows · Post-processing (trace-runtime-loop · trace-lifecycle · trace-components · …).
The prose chapters
- Architecture — two artifacts, GUID identity, monorepo, data flow
- Runtime Basics — app vs kit, bootstrap, frame loop, Babylon hooks
- Blender Add-on — the editor half + export pipeline
- Load Pipeline —
LevelLoader.Load, the passes,FinalizeLevel - Scripting —
Entity,Behavior,@exposed,@inputMap - Physics — bodies, constraints, triggers, right-handed import
- Rendering — lights, cameras, shadows, environment, atmosphere, scene look
- Audio & Animation — sounds, NLA clips, the skinned-mesh rule
- Workflow — Live Link, the validator, Debug Build, tooling, Babylon Launcher
- Feature Traces — every feature's Blender → runtime file/function chain
- UI — 2D GUI, particles, MSDF text, 3D GUI
- Input — Input Actions, stick vs 1D/2D bindings, control type, gamepad, axis half,
@inputMap - Feature List — every component, scene setting, and workflow feature in one table
- API Guide —
Entity,Level,Behavior, input, attachments (behavior authors)
Regenerating
npm run docs:build regenerates both sides from the shared shell template (docs/_template/diagram-shell.html) and rebuilds the searchable landing page. npm run docs:trace rebuilds only this folder; it re-extracts every trace's source from packages/engine/. A renamed/deleted symbol fails the build loudly — the anti-rot guard. (The Blender side alone is npm run docs:blender.)
Full build pipeline, file layout, and how to add traces or subsystem diagrams: Building the documentation.