Concepts

Sprite presents a character document through a host-installed renderer, so a game or app can show an animated avatar without writing its own rendering layer. The host chooses local characters, renderer adapters, network origins, and asset limits. Each mounted player owns its current source and presentation lifetime.

Core concepts

A character document has version: 1, a name, a renderer name, optional controls and poster, and renderer-specific data. The shared schema validates that envelope. The selected adapter validates its own data. A source is either a document URL or { local: "key" } for a character installed by the host.

createSprite creates a stable host service. The host supplies local characters, renderer loaders, and asset policy. A player selects one source and receives activity, expression, appearance, and render-style updates without replacing its host element. The React Sprite owns one player and disposes it when it unmounts. The imperative player exposes set, pause, subscribe, and asynchronous dispose.

A presentation may carry performance, renderer data for that presentation such as a scene. Sprite passes it unchanged to the native renderer and compares it by identity: an equal value in a new object applies again. A host must keep the reference stable (for example with useMemo), or the renderer’s set runs on every render. A renderer reports its own progress through reportProgress on its context. The ready state carries the latest value as progress, and the report is ignored once the selection closes. Sprite never reads either value. The selected adapter owns both schemas, as it owns document.data.

renderStyle applies one of the built-in SVG filters: plain, pencil, manga, riso, halftone, blueprint, crt, or watercolor. Each player owns its filter instance. Animated styles pause when the player is paused, is offscreen, the page is hidden, or reduced motion is requested.

Remote documents and nested assets pass through one reader. The host sets allowed origins, the maximum bytes per response, total bytes per selection, and request count. Local characters need no remote asset policy. Video uses the configured video renderer and reads clip assets through that same path.

The React Sprite takes src, optional activity, expression, appearance, renderStyle and performance, plus ordinary attributes for its host div. Pass paused to suspend it and onState to observe player states. A direct service prop overrides SpriteProvider; one of them is required.

For frame-driven playback, wrap an App in <AnimationTimeProvider timeMs={frame / fps * 1000}> from the same React entry. Every nested Sprite and Parakeet AgentHead inherits that clock, including memoized children. An explicit timeMs prop overrides it (zero included). Controlled players stay paused between seeks; omitting the provider time restores their ordinary live or paused behavior. No provider means no clock override.

Saved avatars

@fungi.computer/sprite/avatar defines the v1 descriptor: v, character, appearance, expression and renderStyle. avatarEnvelopeSchema checks only that envelope. Use createAvatarSchema(catalog) or parseAvatar(data, catalog) to also validate the selected character’s controls and expressions. Sprite Zdog supplies a validator bound to its built-in catalog.

Decorative drawings

mountInkDrawing(host, { art, palette, ...options }) from ./ink paints traced art with Canvas 2D. The palette is a callback; call the returned redraw() after a theme change and destroy() when the host leaves.

mountMycelium(host, { pixi, palette, ...options }) from ./mycelium returns a Promise for a growing field with pulse() and destroy(). The host supplies Pixi 8 and the palette. Both drawings respect reduced motion and release their canvas and observers through destroy().