lecodes-sdk 0.19.0

package/dist/types/g2/Sprite.d.ts

@@ -0,0 +1,51 @@
+import { type ColorInput } from "../core/color";
+import { Vec2, type Vec2Like } from "../math/vec";
+import { Canvas } from "../canvas/Canvas";
+import { Node2D } from "./Node2D";
+import type { Texture2D } from "./Texture2D";
+/** Anything that can back a sprite: a texture, or a Canvas (baked to a texture on assign). */
+export type TextureSource = Texture2D | Canvas;
+export type SpriteOptions = {
+    texture?: TextureSource;
+    /** Pivot, [0,0] = top-left .. [1,1] = bottom-right. Use [0.5, 1] (feet) for Y-sorted depth. */
+    anchor?: Vec2Like;
+    /** World size; defaults to the texture's pixel dimensions. */
+    size?: Vec2Like;
+    /** Normalized UV sub-rect [u0,v0,u1,v1]. */
+    frame?: [number, number, number, number];
+    /** Tint multiplied with the texture. */
+    color?: ColorInput;
+    opacity?: number;
+    layer?: number;
+    position?: Vec2Like;
+};
+export declare class Sprite extends Node2D {
+    private _texture?;
+    private _anchor;
+    private _color;
+    private _opacity;
+    private _flipX;
+    private _flipY;
+    private _size;
+    constructor(options?: SpriteOptions);
+    get texture(): Texture2D | undefined;
+    set texture(t: TextureSource | undefined);
+    /** Current world size: explicit override if set, else the texture's pixel dimensions (a Canvas-backed
+     *  sprite defaults to the canvas's LOGICAL size, so pixelRatio is crispness only, not size). */
+    get size(): Vec2;
+    set size(v: Vec2Like);
+    get anchor(): Vec2;
+    set anchor(v: Vec2Like);
+    /** Set the UV sub-rect (normalized). */
+    set frame(uv: [number, number, number, number]);
+    /** Set the sub-rect in texture pixels. */
+    setFramePx(px: number, py: number, pw: number, ph: number): this;
+    get color(): ColorInput;
+    set color(c: ColorInput);
+    get opacity(): number;
+    set opacity(a: number);
+    get flipX(): boolean;
+    set flipX(v: boolean);
+    get flipY(): boolean;
+    set flipY(v: boolean);
+}

package/dist/types/g2/SpriteAnimation.d.ts

@@ -0,0 +1,50 @@
+import { Aspect } from "../core/Aspect";
+import { type Vec2Like } from "../math/vec";
+import type { Sprite } from "./Sprite";
+/** Per-clip frame list, or an object for per-clip fps/loop/direction overrides. */
+export type Clip = number[] | {
+    frames: number[];
+    fps?: number;
+    loop?: boolean;
+    perDirection?: boolean;
+};
+export declare class SpriteAnimation extends Aspect<"anim", Sprite> {
+    static readonly aspect = "anim";
+    /** Grid cell size in texture pixels (defaults to the full texture). */
+    size?: [number, number];
+    /** Grid columns override — for sheets with padding; defaults to floor(texWidth / cellWidth). */
+    cols?: number;
+    /** Pixel origin of the grid in the texture — cells index from here (a SpriteSheet region). */
+    origin?: [number, number];
+    /** Default fps for clips that don't override it. */
+    fps: number;
+    /** Default loop for clips that don't override it. */
+    loop: boolean;
+    /** Named clips; frame indices are row-major into the grid. Set via the attach opts. */
+    clips: Record<string, Clip>;
+    /** Facing names in texture-row order (row i = directions[i]) for `perDirection` clips. */
+    directions?: string[];
+    private _clipIds;
+    private _clipNames;
+    private _current;
+    private _defined;
+    private _queued;
+    private _dir;
+    onAttach(): void;
+    /** (Re)build native clips from `this.clips`. Called on attach; call again after changing clips. */
+    define(): this;
+    private _define;
+    /**
+     * Play a clip by name. Re-playing the active clip is a no-op (keeps it running smoothly).
+     * For a `perDirection` clip, `dir` picks the facing — a direction name or a movement vector
+     * (nearest compass row wins); omitted, the last direction (or the first row) is kept.
+     */
+    play(name: string, dir?: string | Vec2Like): this;
+    stop(): this;
+    /** Current facing (last direction resolved by play()), or null before the first directional play. */
+    get direction(): string | null;
+    set speed(value: number);
+    get current(): string | null;
+    get frame(): number;
+    private _resolveDir;
+}

package/dist/types/g2/SpriteSheet.d.ts

@@ -0,0 +1,69 @@
+import { type Vec2Like } from "../math/vec";
+import { Sprite } from "./Sprite";
+import { SpriteAnimation, type Clip } from "./SpriteAnimation";
+import { Texture2D } from "./Texture2D";
+/**
+ * A named region of the image. Just a rect is a static sprite; `slice` subdivides the rect into an
+ * animation grid ([cols, rows] — the cell is rect size / counts); `clips` names frame runs over
+ * that grid (local, row-major). A sliced entry with NO clips loops all of its cells in order.
+ */
+export type SheetSprite = {
+    /** Pixel rect [x, y, w, h] in the image. */
+    rect?: [number, number, number, number];
+    /** Subdivide the rect into an animation grid: [cols, rows]. */
+    slice?: [number, number];
+    /** Playback fps for this sprite's animation (defaults to the sheet fps, then 12). */
+    fps?: number;
+    /** Named clips over the local grid (see SpriteAnimation). Omit to loop every cell. */
+    clips?: Record<string, Clip>;
+    /** Facing names in local-row order for `perDirection` clips (compass tokens: S/SE/E/…). */
+    directions?: string[];
+    /** Overrides the sheet anchor. */
+    anchor?: Vec2Like;
+};
+export type SpriteSheetDef = {
+    /** The image URL — write `asset('./sheet.png')`. */
+    image: string;
+    /** Default pivot for every sprite made from this sheet ([0.5, 1] = feet, for Y-sorted worlds). */
+    anchor?: Vec2Like;
+    /** Default fps for sliced sprites / clips that don't override it. */
+    fps?: number;
+    /** The named sprites. */
+    sprites?: Record<string, SheetSprite>;
+};
+export type SpriteMakeOptions = {
+    position?: Vec2Like;
+    layer?: number;
+    /** Overrides the sheet/sprite anchor. */
+    anchor?: Vec2Like;
+    /** Start this clip immediately (sliced sprites with clips). */
+    clip?: string;
+    /** Initial facing for `perDirection` clips. */
+    direction?: string;
+};
+export declare class SpriteSheet {
+    private _def;
+    private _tex;
+    private _loading;
+    constructor(def: SpriteSheetDef);
+    /** The sheet definition (read-only by convention — the editor owns the file). */
+    get def(): SpriteSheetDef;
+    /** The loaded texture, or null before load() resolves. */
+    get texture(): Texture2D | null;
+    /** Load the sheet's texture (idempotent). make() starts this automatically. */
+    load(): Promise<Texture2D>;
+    /** Names of the sheet's sprites. */
+    get spriteNames(): string[];
+    /** Build a named sprite; starting a clip hands back the animation handle. */
+    make(name: string, opts: SpriteMakeOptions & {
+        clip: string;
+    }): Sprite & {
+        anim: SpriteAnimation;
+    };
+    make(name: string, opts?: SpriteMakeOptions): Sprite;
+    /** The pixel rect [x, y, w, h] of a named sprite's REGION (the whole rect, sliced or not). */
+    rectOf(name: string): [number, number, number, number] | null;
+    private _applyTexture;
+}
+/** Declare a sprite sheet (the default export of a `.sprite.ts` file). */
+export declare const defineSpriteSheet: (def: SpriteSheetDef) => SpriteSheet;

package/dist/types/g2/Texture2D.d.ts

@@ -0,0 +1,16 @@
+import { type FetchResponse, type File } from "../runtime/fetch";
+export declare class Texture2D {
+    /** Native texture handle. */
+    readonly id: number;
+    readonly width: number;
+    readonly height: number;
+    constructor(id: number, width: number, height: number);
+    static fromCanvas(canvas: {
+        _bakeSurface(): number;
+        width: number;
+        height: number;
+        pixelRatio: number;
+    }): Texture2D;
+    static load(source: string | FetchResponse | File): Promise<Texture2D>;
+    destroy(): void;
+}

package/dist/types/g2/Tilemap.d.ts

@@ -0,0 +1,20 @@
+import { Node2D } from "./Node2D";
+import type { Texture2D } from "./Texture2D";
+export type TilemapOptions = {
+    texture: Texture2D;
+    /** Map grid size (in tiles). */
+    cols: number;
+    rows: number;
+    /** On-screen cell size in world units — a single number (square) or [w, h]. */
+    tile: number | [number, number];
+    /** Atlas grid: how the texture is sliced into tiles, [atlasCols, atlasRows]. */
+    atlas: [number, number];
+    /** Row-major tile indices into the atlas (-1 = empty), length cols*rows. Row 0 is the top row. */
+    data: number[] | Int32Array;
+};
+export declare class Tilemap extends Node2D {
+    readonly cols: number;
+    readonly rows: number;
+    constructor(options: TilemapOptions);
+    setTile(x: number, y: number, index: number): this;
+}

package/dist/types/g2/Tileset.d.ts

@@ -0,0 +1,32 @@
+import { Aspect } from "../core/Aspect";
+import type { Node2D } from "./Node2D";
+import { type TilesetDef, type TileMaterial } from "./autotile";
+export declare class Tileset {
+    private _def;
+    constructor(def: TilesetDef);
+    /** The tileset definition (read-only by convention — the editor owns the file). */
+    get def(): TilesetDef;
+    /** Names of the declared materials, in file order. */
+    get materialNames(): string[];
+    /** A material by name. */
+    material(name: string): TileMaterial | undefined;
+    /** The cell value maps store for a named material (what you paint / pass in `data`). */
+    id(name: string): number | undefined;
+    /** Derive display atlas indices from a material-id grid (what Autotile2D does at load). */
+    derive(cols: number, rows: number, data: ArrayLike<number>, seed?: number): Int32Array;
+}
+/** Declare a tileset (the default export of a `.tiles.ts` file). */
+export declare const defineTileset: (def: TilesetDef) => Tileset;
+/**
+ * Marks a tilemap node's `cells` as MATERIAL ids of a tileset instead of raw atlas indices:
+ * `aspects: [use(Autotile2D, { tileset: world })]`. The scene2d loader derives the display
+ * indices (neighbor-mask autotile + seeded scatter, deterministic) before building the tilemap;
+ * the aspect itself holds no behavior. Change `seed` to reshuffle scatter variants.
+ */
+export declare class Autotile2D extends Aspect<"autotile", Node2D> {
+    static readonly aspect = "autotile";
+    /** The imported `.tiles.ts` handle. */
+    tileset: Tileset | null;
+    /** Scatter seed — same seed, same map, same result on every platform. */
+    seed: number;
+}

package/dist/types/g2/Trigger2D.d.ts

@@ -0,0 +1,20 @@
+import { Aspect } from "../core/Aspect";
+import { PhysicsGroup2D } from "./groups2d";
+import type { Node2D } from "./Node2D";
+export declare class Trigger2D extends Aspect<"trigger", Node2D> {
+    static readonly aspect = "trigger";
+    private _h;
+    private _enabled;
+    private _group;
+    private _repush;
+    /** Which collision group this zone belongs to. Live. */
+    get group(): PhysicsGroup2D | undefined;
+    set group(g: PhysicsGroup2D | undefined);
+    /** Native physics body id (0 if no physics support). Mirrors 3D `Trigger.id`. */
+    get id(): number;
+    onAttach(): void;
+    onDetach(): void;
+    /** Switch the zone off and on — a spent pickup, a hitbox that is only live during a swing. */
+    get enabled(): boolean;
+    set enabled(v: boolean);
+}

package/dist/types/g2/autotile.d.ts

@@ -0,0 +1,133 @@
+/** A fill entry: an atlas index, or [index, weight] for seeded scatter variants. */
+export type FillEntry = number | [number, number];
+export type Dir4 = [number, number, number, number];
+/** One side's tiles: a single index (used for every cell along that side), or — with `size` > 1 —
+ *  the `size` indices ALONG it (n/s run left→right, w/e run top→bottom). */
+export type EdgeSlot = number | number[];
+/** A whole `size`×`size` piece: one index (drawn in every cell of the block), or size² indices
+ *  row-major. Path pieces and parts are blocks — at size 1 they are just a tile. */
+export type TileBlock = number | number[];
+/** `size`² indices, row-major within the block. */
+export type FillBlock = number[];
+/** A named element placed BY HAND (a pedestrian crossing in a road, a gate in a fence). It carries
+ *  its own `id`, so the map stores it like any material — but it CONNECTS as its parent, so the
+ *  run continues straight through it. Never picked at random: you paint it from the palette, ONE
+ *  CELL at a time, and the tile is worked out from where that cell sits. */
+export type TilePart = {
+    /** Stable small int, unique across every material and part of the tileset. */
+    id: number;
+    /** Which run the art is drawn for — 'v' vertical, 'h' horizontal. It also picks the art: the
+     *  element varies ACROSS the line (a crossing has one tile per lane) and repeats along it, so
+     *  `tiles` is `size` long, indexed by row for 'h' and by column for 'v'. */
+    axis?: "v" | "h";
+    /** The tiles — one index, `size` across the run when `axis` is set, else the size² block. */
+    tiles?: TileBlock;
+};
+/** A block variant: the block, or [block, weight] for seeded scatter. */
+export type BlockEntry = FillBlock | [FillBlock, number];
+/** One transition set of a patch material — the tiles its border shows against a neighbor. */
+export type PatchSlots = {
+    /** Edge line tiles [n, e, s, w] — e.g. `edges[0]` draws where the patch stops toward the top. */
+    edges?: [EdgeSlot, EdgeSlot, EdgeSlot, EdgeSlot];
+    /** Convex corner tiles [ne, se, sw, nw] — the patch's outside corners. Always one cell. */
+    outer?: Dir4;
+    /** Concave corner tiles [ne, se, sw, nw] — the notch where two patch arms meet. One cell. */
+    inner?: Dir4;
+};
+export type PatchMaterial = {
+    /** Stable small int — what `cells('…')` stores when a map carries Autotile2D. */
+    id: number;
+    kind: "patch";
+    /** Editor swatch color ('#4a7c3a'). */
+    color?: string;
+    /** Block size in cells (default 1). With 2 or 3 the material is classified block-to-block on a
+     *  lattice anchored at the map origin, `fill` holds size² tiles and each edge `size` tiles. */
+    size?: number;
+    /** Interior tile — one index, or an ARRAY of scatter variants (each `index` or
+     *  `[index, weight]`; bare indices weigh 1): `fill: [261, [262, 0.1], [263, 0.05]]`.
+     *  With `size` > 1 it is instead the row-major BLOCK of size² indices
+     *  (`fill: [130, 131, 146, 147]`), or a list of such blocks for scatter variants. */
+    fill: number | FillEntry[] | BlockEntry[];
+    /** Transition sets keyed by the neighboring material's name; '*' = any other neighbor
+     *  (including empty). Baked packs draw a material fading into a SPECIFIC background. */
+    over?: Record<string, PatchSlots>;
+    /** Hand-placed elements that connect as this material (see TilePart). */
+    parts?: Record<string, TilePart>;
+};
+export type PathMaterial = {
+    id: number;
+    kind: "path";
+    color?: string;
+    /** Cells ACROSS the line (default 1). A `size: 2` road is two lanes wide: connectivity runs
+     *  block to block and every piece below is a 2×2 block instead of one tile. */
+    size?: number;
+    /** No connections at all. */
+    isolated?: TileBlock;
+    /** End caps [n, e, s, w] — `ends[0]` connects toward the top only. */
+    ends?: [TileBlock, TileBlock, TileBlock, TileBlock];
+    /** [vertical (n+s), horizontal (e+w)]. */
+    straights?: [TileBlock, TileBlock];
+    /** Elbows [ne, se, sw, nw] — `corners[0]` connects top + right. */
+    corners?: [TileBlock, TileBlock, TileBlock, TileBlock];
+    /** T pieces [n, e, s, w] — `tees[0]` is the tee MISSING the top connection. */
+    tees?: [TileBlock, TileBlock, TileBlock, TileBlock];
+    /** All four connections. */
+    cross?: TileBlock;
+    /** Hand-placed elements that connect as this material (see TilePart). */
+    parts?: Record<string, TilePart>;
+};
+export type TileMaterial = PatchMaterial | PathMaterial;
+export type TilesetDef = {
+    /** The atlas image — write `asset('./TileSet.png')`. */
+    image: string;
+    /** Atlas cell size in image pixels — a number (square) or [w, h]. */
+    tile: number | [number, number];
+    /** Named materials; names are the editor/`over:` vocabulary, `id`s are what maps store. */
+    materials?: Record<string, TileMaterial>;
+};
+export declare const normalizeFill: (fill: number | FillEntry[]) => [number, number][];
+/** A material's block size — 1 unless it declares `size` (clamped to a positive int). */
+export declare const blockSize: (mat: TileMaterial) => number;
+/** One cell of a block: a scalar covers the whole block, an array reads row-major. Undefined =
+ *  unassigned (missing, or the negative sentinel the editor writes for a blank slot). */
+export declare const blockTile: (block: TileBlock | undefined, n: number, lx: number, ly: number) => number | undefined;
+/** How many tiles a part holds: `size` across the run when it declares an axis, else the block. */
+export declare const partSlots: (part: TilePart, n: number) => number;
+/** The cell value that draws atlas tile `index` verbatim in a material map. */
+export declare const rawCell: (index: number) => number;
+/** True for a cell holding a raw atlas tile rather than a material id. */
+export declare const isRawCell: (v: number) => boolean;
+/** The atlas index behind a raw cell (garbage in, garbage out — guard with isRawCell). */
+export declare const rawIndex: (v: number) => number;
+export declare const TILE_INDEX_MASK = 268435455;
+/** The atlas index behind a (possibly oriented) tile value. */
+export declare const tileIndex: (v: number) => number;
+/** Clockwise quarter-turns (0–3) of a tile value. */
+export declare const tileTurns: (v: number) => number;
+/** Whether the tile is mirrored horizontally (the mirror applies before the rotation). */
+export declare const tileFlip: (v: number) => boolean;
+/** True when the value carries any orientation (renderers keep the fast path otherwise). */
+export declare const tileOriented: (v: number) => boolean;
+/** Build an oriented tile value: `index`, mirrored when `flip`, then `turns` quarter-turns CW. */
+export declare const packTile: (index: number, turns?: number, flip?: boolean) => number;
+/** The value rotated a further 90° clockwise. */
+export declare const rot90: (v: number) => number;
+/** The value rotated a further 180°. */
+export declare const rot180: (v: number) => number;
+/** The value rotated a further 270° clockwise (90° counter-clockwise). */
+export declare const rot270: (v: number) => number;
+/** The value mirrored horizontally (on screen — existing turns are re-based, group math). */
+export declare const flipX: (v: number) => number;
+/** The tile a part draws in a cell — indexed ACROSS the run ('h' by row, 'v' by column) so one
+ *  element covers a lane each and repeats along the run; without an axis it is a plain block. */
+export declare const partTile: (part: TilePart, n: number, lx: number, ly: number) => number | undefined;
+/** `fill` as weighted BLOCKS of `size`² indices (row-major). Size 1 keeps the scalar/scatter
+ *  reading; with size > 1 a flat number array is one positional block, an array of arrays is the
+ *  variant list, and a bare number fills the whole block. Missing entries read as -1. */
+export declare const fillBlocks: (fill: PatchMaterial["fill"], size?: number) => [number[], number][];
+/**
+ * Derive display atlas indices from a material-id grid (row-major, row 0 = top, -1 = empty).
+ * Values that match no material id pass through unchanged (so converting maps degrades
+ * gracefully); -1 stays -1. Deterministic: same inputs + seed → same output on every platform.
+ */
+export declare const deriveCells: (def: TilesetDef, cols: number, rows: number, cells: ArrayLike<number>, seed?: number) => Int32Array;

package/dist/types/g2/cells.d.ts

@@ -0,0 +1,14 @@
+export type CellsData = {
+    cols: number;
+    rows: number;
+    /** Row-major tile values (row 0 = the top row), length cols*rows. */
+    data: Int32Array;
+};
+/** Encode a grid into a `cells()` payload (the editor / tools side of the codec). */
+export declare const encodeCells: (cols: number, rows: number, data: ArrayLike<number>) => string;
+/**
+ * Decode a `cells('…')` payload into the grid a tilemap block consumes. Scene files call this via
+ * the injected global; the value is plain data, so hand-written code may pass any
+ * `{ cols, rows, data }` of its own instead (procedural maps).
+ */
+export declare const cells: (payload: string) => CellsData;

package/dist/types/g2/defineScene2d.d.ts

@@ -0,0 +1,141 @@
+import type { ColorInput } from "../core/color";
+import type { Vec2Like } from "../math/vec";
+import { type AspectEntry, type MakeEntry as SharedMakeEntry } from "../scene/grammar";
+import { Scene2D } from "./Scene2D";
+import { Node2D } from "./Node2D";
+import { Sprite } from "./Sprite";
+import { Tilemap } from "./Tilemap";
+import { SpriteSheet } from "./SpriteSheet";
+import type { SpriteAnimation } from "./SpriteAnimation";
+import type { CellsData } from "./cells";
+import type { With } from "../core/Aspect";
+export type Scene2dEnv = {
+    /** Background color — '#5a6b3b', 0x5a6b3b, or [r,g,b] in 0..1. */
+    background?: ColorInput;
+    /** Texture sampling: 'nearest' (crisp pixel art, engine default) or 'linear'. */
+    filter?: "nearest" | "linear";
+    /** Pixel-art crispness: snap the camera to whole screen pixels (seeds CameraFollow's
+     *  `pixelSnap`, and the initial camera position lands on whole world units). */
+    pixelPerfect?: boolean;
+    /** Physics world gravity (Y-up: down is negative). Presence configures the world before any
+     *  body is created — `[0, 0]` for top-down worlds. Omit to leave the world unconfigured. */
+    gravity?: Vec2Like;
+};
+/** A sprite node: one named entry of an imported `.sprite.ts` sheet. The sheet is ART only —
+ *  colliders/bodies are scene semantics: put Shape2D / Physics2D / Trigger2D in `aspects`. */
+export type SpriteSourceDef = {
+    /** The imported sheet handle: `import props from './props.sprite'` … `sheet: props`. */
+    sheet: SpriteSheet;
+    /** The entry name; omit when the sheet declares exactly one sprite. */
+    name?: string;
+    /** Start this clip immediately (sliced entries with clips). */
+    clip?: string;
+    /** Initial facing for `perDirection` clips. */
+    direction?: string;
+};
+export type TilemapSourceDef = {
+    /** The tileset image — `asset('./TileSet.png')`. */
+    texture: string;
+    /** On-screen cell size in world units — a number (square) or [w, h]. */
+    tile: number | [number, number];
+    /** Atlas grid: how the texture slices into tiles, [atlasCols, atlasRows]. */
+    atlas: [number, number];
+    /** The map: a `cells('…')` payload — or any `{ cols, rows, data }` of your own. */
+    cells: CellsData | {
+        cols: number;
+        rows: number;
+        data: number[] | Int32Array;
+    };
+};
+/** A camera marker node: seeds the scene camera's starting position (+ zoom). To MOVE the camera
+ *  in play, attach `CameraFollow` to the node being followed — not aspects on this marker. */
+export type Camera2dNodeDef = {
+    zoom?: number;
+};
+export type Scene2dNodeDef = {
+    sprite?: SpriteSourceDef;
+    tilemap?: TilemapSourceDef;
+    camera?: Camera2dNodeDef;
+    /** A code-built subtree — `make(factoryFn, { ...literal args })`, factory returns a Node2D. */
+    make?: SharedMakeEntry<any, Node2D>;
+    position?: Vec2Like;
+    /** Degrees, CCW. */
+    rotation?: number;
+    scale?: Vec2Like | number;
+    /** Draw layer (int) — higher renders on top. */
+    layer?: number;
+    /** Intra-layer depth for non-Y-sorted layers. */
+    z?: number;
+    /** Sprite tint (sprite nodes only). */
+    color?: ColorInput;
+    /** Sprite opacity 0..1 (sprite nodes only). */
+    opacity?: number;
+    flipX?: boolean;
+    flipY?: boolean;
+    visible?: boolean;
+    /** Editor-only: the move gizmo won't target this node (fields still edit). No runtime effect. */
+    locked?: boolean;
+    aspects?: readonly AspectEntry<any>[];
+    children?: Record<string, Scene2dNodeDef>;
+};
+export type Scene2dCameraDef = {
+    position?: Vec2Like;
+    zoom?: number;
+};
+export type Scene2dDef = {
+    env?: Scene2dEnv;
+    /** Per-layer config, keyed by layer number: `layers: { 1: { ySort: true } }`. */
+    layers?: Record<number | string, {
+        ySort?: boolean;
+    }>;
+    /** Starting camera when there's no camera NODE (a camera node wins). */
+    camera?: Scene2dCameraDef;
+    nodes?: Record<string, Scene2dNodeDef>;
+};
+type SourceNodeOf<N extends Scene2dNodeDef> = N extends {
+    sprite: {
+        clip: string;
+    };
+} ? Sprite & {
+    anim: SpriteAnimation;
+} : N extends {
+    sprite: SpriteSourceDef;
+} ? Sprite : N extends {
+    tilemap: TilemapSourceDef;
+} ? Tilemap : Node2D;
+type AspectsOf<N extends Scene2dNodeDef> = N extends {
+    aspects: readonly AspectEntry<infer A>[];
+} ? A : never;
+type NodeOf<N extends Scene2dNodeDef> = [
+    AspectsOf<N>
+] extends [never] ? SourceNodeOf<N> : With<SourceNodeOf<N>, AspectsOf<N>>;
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+type ChildMapsOf<T extends Record<string, Scene2dNodeDef>> = {
+    [K in keyof T]: T[K] extends {
+        children: infer C extends Record<string, Scene2dNodeDef>;
+    } ? NodesOf<C> : never;
+}[keyof T];
+type NodesOf<T extends Record<string, Scene2dNodeDef>> = {
+    [K in keyof T]: NodeOf<T[K]>;
+} & ([ChildMapsOf<T>] extends [never] ? unknown : UnionToIntersection<ChildMapsOf<T>>);
+export type Scene2dNodes<D extends Scene2dDef> = D["nodes"] extends Record<string, Scene2dNodeDef> ? NodesOf<D["nodes"]> : Record<string, Node2D>;
+export type LoadedScene2d<D extends Scene2dDef> = {
+    scene: Scene2D;
+    nodes: Scene2dNodes<D>;
+};
+export declare class Scene2dHandle<D extends Scene2dDef = Scene2dDef> {
+    readonly def: D;
+    private _loading?;
+    constructor(def: D);
+    /** Instantiate the scene (idempotent — subsequent calls return the same instance). Does not open. */
+    load(): Promise<LoadedScene2d<D>>;
+    /** Load and make active (only the active 2D scene renders). */
+    open(): Promise<LoadedScene2d<D>>;
+}
+/**
+ * Define a 2D scene as data — the default export of a `.scene2d.ts` file. Returns a typed handle:
+ * `const { scene, nodes } = await handle.open()` gives `nodes.<name>` typed by its source block
+ * (Sprite / Tilemap / Node2D) with its `use(...)`d aspects attached.
+ */
+export declare const defineScene2d: <const D extends Scene2dDef>(def: D) => Scene2dHandle<D>;
+export {};

package/dist/types/g2/groups2d.d.ts

@@ -0,0 +1,16 @@
+/** Collides with everything. */
+export declare const ALL_GROUPS = 4294967295;
+export declare class PhysicsGroup2D {
+    /** The single category bit this group owns. */
+    readonly bit: number;
+    /** Optional debug label, so an inspector says "bullets" rather than "group #3". */
+    readonly label: string;
+    private _ignored;
+    /**
+     * Stop colliding with these groups — symmetric, so naming it on one side is enough. Safe to call
+     * after bodies exist: their filters are re-pushed.
+     */
+    ignore(...groups: PhysicsGroup2D[]): this;
+    /** Members of this group don't collide with EACH OTHER — bullets, debris, a ragdoll's own bones. */
+    ignoreSelf(): this;
+}

package/dist/types/g2/loop.d.ts

@@ -0,0 +1,4 @@
+export declare const onUpdate: (callback: (dt: number) => void) => void;
+export declare const offUpdate: (callback: (dt: number) => void) => void;
+export declare const ensureAnimEvents: () => void;
+export declare const ensurePhysicsEvents: () => void;

package/dist/types/g2/scenarios2d.d.ts

@@ -0,0 +1,30 @@
+import { Aspect } from "../core/Aspect";
+import type { Node2D } from "./Node2D";
+import type { Scene2D } from "./Scene2D";
+/**
+ * Ease the scene camera toward this node every frame (attach it to the player). In a `.scene2d.ts`
+ * file the loader wires `scene` automatically; from hand-written code pass it yourself:
+ * `hero.aspect(CameraFollow, { scene })`.
+ *
+ * The eased position accumulates at full precision and only the value PUSHED to the camera is
+ * snapped — reading the snapped camera back as the ease-from value would let tiny sub-pixel steps
+ * round to zero near settle (the follow would stall a few px off-centre, then jump).
+ */
+export declare class CameraFollow extends Aspect<"cameraFollow", Node2D> {
+    static readonly aspect = "cameraFollow";
+    /** The scene2d loader injects the scene into aspects that declare this. */
+    static readonly wantsScene = true;
+    /** The scene whose camera follows (wired by the scene file loader). */
+    scene: Scene2D | null;
+    /** Exponential time constant in seconds; smaller = snappier, 0 = pin the node to centre. */
+    smooth: number;
+    /** Camera offset from the node, in world units. */
+    offset: [number, number];
+    /** Quantize the camera to whole screen pixels so eased motion never shimmers pixel art.
+     *  Defaults to the scene's `env.pixelPerfect` (true when unset). */
+    pixelSnap: boolean;
+    private _x;
+    private _y;
+    private readonly _grid;
+    update(dt: number): void;
+}

package/dist/types/g2/touch.d.ts

@@ -0,0 +1,2 @@
+/** Register the host pointer callback once, on the first click/touchstart listener (node or scene). */
+export declare const ensurePointerEvents: () => void;