@babylonjs/lite-compat 1.37.0-preview → 1.37.2-preview

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -118,11 +118,11 @@ overloads within a supported area may still be absent.
118
118
  | Feature area | Status | Notes |
119
119
  | ----------------------------------------------------------------------------------------------------------------------------------------- | :----: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
120
120
  | Math (`Vector*`, `Color*`, `Quaternion`, `Matrix`, `Plane`, `Ray`, `Frustum`, `Scalar`, `Axis`/`Space`, color temperature/white balance) | ✅ | Includes handedness-correct `LookDirection` matrices/quaternions; `Angle` / `Curve3` / `Path3D` partial |
121
- | Engine (`WebGPUEngine`, `Engine`, `ThinEngine`, `NullEngine`) | ⚡ | async startup + render loop; `currentSampleCount` reports the active surface's MSAA count; `beginFrame`/`endFrame`, occlusion queries, engine-wide alpha-to-coverage, and manual `scene.render()` unsupported |
121
+ | Engine (`WebGPUEngine`, `Engine`, `ThinEngine`, `NullEngine`) | ⚡ | async startup + render loop; reverse-depth constructor options/state are exposed over Lite's fixed reverse-Z pipeline; `currentSampleCount` reports the active surface's MSAA count; `beginFrame`/`endFrame`, occlusion queries, engine-wide alpha-to-coverage, and manual `scene.render()` unsupported |
122
122
  | Compute + GPU buffers (`ComputeShader`, `StorageBuffer`, `UniformBuffer`) | ⚡ | WGSL compute, direct/indirect dispatch, storage buffers, and compute-oriented std140 uniform buffers forward to Lite; shader registries/preprocessing, texture bindings, in-frame immediate dispatch, and Effect-oriented UBO methods remain unsupported |
123
123
  | Scene (clear color, cameras/lights, fog, environment, observables, ready state) | ⚡ | `Node.accessibilityTag` forwards description, role, and ARIA metadata to Lite (DOM event handlers remain unsupported); sync `scene.pick` forwards to Lite's CPU triangle picker with thin-instance, predicate, normal, and UV detail; `scene.meshes` + `getMeshBy*`/`getNodeBy*` enumerate every mesh via a canonical wrapper registry; exposure/contrast/tone mapping are forwarded, while white balance and fluid rendering throw because Lite lacks their cross-cutting shader/render-pass subsystems |
124
124
  | Cameras (`ArcRotateCamera`, `FreeCamera`/`Universal`/`Target`, `FollowCamera`, `GeospatialCamera`) | ✅ | arc controls include pointer, wheel, touch, and BJS-default Arrow-key input; orthographic bounds and projection-mode switching forward to Lite; fully unconfigured orthographic extents use Lite's `halfHeight` + aspect-ratio derivation rather than Babylon.js render dimensions; XR / device-orientation / stereoscopic rigs unsupported |
125
- | Lights (`Hemispheric`, `Directional`, `Point`, `Spot`) | ✅ | `ClusteredLightContainer` clusters unshadowed point lights before engine start (⚡ partial); clustered spot lights and `RectAreaLight` unsupported |
125
+ | Lights (`Hemispheric`, `Directional`, `Point`, `Spot`, `RectAreaLight`) | ⚡ | rectangular area lights use Lite's native LTC path, including `AreaLightTextureTools` emission preprocessing; Lite is stricter for invalid negative/non-finite emitter dimensions. `ClusteredLightContainer` clusters unshadowed point lights before engine start (⚡ partial), while clustered spot lights remain unsupported |
126
126
  | Shadows (`ShadowGenerator` directional ESM/PCF, spot PCF) | ⚡ | `CascadedShadowGenerator` uses Lite's native 2–4 cascade CSM |
127
127
  | 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; mesh-blending tag helpers and validated mesh metadata forward to native Lite; `MergeMeshes` bakes positions/normals/UVs and rejects unsupported attributes/animation; polygon/extruded-polygon, decal/text/tiled builders, `GreasedLine*` (thick lines), `InstancedMesh`, LOD/edges/outline, and hardware instances unsupported |
128
128
  | CSG / CSG2 | ✅ | over Lite boolean ops |
@@ -144,14 +144,18 @@ overloads within a supported area may still be absent.
144
144
  | Feature area | Status | Notes |
145
145
  | ---------------------------------------------------------------------------------------------- | :----: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
146
146
  | glTF 2.0 (+ extensions), `.babylon` | ✅ | via Lite `loadGltf` / `loadBabylon`; KHR_interactivity assets run through Lite's native flow-graph runtime |
147
- | `GLTF2.KHR_interactivity` public helpers | ⚡ | pure operation/data normalization and exporter data types are implemented; BJS FlowGraph registry/parser/export planning throws with named structural blockers |
147
+ | `GLTF2.KHR_interactivity` public helpers | ⚡ | pure operation/data normalization and exporter data types are implemented; BJS FlowGraph registry/parser/block/export planning throws with named structural blockers |
148
148
  | glTF 1.0 loader and extensions | ❌ | named `GLTF1` stubs throw; Lite has no legacy parser, extension registry, or material-conversion subsystem |
149
149
  | OpenPBR glTF material adapter | ❌ | exported at root and under `GLTF2`; throws because Lite has no OpenPBR material subsystem |
150
150
  | OpenUSD (`USDFileLoader`) | ⚡ | delegates binary import, virtual files, callbacks, diagnostics, asset containers, and disposal to Lite; all four custom runtime assets must share one directory |
151
151
  | `SceneLoader` (`ImportMeshAsync` / `AppendAsync` / `LoadAssetContainerAsync`), `AssetsManager` | ⚡ | `AssetContainer` partial |
152
- | Gaussian Splatting (`.ply` / `.splat` / `.sog` / `.spz`) | ⚡ | `GaussianSplattingMesh` wraps eager Lite loaders; BJS streaming and the separate stochastic WebGPU point-splatting compute path resolve to named stubs because their budget, pass-lifecycle, and rendering models do not map to Lite's sorted-splat renderer |
152
+ | Gaussian Splatting (`.ply` / `.splat` / `.sog` / `.spz`) | ⚡ | `GaussianSplattingMesh` wraps eager Lite loaders and Lite's opt-in point renderer; point render scale supports `"auto"` or exact `1 / n` multipliers for divisors 1–8. BJS streaming and standalone point-renderer/blit classes remain named stubs |
153
153
  | `OBJ` / `STL` / `FBX` / `BVH` | ❌ | parser/materializer subsystems are not in Lite — convert to glTF |
154
154
 
155
+ > **glTF hierarchy:** `result.meshes` is a flattened view of the glTF node hierarchy (transform nodes plus the
156
+ > primitive meshes beneath them), not one mesh per node as in Babylon.js. Reparent with `setParent()`, not `.parent =`,
157
+ > when you flatten it — see [glTF import hierarchy and reparenting](#gltf-import-hierarchy-and-reparenting).
158
+
155
159
  ### `@babylonjs/addons` · `@recast-navigation/*`
156
160
 
157
161
  | Feature area | Status | Notes |
@@ -174,6 +178,111 @@ The intended migration path is:
174
178
  @babylonjs/core → @babylonjs/lite-compat → babylon-lite (native)
175
179
  ```
176
180
 
181
+ ## glTF import hierarchy and reparenting
182
+
183
+ Babylon Lite keeps the glTF node hierarchy: every glTF node becomes a transform node, and every primitive of its mesh
184
+ becomes a mesh **under** that node. For a node with a single primitive, Babylon.js instead returns one `Mesh` that
185
+ carries both the node transform and the geometry. The compat layer rebuilds Lite's hierarchy as canonical wrappers and
186
+ returns it flattened, in hierarchy order, from `SceneLoader.ImportMeshAsync(...).meshes` and `AssetContainer.meshes`:
187
+
188
+ - The list is a flattened view of a retained hierarchy, not a list of independent renderable meshes. A parent always
189
+ comes before its children.
190
+ - It contains the synthetic `__root__` at index 0, the source glTF transform nodes, and the primitive meshes beneath
191
+ them.
192
+ - Transform-only entries are wrapped as `Mesh` too, but carry no geometry: `getTotalVertices() === 0`. Do not treat an
193
+ entry as geometry just because it is a `Mesh`.
194
+
195
+ ### Why per-entry `.parent` breaks
196
+
197
+ `mesh.parent = node` keeps the mesh's **local** transform and lets its world transform change under the new parent.
198
+ `mesh.setParent(node)` keeps its **world** transform. Both behave as in Babylon.js, but a loop written for Babylon.js
199
+ often assigns `.parent` to every returned entry:
200
+
201
+ ```ts
202
+ // Fine in Babylon.js. Under compat it detaches each primitive from the glTF node that carries its transform.
203
+ for (const mesh of result.meshes) {
204
+ mesh.parent = applicationRoot;
205
+ }
206
+ ```
207
+
208
+ Under compat every primitive mesh is then moved off the glTF node above it and keeps only its own local transform, so
209
+ any scale, rotation or translation that came from an ancestor node is lost. A typical case is a hardware asset modelled
210
+ in millimetres whose glTF node scales it by `0.001`: after the loop its primitives render 1000 times too large, so a
211
+ 40 mm connector becomes 40 m, often far outside the camera range.
212
+
213
+ Baking in list order fails the same way. `bakeCurrentTransformIntoVertices()` bakes only the mesh's **local**
214
+ transform: on a primitive that still sits under its glTF node it leaves the node's scale out, and resetting a node's
215
+ transform first (it comes earlier in the list) changes what its children inherit before they are processed.
216
+
217
+ ### Safe patterns
218
+
219
+ Keep the hierarchy and move the whole import:
220
+
221
+ ```ts
222
+ import { Mesh, SceneLoader } from "@babylonjs/lite-compat";
223
+
224
+ const result = await SceneLoader.ImportMeshAsync("", rootUrl, "model.glb", scene);
225
+ result.meshes[0]!.setParent(applicationRoot);
226
+ ```
227
+
228
+ Flatten only the renderable meshes, keeping their current world transforms. `result.meshes` is typed as
229
+ `TransformNode[]`, so narrow the entries to `Mesh` before calling mesh-only methods:
230
+
231
+ ```ts
232
+ const renderableMeshes = result.meshes.filter((mesh): mesh is Mesh => mesh instanceof Mesh && mesh.getTotalVertices() > 0);
233
+ for (const mesh of renderableMeshes) {
234
+ mesh.setParent(applicationRoot);
235
+ }
236
+ ```
237
+
238
+ Baking the composed transform into the geometry works only for a narrow set of imported meshes. For those, call
239
+ `setParent()` first, so the full hierarchy-composed world transform becomes the mesh's new local transform, then bake:
240
+
241
+ ```ts
242
+ // bakeableMeshes: the entries of renderableMeshes that meet every condition listed below.
243
+ for (const mesh of bakeableMeshes) {
244
+ mesh.setParent(applicationRoot);
245
+ mesh.bakeCurrentTransformIntoVertices();
246
+ }
247
+ ```
248
+
249
+ Bake a mesh only if all of the following hold. Otherwise flatten it with `setParent()` alone, or keep the hierarchy and
250
+ move the whole import:
251
+
252
+ - **Shear-free composed transform.** `setParent()` keeps the exact affine local matrix, but
253
+ `bakeCurrentTransformIntoVertices()` rebuilds the transform from position, rotation and scaling, and that cannot
254
+ express shear. Shear appears when an ancestor has a non-uniform scale and a descendant below it is rotated: for
255
+ example, a node scaled `(2, 1, 1)` above a primitive rotated 45 degrees around Z. Baking such a primitive drops the
256
+ shear and changes the geometry.
257
+ - **Tightly packed vertex data.** Baking replaces the vertex buffers through `resizeMeshGeometry()`, which throws for
258
+ interleaved geometry. A glTF primitive loads as interleaved only when at least one of its vertex attributes comes
259
+ from a bufferView whose `byteStride` is larger than that attribute's element size, for example positions and normals
260
+ sharing one bufferView with `byteStride: 24`, and no loader extension such as Draco has already decoded it. A
261
+ `byteStride` equal to the element size, which many exporters write on tightly packed bufferViews, keeps the primitive
262
+ on the tightly packed path.
263
+ - **Undeformed geometry.** The baker transforms the base positions, normals and tangents only. It does not transform
264
+ morph target deltas, so after baking a delta contributes in the baked space: under an inherited uniform scale of
265
+ `0.001`, a delta of 1 contributes `0.001` before baking and `1` after. Skinned meshes are not covered either, and
266
+ flattening already detaches a primitive from any animated glTF node above it. Keep the hierarchy for assets whose
267
+ morph targets, skinning or node animation must keep working.
268
+ - **Only positions, normals and the first UV set.** Baking can only re-upload the vertex attributes whose CPU arrays are
269
+ retained. The glTF loader uploads `COLOR_0` and `TEXCOORD_1` without keeping CPU copies, so baking drops vertex colors
270
+ and the second UV set, and it retains tangents only after `enableGltfCpuTangents()` from `@babylonjs/lite` is called before loading.
271
+ - **No thin instances.** This includes every primitive on a glTF node with `EXT_mesh_gpu_instancing`, which the loader
272
+ draws as thin instances: their matrices stay in the node's local frame, and the shader composes
273
+ `mesh.world * instanceWorld`. Baking transforms only the prototype geometry and resets the mesh transform, but not the
274
+ instance matrices, so the instance offsets end up in the baked space: under an inherited uniform scale of `0.001`, an
275
+ instance translation of `(0, 1, 0)` contributes `0.001` before baking and `1` after, and the copies scatter. Flatten
276
+ such meshes with `setParent()` alone, or keep the hierarchy.
277
+ - **Triangle lists only.** The glTF loader keeps the topology of line, line-strip and triangle-strip primitives, but the
278
+ baker treats every index buffer as a triangle list. When the baked transform mirrors the geometry, it swaps the second
279
+ and third index of each group of three to keep the winding. Flattening a glTF import under an identity
280
+ `applicationRoot` includes the mirroring of its synthetic handedness root, so a line list `[0, 1, 2, 3, 4, 5]` becomes
281
+ `[0, 2, 1, 3, 5, 4]` and connects other vertices; strips lose their connectivity the same way. Flatten line and strip
282
+ primitives with `setParent()` alone.
283
+
284
+ `setParent()` also preserves mirrored transforms, including the synthetic handedness root of glTF imports (#456).
285
+
177
286
  ## Missing an API you need?
178
287
 
179
288
  The compat surface grows in response to real-world migration needs. If you hit a