# Sprite sheets and clips

## 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

`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

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

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](/guides/sprites/) and
[sprite types](/reference/types/sprites/).

Related types: [SpriteSheet](/reference/types/sprites/#spritesheet), [SpriteGrid](/reference/types/sprites/#spritegrid), [SpriteSheetFormat](/reference/types/sprites/#spritesheetformat), [SpriteFrame](/reference/types/sprites/#spriteframe).

## API details from source

<span id="api-loadSpriteSheet"></span>

### loadSpriteSheet

Load a grid image or metadata through an explicitly supplied import adapter. See SpriteFrame.

```ts
loadSpriteSheet: (url: string, options: { readonly grid: SpriteGrid; } | { readonly format: SpriteSheetFormat; }) => Promise<SpriteSheet>
```

Related API: [loadSpriteSheet](/reference/functions/sprite-sheets/), [SpriteGrid](/reference/types/sprites/#spritegrid), [SpriteSheetFormat](/reference/types/sprites/#spritesheetformat), [SpriteSheet](/reference/types/sprites/#spritesheet).

#### Parameters

- **`url`** — Grid image URL or atlas metadata URL.

- **`options`** — Grid dimensions or an explicit metadata format adapter.

#### Returns

A decoded sprite sheet with explicit disposal ownership.

[View source — packages/core/src/features/sprites/loader.ts:16](/source/packages/core/src/features/sprites/loader-ts/#L16)

<span id="api-defineSpriteAnimation"></span>

### defineSpriteAnimation

Author a finite discrete animation using FPS or explicit positive millisecond durations. See SpriteFrame.

```ts
defineSpriteAnimation: (options: { readonly frames: readonly SpriteFrame[]; readonly fps: number; } | { readonly frames: readonly Readonly<{ frame: SpriteFrame; duration: number; }>[]; }) => PibblAnimationDefinition<SpriteFrame>
```

Related API: [defineSpriteAnimation](/reference/functions/sprite-sheets/), [SpriteFrame](/reference/types/sprites/#spriteframe), [PibblAnimationDefinition](/reference/types/canvas-runtime/#pibblanimationdefinition).

#### Parameters

- **`options`** — Frames with a shared FPS or individual millisecond durations.

#### Returns

A seekable discrete animation definition.

[View source — packages/core/src/features/sprites/model.ts:60](/source/packages/core/src/features/sprites/model-ts/#L60)

<span id="api-aseprite"></span>

### aseprite

Import Aseprite JSON hash or array exports, including frame tags and millisecond timing. See SpriteSheetFormat.

```ts
aseprite: () => SpriteSheetFormat
```

Related API: [aseprite](/reference/functions/sprite-sheets/), [SpriteSheetFormat](/reference/types/sprites/#spritesheetformat).

#### Returns

An explicit atlas metadata adapter.

[View source — packages/core/src/features/sprites/formats/aseprite.ts:5](/source/packages/core/src/features/sprites/formats/aseprite-ts/#L5)

<span id="api-texturePacker"></span>

### texturePacker

Import TexturePacker JSON hash/array rectangles with clockwise packed rotation and trim offsets. See SpriteSheetFormat.

```ts
texturePacker: () => SpriteSheetFormat
```

Related API: [texturePacker](/reference/functions/sprite-sheets/), [SpriteSheetFormat](/reference/types/sprites/#spritesheetformat).

#### Returns

An explicit atlas metadata adapter.

[View source — packages/core/src/features/sprites/formats/texture-packer.ts:5](/source/packages/core/src/features/sprites/formats/texture-packer-ts/#L5)

## Implementation guidance for agents

Read the [Authoring, signals, and lifecycle companion](/agents/topics/lifecycle/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [Animated sprite atlas](/minimal-examples/sprites/atlas/): Generate a two-frame atlas, animate a shared sheet, and dispose it after unmounting. [Plain source](/minimal/sprites/atlas.tsx)
- [Sprite format adapters](/minimal-examples/sprites/formats/): Compare normalized Aseprite, TexturePacker, and application-owned atlas metadata. [Plain source](/minimal/sprites/formats.ts)
## Documentation version

Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.