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 ≥ 20.19 (ESLint 10 requires ^20.19 || ^22.13 || >=24; 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.

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.