theatre-js

Theatre.js のベストプラクティス

Web 向けのモーションデザインエディター兼アニメーションライブラリです。プログラムから操作できるビジュアルタイムラインエディター（Studio）を提供します。

インストール

# Core + Studio (development)
npm install @theatre/[email protected] @theatre/[email protected]

# React Three Fiber integration
npm install @theatre/[email protected]

# React utilities
npm install @theatre/react

# Theatric (simplified controls)
npm install theatric

クイックスタート

import * as core from '@theatre/core'
import studio from '@theatre/studio'

// Initialize Studio (dev only)
if (import.meta.env.DEV) {
  studio.initialize()
}

// Create project → sheet → object
const project = core.getProject('My Project')
const sheet = project.sheet('Main')
const obj = sheet.object('Box', {
  position: { x: 0, y: 0 },
  opacity: 1
})

// Read values
console.log(obj.value.position.x)

// Listen to changes
obj.onValuesChange((values) => {
  element.style.opacity = values.opacity
  element.style.transform = `translate(${values.position.x}px, ${values.position.y}px)`
})

// Play animation
sheet.sequence.play({ iterationCount: Infinity })

主な概念

概念	説明
Project	すべてのアニメーションデータを格納するコンテナです。エクスポートされた JSON の状態に対応します
Sheet	シーンまたはコンポーネントです。オブジェクトと 1 つのシーケンスを含みます
Object	型付きプロパティを持つ、アニメーション可能なエンティティです
Sequence	キーフレームを含むタイムラインです。再生を制御します
Props	型付きの値です（number、compound、rgba など）

リファレンス一覧

リファレンス	使用する場面
references/01-core.md	プロジェクトのセットアップ、シート、オブジェクト、シーケンス、再生制御
references/02-prop-types.md	プロパティの定義、カスタム型、複合プロパティ、制約
references/03-studio.md	Studio の UI、キーボードショートカット、拡張機能、パネル
references/04-react-integration.md	useVal、usePrism、@theatre/react フック
references/05-r3f-integration.md	React Three Fiber、編集可能なコンポーネント、SheetProvider
references/06-production.md	状態のエクスポート、アセット、デプロイ、ツリーシェイキング

よくあるパターン

DOM 要素のアニメーション

const obj = sheet.object('Card', {
  x: 0,
  y: 0,
  rotation: 0,
  scale: 1,
  opacity: 1
})

obj.onValuesChange(({ x, y, rotation, scale, opacity }) => {
  element.style.transform = `translate(${x}px, ${y}px) rotate(${rotation}deg) scale(${scale})`
  element.style.opacity = opacity
})

シーケンスの再生制御

const seq = sheet.sequence

// Play once
seq.play()

// Play with options
seq.play({
  iterationCount: Infinity,  // loop forever
  range: [0, 2],             // play seconds 0-2
  rate: 1.5,                 // 1.5x speed
  direction: 'alternate'     // ping-pong
})

// Pause and seek
seq.pause()
seq.position = 1.5  // jump to 1.5s

// Await completion
await seq.play({ iterationCount: 1 })
console.log('Animation complete')

React Three Fiber のシーン

import { Canvas } from '@react-three/fiber'
import { editable as e, SheetProvider } from '@theatre/r3f'
import { getProject } from '@theatre/core'
import studio from '@theatre/studio'
import extension from '@theatre/r3f/dist/extension'

// Dev setup
if (import.meta.env.DEV) {
  studio.initialize()
  studio.extend(extension)
}

const sheet = getProject('R3F Demo').sheet('Scene')

function App() {
  return (
    <Canvas>
      <SheetProvider sheet={sheet}>
        <e.mesh theatreKey="Cube">
          <boxGeometry />
          <meshStandardMaterial color="orange" />
        </e.mesh>
        <e.pointLight theatreKey="Light" position={[10, 10, 10]} />
      </SheetProvider>
    </Canvas>
  )
}

Theatre のコントロール（シンプル）

import { useControls, types } from 'theatric'

function Component() {
  const { color, intensity, position } = useControls({
    color: '#ff0000',
    intensity: types.number(1, { range: [0, 2] }),
    position: { x: 0, y: 0, z: 0 }
  })

  return <mesh position={[position.x, position.y, position.z]} />
}

避けるべき重大なミス

1. 本番環境での Studio

// ❌ Includes studio in bundle
import studio from '@theatre/studio'
studio.initialize()

// ✅ Dev-only initialization
if (import.meta.env.DEV) {
  studio.initialize()
}

2. 本番環境での状態の欠落

// ❌ No animations without state
const project = core.getProject('My Project')

// ✅ Load exported state
import state from './state.json'
const project = core.getProject('My Project', { state })

3. オブジェクトキーの衝突

// ❌ Same key = same object (shared state)
sheet.object('Box', { x: 0 })
sheet.object('Box', { y: 0 })  // Overwrites!

// ✅ Unique keys per object
sheet.object('Box1', { x: 0 })
sheet.object('Box2', { y: 0 })

4. R3F 拡張機能の欠落

// ❌ No 3D controls in Studio
studio.initialize()

// ✅ Extend with R3F extension
import extension from '@theatre/r3f/dist/extension'
studio.initialize()
studio.extend(extension)

5. theatreKey の指定忘れ

// ❌ Not editable
<e.mesh>

// ✅ Requires theatreKey
<e.mesh theatreKey="MyCube">

クイックリファレンス

タスク	解決方法
プロジェクトの作成	getProject('Name', { state? })
シートの作成	project.sheet('Name')
オブジェクトの作成	sheet.object('Key', { props })
値の変更を監視	obj.onValuesChange(cb)
値の読み取り	obj.value.propName
アニメーションの再生	sheet.sequence.play(opts?)
アニメーションの一時停止	sheet.sequence.pause()
位置のシーク	sheet.sequence.position = 1.5
R3F で編集可能にする	<e.mesh theatreKey="Key">
React の値フック	useVal(obj.props.x)
状態のエクスポート	Studio → Project → Export (JSON)