2D

Sprite Mask

The Sprite Mask component is used to apply masking effects to Sprite Renderers and Text Renderers in 3D/2D scenes.

Parameter	Type	Description
sprite	number	A reference to the sprite
alphaCutoff	number	The lower limit of the effective alpha value (range: 0~1). Pixels with alpha values below this cutoff will be discarded
influenceLayers	number	The mask layer(s) affected by this mask. Defaults to Everything, meaning it affects all mask layers

Currently, only sprite-based masks are supported to define the mask shape

The hierarchical relationship between a Sprite Mask and its target components typically falls into three categories:

influenceLayers	maskLayer	Takes Effect?
Layer0	Layer0	Equal → Takes effect
Layer1, Layer2	Layer2, Layer3	Intersection exists → Takes effect
Layer4	Layer5	No intersection → Does not take effect

influenceLayers: Layers affected by the sprite mask; maskLayer: Mask layer of the target component

If the mask still has no effect after adjusting layers, it might be because the target component's mask type is still set to the default (None). Update its SpriteMaskInteraction accordingly

Usage

In the Hierarchy Panel, right-click → 2D Object → Sprite Mask to quickly create a node containing a Sprite Mask.

You can use the Sprite Mask in scripts as follows:

// Create a mask entity
const spriteEntity = rootEntity.createChild(`spriteMask`);
// Add the SpriteMask component to the entity
const spriteMask = spriteEntity.addComponent(SpriteMask);
// Create a sprite object from a texture
const sprite = new Sprite(engine, texture);
// Assign the sprite
spriteMask.sprite = sprite;
// Discard pixels with alpha < 0.5 in the mask's texture
spriteMask.alphaCutoff = 0.5;
// Apply mask to all mask layers
spriteMask.influenceLayers = SpriteMaskLayer.Everything;
// Apply mask only to Layer0
spriteMask.influenceLayers = SpriteMaskLayer.Layer0;
// Apply mask to both Layer0 and Layer1
spriteMask.influenceLayers = SpriteMaskLayer.Layer0 | SpriteMaskLayer.Layer1;
 
// Set mask interaction type
spriteRenderer.maskInteraction = SpriteMaskInteraction.VisibleInsideMask;
// Assign the component to Layer0
spriteRenderer.maskLayer = SpriteMaskLayer.Layer0;

Was this page helpful?

On this page

Usage