State machines

State machines are a way for defining a graph made by animation states, locomotion states and transitions among them. You might think of a state machine as a graph having nodes (animation or locomotion states) and connections (transitions).

The Atoms UI has a state machine editor where you can define state machines used in Atoms.

For creating animation states right click on the viewport and select "Locomotion" or "State" from the menu.
Alternatively to create a "State", you can click on "add clips" button () inside the viewport and drag and drop animation clip names inside the viewport. The drag and drop only works for one clip at a time.

You create connections by pressing the mouse right button on a node and dragging.

The Inspector

The inspector is where you set up your states and transitions.
When setting up a state, the user has to provide an id which will later be used by several Atoms Behaviour Modules such as the State machine (a unique id is given set as default by the editor). Each state in the same state machine must have a different id.

Animation State

You can assign more than one clip to each animation state or transition. To add more than one clip at the same time, click on the "add clips" button () inside the state machine viewport. A new dialog will pop up, and you will be able to drag and drop clips into the clip list.

If you select multiple clips in the list, you can edit their attributes at the same time.

For "Random" clips (see below) it is possible to edit the random weight of the clip directly inside the clip list.
It is also possible to edit the clip name manually; if an invalid name is set the node in the viewport will show a red exclamation mark.

For each clip, there are three different merge types:

Exclusive : only the exclusive clip is played. This mode has the highest priority. If you have an exclusive clip, all the other clips are ignored. If you have more than one exclusive clip, only the first one is used.
Merge : all merge clips are merged. This has a higher priority over the random mode. Having only a merge clip is like setting its mode to exclusive.
Random : one of the random clips in the list is played. At the end of each clip, another random clip is used.

Finally, there are also seven different motion types: Straight, TurnLeft, TurnRight, TurnUp, TurnDown, BankLeft, BankRight.
Only clips with the same motion mode are merged, randomized or excluded.

The Sync value makes sense for turning clips only (motion type not being straight). With this value, users specify whether or not the turning clip is in sync with the main straight clip.

The angle and blend angle fields are enabled only when the motion type is not straight, and the sync value is set to "Yes".
At each frame, your agent direction changes, and the angle described by the agent direction at the current frame with the direction at the previous frame are used by the blending system.
For instance, when setting a TurnLeft clip with angle value to 1 and blend to 2, our agent will start blending the Straight clip with the TurnLeft clip when the mentioned angle will be between from 1 to 3 degrees (3 is simply the angle value plus the blend value). When the angle is more than 3, the TurnLeft clip will be played.
The angle and blend values are in degrees.

When use clip direction clip is set to "Yes" the user is instructing Atoms to use the clip direction instead of the agent direction metadata. The angle field has meaning in this case too: the clip will start playing when the angle variation between the previous frame, and this frame reaches this value.
The max turn angle field limits the angle variation (degrees) at each frame.

The field tag can be used in two different scenarios:

For random clips, users can control the random probability of each clip with a metadata. Specify the metadata name inside the tag field, then add a metadata with that name on your simulation agents. The metadata value represents the weight used by the random function, it can be a boolean, int or double.
For merge clips (straight), users can control the weight of each clip with a metadata. Specify the metadata name inside the tag field, then add a metadata with that name on your simulation agents. The metadata value represents the weight of the clip, it can be a boolean, int or double.
For additive clips, users can control the weight of that clip on an agent. Specify the metadata name inside the tag field, then add a metadata with that name on your simulation agents. The metadata value represents the weight of the additive clip, it can be a boolean, int or double.

More settings affecting the entire state are available:

The max turn angle field limits the angle variation (degrees) at each frame.
This random loop option (on by default). When an agent enters the given state, and the state has all clips in random mode: Off, a random clip is picked and it is used in a loop; On, a random clip will be picked at random every time playing clip ends.

Whenever a one-shot clip (non-loopable clip) is used inside a state, the transitionis triggered as soon as the animation of that clip ends.

Locomotion State

A locomotion state can be assigned a locomotion asset which must be previously defined in the Atoms UI.

As any other state the id of a locomotion state must be unique.

Users can set the linear/angular max accelerations and average number of frames as they would on the locomotion module.
This values are attached on each locomotion state as each locomotion might need different values to work properly.

Transitions

When connecting two animation states, you can select the transition and assign a transition clip within the inspector.
A light blue dot will appear on your transition in the editor as soon as you assign a clip to it.

The transition UI is similar to the animation state UI. The only difference is that you can specify a blend in and out frame value for the transition itself.

If you don't specify a transition clip between two states and in your simulation you pass from one of those to the other, Atoms will do a straight blend between them. Only the blend in value is used in this case.

If two states do not have a transition, you won't be able to pass from one to the other.

Please always give a name to your transitions, or they won't be evaluated by Atoms.

+

Preview

You can show the preview widget for any state and transition by pressing the "Preview" tab.
The preview widget displays the animation for the selected state or transition. At the bottom, you have controls for playing/scrubbing the animation and a field for changing the joint size.

Before the animation can be displayed, the user must select a valid agent type from the drop down list at the top of the UI.

Yellow circles appearing under the feet show the foot down state for each foot.

By right-clicking on the viewport, a menu will appear with the following options:

Draw grid: enable/disable the grid in the viewport display
Draw Joint Axis: enable/disable the joint axis in the display
Lock Camera: enable/disable the locking on the camera
Reset Camera: resets the translation/rotation of the camera

Navigation Controls:

Alt + left click and drag: Rotate camera
Alt + middle click and drag: Pan camera
Alt + right click and drag: zoom camera

UI Interaction

Please find below a list of mouse actions which can be performed in the node viewport.

Left mouse click on node: Select node (works with Shift and Ctrl modifiers)
Left mouse click on node+ drag: Select node and move
Left mouse click on viewport + drag: Select node with a marquee (works with Shift and Ctrl modifiers)
Right mouse click on viewport: show node list
Right click on a node + drag and drop on another node: create a connection
Ctrl + left click + drag on a connection: break the connection

Please find below a list of keyboard shortcuts:

f : frame graph
Shift + f: frame selection
Backspace or Del : delete selected nodes
Ctrl + Z: undo
Ctrl + Y: redo
Ctrl + C copy
Ctrl + V: paste