State machine example: Interactive Tutorials

One of the most useful applications for a state machine is to build interactive tutorials. To get started, you can load either:

• The TutorialBuldingDemo file located in the Content Browser.
• The interactive Basics tutorial via the Getting Started tab of Application Home.

Both of these files are structured similarly, so regardless of which you choose you can get started by doing the following:

To view the state machine

1. In the Outliner, turn off Display > DAG objects only.
2. Filter by the term "stage".
3. Select all the stage nodes.
   Note: There will also be a number of "activate_stage" nodes alongside the stage nodes. You do not need to worry about these yet.
   
4. Open Windows > Node Editor.
5. Click the Show Inputs / Outputs button () to display the stage nodes and their connections.

At this point, you can see how the tutorial stage nodes are structured. Some important things to pay attention to include:

• On Activate Script: This is the script node where the bulk of each stage happens. You can view the Python code in the Expression Editor (see below).
• On Deactivate Script: Connect a script node here to clean up after a stage once it's finished. It's good practice to try and keep your stage logic self-contained so that it's easy to move them around or insert/delete them as needed. In the example above, it's clear that a stage0_1 was inserted between stage0 and stage1 at some point during development. It can also be handy to design a universal deactivate script that can be used by all stage nodes, allowing you to simply connect all the On Deactivate Script attributes down the chain for readability.
• Time Slider Bookmark: This is handy for setting up animations at the beginning of a stage, but also for changing the state of a scene between one stage to another. For example, you can keyframe the active camera at the start of the bookmark to have the camera jump to a different spot in the scene at the beginning of the stage. Or you can keyframe an object's visibility to have it appear during one stage but not another.
• Stage progression: Depending on the goal of a stage, the way it progresses to the next stage will differ. Some of the most common ways are:
  • Activating the stage's Condition attribute or using the '-next' flag: Use this method when you need to trigger the next stage on any sort of event, such as when the user clicks a button on a custom window or other UI widget, or when they fulfill some sort of condition (e.g. the moving an object into a specific spot, or opening specific editor). In the latter case, you may need to embed the command inside a scriptJob in order to listen for those events.
  • Activating the stage's End of Animation attribute: Use this for stages that are simply demonstrating something to the user. The next stage will activate automatically once the Time Slider is played to the end.
  • Setting a non-zero Delay value: Use this to give a stage a time limit before automatically progressing to the next stage. Useful if you want to give the user a finite time to explore before moving on.
• Displaying 2D text or images on the UI: This is the best way to give instructions and hints to the user. In the example files above, you can find overlay source code in the following script nodes:
  • overlayBubble
  • overlayDialog
  • controller
  There is also a demo included in Maya to show you what else is possible, which you can run with the code:

  import moverlay
  moverlay.mayaDemo.demoOverlays()
  

  You can find the source code for the demo, as well as the moverlay module itself, in the /Python/Lib/site-packages/moverlay folder of your install directory. For more information on 2D overlays, see Displaying 2D Overlays.

Viewing Activate/Deactivate scripts

Most of the work for a stage happens in its connected script nodes. In both example files above, these are typically named 'activate_stage#' or 'deactivate_stage#'. There are also a number of helper scripts that are not connected to stages, but are often called by them to perform some common tasks. Some examples include:

• overlayBubble: Handles drawing word bubble-style overlays on-screen.
• overlayDialog: Handles drawing dialog box-style overlays on-screen. Unlike bubbles, these can be moved and closed.
• clearOverlays: Delete all bubble-style overlays.
• clearDialogs: Delete all dialog-style overlays.
• populateText: Contains a dictionary of all the text for the tutorial which can be referenced via stage name.
• updateController: Refreshes the text and visibility of the controller.

To view all the scripts for the tutorial

1. Open Windows > Animation Editors > Expression Editor.
2. Click Select Filter > By Script Node Name.
3. Select a script in the upper-left column to view its contents.

Both example files are fully commented and documented for convenience.