Babylon Lite

A WebGPU-exclusive, tree-shakable 3D engine that produces pixel-identical output to Babylon.js — in a fraction of the bundle size.

📖 Documentation — Start with Welcome, then Getting Started, the Feature Comparison, the Porting Guide, and Headless (Null Engine)

🤝 Contributing — How to add scenes, tests, and contribute code

Prerequisites

• Node.js 22.13+, 24.x, or 26+ (Vitest 5 no longer supports Node 20; CI runs Node 22)
• pnpm ≥ 9 (corepack enable to activate the version pinned in package.json)
• A browser with WebGPU support (Chrome 113+, Edge 113+, or recent Firefox and Safari)

Getting Started

# 1. Install all workspace dependencies (links the babylon-lite package)
pnpm install

# 2. Install Playwright browsers (needed for parity & bundle-size tests)
pnpm exec playwright install

# 3. Start the dev server (launches Vite on port 5174, scenes served from source)
pnpm dev

Open http://localhost:5174 to browse the scene gallery.

Scene and demo pages are served live from source, so this is the loop for engine work. The Bundle tab additionally needs the production bundles — build them with pnpm dev:lab (same server, preceded by a full bundle build) or with the tab's Regenerate button.

Lab startup and static builds restore scene 112's Flight Helmet KTX2 fixture from a pinned BabylonJS/Assets revision, verifying each file before use. pnpm fetch:flight-helmet runs this preparation separately. The downloaded files live in the gitignored lab/public/models/FlightHelmetKTX/ directory; no model binaries are added to the Lite package.

MeshLoD conversion

The native glTF/GLB-to-.mlod converter is maintained separately in MegameshCLI. Download the mesh-lod-tool executable for your platform from its releases, or build it there with CMake. Conversion does not require this repository or a Babylon Lite installation.

For the Harvard-Yenching Institute statue, run the CLI from a MegameshCLI checkout after extracting/building the executable. Its assets/ directory includes the source GLB:

mesh-lod-tool --input assets/harvard-yenching_institute_statue.glb \
  --output harvard-yenching_institute_statue.mlod \
  --stats-json statue-stats.json

The source has three mesh primitives, so this produces harvard-yenching_institute_statue.mesh000.prim000.mlod through ...mesh002.prim000.mlod; a single selected primitive uses the exact output path. On Windows use mesh-lod-tool.exe and join the command onto one line. See the CLI README for conversion options, supported inputs, installation, and validation.

Serve .mlod files with HTTP byte ranges and Content-Encoding: identity (no compression that changes byte offsets). For each primitive, use its corresponding source glTF material and placement with the root package API:

import { addMeshLoDToScene, createMeshLoDInstance, loadMeshLoD } from "@babylonjs/lite";

const asset = await loadMeshLoD(engine, "/mesh-lod/harvard-yenching_institute_statue.mesh000.prim000.mlod");
const instance = createMeshLoDInstance(asset, sourcePrimitive.material);
addMeshLoDToScene(scene, instance);

After registration, texture/sampler replacements and structural material changes such as doubleSided require await rebuildMaterial(scene, material), imported from the same root package. MeshLoD replaces matching batches transactionally and retires their old GPU resources and texture references behind a queue fence. UBO-only scalar/vector edits use markMaterialUboDirty(material) instead.

The CLI converts geometry, not materials or textures. The demo fetches the original GLB from BabylonJS/Assets for those properties and uses the three checked-in MLOD sidecars for streaming geometry; the source GLB is not kept in this repository. See the MeshLoD architecture for the runtime design. The model is “Harvard-Yenching Institute statue” by Alexandre Tokovinine, licensed CC BY 4.0; credit the author and link the license when redistributing the source or converted assets. Other models are not bundled with this demo.

Available Scripts

Command	Description
pnpm dev	Start the lab dev server on live source (http://localhost:5174)
pnpm dev:lab	Build bundle scenes + start the lab dev server
pnpm dev:playground	Start the Lite Playground dev server (http://localhost:5175)
pnpm build:playground	Build the Lite Playground into playground/dist
pnpm build	Build the babylon-lite library
pnpm build:bundle-scenes	Generate production bundles + per-scene manifest/ for the gallery
pnpm test	Build bundle scenes, then run parity and bundle-size tests
pnpm test:parity	Run Playwright visual parity tests against golden references
pnpm test:perf	Run Playwright performance benchmarks
pnpm test:bundle-size	Run bundle-size ceiling tests
pnpm lint	Run ESLint, then type-check with tsc --noEmit

Project Structure

packages/babylon-lite/   # The engine library
lab/         # Scene gallery & internal dev harness (Vite)
playground/  # Lite Playground — public editor/runner app (see playground/README.md)
tests/lite/unit/              # Vitest unit tests (pure Node.js, no GPU)
tests/lite/plumbing/          # Playwright GPU integration tests (dispose, material-swap)
tests/lite/parity/scenes/     # Playwright visual parity tests (pixel-diff)
tests/lite/perf/              # Playwright performance benchmarks
reference/lite/               # Golden reference screenshots (immutable)
scripts/                 # Build & bundling utilities
docs/lite/architecture/       # One-shot architecture docs

Adding Tests

Test Structure

tests/lite/
  unit/              # Vitest — pure Node.js shader/math tests (no GPU)
  plumbing/          # Playwright — dispose, material-swap (requires WebGPU)
  parity/
    scenes/          # Playwright — pixel-diff against golden references (requires WebGPU)
    compare-utils.ts # Shared image comparison helpers
  perf/              # Playwright — RAF performance benchmarks (requires WebGPU)

Unit Tests (vitest)

For pure logic tests (shaders, math, composition) that don't need a browser or GPU:

1. Create tests/lite/unit/my-feature.test.ts
2. Use vitest APIs (describe, it, expect)
3. Run: pnpm exec vitest run

Plumbing Tests (Playwright + WebGPU)

For GPU integration tests (dispose, material-swap, lifecycle):

1. Create a test page: lab/lite/my-test.html + lab/lite/src/my-test.ts
2. Add the HTML entry to lab/vite.config.ts (auto-detected if in root)
3. Create tests/lite/plumbing/my-test.spec.ts
4. Run: pnpm exec playwright test tests/lite/plumbing/my-test.spec.ts

CI uses Chrome's SwiftShader Vulkan backend — WebGPU works without a real GPU.

Scene Parity Tests (Playwright + WebGPU)

For pixel-diff visual regression tests against Babylon.js golden references:

1. Create the Lite scene: lab/lite/sceneN.html + lab/lite/src/lite/sceneN.ts
2. Create the BJS reference: lab/lite/babylon-ref-sceneN.html + lab/lite/src/bjs/sceneN.ts
3. Add entries to lab/vite.config.ts rollup inputs
4. Capture a golden reference and save to reference/lite/sceneN-<slug>/babylon-ref-golden.png
5. Save a downscaled JPG thumbnail (≤720p) of the golden to lab/public/thumbnails/sceneN.jpg
6. Add scene config to scene-config.json with id, slug, name, maxMad
7. Create tests/lite/parity/scenes/sceneN-<slug>.spec.ts using compare-utils.ts helpers
8. Add a bundle-size ceiling in tests/lite/parity/bundle-size.spec.ts (never raise without approval)
9. Run: pnpm exec playwright test tests/lite/parity/scenes/sceneN-<slug>.spec.ts

CI Workflows

Workflow	Trigger	What it runs
Lint	PR → master	ESLint + tsc --noEmit
Unit	PR → master	Vitest + plumbing tests
Bundle Size	PR → master	Runtime KB ceiling checks
Parity	manual	Scene pixel-diff vs golden refs
Perf	manual	RAF performance benchmarks

Troubleshooting

Vite can't resolve "babylon-lite"

Run pnpm install — the workspace symlink is missing.

Playwright "did not expect test() to be called here"

A rogue node_modules/playwright/ directory (not managed by pnpm) conflicts with the pnpm-managed copy. Fix:

rm -rf node_modules/playwright

Important: always use pnpm exec for Playwright commands (not npx or npm), e.g. pnpm exec playwright install. Using npx can recreate the rogue directory.

404 for /bundle/manifest.json

The dev server synthesizes this from the per-scene files in lab/public/bundle/manifest/, which pnpm build:bundle-scenes generates. The whole lab/public/bundle/ tree is gitignored build output, so a fresh clone has none of it until you build. If this 404s, or the bundle pages themselves are missing or stale, run pnpm build:bundle-scenes (or use pnpm dev:lab, which does this automatically), or hit Regenerate in the lab's Bundle tab.

404 for test-actual.png images

These are generated by parity tests. Run pnpm test:parity once to create them.

404 for /perf-manifest.json

Run pnpm test:perf to generate performance data for the dashboard.