@aethervtt/shard-sprite 0.0.1

package/dist/tilemap.js

@@ -0,0 +1,267 @@
+import { AssetStore, defineAssetType, defineDataAsset } from "@aethervtt/shard-assets";
+import {
+  defineComponent,
+  defineResource,
+  defineSchema,
+  ShardError,
+  t
+} from "@aethervtt/shard-core";
+import { Visibility } from "@aethervtt/shard-render";
+import { Transform } from "@aethervtt/shard-transform";
+const TileFlags = { FlipX: 1, FlipY: 2, Rotate90: 4 };
+const TilemapDataSchema = defineSchema(
+  "sprite/TilemapData",
+  {
+    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)."
+        }),
+        flags: t.string({
+          description: "Base64 of width \xD7 height bytes: 1 flip x, 2 flip y, 4 rotate 90\xB0. Empty: none."
+        }),
+        occludes: t.bool({
+          description: "Filled cells block 2D light (shadowed PointLight2d and SpotLight2d)."
+        })
+      }),
+      { description: "Layers, drawn in order." }
+    ),
+    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." }),
+        frameTime: t.f32({
+          default: 0.2,
+          min: 1e-3,
+          unit: "s",
+          description: "Seconds per frame."
+        })
+      }),
+      { description: "Animated tiles: water, torches, conveyor belts." }
+    )
+  },
+  {
+    description: "Tile layers for a Tilemap: indices into its atlas, per-tile flags, animated tiles."
+  }
+);
+const MAX_EDITS = 4096;
+class TileLayer {
+  name;
+  width;
+  height;
+  tiles;
+  flags;
+  /** Tile indices (y · width + x) edited since `editBase`: renderers upload their chunks. */
+  edits = [];
+  /** Bumps when the edit log overflows: renderers re-upload everything. */
+  editBase = 0;
+  /** Filled cells block 2D light. */
+  occludes = false;
+  constructor(name, width, height, tiles, flags) {
+    this.name = name;
+    this.width = width;
+    this.height = height;
+    this.tiles = tiles ?? new Uint16Array(width * height);
+    this.flags = flags ?? new Uint8Array(width * height);
+  }
+  get(x, y) {
+    if (x < 0 || y < 0 || x >= this.width || y >= this.height) return 0;
+    return this.tiles[y * this.width + x];
+  }
+  set(x, y, tile, flags = 0) {
+    if (x < 0 || y < 0 || x >= this.width || y >= this.height) {
+      throw new ShardError(
+        "sprite/tile-out-of-range",
+        `Tile (${x}, ${y}) is outside the ${this.width}\xD7${this.height} layer "${this.name}"`
+      );
+    }
+    const i = y * this.width + x;
+    if (this.tiles[i] === tile && this.flags[i] === flags) return;
+    this.tiles[i] = tile;
+    this.flags[i] = flags;
+    if (this.edits.length >= MAX_EDITS) {
+      this.edits.length = 0;
+      this.editBase++;
+    } else {
+      this.edits.push(i);
+    }
+  }
+}
+class TilemapData {
+  layers;
+  animations;
+  /** Bumps when the layers are replaced (hot reload). */
+  version = 0;
+  constructor(layers = [], animations = []) {
+    this.layers = layers;
+    this.animations = animations;
+  }
+  /** 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)));
+  }
+  static fromJson(json) {
+    const v = TilemapDataSchema.deserialize(json);
+    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);
+      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` }
+          );
+        }
+      }
+      const layer = new TileLayer(l.name, l.width, l.height, tiles, flags);
+      layer.occludes = l.occludes;
+      return layer;
+    });
+    return new TilemapData(layers, v.animations);
+  }
+  toJson() {
+    return {
+      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 } : {}
+        };
+      }),
+      animations: this.animations
+    };
+  }
+  /** The largest tile index any layer uses (for validating against an atlas). */
+  maxTile() {
+    let max = 0;
+    for (const l of this.layers)
+      for (let k = 0; k < l.tiles.length; k++) max = Math.max(max, l.tiles[k]);
+    return max;
+  }
+  copyFrom(other) {
+    this.layers = other.layers;
+    this.animations = other.animations;
+    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 toBase64(bytes) {
+  let s = "";
+  for (let i = 0; i < bytes.length; i += 32768) {
+    s += String.fromCharCode(...bytes.subarray(i, i + 32768));
+  }
+  return btoa(s);
+}
+class TilemapDataStore extends AssetStore {
+  constructor() {
+    super("TilemapData");
+  }
+}
+const TilemapDatas = defineResource("sprite/TilemapDatas", {
+  description: "Loaded tilemap data by guid.",
+  init: () => new TilemapDataStore()
+});
+const TilemapDataAssetType = defineAssetType("TilemapData", {
+  store: TilemapDatas,
+  load: (artifact) => TilemapData.fromJson(artifact.json),
+  update: (existing, next) => existing.copyFrom(next)
+});
+const TilemapDataImporter = defineDataAsset("TilemapData", TilemapDataSchema, {
+  extension: "tilemap"
+});
+const Tilemap = defineComponent(
+  "sprite/Tilemap",
+  {
+    atlas: t.handle("TextureAtlas", { description: "Tile N draws region N \u2212 1." }),
+    data: t.handle("TilemapData", { description: "The tile layers." }),
+    tileSize: t.vec2({
+      default: [1, 1],
+      min: 0,
+      unit: "m",
+      description: "World size of one tile."
+    }),
+    chunkSize: t.u16({
+      default: 32,
+      min: 4,
+      max: 256,
+      description: "Tiles per chunk side: chunks are the unit of culling and re-upload."
+    }),
+    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."
+    })
+  },
+  {
+    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]
+  }
+);
+function layerOf(world, tilemap, layer) {
+  const value = world.get(tilemap, Tilemap);
+  if (!value) {
+    throw new ShardError("sprite/not-a-tilemap", `Entity ${tilemap} has no Tilemap`);
+  }
+  const data = world.resource(TilemapDatas).get(value.data);
+  if (!data) {
+    throw new ShardError("sprite/tilemap-not-loaded", `Tilemap ${tilemap} has no loaded data`, {
+      hint: "Wait for its TilemapData asset, or create one with TilemapData.create."
+    });
+  }
+  const l = typeof layer === "number" ? data.layers[layer] : data.layers.find((x) => x.name === layer);
+  if (!l) {
+    throw new ShardError(
+      "sprite/no-layer",
+      `Tilemap ${tilemap} has no layer ${JSON.stringify(layer)}`
+    );
+  }
+  return l;
+}
+function setTile(world, tilemap, x, y, tile, options = {}) {
+  layerOf(world, tilemap, options.layer ?? 0).set(x, y, tile, options.flags ?? 0);
+}
+function tileAt(world, tilemap, x, y, layer = 0) {
+  return layerOf(world, tilemap, layer).get(x, y);
+}
+export {
+  TileFlags,
+  TileLayer,
+  Tilemap,
+  TilemapData,
+  TilemapDataAssetType,
+  TilemapDataImporter,
+  TilemapDataSchema,
+  TilemapDataStore,
+  TilemapDatas,
+  setTile,
+  tileAt
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@aethervtt/shard-sprite",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "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"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aethervtt/shard.git",
+    "directory": "packages/sprite"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "shard": {
+    "buildSha": "d6c5c6aef4675575c878b02cf2c8f738b4190229"
+  }
+}