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.
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 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
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.
Edit Mesh mode has three tools:
Modifyallows vertices and edges to be translated by dragging. Multiple vertices can be selected by holding
Createallows new vertices to be created by clicking and new edges to be created by dragging.
Deleteallows vertices or edges to be deleted by clicking. Multiple vertices can be selected by holding
With any of the tools, vertices can be deleted by double clicking. Right click switches tools.
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 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
Generate will create a grid with vertices arranged in rows and columns.
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 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 checkbox is extremely useful for most mesh editing. It is checked by default.
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.
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.
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.
It is not necessary to create edges (orange) over the edges Spine creates automatically (gray). Doing so does not change the mesh triangulation, but may make it easier to select parts of the mesh, especially when using edge loop selection.
If a mesh edge is selected while
shift is held, edge loop selection is performed. This selects an edge and all neighboring edges in a line. While holding
cmd on Mac) can also be held as normal to add to the current selection.
There are a number of factors to consider when choosing where to place mesh vertices.
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.
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.
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.
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
cmd on Mac), then clicking or dragging to box select. The selected vertices can be deselected by pressing
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
Scale tool until a circle appears, then drag the origin to the desired position. The origin will automatically snap to vertices.
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
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 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.
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.
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.
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.
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
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.
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.
Meshes can be automatically deformed when bones are transformed. See Weights for more information.