@ignifx/ui 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/index.d.ts +3460 -1
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +5530 -0
- package/dist/index.js.map +1 -0
- package/package.json +48 -26
- package/skills/ui/SKILL.md +317 -13
package/dist/index.d.ts
CHANGED
|
@@ -1 +1,3460 @@
|
|
|
1
|
-
|
|
1
|
+
import { App, AssetHandle, AssetLoader, AssetProgress, Assets, ColorLike, Component, ComponentHooks, Disconnect, ErrorContext, Extension, FontAsset, IgnifxError, JsonSchemaObject, LiteScene, Logger, QuatLike, Schema, SchemaDescription, SignalLike, System, SystemContext, Vec2Like, Vec3Like, World } from "@ignifx/core";
|
|
2
|
+
import { DefaultTextData, Font, TextLayer, TextRenderable, TextRenderer } from "@babylonjs/lite";
|
|
3
|
+
//#region src/dom/layer.d.ts
|
|
4
|
+
/**
|
|
5
|
+
* One named stacking layer inside the overlay root (`docs/architecture/13-ui.md` §1:
|
|
6
|
+
* "games mount React/Preact/Svelte/Vue/vanilla trees into it, or into named layers"*).
|
|
7
|
+
*
|
|
8
|
+
* A layer is a plain absolutely-positioned `<div>` that fills the root, carries a `z-index`, and is
|
|
9
|
+
* `pointer-events: none` like the root — children opt in with the
|
|
10
|
+
* {@link UI_CLASS_NAMES.interactive} class or their own CSS. Under a headless app the layer still
|
|
11
|
+
* exists as an object, with `element` `null` and every mutation a no-op, so game code never has to
|
|
12
|
+
* branch on the environment.
|
|
13
|
+
*/
|
|
14
|
+
/**
|
|
15
|
+
* Options accepted by `app.ui.layer`.
|
|
16
|
+
*
|
|
17
|
+
* @public
|
|
18
|
+
*/
|
|
19
|
+
interface UiLayerOptions {
|
|
20
|
+
/** The stacking order. Defaults to the layer's declaration index times `UI_LAYER_Z_STEP`. */
|
|
21
|
+
readonly zIndex?: number;
|
|
22
|
+
/** Whether the layer starts visible. Defaults to `true`. */
|
|
23
|
+
readonly visible?: boolean;
|
|
24
|
+
}
|
|
25
|
+
/**
|
|
26
|
+
* A named layer of the overlay.
|
|
27
|
+
*
|
|
28
|
+
* @example
|
|
29
|
+
* ```ts
|
|
30
|
+
* const hud = app.ui.layer("hud");
|
|
31
|
+
* hud.element?.append(document.createElement("div"));
|
|
32
|
+
* hud.visible = false;
|
|
33
|
+
* ```
|
|
34
|
+
*
|
|
35
|
+
* @public
|
|
36
|
+
*/
|
|
37
|
+
export declare class UiLayer {
|
|
38
|
+
#private;
|
|
39
|
+
/** The name the layer is addressed by. */
|
|
40
|
+
readonly name: string;
|
|
41
|
+
/**
|
|
42
|
+
* Builds a layer. `app.ui.layer` does this; a game never constructs one.
|
|
43
|
+
*
|
|
44
|
+
* @param name - The layer name.
|
|
45
|
+
* @param element - The layer's element, or `null` under a headless app.
|
|
46
|
+
* @param zIndex - The initial stacking order.
|
|
47
|
+
* @param visible - Whether the layer starts visible.
|
|
48
|
+
*
|
|
49
|
+
* @internal
|
|
50
|
+
*/
|
|
51
|
+
constructor(name: string, element: HTMLDivElement | null, zIndex: number, visible: boolean);
|
|
52
|
+
/**
|
|
53
|
+
* Gives a layer that was created before the overlay mounted its element.
|
|
54
|
+
*
|
|
55
|
+
* @remarks
|
|
56
|
+
* The host builds its root when the world is created, which is after every extension registered;
|
|
57
|
+
* a layer declared in the `ui` settings section therefore exists as an object first and gets its
|
|
58
|
+
* element a moment later. Nothing observable changes: an unmounted layer is exactly a headless
|
|
59
|
+
* one.
|
|
60
|
+
*
|
|
61
|
+
* @param element - The layer's element.
|
|
62
|
+
*
|
|
63
|
+
* @internal
|
|
64
|
+
*/
|
|
65
|
+
attach(element: HTMLDivElement): void;
|
|
66
|
+
/**
|
|
67
|
+
* The layer's element, or `null` when the app has no DOM overlay.
|
|
68
|
+
*
|
|
69
|
+
* @returns The `<div>` a game mounts its tree into.
|
|
70
|
+
*/
|
|
71
|
+
get element(): HTMLDivElement | null;
|
|
72
|
+
/**
|
|
73
|
+
* The layer's stacking order within the root.
|
|
74
|
+
*
|
|
75
|
+
* @returns The `z-index`.
|
|
76
|
+
*/
|
|
77
|
+
get zIndex(): number;
|
|
78
|
+
set zIndex(value: number);
|
|
79
|
+
/**
|
|
80
|
+
* Whether the layer is shown. Hiding a layer hides everything mounted in it without unmounting
|
|
81
|
+
* anything, which is what a pause menu wants.
|
|
82
|
+
*
|
|
83
|
+
* @returns `true` while the layer is shown.
|
|
84
|
+
*/
|
|
85
|
+
get visible(): boolean;
|
|
86
|
+
set visible(value: boolean);
|
|
87
|
+
/**
|
|
88
|
+
* Removes every child of the layer without removing the layer itself.
|
|
89
|
+
*
|
|
90
|
+
* @remarks
|
|
91
|
+
* A no-op under a headless app.
|
|
92
|
+
*/
|
|
93
|
+
clear(): void;
|
|
94
|
+
}
|
|
95
|
+
//#endregion
|
|
96
|
+
//#region src/dom/dom-target.d.ts
|
|
97
|
+
/**
|
|
98
|
+
* What the overlay host needs from the host page (`docs/architecture/13-ui.md` §1). Passing it
|
|
99
|
+
* explicitly, instead of reaching for `globalThis.document`, is what makes two apps in one document
|
|
100
|
+
* possible (`CONSTITUTION.md` §3.6) and what lets a test hand in a fake.
|
|
101
|
+
*
|
|
102
|
+
* The whole module is written against the real DOM types rather than structural stand-ins, which is
|
|
103
|
+
* the choice `@ignifx/input`'s `DomTarget` already made: games get real elements to mount React or
|
|
104
|
+
* Svelte into, and the node test suite passes a fake through one `as unknown as` in
|
|
105
|
+
* `test/support/fake-dom.ts` rather than every call site paying for an abstraction.
|
|
106
|
+
*/
|
|
107
|
+
/**
|
|
108
|
+
* The DOM objects one app's overlay is built in.
|
|
109
|
+
*
|
|
110
|
+
* @public
|
|
111
|
+
*/
|
|
112
|
+
interface UiDomTarget {
|
|
113
|
+
/** The canvas the overlay is positioned over. */
|
|
114
|
+
readonly canvas: HTMLCanvasElement;
|
|
115
|
+
/** The document the overlay's elements and its stylesheet are created in. */
|
|
116
|
+
readonly document: Document;
|
|
117
|
+
/** The window resize and focus events are read from, and the pixel ratio is read from. */
|
|
118
|
+
readonly window: Window;
|
|
119
|
+
}
|
|
120
|
+
//#endregion
|
|
121
|
+
//#region src/settings.d.ts
|
|
122
|
+
/**
|
|
123
|
+
* The `ui` project settings section (`docs/architecture/04-extensions.md` §5, `13-ui.md` §1).
|
|
124
|
+
* Everything here is what a game writes in `ignifx.config.ts`; the knobs a game changes per frame
|
|
125
|
+
* live on `app.ui` and on the individual layers instead.
|
|
126
|
+
*/
|
|
127
|
+
/**
|
|
128
|
+
* The section name as it appears in `ignifx.config.ts`.
|
|
129
|
+
*
|
|
130
|
+
* @public
|
|
131
|
+
*/
|
|
132
|
+
export declare const UI_SETTINGS_SECTION = "ui";
|
|
133
|
+
/**
|
|
134
|
+
* Every scaling mode the overlay host supports, in the order an inspector should list them
|
|
135
|
+
* (`docs/architecture/13-ui.md` §1).
|
|
136
|
+
*
|
|
137
|
+
* @public
|
|
138
|
+
*/
|
|
139
|
+
export declare const UI_SCALING_MODES: readonly ["css", "fit", "dpi"];
|
|
140
|
+
/**
|
|
141
|
+
* How the overlay's coordinate system relates to the canvas.
|
|
142
|
+
*
|
|
143
|
+
* @remarks
|
|
144
|
+
* - `"css"` — one UI unit is one CSS pixel and nothing is scaled. The browser default, and what a
|
|
145
|
+
* responsive HTML menu wants.
|
|
146
|
+
* - `"fit"` — the root is exactly {@link UiSettings.referenceResolution} CSS pixels and is scaled
|
|
147
|
+
* uniformly to fit inside the canvas, keeping aspect and centring the letterbox. A HUD authored
|
|
148
|
+
* once at 1920x1080 then looks the same on every window size.
|
|
149
|
+
* - `"dpi"` — one UI unit is one **render-target** pixel: the root is sized to the canvas's
|
|
150
|
+
* backing store and scaled by `1 / devicePixelRatio` so it still covers the same area. This is
|
|
151
|
+
* the space `Camera.worldToScreen`, `HudText`, and `app.renderer.captureScreenshot()` all work
|
|
152
|
+
* in, so an element placed at `left: 100px` lands on render-target column 100 exactly.
|
|
153
|
+
*
|
|
154
|
+
* @public
|
|
155
|
+
*/
|
|
156
|
+
type UiScalingMode = (typeof UI_SCALING_MODES)[number];
|
|
157
|
+
/**
|
|
158
|
+
* The resolved `ui` settings section.
|
|
159
|
+
*
|
|
160
|
+
* @example
|
|
161
|
+
* ```ts
|
|
162
|
+
* // ignifx.config.ts
|
|
163
|
+
* export default defineConfig({
|
|
164
|
+
* ui: { scaling: "fit", referenceResolution: [640, 360], layers: ["hud", "menu"] },
|
|
165
|
+
* });
|
|
166
|
+
* ```
|
|
167
|
+
*
|
|
168
|
+
* @public
|
|
169
|
+
*/
|
|
170
|
+
interface UiSettings {
|
|
171
|
+
/** How the overlay's coordinate system relates to the canvas. Defaults to `"css"`. */
|
|
172
|
+
readonly scaling: UiScalingMode;
|
|
173
|
+
/**
|
|
174
|
+
* The `[width, height]`, in UI units, that `"fit"` scales to. Ignored by the other two modes.
|
|
175
|
+
* Defaults to `[1920, 1080]`.
|
|
176
|
+
*/
|
|
177
|
+
readonly referenceResolution: readonly number[];
|
|
178
|
+
/**
|
|
179
|
+
* The layers created eagerly, back to front. Declaring them here is what makes their stacking
|
|
180
|
+
* order independent of the order the game happens to call {@link UiHost.layer} in.
|
|
181
|
+
*/
|
|
182
|
+
readonly layers: readonly string[];
|
|
183
|
+
/** Whether the overlay is shown at all. Defaults to `true`. */
|
|
184
|
+
readonly visible: boolean;
|
|
185
|
+
}
|
|
186
|
+
/**
|
|
187
|
+
* The z-index step between two consecutive layers. The first declared layer sits at
|
|
188
|
+
* `UI_LAYER_Z_STEP`, the second at twice that, and so on, which leaves nine free slots between any
|
|
189
|
+
* two layers for a game that wants to interleave its own elements.
|
|
190
|
+
*
|
|
191
|
+
* @public
|
|
192
|
+
*/
|
|
193
|
+
export declare const UI_LAYER_Z_STEP = 10;
|
|
194
|
+
/**
|
|
195
|
+
* The values used for everything a project omits.
|
|
196
|
+
*
|
|
197
|
+
* @returns The default `ui` section.
|
|
198
|
+
*
|
|
199
|
+
* @public
|
|
200
|
+
*/
|
|
201
|
+
export declare function defaultUiSettings(): UiSettings;
|
|
202
|
+
/**
|
|
203
|
+
* The schema the `ui` section is validated against.
|
|
204
|
+
*
|
|
205
|
+
* @returns The schema, built fresh so no module holds state (`CONSTITUTION.md` §3.5).
|
|
206
|
+
*
|
|
207
|
+
* @public
|
|
208
|
+
*/
|
|
209
|
+
export declare function uiSettingsSchema(): Schema;
|
|
210
|
+
//#endregion
|
|
211
|
+
//#region src/dom/scaling.d.ts
|
|
212
|
+
/**
|
|
213
|
+
* The scaling arithmetic behind `app.ui.scaling` (`docs/architecture/13-ui.md` §1). Every function
|
|
214
|
+
* here is pure: it takes measurements and returns numbers, so the three modes are unit-testable
|
|
215
|
+
* under Node with no DOM at all, and the host is left with nothing but the DOM writes.
|
|
216
|
+
*
|
|
217
|
+
* ## The three coordinate systems
|
|
218
|
+
*
|
|
219
|
+
* A canvas has two sizes: its **CSS** size, which is what layout and pointer coordinates use, and
|
|
220
|
+
* its **backing-store** size (`canvas.width`/`canvas.height`), which is what WebGPU renders into.
|
|
221
|
+
* Their ratio is the effective device pixel ratio. `Camera.worldToScreen`, Lite's text renderer,
|
|
222
|
+
* and `app.renderer.captureScreenshot()` all work in backing-store pixels; a DOM element is placed
|
|
223
|
+
* in CSS pixels. A "UI unit" is whichever of the two — or neither — the scaling mode picks:
|
|
224
|
+
*
|
|
225
|
+
* | Mode | One UI unit is | Root size | Scale |
|
|
226
|
+
* | ------- | -------------------- | ------------------------ | ---------------------------- |
|
|
227
|
+
* | `"css"` | one CSS pixel | the canvas's CSS size | `1` |
|
|
228
|
+
* | `"fit"` | one reference pixel | `referenceResolution` | `min(cssW/refW, cssH/refH)` |
|
|
229
|
+
* | `"dpi"` | one backing pixel | the canvas's pixel size | `cssW / backingW` |
|
|
230
|
+
*/
|
|
231
|
+
/**
|
|
232
|
+
* The two sizes of the canvas the overlay covers, both measured by the host.
|
|
233
|
+
*
|
|
234
|
+
* @public
|
|
235
|
+
*/
|
|
236
|
+
interface UiSurfaceMetrics {
|
|
237
|
+
/** The canvas's laid-out width, in CSS pixels. */
|
|
238
|
+
readonly cssWidth: number;
|
|
239
|
+
/** The canvas's laid-out height, in CSS pixels. */
|
|
240
|
+
readonly cssHeight: number;
|
|
241
|
+
/** The canvas's backing-store width, in device pixels — `canvas.width`. */
|
|
242
|
+
readonly deviceWidth: number;
|
|
243
|
+
/** The canvas's backing-store height, in device pixels — `canvas.height`. */
|
|
244
|
+
readonly deviceHeight: number;
|
|
245
|
+
}
|
|
246
|
+
/**
|
|
247
|
+
* Where the overlay root sits and how big it is, in the units the mode chose.
|
|
248
|
+
*
|
|
249
|
+
* @public
|
|
250
|
+
*/
|
|
251
|
+
interface UiLayout {
|
|
252
|
+
/** The mode this layout was computed for. */
|
|
253
|
+
readonly mode: UiScalingMode;
|
|
254
|
+
/** The root's width, in UI units. */
|
|
255
|
+
readonly width: number;
|
|
256
|
+
/** The root's height, in UI units. */
|
|
257
|
+
readonly height: number;
|
|
258
|
+
/** The uniform CSS scale applied to the root. */
|
|
259
|
+
readonly scale: number;
|
|
260
|
+
/** The root's left edge, in CSS pixels from the canvas's left edge. */
|
|
261
|
+
readonly offsetX: number;
|
|
262
|
+
/** The root's top edge, in CSS pixels from the canvas's top edge. */
|
|
263
|
+
readonly offsetY: number;
|
|
264
|
+
}
|
|
265
|
+
/**
|
|
266
|
+
* Computes the overlay root's size, scale, and offset for one mode and one measured canvas.
|
|
267
|
+
*
|
|
268
|
+
* @param mode - The scaling mode.
|
|
269
|
+
* @param metrics - The canvas's CSS and backing-store sizes.
|
|
270
|
+
* @param reference - The `[width, height]` a `"fit"` layout scales to; ignored by the other modes.
|
|
271
|
+
* @returns The layout to write onto the root.
|
|
272
|
+
*
|
|
273
|
+
* @example
|
|
274
|
+
* ```ts
|
|
275
|
+
* computeUiLayout("fit", { cssWidth: 800, cssHeight: 600, deviceWidth: 800, deviceHeight: 600 }, [
|
|
276
|
+
* 400, 300,
|
|
277
|
+
* ]).scale; // 2
|
|
278
|
+
* ```
|
|
279
|
+
*
|
|
280
|
+
* @public
|
|
281
|
+
*/
|
|
282
|
+
export declare function computeUiLayout(mode: UiScalingMode, metrics: UiSurfaceMetrics, reference: readonly number[]): UiLayout;
|
|
283
|
+
/**
|
|
284
|
+
* How a render-target pixel maps onto a UI unit under one layout.
|
|
285
|
+
*
|
|
286
|
+
* @remarks
|
|
287
|
+
* `Camera.worldToScreen` answers in **backing-store** pixels (it divides by
|
|
288
|
+
* `RendererImpl.readTargetSize`, which reads `canvas.width`/`canvas.height`), and a DOM element is
|
|
289
|
+
* placed in UI units inside a root that is itself translated by `offsetX`/`offsetY` CSS pixels and
|
|
290
|
+
* scaled by `scale`. This is the conversion between the two, expressed so a per-frame loop needs
|
|
291
|
+
* two multiplies and a subtract and allocates nothing.
|
|
292
|
+
*
|
|
293
|
+
* @public
|
|
294
|
+
*/
|
|
295
|
+
interface UiPixelMapping {
|
|
296
|
+
/** Multiply a backing-store x by this. */
|
|
297
|
+
readonly scaleX: number;
|
|
298
|
+
/** Then subtract this. */
|
|
299
|
+
readonly originX: number;
|
|
300
|
+
/** Multiply a backing-store y by this. */
|
|
301
|
+
readonly scaleY: number;
|
|
302
|
+
/** Then subtract this. */
|
|
303
|
+
readonly originY: number;
|
|
304
|
+
}
|
|
305
|
+
/**
|
|
306
|
+
* Builds the backing-store-pixel to UI-unit conversion for one layout and one canvas.
|
|
307
|
+
*
|
|
308
|
+
* @param layout - The current layout.
|
|
309
|
+
* @param metrics - The canvas's CSS and backing-store sizes.
|
|
310
|
+
* @returns The mapping.
|
|
311
|
+
*
|
|
312
|
+
* @example
|
|
313
|
+
* ```ts
|
|
314
|
+
* const metrics = { cssWidth: 400, cssHeight: 300, deviceWidth: 800, deviceHeight: 600 };
|
|
315
|
+
* const layout = computeUiLayout("css", metrics, [400, 300]);
|
|
316
|
+
* const map = pixelMapping(layout, metrics);
|
|
317
|
+
* map.scaleX * 800 - map.originX; // 400 — the canvas's right edge, in CSS pixels
|
|
318
|
+
* ```
|
|
319
|
+
*
|
|
320
|
+
* @public
|
|
321
|
+
*/
|
|
322
|
+
export declare function pixelMapping(layout: UiLayout, metrics: UiSurfaceMetrics): UiPixelMapping;
|
|
323
|
+
//#endregion
|
|
324
|
+
//#region src/dom/host.d.ts
|
|
325
|
+
/**
|
|
326
|
+
* What {@link UiHost} is constructed with.
|
|
327
|
+
*
|
|
328
|
+
* @internal
|
|
329
|
+
*/
|
|
330
|
+
interface UiHostOptions {
|
|
331
|
+
/**
|
|
332
|
+
* Finds the DOM to build the overlay in, or answers `null` for a headless app. Called once, from
|
|
333
|
+
* {@link UiHost.mount}, because the render surface does not exist while extensions register.
|
|
334
|
+
*/
|
|
335
|
+
readonly resolveTarget: () => UiDomTarget | null;
|
|
336
|
+
/** The resolved `ui` settings section, already merged with the extension's options. */
|
|
337
|
+
readonly settings: UiSettings;
|
|
338
|
+
/** The extension's logger. */
|
|
339
|
+
readonly log: Logger;
|
|
340
|
+
/**
|
|
341
|
+
* Writes `app.input.uiHasFocus`. The extension supplies a setter that duck-types the input
|
|
342
|
+
* service, so `@ignifx/ui` never imports `@ignifx/input` and the peer stays genuinely optional.
|
|
343
|
+
*/
|
|
344
|
+
readonly setInputFocus: (value: boolean) => void;
|
|
345
|
+
/**
|
|
346
|
+
* Writes `app.input.uiHasPointer`: `true` while at least one pointer is pressed on the overlay,
|
|
347
|
+
* so pointing-device actions read as released during a drag that began on UI. Same duck-typing
|
|
348
|
+
* as {@link UiHostOptions.setInputFocus}.
|
|
349
|
+
*/
|
|
350
|
+
readonly setInputPointer: (value: boolean) => void;
|
|
351
|
+
}
|
|
352
|
+
/**
|
|
353
|
+
* The DOM overlay host, reached as `app.ui`.
|
|
354
|
+
*
|
|
355
|
+
* @example
|
|
356
|
+
* ```ts
|
|
357
|
+
* const hud = app.ui.layer("hud");
|
|
358
|
+
* app.ui.scaling = "fit";
|
|
359
|
+
* app.ui.referenceResolution = [640, 360];
|
|
360
|
+
* ```
|
|
361
|
+
*
|
|
362
|
+
* @public
|
|
363
|
+
*/
|
|
364
|
+
export declare class UiHost {
|
|
365
|
+
#private;
|
|
366
|
+
/**
|
|
367
|
+
* Builds the host and, when there is a DOM, the root and the declared layers.
|
|
368
|
+
*
|
|
369
|
+
* @param options - The DOM target, the settings, the logger, and the focus setter.
|
|
370
|
+
*
|
|
371
|
+
* @internal
|
|
372
|
+
*/
|
|
373
|
+
constructor(options: UiHostOptions);
|
|
374
|
+
/**
|
|
375
|
+
* Builds the root, the layer elements, the focus watcher, and the resize subscriptions. Called
|
|
376
|
+
* once, from `UiSystem.onWorldCreated`; calling it again does nothing.
|
|
377
|
+
*
|
|
378
|
+
* @internal
|
|
379
|
+
*/
|
|
380
|
+
mount(): void;
|
|
381
|
+
/**
|
|
382
|
+
* The overlay root: an absolutely positioned `<div>` covering the canvas, `pointer-events: none`.
|
|
383
|
+
*
|
|
384
|
+
* @returns The root, or `null` when the app has no DOM overlay.
|
|
385
|
+
*/
|
|
386
|
+
get root(): HTMLDivElement | null;
|
|
387
|
+
/**
|
|
388
|
+
* Whether there is a DOM overlay at all. `false` under a headless app, an `OffscreenCanvas`, or a
|
|
389
|
+
* detached canvas — the three cases in which every other member is a no-op.
|
|
390
|
+
*
|
|
391
|
+
* @returns `true` when {@link UiHost.root} is an element.
|
|
392
|
+
*/
|
|
393
|
+
get isActive(): boolean;
|
|
394
|
+
/**
|
|
395
|
+
* How the overlay's coordinate system relates to the canvas. Writing it recomputes the layout
|
|
396
|
+
* immediately.
|
|
397
|
+
*
|
|
398
|
+
* @returns The current mode.
|
|
399
|
+
*/
|
|
400
|
+
get scaling(): UiScalingMode;
|
|
401
|
+
set scaling(value: UiScalingMode);
|
|
402
|
+
/**
|
|
403
|
+
* The `[width, height]` the `"fit"` mode scales to. Writing it recomputes the layout.
|
|
404
|
+
*
|
|
405
|
+
* @returns A copy of the current reference resolution.
|
|
406
|
+
*/
|
|
407
|
+
get referenceResolution(): readonly number[];
|
|
408
|
+
set referenceResolution(value: readonly number[]);
|
|
409
|
+
/**
|
|
410
|
+
* Whether the whole overlay is shown. Per-layer visibility is `app.ui.layer(name).visible`.
|
|
411
|
+
*
|
|
412
|
+
* @returns `true` while the overlay is shown.
|
|
413
|
+
*/
|
|
414
|
+
get visible(): boolean;
|
|
415
|
+
set visible(value: boolean);
|
|
416
|
+
/**
|
|
417
|
+
* The root's current size, scale, and offset, in the units the scaling mode chose.
|
|
418
|
+
*
|
|
419
|
+
* @returns The layout last computed.
|
|
420
|
+
*/
|
|
421
|
+
get layout(): UiLayout;
|
|
422
|
+
/**
|
|
423
|
+
* The conversion from render-target pixels — the space `Camera.worldToScreen`, `HudText`, and
|
|
424
|
+
* `app.renderer.captureScreenshot()` work in — to UI units.
|
|
425
|
+
*
|
|
426
|
+
* @returns The mapping last computed.
|
|
427
|
+
*/
|
|
428
|
+
get pixelMapping(): UiPixelMapping;
|
|
429
|
+
/**
|
|
430
|
+
* Every layer, back to front.
|
|
431
|
+
*
|
|
432
|
+
* @returns The layers, ordered by `zIndex`.
|
|
433
|
+
*/
|
|
434
|
+
get layers(): readonly UiLayer[];
|
|
435
|
+
/**
|
|
436
|
+
* Whether a pointer is currently pressed on an interactive element of the overlay.
|
|
437
|
+
*
|
|
438
|
+
* @remarks
|
|
439
|
+
* A click on a UI element never reaches gameplay in the first place: `@ignifx/input` reads
|
|
440
|
+
* `pointerdown` and `wheel` from the **canvas** (`packages/input/src/dom/pointer-source.ts`), and
|
|
441
|
+
* the overlay root is the canvas's sibling rather than its child, so a press that lands on a
|
|
442
|
+
* `pointer-events: auto` element is not on the canvas and is never queued. This flag covers the
|
|
443
|
+
* remaining case: `pointermove` and `pointerup` are read from the **window**, so a drag that
|
|
444
|
+
* started on a slider still moves `<Pointer>/delta`. A camera script that must ignore that reads
|
|
445
|
+
* this flag.
|
|
446
|
+
*
|
|
447
|
+
* @returns `true` while at least one pointer is down on the overlay.
|
|
448
|
+
*/
|
|
449
|
+
get pointerOverUi(): boolean;
|
|
450
|
+
/**
|
|
451
|
+
* Whether a text field currently owns the keyboard — the same value the host writes into
|
|
452
|
+
* `app.input.uiHasFocus`.
|
|
453
|
+
*
|
|
454
|
+
* @returns `true` while typing must not fire keyboard actions.
|
|
455
|
+
*/
|
|
456
|
+
get keyboardHasFocus(): boolean;
|
|
457
|
+
/**
|
|
458
|
+
* Emitted after every recomputation that changed the layout: a canvas resize, a device-pixel-ratio
|
|
459
|
+
* change, or a write to {@link UiHost.scaling} or {@link UiHost.referenceResolution}.
|
|
460
|
+
*
|
|
461
|
+
* @returns The signal.
|
|
462
|
+
*/
|
|
463
|
+
get onLayoutChanged(): SignalLike<UiLayout>;
|
|
464
|
+
/**
|
|
465
|
+
* Returns the named layer, creating it the first time it is asked for.
|
|
466
|
+
*
|
|
467
|
+
* @param name - The layer name.
|
|
468
|
+
* @param options - The stacking order and the initial visibility, used only on creation.
|
|
469
|
+
* @returns The layer.
|
|
470
|
+
*
|
|
471
|
+
* @example
|
|
472
|
+
* ```ts
|
|
473
|
+
* const menu = app.ui.layer("menu", { zIndex: 100 });
|
|
474
|
+
* ```
|
|
475
|
+
*/
|
|
476
|
+
layer(name: string, options?: UiLayerOptions): UiLayer;
|
|
477
|
+
/**
|
|
478
|
+
* Re-measures the canvas and rewrites the root's geometry.
|
|
479
|
+
*
|
|
480
|
+
* @remarks
|
|
481
|
+
* Called by the `ResizeObserver`, by the window's `resize` event — which is what a
|
|
482
|
+
* device-pixel-ratio change fires — and by every write to a scaling property. Games call it after
|
|
483
|
+
* changing the canvas's size by hand. A recomputation that produces the same layout writes
|
|
484
|
+
* nothing and emits nothing.
|
|
485
|
+
*/
|
|
486
|
+
refresh(): void;
|
|
487
|
+
/**
|
|
488
|
+
* Removes the overlay from the document and unsubscribes from everything.
|
|
489
|
+
*
|
|
490
|
+
* @internal
|
|
491
|
+
*/
|
|
492
|
+
dispose(): void;
|
|
493
|
+
}
|
|
494
|
+
//#endregion
|
|
495
|
+
//#region src/i18n/locale-file.d.ts
|
|
496
|
+
/**
|
|
497
|
+
* The `ignifx.i18n` document (`docs/architecture/06-serialization-and-scene-format.md` §6,
|
|
498
|
+
* `13-ui.md` §3: *"loaded from `.json` assets"*).
|
|
499
|
+
*
|
|
500
|
+
* One file carries **every** locale, keyed by BCP 47 tag, because a game with two languages should
|
|
501
|
+
* not need two fetches and a `locale` switch should not need a load at all:
|
|
502
|
+
*
|
|
503
|
+
* ```json
|
|
504
|
+
* {
|
|
505
|
+
* "format": "ignifx.i18n",
|
|
506
|
+
* "formatVersion": 1,
|
|
507
|
+
* "defaultLocale": "en",
|
|
508
|
+
* "locales": {
|
|
509
|
+
* "en": { "hud.score": "Score: {score}" },
|
|
510
|
+
* "fr": { "hud.score": "Score : {score}" }
|
|
511
|
+
* }
|
|
512
|
+
* }
|
|
513
|
+
* ```
|
|
514
|
+
*
|
|
515
|
+
* A game that would rather ship one file per locale loads several documents and calls
|
|
516
|
+
* `app.i18n.load` on each; the service merges them, later loads winning on a repeated key.
|
|
517
|
+
*/
|
|
518
|
+
/**
|
|
519
|
+
* The `format` discriminator every translation document carries.
|
|
520
|
+
*
|
|
521
|
+
* @public
|
|
522
|
+
*/
|
|
523
|
+
export declare const I18N_FORMAT = "ignifx.i18n";
|
|
524
|
+
/**
|
|
525
|
+
* The `formatVersion` this build writes and is the only one it can read. Before 1.0 the number
|
|
526
|
+
* stays `1` and an incompatible change invalidates files rather than migrating them
|
|
527
|
+
* (`CONSTITUTION.md` §4.2); a file declaring anything else is rejected with `IGX-1302`.
|
|
528
|
+
*
|
|
529
|
+
* @public
|
|
530
|
+
*/
|
|
531
|
+
export declare const I18N_FORMAT_VERSION = 1;
|
|
532
|
+
/**
|
|
533
|
+
* The asset type translation documents are registered under.
|
|
534
|
+
*
|
|
535
|
+
* @public
|
|
536
|
+
*/
|
|
537
|
+
export declare const I18N_ASSET_TYPE = "i18n";
|
|
538
|
+
/**
|
|
539
|
+
* The file extensions the translation loader claims.
|
|
540
|
+
*
|
|
541
|
+
* @public
|
|
542
|
+
*/
|
|
543
|
+
export declare const I18N_FILE_EXTENSIONS: readonly string[];
|
|
544
|
+
/**
|
|
545
|
+
* A parsed `ignifx.i18n` document.
|
|
546
|
+
*
|
|
547
|
+
* @public
|
|
548
|
+
*/
|
|
549
|
+
interface LocaleDocument {
|
|
550
|
+
/** The locale used when nothing else selected one. */
|
|
551
|
+
readonly defaultLocale: string;
|
|
552
|
+
/** Every locale's message table, keyed by BCP 47 tag. */
|
|
553
|
+
readonly locales: Readonly<Record<string, Readonly<Record<string, string>>>>;
|
|
554
|
+
}
|
|
555
|
+
/**
|
|
556
|
+
* Parses and validates a translation document.
|
|
557
|
+
*
|
|
558
|
+
* @param value - The parsed JSON.
|
|
559
|
+
* @param address - The address it came from, for the error's context.
|
|
560
|
+
* @returns The document.
|
|
561
|
+
* @throws IgnifxError with code `IGX-1302` when the header is missing, the version does not match,
|
|
562
|
+
* or the file declares no locales.
|
|
563
|
+
*
|
|
564
|
+
* @example
|
|
565
|
+
* ```ts
|
|
566
|
+
* const document = parseLocaleFile(
|
|
567
|
+
* { format: "ignifx.i18n", formatVersion: 1, defaultLocale: "en", locales: { en: { ok: "OK" } } },
|
|
568
|
+
* "ui/strings.i18n.json",
|
|
569
|
+
* );
|
|
570
|
+
* document.locales["en"]?.["ok"]; // "OK"
|
|
571
|
+
* ```
|
|
572
|
+
*
|
|
573
|
+
* @public
|
|
574
|
+
*/
|
|
575
|
+
export declare function parseLocaleFile(value: unknown, address: string): LocaleDocument;
|
|
576
|
+
/**
|
|
577
|
+
* A loaded translation document (`docs/architecture/05-assets-and-loading.md` §5).
|
|
578
|
+
*
|
|
579
|
+
* @remarks
|
|
580
|
+
* Pure data: it loads identically under Node and in a browser and has nothing to release.
|
|
581
|
+
*
|
|
582
|
+
* @example
|
|
583
|
+
* ```ts
|
|
584
|
+
* const strings = await app.assets.loadAsync<LocaleAsset>("ui/strings.i18n.json");
|
|
585
|
+
* strings.value.availableLocales; // ["en", "fr"]
|
|
586
|
+
* ```
|
|
587
|
+
*
|
|
588
|
+
* @public
|
|
589
|
+
*/
|
|
590
|
+
export declare class LocaleAsset {
|
|
591
|
+
/** The type name the asset service registers translation documents under. */
|
|
592
|
+
static assetType: string;
|
|
593
|
+
/** The address the document was loaded from. */
|
|
594
|
+
readonly address: string;
|
|
595
|
+
/** The parsed document. */
|
|
596
|
+
readonly document: LocaleDocument;
|
|
597
|
+
/**
|
|
598
|
+
* Wraps a parsed document. The `i18n` loader constructs these.
|
|
599
|
+
*
|
|
600
|
+
* @param address - The address it was loaded from.
|
|
601
|
+
* @param document - The parsed document.
|
|
602
|
+
*
|
|
603
|
+
* @internal
|
|
604
|
+
*/
|
|
605
|
+
constructor(address: string, document: LocaleDocument);
|
|
606
|
+
/**
|
|
607
|
+
* Every locale the document declares, sorted.
|
|
608
|
+
*
|
|
609
|
+
* @returns The BCP 47 tags.
|
|
610
|
+
*/
|
|
611
|
+
get availableLocales(): readonly string[];
|
|
612
|
+
}
|
|
613
|
+
/**
|
|
614
|
+
* The schema a translation document is described and validated against for tooling.
|
|
615
|
+
*
|
|
616
|
+
* @remarks
|
|
617
|
+
* The loader validates with {@link parseLocaleFile}, which produces an actionable `IGX-1302`
|
|
618
|
+
* naming the file; this schema is what `pnpm docs:schemas` renders and what a JSON Schema for an
|
|
619
|
+
* editor is generated from — the split `@ignifx/2d`'s `file-schemas.ts` documents.
|
|
620
|
+
*
|
|
621
|
+
* @returns The schema, built fresh so no module holds state (`CONSTITUTION.md` §3.5).
|
|
622
|
+
*
|
|
623
|
+
* @public
|
|
624
|
+
*/
|
|
625
|
+
export declare function localeFileSchema(): Schema;
|
|
626
|
+
/**
|
|
627
|
+
* Describes the `ignifx.i18n` file format for the documentation harness.
|
|
628
|
+
*
|
|
629
|
+
* @returns The record `pnpm docs:schemas` renders.
|
|
630
|
+
*
|
|
631
|
+
* @public
|
|
632
|
+
*/
|
|
633
|
+
export declare function describeLocaleFileFormat(): SchemaDescription;
|
|
634
|
+
/**
|
|
635
|
+
* The JSON Schema a tool validates a `.i18n.json` document against.
|
|
636
|
+
*
|
|
637
|
+
* @returns The JSON Schema object.
|
|
638
|
+
*
|
|
639
|
+
* @public
|
|
640
|
+
*/
|
|
641
|
+
export declare function localeJsonSchema(): JsonSchemaObject;
|
|
642
|
+
//#endregion
|
|
643
|
+
//#region src/i18n/message.d.ts
|
|
644
|
+
/**
|
|
645
|
+
* What a message's parameters may be.
|
|
646
|
+
*
|
|
647
|
+
* @public
|
|
648
|
+
*/
|
|
649
|
+
type MessageParams = Readonly<Record<string, string | number>>;
|
|
650
|
+
/**
|
|
651
|
+
* Chooses a plural category for a number, in one locale.
|
|
652
|
+
*
|
|
653
|
+
* @public
|
|
654
|
+
*/
|
|
655
|
+
type PluralSelector = (value: number) => string;
|
|
656
|
+
/**
|
|
657
|
+
* A run of literal text.
|
|
658
|
+
*
|
|
659
|
+
* @public
|
|
660
|
+
*/
|
|
661
|
+
interface TextNode {
|
|
662
|
+
/** The discriminator. */
|
|
663
|
+
readonly kind: "text";
|
|
664
|
+
/** The literal. */
|
|
665
|
+
readonly value: string;
|
|
666
|
+
}
|
|
667
|
+
/**
|
|
668
|
+
* A `{name}` substitution.
|
|
669
|
+
*
|
|
670
|
+
* @public
|
|
671
|
+
*/
|
|
672
|
+
interface ArgumentNode {
|
|
673
|
+
/** The discriminator. */
|
|
674
|
+
readonly kind: "argument";
|
|
675
|
+
/** The parameter name. */
|
|
676
|
+
readonly name: string;
|
|
677
|
+
}
|
|
678
|
+
/**
|
|
679
|
+
* A `{name, plural, …}` selection.
|
|
680
|
+
*
|
|
681
|
+
* @public
|
|
682
|
+
*/
|
|
683
|
+
interface PluralNode {
|
|
684
|
+
/** The discriminator. */
|
|
685
|
+
readonly kind: "plural";
|
|
686
|
+
/** The parameter name holding the number. */
|
|
687
|
+
readonly name: string;
|
|
688
|
+
/** The branches, keyed by `"=0"`-style exact matches and by plural category. */
|
|
689
|
+
readonly branches: ReadonlyMap<string, readonly MessageNode[]>;
|
|
690
|
+
}
|
|
691
|
+
/**
|
|
692
|
+
* One piece of a parsed message.
|
|
693
|
+
*
|
|
694
|
+
* @public
|
|
695
|
+
*/
|
|
696
|
+
type MessageNode = TextNode | ArgumentNode | PluralNode;
|
|
697
|
+
/**
|
|
698
|
+
* A parsed message, or the reason it could not be parsed.
|
|
699
|
+
*
|
|
700
|
+
* @public
|
|
701
|
+
*/
|
|
702
|
+
interface MessagePattern {
|
|
703
|
+
/** The nodes to render. Holds the raw pattern as one text node when {@link MessagePattern.error} is set. */
|
|
704
|
+
readonly nodes: readonly MessageNode[];
|
|
705
|
+
/** Why the pattern could not be read, or `null` when it parsed. */
|
|
706
|
+
readonly error: string | null;
|
|
707
|
+
}
|
|
708
|
+
/**
|
|
709
|
+
* Parses one message pattern.
|
|
710
|
+
*
|
|
711
|
+
* @param pattern - The pattern, as written in the `.i18n.json` document.
|
|
712
|
+
* @returns The parsed nodes, or the raw text plus the reason it could not be parsed.
|
|
713
|
+
*
|
|
714
|
+
* @example
|
|
715
|
+
* ```ts
|
|
716
|
+
* parseMessage("{count, plural, one {# life} other {# lives}}").error; // null
|
|
717
|
+
* parseMessage("{count, plural, one {# life}}").error; // "plural count has no other branch"
|
|
718
|
+
* ```
|
|
719
|
+
*
|
|
720
|
+
* @public
|
|
721
|
+
*/
|
|
722
|
+
export declare function parseMessage(pattern: string): MessagePattern;
|
|
723
|
+
/**
|
|
724
|
+
* Builds the plural selector for a locale.
|
|
725
|
+
*
|
|
726
|
+
* @remarks
|
|
727
|
+
* `Intl.PluralRules` is present in every browser and in Node, but a stripped runtime without
|
|
728
|
+
* `Intl` still has to work, so the fallback is English's two-category rule.
|
|
729
|
+
*
|
|
730
|
+
* @param locale - The BCP 47 locale tag.
|
|
731
|
+
* @returns A function from a number to a plural category.
|
|
732
|
+
*
|
|
733
|
+
* @example
|
|
734
|
+
* ```ts
|
|
735
|
+
* createPluralSelector("en")(1); // "one"
|
|
736
|
+
* ```
|
|
737
|
+
*
|
|
738
|
+
* @public
|
|
739
|
+
*/
|
|
740
|
+
export declare function createPluralSelector(locale: string): PluralSelector;
|
|
741
|
+
/**
|
|
742
|
+
* Renders a parsed message.
|
|
743
|
+
*
|
|
744
|
+
* @param pattern - The parsed pattern.
|
|
745
|
+
* @param params - The values to substitute.
|
|
746
|
+
* @param select - The active locale's plural selector.
|
|
747
|
+
* @returns The rendered string.
|
|
748
|
+
*
|
|
749
|
+
* @example
|
|
750
|
+
* ```ts
|
|
751
|
+
* const pattern = parseMessage("{count, plural, one {# life} other {# lives}}");
|
|
752
|
+
* renderMessage(pattern, { count: 3 }, createPluralSelector("en")); // "3 lives"
|
|
753
|
+
* ```
|
|
754
|
+
*
|
|
755
|
+
* @public
|
|
756
|
+
*/
|
|
757
|
+
export declare function renderMessage(pattern: MessagePattern, params: MessageParams, select: PluralSelector): string;
|
|
758
|
+
//#endregion
|
|
759
|
+
//#region src/i18n/i18n-service.d.ts
|
|
760
|
+
/**
|
|
761
|
+
* What {@link I18nService} is constructed with.
|
|
762
|
+
*
|
|
763
|
+
* @internal
|
|
764
|
+
*/
|
|
765
|
+
interface I18nServiceOptions {
|
|
766
|
+
/** The extension's logger. */
|
|
767
|
+
readonly log: Logger;
|
|
768
|
+
/** The locale the app starts in, before any document is loaded. */
|
|
769
|
+
readonly locale: string;
|
|
770
|
+
}
|
|
771
|
+
/**
|
|
772
|
+
* The localization service, reached as `app.i18n`.
|
|
773
|
+
*
|
|
774
|
+
* @example
|
|
775
|
+
* ```ts
|
|
776
|
+
* await app.i18n.load(app.assets.load<LocaleAsset>("ui/strings.i18n.json"));
|
|
777
|
+
* app.i18n.locale = "fr";
|
|
778
|
+
* app.i18n.t("hud.lives", { count: 3 });
|
|
779
|
+
* ```
|
|
780
|
+
*
|
|
781
|
+
* @public
|
|
782
|
+
*/
|
|
783
|
+
export declare class I18nService {
|
|
784
|
+
#private;
|
|
785
|
+
/**
|
|
786
|
+
* Builds an empty service. The extension does this; a game never constructs one.
|
|
787
|
+
*
|
|
788
|
+
* @param options - The logger and the starting locale.
|
|
789
|
+
*
|
|
790
|
+
* @internal
|
|
791
|
+
*/
|
|
792
|
+
constructor(options: I18nServiceOptions);
|
|
793
|
+
/**
|
|
794
|
+
* The active locale. Writing a locale no loaded document declares throws `IGX-1303`, because a
|
|
795
|
+
* silent no-op there is a bug that only shows up as untranslated text much later.
|
|
796
|
+
*
|
|
797
|
+
* @returns The BCP 47 tag.
|
|
798
|
+
* @throws IgnifxError with code `IGX-1303` when no loaded document declares the tag.
|
|
799
|
+
*/
|
|
800
|
+
get locale(): string;
|
|
801
|
+
set locale(value: string);
|
|
802
|
+
/**
|
|
803
|
+
* The locale a key falls back to when the active locale has no entry for it. Set from the first
|
|
804
|
+
* document's `defaultLocale`.
|
|
805
|
+
*
|
|
806
|
+
* @returns The BCP 47 tag.
|
|
807
|
+
*/
|
|
808
|
+
get fallbackLocale(): string;
|
|
809
|
+
set fallbackLocale(value: string);
|
|
810
|
+
/**
|
|
811
|
+
* Every locale any loaded document declares, sorted.
|
|
812
|
+
*
|
|
813
|
+
* @returns The BCP 47 tags.
|
|
814
|
+
*/
|
|
815
|
+
get availableLocales(): readonly string[];
|
|
816
|
+
/**
|
|
817
|
+
* Emitted after {@link I18nService.locale} changed. UI that caches rendered strings — `HudText`
|
|
818
|
+
* does — redraws from here.
|
|
819
|
+
*
|
|
820
|
+
* @returns The signal.
|
|
821
|
+
*/
|
|
822
|
+
get onLocaleChanged(): SignalLike<string>;
|
|
823
|
+
/**
|
|
824
|
+
* Merges a translation document into the service.
|
|
825
|
+
*
|
|
826
|
+
* @remarks
|
|
827
|
+
* Accepts a loaded {@link LocaleAsset} or the handle of one, in which case the merge happens when
|
|
828
|
+
* the handle settles. Later loads win on a repeated key, which is what makes a per-locale
|
|
829
|
+
* download or a downloadable language pack work. The first document loaded also sets
|
|
830
|
+
* {@link I18nService.fallbackLocale} and, when the app is still on its starting locale and the
|
|
831
|
+
* document does not declare it, moves the active locale to the document's `defaultLocale`.
|
|
832
|
+
*
|
|
833
|
+
* @param source - A loaded document, or its handle.
|
|
834
|
+
* @returns A promise that settles once the document has been merged.
|
|
835
|
+
*
|
|
836
|
+
* @example
|
|
837
|
+
* ```ts
|
|
838
|
+
* using strings = app.assets.load<LocaleAsset>("ui/strings.i18n.json");
|
|
839
|
+
* await app.i18n.load(strings);
|
|
840
|
+
* ```
|
|
841
|
+
*/
|
|
842
|
+
load(source: AssetHandle<LocaleAsset> | LocaleAsset): Promise<void>;
|
|
843
|
+
/**
|
|
844
|
+
* Whether the active locale, or the fallback, has an entry for a key.
|
|
845
|
+
*
|
|
846
|
+
* @param key - The message key.
|
|
847
|
+
* @returns `true` when {@link I18nService.t} will find a message.
|
|
848
|
+
*/
|
|
849
|
+
has(key: string): boolean;
|
|
850
|
+
/**
|
|
851
|
+
* Renders a message.
|
|
852
|
+
*
|
|
853
|
+
* @param key - The message key.
|
|
854
|
+
* @param params - The values `{name}` placeholders and plural selectors read.
|
|
855
|
+
* @returns The rendered message, or the key itself when no document declares it.
|
|
856
|
+
*
|
|
857
|
+
* @example
|
|
858
|
+
* ```ts
|
|
859
|
+
* app.i18n.t("hud.lives", { count: 1 }); // "1 life"
|
|
860
|
+
* app.i18n.t("hud.lives", { count: 4 }); // "4 lives"
|
|
861
|
+
* ```
|
|
862
|
+
*/
|
|
863
|
+
t(key: string, params?: MessageParams): string;
|
|
864
|
+
/**
|
|
865
|
+
* Drops every loaded document.
|
|
866
|
+
*
|
|
867
|
+
* @internal
|
|
868
|
+
*/
|
|
869
|
+
clear(): void;
|
|
870
|
+
/**
|
|
871
|
+
* Releases everything the service holds.
|
|
872
|
+
*
|
|
873
|
+
* @internal
|
|
874
|
+
*/
|
|
875
|
+
dispose(): void;
|
|
876
|
+
}
|
|
877
|
+
//#endregion
|
|
878
|
+
//#region src/augmentation.d.ts
|
|
879
|
+
/**
|
|
880
|
+
* The typed entry points (`docs/architecture/03-scripting-and-components.md` §7). Declaration
|
|
881
|
+
* merging is what makes `this.app.ui` and `this.app.i18n` fully typed when `@ignifx/ui` is
|
|
882
|
+
* installed and a compile error when it is not.
|
|
883
|
+
*
|
|
884
|
+
* Two mechanics carry over from `@ignifx/input` and `@ignifx/2d`, both measured rather than assumed:
|
|
885
|
+
*
|
|
886
|
+
* - The module **must** import something from `@ignifx/core`. A `declare module "@ignifx/core"`
|
|
887
|
+
* block in a file that never imports the module is `TS2664: Invalid module name in augmentation`
|
|
888
|
+
* under both `tsc --build` and TypeDoc; importing the `ExtensionContext` type used below is
|
|
889
|
+
* enough to bring the module into the program.
|
|
890
|
+
* - The barrel **must** name this module in a bare `import "./augmentation.js"`. Declaration
|
|
891
|
+
* bundling drops a module whose only exports are unreferenced from the public surface, which
|
|
892
|
+
* silently takes the augmentation out of `dist/index.d.ts` with it. The bare import is a
|
|
893
|
+
* type-only side effect: the emitted JavaScript keeps no statement for it, so `sideEffects: false`
|
|
894
|
+
* stays honest.
|
|
895
|
+
*/
|
|
896
|
+
declare module "@ignifx/core" {
|
|
897
|
+
interface App {
|
|
898
|
+
/**
|
|
899
|
+
* The DOM overlay host (`docs/architecture/13-ui.md` §1): the root over the canvas, the named
|
|
900
|
+
* layers, the scaling modes, the safe-area variables, and the focus flag.
|
|
901
|
+
*/
|
|
902
|
+
readonly ui: UiHost;
|
|
903
|
+
/**
|
|
904
|
+
* The localization service (`docs/architecture/13-ui.md` §3): `.i18n.json` documents,
|
|
905
|
+
* `{name}` interpolation, ICU-style plurals, and the active locale.
|
|
906
|
+
*/
|
|
907
|
+
readonly i18n: I18nService;
|
|
908
|
+
}
|
|
909
|
+
}
|
|
910
|
+
//#endregion
|
|
911
|
+
//#region src/dom/focus.d.ts
|
|
912
|
+
/**
|
|
913
|
+
* Focus routing (`docs/architecture/13-ui.md` §1, `08-input.md` §5).
|
|
914
|
+
*
|
|
915
|
+
* ## What `@ignifx/input` does and does not do
|
|
916
|
+
*
|
|
917
|
+
* `InputService.uiHasFocus` is a **plain settable property**; its own documentation says so —
|
|
918
|
+
* "`@ignifx/ui` assigns it"* (`packages/input/src/service/input-service.ts` 340-349). Nothing in
|
|
919
|
+
* `@ignifx/input` watches the DOM for it: `FocusSource` subscribes only to `blur` and
|
|
920
|
+
* `visibilitychange`, and translates both into one `releaseAll`. So the policy for *what counts as
|
|
921
|
+
* a focused text field* is defined here, by this module, and this module is the only thing that
|
|
922
|
+
* ever writes the flag. While it is `true`, `Binding.readRef` reports every keyboard control as
|
|
923
|
+
* released (`packages/input/src/bindings/binding.ts` 330 and 350), which is what makes typing in a
|
|
924
|
+
* field stop firing actions; pointer and gamepad controls are untouched.
|
|
925
|
+
*
|
|
926
|
+
* ## The policy
|
|
927
|
+
*
|
|
928
|
+
* An element takes the keyboard when it is a text-entry element: a `<textarea>`, a `<select>`, a
|
|
929
|
+
* `contenteditable` element, or an `<input>` whose type is not one of the button-like or
|
|
930
|
+
* slider-like types (which games legitimately want to drive with the keyboard *and* have the
|
|
931
|
+
* player use). Two data attributes override the guess in either direction, for the widgets a
|
|
932
|
+
* framework builds out of `<div role="textbox">` and for the search box a game wants to keep
|
|
933
|
+
* transparent to gameplay:
|
|
934
|
+
*
|
|
935
|
+
* - `data-ignifx-focus="capture"` — always takes the keyboard.
|
|
936
|
+
* - `data-ignifx-focus="ignore"` — never takes it.
|
|
937
|
+
*/
|
|
938
|
+
/**
|
|
939
|
+
* The attribute that overrides the editability guess in either direction.
|
|
940
|
+
*
|
|
941
|
+
* @public
|
|
942
|
+
*/
|
|
943
|
+
export declare const UI_FOCUS_ATTRIBUTE = "data-ignifx-focus";
|
|
944
|
+
/**
|
|
945
|
+
* Reports whether a focused node is a text-entry element, and therefore owns the keyboard.
|
|
946
|
+
*
|
|
947
|
+
* @remarks
|
|
948
|
+
* Deliberately structural rather than `instanceof HTMLInputElement`: the same function then answers
|
|
949
|
+
* for a real element in Chromium and for the fake DOM the node suite builds, and two documents in
|
|
950
|
+
* one page (an `<iframe>`) do not need their constructors to match.
|
|
951
|
+
*
|
|
952
|
+
* @param node - The node that just received focus, or `null`.
|
|
953
|
+
* @returns `true` when typing into it must stop keyboard actions from firing.
|
|
954
|
+
*
|
|
955
|
+
* @example
|
|
956
|
+
* ```ts
|
|
957
|
+
* const field = document.createElement("input");
|
|
958
|
+
* isEditableElement(field); // true — an <input> with no type is a text field
|
|
959
|
+
* ```
|
|
960
|
+
*
|
|
961
|
+
* @public
|
|
962
|
+
*/
|
|
963
|
+
export declare function isEditableElement(node: unknown): boolean;
|
|
964
|
+
//#endregion
|
|
965
|
+
//#region src/dom/styles.d.ts
|
|
966
|
+
/**
|
|
967
|
+
* The one stylesheet `@ignifx/ui` injects, and the class names it defines
|
|
968
|
+
* (`docs/architecture/13-ui.md` §3: *"plain DOM helper classes with no styling opinions beyond a
|
|
969
|
+
* minimal stylesheet; templates ship their own CSS"*).
|
|
970
|
+
*
|
|
971
|
+
* The rules do only what a game cannot reasonably be asked to repeat: position the root over the
|
|
972
|
+
* canvas, make it click-through, and give the helper widgets a shape that is visible before any
|
|
973
|
+
* game CSS loads. No rule uses `!important`, and every rule is a single class selector — except the
|
|
974
|
+
* two that carry a state a game must not be able to defeat by accident: `.ignifx-ui-menu[hidden]`,
|
|
975
|
+
* which is what actually hides a menu, and the `[data-focused]` / `[data-disabled]` row states,
|
|
976
|
+
* which a game restyles by writing the same selector.
|
|
977
|
+
*/
|
|
978
|
+
/**
|
|
979
|
+
* The `id` of the injected `<style>` element, so a second app in one document reuses it.
|
|
980
|
+
*
|
|
981
|
+
* @public
|
|
982
|
+
*/
|
|
983
|
+
export declare const UI_STYLE_ELEMENT_ID = "ignifx-ui-styles";
|
|
984
|
+
/**
|
|
985
|
+
* The `z-index` a `Dialog` is drawn at inside its layer.
|
|
986
|
+
*
|
|
987
|
+
* @remarks
|
|
988
|
+
* A dialog is modal, and a modal that paints under the panel that opened it swallows every click
|
|
989
|
+
* on that panel. Siblings with no `z-index` paint in DOM order, so a `Dialog` created before a
|
|
990
|
+
* `Menu` in the same layer would lose; giving every dialog one number puts it above every other
|
|
991
|
+
* root of its layer whatever order they were built in. Two dialogs in one layer still stack in DOM
|
|
992
|
+
* order, and `DialogOptions.zIndex` overrides the number for a dialog that must sit elsewhere.
|
|
993
|
+
*
|
|
994
|
+
* @public
|
|
995
|
+
*/
|
|
996
|
+
export declare const UI_DIALOG_Z_INDEX = 1e3;
|
|
997
|
+
/**
|
|
998
|
+
* The class names the host and the helper widgets set, so a template's CSS can target them without
|
|
999
|
+
* guessing (`docs/architecture/13-ui.md` §3).
|
|
1000
|
+
*
|
|
1001
|
+
* @public
|
|
1002
|
+
*/
|
|
1003
|
+
export declare const UI_CLASS_NAMES: {
|
|
1004
|
+
/** The overlay root. */
|
|
1005
|
+
readonly root: "ignifx-ui-root";
|
|
1006
|
+
/** A named layer inside the root. */
|
|
1007
|
+
readonly layer: "ignifx-ui-layer";
|
|
1008
|
+
/** Anything that should receive pointer events; the root does not. */
|
|
1009
|
+
readonly interactive: "ignifx-ui-interactive";
|
|
1010
|
+
/** A `Dialog`'s outermost element. */
|
|
1011
|
+
readonly dialog: "ignifx-ui-dialog";
|
|
1012
|
+
/** A `Dialog`'s backdrop. */
|
|
1013
|
+
readonly dialogBackdrop: "ignifx-ui-dialog-backdrop";
|
|
1014
|
+
/** A `Dialog`'s panel. */
|
|
1015
|
+
readonly dialogPanel: "ignifx-ui-dialog-panel";
|
|
1016
|
+
/** A `Dialog`'s title. */
|
|
1017
|
+
readonly dialogTitle: "ignifx-ui-dialog-title";
|
|
1018
|
+
/** A `Dialog`'s message. */
|
|
1019
|
+
readonly dialogMessage: "ignifx-ui-dialog-message";
|
|
1020
|
+
/** A `Dialog`'s button row. */
|
|
1021
|
+
readonly dialogButtons: "ignifx-ui-dialog-buttons";
|
|
1022
|
+
/** One `Dialog` button. */
|
|
1023
|
+
readonly dialogButton: "ignifx-ui-dialog-button";
|
|
1024
|
+
/** A `Menu`'s outermost panel. */
|
|
1025
|
+
readonly menu: "ignifx-ui-menu";
|
|
1026
|
+
/** A `Menu`'s heading. */
|
|
1027
|
+
readonly menuTitle: "ignifx-ui-menu-title";
|
|
1028
|
+
/** A `Menu`'s subtitle. */
|
|
1029
|
+
readonly menuSubtitle: "ignifx-ui-menu-subtitle";
|
|
1030
|
+
/** The list a `Menu`'s rows are appended to. */
|
|
1031
|
+
readonly menuRows: "ignifx-ui-menu-rows";
|
|
1032
|
+
/** One selectable `Menu` row. */
|
|
1033
|
+
readonly menuRow: "ignifx-ui-menu-row";
|
|
1034
|
+
/** A `Menu` row's left-hand text. */
|
|
1035
|
+
readonly menuRowLabel: "ignifx-ui-menu-row-label";
|
|
1036
|
+
/** A `Menu` row's right-hand text. */
|
|
1037
|
+
readonly menuRowValue: "ignifx-ui-menu-row-value";
|
|
1038
|
+
/** A `Menu` slider row's range input. */
|
|
1039
|
+
readonly menuRowSlider: "ignifx-ui-menu-row-slider";
|
|
1040
|
+
/** A `Menu`'s `"heading"` row. */
|
|
1041
|
+
readonly menuHeading: "ignifx-ui-menu-heading";
|
|
1042
|
+
/** A `Menu`'s `"separator"` row. */
|
|
1043
|
+
readonly menuSeparator: "ignifx-ui-menu-separator";
|
|
1044
|
+
/** A `Toast`'s stack container. */
|
|
1045
|
+
readonly toastStack: "ignifx-ui-toasts";
|
|
1046
|
+
/** One toast. */
|
|
1047
|
+
readonly toast: "ignifx-ui-toast";
|
|
1048
|
+
/** A `LoadingScreen`'s outermost element. */
|
|
1049
|
+
readonly loading: "ignifx-ui-loading";
|
|
1050
|
+
/** A `LoadingScreen`'s label. */
|
|
1051
|
+
readonly loadingLabel: "ignifx-ui-loading-label";
|
|
1052
|
+
/** A `LoadingScreen`'s progress track. */
|
|
1053
|
+
readonly loadingTrack: "ignifx-ui-loading-track";
|
|
1054
|
+
/** A `LoadingScreen`'s progress bar. */
|
|
1055
|
+
readonly loadingBar: "ignifx-ui-loading-bar";
|
|
1056
|
+
/** A `VirtualJoystick`'s outer pad. */
|
|
1057
|
+
readonly joystick: "ignifx-ui-joystick";
|
|
1058
|
+
/** A `VirtualJoystick`'s knob. */
|
|
1059
|
+
readonly joystickKnob: "ignifx-ui-joystick-knob";
|
|
1060
|
+
/** A `VirtualButton`. */
|
|
1061
|
+
readonly button: "ignifx-ui-button";
|
|
1062
|
+
};
|
|
1063
|
+
/**
|
|
1064
|
+
* The CSS custom properties the root carries, so game CSS can read the safe area and the current
|
|
1065
|
+
* scale without measuring anything (`docs/architecture/13-ui.md` §1).
|
|
1066
|
+
*
|
|
1067
|
+
* @public
|
|
1068
|
+
*/
|
|
1069
|
+
export declare const UI_CSS_VARIABLES: {
|
|
1070
|
+
/** The top safe-area inset, from `env(safe-area-inset-top)`. */
|
|
1071
|
+
readonly safeTop: "--ignifx-safe-top";
|
|
1072
|
+
/** The right safe-area inset. */
|
|
1073
|
+
readonly safeRight: "--ignifx-safe-right";
|
|
1074
|
+
/** The bottom safe-area inset. */
|
|
1075
|
+
readonly safeBottom: "--ignifx-safe-bottom";
|
|
1076
|
+
/** The left safe-area inset. */
|
|
1077
|
+
readonly safeLeft: "--ignifx-safe-left";
|
|
1078
|
+
/** The uniform scale the root is drawn at, as a bare number. */
|
|
1079
|
+
readonly scale: "--ignifx-ui-scale";
|
|
1080
|
+
};
|
|
1081
|
+
//#endregion
|
|
1082
|
+
//#region src/errors.d.ts
|
|
1083
|
+
/**
|
|
1084
|
+
* The diagnostic codes `@ignifx/ui` owns. The UI subsystem sits in the `13` range of
|
|
1085
|
+
* `docs/architecture/15-devtools-and-diagnostics.md` §1 — *"`13xx` UI"* — so every code reads
|
|
1086
|
+
* `IGX-13##`. `@ignifx/ui` is the only package in the range and owns all of it.
|
|
1087
|
+
*
|
|
1088
|
+
* The table lives here rather than in `@ignifx/core`'s `CoreErrorCode`: an extension owns its own
|
|
1089
|
+
* codes and hands them to the app through `ExtensionContext.registerErrorCodes`
|
|
1090
|
+
* (`docs/architecture/04-extensions.md` §3).
|
|
1091
|
+
*/
|
|
1092
|
+
/**
|
|
1093
|
+
* Every diagnostic code `@ignifx/ui` can throw or log, keyed by an intention-revealing name so call
|
|
1094
|
+
* sites read as prose and the compiler catches typos (coding standards §5.2).
|
|
1095
|
+
*
|
|
1096
|
+
* @example
|
|
1097
|
+
* ```ts
|
|
1098
|
+
* throw uiError(UiErrorCode.unknownLayer, "hud is not a declared UI layer.", {
|
|
1099
|
+
* context: { layer: "hud" },
|
|
1100
|
+
* });
|
|
1101
|
+
* ```
|
|
1102
|
+
*
|
|
1103
|
+
* @public
|
|
1104
|
+
*/
|
|
1105
|
+
export declare const UiErrorCode: {
|
|
1106
|
+
/** A second `ui()` extension was registered on one app. */
|
|
1107
|
+
readonly duplicateExtension: "IGX-1301";
|
|
1108
|
+
/** A `.i18n.json` file is not an `ignifx.i18n` document this build can read. */
|
|
1109
|
+
readonly invalidLocaleFile: "IGX-1302";
|
|
1110
|
+
/** `app.i18n.locale` was set to a locale the loaded document does not declare. */
|
|
1111
|
+
readonly unknownLocale: "IGX-1303";
|
|
1112
|
+
/** A message pattern could not be parsed: an unbalanced brace or an unknown argument form. */
|
|
1113
|
+
readonly invalidMessagePattern: "IGX-1304";
|
|
1114
|
+
/** A widget that needs `@ignifx/input` was built on an app that did not register it. */
|
|
1115
|
+
readonly inputExtensionMissing: "IGX-1305";
|
|
1116
|
+
/** A `WorldText` or `HudText` was asked to draw before its `font` asset was assigned. */
|
|
1117
|
+
readonly missingFont: "IGX-1306";
|
|
1118
|
+
/** A DOM-only member was reached on a host with no document, and did nothing. */
|
|
1119
|
+
readonly headlessNoOp: "IGX-1307";
|
|
1120
|
+
/** A `WorldText` needed a scene renderable after the render scene had already been built. */
|
|
1121
|
+
readonly sceneAlreadyBuilt: "IGX-1308";
|
|
1122
|
+
};
|
|
1123
|
+
/**
|
|
1124
|
+
* The union of the codes the `UiErrorCode` table declares.
|
|
1125
|
+
*
|
|
1126
|
+
* @public
|
|
1127
|
+
*/
|
|
1128
|
+
export type UiErrorCode = (typeof UiErrorCode)[keyof typeof UiErrorCode];
|
|
1129
|
+
/**
|
|
1130
|
+
* The one-line message template of every code, as `ExtensionContext.registerErrorCodes` wants it.
|
|
1131
|
+
* Context keys appear in braces, matching the core table's convention.
|
|
1132
|
+
*
|
|
1133
|
+
* @public
|
|
1134
|
+
*/
|
|
1135
|
+
export declare const UI_ERROR_MESSAGES: Readonly<Record<string, string>>;
|
|
1136
|
+
/**
|
|
1137
|
+
* Options accepted by {@link uiError}: the same subset of `IgnifxErrorOptions` this package uses.
|
|
1138
|
+
*
|
|
1139
|
+
* @public
|
|
1140
|
+
*/
|
|
1141
|
+
interface UiErrorOptions {
|
|
1142
|
+
/** Identifiers that locate the failure. */
|
|
1143
|
+
readonly context?: ErrorContext;
|
|
1144
|
+
/** One sentence telling the developer what to do about it. */
|
|
1145
|
+
readonly hint?: string;
|
|
1146
|
+
/** The failure being wrapped, when there is one. */
|
|
1147
|
+
readonly cause?: unknown;
|
|
1148
|
+
}
|
|
1149
|
+
/**
|
|
1150
|
+
* Builds an `IgnifxError` carrying one of this package's codes.
|
|
1151
|
+
*
|
|
1152
|
+
* @param code - The code from the `UiErrorCode` table.
|
|
1153
|
+
* @param message - The actionable development sentence.
|
|
1154
|
+
* @param options - Context identifiers, a remedy hint, and the wrapped cause.
|
|
1155
|
+
* @returns The error to throw or to reject with.
|
|
1156
|
+
*
|
|
1157
|
+
* @example
|
|
1158
|
+
* ```ts
|
|
1159
|
+
* throw uiError(UiErrorCode.unknownLocale, "fr is not a locale strings.i18n.json declares.", {
|
|
1160
|
+
* context: { locale: "fr" },
|
|
1161
|
+
* });
|
|
1162
|
+
* ```
|
|
1163
|
+
*
|
|
1164
|
+
* @public
|
|
1165
|
+
*/
|
|
1166
|
+
export declare function uiError(code: UiErrorCode, message: string, options?: UiErrorOptions): IgnifxError;
|
|
1167
|
+
//#endregion
|
|
1168
|
+
//#region src/extension.d.ts
|
|
1169
|
+
/**
|
|
1170
|
+
* The `@ignifx/ui` extension (`docs/architecture/04-extensions.md` §1, `13-ui.md`).
|
|
1171
|
+
* Registering it is the whole installation: `ui()` gives a game `app.ui`, `app.i18n`, four
|
|
1172
|
+
* components, the `i18n` asset type, the `ui` settings section, and the one `PreRender` system that
|
|
1173
|
+
* projects anchors and re-shapes text.
|
|
1174
|
+
*
|
|
1175
|
+
* ## What it needs, and what it does not
|
|
1176
|
+
*
|
|
1177
|
+
* `@ignifx/input` is an **optional** peer. The overlay host, the text components, and the
|
|
1178
|
+
* localization service work without it; only `VirtualJoystick` and `VirtualButton` need it, and
|
|
1179
|
+
* they say so with `IGX-1305`. The extension never imports it — it reaches
|
|
1180
|
+
* `app.input.uiHasFocus` structurally, for the reason `src/widgets/virtual-device.ts` records.
|
|
1181
|
+
*
|
|
1182
|
+
* ## Headless
|
|
1183
|
+
*
|
|
1184
|
+
* Everything registers headlessly. With no DOM canvas the host is inert (`13-ui.md` §1's
|
|
1185
|
+
* "the host hides itself in headless mode"*, read through `07-rendering.md` §6's rule that a
|
|
1186
|
+
* headless member is a documented no-op rather than a throw), no text renderer is created, and the
|
|
1187
|
+
* `PreRender` system still runs — so `WorldText` keeps its state and a test asserts on it.
|
|
1188
|
+
*/
|
|
1189
|
+
/**
|
|
1190
|
+
* What `ui()` accepts. Every field that names a settings value overrides the matching `ui` section
|
|
1191
|
+
* value, which is the shape `04-extensions.md` §1 shows for `physics()`.
|
|
1192
|
+
*
|
|
1193
|
+
* @public
|
|
1194
|
+
*/
|
|
1195
|
+
interface UiOptions {
|
|
1196
|
+
/** How the overlay's coordinate system relates to the canvas. */
|
|
1197
|
+
readonly scaling?: UiScalingMode;
|
|
1198
|
+
/** The `[width, height]` the `"fit"` mode scales to. */
|
|
1199
|
+
readonly referenceResolution?: readonly number[];
|
|
1200
|
+
/** The layers created up front, back to front. */
|
|
1201
|
+
readonly layers?: readonly string[];
|
|
1202
|
+
/** Whether the overlay starts shown. */
|
|
1203
|
+
readonly visible?: boolean;
|
|
1204
|
+
/**
|
|
1205
|
+
* The address of a `.i18n.json` document to load into `app.i18n` at start-up. Empty loads
|
|
1206
|
+
* nothing; a game that ships one file per locale calls `app.i18n.load` itself.
|
|
1207
|
+
*/
|
|
1208
|
+
readonly strings?: string;
|
|
1209
|
+
/** The locale the app starts in, before any document is loaded. Defaults to `"en"`. */
|
|
1210
|
+
readonly locale?: string;
|
|
1211
|
+
}
|
|
1212
|
+
/**
|
|
1213
|
+
* The `@ignifx/ui` extension factory.
|
|
1214
|
+
*
|
|
1215
|
+
* @param options - Overrides for the `ui` settings section, plus the start-up translation document.
|
|
1216
|
+
* @returns The extension descriptor to pass to `createApp`.
|
|
1217
|
+
*
|
|
1218
|
+
* @example
|
|
1219
|
+
* ```ts
|
|
1220
|
+
* const app = await createApp({
|
|
1221
|
+
* canvas,
|
|
1222
|
+
* extensions: [ui({ scaling: "fit", referenceResolution: [640, 360] })],
|
|
1223
|
+
* });
|
|
1224
|
+
* ```
|
|
1225
|
+
*
|
|
1226
|
+
* @public
|
|
1227
|
+
*/
|
|
1228
|
+
export declare const ui: (options?: UiOptions) => Extension;
|
|
1229
|
+
//#endregion
|
|
1230
|
+
//#region src/i18n/loader.d.ts
|
|
1231
|
+
/**
|
|
1232
|
+
* The `i18n` asset loader: `.i18n.json` to {@link LocaleAsset}
|
|
1233
|
+
* (`docs/architecture/05-assets-and-loading.md` §5).
|
|
1234
|
+
*
|
|
1235
|
+
* The file is data, so the loader is identical under Node and in a browser and has nothing to
|
|
1236
|
+
* release on unload. `.i18n.json` is a longer suffix than `.json` and the asset service picks the
|
|
1237
|
+
* longest match, so registering it does not shadow the generic JSON loader.
|
|
1238
|
+
*/
|
|
1239
|
+
/**
|
|
1240
|
+
* Builds the loader for `.i18n.json` addresses.
|
|
1241
|
+
*
|
|
1242
|
+
* @returns The loader to register with `ctx.registerAssetLoader`.
|
|
1243
|
+
*
|
|
1244
|
+
* @example
|
|
1245
|
+
* ```ts
|
|
1246
|
+
* ctx.registerAssetLoader(createLocaleLoader());
|
|
1247
|
+
* ```
|
|
1248
|
+
*
|
|
1249
|
+
* @public
|
|
1250
|
+
*/
|
|
1251
|
+
export declare function createLocaleLoader(): AssetLoader<LocaleAsset>;
|
|
1252
|
+
//#endregion
|
|
1253
|
+
//#region src/lite/text.d.ts
|
|
1254
|
+
/**
|
|
1255
|
+
* The device-free half of the Babylon Lite text adapter (`docs/architecture/13-ui.md` §2).
|
|
1256
|
+
* Everything here shapes text, measures it, and builds the pure-data objects a renderer later
|
|
1257
|
+
* draws; nothing touches `engine._device`, which is why this module is **not** under `./gpu/` and
|
|
1258
|
+
* is covered by the node suite. Only `createTextRenderer` needs a surface, and that lives in
|
|
1259
|
+
* `./gpu/text-renderer.ts`.
|
|
1260
|
+
*
|
|
1261
|
+
* ## What was verified against `@babylonjs/lite@1.27.0`
|
|
1262
|
+
*
|
|
1263
|
+
* - `createDefaultTextData(font, fontSizePx, text, textColor?, options?)` (`index.d.ts` 2377)
|
|
1264
|
+
* shapes the string, extracts the glyph outlines, and **owns its own `GlyphStorage`** — the
|
|
1265
|
+
* doc comment at 2375 says so, and `disposeDefaultTextData` (3948) releases both. The returned
|
|
1266
|
+
* `DefaultTextData` carries the laid-out `width` and `height` in pixels (3736-3741), which is
|
|
1267
|
+
* the only text measurement Lite offers.
|
|
1268
|
+
* - `updateDefaultTextData(data, text, textColor?)` (13247) re-shapes **with the font size and the
|
|
1269
|
+
* layout options the block was created with** — `lib/text/default-text-data.js` reads
|
|
1270
|
+
* `data._fontSizePx` and `data._options` and never takes new ones — and writes fresh `width`
|
|
1271
|
+
* and `height` onto the block. Changing `fontSize`, `maxWidth`, `align`, `lineHeight`, or the
|
|
1272
|
+
* font therefore means **recreating** the block; changing `text` or `color` does not. Omitting
|
|
1273
|
+
* `textColor` preserves the run's existing colour (13245-13246).
|
|
1274
|
+
* - `TextLayoutOptions` (12821) is `{ maxWidth, lineHeight, align, letterSpacing, tabSize }`, in
|
|
1275
|
+
* output pixels, with simple LTR word wrapping.
|
|
1276
|
+
* - `align` aligns the lines of a block against **the longest line**, not against `maxWidth`:
|
|
1277
|
+
* measured on the pinned build, `"AAAA\nB"` at 32 px puts the `B` at x 0, 25.92 and 51.84 for
|
|
1278
|
+
* `"left"`, `"center"` and `"right"`, with `width` 69.12 in all three. Centring a block on the
|
|
1279
|
+
* screen is therefore the caller's arithmetic, against {@link measureText}.
|
|
1280
|
+
* - Glyph baselines run **downwards in negative y**: line n sits at `-n × fontSizePx × lineHeight`
|
|
1281
|
+
* (`PlacedGlyph`, 8854-8858). A block's first baseline is at the layer's `positionPx`, so its
|
|
1282
|
+
* ascent is above that point.
|
|
1283
|
+
* - `createTextLayer(data, options)` (3257) and `createTextRenderable(data, options)` (3264) are
|
|
1284
|
+
* pure object construction; `lib/text/text-renderer.js` and `lib/text/text-renderable.js` build
|
|
1285
|
+
* plain records with `_gpu: null` and allocate GPU resources lazily on the first frame.
|
|
1286
|
+
* - **There is no `removeTextRenderable`.** `addTextRenderable(scene, renderable)` (208) pushes a
|
|
1287
|
+
* deferred builder onto the scene (`lib/text/text-renderable.js` 242-249) and Lite exposes no
|
|
1288
|
+
* inverse — `removeFromScene` (9613) takes meshes, lights, cameras, shadow generators, transform
|
|
1289
|
+
* nodes and asset containers, and not a `TextRenderable`. {@link detachSceneText} therefore
|
|
1290
|
+
* empties the block and zeroes its opacity, which makes it draw nothing; the record itself stays
|
|
1291
|
+
* in the scene's renderable list until the scene is disposed. This is reported as a Lite gap.
|
|
1292
|
+
*
|
|
1293
|
+
* Everything here is `@internal` apart from the type aliases the `.lite` escape hatches name.
|
|
1294
|
+
*/
|
|
1295
|
+
/**
|
|
1296
|
+
* The Babylon Lite font handle, re-exported under an ignifx name so feature code can name the type
|
|
1297
|
+
* without importing `@babylonjs/lite` (`CONSTITUTION.md` §3.4).
|
|
1298
|
+
*
|
|
1299
|
+
* @remarks
|
|
1300
|
+
* Unstable: it is Lite's own type, reachable only through documented `.lite` escape hatches.
|
|
1301
|
+
*
|
|
1302
|
+
* @public
|
|
1303
|
+
*/
|
|
1304
|
+
type LiteFont = Font;
|
|
1305
|
+
/**
|
|
1306
|
+
* A shaped block of text, with its glyph storage.
|
|
1307
|
+
*
|
|
1308
|
+
* @remarks
|
|
1309
|
+
* Unstable escape-hatch type.
|
|
1310
|
+
*
|
|
1311
|
+
* @public
|
|
1312
|
+
*/
|
|
1313
|
+
type LiteTextData = DefaultTextData;
|
|
1314
|
+
/**
|
|
1315
|
+
* A 2D text layer placed in render-target pixel space.
|
|
1316
|
+
*
|
|
1317
|
+
* @remarks
|
|
1318
|
+
* Unstable escape-hatch type.
|
|
1319
|
+
*
|
|
1320
|
+
* @public
|
|
1321
|
+
*/
|
|
1322
|
+
type LiteTextLayer = TextLayer;
|
|
1323
|
+
/**
|
|
1324
|
+
* A scene renderable that draws a block of text in world space.
|
|
1325
|
+
*
|
|
1326
|
+
* @remarks
|
|
1327
|
+
* Unstable escape-hatch type.
|
|
1328
|
+
*
|
|
1329
|
+
* @public
|
|
1330
|
+
*/
|
|
1331
|
+
type LiteTextRenderable = TextRenderable;
|
|
1332
|
+
/**
|
|
1333
|
+
* The standalone rendering context that draws 2D text layers onto the swapchain.
|
|
1334
|
+
*
|
|
1335
|
+
* @remarks
|
|
1336
|
+
* Unstable escape-hatch type.
|
|
1337
|
+
*
|
|
1338
|
+
* @public
|
|
1339
|
+
*/
|
|
1340
|
+
type LiteTextRenderer = TextRenderer;
|
|
1341
|
+
/**
|
|
1342
|
+
* The pixel size of a laid-out block.
|
|
1343
|
+
*
|
|
1344
|
+
* @public
|
|
1345
|
+
*/
|
|
1346
|
+
interface TextMetrics {
|
|
1347
|
+
/** The width of the longest line, in render-target pixels. */
|
|
1348
|
+
readonly width: number;
|
|
1349
|
+
/** The number of lines times the line height, in render-target pixels. */
|
|
1350
|
+
readonly height: number;
|
|
1351
|
+
}
|
|
1352
|
+
//#endregion
|
|
1353
|
+
//#region src/schemas.d.ts
|
|
1354
|
+
/**
|
|
1355
|
+
* The documentation harness's view of everything `@ignifx/ui` declares
|
|
1356
|
+
* (`docs/architecture/16-docs-harness-and-skill.md` §3, `scripts/README.md`).
|
|
1357
|
+
*
|
|
1358
|
+
* `pnpm docs:schemas` imports the built entry point, calls {@link describeSchemas}, and renders
|
|
1359
|
+
* `skills/ignifx/references/formats/<format>.md` plus `ignifx.schemas.json` from the result. The
|
|
1360
|
+
* **function** form is what a package exports rather than a `schemas` object: building the record
|
|
1361
|
+
* means calling `describeSchema` for every component, and module scope holds declarations only
|
|
1362
|
+
* (`CONSTITUTION.md` §3.5).
|
|
1363
|
+
*
|
|
1364
|
+
* The translation document is keyed `ignifx/i18n-file` rather than `ignifx.i18n`: the harness
|
|
1365
|
+
* rejects a key with no `/` (`scripts/lib/schema-source.ts`), and it is the entry's `format` — not
|
|
1366
|
+
* its key — that decides which page it lands on. `@ignifx/core` and `@ignifx/audio` key their file
|
|
1367
|
+
* formats the same way.
|
|
1368
|
+
*/
|
|
1369
|
+
/**
|
|
1370
|
+
* Describes every component and file format this package declares, for the documentation harness.
|
|
1371
|
+
*
|
|
1372
|
+
* @returns The records, keyed by namespaced type id.
|
|
1373
|
+
*
|
|
1374
|
+
* @example
|
|
1375
|
+
* ```ts
|
|
1376
|
+
* describeSchemas()["ignifx/HudText"].fields["fontSize"].default; // 32
|
|
1377
|
+
* ```
|
|
1378
|
+
*
|
|
1379
|
+
* @public
|
|
1380
|
+
*/
|
|
1381
|
+
export declare function describeSchemas(): Readonly<Record<string, SchemaDescription>>;
|
|
1382
|
+
//#endregion
|
|
1383
|
+
//#region src/text/hud-layout.d.ts
|
|
1384
|
+
/**
|
|
1385
|
+
* Where a shaped block goes on the screen (`docs/architecture/13-ui.md` §2).
|
|
1386
|
+
*
|
|
1387
|
+
* Pure arithmetic, so the node suite covers all nine anchors with no GPU and no DOM.
|
|
1388
|
+
*
|
|
1389
|
+
* ## What Lite gives, and what it does not
|
|
1390
|
+
*
|
|
1391
|
+
* A `DefaultTextData` reports the laid-out `width` and `height` of the block and nothing else — no
|
|
1392
|
+
* ascent, no descent, no baseline offset (`index.d.ts` 3736-3741). Glyph baselines run downwards
|
|
1393
|
+
* in negative y from the layer's `positionPx`, verified on the pinned build: `"A\nB\nC"` at 32 px
|
|
1394
|
+
* with `lineHeight` 2 places the three baselines at y `0`, `-64`, `-128`.
|
|
1395
|
+
*
|
|
1396
|
+
* So the **first baseline** is at `positionPx.y`, and the box the reader perceives starts one em
|
|
1397
|
+
* above it. `ascentOf` is that approximation, stated once here rather than guessed at in three
|
|
1398
|
+
* components: an em is the right order of magnitude for every Latin face and it is what makes
|
|
1399
|
+
* `anchor: "topLeft"` put the text just inside the top-left corner rather than half off-screen.
|
|
1400
|
+
*/
|
|
1401
|
+
/**
|
|
1402
|
+
* The nine points of a rectangle a block can be anchored to.
|
|
1403
|
+
*
|
|
1404
|
+
* @public
|
|
1405
|
+
*/
|
|
1406
|
+
export declare const HUD_ANCHORS: readonly ["topLeft", "top", "topRight", "left", "center", "right", "bottomLeft", "bottom", "bottomRight"];
|
|
1407
|
+
/**
|
|
1408
|
+
* Which point of the render target a `HudText`'s position is measured from, and which point of the
|
|
1409
|
+
* block sits there.
|
|
1410
|
+
*
|
|
1411
|
+
* @public
|
|
1412
|
+
*/
|
|
1413
|
+
type HudAnchor = (typeof HUD_ANCHORS)[number];
|
|
1414
|
+
/**
|
|
1415
|
+
* A layer position, written in place so the per-frame path allocates nothing.
|
|
1416
|
+
*
|
|
1417
|
+
* @public
|
|
1418
|
+
*/
|
|
1419
|
+
interface HudPlacement {
|
|
1420
|
+
/** The layer's x, in render-target pixels. */
|
|
1421
|
+
x: number;
|
|
1422
|
+
/** The layer's y — the first baseline — in render-target pixels. */
|
|
1423
|
+
y: number;
|
|
1424
|
+
}
|
|
1425
|
+
/**
|
|
1426
|
+
* What {@link computeHudPlacement} needs.
|
|
1427
|
+
*
|
|
1428
|
+
* @public
|
|
1429
|
+
*/
|
|
1430
|
+
interface HudPlacementInput {
|
|
1431
|
+
/** Which point of the target the position is measured from, and which point of the block lands there. */
|
|
1432
|
+
readonly anchor: HudAnchor;
|
|
1433
|
+
/** The offset from that point, in render-target pixels; x grows right, y grows down. */
|
|
1434
|
+
readonly offsetX: number;
|
|
1435
|
+
/** The offset from that point, in render-target pixels. */
|
|
1436
|
+
readonly offsetY: number;
|
|
1437
|
+
/** The render target's width, in pixels. */
|
|
1438
|
+
readonly targetWidth: number;
|
|
1439
|
+
/** The render target's height, in pixels. */
|
|
1440
|
+
readonly targetHeight: number;
|
|
1441
|
+
/** The block's laid-out width. */
|
|
1442
|
+
readonly blockWidth: number;
|
|
1443
|
+
/** The block's laid-out height. */
|
|
1444
|
+
readonly blockHeight: number;
|
|
1445
|
+
/** The em size the block was shaped at. */
|
|
1446
|
+
readonly fontSize: number;
|
|
1447
|
+
}
|
|
1448
|
+
/**
|
|
1449
|
+
* Places a block against one of the nine anchors of the render target.
|
|
1450
|
+
*
|
|
1451
|
+
* @param input - The anchor, the offset, the target size, and the block's size.
|
|
1452
|
+
* @param out - Receives the layer position.
|
|
1453
|
+
* @returns `out`, for chaining.
|
|
1454
|
+
*
|
|
1455
|
+
* @example
|
|
1456
|
+
* ```ts
|
|
1457
|
+
* const out = { x: 0, y: 0 };
|
|
1458
|
+
* computeHudPlacement(
|
|
1459
|
+
* {
|
|
1460
|
+
* anchor: "topRight",
|
|
1461
|
+
* offsetX: -16,
|
|
1462
|
+
* offsetY: 16,
|
|
1463
|
+
* targetWidth: 800,
|
|
1464
|
+
* targetHeight: 600,
|
|
1465
|
+
* blockWidth: 100,
|
|
1466
|
+
* blockHeight: 40,
|
|
1467
|
+
* fontSize: 32,
|
|
1468
|
+
* },
|
|
1469
|
+
* out,
|
|
1470
|
+
* );
|
|
1471
|
+
* out.x; // 684 — 16 px in from the right edge
|
|
1472
|
+
* ```
|
|
1473
|
+
*
|
|
1474
|
+
* @public
|
|
1475
|
+
*/
|
|
1476
|
+
export declare function computeHudPlacement(input: HudPlacementInput, out: HudPlacement): HudPlacement;
|
|
1477
|
+
/**
|
|
1478
|
+
* Places a block around a point, with the given point of the block sitting on it.
|
|
1479
|
+
*
|
|
1480
|
+
* @param pivot - Which point of the block lands on the position.
|
|
1481
|
+
* @param x - The point's x, in render-target pixels.
|
|
1482
|
+
* @param y - The point's y, in render-target pixels.
|
|
1483
|
+
* @param blockWidth - The block's laid-out width.
|
|
1484
|
+
* @param blockHeight - The block's laid-out height.
|
|
1485
|
+
* @param fontSize - The em size the block was shaped at.
|
|
1486
|
+
* @param out - Receives the layer position.
|
|
1487
|
+
* @returns `out`, for chaining.
|
|
1488
|
+
*
|
|
1489
|
+
* @example
|
|
1490
|
+
* ```ts
|
|
1491
|
+
* const out = { x: 0, y: 0 };
|
|
1492
|
+
* computePivotPlacement("center", 400, 300, 100, 40, 32, out);
|
|
1493
|
+
* out.x; // 350
|
|
1494
|
+
* ```
|
|
1495
|
+
*
|
|
1496
|
+
* @public
|
|
1497
|
+
*/
|
|
1498
|
+
export declare function computePivotPlacement(pivot: HudAnchor, x: number, y: number, blockWidth: number, blockHeight: number, fontSize: number, out: HudPlacement): HudPlacement;
|
|
1499
|
+
//#endregion
|
|
1500
|
+
//#region src/text/text-component.d.ts
|
|
1501
|
+
/**
|
|
1502
|
+
* The fields and the block lifecycle every text component shares (`docs/architecture/13-ui.md` §2:
|
|
1503
|
+
* "`text`, `fontSize`, `color`, `align`, `maxWidth`, `opacity`, `billboard`"*).
|
|
1504
|
+
*
|
|
1505
|
+
* ## Why the block is rebuilt for some changes and updated for others
|
|
1506
|
+
*
|
|
1507
|
+
* `updateDefaultTextData` re-shapes with the font size and layout options the block was created
|
|
1508
|
+
* with, and only those — verified in `@babylonjs/lite@1.27.0`'s `lib/text/default-text-data.js`, which reads
|
|
1509
|
+
* `data._fontSizePx` and `data._options` and never takes new ones. So a change to `text` or
|
|
1510
|
+
* `color` is an update, which keeps the glyph storage and its atlas; a change to `font`,
|
|
1511
|
+
* `fontSize`, `maxWidth`, `align`, or `lineHeight` is a rebuild. The component tracks both, so a
|
|
1512
|
+
* HUD counter that changes every frame pays for one re-shape and nothing else.
|
|
1513
|
+
*
|
|
1514
|
+
* ## Localization
|
|
1515
|
+
*
|
|
1516
|
+
* `i18nKey` wins over `text` when it is set, and the block is re-shaped whenever
|
|
1517
|
+
* `app.i18n.onLocaleChanged` fires. A component with neither draws nothing rather than drawing an
|
|
1518
|
+
* empty box.
|
|
1519
|
+
*/
|
|
1520
|
+
/**
|
|
1521
|
+
* The alignments Lite's default layout supports (`index.d.ts` 12826-12827).
|
|
1522
|
+
*
|
|
1523
|
+
* @public
|
|
1524
|
+
*/
|
|
1525
|
+
export declare const TEXT_ALIGNMENTS: readonly ["left", "center", "right"];
|
|
1526
|
+
/**
|
|
1527
|
+
* Which edge a block's lines align to. Lite aligns lines against the block's **longest line**, not
|
|
1528
|
+
* against `maxWidth`, so a single-line block looks the same in all three.
|
|
1529
|
+
*
|
|
1530
|
+
* @public
|
|
1531
|
+
*/
|
|
1532
|
+
type TextAlignment = (typeof TEXT_ALIGNMENTS)[number];
|
|
1533
|
+
/**
|
|
1534
|
+
* The base of `HudText`, `WorldText2D`, and `WorldText`: the schema fields and the shaped block.
|
|
1535
|
+
*
|
|
1536
|
+
* @remarks
|
|
1537
|
+
* Abstract, and never registered as a component itself; the three concrete classes are.
|
|
1538
|
+
*
|
|
1539
|
+
* @public
|
|
1540
|
+
*/
|
|
1541
|
+
export declare abstract class TextComponent extends Component {
|
|
1542
|
+
#private;
|
|
1543
|
+
/** The TTF or OTF the glyphs come from. */
|
|
1544
|
+
font: AssetHandle<FontAsset> | null;
|
|
1545
|
+
/** The literal string to draw; ignored when {@link TextComponent.i18nKey} is set. */
|
|
1546
|
+
text: string;
|
|
1547
|
+
/** A translation key looked up in `app.i18n`; wins over {@link TextComponent.text}. */
|
|
1548
|
+
i18nKey: string;
|
|
1549
|
+
/** The em size, in render-target pixels. */
|
|
1550
|
+
fontSize: number;
|
|
1551
|
+
/** The colour every glyph starts with. */
|
|
1552
|
+
color: ColorLike;
|
|
1553
|
+
/** Which edge the lines align to. */
|
|
1554
|
+
align: TextAlignment;
|
|
1555
|
+
/** The wrap width, in render-target pixels; `0` does not wrap. */
|
|
1556
|
+
maxWidth: number;
|
|
1557
|
+
/** The line-height multiplier. */
|
|
1558
|
+
lineHeight: number;
|
|
1559
|
+
/** The whole-block alpha multiplier. */
|
|
1560
|
+
opacity: number;
|
|
1561
|
+
/**
|
|
1562
|
+
* The shaped block, or `null` until a font and a non-empty string are both present.
|
|
1563
|
+
*
|
|
1564
|
+
* @returns The block.
|
|
1565
|
+
*
|
|
1566
|
+
* @internal
|
|
1567
|
+
*/
|
|
1568
|
+
get block(): LiteTextData | null;
|
|
1569
|
+
/**
|
|
1570
|
+
* The block's laid-out size, in render-target pixels.
|
|
1571
|
+
*
|
|
1572
|
+
* @remarks
|
|
1573
|
+
* `{ width: 0, height: 0 }` until the block exists. This is Lite's only text measurement, and
|
|
1574
|
+
* it is what a caller centring a block on the screen needs — Lite's `align` aligns lines against
|
|
1575
|
+
* each other, not against the screen.
|
|
1576
|
+
*
|
|
1577
|
+
* @returns The size.
|
|
1578
|
+
*
|
|
1579
|
+
* @example
|
|
1580
|
+
* ```ts
|
|
1581
|
+
* const label = entity.addComponent(HudText);
|
|
1582
|
+
* label.metrics.width; // 0 until a font and a string are set
|
|
1583
|
+
* ```
|
|
1584
|
+
*/
|
|
1585
|
+
get metrics(): TextMetrics;
|
|
1586
|
+
/**
|
|
1587
|
+
* The string that will actually be drawn: the translated `i18nKey`, or `text`.
|
|
1588
|
+
*
|
|
1589
|
+
* @param i18n - The localization service, or `null` when the app has none.
|
|
1590
|
+
* @returns The resolved string.
|
|
1591
|
+
*/
|
|
1592
|
+
resolveText(i18n: I18nService | null): string;
|
|
1593
|
+
/**
|
|
1594
|
+
* Brings the shaped block in line with the component's fields.
|
|
1595
|
+
*
|
|
1596
|
+
* @remarks
|
|
1597
|
+
* The one place a block is created, re-shaped, or destroyed. Called by the UI text system once a
|
|
1598
|
+
* frame; it does nothing at all when nothing changed, which is what keeps a static label free.
|
|
1599
|
+
*
|
|
1600
|
+
* @param i18n - The localization service, or `null`.
|
|
1601
|
+
* @returns `"created"` when a new block was built (the caller has to rebuild its layer or
|
|
1602
|
+
* renderable), `"updated"` when the existing one was re-shaped, `"removed"` when the block went
|
|
1603
|
+
* away, and `"unchanged"` otherwise.
|
|
1604
|
+
*
|
|
1605
|
+
* @internal
|
|
1606
|
+
*/
|
|
1607
|
+
syncBlock(i18n: I18nService | null): "created" | "updated" | "removed" | "unchanged";
|
|
1608
|
+
/**
|
|
1609
|
+
* Releases the shaped block. The concrete components call it from `onDestroy`.
|
|
1610
|
+
*
|
|
1611
|
+
* @internal
|
|
1612
|
+
*/
|
|
1613
|
+
releaseBlock(): void;
|
|
1614
|
+
}
|
|
1615
|
+
//#endregion
|
|
1616
|
+
//#region src/text/text-runtime.d.ts
|
|
1617
|
+
/**
|
|
1618
|
+
* The text renderer's life, injected rather than imported so the node suite covers it
|
|
1619
|
+
* (`docs/architecture/11-2d-toolkit.md` §1 uses the same shape for the sprite renderer, and
|
|
1620
|
+
* `07-rendering.md` §1 is the rule both follow).
|
|
1621
|
+
*
|
|
1622
|
+
* ## Why the renderer is created lazily
|
|
1623
|
+
*
|
|
1624
|
+
* A `TextRenderer` must be registered **after** the render scene, so it composites over the frame
|
|
1625
|
+
* rather than under it. An extension's `register` runs before the scene exists and its `onStart`
|
|
1626
|
+
* runs only when a game calls `app.start()` — which a headless tool never does. Creating it on the
|
|
1627
|
+
* first `PreRender` tick is the one moment that satisfies both: the scene is registered, and a
|
|
1628
|
+
* headless app never gets there because it has no renderer factory in the first place.
|
|
1629
|
+
*/
|
|
1630
|
+
/**
|
|
1631
|
+
* The renderer operations the runtime needs, supplied by the extension so this module never imports
|
|
1632
|
+
* `@babylonjs/lite`.
|
|
1633
|
+
*
|
|
1634
|
+
* @internal
|
|
1635
|
+
*/
|
|
1636
|
+
interface TextRuntimeOptions {
|
|
1637
|
+
/** Creates and registers the renderer, or `null` under a headless app. */
|
|
1638
|
+
readonly createRenderer: (() => LiteTextRenderer) | null;
|
|
1639
|
+
/** Adds a layer to the renderer's draw list. */
|
|
1640
|
+
readonly attachLayer: (renderer: LiteTextRenderer, layer: LiteTextLayer) => void;
|
|
1641
|
+
/** Removes a layer from the renderer's draw list. */
|
|
1642
|
+
readonly detachLayer: (renderer: LiteTextRenderer, layer: LiteTextLayer) => boolean;
|
|
1643
|
+
/** Unregisters and disposes the renderer. */
|
|
1644
|
+
readonly destroyRenderer: (renderer: LiteTextRenderer) => void;
|
|
1645
|
+
}
|
|
1646
|
+
/**
|
|
1647
|
+
* Owns the one text renderer an app has, and the layers registered on it.
|
|
1648
|
+
*
|
|
1649
|
+
* @internal
|
|
1650
|
+
*/
|
|
1651
|
+
declare class TextRuntime {
|
|
1652
|
+
#private;
|
|
1653
|
+
/**
|
|
1654
|
+
* Builds the runtime. The extension does this.
|
|
1655
|
+
*
|
|
1656
|
+
* @param options - The renderer operations.
|
|
1657
|
+
*/
|
|
1658
|
+
constructor(options: TextRuntimeOptions);
|
|
1659
|
+
/**
|
|
1660
|
+
* The renderer, once it exists.
|
|
1661
|
+
*
|
|
1662
|
+
* @returns The renderer, or `null` before the first frame and under a headless app.
|
|
1663
|
+
*/
|
|
1664
|
+
get renderer(): LiteTextRenderer | null;
|
|
1665
|
+
/**
|
|
1666
|
+
* How many layers are currently drawn.
|
|
1667
|
+
*
|
|
1668
|
+
* @returns The count.
|
|
1669
|
+
*/
|
|
1670
|
+
get layerCount(): number;
|
|
1671
|
+
/**
|
|
1672
|
+
* Creates the renderer if it does not exist yet and flushes the layers that were registered
|
|
1673
|
+
* before it did. The UI text system calls this at the top of every `PreRender`.
|
|
1674
|
+
*/
|
|
1675
|
+
ensureRenderer(): void;
|
|
1676
|
+
/**
|
|
1677
|
+
* Starts drawing a layer.
|
|
1678
|
+
*
|
|
1679
|
+
* @param layer - The layer.
|
|
1680
|
+
*/
|
|
1681
|
+
addLayer(layer: LiteTextLayer): void;
|
|
1682
|
+
/**
|
|
1683
|
+
* Stops drawing a layer and frees its per-layer GPU buffers.
|
|
1684
|
+
*
|
|
1685
|
+
* @param layer - The layer.
|
|
1686
|
+
*/
|
|
1687
|
+
removeLayer(layer: LiteTextLayer): void;
|
|
1688
|
+
/** Tears the renderer down. The extension calls this from `onDispose`. */
|
|
1689
|
+
dispose(): void;
|
|
1690
|
+
}
|
|
1691
|
+
//#endregion
|
|
1692
|
+
//#region src/text/hud-text.d.ts
|
|
1693
|
+
/**
|
|
1694
|
+
* `HudText` (`docs/architecture/13-ui.md` §2): pixel-space text drawn by Babylon Lite rather than
|
|
1695
|
+
* by the DOM, *"when DOM text is not desirable (e.g. capture-perfect pixel HUDs, screenshots via
|
|
1696
|
+
* `captureScreenshot`)"*.
|
|
1697
|
+
*
|
|
1698
|
+
* ## The coordinate system is the render target, not CSS
|
|
1699
|
+
*
|
|
1700
|
+
* Lite's text renderer positions a layer against `surface.canvas.width`/`.height`
|
|
1701
|
+
* (`lib/text/text-renderer.js`), so `position` is in **backing-store pixels**. That is deliberate
|
|
1702
|
+
* and is the whole point of the component: the pixel a `HudText` draws on is the pixel
|
|
1703
|
+
* `app.renderer.captureScreenshot()` reads back, so a golden test asserts on an exact address. A
|
|
1704
|
+
* DOM label in `app.ui.layer("hud")` is the right tool whenever that is not what you want.
|
|
1705
|
+
*/
|
|
1706
|
+
/**
|
|
1707
|
+
* Pixel-space HUD text.
|
|
1708
|
+
*
|
|
1709
|
+
* @example
|
|
1710
|
+
* ```ts
|
|
1711
|
+
* const label = app.world.createEntity("score").addComponent(HudText);
|
|
1712
|
+
* label.font = app.assets.load<FontAsset>("ui/Inter-Regular.ttf");
|
|
1713
|
+
* label.anchor = "topLeft";
|
|
1714
|
+
* label.position = { x: 16, y: 16 };
|
|
1715
|
+
* label.i18nKey = "hud.score";
|
|
1716
|
+
* ```
|
|
1717
|
+
*
|
|
1718
|
+
* @public
|
|
1719
|
+
*/
|
|
1720
|
+
export declare class HudText extends TextComponent implements ComponentHooks {
|
|
1721
|
+
#private;
|
|
1722
|
+
/** The registration id the serializer writes into scene files. */
|
|
1723
|
+
static typeId: string;
|
|
1724
|
+
/** One HUD label per entity; a second belongs on a second entity. */
|
|
1725
|
+
static allowMultiple: boolean;
|
|
1726
|
+
/** The declarative fields (ADR-0004). */
|
|
1727
|
+
static schema: Schema;
|
|
1728
|
+
/** Which point of the render target {@link HudText.position} is measured from. */
|
|
1729
|
+
anchor: HudAnchor;
|
|
1730
|
+
/** The offset from the anchor, in render-target pixels; x grows right, y grows down. */
|
|
1731
|
+
position: Vec2Like;
|
|
1732
|
+
/** The sort order within the text renderer; lower draws first. */
|
|
1733
|
+
order: number;
|
|
1734
|
+
/** Builds a HUD label with the schema's defaults. */
|
|
1735
|
+
constructor();
|
|
1736
|
+
/**
|
|
1737
|
+
* The Babylon Lite objects the component owns. Unstable escape hatch
|
|
1738
|
+
* (`docs/architecture/00-overview.md` §3).
|
|
1739
|
+
*
|
|
1740
|
+
* @returns The text layer, or `null` before the first frame that had a font and a string.
|
|
1741
|
+
*/
|
|
1742
|
+
get lite(): {
|
|
1743
|
+
readonly layer: LiteTextLayer | null;
|
|
1744
|
+
};
|
|
1745
|
+
/** Drops the layer and the block when the component goes away. */
|
|
1746
|
+
onDetach(): void;
|
|
1747
|
+
/**
|
|
1748
|
+
* Brings the layer in line with the component's fields. The UI text system calls it once a frame.
|
|
1749
|
+
*
|
|
1750
|
+
* @param runtime - The renderer the layer is registered on.
|
|
1751
|
+
* @param i18n - The localization service, or `null`.
|
|
1752
|
+
* @param targetWidth - The render target's width, in pixels.
|
|
1753
|
+
* @param targetHeight - The render target's height, in pixels.
|
|
1754
|
+
*
|
|
1755
|
+
* @internal
|
|
1756
|
+
*/
|
|
1757
|
+
sync(runtime: TextRuntime, i18n: I18nService | null, targetWidth: number, targetHeight: number): void;
|
|
1758
|
+
}
|
|
1759
|
+
//#endregion
|
|
1760
|
+
//#region src/text/world-text.d.ts
|
|
1761
|
+
/**
|
|
1762
|
+
* `WorldText` (`docs/architecture/13-ui.md` §2): text that is part of the world — a sign, a
|
|
1763
|
+
* banner, a floating label that is hidden by the wall in front of it — drawn as a Babylon Lite
|
|
1764
|
+
* `TextRenderable` inside the render scene.
|
|
1765
|
+
*
|
|
1766
|
+
* ## Blocks are laid out in pixels, so the renderable is scaled down
|
|
1767
|
+
*
|
|
1768
|
+
* `createDefaultTextData` shapes in pixels: at `fontSize` 32 a capital letter is about 32 units
|
|
1769
|
+
* tall. A renderable at scale 1 would therefore be tens of metres high. {@link WorldText.pixelsPerUnit}
|
|
1770
|
+
* is the divisor, defaulting to 100 to match `@ignifx/2d`'s own default, so a 32-pixel block is
|
|
1771
|
+
* 0.32 m tall.
|
|
1772
|
+
*
|
|
1773
|
+
* ## It has to exist before `app.start()`
|
|
1774
|
+
*
|
|
1775
|
+
* `addTextRenderable` (`index.d.ts` 208) pushes a **deferred builder** onto the scene
|
|
1776
|
+
* (`lib/text/text-renderable.js` 242-249), and the only thing that drains those builders is
|
|
1777
|
+
* `buildScene`, which `registerScene` calls once (`lib/scene/scene-core.js` 228-241 and 246-262).
|
|
1778
|
+
* `rebuildSceneRenderables` — the one public rebuild — explicitly does not: it rebuilds *groups*
|
|
1779
|
+
* and returns early on an unbuilt scene, and Lite's runtime-build machinery is for meshes only. So
|
|
1780
|
+
* a renderable added after `app.start()` has registered the scene never materialises, and there is
|
|
1781
|
+
* no public call that would make it.
|
|
1782
|
+
*
|
|
1783
|
+
* A `WorldText` whose font and text are both present before the app starts therefore draws; one
|
|
1784
|
+
* that first gets its text mid-game does not, and says so once with `IGX-1308`. Until Lite exposes
|
|
1785
|
+
* a way to drain a late deferred renderable, the answers are to author signs in the scene file the
|
|
1786
|
+
* game starts with, or to use {@link WorldText2D}, which owns a text *layer* and can be added at
|
|
1787
|
+
* any time.
|
|
1788
|
+
*
|
|
1789
|
+
* ## Removal is one-way
|
|
1790
|
+
*
|
|
1791
|
+
* Babylon Lite 1.27.0 has `addTextRenderable` (`index.d.ts` 208) and **no inverse**:
|
|
1792
|
+
* `removeFromScene` (9613) accepts meshes, lights, cameras, shadow generators, transform nodes and
|
|
1793
|
+
* asset containers, and a `TextRenderable` is none of them. A destroyed `WorldText` therefore
|
|
1794
|
+
* empties its block and zeroes the renderable's opacity — it draws nothing and holds no GPU
|
|
1795
|
+
* buffers — but the record itself stays in the scene's renderable list until the scene is disposed.
|
|
1796
|
+
* A game that spawns and destroys thousands of signs should pool the components rather than the
|
|
1797
|
+
* entities. This is recorded as a Lite gap rather than worked around.
|
|
1798
|
+
*/
|
|
1799
|
+
/**
|
|
1800
|
+
* World-space 3D text.
|
|
1801
|
+
*
|
|
1802
|
+
* @example
|
|
1803
|
+
* ```ts
|
|
1804
|
+
* const sign = app.world.createEntity("sign").addComponent(WorldText);
|
|
1805
|
+
* sign.font = app.assets.load<FontAsset>("ui/Inter-Regular.ttf");
|
|
1806
|
+
* sign.text = "Danger";
|
|
1807
|
+
* sign.billboard = true;
|
|
1808
|
+
* ```
|
|
1809
|
+
*
|
|
1810
|
+
* @public
|
|
1811
|
+
*/
|
|
1812
|
+
export declare class WorldText extends TextComponent implements ComponentHooks {
|
|
1813
|
+
#private;
|
|
1814
|
+
/** The registration id the serializer writes into scene files. */
|
|
1815
|
+
static typeId: string;
|
|
1816
|
+
/** One sign per entity. */
|
|
1817
|
+
static allowMultiple: boolean;
|
|
1818
|
+
/** The declarative fields (ADR-0004). */
|
|
1819
|
+
static schema: Schema;
|
|
1820
|
+
/** A local offset added to the entity's world position, in metres. */
|
|
1821
|
+
offset: Vec3Like;
|
|
1822
|
+
/** How many pixels of laid-out text span one world metre. */
|
|
1823
|
+
pixelsPerUnit: number;
|
|
1824
|
+
/** Whether the text turns to face the camera instead of following the entity's rotation. */
|
|
1825
|
+
billboard: boolean;
|
|
1826
|
+
/** Whether the text draws through geometry in front of it. */
|
|
1827
|
+
alwaysOnTop: boolean;
|
|
1828
|
+
/** Builds a sign with the schema's defaults. */
|
|
1829
|
+
constructor();
|
|
1830
|
+
/**
|
|
1831
|
+
* The Babylon Lite objects the component owns. Unstable escape hatch.
|
|
1832
|
+
*
|
|
1833
|
+
* @returns The renderable, or `null` before the first frame that had a font and a string.
|
|
1834
|
+
*/
|
|
1835
|
+
get lite(): {
|
|
1836
|
+
readonly renderable: LiteTextRenderable | null;
|
|
1837
|
+
};
|
|
1838
|
+
/** Silences and releases the renderable when the component goes away. */
|
|
1839
|
+
onDetach(): void;
|
|
1840
|
+
/**
|
|
1841
|
+
* Brings the renderable in line with the component's fields and the entity's transform.
|
|
1842
|
+
*
|
|
1843
|
+
* @param scene - The Lite scene the renderable is added to, from `app.lite.scene`.
|
|
1844
|
+
* @param i18n - The localization service, or `null`.
|
|
1845
|
+
* @param cameraRotation - The main camera's world rotation, for billboarding, or `null` when the
|
|
1846
|
+
* world has no camera.
|
|
1847
|
+
*
|
|
1848
|
+
* @internal
|
|
1849
|
+
*/
|
|
1850
|
+
sync(scene: LiteScene, i18n: I18nService | null, cameraRotation: QuatLike | null): void;
|
|
1851
|
+
/**
|
|
1852
|
+
* The scene the renderable was added to, for diagnostics.
|
|
1853
|
+
*
|
|
1854
|
+
* @returns The scene, or `null` when nothing has been added yet.
|
|
1855
|
+
*
|
|
1856
|
+
* @internal
|
|
1857
|
+
*/
|
|
1858
|
+
get scene(): LiteScene | null;
|
|
1859
|
+
}
|
|
1860
|
+
//#endregion
|
|
1861
|
+
//#region src/text/world-text-2d.d.ts
|
|
1862
|
+
/**
|
|
1863
|
+
* `WorldText2D` (`docs/architecture/13-ui.md` §2): text that belongs to the world — damage numbers,
|
|
1864
|
+
* floating names — but is drawn as a flat pixel-space layer rather than as geometry, so it never
|
|
1865
|
+
* shrinks with distance and never intersects a wall.
|
|
1866
|
+
*
|
|
1867
|
+
* It is `HudText`'s twin: the same Lite text layer, positioned from the entity's **projected**
|
|
1868
|
+
* screen position instead of from a screen anchor. `WorldText` is the other choice, and the one to
|
|
1869
|
+
* take when the text should be occluded by the world.
|
|
1870
|
+
*/
|
|
1871
|
+
/**
|
|
1872
|
+
* World-anchored pixel-space text.
|
|
1873
|
+
*
|
|
1874
|
+
* @example
|
|
1875
|
+
* ```ts
|
|
1876
|
+
* const damage = app.world.createEntity("damage").addComponent(WorldText2D);
|
|
1877
|
+
* damage.font = app.assets.load<FontAsset>("ui/Inter-Regular.ttf");
|
|
1878
|
+
* damage.text = "-12";
|
|
1879
|
+
* damage.offset = { x: 0, y: 1.8, z: 0 };
|
|
1880
|
+
* ```
|
|
1881
|
+
*
|
|
1882
|
+
* @public
|
|
1883
|
+
*/
|
|
1884
|
+
export declare class WorldText2D extends TextComponent implements ComponentHooks {
|
|
1885
|
+
#private;
|
|
1886
|
+
/** The registration id the serializer writes into scene files. */
|
|
1887
|
+
static typeId: string;
|
|
1888
|
+
/** One floating label per entity. */
|
|
1889
|
+
static allowMultiple: boolean;
|
|
1890
|
+
/** The declarative fields (ADR-0004). */
|
|
1891
|
+
static schema: Schema;
|
|
1892
|
+
/** A world-space offset added to the entity's position before projecting, in metres. */
|
|
1893
|
+
offset: Vec3Like;
|
|
1894
|
+
/** A screen-space offset added after projecting, in render-target pixels. */
|
|
1895
|
+
screenOffset: Vec2Like;
|
|
1896
|
+
/** Which point of the block sits on the projected position. */
|
|
1897
|
+
pivot: HudAnchor;
|
|
1898
|
+
/** Whether the label is hidden when the anchor point is behind the camera. */
|
|
1899
|
+
hideWhenBehindCamera: boolean;
|
|
1900
|
+
/** The sort order within the text renderer; lower draws first. */
|
|
1901
|
+
order: number;
|
|
1902
|
+
/** Builds a floating label with the schema's defaults. */
|
|
1903
|
+
constructor();
|
|
1904
|
+
/**
|
|
1905
|
+
* The Babylon Lite objects the component owns. Unstable escape hatch.
|
|
1906
|
+
*
|
|
1907
|
+
* @returns The text layer, or `null` before the first frame that had a font and a string.
|
|
1908
|
+
*/
|
|
1909
|
+
get lite(): {
|
|
1910
|
+
readonly layer: LiteTextLayer | null;
|
|
1911
|
+
};
|
|
1912
|
+
/** Drops the layer and the block when the component goes away. */
|
|
1913
|
+
onDetach(): void;
|
|
1914
|
+
/**
|
|
1915
|
+
* Brings the layer in line with the component's fields and the projected position.
|
|
1916
|
+
*
|
|
1917
|
+
* @param runtime - The renderer the layer is registered on.
|
|
1918
|
+
* @param i18n - The localization service, or `null`.
|
|
1919
|
+
* @param screenX - The entity's projected x, in render-target pixels.
|
|
1920
|
+
* @param screenY - The entity's projected y, in render-target pixels.
|
|
1921
|
+
* @param inFront - Whether the anchor point is in front of the camera.
|
|
1922
|
+
*
|
|
1923
|
+
* @internal
|
|
1924
|
+
*/
|
|
1925
|
+
sync(runtime: TextRuntime, i18n: I18nService | null, screenX: number, screenY: number, inFront: boolean): void;
|
|
1926
|
+
}
|
|
1927
|
+
//#endregion
|
|
1928
|
+
//#region src/version.d.ts
|
|
1929
|
+
/**
|
|
1930
|
+
* The package's own version, reported as `Extension.version`
|
|
1931
|
+
* (`docs/architecture/04-extensions.md` §1). First-party packages ship one version line, so this
|
|
1932
|
+
* tracks `package.json` and the release tooling bumps both together.
|
|
1933
|
+
*/
|
|
1934
|
+
/**
|
|
1935
|
+
* The `@ignifx/ui` version this build was cut from.
|
|
1936
|
+
*
|
|
1937
|
+
* @public
|
|
1938
|
+
*/
|
|
1939
|
+
export declare const VERSION = "0.0.0";
|
|
1940
|
+
//#endregion
|
|
1941
|
+
//#region src/widgets/dialog.d.ts
|
|
1942
|
+
/**
|
|
1943
|
+
* `Dialog` (`docs/architecture/13-ui.md` §3): *"plain DOM helper classes with no styling opinions
|
|
1944
|
+
* beyond a minimal stylesheet; templates ship their own CSS"*.
|
|
1945
|
+
*
|
|
1946
|
+
* The whole point is that a template's pause menu is two lines:
|
|
1947
|
+
*
|
|
1948
|
+
* ```ts ignore-check
|
|
1949
|
+
* const pause = new Dialog(app.ui, {
|
|
1950
|
+
* title: "Paused",
|
|
1951
|
+
* buttons: [{ id: "resume", label: "Resume" }, { id: "quit", label: "Quit" }],
|
|
1952
|
+
* });
|
|
1953
|
+
* pause.onChosen.connect((id) => {
|
|
1954
|
+
* pause.hide();
|
|
1955
|
+
* if (id === "resume") app.resume();
|
|
1956
|
+
* });
|
|
1957
|
+
* ```
|
|
1958
|
+
*
|
|
1959
|
+
* Under a headless app every method is a no-op and {@link Dialog.element} is `null`, so the same
|
|
1960
|
+
* code runs in a test.
|
|
1961
|
+
*
|
|
1962
|
+
* ## Stacking
|
|
1963
|
+
*
|
|
1964
|
+
* A dialog is modal, so it is always drawn **above** the other roots of its layer: the stylesheet
|
|
1965
|
+
* gives `.ignifx-ui-dialog` a `z-index` of `UI_DIALOG_Z_INDEX`, and {@link DialogOptions.zIndex}
|
|
1966
|
+
* overrides it per dialog. Without that rule a dialog created before a `Menu` in the same layer
|
|
1967
|
+
* paints under it — siblings with no `z-index` paint in DOM order — and the invisible backdrop
|
|
1968
|
+
* swallows every click meant for the panel on top. Two dialogs in one layer still stack in DOM
|
|
1969
|
+
* order, so the one shown last is the one on top.
|
|
1970
|
+
*/
|
|
1971
|
+
/**
|
|
1972
|
+
* One button in a dialog.
|
|
1973
|
+
*
|
|
1974
|
+
* @public
|
|
1975
|
+
*/
|
|
1976
|
+
interface DialogButton {
|
|
1977
|
+
/** The identifier `onChosen` reports. */
|
|
1978
|
+
readonly id: string;
|
|
1979
|
+
/** The text drawn on the button. */
|
|
1980
|
+
readonly label: string;
|
|
1981
|
+
}
|
|
1982
|
+
/**
|
|
1983
|
+
* What `new Dialog(app.ui, options)` accepts.
|
|
1984
|
+
*
|
|
1985
|
+
* @public
|
|
1986
|
+
*/
|
|
1987
|
+
interface DialogOptions {
|
|
1988
|
+
/** The heading. Omit for a dialog with no title. */
|
|
1989
|
+
readonly title?: string;
|
|
1990
|
+
/** The body text. Omit for a dialog with no message. */
|
|
1991
|
+
readonly message?: string;
|
|
1992
|
+
/** The buttons, left to right. */
|
|
1993
|
+
readonly buttons?: readonly DialogButton[];
|
|
1994
|
+
/** The layer to mount into. Defaults to `"menu"`. */
|
|
1995
|
+
readonly layer?: string;
|
|
1996
|
+
/** Whether the dialog starts shown. Defaults to `false`. */
|
|
1997
|
+
readonly visible?: boolean;
|
|
1998
|
+
/** Whether a click on the backdrop dismisses the dialog. Defaults to `false`. */
|
|
1999
|
+
readonly dismissOnBackdrop?: boolean;
|
|
2000
|
+
/** The stacking order inside the layer. Defaults to `UI_DIALOG_Z_INDEX`, from the stylesheet. */
|
|
2001
|
+
readonly zIndex?: number;
|
|
2002
|
+
}
|
|
2003
|
+
/**
|
|
2004
|
+
* A modal panel with a title, a message, and buttons.
|
|
2005
|
+
*
|
|
2006
|
+
* @public
|
|
2007
|
+
*/
|
|
2008
|
+
export declare class Dialog {
|
|
2009
|
+
#private;
|
|
2010
|
+
/**
|
|
2011
|
+
* Builds the dialog and mounts it hidden.
|
|
2012
|
+
*
|
|
2013
|
+
* @param host - The overlay host, normally `app.ui`.
|
|
2014
|
+
* @param options - The title, the message, the buttons, and the layer.
|
|
2015
|
+
*/
|
|
2016
|
+
constructor(host: UiHost, options?: DialogOptions);
|
|
2017
|
+
/**
|
|
2018
|
+
* The dialog's outermost element, so a template can restyle it or mount more into it.
|
|
2019
|
+
*
|
|
2020
|
+
* @returns The element, or `null` when the app has no DOM overlay.
|
|
2021
|
+
*/
|
|
2022
|
+
get element(): HTMLDivElement | null;
|
|
2023
|
+
/**
|
|
2024
|
+
* Whether the dialog is shown.
|
|
2025
|
+
*
|
|
2026
|
+
* @returns `true` while it is on screen.
|
|
2027
|
+
*/
|
|
2028
|
+
get isVisible(): boolean;
|
|
2029
|
+
/**
|
|
2030
|
+
* Emitted with a button's `id` when it is pressed. The dialog does not hide itself; the game
|
|
2031
|
+
* decides, because "Cancel" and "Delete everything" want different follow-ups.
|
|
2032
|
+
*
|
|
2033
|
+
* @returns The signal.
|
|
2034
|
+
*/
|
|
2035
|
+
get onChosen(): SignalLike<string>;
|
|
2036
|
+
/**
|
|
2037
|
+
* Emitted after {@link Dialog.hide}, whatever caused it.
|
|
2038
|
+
*
|
|
2039
|
+
* @returns The signal.
|
|
2040
|
+
*/
|
|
2041
|
+
get onDismissed(): SignalLike;
|
|
2042
|
+
/** Shows the dialog. */
|
|
2043
|
+
show(): void;
|
|
2044
|
+
/** Hides the dialog and emits {@link Dialog.onDismissed}. */
|
|
2045
|
+
hide(): void;
|
|
2046
|
+
/**
|
|
2047
|
+
* Replaces the heading, if the dialog was built with one.
|
|
2048
|
+
*
|
|
2049
|
+
* @param text - The new heading.
|
|
2050
|
+
*/
|
|
2051
|
+
setTitle(text: string): void;
|
|
2052
|
+
/**
|
|
2053
|
+
* Replaces the body text, if the dialog was built with one.
|
|
2054
|
+
*
|
|
2055
|
+
* @param text - The new message.
|
|
2056
|
+
*/
|
|
2057
|
+
setMessage(text: string): void;
|
|
2058
|
+
/**
|
|
2059
|
+
* Replaces the buttons.
|
|
2060
|
+
*
|
|
2061
|
+
* @remarks
|
|
2062
|
+
* One dialog re-used for every question is cheaper than one dialog per question and keeps the
|
|
2063
|
+
* stacking predictable, so the buttons have to be able to change: a confirmation asks
|
|
2064
|
+
* "Yes"/"No", a save error offers "Retry"/"Cancel", and a locale change relabels both.
|
|
2065
|
+
*
|
|
2066
|
+
* @param buttons - The buttons, left to right. An empty list leaves the row empty.
|
|
2067
|
+
*
|
|
2068
|
+
* @example
|
|
2069
|
+
* ```ts ignore-check
|
|
2070
|
+
* dialog.setMessage("Delete this save?");
|
|
2071
|
+
* dialog.setButtons([{ id: "no", label: "No" }, { id: "yes", label: "Yes" }]);
|
|
2072
|
+
* ```
|
|
2073
|
+
*/
|
|
2074
|
+
setButtons(buttons: readonly DialogButton[]): void;
|
|
2075
|
+
/** Removes the dialog and unsubscribes. */
|
|
2076
|
+
dispose(): void;
|
|
2077
|
+
}
|
|
2078
|
+
//#endregion
|
|
2079
|
+
//#region src/widgets/loading-screen.d.ts
|
|
2080
|
+
/**
|
|
2081
|
+
* `LoadingScreen` (`docs/architecture/13-ui.md` §3): a full-overlay panel with a label and a
|
|
2082
|
+
* progress bar, bound to `app.assets`.
|
|
2083
|
+
*
|
|
2084
|
+
* ## Where the number comes from
|
|
2085
|
+
*
|
|
2086
|
+
* `app.assets.onProgress` carries `{ loaded, total, bytesLoaded, bytesTotal }`
|
|
2087
|
+
* (`packages/core/src/assets/types.ts`). {@link progressFraction} prefers the byte counts, because
|
|
2088
|
+
* a 40 MB level and a 2 KB config are not half the work each, and falls back to the handle counts
|
|
2089
|
+
* when the build recorded no sizes. A `BatchHandle` from `app.assets.preloadGroup("boot")` reports
|
|
2090
|
+
* its own mean in `progress`, which {@link LoadingScreen.progress} also accepts.
|
|
2091
|
+
*
|
|
2092
|
+
* ## Pairing with the asset-delivery rule
|
|
2093
|
+
*
|
|
2094
|
+
* A completed load settles as soon as it finishes before `app.start()` and after `app.stop()`;
|
|
2095
|
+
* once the loop runs, delivery waits for `PreUpdate`. So a boot screen that awaits
|
|
2096
|
+
* `preloadGroup("boot").promise` **before** `start()` needs no frames, and one that loads a level
|
|
2097
|
+
* mid-game is driven by the frames the loop is already running. Neither case needs this class to
|
|
2098
|
+
* poll.
|
|
2099
|
+
*/
|
|
2100
|
+
/**
|
|
2101
|
+
* What `new LoadingScreen(app.ui, options)` accepts.
|
|
2102
|
+
*
|
|
2103
|
+
* @public
|
|
2104
|
+
*/
|
|
2105
|
+
interface LoadingScreenOptions {
|
|
2106
|
+
/** The layer to mount into. Defaults to `"overlay"`. */
|
|
2107
|
+
readonly layer?: string;
|
|
2108
|
+
/** The initial label. Defaults to `"Loading…"`. */
|
|
2109
|
+
readonly label?: string;
|
|
2110
|
+
/** Whether the screen starts shown. Defaults to `true` — a boot screen is up before anything else. */
|
|
2111
|
+
readonly visible?: boolean;
|
|
2112
|
+
}
|
|
2113
|
+
/**
|
|
2114
|
+
* The fraction of an asset batch that is done.
|
|
2115
|
+
*
|
|
2116
|
+
* @remarks
|
|
2117
|
+
* Bytes when the build recorded sizes, handles otherwise, and `1` for an empty batch — a loading
|
|
2118
|
+
* screen that never reaches 100% because nothing was queued is worse than one that closes at once.
|
|
2119
|
+
*
|
|
2120
|
+
* @param progress - The payload of `app.assets.onProgress`.
|
|
2121
|
+
* @returns The fraction, in `[0, 1]`.
|
|
2122
|
+
*
|
|
2123
|
+
* @example
|
|
2124
|
+
* ```ts
|
|
2125
|
+
* progressFraction({ loaded: 1, total: 4, bytesLoaded: 0, bytesTotal: 0 }); // 0.25
|
|
2126
|
+
* ```
|
|
2127
|
+
*
|
|
2128
|
+
* @public
|
|
2129
|
+
*/
|
|
2130
|
+
export declare function progressFraction(progress: AssetProgress): number;
|
|
2131
|
+
/**
|
|
2132
|
+
* A full-overlay loading panel.
|
|
2133
|
+
*
|
|
2134
|
+
* @example
|
|
2135
|
+
* ```ts
|
|
2136
|
+
* const screen = new LoadingScreen(app.ui, { label: "Loading…" });
|
|
2137
|
+
* screen.bindTo(app.assets);
|
|
2138
|
+
* await app.assets.preloadGroup("boot").promise;
|
|
2139
|
+
* screen.hide();
|
|
2140
|
+
* ```
|
|
2141
|
+
*
|
|
2142
|
+
* @public
|
|
2143
|
+
*/
|
|
2144
|
+
export declare class LoadingScreen {
|
|
2145
|
+
#private;
|
|
2146
|
+
/**
|
|
2147
|
+
* Builds the screen and mounts it.
|
|
2148
|
+
*
|
|
2149
|
+
* @param host - The overlay host, normally `app.ui`.
|
|
2150
|
+
* @param options - The layer, the label, and the initial visibility.
|
|
2151
|
+
*/
|
|
2152
|
+
constructor(host: UiHost, options?: LoadingScreenOptions);
|
|
2153
|
+
/**
|
|
2154
|
+
* The screen's outermost element, so a template can restyle it or add a logo.
|
|
2155
|
+
*
|
|
2156
|
+
* @returns The element, or `null` when the app has no DOM overlay.
|
|
2157
|
+
*/
|
|
2158
|
+
get element(): HTMLDivElement | null;
|
|
2159
|
+
/**
|
|
2160
|
+
* Whether the screen is shown.
|
|
2161
|
+
*
|
|
2162
|
+
* @returns `true` while it is on screen.
|
|
2163
|
+
*/
|
|
2164
|
+
get isVisible(): boolean;
|
|
2165
|
+
/**
|
|
2166
|
+
* How far along the bar is, in `[0, 1]`. Writing it moves the bar; values outside the range are
|
|
2167
|
+
* clamped.
|
|
2168
|
+
*
|
|
2169
|
+
* @returns The fraction.
|
|
2170
|
+
*/
|
|
2171
|
+
get progress(): number;
|
|
2172
|
+
set progress(value: number);
|
|
2173
|
+
/**
|
|
2174
|
+
* Emitted after {@link LoadingScreen.hide}, whatever caused it.
|
|
2175
|
+
*
|
|
2176
|
+
* @returns The signal.
|
|
2177
|
+
*/
|
|
2178
|
+
get onDismissed(): SignalLike;
|
|
2179
|
+
/**
|
|
2180
|
+
* Follows an asset service's aggregate progress until {@link LoadingScreen.dispose} or a second
|
|
2181
|
+
* call to this method.
|
|
2182
|
+
*
|
|
2183
|
+
* @param assets - The asset service, normally `app.assets`.
|
|
2184
|
+
* @returns A function that stops following.
|
|
2185
|
+
*/
|
|
2186
|
+
bindTo(assets: Assets): Disconnect;
|
|
2187
|
+
/**
|
|
2188
|
+
* Replaces the label.
|
|
2189
|
+
*
|
|
2190
|
+
* @param text - The new label.
|
|
2191
|
+
*/
|
|
2192
|
+
setLabel(text: string): void;
|
|
2193
|
+
/** Shows the screen. */
|
|
2194
|
+
show(): void;
|
|
2195
|
+
/** Hides the screen and emits {@link LoadingScreen.onDismissed}. */
|
|
2196
|
+
hide(): void;
|
|
2197
|
+
/** Removes the screen and stops following the asset service. */
|
|
2198
|
+
dispose(): void;
|
|
2199
|
+
}
|
|
2200
|
+
//#endregion
|
|
2201
|
+
//#region src/widgets/menu-row.d.ts
|
|
2202
|
+
/**
|
|
2203
|
+
* The row vocabulary {@link Menu} draws, and the two pure functions that
|
|
2204
|
+
* turn a row's declaration into the text on screen.
|
|
2205
|
+
*
|
|
2206
|
+
* A row is **declarative**: it says what it edits (`get`/`set`) rather than how to draw it, so the
|
|
2207
|
+
* widget can render it, adjust it with Left/Right, announce it to a screen reader, and keep the
|
|
2208
|
+
* value in step with whatever else changes it. That is the difference between this and a list of
|
|
2209
|
+
* buttons: a settings screen written as buttons has to re-implement clamping, formatting and
|
|
2210
|
+
* repeat in every game.
|
|
2211
|
+
*/
|
|
2212
|
+
/**
|
|
2213
|
+
* Text that is either fixed or re-read on every refresh.
|
|
2214
|
+
*
|
|
2215
|
+
* @remarks
|
|
2216
|
+
* A function is what makes a menu localizable: `label: () => app.i18n.t("menu.resume")` re-renders
|
|
2217
|
+
* itself when `app.i18n.locale` changes, because {@link Menu.refresh} calls it again.
|
|
2218
|
+
*
|
|
2219
|
+
* @public
|
|
2220
|
+
*/
|
|
2221
|
+
type MenuLabel = string | (() => string);
|
|
2222
|
+
/**
|
|
2223
|
+
* The values a `"choice"` row cycles through: a fixed list, or one read per use.
|
|
2224
|
+
*
|
|
2225
|
+
* @public
|
|
2226
|
+
*/
|
|
2227
|
+
type MenuChoiceValues = readonly string[] | (() => readonly string[]);
|
|
2228
|
+
/**
|
|
2229
|
+
* What every selectable row carries.
|
|
2230
|
+
*
|
|
2231
|
+
* @public
|
|
2232
|
+
*/
|
|
2233
|
+
interface MenuRowBase {
|
|
2234
|
+
/** A stable id. It becomes the row's `data-row` attribute, which is what a test selects on. */
|
|
2235
|
+
readonly id: string;
|
|
2236
|
+
/** The left-hand text. */
|
|
2237
|
+
readonly label: MenuLabel;
|
|
2238
|
+
/** Whether the row can be selected. A row that answers `false` is drawn dimmed and skipped. */
|
|
2239
|
+
readonly enabled?: () => boolean;
|
|
2240
|
+
}
|
|
2241
|
+
/**
|
|
2242
|
+
* A row that runs something when it is activated.
|
|
2243
|
+
*
|
|
2244
|
+
* @public
|
|
2245
|
+
*/
|
|
2246
|
+
interface MenuActionRow extends MenuRowBase {
|
|
2247
|
+
/** What kind of row this is. */
|
|
2248
|
+
readonly kind: "action";
|
|
2249
|
+
/** The right-hand text, when the row shows one. */
|
|
2250
|
+
readonly value?: MenuLabel;
|
|
2251
|
+
/** What Enter, the pad's south button and a click do. */
|
|
2252
|
+
readonly activate?: () => void;
|
|
2253
|
+
}
|
|
2254
|
+
/**
|
|
2255
|
+
* A row that flips a flag.
|
|
2256
|
+
*
|
|
2257
|
+
* @public
|
|
2258
|
+
*/
|
|
2259
|
+
interface MenuToggleRow extends MenuRowBase {
|
|
2260
|
+
/** What kind of row this is. */
|
|
2261
|
+
readonly kind: "toggle";
|
|
2262
|
+
/** Reads the flag. */
|
|
2263
|
+
readonly get: () => boolean;
|
|
2264
|
+
/** Writes the flag. */
|
|
2265
|
+
readonly set: (value: boolean) => void;
|
|
2266
|
+
/** Renders the flag. Defaults to the menu's `text.on` / `text.off`. */
|
|
2267
|
+
readonly format?: (value: boolean) => string;
|
|
2268
|
+
}
|
|
2269
|
+
/**
|
|
2270
|
+
* A row that edits a number over a range.
|
|
2271
|
+
*
|
|
2272
|
+
* @remarks
|
|
2273
|
+
* Drawn as a native `<input type="range">` plus the formatted value, because dragging a knob is
|
|
2274
|
+
* worth having and `@ignifx/ui`'s own focus policy deliberately does not count a slider as a text
|
|
2275
|
+
* field (`docs/architecture/13-ui.md` §1), so a slider under the pointer never suppresses gameplay
|
|
2276
|
+
* input.
|
|
2277
|
+
*
|
|
2278
|
+
* @public
|
|
2279
|
+
*/
|
|
2280
|
+
interface MenuSliderRow extends MenuRowBase {
|
|
2281
|
+
/** What kind of row this is. */
|
|
2282
|
+
readonly kind: "slider";
|
|
2283
|
+
/** The lowest value the row may take. */
|
|
2284
|
+
readonly min: number;
|
|
2285
|
+
/** The highest value the row may take. */
|
|
2286
|
+
readonly max: number;
|
|
2287
|
+
/** How far one Left or Right press moves the value. */
|
|
2288
|
+
readonly step: number;
|
|
2289
|
+
/** Reads the current value. */
|
|
2290
|
+
readonly get: () => number;
|
|
2291
|
+
/** Writes a new value, already clamped and snapped to the step. */
|
|
2292
|
+
readonly set: (value: number) => void;
|
|
2293
|
+
/** Renders the value. Defaults to the number itself. */
|
|
2294
|
+
readonly format?: (value: number) => string;
|
|
2295
|
+
}
|
|
2296
|
+
/**
|
|
2297
|
+
* A row that cycles through a list of values.
|
|
2298
|
+
*
|
|
2299
|
+
* @public
|
|
2300
|
+
*/
|
|
2301
|
+
interface MenuChoiceRow extends MenuRowBase {
|
|
2302
|
+
/** What kind of row this is. */
|
|
2303
|
+
readonly kind: "choice";
|
|
2304
|
+
/** The values to cycle through, in order. */
|
|
2305
|
+
readonly values: MenuChoiceValues;
|
|
2306
|
+
/** Reads the current value. */
|
|
2307
|
+
readonly get: () => string;
|
|
2308
|
+
/** Writes the new value. */
|
|
2309
|
+
readonly set: (value: string) => void;
|
|
2310
|
+
/** Renders a value for display. Defaults to the value itself. */
|
|
2311
|
+
readonly format?: (value: string) => string;
|
|
2312
|
+
}
|
|
2313
|
+
/**
|
|
2314
|
+
* A row that shows one input binding and starts a rebind when it is activated.
|
|
2315
|
+
*
|
|
2316
|
+
* @remarks
|
|
2317
|
+
* The row knows nothing about `@ignifx/input`: it is handed the binding's path as a string and a
|
|
2318
|
+
* callback that starts whatever rebinding flow the game uses. `@ignifx/input`'s
|
|
2319
|
+
* `performInteractiveRebind` is the usual one.
|
|
2320
|
+
*
|
|
2321
|
+
* @public
|
|
2322
|
+
*/
|
|
2323
|
+
interface MenuBindingRow extends MenuRowBase {
|
|
2324
|
+
/** What kind of row this is. */
|
|
2325
|
+
readonly kind: "binding";
|
|
2326
|
+
/** Reads the binding path, such as `<Keyboard>/arrowUp`, or `""` when nothing is bound. */
|
|
2327
|
+
readonly path: () => string;
|
|
2328
|
+
/** Starts the rebind. */
|
|
2329
|
+
readonly rebind?: () => void;
|
|
2330
|
+
/** Whether this row's rebind is listening right now, which changes what the row shows. */
|
|
2331
|
+
readonly listening?: () => boolean;
|
|
2332
|
+
}
|
|
2333
|
+
/**
|
|
2334
|
+
* A non-selectable label that groups the rows under it.
|
|
2335
|
+
*
|
|
2336
|
+
* @public
|
|
2337
|
+
*/
|
|
2338
|
+
interface MenuHeadingRow {
|
|
2339
|
+
/** What kind of row this is. */
|
|
2340
|
+
readonly kind: "heading";
|
|
2341
|
+
/** A stable id, which becomes the row's `data-row` attribute. */
|
|
2342
|
+
readonly id: string;
|
|
2343
|
+
/** The heading text. */
|
|
2344
|
+
readonly label: MenuLabel;
|
|
2345
|
+
}
|
|
2346
|
+
/**
|
|
2347
|
+
* A non-selectable rule between groups of rows.
|
|
2348
|
+
*
|
|
2349
|
+
* @public
|
|
2350
|
+
*/
|
|
2351
|
+
interface MenuSeparatorRow {
|
|
2352
|
+
/** What kind of row this is. */
|
|
2353
|
+
readonly kind: "separator";
|
|
2354
|
+
/** A stable id, which becomes the row's `data-row` attribute. */
|
|
2355
|
+
readonly id: string;
|
|
2356
|
+
}
|
|
2357
|
+
/**
|
|
2358
|
+
* One row of a {@link Menu}.
|
|
2359
|
+
*
|
|
2360
|
+
* @public
|
|
2361
|
+
*/
|
|
2362
|
+
type MenuRow = MenuActionRow | MenuBindingRow | MenuChoiceRow | MenuHeadingRow | MenuSeparatorRow | MenuSliderRow | MenuToggleRow;
|
|
2363
|
+
/**
|
|
2364
|
+
* The words a menu uses for the states its rows can be in, so a localized game sets them once per
|
|
2365
|
+
* menu rather than on every row.
|
|
2366
|
+
*
|
|
2367
|
+
* @public
|
|
2368
|
+
*/
|
|
2369
|
+
interface MenuText {
|
|
2370
|
+
/** What a `"toggle"` row shows when it is on. Defaults to `"On"`. */
|
|
2371
|
+
readonly on?: MenuLabel;
|
|
2372
|
+
/** What a `"toggle"` row shows when it is off. Defaults to `"Off"`. */
|
|
2373
|
+
readonly off?: MenuLabel;
|
|
2374
|
+
/** What a `"binding"` row shows when nothing is bound. Defaults to `"—"`. */
|
|
2375
|
+
readonly unbound?: MenuLabel;
|
|
2376
|
+
/** What a `"binding"` row shows while it is listening. Defaults to `"Press any key…"`. */
|
|
2377
|
+
readonly listening?: MenuLabel;
|
|
2378
|
+
}
|
|
2379
|
+
/**
|
|
2380
|
+
* Reads a {@link MenuLabel}.
|
|
2381
|
+
*
|
|
2382
|
+
* @param label - The fixed string, the function, or nothing.
|
|
2383
|
+
* @param fallback - What to answer when `label` is `undefined`.
|
|
2384
|
+
* @returns The text to draw.
|
|
2385
|
+
*
|
|
2386
|
+
* @public
|
|
2387
|
+
*/
|
|
2388
|
+
export declare function resolveMenuLabel(label: MenuLabel | undefined, fallback: string): string;
|
|
2389
|
+
/**
|
|
2390
|
+
* Reads a {@link MenuChoiceValues}.
|
|
2391
|
+
*
|
|
2392
|
+
* @param values - The fixed list or the function.
|
|
2393
|
+
* @returns The values, in order.
|
|
2394
|
+
*
|
|
2395
|
+
* @public
|
|
2396
|
+
*/
|
|
2397
|
+
export declare function resolveMenuChoices(values: MenuChoiceValues): readonly string[];
|
|
2398
|
+
/**
|
|
2399
|
+
* Clamps a number into a range and snaps it to the step.
|
|
2400
|
+
*
|
|
2401
|
+
* @remarks
|
|
2402
|
+
* Snapping rather than accumulating is what stops a slider from drifting by floating-point error
|
|
2403
|
+
* after a few hundred key presses: every value is recomputed from `min` and a whole number of
|
|
2404
|
+
* steps.
|
|
2405
|
+
*
|
|
2406
|
+
* @param value - The raw value.
|
|
2407
|
+
* @param min - The lowest allowed value.
|
|
2408
|
+
* @param max - The highest allowed value.
|
|
2409
|
+
* @param step - The grid the value is snapped to. A step of `0` or less disables snapping.
|
|
2410
|
+
* @returns The clamped, snapped value.
|
|
2411
|
+
*
|
|
2412
|
+
* @example
|
|
2413
|
+
* ```ts
|
|
2414
|
+
* snapToStep(0.37, 0, 1, 0.05); // 0.35
|
|
2415
|
+
* ```
|
|
2416
|
+
*
|
|
2417
|
+
* @public
|
|
2418
|
+
*/
|
|
2419
|
+
export declare function snapToStep(value: number, min: number, max: number, step: number): number;
|
|
2420
|
+
/**
|
|
2421
|
+
* Renders an `@ignifx/input` binding path the way a player reads it.
|
|
2422
|
+
*
|
|
2423
|
+
* @param path - The binding path, such as `<Keyboard>/arrowUp`, or `""` for none.
|
|
2424
|
+
* @param unbound - What to answer for an empty path.
|
|
2425
|
+
* @returns The label, such as `Keyboard: Arrow up`.
|
|
2426
|
+
*
|
|
2427
|
+
* @example
|
|
2428
|
+
* ```ts
|
|
2429
|
+
* formatBindingPath("<Keyboard>/arrowUp", "—"); // "Keyboard: Arrow up"
|
|
2430
|
+
* formatBindingPath("", "—"); // "—"
|
|
2431
|
+
* ```
|
|
2432
|
+
*
|
|
2433
|
+
* @public
|
|
2434
|
+
*/
|
|
2435
|
+
export declare function formatBindingPath(path: string, unbound: string): string;
|
|
2436
|
+
//#endregion
|
|
2437
|
+
//#region src/widgets/menu.d.ts
|
|
2438
|
+
/**
|
|
2439
|
+
* `Menu` — the list widget every game menu is made of: a title, an optional subtitle, and a
|
|
2440
|
+
* vertical list of {@link MenuRow}s that keyboard, gamepad and pointer all drive through one
|
|
2441
|
+
* selection model.
|
|
2442
|
+
*
|
|
2443
|
+
* It is a DOM helper in the same family as `Dialog`, `Toast` and `LoadingScreen`
|
|
2444
|
+
* (`docs/architecture/13-ui.md` §3: *"plain DOM helper classes with no styling opinions beyond a
|
|
2445
|
+
* minimal stylesheet; templates ship their own CSS"*), and it follows the same two rules: with no
|
|
2446
|
+
* DOM overlay every method is a no-op and {@link Menu.element} is `null`, and every visible piece
|
|
2447
|
+
* carries a `UI_CLASS_NAMES` class that a game restyles.
|
|
2448
|
+
*
|
|
2449
|
+
* ## Why the widget owns the selection instead of the browser
|
|
2450
|
+
*
|
|
2451
|
+
* Every row is `tabindex="-1"` and the selected row is chosen by this class rather than by
|
|
2452
|
+
* `document.activeElement`. The reason is the gamepad: a pad produces no DOM focus events, so pad
|
|
2453
|
+
* navigation needs its own path anyway, and two focus authorities in one screen disagree the first
|
|
2454
|
+
* time a row is added or removed. The DOM focus that does exist goes to the **list**, once, which
|
|
2455
|
+
* is what lets `aria-activedescendant` tell a screen reader where the selection is and what lets
|
|
2456
|
+
* the widget read the keyboard at all. The pointer only *moves* the selection and activates it,
|
|
2457
|
+
* because a mouse already has a cursor.
|
|
2458
|
+
*
|
|
2459
|
+
* ## ARIA
|
|
2460
|
+
*
|
|
2461
|
+
* The list is `role="menu"` and its rows are `role="menuitem"`, with `role="menuitemcheckbox"` plus
|
|
2462
|
+
* `aria-checked` for a `"toggle"` row and `role="separator"` for headings and separators. `menu`
|
|
2463
|
+
* was chosen over `listbox`/`option` for two reasons: WAI-ARIA's `option` expresses only *"is in
|
|
2464
|
+
* the selection"*, so a toggle's on/off state has nowhere to live, while `menuitemcheckbox` is
|
|
2465
|
+
* exactly that state; and a menu is what this is — a list of commands the player runs, not a set of
|
|
2466
|
+
* values one of which is chosen. `aria-activedescendant` on the list expresses the roving selection
|
|
2467
|
+
* without moving focus, which both roles support.
|
|
2468
|
+
*
|
|
2469
|
+
* The one compromise is the slider row. ARIA has no `menuitemslider`, and neither `menuitem` nor
|
|
2470
|
+
* `option` may contain an interactive descendant, so the native `<input type="range">` is marked
|
|
2471
|
+
* `aria-hidden="true"` and `tabindex="-1"`: it is a pointer affordance only, it is not in the
|
|
2472
|
+
* accessibility tree, and the value reaches a screen reader through the row's own accessible name
|
|
2473
|
+
* (its label plus the formatted value), which is refreshed on every change. Left and Right on the
|
|
2474
|
+
* row adjust the value with no pointer at all.
|
|
2475
|
+
*/
|
|
2476
|
+
/**
|
|
2477
|
+
* What `new Menu(app.ui, options)` accepts.
|
|
2478
|
+
*
|
|
2479
|
+
* @public
|
|
2480
|
+
*/
|
|
2481
|
+
interface MenuOptions {
|
|
2482
|
+
/** A stable id; it becomes the panel's `data-menu` attribute. */
|
|
2483
|
+
readonly id: string;
|
|
2484
|
+
/** The panel's heading. Re-read on every {@link Menu.refresh}. */
|
|
2485
|
+
readonly title?: MenuLabel;
|
|
2486
|
+
/** A line of prose under the heading. */
|
|
2487
|
+
readonly subtitle?: MenuLabel;
|
|
2488
|
+
/** The overlay layer to mount into. Defaults to `"menu"`. */
|
|
2489
|
+
readonly layer?: string;
|
|
2490
|
+
/** The rows to start with. More usually arrive through {@link Menu.setRows}. */
|
|
2491
|
+
readonly rows?: readonly MenuRow[];
|
|
2492
|
+
/** Whether the menu starts shown. Defaults to `false`. */
|
|
2493
|
+
readonly visible?: boolean;
|
|
2494
|
+
/** Whether Escape and {@link Menu.cancel} back out of the menu. Defaults to `true`. */
|
|
2495
|
+
readonly cancelable?: boolean;
|
|
2496
|
+
/**
|
|
2497
|
+
* Whether the widget reads the keyboard itself. Defaults to `true`.
|
|
2498
|
+
*
|
|
2499
|
+
* @remarks
|
|
2500
|
+
* Turn it off when the game drives navigation from its own input actions, or every arrow press
|
|
2501
|
+
* moves the selection twice. A {@link MenuStack} built with a navigation
|
|
2502
|
+
* source does that for you.
|
|
2503
|
+
*/
|
|
2504
|
+
readonly keyboard?: boolean;
|
|
2505
|
+
/** Whether the selection wraps at both ends. Defaults to `true`. */
|
|
2506
|
+
readonly wrap?: boolean;
|
|
2507
|
+
/** The words the rows use for their states. */
|
|
2508
|
+
readonly text?: MenuText;
|
|
2509
|
+
}
|
|
2510
|
+
/**
|
|
2511
|
+
* A panel of selectable rows in an overlay layer.
|
|
2512
|
+
*
|
|
2513
|
+
* @example
|
|
2514
|
+
* ```ts ignore-check
|
|
2515
|
+
* const pause = new Menu(app.ui, { id: "pause", title: "Paused" });
|
|
2516
|
+
* pause.setRows([
|
|
2517
|
+
* { kind: "action", id: "resume", label: "Resume", activate: () => pause.hide() },
|
|
2518
|
+
* { kind: "slider", id: "music", label: "Music", min: 0, max: 1, step: 0.05,
|
|
2519
|
+
* get: () => music.volume, set: (v) => { music.volume = v; },
|
|
2520
|
+
* format: (v) => `${String(Math.round(v * 100))}%` },
|
|
2521
|
+
* ]);
|
|
2522
|
+
* pause.show();
|
|
2523
|
+
* ```
|
|
2524
|
+
*
|
|
2525
|
+
* @public
|
|
2526
|
+
*/
|
|
2527
|
+
export declare class Menu {
|
|
2528
|
+
#private;
|
|
2529
|
+
/** The id the menu was built with. */
|
|
2530
|
+
readonly id: string;
|
|
2531
|
+
/**
|
|
2532
|
+
* Builds the panel and mounts it, hidden unless `options.visible` says otherwise.
|
|
2533
|
+
*
|
|
2534
|
+
* @param host - The overlay host, normally `app.ui`.
|
|
2535
|
+
* @param options - The id, the heading, the layer, and the starting rows.
|
|
2536
|
+
*/
|
|
2537
|
+
constructor(host: UiHost, options: MenuOptions);
|
|
2538
|
+
/**
|
|
2539
|
+
* The panel element, so a game can restyle it or a test can read it.
|
|
2540
|
+
*
|
|
2541
|
+
* @returns The element, or `null` under an app with no DOM overlay.
|
|
2542
|
+
*/
|
|
2543
|
+
get element(): HTMLDivElement | null;
|
|
2544
|
+
/**
|
|
2545
|
+
* Whether the panel is on screen.
|
|
2546
|
+
*
|
|
2547
|
+
* @returns `true` between {@link Menu.show} and {@link Menu.hide}.
|
|
2548
|
+
*/
|
|
2549
|
+
get isVisible(): boolean;
|
|
2550
|
+
/**
|
|
2551
|
+
* The rows the menu is drawing.
|
|
2552
|
+
*
|
|
2553
|
+
* @returns The rows, in draw order.
|
|
2554
|
+
*/
|
|
2555
|
+
get rows(): readonly MenuRow[];
|
|
2556
|
+
/**
|
|
2557
|
+
* The selected row.
|
|
2558
|
+
*
|
|
2559
|
+
* @returns The row under the selection, or `null` when nothing can be selected.
|
|
2560
|
+
*/
|
|
2561
|
+
get selected(): MenuRow | null;
|
|
2562
|
+
/**
|
|
2563
|
+
* Where the selection sits.
|
|
2564
|
+
*
|
|
2565
|
+
* @returns The index into {@link Menu.rows}.
|
|
2566
|
+
*/
|
|
2567
|
+
get selectedIndex(): number;
|
|
2568
|
+
/**
|
|
2569
|
+
* Whether Escape and {@link Menu.cancel} back out of this menu. A title screen sets it `false`.
|
|
2570
|
+
*
|
|
2571
|
+
* @returns `true` when the menu can be dismissed.
|
|
2572
|
+
*/
|
|
2573
|
+
get cancelable(): boolean;
|
|
2574
|
+
set cancelable(value: boolean);
|
|
2575
|
+
/**
|
|
2576
|
+
* Whether the widget reads the keyboard itself.
|
|
2577
|
+
*
|
|
2578
|
+
* @returns `true` while its own `keydown` handler acts.
|
|
2579
|
+
*/
|
|
2580
|
+
get keyboardEnabled(): boolean;
|
|
2581
|
+
set keyboardEnabled(value: boolean);
|
|
2582
|
+
/**
|
|
2583
|
+
* Emitted with the newly selected row whenever the selection moves, from any device. A game
|
|
2584
|
+
* connects a click sound to it.
|
|
2585
|
+
*
|
|
2586
|
+
* @returns The signal.
|
|
2587
|
+
*/
|
|
2588
|
+
get onSelectionChanged(): SignalLike<MenuRow>;
|
|
2589
|
+
/**
|
|
2590
|
+
* Emitted with the row that was activated, after its own handler ran.
|
|
2591
|
+
*
|
|
2592
|
+
* @returns The signal.
|
|
2593
|
+
*/
|
|
2594
|
+
get onActivated(): SignalLike<MenuRow>;
|
|
2595
|
+
/**
|
|
2596
|
+
* Emitted by {@link Menu.cancel} — Escape, the pad's east button, or a call — when the menu is
|
|
2597
|
+
* {@link Menu.cancelable}. A {@link MenuStack} connects `pop` to it.
|
|
2598
|
+
*
|
|
2599
|
+
* @returns The signal.
|
|
2600
|
+
*/
|
|
2601
|
+
get onBack(): SignalLike;
|
|
2602
|
+
/**
|
|
2603
|
+
* Replaces the rows and rebuilds the panel.
|
|
2604
|
+
*
|
|
2605
|
+
* @remarks
|
|
2606
|
+
* Rebuilding rather than diffing is deliberate: the row list changes when a save appears, when a
|
|
2607
|
+
* control scheme changes and when the locale changes, and a menu of at most a few dozen rows is
|
|
2608
|
+
* not worth a reconciler. The selection stays on the same row id when that id is still present.
|
|
2609
|
+
*
|
|
2610
|
+
* @param rows - The rows, in draw order.
|
|
2611
|
+
*/
|
|
2612
|
+
setRows(rows: readonly MenuRow[]): void;
|
|
2613
|
+
/** Re-reads every label and value and redraws the selection. */
|
|
2614
|
+
refresh(): void;
|
|
2615
|
+
/** Shows the panel, puts the selection on the first row that can take it, and focuses the list. */
|
|
2616
|
+
show(): void;
|
|
2617
|
+
/** Hides the panel. */
|
|
2618
|
+
hide(): void;
|
|
2619
|
+
/**
|
|
2620
|
+
* Moves the selection, skipping headings, separators and disabled rows.
|
|
2621
|
+
*
|
|
2622
|
+
* @param delta - `-1` for up, `1` for down.
|
|
2623
|
+
*/
|
|
2624
|
+
moveSelection(delta: -1 | 1): void;
|
|
2625
|
+
/**
|
|
2626
|
+
* Puts the selection on a row by id.
|
|
2627
|
+
*
|
|
2628
|
+
* @param id - The row's {@link MenuRowBase.id}.
|
|
2629
|
+
* @returns `true` when a selectable row with that id was found.
|
|
2630
|
+
*/
|
|
2631
|
+
select(id: string): boolean;
|
|
2632
|
+
/**
|
|
2633
|
+
* Runs the selected row's Left or Right behaviour: a slider moves by one step, a toggle flips,
|
|
2634
|
+
* and a choice advances.
|
|
2635
|
+
*
|
|
2636
|
+
* @param direction - `-1` for left, `1` for right.
|
|
2637
|
+
*/
|
|
2638
|
+
adjustSelection(direction: -1 | 1): void;
|
|
2639
|
+
/** Runs the selected row's activate behaviour. */
|
|
2640
|
+
activateSelection(): void;
|
|
2641
|
+
/**
|
|
2642
|
+
* Backs out of the menu, if it is {@link Menu.cancelable}.
|
|
2643
|
+
*
|
|
2644
|
+
* @returns `true` when {@link Menu.onBack} was emitted, so the caller knows the press was used.
|
|
2645
|
+
*/
|
|
2646
|
+
cancel(): boolean;
|
|
2647
|
+
/** Removes the panel from the overlay and unsubscribes everything. */
|
|
2648
|
+
dispose(): void;
|
|
2649
|
+
}
|
|
2650
|
+
//#endregion
|
|
2651
|
+
//#region src/widgets/menu-stack.d.ts
|
|
2652
|
+
/**
|
|
2653
|
+
* `MenuStack` — screen navigation for {@link Menu}: push a screen on top, pop back to the one
|
|
2654
|
+
* underneath, and drive the whole stack from one place.
|
|
2655
|
+
*
|
|
2656
|
+
* Every front end that has more than one screen needs the same three things, and they are the
|
|
2657
|
+
* three things games get wrong: exactly one screen is visible at a time; Escape (or the pad's east
|
|
2658
|
+
* button) unwinds exactly one level; and a held direction repeats on the **unscaled** clock, so
|
|
2659
|
+
* navigation still works while `app.pause()` has stopped the game.
|
|
2660
|
+
*
|
|
2661
|
+
* ## Why the input is an interface and not `@ignifx/input`
|
|
2662
|
+
*
|
|
2663
|
+
* `@ignifx/input` is an optional peer of `@ignifx/ui` (`docs/architecture/13-ui.md` header), and a
|
|
2664
|
+
* menu is exactly the kind of thing a game builds without it. {@link MenuNavigation} is therefore a
|
|
2665
|
+
* structural shape that an `InputAction` already satisfies — pass the actions of a `UI` action map
|
|
2666
|
+
* straight in — while a game with no input extension passes its own objects, or nothing at all and
|
|
2667
|
+
* uses the widget's own keyboard handling.
|
|
2668
|
+
*
|
|
2669
|
+
* ```ts ignore-check
|
|
2670
|
+
* const ui = app.input.actions.maps.get("UI") ?? null;
|
|
2671
|
+
* const stack = new MenuStack({
|
|
2672
|
+
* navigation: {
|
|
2673
|
+
* move: ui?.actions.get("menuMove") ?? null,
|
|
2674
|
+
* submit: ui?.actions.get("menuSubmit") ?? null,
|
|
2675
|
+
* back: ui?.actions.get("menuBack") ?? null,
|
|
2676
|
+
* },
|
|
2677
|
+
* });
|
|
2678
|
+
* ```
|
|
2679
|
+
*
|
|
2680
|
+
* A stack built with a navigation source turns each pushed menu's own keyboard handling **off**
|
|
2681
|
+
* while the menu is on the stack, and restores it on the way out: otherwise a keyboard bound to
|
|
2682
|
+
* `menuMove` would move the selection twice per press, once through the action and once through
|
|
2683
|
+
* the DOM.
|
|
2684
|
+
*/
|
|
2685
|
+
/**
|
|
2686
|
+
* Anything with a two-dimensional value, which `@ignifx/input`'s `InputAction` is.
|
|
2687
|
+
*
|
|
2688
|
+
* @public
|
|
2689
|
+
*/
|
|
2690
|
+
interface MenuVectorSource {
|
|
2691
|
+
/** The direction, `-1` to `1` on each axis. Positive `y` is up. */
|
|
2692
|
+
readonly vector: Vec2Like;
|
|
2693
|
+
}
|
|
2694
|
+
/**
|
|
2695
|
+
* Anything with a press edge, which `@ignifx/input`'s `InputAction` is.
|
|
2696
|
+
*
|
|
2697
|
+
* @public
|
|
2698
|
+
*/
|
|
2699
|
+
interface MenuButtonSource {
|
|
2700
|
+
/** Whether the control went down this frame. */
|
|
2701
|
+
readonly wasPressedThisFrame: boolean;
|
|
2702
|
+
}
|
|
2703
|
+
/**
|
|
2704
|
+
* The three controls a menu stack reads.
|
|
2705
|
+
*
|
|
2706
|
+
* @public
|
|
2707
|
+
*/
|
|
2708
|
+
interface MenuNavigation {
|
|
2709
|
+
/** Moves the selection (`y`) and adjusts the selected row (`x`). */
|
|
2710
|
+
readonly move?: MenuVectorSource | null;
|
|
2711
|
+
/** Activates the selected row. */
|
|
2712
|
+
readonly submit?: MenuButtonSource | null;
|
|
2713
|
+
/** Backs out one screen. */
|
|
2714
|
+
readonly back?: MenuButtonSource | null;
|
|
2715
|
+
}
|
|
2716
|
+
/**
|
|
2717
|
+
* What `new MenuStack(options)` accepts.
|
|
2718
|
+
*
|
|
2719
|
+
* @public
|
|
2720
|
+
*/
|
|
2721
|
+
interface MenuStackOptions {
|
|
2722
|
+
/** The controls to read in {@link MenuStack.update}. Omit to drive the stack by hand. */
|
|
2723
|
+
readonly navigation?: MenuNavigation;
|
|
2724
|
+
/** How long the first repeat of a held direction waits, in seconds. Defaults to `0.35`. */
|
|
2725
|
+
readonly repeatDelay?: number;
|
|
2726
|
+
/** How long each following repeat waits, in seconds. Defaults to `0.12`. */
|
|
2727
|
+
readonly repeatInterval?: number;
|
|
2728
|
+
/** How far an axis must move before it counts as a direction. Defaults to `0.5`. */
|
|
2729
|
+
readonly threshold?: number;
|
|
2730
|
+
}
|
|
2731
|
+
/**
|
|
2732
|
+
* A stack of {@link Menu} screens, innermost last.
|
|
2733
|
+
*
|
|
2734
|
+
* @example
|
|
2735
|
+
* ```ts ignore-check
|
|
2736
|
+
* const stack = new MenuStack({ navigation });
|
|
2737
|
+
* stack.push(title);
|
|
2738
|
+
* // in a script that runs while paused:
|
|
2739
|
+
* stack.update(app.time.unscaledDeltaTime);
|
|
2740
|
+
* ```
|
|
2741
|
+
*
|
|
2742
|
+
* @public
|
|
2743
|
+
*/
|
|
2744
|
+
export declare class MenuStack {
|
|
2745
|
+
#private;
|
|
2746
|
+
/**
|
|
2747
|
+
* Builds an empty stack.
|
|
2748
|
+
*
|
|
2749
|
+
* @param options - The controls to read, and the repeat timings.
|
|
2750
|
+
*/
|
|
2751
|
+
constructor(options?: MenuStackOptions);
|
|
2752
|
+
/**
|
|
2753
|
+
* The menus on the stack, outermost first.
|
|
2754
|
+
*
|
|
2755
|
+
* @returns The menus, in push order.
|
|
2756
|
+
*/
|
|
2757
|
+
get menus(): readonly Menu[];
|
|
2758
|
+
/**
|
|
2759
|
+
* The menu on top, which is the visible one.
|
|
2760
|
+
*
|
|
2761
|
+
* @returns The top menu, or `null` when the stack is empty.
|
|
2762
|
+
*/
|
|
2763
|
+
get top(): Menu | null;
|
|
2764
|
+
/**
|
|
2765
|
+
* The menu at the bottom, which is the one the stack was opened with.
|
|
2766
|
+
*
|
|
2767
|
+
* @returns The first menu pushed, or `null` when the stack is empty.
|
|
2768
|
+
*/
|
|
2769
|
+
get bottom(): Menu | null;
|
|
2770
|
+
/**
|
|
2771
|
+
* How deep the stack is.
|
|
2772
|
+
*
|
|
2773
|
+
* @returns The number of menus on it.
|
|
2774
|
+
*/
|
|
2775
|
+
get depth(): number;
|
|
2776
|
+
/**
|
|
2777
|
+
* Whether any menu is open.
|
|
2778
|
+
*
|
|
2779
|
+
* @returns `true` while the stack is not empty.
|
|
2780
|
+
*/
|
|
2781
|
+
get isOpen(): boolean;
|
|
2782
|
+
/**
|
|
2783
|
+
* Whether {@link MenuStack.update} is reading its controls.
|
|
2784
|
+
*
|
|
2785
|
+
* @remarks
|
|
2786
|
+
* Set it while something modal is on top of the menu — a confirmation `Dialog`, or a rebind that
|
|
2787
|
+
* is listening for the next key — so that the same press does not reach both.
|
|
2788
|
+
*
|
|
2789
|
+
* @returns `true` while navigation is suspended.
|
|
2790
|
+
*/
|
|
2791
|
+
get suspended(): boolean;
|
|
2792
|
+
set suspended(value: boolean);
|
|
2793
|
+
/**
|
|
2794
|
+
* Emitted with the new top menu — `null` when the stack empties — whenever the stack changes. A
|
|
2795
|
+
* game connects its audio ducking and its pause state to it.
|
|
2796
|
+
*
|
|
2797
|
+
* @returns The signal.
|
|
2798
|
+
*/
|
|
2799
|
+
get onChanged(): SignalLike<Menu | null>;
|
|
2800
|
+
/**
|
|
2801
|
+
* Emitted with the newly selected row whenever the selection moves on the top menu.
|
|
2802
|
+
*
|
|
2803
|
+
* @returns The signal.
|
|
2804
|
+
*/
|
|
2805
|
+
get onSelectionChanged(): SignalLike<MenuRow>;
|
|
2806
|
+
/**
|
|
2807
|
+
* Emitted with the row that was activated on the top menu.
|
|
2808
|
+
*
|
|
2809
|
+
* @returns The signal.
|
|
2810
|
+
*/
|
|
2811
|
+
get onActivated(): SignalLike<MenuRow>;
|
|
2812
|
+
/**
|
|
2813
|
+
* Hides whatever is on top and shows `menu` over it.
|
|
2814
|
+
*
|
|
2815
|
+
* @param menu - The menu to open.
|
|
2816
|
+
*/
|
|
2817
|
+
push(menu: Menu): void;
|
|
2818
|
+
/**
|
|
2819
|
+
* Closes the top menu and shows the one underneath.
|
|
2820
|
+
*
|
|
2821
|
+
* @returns The menu that was closed, or `null` when the stack was already empty.
|
|
2822
|
+
*/
|
|
2823
|
+
pop(): Menu | null;
|
|
2824
|
+
/** Closes every menu on the stack. */
|
|
2825
|
+
closeAll(): void;
|
|
2826
|
+
/** Re-reads every label on every menu on the stack, for a locale change. */
|
|
2827
|
+
refresh(): void;
|
|
2828
|
+
/**
|
|
2829
|
+
* Reads the navigation controls and applies them to the top menu.
|
|
2830
|
+
*
|
|
2831
|
+
* @remarks
|
|
2832
|
+
* Call it from a script that declares `static updateWhenPaused = true`, with
|
|
2833
|
+
* `app.time.unscaledDeltaTime`: a menu that repeats a held direction has to keep time while the
|
|
2834
|
+
* game is stopped, and scaled time is pinned at zero while it is.
|
|
2835
|
+
*
|
|
2836
|
+
* @param unscaledDelta - Seconds since the last call, on the unscaled clock.
|
|
2837
|
+
*/
|
|
2838
|
+
update(unscaledDelta: number): void;
|
|
2839
|
+
/** Drops every subscription. The menus themselves belong to the game and are not disposed. */
|
|
2840
|
+
dispose(): void;
|
|
2841
|
+
}
|
|
2842
|
+
//#endregion
|
|
2843
|
+
//#region src/widgets/toast.d.ts
|
|
2844
|
+
/**
|
|
2845
|
+
* `Toast` (`docs/architecture/13-ui.md` §3): a transient message stacked in a corner of the
|
|
2846
|
+
* overlay.
|
|
2847
|
+
*
|
|
2848
|
+
* ## Why the clock is the app's, not the browser's
|
|
2849
|
+
*
|
|
2850
|
+
* A toast dismisses itself after a number of **game seconds**, advanced by
|
|
2851
|
+
* {@link Toast.advance} from the game's own loop, rather than by `setTimeout`. Three reasons: it
|
|
2852
|
+
* pauses when the game pauses, it is deterministic in a headless test that steps the clock, and it
|
|
2853
|
+
* cannot fire after the app has been disposed. A game that wants wall-clock timing passes
|
|
2854
|
+
* `app.time.unscaledDeltaTime`.
|
|
2855
|
+
*
|
|
2856
|
+
* The consequence is the one thing to remember: **`app.pause()` stops `update` for every ordinary
|
|
2857
|
+
* script**, so a toast advanced from an ordinary script freezes with the game and a message shown
|
|
2858
|
+
* from a pause menu never expires. The script that calls {@link Toast.advance} declares
|
|
2859
|
+
* `static updateWhenPaused = true` and passes `app.time.unscaledDeltaTime`. `UiSystem` deliberately
|
|
2860
|
+
* does not advance toasts for you: `docs/architecture/13-ui.md` §3 defines a toast as running on
|
|
2861
|
+
* the game clock, and a system that advanced every toast would take that choice away from the game
|
|
2862
|
+
* and would have to keep a registry of every toast ever built.
|
|
2863
|
+
*/
|
|
2864
|
+
/**
|
|
2865
|
+
* What `new Toast(app.ui, options)` accepts.
|
|
2866
|
+
*
|
|
2867
|
+
* @public
|
|
2868
|
+
*/
|
|
2869
|
+
interface ToastOptions {
|
|
2870
|
+
/** The layer to mount the stack into. Defaults to `"overlay"`. */
|
|
2871
|
+
readonly layer?: string;
|
|
2872
|
+
/** How long a message stays up, in seconds, unless {@link Toast.show} overrides it. */
|
|
2873
|
+
readonly duration?: number;
|
|
2874
|
+
/** How many messages are stacked before the oldest is dropped. Defaults to `4`. */
|
|
2875
|
+
readonly maxVisible?: number;
|
|
2876
|
+
}
|
|
2877
|
+
/**
|
|
2878
|
+
* A stack of transient messages.
|
|
2879
|
+
*
|
|
2880
|
+
* @example
|
|
2881
|
+
* ```ts
|
|
2882
|
+
* const toasts = new Toast(app.ui);
|
|
2883
|
+
* toasts.show("Checkpoint reached");
|
|
2884
|
+
* // in the update of a script that declares `static updateWhenPaused = true`:
|
|
2885
|
+
* toasts.advance(app.time.unscaledDeltaTime);
|
|
2886
|
+
* ```
|
|
2887
|
+
*
|
|
2888
|
+
* @public
|
|
2889
|
+
*/
|
|
2890
|
+
export declare class Toast {
|
|
2891
|
+
#private;
|
|
2892
|
+
/**
|
|
2893
|
+
* Builds the stack and mounts it.
|
|
2894
|
+
*
|
|
2895
|
+
* @param host - The overlay host, normally `app.ui`.
|
|
2896
|
+
* @param options - The layer, the default duration, and the stack depth.
|
|
2897
|
+
*/
|
|
2898
|
+
constructor(host: UiHost, options?: ToastOptions);
|
|
2899
|
+
/**
|
|
2900
|
+
* The stack element, so a template can reposition it.
|
|
2901
|
+
*
|
|
2902
|
+
* @returns The element, or `null` when the app has no DOM overlay.
|
|
2903
|
+
*/
|
|
2904
|
+
get element(): HTMLDivElement | null;
|
|
2905
|
+
/**
|
|
2906
|
+
* The messages currently on screen, oldest first.
|
|
2907
|
+
*
|
|
2908
|
+
* @returns The texts.
|
|
2909
|
+
*/
|
|
2910
|
+
get messages(): readonly string[];
|
|
2911
|
+
/**
|
|
2912
|
+
* Emitted with a message's text when it times out or is pushed off the stack.
|
|
2913
|
+
*
|
|
2914
|
+
* @returns The signal.
|
|
2915
|
+
*/
|
|
2916
|
+
get onDismissed(): SignalLike<string>;
|
|
2917
|
+
/**
|
|
2918
|
+
* Shows a message.
|
|
2919
|
+
*
|
|
2920
|
+
* @param text - The message.
|
|
2921
|
+
* @param duration - How long it stays up, in seconds; defaults to the stack's own duration.
|
|
2922
|
+
*/
|
|
2923
|
+
show(text: string, duration?: number): void;
|
|
2924
|
+
/**
|
|
2925
|
+
* Advances every message's timer.
|
|
2926
|
+
*
|
|
2927
|
+
* @remarks
|
|
2928
|
+
* Nothing calls this for you. The script that does must declare `static updateWhenPaused = true`
|
|
2929
|
+
* if toasts are to expire while the game is paused — a menu's "Saved" message is shown from a
|
|
2930
|
+
* paused game, and an ordinary script gets no `update` there.
|
|
2931
|
+
*
|
|
2932
|
+
* @param deltaSeconds - Seconds elapsed since the previous call; `dt` from a script's `update`, or
|
|
2933
|
+
* `app.time.unscaledDeltaTime` when the toast has to expire while the game is paused.
|
|
2934
|
+
*/
|
|
2935
|
+
advance(deltaSeconds: number): void;
|
|
2936
|
+
/** Removes every message at once. */
|
|
2937
|
+
clear(): void;
|
|
2938
|
+
/** Removes the stack and unsubscribes. */
|
|
2939
|
+
dispose(): void;
|
|
2940
|
+
}
|
|
2941
|
+
//#endregion
|
|
2942
|
+
//#region src/widgets/virtual-button.d.ts
|
|
2943
|
+
/**
|
|
2944
|
+
* `VirtualButton` (`docs/architecture/13-ui.md` §3): an on-screen button that writes a
|
|
2945
|
+
* `<Virtual>/…` button control, so `jump` is one action bound to a key, a gamepad face button, and
|
|
2946
|
+
* this widget at the same time.
|
|
2947
|
+
*
|
|
2948
|
+
* A real `<button>` element rather than a `<div>`, so it is focusable, announced by a screen
|
|
2949
|
+
* reader, and reachable by keyboard. That has one consequence worth knowing: pressing it with the
|
|
2950
|
+
* keyboard fires a `click`, not a `pointerdown`, so the button also releases on `blur` — otherwise a
|
|
2951
|
+
* `Tab` away mid-press would stick.
|
|
2952
|
+
*/
|
|
2953
|
+
/**
|
|
2954
|
+
* What `new VirtualButton(app, options)` accepts.
|
|
2955
|
+
*
|
|
2956
|
+
* @public
|
|
2957
|
+
*/
|
|
2958
|
+
interface VirtualButtonOptions {
|
|
2959
|
+
/** The `<Virtual>/…` control to write. */
|
|
2960
|
+
readonly control: string;
|
|
2961
|
+
/** The glyph or word drawn on the button. Defaults to the control name. */
|
|
2962
|
+
readonly label?: string;
|
|
2963
|
+
/** The layer to mount into. Defaults to `"hud"`. */
|
|
2964
|
+
readonly layer?: string;
|
|
2965
|
+
/** Inline styles applied to the button, for placement. */
|
|
2966
|
+
readonly style?: Readonly<Record<string, string>>;
|
|
2967
|
+
/** An accessible label. Defaults to the control name. */
|
|
2968
|
+
readonly ariaLabel?: string;
|
|
2969
|
+
}
|
|
2970
|
+
/**
|
|
2971
|
+
* An on-screen button.
|
|
2972
|
+
*
|
|
2973
|
+
* @example
|
|
2974
|
+
* ```ts
|
|
2975
|
+
* const jump = new VirtualButton(app, { control: "jump", label: "A" });
|
|
2976
|
+
* ```
|
|
2977
|
+
*
|
|
2978
|
+
* @public
|
|
2979
|
+
*/
|
|
2980
|
+
export declare class VirtualButton {
|
|
2981
|
+
#private;
|
|
2982
|
+
/**
|
|
2983
|
+
* Builds the widget and mounts it.
|
|
2984
|
+
*
|
|
2985
|
+
* @param app - The running app; `app.ui` and `app.input.devices.virtual` are the parts used.
|
|
2986
|
+
* @param options - The control name, the label, the layer, and the placement styles.
|
|
2987
|
+
* @throws IgnifxError with code `IGX-1305` when `@ignifx/input` is not registered.
|
|
2988
|
+
*/
|
|
2989
|
+
constructor(app: App, options: VirtualButtonOptions);
|
|
2990
|
+
/**
|
|
2991
|
+
* The button element, so a template can restyle or reposition it.
|
|
2992
|
+
*
|
|
2993
|
+
* @returns The element, or `null` when the app has no DOM overlay.
|
|
2994
|
+
*/
|
|
2995
|
+
get element(): HTMLButtonElement | null;
|
|
2996
|
+
/**
|
|
2997
|
+
* The control this button writes.
|
|
2998
|
+
*
|
|
2999
|
+
* @returns The name, as it appears after `<Virtual>/`.
|
|
3000
|
+
*/
|
|
3001
|
+
get control(): string;
|
|
3002
|
+
/**
|
|
3003
|
+
* Whether the button is currently held.
|
|
3004
|
+
*
|
|
3005
|
+
* @returns `true` while it is pressed.
|
|
3006
|
+
*/
|
|
3007
|
+
get isPressed(): boolean;
|
|
3008
|
+
/** Removes the widget, unsubscribes, and releases the control. */
|
|
3009
|
+
dispose(): void;
|
|
3010
|
+
}
|
|
3011
|
+
//#endregion
|
|
3012
|
+
//#region src/widgets/virtual-device.d.ts
|
|
3013
|
+
/**
|
|
3014
|
+
* How `@ignifx/ui` reaches `@ignifx/input`'s virtual device without importing it
|
|
3015
|
+
* (`docs/architecture/13-ui.md` §3, `08-input.md` §8).
|
|
3016
|
+
*
|
|
3017
|
+
* `@ignifx/input` is an **optional** peer: the overlay host, the text components, and the
|
|
3018
|
+
* localization service do not need it, and only the two touch widgets do. Importing it — even
|
|
3019
|
+
* `import type` — would pull its `declare module "@ignifx/core"` augmentation into every consumer's
|
|
3020
|
+
* program, so an app that installs `@ignifx/ui` alone would suddenly have a typed `app.input` that
|
|
3021
|
+
* does not exist at runtime. The device is therefore reached structurally: the two methods the
|
|
3022
|
+
* widgets call, found by name on `app.input.devices.virtual`.
|
|
3023
|
+
*
|
|
3024
|
+
* `VirtualDevice` satisfies {@link VirtualDeviceLike} exactly
|
|
3025
|
+
* (`packages/input/src/devices/virtual.ts`), so nothing is lost by not naming the class.
|
|
3026
|
+
*/
|
|
3027
|
+
/**
|
|
3028
|
+
* The part of `@ignifx/input`'s virtual device the touch widgets use.
|
|
3029
|
+
*
|
|
3030
|
+
* @remarks
|
|
3031
|
+
* Structural on purpose. A test passes a recording double; a game passes
|
|
3032
|
+
* `app.input.devices.virtual`.
|
|
3033
|
+
*
|
|
3034
|
+
* @public
|
|
3035
|
+
*/
|
|
3036
|
+
interface VirtualDeviceLike {
|
|
3037
|
+
/**
|
|
3038
|
+
* Writes a scalar control, creating it when it does not exist.
|
|
3039
|
+
*
|
|
3040
|
+
* @param name - The control name, as it appears after `<Virtual>/`.
|
|
3041
|
+
* @param value - The new value.
|
|
3042
|
+
*/
|
|
3043
|
+
set(name: string, value: number): void;
|
|
3044
|
+
/**
|
|
3045
|
+
* Writes a vector control, creating it when it does not exist.
|
|
3046
|
+
*
|
|
3047
|
+
* @param name - The control name.
|
|
3048
|
+
* @param x - The new x component.
|
|
3049
|
+
* @param y - The new y component.
|
|
3050
|
+
*/
|
|
3051
|
+
setVector(name: string, x: number, y: number): void;
|
|
3052
|
+
}
|
|
3053
|
+
/**
|
|
3054
|
+
* Finds `app.input.devices.virtual`, if `@ignifx/input` is registered.
|
|
3055
|
+
*
|
|
3056
|
+
* @param app - The running app.
|
|
3057
|
+
* @returns The device, or `null` when the input extension is not installed.
|
|
3058
|
+
*
|
|
3059
|
+
* @example
|
|
3060
|
+
* ```ts
|
|
3061
|
+
* const device = findVirtualDevice(app);
|
|
3062
|
+
* device?.setVector("joystick", 0, 1);
|
|
3063
|
+
* ```
|
|
3064
|
+
*
|
|
3065
|
+
* @public
|
|
3066
|
+
*/
|
|
3067
|
+
export declare function findVirtualDevice(app: App): VirtualDeviceLike | null;
|
|
3068
|
+
//#endregion
|
|
3069
|
+
//#region src/widgets/virtual-joystick.d.ts
|
|
3070
|
+
/**
|
|
3071
|
+
* `VirtualJoystick` (`docs/architecture/13-ui.md` §3): an on-screen thumbstick that writes a
|
|
3072
|
+
* `<Virtual>/…` vector control, so a touch game binds exactly the same action to
|
|
3073
|
+
* `<Virtual>/joystick` that a desktop game binds to `<Keyboard>/wasd`.
|
|
3074
|
+
*
|
|
3075
|
+
* ## Replacing a template's own widget
|
|
3076
|
+
*
|
|
3077
|
+
* `templates/2d-topdown/src/touch-controls.ts` says it is *"meant to be **deleted** when
|
|
3078
|
+
* `@ignifx/ui` ships a `VirtualJoystick`… the bindings in `game.input.json`
|
|
3079
|
+
* (`<Virtual>/joystick`, `<Virtual>/interact`) do not change"*. This class writes the same two
|
|
3080
|
+
* controls with the same axis convention — screen `+Y` is down and the stick's `+Y` is up, so the
|
|
3081
|
+
* vertical axis is negated here and nowhere else — and the swap is that file's deletion plus:
|
|
3082
|
+
*
|
|
3083
|
+
* ```ts ignore-check
|
|
3084
|
+
* const stick = new VirtualJoystick(app, { control: "joystick" });
|
|
3085
|
+
* const jump = new VirtualButton(app, { control: "interact", label: "E" });
|
|
3086
|
+
* ```
|
|
3087
|
+
*
|
|
3088
|
+
* ## Multi-touch
|
|
3089
|
+
*
|
|
3090
|
+
* The stick claims exactly one `pointerId` and ignores every other pointer until that one is
|
|
3091
|
+
* released, so a thumb on the stick and a thumb on a button never fight. `pointerup` **and**
|
|
3092
|
+
* `pointercancel` both release it: a value written on `pointerdown` and never cleared would leave
|
|
3093
|
+
* the character walking for ever, which is the bug the template's own comment calls out.
|
|
3094
|
+
*/
|
|
3095
|
+
/**
|
|
3096
|
+
* What `new VirtualJoystick(app, options)` accepts.
|
|
3097
|
+
*
|
|
3098
|
+
* @public
|
|
3099
|
+
*/
|
|
3100
|
+
interface VirtualJoystickOptions {
|
|
3101
|
+
/** The `<Virtual>/…` control to write. Defaults to `"joystick"`. */
|
|
3102
|
+
readonly control?: string;
|
|
3103
|
+
/** The layer to mount into. Defaults to `"hud"`. */
|
|
3104
|
+
readonly layer?: string;
|
|
3105
|
+
/** How far the knob travels, in UI units, before the stick reads as fully deflected. */
|
|
3106
|
+
readonly radius?: number;
|
|
3107
|
+
/** Deflections shorter than this fraction of the radius read as zero. Defaults to `0.15`. */
|
|
3108
|
+
readonly deadZone?: number;
|
|
3109
|
+
/** Inline styles applied to the pad, for placement. */
|
|
3110
|
+
readonly style?: Readonly<Record<string, string>>;
|
|
3111
|
+
/** An accessible label for the pad. Defaults to the control name. */
|
|
3112
|
+
readonly ariaLabel?: string;
|
|
3113
|
+
}
|
|
3114
|
+
/**
|
|
3115
|
+
* Converts a raw deflection into the value written to the control.
|
|
3116
|
+
*
|
|
3117
|
+
* @param delta - The deflection along one axis, in UI units.
|
|
3118
|
+
* @param length - The deflection's length, in UI units.
|
|
3119
|
+
* @param radius - The radius at which the stick is fully deflected.
|
|
3120
|
+
* @param deadZone - The fraction of the radius below which the stick reads as centred.
|
|
3121
|
+
* @returns The axis value, in `-1` to `1`.
|
|
3122
|
+
*
|
|
3123
|
+
* @example
|
|
3124
|
+
* ```ts
|
|
3125
|
+
* stickAxis(0, 0, 44, 0.15); // 0
|
|
3126
|
+
* stickAxis(44, 44, 44, 0.15); // 1
|
|
3127
|
+
* ```
|
|
3128
|
+
*
|
|
3129
|
+
* @public
|
|
3130
|
+
*/
|
|
3131
|
+
export declare function stickAxis(delta: number, length: number, radius: number, deadZone: number): number;
|
|
3132
|
+
/**
|
|
3133
|
+
* An on-screen thumbstick.
|
|
3134
|
+
*
|
|
3135
|
+
* @example
|
|
3136
|
+
* ```ts
|
|
3137
|
+
* const stick = new VirtualJoystick(app, { control: "joystick" });
|
|
3138
|
+
* // later
|
|
3139
|
+
* stick.dispose();
|
|
3140
|
+
* ```
|
|
3141
|
+
*
|
|
3142
|
+
* @public
|
|
3143
|
+
*/
|
|
3144
|
+
export declare class VirtualJoystick {
|
|
3145
|
+
#private;
|
|
3146
|
+
/**
|
|
3147
|
+
* Builds the widget and mounts it.
|
|
3148
|
+
*
|
|
3149
|
+
* @param app - The running app; `app.ui` and `app.input.devices.virtual` are the parts used.
|
|
3150
|
+
* @param options - The control name, the layer, the geometry, and the placement styles.
|
|
3151
|
+
* @throws IgnifxError with code `IGX-1305` when `@ignifx/input` is not registered.
|
|
3152
|
+
*/
|
|
3153
|
+
constructor(app: App, options?: VirtualJoystickOptions);
|
|
3154
|
+
/**
|
|
3155
|
+
* The pad element, so a template can restyle or reposition it.
|
|
3156
|
+
*
|
|
3157
|
+
* @returns The element, or `null` when the app has no DOM overlay.
|
|
3158
|
+
*/
|
|
3159
|
+
get element(): HTMLDivElement | null;
|
|
3160
|
+
/**
|
|
3161
|
+
* The control this stick writes.
|
|
3162
|
+
*
|
|
3163
|
+
* @returns The name, as it appears after `<Virtual>/`.
|
|
3164
|
+
*/
|
|
3165
|
+
get control(): string;
|
|
3166
|
+
/**
|
|
3167
|
+
* Whether a pointer currently holds the stick.
|
|
3168
|
+
*
|
|
3169
|
+
* @returns `true` while the stick is being dragged.
|
|
3170
|
+
*/
|
|
3171
|
+
get isActive(): boolean;
|
|
3172
|
+
/** Removes the widget, unsubscribes, and centres the control. */
|
|
3173
|
+
dispose(): void;
|
|
3174
|
+
}
|
|
3175
|
+
//#endregion
|
|
3176
|
+
//#region src/world/anchor-math.d.ts
|
|
3177
|
+
/**
|
|
3178
|
+
* Where a `WorldAnchor`'s element goes, and whether it is shown
|
|
3179
|
+
* (`docs/architecture/13-ui.md` §2). Pure arithmetic, so every combination of
|
|
3180
|
+
* `hideWhenBehindCamera`, `clampToScreen` and `scaleWithDistance` is a node test with a fake
|
|
3181
|
+
* camera and no DOM.
|
|
3182
|
+
*
|
|
3183
|
+
* ## The two pixel spaces
|
|
3184
|
+
*
|
|
3185
|
+
* `Camera.worldToScreen` writes **render-target** pixels: it divides by
|
|
3186
|
+
* `RendererImpl.readTargetSize`, which is `canvas.width`/`canvas.height`
|
|
3187
|
+
* (`packages/core/src/lite/gpu/render-diagnostics-gpu.ts` 126-128). A DOM element lives in the
|
|
3188
|
+
* overlay's UI units. {@link UiPixelMapping}, built by the host from the current layout, is the
|
|
3189
|
+
* conversion, and it is applied here rather than in the system so the system does nothing but
|
|
3190
|
+
* loop.
|
|
3191
|
+
*
|
|
3192
|
+
* ## Behind the camera
|
|
3193
|
+
*
|
|
3194
|
+
* `worldToScreen` returns `false` and leaves a **mirrored** projection in `out` when the point is
|
|
3195
|
+
* behind the camera — its own documentation says the value "should be ignored". So a point behind
|
|
3196
|
+
* the camera is either hidden (`hideWhenBehindCamera`) or, when the anchor also clamps, reflected
|
|
3197
|
+
* about the viewport centre before being clamped, which pushes an off-screen marker to the correct
|
|
3198
|
+
* edge instead of the opposite one. With neither flag set it is hidden, because a mirrored
|
|
3199
|
+
* position is not a position.
|
|
3200
|
+
*/
|
|
3201
|
+
/**
|
|
3202
|
+
* Everything {@link computeAnchorPlacement} reads.
|
|
3203
|
+
*
|
|
3204
|
+
* @public
|
|
3205
|
+
*/
|
|
3206
|
+
interface AnchorInput {
|
|
3207
|
+
/** The projected x, in render-target pixels. */
|
|
3208
|
+
readonly screenX: number;
|
|
3209
|
+
/** The projected y, in render-target pixels. */
|
|
3210
|
+
readonly screenY: number;
|
|
3211
|
+
/** Whether the point is in front of the camera. */
|
|
3212
|
+
readonly inFront: boolean;
|
|
3213
|
+
/** How far the point is from the camera, in metres. */
|
|
3214
|
+
readonly distance: number;
|
|
3215
|
+
/** The overlay root's width, in UI units. */
|
|
3216
|
+
readonly viewWidth: number;
|
|
3217
|
+
/** The overlay root's height, in UI units. */
|
|
3218
|
+
readonly viewHeight: number;
|
|
3219
|
+
/** The render-target-pixel to UI-unit conversion. */
|
|
3220
|
+
readonly mapping: UiPixelMapping;
|
|
3221
|
+
/** Whether the element is hidden when the point is behind the camera. */
|
|
3222
|
+
readonly hideWhenBehindCamera: boolean;
|
|
3223
|
+
/** Whether the element is kept inside the overlay's bounds. */
|
|
3224
|
+
readonly clampToScreen: boolean;
|
|
3225
|
+
/** Whether the element shrinks with distance. */
|
|
3226
|
+
readonly scaleWithDistance: boolean;
|
|
3227
|
+
/** The distance at which {@link AnchorInput.scaleWithDistance} produces a scale of `1`. */
|
|
3228
|
+
readonly referenceDistance: number;
|
|
3229
|
+
/** The smallest scale distance scaling may produce. */
|
|
3230
|
+
readonly minScale: number;
|
|
3231
|
+
/** The largest scale distance scaling may produce. */
|
|
3232
|
+
readonly maxScale: number;
|
|
3233
|
+
}
|
|
3234
|
+
/**
|
|
3235
|
+
* Where the element goes, written in place so the per-frame path allocates nothing.
|
|
3236
|
+
*
|
|
3237
|
+
* @public
|
|
3238
|
+
*/
|
|
3239
|
+
interface AnchorPlacement {
|
|
3240
|
+
/** Whether the element is shown at all. */
|
|
3241
|
+
visible: boolean;
|
|
3242
|
+
/** The x, in UI units from the overlay root's left edge. */
|
|
3243
|
+
x: number;
|
|
3244
|
+
/** The y, in UI units from the overlay root's top edge. */
|
|
3245
|
+
y: number;
|
|
3246
|
+
/** The uniform scale to draw the element at. */
|
|
3247
|
+
scale: number;
|
|
3248
|
+
}
|
|
3249
|
+
/**
|
|
3250
|
+
* Computes where an anchored element goes this frame.
|
|
3251
|
+
*
|
|
3252
|
+
* @param input - The projection, the flags, and the conversion.
|
|
3253
|
+
* @param out - Receives the placement.
|
|
3254
|
+
* @returns `out`, for chaining.
|
|
3255
|
+
*
|
|
3256
|
+
* @example
|
|
3257
|
+
* ```ts
|
|
3258
|
+
* const out = createAnchorPlacement();
|
|
3259
|
+
* computeAnchorPlacement(
|
|
3260
|
+
* {
|
|
3261
|
+
* screenX: 400,
|
|
3262
|
+
* screenY: 300,
|
|
3263
|
+
* inFront: true,
|
|
3264
|
+
* distance: 10,
|
|
3265
|
+
* viewWidth: 800,
|
|
3266
|
+
* viewHeight: 600,
|
|
3267
|
+
* mapping: { scaleX: 1, originX: 0, scaleY: 1, originY: 0 },
|
|
3268
|
+
* hideWhenBehindCamera: true,
|
|
3269
|
+
* clampToScreen: false,
|
|
3270
|
+
* scaleWithDistance: false,
|
|
3271
|
+
* referenceDistance: 10,
|
|
3272
|
+
* minScale: 0.5,
|
|
3273
|
+
* maxScale: 2,
|
|
3274
|
+
* },
|
|
3275
|
+
* out,
|
|
3276
|
+
* );
|
|
3277
|
+
* out.x; // 400
|
|
3278
|
+
* ```
|
|
3279
|
+
*
|
|
3280
|
+
* @public
|
|
3281
|
+
*/
|
|
3282
|
+
export declare function computeAnchorPlacement(input: AnchorInput, out: AnchorPlacement): AnchorPlacement;
|
|
3283
|
+
//#endregion
|
|
3284
|
+
//#region src/world/ui-system.d.ts
|
|
3285
|
+
/**
|
|
3286
|
+
* The one system `@ignifx/ui` registers (`docs/architecture/01-lifecycle-and-time.md` §3,
|
|
3287
|
+
* `13-ui.md` §2: *"Updated in `PreRender` after camera sync, in batch, using
|
|
3288
|
+
* `Camera.worldToScreen`"*).
|
|
3289
|
+
*
|
|
3290
|
+
* ## Ordering
|
|
3291
|
+
*
|
|
3292
|
+
* `@ignifx/core`'s `RenderSyncSystem` runs at `PreRender` order **900**
|
|
3293
|
+
* (`packages/core/src/render/render-sync-system.ts` 63) and is what refreshes the render target's
|
|
3294
|
+
* size on every `Camera` and writes the frame's transforms onto the Lite cameras. Every projection
|
|
3295
|
+
* this system performs would be a frame stale, and would divide by last frame's viewport, if it ran
|
|
3296
|
+
* before that. {@link UI_SYNC_ORDER} is therefore **1100**: after core's sync, and inside the
|
|
3297
|
+
* `[1001, 9999]` band `RegisterSystemOptions` reserves for extensions
|
|
3298
|
+
* (`packages/core/src/app/types.ts` 649). Nothing else in the engine occupies it — physics
|
|
3299
|
+
* interpolation is at `-500`, 2D sync at `-450`, audio at `-400`.
|
|
3300
|
+
*
|
|
3301
|
+
* ## What it does
|
|
3302
|
+
*
|
|
3303
|
+
* One pass per component kind, in the order a frame needs them: create the text renderer if this is
|
|
3304
|
+
* the first frame, project every `WorldAnchor` and every `WorldText2D` once, then re-shape whatever
|
|
3305
|
+
* text changed. Projection uses the world's main camera; with no camera nothing is projected and
|
|
3306
|
+
* every anchored element is hidden, which is what a loading screen with no scene looks like.
|
|
3307
|
+
*/
|
|
3308
|
+
/**
|
|
3309
|
+
* The `PreRender` order the UI system runs at.
|
|
3310
|
+
*
|
|
3311
|
+
* @remarks
|
|
3312
|
+
* After `RENDER_SYNC_ORDER` (900), which is the frame's camera synchronisation, and inside the
|
|
3313
|
+
* extension band. See the module's own remarks.
|
|
3314
|
+
*
|
|
3315
|
+
* @public
|
|
3316
|
+
*/
|
|
3317
|
+
export declare const UI_SYNC_ORDER = 1100;
|
|
3318
|
+
/**
|
|
3319
|
+
* What the system is built with. Only `uiExtension` builds one, through `UiSystem`'s `@internal`
|
|
3320
|
+
* constructor.
|
|
3321
|
+
*
|
|
3322
|
+
* @internal
|
|
3323
|
+
*/
|
|
3324
|
+
interface UiSystemOptions {
|
|
3325
|
+
/** The app, for the render surface's size and the Lite scene. */
|
|
3326
|
+
readonly app: App;
|
|
3327
|
+
/** The overlay host, for the layout the anchors are placed in. */
|
|
3328
|
+
readonly host: UiHost;
|
|
3329
|
+
/** The text renderer's life. */
|
|
3330
|
+
readonly runtime: TextRuntime;
|
|
3331
|
+
/** The localization service `i18nKey` is resolved through. */
|
|
3332
|
+
readonly i18n: I18nService;
|
|
3333
|
+
}
|
|
3334
|
+
/**
|
|
3335
|
+
* Projects world anchors and re-shapes text once per frame.
|
|
3336
|
+
*
|
|
3337
|
+
* @public
|
|
3338
|
+
*/
|
|
3339
|
+
export declare class UiSystem implements System {
|
|
3340
|
+
#private;
|
|
3341
|
+
/** The name diagnostics and error reports use. */
|
|
3342
|
+
readonly name = "ignifx/ui-sync";
|
|
3343
|
+
/**
|
|
3344
|
+
* Builds the system. The extension does this; a game never constructs one.
|
|
3345
|
+
*
|
|
3346
|
+
* @param options - The app, the host, the text runtime, and the localization service.
|
|
3347
|
+
*
|
|
3348
|
+
* @internal
|
|
3349
|
+
*/
|
|
3350
|
+
constructor(options: UiSystemOptions);
|
|
3351
|
+
/**
|
|
3352
|
+
* Builds the overlay, now that the engine and its canvas exist.
|
|
3353
|
+
*
|
|
3354
|
+
* @remarks
|
|
3355
|
+
* This is the only hook that fires inside `createApp` **after** the Lite engine was created:
|
|
3356
|
+
* `register` runs before it, and `onStart` runs only when a game calls `app.start()`, which a
|
|
3357
|
+
* headless tool never does. `@ignifx/2d` uses the same hook for the same reason.
|
|
3358
|
+
*
|
|
3359
|
+
* @param _world - The new world, which the overlay does not need.
|
|
3360
|
+
*/
|
|
3361
|
+
onWorldCreated(_world: World): void;
|
|
3362
|
+
/**
|
|
3363
|
+
* Runs one frame's synchronisation.
|
|
3364
|
+
*
|
|
3365
|
+
* @param ctx - The world, clock, phase, and delta.
|
|
3366
|
+
*/
|
|
3367
|
+
update(ctx: SystemContext): void;
|
|
3368
|
+
}
|
|
3369
|
+
//#endregion
|
|
3370
|
+
//#region src/world/world-anchor.d.ts
|
|
3371
|
+
/**
|
|
3372
|
+
* `WorldAnchor` (`docs/architecture/13-ui.md` §2): *"keeps a DOM element positioned at the entity's
|
|
3373
|
+
* screen position (name tags, health bars, markers)"*.
|
|
3374
|
+
*
|
|
3375
|
+
* ## The element is the game's, not the component's
|
|
3376
|
+
*
|
|
3377
|
+
* A game creates the element — with its framework, its CSS, its accessibility attributes — mounts
|
|
3378
|
+
* it in whichever `app.ui.layer` it belongs to, and assigns it to {@link WorldAnchor.element}. The
|
|
3379
|
+
* component writes exactly three properties on it and nothing else: `position: absolute`,
|
|
3380
|
+
* `left`/`top` at the origin, and a `transform` carrying the translate and the scale. That keeps a
|
|
3381
|
+
* React tree's own rendering untouched — the anchor only ever writes inline style — and it means
|
|
3382
|
+
* an anchor with no element is simply inert.
|
|
3383
|
+
*
|
|
3384
|
+
* ## Cost
|
|
3385
|
+
*
|
|
3386
|
+
* The transform string is the one per-frame allocation and it is unavoidable: the DOM takes CSS
|
|
3387
|
+
* text. Everything else is compared first, so an anchor whose entity did not move and whose camera
|
|
3388
|
+
* did not move writes nothing at all (coding standards §7).
|
|
3389
|
+
*/
|
|
3390
|
+
/**
|
|
3391
|
+
* An entity-to-element anchor.
|
|
3392
|
+
*
|
|
3393
|
+
* @example
|
|
3394
|
+
* ```ts
|
|
3395
|
+
* const tag = document.createElement("div");
|
|
3396
|
+
* tag.textContent = "Boss";
|
|
3397
|
+
* app.ui.layer("hud").element?.append(tag);
|
|
3398
|
+
*
|
|
3399
|
+
* const anchor = enemy.addComponent(WorldAnchor);
|
|
3400
|
+
* anchor.element = tag;
|
|
3401
|
+
* anchor.offset = { x: 0, y: 2, z: 0 };
|
|
3402
|
+
* ```
|
|
3403
|
+
*
|
|
3404
|
+
* @public
|
|
3405
|
+
*/
|
|
3406
|
+
export declare class WorldAnchor extends Component implements ComponentHooks {
|
|
3407
|
+
#private;
|
|
3408
|
+
/** The registration id the serializer writes into scene files. */
|
|
3409
|
+
static typeId: string;
|
|
3410
|
+
/** One anchored element per entity. */
|
|
3411
|
+
static allowMultiple: boolean;
|
|
3412
|
+
/** The declarative fields (ADR-0004). */
|
|
3413
|
+
static schema: Schema;
|
|
3414
|
+
/** A world-space offset added to the entity's position before projecting, in metres. */
|
|
3415
|
+
offset: Vec3Like;
|
|
3416
|
+
/** Whether the element is hidden when the anchor point is behind the camera. */
|
|
3417
|
+
hideWhenBehindCamera: boolean;
|
|
3418
|
+
/** Whether the element is kept inside the overlay's bounds instead of being hidden off-screen. */
|
|
3419
|
+
clampToScreen: boolean;
|
|
3420
|
+
/** Whether the element shrinks with distance. */
|
|
3421
|
+
scaleWithDistance: boolean;
|
|
3422
|
+
/** The distance at which {@link WorldAnchor.scaleWithDistance} produces a scale of `1`, in metres. */
|
|
3423
|
+
referenceDistance: number;
|
|
3424
|
+
/** The smallest scale distance scaling may produce. */
|
|
3425
|
+
minScale: number;
|
|
3426
|
+
/** The largest scale distance scaling may produce. */
|
|
3427
|
+
maxScale: number;
|
|
3428
|
+
/**
|
|
3429
|
+
* The element to position. Not serialised — a DOM node cannot be — so a scene file carries the
|
|
3430
|
+
* flags and the game assigns the element in `awake`.
|
|
3431
|
+
*/
|
|
3432
|
+
element: HTMLElement | null;
|
|
3433
|
+
/** Builds an anchor with the schema's defaults. */
|
|
3434
|
+
constructor();
|
|
3435
|
+
/**
|
|
3436
|
+
* Where the element was placed on the last synchronised frame.
|
|
3437
|
+
*
|
|
3438
|
+
* @returns The placement; `visible` is `false` before the first sync.
|
|
3439
|
+
*/
|
|
3440
|
+
get placement(): Readonly<AnchorPlacement>;
|
|
3441
|
+
/** Hides the element when the component goes away, so an orphaned tag does not linger. */
|
|
3442
|
+
onDetach(): void;
|
|
3443
|
+
/**
|
|
3444
|
+
* Places the element for this frame.
|
|
3445
|
+
*
|
|
3446
|
+
* @param screenX - The anchor point's projected x, in render-target pixels.
|
|
3447
|
+
* @param screenY - The anchor point's projected y, in render-target pixels.
|
|
3448
|
+
* @param inFront - Whether the point is in front of the camera.
|
|
3449
|
+
* @param distance - How far the point is from the camera, in metres.
|
|
3450
|
+
* @param viewWidth - The overlay root's width, in UI units.
|
|
3451
|
+
* @param viewHeight - The overlay root's height, in UI units.
|
|
3452
|
+
* @param mapping - The render-target-pixel to UI-unit conversion.
|
|
3453
|
+
*
|
|
3454
|
+
* @internal
|
|
3455
|
+
*/
|
|
3456
|
+
place(screenX: number, screenY: number, inFront: boolean, distance: number, viewWidth: number, viewHeight: number, mapping: UiPixelMapping): void;
|
|
3457
|
+
}
|
|
3458
|
+
//#endregion
|
|
3459
|
+
export type { AnchorInput, AnchorPlacement, ArgumentNode, DialogButton, DialogOptions, HudAnchor, HudPlacement, HudPlacementInput, LiteFont, LiteTextData, LiteTextLayer, LiteTextRenderable, LiteTextRenderer, LoadingScreenOptions, LocaleDocument, MenuActionRow, MenuBindingRow, MenuButtonSource, MenuChoiceRow, MenuChoiceValues, MenuHeadingRow, MenuLabel, MenuNavigation, MenuOptions, MenuRow, MenuRowBase, MenuSeparatorRow, MenuSliderRow, MenuStackOptions, MenuText, MenuToggleRow, MenuVectorSource, MessageNode, MessageParams, MessagePattern, PluralNode, PluralSelector, TextAlignment, TextMetrics, TextNode, ToastOptions, UiDomTarget, UiErrorOptions, UiLayerOptions, UiLayout, UiOptions, UiPixelMapping, UiScalingMode, UiSettings, UiSurfaceMetrics, VirtualButtonOptions, VirtualDeviceLike, VirtualJoystickOptions };
|
|
3460
|
+
//# sourceMappingURL=index.d.ts.map
|