feat: react timeline components

Author: bbohlender

README.md

@@ -31,7 +31,7 @@ const camera = useThree((s) => s.camera)
 const redPill = useRef<Mesh>(null)
 const bluePill = useRef<Mesh>(null)
 
-useTimeline(async function* () {
+useRunTimeline(async function* () {
   while (true) {
     //transition to look at the red pill
     yield* action({ update: lookAt(camera, redPill.current!, spring()) })

docs/getting-started/0-introduction.mdx

@@ -19,7 +19,7 @@ const camera = useThree((s) => s.camera)
 const redPill = useRef<Mesh>(null)
 const bluePill = useRef<Mesh>(null)
 
-useTimeline(async function* () {
+useRunTimeline(async function* () {
   while (true) {
     //transition to look at the red pill
     yield* action({ update: lookAt(camera, redPill.current!, spring()) })

docs/getting-started/1-what-is-a-timeline.mdx

@@ -72,15 +72,15 @@ yield * reusableFadeIn()
 
 ### Running timelines
 
-- **React**: use `useTimeline(reusableTimeline, deps)`; it wires into `useFrame` and restarts on `deps` change.
-- **Vanilla**: use `start(reusableTimeline)` to get an update function you call each frame with `deltaSeconds`.
+- **React**: use `useRunTimelinereusableTimeline, deps)`; it wires into `useFrame` and restarts on `deps` change.
+- **Vanilla**: use `runTimeline(reusableTimeline)` to get an update function you call each frame with `deltaSeconds`.
 
 ```ts
 // React
-useTimeline(() => reusableFadeIn(), [someDep])
+useRunTimeline(() => reusableFadeIn(), [someDep])
 
 // Vanilla
-const update = start(reusableFadeIn)
+const update = runTimeline(reusableFadeIn)
 // in your render loop
 update(state, deltaSeconds)
 ```

docs/getting-started/2-first-timeline.mdx

@@ -23,14 +23,14 @@ This walks you through building the intro example from scratch.
 import { Text, Environment } from '@react-three/drei'
 import { useRef } from 'react'
 import { Mesh } from 'three'
-import { useTimeline, action, lookAt, spring, springPresets } from '@react-three/timeline'
+import { useRunTimeline, action, lookAt, spring, springPresets } from '@react-three/timeline'
 
 function Scene() {
   const camera = useThree((s) => s.camera)
   const red = useRef<Mesh>(null)
   const blue = useRef<Mesh>(null)
 
-  useTimeline(async function* () {
+  useRunTimeline(async function* () {
     while (true) {
       yield* action({ update: lookAt(camera, red.current!, spring(springPresets.stiff)) })
       yield* action({ update: lookAt(camera, blue.current!, spring(springPresets.stiff)) })
@@ -142,7 +142,7 @@ function Scene() {
   const red = useRef<Mesh>(null)
   const blue = useRef<Mesh>(null)
 
-  useTimeline(async function* () {
+  useRunTimeline(async function* () {
     while (true) {
       yield* action({ update: lookAt(camera, red.current!, spring(springPresets.stiff)) })
       yield* action({ update: lookAt(camera, blue.current!, spring(springPresets.stiff)) })

docs/tutorials/5-parallel.mdx

@@ -25,7 +25,7 @@ The following demo shows how the left cube constantly moves since it has to cove
     '/App.tsx': `import { Canvas, useThree } from '@react-three/fiber'
 import { useRef } from 'react'
 import { Mesh, Vector3 } from 'three'
-import { useTimeline, action, parallel, transition, velocity } from '@react-three/timeline'
+import { useRunTimeline, action, parallel, transition, velocity } from '@react-three/timeline'
 
 async function* moveTo(ref: React.RefObject<Mesh>, to: Vector3) {
 if (!ref.current) return
@@ -35,7 +35,7 @@ yield* action({ update: transition(ref.current.position, to, velocity(1, 5)) })
 function Scene() {
 const cubeA = useRef<Mesh>(null)
 const cubeB = useRef<Mesh>(null)
-useTimeline(async function* () {
+useRunTimeline(async function* () {
 while (true) {
 yield* parallel('all', moveTo(cubeA, new Vector3(-3.5, 0.5, 0)), moveTo(cubeB, new Vector3(1.5, -0.5, 0)))
 // Then nudge both back to origin, racing the first finisher
@@ -126,7 +126,7 @@ import { Vector3 } from 'three'
 function Scene() {
   const cubeA = useRef<Mesh>(null)
   const cubeB = useRef<Mesh>(null)
-  useTimeline(async function* () {
+  useRunTimeline(async function* () {
     while (true) {
       yield* parallel('all', moveTo(cubeA, new Vector3(-3.5, 0.5, 0)), moveTo(cubeB, new Vector3(1.5, -0.5, 0)))
       yield* parallel('all', moveTo(cubeA, new Vector3(0, 0, 0)), moveTo(cubeB, new Vector3(0, 0, 0)))

docs/tutorials/7-vanilla.mdx

@@ -8,8 +8,8 @@ nav: 7
 
 ### Differences to React usage
 
-- In React you use `useTimeline(...)` which ties into the render loop for you.
-- In vanilla you call `start(timeline)` and invoke the returned function every frame with `deltaSeconds` (the library internally clamps large deltas to ~1/30s for stability).
+- In React you use `useRunTimeline(...)` which ties into the render loop for you.
+- In vanilla you call `runTimeline(timeline)` and invoke the returned function every frame with `deltaSeconds` (the library internally clamps large deltas to ~1/30s for stability).
 
 ## Build a scene with `@pmndrs/timeline`
 
@@ -25,7 +25,7 @@ Below is a complete example using two spheres and a camera that alternates betwe
     },
   }}
   files={{
-    '/index.ts': `import { action, lookAt, spring, springPresets, start, timePassed } from '@pmndrs/timeline'
+    '/index.ts': `import { action, lookAt, spring, springPresets, runTimeline, timePassed } from '@pmndrs/timeline'
 import { EffectComposer, RenderPass, EffectPass, BloomEffect, VignetteEffect } from 'postprocessing'
 import { PerspectiveCamera, Scene, WebGLRenderer, Color, Mesh, MeshPhysicalMaterial, SphereGeometry, ACESFilmicToneMapping, AmbientLight, SRGBColorSpace, PMREMGenerator, HalfFloatType, MeshStandardMaterial } from 'three'
 import { TextGeometry } from 'three/examples/jsm/geometries/TextGeometry.js'
@@ -110,7 +110,7 @@ async function* mainTimeline() {
     yield* action({ until: timePassed(0.3, 'seconds') })
   }
 }
-const update = start(mainTimeline())
+const update = runTimeline(mainTimeline())
 
 // render loop
 let last = performance.now()
@@ -215,7 +215,7 @@ async function* mainTimeline() {
     yield* action({ until: timePassed(0.3, 'seconds') })
   }
 }
-const update = start(mainTimeline())
+const update = runTimeline(mainTimeline())
 ```
 
 5) Drive frames and handle resize

examples/showcase/lamborghini.tsx

@@ -13,7 +13,7 @@ import {
   springPresets,
   timePassed,
   transition,
-  useTimeline,
+  useRunTimeline,
   velocity,
 } from '@react-three/timeline'
 import { useEffect, useMemo } from 'react'
@@ -41,7 +41,7 @@ export function Lamborghini(props: any) {
   }, [scene])
   useEffect(() => scene.traverse((object) => (object.castShadow = true)), [scene])
   const camera = useThree((s) => s.camera)
-  useTimeline(
+  useRunTimeline(
     async function* () {
       const wheels = ['RR', 'RL', 'FR', 'FL'].map((name) => scene.getObjectByName(name))
       const frontWheels = ['FR', 'FL'].map((name) => scene.getObjectByName(name))

examples/simple/app.tsx

@@ -1,8 +1,18 @@
 import { Environment, Text } from '@react-three/drei'
 import { Canvas, useThree } from '@react-three/fiber'
 import { Bloom, EffectComposer, Vignette } from '@react-three/postprocessing'
-import { useTimeline, action, lookAt, spring, springPresets, timePassed } from '@react-three/timeline'
-import { useRef } from 'react'
+import {
+  lookAt,
+  RunTimeline,
+  Loop,
+  Sequential,
+  SequentialEntry,
+  Action,
+  spring,
+  springPresets,
+} from '@react-three/timeline'
+import { useControls } from 'leva'
+import { useState } from 'react'
 import { Mesh } from 'three'
 
 export function App() {
@@ -26,31 +36,78 @@ export function App() {
 
 function Scene() {
   const camera = useThree((s) => s.camera)
-  const redPill = useRef<Mesh>(null)
-  const bluePill = useRef<Mesh>(null)
+  const [redPill, setRedPill] = useState<Mesh | undefined>(undefined)
+  const [greenPill, setGreenPill] = useState<Mesh | undefined>(undefined)
+  const [bluePill, setBluePill] = useState<Mesh | undefined>(undefined)
 
-  useTimeline(async function* () {
-    while (true) {
-      yield* action({ update: lookAt(camera, redPill.current!, spring(springPresets.stiff)) })
-      yield* action({ until: timePassed(0.3, 'seconds') })
-      yield* action({ update: lookAt(camera, bluePill.current!, spring(springPresets.stiff)) })
-      yield* action({ until: timePassed(0.3, 'seconds') })
-    }
-  }, [])
+  const { blue, green, red } = useControls({ red: true, green: true, blue: true })
 
   return (
     <>
-      <Text position-y={1} scale={0.3}>
+      <RunTimeline>
+        <Loop>
+          <Sequential>
+            {redPill && red && (
+              <SequentialEntry index={0}>
+                <Action update={lookAt(camera, redPill, spring(springPresets.stiff))} />
+              </SequentialEntry>
+            )}
+            {greenPill && green && (
+              <SequentialEntry index={1}>
+                <Action update={lookAt(camera, greenPill, spring(springPresets.stiff))} />
+              </SequentialEntry>
+            )}
+            {bluePill && blue && (
+              <SequentialEntry index={2}>
+                <Action update={lookAt(camera, bluePill, spring(springPresets.stiff))} />
+              </SequentialEntry>
+            )}
+          </Sequential>
+        </Loop>
+      </RunTimeline>
+
+      <Text position-y={0.6} scale={0.3}>
         Remember: all I'm offering is the truth. Nothing more.
       </Text>
-      <mesh position-y={-1} position-x={-2} rotation-y={(-30 / 180) * Math.PI} scale={0.2} scale-z={0.4} ref={redPill}>
-        <sphereGeometry />
-        <meshPhysicalMaterial emissive="red" emissiveIntensity={0.5} color="red" />
-      </mesh>
-      <mesh position-y={-1} position-x={2} rotation-y={(20 / 180) * Math.PI} scale={0.2} scale-z={0.4} ref={bluePill}>
-        <sphereGeometry />
-        <meshPhysicalMaterial emissive="blue" emissiveIntensity={5} color="blue" />
-      </mesh>
+      {red && (
+        <mesh
+          position-y={-1}
+          position-x={-2}
+          rotation-y={(-30 / 180) * Math.PI}
+          scale={0.2}
+          scale-z={0.4}
+          ref={setRedPill}
+        >
+          <sphereGeometry />
+          <meshPhysicalMaterial emissive="red" emissiveIntensity={0.5} color="red" />
+        </mesh>
+      )}
+      {blue && (
+        <mesh
+          position-y={2}
+          position-x={0}
+          rotation-y={(20 / 180) * Math.PI}
+          scale={0.2}
+          scale-z={0.4}
+          ref={setBluePill}
+        >
+          <sphereGeometry />
+          <meshPhysicalMaterial emissive="blue" emissiveIntensity={5} color="blue" />
+        </mesh>
+      )}
+      {green && (
+        <mesh
+          position-y={-1}
+          position-x={2}
+          rotation-y={(20 / 180) * Math.PI}
+          scale={0.2}
+          scale-z={0.4}
+          ref={setGreenPill}
+        >
+          <sphereGeometry />
+          <meshPhysicalMaterial emissive="green" emissiveIntensity={5} color="green" />
+        </mesh>
+      )}
     </>
   )
 }

examples/simple/package.json

@@ -1,14 +1,15 @@
 {
   "type": "module",
   "dependencies": {
-    "@react-three/fiber": "^9.2.0",
     "@react-three/drei": "10.7.3",
+    "@react-three/fiber": "^9.2.0",
+    "@react-three/postprocessing": "3.0.4",
     "@react-three/timeline": "workspace:^",
     "@vitejs/plugin-react": "^4.6.0",
+    "leva": "^0.10.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
-    "three": "^0.178.0",
-    "@react-three/postprocessing": "3.0.4"
+    "three": "^0.178.0"
   },
   "devDependencies": {
     "@types/react": "^19.1.8",

examples/vanilla/index.ts

@@ -1,4 +1,4 @@
-import { action, lookAt, spring, springPresets, start, timePassed } from '@pmndrs/timeline'
+import { action, lookAt, spring, springPresets, runTimeline, timePassed } from '@pmndrs/timeline'
 import { EffectComposer, RenderPass, EffectPass, BloomEffect, VignetteEffect } from 'postprocessing'
 import {
   PerspectiveCamera,
@@ -114,7 +114,7 @@ async function* mainTimeline() {
   }
 }
 
-const update = start(mainTimeline())
+const update = runTimeline(mainTimeline())
 
 // animate
 let lastTimeMs = performance.now()