In this article

# πŸŽ“ Learn the basics

# Prerequisites

This page assumes that you have a project with Theatre.js up and running and you can see the Theatre.js studio outline panel icon () in the top left of your web page.

If you don't yet have a project with Theatre.js running, go back to the Set up section of The Guide.

# Setting the scene

First, let's learn about Projects, Sheets, and Objects.

See this step in the video tutorial

# Creating a Project

A Project in Theatre.js is like a save file. Projects are stored in the browser's local storage, so you don't lose your progress if you close and reopen Theatre.js. Later in this page, you'll learn how Projects can be exported and saved as a file so you can share them with teammates; for example, by putting the saved Project in a git repo.

Calling core.getProject(projectID) either creates and returns a new Project, or returns an existing Project if one with the name projectID is stored in your browser's local storage.

// create a project
const proj = getProject(
  // the ID of the project is "My first project"
  "First project"
);

# Creating a Sheet

A Sheet is like a component in React, a composition in After Effects, or a folder that groups together related parts of an animation into a reusable template. It contains a number of Objects (which we'll introduce next) that are animated together.

You can create a new Sheet or get an existing Sheet by calling proj.getSheet(sheetID).

// create a sheet
const sheet = proj.sheet(
  // Our sheet is identified as "Scene"
  "Scene"
);

We can learn more about Sheets later. For now, let's move on to creating our first object.

# Creating an Object

You can create a new Theatre.JS Object or get an existing one by calling sheet.object(objectID, propsAndValues). You define the "props" (properties) and respective values of an Theatre.js Object as follows:

// create an object
const obj = sheet.object(
  // The object's key is "First object"
  "First object",
  // These are the object's default values (and as we'll later learn, its props types)
  {
    // we pick our first props's name to be "foo". It's default value is 0.
    // Theatre will determine that the type of this prop is a number
    foo: 0,
    // Second prop is a boolean called "bar", and it defaults to true.
    bar: true,
    // Last prop is a string
    baz: "A string",
  }
);

Note that Theatre.js Objects are not just JavaScript objects. From now on, we will use the word Object to mean a Theatre.js Object. We will see how to read, and react to, the changing values of a Theatre.js object in the next section.

Projects, Sheets, and Objects are the most basic concepts of Theatre.js. Now that we know what they are and have set them up, we can see how all our Projects, Sheets and Objects show up in the "outline panel" (the panel on the left).

If we select an Object's name in the outline panel, that Object's "details panel" shows up. In the details panel you can change the value of a prop.

# Reading Object values in code

Learn this step from the video tutorial

To read the value of a prop, you can use object.value.

console.log(obj.value.foo); // prints a number
console.log(obj.value.bar); // prints a boolean
console.log(obj.value.baz); // prints a string

If you change these values in the details panel, and then console.log(object.value) again, you will see the changed values.

# Listening to Object value changes

Learn this step from the video tutorial

At some point you will want to write code that can react to an Object's value changingβ€”for example when you change the value in the details panel, or as we will see shortly, when an animation is playing.

You can use object.onValuesChange(callback) to accomplish this. Whenever the value of a prop on the Object changes, the callback function you provide to object.onValuesChange is called. Importantly, Your callback function is passed an argument which is a JavaScript object that contains all the values of the Object, including the updated values.

// Calls the callback every time the values change
const unsubscribe = obj.onValuesChange(function callback(newValue) {
  console.log(newValue.foo); // prints a number
  console.log(newValue.bar); // prints a boolean
  console.log(newValue.baz); // prints a string
});

// stop listening to changes after 5 seconds:
setTimeout(unsubscribe, 5000);

# Hooking up our Object to HTML

Learn this step from the video tutorial

The object.onValuesChange(callback) method allows us to connect our Objects to visual elements, like HTML elements, WebGL, or even IOT devices.

// Create a div to animate
const div = document.createElement("div");
div.style.height = "50px";
div.style.width = "50px";
div.style.background = "LightSeaGreen";
// Add the div to our web page
document.body.append(div);

obj.onValuesChange((newValue) => {
  // obj.foo will now set the horizontal position of the div
  div.style.left = newValue.foo + "px";
});

# Animating

Learn this step from the video tutorial

So far, we've only changed the values of props using the details panel. In order to animate prop values, we can put them in a "Sequence". A Sequence is a collection of props and their respective animations.

Here's how you put a prop in Sequence: In the details panels, right click on the label of a prop, and choose "Sequence" from the dropdown menu. The "Sequence Editor" should pop up at the bottom of your screenβ€”this is where the animations are made and played.

Now that you know how to put a prop in Sequence, Here's the recipe for a simple animation:

  • Put the number valued prop "foo" from earlier in the tutorial in Sequence;
  • with the sequence editor now open, change the value of "foo" in the Details Panel;
  • this change should cause a small diamond appear to the right of "foo" in the Sequence Editor, this is a "Keyframe";
  • move the animation "Playhead" line by clicking somewhere in the empty space on the right side of of the Sequence Editor;
  • change the value of "foo" in the Details Panel again to create a new Keyframe at a new time in the Sequence; and
  • finally, move the playhead back to the first Keyframe and press space to see the animation play out πŸ˜ƒ

Cool! You can see how Theatre.js animates smoothly between the two Keyframe values.

If you want to get nuanced and adjust how Theatre.js smoothly animates between Keyframes, you can use the "Curve Editor" inside the Sequence Editor. Open the Curve Editor for a prop by clicking on the small curve icon () beside a prop's name in the Sequence Editor's left side. If you already have a couple of Keyframes, you should now see a Curve (representing the transition between those two Keyframes) at the bottom of the Sequence Editor. Change a curve by grabbing and dragging the handles the protrude from its beginning and end.

# Sharing Projects

Now that you've made a simple animation Project, you may want to share it with friends so that they can play around with it too. One way to do this is to export the state of your Project to a file, put the exported Project file the same folder as your code (or a folder nearby your code), add a line of code that imports the Project file into your animation code, then share the folder that contains all your code and Project file with your friends. Let's try it out.

  1. In the outline panel, click on the name of the Project (instead of an Object) that you want to export.
  2. Now on the right side of your screen, you should see a Project panel with a button that says "Export _ Project to JSON", click it!
  3. Your Project file state.json should start downloading, find the downloaded file and move it to a folder closer to your code.
  4. In your code, add an import for the Project file:
import state from "<relative-path-to>/state.json";
  1. Finally, you can add a second { state } argument to your core.getProject call to load the Project from the imported Project file:
const proj = getProject("First project". { state });

# Conclusion

Now you know the basics of creating animations with Theatre.js! Theatre.js has a lot more to offer, from our community to many more programmatic animation features and concepts.

Was any part of these docs confusing, missing something, or erroneous? If so, reach out to us on Discord (opens new window)! we'd love to hear about your experience learning Theatre.js, and anything you'd like to see added or fixed. Want to fix or add something yourself? Edit this page on GitHub (opens new window)!

Thanks for reading! we look forward to seeing what you bring to life with Theatre.js!

Want to learn more? Keep reading for a sample of some features discussed in the In Depth docs.

# Introduction to in depth features

# Playing an animation with code

// reset the Sequence to the start (0 seconds)
sequence.position = 0;

// play the Sequence from the current position to sequence.length
sequence.play();

Learn more in the Sequence section of the In Depth docs β†’

# Custom prop types

strings, compponds, numbers customization, strig kusters

const obj = sheet.object("box", {
  x: t.number(0, {
    nudgeMultiplier: 0.25,
  }),
});

Learn more in the Prop types section of the In Depth docs β†’

# Making more instances of a Sheet

See Sheet instancing in the video tutorial

Here is an example of 3 instances of the same Sheet running at the same time. Each white box on the screen is attached to a different instance of the same Sheet. They all have the same animation Sequence, but the animation runs for each of them independently.

for (let i = 0; i < 3; i++) {
  // All three Sheet instances use the "Box Scene" Sheet and Sequence.
  // This way they all have the same animation.
  const sheet = proj.sheet("Box Scene", "Instance " + i);

  const obj = sheet.object("box", { y: 20 });
  obj.onValuesChange((newValue) => {
    div.style.top = newValue.y + "px";
  });

  const div = document.createElement("div");
  div.style.left = i * 60 + "px";
  div.style.height = "50px";
  div.style.width = "50px";
  div.style.background = "white";
  document.body.append(div);

  div.addEventListener("click", () => sheet.sequence.play());
}