Mesh Animator Documentation

Looking for version 1.x documentation? View it here!

Upgrading to version 2.x from 1.x

Version 2.0 of Mesh Animator introduced sweeping changes that may not be compatible with previous versions. It is recommended to delete the existing MeshAnimator folder from the project, import the new package, and then re-bake any previously baked assets.

Unity version support

Version 2.0 dropped support for older Unity versions and is being built for Unity 2018.3+. If example asset meshes look stretched or corrupt, it's most likely just a version difference issue. Rebake the included example prefabs. Snapshot mode may still work with older Unity versions, but it will not be officially supported.

Overview

Mesh Animator is a toolset for converting and fully animating characters, animated assets, or any other kind of skinned mesh.
Find resources below on how to use Mesh Animator and all it's features. To report any bugs, or for questions not covered in the documentation, please e-mail jschieck@gmail.com.

Topics

• Frequently Asked Questions
• Getting Started
• Bake Window
  • Mesh Animator Modes
  • Information Section
  • Animation Setup
  • Mesh Setup
  • Expose Transforms
  • Bake Preferences
  • Utilities
• Using Mesh Animator
• Snapshot Mode
  • Mecanim Controller
  • Memory Implications
• Shader Mode
  • Using Mesh Animator Shaders
  • Adding Mesh Animator support to shaders
  • Universal Render Pipeline (URP)
  • High Definition Render Pipeline (HDRP)
  • Shader Graph
• Example State Machine

Generated Assets

Using Mesh Animator

Mesh Animator functions much like the legacy Animation component. In it's simplest form, animations are played by calling the Play() method.

public MeshAnimatorBase meshAnimator;
void Start()
{
    meshAnimator.Play("idle");
}

The Mesh Animator component has a few callbacks that can be used.

public MeshAnimatorBase meshAnimator;
void Start()
{
    // called when an animation completes
    meshAnimator.OnAnimationFinished += (anim) =>
    { 
        Debug.Log(anim + " finished."); 
    };
    // called when a new frame of animation is displayed
    meshAnimator.OnFrameUpdated += () => 
    { 
        Debug.Log("Animation frame changed.");
    };
    // called when a MeshAnimator enters or leaves the screen
    meshAnimator.OnVisibilityChanged += (isVisible) =>
    {
        Debug.Log(isVisible);
    };
}

Controlling Mesh Animator with Mecanim

With the convience of Mecanim's state machines, included is an example MecanimMeshAnimatorController.cs script. This script looks at the current state of a Mecanim animator, and plays the appropriate animation on the Mesh Animator. State names MUST match the name of the MeshAnimation and blend trees are not supported.

Example State Machine

Since running an animator with it's own controller when not needed is excessive and hurts performance, included is an example state machine that achieves the same result as the Mecanim controller but more efficiently.

using UnityEngine;
using System.Collections;

public class AnimatorStateMachine : MonoBehaviour
{
    public MeshAnimatorBase meshAnimator;
    public bool crossFade = false;
    void Start()
    {
        meshAnimator.Play();
        meshAnimator.OnAnimationFinished += OnAnimationFinished;
    }
    void OnAnimationFinished(string anim)
    {
        string newAnim = string.Empty;
        switch (anim)
        {
            case "idle":
                newAnim = "run_forward";
                break;
            case "run_forward":
                newAnim = "run_backward";
                break;
            case "run_backward":
                newAnim = "run_left";
                break;
            case "run_left":
                newAnim = "run_right";
                break;
            case "run_right":
                newAnim = "idle";
                break;
        }
        if (crossFade)
            meshAnimator.Crossfade(newAnim);
        else
            meshAnimator.Play(newAnim);
    }
}

Memory Implications

Snapshot Mode Only

With Mesh Animator, depending on the number of vertices, and number of frames in the animation, it is going to take up more memory than a traditional SkinnedMeshRenderer and Animator. However, the performance gains occur on the CPU. Finding a good balance between the two is important. If a character has 5k vertices and 20 animations each a few seconds long, it's not practical to use Snapshot mode.

The best use of Mesh Animator is with low-polygon models with short animations. Each frame of animation is generated and copied from the base, which is why so much memory is needed for larger meshes and longer animations.

A 4k triangle character (like in the example) takes up 500KB of memory. To display a 1 second idle animation baked at 30fps, the system would need approximately 15MB of memory. Memory usage is the same whether displaying 1 character or 1000 characters. A character that has only 400 triangles takes 32KB of memory per mesh, so the same length animation would only take 960KB of memory. Use this information to plan accordingly in the project.

Crossfading animations requires a temporary mesh to be created for the interpolation and adds a little CPU overhead for interpolating the vertex positions. This overhead grows larger the more vertices the mesh has. The temporary meshes are pooled automatically so that Mesh Animators sharing the same base mesh can use it. Crossfading a mesh requires at least 1 extra copy of the base mesh.

Shader Mode

Shader mode uses animation textures to display animation on a mesh. In order to accomplish this and support GPU instancing, custom shaders are needed.

Mesh Animator Code Reference

All Mesh Animator scripts reside in the FSG.MeshAnimator namespace.

Implement as follows:

using FSG.MeshAnimator;

Variables

// The mesh that will be animated
public Mesh baseMesh;
	
// The default animation that will be played if playAutomatically = true
public MeshAnimation defaultAnimation;

// Array of animations on the animator
public MeshAnimation[] animations;

// Playback speed of the animator
public float speed;

// Continue playing animation when the animator is off screen
public bool updateWhenOffscreen;

// Should animation begin playing when the animator is enabled
public bool playAutomatically;

// Reset the animator OnEnable and play the default animation
public bool resetOnEnable;

// The target object to recieve AnimationEvents
public GameObject eventReciever;

// Get the current animation playing
public MeshAnimation currentAnimation { get; }

// The FPS the animations were baked at
public int FPS;

// Callback for when an animation has finished playing
public Action OnAnimationFinished;

// Callback for when the mesh has changed frames
public Action OnFrameUpdated;

// Callback for when the object has entered or left the viewable screen
public Action OnVisibilityChanged;

Public Methods

// Crossfade an animation by index
public void Crossfade(int index, float speed = 0.1f);
meshAnimator.Crossfade(0, 0.25f);
	
// Crossfade an animation by name
public void Crossfade(string anim, float speed = 0.1f);
meshAnimator.Crossfade("idle", 0.25f);
	
// Play the default animation, or resume playing a paused animator
public void Play();
meshAnimator.Play();
	
// Play an animation by name
public void Play(string anim);
meshAnimator.Play("idle");	
	
// Play an animation by index
public void Play(int index);
meshAnimator.Play(0);	
	
// Play a random animation
public void PlayRandom(params string[] anim);
meshAnimator.Play("idle", "idle_bored", "dance", "sit");	
	
// Play an animation after the previous one has finished
public void PlayQueued(string anim);
meshAnimator.Play("wave");
meshAnimator.PlayQueued("idle");
	
// Pause an animator, disabling the component also has the same effect
public void Pause();
meshAnimator.Pause();
	
// Restart the current animation from the beginning
public void RestartAnim();
meshAnimator.RestartAnim();
	
// Get the MeshAnimation by name
public MeshAnimation GetClip(string clipname);
MeshAnimation clip = meshAnimator.GetClip("idle");