@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 Component	Description	Corresponding Theatre.js Concept(s)
<Project>	Contains your project’s animation sheets	Project
<Sheet>	Binds to an animation sheet that contains animation sequences	Sheet
<Sequence>	Binds to an animation sequence and contains the animated components	Sequence
<Studio>	Enables the Theatre.js in-browser studio interface during development	Studio
<SheetObject>	Enables editing and animating its parent in the studio interface	Sheet Object
<Theatre>	A helper component providing a project with a single sheet and a studio	Project, 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:

Create your scene as usual, placing a <Project> and one or more <Sheets> in your <Canvas>.
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.
Edit props and animations of elements in the <Studio> in the browser; config state is autosaved to local storage.
Export the updated state as a JSON file by selecting your project in the studio and clicking export (top-right corner).
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.

Previous Page usePrismaticJoint

Next Page Components