Animancer v6.0

Released 2020-12-04

Upgrade Guide

When upgrading to a newer version of Animancer, you must delete any previous version from your project first.

Here is a summary of how to modify a state class to accomodate the new changes.

Old

class CharacterState : IState<CharacterState>
{
    // Expression Bodied Method:
    public virtual bool CanEnterState(CharacterState previousState) => true;

    // Regular (Block Bodied) Method:
    public virtual bool CanExitState(CharacterState nextState)
    {
        return true;
    }

    public virtual void OnEnterState() { }
    public virtual void OnExitState() { }
}

New

class CharacterState : IState// Remove the generic argument from IState.
{
    // Change the Can... methods to properties.

    // Expression Bodied Property:
    public virtual bool CanEnterState => true;

    // Regular (Block Bodied) Property:
    public virtual bool CanExitState
    {
        get
        {
            return true;
        }
    }

    // No change to OnEnterState or OnExitState.
    public virtual void OnEnterState() { }
    public virtual void OnExitState() { }
}

The old previousState and nextState that were passed into CanEnterState and CanExitState are now accessible via static properties in StateChange<CharacterState> as well as several other options explained in the State Change Details section.

Major Features

Native Animator Controllers

Added proper support for Native Animator Controllers (ones assigned to the regular Controller field on the Animator component):

  • Adding an AnimancerComponent no longer clears that field or collapses the Animator Inspector.
  • The AnimancerComponent Inspector no longer displays the Animator fields nested inside itself since they are now all usable andthe Controller field doesn't need to be highlighted as a warning.
  • Replaced the Basics/Simple Hybrid example with Animator Controllers/Hybrid Basics.
  • Added Controller State Generator to Weaver which can procedurally generate a class that inherits from ControllerState with properties for directly accessing the parameters of a specific Animator Controller asset.
  • Added Generate Transition context menu functions on everything inside Animator Controllers (States, Blend Trees, etc.) which will generate Transition Assets from them.

Animancer Tools

Added the Animancer Tools window which can be opened via Window/Animation/Animancer Tools and has 5 panels:

  • Modify Sprites: allows you to modify the rect, pivot, alignment, and borders of multipl Sprites at once.
  • Rename Sprites: allows you to rename multiple Sprites at once.
  • Generate Sprite Animations: allows you to generate animations from Sprites based ontheir names.
  • Remap Sprite Animation: allows you to change an animation to use different Sprites.
  • Remap Animation Bindings: allows you to change the Hierarchy paths used by an animation. This is particularly useful for bone animations if you want to rename the bones in a model.

Improved State Machines

Improved the Finite State Machine system:

Flexible Mixer Transitions

Mixer Transitions can now use either AnimationClips or Transition Assets (any ITransition that inherits from UnityEngine.Object) for their children, meaning that you can now fully set up Nested Mixers using transitions instead of in code.

  • Renamed ManualMixerTransition.Clips to States and changed it from an AnimationClip[] to an Object[].
  • Added several AnimancerUtilities.TryGet... methods that take an Object and output a particular value from it as an AnimationClip or the corresponding value from an ITransition.

Minor Features

  • Animancer Events:
    • The AnimancerNode context menu now shows the details of all Animancer Events instead of only the End Events.
    • Added AnimancerEvent.Sequence.RemoveCallback. #77
    • Added a startIndex parameter to AnimancerEvent.Sequence.IndexOf and IndexOfRequired (default value 0).
    • Added equality operators to AnimancerEvent.
    • Added AnimancerEvent.Sequence.Serializable.SetNormalizedEndTime.
    • Added ITransitionDetailed.Events and SerializedEvents.
    • Added context menu functions to the TimeRuler for all the functions that can be executed via keyboard controls.
  • Added State as an abstract class that implements IState using virtual methods so you can inherit from it to avoid needing to specify all 4 members of IState yourself.
  • Added Initialize 8 Directions function to the Thresholds menu for MixerTransition2D.
  • Added ITransitionDetailed.AverageAngularSpeed and AverageVelocity.
  • Added AnimancerPlayable.SkipFirstFade to control whether playing an animation with the Base Layer at 0 Weight should snap the Weight to 1 (as it did previously) or allow the fade to play normally (so that it can fade from the Native Animator Controller).
  • Added AnimancerEditorUtilities.IsNaN for Vector2 and Vector3.

Changes

  • Renamed AnimancerLayer.Play(object) to TryPlay to match the name used in AnimancerPlayable and AnimancerComponent.
  • Renamed AnimancerNode.EditorName to DebugName and made it available in Development Builds as well as in the Unity Editor.
  • Renamed ControllerState.Parameter to ParameterID and cleaned up its usage:
    • It is now a readonly struct.
    • Added a constructor that takes both a name and hash (but doesn't verify them).
    • Float1ControllerState now exposes its ParameterID directly instead of having separate properties for the name and hash (same for the 2 and 3 variants).
  • Changed AnimancerState.Duration to properly account for the End Time.
  • Changed AnimancerState.RemainingDuration to properly account for the End Time and negative speeds and not give different results for looping animations since End Events don't work any differently for them.
  • Changed AnimancerState.IsPlaying to not be virtual and added OnSetIsPlaying instead since only the setter should ever be overridden.
  • Changed AnimancerUtilities.Wrap01 and AnimancerUtilities.Wrap to not be extension methods since they aren't used that often.
  • State Machines:
    • Changed StateMachines to not allow the state to be set to null unless you call SetAllowNullStates first. This assertion is only performed in the Unity Editor and Development Builds.
    • Removed StateExtensions.CanEnterState since it is too similar to the IState.CanEnterState property.
    • Removed the DelegateState constructor since object initializer syntax is clearer anyway.
    • Removed the InterruptManagement.Character script and modified its CharacterState to inherit from Characters.CharacterState now that StateBehaviour is no longer generic.
    • Changed the StateMachine<TState>.InputBuffer.StateMachine to a readonly field.
  • Animancer Events:
    • Removed the Inspector toggle from event times which was previously used to remove them.
    • Changed the Add Event button in the Inspector into an X to remove the selected event (while one is selected).
    • Changed AnimancerEvent.Sequence.SetCallback to trigger OptionalWarning.DuplicateEvent if necessary.
    • Changed AnimancerEvent.Sequence methods that modify callbacks to throw an ArgumentNullException if the callback is null rather than just logging an assertion.
    • Moved AnimancerEvent.Sequence.Serializable.DummyCallback out to AnimancerEvent and added a Dummy method so that it has a proper name instead of a compiler generated name for an anonymous method..
  • Inverse Kinematics:
    • Changed AnimancerPlayable, AnimancerLayer, and MixerState to store whatever IK flags you set (ApplyAnimatorIK and ApplyFootIK) so that when a child is added it can get the same flags.
    • You can disable the static AnimancerNode.ApplyParentAnimatorIK and ApplyParentFootIK properties to prevent children from receiving their parent's flags.
    • Added the IK flags to AnimancerNode.AppendDescription.
    • Removed IHasIK and merged it into IPlayableWrapper.
    • Removed AnimancerPlayable.DefaultApplyAnimatorIK and DefaultApplyFootIK.
  • Removed AnimancerPlayable.LayerList.RespectSingleLayerWeight since it is now handled by AnimancerPlayable.SkipFirstFade.
  • Removed AnimancerEditorUtilities.GetIsInspectorExpanded and SetIsInspectorExpanded since they are now unused. They were just wrappers around UnityEditorInternal.InternalEditorUtility methods anyway.
  • Removed AnimancerUtilities.IfMultiComponentThenChangeType.
  • Removed the ability to Ctrl + Shift + Click on states in the Inspector to queue them to Cross Fade in a sequence (and the context menu function) since it was more complex to maintain than its usefulness warranted.

Improvements

  • The Time bars displayed on states in the AnimancerComponent Inspector now scale their height proportional to the AnimancerNode.EffectiveWeight.
  • Improved Timeline track binding support:
    • Added OptionalWarning.PlayableAssetAnimatorBinding in case a PlayableAssetState tries to bind to the same Animator as Animancer.
    • The IsPlaying state is now propogated onto all tracks.
    • Tracks which don't require an object to bind will now properly create their output and are shown in the Inspector as a simple label without an Object field.
    • If a binding has the wrong type, it is now highlighted as a warning in the Inspector.
  • Optimised AnimancerEvent.Sequence methods that search for a particular item.
  • Added Remove function to the event sub-menus of the AnimancerState Inspector context menu.
  • Improved the AnimationGatherer to be able to gather clips and transitions separately.

Fixes

  • Implemented a workaround for the Serialized Array Initialization Bug for Transitions: if all the fields of a transition are at the default values of their type (i.e. Fade Duration and Speed at 0 rather than the 0.25 and 1 set by their field initializers) then assigning its main object (i.e. the AnimationClip for a ClipTransition) will initialize its values properly.
    • Removed the Reset Transition Context Menu Function since it was mainly just a manual workaround for that issue. Inspector Gadgets has Context Menu Functions to Reset, Copy, and Paste any serialized field (and many others).
  • Fixed AnimancerLayer.Play(state, fadeDuration, fadeMode) to set the Weight = 1 if it redirects to Play(state) (usually due to having fadeDuration <= 0).
    • Removed AnimancerEditorUtilities.TopologicalSort since it is no longer needed.
  • Fixed AnimationBindings.GetBindings to allow gathering multiple times per frame by default and only disable it for GUI calls.
  • Fixed the TransitionPreviewWindow models list to automatically remove duplicates.
  • Fixed TransitionPreviewWindow to not cause errors when it instantiates a copy of an object that has [RequireComponent] attributes on its components which create a circular reference (A requires B and B requires A). It doesn't seem to be possible to destroy such components so it now just disables all undesirable components instead of destroying them.
  • Fixed the TransitionPreviewWindow to properly initialize the camera when the target has no bounds.
  • Fixed the keyed StateMachine to properly register the default state provided in the constructor.
  • Fixed AnimancerGUI.DoOptionalTimeToggle to properly indicate when the selected objects have different values.
    • Fixed AnimancerState.EventRunner to allow events to be assigned before the AnimancerNode.Root is set.
    • Fixed EventSequenceDrawer to avoid causing errors when multiple objects are selected with different values.
  • Fixed AnimancerUtilities.Wrap01 and Wrap to never return the maximum value (unlike Mathf.Repeat).
  • Animancer Events:
    • Fixed AnimancerState.EventRunner to allow events to be assigned before the AnimancerNode.Root is set.
    • Fixed EventSequenceDrawer to avoid causing errors when multiple objects are selected with different values.
    • Fixed AnimancerEvent.Sequence.Serializable.OnBeforeSerialize to not cause an exception if called when there is no Editor.EventSequenceDrawer.Context.Current.
  • Fixed UnityVersionChecker to get properly removed when overriding Animancer Lite with Animancer Pro by moving it into the ReadMe.cs file.
  • Fixed the AnimancerState Inspector context menu to disable the Invoke function for events using the AnimancerEvent.DummyCallback.
  • Fixed TransitionPreviewWindow.GetCurrentState to not throw an exception if the state doesn't exist.
  • Fixed the AssemblyInfo.cs file to be properly included in Animancer Pro.