@aethervtt/shard-sprite 0.0.1

package/dist/clip.d.ts

@@ -0,0 +1,73 @@
+import { AssetStore } from '@aethervtt/shard-assets';
+import { type AssetRef, type Entity } from '@aethervtt/shard-core';
+export declare const CLIP_LOOPS: readonly ['loop', 'once', 'ping-pong'];
+export declare const SpriteClipSchema: import("@aethervtt/shard-core").ComponentDef<{
+    readonly atlas: import("@aethervtt/shard-core").FieldType<AssetRef<"TextureAtlas"> | null, "object">;
+    readonly frames: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+        region: import("@aethervtt/shard-core").FieldType<string, "object">;
+        duration: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    }>[], "object">;
+    readonly loop: import("@aethervtt/shard-core").FieldType<"loop" | "once" | "ping-pong", "u8">;
+    readonly events: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+        frame: import("@aethervtt/shard-core").FieldType<number, "u32">;
+        name: import("@aethervtt/shard-core").FieldType<string, "object">;
+    }>[], "object">;
+}>;
+/** A frame animation over an atlas: regions, durations, loop mode, and named events. */
+export declare class SpriteClip {
+    atlas: AssetRef<'TextureAtlas'> | null;
+    regions: string[];
+    /** Frame start times (s), plus the total at the end. */
+    starts: Float64Array;
+    loop: (typeof CLIP_LOOPS)[number];
+    /** Event names by frame. */
+    events: Map<number, string[]>;
+    constructor(atlas: AssetRef<'TextureAtlas'> | null, frames: {
+        region: string;
+        duration: number;
+    }[], loop?: (typeof CLIP_LOOPS)[number], events?: {
+        frame: number;
+        name: string;
+    }[]);
+    get duration(): number;
+    /**
+     * The frame showing at `time` (seconds from the start). Ping-pong runs the frames forward, then
+     * back over the inner ones, so the ends don't show twice.
+     */
+    frameAt(time: number): number;
+    /** Whether a `once` clip has played to its end at `time`. */
+    ended(time: number): boolean;
+    private search;
+    copyFrom(other: SpriteClip): void;
+}
+export declare class SpriteClipStore extends AssetStore<SpriteClip, 'SpriteClip'> {
+    constructor();
+}
+export declare const SpriteClips: import("@aethervtt/shard-core").ResourceDef<SpriteClipStore>;
+export declare const SpriteClipAssetType: import("@aethervtt/shard-assets").AssetTypeDef<SpriteClip>;
+/** `*.clip.json`: a frame animation over an atlas's regions. */
+export declare const SpriteClipImporter: import("@aethervtt/shard-assets").ImporterDef;
+export declare const SpriteAnimation: import("@aethervtt/shard-core").ComponentDef<{
+    readonly clip: import("@aethervtt/shard-core").FieldType<AssetRef<"SpriteClip"> | null, "object">;
+    readonly playing: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly speed: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly time: import("@aethervtt/shard-core").FieldType<number, "f32">;
+}>;
+export interface SpriteAnimationEventValue {
+    entity: Entity;
+    /** The event's name from the clip. */
+    name: string;
+    frame: number;
+}
+export declare const SpriteAnimationEvent: import("@aethervtt/shard-core").EventDef<SpriteAnimationEventValue>;
+/**
+ * Advances every SpriteAnimation, points its Sprite at the current frame's region, and sends the
+ * events of frames it passes (all of them, even when a long step skips frames).
+ */
+export declare const animateSprites: import("@aethervtt/shard-core").SystemDef<{
+    q: import("@aethervtt/shard-core").Query;
+    warned: Set<string>;
+    lastFrames: Map<number, number>;
+}>;
+/** A clip's frames side by side, in order, each labeled with its index. */
+export declare const spriteClipPreview: import("@aethervtt/shard-assets").AssetPreview;

package/dist/clip.js

@@ -0,0 +1,278 @@
+import {
+  AssetStore,
+  assetServer,
+  defineAssetPreview,
+  defineAssetType,
+  defineDataAsset
+} from "@aethervtt/shard-assets";
+import {
+  defineComponent,
+  defineEvent,
+  defineResource,
+  defineSchema,
+  defineSystem,
+  ShardError,
+  t
+} from "@aethervtt/shard-core";
+import { LogResource, Time } from "@aethervtt/shard-runtime";
+import { readKtx2 } from "@aethervtt/shard-texture";
+import { TextureAtlas, TextureAtlases } from "./atlas.js";
+import { drawLabel, fitImage } from "./preview.js";
+import { Sprite } from "./sprite.js";
+const CLIP_LOOPS = ["loop", "once", "ping-pong"];
+const SpriteClipSchema = defineSchema(
+  "sprite/SpriteClip",
+  {
+    atlas: t.handle("TextureAtlas", { description: "The atlas the frames come from." }),
+    frames: t.list(
+      t.struct({
+        region: t.string({ description: "Atlas region name." }),
+        duration: t.f32({ default: 0.1, min: 1e-3, unit: "s", description: "How long it shows." })
+      }),
+      { description: "Frames in order." }
+    ),
+    loop: t.enum(CLIP_LOOPS, {
+      description: "loop: from the start again; once: stop on the last frame; ping-pong: back and forth."
+    }),
+    events: t.list(
+      t.struct({
+        frame: t.u32({ description: "Frame index that sends it, when it starts showing." }),
+        name: t.string({ description: 'Event name, e.g. "footstep".' })
+      }),
+      { description: "Named events sent as SpriteAnimationEvent." }
+    )
+  },
+  { description: "A frame animation: atlas regions with durations, a loop mode, and events." }
+);
+class SpriteClip {
+  atlas;
+  regions;
+  /** Frame start times (s), plus the total at the end. */
+  starts;
+  loop;
+  /** Event names by frame. */
+  events;
+  constructor(atlas, frames, loop = "loop", events = []) {
+    this.atlas = atlas;
+    this.regions = frames.map((f) => f.region);
+    this.starts = new Float64Array(frames.length + 1);
+    for (let i = 0; i < frames.length; i++)
+      this.starts[i + 1] = this.starts[i] + frames[i].duration;
+    this.loop = loop;
+    this.events = /* @__PURE__ */ new Map();
+    for (const e of events) {
+      const list = this.events.get(e.frame) ?? [];
+      list.push(e.name);
+      this.events.set(e.frame, list);
+    }
+  }
+  get duration() {
+    return this.starts[this.regions.length];
+  }
+  /**
+   * The frame showing at `time` (seconds from the start). Ping-pong runs the frames forward, then
+   * back over the inner ones, so the ends don't show twice.
+   */
+  frameAt(time) {
+    const n = this.regions.length;
+    if (n === 0) return -1;
+    const total = this.duration;
+    if (this.loop === "once") return time >= total ? n - 1 : this.search(Math.max(0, time));
+    if (this.loop === "loop" || n < 3) return this.search(mod(time, total));
+    const back = this.starts[n - 1] - this.starts[1];
+    const t2 = mod(time, total + back);
+    if (t2 < total) return this.search(t2);
+    let r = t2 - total;
+    for (let f = n - 2; f >= 1; f--) {
+      const d = this.starts[f + 1] - this.starts[f];
+      if (r < d) return f;
+      r -= d;
+    }
+    return 1;
+  }
+  /** Whether a `once` clip has played to its end at `time`. */
+  ended(time) {
+    return this.loop === "once" && time >= this.duration;
+  }
+  search(t2) {
+    const n = this.regions.length;
+    let lo = 0;
+    let hi = n - 1;
+    while (lo < hi) {
+      const mid = lo + hi + 1 >> 1;
+      if (this.starts[mid] <= t2) lo = mid;
+      else hi = mid - 1;
+    }
+    return lo;
+  }
+  copyFrom(other) {
+    this.atlas = other.atlas;
+    this.regions = other.regions;
+    this.starts = other.starts;
+    this.loop = other.loop;
+    this.events = other.events;
+  }
+}
+const mod = (a, b) => b > 0 ? (a % b + b) % b : 0;
+class SpriteClipStore extends AssetStore {
+  constructor() {
+    super("SpriteClip");
+  }
+}
+const SpriteClips = defineResource("sprite/SpriteClips", {
+  description: "Loaded sprite animation clips by guid.",
+  init: () => new SpriteClipStore()
+});
+const SpriteClipAssetType = defineAssetType("SpriteClip", {
+  store: SpriteClips,
+  load: (artifact, ctx) => {
+    const v = SpriteClipSchema.deserialize(artifact.json);
+    const atlas = v.atlas?.path ? ctx.resolve(v.atlas.path) ?? v.atlas : v.atlas;
+    return new SpriteClip(atlas ?? null, v.frames, v.loop, v.events);
+  },
+  update: (existing, next) => existing.copyFrom(next)
+});
+const SpriteClipImporter = defineDataAsset("SpriteClip", SpriteClipSchema, {
+  extension: "clip"
+});
+const SpriteAnimation = defineComponent(
+  "sprite/SpriteAnimation",
+  {
+    clip: t.handle("SpriteClip", { description: "The frame animation to play." }),
+    playing: t.bool({
+      default: true,
+      description: "Advances each frame. A once clip clears it at its end."
+    }),
+    speed: t.f32({
+      default: 1,
+      description: "Playback rate: 2 is twice as fast, negative plays backward."
+    }),
+    time: t.f32({ unit: "s", description: "Position in the clip." })
+  },
+  {
+    description: "Plays a SpriteClip on this entity's Sprite: sets its atlas and region each frame.",
+    requires: [Sprite]
+  }
+);
+const SpriteAnimationEvent = defineEvent(
+  "sprite/SpriteAnimationEvent",
+  { description: "A clip frame with an event started showing: { entity, name, frame }." }
+);
+const animateSprites = defineSystem({
+  name: "sprite/animate",
+  description: "Plays sprite animation clips: time, frame, Sprite region, events.",
+  setup: (world) => ({
+    q: world.query({ with: [SpriteAnimation, Sprite] }),
+    warned: /* @__PURE__ */ new Set(),
+    // The last frame shown per entity, so events fire once per frame change.
+    lastFrames: /* @__PURE__ */ new Map()
+  }),
+  run: ({ q, warned, lastFrames }, world) => {
+    const clips = world.resource(SpriteClips);
+    const atlases = world.resource(TextureAtlases);
+    const dt = world.resource(Time).delta;
+    for (const table of q.tables) {
+      const clipRefs = table.column(SpriteAnimation, "clip");
+      const playing = table.column(SpriteAnimation, "playing");
+      const speed = table.column(SpriteAnimation, "speed");
+      const time = table.column(SpriteAnimation, "time");
+      const atlas = table.column(Sprite, "atlas");
+      const region = table.column(Sprite, "region");
+      for (let i = 0; i < table.count; i++) {
+        const clip = clips.get(clipRefs[i]);
+        if (!clip || clip.regions.length === 0) continue;
+        const entity = table.entities[i];
+        const before = time[i];
+        if (playing[i]) {
+          time[i] = before + dt * speed[i];
+          table.markChanged(SpriteAnimation, i);
+        }
+        const frame = clip.frameAt(time[i]);
+        if (playing[i] && clip.ended(time[i])) playing[i] = 0;
+        const previous = lastFrames.get(entity);
+        if (previous !== frame) {
+          if (clip.events.size > 0)
+            sendPassed(world, clip, entity, previous, before, time[i], frame);
+          lastFrames.set(entity, frame);
+          const name = clip.regions[frame];
+          if (region[i] !== name || clip.atlas && atlas[i]?.guid !== clip.atlas.guid) {
+            region[i] = name;
+            if (clip.atlas) atlas[i] = clip.atlas;
+            table.markChanged(Sprite, i);
+          }
+          const a = atlases.get(clip.atlas);
+          if (a && a.region(name) < 0 && !warned.has(name)) {
+            warned.add(name);
+            world.tryResource(LogResource)?.warn(`Sprite clip frame "${name}" isn't a region of its atlas`);
+          }
+        }
+      }
+    }
+  }
+});
+function sendPassed(world, clip, entity, previous, from, to, frame) {
+  const n = clip.regions.length;
+  if (previous === void 0 || clip.loop === "ping-pong" || n === 1) {
+    for (const name of clip.events.get(frame) ?? []) {
+      world.send(SpriteAnimationEvent, { entity, name, frame });
+    }
+    return;
+  }
+  const step = to >= from ? 1 : -1;
+  let f = previous;
+  for (let guard = 0; guard < n * 4 && f !== frame; guard++) {
+    f = ((f + step) % n + n) % n;
+    for (const name of clip.events.get(f) ?? []) {
+      world.send(SpriteAnimationEvent, { entity, name, frame: f });
+    }
+  }
+}
+const spriteClipPreview = defineAssetPreview(
+  "SpriteClip",
+  async (world, path, width, height) => {
+    const server = assetServer(world);
+    const clip = SpriteClipSchema.deserialize((await server.artifact(path)).json);
+    const atlasPath = clip.atlas?.path;
+    if (!atlasPath)
+      throw new ShardError("sprite/no-atlas", `${path} has no atlas`, { path: "/atlas" });
+    const atlas = TextureAtlas.fromJson((await server.artifact(atlasPath)).json);
+    const texturePath = atlas.texture?.path?.startsWith("#") ? `${atlasPath.split("#")[0]}${atlas.texture.path}` : atlas.texture?.path;
+    if (!texturePath) throw new ShardError("sprite/no-texture", `${atlasPath} has no texture`);
+    const ktx = readKtx2((await server.artifact(texturePath)).bytes);
+    const src = ktx.levels[0];
+    const rects = clip.frames.map((f) => {
+      const r = atlas.region(f.region);
+      return r < 0 ? [0, 0, 1, 1] : [...atlas.rects.subarray(r * 4, r * 4 + 4)];
+    });
+    const cw = Math.max(1, ...rects.map((r) => r[2]));
+    const ch = Math.max(1, ...rects.map((r) => r[3]));
+    const sheetW = cw * rects.length;
+    const sheet = new Uint8Array(sheetW * ch * 4);
+    rects.forEach(([x, y, w, h], k) => {
+      for (let j = 0; j < h; j++) {
+        for (let i = 0; i < w; i++) {
+          const s = ((y + j) * ktx.width + x + i) * 4;
+          sheet.set(src.subarray(s, s + 4), (j * sheetW + k * cw + i) * 4);
+        }
+      }
+    });
+    const image = fitImage(sheet, sheetW, ch, width, height);
+    const scale = image.width / sheetW;
+    for (let k = 0; k < rects.length; k++)
+      drawLabel(image, String(k), Math.round(k * cw * scale) + 1, 1);
+    return image;
+  }
+);
+export {
+  CLIP_LOOPS,
+  SpriteAnimation,
+  SpriteAnimationEvent,
+  SpriteClip,
+  SpriteClipAssetType,
+  SpriteClipImporter,
+  SpriteClipSchema,
+  SpriteClipStore,
+  SpriteClips,
+  animateSprites,
+  spriteClipPreview
+};

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { AtlasPackImporter, AtlasPackSchema, packImages, packNormals, regionOutline, TextureAtlas, TextureAtlasAssetType, TextureAtlases, TextureAtlasImporter, TextureAtlasSchema, TextureAtlasStore, } from './atlas.js';
+export { animateSprites, CLIP_LOOPS, SpriteAnimation, SpriteAnimationEvent, type SpriteAnimationEventValue, SpriteClip, SpriteClipAssetType, SpriteClipImporter, SpriteClipSchema, SpriteClipStore, SpriteClips, } from './clip.js';
+export { Lighting2d, LightOccluder2d, layerBit, OCCLUDER_SHAPES, type OccluderShape, PointLight2d, SpotLight2d, SpriteLighting, } from './lighting.js';
+export { binLightsCpu, describeLights2d, LIGHT2D_FLOATS, Lights2d, Lights2dStore, LightView2d, lightCircle, MAX_SHADOWED, OccluderStore, prepareLights2d, SEGMENT_FLOATS, SHADOW_RES, shadowFactorCpu, shadowRowCpu, TILE_MAX, TILE_PIXELS, TILE_STRIDE, } from './lights2d.js';
+export { boxPolygon, capsulePolygon, circlePolygon, convexHull, occluderSegments, polygonProblem, polygonSegments, spriteOutline, tileChunkEdges, transformSegments, } from './occluders.js';
+export { alphaOutline, distanceToLoop, loopArea, simplifyLoop, traceAlpha } from './outline.js';
+export { spritePlugin } from './plugin.js';
+export { describeSprites, prepareSprites, SPRITE_FLOATS, type SpriteBatch, SpriteStore, Sprites, TilemapStore, Tilemaps, } from './render.js';
+export { SPRITE_SHADERS } from './shaders.js';
+export { SPRITE_BLENDS, SPRITE_SORTS, SPRITE_SPACES, Sprite, Sprite2dSettings, type Sprite2dSettingsValue, SpriteSlot, } from './sprite.js';
+export { setTile, TileFlags, TileLayer, Tilemap, TilemapData, TilemapDataAssetType, TilemapDataImporter, TilemapDataSchema, TilemapDataStore, TilemapDatas, tileAt, } from './tilemap.js';

package/dist/index.js

@@ -0,0 +1,186 @@
+import {
+  AtlasPackImporter,
+  AtlasPackSchema,
+  packImages,
+  packNormals,
+  regionOutline,
+  TextureAtlas,
+  TextureAtlasAssetType,
+  TextureAtlases,
+  TextureAtlasImporter,
+  TextureAtlasSchema,
+  TextureAtlasStore
+} from "./atlas.js";
+import {
+  animateSprites,
+  CLIP_LOOPS,
+  SpriteAnimation,
+  SpriteAnimationEvent,
+  SpriteClip,
+  SpriteClipAssetType,
+  SpriteClipImporter,
+  SpriteClipSchema,
+  SpriteClipStore,
+  SpriteClips
+} from "./clip.js";
+import {
+  Lighting2d,
+  LightOccluder2d,
+  layerBit,
+  OCCLUDER_SHAPES,
+  PointLight2d,
+  SpotLight2d,
+  SpriteLighting
+} from "./lighting.js";
+import {
+  binLightsCpu,
+  describeLights2d,
+  LIGHT2D_FLOATS,
+  Lights2d,
+  Lights2dStore,
+  LightView2d,
+  lightCircle,
+  MAX_SHADOWED,
+  OccluderStore,
+  prepareLights2d,
+  SEGMENT_FLOATS,
+  SHADOW_RES,
+  shadowFactorCpu,
+  shadowRowCpu,
+  TILE_MAX,
+  TILE_PIXELS,
+  TILE_STRIDE
+} from "./lights2d.js";
+import {
+  boxPolygon,
+  capsulePolygon,
+  circlePolygon,
+  convexHull,
+  occluderSegments,
+  polygonProblem,
+  polygonSegments,
+  spriteOutline,
+  tileChunkEdges,
+  transformSegments
+} from "./occluders.js";
+import { alphaOutline, distanceToLoop, loopArea, simplifyLoop, traceAlpha } from "./outline.js";
+import { spritePlugin } from "./plugin.js";
+import {
+  describeSprites,
+  prepareSprites,
+  SPRITE_FLOATS,
+  SpriteStore,
+  Sprites,
+  TilemapStore,
+  Tilemaps
+} from "./render.js";
+import { SPRITE_SHADERS } from "./shaders.js";
+import {
+  SPRITE_BLENDS,
+  SPRITE_SORTS,
+  SPRITE_SPACES,
+  Sprite,
+  Sprite2dSettings,
+  SpriteSlot
+} from "./sprite.js";
+import {
+  setTile,
+  TileFlags,
+  TileLayer,
+  Tilemap,
+  TilemapData,
+  TilemapDataAssetType,
+  TilemapDataImporter,
+  TilemapDataSchema,
+  TilemapDataStore,
+  TilemapDatas,
+  tileAt
+} from "./tilemap.js";
+export {
+  AtlasPackImporter,
+  AtlasPackSchema,
+  CLIP_LOOPS,
+  LIGHT2D_FLOATS,
+  LightOccluder2d,
+  LightView2d,
+  Lighting2d,
+  Lights2d,
+  Lights2dStore,
+  MAX_SHADOWED,
+  OCCLUDER_SHAPES,
+  OccluderStore,
+  PointLight2d,
+  SEGMENT_FLOATS,
+  SHADOW_RES,
+  SPRITE_BLENDS,
+  SPRITE_FLOATS,
+  SPRITE_SHADERS,
+  SPRITE_SORTS,
+  SPRITE_SPACES,
+  SpotLight2d,
+  Sprite,
+  Sprite2dSettings,
+  SpriteAnimation,
+  SpriteAnimationEvent,
+  SpriteClip,
+  SpriteClipAssetType,
+  SpriteClipImporter,
+  SpriteClipSchema,
+  SpriteClipStore,
+  SpriteClips,
+  SpriteLighting,
+  SpriteSlot,
+  SpriteStore,
+  Sprites,
+  TILE_MAX,
+  TILE_PIXELS,
+  TILE_STRIDE,
+  TextureAtlas,
+  TextureAtlasAssetType,
+  TextureAtlasImporter,
+  TextureAtlasSchema,
+  TextureAtlasStore,
+  TextureAtlases,
+  TileFlags,
+  TileLayer,
+  Tilemap,
+  TilemapData,
+  TilemapDataAssetType,
+  TilemapDataImporter,
+  TilemapDataSchema,
+  TilemapDataStore,
+  TilemapDatas,
+  TilemapStore,
+  Tilemaps,
+  alphaOutline,
+  animateSprites,
+  binLightsCpu,
+  boxPolygon,
+  capsulePolygon,
+  circlePolygon,
+  convexHull,
+  describeLights2d,
+  describeSprites,
+  distanceToLoop,
+  layerBit,
+  lightCircle,
+  loopArea,
+  occluderSegments,
+  packImages,
+  packNormals,
+  polygonProblem,
+  polygonSegments,
+  prepareLights2d,
+  prepareSprites,
+  regionOutline,
+  setTile,
+  shadowFactorCpu,
+  shadowRowCpu,
+  simplifyLoop,
+  spriteOutline,
+  spritePlugin,
+  tileAt,
+  tileChunkEdges,
+  traceAlpha,
+  transformSegments
+};

package/dist/lighting-shaders.d.ts

@@ -0,0 +1,5 @@
+/**
+ * WGSL for 2D lighting: light records, tile binning, 1D polar shadow maps, and the per-fragment
+ * light loop the lit sprite and tilemap variants call. Constants match lights2d.ts.
+ */
+export declare const LIGHT2D_SHADERS: Record<string, string>;