@aethervtt/shard-sprite 0.0.1 → 0.2.0

package/dist/tilemap.js

@@ -8,20 +8,51 @@ import {
 } from "@aethervtt/shard-core";
 import { Visibility } from "@aethervtt/shard-render";
 import { Transform } from "@aethervtt/shard-transform";
+import {
+  flagsFromBase64,
+  layerChunks,
+  readChunkRows,
+  rowsCanName,
+  tilesFromBase64,
+  tilesToBase64,
+  toBase64
+} from "./tilemap-format.js";
 const TileFlags = { FlipX: 1, FlipY: 2, Rotate90: 4 };
 const TilemapDataSchema = defineSchema(
   "sprite/TilemapData",
   {
+    version: t.u8({
+      default: 1,
+      min: 1,
+      max: 2,
+      description: "2: tiles are named through the palette. 1 (old files): atlas region + 1."
+    }),
+    encoding: t.enum(["base64", "rows"], {
+      description: "rows: layers hold chunks of run-length rows (readable, one-line diffs). base64: tiles and flags as base64."
+    }),
+    chunkSize: t.u16({
+      default: 16,
+      min: 1,
+      max: 256,
+      description: "Tiles per chunk side in the rows encoding."
+    }),
+    palette: t.list(t.string, {
+      description: "Version 2: atlas region names; tile id N is palette entry N \u2212 1."
+    }),
     layers: t.list(
       t.struct({
         name: t.string({ description: 'Layer name, e.g. "ground".' }),
         width: t.u32({ min: 1, description: "Tiles across." }),
         height: t.u32({ min: 1, description: "Tiles down." }),
         tiles: t.string({
-          description: "Base64 of width \xD7 height little-endian u16s, row by row from the top: atlas region + 1 (0 is empty)."
+          description: "base64 encoding: width \xD7 height little-endian u16s, row by row from the top: palette index + 1 (version 1: atlas region + 1); 0 is empty."
         }),
         flags: t.string({
-          description: "Base64 of width \xD7 height bytes: 1 flip x, 2 flip y, 4 rotate 90\xB0. Empty: none."
+          description: "base64 encoding: width \xD7 height bytes: 1 flip x, 2 flip y, 4 rotate 90\xB0. Empty: none."
+        }),
+        chunks: t.json({
+          default: {},
+          description: 'rows encoding: "cx,cy" \u2192 rows from the top of the chunk, each space-separated runs of name[:fx+fy+r90][*count], "." empty. Chunks with no tiles are left out.'
         }),
         occludes: t.bool({
           description: "Filled cells block 2D light (shadowed PointLight2d and SpotLight2d)."
@@ -31,8 +62,10 @@ const TilemapDataSchema = defineSchema(
     ),
     animations: t.list(
       t.struct({
-        tile: t.u16({ min: 1, description: "The tile that animates, everywhere it appears." }),
-        frames: t.list(t.u16, { description: "Tiles it cycles through." }),
+        tile: t.json({
+          description: "The tile that animates, everywhere it appears: a palette name (v1: a tile id)."
+        }),
+        frames: t.list(t.json, { description: "Tiles it cycles through (names; v1: ids)." }),
         frameTime: t.f32({
           default: 0.2,
           min: 1e-3,
@@ -44,7 +77,7 @@ const TilemapDataSchema = defineSchema(
     )
   },
   {
-    description: "Tile layers for a Tilemap: indices into its atlas, per-tile flags, animated tiles."
+    description: "Tile layers for a Tilemap: tiles named through a palette of atlas regions, per-tile flags, animated tiles. Saved as readable rows or compact base64."
   }
 );
 const MAX_EDITS = 4096;
@@ -93,66 +126,243 @@ class TileLayer {
 class TilemapData {
   layers;
   animations;
+  /**
+   * 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;
+  /** How the map is saved: readable rows (the default) or compact base64. */
+  encoding = "rows";
+  /** Tiles per chunk side in the rows encoding. */
+  chunkSize = 16;
   /** Bumps when the layers are replaced (hot reload). */
   version = 0;
-  constructor(layers = [], animations = []) {
+  constructor(layers = [], animations = [], palette) {
     this.layers = layers;
     this.animations = animations;
+    this.palette = palette;
+  }
+  /**
+   * 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, height, layers = ["main"], palette) {
+    return new TilemapData(
+      layers.map((name) => new TileLayer(name, width, height)),
+      [],
+      palette ? [...palette] : void 0
+    );
+  }
+  /** The id of a palette name, adding it to the palette if it's new. Needs a palette. */
+  tileId(name) {
+    if (!this.palette) {
+      throw new ShardError("sprite/no-palette", "This tilemap names no tiles (version 1)", {
+        hint: "Save it once with its atlas (tilemapToJson(data, { atlas })) to give it a palette."
+      });
+    }
+    let i = this.palette.indexOf(name);
+    if (i === -1) {
+      i = this.palette.length;
+      this.palette.push(name);
+    }
+    return i + 1;
   }
-  /** An empty map of `layers` layers, width × height tiles each. */
-  static create(width, height, layers = ["main"]) {
-    return new TilemapData(layers.map((name) => new TileLayer(name, width, height)));
+  /** The name a tile id draws: through the palette, or the atlas for version 1 maps. */
+  tileName(id, atlas) {
+    if (id === 0) return void 0;
+    return this.palette ? this.palette[id - 1] : atlas?.names[id - 1];
   }
+  /** A map from its file's JSON (`$schema`, an editor's pointer, is ignored). */
   static fromJson(json) {
+    if (json && typeof json === "object" && "$schema" in json) {
+      const { $schema: _, ...body } = json;
+      json = body;
+    }
     const v = TilemapDataSchema.deserialize(json);
+    const named = v.version >= 2;
+    const palette = named ? [...v.palette] : void 0;
+    const index = new Map((palette ?? []).map((name, i) => [name, i]));
     const layers = v.layers.map((l, i) => {
       const n = l.width * l.height;
-      const tileBytes = fromBase64(l.tiles);
-      if (tileBytes.length !== n * 2) {
-        throw new ShardError(
-          "sprite/invalid-tilemap",
-          `Layer "${l.name}" has ${tileBytes.length / 2} tiles; ${l.width}\xD7${l.height} needs ${n}`,
-          { path: `/layers/${i}/tiles` }
-        );
-      }
-      const tiles = new Uint16Array(n);
-      const view = new DataView(tileBytes.buffer, tileBytes.byteOffset, tileBytes.byteLength);
-      for (let k = 0; k < n; k++) tiles[k] = view.getUint16(k * 2, true);
+      const path = `/layers/${i}`;
+      let tiles;
       let flags;
-      if (l.flags) {
-        flags = fromBase64(l.flags);
-        if (flags.length !== n) {
-          throw new ShardError(
-            "sprite/invalid-tilemap",
-            `Layer "${l.name}" has ${flags.length} flag bytes; ${l.width}\xD7${l.height} needs ${n}`,
-            { path: `/layers/${i}/flags` }
-          );
+      if (named && v.encoding === "rows") {
+        tiles = new Uint16Array(n);
+        flags = new Uint8Array(n);
+        const grid = { width: l.width, height: l.height, tiles, flags };
+        const chunks = l.chunks ?? {};
+        if (typeof chunks !== "object" || Array.isArray(chunks)) {
+          throw new ShardError("sprite/invalid-tilemap", 'Expected chunks by "cx,cy"', {
+            path: `${path}/chunks`
+          });
+        }
+        for (const [key, rows] of Object.entries(chunks)) {
+          const m = /^(\d+),(\d+)$/.exec(key);
+          const at = `${path}/chunks/${key}`;
+          if (!m) {
+            throw new ShardError("sprite/invalid-tilemap", `Bad chunk key "${key}"`, {
+              path: at,
+              hint: 'Chunk keys are "cx,cy": the chunk column and row from the top left.'
+            });
+          }
+          readChunkRows(grid, palette, index, Number(m[1]), Number(m[2]), v.chunkSize, rows, at);
+        }
+      } else {
+        tiles = tilesFromBase64(l.tiles, n, `${path}/tiles`, l.name);
+        flags = flagsFromBase64(l.flags, n, `${path}/flags`, l.name);
+        if (palette) {
+          for (let k = 0; k < n; k++) {
+            if (tiles[k] > palette.length) {
+              throw new ShardError(
+                "sprite/invalid-tilemap",
+                `Tile id ${tiles[k]} at (${k % l.width}, ${Math.floor(k / l.width)}) has no palette entry`,
+                { path: `${path}/tiles` }
+              );
+            }
+          }
         }
       }
       const layer = new TileLayer(l.name, l.width, l.height, tiles, flags);
       layer.occludes = l.occludes;
       return layer;
     });
-    return new TilemapData(layers, v.animations);
+    const idOf = (value, at) => {
+      if (!named) {
+        if (typeof value !== "number") {
+          throw new ShardError("sprite/invalid-tilemap", "Expected a tile id", { path: at });
+        }
+        return value;
+      }
+      if (typeof value !== "string") {
+        throw new ShardError("sprite/invalid-tilemap", "Expected a palette name", { path: at });
+      }
+      let p = index.get(value);
+      if (p === void 0) {
+        p = palette.length;
+        palette.push(value);
+        index.set(value, p);
+      }
+      return p + 1;
+    };
+    const animations = v.animations.map((a, i) => ({
+      tile: idOf(a.tile, `/animations/${i}/tile`),
+      frames: a.frames.map((f, k) => idOf(f, `/animations/${i}/frames/${k}`)),
+      frameTime: a.frameTime
+    }));
+    const data = new TilemapData(layers, animations, palette);
+    data.encoding = named ? v.encoding : "base64";
+    data.chunkSize = v.chunkSize;
+    return data;
   }
-  toJson() {
+  /**
+   * 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 = {}) {
+    const encoding = options.encoding ?? this.encoding;
+    let palette;
+    let remap;
+    if (this.palette) palette = this.palette;
+    else {
+      const atlas = options.atlas;
+      if (!atlas) {
+        throw new ShardError(
+          "sprite/tilemap-needs-atlas",
+          "Saving a version 1 tilemap needs its atlas",
+          {
+            hint: "Its tiles are atlas regions: pass the atlas so they can be named (the palette)."
+          }
+        );
+      }
+      palette = [];
+      const byRegion = /* @__PURE__ */ new Map();
+      const use = (id) => {
+        if (id === 0) return 0;
+        let p = byRegion.get(id);
+        if (p === void 0) {
+          const name2 = atlas.names[id - 1];
+          if (name2 === void 0) {
+            throw new ShardError(
+              "sprite/unknown-tile",
+              `Tile ${id} is past the atlas's ${atlas.names.length} regions`
+            );
+          }
+          p = palette.length;
+          palette.push(name2);
+          byRegion.set(id, p);
+        }
+        return p + 1;
+      };
+      for (const l of this.layers) for (let k = 0; k < l.tiles.length; k++) use(l.tiles[k]);
+      for (const a of this.animations) {
+        use(a.tile);
+        for (const f of a.frames) use(f);
+      }
+      remap = use;
+    }
+    if (encoding === "rows") {
+      for (const name2 of palette) {
+        if (!rowsCanName(name2)) {
+          throw new ShardError(
+            "sprite/unencodable-tile",
+            `Tile "${name2}" can't be written in rows`,
+            {
+              hint: 'Region names in rows have no spaces, ":", "*" or "+". Save with encoding base64.'
+            }
+          );
+        }
+      }
+    }
+    const idsOf = (l) => {
+      if (!remap) return l.tiles;
+      const out = new Uint16Array(l.tiles.length);
+      for (let k = 0; k < out.length; k++) out[k] = remap(l.tiles[k]);
+      return out;
+    };
+    const name = (id) => palette[(remap ? remap(id) : id) - 1];
     return {
+      version: 2,
+      encoding,
+      ...encoding === "rows" ? { chunkSize: this.chunkSize } : {},
+      palette: [...palette],
       layers: this.layers.map((l) => {
-        const bytes = new Uint8Array(l.tiles.length * 2);
-        const view = new DataView(bytes.buffer);
-        for (let k = 0; k < l.tiles.length; k++) view.setUint16(k * 2, l.tiles[k], true);
-        return {
-          name: l.name,
-          width: l.width,
-          height: l.height,
-          tiles: toBase64(bytes),
-          flags: l.flags.some((f) => f !== 0) ? toBase64(l.flags) : "",
-          ...l.occludes ? { occludes: true } : {}
+        const tiles = idsOf(l);
+        const head = { name: l.name, width: l.width, height: l.height };
+        const cells = encoding === "rows" ? {
+          chunks: layerChunks(
+            { width: l.width, height: l.height, tiles, flags: l.flags },
+            palette,
+            this.chunkSize
+          )
+        } : {
+          tiles: tilesToBase64(tiles),
+          flags: l.flags.some((f) => f !== 0) ? toBase64(l.flags) : ""
         };
+        return { ...head, ...cells, ...l.occludes ? { occludes: true } : {} };
       }),
-      animations: this.animations
+      animations: this.animations.map((a) => ({
+        tile: name(a.tile),
+        frames: a.frames.map(name),
+        frameTime: a.frameTime
+      }))
     };
   }
+  sameAs(other) {
+    if (this.encoding !== other.encoding || this.chunkSize !== other.chunkSize || this.layers.length !== other.layers.length || JSON.stringify(this.palette) !== JSON.stringify(other.palette) || JSON.stringify(this.animations) !== JSON.stringify(other.animations))
+      return false;
+    for (let i = 0; i < this.layers.length; i++) {
+      const a = this.layers[i];
+      const b = other.layers[i];
+      if (a.name !== b.name || a.width !== b.width || a.height !== b.height) return false;
+      if (a.occludes !== b.occludes) return false;
+      for (let k = 0; k < a.tiles.length; k++) {
+        if (a.tiles[k] !== b.tiles[k] || a.flags[k] !== b.flags[k]) return false;
+      }
+    }
+    return true;
+  }
   /** The largest tile index any layer uses (for validating against an atlas). */
   maxTile() {
     let max = 0;
@@ -160,24 +370,28 @@ class TilemapData {
       for (let k = 0; k < l.tiles.length; k++) max = Math.max(max, l.tiles[k]);
     return max;
   }
+  /** Takes another map's content (hot reload). Identical content (a save reloading) changes nothing. */
   copyFrom(other) {
+    if (this.sameAs(other)) return;
     this.layers = other.layers;
     this.animations = other.animations;
+    this.palette = other.palette;
+    this.encoding = other.encoding;
+    this.chunkSize = other.chunkSize;
     this.version++;
   }
 }
-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 tileNames(data, atlas) {
+  if (data.palette) return data.palette;
+  if (atlas) return atlas.names;
+  throw new ShardError("sprite/tilemap-needs-atlas", "This tilemap names no tiles (version 1)", {
+    hint: "Give a Tilemap using it an atlas, or save it once with one (tilemapToText(data, { atlas }))."
+  });
 }
-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 tilemapToText(data, options = {}) {
+  const json = data.toJson(options);
+  return `${JSON.stringify(options.schema === void 0 ? json : { $schema: options.schema, ...json }, null, 2)}
+`;
 }
 class TilemapDataStore extends AssetStore {
   constructor() {
@@ -216,14 +430,20 @@ const Tilemap = defineComponent(
     layer: t.i16({
       description: "Draw-order band, like Sprite.layer (tilemaps draw first in a band)."
     }),
-    lit: t.bool({
-      default: true,
-      description: "Lit by 2D lights under a Lighting2d camera."
+    lit: t.enum(["2d", "3d", "none"], {
+      description: "2d: lit by 2D lights under a Lighting2d camera. 3d: lit by 3D lights and shadows like a floor. none: drawn as the atlas is. On the ground (with a GroundLayer) there are no 2D lights: 2d and 3d both light it like a floor."
     })
   },
   {
-    description: "Tile layers drawn over the entity's XY plane: tile (x, y) covers [x, x+1] \xD7 [\u2212y\u22121, \u2212y] tile sizes, rows going down from the top.",
-    requires: [Transform, Visibility]
+    description: "Tile layers drawn over the entity's XY plane: tile (x, y) covers [x, x+1] \xD7 [\u2212y\u22121, \u2212y] tile sizes, rows going down from the top. With a GroundLayer (0059), they draw in the ground phase among the tabletop's bands (lay them flat with tilemapOnGround).",
+    requires: [Transform, Visibility],
+    version: 2,
+    // Version 1: lit was a flag for 2D lighting.
+    migrate: (_from, json) => {
+      const v = { ...json };
+      if (typeof v.lit === "boolean") v.lit = v.lit ? "2d" : "none";
+      return v;
+    }
   }
 );
 function layerOf(world, tilemap, layer) {
@@ -252,6 +472,36 @@ function setTile(world, tilemap, x, y, tile, options = {}) {
 function tileAt(world, tilemap, x, y, layer = 0) {
   return layerOf(world, tilemap, layer).get(x, y);
 }
+function unknownTiles(data, atlas) {
+  const out = [];
+  if (!data.palette) return out;
+  for (let i = 0; i < data.palette.length; i++) {
+    const name = data.palette[i];
+    if (atlas.region(name) !== -1) continue;
+    const id = i + 1;
+    let where;
+    for (let li = 0; li < data.layers.length && !where; li++) {
+      const l2 = data.layers[li];
+      const at = l2.tiles.indexOf(id);
+      if (at !== -1) where = { layer: li, x: at % l2.width, y: Math.floor(at / l2.width) };
+    }
+    if (!where) continue;
+    const l = data.layers[where.layer];
+    const cs = data.chunkSize;
+    const path = data.encoding === "rows" ? `/layers/${where.layer}/chunks/${Math.floor(where.x / cs)},${Math.floor(where.y / cs)}/${where.y % cs}` : `/layers/${where.layer}/tiles`;
+    out.push(
+      new ShardError(
+        "sprite/unknown-tile",
+        `Layer "${l.name}", cell (${where.x}, ${where.y}): tile "${name}" isn't a region of the atlas`,
+        {
+          path,
+          hint: "Rename it to a region the atlas has, or add the region to the atlas."
+        }
+      )
+    );
+  }
+  return out;
+}
 export {
   TileFlags,
   TileLayer,
@@ -263,5 +513,8 @@ export {
   TilemapDataStore,
   TilemapDatas,
   setTile,
-  tileAt
+  tileAt,
+  tileNames,
+  tilemapToText,
+  unknownTiles
 };

package/dist/validate.d.ts

@@ -0,0 +1,11 @@
+import type { ShardError, World } from '@aethervtt/shard-core';
+/**
+ * Checks each Tilemap's data against its atlas (0059): a palette name the atlas has no region
+ * for is `sprite/unknown-tile`, naming the layer, the cell and the name, with a JSON pointer to
+ * the cell's row in the data file. Scenes and prefabs say which atlas draws which data, so the
+ * check runs over their files. Loads what it checks.
+ */
+export declare function validateTilemaps(world: World, files: readonly unknown[]): Promise<{
+    source: string;
+    errors: ShardError[];
+}[]>;

package/dist/validate.js

@@ -0,0 +1,49 @@
+import { assetServer } from "@aethervtt/shard-assets";
+import { TextureAtlas } from "./atlas.js";
+import { TilemapData, unknownTiles } from "./tilemap.js";
+function tilemapsIn(json, out) {
+  if (Array.isArray(json)) {
+    for (const item of json) tilemapsIn(item, out);
+    return;
+  }
+  if (!json || typeof json !== "object") return;
+  for (const [key, value] of Object.entries(json)) {
+    if (key === "sprite/Tilemap" && value && typeof value === "object") {
+      const v = value;
+      if (v.data && v.atlas) out.push({ data: v.data, atlas: v.atlas });
+    } else tilemapsIn(value, out);
+  }
+}
+async function validateTilemaps(world, files) {
+  const server = assetServer(world);
+  const found = [];
+  for (const file of files) tilemapsIn(file, found);
+  const seen = /* @__PURE__ */ new Set();
+  const out = /* @__PURE__ */ new Map();
+  for (const pair of found) {
+    const data = server.entry(pair.data);
+    const atlas = server.entry(pair.atlas);
+    if (!data || !atlas || data.type !== "TilemapData" || atlas.type !== "TextureAtlas") continue;
+    const key = `${data.guid}|${atlas.guid}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    try {
+      await Promise.all([server.load(data.guid), server.load(atlas.guid)]);
+    } catch {
+      continue;
+    }
+    const d = server.item(data.guid);
+    const a = server.item(atlas.guid);
+    if (!(d instanceof TilemapData) || !(a instanceof TextureAtlas)) continue;
+    const errors = unknownTiles(d, a);
+    if (errors.length === 0) continue;
+    const source = data.source ?? data.path;
+    const list = out.get(source) ?? [];
+    for (const e of errors) if (!list.some((x) => x.message === e.message)) list.push(e);
+    out.set(source, list);
+  }
+  return [...out].map(([source, errors]) => ({ source, errors }));
+}
+export {
+  validateTilemaps
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aethervtt/shard-sprite",
-  "version": "0.0.1",
+  "version": "0.2.0",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,
@@ -16,13 +16,13 @@
     "README.md"
   ],
   "dependencies": {
-    "@aethervtt/shard-assets": "0.0.1",
-    "@aethervtt/shard-core": "0.0.1",
-    "@aethervtt/shard-gpu": "0.0.1",
-    "@aethervtt/shard-render": "0.0.1",
-    "@aethervtt/shard-runtime": "0.0.1",
-    "@aethervtt/shard-texture": "0.0.1",
-    "@aethervtt/shard-transform": "0.0.1"
+    "@aethervtt/shard-assets": "0.2.0",
+    "@aethervtt/shard-core": "0.2.0",
+    "@aethervtt/shard-gpu": "0.2.0",
+    "@aethervtt/shard-render": "0.2.0",
+    "@aethervtt/shard-runtime": "0.2.0",
+    "@aethervtt/shard-texture": "0.2.0",
+    "@aethervtt/shard-transform": "0.2.0"
   },
   "repository": {
     "type": "git",
@@ -34,6 +34,6 @@
     "provenance": true
   },
   "shard": {
-    "buildSha": "d6c5c6aef4675575c878b02cf2c8f738b4190229"
+    "buildSha": "32c22a3944ed23f5d1baa90bf7cc9fae724f5fd8"
   }
 }