[RELEASED] Rukhanka - ECS (DOTS) Animation System

Rukhanka is an animation system for the Entities Component System (ECS). It works (and requires) Entities and Entities Graphics packages. Rukhanka animates skinned meshes and passes prepared data to the Entities Graphics package which renders animated objects. There is only Generic animation type support for now.

[ Asset Store ]
[ Documentation | YouTube | Discord | Support ]​

It is made with three main principles in mind:

• Complex inside - simple outside. Usage and setup are trivial. Use familiar Unity animation tools such as Mecanim and Animation Clips as authoring components. Rukhanka converts them during the baking phase and internally processes the animator state machine and plays all required animations.
• Performance in all aspects. Everything is fully bursted. ISystem-based and fully parallel with per-bone granularity (not per-skeleton). This allows achieving high thread utilization for low-bone and high-bone meshes.
• Behavior is nearly 100% similar to Unity Mecanim. Although I try to achieve 100% behavior identity, I am not a Unity employee and have no access to the Unity Animation system source code. Everything in Rukhanka is achieved by reading public documentation and investigating Unity's behavior.

Getting started video:

IMPORTANT: Make sure to refer to Feature Support Tables to figure out what functionality is supported before purchase.

 

Very nice!
I couldn't find explicit info. Your animation system doesn't require a compute shader, right?

How long did you work on this asset?
Unity devs, why is this dev out-pacing you in one of the most crucial parts of a game?

 

Hi. You are right, compute shaders don't required. Pure Entities + Burst. I am worked approximately 4 monthes till v1.0.0 release.

 

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.

 

Version 1.1.0 is 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.

 

Just bought it. Looks promising. Though I do notice that the skeleton Rukhanka creates ignores the "Scale Factor" in the Mesh import settings. So the scaled mesh gets applied to the unscaled skeleton and thus looks deformed. Is this by design?

 

Thank you for using Rukhanka. No, this behavior is not by design, but I have not so many test animated meshes with various scale setups. Would you be so kind as send me one example mesh plus one animation, please? I will do necessary fixes. support@rukhanka.com

 

You can test this on any skinned mesh. Since the Scale Factor is a setting in
the import settings of the mesh, not scaling on the mesh or skeleton themselves.




This is what happens when I set the Scale Factor to 2 on the Ellen asset of the sample scene

 

Looks like this is a problem with URP and skinned mesh importer. You can check this by dragging one of the models out of entity subscene and default unity animator will produce exact same results during animation and rendering.
HDRP behaves differently. If model and animation (these are in seprate files) are scaled equivalently then animation palyed correctly.

 

That's weird. I've used URP and skinned meshes before and this never happened with the Scale Factor applied. If I drag the Ellen prefab or model from the project folder into the parent scene, apply the same URP materials as the Rukhanaka version and set the Scale Factor to 2 on the model and animation files then it scales appropriately.

see in this pic the Monobehavior version looks normal while the Rukhanak versions are distorted.




Edit:

Just tested again, something strange is going on. If I copy that properly scaling version and add it to the Subscene and apply the Rukhanka rig definition script I get the proper scaling on that Entity.



edit 2:
I think it is because that the models in the example scene aren't linked to the model file/prefab anymore and are just normal gameobjects, that's why the scale didn't transfer to the skeleton. Now I just need to check why my at runtime instanced Entities are not scaling right.

edit 3:
I tested with my own models and animations and the reason why it didn't scale properly was that I needed to set the same scale factor on the animation files. Which, if I remember correctly, wasn't necessary for the normal Unity MonoBehaviour animation system. You should probably add that in the documentation.

 

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.

 

Rukhanka is part of "Dev Days of Summer" sale. The price is reduced by 50%

 

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.

 

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.

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.

 

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.

 

Hi there,

The Loop Pose function in Animation Properties doesn't work under humanoid types.

You can reproduce it by setting one of EllenCombos to obviously "non-loop-match", in `HumanoidAnimationStateMachine` in 15. Humanoid Animations sample.


The pose under unity animator works with Loop Pose but baked three don't.

Using Rukhanka Animation v1.3.1 and Unity 2022.3.6f1.

 

Please update to the v1.4.1. This issue was fixed in this release.

 

Hi,
Are you planning to add animation events support in future releases? Or something else that gives similar possibilities?
Feature-wise this asset looks great, but we use a lot of events in our project and it would be hard to replace them with anything else.

 

Hi. Yes, animation events are planned in one of the next releases.

 

Hello,
I have a question about the Ragdoll example, when I change the state to ragdoll (without animation), after that I want to change the state to GetUp animation, but how do I synchronize the positions? How to start GetUp animation (its bones positions) from the ragdoll's bones LocalTransforms?

 

Hi. Your goal is achievable, but some work is required. You need to make a system that blends current bone poses (after ragdoll application) and animated bone poses for GetUp animation over some time.

Basically algorithm is follows:
* At start of "get up" event memorize bone poses for entity. Dynamic buffer component can be used for example, or attach component with recoreded pose to the entities that contains AnimatorEntityRefComponent.
* Write a system that blends between memorized pose and animated pose over time. This is simply as lerp(memPose, localTransformPose, transitionTime). Note that this system sould run after RukhankaAnimationSystemGroup.

That's all. Quick and simple "get up" sequence system. Far from ideal but maybe will fit your needs.

 

Thanks, everything is clear, except I can’t figure out how to blend between saved positions of the bones and the GetUp animation bones transforms before actually playing the animation? I think I am doing something wrong...

Code (CSharp):

1. case CharacterState.GetUpState: //GetUp event
2.  {
3.  
4.             //Memorize the Ragdoll bones transforms to MemPose component
5.             ecb.AddComponent(entity, new MemPose{
6.                 pelvisPosition = pelvis_Transform.Position,
7.                 pelvisRotation = pelvis_Transform.Rotation,
8.                 spinePosition ...
9.             });
10.  
11.             //Play the GetUp animation
12.             new ProcessInputJob() {
13.                 _clipIndex = 16,  //change to getup animation
14.                 _ragdoll = false,
15.                 _speed = 1f,
16.                 _blending = newBlend  // getup animation depends on pelvis orientation
17.             }.ScheduleParallel();
18.          
19.             break;
20. }

Now I want to blend between memorized and animated pose, but if I start the GetUp animation it's already jumps to another location

Code (CSharp):

1. [UpdateAfter(typeof(RukhankaAnimationSystemGroup))]
2. public partial struct CustomSystem : ISystem
3. {
4.        //...
5.        public void OnUpdate(ref SystemState state)
6.        {
7.              foreach ( var (memPose, animatorState, characterComponent, entity) in
8.                 SystemAPI.Query<MemPose, AnimatorStateQueryAspect, PlatformerCharacterComponent>().WithAll<MemPose>().WithEntityAccess())
9.              {
10.                 //...
11.                 var transitionState = animatorState.GetLayerCurrentTransitionInfo(0);
12.                  if (transitionState.hash == ragdollToGetUpTransitionHash)
13.                   {
14.                     //...
15.                     pelvis_Transform.Position = math.lerp(memPose.pelvisPosition, pelvis_Transform.Position, TimeData.DeltaTime);
16.                     pelvis_Transform.Rotation = math.slerp(memPose.pelvisRotation, pelvis_Transform.Rotation, TimeData.DeltaTime);
17.                     //...
18.                   }
19.  
20.               }
21.         }
22. }

I think I lost my brain) I guess I need to get the GetUp animation bone positions and lerp them before the animation starts playing, but how can I do that?

 

Sorry for late response. Turns out that things a little more complicated then expected. I forgot that at a point of time after RukhankaAnimationSystemGroup calculated animations already applied to skeleton as skinned mesh matrices, so there is no effect of modifying them after animation processing. You need to move your system after AnimationProcessSystem but before AnimationApplicationSystem. There you should modify internal Rukhanka's animation poses for bones. As reference to how to access this data for specific entity you can look at PropagateBoneTransformToEntityTRSJob. In your system you need to adjust internal bone poses by discussed earlier algorithm (lerping poses).