@ignifx/core 0.3.1 → 0.5.0

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/dist/index.js CHANGED
@@ -1,9 +1,8 @@
1
1
  import { a as CORE_ERROR_MESSAGES, c as THIRD_PARTY_ERROR_PREFIX, i as isIgnifxError, l as isValidErrorCode, n as assertNever, o as CoreErrorCode, r as formatErrorMessage, s as ErrorRange, t as IgnifxError } from "./ignifx-error-R1ma_Lzv.js";
2
- import { _ as smoothStep, a as clamp, c as deltaAngleDegrees, d as lerpAngleDegrees, f as moveTowards, g as sign, h as repeat, i as approximately, l as inverseLerp, m as radToDeg, n as EPSILON, o as clamp01, p as pingPong, r as RAD_TO_DEG, s as degToRad, t as DEG_TO_RAD, u as lerp, v as wrapAngleDegrees } from "./math-utils-BcDnL-gi.js";
2
+ import { _ as sign, a as approximately, c as degToRad, d as lerp, f as lerpAngleDegrees, g as repeat, h as radToDeg, i as RAD_TO_DEG, l as deltaAngleDegrees, m as pingPong, n as DEG_TO_RAD, o as clamp, p as moveTowards, r as EPSILON, s as clamp01, t as Color, u as inverseLerp, v as smoothStep, y as wrapAngleDegrees } from "./color-CpvebMIh.js";
3
3
  import { A as linkParent, B as tagNode, C as setMeshSubtreeVisible, D as updateMeshUvs$1, E as updateMeshPositions$1, F as readNodeTag, I as readWorldMatrix, L as reparentKeepingWorld, M as localRotation, N as localScale, O as createNode, P as parentNode, R as setNodeName, S as setMeshRenderOrder, T as updateMeshNormals$1, V as worldMatrixVersion, a as createCapsuleMesh, b as setMeshPickable, c as createMeshFromGeometry, d as createTorusMesh, g as removeMeshFromScene, h as recomputeMeshBounds, i as createBoxMesh, j as localPosition, k as disposeNode, l as createPlaneMesh, m as overrideSubtreeMaterials, n as cloneMeshUnderNode, o as createCylinderMesh, p as disposeMeshTemplate, r as collectSubtreeMeshes, s as createGroundMesh, t as addMeshToScene, u as createSphereMesh, v as setMeshId, w as updateMeshColors$1, x as setMeshReceiveShadows, y as setMeshMaterial, z as setNodeSelfVisible } from "./mesh-CnK_PX46.js";
4
- import { a as setSceneClearColor, c as setSceneFog, l as setSceneImageProcessingOptions, n as installSceneEnvironment, o as setSceneEnvironmentBlur, r as loadSceneEnvironment, s as setSceneEnvironmentRotation, t as TONE_MAPPING_NAMES } from "./environment-C_JfuAjj.js";
4
+ import { a as setSceneClearColor, c as setSceneFog, l as setSceneImageProcessingOptions, n as installSceneEnvironment, o as setSceneEnvironmentBlur, r as loadSceneEnvironment, s as setSceneEnvironmentRotation, t as TONE_MAPPING_NAMES } from "./environment-_EeJXzjk.js";
5
5
  import { a as defineMaterialPlugin, c as MATERIAL_ALPHA_MODES, d as createStandardMaterialFromProps, f as markMaterialDirty, g as setPbrMetallicRoughness, h as setPbrBaseColor, i as MATERIAL_PLUGIN_SAMPLER_BUDGET, l as createDefaultMaterial, m as setMaterialAlpha, n as MATERIAL_PLUGIN_DEFAULT_PRIORITY, o as isLiteMaterialPluginPoint, r as MATERIAL_PLUGIN_RESERVED_NAMES, t as LITE_MATERIAL_PLUGIN_POINTS, u as createPbrMaterialFromProps } from "./material-plugin-CTaWZXEk.js";
6
- import { t as Color } from "./color-DrR6GFTd.js";
7
6
  import { a as postEffectValuesCodec, i as declaredTextureBinding, n as POST_EFFECT_FUNCTION, o as asJsonArray, r as customEffect, s as asJsonObject, t as POST_EFFECT_BUILTIN_UNIFORMS } from "./post-effect-C42XJFmo.js";
8
7
  import { a as SHADER_BLEND_MODES, c as SHADER_KINDS, d as SURFACE_HOOK_NAMES, f as SURFACE_UNIFORM_BLOCK, i as SHADER_ATTRIBUTE_NAMES, l as SHADER_TEXTURE_FALLBACKS, o as SHADER_CULL_MODES, r as LITE_SYSTEM_UNIFORM_NAMES, s as SHADER_INSTANCING_MODES, t as IGNIFX_UNIFORM_NAMES, u as SHADER_UNIFORM_TYPES } from "./shader-declaration-5q__jycG.js";
9
8
  import { acquireTexture, addTask, addToScene, buildFrameGraphTask, captureScreenshot, cloneTransformNode, createBloomPostProcessTask, createCopyToTextureTask, createCsmDirectionalShadowGenerator, createDirectionalLight, createEngine, createEsmDirectionalShadowGenerator, createFontFromBuffer, createFreeCamera, createGpuPicker, createHemisphericLight, createImageProcessingTask, createMeshFromData, createNullEngine, createPcfDirectionalShadowGenerator, createPcfSpotlightShadowGenerator, createPointLight, createRenderTarget, createRenderTask, createSceneContext, createSmaaPostProcessTask, createSpotLight, createStorageBuffer, createTexture2DFromPixels, disableOrthographicCamera, disposeEngine, disposePicker, disposeScene, disposeStorageBuffer, enableBoneControl, enableDeviceLostSceneRecovery, enableMaterialPlugins, enableMaterialStencil, enableOrthographicCamera, enablePbrLightmap, enableStandardSkeleton, forceWebGpuDeviceLossForTesting, getEffectiveAspectRatio, getFrameGraph, getProjectionMatrix, getRenderTaskGpuTimings, getViewMatrix, getViewProjectionMatrix, isShaderMaterial, loadTexture2D, onBeforeRender, pickAsync, pickWithRay, rebuildSceneRenderables, registerScene, registerSceneWithShadowSupport, releaseTexture, removeFromScene, resizeEngine, resolveCameraViewport, setGpuTimingEnabled, setShadowTaskCasterMeshes, setSubtreeVisible, setSurfaceSize, startEngine, stopEngine, updateStorageBuffer, updateTexture2DFromPixels } from "@babylonjs/lite";
@@ -7259,7 +7258,7 @@ const ENVIRONMENT_FILE_EXTENSION = ".environment.json";
7259
7258
  * @example
7260
7259
  * ```ts
7261
7260
  * const studio = await app.assets.loadAsync<EnvironmentAsset>("environments/studio.env");
7262
- * world.createEntity("Env").addComponent(Environment, { environment: studio.retain() });
7261
+ * world.createEntity("Env").addComponent(Environment, { environment: studio });
7263
7262
  * ```
7264
7263
  *
7265
7264
  * @public
@@ -7461,6 +7460,14 @@ function installLoadedEnvironment(scene, textures) {
7461
7460
  * default was a flat box painted in the clear colour. So a bare `.env` gets a real background, and
7462
7461
  * the component's default `skybox.enabled: true` agrees with it.
7463
7462
  *
7463
+ * ## `clearColor` is optional, as the camera's is
7464
+ *
7465
+ * `null`, the default, means "leave the scene's clear colour alone", exactly as on `Camera`: an
7466
+ * environment added for its fog or its lighting keeps the `rendering.clearColor` setting standing.
7467
+ * Until 2026-10-11 the field was a plain colour defaulting to black, and the first sync wrote that
7468
+ * black over the setting whether or not anything had asked for it. Setting the field back to `null`
7469
+ * does not restore the setting either — `null` stops steering, it does not undo.
7470
+ *
7464
7471
  * ## `ambientColor` does not exist
7465
7472
  *
7466
7473
  * §2.5 lists an `ambientColor` field. Babylon Lite 1.27.0 has no scene-level ambient term:
@@ -7501,17 +7508,18 @@ const SKYBOX_SIZE_DEFAULT = 20;
7501
7508
  * ```ts
7502
7509
  * const studio = await app.assets.loadAsync<EnvironmentAsset>("environments/studio.env");
7503
7510
  * const env = world.createEntity("Environment").addComponent(Environment, {
7504
- * environment: studio.retain(),
7511
+ * environment: studio,
7505
7512
  * imageProcessing: { exposure: 1.2, contrast: 1, toneMapping: "aces" },
7506
7513
  * });
7507
7514
  * ```
7508
7515
  *
7509
7516
  * @example
7510
- * Switching environments at runtime. Both handles stay retained, so switching back costs nothing.
7517
+ * Switching environments at runtime. The field takes no reference of its own: both handles stay
7518
+ * loaded until you release them, so switching back costs nothing.
7511
7519
  *
7512
7520
  * ```ts
7513
7521
  * const night = await app.assets.loadAsync<EnvironmentAsset>("environments/night.env");
7514
- * env.environment = night.retain();
7522
+ * env.environment = night;
7515
7523
  * ```
7516
7524
  *
7517
7525
  * @public
@@ -7537,6 +7545,8 @@ var Environment = class Environment extends Component {
7537
7545
  #trackedEnvironment = null;
7538
7546
  #installedEnvironment = null;
7539
7547
  #hasWarnedAboutSkybox = false;
7548
+ /** Set by {@link Environment.reclaim}: the next sync re-installs even an unchanged asset. */
7549
+ #isReclaimed = false;
7540
7550
  /**
7541
7551
  * The environment asset this component installed on the scene.
7542
7552
  *
@@ -7570,6 +7580,25 @@ var Environment = class Environment extends Component {
7570
7580
  this.#installedEnvironment = null;
7571
7581
  }
7572
7582
  /**
7583
+ * Forgets what this component last wrote, so its next sync writes every field again.
7584
+ *
7585
+ * @remarks
7586
+ * The `PreRender` system calls it when this component becomes the winning environment. Another
7587
+ * one may have written the scene since this one last did — it won, and has now been disabled or
7588
+ * removed — and a component that only writes what changed since *its own* last write would
7589
+ * otherwise leave the other's fog, clear colour and cube map in place.
7590
+ *
7591
+ * @internal
7592
+ */
7593
+ reclaim() {
7594
+ this.#appliedRotation = NaN;
7595
+ this.#appliedBlur = NaN;
7596
+ this.#appliedFog = "";
7597
+ this.#appliedClearColor = "";
7598
+ this.#appliedImageProcessing = "";
7599
+ this.#isReclaimed = true;
7600
+ }
7601
+ /**
7573
7602
  * Writes every field that changed onto the scene. The `PreRender` system calls it for the winning
7574
7603
  * environment only.
7575
7604
  *
@@ -7589,16 +7618,20 @@ var Environment = class Environment extends Component {
7589
7618
  return installed;
7590
7619
  }
7591
7620
  /**
7592
- * Writes the clear colour, decoded to linear.
7621
+ * Writes the clear colour.
7593
7622
  *
7594
7623
  * @remarks
7595
- * Only when the field changed, which is what leaves the `rendering.clearColor` setting standing
7596
- * in a world whose `Environment` never touches its own — and what keeps the main camera's
7624
+ * Nothing while the field is `null`, which is what leaves the `rendering.clearColor` setting
7625
+ * standing; otherwise only when the colour changed, which is what keeps the main camera's
7597
7626
  * override, written every frame, on top of this one (`RendererImpl.applyClearColor`).
7598
7627
  *
7599
7628
  * @param renderer - The rendering service, for the scene.
7600
7629
  */
7601
7630
  #applyClearColor(renderer) {
7631
+ if (this.clearColor === null) {
7632
+ this.#appliedClearColor = "";
7633
+ return;
7634
+ }
7602
7635
  const key = colorKey$1(this.clearColor);
7603
7636
  if (key === this.#appliedClearColor) return;
7604
7637
  this.#appliedClearColor = key;
@@ -7608,11 +7641,11 @@ var Environment = class Environment extends Component {
7608
7641
  * Writes the fog record.
7609
7642
  *
7610
7643
  * @remarks
7611
- * The colour goes across **encoded**, unlike every other colour this component writes: Lite's fog
7612
- * block decodes it itself — `color = mix(pow(scene.vFogColor.rgb, vec3(2.2)), color, fogFactor)`
7644
+ * The colour goes across **encoded**: Lite's fog block decodes it itself —
7645
+ * `color = mix(pow(scene.vFogColor.rgb, vec3(2.2)), color, fogFactor)`
7613
7646
  * (`lib/material/pbr/pbr-fog-wgsl.js` 4) — so handing it a linear value decodes it twice and the
7614
- * fog reads far darker than the swatch. The clear colour, which the render pass consumes as a
7615
- * linear clear value, is decoded by `RendererImpl.applyClearColor` instead.
7647
+ * fog reads far darker than the swatch. The clear colour also goes across encoded, for its own
7648
+ * reason (`RendererImpl.applyClearColor`).
7616
7649
  *
7617
7650
  * @param renderer - The rendering service, for the scene.
7618
7651
  */
@@ -7632,7 +7665,8 @@ var Environment = class Environment extends Component {
7632
7665
  * at the asset's recorded Lite handles, the rotation and the blur are invalidated so they are
7633
7666
  * written against the new cube map, and the image-processing key is cleared — Lite's
7634
7667
  * `loadEnvironment` overwrote `scene.imageProcessing` while that asset was loading, so the
7635
- * component's own exposure, contrast and curve have to be written again.
7668
+ * component's own exposure, contrast and curve have to be written again. The same happens, with the
7669
+ * same asset, after {@link Environment.reclaim}: another environment may have moved the slot.
7636
7670
  *
7637
7671
  * A move to `null` is deliberately *not* an uninstall (see the module remarks): the field stops
7638
7672
  * steering, and the scene stays lit by whatever was installed last.
@@ -7642,15 +7676,17 @@ var Environment = class Environment extends Component {
7642
7676
  */
7643
7677
  #applyEnvironment(renderer) {
7644
7678
  const loaded = this.environment?.state === "loaded" ? this.environment.value : null;
7679
+ const reclaimed = this.#isReclaimed;
7680
+ this.#isReclaimed = false;
7645
7681
  let installed = false;
7646
- if (loaded !== this.#trackedEnvironment) {
7682
+ if (loaded !== this.#trackedEnvironment || reclaimed) {
7647
7683
  this.#trackedEnvironment = loaded;
7648
- if (loaded !== null && loaded !== this.#installedEnvironment) {
7684
+ if (loaded !== null && (loaded !== this.#installedEnvironment || reclaimed)) {
7685
+ if (loaded !== this.#installedEnvironment) this.#hasWarnedAboutSkybox = false;
7649
7686
  this.#installedEnvironment = loaded;
7650
7687
  this.#appliedRotation = NaN;
7651
7688
  this.#appliedBlur = NaN;
7652
7689
  this.#appliedImageProcessing = "";
7653
- this.#hasWarnedAboutSkybox = false;
7654
7690
  const textures = loaded.lite.textures;
7655
7691
  installed = textures !== null && installLoadedEnvironment(renderer.scene, textures);
7656
7692
  }
@@ -7793,7 +7829,7 @@ function environmentSchema() {
7793
7829
  }),
7794
7830
  toneMapping: enumOf(TONE_MAPPING_NAMES, "none", { tooltip: "The tone-mapping curve." })
7795
7831
  }, { tooltip: "Exposure, contrast, and tone mapping. Recompiles PBR pipelines when it changes." }),
7796
- clearColor: color("#000000", { tooltip: "The colour the scene is cleared to, in sRGB." })
7832
+ clearColor: optional(color("#000000"), { tooltip: "The colour the scene is cleared to, in sRGB; null leaves the rendering.clearColor setting." })
7797
7833
  });
7798
7834
  }
7799
7835
  //#endregion
@@ -7836,7 +7872,7 @@ let surfaceLayer = null;
7836
7872
  * @internal
7837
7873
  */
7838
7874
  async function loadShaderSupport() {
7839
- const loaded = shaderLayer ?? await import("./shader-material-DssOqsvZ.js").then((n) => n.n);
7875
+ const loaded = shaderLayer ?? await import("./shader-material-CqkEsKQ2.js").then((n) => n.n);
7840
7876
  shaderLayer = loaded;
7841
7877
  await loaded.loadShaderMaterialAdapter();
7842
7878
  return loaded;
@@ -7859,7 +7895,7 @@ function shaderSupport() {
7859
7895
  * @internal
7860
7896
  */
7861
7897
  async function loadSurfaceShaderSupport() {
7862
- const loaded = surfaceLayer ?? await import("./surface-shader-C2HtysNN.js");
7898
+ const loaded = surfaceLayer ?? await import("./surface-shader-B3gtg_8Q.js");
7863
7899
  surfaceLayer = loaded;
7864
7900
  return loaded;
7865
7901
  }
@@ -8904,9 +8940,11 @@ const FLOATS_PER_COLOR$1 = 4;
8904
8940
  *
8905
8941
  * @example
8906
8942
  * ```ts
8907
- * using box = MeshAsset.box(app, { size: 2 });
8943
+ * const box = MeshAsset.box(app, { size: 2 }); // one reference, owned by this code
8908
8944
  * const cube = app.world.createEntity("Cube");
8909
- * cube.addComponent(MeshRenderer, { mesh: box.retain() });
8945
+ * cube.addComponent(MeshRenderer, { mesh: box }); // the field takes no reference
8946
+ * // Once nothing draws the box any more:
8947
+ * box.release();
8910
8948
  * ```
8911
8949
  *
8912
8950
  * @public
@@ -10913,7 +10951,7 @@ var RendererImpl = class {
10913
10951
  this.applyClearColor(this.settings.clearColor);
10914
10952
  }
10915
10953
  /**
10916
- * Writes an sRGB colour onto the render scene's clear colour, decoded to linear.
10954
+ * Writes an sRGB colour onto the render scene's clear colour, so it presents as authored.
10917
10955
  *
10918
10956
  * @remarks
10919
10957
  * The one place `scene.clearColor` is written, so the precedence
@@ -10922,22 +10960,26 @@ var RendererImpl = class {
10922
10960
  *
10923
10961
  * 1. **`Camera.clearColor` on the main camera**, when it is not `null`. The `PreRender` system
10924
10962
  * writes it every frame the camera renders, so it always wins.
10925
- * 2. **`Environment.clearColor`** of the winning environment, written whenever the field changes.
10963
+ * 2. **`Environment.clearColor`** of the winning environment, when it is not `null`, written
10964
+ * whenever the field changes and whenever that environment becomes the winner.
10926
10965
  * 3. **The `rendering.clearColor` setting**, written once by {@link RendererImpl.attachHandles}
10927
10966
  * as the scene is created — before a frame has run, and therefore before either component.
10928
10967
  * 4. Babylon Lite's own default, a mid grey, when the project declared no section at all. The
10929
10968
  * ignifx default is opaque black (`src/render/rendering-settings.ts`), so Lite's grey is only
10930
10969
  * ever seen by code that bypasses `createApp`.
10931
10970
  *
10932
- * Colours are stored in sRGB in every settings section and every component field, and Lite's
10933
- * `scene.clearColor` is linear, so each component is decoded on the way through.
10971
+ * Colours are stored in sRGB in every settings section and every component field, and the clear
10972
+ * reaches the swapchain without tone mapping or image processing, so an sRGB `0.5` presents as
10973
+ * byte `128`. The value is written unchanged on the default surface and decoded only for an
10974
+ * `*-srgb` surface view (`rendering.srgb: true`), which encodes it again on write
10975
+ * (`setSceneClearColor`).
10934
10976
  *
10935
10977
  * @param value - The sRGB colour, `0` to `1` per channel.
10936
10978
  *
10937
10979
  * @internal
10938
10980
  */
10939
10981
  applyClearColor(value) {
10940
- setSceneClearColor(this.scene, Color.srgbToLinear(value.r), Color.srgbToLinear(value.g), Color.srgbToLinear(value.b), value.a);
10982
+ setSceneClearColor(this.scene, value.r, value.g, value.b, value.a);
10941
10983
  }
10942
10984
  /**
10943
10985
  * Reconciles the world with the Lite scene once, before the scene is registered.
@@ -11181,9 +11223,9 @@ function noMatrices() {
11181
11223
  *
11182
11224
  * @example
11183
11225
  * ```ts
11184
- * using box = MeshAsset.box(app, { size: 0.5 });
11226
+ * const box = MeshAsset.box(app, { size: 0.5 }); // release it once nothing draws it
11185
11227
  * const field = world.createEntity("Asteroids");
11186
- * const renderer = field.addComponent(InstancedMeshRenderer, { mesh: box.retain(), capacity: 20_000 });
11228
+ * const renderer = field.addComponent(InstancedMeshRenderer, { mesh: box, capacity: 20_000 });
11187
11229
  *
11188
11230
  * const slab = new Float32Array(20_000 * 16);
11189
11231
  * // ... write 16 column-major floats per instance ...
@@ -12069,21 +12111,6 @@ function toSpotConfig(settings) {
12069
12111
  //#endregion
12070
12112
  //#region src/lite/gpu/shadow-generator.ts
12071
12113
  /**
12072
- * The four shadow-generator factories (`docs/architecture/07-rendering.md` §2.2). Each allocates a
12073
- * depth texture and a comparison sampler through `engine._device`
12074
- * (`lib/shadow/pcf-directional-shadow-generator.js`), so they are GPU-only. Everything a generator
12075
- * needs afterwards — caster lists, attachment, disposal — is in `../shadow.ts`.
12076
- *
12077
- * Everything here is `@internal`.
12078
- *
12079
- * ## Which techniques exist (verified against `@babylonjs/lite@1.27.0`)
12080
- *
12081
- * Directional lights get ESM (`index.d.ts` 2482), PCF (2846) or CSM (2329); spot lights get PCF
12082
- * only (2856). There is no point-light generator and no area light, which is why `../shadow.ts`
12083
- * rejects those with `IGX-0703`. The `technique` a spot light declares is therefore ignored, not an
12084
- * error: PCF is the only thing Lite can do for it.
12085
- */
12086
- /**
12087
12114
  * Builds the shadow generator a light's declared settings ask for.
12088
12115
  *
12089
12116
  * @param engine - The engine that owns the shadow map.
@@ -12102,8 +12129,31 @@ function toSpotConfig(settings) {
12102
12129
  * @internal
12103
12130
  */
12104
12131
  function createShadowGeneratorForLight(engine, light, settings) {
12105
- if (light.lightType === "spot") return createPcfSpotlightShadowGenerator(engine, light, toSpotConfig(settings));
12106
- return createDirectionalGenerator(engine, light, settings);
12132
+ const generator = light.lightType === "spot" ? createPcfSpotlightShadowGenerator(engine, light, toSpotConfig(settings)) : createDirectionalGenerator(engine, light, settings);
12133
+ recordReplacedShadowTaskStates(generator);
12134
+ return generator;
12135
+ }
12136
+ /**
12137
+ * Makes a generator record a shadow task state it replaced for the same casters before that state
12138
+ * can draw (see the module header for the frame this prevents).
12139
+ *
12140
+ * @remarks
12141
+ * Lite's own `enableDeformableShadowCasters` wraps the same hook the same way
12142
+ * (`lib/shadow/deformable-shadow-casters.js` 98-104). A state built for a *new* caster array is
12143
+ * left alone, because the shadow task records that one itself.
12144
+ *
12145
+ * @param generator - A generator from one of Lite's four factories.
12146
+ */
12147
+ function recordReplacedShadowTaskStates(generator) {
12148
+ const hooks = generator;
12149
+ const ensure = hooks._ensureShadowTaskState;
12150
+ if (ensure === void 0) return;
12151
+ hooks._ensureShadowTaskState = (engine, scene, casterMeshes) => {
12152
+ const previous = hooks._shadowTaskState;
12153
+ const state = ensure(engine, scene, casterMeshes);
12154
+ if (previous !== void 0 && state !== previous && state._casterMeshes === previous._casterMeshes) state._task.record();
12155
+ return state;
12156
+ };
12107
12157
  }
12108
12158
  /**
12109
12159
  * Builds the directional generator for a technique.
@@ -12230,6 +12280,9 @@ const TRANSLATION_COLUMN = 12;
12230
12280
  * local `+Z`, a point light sits at its origin, and a hemispheric light's sky direction is its local
12231
12281
  * `+Y`.
12232
12282
  *
12283
+ * A disabled light, or one on an inactive entity, contributes nothing: its intensity reaches Lite
12284
+ * as `0` and its shadow generator is released. Enabling it again restores both on the next frame.
12285
+ *
12233
12286
  * @example
12234
12287
  * ```ts
12235
12288
  * const sun = world.createEntity("Sun");
@@ -12280,7 +12333,7 @@ var Light = class Light extends Component {
12280
12333
  }
12281
12334
  /**
12282
12335
  * Whether this light currently casts shadows — which needs the `shadows` rendering feature, a
12283
- * light kind Lite can shadow, and `shadows.enabled`.
12336
+ * light kind Lite can shadow, `shadows.enabled`, and the light enabled in the hierarchy.
12284
12337
  *
12285
12338
  * @returns `true` when a shadow generator is attached.
12286
12339
  */
@@ -12297,7 +12350,8 @@ var Light = class Light extends Component {
12297
12350
  }
12298
12351
  /**
12299
12352
  * Writes every field that changed onto the Lite light, keeps the lights uniform buffer honest for
12300
- * a moving parent, and re-fits a shadow frustum that follows one. The `PreRender` system calls it.
12353
+ * a moving parent, and re-fits a shadow frustum that follows one. The `PreRender` system calls it
12354
+ * for every light, enabled or not, because a disabled light is dimmed to `0` rather than skipped.
12301
12355
  *
12302
12356
  * @param renderer - The rendering service, for the scene and the feature flags.
12303
12357
  * @returns `true` when the call changed the scene's light topology, which the system coalesces
@@ -12343,12 +12397,13 @@ var Light = class Light extends Component {
12343
12397
  const type = this.type;
12344
12398
  if (this.#appliedType === type && this.#light !== null) return false;
12345
12399
  this.#teardown(renderer);
12346
- const light = createLightOfType(type, this.intensity);
12400
+ const intensity = this.#effectiveIntensity();
12401
+ const light = createLightOfType(type, intensity);
12347
12402
  this.#light = light;
12348
12403
  this.#appliedType = type;
12349
12404
  this.#appliedColor = "";
12350
12405
  this.#appliedGroundColor = "";
12351
- this.#appliedIntensity = this.intensity;
12406
+ this.#appliedIntensity = intensity;
12352
12407
  this.#appliedRange = NaN;
12353
12408
  this.#appliedSpotAngle = NaN;
12354
12409
  this.#appliedSpotExponent = NaN;
@@ -12380,9 +12435,10 @@ var Light = class Light extends Component {
12380
12435
  * @param light - The Lite light.
12381
12436
  */
12382
12437
  #applyScalars(light) {
12383
- if (this.#appliedIntensity !== this.intensity) {
12384
- this.#appliedIntensity = this.intensity;
12385
- setLightIntensity(light, this.intensity);
12438
+ const intensity = this.#effectiveIntensity();
12439
+ if (this.#appliedIntensity !== intensity) {
12440
+ this.#appliedIntensity = intensity;
12441
+ setLightIntensity(light, intensity);
12386
12442
  }
12387
12443
  if (isRanged(light) && this.#appliedRange !== this.range) {
12388
12444
  this.#appliedRange = this.range;
@@ -12399,6 +12455,18 @@ var Light = class Light extends Component {
12399
12455
  }
12400
12456
  }
12401
12457
  /**
12458
+ * The intensity Lite should use: the field, or `0` while the component or its entity is disabled.
12459
+ *
12460
+ * @remarks
12461
+ * Dimming keeps the light in the scene. Removing it would change the light count every compiled
12462
+ * PBR permutation bakes in, and so cost a renderable rebuild on every toggle.
12463
+ *
12464
+ * @returns The intensity to apply.
12465
+ */
12466
+ #effectiveIntensity() {
12467
+ return this.isEnabledInHierarchy ? this.intensity : 0;
12468
+ }
12469
+ /**
12402
12470
  * Rebuilds the include and exclude mesh-id sets when either list changed length.
12403
12471
  *
12404
12472
  * @remarks
@@ -12426,7 +12494,7 @@ var Light = class Light extends Component {
12426
12494
  */
12427
12495
  #applyShadows(renderer) {
12428
12496
  const light = this.#light;
12429
- const wanted = this.shadows.enabled && renderer.features.shadows && !renderer.isHeadless;
12497
+ const wanted = this.shadows.enabled && this.isEnabledInHierarchy && renderer.features.shadows && !renderer.isHeadless;
12430
12498
  if (light === null || wanted === this.#appliedShadows) {
12431
12499
  this.#warnAboutShadows(renderer);
12432
12500
  return false;
@@ -14813,9 +14881,9 @@ function asMesh(node) {
14813
14881
  *
14814
14882
  * @example
14815
14883
  * ```ts
14816
- * using box = MeshAsset.box(app, { size: 1 });
14884
+ * const box = MeshAsset.box(app, { size: 1 }); // release it once nothing draws it
14817
14885
  * const cube = world.createEntity("Cube");
14818
- * cube.addComponent(MeshRenderer, { mesh: box.retain(), castShadows: true });
14886
+ * cube.addComponent(MeshRenderer, { mesh: box, castShadows: true });
14819
14887
  * ```
14820
14888
  *
14821
14889
  * @public
@@ -15190,7 +15258,7 @@ const NO_SKELETONS = Object.freeze([]);
15190
15258
  * ```ts
15191
15259
  * const hero = await app.assets.loadAsync<ModelAsset>("models/hero.glb");
15192
15260
  * const entity = world.createEntity("Hero");
15193
- * const model = entity.addComponent(Model, { model: hero.retain() });
15261
+ * const model = entity.addComponent(Model, { model: hero });
15194
15262
  * model.attachToNode("hand.R", sword);
15195
15263
  * ```
15196
15264
  *
@@ -16488,6 +16556,8 @@ var RenderSyncSystem = class {
16488
16556
  /** Renderers already reported with `IGX-0724`, so the warning fires once per component. */
16489
16557
  #esmSkipReported = /* @__PURE__ */ new WeakSet();
16490
16558
  #hasLoggedMultipleEnvironments = false;
16559
+ /** Each world's winning `Environment` last frame, so a change of winner is seen. */
16560
+ #lastEnvironment = /* @__PURE__ */ new WeakMap();
16491
16561
  #isRebuildDue = false;
16492
16562
  #isRebuildInFlight = false;
16493
16563
  /** A rebuild asked for while one was already running; it is run once the in-flight one lands. */
@@ -16642,6 +16712,8 @@ var RenderSyncSystem = class {
16642
16712
  world.app.log.warn("IGX-0705: {count} Environment components are enabled in this world; the most recent one wins.", enabledCount);
16643
16713
  }
16644
16714
  if (enabledCount <= 1) this.#hasLoggedMultipleEnvironments = false;
16715
+ if (winner !== null && winner !== (this.#lastEnvironment.get(world) ?? null)) winner.reclaim();
16716
+ this.#lastEnvironment.set(world, winner);
16645
16717
  return winner?.sync(this.#renderer) ?? false;
16646
16718
  }
16647
16719
  /**