effect-motion
Guides

Alpha masks

Reveal or hide shapes, text, images, and groups with an independently animated source

An alpha mask uses one existing instance to control where another is visible. Create both instances, then attach the source with Scene.setMask(target, source). The source keeps its place in the instance tree and can animate independently, but it supplies coverage instead of drawing its own color while attached.

Reveal text with a moving shape

This rectangle sweeps across a stationary Text. The title fades at the same time, so its final opacity and the mask's position are independent.

0:00
import * as Color from "effect-motion/Color";import * as Entity from "effect-motion/Entity";import * as Motion from "effect-motion/Motion";import * as Scene from "effect-motion/Scene";export const scene = Scene.make(	"mask text reveal",	function* () {		const title = yield* Scene.instantiate("Text", {			text: "REVEAL",			fontSize: 220,			fillColor: Color.hex("#f4f0e8"),			textAnchor: "middle",			baseline: "middle",		});		const wipe = yield* Scene.instantiate("Rect", {			position: Entity.vec3({ x: -1300 }),			width: 1300,			height: 300,			fillColor: Color.hex("#ff5a1f"),		});		yield* Scene.setMask(title, wipe);		yield* Scene.all([			Motion.moveTo(wipe, { x: 0 }, "2 seconds", "easeInOutCubic"),			Motion.fadeTo(title, 0.7, "2 seconds"),		]);		yield* Motion.wait("500 millis");	},	{ width: 1920, height: 1080, backgroundColor: Color.hex("#16161d") },);

The call defaults to { mode: "alpha" }: target alpha is multiplied by the source's alpha at each projected pixel. The source's color does not affect the result. Move a source with Motion.moveTo, fade it with Motion.fadeTo, or animate the target with the same helpers. Both retain their usual exact animation endpoints.

Cut a hole from a group

Pass { mode: "inverse" } to use one minus the source alpha. Here a Circle cuts a moving hole through a Group containing a colored card and text. The Group stays an ordinary container: each child keeps its own depth and paint order among surrounding content.

0:00
import * as Color from "effect-motion/Color";import * as Entity from "effect-motion/Entity";import * as Motion from "effect-motion/Motion";import * as Scene from "effect-motion/Scene";export const scene = Scene.make(	"mask inverse cutout",	function* () {		const card = yield* Scene.instantiate("Group", {			children: [				Scene.instantiate("Rect", {					width: 1150,					height: 440,					fillColor: Color.hex("#7f5af0"),				}),				Scene.instantiate("Text", {					text: "CUT OUT",					fontSize: 150,					fillColor: Color.hex("#f4f0e8"),					textAnchor: "middle",					baseline: "middle",				}),			],		});		const hole = yield* Scene.instantiate("Circle", {			position: Entity.vec3({ x: -580 }),			radius: 170,			fillColor: Color.hex("#ff5a1f"),		});		yield* Scene.setMask(card, hole, { mode: "inverse" });		yield* Motion.moveTo(hole, { x: 580 }, "2 seconds", "easeInOutCubic");		yield* Motion.wait("500 millis");	},	{ width: 1920, height: 1080, backgroundColor: Color.hex("#16161d") },);

A target can have one mask at a time. Calling setMask again replaces its attachment; the former source resumes ordinary drawing unless it is still suppressed by another active source subtree. Scene.clearMask(target) removes the attachment on the current frame. The former source then draws normally if it is mounted and visible. Hide or remove it yourself if it should remain off screen. clearMask on an unmasked target has no effect.

Use partial coverage

Source opacity, transparent image pixels, glyph edges, and shape edges all produce partial coverage. The example's Circle has opacity 0.45, while the target Rect has opacity 0.8. Where they overlap, normal-mode target alpha is 0.8 × 0.45 = 0.36; the green card remains visible through it.

0:00
import * as Color from "effect-motion/Color";import * as Entity from "effect-motion/Entity";import * as Motion from "effect-motion/Motion";import * as Scene from "effect-motion/Scene";export const scene = Scene.make(	"mask partial alpha",	function* () {		const backdrop = yield* Scene.instantiate("Rect", {			width: 1350,			height: 560,			fillColor: Color.hex("#2cb67d"),		});		const panel = yield* Scene.instantiate("Rect", {			width: 1100,			height: 400,			fillColor: Color.hex("#f4f0e8"),			opacity: 0.8,		});		const softSource = yield* Scene.instantiate("Circle", {			position: Entity.vec3({ x: -440 }),			radius: 240,			fillColor: Color.hex("#ff5a1f"),			opacity: 0.45,		});		yield* Scene.setMask(panel, softSource);		yield* Scene.all([			Motion.moveTo(softSource, { x: 440 }, "2 seconds", "easeInOutCubic"),			Motion.fadeTo(backdrop, 0.5, "2 seconds"),		]);		yield* Motion.wait("500 millis");	},	{ width: 1920, height: 1080, backgroundColor: Color.hex("#16161d") },);

In inverse mode the same overlap would have alpha 0.8 × (1 − 0.45) = 0.44. An invisible source supplies zero coverage. A source outside the view also supplies zero coverage. There is no luminance mask or dedicated feather control; source alpha and edges define the coverage.

Choose a source and target

Any paintable Line, Path, Rect, Circle, Ellipse, Text, Image, Group, or Hud can be a source or target. A Group source combines its eligible children into one coverage field. Text uses its glyph coverage, and an Image uses its decoded image alpha. Camera cannot be masked or used as a source. A mask source may itself have a mask, and masks on a Group and its descendant multiply their factors once per drawable child.

The source and target must be mounted in the same scene composition and the same render tier. World content uses that composition's camera and each instance's tree transform; a Hud subtree uses screen coordinates and stays sharp over the world. Their coverage meets in projected composition pixels, even when they have different parents or depths. Source depth affects overlap within the source, but it does not have to match the target's depth. A Scene.play mount is a composition boundary: mask its group in the parent, or attach a separate source and target inside the played scene. A source inside the child cannot mask a target in the parent. Child content remains sharp internally; the parent's depth of field treats its plane as one layer.

Each source can mask only one target. The source and target cannot be the same instance, contain one another, form a mask cycle, or cross a world/HUD or composition boundary. Invalid relationships fail with diagnostics naming the instances and rule. Detaching or destroying an endpoint, or an ancestor that unmounts it, clears the attachment. Moving an endpoint to another parent in the same domain retains it; a move that would break a mask relationship fails. The source returns to ordinary rendering when its attachment clears.

Masks preserve each target fragment's depth: a fully hidden pixel reveals objects behind it; fully opaque covered pixels still occlude; partial pixels follow the renderer's translucent depth behavior. World depth of field uses the target's depth, with the existing approximation for translucent content. HUD masks stay sharp. Masking does not add Boolean mask operations, physical transparency blur, or a visual mask editor.

For a fixed rectangular crop, a smaller transparent scene mounted with Scene.play still clips to its bounds; see Precomps, masks and HUD.

On this page