@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.

@babylonjs/core

@babylonjs/loaders

glTF hierarchy: result.meshes is a flattened view of the glTF node hierarchy (transform nodes plus the primitive meshes beneath them), not one mesh per node as in Babylon.js. Reparent with setParent(), not .parent =, when you flatten it — see glTF import hierarchy and reparenting.

@babylonjs/addons · @recast-navigation/*

@babylonjs/materials

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)

Per-mesh opacity

mesh.visibility works automatically for ordinary Standard and PBR meshes, independently of mesh.isVisible. It never changes or clones the material, so meshes sharing a material can fade independently. Native Lite users explicitly import setMeshOpacity / getMeshOpacity from the package root; compat needs no enabler.

mesh.visibility = 0.5; // Sorted blending, depth writes off.
mesh.visibility = 0; // No colour or geometry-output draws; still pickable.
mesh.visibility = 1; // Original material route.

• The getter retains the raw finite value; rendering clamps it to [0, 1]. NaN and infinities throw RangeError (a deliberate deviation from Babylon.js).
• Shadows remain full strength, including at zero. Picking, isVisible, and enabled state are unchanged. Geometry outputs apply opacity before their existing > 0.4 alpha gate.
• Fading node/shader/line materials throws LiteCompatError; assigning one to a faded mesh is rejected before changing its material. Pending NodeMaterial handles are also rejected. Resetting visibility to 1 is allowed unless the native mesh is disposed.
• Imported glTF OPAQUE/MASK materials deliberately fade too, unlike Babylon.js's explicit transparency-mode behaviour. MASK cutoff uses the original alpha before opacity.
• A glTF-node wrapper updates its immediate primitive meshes atomically, not a child glTF node's primitives. Visibility is not inherited; a synthetic root has no geometry to fade. Raw getters belong to the wrapper assigned, even when its primitive wrappers share the resulting native rendering factor. Clones copy raw values and own new GPU bindings.
• Thin instances share their mesh's opacity. InstancedMesh.visibility, MeshLoD opacity, per-submesh opacity, and per-thin-instance opacity are not supported.

See the mesh-opacity architecture for native contracts and the explicitly normalized reference policies.

glTF import hierarchy and reparenting

Babylon Lite keeps the glTF node hierarchy: every glTF node becomes a transform node, and every primitive of its mesh becomes a mesh under that node. For a node with a single primitive, Babylon.js instead returns one Mesh that carries both the node transform and the geometry. The compat layer rebuilds Lite's hierarchy as canonical wrappers and returns it flattened, in hierarchy order, from SceneLoader.ImportMeshAsync(...).meshes and AssetContainer.meshes:

• The list is a flattened view of a retained hierarchy, not a list of independent renderable meshes. A parent always comes before its children.
• It contains the synthetic __root__ at index 0, the source glTF transform nodes, and the primitive meshes beneath them.
• Transform-only entries are wrapped as Mesh too, but carry no geometry: getTotalVertices() === 0. Do not treat an entry as geometry just because it is a Mesh.

Why per-entry .parent breaks

mesh.parent = node keeps the mesh's local transform and lets its world transform change under the new parent. mesh.setParent(node) keeps its world transform. Both behave as in Babylon.js, but a loop written for Babylon.js often assigns .parent to every returned entry:

// Fine in Babylon.js. Under compat it detaches each primitive from the glTF node that carries its transform.
for (const mesh of result.meshes) {
    mesh.parent = applicationRoot;
}

Under compat every primitive mesh is then moved off the glTF node above it and keeps only its own local transform, so any scale, rotation or translation that came from an ancestor node is lost. A typical case is a hardware asset modelled in millimetres whose glTF node scales it by 0.001: after the loop its primitives render 1000 times too large, so a 40 mm connector becomes 40 m, often far outside the camera range.

Baking in list order fails the same way. bakeCurrentTransformIntoVertices() bakes only the mesh's local transform: on a primitive that still sits under its glTF node it leaves the node's scale out, and resetting a node's transform first (it comes earlier in the list) changes what its children inherit before they are processed.

Safe patterns

Keep the hierarchy and move the whole import:

import { Mesh, SceneLoader } from "@babylonjs/lite-compat";

const result = await SceneLoader.ImportMeshAsync("", rootUrl, "model.glb", scene);
result.meshes[0]!.setParent(applicationRoot);

Flatten only the renderable meshes, keeping their current world transforms. result.meshes is typed as TransformNode[], so narrow the entries to Mesh before calling mesh-only methods:

const renderableMeshes = result.meshes.filter((mesh): mesh is Mesh => mesh instanceof Mesh && mesh.getTotalVertices() > 0);
for (const mesh of renderableMeshes) {
    mesh.setParent(applicationRoot);
}

Baking the composed transform into the geometry works only for a narrow set of imported meshes. For those, call setParent() first, so the full hierarchy-composed world transform becomes the mesh's new local transform, then bake:

// bakeableMeshes: the entries of renderableMeshes that meet every condition listed below.
for (const mesh of bakeableMeshes) {
    mesh.setParent(applicationRoot);
    mesh.bakeCurrentTransformIntoVertices();
}

Bake a mesh only if all of the following hold. Otherwise flatten it with setParent() alone, or keep the hierarchy and move the whole import:

• Shear-free composed transform. setParent() keeps the exact affine local matrix, but bakeCurrentTransformIntoVertices() rebuilds the transform from position, rotation and scaling, and that cannot express shear. Shear appears when an ancestor has a non-uniform scale and a descendant below it is rotated: for example, a node scaled (2, 1, 1) above a primitive rotated 45 degrees around Z. Baking such a primitive drops the shear and changes the geometry.
• Tightly packed vertex data. Baking replaces the vertex buffers through resizeMeshGeometry(), which throws for interleaved geometry. A glTF primitive loads as interleaved only when at least one of its vertex attributes comes from a bufferView whose byteStride is larger than that attribute's element size, for example positions and normals sharing one bufferView with byteStride: 24, and no loader extension such as Draco has already decoded it. A byteStride equal to the element size, which many exporters write on tightly packed bufferViews, keeps the primitive on the tightly packed path.
• Undeformed geometry. The baker transforms the base positions, normals and tangents only. It does not transform morph target deltas, so after baking a delta contributes in the baked space: under an inherited uniform scale of 0.001, a delta of 1 contributes 0.001 before baking and 1 after. Skinned meshes are not covered either, and flattening already detaches a primitive from any animated glTF node above it. Keep the hierarchy for assets whose morph targets, skinning or node animation must keep working.
• Only positions, normals and the first UV set. Baking can only re-upload the vertex attributes whose CPU arrays are retained. The glTF loader uploads COLOR_0 and TEXCOORD_1 without keeping CPU copies, so baking drops vertex colors and the second UV set, and it retains tangents only after enableGltfCpuTangents() from @babylonjs/lite is called before loading.
• No thin instances. This includes every primitive on a glTF node with EXT_mesh_gpu_instancing, which the loader draws as thin instances: their matrices stay in the node's local frame, and the shader composes mesh.world * instanceWorld. Baking transforms only the prototype geometry and resets the mesh transform, but not the instance matrices, so the instance offsets end up in the baked space: under an inherited uniform scale of 0.001, an instance translation of (0, 1, 0) contributes 0.001 before baking and 1 after, and the copies scatter. Flatten such meshes with setParent() alone, or keep the hierarchy.
• Triangle lists only. The glTF loader keeps the topology of line, line-strip and triangle-strip primitives, but the baker treats every index buffer as a triangle list. When the baked transform mirrors the geometry, it swaps the second and third index of each group of three to keep the winding. Flattening a glTF import under an identity applicationRoot includes the mirroring of its synthetic handedness root, so a line list [0, 1, 2, 3, 4, 5] becomes [0, 2, 1, 3, 5, 4] and connects other vertices; strips lose their connectivity the same way. Flatten line and strip primitives with setParent() alone.

setParent() also preserves mirrored transforms, including the synthetic handedness root of glTF imports (#456).

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.