1. @threlte/theatre
  2. Sheet

@threlte/theatre

Sheet

Theatre.js sheets contain one or more Theatre.js objects (which can be created with <Editable> components), that can be animated together.

Import

Source

Github View Source Code

Package

NPM View Package

Related Docs


Creating Sheets

You can create a sheet by placing the component <Sheet> as a child of a <Project> component. If a sheet with the given name already exists, it will represent the existing sheet instead of creating a new one.

<script>
	import { Project, Sheet, Editable } from '@threlte/theatre'
</script>

<Project>
	<!-- Will create a sheet with the name "Sheet A" -->
	<Sheet name="Sheet A">
		<Editable name="Editable A" />
	</Sheet>

	<!-- Will create a sheet with the name "Sheet B" -->
	<Sheet name="Sheet B">
		<Editable name="Editable A" />
	</Sheet>

	<!-- Will NOT create a sheet but reference "Sheet A" -->
	<Sheet name="Sheet A">
		<Editable name="Editable A" />
	</Sheet>
</Project>

Playing a Sheet's animation

Each Theatre.js sheet has a sequence attached to it.

Binding to the Sequence

You can access a sheet's sequence by binding to the sheet or its sequence directly. You can then use the playback controls on the sequence to play back the animation.

<script lang="ts">
	import { Sheet } from '@threlte/theatre'
	import type { ISequence } from '@theatre/core'

	let sequence: ISequence | undefined = undefined

	const runAnimation = () => {
		sequence?.play()
	}
</script>

<Sheet bind:sequence>
	<!-- … -->
</Sheet>

Using the property autoPlay

If you want your animation to play as soon as the Sheet is mounted or with a set delay, use the property autoPlay.

<script lang="ts">
	import { Sheet } from '@threlte/theatre'
</script>

<!-- Plays immediately -->
<Sheet autoPlay>
	<!-- … -->
</Sheet>

<!-- Plays the sequence with a delay of 300ms -->
<Sheet autoPlay={{ delay: 300 }}>
	<!-- … -->
</Sheet>

<!-- Plays the sequence in reverse -->
<Sheet autoPlay={{ direction: 'reverse' }}>
	<!-- … -->
</Sheet>

<!-- Plays the sequence 3 times -->
<Sheet autoPlay={{ iterationCount: 3 }}>
	<!-- … -->
</Sheet>

<!-- Plays the sequence from second 1 to 3 -->
<Sheet autoPlay={{ range: [1, 3] }}>
	<!-- … -->
</Sheet>

<!-- Plays the sequence in half speed -->
<Sheet autoPlay={{ rate: 0.5 }}>
	<!-- … -->
</Sheet>

Using a Slot Prop

When using the sequence or sheet in a child component, a slot prop can come in handy.

<script lang="ts">
	import { T, InteractiveObject } from '@threlte/core'
	import { Sheet, Editable } from '@threlte/theatre'
</script>

<Sheet let:play>
	<T.Mesh>
		<Editable name="Cube" transform controls />
		<InteractiveObject interactive on:click={play}>
		<T.BoxGeometry />
		<T.MeshStandardMaterial />
	</T.Mesh>
</Sheet>

Playback Controls

autoReset

The underlying Theatre.js sheets are persisted even when unmounting a <Sheet> component. That's why the sequence of a sheet does not reset itself to the initial playback position when unmounting a <Sheet> component. Provide the property autoReset to reset the playback to the position 0 of the sequence.

<script lang="ts">
	import { Sheet } from '@threlte/theatre'
</script>

<!-- Resets the sequence position onMount and onDestros -->
<Sheet autoReset>
	<!-- … -->
</Sheet>

<!-- Resets the sequence position only on onMount -->
<Sheet autoReset="onMount">
	<!-- … -->
</Sheet>

<!-- Resets the sequence position only on onDestroy -->
<Sheet autoReset="onDestroy">
	<!-- … -->
</Sheet>

autoPause

Similarly, when you want to pause a sequence as soon as a <Sheet> is unmounted, provide the flag autoPause.

<script lang="ts">
	import { Sheet } from '@threlte/theatre'
</script>

<!-- Pauses the sequence as soon as it's unmounted -->
<Sheet autoPause>
	<!-- … -->
</Sheet>