Sprite Mask

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

Control the interaction with Sprite using parameters provided by SpriteMask.

SpriteMaskLayer declares the mask layers provided by the engine. There are 32 mask layers in total, named Layer0~Layer31. Mask layers are unrelated to rendering and are only used to help developers set how SpriteMask and SpriteRenderer interact. For a SpriteMask object to mask a SpriteRenderer object, their mask layers must intersect.

The influenceLayers of SpriteMask indicates which mask layers the mask will affect for SpriteRenderer. The maskLayer of SpriteRenderer indicates which mask layers the sprite belongs to, as shown below:

In the image above, the spriteMask affects sprites in Layer1 and Layer30. spriteRenderer0 is in Layer2, so there is no intersection, and spriteRenderer0 does not interact with spriteMask. spriteRenderer1 is in Layer1, which intersects with the mask layers affected by spriteMask, so spriteRenderer1 interacts with spriteMask.

Usage

Adding a Sprite Mask Component

When we need to mask a sprite, we first need to create an entity and add a sprite mask component, as shown below:

Setting the Mask Area

The sprite mask component uses an image to represent the mask area. We set the sprite resource through the component's sprite parameter, as shown below:

Setting the Sprite's Mask Type

After the above two steps, you may find that the mask still has no effect. This is because the current sprite's mask type is still the default (None). We set the mask interaction of the sprite in the scene to the inner mask type, as shown below:

Setting alpha cutoff

This parameter represents the lower limit of the effective alpha value for the current mask (range: 0~1). In other words, any alpha value in the sprite's texture that is less than the alpha cutoff will be discarded (i.e., it will not be considered as a mask area). We can dynamically adjust the value of this property to see the actual effect, as shown below:

Similarly, in the script, we can use the following code to apply the sprite mask:

// 创建一个遮罩实体
const spriteEntity = rootEntity.createChild(`spriteMask`);
// 给实体添加 SpriteMask 组件
const spriteMask = spriteEntity.addComponent(SpriteMask);
// 通过 texture 创建 sprite 对象
const sprite = new Sprite(engine, texture);
// 设置 sprite
spriteMask.sprite = sprite;
// mask 的 sprite 中纹理 alpha 小于 0.5 的将被丢弃
spriteMask.alphaCutoff = 0.5;
// mask 对所有遮罩层的精灵都生效
spriteMask.influenceLayers = SpriteMaskLayer.Everything;
// mask 只对处于遮罩层 Layer0 的精灵有效
spriteMask.influenceLayers = SpriteMaskLayer.Layer0;
// mask 对处于遮罩层 Layer0 和 Layer1 的精灵有效
spriteMask.influenceLayers = SpriteMaskLayer.Layer0 | SpriteMaskLayer.Layer1;
 
// 设置遮罩类型
spriteRenderer.maskInteraction = SpriteMaskInteraction.VisibleInsideMask;
// 设置精灵处于哪个遮罩层
spriteRenderer.maskLayer = SpriteMaskLayer.Layer0;