Skeletal animation

Intro to Skeletal Animation

Skeletal animation is great for organic-looking character animations. It allows meshes to be deformed by only animating a few 3D points (which are hierarchically organized into a “skeleton”) instead of having to animate each and every mesh vertex.

If you upload a 3D file with a skeletal animation to the console and open it in the scene editor, you will see your animated model.

In the example above, “enable debug lines” was toggled to see the skeleton as well (the yellow hierarchy). The animated model came from Mixamo.

Once uploaded to the console, the assets generated were the following:

The animation-related assets generated are a skeleton and animations but also two assets that are 3dverse-specific: the animation graph and the animation set.

The mesh, the skeleton and the animations can usually be exported quite easily from other tools (Blender, 3ds Max, etc.), but the logic that governs the choice of animation cannot be. This is where the animation graph comes into play.

🦴 The animation graph is where all the logic that governs animations lives. For example, if you want an animation to transition to another one (e.g. an idle animation transitioning to a walking animation), you can configure this in an animation graph.

🦴 The animation set is simply a list of animations. The animation set works alongside the animation graph to provide the animations the graph will work with.

🦴 In the scene itself the animation graph and animation set assets are linked to an entity via the animation controller component.

Animation Graph

An animation graph is an asset which applies some logic to animations. While it is running, the animation graph outputs a pose at each frame. Animation graphs run automatically at the start of each session.

To have control over animation transitions you will have to create a state machine in your animation graph.

While it is running, the animation graph is either in a state or in a transition between states. If it is in a state it computes and outputs the pose of that state. If it is in a transition between states, it blends between the pose of the initial state and the pose of the next state to generate the final pose.

Animation Graph Editor

If you double click on an animation graph in the console, the animation graph editor will open.

The Animation Graph Editor is where you edit your animation graph. An animation graph will output a pose at each frame, and this is where you will define the logic of how it does so. The Animation Graph Editor is composed of different tabs: Details, State Editor, State Machine Editor, Animation Controller Input Editor, Animation Set Editor, Blend Space Editor and Animation Graph Description. It all starts (and ends!) in the State Editor, with the “Root” state, which outputs your final pose.

Animation Graph Editor Tabs

Publish Button

To save your animation graph, press the Publish button.

If publishing succeeded, you’ll get a green notification on the bottom right.

If publishing failed, you’ll get a red notification. The publishing error will be shown in the Animation Graph Description tab.

Examples of publishing errors:

Var node <input name> (<input id>) is referencing an unknown attribute of the input descriptor.

This signifies that you have an input (in the example above the input named speed) which you use in your State Editor but that you deleted from your Animation Controller Input Editor. To fix the error, simply delete all those input nodes in your State Editor and republish.

State machine ID <state machine id> (<state machine name>) does not have an entrypoint

This signifies that your state machine (in the example above the state machine named Main State Machine) does not have an entrypoint state. To fix the error, specify a state as entrypoint in your state machine and republish.

If you have any other publishing errors, do not hesitate to reach out to us in our community page.

Details

Select a node, state, or transition and you can see and edit the details of it. For a simple Animation Sample Node, the details include the playback speed. the start offset (expected to be between 0.0 and 1.0), the animation in question, etc.

State Editor

The state editor is where you edit a state of your animation graph. Each animation graph is composed of a state called “Root” which is the starting point of your animation graph.

A state is composed of nodes. The purpose of a state is to create a pose.

See more info on the nodes you can create here.

[object Object]

Each state is composed of an output pose node. What is connected to the output pose node is the resulting pose of that state.

You can see which state your editing by looking at the path of your state on the top left. In the example above we are editing the state named “Idle State”. To go back to a previous state in the path, like the state called “Root”, click on it in the path.

When you select a state machine node, the state machine will open in the State Machine Editor above the State Editor. You can then modify the states of that state machine.

State Editor Actions:

Move Around
To move around, hold RMB or Mouse Scroll within your state editor and move your mouse.
To zoom in and out, scroll your mouse.
Create Node
Right click on where you to create your node. The nodes that you can create will appear in a drop down menu. For Animation Sample, Blend Space nodes, and State Machine, you will also need to specify the name of your node.
See more info on the nodes you can create here.
Edit Node Details
Click on the node. You will see the node details that you can edit in the Details tab.
Connect Nodes
Drag the output of a node to the input of the next node. The input type and output type need to match.
Delete Transition Between Nodes
Select the connection and press Delete.
Delete Node
Click on the node you want to delete and then press ‘Delete’.
You cannot delete an Output Pose node.

State Machine Editor

The state machine editor is where you edit a state machine node of your animation graph.

A state machine is composed of states. Each state machine has an entrypoint state which is the state outlined in red. The starting point of a state machine is the entrypoint state.

[object Object]

To go back to previous state machines, use the path on the top left.

When you select a state, the state will open in the State Editor below. You can then modify the nodes of that state.

State Machine Editor Actions:

Move Around
- To move around, hold RMB or Mouse Scroll within your state editor and move your mouse.
- To zoom in and out, scroll your mouse.
Create State
- Right click, select “New state” and specify the state name.
Make State Entrypoint
- Click on the state and toggle “Is entrypoint” in the Details tab. You can also rename the state here.
Delete State
- Click on the state then press Delete.
Create Transition Between States
- Click on the arrows button of a state and then click on the state you want it to transition to.
Edit Transition
- Click on the transition and then edit it in the Details tab.
- You can modify the duration of the transition (i.e. how long does it to take to transition from the previous state to the next). You can also modify the transition condition. There are two possible transition conditions:
  - State Played X Times
    - The transition will trigger after the previous state played X amount of times. X is a float that you can modify.
  - An Animation Controller Input is TRUE
    - The transition will trigger when the animation controller input is true. The animation controller inputs you specified as bools will appear in the Transition Condition drop down list. For more info on how to create these inputs, see the Animation Controller Input Editor.
Delete Transition Between States
- Click on the transition then press Delete.

Animation Controller Input Editor

The Animation Controller Input Editor is where you can edit animation controller inputs, which can be used within your animation graph. They will show up in the animation controller component that references your animation graph, which is where you will modify their values.

An input of type bool can be used as a transition condition between states, and an input of type float can be used as input to Blend Space 1D and 2D nodes.

[object Object]

You can change these input values within the scene editor or in the code of your application, by editing the animation controller component data directly.

Animation Controller Input Editor Actions:

Create Input
To create an input specify the input name, the input type and then press the + button on the right.
You can optionally add a category, that’s to organize your inputs in folders called categories.
Give Input Default Value
Once you created the input, you can specify its default value in the widget to the left of the trash can. This is the default value that will show up in your animation controller.
Examples:
Delete Input
Use bool Input in Animation Graph
A bool variable can influence a transition condition between states. When you select your transition condition, you will see the input bools you specified in the input editor, and can select one as the condition.
Use float Input in Animation Graph
A float variable can be used as input of a Blend Space 1D or Blend Space 2D node. For more information on those nodes, check
To use a float input in your State Editor (to connect it to Blend Space nodes), click on the “Grip” button and drag your input to the State Editor.
Then, in your state editor you can connect your input to the input of the Blend Space 1D or 2Dnode.

Animation Set Editor

The Animation Set Editor is where you edit your animation set(s) that are compatible with your animation graph.

In your animation controller, you will have to specify your animation graph and the desired animation set you want to use it with.

Animation sets contain the animations that you want to use in your Animation Sample, Blend Space 1D and Blend Space 2D nodes of the animation graph. When you add one of those nodes (or in the case of blend spaces, when you add a control point) an animation set entry will appear.

Each animation set entry contains:

the path of the node using your animation in your animation graph
the animation reference

[object Object]

You cannot create entries in your animation set. This is done automatically for you when you create an Animation Sample node, or when you add a control point to a Blend Space 1D or Blend Space 2D node. All you have to do in the animation set editor is to specify the animations you want to use for those nodes.

<u>Animation Set Editor Actions:</u>

Create Animation Set
Press the + button and then specify your animation set name in the pop up and press OK.
Now you should have both:
Note: when you open an empty animation graph for the first time, you will be asked to create an animation set automatically. You will always have at least one animation set associated to your animation graph.
Rename Animation Set
Unfortunately you cannot do this in the animation graph editor today. Rename your animation set in your asset browser, like you would with other assets.
Delete Animation Set
Select the animation set you want to delete (it will appear in red). Then press the trash button.
Note: If you only have one animation set, you will not be able to delete it. An animation graph has at least one associated animation set to it.
Set Animation
Open your asset browser in another tab or window and drag the animation asset to the animation set entry to set it. In the example below, the animation “A_Legs_NarutoRun” was dragged to the entry “Main State Machine/Locomotion State/Locomotion Node/Run Control Point”.
Open Animation in Asset Browser

Blend Space Editor

The Blend Space Editor is the tab next to the Animation Controller Input Editor.

The Blend Space Editor is where you will edit the control points of your Blend Space 1D and your Blend Space 2D nodes.

When you click on a Blend Space node the Blend Space Editor should open automatically.

<u>Blend Space Editor Actions:</u>

Move Around
To move around, hold RMB or Mouse Scroll within your Blend Space Editor and move your mouse.
To zoom in and out, scroll your mouse.
Create Control Point
Right click to create control point, specify its name, then press enter.
Edit Control Point Animation
There is an animation set entry in the Animation Set Editor for each control point you create. You can modify the animation there.
View Control Point Coordinates
Hover over the control point to see its coordinates.
Edit Control Point Coordinates
You can hold and drag the control point on the X axis (Blend Space 1D) or X/Y axis (Blend Space 2D) of your Blend Space Editor to edit its coordinates.
Delete Control Point
Select the control point by clicking on it and press Delete.

Animation Graph Description

The Animation Graph Description is the tab next to Details. It simply shows your animation graph description and is mainly a debug tool. If you have any publishing errors, they will show up here.

Animation Graph Nodes

Animation Sample Node

An animation sample node simply samples its given animation and outputs it.

[object Object]

In the details of animation sample node you can specify things like:

animation
- the animation for the selected animation set. This value is synchronized with the corresponding animation set entry in the Animation Set Editor.
playback speed (float)
start offset (float, normalized value between 0 and 1)
- this will force the sampling to start at a given offset of the animation. 0 corresponds to the start and 1 corresponds to the end.
loop

Blend Space 1D Node

A blend space 1D allows you to control the blend between different animations (or control points) through a float input. It is 1D because we define control points along one axis.

Note that when you add a control point in the Blend Space Editor, you can edit its corresponding animation in the Animation Set Editor.

[object Object]

In the example above, my Blend Space 1D has two control points: “Walk Control Point” which is at speed = 0, and “Run Control Point” which is at speed = 1. “Walk Control Point” and “Run Control Point” reference walk and run animations respectively.

In my scene, when I change the value of speed (in my animation controller) to 0.5, then this node will blend equally between Walk and Run animations. If I change the value of speed to 0.75, it will blend both animations but the Run animation will have a weight of 0.75, while the Walk animation will have a weight of 0.25.

[object Object]

Blend Space 2D Node

The idea is the same as Blend Space 1D except now we can control the blend of animations using two float inputs (which correspond to X and Y axis in Blend Space Editor).

[object Object]

State Machine Node

A state machine node is… a state machine! When you click on a state machine node, its state machine will open in the State Machine Editor above the State Editor. The output pose of a state machine node is the output of its state machine.

[object Object]

Blend Poses Node

Blend Poses allows you to blend different poses and give them different weights.

[object Object]

You can give the Blend Poses an arbitrary amount of poses to blend with, and then specify the pose weights. Pose weights should be between 0.0 and 1.0 and should all add up to 1.0.

[object Object]

Select Random Pose Node

Select Random Pose takes an arbitrary amount of input poses and will select to output one of those poses at random. When a state begins to run, the random input is chosen. The random input will stay the same until that state transitions to another one. Then, when some other state transitions to our state again, the random input will be recalculated.

[object Object]

You can also specify Pose probabilities. If specified, probabilities are between 0.0 and 1.0 and should all add up to 1.0.

Incorporating Object in Skeletal Animation

If you have an animated character, you may want to incorporate some other object in its animation. For example you may want to give your character a sword. However, you want the sword to move when the animated character’s hand moves.

This is possible by taking advantage of the skeleton entity that is generated for you upon conversion.

🤺 The skeleton entity mirrors the skeleton, and all the bones of the skeleton fall underneath it. Those bone entities will be given the actual bones’ animated transforms at each frame.

If you add other entities in the skeleton entity hierarchy, those entities will be impacted by the animation as well.

🤺 If you want to give your character a sword, you could add a sword entity underneath its right hand bone, so that its transform is affected by the right hand bone animation.

For all this to work, just make sure that the skeleton root bone entity is well plugged into the animation controller in the “RootBoneEntityRef” slot (if not, just drag the entity to it). F.y.i. the root bone entity has a skeleton reference and a bone reference with a bone index of 0.

Example:

Problem: I want my sword to move with this animation…

Solution:

[object Object]

FAQ

What are the assets and components involved in skeletal animation?

Skeleton asset

[object Object]

A skeleton is a 3D hierarchy of bones. A bone has a name and a transform, and is linked to other bones in a skeleton. Think of a bone more like a joint (point) than a bone (edge between two points). There is also a bone component.

Animation asset

A series of key poses. Each key pose correspond to a frame of the animation. A key pose is a pose of the skeleton, with transforms for each bone of the skeleton.

Skinned Mesh / Rigged Mesh asset

A mesh whose vertices are influenced by bones of a skeleton. A skinned mesh is a mesh with a bone id channel and a weight channel.

Animation Graph asset

An asset which applies some logic to animations. While it is running, the animation graph outputs a pose at each frame.

Animation Set asset

A set of animations that can be used alongside an animation graph. An animation set should only contain animations that are compatible with the same skeleton (i.e. their skeleton reference links to the same skeleton).

Animation Controller component

A component that has an animation graph reference and an animation set reference. If the animation graph has any inputs specified, they will show up in the animation controller.

Bone component

Links entity to bone in skeleton with its bone index attribute. The root bone (boneIndex=0) entity should also have a skeleton reference.

If set up correctly, the entity with bone component will be impacted by that bone’s animated transform. It is useful for incorporating external entities to your animation. For example, if you wanted to give your animated avatar a sword, you could parent the sword to the hand bone entity, and the sword will follow the animated hand movement.

How to set up skeletal animation in your scene?

📄 When you upload a model with a skeletal animation in it, everything will be set up correctly for you. Your scene graph will have the structure below. If ever you want to manually set up scenes with skeletal animation, you must follow this structure.

[object Object]

A more precise view of the entity hierarchy:

Root: Entity with animation controller. A compatible animation graph and animation set are assigned to the animation controller. The skeleton the animation set’s animations depend on should be the same skeleton that is referenced by the skinned mesh entity.

Skinned Mesh: Entity with skeleton reference and mesh reference. The mesh should be a skinned mesh and the skeleton should be compatible with it (e.g. they were converted from the same source file).

Skeleton Root Bone: This entity and its children are a hierarchy that mirrors the skeleton. It is created automatically for you when you upload a file with a skeletal animation. It’s optional.

How to find skeletal animations online and use them in 3dverse?

📄 Go to mixamo.com to:
Download rigged animated models
OR
Upload your own static model, rig it within Mixamo, and then download it as a rigged and animated! (try it, it’s super easy!)

Mixamo download settings:

The download setting “With Skin” will give you a file with the skinned mesh inside of it, the skeleton and the animation. If you are not sure which to choose, choose “With Skin”.

The download setting “Without Skin” will give you a file with just the animation.

Pro tip: If you want to upload multiple animations of the same Mixamo character to 3dverse, you can first upload the “With Skin” character to have the skeleton and mesh. Then you can get other animations of the same character (without the skeleton, mesh, etc.) by downloading “Without Skin”. When you upload the “Without Skin” file to the Console, specify the character’s skeleton in the “Skeleton” option. Then your converted animations will work with that skeleton.

Physics

Animation Sequence