2D

Sprite Mask

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

070C8B9F-14E2-4A9A-BFEC-4BC3F2BB564F
ParameterTypeDescription
spritenumberA reference to the sprite
alphaCutoffnumberThe lower limit of the effective alpha value (range: 0~1). Pixels with alpha values below this cutoff will be discarded
influenceLayersnumberThe 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:

influenceLayersmaskLayerTakes Effect?
Layer0Layer0Equal → Takes effect
Layer1, Layer2Layer2, Layer3Intersection exists → Takes effect
Layer4Layer5No 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-click2D ObjectSprite Mask to quickly create a node containing a Sprite Mask.

070C8B9F-14E2-4A9A-BFEC-4BC3F2BB564F

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