Skip to content
Sprite Swarm
API reference

scene

Import

Section titled “Import”
Import
import * as api from "@fungi.computer/sprite-swarm/scene";

Exports

Section titled “Exports”
Kind Export Description
type alias Models Model references resolved by the host from the catalog.
type alias Cue A decoded cue.
type alias Performance A decoded performance.
type alias Progress Decoded progress.
type alias Scene A decoded scene.
type alias SceneBeat One beat of a scene: a caption and the elements it shows.
type alias SceneElement A primitive, label, path or catalog model within one beat.
type alias Vec3 Three numbers: a position, a rotation or a scale.
type alias ElementMake What an element is made of; a change of make is a crossfade, not a tween.
type alias ElementState One element fully resolved for one instant of the scene.
type alias SceneFrame What a scene shows at one moment: its beat, caption and elements.
type alias BeatPosition A beat’s index, and the seconds since that beat started.
constant cueSchema Where the swarm is told to be: a beat, and whether it plays on from it.
constant modelsSchema Catalog model references, with their declared height in metres.
constant performanceSchema A scene and the cue that moves the swarm through it.
constant progressSchema What the swarm reports back: the beat shown and whether it is playing.
constant decodePerformance Decode a performance a host passed in; extra keys are refused.
constant decodeProgress Decode the progress the swarm reported.
constant sceneSchema The scene an Agent writes: beats of named shapes, paths, labels and catalog models.
constant decodeScene Decode untrusted scene input; extra keys are refused, not dropped.
function performanceOf() Encode a scene selection and its cue as Sprite’s plain JSON payload.
function transitionSeconds() Seconds a beat spends tweening in from the previous one.
function sceneDuration() Seconds from the scene start to the end of its last beat.
function beatStart() Seconds from the scene start to the start of index.
function resolveBeat() Resolve one beat’s elements with their defaults, keyed by name.
function ease() Ease in and out, so beats settle rather than stop.
function beatAt() Which beat is showing seconds into the scene, and how far into it.
function frameAt() The scene seconds after it started. The first beat grows in from an empty stage; each later beat tweens from the one before; the last holds.
function keyFrame() A beat’s settled key state, shown when motion is reduced.

Modelstype alias

Section titled “Models”
Signature
type Models = Schema.Schema.Type<typeof modelsSchema>;

Model references resolved by the host from the catalog.

Cuetype alias

Section titled “Cue”
Signature
type Cue = Schema.Schema.Type<typeof cueSchema>;

A decoded cue.

Performancetype alias

Section titled “Performance”
Signature
type Performance = Schema.Schema.Type<typeof performanceSchema>;

A decoded performance.

Progresstype alias

Section titled “Progress”
Signature
type Progress = Schema.Schema.Type<typeof progressSchema>;

Decoded progress.

Scenetype alias

Section titled “Scene”
Signature
type Scene = Schema.Schema.Type<typeof sceneSchema>;

A decoded scene.

SceneBeattype alias

Section titled “SceneBeat”
Signature
type SceneBeat = Scene["beats"][number];

One beat of a scene: a caption and the elements it shows.

SceneElementtype alias

Section titled “SceneElement”
Signature
type SceneElement = SceneBeat["elements"][number];

A primitive, label, path or catalog model within one beat.

Vec3type alias

Section titled “Vec3”
Signature
type Vec3 = readonly [number, number, number];

Three numbers: a position, a rotation or a scale.

ElementMaketype alias

Section titled “ElementMake”
Signature
type ElementMake =
  | Readonly<{
      kind: "shape";
      primitive: Extract<
        SceneElement,
        {
          kind: "shape";
        }
      >["primitive"];
    }>
  | Readonly<{
      kind: "path";
      d: string;
      style: "fill" | "stroke";
      strokeWidth: number;
    }>
  | Readonly<{
      kind: "label";
      text: string;
    }>
  | Readonly<{
      kind: "model";
      model: string;
    }>;

What an element is made of; a change of make is a crossfade, not a tween.

ElementStatetype alias

Section titled “ElementState”
Signature
type ElementState = Readonly<{
  key: string;
  name: string;
  make: ElementMake;
  position: Vec3;
  rotation: Vec3;
  scale: Vec3;
  color: Vec3;
  opacity: number;
}>;

One element fully resolved for one instant of the scene.

SceneFrametype alias

Section titled “SceneFrame”
Signature
type SceneFrame = Readonly<{
  beat: number;
  caption: string | null;
  elements: readonly ElementState[];
}>;

What a scene shows at one moment: its beat, caption and elements.

BeatPositiontype alias

Section titled “BeatPosition”
Signature
type BeatPosition = Readonly<{
  index: number;
  local: number;
}>;

A beat’s index, and the seconds since that beat started.

cueSchemaconstant

Section titled “cueSchema”
Signature
const cueSchema: Struct<{
  beat: Number;
  playing: Boolean;
}>;

Where the swarm is told to be: a beat, and whether it plays on from it.

modelsSchemaconstant

Section titled “modelsSchema”
Signature
const modelsSchema: $Record<
  String,
  Struct<{
    file: String;
    height: Number;
  }>
>;

Catalog model references, with their declared height in metres.

performanceSchemaconstant

Section titled “performanceSchema”
Signature
const performanceSchema: Struct<{
  sceneId: Number;
  scene: Struct<{
     title: optionalKey<String>;
     background: optionalKey<String>;
     beats: $Array<Struct<{
        duration: Number;
        caption: optionalKey<String>;
        elements: $Array<Union<readonly [Struct<...>, Struct<...>, Struct<...>, Struct<...>]>>;
     }>>;
  }>;
  models: $Record<String, Struct<{
     file: String;
     height: Number;
  }>>;
  cue: Struct<{
     beat: Number;
     playing: Boolean;
  }>;
}>;

A scene and the cue that moves the swarm through it.

progressSchemaconstant

Section titled “progressSchema”
Signature
const progressSchema: Struct<{
  sceneId: Number;
  beat: Number;
  caption: NullOr<String>;
  playing: Boolean;
  unavailable: $Array<String>;
}>;

What the swarm reports back: the beat shown and whether it is playing.

decodePerformanceconstant

Section titled “decodePerformance”
Signature
const decodePerformance: (
  input,
  options?,
) => Result<
  {
    sceneId: number;
    scene: {
      title?: string;
      background?: string;
      beats: readonly object[];
    };
    models: {
      [key: string]: object;
    };
    cue: {
      beat: number;
      playing: boolean;
    };
  },
  SchemaError
>;

Decode a performance a host passed in; extra keys are refused.

Parameters

Section titled “Parameters”
Parameter Type
input unknown
options? ParseOptions

Returns

Section titled “Returns”

Result<{ sceneId: number; scene: { title?: string; background?: string; beats: readonly object[]; }; models: { [key: string]: object; }; cue: { beat: number; playing: boolean; }; }, SchemaError>

decodeProgressconstant

Section titled “decodeProgress”
Signature
const decodeProgress: (
  input,
  options?,
) => Result<
  {
    sceneId: number;
    beat: number;
    caption: string | null;
    playing: boolean;
    unavailable: readonly string[];
  },
  SchemaError
>;

Decode the progress the swarm reported.

Parameters

Section titled “Parameters”
Parameter Type
input unknown
options? ParseOptions

Returns

Section titled “Returns”

Result<{ sceneId: number; beat: number; caption: string | null; playing: boolean; unavailable: readonly string[]; }, SchemaError>

sceneSchemaconstant

Section titled “sceneSchema”
Signature
const sceneSchema: Struct<{
  title: optionalKey<String>;
  background: optionalKey<String>;
  beats: $Array<Struct<{
     duration: Number;
     caption: optionalKey<String>;
     elements: $Array<Union<readonly [Struct<{
        name: String;
        position: optionalKey<...>;
        rotation: optionalKey<...>;
        scale: optionalKey<...>;
        color: optionalKey<...>;
        opacity: optionalKey<...>;
        kind: Literal<...>;
        primitive: Literals<...>;
      }>, Struct<{
        name: String;
        position: optionalKey<...>;
        rotation: optionalKey<...>;
        scale: optionalKey<...>;
        color: optionalKey<...>;
        opacity: optionalKey<...>;
        kind: Literal<...>;
        d: String;
        style: optionalKey<...>;
        strokeWidth: optionalKey<...>;
      }>, Struct<{
        name: String;
        position: optionalKey<...>;
        rotation: optionalKey<...>;
        scale: optionalKey<...>;
        color: optionalKey<...>;
        opacity: optionalKey<...>;
        kind: Literal<...>;
        text: String;
      }>, Struct<{
        name: String;
        position: optionalKey<...>;
        rotation: optionalKey<...>;
        scale: optionalKey<...>;
        color: optionalKey<...>;
        opacity: optionalKey<...>;
        kind: Literal<...>;
        model: String;
     }>]>>;
  }>>;
}>;

The scene an Agent writes: beats of named shapes, paths, labels and catalog models.

decodeSceneconstant

Section titled “decodeScene”
Signature
const decodeScene: (
  input,
  options?,
) => Result<
  {
    title?: string;
    background?: string;
    beats: readonly object[];
  },
  SchemaError
>;

Decode untrusted scene input; extra keys are refused, not dropped.

Parameters

Section titled “Parameters”
Parameter Type
input unknown
options? ParseOptions

Returns

Section titled “Returns”

Result<{ title?: string; background?: string; beats: readonly object[]; }, SchemaError>

performanceOf()function

Section titled “performanceOf()”
Signature
function performanceOf(sceneId, scene, cue, models): JSONType;

Encode a scene selection and its cue as Sprite’s plain JSON payload.

Parameters

Section titled “Parameters”
Parameter Type
sceneId number
scene { title?: string; background?: string; beats: readonly object[]; }
scene.title? string
scene.background? string
scene.beats readonly object[]
cue { beat: number; playing: boolean; }
cue.beat number
cue.playing boolean
models { [key: string]: object; }

Returns

Section titled “Returns”

JSONType

transitionSeconds()function

Section titled “transitionSeconds()”
Signature
function transitionSeconds(beat): number;

Seconds a beat spends tweening in from the previous one.

Parameters

Section titled “Parameters”
Parameter Type Description
beat { duration: number; caption?: string; elements: readonly ( | { name: string; position?: readonly [number, number, number]; rotation?: readonly [number, number, number]; scale?: readonly [number, number, number]; color?: string; opacity?: number; kind: "shape"; primitive: "plane" | "box" | "sphere" | "cylinder" | "cone" | "torus"; } | { name: string; position?: readonly [number, number, number]; rotation?: readonly [number, number, number]; scale?: readonly [number, number, number]; color?: string; opacity?: number; kind: "path"; d: string; style?: "fill" | "stroke"; strokeWidth?: number; } | { name: string; position?: readonly [number, number, number]; rotation?: readonly [number, number, number]; scale?: readonly [number, number, number]; color?: string; opacity?: number; kind: "label"; text: string; } | { name: string; position?: readonly [number, number, number]; rotation?: readonly [number, number, number]; scale?: readonly [number, number, number]; color?: string; opacity?: number; kind: "model"; model: string; })[]; } -
beat.duration number Seconds this beat holds, its entrance tween included.
beat.caption? string -
beat.elements readonly ( | { name: string; position?: readonly [number, number, number]; rotation?: readonly [number, number, number]; scale?: readonly [number, number, number]; color?: string; opacity?: number; kind: "shape"; primitive: "plane" | "box" | "sphere" | "cylinder" | "cone" | "torus"; } | { name: string; position?: readonly [number, number, number]; rotation?: readonly [number, number, number]; scale?: readonly [number, number, number]; color?: string; opacity?: number; kind: "path"; d: string; style?: "fill" | "stroke"; strokeWidth?: number; } | { name: string; position?: readonly [number, number, number]; rotation?: readonly [number, number, number]; scale?: readonly [number, number, number]; color?: string; opacity?: number; kind: "label"; text: string; } | { name: string; position?: readonly [number, number, number]; rotation?: readonly [number, number, number]; scale?: readonly [number, number, number]; color?: string; opacity?: number; kind: "model"; model: string; })[] -

Returns

Section titled “Returns”

number

sceneDuration()function

Section titled “sceneDuration()”
Signature
function sceneDuration(scene): number;

Seconds from the scene start to the end of its last beat.

Parameters

Section titled “Parameters”
Parameter Type
scene { title?: string; background?: string; beats: readonly object[]; }
scene.title? string
scene.background? string
scene.beats readonly object[]

Returns

Section titled “Returns”

number

beatStart()function

Section titled “beatStart()”
Signature
function beatStart(scene, index): number;

Seconds from the scene start to the start of index.

Parameters

Section titled “Parameters”
Parameter Type
scene { title?: string; background?: string; beats: readonly object[]; }
scene.title? string
scene.background? string
scene.beats readonly object[]
index number

Returns

Section titled “Returns”

number

resolveBeat()function

Section titled “resolveBeat()”
Signature
function resolveBeat(beat): ReadonlyMap<
  string,
  Readonly<{
    key: string;
    name: string;
    make: ElementMake;
    position: Vec3;
    rotation: Vec3;
    scale: Vec3;
    color: Vec3;
    opacity: number;
  }>
>;

Resolve one beat’s elements with their defaults, keyed by name.

Parameters

Section titled “Parameters”
Parameter Type Description
beat { duration: number; caption?: string; elements: readonly ( | { name: string; position?: readonly [number, number, number]; rotation?: readonly [number, number, number]; scale?: readonly [number, number, number]; color?: string; opacity?: number; kind: "shape"; primitive: "plane" | "box" | "sphere" | "cylinder" | "cone" | "torus"; } | { name: string; position?: readonly [number, number, number]; rotation?: readonly [number, number, number]; scale?: readonly [number, number, number]; color?: string; opacity?: number; kind: "path"; d: string; style?: "fill" | "stroke"; strokeWidth?: number; } | { name: string; position?: readonly [number, number, number]; rotation?: readonly [number, number, number]; scale?: readonly [number, number, number]; color?: string; opacity?: number; kind: "label"; text: string; } | { name: string; position?: readonly [number, number, number]; rotation?: readonly [number, number, number]; scale?: readonly [number, number, number]; color?: string; opacity?: number; kind: "model"; model: string; })[]; } -
beat.duration number Seconds this beat holds, its entrance tween included.
beat.caption? string -
beat.elements readonly ( | { name: string; position?: readonly [number, number, number]; rotation?: readonly [number, number, number]; scale?: readonly [number, number, number]; color?: string; opacity?: number; kind: "shape"; primitive: "plane" | "box" | "sphere" | "cylinder" | "cone" | "torus"; } | { name: string; position?: readonly [number, number, number]; rotation?: readonly [number, number, number]; scale?: readonly [number, number, number]; color?: string; opacity?: number; kind: "path"; d: string; style?: "fill" | "stroke"; strokeWidth?: number; } | { name: string; position?: readonly [number, number, number]; rotation?: readonly [number, number, number]; scale?: readonly [number, number, number]; color?: string; opacity?: number; kind: "label"; text: string; } | { name: string; position?: readonly [number, number, number]; rotation?: readonly [number, number, number]; scale?: readonly [number, number, number]; color?: string; opacity?: number; kind: "model"; model: string; })[] -

Returns

Section titled “Returns”

ReadonlyMap<string, Readonly<{ key: string; name: string; make: ElementMake; position: Vec3; rotation: Vec3; scale: Vec3; color: Vec3; opacity: number; }>>

ease()function

Section titled “ease()”
Signature
function ease(amount): number;

Ease in and out, so beats settle rather than stop.

Parameters

Section titled “Parameters”
Parameter Type
amount number

Returns

Section titled “Returns”

number

beatAt()function

Section titled “beatAt()”
Signature
function beatAt(scene, seconds): BeatPosition;

Which beat is showing seconds into the scene, and how far into it.

Parameters

Section titled “Parameters”
Parameter Type
scene { title?: string; background?: string; beats: readonly object[]; }
scene.title? string
scene.background? string
scene.beats readonly object[]
seconds number

Returns

Section titled “Returns”

BeatPosition

frameAt()function

Section titled “frameAt()”
Signature
function frameAt(scene, seconds): SceneFrame;

The scene seconds after it started. The first beat grows in from an empty stage; each later beat tweens from the one before; the last holds.

Parameters

Section titled “Parameters”
Parameter Type
scene { title?: string; background?: string; beats: readonly object[]; }
scene.title? string
scene.background? string
scene.beats readonly object[]
seconds number

Returns

Section titled “Returns”

SceneFrame

keyFrame()function

Section titled “keyFrame()”
Signature
function keyFrame(scene, index): SceneFrame;

A beat’s settled key state, shown when motion is reduced.

Parameters

Section titled “Parameters”
Parameter Type
scene { title?: string; background?: string; beats: readonly object[]; }
scene.title? string
scene.background? string
scene.beats readonly object[]
index number

Returns

Section titled “Returns”

SceneFrame