Mask Component Reference

Mask is used to specify the range which clip the render results of the children. A node with a Mask component will use a bounding box (which is specified by the contentSize of the UITransform component in the Inspector) to create a rectangular rendered mask. All child nodes of this node will only appear inside the mask’s boundary.

mask

Select a node in the Hierarchy panel, then click the Add Component button at the bottom of the Inspector panel and select Mask from UI -> Render. Then you can add the Mask component to the node.

Note: the Mask component cannot be added to a node with other renderer components such as Sprite, Label, etc.

To use Mask, please refer to the Mask API documentation and the mask scene of the test-cases-3d project.

Mask Properties

PropertyFunction Explanation
TypeMask type, including RECT, ELLIPSE, GRAPHICS_STENCIL, IMAGE_STENCIL.
SegmentsThe segments for ellipse mask, which takes effect only when the Mask type is set to ELLIPSE.
InvertedThe Reverse mask.
SpriteFrameImage used for the type is IMAGE_STENCIL

Type

RECT

mask

ELLIPSE

mask

It can also be set by code at runtime. Example:

  1.     const mask = this.getComponent(Mask);
  2.     mask.type = Mask.Type.ELLIPSE;
  3.     mask.segments = 32;

GRAPHICS_STENCIL

mask

It can also be set by code at runtime. Example:

  1.     const mask = this.getComponent(Mask);
  2.     mask.type = Mask.Type.GRAPHICS_STENCIL;
  3.     const g = mask.graphics;
  4.     g.lineWidth = 10;
  5.     g.fillColor.fromHEX('#ff0000');
  6.     g.moveTo(-40, 0);
  7.     g.lineTo(0, -80);
  8.     g.lineTo(40, 0);
  9.     g.lineTo(0, 80);
  10.     g.close();
  11.     g.stroke();
  12.     g.fill();

IMAGE_STENCIL

mask

It can also be set by code at runtime. Example:

  1.     const mask = this.getComponent(Mask);
  2.     mask.type = Mask.Type.IMAGE_STENCIL;
  3.     mask.spriteFrame = this.spriteFrame;
  4.     mask.alphaThreshold = 0.1;

Notes:

  1. After adding the Mask component to a node, all nodes in the sub tree of this node will be affected by Mask during rendering.
  2. The GRAPHICS_STENCIL simply provides the graphics component, which developers can use graphics property in the mask component to draw custom graphics. But the node click events are still calculated based on the size of the node.
  3. The IMAGE_STENCIL type requires a picture resource by default. If it is not set, it is equivalent to no mask.
  4. In the current version and previous versions, due to the underlying rendering architecture, the rendering content of all sub-nodes of Mask in the editor is invisible. The solution is to adjust the layer of the Mask node in the editor to default, which will not affect the runtime data.