Sprite sheets and clips
loadSpriteSheet
Section titled “loadSpriteSheet”Import from @pibbl/core/sprites. loadSpriteSheet(url, { grid }) loads a regular
image grid; loadSpriteSheet(url, { format }) loads metadata through a supplied
adapter. It returns a promise for a sheet with readonly frames and animations
maps, and idempotent dispose(). Failures release partially loaded image resources.
Unmount consumers before disposal. Loading uses browser image decoding.
defineSpriteAnimation
Section titled “defineSpriteAnimation”defineSpriteAnimation({ frames, fps }) or
defineSpriteAnimation({ frames: [{ frame, duration }, ...] }) creates an ordinary
seekable animation definition. FPS and millisecond durations must be finite and
positive. The frame list must be nonempty. Loop with repeat; control playback
with the existing animation API.
aseprite
Section titled “aseprite”Import aseprite from @pibbl/core/sprites/formats/aseprite and pass
{ format: aseprite() }. Supports JSON hash/array frames and frame tags, including
forward, reverse, and ping-pong ordering. Images resolve relative to metadata.
texturePacker
Section titled “texturePacker”Import texturePacker from @pibbl/core/sprites/formats/texture-packer and pass
{ format: texturePacker() }. Supports JSON hash/array rectangles, trim offsets,
and clockwise packed rotation. Linked multipacks and scales other than 1 are
explicitly rejected. Author clips with defineSpriteAnimation.
Adapters are separate imports; importing a grid loader does not import either parser. See the sprite guide and sprite types.
Related types: SpriteSheet, SpriteGrid, SpriteSheetFormat, SpriteFrame.
API details from source
Section titled “API details from source”
loadSpriteSheet
Section titled “loadSpriteSheet”Load a grid image or metadata through an explicitly supplied import adapter. See SpriteFrame.
loadSpriteSheet: (url: string, options: { readonly grid: SpriteGrid; } | { readonly format: SpriteSheetFormat; }) => Promise<SpriteSheet>Related API: loadSpriteSheet, SpriteGrid, SpriteSheetFormat, SpriteSheet.
Parameters
Section titled “Parameters”-
url— Grid image URL or atlas metadata URL. -
options— Grid dimensions or an explicit metadata format adapter.
Returns
Section titled “Returns”A decoded sprite sheet with explicit disposal ownership.
View source — packages/core/src/features/sprites/loader.ts:16
defineSpriteAnimation
Section titled “defineSpriteAnimation”Author a finite discrete animation using FPS or explicit positive millisecond durations. See SpriteFrame.
defineSpriteAnimation: (options: { readonly frames: readonly SpriteFrame[]; readonly fps: number; } | { readonly frames: readonly Readonly<{ frame: SpriteFrame; duration: number; }>[]; }) => PibblAnimationDefinition<SpriteFrame>Related API: defineSpriteAnimation, SpriteFrame, PibblAnimationDefinition.
Parameters
Section titled “Parameters”options— Frames with a shared FPS or individual millisecond durations.
Returns
Section titled “Returns”A seekable discrete animation definition.
View source — packages/core/src/features/sprites/model.ts:60
aseprite
Section titled “aseprite”Import Aseprite JSON hash or array exports, including frame tags and millisecond timing. See SpriteSheetFormat.
aseprite: () => SpriteSheetFormatRelated API: aseprite, SpriteSheetFormat.
Returns
Section titled “Returns”An explicit atlas metadata adapter.
View source — packages/core/src/features/sprites/formats/aseprite.ts:5
texturePacker
Section titled “texturePacker”Import TexturePacker JSON hash/array rectangles with clockwise packed rotation and trim offsets. See SpriteSheetFormat.
texturePacker: () => SpriteSheetFormatRelated API: texturePacker, SpriteSheetFormat.
Returns
Section titled “Returns”An explicit atlas metadata adapter.
View source — packages/core/src/features/sprites/formats/texture-packer.ts:5
Implementation guidance for agents
Section titled “Implementation guidance for agents”Read the Authoring, signals, and lifecycle companion for ownership, adaptation, failure modes, and verification. Agent start provides the version-selection workflow.
Complete minimal examples
Section titled “Complete minimal examples”- Animated sprite atlas: Generate a two-frame atlas, animate a shared sheet, and dispose it after unmounting. Plain source
- Sprite format adapters: Compare normalized Aseprite, TexturePacker, and application-owned atlas metadata. Plain source
Documentation version
Section titled “Documentation version”Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.