Menu
Lumberyard
User Guide (Version 1.14)

Mask

You can add a mask component to an element to show a portion of content in child elements (for example, image or text).

To see in-game examples of completed canvases with a Mask component

  1. Open the Samples Project.

  2. When Lumberyard Editor has started, choose File, Open and open the UiFeatures level.

  3. Press Ctrl+G to play the game.

  4. Choose Components, Other Components, Mask.

  5. Press Esc to exit the game.

To view these same canvases in the UI Editor

  • Navigate to the \Gems\LyShineExamples\Assets\UI\Canvases\LyShineExamples\Comp\Mask directory.

You can open the following canvases:

  • AlphaMask.uicanvas – Using a texture with alpha as a mask

  • Basic.uicanvas – Basic mask example

  • ImageMode.uicanvas – Examples of using different image modes on the image used for the mask

  • MaskingInteractables.uicanvas – Example of how masks interact with interactable components

  • NestedMasks.uicanvas – Example of nesting masks

  • TextMask.uicanvas – Example of using text as the visual component of the mask

When you add a mask component, the default mask (visible area) is a square. If you want to use a nonrectangular mask, you need a texture or image that contains an alpha channel, which specifies transparent and opaque areas. You can set the image component of the element as a custom image to be used as a mask. The child elements are drawn to (shown by) the visible area of the image and hidden by the transparent area of the image. Masks are most commonly used with a ScrollBox prefab element.

To add an image to be used as a custom mask

  1. In the UI Editor toolbar, create a new empty element by choosing New, Empty Element. This is the parent element.

  2. In the Properties pane, add an image component by choosing Add Component, Image.

  3. Add a mask component by choosing Add Component, Mask.

  4. Add a child element by right-clicking the parent element and then choosing New, Empty Element.

  5. Select the child element. Add an image component to the child element.

  6. Select an image for the child element by clicking the folder icon next to Image, Sprite Path in the Properties pane. Open an image file that is located within your current project directory.

  7. Select the parent element. Select the texture or image to use as a mask by clicking the folder icon next to the Image, Sprite Path in the Properties pane. Open an image file that is located within your current project directory.

    The image that you use as a mask should have opaque areas (which shows the content in child elements) and transparent areas (which hides the content in child elements).

  8. In the Properties pane, under Mask, select Use alpha test.

To edit a mask component

In the Properties pane of the UI Editor, expand Mask and use the following settings, as appropriate:

Enable Masking

Enables masking (selected by default). When selected, only the parts of the child elements that are revealed by the mask are visible.

Draw behind

Draws the mask visual behind the child elements. Can be useful for debugging purposes.

Draw in front

Draws the mask visual in front of the child elements. Can be useful for debugging purposes.

Use alpha test

Uses the alpha channel in the masks visual's texture to define the mask. Must be enabled for masks that are anything other than a rectangle.

Mask interaction

Prevents input events from being sent to elements that are outside of the mask.