@ignifx/core 0.12.0 → 0.14.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.
Files changed (31) hide show
  1. package/dist/{environment-C9AjYJgV.js → environment-Cq2BmA96.js} +2 -2
  2. package/dist/{environment-C9AjYJgV.js.map → environment-Cq2BmA96.js.map} +1 -1
  3. package/dist/hdr-output-DDpIo4Q5.js +300 -0
  4. package/dist/hdr-output-DDpIo4Q5.js.map +1 -0
  5. package/dist/{ignifx-error-Dq2qJMkZ.js → ignifx-error-oYdVnT1S.js} +16 -1
  6. package/dist/ignifx-error-oYdVnT1S.js.map +1 -0
  7. package/dist/index.d.ts +343 -4
  8. package/dist/index.d.ts.map +1 -1
  9. package/dist/index.js +842 -165
  10. package/dist/index.js.map +1 -1
  11. package/dist/material-CGk5mAah.js +204 -0
  12. package/dist/material-CGk5mAah.js.map +1 -0
  13. package/dist/{material-plugin-BOCB7Stt.js → material-plugin-BUlqLsap.js} +3 -204
  14. package/dist/material-plugin-BUlqLsap.js.map +1 -0
  15. package/dist/{post-effect-compiler-Dw6zW2cG.js → post-effect-compiler-CRek8VxQ.js} +2 -2
  16. package/dist/{post-effect-compiler-Dw6zW2cG.js.map → post-effect-compiler-CRek8VxQ.js.map} +1 -1
  17. package/dist/render-path-Dx0learj.js +135 -0
  18. package/dist/render-path-Dx0learj.js.map +1 -0
  19. package/dist/render-texture-IuR0iFVa.js +174 -0
  20. package/dist/render-texture-IuR0iFVa.js.map +1 -0
  21. package/dist/{shader-material-BxQn9FT4.js → shader-material-BPb_oEZQ.js} +2 -2
  22. package/dist/{shader-material-BxQn9FT4.js.map → shader-material-BPb_oEZQ.js.map} +1 -1
  23. package/dist/{shader-material-DRZmqA_S.js → shader-material-CDQ0Y5kN.js} +3 -3
  24. package/dist/{shader-material-DRZmqA_S.js.map → shader-material-CDQ0Y5kN.js.map} +1 -1
  25. package/dist/{shader-pragma-DrFm5f5m.js → shader-pragma-BKCoZTTA.js} +2 -2
  26. package/dist/{shader-pragma-DrFm5f5m.js.map → shader-pragma-BKCoZTTA.js.map} +1 -1
  27. package/dist/{surface-shader-BgZchRBe.js → surface-shader-CwQ03yHG.js} +5 -4
  28. package/dist/{surface-shader-BgZchRBe.js.map → surface-shader-CwQ03yHG.js.map} +1 -1
  29. package/package.json +1 -1
  30. package/dist/ignifx-error-Dq2qJMkZ.js.map +0 -1
  31. package/dist/material-plugin-BOCB7Stt.js.map +0 -1
package/dist/index.d.ts CHANGED
@@ -187,6 +187,8 @@ export declare const CoreErrorCode: {
187
187
  readonly physicsCallbackOutsideFixedStep: "IGX-0409";
188
188
  /** A second, different simulation scene was handed to a world that already has one. */
189
189
  readonly simulationSceneAlreadySet: "IGX-0410";
190
+ /** One `Extension` object was handed to a second app while the first still runs it. */
191
+ readonly extensionInstalledTwice: "IGX-0411";
190
192
  /** An asset's value was read before the asset finished loading. */
191
193
  readonly assetNotLoaded: "IGX-0501";
192
194
  /** An asset load was aborted through its `AbortSignal`. */
@@ -279,6 +281,14 @@ export declare const CoreErrorCode: {
279
281
  readonly instancingLodWithoutCulling: "IGX-0727";
280
282
  /** `app.renderer.openOverlay()` was called on a headless app, or before `app.start()` registered the render scene. */
281
283
  readonly overlayNeedsRenderScene: "IGX-0728";
284
+ /** A render texture was rendered into or read on a headless app, or before `app.start()` started the render loop. */
285
+ readonly renderTextureNeedsRenderLoop: "IGX-0729";
286
+ /** `app.renderer.createRenderTexture` was given a side that is not a whole number from 1 to 4096. */
287
+ readonly invalidRenderTextureSize: "IGX-0730";
288
+ /** A render texture was used after `dispose()`, or with another app's renderer. */
289
+ readonly renderTextureUnusable: "IGX-0731";
290
+ /** `app.renderer.renderToTexture` was given a camera that is not attached to an entity. */
291
+ readonly renderTextureCameraDetached: "IGX-0732";
282
292
  /** The host exposes no Web Crypto implementation. */
283
293
  readonly cryptoUnavailable: "IGX-1420";
284
294
  /** A storage namespace name is not a legal namespace segment. */
@@ -1898,6 +1908,10 @@ interface ComponentClassInfo {
1898
1908
  readonly requires: readonly ComponentType[];
1899
1909
  /** `false` when at most one instance may live on an entity. */
1900
1910
  readonly allowMultiple: boolean;
1911
+ /** The class's own `static title`, or `null` when it declares none (an inherited one is ignored). */
1912
+ readonly title: string | null;
1913
+ /** The class's own `static description`, or `null` when it declares none (an inherited one is ignored). */
1914
+ readonly description: string | null;
1901
1915
  /**
1902
1916
  * The class and every component class it derives from, nearest first, ending at `Component`.
1903
1917
  * `world.components(Type)` and `getComponent(Type)` match against this list, which is why they
@@ -3712,6 +3726,8 @@ export declare class Transform extends Component {
3712
3726
  #private;
3713
3727
  /** The registration id of the one component every entity carries. */
3714
3728
  static typeId: string;
3729
+ /** What the component does, in one line, for an inspector. */
3730
+ static description: string;
3715
3731
  /** An entity has exactly one transform. */
3716
3732
  static allowMultiple: boolean;
3717
3733
  /** Creates an unbound transform. The entity constructor binds it to a Lite node immediately. */
@@ -7780,6 +7796,18 @@ interface RenderingSettings {
7780
7796
  readonly clearColor: ColorLike;
7781
7797
  /** The address of the RGBD BRDF lookup table `loadEnvironment` requires. */
7782
7798
  readonly brdfLut: string;
7799
+ /**
7800
+ * Render the scene into a floating-point (`rgba16float`) target and tone map it in one final pass.
7801
+ *
7802
+ * @remarks
7803
+ * Off by default, and nothing of it loads while it is off. On, PBR materials keep their linear
7804
+ * colour, which may go above 1, and a final output pass applies the `Environment`'s exposure,
7805
+ * contrast and tone-mapping curve and encodes the result for the screen. A scene that only uses
7806
+ * PBR materials looks the same either way; later effects (HDR bloom, auto exposure) need it on.
7807
+ * Fog, Standard materials, surface shaders, sprites, particles and the skybox are not yet carried
7808
+ * in linear colour (`docs/plan/2026-11-gi-phase-1-execution-plan.md`, step G3).
7809
+ */
7810
+ readonly hdr: boolean;
7783
7811
  }
7784
7812
  /**
7785
7813
  * The name the `rendering` project settings section is registered under.
@@ -7812,6 +7840,23 @@ export declare const DEFAULT_BRDF_LUT_ADDRESS = "environments/brdf-lut.png";
7812
7840
  export declare function defaultRenderingSettings(): RenderingSettings;
7813
7841
  //#endregion
7814
7842
  //#region src/lite/gpu/render-path.d.ts
7843
+ /**
7844
+ * The HDR half of a presenter, when `rendering.hdr` built one (`./hdr-output.ts`).
7845
+ *
7846
+ * @internal
7847
+ */
7848
+ interface HdrOutputHandle {
7849
+ /** The scene's linear `rgba16float` colour, as a sampled texture. Values may exceed 1. */
7850
+ readonly sceneTexture: Texture2D;
7851
+ /**
7852
+ * The per-frame work: uploads the scene's exposure, contrast and curve when they changed, and
7853
+ * gives every new PBR material the linear-output plugin.
7854
+ *
7855
+ * @param isSceneRegistered - Whether Lite has built the scene, so a patched material needs a
7856
+ * rebuild.
7857
+ */
7858
+ update(isSceneRegistered: boolean): void;
7859
+ }
7815
7860
  /**
7816
7861
  * A scene's offscreen render path: the colour a `PostProcessStack` reads, and the compositing blit
7817
7862
  * it takes over from.
@@ -7834,6 +7879,8 @@ interface ScenePresenter {
7834
7879
  setPresentEnabled(enabled: boolean): void;
7835
7880
  /** Whether the compositing blit currently runs. */
7836
7881
  readonly isPresentEnabled: boolean;
7882
+ /** The HDR output pass, when `rendering.hdr` is on; `null` for the plain offscreen path. */
7883
+ readonly hdr: HdrOutputHandle | null;
7837
7884
  }
7838
7885
  //#endregion
7839
7886
  //#region src/lite/picking.d.ts
@@ -8325,6 +8372,49 @@ interface Renderer {
8325
8372
  * would never settle.
8326
8373
  */
8327
8374
  captureScreenshot(): Promise<RenderCapture>;
8375
+ /**
8376
+ * Creates an offscreen texture a camera can render into, beside the main view
8377
+ * (`docs/architecture/07-rendering.md` §2.11).
8378
+ *
8379
+ * @remarks
8380
+ * Fill it once with {@link Renderer.renderToTexture}, or every frame by setting a camera's
8381
+ * `renderTarget`. Its GPU pass and target are created on the first render or read, so creating
8382
+ * one costs nothing until then, and a headless app may create one (it can never fill it).
8383
+ *
8384
+ * @param width - The width, in pixels: a whole number from 1 to 4096.
8385
+ * @param height - The height, in pixels: a whole number from 1 to 4096.
8386
+ * @returns The texture. Dispose it when done; `app.dispose()` disposes any still open.
8387
+ * @throws IgnifxError with code `IGX-0730` for a side out of range, and `IGX-0106` once the app is
8388
+ * disposed.
8389
+ *
8390
+ * @beta
8391
+ */
8392
+ createRenderTexture(width: number, height: number): RenderTexture;
8393
+ /**
8394
+ * Renders the scene through a camera into a texture on the next frame, beside the main view
8395
+ * (`docs/architecture/07-rendering.md` §2.11).
8396
+ *
8397
+ * @remarks
8398
+ * The camera need not be the main one, and stays a candidate for it. Requests queued for the
8399
+ * same texture render one camera per frame, oldest first. The camera's aspect is the texture's.
8400
+ * Read the result with {@link RenderTexture.readPixels}.
8401
+ *
8402
+ * @param camera - A camera attached to an entity of this app's world.
8403
+ * @param texture - A texture from this renderer's {@link Renderer.createRenderTexture}.
8404
+ * @returns A promise that settles once the frame that rendered it has been submitted.
8405
+ * @throws IgnifxError with code `IGX-0729` on a headless app or while no render loop runs,
8406
+ * `IGX-0731` for a disposed or foreign texture, and `IGX-0732` for a detached camera.
8407
+ *
8408
+ * @example
8409
+ * ```ts
8410
+ * const texture = app.renderer.createRenderTexture(128, 128);
8411
+ * await app.renderer.renderToTexture(previewCamera, texture);
8412
+ * const { data } = await texture.readPixels();
8413
+ * ```
8414
+ *
8415
+ * @beta
8416
+ */
8417
+ renderToTexture(camera: Camera, texture: RenderTexture): Promise<void>;
8328
8418
  /**
8329
8419
  * The latest per-task GPU timing snapshot. Check `status` before reading `tasks`.
8330
8420
  *
@@ -8620,6 +8710,33 @@ declare class RendererImpl implements Renderer {
8620
8710
  * @throws IgnifxError with code `IGX-0707` when no render loop is running.
8621
8711
  */
8622
8712
  captureScreenshot(): Promise<RenderCapture>;
8713
+ /**
8714
+ * Creates an offscreen texture a camera can render into.
8715
+ *
8716
+ * @param width - The width, in pixels.
8717
+ * @param height - The height, in pixels.
8718
+ * @returns The texture.
8719
+ * @throws IgnifxError with code `IGX-0730` for a side out of range, `IGX-0106` once disposed.
8720
+ */
8721
+ createRenderTexture(width: number, height: number): RenderTexture;
8722
+ /**
8723
+ * Renders the scene through a camera into a texture on the next frame.
8724
+ *
8725
+ * @param camera - The camera.
8726
+ * @param texture - The texture.
8727
+ * @returns A promise that settles once the frame has been submitted.
8728
+ * @throws IgnifxError with code `IGX-0729`, `IGX-0731` or `IGX-0732`; see the interface.
8729
+ */
8730
+ renderToTexture(camera: Camera, texture: RenderTexture): Promise<void>;
8731
+ /**
8732
+ * Points every render texture's pass at this frame's camera. The `PreRender` sync calls it after
8733
+ * the main camera is chosen.
8734
+ *
8735
+ * @param cameras - Every camera in the world, in creation order.
8736
+ *
8737
+ * @internal
8738
+ */
8739
+ syncRenderTextures(cameras: readonly Camera[]): void;
8623
8740
  /**
8624
8741
  * The latest per-task GPU timing snapshot.
8625
8742
  *
@@ -8761,6 +8878,7 @@ declare class RendererImpl implements Renderer {
8761
8878
  applyClearColor(value: ColorLike): void;
8762
8879
  /**
8763
8880
  * Re-applies the clear colour when the scene's image processing changed since it was written.
8881
+ * With `rendering.hdr` on it runs the HDR output pass's per-frame update instead.
8764
8882
  *
8765
8883
  * @remarks
8766
8884
  * The `PreRender` system calls it every frame, after the `Environment` has written its image
@@ -8932,6 +9050,51 @@ export declare function forceRendererDeviceLossForTesting(renderer: Renderer): v
8932
9050
  */
8933
9051
  type LiteCamera = FreeCamera;
8934
9052
  //#endregion
9053
+ //#region src/render/render-texture.d.ts
9054
+ /**
9055
+ * The largest side of a render texture, in pixels.
9056
+ *
9057
+ * @public
9058
+ */
9059
+ export declare const RENDER_TEXTURE_MAX_SIZE = 4096;
9060
+ /**
9061
+ * An offscreen colour target a camera renders into (`docs/architecture/07-rendering.md` §2.11).
9062
+ *
9063
+ * @remarks
9064
+ * Create one with `app.renderer.createRenderTexture(width, height)`. Fill it once with
9065
+ * `app.renderer.renderToTexture(camera, texture)`, or every frame by setting a camera's
9066
+ * `renderTarget`. It holds a GPU pass of the render scene and its target from the first render
9067
+ * on; `dispose()` frees both, and `app.dispose()` disposes every texture still open.
9068
+ *
9069
+ * @example
9070
+ * ```ts
9071
+ * const texture = app.renderer.createRenderTexture(256, 256);
9072
+ * await app.renderer.renderToTexture(minimapCamera, texture);
9073
+ * const pixels = await texture.readPixels();
9074
+ * texture.dispose();
9075
+ * ```
9076
+ *
9077
+ * @beta
9078
+ */
9079
+ interface RenderTexture {
9080
+ /** The width, in pixels. */
9081
+ readonly width: number;
9082
+ /** The height, in pixels. */
9083
+ readonly height: number;
9084
+ /** Whether `dispose()` has run. */
9085
+ readonly isDisposed: boolean;
9086
+ /**
9087
+ * Reads the texture as the last rendered frame left it.
9088
+ *
9089
+ * @returns Tightly packed RGBA8, top row first. All zeros before anything was rendered into it.
9090
+ * @throws IgnifxError with code `IGX-0729` on a headless app or while no render loop runs, and
9091
+ * `IGX-0731` once the texture is disposed.
9092
+ */
9093
+ readPixels(): Promise<RenderCapture>;
9094
+ /** Frees the texture's GPU pass and target. Idempotent; a camera rendering into it stops. */
9095
+ dispose(): void;
9096
+ }
9097
+ //#endregion
8935
9098
  //#region src/math/mat4.d.ts
8936
9099
  /**
8937
9100
  * The backing store of a {@link Mat4}: a `Float32Array` of exactly 16 elements, in column-major
@@ -9457,6 +9620,8 @@ export declare class Camera extends Component implements ComponentHooks {
9457
9620
  #private;
9458
9621
  /** The namespaced registration id. */
9459
9622
  static typeId: string;
9623
+ /** What the component does, in one line, for an inspector. */
9624
+ static description: string;
9460
9625
  /** At most one camera per entity: two views from one transform would be the same view. */
9461
9626
  static allowMultiple: boolean;
9462
9627
  /** The serialized field declarations (ADR-0004). */
@@ -9474,6 +9639,26 @@ export declare class Camera extends Component implements ComponentHooks {
9474
9639
  };
9475
9640
  clearColor: ColorLike | null;
9476
9641
  priority: number;
9642
+ /**
9643
+ * The texture this camera renders into every frame, instead of the canvas, or `null` for the
9644
+ * canvas (`docs/architecture/07-rendering.md` §2.11).
9645
+ *
9646
+ * @remarks
9647
+ * A camera with a render target is never the main camera, whatever its `priority`; it draws the
9648
+ * same scene from its own view into the texture, at the texture's aspect, in every frame it is
9649
+ * enabled. Runtime state: it is not serialized. Create the texture with
9650
+ * `app.renderer.createRenderTexture`.
9651
+ *
9652
+ * @example
9653
+ * ```ts
9654
+ * const minimap = app.renderer.createRenderTexture(256, 256);
9655
+ * overhead.renderTarget = minimap;
9656
+ * const pixels = await minimap.readPixels();
9657
+ * ```
9658
+ *
9659
+ * @beta
9660
+ */
9661
+ renderTarget: RenderTexture | null;
9477
9662
  /** Applies the schema defaults, exactly as `Component.define` would. */
9478
9663
  constructor();
9479
9664
  /**
@@ -11423,6 +11608,17 @@ interface ComponentStatics {
11423
11608
  readonly requires?: readonly ComponentType[];
11424
11609
  /** `false` when at most one instance may be attached to an entity; defaults to `true`. */
11425
11610
  readonly allowMultiple?: boolean;
11611
+ /**
11612
+ * The name an inspector shows for the component, for example `"Rigidbody mover"`. Read only from
11613
+ * the class that declares it, never inherited; without one, tools title the component from its
11614
+ * type id.
11615
+ */
11616
+ readonly title?: string;
11617
+ /**
11618
+ * A one-line summary of what the component does, shown by an inspector. Read only from the class
11619
+ * that declares it, never inherited.
11620
+ */
11621
+ readonly description?: string;
11426
11622
  }
11427
11623
  /**
11428
11624
  * The static members a script class may declare: everything {@link ComponentStatics} allows plus
@@ -13611,7 +13807,8 @@ interface App {
13611
13807
  */
13612
13808
  registerComponents(types: readonly ConcreteComponentType[]): void;
13613
13809
  /**
13614
- * Runs extension `onStart` hooks and starts the frame loop.
13810
+ * Runs extension `onStart` hooks and starts the frame loop. A no-op while running; after `stop()`
13811
+ * it restarts the loop without running `onStart` again.
13615
13812
  *
13616
13813
  * @returns A promise that settles once the first frame has been submitted.
13617
13814
  */
@@ -13905,7 +14102,8 @@ interface Extension {
13905
14102
  */
13906
14103
  register(ctx: ExtensionContext): void | Promise<void>;
13907
14104
  /**
13908
- * Runs after every extension registered and the Lite engine exists, before the first frame.
14105
+ * Runs after every extension registered and the Lite engine exists, before the first frame. It
14106
+ * runs once: a start after `app.stop()` does not run it again.
13909
14107
  *
13910
14108
  * @param app - The app being started.
13911
14109
  * @returns Nothing, or a promise `app.start()` awaits.
@@ -16009,6 +16207,8 @@ export declare class Environment extends Component implements ComponentHooks {
16009
16207
  #private;
16010
16208
  /** The namespaced registration id. */
16011
16209
  static typeId: string;
16210
+ /** What the component does, in one line, for an inspector. */
16211
+ static description: string;
16012
16212
  /** One per entity, and effectively one per world: the fields are all scene state. */
16013
16213
  static allowMultiple: boolean;
16014
16214
  /** The serialized field declarations (ADR-0004). */
@@ -16292,6 +16492,21 @@ interface LightShadowSettings {
16292
16492
  cascades: number;
16293
16493
  /** The distance beyond which nothing is shadowed, in metres; `0` takes Lite's default. */
16294
16494
  maxDistance: number;
16495
+ /**
16496
+ * Whether cascades use a stable sphere fit, CSM only. `true` stops shadow edges shimmering as the
16497
+ * camera moves, at the cost of some resolution. Default `false`.
16498
+ */
16499
+ stabilizeCascades: boolean;
16500
+ /**
16501
+ * How the cascade splits are spaced, CSM only, from `0` (even) to `1` (logarithmic: more detail
16502
+ * near the camera). Default `0.5`.
16503
+ */
16504
+ cascadeLambda: number;
16505
+ /**
16506
+ * The fraction of each cascade that cross-fades into the next, CSM only, from `0` to `1`; `0`
16507
+ * turns blending off and shows hard seams. Default `0.1`.
16508
+ */
16509
+ cascadeBlend: number;
16295
16510
  }
16296
16511
  /**
16297
16512
  * A light source (`docs/architecture/07-rendering.md` §2.2).
@@ -16317,6 +16532,8 @@ export declare class Light extends Component implements ComponentHooks {
16317
16532
  #private;
16318
16533
  /** The namespaced registration id. */
16319
16534
  static typeId: string;
16535
+ /** What the component does, in one line, for an inspector. */
16536
+ static description: string;
16320
16537
  /** At most one light per entity: two lights from one transform want two entities. */
16321
16538
  static allowMultiple: boolean;
16322
16539
  /** The serialized field declarations (ADR-0004). */
@@ -17427,6 +17644,8 @@ export declare class MeshRenderer extends Component implements ComponentHooks {
17427
17644
  #private;
17428
17645
  /** The namespaced registration id. */
17429
17646
  static typeId: string;
17647
+ /** What the component does, in one line, for an inspector. */
17648
+ static description: string;
17430
17649
  /** Several renderers on one entity draw several meshes from one transform, which is useful. */
17431
17650
  static allowMultiple: boolean;
17432
17651
  /** The serialized field declarations (ADR-0004). */
@@ -17928,6 +18147,8 @@ export declare class InstancedMeshRenderer extends Component implements Componen
17928
18147
  #private;
17929
18148
  /** The namespaced registration id. */
17930
18149
  static typeId: string;
18150
+ /** What the component does, in one line, for an inspector. */
18151
+ static description: string;
17931
18152
  /** Several instanced renderers on one entity draw several clouds from one transform. */
17932
18153
  static allowMultiple: boolean;
17933
18154
  /** The serialized field declarations (ADR-0004). */
@@ -18078,6 +18299,8 @@ export declare class Model extends Component implements ComponentHooks {
18078
18299
  #private;
18079
18300
  /** The namespaced registration id. */
18080
18301
  static typeId: string;
18302
+ /** What the component does, in one line, for an inspector. */
18303
+ static description: string;
18081
18304
  /** One model per entity: a second instance under the same transform wants its own entity. */
18082
18305
  static allowMultiple: boolean;
18083
18306
  /** The serialized field declarations (ADR-0004). */
@@ -18335,6 +18558,8 @@ export declare class PostProcessStack extends Component implements ComponentHook
18335
18558
  #private;
18336
18559
  /** The namespaced registration id. */
18337
18560
  static typeId: string;
18561
+ /** What the component does, in one line, for an inspector. */
18562
+ static description: string;
18338
18563
  /** One chain per camera entity; a second would fight the first for the swapchain. */
18339
18564
  static allowMultiple: boolean;
18340
18565
  /** The serialized field declarations (ADR-0004). */
@@ -18533,6 +18758,115 @@ type EntityOverrideField = "name" | "active" | "static" | "layer" | "tags";
18533
18758
  */
18534
18759
  export declare function parseOverridePath(path: string): OverridePath;
18535
18760
  //#endregion
18761
+ //#region src/serialization/prefab-overrides.d.ts
18762
+ /**
18763
+ * Which overrides of an instance {@link applyOverridesToAsset} and {@link revertOverrides} act on.
18764
+ *
18765
+ * @public
18766
+ */
18767
+ interface PrefabOverrideSelection {
18768
+ /**
18769
+ * Override paths to act on. A path selects every override at that path or below it, so
18770
+ * `"<entityUid>"` selects everything on that entity and `"<entityUid>/components/<componentUid>"`
18771
+ * selects a component's removal, its `enabled` flag, and its props. An `add` to
18772
+ * `<entityUid>/components` sits at `<entityUid>/components/<addedUid>`. Omitted, every override
18773
+ * is selected.
18774
+ */
18775
+ readonly paths?: readonly string[];
18776
+ }
18777
+ /**
18778
+ * An override {@link applyOverridesToAsset} left on the instance, and why.
18779
+ *
18780
+ * @public
18781
+ */
18782
+ interface PrefabOverrideSkip {
18783
+ /** The override, as the instance entry holds it. */
18784
+ readonly override: SceneFileOverride;
18785
+ /** Why it could not be written into the prefab file. */
18786
+ readonly reason: string;
18787
+ }
18788
+ /**
18789
+ * What {@link applyOverridesToAsset} returns.
18790
+ *
18791
+ * @public
18792
+ */
18793
+ interface PrefabApplyResult {
18794
+ /** The new prefab file, with the applied overrides written into it. */
18795
+ readonly asset: SceneFile;
18796
+ /** The content hash of {@link PrefabApplyResult.asset}, as {@link computeSceneHash} writes it. */
18797
+ readonly hash: string;
18798
+ /**
18799
+ * The instance entry without the applied overrides, recording {@link PrefabApplyResult.hash}. It
18800
+ * expands to the same values it did before the apply; a component an applied `add` brought now
18801
+ * comes from the prefab, so like every prefab component it gets a fresh uid per instance.
18802
+ */
18803
+ readonly instance: SceneFileInstance;
18804
+ /** The overrides written into the prefab, in instance order. */
18805
+ readonly applied: readonly SceneFileOverride[];
18806
+ /** The selected overrides that stay on the instance, in instance order. */
18807
+ readonly skipped: readonly PrefabOverrideSkip[];
18808
+ }
18809
+ /**
18810
+ * Writes an instance's overrides into the prefab file it instances, so every instance of the prefab
18811
+ * gets them — Unity's "Apply to prefab" (ADR-0005).
18812
+ *
18813
+ * @remarks
18814
+ * A pure function over the two files: nothing is loaded, and the same input always gives
18815
+ * byte-identical output through {@link stringifySceneFile}. The rules:
18816
+ *
18817
+ * - Property, `enabled`, transform, and entity-field overrides change the prefab's record. An `add`
18818
+ * appends the component, keeping its uid; a `remove` deletes the component.
18819
+ * - On a prefab with exactly one root, the instance root's own `name`, `transform`, and other entity
18820
+ * fields are its placement, not prefab content, so overrides of the root's entity fields and
18821
+ * transform are skipped.
18822
+ * - Overrides reach only the prefab's own entities. Content of a scene the prefab itself instances
18823
+ * is not addressable by an override path, so a nested prefab is never edited: an override that
18824
+ * names something the prefab file does not hold is skipped.
18825
+ * - An override is skipped when an earlier override that stays on the instance overlaps its path, so
18826
+ * the instance keeps the value it had.
18827
+ * - A skipped override stays on the returned instance. The instance's own `components` are not
18828
+ * overrides and are not touched.
18829
+ * - Other instances of the prefab keep their overrides, which still win over the new prefab values
18830
+ * at the same path. Record {@link PrefabApplyResult.hash} on them, or loading them logs `IGX-0604`.
18831
+ * - References inside added components (`$entity`, `$component`) are copied unchanged.
18832
+ *
18833
+ * @param instance - The instance entry whose overrides to apply; its `scene` should name `asset`.
18834
+ * @param asset - The prefab file the entry instances.
18835
+ * @param selection - Which overrides to apply; all of them by default.
18836
+ * @returns The new prefab file and its hash, the instance entry without the applied overrides, and
18837
+ * what was applied or skipped.
18838
+ * @throws IgnifxError with code `IGX-0609` when a selected override path is outside the grammar.
18839
+ *
18840
+ * @example
18841
+ * ```ts
18842
+ * const result = await applyOverridesToAsset(spawn.instance, prefabFile);
18843
+ * await app.storage.write("prefabs/enemy.prefab.json", stringifySceneFile(result.asset));
18844
+ * ```
18845
+ *
18846
+ * @public
18847
+ */
18848
+ export declare function applyOverridesToAsset(instance: SceneFileInstance, asset: SceneFile, selection?: PrefabOverrideSelection): Promise<PrefabApplyResult>;
18849
+ /**
18850
+ * Drops an instance's overrides so it follows its prefab again — Unity's "Revert".
18851
+ *
18852
+ * @remarks
18853
+ * A pure function: the entry's `scene` and `hash` are kept, and `overrides` is omitted when none
18854
+ * remain. Reverting an `add` also reverts the overrides below the added component when the
18855
+ * selection path covers them (`<entityUid>/components/<addedUid>` does).
18856
+ *
18857
+ * @param instance - The instance entry.
18858
+ * @param selection - Which overrides to drop; all of them by default.
18859
+ * @returns The entry without the selected overrides, or `instance` itself when none was selected.
18860
+ *
18861
+ * @example
18862
+ * ```ts
18863
+ * const reverted = revertOverrides(spawn.instance, { paths: [`${rootUid}/components/${aiUid}`] });
18864
+ * ```
18865
+ *
18866
+ * @public
18867
+ */
18868
+ export declare function revertOverrides(instance: SceneFileInstance, selection?: PrefabOverrideSelection): SceneFileInstance;
18869
+ //#endregion
18536
18870
  //#region src/serialization/scene-loader.d.ts
18537
18871
  /**
18538
18872
  * Options accepted by {@link createSceneLoader}.
@@ -18775,9 +19109,14 @@ export declare function validateSceneFile(value: unknown): readonly SceneFileIss
18775
19109
  * and marked `builtIn`, because every entity carries exactly one and a scene file stores it as the
18776
19110
  * entity's `transform` block rather than in its `components`.
18777
19111
  *
19112
+ * A component's `title` and `description` come from `curated` when it has an entry, else from the
19113
+ * class's own `static title` and `static description`, which is how an extension's components
19114
+ * reach an inspector with their curated names without the inspector importing the extension.
19115
+ *
18778
19116
  * @param registry - The registry to walk, usually `app.world.registry`.
18779
19117
  * @param curated - Titles, formats and summaries by type id, for example a package's own
18780
- * `describeSchemas()`; a component without an entry is titled from its type id.
19118
+ * `describeSchemas()`; an entry wins over the class's own `static title` and `static description`, and a component
19119
+ * with neither is titled from its type id.
18781
19120
  * @returns The descriptions, keyed by type id, in registration order.
18782
19121
  *
18783
19122
  * @example
@@ -19633,5 +19972,5 @@ export declare function transformSchema(): Schema;
19633
19972
  */
19634
19973
  export declare const TWEEN_SYSTEM_ORDER = -100;
19635
19974
  //#endregion
19636
- export type { AddComponentFromRecordOptions, App, AppEvents, AppLiteHandles, AppSettings, ArrayFieldSpec, AssetFieldSpec, AssetHandle, AssetLoadErrorOptions, AssetLoader, AssetManifest, AssetManifestEntry, AssetProgress, AssetRef, AssetRefValue, AssetState, AssetTypeDefinition, AssetTypeToken, Assets, AssetsCreateOptions, AssetsSettings, BatchHandle, BloomEffectSettings, BoolFieldSpec, BoxMeshOptions, CameraProjection, CanvasAlphaMode, CapsuleMeshOptions, Clock, ColorFieldSpec, ColorLike, ComponentBuildResult, ComponentClassInfo, ComponentDefinition, ComponentHandle, ComponentHooks, ComponentInit, ComponentInitValue, ComponentRefFieldSpec, ComponentReplacement, ComponentStatics, ComponentType, ComponentTypeToken, ConcreteComponentType, ConnectOptions, ConsoleLike, ConsoleSinkOptions, Coroutine, CoroutineHandle, CoroutineHost, CoroutineYield, CreateAppOptions, CreateEntityOptions, CreateSceneOptions, CurveFieldSpec, CurveKey, CurveValue, CustomEffectInit, CustomEffectSettings, CustomFieldCodec, CustomFieldSpec, CylinderMeshOptions, DecodeResult, DeferredQueue, DeviceLostInfo, DiagnosticsGroup, DiagnosticsOptions, Disconnect, EasingFunction, EasingName, EntityHandle, EntityOverrideField, EntityPrefabLink, EntityRefFieldSpec, EnumFieldSpec, EnvironmentAssetLiteHandles, EnvironmentDefinition, EnvironmentFogMode, EnvironmentFogSettings, EnvironmentSkyboxSettings, ErrorCode, ErrorCodeDescription, ErrorCodeRegistry, ErrorContext, ErrorFormatMode, ErrorReport, Extension, ExtensionContext, FetchLike, FieldDefinition, FieldOptions, FieldSpec, FieldsOf, FileStorageOptions, FontAssetLiteHandles, FrameSample, FrameState, GpuAdapterInfo, GroundMeshOptions, HotReloadHost, HotReloadKind, HotReloadModule, HotReloadOptions, HotReloadPolicy, HotReloadReport, HotReloadStatics, IgnifxErrorOptions, IgnifxUniformName, ImageProcessingEffectSettings, ImageProcessingSettings, InstanceRange, InstancedMeshLod, InstancedMeshRendererLiteHandles, InstantiateOptions, InstantiateSceneOptions, JsonArray, JsonObject, JsonSchemaObject, JsonValue, LayerMaskFieldSpec, LayersSettings, LightShadowSettings, LightType, LiteAnimationGroup, LiteAssetContainer, LiteCamera, LiteEngine, LiteEnvironmentTextures, LiteFont, AdapterLight as LiteLight, LiteMaterial, LiteMaterialPluginPoint, LiteMesh, LitePbrMaterial, LiteScene, LiteSceneNode, LiteShaderMaterial, LiteShadowGenerator, LiteSkeleton, LiteStandardMaterial, LiteStorageBuffer, LiteSystemUniformName, LiteTexture2D, LoadOptions, LoadProgress, LoadSceneDependenciesOptions, LoadSceneFileOptions, LoadSceneOptions, LoaderContext, LogRecord, LogSink, LogThreshold, Logger, LoggerOptions, ManualClock, MapFieldSpec, Mat4Elements, Mat4Like, MaterialAlphaMode, MaterialAssetLiteHandles, MaterialDefinition, MaterialKind, MaterialPluginDefinition, MaterialPluginDefinitionInit, MemorySink, MeshAssetLiteHandles, MeshGeometryData, MeshOptionKind, MeshPrimitive, MeshPrimitiveDefinition, MeshPrimitiveOptionKinds, ModelAssetLiteHandles, ModelInstantiation, MutableQuat, MutableVec2, MutableVec3, MutableVec4, NumberFieldSpec, OptionalFieldSpec, OverridePath, PartialFieldsOf, PbrMaterialDefinition, PhaseIndex, PixelTextureOptions, PlaneMeshOptions, PlatformInfo, PlatformKind, PlatformOs, ProfileScope, QuatLike, RandomSource, Ray, RayVector, RecordFieldSpec, ReferenceDecoder, ReferenceEncoder, RegisterAssetOptions, RegisterComponentOptions, RegisterSystemOptions, RenderCapture, RenderOverlay, RenderOverlayLiteHandles, RenderPick, RenderPickIgnore, RenderPickOptions, RenderSurface, RenderTaskTiming, RenderTaskTimings, Renderer, RenderingFeature, RenderingFeatureSettings, RenderingSettings, SceneAsset, SceneBuildResult, SceneFile, SceneFileAssetRef, SceneFileComponent, SceneFileEntity, SceneFileInstance, SceneFileIssue, SceneFileOverride, SceneFileTransform, SceneLoadIssue, SceneLoaderOptions, Schema, SchemaDescription, SchemaDescriptionMeta, SchemaFieldDescription, SchemaIssue, ScriptCallbacks, ScriptClassInfo, ScriptDefinition, ScriptStatics, SerializeIssue, SerializeSceneOptions, ServiceClassKey, ServiceKey, ServiceNameKey, ServiceRegistry, SetParentOptions, SettingsInput, ShaderAttributeName, ShaderBlendMode, ShaderCullMode, ShaderDeclaration, ShaderDefineDeclaration, ShaderInstancingMode, ShaderKind, ShaderMaterialDefinition, ShaderMaterialDefinitionInput, ShaderPipelineState, ShaderStorageDeclaration, ShaderTextureDeclaration, ShaderTextureFallback, ShaderUniformDeclaration, ShaderUniformType, ShadowTechniqueName, SignalHandler, SignalLike, SignalOptions, SignalOwner, SmaaEffectSettings, SortingLayersSettings, SphereMeshOptions, StandardMaterialDefinition, Storage, StorageBackend, StorageBufferAssetLiteHandles, StoredValue, StoredValueKind, StringFieldSpec, SurfaceHookName, SurfaceHostCapabilities, SurfaceHostFamily, SurfaceShaderBinding, SurfaceShaderInit, SurfaceShaderReference, System, SystemContext, SystemEditMode, TextureAssetLiteHandles, TextureImportOptions, Time, TimeSettings, ToneMappingCurve, TorusMeshOptions, TweenOptions, TweenProps, TweenTargetValue, TweenValueKind, TweenableValue, Tweens, UlidFactoryOptions, Vec2Like, Vec3Like, Vec4Like, VectorFieldSpec, WaitInstruction, WebGpuInfo, WorldLiteHandles };
19975
+ export type { AddComponentFromRecordOptions, App, AppEvents, AppLiteHandles, AppSettings, ArrayFieldSpec, AssetFieldSpec, AssetHandle, AssetLoadErrorOptions, AssetLoader, AssetManifest, AssetManifestEntry, AssetProgress, AssetRef, AssetRefValue, AssetState, AssetTypeDefinition, AssetTypeToken, Assets, AssetsCreateOptions, AssetsSettings, BatchHandle, BloomEffectSettings, BoolFieldSpec, BoxMeshOptions, CameraProjection, CanvasAlphaMode, CapsuleMeshOptions, Clock, ColorFieldSpec, ColorLike, ComponentBuildResult, ComponentClassInfo, ComponentDefinition, ComponentHandle, ComponentHooks, ComponentInit, ComponentInitValue, ComponentRefFieldSpec, ComponentReplacement, ComponentStatics, ComponentType, ComponentTypeToken, ConcreteComponentType, ConnectOptions, ConsoleLike, ConsoleSinkOptions, Coroutine, CoroutineHandle, CoroutineHost, CoroutineYield, CreateAppOptions, CreateEntityOptions, CreateSceneOptions, CurveFieldSpec, CurveKey, CurveValue, CustomEffectInit, CustomEffectSettings, CustomFieldCodec, CustomFieldSpec, CylinderMeshOptions, DecodeResult, DeferredQueue, DeviceLostInfo, DiagnosticsGroup, DiagnosticsOptions, Disconnect, EasingFunction, EasingName, EntityHandle, EntityOverrideField, EntityPrefabLink, EntityRefFieldSpec, EnumFieldSpec, EnvironmentAssetLiteHandles, EnvironmentDefinition, EnvironmentFogMode, EnvironmentFogSettings, EnvironmentSkyboxSettings, ErrorCode, ErrorCodeDescription, ErrorCodeRegistry, ErrorContext, ErrorFormatMode, ErrorReport, Extension, ExtensionContext, FetchLike, FieldDefinition, FieldOptions, FieldSpec, FieldsOf, FileStorageOptions, FontAssetLiteHandles, FrameSample, FrameState, GpuAdapterInfo, GroundMeshOptions, HotReloadHost, HotReloadKind, HotReloadModule, HotReloadOptions, HotReloadPolicy, HotReloadReport, HotReloadStatics, IgnifxErrorOptions, IgnifxUniformName, ImageProcessingEffectSettings, ImageProcessingSettings, InstanceRange, InstancedMeshLod, InstancedMeshRendererLiteHandles, InstantiateOptions, InstantiateSceneOptions, JsonArray, JsonObject, JsonSchemaObject, JsonValue, LayerMaskFieldSpec, LayersSettings, LightShadowSettings, LightType, LiteAnimationGroup, LiteAssetContainer, LiteCamera, LiteEngine, LiteEnvironmentTextures, LiteFont, AdapterLight as LiteLight, LiteMaterial, LiteMaterialPluginPoint, LiteMesh, LitePbrMaterial, LiteScene, LiteSceneNode, LiteShaderMaterial, LiteShadowGenerator, LiteSkeleton, LiteStandardMaterial, LiteStorageBuffer, LiteSystemUniformName, LiteTexture2D, LoadOptions, LoadProgress, LoadSceneDependenciesOptions, LoadSceneFileOptions, LoadSceneOptions, LoaderContext, LogRecord, LogSink, LogThreshold, Logger, LoggerOptions, ManualClock, MapFieldSpec, Mat4Elements, Mat4Like, MaterialAlphaMode, MaterialAssetLiteHandles, MaterialDefinition, MaterialKind, MaterialPluginDefinition, MaterialPluginDefinitionInit, MemorySink, MeshAssetLiteHandles, MeshGeometryData, MeshOptionKind, MeshPrimitive, MeshPrimitiveDefinition, MeshPrimitiveOptionKinds, ModelAssetLiteHandles, ModelInstantiation, MutableQuat, MutableVec2, MutableVec3, MutableVec4, NumberFieldSpec, OptionalFieldSpec, OverridePath, PartialFieldsOf, PbrMaterialDefinition, PhaseIndex, PixelTextureOptions, PlaneMeshOptions, PlatformInfo, PlatformKind, PlatformOs, PrefabApplyResult, PrefabOverrideSelection, PrefabOverrideSkip, ProfileScope, QuatLike, RandomSource, Ray, RayVector, RecordFieldSpec, ReferenceDecoder, ReferenceEncoder, RegisterAssetOptions, RegisterComponentOptions, RegisterSystemOptions, RenderCapture, RenderOverlay, RenderOverlayLiteHandles, RenderPick, RenderPickIgnore, RenderPickOptions, RenderSurface, RenderTaskTiming, RenderTaskTimings, RenderTexture, Renderer, RenderingFeature, RenderingFeatureSettings, RenderingSettings, SceneAsset, SceneBuildResult, SceneFile, SceneFileAssetRef, SceneFileComponent, SceneFileEntity, SceneFileInstance, SceneFileIssue, SceneFileOverride, SceneFileTransform, SceneLoadIssue, SceneLoaderOptions, Schema, SchemaDescription, SchemaDescriptionMeta, SchemaFieldDescription, SchemaIssue, ScriptCallbacks, ScriptClassInfo, ScriptDefinition, ScriptStatics, SerializeIssue, SerializeSceneOptions, ServiceClassKey, ServiceKey, ServiceNameKey, ServiceRegistry, SetParentOptions, SettingsInput, ShaderAttributeName, ShaderBlendMode, ShaderCullMode, ShaderDeclaration, ShaderDefineDeclaration, ShaderInstancingMode, ShaderKind, ShaderMaterialDefinition, ShaderMaterialDefinitionInput, ShaderPipelineState, ShaderStorageDeclaration, ShaderTextureDeclaration, ShaderTextureFallback, ShaderUniformDeclaration, ShaderUniformType, ShadowTechniqueName, SignalHandler, SignalLike, SignalOptions, SignalOwner, SmaaEffectSettings, SortingLayersSettings, SphereMeshOptions, StandardMaterialDefinition, Storage, StorageBackend, StorageBufferAssetLiteHandles, StoredValue, StoredValueKind, StringFieldSpec, SurfaceHookName, SurfaceHostCapabilities, SurfaceHostFamily, SurfaceShaderBinding, SurfaceShaderInit, SurfaceShaderReference, System, SystemContext, SystemEditMode, TextureAssetLiteHandles, TextureImportOptions, Time, TimeSettings, ToneMappingCurve, TorusMeshOptions, TweenOptions, TweenProps, TweenTargetValue, TweenValueKind, TweenableValue, Tweens, UlidFactoryOptions, Vec2Like, Vec3Like, Vec4Like, VectorFieldSpec, WaitInstruction, WebGpuInfo, WorldLiteHandles };
19637
19976
  //# sourceMappingURL=index.d.ts.map