@ignifx/2d 0.20.0 → 0.21.1

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.20.0",
3
+ "version": "0.21.1",
4
4
  "description": "ignifx 2D toolkit: Camera2D, sprites, sprite animation, atlases, tilemaps, sorting layers, pixel-perfect, parallax.",
5
5
  "keywords": [
6
6
  "ignifx",
@@ -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.20.0"
46
+ "@ignifx/core": "0.21.1"
47
47
  },
48
48
  "peerDependencies": {
49
49
  "@babylonjs/lite": "1.34.0",
50
- "@ignifx/core": "0.20.0"
50
+ "@ignifx/core": "0.21.1"
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.20.0"
6
+ ignifx-version: "0.21.1"
7
7
  ---
8
8
 
9
9
  # @ignifx/2d
@@ -21,7 +21,7 @@ parse, `SpriteAnimator` advances on the stepped clock. Only the pixels need a GP
21
21
 
22
22
  ## Environment
23
23
 
24
- - Engine: ignifx `0.20.0`; this package targets `@ignifx/core` `>=0.0.0 <1.0.0`.
24
+ - Engine: ignifx `0.21.1`; this package targets `@ignifx/core` `>=0.0.0 <1.0.0`.
25
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
 
@@ -43,11 +43,11 @@ if (canvas instanceof HTMLCanvasElement) {
43
43
  `ignifx.config.ts` carries the same settings under `twoD`, and a scene file's `settings.twoD` block
44
44
  overrides them for that scene:
45
45
 
46
- | Setting | Default | Meaning |
47
- | --------------- | ---------- | ------------------------------------------------------------------- |
48
- | `mode` | `"sprite"` | `"sprite"` clears the frame; `"mixed"` composites over the 3D scene |
49
- | `pixelsPerUnit` | `100` | How many pixels one world metre spans |
50
- | `ySort` | `{}` | Which sorting layers draw back-to-front by world Y |
46
+ | Setting | Default | Meaning |
47
+ | --- | --- | --- |
48
+ | `mode` | `"sprite"` | `"sprite"` clears the frame; `"mixed"` composites over the 3D scene |
49
+ | `pixelsPerUnit` | `100` | How many pixels one world metre spans |
50
+ | `ySort` | `{}` | Which sorting layers draw back-to-front by world Y |
51
51
 
52
52
  Sorting layers themselves live in the **core** `sortingLayers` section, back to front, and the colour
53
53
  a `"sprite"`-mode frame is cleared to is the core `rendering.clearColor` setting — see the Gotchas.
@@ -107,35 +107,35 @@ load is delivered in `PreUpdate`.
107
107
 
108
108
  ## Core APIs
109
109
 
110
- Full signatures: `skills/ignifx/references/api/2d.md`.
110
+ Full signatures: `skills/ignifx/references/api/2d.md` in the `ignifx` package.
111
111
 
112
112
  ### `app.twoD` — `TwoDService`
113
113
 
114
- | Member | Meaning |
115
- | ------------------------------------- | ---------------------------------------------------------- |
116
- | `pixelsPerUnit` · `mode` · `settings` | The resolved `twoD` section, after any scene override |
117
- | `mainCamera` | The highest-priority enabled `Camera2D`, 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 |
120
- | `screenToWorld` · `worldToScreen` | Through the active camera |
121
- | `visibleWorldBounds(out)` | The world rectangle the camera sees (parallax not applied) |
122
- | `layers` | Diagnostics: every Lite layer in draw order |
123
- | `syncedLastFrame` · `spriteCount` | How many sprites the last frame actually wrote |
124
- | `createSpriteBatch(options)` | A fixed-capacity crowd of entity-less sprites (`@beta`) |
125
- | `lite.renderer` | The Lite `SpriteRenderer`, or `null` headless |
114
+ | Member | Meaning |
115
+ | --- | --- |
116
+ | `pixelsPerUnit` · `mode` · `settings` | The resolved `twoD` section, after any scene override |
117
+ | `mainCamera` | The highest-priority enabled `Camera2D`, 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 |
120
+ | `screenToWorld` · `worldToScreen` | Through the active camera |
121
+ | `visibleWorldBounds(out)` | The world rectangle the camera sees (parallax not applied) |
122
+ | `layers` | Diagnostics: every Lite layer in draw order |
123
+ | `syncedLastFrame` · `spriteCount` | How many sprites the last frame actually wrote |
124
+ | `createSpriteBatch(options)` | A fixed-capacity crowd of entity-less sprites (`@beta`) |
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`, `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`/`sampleTime`, `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` |
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`/`sampleTime`, `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
 
@@ -145,14 +145,14 @@ sprites are not _things_ — bullets, sparks, debris, 2D particles — and one e
145
145
  more than the drawing does. Use `SpriteRenderer` for anything with a transform, a pick or a place in
146
146
  a scene file.
147
147
 
148
- | Member | Meaning |
149
- | ----------------------------------------------------------------------- | ------------------------------------------------------------------ |
150
- | `capacity` | The slots claimed; fixed for the batch's life |
151
- | `count` | How many leading slots draw; slots at `count` and above are hidden |
152
- | `write(index, x, y, w, h, frame, rotation, r, g, b, a, flipX?, flipY?)` | One slot, in world metres, +Y up, and degrees counter-clockwise |
153
- | `hide(index)` | Hides one slot until it is written again |
154
- | `dispose()` | Gives the slots back; also runs at the end of a `using` block |
155
- | `lite.handles` | The Lite `Sprite2DHandle` per slot — unstable escape hatch |
148
+ | Member | Meaning |
149
+ | --- | --- |
150
+ | `capacity` | The slots claimed; fixed for the batch's life |
151
+ | `count` | How many leading slots draw; slots at `count` and above are hidden |
152
+ | `write(index, x, y, w, h, frame, rotation, r, g, b, a, flipX?, flipY?)` | One slot, in world metres, +Y up, and degrees counter-clockwise |
153
+ | `hide(index)` | Hides one slot until it is written again |
154
+ | `dispose()` | Gives the slots back; also runs at the end of a `using` block |
155
+ | `lite.handles` | The Lite `Sprite2DHandle` per slot — unstable escape hatch |
156
156
 
157
157
  ```ts
158
158
  import { createApp } from "ignifx";
@@ -226,7 +226,9 @@ if (canvas instanceof HTMLCanvasElement) {
226
226
  A level kept in a scene file gets its objects once, as entities, from the command line. Each
227
227
  becomes an entity named after the object and tagged with its type, at the object's centre, and the
228
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.
229
+ every object's size and properties for that. The `ignifx` command is an executable of `@ignifx/cli`, which the templates do not install: add
230
+ `@ignifx/cli` to the project's dev dependencies and run `pnpm exec ignifx …`, or run it once with
231
+ `npx --package=@ignifx/cli ignifx …`.
230
232
 
231
233
  ```sh
232
234
  ignifx import tilemap assets/level.tilemap.json assets/scenes/main.scene.json --parent Level
@@ -358,7 +360,7 @@ export function clearRect(map: Tilemap, layer: number, x0: number, y0: number, x
358
360
 
359
361
  ## File formats
360
362
 
361
- Generated reference: `skills/ignifx/references/formats/`.
363
+ Generated reference: `skills/ignifx/references/formats/` in the `ignifx` package.
362
364
 
363
365
  - **`.atlas.json`** (`ignifx.spriteatlas`) — `image` (an address relative to the document, resolved through the manifest; `/x.png` and URLs verbatim), `sampling`,
364
366
  `premultipliedAlpha`, and `frames: [{ name, x, y, w, h, pivot?, sourceSize?, sourceOffset? }]` in **image pixels
@@ -398,7 +400,7 @@ Generated reference: `skills/ignifx/references/formats/`.
398
400
  - **`pixelPerfect` ignores `orthographicSize`** and scales `referenceResolution` by a whole number
399
401
  instead. It does **not** change an atlas's sampling: write `"sampling": "nearest"` in the
400
402
  `.atlas.json`, because a texture's sampler is fixed at upload.
401
- - **A tilemap's objects layer is authoring data.** Nothing spawns from it at runtime (ADR-0030):
403
+ - **A tilemap's objects layer is authoring data.** Nothing spawns from it at runtime:
402
404
  move it into the scene with `ignifx import tilemap`, or read `tilemap.definition.objects` in code.
403
405
  - **Tiles are not pickable.** They have no component, so `pickAt` skips them and looks underneath; use
404
406
  `Tilemap.worldToCell`, which is exact and free.
@@ -422,8 +424,7 @@ Generated reference: `skills/ignifx/references/formats/`.
422
424
  precedence applies as usual.
423
425
  - **`clearColor` is sRGB and presents as authored**, so a channel lands on screen at `value * 255`:
424
426
  `{ r: 0.6, g: 0.2, b: 0.9 }` reads back as bytes `153, 51, 230`, and `#14181F` matches the same
425
- page colour. That is the same in both 2D modes and on the 3D path — one setting, one colour
426
- (`packages/2d/test/clear-color.browser.test.ts`).
427
+ page colour. That is the same in both 2D modes and on the 3D path — one setting, one colour.
427
428
  - **A world whose only camera is a `Camera2D` does not log `IGX-0706`.** Core's "no enabled camera"
428
429
  warning is suppressed while the sprite renderer has an active `Camera2D`, so a correct 2D-only
429
430
  scene is quiet. Build the camera **before** `app.start()`, as the templates do: a world that is
@@ -440,5 +441,6 @@ None (pre-1.0: no deprecation window; breaking changes are listed in the changel
440
441
 
441
442
  ## Where to look next
442
443
 
443
- `skills/ignifx/SKILL.md` for the engine entry skill · `docs/architecture/11-2d-toolkit.md` for
444
- design rationale · `skills/ignifx/references/api/2d.md` for full signatures.
444
+ The entry skill is `skills/ignifx/SKILL.md` in the `ignifx` package: `node_modules/ignifx/` in an
445
+ installed project, the repository root in the engine repository. Under it, `references/api/2d.md` has every exact signature and `references/formats/` the atlas,
446
+ sprite-animation and tilemap field tables.