http://esotericsoftware.com/spine-unity-attachments-and-attachmenttools
This contains intermediate-level documentation. If you're just starting out, try the Getting Started document.
Documentation last updated for Spine-Unity for Spine 3.6.x and 3.7.x
If this documentation contains mistakes or doesn't cover some questions, please feel free to open an issue or post in the official Spine-Unity forums.
In Spine, Attachments are primarily the visible parts of your skeleton: images and meshes. But they also include things like bounding boxes, paths and points. They are the things that you "attach" to bones by putting them in slots. This allows the visible parts of your skeleton to move according to bones.
In the Spine runtimes, Attachments are objects that can be placed in a Slot to follow a Bone; They move according to a Bone's transform (rotation, position, scale).
There are two renderable attachment types:
- RegionAttachments, rectangular image attachments that map to a rectangular region in an atlas, or any backing texture.
- MeshAttachments, attachments that map their texture area to a deformable mesh.
- Other Attachment types exist such as BoundingBoxAttachment, PathAttachment and PointAttachment. These are typically not rendered in-game. They will be documented separately.
In the process of loading skeleton data from skeleton json or binary at runtime, all Attachments are stored in Skin objects.
You can find these loaded skins and Attachments in the SkeletonData: `
Skeleton.Data.FindSkin(string)Attachments that weren't explicitly placed in a skin and skin placeholders in Spine are included in the skeleton data's "default skin". For skeletons that you did not add skins to, all attachments can be found in the default skin.
At runtime, you can find the default skin in the skeleton data.
Skeleton.Data.DefaultSkinAttachments in a Skin are stored and mapped to a Skin key: comprised of an int slot index, and a string (the Skin Placeholder name).
To get an Attachment from a skin, you need to know its skin key name and the index of the slot it belongs to.
SkeletonData skeletonData = skeleton.Data;
//Skin defaultSkin = skeletonData.DefaultSkin;
Skin foundSkin = skeletonData.FindSkin("robot");
int slotIndex = skeletonData.FindSlotIndex("hand");
string placeholderName = "closed-hand";
Attachment closedHandAttachment = foundSkin.GetAttachment(slotIndex, placeholderName);
For attachments you placed in Skin Placeholders, the name of the Skin Placeholder is the skin key name.
But for the default skin, the skin key name is the name of the attachment itself.
See also Mix and Match documentation or generic Runtime Skins documentation for more information.
Any changes you make to skins and attachments in SkeletonData will affect all instances using that same data.
This is because Skins and Attachments are loaded as SkeletonData-level objects: They are stored as part of the SkeletonData, and shared— but not copied— across all skeletons that use them. Multiple of the same skeleton can have independent states: like different poses, active attachments, mesh deform states and chosen skins; but they will use the same SkeletonData, Skin and Attachment objects by default.
So modifying the skins and attachments in the SkeletonData directly is only advisable if (1) you are instantiate only one of that skeleton or only skeleton per skin, and (2) you store the original state of the modified skin or attachment if you need to return to its original state.
A RegionAttachment is a basic, rectangular, renderable attachment mapped to a texture region.
In Spine-Unity, it maps to a Material, via its RendererObject property. It also contains information about the region of the texture it's supposed to render through various properties.
You can change its color via its R, G, B and A properties, or through the Spine-Unity extension method. attachment.SetColor(UnityEngine.Color).
A MeshAttachment is as a renderable attachment with a deformable set of vertices (see VertexAttachment), as well as triangles, to define a renderable mesh, mapped to a texture region.
Some MeshAttachments have bone weights added to its vertices so that bone positions and movements can drive the shape of the mesh. The interpretation of the MeshAttachment's internal data can change based on whether it is weighted or not. Spine-Unity provides an extension method to determine if it is weighted.
bool isWeighted = meshAttachment.IsWeighted();In Spine-Unity, it maps to a Material, via its RendererObject property. It also contains information about the region of the texture it's supposed to render through various properties.
You can change its color via its R, G, B and A properties, or through the Spine-Unity extension method. attachment.SetColor(UnityEngine.Color).
In spine-csharp, each renderable Attachment type has an object RendererObject property, which is a reference to the runtime-dependent object necessary for rendering that attachment.
In Spine-Unity, RendererObject is a reference to an Spine.AtlasRegion, which has a reference to a Spine.AtlasPage, which has a reference to a UnityEngine.Material.
Spine-Unity provides an extension method to retrieve the Material more easily.
The code to retrieve the Material looks like this:
Material m = meshOrRegionAttachment.GetMaterial();
// Internally, this extension method does this, and some type checks.
//object rendererObject = ((IHasRendererObject)attachment).RendererObject;
//Material m = (Material)((AtlasRegion)rendererObject).page.rendererObject;All renderable attachment types implement the IHasRendererObject interface, which has the object RendererObject property.
// TODO: Describe how to replace the backing texture using an AtlasRegion in Spine-Unity. And how to create a new AtlasRegion using UnityEngine.Sprite and a bare UnityEngine.Texture2D.
AttachmentTools is a collection of utility methods and static classes that help manipulate Spine Attachment objects for Spine-Unity.
These are contained in the namespace:
using Spine.Unity.Modules.AttachmentTools;skeleton.UnshareSkin / skeleton.GetClonedSkin
Gets a duplicate of the skeleton's currently active skin, optionally including items from its default skin. This allows this new skin to be modified without affecting other skeleton instances.
If unshareAttachments or cloneAttachments is true, duplicates of the attachments will also be created. This allows the attachments to be modified without affecting other skeletons that use the original attachments.
In skeleton.UnshareSkin, this duplicate skin is assigned to the Skeleton's .Skin. If AnimationState is provided, the skeleton will be "refreshed" to use the new cloned skin.
skin.GetClone
Creates a clone of a Skin. Attachments in this new skin are not clones.
skin.CopyTo
Copies all the items in a Skin to a given destination Skin.
skin.RemoveAttachment
Removes an item in a Skin.
skin.GetRepackedSkin
Creates an populates a duplicate skin with cloned attachments that use a new packed texture. The new packed texture is comprised of all the regions used by the attachments of the original skin.
You can pass a shader, or a template material so that it can use the right material property and shader keyword values.
renderableAttachment.GetRemappedClone
Creates a clone of the original attachment but mapped to a different texture.
You can use a UnityEngine.Sprite, or an AtlasRegion (see AtlasUtilities) as the texture source.
For MeshAttachments, this gives you the option to inherit the original mesh's animations.
meshAttachment.GetLinkedMesh
Creates a new linked mesh based on the given MeshAttachment.
You can use a Sprite or AtlasRegion (see AtlasUtilities) as the texture source.
These methods create a new AtlasRegion which attachments can use.
texture.ToAtlasRegion
Creates a new AtlasRegion based on a Texture2D. You can provide a shader or template Material to get shader properties and material properties from.
This method creates its own AtlasPage to assign to the new AtlasRegion.
texture.ToAtlasRegionPMAClone
Clones a Texture2D, applies PMA to it, and then creates an AtlasRegion that uses that texture.
Some shaders (such as the Spine default shaders) require a premultiplied alpha texture by default. In those cases, use this method.
This method creates its own AtlasPage to assign to the new AtlasRegion.
material.ToSpineAtlasPage
Creates an AtlasPage based on a Material with a main texture.
This AtlasPage can be reused when creating multiple new AtlasRegions as long as they share the same backing texture.
sprite.ToAtlasRegion
Creates a new AtlasRegion based on a UnityEngine.Sprite.
Passing a cached AtlasPage from material.ToSpineAtlasPage is recommended.
sprite.ToAtlasRegionPMAClone
Creates a clone of the sprite as a new premultiplied alpha texture, then creates an AtlasRegion that uses that texture.
AtlasUtilities.GetRepackedAttachments
Fills an outputAttachments list with new attachment objects based on the attachments in sourceAttachments, but mapped to a new single texture using the same material.
This is useful for if you want an arbitrary set of renderable attachments that come from different texture sources to be repacked into a single texture. This minimizes engine draw calls which are especially important when you have many of the same skeleton being instantiated. This also minimizes dynamic sorting bugs in Unity.
atlasRegion.ToSprite
This creates a new UnityEngine Sprite based on a Spine.AtlasRegion.
This is handy at runtime for when you want to render a region from the atlas using a SpriteRenderer.
However, SpineAtlasAsset's inspector provides a button, which generates Sprite data from the Spine atlas, and have them available in edit mode just like normal Unity sprites.
atlasRegion.ToTexture
This creates a new Texture2D based on an AtlasRegion.
This is mostly a utility method for longer more complex atlas-manipulation operations.
A set of extension methods for manipulating the source region for an Attachment.
Note these do not apply when the skeleton uses TK2D.
Gets an AtlasRegion from a renderable attachment. This is otherwise done by getting its .RendererObject and casting it as an AtlasRegion.
If the attachment is not renderable, the method will return null.
Sets the AtlasRegion of a renderable attachment. This is useful when pulling AtlasRegions from other atlases, or creating new AtlasRegions from other sources.
Premultiply Alpha: http://esotericsoftware.com/forum/Premultiply-Alpha-3132