@ignifx/core 0.1.0 → 0.2.1

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
@@ -209,6 +209,8 @@ const CoreErrorCode = {
209
209
  invalidAssetFile: "IGX-0709",
210
210
  /** A `PostProcessStack` was attached without the `postProcessing` rendering feature. */
211
211
  postProcessingFeatureOff: "IGX-0710",
212
+ /** An `Environment.skybox` asks for a background the environment it installed cannot draw. */
213
+ skyboxFixedAtLoad: "IGX-0711",
212
214
  /** The host exposes no Web Crypto implementation. */
213
215
  cryptoUnavailable: "IGX-1420",
214
216
  /** A storage namespace name is not a legal namespace segment. */
@@ -306,6 +308,7 @@ const CORE_ERROR_MESSAGES = {
306
308
  "IGX-0708": "{asset} declares the material kind {kind}, which this build cannot construct.",
307
309
  "IGX-0709": "{file} is not an {format} file.",
308
310
  "IGX-0710": "{entity} attached a PostProcessStack, but rendering.features.postProcessing is off.",
311
+ "IGX-0711": "{entity} asks for an Environment.skybox that {asset} was not loaded with; declare it in the .environment.json.",
309
312
  "IGX-1420": "This host does not expose Web Crypto.",
310
313
  "IGX-1421": "{namespace} is not a valid storage namespace.",
311
314
  "IGX-1422": "That storage key is empty, too long, or contains a control character.",
@@ -8357,6 +8360,48 @@ function loadSceneEnvironment(scene, options) {
8357
8360
  return loadEnvironment(scene, options.url, liteOptions);
8358
8361
  }
8359
8362
  /**
8363
+ * Views a scene through its undeclared environment slot.
8364
+ *
8365
+ * @param scene - The scene.
8366
+ * @returns The same object, typed so the slot is reachable.
8367
+ */
8368
+ function environmentSlotOf(scene) {
8369
+ return scene;
8370
+ }
8371
+ /**
8372
+ * Points a scene at an already-loaded set of environment textures, without loading anything.
8373
+ *
8374
+ * @remarks
8375
+ * This is how an `Environment` component swaps environments at runtime: the textures belong to the
8376
+ * `EnvironmentAsset` that loaded them and stay alive as long as its handle is retained, so
8377
+ * switching between two loaded assets uploads nothing and frees nothing.
8378
+ *
8379
+ * The specular reflection follows only after the scene's material groups are rebuilt
8380
+ * (`rebuildRenderables` in `../shadow.ts`): a PBR bind group holds the cube map's `GPUTextureView`,
8381
+ * not the slot. The diffuse harmonics and the LOD scale follow immediately, because the render
8382
+ * task's scene-UBO cache is keyed on this object's identity.
8383
+ *
8384
+ * @param scene - The scene to light.
8385
+ * @param textures - The textures to light it with.
8386
+ * @returns `true` when the scene was lit by something else and now is not — the caller owes a
8387
+ * renderable rebuild; `false` when these textures were already installed and nothing was written.
8388
+ *
8389
+ * @example
8390
+ * ```ts
8391
+ * if (installSceneEnvironment(scene, asset.lite.textures)) {
8392
+ * await rebuildRenderables(scene);
8393
+ * }
8394
+ * ```
8395
+ *
8396
+ * @internal
8397
+ */
8398
+ function installSceneEnvironment(scene, textures) {
8399
+ const slot = environmentSlotOf(scene);
8400
+ if (slot._envTextures === textures) return false;
8401
+ slot._envTextures = textures;
8402
+ return true;
8403
+ }
8404
+ /**
8360
8405
  * Rotates the environment around the world Y axis.
8361
8406
  *
8362
8407
  * @param scene - The scene to rotate the environment of.
@@ -8977,6 +9022,11 @@ function environmentDefinition(overrides = {}) {
8977
9022
  * both live under `src/render/gpu/` and are measured by the browser project rather than the Node
8978
9023
  * coverage floor. Fog, the clear colour, and the "which asset is installed" bookkeeping are plain
8979
9024
  * scene state and stay on the component, where Node tests reach them.
9025
+ *
9026
+ * {@link installLoadedEnvironment} is the runtime swap: it moves the scene onto an already-loaded
9027
+ * asset's cube map with no fetch, no decode, and no upload. It lives here because the textures it
9028
+ * installs only exist with a device, but the write itself is a plain field assignment, so a headless
9029
+ * test that hands it a fabricated handle still exercises it.
8980
9030
  */
8981
9031
  /**
8982
9032
  * Applies an environment's rotation and blur to the scene.
@@ -9009,6 +9059,26 @@ function applyEnvironmentOrientation(scene, rotationDegrees, blur) {
9009
9059
  function applySceneImageProcessing(scene, exposure, contrast, toneMapping) {
9010
9060
  return setSceneImageProcessingOptions(scene, exposure, contrast, toneMapping);
9011
9061
  }
9062
+ /**
9063
+ * Moves a scene onto an already-loaded environment's textures.
9064
+ *
9065
+ * @remarks
9066
+ * The specular reflection follows only once the scene's material groups have been rebuilt — a PBR
9067
+ * bind group holds the cube map's texture view, not the scene's slot — so a `true` answer means the
9068
+ * caller owes a `rebuildSceneRenderables`. The `Environment` component discharges that by reporting
9069
+ * the install as a topology change, which the render-sync system coalesces with every other change
9070
+ * of the frame into one rebuild (`docs/architecture/07-rendering.md` §2.2, §2.5).
9071
+ *
9072
+ * @param scene - The render scene.
9073
+ * @param textures - The Lite handles the loaded `EnvironmentAsset` recorded.
9074
+ * @returns `true` when the scene was lit by something else and now is not; `false` when these
9075
+ * textures were already installed, in which case nothing was written.
9076
+ *
9077
+ * @internal
9078
+ */
9079
+ function installLoadedEnvironment(scene, textures) {
9080
+ return installSceneEnvironment(scene, textures);
9081
+ }
9012
9082
  //#endregion
9013
9083
  //#region src/render/environment.ts
9014
9084
  /**
@@ -9032,6 +9102,53 @@ function applySceneImageProcessing(scene, exposure, contrast, toneMapping) {
9032
9102
  * becoming an unhandled rejection (coding standards §8). The visible consequence is that a script
9033
9103
  * that ramps exposure every frame gets as many recompiles as the GPU can keep up with and no queue.
9034
9104
  *
9105
+ * ## Switching environments at runtime
9106
+ *
9107
+ * An `.env` is loaded **onto the scene** by the asset loader, because that is the only shape Lite's
9108
+ * `loadEnvironment` has (`./environment-asset.ts` explains it at length). Until 2026-09-08 that
9109
+ * meant `environment` was effectively read-only after the first load: the component re-aimed what
9110
+ * the loader had installed and nothing more, so assigning a second loaded handle changed the
9111
+ * rotation and the blur and left the lighting alone. It now installs the asset's recorded handles
9112
+ * on the scene (`./gpu/environment-install.ts`) and reports the install as a **topology change**,
9113
+ * which the render-sync system coalesces into the frame's one `rebuildSceneRenderables` — the step
9114
+ * that makes every PBR material re-bind the new cube map, because a bind group holds the texture
9115
+ * view rather than the scene's slot. Two loaded handles can therefore be swapped back and forth for
9116
+ * free: the GPU resources belong to the assets, stay alive while their handles are retained, and are
9117
+ * released by the asset system exactly as before.
9118
+ *
9119
+ * Installing also re-applies rotation, blur, **and** image processing, because Lite's
9120
+ * `loadEnvironment` overwrites `scene.imageProcessing` (`toneMappingEnabled`, `exposure = 0.8`,
9121
+ * `contrast = 1.2`) as a side effect of every load.
9122
+ *
9123
+ * ## Assigning `null` leaves the scene lit
9124
+ *
9125
+ * Lite 1.27.0 has no inverse of `loadEnvironment` — no `unloadEnvironment`, no
9126
+ * `scene.environmentTexture` to clear — and clearing its slot by hand would leave every PBR
9127
+ * material bound to a cube map the scene no longer admits to having until the next renderable
9128
+ * rebuild. So `environment = null` is documented as "stop steering the environment", not "turn the
9129
+ * lights off": the last installed environment keeps lighting the scene, exactly as detaching the
9130
+ * component does. {@link Environment.installed} keeps naming it, because that is what the scene is
9131
+ * actually lit by. To change the lighting, install a different loaded environment.
9132
+ *
9133
+ * ## `skybox` is decided when the environment loads, not here
9134
+ *
9135
+ * Lite builds the background inside `loadEnvironment`, as a *feature-owned* `Renderable` pushed
9136
+ * onto the scene from a deferred builder that `registerScene` drains
9137
+ * (`lib/_chunks/env-helpers-*.js`). `Renderable` (`index.d.ts` 9678) is `{ order, isTransparent,
9138
+ * mesh?, bind }` — no visibility flag, no size, no handle — and Lite exposes no way to remove one,
9139
+ * so a background that has been built cannot be hidden, resized, or re-aimed at another cube map.
9140
+ * The `.environment.json` is therefore the authority: `skyboxEnabled`, `skybox` and `skyboxSize`
9141
+ * decide the background when the asset loads. The component's `skybox` record is read every frame
9142
+ * so that a value the installed environment cannot deliver is *reported* — `IGX-0711`, once per
9143
+ * component — rather than silently ignored, which is what it was until 2026-09-08. A field left at
9144
+ * its schema default never reports anything, so only a project that actually asked for a different
9145
+ * background hears about it.
9146
+ *
9147
+ * The one improvement that did fit: an environment with `skyboxEnabled` and no explicit `skybox`
9148
+ * now draws **its own** prefiltered cube map (`./loaders/environment-loader.ts`), where Lite's
9149
+ * default was a flat box painted in the clear colour. So a bare `.env` gets a real background, and
9150
+ * the component's default `skybox.enabled: true` agrees with it.
9151
+ *
9035
9152
  * ## `ambientColor` does not exist
9036
9153
  *
9037
9154
  * §2.5 lists an `ambientColor` field. Babylon Lite 1.27.0 has no scene-level ambient term:
@@ -9059,17 +9176,32 @@ const FOG_MODE_NAMES = [
9059
9176
  "exp2"
9060
9177
  ];
9061
9178
  /**
9179
+ * Whether a background is drawn, when nothing says otherwise. It matches the `.environment.json`
9180
+ * default (`skyboxEnabled`), which is what makes the ordinary case agree with itself.
9181
+ */
9182
+ const SKYBOX_ENABLED_DEFAULT = true;
9183
+ /** The background cube's default size in metres. It matches the file format's `skyboxSize`. */
9184
+ const SKYBOX_SIZE_DEFAULT = 20;
9185
+ /**
9062
9186
  * The world's lighting environment (`docs/architecture/07-rendering.md` §2.5).
9063
9187
  *
9064
9188
  * @example
9065
9189
  * ```ts
9066
9190
  * const studio = await app.assets.loadAsync<EnvironmentAsset>("environments/studio.env");
9067
- * world.createEntity("Environment").addComponent(Environment, {
9191
+ * const env = world.createEntity("Environment").addComponent(Environment, {
9068
9192
  * environment: studio.retain(),
9069
9193
  * imageProcessing: { exposure: 1.2, contrast: 1, toneMapping: "aces" },
9070
9194
  * });
9071
9195
  * ```
9072
9196
  *
9197
+ * @example
9198
+ * Switching environments at runtime. Both handles stay retained, so switching back costs nothing.
9199
+ *
9200
+ * ```ts
9201
+ * const night = await app.assets.loadAsync<EnvironmentAsset>("environments/night.env");
9202
+ * env.environment = night.retain();
9203
+ * ```
9204
+ *
9073
9205
  * @public
9074
9206
  */
9075
9207
  var Environment = class Environment extends Component {
@@ -9090,18 +9222,27 @@ var Environment = class Environment extends Component {
9090
9222
  #appliedClearColor = "";
9091
9223
  #appliedImageProcessing = "";
9092
9224
  #imageProcessingInFlight = false;
9093
- #appliedEnvironment = null;
9225
+ #trackedEnvironment = null;
9226
+ #installedEnvironment = null;
9227
+ #hasWarnedAboutSkybox = false;
9094
9228
  /**
9095
- * The environment asset this component installed, once it has loaded.
9229
+ * The environment asset this component installed on the scene.
9096
9230
  *
9097
- * @returns The asset, or `null` when none is loaded.
9231
+ * @remarks
9232
+ * It stops at the **last installed** asset, which is what the scene is actually lit by: setting
9233
+ * `environment` back to `null` does not un-light the scene, because Lite has no inverse of
9234
+ * `loadEnvironment` (see the module remarks). Headless it names the asset too — what a headless
9235
+ * app skips is the cube map, not the bookkeeping.
9236
+ *
9237
+ * @returns The asset, or `null` when this component has never installed one.
9098
9238
  */
9099
9239
  get installed() {
9100
- return this.#appliedEnvironment;
9240
+ return this.#installedEnvironment;
9101
9241
  }
9102
9242
  /** Records that the component exists; the scene is written on the first sync. */
9103
9243
  onAttach() {
9104
- this.#appliedEnvironment = null;
9244
+ this.#trackedEnvironment = null;
9245
+ this.#installedEnvironment = null;
9105
9246
  }
9106
9247
  /**
9107
9248
  * Leaves the scene as it is.
@@ -9113,21 +9254,27 @@ var Environment = class Environment extends Component {
9113
9254
  * implies. The `PreRender` system re-picks the winner on the next frame.
9114
9255
  */
9115
9256
  onDetach() {
9116
- this.#appliedEnvironment = null;
9257
+ this.#trackedEnvironment = null;
9258
+ this.#installedEnvironment = null;
9117
9259
  }
9118
9260
  /**
9119
9261
  * Writes every field that changed onto the scene. The `PreRender` system calls it for the winning
9120
9262
  * environment only.
9121
9263
  *
9122
9264
  * @param renderer - The rendering service, for the scene and the headless flag.
9265
+ * @returns `true` when a different environment was installed on the scene this frame, which is a
9266
+ * topology change: the render-sync system owes the frame one `rebuildSceneRenderables` so that
9267
+ * every PBR material re-binds the new cube map.
9123
9268
  *
9124
9269
  * @internal
9125
9270
  */
9126
9271
  sync(renderer) {
9127
9272
  this.#applyClearColor(renderer);
9128
9273
  this.#applyFog(renderer);
9129
- this.#applyEnvironment(renderer);
9274
+ const installed = this.#applyEnvironment(renderer);
9275
+ this.#reportSkybox(renderer);
9130
9276
  this.#applyImageProcessing(renderer);
9277
+ return installed;
9131
9278
  }
9132
9279
  /**
9133
9280
  * Writes the clear colour, decoded to linear.
@@ -9158,23 +9305,74 @@ var Environment = class Environment extends Component {
9158
9305
  setSceneFog(renderer.scene, toFogMode(fog.mode), Color.srgbToLinear(fog.color.r), Color.srgbToLinear(fog.color.g), Color.srgbToLinear(fog.color.b), fog.density, fog.start, fog.end);
9159
9306
  }
9160
9307
  /**
9161
- * Applies the loaded environment's rotation and blur, and records which asset is installed.
9308
+ * Installs a newly assigned environment on the scene, then applies its rotation and blur.
9309
+ *
9310
+ * @remarks
9311
+ * Three things happen only when the field moves to a *different* loaded asset, which is what
9312
+ * keeps the "write only what changed" discipline of `07-rendering.md` §2.2: the scene is pointed
9313
+ * at the asset's recorded Lite handles, the rotation and the blur are invalidated so they are
9314
+ * written against the new cube map, and the image-processing key is cleared — Lite's
9315
+ * `loadEnvironment` overwrote `scene.imageProcessing` while that asset was loading, so the
9316
+ * component's own exposure, contrast and curve have to be written again.
9317
+ *
9318
+ * A move to `null` is deliberately *not* an uninstall (see the module remarks): the field stops
9319
+ * steering, and the scene stays lit by whatever was installed last.
9162
9320
  *
9163
9321
  * @param renderer - The rendering service, for the scene.
9322
+ * @returns `true` when the scene's environment slot moved this frame.
9164
9323
  */
9165
9324
  #applyEnvironment(renderer) {
9166
9325
  const loaded = this.environment?.state === "loaded" ? this.environment.value : null;
9167
- if (loaded !== this.#appliedEnvironment) {
9168
- this.#appliedEnvironment = loaded;
9169
- this.#appliedRotation = NaN;
9170
- this.#appliedBlur = NaN;
9326
+ let installed = false;
9327
+ if (loaded !== this.#trackedEnvironment) {
9328
+ this.#trackedEnvironment = loaded;
9329
+ if (loaded !== null && loaded !== this.#installedEnvironment) {
9330
+ this.#installedEnvironment = loaded;
9331
+ this.#appliedRotation = NaN;
9332
+ this.#appliedBlur = NaN;
9333
+ this.#appliedImageProcessing = "";
9334
+ this.#hasWarnedAboutSkybox = false;
9335
+ const textures = loaded.lite.textures;
9336
+ installed = textures !== null && installLoadedEnvironment(renderer.scene, textures);
9337
+ }
9171
9338
  }
9172
- if (loaded === null || renderer.isHeadless) return;
9339
+ if (this.#installedEnvironment === null || renderer.isHeadless) return installed;
9173
9340
  if (this.#appliedRotation !== this.rotation || this.#appliedBlur !== this.blur) {
9174
9341
  this.#appliedRotation = this.rotation;
9175
9342
  this.#appliedBlur = this.blur;
9176
9343
  applyEnvironmentOrientation(renderer.scene, this.rotation, this.blur);
9177
9344
  }
9345
+ return installed;
9346
+ }
9347
+ /**
9348
+ * Says once, at warning level, that the `skybox` record asks for a background the installed
9349
+ * environment was not loaded with.
9350
+ *
9351
+ * @remarks
9352
+ * The field cannot be honoured here and this is not an oversight: Lite 1.27.0 builds the
9353
+ * background inside `loadEnvironment`, as a `Renderable` with no visibility flag, no size and no
9354
+ * handle, and offers nothing that removes or re-aims one (see the module remarks). So the record
9355
+ * is compared with what the installed asset's declaration actually delivered, and a disagreement
9356
+ * is reported rather than dropped.
9357
+ *
9358
+ * A field still sitting at its schema default is **not** a disagreement, whatever the declaration
9359
+ * says. Otherwise every project whose `.environment.json` turns the background off would be told
9360
+ * off for never having touched a component field, which is the opposite of actionable. The
9361
+ * warning therefore means "you asked for something and did not get it", never "these two numbers
9362
+ * differ".
9363
+ *
9364
+ * @param renderer - The rendering service, for the log sink.
9365
+ */
9366
+ #reportSkybox(renderer) {
9367
+ const installed = this.#installedEnvironment;
9368
+ if (installed === null || this.#hasWarnedAboutSkybox) return;
9369
+ const definition = installed.definition;
9370
+ const skybox = this.skybox;
9371
+ const askedForEnabled = skybox.enabled !== SKYBOX_ENABLED_DEFAULT && skybox.enabled !== definition.skyboxEnabled;
9372
+ const askedForSize = skybox.size !== SKYBOX_SIZE_DEFAULT && skybox.size !== definition.skyboxSize;
9373
+ if (!askedForEnabled && !askedForSize) return;
9374
+ this.#hasWarnedAboutSkybox = true;
9375
+ renderer.app.log.warn(`${CoreErrorCode.skyboxFixedAtLoad}: {entity} asks for skybox {requested}, but {asset} was loaded with {loaded} and Babylon Lite builds the background when the environment loads, with no handle to change it afterwards. Declare skyboxEnabled and skyboxSize in the .environment.json instead.`, this.entity.name, `{ enabled: ${String(skybox.enabled)}, size: ${String(skybox.size)} }`, installed.address, `{ enabled: ${String(definition.skyboxEnabled)}, size: ${String(definition.skyboxSize)} }`);
9178
9376
  }
9179
9377
  /**
9180
9378
  * Fires the asynchronous image-processing update, at most one at a time.
@@ -9243,12 +9441,12 @@ function environmentSchema() {
9243
9441
  tooltip: "How blurred the specular reflection is."
9244
9442
  }),
9245
9443
  skybox: record({
9246
- enabled: bool(true, { tooltip: "Whether a skybox is drawn behind the scene." }),
9247
- size: f32(20, {
9444
+ enabled: bool(SKYBOX_ENABLED_DEFAULT, { tooltip: "Whether a skybox is drawn; set it in the .environment.json." }),
9445
+ size: f32(SKYBOX_SIZE_DEFAULT, {
9248
9446
  min: .001,
9249
- tooltip: "The skybox cube's size, in metres."
9447
+ tooltip: "The skybox cube's size in metres; set it in the .environment.json."
9250
9448
  })
9251
- }, { tooltip: "The background the environment draws." }),
9449
+ }, { tooltip: "The background, as the installed .environment.json declared it. Read-only in practice." }),
9252
9450
  fog: record({
9253
9451
  mode: enumOf(FOG_MODE_NAMES, "none", { tooltip: "Fog falloff, or none." }),
9254
9452
  color: color("#c8c8c8", { tooltip: "The fog's sRGB colour." }),
@@ -11801,6 +11999,8 @@ var RendererImpl = class {
11801
11999
  /** How many times the sync system has rebuilt the scene's renderables; a diagnostics counter. */
11802
12000
  renderableRebuilds = 0;
11803
12001
  #app;
12002
+ /** Probes registered by {@link RendererImpl.addCameraSource}, in registration order. */
12003
+ #cameraSources = [];
11804
12004
  #features;
11805
12005
  #counters;
11806
12006
  #countersDrawCalls;
@@ -12083,6 +12283,36 @@ var RendererImpl = class {
12083
12283
  this.#features[feature] = true;
12084
12284
  }
12085
12285
  /**
12286
+ * Registers a probe that answers whether another rendering context has a camera of its own.
12287
+ *
12288
+ * @param probe - Answers `true` while the caller has an active camera for the world.
12289
+ * @returns A function that removes the probe.
12290
+ */
12291
+ addCameraSource(probe) {
12292
+ this.#cameraSources.push(probe);
12293
+ return () => {
12294
+ const index = this.#cameraSources.indexOf(probe);
12295
+ if (index >= 0) this.#cameraSources.splice(index, 1);
12296
+ };
12297
+ }
12298
+ /**
12299
+ * Whether any registered probe claims a camera for this world.
12300
+ *
12301
+ * @remarks
12302
+ * Asked by the render sync system only in a frame where no enabled `Camera` was found, which is
12303
+ * what keeps `IGX-0706` off a correct 2D-only scene without costing a well-formed 3D scene
12304
+ * anything (`docs/architecture/07-rendering.md` §2.1).
12305
+ *
12306
+ * @param world - The world being reconciled.
12307
+ * @returns `true` when something other than the render scene draws it.
12308
+ *
12309
+ * @internal
12310
+ */
12311
+ hasExternalCamera(world) {
12312
+ for (let index = 0; index < this.#cameraSources.length; index += 1) if (this.#cameraSources[index]?.(world) === true) return true;
12313
+ return false;
12314
+ }
12315
+ /**
12086
12316
  * The material a `MeshRenderer` draws with when it declares none
12087
12317
  * (`docs/architecture/07-rendering.md` §2.3): a neutral, fully rough dielectric.
12088
12318
  *
@@ -12799,6 +13029,14 @@ function lightSchema() {
12799
13029
  * file (`docs/architecture/05-assets-and-loading.md` §5,
12800
13030
  * `06-serialization-and-scene-format.md` §6).
12801
13031
  *
13032
+ * ## The skybox is decided here, once
13033
+ *
13034
+ * Lite builds the background inside `loadEnvironment` and hands back no handle on it, so this is
13035
+ * the only place that can decide whether there is one: `Environment.skybox` can report a
13036
+ * disagreement (`IGX-0711`) but cannot change it. `skyboxEnabled: false` skips the background;
13037
+ * otherwise the declaration's `skybox` image is used, and when it names none the environment draws
13038
+ * **its own** prefiltered cube map (see {@link toLoadOptions}).
13039
+ *
12802
13040
  * ## Two addresses, one asset type
12803
13041
  *
12804
13042
  * A bare `.env` address is the common case: load this IBL, take the BRDF table and the skybox from
@@ -12921,8 +13159,10 @@ function toLoadOptions(ctx, definition, brdfUrl) {
12921
13159
  skipGround: true
12922
13160
  };
12923
13161
  if (!definition.skyboxEnabled) options.skipSkybox = true;
12924
- else if (definition.skybox === "") options.skyboxSize = definition.skyboxSize;
12925
- else {
13162
+ else if (definition.skybox === "") {
13163
+ options.skyboxUrl = options.url;
13164
+ options.skyboxSize = definition.skyboxSize;
13165
+ } else {
12926
13166
  options.skyboxUrl = ctx.app.assets.resolveUrl(definition.skybox);
12927
13167
  options.skyboxSize = definition.skyboxSize;
12928
13168
  }
@@ -15459,6 +15699,53 @@ function createSmaaTask(engine, scene, source, target, settings) {
15459
15699
  return createSmaaPostProcessTask(config, engine, scene);
15460
15700
  }
15461
15701
  /**
15702
+ * Pushes a bloom task's tuning to the GPU without rebuilding the task.
15703
+ *
15704
+ * @remarks
15705
+ * `weight`, `kernel`, `threshold` and `exposure` are plain writable fields on Lite's task, and
15706
+ * `updateUniforms()` "recomputes and uploads the uniforms of all sub-passes (extract, blur X/Y,
15707
+ * merge) from current settings" (`index.d.ts` 1287–1298, verified against `@babylonjs/lite@1.27.0`).
15708
+ * `bloomScale` is **read-only** on the task: it sizes the blur targets when the task is created, so
15709
+ * a scale change is a new task, not an update — `PostProcessStack` rebuilds its chain for that.
15710
+ *
15711
+ * Call it only once the task has been recorded: before `record()` there is no uniform buffer to
15712
+ * upload into. A task created before `registerScene` is recorded by the scene's own frame-graph
15713
+ * build, and it was created with the settings it has, so nothing is lost by waiting.
15714
+ *
15715
+ * @param task - The recorded bloom task.
15716
+ * @param settings - The tuning to apply; a field left `undefined` keeps the task's current value.
15717
+ *
15718
+ * @internal
15719
+ */
15720
+ function updateBloomTask(task, settings) {
15721
+ if (settings.weight !== void 0) task.weight = settings.weight;
15722
+ if (settings.kernel !== void 0) task.kernel = settings.kernel;
15723
+ if (settings.threshold !== void 0) task.threshold = settings.threshold;
15724
+ if (settings.exposure !== void 0) task.exposure = settings.exposure;
15725
+ task.updateUniforms();
15726
+ }
15727
+ /**
15728
+ * Pushes an SMAA task's tuning to the GPU without rebuilding the task.
15729
+ *
15730
+ * @remarks
15731
+ * Lite documents every one of these fields as "call `updateUniforms()` after changing it"
15732
+ * (`index.d.ts` 11622–11652). `sourceIsSrgb` is deliberately not here: it describes the source
15733
+ * target, which does not change while the chain stands. The same "recorded first" rule as
15734
+ * {@link updateBloomTask} applies.
15735
+ *
15736
+ * @param task - The recorded SMAA task.
15737
+ * @param settings - The tuning to apply; a field left `undefined` keeps the task's current value.
15738
+ *
15739
+ * @internal
15740
+ */
15741
+ function updateSmaaTask(task, settings) {
15742
+ if (settings.threshold !== void 0) task.threshold = settings.threshold;
15743
+ if (settings.maxSearchSteps !== void 0) task.maxSearchSteps = settings.maxSearchSteps;
15744
+ if (settings.diagonalDetection !== void 0) task.diagonalDetection = settings.diagonalDetection;
15745
+ if (settings.cornerDetection !== void 0) task.cornerDetection = settings.cornerDetection;
15746
+ task.updateUniforms();
15747
+ }
15748
+ /**
15462
15749
  * Creates a task that applies the scene's exposure, contrast, and tone mapping as a full-screen
15463
15750
  * pass, straight onto the swapchain.
15464
15751
  *
@@ -15553,6 +15840,14 @@ var PostProcessChain = class {
15553
15840
  #tasks = [];
15554
15841
  #presenter;
15555
15842
  #isFrameGraphBuilt;
15843
+ /** The bloom task, when the chain has one; the one task whose tuning is retuned live. */
15844
+ #bloom = null;
15845
+ /** The SMAA task, when the chain has one. */
15846
+ #smaa = null;
15847
+ /** What the bloom task was created with, and then what it was last retuned to. */
15848
+ #appliedBloom = null;
15849
+ /** What the SMAA task was created with, and then what it was last retuned to. */
15850
+ #appliedSmaa = null;
15556
15851
  /**
15557
15852
  * Records the requested effects into a scene's frame graph.
15558
15853
  *
@@ -15597,6 +15892,41 @@ var PostProcessChain = class {
15597
15892
  return this.#tasks.length;
15598
15893
  }
15599
15894
  /**
15895
+ * Pushes the effects' current tuning to the recorded tasks, uploading only what changed since the
15896
+ * last call.
15897
+ *
15898
+ * @remarks
15899
+ * Nothing is uploaded until the scene's frame graph has been built: a task created before
15900
+ * `registerScene` has no uniform buffer yet, and it was created with the very settings it holds,
15901
+ * so there is nothing to catch up on. `scale` is not applied here — it is baked into the task and
15902
+ * a change to it is a rebuild, which `PostProcessStack` performs.
15903
+ *
15904
+ * @param bloom - The stack's bloom record.
15905
+ * @param smaa - The stack's SMAA record.
15906
+ * @param isFrameGraphBuilt - Whether the scene has been registered, so the tasks are recorded.
15907
+ */
15908
+ applySettings(bloom, smaa, isFrameGraphBuilt) {
15909
+ if (!isFrameGraphBuilt) return;
15910
+ const bloomTask = this.#bloom;
15911
+ const appliedBloom = this.#appliedBloom;
15912
+ if (bloomTask !== null && appliedBloom !== null && (appliedBloom.weight !== bloom.weight || appliedBloom.kernel !== bloom.kernel || appliedBloom.threshold !== bloom.threshold || appliedBloom.exposure !== bloom.exposure)) {
15913
+ appliedBloom.weight = bloom.weight;
15914
+ appliedBloom.kernel = bloom.kernel;
15915
+ appliedBloom.threshold = bloom.threshold;
15916
+ appliedBloom.exposure = bloom.exposure;
15917
+ updateBloomTask(bloomTask, appliedBloom);
15918
+ }
15919
+ const smaaTask = this.#smaa;
15920
+ const appliedSmaa = this.#appliedSmaa;
15921
+ if (smaaTask !== null && appliedSmaa !== null && (appliedSmaa.threshold !== smaa.threshold || appliedSmaa.maxSearchSteps !== smaa.maxSearchSteps || appliedSmaa.diagonalDetection !== smaa.diagonalDetection || appliedSmaa.cornerDetection !== smaa.cornerDetection)) {
15922
+ appliedSmaa.threshold = smaa.threshold;
15923
+ appliedSmaa.maxSearchSteps = smaa.maxSearchSteps;
15924
+ appliedSmaa.diagonalDetection = smaa.diagonalDetection;
15925
+ appliedSmaa.cornerDetection = smaa.cornerDetection;
15926
+ updateSmaaTask(smaaTask, appliedSmaa);
15927
+ }
15928
+ }
15929
+ /**
15600
15930
  * Switches every recorded task on or off. Lite offers no removal, so this is what "disable the
15601
15931
  * stack" means.
15602
15932
  *
@@ -15624,6 +15954,10 @@ var PostProcessChain = class {
15624
15954
  }
15625
15955
  if (this.#tasks.length > 0) this.#presenter.setPresentEnabled(true);
15626
15956
  this.#tasks.length = 0;
15957
+ this.#bloom = null;
15958
+ this.#smaa = null;
15959
+ this.#appliedBloom = null;
15960
+ this.#appliedSmaa = null;
15627
15961
  }
15628
15962
  /**
15629
15963
  * Appends one task to the scene's frame graph and remembers it.
@@ -15648,22 +15982,32 @@ var PostProcessChain = class {
15648
15982
  #createEffect(engine, scene, effect, source, target) {
15649
15983
  if (effect.name === "bloom") {
15650
15984
  const settings = effect.bloom;
15651
- return createBloomTask(engine, scene, source, target, {
15985
+ this.#appliedBloom = {
15652
15986
  weight: settings.weight,
15653
15987
  kernel: settings.kernel,
15654
15988
  threshold: settings.threshold,
15655
- exposure: settings.exposure,
15989
+ exposure: settings.exposure
15990
+ };
15991
+ const task = createBloomTask(engine, scene, source, target, {
15992
+ ...this.#appliedBloom,
15656
15993
  scale: settings.scale
15657
15994
  });
15995
+ this.#bloom = task;
15996
+ return task;
15658
15997
  }
15659
15998
  const settings = effect.smaa;
15660
- return createSmaaTask(engine, scene, source, target, {
15999
+ this.#appliedSmaa = {
15661
16000
  threshold: settings.threshold,
15662
16001
  maxSearchSteps: settings.maxSearchSteps,
15663
16002
  diagonalDetection: settings.diagonalDetection,
15664
- cornerDetection: settings.cornerDetection,
16003
+ cornerDetection: settings.cornerDetection
16004
+ };
16005
+ const task = createSmaaTask(engine, scene, source, target, {
16006
+ ...this.#appliedSmaa,
15665
16007
  sourceIsSrgb: effect.sourceIsSrgb
15666
16008
  });
16009
+ this.#smaa = task;
16010
+ return task;
15667
16011
  }
15668
16012
  };
15669
16013
  /**
@@ -15767,8 +16111,8 @@ var PostProcessStack = class PostProcessStack extends Component {
15767
16111
  chain?.dispose();
15768
16112
  }
15769
16113
  /**
15770
- * Builds the chain the first time any effect is enabled, and switches individual effects on and
15771
- * off after that. The `PreRender` system calls it.
16114
+ * Builds the chain when the effects it should hold change, and keeps the recorded tasks' tuning
16115
+ * and enabled state in step with the fields after that. The `PreRender` system calls it.
15772
16116
  *
15773
16117
  * @remarks
15774
16118
  * It is also called once by `app.start()`, through `renderer.syncBeforeRegister`, which is what
@@ -15777,22 +16121,53 @@ var PostProcessStack = class PostProcessStack extends Component {
15777
16121
  * (`PostProcessChain`'s `isFrameGraphBuilt`). Recording them early instead binds a scene colour
15778
16122
  * that no task has allocated yet and Lite rejects the whole frame with error 107.
15779
16123
  *
16124
+ * The chain's identity is {@link PostProcessStack.plannedChain} plus bloom's `scale`. When it
16125
+ * changes, the old chain is disposed and a new one recorded; when it does not, the chain follows
16126
+ * the component's `enabled` and re-uploads whatever tuning changed. A rebuild never happens
16127
+ * before the frame graph is built, because `syncBeforeRegister` is the only sync `start()` runs.
16128
+ *
15780
16129
  * @param renderer - The rendering service, for the engine and the scene.
15781
16130
  *
15782
16131
  * @internal
15783
16132
  */
15784
16133
  sync(renderer) {
15785
16134
  const wanted = this.#chainKey();
15786
- if (wanted !== this.#built && this.#chain === null) {
15787
- this.#built = wanted;
15788
- const requests = this.#requests(renderer.settings.srgb);
15789
- const presenter = renderer.presenter;
15790
- if (!renderer.isHeadless && presenter !== null) this.#chain = new PostProcessChain(renderer.engine, renderer.scene, presenter, requests, renderer.isSceneRegistered);
15791
- this.#warnAboutFeature(renderer, requests.length);
16135
+ if (wanted !== this.#built) {
16136
+ this.#rebuild(renderer, wanted);
15792
16137
  return;
15793
16138
  }
15794
16139
  this.#warnAboutFeature(renderer, this.plannedChain().length);
15795
- this.#chain?.setEnabled(this.isEnabledInHierarchy);
16140
+ const chain = this.#chain;
16141
+ if (chain !== null) {
16142
+ chain.setEnabled(this.isEnabledInHierarchy);
16143
+ chain.applySettings(this.bloom, this.smaa, renderer.isSceneRegistered);
16144
+ }
16145
+ }
16146
+ /**
16147
+ * Replaces the chain with one that holds the effects the fields currently ask for.
16148
+ *
16149
+ * @remarks
16150
+ * The request list is the component's own state, so it is built whether or not there is a device
16151
+ * to record it into; only the recording is device-only. An old chain is disposed first, which
16152
+ * also hands the swapchain back to the compositing blit, so a stack whose last effect was just
16153
+ * switched off presents the plain scene from the next frame rather than a stale one.
16154
+ *
16155
+ * @param renderer - The rendering service, for the engine and the scene.
16156
+ * @param wanted - The chain identity the fields currently describe.
16157
+ */
16158
+ #rebuild(renderer, wanted) {
16159
+ this.#built = wanted;
16160
+ const previous = this.#chain;
16161
+ this.#chain = null;
16162
+ previous?.dispose();
16163
+ const requests = this.#requests(renderer.settings.srgb);
16164
+ const presenter = renderer.presenter;
16165
+ if (!renderer.isHeadless && presenter !== null && requests.length > 0) {
16166
+ const chain = new PostProcessChain(renderer.engine, renderer.scene, presenter, requests, renderer.isSceneRegistered);
16167
+ chain.setEnabled(this.isEnabledInHierarchy);
16168
+ this.#chain = chain;
16169
+ }
16170
+ this.#warnAboutFeature(renderer, requests.length);
15796
16171
  }
15797
16172
  /**
15798
16173
  * Says once, at warning level, that the stack asks for effects the project did not opt into.
@@ -15842,14 +16217,16 @@ var PostProcessStack = class PostProcessStack extends Component {
15842
16217
  return names;
15843
16218
  }
15844
16219
  /**
15845
- * The identity of the chain the fields currently ask for: which effects are on, in which order.
15846
- * A change to it while the chain already exists only flips `executionEnabled`, because Lite
15847
- * cannot re-order a recorded frame graph.
16220
+ * The identity of the chain the fields currently ask for: which effects are on, in which order,
16221
+ * and — while bloom is one of them — bloom's `scale`, the one tuning Lite fixes when the task is
16222
+ * created. A change to it while a chain exists is a rebuild, because Lite cannot re-order a
16223
+ * recorded frame graph or resize a bloom task's blur targets.
15848
16224
  *
15849
16225
  * @returns The key.
15850
16226
  */
15851
16227
  #chainKey() {
15852
- return this.plannedChain().join(",");
16228
+ const effects = this.plannedChain().join(",");
16229
+ return this.bloom.enabled ? `${effects}|scale=${String(this.bloom.scale)}` : effects;
15853
16230
  }
15854
16231
  /**
15855
16232
  * The three effect records, as a uniform list ordered by their `order` fields.
@@ -16007,7 +16384,7 @@ var RenderSyncSystem = class {
16007
16384
  castersChanged = changed || castersChanged;
16008
16385
  }
16009
16386
  this.#selectCamera(world, cameras);
16010
- this.#applyEnvironment(world);
16387
+ topologyChanged = this.#applyEnvironment(world) || topologyChanged;
16011
16388
  this.#applyStacks(world);
16012
16389
  this.#areCastersDirty = this.#areCastersDirty || castersChanged;
16013
16390
  if (this.#isRebuildDue && !topologyChanged) {
@@ -16049,10 +16426,20 @@ var RenderSyncSystem = class {
16049
16426
  /**
16050
16427
  * Says once, at warning level, that the world renders nothing because no camera is enabled.
16051
16428
  *
16429
+ * @remarks
16430
+ * Silent when another rendering context claims the frame through a camera of its own — a
16431
+ * `"sprite"`-mode `@ignifx/2d` world with a `Camera2D` and no 3D `Camera` is a correct scene, and
16432
+ * `Renderer.addCameraSource` is how it says so. The claim is re-asked every frame rather than
16433
+ * latched, so a world that later loses its `Camera2D` still gets the warning.
16434
+ *
16052
16435
  * @param world - The world being reconciled.
16053
16436
  */
16054
16437
  #warnAboutMissingCamera(world) {
16055
16438
  const renderer = this.#renderer;
16439
+ if (renderer.hasExternalCamera(world)) {
16440
+ renderer.hasLoggedNoCamera = false;
16441
+ return;
16442
+ }
16056
16443
  if (renderer.hasLoggedNoCamera) return;
16057
16444
  renderer.hasLoggedNoCamera = true;
16058
16445
  world.app.log.warn("IGX-0706: this world has no enabled camera, so nothing is drawn.");
@@ -16061,6 +16448,7 @@ var RenderSyncSystem = class {
16061
16448
  * Applies the winning `Environment`, warning once when a world has more than one enabled.
16062
16449
  *
16063
16450
  * @param world - The world being reconciled.
16451
+ * @returns `true` when the winner installed a different environment on the scene this frame.
16064
16452
  */
16065
16453
  #applyEnvironment(world) {
16066
16454
  const environments = world.components(Environment);
@@ -16077,7 +16465,7 @@ var RenderSyncSystem = class {
16077
16465
  world.app.log.warn("IGX-0705: {count} Environment components are enabled in this world; the most recent one wins.", enabledCount);
16078
16466
  }
16079
16467
  if (enabledCount <= 1) this.#hasLoggedMultipleEnvironments = false;
16080
- winner?.sync(this.#renderer);
16468
+ return winner?.sync(this.#renderer) ?? false;
16081
16469
  }
16082
16470
  /**
16083
16471
  * Reconciles every post-process stack.
@@ -32752,7 +33140,7 @@ function describeEnvironmentFileFormat() {
32752
33140
  skybox: {
32753
33141
  kind: "str",
32754
33142
  default: "",
32755
- description: "A .dds or .env skybox address; empty for none."
33143
+ description: "A .dds or .env skybox address; empty draws this environment's own cube map."
32756
33144
  },
32757
33145
  skyboxSize: {
32758
33146
  kind: "f32",
@@ -32762,7 +33150,7 @@ function describeEnvironmentFileFormat() {
32762
33150
  skyboxEnabled: {
32763
33151
  kind: "bool",
32764
33152
  default: true,
32765
- description: "Whether a skybox is drawn at all."
33153
+ description: "Whether a skybox is drawn at all; decided here, not on the component."
32766
33154
  },
32767
33155
  blur: {
32768
33156
  kind: "f32",