@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.
- package/dist/index.d.ts +4005 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +7499 -0
- package/dist/index.js.map +1 -0
- package/package.json +64 -0
- package/skills/2d/SKILL.md +51 -0
package/dist/index.d.ts
ADDED
|
@@ -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
|