@babylonjs/lite-compat 1.17.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
@@ -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
@@ -1412,7 +1412,10 @@ export declare class CSG2 {
1412
1412
  * rather than as a standalone GPU texture object. This compat `CubeTexture`
1413
1413
  * therefore acts as a lightweight handle that records the environment URL; the
1414
1414
  * actual GPU work happens when it is assigned to `scene.environmentTexture` and
1415
- * 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`.
1416
1419
  */
1417
1420
  export declare class CubeTexture extends BaseTexture {
1418
1421
  /** Source URL of the (prefiltered) environment. */
@@ -2912,8 +2915,69 @@ export declare class ParticleHelper {
2912
2915
  constructor();
2913
2916
  }
2914
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
+ */
2915
2925
  export declare class ParticleSystem {
2916
- constructor();
2926
+ name: string;
2917
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();
2918
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;
2919
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;
2920
2984
  }
2921
2985
 
2922
2986
  /**
@@ -2922,19 +2986,26 @@ export declare class ParticleSystem {
2922
2986
  * scene. Directly constructing an empty set (`new ParticleSystemSet()`) is allowed
2923
2987
  * for parity but has no systems until produced by {@link NodeParticleSystemSet.buildAsync}.
2924
2988
  */
2925
- export declare class ParticleSystemSet {
2926
2989
  private _started;
2927
- getClassName(): string;
2990
+ export declare class ParticleSystemSet {
2928
2991
  private _started;
2929
2992
  getClassName(): string;
2930
2993
  /**
2931
- * Babylon.js `ParticleSystemSet.systems` — the array of per-system
2932
- * `ParticleSystem` handles. Not backed: Lite's node-particle runtime is a fused
2933
- * struct-of-arrays simulation with no per-system BJS `ParticleSystem` object to
2934
- * 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.
2935
2998
  */
2936
- get systems(): never;
2999
+ get systems(): ParticleSystem[];
2937
3000
  /**
2938
3001
  * Babylon.js `ParticleSystemSet.start()` — begin all systems. Forwards to Lite
2939
3002
  * `registerNodeParticleSet`, which renders each system as a camera-facing
2940
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.
2941
3012
  */
2942
3013
  start(): void;
2943
3014
  /**
package/index.js CHANGED
@@ -3,7 +3,7 @@ var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { en
3
3
  var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
4
4
  import { V as Vector3, u as unsupported, L as LiteCompatError, N as Node, M as Matrix, C as Color3, S as StandardMaterial, a as Color4, b as Mesh, T as TransformNode, l as liteBackedVector3, Q as Quaternion } from "./meshes-0TVZfbq3.js";
5
5
  import { A, B, c, d, e, f, g, h, i, j, k, m, n, o, p, G, I, q, r, s, P, t, v, w, x, y, z, D, E, F, H, J, K, O } from "./meshes-0TVZfbq3.js";
6
- import { VERSION, createEngine, onBeforeRender, stopEngine, resizeEngine, setEngineSize, disposeEngine, uploadImageToArrayLayer, enableMirroredMeshes, registerSceneWithShadowSupport, registerScene, startEngine, createNullEngine, stepScene, setPhysicsTimestep, setPhysicsGravity, disposePhysics, createHavokWorld, createArcRotateCamera, attachControl, getCameraPosition, getViewMatrix, getProjectionMatrix, createGeospatialCamera, setGeospatialOrientation, attachGeospatialControls, createFreeCamera, attachFreeControl, setAnimationAdditive, playAnimation, pauseAnimation, goToFrame, stopAnimation, createSceneContext, updateAnimationManager, setFog, setClipPlane, loadHdrEnvironment, loadDdsEnvironment, loadEnvironment, createDefaultCamera, addToScene, createHemisphericLight, createAnimationManager, enableAnimationBlending, addAnimationGroup, disposeScene, createDirectionalLight, createPointLight, createSpotLight, createCsgFromMesh, csgSubtract, csgIntersect, csgUnion, createMeshFromCsg, createCsg2FromMesh, csg2Subtract, csg2Intersect, csg2Add, createMeshesFromCsg2, disposeCsg2, initializeCsg2Async, createMorphTargets, setMorphTargetWeights, createTransformNode, bakeCurrentTransformIntoVertices, loadSOG, loadSPZ, loadSplat, createDynamicTexture, updateDynamicTexture, createTexture2DFromPixels, updateTexture2DFromPixels, createTexture3DFromPixels, loadBasisTexture2D, loadKtxTexture2D, loadTexture2D, createTexture2DArrayFromUrls, createTexture2DArrayFromKtx2, loadImageToArrayLayer, createTexture2DArray, createTexture2DArrayFromPixels, updateTexture2DArrayFromPixels, loadBabylon, loadGltf, resetVariant, getVariantNames, selectVariant, disposePicker, createGpuPicker, pickAsync, createAxisDragGizmo, attachAxisDragGizmoToNode, disposeAxisDragGizmo, createAxisScaleGizmo, attachAxisScaleGizmoToNode, disposeAxisScaleGizmo, createBoundingBoxGizmo, attachBoundingBoxGizmoToNode, disposeBoundingBoxGizmo, createCameraGizmo, attachCameraGizmoToCamera, disposeCameraGizmo, createLightGizmo, attachLightGizmoToLight, disposeLightGizmo, createPlaneDragGizmo, attachPlaneDragGizmoToNode, disposePlaneDragGizmo, createPlaneRotationGizmo, attachPlaneRotationGizmoToNode, disposePlaneRotationGizmo, createPositionGizmo, setPositionGizmoLocalCoordinates, attachPositionGizmoToNode, disposePositionGizmo, createRotationGizmo, setRotationGizmoLocalCoordinates, attachRotationGizmoToNode, disposeRotationGizmo, createScaleGizmo, setScaleGizmoLocalCoordinates, attachScaleGizmoToNode, disposeScaleGizmo, createUtilityLayer, registerUtilityLayer, disposeUtilityLayer, addBillboardSpriteIndex, updateBillboardSpriteIndex, loadSpriteAtlas, createFacingBillboardSystem, addFacingBillboardSystem, billboardBlendAdditive, billboardBlendAlpha, spriteBlendPremultiplied, spriteBlendAdditive, spriteBlendAlpha, createSprite2DLayer, addSprite2DIndex, createSpriteRenderer, registerSpriteRenderer, updateSprite2DIndex, createPcfSpotlightShadowGenerator, createPcfDirectionalShadowGenerator, createEsmDirectionalShadowGenerator, setShadowTaskCasterMeshes, parseNodeMaterialFromSnippet, createGridMaterial, getByteFrequencyData, getFloatFrequencyData, getByteTimeDomainData, getFloatTimeDomainData, enableAnalyzer, setSpatialPosition, setSpatialOrientation, enableSpatial, setSpatialListenerPosition, setSpatialListener, updateSpatialAudio, enableStereo, setStereoPan, disposeAudioBus, setBusVolume, getMasterVolume, setMasterVolume, unlockAudioEngineAsync, createSoundAsync, createSoundBufferAsync, createStreamingSoundAsync, createAudioBusAsync, createSoundSourceAsync, createMicrophoneSoundSourceAsync, disposeAudioEngine, createAudioEngineAsync, disposeSoundSource, setSoundSourceVolume, playSound, pauseSound, resumeSound, stopSound, disposeSound, setSoundVolume, playStreamingSound, pauseStreamingSound, resumeStreamingSound, stopStreamingSound, preloadStreamingInstanceAsync, preloadStreamingInstancesAsync, disposeStreamingSound, setStreamingSoundVolume, parseNodeParticleSetFromSnippet, registerNodeParticleSet, stopParticleSystem } from "@babylonjs/lite";
6
+ import { VERSION, createEngine, onBeforeRender, stopEngine, resizeEngine, setEngineSize, disposeEngine, uploadImageToArrayLayer, enableMirroredMeshes, registerSceneWithShadowSupport, registerScene, startEngine, createNullEngine, stepScene, setPhysicsTimestep, setPhysicsGravity, disposePhysics, createHavokWorld, createArcRotateCamera, attachControl, getCameraPosition, getViewMatrix, getProjectionMatrix, createGeospatialCamera, setGeospatialOrientation, attachGeospatialControls, createFreeCamera, attachFreeControl, setAnimationAdditive, playAnimation, pauseAnimation, goToFrame, stopAnimation, createSceneContext, updateAnimationManager, setFog, setClipPlane, loadHdrEnvironment, loadDdsEnvironment, loadEnvironment, createDefaultCamera, addToScene, createHemisphericLight, createAnimationManager, enableAnimationBlending, addAnimationGroup, disposeScene, createDirectionalLight, createPointLight, createSpotLight, createCsgFromMesh, csgSubtract, csgIntersect, csgUnion, createMeshFromCsg, createCsg2FromMesh, csg2Subtract, csg2Intersect, csg2Add, createMeshesFromCsg2, disposeCsg2, initializeCsg2Async, createMorphTargets, setMorphTargetWeights, createTransformNode, bakeCurrentTransformIntoVertices, loadSOG, loadSPZ, loadSplat, createDynamicTexture, updateDynamicTexture, createTexture2DFromPixels, updateTexture2DFromPixels, createTexture3DFromPixels, loadBasisTexture2D, loadKtxTexture2D, loadTexture2D, createTexture2DArrayFromUrls, createTexture2DArrayFromKtx2, loadImageToArrayLayer, createTexture2DArray, createTexture2DArrayFromPixels, updateTexture2DArrayFromPixels, loadBabylon, loadGltf, resetVariant, getVariantNames, selectVariant, disposePicker, createGpuPicker, pickAsync, createAxisDragGizmo, attachAxisDragGizmoToNode, disposeAxisDragGizmo, createAxisScaleGizmo, attachAxisScaleGizmoToNode, disposeAxisScaleGizmo, createBoundingBoxGizmo, attachBoundingBoxGizmoToNode, disposeBoundingBoxGizmo, createCameraGizmo, attachCameraGizmoToCamera, disposeCameraGizmo, createLightGizmo, attachLightGizmoToLight, disposeLightGizmo, createPlaneDragGizmo, attachPlaneDragGizmoToNode, disposePlaneDragGizmo, createPlaneRotationGizmo, attachPlaneRotationGizmoToNode, disposePlaneRotationGizmo, createPositionGizmo, setPositionGizmoLocalCoordinates, attachPositionGizmoToNode, disposePositionGizmo, createRotationGizmo, setRotationGizmoLocalCoordinates, attachRotationGizmoToNode, disposeRotationGizmo, createScaleGizmo, setScaleGizmoLocalCoordinates, attachScaleGizmoToNode, disposeScaleGizmo, createUtilityLayer, registerUtilityLayer, disposeUtilityLayer, addBillboardSpriteIndex, updateBillboardSpriteIndex, loadSpriteAtlas, createFacingBillboardSystem, addFacingBillboardSystem, billboardBlendAdditive, billboardBlendAlpha, spriteBlendPremultiplied, spriteBlendAdditive, spriteBlendAlpha, createSprite2DLayer, addSprite2DIndex, createSpriteRenderer, registerSpriteRenderer, updateSprite2DIndex, createPcfSpotlightShadowGenerator, createPcfDirectionalShadowGenerator, createEsmDirectionalShadowGenerator, setShadowTaskCasterMeshes, parseNodeMaterialFromSnippet, createGridMaterial, getByteFrequencyData, getFloatFrequencyData, getByteTimeDomainData, getFloatTimeDomainData, enableAnalyzer, setSpatialPosition, setSpatialOrientation, enableSpatial, setSpatialListenerPosition, setSpatialListener, updateSpatialAudio, enableStereo, setStereoPan, disposeAudioBus, setBusVolume, getMasterVolume, setMasterVolume, unlockAudioEngineAsync, createSoundAsync, createSoundBufferAsync, createStreamingSoundAsync, createAudioBusAsync, createSoundSourceAsync, createMicrophoneSoundSourceAsync, disposeAudioEngine, createAudioEngineAsync, disposeSoundSource, setSoundSourceVolume, playSound, pauseSound, resumeSound, stopSound, disposeSound, setSoundVolume, playStreamingSound, pauseStreamingSound, resumeStreamingSound, stopStreamingSound, preloadStreamingInstanceAsync, preloadStreamingInstancesAsync, disposeStreamingSound, setStreamingSoundVolume, startParticleSystem, animateParticleSystem, stopParticleSystem, createParticleBillboard, syncParticleBillboard, parseNodeParticleSetFromSnippet, registerNodeParticleSet } from "@babylonjs/lite";
7
7
  const Epsilon = 1e-3;
8
8
  const ToRadians = Math.PI / 180;
9
9
  const ToDegrees = 180 / Math.PI;
@@ -7031,14 +7031,6 @@ class ClusteredLightContainer {
7031
7031
  unsupported("ClusteredLightContainer", "Clustered lighting is not exposed by the Babylon Lite public API; the compat layer cannot wrap it.");
7032
7032
  }
7033
7033
  }
7034
- class ParticleSystem {
7035
- constructor() {
7036
- unsupported(
7037
- "ParticleSystem",
7038
- "Babylon Lite backs serialized Node Particle Editor graphs via `NodeParticleSystemSet` (`Parse`/`ParseFromSnippetAsync` → `buildAsync` → `start`), not the imperative classic `ParticleSystem` construction API (emitters, over-lifetime gradients, `minEmitBox`)."
7039
- );
7040
- }
7041
- }
7042
7034
  class GPUParticleSystem {
7043
7035
  constructor() {
7044
7036
  unsupported(
@@ -7363,6 +7355,162 @@ class SceneOptimizer {
7363
7355
  unsupported("SceneOptimizer", "Automatic scene optimisation is not implemented in the compat layer.");
7364
7356
  }
7365
7357
  }
7358
+ class ParticleSystem {
7359
+ /**
7360
+ * Babylon.js `new ParticleSystem(name, capacity, scene)`. The imperative
7361
+ * construction API (emitters, over-lifetime gradients, `minEmitBox`, a
7362
+ * GPU-compute path) is not backed: Babylon Lite builds particle systems only
7363
+ * from a serialized Node Particle Editor graph. Load a graph via
7364
+ * `NodeParticleSystemSet.Parse` / `ParseFromSnippetAsync` → `buildAsync` and read
7365
+ * its {@link ParticleSystemSet.systems} instead.
7366
+ */
7367
+ constructor() {
7368
+ __publicField(this, "name", "");
7369
+ /** @internal The backing Lite particle system (null on a bare, unbuilt instance). */
7370
+ __publicField(this, "_lite", null);
7371
+ /** @internal The compat scene this system was built against. */
7372
+ __publicField(this, "_scene", null);
7373
+ /**
7374
+ * Babylon.js `ParticleSystem.preWarmStepOffset` — the step ratio applied during
7375
+ * prewarm cycles. Multiplies {@link updateSpeed} on every `animate(true)` call,
7376
+ * matching Babylon.js (which uses `updateSpeed * preWarmStepOffset` while
7377
+ * prewarming and the regular animation ratio otherwise).
7378
+ */
7379
+ __publicField(this, "preWarmStepOffset", 1);
7380
+ __publicField(this, "_texture", null);
7381
+ __publicField(this, "_billboardScheduled", false);
7382
+ __publicField(this, "_billboardOwnedBySet", false);
7383
+ unsupported(
7384
+ "ParticleSystem",
7385
+ "Babylon Lite builds particle systems only from a serialized Node Particle Editor graph, not the imperative classic `ParticleSystem` construction API (emitters, over-lifetime gradients, `minEmitBox`). Use `NodeParticleSystemSet.Parse`/`ParseFromSnippetAsync` → `buildAsync` and drive `set.systems[i]`."
7386
+ );
7387
+ }
7388
+ /**
7389
+ * @internal Build a `ParticleSystem` backed by a Lite `ParticleSystem` produced
7390
+ * by an NPE graph build. Bypasses the throwing public constructor.
7391
+ */
7392
+ static _fromLite(lite, scene) {
7393
+ const system = Object.create(ParticleSystem.prototype);
7394
+ system.name = "";
7395
+ system._lite = lite;
7396
+ system._scene = scene;
7397
+ system.preWarmStepOffset = 1;
7398
+ system._texture = null;
7399
+ system._billboardScheduled = false;
7400
+ system._billboardOwnedBySet = false;
7401
+ return system;
7402
+ }
7403
+ getClassName() {
7404
+ return "ParticleSystem";
7405
+ }
7406
+ /** Babylon.js `ParticleSystem.updateSpeed` — simulation advance per frame. Proxies the Lite system. */
7407
+ get updateSpeed() {
7408
+ var _a;
7409
+ return ((_a = this._lite) == null ? void 0 : _a.updateSpeed) ?? 0;
7410
+ }
7411
+ set updateSpeed(value) {
7412
+ if (this._lite) {
7413
+ this._lite.updateSpeed = value;
7414
+ }
7415
+ }
7416
+ /**
7417
+ * Babylon.js `ParticleSystem.particleTexture` — the sprite texture. Recorded and
7418
+ * bound onto the Lite system when the billboard is built at engine start (the
7419
+ * compat `Texture` loads asynchronously, so its GPU handle is read after the
7420
+ * scene's pending texture loads settle).
7421
+ */
7422
+ get particleTexture() {
7423
+ return this._texture;
7424
+ }
7425
+ set particleTexture(value) {
7426
+ this._texture = value;
7427
+ }
7428
+ /**
7429
+ * Babylon.js `ParticleSystem.start()` — begin emission. Forwards to Lite
7430
+ * `startParticleSystem` (which clears the stopped flag and resets the frame
7431
+ * counter, so `start()` → `stop()` → `start()` resumes emission) and schedules
7432
+ * the camera-facing billboard build for engine start. The billboard build is
7433
+ * separately guarded, so it happens exactly once however often `start()` runs.
7434
+ */
7435
+ start() {
7436
+ if (!this._lite) {
7437
+ return;
7438
+ }
7439
+ startParticleSystem(this._lite);
7440
+ this._scheduleBillboard();
7441
+ }
7442
+ /**
7443
+ * Babylon.js `ParticleSystem.animate(preWarmOnly?)` — advance the simulation by
7444
+ * one deterministic step. Forwards to Lite `animateParticleSystem` with Babylon.js's
7445
+ * step ratio: {@link preWarmStepOffset} while prewarming, otherwise the ratio `1`
7446
+ * used by the parity ports' seeded step loop.
7447
+ */
7448
+ animate(preWarmOnly = false) {
7449
+ if (this._lite) {
7450
+ animateParticleSystem(this._lite, preWarmOnly ? this.preWarmStepOffset : 1);
7451
+ }
7452
+ }
7453
+ /** Babylon.js `ParticleSystem.stop()` — stop emission; live particles drain. Forwards to Lite `stopParticleSystem`. */
7454
+ stop() {
7455
+ if (this._lite) {
7456
+ stopParticleSystem(this._lite);
7457
+ }
7458
+ }
7459
+ /** Babylon.js `ParticleSystem.dispose()` — stop the system. */
7460
+ dispose() {
7461
+ this.stop();
7462
+ }
7463
+ /**
7464
+ * @internal Bind the recorded {@link particleTexture}'s GPU handle onto the backing
7465
+ * Lite system. Called from the deferred per-system billboard build and from
7466
+ * {@link ParticleSystemSet.start} before set-level registration, so a
7467
+ * wrapper-assigned texture wins over whatever the graph baked in. A no-op while
7468
+ * the compat `Texture` is still loading (callers run after the scene's pending
7469
+ * texture loads settle).
7470
+ */
7471
+ _bindTexture() {
7472
+ var _a;
7473
+ const liteTexture = (_a = this._texture) == null ? void 0 : _a._lite;
7474
+ if (this._lite && liteTexture) {
7475
+ this._lite.texture = liteTexture;
7476
+ }
7477
+ }
7478
+ /**
7479
+ * @internal Hand billboard rendering to the owning {@link ParticleSystemSet}: Lite's
7480
+ * `registerNodeParticleSet` builds and per-frame syncs a billboard for every system
7481
+ * in the set, so this wrapper's one-shot build must be skipped to avoid rendering
7482
+ * the same particles twice.
7483
+ */
7484
+ _releaseBillboardToSet() {
7485
+ this._billboardOwnedBySet = true;
7486
+ }
7487
+ /**
7488
+ * Schedule the one-time billboard build. Deferred to engine start (via the
7489
+ * scene's `_deferAdd`, which runs after pending texture loads settle), so the
7490
+ * particle system is already prewarmed/frozen and its texture GPU handle is
7491
+ * ready. Mirrors the native Lite port's build → sync → add sequence.
7492
+ */
7493
+ _scheduleBillboard() {
7494
+ if (this._billboardScheduled || !this._scene || !this._lite) {
7495
+ return;
7496
+ }
7497
+ this._billboardScheduled = true;
7498
+ const scene = this._scene;
7499
+ const lite = this._lite;
7500
+ scene._deferAdd(() => {
7501
+ if (this._billboardOwnedBySet) {
7502
+ return;
7503
+ }
7504
+ this._bindTexture();
7505
+ if (!lite.texture) {
7506
+ return;
7507
+ }
7508
+ const billboard = createParticleBillboard(lite);
7509
+ syncParticleBillboard(lite, billboard);
7510
+ addFacingBillboardSystem(scene._lite, billboard);
7511
+ });
7512
+ }
7513
+ }
7366
7514
  class ParticleSystemSet {
7367
7515
  constructor() {
7368
7516
  /** @internal The built Lite node-particle set (null for a directly-constructed empty set). */
@@ -7370,33 +7518,63 @@ class ParticleSystemSet {
7370
7518
  /** @internal The compat scene the set was built against (set by `buildAsync`). */
7371
7519
  __publicField(this, "_scene", null);
7372
7520
  __publicField(this, "_started", false);
7521
+ /** @internal Cached per-system wrappers (stable identity across `systems` reads). */
7522
+ __publicField(this, "_systems", null);
7373
7523
  }
7374
7524
  getClassName() {
7375
7525
  return "ParticleSystemSet";
7376
7526
  }
7377
7527
  /**
7378
- * Babylon.js `ParticleSystemSet.systems` — the array of per-system
7379
- * `ParticleSystem` handles. Not backed: Lite's node-particle runtime is a fused
7380
- * struct-of-arrays simulation with no per-system BJS `ParticleSystem` object to
7381
- * expose. Drive the set as a whole via {@link start} instead.
7528
+ * Babylon.js `ParticleSystemSet.systems` — the per-system {@link ParticleSystem}
7529
+ * handles. Each wraps one Lite `NodeParticleSet.systems[i]`, exposing the
7530
+ * runtime subset Lite backs (`start` / `animate` / `stop` / `updateSpeed` /
7531
+ * `particleTexture`). An empty (directly-constructed) set has no systems.
7382
7532
  */
7383
7533
  get systems() {
7384
- return unsupported(
7385
- "ParticleSystemSet.systems",
7386
- "Babylon Lite's node-particle runtime is a fused struct-of-arrays simulation and exposes no per-system BJS ParticleSystem handle. Start/stop the whole set via `set.start()` / `set.dispose()`."
7387
- );
7534
+ if (!this._lite || !this._scene) {
7535
+ return [];
7536
+ }
7537
+ if (!this._systems) {
7538
+ const scene = this._scene;
7539
+ this._systems = this._lite.systems.map((s2) => {
7540
+ const system = ParticleSystem._fromLite(s2, scene);
7541
+ if (this._started) {
7542
+ system._releaseBillboardToSet();
7543
+ }
7544
+ return system;
7545
+ });
7546
+ }
7547
+ return this._systems;
7388
7548
  }
7389
7549
  /**
7390
7550
  * Babylon.js `ParticleSystemSet.start()` — begin all systems. Forwards to Lite
7391
7551
  * `registerNodeParticleSet`, which renders each system as a camera-facing
7392
7552
  * billboard and advances it once per frame. Idempotent.
7553
+ *
7554
+ * Per-system wrapper state (`systems[i].particleTexture`) is pushed onto the
7555
+ * backing Lite systems first, so the standard
7556
+ * `set.systems[i].particleTexture = texture; set.start()` sequence renders with
7557
+ * the assigned texture rather than the graph's. Registration is deferred to
7558
+ * engine start (`scene._deferAdd`, which runs after the scene's pending texture
7559
+ * loads settle) because a compat `Texture` resolves its GPU handle
7560
+ * asynchronously and Lite's billboard build needs it.
7393
7561
  */
7394
7562
  start() {
7395
7563
  if (this._started || !this._lite || !this._scene) {
7396
7564
  return;
7397
7565
  }
7398
7566
  this._started = true;
7399
- registerNodeParticleSet(this._scene._lite, this._lite, { autoStart: true });
7567
+ const scene = this._scene;
7568
+ const lite = this._lite;
7569
+ for (const system of this._systems ?? []) {
7570
+ system._releaseBillboardToSet();
7571
+ }
7572
+ scene._deferAdd(() => {
7573
+ for (const system of this._systems ?? []) {
7574
+ system._bindTexture();
7575
+ }
7576
+ registerNodeParticleSet(scene._lite, lite, { autoStart: true });
7577
+ });
7400
7578
  }
7401
7579
  /**
7402
7580
  * Babylon.js `ParticleSystemSet.dispose()` — stop the systems. Lite exposes no