@ignifx/2d 0.2.1 → 0.3.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.2.1",
3
+ "version": "0.3.0",
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.2.1"
46
+ "@ignifx/core": "0.3.0"
47
47
  },
48
48
  "peerDependencies": {
49
49
  "@babylonjs/lite": "1.27.0",
50
- "@ignifx/core": "0.2.1"
50
+ "@ignifx/core": "0.3.0"
51
51
  },
52
52
  "ignifx": {
53
53
  "extension": true,
@@ -1,9 +1,9 @@
1
1
  ---
2
2
  name: 2d
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, and 2D picking. Use when adding or editing sprites, sprite animation, tilemaps, atlases, sorting layers, or a 2D camera in an ignifx project, or when the user mentions @ignifx/2d, Camera2D, SpriteRenderer, or Tilemap.
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.2.1"
6
+ ignifx-version: "0.3.0"
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.0.0-unreleased`; this package targets `@ignifx/core` `>=0.0.0 <1.0.0`.
24
+ - Engine: ignifx `0.3.0`; this package targets `@ignifx/core` `>=0.0.0 <1.0.0`.
25
25
  - WebGPU only, browser and Electron. Babylon Lite `1.27.0` is a peer dependency.
26
26
  - Register it like any extension; nothing happens at import time.
27
27
 
@@ -121,6 +121,7 @@ Full signatures: `skills/ignifx/references/api/2d.md`.
121
121
  | `layers` | Diagnostics: every Lite layer in draw order |
122
122
  | `registerTileObjectFactory(type, fn)` | What a tilemap's objects layer spawns |
123
123
  | `syncedLastFrame` · `spriteCount` | How many sprites the last frame actually wrote |
124
+ | `createSpriteBatch(options)` | A fixed-capacity crowd of entity-less sprites (`@beta`) |
124
125
  | `lite.renderer` | The Lite `SpriteRenderer`, or `null` headless |
125
126
 
126
127
  ### Components
@@ -136,6 +137,42 @@ Full signatures: `skills/ignifx/references/api/2d.md`.
136
137
  | `SpriteLayerEffect` (`ignifx/SpriteLayerEffect`) | `sortingLayer`, `kind`, `tint`, `params`, `shader` |
137
138
  | `Camera2DFollow` (`ignifx/Camera2DFollow`) | A `Script`; reads `Camera2D`'s follow fields in `lateUpdate` |
138
139
 
140
+ ### `SpriteBatch` — sprites without entities (`@beta`)
141
+
142
+ `app.twoD.createSpriteBatch({ atlas, capacity, sortingLayer?, blend?, screenSpace? })` claims
143
+ `capacity` slots in one Lite layer and hands back a `SpriteBatch` addressed by index. Use it when the
144
+ sprites are not _things_ — bullets, sparks, debris, 2D particles — and one entity each would cost
145
+ more than the drawing does. Use `SpriteRenderer` for anything with a transform, a pick or a place in
146
+ a scene file.
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 |
156
+
157
+ ```ts
158
+ import { createApp } from "ignifx";
159
+ import { twoD } from "@ignifx/2d";
160
+ import type { SpriteAtlasAsset } from "@ignifx/2d";
161
+
162
+ const app = await createApp({ headless: true, extensions: [twoD()] });
163
+ const atlas = app.assets.load<SpriteAtlasAsset>("2d/spark.atlas.json");
164
+ await atlas.promise;
165
+
166
+ const sparks = app.twoD.createSpriteBatch({ atlas, capacity: 2048, blend: "additive" });
167
+ sparks.count = 1;
168
+ // index, centre x/y (metres, +Y up), width/height (metres), frame, rotation (degrees), then RGBA.
169
+ sparks.write(0, 1.5, 0.5, 0.2, 0.2, 0, 0, 1, 0.8, 0.3, 1);
170
+ sparks.dispose();
171
+ ```
172
+
173
+ A batch is not picked, does not sort its own slots, and centres every slot on the `(x, y)` written —
174
+ see the Gotchas.
175
+
139
176
  ### Importers
140
177
 
141
178
  Pure functions, so a build step or a test can call them with no app:
@@ -147,7 +184,9 @@ Pure functions, so a build step or a test can call them with no app:
147
184
  `IGX-1102` unextruded atlas frame (logged, not thrown) · `IGX-1103`/`IGX-1104`/`IGX-1105` unreadable
148
185
  document · `IGX-1106` unknown frame · `IGX-1107` unknown sorting layer · `IGX-1108` unknown clip ·
149
186
  `IGX-1109` unsupported import · `IGX-1110` duplicate object factory · `IGX-1111` cell out of range ·
150
- `IGX-1112` duplicate extension · `IGX-1113` custom effect with no WGSL.
187
+ `IGX-1112` duplicate extension · `IGX-1113` custom effect with no WGSL · `IGX-1114` bad sprite-batch
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.
151
190
 
152
191
  ## Recipes
153
192
 
@@ -230,6 +269,14 @@ Generated reference: `skills/ignifx/references/formats/`.
230
269
  `.atlas.json`, because a texture's sampler is fixed at upload.
231
270
  - **Tiles are not pickable.** They have no component, so `pickAt` skips them; use
232
271
  `Tilemap.worldToCell`, which is exact and free.
272
+ - **A `SpriteBatch` slot is centred on the position written and is never picked.** It ignores the
273
+ frame's pivot — offset the position yourself if you need feet on the ground — and holds no
274
+ component for `pickAt` to resolve. It also does not sort its own slots: on a Y-sorted sorting layer
275
+ Lite sorts them with that layer's sprites, and otherwise they draw in index order. Raising `count`
276
+ reveals slots with the geometry they last carried, so write a slot before counting it in.
277
+ - **Keep a big moving batch off a Y-sorted sorting layer.** One moved sprite marks the whole Lite
278
+ layer unsorted, which costs a merge sort and a full re-upload of every sprite in it that frame.
279
+ Put a thousand particles on their own non-Y-sorted sorting layer instead.
233
280
  - **Register `SpriteLayerEffect` before the first sprite on its layer.** A Lite layer's shader is
234
281
  fixed at creation.
235
282
  - **The sky of a `"sprite"`-mode frame is `rendering.clearColor`, and nothing else.** The sprite pass