@spritebuddy/core 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Patrick Hammond
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,61 @@
-# Temporary Holding Version
+# @spritebuddy/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Reads [SpriteBuddy](https://github.com/Patrick-Hammond/spritebuddy) runtime files
+([format](https://github.com/Patrick-Hammond/spritebuddy-runtimes/blob/main/docs/format.md)) and works out what to draw at any moment. No
+dependencies and no engine: [`@spritebuddy/pixi`](https://www.npmjs.com/package/@spritebuddy/pixi)
+builds on it, and you can use it with any renderer that can draw part of an image.
+
+```sh
+npm install @spritebuddy/core
+```
+
+## Quick start
+
+```ts
+import { parseFile, Player } from '@spritebuddy/core';
+
+const file = parseFile(await (await fetch('knight.anims.json')).json());
+const player = new Player(file, {
+  onComplete: () => player.play('idle'),
+  onEvent: (name) => name === 'hit' && dealDamage(), // events tagged on frames in SpriteBuddy
+}).play('attack');
+
+// every tick
+player.update(deltaMs);
+for (const part of player.parts) {
+  // Draw part.frame.rect from the sheet with its full-frame top-left at
+  // (spriteX + part.x, spriteY + part.y), mirrored by part.flipX / part.flipY, at
+  // part.opacity. Trimmed frames start part.frame.trim.x/y further in; rotated frames are
+  // stored turned 90° clockwise.
+}
+```
+
+The [canvas example](https://github.com/Patrick-Hammond/spritebuddy-runtimes/tree/main/examples/canvas) is a complete page that does exactly
+this with a 2D canvas, rotation, trim and flips included, in about 60 lines.
+
+## API
+
+- `parseFile(json)` checks a runtime file and fills in every default. It throws a
+  `FormatError` that says where the file is wrong, and refuses versions newer than `VERSION`.
+- `new Player(file, { onFrame, onEvent, onComplete })` keeps time for one sprite:
+  - `play(name, fromMs?)` starts an animation (it throws for an unknown name, listing the
+    names there are), `stop()`, `seek(ms)` and `update(ms)`.
+  - `speed` (1 is normal), `playing`, `names`, `animation(name)`.
+  - `parts`: what to draw now, bottom to top. `state` adds the animation, frame index, time
+    and whether a `once` animation is done.
+  - `onFrame(index)` fires when the frame changes; `onEvent(name, index)` for each event
+    tagged on a frame as it starts showing (after `onFrame`), including frames a long tick
+    skipped; `onComplete()` when a `once` animation ends. `play` fires the first frame's
+    events; `seek` fires none.
+- The pure functions underneath, for engines that keep their own clock:
+  - `frameAt(animation, ms)` gives the frame index showing at a time, and whether it is done.
+  - `partsOf(file, animationFrame)` gives the parts to draw for one frame.
+  - `eventsBetween(animation, fromMs, toMs)` lists the events of frames starting after `fromMs`
+    up to `toMs`, at most one cycle's worth.
+  - `boundsOf`, `cycleDuration` and `cycleOrder` help with layout and timelines.
+- The JSON Schema ships as `@spritebuddy/core/schema.json`.
+
+Every function is tested against the shared
+[golden tables](https://github.com/Patrick-Hammond/spritebuddy-runtimes/tree/main/fixtures), the same ones the PixiJS and Godot runtimes pass.
+
+Licence: ISC.

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { FORMAT, VERSION } from './types.js';
+export type { AnimationDef, AnimationFrameDef, FrameDef, LayerDef, LoopMode, Point, Rect, SpriteBuddyFile, Trim, } from './types.js';
+export { DEFAULT_DURATION, FormatError, parseFile } from './parse.js';
+export { cycleDuration, cycleOrder, eventsBetween, frameAt, type FrameEvent, type PlaybackPosition, } from './timing.js';
+export { boundsOf, partsOf, type Part } from './resolve.js';
+export { Player, type PlayerEvents, type PlayerState } from './player.js';

package/dist/index.js

@@ -0,0 +1,6 @@
+export { FORMAT, VERSION } from './types.js';
+export { DEFAULT_DURATION, FormatError, parseFile } from './parse.js';
+export { cycleDuration, cycleOrder, eventsBetween, frameAt, } from './timing.js';
+export { boundsOf, partsOf } from './resolve.js';
+export { Player } from './player.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAY7C,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EACL,aAAa,EACb,UAAU,EACV,aAAa,EACb,OAAO,GAGR,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAa,MAAM,cAAc,CAAC;AAC5D,OAAO,EAAE,MAAM,EAAuC,MAAM,aAAa,CAAC"}

package/dist/parse.d.ts

@@ -0,0 +1,14 @@
+import { type SpriteBuddyFile } from './types.js';
+/** Thrown for a file that isn't a readable SpriteBuddy runtime file; `path` says where. */
+export declare class FormatError extends Error {
+    readonly path: string;
+    constructor(message: string, path: string);
+}
+/** Default display time of a frame when neither it nor its animation says, in ms. */
+export declare const DEFAULT_DURATION = 100;
+/**
+ * Reads a SpriteBuddy runtime file (`.anims.json`, version 3) from parsed JSON, filling in every
+ * default. Unknown fields are ignored so newer minor additions still load. Throws
+ * {@link FormatError} saying where the file is wrong.
+ */
+export declare function parseFile(json: unknown): SpriteBuddyFile;

package/dist/parse.js

@@ -0,0 +1,178 @@
+import { FORMAT, VERSION, } from './types.js';
+/** Thrown for a file that isn't a readable SpriteBuddy runtime file; `path` says where. */
+export class FormatError extends Error {
+    constructor(message, path) {
+        super(path ? `${path}: ${message}` : message);
+        this.path = path;
+        this.name = 'FormatError';
+    }
+}
+/** Default display time of a frame when neither it nor its animation says, in ms. */
+export const DEFAULT_DURATION = 100;
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+function object(v, path) {
+    if (!isObject(v))
+        throw new FormatError('expected an object', path);
+    return v;
+}
+function array(v, path) {
+    if (!Array.isArray(v))
+        throw new FormatError('expected a list', path);
+    return v;
+}
+function string(v, path) {
+    if (typeof v !== 'string' || v === '')
+        throw new FormatError('expected a non-empty string', path);
+    return v;
+}
+function int(v, path, min = -Infinity) {
+    if (typeof v !== 'number' || !Number.isInteger(v) || v < min) {
+        throw new FormatError(min > -Infinity ? `expected a whole number ≥ ${min}` : 'expected a whole number', path);
+    }
+    return v;
+}
+function number(v, path, min, max) {
+    if (typeof v !== 'number' || !Number.isFinite(v) || v < min || v > max) {
+        throw new FormatError(`expected a number from ${min} to ${max}`, path);
+    }
+    return v;
+}
+function bool(v, path) {
+    if (typeof v !== 'boolean')
+        throw new FormatError('expected true or false', path);
+    return v;
+}
+/** A list of whole numbers of a fixed length, such as `[x, y]`. */
+function ints(v, path, length, min) {
+    const list = array(v, path);
+    if (list.length !== length)
+        throw new FormatError(`expected ${length} numbers`, path);
+    return list.map((n, i) => int(n, `${path}[${i}]`, min[i]));
+}
+const opt = (v, fallback, read) => v === undefined ? fallback : read(v);
+function frameDef(v, path, sheet) {
+    const o = object(v, path);
+    const [x, y, w, h] = ints(o.rect, `${path}.rect`, 4, [0, 0, 1, 1]);
+    const rotated = opt(o.rotated, false, (r) => bool(r, `${path}.rotated`));
+    const [cols, rows] = rotated ? [h, w] : [w, h];
+    if (x + cols > sheet.w || y + rows > sheet.h) {
+        throw new FormatError('lies outside the sheet', `${path}.rect`);
+    }
+    let trim = null;
+    let width = w;
+    let height = h;
+    if (o.trim !== undefined) {
+        const [tx, ty, fw, fh] = ints(o.trim, `${path}.trim`, 4, [0, 0, 1, 1]);
+        if (tx + w > fw || ty + h > fh) {
+            throw new FormatError('the trimmed pixels lie outside the full frame', `${path}.trim`);
+        }
+        trim = { x: tx, y: ty };
+        width = fw;
+        height = fh;
+    }
+    const pivot = array(o.pivot ?? [width / 2, height], `${path}.pivot`);
+    if (pivot.length !== 2)
+        throw new FormatError('expected 2 numbers', `${path}.pivot`);
+    const [px, py] = pivot.map((n, i) => number(n, `${path}.pivot[${i}]`, -1e6, 1e6));
+    return {
+        name: string(o.name, `${path}.name`),
+        rect: { x, y, w, h },
+        pivot: { x: px, y: py },
+        rotated,
+        trim,
+        width,
+        height,
+    };
+}
+function frameIndex(v, path, count) {
+    const i = int(v, path, 0);
+    if (i >= count)
+        throw new FormatError(`no frame ${i}; the file has ${count}`, path);
+    return i;
+}
+function layerDef(v, path, count) {
+    const o = object(v, path);
+    return {
+        frame: frameIndex(o.frame, `${path}.frame`, count),
+        x: opt(o.x, 0, (n) => int(n, `${path}.x`)),
+        y: opt(o.y, 0, (n) => int(n, `${path}.y`)),
+        z: opt(o.z, 1, (n) => int(n, `${path}.z`)),
+        opacity: opt(o.opacity, 1, (n) => number(n, `${path}.opacity`, 0, 1)),
+        flipX: opt(o.flipX, false, (b) => bool(b, `${path}.flipX`)),
+        flipY: opt(o.flipY, false, (b) => bool(b, `${path}.flipY`)),
+    };
+}
+function animationFrameDef(v, path, count, duration) {
+    if (typeof v === 'number') {
+        return {
+            frame: frameIndex(v, path, count),
+            duration,
+            offset: { x: 0, y: 0 },
+            layers: [],
+            events: [],
+        };
+    }
+    const o = object(v, path);
+    const [ox, oy] = opt(o.offset, [0, 0], (n) => ints(n, `${path}.offset`, 2, [-Infinity, -Infinity]));
+    return {
+        frame: frameIndex(o.frame, `${path}.frame`, count),
+        duration: opt(o.duration, duration, (n) => int(n, `${path}.duration`, 1)),
+        offset: { x: ox, y: oy },
+        layers: opt(o.layers, [], (l) => array(l, `${path}.layers`).map((layer, i) => layerDef(layer, `${path}.layers[${i}]`, count))),
+        events: opt(o.events, [], (e) => array(e, `${path}.events`).map((name, i) => string(name, `${path}.events[${i}]`))),
+    };
+}
+const LOOPS = ['loop', 'pingpong', 'once'];
+function animationDef(v, path, count) {
+    const o = object(v, path);
+    const loop = opt(o.loop, 'loop', (l) => {
+        if (!LOOPS.includes(l)) {
+            throw new FormatError('expected "loop", "pingpong" or "once"', `${path}.loop`);
+        }
+        return l;
+    });
+    const duration = opt(o.duration, DEFAULT_DURATION, (n) => int(n, `${path}.duration`, 1));
+    return {
+        name: string(o.name, `${path}.name`),
+        loop,
+        frames: array(o.frames, `${path}.frames`).map((f, i) => animationFrameDef(f, `${path}.frames[${i}]`, count, duration)),
+    };
+}
+/**
+ * Reads a SpriteBuddy runtime file (`.anims.json`, version 3) from parsed JSON, filling in every
+ * default. Unknown fields are ignored so newer minor additions still load. Throws
+ * {@link FormatError} saying where the file is wrong.
+ */
+export function parseFile(json) {
+    const o = object(json, '');
+    if (o.format !== FORMAT) {
+        throw new FormatError(`not a SpriteBuddy animations file (format should be "${FORMAT}")`, 'format');
+    }
+    const version = int(o.version, 'version', 1);
+    if (version < 3) {
+        throw new FormatError(`version ${version} files need the sheet's own JSON; export again from SpriteBuddy for version ${VERSION}`, 'version');
+    }
+    if (version > VERSION) {
+        throw new FormatError(`version ${version} is newer than this runtime reads (${VERSION}); update @spritebuddy packages`, 'version');
+    }
+    const [width, height] = ints(o.size, 'size', 2, [1, 1]);
+    const sheet = { w: width, h: height };
+    const frames = array(o.frames, 'frames').map((f, i) => frameDef(f, `frames[${i}]`, sheet));
+    const animations = opt(o.animations, [], (a) => array(a, 'animations').map((anim, i) => animationDef(anim, `animations[${i}]`, frames.length)));
+    const names = new Set();
+    animations.forEach((a, i) => {
+        if (names.has(a.name))
+            throw new FormatError(`duplicate animation "${a.name}"`, `animations[${i}].name`);
+        names.add(a.name);
+    });
+    return {
+        version,
+        image: string(o.image, 'image'),
+        width,
+        height,
+        scale: opt(o.scale, 1, (s) => number(s, 'scale', 1e-6, 1e6)),
+        frames,
+        animations,
+    };
+}
+//# sourceMappingURL=parse.js.map

package/dist/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"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"}

package/dist/player.d.ts

@@ -0,0 +1,53 @@
+import { type Part } from './resolve.js';
+import type { AnimationDef, SpriteBuddyFile } from './types.js';
+export interface PlayerState {
+    /** The animation playing, or null before `play`. */
+    readonly animation: AnimationDef | null;
+    /** Index into the animation's frames, or -1. */
+    readonly index: number;
+    /** Ms since the animation started, scaled by `speed`. */
+    readonly time: number;
+    readonly done: boolean;
+    /** What to draw now, bottom to top. */
+    readonly parts: readonly Part[];
+}
+export interface PlayerEvents {
+    /** Called with the frame index each time the frame changes. */
+    onFrame?: (index: number) => void;
+    /** Called when a `once` animation ends. */
+    onComplete?: () => void;
+    /**
+     * Called for each event of a frame as it starts showing (see {@link eventsBetween}). `play`
+     * fires the first frame's events; `seek` jumps without firing any.
+     */
+    onEvent?: (name: string, index: number) => void;
+}
+/**
+ * Plays a file's animations with nothing but a clock: call {@link update} every tick with the
+ * elapsed ms and draw {@link parts}. Engine adapters wrap this; games can use it directly too.
+ */
+export declare class Player {
+    #private;
+    readonly file: SpriteBuddyFile;
+    /** Playback rate: 1 is normal, 2 twice as fast, 0 frozen. */
+    speed: number;
+    /** Whether {@link update} moves time on. */
+    playing: boolean;
+    constructor(file: SpriteBuddyFile, events?: PlayerEvents);
+    /** Names of every animation in the file. */
+    get names(): string[];
+    /** The animation called `name`, or undefined. */
+    animation(name: string): AnimationDef | undefined;
+    /**
+     * Starts an animation from its first frame (or from `time` ms). Throws for an unknown name,
+     * listing the ones there are.
+     */
+    play(name: string, time?: number): this;
+    stop(): this;
+    /** Jumps to `time` ms into the current animation. */
+    seek(time: number): this;
+    /** Moves time on by `ms` (times {@link speed}) while playing. */
+    update(ms: number): this;
+    get state(): PlayerState;
+    get parts(): readonly Part[];
+}

package/dist/player.js

@@ -0,0 +1,116 @@
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _Player_instances, _Player_animation, _Player_time, _Player_index, _Player_done, _Player_parts, _Player_onFrame, _Player_onComplete, _Player_onEvent, _Player_refresh;
+import { partsOf } from './resolve.js';
+import { eventsBetween, frameAt } from './timing.js';
+/**
+ * Plays a file's animations with nothing but a clock: call {@link update} every tick with the
+ * elapsed ms and draw {@link parts}. Engine adapters wrap this; games can use it directly too.
+ */
+export class Player {
+    constructor(file, events = {}) {
+        _Player_instances.add(this);
+        /** Playback rate: 1 is normal, 2 twice as fast, 0 frozen. */
+        this.speed = 1;
+        /** Whether {@link update} moves time on. */
+        this.playing = false;
+        _Player_animation.set(this, null);
+        _Player_time.set(this, 0);
+        _Player_index.set(this, -1);
+        _Player_done.set(this, false);
+        _Player_parts.set(this, []);
+        _Player_onFrame.set(this, void 0);
+        _Player_onComplete.set(this, void 0);
+        _Player_onEvent.set(this, void 0);
+        this.file = file;
+        __classPrivateFieldSet(this, _Player_onFrame, events.onFrame, "f");
+        __classPrivateFieldSet(this, _Player_onComplete, events.onComplete, "f");
+        __classPrivateFieldSet(this, _Player_onEvent, events.onEvent, "f");
+    }
+    /** Names of every animation in the file. */
+    get names() {
+        return this.file.animations.map((a) => a.name);
+    }
+    /** The animation called `name`, or undefined. */
+    animation(name) {
+        return this.file.animations.find((a) => a.name === name);
+    }
+    /**
+     * Starts an animation from its first frame (or from `time` ms). Throws for an unknown name,
+     * listing the ones there are.
+     */
+    play(name, time = 0) {
+        const anim = this.animation(name);
+        if (!anim) {
+            throw new Error(`No animation "${name}"; this file has ${this.names.map((n) => `"${n}"`).join(', ') || 'none'}`);
+        }
+        __classPrivateFieldSet(this, _Player_animation, anim, "f");
+        __classPrivateFieldSet(this, _Player_index, -1, "f");
+        __classPrivateFieldSet(this, _Player_done, false, "f");
+        this.playing = true;
+        __classPrivateFieldSet(this, _Player_time, Math.max(0, time), "f");
+        const index = frameAt(anim, __classPrivateFieldGet(this, _Player_time, "f")).index;
+        __classPrivateFieldGet(this, _Player_instances, "m", _Player_refresh).call(this, index < 0 ? [] : anim.frames[index].events.map((name) => ({ name, index })));
+        return this;
+    }
+    stop() {
+        this.playing = false;
+        return this;
+    }
+    /** Jumps to `time` ms into the current animation. */
+    seek(time) {
+        __classPrivateFieldSet(this, _Player_time, Math.max(0, time), "f");
+        __classPrivateFieldGet(this, _Player_instances, "m", _Player_refresh).call(this);
+        return this;
+    }
+    /** Moves time on by `ms` (times {@link speed}) while playing. */
+    update(ms) {
+        const anim = __classPrivateFieldGet(this, _Player_animation, "f");
+        if (this.playing && anim) {
+            const from = __classPrivateFieldGet(this, _Player_time, "f");
+            __classPrivateFieldSet(this, _Player_time, __classPrivateFieldGet(this, _Player_time, "f") + Math.max(0, ms) * this.speed, "f");
+            __classPrivateFieldGet(this, _Player_instances, "m", _Player_refresh).call(this, __classPrivateFieldGet(this, _Player_onEvent, "f") ? eventsBetween(anim, from, __classPrivateFieldGet(this, _Player_time, "f")) : []);
+        }
+        return this;
+    }
+    get state() {
+        return {
+            animation: __classPrivateFieldGet(this, _Player_animation, "f"),
+            index: __classPrivateFieldGet(this, _Player_index, "f"),
+            time: __classPrivateFieldGet(this, _Player_time, "f"),
+            done: __classPrivateFieldGet(this, _Player_done, "f"),
+            parts: __classPrivateFieldGet(this, _Player_parts, "f"),
+        };
+    }
+    get parts() {
+        return __classPrivateFieldGet(this, _Player_parts, "f");
+    }
+}
+_Player_animation = new WeakMap(), _Player_time = new WeakMap(), _Player_index = new WeakMap(), _Player_done = new WeakMap(), _Player_parts = new WeakMap(), _Player_onFrame = new WeakMap(), _Player_onComplete = new WeakMap(), _Player_onEvent = new WeakMap(), _Player_instances = new WeakSet(), _Player_refresh = function _Player_refresh(fired = []) {
+    const anim = __classPrivateFieldGet(this, _Player_animation, "f");
+    if (!anim)
+        return;
+    const pos = frameAt(anim, __classPrivateFieldGet(this, _Player_time, "f"));
+    const changed = pos.index !== __classPrivateFieldGet(this, _Player_index, "f");
+    __classPrivateFieldSet(this, _Player_index, pos.index, "f");
+    __classPrivateFieldSet(this, _Player_parts, pos.index < 0 ? [] : partsOf(this.file, anim.frames[pos.index]), "f");
+    if (changed && pos.index >= 0)
+        __classPrivateFieldGet(this, _Player_onFrame, "f")?.call(this, pos.index);
+    for (const e of fired)
+        __classPrivateFieldGet(this, _Player_onEvent, "f")?.call(this, e.name, e.index);
+    if (pos.done && !__classPrivateFieldGet(this, _Player_done, "f")) {
+        __classPrivateFieldSet(this, _Player_done, true, "f");
+        this.playing = false;
+        __classPrivateFieldGet(this, _Player_onComplete, "f")?.call(this);
+    }
+};
+//# sourceMappingURL=player.js.map

package/dist/player.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"player.js","sourceRoot":"","sources":["../src/player.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,OAAO,EAAE,OAAO,EAAa,MAAM,cAAc,CAAC;AAClD,OAAO,EAAE,aAAa,EAAE,OAAO,EAAmB,MAAM,aAAa,CAAC;AA2BtE;;;GAGG;AACH,MAAM,OAAO,MAAM;IAejB,YAAY,IAAqB,EAAE,SAAuB,EAAE;;QAb5D,6DAA6D;QAC7D,UAAK,GAAG,CAAC,CAAC;QACV,4CAA4C;QAC5C,YAAO,GAAG,KAAK,CAAC;QAChB,4BAAkC,IAAI,EAAC;QACvC,uBAAQ,CAAC,EAAC;QACV,wBAAS,CAAC,CAAC,EAAC;QACZ,uBAAQ,KAAK,EAAC;QACd,wBAA0B,EAAE,EAAC;QAC7B,kCAAmC;QACnC,qCAAyB;QACzB,kCAAiD;QAG/C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,uBAAA,IAAI,mBAAY,MAAM,CAAC,OAAO,MAAA,CAAC;QAC/B,uBAAA,IAAI,sBAAe,MAAM,CAAC,UAAU,MAAA,CAAC;QACrC,uBAAA,IAAI,mBAAY,MAAM,CAAC,OAAO,MAAA,CAAC;IACjC,CAAC;IAED,4CAA4C;IAC5C,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACjD,CAAC;IAED,iDAAiD;IACjD,SAAS,CAAC,IAAY;QACpB,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IAC3D,CAAC;IAED;;;OAGG;IACH,IAAI,CAAC,IAAY,EAAE,IAAI,GAAG,CAAC;QACzB,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,KAAK,CACb,iBAAiB,IAAI,oBAAoB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,EAAE,CAChG,CAAC;QACJ,CAAC;QACD,uBAAA,IAAI,qBAAc,IAAI,MAAA,CAAC;QACvB,uBAAA,IAAI,iBAAU,CAAC,CAAC,MAAA,CAAC;QACjB,uBAAA,IAAI,gBAAS,KAAK,MAAA,CAAC;QACnB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;QACpB,uBAAA,IAAI,gBAAS,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,MAAA,CAAC;QAC/B,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,EAAE,uBAAA,IAAI,oBAAM,CAAC,CAAC,KAAK,CAAC;QAC9C,uBAAA,IAAI,0CAAS,MAAb,IAAI,EAAU,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC;QAC5F,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI;QACF,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,qDAAqD;IACrD,IAAI,CAAC,IAAY;QACf,uBAAA,IAAI,gBAAS,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,MAAA,CAAC;QAC/B,uBAAA,IAAI,0CAAS,MAAb,IAAI,CAAW,CAAC;QAChB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,iEAAiE;IACjE,MAAM,CAAC,EAAU;QACf,MAAM,IAAI,GAAG,uBAAA,IAAI,yBAAW,CAAC;QAC7B,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,EAAE,CAAC;YACzB,MAAM,IAAI,GAAG,uBAAA,IAAI,oBAAM,CAAC;YACxB,6FAAc,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,CAAC,KAAK,MAAA,CAAC;YAC3C,uBAAA,IAAI,0CAAS,MAAb,IAAI,EAAU,uBAAA,IAAI,uBAAS,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,EAAE,IAAI,EAAE,uBAAA,IAAI,oBAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC5E,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,KAAK;QACP,OAAO;YACL,SAAS,EAAE,uBAAA,IAAI,yBAAW;YAC1B,KAAK,EAAE,uBAAA,IAAI,qBAAO;YAClB,IAAI,EAAE,uBAAA,IAAI,oBAAM;YAChB,IAAI,EAAE,uBAAA,IAAI,oBAAM;YAChB,KAAK,EAAE,uBAAA,IAAI,qBAAO;SACnB,CAAC;IACJ,CAAC;IAED,IAAI,KAAK;QACP,OAAO,uBAAA,IAAI,qBAAO,CAAC;IACrB,CAAC;CAkBF;iVAfU,QAA+B,EAAE;IACxC,MAAM,IAAI,GAAG,uBAAA,IAAI,yBAAW,CAAC;IAC7B,IAAI,CAAC,IAAI;QAAE,OAAO;IAClB,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,EAAE,uBAAA,IAAI,oBAAM,CAAC,CAAC;IACtC,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,KAAK,uBAAA,IAAI,qBAAO,CAAC;IAC1C,uBAAA,IAAI,iBAAU,GAAG,CAAC,KAAK,MAAA,CAAC;IACxB,uBAAA,IAAI,iBAAU,GAAG,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC,MAAA,CAAC;IAC/E,IAAI,OAAO,IAAI,GAAG,CAAC,KAAK,IAAI,CAAC;QAAE,uBAAA,IAAI,uBAAS,EAAE,KAAf,IAAI,EAAY,GAAG,CAAC,KAAK,CAAC,CAAC;IAC1D,KAAK,MAAM,CAAC,IAAI,KAAK;QAAE,uBAAA,IAAI,uBAAS,EAAE,KAAf,IAAI,EAAY,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC;IACxD,IAAI,GAAG,CAAC,IAAI,IAAI,CAAC,uBAAA,IAAI,oBAAM,EAAE,CAAC;QAC5B,uBAAA,IAAI,gBAAS,IAAI,MAAA,CAAC;QAClB,IAAI,CAAC,OAAO,GAAG,KAAK,CAAC;QACrB,uBAAA,IAAI,0BAAY,EAAE,KAAlB,IAAI,CAAgB,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/resolve.d.ts

@@ -0,0 +1,30 @@
+import type { AnimationFrameDef, FrameDef, SpriteBuddyFile } from './types.js';
+/**
+ * One image to draw for an animation frame: the base frame or one of its layers, in draw order.
+ * `x, y` is where the part's full (untrimmed, upright) frame has its top-left, relative to the
+ * sprite's origin: the base frame's pivot, already moved by the frame's offset. So a renderer
+ * puts the sprite where the character stands and draws each part at `origin + (x, y)`.
+ */
+export interface Part {
+    readonly frame: FrameDef;
+    /** Index into the file's frames. */
+    readonly index: number;
+    readonly x: number;
+    readonly y: number;
+    readonly opacity: number;
+    /** Mirrored within the part's own full frame. */
+    readonly flipX: boolean;
+    readonly flipY: boolean;
+}
+/**
+ * Everything to draw for one animation frame, bottom to top: the base frame (z 0) and its
+ * layers sorted by z, ties keeping the base first and then list order.
+ */
+export declare function partsOf(file: Pick<SpriteBuddyFile, 'frames'>, entry: AnimationFrameDef): Part[];
+/** Box around every part of an animation frame, relative to the sprite's origin. */
+export declare function boundsOf(parts: readonly Part[]): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};

package/dist/resolve.js

@@ -0,0 +1,50 @@
+/**
+ * Everything to draw for one animation frame, bottom to top: the base frame (z 0) and its
+ * layers sorted by z, ties keeping the base first and then list order.
+ */
+export function partsOf(file, entry) {
+    const base = file.frames[entry.frame];
+    const left = -base.pivot.x + entry.offset.x;
+    const top = -base.pivot.y + entry.offset.y;
+    const stack = [
+        {
+            z: 0,
+            part: {
+                frame: base,
+                index: entry.frame,
+                x: left,
+                y: top,
+                opacity: 1,
+                flipX: false,
+                flipY: false,
+            },
+        },
+        ...entry.layers.map((l) => ({
+            z: l.z,
+            part: {
+                frame: file.frames[l.frame],
+                index: l.frame,
+                x: left + l.x,
+                y: top + l.y,
+                opacity: l.opacity,
+                flipX: l.flipX,
+                flipY: l.flipY,
+            },
+        })),
+    ];
+    return stack
+        .map((s, order) => ({ ...s, order }))
+        .sort((a, b) => a.z - b.z || a.order - b.order)
+        .map((s) => s.part);
+}
+/** Box around every part of an animation frame, relative to the sprite's origin. */
+export function boundsOf(parts) {
+    if (parts.length === 0)
+        return { x: 0, y: 0, w: 0, h: 0 };
+    const x0 = Math.min(...parts.map((p) => p.x));
+    const y0 = Math.min(...parts.map((p) => p.y));
+    const x1 = Math.max(...parts.map((p) => p.x + p.frame.width));
+    const y1 = Math.max(...parts.map((p) => p.y + p.frame.height));
+    return { x: x0, y: y0, w: x1 - x0, h: y1 - y0 };
+}
+//# sourceMappingURL=resolve.js.map

package/dist/resolve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.js","sourceRoot":"","sources":["../src/resolve.ts"],"names":[],"mappings":"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"}

package/dist/timing.d.ts

@@ -0,0 +1,33 @@
+import type { AnimationDef } from './types.js';
+export interface PlaybackPosition {
+    /** Index into the animation's `frames`, or -1 for an animation with no frames. */
+    readonly index: number;
+    /** True once a `once` animation has reached its end (it then holds the last frame). */
+    readonly done: boolean;
+}
+/**
+ * The frame indices one cycle visits. `pingpong` plays forward then back without repeating the
+ * end frames (0 1 2 3 2 1), so with two frames or fewer it is the same as `loop`.
+ */
+export declare function cycleOrder(anim: Pick<AnimationDef, 'frames' | 'loop'>): number[];
+/** Length of one cycle in ms (forward and back for `pingpong`). */
+export declare function cycleDuration(anim: Pick<AnimationDef, 'frames' | 'loop'>): number;
+/**
+ * Which frame shows `time` ms after the animation starts. A frame shows from its start time up
+ * to, not including, its end; `loop` and `pingpong` repeat forever, `once` holds the last frame.
+ * Negative times count as 0.
+ */
+export declare function frameAt(anim: Pick<AnimationDef, 'frames' | 'loop'>, time: number): PlaybackPosition;
+/** An event fired by an animation frame: its name and the frame's index in the animation. */
+export interface FrameEvent {
+    readonly name: string;
+    readonly index: number;
+}
+/**
+ * The events of every frame that starts showing after `from` ms and up to and including `to` ms,
+ * in the order they start. A frame that starts exactly at `from` was already counted, so calling
+ * this with each tick's old and new time fires every event once, even when a long tick skips
+ * past short frames. A ping-pong cycle fires a frame's events each time it shows. One call fires
+ * at most one cycle's worth, so a game that was paused for a minute doesn't get a burst.
+ */
+export declare function eventsBetween(anim: Pick<AnimationDef, 'frames' | 'loop'>, from: number, to: number): FrameEvent[];

package/dist/timing.js

@@ -0,0 +1,74 @@
+/**
+ * The frame indices one cycle visits. `pingpong` plays forward then back without repeating the
+ * end frames (0 1 2 3 2 1), so with two frames or fewer it is the same as `loop`.
+ */
+export function cycleOrder(anim) {
+    const forward = anim.frames.map((_, i) => i);
+    if (anim.loop !== 'pingpong' || forward.length <= 2)
+        return forward;
+    return [...forward, ...forward.slice(1, -1).reverse()];
+}
+/** Length of one cycle in ms (forward and back for `pingpong`). */
+export function cycleDuration(anim) {
+    return cycleOrder(anim).reduce((t, i) => t + anim.frames[i].duration, 0);
+}
+/**
+ * Which frame shows `time` ms after the animation starts. A frame shows from its start time up
+ * to, not including, its end; `loop` and `pingpong` repeat forever, `once` holds the last frame.
+ * Negative times count as 0.
+ */
+export function frameAt(anim, time) {
+    const order = cycleOrder(anim);
+    if (order.length === 0)
+        return { index: -1, done: true };
+    const total = cycleDuration(anim);
+    const t = Math.max(0, time);
+    if (anim.loop === 'once' && t >= total)
+        return { index: order[order.length - 1], done: true };
+    let rest = t % total;
+    for (const i of order) {
+        rest -= anim.frames[i].duration;
+        if (rest < 0)
+            return { index: i, done: false };
+    }
+    /* v8 ignore next */
+    return { index: order[order.length - 1], done: false };
+}
+/**
+ * The events of every frame that starts showing after `from` ms and up to and including `to` ms,
+ * in the order they start. A frame that starts exactly at `from` was already counted, so calling
+ * this with each tick's old and new time fires every event once, even when a long tick skips
+ * past short frames. A ping-pong cycle fires a frame's events each time it shows. One call fires
+ * at most one cycle's worth, so a game that was paused for a minute doesn't get a burst.
+ */
+export function eventsBetween(anim, from, to) {
+    const order = cycleOrder(anim);
+    if (order.length === 0 || to <= from)
+        return [];
+    if (!anim.frames.some((f) => f.events.length > 0))
+        return [];
+    const total = cycleDuration(anim);
+    const starts = [];
+    let t = 0;
+    for (const i of order) {
+        starts.push(t);
+        t += anim.frames[i].duration;
+    }
+    const crossed = [];
+    const once = anim.loop === 'once';
+    const first = once
+        ? 0
+        : Math.max(Math.floor(Math.max(0, from) / total), Math.floor(to / total) - 1);
+    const last = once ? 0 : Math.floor(to / total);
+    for (let cycle = first; cycle <= last; cycle++) {
+        order.forEach((index, k) => {
+            const at = cycle * total + starts[k];
+            if (at > from && at <= to)
+                crossed.push(index);
+        });
+    }
+    return crossed
+        .slice(-order.length)
+        .flatMap((index) => anim.frames[index].events.map((name) => ({ name, index })));
+}
+//# sourceMappingURL=timing.js.map

package/dist/timing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timing.js","sourceRoot":"","sources":["../src/timing.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,84 @@
+/** `format` of every SpriteBuddy runtime file. */
+export declare const FORMAT = "spritebuddy-animations";
+/** The newest runtime file version this package reads. */
+export declare const VERSION = 3;
+export type LoopMode = 'loop' | 'pingpong' | 'once';
+/**
+ * One frame on the sheet. Coordinates are pixels with y down, as in the image.
+ *
+ * - `rect` is where the frame's pixels sit on the sheet, at their upright size. A `rotated`
+ *   frame is stored turned 90° clockwise, so it covers `rect.h` columns and `rect.w` rows
+ *   starting at `rect.x, rect.y` (TexturePacker's rule).
+ * - `trim` is set when transparent edges were cut off: the cut pixels' place inside the full
+ *   frame and the full frame's size. Without it the full frame is `rect`.
+ * - `pivot` is in full-frame pixels; the frame hangs from it (feet, usually).
+ */
+export interface FrameDef {
+    readonly name: string;
+    readonly rect: Rect;
+    readonly pivot: Point;
+    readonly rotated: boolean;
+    readonly trim: Trim | null;
+    /** Full (untrimmed) frame size. */
+    readonly width: number;
+    readonly height: number;
+}
+export interface Rect {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+export interface Point {
+    readonly x: number;
+    readonly y: number;
+}
+export interface Trim {
+    /** Where the trimmed pixels start inside the full frame. */
+    readonly x: number;
+    readonly y: number;
+}
+/** An extra frame drawn with an animation frame: a weapon, an effect, a shadow. */
+export interface LayerDef {
+    /** Index into {@link SpriteBuddyFile.frames}. */
+    readonly frame: number;
+    /** Top-left of the layer's full frame, relative to the base frame's full top-left. */
+    readonly x: number;
+    readonly y: number;
+    /** Draw order: the base frame is 0, higher draws on top, ties keep list order. */
+    readonly z: number;
+    readonly opacity: number;
+    readonly flipX: boolean;
+    readonly flipY: boolean;
+}
+export interface AnimationFrameDef {
+    /** Index into {@link SpriteBuddyFile.frames}. */
+    readonly frame: number;
+    /** Display time in ms. */
+    readonly duration: number;
+    /** Nudge in pixels from where the pivot puts the frame (+x right, +y down). */
+    readonly offset: Point;
+    readonly layers: readonly LayerDef[];
+    /**
+     * Names fired when this frame starts showing, such as `"hit"` on the frame a sword lands or
+     * `"step"` on a footstep. Empty for most frames.
+     */
+    readonly events: readonly string[];
+}
+export interface AnimationDef {
+    readonly name: string;
+    readonly loop: LoopMode;
+    readonly frames: readonly AnimationFrameDef[];
+}
+/** A parsed runtime file, with every default filled in. */
+export interface SpriteBuddyFile {
+    readonly version: number;
+    /** The sheet image's file name, relative to the runtime file. */
+    readonly image: string;
+    readonly width: number;
+    readonly height: number;
+    /** Scale the sheet was exported at (1 = original pixels). */
+    readonly scale: number;
+    readonly frames: readonly FrameDef[];
+    readonly animations: readonly AnimationDef[];
+}

package/dist/types.js

@@ -0,0 +1,5 @@
+/** `format` of every SpriteBuddy runtime file. */
+export const FORMAT = 'spritebuddy-animations';
+/** The newest runtime file version this package reads. */
+export const VERSION = 3;
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,MAAM,CAAC,MAAM,MAAM,GAAG,wBAAwB,CAAC;AAC/C,0DAA0D;AAC1D,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@spritebuddy/core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Reads SpriteBuddy animation files and works out what to draw at any moment. No dependencies, any engine.",
+  "license": "ISC",
+  "author": "Patrick Hammond",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Patrick-Hammond/spritebuddy-runtimes.git",
+    "directory": "packages/core"
+  },
+  "keywords": [
+    "spritebuddy",
+    "sprites",
+    "spritesheet",
+    "animation",
+    "gamedev"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./schema.json": "./schema.json"
+  },
+  "files": [
+    "dist",
+    "schema.json"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node -e \"require('node:fs').copyFileSync('../../schema/spritebuddy-animations.v3.schema.json', 'schema.json')\"",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/schema.json

@@ -0,0 +1,161 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/Patrick-Hammond/spritebuddy-runtimes/blob/main/schema/spritebuddy-animations.v3.schema.json",
+  "title": "SpriteBuddy animations, version 3",
+  "description": "A spritesheet's frames and animations, with per-frame timing, offsets and layers. Coordinates are sheet pixels with y down; times are milliseconds. See docs/format.md.",
+  "type": "object",
+  "required": ["format", "version", "image", "size", "frames"],
+  "properties": {
+    "format": { "const": "spritebuddy-animations" },
+    "version": { "const": 3 },
+    "image": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The sheet image, relative to this file."
+    },
+    "size": {
+      "$ref": "#/$defs/size",
+      "description": "Sheet size in pixels: [width, height]."
+    },
+    "scale": {
+      "type": "number",
+      "exclusiveMinimum": 0,
+      "default": 1,
+      "description": "Scale the sheet was exported at. Informational: every coordinate in the file is already in sheet pixels."
+    },
+    "frames": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/frame" }
+    },
+    "animations": {
+      "type": "array",
+      "default": [],
+      "items": { "$ref": "#/$defs/animation" }
+    }
+  },
+  "$defs": {
+    "int": { "type": "integer" },
+    "count": { "type": "integer", "minimum": 0 },
+    "positive": { "type": "integer", "minimum": 1 },
+    "size": {
+      "type": "array",
+      "prefixItems": [{ "$ref": "#/$defs/positive" }, { "$ref": "#/$defs/positive" }],
+      "minItems": 2,
+      "maxItems": 2
+    },
+    "point": {
+      "type": "array",
+      "prefixItems": [{ "type": "number" }, { "type": "number" }],
+      "minItems": 2,
+      "maxItems": 2
+    },
+    "offset": {
+      "type": "array",
+      "prefixItems": [{ "$ref": "#/$defs/int" }, { "$ref": "#/$defs/int" }],
+      "minItems": 2,
+      "maxItems": 2
+    },
+    "frame": {
+      "type": "object",
+      "required": ["name", "rect"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "rect": {
+          "type": "array",
+          "description": "[x, y, w, h]: where the pixels sit on the sheet, at their upright size.",
+          "prefixItems": [
+            { "$ref": "#/$defs/count" },
+            { "$ref": "#/$defs/count" },
+            { "$ref": "#/$defs/positive" },
+            { "$ref": "#/$defs/positive" }
+          ],
+          "minItems": 4,
+          "maxItems": 4
+        },
+        "pivot": {
+          "$ref": "#/$defs/point",
+          "description": "[x, y] in full-frame pixels. Defaults to the bottom centre."
+        },
+        "rotated": {
+          "type": "boolean",
+          "default": false,
+          "description": "Stored turned 90° clockwise: covers h columns and w rows on the sheet."
+        },
+        "trim": {
+          "type": "array",
+          "description": "[x, y, fullWidth, fullHeight]: transparent edges were cut off; the pixels start at x, y inside a full frame of this size.",
+          "prefixItems": [
+            { "$ref": "#/$defs/count" },
+            { "$ref": "#/$defs/count" },
+            { "$ref": "#/$defs/positive" },
+            { "$ref": "#/$defs/positive" }
+          ],
+          "minItems": 4,
+          "maxItems": 4
+        }
+      }
+    },
+    "layer": {
+      "type": "object",
+      "required": ["frame"],
+      "properties": {
+        "frame": { "$ref": "#/$defs/count", "description": "Index into frames." },
+        "x": {
+          "$ref": "#/$defs/int",
+          "default": 0,
+          "description": "Layer's full-frame left, from the base frame's left."
+        },
+        "y": {
+          "$ref": "#/$defs/int",
+          "default": 0,
+          "description": "Layer's full-frame top, from the base frame's top."
+        },
+        "z": {
+          "$ref": "#/$defs/int",
+          "default": 1,
+          "description": "Draw order; the base frame is 0."
+        },
+        "opacity": { "type": "number", "minimum": 0, "maximum": 1, "default": 1 },
+        "flipX": { "type": "boolean", "default": false },
+        "flipY": { "type": "boolean", "default": false }
+      }
+    },
+    "animationFrame": {
+      "oneOf": [
+        { "$ref": "#/$defs/count", "description": "A frame index, with the animation's duration." },
+        {
+          "type": "object",
+          "required": ["frame"],
+          "properties": {
+            "frame": { "$ref": "#/$defs/count" },
+            "duration": { "$ref": "#/$defs/positive", "description": "Milliseconds." },
+            "offset": {
+              "$ref": "#/$defs/offset",
+              "description": "[x, y] nudge from where the pivot puts the frame; +x right, +y down."
+            },
+            "layers": { "type": "array", "items": { "$ref": "#/$defs/layer" } },
+            "events": {
+              "type": "array",
+              "description": "Names fired when this frame starts showing, such as \"hit\" or \"step\".",
+              "items": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      ]
+    },
+    "animation": {
+      "type": "object",
+      "required": ["name", "frames"],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "loop": { "enum": ["loop", "pingpong", "once"], "default": "loop" },
+        "duration": {
+          "$ref": "#/$defs/positive",
+          "default": 100,
+          "description": "Milliseconds for frames that don't give their own."
+        },
+        "frames": { "type": "array", "items": { "$ref": "#/$defs/animationFrame" } }
+      }
+    }
+  }
+}