@ignifx/core 0.10.0 → 0.11.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
@@ -4704,7 +4704,7 @@ function createServiceKey(name) {
4704
4704
  *
4705
4705
  * @public
4706
4706
  */
4707
- const VERSION = "0.10.0";
4707
+ const VERSION = "0.11.0";
4708
4708
  //#endregion
4709
4709
  //#region src/assets/delivery-system.ts
4710
4710
  /**
@@ -10609,6 +10609,13 @@ var RendererImpl = class {
10609
10609
  #resolutionScale = 1;
10610
10610
  #pixelRatio;
10611
10611
  #profileTasks = false;
10612
+ #animateMaterialsInEditMode = true;
10613
+ /** The shader clock `ShaderUniformSystem` accumulates, which edit mode's post effects read too. */
10614
+ #shaderClock = {
10615
+ time: 0,
10616
+ unscaledTime: 0,
10617
+ deltaTime: 0
10618
+ };
10612
10619
  #isSceneRegistered = false;
10613
10620
  #isLoopRunning = false;
10614
10621
  #isDisposed = false;
@@ -10787,6 +10794,55 @@ var RendererImpl = class {
10787
10794
  else disableGpuTiming(this.engine);
10788
10795
  }
10789
10796
  /**
10797
+ * Whether the shader clock runs in an edit-mode app.
10798
+ *
10799
+ * @returns `true` unless an editor turned material animation off.
10800
+ */
10801
+ get animateMaterialsInEditMode() {
10802
+ return this.#animateMaterialsInEditMode;
10803
+ }
10804
+ set animateMaterialsInEditMode(value) {
10805
+ this.#animateMaterialsInEditMode = value;
10806
+ }
10807
+ /**
10808
+ * Records this frame's shader clock, as `ShaderUniformSystem` accumulated it: the one clock both
10809
+ * shader materials and, in edit mode, custom post effects read.
10810
+ *
10811
+ * @param time - Scaled seconds the clock has run.
10812
+ * @param unscaledTime - Unscaled seconds the clock has run.
10813
+ * @param deltaTime - This frame's step; `0` while the clock is held.
10814
+ *
10815
+ * @internal
10816
+ */
10817
+ setShaderClock(time, unscaledTime, deltaTime) {
10818
+ this.#shaderClock.time = time;
10819
+ this.#shaderClock.unscaledTime = unscaledTime;
10820
+ this.#shaderClock.deltaTime = deltaTime;
10821
+ }
10822
+ /**
10823
+ * Whether the shader clock stands still this frame because an edit-mode app turned material
10824
+ * animation off. `app.pause()` is checked separately, by each reader.
10825
+ *
10826
+ * @returns `true` while the editor's toggle holds the clock.
10827
+ *
10828
+ * @internal
10829
+ */
10830
+ get isShaderClockHeld() {
10831
+ return this.#app.isEditMode && !this.#animateMaterialsInEditMode;
10832
+ }
10833
+ /**
10834
+ * The clock custom post effects upload. In an edit-mode app it is the shader clock materials read
10835
+ * (`setShaderClock`), so the two never drift apart when the editor holds and resumes it
10836
+ * (ADR-0028, amendment of 2026-10-20). A game keeps the app's own clock.
10837
+ *
10838
+ * @returns The clock.
10839
+ *
10840
+ * @internal
10841
+ */
10842
+ get effectClock() {
10843
+ return this.#app.isEditMode ? this.#shaderClock : this.#app.time;
10844
+ }
10845
+ /**
10790
10846
  * GPU draw calls in the last rendered frame.
10791
10847
  *
10792
10848
  * @returns The count; `0` under a headless app.
@@ -14280,6 +14336,128 @@ function collectNames(node, out) {
14280
14336
  if (child !== void 0) collectNames(child, out);
14281
14337
  }
14282
14338
  }
14339
+ /**
14340
+ * The file name of the meshopt decoder script Lite injects.
14341
+ *
14342
+ * @internal
14343
+ */
14344
+ const MESHOPT_DECODER_FILE = "meshopt_decoder.js";
14345
+ /**
14346
+ * The transcoder modules `babylon.ktx2Decoder.js` fetches, as `[class, static property, file]`:
14347
+ * the class in the decoder's `KTX2DECODER` namespace whose property holds the URL, and the file
14348
+ * name it is served under. These are the defaults in `@babylonjs/ktx2decoder`'s
14349
+ * `Transcoders/*.js` and `zstddec.js`.
14350
+ *
14351
+ * @internal
14352
+ */
14353
+ const KTX2_TRANSCODER_FILES = [
14354
+ [
14355
+ "MSCTranscoder",
14356
+ "JSModuleURL",
14357
+ "msc_basis_transcoder.js"
14358
+ ],
14359
+ [
14360
+ "MSCTranscoder",
14361
+ "WasmModuleURL",
14362
+ "msc_basis_transcoder.wasm"
14363
+ ],
14364
+ [
14365
+ "ZSTDDecoder",
14366
+ "WasmModuleURL",
14367
+ "zstddec.wasm"
14368
+ ],
14369
+ [
14370
+ "LiteTranscoder_UASTC_ASTC",
14371
+ "WasmModuleURL",
14372
+ "uastc_astc.wasm"
14373
+ ],
14374
+ [
14375
+ "LiteTranscoder_UASTC_BC7",
14376
+ "WasmModuleURL",
14377
+ "uastc_bc7.wasm"
14378
+ ],
14379
+ [
14380
+ "LiteTranscoder_UASTC_R8_UNORM",
14381
+ "WasmModuleURL",
14382
+ "uastc_r8_unorm.wasm"
14383
+ ],
14384
+ [
14385
+ "LiteTranscoder_UASTC_RG8_UNORM",
14386
+ "WasmModuleURL",
14387
+ "uastc_rg8_unorm.wasm"
14388
+ ],
14389
+ [
14390
+ "LiteTranscoder_UASTC_RGBA_SRGB",
14391
+ "WasmModuleURL",
14392
+ "uastc_rgba8_srgb_v2.wasm"
14393
+ ],
14394
+ [
14395
+ "LiteTranscoder_UASTC_RGBA_UNORM",
14396
+ "WasmModuleURL",
14397
+ "uastc_rgba8_unorm_v2.wasm"
14398
+ ]
14399
+ ];
14400
+ /**
14401
+ * Reads the decoder locations a manifest records.
14402
+ *
14403
+ * @remarks
14404
+ * The transcoders are only worth overriding together with the decoder script that reads them, so
14405
+ * they are ignored when the manifest has no `babylon.ktx2Decoder.js`. Lite takes the meshopt
14406
+ * decoder's **directory**, so its entry is used only when its URL ends in the file name.
14407
+ *
14408
+ * @param manifest - The asset manifest.
14409
+ * @returns The locations; a `null` field means the manifest does not list that decoder.
14410
+ *
14411
+ * @example
14412
+ * ```ts
14413
+ * decoderUrlsFromManifest(app.assets.manifest).ktx2Decoder; // "/assets/babylon.ktx2Decoder.js"
14414
+ * ```
14415
+ *
14416
+ * @internal
14417
+ */
14418
+ function decoderUrlsFromManifest(manifest) {
14419
+ const urls = /* @__PURE__ */ new Map();
14420
+ for (const entry of manifest.entries) urls.set(entry.address, entry.url);
14421
+ const ktx2Decoder = urls.get("babylon.ktx2Decoder.js") ?? null;
14422
+ const ktx2Transcoders = {};
14423
+ if (ktx2Decoder !== null) for (const [name, property, file] of KTX2_TRANSCODER_FILES) {
14424
+ const url = urls.get(file);
14425
+ if (url !== void 0) ktx2Transcoders[name] = {
14426
+ ...ktx2Transcoders[name],
14427
+ [property]: url
14428
+ };
14429
+ }
14430
+ const meshoptUrl = urls.get(MESHOPT_DECODER_FILE);
14431
+ return {
14432
+ ktx2Decoder,
14433
+ ktx2Transcoders,
14434
+ meshoptBaseUrl: meshoptUrl?.endsWith("meshopt_decoder.js") === true ? meshoptUrl.slice(0, meshoptUrl.length - 18) : null
14435
+ };
14436
+ }
14437
+ /** What {@link configureDecoders} last handed Lite, so an unchanged manifest costs one comparison. */
14438
+ let appliedKey = null;
14439
+ /**
14440
+ * Points Lite at the decoders the app's manifest lists, before a load that may need one.
14441
+ *
14442
+ * @remarks
14443
+ * Lite's decoder locations are process-wide, so two apps on one page with different manifests share
14444
+ * the last one applied. Lite loads the KTX2 decoder once and keeps it, so this has to run before the
14445
+ * first KTX2 texture — the texture and model loaders call it at the start of every load, and a call
14446
+ * whose manifest has not changed does nothing.
14447
+ *
14448
+ * @param app - The app whose manifest to read.
14449
+ * @returns Once Lite has been told; immediately when the manifest lists no decoder.
14450
+ *
14451
+ * @internal
14452
+ */
14453
+ async function configureDecoders(app) {
14454
+ const urls = decoderUrlsFromManifest(app.assets.manifest);
14455
+ if (urls.ktx2Decoder === null && urls.meshoptBaseUrl === null) return;
14456
+ const key = JSON.stringify(urls);
14457
+ if (key === appliedKey) return;
14458
+ (await import("./decoders-CHJ7vduE.js")).applyLiteDecoderUrls(urls);
14459
+ appliedKey = key;
14460
+ }
14283
14461
  //#endregion
14284
14462
  //#region src/render/model-asset.ts
14285
14463
  /**
@@ -14477,6 +14655,13 @@ function createModelAsset(address, container, scene) {
14477
14655
  * asset pipeline produces, and the fix — passing the URL through for that one shape — is a
14478
14656
  * three-line change whenever a project needs it.
14479
14657
  *
14658
+ * ## Decoders
14659
+ *
14660
+ * A glTF may need one of Lite's run-time decoders: `KHR_texture_basisu` images go through the KTX2
14661
+ * decoder and `EXT_meshopt_compression` buffers through the meshopt decoder. Both load from
14662
+ * `cdn.babylonjs.com` unless told otherwise, so the loader calls `configureDecoders` first, which
14663
+ * points Lite at the copies `@ignifx/vite-plugin` serves (`../decoder-urls.ts`).
14664
+ *
14480
14665
  * ## Headless
14481
14666
  *
14482
14667
  * `loadGltf` throws a `TypeError` under the null engine: it uploads while parsing and reaches for
@@ -14504,6 +14689,7 @@ function createModelLoader() {
14504
14689
  async load(ctx) {
14505
14690
  const bytes = await ctx.fetchBytes();
14506
14691
  if (ctx.app.isHeadless) return createModelAsset(ctx.address, null, null);
14692
+ await configureDecoders(ctx.app);
14507
14693
  const container = await loadGltfFromBytes(ctx.lite.engine, bytes);
14508
14694
  return createModelAsset(ctx.address, container, ctx.app.lite.scene);
14509
14695
  },
@@ -14694,6 +14880,50 @@ function loadTexture(engine, url, options) {
14694
14880
  return loadTexture2D(engine, url, options);
14695
14881
  }
14696
14882
  /**
14883
+ * Loads a KTX2 (Basis Universal) texture from a URL, transcoded to the device's best compressed
14884
+ * format.
14885
+ *
14886
+ * @remarks
14887
+ * Lite's KTX2 glue is imported on first use (`./decoders.ts`), so a game that never loads a `.ktx2`
14888
+ * does not carry it. The decoder script and its transcoders load from wherever
14889
+ * `applyLiteDecoderUrls` last pointed Lite, or from `cdn.babylonjs.com` when nothing did. Sampler and
14890
+ * sRGB options apply; `mipMaps`, `invertY` and `premultiplyAlpha` do not — the file's rows and mips
14891
+ * are uploaded as stored (`./decoders.ts` explains the orientation).
14892
+ *
14893
+ * @param engine - The engine that owns the GPU texture.
14894
+ * @param url - Where to fetch it from.
14895
+ * @param options - Colour space and sampler.
14896
+ * @returns The texture. Its reference count starts at an implicit one.
14897
+ *
14898
+ * @example
14899
+ * ```ts
14900
+ * const albedo = await loadKtx2Texture(engine, "textures/hero-albedo.ktx2", { srgb: true });
14901
+ * ```
14902
+ *
14903
+ * @internal
14904
+ */
14905
+ async function loadKtx2Texture(engine, url, options = {}) {
14906
+ return (await import("./decoders-CHJ7vduE.js")).loadKtx2TextureWithOptions(engine, url, options);
14907
+ }
14908
+ /**
14909
+ * Loads a Basis Universal (`.basis`) texture from a URL.
14910
+ *
14911
+ * @remarks
14912
+ * Babylon Lite 1.34 always fetches the Basis transcoder from `cdn.babylonjs.com` and offers no
14913
+ * setter for it, so this works only where the page may load scripts from that origin. Prefer
14914
+ * `.ktx2`, which carries the same Basis payloads and whose decoder is served locally.
14915
+ *
14916
+ * @param engine - The engine that owns the GPU texture.
14917
+ * @param url - Where to fetch it from.
14918
+ * @param options - Colour space and sampler.
14919
+ * @returns The texture.
14920
+ *
14921
+ * @internal
14922
+ */
14923
+ async function loadBasisTexture(engine, url, options = {}) {
14924
+ return (await import("./decoders-CHJ7vduE.js")).loadBasisTextureWithOptions(engine, url, options);
14925
+ }
14926
+ /**
14697
14927
  * Creates a 2D texture from tightly packed RGBA8 bytes.
14698
14928
  *
14699
14929
  * @param engine - The engine that owns the GPU texture.
@@ -15241,6 +15471,17 @@ function readString$1(block, key, fallback) {
15241
15471
  * one place §5's "the three `fetch*` methods are the only network paths" does not hold; the
15242
15472
  * alternative is worse.
15243
15473
  *
15474
+ * ## The container picks the decoder
15475
+ *
15476
+ * `.png`, `.jpg`, `.jpeg` and `.webp` go to `loadTexture2D` and the browser's image decoder.
15477
+ * `.ktx2` goes to Lite's KTX2 loader and `.basis` to its Basis loader, which transcode to the
15478
+ * device's best compressed format (`src/lite/gpu/decoders.ts` lists the targets); handing either
15479
+ * to `createImageBitmap` fails with "The source image could not be decoded". The asset type stays
15480
+ * `texture` for all six, so the choice is made here, from the address's extension — the one name a
15481
+ * manifest entry, a hashed build URL and a hand-written `{ type: "texture" }` load all keep. Before
15482
+ * a KTX2 or Basis load, {@link configureDecoders} points Lite at the decoders the manifest lists,
15483
+ * which is how a built game avoids `cdn.babylonjs.com`.
15484
+ *
15244
15485
  * ## Options come from the sidecar
15245
15486
  *
15246
15487
  * `.meta.json` sidecars carry per-asset import options (§7), the build copies them into the
@@ -15274,7 +15515,9 @@ function createTextureLoader() {
15274
15515
  const options = readTextureImportOptions(ctx.meta);
15275
15516
  if (ctx.app.isHeadless) return new TextureAsset(ctx.address, null, options);
15276
15517
  ctx.reportProgress(0);
15277
- const texture = await loadTexture(ctx.lite.engine, ctx.url, toLiteTextureOptions(options));
15518
+ const container = textureContainerOf(ctx.address, ctx.url);
15519
+ if (container !== "image") await configureDecoders(ctx.app);
15520
+ const texture = await loadByContainer(container, ctx.lite.engine, ctx.url, toLiteTextureOptions(options));
15278
15521
  ctx.reportProgress(1);
15279
15522
  return new TextureAsset(ctx.address, texture, options);
15280
15523
  },
@@ -15283,6 +15526,57 @@ function createTextureLoader() {
15283
15526
  }
15284
15527
  };
15285
15528
  }
15529
+ /**
15530
+ * The lowercase extension of a path or URL, without its query or fragment.
15531
+ *
15532
+ * @param reference - An address or URL.
15533
+ * @returns The extension with its dot, or `""`.
15534
+ */
15535
+ function extensionOf(reference) {
15536
+ const path = reference.split(/[?#]/u, 1)[0] ?? "";
15537
+ const name = path.slice(path.lastIndexOf("/") + 1);
15538
+ const dot = name.lastIndexOf(".");
15539
+ return dot <= 0 ? "" : name.slice(dot).toLowerCase();
15540
+ }
15541
+ /**
15542
+ * Decides which Lite loader a texture needs.
15543
+ *
15544
+ * @remarks
15545
+ * The address decides; the URL is consulted only when the address has no extension, which happens
15546
+ * when a load passes `{ type: "texture" }` for an address the manifest maps to a file. Anything that
15547
+ * is neither `.ktx2` nor `.basis` is an image for the browser to decode.
15548
+ *
15549
+ * @param address - The asset address.
15550
+ * @param url - The URL it resolved to.
15551
+ * @returns The container.
15552
+ *
15553
+ * @example
15554
+ * ```ts
15555
+ * textureContainerOf("textures/rock.ktx2", "/assets/textures/rock.3f2a1b9c.ktx2"); // "ktx2"
15556
+ * ```
15557
+ *
15558
+ * @internal
15559
+ */
15560
+ function textureContainerOf(address, url) {
15561
+ const extension = extensionOf(address) || extensionOf(url);
15562
+ if (extension === ".ktx2") return "ktx2";
15563
+ if (extension === ".basis") return "basis";
15564
+ return "image";
15565
+ }
15566
+ /**
15567
+ * Loads a texture with the Lite loader its container needs.
15568
+ *
15569
+ * @param container - What the file is.
15570
+ * @param engine - The engine that owns the GPU texture.
15571
+ * @param url - Where to fetch it from.
15572
+ * @param options - Lite's texture options, from the sidecar.
15573
+ * @returns The texture.
15574
+ */
15575
+ function loadByContainer(container, engine, url, options) {
15576
+ if (container === "ktx2") return loadKtx2Texture(engine, url, options);
15577
+ if (container === "basis") return loadBasisTexture(engine, url, options);
15578
+ return loadTexture(engine, url, options);
15579
+ }
15286
15580
  //#endregion
15287
15581
  //#region src/render/gpu/mesh-instance.ts
15288
15582
  /**
@@ -16894,7 +17188,7 @@ var PostProcessStack = class PostProcessStack extends Component {
16894
17188
  }
16895
17189
  if (!this.#hasWarnedAboutFeature && !renderer.features.postProcessing) this.#warnAboutFeature(renderer, this.plannedChain().length);
16896
17190
  const surface = renderer.surface;
16897
- applyPostProcessSettings(this.#chain, this.isEnabledInHierarchy, this.bloom, this.smaa, renderer.app.time, surface?.width ?? 0, surface?.height ?? 0, renderer.isSceneRegistered);
17191
+ applyPostProcessSettings(this.#chain, this.isEnabledInHierarchy, this.bloom, this.smaa, renderer.effectClock, surface?.width ?? 0, surface?.height ?? 0, renderer.isSceneRegistered);
16898
17192
  }
16899
17193
  /**
16900
17194
  * Replaces the chain with one that holds the effects the fields currently ask for.
@@ -17610,8 +17904,10 @@ var RenderSyncSystem = class {
17610
17904
  * The clock is accumulated here rather than read from `app.time.time` because a system keeps running
17611
17905
  * with a non-zero `dt` while the app is paused and has to check `time.paused` itself
17612
17906
  * (`docs/architecture/01-lifecycle-and-time.md` §7); that is what freezes `time` under
17613
- * `app.pause()` and resumes it without a jump. A held clock (`ctx.isClockHeld`, edit mode) freezes
17614
- * it the same way.
17907
+ * `app.pause()` and resumes it without a jump. In an edit-mode app the system runs, so materials
17908
+ * animate as an editor previews them, and `app.renderer.animateMaterialsInEditMode = false` freezes
17909
+ * the clock the same way (ADR-0028, amendment of 2026-10-20). A held clock (`ctx.isClockHeld`, for a
17910
+ * registration that asks for `"hold"`) would too.
17615
17911
  */
17616
17912
  /**
17617
17913
  * Where the shader uniform writer sits inside `PreRender`: just before the render sync
@@ -17665,18 +17961,20 @@ var ShaderUniformSystem = class {
17665
17961
  */
17666
17962
  update(ctx) {
17667
17963
  const time = ctx.time;
17668
- const isPaused = time.paused || ctx.isClockHeld;
17964
+ const renderer = rendererInternals(this.#app.renderer);
17965
+ const isPaused = time.paused || ctx.isClockHeld || renderer.isShaderClockHeld;
17669
17966
  if (!isPaused) {
17670
17967
  this.#time += time.deltaTime;
17671
17968
  this.#unscaledTime += time.unscaledDeltaTime;
17672
17969
  }
17970
+ const delta = isPaused ? 0 : time.deltaTime;
17971
+ renderer.setShaderClock(this.#time, this.#unscaledTime, delta);
17673
17972
  const support = shaderSupport();
17674
17973
  if (support === null) return;
17675
17974
  const materials = support.shaderMaterialsOf(this.#app).animated;
17676
17975
  if (materials.length === 0) return;
17677
17976
  const hasLight = this.#readMainLight(ctx.world);
17678
17977
  this.#readAmbient();
17679
- const delta = isPaused ? 0 : time.deltaTime;
17680
17978
  for (let index = 0; index < materials.length; index += 1) materials[index]?.writeFrameUniforms(this.#time, this.#unscaledTime, delta, this.#frame, hasLight);
17681
17979
  }
17682
17980
  /**
@@ -22620,8 +22918,7 @@ function registerRendering(ctx) {
22620
22918
  ctx.registerAssetLoader(createMeshLoader());
22621
22919
  ctx.registerSystem(new ShaderUniformSystem(ctx.app), {
22622
22920
  phase: Phase.PreRender,
22623
- order: SHADER_UNIFORM_ORDER,
22624
- editMode: "hold"
22921
+ order: SHADER_UNIFORM_ORDER
22625
22922
  });
22626
22923
  const sync = new RenderSyncSystem(renderer);
22627
22924
  renderer.attachSyncSystem(sync);