@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/README.md +22 -0
- package/dist/index.d.ts +6 -7
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +7 -9
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
- package/skills/2d/SKILL.md +47 -45
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ignifx/2d",
|
|
3
|
-
"version": "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.
|
|
46
|
+
"@ignifx/core": "0.21.1"
|
|
47
47
|
},
|
|
48
48
|
"peerDependencies": {
|
|
49
49
|
"@babylonjs/lite": "1.34.0",
|
|
50
|
-
"@ignifx/core": "0.
|
|
50
|
+
"@ignifx/core": "0.21.1"
|
|
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.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.
|
|
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
|
|
47
|
-
|
|
|
48
|
-
| `mode`
|
|
49
|
-
| `pixelsPerUnit` | `100`
|
|
50
|
-
| `ySort`
|
|
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
|
|
115
|
-
|
|
|
116
|
-
| `pixelsPerUnit` · `mode` · `settings` | The resolved `twoD` section, after any scene override
|
|
117
|
-
| `mainCamera`
|
|
118
|
-
| `pickAt(xPx, yPx, options?)`
|
|
119
|
-
| `pickAllAt(xPx, yPx, options?)`
|
|
120
|
-
| `screenToWorld` · `worldToScreen`
|
|
121
|
-
| `visibleWorldBounds(out)`
|
|
122
|
-
| `layers`
|
|
123
|
-
| `syncedLastFrame` · `spriteCount`
|
|
124
|
-
| `createSpriteBatch(options)`
|
|
125
|
-
| `lite.renderer`
|
|
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`)
|
|
130
|
-
|
|
|
131
|
-
| `Camera2D` (`ignifx/Camera2D`)
|
|
132
|
-
| `SpriteRenderer` (`ignifx/SpriteRenderer`)
|
|
133
|
-
| `SpriteAnimator` (`ignifx/SpriteAnimator`)
|
|
134
|
-
| `Tilemap` (`ignifx/Tilemap`)
|
|
135
|
-
| `TilemapRenderer` (`ignifx/TilemapRenderer`)
|
|
136
|
-
| `ParallaxLayer` (`ignifx/ParallaxLayer`)
|
|
137
|
-
| `SpriteLayerEffect` (`ignifx/SpriteLayerEffect`) | `sortingLayer`, `kind`, `tint`, `params`, `shader`
|
|
138
|
-
| `Camera2DFollow` (`ignifx/Camera2DFollow`)
|
|
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
|
|
149
|
-
|
|
|
150
|
-
| `capacity`
|
|
151
|
-
| `count`
|
|
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)`
|
|
154
|
-
| `dispose()`
|
|
155
|
-
| `lite.handles`
|
|
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
|
|
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`
|
|
444
|
-
|
|
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.
|