<Sequence>

Sequences are the heart of the Theatre.js animation system. The sequence represents the animation timeline and provides an API for controlling its playback. In Threlte 7, you can reactively control animations through the <Sequence> component, which you place inside a <Sheet>.

Currently, you can only have one sequence in each sheet. Future versions of Theatre.js are expected to support multisequence sheets.

Theatre.js Docs

Sequence | Sequence Manual | Sequence API Reference

Usage

The following example shows how <Sequence> can be used to build a simple playback controller.

1
<script lang="ts">
2
  import { Canvas } from '@threlte/core'
3
  import { Project, Sequence, Sheet, type SequenceController } from '@threlte/theatre'
4
  import Controller from './Controller.svelte'
5
  import Scene from './Scene.svelte'
6
  import stateJson from './state.json'
7

8
  let sequence = $state<SequenceController>()
9
  let position = $state(0)
10
  let playing = $state(false)
11
  let play = $state<(opts?: {}) => Promise<boolean>>()
12
  let pause = $state<(opts?: {}) => Promise<boolean>>()
13
  let rate = $state(1)
14
</script>
15

16
<div>
17
  <Canvas>
18
    <Project config={{ state: stateJson }}>
19
      <Sheet>
20
        <Scene />
21
        <Sequence
22
          bind:sequence
23
          bind:playing
24
          bind:position
25
          bind:play
26
          bind:pause
27
          iterationCount={3}
28
          direction="alternate"
29
          autoplay
30
          delay={1000}
31
          {rate}
32
        />
33
      </Sheet>
34
    </Project>
35
  </Canvas>
36
  <Controller
37
    bind:position
38
    bind:rate
39
    {playing}
40
    {play}
41
    {pause}
42
  />
43
</div>
44

45
<style>
46
  div {
47
    height: 100%;
48
  }
49
</style>

1
<script lang="ts">
2
  import { PauseIcon, PlayIcon } from './icons'
3
  interface Props {
4
    position: number
5
    playing: boolean
6
    play?: (opts?: {}) => Promise<boolean>
7
    pause?: (opts?: {}) => Promise<boolean>
8
    rate?: number
9
  }
10

11
  let { position = $bindable(), playing, play, pause, rate = $bindable(1) }: Props = $props()
12

13
  const fmt = (n: number) =>
14
    n.toLocaleString('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 })
15

16
  const toggleRate = () => {
17
    if (rate == 1) {
18
      rate = 0.5
19
    } else if (rate == 0.5) {
20
      rate = 2
21
    } else {
22
      rate = 1
23
    }
24
  }
25
</script>
26

27
<menu>
28
  {#if !playing}
29
    <button onclick={() => play?.()}>
30
      <PlayIcon />
31
    </button>
32
  {:else}
33
    <button onclick={() => pause?.()}>
34
      <PauseIcon />
35
    </button>
36
  {/if}
37
  <button onclick={() => toggleRate()}>
38
    x{rate.toFixed(1)}
39
  </button>
40
  <input
41
    type="range"
42
    min={0}
43
    max={1}
44
    step={0.01}
45
    bind:value={position}
46
  />
47
  <div>{fmt(position)}</div>
48
</menu>
49

50
<style>
51
  menu {
52
    position: absolute;
53
    top: 0;
54
    width: 100%;
55
    display: flex;
56
    flex-flow: row;
57
    align-items: center;
58
    gap: 1rem;
59
    padding: 1rem;
60
    color: white;
61
    font-weight: bold;
62
  }
63

64
  menu :global(svg) {
65
    fill: white;
66
    width: 24px;
67
    height: 24px;
68
  }
69

70
  menu div {
71
    width: 50px;
72
    min-width: 50px;
73
  }
74

75
  menu input {
76
    flex-grow: 1;
77
  }
78
</style>

1
<script lang="ts">
2
  import { T } from '@threlte/core'
3
  import { SheetObject } from '@threlte/theatre'
4
</script>
5

6
<!-- Box -->
7
<SheetObject key="Box">
8
  {#snippet children({ Transform, Sync })}
9
    <Transform>
10
      <T.Mesh
11
        receiveShadow
12
        castShadow
13
      >
14
        <T.BoxGeometry args={[1, 1, 1]} />
15
        <T.MeshStandardMaterial>
16
          <Sync
17
            color
18
            emissive
19
          />
20
        </T.MeshStandardMaterial>
21
      </T.Mesh>
22
    </Transform>
23
  {/snippet}
24
</SheetObject>
25

26
<T.DirectionalLight
27
  position={[0.5, 2, 1]}
28
  castShadow
29
/>
30

31
<T.AmbientLight intensity={0.2} />
32

33
<T.PerspectiveCamera
34
  position={[4, 5, 10]}
35
  makeDefault
36
  oncreate={(ref) => {
37
    ref.lookAt(0, 0.5, 0)
38
  }}
39
/>

1
<svg
2
  xmlns="http://www.w3.org/2000/svg"
3
  viewBox="0 0 256 256"
4
>
5
  <rect
6
    width="256"
7
    height="256"
8
    fill="none"
9
  />
10
  <path
11
    d="M216,48V208a16,16,0,0,1-16,16H160a16,16,0,0,1-16-16V48a16,16,0,0,1,16-16h40A16,16,0,0,1,216,48ZM96,32H56A16,16,0,0,0,40,48V208a16,16,0,0,0,16,16H96a16,16,0,0,0,16-16V48A16,16,0,0,0,96,32Z"
12
  />
13
</svg>

1
<svg
2
  xmlns="http://www.w3.org/2000/svg"
3
  viewBox="0 0 256 256"
4
>
5
  <rect
6
    width="256"
7
    height="256"
8
    fill="none"
9
  />
10
  <path
11
    d="M240,128a15.74,15.74,0,0,1-7.6,13.51L88.32,229.65a16,16,0,0,1-16.2.3A15.86,15.86,0,0,1,64,216.13V39.87a15.86,15.86,0,0,1,8.12-13.82,16,16,0,0,1,16.2.3L232.4,114.49A15.74,15.74,0,0,1,240,128Z"
12
  />
13
</svg>

1
export { default as PlayIcon } from './PlayIcon.svelte'
2
export { default as PauseIcon } from './PauseIcon.svelte'

1
{
2
  "sheetsById": {
3
    "default": {
4
      "staticOverrides": {
5
        "byObject": {
6
          "Box": {
7
            "scale": {
8
              "x": 1,
9
              "y": 1,
10
              "z": 1
11
            },
12
            "rotation": {
13
              "x": 0,
14
              "y": 0,
15
              "z": 0
16
            },
17
            "color": {
18
              "r": 1,
19
              "g": 1,
20
              "b": 1,
21
              "a": 1
22
            }
23
          }
24
        }
25
      },
26
      "sequence": {
27
        "subUnitsPerUnit": 30,
28
        "length": 1,
29
        "type": "PositionalSequence",
30
        "tracksByObject": {
31
          "Box": {
32
            "trackData": {
33
              "6jxcIVb5VE": {
34
                "type": "BasicKeyframedTrack",
35
                "__debugName": "Box:[\"position\",\"x\"]",
36
                "keyframes": [
37
                  {
38
                    "id": "2znog1Hqt9",
39
                    "position": 0,
40
                    "connectedRight": true,
41
                    "handles": [0.5, 1, 0.5, 0],
42
                    "type": "bezier",
43
                    "value": 0
44
                  },
45
                  {
46
                    "id": "izysi9xIZV",
47
                    "position": 0.467,
48
                    "connectedRight": true,
49
                    "handles": [0.5, 1, 0.5, 0],
50
                    "type": "bezier",
51
                    "value": 0
52
                  },
53
                  {
54
                    "id": "1R7ALr_y7I",
55
                    "position": 1,
56
                    "connectedRight": true,
57
                    "handles": [0.5, 1, 0.5, 0],
58
                    "type": "bezier",
59
                    "value": 0
60
                  }
61
                ]
62
              },
63
              "CL6ilYk5F0": {
64
                "type": "BasicKeyframedTrack",
65
                "__debugName": "Box:[\"position\",\"y\"]",
66
                "keyframes": [
67
                  {
68
                    "id": "ILuids3SS2",
69
                    "position": 0,
70
                    "connectedRight": true,
71
                    "handles": [0.5, 1, 0.5, 0],
72
                    "type": "bezier",
73
                    "value": 0
74
                  },
75
                  {
76
                    "id": "5Fx9QwZog4",
77
                    "position": 0.467,
78
                    "connectedRight": true,
79
                    "handles": [0.5, 1, 0.5, 0],
80
                    "type": "bezier",
81
                    "value": 2.884894266415041
82
                  },
83
                  {
84
                    "id": "QdxaWbUKTO",
85
                    "position": 1,
86
                    "connectedRight": true,
87
                    "handles": [0.5, 1, 0.5, 0],
88
                    "type": "bezier",
89
                    "value": 0
90
                  }
91
                ]
92
              },
93
              "k17VolLHaa": {
94
                "type": "BasicKeyframedTrack",
95
                "__debugName": "Box:[\"position\",\"z\"]",
96
                "keyframes": [
97
                  {
98
                    "id": "ensBkfE4zJ",
99
                    "position": 0,
100
                    "connectedRight": true,
101
                    "handles": [0.5, 1, 0.5, 0],
102
                    "type": "bezier",
103
                    "value": 0
104
                  },
105
                  {
106
                    "id": "qGYRgJFQt0",
107
                    "position": 0.467,
108
                    "connectedRight": true,
109
                    "handles": [0.5, 1, 0.5, 0],
110
                    "type": "bezier",
111
                    "value": 0
112
                  },
113
                  {
114
                    "id": "acTy6onWqA",
115
                    "position": 1,
116
                    "connectedRight": true,
117
                    "handles": [0.5, 1, 0.5, 0],
118
                    "type": "bezier",
119
                    "value": 0
120
                  }
121
                ]
122
              },
123
              "8ozF3Q9pr9": {
124
                "type": "BasicKeyframedTrack",
125
                "__debugName": "Box:[\"rotation\",\"x\"]",
126
                "keyframes": [
127
                  {
128
                    "id": "zemdW99tC7",
129
                    "position": 0.3,
130
                    "connectedRight": true,
131
                    "handles": [0.5, 1, 0.5, 0],
132
                    "type": "bezier",
133
                    "value": 0
134
                  },
135
                  {
136
                    "id": "FKeku-J_jh",
137
                    "position": 0.7,
138
                    "connectedRight": true,
139
                    "handles": [0.5, 1, 0.5, 0],
140
                    "type": "bezier",
141
                    "value": 90
142
                  }
143
                ]
144
              },
145
              "Yz64RYOUhH": {
146
                "type": "BasicKeyframedTrack",
147
                "__debugName": "Box:[\"rotation\",\"y\"]",
148
                "keyframes": [
149
                  {
150
                    "id": "cO8d4gOyP7",
151
                    "position": 0.3,
152
                    "connectedRight": true,
153
                    "handles": [0.5, 1, 0.5, 0],
154
                    "type": "bezier",
155
                    "value": 0
156
                  },
157
                  {
158
                    "id": "GEPzCyTP8m",
159
                    "position": 0.7,
160
                    "connectedRight": true,
161
                    "handles": [0.5, 1, 0.5, 0],
162
                    "type": "bezier",
163
                    "value": 90
164
                  }
165
                ]
166
              },
167
              "aWuU3nv7t2": {
168
                "type": "BasicKeyframedTrack",
169
                "__debugName": "Box:[\"rotation\",\"z\"]",
170
                "keyframes": []
171
              },
172
              "825UyDpz6a": {
173
                "type": "BasicKeyframedTrack",
174
                "__debugName": "Box:[\"emissive\"]",
175
                "keyframes": [
176
                  {
177
                    "id": "2u6ASUPCLN",
178
                    "position": 0,
179
                    "connectedRight": true,
180
                    "handles": [0.5, 1, 0.5, 0],
181
                    "type": "bezier",
182
                    "value": {
183
                      "r": 0,
184
                      "g": 0,
185
                      "b": 0,
186
                      "a": 1
187
                    }
188
                  },
189
                  {
190
                    "id": "NuH1fhxmZy",
191
                    "position": 0.467,
192
                    "connectedRight": true,
193
                    "handles": [0.5, 1, 0.5, 0],
194
                    "type": "bezier",
195
                    "value": {
196
                      "r": 0.996078431372549,
197
                      "g": 0.23921568627450981,
198
                      "b": 0,
199
                      "a": 1
200
                    }
201
                  },
202
                  {
203
                    "id": "VmWNCbzBhT",
204
                    "position": 1,
205
                    "connectedRight": true,
206
                    "handles": [0.5, 1, 0.5, 0],
207
                    "type": "bezier",
208
                    "value": {
209
                      "r": 0,
210
                      "g": 0,
211
                      "b": 0,
212
                      "a": 1
213
                    }
214
                  }
215
                ]
216
              },
217
              "UP-UOQISBD": {
218
                "type": "BasicKeyframedTrack",
219
                "__debugName": "Box:[\"color\"]",
220
                "keyframes": [
221
                  {
222
                    "id": "A-rHMw_1mz",
223
                    "position": 0,
224
                    "connectedRight": true,
225
                    "handles": [0.5, 1, 0.5, 0],
226
                    "type": "bezier",
227
                    "value": {
228
                      "r": 1,
229
                      "g": 1,
230
                      "b": 1,
231
                      "a": 1
232
                    }
233
                  },
234
                  {
235
                    "id": "jrpD3O8bLK",
236
                    "position": 0.467,
237
                    "connectedRight": true,
238
                    "handles": [0.5, 1, 0.5, 0],
239
                    "type": "bezier",
240
                    "value": {
241
                      "r": 0.996078431372549,
242
                      "g": 0.23921568627450981,
243
                      "b": 0,
244
                      "a": 1
245
                    }
246
                  },
247
                  {
248
                    "id": "3B_Qi4_QFS",
249
                    "position": 1,
250
                    "connectedRight": true,
251
                    "handles": [0.5, 1, 0.5, 0],
252
                    "type": "bezier",
253
                    "value": {
254
                      "r": 1,
255
                      "g": 1,
256
                      "b": 1,
257
                      "a": 1
258
                    }
259
                  }
260
                ]
261
              }
262
            },
263
            "trackIdByPropPath": {
264
              "[\"position\",\"x\"]": "6jxcIVb5VE",
265
              "[\"position\",\"y\"]": "CL6ilYk5F0",
266
              "[\"position\",\"z\"]": "k17VolLHaa",
267
              "[\"rotation\",\"x\"]": "8ozF3Q9pr9",
268
              "[\"rotation\",\"y\"]": "Yz64RYOUhH",
269
              "[\"rotation\",\"z\"]": "aWuU3nv7t2",
270
              "[\"emissive\"]": "825UyDpz6a",
271
              "[\"color\"]": "UP-UOQISBD"
272
            }
273
          }
274
        }
275
      }
276
    }
277
  },
278
  "definitionVersion": "0.4.0",
279
  "revisionHistory": ["VSRORcDV9_yJ8fbi", "4poCDvFG3GZwc5nU", "gR-SIAqfZWUtx-q_"]
280
}

Lifecycle

Threlte provides lifecycle props to allow you to configure how the sequence playback is connected to the Svelte component lifecycle. See the autoplay, autoreset and autopause props below.

Note that the underlying Theatre.js sheets are persisted even when unmounting a <Sheet> component. That’s why the sequence doesn’t reset automatically when unmounting a <Sheet>, and why the autoreset options is required.

Audio

The audio options allow you to attach a soundtrack to your animation sequence. Theatre.js achieves this using the Web Audio API. For more details, see audio manual and attach audio API reference

Snippet Prop

When using the sequence in a child component, a snippet prop can come in handy.

1
<script lang="ts">
2
  import { T } from '@threlte/core'
3
  import { Sheet, Sequence, SheetObject } from '@threlte/theatre'
4
</script>
5

6
<Sheet>
7
  <Sequence>
8
    {#snippet children({ play })}
9
      <SheetObject key="Cube">
10
        {#snippet children({ Transform })}
11
          <Transform>
12
            <T.Mesh onclick={play}>
13
              <T.BoxGeometry />
14
              <T.MeshStandardMaterial />
15
            </T.Mesh>
16
          </Transform>
17
        {/snippet}
18
      </SheetObject>
19
    {/snippet}
20
  </Sequence>
21
</Sheet>

Component Signature

Props

name

type

required

default

description

audio

{source: AudioBuffer; audioContext: AudioContext; destinationNode: AudioContext['destination'];}

{}

Syncronize an audio track to the sequence; see the audio section below (Theatre.js)

autopause

boolean

false

Whether to pause playback when the component is unmounted (Threlte)

autoplay

boolean

false

Choose whether to automatically play the animation when the component is mounted (Threlte)

autoreset

"always" | "onMount" | "onDestroy" | undefined

undefined

Reset the playhead when the component is mounted, unmounted**, both or neither (Threlte)

delay

number

0

When using autoplay, how many milliseconds to wait before starting playback (Threlte)

direction

"normal" | "reverse" | "alternate" | "alternateReverse"

normal

Choose the direction of animation playback (Theatre.js)

iterationCount

number

1

Control how often the animation is played. Set Infinity to keep looping (Theatre.js)

range

[number, number] | undefined

[0, length]

Choose what part of the animation is played (Theatre.js)

rate

number

1

Set the speed of playback (Theatre.js)

Bindings

name

type

position

number | undefined

play

(opts?) => Promise<boolean> (see Theatre.js Sequence API docs for options)

pause

() => void

sequence

ISequence

sheet

ISheet