Unity SpriteMask and RectMask2D support

February 22nd, 2019

We are happy to announce support for Unity sprite masks and Unity UI rect masks in our spine-unity runtime!

A sprite mask can be used to either hide or reveal parts of a skeleton or group of skeletons based on a masking image. This feature is implemented for both the SkeletonAnimation and SkeletonMecanim components. It supports all shaders shipped with the spine-unity runtime out of the box.

A rect mask is a masking control similar to the sprite mask control. It can be used to restrict Unity UI SkeletonGraphic objects to a rectangular area with better performance versus using a masking image.

Sprite masks and Spine skeletons

The SkeletonAnimation and SkeletonMecanim components now provide an additional Mask Interaction field in the inspector, mirroring the same mask interaction modes available in Unity's built-in SpriteRenderer component:

The following mask interaction modes are supported:

• None: The sprite will not interact with the masking system. Default behavior.
• Visible Inside Mask: The sprite will be visible only in areas where a mask is present.
• Visible Outside Mask: The sprite will be visible only in areas where a mask is not present.

Automatically generated materials

When switching mask interaction modes in the inspector outside of Play mode, additional material assets are generated for the respective Stencil Compare parameters. These additional material assets use the file suffixes _InsideMask and _OutsideMask, and are placed in the same folder as the original materials.

By default, a Skeleton Animation component keeps references to all generated materials. This allows sharing the materials between many component instances and reduces overhead from generating materials on-the-fly at runtime. You can manage and optimize the generated materials via the Advanced section of the SkeletonAnimation component:

• The Clear button lets you clear references to unneeded materials.
• The Delete button lets you clear the reference to the material and delete the underlying asset. Note that other SkeletonAnimation components on other game objects might still reference the materials. Use with caution!
• The Set button lets you reassign a link to the respective material to prepare them for runtime use. If the material is not present or has been deleted, it is generated again based on the default material.

When changing the Mask Interaction mode at runtime, the component will use the pregenerated materials if available. When these pregenerated materials can not be found, for example because they were deleted via the Advanced section, copies of the default materials are created on-the-fly. These materials are not shared between Skeleton Animation components and can incur overhead when generated frequently on-the-fly at runtime. Prefer to use the pregenerated masking materials when possible!

Stencil Compare shader parameters

Every shader shipped with our spine-unity runtime now exposes the Stencil Compare parameter for further customization. This gives maximum flexibility to customize material management at runtime and lets you create more material variations than the three variations the runtime itself supports.

The available Stencil Compare values are:

• CompareFunction.Disabled for Mask Interaction - None.
• CompareFunction.LessEqual for Mask Interaction - Visible Inside Mask.
• CompareFunction.Greater for Mask Interaction - Visible Outside Mask.

Unity UI - Rect masks and SkeletonGraphic

The shaders used by SkeletonGraphic now support Unity's RectMask2D component. A rect mask can be used to restrict SkeletonGraphic child elements to the rectangle of the parent element.

In the example above, each of the three SkeletonGraphic objects has a parent with a RectMask2D component to constrain it to a rectangular area. RectMask2D is more limited than the standard mask control, but gives better performance.

We hope that these additions to our spine-unity runtime let you create even more visually impressive games and apps. Share your thoughts on the Spine forum.