Spritedeck TypeScript SDK

Client SDK for fetching, building, and hydrating Spritedeck documents.

Live documents

Fetch a document from Spritedeck while developing so content changes are available without rebuilding your application:

import { createClient } from "spritedeck";

const client = createClient({
  projectId: "colorful-coffee-x9rh5e",
  publicToken: "pubtoken_...",
});

const document = await client.fetchDocument({
  documentId: "doc_ewj4vuye4sbegwb",
});

document is a hydrated SpritedeckDocument instance. It exposes document metadata plus hydrated tile sets, tiles, markers, and child objects:

import { Rectangle, Room } from "spritedeck";

console.log(document.id, document.name);

await document.loadAssets();

for (const child of document.children) {
  if (child instanceof Room) {
    console.log(child.name, child.children.length);
  }

  if (child instanceof Rectangle) {
    const renderData = child.getRenderData();
  }
}

fetchDocumentPreview and DocumentPreview remain available as deprecated aliases for compatibility.

Exported documents

Use buildDocument with an exported document snapshot for a deterministic, local-only production build. Pass the exported document object directly:

{
  "name": "Forest",
  "tileSets": {
    "terrain": "https://images.spritedeck.com/terrain.png"
  }
}

Map each tile-set ID to an imported local asset. buildDocument never falls back to the exported remote source when a mapping is missing.

import { buildDocument } from "spritedeck";
import documentJson from "./static/forest.spritedeck.json";
import terrainImage from "./static/terrain.png";

const document = buildDocument({
  documentJson,
  assets: {
    terrain: terrainImage,
  },
});

await document.loadAssets();

For dynamic naming or asset registries, pass a resolver instead of a map:

const document = buildDocument({
  documentJson,
  resolveAsset: ({ id, type, originalSource }) => {
    const source = localAssets[id];
    if (!source) throw new Error(`Missing local ${type} asset: ${id}`);
    return source;
  },
});

The resolver receives the stable tile-set ID and the original Spritedeck image source as metadata. It must return a browser-compatible image source string. Pass either assets or resolveAsset, not both.

Invalid exports throw SpritedeckExportError. Missing or invalid local asset mappings throw SpritedeckAssetResolutionError and expose the relevant assetId.

If your runtime does not expose globalThis.fetch, pass a compatible fetch implementation to createClient.

import { createClient, SpritedeckRequestError } from "spritedeck";

const client = createClient({
  projectId: "colorful-coffee-x9rh5e",
  publicToken: "pubtoken_...",
  fetch: customFetch,
});

try {
  await client.fetchDocumentPreview({ documentId: "doc_ewj4vuye4sbegwb" });
} catch (error) {
  if (error instanceof SpritedeckRequestError) {
    console.error(error.status, error.statusText);
  }
}

Types

The package exports the hydrated model classes, their raw API data interfaces, and client helper types from the root module.

Client

type FetchLike = typeof fetch;

interface CreateClientOptions {
  projectId: string;
  publicToken: string;
  apiBaseUrl?: string;
  fetch?: FetchLike;
}

interface FetchDocumentOptions {
  documentId: string;
}

interface SpritedeckClient {
  fetchDocument(options: FetchDocumentOptions): Promise<SpritedeckDocument>;

  /** @deprecated Use fetchDocument. */
  fetchDocumentPreview<TResponse = SpritedeckDocument>(
    options: FetchDocumentOptions,
  ): Promise<TResponse>;
}

SpritedeckRequestError is thrown for non-2xx responses and includes status and statusText.

Spritedeck Document

interface SpritedeckDocumentData {
  id?: string;
  name: string;
  tileSets?: Record<string, string>;
  tiles?: Record<string, TileData>;
  markers?: unknown[];
  children?: DocumentChildData[];
  userData?: Record<string, unknown>;
}

class SpritedeckDocument {
  readonly id?: string;
  readonly name: string;
  readonly tileSets: Record<string, TileSet>;
  readonly tiles: Record<string, Tile>;
  readonly markers: unknown[];
  readonly children: DocumentChild[];
  readonly userData: Record<string, unknown>;

  loadAssets(): Promise<void>;
}

userData is preserved without interpretation by the SDK and is the safe extension point for game-specific document metadata.

DocumentChild is a union of Room | Rectangle | ObjectPlacement | Path. The matching raw API union is DocumentChildData.

Child Models

interface RoomData {
  id: string;
  type: "Room";
  name?: string;
  x?: number;
  y?: number;
  w?: number;
  h?: number;
  children?: DocumentChildData[];
}

class Room {
  readonly id: string;
  readonly type: "Room";
  readonly name?: string;
  readonly x?: number;
  readonly y?: number;
  readonly width?: number;
  readonly height?: number;
  readonly children: DocumentChild[];
}

interface RectangleData {
  id: string;
  type: "Rectangle";
  x: number;
  y: number;
  w: number;
  h: number;
  tile?: string;
}

class Rectangle {
  readonly id: string;
  readonly type: "Rectangle";
  readonly x: number;
  readonly y: number;
  readonly width: number;
  readonly height: number;
  readonly tile?: Tile;

  getRenderData(): RenderData[];
}

interface ObjectPlacementData {
  id: string;
  type: "Object";
  objectType: string;
  variant?: string | null;
  x: number;
  y: number;
  events?: SpritedeckEvent[];
}

class ObjectPlacement {
  readonly id: string;
  readonly type: "Object";
  readonly objectTypeId: string;
  readonly variantId: string | null;
  readonly x: number;
  readonly y: number;
  readonly events: SpritedeckEvent[];
}

interface PathData {
  id: string;
  type: "Path";
}

class Path {
  readonly id: string;
  readonly type: "Path";
}

Tiles and Rendering

type PatternType = "NineSlice" | "Stamp" | "VerticalThree" | "HorizontalThree";
type SourceRect = [x: number, y: number, width: number, height: number];
type RenderRect = [x: number, y: number, width: number, height: number];

interface TileData {
  tileSet: string;
  patternType?: PatternType;
  drawLayer?: number;
  tags?: string[];
  frames?: TileFrameData[];
}

class Tile {
  readonly id: string;
  readonly tileSet?: TileSet;
  readonly patternType?: PatternType;
  readonly drawLayer?: number;
  readonly tags: string[];
  readonly frames: TileFrameData[];
}

class TileSet {
  readonly id: string;
  /** Resolved runtime image source. */
  readonly url: string;
  /** Original image source stored in the Spritedeck document. */
  readonly originalSource: string;
  image?: HTMLImageElement;

  loadImage(): Promise<HTMLImageElement>;
}

interface RenderData {
  image: HTMLImageElement;
  imageUrl: string;
  source: SourceRect;
  dests: RenderRect[];
}

The SDK also exports TileSourceData, TileFrameLayerData, TileAnimationFrameData, TileFrameData, SpritedeckEvent, SpritedeckEventTrigger, SpritedeckEventAction, HydrationContext, and createDocumentChild.

Development

npm install
npm run typecheck
npm run test
npm run build