@ludic-labs/assembly 0.0.0-stage → 0.4.0

package/dist/sprite-scene.d.ts

@@ -0,0 +1,277 @@
+import type { AssetSpec, CompiledAsset, Vec3 } from "./types.js";
+import type { PixelCamera } from "./pixel.js";
+import type { SpriteView, SpriteResult, SpriteDocument } from "./sprite-types.js";
+export interface SpriteSceneDocument {
+    format: "pixel-sprite-scene/0.1";
+    id?: string;
+    title?: string;
+    description?: string;
+    units?: "meters";
+    notes?: unknown;
+    pixelsPerMetre: number;
+    outline: string;
+    assets: Record<string, {
+        sprite: string;
+        states?: Record<string, {
+            clip: string;
+            phase: number;
+        }>;
+    }>;
+    placements: SpriteScenePlacement[];
+    views: Record<string, {
+        camera: SpriteView["camera"];
+        hide?: string[];
+    }>;
+}
+export interface SpriteScenePlacement {
+    id: string;
+    asset: string;
+    position: Vec3;
+    yaw?: number;
+    tint?: string | null;
+    order?: "back";
+    states?: string[];
+}
+export interface SpriteSceneAsset {
+    ref: string;
+    spec: AssetSpec;
+    compiled: CompiledAsset;
+    motion: unknown;
+    sprite: string;
+    states: Record<string, {
+        clip: string;
+        phase: number;
+    }>;
+}
+export type SpriteSceneResolver = (ref: string) => {
+    spec: AssetSpec;
+    motion?: unknown;
+};
+export interface SpriteScene {
+    scene: SpriteSceneDocument;
+    assets: Map<string, SpriteSceneAsset>;
+    placements: (SpriteScenePlacement & {
+        yaw: number;
+        tint: string | null;
+    })[];
+}
+export interface SpriteSceneOptions {
+    states?: Record<string, string>;
+    background?: string | null;
+    depth?: "parts" | "placements";
+}
+export interface SpriteSceneImage {
+    view: string;
+    width: number;
+    height: number;
+    rgba: Uint8Array;
+    owner: Int32Array;
+    part: (string | null)[];
+    placed: {
+        id: string;
+        asset: string;
+        state: string;
+        cel: string;
+        at: [number, number];
+        size: [number, number];
+        mask: number[];
+    }[];
+    skipped: string[];
+}
+export interface SpriteScenePalette {
+    palette: {
+        lock: boolean;
+        colors: Record<string, string>;
+        ramps: Record<string, string[]>;
+    };
+    materials: Record<string, Record<string, string>>;
+}
+/** Prepare a scene using caller-owned asset JSON; performs no IO. */
+export declare function prepareSpriteScene(scene: SpriteSceneDocument, resolve: SpriteSceneResolver): SpriteScene;
+export declare const cameraOf: (camera: SpriteView["camera"]) => PixelCamera;
+/** Name of the asset view for a scene view and state ("dimetric", "dimetric-open"). */
+export declare const assetViewName: (view: string, state?: string) => string;
+/** Cel id a placement shows in a scene view and state. */
+export declare const celIdFor: (view: string, state?: string) => string;
+/**
+ * The asset-local view a placement needs: a placement with yaw ψ seen by a
+ * camera of yaw φ is its asset seen from yaw φ − ψ at the same pitch.
+ */
+export declare function placementView(loaded: SpriteScene, placement: SpriteScene["placements"][number], view: string, state?: string): SpriteView;
+/** The states an asset offers, idle first. */
+export declare const statesOf: (loaded: SpriteScene, ref: string) => string[];
+/** The `views` object an asset's sprite document must declare, and the cels it must contain. */
+export declare function assetViews(loaded: SpriteScene, ref: string): {
+    views: Record<string, SpriteView>;
+    cels: string[];
+};
+/** Scene instances for a view (cutaways applied), optionally only some placements, with states. */
+export declare function sceneInstances(loaded: SpriteScene, view: string, { only, states }?: {
+    only?: string[] | null;
+    states?: Record<string, string>;
+}): import("./pixel.js").PixelInstance[];
+/**
+ * The scene's pixel grid in a view: canvas size and the world position of its
+ * top-left corner along camera right and up, fitted to every placement at rest.
+ */
+export declare function sceneFrame(loaded: SpriteScene, view: string, margin?: number): {
+    camera: PixelCamera;
+    ppm: number;
+    width: number;
+    height: number;
+    originX: number;
+    originY: number;
+    frame: {
+        center: Vec3;
+        width: number;
+        height: number;
+    };
+};
+/** 3D reference render (arcade profile) of the scene, or of some placements, on the scene grid. */
+export declare function sceneRender(loaded: SpriteScene, view: string, { only, states, background, }?: {
+    only?: string[] | null;
+    states?: Record<string, string>;
+    background?: string | null;
+}): import("./pixel.js").PixelImage;
+/** Screen offset (pixels, unrounded) of a placement's asset-local origin on the scene grid. */
+export declare function placementOffset(loaded: SpriteScene, placement: SpriteScene["placements"][number], view: string): {
+    x: number;
+    y: number;
+    depth: number;
+};
+/** Materials closer than this in OKLab share one ramp. */
+export declare const MERGE_DISTANCE = 0.015;
+/**
+ * One locked palette for the whole scene: four tones (deep, shadow, mid,
+ * light) per material colour as placed (tints applied), from the /pixel arcade
+ * ramp, with near-identical materials merged, plus the shared outline `line`.
+ * Returns the palette, and per asset the ramp of each material.
+ */
+export declare function scenePalette(loaded: SpriteScene): SpriteScenePalette;
+/**
+ * A short descriptive name for a colour from its OKLab value ("pale-teal",
+ * "dark-red", "cream", "charcoal"), so ramps read as what they look like.
+ */
+export declare function colourName([L, a, b]: Vec3): string;
+/** The palette subset an asset's document uses: its materials' ramps and the outline. */
+export declare function assetPalette(shared: SpriteScenePalette, ref: string): SpriteScenePalette["palette"];
+/** Per part of an asset: its material and the scene ramp that material uses. */
+export declare function partRamps(loaded: SpriteScene, shared: SpriteScenePalette, ref: string): Record<string, {
+    material: string;
+    ramp: string | null;
+}>;
+/** Compiles one asset's document with the kitchen resolvers and checks it against the scene's contract. */
+export declare function compileAssetSprite(loaded: SpriteScene, shared: SpriteScenePalette, ref: string, input: SpriteDocument): {
+    result: SpriteResult;
+    problems: string[];
+    cels: string[];
+};
+/** Share of two placements' 3D overlap that must disagree before their draw order is reported as wrong. */
+export declare const ORDER_SHARE = 0.25;
+/** Back-to-front order: "back" placements (the room) first, then by bounds-centre depth. */
+export declare function drawOrder(loaded: SpriteScene, view: string, states?: Record<string, string>): (SpriteScenePlacement & {
+    yaw: number;
+    tint: string | null;
+})[];
+/** One placement's drawn cel, placed on a scene grid with a depth per pixel. */
+export interface SpriteSceneLayer {
+    id: string;
+    asset: string;
+    state: string;
+    cel: string;
+    /** Top-left of the cel on the scene grid. */
+    at: [number, number];
+    width: number;
+    height: number;
+    rgba: Uint8Array;
+    /** Per cel pixel: index into `parts`, or -1. */
+    owners: Int32Array;
+    parts: string[];
+    /** Per cel pixel: distance toward the camera (larger is nearer); NaN where empty. */
+    depth: Float64Array;
+    /** "back" placements (a room) are behind everything. */
+    back: boolean;
+    /** Draw-order key: depth of the placement's (posed) bounds centre. */
+    order: number;
+}
+export interface SpriteSceneLayers {
+    view: string;
+    width: number;
+    height: number;
+    layers: SpriteSceneLayer[];
+    skipped: string[];
+}
+/**
+ * The layers of one view: per placement, its cel for the state in `states`
+ * (or, with `allStates`, one layer for idle and each state the placement
+ * offers in its `states` list), placed
+ * by its guide's origin, with a 3D depth per pixel. `depth: "parts"` (default)
+ * takes the depth of the guide's projected surface under each pixel (plus the
+ * placement's translation), else the mean depth of the part that owns it, else
+ * the nearest among its neighbours (outlines, details drawn beyond the
+ * projection), else the placement's centre. `depth: "placements"` gives every
+ * pixel the placement's centre depth. Placements without a compiled sprite are
+ * skipped and listed. The result can be composed many times, with different
+ * states, by `composeSpriteLayers` (for example in a browser).
+ */
+export declare function spriteSceneLayers(loaded: SpriteScene, view: string, sprites: Map<string, SpriteResult>, { states, depth, allStates }?: SpriteSceneOptions & {
+    allStates?: boolean;
+}): SpriteSceneLayers;
+/**
+ * Composes layers (from `spriteSceneLayers`) with a depth buffer: per
+ * placement the layer for its state in `states` (default "idle"), drawn
+ * "back" placements first, then by the order key and id, keeping the nearest
+ * pixel (later layers win ties). Host independent and cheap enough to run on
+ * every toggle in a browser.
+ */
+export declare function composeSpriteLayers(built: SpriteSceneLayers, { states, background }?: {
+    states?: Record<string, string>;
+    background?: string | null;
+}): SpriteSceneImage;
+/**
+ * Composes one view. `sprites` maps an asset ref to its compiled result;
+ * `states` maps a placement id to a state ("open"). Equivalent to
+ * `composeSpriteLayers(spriteSceneLayers(...))`: pixels sort by the 3D depth
+ * under them, so a non-convex object such as an open door sorts pixel by
+ * pixel; "back" placements are always behind; `depth: "placements"` is plain
+ * back-to-front drawing by bounds centre.
+ */
+export declare function composeSpriteScene(loaded: SpriteScene, view: string, sprites: Map<string, SpriteResult>, { states, background, depth }?: SpriteSceneOptions): SpriteSceneImage;
+/** Placement and part under a scene pixel, or null. */
+export declare function pickScene(composed: SpriteSceneImage, x: number, y: number): {
+    placement: string;
+    part: string | null;
+} | null;
+/**
+ * Footprint report: per placed sprite, overlap with the placement's own
+ * (unoccluded) 3D mask, the integer shift within ±3 px that maximises it, and
+ * draw-order disagreements with the 3D scene render.
+ */
+export declare function spriteSceneFootprint(loaded: SpriteScene, composed: SpriteSceneImage, { states }?: {
+    states?: Record<string, string>;
+}): SpriteSceneFootprint;
+export interface SpriteSceneFootprint {
+    view: string;
+    placements: {
+        placement: string;
+        asset: string;
+        state: string;
+        spritePixels: number;
+        modelPixels: number;
+        iou: number;
+        bestShift: number[];
+        bestIou: number;
+        misaligned: boolean;
+        index: number;
+    }[];
+    orderDisagreements: {
+        pair: string;
+        pixels: number;
+        share: number;
+    }[];
+    wrongOrder: {
+        pair: string;
+        pixels: number;
+        share: number;
+    }[];
+}