@ignifx/2d 0.0.0 → 0.2.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.0.0",
3
+ "version": "0.2.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": true
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": "catalog:",
40
- "@babylonjs/lite": "catalog:",
41
- "@ignifx/core": "workspace:*",
42
- "@microsoft/api-extractor": "catalog:",
43
- "@types/webxr": "catalog:",
44
- "@webgpu/types": "catalog:",
45
- "publint": "catalog:",
46
- "tsdown": "catalog:",
47
- "typedoc": "catalog:",
48
- "typedoc-plugin-markdown": "catalog:",
49
- "typescript-native": "catalog:",
50
- "vitest": "catalog:"
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.2.0"
51
47
  },
52
48
  "peerDependencies": {
53
- "@babylonjs/lite": "catalog:",
54
- "@ignifx/core": "workspace:*"
49
+ "@babylonjs/lite": "1.27.0",
50
+ "@ignifx/core": "0.2.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
+ }
@@ -3,44 +3,249 @@ 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.0.0-unreleased"
6
+ ignifx-version: "0.2.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 provides `Camera2D`, `SpriteRenderer`, `SpriteAnimator`, atlases, `Tilemap`, sorting layers, pixel-perfect rendering, and parallax _(populated in Phase 6)_.
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 version, the pinned Babylon Lite version, and the registration snippet for this extension _(populated in Phase 6)_.
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, and the colour
53
+ a `"sprite"`-mode frame is cleared to is the core `rendering.clearColor` setting — see the Gotchas.
20
54
 
21
55
  ## Mental model
22
56
 
23
- How this subsystem's components, services, and phases fit into the App → World → Entity model _(populated in Phase 6)_.
57
+ ```
58
+ app.twoD (TwoDService)
59
+ ├─ pixelsPerUnit · mode · sortingLayers
60
+ ├─ mainCamera the highest-priority enabled Camera2D
61
+ ├─ pickAt(x, y) CPU pick over the sprite layers → { entity, component, u, v }
62
+ ├─ layers one Lite Sprite2DLayer per (sortingLayer × atlas × blend × space)
63
+ └─ registerTileObjectFactory(type, factory)
64
+
65
+ PostUpdate → SpriteAnimator.advance + animated tiles (ignifx's clock, so timeScale works)
66
+ PreRender → camera view, sprite sync, tilemap chunks (order -450)
67
+ ```
68
+
69
+ World space is **metres, +Y up**. Lite draws in **pixels, +Y down**; the adapter is the only place
70
+ that flip lives. Z is never a draw order — sorting layers and `orderInLayer` are.
24
71
 
25
72
  ## First app
26
73
 
27
- A complete, compiling example that registers the extension and uses it once _(populated in Phase 6)_.
74
+ ```ts
75
+ import { createApp, Vec2 } from "ignifx";
76
+ import { Camera2D, SpriteAnimator, SpriteRenderer, twoD } from "@ignifx/2d";
77
+ import type { SpriteAnimationAsset, SpriteAtlasAsset } from "@ignifx/2d";
78
+
79
+ const canvas = document.querySelector("canvas");
80
+ if (canvas instanceof HTMLCanvasElement) {
81
+ const app = await createApp({ canvas, extensions: [twoD({ pixelsPerUnit: 16 })] });
82
+
83
+ const eye = app.world.createEntity("Camera");
84
+ const camera = eye.addComponent(Camera2D);
85
+ camera.orthographicSize = 5;
86
+
87
+ const atlas = app.assets.load<SpriteAtlasAsset>("2d/hero.atlas.json");
88
+ const clips = app.assets.load<SpriteAnimationAsset>("2d/hero.spriteanim.json");
89
+ await Promise.all([atlas.promise, clips.promise]);
90
+
91
+ const hero = app.world.createEntity("Hero");
92
+ hero.transform.position2D = new Vec2(0, 0);
93
+ const sprite = hero.addComponent(SpriteRenderer);
94
+ sprite.sprite = atlas.retain();
95
+ sprite.sortingLayer = "Default";
96
+
97
+ const animator = hero.addComponent(SpriteAnimator);
98
+ animator.animations = clips.retain();
99
+ animator.play("idle");
100
+
101
+ await app.start();
102
+ }
103
+ ```
104
+
105
+ Await the handles **before** `app.start()`, or pump frames after it: once the loop runs, a completed
106
+ load is delivered in `PreUpdate`.
28
107
 
29
108
  ## Core APIs
30
109
 
31
- Component and service tables generated from `skills/ignifx/references/api/2d.md` _(populated in Phase 6)_.
110
+ Full signatures: `skills/ignifx/references/api/2d.md`.
111
+
112
+ ### `app.twoD` — `TwoDService`
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)` | Topmost `SpriteRenderer` under a viewport pixel, or `null` |
119
+ | `screenToWorld` · `worldToScreen` | Through the active camera |
120
+ | `visibleWorldBounds(out)` | The world rectangle the camera can see |
121
+ | `layers` | Diagnostics: every Lite layer in draw order |
122
+ | `registerTileObjectFactory(type, fn)` | What a tilemap's objects layer spawns |
123
+ | `syncedLastFrame` · `spriteCount` | How many sprites the last frame actually wrote |
124
+ | `lite.renderer` | The Lite `SpriteRenderer`, or `null` headless |
125
+
126
+ ### Components
127
+
128
+ | Component (`typeId`) | Key fields |
129
+ | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
130
+ | `Camera2D` (`ignifx/Camera2D`) | `orthographicSize`, `pixelPerfect`, `referenceResolution`, `boundsMin`/`boundsMax`, `follow`, `deadZone`, `priority` |
131
+ | `SpriteRenderer` (`ignifx/SpriteRenderer`) | `sprite`, `color`, `flipX`/`flipY`, `sortingLayer`, `orderInLayer`, `blend`, `pivotOverride`, `screenSpace`, `pickable` |
132
+ | `SpriteAnimator` (`ignifx/SpriteAnimator`) | `animations`, `defaultClip`, `playOnAwake`, `speed`; `play`/`stop`/`pause`/`resume`, `onClipEnded`, `onEvent` |
133
+ | `Tilemap` (`ignifx/Tilemap`) | `map`, `chunkSize`; `getTile`/`setTile`, `worldToCell`/`cellToWorld`, `collisionData`, `onTileChanged` |
134
+ | `TilemapRenderer` (`ignifx/TilemapRenderer`) | `atlas`, `sortingLayer`, `cullChunks` |
135
+ | `ParallaxLayer` (`ignifx/ParallaxLayer`) | `sortingLayer`, `factor`, `repeatX`/`repeatY`, `repeatWidth`/`repeatHeight` |
136
+ | `SpriteLayerEffect` (`ignifx/SpriteLayerEffect`) | `sortingLayer`, `kind`, `tint`, `params`, `shader` |
137
+ | `Camera2DFollow` (`ignifx/Camera2DFollow`) | A `Script`; reads `Camera2D`'s follow fields in `lateUpdate` |
138
+
139
+ ### Importers
140
+
141
+ Pure functions, so a build step or a test can call them with no app:
142
+ `gridAtlas`, `importTexturePackerAtlas`, `importAsepriteAtlas`, `importAsepriteAnimations`,
143
+ `importTiledMap`, `importLdtkLevel`.
144
+
145
+ ### Error codes
146
+
147
+ `IGX-1102` unextruded atlas frame (logged, not thrown) · `IGX-1103`/`IGX-1104`/`IGX-1105` unreadable
148
+ document · `IGX-1106` unknown frame · `IGX-1107` unknown sorting layer · `IGX-1108` unknown clip ·
149
+ `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.
32
151
 
33
152
  ## Recipes
34
153
 
35
- Task-oriented examples extracted from `examples/recipes/` _(populated in Phase 6)_.
154
+ ### Tilemap with spawned objects
155
+
156
+ ```ts
157
+ import { createApp, Vec2 } from "ignifx";
158
+ import { Tilemap, TilemapRenderer, twoD } from "@ignifx/2d";
159
+ import type { SpriteAtlasAsset, TilemapAsset } from "@ignifx/2d";
160
+ import type { Entity } from "ignifx";
161
+
162
+ const canvas = document.querySelector("canvas");
163
+ if (canvas instanceof HTMLCanvasElement) {
164
+ const app = await createApp({ canvas, extensions: [twoD()] });
165
+
166
+ app.twoD.registerTileObjectFactory("spawn", (context): Entity | null => {
167
+ const player = context.world.createEntity(context.name);
168
+ player.transform.position2D = new Vec2(context.position.x, context.position.y);
169
+ return player;
170
+ });
171
+
172
+ const map = app.assets.load<TilemapAsset>("2d/level-1.tilemap.json");
173
+ const tiles = app.assets.load<SpriteAtlasAsset>("2d/tiles.atlas.json");
174
+ await Promise.all([map.promise, tiles.promise]);
175
+
176
+ const level = app.world.createEntity("Level");
177
+ level.addComponent(Tilemap).map = map.retain();
178
+ level.addComponent(TilemapRenderer).atlas = tiles.retain();
179
+ await app.start();
180
+ }
181
+ ```
182
+
183
+ ### Picking a sprite under the pointer
184
+
185
+ ```ts run
186
+ import { Script } from "ignifx";
187
+
188
+ export class ClickToSelect extends Script {
189
+ static typeId = "game/ClickToSelect";
190
+
191
+ update(): void {
192
+ const hit = this.app.twoD.pickAt(120, 80);
193
+ if (hit !== null) {
194
+ this.app.log.info(`picked ${hit.entity.name}`);
195
+ }
196
+ }
197
+ }
198
+ ```
36
199
 
37
200
  ## File formats
38
201
 
39
- The file formats this subsystem reads and writes, with links to `skills/ignifx/references/formats/` _(populated in Phase 6)_.
202
+ Generated reference: `skills/ignifx/references/formats/`.
203
+
204
+ - **`.atlas.json`** (`ignifx.spriteatlas`) — `image` (an address relative to the document, resolved through the manifest; `/x.png` and URLs verbatim), `sampling`,
205
+ `premultipliedAlpha`, and `frames: [{ name, x, y, w, h, pivot?, sourceSize? }]` in **image pixels
206
+ with a top-left origin**. A pivot is `[x, y]` or `{ x, y }` in `[0, 1]` of the frame; `[0, 0]` is
207
+ top-left. Address one frame with `"2d/hero.atlas.json#frame:idle_0"`.
208
+ - **`.spriteanim.json`** (`ignifx.spriteanimation`) — `atlas` plus
209
+ `clips: [{ name, frames | from/to, fps, loop, events }]`. An event's `frame` is the index **within
210
+ the clip**. `frames` is a list of frame names played in the order written and may skip around the
211
+ sheet; `from`/`to` is an **inclusive range over atlas indices**, so every frame between the two
212
+ endpoints plays — use `frames` when the run is not contiguous in the atlas.
213
+ - **`.tilemap.json`** (`ignifx.tilemap`) — tile size, `cellSize` in metres, tilesets with colliders
214
+ and animations, layers of tile ids (dense or RLE, **top row first**), and an objects layer in
215
+ world metres.
40
216
 
41
217
  ## Gotchas
42
218
 
43
- The traps this subsystem has, each with the replacement to use instead _(populated in Phase 6)_.
219
+ - **`pixelsPerUnit` is 100 by default.** A 32-px sprite is 0.32 metres wide, so a camera with
220
+ `orthographicSize = 5` shows about 31 sprites vertically. Set it to your art's pixel size (16, 32)
221
+ for pixel art.
222
+ - **Cell `(0, 0)` is the bottom-left of a tilemap**, because the world is +Y up — but the file stores
223
+ its rows **top first**, like every editor. `Tilemap` flips on load; `getTile` speaks cells.
224
+ - **`orderInLayer` only reorders inside a Y-sorted layer.** Without `ySort` for that sorting layer,
225
+ Lite draws by insertion order. Turn Y-sort on, or use separate sorting layers.
226
+ - **A frame's pivot moves the sprite, not the layer.** Lite has one pivot per layer, so ignifx
227
+ offsets each sprite instead. A `[0.5, 1]` pivot puts the entity's origin at the sprite's feet.
228
+ - **`pixelPerfect` ignores `orthographicSize`** and scales `referenceResolution` by a whole number
229
+ instead. It does **not** change an atlas's sampling: write `"sampling": "nearest"` in the
230
+ `.atlas.json`, because a texture's sampler is fixed at upload.
231
+ - **Tiles are not pickable.** They have no component, so `pickAt` skips them; use
232
+ `Tilemap.worldToCell`, which is exact and free.
233
+ - **Register `SpriteLayerEffect` before the first sprite on its layer.** A Lite layer's shader is
234
+ fixed at creation.
235
+ - **The sky of a `"sprite"`-mode frame is `rendering.clearColor`, and nothing else.** The sprite pass
236
+ owns the frame and clears it, so neither `Camera.clearColor` nor `Environment.clearColor` reaches
237
+ the screen in a 2D game — and `Camera2D` has no `clearColor` field. Set it in `ignifx.config.ts`
238
+ under `rendering`, not per camera. In `"mixed"` mode the render scene clears instead and the 3D
239
+ precedence applies as usual.
240
+ - **`clearColor` is sRGB and is presented as its linear value**, so a channel lands on screen at
241
+ `srgbToLinear(value) * 255` rather than `value * 255`: `{ r: 0.6, g: 0.2, b: 0.9 }` reads back as
242
+ bytes `81, 8, 201`, and a literal `#14181F` is almost black. That is the same in both 2D modes and
243
+ on the 3D path — one setting, one colour — so pass the inverse if you are matching a page colour.
244
+ Measured on 2026-09-08 (macOS arm64, SwiftShader, `packages/2d/test/clear-color.browser.test.ts`).
245
+ - **A world whose only camera is a `Camera2D` does not log `IGX-0706`.** Core's "no enabled camera"
246
+ warning is suppressed while the sprite renderer has an active `Camera2D`, so a correct 2D-only
247
+ scene is quiet. Build the camera **before** `app.start()`, as the templates do: a world that is
248
+ still empty when the loop starts has no camera of any kind, and that does warn.
44
249
 
45
250
  ## Deprecated (current window)
46
251
 
@@ -48,4 +253,5 @@ None (pre-1.0: no deprecation window; breaking changes are listed in the changel
48
253
 
49
254
  ## Where to look next
50
255
 
51
- `skills/ignifx/SKILL.md` for the engine entry skill · `docs/architecture/` for design rationale.
256
+ `skills/ignifx/SKILL.md` for the engine entry skill · `docs/architecture/11-2d-toolkit.md` for
257
+ design rationale · `skills/ignifx/references/api/2d.md` for full signatures.