author

Import

Import

import * as api from "@fungi.computer/sprite-zdog/author";

Exports

Kind	Export	Description
Ttype alias	SceneNode	An opaque node in a renderer-neutral Sprite scene.
Ttype alias	Point	A point in Sprite scene space.
Ttype alias	BezierStep	One cubic Bezier path segment.
Ttype alias	PathStep	One renderer-neutral shape path segment.
Ttype alias	Transform	Optional translation, rotation, or scale coordinates.
Ttype alias	SceneNodeOptions	Shared renderer-neutral options for one scene node.
Ttype alias	PathOptions	Renderer-neutral options for a freeform shape.
Ttype alias	EllipseOptions	Renderer-neutral options for an ellipse.
Ttype alias	HemisphereOptions	Renderer-neutral options for a hemisphere.
Ttype alias	CylinderOptions	Renderer-neutral options for a cylinder.
Ttype alias	SceneBuilder	The complete renderer-neutral scene authoring surface.
Ttype alias	MotionSpec	A named motion applied while presenting a Sprite.
Ttype alias	StandardActivity	The standard presentation activity names accepted by every Sprite.
Ttype alias	StateGeometry	Variant selections applied to one expression or activity.
Ttype alias	MouthCycleStep	One timed mouth state in a speaking cycle.
Ttype alias	ActivitySpec	Presentation behavior associated with an activity.
Ttype alias	ExpressionSpec	Variant and motion behavior associated with an expression.
Ttype alias	BuildResult	The root and named variants produced by one author build.
Ttype alias	AuthorContext	Renderer-neutral capabilities available while authoring a Sprite.
Ttype alias	SpriteDefinitionInput	Input accepted by the Sprite authoring seam.
Ttype alias	SpriteDefinition	An authored Sprite definition preserving the author’s input shape.
Ttype alias	SpriteCheckResult	A compact receipt describing one already-authored Sprite definition.
constconstant	STANDARD_ACTIVITIES	The standard presentation activities every Sprite understands.
fnfunction	defineSprite()	Validate and freeze one renderer-neutral Sprite definition.
fnfunction	check()	Return a compact, machine-readable receipt for an already authored definition.

SceneNodeTtype alias

Signature

type SceneNode = object;

An opaque node in a renderer-neutral Sprite scene.

Properties

[sceneNodeBrand]

Signature

readonly [sceneNodeBrand]: true;

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

---

PointTtype alias

Signature

type Point = object;

A point in Sprite scene space.

Properties

x

Signature

readonly x: number;

Horizontal scene coordinate.

y

Signature

readonly y: number;

Vertical scene coordinate.

z?

Signature

readonly optional z?: number;

Optional depth coordinate.

---

BezierStepTtype alias

Signature

type BezierStep = object;

One cubic Bezier path segment.

Properties

bezier

Signature

readonly bezier: readonly [Point, Point, Point];

Two control points followed by the segment endpoint.

---

PathStepTtype alias

Signature

type PathStep = Point | BezierStep;

One renderer-neutral shape path segment.

---

TransformTtype alias

Signature

type Transform = object;

Optional translation, rotation, or scale coordinates.

Properties

x?

Signature

readonly optional x?: number;

Optional horizontal component.

y?

Signature

readonly optional y?: number;

Optional vertical component.

z?

Signature

readonly optional z?: number;

Optional depth component.

---

SceneNodeOptionsTtype alias

Signature

type SceneNodeOptions = object;

Shared renderer-neutral options for one scene node.

Properties

name?

Signature

readonly optional name?: string;

Definition-local name used by authored references.

parent?

Signature

readonly optional parent?: SceneNode;

Parent node in the same definition.

x?

Signature

readonly optional x?: number;

Horizontal translation that takes precedence over translate.x.

y?

Signature

readonly optional y?: number;

Vertical translation that takes precedence over translate.y.

z?

Signature

readonly optional z?: number;

Depth translation that takes precedence over translate.z.

translate?

Signature

readonly optional translate?: Transform;

Translation components not supplied by the direct coordinates.

rotate?

Signature

readonly optional rotate?: Transform;

Rotation around each scene axis, in radians.

scale?

Signature

readonly optional scale?: Transform;

Scale applied along each scene axis.

visible?

Signature

readonly optional visible?: boolean;

Whether the node participates in rendering.

color?

Signature

readonly optional color?: string;

Literal paint or an opaque reference returned by color.

stroke?

Signature

readonly optional stroke?: number | false;

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

fill?

Signature

readonly optional fill?: boolean;

backface?

Signature

readonly optional backface?: string;

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

frontFace?

Signature

readonly optional frontFace?: string;

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

updateSort?

Signature

readonly optional updateSort?: boolean;

Whether supported primitives update child depth ordering.

---

PathOptionsTtype alias

Signature

type PathOptions = object & SceneNodeOptions;

Renderer-neutral options for a freeform shape.

Type Declaration

Name	Type	Description
path?	readonly PathStep[]	Ordered points and cubic Bezier segments in the path.
closed?	boolean	Whether the renderer closes the path.

---

EllipseOptionsTtype alias

Signature

type EllipseOptions = object & SceneNodeOptions;

Renderer-neutral options for an ellipse.

Type Declaration

Name	Type	Description
width	number	Horizontal diameter.
height	number	Vertical diameter.

---

HemisphereOptionsTtype alias

Signature

type HemisphereOptions = object & SceneNodeOptions;

Renderer-neutral options for a hemisphere.

Type Declaration

Name	Type	Description
diameter	number	Diameter of the hemisphere’s base.

---

CylinderOptionsTtype alias

Signature

type CylinderOptions = object & SceneNodeOptions;

Renderer-neutral options for a cylinder.

Type Declaration

Name	Type	Description
diameter	number	Diameter of the cylinder’s circular faces.
length	number	Distance between the cylinder’s faces.

---

SceneBuilderTtype alias

Signature

type SceneBuilder = object;

The complete renderer-neutral scene authoring surface.

Methods

group()

Signature

group(options?): SceneNode;

Create a grouping node.

Parameters

Parameter	Type
options?	SceneNodeOptions

Returns

SceneNode

path()

Signature

path(options): SceneNode;

Create a freeform path node.

Parameters

Parameter	Type
options	PathOptions

Returns

SceneNode

ellipse()

Signature

ellipse(options): SceneNode;

Create an ellipse node.

Parameters

Parameter	Type
options	EllipseOptions

Returns

SceneNode

hemisphere()

Signature

hemisphere(options): SceneNode;

Create a hemisphere node.

Parameters

Parameter	Type
options	HemisphereOptions

Returns

SceneNode

cylinder()

Signature

cylinder(options): SceneNode;

Create a cylinder node.

Parameters

Parameter	Type
options	CylinderOptions

Returns

SceneNode

---

MotionSpecTtype alias

Signature

type MotionSpec = object;

A named motion applied while presenting a Sprite.

Properties

target

Signature

readonly target: string;

Name of the scene node targeted by the motion.

translate?

Signature

readonly optional translate?: Transform;

Authored translation change.

rotate?

Signature

readonly optional rotate?: Transform;

Authored rotation change.

durationMs?

Signature

readonly optional durationMs?: number;

Duration of one motion pass in milliseconds.

repeat?

Signature

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

Repetition mode for the motion.

---

StandardActivityTtype alias

Signature

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

The standard presentation activity names accepted by every Sprite.

---

StateGeometryTtype alias

Signature

type StateGeometry = object;

Variant selections applied to one expression or activity.

Properties

expression?

Signature

readonly optional expression?: string;

Expression selected by an activity.

eyes?

Signature

readonly optional eyes?: string;

Value selected from the eyes variant channel.

mouth?

Signature

readonly optional mouth?: string;

Value selected from the mouth variant channel.

blush?

Signature

readonly optional blush?: number;

Normalized blush intensity.

---

MouthCycleStepTtype alias

Signature

type MouthCycleStep = object;

One timed mouth state in a speaking cycle.

Properties

durationMs

Signature

readonly durationMs: number;

Time spent in this mouth state, in milliseconds.

mouth

Signature

readonly mouth: "base" | "open";

Mouth state shown during the step.

---

ActivitySpecTtype alias

Signature

type ActivitySpec = object;

Presentation behavior associated with an activity.

Properties

motion?

Signature

readonly optional motion?: MotionSpec;

Optional motion authored for the activity.

geometry?

Signature

readonly optional geometry?: StateGeometry;

Optional geometry selections authored for the activity.

mouseInfluence?

Signature

readonly optional mouseInfluence?: number;

Authored pointer-influence strength.

mouthCycle?

Signature

readonly optional mouthCycle?: readonly MouthCycleStep[];

Ordered timed mouth states for the activity.

---

ExpressionSpecTtype alias

Signature

type ExpressionSpec = object;

Variant and motion behavior associated with an expression.

Properties

variants?

Signature

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

Fixed value selected for each variant channel.

variantChoices?

Signature

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

Candidate values authored for each variant channel.

blush?

Signature

readonly optional blush?: number;

Normalized blush intensity.

motion?

Signature

readonly optional motion?: MotionSpec;

Optional motion authored for the expression.

---

BuildResultTtype alias

Signature

type BuildResult = object;

The root and named variants produced by one author build.

Properties

root

Signature

readonly root: SceneNode;

Root node of the rendered scene tree.

variants?

Signature

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

Definition-local nodes grouped by variant channel and value.

---

AuthorContextTtype alias

Signature

type AuthorContext = object;

Renderer-neutral capabilities available while authoring a Sprite.

Properties

scene

Signature

readonly scene: SceneBuilder;

Scene builder valid only for the duration of build.

color

Signature

readonly color: (name) => string;

Create an opaque reference to an own palette slot.

Parameters

Parameter	Type
name	string

Returns

string

---

SpriteDefinitionInputTtype alias

Signature

type SpriteDefinitionInput = object;

Input accepted by the Sprite authoring seam.

Properties

apiVersion

Signature

readonly apiVersion: 1;

Version of the authoring contract used by this definition.

name

Signature

readonly name: string;

Human-readable Sprite definition name.

palette

Signature

readonly palette: Record<string, string>;

Named default paints available to the author callback.

build

Signature

readonly build: (context) => BuildResult;

Construct the renderer-neutral scene and its named variants.

Parameters

Parameter	Type
context	AuthorContext

Returns

BuildResult

expressions

Signature

readonly expressions: Record<string, ExpressionSpec>;

Named expression specifications; at least one is required.

activities?

Signature

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

Optional custom activity specifications.

defaultPresentation?

Signature

readonly optional defaultPresentation?: object;

Initial activity and expression selected when mounted.

activity?

Signature

readonly optional activity?: string;

Standard or custom activity selected initially.

expression?

Signature

readonly optional expression?: string;

Declared expression selected initially.

---

SpriteDefinitionTtype alias

Signature

type SpriteDefinition<Input> = Readonly<Input>;

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

Type Parameters

Type Parameter	Default type
Input extends SpriteDefinitionInput	SpriteDefinitionInput

---

SpriteCheckResultTtype alias

Signature

type SpriteCheckResult = object;

A compact receipt describing one already-authored Sprite definition.

Properties

valid

Signature

readonly valid: true;

Whether the definition has completed author-time validation.

name

Signature

readonly name: string;

Human-readable name of the checked definition.

nodeCount

Signature

readonly nodeCount: number;

Number of scene nodes reachable from the definition root.

expressions

Signature

readonly expressions: readonly string[];

Expression names in author insertion order.

activities

Signature

readonly activities: readonly string[];

Standard activities followed by unique custom activities in author order.

variants

Signature

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

Variant values by channel, preserving author insertion order.

STANDARD_ACTIVITIESconstconstant

Signature

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

The standard presentation activities every Sprite understands.

defineSprite()fnfunction

Signature

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

Validate and freeze one renderer-neutral Sprite definition.

Type Parameters

Type Parameter
Input extends SpriteDefinitionInput

Parameters

Parameter	Type
input	Input

Returns

SpriteDefinition<Input>

---

check()fnfunction

Signature

function check(definition): SpriteCheckResult;

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

Parameters

Parameter	Type
definition	SpriteDefinition

Returns

SpriteCheckResult

References

toCharacter

Re-exports toCharacter