@aethervtt/shard-sprite 0.0.1 → 0.1.0

package/dist/shaders.js

@@ -113,8 +113,8 @@ struct SpriteRecord {
   _pad1: u32,
 }
 
-@group(1) @binding(0) var<storage, read> sprites: array<SpriteRecord>;
-@group(1) @binding(1) var<storage, read> order: array<u32>;
+@data @group(1) @binding(0) var<storage, read> sprites: array<SpriteRecord>;
+@data @group(1) @binding(1) var<storage, read> order: array<u32>;
 
 @vertex fn vs(@builtin(vertex_index) v: u32, @builtin(instance_index) i: u32) -> SpriteOutput {
   let s = sprites[order[i]];
@@ -189,10 +189,10 @@ struct TilemapParams {
   chunks: vec4u,
 }
 
-@group(1) @binding(0) var<storage, read> tiles: array<u32>;
-@group(1) @binding(1) var<storage, read> visible_chunks: array<u32>;
-@group(1) @binding(2) var<storage, read> regions: array<vec4f>;
-@group(1) @binding(3) var<storage, read> remap: array<u32>;
+@data @group(1) @binding(0) var<storage, read> tiles: array<u32>;
+@data @group(1) @binding(1) var<storage, read> visible_chunks: array<u32>;
+@data @group(1) @binding(2) var<storage, read> regions: array<vec4f>;
+@data @group(1) @binding(3) var<storage, read> remap: array<u32>;
 @group(1) @binding(4) var<uniform> map: TilemapParams;
 
 /**
@@ -217,6 +217,11 @@ struct TilemapParams {
     return out;
   }
   let tile = remap[min(raw, arrayLength(&remap) - 1u)];
+  // A palette name the atlas lacks resolves to 0: nothing to draw.
+  if (tile == 0u) {
+    out.clip = vec4f(0.0, 0.0, 0.0, 0.0);
+    return out;
+  }
   let flags = value >> 16u;
   let c = corner(v);
   // Tile (x, y) covers [x, x + 1] \xD7 [-y - 1, -y] in tile units.

package/dist/tilemap-format.d.ts

@@ -0,0 +1,39 @@
+/** Tile flag bits (shared with the renderer). */
+export declare const TILE_FLAG_NAMES: {
+    readonly fx: 1;
+    readonly fy: 2;
+    readonly r90: 4;
+};
+export type TileEncoding = 'rows' | 'base64';
+/** What a layer's cells are in memory: tile ids (palette index + 1, 0 empty) and flag bits. */
+export interface CellGrid {
+    width: number;
+    height: number;
+    tiles: Uint16Array;
+    flags: Uint8Array;
+}
+/** Whether a palette name can be written in rows (no spaces or the run syntax's characters). */
+export declare function rowsCanName(name: string): boolean;
+/** The rows of one chunk: `chunkSize` cells a row at most, rows from the top. Undefined if empty. */
+export declare function chunkRows(grid: CellGrid, palette: readonly string[], cx: number, cy: number, chunkSize: number): string[] | undefined;
+/**
+ * The cells of a w × h rectangle as rows, in the rows syntax (`tilemap.read` with a rect), and
+ * whether any cell is filled. The rectangle must lie inside the grid.
+ */
+export declare function rectRows(grid: CellGrid, palette: readonly string[], x0: number, y0: number, w: number, h: number): {
+    rows: string[];
+    any: boolean;
+};
+/**
+ * Reads one chunk's rows into the grid. Unknown names are added to the palette (the caller
+ * checks them against the atlas); `path` is the chunk's JSON pointer.
+ */
+export declare function readChunkRows(grid: CellGrid, palette: string[], index: Map<string, number>, cx: number, cy: number, chunkSize: number, rows: unknown, path: string): void;
+/** All non-empty chunks of a layer as rows, keyed "cx,cy" in row-major order. */
+export declare function layerChunks(grid: CellGrid, palette: readonly string[], chunkSize: number): Record<string, string[]>;
+export declare function fromBase64(s: string): Uint8Array;
+export declare function toBase64(bytes: Uint8Array): string;
+/** A layer's tile ids as base64 of little-endian u16s. */
+export declare function tilesToBase64(tiles: Uint16Array): string;
+export declare function tilesFromBase64(s: string, n: number, path: string, name: string): Uint16Array;
+export declare function flagsFromBase64(s: string, n: number, path: string, name: string): Uint8Array;

package/dist/tilemap-format.js

@@ -0,0 +1,177 @@
+import { ShardError } from "@aethervtt/shard-core";
+const TILE_FLAG_NAMES = { fx: 1, fy: 2, r90: 4 };
+function invalid(message, path, hint) {
+  return new ShardError("sprite/invalid-tilemap", message, {
+    path,
+    hint: hint ?? 'Rows are space-separated runs of name[:flags][*count]; flags are fx, fy and r90 joined by +; "." is an empty cell.'
+  });
+}
+function rowsCanName(name) {
+  return name.length > 0 && name !== "." && !/[\s:*+]/.test(name);
+}
+function flagText(flags) {
+  const parts = [];
+  if (flags & 1) parts.push("fx");
+  if (flags & 2) parts.push("fy");
+  if (flags & 4) parts.push("r90");
+  return parts.join("+");
+}
+function chunkRows(grid, palette, cx, cy, chunkSize) {
+  const x0 = cx * chunkSize;
+  const y0 = cy * chunkSize;
+  const { rows, any } = rectRows(
+    grid,
+    palette,
+    x0,
+    y0,
+    Math.min(chunkSize, grid.width - x0),
+    Math.min(chunkSize, grid.height - y0)
+  );
+  return any ? rows : void 0;
+}
+function rectRows(grid, palette, x0, y0, w, h) {
+  let any = false;
+  const rows = [];
+  for (let ly = 0; ly < h; ly++) {
+    const runs = [];
+    let token = "";
+    let count = 0;
+    for (let lx = 0; lx < w; lx++) {
+      const i = (y0 + ly) * grid.width + x0 + lx;
+      const id = grid.tiles[i];
+      let t;
+      if (id === 0) t = ".";
+      else {
+        any = true;
+        const name = palette[id - 1];
+        if (name === void 0) throw invalid(`Tile id ${id} has no palette entry`, `/palette`);
+        const f = grid.flags[i];
+        t = f ? `${name}:${flagText(f)}` : name;
+      }
+      if (t === token) count++;
+      else {
+        if (count > 0) runs.push(count > 1 ? `${token}*${count}` : token);
+        token = t;
+        count = 1;
+      }
+    }
+    if (count > 0) runs.push(count > 1 ? `${token}*${count}` : token);
+    rows.push(runs.join(" "));
+  }
+  return { rows, any };
+}
+function readChunkRows(grid, palette, index, cx, cy, chunkSize, rows, path) {
+  if (!Array.isArray(rows)) throw invalid("Expected a list of rows", path);
+  const x0 = cx * chunkSize;
+  const y0 = cy * chunkSize;
+  const w = Math.min(chunkSize, grid.width - x0);
+  const h = Math.min(chunkSize, grid.height - y0);
+  if (w <= 0 || h <= 0) throw invalid(`Chunk ${cx},${cy} is outside the layer`, path);
+  if (rows.length > h) throw invalid(`Chunk has ${rows.length} rows; it can hold ${h}`, path);
+  for (let ly = 0; ly < rows.length; ly++) {
+    const row = rows[ly];
+    const at = `${path}/${ly}`;
+    if (typeof row !== "string") throw invalid("Expected a row string", at);
+    let lx = 0;
+    const runs = row.trim() === "" ? [] : row.trim().split(/\s+/);
+    for (const run of runs) {
+      const star = run.lastIndexOf("*");
+      const body = star === -1 ? run : run.slice(0, star);
+      const count = star === -1 ? 1 : Number(run.slice(star + 1));
+      if (!Number.isInteger(count) || count < 1) {
+        throw invalid(`Bad run count in "${run}" (column ${lx + 1})`, at);
+      }
+      let id = 0;
+      let flags = 0;
+      if (body !== ".") {
+        const colon = body.indexOf(":");
+        const name = colon === -1 ? body : body.slice(0, colon);
+        if (!rowsCanName(name)) throw invalid(`Bad tile name in "${run}" (column ${lx + 1})`, at);
+        if (colon !== -1) {
+          for (const f of body.slice(colon + 1).split("+")) {
+            const bit = TILE_FLAG_NAMES[f];
+            if (!bit) throw invalid(`Unknown flag "${f}" in "${run}" (column ${lx + 1})`, at);
+            flags |= bit;
+          }
+        }
+        let p = index.get(name);
+        if (p === void 0) {
+          p = palette.length;
+          palette.push(name);
+          index.set(name, p);
+        }
+        id = p + 1;
+      }
+      if (lx + count > w) throw invalid(`Row has more than ${w} cells`, at);
+      for (let k = 0; k < count; k++) {
+        const i = (y0 + ly) * grid.width + x0 + lx + k;
+        grid.tiles[i] = id;
+        grid.flags[i] = flags;
+      }
+      lx += count;
+    }
+    if (lx !== 0 && lx !== w) throw invalid(`Row has ${lx} cells; it needs ${w}`, at);
+  }
+}
+function layerChunks(grid, palette, chunkSize) {
+  const out = {};
+  const cols = Math.ceil(grid.width / chunkSize);
+  const rowsOfChunks = Math.ceil(grid.height / chunkSize);
+  for (let cy = 0; cy < rowsOfChunks; cy++) {
+    for (let cx = 0; cx < cols; cx++) {
+      const rows = chunkRows(grid, palette, cx, cy, chunkSize);
+      if (rows) out[`${cx},${cy}`] = rows;
+    }
+  }
+  return out;
+}
+function fromBase64(s) {
+  const bin = atob(s);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+function toBase64(bytes) {
+  let s = "";
+  for (let i = 0; i < bytes.length; i += 32768) {
+    s += String.fromCharCode(...bytes.subarray(i, i + 32768));
+  }
+  return btoa(s);
+}
+function tilesToBase64(tiles) {
+  const bytes = new Uint8Array(tiles.length * 2);
+  const view = new DataView(bytes.buffer);
+  for (let k = 0; k < tiles.length; k++) view.setUint16(k * 2, tiles[k], true);
+  return toBase64(bytes);
+}
+function tilesFromBase64(s, n, path, name) {
+  const bytes = fromBase64(s);
+  if (bytes.length !== n * 2) {
+    throw invalid(`Layer "${name}" has ${bytes.length / 2} tiles; it needs ${n}`, path);
+  }
+  const tiles = new Uint16Array(n);
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  for (let k = 0; k < n; k++) tiles[k] = view.getUint16(k * 2, true);
+  return tiles;
+}
+function flagsFromBase64(s, n, path, name) {
+  if (!s) return new Uint8Array(n);
+  const flags = fromBase64(s);
+  if (flags.length !== n) {
+    throw invalid(`Layer "${name}" has ${flags.length} flag bytes; it needs ${n}`, path);
+  }
+  return flags;
+}
+export {
+  TILE_FLAG_NAMES,
+  chunkRows,
+  flagsFromBase64,
+  fromBase64,
+  layerChunks,
+  readChunkRows,
+  rectRows,
+  rowsCanName,
+  tilesFromBase64,
+  tilesToBase64,
+  toBase64
+};

package/dist/tilemap.d.ts

@@ -1,5 +1,6 @@
 import { AssetStore } from '@aethervtt/shard-assets';
-import { type AssetRef, type Entity, type World } from '@aethervtt/shard-core';
+import { type AssetRef, type Entity, ShardError, type World } from '@aethervtt/shard-core';
+import { type TileEncoding } from './tilemap-format.js';
 /** Tile flag bits. */
 export declare const TileFlags: {
     readonly FlipX: 1;
@@ -7,17 +8,22 @@ export declare const TileFlags: {
     readonly Rotate90: 4;
 };
 export declare const TilemapDataSchema: import("@aethervtt/shard-core").ComponentDef<{
+    readonly version: import("@aethervtt/shard-core").FieldType<number, "u8">;
+    readonly encoding: import("@aethervtt/shard-core").FieldType<"base64" | "rows", "u8">;
+    readonly chunkSize: import("@aethervtt/shard-core").FieldType<number, "u16">;
+    readonly palette: import("@aethervtt/shard-core").FieldType<string[], "object">;
     readonly layers: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
         name: import("@aethervtt/shard-core").FieldType<string, "object">;
         width: import("@aethervtt/shard-core").FieldType<number, "u32">;
         height: import("@aethervtt/shard-core").FieldType<number, "u32">;
         tiles: import("@aethervtt/shard-core").FieldType<string, "object">;
         flags: import("@aethervtt/shard-core").FieldType<string, "object">;
+        chunks: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").JsonValue, "object">;
         occludes: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
     }>[], "object">;
     readonly animations: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
-        tile: import("@aethervtt/shard-core").FieldType<number, "u16">;
-        frames: import("@aethervtt/shard-core").FieldType<number[], "object">;
+        tile: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").JsonValue, "object">;
+        frames: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").JsonValue[], "object">;
         frameTime: import("@aethervtt/shard-core").FieldType<number, "f32">;
     }>[], "object">;
 }>;
@@ -45,31 +51,88 @@ export declare class TilemapData {
         frames: number[];
         frameTime: number;
     }[];
+    /**
+     * Atlas region names: tile id N draws the region named `palette[N - 1]` (0059). Undefined for
+     * maps made before palettes, whose ids are atlas regions + 1.
+     */
+    palette: string[] | undefined;
+    /** How the map is saved: readable rows (the default) or compact base64. */
+    encoding: TileEncoding;
+    /** Tiles per chunk side in the rows encoding. */
+    chunkSize: number;
     /** Bumps when the layers are replaced (hot reload). */
     version: number;
-    constructor(layers?: TileLayer[], animations?: TilemapData['animations']);
-    /** An empty map of `layers` layers, width × height tiles each. */
-    static create(width: number, height: number, layers?: string[]): TilemapData;
+    constructor(layers?: TileLayer[], animations?: TilemapData['animations'], palette?: string[]);
+    /**
+     * An empty map of `layers` layers, width × height tiles each. With a palette, tile ids name its
+     * entries; without, they're atlas regions + 1.
+     */
+    static create(width: number, height: number, layers?: string[], palette?: string[]): TilemapData;
+    /** The id of a palette name, adding it to the palette if it's new. Needs a palette. */
+    tileId(name: string): number;
+    /** The name a tile id draws: through the palette, or the atlas for version 1 maps. */
+    tileName(id: number, atlas?: {
+        names: readonly string[];
+    }): string | undefined;
+    /** A map from its file's JSON (`$schema`, an editor's pointer, is ignored). */
     static fromJson(json: unknown): TilemapData;
-    toJson(): {
-        layers: {
+    /**
+     * The map as version 2 JSON, in its encoding (or `options.encoding`). A version 1 map needs its
+     * atlas to name its tiles; its palette lists them in first use order. A map with a palette keeps
+     * it in order, so an edit that uses a known tile changes one row.
+     */
+    toJson(options?: {
+        encoding?: TileEncoding;
+        atlas?: {
+            names: readonly string[];
+        };
+    }): {
+        version: number;
+        encoding: TileEncoding;
+        chunkSize?: number | undefined;
+        palette: string[];
+        layers: ({
             name: string;
             width: number;
             height: number;
+            chunks: Record<string, string[]>;
+            tiles?: undefined;
+            flags?: undefined;
+            occludes?: boolean | undefined;
+        } | {
+            name: string;
+            width: number;
+            height: number;
+            chunks?: undefined;
             tiles: string;
             flags: string;
             occludes?: boolean | undefined;
-        }[];
+        })[];
         animations: {
-            tile: number;
-            frames: number[];
+            tile: string;
+            frames: string[];
             frameTime: number;
         }[];
     };
+    private sameAs;
     /** The largest tile index any layer uses (for validating against an atlas). */
     maxTile(): number;
+    /** Takes another map's content (hot reload). Identical content (a save reloading) changes nothing. */
     copyFrom(other: TilemapData): void;
 }
+/** The palette itself when the map has one; else the atlas's names (version 1 ids are regions + 1). */
+export declare function tileNames(data: TilemapData, atlas?: {
+    names: readonly string[];
+}): readonly string[];
+/** A tilemap file's text: its JSON, two-space indented, a newline at the end. */
+export declare function tilemapToText(data: TilemapData, options?: {
+    encoding?: TileEncoding;
+    atlas?: {
+        names: readonly string[];
+    };
+    /** The file's `$schema`, written first. */
+    schema?: string;
+}): string;
 export declare class TilemapDataStore extends AssetStore<TilemapData, 'TilemapData'> {
     constructor();
 }
@@ -83,7 +146,7 @@ export declare const Tilemap: import("@aethervtt/shard-core").ComponentDef<{
     readonly tileSize: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
     readonly chunkSize: import("@aethervtt/shard-core").FieldType<number, "u16">;
     readonly layer: import("@aethervtt/shard-core").FieldType<number, "i16">;
-    readonly lit: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly lit: import("@aethervtt/shard-core").FieldType<"2d" | "3d" | "none", "u8">;
 }>;
 /** Sets a tile (atlas region + 1, 0 to clear) and its flags. Only its chunk re-uploads. */
 export declare function setTile(world: World, tilemap: Entity, x: number, y: number, tile: number, options?: {
@@ -92,3 +155,11 @@ export declare function setTile(world: World, tilemap: Entity, x: number, y: num
 }): void;
 /** The tile at (x, y): atlas region + 1, or 0 for empty or outside the map. */
 export declare function tileAt(world: World, tilemap: Entity, x: number, y: number, layer?: number | string): number;
+/**
+ * Palette names the atlas has no region for (0059), each as `sprite/unknown-tile` naming the
+ * name, the first layer and cell that use it, and a JSON pointer to where that cell is saved: its
+ * row in the rows encoding, or the layer's tiles in base64. Version 1 maps name no tiles: none.
+ */
+export declare function unknownTiles(data: TilemapData, atlas: {
+    region(name: string): number;
+}): ShardError[];