@ignifx/2d 0.0.0 → 0.1.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/LICENSE +201 -0
- package/dist/index.d.ts +615 -354
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2101 -1627
- package/dist/index.js.map +1 -1
- package/package.json +38 -27
- package/skills/2d/SKILL.md +203 -12
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ignifx/2d",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.1.0",
|
|
4
4
|
"description": "ignifx 2D toolkit: Camera2D, sprites, sprite animation, atlases, tilemaps, sorting layers, pixel-perfect, parallax.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"ignifx",
|
|
@@ -9,6 +9,11 @@
|
|
|
9
9
|
"homepage": "https://ignifx.com",
|
|
10
10
|
"license": "Apache-2.0",
|
|
11
11
|
"author": "Astrum Forge Studios",
|
|
12
|
+
"repository": {
|
|
13
|
+
"type": "git",
|
|
14
|
+
"url": "git+https://github.com/astrum-forge/ignifx.git",
|
|
15
|
+
"directory": "packages/2d"
|
|
16
|
+
},
|
|
12
17
|
"files": [
|
|
13
18
|
"dist",
|
|
14
19
|
"skills"
|
|
@@ -24,41 +29,47 @@
|
|
|
24
29
|
},
|
|
25
30
|
"publishConfig": {
|
|
26
31
|
"access": "public",
|
|
27
|
-
"provenance":
|
|
28
|
-
},
|
|
29
|
-
"scripts": {
|
|
30
|
-
"build": "tsdown",
|
|
31
|
-
"typecheck": "tsc --build tsconfig.json tsconfig.test.json",
|
|
32
|
-
"test": "vitest run --project node --root ../.. packages/2d",
|
|
33
|
-
"api-report": "api-extractor run --verbose",
|
|
34
|
-
"docs:api": "typedoc",
|
|
35
|
-
"api-report:update": "api-extractor run --local --verbose",
|
|
36
|
-
"pack-check": "publint && attw --pack . --profile esm-only"
|
|
32
|
+
"provenance": false
|
|
37
33
|
},
|
|
38
34
|
"devDependencies": {
|
|
39
|
-
"@arethetypeswrong/cli": "
|
|
40
|
-
"@babylonjs/lite": "
|
|
41
|
-
"@
|
|
42
|
-
"@
|
|
43
|
-
"@types
|
|
44
|
-
"
|
|
45
|
-
"
|
|
46
|
-
"
|
|
47
|
-
"typedoc": "
|
|
48
|
-
"
|
|
49
|
-
"
|
|
50
|
-
"
|
|
35
|
+
"@arethetypeswrong/cli": "^0.18.5",
|
|
36
|
+
"@babylonjs/lite": "1.27.0",
|
|
37
|
+
"@microsoft/api-extractor": "^7.59.0",
|
|
38
|
+
"@types/webxr": "^0.5.0",
|
|
39
|
+
"@webgpu/types": "^0.1.72",
|
|
40
|
+
"publint": "^0.3.24",
|
|
41
|
+
"tsdown": "^0.23.0",
|
|
42
|
+
"typedoc": "^0.28.20",
|
|
43
|
+
"typedoc-plugin-markdown": "^4.13.0",
|
|
44
|
+
"typescript-native": "npm:typescript@7.0.2",
|
|
45
|
+
"vitest": "^5.0.0",
|
|
46
|
+
"@ignifx/core": "0.1.0"
|
|
51
47
|
},
|
|
52
48
|
"peerDependencies": {
|
|
53
|
-
"@babylonjs/lite": "
|
|
54
|
-
"@ignifx/core": "
|
|
49
|
+
"@babylonjs/lite": "1.27.0",
|
|
50
|
+
"@ignifx/core": "0.1.0"
|
|
55
51
|
},
|
|
56
52
|
"ignifx": {
|
|
57
53
|
"extension": true,
|
|
58
54
|
"engine": ">=0.0.0 <1.0.0",
|
|
59
55
|
"requires": [],
|
|
60
56
|
"optional": [],
|
|
61
|
-
"capabilities": [
|
|
57
|
+
"capabilities": [
|
|
58
|
+
"components",
|
|
59
|
+
"systems",
|
|
60
|
+
"services",
|
|
61
|
+
"settings",
|
|
62
|
+
"assets"
|
|
63
|
+
],
|
|
62
64
|
"skill": "./skills/2d/SKILL.md"
|
|
65
|
+
},
|
|
66
|
+
"scripts": {
|
|
67
|
+
"build": "tsdown",
|
|
68
|
+
"typecheck": "tsc --build tsconfig.json tsconfig.test.json",
|
|
69
|
+
"test": "vitest run --project node --root ../.. packages/2d",
|
|
70
|
+
"api-report": "api-extractor run --verbose",
|
|
71
|
+
"docs:api": "typedoc",
|
|
72
|
+
"api-report:update": "api-extractor run --local --verbose",
|
|
73
|
+
"pack-check": "publint && attw --pack . --profile esm-only"
|
|
63
74
|
}
|
|
64
|
-
}
|
|
75
|
+
}
|
package/skills/2d/SKILL.md
CHANGED
|
@@ -3,44 +3,234 @@ 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, 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.
|
|
4
4
|
license: Apache-2.0
|
|
5
5
|
metadata:
|
|
6
|
-
ignifx-version: "0.
|
|
6
|
+
ignifx-version: "0.1.0"
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
# @ignifx/2d
|
|
10
10
|
|
|
11
|
-
> **Scaffold notice.** ignifx is in the planning phase and `@ignifx/2d` is an empty package. Every section below is filled by Phase 6 of `docs/plan/engineering-plan.md`; until then this file makes no API claims (`CONSTITUTION.md` Article V).
|
|
12
|
-
|
|
13
11
|
## What this is / when to use
|
|
14
12
|
|
|
15
|
-
`@ignifx/2d` is the ignifx extension that
|
|
13
|
+
`@ignifx/2d` is the ignifx extension that draws **sprites**. It uses the same entities, transforms,
|
|
14
|
+
scripts, assets and phases as 3D — only the camera, the renderer and the sorting model differ.
|
|
15
|
+
|
|
16
|
+
Use it for anything drawn from a texture atlas: characters, tilemaps, HUD art, parallax backdrops,
|
|
17
|
+
2D pickable objects. Pair it with `@ignifx/physics-2d` for collision.
|
|
18
|
+
|
|
19
|
+
The whole toolkit works under `createApp({ headless: true })`: components keep their state, loaders
|
|
20
|
+
parse, `SpriteAnimator` advances on the stepped clock. Only the pixels need a GPU.
|
|
16
21
|
|
|
17
22
|
## Environment
|
|
18
23
|
|
|
19
|
-
Engine
|
|
24
|
+
- Engine: ignifx `0.0.0-unreleased`; 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.
|
|
26
|
+
- Register it like any extension; nothing happens at import time.
|
|
27
|
+
|
|
28
|
+
```ts
|
|
29
|
+
import { createApp } from "ignifx";
|
|
30
|
+
import { twoD } from "@ignifx/2d";
|
|
31
|
+
|
|
32
|
+
const canvas = document.querySelector("canvas");
|
|
33
|
+
if (canvas instanceof HTMLCanvasElement) {
|
|
34
|
+
const app = await createApp({
|
|
35
|
+
canvas,
|
|
36
|
+
settings: { sortingLayers: { sortingLayers: ["Background", "Default", "Foreground"] } },
|
|
37
|
+
extensions: [twoD({ pixelsPerUnit: 16, ySort: { Default: true } })],
|
|
38
|
+
});
|
|
39
|
+
await app.start();
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
`ignifx.config.ts` carries the same settings under `twoD`, and a scene file's `settings.twoD` block
|
|
44
|
+
overrides them for that scene:
|
|
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 |
|
|
51
|
+
|
|
52
|
+
Sorting layers themselves live in the **core** `sortingLayers` section, back to front.
|
|
20
53
|
|
|
21
54
|
## Mental model
|
|
22
55
|
|
|
23
|
-
|
|
56
|
+
```
|
|
57
|
+
app.twoD (TwoDService)
|
|
58
|
+
├─ pixelsPerUnit · mode · sortingLayers
|
|
59
|
+
├─ mainCamera the highest-priority enabled Camera2D
|
|
60
|
+
├─ pickAt(x, y) CPU pick over the sprite layers → { entity, component, u, v }
|
|
61
|
+
├─ layers one Lite Sprite2DLayer per (sortingLayer × atlas × blend × space)
|
|
62
|
+
└─ registerTileObjectFactory(type, factory)
|
|
63
|
+
|
|
64
|
+
PostUpdate → SpriteAnimator.advance + animated tiles (ignifx's clock, so timeScale works)
|
|
65
|
+
PreRender → camera view, sprite sync, tilemap chunks (order -450)
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
World space is **metres, +Y up**. Lite draws in **pixels, +Y down**; the adapter is the only place
|
|
69
|
+
that flip lives. Z is never a draw order — sorting layers and `orderInLayer` are.
|
|
24
70
|
|
|
25
71
|
## First app
|
|
26
72
|
|
|
27
|
-
|
|
73
|
+
```ts
|
|
74
|
+
import { createApp, Vec2 } from "ignifx";
|
|
75
|
+
import { Camera2D, SpriteAnimator, SpriteRenderer, twoD } from "@ignifx/2d";
|
|
76
|
+
import type { SpriteAnimationAsset, SpriteAtlasAsset } from "@ignifx/2d";
|
|
77
|
+
|
|
78
|
+
const canvas = document.querySelector("canvas");
|
|
79
|
+
if (canvas instanceof HTMLCanvasElement) {
|
|
80
|
+
const app = await createApp({ canvas, extensions: [twoD({ pixelsPerUnit: 16 })] });
|
|
81
|
+
|
|
82
|
+
const eye = app.world.createEntity("Camera");
|
|
83
|
+
const camera = eye.addComponent(Camera2D);
|
|
84
|
+
camera.orthographicSize = 5;
|
|
85
|
+
|
|
86
|
+
const atlas = app.assets.load<SpriteAtlasAsset>("2d/hero.atlas.json");
|
|
87
|
+
const clips = app.assets.load<SpriteAnimationAsset>("2d/hero.spriteanim.json");
|
|
88
|
+
await Promise.all([atlas.promise, clips.promise]);
|
|
89
|
+
|
|
90
|
+
const hero = app.world.createEntity("Hero");
|
|
91
|
+
hero.transform.position2D = new Vec2(0, 0);
|
|
92
|
+
const sprite = hero.addComponent(SpriteRenderer);
|
|
93
|
+
sprite.sprite = atlas.retain();
|
|
94
|
+
sprite.sortingLayer = "Default";
|
|
95
|
+
|
|
96
|
+
const animator = hero.addComponent(SpriteAnimator);
|
|
97
|
+
animator.animations = clips.retain();
|
|
98
|
+
animator.play("idle");
|
|
99
|
+
|
|
100
|
+
await app.start();
|
|
101
|
+
}
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Await the handles **before** `app.start()`, or pump frames after it: once the loop runs, a completed
|
|
105
|
+
load is delivered in `PreUpdate`.
|
|
28
106
|
|
|
29
107
|
## Core APIs
|
|
30
108
|
|
|
31
|
-
|
|
109
|
+
Full signatures: `skills/ignifx/references/api/2d.md`.
|
|
110
|
+
|
|
111
|
+
### `app.twoD` — `TwoDService`
|
|
112
|
+
|
|
113
|
+
| Member | Meaning |
|
|
114
|
+
| ------------------------------------- | ---------------------------------------------------------- |
|
|
115
|
+
| `pixelsPerUnit` · `mode` · `settings` | The resolved `twoD` section, after any scene override |
|
|
116
|
+
| `mainCamera` | The highest-priority enabled `Camera2D`, or `null` |
|
|
117
|
+
| `pickAt(xPx, yPx)` | Topmost `SpriteRenderer` under a viewport pixel, or `null` |
|
|
118
|
+
| `screenToWorld` · `worldToScreen` | Through the active camera |
|
|
119
|
+
| `visibleWorldBounds(out)` | The world rectangle the camera can see |
|
|
120
|
+
| `layers` | Diagnostics: every Lite layer in draw order |
|
|
121
|
+
| `registerTileObjectFactory(type, fn)` | What a tilemap's objects layer spawns |
|
|
122
|
+
| `syncedLastFrame` · `spriteCount` | How many sprites the last frame actually wrote |
|
|
123
|
+
| `lite.renderer` | The Lite `SpriteRenderer`, or `null` headless |
|
|
124
|
+
|
|
125
|
+
### Components
|
|
126
|
+
|
|
127
|
+
| Component (`typeId`) | Key fields |
|
|
128
|
+
| ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
|
|
129
|
+
| `Camera2D` (`ignifx/Camera2D`) | `orthographicSize`, `pixelPerfect`, `referenceResolution`, `boundsMin`/`boundsMax`, `follow`, `deadZone`, `priority` |
|
|
130
|
+
| `SpriteRenderer` (`ignifx/SpriteRenderer`) | `sprite`, `color`, `flipX`/`flipY`, `sortingLayer`, `orderInLayer`, `blend`, `pivotOverride`, `screenSpace`, `pickable` |
|
|
131
|
+
| `SpriteAnimator` (`ignifx/SpriteAnimator`) | `animations`, `defaultClip`, `playOnAwake`, `speed`; `play`/`stop`/`pause`/`resume`, `onClipEnded`, `onEvent` |
|
|
132
|
+
| `Tilemap` (`ignifx/Tilemap`) | `map`, `chunkSize`; `getTile`/`setTile`, `worldToCell`/`cellToWorld`, `collisionData`, `onTileChanged` |
|
|
133
|
+
| `TilemapRenderer` (`ignifx/TilemapRenderer`) | `atlas`, `sortingLayer`, `cullChunks` |
|
|
134
|
+
| `ParallaxLayer` (`ignifx/ParallaxLayer`) | `sortingLayer`, `factor`, `repeatX`/`repeatY`, `repeatWidth`/`repeatHeight` |
|
|
135
|
+
| `SpriteLayerEffect` (`ignifx/SpriteLayerEffect`) | `sortingLayer`, `kind`, `tint`, `params`, `shader` |
|
|
136
|
+
| `Camera2DFollow` (`ignifx/Camera2DFollow`) | A `Script`; reads `Camera2D`'s follow fields in `lateUpdate` |
|
|
137
|
+
|
|
138
|
+
### Importers
|
|
139
|
+
|
|
140
|
+
Pure functions, so a build step or a test can call them with no app:
|
|
141
|
+
`gridAtlas`, `importTexturePackerAtlas`, `importAsepriteAtlas`, `importAsepriteAnimations`,
|
|
142
|
+
`importTiledMap`, `importLdtkLevel`.
|
|
143
|
+
|
|
144
|
+
### Error codes
|
|
145
|
+
|
|
146
|
+
`IGX-1102` unextruded atlas frame (logged, not thrown) · `IGX-1103`/`IGX-1104`/`IGX-1105` unreadable
|
|
147
|
+
document · `IGX-1106` unknown frame · `IGX-1107` unknown sorting layer · `IGX-1108` unknown clip ·
|
|
148
|
+
`IGX-1109` unsupported import · `IGX-1110` duplicate object factory · `IGX-1111` cell out of range ·
|
|
149
|
+
`IGX-1112` duplicate extension · `IGX-1113` custom effect with no WGSL.
|
|
32
150
|
|
|
33
151
|
## Recipes
|
|
34
152
|
|
|
35
|
-
|
|
153
|
+
### Tilemap with spawned objects
|
|
154
|
+
|
|
155
|
+
```ts
|
|
156
|
+
import { createApp, Vec2 } from "ignifx";
|
|
157
|
+
import { Tilemap, TilemapRenderer, twoD } from "@ignifx/2d";
|
|
158
|
+
import type { SpriteAtlasAsset, TilemapAsset } from "@ignifx/2d";
|
|
159
|
+
import type { Entity } from "ignifx";
|
|
160
|
+
|
|
161
|
+
const canvas = document.querySelector("canvas");
|
|
162
|
+
if (canvas instanceof HTMLCanvasElement) {
|
|
163
|
+
const app = await createApp({ canvas, extensions: [twoD()] });
|
|
164
|
+
|
|
165
|
+
app.twoD.registerTileObjectFactory("spawn", (context): Entity | null => {
|
|
166
|
+
const player = context.world.createEntity(context.name);
|
|
167
|
+
player.transform.position2D = new Vec2(context.position.x, context.position.y);
|
|
168
|
+
return player;
|
|
169
|
+
});
|
|
170
|
+
|
|
171
|
+
const map = app.assets.load<TilemapAsset>("2d/level-1.tilemap.json");
|
|
172
|
+
const tiles = app.assets.load<SpriteAtlasAsset>("2d/tiles.atlas.json");
|
|
173
|
+
await Promise.all([map.promise, tiles.promise]);
|
|
174
|
+
|
|
175
|
+
const level = app.world.createEntity("Level");
|
|
176
|
+
level.addComponent(Tilemap).map = map.retain();
|
|
177
|
+
level.addComponent(TilemapRenderer).atlas = tiles.retain();
|
|
178
|
+
await app.start();
|
|
179
|
+
}
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
### Picking a sprite under the pointer
|
|
183
|
+
|
|
184
|
+
```ts run
|
|
185
|
+
import { Script } from "ignifx";
|
|
186
|
+
|
|
187
|
+
export class ClickToSelect extends Script {
|
|
188
|
+
static typeId = "game/ClickToSelect";
|
|
189
|
+
|
|
190
|
+
update(): void {
|
|
191
|
+
const hit = this.app.twoD.pickAt(120, 80);
|
|
192
|
+
if (hit !== null) {
|
|
193
|
+
this.app.log.info(`picked ${hit.entity.name}`);
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
}
|
|
197
|
+
```
|
|
36
198
|
|
|
37
199
|
## File formats
|
|
38
200
|
|
|
39
|
-
|
|
201
|
+
Generated reference: `skills/ignifx/references/formats/`.
|
|
202
|
+
|
|
203
|
+
- **`.atlas.json`** (`ignifx.spriteatlas`) — `image` (an address relative to the document, resolved through the manifest; `/x.png` and URLs verbatim), `sampling`,
|
|
204
|
+
`premultipliedAlpha`, and `frames: [{ name, x, y, w, h, pivot?, sourceSize? }]` in **image pixels
|
|
205
|
+
with a top-left origin**. A pivot is `[x, y]` or `{ x, y }` in `[0, 1]` of the frame; `[0, 0]` is
|
|
206
|
+
top-left. Address one frame with `"2d/hero.atlas.json#frame:idle_0"`.
|
|
207
|
+
- **`.spriteanim.json`** (`ignifx.spriteanimation`) — `atlas` plus
|
|
208
|
+
`clips: [{ name, frames | from/to, fps, loop, events }]`. An event's `frame` is the index **within
|
|
209
|
+
the clip**. `frames` is a list of frame names played in the order written and may skip around the
|
|
210
|
+
sheet; `from`/`to` is an **inclusive range over atlas indices**, so every frame between the two
|
|
211
|
+
endpoints plays — use `frames` when the run is not contiguous in the atlas.
|
|
212
|
+
- **`.tilemap.json`** (`ignifx.tilemap`) — tile size, `cellSize` in metres, tilesets with colliders
|
|
213
|
+
and animations, layers of tile ids (dense or RLE, **top row first**), and an objects layer in
|
|
214
|
+
world metres.
|
|
40
215
|
|
|
41
216
|
## Gotchas
|
|
42
217
|
|
|
43
|
-
|
|
218
|
+
- **`pixelsPerUnit` is 100 by default.** A 32-px sprite is 0.32 metres wide, so a camera with
|
|
219
|
+
`orthographicSize = 5` shows about 31 sprites vertically. Set it to your art's pixel size (16, 32)
|
|
220
|
+
for pixel art.
|
|
221
|
+
- **Cell `(0, 0)` is the bottom-left of a tilemap**, because the world is +Y up — but the file stores
|
|
222
|
+
its rows **top first**, like every editor. `Tilemap` flips on load; `getTile` speaks cells.
|
|
223
|
+
- **`orderInLayer` only reorders inside a Y-sorted layer.** Without `ySort` for that sorting layer,
|
|
224
|
+
Lite draws by insertion order. Turn Y-sort on, or use separate sorting layers.
|
|
225
|
+
- **A frame's pivot moves the sprite, not the layer.** Lite has one pivot per layer, so ignifx
|
|
226
|
+
offsets each sprite instead. A `[0.5, 1]` pivot puts the entity's origin at the sprite's feet.
|
|
227
|
+
- **`pixelPerfect` ignores `orthographicSize`** and scales `referenceResolution` by a whole number
|
|
228
|
+
instead. It does **not** change an atlas's sampling: write `"sampling": "nearest"` in the
|
|
229
|
+
`.atlas.json`, because a texture's sampler is fixed at upload.
|
|
230
|
+
- **Tiles are not pickable.** They have no component, so `pickAt` skips them; use
|
|
231
|
+
`Tilemap.worldToCell`, which is exact and free.
|
|
232
|
+
- **Register `SpriteLayerEffect` before the first sprite on its layer.** A Lite layer's shader is
|
|
233
|
+
fixed at creation.
|
|
44
234
|
|
|
45
235
|
## Deprecated (current window)
|
|
46
236
|
|
|
@@ -48,4 +238,5 @@ None (pre-1.0: no deprecation window; breaking changes are listed in the changel
|
|
|
48
238
|
|
|
49
239
|
## Where to look next
|
|
50
240
|
|
|
51
|
-
`skills/ignifx/SKILL.md` for the engine entry skill · `docs/architecture
|
|
241
|
+
`skills/ignifx/SKILL.md` for the engine entry skill · `docs/architecture/11-2d-toolkit.md` for
|
|
242
|
+
design rationale · `skills/ignifx/references/api/2d.md` for full signatures.
|