Theatre.js Animation Library

Theatre.js is a motion design library for the web designed for high-fidelity animation. It allows you to express detailed, nuanced movement both programmatically and visually.

Key use cases include:

• Animating 3D objects (e.g., with THREE.js).
• Animating HTML/SVG elements (e.g., via React).
• Designing micro-interactions.
• Choreographing generative interactive art.
• Animating any arbitrary JavaScript variable.

Theatre.js is an animation library designed for high-fidelity motion graphics. It allows you to express detailed, nuanced movement both programmatically and visually.

Key use cases include:

• Animating 3D objects (e.g., using THREE.js).
• Animating HTML/SVG elements via React or other libraries.
• Designing micro-interactions.
• Choreographing generative interactive art.
• Animating any arbitrary JavaScript variable.

Theatre.js allows you to animate various types of content both programmatically and visually. Common use cases include:

• 3D Objects: Animate objects in THREE.js or other 3D libraries.
• HTML/SVG: Animate DOM elements via React or other web libraries.
• Micro-interactions: Design subtle UI feedback and transitions.
• Generative Art: Choreograph interactive and generative art pieces.
• Arbitrary JS Variables: Animate any JavaScript variable by connecting it to the Theatre.js timeline.

A prism is a reactive unit in @theatre/dataverse. It is created by passing a function to prism(). This function automatically tracks any other prisms referenced within it as dependencies. When those dependencies change, the function reruns. This allows you to build complex, reactive dependency graphs where updates propagate efficiently through the system.

import { prism } from '@theatre/dataverse'

const myPrism = prism(() => {
  // Any prism used here becomes a dependency
  return someOtherPrism.getValue() + 1
})

Dataverse is built around four main abstractions that manage state and computation:

1. Atoms: State holders that manage either component-level or global application state.
2. Pointers: Type-safe references to specific properties within an Atom.
3. Prisms: Functions that derive values from Atoms or other Prisms.
4. Tickers: Mechanisms to schedule and synchronize computations, especially useful for reacting to changes outside of the React render loop.

The Ticker class is used to schedule and execute callbacks per tick. It provides a mechanism to decouple the registration of side effects from their execution. Ticks are not automatic; they must be triggered externally (for example, using a requestAnimationFrame loop) by calling the tick() method.

When you register a callback, you can choose whether it runs immediately (if a tick is already in progress) or waits for the next cycle. This is useful for managing high-frequency updates or ensuring certain logic runs in sync with a rendering loop.

// Conceptual usage pattern
const ticker = new Ticker();

// Schedule a callback
ticker.onNextTick(() => {
  console.log('Running on the next tick');
});

// Trigger the tick manually (e.g., in a loop)
function loop(time: number) {
  ticker.tick(time);
  requestAnimationFrame(loop);
}
requestAnimationFrame(loop);

Theatre.js is split into two distinct packages that work together:

1. @theatre/core: The runtime library used to define animations and manage state in your application.
2. @theatre/studio: The visual editor (Studio) used to choreograph and tweak animations in real-time.

To use Theatre.js in a project, you will typically install @theatre/core for your application logic and use @theatre/studio during development to visually design your motion graphics.

Theatre.js is split into two distinct packages that serve different roles in your workflow:

1. @theatre/core: The runtime library. This is what you include in your production application to drive animations and manage state. It is released under the Apache License.

2. @theatre/studio: The visual editor. This package provides the UI for designing animations, setting up scenes, and choreographing motion. It is intended to be used only during design and development. It is released under the AGPL 3.0 License.

Important for Production: Your final production bundle should only include @theatre/core. Because @theatre/studio is only used during development, your end-users will not be affected by the AGPL 3.0 license of the studio package.

The PointerProxy<O> class in @theatre/dataverse allows you to create "pointer-prisms" where the underlying target pointer can be swapped out dynamically. This is useful when you want to maintain a stable reference to a proxy object while changing which part of the data tree it is currently observing or manipulating.

Key Capabilities

• Dynamic Switching: Use setPointer(p) to change the underlying Pointer being proxied.
• Prism Access: Use pointerToPrism(pointer) to obtain a Prism for a specific sub-path relative to the current proxied pointer.
• Root Access: The pointer property provides a read-only reference to the current root pointer of the proxy.