# packages/core/src/features/sprites/model.ts This is the source snapshot used to build these API details. [View this revision on GitHub](https://github.com/benlesh/pibbl/blob/272a94aaf62e0bd6ad8726a4c607a76a9ec44ca1/packages/core/src/features/sprites/model.ts#L60). [Back to reference](/reference/functions/sprite-sheets/)
1 import { defineAnimation } from '../../lib/animation/definition.js';
2 import type { PibblAnimationDefinition } from '../../lib/animation/types.js';
3 
4 /** Pixel rectangle within an atlas page or original frame. See {@link SpriteFrame}. */
5 export interface SpriteRectangle { /** Horizontal pixel offset. */ readonly x: number; /** Vertical pixel offset. */ readonly y: number; /** Width in pixels. */ readonly width: number; /** Height in pixels. */ readonly height: number }
6 /** Normalized frame information returned by a format adapter. See {@link SpriteFrame}. */
7 export interface SpriteFrameData {
8   /** Unique frame name in this sheet. */ readonly name: string;
9   /** Zero-based atlas page index; defaults to zero. */ readonly page?: number;
10   /** Packed rectangle within the atlas page. */ readonly rect: SpriteRectangle;
11   /** Original frame dimensions before trimming. */ readonly sourceSize?: Readonly<{ /** Width in pixels. */ width: number; /** Height in pixels. */ height: number }>;
12   /** Trimmed content offset within the original frame. */ readonly trim?: Readonly<{ /** Horizontal pixel offset. */ x: number; /** Vertical pixel offset. */ y: number }>;
13   /** Whether the packed rectangle is rotated clockwise. */ readonly rotated?: boolean;
14 }
15 /** One normalized timed frame reference. Durations are milliseconds. See {@link SpriteFrame}. */
16 export interface SpriteAnimationFrameData { /** Name of the frame used by this animation step. */ readonly frame: string; /** Positive duration of the animation step in milliseconds. */ readonly duration: number }
17 /** Adapter result. Image paths resolve relative to the metadata URL. See {@link SpriteFrame}. */
18 export interface SpriteSheetData {
19   /** Atlas image URLs, relative to the metadata URL. */ readonly images: readonly string[];
20   /** Normalized frame records for this sheet. */ readonly frames: readonly SpriteFrameData[];
21   /** Named sequences of timed frame references. */ readonly animations?: Readonly<Record<string, readonly SpriteAnimationFrameData[]>>;
22 }
23 /** Import adapter; loaders invoke this directly without a format registry. See {@link SpriteFrame}. */
24 export interface SpriteSheetFormat { /** Convert decoded metadata to normalized sheet data.
25  * @param data - Parsed atlas JSON.
26  * @returns Validated adapter data for loading the sheet.
27  */ readonly parse: (data: unknown) => SpriteSheetData }
28 
29 export interface FrameRecord extends SpriteFrameData { readonly image: HTMLImageElement; readonly owner: { disposed: boolean } }
30 const records = new WeakMap<SpriteFrame, FrameRecord>();
31 /** Immutable atlas frame. Obtain frames from loadSpriteSheet; images belong to the sheet. See {@link SpriteFrame}. */
32 export class SpriteFrame {
33   private readonly identity = true;
34   /** Original logical frame width, before transparent borders were trimmed.
35    * @returns Width in logical pixels.
36    */
37   get width(): number { return frameRecord(this).sourceSize?.width ?? frameRecord(this).rect.width; }
38   /** Original logical frame height, before transparent borders were trimmed.
39    * @returns Height in logical pixels.
40    */
41   get height(): number { return frameRecord(this).sourceSize?.height ?? frameRecord(this).rect.height; }
42   /** Stable name supplied by the atlas or numeric grid index.
43    * @returns The frame name.
44    */
45   get name(): string { void this.identity; return frameRecord(this).name; }
46 }
47 export function makeFrame(record: FrameRecord): SpriteFrame {
48   const frame = new SpriteFrame(); records.set(frame, record); Object.freeze(frame); return frame;
49 }
50 export function frameRecord(frame: SpriteFrame): FrameRecord {
51   const record = records.get(frame);
52   if (!record) throw new TypeError('Expected a SpriteFrame from loadSpriteSheet.');
53   if (record.owner.disposed) throw new Error('Sprite sheet has been disposed.');
54   return record;
55 }
56 /** Author a finite discrete animation using FPS or explicit positive millisecond durations. See {@link SpriteFrame}.
57  * @param options - Frames with a shared FPS or individual millisecond durations.
58  * @returns A seekable discrete animation definition.
59  */
60 export function defineSpriteAnimation(options: {
61   readonly frames: readonly SpriteFrame[];
62   readonly fps: number;
63 } | {
64   readonly frames: readonly Readonly<{ frame: SpriteFrame; duration: number }>[];
65 }): PibblAnimationDefinition<SpriteFrame> {
66   if (!options.frames.length) throw new RangeError('Sprite animation requires at least one frame.');
67   if ('fps' in options && (!Number.isFinite(options.fps) || options.fps <= 0)) throw new RangeError('Sprite FPS must be finite and positive.');
68   const entries = options.frames.map(item => {
69     const entry = 'fps' in options ? { frame: item as SpriteFrame, duration: 1000 / options.fps } : item as { frame: SpriteFrame; duration: number };
70     frameRecord(entry.frame);
71     if (!Number.isFinite(entry.duration) || entry.duration <= 0) throw new RangeError('Sprite duration must be finite and positive.');
72     return { ...entry };
73   });
74   let duration = 0;
75   const ends = entries.map(entry => duration += entry.duration);
76   return defineAnimation({ duration, sample: ({ localTime }) => {
77     let low = 0, high = ends.length - 1;
78     while (low < high) { const mid = (low + high) >>> 1; if (localTime < ends[mid]) high = mid; else low = mid + 1; }
79     return entries[low].frame;
80   } });
81 }
82
## Documentation version Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.