Gltf thin instances require explicit negative x scaling

ComicSans · August 3, 2026, 7:02pm

Observed: Even if the source gltf has (-1,1,1) scaling, the instance also needs (-1,1,1).

Expected: A thin instance transform would compose with the model transform, in the same way that a parent transform node would.

RaananW · August 4, 2026, 10:49am

checking! thanks for reporting

RaananW · August 4, 2026, 11:27am

github.com/BabylonJS/Babylon-Lite

fix!: compose hierarchy instance matrices with the template hierarchy (#525)

master ← raananw-bookish-garbanzo

opened 10:52AM - 04 Aug 26 UTC

RaananW

+40 -16

Fixes the forum report: [glTF thin instances require explicit negative X scaling…](https://forum.babylonjs.com/t/gltf-thin-instances-require-explicit-negative-x-scaling/63886) ([repro playground](https://liteplayground.babylonjs.com/snippet/N601SI/v/3)). ## Problem `createHierarchyInstancePool()` baked `rootWorld⁻¹` into every binding: ``` instanceMatrix = meshWorld⁻¹ · M · rootWorld⁻¹ · meshWorld finalWorld = mesh.world · instanceMatrix = M · rootWorld⁻¹ · meshWorld ``` So the instance matrix **replaced** the template root's world matrix rather than composing with it. A `loadGltf()` hierarchy's `__root__` node carries the RH→LH conversion as scaling `(-1, 1, 1)` (`load-gltf.ts:350`). Dividing it out mirrors every instance and inverts its winding, which is why the reporter had to pass an explicit `(-1, 1, 1)` scale just to get the model back to its authored orientation. A coordinate-system conversion is not user placement and must never be cancelled by an instancing helper. ## Fix Store `meshWorld` instead of `rootWorld⁻¹ · meshWorld`, so the stored per-mesh matrix is `meshWorld⁻¹ · M · meshWorld` and: ``` finalWorld = M · meshWorld ``` The instance matrix now behaves like a parent transform node above the hierarchy root — identity reproduces the template unchanged, and translations/rotations apply in world space on top of it. This is exactly what the existing unit test already asserted (`expected = rootInstance * mesh.worldMatrix`); it passed only because that test's template root world was identity. Also drops the now-dead root-inversion path and its `"requires an invertible root world matrix"` error. ## Breaking change `addHierarchyInstance()` / `setHierarchyInstanceMatrix()` matrices compose with the template hierarchy instead of replacing the root world matrix. Only affects templates whose root world is not identity (every glTF). Callers relying on the old semantics should pass `matrix * rootWorld⁻¹`. ## Validation - New regression test with a flipped glTF-style root (`scaling (-1, 1, 1)`): identity instance is a no-op, and a translated instance equals `offset * templateWorld`. Verified it **fails** on `master` and passes with the fix. - `vitest run tests/lite/unit/hierarchy-instance-pool.test.ts` — 5 passed. - `tsc -p packages/babylon-lite/tsconfig.json --noEmit` and `tsc -p tests/lite/tsconfig.json --noEmit` clean; eslint clean on changed files. - No scene or lab code uses hierarchy instance pools, so no parity/bundle-manifest impact (the change is net code removal).

Solves the issue - Babylon Lite Playground

Topic		Replies	Views
Strange thin intances behaviour Bugs	15	689	July 5, 2021
HowTo : Scale + ThinInstances Questions typescript	13	371	March 7, 2024
Automatically Convert Instances to Thin Instances? Questions	13	1031	September 20, 2023
Thin instances not rendering? Questions thininstances	3	727	June 6, 2022
Auto Thin Instances are parsing different than in a PG on the same Environment Questions	7	101	October 7, 2025

Gltf thin instances require explicit negative x scaling

Related topics