Commands

Commands allow you to control a wide variety of elements while your story is playing. For example, you can use a command 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 include commands either while a state is playing (using an action), or as it transitions to another state. For more information, see actions and transitions.

Story Commands

Align Offscreen

This command allows you to move an object just outside of the visible area of the camera frustum. The distance that the actor (object) will be positioned from the camera is based on its z-axis offset from the origin. Therefore, we recommend that the actor be animated away from the world origin so that, when it is aligned, it does not end up at the same position as the camera.

  • Target: Enter the name of the object to be moved.
  • Direction: Choose whether the object is aligned outside of the Left or Right side of the camera frustum.
  • Offset Angle: Enter an additional value to add to the angle that the object is moved outside of the edge of the frustum.

Align Position

Use this command to align the position of a Target object to the position of a Goal object. This will affect the axes of the Target that you specify in the Axes parameter. See also Attach.

  • Target: Enter the name of the object you want to align.
  • Goal: Enter the name of the object you want the Target to align with.
  • Axes: Enter the axes (X, Y, and/or Z) that you want to be affected by the command.
  • Offset X, Y, Z: Enter a value as an additional offset from the aligned position for each axis.

Align Rotation

Use this command to align the rotation of a Target object to the rotation of a Goal object. This will affect the axes of the Target that you specify in the Axes parameter. See also Attach.

  • Target: Enter the name of the object you want to align.
  • Goal: Enter the name of the object you want the Target to align with.
  • Axes: Enter the axes (X, Y, and/or Z) that you want to be affected by the command.
  • Offset X, Y, Z: Enter a value as an additional offset from the aligned position for each axis.

Attach

You can attach one object to another using this command. The attach means that the Target object will maintain a relative position (translation and rotation) to the Parent object until it is detached. See also Align Position and Align Rotation. Use the Detach command to remove the Attach.

  • Target: Enter the name of the object you want to attach.
  • Parent: Enter the name of the object you want the Target object to attach to.
  • Preserve World Transformation: Toggle this parameter On to preserve the current position of the Target object in world space. Otherwise, the offset of the Target from the origin will be transferred to an offset from the Parent object.

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.

Detach

Use this command to detach an an attached object from its parent object. See also Attach.

  • Target: Enter the name of the object you want to detach.
  • Preserve World Transformation: Toggle this parameter On to preserve the current position of the Target object in world space. Otherwise, the offset of the Target to the Parent will transfer back to the world origin.

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.

Proxy Command

Experimental. Internal Use Only.

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 Commands

For information about how to use sounds in your stories, see Using Sounds.

Play Sound

Play a specified sound with additional settings. For more information on audio clips and their properties, see Audio Clips in the Outliner.

  • Sound: Choose the audio clip from the imported audio file in the drop-down menu. You can also browse sound files by clicking on the button next to the menu and choosing a Root Audio Folder.
  • 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 Master Volume

This command multiplies the level of all sounds in your story by a Volume scalar. See also Set Volume.

  • Volume: Enter the value of the multiplier to adjust the level of all the sounds. The default value of "1" will leave the volume level unchanged.

Set Pan

Set the left and right channel balance of a specific sound.

  • Sound: Choose the audio clip from the imported audio file in the drop-down menu. You can also browse sound files by clicking on the button next to the menu and choosing a Root Audio Folder.
  • 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 frames, to ramp the volume from the current level to the goal Balance. When setting this value, keep in mind the frame rate of the story.

Set Pitch

Set the pitch of a specific sound instantly or over time.

  • Sound: Choose the audio clip from the imported audio file in the drop-down menu. You can also browse sound files by clicking on the button next to the menu and choosing a Root Audio Folder.
  • Units: Choose either Semitones or Ratio. Use Semitones to change the pitch by the Goal number of musical half-steps (where there are twelve half-steps in an octave). Use Ratio to multiply the playback rate by the value of the Goal, so that 0.5 will play one octave down, and 2.0 will play one octave up.
  • Goal: When Units is set to Semitones, this parameter has a range of "-36" to "36" corresponding to three octaves down and three octaves up respectively, with value zero indicating no pitch change. When Units is set to Ratio, this parameter has a range of "0.125" to "8.0" for the same octave range, with "1.0" indicating no pitch change.
  • Duration: Time, in frames, to ramp the pitch from the current setting to the Goal pitch. When setting this value, keep in mind the frame rate of the story.

Set Volume

Set the volume of a specific sound instantly or over time. See also Set Master Volume.

  • Sound: Choose the audio clip from the imported audio file in the drop-down menu. You can also browse sound files by clicking on the button next to the menu and choosing a Root Audio Folder.
  • Goal: Scalar multiplier used to set the end volume level after the ramping Duration is complete.
  • Duration: Time, in frames, to ramp the volume from the current level to the Goal. When setting this value, keep in mind the frame rate of the story.

Stop Sound

Stop a sound if it is playing.

  • Sound: Choose the audio clip from the imported audio file in the drop-down menu. You can also browse sound files by clicking on the button next to the menu and choosing a Root Audio Folder.

Camera Commands

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.

Set New Units Per Meter

Use this command to change how many world units map to a meter.

  • Scalar: Enter a value that will be multiplied to the current setting of units per meter.

Utility Commands

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 Particle Emit Rate

Use this command to change the rate for a particle emitter.

  • Particle Name: Enter the name of the particle.
  • Rate: Enter a value for the rate.

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.

Display Commands

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.

Video Commands

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.