@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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ignifx/2d",
3
- "version": "0.0.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": 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.1.0"
51
47
  },
52
48
  "peerDependencies": {
53
- "@babylonjs/lite": "catalog:",
54
- "@ignifx/core": "workspace:*"
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
+ }
@@ -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.0.0-unreleased"
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 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.
20
53
 
21
54
  ## Mental model
22
55
 
23
- How this subsystem's components, services, and phases fit into the App → World → Entity model _(populated in Phase 6)_.
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
- A complete, compiling example that registers the extension and uses it once _(populated in Phase 6)_.
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
- Component and service tables generated from `skills/ignifx/references/api/2d.md` _(populated in Phase 6)_.
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
- Task-oriented examples extracted from `examples/recipes/` _(populated in Phase 6)_.
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
- The file formats this subsystem reads and writes, with links to `skills/ignifx/references/formats/` _(populated in Phase 6)_.
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
- The traps this subsystem has, each with the replacement to use instead _(populated in Phase 6)_.
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/` for design rationale.
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.