author

Type Aliases

SceneNode

SceneNode = object

An opaque node in a renderer-neutral Sprite scene.

Properties

[sceneNodeBrand]

readonly [sceneNodeBrand]: true

Nominal marker that keeps renderer details out of the author surface.

Point

Point = object

A point in Sprite scene space.

Properties

x

readonly x: number

Horizontal scene coordinate.

y

readonly y: number

Vertical scene coordinate.

z?

readonly optional z?: number

Optional depth coordinate.

BezierStep

BezierStep = object

One cubic Bezier path segment.

Properties

bezier

readonly bezier: readonly [Point, Point, Point]

Two control points followed by the segment endpoint.

PathStep

PathStep = Point | BezierStep

One renderer-neutral shape path segment.

Transform

Transform = object

Optional translation, rotation, or scale coordinates.

Properties

x?

readonly optional x?: number

Optional horizontal component.

y?

readonly optional y?: number

Optional vertical component.

z?

readonly optional z?: number

Optional depth component.

SceneNodeOptions

SceneNodeOptions = object

Shared renderer-neutral options for one scene node.

Properties

name?

readonly optional name?: string

Definition-local name used by authored references.

parent?

readonly optional parent?: SceneNode

Parent node in the same definition.

x?

readonly optional x?: number

Horizontal translation that takes precedence over translate.x.

y?

readonly optional y?: number

Vertical translation that takes precedence over translate.y.

z?

readonly optional z?: number

Depth translation that takes precedence over translate.z.

translate?

readonly optional translate?: Transform

Translation components not supplied by the direct coordinates.

rotate?

readonly optional rotate?: Transform

Rotation around each scene axis, in radians.

scale?

readonly optional scale?: Transform

Scale applied along each scene axis.

visible?

readonly optional visible?: boolean

Whether the node participates in rendering.

color?

readonly optional color?: string

Literal paint or an opaque reference returned by color.

stroke?

readonly optional stroke?: number | false

A false stroke keeps a solid primitive edge-free, as in Zdog fills.

fill?

readonly optional fill?: boolean

backface?

readonly optional backface?: string

Optional rear/forward surface palette slots for 3D solids.

frontFace?

readonly optional frontFace?: string

Paint used for a primitive’s front face when supported.

updateSort?

readonly optional updateSort?: boolean

Whether supported primitives update child depth ordering.

PathOptions

PathOptions = object & SceneNodeOptions

Renderer-neutral options for a freeform shape.

Type Declaration

path?

readonly optional path?: readonly PathStep[]

Ordered points and cubic Bezier segments in the path.

closed?

readonly optional closed?: boolean

Whether the renderer closes the path.

EllipseOptions

EllipseOptions = object & SceneNodeOptions

Renderer-neutral options for an ellipse.

Type Declaration

width

readonly width: number

Horizontal diameter.

height

readonly height: number

Vertical diameter.

HemisphereOptions

HemisphereOptions = object & SceneNodeOptions

Renderer-neutral options for a hemisphere.

Type Declaration

diameter

readonly diameter: number

Diameter of the hemisphere’s base.

CylinderOptions

CylinderOptions = object & SceneNodeOptions

Renderer-neutral options for a cylinder.

Type Declaration

diameter

readonly diameter: number

Diameter of the cylinder’s circular faces.

length

readonly length: number

Distance between the cylinder’s faces.

SceneBuilder

SceneBuilder = object

The complete renderer-neutral scene authoring surface.

Methods

group()

group(options?): SceneNode

Create a grouping node.

Parameters

options?

SceneNodeOptions

Returns

SceneNode

path()

path(options): SceneNode

Create a freeform path node.

Parameters

options

PathOptions

Returns

SceneNode

ellipse()

ellipse(options): SceneNode

Create an ellipse node.

Parameters

options

EllipseOptions

Returns

SceneNode

hemisphere()

hemisphere(options): SceneNode

Create a hemisphere node.

Parameters

options

HemisphereOptions

Returns

SceneNode

cylinder()

cylinder(options): SceneNode

Create a cylinder node.

Parameters

options

CylinderOptions

Returns

SceneNode

MotionSpec

MotionSpec = object

A named motion applied while presenting a Sprite.

Properties

target

readonly target: string

Name of the scene node targeted by the motion.

translate?

readonly optional translate?: Transform

Authored translation change.

rotate?

readonly optional rotate?: Transform

Authored rotation change.

durationMs?

readonly optional durationMs?: number

Duration of one motion pass in milliseconds.

repeat?

readonly optional repeat?: "none" | "loop" | "yoyo"

Repetition mode for the motion.

StandardActivity

StandardActivity = "idle" | "listening" | "processing" | "speaking" | "thinking" | "error"

The standard presentation activity names accepted by every Sprite.

StateGeometry

StateGeometry = object

Variant selections applied to one expression or activity.

Properties

expression?

readonly optional expression?: string

Expression selected by an activity.

eyes?

readonly optional eyes?: string

Value selected from the eyes variant channel.

mouth?

readonly optional mouth?: string

Value selected from the mouth variant channel.

blush?

readonly optional blush?: number

Normalized blush intensity.

MouthCycleStep

MouthCycleStep = object

One timed mouth state in a speaking cycle.

Properties

durationMs

readonly durationMs: number

Time spent in this mouth state, in milliseconds.

mouth

readonly mouth: "base" | "open"

Mouth state shown during the step.

ActivitySpec

ActivitySpec = object

Presentation behavior associated with an activity.

Properties

motion?

readonly optional motion?: MotionSpec

Optional motion authored for the activity.

geometry?

readonly optional geometry?: StateGeometry

Optional geometry selections authored for the activity.

mouseInfluence?

readonly optional mouseInfluence?: number

Authored pointer-influence strength.

mouthCycle?

readonly optional mouthCycle?: readonly MouthCycleStep[]

Ordered timed mouth states for the activity.

ExpressionSpec

ExpressionSpec = object

Variant and motion behavior associated with an expression.

Properties

variants?

readonly optional variants?: Record<string, string>>

Fixed value selected for each variant channel.

variantChoices?

readonly optional variantChoices?: Record<string, readonly string[]>

Candidate values authored for each variant channel.

blush?

readonly optional blush?: number

Normalized blush intensity.

motion?

readonly optional motion?: MotionSpec

Optional motion authored for the expression.

BuildResult

BuildResult = object

The root and named variants produced by one author build.

Properties

root

readonly root: SceneNode

Root node of the rendered scene tree.

variants?

readonly optional variants?: Record<string, Record<string, SceneNode>>>>

Definition-local nodes grouped by variant channel and value.

AuthorContext

AuthorContext = object

Renderer-neutral capabilities available while authoring a Sprite.

Properties

scene

readonly scene: SceneBuilder

Scene builder valid only for the duration of build.

color

readonly color: (name) => string

Create an opaque reference to an own palette slot.

Parameters

name

string

Returns

string

SpriteDefinitionInput

SpriteDefinitionInput = object

Input accepted by the Sprite authoring seam.

Properties

apiVersion

readonly apiVersion: 1

Version of the authoring contract used by this definition.

name

readonly name: string

Human-readable Sprite definition name.

palette

readonly palette: Record<string, string>>

Named default paints available to the author callback.

build

readonly build: (context) => BuildResult

Construct the renderer-neutral scene and its named variants.

Parameters

context

AuthorContext

Returns

BuildResult

expressions

readonly expressions: Record<string, ExpressionSpec>>

Named expression specifications; at least one is required.

activities?

readonly optional activities?: Record<string, ActivitySpec>>

Optional custom activity specifications.

defaultPresentation?

readonly optional defaultPresentation?: object

Initial activity and expression selected when mounted.

activity?

readonly optional activity?: string

Standard or custom activity selected initially.

expression?

readonly optional expression?: string

Declared expression selected initially.

SpriteDefinition

SpriteDefinition<Input> > = Readonly<Input>>

An authored Sprite definition preserving the author’s input shape.

Type Parameters

Input

Input extends SpriteDefinitionInput = SpriteDefinitionInput

SpriteCheckResult

SpriteCheckResult = object

A compact receipt describing one already-authored Sprite definition.

Properties

valid

readonly valid: true

Whether the definition has completed author-time validation.

name

readonly name: string

Human-readable name of the checked definition.

nodeCount

readonly nodeCount: number

Number of scene nodes reachable from the definition root.

expressions

readonly expressions: readonly string[]

Expression names in author insertion order.

activities

readonly activities: readonly string[]

Standard activities followed by unique custom activities in author order.

variants

readonly variants: Readonly<Record<string, readonly string[]>>

Variant values by channel, preserving author insertion order.

Variables

STANDARD_ACTIVITIES

const STANDARD_ACTIVITIES: readonly ["idle", "listening", "processing", "speaking", "thinking", "error"]

The standard presentation activities every Sprite understands.

Functions

defineSprite()

defineSprite<Input>>(input): SpriteDefinition<Input>>

Validate and freeze one renderer-neutral Sprite definition.

Type Parameters

Input

Input extends SpriteDefinitionInput

Parameters

input

Input

Returns

SpriteDefinition<Input>

check()

check(definition): SpriteCheckResult

Return a compact, machine-readable receipt for an already authored definition.

Parameters

definition

SpriteDefinition

Returns

SpriteCheckResult

References

toCharacter

Re-exports toCharacter