@ignifx/2d 0.9.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/dist/index.d.ts +247 -106
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +534 -207
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
- package/skills/2d/SKILL.md +103 -32
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ignifx/2d",
|
|
3
|
-
"version": "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",
|
|
@@ -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.
|
|
46
|
+
"@ignifx/core": "0.10.0"
|
|
47
47
|
},
|
|
48
48
|
"peerDependencies": {
|
|
49
49
|
"@babylonjs/lite": "1.34.0",
|
|
50
|
-
"@ignifx/core": "0.
|
|
50
|
+
"@ignifx/core": "0.10.0"
|
|
51
51
|
},
|
|
52
52
|
"ignifx": {
|
|
53
53
|
"extension": true,
|
package/skills/2d/SKILL.md
CHANGED
|
@@ -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.
|
|
6
|
+
ignifx-version: "0.10.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.
|
|
24
|
+
- Engine: ignifx `0.10.0`; 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
|
|
|
@@ -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)
|
|
62
|
-
├─
|
|
63
|
-
└─
|
|
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)`
|
|
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-
|
|
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
|
|
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.
|
|
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
|
-
- **
|
|
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
|
|