Graph Editor

The Graph Editor is the tool you use to construct your story. Once you set up the Story Editor and import your animation clips from Maya, you use the Graph Editor to place the clips in order and add transitions between them.

The Graph Editor

Building a Story

To use an animation clip you have imported into the Story Editor, you include it in a node called a state. A state contains both information about the clip and attributes you can use to control how it behaves. You build your story by adding a series of states to a story graph.

Adding States

To add a state to your story:

  1. Right-click in the background of the Graph Editor. At the bottom of the context menu you see the names of your Maya source files.
  2. Hover the mouse over a source file to see the list of clips included.
  3. Click on a clip name (or Add Empty State) to add a state to the story graph.

Click on your newly added state to select it and see its properties in the Properties window. For more information on a state's properties, including how to control its looping behavior, see States.

You can move a state around in the Graph Editor by clicking and dragging it.

To delete a selected state, press the delete key or right-click and choose Delete Selected.

Adding all clips

When you right-click on the background of the Graph Editor, under each set of available states you will also see the menu option Add all clips. If you choose this command, all of the states for that source file will be added to the story graph with simple transitions between them.

Adding Transitions

Once you have at least two states added to your story graph, you use transitions to tell the Story Editor the order in which they should be played. A transition is represented by an arrow you draw from a source state to a target state.

Dragging a New Transition

Notice that the area of the source state where you drag from changes color when you hover your mouse over it.

Click on your newly created transition arrow to see its properties in the Properties window.

You can also set up a branch condition where a single source state has multiple target states.

Transition Order

For more information on using transitions, including making them dependent on events or conditions, see Transitions.

To delete a selected transition, press the delete key or right-click and choose Delete Selected.

Root and End States

The root state of a story graph is the first one that plays when your story begins. If you have multiple story graphs in your story, each will have a root state, and all the root states begin simultaneously when the story begins.

By default, the first state you add to the story graph will be marked as the root state with a green triangle. To assign a different state as the root state, right-click on it in the Graph Editor and choose Set As Root State.

The Root State

An end state is designated as the last state to play in a story graph. Depending on the flow of your story, you can have multiple end states, or no end state at all.

Assigning an end state adds a red square to that state in the Graph Editor. The icon can be useful to quickly identify potential end points in your story graph.

To set a state as an end state, right-click on it in the Graph Editor and choose Set As End State. A check mark appears next to that menu item.

An End State

If you assign a state as an end state, any transitions coming out of that state will be muted and hidden. But they are not lost, and they reappear if you turn off the end state designation.

State Groups

As you add more states to a story graph, you may find it helpful to visually group them by function or by parts of your story.

In the Graph Editor, creating a group of states gives them a colored background, to which you can add a name or description, and allows you to move them around together in the story graph.

To create a state group:

  1. Select one or more states which you want included. You can drag select them in the Graph Editor window, or you can hold down the Command key (iOS) or Control key (Windows) and click them individually to add them to the selection.
  2. Right-click on one of the selected states. A context menu appears.
  3. Choose Create State Group. A background appears behind the selected states.

A State Group

When you have created a state group, click on the background of the group to select it (it will be highlighted in yellow). You will then see its properties in the Properties window. You can:

  • Change the name of the group
  • Add a comment to the top of the background
  • Change the color of the background.

State Group Background

Once you create a group, you can still interact with each state normally. That includes dragging it to a new position. The group's background rectangle will resize automatically.

However, you can also drag on the background to move the whole group at once. Transition arrows entering or exiting the group will follow.

To add another state to an existing state group:

  1. Select one or more states to add to the group.
  2. Drag the selected states so that at least one of them is over the desired group background.
  3. Right-click on the selected state that is over the background. A context menu appears.
  4. Choose Add to underlying state group from the menu. The selected states are added to the group, and the group background resizes to include the new states.

Adding a state to a group

Once you have added states to a group, you can drag them to new positions, or back where they came from, and the group background resizes automatically.

Adding a state to a group

Note that it is possible to create groups whose backgrounds appear behind states that are not included in the group. Take care that this does not create confusion when you are looking at a state graph. If you have this situation, consider repositioning the states that are not included in the group so that they do not appear in front of the group's background.

To delete a state from a state group:

  1. Select one or more states you want to remove from the group.
  2. Right-click on one of the selected states. A context menu appears.
  3. Choose Remove From State Group. The selected states are removed from the group and the group background resizes to accommodate the states still in the group.

If you delete all of the states in a group, the group background disappears and the group no longer exists.

To delete a group:

  1. Click on the group background to select it.
  2. Press the Delete key or right-click and choose Delete Selected.

Adding Story Graphs

There will often be times when you want your story to have different things going on in different places or times. Or maybe your story progresses in different phases, and you want to look at them separately in the Graph Editor. In order to help keep the flow of your story organized, you can use additional story graphs.

Each story graph shows up in your Graph Editor, and they run simultaneously when your story starts. Each will have its own root state, and can have its own end states.

Tip: To delay an additional story graph from starting until you are ready, use a loop or transition that waits for an event message before it moves on.

Multiple State Graphs

The default story graph you start with is named "Main." You can change that name at the top of the Graph Editor window.

To add another story graph:

  1. Click on Story > Add Story Graph. A dialog box appears allowing you to give the story graph a name.
  2. Type in a name.
  3. Click the OK button. Your new state graph appears at the bottom of the Graph Editor window.

You can delete a story graph by clicking on the trash can icon at the top, as long as at least one other story graph is left.

Adding Reference Stories

The Story Editor allows you to add a reference to a completely separate story file into a story graph. This can be useful if, for example, you have a re-usable section of story to include, or you have multiple people working on separate story files.

To add a reference story:

  1. Right-click on the background of a story graph. A context menu appears.
  2. Choose Reference Story. A dialog box appears allowing you to navigate to the other story directory.
  3. Choose the story file (by default, it will have a .story extension) and click Open. The reference appears as a state group. Note that it may not appear where you clicked, and you might have to zoom out to see it.

Just like a state group, you will be able to move states around, add transitions into or out of the group, and drag the background to move the entire group. However, any changes you make to the referenced story graph, and its assets, will not be reflected in the referenced source.

Story graphs can grow large enough that it becomes difficult to navigate around the Graph Editor window. We've included some navigation aids to make things easier.

  • Hold down the Spacebar or the Option/Alt key and click-drag to pan around the window.
  • Hold down the Shift key and hover over a state or transition to highlight its connections in the state graph.
  • Hold down the S key to highlight all selected nodes in the story.
  • Hold down the Option/Alt key and either right-click or scroll the mouse wheel to zoom.
  • Press the A key to frame all of the states in the window.
  • Press the F key to frame only the selected states in the window. If no states are selected, it will frame all of the states.
  • Press the 0 (zero) key to stack the Story Graph windows and frame all the story graphs in them.
  • Use the mouse wheel to scroll down the list of Story Graphs. Hold down the Command/Control key to accelerate the scrolling.

Controls in the Menu Bar

The Graph Editor Menu

The menu bar at the top of the each story graph in the Graph Editor is mostly the same. The controls, and which story graphs they affect, are described below:

  • Minimize/Maximize: These buttons control the display of an individual story graph within the Graph Editor window.
  • Name: The name of the story graph. You can type a new name in the field, which is also reflected in the list of story graphs in the Outliner.
  • Follow: Toggle this button on to enable the Graph Editor to pan automatically during playback. As your story plays in the Story Viewer, the Graph Editor will follow the currently playing state. This control appears only in the Main story graph.
  • Grid: Toggle this button on to display a background grid in the Graph Editor. States and state groups will snap to the grid, at their center points, when you move them. This control appears only in the Main story graph.
  • Set Background Color: Click this button to choose a background color for the story graph.
  • Delete: Click this button to delete the story graph.
  • Mute: A muted Story Graph is not included when you build and play your story.

Opening the Timeline

The Timeline displays the states of your story in sequence, with tracks that show you the actions created in each state. For more information, see Timeline.

To open the Timeline, double-click on a state in the Graph Editor. The Timeline opens in another tab of the Story window.