Puppet

• config: Partial<IPuppetUserConfig> & {backend: string; src: string}

Fields:

• backend: string - The name a registered backend answers to. Required; a puppet without one throws at construction.
• src: string - The resource descriptor handed to the backend, passed through verbatim. Required.
• options: Record<string, unknown> - Backend-specific options, passed through verbatim. Defaults to {}.
• size: PuppetSize | null - The logical size of the box in pixels. Defaults to null, meaning the stage size.
• layer?: Layer - See Layer.
• className?: string - Class names for the box. They land on the element carrying the box's position: relative and its width and height, which is the parent of the container handed to mount, not the container itself. The wrapper above it is where the transform is written, so a class that sets transform here is overwritten frame by frame.
• motion: string | null - Initial motion. Part of the saved state, so it survives a save/load round trip.
• expression: string | null - Initial expression.
• skin: string | null - Initial skin.
• params: Record<string, number> - Initial numeric parameters.
• slots: Record<string, string | null> - Initial string slots.

Plus every transform property a displayable takes: position, scale, rotation, opacity, and so on.

const alice = new Puppet({
    backend: "swatch",
    src: "models/alice/alice.model.json",
    options: {outline: true},
    motion: "idle",
    params: {ParamAngleX: 12},
});

What the backend drawing this puppet is currently doing.

• Returns PuppetStatus - See PuppetStatus

Two values are worth acting on. "missing-backend" means nothing answers to config.backend, and "error" means the backend threw or the model failed to load. In both cases the element is still on stage, still transforming and still saving, and is not being drawn.

The status describes the live instance and is not part of the saved game: a load re-mounts, and the status starts over from "unmounted".

if (alice.getStatus() === "missing-backend") {
    // the renderer this project depends on was never registered
}

Listen for this puppet's status changing, receiving the new status.

• listener: (status: PuppetStatus) => void - Called with the new status
• Returns LiveGameEventToken - dispose it to stop listening

A backend fails asynchronously: the element mounts, then the model does or does not load. Subscribe to find out whether the renderer came up.

const token = alice.onStatusChange((status) => {
    if (status === "error") console.warn("Alice is not being drawn");
});

Override the layer used to render this puppet.

• layer: Layer - See Layer
• Returns this

puppet.useLayer(foreground);

Request a named motion, usually the loop the model settles into.

• motion: string | null - The motion to request, or null to clear it

This is persistent state, not a one-shot: it is saved, and re-applied in full the next time the model mounts. A motion meant to play once and end belongs in command. The story does not wait for the backend to take the pose.

alice.setMotion("idle");

Request a named expression. Persistent state, like the motion.

• expression: string | null - The expression to request, or null to clear it

alice.setExpression("smile");

Request a named skin or costume. Persistent state, like the motion.

• skin: string | null - The skin to request, or null to clear it

alice.setSkin("winter");

Set one numeric parameter, leaving every other parameter as it stands.

• id: string - The parameter id
• value: number - Its new value

What an id means is the backend's business: a rig parameter, a bone override, a blend weight. The engine remembers it, saves it, and hands the whole map back on a load.

alice.setParam("ParamAngleX", 12);

Set one free string slot, leaving every other slot as it stands.

• id: string - The slot id
• value: string | null - Its new value; null clears that slot

Slots carry the named things motion / expression / skin do not cover: an attachment point, a swapped-in prop, or whatever a particular renderer calls its own.

alice.setSlot("prop", "umbrella");

Send the backend a command the engine neither models nor interprets.

• name: string - Forwarded verbatim
• payload?: unknown - Forwarded verbatim
• options?: PuppetCommandOptions - See PuppetCommandOptions

Use it for what PuppetState leaves out: a motion that plays once and ends, a hit test, lip sync. None of it is saved, so a command is not restored by a load and not taken back by an undo. Anything that has to survive either belongs in the state, through the set* methods above.

The story does not wait unless it is asked to.

alice.command("playMotion", {id: "wave"});                  // the story moves straight on
alice.command("playMotion", {id: "bow"}, {await: true});    // this one waits for it

• name: string - The key a puppet's backend config refers to.
• mount(container: HTMLDivElement, ctx: PuppetMountContext): PuppetInstance - Create an instance bound to a host element. The engine owns the box, the backend owns what is inside it. The container is emptied when the instance is disposed.

What the engine tells a backend when it mounts one.

• src: string - The resource descriptor the puppet declared, verbatim. The only structure the engine reads out of it is the directory it sits in, and only through resolveSibling.
• options: Readonly<Record<string, unknown>> - The author's options for this backend, verbatim.
• size: PuppetSize - The logical size of the box, in pixels. Later changes arrive via resize.
• resolveSrc(src: string): string - Resolve a source to a URL by the same rules images use. See Preloading.
• resolveSibling(relativePath: string): string - Resolve a path relative to this puppet's own src, a sibling in the same bundle. See Resolving files in a model bundle.
• warn(message: string, detail?: unknown): void - Report a non-fatal problem. The engine logs it and keeps the stage alive; it never throws.

One mounted model. The engine holds this handle and nothing else. For when each member is called, see Backend lifecycle.

• ready(): Promise<void> - Resolves once the model is loaded and its first frame has been drawn.
• apply(state: Readonly<PuppetState>): void | Promise<void> - Apply a complete state. Called once on mount, before ready(), then on every change.
• command(name: string, payload: unknown): void | Promise<void> - Run a named command. The engine never interprets name or payload. Returning a promise lets a caller that passed {await: true} wait for it; nothing waits by default.
• resize(size: PuppetSize): void - The box changed size.
• describe?(): Promise<PuppetDescription> - Optional. Describe the model to an editor host.
• dispose(): void - Tear the instance down. The container is emptied afterwards.

describe is not gated on status. It can be called any time between mount and dispose, before ready() has resolved, and more than once. A backend that can only describe a loaded model awaits its own load inside describe. Rejecting is also safe: the host logs it and falls back to letting the author type names.

See What null means for each field.

• motion: string | null - The named action currently requested, usually the loop the model settles into.
• expression: string | null - The named expression currently requested.
• skin: string | null - The named skin / costume currently requested.
• params: Record<string, number> - Free numeric parameters.
• slots: Record<string, string | null> - Free string slots, for whatever the three names above do not cover.

How the story treats a one-shot command.

• await?: boolean - Wait for the backend to finish the command before the story moves on. Defaults to false.

A waiting command is skippable like any other timed action.

A model describing itself to an editor host, so the host can fill its inspector's dropdowns from the live instance. Backends that cannot answer do not implement describe, and the host falls back to letting the author type names.

• motions: string[]
• expressions: string[]
• skins: string[]
• params: {id: string; min: number; max: number; default: number}[]
• size: PuppetSize | null - The model's own canvas size, or null when it does not report one.

• width: number
• height: number

Logical pixels.

• game.registerPuppetBackend(backend: PuppetBackend): this - Register a backend. Returns the game, so calls chain.
• game.getPuppetBackend(name: string): PuppetBackend | null - The backend registered under a name, or null.
• game.listPuppetBackends(): string[] - The names of every registered backend, in registration order.