@ignifx/ui 0.0.0 → 0.1.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/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ignifx/ui",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.1.0",
|
|
4
4
|
"description": "ignifx UI: DOM overlay host, focus routing, world and HUD text.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"ignifx",
|
|
@@ -9,6 +9,11 @@
|
|
|
9
9
|
"homepage": "https://ignifx.com",
|
|
10
10
|
"license": "Apache-2.0",
|
|
11
11
|
"author": "Astrum Forge Studios",
|
|
12
|
+
"repository": {
|
|
13
|
+
"type": "git",
|
|
14
|
+
"url": "git+https://github.com/astrum-forge/ignifx.git",
|
|
15
|
+
"directory": "packages/ui"
|
|
16
|
+
},
|
|
12
17
|
"files": [
|
|
13
18
|
"dist",
|
|
14
19
|
"skills"
|
|
@@ -24,39 +29,56 @@
|
|
|
24
29
|
},
|
|
25
30
|
"publishConfig": {
|
|
26
31
|
"access": "public",
|
|
27
|
-
"provenance":
|
|
28
|
-
},
|
|
29
|
-
"scripts": {
|
|
30
|
-
"build": "tsdown",
|
|
31
|
-
"typecheck": "tsc --build tsconfig.json tsconfig.test.json",
|
|
32
|
-
"test": "vitest run --project node --root ../.. packages/ui",
|
|
33
|
-
"api-report": "api-extractor run --verbose",
|
|
34
|
-
"docs:api": "typedoc",
|
|
35
|
-
"api-report:update": "api-extractor run --local --verbose",
|
|
36
|
-
"pack-check": "publint && attw --pack . --profile esm-only"
|
|
32
|
+
"provenance": false
|
|
37
33
|
},
|
|
38
34
|
"devDependencies": {
|
|
39
|
-
"@arethetypeswrong/cli": "
|
|
40
|
-
"@
|
|
41
|
-
"@microsoft/api-extractor": "
|
|
42
|
-
"@types/webxr": "
|
|
43
|
-
"@webgpu/types": "
|
|
44
|
-
"publint": "
|
|
45
|
-
"tsdown": "
|
|
46
|
-
"typedoc": "
|
|
47
|
-
"typedoc-plugin-markdown": "
|
|
48
|
-
"typescript-native": "
|
|
49
|
-
"vitest": "
|
|
35
|
+
"@arethetypeswrong/cli": "^0.18.5",
|
|
36
|
+
"@babylonjs/lite": "1.27.0",
|
|
37
|
+
"@microsoft/api-extractor": "^7.59.0",
|
|
38
|
+
"@types/webxr": "^0.5.0",
|
|
39
|
+
"@webgpu/types": "^0.1.72",
|
|
40
|
+
"publint": "^0.3.24",
|
|
41
|
+
"tsdown": "^0.23.0",
|
|
42
|
+
"typedoc": "^0.28.20",
|
|
43
|
+
"typedoc-plugin-markdown": "^4.13.0",
|
|
44
|
+
"typescript-native": "npm:typescript@7.0.2",
|
|
45
|
+
"vitest": "^5.0.0",
|
|
46
|
+
"@ignifx/core": "0.1.0",
|
|
47
|
+
"@ignifx/input": "0.1.0"
|
|
50
48
|
},
|
|
51
49
|
"peerDependencies": {
|
|
52
|
-
"@
|
|
50
|
+
"@babylonjs/lite": "1.27.0",
|
|
51
|
+
"@ignifx/core": "0.1.0",
|
|
52
|
+
"@ignifx/input": "0.1.0"
|
|
53
|
+
},
|
|
54
|
+
"peerDependenciesMeta": {
|
|
55
|
+
"@ignifx/input": {
|
|
56
|
+
"optional": true
|
|
57
|
+
}
|
|
53
58
|
},
|
|
54
59
|
"ignifx": {
|
|
55
60
|
"extension": true,
|
|
56
61
|
"engine": ">=0.0.0 <1.0.0",
|
|
57
62
|
"requires": [],
|
|
58
|
-
"optional": [
|
|
59
|
-
|
|
63
|
+
"optional": [
|
|
64
|
+
"@ignifx/input"
|
|
65
|
+
],
|
|
66
|
+
"capabilities": [
|
|
67
|
+
"components",
|
|
68
|
+
"systems",
|
|
69
|
+
"services",
|
|
70
|
+
"settings",
|
|
71
|
+
"assets"
|
|
72
|
+
],
|
|
60
73
|
"skill": "./skills/ui/SKILL.md"
|
|
74
|
+
},
|
|
75
|
+
"scripts": {
|
|
76
|
+
"build": "tsdown",
|
|
77
|
+
"typecheck": "tsc --build tsconfig.json tsconfig.test.json",
|
|
78
|
+
"test": "vitest run --project node --root ../.. packages/ui",
|
|
79
|
+
"api-report": "api-extractor run --verbose",
|
|
80
|
+
"docs:api": "typedoc",
|
|
81
|
+
"api-report:update": "api-extractor run --local --verbose",
|
|
82
|
+
"pack-check": "publint && attw --pack . --profile esm-only"
|
|
61
83
|
}
|
|
62
|
-
}
|
|
84
|
+
}
|
package/skills/ui/SKILL.md
CHANGED
|
@@ -1,46 +1,349 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: ui
|
|
3
|
-
description: Builds game UI in ignifx with @ignifx/ui: the DOM overlay host and layers, scaling modes, input focus routing, world-space anchors, world and HUD text, virtual joysticks and buttons for touch, dialogs, toasts, loading screens, and localization. Use when adding or editing menus, HUDs, on-screen text, touch controls, or overlay UI in an ignifx project, or when the user mentions @ignifx/ui, HudText, WorldAnchor, or
|
|
3
|
+
description: Builds game UI in ignifx with @ignifx/ui: the DOM overlay host and layers, scaling modes, input focus routing, world-space anchors, world and HUD text on Babylon Lite's text renderer, menus and menu stacks, virtual joysticks and buttons for touch, dialogs, toasts, loading screens, and localization. Use when adding or editing menus, title/pause/settings screens, HUDs, on-screen text, touch controls, or overlay UI in an ignifx project, or when the user mentions @ignifx/ui, Menu, MenuStack, HudText, WorldAnchor, VirtualJoystick, or app.i18n.
|
|
4
4
|
license: Apache-2.0
|
|
5
5
|
metadata:
|
|
6
|
-
ignifx-version: "0.
|
|
6
|
+
ignifx-version: "0.1.0"
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
# @ignifx/ui
|
|
10
10
|
|
|
11
|
-
> **Scaffold notice.** ignifx is in the planning phase and `@ignifx/ui` is an empty package. Every section below is filled by Phase 8 of `docs/plan/engineering-plan.md`; until then this file makes no API claims (`CONSTITUTION.md` Article V).
|
|
12
|
-
|
|
13
11
|
## What this is / when to use
|
|
14
12
|
|
|
15
|
-
|
|
13
|
+
**Game UI in ignifx is HTML.** `@ignifx/ui` puts one absolutely positioned `<div>` over the canvas
|
|
14
|
+
and lets a game mount React, Svelte, Vue or plain DOM into named layers inside it. That is what
|
|
15
|
+
gives every game accessibility, real fonts, real layout, and any framework the team already knows.
|
|
16
|
+
|
|
17
|
+
Use the DOM for menus, HUDs, dialogs and touch controls. Use the **text components** only for text
|
|
18
|
+
that has to be drawn by the GPU: text that belongs in the world (`WorldText`), text that follows an
|
|
19
|
+
entity (`WorldText2D`), and pixel-exact HUD text that has to show up in `captureScreenshot()`
|
|
20
|
+
(`HudText`).
|
|
21
|
+
|
|
22
|
+
Everything registers headlessly. With no canvas, `app.ui.root` is `null`, every DOM member is a
|
|
23
|
+
documented no-op, and the components keep their state — so the same script runs in a Node test.
|
|
16
24
|
|
|
17
25
|
## Environment
|
|
18
26
|
|
|
19
|
-
Engine
|
|
27
|
+
- Engine: ignifx `0.0.0-unreleased`; this package targets `@ignifx/core` `>=0.0.0 <1.0.0`.
|
|
28
|
+
- WebGPU only, browser and Electron. Babylon Lite `1.27.0` is a peer dependency.
|
|
29
|
+
- `@ignifx/input` is an **optional** peer: only `VirtualJoystick` and `VirtualButton` need it.
|
|
30
|
+
- Register it like any extension; nothing happens at import time.
|
|
31
|
+
|
|
32
|
+
```ts
|
|
33
|
+
import { createApp } from "ignifx";
|
|
34
|
+
import { ui } from "@ignifx/ui";
|
|
35
|
+
|
|
36
|
+
const canvas = document.querySelector("canvas");
|
|
37
|
+
if (canvas instanceof HTMLCanvasElement) {
|
|
38
|
+
const app = await createApp({
|
|
39
|
+
canvas,
|
|
40
|
+
extensions: [ui({ scaling: "fit", referenceResolution: [640, 360] })],
|
|
41
|
+
});
|
|
42
|
+
await app.start();
|
|
43
|
+
}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
`ignifx.config.ts` carries the same settings under `ui`:
|
|
47
|
+
|
|
48
|
+
| Setting | Default | Meaning |
|
|
49
|
+
| --------------------- | ---------------------------- | --------------------------------------- |
|
|
50
|
+
| `scaling` | `"css"` | `"css"`, `"fit"` or `"dpi"` — see below |
|
|
51
|
+
| `referenceResolution` | `[1920, 1080]` | The `[w, h]` `"fit"` scales to |
|
|
52
|
+
| `layers` | `["hud", "menu", "overlay"]` | Created up front, back to front |
|
|
53
|
+
| `visible` | `true` | Whether the overlay is shown |
|
|
54
|
+
|
|
55
|
+
`ui()` also takes `strings` (a `.i18n.json` address to load at start-up) and `locale`.
|
|
20
56
|
|
|
21
57
|
## Mental model
|
|
22
58
|
|
|
23
|
-
|
|
59
|
+
```
|
|
60
|
+
app.ui (UiHost)
|
|
61
|
+
├─ root the <div> over the canvas; pointer-events: none
|
|
62
|
+
├─ layer(name) one <div> per layer, z-index 10, 20, 30 …
|
|
63
|
+
├─ scaling "css" | "fit" | "dpi"; layout · pixelMapping · onLayoutChanged
|
|
64
|
+
├─ visible · pointerOverUi · keyboardHasFocus · refresh()
|
|
65
|
+
app.i18n (I18nService)
|
|
66
|
+
└─ load(handle) · t(key, params) · locale · onLocaleChanged · availableLocales
|
|
67
|
+
|
|
68
|
+
components WorldAnchor · HudText · WorldText2D · WorldText
|
|
69
|
+
helpers Menu · MenuStack · Dialog · Toast · LoadingScreen · VirtualJoystick · VirtualButton
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
**One system, `PreRender` order 1100** — after core's camera sync at 900, because every projection
|
|
73
|
+
needs this frame's camera. It projects the anchors, re-shapes whatever text changed, and writes the
|
|
74
|
+
DOM.
|
|
75
|
+
|
|
76
|
+
**Three coordinate systems.** A canvas has a CSS size and a backing-store size. `Camera.worldToScreen`,
|
|
77
|
+
`HudText`, and `captureScreenshot()` all work in **backing-store** pixels; a DOM element is placed in
|
|
78
|
+
**UI units**. The scaling mode decides what a UI unit is:
|
|
79
|
+
|
|
80
|
+
| Mode | One UI unit is | Use it for |
|
|
81
|
+
| ------- | ------------------- | ------------------------------------------------------ |
|
|
82
|
+
| `"css"` | one CSS pixel | responsive HTML menus (the browser default) |
|
|
83
|
+
| `"fit"` | one reference pixel | a HUD authored once at a fixed resolution, letterboxed |
|
|
84
|
+
| `"dpi"` | one backing pixel | a pixel HUD that must line up with a screenshot |
|
|
85
|
+
|
|
86
|
+
`app.ui.pixelMapping` converts between them, and `WorldAnchor` already does it for you.
|
|
24
87
|
|
|
25
88
|
## First app
|
|
26
89
|
|
|
27
|
-
|
|
90
|
+
```ts
|
|
91
|
+
import { createApp, FontAsset } from "ignifx";
|
|
92
|
+
import { HudText, ui, WorldAnchor } from "@ignifx/ui";
|
|
93
|
+
|
|
94
|
+
const canvas = document.querySelector("canvas");
|
|
95
|
+
if (canvas instanceof HTMLCanvasElement) {
|
|
96
|
+
const app = await createApp({ canvas, extensions: [ui()] });
|
|
97
|
+
|
|
98
|
+
// A name tag that follows an entity. (A plain DOM label goes in
|
|
99
|
+
// `app.ui.layer("hud").element` the same way, positioned with CSS.)
|
|
100
|
+
const tag = document.createElement("div");
|
|
101
|
+
tag.textContent = "Boss";
|
|
102
|
+
app.ui.layer("hud").element?.append(tag);
|
|
103
|
+
const boss = app.world.createEntity("boss");
|
|
104
|
+
const anchor = boss.addComponent(WorldAnchor);
|
|
105
|
+
anchor.element = tag;
|
|
106
|
+
anchor.offset = { x: 0, y: 2, z: 0 };
|
|
107
|
+
|
|
108
|
+
// GPU text, for a pixel-exact readout.
|
|
109
|
+
const font = app.assets.load<FontAsset>("ui/Inter-Regular.ttf");
|
|
110
|
+
const readout = app.world.createEntity("readout").addComponent(HudText);
|
|
111
|
+
readout.font = font;
|
|
112
|
+
readout.text = "60 fps";
|
|
113
|
+
readout.anchor = "topRight";
|
|
114
|
+
readout.position = { x: -16, y: 16 };
|
|
115
|
+
|
|
116
|
+
await app.start();
|
|
117
|
+
}
|
|
118
|
+
```
|
|
28
119
|
|
|
29
120
|
## Core APIs
|
|
30
121
|
|
|
31
|
-
|
|
122
|
+
**`app.ui`** — `root`, `isActive`, `layer(name, { zIndex, visible })`, `layers`, `scaling`,
|
|
123
|
+
`referenceResolution`, `visible`, `layout`, `pixelMapping`, `pointerOverUi`, `keyboardHasFocus`,
|
|
124
|
+
`onLayoutChanged`, `refresh()`.
|
|
125
|
+
|
|
126
|
+
**`UiLayer`** — `name`, `element`, `zIndex`, `visible`, `clear()`.
|
|
127
|
+
|
|
128
|
+
**`WorldAnchor`** — `element` (assigned in code, never serialised), `offset`,
|
|
129
|
+
`hideWhenBehindCamera`, `clampToScreen`, `scaleWithDistance`, `referenceDistance`, `minScale`,
|
|
130
|
+
`maxScale`, `placement`.
|
|
131
|
+
|
|
132
|
+
**`HudText`** — the shared text fields plus `anchor` (one of nine), `position` (backing pixels from
|
|
133
|
+
that anchor), `order`, `metrics`.
|
|
134
|
+
|
|
135
|
+
**`WorldText2D`** — the shared fields plus `offset` (world), `screenOffset` (pixels), `pivot`,
|
|
136
|
+
`hideWhenBehindCamera`, `order`.
|
|
137
|
+
|
|
138
|
+
**`WorldText`** — the shared fields plus `offset`, `pixelsPerUnit` (default 100), `billboard`,
|
|
139
|
+
`alwaysOnTop`.
|
|
140
|
+
|
|
141
|
+
Shared text fields: `font` (a `FontAsset` handle), `text`, `i18nKey`, `fontSize`, `color`, `align`,
|
|
142
|
+
`maxWidth`, `lineHeight`, `opacity`.
|
|
143
|
+
|
|
144
|
+
**`Menu`** — `new Menu(app.ui, { id, title, subtitle, layer, rows, visible, cancelable, keyboard,
|
|
145
|
+
wrap, text })`, then `setRows`, `refresh()`, `show()`/`hide()`, `moveSelection(±1)`,
|
|
146
|
+
`adjustSelection(±1)`, `activateSelection()`, `select(id)`, `cancel()`, `dispose()`, plus `element`,
|
|
147
|
+
`rows`, `selected`, `selectedIndex`, `isVisible`, `cancelable`, `keyboardEnabled`, and the signals
|
|
148
|
+
`onSelectionChanged`, `onActivated`, `onBack`.
|
|
149
|
+
|
|
150
|
+
| Row `kind` | What it declares, on top of `id`, `label` and `enabled?` |
|
|
151
|
+
| ------------- | ------------------------------------------------------------- |
|
|
152
|
+
| `"action"` | `activate?()`, and an optional right-hand `value` |
|
|
153
|
+
| `"toggle"` | `get`/`set` a boolean; drawn with the menu's `text.on`/`.off` |
|
|
154
|
+
| `"slider"` | `min`/`max`/`step` plus `get`/`set`, and an optional `format` |
|
|
155
|
+
| `"choice"` | `values` plus `get`/`set` a string, and an optional `format` |
|
|
156
|
+
| `"binding"` | `path()` and `rebind?()`, and an optional `listening()` |
|
|
157
|
+
| `"heading"` | a label that groups the rows under it; never selected |
|
|
158
|
+
| `"separator"` | a rule; never selected |
|
|
159
|
+
|
|
160
|
+
`label` (and `title`, `subtitle`, `text.*`) is a string **or** a function, re-read on every
|
|
161
|
+
`refresh()` — which is what makes a menu localizable.
|
|
162
|
+
|
|
163
|
+
**`MenuStack`** — `new MenuStack({ navigation, repeatDelay, repeatInterval, threshold })`, then
|
|
164
|
+
`push(menu)`, `pop()`, `closeAll()`, `refresh()`, `update(unscaledDelta)`, plus `top`, `bottom`,
|
|
165
|
+
`menus`, `depth`, `isOpen`, `suspended`, and `onChanged`/`onSelectionChanged`/`onActivated`.
|
|
166
|
+
`navigation` is `{ move, submit, back }` — three objects shaped like `@ignifx/input` actions, which
|
|
167
|
+
is how the widget reaches a gamepad without importing the package.
|
|
168
|
+
|
|
169
|
+
**`app.i18n`** — `load(handleOrAsset)`, `t(key, params)`, `has(key)`, `locale`, `fallbackLocale`,
|
|
170
|
+
`availableLocales`, `onLocaleChanged`.
|
|
171
|
+
|
|
172
|
+
Full signatures: `skills/ignifx/references/api/ui.md`.
|
|
32
173
|
|
|
33
174
|
## Recipes
|
|
34
175
|
|
|
35
|
-
|
|
176
|
+
### A pause menu, and a loading screen
|
|
177
|
+
|
|
178
|
+
```ts
|
|
179
|
+
import { createApp } from "ignifx";
|
|
180
|
+
import { LoadingScreen, Menu, MenuStack, ui } from "@ignifx/ui";
|
|
181
|
+
|
|
182
|
+
const canvas = document.querySelector("canvas");
|
|
183
|
+
if (canvas instanceof HTMLCanvasElement) {
|
|
184
|
+
const app = await createApp({ canvas, extensions: [ui()] });
|
|
185
|
+
|
|
186
|
+
const loading = new LoadingScreen(app.ui, { label: "Loading…" });
|
|
187
|
+
loading.bindTo(app.assets);
|
|
188
|
+
await app.assets.preloadGroup("boot").promise;
|
|
189
|
+
loading.hide();
|
|
190
|
+
|
|
191
|
+
const state = { music: 0.8, shadows: true };
|
|
192
|
+
const stack = new MenuStack();
|
|
193
|
+
const pause = new Menu(app.ui, {
|
|
194
|
+
id: "pause",
|
|
195
|
+
title: "Paused",
|
|
196
|
+
text: { on: "On", off: "Off" },
|
|
197
|
+
rows: [
|
|
198
|
+
{ kind: "action", id: "resume", label: "Resume", activate: stack.closeAll.bind(stack) },
|
|
199
|
+
{ kind: "heading", id: "audio", label: "Audio" },
|
|
200
|
+
// prettier-ignore
|
|
201
|
+
{ kind: "slider", id: "music", label: "Music", min: 0, max: 1, step: 0.05,
|
|
202
|
+
get: (): number => state.music, set: (v: number): void => void (state.music = v),
|
|
203
|
+
format: (v: number): string => `${String(Math.round(v * 100))}%` },
|
|
204
|
+
// prettier-ignore
|
|
205
|
+
{ kind: "toggle", id: "shadows", label: "Shadows",
|
|
206
|
+
get: (): boolean => state.shadows, set: (v: boolean): void => void (state.shadows = v) },
|
|
207
|
+
],
|
|
208
|
+
});
|
|
209
|
+
// The stack owns pausing: any screen up stops the game, and the last one closing starts it again.
|
|
210
|
+
stack.onChanged.connect((top: Menu | null): void => {
|
|
211
|
+
if (top === null) {
|
|
212
|
+
app.resume();
|
|
213
|
+
} else {
|
|
214
|
+
app.pause();
|
|
215
|
+
}
|
|
216
|
+
});
|
|
217
|
+
|
|
218
|
+
stack.push(pause); // …from the game's own input handling
|
|
219
|
+
await app.start();
|
|
220
|
+
}
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
`stack.push(other)` opens a screen over this one and `pop()` (or Escape, or the pad's east button)
|
|
224
|
+
comes back; `menu.cancelable = false` is what stops Escape unwinding past a title screen.
|
|
225
|
+
|
|
226
|
+
With no `navigation` source a menu reads the keyboard itself — Up/Down, Left/Right, Enter, Escape —
|
|
227
|
+
because the list takes DOM focus on `show()`. Give the stack one to add the gamepad, and pump it
|
|
228
|
+
from a script that declares `static updateWhenPaused = true`:
|
|
229
|
+
|
|
230
|
+
```ts ignore-check
|
|
231
|
+
const map = app.input.actions.maps.get("UI") ?? null;
|
|
232
|
+
const stack = new MenuStack({
|
|
233
|
+
navigation: {
|
|
234
|
+
move: map?.actions.get("menuMove") ?? null,
|
|
235
|
+
submit: map?.actions.get("menuSubmit") ?? null,
|
|
236
|
+
back: map?.actions.get("menuBack") ?? null,
|
|
237
|
+
},
|
|
238
|
+
});
|
|
239
|
+
stack.update(app.time.unscaledDeltaTime); // in the script's update
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
### Touch controls
|
|
243
|
+
|
|
244
|
+
```ts
|
|
245
|
+
import { createApp } from "ignifx";
|
|
246
|
+
import { input } from "@ignifx/input";
|
|
247
|
+
import { ui, VirtualButton, VirtualJoystick } from "@ignifx/ui";
|
|
248
|
+
|
|
249
|
+
const canvas = document.querySelector("canvas");
|
|
250
|
+
if (canvas instanceof HTMLCanvasElement) {
|
|
251
|
+
const app = await createApp({ canvas, extensions: [input(), ui()] });
|
|
252
|
+
if (navigator.maxTouchPoints > 0) {
|
|
253
|
+
const stick = new VirtualJoystick(app, { control: "joystick", style: { left: "2rem", bottom: "2rem" } });
|
|
254
|
+
const jump = new VirtualButton(app, { control: "jump", label: "A", style: { right: "2rem", bottom: "2rem" } });
|
|
255
|
+
void stick;
|
|
256
|
+
void jump;
|
|
257
|
+
}
|
|
258
|
+
await app.start();
|
|
259
|
+
}
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
Bind `<Virtual>/joystick` and `<Virtual>/jump` in the game's `.input.json` exactly as any hardware
|
|
263
|
+
path; nothing else changes.
|
|
264
|
+
|
|
265
|
+
### Localized text
|
|
266
|
+
|
|
267
|
+
```ts
|
|
268
|
+
import { createApp } from "ignifx";
|
|
269
|
+
import { LocaleAsset, ui } from "@ignifx/ui";
|
|
270
|
+
|
|
271
|
+
const app = await createApp({ headless: true, extensions: [ui()] });
|
|
272
|
+
const strings = app.assets.load<LocaleAsset>("ui/strings.i18n.json");
|
|
273
|
+
await app.i18n.load(strings);
|
|
274
|
+
|
|
275
|
+
app.i18n.t("hud.score", { score: 42 }); // "Score: 42"
|
|
276
|
+
app.i18n.t("hud.lives", { count: 1 }); // "1 life"
|
|
277
|
+
app.i18n.t("hud.lives", { count: 3 }); // "3 lives"
|
|
278
|
+
|
|
279
|
+
app.i18n.locale = "fr";
|
|
280
|
+
app.i18n.t("hud.lives", { count: 3 }); // "3 vies"
|
|
281
|
+
app.dispose();
|
|
282
|
+
```
|
|
283
|
+
|
|
284
|
+
A `HudText`, `WorldText` or `WorldText2D` with an `i18nKey` re-shapes itself when the locale
|
|
285
|
+
changes; `i18nKey` wins over `text`.
|
|
36
286
|
|
|
37
287
|
## File formats
|
|
38
288
|
|
|
39
|
-
|
|
289
|
+
`ignifx.i18n` (`.i18n.json`, asset type `i18n`) — one document, every locale:
|
|
290
|
+
|
|
291
|
+
```json
|
|
292
|
+
{
|
|
293
|
+
"format": "ignifx.i18n",
|
|
294
|
+
"formatVersion": 1,
|
|
295
|
+
"defaultLocale": "en",
|
|
296
|
+
"locales": {
|
|
297
|
+
"en": { "hud.lives": "{count, plural, =0 {No lives} one {# life} other {# lives}}" },
|
|
298
|
+
"fr": { "hud.lives": "{count, plural, =0 {Aucune vie} one {# vie} other {# vies}}" }
|
|
299
|
+
}
|
|
300
|
+
}
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
Supported: `{name}` interpolation, `{n, plural, …}` with `=0`-style exact matches, the CLDR
|
|
304
|
+
categories for the active locale, and `#` for the number. Not supported: `select`, number and date
|
|
305
|
+
skeletons, and ICU's apostrophe quoting — braces are structural, so a literal brace arrives as a
|
|
306
|
+
parameter. Field reference: `skills/ignifx/references/formats/ignifx.i18n.md`.
|
|
40
307
|
|
|
41
308
|
## Gotchas
|
|
42
309
|
|
|
43
|
-
|
|
310
|
+
- **A click on UI never reaches gameplay, but a drag does.** `@ignifx/input` reads `pointerdown`
|
|
311
|
+
from the _canvas_, and the overlay is the canvas's sibling — so a press on a
|
|
312
|
+
`pointer-events: auto` element is never queued. It reads `pointermove`/`pointerup` from the
|
|
313
|
+
_window_, so a drag that started on a slider still moves `<Pointer>/delta`. Check
|
|
314
|
+
`app.ui.pointerOverUi` in a camera script.
|
|
315
|
+
- **Only text fields take the keyboard.** `app.input.uiHasFocus` is set for `<input>` (except the
|
|
316
|
+
button- and slider-like types), `<textarea>`, `<select>` and `contenteditable`. A focused
|
|
317
|
+
`<button>` deliberately does not stop gameplay. Override with `data-ignifx-focus="capture"` or
|
|
318
|
+
`"ignore"`.
|
|
319
|
+
- **`HudText.position` is in render-target pixels, not CSS pixels.** That is the point: it is the
|
|
320
|
+
same space `captureScreenshot()` reads back. A DOM label in `app.ui.layer("hud")` is the right
|
|
321
|
+
tool when you want CSS pixels.
|
|
322
|
+
- **`WorldText` has to exist before `app.start()`.** Babylon Lite drains a deferred scene renderable
|
|
323
|
+
exactly once, when the scene is registered, and offers no way to drain a later one; a sign that
|
|
324
|
+
first gets its text mid-game logs `IGX-1308` and does not draw. Use `WorldText2D`, which owns a
|
|
325
|
+
text layer and can be added at any time.
|
|
326
|
+
- **`align` aligns lines against each other, not against `maxWidth`.** To centre a block on screen,
|
|
327
|
+
use `HudText.anchor` (or read `metrics` and do the arithmetic).
|
|
328
|
+
- **Changing `fontSize`, `maxWidth`, `align`, `lineHeight` or `font` re-shapes from scratch**;
|
|
329
|
+
changing `text` or `color` does not. A per-frame counter is cheap; a per-frame font size is not.
|
|
330
|
+
- **`WorldAnchor.element` is not serialised.** A scene file carries the flags; the game assigns the
|
|
331
|
+
element in `awake`.
|
|
332
|
+
- **A `Toast` runs on the game clock, and nothing advances it for you.** Call `toast.advance(dt)`
|
|
333
|
+
from a script's `update`. A message shown from a pause menu only expires if that script declares
|
|
334
|
+
`static updateWhenPaused = true` and passes `app.time.unscaledDeltaTime` — `app.pause()` stops
|
|
335
|
+
`update` for every other script.
|
|
336
|
+
- **A `Dialog` is always above the other roots of its layer.** The stylesheet gives it
|
|
337
|
+
`z-index: 1000` (`UI_DIALOG_Z_INDEX`, overridable with `DialogOptions.zIndex`), because siblings
|
|
338
|
+
with no `z-index` paint in DOM order and a modal built before a `Menu` would otherwise sit under
|
|
339
|
+
it with its backdrop swallowing every click. Re-use one dialog and call `setTitle`, `setMessage`
|
|
340
|
+
and `setButtons` rather than building one per question.
|
|
341
|
+
- **A menu owns its selection; the browser owns focus only for the list.** Rows are `tabindex="-1"`
|
|
342
|
+
and the list carries `aria-activedescendant`, because a gamepad raises no DOM focus events. If the
|
|
343
|
+
game also binds arrows to a `menuMove` action, drive the menus through a `MenuStack` with a
|
|
344
|
+
`navigation` source — it turns each pushed menu's own key handling off, and back on when it pops.
|
|
345
|
+
- **Two apps in one document share one stylesheet and get one overlay each.** The root is mounted
|
|
346
|
+
as the canvas's next sibling, so put the canvas in a positioned wrapper.
|
|
44
347
|
|
|
45
348
|
## Deprecated (current window)
|
|
46
349
|
|
|
@@ -48,4 +351,5 @@ None (pre-1.0: no deprecation window; breaking changes are listed in the changel
|
|
|
48
351
|
|
|
49
352
|
## Where to look next
|
|
50
353
|
|
|
51
|
-
`skills/ignifx/SKILL.md` for the engine entry skill · `docs/architecture
|
|
354
|
+
`skills/ignifx/SKILL.md` for the engine entry skill · `docs/architecture/13-ui.md` for design
|
|
355
|
+
rationale · `skills/ignifx/references/api/ui.md` for full signatures.
|