@ludic-labs/assembly 0.0.0-stage → 0.4.0

package/dist/pixel.d.ts

@@ -0,0 +1,268 @@
+/**
+ * Experimental pixel-art presentation for compiled assets (`pixel-profile/0.1`).
+ *
+ * Renders compiled meshes straight to a logical pixel grid with supersampling,
+ * then applies explicit pixel-art rules: material ramps derived in OKLCH with
+ * hue-shifted shadows, banded camera-relative light, coloured outlines, inner
+ * lines decided once per pair of parts, accents for declared features and tiny
+ * parts, sub-pixel face suppression and orphan cleanup. Surface patterns are
+ * evaluated in each asset's own frame, so they need no UVs and cover any mesh.
+ *
+ * The asset stays an ordinary three-dimensional definition; profiles, cameras
+ * and surfaces are presentation options. Pure and deterministic: no DOM, IO,
+ * randomness or mutation of inputs. The format is experimental and may change.
+ */
+import type { CompiledAsset, Diagnostic, MeshData, Vec3 } from "./types.js";
+export declare const PIXEL_PROFILE_FORMAT = "pixel-profile/0.1";
+export declare const PIXEL_IMAGE_FORMAT = "pixel-image/0.1";
+/** Upper bound on logical width or height. */
+export declare const PIXEL_MAX_DIMENSION = 2048;
+/** Upper bound on supersamples (width * height * samples^2) per render. */
+export declare const PIXEL_MAX_SUBSAMPLES = 16777216;
+export interface PixelRampStep {
+    /** OKLab lightness offset from the material colour. */
+    dL: number;
+    /** Degrees toward the cool (negative) or warm (positive) hue. */
+    hueShift: number;
+    /** Chroma multiplier. */
+    chroma: number;
+    /** Chroma floor, so near-gray materials still receive tinted shadows. */
+    minChroma: number;
+}
+export interface PixelProfile {
+    format: typeof PIXEL_PROFILE_FORMAT;
+    name: string;
+    coolHue: number;
+    warmHue: number;
+    /** Exactly five steps: outline, deep, shadow, mid (material colour), light. */
+    steps: readonly PixelRampStep[];
+    /** Key light in camera space (screen right, screen up, toward the viewer). */
+    light: {
+        right: number;
+        up: number;
+        back: number;
+    };
+    /** Added brightness proportional to the world-up normal component. */
+    topBias: number;
+    /** Descending n.L thresholds for light, mid and shadow; below the last is deep. */
+    bands: readonly [number, number, number];
+    /**
+     * "coloured": each part's own darkest ramp step; "dark": one shared line
+     * colour; "none". (A true selective outline that breaks lit edges is not
+     * implemented.)
+     */
+    outline: "coloured" | "dark" | "none";
+    /** Shared line colour for outline "dark". */
+    outlineColor: string;
+    /** Draw a line on the nearer part where one part is in front of another. */
+    innerLines: boolean;
+    /** Metres one part must be in front of another to count as in front. */
+    depthGap: number;
+    /** Share of boundary votes needed to decide that one part is in front. */
+    frontVotes: number;
+    /** Faces with less area than this per touched pixel are dropped. */
+    sliverThinness: number;
+    /** Parts with at most this many pixels are drawn as accents. */
+    accentArea: number;
+    /** Coverage weight that lets a declared feature win a contested pixel. */
+    featureWeight: number;
+    orphanCleanup: boolean;
+    /** Smallest pattern gap, in pixels, that is drawn rather than suppressed. */
+    patternMinPixels: number;
+    /** Fill tones: 4 (deep, shadow, mid, light) or 3 (deep merges into shadow). */
+    tones: 3 | 4;
+    /**
+     * Maximum distinct opaque colours, or null for no cap. The palette is
+     * derived from every input material and surface colour, not from visible
+     * pixels, so it is identical across views of the same scene.
+     */
+    paletteCap: number | null;
+}
+/**
+ * Built-in profiles, after a survey of itch.io environment packs (see
+ * docs/pixel-art.md). Experimental; none has owner visual acceptance.
+ */
+export declare const PIXEL_PROFILES: Readonly<Record<"scene" | "fantasy" | "arcade", PixelProfile>>;
+/** Profile, camera and density bundles for the built-in profiles. */
+export declare const PIXEL_PRESETS: Readonly<Record<"scene" | "fantasy" | "arcade", {
+    profile: PixelProfile;
+    camera: string;
+    pixelsPerMetre: number;
+}>>;
+export interface PixelCamera {
+    name: string;
+    /** Orthonormal world-space basis: screen right, screen up and toward the viewer. */
+    right: Vec3;
+    up: Vec3;
+    back: Vec3;
+}
+/** Orthographic camera looking from `yaw` (about +Y, from +Z toward +X) and `pitch` above the horizon. */
+export declare function pixelCamera(yawDegrees: number, pitchDegrees: number, name?: string): PixelCamera;
+/**
+ * Camera presets. The dimetric presets use a 30 degree pitch at a diagonal
+ * yaw, which projects the ground axes to exact 2:1 pixel slopes.
+ */
+export declare const PIXEL_CAMERAS: Readonly<Record<string, PixelCamera>>;
+export interface PixelInstance {
+    /** Unique instance ID, used for picking. */
+    id: string;
+    /** Source part name; declared features refer to it. */
+    part: string;
+    material: string;
+    /** World-space mesh to draw (rest or posed). */
+    mesh: MeshData;
+    /**
+     * Positions in the asset's own rest frame, aligned with `mesh.positions`, for
+     * surface patterns. Defaults to `mesh.positions`. Supplying rest positions
+     * keeps patterns attached through posing and scene placement.
+     */
+    restPositions?: readonly number[] | null;
+}
+export interface PixelPlacement {
+    id: string;
+    asset: CompiledAsset;
+    /** World position of the asset origin, metres. */
+    position: Vec3;
+    /** Rotation about +Y, degrees. */
+    yawDegrees?: number;
+    /** Tint for tintable materials, #rrggbb. */
+    tint?: string | null;
+}
+/**
+ * Rest-pose instances of a compiled asset (instances hidden in rest states are
+ * omitted). `tint` (#rrggbb) multiplies tintable materials, as in meshForAsset.
+ */
+export declare function pixelInstances(asset: CompiledAsset, tint?: string | null): PixelInstance[];
+/**
+ * Places compiled assets in one scene. Each placement rotates about +Y and
+ * translates its rest meshes; IDs become `<placement>/<instance>` and patterns
+ * stay in each asset's own frame.
+ */
+export declare function composePixelScene(placements: readonly PixelPlacement[]): PixelInstance[];
+export type PixelPattern = {
+    type: "stripes";
+    axis: "x" | "y" | "z";
+    period: number;
+    width: number;
+} | {
+    type: "checker";
+    period: number;
+} | {
+    type: "grid";
+    axes: readonly ("x" | "y" | "z")[];
+    period: number;
+    width: number;
+} | {
+    type: "bricks";
+    course: number;
+    length: number;
+    mortar: number;
+    axis: "x" | "z";
+};
+export interface PixelSurface {
+    /** Material name the pattern covers. */
+    material: string;
+    /**
+     * Scene placement ID the surface is limited to (instance IDs starting with
+     * `<scope>/`), or null for every instance using the material.
+     */
+    scope?: string | null;
+    pattern: PixelPattern;
+    /** Pattern colour, #rrggbb; shading bands still apply. */
+    color: string;
+}
+/**
+ * Whether a point in the asset's own frame lies on the drawn part of a
+ * pattern. `lineWidth` is the minimum line width in metres (0 for none). The
+ * same function can drive an ordinary 3D renderer as a solid texture.
+ */
+export declare function samplePixelPattern(p: PixelPattern, point: Vec3, lineWidth?: number): boolean;
+export interface PixelFrame {
+    /** World point placed at the canvas centre. */
+    center: Vec3;
+    width: number;
+    height: number;
+}
+export interface PixelArtOptions {
+    camera?: PixelCamera;
+    /** Fixed pixel density. Default 32. */
+    pixelsPerMetre?: number;
+    /** Empty pixels around fitted content. Default 4. Ignored with `frame`. */
+    margin?: number;
+    /** Fixed canvas around a world point instead of fitting the content. */
+    frame?: PixelFrame | null;
+    /** Supersamples per pixel axis, 1 to 4. Default 4. */
+    samples?: number;
+    profile?: PixelProfile;
+    /** Part names drawn as protected accents (handles, eyes, controls). */
+    features?: readonly string[];
+    surfaces?: readonly PixelSurface[];
+    /** Background #rrggbb, or null for transparent. Default null. */
+    background?: string | null;
+}
+export declare class PixelArtError extends Error {
+    readonly diagnostics: Diagnostic[];
+    constructor(diagnostics: Diagnostic[]);
+}
+/** Structural validation of render options. Errors only; render warnings are returned with the image. */
+export declare function validatePixelOptions(options: PixelArtOptions): Diagnostic[];
+/** Linear sRGB to OKLab (Ottosson 2020). */
+export declare function linearToOklab(rgb: Vec3): Vec3;
+/** OKLab to linear sRGB. */
+export declare function oklabToLinear(lab: Vec3): Vec3;
+/** Ramp step indices. */
+export declare const PIXEL_RAMP: Readonly<{
+    outline: 0;
+    deep: 1;
+    shadow: 2;
+    mid: 3;
+    light: 4;
+}>;
+/** Five-step hue-shifted ramp (#rrggbb) for a linear-sRGB colour. */
+export declare function pixelRamp(linearRgb: Vec3, profile?: PixelProfile): string[];
+export interface PixelImage {
+    format: typeof PIXEL_IMAGE_FORMAT;
+    width: number;
+    height: number;
+    pixelsPerMetre: number;
+    camera: string;
+    profile: string;
+    /** RGBA, row-major, top row first. Background pixels are transparent unless a background is set. */
+    rgba: Uint8Array;
+    /** Index into `instances` per pixel, or -1 for background. */
+    owners: Int32Array;
+    /** Ramp step per pixel (see PIXEL_RAMP), or -1 for background. */
+    roles: Int8Array;
+    /**
+     * Distance toward the camera (world units along `camera.back`) of the owner's
+     * nearest surface in each pixel, or NaN for background. Larger is nearer.
+     * Lets 2D layers drawn over the image be depth-composited.
+     */
+    depth: Float32Array;
+    instances: {
+        id: string;
+        part: string;
+        material: string;
+    }[];
+    /** Distinct opaque colours used, sorted. */
+    palette: string[];
+    stats: {
+        outline: number;
+        inner: number;
+        accent: number;
+        fill: number;
+        pattern: number;
+        orphansCleaned: number;
+        sliverFaces: number;
+        frontPairs: number;
+    };
+    /** Non-fatal conditions, for example patterns suppressed below the pixel grid. */
+    warnings: Diagnostic[];
+}
+/** Instance and part under a pixel, or null for background and out-of-range coordinates. */
+export declare function pickPixel(image: PixelImage, x: number, y: number): {
+    id: string;
+    part: string;
+} | null;
+/** Renders an asset or a composed scene to pixel art. Throws PixelArtError on invalid options or empty input. */
+export declare function renderPixelArt(source: CompiledAsset | readonly PixelInstance[], options?: PixelArtOptions): PixelImage;