Utility Components

SkeletonRootMotion

spine-unity supports root motion on all three Spine skeleton components. The SkeletonRootMotion component can be attached to SkeletonAnimation and SkeletonGraphic (UI) GameObjects, while a separate SkeletonMecanimRootMotion component is provided for SkeletonMecanim. Attaching this root motion component is similar to enabling the Apply Root Motion parameter at the Unity Mecanim Animator component. When enabled, the character's position is driven by the animation according to the movement of the selected Root Motion Bone.

Note: There is a SkeletonMecanimRootMotion component provided for SkeletonMecanim objects. SkeletonRootMotion will fail when used on SkeletonAnimation or SkeletonGraphic (UI) components.

Parameters

• Root Motion Bone. The target bone whose movement is used as root motion.
• X. When enabled, movement along the local X axis is applied as root motion.
• Y. When enabled, movement along the local Y axis is applied as root motion.
• Root Motion Scale (X). Scale applied to the horizontal root motion delta. Can be used for delta compensation to e.g. stretch a jump to the desired distance.
• Root Motion Scale (Y) Scale applied to the vertical root motion delta. Can be used for delta compensation to e.g. stretch a jump to the desired height.
• Animation Tracks. Allows you to specify which animation tracks shall be included in root motion calculations.

Optional Parameters

• Rigidbody2D. When a Rigidbody2D is assigned, movement is applied via physics to the given Rigidbody2D instead of the Transform component. It is then recommended to set the skeleton animation component's Advanced - Animation Update Inspector parameter to In FixedUpdate.
• Rigidbody. When a Rigidbody is assigned, movement is applied via physics to the given Rigidbody instead of the Transform component. It is then recommended to set the skeleton animation component's Advanced - Animation Update Inspector parameter to In FixedUpdate.

Note: The SkeletonRootMotion class provides AdjustRootMotionToDistance() and other methods to allow for easy delta compensation. Delta compensation can be used to e.g. stretch a jump to a given distance. Root motion can be adjusted at the start of an animation or every frame via skeletonRootMotion.AdjustRootMotionToDistance(targetPosition - transform.position, trackIndex);.

SkeletonMecanimRootMotion

This component is a variant of the SkeletonRootMotion component to be used with SkeletonMecanim components.

The SkeletonMecanimRootMotion component is automatically added to your skeleton GameObject when the Apply Root Motion parameter at the Unity Mecanim Animator is enabled. To remove the SkeletonMecanimRootMotion component you have to ensure to disable the Animator's Apply Root Motion parameter first.

Parameters

• Root Motion Bone. The target bone whose movement is used as root motion.
• X. When enabled, movement along the local X axis is applied as root motion.
• Y. When enabled, movement along the local Y axis is applied as root motion.
• Root Motion Scale (X). Scale applied to the horizontal root motion delta. Can be used for delta compensation to e.g. stretch a jump to the desired distance.
• Root Motion Scale (Y) Scale applied to the vertical root motion delta. Can be used for delta compensation to e.g. stretch a jump to the desired height.
• Mecanim Layers. Allows you to specify which Mecanim layers shall be included in root motion calculations.

Optional Parameters

• Rigidbody2D. When a Rigidbody2D is assigned, movement is applied via physics to the given Rigidbody2D instead of the Transform component.
• Rigidbody. When a Rigidbody is assigned, movement is applied via physics to the given Rigidbody instead of the Transform component.

Note: The SkeletonMecanimRootMotion class provides AdjustRootMotionToDistance() and other methods to allow for easy delta compensation. Delta compensation can be used to e.g. stretch a jump to a given distance. Root motion can be adjusted at the start of an animation or every frame via skeletonRootMotion.AdjustRootMotionToDistance(targetPosition - transform.position, trackIndex);.

BoneFollower

This component references a bone of a SkeletonAnimation component and sets its own transform to that of the bone on every Update.

Note: There is a BoneFollowerGraphic component provided for SkeletonGraphic objects.

In contrast to the SkeletonUtilityBone component a BoneFollower can be used as a single isolated GameObject without any parent bone objects.

Use this to let objects like particle systems follow a specific bone on the skeleton.

You can examine the example scene Spine Examples/Getting Started/4 Object Oriented Sample on how to set up a BoneFollower component.

BoneFollowerGraphic

This component is a variant of the Bone Follower component to be used with SkeletonGraphic components.

In contrast to the SkeletonUtilityBone component a BoneFollowerGraphic can be used as a single isolated GameObject without any parent bone objects.

Use this to let objects like particle systems follow a specific bone on the skeleton.

You can examine the example scene Spine Examples/Getting Started/6 Skeleton Graphic on how to set up a BoneFollowerGraphic component.

PointFollower

This component is similar to the Bone Follower component but follows a PointAttachment instead of a bone.

In contrast to the SkeletonUtilityBone component a PointFollower can be used as a single isolated GameObject without any parent bone objects.

BoundingBoxFollower

This component is used to match a Bounding Box at a skeleton's slot. It extracts the shape and assigns it at a PolygonCollider2D and enables or disables it every frame to match the current animation.

Note: The bone's position is not automatically followed, which is why it is typically used together with a BoneFollower component. You can use the Add Bone Follower button in the BoundingBoxFollower inspector to create and setup a BoneFollower component.

Note: Vertex deformation animation (moving vertices of a Bounding Box over time in an animation) is not followed along, it only covers the initial shape.

See Bone Follower for further information.

SkeletonUtilityBone

Sometimes you may want to modify bone positions programmatically at runtime to react to physics or user input.

The SkeletonUtilityBone component provides a convenient interface to let GameObjects follow a bone position, override a bone position manually or via 2D and 3D physics. It can be configured to either follow the local bone position or override it on every Update. When set to Override, the component will set the bone position before the SkeletonAnimation component updates the world transforms.

Important Note: A SkeletonUtilityBone uses local transform values. It relies on a hierarchy of SkeletonUtilityBone GameObjects that mirrors the skeleton's bone hierarchy. The recommended way to quickly create a SkeletonUtilityBone hierarchy is via the SkeletonUtility component described below.

The SkeletonUtilityBone Inspector also provides an interface to create additional child bones (selectively or recursively) or create a 2D and 3D hinge chain.

Once your hierarchy of SkeletonUtilityBones is created, the Hierarchy panel shows different icons next to a SkeletonUtilityBone GameObject depending on whether it is set to

• Follow:
• or Override:

Example Use Case

Use a SkeletonUtilityBone in Override mode for use cases such as letting the user drag a bone of the skeleton around.

In case you need a GameObject to follow only a single bone position, you can use the BoneFollower component instead to save resources.

Example Scene

You can find an example scene that demonstrates usage of SkeletonUtilityBone at Spine Examples/Other Examples/SkeletonUtility Animated Physics. It shows how some SkeletonUtilityBones nodes are configured to Follow bone positions to be the necessary hierarchial parents for the Override nodes.

2D and 3D Hinge Chains for Physics

You may want to add physics to the cape of your character, have it drag heavy objects around or swing a morning-star. The spine-unity runtime allows you to generate a physics rig of HingeJoint or HingeJoint2D elements from an existing SkeletonUtilityBone hierarchy (see Creating a Hierarchy of SkeletonUtilityBones).

Select the first SkeletonUtilityBone chain element and in the Inspector choose Create 3D Hinge Chain or Create 2D Hinge Chain to generate the physics rig. The selected element and all its SkeletonUtilityBone children are turned into a hinge chain. You can then adjust the Rigidbody's drag and mass parameters to tweak the result. Raising the drag value will make the Rigidbody move slower and create the effect of being heavy or interact with air.

Note that the chain root node is no longer parented to bones of the skeleton, but placed at the top hierarchy level of the scene. This is a requirement in Unity to have momentum applied properly. Do not reparent the chain root to bones of your skeleton, or chain elements will no longer be affected by skeleton movement!

3D hinge chains

1. Create a SkeletonUtilityBone hierarchy as usual.
2. Select the first chain element in the Scene panel and in the Inspector choose Create 3D Hinge Chain to create the 3D hinge chain rig.
3. This will remove the chain GameObjects from the previous parent (cape-root in the example) and place a new HingeChain Parent GameObject at the top level of the scene. As mentioned above, do not reparent this GameObject to the skeleton!
4. Adjust chain elements Rigidbody drag and mass parameters to tweak the result.

When the skeleton is flipped, the HingeChain Parent GameObject will automatically be rotated by 180 degrees to adjust the hinge chain to the flipped bone locations.

2D hinge chains

1. Create a SkeletonUtilityBone hierarchy as usual.
2. Select the first chain element in the Scene panel and in the Inspector choose Create 2D Hinge Chain to create the 2D hinge chain rig.
3. This will remove the chain GameObjects from the previous parent (cape-root in the example) and place a new HingeChain Parent GameObject at the top level of the scene. As mentioned above, do not reparent this GameObject to the skeleton!
4. Adjust chain elements Rigidbody2D drag and mass parameters to tweak the result.

Note that this GameObject contains two child objects, named Hinge Chain and Hinge Chain FlippedX. When the skeleton is flipped, these GameObjects will automatically be activated and deactivated to enable the respective hinge chain.

SkeletonUtility

Creating a Hierarchy of SkeletonUtilityBones

The SkeletonUtility component offers a quick way to create a hierarchy of SkeletonUtilityBone GameObjects mirroring the bone hierarchy of the skeleton.

To create a SkeletonUtility component, select your SkeletonAnimation component and in the Inspector unfold the Advanced section and hit Add Skeleton Utility. Once created, the Add Skeleton Utility button will disappear and SkeletonUtility component is added to your GameObject.

The SkeletonUtility component provides a Spawn Hierarchy button with the following options presented on click:

1. Follow all bones Creates SkeletonUtilityBone GameObjects for all bones in the hierarchy, set to mode Follow
2. Follow (Root Only) Creates only the root SkeletonUtilityBone GameObject, set to mode Follow
3. Override all bones Creates SkeletonUtilityBone GameObjects for all bones in the hierarchy, set to mode Override
4. Override (Root Only) Creates only the root SkeletonUtilityBone GameObject, set to mode Override

EachSkeletonUtilityBone can then be configured to override bone positions of a skeleton where necessary.

Note: You can add additional SkeletonUtilityBone GameObjects via the inspector of a SkeletonUtilityBone later, the Spawn Hierarchy functionality serves as a rough starting point. You can also delete unneeded SkeletonUtilityBone GameObjects to save resources. Just remember you need to keep their parents intact, so do not delete GameObjects in the middle of a hierarchy-chain or change their parents.

SkeletonUtilityConstraint

C#

Base class to derive skeleton utility constraint subclasses from. It automatically registers itself at the parent SkeletonUtility and will be updated accordingly.

See example constraint classes SkeletonUtilityGroundConstraint and SkeletonUtilityEyeConstraint for how to write your own constraint classes.

Example Scene

The spine-unity runtime comes with example scenes that demonstrate the above constraints. You can find them in Spine Examples/Other Examples/SkeletonUtility GroundConstraint and Spine Examples/Other Examples/SkeletonUtility Eyes.

SkeletonRendererCustomMaterials

You may want to override materials for a specific Skeleton instance or even only at certain slots. This component provides an inspector interface to assign custom material overrides for SkeletonRenderer, including subclasses SkeletonAnimation and SkeletonMecanim.

You can right-click on a SkeletonRenderer (or subclasses SkeletonAnimation and SkeletonMecanim) and select Add Basic Serialized Custom Materials to add this component to the renderer. Add entries to the Custom Slot Materials array to override materials at certain slots or to the Custom Material Overrides array to replace one material with another for the whole skeleton. Be sure to uncheck Override Disabled to enable the respective material overrides.

Note: This component is not intended to be interfaced through code. To dynamically set materials for your SkeletonRenderer through code, you can directly access SkeletonRenderer.CustomMaterialOverride for material array overrides and SkeletonRenderer.CustomSlotMaterials for slot material overrides.

SkeletonGraphicCustomMaterials

A variant of SkeletonRendererCustomMaterials for SkeletonGraphic. This component provides an inspector interface to assign custom material and texture overrides for SkeletonGraphic.

You can right-click on a SkeletonGraphic and select Add Basic Serialized Custom Materials to add this component to the GameObject. Add entries to the Custom Texture Overrides array to replace one texture with another for the whole skeleton. Add entries to the Custom Material Overrides array to replace the used material at an original texture (before replacement) with another material. Be sure to check Override Enabled to enable the respective texture or material overrides.

Note: This component is not intended to be interfaced through code. To dynamically set materials for your SkeletonGraphic through code, you can directly access SkeletonGraphic.CustomMaterialOverride for material array overrides and SkeletonGraphic.CustomTextureOverride for texture overrides.

SkeletonRenderSeparator

You may want to display other GameObjects between parts of your character, e.g. to let your character run into a tree and display one leg in front and one behind the trunk. The SkeletonRenderSeparator component allows you to split your SkeletonRenderer (or subclass SkeletonAnimation and SkeletonMecanim) into two or more SkeletonPartsRenderers with customizable layer order.

Note: The SkeletonGraphic component provides render separation functionality directly at the SkeletonGraphic Inspector in the Advanced section, it does not require any additional components.

Note: Normally, Spine renderer components will use a single renderer to display the whole mesh of a skeleton. This unfortunately prevents you from inserting other UnityEngine.Renderers (SpriteRenderer, MeshRenderer, ParticleSystem, etc.) between its parts.

Setup

1. Make sure you know your Skeleton's draw order. Find out which slot you want to use to separate your Skeleton's render into parts. For convenience, label this slot clearly before exporting your Skeleton.

2. Add the SkeletonRenderSeparator component Select your Spine GameObject. Right-click on your SkeletonAnimation or SkeletonRenderer in the inspector. Choose Add Skeleton Render Separator. This will add the SkeletonRenderSeparator component to the GameObject.

3. Assign Separator Slots The inspector now shows a warning that the list of separators is empty. Setup separator slots by choosing the desired slot(s) under Separator Slot Names. You can add additional separator slots using the + button.

   Note: This field is serialized at the SkeletonRenderer (or SkeletonAnimation and SkeletonMecanim subclass) component, SkeletonRenderSeparator just provides the interface for it.

4. Add Parts Renderers The inspector now shows a warning that you don't have enough parts renderers.
   Click on the Add the missing renderers (n) button to create the required GameObjects with SkeletonPartsRenderer components. These GameObjects will be automatically assigned at the Parts Renderers list above.

   Note: The SkeletonRenderSeparator detects the currently required number of parts renderers,depending on the current draw order. If draw order is modified at runtime, it may happen that the renderer requires more parts renderers. In this case you may need to add one or two additional parts renderers manually by clicking the Add Parts Renderer button.

5. Setup Sorting Layer and Order in Layer Each of the SkeletonPartsRenderers provides a Sorting Layer and Order in Layer property in the inspector. You can now setup the sorting properties at each SkeletonPartsRenderer. Higher values will move the renderer to the front.

Note: The SkeletonPartsRenderer GameObjects don't have to be children of your Spine GameObject. The SkeletonRenderSeparator keeps references, so you can organize them however you need to.

Example Scene

You can find an example scene that demonstrates usage of SkeletonPartsRenderer and SkeletonRenderSeparator at Spine Examples/Other Examples/SkeletonRenderSeparator.

C#

Enabling and Disabling

By default, SkeletonRenderSeparator will disable the SkeletonRenderer and take over his mesh rendering task. Likewise, if you disable SkeletonRenderSeparator, SkeletonRenderer will take over rendering again.

You can enable and disable a SkeletonRenderSeparator as any component:

Changing the separation point

The point of separation is not stored in SkeletonRenderSeparator.
It is defined by the separator slots in SkeletonRenderer (or subclasses SkeletonAnimation and SkeletonMecanim). If you want to manipulate separator slots at runtime, you can access the list SkeletonRenderer.separatorSlots and manipulate it as usual by calling Add, Remove or Clear.

Adding a SkeletonRenderSeparator at runtime

You can use the static method SkeletonRenderSeparator.AddToSkeletonRenderer to add and initialize a new SkeletonRenderSeparator component.

By default, it will add the currently necessary SkeletonPartsRenderers. It provides a number of optional arguments for advanced use cases, please see the code documentation.

Example Components

spine-unity comes with additional example components that demonstrate solutions for some advanced use cases. The most important example components are listed below.

SkeletonRagdoll

You may want to turn an animated skeleton into a puppet-like ragdoll, e.g. to simulate falling down via physics in case of death. This can be achieved with the SkeletonRagdoll and SkeletonRagdoll2D example components, which provide a comfortable interface to create ragdoll physics components at a SkeletonRenderer (or subclasses SkeletonAnimation and SkeletonMecanim).

You can find a demonstration of the SkeletonRagdoll2D component in the example scene Spine Examples/Other Examples/SkeletonUtility Ragdoll.

SkeletonRenderTexture

There are situations where you may need to render your skeleton to a RenderTexture instead of directly to the screen, e.g. when you want to fade out a skeleton via transparency. This component takes care of rendering the skeleton to a RenderTexture at the appropriate size and resolution and displays it at a matched quad, so that you can seamlessly switch to a one-to-one replacement.

The SkeletonRenderTextureFadeout component described below requires a SkeletonRenderTexture or a SkeletonGraphicRenderTexture component. After adding the SkeletonRenderTexture component to your GameObject, you can add a SkeletonRenderTextureFadeout component to take care of a fade-out effect.

Important Note: Using an intermediate RenderTexture for rendering is an expensive operation compared to directly drawing a skeleton to the frame buffer. Use this component only where necessary. Keep it disabled until you actually want to enable the desired effect. E.g. only enable the SkeletonRenderTexture component during fade-out, but keep it disabled before and after that.

SkeletonGraphicRenderTexture

A variant of the SkeletonRenderTexture component to be used with SkeletonGraphic.

SkeletonRenderTextureFadeout

You may want to fade-out a skeleton via transparency, but want to avoid the overlapping attachments issue described here. This components can be used either with a SkeletonRenderTexture or SkeletonGraphicRenderTexture component (which needs to be added first) to render a skeleton at full opacity to a temporary RenderTexture and then draw the content of this RenderTexture to your scene at the desired fade opacity.

SkeletonGhost

You may want to render a motion-trail or motion-blur effect at at character to simulate speed or power. The SkeletonGhost example component can be attached at a SkeletonRenderer (or subclasses SkeletonAnimation and SkeletonMecanim) to draw the skeleton multiple times, using a customizable material.

SkeletonUtilityKinematicShadow

You may want to have some bones to receive some inertia or to react to movement of other bones. This may be useful to have a cape follow the movement of a character in a more convincing way. This can be achieved with the SkeletonUtilityKinematicShadow component. It allows hinge chains to inherit a velocity interpreted from changes in parent transform position or from unrelated rigidbodies.

You can find a demonstration of the SkeletonUtilityKinematicShadow component in the example scene Spine Examples/Other Examples/SkeletonUtility Animated Physics.

RenderExistingMesh

You may want to save performance by rendering identical copies of animated Skeletons multiple times at different locations, e.g. when a large group of skeletons allows for some repetition. Or you want to render a mesh again behind itself using e.g. the URP shader Universal Render Pipeline/Spine/Outline/Skeleton-OutlineOnly when selected. This component can be used to render an already animated and updated skeleton mesh again, saving the overhead of animation and calculating the mesh.

RenderCombinedMesh

When your skeleton requires multiple materials, the included outline shaders will incorrectly outline each submesh instead of the whole skeleton. This component can be used to combine the submeshes and render them as a single mesh, leading to correct outlines.

Next: Rendering Previous: Main Components