Animations & Transitions

The format describes motion in two places: within a panel (PanelAnimations — layer keyframes and a camera move across the artwork) and between panels or pages (Transition — the visual effect while navigating). Both are declarative.

PanelAnimations

Defined as $defs/PanelAnimations, set per panel at chapters[].panels.<panelId>.animations (also overridable via variants). A panel has one animation. It can hold layer keyframes (layers move, fade or change their filters), a viewport move (a Ken-Burns-style pan/zoom over the artwork), or both.

Layer keyframes (AnimationKeyframe)

Added within format 1.6.0. Each keyframe sets one property of one layer at one point in time:

No other properties are allowed on a keyframe.

Offsets and blur are relative to the panel, not device pixels, so an animation looks the same on every screen.

How keyframes play:

• Keyframes with the same layerId and property form a track, ordered by timeMs.
• Before a track's first keyframe the layer holds the first value; after the last it holds the last value.
• Between two keyframes the value is interpolated with the easing of the earlier keyframe.
• Properties without keyframes are left as the layer defines them.
• The animation starts when the panel is shown and runs for durationMs (or until the last keyframe, when that is later). With loop: true it restarts; otherwise it keeps its end state.
• Players that honour a reduced-motion preference skip the motion and show the end state.
• A keyframe whose layerId does not exist in the panel is ignored.

{
  "animations": {
    "name": "Robot rolls in",
    "durationMs": 4000,
    "loop": false,
    "keyframes": [
      { "layerId": "character", "property": "transform.x", "timeMs": 0, "value": -0.4, "easing": "ease-out" },
      { "layerId": "character", "property": "transform.x", "timeMs": 3000, "value": 0 },
      { "layerId": "character", "property": "opacity", "timeMs": 0, "value": 0 },
      { "layerId": "character", "property": "opacity", "timeMs": 800, "value": 1 }
    ]
  }
}

The character starts 40% of the panel width to the left, invisible, fades in over 0.8 s and rolls to its resting position over 3 s.

Viewport moves

startViewportRect and endViewportRect describe a camera move from one rectangle of the panel to another: the part of the panel the reader sees at the start and at the end of the animation. A NormalizedRect requires all four of x, y, w, h, each between 0 and 1.

{
  "animations": {
    "startViewportRect": { "x": 0, "y": 0, "w": 1, "h": 1 },
    "endViewportRect": { "x": 0.3, "y": 0.2, "w": 0.4, "h": 0.4 },
    "durationMs": 4000,
    "easing": "ease-in-out"
  }
}

This starts on the full panel and slowly zooms into the region at (0.3, 0.2) sized 40% × 40% — a classic dramatic push-in.

How a viewport move plays:

• The move runs from the start rect to the end rect over durationMs, eased by easing, on the same timeline as the layer keyframes; loop restarts both.
• A missing rect is the whole panel: an end rect alone is a push-in, a start rect alone a pull-back.
• The rect is fitted into the panel box with a uniform scale — the artwork is never stretched — and centred. Near an edge the rect sits off-centre rather than showing empty space.
• Everything anchored to the artwork moves together: layers, hotspots and speech bubbles. The panel box clips the result.
• Without durationMs there is no travel: the end rect is shown as a static framing.
• Reduced motion shows the end rect at once.

Transition

Defined as $defs/Transition. Transitions describe how the view changes while navigating, and appear in several places:

• Graph edges — chapters[].graph.edges[].transition (the transition used when following that edge)
• Hotspot goTo actions — action.transition (see Hotspots)
• Page transitions — pages[].transitions.in / pages[].transitions.out (entering/leaving a page)
• Format presets — settings.outputPresets.<format>.defaultTransition (per-output-format default, see Settings)

All properties are optional:

Transitions on edges

The most common placement is on a graph edge, so different paths through the story can feel different:

{
  "graph": {
    "entry": "p1",
    "edges": [
      {
        "from": "p1",
        "to": "p2",
        "transition": { "type": "slide", "dir": "left", "durationMs": 300 }
      },
      {
        "from": "p2",
        "to": "p3-dream",
        "condition": { "==": [{ "var": "state.dreaming" }, true] },
        "transition": { "type": "fade", "durationMs": 800, "easing": "ease-in-out" }
      }
    ]
  }
}

Which transition applies

• Navigation triggered by a hotspot goTo action uses the transition declared on that action.
• Navigation along a graph edge uses the edge's transition.
• When the chosen navigation declares no transition, the active output format's defaultTransition from settings.outputPresets serves as the fallback.

What can animate — summary

Related pages

• Graph — edges and conditions
• Chapters & Pages — page transitions.in/out
• Settings — outputPresets and default transitions