Skip to main content

Animation Builder API

This page documents the fluent AnimationBuilder API you receive as aBuilder inside builder.animate((aBuilder) => ...).

Overview​

AnimationBuilder is a timeline compiler:

  • You select a target (node / edge).
  • You add tweens with to(...).
  • Time advances via an internal cursor (sequential by default).

Target selection​

aBuilder.node(id: string)​

Targets a node by id.

  • Target form: AnimationTarget = node:<id>
  • Returns: AnimationBuilder (chainable)

aBuilder.edge(id: string)​

Targets an edge by id.

  • Target form: AnimationTarget = edge:<id>
  • Typical id format: "a->b"
  • Returns: AnimationBuilder (chainable)

aBuilder.edge(from: string, to: string, id?: string)​

Convenience overload.

  • If id is provided, equivalent to aBuilder.edge(id).
  • Otherwise, equivalent to aBuilder.edge(from + '->' + to).
  • Returns: AnimationBuilder

Writing tweens​

aBuilder.to(props: AnimatableProps, opts: TweenOptions)​

Adds tweens for the current target.

  • props: AnimatableProps
    • One tween is emitted per numeric property in props.
    • Non-numeric values are ignored.
  • opts: TweenOptions
    • duration: number (ms)
    • easing?: Ease (Ease)
    • from?: Partial<Record<AnimProperty, number>> (AnimProperty)

Time behavior

  • The tween’s delay is the current internal cursor time.
  • After .to(...), the cursor advances by duration (sequential by default).

Errors

  • Throws if you call to(...) without selecting a target first.

Timeline control​

aBuilder.wait(ms: number)​

Advances the internal cursor by ms without adding tweens.

aBuilder.at(ms: number)​

Sets the internal cursor to an absolute time offset (ms).

This is the main way to schedule multiple sequences in parallel (e.g. move A and B at the same time).

Custom properties (advanced)​

aBuilder.extendAdapter(cb: ExtendAdapter)​

Registers custom animatable properties for the spec produced by this animate(...) call.

  • cb: ExtendAdapter
  • During playback, VizCraft will call your callback with an adapter that may support register(...).

Typical usage:

  • Add a custom property name (e.g. r) and provide get/set handlers.
  • Then tween that property with .to({ r: 42 }, { duration: 500 }).

Example: parallel sequences​

builder.animate((aBuilder) => {
  aBuilder.at(0).node('a');
  aBuilder.to({ x: 320 }, { duration: 1200, easing: 'easeInOut' });

  aBuilder.at(0).node('b');
  aBuilder.to({ y: 150 }, { duration: 1200, easing: 'easeInOut' });
});