@ignifx/core 0.0.0 → 0.2.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/LICENSE +201 -0
- package/dist/error-decoding-T3P1YuiL.js +40 -0
- package/dist/error-decoding-T3P1YuiL.js.map +1 -0
- package/dist/gltf-source-Co5Khb60.js +32 -0
- package/dist/gltf-source-Co5Khb60.js.map +1 -0
- package/dist/index.d.ts +1743 -174
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +6133 -2472
- package/dist/index.js.map +1 -1
- package/package.json +24 -19
package/dist/index.d.ts
CHANGED
|
@@ -91,9 +91,14 @@ type ErrorCode = `IGX-${number}`;
|
|
|
91
91
|
*
|
|
92
92
|
* @remarks
|
|
93
93
|
* Code blocks reserved for other first-party packages, which cannot import this table
|
|
94
|
-
* (`docs/architecture/00-overview.md` §2): `@ignifx/cli` owns `IGX-1401`–`IGX-1419`;
|
|
94
|
+
* (`docs/architecture/00-overview.md` §2): `@ignifx/cli` owns `IGX-1401`–`IGX-1419`; `@ignifx/electron`
|
|
95
|
+
* owns `IGX-1460`–`IGX-1499` (core's own platform codes therefore stop at `IGX-1459`); `@ignifx/devtools`
|
|
96
|
+
* owns `IGX-1550`–`IGX-1599` (core's own devtools-range codes stop at `IGX-1549`);
|
|
95
97
|
* `@ignifx/vite-plugin` owns `IGX-0550`–`IGX-0599` and `IGX-0650`–`IGX-0699`. Core allocates its
|
|
96
|
-
* own codes from the bottom of each range and, in the platform range, from `IGX-1420` upward
|
|
98
|
+
* own codes from the bottom of each range and, in the platform range, from `IGX-1420` upward —
|
|
99
|
+
* which is where `app.platform` and `app.storage` live, because storage is a *platform* service:
|
|
100
|
+
* the same three calls resolve to IndexedDB, a directory, or the Electron bridge depending only on
|
|
101
|
+
* the host, so a failure is a platform failure and not a serialization or asset one.
|
|
97
102
|
*
|
|
98
103
|
* @public
|
|
99
104
|
*/
|
|
@@ -114,6 +119,10 @@ export declare const CoreErrorCode: {
|
|
|
114
119
|
readonly appNotReady: "IGX-0107";
|
|
115
120
|
/** A `Time` property was set to a value outside its documented domain. */
|
|
116
121
|
readonly invalidTimeValue: "IGX-0108";
|
|
122
|
+
/** A `app.tweens.to(...)` option was outside its documented domain. */
|
|
123
|
+
readonly invalidTweenOptions: "IGX-0109";
|
|
124
|
+
/** A tweened field is not a number, `Vec2`, `Vec3`, or `Quat`, or is not writable. */
|
|
125
|
+
readonly tweenFieldNotTweenable: "IGX-0110";
|
|
117
126
|
/** A component declared through `requires` is missing from the entity. */
|
|
118
127
|
readonly requiredComponentMissing: "IGX-0201";
|
|
119
128
|
/** A second instance of a component type that does not allow multiples was added. */
|
|
@@ -126,6 +135,10 @@ export declare const CoreErrorCode: {
|
|
|
126
135
|
readonly transformIsNotRemovable: "IGX-0205";
|
|
127
136
|
/** A component's engine-assigned state was read before the engine attached it to an entity. */
|
|
128
137
|
readonly componentNotAttached: "IGX-0206";
|
|
138
|
+
/** A hot-reloaded class kept the `"patch"` policy while its schema shape changed. */
|
|
139
|
+
readonly hotReloadSchemaChanged: "IGX-0207";
|
|
140
|
+
/** `app.hotReload.apply()` was called from inside a lifecycle callback. */
|
|
141
|
+
readonly hotReloadInsideCallback: "IGX-0208";
|
|
129
142
|
/** A scene was instantiated before it had finished loading. */
|
|
130
143
|
readonly sceneNotLoaded: "IGX-0301";
|
|
131
144
|
/** Instantiating a scene would place an instance inside itself. */
|
|
@@ -214,8 +227,22 @@ export declare const CoreErrorCode: {
|
|
|
214
227
|
readonly invalidAssetFile: "IGX-0709";
|
|
215
228
|
/** A `PostProcessStack` was attached without the `postProcessing` rendering feature. */
|
|
216
229
|
readonly postProcessingFeatureOff: "IGX-0710";
|
|
230
|
+
/** An `Environment.skybox` asks for a background the environment it installed cannot draw. */
|
|
231
|
+
readonly skyboxFixedAtLoad: "IGX-0711";
|
|
217
232
|
/** The host exposes no Web Crypto implementation. */
|
|
218
233
|
readonly cryptoUnavailable: "IGX-1420";
|
|
234
|
+
/** A storage namespace name is not a legal namespace segment. */
|
|
235
|
+
readonly storageInvalidNamespace: "IGX-1421";
|
|
236
|
+
/** A storage key is empty, too long, or contains a control character. */
|
|
237
|
+
readonly storageInvalidKey: "IGX-1422";
|
|
238
|
+
/** A value handed to `app.storage.set` has no JSON form. */
|
|
239
|
+
readonly storageValueNotSerializable: "IGX-1423";
|
|
240
|
+
/** The storage backend refused a write because the host is out of quota or disk space. */
|
|
241
|
+
readonly storageQuotaExceeded: "IGX-1424";
|
|
242
|
+
/** The storage backend failed for a reason the engine cannot classify. */
|
|
243
|
+
readonly storageBackendFailed: "IGX-1425";
|
|
244
|
+
/** A stored value could not be read back; the store was damaged or written by something else. */
|
|
245
|
+
readonly storageValueCorrupt: "IGX-1426";
|
|
219
246
|
/** An error code was registered twice. */
|
|
220
247
|
readonly duplicateErrorCode: "IGX-1501";
|
|
221
248
|
/** An error code does not match `IGX-####` in a known range. */
|
|
@@ -226,6 +253,8 @@ export declare const CoreErrorCode: {
|
|
|
226
253
|
readonly unknownDiagnosticsCounter: "IGX-1504";
|
|
227
254
|
/** A `switch` over a union reached a case the type system said was impossible. */
|
|
228
255
|
readonly unreachableCase: "IGX-1505";
|
|
256
|
+
/** `app.hotReload.reloadScene()` was given an instance that was not built from a scene asset. */
|
|
257
|
+
readonly sceneNotReloadable: "IGX-1506";
|
|
229
258
|
};
|
|
230
259
|
/**
|
|
231
260
|
* The union of the codes `@ignifx/core` owns. Use it to narrow `catch` blocks to core failures.
|
|
@@ -1035,7 +1064,9 @@ interface RegisterAssetOptions {
|
|
|
1035
1064
|
/**
|
|
1036
1065
|
* The `fetch` implementation the service performs every read through
|
|
1037
1066
|
* (`docs/architecture/05-assets-and-loading.md` §8). Injecting it is how headless tests supply
|
|
1038
|
-
* deterministic responses and how a Node app maps addresses onto `fs
|
|
1067
|
+
* deterministic responses and how a Node app maps addresses onto `fs`. A packaged Electron build
|
|
1068
|
+
* needs no injection: `@ignifx/electron` serves `dist/` over `ignifx://`, which the renderer's own
|
|
1069
|
+
* `fetch` reaches.
|
|
1039
1070
|
*
|
|
1040
1071
|
* @public
|
|
1041
1072
|
*/
|
|
@@ -1083,6 +1114,14 @@ interface Assets {
|
|
|
1083
1114
|
* @returns The handle, once it has loaded.
|
|
1084
1115
|
*/
|
|
1085
1116
|
loadAsync<T>(ref: AssetRef<T> | string, options?: LoadOptions): Promise<AssetHandle<T>>;
|
|
1117
|
+
/**
|
|
1118
|
+
* Reloads a loaded asset from its source, delivering the new value through `onReplaced` the way a
|
|
1119
|
+
* development hot reload does (`docs/architecture/05-assets-and-loading.md` §7); a handle that is
|
|
1120
|
+
* not loaded is left alone. The Vite plugin's HMR channel and the devtools Assets panel call it.
|
|
1121
|
+
*
|
|
1122
|
+
* @param address - The asset's address.
|
|
1123
|
+
*/
|
|
1124
|
+
reload(address: string): void;
|
|
1086
1125
|
/**
|
|
1087
1126
|
* Requests several assets as one batch.
|
|
1088
1127
|
*
|
|
@@ -1189,7 +1228,7 @@ interface AssetLoadErrorOptions extends IgnifxErrorOptions {
|
|
|
1189
1228
|
* await app.assets.loadAsync("levels/1.scene.json");
|
|
1190
1229
|
* } catch (error) {
|
|
1191
1230
|
* if (error instanceof AssetLoadError) {
|
|
1192
|
-
* app.log.error(
|
|
1231
|
+
* app.log.error(`${error.address} failed from ${error.url}`, error);
|
|
1193
1232
|
* }
|
|
1194
1233
|
* }
|
|
1195
1234
|
* ```
|
|
@@ -1452,8 +1491,12 @@ interface ComponentTypeToken<C> {
|
|
|
1452
1491
|
interface AssetTypeToken<A> {
|
|
1453
1492
|
/** The asset type name written into files when the extension is ambiguous. */
|
|
1454
1493
|
readonly assetType?: string;
|
|
1455
|
-
/**
|
|
1456
|
-
|
|
1494
|
+
/**
|
|
1495
|
+
* The instance shape the token names. A class token carries it for free; a plain token for an
|
|
1496
|
+
* asset that has no class (a scene, a prefab) leaves it out and fixes `A` through its annotation —
|
|
1497
|
+
* see `SceneAssetToken`. Nothing reads it at runtime.
|
|
1498
|
+
*/
|
|
1499
|
+
readonly prototype?: A;
|
|
1457
1500
|
}
|
|
1458
1501
|
/**
|
|
1459
1502
|
* The plain, serializable form of an asset reference: what `{ "$asset": … }` decodes to before the
|
|
@@ -1822,6 +1865,18 @@ interface ComponentClassInfo {
|
|
|
1822
1865
|
/** A dense index assigned in registration order, for array-indexed per-class bookkeeping. */
|
|
1823
1866
|
readonly classIndex: number;
|
|
1824
1867
|
}
|
|
1868
|
+
/**
|
|
1869
|
+
* What {@link ComponentRegistry.replace} swapped, for the hot-reload path that has to re-file every
|
|
1870
|
+
* live instance of the class that went away.
|
|
1871
|
+
*
|
|
1872
|
+
* @public
|
|
1873
|
+
*/
|
|
1874
|
+
interface ComponentReplacement {
|
|
1875
|
+
/** The class registered under the id before, or `null` when nothing was. */
|
|
1876
|
+
readonly previous: ComponentType | null;
|
|
1877
|
+
/** The replacement's freshly built info. */
|
|
1878
|
+
readonly info: ComponentClassInfo;
|
|
1879
|
+
}
|
|
1825
1880
|
/**
|
|
1826
1881
|
* The component-class table of one app. There is one per {@link App}, never a module-level one
|
|
1827
1882
|
* (`CONSTITUTION.md` §3.5, §3.6): two apps in one test process must not see each other's types.
|
|
@@ -1859,6 +1914,26 @@ export declare class ComponentRegistry {
|
|
|
1859
1914
|
* @param types - The component classes.
|
|
1860
1915
|
*/
|
|
1861
1916
|
registerAll(types: readonly ConcreteComponentType[]): void;
|
|
1917
|
+
/**
|
|
1918
|
+
* Swaps the class registered under a `typeId` for a replacement, for script hot reload
|
|
1919
|
+
* (`docs/architecture/15-devtools-and-diagnostics.md` §5). The previous class's cached info is
|
|
1920
|
+
* dropped and the replacement inherits its `classIndex`, so per-class bookkeeping indexed by that
|
|
1921
|
+
* number stays valid across a reload.
|
|
1922
|
+
*
|
|
1923
|
+
* @remarks
|
|
1924
|
+
* Additive and hot-reload-only: nothing on the normal path replaces a registration, and
|
|
1925
|
+
* `register` still refuses to bind one id to two classes (`IGX-0203`).
|
|
1926
|
+
*
|
|
1927
|
+
* @param type - The replacement class. It must declare the `typeId` it replaces.
|
|
1928
|
+
* @returns The freshly built info for the replacement, and the class it replaced.
|
|
1929
|
+
* @throws IgnifxError with code `IGX-0204` when the replacement declares no `typeId`.
|
|
1930
|
+
*
|
|
1931
|
+
* @example
|
|
1932
|
+
* ```ts
|
|
1933
|
+
* const { previous } = registry.replace(NextMover);
|
|
1934
|
+
* ```
|
|
1935
|
+
*/
|
|
1936
|
+
replace(type: ConcreteComponentType): ComponentReplacement;
|
|
1862
1937
|
/**
|
|
1863
1938
|
* Describes a class, computing and caching its info on first sight. Explicit registration is only
|
|
1864
1939
|
* needed for *serializable* components; a script added from code is described the first time it
|
|
@@ -2423,24 +2498,24 @@ export declare class Quat {
|
|
|
2423
2498
|
/**
|
|
2424
2499
|
* Builds a rotation from Euler angles in radians, in intrinsic XYZ order.
|
|
2425
2500
|
*
|
|
2426
|
-
* @param
|
|
2427
|
-
* @param
|
|
2428
|
-
* @param
|
|
2501
|
+
* @param xRad - Rotation about X, in radians.
|
|
2502
|
+
* @param yRad - Rotation about Y, in radians.
|
|
2503
|
+
* @param zRad - Rotation about Z, in radians.
|
|
2429
2504
|
* @returns A new quaternion. **Allocates.**
|
|
2430
2505
|
*/
|
|
2431
|
-
static
|
|
2506
|
+
static fromEulerRad(xRad: number, yRad: number, zRad: number): Quat;
|
|
2432
2507
|
/**
|
|
2433
2508
|
* Writes a rotation built from Euler radians into `out`. This is Babylon Lite's `eulerToQuat`
|
|
2434
2509
|
* (`lib/math/quat-euler.js`) element for element, so a rotation built here means the same thing
|
|
2435
2510
|
* to Lite's node hierarchy.
|
|
2436
2511
|
*
|
|
2437
|
-
* @param
|
|
2438
|
-
* @param
|
|
2439
|
-
* @param
|
|
2512
|
+
* @param xRad - Rotation about X, in radians.
|
|
2513
|
+
* @param yRad - Rotation about Y, in radians.
|
|
2514
|
+
* @param zRad - Rotation about Z, in radians.
|
|
2440
2515
|
* @param out - The quaternion to write.
|
|
2441
2516
|
* @returns `out`.
|
|
2442
2517
|
*/
|
|
2443
|
-
static
|
|
2518
|
+
static fromEulerRadToRef<TOut extends MutableQuat>(xRad: number, yRad: number, zRad: number, out: TOut): TOut;
|
|
2444
2519
|
/**
|
|
2445
2520
|
* Writes a rotation's Euler angles in degrees into `out`, in intrinsic XYZ order — the inverse of
|
|
2446
2521
|
* {@link Quat.fromEulerDegreesToRef}.
|
|
@@ -2460,7 +2535,7 @@ export declare class Quat {
|
|
|
2460
2535
|
* @param out - The vector to write, in radians.
|
|
2461
2536
|
* @returns `out`.
|
|
2462
2537
|
*/
|
|
2463
|
-
static
|
|
2538
|
+
static toEulerRadToRef<TOut extends MutableVec3>(q: QuatLike, out: TOut): TOut;
|
|
2464
2539
|
/**
|
|
2465
2540
|
* Builds a rotation of `degrees` about an axis.
|
|
2466
2541
|
*
|
|
@@ -4187,6 +4262,27 @@ interface SceneAsset {
|
|
|
4187
4262
|
/** The content hash of {@link SceneAsset.file}, as `sha256:<hex>`. */
|
|
4188
4263
|
readonly hash: string;
|
|
4189
4264
|
}
|
|
4265
|
+
/**
|
|
4266
|
+
* The `asset()` token for a scene or prefab field. `SceneAsset` is an interface, so it cannot be
|
|
4267
|
+
* passed to `asset()` the way a class such as `MeshAsset` can; this token names the type instead:
|
|
4268
|
+
*
|
|
4269
|
+
* ```ts
|
|
4270
|
+
* class Spawner extends Script.define({ prefab: asset(SceneAssetToken) }) {
|
|
4271
|
+
* static typeId = "game/Spawner";
|
|
4272
|
+
* spawn(): void {
|
|
4273
|
+
* const value = this.prefab?.value;
|
|
4274
|
+
* if (value !== undefined) {
|
|
4275
|
+
* this.app.world.instantiate(value, { position: this.transform.position });
|
|
4276
|
+
* }
|
|
4277
|
+
* }
|
|
4278
|
+
* }
|
|
4279
|
+
* ```
|
|
4280
|
+
*
|
|
4281
|
+
* In a scene file the field is written as `{ "$asset": "props/crate.prefab.json" }`.
|
|
4282
|
+
*
|
|
4283
|
+
* @public
|
|
4284
|
+
*/
|
|
4285
|
+
export declare const SceneAssetToken: AssetTypeToken<SceneAsset>;
|
|
4190
4286
|
/**
|
|
4191
4287
|
* The content hash of a scene file: SHA-256 over the canonical JSON text, so two saves of the same
|
|
4192
4288
|
* state hash the same and an edited prefab does not
|
|
@@ -4931,6 +5027,17 @@ interface WorldInternals {
|
|
|
4931
5027
|
* @returns `true` when at least one of the entity's scripts implements it.
|
|
4932
5028
|
*/
|
|
4933
5029
|
entityImplements(entity: Entity, kind: ScriptCallbackKind): boolean;
|
|
5030
|
+
/**
|
|
5031
|
+
* Re-files an effectively-enabled script in the sorted dispatch lists after script hot reload
|
|
5032
|
+
* swapped its class (`docs/architecture/15-devtools-and-diagnostics.md` §5). No callback runs: the
|
|
5033
|
+
* script leaves the lists its previous class was filed in and joins the ones its new class
|
|
5034
|
+
* implements, at its new `executionOrder`.
|
|
5035
|
+
*
|
|
5036
|
+
* @param component - The component whose class was replaced. A plain component is ignored.
|
|
5037
|
+
* @param previous - The class info the component was filed under.
|
|
5038
|
+
* @param next - The class info it is filed under now, already written to its engine state.
|
|
5039
|
+
*/
|
|
5040
|
+
rebindDispatch(component: Component, previous: ScriptClassInfo | null, next: ScriptClassInfo | null): void;
|
|
4934
5041
|
/**
|
|
4935
5042
|
* Tells the world which phase is running, so a failure reported through `app.onError` names it.
|
|
4936
5043
|
* The scheduler sets it on entering a phase and clears it on leaving.
|
|
@@ -5327,15 +5434,6 @@ export declare class LayerTable {
|
|
|
5327
5434
|
* @public
|
|
5328
5435
|
*/
|
|
5329
5436
|
export declare function createLayerTable(names?: readonly string[]): LayerTable;
|
|
5330
|
-
/**
|
|
5331
|
-
* Checks that a number is a usable layer slot.
|
|
5332
|
-
*
|
|
5333
|
-
* @param layer - The candidate slot.
|
|
5334
|
-
* @returns `true` when the value is an integer in `[0, 31]`.
|
|
5335
|
-
*
|
|
5336
|
-
* @internal
|
|
5337
|
-
*/
|
|
5338
|
-
export declare function isValidLayer(layer: number): boolean;
|
|
5339
5437
|
//#endregion
|
|
5340
5438
|
//#region src/lifecycle/frame-state.d.ts
|
|
5341
5439
|
/**
|
|
@@ -5585,15 +5683,16 @@ type LitePbrMaterial = PbrMaterialProps;
|
|
|
5585
5683
|
*/
|
|
5586
5684
|
type LiteStandardMaterial = StandardMaterialProps;
|
|
5587
5685
|
/**
|
|
5588
|
-
* How a material's alpha channel is interpreted, in glTF's vocabulary
|
|
5686
|
+
* How a material's alpha channel is interpreted, in glTF's vocabulary, in the order the inspector
|
|
5687
|
+
* lists them (`docs/architecture/07-rendering.md` §2.4).
|
|
5589
5688
|
*
|
|
5590
|
-
* @
|
|
5689
|
+
* @public
|
|
5591
5690
|
*/
|
|
5592
5691
|
export declare const MATERIAL_ALPHA_MODES: readonly ["opaque", "mask", "blend"];
|
|
5593
5692
|
/**
|
|
5594
5693
|
* The union of the alpha modes a material can declare.
|
|
5595
5694
|
*
|
|
5596
|
-
* @
|
|
5695
|
+
* @public
|
|
5597
5696
|
*/
|
|
5598
5697
|
type MaterialAlphaMode = (typeof MATERIAL_ALPHA_MODES)[number];
|
|
5599
5698
|
//#endregion
|
|
@@ -5612,14 +5711,15 @@ type MaterialAlphaMode = (typeof MATERIAL_ALPHA_MODES)[number];
|
|
|
5612
5711
|
* renderer". This module is that boundary: `baseColor`, `emissive`, `diffuse`, and `specular` are
|
|
5613
5712
|
* decoded here and handed to the adapter linear. Factors that are not colours — `metallic`,
|
|
5614
5713
|
* `roughness`, `alpha` — are unitless and pass through.
|
|
5615
|
-
* - **`"type": "shader"` is
|
|
5616
|
-
* its declaration takes a WGSL attribute/uniform/sampler layout whose shape is Lite's
|
|
5617
|
-
* (`ShaderMaterialOptions`, `index.d.ts`); publishing that verbatim would put a Lite type in
|
|
5618
|
-
* public API, which `CONSTITUTION.md` §3.4 forbids, and mirroring it is a design job of its
|
|
5619
|
-
* A file that declares it is rejected with `IGX-0708
|
|
5620
|
-
* - **PBR extensions (`clearcoat`, `sheen`, `transmission`, …) are
|
|
5621
|
-
* each is a sub-record with its own textures, and §2.6 wants them opt-in so unused shader
|
|
5622
|
-
* tree-shaken. The loader reports an unknown top-level key rather than silently dropping
|
|
5714
|
+
* - **`"type": "shader"` is not implemented.** §2.6 lists it, and Lite's `createShaderMaterial`
|
|
5715
|
+
* exists, but its declaration takes a WGSL attribute/uniform/sampler layout whose shape is Lite's
|
|
5716
|
+
* own (`ShaderMaterialOptions`, `index.d.ts`); publishing that verbatim would put a Lite type in
|
|
5717
|
+
* the public API, which `CONSTITUTION.md` §3.4 forbids, and mirroring it is a design job of its
|
|
5718
|
+
* own that no delivered phase took on. A file that declares it is rejected with `IGX-0708`.
|
|
5719
|
+
* - **PBR extensions (`clearcoat`, `sheen`, `transmission`, …) are not implemented** for the same
|
|
5720
|
+
* reason: each is a sub-record with its own textures, and §2.6 wants them opt-in so unused shader
|
|
5721
|
+
* code is tree-shaken. The loader reports an unknown top-level key rather than silently dropping
|
|
5722
|
+
* it.
|
|
5623
5723
|
*
|
|
5624
5724
|
* ## Headless
|
|
5625
5725
|
*
|
|
@@ -5664,18 +5764,6 @@ export declare const MATERIAL_KINDS: readonly ["pbr", "standard", "shader"];
|
|
|
5664
5764
|
* @public
|
|
5665
5765
|
*/
|
|
5666
5766
|
type MaterialKind = (typeof MATERIAL_KINDS)[number];
|
|
5667
|
-
/**
|
|
5668
|
-
* How a material interprets its alpha channel, in glTF's vocabulary.
|
|
5669
|
-
*
|
|
5670
|
-
* @public
|
|
5671
|
-
*/
|
|
5672
|
-
type MaterialAlphaModeName = MaterialAlphaMode;
|
|
5673
|
-
/**
|
|
5674
|
-
* The alpha modes a material may declare, in the order the inspector lists them.
|
|
5675
|
-
*
|
|
5676
|
-
* @public
|
|
5677
|
-
*/
|
|
5678
|
-
export declare const MATERIAL_ALPHA_MODE_NAMES: readonly MaterialAlphaModeName[];
|
|
5679
5767
|
/**
|
|
5680
5768
|
* The properties a `"pbr"` material declares. Every colour is sRGB; every factor is unitless.
|
|
5681
5769
|
*
|
|
@@ -5699,7 +5787,7 @@ interface PbrMaterialDefinition {
|
|
|
5699
5787
|
/** How strongly ambient occlusion darkens the surface, 0 to 1. */
|
|
5700
5788
|
readonly occlusionStrength: number;
|
|
5701
5789
|
/** How the alpha channel is interpreted. */
|
|
5702
|
-
readonly alphaMode:
|
|
5790
|
+
readonly alphaMode: MaterialAlphaMode;
|
|
5703
5791
|
/** The cutoff below which a `"mask"` material discards a fragment. */
|
|
5704
5792
|
readonly alphaCutoff: number;
|
|
5705
5793
|
/** Overall material alpha, 0 to 1. */
|
|
@@ -6364,15 +6452,18 @@ interface Renderer {
|
|
|
6364
6452
|
*/
|
|
6365
6453
|
warmUp(materials: readonly MaterialAsset[]): void;
|
|
6366
6454
|
/**
|
|
6367
|
-
* Picks the object under one
|
|
6455
|
+
* Picks the object under one pixel of the canvas, exactly, on the GPU
|
|
6368
6456
|
* (`docs/architecture/07-rendering.md` §3).
|
|
6369
6457
|
*
|
|
6370
6458
|
* @remarks
|
|
6371
|
-
*
|
|
6372
|
-
*
|
|
6373
|
-
*
|
|
6374
|
-
*
|
|
6375
|
-
*
|
|
6459
|
+
* Coordinates are **backing-store pixels** — the canvas's `width`/`height`, the space
|
|
6460
|
+
* `Camera.worldToScreen` answers in — not CSS pixels; multiply a DOM event's `offsetX`/`offsetY`
|
|
6461
|
+
* by `devicePixelRatio` first. Picks are serialised per app: Lite's picker owns one set of staging
|
|
6462
|
+
* buffers and chains each call onto the previous one's promise. A headless app has no picker and
|
|
6463
|
+
* always misses.
|
|
6464
|
+
*
|
|
6465
|
+
* @param x - The backing-store pixel x, from the canvas's left edge.
|
|
6466
|
+
* @param y - The backing-store pixel y, from the canvas's top edge.
|
|
6376
6467
|
* @param options - An entity filter.
|
|
6377
6468
|
* @returns What was hit, or `null` for a miss.
|
|
6378
6469
|
*/
|
|
@@ -6400,6 +6491,25 @@ interface Renderer {
|
|
|
6400
6491
|
* which point Lite has compiled what it is going to compile.
|
|
6401
6492
|
*/
|
|
6402
6493
|
requireFeature(feature: RenderingFeature): void;
|
|
6494
|
+
/**
|
|
6495
|
+
* Registers a probe that answers whether a rendering context **other than the render scene** is
|
|
6496
|
+
* drawing a world through a camera of its own.
|
|
6497
|
+
*
|
|
6498
|
+
* @remarks
|
|
6499
|
+
* The one caller is an extension that owns a second rendering context on the same surface —
|
|
6500
|
+
* `@ignifx/2d`'s sprite renderer, which draws a `"sprite"`-mode frame through a `Camera2D` and
|
|
6501
|
+
* needs no 3D `Camera` at all. `IGX-0706` says "this world has no enabled camera, so nothing is
|
|
6502
|
+
* drawn"; on such a world the second half is false, so the probe suppresses it
|
|
6503
|
+
* (`docs/architecture/07-rendering.md` §2.1, `11-2d-toolkit.md` §1). The probe is asked only in
|
|
6504
|
+
* the frames where no 3D camera was selected, and it is never cached: a scene that loses its
|
|
6505
|
+
* `Camera2D` starts warning again.
|
|
6506
|
+
*
|
|
6507
|
+
* @param probe - Answers `true` while the caller has an active camera for the world it is handed.
|
|
6508
|
+
* @returns A function that removes the probe.
|
|
6509
|
+
*
|
|
6510
|
+
* @internal
|
|
6511
|
+
*/
|
|
6512
|
+
addCameraSource(probe: (world: World) => boolean): Disconnect;
|
|
6403
6513
|
}
|
|
6404
6514
|
/**
|
|
6405
6515
|
* The rendering service of one app, and the render layer's per-app state.
|
|
@@ -6457,6 +6567,17 @@ declare class RendererImpl implements Renderer {
|
|
|
6457
6567
|
* @returns The surface, or `null` under the null engine.
|
|
6458
6568
|
*/
|
|
6459
6569
|
get surface(): RenderSurface | null;
|
|
6570
|
+
/**
|
|
6571
|
+
* Destroys the GPU device the way a real loss would, so that recovery runs — for tests and probes.
|
|
6572
|
+
*
|
|
6573
|
+
* @remarks
|
|
6574
|
+
* Reached through `rendererInternals(app.renderer)`; a game never calls it. It throws when no
|
|
6575
|
+
* recovery strategy is enabled (`rendering.features.deviceLostRecovery` is off) or under the null
|
|
6576
|
+
* engine, which has no device to lose.
|
|
6577
|
+
*
|
|
6578
|
+
* @internal
|
|
6579
|
+
*/
|
|
6580
|
+
forceDeviceLossForTesting(): void;
|
|
6460
6581
|
/**
|
|
6461
6582
|
* The offscreen render path, when the project declared `rendering.features.postProcessing`.
|
|
6462
6583
|
*
|
|
@@ -6540,8 +6661,8 @@ declare class RendererImpl implements Renderer {
|
|
|
6540
6661
|
* What the ADR actually measured makes the deadlock unnecessary. Lite stamps **every** PBR
|
|
6541
6662
|
* material in the process with one `_buildGroup` singleton, and every Standard material with
|
|
6542
6663
|
* another, so the unit that has to exist at `registerScene` is the *family*, not the asset: "there
|
|
6543
|
-
* are four families to worry about, not one per asset". This warms the two families
|
|
6544
|
-
*
|
|
6664
|
+
* are four families to worry about, not one per asset". This warms the two families core can
|
|
6665
|
+
* produce, plus any material already in the cache, which reaches the ADR's outcome — a
|
|
6545
6666
|
* mesh added later takes the synchronous rebuild path — with two degenerate triangles and no
|
|
6546
6667
|
* ordering problem.
|
|
6547
6668
|
*
|
|
@@ -6555,10 +6676,10 @@ declare class RendererImpl implements Renderer {
|
|
|
6555
6676
|
*/
|
|
6556
6677
|
warmUp(materials: readonly MaterialAsset[]): void;
|
|
6557
6678
|
/**
|
|
6558
|
-
* Picks the object under one
|
|
6679
|
+
* Picks the object under one backing-store pixel of the canvas (see the interface's remarks).
|
|
6559
6680
|
*
|
|
6560
|
-
* @param x - The
|
|
6561
|
-
* @param y - The
|
|
6681
|
+
* @param x - The backing-store pixel x, from the canvas's left edge.
|
|
6682
|
+
* @param y - The backing-store pixel y, from the canvas's top edge.
|
|
6562
6683
|
* @param options - An entity filter.
|
|
6563
6684
|
* @returns What was hit, or `null` for a miss.
|
|
6564
6685
|
*/
|
|
@@ -6583,6 +6704,27 @@ declare class RendererImpl implements Renderer {
|
|
|
6583
6704
|
* @throws IgnifxError with code `IGX-0704` after the render scene has been registered.
|
|
6584
6705
|
*/
|
|
6585
6706
|
requireFeature(feature: RenderingFeature): void;
|
|
6707
|
+
/**
|
|
6708
|
+
* Registers a probe that answers whether another rendering context has a camera of its own.
|
|
6709
|
+
*
|
|
6710
|
+
* @param probe - Answers `true` while the caller has an active camera for the world.
|
|
6711
|
+
* @returns A function that removes the probe.
|
|
6712
|
+
*/
|
|
6713
|
+
addCameraSource(probe: (world: World) => boolean): Disconnect;
|
|
6714
|
+
/**
|
|
6715
|
+
* Whether any registered probe claims a camera for this world.
|
|
6716
|
+
*
|
|
6717
|
+
* @remarks
|
|
6718
|
+
* Asked by the render sync system only in a frame where no enabled `Camera` was found, which is
|
|
6719
|
+
* what keeps `IGX-0706` off a correct 2D-only scene without costing a well-formed 3D scene
|
|
6720
|
+
* anything (`docs/architecture/07-rendering.md` §2.1).
|
|
6721
|
+
*
|
|
6722
|
+
* @param world - The world being reconciled.
|
|
6723
|
+
* @returns `true` when something other than the render scene draws it.
|
|
6724
|
+
*
|
|
6725
|
+
* @internal
|
|
6726
|
+
*/
|
|
6727
|
+
hasExternalCamera(world: World): boolean;
|
|
6586
6728
|
/**
|
|
6587
6729
|
* The material a `MeshRenderer` draws with when it declares none
|
|
6588
6730
|
* (`docs/architecture/07-rendering.md` §2.3): a neutral, fully rough dielectric.
|
|
@@ -6724,6 +6866,19 @@ declare class RendererImpl implements Renderer {
|
|
|
6724
6866
|
*/
|
|
6725
6867
|
dispose(): void;
|
|
6726
6868
|
}
|
|
6869
|
+
/**
|
|
6870
|
+
* Destroys a renderer's GPU device the way a real loss would, so that recovery runs — for tests and
|
|
6871
|
+
* probes that live outside `@ignifx/core` and may not import Babylon Lite (`CONSTITUTION.md` §3.4).
|
|
6872
|
+
*
|
|
6873
|
+
* @remarks
|
|
6874
|
+
* It throws when `rendering.features.deviceLostRecovery` is off, or under the null engine, which
|
|
6875
|
+
* has no device to lose.
|
|
6876
|
+
*
|
|
6877
|
+
* @param renderer - The app's renderer.
|
|
6878
|
+
*
|
|
6879
|
+
* @internal
|
|
6880
|
+
*/
|
|
6881
|
+
export declare function forceRendererDeviceLossForTesting(renderer: Renderer): void;
|
|
6727
6882
|
//#endregion
|
|
6728
6883
|
//#region src/lite/camera.d.ts
|
|
6729
6884
|
/**
|
|
@@ -7334,8 +7489,13 @@ export declare class Camera extends Component implements ComponentHooks {
|
|
|
7334
7489
|
/**
|
|
7335
7490
|
* Builds a world-space ray through a point on the canvas.
|
|
7336
7491
|
*
|
|
7337
|
-
* @
|
|
7338
|
-
*
|
|
7492
|
+
* @remarks
|
|
7493
|
+
* Coordinates are backing-store pixels — the canvas's `width`/`height`, the space
|
|
7494
|
+
* {@link Camera.worldToScreen} answers in and `@ignifx/input` reports `<Pointer>/position` in — not
|
|
7495
|
+
* CSS pixels; multiply a DOM event's `offsetX`/`offsetY` by `devicePixelRatio` first.
|
|
7496
|
+
*
|
|
7497
|
+
* @param x - The backing-store pixel x, from the canvas's left edge.
|
|
7498
|
+
* @param y - The backing-store pixel y, from the canvas's top edge.
|
|
7339
7499
|
* @param out - The ray to fill; a fresh one is allocated when omitted.
|
|
7340
7500
|
* @returns `out`, or `null` when the view-projection matrix is singular — a zero-sized viewport,
|
|
7341
7501
|
* or a camera that is not attached.
|
|
@@ -7361,8 +7521,8 @@ export declare class Camera extends Component implements ComponentHooks {
|
|
|
7361
7521
|
/**
|
|
7362
7522
|
* The world-space point a canvas pixel maps to at a given distance along the view ray.
|
|
7363
7523
|
*
|
|
7364
|
-
* @param x - The
|
|
7365
|
-
* @param y - The
|
|
7524
|
+
* @param x - The backing-store pixel x, from the canvas's left edge (see {@link Camera.screenToRay}).
|
|
7525
|
+
* @param y - The backing-store pixel y, from the canvas's top edge.
|
|
7366
7526
|
* @param distance - How far along the ray to travel, in metres.
|
|
7367
7527
|
* @param out - Receives the point.
|
|
7368
7528
|
* @returns `out`, or `null` when no ray could be built.
|
|
@@ -7410,10 +7570,10 @@ export declare class Camera extends Component implements ComponentHooks {
|
|
|
7410
7570
|
* (`docs/architecture/02-scene-graph.md` §2). One world per app in the MVP.
|
|
7411
7571
|
*
|
|
7412
7572
|
* @remarks
|
|
7413
|
-
*
|
|
7414
|
-
*
|
|
7415
|
-
* `instantiateAsync`,
|
|
7416
|
-
*
|
|
7573
|
+
* The world owns entity creation, queries, the implicit `"default"` scene, and the lifecycle, plus
|
|
7574
|
+
* the scene operations that need the asset service — `loadScene`, `unloadScene`, `instantiate`,
|
|
7575
|
+
* `instantiateAsync`, `moveEntityToScene` — and the `onSceneLoaded`/`onSceneUnloaded` signals they
|
|
7576
|
+
* raise.
|
|
7417
7577
|
*
|
|
7418
7578
|
* @example
|
|
7419
7579
|
* ```ts
|
|
@@ -7524,13 +7684,13 @@ export declare class World implements WorldHost {
|
|
|
7524
7684
|
*/
|
|
7525
7685
|
get onEntityDestroyed(): Signal<Entity>;
|
|
7526
7686
|
/**
|
|
7527
|
-
* Emitted when a scene instance finishes loading.
|
|
7687
|
+
* Emitted when a scene instance finishes loading.
|
|
7528
7688
|
*
|
|
7529
7689
|
* @returns The signal.
|
|
7530
7690
|
*/
|
|
7531
7691
|
get onSceneLoaded(): Signal<SceneInstance>;
|
|
7532
7692
|
/**
|
|
7533
|
-
* Emitted when a scene instance is unloaded.
|
|
7693
|
+
* Emitted when a scene instance is unloaded.
|
|
7534
7694
|
*
|
|
7535
7695
|
* @returns The signal.
|
|
7536
7696
|
*/
|
|
@@ -9125,8 +9285,16 @@ interface FrameSample {
|
|
|
9125
9285
|
/** How many entities and components were destroyed in this frame's flush. */
|
|
9126
9286
|
destroyed: number;
|
|
9127
9287
|
/**
|
|
9128
|
-
* CPU milliseconds per phase, indexed by {@link PhaseIndex}. Always {@link PHASE_COUNT} long and
|
|
9129
|
-
* only
|
|
9288
|
+
* CPU milliseconds per phase, indexed by {@link PhaseIndex}. Always {@link PHASE_COUNT} long, and
|
|
9289
|
+
* filled only while the app is in development mode — every entry is `0` otherwise.
|
|
9290
|
+
*
|
|
9291
|
+
* @remarks
|
|
9292
|
+
* "Development mode" is `createApp({ mode })`, and nothing else. It is **not** the bundler's mode:
|
|
9293
|
+
* `mode` defaults to `"development"` and no ignifx tooling overrides it, so a `vite build` of a
|
|
9294
|
+
* game that never passes `mode` still records these timings. A project that wants them gone from
|
|
9295
|
+
* its shipped build passes `mode: "production"` itself — for example
|
|
9296
|
+
* `createApp({ mode: import.meta.env.PROD ? "production" : "development" })` — and a probe that
|
|
9297
|
+
* reads `cpuMs` then reports zeros.
|
|
9130
9298
|
*/
|
|
9131
9299
|
readonly cpuMs: Float64Array;
|
|
9132
9300
|
}
|
|
@@ -9192,8 +9360,10 @@ interface ProfileScope {
|
|
|
9192
9360
|
*/
|
|
9193
9361
|
interface DiagnosticsOptions {
|
|
9194
9362
|
/**
|
|
9195
|
-
* Whether
|
|
9196
|
-
* entries are only produced when it is `true`. Defaults to `false
|
|
9363
|
+
* Whether the app runs in development mode. Per-phase CPU timings and
|
|
9364
|
+
* `performance.mark`/`measure` entries are only produced when it is `true`. Defaults to `false`
|
|
9365
|
+
* here; `createApp` passes `mode === "development"`, and that `mode` itself defaults to
|
|
9366
|
+
* `"development"` in every build — a bundler's production flag does not change it.
|
|
9197
9367
|
*/
|
|
9198
9368
|
readonly development?: boolean;
|
|
9199
9369
|
/**
|
|
@@ -9231,7 +9401,11 @@ export declare class Diagnostics {
|
|
|
9231
9401
|
* them. Values are reset by {@link Diagnostics.beginFrame}.
|
|
9232
9402
|
*/
|
|
9233
9403
|
readonly frame: FrameSample;
|
|
9234
|
-
/**
|
|
9404
|
+
/**
|
|
9405
|
+
* Whether per-phase timings and User Timing entries are being recorded — that is, whether the app
|
|
9406
|
+
* was created with `mode: "development"`, which is the default in every build. Read it before
|
|
9407
|
+
* trusting `FrameSample.cpuMs`.
|
|
9408
|
+
*/
|
|
9235
9409
|
readonly isDevelopment: boolean;
|
|
9236
9410
|
/** How many frames the history can hold. */
|
|
9237
9411
|
readonly historyCapacity: number;
|
|
@@ -9282,6 +9456,11 @@ export declare class Diagnostics {
|
|
|
9282
9456
|
/**
|
|
9283
9457
|
* Registers a subsystem's counter group.
|
|
9284
9458
|
*
|
|
9459
|
+
* @remarks
|
|
9460
|
+
* A second registration of the same name is a mistake, not a merge, so it throws. A script that
|
|
9461
|
+
* cannot know whether it is the first instance to run — a gameplay counter shared by every enemy,
|
|
9462
|
+
* a group that survives a scene reload — asks for {@link Diagnostics.groupOrRegister} instead.
|
|
9463
|
+
*
|
|
9285
9464
|
* @param name - The group name, unique within this app.
|
|
9286
9465
|
* @param counterNames - The counter names, in the order their indices are assigned.
|
|
9287
9466
|
* @returns The group, whose indices are resolved once with {@link DiagnosticsGroup.index}.
|
|
@@ -9296,6 +9475,33 @@ export declare class Diagnostics {
|
|
|
9296
9475
|
* absence, not a failure (coding standards §5.5).
|
|
9297
9476
|
*/
|
|
9298
9477
|
group(name: string): DiagnosticsGroup | null;
|
|
9478
|
+
/**
|
|
9479
|
+
* Looks a counter group up by name and registers it if no subsystem has yet — the idiom for code
|
|
9480
|
+
* that may run more than once (`docs/architecture/15-devtools-and-diagnostics.md` §3).
|
|
9481
|
+
*
|
|
9482
|
+
* @remarks
|
|
9483
|
+
* `registerGroup` throws `IGX-1503` on a duplicate name, which is right for an extension that
|
|
9484
|
+
* registers its group once at `register()` time and wrong for a script: a script's `awake` runs
|
|
9485
|
+
* once per instance, and a scene reload runs it again, so `group(name) ?? registerGroup(name, …)`
|
|
9486
|
+
* had to be written out by hand at every call site. This is that expression, with one difference
|
|
9487
|
+
* worth knowing: when the group already exists it is returned **as it was registered**, and
|
|
9488
|
+
* `counterNames` is ignored rather than merged — Lite-style counter arrays are indexed, and
|
|
9489
|
+
* growing one under a subsystem that already holds indices into it would silently renumber its
|
|
9490
|
+
* counters. A caller that then asks for a counter the first registration did not declare gets
|
|
9491
|
+
* `IGX-1504` from {@link DiagnosticsGroup.index}, which names the group and the counter.
|
|
9492
|
+
*
|
|
9493
|
+
* @param name - The group name.
|
|
9494
|
+
* @param counterNames - The counter names to register with, used only on the first call.
|
|
9495
|
+
* @returns The existing group, or the newly registered one.
|
|
9496
|
+
*
|
|
9497
|
+
* @example
|
|
9498
|
+
* ```ts
|
|
9499
|
+
* // In a Script's `awake`, which runs once per instance and again after a scene reload.
|
|
9500
|
+
* const counters = this.app.diagnostics.groupOrRegister("game", ["enemiesAlive", "wavesCleared"]);
|
|
9501
|
+
* this.enemiesAlive = counters.index("enemiesAlive");
|
|
9502
|
+
* ```
|
|
9503
|
+
*/
|
|
9504
|
+
groupOrRegister(name: string, counterNames: readonly string[]): DiagnosticsGroup;
|
|
9299
9505
|
/**
|
|
9300
9506
|
* Opens a timing scope. In development builds it writes a `performance.mark`/`measure` pair that
|
|
9301
9507
|
* shows up in browser profilers; outside development it is free
|
|
@@ -9314,6 +9520,141 @@ export declare class Diagnostics {
|
|
|
9314
9520
|
profile(name: string): ProfileScope;
|
|
9315
9521
|
}
|
|
9316
9522
|
//#endregion
|
|
9523
|
+
//#region src/hot-reload/contract.d.ts
|
|
9524
|
+
/**
|
|
9525
|
+
* What a class asks the engine to do with its live instances when its module is replaced
|
|
9526
|
+
* (`docs/architecture/15-devtools-and-diagnostics.md` §5).
|
|
9527
|
+
*
|
|
9528
|
+
* @remarks
|
|
9529
|
+
* `"patch"` is the default and the one to reach for while iterating on logic: the live instances
|
|
9530
|
+
* keep their identity and every field value, and no lifecycle callback re-runs. `"recreate"` is
|
|
9531
|
+
* required when the *field layout* changes, because a patched instance keeps whatever properties
|
|
9532
|
+
* its constructor assigned and a renamed or added field would read `undefined`.
|
|
9533
|
+
*
|
|
9534
|
+
* @public
|
|
9535
|
+
*/
|
|
9536
|
+
type HotReloadPolicy = "patch" | "recreate";
|
|
9537
|
+
/**
|
|
9538
|
+
* What one {@link HotReloadReport} describes: a prototype swap, a destroy-and-rebuild of component
|
|
9539
|
+
* instances, or a scene instance rebuilt from its file.
|
|
9540
|
+
*
|
|
9541
|
+
* @public
|
|
9542
|
+
*/
|
|
9543
|
+
type HotReloadKind = "patch" | "recreate" | "scene";
|
|
9544
|
+
/**
|
|
9545
|
+
* The statics a component or script class may declare to steer its own hot reload
|
|
9546
|
+
* (`docs/architecture/15-devtools-and-diagnostics.md` §5). Structural and optional, for the reason
|
|
9547
|
+
* given on `ComponentStatics`: a member declared on the `Component` base class would force the
|
|
9548
|
+
* `override` keyword on every `static hotReload = "recreate"` under `noImplicitOverride`.
|
|
9549
|
+
*
|
|
9550
|
+
* @example
|
|
9551
|
+
* ```ts
|
|
9552
|
+
* class Inventory extends Script.define({ slots: u32(4) }) {
|
|
9553
|
+
* static typeId = "mygame/Inventory";
|
|
9554
|
+
* static hotReload = "recreate" as const;
|
|
9555
|
+
* }
|
|
9556
|
+
* ```
|
|
9557
|
+
*
|
|
9558
|
+
* @public
|
|
9559
|
+
*/
|
|
9560
|
+
interface HotReloadStatics {
|
|
9561
|
+
/** The policy for this class; defaults to `"patch"`. */
|
|
9562
|
+
readonly hotReload?: HotReloadPolicy;
|
|
9563
|
+
/**
|
|
9564
|
+
* Runs once on the **new** class after every live instance of it has been swapped or re-created,
|
|
9565
|
+
* with the class that was registered before as `previous`. It is the seam for class-level
|
|
9566
|
+
* transient state — a cache keyed off the old class, a static counter — and it is deliberately
|
|
9567
|
+
* not per instance: under `"patch"` the instances are the very same objects, so there is
|
|
9568
|
+
* nothing to copy across (PlayCanvas's `swap(old)` exists only because it re-instantiates), and
|
|
9569
|
+
* under `"recreate"` per-instance state is re-derived from the schema by design.
|
|
9570
|
+
*
|
|
9571
|
+
* @param previous - The class this one replaces.
|
|
9572
|
+
*/
|
|
9573
|
+
onHotReload?(previous: ConcreteComponentType): void;
|
|
9574
|
+
}
|
|
9575
|
+
/**
|
|
9576
|
+
* One replaced module's worth of component classes, as the HMR client hands them over. Classes the
|
|
9577
|
+
* app has never seen are registered; classes whose `typeId` is already registered to a different
|
|
9578
|
+
* class are reloaded under their policy; classes that are already the registered ones are skipped.
|
|
9579
|
+
*
|
|
9580
|
+
* @public
|
|
9581
|
+
*/
|
|
9582
|
+
interface HotReloadModule {
|
|
9583
|
+
/** Every component or script class the replaced module exports. */
|
|
9584
|
+
readonly types: readonly ConcreteComponentType[];
|
|
9585
|
+
}
|
|
9586
|
+
/**
|
|
9587
|
+
* What one hot reload did, for logs, tests, and the devtools overlay.
|
|
9588
|
+
*
|
|
9589
|
+
* @public
|
|
9590
|
+
*/
|
|
9591
|
+
interface HotReloadReport {
|
|
9592
|
+
/** Which of the three operations this report describes. */
|
|
9593
|
+
readonly kind: HotReloadKind;
|
|
9594
|
+
/** The `typeId`s actually reloaded, in the order they were applied; empty when nothing changed. */
|
|
9595
|
+
readonly typeIds: readonly string[];
|
|
9596
|
+
/** How many live component instances were swapped or re-created, or entities rebuilt for a scene. */
|
|
9597
|
+
readonly instances: number;
|
|
9598
|
+
/** How long the operation took, in milliseconds. */
|
|
9599
|
+
readonly durationMs: number;
|
|
9600
|
+
/** Everything that threw on the way; the reload continues past each one. */
|
|
9601
|
+
readonly errors: readonly unknown[];
|
|
9602
|
+
}
|
|
9603
|
+
/**
|
|
9604
|
+
* The app's hot-reload service, reached as `app.hotReload`
|
|
9605
|
+
* (`docs/architecture/15-devtools-and-diagnostics.md` §5). It works with no Vite and no browser:
|
|
9606
|
+
* `@ignifx/vite-plugin` generates a client that calls {@link HotReloadHost.apply}, and a headless
|
|
9607
|
+
* test calls it directly.
|
|
9608
|
+
*
|
|
9609
|
+
* @example
|
|
9610
|
+
* ```ts
|
|
9611
|
+
* const report = app.hotReload.apply([{ types: [NextMover] }]);
|
|
9612
|
+
* console.log(report.kind, report.typeIds, report.instances);
|
|
9613
|
+
* ```
|
|
9614
|
+
*
|
|
9615
|
+
* @public
|
|
9616
|
+
*/
|
|
9617
|
+
interface HotReloadHost {
|
|
9618
|
+
/**
|
|
9619
|
+
* Emitted once per completed {@link HotReloadHost.apply} or
|
|
9620
|
+
* {@link HotReloadHost.reloadScene} with the report that call returns.
|
|
9621
|
+
*/
|
|
9622
|
+
readonly onApplied: SignalLike<HotReloadReport>;
|
|
9623
|
+
/**
|
|
9624
|
+
* Whether a changed scene file re-instantiates the live scene instances built from it, set with
|
|
9625
|
+
* `createApp({ hotReload: { reloadScenes: true } })`. Off by default, because rebuilding a scene
|
|
9626
|
+
* throws away everything the running game has done to it.
|
|
9627
|
+
*/
|
|
9628
|
+
readonly reloadScenes: boolean;
|
|
9629
|
+
/**
|
|
9630
|
+
* Applies replaced component classes to the running app.
|
|
9631
|
+
*
|
|
9632
|
+
* @param modules - The replaced modules and the classes they export.
|
|
9633
|
+
* @returns What was reloaded.
|
|
9634
|
+
* @throws IgnifxError with code `IGX-0208` when called from inside a lifecycle callback, where a
|
|
9635
|
+
* half-swapped world would be observable.
|
|
9636
|
+
*/
|
|
9637
|
+
apply(modules: readonly HotReloadModule[]): HotReloadReport;
|
|
9638
|
+
/**
|
|
9639
|
+
* Rebuilds one scene instance from its asset's current value, honouring the file's instance
|
|
9640
|
+
* overrides wherever their paths still resolve.
|
|
9641
|
+
*
|
|
9642
|
+
* @param instance - The instance to rebuild. It is unloaded and a fresh one takes its place.
|
|
9643
|
+
* @returns The new instance.
|
|
9644
|
+
* @throws IgnifxError with code `IGX-0209` when the instance was not built from a scene asset.
|
|
9645
|
+
*/
|
|
9646
|
+
reloadScene(instance: SceneInstance): Promise<SceneInstance>;
|
|
9647
|
+
}
|
|
9648
|
+
/**
|
|
9649
|
+
* The `hotReload` section of `createApp`'s options.
|
|
9650
|
+
*
|
|
9651
|
+
* @public
|
|
9652
|
+
*/
|
|
9653
|
+
interface HotReloadOptions {
|
|
9654
|
+
/** Sets {@link HotReloadHost.reloadScenes}. Defaults to `false`. */
|
|
9655
|
+
readonly reloadScenes?: boolean;
|
|
9656
|
+
}
|
|
9657
|
+
//#endregion
|
|
9317
9658
|
//#region src/log/log-level.d.ts
|
|
9318
9659
|
/**
|
|
9319
9660
|
* Severity levels and the record shape the logging sinks receive
|
|
@@ -9400,10 +9741,15 @@ interface LogSink {
|
|
|
9400
9741
|
* one numeric comparison. The rest parameter itself is still materialised by the JavaScript engine,
|
|
9401
9742
|
* so per-frame call sites guard with {@link Logger.isEnabled} instead (coding standards §7).
|
|
9402
9743
|
*
|
|
9744
|
+
* **A message is not a format string.** It is written to the sink verbatim and the extras are
|
|
9745
|
+
* appended beside it, the way `console.warn(message, ...data)` does; nothing substitutes into it, so
|
|
9746
|
+
* a `{placeholder}` token is printed literally. Pass values as extras
|
|
9747
|
+
* (`log.info("hero z:", z)`), never as tokens inside the message.
|
|
9748
|
+
*
|
|
9403
9749
|
* @example
|
|
9404
9750
|
* ```ts
|
|
9405
9751
|
* const log = app.log.child("physics");
|
|
9406
|
-
* log.info("stepping at
|
|
9752
|
+
* log.info("stepping at 60 Hz");
|
|
9407
9753
|
* if (log.isEnabled("debug")) {
|
|
9408
9754
|
* log.debug("contacts", collectContacts());
|
|
9409
9755
|
* }
|
|
@@ -9475,6 +9821,16 @@ interface Logger {
|
|
|
9475
9821
|
* @returns The scoped logger.
|
|
9476
9822
|
*/
|
|
9477
9823
|
child(scope: string): Logger;
|
|
9824
|
+
/**
|
|
9825
|
+
* Adds a second sink that receives every record this logger tree writes, alongside the one
|
|
9826
|
+
* `createApp({ logSink })` installed. Children share the list, so a sink added on `app.log` sees
|
|
9827
|
+
* `ctx.log` records too. This is how `@ignifx/devtools` fills its Console panel without the game
|
|
9828
|
+
* wiring anything.
|
|
9829
|
+
*
|
|
9830
|
+
* @param sink - The sink to add.
|
|
9831
|
+
* @returns A function that removes it again.
|
|
9832
|
+
*/
|
|
9833
|
+
addSink(sink: LogSink): () => void;
|
|
9478
9834
|
}
|
|
9479
9835
|
/**
|
|
9480
9836
|
* Options for {@link createLogger}.
|
|
@@ -9503,7 +9859,8 @@ interface LoggerOptions {
|
|
|
9503
9859
|
* @example
|
|
9504
9860
|
* ```ts
|
|
9505
9861
|
* const log = createLogger({ sink: createConsoleSink(), level: "debug" });
|
|
9506
|
-
*
|
|
9862
|
+
* // A message is not a format string — nothing substitutes into it. Pass values as extras.
|
|
9863
|
+
* log.child("assets").warnOnce("missing-atlas", "No atlas for sprite:", spriteId);
|
|
9507
9864
|
* ```
|
|
9508
9865
|
*
|
|
9509
9866
|
* @public
|
|
@@ -9512,102 +9869,908 @@ export declare function createLogger(options: LoggerOptions): Logger;
|
|
|
9512
9869
|
//#endregion
|
|
9513
9870
|
//#region src/platform/platform.d.ts
|
|
9514
9871
|
/**
|
|
9515
|
-
*
|
|
9516
|
-
* (`docs/architecture/14-platform-electron.md` §1).
|
|
9517
|
-
*
|
|
9518
|
-
*
|
|
9519
|
-
*
|
|
9872
|
+
* `app.platform`: what the engine knows about the host it is running on
|
|
9873
|
+
* (`docs/architecture/14-platform-electron.md` §1). Extensions branch on it — the input extension to
|
|
9874
|
+
* decide whether pointer lock is worth offering, the renderer to size its budgets — and game code
|
|
9875
|
+
* rarely should.
|
|
9876
|
+
*
|
|
9877
|
+
* ## Decisions the documents left open
|
|
9878
|
+
*
|
|
9879
|
+
* - **Detection is a pure function of a `PlatformHost` record.** §1 says the service is
|
|
9880
|
+
* "populated at `createApp`" and nothing else. Reading the globals and *interpreting* them are
|
|
9881
|
+
* two different jobs, and only the first one needs a browser: `readPlatformHost` scrapes
|
|
9882
|
+
* `globalThis` and `detectPlatform` turns the result into a {@link PlatformInfo}. That is
|
|
9883
|
+
* what lets the whole of the interpretation — every operating system, every mobile heuristic — be
|
|
9884
|
+
* unit-tested under Node with a fabricated host.
|
|
9885
|
+
* - **`kind` is `"browser"` until something proves otherwise.** An Electron renderer *is* a browser
|
|
9886
|
+
* as far as the kernel can tell; guessing from the user agent would be worse than being honest.
|
|
9887
|
+
* `@ignifx/electron` detects its own preload bridge and calls
|
|
9888
|
+
* `platformInternals(app.platform).setKind("electron")`, which is the one supported mutation.
|
|
9889
|
+
* - **`webgpu` describes the adapter, not the device.** Babylon Lite's public `index.d.ts` (v1.27.0)
|
|
9890
|
+
* exposes neither the `GPUAdapter` nor the `GPUDevice` it acquired — `EngineContext` declares only
|
|
9891
|
+
* `surfaces`, `drawCallCount`, `gpuFrameTimeMs`, `useHighPrecisionMatrix` and `useFloatingOrigin`
|
|
9892
|
+
* — so reaching the engine's device would mean an assertion onto an undocumented `_device`
|
|
9893
|
+
* property. `createApp` asks `navigator.gpu` for a *second* adapter instead, which costs nothing
|
|
9894
|
+
* (an adapter is not a device) and reports what the hardware can do rather than what Lite asked
|
|
9895
|
+
* for. `features` and `limits` are therefore an upper bound on the running device's.
|
|
9896
|
+
* - **Every field is plain data.** `features` is a sorted string array and `limits` a number record,
|
|
9897
|
+
* not the live `GPUSupportedFeatures`/`GPUSupportedLimits` objects, so the whole record survives
|
|
9898
|
+
* `JSON.stringify` into a bug report or a devtools panel.
|
|
9520
9899
|
*/
|
|
9521
9900
|
/**
|
|
9522
9901
|
* Where an app is running.
|
|
9523
9902
|
*
|
|
9903
|
+
* @public
|
|
9904
|
+
*/
|
|
9905
|
+
type PlatformKind = "browser" | "electron" | "node";
|
|
9906
|
+
/**
|
|
9907
|
+
* Which operating system the host runs, as far as it will admit.
|
|
9908
|
+
*
|
|
9909
|
+
* @remarks
|
|
9910
|
+
* `"unknown"` is a real answer, not a failure: a locked-down browser that freezes its user agent
|
|
9911
|
+
* and exposes no `navigator.userAgentData` genuinely does not say, and code that branches on the
|
|
9912
|
+
* operating system has to have a default anyway.
|
|
9913
|
+
*
|
|
9914
|
+
* @public
|
|
9915
|
+
*/
|
|
9916
|
+
type PlatformOs = "macos" | "windows" | "linux" | "ios" | "android" | "unknown";
|
|
9917
|
+
/**
|
|
9918
|
+
* Who made the GPU, as WebGPU reports it.
|
|
9919
|
+
*
|
|
9524
9920
|
* @remarks
|
|
9525
|
-
*
|
|
9526
|
-
*
|
|
9527
|
-
*
|
|
9921
|
+
* Browsers deliberately blur these strings — most return an empty `architecture` and `device` on
|
|
9922
|
+
* the default, non-`unmaskHints` path — so treat every field as a hint for a bug report rather than
|
|
9923
|
+
* as something to branch on.
|
|
9528
9924
|
*
|
|
9529
9925
|
* @public
|
|
9530
9926
|
*/
|
|
9531
|
-
|
|
9927
|
+
interface GpuAdapterInfo {
|
|
9928
|
+
/** The GPU vendor, `"apple"` or `"nvidia"`; `""` when the browser withholds it. */
|
|
9929
|
+
readonly vendor: string;
|
|
9930
|
+
/** The GPU family, `"metal-3"`; `""` when the browser withholds it. */
|
|
9931
|
+
readonly architecture: string;
|
|
9932
|
+
/** The specific device; `""` when the browser withholds it. */
|
|
9933
|
+
readonly device: string;
|
|
9934
|
+
/** A human-readable summary; `""` when the browser withholds it. */
|
|
9935
|
+
readonly description: string;
|
|
9936
|
+
}
|
|
9937
|
+
/**
|
|
9938
|
+
* What the host's WebGPU adapter offers.
|
|
9939
|
+
*
|
|
9940
|
+
* @public
|
|
9941
|
+
*/
|
|
9942
|
+
interface WebGpuInfo {
|
|
9943
|
+
/** Who made the adapter. */
|
|
9944
|
+
readonly adapterInfo: GpuAdapterInfo;
|
|
9945
|
+
/** The optional features the adapter supports, sorted ascending. */
|
|
9946
|
+
readonly features: readonly string[];
|
|
9947
|
+
/** The adapter's limits, by their WebGPU names. */
|
|
9948
|
+
readonly limits: Readonly<Record<string, number>>;
|
|
9949
|
+
}
|
|
9532
9950
|
/**
|
|
9533
|
-
* What the kernel knows about the host.
|
|
9951
|
+
* What the kernel knows about the host, reached as `app.platform`.
|
|
9534
9952
|
*
|
|
9535
9953
|
* @example
|
|
9536
9954
|
* ```ts
|
|
9537
|
-
* if (app.platform.
|
|
9538
|
-
*
|
|
9955
|
+
* if (app.platform.isMobile) {
|
|
9956
|
+
* app.renderer.resolutionScale = 0.75;
|
|
9957
|
+
* }
|
|
9958
|
+
* if (app.platform.reducedMotion) {
|
|
9959
|
+
* disableScreenShake();
|
|
9539
9960
|
* }
|
|
9540
9961
|
* ```
|
|
9541
9962
|
*
|
|
9542
9963
|
* @public
|
|
9543
9964
|
*/
|
|
9544
9965
|
interface PlatformInfo {
|
|
9545
|
-
/** Whether the app runs in a document or in a bare JavaScript runtime. */
|
|
9966
|
+
/** Whether the app runs in a document, in an Electron renderer, or in a bare JavaScript runtime. */
|
|
9546
9967
|
readonly kind: PlatformKind;
|
|
9547
|
-
|
|
9548
|
-
|
|
9549
|
-
|
|
9550
|
-
|
|
9551
|
-
|
|
9552
|
-
|
|
9553
|
-
|
|
9554
|
-
|
|
9968
|
+
/** The operating system, or `"unknown"` when the host does not say. */
|
|
9969
|
+
readonly os: PlatformOs;
|
|
9970
|
+
/** `true` on a phone or a tablet. */
|
|
9971
|
+
readonly isMobile: boolean;
|
|
9972
|
+
/** `true` when the host implements the Pointer Lock API. */
|
|
9973
|
+
readonly hasPointerLock: boolean;
|
|
9974
|
+
/** `true` when the host implements the Gamepad API. */
|
|
9975
|
+
readonly hasGamepads: boolean;
|
|
9976
|
+
/** What WebGPU offers, or `null` in a headless app and on a host with no WebGPU. */
|
|
9977
|
+
readonly webgpu: WebGpuInfo | null;
|
|
9978
|
+
/** The host's BCP 47 language tag, `"en-AU"`. Never empty. */
|
|
9979
|
+
readonly locale: string;
|
|
9980
|
+
/** `true` when the user asked their system for reduced motion. */
|
|
9981
|
+
readonly reducedMotion: boolean;
|
|
9982
|
+
}
|
|
9983
|
+
/**
|
|
9984
|
+
* The raw host readings `detectPlatform` interprets. Every field is exactly one global read, so a
|
|
9985
|
+
* test can fabricate any host without touching `globalThis`.
|
|
9555
9986
|
*
|
|
9556
|
-
*
|
|
9557
|
-
|
|
9987
|
+
* @internal
|
|
9988
|
+
*/
|
|
9989
|
+
interface PlatformHost {
|
|
9990
|
+
/** `true` when both a `document` and a `window` are reachable. */
|
|
9991
|
+
readonly hasDocument: boolean;
|
|
9992
|
+
/** `navigator.userAgent`, or `null`. */
|
|
9993
|
+
readonly userAgent: string | null;
|
|
9994
|
+
/** The deprecated `navigator.platform`, or `null`. */
|
|
9995
|
+
readonly navigatorPlatform: string | null;
|
|
9996
|
+
/** `navigator.userAgentData.platform`, or `null` on a browser that has no client hints. */
|
|
9997
|
+
readonly userAgentDataPlatform: string | null;
|
|
9998
|
+
/** `navigator.userAgentData.mobile`, or `null` on a browser that has no client hints. */
|
|
9999
|
+
readonly userAgentDataMobile: boolean | null;
|
|
10000
|
+
/** `navigator.maxTouchPoints`, `0` when the host has none. */
|
|
10001
|
+
readonly maxTouchPoints: number;
|
|
10002
|
+
/** `true` when the document implements pointer lock. */
|
|
10003
|
+
readonly hasPointerLock: boolean;
|
|
10004
|
+
/** `true` when the navigator implements the Gamepad API. */
|
|
10005
|
+
readonly hasGamepads: boolean;
|
|
10006
|
+
/** The BCP 47 language tag the host reports. */
|
|
10007
|
+
readonly locale: string;
|
|
10008
|
+
/** `true` when `(prefers-reduced-motion: reduce)` matches. */
|
|
10009
|
+
readonly reducedMotion: boolean;
|
|
10010
|
+
/** Node's `process.platform`, or `null` outside Node. */
|
|
10011
|
+
readonly processPlatform: string | null;
|
|
10012
|
+
}
|
|
10013
|
+
/**
|
|
10014
|
+
* The mutable `PlatformInfo` the app owns.
|
|
10015
|
+
*
|
|
10016
|
+
* @internal
|
|
9558
10017
|
*/
|
|
10018
|
+
declare class PlatformInfoImpl implements PlatformInfo {
|
|
10019
|
+
#private;
|
|
10020
|
+
/** The operating system. */
|
|
10021
|
+
readonly os: PlatformOs;
|
|
10022
|
+
/** `true` on a phone or a tablet. */
|
|
10023
|
+
readonly isMobile: boolean;
|
|
10024
|
+
/** `true` when the host implements pointer lock. */
|
|
10025
|
+
readonly hasPointerLock: boolean;
|
|
10026
|
+
/** `true` when the host implements the Gamepad API. */
|
|
10027
|
+
readonly hasGamepads: boolean;
|
|
10028
|
+
/** The host's BCP 47 language tag. */
|
|
10029
|
+
readonly locale: string;
|
|
10030
|
+
/** `true` when the user asked for reduced motion. */
|
|
10031
|
+
readonly reducedMotion: boolean;
|
|
10032
|
+
/**
|
|
10033
|
+
* Builds the record from one set of host readings.
|
|
10034
|
+
*
|
|
10035
|
+
* @param host - What `readPlatformHost` scraped, or what a test fabricated.
|
|
10036
|
+
*/
|
|
10037
|
+
constructor(host: PlatformHost);
|
|
10038
|
+
/**
|
|
10039
|
+
* Where the app is running.
|
|
10040
|
+
*
|
|
10041
|
+
* @returns The host kind.
|
|
10042
|
+
*/
|
|
10043
|
+
get kind(): PlatformKind;
|
|
10044
|
+
/**
|
|
10045
|
+
* What WebGPU offers.
|
|
10046
|
+
*
|
|
10047
|
+
* @returns The adapter report, or `null` in a headless app.
|
|
10048
|
+
*/
|
|
10049
|
+
get webgpu(): WebGpuInfo | null;
|
|
10050
|
+
/**
|
|
10051
|
+
* Records that this browser is in fact an Electron renderer.
|
|
10052
|
+
*
|
|
10053
|
+
* @param kind - The host kind to report from now on.
|
|
10054
|
+
*/
|
|
10055
|
+
setKind(kind: PlatformKind): void;
|
|
10056
|
+
/**
|
|
10057
|
+
* Records what the WebGPU adapter offered.
|
|
10058
|
+
*
|
|
10059
|
+
* @param webgpu - The adapter report, or `null` to clear it.
|
|
10060
|
+
*/
|
|
10061
|
+
setWebGpu(webgpu: WebGpuInfo | null): void;
|
|
10062
|
+
}
|
|
9559
10063
|
/**
|
|
9560
|
-
*
|
|
9561
|
-
*
|
|
9562
|
-
* `FrameSample.cpuMs`.
|
|
10064
|
+
* Reaches the mutable half of `app.platform`, the way `rendererInternals` does for the renderer.
|
|
10065
|
+
* `@ignifx/electron` uses it to record that the browser it detected is an Electron renderer.
|
|
9563
10066
|
*
|
|
9564
|
-
* @
|
|
9565
|
-
*
|
|
9566
|
-
*
|
|
9567
|
-
*
|
|
10067
|
+
* @param platform - The record, normally `app.platform`.
|
|
10068
|
+
* @returns The implementation.
|
|
10069
|
+
* @throws IgnifxError with code `IGX-0702` when the record was not created by this copy of
|
|
10070
|
+
* `@ignifx/core`.
|
|
9568
10071
|
*
|
|
9569
10072
|
* @example
|
|
9570
10073
|
* ```ts
|
|
9571
|
-
*
|
|
10074
|
+
* platformInternals(app.platform).setKind("electron");
|
|
9572
10075
|
* ```
|
|
9573
10076
|
*
|
|
9574
|
-
* @
|
|
10077
|
+
* @internal
|
|
9575
10078
|
*/
|
|
9576
|
-
export declare
|
|
9577
|
-
|
|
9578
|
-
|
|
9579
|
-
/** Input polling and asset delivery, before any script callback. */
|
|
9580
|
-
readonly PreUpdate: 1;
|
|
9581
|
-
/** The fixed-timestep simulation loop: `fixedUpdate`, physics, collision dispatch. */
|
|
9582
|
-
readonly FixedUpdate: 2;
|
|
9583
|
-
/** `update` on every enabled script, then coroutine resumption. */
|
|
9584
|
-
readonly Update: 3;
|
|
9585
|
-
/** Animation, state machines, and tweens, between `update` and `lateUpdate`. */
|
|
9586
|
-
readonly PostUpdate: 4;
|
|
9587
|
-
/** Render synchronisation: interpolation, sprite and camera sync, audio, diagnostics. */
|
|
9588
|
-
readonly PreRender: 5;
|
|
9589
|
-
};
|
|
10079
|
+
export declare function platformInternals(platform: PlatformInfo): PlatformInfoImpl;
|
|
10080
|
+
//#endregion
|
|
10081
|
+
//#region src/storage/backend.d.ts
|
|
9590
10082
|
/**
|
|
9591
|
-
* The
|
|
10083
|
+
* The contract every storage backend implements, and the value shape backends persist
|
|
10084
|
+
* (`docs/architecture/14-platform-electron.md` §2). This module declares types only — no behaviour,
|
|
10085
|
+
* no imports — so that `@ignifx/electron` can implement the contract without depending on anything
|
|
10086
|
+
* else in the kernel, and so that {@link StorageBackend} can be quoted in full in a design review.
|
|
9592
10087
|
*
|
|
9593
|
-
*
|
|
9594
|
-
*/
|
|
9595
|
-
export type Phase = (typeof Phase)[keyof typeof Phase];
|
|
9596
|
-
/**
|
|
9597
|
-
* Every phase in frame order, for loops that walk them all.
|
|
10088
|
+
* The split of responsibilities is the whole point of the contract:
|
|
9598
10089
|
*
|
|
9599
|
-
*
|
|
10090
|
+
* - The `Storage` facade (`./storage.ts`) owns **policy**: it validates namespace and key syntax,
|
|
10091
|
+
* turns a JavaScript value into a {@link StoredValue} (canonical JSON text, or bytes), and turns a
|
|
10092
|
+
* {@link StoredValue} back into a value. A backend never sees a user object.
|
|
10093
|
+
* - A backend owns **persistence**: it stores opaque JSON text or opaque bytes under a
|
|
10094
|
+
* `(namespace, key)` pair, and reports failures as `IgnifxError`s from the storage code block.
|
|
10095
|
+
*
|
|
10096
|
+
* A backend that keeps those two rules is interchangeable with every other one, which is what makes
|
|
10097
|
+
* the same save file readable from the memory backend in a unit test, the IndexedDB backend in a
|
|
10098
|
+
* browser, and the Electron file-system backend on a desktop build.
|
|
9600
10099
|
*/
|
|
9601
|
-
export declare const PHASES: readonly Phase[];
|
|
9602
10100
|
/**
|
|
9603
|
-
*
|
|
10101
|
+
* Which of the two representations a stored value uses.
|
|
10102
|
+
*
|
|
10103
|
+
* @remarks
|
|
10104
|
+
* `"json"` carries text produced by the facade's canonical `JSON.stringify`; `"bytes"` carries the
|
|
10105
|
+
* raw octets of a `Blob`, `ArrayBuffer`, or `Uint8Array` the caller handed to `set`. The kind is
|
|
10106
|
+
* stored alongside the payload — a backend that loses it cannot round-trip, because JSON text and
|
|
10107
|
+
* a UTF-8 byte array are indistinguishable once written.
|
|
9604
10108
|
*
|
|
9605
10109
|
* @public
|
|
9606
10110
|
*/
|
|
9607
|
-
|
|
10111
|
+
type StoredValueKind = "json" | "bytes";
|
|
9608
10112
|
/**
|
|
9609
|
-
*
|
|
9610
|
-
*
|
|
10113
|
+
* A value as a backend sees it: opaque JSON text, or opaque octets.
|
|
10114
|
+
*
|
|
10115
|
+
* @remarks
|
|
10116
|
+
* The two members are a discriminated union on their `kind`, so a backend switches once
|
|
10117
|
+
* and the compiler proves both arms are handled. Backends must round-trip both members exactly: the
|
|
10118
|
+
* `json` string that comes back from {@link StorageBackend.get} has to be the same string that went
|
|
10119
|
+
* into {@link StorageBackend.set}, and the `bytes` have to be byte-identical and the same length. A
|
|
10120
|
+
* backend may copy the bytes (IndexedDB's structured clone does) but must never alias the caller's
|
|
10121
|
+
* buffer after `set` resolves.
|
|
10122
|
+
*
|
|
10123
|
+
* @example
|
|
10124
|
+
* ```ts
|
|
10125
|
+
* const value: StoredValue = { kind: "json", json: '{"volume":0.8}' };
|
|
10126
|
+
* await backend.set("settings", "audio", value);
|
|
10127
|
+
* ```
|
|
10128
|
+
*
|
|
10129
|
+
* @public
|
|
10130
|
+
*/
|
|
10131
|
+
type StoredValue = {
|
|
10132
|
+
/** Discriminant: this value is JSON text. */
|
|
10133
|
+
readonly kind: "json";
|
|
10134
|
+
/** The canonical JSON text of the value. Never `undefined`, never empty. */
|
|
10135
|
+
readonly json: string;
|
|
10136
|
+
} | {
|
|
10137
|
+
/** Discriminant: this value is a byte array. */
|
|
10138
|
+
readonly kind: "bytes";
|
|
10139
|
+
/** The octets. May be empty. */
|
|
10140
|
+
readonly bytes: Uint8Array;
|
|
10141
|
+
};
|
|
10142
|
+
/**
|
|
10143
|
+
* Where `app.storage` actually puts things (`docs/architecture/14-platform-electron.md` §2).
|
|
10144
|
+
*
|
|
10145
|
+
* @remarks
|
|
10146
|
+
* **The contract.** Implementations may assume all of the following, because the `Storage` facade
|
|
10147
|
+
* guarantees them before every call:
|
|
10148
|
+
*
|
|
10149
|
+
* 1. `namespace` is a non-empty `/`-joined path of segments; each segment is 1–64 characters of
|
|
10150
|
+
* `A`–`Z`, `a`–`z`, `0`–`9`, `.`, `_`, or `-`, and no segment is `.` or `..`. A backend that maps
|
|
10151
|
+
* namespaces onto a hierarchy (directories, object stores) must encode each segment so that two
|
|
10152
|
+
* namespaces differing only in case cannot collide on a case-insensitive file system.
|
|
10153
|
+
* 2. `key` is 1–512 characters, contains no C0 or C1 control character, and is otherwise arbitrary
|
|
10154
|
+
* Unicode — including `/`, `..`, `:`, and characters Windows forbids in file names. Keys are
|
|
10155
|
+
* opaque: a backend never interprets a key's structure, and `keys(namespace, prefix)` is a plain
|
|
10156
|
+
* string-prefix filter, not a path walk.
|
|
10157
|
+
* 3. Namespaces are **scopes, not prefixes**: `get("saves", "a")` and `get("saves/coop", "a")` name
|
|
10158
|
+
* two different values, and neither appears in the other's `keys()` listing.
|
|
10159
|
+
*
|
|
10160
|
+
* Implementations must guarantee all of the following:
|
|
10161
|
+
*
|
|
10162
|
+
* 4. `get` resolves `null` for an absent key — absence is not an error.
|
|
10163
|
+
* 5. `set` replaces any existing value under the same `(namespace, key)`, whatever its kind, and
|
|
10164
|
+
* is atomic against a crash: a reader either sees the whole previous value or the whole new one,
|
|
10165
|
+
* never a partial write. `delete` on an absent key resolves without error.
|
|
10166
|
+
* 6. `keys` resolves the keys of one namespace, filtered by `prefix` when it is given, sorted
|
|
10167
|
+
* ascending with the default `Array.prototype.sort` comparison (UTF-16 code unit order). An
|
|
10168
|
+
* unknown namespace lists as `[]` rather than throwing.
|
|
10169
|
+
* 7. `clear` removes every key of one namespace and leaves other namespaces untouched. Clearing an
|
|
10170
|
+
* unknown namespace resolves without error.
|
|
10171
|
+
* 8. Every rejection is an `IgnifxError` carrying a code from the storage block: `IGX-1424` when the
|
|
10172
|
+
* host is out of quota, `IGX-1426` when a stored value cannot be read back, and `IGX-1425` for
|
|
10173
|
+
* every other backend failure, with the underlying failure as `cause`. Backends never reject with
|
|
10174
|
+
* a raw `DOMException` or a Node `SystemError`.
|
|
10175
|
+
* 9. Every method is safe to call concurrently. Two `set` calls on the same key may land in either
|
|
10176
|
+
* order, but neither may leave the store damaged.
|
|
10177
|
+
*
|
|
10178
|
+
* @example
|
|
10179
|
+
* ```ts
|
|
10180
|
+
* const backend: StorageBackend = new MemoryStorageBackend();
|
|
10181
|
+
* await backend.set("saves", "slot1", { kind: "json", json: '{"level":3}' });
|
|
10182
|
+
* await backend.keys("saves"); // ["slot1"]
|
|
10183
|
+
* ```
|
|
10184
|
+
*
|
|
10185
|
+
* @public
|
|
10186
|
+
*/
|
|
10187
|
+
interface StorageBackend {
|
|
10188
|
+
/**
|
|
10189
|
+
* A short, stable identifier for this backend — `"memory"`, `"file"`, `"indexeddb"`,
|
|
10190
|
+
* `"electron-file"`. It appears in error context so a failure names the store it came from.
|
|
10191
|
+
*/
|
|
10192
|
+
readonly name: string;
|
|
10193
|
+
/**
|
|
10194
|
+
* Reads one value.
|
|
10195
|
+
*
|
|
10196
|
+
* @param namespace - The namespace path.
|
|
10197
|
+
* @param key - The key inside that namespace.
|
|
10198
|
+
* @returns The stored value, or `null` when the namespace has no such key.
|
|
10199
|
+
*/
|
|
10200
|
+
get(namespace: string, key: string): Promise<StoredValue | null>;
|
|
10201
|
+
/**
|
|
10202
|
+
* Writes one value, replacing whatever was there.
|
|
10203
|
+
*
|
|
10204
|
+
* @param namespace - The namespace path, created on demand.
|
|
10205
|
+
* @param key - The key inside that namespace.
|
|
10206
|
+
* @param value - The JSON text or the octets to persist.
|
|
10207
|
+
* @returns A promise that settles once the value is durable.
|
|
10208
|
+
*/
|
|
10209
|
+
set(namespace: string, key: string, value: StoredValue): Promise<void>;
|
|
10210
|
+
/**
|
|
10211
|
+
* Removes one value.
|
|
10212
|
+
*
|
|
10213
|
+
* @param namespace - The namespace path.
|
|
10214
|
+
* @param key - The key inside that namespace.
|
|
10215
|
+
* @returns A promise that settles once the value is gone; removing an absent key is a no-op.
|
|
10216
|
+
*/
|
|
10217
|
+
delete(namespace: string, key: string): Promise<void>;
|
|
10218
|
+
/**
|
|
10219
|
+
* Lists the keys of one namespace.
|
|
10220
|
+
*
|
|
10221
|
+
* @param namespace - The namespace path.
|
|
10222
|
+
* @param prefix - When given, only keys that start with this string are returned.
|
|
10223
|
+
* @returns The matching keys, sorted ascending; `[]` for an unknown namespace.
|
|
10224
|
+
*/
|
|
10225
|
+
keys(namespace: string, prefix?: string): Promise<readonly string[]>;
|
|
10226
|
+
/**
|
|
10227
|
+
* Removes every value of one namespace.
|
|
10228
|
+
*
|
|
10229
|
+
* @param namespace - The namespace path.
|
|
10230
|
+
* @returns A promise that settles once the namespace is empty; an unknown namespace is a no-op.
|
|
10231
|
+
*/
|
|
10232
|
+
clear(namespace: string): Promise<void>;
|
|
10233
|
+
/**
|
|
10234
|
+
* Releases whatever the backend holds open — an IndexedDB connection, a file handle, a bridge
|
|
10235
|
+
* subscription. Called from `app.dispose()`. Disposing twice is a no-op, and a backend that holds
|
|
10236
|
+
* nothing may omit the method entirely.
|
|
10237
|
+
*/
|
|
10238
|
+
dispose?(): void;
|
|
10239
|
+
}
|
|
10240
|
+
//#endregion
|
|
10241
|
+
//#region src/storage/storage.d.ts
|
|
10242
|
+
/**
|
|
10243
|
+
* `app.storage`: the small, asynchronous key-value store a game keeps its settings, its save slots,
|
|
10244
|
+
* and its input rebindings in (`docs/architecture/14-platform-electron.md` §2).
|
|
10245
|
+
*
|
|
10246
|
+
* The facade owns policy and the backend owns persistence (`./backend.ts`). Everything a game sees
|
|
10247
|
+
* — namespaces, JSON canonicalization, `Blob` support, the error codes — lives here, once, so that
|
|
10248
|
+
* a save written under Node's memory backend in a unit test reads back identically from IndexedDB
|
|
10249
|
+
* in a browser and from the Electron bridge on a desktop build.
|
|
10250
|
+
*
|
|
10251
|
+
* ## Decisions the documents left open
|
|
10252
|
+
*
|
|
10253
|
+
* - **A namespace is a backend scope, not a key prefix.** §2 offers `namespace(name)` without
|
|
10254
|
+
* saying which. A scope is the stronger contract: `keys()` on `"saves"` cannot leak a key from
|
|
10255
|
+
* `"saves-old"`, a directory backend gets one directory per namespace for free, and clearing a
|
|
10256
|
+
* namespace is one operation rather than a scan. Nested namespaces join with `/`, so
|
|
10257
|
+
* `storage.namespace("saves").namespace("coop")` is the scope `"saves/coop"` — a *different*
|
|
10258
|
+
* scope from `"saves"`, whose keys it does not list.
|
|
10259
|
+
* - **`app.storage` itself is the namespace `"default"`.** Every backend call carries a namespace,
|
|
10260
|
+
* so the root needs a name rather than an empty string each backend would special-case.
|
|
10261
|
+
* - **`namespace(name)` is memoized.** Two calls with the same name return the same object, which
|
|
10262
|
+
* makes `app.storage.namespace("saves") === app.storage.namespace("saves")` true and keeps a
|
|
10263
|
+
* per-frame call from allocating.
|
|
10264
|
+
*/
|
|
10265
|
+
/**
|
|
10266
|
+
* The store reached as `app.storage`, and as `app.storage.namespace(name)`.
|
|
10267
|
+
*
|
|
10268
|
+
* @remarks
|
|
10269
|
+
* Values are JSON, or binary: a `Blob`, an `ArrayBuffer`, or any typed array is stored as octets
|
|
10270
|
+
* and read back as a `Uint8Array`. Numbers inside JSON values are canonicalized the way scene files
|
|
10271
|
+
* canonicalize them (`docs/architecture/06-serialization-and-scene-format.md` §2), so writing the
|
|
10272
|
+
* same state twice produces the same bytes.
|
|
10273
|
+
*
|
|
10274
|
+
* Reads and writes are asynchronous on every backend, including the in-memory one, so that game
|
|
10275
|
+
* code written against a test app keeps working on IndexedDB.
|
|
10276
|
+
*
|
|
10277
|
+
* @example
|
|
10278
|
+
* ```ts
|
|
10279
|
+
* const settings = app.storage.namespace("settings");
|
|
10280
|
+
* await settings.set("audio", { master: 0.8, music: 0.5 });
|
|
10281
|
+
* const audio = await settings.get<{ master: number; music: number }>("audio");
|
|
10282
|
+
* ```
|
|
10283
|
+
*
|
|
10284
|
+
* @public
|
|
10285
|
+
*/
|
|
10286
|
+
interface Storage {
|
|
10287
|
+
/**
|
|
10288
|
+
* Reads one value.
|
|
10289
|
+
*
|
|
10290
|
+
* @typeParam T - What the caller declares the key holds; unchecked, as for `JSON.parse`.
|
|
10291
|
+
* @param key - The key, 1–512 characters with no control characters.
|
|
10292
|
+
* @returns The value, or `null` when the key was never written.
|
|
10293
|
+
* @throws IgnifxError with code `IGX-1422` when the key is invalid, `IGX-1426` when the stored
|
|
10294
|
+
* value cannot be read back, or `IGX-1425` when the backend fails.
|
|
10295
|
+
*/
|
|
10296
|
+
get<T>(key: string): Promise<T | null>;
|
|
10297
|
+
/**
|
|
10298
|
+
* Writes one value, replacing whatever was there.
|
|
10299
|
+
*
|
|
10300
|
+
* @typeParam T - The value's type.
|
|
10301
|
+
* @param key - The key, 1–512 characters with no control characters.
|
|
10302
|
+
* @param value - A JSON value, a `Blob`, an `ArrayBuffer`, or a typed array.
|
|
10303
|
+
* @returns A promise that settles once the value is durable.
|
|
10304
|
+
* @throws IgnifxError with code `IGX-1422` when the key is invalid, `IGX-1423` when the value has
|
|
10305
|
+
* no JSON form, `IGX-1424` when the host is out of quota, or `IGX-1425` when the backend fails.
|
|
10306
|
+
*/
|
|
10307
|
+
set<T>(key: string, value: T): Promise<void>;
|
|
10308
|
+
/**
|
|
10309
|
+
* Removes one value.
|
|
10310
|
+
*
|
|
10311
|
+
* @param key - The key.
|
|
10312
|
+
* @returns A promise that settles once the value is gone. Deleting an absent key is a no-op.
|
|
10313
|
+
* @throws IgnifxError with code `IGX-1422` when the key is invalid, or `IGX-1425` when the
|
|
10314
|
+
* backend fails.
|
|
10315
|
+
*/
|
|
10316
|
+
delete(key: string): Promise<void>;
|
|
10317
|
+
/**
|
|
10318
|
+
* Lists this namespace's keys.
|
|
10319
|
+
*
|
|
10320
|
+
* @param prefix - When given, only keys that start with this string are returned.
|
|
10321
|
+
* @returns The keys, sorted ascending. Keys of nested namespaces are not included.
|
|
10322
|
+
* @throws IgnifxError with code `IGX-1425` when the backend fails.
|
|
10323
|
+
*/
|
|
10324
|
+
keys(prefix?: string): Promise<readonly string[]>;
|
|
10325
|
+
/**
|
|
10326
|
+
* Narrows to a child namespace — `"saves"`, `"settings"`, `"input-overrides"`.
|
|
10327
|
+
*
|
|
10328
|
+
* @param name - 1–64 characters of `A`–`Z`, `a`–`z`, `0`–`9`, `.`, `_`, `-`; not `.` or `..`.
|
|
10329
|
+
* @returns The child store, which shares this store's backend and sees none of its keys.
|
|
10330
|
+
* @throws IgnifxError with code `IGX-1421` when the name is not a legal namespace segment.
|
|
10331
|
+
*/
|
|
10332
|
+
namespace(name: string): Storage;
|
|
10333
|
+
}
|
|
10334
|
+
/**
|
|
10335
|
+
* The `Storage` implementation: one object per namespace, all of them sharing one backend.
|
|
10336
|
+
*
|
|
10337
|
+
* @internal
|
|
10338
|
+
*/
|
|
10339
|
+
declare class StorageImpl implements Storage {
|
|
10340
|
+
#private;
|
|
10341
|
+
/**
|
|
10342
|
+
* Builds a store.
|
|
10343
|
+
*
|
|
10344
|
+
* @param backend - Where values are persisted.
|
|
10345
|
+
* @param namespace - This store's namespace path. Defaults to `"default"`.
|
|
10346
|
+
*/
|
|
10347
|
+
constructor(backend: StorageBackend, namespace?: string);
|
|
10348
|
+
/**
|
|
10349
|
+
* This store's namespace path.
|
|
10350
|
+
*
|
|
10351
|
+
* @returns The path, `"default"` at the root and `"saves/coop"` two levels down.
|
|
10352
|
+
*/
|
|
10353
|
+
get namespacePath(): string;
|
|
10354
|
+
/**
|
|
10355
|
+
* The backend behind this store and every namespace derived from it.
|
|
10356
|
+
*
|
|
10357
|
+
* @returns The backend.
|
|
10358
|
+
*/
|
|
10359
|
+
get backend(): StorageBackend;
|
|
10360
|
+
/**
|
|
10361
|
+
* Swaps the backend of this store and of every namespace already derived from it.
|
|
10362
|
+
*
|
|
10363
|
+
* @remarks
|
|
10364
|
+
* This is how `@ignifx/electron`'s renderer extension installs the file-system backend after
|
|
10365
|
+
* `createApp` has already built the default one: the `app.storage` object a script may already
|
|
10366
|
+
* hold keeps working and starts writing through the bridge.
|
|
10367
|
+
*
|
|
10368
|
+
* @param backend - The replacement backend.
|
|
10369
|
+
*/
|
|
10370
|
+
setBackend(backend: StorageBackend): void;
|
|
10371
|
+
/**
|
|
10372
|
+
* Reads one value.
|
|
10373
|
+
*
|
|
10374
|
+
* @typeParam T - What the caller declares the key holds.
|
|
10375
|
+
* @param key - The key.
|
|
10376
|
+
* @returns The value, or `null`.
|
|
10377
|
+
*/
|
|
10378
|
+
get<T>(key: string): Promise<T | null>;
|
|
10379
|
+
/**
|
|
10380
|
+
* Writes one value.
|
|
10381
|
+
*
|
|
10382
|
+
* @typeParam T - The value's type.
|
|
10383
|
+
* @param key - The key.
|
|
10384
|
+
* @param value - The value.
|
|
10385
|
+
* @returns A promise that settles once the value is durable.
|
|
10386
|
+
*/
|
|
10387
|
+
set<T>(key: string, value: T): Promise<void>;
|
|
10388
|
+
/**
|
|
10389
|
+
* Removes one value.
|
|
10390
|
+
*
|
|
10391
|
+
* @param key - The key.
|
|
10392
|
+
* @returns A promise that settles once the value is gone.
|
|
10393
|
+
*/
|
|
10394
|
+
delete(key: string): Promise<void>;
|
|
10395
|
+
/**
|
|
10396
|
+
* Lists this namespace's keys.
|
|
10397
|
+
*
|
|
10398
|
+
* @param prefix - An optional key prefix.
|
|
10399
|
+
* @returns The keys, sorted ascending.
|
|
10400
|
+
*/
|
|
10401
|
+
keys(prefix?: string): Promise<readonly string[]>;
|
|
10402
|
+
/**
|
|
10403
|
+
* Narrows to a child namespace.
|
|
10404
|
+
*
|
|
10405
|
+
* @param name - The child segment.
|
|
10406
|
+
* @returns The child store.
|
|
10407
|
+
*/
|
|
10408
|
+
namespace(name: string): Storage;
|
|
10409
|
+
}
|
|
10410
|
+
/**
|
|
10411
|
+
* Reaches the engine-owned half of a `Storage`, the way `rendererInternals` does for the
|
|
10412
|
+
* renderer. `@ignifx/electron` uses it to install its bridge backend after `createApp`.
|
|
10413
|
+
*
|
|
10414
|
+
* @param storage - The store, normally `app.storage`.
|
|
10415
|
+
* @returns The implementation.
|
|
10416
|
+
* @throws IgnifxError with code `IGX-0702` when the object was not created by this copy of
|
|
10417
|
+
* `@ignifx/core`.
|
|
10418
|
+
*
|
|
10419
|
+
* @example
|
|
10420
|
+
* ```ts
|
|
10421
|
+
* storageInternals(app.storage).setBackend(new ElectronFileStorageBackend(host));
|
|
10422
|
+
* ```
|
|
10423
|
+
*
|
|
10424
|
+
* @internal
|
|
10425
|
+
*/
|
|
10426
|
+
export declare function storageInternals(storage: Storage): StorageImpl;
|
|
10427
|
+
//#endregion
|
|
10428
|
+
//#region src/tween/channel.d.ts
|
|
10429
|
+
/**
|
|
10430
|
+
* One tweened property: what kind of value it holds, where it started, where it is going, and how
|
|
10431
|
+
* to write it back (`docs/architecture/12-3d-toolkit.md` §4).
|
|
10432
|
+
*
|
|
10433
|
+
* A channel allocates its two endpoint buffers once, when the tween is created, and never again —
|
|
10434
|
+
* which is what keeps `Tweens.advance` allocation-free on the per-frame path (coding standards §7).
|
|
10435
|
+
*/
|
|
10436
|
+
/**
|
|
10437
|
+
* The four value shapes a tween can interpolate.
|
|
10438
|
+
*
|
|
10439
|
+
* @public
|
|
10440
|
+
*/
|
|
10441
|
+
export declare const TWEEN_VALUE_KINDS: readonly ["number", "vec2", "vec3", "quat"];
|
|
10442
|
+
/**
|
|
10443
|
+
* The union of {@link TWEEN_VALUE_KINDS}.
|
|
10444
|
+
*
|
|
10445
|
+
* @public
|
|
10446
|
+
*/
|
|
10447
|
+
type TweenValueKind = (typeof TWEEN_VALUE_KINDS)[number];
|
|
10448
|
+
/**
|
|
10449
|
+
* A value a tween knows how to interpolate: a plain number, or an object with `x`/`y`(`/z`(`/w`))
|
|
10450
|
+
* components.
|
|
10451
|
+
*
|
|
10452
|
+
* @public
|
|
10453
|
+
*/
|
|
10454
|
+
type TweenableValue = number | Vec2Like | Vec3Like | QuatLike;
|
|
10455
|
+
//#endregion
|
|
10456
|
+
//#region src/tween/easing.d.ts
|
|
10457
|
+
/**
|
|
10458
|
+
* A curve mapping normalized time to a normalized value. Custom curves have this shape.
|
|
10459
|
+
*
|
|
10460
|
+
* @param t - Normalized time in `[0, 1]`.
|
|
10461
|
+
* @returns The eased value; `0` at `t = 0` and `1` at `t = 1`, free to overshoot in between.
|
|
10462
|
+
*
|
|
10463
|
+
* @public
|
|
10464
|
+
*/
|
|
10465
|
+
type EasingFunction = (t: number) => number;
|
|
10466
|
+
/**
|
|
10467
|
+
* Every named easing curve, keyed by the name `TweenOptions.ease` accepts.
|
|
10468
|
+
*
|
|
10469
|
+
* @example
|
|
10470
|
+
* ```ts
|
|
10471
|
+
* const halfway = EASINGS.cubicInOut(0.5); // 0.5
|
|
10472
|
+
* ```
|
|
10473
|
+
*
|
|
10474
|
+
* @public
|
|
10475
|
+
*/
|
|
10476
|
+
export declare const EASINGS: Readonly<Record<string, EasingFunction>>;
|
|
10477
|
+
/**
|
|
10478
|
+
* The names {@link EASINGS} declares, in table order (coding standards §5.2 — an `as const` table
|
|
10479
|
+
* and the union derived from it, never an enum).
|
|
10480
|
+
*
|
|
10481
|
+
* @public
|
|
10482
|
+
*/
|
|
10483
|
+
export declare const EASING_NAMES: readonly ["linear", "quadIn", "quadOut", "quadInOut", "cubicIn", "cubicOut", "cubicInOut", "sineInOut", "backOut", "elasticOut", "bounceOut"];
|
|
10484
|
+
/**
|
|
10485
|
+
* The union of the named easing curves.
|
|
10486
|
+
*
|
|
10487
|
+
* @public
|
|
10488
|
+
*/
|
|
10489
|
+
type EasingName = (typeof EASING_NAMES)[number];
|
|
10490
|
+
/**
|
|
10491
|
+
* Resolves an `ease` option to the function a tween will call.
|
|
10492
|
+
*
|
|
10493
|
+
* @param ease - A name from {@link EASING_NAMES}, a custom curve, or `undefined` for `linear`.
|
|
10494
|
+
* @returns The curve, or `null` when the name is not one the table declares.
|
|
10495
|
+
*
|
|
10496
|
+
* @example
|
|
10497
|
+
* ```ts
|
|
10498
|
+
* const curve = resolveEase("cubicOut");
|
|
10499
|
+
* ```
|
|
10500
|
+
*
|
|
10501
|
+
* @public
|
|
10502
|
+
*/
|
|
10503
|
+
export declare function resolveEase(ease: EasingName | EasingFunction | undefined): EasingFunction | null;
|
|
10504
|
+
//#endregion
|
|
10505
|
+
//#region src/tween/tween.d.ts
|
|
10506
|
+
/**
|
|
10507
|
+
* A running tween and the handle a game holds on to (`docs/architecture/12-3d-toolkit.md` §4).
|
|
10508
|
+
*
|
|
10509
|
+
* A tween is created by `app.tweens.to(...)`, advanced once per frame in `PostUpdate`, and dies
|
|
10510
|
+
* with the app. Everything it needs is allocated in the constructor: advancing one costs a few
|
|
10511
|
+
* multiplications per channel and nothing on the heap (coding standards §7).
|
|
10512
|
+
*/
|
|
10513
|
+
/**
|
|
10514
|
+
* `loop: -1` means "repeat until stopped".
|
|
10515
|
+
*
|
|
10516
|
+
* @public
|
|
10517
|
+
*/
|
|
10518
|
+
export declare const TWEEN_LOOP_FOREVER = -1;
|
|
10519
|
+
/**
|
|
10520
|
+
* What `app.tweens.to(...)` accepts.
|
|
10521
|
+
*
|
|
10522
|
+
* @public
|
|
10523
|
+
*/
|
|
10524
|
+
interface TweenOptions {
|
|
10525
|
+
/** How long one cycle takes, in seconds. Must be finite and greater than zero. */
|
|
10526
|
+
readonly duration: number;
|
|
10527
|
+
/** The curve, by name or as a custom `(t) => number`. Defaults to `"linear"`. */
|
|
10528
|
+
readonly ease?: EasingName | EasingFunction;
|
|
10529
|
+
/** How long to wait before the first cycle starts, in seconds. Defaults to `0`. */
|
|
10530
|
+
readonly delay?: number;
|
|
10531
|
+
/** How many extra cycles to run; `-1` repeats forever. Defaults to `0` — one cycle. */
|
|
10532
|
+
readonly loop?: number;
|
|
10533
|
+
/** Whether every other cycle plays backwards. Defaults to `false`. */
|
|
10534
|
+
readonly yoyo?: boolean;
|
|
10535
|
+
/**
|
|
10536
|
+
* Whether the tween keeps running while `app.pause()` holds. A tween that does advances on
|
|
10537
|
+
* `time.unscaledDeltaTime`; every other tween advances on `time.deltaTime` and is frozen by a
|
|
10538
|
+
* pause. Defaults to `false`.
|
|
10539
|
+
*/
|
|
10540
|
+
readonly updateWhenPaused?: boolean;
|
|
10541
|
+
/** Called once when the tween finishes on its own or through {@link Tween.complete}. */
|
|
10542
|
+
readonly onComplete?: () => void;
|
|
10543
|
+
}
|
|
10544
|
+
/**
|
|
10545
|
+
* A tween in flight.
|
|
10546
|
+
*
|
|
10547
|
+
* @remarks
|
|
10548
|
+
* Endpoints are latched when the delay elapses, not when the tween is created, so two tweens queued
|
|
10549
|
+
* on one property in the same frame chain rather than fight.
|
|
10550
|
+
*
|
|
10551
|
+
* @example
|
|
10552
|
+
* ```ts
|
|
10553
|
+
* const tween = app.tweens.to(entity.transform, { position: { x: 5, y: 0, z: 0 } }, {
|
|
10554
|
+
* duration: 1,
|
|
10555
|
+
* ease: "cubicInOut",
|
|
10556
|
+
* });
|
|
10557
|
+
* tween.onComplete.connect(() => app.log.info("arrived"));
|
|
10558
|
+
* ```
|
|
10559
|
+
*
|
|
10560
|
+
* @public
|
|
10561
|
+
*/
|
|
10562
|
+
export declare class Tween {
|
|
10563
|
+
#private;
|
|
10564
|
+
/** Fires once when the tween finishes, with the tween itself. Never fires after `stop`. */
|
|
10565
|
+
readonly onComplete: Signal<Tween>;
|
|
10566
|
+
/** Whether the tween runs while the app is paused. */
|
|
10567
|
+
readonly updateWhenPaused: boolean;
|
|
10568
|
+
/**
|
|
10569
|
+
* Builds a tween. Games call `app.tweens.to(...)` instead.
|
|
10570
|
+
*
|
|
10571
|
+
* @param target - The object whose fields move.
|
|
10572
|
+
* @param props - The destination value of each field.
|
|
10573
|
+
* @param options - Duration, curve, delay, looping, and the completion callback.
|
|
10574
|
+
* @throws IgnifxError with code `IGX-0109` when an option is outside its domain.
|
|
10575
|
+
* @throws IgnifxError with code `IGX-0110` when a named field is not tweenable.
|
|
10576
|
+
*
|
|
10577
|
+
* @internal
|
|
10578
|
+
*/
|
|
10579
|
+
constructor(target: object, props: Readonly<Record<string, TweenableValue>>, options: TweenOptions);
|
|
10580
|
+
/**
|
|
10581
|
+
* The object being tweened, for `stopAllOf`.
|
|
10582
|
+
*
|
|
10583
|
+
* @returns The object being tweened, for `stopAllOf`.
|
|
10584
|
+
*/
|
|
10585
|
+
get target(): object;
|
|
10586
|
+
/**
|
|
10587
|
+
* How far through the current cycle the tween is, in `[0, 1]`, after the yoyo reversal and before
|
|
10588
|
+
* the easing curve.
|
|
10589
|
+
*
|
|
10590
|
+
* @returns The normalized cycle time.
|
|
10591
|
+
*/
|
|
10592
|
+
get progress(): number;
|
|
10593
|
+
/**
|
|
10594
|
+
* Whether the tween is still advancing.
|
|
10595
|
+
*
|
|
10596
|
+
* @returns Whether the tween is still advancing.
|
|
10597
|
+
*/
|
|
10598
|
+
get isPlaying(): boolean;
|
|
10599
|
+
/**
|
|
10600
|
+
* Whether `pause` is holding the tween.
|
|
10601
|
+
*
|
|
10602
|
+
* @returns Whether `pause` is holding the tween.
|
|
10603
|
+
*/
|
|
10604
|
+
get isPaused(): boolean;
|
|
10605
|
+
/**
|
|
10606
|
+
* Whether the tween has finished or been stopped and will never advance again.
|
|
10607
|
+
*
|
|
10608
|
+
* @returns Whether the tween has finished or been stopped and will never advance again.
|
|
10609
|
+
*/
|
|
10610
|
+
get isDone(): boolean;
|
|
10611
|
+
/** Holds the tween where it is; `resume` picks it back up. */
|
|
10612
|
+
pause(): void;
|
|
10613
|
+
/** Releases a `pause`. */
|
|
10614
|
+
resume(): void;
|
|
10615
|
+
/**
|
|
10616
|
+
* Ends the tween where it stands, leaving the target at its current value. `onComplete` does not
|
|
10617
|
+
* fire.
|
|
10618
|
+
*/
|
|
10619
|
+
stop(): void;
|
|
10620
|
+
/**
|
|
10621
|
+
* Jumps the target to the tween's end value, then finishes it. `onComplete` fires, exactly as it
|
|
10622
|
+
* would have on the last frame.
|
|
10623
|
+
*/
|
|
10624
|
+
complete(): void;
|
|
10625
|
+
/**
|
|
10626
|
+
* Advances the tween by one frame's worth of time.
|
|
10627
|
+
*
|
|
10628
|
+
* @param dt - Seconds to advance by, already chosen for this tween's `updateWhenPaused`.
|
|
10629
|
+
* @returns `true` when the tween is done and should leave the list.
|
|
10630
|
+
*
|
|
10631
|
+
* @internal
|
|
10632
|
+
*/
|
|
10633
|
+
advance(dt: number): boolean;
|
|
10634
|
+
}
|
|
10635
|
+
//#endregion
|
|
10636
|
+
//#region src/tween/tweens.d.ts
|
|
10637
|
+
/**
|
|
10638
|
+
* `app.tweens` (`docs/architecture/12-3d-toolkit.md` §4): the app-wide tween list, advanced once
|
|
10639
|
+
* per frame in `PostUpdate` on ignifx's own clock.
|
|
10640
|
+
*
|
|
10641
|
+
* Tweens live in core rather than in a toolkit because both toolkits use them, and because a tween
|
|
10642
|
+
* is a clock consumer like any other: it obeys `time.timeScale`, it is frozen by `app.pause()`
|
|
10643
|
+
* unless it opted out, and it dies when the app is disposed (ADR-0003).
|
|
10644
|
+
*/
|
|
10645
|
+
/**
|
|
10646
|
+
* The destination value the tween should reach for one field, narrowed to the field's own shape.
|
|
10647
|
+
*
|
|
10648
|
+
* @remarks
|
|
10649
|
+
* `QuatLike` is tested before `Vec3Like` because a quaternion satisfies both: `{ x, y, z, w }` is
|
|
10650
|
+
* assignable to `{ x, y, z }`.
|
|
10651
|
+
*
|
|
10652
|
+
* @typeParam V - The field's declared type.
|
|
10653
|
+
*
|
|
10654
|
+
* @public
|
|
10655
|
+
*/
|
|
10656
|
+
type TweenTargetValue<V> = V extends number ? number : V extends QuatLike ? QuatLike : V extends Vec3Like ? Vec3Like : V extends Vec2Like ? Vec2Like : never;
|
|
10657
|
+
/**
|
|
10658
|
+
* The destinations `app.tweens.to` accepts for a target: every numeric, `Vec2`, `Vec3`, or `Quat`
|
|
10659
|
+
* field of `T`, each one optional.
|
|
10660
|
+
*
|
|
10661
|
+
* @typeParam T - The target object's type.
|
|
10662
|
+
*
|
|
10663
|
+
* @example
|
|
10664
|
+
* ```ts
|
|
10665
|
+
* const props: TweenProps<Transform> = { position: { x: 1, y: 2, z: 3 } };
|
|
10666
|
+
* ```
|
|
10667
|
+
*
|
|
10668
|
+
* @public
|
|
10669
|
+
*/
|
|
10670
|
+
type TweenProps<T> = { readonly [K in keyof T as T[K] extends TweenableValue ? K : never]?: TweenTargetValue<T[K]>; };
|
|
10671
|
+
/**
|
|
10672
|
+
* The app-wide tween list.
|
|
10673
|
+
*
|
|
10674
|
+
* @example
|
|
10675
|
+
* ```ts
|
|
10676
|
+
* app.tweens.to(entity.transform, { position: { x: 0, y: 3, z: 0 } }, {
|
|
10677
|
+
* duration: 0.6,
|
|
10678
|
+
* ease: "backOut",
|
|
10679
|
+
* yoyo: true,
|
|
10680
|
+
* loop: 1,
|
|
10681
|
+
* });
|
|
10682
|
+
* ```
|
|
10683
|
+
*
|
|
10684
|
+
* @public
|
|
10685
|
+
*/
|
|
10686
|
+
interface Tweens {
|
|
10687
|
+
/** How many tweens are alive. */
|
|
10688
|
+
readonly count: number;
|
|
10689
|
+
/**
|
|
10690
|
+
* Starts a tween towards `props` and returns the handle.
|
|
10691
|
+
*
|
|
10692
|
+
* @typeParam T - The target object's type.
|
|
10693
|
+
* @param target - The object whose fields move. Any object with numeric or vector fields works.
|
|
10694
|
+
* @param props - The destination value of each field to move.
|
|
10695
|
+
* @param options - Duration, curve, delay, looping, and the completion callback.
|
|
10696
|
+
* @returns The running tween.
|
|
10697
|
+
* @throws IgnifxError with code `IGX-0109` when an option is outside its domain.
|
|
10698
|
+
* @throws IgnifxError with code `IGX-0110` when a named field is not tweenable.
|
|
10699
|
+
*/
|
|
10700
|
+
to<T extends object>(target: T, props: TweenProps<T>, options: TweenOptions): Tween;
|
|
10701
|
+
/** Stops every tween, without firing any `onComplete`. */
|
|
10702
|
+
stopAll(): void;
|
|
10703
|
+
/**
|
|
10704
|
+
* Stops every tween that moves one object.
|
|
10705
|
+
*
|
|
10706
|
+
* @param target - The object.
|
|
10707
|
+
* @returns How many tweens were stopped.
|
|
10708
|
+
*/
|
|
10709
|
+
stopAllOf(target: object): number;
|
|
10710
|
+
}
|
|
10711
|
+
//#endregion
|
|
10712
|
+
//#region src/app/types.d.ts
|
|
10713
|
+
/**
|
|
10714
|
+
* The contracts the kernel and the runtime agree on: frame phases, the clock, systems, extensions,
|
|
10715
|
+
* services, coroutines, and the `App` surface a script sees through `this.app`
|
|
10716
|
+
* (`docs/architecture/01-lifecycle-and-time.md`, `03-scripting-and-components.md` §6–§7,
|
|
10717
|
+
* `04-extensions.md` §1).
|
|
10718
|
+
*
|
|
10719
|
+
* The module declares types and two frozen constant tables only — no classes and no behaviour — so
|
|
10720
|
+
* that the scene graph and the runtime can be written against it independently.
|
|
10721
|
+
*/
|
|
10722
|
+
/**
|
|
10723
|
+
* The ordered frame phases (`docs/architecture/01-lifecycle-and-time.md` §3). The ordinals are the
|
|
10724
|
+
* order the frame function walks them in, and they index the per-phase CPU timings in
|
|
10725
|
+
* `FrameSample.cpuMs`.
|
|
10726
|
+
*
|
|
10727
|
+
* @remarks
|
|
10728
|
+
* `EndOfFrame` is ordinal `0` because the work it carries is drained at the *top* of the next
|
|
10729
|
+
* frame, before the clock advances; the name describes when the work was queued, the ordinal
|
|
10730
|
+
* describes when it runs.
|
|
10731
|
+
*
|
|
10732
|
+
* @example
|
|
10733
|
+
* ```ts
|
|
10734
|
+
* ctx.registerSystem(new SpriteSyncSystem(), { phase: Phase.PreRender, order: 100 });
|
|
10735
|
+
* ```
|
|
10736
|
+
*
|
|
10737
|
+
* @public
|
|
10738
|
+
*/
|
|
10739
|
+
export declare const Phase: {
|
|
10740
|
+
/** Deferred signal deliveries and end-of-frame systems, drained at the start of the next frame. */
|
|
10741
|
+
readonly EndOfFrame: 0;
|
|
10742
|
+
/** Input polling and asset delivery, before any script callback. */
|
|
10743
|
+
readonly PreUpdate: 1;
|
|
10744
|
+
/** The fixed-timestep simulation loop: `fixedUpdate`, physics, collision dispatch. */
|
|
10745
|
+
readonly FixedUpdate: 2;
|
|
10746
|
+
/** `update` on every enabled script, then coroutine resumption. */
|
|
10747
|
+
readonly Update: 3;
|
|
10748
|
+
/** Animation, state machines, and tweens, between `update` and `lateUpdate`. */
|
|
10749
|
+
readonly PostUpdate: 4;
|
|
10750
|
+
/** Render synchronisation: interpolation, sprite and camera sync, audio, diagnostics. */
|
|
10751
|
+
readonly PreRender: 5;
|
|
10752
|
+
};
|
|
10753
|
+
/**
|
|
10754
|
+
* The union of the frame phases.
|
|
10755
|
+
*
|
|
10756
|
+
* @public
|
|
10757
|
+
*/
|
|
10758
|
+
export type Phase = (typeof Phase)[keyof typeof Phase];
|
|
10759
|
+
/**
|
|
10760
|
+
* Every phase in frame order, for loops that walk them all.
|
|
10761
|
+
*
|
|
10762
|
+
* @public
|
|
10763
|
+
*/
|
|
10764
|
+
export declare const PHASES: readonly Phase[];
|
|
10765
|
+
/**
|
|
10766
|
+
* The display name of each phase, indexed by its ordinal. Used by diagnostics and error messages.
|
|
10767
|
+
*
|
|
10768
|
+
* @public
|
|
10769
|
+
*/
|
|
10770
|
+
export declare const PHASE_NAMES: readonly string[];
|
|
10771
|
+
/**
|
|
10772
|
+
* The clock reached as `app.time` (`docs/architecture/01-lifecycle-and-time.md` §2). Every value is
|
|
10773
|
+
* in **seconds** unless its name ends in `Ms`.
|
|
9611
10774
|
*
|
|
9612
10775
|
* @example
|
|
9613
10776
|
* ```ts
|
|
@@ -9662,7 +10825,11 @@ interface SystemContext {
|
|
|
9662
10825
|
readonly time: Time;
|
|
9663
10826
|
/** The phase currently running. */
|
|
9664
10827
|
readonly phase: Phase;
|
|
9665
|
-
/**
|
|
10828
|
+
/**
|
|
10829
|
+
* Seconds elapsed: `time.deltaTime`, or `time.fixedDeltaTime` inside the fixed loop. Systems run
|
|
10830
|
+
* while the app is paused and `dt` is **not** zeroed then — only scripts are filtered by
|
|
10831
|
+
* `updateWhenPaused` — so a system that animates checks `time.paused` itself.
|
|
10832
|
+
*/
|
|
9666
10833
|
readonly dt: number;
|
|
9667
10834
|
}
|
|
9668
10835
|
/**
|
|
@@ -9855,7 +11022,7 @@ interface AppSettings {
|
|
|
9855
11022
|
* @example
|
|
9856
11023
|
* ```ts
|
|
9857
11024
|
* app.onError.connect((report) => {
|
|
9858
|
-
* app.log.error(
|
|
11025
|
+
* app.log.error(`${report.source} callback threw on ${report.entity?.name ?? "-"}`, report.error);
|
|
9859
11026
|
* });
|
|
9860
11027
|
* ```
|
|
9861
11028
|
*
|
|
@@ -10062,14 +11229,31 @@ interface App {
|
|
|
10062
11229
|
/** The `@ignifx/core` version this app was built from. */
|
|
10063
11230
|
readonly version: string;
|
|
10064
11231
|
/**
|
|
10065
|
-
* Where the app is running
|
|
10066
|
-
* `
|
|
11232
|
+
* Where the app is running, what it is running on, and what its WebGPU adapter offers
|
|
11233
|
+
* (`docs/architecture/14-platform-electron.md` §1).
|
|
10067
11234
|
*/
|
|
10068
11235
|
readonly platform: PlatformInfo;
|
|
11236
|
+
/**
|
|
11237
|
+
* The asynchronous key-value store settings, save games, and input rebindings live in
|
|
11238
|
+
* (`docs/architecture/14-platform-electron.md` §2). The backend is chosen from
|
|
11239
|
+
* {@link PlatformInfo.kind} — IndexedDB in a browser, memory under Node — unless `createApp` was
|
|
11240
|
+
* given one.
|
|
11241
|
+
*/
|
|
11242
|
+
readonly storage: Storage;
|
|
10069
11243
|
/** Unstable Babylon Lite escape hatch (`docs/architecture/00-overview.md` §3). */
|
|
10070
11244
|
readonly lite: AppLiteHandles;
|
|
10071
11245
|
/** The coroutine scheduler. */
|
|
10072
11246
|
readonly coroutines: CoroutineHost;
|
|
11247
|
+
/**
|
|
11248
|
+
* The app-wide tween list (`docs/architecture/12-3d-toolkit.md` §4), advanced in `PostUpdate` on
|
|
11249
|
+
* ignifx's clock and used by both toolkits.
|
|
11250
|
+
*/
|
|
11251
|
+
readonly tweens: Tweens;
|
|
11252
|
+
/**
|
|
11253
|
+
* Script and scene hot reload (`docs/architecture/15-devtools-and-diagnostics.md` §5). The Vite
|
|
11254
|
+
* plugin's HMR client drives it in development; it works headlessly with no bundler at all.
|
|
11255
|
+
*/
|
|
11256
|
+
readonly hotReload: HotReloadHost;
|
|
10073
11257
|
/**
|
|
10074
11258
|
* Makes component `typeId`s known to the serializer and the inspector
|
|
10075
11259
|
* (`docs/architecture/03-scripting-and-components.md` §4).
|
|
@@ -10390,6 +11574,42 @@ interface Extension {
|
|
|
10390
11574
|
*/
|
|
10391
11575
|
type SettingsInput = Readonly<Record<string, unknown>>;
|
|
10392
11576
|
//#endregion
|
|
11577
|
+
//#region src/storage/node/file-backend.d.ts
|
|
11578
|
+
/**
|
|
11579
|
+
* Options accepted by {@link createFileStorageBackend}.
|
|
11580
|
+
*
|
|
11581
|
+
* @public
|
|
11582
|
+
*/
|
|
11583
|
+
interface FileStorageOptions {
|
|
11584
|
+
/**
|
|
11585
|
+
* The root directory. It is created on first write, together with every namespace directory
|
|
11586
|
+
* under it. Under Electron this is `app.getPath("userData")`; in a test it is a temporary
|
|
11587
|
+
* directory.
|
|
11588
|
+
*/
|
|
11589
|
+
readonly directory: string;
|
|
11590
|
+
}
|
|
11591
|
+
/**
|
|
11592
|
+
* Builds a storage backend over a directory (`docs/architecture/14-platform-electron.md` §5).
|
|
11593
|
+
*
|
|
11594
|
+
* @remarks
|
|
11595
|
+
* Node only: the factory loads `node:fs/promises` and rejects on a host that has none. It is what
|
|
11596
|
+
* `createApp({ storage: { directory } })` calls, and it is exported so that tooling — `ignifx bake`,
|
|
11597
|
+
* a future authoritative server — can build one without an app.
|
|
11598
|
+
*
|
|
11599
|
+
* @param options - The root directory.
|
|
11600
|
+
* @returns The backend.
|
|
11601
|
+
* @throws IgnifxError with code `IGX-1425` when the host exposes no `node:fs/promises`.
|
|
11602
|
+
*
|
|
11603
|
+
* @example
|
|
11604
|
+
* ```ts
|
|
11605
|
+
* const app = await createApp({ headless: true, storage: { directory: "./.saves" } });
|
|
11606
|
+
* await app.storage.namespace("saves").set("slot1", { level: 3 });
|
|
11607
|
+
* ```
|
|
11608
|
+
*
|
|
11609
|
+
* @public
|
|
11610
|
+
*/
|
|
11611
|
+
export declare function createFileStorageBackend(options: FileStorageOptions): Promise<StorageBackend>;
|
|
11612
|
+
//#endregion
|
|
10393
11613
|
//#region src/time/clock.d.ts
|
|
10394
11614
|
/**
|
|
10395
11615
|
* The wall clock the runtime reads (`docs/architecture/01-lifecycle-and-time.md` §2, §8). It is a
|
|
@@ -10504,10 +11724,17 @@ interface CreateAppOptions {
|
|
|
10504
11724
|
readonly extensions?: readonly Extension[];
|
|
10505
11725
|
/**
|
|
10506
11726
|
* Project settings, as `ignifx.config.ts` would supply them
|
|
10507
|
-
* (`docs/architecture/04-extensions.md` §5).
|
|
10508
|
-
*
|
|
11727
|
+
* (`docs/architecture/04-extensions.md` §5). `@ignifx/vite-plugin` injects the resolved
|
|
11728
|
+
* `ignifx.config.ts` as the `import.meta.env.IGNIFX_CONFIG` literal, which a game passes straight
|
|
11729
|
+
* in here; tests and Electron tooling pass their own object instead.
|
|
10509
11730
|
*/
|
|
10510
11731
|
readonly settings?: SettingsInput;
|
|
11732
|
+
/**
|
|
11733
|
+
* Where `app.storage` puts things (`docs/architecture/14-platform-electron.md` §2). Pass a
|
|
11734
|
+
* {@link StorageBackend} to install one, or `{ directory }` to write a directory tree under Node.
|
|
11735
|
+
* Defaults to IndexedDB in a browser and to an in-memory store everywhere else.
|
|
11736
|
+
*/
|
|
11737
|
+
readonly storage?: StorageBackend | FileStorageOptions;
|
|
10511
11738
|
/**
|
|
10512
11739
|
* The asset service's construction options
|
|
10513
11740
|
* (`docs/architecture/05-assets-and-loading.md` §7). The manifest normally arrives from
|
|
@@ -10531,8 +11758,17 @@ interface CreateAppOptions {
|
|
|
10531
11758
|
readonly clock?: Clock;
|
|
10532
11759
|
/**
|
|
10533
11760
|
* `"development"` turns on per-phase CPU timings, full error messages, and the strict half of
|
|
10534
|
-
* every rule `04-extensions.md` §2 relaxes in production.
|
|
10535
|
-
*
|
|
11761
|
+
* every rule `04-extensions.md` §2 relaxes in production.
|
|
11762
|
+
*
|
|
11763
|
+
* @remarks
|
|
11764
|
+
* Defaults to `"development"`, and **nothing else ever changes it**: neither `@ignifx/vite-plugin`
|
|
11765
|
+
* nor a template overrides it, so a production `vite build` of a game that passes no `mode` runs
|
|
11766
|
+
* in development mode — full error text, `performance.mark`/`measure` entries, and
|
|
11767
|
+
* `FrameSample.cpuMs` filled in. That is deliberate: the mode decides how the *engine* reports
|
|
11768
|
+
* itself, and only the game knows whether its shipped build wants that. Pass it from the bundler's
|
|
11769
|
+
* own flag to opt out — `mode: import.meta.env.PROD ? "production" : "development"`.
|
|
11770
|
+
*
|
|
11771
|
+
* @defaultValue `"development"`
|
|
10536
11772
|
*/
|
|
10537
11773
|
readonly mode?: ErrorFormatMode;
|
|
10538
11774
|
/** Where `app.log` writes. Defaults to the console sink. */
|
|
@@ -10542,6 +11778,12 @@ interface CreateAppOptions {
|
|
|
10542
11778
|
* prints nothing at startup; pass `"debug"` to see the kernel's own diagnostics.
|
|
10543
11779
|
*/
|
|
10544
11780
|
readonly logLevel?: LogThreshold;
|
|
11781
|
+
/**
|
|
11782
|
+
* Script and scene hot reload (`docs/architecture/15-devtools-and-diagnostics.md` §5).
|
|
11783
|
+
* `app.hotReload.apply` always works; the only thing to configure is whether a changed scene file
|
|
11784
|
+
* rebuilds the live instances built from it.
|
|
11785
|
+
*/
|
|
11786
|
+
readonly hotReload?: HotReloadOptions;
|
|
10545
11787
|
}
|
|
10546
11788
|
/**
|
|
10547
11789
|
* Creates a game (`docs/architecture/00-overview.md` §1, `04-extensions.md` §2).
|
|
@@ -10839,7 +12081,8 @@ export declare const coreExtension: (options?: void) => Extension;
|
|
|
10839
12081
|
*
|
|
10840
12082
|
* @typeParam O - The options object the factory accepts. Defaults to `void` for an extension that
|
|
10841
12083
|
* takes none.
|
|
10842
|
-
* @param factory - Builds the extension descriptor from its options
|
|
12084
|
+
* @param factory - Builds the extension descriptor from its options, which are `undefined` when the
|
|
12085
|
+
* game called the factory without an argument — default them (`(options = {})`) or read them as optional.
|
|
10843
12086
|
* @returns A factory that may be called with no argument, in which case the options are `undefined`.
|
|
10844
12087
|
*
|
|
10845
12088
|
* @example
|
|
@@ -10858,7 +12101,7 @@ export declare const coreExtension: (options?: void) => Extension;
|
|
|
10858
12101
|
*
|
|
10859
12102
|
* @public
|
|
10860
12103
|
*/
|
|
10861
|
-
export declare function defineExtension<O = void>(factory: (options: O) => Extension): (options?: O) => Extension;
|
|
12104
|
+
export declare function defineExtension<O = void>(factory: (options: O | undefined) => Extension): (options?: O) => Extension;
|
|
10862
12105
|
//#endregion
|
|
10863
12106
|
//#region src/ids/random-source.d.ts
|
|
10864
12107
|
/**
|
|
@@ -11103,7 +12346,7 @@ type LiteShadowGenerator = ShadowGenerator;
|
|
|
11103
12346
|
/**
|
|
11104
12347
|
* The shadow techniques Lite offers, in the order `docs/architecture/07-rendering.md` §2.2 lists them.
|
|
11105
12348
|
*
|
|
11106
|
-
* @
|
|
12349
|
+
* @public
|
|
11107
12350
|
*/
|
|
11108
12351
|
export declare const SHADOW_TECHNIQUES: readonly ["esm", "pcf", "csm"];
|
|
11109
12352
|
//#endregion
|
|
@@ -12025,7 +13268,39 @@ export declare class Vec4 {
|
|
|
12025
13268
|
* `setSceneImageProcessing` is **async** (`index.d.ts` 10917) because tone mapping is baked into
|
|
12026
13269
|
* the PBR shaders at `registerScene` time; changing it recompiles the affected pipelines
|
|
12027
13270
|
* (`rebuildScenePbrPipelines`). Setting exposure or contrast alone still goes through the same
|
|
12028
|
-
* call.
|
|
13271
|
+
* call. Note that `loadEnvironment` **overwrites** all three (`toneMappingEnabled = true`,
|
|
13272
|
+
* `exposure = 0.8`, `contrast = 1.2`) as a side effect of installing an environment, which is why
|
|
13273
|
+
* the `Environment` component re-applies its own image processing after every install.
|
|
13274
|
+
*
|
|
13275
|
+
* ## Swapping the installed environment: `scene._envTextures`
|
|
13276
|
+
*
|
|
13277
|
+
* Lite 1.27.0 declares **no** public way to replace, clear, or read back a registered scene's
|
|
13278
|
+
* environment. `index.d.ts` has no `scene.environmentTexture`, no `unloadEnvironment`, and no
|
|
13279
|
+
* setter of any kind; `loadEnvironment` is the only installer and it fetches, decodes, and uploads
|
|
13280
|
+
* a fresh cube map every call. What it actually installs is one field —
|
|
13281
|
+
* `scene._envTextures = textures` (`lib/_chunks/env-helpers-CRI1i-A3.js` 24, and the same line in
|
|
13282
|
+
* `lib/loader-hdr/load-hdr.js` 23, `lib/loader-env/load-dds-env.js` 177 and
|
|
13283
|
+
* `lib/loader-gltf/gltf-ext-lights-image-based.js` 65) — and every consumer reads that field:
|
|
13284
|
+
*
|
|
13285
|
+
* - the PBR group builder, which bakes the cube view and sampler into each material's bind group
|
|
13286
|
+
* (`lib/material/pbr/pbr-material.js` 12 → `lib/material/pbr/pbr-renderable.js`);
|
|
13287
|
+
* - the scene-uniform packer, for `lodGenerationScale` (`lib/frame-graph/scene-uniforms-pack.js` 21);
|
|
13288
|
+
* - the env UBO contributor, for the diffuse spherical harmonics (`lib/scene/scene-ubo-extras.js` 24);
|
|
13289
|
+
* - the blur contributor, for `lodGenerationOffset` (`lib/scene/set-environment-blur.js` 8);
|
|
13290
|
+
* - the render task's scene-UBO cache key, which is keyed on the **object identity** of the field
|
|
13291
|
+
* (`lib/frame-graph/render-task.js` 358), so a new object re-uploads the harmonics by itself.
|
|
13292
|
+
*
|
|
13293
|
+
* Lite's own device-lost recovery replaces the field exactly this way
|
|
13294
|
+
* (`lib/loader-env/environment-recovery.js` 16 and 38), so {@link installSceneEnvironment} writes it
|
|
13295
|
+
* too. Bind groups are the one consumer that does *not* re-read it: they hold the `GPUTextureView`,
|
|
13296
|
+
* so a swap only reaches the specular reflection once the material groups have been rebuilt, which
|
|
13297
|
+
* `rebuildSceneRenderables` does (`lib/scene/scene-rebuild.js`, `rebuildEachGroup`). The
|
|
13298
|
+
* `Environment` component therefore reports an install as a topology change and lets the render-sync
|
|
13299
|
+
* system fire its one coalesced rebuild. This is the only place in ignifx that touches a Lite field
|
|
13300
|
+
* `index.d.ts` does not declare, which is what the adapter boundary exists for
|
|
13301
|
+
* (`CONSTITUTION.md` §3.4, ADR-0002); it is pinned by
|
|
13302
|
+
* `packages/core/test/lite/render/environment.browser.test.ts`, which fails loudly if the field is
|
|
13303
|
+
* renamed.
|
|
12029
13304
|
*/
|
|
12030
13305
|
/**
|
|
12031
13306
|
* The GPU-resident image-based-lighting textures `loadEnvironment` resolves to, re-exported under an
|
|
@@ -12040,7 +13315,7 @@ type LiteEnvironmentTextures = EnvironmentTextures;
|
|
|
12040
13315
|
/**
|
|
12041
13316
|
* The tone-mapping curves `docs/architecture/07-rendering.md` §2.5 exposes.
|
|
12042
13317
|
*
|
|
12043
|
-
* @
|
|
13318
|
+
* @public
|
|
12044
13319
|
*/
|
|
12045
13320
|
export declare const TONE_MAPPING_NAMES: readonly ["none", "standard", "aces", "neutral"];
|
|
12046
13321
|
//#endregion
|
|
@@ -12219,6 +13494,53 @@ export declare function environmentDefinition(overrides?: Partial<EnvironmentDef
|
|
|
12219
13494
|
* becoming an unhandled rejection (coding standards §8). The visible consequence is that a script
|
|
12220
13495
|
* that ramps exposure every frame gets as many recompiles as the GPU can keep up with and no queue.
|
|
12221
13496
|
*
|
|
13497
|
+
* ## Switching environments at runtime
|
|
13498
|
+
*
|
|
13499
|
+
* An `.env` is loaded **onto the scene** by the asset loader, because that is the only shape Lite's
|
|
13500
|
+
* `loadEnvironment` has (`./environment-asset.ts` explains it at length). Until 2026-09-08 that
|
|
13501
|
+
* meant `environment` was effectively read-only after the first load: the component re-aimed what
|
|
13502
|
+
* the loader had installed and nothing more, so assigning a second loaded handle changed the
|
|
13503
|
+
* rotation and the blur and left the lighting alone. It now installs the asset's recorded handles
|
|
13504
|
+
* on the scene (`./gpu/environment-install.ts`) and reports the install as a **topology change**,
|
|
13505
|
+
* which the render-sync system coalesces into the frame's one `rebuildSceneRenderables` — the step
|
|
13506
|
+
* that makes every PBR material re-bind the new cube map, because a bind group holds the texture
|
|
13507
|
+
* view rather than the scene's slot. Two loaded handles can therefore be swapped back and forth for
|
|
13508
|
+
* free: the GPU resources belong to the assets, stay alive while their handles are retained, and are
|
|
13509
|
+
* released by the asset system exactly as before.
|
|
13510
|
+
*
|
|
13511
|
+
* Installing also re-applies rotation, blur, **and** image processing, because Lite's
|
|
13512
|
+
* `loadEnvironment` overwrites `scene.imageProcessing` (`toneMappingEnabled`, `exposure = 0.8`,
|
|
13513
|
+
* `contrast = 1.2`) as a side effect of every load.
|
|
13514
|
+
*
|
|
13515
|
+
* ## Assigning `null` leaves the scene lit
|
|
13516
|
+
*
|
|
13517
|
+
* Lite 1.27.0 has no inverse of `loadEnvironment` — no `unloadEnvironment`, no
|
|
13518
|
+
* `scene.environmentTexture` to clear — and clearing its slot by hand would leave every PBR
|
|
13519
|
+
* material bound to a cube map the scene no longer admits to having until the next renderable
|
|
13520
|
+
* rebuild. So `environment = null` is documented as "stop steering the environment", not "turn the
|
|
13521
|
+
* lights off": the last installed environment keeps lighting the scene, exactly as detaching the
|
|
13522
|
+
* component does. {@link Environment.installed} keeps naming it, because that is what the scene is
|
|
13523
|
+
* actually lit by. To change the lighting, install a different loaded environment.
|
|
13524
|
+
*
|
|
13525
|
+
* ## `skybox` is decided when the environment loads, not here
|
|
13526
|
+
*
|
|
13527
|
+
* Lite builds the background inside `loadEnvironment`, as a *feature-owned* `Renderable` pushed
|
|
13528
|
+
* onto the scene from a deferred builder that `registerScene` drains
|
|
13529
|
+
* (`lib/_chunks/env-helpers-*.js`). `Renderable` (`index.d.ts` 9678) is `{ order, isTransparent,
|
|
13530
|
+
* mesh?, bind }` — no visibility flag, no size, no handle — and Lite exposes no way to remove one,
|
|
13531
|
+
* so a background that has been built cannot be hidden, resized, or re-aimed at another cube map.
|
|
13532
|
+
* The `.environment.json` is therefore the authority: `skyboxEnabled`, `skybox` and `skyboxSize`
|
|
13533
|
+
* decide the background when the asset loads. The component's `skybox` record is read every frame
|
|
13534
|
+
* so that a value the installed environment cannot deliver is *reported* — `IGX-0711`, once per
|
|
13535
|
+
* component — rather than silently ignored, which is what it was until 2026-09-08. A field left at
|
|
13536
|
+
* its schema default never reports anything, so only a project that actually asked for a different
|
|
13537
|
+
* background hears about it.
|
|
13538
|
+
*
|
|
13539
|
+
* The one improvement that did fit: an environment with `skyboxEnabled` and no explicit `skybox`
|
|
13540
|
+
* now draws **its own** prefiltered cube map (`./loaders/environment-loader.ts`), where Lite's
|
|
13541
|
+
* default was a flat box painted in the clear colour. So a bare `.env` gets a real background, and
|
|
13542
|
+
* the component's default `skybox.enabled: true` agrees with it.
|
|
13543
|
+
*
|
|
12222
13544
|
* ## `ambientColor` does not exist
|
|
12223
13545
|
*
|
|
12224
13546
|
* §2.5 lists an `ambientColor` field. Babylon Lite 1.27.0 has no scene-level ambient term:
|
|
@@ -12269,6 +13591,24 @@ interface EnvironmentFogSettings {
|
|
|
12269
13591
|
/** Where linear fog reaches full strength, in metres. */
|
|
12270
13592
|
end: number;
|
|
12271
13593
|
}
|
|
13594
|
+
/**
|
|
13595
|
+
* The `skybox` record an `Environment` declares (`docs/architecture/07-rendering.md` §2.5).
|
|
13596
|
+
*
|
|
13597
|
+
* @remarks
|
|
13598
|
+
* Babylon Lite 1.27.0 builds the background inside `loadEnvironment` and hands back no handle on
|
|
13599
|
+
* it, so both fields are decided when the environment **loads** and cannot be changed afterwards.
|
|
13600
|
+
* Declare them in the `.environment.json` (`skyboxEnabled`, `skyboxSize`); a component that asks
|
|
13601
|
+
* for something else logs `IGX-0711` once. The defaults match the file format's, so the ordinary
|
|
13602
|
+
* case is silent.
|
|
13603
|
+
*
|
|
13604
|
+
* @public
|
|
13605
|
+
*/
|
|
13606
|
+
interface EnvironmentSkyboxSettings {
|
|
13607
|
+
/** Whether a background is drawn behind the scene. */
|
|
13608
|
+
enabled: boolean;
|
|
13609
|
+
/** The background cube's size, in metres. */
|
|
13610
|
+
size: number;
|
|
13611
|
+
}
|
|
12272
13612
|
/**
|
|
12273
13613
|
* The `imageProcessing` record an `Environment` declares
|
|
12274
13614
|
* (`docs/architecture/07-rendering.md` §2.5).
|
|
@@ -12289,12 +13629,20 @@ interface ImageProcessingSettings {
|
|
|
12289
13629
|
* @example
|
|
12290
13630
|
* ```ts
|
|
12291
13631
|
* const studio = await app.assets.loadAsync<EnvironmentAsset>("environments/studio.env");
|
|
12292
|
-
* world.createEntity("Environment").addComponent(Environment, {
|
|
13632
|
+
* const env = world.createEntity("Environment").addComponent(Environment, {
|
|
12293
13633
|
* environment: studio.retain(),
|
|
12294
13634
|
* imageProcessing: { exposure: 1.2, contrast: 1, toneMapping: "aces" },
|
|
12295
13635
|
* });
|
|
12296
13636
|
* ```
|
|
12297
13637
|
*
|
|
13638
|
+
* @example
|
|
13639
|
+
* Switching environments at runtime. Both handles stay retained, so switching back costs nothing.
|
|
13640
|
+
*
|
|
13641
|
+
* ```ts
|
|
13642
|
+
* const night = await app.assets.loadAsync<EnvironmentAsset>("environments/night.env");
|
|
13643
|
+
* env.environment = night.retain();
|
|
13644
|
+
* ```
|
|
13645
|
+
*
|
|
12298
13646
|
* @public
|
|
12299
13647
|
*/
|
|
12300
13648
|
export declare class Environment extends Component implements ComponentHooks {
|
|
@@ -12308,19 +13656,22 @@ export declare class Environment extends Component implements ComponentHooks {
|
|
|
12308
13656
|
environment: AssetHandle<EnvironmentAsset> | null;
|
|
12309
13657
|
rotation: number;
|
|
12310
13658
|
blur: number;
|
|
12311
|
-
skybox:
|
|
12312
|
-
enabled: boolean;
|
|
12313
|
-
size: number;
|
|
12314
|
-
};
|
|
13659
|
+
skybox: EnvironmentSkyboxSettings;
|
|
12315
13660
|
fog: EnvironmentFogSettings;
|
|
12316
13661
|
imageProcessing: ImageProcessingSettings;
|
|
12317
13662
|
clearColor: ColorLike;
|
|
12318
13663
|
/** Applies the schema defaults, exactly as `Component.define` would. */
|
|
12319
13664
|
constructor();
|
|
12320
13665
|
/**
|
|
12321
|
-
* The environment asset this component installed
|
|
13666
|
+
* The environment asset this component installed on the scene.
|
|
12322
13667
|
*
|
|
12323
|
-
* @
|
|
13668
|
+
* @remarks
|
|
13669
|
+
* It stops at the **last installed** asset, which is what the scene is actually lit by: setting
|
|
13670
|
+
* `environment` back to `null` does not un-light the scene, because Lite has no inverse of
|
|
13671
|
+
* `loadEnvironment` (see the module remarks). Headless it names the asset too — what a headless
|
|
13672
|
+
* app skips is the cube map, not the bookkeeping.
|
|
13673
|
+
*
|
|
13674
|
+
* @returns The asset, or `null` when this component has never installed one.
|
|
12324
13675
|
*/
|
|
12325
13676
|
get installed(): EnvironmentAsset | null;
|
|
12326
13677
|
/** Records that the component exists; the scene is written on the first sync. */
|
|
@@ -12340,10 +13691,13 @@ export declare class Environment extends Component implements ComponentHooks {
|
|
|
12340
13691
|
* environment only.
|
|
12341
13692
|
*
|
|
12342
13693
|
* @param renderer - The rendering service, for the scene and the headless flag.
|
|
13694
|
+
* @returns `true` when a different environment was installed on the scene this frame, which is a
|
|
13695
|
+
* topology change: the render-sync system owes the frame one `rebuildSceneRenderables` so that
|
|
13696
|
+
* every PBR material re-binds the new cube map.
|
|
12343
13697
|
*
|
|
12344
13698
|
* @internal
|
|
12345
13699
|
*/
|
|
12346
|
-
sync(renderer: RendererImpl):
|
|
13700
|
+
sync(renderer: RendererImpl): boolean;
|
|
12347
13701
|
}
|
|
12348
13702
|
//#endregion
|
|
12349
13703
|
//#region src/lite/font.d.ts
|
|
@@ -12661,6 +14015,14 @@ export declare class Light extends Component implements ComponentHooks {
|
|
|
12661
14015
|
* file (`docs/architecture/05-assets-and-loading.md` §5,
|
|
12662
14016
|
* `06-serialization-and-scene-format.md` §6).
|
|
12663
14017
|
*
|
|
14018
|
+
* ## The skybox is decided here, once
|
|
14019
|
+
*
|
|
14020
|
+
* Lite builds the background inside `loadEnvironment` and hands back no handle on it, so this is
|
|
14021
|
+
* the only place that can decide whether there is one: `Environment.skybox` can report a
|
|
14022
|
+
* disagreement (`IGX-0711`) but cannot change it. `skyboxEnabled: false` skips the background;
|
|
14023
|
+
* otherwise the declaration's `skybox` image is used, and when it names none the environment draws
|
|
14024
|
+
* **its own** prefiltered cube map (see {@link toLoadOptions}).
|
|
14025
|
+
*
|
|
12664
14026
|
* ## Two addresses, one asset type
|
|
12665
14027
|
*
|
|
12666
14028
|
* A bare `.env` address is the common case: load this IBL, take the BRDF table and the skybox from
|
|
@@ -12781,7 +14143,9 @@ export declare function createMaterialLoader(): AssetLoader<MaterialAsset>;
|
|
|
12781
14143
|
*
|
|
12782
14144
|
* ## What a container holds (verified against `@babylonjs/lite@1.27.0`)
|
|
12783
14145
|
*
|
|
12784
|
-
* `loadGltf(engine, source)` (`index.d.ts` 6821)
|
|
14146
|
+
* `loadGltf(engine, source)` (`index.d.ts` 6821) — reached through the dynamically imported
|
|
14147
|
+
* `./gltf-source.ts`, so that a game which loads no model carries no glTF parser — takes a URL, an
|
|
14148
|
+
* `ArrayBuffer`, or a `Blob` and
|
|
12785
14149
|
* resolves to an `AssetContainer` (`index.d.ts` 653) whose `entities` is `[rootTransformNode]` for
|
|
12786
14150
|
* glTF. The ignifx asset layer fetches the bytes itself — that is where progress reporting and
|
|
12787
14151
|
* `AbortSignal` support live (`docs/architecture/05-assets-and-loading.md`) — and hands Lite an
|
|
@@ -12852,8 +14216,8 @@ type LiteSkeleton = Skeleton;
|
|
|
12852
14216
|
* `addToScene` would register a container's `animationGroups` with Lite's own animation manager and
|
|
12853
14217
|
* install a before-render hook for them. ADR-0003 says ignifx owns every clock, so the loader
|
|
12854
14218
|
* removes them from the container the moment it is loaded and the asset keeps them
|
|
12855
|
-
* ({@link ModelAsset.animations}).
|
|
12856
|
-
*
|
|
14219
|
+
* ({@link ModelAsset.animations}). Core exposes them and advances nothing; `@ignifx/3d`'s
|
|
14220
|
+
* `Animator` is what plays them.
|
|
12857
14221
|
*
|
|
12858
14222
|
* ## Instance counting
|
|
12859
14223
|
*
|
|
@@ -12923,9 +14287,9 @@ export declare class ModelAsset {
|
|
|
12923
14287
|
* The clips the file declared, stripped from the container so Lite never ticks them.
|
|
12924
14288
|
*
|
|
12925
14289
|
* @remarks
|
|
12926
|
-
* Unstable: these are Lite's own animation groups, handed on to `@ignifx/3d`'s
|
|
12927
|
-
* are excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
|
|
12928
|
-
*
|
|
14290
|
+
* Unstable: these are Lite's own animation groups, handed on to `@ignifx/3d`'s `Animator`, and
|
|
14291
|
+
* they are excluded from the stability guarantees of `CONSTITUTION.md` Article IV. To core they
|
|
14292
|
+
* are read-only metadata: nothing here advances or re-binds them.
|
|
12929
14293
|
*
|
|
12930
14294
|
* @beta
|
|
12931
14295
|
*/
|
|
@@ -12998,8 +14362,8 @@ export declare class ModelAsset {
|
|
|
12998
14362
|
* priority queue, and the retry policy live (§5). A `.glb` is one file, so this is lossless.
|
|
12999
14363
|
*
|
|
13000
14364
|
* A `.gltf` with **external** buffers and images is the one case where it is not: Lite would have to
|
|
13001
|
-
* resolve those relative URLs itself, which it can only do when it did the fetching.
|
|
13002
|
-
* the container from bytes either way and therefore supports self-contained `.gltf` files and
|
|
14365
|
+
* resolve those relative URLs itself, which it can only do when it did the fetching. This loader
|
|
14366
|
+
* loads the container from bytes either way and therefore supports self-contained `.gltf` files and
|
|
13003
14367
|
* `.glb`; a `.gltf` with siblings fails inside Lite and surfaces as `IGX-0505`. `.glb` is what the
|
|
13004
14368
|
* asset pipeline produces, and the fix — passing the URL through for that one shape — is a
|
|
13005
14369
|
* three-line change whenever a project needs it.
|
|
@@ -13394,10 +14758,11 @@ export declare class MeshAsset {
|
|
|
13394
14758
|
* - **The clone's Lite `id` is the entity's uid.** Lite's light include/exclude lists match on
|
|
13395
14759
|
* `Mesh.id` strings (`lib/render/lights-ubo.js`), and §2.2 maps `Light.includeOnly` onto them
|
|
13396
14760
|
* from *entity* references. The uid is the one identifier both sides can name.
|
|
13397
|
-
* - **`materials` beyond the first is accepted and ignored
|
|
13398
|
-
*
|
|
13399
|
-
*
|
|
13400
|
-
* renderer uses index 0, or the default material when
|
|
14761
|
+
* - **`materials` beyond the first is accepted and ignored.** §2.3 says "one per submesh", but
|
|
14762
|
+
* Lite's `Mesh.material` is a single value and Lite has no submesh material list in 1.27.0, so
|
|
14763
|
+
* there is nothing for the extra entries to drive. The field keeps its array shape so files do
|
|
14764
|
+
* not have to change if submeshes land; the renderer uses index 0, or the default material when
|
|
14765
|
+
* the array is empty.
|
|
13401
14766
|
*
|
|
13402
14767
|
* ## Headless
|
|
13403
14768
|
*
|
|
@@ -13524,8 +14889,8 @@ export declare class Model extends Component implements ComponentHooks {
|
|
|
13524
14889
|
* The clips the file declared.
|
|
13525
14890
|
*
|
|
13526
14891
|
* @remarks
|
|
13527
|
-
* Unstable: these are Lite's own animation groups, and
|
|
13528
|
-
* (ADR-0003 — `@ignifx/3d`'s
|
|
14892
|
+
* Unstable: these are Lite's own animation groups, and core does not advance them
|
|
14893
|
+
* (ADR-0003 — `@ignifx/3d`'s `Animator` owns playback).
|
|
13529
14894
|
*
|
|
13530
14895
|
* @returns The clips, in load order.
|
|
13531
14896
|
*
|
|
@@ -13614,8 +14979,8 @@ export declare class Model extends Component implements ComponentHooks {
|
|
|
13614
14979
|
* neither is inspectable without extra tooling. Three optional records with an `order` each is the
|
|
13615
14980
|
* simplest shape that round-trips through `encodeProps`/`decodeProps` unchanged, shows up in the
|
|
13616
14981
|
* inspector with real field names and tooltips, and still lets a project reorder the chain. The
|
|
13617
|
-
* cost is that
|
|
13618
|
-
*
|
|
14982
|
+
* cost is that a fourth effect would add a fourth record rather than a new list entry; that is a
|
|
14983
|
+
* schema addition, which the format already tolerates.
|
|
13619
14984
|
*
|
|
13620
14985
|
* ## It needs `rendering.features.postProcessing`, declared at app start
|
|
13621
14986
|
*
|
|
@@ -13706,6 +15071,12 @@ interface ImageProcessingEffectSettings {
|
|
|
13706
15071
|
* One instance of a post-process chain, attached to the main camera's entity
|
|
13707
15072
|
* (`docs/architecture/07-rendering.md` §2.7).
|
|
13708
15073
|
*
|
|
15074
|
+
* @remarks
|
|
15075
|
+
* The stack may be attached and configured either **before** or after `app.start()`. Before start
|
|
15076
|
+
* the chain's frame-graph tasks are appended and recorded by the scene registration `start()` runs;
|
|
15077
|
+
* after start they are recorded on the spot. Either way the first frame the canvas presents already
|
|
15078
|
+
* carries the effects.
|
|
15079
|
+
*
|
|
13709
15080
|
* @example
|
|
13710
15081
|
* ```ts
|
|
13711
15082
|
* cameraEntity.addComponent(PostProcessStack, {
|
|
@@ -13744,6 +15115,13 @@ export declare class PostProcessStack extends Component implements ComponentHook
|
|
|
13744
15115
|
* Builds the chain the first time any effect is enabled, and switches individual effects on and
|
|
13745
15116
|
* off after that. The `PreRender` system calls it.
|
|
13746
15117
|
*
|
|
15118
|
+
* @remarks
|
|
15119
|
+
* It is also called once by `app.start()`, through `renderer.syncBeforeRegister`, which is what
|
|
15120
|
+
* makes a stack configured **before** `start()` work: at that point the scene's frame graph has
|
|
15121
|
+
* not been built, so the chain appends its tasks and lets `registerScene` record them
|
|
15122
|
+
* (`PostProcessChain`'s `isFrameGraphBuilt`). Recording them early instead binds a scene colour
|
|
15123
|
+
* that no task has allocated yet and Lite rejects the whole frame with error 107.
|
|
15124
|
+
*
|
|
13747
15125
|
* @param renderer - The rendering service, for the engine and the scene.
|
|
13748
15126
|
*
|
|
13749
15127
|
* @internal
|
|
@@ -14473,8 +15851,8 @@ export declare function optional<T>(inner: FieldDefinition<T>, options?: FieldOp
|
|
|
14473
15851
|
* project settings does not silently repoint existing files
|
|
14474
15852
|
* (`docs/architecture/06-serialization-and-scene-format.md` §3).
|
|
14475
15853
|
*
|
|
14476
|
-
* The value
|
|
14477
|
-
*
|
|
15854
|
+
* The field's value is a read-only array of names. The kernel's `LayerMask` satisfies the same
|
|
15855
|
+
* structural shape, so a component may hold either.
|
|
14478
15856
|
*
|
|
14479
15857
|
* @param defaultValue - The names a new component starts with; defaults to empty.
|
|
14480
15858
|
* @param options - Inspector and serializer metadata.
|
|
@@ -14708,5 +16086,196 @@ export declare function waitUntil(predicate: () => boolean): WaitInstruction;
|
|
|
14708
16086
|
*/
|
|
14709
16087
|
export declare function waitWhile(predicate: () => boolean): WaitInstruction;
|
|
14710
16088
|
//#endregion
|
|
14711
|
-
|
|
16089
|
+
//#region src/storage/memory-backend.d.ts
|
|
16090
|
+
/**
|
|
16091
|
+
* The in-memory storage backend: the default for a headless app, and the one every unit test in the
|
|
16092
|
+
* engine runs against (`docs/architecture/14-platform-electron.md` §2, §5).
|
|
16093
|
+
*
|
|
16094
|
+
* It is the reference implementation of `./backend.ts`: nothing here is a shortcut for being
|
|
16095
|
+
* in-process. Values are copied in and out, so a caller that mutates the `Uint8Array` it wrote
|
|
16096
|
+
* cannot reach the store; namespaces are separate maps rather than prefixed keys; and every method
|
|
16097
|
+
* is asynchronous even though none of them needs to be, because game code written against this
|
|
16098
|
+
* backend has to keep working on IndexedDB.
|
|
16099
|
+
*/
|
|
16100
|
+
/**
|
|
16101
|
+
* A store that lives as long as the app does.
|
|
16102
|
+
*
|
|
16103
|
+
* @example
|
|
16104
|
+
* ```ts
|
|
16105
|
+
* const app = await createApp({ storage: new MemoryStorageBackend() });
|
|
16106
|
+
* ```
|
|
16107
|
+
*
|
|
16108
|
+
* @public
|
|
16109
|
+
*/
|
|
16110
|
+
export declare class MemoryStorageBackend implements StorageBackend {
|
|
16111
|
+
#private;
|
|
16112
|
+
/** The identifier that appears in error context. */
|
|
16113
|
+
readonly name = "memory";
|
|
16114
|
+
/**
|
|
16115
|
+
* Reads one value.
|
|
16116
|
+
*
|
|
16117
|
+
* @param namespace - The namespace path.
|
|
16118
|
+
* @param key - The key.
|
|
16119
|
+
* @returns A copy of the stored value, or `null`.
|
|
16120
|
+
*/
|
|
16121
|
+
get(namespace: string, key: string): Promise<StoredValue | null>;
|
|
16122
|
+
/**
|
|
16123
|
+
* Writes one value.
|
|
16124
|
+
*
|
|
16125
|
+
* @param namespace - The namespace path, created on demand.
|
|
16126
|
+
* @param key - The key.
|
|
16127
|
+
* @param value - The value to copy in.
|
|
16128
|
+
* @returns A promise that settles once the value is stored.
|
|
16129
|
+
*/
|
|
16130
|
+
set(namespace: string, key: string, value: StoredValue): Promise<void>;
|
|
16131
|
+
/**
|
|
16132
|
+
* Removes one value.
|
|
16133
|
+
*
|
|
16134
|
+
* @param namespace - The namespace path.
|
|
16135
|
+
* @param key - The key.
|
|
16136
|
+
* @returns A promise that settles once the value is gone.
|
|
16137
|
+
*/
|
|
16138
|
+
delete(namespace: string, key: string): Promise<void>;
|
|
16139
|
+
/**
|
|
16140
|
+
* Lists one namespace's keys.
|
|
16141
|
+
*
|
|
16142
|
+
* @param namespace - The namespace path.
|
|
16143
|
+
* @param prefix - An optional key prefix.
|
|
16144
|
+
* @returns The matching keys, sorted ascending.
|
|
16145
|
+
*/
|
|
16146
|
+
keys(namespace: string, prefix?: string): Promise<readonly string[]>;
|
|
16147
|
+
/**
|
|
16148
|
+
* Empties one namespace.
|
|
16149
|
+
*
|
|
16150
|
+
* @param namespace - The namespace path.
|
|
16151
|
+
* @returns A promise that settles once the namespace is empty.
|
|
16152
|
+
*/
|
|
16153
|
+
clear(namespace: string): Promise<void>;
|
|
16154
|
+
/** Drops every namespace. */
|
|
16155
|
+
dispose(): void;
|
|
16156
|
+
}
|
|
16157
|
+
//#endregion
|
|
16158
|
+
//#region src/storage/names.d.ts
|
|
16159
|
+
/**
|
|
16160
|
+
* The syntax rules `app.storage` enforces on namespaces and keys before a backend ever sees them
|
|
16161
|
+
* (`docs/architecture/14-platform-electron.md` §2), and the reasons they are as narrow as they are.
|
|
16162
|
+
*
|
|
16163
|
+
* A **namespace** ends up as a directory on disk and as part of a compound IndexedDB key, so its
|
|
16164
|
+
* alphabet has to survive every file system ignifx runs on: it is deliberately small, and the
|
|
16165
|
+
* validator refuses the two names — `.` and `..` — that mean something else to a path resolver. A
|
|
16166
|
+
* **key** is opaque: it may hold anything a game wants to name a save slot, including `/`, `..`,
|
|
16167
|
+
* `:` and characters Windows forbids, because backends encode keys rather than resolve them
|
|
16168
|
+
* (`./file-names.ts`). All a key may not be is empty, unreasonably long, or full of control
|
|
16169
|
+
* characters that would make a listing unreadable.
|
|
16170
|
+
*/
|
|
16171
|
+
/**
|
|
16172
|
+
* The namespace `app.storage` itself reads and writes before `namespace(name)` is called.
|
|
16173
|
+
*
|
|
16174
|
+
* @remarks
|
|
16175
|
+
* Every backend call carries a namespace, so the root storage needs a name of its own rather than
|
|
16176
|
+
* an empty string that each backend would have to special-case. `"default"` is a legal namespace
|
|
16177
|
+
* name, which means a game that writes `app.storage.namespace("default")` reaches the same values —
|
|
16178
|
+
* intentionally, since the two are the same store.
|
|
16179
|
+
*
|
|
16180
|
+
* @public
|
|
16181
|
+
*/
|
|
16182
|
+
export declare const DEFAULT_STORAGE_NAMESPACE = "default";
|
|
16183
|
+
/**
|
|
16184
|
+
* The longest one segment of a namespace path may be.
|
|
16185
|
+
*
|
|
16186
|
+
* @public
|
|
16187
|
+
*/
|
|
16188
|
+
export declare const NAMESPACE_SEGMENT_MAX_LENGTH = 64;
|
|
16189
|
+
/**
|
|
16190
|
+
* The longest a storage key may be.
|
|
16191
|
+
*
|
|
16192
|
+
* @remarks
|
|
16193
|
+
* 512 UTF-16 code units is comfortably below the ~255 *byte* file-name limit once percent-encoding
|
|
16194
|
+
* has expanded the key, which is why the file backend hashes nothing and truncates nothing: a key
|
|
16195
|
+
* that passes this check always encodes to a name a file system accepts.
|
|
16196
|
+
*
|
|
16197
|
+
* @public
|
|
16198
|
+
*/
|
|
16199
|
+
export declare const STORAGE_KEY_MAX_LENGTH = 512;
|
|
16200
|
+
//#endregion
|
|
16201
|
+
//#region src/storage/web/indexeddb-backend.d.ts
|
|
16202
|
+
/**
|
|
16203
|
+
* A store backed by the browser's IndexedDB.
|
|
16204
|
+
*
|
|
16205
|
+
* @example
|
|
16206
|
+
* ```ts
|
|
16207
|
+
* const app = await createApp({ canvas, storage: new IndexedDbStorageBackend() });
|
|
16208
|
+
* ```
|
|
16209
|
+
*
|
|
16210
|
+
* @public
|
|
16211
|
+
*/
|
|
16212
|
+
export declare class IndexedDbStorageBackend implements StorageBackend {
|
|
16213
|
+
#private;
|
|
16214
|
+
/** The identifier that appears in error context. */
|
|
16215
|
+
readonly name = "indexeddb";
|
|
16216
|
+
/**
|
|
16217
|
+
* Reads one value.
|
|
16218
|
+
*
|
|
16219
|
+
* @param namespace - The namespace path.
|
|
16220
|
+
* @param key - The key.
|
|
16221
|
+
* @returns The value, or `null`.
|
|
16222
|
+
*/
|
|
16223
|
+
get(namespace: string, key: string): Promise<StoredValue | null>;
|
|
16224
|
+
/**
|
|
16225
|
+
* Writes one value.
|
|
16226
|
+
*
|
|
16227
|
+
* @param namespace - The namespace path.
|
|
16228
|
+
* @param key - The key.
|
|
16229
|
+
* @param value - The value.
|
|
16230
|
+
* @returns A promise that settles once the transaction commits.
|
|
16231
|
+
*/
|
|
16232
|
+
set(namespace: string, key: string, value: StoredValue): Promise<void>;
|
|
16233
|
+
/**
|
|
16234
|
+
* Removes one value.
|
|
16235
|
+
*
|
|
16236
|
+
* @param namespace - The namespace path.
|
|
16237
|
+
* @param key - The key.
|
|
16238
|
+
* @returns A promise that settles once the transaction commits.
|
|
16239
|
+
*/
|
|
16240
|
+
delete(namespace: string, key: string): Promise<void>;
|
|
16241
|
+
/**
|
|
16242
|
+
* Lists one namespace's keys.
|
|
16243
|
+
*
|
|
16244
|
+
* @param namespace - The namespace path.
|
|
16245
|
+
* @param prefix - An optional key prefix.
|
|
16246
|
+
* @returns The matching keys, in ascending order.
|
|
16247
|
+
*/
|
|
16248
|
+
keys(namespace: string, prefix?: string): Promise<readonly string[]>;
|
|
16249
|
+
/**
|
|
16250
|
+
* Empties one namespace.
|
|
16251
|
+
*
|
|
16252
|
+
* @param namespace - The namespace path.
|
|
16253
|
+
* @returns A promise that settles once the transaction commits.
|
|
16254
|
+
*/
|
|
16255
|
+
clear(namespace: string): Promise<void>;
|
|
16256
|
+
/** Closes the connection. The next call opens a new one. */
|
|
16257
|
+
dispose(): void;
|
|
16258
|
+
}
|
|
16259
|
+
//#endregion
|
|
16260
|
+
//#region src/tween/tween-system.d.ts
|
|
16261
|
+
/**
|
|
16262
|
+
* The `PostUpdate` system that advances `app.tweens` (`docs/architecture/01-lifecycle-and-time.md`
|
|
16263
|
+
* §3 step 5, `12-3d-toolkit.md` §4).
|
|
16264
|
+
*
|
|
16265
|
+
* `PostUpdate` is where every clock consumer in ignifx advances, so a `lateUpdate` and the render
|
|
16266
|
+
* sync both see the value a tween wrote in the same frame it wrote it.
|
|
16267
|
+
*/
|
|
16268
|
+
/**
|
|
16269
|
+
* The `PostUpdate` order the tween system runs at.
|
|
16270
|
+
*
|
|
16271
|
+
* @remarks
|
|
16272
|
+
* `-100` puts tweens **before** the toolkits' animation systems, which register at `0`
|
|
16273
|
+
* (`@ignifx/2d`) and `10` (`@ignifx/3d`): a tween that drives an `Animator` parameter or a
|
|
16274
|
+
* material property is read by the animation that runs after it, in the same frame.
|
|
16275
|
+
*
|
|
16276
|
+
* @public
|
|
16277
|
+
*/
|
|
16278
|
+
export declare const TWEEN_SYSTEM_ORDER = -100;
|
|
16279
|
+
//#endregion
|
|
16280
|
+
export type { 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, ComponentClassInfo, ComponentDefinition, ComponentHandle, ComponentHooks, ComponentInit, ComponentRefFieldSpec, ComponentReplacement, ComponentStatics, ComponentType, ComponentTypeToken, ConcreteComponentType, ConnectOptions, ConsoleLike, ConsoleSinkOptions, Coroutine, CoroutineHandle, CoroutineHost, CoroutineYield, CreateAppOptions, CreateEntityOptions, CurveFieldSpec, CurveKey, CurveValue, 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, ImageProcessingEffectSettings, ImageProcessingSettings, InstantiateOptions, InstantiateSceneOptions, JsonArray, JsonObject, JsonSchemaObject, JsonValue, LayerMaskFieldSpec, LayersSettings, LightShadowSettings, LightType, LiteAnimationGroup, LiteAssetContainer, LiteCamera, LiteEngine, LiteEnvironmentTextures, LiteFont, AdapterLight as LiteLight, LiteMaterial, LiteMesh, LitePbrMaterial, LiteScene, LiteSceneNode, LiteShadowGenerator, LiteSkeleton, LiteStandardMaterial, LiteTexture2D, LoadOptions, LoadProgress, LoadSceneOptions, LoaderContext, LogRecord, LogSink, LogThreshold, Logger, LoggerOptions, ManualClock, MapFieldSpec, Mat4Elements, Mat4Like, MaterialAlphaMode, MaterialAssetLiteHandles, MaterialDefinition, MaterialKind, MemorySink, MeshAssetLiteHandles, MeshGeometryData, ModelAssetLiteHandles, ModelInstantiation, MutableQuat, MutableVec2, MutableVec3, MutableVec4, NumberFieldSpec, OptionalFieldSpec, OverridePath, PartialFieldsOf, PbrMaterialDefinition, PhaseIndex, PlaneMeshOptions, PlatformInfo, PlatformKind, PlatformOs, ProfileScope, QuatLike, RandomSource, Ray, RayVector, RecordFieldSpec, ReferenceDecoder, ReferenceEncoder, RegisterAssetOptions, RegisterComponentOptions, RegisterSystemOptions, RenderCapture, RenderPick, 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, ShadowTechniqueName, SignalHandler, SignalLike, SignalOptions, SignalOwner, SmaaEffectSettings, SortingLayersSettings, SphereMeshOptions, StandardMaterialDefinition, Storage, StorageBackend, StoredValue, StoredValueKind, StringFieldSpec, System, SystemContext, TextureAssetLiteHandles, TextureImportOptions, Time, TimeSettings, ToneMappingCurve, TorusMeshOptions, TweenOptions, TweenProps, TweenTargetValue, TweenValueKind, TweenableValue, Tweens, UlidFactoryOptions, Vec2Like, Vec3Like, Vec4Like, VectorFieldSpec, WaitInstruction, WebGpuInfo, WorldLiteHandles };
|
|
14712
16281
|
//# sourceMappingURL=index.d.ts.map
|