Other Rukhanka - ECS Animation System

The absence of an animation system leads to a self-made subproject for current DOTS projects. Which consequently evolved into a standalone tool. It was a relatively long road from DOTS 0.17 to Entities 0.51 and finally 1.0.0-pre.15.

In short: use default Unity's Mecanim and Animation Clips as authoring workflow. Rukhanka will do the rest: bake state machines and animations in entity components, advance state machines, play animations and feed animated matrices to the SkinMatrix buffers of the Entities Graphics Package. Entities Graphics will render animated objects.

Rukhanka - ECS Animation System

Above link has brief description of the project. Consult documentation and feel free to ask any questions/make suggestions/critique/etc

 

Version 1.0.1 is released.

Changelog:
Changed

• Crowd and Stress Test samples now have control for skeleton visualization enabling (with RUKHANKA_DEBUG_INFO defined).
• Crowd and Stress Test samples now show total number of animated bones in scene.

Added

• IEnableableComponent interface for AnimatorControllerLayerComponent and RigDefinitionComponent.
• Description of main Rukhanka entity components.

Fixed

• Incorrect handling handling of uniform scale in animations.

 

Version 1.0.3 is released.

Changelog:
Fixed

• Incorrect handling of very small transition exit time during state loops.
• Preventing NANs (division by zero) when transition duration is zero.
• Memory allocation error in PerfectHash tests.
• Controller parameters order in authoring animator does not coincide with generated AnimatorControllerParameter buffer.
• Empty animations to process buffer were handled incorrectly.
• Exit states of state machines are now handled properly.
• Animator state `Cycle Offset` treated as animation normalized time offset as in Unity.Animator.

Added

• Adding authoring Unity.Animator and all used Unity.Animation in the baker dependency list.
• Extended animator controller logging with RUKHANKA_DEBUG_INFO which displays all states parameters and transitions of baked state machines.

 

Is humanoid support planned for this year?!
THANKS!

 

It is almost ready. I would say it is 99% ready. But I can't get how three muscle values for bone should be converted into single quaternion. All my experiments leads to wrong result in some cases. I am digging into animation forums, asking people but still no correct solution found. Trying more.

 

Version 1.1.0 was released.

Changelog:
Added

• 'Unity Netcode for Entities' package support. Animations and controllers can be synchronized using interpolated and predicted modes.
• New 'Netcode Demo' sample with 'Rukhanka' and 'Netcode for Entities' collaboration showcase.
• Animator parameter aspect to simplify animator controller parameter data manipulation.

Changed

• Minimum 'Entities' and 'Entities.Graphics' packages version is 1.0.10.

Fixed

• State machine transitions with exit time 0 were handled incorrectly.
• Transitions with exit time 1 are looped contrary to Unity documentation. 'Rukhanka' behavior changed to match 'Mecanim' in this aspect.
• Various deprecated API usage warnings.

 

Version 1.2.0 was released.

Changelog:
Added

• Compute deformation node for 'Amplify Shader Editor'. Now it is possible to make 'Entities.Graphics' deformation-compatible shaders with this tool.
• Trigger set API for 'AnimatorParametersAspect'.
• Animator parameter access performance tests.
• Own entity command buffer system for optimizing ECB usage after 'AnimationControllerSystem'.
• Animator state query aspect for access to runtime animator data.

Changed

• Animator parameter internal hash code representation was moved from Hash128 to uint. This leads to a smaller 'AnimatorControllerParameterComponent' size and better chunk utilization.

Fixed

• The state machine states without an assigned motion field had incorrect weight calculation.
• Exit and enter transition events that happened in the same frame lead to one incorrectly processed frame. This was clearly observable with transitions from/to "no-motion" states.
• Trigger parameters were reset even if the transition cumulative condition (all conditions must be true) is not met.
• Entering through the sub-state machine's 'Enter' state was handled incorrectly.
• Exiting from nested sub-state machines using the 'Exit' state was handled incorrectly.
• Multiple transitions from the 'Enter' state machine state were handled incorrectly.

 

Hey, this asset looks amazing, is it possible to have some benchmark numbers regarding performance so we can have an idea before buying ? Thanks

 

Hi, sure. Some measurements on "Stress Scene" with ~10K animated entites (~870K animated bones)
* Ryzen 7 5800X Windows: frame time is ~42 ms.
* MacBook Pro with Apple M2: frame time is ~47 ms.
Must note that there is optimization milestone planned in near future (after humanoid animation support will be done) which introduces some big optimization strategies like frustum and occlusion culling, rig bone hierarchy optimization, etc.

 

Thats impressive, i think i can get even better performance because i wont need 10k agents and, plus i suppose you tested with a lot of features enabled ? i wont do that either, i mainly need a way to play and blend animations. Culling will be a huge plus though! Thank you very much!

 

Tested entities are animated models with simple animators with several animations. Not so complex, but the complexity of the animator has no big influence on performance. The number of bones and simultaneously computed animations - is.

 

Grabbed this asset, and it worked like a charm for the walk/run blendtree I had setup. Fantastic work! The parameter setting aspects are amazing too.

 

Thanks. More features to come.

 

When are you gonna be bought by Unity like the kinematic character controller made by PhilSA ?

 

I think the answer is - "Never". A more favorable scenario is "Entities.Animations" comes out and Rukhanka not needed anymore.

 

And you, my friend, are a true hero.

 

I spotted that the systems in Rukhanka still run, even if there's no entities in the world that use animation. I know performance is on the list, so worth taking a look at maybe!

Looks like the systems have [RequireMatchingQueriesForUpdate] but I don't know enough about ECS to know why that wouldn't be working.

 

Thanks for reporting this. I will investigate.

 

I concur with WAYN. Animation is the first thing everyone asks about when they start DOTS. Unity would be smart to buy it off you and/or hire you because it's going to take years for something to come out, and animation is one of the top 3 reasons people use a gaming engine in the first place. As you know there are a couple other good ECS animation systems out there, but I think yours is the easiest to dive into since it re-uses the standard authoring tools.

 

Version 1.3.0 was released. Main feature of this version is Humanoid animation and avatars support.

Changelog
Added

• Humanoid-type support for models and animations.
• Humanoid avatar mask support.
• Humanoid avatars and animations sample scene.

Changed

• The rig definition authoring script now contains zero configuration fields. The avatar mask used for rig definition is not needed anymore. All required information Rukhanka reads from Unity Avatar. This is a breaking change. Please carefully read the upgrade process.

Fixed

• AnimatorControllerParameterComponent buffer did not replicate with NetCode.

 

Amazing. Is this feasible for a current project that already has many entities synced and animated via game object? I am guessing no

 

I saw that you've added humanoid support! This is the version I've been waiting for. I read through your documentation, but it seems to be missing a few details. Can it handle runtime downloaded humanoid characters and animations ?

 

All ECS data should be prepared beforehead by bakers. I think you can use use entities content management

 

Version 1.4.0 was released. This release contains a lot of changes and improvements. The most notable ones are physics collider attachment support, better root motion, and bone entity stripping feature. As a neat bonus Rukhanka is on the sale now with 50% off.

Changelog
Fixed

• Several memory leaks during baking and runtime.
• Incorrect additive animation calculation for humanoid animations.

Added

• Two new sample scenes: Ragdoll and Simple Physics.
• Animation keyframe binary search was implemented.
• Rukhanka can now work with unparented bone entities. This allows to properly handle physics body bone attachments.
• Unneeded bone entity stripping functionality. Refer to documentation for the detailed description.
• Internal bone animation data is now exposed as a RuntimeAnimationData singleton.
• Full root motion support for Humanoid and Generic rigs. All root motion animation configuration parameters are supported.
• Rukhanka now requires UNITY_BURST_EXPERIMENTAL_ATOMIC_INTRINSICS script compilation symbol. It will be added to project scripting define symbols automatically if not present.

Changed

• Updated Entities dependency to version 1.0.16.
• Removed synchronization point related to AnimationToProcess buffer filling.
• Removed synchronization point related to root motion delta states processing.
• The animation process system is split into two distinct parts: animation calculation and animation application. This allows to injection of animation results post-processing and modifications (for example IK) functionality.
• Runtime created bone-name-to-index hash map was removed. It has been replaced with a blob perfect hash map created during baking time.
• Samples were moved to the samples tab of package properties. There are shared HDRP/URP sample scenes now. Materials and scene properties will adapt to the current renderer pipeline automatically.
• Animation controller layer weight is a runtime property of AnimatorControllerLayerComponent now.

 

For games with hundreds or even thousands of character skins, like Fortnite, managing them through the content manager within a subscene becomes impractical. Instead, it's more efficient to load cosmetics separately during runtime rather than loading an entire subscene filled with hundreds of them.

It would be incredibly easier if we could simply instantiate an animated character entity prefab and override its mesh and materials. This approach can significantly reduce the overall workflow and required resources.

I could be wrong as I never used Rukhanka before. but the asset is very advanced, easy to use as it follows the Mono approach.

Btw, I am surprised that Unity didn’t adopted this asset and made it official. It is by far more sophisticated than the Animation package made by Unity.

 

Version 1.4.1 is out. This mostly bugfix release with important changes related to humanoid rigs. It is strongly advised to update, if you use humanoid avatars and animations (with or without root motion).
Changed

• All runtime systems TempJob allocations was changed to WorldUpdateAllocator.
• Code cleanup with more extensive SystemAPI usage.
• Moving shared utility code into separate Rukhanka.Toolbox assembly.

Fixed

• Incorrect root bone indexing for humanoid rigs.
• Incorrect non-root motion of humanoid rig hips.

 

I will purchase it as soon as the discount is applied on the Asset Store.

 

Hi @Rukhanka - I posted this message on Discord 2 days ago but didn't get a reply.
Is that the best place to get support - or is it better to post here in the forums?
--
I bought the asset just now, having previously tried the ECS GPU Baker. It was incredibly easy to get started with Rukhanka - everything "just worked" for me. One thing I am trying to work out, how do I react to animation events? I want to choose a random animation and speed after each animation is completed. This is how I handled it in Mecanim with a StateMachineBehavior on the AnimatorController:

Code (CSharp):

1.        public override void OnStateEnter(Animator animator, AnimatorStateInfo stateInfo, int layerIndex)
2.        {
3.            // set the animation index to a random number so we can choose the next animation by random
4.            animator.SetInteger("AnimationIndex", Random.Range(0, 8));
5.            // randomize the speed between 0.6f and 1.8f
6.            animator.SetFloat("Speed", Random.Range(0.6f, 1.8f));
7.        }

In Rukhanka, I can see how to set the speed, but how do I trigger this? I have an animation event near the end of each animation - can I execute code on an animation event? Or is there an equivalent to OnStateEnter or OnStateExit?

 

Hi. Sorry for late response. I have answered your question in Discord, but will duplicate it here.

Unfortunately right now Rukhanka has no animation and state machine event system. Animation events feature is planned for the next major release (1.5.0). Callback functions like OnStateEnter is not how ECS works, so it will be some sort of event system. As for now you can utilize state machine runtime information stored in AnimatorControllerLayerComponent DynamicBuffer attached to the animated entity. You can look at Animator State Query sample for the reference.

 

Yeah, sorry too for the chase! I kind of forgot it was the weekend.

Thanks for everything you do - the asset is a godsend.

 

This is standalone profiler printscreen in Rukhanka/CrowdSample scene with 500 skeletons. Why unity needs to wait 60ms?
what is she doing all this time?

 

Version v1.4.2 is out. This release has some important fixes and additions related to animator state machine processing.

Fixed

• The last syncpoint of AnimationProcessSystem job has been removed by moving all frame initialization code into a separate job.
• Fixed incorrect excessive internal hash map capacity setting.
• Fixed memory leaks during blob creation in several baking systems.
• Internal perfect hash tables gain better validation. This change fixes rare creation errors from valid data.
• Correct handling of inexistent conditions during state machine baking.
• Fixed "enter transition"->"exit transition" sequence that appeared in one frame.
• Fixed warning of implicit usage of ToNativeArray() calls.
• The transition offset were measured in normalized time. It is correctly in seconds now.

Added

• Sub-state machine transitions was implemented.

Changed

• Animator parameter usage documentation has been changed to emphasize AnimatorParametersAspect as the preferred runtime interface to parameters data.

 

Version 1.5.0 was released. Main new features of this release are Animation Results Customization with some Inverse Kinematics algorithms and Animation and Animator Controller Events.

Fixed

• The BoneTransform.Inverse function worked incorrectly with respect to scale.
• User curves were parsed incorrectly in humanoid animation clips.

Added

• Animation modification injection point represented by RukhankaAnimationInjectionSystemGroup.
• AnimationStream structure to simplify working with animation data.
• Several inverse kinematics algorithms:
  • Aim.
  • Override transform.
  • Forward And Backward Reaching Inverse Kinematics (FABRIK).
  • Two Bone.
• Animation events.
• Animator controller events.
• The debug bone renderer was extended to be able to draw various primitive geometry (lines, triangles, cones, cubes, etc.) and moved to separate DebugDrawer assembly. It is independent from other Rukhanka assemblies and can be used as a standalone library.
• Two new samples: Events and IK.

Changed

• The package's internal name has been changed to com.rukhanka.animation.
• Bone stripping functionality has an additional Automatic mode now.
• The RukhankaDebugConfiguration new options to log all animation and animator controller events.
• Multiple bone visualization systems can run. This is useful to display skeletons in multiple worlds (particularly when using NetCode).

 

Version 1.5.1 was released. This is mostly a small bug fix release.

[1.5.1]
Fixed

• Removed empty DebugDrawer draw calls in case of no primitives submitted.
• Server world missed the animation injection system group.
• Some memory leaks during baking.

Added

• Duplicated bone names checker during baking.

Changed

• AnimationStream bone hierarchy recalculation rework. There is no need for RebuildOutdatedBonePoses explicit calls anymore. All dependent bones will be recalculated automatically during Get calls. AnimationStream is derived from an IDisposable interface now, and disposal is required after its usage.

 

Version 1.6.0 was released. New features of this release are Animation Frustum Culling and Skinned Mesh Bounding Box Recalculation. Please read appropriate documentation sections about new features. Incorrect configuration can lead to errors/degraded performance. Also note that minimum Entities version is set to 1.2.0-pre.6 for this release.

[1.6.0]
Fixed

• User curves incorrect multiple layers blending.
• IK targets incorrect world pose calculation if the animated entity is not a hierarchy root.

Added

• Animation frustum culling ability.
• Skinned mesh renderer bounding box recalculation ability.
• Sample showcase scene to demonstrate animation culling and bounding box recalculation features.
• IsInTransition utility function of AnimatorStateQueryAspect.

Changed

• Updated Entities dependency to version 1.2.0-pre.6
• Making DebugDrawer a client only system.

 

Version 1.6.1 was released. This is a small bugfix release mostly dedicated to the DebugDrawer fix related to the line rendering.

[1.6.1]
Fixed

• DebugDrawer incorrect line renderer in Unity versions newer than 2022.3.17f1.
• Authoring object copy for animation sampling is not created if avatar is missing on animator.

 

Version 1.6.2 was released. This release mostly dedicated to animation events fixes: negative animation direction, big animation steps, edge cases, etc.

[1.6.2]
Fixed

• Animation events edge cases (start and end animation).
• Correcting events for looped animations.
• Exception during renderers bounding box recalculation if skinned mesh renderer root bone property is null.

 

Version 1.6.3 was released.

[1.6.3]
Changed

• Reverting Entities dependency to version 1.0.16 with appropriate changes. No functionality was affected.