threlte logo
@threlte/theatre

Getting Started

Theatre.js is a javascript animation library with a professional motion design toolset. It helps you create any animation, from cinematic scenes in 3D, to delightful UI interactions.

Concepts

As with the rest of Threlte, @threlte/theatre provides an idiomatic yet transparent Svelte wrapper. The core concepts of @threlte/theatre are:

@threlte/theatre ComponentDescriptionCorresponding Theatre.js Concept(s)
<Project>Contains your project’s animation sheetsProject
<Sheet>Binds to an animation sheet that contains animation sequencesSheet
<Sequence>Binds to an animation sequence and contains the animated componentsSequence
<Studio>Enables the Theatre.js in-browser studio interface during developmentStudio
<SheetObject>Enables editing and animating its parent in the studio interfaceSheet Object
<Theatre>A helper component providing a project with a single sheet and a studioProject, Sheet, Studio

The @threlte/theatre documentation cross-references the Theatre.js documentation, allowing you to get a deeper understanding of the underlying concepts.

Workflow

Theatre.js combines programming in your IDE with editing in a browser-based GUI. The core workflow looks something like this:

  1. Create your scene as usual, placing a <Project> and one or more <Sheets> in your <Canvas>.
  2. Identify the elements and props you wish to edit in the <Studio>, and place an <SheetObject> component around them, then use the slotted components <Sync>, <Declare> or <Transform> to add editable props.
  3. Edit props and animations of elements in the <Studio> in the browser; config state is autosaved to local storage.
  4. Export the updated state as a JSON file by selecting your project in the studio and clicking export (top-right corner).
  5. Import your scene’s state.json and use it in your <Project>’s config prop.

Installation

npm install @threlte/theatre @theatre/core @theatre/studio

Quick Start

To get started quickly, encapsulate your whole scene in the component <Theatre>.

The component <Theatre> provides a default <Project> and <Sheet> and implements <Studio>. For a more flexible structure please consider using <Project>, <Sheet> and <Studio> on their own.

App.svelte
<script lang="ts">
  import { Canvas } from '@threlte/core'
  import { Theatre } from '@threlte/theatre'
  import Scene from './Scene.svelte'
</script>

<Canvas>
  <Theatre>
    <Scene />
  </Theatre>
</Canvas>

In your Scene, add the component <SheetObject> as a parent of any component you’d wish to edit or animate. The component <SheetObject> provides the components <Sync>, <Declare> and <Transform> that allow you to manipulate properties in Theatre.js based on your Threlte markup.

The component <Transform> is a shortcut to add position, scale and rotation at once as well as mount handy <TransformControls> whenever the respective Sheet Object is selected in the studio.

Scene.svelte
<script lang="ts">
  import { T } from '@threlte/core'
  import { OrbitControls } from '@threlte/extras'
  import { SheetObject } from '@threlte/theatre'
</script>

<T.PerspectiveCamera
  position={[0, 5, 10]}
  makeDefault
>
  <OrbitControls target={{ y: 1.5 }} />
</T.PerspectiveCamera>

<!-- Box -->
<SheetObject key="Box">
  {#snippet children({ Transform, Sync })}
    <Transform>
      <T.Mesh
        receiveShadow
        castShadow
        position.y={0.5}
      >
        <T.BoxGeometry args={[1, 1, 1]} />
        <T.MeshStandardMaterial color="#b00d03">
          <Sync
            color
            roughness
            metalness
          />
        </T.MeshStandardMaterial>
      </T.Mesh>
    </Transform>
  {/snippet}
</SheetObject>

You will now see the Theatre.js studio interface. Make yourself comfortable with the controls and if you haven’t done yet, please read the Theatre.js studio manual and keyboard shortcuts.