Actions

Actions allow you to control a wide variety of elements while your story is playing. For example, you can use an action to play a sound, move a camera, make an actor appear or disappear, or broadcast an event message that kicks off a whole different part of the story.

You can choose to launch an action when the story gets to a specific frame in a clip, or you can make it depend on an event or condition.

Creating an Action

Double-click on a state in the Graph Editor to open the Timeline. For more information on the Timeline and how to use it, see Timeline.

Each state in the Timeline will have tracks underneath. The tracks' only function is to help you visually spread out and organize a state's actions.

You can choose to make an action instant, meaning it will be evaluated for launch on only that frame. Or, you can give the action a duration, or frame range, during which it can launch. Instant actions are shown as a diamond icon while actions with a duration appear as a bar extending over their frame range.

Actions in the Timeline

To add an action to a particular state in the Timeline:

  1. Move your mouse to a track under the chosen state. A vertical line appears showing you the current frame.
  2. At the frame you want to launch the action, right-click in the desired track. A menu appears.
  3. From the menu, choose Create Action. A list of the available actions appears. The actions are divided into categories, and are described below.
  4. Click on the action you want. Its icon appears in the timeline, and its parameters appear in the Properties window.

Create an Action

Once you create the action, you can give it a name in the Properties window. There you can also change its icon color and set its other parameters. Depending on the type of action, you may also want to set an event or condition that must happen before the action will run. See the Timing and Condition section below.

Two things to remember:

  • An action in the Timeline must start on a state's track and within its frame range. Otherwise, it will never run. It may, however, end outside of the state's frame range.
  • You can also specify an action in a transition rather than directly in the Timeline. The action will run when the transition launches.

Changing an Action

In the Timeline, click on an action to see its properties in the Properties window. At any time, you can give the action a new name or color, change its type, or change the other parameters.

If you decide you want to move an action to a different track or frame, you can click and drag its icon to a new location in the Timeline. You can drag one action on top of another, however if they are both represented as diamond icons you will not be able to see them both. We recommend you place the actions on different tracks.

You can mute an action, causing the Story Editor to omit that action when you build the story. To mute an action, do one of the following:

  • Check the Mute checkbox in the Properties window.
  • Right-click on the action in the Timeline and select Mute.
  • Right-click on a track and choose Mute Track Actions. All the actions in that track are muted.

Mute Actions

To delete an action, click to select it and press the Delete key.

Timing and Condition

Aside from their individual properties, each of the action types uses the same Timing (dependent on an event) and Condition settings in the Properties window, as shown here:

Timing

  • On Event: Set an event that must be received for the action to run. Choose "none" if you do not want the action to be dependent on an event.
  • Instant: When checked, the action will evaluate for launch only on its Start Frame. If unchecked, you can enter a Duration and Period.
  • Start Frame: Choose the first frame for this action to launch.
  • Duration: A frame range during which the action can run. Appears when the action is not Instant.
  • Period: The action will be evaluated for launch once in this number of frames. For example, a Period of three ("3") means the action will be evaluated only on every third frame. The default zero means the action will be evaluated every frame. Appears when the action is not Instant.
  • Min Loop: Specify a minimum number of loops a state must play before running the action.
  • Loop Count: Enter a specific loop during which the action can launch. The action must launch between the beginning and end of that specified loop. The default ("-1") means you are not specifying a particular loop.

Condition

The action will launch only if the condition you set is true. For more information, see Conditions.

  • Type: Choose a type of condition. Other parameters appear depending on your choice.

Story Actions

Bind Render Variable

Use this command to bind an already created variable to a shader parameter. This allows you to change the value of the shader parameter during the run of your story.

  • Parameter Index: There are eight reserved index values (0 to 7), each with four parameters (vectors) you can bind to a shader. Choose a parameter index number.
  • X, Y, Z, W: Enter a string in one or more vector fields. The shader can refer to this string to use its value. For example, you can enter the string "red" and a shader can then refer to this string to get its value.

Note: You can use the Set Global Variable and Set Local Variable commands to create the variables.

Broadcast Event

Send an event message that can be used to control the flow of the story or other effects.

  • Event: Choose a type of event to be broadcast.

Checkpoint

Add a checkpoint that a viewer can return to when watching a story in the Story Viewer. In the Story Viewer, checkpoints appear under the Playback menu. For more information, see Using Checkpoints.

  • Label: Provide a label (name) for the checkpoint.

Data Point

Track viewer progress for the analytics system.

  • Data Point: Provide a string that can be used by data analytics tools.
  • Unique: If you set this field to "on", the data point will be registered only the first time this command is encountered, even if the state that contains it runs more than once. If you set this field to "off", the data point will be registered each time the command is encountered during the story.

Exit

Signal that the story is over and should exit. This can be useful given that the story can end in multiple ways.

  • Exit Message: Provide a string that records the reason for exiting, or any other information you might want for analysis.

Interpolate Global Variable

Use this command to interpolate an already set global variable.

  • Name: Enter the name of the variable you wish to interpolate.
  • Goal: Enter the goal (end) value you want to change the variable to.
  • Duration: Enter the duration, in frames, over which the variable chages its value.
  • Interpolation: Choose the type of interpolation.

Interpolate Local Variable

Use this command to interpolate an already set local variable.

  • Name: Enter the name of the variable you wish to interpolate.
  • Goal: Enter the goal (end) value you want to change the variable to.
  • Duration: Enter the duration, in frames, over which the variable chages its value.
  • Interpolation: Choose the type of interpolation.

Preload

Force a state to be loaded into memory. This action overrides the automatic preload setting in the Set Preload Async Mode action. This command can be useful to ensure that the assets needed for a state are ready when the automatic preload does not have enough time.

  • State: Enter the name of the state to be preloaded.
  • Event: Enter a string which will be sent as an event message when the preload is finished.

Set Global or Local Variable

Setting a variable allows you to associate a value to a custom name you create. You can then use and modify that value for your own purposes during the story. For example, you may want to keep track of how many times the viewer looked at a specific trigger.

Local variables have a scope limited to the Story Graph in which they are set. Global variables can be used across Story Graphs.

  • Name: Enter a name for your variable. The name must be unique to the scope of the variable: global or local.
  • Operator: The operators allow you to either set or otherwise modify the value of your variable.
    • Set: Create or change the variable to the value you specify.
    • Add, Subtract, Multiply, Divide: Apply the operation to the current value of the variable.
    • Negate: Flip the sign of the current value. No value needs to be entered for this operator.
    • Toggle: Switch between values of "0" and "1" (or any non-zero value to start) to use as a boolean.
    • Undefine: Remove the variable name allowing it to be used again later. No value needs to be entered for this operator.
  • Value: Enter the value to be used by the operator for this variable.

Set Preload Async Mode

Control the automatic preloading of resources. If enabled, as the story enters a state, the application will start asynchronously fetching the resources needed to play the following states. If you disable automatic preloading, you will need to use Preload actions to do any preloading you require.

  • Mode: Enable or Disable automatic preloading.
    • Auto: Automatically preload resources in an asynchronous background process.
    • Manual: Do not automatically preload resources.

Sound Actions

Play Sound

Play a specified sound with additional settings. For more information on sound settings, see the Audio information in Outliner.

  • Sound: Choose the audio clip from the imported audio file in the drop-down menu.
  • Volume: Scalar multiplier for the volume level. Set to "1" for the default volume level.
  • Pan: Fixed stereo pan balance for the sound. This value ranges from "-1", which is biased toward the left channel, to "1", which is biased toward the right channel. This setting is overridden by directional panning.
  • Emitter: Choose the emitter from the imported Maya elements in the drop-down menu.
  • QuantizationMaster: Choose another sound file to serve as quantization master for this clip, providing the pulse starting point.
  • PulseMultiplier: Scalar multiplier to adjust the timescale of the pulse taken from the quantization master.

Set Pan

Set the panning balance of a sound.

  • Sound: Choose the audio clip from the imported audio file in the drop-down menu.
  • Balance: Scalar used to set the balance of a sound between channels. This value ranges from "-1", which is biased toward the left channel, to "1", which is biased toward the right channel.
  • Duration: Time, in milliseconds, to ramp the volume from the current level to the Goal.

Set Volume

Set the volume of a sound instantly or over time.

  • Sound: Choose the audio clip from the imported audio file in the drop-down menu.
  • Goal: Scalar multiplier used to set the end volume level after ramping is complete.
  • Duration: Time, in milliseconds, to ramp the volume from the current level to the Goal.

Stop Sound

Stop a sound if it is playing.

  • Sound: Choose the audio clip from the imported audio file in the drop-down menu.

Camera Actions

Camera Set Absolute Yaw

Add a yaw angle to the camera. This can be useful to help turn a viewer's camera in a particular direction at a particular time.

  • Yaw: Enter the yaw angle.
  • Duration: The number of frames over which the change will happen. Enter "0" for the change to be instant.
  • Interpolation: Choose an interpolation method for the change in the angle.

Camera Set Desired Yaw

Apply a yaw offset to the camera in order to turn it a desired angle. Generally, this is set on the first frame of a show. Since we don't know at what direction a viewer will start the story, this effect helps the viewer see a more understandable composition.

  • Yaw: Enter the yaw angle.
  • Duration: The number of frames over which the change will happen. Enter '0" for the change to be instant.

Camera Set FOV

Override the authored setting of the camera's Field of View (FOV) to allow dynamic behavior. The camera's FOV changes to the supplied angle over the desired duration.

  • Vertical Angle of View: Enter a vertical angle for the FOV.
  • Duration: The number of frames over which the change will happen. Enter "0" for the change to be instant.
  • Interpolation Choose an interpolation method for the change in the angle.

Camera Set Pitch Offset

Apply a pitch offset to the camera in order to bias it toward the horizon. Generally, this is set on the first frame of a show. Since we don't know at what pitch angle a viewer will start the story, this effect helps the viewer see a more understandable composition. The Set Camera Offset action builds on this idea and provides a way to alter the starting position of the camera based on its position.

  • Pitch Angle: Enter an angle for the initial pitch.
  • Duration: The number of frames over which the change will happen. Enter “0” for the change to be instant.
  • Interpolation: Choose an interpolation method for the change in the angle.

Camera Set Yaw Lock

Lock the camera to a specified yaw setting, not allowing the viewer to change this value. This can be useful when you want the viewer to be looking at a certain position, particularly at the end of a story.

  • Yaw Lock Angle: Enter the desired yaw angle.
  • Mode: Choose to turn on or off the lock.

Map Current HMD Pose To Initial Main Camera Xform

This action is used to calibrate the camera to the current VR (HMD) direction and position.

  • Which: Choose whether to calibrate the camera to translation, rotation, or both.

Parent Actor to Camera

Attach an actor to the camera. Used to keep elements such as title cards in the camera view.

  • Actor: Enter the name of the actor. Actor names can be found in a state's Properties window.
  • Roll: This setting controls whether the parented actor rolls with the device. For example, at the end of a story, if the viewer turns their phone upright, an end title card can roll with the camera.
    • off: The actor does not roll as the device rolls.
    • on: The actor rolls as the device rolls.
    • snap: The actor will snap into position as the device rolls to intervals of 90 degrees.
    • snap_landscape: The actor will snap into position as the device rolls to intervals of 180 degrees.
  • Pitch: Keep the actor's vertical position relative to the camera view as the device looks up and down.

Scale Actor by Aspect

Apply a scale to an actor based on the aspect ratio of the screen. Used primarily for adjusting the layout of title cards or other screen space graphics.

  • Actor: Enter the name of the actor. Actor names can be found in a state's Properties window.
  • Portrait Scale: Enter a scale value for when your story is being viewed in Portrait mode.
  • Landscape Scale: Enter a scale value for when your story is being viewed in Landscape mode.
  • Scale Mode: Choose how the scale will be applied, snap or smooth.

Set Axes Affected By Calibration

Use this action to choose which axes are used by the Map Current HMD Pose to Initial Main Camera Xform action to calibrate the translation of the camera. Normally, the calibration uses the XZ axes.

  • Translational Axes: Choose the axes to be used. You can choose None if the calibration is going to be for rotation only.

Set Camera Offset

Allow users to make positional offsets to the camera instantly, or over time. This action builds on the function of the Camera Set Pitch Offset action. It allows you to start your story with a camera offset from the default position ("Offset from"), and then move the camera position over time to a target position ("Offset to"). During this move, the camera vector will be interpolated according to the setting you choose. This method may be smoother and more seamless than Camera Set Pitch Offset.

  • Offset from x, y, z: The starting offset position of the camera.
  • Offset to x, y, z: The target offset position of the camera.
  • Duration: The number of frames over which the change will happen. Enter "0" for the change to be instant.
  • Interpolation: Choose an interpolation method for the change in position.
  • Orientation Mode: OrientationSnapping will snap the camera to the phone orientation as it rotates between landscape and portrait. FreeOrientation will not.
  • Is Active: Turns this action on or off without losing the information entered here.

Set Camera Up Vector

Give the camera a fixed up vector to avoid rotational issues when two axes become aligned. This essentially locks the story to the camera's up position, so that rolling the viewer's device also rolls the camera, keeping the story window aligned to an axis.

  • Up x, y, z: Enter values for each axis that will be normalized to an up vector. Typically, the axis you want to align with is set to "1" with the others set to "0".
  • Is Active: Turns this action on or off without losing the information entered here.

Set New Interpupillary Distance Scalar

Set a scale for the interpupillary distance for VR displays. You can manipulate this value to make the viewer feel smaller or larger inside the VR world (smaller values make the viewer smaller).

  • Scalar: Enter a multiplier for the interpupillary distance.

Set New Physical to World Scalar

Set the physical to virtual world scalar value for VR displays. For example, entering a value of 100 will multiply real world distances by 100 to get virtual world distances.

  • Scalar: Enter a multiplier for physical to virtual world distances.

Set New Position of Floor Origin for Room Scale VR

In VR environments, the origin point is typically set in the center of the floor. This action allows you to offset the origin to another point in the scene.

  • Offset from x, y, z: Enter values for the offset position of the origin.
  • Interpolation reaction time: Enter a time in seconds to control how fast the camera reacts to the new position setting.
  • Interpolation max speed: Enter a maximum speed, in units per second, that the camera will move to the new position.

Utility Actions

Actor Visibility

Toggle the visibility of an actor.

  • Actor: Enter the name of the actor. Actor names can be found in a state's Properties window.
  • Visibility: Choose to turn visibility on or off.

Draw Text

Draw text to the screen for one frame. This is useful mostly for debugging purposes. The position given in this action specifies the position of the lower left corner of the text string.

  • Position X: Enter the X coordinate relative to the upper left corner of the screen.
  • Position Y: Enter the Y coordinate relative to the upper left corner of the screen.
  • Text: Enter the text you want to appear.

Halt Playback

This action will stop the playback of your story. This can be useful for debugging purposes.

  • Pause Message: Enter a message to be logged when this action occurs.

Mute

This action, along with the Unmute action, allows you to temporarily suspend the playback of the named Story Graph. This might be used to, for example, synchronize certain parts of your story, or for debugging purposes.

This is different from the Mute button available in the Graph Editor, which causes the Story Graph to be excluded from the story build altogether.

  • Story Graph: Enter the name of the Story Graph to be muted.

Render to Disk

Allow the Story Editor to render your story to disk.

  • Render: This field allows you to disable this render without removing the action or losing the information entered into the fields.
  • Path root|relative: Enter the root path and filename you wish to render to. They are given separate fields so that you can easily change the path without changing the file name field.
  • Fixed Time Step: Specify the frames per second you wish to render to. The Use Last Time Step option will make it render at the same Time Step as the previous render action, allowing you to change a range of actions by changing just the first.
  • Resolution: Choose a resolution from the drop down menu, or enter a custom resolution (width and height). The Last choice uses the resolution of the previous render, allowing you to change a range of actions by changing just the first.
  • Write Frames Starting at: Enter a number for the first rendered frame regardless of the frame the render actions starts on.

Send Log Message

Write text to the output log in the Story Editor for debugging purposes.

  • Message: Enter the text of the log message.

Sensor Set Dynamic Filter

When a viewer holds the camera in one position, particularly a hand-held device, there will naturally be some jitter. The jitter, translated into the camera control of your story, can be visually distracting.

This action applies a filter that dampens small camera movements to minimize the jitter effect. Because the jitter is less noticeable as the camera turns more quickly, the action also allows you to reduce the dampening applied by the filter at greater turning speeds. This also prevents introducing too much lag as a dampened camera tries to keep up with a rapid sensor movement.

This action is similar to Sensor Set Lowpass Filter but has more control.

  • Status: Turn this action on or off without deleting the action or losing the settings.
  • Min Speed (rad/sec): The filter will be applied at the From Frequency until the camera moves at this minimum turn speed, at which point the filter amount will start changing to the "To Frequency."
  • Max Speed (rad/sec): Set the turn speed beyond which the filter is applied at the "To Frequency."
  • From Frequency: The frequency of the filter applied when any turn speed is less than the "Min. Speed." Note: smaller numbers apply more dampening.
  • To Frequency: The frequency of the filter applied as the turn speed passes the "Max Speed." Note: larger numbers apply less dampening.
  • Interpolation: Choose an interpolation method for the change in frequency.

Sensor Set Lowpass Filter

When a viewer holds the camera in one position, particularly a hand-held device, there will naturally be some jitter. The jitter, translated into the camera control of your story, can be visually distracting.

This action applies a filter that dampens small camera movements to minimize the jitter effect. This action is similar to Sensor Set Dynamic Filter but applies only one filter level for the duration of the action.

  • Status: Turn this action on or off without deleting the action or losing the settings.
  • Factor: The frequency of the applied filter. Note: smaller numbers apply more dampening.

Set Active RenderGraph

If you have set up render graphs in your scene, for example to be used with post effects, you can choose which one is active using this action. You can reuse the action at any time to switch to another active render graph.

  • Render Graph Name: In the pull-down menu, choose from the render graphs that the Story Editor found in your scene.

Set Time Scale

Set the time scale for the story, making animations run faster or slower.

  • Time Scalar: Enter a multiplier for the speed of playback. For example, entering "2" make the animation clips run twice as fast as normal.

Unmute

This action, along with the Mute action, allows you to temporarily suspend the playback of the named Story Graph. This might be used to, for example, synchronize certain parts of your story, or for debugging purposes.

This is different from the Mute button available in the Graph Editor, which causes the Story Graph to be excluded from the story build altogether.

Note that while a Story Graph can be muted by an action within it, the Unmute action will have to be called by a different Story Graph.

  • Story Graph: Enter the name of the Story Graph to be unmuted.

Video

Set Video Tint Color

Apply a color to the 360 video layer. The video will by multiplied by the values you specify.

  • Tint R, G, B, A: Enter a value between 0.0 and 1.0 for each channel.

Display

Set Display Background Color

Reset the background color for your scene. The default color is black.

This background color will be visible if you use the Set Display Transparency command to fade the device display.

  • Color R, G, B: Set the RGB value of the background color.

Set Display Transparency

Use this command to fade the device display to the background color. This may be useful when, for example, a viewer gets too close to an object, or moves outside of the bounds of a scene.

  • Alpha: Set the target Alpha value of the fade. 1.0 is fully opaque; 0.0 is fully transparent.
  • Time: Set the duration (in seconds) for the smoooth transition to the target Alpha value. To set the target transparency immediately, use 0.0.