@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 +113 -4
- package/index.d.ts +397 -19
- package/index.js +1584 -1023
- package/index.js.map +1 -1
- package/{meshes-zeNif9yt.js → meshes-sOWGK4P8.js} +40 -13
- package/meshes-sOWGK4P8.js.map +1 -0
- package/navigation.d.ts +42 -9
- package/navigation.js +1 -1
- package/package.json +4 -4
- package/meshes-zeNif9yt.js.map +0 -1
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`)
|
|
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
|
|
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
|