@ignifx/2d 0.8.0 → 0.10.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ignifx/2d",
3
- "version": "0.8.0",
3
+ "version": "0.10.0",
4
4
  "description": "ignifx 2D toolkit: Camera2D, sprites, sprite animation, atlases, tilemaps, sorting layers, pixel-perfect, parallax.",
5
5
  "keywords": [
6
6
  "ignifx",
@@ -33,7 +33,7 @@
33
33
  },
34
34
  "devDependencies": {
35
35
  "@arethetypeswrong/cli": "^0.18.5",
36
- "@babylonjs/lite": "1.27.0",
36
+ "@babylonjs/lite": "1.34.0",
37
37
  "@microsoft/api-extractor": "^7.59.0",
38
38
  "@types/webxr": "^0.5.0",
39
39
  "@webgpu/types": "^0.1.72",
@@ -43,11 +43,11 @@
43
43
  "typedoc-plugin-markdown": "^4.13.0",
44
44
  "typescript-native": "npm:typescript@7.0.2",
45
45
  "vitest": "^5.0.0",
46
- "@ignifx/core": "0.8.0"
46
+ "@ignifx/core": "0.10.0"
47
47
  },
48
48
  "peerDependencies": {
49
- "@babylonjs/lite": "1.27.0",
50
- "@ignifx/core": "0.8.0"
49
+ "@babylonjs/lite": "1.34.0",
50
+ "@ignifx/core": "0.10.0"
51
51
  },
52
52
  "ignifx": {
53
53
  "extension": true,
@@ -3,7 +3,7 @@ name: 2d
3
3
  description: Builds 2D games in ignifx with @ignifx/2d: Camera2D, SpriteRenderer, SpriteAnimator, texture atlases, Tilemap rendering and import, sorting layers and Y-sort, pixel-perfect cameras, parallax layers, sprite batches, and 2D picking. Use when adding or editing sprites, sprite animation, tilemaps, atlases, sorting layers, sprite batches, or a 2D camera in an ignifx project, or when the user mentions @ignifx/2d, Camera2D, SpriteRenderer, SpriteBatch, or Tilemap.
4
4
  license: Apache-2.0
5
5
  metadata:
6
- ignifx-version: "0.8.0"
6
+ ignifx-version: "0.10.0"
7
7
  ---
8
8
 
9
9
  # @ignifx/2d
@@ -21,8 +21,8 @@ parse, `SpriteAnimator` advances on the stepped clock. Only the pixels need a GP
21
21
 
22
22
  ## Environment
23
23
 
24
- - Engine: ignifx `0.8.0`; this package targets `@ignifx/core` `>=0.0.0 <1.0.0`.
25
- - WebGPU only, browser and Electron. Babylon Lite `1.27.0` is a peer dependency.
24
+ - Engine: ignifx `0.10.0`; this package targets `@ignifx/core` `>=0.0.0 <1.0.0`.
25
+ - WebGPU only, browser and Electron. Babylon Lite `1.34.0` is a peer dependency.
26
26
  - Register it like any extension; nothing happens at import time.
27
27
 
28
28
  ```ts
@@ -58,9 +58,9 @@ a `"sprite"`-mode frame is cleared to is the core `rendering.clearColor` setting
58
58
  app.twoD (TwoDService)
59
59
  ├─ pixelsPerUnit · mode · sortingLayers
60
60
  ├─ mainCamera the highest-priority enabled Camera2D
61
- ├─ pickAt(x, y) CPU pick over the sprite layers → { entity, component, u, v }
62
- ├─ layers one Lite Sprite2DLayer per (sortingLayer × atlas × blend × space)
63
- └─ registerTileObjectFactory(type, factory)
61
+ ├─ pickAt(x, y, o?) CPU pick over the sprite layers → { entity, component, u, v }
62
+ ├─ pickAllAt(x, y) every sprite under the pixel, topmost first
63
+ └─ layers one Lite Sprite2DLayer per (sortingLayer × atlas × blend × space)
64
64
 
65
65
  PostUpdate → SpriteAnimator.advance + animated tiles (ignifx's clock, so timeScale works)
66
66
  PreRender → camera view, sprite sync, tilemap chunks (order -450)
@@ -115,27 +115,27 @@ Full signatures: `skills/ignifx/references/api/2d.md`.
115
115
  | ------------------------------------- | ---------------------------------------------------------- |
116
116
  | `pixelsPerUnit` · `mode` · `settings` | The resolved `twoD` section, after any scene override |
117
117
  | `mainCamera` | The highest-priority enabled `Camera2D`, or `null` |
118
- | `pickAt(xPx, yPx)` | Topmost `SpriteRenderer` under a viewport pixel, or `null` |
118
+ | `pickAt(xPx, yPx, options?)` | Topmost `SpriteRenderer` under a viewport pixel, or `null` |
119
+ | `pickAllAt(xPx, yPx, options?)` | Every `SpriteRenderer` under the pixel, topmost first |
119
120
  | `screenToWorld` · `worldToScreen` | Through the active camera |
120
121
  | `visibleWorldBounds(out)` | The world rectangle the camera sees (parallax not applied) |
121
122
  | `layers` | Diagnostics: every Lite layer in draw order |
122
- | `registerTileObjectFactory(type, fn)` | What a tilemap's objects layer spawns |
123
123
  | `syncedLastFrame` · `spriteCount` | How many sprites the last frame actually wrote |
124
124
  | `createSpriteBatch(options)` | A fixed-capacity crowd of entity-less sprites (`@beta`) |
125
125
  | `lite.renderer` | The Lite `SpriteRenderer`, or `null` headless |
126
126
 
127
127
  ### Components
128
128
 
129
- | Component (`typeId`) | Key fields |
130
- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
131
- | `Camera2D` (`ignifx/Camera2D`) | `orthographicSize`, `pixelPerfect`, `referenceResolution`, `boundsMin`/`boundsMax`, `follow`, `deadZone`, `priority` |
132
- | `SpriteRenderer` (`ignifx/SpriteRenderer`) | `sprite`, `color`, `flipX`/`flipY`, `sortingLayer`, `orderInLayer`, `blend`, `pivotOverride`, `screenSpace`, `pickable` |
133
- | `SpriteAnimator` (`ignifx/SpriteAnimator`) | `animations`, `defaultClip`, `playOnAwake`, `speed`; `play`/`stop`/`pause`/`resume`, `onClipEnded`, `onEvent` |
134
- | `Tilemap` (`ignifx/Tilemap`) | `map`, `chunkSize`; `getTile`/`setTile`, `worldToCell`/`cellToWorld`, `collisionData`, `onTileChanged` |
135
- | `TilemapRenderer` (`ignifx/TilemapRenderer`) | `atlas`, `sortingLayer`, `cullChunks` |
136
- | `ParallaxLayer` (`ignifx/ParallaxLayer`) | `sortingLayer`, `factor`, `repeatX`/`repeatY`, `repeatWidth`/`repeatHeight` |
137
- | `SpriteLayerEffect` (`ignifx/SpriteLayerEffect`) | `sortingLayer`, `kind`, `tint`, `params`, `shader` |
138
- | `Camera2DFollow` (`ignifx/Camera2DFollow`) | A `Script`; reads `Camera2D`'s follow fields in `lateUpdate` |
129
+ | Component (`typeId`) | Key fields |
130
+ | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
131
+ | `Camera2D` (`ignifx/Camera2D`) | `orthographicSize`, `pixelPerfect`, `referenceResolution`, `boundsMin`/`boundsMax`, `follow`, `deadZone`, `priority` |
132
+ | `SpriteRenderer` (`ignifx/SpriteRenderer`) | `sprite`, `frameName`, `color`, `flipX`/`flipY`, `sortingLayer`, `orderInLayer`, `blend`, `pivotOverride`, `screenSpace`, `pickable`; runtime `frame` |
133
+ | `SpriteAnimator` (`ignifx/SpriteAnimator`) | `animations`, `defaultClip`, `playOnAwake`, `speed`; `play`/`stop`/`pause`/`resume`/`sample`, `onClipEnded`, `onEvent` |
134
+ | `Tilemap` (`ignifx/Tilemap`) | `map`, `chunkSize`; `getTile`/`setTile`/`setCells`, `worldToCell`/`cellToWorld`, `collisionData`, `onTileChanged` |
135
+ | `TilemapRenderer` (`ignifx/TilemapRenderer`) | `atlas`, `sortingLayer`, `cullChunks` |
136
+ | `ParallaxLayer` (`ignifx/ParallaxLayer`) | `sortingLayer`, `factor`, `repeatX`/`repeatY`, `repeatWidth`/`repeatHeight` |
137
+ | `SpriteLayerEffect` (`ignifx/SpriteLayerEffect`) | `sortingLayer`, `kind`, `tint`, `params`, `shader` |
138
+ | `Camera2DFollow` (`ignifx/Camera2DFollow`) | A `Script`; reads `Camera2D`'s follow fields in `lateUpdate` |
139
139
 
140
140
  ### `SpriteBatch` — sprites without entities (`@beta`)
141
141
 
@@ -182,31 +182,26 @@ Pure functions, so a build step or a test can call them with no app:
182
182
  ### Error codes
183
183
 
184
184
  `IGX-1102` unextruded atlas frame (logged, not thrown) · `IGX-1103`/`IGX-1104`/`IGX-1105` unreadable
185
- document · `IGX-1106` unknown frame · `IGX-1107` unknown sorting layer · `IGX-1108` unknown clip ·
186
- `IGX-1109` unsupported import · `IGX-1110` duplicate object factory · `IGX-1111` cell out of range ·
185
+ document · `IGX-1106` unknown frame (a bad `frameName` is reported once, not thrown) · `IGX-1107` unknown sorting layer · `IGX-1108` unknown clip ·
186
+ `IGX-1109` unsupported import · `IGX-1111` cell out of range ·
187
187
  `IGX-1112` duplicate extension · `IGX-1113` custom effect with no WGSL · `IGX-1114` bad sprite-batch
188
188
  capacity · `IGX-1115` sprite-batch slot or count out of range · `IGX-1116` sprite batch used after
189
- `dispose()` · `IGX-1117` sprite-batch atlas not loaded.
189
+ `dispose()` · `IGX-1117` sprite-batch atlas not loaded · `IGX-1118` `SpriteRenderer.sprite` is not an
190
+ atlas (reported once, not thrown) · `IGX-1119` a pick called from inside a pick `filter`.
190
191
 
191
192
  ## Recipes
192
193
 
193
- ### Tilemap with spawned objects
194
+ ### Tilemap with collision and objects
194
195
 
195
196
  ```ts
196
197
  import { createApp, Vec2 } from "ignifx";
197
198
  import { Tilemap, TilemapRenderer, twoD } from "@ignifx/2d";
199
+ import { physics2d, TilemapCollider2D } from "@ignifx/physics-2d";
198
200
  import type { SpriteAtlasAsset, TilemapAsset } from "@ignifx/2d";
199
- import type { Entity } from "ignifx";
200
201
 
201
202
  const canvas = document.querySelector("canvas");
202
203
  if (canvas instanceof HTMLCanvasElement) {
203
- const app = await createApp({ canvas, extensions: [twoD()] });
204
-
205
- app.twoD.registerTileObjectFactory("spawn", (context): Entity | null => {
206
- const player = context.world.createEntity(context.name);
207
- player.transform.position2D = new Vec2(context.position.x, context.position.y);
208
- return player;
209
- });
204
+ const app = await createApp({ canvas, extensions: [twoD(), physics2d()] });
210
205
 
211
206
  const map = app.assets.load<TilemapAsset>("2d/level-1.tilemap.json");
212
207
  const tiles = app.assets.load<SpriteAtlasAsset>("2d/tiles.atlas.json");
@@ -215,10 +210,28 @@ if (canvas instanceof HTMLCanvasElement) {
215
210
  const level = app.world.createEntity("Level");
216
211
  level.addComponent(Tilemap).map = map;
217
212
  level.addComponent(TilemapRenderer).atlas = tiles;
213
+ level.addComponent(TilemapCollider2D); // reads the Tilemap beside it
214
+
215
+ // A level built in code places its objects itself; a scene file holds them as entities.
216
+ for (const object of map.value.definition.objects) {
217
+ if (object.type === "spawn") {
218
+ const player = app.world.createEntity(object.name);
219
+ player.transform.position2D = new Vec2(object.x + object.width / 2, object.y + object.height / 2);
220
+ }
221
+ }
218
222
  await app.start();
219
223
  }
220
224
  ```
221
225
 
226
+ A level kept in a scene file gets its objects once, as entities, from the command line. Each
227
+ becomes an entity named after the object and tagged with its type, at the object's centre, and the
228
+ map's `objects` field is deleted. Add the components each type needs afterwards; the command prints
229
+ every object's size and properties for that.
230
+
231
+ ```sh
232
+ ignifx import tilemap assets/level.tilemap.json assets/scenes/main.scene.json --parent Level
233
+ ```
234
+
222
235
  ### Picking a sprite under the pointer
223
236
 
224
237
  ```ts run
@@ -236,6 +249,50 @@ export class ClickToSelect extends Script {
236
249
  }
237
250
  ```
238
251
 
252
+ `pickAt` and `pickAllAt` take options named after core's `RenderPickOptions`: `filter(entity,
253
+ component)`, `ignore` (a list of entities), and `includeUnpickable` (also consider sprites with
254
+ `pickable: false`). `pickAllAt` also takes `limit`, which defaults to `DEFAULT_PICK_ALL_LIMIT` (64).
255
+ A rejected sprite never hides the sprites under it: the pick looks further down the same sorting
256
+ layer, then the layers below. Each sprite examined costs one more scan of its layer.
257
+
258
+ ```ts
259
+ import type { App, Entity, TwoDPick } from "ignifx";
260
+
261
+ /** Click-cycles through the stack under the pointer, skipping locked entities. */
262
+ export function nextUnder(
263
+ app: App,
264
+ x: number,
265
+ y: number,
266
+ current: Entity | null,
267
+ locked: Set<Entity>,
268
+ ): TwoDPick | null {
269
+ const stack = app.twoD.pickAllAt(x, y, { includeUnpickable: true, filter: (entity) => !locked.has(entity) });
270
+ const index = stack.findIndex((hit) => hit.entity === current);
271
+ return stack[(index + 1) % Math.max(1, stack.length)] ?? null;
272
+ }
273
+ ```
274
+
275
+ ### Editing tiles at runtime
276
+
277
+ `setTile` writes one cell; `setCells` writes a batch with the same meaning, checks every cell before
278
+ writing any, and costs one collision merge however many cells changed. Either way the
279
+ `TilemapRenderer` rebuilds only the chunks that were touched, on the next frame.
280
+
281
+ ```ts
282
+ import type { Tilemap, TileWrite } from "ignifx";
283
+
284
+ /** Clears a rectangle of cells on one layer. */
285
+ export function clearRect(map: Tilemap, layer: number, x0: number, y0: number, x1: number, y1: number): number {
286
+ const cells: TileWrite[] = [];
287
+ for (let y = y0; y <= y1; y += 1) {
288
+ for (let x = x0; x <= x1; x += 1) {
289
+ cells.push({ layer, x, y, tileId: 0 });
290
+ }
291
+ }
292
+ return map.setCells(cells);
293
+ }
294
+ ```
295
+
239
296
  ## File formats
240
297
 
241
298
  Generated reference: `skills/ignifx/references/formats/`.
@@ -243,7 +300,8 @@ Generated reference: `skills/ignifx/references/formats/`.
243
300
  - **`.atlas.json`** (`ignifx.spriteatlas`) — `image` (an address relative to the document, resolved through the manifest; `/x.png` and URLs verbatim), `sampling`,
244
301
  `premultipliedAlpha`, and `frames: [{ name, x, y, w, h, pivot?, sourceSize? }]` in **image pixels
245
302
  with a top-left origin**. A pivot is `[x, y]` or `{ x, y }` in `[0, 1]` of the frame; `[0, 0]` is
246
- top-left. Address one frame with `"2d/hero.atlas.json#frame:idle_0"`.
303
+ top-left. A `SpriteRenderer` picks a frame by name with `frameName`. A
304
+ `"2d/hero.atlas.json#frame:idle_0"` address loads a `SpriteAsset` for code; it is not a sprite.
247
305
  - **`.spriteanim.json`** (`ignifx.spriteanimation`) — `atlas` plus
248
306
  `clips: [{ name, frames | from/to, fps, loop, events }]`. An event's `frame` is the index **within
249
307
  the clip**. `frames` is a list of frame names played in the order written and may skip around the
@@ -251,10 +309,15 @@ Generated reference: `skills/ignifx/references/formats/`.
251
309
  endpoints plays — use `frames` when the run is not contiguous in the atlas.
252
310
  - **`.tilemap.json`** (`ignifx.tilemap`) — tile size, `cellSize` in metres, tilesets with colliders
253
311
  and animations, layers of tile ids (dense or RLE, **top row first**), and an objects layer in
254
- world metres.
312
+ world metres (`x`, `y` is the bottom-left corner) that the runtime never spawns.
255
313
 
256
314
  ## Gotchas
257
315
 
316
+ - **A sprite's frame is a field, not part of its address.** `sprite` names the `.atlas.json`;
317
+ `frameName` names the frame and is what a scene file saves (`""` is the first frame). `frame` is
318
+ the index drawn now, which `SpriteAnimator` writes; whichever of the two was written last wins, so
319
+ saving mid-animation keeps the authored name. A `#frame:` fragment in `sprite` reports `IGX-1118`
320
+ and draws nothing; an unknown `frameName` reports `IGX-1106` once and draws the first frame.
258
321
  - **`pixelsPerUnit` is 100 by default.** A 32-px sprite is 0.32 metres wide, so a camera with
259
322
  `orthographicSize = 5` shows about 31 sprites vertically. Set it to your art's pixel size (16, 32)
260
323
  for pixel art.
@@ -267,8 +330,13 @@ Generated reference: `skills/ignifx/references/formats/`.
267
330
  - **`pixelPerfect` ignores `orthographicSize`** and scales `referenceResolution` by a whole number
268
331
  instead. It does **not** change an atlas's sampling: write `"sampling": "nearest"` in the
269
332
  `.atlas.json`, because a texture's sampler is fixed at upload.
270
- - **Tiles are not pickable.** They have no component, so `pickAt` skips them; use
333
+ - **A tilemap's objects layer is authoring data.** Nothing spawns from it at runtime (ADR-0030):
334
+ move it into the scene with `ignifx import tilemap`, or read `tilemap.definition.objects` in code.
335
+ - **Tiles are not pickable.** They have no component, so `pickAt` skips them and looks underneath; use
271
336
  `Tilemap.worldToCell`, which is exact and free.
337
+ - **A pick `filter` must not change sprites or pick again.** It runs in the middle of the pick, which
338
+ briefly hides each rejected sprite to look under it and restores them all before returning (also
339
+ when the filter throws). A `pickAt` or `pickAllAt` from inside a filter throws `IGX-1119`.
272
340
  - **A `SpriteBatch` slot is centred on the position written and is never picked.** It ignores the
273
341
  frame's pivot — offset the position yourself if you need feet on the ground — and holds no
274
342
  component for `pickAt` to resolve. It also does not sort its own slots: on a Y-sorted sorting layer
@@ -292,6 +360,9 @@ Generated reference: `skills/ignifx/references/formats/`.
292
360
  warning is suppressed while the sprite renderer has an active `Camera2D`, so a correct 2D-only
293
361
  scene is quiet. Build the camera **before** `app.start()`, as the templates do: a world that is
294
362
  still empty when the loop starts has no camera of any kind, and that does warn.
363
+ - **In an edit-mode app (`createApp({ editMode: true })`) clips and animated tiles do not play.**
364
+ The renderer keeps its authored `frameName`. To preview one, call `animator.sample("run", 2)`: it writes
365
+ that frame, stops there, and fires no event; `resume()` plays on from it. It works in a game too.
295
366
 
296
367
  ## Deprecated (current window)
297
368