@ignifx/2d 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/dist/index.d.ts CHANGED
@@ -1,169 +1,235 @@
1
- import { App, AssetHandle, AssetLoader, ColorLike, Component, ComponentHooks, Entity, ErrorContext, Extension, IgnifxError, JsonSchemaObject, MutableVec2, Schema, SchemaDescription, Script, Signal, System, SystemContext, Vec2Like, Vec4Like, World } from "@ignifx/core";
2
- import { Bounds2D, Sprite2DHandle, Sprite2DLayer, Sprite2DProps, Sprite2DView, SpriteAtlas, SpriteBlendMode, SpriteFrame, SpritePickInfo, SpriteRenderer as SpriteRenderer$1, SpriteSampling, Texture2D } from "@babylonjs/lite";
3
- //#region src/camera/camera-2d.d.ts
1
+ import { App, AssetHandle, AssetLoader, ColorLike, Component, ComponentHooks, Entity, ErrorContext, Extension, IgnifxError, JsonSchemaObject, MutableVec2, SceneInstance, Schema, SchemaDescription, Script, Signal, System, SystemContext, Vec2Like, Vec4Like, World } from "@ignifx/core";
2
+ import { Bounds2D, Sprite2DCustomShader, Sprite2DHandle, Sprite2DLayer, Sprite2DProps, Sprite2DView, SpriteAtlas, SpriteBlendMode, SpriteFrame, SpritePickInfo, SpriteRenderer as SpriteRenderer$1, SpriteSampling, Texture2D } from "@babylonjs/lite";
3
+ //#region src/service/sorting-layers.d.ts
4
4
  /**
5
- * `Camera2D` (`docs/architecture/11-2d-toolkit.md` §2.1): the component that drives every world
6
- * sprite layer's `Sprite2DView`.
5
+ * The sorting-layer table (`docs/architecture/11-2d-toolkit.md` §1).
7
6
  *
8
- * The camera holds no Lite object of its own. A `Sprite2DView` belongs to a layer, and every world
9
- * layer gets the *same* view written to it each frame, which is what makes the layers move
10
- * together; screen-space layers keep the identity view. The 2D sync system does the writing —
11
- * this class owns the arithmetic and the public conversions.
7
+ * `@ignifx/core` owns the `sortingLayers` settings section — an ordered list of names, back to
8
+ * front — but ships no resolver for it, the way `layers/layer-table.ts` resolves the `layers`
9
+ * section. This is that resolver: it turns a name into the index the Lite layer's `order` is
10
+ * derived from, and it refuses a name the project never declared instead of silently drawing on
11
+ * the wrong layer.
12
12
  */
13
- /** The half-height, in metres, a camera that declares none shows. @public */
14
- export declare const DEFAULT_ORTHOGRAPHIC_SIZE = 5;
15
- /** The reference resolution a pixel-perfect camera fits an integer zoom to. @public */
16
- export declare const DEFAULT_REFERENCE_RESOLUTION: Vec2Like;
17
13
  /**
18
- * The 2D camera.
14
+ * The sorting layer a component that names none draws on.
15
+ *
16
+ * @public
17
+ */
18
+ export declare const DEFAULT_SORTING_LAYER = "Default";
19
+ /**
20
+ * How far apart two sorting layers' Lite `order` values sit.
19
21
  *
20
22
  * @remarks
21
- * `orthographicSize` is a **half-height in metres**, exactly as Unity's orthographic camera is, so
22
- * the zoom it produces is `viewportHeightPx / (2 · size · PPU)`. With `pixelPerfect` on, that zoom
23
- * is snapped to a whole number (or to `1/n` when the camera is pulled far out) and the camera's
24
- * position is snapped to the pixel grid at sync time — scripts keep their sub-pixel positions, so
25
- * movement stays smooth even though drawing does not.
23
+ * A gap of 1000 leaves room for the per-(atlas, blend, space) sub-layers a single sorting layer
24
+ * expands into: one sorting layer holding sprites from twelve atlases in three blend modes still
25
+ * fits inside its slice without reaching the next layer's.
26
+ *
27
+ * @public
28
+ */
29
+ export declare const SORTING_LAYER_ORDER_STEP = 1e3;
30
+ /**
31
+ * Resolves sorting-layer names to draw orders.
26
32
  *
27
33
  * @example
28
34
  * ```ts
29
- * const camera = app.world.createEntity({ name: "camera" }).addComponent(Camera2D);
30
- * camera.orthographicSize = 3;
31
- * camera.pixelPerfect = true;
35
+ * const layers = new SortingLayerTable(["Background", "Default", "Foreground"]);
36
+ * layers.indexOf("Foreground"); // 2
32
37
  * ```
33
38
  *
34
39
  * @public
35
40
  */
36
- export declare class Camera2D extends Component {
41
+ export declare class SortingLayerTable {
37
42
  #private;
38
- /** The registration id the serializer writes into scene files. */
39
- static typeId: string;
40
- /** One camera per entity. */
41
- static allowMultiple: boolean;
42
- /** The declarative fields (ADR-0004). */
43
- static schema: Schema;
44
- /** Half the viewport height, in metres. */
45
- orthographicSize: number;
46
- /** Whether zoom snaps to an integer and positions snap to the pixel grid. */
47
- pixelPerfect: boolean;
48
- /** The design resolution a pixel-perfect camera fits an integer zoom to, in pixels. */
49
- referenceResolution: Vec2Like;
50
- /** The lower bound of the camera's travel, in metres, or `null` for no bound. */
51
- boundsMin: Vec2Like | null;
52
- /** The upper bound of the camera's travel, in metres, or `null` for no bound. */
53
- boundsMax: Vec2Like | null;
54
- /** The entity this camera follows, or `null`. Read by `Camera2DFollow`. */
55
- follow: Entity | null;
56
- /** How long the follow takes to catch up, in seconds. */
57
- followDamping: number;
58
- /** A constant offset added to the followed entity's position, in metres. */
59
- followOffset: Vec2Like;
60
- /** The half-size of the rectangle the target may move inside before the camera reacts, in metres. */
61
- deadZone: Vec2Like;
62
- /** Highest wins when a world has several enabled cameras. */
63
- priority: number;
64
- /**
65
- * Builds a camera with the schema's defaults.
66
- */
67
- constructor();
68
43
  /**
69
- * The zoom the camera last resolved to — `Sprite2DView.zoom`.
44
+ * Builds the table from the project's `sortingLayers` section.
70
45
  *
71
- * @returns The zoom; `1` before the first sync.
46
+ * @param names - The names, back to front. An empty list falls back to `["Default"]`.
72
47
  */
73
- get zoom(): number;
48
+ constructor(names: readonly string[]);
74
49
  /**
75
- * The viewport the camera last measured, in pixels.
50
+ * The layer names, back to front.
76
51
  *
77
- * @returns A read-only view of the size.
52
+ * @returns The names.
78
53
  */
79
- get viewportSizePx(): Vec2Like;
54
+ get names(): readonly string[];
80
55
  /**
81
- * The world point the camera is centred on, after bounds clamping and pixel-perfect snapping.
56
+ * Resolves a name to its index.
82
57
  *
83
- * @returns A read-only view of the centre, in metres.
58
+ * @param name - The sorting layer name.
59
+ * @returns The index, or `-1` when the project declares no such layer.
84
60
  */
85
- get centre(): Vec2Like;
61
+ indexOf(name: string): number;
86
62
  /**
87
- * Recomputes the camera's zoom and centre. The 2D sync system calls this once per frame, before
88
- * it writes the view onto each world layer.
89
- *
90
- * @param worldX - The entity's world x, in metres.
91
- * @param worldY - The entity's world y, in metres.
92
- * @param viewportWidthPx - The surface width, in pixels.
93
- * @param viewportHeightPx - The surface height, in pixels.
94
- * @param pixelsPerUnit - The pixels one metre spans.
63
+ * Resolves a name to its index and refuses to guess.
95
64
  *
96
- * @internal
65
+ * @param name - The sorting layer name.
66
+ * @returns The index.
67
+ * @throws IgnifxError with code `IGX-1107` when the project declares no such layer.
97
68
  */
98
- resolve(worldX: number, worldY: number, viewportWidthPx: number, viewportHeightPx: number, pixelsPerUnit: number): void;
69
+ require(name: string): number;
99
70
  /**
100
- * Converts a viewport pixel into a world point.
101
- *
102
- * @remarks
103
- * `x` and `y` are measured from the surface's top-left corner, which is what a `PointerEvent`
104
- * reports and what `@ignifx/input`'s pointer position carries. The result is in metres with +Y
105
- * up. Before the first frame has synced, the camera has no viewport and the result is the
106
- * camera's own centre.
107
- *
108
- * @param x - The viewport x, in pixels from the left edge.
109
- * @param y - The viewport y, in pixels from the top edge.
110
- * @param out - The vector to write; omitting it allocates one.
111
- * @returns `out`, in world metres.
71
+ * The Lite `Sprite2DLayer.order` a sorting layer's sub-layers start at.
112
72
  *
113
- * @example
114
- * ```ts
115
- * const world = camera.screenToWorld(pointer.x, pointer.y);
116
- * ```
73
+ * @param name - The sorting layer name.
74
+ * @returns The base order.
75
+ * @throws IgnifxError with code `IGX-1107` when the project declares no such layer.
117
76
  */
118
- screenToWorld(x: number, y: number, out?: MutableVec2): MutableVec2;
77
+ orderOf(name: string): number;
78
+ }
79
+ //#endregion
80
+ //#region src/atlas/definition.d.ts
81
+ /**
82
+ * The `ignifx.spriteatlas` document — the `.atlas.json` file that names an image and the frame
83
+ * rectangles inside it (`docs/architecture/06-serialization-and-scene-format.md` §6,
84
+ * `11-2d-toolkit.md` §2.3).
85
+ *
86
+ * Frames are in **image pixels with a top-left origin**, which is what every atlas packer emits.
87
+ * The conversion into Lite's normalised UVs happens in the loader, once.
88
+ */
89
+ /**
90
+ * The `format` discriminator every `.atlas.json` document carries.
91
+ *
92
+ * @public
93
+ */
94
+ export declare const SPRITE_ATLAS_FORMAT = "ignifx.spriteatlas";
95
+ /**
96
+ * The document version this build reads and writes.
97
+ *
98
+ * @public
99
+ */
100
+ export declare const SPRITE_ATLAS_FORMAT_VERSION = 1;
101
+ /**
102
+ * The asset type name the loader registers.
103
+ *
104
+ * @public
105
+ */
106
+ export declare const SPRITE_ATLAS_ASSET_TYPE = "spriteatlas";
107
+ /**
108
+ * The address suffixes that select the sprite-atlas loader.
109
+ *
110
+ * @public
111
+ */
112
+ export declare const SPRITE_ATLAS_FILE_EXTENSIONS: readonly string[];
113
+ /**
114
+ * The fragment prefix that addresses one frame: `"sprites/hero.atlas.json#frame:idle_0"`.
115
+ *
116
+ * @public
117
+ */
118
+ export declare const SPRITE_FRAME_FRAGMENT_PREFIX = "frame:";
119
+ /**
120
+ * A 2D value as a document may write it: `[x, y]`, the form `@ignifx/core` encodes every `vec2`
121
+ * field into a file as (`schema/encode.ts` line 393), or `{ x, y }`, the form an importer emits.
122
+ *
123
+ * @public
124
+ */
125
+ type Vec2Json = Vec2Like | readonly [number, number];
126
+ /**
127
+ * Normalises either written form of a 2D value.
128
+ *
129
+ * @param value - What the document wrote, or `undefined`.
130
+ * @param fallback - What to use when the document wrote nothing.
131
+ * @returns The normalised vector.
132
+ *
133
+ * @public
134
+ */
135
+ export declare function readVec2(value: Vec2Json | undefined, fallback: Vec2Like): Vec2Like;
136
+ /**
137
+ * One frame rectangle, in image pixels with a top-left origin.
138
+ *
139
+ * @public
140
+ */
141
+ interface SpriteFrameDefinition {
142
+ /** The frame's name, unique within the document; what `#frame:` addresses. */
143
+ readonly name: string;
144
+ /** The left edge, in image pixels. */
145
+ readonly x: number;
146
+ /** The top edge, in image pixels. */
147
+ readonly y: number;
148
+ /** The width, in image pixels. */
149
+ readonly w: number;
150
+ /** The height, in image pixels. */
151
+ readonly h: number;
119
152
  /**
120
- * Converts a world point into a viewport pixel.
121
- *
122
- * @param point - The world point, in metres.
123
- * @param out - The vector to write; omitting it allocates one.
124
- * @returns `out`, in pixels from the surface's top-left corner.
153
+ * The pivot in `[0, 1]` of the frame — `[0, 0]` top-left, `[0.5, 0.5]` centre, `[1, 1]`
154
+ * bottom-right. Defaults to the centre. Written either as `[x, y]` or as `{ x, y }`.
125
155
  */
126
- worldToScreen(point: Vec2Like, out?: MutableVec2): MutableVec2;
156
+ readonly pivot?: Vec2Json;
157
+ /** The untrimmed source size, when the packer trimmed transparent margins. Defaults to `w`/`h`. */
158
+ readonly sourceSize?: Vec2Json;
127
159
  }
128
- //#endregion
129
- //#region src/lite/sprite-layer.d.ts
130
160
  /**
131
- * The CPU half of the Babylon Lite sprite adapter (`docs/architecture/07-rendering.md` §7,
132
- * `11-2d-toolkit.md` §1). Nothing in this module touches `engine._device`: a `Sprite2DLayer` is a
133
- * plain object holding a `Float32Array` of instance data, and every sprite mutation writes into
134
- * that array (verified in `@babylonjs/lite@1.27.0`, `lib/sprite/sprite-2d.js` lines 14-48 for
135
- * `createSprite2DLayer` and 73-200 for `writeInstance`/`addSprite2DIndex`). GPU buffers are
136
- * allocated lazily by the renderer at draw time, which is why the device-only calls live in
137
- * `./gpu/sprite-renderer.ts` instead.
161
+ * The parsed `.atlas.json` document.
138
162
  *
139
- * That split is what makes the sprite maths unit-testable under Node: a test fabricates a
140
- * `SpriteAtlas` with {@link createDataAtlas} and exercises everything here on the null engine.
163
+ * @example
164
+ * ```ts
165
+ * const atlas = defineSpriteAtlas({
166
+ * image: "2d/hero.png",
167
+ * sampling: "nearest",
168
+ * frames: [{ name: "idle_0", x: 0, y: 0, w: 32, h: 32, pivot: { x: 0.5, y: 1 } }],
169
+ * });
170
+ * ```
141
171
  *
142
- * Everything except the blend-mode table is `@internal`.
172
+ * @public
143
173
  */
144
- /** The blend modes `SpriteRenderer.blend` accepts, in the order an inspector should list them. @public */
145
- export declare const SPRITE_BLEND_MODES: readonly ["alpha", "premultiplied", "additive", "multiply", "opaque"];
174
+ interface SpriteAtlasDefinition {
175
+ /** Always `"ignifx.spriteatlas"`. */
176
+ readonly format: typeof SPRITE_ATLAS_FORMAT;
177
+ /** Always `1` in this build. */
178
+ readonly formatVersion: number;
179
+ /** The address of the image the frames are cut from. */
180
+ readonly image: string;
181
+ /** The min/mag filter. `"nearest"` is what pixel art wants. Defaults to `"linear"`. */
182
+ readonly sampling: "linear" | "nearest";
183
+ /** Whether the image's RGB is already multiplied by its alpha. Defaults to `false`. */
184
+ readonly premultipliedAlpha: boolean;
185
+ /** The frames, in the order they are indexed. */
186
+ readonly frames: readonly SpriteFrameDefinition[];
187
+ }
146
188
  /**
147
- * How a sprite's colour combines with what is already in the framebuffer
148
- * (`docs/architecture/11-2d-toolkit.md` §2.2).
189
+ * What {@link defineSpriteAtlas} accepts: the document with every defaulted field optional.
149
190
  *
150
191
  * @public
151
192
  */
152
- type SpriteBlendName = (typeof SPRITE_BLEND_MODES)[number];
193
+ interface SpriteAtlasInput {
194
+ /** Always `"ignifx.spriteatlas"` when present. */
195
+ readonly format?: string;
196
+ /** The document version. */
197
+ readonly formatVersion?: number;
198
+ /** The address of the image the frames are cut from. */
199
+ readonly image: string;
200
+ /** The min/mag filter. Defaults to `"linear"`. */
201
+ readonly sampling?: "linear" | "nearest";
202
+ /** Whether the image is premultiplied. Defaults to `false`. */
203
+ readonly premultipliedAlpha?: boolean;
204
+ /** The frames. */
205
+ readonly frames: readonly SpriteFrameDefinition[];
206
+ }
153
207
  /**
154
- * A reusable `Sprite2DProps` record, so a per-frame sync allocates nothing.
208
+ * Fills in the defaults of an atlas document and checks the invariants a loader relies on.
155
209
  *
156
- * @remarks
157
- * `positionPx`, `sizePx`, and `color` are mutable tuples Lite reads and never retains
158
- * (`writeInstance` copies each component out — `lib/sprite/sprite-2d.js` lines 79-167), so one
159
- * scratch object can be rewritten and re-submitted every frame (coding standards §7).
210
+ * @param input - The document, as authored or as an importer emitted it.
211
+ * @param address - What to name in an error; defaults to `"<inline>"`.
212
+ * @returns The complete document.
213
+ * @throws IgnifxError with code `IGX-1103` when the format tag, the version, the image address, or
214
+ * a frame rectangle is wrong, or two frames share a name.
215
+ *
216
+ * @public
217
+ */
218
+ export declare function defineSpriteAtlas(input: SpriteAtlasInput, address?: string): SpriteAtlasDefinition;
219
+ /**
220
+ * Splits a sprite address into its atlas address and its frame name.
221
+ *
222
+ * @param fragment - The part after `#`, or `null` for a bare atlas address.
223
+ * @returns The frame name, or `null` when the fragment does not select a frame.
160
224
  *
161
- * @internal
225
+ * @example
226
+ * ```ts
227
+ * parseSpriteFragment("frame:idle_0"); // "idle_0"
228
+ * ```
229
+ *
230
+ * @public
162
231
  */
163
- interface SpriteScratch {
164
- /** The props object handed to `addSprite2D`/`updateSprite2D`. */
165
- readonly props: Sprite2DProps;
166
- }
232
+ export declare function parseSpriteFragment(fragment: string | null): string | null;
167
233
  //#endregion
168
234
  //#region src/lite/types.d.ts
169
235
  /**
@@ -276,131 +342,23 @@ type LiteSpritePickInfo = SpritePickInfo;
276
342
  */
277
343
  type LiteBounds2D = Bounds2D;
278
344
  /**
279
- * The GPU texture behind an atlas (`index.d.ts` 12907).
345
+ * A compiled per-layer fragment shader (`index.d.ts` 11863).
280
346
  *
281
347
  * @remarks
282
348
  * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
283
349
  *
284
350
  * @public
285
351
  */
286
- type LiteAtlasTexture = Texture2D;
287
- //#endregion
288
- //#region src/atlas/definition.d.ts
289
- /**
290
- * The `ignifx.spriteatlas` document — the `.atlas.json` file that names an image and the frame
291
- * rectangles inside it (`docs/architecture/06-serialization-and-scene-format.md` §6,
292
- * `11-2d-toolkit.md` §2.3).
293
- *
294
- * Frames are in **image pixels with a top-left origin**, which is what every atlas packer emits.
295
- * The conversion into Lite's normalised UVs happens in the loader, once.
296
- */
297
- /** The `format` discriminator every `.atlas.json` document carries. @public */
298
- export declare const SPRITE_ATLAS_FORMAT = "ignifx.spriteatlas";
299
- /** The document version this build reads and writes. @public */
300
- export declare const SPRITE_ATLAS_FORMAT_VERSION = 1;
301
- /** The asset type name the loader registers. @public */
302
- export declare const SPRITE_ATLAS_ASSET_TYPE = "spriteatlas";
303
- /** The address suffixes that select the sprite-atlas loader. @public */
304
- export declare const SPRITE_ATLAS_FILE_EXTENSIONS: readonly string[];
305
- /** The fragment prefix that addresses one frame: `"sprites/hero.atlas.json#frame:idle_0"`. @public */
306
- export declare const SPRITE_FRAME_FRAGMENT_PREFIX = "frame:";
307
- /**
308
- * One frame rectangle, in image pixels with a top-left origin.
309
- *
310
- * @public
311
- */
312
- interface SpriteFrameDefinition {
313
- /** The frame's name, unique within the document; what `#frame:` addresses. */
314
- readonly name: string;
315
- /** The left edge, in image pixels. */
316
- readonly x: number;
317
- /** The top edge, in image pixels. */
318
- readonly y: number;
319
- /** The width, in image pixels. */
320
- readonly w: number;
321
- /** The height, in image pixels. */
322
- readonly h: number;
323
- /**
324
- * The pivot in `[0, 1]` of the frame — `[0, 0]` top-left, `[0.5, 0.5]` centre, `[1, 1]`
325
- * bottom-right. Defaults to the centre.
326
- */
327
- readonly pivot?: Vec2Like;
328
- /** The untrimmed source size, when the packer trimmed transparent margins. Defaults to `w`/`h`. */
329
- readonly sourceSize?: Vec2Like;
330
- }
331
- /**
332
- * The parsed `.atlas.json` document.
333
- *
334
- * @example
335
- * ```ts
336
- * const atlas = defineSpriteAtlas({
337
- * image: "2d/hero.png",
338
- * sampling: "nearest",
339
- * frames: [{ name: "idle_0", x: 0, y: 0, w: 32, h: 32, pivot: { x: 0.5, y: 1 } }],
340
- * });
341
- * ```
342
- *
343
- * @public
344
- */
345
- interface SpriteAtlasDefinition {
346
- /** Always `"ignifx.spriteatlas"`. */
347
- readonly format: typeof SPRITE_ATLAS_FORMAT;
348
- /** Always `1` in this build. */
349
- readonly version: number;
350
- /** The address of the image the frames are cut from. */
351
- readonly image: string;
352
- /** The min/mag filter. `"nearest"` is what pixel art wants. Defaults to `"linear"`. */
353
- readonly sampling: "linear" | "nearest";
354
- /** Whether the image's RGB is already multiplied by its alpha. Defaults to `false`. */
355
- readonly premultipliedAlpha: boolean;
356
- /** The frames, in the order they are indexed. */
357
- readonly frames: readonly SpriteFrameDefinition[];
358
- }
359
- /**
360
- * What {@link defineSpriteAtlas} accepts: the document with every defaulted field optional.
361
- *
362
- * @public
363
- */
364
- interface SpriteAtlasInput {
365
- /** Always `"ignifx.spriteatlas"` when present. */
366
- readonly format?: string;
367
- /** The document version. */
368
- readonly version?: number;
369
- /** The address of the image the frames are cut from. */
370
- readonly image: string;
371
- /** The min/mag filter. Defaults to `"linear"`. */
372
- readonly sampling?: "linear" | "nearest";
373
- /** Whether the image is premultiplied. Defaults to `false`. */
374
- readonly premultipliedAlpha?: boolean;
375
- /** The frames. */
376
- readonly frames: readonly SpriteFrameDefinition[];
377
- }
378
- /**
379
- * Fills in the defaults of an atlas document and checks the invariants a loader relies on.
380
- *
381
- * @param input - The document, as authored or as an importer emitted it.
382
- * @param address - What to name in an error; defaults to `"<inline>"`.
383
- * @returns The complete document.
384
- * @throws IgnifxError with code `IGX-1103` when the format tag, the version, the image address, or
385
- * a frame rectangle is wrong, or two frames share a name.
386
- *
387
- * @public
388
- */
389
- export declare function defineSpriteAtlas(input: SpriteAtlasInput, address?: string): SpriteAtlasDefinition;
352
+ type LiteSpriteCustomShader = Sprite2DCustomShader;
390
353
  /**
391
- * Splits a sprite address into its atlas address and its frame name.
392
- *
393
- * @param fragment - The part after `#`, or `null` for a bare atlas address.
394
- * @returns The frame name, or `null` when the fragment does not select a frame.
354
+ * The GPU texture behind an atlas (`index.d.ts` 12907).
395
355
  *
396
- * @example
397
- * ```ts
398
- * parseSpriteFragment("frame:idle_0"); // "idle_0"
399
- * ```
356
+ * @remarks
357
+ * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
400
358
  *
401
359
  * @public
402
360
  */
403
- export declare function parseSpriteFragment(fragment: string | null): string | null;
361
+ type LiteAtlasTexture = Texture2D;
404
362
  //#endregion
405
363
  //#region src/atlas/sprite-atlas-asset.d.ts
406
364
  /**
@@ -552,6 +510,49 @@ interface SpriteAsset {
552
510
  readonly name: string;
553
511
  }
554
512
  //#endregion
513
+ //#region src/lite/sprite-layer.d.ts
514
+ /**
515
+ * The CPU half of the Babylon Lite sprite adapter (`docs/architecture/07-rendering.md` §7,
516
+ * `11-2d-toolkit.md` §1). Nothing in this module touches `engine._device`: a `Sprite2DLayer` is a
517
+ * plain object holding a `Float32Array` of instance data, and every sprite mutation writes into
518
+ * that array (verified in `@babylonjs/lite@1.27.0`, `lib/sprite/sprite-2d.js` lines 14-48 for
519
+ * `createSprite2DLayer` and 73-200 for `writeInstance`/`addSprite2DIndex`). GPU buffers are
520
+ * allocated lazily by the renderer at draw time, which is why the device-only calls live in
521
+ * `./gpu/sprite-renderer.ts` instead.
522
+ *
523
+ * That split is what makes the sprite maths unit-testable under Node: a test fabricates a
524
+ * `SpriteAtlas` with {@link createDataAtlas} and exercises everything here on the null engine.
525
+ *
526
+ * Everything except the blend-mode table is `@internal`.
527
+ */
528
+ /**
529
+ * The blend modes `SpriteRenderer.blend` accepts, in the order an inspector should list them.
530
+ *
531
+ * @public
532
+ */
533
+ export declare const SPRITE_BLEND_MODES: readonly ["alpha", "premultiplied", "additive", "multiply", "opaque"];
534
+ /**
535
+ * How a sprite's colour combines with what is already in the framebuffer
536
+ * (`docs/architecture/11-2d-toolkit.md` §2.2).
537
+ *
538
+ * @public
539
+ */
540
+ type SpriteBlendName = (typeof SPRITE_BLEND_MODES)[number];
541
+ /**
542
+ * A reusable `Sprite2DProps` record, so a per-frame sync allocates nothing.
543
+ *
544
+ * @remarks
545
+ * `positionPx`, `sizePx`, and `color` are mutable tuples Lite reads and never retains
546
+ * (`writeInstance` copies each component out — `lib/sprite/sprite-2d.js` lines 79-167), so one
547
+ * scratch object can be rewritten and re-submitted every frame (coding standards §7).
548
+ *
549
+ * @internal
550
+ */
551
+ interface SpriteScratch {
552
+ /** The props object handed to `addSprite2D`/`updateSprite2D`. */
553
+ readonly props: Sprite2DProps;
554
+ }
555
+ //#endregion
555
556
  //#region src/sprite/sprite-renderer.d.ts
556
557
  /**
557
558
  * `SpriteRenderer` (`docs/architecture/11-2d-toolkit.md` §2.2): one sprite drawn from one frame of
@@ -648,6 +649,11 @@ export declare class SpriteRenderer extends Component implements ComponentHooks
648
649
  * @returns The frame index.
649
650
  */
650
651
  get frame(): number;
652
+ /**
653
+ * Sets the atlas frame drawn, marking the sprite for the next sync when it changes.
654
+ *
655
+ * @param value - The frame index.
656
+ */
651
657
  set frame(value: number);
652
658
  /**
653
659
  * The Babylon Lite objects the component uses. Unstable escape hatch
@@ -731,79 +737,6 @@ export declare class SpriteRenderer extends Component implements ComponentHooks
731
737
  setPlacement(handle: LiteSprite2DHandle | null, key: string | null): void;
732
738
  }
733
739
  //#endregion
734
- //#region src/service/sorting-layers.d.ts
735
- /**
736
- * The sorting-layer table (`docs/architecture/11-2d-toolkit.md` §1).
737
- *
738
- * `@ignifx/core` owns the `sortingLayers` settings section — an ordered list of names, back to
739
- * front — but ships no resolver for it, the way `layers/layer-table.ts` resolves the `layers`
740
- * section. This is that resolver: it turns a name into the index the Lite layer's `order` is
741
- * derived from, and it refuses a name the project never declared instead of silently drawing on
742
- * the wrong layer.
743
- */
744
- /** The sorting layer a component that names none draws on. @public */
745
- export declare const DEFAULT_SORTING_LAYER = "Default";
746
- /**
747
- * How far apart two sorting layers' Lite `order` values sit.
748
- *
749
- * @remarks
750
- * A gap of 1000 leaves room for the per-(atlas, blend, space) sub-layers a single sorting layer
751
- * expands into: one sorting layer holding sprites from twelve atlases in three blend modes still
752
- * fits inside its slice without reaching the next layer's.
753
- *
754
- * @public
755
- */
756
- export declare const SORTING_LAYER_ORDER_STEP = 1e3;
757
- /**
758
- * Resolves sorting-layer names to draw orders.
759
- *
760
- * @example
761
- * ```ts
762
- * const layers = new SortingLayerTable(["Background", "Default", "Foreground"]);
763
- * layers.indexOf("Foreground"); // 2
764
- * ```
765
- *
766
- * @public
767
- */
768
- export declare class SortingLayerTable {
769
- #private;
770
- /**
771
- * Builds the table from the project's `sortingLayers` section.
772
- *
773
- * @param names - The names, back to front. An empty list falls back to `["Default"]`.
774
- */
775
- constructor(names: readonly string[]);
776
- /**
777
- * The layer names, back to front.
778
- *
779
- * @returns The names.
780
- */
781
- get names(): readonly string[];
782
- /**
783
- * Resolves a name to its index.
784
- *
785
- * @param name - The sorting layer name.
786
- * @returns The index, or `-1` when the project declares no such layer.
787
- */
788
- indexOf(name: string): number;
789
- /**
790
- * Resolves a name to its index and refuses to guess.
791
- *
792
- * @param name - The sorting layer name.
793
- * @returns The index.
794
- * @throws IgnifxError with code `IGX-1107` when the project declares no such layer.
795
- */
796
- require(name: string): number;
797
- /**
798
- * The Lite `Sprite2DLayer.order` a sorting layer's sub-layers start at.
799
- *
800
- * @param name - The sorting layer name.
801
- * @returns The base order.
802
- * @throws IgnifxError with code `IGX-1107` when the project declares no such layer.
803
- */
804
- orderOf(name: string): number;
805
- }
806
- //#endregion
807
740
  //#region src/service/layer-registry.d.ts
808
741
  /**
809
742
  * One Lite layer and everything the registry tracks alongside it.
@@ -811,7 +744,7 @@ export declare class SortingLayerTable {
811
744
  * @public
812
745
  */
813
746
  interface SpriteLayerEntry {
814
- /** The composite key: `` `${sortingLayer}|${atlasAddress}|${blend}|${space}` ``. */
747
+ /** The composite key, built by {@link spriteLayerKey}. */
815
748
  readonly key: string;
816
749
  /** The sorting layer's name. */
817
750
  readonly sortingLayer: string;
@@ -846,12 +779,34 @@ export declare class SpriteLayerRegistry {
846
779
  /**
847
780
  * Builds the registry.
848
781
  *
849
- * @param sortingLayers - Resolves a sorting-layer name to its draw order.
850
- * @param ySort - Which sorting layers draw back-to-front by world Y.
851
- * @param onLayerCreated - Called with each new Lite layer, so the sprite renderer can draw it.
852
- * @param onLayerRemoved - Called before a layer is dropped.
782
+ * @param sortingLayers - Resolves a sorting-layer name to its draw order.
783
+ * @param ySort - Which sorting layers draw back-to-front by world Y.
784
+ * @param onLayerCreated - Called with each new Lite layer, so the sprite renderer can draw it.
785
+ * @param onLayerRemoved - Called before a layer is dropped.
786
+ */
787
+ constructor(sortingLayers: SortingLayerTable, ySort: Readonly<Record<string, boolean>>, onLayerCreated: (layer: LiteSprite2DLayer) => void, onLayerRemoved: (layer: LiteSprite2DLayer) => void);
788
+ /**
789
+ * Installs the source of per-sorting-layer custom shaders.
790
+ *
791
+ * @remarks
792
+ * `Sprite2DLayer.customShader` is `readonly` and is only read at creation, so a
793
+ * `SpriteLayerEffect` has to be discoverable **before** the first sprite on its sorting layer is
794
+ * placed. That is why the registry pulls the shader rather than the effect pushing it.
795
+ *
796
+ * @param provider - Returns the compiled shader for a sorting layer, or `null`.
797
+ *
798
+ * @internal
799
+ */
800
+ setShaderProvider(provider: (sortingLayer: string) => LiteSpriteCustomShader | null): void;
801
+ /**
802
+ * Writes a sorting layer's `fx.params` vec4 onto every layer belonging to it.
803
+ *
804
+ * @param sortingLayer - The sorting layer's name.
805
+ * @param params - The four components.
806
+ *
807
+ * @internal
853
808
  */
854
- constructor(sortingLayers: SortingLayerTable, ySort: Readonly<Record<string, boolean>>, onLayerCreated: (layer: LiteSprite2DLayer) => void, onLayerRemoved: (layer: LiteSprite2DLayer) => void);
809
+ writeShaderParams(sortingLayer: string, params: Float32Array): void;
855
810
  /**
856
811
  * Every layer, in draw order.
857
812
  *
@@ -924,6 +879,23 @@ export declare class SpriteLayerRegistry {
924
879
  * @internal
925
880
  */
926
881
  removeRaw(key: string, handle: LiteSprite2DHandle): void;
882
+ /**
883
+ * Applies a sprite's `orderInLayer` to the layer holding it.
884
+ *
885
+ * @remarks
886
+ * Lite's Y-sort bias setter **throws** on a layer that has no Y-sort state
887
+ * (`lib/sprite/sprite-2d-y-sort.js`, `setSprite2DYSortBias`), so the bias is only written to a
888
+ * layer that is actually sorting. On a layer that is not, `orderInLayer` falls back to ordering
889
+ * by insertion, which is exactly what `docs/architecture/11-2d-toolkit.md` §1 specifies:
890
+ * "applied as a Y-sort bias when Y-sort is on, or as sub-ordering by insertion when off"*.
891
+ *
892
+ * @param key - The key of the layer holding the sprite.
893
+ * @param handle - The sprite.
894
+ * @param orderInLayer - The component's `orderInLayer`.
895
+ *
896
+ * @internal
897
+ */
898
+ applyOrderInLayer(key: string, handle: LiteSprite2DHandle, orderInLayer: number): void;
927
899
  /**
928
900
  * Resolves a pick hit back to the component that owns the sprite.
929
901
  *
@@ -942,6 +914,140 @@ export declare class SpriteLayerRegistry {
942
914
  clear(): void;
943
915
  }
944
916
  //#endregion
917
+ //#region src/camera/camera-2d.d.ts
918
+ /**
919
+ * `Camera2D` (`docs/architecture/11-2d-toolkit.md` §2.1): the component that drives every world
920
+ * sprite layer's `Sprite2DView`.
921
+ *
922
+ * The camera holds no Lite object of its own. A `Sprite2DView` belongs to a layer, and every world
923
+ * layer gets the *same* view written to it each frame, which is what makes the layers move
924
+ * together; screen-space layers keep the identity view. The 2D sync system does the writing —
925
+ * this class owns the arithmetic and the public conversions.
926
+ */
927
+ /**
928
+ * The half-height, in metres, a camera that declares none shows.
929
+ *
930
+ * @public
931
+ */
932
+ export declare const DEFAULT_ORTHOGRAPHIC_SIZE = 5;
933
+ /**
934
+ * The reference resolution a pixel-perfect camera fits an integer zoom to.
935
+ *
936
+ * @public
937
+ */
938
+ export declare const DEFAULT_REFERENCE_RESOLUTION: Vec2Like;
939
+ /**
940
+ * The 2D camera.
941
+ *
942
+ * @remarks
943
+ * `orthographicSize` is a **half-height in metres**, exactly as Unity's orthographic camera is, so
944
+ * the zoom it produces is `viewportHeightPx / (2 · size · PPU)`. With `pixelPerfect` on, that zoom
945
+ * is snapped to a whole number (or to `1/n` when the camera is pulled far out) and the camera's
946
+ * position is snapped to the pixel grid at sync time — scripts keep their sub-pixel positions, so
947
+ * movement stays smooth even though drawing does not.
948
+ *
949
+ * @example
950
+ * ```ts
951
+ * const camera = app.world.createEntity({ name: "camera" }).addComponent(Camera2D);
952
+ * camera.orthographicSize = 3;
953
+ * camera.pixelPerfect = true;
954
+ * ```
955
+ *
956
+ * @public
957
+ */
958
+ export declare class Camera2D extends Component {
959
+ #private;
960
+ /** The registration id the serializer writes into scene files. */
961
+ static typeId: string;
962
+ /** One camera per entity. */
963
+ static allowMultiple: boolean;
964
+ /** The declarative fields (ADR-0004). */
965
+ static schema: Schema;
966
+ /** Half the viewport height, in metres. */
967
+ orthographicSize: number;
968
+ /** Whether zoom snaps to an integer and positions snap to the pixel grid. */
969
+ pixelPerfect: boolean;
970
+ /** The design resolution a pixel-perfect camera fits an integer zoom to, in pixels. */
971
+ referenceResolution: Vec2Like;
972
+ /** The lower bound of the camera's travel, in metres, or `null` for no bound. */
973
+ boundsMin: Vec2Like | null;
974
+ /** The upper bound of the camera's travel, in metres, or `null` for no bound. */
975
+ boundsMax: Vec2Like | null;
976
+ /** The entity this camera follows, or `null`. Read by `Camera2DFollow`. */
977
+ follow: Entity | null;
978
+ /** How long the follow takes to catch up, in seconds. */
979
+ followDamping: number;
980
+ /** A constant offset added to the followed entity's position, in metres. */
981
+ followOffset: Vec2Like;
982
+ /** The half-size of the rectangle the target may move inside before the camera reacts, in metres. */
983
+ deadZone: Vec2Like;
984
+ /** Highest wins when a world has several enabled cameras. */
985
+ priority: number;
986
+ /**
987
+ * Builds a camera with the schema's defaults.
988
+ */
989
+ constructor();
990
+ /**
991
+ * The zoom the camera last resolved to — `Sprite2DView.zoom`.
992
+ *
993
+ * @returns The zoom; `1` before the first sync.
994
+ */
995
+ get zoom(): number;
996
+ /**
997
+ * The viewport the camera last measured, in pixels.
998
+ *
999
+ * @returns A read-only view of the size.
1000
+ */
1001
+ get viewportSizePx(): Vec2Like;
1002
+ /**
1003
+ * The world point the camera is centred on, after bounds clamping and pixel-perfect snapping.
1004
+ *
1005
+ * @returns A read-only view of the centre, in metres.
1006
+ */
1007
+ get centre(): Vec2Like;
1008
+ /**
1009
+ * Recomputes the camera's zoom and centre. The 2D sync system calls this once per frame, before
1010
+ * it writes the view onto each world layer.
1011
+ *
1012
+ * @param worldX - The entity's world x, in metres.
1013
+ * @param worldY - The entity's world y, in metres.
1014
+ * @param viewportWidthPx - The surface width, in pixels.
1015
+ * @param viewportHeightPx - The surface height, in pixels.
1016
+ * @param pixelsPerUnit - The pixels one metre spans.
1017
+ *
1018
+ * @internal
1019
+ */
1020
+ resolve(worldX: number, worldY: number, viewportWidthPx: number, viewportHeightPx: number, pixelsPerUnit: number): void;
1021
+ /**
1022
+ * Converts a viewport pixel into a world point.
1023
+ *
1024
+ * @remarks
1025
+ * `x` and `y` are measured from the surface's top-left corner, which is what a `PointerEvent`
1026
+ * reports and what `@ignifx/input`'s pointer position carries. The result is in metres with +Y
1027
+ * up. Before the first frame has synced, the camera has no viewport and the result is the
1028
+ * camera's own centre.
1029
+ *
1030
+ * @param x - The viewport x, in pixels from the left edge.
1031
+ * @param y - The viewport y, in pixels from the top edge.
1032
+ * @param out - The vector to write; omitting it allocates one.
1033
+ * @returns `out`, in world metres.
1034
+ *
1035
+ * @example
1036
+ * ```ts
1037
+ * const world = camera.screenToWorld(pointer.x, pointer.y);
1038
+ * ```
1039
+ */
1040
+ screenToWorld(x: number, y: number, out?: MutableVec2): MutableVec2;
1041
+ /**
1042
+ * Converts a world point into a viewport pixel.
1043
+ *
1044
+ * @param point - The world point, in metres.
1045
+ * @param out - The vector to write; omitting it allocates one.
1046
+ * @returns `out`, in pixels from the surface's top-left corner.
1047
+ */
1048
+ worldToScreen(point: Vec2Like, out?: MutableVec2): MutableVec2;
1049
+ }
1050
+ //#endregion
945
1051
  //#region src/sprite/parallax-layer.d.ts
946
1052
  /**
947
1053
  * `ParallaxLayer` (`docs/architecture/11-2d-toolkit.md` §2.6): makes one sorting layer scroll at a
@@ -1141,26 +1247,88 @@ declare class TwoDRuntime {
1141
1247
  * @param options - The app, the settings, the sorting layers, and the Lite hooks.
1142
1248
  */
1143
1249
  constructor(options: TwoDRuntimeOptions);
1144
- /** The resolved settings. */
1250
+ /**
1251
+ * The resolved settings.
1252
+ *
1253
+ * @returns The `twoD` settings, after any scene-file override.
1254
+ */
1145
1255
  get settings(): TwoDSettings;
1146
- /** How many pixels one world metre spans. */
1256
+ /**
1257
+ * How many pixels one world metre spans.
1258
+ *
1259
+ * @returns The conversion factor.
1260
+ */
1147
1261
  get pixelsPerUnit(): number;
1148
- /** The sorting-layer resolver. */
1262
+ /**
1263
+ * The sorting-layer resolver.
1264
+ *
1265
+ * @returns The table.
1266
+ */
1149
1267
  get sortingLayers(): SortingLayerTable;
1150
- /** The layer pool. */
1268
+ /**
1269
+ * The layer pool.
1270
+ *
1271
+ * @returns The registry.
1272
+ */
1151
1273
  get layers(): SpriteLayerRegistry;
1152
- /** The Lite sprite renderer, or `null`. */
1274
+ /**
1275
+ * The Lite sprite renderer, or `null`.
1276
+ *
1277
+ * @returns The renderer, or `null` under a headless app or before the first frame.
1278
+ */
1153
1279
  get renderer(): LiteSpriteRenderer | null;
1154
- /** The camera the last frame drew through, or `null`. */
1280
+ /**
1281
+ * The camera the last frame drew through, or `null`.
1282
+ *
1283
+ * @returns The camera.
1284
+ */
1155
1285
  get mainCamera(): Camera2D | null;
1156
- /** How many sprites the last frame actually wrote to Lite. */
1286
+ /**
1287
+ * How many sprites the last frame actually wrote to Lite.
1288
+ *
1289
+ * @returns The count.
1290
+ */
1157
1291
  get syncedLastFrame(): number;
1158
- /** How many `SpriteRenderer` components the last frame walked. */
1292
+ /**
1293
+ * How many `SpriteRenderer` components the last frame walked.
1294
+ *
1295
+ * @returns The count.
1296
+ */
1159
1297
  get spriteCount(): number;
1160
- /** The surface width the views are sized against, in pixels. */
1298
+ /**
1299
+ * The surface width the views are sized against, in pixels.
1300
+ *
1301
+ * @returns The width; `0` under a headless app.
1302
+ */
1161
1303
  get viewportWidthPx(): number;
1162
- /** The surface height the views are sized against, in pixels. */
1304
+ /**
1305
+ * The surface height the views are sized against, in pixels.
1306
+ *
1307
+ * @returns The height; `0` under a headless app.
1308
+ */
1163
1309
  get viewportHeightPx(): number;
1310
+ /**
1311
+ * Installs the callback that reacts to a scene load.
1312
+ *
1313
+ * @remarks
1314
+ * The extension cannot connect `world.onSceneLoaded` itself: `register` runs before the world
1315
+ * exists, and `onStart` runs only when a game calls `app.start()` — which a headless tool or a
1316
+ * test may never do. `System.onWorldCreated` is the one hook that fires for every world, started
1317
+ * or not, so the sync system routes it here.
1318
+ *
1319
+ * @param handler - What to run for each loaded scene.
1320
+ */
1321
+ setSceneHandler(handler: (scene: SceneInstance) => void): void;
1322
+ /**
1323
+ * Connects the scene hook to a world.
1324
+ *
1325
+ * @param world - The world that was just created.
1326
+ */
1327
+ attachWorld(world: World): void;
1328
+ /**
1329
+ * Disconnects the scene hook.
1330
+ */
1331
+ detachWorld(): void;
1164
1332
  /**
1165
1333
  * Replaces the settings, which a scene file's `settings.twoD` block does at load time.
1166
1334
  *
@@ -1206,6 +1374,17 @@ declare class TwoDRuntime {
1206
1374
  * @param deltaSeconds - The scaled frame delta.
1207
1375
  */
1208
1376
  advanceAnimatedTiles(world: World, deltaSeconds: number): void;
1377
+ /**
1378
+ * Records the enabled `SpriteLayerEffect` of each sorting layer, so the registry can reach one
1379
+ * when it creates a layer.
1380
+ *
1381
+ * @param world - The world to walk.
1382
+ */
1383
+ collectEffects(world: World): void;
1384
+ /**
1385
+ * Writes every effect's `fx.params` vec4 onto its sorting layer's Lite layers.
1386
+ */
1387
+ writeEffectParams(): void;
1209
1388
  /**
1210
1389
  * Publishes the frame's sync counters.
1211
1390
  *
@@ -1277,6 +1456,17 @@ interface TileObjectContext {
1277
1456
  /** The tilemap entity the object came from, so a factory can parent to it. */
1278
1457
  readonly tilemap: Entity;
1279
1458
  }
1459
+ /**
1460
+ * A caller-owned world-space box, so reading the camera's bounds allocates nothing.
1461
+ *
1462
+ * @public
1463
+ */
1464
+ interface WorldBox {
1465
+ /** The lower corner, in world metres. */
1466
+ readonly min: MutableVec2;
1467
+ /** The upper corner, in world metres. */
1468
+ readonly max: MutableVec2;
1469
+ }
1280
1470
  /**
1281
1471
  * The 2D service.
1282
1472
  *
@@ -1379,13 +1569,10 @@ export declare class TwoDService {
1379
1569
  /**
1380
1570
  * The world-space rectangle the camera can currently see.
1381
1571
  *
1382
- * @param out - The vectors to write.
1572
+ * @param out - The box to write: its `min` takes the lower corner and its `max` the upper.
1383
1573
  * @returns `true` when a camera and a layer existed to measure against.
1384
1574
  */
1385
- visibleWorldBounds(out: {
1386
- readonly min: MutableVec2;
1387
- readonly max: MutableVec2;
1388
- }): boolean;
1575
+ visibleWorldBounds(out: WorldBox): boolean;
1389
1576
  /**
1390
1577
  * Registers the factory that turns one kind of tilemap object into an entity
1391
1578
  * (`docs/architecture/11-2d-toolkit.md` §2.5).
@@ -1498,8 +1685,11 @@ interface AnimatedTilemapSink {
1498
1685
  * It runs in `PostUpdate` — after `update`, before `PreRender` — which is where every animation in
1499
1686
  * ignifx advances, so a `lateUpdate` sees the posed frame and the render sync writes it in the same
1500
1687
  * frame it was computed. It advances every `SpriteAnimator` and every animated tile on the same
1501
- * `ctx.dt`, which is `time.deltaTime`: already scaled by `time.timeScale` and already zero while
1502
- * the app is paused.
1688
+ * `ctx.dt`, which is `time.deltaTime`, already scaled by `time.timeScale`. Systems keep running
1689
+ * while the app is paused and `dt` is **not** zeroed then (only scripts are filtered by
1690
+ * `updateWhenPaused`), so the system checks `time.paused` itself: sprite animation does not advance
1691
+ * while paused (`01-lifecycle-and-time.md` §7). Phase 6 shipped without this check and the sprites
1692
+ * kept animating under a pause menu.
1503
1693
  */
1504
1694
  /**
1505
1695
  * The `PostUpdate` order the 2D animation system runs at.
@@ -1545,13 +1735,29 @@ export declare class TwoDAnimationSystem implements System {
1545
1735
  * `SpriteAnimationManager`, so `timeScale`, pause, and frame events behave exactly as they do for
1546
1736
  * 3D animation (ADR-0003).
1547
1737
  */
1548
- /** The `format` discriminator every `.spriteanim.json` document carries. @public */
1738
+ /**
1739
+ * The `format` discriminator every `.spriteanim.json` document carries.
1740
+ *
1741
+ * @public
1742
+ */
1549
1743
  export declare const SPRITE_ANIMATION_FORMAT = "ignifx.spriteanimation";
1550
- /** The document version this build reads and writes. @public */
1744
+ /**
1745
+ * The document version this build reads and writes.
1746
+ *
1747
+ * @public
1748
+ */
1551
1749
  export declare const SPRITE_ANIMATION_FORMAT_VERSION = 1;
1552
- /** The asset type name the loader registers. @public */
1750
+ /**
1751
+ * The asset type name the loader registers.
1752
+ *
1753
+ * @public
1754
+ */
1553
1755
  export declare const SPRITE_ANIMATION_ASSET_TYPE = "spriteanimation";
1554
- /** The address suffixes that select the sprite-animation loader. @public */
1756
+ /**
1757
+ * The address suffixes that select the sprite-animation loader.
1758
+ *
1759
+ * @public
1760
+ */
1555
1761
  export declare const SPRITE_ANIMATION_FILE_EXTENSIONS: readonly string[];
1556
1762
  /**
1557
1763
  * A frame event: a name emitted on `SpriteAnimator.onEvent` when the clip reaches a frame.
@@ -1567,16 +1773,38 @@ interface SpriteAnimationEvent {
1567
1773
  /**
1568
1774
  * One clip: an ordered run of atlas frames with a rate and a loop flag.
1569
1775
  *
1776
+ * @remarks
1777
+ * A clip names its frames one of two ways, and they mean different things.
1778
+ *
1779
+ * - `frames` is an explicit **list of frame names**, played in the order written. Anything the
1780
+ * atlas does not carry is dropped, and the frames need not be adjacent in the atlas.
1781
+ * - `from`/`to` is an **index range over the atlas**, not a pair of endpoints joined by name. Both
1782
+ * names are resolved to their atlas indices and *every index between them is played*, in atlas
1783
+ * order, endpoints included. So a range whose endpoints are not adjacent in the sheet plays
1784
+ * whatever the packer happened to put between them — a `from: "run_0"`, `to: "run_5"` over an
1785
+ * atlas ordered `run_0, idle_0, run_1, …` plays `idle_0` too. Use `frames` whenever the run is
1786
+ * not contiguous in the atlas.
1787
+ * - `to` before `from` is legal and plays the range backwards.
1788
+ *
1570
1789
  * @public
1571
1790
  */
1572
1791
  interface SpriteClipDefinition {
1573
1792
  /** The clip's name, unique within the document; what `SpriteAnimator.play` takes. */
1574
1793
  readonly name: string;
1575
- /** The atlas frame names, in play order. Empty when `from`/`to` name a range instead. */
1794
+ /**
1795
+ * The atlas frame names, in play order; they need not be adjacent in the atlas. Absent or empty
1796
+ * when `from`/`to` name a range instead.
1797
+ */
1576
1798
  readonly frames?: readonly string[];
1577
- /** The first frame of a contiguous atlas range, when `frames` is absent. */
1799
+ /**
1800
+ * The atlas frame whose **index** starts the range, when `frames` is absent. The clip plays every
1801
+ * atlas index from here to `to`, so the two must bracket a contiguous run in the sheet.
1802
+ */
1578
1803
  readonly from?: string;
1579
- /** The last frame of a contiguous atlas range, inclusive. */
1804
+ /**
1805
+ * The atlas frame whose **index** ends the range, inclusive. An index below `from`'s plays the
1806
+ * range backwards.
1807
+ */
1580
1808
  readonly to?: string;
1581
1809
  /** Frames per second. Defaults to `12`. */
1582
1810
  readonly fps?: number;
@@ -1594,7 +1822,7 @@ interface SpriteAnimationDefinition {
1594
1822
  /** Always `"ignifx.spriteanimation"`. */
1595
1823
  readonly format: typeof SPRITE_ANIMATION_FORMAT;
1596
1824
  /** Always `1` in this build. */
1597
- readonly version: number;
1825
+ readonly formatVersion: number;
1598
1826
  /** The address of the `.atlas.json` the clips index into; empty uses the renderer's own atlas. */
1599
1827
  readonly atlas: string;
1600
1828
  /** The clips, in declaration order; the first is the default when the component names none. */
@@ -1609,13 +1837,17 @@ interface SpriteAnimationInput {
1609
1837
  /** Always `"ignifx.spriteanimation"` when present. */
1610
1838
  readonly format?: string;
1611
1839
  /** The document version. */
1612
- readonly version?: number;
1840
+ readonly formatVersion?: number;
1613
1841
  /** The address of the `.atlas.json` the clips index into. */
1614
1842
  readonly atlas?: string;
1615
1843
  /** The clips. */
1616
1844
  readonly clips: readonly SpriteClipDefinition[];
1617
1845
  }
1618
- /** The frames-per-second a clip that declares none plays at. @public */
1846
+ /**
1847
+ * The frames-per-second a clip that declares none plays at.
1848
+ *
1849
+ * @public
1850
+ */
1619
1851
  export declare const DEFAULT_CLIP_FPS = 12;
1620
1852
  /**
1621
1853
  * Fills in the defaults of an animation document and checks the invariants the animator relies on.
@@ -1631,6 +1863,12 @@ export declare function defineSpriteAnimation(input: SpriteAnimationInput, addre
1631
1863
  /**
1632
1864
  * Resolves a clip's frame names into atlas frame indices.
1633
1865
  *
1866
+ * @remarks
1867
+ * `frames` resolves name by name and skips what the atlas does not carry. `from`/`to` resolves both
1868
+ * endpoints to atlas **indices** and walks every index between them — ascending or descending — so
1869
+ * a range over non-adjacent frames plays everything the packer put in between
1870
+ * ({@link SpriteClipDefinition}).
1871
+ *
1634
1872
  * @param clip - The clip to resolve.
1635
1873
  * @param indexOf - Maps an atlas frame name to its index, or `-1` when the atlas has no such frame.
1636
1874
  * @returns The indices in play order; empty when the clip names nothing the atlas has.
@@ -1960,7 +2198,7 @@ export declare class SpriteAnimator extends Component implements ComponentHooks
1960
2198
  *
1961
2199
  * @remarks
1962
2200
  * `deltaSeconds` is `ctx.dt` in the `PostUpdate` phase, which is `time.deltaTime` — already
1963
- * multiplied by `time.timeScale` and already zero while the app is paused
2201
+ * multiplied by `time.timeScale`; the 2D animation system skips the call while the app is paused
1964
2202
  * (`docs/architecture/01-lifecycle-and-time.md` §2). The animator does not consult the clock
1965
2203
  * itself, which is what makes it deterministic under `app.step`.
1966
2204
  *
@@ -2070,7 +2308,7 @@ interface GridAtlasImportOptions {
2070
2308
  * Cuts an evenly spaced sprite sheet into an `ignifx.spriteatlas` document.
2071
2309
  *
2072
2310
  * Frames come out in reading order — left to right, then top to bottom — named
2073
- * `` `${namePrefix}_${index}` `` with `index` counting from `0` across the whole sheet, so a 4×2
2311
+ * `<namePrefix>_<index>` with `index` counting from `0` across the whole sheet, so a 4×2
2074
2312
  * grid ends at `tile_7`. `columns` and `rows` default to as many whole cells as the image holds
2075
2313
  * (`floor((imageWidth - 2·margin + spacing) / (cellWidth + spacing))`, and likewise for rows) and
2076
2314
  * are clamped to that capacity when given, so an over-large explicit count never produces a frame
@@ -2078,7 +2316,7 @@ interface GridAtlasImportOptions {
2078
2316
  *
2079
2317
  * @remarks
2080
2318
  * `namePrefix` is how a grid atlas lines up with the rest of the toolkit: `@ignifx/2d`'s Tiled
2081
- * importer names a tileset's frames `` `${tilesetName}_${index}` ``, so passing the tileset's name
2319
+ * importer names a tileset's frames `<tilesetName>_<index>`, so passing the tileset's name
2082
2320
  * as `namePrefix` makes a hand-cut grid atlas addressable by exactly the names a tilemap emits.
2083
2321
  *
2084
2322
  * @param options - The sheet's geometry and the frame naming.
@@ -2726,9 +2964,11 @@ export declare class TwoDSyncSystem implements System {
2726
2964
  /** The name diagnostics and error reports use. */
2727
2965
  readonly name = "ignifx/2d-sync";
2728
2966
  /**
2729
- * Builds the system.
2967
+ * Builds the system. The extension does this; a game never constructs one.
2730
2968
  *
2731
2969
  * @param runtime - The 2D runtime state: settings, the layer registry, and the Lite renderer.
2970
+ *
2971
+ * @internal
2732
2972
  */
2733
2973
  constructor(runtime: TwoDRuntime);
2734
2974
  /**
@@ -2737,6 +2977,17 @@ export declare class TwoDSyncSystem implements System {
2737
2977
  * @param ctx - The world, clock, phase, and delta.
2738
2978
  */
2739
2979
  update(ctx: SystemContext): void;
2980
+ /**
2981
+ * Connects the scene hook to a new world.
2982
+ *
2983
+ * @remarks
2984
+ * This is the only hook that fires for every world. `register` runs before the world exists and
2985
+ * `onStart` runs only when a game calls `app.start()`, so a headless tool that loads a scene
2986
+ * without ever starting a loop would otherwise never see its `settings.twoD` block.
2987
+ *
2988
+ * @param world - The new world.
2989
+ */
2990
+ onWorldCreated(world: World): void;
2740
2991
  /**
2741
2992
  * Drops every layer when the world goes away.
2742
2993
  *
@@ -2749,6 +3000,8 @@ export declare class TwoDSyncSystem implements System {
2749
3000
  *
2750
3001
  * @param world - The world to search.
2751
3002
  * @returns The camera, or `null` when the world has none enabled.
3003
+ *
3004
+ * @public
2752
3005
  */
2753
3006
  export declare function selectCamera(world: World): Camera2D | null;
2754
3007
  //#endregion
@@ -2769,7 +3022,11 @@ export declare function selectCamera(world: World): Camera2D | null;
2769
3022
  * the first sprite on its sorting layer is synced — put it in the scene file, or add it in
2770
3023
  * `awake`, not halfway through a level.
2771
3024
  */
2772
- /** The built-in effects, in the order an inspector should list them. @public */
3025
+ /**
3026
+ * The built-in effects, in the order an inspector should list them.
3027
+ *
3028
+ * @public
3029
+ */
2773
3030
  export declare const SPRITE_EFFECT_KINDS: readonly ["tint", "custom"];
2774
3031
  /**
2775
3032
  * Which shader a `SpriteLayerEffect` installs.
@@ -3234,7 +3491,7 @@ interface TilemapDefinition {
3234
3491
  /** Always `"ignifx.tilemap"`. */
3235
3492
  readonly format: typeof TILEMAP_FORMAT;
3236
3493
  /** Always `1` in this build. */
3237
- readonly version: number;
3494
+ readonly formatVersion: number;
3238
3495
  /** The width of one tile, in **pixels**. */
3239
3496
  readonly tileWidth: number;
3240
3497
  /** The height of one tile, in **pixels**. */
@@ -3305,7 +3562,7 @@ interface TilemapInput {
3305
3562
  /** Always `"ignifx.tilemap"` when present. */
3306
3563
  readonly format?: string;
3307
3564
  /** The document version. */
3308
- readonly version?: number;
3565
+ readonly formatVersion?: number;
3309
3566
  /** The width of one tile, in pixels. */
3310
3567
  readonly tileWidth: number;
3311
3568
  /** The height of one tile, in pixels. Defaults to `tileWidth`. */
@@ -3587,7 +3844,7 @@ export declare function tiledPropertiesToRecord(properties: unknown): Readonly<R
3587
3844
  * global tile id. ignifx has no per-cell flip yet, so those bits are **masked off** and the tile
3588
3845
  * draws unflipped; without the mask a flipped tile would resolve to a nonsensical tileset.
3589
3846
  *
3590
- * The frame names this importer emits are `` `${tilesetName}_${localTileIndex}` `` — the same names
3847
+ * The frame names this importer emits are `<tilesetName>_<localTileIndex>` — the same names
3591
3848
  * the grid-atlas generator gives the frames it cuts out of the tileset image, which is the contract
3592
3849
  * that lets `TilemapRenderer` look a tile's sprite up without a side table.
3593
3850
  *
@@ -3684,6 +3941,12 @@ export declare function createTilemapLoader(): AssetLoader<TilemapAsset>;
3684
3941
  * flips on the way in. `worldToCell`/`cellToWorld` are relative to the tilemap entity's own
3685
3942
  * transform, so moving the entity moves the whole map.
3686
3943
  */
3944
+ /**
3945
+ * How many cells one chunk spans by default (`docs/architecture/11-2d-toolkit.md` §2.5).
3946
+ *
3947
+ * @public
3948
+ */
3949
+ export declare const DEFAULT_CHUNK_SIZE = 32;
3687
3950
  /**
3688
3951
  * One tile change, as {@link Tilemap.onTileChanged} reports it.
3689
3952
  *
@@ -3756,7 +4019,7 @@ export declare class Tilemap extends Component implements ComponentHooks {
3756
4019
  *
3757
4020
  * @returns The signal.
3758
4021
  */
3759
- get onCollisionChanged(): Signal<void>;
4022
+ get onCollisionChanged(): Signal;
3760
4023
  /**
3761
4024
  * The loaded document, or `null` while it is still loading.
3762
4025
  *
@@ -3855,8 +4118,6 @@ export declare class Tilemap extends Component implements ComponentHooks {
3855
4118
  */
3856
4119
  invalidateCollision(): void;
3857
4120
  }
3858
- /** How many cells one chunk spans by default (`docs/architecture/11-2d-toolkit.md` §2.5). */
3859
- export declare const DEFAULT_CHUNK_SIZE = 32;
3860
4121
  //#endregion
3861
4122
  //#region src/tilemap/spawn-objects.d.ts
3862
4123
  /**
@@ -4001,5 +4262,5 @@ export declare class TilemapRenderer extends Component implements ComponentHooks
4001
4262
  */
4002
4263
  export declare const VERSION = "0.0.0";
4003
4264
  //#endregion
4004
- export type { AnimatedTilemapSink, AsepriteAnimationImportOptions, AsepriteImportOptions, CollisionMergeOptions, GridAtlasImportOptions, LdtkImportOptions, LiteAtlasTexture, LiteBounds2D, LiteSprite2DHandle, LiteSprite2DLayer, LiteSprite2DView, LiteSpriteAtlas, LiteSpriteBlendMode, LiteSpriteFrame, LiteSpritePickInfo, LiteSpriteRenderer, LiteSpriteSampling, PlayClipOptions, SpriteAnimationDefinition, SpriteAnimationEvent, SpriteAnimationInput, SpriteAsset, SpriteAtlasAssetLiteHandles, SpriteAtlasDefinition, SpriteAtlasInput, SpriteBlendName, SpriteClip, SpriteClipDefinition, SpriteEffectKind, SpriteFrameDefinition, SpriteFrameInfo, SpriteLayerEntry, SpriteLayerKey, TexturePackerImportOptions, TileAnimationFrame, TileChange, TileColliderDefinition, TileCollisionInfo, TileCollisionShape, TileDefinition, TileObjectContext, TileObjectFactory, TileRleData, TiledImportOptions, TilemapCollisionChunk, TilemapCollisionData, TilemapDefinition, TilemapInput, TilemapLayerDefinition, TilemapLayerInput, TilemapObjectDefinition, TilesetDefinition, TwoDErrorOptions, TwoDLiteHandles, TwoDMode, TwoDOptions, TwoDPick, TwoDSettings };
4265
+ export type { AnimatedTilemapSink, AsepriteAnimationImportOptions, AsepriteImportOptions, CollisionMergeOptions, GridAtlasImportOptions, LdtkImportOptions, LiteAtlasTexture, LiteBounds2D, LiteSprite2DHandle, LiteSprite2DLayer, LiteSprite2DView, LiteSpriteAtlas, LiteSpriteBlendMode, LiteSpriteFrame, LiteSpritePickInfo, LiteSpriteRenderer, LiteSpriteSampling, PlayClipOptions, SpriteAnimationDefinition, SpriteAnimationEvent, SpriteAnimationInput, SpriteAsset, SpriteAtlasAssetLiteHandles, SpriteAtlasDefinition, SpriteAtlasInput, SpriteBlendName, SpriteClip, SpriteClipDefinition, SpriteEffectKind, SpriteFrameDefinition, SpriteFrameInfo, SpriteLayerEntry, SpriteLayerKey, TexturePackerImportOptions, TileAnimationFrame, TileChange, TileColliderDefinition, TileCollisionInfo, TileCollisionShape, TileDefinition, TileObjectContext, TileObjectFactory, TileRleData, TiledImportOptions, TilemapCollisionChunk, TilemapCollisionData, TilemapDefinition, TilemapInput, TilemapLayerDefinition, TilemapLayerInput, TilemapObjectDefinition, TilesetDefinition, TwoDErrorOptions, TwoDLiteHandles, TwoDMode, TwoDOptions, TwoDPick, TwoDSettings, Vec2Json, WorldBox };
4005
4266
  //# sourceMappingURL=index.d.ts.map