@ignifx/2d 0.0.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.
@@ -0,0 +1,4005 @@
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
4
+ /**
5
+ * `Camera2D` (`docs/architecture/11-2d-toolkit.md` §2.1): the component that drives every world
6
+ * sprite layer's `Sprite2DView`.
7
+ *
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.
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
+ /**
18
+ * The 2D camera.
19
+ *
20
+ * @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.
26
+ *
27
+ * @example
28
+ * ```ts
29
+ * const camera = app.world.createEntity({ name: "camera" }).addComponent(Camera2D);
30
+ * camera.orthographicSize = 3;
31
+ * camera.pixelPerfect = true;
32
+ * ```
33
+ *
34
+ * @public
35
+ */
36
+ export declare class Camera2D extends Component {
37
+ #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
+ /**
69
+ * The zoom the camera last resolved to — `Sprite2DView.zoom`.
70
+ *
71
+ * @returns The zoom; `1` before the first sync.
72
+ */
73
+ get zoom(): number;
74
+ /**
75
+ * The viewport the camera last measured, in pixels.
76
+ *
77
+ * @returns A read-only view of the size.
78
+ */
79
+ get viewportSizePx(): Vec2Like;
80
+ /**
81
+ * The world point the camera is centred on, after bounds clamping and pixel-perfect snapping.
82
+ *
83
+ * @returns A read-only view of the centre, in metres.
84
+ */
85
+ get centre(): Vec2Like;
86
+ /**
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.
95
+ *
96
+ * @internal
97
+ */
98
+ resolve(worldX: number, worldY: number, viewportWidthPx: number, viewportHeightPx: number, pixelsPerUnit: number): void;
99
+ /**
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.
112
+ *
113
+ * @example
114
+ * ```ts
115
+ * const world = camera.screenToWorld(pointer.x, pointer.y);
116
+ * ```
117
+ */
118
+ screenToWorld(x: number, y: number, out?: MutableVec2): MutableVec2;
119
+ /**
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.
125
+ */
126
+ worldToScreen(point: Vec2Like, out?: MutableVec2): MutableVec2;
127
+ }
128
+ //#endregion
129
+ //#region src/lite/sprite-layer.d.ts
130
+ /**
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.
138
+ *
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.
141
+ *
142
+ * Everything except the blend-mode table is `@internal`.
143
+ */
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"];
146
+ /**
147
+ * How a sprite's colour combines with what is already in the framebuffer
148
+ * (`docs/architecture/11-2d-toolkit.md` §2.2).
149
+ *
150
+ * @public
151
+ */
152
+ type SpriteBlendName = (typeof SPRITE_BLEND_MODES)[number];
153
+ /**
154
+ * A reusable `Sprite2DProps` record, so a per-frame sync allocates nothing.
155
+ *
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).
160
+ *
161
+ * @internal
162
+ */
163
+ interface SpriteScratch {
164
+ /** The props object handed to `addSprite2D`/`updateSprite2D`. */
165
+ readonly props: Sprite2DProps;
166
+ }
167
+ //#endregion
168
+ //#region src/lite/types.d.ts
169
+ /**
170
+ * The Babylon Lite 2D handle types, re-exported under ignifx names so feature code outside
171
+ * `src/lite/**` can name them without importing `@babylonjs/lite`
172
+ * (`CONSTITUTION.md` §3.4, coding standards §4).
173
+ *
174
+ * Every alias here is unstable and excluded from the stability guarantees of
175
+ * `CONSTITUTION.md` Article IV; they exist for the `.lite` escape hatches only.
176
+ */
177
+ /**
178
+ * Lite's sprite rendering context — the second rendering context `@ignifx/2d` registers on the
179
+ * app's surface, after the render scene, so 2D composites on top (`index.d.ts` 12215).
180
+ *
181
+ * @remarks
182
+ * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
183
+ *
184
+ * @public
185
+ */
186
+ type LiteSpriteRenderer = SpriteRenderer$1;
187
+ /**
188
+ * One ordered batch of sprites drawn from a single atlas with a single blend mode
189
+ * (`index.d.ts` 11885).
190
+ *
191
+ * @remarks
192
+ * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
193
+ *
194
+ * @public
195
+ */
196
+ type LiteSprite2DLayer = Sprite2DLayer;
197
+ /**
198
+ * A stable identity for one sprite that survives Lite's swap-remove reindexing
199
+ * (`index.d.ts` 11880).
200
+ *
201
+ * @remarks
202
+ * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
203
+ *
204
+ * @public
205
+ */
206
+ type LiteSprite2DHandle = Sprite2DHandle;
207
+ /**
208
+ * A layer's 2D camera: pan, zoom, and rotation in Lite's pixel space (`index.d.ts` 11988).
209
+ *
210
+ * @remarks
211
+ * `positionPx` is the layer-pixel point that lands at the **top-left** of the viewport, not the
212
+ * centre — verified against `sprite2DWorldToScreenToRef` in `lib/sprite/sprite-2d-view.js`.
213
+ *
214
+ * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
215
+ *
216
+ * @public
217
+ */
218
+ type LiteSprite2DView = Sprite2DView;
219
+ /**
220
+ * A loaded atlas: one texture plus the frame rectangles inside it (`index.d.ts` 12041).
221
+ *
222
+ * @remarks
223
+ * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
224
+ *
225
+ * @public
226
+ */
227
+ type LiteSpriteAtlas = SpriteAtlas;
228
+ /**
229
+ * One frame of an atlas: UVs in `[0, 1]`, source size in pixels, and a pivot (`index.d.ts` 12156).
230
+ *
231
+ * @remarks
232
+ * The `pivot` field is **stored but not applied** by the `Sprite2DLayer` pipeline; only Lite's
233
+ * billboard family reads it. `@ignifx/2d` applies it itself — see `pivotedPositionToRef`.
234
+ *
235
+ * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
236
+ *
237
+ * @public
238
+ */
239
+ type LiteSpriteFrame = SpriteFrame;
240
+ /**
241
+ * An opaque blend-mode descriptor (`index.d.ts` 12122).
242
+ *
243
+ * @remarks
244
+ * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
245
+ *
246
+ * @public
247
+ */
248
+ type LiteSpriteBlendMode = SpriteBlendMode;
249
+ /**
250
+ * A sprite atlas's min/mag filter (`index.d.ts` 12229).
251
+ *
252
+ * @remarks
253
+ * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
254
+ *
255
+ * @public
256
+ */
257
+ type LiteSpriteSampling = SpriteSampling;
258
+ /**
259
+ * A `pickSprite2D` hit: the layer, the dense sprite index, and the within-quad UV
260
+ * (`index.d.ts` 12179).
261
+ *
262
+ * @remarks
263
+ * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
264
+ *
265
+ * @public
266
+ */
267
+ type LiteSpritePickInfo = SpritePickInfo;
268
+ /**
269
+ * Mutable axis-aligned 2D bounds, the shape `getSprite2DVisibleBoundsToRef` writes
270
+ * (`index.d.ts` 1352).
271
+ *
272
+ * @remarks
273
+ * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
274
+ *
275
+ * @public
276
+ */
277
+ type LiteBounds2D = Bounds2D;
278
+ /**
279
+ * The GPU texture behind an atlas (`index.d.ts` 12907).
280
+ *
281
+ * @remarks
282
+ * Unstable; excluded from the stability guarantees of `CONSTITUTION.md` Article IV.
283
+ *
284
+ * @public
285
+ */
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;
390
+ /**
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.
395
+ *
396
+ * @example
397
+ * ```ts
398
+ * parseSpriteFragment("frame:idle_0"); // "idle_0"
399
+ * ```
400
+ *
401
+ * @public
402
+ */
403
+ export declare function parseSpriteFragment(fragment: string | null): string | null;
404
+ //#endregion
405
+ //#region src/atlas/sprite-atlas-asset.d.ts
406
+ /**
407
+ * The value a `.atlas.json` address loads to: the parsed document, the Lite `SpriteAtlas` built
408
+ * from it, and a name-to-index map so `#frame:` addressing is a hash lookup rather than a scan
409
+ * (`docs/architecture/11-2d-toolkit.md` §2.3).
410
+ */
411
+ /**
412
+ * The Babylon Lite objects a {@link SpriteAtlasAsset} owns.
413
+ *
414
+ * @public
415
+ */
416
+ interface SpriteAtlasAssetLiteHandles {
417
+ /** The Lite atlas, or `null` under a headless app, which uploads nothing. */
418
+ readonly atlas: LiteSpriteAtlas | null;
419
+ }
420
+ /**
421
+ * One frame of a loaded atlas, as game code sees it.
422
+ *
423
+ * @public
424
+ */
425
+ interface SpriteFrameInfo {
426
+ /** The frame's name. */
427
+ readonly name: string;
428
+ /** Its index in the atlas, which is what Lite addresses frames by. */
429
+ readonly index: number;
430
+ /** Its drawn width, in image pixels. */
431
+ readonly widthPx: number;
432
+ /** Its drawn height, in image pixels. */
433
+ readonly heightPx: number;
434
+ /** Its pivot in `[0, 1]` of the frame, `[0, 0]` top-left. */
435
+ readonly pivot: Vec2Like;
436
+ }
437
+ /**
438
+ * A loaded sprite atlas.
439
+ *
440
+ * @remarks
441
+ * Under a headless app the document is parsed and every frame is queryable, but `lite.atlas` is
442
+ * `null` — nothing is uploaded (`docs/architecture/07-rendering.md` §6). That is what lets a
443
+ * headless test assert frame counts, pivots, and animation timing without a GPU.
444
+ *
445
+ * @example
446
+ * ```ts
447
+ * const handle = app.assets.load<SpriteAtlasAsset>("2d/hero.atlas.json");
448
+ * const atlas = await handle.promise;
449
+ * atlas.frameIndex("idle_0"); // 0
450
+ * ```
451
+ *
452
+ * @public
453
+ */
454
+ export declare class SpriteAtlasAsset {
455
+ #private;
456
+ /** The type name the asset service registers sprite atlases under. */
457
+ static assetType: string;
458
+ /** The address the atlas was loaded from. */
459
+ readonly address: string;
460
+ /** The parsed `.atlas.json` document. */
461
+ readonly definition: SpriteAtlasDefinition;
462
+ /**
463
+ * Wraps a parsed atlas. The `spriteatlas` loader constructs these.
464
+ *
465
+ * @param address - The address it was loaded from.
466
+ * @param definition - The parsed document.
467
+ * @param atlas - The Lite atlas, or `null` under a headless app.
468
+ * @param release - Frees the GPU texture, or `null` when there is nothing to free.
469
+ *
470
+ * @internal
471
+ */
472
+ constructor(address: string, definition: SpriteAtlasDefinition, atlas: LiteSpriteAtlas | null, release: (() => void) | null);
473
+ /**
474
+ * The Babylon Lite objects the asset owns. Unstable escape hatch
475
+ * (`CONSTITUTION.md` §3.4).
476
+ *
477
+ * @returns The Lite atlas, or `null` under a headless app.
478
+ */
479
+ get lite(): SpriteAtlasAssetLiteHandles;
480
+ /**
481
+ * How many frames the atlas declares.
482
+ *
483
+ * @returns The frame count.
484
+ */
485
+ get frameCount(): number;
486
+ /**
487
+ * Looks a frame up by name.
488
+ *
489
+ * @param name - The frame name.
490
+ * @returns The index, or `-1` when the atlas has no such frame.
491
+ */
492
+ frameIndex(name: string): number;
493
+ /**
494
+ * Looks a frame up by name and refuses to guess.
495
+ *
496
+ * @param name - The frame name.
497
+ * @returns The index.
498
+ * @throws IgnifxError with code `IGX-1106` when the atlas declares no such frame.
499
+ */
500
+ requireFrame(name: string): number;
501
+ /**
502
+ * Every frame name, in index order.
503
+ *
504
+ * @returns A freshly allocated array.
505
+ */
506
+ frameNames(): readonly string[];
507
+ /**
508
+ * Describes one frame.
509
+ *
510
+ * @param index - The frame index.
511
+ * @returns The frame, or `null` when the index is out of range.
512
+ */
513
+ frame(index: number): SpriteFrameInfo | null;
514
+ /**
515
+ * The Lite frame record, for the sync system.
516
+ *
517
+ * @param index - The frame index.
518
+ * @returns The record, or `null` under a headless app or for an out-of-range index.
519
+ *
520
+ * @internal
521
+ */
522
+ liteFrame(index: number): LiteSpriteFrame | null;
523
+ /**
524
+ * Whether the atlas was uploaded to a device at all.
525
+ *
526
+ * @returns `true` once the GPU texture has been given up, or under a headless app.
527
+ */
528
+ get isReleased(): boolean;
529
+ /**
530
+ * Frees the GPU texture. The asset service calls this on unload.
531
+ *
532
+ * @internal
533
+ */
534
+ releaseGpu(): void;
535
+ }
536
+ /**
537
+ * A sprite: one frame of one atlas, which is what `SpriteRenderer.sprite` points at.
538
+ *
539
+ * @remarks
540
+ * A bare `"2d/hero.atlas.json"` address resolves to frame `0`; the `#frame:` fragment picks another
541
+ * (`docs/architecture/11-2d-toolkit.md` §2.2). The asset service shares the underlying atlas
542
+ * between every fragment of the same address, so ten sprites off one atlas upload one texture.
543
+ *
544
+ * @public
545
+ */
546
+ interface SpriteAsset {
547
+ /** The atlas the frame lives in. */
548
+ readonly atlas: SpriteAtlasAsset;
549
+ /** The frame index. */
550
+ readonly frame: number;
551
+ /** The frame's name. */
552
+ readonly name: string;
553
+ }
554
+ //#endregion
555
+ //#region src/sprite/sprite-renderer.d.ts
556
+ /**
557
+ * `SpriteRenderer` (`docs/architecture/11-2d-toolkit.md` §2.2): one sprite drawn from one frame of
558
+ * one atlas.
559
+ *
560
+ * The component holds a single Lite sprite handle inside the layer that matches its
561
+ * (sorting layer, atlas, blend mode, screen-space) key. It creates nothing itself: the 2D sync
562
+ * system owns every layer, so the component only records which layer it belongs in and lets the
563
+ * system reconcile that against the layer it is currently in.
564
+ */
565
+ /**
566
+ * The layer key a sprite belongs to.
567
+ *
568
+ * @remarks
569
+ * Two sprites share a Lite layer exactly when all four parts match. The atlas is part of the key
570
+ * because a `Sprite2DLayer` is bound to one atlas for its whole life (`index.d.ts` 11885,
571
+ * `readonly atlas`), and the blend mode is part of it for the same reason (`readonly blendMode`).
572
+ *
573
+ * @public
574
+ */
575
+ interface SpriteLayerKey {
576
+ /** The sorting layer's name. */
577
+ readonly sortingLayer: string;
578
+ /** The atlas every sprite in the layer draws from. */
579
+ readonly atlas: SpriteAtlasAsset;
580
+ /** The blend mode. */
581
+ readonly blend: SpriteBlendName;
582
+ /** Whether the layer keeps the identity view instead of following the `Camera2D`. */
583
+ readonly screenSpace: boolean;
584
+ }
585
+ /**
586
+ * A sprite.
587
+ *
588
+ * @remarks
589
+ * The `sprite` field is an atlas handle; the frame inside it comes from the address's `#frame:`
590
+ * fragment when there is one, and otherwise from {@link SpriteRenderer.frame}, which game code and
591
+ * `SpriteAnimator` both write. A sprite whose atlas has not finished loading draws nothing and
592
+ * costs nothing.
593
+ *
594
+ * @example
595
+ * ```ts
596
+ * const hero = app.world.createEntity({ name: "hero" });
597
+ * const sprite = hero.addComponent(SpriteRenderer);
598
+ * sprite.sprite = app.assets.load<SpriteAtlasAsset>("2d/hero.atlas.json").retain();
599
+ * sprite.sortingLayer = "Default";
600
+ * ```
601
+ *
602
+ * @public
603
+ */
604
+ export declare class SpriteRenderer extends Component implements ComponentHooks {
605
+ #private;
606
+ /** The registration id the serializer writes into scene files. */
607
+ static typeId: string;
608
+ /** Several sprites may share an entity — a character and its shadow, for instance. */
609
+ static allowMultiple: boolean;
610
+ /** The declarative fields (ADR-0004). */
611
+ static schema: Schema;
612
+ /** The atlas this sprite draws a frame of. */
613
+ sprite: AssetHandle<SpriteAtlasAsset> | null;
614
+ /** The tint multiplied into every texel. */
615
+ color: ColorLike;
616
+ /** Whether the sprite is mirrored horizontally. */
617
+ flipX: boolean;
618
+ /** Whether the sprite is mirrored vertically. */
619
+ flipY: boolean;
620
+ /** Which sorting layer the sprite draws on. */
621
+ sortingLayer: string;
622
+ /** The sub-order within the sorting layer; higher draws in front. */
623
+ orderInLayer: number;
624
+ /** How the sprite's colour combines with what is behind it. */
625
+ blend: SpriteBlendName;
626
+ /** The pivot in `[0, 1]` of the frame, overriding the frame's own; `null` uses the frame's. */
627
+ pivotOverride: Vec2Like | null;
628
+ /** Whether the sprite keeps the identity view instead of following the `Camera2D`. */
629
+ screenSpace: boolean;
630
+ /** Whether `app.twoD.pickAt` considers this sprite. */
631
+ pickable: boolean;
632
+ /**
633
+ * Builds a sprite with the schema's defaults.
634
+ */
635
+ constructor();
636
+ /**
637
+ * Resets the sync shadow state, so a recycled component does not inherit the previous one's.
638
+ */
639
+ onAttach(): void;
640
+ /**
641
+ * Marks the sprite for removal from its layer. The sync system does the removal, because it owns
642
+ * the layer.
643
+ */
644
+ onDetach(): void;
645
+ /**
646
+ * The atlas frame drawn.
647
+ *
648
+ * @returns The frame index.
649
+ */
650
+ get frame(): number;
651
+ set frame(value: number);
652
+ /**
653
+ * The Babylon Lite objects the component uses. Unstable escape hatch
654
+ * (`CONSTITUTION.md` §3.4).
655
+ *
656
+ * @returns The sprite handle, or `null` when the sprite is not in a layer.
657
+ */
658
+ get lite(): {
659
+ readonly sprite: LiteSprite2DHandle | null;
660
+ };
661
+ /**
662
+ * The sprite's world-space axis-aligned bounding box, for coarse queries
663
+ * (`docs/architecture/11-2d-toolkit.md` §5).
664
+ *
665
+ * @remarks
666
+ * The box is the one the last sync computed, so it is a frame behind a sprite that has just
667
+ * moved, and it is the origin-sized empty box until the sprite has been synced once. It ignores
668
+ * rotation: a rotated sprite reports the box of its unrotated quad, which is the cheap
669
+ * conservative answer only for rotations that are multiples of a quarter turn.
670
+ *
671
+ * @returns A freshly allocated box in world metres.
672
+ */
673
+ get bounds(): {
674
+ readonly min: Vec2Like;
675
+ readonly max: Vec2Like;
676
+ };
677
+ /**
678
+ * The loaded atlas, or `null` while it is still loading or failed.
679
+ *
680
+ * @returns The atlas.
681
+ */
682
+ get atlas(): SpriteAtlasAsset | null;
683
+ /**
684
+ * Whether anything about this sprite needs writing to Lite this frame.
685
+ *
686
+ * @param isStatic - Whether the owning entity is marked static.
687
+ * @param matrixVersion - The entity transform's `worldMatrixVersion`.
688
+ * @returns `true` when the sync system must write the sprite.
689
+ *
690
+ * @internal
691
+ */
692
+ needsSync(isStatic: boolean, matrixVersion: number): boolean;
693
+ /**
694
+ * Records that the sync system has written this sprite.
695
+ *
696
+ * @param isStatic - Whether the owning entity is marked static.
697
+ * @param matrixVersion - The transform version written at.
698
+ * @param minX - The world AABB, in metres.
699
+ * @param minY - The world AABB, in metres.
700
+ * @param maxX - The world AABB, in metres.
701
+ * @param maxY - The world AABB, in metres.
702
+ *
703
+ * @internal
704
+ */
705
+ markSynced(isStatic: boolean, matrixVersion: number, minX: number, minY: number, maxX: number, maxY: number): void;
706
+ /**
707
+ * Forces the next sync to rewrite this sprite.
708
+ *
709
+ * @internal
710
+ */
711
+ invalidate(): void;
712
+ /**
713
+ * The Lite handle and the key of the layer holding it.
714
+ *
715
+ * @returns The placement, or `null` when the sprite is not in a layer.
716
+ *
717
+ * @internal
718
+ */
719
+ placement(): {
720
+ readonly handle: LiteSprite2DHandle;
721
+ readonly key: string;
722
+ } | null;
723
+ /**
724
+ * Records the layer the sync system put this sprite in.
725
+ *
726
+ * @param handle - The Lite handle, or `null` when the sprite was removed.
727
+ * @param key - The layer key, or `null`.
728
+ *
729
+ * @internal
730
+ */
731
+ setPlacement(handle: LiteSprite2DHandle | null, key: string | null): void;
732
+ }
733
+ //#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
+ //#region src/service/layer-registry.d.ts
808
+ /**
809
+ * One Lite layer and everything the registry tracks alongside it.
810
+ *
811
+ * @public
812
+ */
813
+ interface SpriteLayerEntry {
814
+ /** The composite key: `` `${sortingLayer}|${atlasAddress}|${blend}|${space}` ``. */
815
+ readonly key: string;
816
+ /** The sorting layer's name. */
817
+ readonly sortingLayer: string;
818
+ /** The Lite layer. */
819
+ readonly layer: LiteSprite2DLayer;
820
+ /** Whether the layer keeps the identity view instead of following the `Camera2D`. */
821
+ readonly screenSpace: boolean;
822
+ /** How many sprites the layer currently holds. */
823
+ readonly count: number;
824
+ /** Whether the layer is Y-sorted. */
825
+ readonly ySort: boolean;
826
+ }
827
+ /**
828
+ * Builds the composite key two sprites must share to land in one Lite layer.
829
+ *
830
+ * @param sortingLayer - The sorting layer's name.
831
+ * @param atlasAddress - The atlas's address.
832
+ * @param blend - The blend mode.
833
+ * @param screenSpace - Whether the layer ignores the camera.
834
+ * @returns The key.
835
+ *
836
+ * @public
837
+ */
838
+ export declare function spriteLayerKey(sortingLayer: string, atlasAddress: string, blend: SpriteBlendName, screenSpace: boolean): string;
839
+ /**
840
+ * Owns every Lite sprite layer in one app.
841
+ *
842
+ * @public
843
+ */
844
+ export declare class SpriteLayerRegistry {
845
+ #private;
846
+ /**
847
+ * Builds the registry.
848
+ *
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.
853
+ */
854
+ constructor(sortingLayers: SortingLayerTable, ySort: Readonly<Record<string, boolean>>, onLayerCreated: (layer: LiteSprite2DLayer) => void, onLayerRemoved: (layer: LiteSprite2DLayer) => void);
855
+ /**
856
+ * Every layer, in draw order.
857
+ *
858
+ * @returns A freshly allocated snapshot, for diagnostics.
859
+ */
860
+ describe(): readonly SpriteLayerEntry[];
861
+ /**
862
+ * The Lite layers, in draw order — what picking tests against.
863
+ *
864
+ * @param worldOnly - Whether to skip screen-space layers.
865
+ * @param out - The array to fill; it is emptied first, so one array serves every frame.
866
+ * @returns `out`.
867
+ */
868
+ collectLayers(worldOnly: boolean, out: LiteSprite2DLayer[]): LiteSprite2DLayer[];
869
+ /**
870
+ * Walks every layer's view, so the camera can write world layers and skip screen-space ones.
871
+ *
872
+ * @param visit - Called with each layer and whether it follows the camera.
873
+ *
874
+ * @internal
875
+ */
876
+ forEachLayer(visit: (layer: LiteSprite2DLayer, screenSpace: boolean) => void): void;
877
+ /**
878
+ * Adds a sprite to the layer its key selects, creating the layer when it is the first of its kind.
879
+ *
880
+ * @param component - The sprite component.
881
+ * @param atlas - Its loaded atlas.
882
+ * @param scratch - The reusable props record, already written.
883
+ * @returns The key of the layer the sprite landed in.
884
+ *
885
+ * @internal
886
+ */
887
+ place(component: SpriteRenderer, atlas: SpriteAtlasAsset, scratch: SpriteScratch): string;
888
+ /**
889
+ * Removes a sprite from whichever layer holds it.
890
+ *
891
+ * @param component - The sprite component.
892
+ *
893
+ * @internal
894
+ */
895
+ remove(component: SpriteRenderer): void;
896
+ /**
897
+ * Adds a sprite that no `SpriteRenderer` owns — a tilemap's tiles.
898
+ *
899
+ * @remarks
900
+ * The sprite occupies a slot in the same layers component-owned sprites use, so it sorts and
901
+ * Y-sorts alongside them, but its slot in the pick map stays empty: `app.twoD.pickAt` resolves
902
+ * `SpriteRenderer` components, and a tile is not one. Pick a tile with `Tilemap.worldToCell`
903
+ * instead, which is exact and costs no draw-order search.
904
+ *
905
+ * @param sortingLayer - The sorting layer's name.
906
+ * @param atlas - The atlas the sprite draws from.
907
+ * @param blend - The blend mode.
908
+ * @param screenSpace - Whether the layer ignores the camera.
909
+ * @param scratch - The reusable props record, already written.
910
+ * @returns The key and the handle.
911
+ *
912
+ * @internal
913
+ */
914
+ placeRaw(sortingLayer: string, atlas: SpriteAtlasAsset, blend: SpriteBlendName, screenSpace: boolean, scratch: SpriteScratch): {
915
+ readonly key: string;
916
+ readonly handle: LiteSprite2DHandle;
917
+ };
918
+ /**
919
+ * Removes a sprite added by {@link SpriteLayerRegistry.placeRaw}.
920
+ *
921
+ * @param key - The key the sprite was placed under.
922
+ * @param handle - The handle.
923
+ *
924
+ * @internal
925
+ */
926
+ removeRaw(key: string, handle: LiteSprite2DHandle): void;
927
+ /**
928
+ * Resolves a pick hit back to the component that owns the sprite.
929
+ *
930
+ * @param layer - The Lite layer the hit is in.
931
+ * @param spriteIndex - The dense index the hit reports.
932
+ * @returns The component, or `null` when the slot is unmapped.
933
+ *
934
+ * @internal
935
+ */
936
+ componentAt(layer: LiteSprite2DLayer, spriteIndex: number): SpriteRenderer | null;
937
+ /**
938
+ * Empties every layer and drops them all.
939
+ *
940
+ * @internal
941
+ */
942
+ clear(): void;
943
+ }
944
+ //#endregion
945
+ //#region src/sprite/parallax-layer.d.ts
946
+ /**
947
+ * `ParallaxLayer` (`docs/architecture/11-2d-toolkit.md` §2.6): makes one sorting layer scroll at a
948
+ * fraction of the camera's speed, which is what gives a side-scroller depth.
949
+ *
950
+ * The component owns no sprites. It reaches into the views of every Lite layer belonging to its
951
+ * sorting layer, after the 2D sync system has written the camera's view onto them, and slides each
952
+ * one back by `cameraPositionPx × (1 − factor)`. A factor of `1` moves with the camera (no
953
+ * parallax); `0` is pinned to the world origin, which is what a distant sky wants.
954
+ */
955
+ /**
956
+ * A parallax layer.
957
+ *
958
+ * @example
959
+ * ```ts
960
+ * const sky = app.world.createEntity({ name: "sky" }).addComponent(ParallaxLayer);
961
+ * sky.sortingLayer = "Background";
962
+ * sky.factor = { x: 0.2, y: 0.5 };
963
+ * ```
964
+ *
965
+ * @public
966
+ */
967
+ export declare class ParallaxLayer extends Component {
968
+ #private;
969
+ /** The registration id the serializer writes into scene files. */
970
+ static typeId: string;
971
+ /** One parallax setting per entity; several entities may each drive a different sorting layer. */
972
+ static allowMultiple: boolean;
973
+ /** The declarative fields (ADR-0004). */
974
+ static schema: Schema;
975
+ /** Which sorting layer this component slows down. */
976
+ sortingLayer: string;
977
+ /** How much of the camera's motion the layer follows, per axis; `1` is no parallax. */
978
+ factor: Vec2Like;
979
+ /** Whether the layer's sprites repeat horizontally across the camera's view. */
980
+ repeatX: boolean;
981
+ /** Whether the layer's sprites repeat vertically. */
982
+ repeatY: boolean;
983
+ /** The world width one repetition spans, in metres; `0` disables horizontal repetition. */
984
+ repeatWidth: number;
985
+ /** The world height one repetition spans, in metres. */
986
+ repeatHeight: number;
987
+ /**
988
+ * Builds a parallax layer with the schema's defaults.
989
+ */
990
+ constructor();
991
+ /**
992
+ * Slides every matching layer's view.
993
+ *
994
+ * @remarks
995
+ * Runs after the camera has written its own view, so the arithmetic is a pure offset:
996
+ * `view.positionPx -= cameraPx × (1 − factor)`. With `repeatX`/`repeatY` the offset is taken
997
+ * modulo one repetition, which keeps a tiled backdrop from drifting away from the camera no
998
+ * matter how far the player walks — and keeps the number in single-precision range.
999
+ *
1000
+ * @param entries - Every layer, as the registry describes them.
1001
+ * @param camera - The active camera.
1002
+ * @param pixelsPerUnit - The pixels one metre spans.
1003
+ *
1004
+ * @internal
1005
+ */
1006
+ applyTo(entries: readonly SpriteLayerEntry[], camera: Camera2D, pixelsPerUnit: number): void;
1007
+ }
1008
+ //#endregion
1009
+ //#region src/settings.d.ts
1010
+ /**
1011
+ * The `twoD` project settings section (`docs/architecture/04-extensions.md` §5,
1012
+ * `11-2d-toolkit.md` §1 and §7). Everything here is what a game writes in `ignifx.config.ts` or in
1013
+ * a scene file's `settings.twoD` block; the knobs a game changes per frame live on `app.twoD` and
1014
+ * on `Camera2D` instead.
1015
+ */
1016
+ /**
1017
+ * The section name as it appears in `ignifx.config.ts` and in a scene file's `settings` block.
1018
+ *
1019
+ * @public
1020
+ */
1021
+ export declare const TWO_D_SETTINGS_SECTION = "twoD";
1022
+ /**
1023
+ * Every rendering mode the 2D toolkit supports, in the order an inspector should list them
1024
+ * (`docs/architecture/11-2d-toolkit.md` §1).
1025
+ *
1026
+ * @public
1027
+ */
1028
+ export declare const TWO_D_MODES: readonly ["sprite", "mixed"];
1029
+ /**
1030
+ * How 2D composites with the 3D render scene.
1031
+ *
1032
+ * @remarks
1033
+ * `"sprite"` is a pure 2D game: sprites are the only thing drawn. `"mixed"` is 2.5D — the render
1034
+ * scene draws first and the sprite pass composites on top without clearing, so meshes and sprites
1035
+ * share a frame.
1036
+ *
1037
+ * @public
1038
+ */
1039
+ type TwoDMode = (typeof TWO_D_MODES)[number];
1040
+ /**
1041
+ * The resolved `twoD` settings section.
1042
+ *
1043
+ * @example
1044
+ * ```ts
1045
+ * // ignifx.config.ts
1046
+ * export default defineConfig({
1047
+ * sortingLayers: { sortingLayers: ["Background", "Default", "Foreground"] },
1048
+ * twoD: { mode: "sprite", pixelsPerUnit: 16, ySort: { Default: true } },
1049
+ * });
1050
+ * ```
1051
+ *
1052
+ * @public
1053
+ */
1054
+ interface TwoDSettings {
1055
+ /** Whether sprites are the whole frame (`"sprite"`) or composite over the 3D scene (`"mixed"`). */
1056
+ readonly mode: TwoDMode;
1057
+ /** How many pixels one world metre spans. Defaults to `100`. */
1058
+ readonly pixelsPerUnit: number;
1059
+ /**
1060
+ * Which sorting layers draw back-to-front by world Y rather than by `orderInLayer`. A layer the
1061
+ * record does not mention does not Y-sort.
1062
+ */
1063
+ readonly ySort: Readonly<Record<string, boolean>>;
1064
+ }
1065
+ /**
1066
+ * The values used for everything a project omits.
1067
+ *
1068
+ * @returns The default `twoD` section.
1069
+ *
1070
+ * @public
1071
+ */
1072
+ export declare function defaultTwoDSettings(): TwoDSettings;
1073
+ /**
1074
+ * The schema the `twoD` section is validated against, in `ignifx.config.ts` and in a scene file
1075
+ * alike.
1076
+ *
1077
+ * @returns The schema, built fresh so no module holds state (`CONSTITUTION.md` §3.5).
1078
+ *
1079
+ * @public
1080
+ */
1081
+ export declare function twoDSettingsSchema(): Schema;
1082
+ //#endregion
1083
+ //#region src/service/runtime.d.ts
1084
+ /**
1085
+ * The mutable state one app's 2D toolkit carries between frames: the resolved settings, the layer
1086
+ * registry, the Lite sprite renderer, and the active camera.
1087
+ *
1088
+ * It exists as its own object rather than as fields on the service because the sync system, the
1089
+ * animation system, and the service all need it, and none of them owns the others.
1090
+ *
1091
+ * ## Why the renderer is created lazily
1092
+ *
1093
+ * Lite requires the sprite renderer to be registered **after** `registerScene`, so that it
1094
+ * composites on top (`index.d.ts` 12205-12209). `@ignifx/core` registers the render scene inside
1095
+ * `app.start()`, *after* every extension's `onStart` has already run, and emits no signal when it
1096
+ * does — `RendererImpl.isSceneRegistered` is internal. So there is no hook an extension can use.
1097
+ * {@link TwoDRuntime.ensureRenderer} closes that gap: the sync system calls it at the top of every
1098
+ * `PreRender`, and the first such call happens inside Lite's own frame callback, which only runs
1099
+ * once the scene is registered and the loop is going.
1100
+ */
1101
+ /**
1102
+ * The Babylon Lite objects `app.twoD` owns.
1103
+ *
1104
+ * @public
1105
+ */
1106
+ interface TwoDLiteHandles {
1107
+ /** The sprite rendering context, or `null` under a headless app or before the first frame. */
1108
+ readonly renderer: LiteSpriteRenderer | null;
1109
+ }
1110
+ /**
1111
+ * What {@link TwoDRuntime} needs to build itself.
1112
+ *
1113
+ * @internal
1114
+ */
1115
+ interface TwoDRuntimeOptions {
1116
+ /** The app the runtime belongs to. */
1117
+ readonly app: App;
1118
+ /** The resolved `twoD` settings, options merged over the section. */
1119
+ readonly settings: TwoDSettings;
1120
+ /** The project's sorting layers, back to front. */
1121
+ readonly sortingLayers: readonly string[];
1122
+ /** Creates and registers the Lite sprite renderer; `null` under a headless app. */
1123
+ readonly createRenderer: (() => LiteSpriteRenderer) | null;
1124
+ /** Adds a layer to the renderer's draw list. */
1125
+ readonly attachLayer: (renderer: LiteSpriteRenderer, layer: LiteSprite2DLayer) => void;
1126
+ /** Removes a layer from the renderer's draw list. */
1127
+ readonly detachLayer: (renderer: LiteSpriteRenderer, layer: LiteSprite2DLayer) => void;
1128
+ /** Tears the renderer down. */
1129
+ readonly destroyRenderer: (renderer: LiteSpriteRenderer) => void;
1130
+ }
1131
+ /**
1132
+ * One app's 2D runtime state.
1133
+ *
1134
+ * @internal
1135
+ */
1136
+ declare class TwoDRuntime {
1137
+ #private;
1138
+ /**
1139
+ * Builds the runtime.
1140
+ *
1141
+ * @param options - The app, the settings, the sorting layers, and the Lite hooks.
1142
+ */
1143
+ constructor(options: TwoDRuntimeOptions);
1144
+ /** The resolved settings. */
1145
+ get settings(): TwoDSettings;
1146
+ /** How many pixels one world metre spans. */
1147
+ get pixelsPerUnit(): number;
1148
+ /** The sorting-layer resolver. */
1149
+ get sortingLayers(): SortingLayerTable;
1150
+ /** The layer pool. */
1151
+ get layers(): SpriteLayerRegistry;
1152
+ /** The Lite sprite renderer, or `null`. */
1153
+ get renderer(): LiteSpriteRenderer | null;
1154
+ /** The camera the last frame drew through, or `null`. */
1155
+ get mainCamera(): Camera2D | null;
1156
+ /** How many sprites the last frame actually wrote to Lite. */
1157
+ get syncedLastFrame(): number;
1158
+ /** How many `SpriteRenderer` components the last frame walked. */
1159
+ get spriteCount(): number;
1160
+ /** The surface width the views are sized against, in pixels. */
1161
+ get viewportWidthPx(): number;
1162
+ /** The surface height the views are sized against, in pixels. */
1163
+ get viewportHeightPx(): number;
1164
+ /**
1165
+ * Replaces the settings, which a scene file's `settings.twoD` block does at load time.
1166
+ *
1167
+ * @param settings - The new settings.
1168
+ */
1169
+ applySettings(settings: TwoDSettings): void;
1170
+ /**
1171
+ * Records the frame's camera.
1172
+ *
1173
+ * @param camera - The camera, or `null`.
1174
+ */
1175
+ setMainCamera(camera: Camera2D | null): void;
1176
+ /**
1177
+ * Records the parallax components the sync system should offset views for.
1178
+ *
1179
+ * @param layers - The components.
1180
+ */
1181
+ setParallaxLayers(layers: readonly ParallaxLayer[]): void;
1182
+ /**
1183
+ * Offsets each parallax layer's view by the camera's motion times `1 - factor`
1184
+ * (`docs/architecture/11-2d-toolkit.md` §2.6).
1185
+ */
1186
+ applyParallax(): void;
1187
+ /**
1188
+ * The layer-pixel rectangle the camera can currently see, for chunk culling.
1189
+ *
1190
+ * @remarks
1191
+ * Read off the first world layer's view, which the sync system has already written this frame.
1192
+ * Every world layer carries the same view, so any of them answers; `null` means there is no world
1193
+ * layer yet, in which case a tilemap builds every chunk and culls from the next frame on.
1194
+ *
1195
+ * @returns The bounds, or `null`.
1196
+ */
1197
+ cameraBounds(): LiteBounds2D | null;
1198
+ /**
1199
+ * Advances every animated tile on the 2D animation clock.
1200
+ *
1201
+ * @remarks
1202
+ * Implements `AnimatedTilemapSink`, which is what lets the animation system drive tilemaps
1203
+ * without importing the renderer.
1204
+ *
1205
+ * @param world - The world holding the tilemaps.
1206
+ * @param deltaSeconds - The scaled frame delta.
1207
+ */
1208
+ advanceAnimatedTiles(world: World, deltaSeconds: number): void;
1209
+ /**
1210
+ * Publishes the frame's sync counters.
1211
+ *
1212
+ * @param synced - How many sprites were written.
1213
+ * @param total - How many sprite components were walked.
1214
+ */
1215
+ reportSynced(synced: number, total: number): void;
1216
+ /**
1217
+ * Creates and registers the Lite sprite renderer, once, on the first frame that can.
1218
+ *
1219
+ * @remarks
1220
+ * Idempotent, and a no-op under a headless app or once a first attempt has failed. See the
1221
+ * module's own remarks for why this cannot happen in `onStart`.
1222
+ */
1223
+ ensureRenderer(): void;
1224
+ /**
1225
+ * Drops every layer and the renderer.
1226
+ */
1227
+ dispose(): void;
1228
+ }
1229
+ //#endregion
1230
+ //#region src/service/two-d-service.d.ts
1231
+ /**
1232
+ * `app.twoD` (`docs/architecture/11-2d-toolkit.md` §1 and §5): the 2D toolkit's runtime surface.
1233
+ *
1234
+ * Everything a game reaches for that is not attached to an entity lives here — the pixels-per-unit
1235
+ * conversion, the camera the frame is drawn through, sprite picking, the tile-object factory
1236
+ * registry, the per-layer diagnostics, and the Lite escape hatch.
1237
+ */
1238
+ /**
1239
+ * What `app.twoD.pickAt` returns.
1240
+ *
1241
+ * @public
1242
+ */
1243
+ interface TwoDPick {
1244
+ /** The entity carrying the sprite that was hit. */
1245
+ readonly entity: Entity;
1246
+ /** The sprite component that was hit. */
1247
+ readonly component: SpriteRenderer;
1248
+ /** Where inside the sprite's quad the hit landed, in `[0, 1]`. */
1249
+ readonly u: number;
1250
+ /** Where inside the sprite's quad the hit landed, in `[0, 1]`. */
1251
+ readonly v: number;
1252
+ }
1253
+ /**
1254
+ * Builds the entities a tilemap's objects layer describes.
1255
+ *
1256
+ * @public
1257
+ */
1258
+ type TileObjectFactory = (context: TileObjectContext) => Entity | null;
1259
+ /**
1260
+ * What a {@link TileObjectFactory} is handed.
1261
+ *
1262
+ * @public
1263
+ */
1264
+ interface TileObjectContext {
1265
+ /** The world to create the entity in. */
1266
+ readonly world: World;
1267
+ /** The object's name, as the map wrote it. */
1268
+ readonly name: string;
1269
+ /** The object's type, which selected this factory. */
1270
+ readonly type: string;
1271
+ /** The object's bottom-left corner, in world metres relative to the tilemap entity. */
1272
+ readonly position: Vec2Like;
1273
+ /** The object's size, in world metres. */
1274
+ readonly size: Vec2Like;
1275
+ /** The object's custom properties. */
1276
+ readonly properties: Readonly<Record<string, string | number | boolean>>;
1277
+ /** The tilemap entity the object came from, so a factory can parent to it. */
1278
+ readonly tilemap: Entity;
1279
+ }
1280
+ /**
1281
+ * The 2D service.
1282
+ *
1283
+ * @example
1284
+ * ```ts
1285
+ * const hit = app.twoD.pickAt(pointer.x, pointer.y);
1286
+ * if (hit !== null) {
1287
+ * hit.entity.destroy();
1288
+ * }
1289
+ * ```
1290
+ *
1291
+ * @public
1292
+ */
1293
+ export declare class TwoDService {
1294
+ #private;
1295
+ /**
1296
+ * Builds the service.
1297
+ *
1298
+ * @param runtime - The app's 2D runtime state.
1299
+ *
1300
+ * @internal
1301
+ */
1302
+ constructor(runtime: TwoDRuntime);
1303
+ /**
1304
+ * How many pixels one world metre spans (`docs/architecture/11-2d-toolkit.md` §1).
1305
+ *
1306
+ * @returns The conversion factor; `100` unless the project or a scene changed it.
1307
+ */
1308
+ get pixelsPerUnit(): number;
1309
+ /**
1310
+ * Whether sprites are the whole frame or composite over the 3D scene.
1311
+ *
1312
+ * @returns The mode.
1313
+ */
1314
+ get mode(): TwoDMode;
1315
+ /**
1316
+ * The resolved `twoD` settings, after any scene-file override.
1317
+ *
1318
+ * @returns The settings.
1319
+ */
1320
+ get settings(): TwoDSettings;
1321
+ /**
1322
+ * The camera the last frame was drawn through: the highest-priority enabled `Camera2D`.
1323
+ *
1324
+ * @returns The camera, or `null` when the world has none enabled.
1325
+ */
1326
+ get mainCamera(): Camera2D | null;
1327
+ /**
1328
+ * The project's sorting layers, back to front.
1329
+ *
1330
+ * @returns The names.
1331
+ */
1332
+ get sortingLayers(): readonly string[];
1333
+ /**
1334
+ * Every Lite sprite layer in draw order, for diagnostics and tests.
1335
+ *
1336
+ * @remarks
1337
+ * The snapshot is freshly allocated on each read; it is a debugging surface, not a per-frame one.
1338
+ *
1339
+ * @returns The layers.
1340
+ */
1341
+ get layers(): readonly SpriteLayerEntry[];
1342
+ /**
1343
+ * The Babylon Lite objects the toolkit owns. Unstable escape hatch
1344
+ * (`CONSTITUTION.md` §3.4).
1345
+ *
1346
+ * @returns The sprite rendering context, or `null` under a headless app or before the first frame.
1347
+ */
1348
+ get lite(): TwoDLiteHandles;
1349
+ /**
1350
+ * How many sprites the last frame actually wrote to Lite.
1351
+ *
1352
+ * @remarks
1353
+ * This is the number spike S6.1 watches: on a steady frame with a static tilemap it is the count
1354
+ * of sprites that genuinely moved, not the count that exist.
1355
+ *
1356
+ * @returns The count.
1357
+ */
1358
+ get syncedLastFrame(): number;
1359
+ /**
1360
+ * How many `SpriteRenderer` components the last frame walked.
1361
+ *
1362
+ * @returns The count.
1363
+ */
1364
+ get spriteCount(): number;
1365
+ /**
1366
+ * Picks the topmost sprite under a viewport pixel (`docs/architecture/11-2d-toolkit.md` §5).
1367
+ *
1368
+ * @remarks
1369
+ * Picking is a CPU test against every world layer's instance data, in draw order — no GPU
1370
+ * readback and no frame of latency, which is what makes it usable from a click handler. It
1371
+ * resolves only `SpriteRenderer` components: a tilemap's tiles have no component, so use
1372
+ * `Tilemap.worldToCell` for those.
1373
+ *
1374
+ * @param xPx - The viewport x, in pixels from the left edge.
1375
+ * @param yPx - The viewport y, in pixels from the top edge.
1376
+ * @returns The hit, or `null` for a miss.
1377
+ */
1378
+ pickAt(xPx: number, yPx: number): TwoDPick | null;
1379
+ /**
1380
+ * The world-space rectangle the camera can currently see.
1381
+ *
1382
+ * @param out - The vectors to write.
1383
+ * @returns `true` when a camera and a layer existed to measure against.
1384
+ */
1385
+ visibleWorldBounds(out: {
1386
+ readonly min: MutableVec2;
1387
+ readonly max: MutableVec2;
1388
+ }): boolean;
1389
+ /**
1390
+ * Registers the factory that turns one kind of tilemap object into an entity
1391
+ * (`docs/architecture/11-2d-toolkit.md` §2.5).
1392
+ *
1393
+ * @param type - The object `type` the map writes.
1394
+ * @param factory - Builds the entity, or returns `null` to spawn nothing.
1395
+ * @throws IgnifxError with code `IGX-1110` when a factory for the type is already registered.
1396
+ *
1397
+ * @example
1398
+ * ```ts
1399
+ * app.twoD.registerTileObjectFactory("spawn", ({ world, position }) => {
1400
+ * const player = world.createEntity({ name: "player" });
1401
+ * player.transform.position2D = new Vec2(position.x, position.y);
1402
+ * return player;
1403
+ * });
1404
+ * ```
1405
+ */
1406
+ registerTileObjectFactory(type: string, factory: TileObjectFactory): void;
1407
+ /**
1408
+ * Removes a tile-object factory.
1409
+ *
1410
+ * @param type - The object type.
1411
+ * @returns `true` when a factory was registered.
1412
+ */
1413
+ unregisterTileObjectFactory(type: string): boolean;
1414
+ /**
1415
+ * The factory registered for an object type.
1416
+ *
1417
+ * @param type - The object type.
1418
+ * @returns The factory, or `null`.
1419
+ *
1420
+ * @internal
1421
+ */
1422
+ tileObjectFactory(type: string): TileObjectFactory | null;
1423
+ /**
1424
+ * Converts a viewport pixel into a world point through the active camera.
1425
+ *
1426
+ * @param xPx - The viewport x.
1427
+ * @param yPx - The viewport y.
1428
+ * @param out - The vector to write; omitting it allocates one.
1429
+ * @returns `out`, or the origin when no camera is active.
1430
+ */
1431
+ screenToWorld(xPx: number, yPx: number, out?: MutableVec2): MutableVec2;
1432
+ /**
1433
+ * Converts a world point into a viewport pixel through the active camera.
1434
+ *
1435
+ * @param point - The world point, in metres.
1436
+ * @param out - The vector to write; omitting it allocates one.
1437
+ * @returns `out`, or the origin when no camera is active.
1438
+ */
1439
+ worldToScreen(point: Vec2Like, out?: MutableVec2): MutableVec2;
1440
+ }
1441
+ //#endregion
1442
+ //#region src/augmentation.d.ts
1443
+ /**
1444
+ * The typed entry point (`docs/architecture/03-scripting-and-components.md` §7). Declaration
1445
+ * merging is what makes `this.app.twoD` fully typed when `@ignifx/2d` is installed and a compile
1446
+ * error when it is not.
1447
+ *
1448
+ * Two mechanics carry over from `@ignifx/input`, both measured rather than assumed:
1449
+ *
1450
+ * - The module **must** import something from `@ignifx/core`. A `declare module "@ignifx/core"`
1451
+ * block in a file that never imports the module is `TS2664: Invalid module name in augmentation`
1452
+ * under both `tsc --build` and TypeDoc; importing the `ExtensionContext` type used below is
1453
+ * enough to bring the module into the program.
1454
+ * - The barrel **must** name this module in a bare `import "./augmentation.js"`. Declaration
1455
+ * bundling drops a module whose only exports are unreferenced from the public surface, which
1456
+ * silently takes the augmentation out of `dist/index.d.ts` with it. The bare import is a
1457
+ * type-only side effect: the emitted JavaScript keeps no statement for it, so `sideEffects: false`
1458
+ * stays honest.
1459
+ */
1460
+ declare module "@ignifx/core" {
1461
+ interface App {
1462
+ /**
1463
+ * The 2D service (`docs/architecture/11-2d-toolkit.md` §1): the pixels-per-unit conversion, the
1464
+ * active `Camera2D`, sprite picking, the sprite-layer diagnostics, and the Lite escape hatch.
1465
+ */
1466
+ readonly twoD: TwoDService;
1467
+ }
1468
+ }
1469
+ //#endregion
1470
+ //#region src/tilemap/animated-tiles.d.ts
1471
+ /**
1472
+ * The seam between the 2D animation system and the tilemap renderer.
1473
+ *
1474
+ * Animated tiles advance on the same clock as `SpriteAnimator`
1475
+ * (`docs/architecture/11-2d-toolkit.md` §2.5), so the animation system drives both. This interface
1476
+ * is what keeps the animation system from importing the tilemap renderer, which imports the layer
1477
+ * registry, which imports the sprite component — a cycle that adds nothing.
1478
+ */
1479
+ /**
1480
+ * Anything that owns animated tiles and can step them.
1481
+ *
1482
+ * @public
1483
+ */
1484
+ interface AnimatedTilemapSink {
1485
+ /**
1486
+ * Advances every animated tile by one frame's worth of scaled time.
1487
+ *
1488
+ * @param world - The world holding the tilemaps.
1489
+ * @param deltaSeconds - The scaled frame delta, `time.deltaTime`.
1490
+ */
1491
+ advanceAnimatedTiles(world: World, deltaSeconds: number): void;
1492
+ }
1493
+ //#endregion
1494
+ //#region src/animation/animation-system.d.ts
1495
+ /**
1496
+ * The 2D animation system (`docs/architecture/01-lifecycle-and-time.md` §3, ADR-0003).
1497
+ *
1498
+ * It runs in `PostUpdate` — after `update`, before `PreRender` — which is where every animation in
1499
+ * ignifx advances, so a `lateUpdate` sees the posed frame and the render sync writes it in the same
1500
+ * 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.
1503
+ */
1504
+ /**
1505
+ * The `PostUpdate` order the 2D animation system runs at.
1506
+ *
1507
+ * @remarks
1508
+ * `PostUpdate` is empty today — no core or extension system registers there — so `0` is the middle
1509
+ * of an open phase. Anything a game adds later can sit either side of it by choosing a sign.
1510
+ *
1511
+ * @public
1512
+ */
1513
+ export declare const TWO_D_ANIMATION_ORDER = 0;
1514
+ /**
1515
+ * Advances sprite animation on ignifx's clock.
1516
+ *
1517
+ * @public
1518
+ */
1519
+ export declare class TwoDAnimationSystem implements System {
1520
+ #private;
1521
+ /** The name diagnostics and error reports use. */
1522
+ readonly name = "ignifx/2d-animation";
1523
+ /**
1524
+ * Builds the system.
1525
+ *
1526
+ * @param tilemaps - Advances animated tiles on the same clock.
1527
+ */
1528
+ constructor(tilemaps: AnimatedTilemapSink);
1529
+ /**
1530
+ * Advances every animator and every animated tile.
1531
+ *
1532
+ * @param ctx - The world, clock, phase, and delta.
1533
+ */
1534
+ update(ctx: SystemContext): void;
1535
+ }
1536
+ //#endregion
1537
+ //#region src/animation/definition.d.ts
1538
+ /**
1539
+ * The `ignifx.spriteanimation` document — the `.spriteanim.json` file that names an atlas and the
1540
+ * clips cut out of its frames (`docs/architecture/06-serialization-and-scene-format.md` §6,
1541
+ * `11-2d-toolkit.md` §2.4).
1542
+ *
1543
+ * A clip lists frame names explicitly, or names the first and last frame of a contiguous run in the
1544
+ * atlas. ignifx drives these on its own clock in `PostUpdate`, not on Lite's
1545
+ * `SpriteAnimationManager`, so `timeScale`, pause, and frame events behave exactly as they do for
1546
+ * 3D animation (ADR-0003).
1547
+ */
1548
+ /** The `format` discriminator every `.spriteanim.json` document carries. @public */
1549
+ export declare const SPRITE_ANIMATION_FORMAT = "ignifx.spriteanimation";
1550
+ /** The document version this build reads and writes. @public */
1551
+ export declare const SPRITE_ANIMATION_FORMAT_VERSION = 1;
1552
+ /** The asset type name the loader registers. @public */
1553
+ export declare const SPRITE_ANIMATION_ASSET_TYPE = "spriteanimation";
1554
+ /** The address suffixes that select the sprite-animation loader. @public */
1555
+ export declare const SPRITE_ANIMATION_FILE_EXTENSIONS: readonly string[];
1556
+ /**
1557
+ * A frame event: a name emitted on `SpriteAnimator.onEvent` when the clip reaches a frame.
1558
+ *
1559
+ * @public
1560
+ */
1561
+ interface SpriteAnimationEvent {
1562
+ /** The zero-based index **within the clip**, not within the atlas. */
1563
+ readonly frame: number;
1564
+ /** The name emitted on `SpriteAnimator.onEvent`. */
1565
+ readonly name: string;
1566
+ }
1567
+ /**
1568
+ * One clip: an ordered run of atlas frames with a rate and a loop flag.
1569
+ *
1570
+ * @public
1571
+ */
1572
+ interface SpriteClipDefinition {
1573
+ /** The clip's name, unique within the document; what `SpriteAnimator.play` takes. */
1574
+ readonly name: string;
1575
+ /** The atlas frame names, in play order. Empty when `from`/`to` name a range instead. */
1576
+ readonly frames?: readonly string[];
1577
+ /** The first frame of a contiguous atlas range, when `frames` is absent. */
1578
+ readonly from?: string;
1579
+ /** The last frame of a contiguous atlas range, inclusive. */
1580
+ readonly to?: string;
1581
+ /** Frames per second. Defaults to `12`. */
1582
+ readonly fps?: number;
1583
+ /** Whether the clip restarts at its end. Defaults to `true`. */
1584
+ readonly loop?: boolean;
1585
+ /** Events fired as the clip passes a frame. */
1586
+ readonly events?: readonly SpriteAnimationEvent[];
1587
+ }
1588
+ /**
1589
+ * The parsed `.spriteanim.json` document.
1590
+ *
1591
+ * @public
1592
+ */
1593
+ interface SpriteAnimationDefinition {
1594
+ /** Always `"ignifx.spriteanimation"`. */
1595
+ readonly format: typeof SPRITE_ANIMATION_FORMAT;
1596
+ /** Always `1` in this build. */
1597
+ readonly version: number;
1598
+ /** The address of the `.atlas.json` the clips index into; empty uses the renderer's own atlas. */
1599
+ readonly atlas: string;
1600
+ /** The clips, in declaration order; the first is the default when the component names none. */
1601
+ readonly clips: readonly SpriteClipDefinition[];
1602
+ }
1603
+ /**
1604
+ * What {@link defineSpriteAnimation} accepts.
1605
+ *
1606
+ * @public
1607
+ */
1608
+ interface SpriteAnimationInput {
1609
+ /** Always `"ignifx.spriteanimation"` when present. */
1610
+ readonly format?: string;
1611
+ /** The document version. */
1612
+ readonly version?: number;
1613
+ /** The address of the `.atlas.json` the clips index into. */
1614
+ readonly atlas?: string;
1615
+ /** The clips. */
1616
+ readonly clips: readonly SpriteClipDefinition[];
1617
+ }
1618
+ /** The frames-per-second a clip that declares none plays at. @public */
1619
+ export declare const DEFAULT_CLIP_FPS = 12;
1620
+ /**
1621
+ * Fills in the defaults of an animation document and checks the invariants the animator relies on.
1622
+ *
1623
+ * @param input - The document, as authored or as an importer emitted it.
1624
+ * @param address - What to name in an error; defaults to `"<inline>"`.
1625
+ * @returns The complete document.
1626
+ * @throws IgnifxError with code `IGX-1104` when the format tag, the version, or a clip is wrong.
1627
+ *
1628
+ * @public
1629
+ */
1630
+ export declare function defineSpriteAnimation(input: SpriteAnimationInput, address?: string): SpriteAnimationDefinition;
1631
+ /**
1632
+ * Resolves a clip's frame names into atlas frame indices.
1633
+ *
1634
+ * @param clip - The clip to resolve.
1635
+ * @param indexOf - Maps an atlas frame name to its index, or `-1` when the atlas has no such frame.
1636
+ * @returns The indices in play order; empty when the clip names nothing the atlas has.
1637
+ *
1638
+ * @public
1639
+ */
1640
+ export declare function resolveClipFrames(clip: SpriteClipDefinition, indexOf: (name: string) => number): readonly number[];
1641
+ //#endregion
1642
+ //#region src/animation/importers.d.ts
1643
+ /**
1644
+ * What {@link importAsepriteAnimations} accepts alongside the document.
1645
+ *
1646
+ * @public
1647
+ */
1648
+ interface AsepriteAnimationImportOptions {
1649
+ /** The `.atlas.json` address the clips index into. Defaults to `""`, the renderer's own atlas. */
1650
+ readonly atlas?: string;
1651
+ /** The rate a tag gets when Aseprite recorded no usable frame durations. Defaults to `12`. */
1652
+ readonly defaultFps?: number;
1653
+ /**
1654
+ * Names the atlas frame at a document frame index. Defaults to the same normalisation
1655
+ * `importAsepriteAtlas` applies to the document's own frame keys, which is what makes the two
1656
+ * imports agree; override it when the atlas was produced some other way.
1657
+ */
1658
+ readonly frameNameOf?: (index: number) => string;
1659
+ }
1660
+ /**
1661
+ * Converts an Aseprite sheet export's tags into an `ignifx.spriteanimation` document.
1662
+ *
1663
+ * Every entry in `meta.frameTags` becomes one clip, named after the tag, listing the frame names
1664
+ * for indices `from` through `to` explicitly rather than as a range — a clip that lists names
1665
+ * survives an atlas being repacked in a different order.
1666
+ *
1667
+ * Playback direction is baked into that list, because ignifx clips play forwards:
1668
+ *
1669
+ * - `"forward"` (and anything unrecognised) lists `from … to` in order.
1670
+ * - `"reverse"` lists them backwards.
1671
+ * - `"pingpong"` lists them forwards and then appends the **interior** frames in reverse, so a
1672
+ * three-frame tag becomes `0, 1, 2, 1` — the ends are not repeated, which is what makes the clip
1673
+ * loop seamlessly.
1674
+ *
1675
+ * `loop` is `true` unless the tag's `repeat` is the string `"1"`, Aseprite's "play once".
1676
+ *
1677
+ * @remarks
1678
+ * Aseprite stores a duration **per frame**, in milliseconds, while an ignifx clip carries a single
1679
+ * `fps`. A tag is therefore approximated by the mean of its frames' durations: `fps` is
1680
+ * `1000 / averageDuration`, rounded to three decimal places. A tag whose frames all share a
1681
+ * duration converts exactly; one with uneven durations does not, and the individual frames will
1682
+ * hold for the average instead of their authored time. Split such a tag, or even the durations out
1683
+ * in Aseprite, when the timing matters. When no frame in the range declares a positive duration,
1684
+ * `options.defaultFps` — itself defaulting to `12` — is used instead.
1685
+ *
1686
+ * Aseprite has no frame-event concept, so no clip carries `events`.
1687
+ *
1688
+ * @param json - The parsed Aseprite document.
1689
+ * @param options - The atlas address, the fallback rate, and a frame-naming override.
1690
+ * @returns The complete animation document, already through `defineSpriteAnimation`.
1691
+ * @throws IgnifxError with code `IGX-1109` when the document is not an object, when
1692
+ * `meta.frameTags` is missing, is not an array, or is empty, when a tag has no name, or when
1693
+ * frames cannot be named because the document has no readable `frames` and no `frameNameOf` was
1694
+ * supplied.
1695
+ *
1696
+ * @example
1697
+ * ```ts
1698
+ * const animations = importAsepriteAnimations(JSON.parse(text), { atlas: "2d/hero.atlas.json" });
1699
+ * animations.clips[0]; // { name: "idle", frames: ["hero_0", "hero_1"], fps: 10, loop: true }
1700
+ * ```
1701
+ *
1702
+ * @public
1703
+ */
1704
+ export declare function importAsepriteAnimations(json: unknown, options?: AsepriteAnimationImportOptions): SpriteAnimationDefinition;
1705
+ //#endregion
1706
+ //#region src/animation/sprite-animation-asset.d.ts
1707
+ /**
1708
+ * The value a `.spriteanim.json` address loads to: the parsed document plus, once the atlas it
1709
+ * names has loaded, every clip resolved to atlas frame indices
1710
+ * (`docs/architecture/11-2d-toolkit.md` §2.4).
1711
+ */
1712
+ /**
1713
+ * One clip, resolved against an atlas.
1714
+ *
1715
+ * @public
1716
+ */
1717
+ interface SpriteClip {
1718
+ /** The clip's name. */
1719
+ readonly name: string;
1720
+ /** The atlas frame indices, in play order. */
1721
+ readonly frames: readonly number[];
1722
+ /** Frames per second. */
1723
+ readonly fps: number;
1724
+ /** Whether the clip restarts at its end. */
1725
+ readonly loop: boolean;
1726
+ /** Events fired as the clip passes a frame. */
1727
+ readonly events: readonly SpriteAnimationEvent[];
1728
+ /** How long one pass through the clip takes, in seconds. */
1729
+ readonly durationSeconds: number;
1730
+ }
1731
+ /**
1732
+ * A loaded sprite-animation document.
1733
+ *
1734
+ * @remarks
1735
+ * Resolution needs an atlas, and a document may be loaded before, after, or without one. The asset
1736
+ * therefore keeps the parsed clips and resolves them lazily the first time an atlas is offered;
1737
+ * `SpriteAnimator` offers its renderer's atlas. Under a headless app everything here works
1738
+ * unchanged, which is what makes animation timing testable with `app.step`.
1739
+ *
1740
+ * @example
1741
+ * ```ts
1742
+ * const clips = await app.assets.load<SpriteAnimationAsset>("2d/hero.spriteanim.json").promise;
1743
+ * clips.clipNames(); // ["idle", "run"]
1744
+ * ```
1745
+ *
1746
+ * @public
1747
+ */
1748
+ export declare class SpriteAnimationAsset {
1749
+ #private;
1750
+ /** The type name the asset service registers animation documents under. */
1751
+ static assetType: string;
1752
+ /** The address the document was loaded from. */
1753
+ readonly address: string;
1754
+ /** The parsed document. */
1755
+ readonly definition: SpriteAnimationDefinition;
1756
+ /** The atlas address the document names, already resolved against its own address. */
1757
+ readonly atlasAddress: string;
1758
+ /**
1759
+ * Wraps a parsed document. The `spriteanimation` loader constructs these.
1760
+ *
1761
+ * @param address - The address it was loaded from.
1762
+ * @param definition - The parsed document.
1763
+ * @param atlasAddress - The atlas address, resolved against `address`.
1764
+ *
1765
+ * @internal
1766
+ */
1767
+ constructor(address: string, definition: SpriteAnimationDefinition, atlasAddress: string);
1768
+ /**
1769
+ * Every clip name, in declaration order.
1770
+ *
1771
+ * @returns A freshly allocated array.
1772
+ */
1773
+ clipNames(): readonly string[];
1774
+ /**
1775
+ * The name of the clip a component that names none plays.
1776
+ *
1777
+ * @returns The first clip's name, or `""` when the document is empty.
1778
+ */
1779
+ get defaultClipName(): string;
1780
+ /**
1781
+ * Resolves every clip's frame names against an atlas.
1782
+ *
1783
+ * @remarks
1784
+ * The result is cached against the atlas it was resolved with, so playing ten characters off one
1785
+ * atlas resolves once. Offering a different atlas re-resolves.
1786
+ *
1787
+ * @param atlas - The atlas the frame names index into.
1788
+ * @returns The clips, keyed by name.
1789
+ */
1790
+ resolve(atlas: SpriteAtlasAsset): ReadonlyMap<string, SpriteClip>;
1791
+ /**
1792
+ * Looks a clip up, resolving against an atlas first.
1793
+ *
1794
+ * @param name - The clip name.
1795
+ * @param atlas - The atlas the frame names index into.
1796
+ * @returns The clip.
1797
+ * @throws IgnifxError with code `IGX-1108` when the document declares no such clip.
1798
+ */
1799
+ requireClip(name: string, atlas: SpriteAtlasAsset): SpriteClip;
1800
+ }
1801
+ //#endregion
1802
+ //#region src/animation/loader.d.ts
1803
+ /**
1804
+ * The `spriteanimation` asset loader (`docs/architecture/05-assets-and-loading.md` §5).
1805
+ *
1806
+ * The document is pure data — clip names, frame names, rates — so the loader needs no device and
1807
+ * behaves identically under a headless app. It does not load the atlas it names: a `SpriteAnimator`
1808
+ * already has one on its `SpriteRenderer`, and forcing a second copy would double the upload.
1809
+ * `SpriteAnimationAsset.atlasAddress` carries the reference for a game that wants to load it.
1810
+ */
1811
+ /**
1812
+ * Builds the loader for `.spriteanim.json` addresses.
1813
+ *
1814
+ * @returns The loader to register with `ctx.registerAssetLoader`.
1815
+ *
1816
+ * @example
1817
+ * ```ts
1818
+ * ctx.registerAssetLoader(createSpriteAnimationLoader());
1819
+ * ```
1820
+ *
1821
+ * @public
1822
+ */
1823
+ export declare function createSpriteAnimationLoader(): AssetLoader<SpriteAnimationAsset>;
1824
+ //#endregion
1825
+ //#region src/animation/sprite-animator.d.ts
1826
+ /**
1827
+ * `SpriteAnimator` (`docs/architecture/11-2d-toolkit.md` §2.4): plays a clip of atlas frames on the
1828
+ * `SpriteRenderer` sharing its entity.
1829
+ *
1830
+ * The clock is **ignifx's**, advanced in `PostUpdate` (ADR-0003), not Lite's
1831
+ * `SpriteAnimationManager`. That is what makes `app.time.timeScale`, `app.pause()`, and frame
1832
+ * events behave for a 2D character exactly as they do for a 3D one — and what makes the whole
1833
+ * thing testable with `app.step` under a headless app, where no sprite is drawn at all.
1834
+ */
1835
+ /**
1836
+ * What {@link SpriteAnimator.play} accepts.
1837
+ *
1838
+ * @public
1839
+ */
1840
+ interface PlayClipOptions {
1841
+ /** Whether to rewind a clip that is already playing. Defaults to `false`. */
1842
+ readonly restart?: boolean;
1843
+ }
1844
+ /**
1845
+ * A sprite animator.
1846
+ *
1847
+ * @example
1848
+ * ```ts
1849
+ * const animator = hero.addComponent(SpriteAnimator);
1850
+ * animator.animations = app.assets.load<SpriteAnimationAsset>("2d/hero.spriteanim.json").retain();
1851
+ * animator.onEvent.connect((name) => { if (name === "footstep") playStep(); }, { owner: animator });
1852
+ * animator.play("run");
1853
+ * ```
1854
+ *
1855
+ * @public
1856
+ */
1857
+ export declare class SpriteAnimator extends Component implements ComponentHooks {
1858
+ #private;
1859
+ /** The registration id the serializer writes into scene files. */
1860
+ static typeId: string;
1861
+ /** One animator per entity. */
1862
+ static allowMultiple: boolean;
1863
+ /** The declarative fields (ADR-0004). */
1864
+ static schema: Schema;
1865
+ /** The document holding the clips. */
1866
+ animations: AssetHandle<SpriteAnimationAsset> | null;
1867
+ /** Which clip to start on; empty plays the document's first. */
1868
+ defaultClip: string;
1869
+ /** Whether the default clip starts as soon as the document has loaded. */
1870
+ playOnAwake: boolean;
1871
+ /** A multiplier on the clip's own frame rate. */
1872
+ speed: number;
1873
+ /**
1874
+ * Builds an animator with the schema's defaults.
1875
+ */
1876
+ constructor();
1877
+ /**
1878
+ * Clears playback state, so a recycled component does not inherit the previous one's.
1879
+ */
1880
+ onAttach(): void;
1881
+ /**
1882
+ * Releases the signals' handlers.
1883
+ */
1884
+ onDetach(): void;
1885
+ /**
1886
+ * Emitted with a clip's name when a non-looping clip reaches its last frame.
1887
+ *
1888
+ * @returns The signal.
1889
+ */
1890
+ get onClipEnded(): Signal<string>;
1891
+ /**
1892
+ * Emitted with an event's name when playback passes the frame that declares it.
1893
+ *
1894
+ * @remarks
1895
+ * A looping clip fires each event once per pass. A clip advanced by more than one frame in a
1896
+ * single step — a long frame, or a high `speed` — fires every event it skipped over, in order,
1897
+ * so a footstep is never silently dropped.
1898
+ *
1899
+ * @returns The signal.
1900
+ */
1901
+ get onEvent(): Signal<string>;
1902
+ /**
1903
+ * Whether a clip is currently advancing.
1904
+ *
1905
+ * @returns `true` while playing.
1906
+ */
1907
+ get isPlaying(): boolean;
1908
+ /**
1909
+ * The clip currently playing, or `null`.
1910
+ *
1911
+ * @returns The clip.
1912
+ */
1913
+ get clip(): SpriteClip | null;
1914
+ /**
1915
+ * The atlas frame index the animator last wrote.
1916
+ *
1917
+ * @returns The frame index, or `-1` when no clip is playing.
1918
+ */
1919
+ get frame(): number;
1920
+ /**
1921
+ * How far into the clip playback is, in seconds.
1922
+ *
1923
+ * @returns The elapsed time.
1924
+ */
1925
+ get time(): number;
1926
+ /**
1927
+ * The loaded animation document, or `null` while it is still loading.
1928
+ *
1929
+ * @returns The document.
1930
+ */
1931
+ get asset(): SpriteAnimationAsset | null;
1932
+ /**
1933
+ * Starts a clip.
1934
+ *
1935
+ * @param name - The clip's name.
1936
+ * @param options - Whether to rewind a clip that is already playing.
1937
+ * @throws IgnifxError with code `IGX-1108` when the document declares no such clip.
1938
+ *
1939
+ * @example
1940
+ * ```ts
1941
+ * animator.play("run", { restart: true });
1942
+ * ```
1943
+ */
1944
+ play(name: string, options?: PlayClipOptions): void;
1945
+ /**
1946
+ * Stops playback and rewinds to the clip's first frame.
1947
+ */
1948
+ stop(): void;
1949
+ /**
1950
+ * Suspends playback where it is; {@link SpriteAnimator.resume} continues from there.
1951
+ */
1952
+ pause(): void;
1953
+ /**
1954
+ * Continues a paused clip.
1955
+ */
1956
+ resume(): void;
1957
+ /**
1958
+ * Advances playback by one frame's worth of scaled time. The animation system calls this in
1959
+ * `PostUpdate`.
1960
+ *
1961
+ * @remarks
1962
+ * `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
1964
+ * (`docs/architecture/01-lifecycle-and-time.md` §2). The animator does not consult the clock
1965
+ * itself, which is what makes it deterministic under `app.step`.
1966
+ *
1967
+ * @param deltaSeconds - The scaled frame delta.
1968
+ *
1969
+ * @internal
1970
+ */
1971
+ advance(deltaSeconds: number): void;
1972
+ }
1973
+ //#endregion
1974
+ //#region src/assets/relative.d.ts
1975
+ /**
1976
+ * Resolves a document-relative reference against the document's own address or URL.
1977
+ *
1978
+ * @remarks
1979
+ * A reference that is absolute — one of the recognised URL schemes, or one starting with `/` — is
1980
+ * returned untouched, so a project that prefers project-root addresses can write them. `.` and `..`
1981
+ * segments are collapsed, and a base with no `/` at all is treated as a file in the root.
1982
+ *
1983
+ * @param base - The address or URL of the document holding the reference.
1984
+ * @param reference - What the document wrote.
1985
+ * @returns The resolved address or URL.
1986
+ *
1987
+ * @example
1988
+ * ```ts
1989
+ * resolveRelative("2d/hero.atlas.json", "hero.png"); // "2d/hero.png"
1990
+ * resolveRelative("2d/hero.atlas.json", "../shared/pal.png"); // "shared/pal.png"
1991
+ * resolveRelative("2d/hero.atlas.json", "/sprites/hero.png"); // "/sprites/hero.png"
1992
+ * ```
1993
+ *
1994
+ * @public
1995
+ */
1996
+ export declare function resolveRelative(base: string, reference: string): string;
1997
+ /**
1998
+ * Collapses `.` and `..` segments in a `/`-separated path.
1999
+ *
2000
+ * @param path - The path to normalise.
2001
+ * @returns The normalised path; leading `..` segments that escape the root are dropped.
2002
+ *
2003
+ * @public
2004
+ */
2005
+ export declare function normalisePath(path: string): string;
2006
+ //#endregion
2007
+ //#region src/atlas/importers.d.ts
2008
+ /**
2009
+ * Normalises an Aseprite frame key into an identifier a clip and a `#frame:` fragment can name.
2010
+ *
2011
+ * The rule, applied in this order:
2012
+ *
2013
+ * 1. Drop a trailing file extension — a dot, a letter, then up to seven more alphanumerics — so
2014
+ * `hero 0.aseprite` and `hero_0.png` both lose their suffix but `walk.2` does not.
2015
+ * 2. Replace every run of non-alphanumeric characters with a single `_`.
2016
+ * 3. Trim leading and trailing `_`.
2017
+ *
2018
+ * Case is preserved: `Hero (Idle) 0.aseprite` becomes `Hero_Idle_0`, not `hero_idle_0`. A key that
2019
+ * normalises to nothing at all (`"###.png"`) becomes `frame`.
2020
+ *
2021
+ * {@link importAsepriteAtlas} and `importAsepriteAnimations` both run keys through this function,
2022
+ * which is what makes an imported clip's frame names line up with the imported atlas's.
2023
+ *
2024
+ * @param raw - The frame key as Aseprite wrote it — a hash key, or an array entry's `filename`.
2025
+ * @returns The normalised frame name.
2026
+ *
2027
+ * @example
2028
+ * ```ts
2029
+ * asepriteFrameName("hero (idle) 0.aseprite"); // "hero_idle_0"
2030
+ * asepriteFrameName("hero_0.png"); // "hero_0"
2031
+ * ```
2032
+ *
2033
+ * @public
2034
+ */
2035
+ export declare function asepriteFrameName(raw: string): string;
2036
+ /**
2037
+ * What {@link gridAtlas} needs to cut an evenly spaced sheet into frames.
2038
+ *
2039
+ * @public
2040
+ */
2041
+ interface GridAtlasImportOptions {
2042
+ /** The address of the image the frames are cut from. */
2043
+ readonly image: string;
2044
+ /** The image's full width, in pixels. */
2045
+ readonly imageWidth: number;
2046
+ /** The image's full height, in pixels. */
2047
+ readonly imageHeight: number;
2048
+ /** One cell's width, in pixels. Must be positive. */
2049
+ readonly cellWidth: number;
2050
+ /** One cell's height, in pixels. Must be positive. */
2051
+ readonly cellHeight: number;
2052
+ /** How many columns to emit. Defaults to as many as the image holds; clamped to that. */
2053
+ readonly columns?: number;
2054
+ /** How many rows to emit. Defaults to as many as the image holds; clamped to that. */
2055
+ readonly rows?: number;
2056
+ /** The border left around the whole grid, in pixels. Defaults to `0`. */
2057
+ readonly margin?: number;
2058
+ /** The gap between adjacent cells, in pixels. Defaults to `0`. */
2059
+ readonly spacing?: number;
2060
+ /** The pivot every frame gets, in `[0, 1]`. Defaults to the centre. */
2061
+ readonly pivot?: Vec2Like;
2062
+ /** The `<prefix>_<index>` frame names use. Defaults to `"tile"`. */
2063
+ readonly namePrefix?: string;
2064
+ /** The min/mag filter. Defaults to `"linear"`; pixel art wants `"nearest"`. */
2065
+ readonly sampling?: "linear" | "nearest";
2066
+ /** Whether the image's RGB is already multiplied by its alpha. Defaults to `false`. */
2067
+ readonly premultipliedAlpha?: boolean;
2068
+ }
2069
+ /**
2070
+ * Cuts an evenly spaced sprite sheet into an `ignifx.spriteatlas` document.
2071
+ *
2072
+ * 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
2074
+ * grid ends at `tile_7`. `columns` and `rows` default to as many whole cells as the image holds
2075
+ * (`floor((imageWidth - 2·margin + spacing) / (cellWidth + spacing))`, and likewise for rows) and
2076
+ * are clamped to that capacity when given, so an over-large explicit count never produces a frame
2077
+ * that falls off the image.
2078
+ *
2079
+ * @remarks
2080
+ * `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
2082
+ * as `namePrefix` makes a hand-cut grid atlas addressable by exactly the names a tilemap emits.
2083
+ *
2084
+ * @param options - The sheet's geometry and the frame naming.
2085
+ * @returns The complete atlas document.
2086
+ * @throws IgnifxError with code `IGX-1109` when a cell dimension is not positive, or when the
2087
+ * geometry yields no frames at all.
2088
+ *
2089
+ * @example
2090
+ * ```ts
2091
+ * const atlas = gridAtlas({
2092
+ * image: "2d/terrain.png",
2093
+ * imageWidth: 64,
2094
+ * imageHeight: 64,
2095
+ * cellWidth: 32,
2096
+ * cellHeight: 32,
2097
+ * namePrefix: "terrain",
2098
+ * sampling: "nearest",
2099
+ * });
2100
+ * atlas.frames.map((frame) => frame.name); // ["terrain_0", "terrain_1", "terrain_2", "terrain_3"]
2101
+ * ```
2102
+ *
2103
+ * @public
2104
+ */
2105
+ export declare function gridAtlas(options: GridAtlasImportOptions): SpriteAtlasDefinition;
2106
+ /**
2107
+ * What {@link importTexturePackerAtlas} accepts alongside the document.
2108
+ *
2109
+ * @public
2110
+ */
2111
+ interface TexturePackerImportOptions {
2112
+ /** The image address to write into the atlas. Defaults to the document's `meta.image`. */
2113
+ readonly image?: string;
2114
+ /** Whether to keep the `.png` on frame names. Defaults to `false`, which strips it. */
2115
+ readonly keepExtensions?: boolean;
2116
+ /** The min/mag filter. Defaults to `"linear"`. */
2117
+ readonly sampling?: "linear" | "nearest";
2118
+ /** Whether the image's RGB is already multiplied by its alpha. Defaults to `false`. */
2119
+ readonly premultipliedAlpha?: boolean;
2120
+ }
2121
+ /**
2122
+ * Converts a TexturePacker JSON export into an `ignifx.spriteatlas` document.
2123
+ *
2124
+ * Both of TexturePacker's JSON layouts are read and produce identical output for the same sheet:
2125
+ * the **hash** layout, whose `frames` is an object keyed by file name, and the **array** layout,
2126
+ * whose `frames` is an array of entries carrying a `filename`. Frame names lose their trailing file
2127
+ * extension (`hero_0.png` becomes `hero_0`) unless `keepExtensions` is set.
2128
+ *
2129
+ * A frame's `pivot` is used as-is when the document declares one: TexturePacker already writes
2130
+ * pivots normalised into `[0, 1]` against a top-left origin, which is exactly ignifx's convention.
2131
+ * Frames without one get the centre. A frame marked `trimmed` carries its `sourceSize` through so
2132
+ * the loader can lay the trimmed rectangle back inside its original bounds.
2133
+ *
2134
+ * @remarks
2135
+ * Rotated frames are rejected rather than silently drawn wrong — the sprite pipeline has no
2136
+ * per-frame rotation flag.
2137
+ *
2138
+ * `spriteSourceSize`'s **offset** (`x`/`y`) has no home in `SpriteFrameDefinition`, which records
2139
+ * only the untrimmed size, so a trimmed frame whose art is not centred in its source bounds may sit
2140
+ * slightly off. Pack with trimming disabled, or with `spriteSourceSize` centred, when that matters.
2141
+ *
2142
+ * @param json - The parsed TexturePacker document.
2143
+ * @param options - The image override, name handling, and sampling.
2144
+ * @returns The complete atlas document.
2145
+ * @throws IgnifxError with code `IGX-1109` when the document is not an object, when `frames` is
2146
+ * neither an object nor an array, when it is empty, when no image address can be found, when a
2147
+ * frame has no rectangle, or when a frame is rotated.
2148
+ *
2149
+ * @example
2150
+ * ```ts
2151
+ * const atlas = importTexturePackerAtlas(JSON.parse(text), { image: "2d/hero.png" });
2152
+ * atlas.frames[0]?.name; // "hero_0"
2153
+ * ```
2154
+ *
2155
+ * @public
2156
+ */
2157
+ export declare function importTexturePackerAtlas(json: unknown, options?: TexturePackerImportOptions): SpriteAtlasDefinition;
2158
+ /**
2159
+ * What {@link importAsepriteAtlas} accepts alongside the document.
2160
+ *
2161
+ * @public
2162
+ */
2163
+ interface AsepriteImportOptions {
2164
+ /** The image address to write into the atlas. Defaults to the document's `meta.image`. */
2165
+ readonly image?: string;
2166
+ /** The min/mag filter. Defaults to `"linear"`; pixel art wants `"nearest"`. */
2167
+ readonly sampling?: "linear" | "nearest";
2168
+ /** Whether the image's RGB is already multiplied by its alpha. Defaults to `false`. */
2169
+ readonly premultipliedAlpha?: boolean;
2170
+ }
2171
+ /**
2172
+ * Converts an Aseprite JSON sheet export into an `ignifx.spriteatlas` document.
2173
+ *
2174
+ * Aseprite writes a TexturePacker-shaped document — `frames` as either a hash or an array,
2175
+ * `meta.image`, `meta.size` — plus its own `meta.frameTags`, `meta.slices` and `meta.layers`. The
2176
+ * frame keys it produces are file-ish (`hero 0.aseprite`, `hero (idle) 0.aseprite`), so every one
2177
+ * is put through {@link asepriteFrameName}; `importAsepriteAnimations` uses the same normaliser,
2178
+ * which is what makes the imported clips and the imported atlas agree on names.
2179
+ *
2180
+ * A trimmed frame keeps its `sourceSize` so the loader can place the trimmed rectangle back inside
2181
+ * its original bounds.
2182
+ *
2183
+ * @remarks
2184
+ * Pivots are **best-effort**. Aseprite has no per-frame pivot; it has slices, which carry an
2185
+ * optional pivot in sprite-canvas pixels relative to the slice's own bounds and apply from their
2186
+ * key's `frame` index onwards. This importer takes the slice key with the greatest `frame` index at
2187
+ * or below the frame being converted (ties going to the earlier slice in document order) and
2188
+ * normalises `bounds + pivot` against the frame's untrimmed size, clamped into `[0, 1]`. That is
2189
+ * right for the common case — one slice covering the character, authored on an untrimmed sheet —
2190
+ * and approximate for anything else. Frames no slice covers get the centre.
2191
+ *
2192
+ * @param json - The parsed Aseprite document.
2193
+ * @param options - The image override and sampling.
2194
+ * @returns The complete atlas document.
2195
+ * @throws IgnifxError with code `IGX-1109` when the document is not an object, when `frames` is
2196
+ * neither an object nor an array, when it is empty, when no image address can be found, or when a
2197
+ * frame has no rectangle.
2198
+ *
2199
+ * @example
2200
+ * ```ts
2201
+ * const atlas = importAsepriteAtlas(JSON.parse(text), { sampling: "nearest" });
2202
+ * atlas.frames[0]?.name; // "hero_idle_0", from the key "hero (idle) 0.aseprite"
2203
+ * ```
2204
+ *
2205
+ * @public
2206
+ */
2207
+ export declare function importAsepriteAtlas(json: unknown, options?: AsepriteImportOptions): SpriteAtlasDefinition;
2208
+ //#endregion
2209
+ //#region src/atlas/loader.d.ts
2210
+ /**
2211
+ * Builds the loader for `.atlas.json` addresses.
2212
+ *
2213
+ * @returns The loader to register with `ctx.registerAssetLoader`.
2214
+ *
2215
+ * @example
2216
+ * ```ts
2217
+ * ctx.registerAssetLoader(createSpriteAtlasLoader());
2218
+ * ```
2219
+ *
2220
+ * @public
2221
+ */
2222
+ export declare function createSpriteAtlasLoader(): AssetLoader<SpriteAtlasAsset>;
2223
+ //#endregion
2224
+ //#region src/camera/camera-2d-follow.d.ts
2225
+ /**
2226
+ * `Camera2DFollow` (`docs/architecture/11-2d-toolkit.md` §2.1): the reference implementation of a
2227
+ * smooth, dead-zoned camera follow.
2228
+ *
2229
+ * It is a `Script`, not part of `Camera2D`, on purpose: following is a *policy*, and a game that
2230
+ * wants look-ahead, screen shake, or room-based snapping replaces this script without touching the
2231
+ * camera. `Camera2D` holds the fields (`follow`, `followDamping`, `followOffset`, `deadZone`)
2232
+ * because a scene file has to be able to author them; this script is what reads them.
2233
+ *
2234
+ * The move happens in `lateUpdate`, after every `update` has run, so the camera sees the frame's
2235
+ * final player position rather than last frame's — the single most common cause of a camera that
2236
+ * visibly lags its target by one frame.
2237
+ */
2238
+ /**
2239
+ * A damped, dead-zoned camera follow.
2240
+ *
2241
+ * @example
2242
+ * ```ts
2243
+ * const camera = app.world.createEntity({ name: "camera" });
2244
+ * const view = camera.addComponent(Camera2D);
2245
+ * view.follow = player;
2246
+ * view.deadZone = { x: 0.5, y: 0.3 };
2247
+ * camera.addComponent(Camera2DFollow);
2248
+ * ```
2249
+ *
2250
+ * @public
2251
+ */
2252
+ export declare class Camera2DFollow extends Script {
2253
+ #private;
2254
+ /** The registration id the serializer writes into scene files. */
2255
+ static typeId: string;
2256
+ /** One follow per entity. */
2257
+ static allowMultiple: boolean;
2258
+ /**
2259
+ * Finds the camera on this entity.
2260
+ */
2261
+ awake(): void;
2262
+ /**
2263
+ * Moves the camera toward its target.
2264
+ *
2265
+ * @remarks
2266
+ * The damping is frame-rate independent: the camera covers the same fraction of the remaining
2267
+ * distance per *second*, not per frame, so a 30 fps machine and a 144 fps machine see the same
2268
+ * motion. `followDamping` is the time constant in seconds; `0` snaps.
2269
+ *
2270
+ * @param deltaTime - The scaled frame delta.
2271
+ */
2272
+ lateUpdate(deltaTime: number): void;
2273
+ }
2274
+ //#endregion
2275
+ //#region src/errors.d.ts
2276
+ /**
2277
+ * The diagnostic codes `@ignifx/2d` owns. The 2D subsystem sits in the `11` range of
2278
+ * `docs/architecture/15-devtools-and-diagnostics.md` §1, so every code reads `IGX-11##`.
2279
+ *
2280
+ * The `11` range is shared with `@ignifx/physics-2d`, which owns `IGX-1101` (registering both
2281
+ * `physics()` and `physics2d()` on one world — `docs/architecture/11-2d-toolkit.md` §8) and the
2282
+ * codes from `IGX-1130` up. The 2D toolkit owns `IGX-1102` through `IGX-1129`.
2283
+ *
2284
+ * The table lives here rather than in `@ignifx/core`'s `CoreErrorCode`: an extension owns its own
2285
+ * codes and hands them to the app through `ExtensionContext.registerErrorCodes`
2286
+ * (`docs/architecture/04-extensions.md` §3).
2287
+ */
2288
+ /**
2289
+ * Every diagnostic code `@ignifx/2d` can throw or log, keyed by an intention-revealing name so call
2290
+ * sites read as prose and the compiler catches typos (coding standards §5.2).
2291
+ *
2292
+ * @example
2293
+ * ```ts
2294
+ * throw twoDError(TwoDErrorCode.unknownSortingLayer, "Foreground is not a declared sorting layer.", {
2295
+ * context: { sortingLayer: "Foreground" },
2296
+ * });
2297
+ * ```
2298
+ *
2299
+ * @public
2300
+ */
2301
+ export declare const TwoDErrorCode: {
2302
+ /** An atlas frame has no one-pixel extruded border, which a pixel-perfect camera will bleed. */
2303
+ readonly atlasFrameNotExtruded: "IGX-1102";
2304
+ /** A `.atlas.json` file is not an `ignifx.spriteatlas` document this build can read. */
2305
+ readonly invalidAtlasFile: "IGX-1103";
2306
+ /** A `.spriteanim.json` file is not an `ignifx.spriteanimation` document this build can read. */
2307
+ readonly invalidAnimationFile: "IGX-1104";
2308
+ /** A `.tilemap.json` file is not an `ignifx.tilemap` document this build can read. */
2309
+ readonly invalidTilemapFile: "IGX-1105";
2310
+ /** A sprite address names a frame the atlas does not declare. */
2311
+ readonly unknownFrame: "IGX-1106";
2312
+ /** A component named a sorting layer the `sortingLayers` settings section does not declare. */
2313
+ readonly unknownSortingLayer: "IGX-1107";
2314
+ /** `SpriteAnimator.play` named a clip the animation asset does not declare. */
2315
+ readonly unknownClip: "IGX-1108";
2316
+ /** A tilemap importer was handed a document it cannot read, or an unsupported projection. */
2317
+ readonly unsupportedImport: "IGX-1109";
2318
+ /** `app.twoD.registerTileObjectFactory` was called twice for one object type. */
2319
+ readonly duplicateObjectFactory: "IGX-1110";
2320
+ /** A tile coordinate is outside the tilemap layer's bounds. */
2321
+ readonly tileOutOfRange: "IGX-1111";
2322
+ /** A second `twoD()` extension was registered on one app. */
2323
+ readonly duplicateExtension: "IGX-1112";
2324
+ /** A `SpriteLayerEffect` declared the `custom` kind without a WGSL fragment body. */
2325
+ readonly missingShaderSource: "IGX-1113";
2326
+ };
2327
+ /**
2328
+ * The union of the codes the `TwoDErrorCode` table declares.
2329
+ *
2330
+ * @public
2331
+ */
2332
+ export type TwoDErrorCode = (typeof TwoDErrorCode)[keyof typeof TwoDErrorCode];
2333
+ /**
2334
+ * The one-line message template of every code, as `ExtensionContext.registerErrorCodes` wants it.
2335
+ * Context keys appear in braces, matching the core table's convention.
2336
+ *
2337
+ * @public
2338
+ */
2339
+ export declare const TWO_D_ERROR_MESSAGES: Readonly<Record<string, string>>;
2340
+ /**
2341
+ * Options accepted by {@link twoDError}: the same subset of `IgnifxErrorOptions` this package uses.
2342
+ *
2343
+ * @public
2344
+ */
2345
+ interface TwoDErrorOptions {
2346
+ /** Identifiers that locate the failure. */
2347
+ readonly context?: ErrorContext;
2348
+ /** One sentence telling the developer what to do about it. */
2349
+ readonly hint?: string;
2350
+ /** The failure being wrapped, when there is one. */
2351
+ readonly cause?: unknown;
2352
+ }
2353
+ /**
2354
+ * Builds an `IgnifxError` carrying one of this package's codes.
2355
+ *
2356
+ * @param code - The code from the `TwoDErrorCode` table.
2357
+ * @param message - The actionable development sentence.
2358
+ * @param options - Context identifiers, a remedy hint, and the wrapped cause.
2359
+ * @returns The error to throw or to reject with.
2360
+ *
2361
+ * @example
2362
+ * ```ts
2363
+ * throw twoDError(TwoDErrorCode.unknownClip, "hero.spriteanim.json declares no clip named jump.", {
2364
+ * context: { asset: "hero.spriteanim.json", clip: "jump" },
2365
+ * });
2366
+ * ```
2367
+ *
2368
+ * @public
2369
+ */
2370
+ export declare function twoDError(code: TwoDErrorCode, message: string, options?: TwoDErrorOptions): IgnifxError;
2371
+ //#endregion
2372
+ //#region src/extension.d.ts
2373
+ /**
2374
+ * The `@ignifx/2d` extension (`docs/architecture/04-extensions.md` §1,
2375
+ * `11-2d-toolkit.md` §1). Registering it is the whole installation: `twoD()` gives a game
2376
+ * `app.twoD`, seven components, the `Camera2DFollow` script, three asset types, the `twoD` settings
2377
+ * section, and the two systems that drive sprites — the `PreRender` sync and the `PostUpdate`
2378
+ * animation clock.
2379
+ */
2380
+ /**
2381
+ * What `twoD()` accepts. Every field overrides the matching `twoD` settings section value.
2382
+ *
2383
+ * @public
2384
+ */
2385
+ interface TwoDOptions {
2386
+ /** Whether sprites are the whole frame (`"sprite"`) or composite over the 3D scene (`"mixed"`). */
2387
+ readonly mode?: TwoDMode;
2388
+ /** How many pixels one world metre spans. */
2389
+ readonly pixelsPerUnit?: number;
2390
+ /** Which sorting layers draw back-to-front by world Y. */
2391
+ readonly ySort?: Readonly<Record<string, boolean>>;
2392
+ }
2393
+ /**
2394
+ * The `@ignifx/2d` extension factory.
2395
+ *
2396
+ * @param options - Overrides for the `twoD` settings section.
2397
+ * @returns The extension descriptor to pass to `createApp`.
2398
+ *
2399
+ * @example
2400
+ * ```ts
2401
+ * const app = await createApp({
2402
+ * canvas,
2403
+ * extensions: [twoD({ pixelsPerUnit: 16, ySort: { Default: true } })],
2404
+ * });
2405
+ * ```
2406
+ *
2407
+ * @public
2408
+ */
2409
+ export declare const twoD: (options?: TwoDOptions) => Extension;
2410
+ //#endregion
2411
+ //#region src/file-schemas.d.ts
2412
+ /**
2413
+ * Declarative schemas for the three file formats `@ignifx/2d` reads
2414
+ * (`docs/architecture/06-serialization-and-scene-format.md` §6).
2415
+ *
2416
+ * These exist for **documentation and tooling**, not for the loaders: a loader validates with its
2417
+ * own `defineX` function, which produces an actionable `IGX-11##` message naming the offending
2418
+ * frame or clip. The schema here is what `pnpm docs:schemas` renders into
2419
+ * `skills/ignifx/references/formats/`, and what a JSON Schema for an editor is generated from.
2420
+ *
2421
+ * The two descriptions are deliberately kept in one package so they cannot drift apart in a
2422
+ * release; a test asserts that a fixture accepted by the loader also validates against the schema.
2423
+ */
2424
+ /**
2425
+ * The `ignifx.spriteatlas` document schema.
2426
+ *
2427
+ * @returns The schema, built fresh so no module holds state (`CONSTITUTION.md` §3.5).
2428
+ *
2429
+ * @public
2430
+ */
2431
+ export declare function spriteAtlasFileSchema(): Schema;
2432
+ /**
2433
+ * The `ignifx.spriteanimation` document schema.
2434
+ *
2435
+ * @returns The schema, built fresh so no module holds state (`CONSTITUTION.md` §3.5).
2436
+ *
2437
+ * @public
2438
+ */
2439
+ export declare function spriteAnimationFileSchema(): Schema;
2440
+ /**
2441
+ * The `ignifx.tilemap` document schema.
2442
+ *
2443
+ * @returns The schema, built fresh so no module holds state (`CONSTITUTION.md` §3.5).
2444
+ *
2445
+ * @public
2446
+ */
2447
+ export declare function tilemapFileSchema(): Schema;
2448
+ //#endregion
2449
+ //#region src/math/coords.d.ts
2450
+ /**
2451
+ * The one place the ignifx 2D world (metres, **+Y up**, ADR-0011) is converted into Babylon Lite's
2452
+ * sprite space (pixels, **+Y down**) and back. Every other module in this package goes through
2453
+ * these functions, so the flip lives in exactly one file
2454
+ * (`docs/architecture/11-2d-toolkit.md` §1 and §3).
2455
+ *
2456
+ * Nothing here allocates: every conversion writes into a caller-owned vector (coding standards §7).
2457
+ */
2458
+ /**
2459
+ * The default pixels-per-unit, matching `twoD.pixelsPerUnit`
2460
+ * (`docs/architecture/11-2d-toolkit.md` §1). At 100, a 32-pixel sprite is 0.32 metres wide.
2461
+ *
2462
+ * @public
2463
+ */
2464
+ export declare const DEFAULT_PIXELS_PER_UNIT = 100;
2465
+ /**
2466
+ * Converts a world point in metres to a Lite layer-pixel point.
2467
+ *
2468
+ * @param x - The world x, in metres.
2469
+ * @param y - The world y, in metres, with +Y up.
2470
+ * @param pixelsPerUnit - The pixels one metre spans.
2471
+ * @param out - The vector to write.
2472
+ * @returns `out`, in pixels with +Y down.
2473
+ *
2474
+ * @example
2475
+ * ```ts
2476
+ * worldToPixelsToRef(1.5, 0.5, 100, out); // out is (150, -50)
2477
+ * ```
2478
+ *
2479
+ * @public
2480
+ */
2481
+ export declare function worldToPixelsToRef<TOut extends MutableVec2>(x: number, y: number, pixelsPerUnit: number, out: TOut): TOut;
2482
+ /**
2483
+ * Converts a Lite layer-pixel point back to world metres.
2484
+ *
2485
+ * @param xPx - The layer x, in pixels.
2486
+ * @param yPx - The layer y, in pixels, with +Y down.
2487
+ * @param pixelsPerUnit - The pixels one metre spans.
2488
+ * @param out - The vector to write.
2489
+ * @returns `out`, in metres with +Y up.
2490
+ *
2491
+ * @public
2492
+ */
2493
+ export declare function pixelsToWorldToRef<TOut extends MutableVec2>(xPx: number, yPx: number, pixelsPerUnit: number, out: TOut): TOut;
2494
+ /**
2495
+ * Converts an ignifx rotation about +Z into the rotation Lite gives a **sprite**.
2496
+ *
2497
+ * @remarks
2498
+ * `Transform.rotation2D` is degrees counter-clockwise in a +Y-up world. A sprite's quad is built in
2499
+ * Lite's +Y-down pixel space (`(corner - pivot) * sizePx`, then rotated), so the same visual turn is
2500
+ * the negated angle there. Verified against the sprite vertex shader in
2501
+ * `@babylonjs/lite@1.27.0`, `lib/sprite/sprite-pipeline.js` line 25.
2502
+ *
2503
+ * @param degrees - The ignifx rotation, in degrees counter-clockwise.
2504
+ * @returns The rotation to write to `Sprite2DProps.rotation`, in radians.
2505
+ *
2506
+ * @public
2507
+ */
2508
+ export declare function spriteRotationToLite(degrees: number): number;
2509
+ /**
2510
+ * Converts a Lite sprite rotation back to ignifx degrees.
2511
+ *
2512
+ * @param radians - The `Sprite2DProps.rotation` value.
2513
+ * @returns The ignifx rotation, in degrees counter-clockwise.
2514
+ *
2515
+ * @public
2516
+ */
2517
+ export declare function spriteRotationFromLite(radians: number): number;
2518
+ /**
2519
+ * Converts a `Camera2D` rotation into the rotation Lite gives a **view**.
2520
+ *
2521
+ * @remarks
2522
+ * A view rotation is applied to an already-flipped world offset rather than to a sprite-local
2523
+ * offset, and the two flips cancel — so unlike {@link spriteRotationToLite} the sign is kept.
2524
+ * Verified against `sprite2DWorldToScreenToRef` in `@babylonjs/lite@1.27.0`,
2525
+ * `lib/sprite/sprite-2d-view.js`.
2526
+ *
2527
+ * @param degrees - The camera rotation, in degrees counter-clockwise.
2528
+ * @returns The rotation to write to `Sprite2DView.rotation`, in radians.
2529
+ *
2530
+ * @public
2531
+ */
2532
+ export declare function viewRotationToLite(degrees: number): number;
2533
+ /**
2534
+ * The zoom a `Camera2D` needs so that `orthographicSize` metres fill half the viewport's height
2535
+ * (`docs/architecture/11-2d-toolkit.md` §2.1).
2536
+ *
2537
+ * @param viewportHeightPx - The viewport height, in pixels.
2538
+ * @param orthographicSize - The camera's half-height, in metres.
2539
+ * @param pixelsPerUnit - The pixels one metre spans.
2540
+ * @returns The `Sprite2DView.zoom` value; never zero, because Lite rejects a zero zoom.
2541
+ *
2542
+ * @public
2543
+ */
2544
+ export declare function zoomForSize(viewportHeightPx: number, orthographicSize: number, pixelsPerUnit: number): number;
2545
+ /**
2546
+ * The inverse of {@link zoomForSize}: what half-height a zoom shows.
2547
+ *
2548
+ * @param viewportHeightPx - The viewport height, in pixels.
2549
+ * @param zoom - The `Sprite2DView.zoom` value.
2550
+ * @param pixelsPerUnit - The pixels one metre spans.
2551
+ * @returns The half-height, in metres.
2552
+ *
2553
+ * @public
2554
+ */
2555
+ export declare function sizeForZoom(viewportHeightPx: number, zoom: number, pixelsPerUnit: number): number;
2556
+ /**
2557
+ * Snaps a zoom to the nearest usable integer for a pixel-perfect camera
2558
+ * (`docs/architecture/11-2d-toolkit.md` §4).
2559
+ *
2560
+ * @remarks
2561
+ * Zooms below 1 snap to the reciprocal of an integer (`1/2`, `1/3`, …) rather than to zero, so a
2562
+ * camera that is pulled far out still lands on a whole-texel scale.
2563
+ *
2564
+ * @param zoom - The continuous zoom {@link zoomForSize} produced.
2565
+ * @returns The snapped zoom, always greater than zero.
2566
+ *
2567
+ * @public
2568
+ */
2569
+ export declare function snapZoomToInteger(zoom: number): number;
2570
+ /**
2571
+ * Snaps a layer-pixel coordinate to the whole-pixel grid a pixel-perfect camera draws on.
2572
+ *
2573
+ * @param valuePx - The coordinate, in layer pixels.
2574
+ * @param zoom - The camera's zoom; at zoom 2 the grid step is half a layer pixel.
2575
+ * @returns The snapped coordinate.
2576
+ *
2577
+ * @public
2578
+ */
2579
+ export declare function snapPixel(valuePx: number, zoom: number): number;
2580
+ /**
2581
+ * Places the pivot of a sprite at a world point by offsetting the position Lite draws it at.
2582
+ *
2583
+ * @remarks
2584
+ * Lite's sprite pipeline has **one pivot per layer**, not per sprite or per frame: the vertex
2585
+ * shader reads `L.pivot` out of the layer uniform (`lib/sprite/sprite-pipeline.js` lines 25 and
2586
+ * 264–265), and the per-frame `SpriteFrame.pivot` is consumed only by the *billboard* family
2587
+ * (`lib/sprite/billboard-sprite.js` lines 166–167). ignifx therefore keeps every layer on the
2588
+ * centre pivot `[0.5, 0.5]` and moves the sprite instead, which is what makes a per-frame pivot and
2589
+ * `SpriteRenderer.pivotOverride` work at all.
2590
+ *
2591
+ * @param anchorXPx - The world anchor, in layer pixels.
2592
+ * @param anchorYPx - The world anchor, in layer pixels.
2593
+ * @param pivot - The pivot in `[0, 1]` of the frame; `[0, 0]` is top-left, `[1, 1]` bottom-right.
2594
+ * @param widthPx - The drawn width, in pixels.
2595
+ * @param heightPx - The drawn height, in pixels.
2596
+ * @param rotationRadians - The sprite's Lite rotation, which the offset turns with.
2597
+ * @param out - The vector to write.
2598
+ * @returns `out`: the value to write to `Sprite2DProps.positionPx`.
2599
+ *
2600
+ * @public
2601
+ */
2602
+ export declare function pivotedPositionToRef<TOut extends MutableVec2>(anchorXPx: number, anchorYPx: number, pivot: Vec2Like, widthPx: number, heightPx: number, rotationRadians: number, out: TOut): TOut;
2603
+ //#endregion
2604
+ //#region src/schemas.d.ts
2605
+ /**
2606
+ * The documentation harness's view of everything `@ignifx/2d` declares
2607
+ * (`scripts/README.md`, "Schema discovery convention";
2608
+ * `docs/architecture/16-docs-harness-and-skill.md` §3).
2609
+ *
2610
+ * The **function** form is what a package uses rather than a `schemas` object, because building the
2611
+ * record means calling `describeSchema` and module scope holds declarations only
2612
+ * (`CONSTITUTION.md` §3.5).
2613
+ */
2614
+ /**
2615
+ * Describes the `ignifx.spriteatlas` file format.
2616
+ *
2617
+ * @returns The record `pnpm docs:schemas` renders.
2618
+ *
2619
+ * @public
2620
+ */
2621
+ export declare function describeSpriteAtlasFormat(): SchemaDescription;
2622
+ /**
2623
+ * Describes the `ignifx.spriteanimation` file format.
2624
+ *
2625
+ * @returns The record `pnpm docs:schemas` renders.
2626
+ *
2627
+ * @public
2628
+ */
2629
+ export declare function describeSpriteAnimationFormat(): SchemaDescription;
2630
+ /**
2631
+ * Describes the `ignifx.tilemap` file format.
2632
+ *
2633
+ * @returns The record `pnpm docs:schemas` renders.
2634
+ *
2635
+ * @public
2636
+ */
2637
+ export declare function describeTilemapFormat(): SchemaDescription;
2638
+ /**
2639
+ * The JSON Schema a tool validates a `.atlas.json` document against.
2640
+ *
2641
+ * @returns The JSON Schema object.
2642
+ *
2643
+ * @public
2644
+ */
2645
+ export declare function spriteAtlasJsonSchema(): JsonSchemaObject;
2646
+ /**
2647
+ * The JSON Schema a tool validates a `.spriteanim.json` document against.
2648
+ *
2649
+ * @returns The JSON Schema object.
2650
+ *
2651
+ * @public
2652
+ */
2653
+ export declare function spriteAnimationJsonSchema(): JsonSchemaObject;
2654
+ /**
2655
+ * The JSON Schema a tool validates a `.tilemap.json` document against.
2656
+ *
2657
+ * @returns The JSON Schema object.
2658
+ *
2659
+ * @public
2660
+ */
2661
+ export declare function tilemapJsonSchema(): JsonSchemaObject;
2662
+ /**
2663
+ * Describes every component and file format this package declares, for the documentation harness.
2664
+ *
2665
+ * @returns The records, keyed by namespaced type id.
2666
+ *
2667
+ * @example
2668
+ * ```ts
2669
+ * describeTwoDSchemas()["ignifx/Camera2D"].fields["orthographicSize"].default; // 5
2670
+ * ```
2671
+ *
2672
+ * @public
2673
+ */
2674
+ export declare function describeTwoDSchemas(): Readonly<Record<string, SchemaDescription>>;
2675
+ /**
2676
+ * The name `pnpm docs:schemas` discovers this package's schemas under.
2677
+ *
2678
+ * @returns The same records {@link describeTwoDSchemas} returns.
2679
+ *
2680
+ * @public
2681
+ */
2682
+ export declare function describeSchemas(): Readonly<Record<string, SchemaDescription>>;
2683
+ //#endregion
2684
+ //#region src/service/sync-system.d.ts
2685
+ /**
2686
+ * The 2D sync system (`docs/architecture/11-2d-toolkit.md` §2.2,
2687
+ * `01-lifecycle-and-time.md` §3): once per frame, in `PreRender`, it selects the active
2688
+ * `Camera2D`, writes every world layer's view, and pushes every sprite whose transform or fields
2689
+ * changed into its Lite layer.
2690
+ *
2691
+ * ## Ordering
2692
+ *
2693
+ * `docs/architecture/11-2d-toolkit.md` §2.2 asks for `PreRender` order `-400`, but
2694
+ * `@ignifx/audio`'s spatial pump already occupies that exact slot
2695
+ * (`AUDIO_PUMP_ORDER`, `docs/architecture/10-audio.md` §5). Equal orders are broken by
2696
+ * registration order, which makes the interleaving depend on the order a game lists its
2697
+ * extensions in. The two systems touch nothing in common, so the tie would be harmless — but a
2698
+ * frame order that changes with an argument list is not something to leave in place, so 2D takes
2699
+ * {@link TWO_D_SYNC_ORDER} instead: after physics interpolation at `-500` has written the frame's
2700
+ * final transforms, before audio at `-400`, and well before core's render sync at `900`.
2701
+ *
2702
+ * ## Cost
2703
+ *
2704
+ * A sprite that did not move and whose fields did not change costs one integer comparison
2705
+ * (`Transform.worldMatrixVersion`), and an entity marked `isStatic` costs that comparison only
2706
+ * until its first sync. That is what keeps a 100x100 tilemap at zero per-frame sync cost once its
2707
+ * chunks are up (spike S6.1).
2708
+ */
2709
+ /**
2710
+ * The `PreRender` order the 2D sync system runs at.
2711
+ *
2712
+ * @remarks
2713
+ * `-450`, not the `-400` `docs/architecture/11-2d-toolkit.md` §2.2 names, because audio's pump
2714
+ * already holds `-400`. See the module's own remarks.
2715
+ *
2716
+ * @public
2717
+ */
2718
+ export declare const TWO_D_SYNC_ORDER = -450;
2719
+ /**
2720
+ * Writes sprites and camera views into Babylon Lite once per frame.
2721
+ *
2722
+ * @public
2723
+ */
2724
+ export declare class TwoDSyncSystem implements System {
2725
+ #private;
2726
+ /** The name diagnostics and error reports use. */
2727
+ readonly name = "ignifx/2d-sync";
2728
+ /**
2729
+ * Builds the system.
2730
+ *
2731
+ * @param runtime - The 2D runtime state: settings, the layer registry, and the Lite renderer.
2732
+ */
2733
+ constructor(runtime: TwoDRuntime);
2734
+ /**
2735
+ * Runs one frame's synchronisation.
2736
+ *
2737
+ * @param ctx - The world, clock, phase, and delta.
2738
+ */
2739
+ update(ctx: SystemContext): void;
2740
+ /**
2741
+ * Drops every layer when the world goes away.
2742
+ *
2743
+ * @param _world - The world being disposed.
2744
+ */
2745
+ onWorldDisposed(_world: World): void;
2746
+ }
2747
+ /**
2748
+ * Picks the camera the frame draws through: the highest-priority enabled `Camera2D`.
2749
+ *
2750
+ * @param world - The world to search.
2751
+ * @returns The camera, or `null` when the world has none enabled.
2752
+ */
2753
+ export declare function selectCamera(world: World): Camera2D | null;
2754
+ //#endregion
2755
+ //#region src/sprite/sprite-layer-effect.d.ts
2756
+ /**
2757
+ * `SpriteLayerEffect` (`docs/architecture/11-2d-toolkit.md` §6): a per-layer custom fragment shader.
2758
+ *
2759
+ * Lite's 2D path has no lighting model, so effects are what a 2D game reaches for instead: a tint,
2760
+ * a dissolve, water, a heat shimmer. A layer created with a `customShader`
2761
+ * (`Sprite2DLayerOptions.customShader`, `index.d.ts` 11934) runs a WGSL fragment body with a
2762
+ * built-in `fx.time` clock and a `fx.params` vec4 the component writes every frame through
2763
+ * `setSprite2DShaderParams` (`index.d.ts` 11074).
2764
+ *
2765
+ * ## The one-shader-per-layer constraint
2766
+ *
2767
+ * `Sprite2DLayer.customShader` is `readonly` and is only set at creation. A layer's shader
2768
+ * therefore cannot change once sprites are in it, so `SpriteLayerEffect` has to exist **before**
2769
+ * the first sprite on its sorting layer is synced — put it in the scene file, or add it in
2770
+ * `awake`, not halfway through a level.
2771
+ */
2772
+ /** The built-in effects, in the order an inspector should list them. @public */
2773
+ export declare const SPRITE_EFFECT_KINDS: readonly ["tint", "custom"];
2774
+ /**
2775
+ * Which shader a `SpriteLayerEffect` installs.
2776
+ *
2777
+ * @public
2778
+ */
2779
+ type SpriteEffectKind = (typeof SPRITE_EFFECT_KINDS)[number];
2780
+ /**
2781
+ * The WGSL body of the built-in `tint` effect.
2782
+ *
2783
+ * @remarks
2784
+ * Multiplies the sampled texel by `fx.params.rgb` and scales its alpha by `fx.params.a`, which is
2785
+ * a per-layer tint that a per-sprite `color` cannot express — every sprite in the layer fades
2786
+ * together, in one uniform write, rather than in one instance write each.
2787
+ *
2788
+ * @public
2789
+ */
2790
+ export declare const TINT_EFFECT_WGSL = "let texel = textureSample(atlasTex, atlasSamp, uv); return vec4f(texel.rgb * fx.params.rgb, texel.a * fx.params.a);";
2791
+ /**
2792
+ * A per-layer shader effect.
2793
+ *
2794
+ * @example
2795
+ * ```ts
2796
+ * const dusk = app.world.createEntity({ name: "dusk" }).addComponent(SpriteLayerEffect);
2797
+ * dusk.sortingLayer = "Default";
2798
+ * dusk.kind = "tint";
2799
+ * dusk.tint = { r: 0.6, g: 0.6, b: 0.9, a: 1 };
2800
+ * ```
2801
+ *
2802
+ * @public
2803
+ */
2804
+ export declare class SpriteLayerEffect extends Component {
2805
+ /** The registration id the serializer writes into scene files. */
2806
+ static typeId: string;
2807
+ /** One effect per entity; several entities may each drive a different sorting layer. */
2808
+ static allowMultiple: boolean;
2809
+ /** The declarative fields (ADR-0004). */
2810
+ static schema: Schema;
2811
+ /** Which sorting layer the effect applies to. */
2812
+ sortingLayer: string;
2813
+ /** Which shader to install. */
2814
+ kind: SpriteEffectKind;
2815
+ /** The colour the `tint` effect multiplies by, written into `fx.params`. */
2816
+ tint: {
2817
+ readonly r: number;
2818
+ readonly g: number;
2819
+ readonly b: number;
2820
+ readonly a: number;
2821
+ };
2822
+ /** The `fx.params` vec4 a `custom` shader reads. */
2823
+ params: Vec4Like;
2824
+ /** The WGSL fragment body a `custom` effect installs. */
2825
+ shader: string;
2826
+ /**
2827
+ * Builds an effect with the schema's defaults.
2828
+ */
2829
+ constructor();
2830
+ /**
2831
+ * The WGSL fragment body this effect installs.
2832
+ *
2833
+ * @returns The shader source.
2834
+ * @throws IgnifxError with code `IGX-1113` when `kind` is `"custom"` and `shader` is empty.
2835
+ */
2836
+ source(): string;
2837
+ /**
2838
+ * The `fx.params` vec4 to write this frame.
2839
+ *
2840
+ * @param out - The four numbers to fill.
2841
+ * @returns `out`.
2842
+ *
2843
+ * @internal
2844
+ */
2845
+ writeParams(out: Float32Array): Float32Array;
2846
+ }
2847
+ //#endregion
2848
+ //#region src/tilemap/collision-data.d.ts
2849
+ /**
2850
+ * The collision footprint of a single tile, expressed in **cell-local metres** with the origin at
2851
+ * the bottom-left corner of the cell (ignifx 2D is +Y up — `docs/adr/0011`).
2852
+ *
2853
+ * @remarks
2854
+ * `"none"` is the shape of a tile that renders but does not collide; it is the default for a tile
2855
+ * whose tileset entry declares no collider.
2856
+ *
2857
+ * @public
2858
+ */
2859
+ type TileCollisionShape = {
2860
+ /** Discriminant: an axis-aligned box. */
2861
+ readonly kind: "box";
2862
+ /** The box's left edge, in cell-local metres. */
2863
+ readonly x: number;
2864
+ /** The box's bottom edge, in cell-local metres. */
2865
+ readonly y: number;
2866
+ /** The box's width, in metres. */
2867
+ readonly width: number;
2868
+ /** The box's height, in metres. */
2869
+ readonly height: number;
2870
+ } | {
2871
+ /** Discriminant: a convex or concave outline. */
2872
+ readonly kind: "polygon";
2873
+ /** The outline's vertices in cell-local metres, wound counter-clockwise. */
2874
+ readonly points: readonly Vec2Like[];
2875
+ } | {
2876
+ /** Discriminant: the tile does not collide. */
2877
+ readonly kind: "none";
2878
+ };
2879
+ /**
2880
+ * Everything a physics backend needs to know about one tile of a tileset.
2881
+ *
2882
+ * @public
2883
+ */
2884
+ interface TileCollisionInfo {
2885
+ /** The tile's collision footprint in cell-local metres. */
2886
+ readonly shape: TileCollisionShape;
2887
+ /** Whether the tile is a one-way platform (solid only when crossed from above). */
2888
+ readonly oneWay: boolean;
2889
+ /** The tile's custom properties, carried through from the tileset or the importer. */
2890
+ readonly properties: Readonly<Record<string, string | number | boolean>>;
2891
+ }
2892
+ /**
2893
+ * The merged collision geometry of one chunk of a tilemap, in **world-space metres relative to the
2894
+ * tilemap entity's origin**.
2895
+ *
2896
+ * @remarks
2897
+ * Adjacent solid tiles are merged into as few polygons as possible before they reach this shape, so
2898
+ * a solid 3x2 block of tiles arrives as a single six-vertex rectangle rather than six boxes.
2899
+ *
2900
+ * @public
2901
+ */
2902
+ interface TilemapCollisionChunk {
2903
+ /** The chunk's column index, in chunks. */
2904
+ readonly chunkX: number;
2905
+ /** The chunk's row index, in chunks. */
2906
+ readonly chunkY: number;
2907
+ /** The merged solid outlines, each wound counter-clockwise. */
2908
+ readonly polygons: readonly (readonly Vec2Like[])[];
2909
+ /** The one-way platform edges, each a `[from, to]` pair with solid side to the left of `from → to`. */
2910
+ readonly oneWayEdges: readonly (readonly [Vec2Like, Vec2Like])[];
2911
+ }
2912
+ /**
2913
+ * The whole collision surface of a `Tilemap`, chunked so a physics backend can rebuild only the
2914
+ * chunks that changed.
2915
+ *
2916
+ * @remarks
2917
+ * `version` increments whenever any chunk changes; a backend that caches colliders compares it to
2918
+ * the version it last consumed and rebuilds when they differ. `Tilemap.onCollisionChanged` fires at
2919
+ * the same moment.
2920
+ *
2921
+ * @public
2922
+ */
2923
+ interface TilemapCollisionData {
2924
+ /** The edge length of one cell, in metres. */
2925
+ readonly cellSize: number;
2926
+ /** The edge length of one chunk, in cells. */
2927
+ readonly chunkSize: number;
2928
+ /** The chunks that carry at least one collider; empty chunks are omitted. */
2929
+ readonly chunks: readonly TilemapCollisionChunk[];
2930
+ /** Increments on every change to the merged geometry. */
2931
+ readonly version: number;
2932
+ }
2933
+ //#endregion
2934
+ //#region src/tilemap/collision-merge.d.ts
2935
+ /**
2936
+ * The greedy merge that turns a grid of per-tile collision shapes into the handful of polygons a 2D
2937
+ * physics backend actually wants (`docs/architecture/11-2d-toolkit.md` §2.5).
2938
+ *
2939
+ * A tilemap with ten thousand solid cells must not become ten thousand colliders: Rapier would
2940
+ * spend its whole broad-phase on them and the island solver would never sleep. Merging a solid
2941
+ * region into one polygon per rectangle is the standard fix, and it is worth doing at rebuild time
2942
+ * because a rebuild is rare and a step is not.
2943
+ */
2944
+ /**
2945
+ * The grid {@link mergeTileCollisions} walks.
2946
+ *
2947
+ * @public
2948
+ */
2949
+ interface CollisionMergeOptions {
2950
+ /** The edge length of one cell, in metres. */
2951
+ readonly cellSize: number;
2952
+ /** The edge length of one chunk, in cells; `32` is what `TilemapRenderer` uses. */
2953
+ readonly chunkSize: number;
2954
+ /** The grid's width, in cells. */
2955
+ readonly width: number;
2956
+ /** The grid's height, in cells. */
2957
+ readonly height: number;
2958
+ }
2959
+ /**
2960
+ * Whether a tile's collider fills its whole cell and is not a one-way platform — the only shape the
2961
+ * rectangle merge can absorb.
2962
+ *
2963
+ * @param info - The tile's collision info, in cell-local metres.
2964
+ * @param cellSize - The edge length of one cell, in metres.
2965
+ * @returns Whether the tile is a plain, full-cell solid.
2966
+ *
2967
+ * @example
2968
+ * ```ts
2969
+ * isFullCellSolid({ shape: { kind: "box", x: 0, y: 0, width: 1, height: 1 }, oneWay: false, properties: {} }, 1);
2970
+ * // true
2971
+ * ```
2972
+ *
2973
+ * @public
2974
+ */
2975
+ export declare function isFullCellSolid(info: TileCollisionInfo, cellSize: number): boolean;
2976
+ /**
2977
+ * Merges a grid of per-tile collision shapes into chunked, world-space polygons.
2978
+ *
2979
+ * @remarks
2980
+ * **Coordinates.** `infoAt` is called with cell coordinates in which `y = 0` is the **bottom** row,
2981
+ * because the ignifx 2D world is +Y up; a caller reading a `TilemapLayerDefinition`, whose rows run
2982
+ * top-first, indexes it as `(height - 1 - y) * width + x`. Everything this function emits is world
2983
+ * metres relative to the tilemap's origin, so cell `(x, y)` spans
2984
+ * `[x·cellSize, (x+1)·cellSize] × [y·cellSize, (y+1)·cellSize]`.
2985
+ *
2986
+ * **The merge.** Each chunk is handled independently, so a later edit rebuilds one chunk rather than
2987
+ * the map. Inside a chunk, cells that {@link isFullCellSolid} accepts go into a boolean grid and are
2988
+ * merged in two greedy passes: first every row is cut into maximal horizontal runs, then a run
2989
+ * extends upwards for as long as the row above holds a run with exactly the same span, which is
2990
+ * marked consumed. Each surviving block is emitted as one counter-clockwise rectangle. It is the
2991
+ * classic row-then-column greedy mesher: linear in cells plus a small scan per row, and optimal for
2992
+ * rectangles while deliberately not optimal in general — an L-shape comes out as two rectangles, not
2993
+ * one six-vertex polygon, and that is the trade the algorithm makes for being O(n).
2994
+ *
2995
+ * Anything the rectangle pass cannot absorb — a partial box, a slope polygon — is emitted as its own
2996
+ * polygon, translated into world metres. Its winding is already counter-clockwise, because
2997
+ * `tileCollisionInfo` guarantees it.
2998
+ *
2999
+ * **One-way platforms.** A one-way tile contributes no polygon at all; it contributes its collider's
3000
+ * **top edge** to `oneWayEdges`. The winding follows the same rule as a polygon: the solid material
3001
+ * is to the **left** of `from → to`. For a directed edge `d = to − from`, "left" is `d` rotated a
3002
+ * quarter turn counter-clockwise, `(−dy, dx)`. An upward-facing platform is solid *below* its
3003
+ * surface — that is the half you cannot pass through once you have landed — so we need
3004
+ * `(−dy, dx) = (0, −1)`, giving `dy = 0` and `dx = −1`. The edge therefore runs from its **right**
3005
+ * end to its **left** end.
3006
+ *
3007
+ * Chunks that end up with neither a polygon nor a one-way edge are omitted entirely.
3008
+ *
3009
+ * @param infoAt - The per-cell collision info, in cell coordinates with `y = 0` at the bottom.
3010
+ * @param options - The cell size, chunk size, and grid extent.
3011
+ * @param version - The version stamp to carry into the result; callers increment it per rebuild.
3012
+ * @returns The chunked collision data.
3013
+ *
3014
+ * @example
3015
+ * ```ts
3016
+ * const data = mergeTileCollisions((x, y) => tileCollisionInfo(map, tileAt(x, y)), {
3017
+ * cellSize: map.cellSize,
3018
+ * chunkSize: 32,
3019
+ * width: map.width,
3020
+ * height: map.height,
3021
+ * }, 1);
3022
+ * ```
3023
+ *
3024
+ * @public
3025
+ */
3026
+ export declare function mergeTileCollisions(infoAt: (x: number, y: number) => TileCollisionInfo, options: CollisionMergeOptions, version: number): TilemapCollisionData;
3027
+ //#endregion
3028
+ //#region src/tilemap/definition.d.ts
3029
+ /**
3030
+ * The `ignifx.tilemap` document — the `.tilemap.json` file that names tile sizes, tilesets, tile
3031
+ * layers and object layers (`docs/architecture/06-serialization-and-scene-format.md` §6,
3032
+ * `11-2d-toolkit.md` §2.5).
3033
+ *
3034
+ * Two coordinate conventions meet in this file and it is worth stating both loudly, because getting
3035
+ * them backwards is the single easiest mistake to make in a tilemap pipeline:
3036
+ *
3037
+ * - **Authoring space** (everything on `TileColliderDefinition` and every editor this package
3038
+ * imports from) is cell-normalised `[0, 1]` with the origin at the **top-left** of the cell and
3039
+ * +Y pointing **down**. Tiled and LDtk both emit pixels in that orientation, and the importers
3040
+ * divide by the tile size rather than flipping.
3041
+ * - **Runtime space** (`TileCollisionShape`, `TilemapCollisionData`, and every world coordinate on
3042
+ * `TilemapObjectDefinition`) is metres with the origin at the **bottom-left** and +Y pointing
3043
+ * **up**, because that is the ignifx 2D world (ADR-0011).
3044
+ *
3045
+ * {@link tileCollisionInfo} is the one function that crosses between them, so the flip lives in
3046
+ * exactly one place — the same discipline `../math/coords.ts` applies to the render path.
3047
+ */
3048
+ /**
3049
+ * The `format` discriminator every `.tilemap.json` document carries.
3050
+ *
3051
+ * @public
3052
+ */
3053
+ export declare const TILEMAP_FORMAT = "ignifx.tilemap";
3054
+ /**
3055
+ * The document version this build reads and writes.
3056
+ *
3057
+ * @public
3058
+ */
3059
+ export declare const TILEMAP_FORMAT_VERSION = 1;
3060
+ /**
3061
+ * The asset type name the loader registers.
3062
+ *
3063
+ * @public
3064
+ */
3065
+ export declare const TILEMAP_ASSET_TYPE = "tilemap";
3066
+ /**
3067
+ * The address suffixes that select the tilemap loader.
3068
+ *
3069
+ * @public
3070
+ */
3071
+ export declare const TILEMAP_FILE_EXTENSIONS: readonly string[];
3072
+ /**
3073
+ * The tile id that means "this cell is empty"; no tileset may claim it.
3074
+ *
3075
+ * @public
3076
+ */
3077
+ export declare const EMPTY_TILE_ID = 0;
3078
+ /**
3079
+ * A tile's collision footprint **as authored**: cell-normalised `[0, 1]` units with the origin at
3080
+ * the cell's **top-left** corner and +Y pointing **down**.
3081
+ *
3082
+ * @remarks
3083
+ * This is deliberately *not* {@link TileCollisionShape}, which is cell-local **metres** with a
3084
+ * **bottom-left** origin, +Y up and counter-clockwise winding. Editors work top-down and the
3085
+ * physics world works bottom-up; {@link tileCollisionInfo} converts, and nothing else should.
3086
+ *
3087
+ * A box covering the top quarter of a cell — the usual one-way platform — is
3088
+ * `{ kind: "box", x: 0, y: 0, width: 1, height: 0.25, oneWay: true }`.
3089
+ *
3090
+ * @public
3091
+ */
3092
+ type TileColliderDefinition = {
3093
+ /** Discriminant: an axis-aligned box. */
3094
+ readonly kind: "box";
3095
+ /** The box's left edge, in cell-normalised units. */
3096
+ readonly x: number;
3097
+ /** The box's **top** edge, in cell-normalised units measured downwards from the cell's top. */
3098
+ readonly y: number;
3099
+ /** The box's width, in cell-normalised units. */
3100
+ readonly width: number;
3101
+ /** The box's height, in cell-normalised units. */
3102
+ readonly height: number;
3103
+ /** Whether the tile is a one-way platform. Defaults to `false`. */
3104
+ readonly oneWay?: boolean;
3105
+ } | {
3106
+ /** Discriminant: an outline. */
3107
+ readonly kind: "polygon";
3108
+ /** The vertices in cell-normalised units with a top-left origin, in the editor's winding. */
3109
+ readonly points: readonly Vec2Like[];
3110
+ /** Whether the tile is a one-way platform. Defaults to `false`. */
3111
+ readonly oneWay?: boolean;
3112
+ } | {
3113
+ /** Discriminant: the tile renders but does not collide. */
3114
+ readonly kind: "none";
3115
+ };
3116
+ /**
3117
+ * One frame of an animated tile.
3118
+ *
3119
+ * @public
3120
+ */
3121
+ interface TileAnimationFrame {
3122
+ /** The atlas frame name drawn during this step. */
3123
+ readonly frame: string;
3124
+ /** How long the step lasts, in milliseconds. */
3125
+ readonly durationMs: number;
3126
+ }
3127
+ /**
3128
+ * One tile of a tileset: what it draws, what it collides with, and what it carries.
3129
+ *
3130
+ * @public
3131
+ */
3132
+ interface TileDefinition {
3133
+ /** The tile's index **within its tileset**, zero-based; the global id is `tileset.firstId + id`. */
3134
+ readonly id: number;
3135
+ /** The atlas frame the tile draws, by name. */
3136
+ readonly frame: string;
3137
+ /** The collision footprint, in cell-normalised top-left-origin units. Absent means no collider. */
3138
+ readonly collider?: TileColliderDefinition;
3139
+ /** The tile's custom properties, carried through from the editor. */
3140
+ readonly properties?: Readonly<Record<string, string | number | boolean>>;
3141
+ /** The animation frames, when the tile animates. A single frame is treated as a static tile. */
3142
+ readonly animation?: readonly TileAnimationFrame[];
3143
+ }
3144
+ /**
3145
+ * A block of tiles cut from one atlas, occupying a contiguous run of global tile ids.
3146
+ *
3147
+ * @public
3148
+ */
3149
+ interface TilesetDefinition {
3150
+ /** The tileset's name, unique within the document; also the frame-name prefix. */
3151
+ readonly name: string;
3152
+ /** The address of the `.atlas.json` the frames come from; empty for a collision-only tileset. */
3153
+ readonly atlas: string;
3154
+ /** The global id of this tileset's tile `0`. Always at least `1`, because `0` means empty. */
3155
+ readonly firstId: number;
3156
+ /** The tiles, indexed by their local {@link TileDefinition.id}. */
3157
+ readonly tiles: readonly TileDefinition[];
3158
+ }
3159
+ /**
3160
+ * One layer of tiles.
3161
+ *
3162
+ * @remarks
3163
+ * `tiles` is **always** the dense, decoded array in the parsed form: `width * height` global tile
3164
+ * ids in row-major order with the **top** row first, which is how every editor stores a grid.
3165
+ * `0` ({@link EMPTY_TILE_ID}) means the cell is empty. Runtime code that thinks in +Y-up cell
3166
+ * coordinates reads index `(height - 1 - cellY) * width + cellX`.
3167
+ *
3168
+ * @public
3169
+ */
3170
+ interface TilemapLayerDefinition {
3171
+ /** The layer's name, unique within the document. */
3172
+ readonly name: string;
3173
+ /** The sorting layer the tiles draw in (`docs/architecture/11-2d-toolkit.md` §1). */
3174
+ readonly sortingLayer: string;
3175
+ /** The order within the sorting layer; higher draws in front. */
3176
+ readonly orderInLayer: number;
3177
+ /** The layer's opacity in `[0, 1]`. */
3178
+ readonly opacity: number;
3179
+ /** The parallax multiplier; `{ x: 1, y: 1 }` moves with the camera. */
3180
+ readonly parallax: Vec2Like;
3181
+ /** Whether the layer contributes collision geometry. */
3182
+ readonly collision: boolean;
3183
+ /** The layer's width, in cells. */
3184
+ readonly width: number;
3185
+ /** The layer's height, in cells. */
3186
+ readonly height: number;
3187
+ /** `width * height` global tile ids, row-major, top row first. */
3188
+ readonly tiles: readonly number[];
3189
+ }
3190
+ /**
3191
+ * One object placed on the map, to be turned into an entity by a registered `TileObjectFactory`.
3192
+ *
3193
+ * @remarks
3194
+ * `x`, `y`, `width` and `height` are **world metres with +Y up**, and `x`/`y` name the object's
3195
+ * **bottom-left** corner. Importers do the conversion out of the editor's top-left pixel space, so
3196
+ * nothing downstream has to know what editor the map came from.
3197
+ *
3198
+ * @public
3199
+ */
3200
+ interface TilemapObjectDefinition {
3201
+ /** The object's name, as authored; not required to be unique. */
3202
+ readonly name: string;
3203
+ /** The object's type — what `app.twoD.registerTileObjectFactory` keys on. */
3204
+ readonly type: string;
3205
+ /** The left edge, in world metres. */
3206
+ readonly x: number;
3207
+ /** The bottom edge, in world metres, +Y up. */
3208
+ readonly y: number;
3209
+ /** The width, in world metres. */
3210
+ readonly width: number;
3211
+ /** The height, in world metres. */
3212
+ readonly height: number;
3213
+ /** The object's custom properties. */
3214
+ readonly properties: Readonly<Record<string, string | number | boolean>>;
3215
+ }
3216
+ /**
3217
+ * The parsed `.tilemap.json` document.
3218
+ *
3219
+ * @example
3220
+ * ```ts
3221
+ * const map = defineTilemap({
3222
+ * tileWidth: 32,
3223
+ * width: 2,
3224
+ * height: 1,
3225
+ * tilesets: [{ name: "hero", atlas: "2d/hero.atlas.json", firstId: 1, tiles: [{ id: 0, frame: "hero_0" }] }],
3226
+ * layers: [{ name: "Ground", tiles: [1, 0] }],
3227
+ * });
3228
+ * map.cellSize; // 0.32 — 32 px at the default 100 pixels per unit
3229
+ * ```
3230
+ *
3231
+ * @public
3232
+ */
3233
+ interface TilemapDefinition {
3234
+ /** Always `"ignifx.tilemap"`. */
3235
+ readonly format: typeof TILEMAP_FORMAT;
3236
+ /** Always `1` in this build. */
3237
+ readonly version: number;
3238
+ /** The width of one tile, in **pixels**. */
3239
+ readonly tileWidth: number;
3240
+ /** The height of one tile, in **pixels**. */
3241
+ readonly tileHeight: number;
3242
+ /**
3243
+ * The world size of one cell, in metres — `tileWidth / pixelsPerUnit`.
3244
+ *
3245
+ * @remarks
3246
+ * Collision uses this single number on both axes. A map whose tiles are not square still gets a
3247
+ * square collision cell; that is a deliberate MVP limitation and it is why the importers warn
3248
+ * nothing and simply record both pixel sizes above.
3249
+ */
3250
+ readonly cellSize: number;
3251
+ /** The map's width, in cells. */
3252
+ readonly width: number;
3253
+ /** The map's height, in cells. */
3254
+ readonly height: number;
3255
+ /** The tilesets, sorted by ascending {@link TilesetDefinition.firstId}. */
3256
+ readonly tilesets: readonly TilesetDefinition[];
3257
+ /** The tile layers, back to front: index `0` draws behind index `1`. */
3258
+ readonly layers: readonly TilemapLayerDefinition[];
3259
+ /** The objects gathered from every object layer, in document order. */
3260
+ readonly objects: readonly TilemapObjectDefinition[];
3261
+ /** The map's custom properties. */
3262
+ readonly properties: Readonly<Record<string, string | number | boolean>>;
3263
+ }
3264
+ /**
3265
+ * A run-length-encoded tile array, as a `.tilemap.json` may store it to keep sparse maps small.
3266
+ *
3267
+ * @public
3268
+ */
3269
+ interface TileRleData {
3270
+ /** Flattened `[count, value, count, value, …]` pairs; see {@link decodeTileRle}. */
3271
+ readonly rle: readonly number[];
3272
+ }
3273
+ /**
3274
+ * What {@link defineTilemap} accepts for one layer: every defaulted field optional, and `tiles`
3275
+ * either dense or run-length encoded.
3276
+ *
3277
+ * @public
3278
+ */
3279
+ interface TilemapLayerInput {
3280
+ /** The layer's name, unique within the document. */
3281
+ readonly name: string;
3282
+ /** The sorting layer. Defaults to `"Default"`. */
3283
+ readonly sortingLayer?: string;
3284
+ /** The order within the sorting layer. Defaults to `0`. */
3285
+ readonly orderInLayer?: number;
3286
+ /** The opacity in `[0, 1]`. Defaults to `1`. */
3287
+ readonly opacity?: number;
3288
+ /** The parallax multiplier. Defaults to `{ x: 1, y: 1 }`. */
3289
+ readonly parallax?: Vec2Like;
3290
+ /** Whether the layer collides. Defaults to `false`. */
3291
+ readonly collision?: boolean;
3292
+ /** The layer's width in cells. Defaults to the map's width. */
3293
+ readonly width?: number;
3294
+ /** The layer's height in cells. Defaults to the map's height. */
3295
+ readonly height?: number;
3296
+ /** The tile ids, dense (row-major, top row first) or run-length encoded. */
3297
+ readonly tiles: readonly number[] | TileRleData;
3298
+ }
3299
+ /**
3300
+ * What {@link defineTilemap} accepts: the document with every defaulted field optional.
3301
+ *
3302
+ * @public
3303
+ */
3304
+ interface TilemapInput {
3305
+ /** Always `"ignifx.tilemap"` when present. */
3306
+ readonly format?: string;
3307
+ /** The document version. */
3308
+ readonly version?: number;
3309
+ /** The width of one tile, in pixels. */
3310
+ readonly tileWidth: number;
3311
+ /** The height of one tile, in pixels. Defaults to `tileWidth`. */
3312
+ readonly tileHeight?: number;
3313
+ /** The metre size of one cell. Defaults to `tileWidth / 100`, the default pixels-per-unit. */
3314
+ readonly cellSize?: number;
3315
+ /** The map's width, in cells. */
3316
+ readonly width: number;
3317
+ /** The map's height, in cells. */
3318
+ readonly height: number;
3319
+ /** The tilesets. Defaults to none. */
3320
+ readonly tilesets?: readonly TilesetDefinition[];
3321
+ /** The tile layers, back to front. Defaults to none. */
3322
+ readonly layers?: readonly TilemapLayerInput[];
3323
+ /** The objects. Defaults to none. */
3324
+ readonly objects?: readonly TilemapObjectDefinition[];
3325
+ /** The map's custom properties. Defaults to none. */
3326
+ readonly properties?: Readonly<Record<string, string | number | boolean>>;
3327
+ }
3328
+ /**
3329
+ * Run-length encodes a dense tile array.
3330
+ *
3331
+ * @remarks
3332
+ * The layout is flat `[count, value, count, value, …]` pairs, read left to right, so
3333
+ * `[1, 1, 0, 0, 0]` encodes to `[2, 1, 3, 0]`. It is the same shape Tiled's chunk encoding and
3334
+ * LDtk's exports settle on, and it round-trips exactly through {@link decodeTileRle}.
3335
+ *
3336
+ * @param tiles - The dense tile ids.
3337
+ * @returns The encoded pairs; empty for an empty input.
3338
+ *
3339
+ * @example
3340
+ * ```ts
3341
+ * encodeTileRle([1, 1, 0, 0, 0]); // [2, 1, 3, 0]
3342
+ * ```
3343
+ *
3344
+ * @public
3345
+ */
3346
+ export declare function encodeTileRle(tiles: readonly number[]): readonly number[];
3347
+ /**
3348
+ * Expands the `[count, value, …]` pairs {@link encodeTileRle} produces back into a dense array.
3349
+ *
3350
+ * @param rle - The encoded pairs.
3351
+ * @returns The dense tile ids.
3352
+ * @throws IgnifxError with code `IGX-1105` when the array has an odd length, or a run count that is
3353
+ * not a finite non-negative integer.
3354
+ *
3355
+ * @example
3356
+ * ```ts
3357
+ * decodeTileRle([2, 1, 3, 0]); // [1, 1, 0, 0, 0]
3358
+ * ```
3359
+ *
3360
+ * @public
3361
+ */
3362
+ export declare function decodeTileRle(rle: readonly number[]): readonly number[];
3363
+ /**
3364
+ * Fills in the defaults of a tilemap document, decodes any run-length-encoded layer, and checks the
3365
+ * invariants the renderer and the collider rely on.
3366
+ *
3367
+ * @param input - The document, as authored or as an importer emitted it.
3368
+ * @param address - What to name in an error; defaults to `"\<inline\>"`.
3369
+ * @returns The complete document, with every layer's `tiles` dense.
3370
+ * @throws IgnifxError with code `IGX-1105` when the format tag or version is wrong, a tile size is
3371
+ * not positive, a tileset's `firstId` is not positive, two layers share a name, a run-length array
3372
+ * has an odd length, or a layer's decoded tile count is not `width * height`.
3373
+ *
3374
+ * @public
3375
+ */
3376
+ export declare function defineTilemap(input: TilemapInput, address?: string): TilemapDefinition;
3377
+ /**
3378
+ * Resolves a global tile id to the tileset that owns it.
3379
+ *
3380
+ * @remarks
3381
+ * The owner is the tileset with the highest {@link TilesetDefinition.firstId} that is still less
3382
+ * than or equal to `tileId` — the rule Tiled's `firstgid` implies. `defineTilemap` sorts the
3383
+ * tilesets ascending, so this is a backward scan over a handful of entries.
3384
+ *
3385
+ * @param map - The parsed document.
3386
+ * @param tileId - The global tile id.
3387
+ * @returns The owning tileset, or `null` for the empty tile and for an id no tileset claims.
3388
+ *
3389
+ * @public
3390
+ */
3391
+ export declare function findTileset(map: TilemapDefinition, tileId: number): TilesetDefinition | null;
3392
+ /**
3393
+ * The atlas frame a global tile id draws.
3394
+ *
3395
+ * @param map - The parsed document.
3396
+ * @param tileId - The global tile id.
3397
+ * @returns The frame name, or `null` for the empty tile and for an id no tileset claims.
3398
+ *
3399
+ * @example
3400
+ * ```ts
3401
+ * tileFrameName(map, 1); // "hero_0"
3402
+ * ```
3403
+ *
3404
+ * @public
3405
+ */
3406
+ export declare function tileFrameName(map: TilemapDefinition, tileId: number): string | null;
3407
+ /**
3408
+ * Resolves a global tile id into the collision information a physics backend consumes.
3409
+ *
3410
+ * @remarks
3411
+ * This is the only place the authoring convention becomes the runtime one. A
3412
+ * {@link TileColliderDefinition} is cell-normalised with a **top-left** origin and +Y down; a
3413
+ * {@link TileCollisionShape} is cell-local **metres** with a **bottom-left** origin, +Y up and
3414
+ * counter-clockwise winding. So:
3415
+ *
3416
+ * - a box's bottom edge is `(1 - y - height) * cellSize`, because the authored `y` measures the
3417
+ * distance from the cell's top down to the box's *top* edge;
3418
+ * - a polygon's points each become `(x * cellSize, (1 - y) * cellSize)`, and the point **order is
3419
+ * reversed**, because mirroring a ring about a horizontal axis flips its winding — a clockwise
3420
+ * editor outline is counter-clockwise once flipped only if it is also walked backwards.
3421
+ *
3422
+ * @param map - The parsed document.
3423
+ * @param tileId - The global tile id, `0` for an empty cell.
3424
+ * @returns The tile's runtime collision info; a non-colliding, non-one-way default for the empty
3425
+ * tile, for an id no tileset claims, and for a tile that declares no collider.
3426
+ *
3427
+ * @example
3428
+ * ```ts
3429
+ * // A one-way platform authored as the top quarter of the cell, at cellSize 1:
3430
+ * tileCollisionInfo(map, 2).shape; // { kind: "box", x: 0, y: 0.75, width: 1, height: 0.25 }
3431
+ * ```
3432
+ *
3433
+ * @public
3434
+ */
3435
+ export declare function tileCollisionInfo(map: TilemapDefinition, tileId: number): TileCollisionInfo;
3436
+ //#endregion
3437
+ //#region src/tilemap/importers/ldtk.d.ts
3438
+ /**
3439
+ * The name given to the synthetic tileset that carries IntGrid colliders.
3440
+ *
3441
+ * @public
3442
+ */
3443
+ export declare const LDTK_INTGRID_TILESET_NAME = "intgrid";
3444
+ /**
3445
+ * The default meaning of an LDtk IntGrid value, in cell-normalised top-left-origin units.
3446
+ *
3447
+ * @remarks
3448
+ * `1` is "solid" — the whole cell collides. `2` is "one-way" — the top quarter of the cell collides,
3449
+ * and only from above. Those two conventions cover the LDtk projects people actually ship, and
3450
+ * anything else is project-specific, so {@link LdtkImportOptions.intGridColliders} replaces this
3451
+ * table wholesale. An IntGrid value with no entry still gets a tile id and a frame; it simply does
3452
+ * not collide.
3453
+ *
3454
+ * @public
3455
+ */
3456
+ export declare const LDTK_DEFAULT_INTGRID_COLLIDERS: Readonly<Record<number, TileColliderDefinition>>;
3457
+ /**
3458
+ * How {@link importLdtkLevel} maps LDtk's conventions onto ignifx's.
3459
+ *
3460
+ * @public
3461
+ */
3462
+ interface LdtkImportOptions {
3463
+ /** The pixels one world metre spans. Defaults to `100`, matching `twoD.pixelsPerUnit`. */
3464
+ readonly pixelsPerUnit?: number;
3465
+ /** The `identifier` of the level to import. Defaults to the project's first level. */
3466
+ readonly level?: string;
3467
+ /** The sorting layer every layer lands in. Defaults to `"Default"`. */
3468
+ readonly sortingLayer?: string;
3469
+ /**
3470
+ * Maps an LDtk tileset's `relPath` onto the address of the ignifx `.atlas.json` generated from it.
3471
+ * Defaults to swapping the file extension for `.atlas.json`.
3472
+ */
3473
+ readonly atlasFor?: (relPath: string) => string;
3474
+ /** Replaces {@link LDTK_DEFAULT_INTGRID_COLLIDERS} for this import. */
3475
+ readonly intGridColliders?: Readonly<Record<number, TileColliderDefinition>>;
3476
+ }
3477
+ /**
3478
+ * Imports one level of an LDtk project.
3479
+ *
3480
+ * @remarks
3481
+ * Three LDtk conventions need translating, and each is a place a naive importer goes wrong:
3482
+ *
3483
+ * - **Layer order is reversed.** LDtk stores `layerInstances` front-to-back — index `0` is the
3484
+ * layer drawn on *top*. ignifx layers are back-to-front, so the list is reversed and
3485
+ * `orderInLayer` follows the reversed index.
3486
+ * - **Tile layers are sparse.** `gridTiles` is a list of `{ px, t }` placements, not a grid; the
3487
+ * importer expands it into the dense `__cWid * __cHei` array the tilemap format wants, filling
3488
+ * the gaps with `0`. `t` is a tile index *within its tileset*, so the global id is
3489
+ * `tileset.firstId + t`. A layer's `pxOffsetX`/`pxOffsetY` shift the grid; a dense grid has no
3490
+ * sub-cell placement, so the offset is rounded to whole cells.
3491
+ * - **IntGrid layers are collision, not art.** An `intGridCsv` becomes a layer with
3492
+ * `collision: true` whose ids point into a synthetic, art-less tileset named
3493
+ * {@link LDTK_INTGRID_TILESET_NAME}; see {@link LDTK_DEFAULT_INTGRID_COLLIDERS} for the value
3494
+ * mapping and {@link LdtkImportOptions.intGridColliders} for overriding it.
3495
+ *
3496
+ * A tileset's `customData` entries are read as JSON, and an entry that parses to an object with
3497
+ * `solid: true` gives its tile a full-cell box collider. Data that is not JSON, or that says
3498
+ * something else, is ignored rather than treated as an error — `customData` is a free-form field
3499
+ * and other tools put other things in it.
3500
+ *
3501
+ * Per-tile flips (`gridTiles[].f`) are dropped, as they are in the Tiled importer: the tilemap
3502
+ * format has no per-cell flip yet.
3503
+ *
3504
+ * @param ldtk - The parsed `.ldtk` project.
3505
+ * @param options - The level to pick, pixels-per-unit, the sorting layer, and the mappings.
3506
+ * @returns The `ignifx.tilemap` document for that level.
3507
+ * @throws IgnifxError with code `IGX-1109` when the project has no levels, when
3508
+ * {@link LdtkImportOptions.level} names a level that is not there, or when a layer's type is not
3509
+ * `Tiles`, `IntGrid` or `Entities`; and `IGX-1105` when what it decodes to is not a valid tilemap.
3510
+ *
3511
+ * @example
3512
+ * ```ts
3513
+ * const map = importLdtkLevel(JSON.parse(await readFile("world.ldtk", "utf8")), { level: "Cave" });
3514
+ * ```
3515
+ *
3516
+ * @public
3517
+ */
3518
+ export declare function importLdtkLevel(ldtk: unknown, options?: LdtkImportOptions): TilemapDefinition;
3519
+ /**
3520
+ * Flattens LDtk's `[{ __identifier, __type, __value }]` field instances into a plain record.
3521
+ *
3522
+ * @remarks
3523
+ * Only `string`, `number` and `boolean` values survive. LDtk's richer field types — points, entity
3524
+ * references, arrays, enum tuples — have no equivalent in the tilemap format's flat property record
3525
+ * and are dropped rather than stringified.
3526
+ *
3527
+ * @param fields - The value of a `fieldInstances` field, or anything else.
3528
+ * @returns The flattened record; empty when `fields` is not a field-instance array.
3529
+ *
3530
+ * @example
3531
+ * ```ts
3532
+ * fieldInstancesToRecord([{ __identifier: "facing", __type: "String", __value: "left" }]);
3533
+ * // { facing: "left" }
3534
+ * ```
3535
+ *
3536
+ * @public
3537
+ */
3538
+ export declare function fieldInstancesToRecord(fields: unknown): Readonly<Record<string, string | number | boolean>>;
3539
+ //#endregion
3540
+ //#region src/tilemap/importers/tiled.d.ts
3541
+ /**
3542
+ * How {@link importTiledMap} maps Tiled's conventions onto ignifx's.
3543
+ *
3544
+ * @public
3545
+ */
3546
+ interface TiledImportOptions {
3547
+ /** The pixels one world metre spans. Defaults to `100`, matching `twoD.pixelsPerUnit`. */
3548
+ readonly pixelsPerUnit?: number;
3549
+ /** The sorting layer every tile layer lands in unless it says otherwise. Defaults to `"Default"`. */
3550
+ readonly sortingLayer?: string;
3551
+ /**
3552
+ * Maps a Tiled tileset's `image` path onto the address of the ignifx `.atlas.json` that was
3553
+ * generated from it. Defaults to swapping the file extension for `.atlas.json`.
3554
+ */
3555
+ readonly atlasFor?: (imageSource: string) => string;
3556
+ }
3557
+ /**
3558
+ * Flattens Tiled's `[{ name, type, value }]` property arrays into a plain record.
3559
+ *
3560
+ * @remarks
3561
+ * Only `string`, `number` and `boolean` values survive; Tiled's `object` and `class` property types
3562
+ * carry editor-side references that mean nothing at runtime, and are dropped rather than stringified
3563
+ * into something that looks meaningful but is not. `color` and `file` properties are strings in the
3564
+ * JSON and come through as strings.
3565
+ *
3566
+ * @param properties - The value of a Tiled `properties` field, or anything else.
3567
+ * @returns The flattened record; empty when `properties` is not a Tiled property array.
3568
+ *
3569
+ * @example
3570
+ * ```ts
3571
+ * tiledPropertiesToRecord([{ name: "biome", type: "string", value: "cave" }]); // { biome: "cave" }
3572
+ * ```
3573
+ *
3574
+ * @public
3575
+ */
3576
+ export declare function tiledPropertiesToRecord(properties: unknown): Readonly<Record<string, string | number | boolean>>;
3577
+ /**
3578
+ * Imports a Tiled JSON map.
3579
+ *
3580
+ * @remarks
3581
+ * Three Tiled features are rejected outright with `IGX-1109` rather than approximated: a non
3582
+ * orthogonal `orientation`, an `infinite` map (whose layers are chunked rather than dense), and
3583
+ * base64/compressed layer `data` (which arrives as a string). Everything else degrades quietly —
3584
+ * image layers and group layers are skipped, and unknown properties are carried through.
3585
+ *
3586
+ * Tiled stores the horizontal, vertical and diagonal flip flags in the top three bits of every
3587
+ * global tile id. ignifx has no per-cell flip yet, so those bits are **masked off** and the tile
3588
+ * draws unflipped; without the mask a flipped tile would resolve to a nonsensical tileset.
3589
+ *
3590
+ * The frame names this importer emits are `` `${tilesetName}_${localTileIndex}` `` — the same names
3591
+ * the grid-atlas generator gives the frames it cuts out of the tileset image, which is the contract
3592
+ * that lets `TilemapRenderer` look a tile's sprite up without a side table.
3593
+ *
3594
+ * @param tmj - The parsed `.tmj` document.
3595
+ * @param options - Pixels-per-unit, the default sorting layer, and the atlas address mapping.
3596
+ * @returns The `ignifx.tilemap` document.
3597
+ * @throws IgnifxError with code `IGX-1109` when the document is not an orthogonal, finite,
3598
+ * uncompressed Tiled map, and `IGX-1105` when what it decodes to is not a valid tilemap.
3599
+ *
3600
+ * @example
3601
+ * ```ts
3602
+ * const map = importTiledMap(JSON.parse(await readFile("cave.tmj", "utf8")), { pixelsPerUnit: 32 });
3603
+ * ```
3604
+ *
3605
+ * @public
3606
+ */
3607
+ export declare function importTiledMap(tmj: unknown, options?: TiledImportOptions): TilemapDefinition;
3608
+ //#endregion
3609
+ //#region src/tilemap/tilemap-asset.d.ts
3610
+ /**
3611
+ * The `tilemap` asset type and its loader (`docs/architecture/05-assets-and-loading.md` §5,
3612
+ * `11-2d-toolkit.md` §2.5).
3613
+ *
3614
+ * A `.tilemap.json` document is pure data — tile ids, tilesets, objects — so the loader needs no
3615
+ * device and behaves identically under a headless app, which is what lets a headless test assert
3616
+ * collision geometry and object spawning. The atlases the tilesets name are loaded by
3617
+ * `TilemapRenderer`, not here: a map with six tilesets in a scene that only shows one chunk should
3618
+ * not upload six textures at load time.
3619
+ */
3620
+ /**
3621
+ * A loaded tilemap document.
3622
+ *
3623
+ * @example
3624
+ * ```ts
3625
+ * const map = await app.assets.load<TilemapAsset>("2d/level-1.tilemap.json").promise;
3626
+ * map.definition.layers.length; // 2
3627
+ * ```
3628
+ *
3629
+ * @public
3630
+ */
3631
+ export declare class TilemapAsset {
3632
+ /** The type name the asset service registers tilemaps under. */
3633
+ static assetType: string;
3634
+ /** The address the document was loaded from. */
3635
+ readonly address: string;
3636
+ /** The parsed document, with every tile layer decoded to a dense array. */
3637
+ readonly definition: TilemapDefinition;
3638
+ /** Each tileset's atlas address, resolved against this document's address. */
3639
+ readonly atlasAddresses: readonly string[];
3640
+ /**
3641
+ * Wraps a parsed document. The `tilemap` loader constructs these.
3642
+ *
3643
+ * @param address - The address it was loaded from.
3644
+ * @param definition - The parsed document.
3645
+ *
3646
+ * @internal
3647
+ */
3648
+ constructor(address: string, definition: TilemapDefinition);
3649
+ /**
3650
+ * The atlas address a tileset's tiles come from.
3651
+ *
3652
+ * @param tilesetIndex - The tileset's index in the document.
3653
+ * @returns The address, or `""` when the index is out of range.
3654
+ */
3655
+ atlasFor(tilesetIndex: number): string;
3656
+ }
3657
+ /**
3658
+ * Builds the loader for `.tilemap.json` addresses.
3659
+ *
3660
+ * @returns The loader to register with `ctx.registerAssetLoader`.
3661
+ *
3662
+ * @example
3663
+ * ```ts
3664
+ * ctx.registerAssetLoader(createTilemapLoader());
3665
+ * ```
3666
+ *
3667
+ * @public
3668
+ */
3669
+ export declare function createTilemapLoader(): AssetLoader<TilemapAsset>;
3670
+ //#endregion
3671
+ //#region src/tilemap/tilemap.d.ts
3672
+ /**
3673
+ * `Tilemap` (`docs/architecture/11-2d-toolkit.md` §2.5): the grid of tile ids a level is built
3674
+ * from, its cell arithmetic, and the merged collision geometry `@ignifx/physics-2d` consumes.
3675
+ *
3676
+ * The component holds no Lite object — `TilemapRenderer` draws it — so a headless app carries the
3677
+ * full grid and the full collision surface. That is what makes a level's collision testable
3678
+ * without a GPU, and what lets a server run the same map the client draws.
3679
+ *
3680
+ * ## Coordinates
3681
+ *
3682
+ * Cell `(0, 0)` is the **bottom-left** of the map, because ignifx 2D is +Y up (ADR-0011). The
3683
+ * document's own layers are stored top row first, as every editor writes them, and the component
3684
+ * flips on the way in. `worldToCell`/`cellToWorld` are relative to the tilemap entity's own
3685
+ * transform, so moving the entity moves the whole map.
3686
+ */
3687
+ /**
3688
+ * One tile change, as {@link Tilemap.onTileChanged} reports it.
3689
+ *
3690
+ * @public
3691
+ */
3692
+ interface TileChange {
3693
+ /** The layer's index in the document. */
3694
+ readonly layer: number;
3695
+ /** The cell's column, with `0` at the left. */
3696
+ readonly x: number;
3697
+ /** The cell's row, with `0` at the **bottom**. */
3698
+ readonly y: number;
3699
+ /** The tile id that was there. */
3700
+ readonly previous: number;
3701
+ /** The tile id that is there now. */
3702
+ readonly current: number;
3703
+ }
3704
+ /**
3705
+ * A tilemap.
3706
+ *
3707
+ * @example
3708
+ * ```ts
3709
+ * const level = app.world.createEntity({ name: "level" }).addComponent(Tilemap);
3710
+ * level.map = app.assets.load<TilemapAsset>("2d/level-1.tilemap.json").retain();
3711
+ * level.setTile(0, 3, 2, 0); // carve a hole in the ground layer
3712
+ * ```
3713
+ *
3714
+ * @public
3715
+ */
3716
+ export declare class Tilemap extends Component implements ComponentHooks {
3717
+ #private;
3718
+ /** The registration id the serializer writes into scene files. */
3719
+ static typeId: string;
3720
+ /** One tilemap per entity. */
3721
+ static allowMultiple: boolean;
3722
+ /** The declarative fields (ADR-0004). */
3723
+ static schema: Schema;
3724
+ /** The `.tilemap.json` document. */
3725
+ map: AssetHandle<TilemapAsset> | null;
3726
+ /** How many cells one chunk spans on each axis. */
3727
+ chunkSize: number;
3728
+ /** The metres one cell spans, overriding the document's own; `0` uses the document's. */
3729
+ cellSizeOverride: number;
3730
+ /**
3731
+ * Builds a tilemap with the schema's defaults.
3732
+ */
3733
+ constructor();
3734
+ /**
3735
+ * Drops the grids, so a recycled component does not inherit the previous one's.
3736
+ */
3737
+ onAttach(): void;
3738
+ /**
3739
+ * Releases the grids.
3740
+ */
3741
+ onDetach(): void;
3742
+ /**
3743
+ * Emitted whenever `setTile` changes a cell.
3744
+ *
3745
+ * @returns The signal.
3746
+ */
3747
+ get onTileChanged(): Signal<TileChange>;
3748
+ /**
3749
+ * Emitted after the merged collision surface has been rebuilt.
3750
+ *
3751
+ * @remarks
3752
+ * `@ignifx/physics-2d` connects to this and rebuilds only the chunks whose geometry moved. The
3753
+ * rebuild is lazy: the signal fires on the first read of {@link Tilemap.collisionData} after a
3754
+ * change, not on the `setTile` call itself, so a script that rewrites a thousand tiles in one
3755
+ * frame pays for one merge.
3756
+ *
3757
+ * @returns The signal.
3758
+ */
3759
+ get onCollisionChanged(): Signal<void>;
3760
+ /**
3761
+ * The loaded document, or `null` while it is still loading.
3762
+ *
3763
+ * @returns The asset.
3764
+ */
3765
+ get asset(): TilemapAsset | null;
3766
+ /**
3767
+ * The parsed document, or `null`.
3768
+ *
3769
+ * @returns The definition.
3770
+ */
3771
+ get definition(): TilemapDefinition | null;
3772
+ /**
3773
+ * How many metres one cell spans.
3774
+ *
3775
+ * @returns The cell size; `0` when nothing has loaded.
3776
+ */
3777
+ get cellSize(): number;
3778
+ /**
3779
+ * How many layers the document has.
3780
+ *
3781
+ * @returns The layer count.
3782
+ */
3783
+ get layerCount(): number;
3784
+ /**
3785
+ * The merged collision surface, rebuilt if a tile changed since the last read.
3786
+ *
3787
+ * @remarks
3788
+ * The shape is the contract `@ignifx/physics-2d` consumes: chunked, in world metres relative to
3789
+ * the tilemap entity's origin, with adjacent full-cell tiles merged into as few counter-clockwise
3790
+ * rectangles as possible.
3791
+ *
3792
+ * @returns The collision data.
3793
+ */
3794
+ get collisionData(): TilemapCollisionData;
3795
+ /**
3796
+ * Reads a tile.
3797
+ *
3798
+ * @param layer - The layer's index in the document.
3799
+ * @param x - The cell's column, with `0` at the left.
3800
+ * @param y - The cell's row, with `0` at the bottom.
3801
+ * @returns The tile id, or `0` for an empty or out-of-range cell.
3802
+ */
3803
+ getTile(layer: number, x: number, y: number): number;
3804
+ /**
3805
+ * Writes a tile.
3806
+ *
3807
+ * @param layer - The layer's index in the document.
3808
+ * @param x - The cell's column, with `0` at the left.
3809
+ * @param y - The cell's row, with `0` at the bottom.
3810
+ * @param tileId - The tile id, or `0` to clear the cell.
3811
+ * @throws IgnifxError with code `IGX-1111` when the cell is outside the layer.
3812
+ */
3813
+ setTile(layer: number, x: number, y: number, tileId: number): void;
3814
+ /**
3815
+ * A layer's size, in cells.
3816
+ *
3817
+ * @param layer - The layer's index.
3818
+ * @returns The size, or a zero size for an unknown layer.
3819
+ */
3820
+ layerSize(layer: number): Vec2Like;
3821
+ /**
3822
+ * Converts a world point into the cell containing it.
3823
+ *
3824
+ * @remarks
3825
+ * The point is in world metres; the map's own origin is the tilemap entity's position, so a moved
3826
+ * or scaled tilemap still answers correctly. The result is floored, so a point exactly on a cell
3827
+ * boundary belongs to the cell above and to the right of it.
3828
+ *
3829
+ * @param point - The world point, in metres.
3830
+ * @param out - The vector to write.
3831
+ * @returns `out`, holding integer cell coordinates that may be outside the map.
3832
+ */
3833
+ worldToCell<TOut extends MutableVec2>(point: Vec2Like, out: TOut): TOut;
3834
+ /**
3835
+ * Converts a cell into the world point at its **centre**.
3836
+ *
3837
+ * @param x - The cell's column.
3838
+ * @param y - The cell's row, with `0` at the bottom.
3839
+ * @param out - The vector to write.
3840
+ * @returns `out`, in world metres.
3841
+ */
3842
+ cellToWorld<TOut extends MutableVec2>(x: number, y: number, out: TOut): TOut;
3843
+ /**
3844
+ * The collision footprint of whatever is at a cell, across every collision layer.
3845
+ *
3846
+ * @param x - The cell's column.
3847
+ * @param y - The cell's row, with `0` at the bottom.
3848
+ * @returns The topmost non-empty collider, or a `"none"` shape.
3849
+ */
3850
+ collisionAt(x: number, y: number): TileCollisionInfo;
3851
+ /**
3852
+ * Forces the collision surface to be rebuilt on the next read.
3853
+ *
3854
+ * @internal
3855
+ */
3856
+ invalidateCollision(): void;
3857
+ }
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
+ //#endregion
3861
+ //#region src/tilemap/spawn-objects.d.ts
3862
+ /**
3863
+ * Runs the registered factory for every object in one tilemap.
3864
+ *
3865
+ * @param app - The app.
3866
+ * @param service - The 2D service holding the factory registry.
3867
+ * @param tilemap - The tilemap whose objects layer to walk.
3868
+ * @returns The entities that were created, in document order.
3869
+ *
3870
+ * @example
3871
+ * ```ts
3872
+ * app.twoD.registerTileObjectFactory("spawn", ({ world, position }) => {
3873
+ * const player = world.createEntity({ name: "player" });
3874
+ * player.transform.position2D = new Vec2(position.x, position.y);
3875
+ * return player;
3876
+ * });
3877
+ * ```
3878
+ *
3879
+ * @public
3880
+ */
3881
+ export declare function spawnTilemapObjects(app: App, service: TwoDService, tilemap: Tilemap): readonly Entity[];
3882
+ //#endregion
3883
+ //#region src/tilemap/tilemap-renderer.d.ts
3884
+ /**
3885
+ * A tilemap renderer.
3886
+ *
3887
+ * @example
3888
+ * ```ts
3889
+ * const level = app.world.createEntity({ name: "level" });
3890
+ * level.addComponent(Tilemap).map = app.assets.load<TilemapAsset>("2d/level-1.tilemap.json").retain();
3891
+ * const renderer = level.addComponent(TilemapRenderer);
3892
+ * renderer.atlas = app.assets.load<SpriteAtlasAsset>("2d/tiles.atlas.json").retain();
3893
+ * ```
3894
+ *
3895
+ * @public
3896
+ */
3897
+ export declare class TilemapRenderer extends Component implements ComponentHooks {
3898
+ #private;
3899
+ /** The registration id the serializer writes into scene files. */
3900
+ static typeId: string;
3901
+ /** One renderer per entity. */
3902
+ static allowMultiple: boolean;
3903
+ /** The declarative fields (ADR-0004). */
3904
+ static schema: Schema;
3905
+ /** The atlas the tile frames come from. */
3906
+ atlas: AssetHandle<SpriteAtlasAsset> | null;
3907
+ /** Which sorting layer the tiles draw on, when the document's layers name none. */
3908
+ sortingLayer: string;
3909
+ /** Whether chunks outside the camera's visible bounds are dropped. */
3910
+ cullChunks: boolean;
3911
+ /**
3912
+ * Builds a renderer with the schema's defaults.
3913
+ */
3914
+ constructor();
3915
+ /**
3916
+ * Marks every chunk stale, so a recycled component rebuilds.
3917
+ */
3918
+ onAttach(): void;
3919
+ /**
3920
+ * Marks every chunk stale; the 2D sync system does the removal, because it owns the layers.
3921
+ */
3922
+ onDetach(): void;
3923
+ /**
3924
+ * How many chunks are currently materialised.
3925
+ *
3926
+ * @returns The count.
3927
+ */
3928
+ get chunkCount(): number;
3929
+ /**
3930
+ * How many sprites the materialised chunks hold in total.
3931
+ *
3932
+ * @returns The count.
3933
+ */
3934
+ get spriteCount(): number;
3935
+ /**
3936
+ * The loaded atlas, or `null`.
3937
+ *
3938
+ * @returns The atlas.
3939
+ */
3940
+ get loadedAtlas(): SpriteAtlasAsset | null;
3941
+ /**
3942
+ * Forces every chunk to be rebuilt on the next sync.
3943
+ *
3944
+ * @remarks
3945
+ * `Tilemap.onTileChanged` is what normally calls this — a rewritten cell has to reach the sprite
3946
+ * that draws it, and rebuilding the chunk is both simpler and, for anything short of a per-frame
3947
+ * rewrite, cheaper than tracking one sprite per cell.
3948
+ *
3949
+ * @internal
3950
+ */
3951
+ invalidate(): void;
3952
+ /**
3953
+ * Brings the materialised chunks in line with the camera's visible bounds.
3954
+ *
3955
+ * @param map - The tilemap being drawn.
3956
+ * @param registry - The layer registry that owns the Lite layers.
3957
+ * @param bounds - The camera's visible bounds, in layer pixels, or `null` to build every chunk.
3958
+ * @param pixelsPerUnit - The pixels one metre spans.
3959
+ * @returns How many sprites were written this call; `0` on a steady frame.
3960
+ *
3961
+ * @internal
3962
+ */
3963
+ sync(map: Tilemap, registry: SpriteLayerRegistry, bounds: LiteBounds2D | null, pixelsPerUnit: number): number;
3964
+ /**
3965
+ * Advances animated tiles and rewrites the chunks holding them.
3966
+ *
3967
+ * @param deltaSeconds - The scaled frame delta.
3968
+ * @returns `true` when a tile's frame changed, so the renderer must rebuild.
3969
+ *
3970
+ * @internal
3971
+ */
3972
+ advanceAnimation(deltaSeconds: number): boolean;
3973
+ /**
3974
+ * The animation clock animated tiles are sampled at, in seconds.
3975
+ *
3976
+ * @returns The elapsed time.
3977
+ *
3978
+ * @internal
3979
+ */
3980
+ get animationClock(): number;
3981
+ /**
3982
+ * Drops every materialised chunk.
3983
+ *
3984
+ * @param registry - The layer registry.
3985
+ *
3986
+ * @internal
3987
+ */
3988
+ dropAll(registry: SpriteLayerRegistry): void;
3989
+ }
3990
+ //#endregion
3991
+ //#region src/version.d.ts
3992
+ /**
3993
+ * The package's own version, reported as `Extension.version`
3994
+ * (`docs/architecture/04-extensions.md` §1). First-party packages ship one version line, so this
3995
+ * tracks `package.json` and the release tooling bumps both together.
3996
+ */
3997
+ /**
3998
+ * The `@ignifx/2d` version this build was cut from.
3999
+ *
4000
+ * @public
4001
+ */
4002
+ export declare const VERSION = "0.0.0";
4003
+ //#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 };
4005
+ //# sourceMappingURL=index.d.ts.map