Why does the Playables API exist, when should I use it rather than Mecanim (Animator Controllers)?

After untangling Animation from Mecanim/Animators from Anima2D from 2D Animation Package + 2D IK from Unity Animation, I just today noticed Playables API. I saw a reference to it in the Animancer thread.

Why does Playables exist? I've read the documentation. It seems it's meant to restore some of (what I'm inferring was) the "simpler" legacy Animation system, at least to some extent. Maybe. The tutorials and articles I've found while learning about Unity and 2D Animation have all focused on Mecanim (Animator Controllers, Animator Components, and .anim Animation assets).

What is its target situation distinguished from Mecanim? Is it actively maintained? Is it commonly used and I just somehow missed it? And is it commonly used alongside Mecanim or instead of Mecanim?

I'm looking more for some insight into its update status, best practices, and its place in common animation workflows, rather than the functionality bullet points in the docs. Basically: use? (if so, when) ... or ignore?

 

The Playables API gives you much more low level control over your animations which isn't possible in Animator Controllers. As a simple example, you can add an animation to a Playable Graph at any time where Animator Controllers require you to set up all your states in the Unity Editor using the Animator window. The Why Replace Mecanim page in the Animancer documentation explains some of the main problems with Animator Controllers and Animancer is built on the Playables API, so whenever it says something like "Animancer doesn't have that problem" you can just pretend that it says "The Playables API allows you to build a system which doesn't have that problem".

It's not really an animation system, it's a low level tool which can be used to build an animation system. So it's target audience is anyone who doesn't want to be limited by Animator Controllers and has the time to decipher how to use it (the documentation is terrible, even by Unity standards) and build the features they need on top of it. For example, it doesn't have any cross fading to create smooth transitions, you need to make your own system that manipulates its blend weights over time to achieve that.

It still gets bug fixes and new features like the Animation Rigging package which is built with it.

I have no idea how many people directly use the Playables API, but I suspect it's a pretty small number since it's not very convenient to use on its own.

I also don't know how most people use it. Animancer's Hybrid Mini Game example shows how you can use Animator Controllers alongside Playables and I know some people do make use of that feature, but I suspect that's mostly limited to people who are in the middle of a project where they have already built a lot of stuff around their existing Animator Controller.

 

That is exactly what I wanted to know. Thank you very much.

 

Awesome post. Being helpful and forthcoming with your knowledge, and NOT just pushing your product, is a great marketing strategy. You sold me on buying Animancer rather than building my own!

 

@Kybernetik

I know it's over a year later, but I wanted to thank you for posting this information (and plugging Animancer). We do a lot of work with runtime GLTF model importing (via the Piglet plugin), and we always wondered why all the GLTF plugins used Legacy instead of Mecanim, but it looks like the answer is that Mecanim doesn't support runtime creation of controllers and states (and is missing basic things like setting the wrap mode at runtime).

I'm still reading through your documentation, but it looks like Animancer should support runtime creation of an animation system after a GLTF file get's imported, does this sound correct?

If so it might be worth reaching out to the various GLTF importer plugins Piglet, GLTFUtility, glTFast (which all primarily deal with runtime imports and therefore use Legacy) and seeing if it's worth a direct integration of your package into theirs (so it becomes officially supported if the Animancer plugin exists in the project but reverts to using Legacy if it's missing). Because it's quite a step up in terms of features and bug fixes from having to use the Legacy system.

 

Animancer (i.e. the Playables API) supports playing AnimationClips from any source such as if they're loaded from an Asset Bundle at Runtime.

But unfortunately, Unity doesn't allow new non-Legacy AnimationClips to be created at runtime.

So if those plugins create AnimationClips in the Unity Editor then Animancer/Playables will be able to play them like any other clip but for importing a custom clip format at runtime you still need to use Legacy.

Theoretically it would be possible to basically make your own AnimationClip class that applies GLTF data using the Animation Jobs system (which is also supported by Animancer), but that would likely take quite a lot of effort to implement.

 

@Kybernetik
I recently discovered the Playables API when researching how Unity's provided animation solutions could be used to create a combo system for a character action game.

Goal and Assumptions

My initial hope was that the Playables API would let me place the different assets that comprise one of my character's attacks (script, animation, SFX, VFX) in the timeline window as a custom playable that would be output in response to player input actions (handled in character controller script) given the current player state.

Spoiler: Playable Graph Visualizer

Despite its recurring presence in the documentation, the Playable Graph Visualizer is not included with the rest of the Playables API. At the time of writing it is only available on Github and has not been updated since 2018. It was not written with the previous UnityEditor.Graphs and predates UnityEditor.GraphView (technically still Experimental despite having many released packages dependent on it).

I assume I could have a playable behavior for every individual attack/move, meaning that a three-hit combo would consist of three playable behaviors, a different behavior for each portion of the combo.

Examples Only for Cutscenes, not Runtime?

However most examples, including Unity's own samples, use custom Playables for cutscenes rather than real-time gameplay.

I've only found a few implementation examples, one tutorial from CatLikeCoding about enemy behavior in a tower defense game, and another post from Harry Jones, aka Delphic about getting a simple player character moving and animating.

For clear explanations of the Playables API, this blog post by 5argon and this forum thread are the most concise and easy to understand information I've found about the Playables API.

Well, what about Input?

The Input System documentation admits it is a known limitation that Actions cannot "preempt" other actions. If you have two actions, one bound to B and another with a composite binding of "Left Shift + B", both actions will be triggered when the player presses "Left Shift + B."

Thus you cannot drive/direct the player state using Input Actions alone.

This is no longer the case.

I have seen some suggestions of creating a custom input buffer that stores the last n actions. I most likely am wrong but it seems like you could use one or many of the following to control what the moves the player character can perform.

• Custom buffer that stores information about last n input actions
  
• Input event history or some other class in the Input System or Input Module
  • Use Input Action's CallbackContext phase
• Custom events using the Event System
  • Define Custom Messages in the Messaging System
• Mark animation clips with AnimationEvents
• A lot of Animator parameters
  • Fewer parameters through additional control using Animator Helpers by ashblue
    Spoiler: Features

    • Create animator variable changes from a ScriptableObject with visual programming
      
    • Share animator playback variable changes between GameObject(s)
      
    • Wait for multiple animator variable changes from a coroutine or loop
      
    • Pre-made library of common Animator Behaviors for visually programming the Animator with variable changes and randomization
• PlayableDirector, Timeline Signals, SignalEmitter/Receiver or related classes in Timeline/Playable

Additionally I wondered what state machine I should even use. Unity provides a few state machine solutions but it is unclear to me why you would want to use one over the other.

• Animation State Machine (Mecanim)
• PlayableGraph (unlike Mecanim, not restricted to animation assets)
• Visual Scripting¹ State Machine

Another option would be to make or use a third-party FSM² in conjunction with whatever feasible options from the bullet list above.

Either way, these are the other packages I know will be used for the project.

• Input System
• Event System
• Animation Rigging Package
• Cinemachine

If the Playables API can work like I hope then that would allow the combo system to be pretty modular and would provide animators and designers ways author and tweak values for all assets for a character's moves without excessive programming.

1. Known as Bolt prior to Unity 2021.1
2. Finite State Machine


More links about combos and/or the input system:

• How to handle button combos using Input System?
  
• Check for Input Combo
• Fighting Game Combos

 

The Playables API can't really do any of that out of the box, but it would allow you to build a system that can if you are willing to invest significant time into it.

Animancer's Weapons example and the attack system in my Platformer Game Kit demonstrate how I would create an attack combo system. Once the logic is set up, that approach should allow non-programmers to set up new characters and attacks and tweak their parameters without any programming at all.

I use an entirely script based FSM with its own Input Buffer system and wouldn't recommend any of those others you listed:

• I wouldn't generally recommend Animator Controllers for any purpose. Even before I made Animancer, I still used my script based FSM to keep as much of the game logic out of Animator Controllers as possible.
  
• You could theoretically use a Playable Graph as a state machine, but it wouldn't really contribute anything useful towards that goal. You would essentially be implementing a script based system like mine, just with significant inconveniences and performance overhead in the way you create and manage states.
• I'm not a fan of visual scripting and have never used Bolt, but it is probably a viable option you prefer it over text scripting.

 

@Kybernetik
I need to look into Bolt's state machine further to determine whether it is worthwhile to learn. Thank you for the resources. I will look into your combo system implementation in the Platformer Game Kit. It is a shame it would require a significant time investment to create such a system with the Playables API.

To me the main appeal would be using the Timeline window. Timing becomes especially hard, particularly making effects and activation execute in concert with game logic.

A custom clip asset that contains all the properly timed assets that comprise an attack and can be edited in the Timeline window would be ideal. I can imagine then using the custom clip with FSM and an InputBuffer system with or without Mecanim.

 

@Kybernetik : GLTF Importer plugins primarily are used for runtime loading of 3D models, so it sounds like it's easier for the plugin devs to just stick with Legacy. Thanks for the insight!