Mesh attachments

Meshes allow a polygon to be defined inside an image, then the polygon vertices can be manipulated to bend and deform the image in powerful ways. Meshes also have the advantage that the polygon can exclude blank space in an image, which can reduce fill rate usage and potentially increase performance.

Please note that mesh attachments are not available in Spine Essential.

Setup

To create a mesh, first create a region attachment from an image under the Images node, then check Mesh in the region attachment's properties at the bottom of the tree.

The region attachment is converted to a mesh with 4 vertices, one in each corner.

Edit Mesh mode

Clicking the Edit Mesh button enters Edit Mesh mode. The mesh vertices in this mode represent the mesh's texture coordinates, also known as UVs.

Edit Mesh mode can be exited at any time by pressing spacebar or escape, by clicking the Edit Mesh button in the properties at the bottom of the tree, or by closing the Edit Mesh dialog.

The Outline view can be used to visualize the mesh while changing the UVs.

Tools

Edit Mesh mode has three tools:

  • Modify allows vertices and edges to be translated by dragging. Multiple vertices can be selected by holding ctrl (cmd on Mac).
  • Create allows new vertices to be created by clicking and new edges to be created by dragging.
  • Delete allows vertices or edges to be deleted by clicking. Multiple vertices can be selected by holding ctrl (cmd on Mac).

With any of the tools, vertices can be deleted by double clicking. Right click switches tools.

Reset UVs

The Reset button replaces all vertices with 4 vertices, one in each corner. All weights and deform keys in animations are removed. The Reset button is useful to start over. This should not be confused with the Reset button in the tree properties for a mesh.

Generate

The Generate button adds new vertices to the mesh at positions that will benefit deformation the most. All weights and deform keys in animations are removed. Generate can be clicked multiple times to add more and more vertices. Existing vertices are not moved, so Generate can be used to automatically fill in a mesh after manually adding vertices around important features in the image.

If a mesh has vertices in all 4 corners, such as after clicking Reset, then Generate will create a grid with vertices arranged in rows and columns.

New mode

Clicking the New button deletes all vertices and enters New vertices mode. This mode allows the hull of the mesh to be defined by clicking to create a vertex. Vertices can also be translated by dragging or deleted by double clicking. When the mesh hull is complete, exit New mode by clicking the first vertex to close the shape or by clicking the New button.

New mode allows the hull of the mesh to be defined quickly. Alternatively, the Create tool can be used to create vertices and edges, then the Delete tool used to remove any unwanted vertices or edges.

Deformed

The Deformed checkbox is extremely useful for most mesh editing. It is checked by default.

When Deformed is unchecked and a vertex is translated in Edit Mesh mode, it changes the position on the image that is used for the vertex when drawn, but it does not change the position of the vertex outside of Edit Mesh mode. When Edit Mesh mode is exited, you will find the vertex position has not changed but the image is now stretched differently across the mesh.

In Edit Mesh mode, when Deformed is checked it shows the mesh as it looks outside of Edit Mesh mode. When a vertex is translated, it changes both the vertex position and the position on the image that is used for the vertex when drawn. The vertex positions are still limited to the image bounds.

Edges

A mesh's vertices and edges are used to decompose the mesh into a number of triangles, shown as faint gray lines in Edit Mesh mode. Triangles will never cross an edge, so creating edges gives complete control over how the vertices are connected by triangles. This is important because the triangles determine how a mesh is deformed when a vertex is translated.

For example, we have made the hull for spineboy's head and now want to make the nose stretch.

When the vertex was moved, only the triangles that include the vertex are deformed. This stretches the tip of the nose but not the base and also stretches some of the cheek. By introducing a new vertex, we will get different triangles and the mesh will deform differently.

A new vertex was added at the base of the nose which results in different triangles. Now the vertex we are moving belongs to two triangles. When the vertex is moved, it deforms both triangles. This stretches the entire nose, but also a lot of the cheek. Another vertex is needed to stop the cheek from deforming.

A new vertex was added under the nose. The entire nose is now contained within two triangles, but moving the vertex deforms only one of them. To fix this, in Edit Mesh mode we need to create an edge by selecting the Create tool and dragging between vertices.

The new edge (displayed in orange) causes the nose triangles to connect differently and the nose can be deformed without affecting the rest of the head.

Vertices

There are a number of factors to consider when choosing where to place mesh vertices.

Hull size

The hull of the mesh should exclude as much blank space as possible. Any pixels outside the hull are not drawn and do not count against the fill rate. This can improve performance for a game that is fill rate limited, especially for large images with a lot of blank space. For example, a tree image may have a lot of blank space on either side of the trunk. It is not possible for meshes to contain holes.

Vertex count

Generally the number of vertices in a mesh should be kept to a minimum because the position of each vertex must be computed by the CPU each frame. This is a fast operation, but many skeletons on screen at once with many meshes each having many vertices can add up to thousands of positions that need to be computed.

When using weights, each bone affecting a vertex adds an additional vertex transform. For example, a mesh with 100 vertices requires 100 vertex transforms. If the same mesh has 2 bones affecting every vertex, it requires 200 vertex transforms. If a mesh is bound to many bones and smoothing is used to spread the weights out, it can greatly increase the number of vertex transforms required. Use pruning to remove unnecessary weights.

Deformation

Where vertices are placed and how they are connected by triangles determines how the mesh deforms. Edges should be used to control how the vertices are connected by triangles.

When an image needs to bend, for example when weights are used, it is important to have enough vertices for a smooth bend. For example, a long tail.

A common deformation effect is to make a mesh appear 3D. One way to achieve this is to use an edge along the center of the mesh, following any contours in the image. The edge vertices are then animated toward the mesh hull. This stretches half the mesh and squashes the other half, creating the illusion that the mesh is rotating in 3D.

Animations by hwadock.

Transform tools

The mesh vertices can be edited outside of Edit Mesh mode by using the transform tools. The entire mesh can be rotated, translated, and scaled like any other attachment.

Individual vertices can be translated with any transform tool by dragging, which will deform the image. Multiple vertices can be selected by holding ctrl (cmd on Mac), then clicking or dragging to box select. The selected vertices can be deselected by pressing spacebar or escape, or by clicking in any empty space.

The origin used for rotation or scaling can be changed. Mouse over the small crosshair at the center of the Rotate or Scale tool until a circle appears, then drag the origin to the desired position. The origin will automatically snap to vertices.

Freeze

A mesh does not really have a rotation, translation, or scale. Instead, the mesh is made up of a number of vertices, each of which is a position relative to the mesh's parent bone. Spine provides rotation, translation, and scale for convenience and so meshes can be manipulated similar to other attachments. The translation is the centroid of the mesh hull. The rotation and scale are adjusted when the Rotate or Scale tools are used on the entire mesh. The Freeze button can be used to set the rotation and scale values to 0 and 1 respectively for the current vertex positions.

Reset

The Reset button adjusts the mesh's vertex positions so they are not deformed -- they will match the UVs as defined in Edit Mesh mode. Since all the vertices are given new positions, the mesh may shift position if it was deformed. All weights and deform keys in animations are removed. This should not be confused with the Reset button in Edit Mesh mode.

When vertices are added, removed, or translated in Edit Mesh mode, the vertex positions outside of Edit Mesh mode may not be in the desired position. Reset can be used to remove any deformation from the mesh.

Color

The color tints the mesh attachment image, but cannot be changed during animations. To animate the color, set the slot color instead of the mesh attachment color.

Keying

When a mesh's vertices have been manipulated in animate mode, the mesh can be keyed. Animating a mesh's vertices is known as keying deformation.

Even though the mesh vertices can be rotated with the Rotate tool, when the mesh keys are actually tweened the vertices will translate in a straight line from their position in the first key to their position in the next key. Multiple keys can be used to make the vertices appear to move in an arc.

All vertices are keyed together. This can make it difficult to animate different parts of the same mesh solely by using deformation, unless all the deform animation is done using straight ahead. For complex mesh animation, it is best to use weights.

Whitespace stripping

When using the texture packer, whitespace stripping cannot be applied to images that are used for meshes. A mesh may have UVs in the whitespace. If the whitespace was removed, the mesh would use pixels outside of the mesh's texture atlas region.

Each image for a mesh should only contain the whitespace the mesh requires and whitespace stripping should be disabled in the texture packer settings.

Image resize

If an image file a mesh uses is made larger, Spine assumes whitespace has been added to the edges of the image and adjusts the mesh UVs to keep the image contents the same size, centered by how much larger the image is. Afterward, if the whitespace was not added evenly to all sides of the image, the UVs may need to be manually adjusted in Edit Mesh mode. Select all vertices by holding ctrl (cmd on Mac), then drag to box select. Next, use the Modify tool to move the vertices to the correct position.

If the image was made larger because a higher resolution image is needed, keeping the UVs the same size may not be desirable. Spine currently doesn't have a way to scale the UVs, so the mesh will have to be recreated. To change to size of all images for a skeleton, see Import Data - Scale.

If an image file a mesh uses is made smaller, the UVs are scaled the same amount. This would be desirable to reduce the resolution of the original image.

If the image was made smaller by trimming, so the image contents are the same size but the image dimensions are now smaller, then the scaled down UVs may not be desirable. Spine currently doesn't have a way to scale the UVs, so the mesh will have to be recreated.

Linked meshes

It is common to want to reuse a mesh with a different image. For example, you have animated a mesh for a flag using deformation and now you want to use various different flag images with the same mesh and animations.

Duplicating the mesh isn't a great solution because it results in two separate meshes, so any changes to the mesh need to be made multiple times. Also, the original mesh's deform keys are not applied to the duplicate mesh. The deform keys could be copied and pasted, but then after any animation edits the deform keys need to be updated for each duplicate mesh.

Linked meshes solve this problem. To create a linked mesh, click the blue linked mesh button in the mesh properties below the tree:

This is similar to duplicating a mesh, except the new mesh uses the same mesh structure (vertices, edges, UVs, triangles, and weights). Because linked meshes share the same mesh structure as the original mesh, any changes to the original mesh or to any linked meshes will affect all the meshes. To indicate that changing a vertex will affect other meshes, the vertices appear with a ring around them:

To use a different image for the linked mesh, simply rename it or set a Path, as normal. If Inherit Deform is checked, then any deform keys for the original mesh will also affect the linked mesh. If Inherit Deform is not checked, deform keys for the linked mesh can be set as normal.

Linked meshes must always be under the same slot as the original mesh. Moving any of them to another slot will cause all the meshes to be moved. Linked meshes can be in different skins.

Weights

Meshes can be automatically deformed when bones are transformed. See Weights for more information.

Video

Next: Bounding Boxes Previous: Point Attachments