@babylonjs/lite-compat 1.16.0-preview → 1.18.0-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
@@ -123,7 +123,7 @@ overloads within a supported area may still be absent.
123
123
  | Cameras (`ArcRotateCamera`, `FreeCamera`/`Universal`/`Target`, `FollowCamera`, `GeospatialCamera`) | ✅ | XR / device-orientation / stereoscopic rigs unsupported |
124
124
  | Lights (`Hemispheric`, `Directional`, `Point`, `Spot`) | ✅ | `RectAreaLight` / clustered lights unsupported |
125
125
  | Shadows (`ShadowGenerator` directional ESM/PCF, spot PCF) | ⚡ | `CascadedShadowGenerator` falls back to single cascade |
126
- | Meshes & geometry (class chain, `MeshBuilder` primitives, transforms, thin instances, `clone`, `VertexData`, `Mesh.MergeMeshes`) | ⚡ | `MergeMeshes` bakes positions/normals/UVs and rejects unsupported attributes/animation; `CreateLines`/`CreateDecal`/`CreateText`/`CreateTiledBox`/`CreateTiledPlane`, `InstancedMesh`, LOD/edges/outline, hardware instances unsupported |
126
+ | Meshes & geometry (class chain, `MeshBuilder` primitives, transforms, thin instances, `clone`, `VertexData`, `Mesh.MergeMeshes`) | ⚡ | `CreateLines`/`CreateLineSystem` support fixed-topology line lists and RGBA point colors; `MergeMeshes` bakes positions/normals/UVs and rejects unsupported attributes/animation; `CreateDashedLines`/`CreateDecal`/`CreateText`/`CreateTiledBox`/`CreateTiledPlane`, `InstancedMesh`, LOD/edges/outline, hardware instances unsupported |
127
127
  | CSG / CSG2 | ✅ | over Lite boolean ops |
128
128
  | Gizmos (position/rotation/scale/bounding-box/light/camera + `GizmoManager`) | ⚡ | over Lite gizmo suite; `isEnabled` toggles per-axis interactivity (display-only when disabled) |
129
129
  | Materials (`StandardMaterial`, `PBRMaterial`, metallic-rough / spec-gloss, `NodeMaterial`) | ⚡ | `clone(name)` shares textures with its own renderable; `ShaderMaterial` (GLSL), `MultiMaterial`, `BackgroundMaterial` unsupported |
@@ -135,7 +135,7 @@ overloads within a supported area may still be absent.
135
135
  | Misc (`Observable`, `Tools`, `SmartArray`, `Tags`, gradients, `PerformanceMonitor`) | ✅ | |
136
136
  | Audio V2 (`AudioEngineV2`, `StaticSound`, `StreamingSound`, `AudioBus`, buses/sources/analyzer) | ⚡ | over Lite's AudioV2 port; `MainAudioBus` spatial/analyzer and a second main bus unsupported |
137
137
  | Physics (`HavokPlugin`, `scene.enablePhysics`/`getPhysicsEngine`, `PhysicsShapeType`/`PhysicsMotionType`) | ⚡ | Havok V2 over Lite `createHavokWorld`; refresh-rate-independent `useDeltaForWorldStep`. Bodies via native `createPhysicsAggregate` (`PhysicsAggregate` class not wrapped) |
138
- | Particles (`NodeParticleSystemSet` / `ParticleSystemSet` — Node Particle Editor) | ⚡ | NPE snippet/JSON graphs: `Parse`/`ParseFromSnippetAsync` → `buildAsync` → `start`. Imperative classic/GPU/solid `ParticleSystem` + programmatic block authoring unsupported |
138
+ | 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 |
139
139
  | Post-processes, layers (glow/highlight), probes, WebXR | ❌ | not in Babylon Lite — use native Lite `create*Task` functions |
140
140
 
141
141
  ### `@babylonjs/loaders`
package/index.d.ts CHANGED
@@ -6,6 +6,7 @@ import { ClearCoatProps } from '@babylonjs/lite';
6
6
  import { EngineContext } from '@babylonjs/lite';
7
7
  import { EngineOptions } from '@babylonjs/lite';
8
8
  import { IridescenceProps } from '@babylonjs/lite';
9
+ import { LineMaterial } from '@babylonjs/lite';
9
10
  import { Mesh as Mesh_2 } from '@babylonjs/lite';
10
11
  import { PhysicsWorld } from '@babylonjs/lite';
11
12
  import { RenderCanvas } from '@babylonjs/lite';
@@ -1235,7 +1236,7 @@ export declare class ColorGradient {
1235
1236
  constructor(gradient: number, color1: [number, number, number, number], color2?: [number, number, number, number] | undefined);
1236
1237
  }
1237
1238
 
1238
- declare type CompatMaterial = StandardMaterial | PBRMaterial | NodeMaterial | GridMaterial;
1239
+ declare type CompatMaterial = StandardMaterial | PBRMaterial | NodeMaterial | GridMaterial | LinesMaterial;
1239
1240
 
1240
1241
  declare type CompatMaterial_2 = StandardMaterial | PBRMaterial | NodeMaterial;
1241
1242
 
@@ -1294,6 +1295,12 @@ export declare function CreateDisc(name: string, options: object, scene: Scene):
1294
1295
  /** Babylon.js `CreateGround(name, options, scene)` (groundBuilder). */
1295
1296
  export declare function CreateGround(name: string, options: GroundOptions, scene: Scene): Mesh;
1296
1297
 
1298
+ /** Babylon.js `CreateLines(name, options, scene)` (linesBuilder). */
1299
+ export declare function CreateLines(name: string, options: LinesBuilderOptions, scene?: Scene | null): LinesMesh;
1300
+
1301
+ /** Babylon.js `CreateLineSystem(name, options, scene)` (linesBuilder). */
1302
+ export declare function CreateLineSystem(name: string, options: LineSystemBuilderOptions, scene?: Scene | null): LinesMesh;
1303
+
1297
1304
  /** Babylon.js `CreateMainAudioBusAsync`. */
1298
1305
  export declare function CreateMainAudioBusAsync(name: string, options?: Partial<IMainAudioBusOptions>, engine?: AudioEngineV2 | null): Promise<MainAudioBus>;
1299
1306
 
@@ -1405,21 +1412,26 @@ export declare class CSG2 {
1405
1412
  * rather than as a standalone GPU texture object. This compat `CubeTexture`
1406
1413
  * therefore acts as a lightweight handle that records the environment URL; the
1407
1414
  * actual GPU work happens when it is assigned to `scene.environmentTexture` and
1408
- * the engine starts (see `Scene` env handling).
1415
+ * the engine starts (see `Scene` env handling). It still extends
1416
+ * {@link BaseTexture} to match the Babylon.js class hierarchy, so it can appear
1417
+ * in `BaseTexture[]` surfaces such as `Material.getActiveTextures()`; because the
1418
+ * environment has no standalone Lite handle, `getInternalTexture()` stays `null`.
1409
1419
  */
1410
- export declare class CubeTexture {
1420
+ export declare class CubeTexture extends BaseTexture {
1411
1421
  /** Source URL of the (prefiltered) environment. */
1412
1422
  readonly url: string;
1413
1423
  /** Babylon.js `coordinatesMode` (skybox = 5). Recorded for API parity. */
1414
1424
  coordinatesMode: number;
1415
- name: string;
1416
1425
  gammaSpace: boolean;
1417
1426
  level: number;
1418
1427
  /** Fires when the cube map is "ready" (resolved on a microtask in this compat layer). */
1419
1428
  readonly onLoadObservable: Observable<CubeTexture>;
1420
1429
  private _ready;
1430
+ private readonly _readyPromise;
1421
1431
  constructor(url: string, _scene?: unknown, _extensions?: unknown, _noMipmap?: boolean, _files?: unknown, onLoad?: (() => void) | null, _onError?: unknown, _format?: unknown, _prefiltered?: boolean);
1432
+ getClassName(): string;
1422
1433
  /** Babylon.js `BaseTexture.isReady()`. */
1423
1434
  isReady(): boolean;
1435
+ whenReadyAsync(): Promise<void>;
1424
1436
  /** Babylon.js `CubeTexture.CreateFromPrefilteredData(url, scene)`. */
1425
1437
  static CreateFromPrefilteredData(url: string, scene?: unknown): CubeTexture;
1426
1438
  dispose(): void;
@@ -1924,21 +1936,23 @@ export declare class HavokPlugin {
1924
1936
  * `scene.environmentTexture` and the engine starts, at which point the scene
1925
1937
  * routes it through Babylon Lite's native `loadHdrEnvironment`.
1926
1938
  */
1927
- export declare class HDRCubeTexture {
1939
+ export declare class HDRCubeTexture extends BaseTexture {
1928
1940
  /** Source URL of the `.hdr` panorama. */
1929
1941
  readonly url: string;
1930
1942
  /** Requested cubemap face size (BJS `size`); forwarded to Lite's `faceSize`. */
1931
1943
  readonly size: number;
1932
1944
  /** Babylon.js `coordinatesMode` (skybox = 5). Recorded for API parity. */
1933
1945
  coordinatesMode: number;
1934
- name: string;
1935
1946
  gammaSpace: boolean;
1936
1947
  level: number;
1937
1948
  /** Fires when the HDR environment is "ready" (resolved on a microtask). */
1938
1949
  readonly onLoadObservable: Observable<HDRCubeTexture>;
1939
1950
  private _ready;
1951
+ private readonly _readyPromise;
1940
1952
  constructor(url: string, _sceneOrEngine?: unknown, size?: number, _noMipmap?: boolean, _generateHarmonics?: boolean, _gammaSpace?: boolean, _prefilterOnLoad?: boolean, onLoad?: (() => void) | null);
1953
+ getClassName(): string;
1941
1954
  /** Babylon.js `BaseTexture.isReady()`. */
1942
1955
  isReady(): boolean;
1956
+ whenReadyAsync(): Promise<void>;
1943
1957
  dispose(): void;
1944
1958
  }
1945
1959
 
@@ -2361,8 +2375,49 @@ export declare class LightGizmo {
2361
2375
  private _attached;
2362
2376
  dispose(): void;
2363
2377
  }
2364
2378
 
2365
- export declare class LinesMesh {
2366
- constructor();
2379
+ declare interface LinesBuilderOptions {
2380
+ points: Vector3[];
2381
+ updatable?: boolean;
2382
+ instance?: LinesMesh | null;
2383
+ colors?: Color4[];
2384
+ useVertexAlpha?: boolean;
2385
+ material?: unknown;
2386
+ }
2387
+
2388
+ declare class LinesMaterial extends Material {
2389
+ readonly _lite: LineMaterial;
2390
+ constructor(name: string, lite: LineMaterial, scene?: Scene);
2391
+ getClassName(): string;
2392
+ clone(name: string): LinesMaterial;
2393
+ }
2394
+
2395
+ /** Babylon.js `LinesMesh` backed by a Babylon Lite line-system mesh. */
2396
+ export declare class LinesMesh extends Mesh {
2397
+ readonly useVertexColor: boolean;
2398
+ readonly useVertexAlpha: boolean;
2399
+ intersectionThreshold: number;
2400
+ private _lineMaterial;
2401
+ private readonly _color;
2402
+ private _alpha;
2403
+ private _suspendLineColorSync;
2404
+ constructor(name: string, sceneOrLite: Scene | Mesh_2, scene?: Scene, useVertexColor?: boolean, useVertexAlpha?: boolean);
2405
+ getClassName(): string;
2406
+ get color(): Color3;
2407
+ set color(value: Color3);
2408
+ get alpha(): number;
2409
+ set alpha(value: number);
2410
+ thinInstanceSetBuffer(kind: string, buffer: Float32Array | null, stride?: number): void;
2411
+ private _enableThinLineMaterial;
2412
+ private _syncLineColor;
2413
+ }
2414
+
2415
+ declare interface LineSystemBuilderOptions {
2416
+ lines: Vector3[][];
2417
+ updatable?: boolean;
2418
+ instance?: LinesMesh | null;
2419
+ colors?: Color4[][] | null;
2420
+ useVertexAlpha?: boolean;
2421
+ material?: unknown;
2367
2422
  }
2368
2423
 
2369
2424
  /**
@@ -2594,8 +2649,8 @@ export declare const MeshBuilder: {
2594
2649
  CreateRibbon(name: string, options: object, scene: Scene): Mesh;
2595
2650
  CreateTube(name: string, options: object, scene: Scene): Mesh;
2596
2651
  ExtrudeShape(name: string, options: object, scene: Scene): Mesh;
2597
- CreateLines(): never;
2598
- CreateLineSystem(): never;
2652
+ CreateLines(name: string, options: LinesBuilderOptions, scene?: Scene | null): LinesMesh;
2653
+ CreateLineSystem(name: string, options: LineSystemBuilderOptions, scene?: Scene | null): LinesMesh;
2599
2654
  CreateDashedLines(): never;
2600
2655
  CreateDecal(): never;
2601
2656
  CreateText(): never;
@@ -2860,8 +2915,69 @@ export declare class ParticleHelper {
2860
2915
  constructor();
2861
2916
  }
2862
2917
 
2918
+ /**
2919
+ * Babylon.js `ParticleSystem` — the built output of one NPE graph system. Backed
2920
+ * by a Lite `ParticleSystem`; the deterministic prewarm-and-freeze pattern used by
2921
+ * ported parity scenes (seed RNG → `start()` → N × `animate()` → `updateSpeed = 0`)
2922
+ * maps directly onto Lite's `startParticleSystem` / `animateParticleSystem`, with a
2923
+ * camera-facing billboard built and synced once the scene starts.
2924
+ */
2863
2925
  export declare class ParticleSystem {
2864
- constructor();
2926
+ name: string;
2865
2927
  /**
2928
+ * Babylon.js `ParticleSystem.preWarmStepOffset` — the step ratio applied during
2929
+ * prewarm cycles. Multiplies {@link updateSpeed} on every `animate(true)` call,
2930
+ * matching Babylon.js (which uses `updateSpeed * preWarmStepOffset` while
2931
+ * prewarming and the regular animation ratio otherwise).
2932
+ */
2933
+ preWarmStepOffset: number;
2934
+ private _texture;
2935
+ private _billboardScheduled;
2936
+ private _billboardOwnedBySet;
2937
+ /**
2938
+ * Babylon.js `new ParticleSystem(name, capacity, scene)`. The imperative
2939
+ * construction API (emitters, over-lifetime gradients, `minEmitBox`, a
2940
+ * GPU-compute path) is not backed: Babylon Lite builds particle systems only
2941
+ * from a serialized Node Particle Editor graph. Load a graph via
2942
+ * `NodeParticleSystemSet.Parse` / `ParseFromSnippetAsync` → `buildAsync` and read
2943
+ * its {@link ParticleSystemSet.systems} instead.
2944
+ */
2945
+ constructor();
2866
2946
  getClassName(): string;
2947
+ /** Babylon.js `ParticleSystem.updateSpeed` — simulation advance per frame. Proxies the Lite system. */
2948
+ get updateSpeed(): number;
2949
+ set updateSpeed(value: number);
2950
+ /**
2951
+ * Babylon.js `ParticleSystem.particleTexture` — the sprite texture. Recorded and
2952
+ * bound onto the Lite system when the billboard is built at engine start (the
2953
+ * compat `Texture` loads asynchronously, so its GPU handle is read after the
2954
+ * scene's pending texture loads settle).
2955
+ */
2956
+ get particleTexture(): Texture | null;
2957
+ set particleTexture(value: Texture | null);
2958
+ /**
2959
+ * Babylon.js `ParticleSystem.start()` — begin emission. Forwards to Lite
2960
+ * `startParticleSystem` (which clears the stopped flag and resets the frame
2961
+ * counter, so `start()` → `stop()` → `start()` resumes emission) and schedules
2962
+ * the camera-facing billboard build for engine start. The billboard build is
2963
+ * separately guarded, so it happens exactly once however often `start()` runs.
2964
+ */
2965
+ start(): void;
2966
+ /**
2967
+ * Babylon.js `ParticleSystem.animate(preWarmOnly?)` — advance the simulation by
2968
+ * one deterministic step. Forwards to Lite `animateParticleSystem` with Babylon.js's
2969
+ * step ratio: {@link preWarmStepOffset} while prewarming, otherwise the ratio `1`
2970
+ * used by the parity ports' seeded step loop.
2971
+ */
2972
+ animate(preWarmOnly?: boolean): void;
2973
+ /** Babylon.js `ParticleSystem.stop()` — stop emission; live particles drain. Forwards to Lite `stopParticleSystem`. */
2974
+ stop(): void;
2975
+ /** Babylon.js `ParticleSystem.dispose()` — stop the system. */
2976
+ dispose(): void;
2867
2977
  /**
2978
+ * Schedule the one-time billboard build. Deferred to engine start (via the
2979
+ * scene's `_deferAdd`, which runs after pending texture loads settle), so the
2980
+ * particle system is already prewarmed/frozen and its texture GPU handle is
2981
+ * ready. Mirrors the native Lite port's build → sync → add sequence.
2982
+ */
2983
+ private _scheduleBillboard;
2868
2984
  }
2869
2985
 
2870
2986
  /**
@@ -2870,19 +2986,26 @@ export declare class ParticleSystem {
2870
2986
  * scene. Directly constructing an empty set (`new ParticleSystemSet()`) is allowed
2871
2987
  * for parity but has no systems until produced by {@link NodeParticleSystemSet.buildAsync}.
2872
2988
  */
2873
- export declare class ParticleSystemSet {
2874
2989
  private _started;
2875
- getClassName(): string;
2990
+ export declare class ParticleSystemSet {
2876
2991
  private _started;
2877
2992
  getClassName(): string;
2878
2993
  /**
2879
- * Babylon.js `ParticleSystemSet.systems` — the array of per-system
2880
- * `ParticleSystem` handles. Not backed: Lite's node-particle runtime is a fused
2881
- * struct-of-arrays simulation with no per-system BJS `ParticleSystem` object to
2882
- * expose. Drive the set as a whole via {@link start} instead.
2994
+ * Babylon.js `ParticleSystemSet.systems` — the per-system {@link ParticleSystem}
2995
+ * handles. Each wraps one Lite `NodeParticleSet.systems[i]`, exposing the
2996
+ * runtime subset Lite backs (`start` / `animate` / `stop` / `updateSpeed` /
2997
+ * `particleTexture`). An empty (directly-constructed) set has no systems.
2883
2998
  */
2884
- get systems(): never;
2999
+ get systems(): ParticleSystem[];
2885
3000
  /**
2886
3001
  * Babylon.js `ParticleSystemSet.start()` — begin all systems. Forwards to Lite
2887
3002
  * `registerNodeParticleSet`, which renders each system as a camera-facing
2888
3003
  * billboard and advances it once per frame. Idempotent.
3004
+ *
3005
+ * Per-system wrapper state (`systems[i].particleTexture`) is pushed onto the
3006
+ * backing Lite systems first, so the standard
3007
+ * `set.systems[i].particleTexture = texture; set.start()` sequence renders with
3008
+ * the assigned texture rather than the graph's. Registration is deferred to
3009
+ * engine start (`scene._deferAdd`, which runs after the scene's pending texture
3010
+ * loads settle) because a compat `Texture` resolves its GPU handle
3011
+ * asynchronously and Lite's billboard build needs it.
2889
3012
  */
2890
3013
  start(): void;
2891
3014
  /**