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 |
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 |
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;