Animancer v5.0

Released 2020-07-17

Upgrade Guide

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

  • See the Animancer v4.0 Upgrade Guide first if you're upgrading from a version older than that.
  • The Minimum Unity Version is now 2018.4 and it requires the .NET 4.x scripting runtime (the default for all new projects) because it uses C# language features like expression bodied methods, ref returns, out variables, nameof, and string interpolation.
  • Renamed the AnimancerComponent.Play(object key) methods to TryPlay and changed them to throw exceptions if the key isn't found instead of returning null. Unlike the other Play methods, those ones can only use existing states but not create new ones so this change ensures that they can't be accidentally used when intending to use one of the other overloads and also prevents them from silently doing nothing if the key isn't found.
  • The AnimancerPlayable.StateDictionary indexers (animancer.States[...]) now throw an exception if no state is registered with the specified key.
  • When using a script to access Animancer Events in a Transition, instead of accessing them with transition.Events.Sequence... you now only need transition.Events... (the serialized sequence is accessible via transition.SerializedEvents).
  • MixerState.CreateState has been renamed to CreateChild.
  • Added LinearMixerState.ExtrapolateSpeed to allow parameter values above the highest threshold to increase the Speed of the mixer proportionally.

Major Features

  • Added Custom Fade system for easily fading weights using an AnimationCurve, custom delegate, or the Interpolation.Function enum to tweak your transitions as described here.
  • Added MixerParameterTween for easily interpolating mixer parameters over time.
  • Animancer can now be blended with an Animator Controller assigned to the regular Controller field on the Animator component, though this is subject to several limitations (described on that page).
  • Expanded support for Animation Jobs:
    • Added several examples in the Examples/10 Animation Jobs folder:
      • Two Bone IK: a basic IK system that works on Generic rigs (unlike Unity's built in IK).
      • Damping: applies simple physics based drag to a character's limb.
      • Lean: lets you dynamically lean a character with a slider.
    • Added AnimancerPlayable.InsertOutputJob, AnimancerPlayable.InsertOutputPlayable, and AnimancerUtilities.RemovePlayable to allow Animation Jobs and other playables to be easily added to the graph output.
    • Added AnimancerPlayable.Disposables list for easily registering objects that need to be cleaned up with the graph (mostly NativeArrays).
    • Added AnimancerUtilities.CreateNativeReference to create single element arrays for easy data interactions in and out of jobs.
    • Added several MixerState.CreatePlayable<T> and Get/SetJobData methods to use Animation Jobs in Mixer States instead of the default AnimationMixerPlayable.

Minor Features

  • Added optional Event Names to AnimancerEvent.Sequence and AnimancerEvent.Sequence.Serializable so they can be used to identify events when defining event times in the Inspector and assigning their callbacks in code. #56
  • Improved Transition Previews:
    • You can now pan the camera using Left Click while Right Click still rotates it as before.
    • Added settings to customise the movement and rotation sensitivity.
    • Added a field for selecting a model with a dropdown that remembers previously used assets.
    • It automatically picks a recently used model based on the best match of properties animated by the transition and properties that exist in each model.
    • Added default human model (uses Animancer's DefaultHumanoid if it exists, otherwise it uses Unity's DefaultAvatar which is just the same model with a different texture).
    • Fixed the grid to properly draw behind Sprites.
    • Added the ability to assign a custom floor material or disable the floor entirely because Scriptable Render Pipelines often break the default shader. #53
    • Fixed the internal details display to use the correct margins in both the Inspector and TransitionPreviewWindow.
    • AnimancerState.RecreatePlayable is now overridden by ControllerState and MixerState to retain their parameter values.
    • Fixed the preview time indicator in the TimeRuler to work properly on transitions with a variable AnimancerState.Length (ControllerState and MixerState).
    • AnimationGatherer now stores exceptions in a list for the TransitionPreviewWindow to show instead of logging them.
    • It no longer resets the preview time after an assembly reload.
  • Replaced the "Possible animation type mismatch..." warning in the Inspector with a compact icon:
    • The icon differentiates between warnings (some animated properties aren't present in the Rig) and errors (none of the animated properties are present in the Rig).
    • You can click the icon to have it log a full explanation of the incompatibilities between the animations and the Rig.
    • If this feature is affecting your performance too much while you have a character selected, you can disable it via the Display Options in the layer context menu.
  • Added DefaultHumanoid model (Unity's DefaultAvatar with a different texture) to replace the LowPolyMan.
    • Fixed the finger pose of all Humanoid animations (the LowPolyMan didn't have individual fingers).
  • Improved the SpiderBot model:
    • Cleaned up the naming conventions for bones, meshes, etc.
    • Added foot bones so it can be used with Two Bone IK (one of the Animation Jobs examples).
  • Added Start Time field to ControllerTransition.
  • Added AnimancerEvent.Sequence.AddCallback.
  • Added AnimancerPlayable.Graph to expose the PlayableGraph. #48
    • Removed AnimancerNode.Graph since custom states can now directly access the Root.Graph.
  • Reworked the AnimatedProperty system:
    • Instead of a Type enum parameter, it now has a generic base class with several subclasses: AnimatedFloat, AnimatedBool, and AnimatedInt.
    • Improved the performance of accessing the value.
    • It is now supports accessing multiple properties in a single AnimatedProperty, which is more efficient than making multiple separate AnimatedProperty objects.
    • Added AnimancerJob base class to allow custom Animation Jobs to be easily inserted into the graph. It intercepts the playable output instead of creating its own. This is more efficient and means that it and the Uneven Ground example no longer requires Unity 2019.1+.
    • AnimatedProperty now uses AnimancerPlayable.Disposables to clean up its NativeArrays so you no longer need to manually destroy them.
  • Added various state creation methods:
    • AnimancerLayer.CreateState<T> for creating any state type as a child of that layer (with the same in AnimancerPlayable.StateDictionary for the default layer).
    • MixerState.CreateChild(index, transition) to avoid the need to call CreateState and Apply when manually constructing a mixer.
    • Renamed MixerState.CreateState to CreateChild.
  • Added WarningType enum with various extension methods in Validate to standardise the way optional warning messages can be disabled.
    • These warnings can be disabled individually using WarningType.X.Disable();.
    • Moved the Pro-Only, duplicate event, and unsupported event warnings to this system.
    • Added a warning when attempting to enable IK on a ControllerState or PlayableAssetState.
    • Added a warning when attempting to use Animancer Events on a ControllerStates explaining that it will probably not work as expected. #37
    • Added a warning for when an AnimancerPlayable is created for an inactive GameObject to explain that it needs to be manually destroyed if that object is never activated because Unity won't call OnDestroy otherwise.
    • Added a warning for when adding the same callback to an AnimancerEvent.Sequence multiple times, even if the delegate's Target object is different. This allows it to detect situations where multiple objects are each adding their own version of an event to a shared sequence.
    • Added a warning for when the Animator.speed is changed to explain that AnimancerPlayable.Speed needs to be used instead.
  • Added ObjectPool methods for StringBuilders and replaced all standard usage with them.

Changes

  • Renamed the AnimancerComponent.Play(object key) methods to TryPlay and changed them to throw exceptions if the key isn't found instead of returning null. Unlike the other Play methods, those ones can only use existing states but not create new ones so this change ensures that they can't be accidentally used when intending to use one of the other overloads and also prevents them from silently doing nothing if the key isn't found.
  • The AnimancerPlayable.StateDictionary indexers (animancer.States[...]) now throw an exception if no state is registered with the specified key.
  • Renamed the AnimancerTransition.Events property to SerializedEvents and replaced the original with a property that returns the AnimancerEvent.Sequence directly instead of the AnimancerEvent.Sequence.Serializable.
  • Changed AnimancerLayer.Play to only snap its Weight = 1 if it was at 0 rather than if it was not at 1.
  • Moved the editor version of Animancer.Lite.dll into the Internal/Core folder since having it visible in the root Animancer folder serves no purpose.
  • Mixers now initialize with empty arrays of states and thresholds so they don't need to null check them.
  • ManualMixerState.Initialize(count) now creates the Playable if the Root is set and simply changes the number of inputs if it already existed.
  • Moved various functionality from ManualMixerState into the base MixerState so it can be used by custom mixers that don't want to inherit from ManualMixerState.
  • The AnimancerComponent Inspector now always shows the AnimancerPlayable.IsGraphPlaying field (instead of only when it is paused) and also shows its Speed field.
  • Changed Transition.CreateState to a method because it doesn't make much sense as a property.
  • AnimancerUtilities.AddAnimancerComponent (an Animator extension method) now clears the runtimeAnimatorController.
  • Removed the standard Animation Event receiver methods from AnimancerComponent since they were not very convenient to use anyway.
    • Added EndEventReceiver for receiving Animation Events with the Function Name "End" and moved all the related functionality out of AnimancerPlayable and AnimancerLayer.
  • Removed the context menu functions from AnimancerComponent since they are no longer necessary with the changes to the runtime Inspector.
  • Standardised AnimancerState.ToString instead of having each child class implement its own.
  • Split AnimancerPlayable.AppendInternalDetails out of AppendDescription so it can be used to display updatables, dirty nodes, and disposables in a single label.
  • AnimationType.Sprite now includes any object with only SpriteRenderers in its children without any other Renderer types.
  • Moved GetParameterValue (and Set) to AnimancerUtilities to be usable at runtime.
  • Changed AnimancerPlayable.FrameID from uint to ulong to avoid the need for a cast.
  • ScriptableObjectEditor now displays its message about changes being undone when exiting Play Mode as a warning rather than info and only in Play Mode.
  • AnimancerNode.ConnectToGraph now applies the weight instantly instead of registering the node to be updated.
  • OrbitControls now uses an enum to specify the mouse button instead of an int slider.
  • Changed KeyedList.AddNew to throw an exception if the item is already in another list (since KeyedLists only allow each item to be in one list at a time).

Improvements

  • Added AnimancerUtilities.CreateStateAndApply extension method for ITransition.
  • Added MixerState.DontSynchronizeChildren which can be assigned to the SynchroniseChildren property to easily disable synchronization for all children without needing to allocate an array of the correct size.
  • Added context parameter to various log messages so that clicking them in the Console window will highlight the object that caused the message.
  • Improved the "AnimancerNode.Root is null" exception message to explain that you probably just need to play the state or call state.SetRoot(animancer) before trying to access it.
  • Added Validate.AssertPlayable to give a more useful error message if a state's Playable doesn't exist.
  • Middle clicking on live fields to reset them now deselects the active control since having a field selected would not display the modified value.
  • All Transition.CreateState methods now set the State property.
  • Added more specific exceptions for if you try to initialize a mixer without any clips or thresholds.
  • Added ObjectPool.GetCachedResult for easily creating GUIStyles and other things that need caching.
  • The Display Options Conext Menu functions are now shown on states as well as layers.
    • Added Repaint Constantly option which can be disabled to reduce the automatic repainting rate to an interval specified in the AnimancerSettings (default 0.25 seconds) in case the constant repainting is affecting performance.
  • Improved the 3D Game Kit example to use a CustomFade for the random idle animations and a Mixer for Locomotion instead of the old Blend Tree.
  • Improved the Inspector warning when the Animator.runtimeAnimatorController field is assigned to explain how generic rigs need a second layer.

Fixes

  • Added DummyObjectEditor back in for Unity 2018.4.
  • The Inspector warnings about layers being at 0 weight are no longer shown if the object is inactive since the default DisableAction.Stop resets everything to 0 weight.
  • Fixed an exception when resizing transition arrays in the Inspector on a script without a custom Editor. #38
  • Fixed the AnimancerState.Time property to work properly for Mixers. #51
  • Fixed AnimancerNode.ParentEffectiveSpeed to exclude the root because the delta time value already includes it.
    • This fixes cross fading to advance correctly when the root speed is not 1.
    • Fixed AnimancerNode.EffectiveSpeed to not throw exceptions if the Root is not set.
  • Fixed the MixerState.SynchroniseChildren setter to correctly reset the speed of any children that were previously synced but aren't anymore.
  • Fixed the AnimancerNode.Weight and TargetWeight fields in the Inspector to silently clamp the value to be non-negative instead of letting the underlying properties throw exceptions.
  • Fixed AnimancerEvent.Sequence.CopyFrom and the copy constructor to properly handle nulls.
  • Fixed GUI Layout bug in AnimancerPlayable.DoUpdateListGUI if the lists are changed between Layout and Repaint events.
  • Fixed AnimancerLayer.Play to respect FadeMode.FromStart when the fadeDuration is 0.
  • Fixed various Mixer methods to recalculate the child weights if necessary.
  • Fixed StackOverflowException in LinearMixerState.Initialize(AnimationClip[], float, float).
  • Fixed formatting of AnimancerEvent.AppendDetails.
  • Fixed HybridAnimancerComponent.Play and CrossFade to not set the AnimancerState.NormalizedTime to the default value (negative infinity).
  • Fixed the AnimancerComponent Inspector updatables list to not cause the horizontal scrollbar to appear.
  • Fixed MouseDrag to maintain a fixed distance to the target.
  • Fixed drag and drop into the NamedAnimancerComponent.Animations field to work properly.
  • Fixed the NamedAnimancerComponent Inspector to not hide the Animations fields until Play Mode has been properly entered.
  • Fixed some minor pixel alignment issues in TimeRuler.
  • Fixed Animancer Lite to correctly give a Pro-Only warning when using a custom End Event Time.
  • Fixed the Transition Inspector to allow events to be modified in Play Mode after they have been first used.
  • Fixed TimeRuler to not show looping time indicators for super short animations if they would be so close together that they overlap.
  • Fixed TimeRuler keyboard controls for events.
  • Fixed TimeRuler to properly show looped time indicators when the current time is out of bounds.