Animations

Internotes have two animation modes. In time-based scenes, elements are revealed and animated along a millisecond timeline — students press play and watch. In cut-based scenes, students step through discrete states manually by scrolling through the page. The SDK delivers the current timeline state to your plugin so it can keep its rendering in sync with both modes.

The animation system is powered by the same cue, cue.draw, and cue.morph elements used by built-in diagram elements. When you wrap a plugin element in cue{}, the host applies a fade to the frame at the right time — and separately, the SDK delivers the timeline state so your plugin can also respond from inside.

AnimationState

Every animation state update delivers an object with four fields:

interface AnimationState {
  time: number            // Milliseconds elapsed since playback started or since last restart
  isPaused: boolean       // True while the student has paused the scene
  cutIndex: number | null // Index of the current cut; null in time-based scenes
  restartCounter: number  // Increments each time the scene is restarted or replayed
}

A scene is time-based when at least one cue{} or cue.draw{} element uses a time attribute (in, out, at). In time-based scenes, cutIndex is null and time advances in real time.

A scene is cut-based when every cue uses step-through navigation (no time attribute). In cut-based scenes, time is not meaningful and cutIndex increments each time the student presses forward.

animation.onState

Registers a handler that fires whenever the timeline state changes: playback starts or pauses, time advances significantly, a cut advances, or the scene is restarted.

• handler (function; required). Called with an AnimationState object.
• Returns void

internote.animation.onState(({ time, isPaused, cutIndex, restartCounter }) => {
  if (isPaused) pauseSimulation()
  else resumeSimulation()
})

animation.state

A synchronous getter for the most recently delivered animation state. Returns null before the first state message arrives — typically only possible if accessed before onInitialize fires.

• Returns AnimationState | null

const state = internote.animation.state
if (state && !state.isPaused) startLoop()

Time-Based Sync

In time-based scenes, time lets you drive your simulation or animation to match a specific position in the timeline. This is useful for seeking behaviour — if a student jumps forward on the timeline, your plugin can skip its state forward to match rather than playing through every intermediate frame.

let simTime = 0
let paused = false
let lastRestart = -1

internote.animation.onState(({ time, isPaused, restartCounter }) => {
  if (restartCounter !== lastRestart) {
    resetSimulation()
    lastRestart = restartCounter
    simTime = 0
  }

  paused = isPaused
  simTime = time
})

function loop() {
  if (!paused) {
    advanceSimulationTo(simTime)
    draw()
  }
  requestAnimationFrame(loop)
}

time is in milliseconds. If your plugin's first cue{} fires at 500 ms, you can use time < 500 to detect that the plugin is not yet visible and skip expensive computation during that window.

Cut-Based Sync

In cut-based scenes, cutIndex is the index of the current step the student is on. Zero-indexed: the first cut is cutIndex: 0, the second is cutIndex: 1, and so on.

Design your plugin to map cut indices to internal states:

const PHASES = [
  { particles: 10, gravity: 0.5, label: 'Few particles, low gravity' },
  { particles: 50, gravity: 1.0, label: 'More particles, normal gravity' },
  { particles: 200, gravity: 2.5, label: 'Dense field, high gravity' },
]

internote.animation.onState(({ cutIndex }) => {
  if (cutIndex === null) return  // Scene is time-based — ignore
  const phase = PHASES[cutIndex] ?? PHASES[PHASES.length - 1]
  applyPhase(phase)
})

Restart Handling

restartCounter increments each time the student replays the scene (using the restart button in the playback controls). Watch it and reset your simulation to its initial state to avoid carrying stale data from a previous run.

let lastRestart = -1

internote.animation.onState(({ restartCounter }) => {
  if (restartCounter !== lastRestart) {
    resetSimulation()
    lastRestart = restartCounter
  }
})

Combining with a Render Loop

The most common pattern: run a requestAnimationFrame loop and use animation state to control pause, seek, and restart behaviour.

import { internote } from '@internote/plugin-sdk'

let paused = false
let targetTime = 0
let lastRestart = -1
let rafId

internote.onInitialize(({ attrs, width, height, animation }) => {
  setup(attrs, width, height)

  // Initialise from the state at load time (in case the scene is mid-play)
  if (animation) {
    paused = animation.isPaused
    targetTime = animation.time
    lastRestart = animation.restartCounter
  }

  rafId = requestAnimationFrame(loop)
  internote.ready()
})

internote.animation.onState(({ time, isPaused, restartCounter }) => {
  if (restartCounter !== lastRestart) {
    resetSimulation()
    lastRestart = restartCounter
    targetTime = 0
  }
  paused = isPaused
  targetTime = time
})

function loop() {
  if (!paused) tick(targetTime)
  rafId = requestAnimationFrame(loop)
}

internote.onUnload(() => {
  cancelAnimationFrame(rafId)
})

Easing Reference

The internote animation system uses two easing curves that you can mirror in your plugin for visual consistency:

• smooth — cubic ease-in-out: t => t < 0.5 ? 4*t*t*t : 1 - Math.pow(-2*t+2, 3) / 2
• linear — no easing: t => t

Both correspond to the easing attribute on cue, cue.draw, and cue.morph elements. If your plugin animates a state transition in response to a cut, using the same easing as the surrounding cue elements produces a coherent feel.