@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>
’sconfig
prop.
Installation
npm install @threlte/theatre @theatre/core @theatre/studio
Quick Start
To get started quickly, encapsulate your whole scene in the component <Theatre>
.
<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.
<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.