Animancer v5.0

Planned Release 2020-??-?? (this page was last updated on 2020-07-03)

  • Animancer v5.0 is currently in development and has reached the Beta phase (feature complete, but the examples and documentation are not ready yet).
  • Upgrading from earlier versions will be free as always.
  • Please create a Github Issue if you have any questions, bug reports, feature suggestions, etc.

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

Major Features

  • Increased Minimum Unity Version to 2018.4 and modified all scripts to use features of the .NET 4.x scripting runtime where appropriate (expression bodied methods, ref returns, out variables, nameof, string interpolation).
  • 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:
    • Generic Rigs only. Humanoids will play the Animator Controller when Animancer is at 0 weight, but anything higher than that will only play the Animancer graph without any blending (Bug Report 1251106).
    • Requires Unity 2019.1+.
    • You control the blending by setting the Weight of Animancer's layers (or using StartFade to transition smoothly), but Unity's AnimationLayerMixerPlayable ignores the weight if there is only one layer (Bug Report 1159548). So if you aren't already using multiple layers you just need to call animancer.Layers.RespectSingleLayerWeight(); for it to work.
    • Features of the Animator like IK and Target Matching will only apply to the Animator Controller but not to the animations you play in Animancer.
    • Adding an AnimancerComponent will still clear the Animator's Controller field. Just re-assign it and ignore Animancer's warning about it having no effect. I'll need to reword that warning before release, but I'm not sure if I want to stop auto-clearing the Controller because Animancer is still intended to be used without one by default.
  • Expanded support for Animation Jobs:
    • Added several (currently barebones) examples in the Examples/10 Animation Jobs folder:
      • Damping: applies simple physics based drag to a character's arm (because I don't have a character with a tail). Uses the DampingJob from the Animation Jobs Samples.
      • Lean: lets you dynamically lean the character's spine to the left or right with an Inspector slider. You can also change the rotation axis to have the character bend forward/back or turn left/right instead. Based on an implementation by ted-hou on GitHub.
      • Two Bone IK: a basic IK system that works on Generic rigs (unlike Unity's built in IK). Uses the TwoBoneIKJob from the Animation Jobs Samples.
      • If you have any suggestions for other similar examples, please use any of the contact options on the Help page.
    • 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.
  • Added Custom Fade system for easily fading weights using an AnimationCurve, custom delegate, or Interpolation.Function enum to tweak your transitions as described here.
    • I haven't made any examples for it yet, but it's pretty simple to use. Just call any of the static CustomFade.Apply methods right after calling animancer.Play normally. Playing anything else after that will automatically cancel the custom fade if it's still in progress.
    • The source code for this system is located in Assets/Plugins/Animancer/Utilities/Custom Fade. Even though it is a Pro-Only feature, it can serve as a supplementary example of how you can extend Animancer without modifying any of its internals and the Interpolation class originated as open source anyway.
    • Added AnimationCurve preset libraries for common easing functions which can be selected from the dropdown menu in the Presets area when editing an AnimationCurve field. Note that these curves were configured by hand with the minimum number of keyframes for efficiency. They do not cover the exact same set of functions as the Interpolation class and any that are the same will have slight differences.
  • 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.

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.
  • Added MixerParameterTween for easily interpolating mixer parameters over time.
  • 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 get a full explanation of the incompatabilities between the animations and the Rig.
    • If this feature is affecting your performance, 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 LinearMixerState.ExtrapolateSpeed to allow parameter values above the highest threshold to increase the Speed of the mixer proportionally. This feature is enabled by default and you can try it out in the Linear Blending example by simply increasing the maximum value of the UI Slider.
  • Added Start Time field to ControllerState.Transition.
  • 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

  • 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 initialise with empty arrays of states and thresholds so they don't need to null check them.
  • ManualMixerState.Initialise(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 are 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.
  • 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.
  • 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.DontSynchroniseChildren which can be assigned to the SynchroniseChildren property to easily disable synchronisation 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 initialise 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.

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 ControllerState.Transition.NormalizedStartTime to not interfere with resetting to the default states.
  • 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.Initialise(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 some minor pixel alignment issues in TimeRuler.
  • Fixed Animancer Lite to correctly give a Pro-Only warning when using a custom End Event Time.