Sprite types

Read as Markdown

SpriteFrame

Opaque immutable handle with a stable name and original logical width/height. Its sheet owns image data.

SpriteRectangle

Source pixel rectangle with x, y, width, and height.

SpriteFrameData

Normalized adapter record: name, optional page, packed rectangle, original size, trim offset, and rotation flag.

SpriteAnimationFrameData

Normalized frame name and positive duration in milliseconds.

SpriteSheetData

Adapter result containing relative image URLs, frame records, and optional named timed clips.

SpriteSheetFormat

Explicit parser object with parse(unknown) returning normalized sheet data.

SpriteSheet

Shared decoded images exposed through readonly frame and animation maps, with idempotent disposal.

SpriteGrid

Positive integer frameWidth/frameHeight and optional nonnegative integer margin/spacing, measured in pixels.

SpriteProps

Frame, sampling, normalized anchor, flipX/flipY, and ordinary drawing event props. Declared primitive inputs accept signals.

SpriteStyle

Logical width, height, opacity, and ordinary Pibbl system style. Default size is the frame’s original untrimmed size.

API details from source

SpriteProps

Drawing inputs; frame also accepts a signal through Pibbl’s declared primitive inputs. See SpriteFrame.

interface SpriteProps extends ImageProps

Related API: SpriteProps, ImageProps.

View source — packages/core/src/features/sprites/sprite.ts:8

Properties and methods

frame

readonly frame: SpriteFrame

Related API: SpriteFrame.

Atlas frame to draw; its sheet must remain undisposed.

View source — packages/core/src/features/sprites/sprite.ts:9

sampling (optional)

readonly sampling?: "linear" | "nearest" | undefined

Image interpolation; defaults to linear.

View source — packages/core/src/features/sprites/sprite.ts:10

anchor (optional)

readonly anchor?: Readonly<{ x: number; y: number; }> | undefined

Normalized origin within the original frame, defaulting to the top-left.

View source — packages/core/src/features/sprites/sprite.ts:11

flipX (optional)

readonly flipX?: boolean | undefined

Mirror the frame horizontally.

View source — packages/core/src/features/sprites/sprite.ts:12

flipY (optional)

readonly flipY?: boolean | undefined

Mirror the frame vertically.

View source — packages/core/src/features/sprites/sprite.ts:13

pointerEvents (optional)

readonly pointerEvents?: PibblPointerEvents | undefined

Related API: PibblPointerEvents.

Whether this content participates in pointer targeting. See PibblPointerEvents.

View source — packages/core/src/lib/events/types.ts:126

keyboardFocusable (optional)

readonly keyboardFocusable?: boolean | undefined

Whether the target may receive keyboard focus. See PibblEventFocusOptions.

View source — packages/core/src/lib/events/types.ts:137

keyboardNavigationBounds (optional)

readonly keyboardNavigationBounds?: Readonly<LayoutBox> | undefined

Related API: LayoutBox.

Logical rectangle used for directional keyboard navigation. See LayoutBox.

View source — packages/core/src/lib/events/types.ts:139

physics (optional)

readonly physics?: PibblPhysicsAttachment2D | undefined

Related API: PibblPhysicsAttachment2D.

View source — packages/core/src/features/physics/lib/2d/types.ts:321

SpriteStyle

Logical size overrides; omitted dimensions use the original untrimmed frame size. See SpriteFrame.

interface SpriteStyle extends SystemStyle

Related API: SpriteStyle, SystemStyle.

View source — packages/core/src/features/sprites/sprite.ts:16

Properties and methods

width (optional)

readonly width?: number | undefined

View source — packages/core/src/features/sprites/sprite.ts:16

height (optional)

readonly height?: number | undefined

View source — packages/core/src/features/sprites/sprite.ts:16

opacity (optional)

readonly opacity?: number | undefined

Related API: opacity.

View source — packages/core/src/features/sprites/sprite.ts:16

transition (optional)

transition?: PibblTransitionBinding | undefined

Related API: PibblTransitionBinding.

Visibility-transition binding applied to this primitive and its captured descendants. See SystemStyle.

View source — packages/core/src/lib/types.ts:69

custom (optional)

custom?: unknown

Application-defined style payload passed through the runtime. See SystemStyle.

View source — packages/core/src/lib/types.ts:71

filter (optional)

filter?: PibblFilter | readonly PibblFilter[] | undefined

Related API: PibblFilter.

Ordered pixel-only filters applied to the receiving primitive and its descendants. See PibblFilter.

View source — packages/core/src/lib/types.ts:76

SpriteSheet

Shared decoded atlas and immutable frames/clips. Dispose after all consumers unmount. See SpriteFrame.

interface SpriteSheet

Related API: SpriteSheet.

View source — packages/core/src/features/sprites/loader.ts:4

Properties and methods

frames

readonly frames: Readonly<Record<string | number, SpriteFrame>>

Related API: SpriteFrame.

Frames indexed by atlas name or numeric grid index.

View source — packages/core/src/features/sprites/loader.ts:5

animations

readonly animations: Readonly<Record<string, PibblAnimationDefinition<SpriteFrame>>>

Related API: PibblAnimationDefinition, SpriteFrame.

Named, seekable animation definitions from the atlas.

View source — packages/core/src/features/sprites/loader.ts:6

dispose

readonly dispose: () => void

Release decoded images; unmount every consumer before calling.

View source — packages/core/src/features/sprites/loader.ts:7

SpriteGrid

Dimensions of a regular grid, in image pixels. See SpriteFrame.

interface SpriteGrid

Related API: SpriteGrid.

View source — packages/core/src/features/sprites/loader.ts:10

Properties and methods

frameWidth

readonly frameWidth: number

View source — packages/core/src/features/sprites/loader.ts:10

frameHeight

readonly frameHeight: number

View source — packages/core/src/features/sprites/loader.ts:10

margin (optional)

readonly margin?: number | undefined

View source — packages/core/src/features/sprites/loader.ts:10

spacing (optional)

readonly spacing?: number | undefined

View source — packages/core/src/features/sprites/loader.ts:10

SpriteFrame

Immutable atlas frame. Obtain frames from loadSpriteSheet; images belong to the sheet. See SpriteFrame.

class SpriteFrame

Related API: SpriteFrame.

View source — packages/core/src/features/sprites/model.ts:32

Properties and methods

width

readonly width: number

Original logical frame width, before transparent borders were trimmed.

Returns

Width in logical pixels.

View source — packages/core/src/features/sprites/model.ts:37

height

readonly height: number

Original logical frame height, before transparent borders were trimmed.

Returns

Height in logical pixels.

View source — packages/core/src/features/sprites/model.ts:41

name

readonly name: string

Stable name supplied by the atlas or numeric grid index.

Returns

The frame name.

View source — packages/core/src/features/sprites/model.ts:45

SpriteRectangle

Pixel rectangle within an atlas page or original frame. See SpriteFrame.

interface SpriteRectangle

Related API: SpriteRectangle.

View source — packages/core/src/features/sprites/model.ts:5

Properties and methods

readonly x: number

View source — packages/core/src/features/sprites/model.ts:5

readonly y: number

View source — packages/core/src/features/sprites/model.ts:5

width

readonly width: number

View source — packages/core/src/features/sprites/model.ts:5

height

readonly height: number

View source — packages/core/src/features/sprites/model.ts:5

SpriteFrameData

Normalized frame information returned by a format adapter. See SpriteFrame.

interface SpriteFrameData

Related API: SpriteFrameData.

View source — packages/core/src/features/sprites/model.ts:7

Properties and methods

name

readonly name: string

Unique frame name in this sheet.

View source — packages/core/src/features/sprites/model.ts:8

page (optional)

readonly page?: number | undefined

Zero-based atlas page index; defaults to zero.

View source — packages/core/src/features/sprites/model.ts:9

rect

readonly rect: SpriteRectangle

Related API: SpriteRectangle.

Packed rectangle within the atlas page.

View source — packages/core/src/features/sprites/model.ts:10

sourceSize (optional)

readonly sourceSize?: Readonly<{ width: number; height: number; }> | undefined

Original frame dimensions before trimming.

View source — packages/core/src/features/sprites/model.ts:11

trim (optional)

readonly trim?: Readonly<{ x: number; y: number; }> | undefined

Trimmed content offset within the original frame.

View source — packages/core/src/features/sprites/model.ts:12

rotated (optional)

readonly rotated?: boolean | undefined

Whether the packed rectangle is rotated clockwise.

View source — packages/core/src/features/sprites/model.ts:13

SpriteAnimationFrameData

One normalized timed frame reference. Durations are milliseconds. See SpriteFrame.

interface SpriteAnimationFrameData

Related API: SpriteAnimationFrameData.

View source — packages/core/src/features/sprites/model.ts:16

Properties and methods

frame

readonly frame: string

View source — packages/core/src/features/sprites/model.ts:16

duration

readonly duration: number

View source — packages/core/src/features/sprites/model.ts:16

SpriteSheetData

Adapter result. Image paths resolve relative to the metadata URL. See SpriteFrame.

interface SpriteSheetData

Related API: SpriteSheetData.

View source — packages/core/src/features/sprites/model.ts:18

Properties and methods

images

readonly images: readonly string[]

Atlas image URLs, relative to the metadata URL.

View source — packages/core/src/features/sprites/model.ts:19

frames

readonly frames: readonly SpriteFrameData[]

Related API: SpriteFrameData.

Normalized frame records for this sheet.

View source — packages/core/src/features/sprites/model.ts:20

animations (optional)

readonly animations?: Readonly<Record<string, readonly SpriteAnimationFrameData[]>> | undefined

Related API: SpriteAnimationFrameData.

Named sequences of timed frame references.

View source — packages/core/src/features/sprites/model.ts:21

SpriteSheetFormat

Import adapter; loaders invoke this directly without a format registry. See SpriteFrame.

interface SpriteSheetFormat

Related API: SpriteSheetFormat.

View source — packages/core/src/features/sprites/model.ts:24

Properties and methods

parse

readonly parse: (data: unknown) => SpriteSheetData

Related API: SpriteSheetData.

View source — packages/core/src/features/sprites/model.ts:27

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

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

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