Theatre.js

https://www.theatrejs.com/docs
Admin
Theatre.js is a design tool and animation library for creating and editing keyframe-based animations...
Tokens:58,227
Snippets:526
Trust Score:8.8
Update:1 day ago
Show doc for...
Tokens:
Raw
### Install dependencies and start dev server with yarn

Source: https://www.theatrejs.com/docs/latest/getting-started/with-three-js

Alternative to npm: install dependencies and start the dev server using yarn.

```bash
# install the dependencies:
  yarn install
  # and start the dev server:
  yarn run dev
```

--------------------------------

### Install dependencies and start dev server with npm

Source: https://www.theatrejs.com/docs/latest/getting-started/with-three-js

Install dependencies and start the Vite dev server using npm. The dev server runs at http://localhost:3000.

```bash
# install the dependencies:
  npm install
  # and start the dev server:
  npm run dev
```

--------------------------------

### Quick start: useControls example

Source: https://www.theatrejs.com/docs/latest/api/theatric

A minimal React app using useControls to create and tweak name and age values. The code includes index.jsx and App.jsx in one block.

```jsx
// index.jsx
ReactDOM.render(<App />, document.getElementById('root'))

// App.jsx
import { useControls } from 'theatric'
import React from 'react'

export default function App() {
  const { name, age } = useControls({ name: 'Andrew', age: 28 })
  return (
    <div>
      Hey, I'm {name} and I'm {age} years old.
    </div>
  )
}
```

--------------------------------

### useControls with nested props and button

Source: https://www.theatrejs.com/docs/latest/api/theatric

Example of setting a nested prop using pointers with $get and $set.

```jsx
import { useControls, button } from 'theatric'
function Introduction() {
  const { person, $get, $set } = useControls({
    // note how name and age are sub-props of person
    person: {
      name: 'Andrew',
      age: 28,
    },
    IncrementAge: button(() => {
      // values.person.age is a pointer to the age prop of the person object
      $set((values) => values.person.age, $get((values) => values.person.age) + 1)
    }),
  })
  return (
    <div>
      <div>
        Hey, I'm {person.name} and I'm {person.age} years old.
      </div>
    </div>
  )
}
```

--------------------------------

### Install dependencies with npm

Source: https://www.theatrejs.com/docs/latest/getting-started/with-react-three-fiber

Install React, Three.js, React Three Fiber, Theatre.js packages, and TypeScript types for Three.js using npm.

```bash
# r3f and its dependencies
npm install --save react three @react-three/fiber
# Theatre.js
npm install --save @theatre/core @theatre/react @theatre/r3f
# Three.js types (when using Typescript)
npm install --save-dev @types/three
```

--------------------------------

### Open a pane with studio.createPane

Source: https://www.theatrejs.com/docs/latest/manual/authoring-extensions

Opens the pane defined with class 'example' by calling studio.createPane with the pane's class name.

```javascript
studio.createPane('example')
```

--------------------------------

### Install Theatre.js packages with npm or yarn

Source: https://www.theatrejs.com/docs/latest/getting-started/with-three-js

Install @theatre/core and @theatre/studio using npm or yarn. The studio package provides the editor GUI, while core plays animations.

```bash
# with npm
npm install --save @theatre/core @theatre/studio

# or with yarn
yarn add @theatre/core @theatre/studio
```

--------------------------------

### Import and initialize Theatre.js studio

Source: https://www.theatrejs.com/docs/latest/getting-started/with-three-js

Import the studio package and call studio.initialize() to start the editor. This is done in the main.ts file of the starting project.

```typescript
/* ... */
import * as THREE from 'three'
import studio from '@theatre/studio'

/**
 * Theatre.js
 */
studio.initialize()
/* ... */
```

--------------------------------

### Install theatric via npm

Source: https://www.theatrejs.com/docs/latest/api/theatric

Install the theatric package using npm.

```bash
$ npm install theatric
```

--------------------------------

### Create or get a project with getProject

Source: https://www.theatrejs.com/docs/latest/manual/projects

Creates a project named 'My Project' or returns the existing one if it already exists.

```javascript
import { getProject } from '@theatre/core'

// This will create a project called "My Project"
// or return it if it already exists:
const project = getProject('My Project')
```

--------------------------------

### Install dependencies with yarn

Source: https://www.theatrejs.com/docs/latest/getting-started/with-react-three-fiber

Install the same dependencies using yarn, including the optional TypeScript types for Three.js.

```bash
# r3f and its deps
yarn add react three @react-three/fiber
# Theatre.js
yarn add @theatre/core @theatre/react @theatre/r3f
# Three.js types (when using Typescript)
yarn add --dev @types/three
```

--------------------------------

### Using image assets with initialize and getAssetUrl

Source: https://www.theatrejs.com/docs/latest/api/theatric

Shows how to initialize Theatric with an assets baseUrl, use types.image for an image control, and get the asset URL. Awaiting initialize ensures assets are loaded before rendering.

```jsx
import { initialize, useControls, types, getAssetUrl } from 'theatric'
import theatricState from './theatricState.json'

initialize({
  // if you're using assets in your controls, you can specify the base URL here.
  assets: {
    // Defaults to '/'
    // If you host your assets on a different domain, you can specify it here.
    // For example if you're hosting your assets on https://cdn.example.com/theatric-assets
    // you can set this to 'https://cdn.example.com/theatric-assets' (no trailing slash)
    baseUrl: '/theatric-assets',
  },
}).then(() => {
  // this is only necessary if you're using assets such as .hdr images in your prop values.
  // awaiting the initialization ensures that the assets are loaded before rendering the app.
  ReactDOM.render(<App />, document.getElementById('root'))
})

function App() {
  const { img } = useControls({
    // this will accept jpegs/pngs/hdrs/etc
    // its default value is '' (empty string)
    // learn more about assets here: https://www.theatrejs.com/docs/latest/manual/assets
    img: types.image(''),
  })
  const src = getAssetUrl(img)
  return (
    <div>
      <img src={src} />
    </div>
  )
}
```

--------------------------------

### types.string usage examples

Source: https://www.theatrejs.com/docs/latest/manual/prop-types

Shows shorthand and with a custom label for the string prop.

```javascript
// shorthand:
const obj = sheet.object('key', { message: 'Animation loading' })
// with a label:
const obj = sheet.object('key', {
  message: types.string('Animation Loading', {
    // override the label given in the Details Panel and DopeSheet
    label: 'The Message',
  }),
})
```

--------------------------------

### Starter extension with a toolbar button

Source: https://www.theatrejs.com/docs/latest/manual/authoring-extensions

Defines an extension config with a global toolbar button. Must be passed to studio.extend() before studio.initialize(). Requires TypeScript and a bundler. Adds a button with title 'Example Button' and svgSource '👁'.

```typescript
// The code below assumes that your project is set up with TypeScript and a bundler.
import studio from '@theatre/studio'

const extensionConfig: IExtension = {
  id: 'hello-world-extension',
  toolbars: {
    global(set, studio) {
      set([
        {
          type: 'Icon',
          title: 'Example Button',
          svgSource: '👁',
        },
      ])
    },
  },
  panes: [],
}

studio.extend(extensionConfig)
studio.initialize()
```

--------------------------------

### sequence.play(opts?)

Source: https://www.theatrejs.com/docs/latest/api/core

Starts playback of a sequence. Returns a Promise that resolves to true when playback completes or false if interrupted.

```APIDOC
## sequence.play(opts?)

### Description
Starts playback of a sequence. Returns a `Promise` that resolves to `true` when the playback completes or resolves to `false` if playback gets interrupted (for example by calling `Sequence.pause`).

### Method
play

### Parameters
#### Options (opts)
- **rate** (number) - Optional - Playback speed multiplier. Example: `{ rate: 2.4 }`
- **range** (Array<number>) - Optional - Playback range in seconds. Example: `{ range: [1, 4] }`
- **iterationCount** (number) - Optional - Number of times to play. Use `Infinity` for infinite. Example: `{ iterationCount: 4 }`
- **direction** (string) - Optional - Playback direction: 'reverse', 'alternateReverse', etc. Example: `{ direction: 'reverse' }`
- **rafDriver** (object) - Optional - Custom rafDriver to control progression (since version 0.6.0).

### Request Example
```javascript
// plays the sequence from the current position to sequence.length
sheet.sequence.play()
// plays the sequence at 2.4x speed
sheet.sequence.play({ rate: 2.4 })
// plays the sequence from second 1 to 4
sheet.sequence.play({ range: [1, 4] })
// plays the sequence 4 times
sheet.sequence.play({ iterationCount: 4 })
// plays the sequence in reverse
sheet.sequence.play({ direction: 'reverse' })
// plays the sequence back and forth forever (until interrupted)
sheet.sequence.play({ iterationCount: Infinity, direction: 'alternateReverse' })
// plays the sequence and logs "done" once playback is finished
sheet.sequence.play().then(() => console.log('done'))
// play the sequence using the given rafDriver (since version 0.6.0)
sheet.sequence.play({ rafDriver })
```

### Response
#### Success Response
- Resolves to `true` when playback completes.
- Resolves to `false` if playback is interrupted.

### Notes
You can control how often `sequence.play()` progresses forward by optionally providing a `rafDriver`.
```

--------------------------------

### types.number usage examples

Source: https://www.theatrejs.com/docs/latest/manual/prop-types

Illustrates shorthand, options, range, custom nudging, and custom nudge function for the number prop.

```javascript
// shorthand:
const obj = sheet.object('key', { x: 0 })
// With options (equal to above)
const obj = sheet.object('key', {
  x: types.number(0),
})
// With a range (note that opts.range is just a visual guide, not a validation rule)
const x = types.number(0, { range: [0, 10] }) // limited to 0 and 10
// With custom nudging
const x = types.number(0, { nudgeMultiplier: 0.1 }) // nudging will happen in 0.1 increments
// With custom nudging function
const x = types.number({
  nudgeFn: (
    // the mouse movement (in pixels)
    deltaX: number,
    // the movement as a fraction of the width of the number editor's input
    deltaFraction: number,
    // A multiplier that's usually 1, but might be another number if user wants to nudge slower/faster
    magnitude: number,
    // the configuration of the number
    config: { nudgeMultiplier?: number; range?: [number, number] },
  ): number => {
    return deltaX * magnitude
  },
})
```

--------------------------------

### Access the Project via sheet.project

Source: https://www.theatrejs.com/docs/latest/api/core

Shows that sheet.project returns the Project this Sheet belongs to. The example creates a project and sheet, then verifies that sheet.project equals the project.

```javascript
import { getProject } from '@theatre/core'
const project = getProject('My Project')
const sheet = project.sheet('My Sheet')
// true
console.log(sheet.project === project)
```

--------------------------------

### types.stringLiteral usage examples

Source: https://www.theatrejs.com/docs/latest/manual/prop-types

Shows basic usage and a radio switch with custom label for the stringLiteral prop.

```javascript
// Basic usage
const obj = sheet.object('key', {
  light: types.stringLiteral(
    'r',
    // Specify labels for the specific values given in the Details Panel and Keyframe Editor
    { r: 'Red', g: 'Green' },
  ),
})
// Shown as a radio switch with a custom label
const obj = sheet.object(
  'key',
  {
    light: types.stringLiteral('r', { r: 'Red', g: 'Green' }),
  },
  // Optionally pass in prop options
  { as: 'switch', label: 'Street Light' },
)
```

--------------------------------

### Production HTML example with Theatre.js core-only

Source: https://www.theatrejs.com/docs/latest/getting-started/with-html-svg

Complete production HTML file that imports only the core Theatre.js bundle, embeds the project state, and plays the animation. It removes Studio initialization and uses the core-only script.

```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Theatre.js Tutorial</title>
<style>
body {
  margin: 0;
  color: white;
  background: black;
  font-family: sans-serif;
}
</style>
</head>
<body>
<h1 id="article-heading" style="text-align: center">Welcome</h1>
<script type="module">
  // only import core
  import 'https://cdn.jsdelivr.net/npm/@theatre/[[email protected]](https://www.theatrejs.com/cdn-cgi/l/email-protection)/dist/core-only.min.js'
  // We can now access just Theatre.core from here
  const articleHeadingElement = document.getElementById('article-heading')
  // Exported by clicking the project name and "Export Project Name to JSON" button.
  const projectState = {
    sheetsById: {
      'Sheet 1': {
        staticOverrides: {
          byObject: {
            'Heading 1': {
              opacity: 0.9936708860759493,
            },
          },
        },
        sequence: {
          subUnitsPerUnit: 30,
          length: 10,
          type: 'PositionalSequence',
          tracksByObject: {
            'Heading 1': {
              trackData: {
                LrJ3eujCAE: {
                  type: 'BasicKeyframedTrack',
                  keyframes: [
                    {
                      id: 'i-s2GT5JFm',
                      position: 0,
                      connectedRight: true,
                      handles: [0.5, 1, 0.882, 0],
                      value: 0,
                    },
                    {
                      id: 'I3Suv35jmV',
                      position: 3.433,
                      connectedRight: true,
                      handles: [0.055, 0.969, 0.82, -0.031],
                      value: 96,
                    },
                    {
                      id: 'M_00uVAeuK',
                      position: 5.6,
                      connectedRight: true,
                      handles: [0.087, 1.01, 0.5, 0],
                      value: 0,
                    },
                  ],
                },
                '9JzZUrUSb7': {
                  type: 'BasicKeyframedTrack',
                  __debugName: 'Heading 1:["opacity"]',
                  keyframes: [
                    {
                      id: 'EfAPcjrYAy',
                      position: 0,
                      connectedRight: true,
                      handles: [0.5, 1, 0.5, 0],
                      value: 0.9936708860759493,
                    },
                    {
                      id: 'hZ-tUkMP4C',
                      position: 2.367,
                      connectedRight: true,
                      handles: [0.5, 1, 0.5, 0],
                      value: 0,
                    },
                    {
                      id: 'D5PA_XGfS6',
                      position: 5.6,
                      connectedRight: true,
                      handles: [0.5, 1, 0.5, 0],
                      value: 0.9936708860759493,
                    },
                  ],
                },
              },
              trackIdByPropPath: {
                '["y"]': 'LrJ3eujCAE',
                '["opacity"]': '9JzZUrUSb7',
              },
            },
          },
        },
      },
    },
    definitionVersion: '0.4.0',
    revisionHistory: ['vLg01lxRrpP8eGsS'],
  }
  const { core } = Theatre
  // We don't need studio in production
  // studio.initialize()
  const project = core.getProject('HTML Animation Tutorial', {
    state: projectState,
  })
  const sheet = project.sheet('Sheet 1')
  const obj = sheet.object('Heading 1', {
    y: 0,
    opacity: core.types.number(1, { range: [0, 1] }),
  })
  // animations
  obj.onValuesChange((obj) => {
    articleHeadingElement.style.transform = `translateY(${obj.y}px)`
    articleHeadingElement.style.opacity = obj.opacity
  })
  // wait for project to be ready
  project.ready.then(() => {
    sheet.sequence.play({ iterationCount: Infinity, range: [0, 6] })
  })
</script>
</body>
</html>
```

--------------------------------

### Sequence.play() with various options

Source: https://www.theatrejs.com/docs/latest/api/core

Starts playback of a sequence. Returns a Promise that resolves to true on completion or false if interrupted. Options include rate, range, iterationCount, direction, and rafDriver (since 0.6.0).

```javascript
// plays the sequence from the current position to sequence.length
sheet.sequence.play()
// plays the sequence at 2.4x speed
sheet.sequence.play({ rate: 2.4 })
// plays the sequence from second 1 to 4
sheet.sequence.play({ range: [1, 4] })
// plays the sequence 4 times
sheet.sequence.play({ iterationCount: 4 })
// plays the sequence in reverse
sheet.sequence.play({ direction: 'reverse' })
// plays the sequence back and forth forever (until interrupted)
sheet.sequence.play({ iterationCount: Infinity, direction: 'alternateReverse' })
// plays the sequence and logs "done" once playback is finished
sheet.sequence.play().then(() => console.log('done'))
// play the sequence using the given rafDriver (since version 0.6.0)
sheet.sequence.play({ rafDriver })
```

--------------------------------

### Starter HTML file for Theatre.js tutorial

Source: https://www.theatrejs.com/docs/latest/getting-started/with-html-svg

Basic HTML page with a heading and a module script placeholder. Save as animation-tutorial.html and open in a browser to see a Welcome page.

```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Theatre.js Tutorial</title>
<style>
body {
margin: 0;
color: white;
background: black;
font-family: sans-serif;
}
</style>
</head>
<body>
<h1 id="article-heading" style="text-align: center">Welcome</h1>
<script type="module">
// Add JavaScript here
</script>
</body>
</html>
```

--------------------------------

### Show the Studio with studio.ui.restore()

Source: https://www.theatrejs.com/docs/latest/api/studio

Shows the Studio UI.

```javascript
studio.ui.restore()
```

--------------------------------

### Accessing the current sheet with useCurrentSheet

Source: https://www.theatrejs.com/docs/latest/api/r3f

Import useCurrentSheet from '@theatre/r3f' to get the sheet of the nearest SheetProvider. The example logs the sheet to the console and uses an editable mesh.

```jsx
import { useCurrentSheet } from '@theatre/r3f'

export default function Scene() {
  const currentSheet = useCurrentSheet()
  console.log(currentSheet)
  return (
    <editable.mesh theatreKey="Box">
      <boxBufferGeometry />
      <meshStandardMaterial color="orange" />
    </editable.mesh>
  )
}
```

--------------------------------

### Navigate to the project folder

Source: https://www.theatrejs.com/docs/latest/getting-started/with-three-js

Change into the cloned project directory from the terminal.

```bash
# open the repository in your terminal
  cd vanilla-threejs-project
```

--------------------------------

### Destructure sheet.address to get projectId, sheetId, sheetInstanceId

Source: https://www.theatrejs.com/docs/latest/api/core

Shows how to access the Sheet's unique address in Theatre.js. The address is an object containing projectId, sheetId, and sheetInstanceId. The example destructures these properties from sheet.address.

```javascript
import { getProject } from '@theatre/core'
const project = getProject('My Project')
const sheet = project.sheet('My Sheet')
const { projectId, sheetId, sheetInstanceId } = sheet.address
```

--------------------------------

### initialize(config)

Source: https://www.theatrejs.com/docs/latest/api/theatric

Optionally initializes the UI with a certain state or to take advantage of features like assets support. Takes the same config object as getProject().

```APIDOC
## initialize(config)

### Description
Optionally, you can call `initialize()` to initialize the UI with a certain state, or to take advantage of features like [assets](https://www.theatrejs.com/docs/latest/manual/assets) support. `initialize()` takes the same config object as [`getProject()`](https://www.theatrejs.com/docs/latest/api/core#getproject_id-config_).

### Parameters
- **config** (object) - Required - The configuration object, same as `getProject()` config. Can include a `state` property to load a state JSON file exported from the UI.

### Returns
- A Promise that resolves when theatric is ready (though you don't have to wait for it unless you want to use assets).

### Usage Example
```js
import { initialize, useControls, types, getAssetUrl } from 'theatric'
import theatricState from './theatricState.json'

initialize({
  // use the state of the state.json file you exported from the UI
  state: theatricState,
}).then(() => {
  // theatric is ready (although we don't have to wait for it unless we want to use assets)
})

ReactDOM.render(<App />, document.getElementById('root'))

function App() {
  const { img } = useControls({
    name: 'Andrew',
    age: types.number(28, {
      range: [0, 150],
    }),
  })
  return (
    <div>
      Hey, I'm {name} and I'm {age} years old.
    </div>
  )
}
```
```

--------------------------------

### useControls with $get and $set

Source: https://www.theatrejs.com/docs/latest/api/theatric

Use $get and $set to imperatively get and set control values.

```jsx
import { useControls } from 'theatric'
function Introduction() {
  const { name, age, $get, $set } = useControls({ name: 'Andrew', age: 28 })
  const increaseAge = useCallback(() => {
    $set((values) => values.age, $get((values) => values.age) + 1)
  }, [$get, $set])
  return (
    <div>
      <div>
        Hey, I'm {name} and I'm {age} years old.
      </div>
      <button onClick={increaseAge}>Increase age</button>
    </div>
  )
}
```

--------------------------------

### Sequence.pause() example

Source: https://www.theatrejs.com/docs/latest/api/core

Pauses the currently playing animation. The example plays a sequence and pauses it after 1 second using setTimeout.

```javascript
sheet.sequence.play()
setTimeout(() => sheet.sequence.pause(), 1000) // pause after 1 second
```

--------------------------------

### Create a rafDriver with start/stop callbacks

Source: https://www.theatrejs.com/docs/latest/manual/advanced

Defines a custom rafDriver that starts and stops its own requestAnimationFrame loop. Theatre calls start when computations are scheduled and stop when idle.

```typescript
import { createRafDriver } from '@theatre/core'
import type { IRafDriver } from '@theare/core'

function createBasicRafDriver(): IRafDriver {
  let rafId: number | null = null

  const start = (): void => {
    if (typeof window !== 'undefined') {
      const onAnimationFrame = (t: number) => {
        driver.tick(t)
        rafId = window.requestAnimationFrame(onAnimationFrame)
      }
      rafId = window.requestAnimationFrame(onAnimationFrame)
    } else {
      driver.tick(0)
      setTimeout(() => driver.tick(1), 0)
    }
  }

  const stop = (): void => {
    if (typeof window !== 'undefined') {
      if (rafId !== null) {
        window.cancelAnimationFrame(rafId)
      }
    } else {
      // nothing to do in SSR
    }
  }

  const driver = createRafDriver({ name: 'DefaultCoreRafDriver', start, stop })
  return driver
}
```

--------------------------------

### Initialize studio with custom rafDriver

Source: https://www.theatrejs.com/docs/latest/manual/advanced

Optionally makes the studio tick at the custom rafDriver's rate (e.g., 5fps). Useful for running the studio in XR frames.

```javascript
studio.initialize({
  __experimental_rafDriver: rafDriver,
})
```

--------------------------------

### project.getAssetUrl(assetHandle)

Source: https://www.theatrejs.com/docs/latest/api/core

Gets the URL for the provided asset handle. You would normally get an asset handle by listening to changes of asset props, like the image prop.

```APIDOC
## project.getAssetUrl(assetHandle)

### Description
Gets the URL for the provided asset handle. You would normally get an asset handle by listening to changes of asset props, like the image prop.

### Parameters
- **assetHandle** (AssetHandle) - Required - The asset handle for which to get the URL.

### Example
```js
const object = sheet.object('My Object', {
  texture: types.image(undefined, {
    label: 'Texture',
  }),
})
object.onValuesChange(({ texture }) => {
  setImageUrl(project.getAssetUrl(texture))
})
```

```

--------------------------------

### studio.initialize()

Source: https://www.theatrejs.com/docs/latest/api/studio

Initializes the studio. Call it once in your index.js/index.ts module. It silently ignores subsequent calls.

```APIDOC
## studio.initialize()

### Description
Initializes the studio. Call it once in your index.js/index.ts module. It silently ignores subsequent calls.

### Method
initialize

### Endpoint
studio.initialize()

### Parameters
None

### Request Example
```js
import studio from '@theatre/studio'
studio.initialize()
```

### Response
No return value.
```

--------------------------------

### Create a pane with studio.createPane('snapshot')

Source: https://www.theatrejs.com/docs/latest/api/studio

Creates a new pane of the specified class, which must have been previously registered by an extension.

```javascript
studio.createPane('snapshot')
```

--------------------------------

### Make cube editable with e.mesh

Source: https://www.theatrejs.com/docs/latest/getting-started/with-react-three-fiber

Make the cube editable by prefixing the mesh element with e. and adding the theatreKey prop. This example also includes the editable point light from the previous example.

```jsx
<Canvas  camera={{  position: [5, 5, -5],  fov: 75,  }}  >
  <SheetProvider sheet={getProject('Demo Project').sheet('Demo Sheet')}>
    <PerspectiveCamera theatreKey="Camera" makeDefault position={[5, 5, -5]} fov={75} />
    <ambientLight />
    <e.pointLight theatreKey="Light" position={[10, 10, 10]} />
    <e.mesh theatreKey="Cube">
      <boxGeometry args={[1, 1, 1]} />
      <meshStandardMaterial color="orange" />
    </e.mesh>
  </SheetProvider>
</Canvas>
```

--------------------------------

### Sequence.position set example

Source: https://www.theatrejs.com/docs/latest/api/core

Sets the animation position to 1 second.

```javascript
// set the animation position to 1 second
sheet.sequence.position = 1
```

--------------------------------

### Clone the THREE.js + bundler project repository

Source: https://www.theatrejs.com/docs/latest/getting-started/with-three-js

Clone the starter project using git. This provides a basic THREE.js scene with torus knot geometry, lighting, and a render loop.

```bash
# using git
  git clone https://github.com/fulopkovacs/vanilla-threejs-project
```

--------------------------------

### Wait for project to load with Project.ready

Source: https://www.theatrejs.com/docs/latest/manual/projects

When using Studio, loading a project happens asynchronously. Use project.ready to wait for the project to load.

```javascript
project.ready.then(() => console.log('Project loaded!'))
```

--------------------------------

### Define a pane toolbar and render it in the pane

Source: https://www.theatrejs.com/docs/latest/manual/authoring-extensions

Shows a full extension config with a custom toolbar named exampleToolbar and a pane that renders that toolbar into its node using studio.ui.renderToolset. The toolbar is defined like toolbars.global and the pane's mount returns cleanup functions.

```typescript
const extensionConfig: IExtension = {
  id: 'hello-world-extension',
  toolbars: {
    exampleToolbar(set, studio) {
      const toolsetConfig: ToolsetConfig = [
        {
          type: 'Icon',
          title: 'Example Button',
          svgSource: '🍕',
          onClick: () => {},
        },
      ]
      set(toolsetConfig)
      return () => console.log('toolbar removed!')
    },
  },
  panes: [
    {
      class: 'example',
      mount({ paneId, node }) {
        studio.ui.renderToolset('exampleToolbar', node)
        return () => console.log('pane closed!')
      },
    },
  ],
}
```

--------------------------------

### types.boolean usage examples

Source: https://www.theatrejs.com/docs/latest/manual/prop-types

Shows shorthand and with a custom label for the boolean prop.

```javascript
// shorthand:
const obj = sheet.object('key', { isOn: true })
// with a label:
const obj = sheet.object('key', {
  isOn: types.boolean(true, {
    // override the label given in the Details Panel and DopeSheet
    label: 'Enabled',
  }),
})
```

--------------------------------

### useControls with button

Source: https://www.theatrejs.com/docs/latest/api/theatric

Add a button to the control panel to trigger actions, combined with $get and $set.

```jsx
import { useControls, button } from 'theatric'
function Introduction() {
  const { name, age, $get, $set } = useControls({
    name: 'Andrew',
    age: 28,
    IncrementAge: button(() => {
      $set((values) => values.age, $get((values) => values.age) + 1)
    }),
  })
  return (
    <div>
      <div>
        Hey, I'm {name} and I'm {age} years old.
      </div>
    </div>
  )
}
```

--------------------------------

### Sequence.__experimental_getKeyframes() example

Source: https://www.theatrejs.com/docs/latest/api/core

Returns the keyframes of a given prop of an object. This is experimental since version 0.6.1.

```javascript
const obj = sheet.object('My Object', { position: { x: 0, y: 0 } })
// (assuming the user has sequenced the x prop)
const keyframes = sequence.__experimental_getKeyframes(obj.props.position.x) // an array of keyframes
```

--------------------------------

### studio.ui.restore()

Source: https://www.theatrejs.com/docs/latest/api/studio

Shows the Studio.

```APIDOC
## studio.ui.restore()

### Description
Shows the Studio.

### Method
restore

### Example
```js
studio.ui.restore()
```
```

--------------------------------

### Sequence.position read example

Source: https://www.theatrejs.com/docs/latest/api/core

Reads the current position of the playhead. In a time-based sequence, this represents the current time in seconds.

```javascript
// if the animation is past the 1 second mark
if (sheet.sequence.position > 1) {
  // do something
}
```

--------------------------------

### Registering the extension with Studio

Source: https://www.theatrejs.com/docs/latest/api/r3f

Import extension from '@theatre/r3f/dist/extension' and call studio.extend(extension) before studio.initialize() to register the R3F extension.

```js
import { extension } from '@theatre/r3f/dist/extension'
import studio from '@theatre/studio'
studio.extend(extension)
studio.initialize()
```

--------------------------------

### editable.group with objRef

Source: https://www.theatrejs.com/docs/latest/api/r3f

Exposes the backing-object of the element via a ref. The objRef prop is used to get a reference to the Theatre.js object.

```tsx
const MyComponent: React.FC = () => {
  const objRef = useRef<ISheetObject>()
  return <editable.group theatreKey="My group" objRef={objRef} />
}
```

--------------------------------

### getProject(id, config)

Source: https://www.theatrejs.com/docs/latest/api/core

Creates or returns a Project instance. When used with Studio, the state can be managed automatically; otherwise, pass a saved state object in the config.

```APIDOC
## getProject(id, config)

### Description
Creates or returns a Project instance. When used with Studio, the state can be managed automatically; otherwise, pass a saved state object in the config.

### Parameters
- **id** (string) - Required - The unique identifier of the project.
- **config** (object) - Optional - Configuration object. Can be empty or contain a `state` property with the saved project state.

### Request Example
```js
import { getProject } from '@theatre/core'
const config = {} // the config can be empty when starting a new project
const project = getProject('My Project', config)
```

### Response
Returns a Project instance.

```

--------------------------------

### project.ready

Source: https://www.theatrejs.com/docs/latest/api/core

A Promise that resolves when the project is loaded. If Studio is used, it resolves after Studio loads the project state; otherwise, it is already resolved.

```APIDOC
## project.ready

### Description
A Promise that resolves when the project is loaded. If Studio is used, it resolves after Studio loads the project state; otherwise, it is already resolved.

### Example
```js
project.ready.then(() => console.log('Project loaded!'))
```

```

--------------------------------

### Play a Sheet's animation with sheet.sequence.play()

Source: https://www.theatrejs.com/docs/latest/manual/sheets

Accesses the Sheet's Sequence through sheet.sequence and calls play() to start playback of the animation.

```javascript
sheet.sequence.play()
```

--------------------------------

### Retrieve asset URL with Project.getAssetUrl()

Source: https://www.theatrejs.com/docs/latest/manual/assets

Use the asset handle from onValuesChange to get the URL for the asset. The texture prop is defined with undefined as default.

```javascript
const object = sheet.object('My Object', {
  texture: types.image(undefined, {
    label: 'Texture',
  }),
})
object.onValuesChange(({ texture }) => {
  setImageUrl(project.getAssetUrl(texture))
})
```

--------------------------------

### Inferred compound prop type

Source: https://www.theatrejs.com/docs/latest/api/core

Create an object with a `position` prop that is an object, and Theatre.js infers its type as `types.compound`. The example also asserts the value.

```javascript
const obj = sheet.object('My Object', {
  position: {
    x: 0,
    y: 0,
  },
})
assert(obj.value.position.x === 0)
```

--------------------------------

### Create a Theatre.js project with getProject

Source: https://www.theatrejs.com/docs/latest/getting-started/with-three-js

Create a project using getProject('THREE.js x Theatre.js'). Projects act as save files stored in localStorage.

```typescript
import * as THREE from 'three'
import { getProject } from '@theatre/core'

// Initialize the studio
studio.initialize()

// Create a project for the animation
const project = getProject('THREE.js x Theatre.js')
```

--------------------------------

### useControls(controls, options?)

Source: https://www.theatrejs.com/docs/latest/api/theatric

The main API of Theatric. A React hook that takes an object of controls and returns an object of values, along with special $get and $set methods for imperative access.

```APIDOC
## useControls(controls, options?)

### Description
`useControls` is Theatric's main API. It is a React hook which you can call from anywhere in your component tree. It takes an object of controls and returns an object of values.

### Parameters
- **controls** (object) - Required - An object of controls, where each key is a control name and each value is a default value or a type definition.
- **options** (object) - Optional - An options object. Currently supports a `folder` option to namespace controls in the UI.

### Returns
- An object of values corresponding to the controls, plus two special properties: `$get` and `$set`.

### Usage Examples

#### Basic usage
```js
import { useControls } from 'theatric'

function Introduction() {
  const { name, age } = useControls({ name: 'Andrew', age: 28 })
  return (
    <div>
      Hey, I'm {name} and I'm {age} years old.
    </div>
  )
}
```

#### Using folder option
```js
import { useControls } from 'theatric'

function Introduction({ id }) {
  const { name, age } = useControls({ name: 'Andrew', age: 28 }, { folder: id })
  return (
    <div>
      Hey, I'm {name} and I'm {age} years old.
    </div>
  )
}
```

#### Using $get and $set
```js
import { useControls } from 'theatric'

function Introduction() {
  const { name, age, $get, $set } = useControls({ name: 'Andrew', age: 28 })
  const increaseAge = useCallback(() => {
    $set((values) => values.age, $get((values) => values.age) + 1)
  }, [$get, $set])
  return (
    <div>
      <div>
        Hey, I'm {name} and I'm {age} years old.
      </div>
      <button onClick={increaseAge}>Increase age</button>
    </div>
  )
}
```

#### Using buttons
```js
import { useControls, button } from 'theatric'

function Introduction() {
  const { name, age, $get, $set } = useControls({
    name: 'Andrew',
    age: 28,
    IncrementAge: button(() => {
      $set((values) => values.age, $get((values) => values.age) + 1)
    }),
  })
  return (
    <div>
      <div>
        Hey, I'm {name} and I'm {age} years old.
      </div>
    </div>
  )
}
```

#### Setting nested props
```js
import { useControls, button } from 'theatric'

function Introduction() {
  const { person, $get, $set } = useControls({
    // note how name and age are sub-props of person
    person: {
      name: 'Andrew',
      age: 28,
    },
    IncrementAge: button(() => {
      // values.person.age is a pointer to the age prop of the person object
      $set((values) => values.person.age, $get((values) => values.person.age) + 1)
    }),
  })
  return (
    <div>
      <div>
        Hey, I'm {person.name} and I'm {person.age} years old.
      </div>
    </div>
  )
}
```

### Notes
- `$get()` and `$set()` use pointers to specify which prop to get/set. Learn more about pointers [here](https://www.theatrejs.com/docs/latest/api/core#pointers).
```

--------------------------------

### Initialize Theatre.js Studio

Source: https://www.theatrejs.com/docs/latest/getting-started/with-react-three-fiber

Adds the Theatre.js Studio GUI to the page. Place below the other imports in main.tsx. After this, the Studio appears on top of the webpage.

```TypeScript
import studio from '@theatre/studio'
studio.initialize()
```

--------------------------------

### Development-only Studio initialization for create-react-app

Source: https://www.theatrejs.com/docs/latest/getting-started/with-react-three-fiber

Wraps Studio initialization and extension in a create-react-app environment check to include Studio only in development builds.

```TypeScript
// create-react-app
if (process.env.NODE_ENV === 'development') {
  studio.initialize()
  studio.extend(extension)
}
```

--------------------------------

### Sequence.attachAudio() with user gesture

Source: https://www.theatrejs.com/docs/latest/api/core

Attaches audio after a user gesture (button click) to avoid browser autoplay suspension. The example shows an event listener that creates an AudioContext and plays the sequence.

```javascript
// html: <button id="#start">start</button>
const button = document.getElementById('start')
button.addEventListener('click', async () => {
  const audioContext = somehowCreateAudioContext()
  await sheet.sequence.attachAudio({ audioContext, source: '...' })
  sheet.sequence.play()
})
```

--------------------------------

### Development-only Studio initialization for Vite

Source: https://www.theatrejs.com/docs/latest/getting-started/with-react-three-fiber

Wraps Studio initialization and extension in a Vite environment check to include Studio only in development builds.

```TypeScript
// Vite
if (import.meta.env.DEV) {
  studio.initialize()
  studio.extend(extension)
}
```

--------------------------------

### Create Theatre.js project, sheet, and object

Source: https://www.theatrejs.com/docs/latest/getting-started/with-html-svg

Creates a project named 'HTML Animation Tutorial' with a sheet 'Sheet 1' and an object 'Heading 1' with props y and opacity. The object appears in the Outline Menu.

```javascript
const project = core.getProject('HTML Animation Tutorial')
const sheet = project.sheet('Sheet 1')
const obj = sheet.object('Heading 1', {
  y: 0, // you can use just a simple default value
  opacity: core.types.number(1, { range: [0, 1] }), // or use a type constructor to customize
})
```

--------------------------------

### Import Theatre.js core and studio and initialize

Source: https://www.theatrejs.com/docs/latest/getting-started/with-html-svg

Add this JavaScript to the script tag where indicated to import Theatre.js from CDN and initialize the studio. After refreshing, the Theatre.js Studio UI appears over the page.

```javascript
import 'https://cdn.jsdelivr.net/npm/@theatre/[email protected]/dist/core-and-studio.js'
// We can now access Theatre.core and Theatre.studio from here
const { core, studio } = Theatre
studio.initialize() // Start the Theatre.js UI
```
Tokens:
Raw