With THREE.js

In this guide, you'll learn how to animate a 3D scene by integrating Theatre.js into a THREE.js project. Theatre.js can be used with THREE.js to animate things like the camera, lights, material colors, and more.

#Prerequisites

We'll start by cloning or downloading the code in the THREE.js + bundler project repository.

Alternatively, you can download the ZIP archive of the code and extract it to a folder of your choice.

This code will set up a basic THREE.js scene with a torus know geometry, basic lighting, and a render loop.

Once you have your project cloned, navigate to the project folder in your terminal.

And use a package manager of your choice (e.g., npm or yarn) to install dependencies to the ./node_modules folder.

Or with yarn:

Now, if you open http://localhost:3000 in the browser, you should see something like this:

#Add Theatre.js packages

Now that you have a THREE.js codebase you want to add Theatre.js to, let's install Theatre.js's packages.

#Create an animation

Theatre.js has two essential packages that we need to use in this project. @theatre/studio is the editor GUI that we use to create animations, and @theatre/core plays the animations we've created. If you're using the started project, naviage to the main.ts file and let's import the studio package and initialize the editor:

#Animate the rotation of the TorusKnot

So far, we cannot edit anything using the UI; we need to hook up our THREE.js objects to Theatre.js first. There are a lot of things we could animate in the starting scene, but let's focus on the rotation of the torusKnot for now.

First, create a Theatre.js project using the code below. A Project in Theatre.js is like a save file. Projects are stored in the browser's localStorage, so you don't lose your progress if you close and reopen Theatre.js.

Now we'll add a Sheet. Sheets are a collection of objects which can be animated together.

Next, we'll create a Sheet Object with the props that you want to animate. Sheets contain one or more objects, that can be animated together. You can customize how these props look and behave in the UI, e.g. you can set minimum and maximum values of a number prop by modifying its range.

The last thing to do is to rotate the torusKnot's mesh based on the values of torusKnotObj. This can be done by listening to the changes of the torusKnotObj and updating the rotation of the torusKnot.

Now you're set up to use the Studio to edit and animate the torusKnot's rotation!

#Animating objects

To start animating, we first have to sequence the properties of an object we want to animate. To sequence properties: select an object, right-click on a property (or group of properties) in the property editor panel, and click "sequence". After clicking "sequence", the sequence editor will open. Here, we'll sequence the rotation of the torus knot.

To animate the knot's rotation, we'll create two sets of keyframes by clicking on the yellow diamond next to the rotation prop in the Details Panel, one with the playhead at 0s, and one at 3s. We'll then set the first set of keyframes to 0, and the second set to 1.

You can of course experiment with adding more keyframes.

Once we have some keyframes in the sequence editor, we can play our animation by pressing Space.

To learn more about creating animations, see Working with Sequences.

#Getting ready for production

All the keyframes you created are saved in your browser's localStorage so that your animation will be remembered between page refreshes. However, now you may want a way to save, share/publish, and programmatically play your animation.

To distribute your animation as a part of your website, export your Theatre.js Project by clicking on "THREE.js x Theatre.js" in the outline menu in the top left of the UI.

Then click on the "Export THREE.js x Theatre.js to JSON" button on the right.

This will download a JSON file state.json. Now, we can move state.json to the folder containing our web project, and import the JSON file:

Then replace our code from before:

With this code:

We are now passing the saved animation state to getProject. By doing this,the Theatre.js project will be initialized with the saved animation from state.json instead of the animation saved in localStorage. Don't worry; any changes you make to your animation in Studio will still be saved to localStorage after you do this (your edits will still survive page refreshes).

The last thing left is programmatically playing your animation.

To play an animation, we need to get a reference to its sequence and call the play method on it. Sequence.play accepts a number of options. Here, we are going to instruct Theatre.js to play the animation forever.

In summary, your code will now look like the following GitHub repo.

To check what our page looks like without the Studio, we can press Alt/Option + \ to hide it. Alternatively, we can comment out studio.initialize().

#Deploying to production

When we are done and ready to deploy our webpage to production, we only need to do two things.

1. Make sure that we have the latest project state exported to a JSON file and passed to getProject.
2. Remove studio.initialize and studio.extend.

We can also achieve the last step without manually editing the code every time by using environment-checks and relying on our bundler's tree-shaking feature:

#Next steps

Want to learn more? Take a look at some more in-depth topics from our manual:

Or check out another getting started guide:

---