@babylonjs/lite-compat

An opt-in Babylon.js-shaped compatibility layer implemented on top of the Babylon Lite public API. It exists to give Babylon.js apps a low-friction migration runway to Babylon Lite's WebGPU renderer.

import { WebGPUEngine, Scene, ArcRotateCamera, HemisphericLight, MeshBuilder, StandardMaterial, Vector3, Color3 } from "@babylonjs/lite-compat";

const engine = new WebGPUEngine(canvas);
await engine.initAsync();

const scene = new Scene(engine);
const camera = new ArcRotateCamera("cam", -Math.PI / 2, Math.PI / 2.5, 5, new Vector3(0, 0, 0), scene);
camera.attachControl(canvas, true);
new HemisphericLight("light", new Vector3(0, 1, 0), scene);

const box = MeshBuilder.CreateBox("box", { size: 1 }, scene);
const mat = new StandardMaterial("mat", scene);
mat.diffuseColor = new Color3(1, 0, 0);
box.material = mat;

engine.runRenderLoop(() => scene.render());

Drop-in migration: keep your Babylon.js imports

If you have an existing Babylon.js app, you don't have to rewrite a single import. This package ships a bundler plugin that rewrites @babylonjs/* imports onto the compat layer at build time, so your @babylonjs/core, @babylonjs/loaders, @babylonjs/addons, @babylonjs/materials, and @recast-navigation/* imports resolve to @babylonjs/lite-compat instead.

// Your code stays exactly as it was — no edits needed:
import { Scene, ArcRotateCamera, MeshBuilder } from "@babylonjs/core";

Add the plugin for your bundler:

Vite

// vite.config.ts
import { defineConfig } from "vite";
import { liteCompat } from "@babylonjs/lite-compat/vite";

export default defineConfig({
    plugins: [liteCompat()],
});

Rollup (also works with Rolldown)

// rollup.config.js
import { liteCompat } from "@babylonjs/lite-compat/rollup";

export default {
    plugins: [liteCompat()],
};

Webpack (also works with Rspack)

// webpack.config.js
const { LiteCompatPlugin } = require("@babylonjs/lite-compat/webpack");

module.exports = {
    plugins: [new LiteCompatPlugin()],
};

esbuild

import { build } from "esbuild";
import { liteCompat } from "@babylonjs/lite-compat/esbuild";

await build({
    plugins: [liteCompat()],
    // …
});

Every adapter shares one redirect table, so they map imports identically. Specifiers outside the supported surface (e.g. @babylonjs/gui) are left untouched and resolve to the real Babylon.js package — so unsupported APIs fail loudly instead of silently mismapping. Once migration is complete you can drop the plugin and import from @babylonjs/lite-compat (or native @babylonjs/lite) directly.

What it is (and isn't)

• A class-based, Babylon.js-shaped surface over Lite's plain-data + factory API.
• Opt-in: import it explicitly. It installs no BABYLON global and has no module-level side effects, so it never bloats consumers that don't use it.
• Honest: unsupported Babylon.js APIs throw LiteCompatError rather than rendering something subtly wrong.
• Not a full Babylon.js reimplementation. Classic imperative particle systems, GUI, WebXR, decals, and other features absent from Babylon Lite are out of scope (Node Particle Editor graphs are partially supported).

Supported APIs at a glance

A high-level view of which Babylon.js packages and feature areas the compat layer covers. This is a summary of the common surface; individual properties and overloads within a supported area may still be absent.

| Status | Meaning | | ------ | ----------------------------------------------------------------------- | | ✅ | Common surface implemented and tested where possible | | ⚡ | A practical subset works; some properties/overloads are absent or throw | | ❌ | Not supported on the current Lite API (throws LiteCompatError) |

@babylonjs/core

| Feature area | Status | Notes | | --------------------------------------------------------------------------------------------------------- | :----: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Math (Vector*, Color*, Quaternion, Matrix, Plane, Ray, Frustum, Scalar, Axis/Space) | ✅ | Angle / Curve3 / Path3D partial | | Engine (WebGPUEngine, Engine, ThinEngine, NullEngine) | ⚡ | async startup + render loop; beginFrame/endFrame, MSAA/alpha-to-coverage (currentSampleCount/get/setAlphaToCoverage), and manual scene.render() unsupported | | Scene (clear color, cameras/lights, fog, environment, observables, ready state) | ⚡ | sync scene.pick unsupported (use async GPUPicker); scene.meshes + getMeshBy*/getNodeBy* now enumerate every mesh via a canonical wrapper registry | | Cameras (ArcRotateCamera, FreeCamera/Universal/Target, FollowCamera, GeospatialCamera) | ✅ | XR / device-orientation / stereoscopic rigs unsupported | | Lights (Hemispheric, Directional, Point, Spot) | ✅ | ClusteredLightContainer clusters point lights (⚡ partial); RectAreaLight unsupported | | Shadows (ShadowGenerator directional ESM/PCF, spot PCF) | ⚡ | CascadedShadowGenerator falls back to single cascade | | Meshes & geometry (class chain, MeshBuilder primitives, transforms, thin instances, clone, VertexData, Mesh.MergeMeshes) | ⚡ | CreateLines/CreateLineSystem support fixed-topology line lists and RGBA point colors; CreateDashedLines supports uniform-color dashed line lists; MergeMeshes bakes positions/normals/UVs and rejects unsupported attributes/animation; CreateDecal/CreateText/CreateTiledBox/CreateTiledPlane, GreasedLine* (thick lines), InstancedMesh, LOD/edges/outline, hardware instances unsupported | | CSG / CSG2 | ✅ | over Lite boolean ops | | Gizmos (position/rotation/scale/bounding-box/light/camera + GizmoManager) | ⚡ | over Lite gizmo suite; isEnabled toggles per-axis interactivity (display-only when disabled) | | Materials (StandardMaterial, PBRMaterial, metallic-rough / spec-gloss, NodeMaterial) | ⚡ | clone(name) shares textures with its own renderable; ShaderMaterial (GLSL), MultiMaterial, BackgroundMaterial unsupported | | Textures (Texture, RawTexture, RawTexture2DArray, RawTexture3D, DynamicTexture, CubeTexture, HDRCubeTexture) | ⚡ | HDRCubeTexture routes to native loadHdrEnvironment; RawTexture2DArray supports the raw-bytes, image-source/URL, and single-file KTX2 array paths; RenderTargetTexture / MirrorTexture / HtmlTexture unsupported | | Animation (keyframe Animation, easing, Animatable, AnimationGroup incl. weighted/additive blend) | ⚡ | CPU evaluation; loaded glTF skeletal blending supported | | Morph targets (MorphTarget / MorphTargetManager) | ✅ | over Lite morph targets | | Sprites (SpriteManager / Sprite) | ⚡ | camera-facing billboards; SpriteMap / packed atlas unsupported | | Behaviors / Actions (AutoRotation, Framing, ActionManager, conditions) | ⚡ | ActionManager is manual-dispatch; drag / six-DoF / XR-oriented mesh behaviors throw | | Misc (Observable, Tools, SmartArray, Tags, gradients, PerformanceMonitor) | ✅ | | | Audio V2 (AudioEngineV2, StaticSound, StreamingSound, AudioBus, buses/sources/analyzer) | ⚡ | over Lite's AudioV2 port; MainAudioBus spatial/analyzer and a second main bus unsupported | | Physics (HavokPlugin, scene.enablePhysics/getPhysicsEngine, PhysicsShapeType/PhysicsMotionType) | ⚡ | Havok V2 over Lite createHavokWorld; refresh-rate-independent useDeltaForWorldStep. Bodies via native createPhysicsAggregate (PhysicsAggregate class not wrapped) | | Particles (NodeParticleSystemSet / ParticleSystemSet — Node Particle Editor) | ⚡ | NPE snippet/JSON graphs: Parse/ParseFromSnippetAsync → buildAsync → start, incl. per-system set.systems[i] runtime (start/animate/updateSpeed/particleTexture). Imperative classic/GPU/solid ParticleSystem construction + programmatic block authoring unsupported | | Post-processes, layers (glow/highlight), probes, WebXR | ❌ | not in Babylon Lite — use native Lite create*Task functions |

@babylonjs/loaders

| Feature area | Status | Notes | | ---------------------------------------------------------------------------------------------- | :----: | --------------------------------------------------------------- | | glTF 2.0 (+ extensions), .babylon | ✅ | via Lite loadGltf / loadBabylon | | SceneLoader (ImportMeshAsync / AppendAsync / LoadAssetContainerAsync), AssetsManager | ⚡ | AssetContainer partial | | Gaussian Splatting (.ply / .splat / .sog / .spz) | ⚡ | via GaussianSplattingMesh; LOD-streaming + glTF-embedded (KHR_gaussian_splatting) variants unsupported | | OBJ / STL / FBX / BVH | ❌ | not in Lite — convert to glTF |

@babylonjs/addons · @recast-navigation/*

| Feature area | Status | Notes | | -------------------------------------------------------------------------------------- | :----: | -------------------------------- | | RecastJSPlugin (navmesh, crowd, path, raycast, off-mesh links, tile-cache obstacles) | ✅ | over Lite's native Recast-V2 API |

@babylonjs/materials

| Feature area | Status | Notes | | ----------------- | :----: | ---------------------------------------------------------------------------------------------- | | Library materials | ⚡ | mapped onto the compat material surface where a Lite equivalent exists; unsupported ones throw |

Specifiers outside the supported surface (e.g. @babylonjs/gui, @babylonjs/inspector) are left untouched by the bundler plugins and resolve to real Babylon.js, so unsupported APIs fail loudly instead of mis-mapping.

The intended migration path is:

@babylonjs/core  →  @babylonjs/lite-compat  →  babylon-lite (native)

Missing an API you need?

The compat surface grows in response to real-world migration needs. If you hit a Babylon.js API that isn't wrapped yet (or one that throws LiteCompatError), open an issue in the Babylon Lite repo and add the compat label. Describe the API and your use case — issues with the compat label feed directly into the layer's maintenance workflow.