Cocos 组件 / 2D / Mask节点

学习目标

访问 Cocos Creator 组件的属性、方法和事件，把引擎能力转成可视化工作流。

覆盖范围

• 节点数量：11
• 分类路径：Cocos 组件 / 2D / Mask

典型使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

通用注意事项

• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。
• 部分组件能力受 Cocos Creator 版本限制，页面会标出版本字段。

节点索引

节点	节点 ID	输入/输出	执行方式
获取 Alpha 阈值	maskGetAlphaThreshold	1 / 1	立即继续
获取反向遮罩	maskGetInverted	1 / 1	立即继续
获取所有属性	maskGetProperties	1 / 4	立即继续
获取椭圆细分数	maskGetSegments	1 / 1	立即继续
获取遮罩类型	maskGetType	1 / 1	立即继续
设置 Alpha 阈值	maskSetAlphaThreshold	3 / 2	立即继续
设置反向遮罩	maskSetInverted	3 / 2	立即继续
设置所有属性	maskSetProperties	6 / 2	立即继续
设置椭圆细分数	maskSetSegments	3 / 2	立即继续
设置遮罩类型	maskSetType	3 / 2	立即继续
遮罩命中判断	maskIsHit	2 / 1	立即继续

获取 Alpha 阈值

获取 Alpha 阈值：返回 Mask 组件图片模板的 Alpha 阈值。 默认值：0.1。 注意：该属性仅在 type = SPRITE_STENCIL（图片模板）时有效。只有模板像素的 alpha 值大于等于阈值时才会显示内容。当值为 1 时，所有模板像素都会被丢弃，等价于什么都不显示。图片模板需要同节点 Sprite 组件提供有效 spriteFrame。

节点信息

字段	值
节点 ID	maskGetAlphaThreshold
分类	Cocos 组件
二级分类	2D
分组	Mask
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
mask	Mask 组件	数据	cc.Component / Mask	目标 Mask 组件 要操作的 Mask 组件。 Mask 组件会裁剪当前节点整棵子树的渲染内容，只有遮罩区域内（或反向遮罩时区域外）的内容会被显示。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
alphaThreshold	Alpha 阈值	数据	number	Alpha 阈值 仅在 type = SPRITE_STENCIL 时有效。 只有模板像素 alpha >= 阈值时才显示内容。 取值范围 [0, 1]，为 1 时等价于什么都不显示。	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

获取反向遮罩

获取反向遮罩：返回 Mask 组件是否启用反向遮罩。 默认值：false。 注意：反向遮罩是指显示遮罩区域外部的内容，而不是简单的颜色反相。当 inverted = true 时，遮罩区域内的内容会被隐藏，区域外的内容会被显示。

节点信息

字段	值
节点 ID	maskGetInverted
分类	Cocos 组件
二级分类	2D
分组	Mask
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
mask	Mask 组件	数据	cc.Component / Mask	目标 Mask 组件 要操作的 Mask 组件。 Mask 组件会裁剪当前节点整棵子树的渲染内容，只有遮罩区域内（或反向遮罩时区域外）的内容会被显示。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
inverted	反向遮罩	数据	boolean	反向遮罩 true=显示遮罩区域外部内容 false=显示遮罩区域内部内容	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

获取所有属性

一次性读出 Mask 组件的全部常用属性：遮罩类型、反向遮罩、椭圆细分数、Alpha 阈值。等同于连接多个 获取类节点，但只用一个节点即可。适合序列化、调试、批量比较等场景。

节点信息

字段	值
节点 ID	maskGetProperties
分类	Cocos 组件
二级分类	2D
分组	Mask
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
mask	Mask 组件	数据	cc.Component / Mask	目标 Mask 组件 要操作的 Mask 组件。 Mask 组件会裁剪当前节点整棵子树的渲染内容，只有遮罩区域内（或反向遮罩时区域外）的内容会被显示。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
type	遮罩类型	数据	number	遮罩类型 GRAPHICS_RECT（=0）：矩形遮罩 GRAPHICS_ELLIPSE（=1）：椭圆遮罩 GRAPHICS_STENCIL（=2）：自定义图形模板 SPRITE_STENCIL（=3）：图片模板	-	可选
inverted	反向遮罩	数据	boolean	反向遮罩 true=显示遮罩区域外部内容 false=显示遮罩区域内部内容	-	可选
segments	细分数	数据	number	椭圆细分数 椭圆遮罩的细分段数，仅在 type = GRAPHICS_ELLIPSE 时有效。	-	可选
alphaThreshold	Alpha 阈值	数据	number	Alpha 阈值 仅在 type = SPRITE_STENCIL 时有效。 取值范围 [0, 1]。	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

获取椭圆细分数

获取椭圆细分数：返回 Mask 组件椭圆遮罩的细分段数。 默认值：64。 注意：该属性仅在 type = GRAPHICS_ELLIPSE（椭圆遮罩）时有效。更高的细分数会让椭圆边缘更平滑，但也会增加路径点数量。输入值会被限制到 [3, 10000] 范围内。

节点信息

字段	值
节点 ID	maskGetSegments
分类	Cocos 组件
二级分类	2D
分组	Mask
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
mask	Mask 组件	数据	cc.Component / Mask	目标 Mask 组件 要操作的 Mask 组件。 Mask 组件会裁剪当前节点整棵子树的渲染内容，只有遮罩区域内（或反向遮罩时区域外）的内容会被显示。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
segments	细分数	数据	number	椭圆细分数 椭圆遮罩的细分段数，仅在 type = GRAPHICS_ELLIPSE 时有效。 值越大椭圆越平滑，限制范围 [3, 10000]。	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

获取遮罩类型

获取遮罩类型：返回 Mask 组件的当前遮罩类型。 类型枚举：

• 0 GRAPHICS_RECT：矩形遮罩，使用节点 UI 矩形范围裁剪
• 1 GRAPHICS_ELLIPSE：椭圆遮罩，使用节点 UI 矩形内切椭圆裁剪，可通过 segments 调节精度
• 2 GRAPHICS_STENCIL：自定义图形模板，需同节点 Graphics 组件配合绘制模板形状
• 3 SPRITE_STENCIL：图片模板，需同节点 Sprite 组件上已具备有效 spriteFrame

节点信息

字段	值
节点 ID	maskGetType
分类	Cocos 组件
二级分类	2D
分组	Mask
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
mask	Mask 组件	数据	cc.Component / Mask	目标 Mask 组件 要操作的 Mask 组件。 Mask 组件会裁剪当前节点整棵子树的渲染内容，只有遮罩区域内（或反向遮罩时区域外）的内容会被显示。	-	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
type	遮罩类型	数据	number	遮罩类型 GRAPHICS_RECT（=0）：矩形遮罩 GRAPHICS_ELLIPSE（=1）：椭圆遮罩 GRAPHICS_STENCIL（=2）：自定义图形模板，需配合 Graphics 组件 SPRITE_STENCIL（=3）：图片模板，需配合 Sprite 组件	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

设置 Alpha 阈值

设置 Alpha 阈值：设置 Mask 组件图片模板的 Alpha 阈值。 默认值：0.1。 注意：该属性仅在 type = SPRITE_STENCIL（图片模板）时有效。只有模板像素的 alpha 值大于等于阈值时才会显示内容。当值为 1 时，所有模板像素都会被丢弃，等价于什么都不显示。图片模板需要同节点 Sprite 组件提供有效 spriteFrame。

节点信息

字段	值
节点 ID	maskSetAlphaThreshold
分类	Cocos 组件
二级分类	2D
分组	Mask
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
mask	Mask 组件	数据	cc.Component / Mask	目标 Mask 组件 要操作的 Mask 组件。 Mask 组件会裁剪当前节点整棵子树的渲染内容，只有遮罩区域内（或反向遮罩时区域外）的内容会被显示。	-	必填
alphaThreshold	Alpha 阈值	数据	number	Alpha 阈值 仅在 type = SPRITE_STENCIL 时有效。 只有模板像素 alpha >= 阈值时才显示内容。 取值范围 [0, 1]，为 1 时等价于什么都不显示。	输入框 默认值：0.1	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
mask	Mask 组件	数据	cc.Component / Mask	目标 Mask 组件 透传当前操作的 Mask 组件，便于链式修改遮罩配置。	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

设置反向遮罩

设置反向遮罩：设置 Mask 组件是否启用反向遮罩。 默认值：false。 注意：反向遮罩是指显示遮罩区域外部的内容，而不是简单的颜色反相。当 inverted = true 时，遮罩区域内的内容会被隐藏，区域外的内容会被显示。

节点信息

字段	值
节点 ID	maskSetInverted
分类	Cocos 组件
二级分类	2D
分组	Mask
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
mask	Mask 组件	数据	cc.Component / Mask	目标 Mask 组件 要操作的 Mask 组件。 Mask 组件会裁剪当前节点整棵子树的渲染内容，只有遮罩区域内（或反向遮罩时区域外）的内容会被显示。	-	必填
inverted	反向遮罩	数据	boolean	反向遮罩 true=显示遮罩区域外部内容 false=显示遮罩区域内部内容	开关 默认值：false	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
mask	Mask 组件	数据	cc.Component / Mask	目标 Mask 组件 透传当前操作的 Mask 组件，便于链式修改遮罩配置。	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

设置所有属性

一次性批量修改 Mask 组件的多个常用属性。 公开引脚语义（重要）：除 exe 与 mask 外，所有可写属性引脚默认不公开（isPublic: false），只有被显式公开的引脚才参与写入。若想保留目标属性原值不变，必须保持引脚不公开——仅断开连线不够，已公开的引脚会用内联控件默认值覆盖原值。

节点信息

字段	值
节点 ID	maskSetProperties
分类	Cocos 组件
二级分类	2D
分组	Mask
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
mask	Mask 组件	数据	cc.Component / Mask	目标 Mask 组件 要操作的 Mask 组件。 Mask 组件会裁剪当前节点整棵子树的渲染内容，只有遮罩区域内（或反向遮罩时区域外）的内容会被显示。	-	必填
type	遮罩类型	数据	number	遮罩类型 GRAPHICS_RECT（=0）：矩形遮罩 GRAPHICS_ELLIPSE（=1）：椭圆遮罩 GRAPHICS_STENCIL（=2）：自定义图形模板 SPRITE_STENCIL（=3）：图片模板 默认不公开；公开后才参与写入。	下拉选择 默认值：0	可选 默认隐藏
inverted	反向遮罩	数据	boolean	反向遮罩 true=显示遮罩区域外部内容 false=显示遮罩区域内部内容 默认不公开；公开后才参与写入。	开关 默认值：false	可选 默认隐藏
segments	细分数	数据	number	椭圆细分数 仅在 type = GRAPHICS_ELLIPSE 时有效。 默认不公开；公开后才参与写入。	输入框 默认值：64	可选 默认隐藏
alphaThreshold	Alpha 阈值	数据	number	Alpha 阈值 仅在 type = SPRITE_STENCIL 时有效。 取值范围 [0, 1]。 默认不公开；公开后才参与写入。	输入框 默认值：0.1	可选 默认隐藏

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
mask	Mask 组件	数据	cc.Component / Mask	目标 Mask 组件 透传当前操作的 Mask 组件，便于链式修改遮罩配置。	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

设置椭圆细分数

设置椭圆细分数：设置 Mask 组件椭圆遮罩的细分段数。 默认值：64。 注意：该属性仅在 type = GRAPHICS_ELLIPSE（椭圆遮罩）时有效。更高的细分数会让椭圆边缘更平滑，但也会增加路径点数量。输入值会被限制到 [3, 10000] 范围内。

节点信息

字段	值
节点 ID	maskSetSegments
分类	Cocos 组件
二级分类	2D
分组	Mask
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
mask	Mask 组件	数据	cc.Component / Mask	目标 Mask 组件 要操作的 Mask 组件。 Mask 组件会裁剪当前节点整棵子树的渲染内容，只有遮罩区域内（或反向遮罩时区域外）的内容会被显示。	-	必填
segments	细分数	数据	number	椭圆细分数 椭圆遮罩的细分段数，仅在 type = GRAPHICS_ELLIPSE 时有效。 值越大椭圆越平滑，限制范围 [3, 10000]。	输入框 默认值：64	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
mask	Mask 组件	数据	cc.Component / Mask	目标 Mask 组件 透传当前操作的 Mask 组件，便于链式修改遮罩配置。	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

设置遮罩类型

设置遮罩类型：设置 Mask 组件的遮罩类型。 类型枚举：

• 0 GRAPHICS_RECT：矩形遮罩
• 1 GRAPHICS_ELLIPSE：椭圆遮罩
• 2 GRAPHICS_STENCIL：自定义图形模板
• 3 SPRITE_STENCIL：图片模板 注意：本节点只切换遮罩模式，不负责配置模板内容。

节点信息

字段	值
节点 ID	maskSetType
分类	Cocos 组件
二级分类	2D
分组	Mask
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
exe	-	执行流	执行流	执行入口	-	可选
mask	Mask 组件	数据	cc.Component / Mask	目标 Mask 组件 要操作的 Mask 组件。 Mask 组件会裁剪当前节点整棵子树的渲染内容，只有遮罩区域内（或反向遮罩时区域外）的内容会被显示。	-	必填
type	遮罩类型	数据	number	遮罩类型 GRAPHICS_RECT（=0）：矩形遮罩 GRAPHICS_ELLIPSE（=1）：椭圆遮罩 GRAPHICS_STENCIL（=2）：自定义图形模板，需配合 Graphics 组件 SPRITE_STENCIL（=3）：图片模板，需配合 Sprite 组件	下拉选择 默认值：0	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
out	-	执行流	执行流	执行完成	-	可选
mask	Mask 组件	数据	cc.Component / Mask	目标 Mask 组件 透传当前操作的 Mask 组件，便于链式修改遮罩配置。	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。

---

遮罩命中判断

遮罩命中判断：判断指定的世界坐标点是否命中 Mask 遮罩区域。 输入坐标：worldPt 是世界坐标，不是节点局部坐标。 命中语义：

• GRAPHICS_RECT、GRAPHICS_STENCIL、SPRITE_STENCIL：均按节点 UI 矩形边界判定命中
• GRAPHICS_ELLIPSE：按椭圆数学区域判定命中 注意：当 inverted = true 时，最终命中结果会被翻转。GRAPHICS_STENCIL 并不会按自定义图形像素做复杂命中判定，而是按节点矩形范围处理。

节点信息

字段	值
节点 ID	maskIsHit
分类	Cocos 组件
二级分类	2D
分组	Mask
是否需要等待结果	否
是否需要先选择目标	否

输入引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
mask	Mask 组件	数据	cc.Component / Mask	目标 Mask 组件 要操作的 Mask 组件。 Mask 组件会裁剪当前节点整棵子树的渲染内容，只有遮罩区域内（或反向遮罩时区域外）的内容会被显示。	-	必填
worldPt	世界坐标	数据	vector2	世界坐标 要判断的目标点，使用世界坐标系（不是节点局部坐标）。	可编辑控件 默认值：[0,0]	必填

输出引脚

引脚 ID	名称	连接方式	值类型	用途	默认或选择	连接要求
hit	命中	数据	boolean	命中结果 true=世界坐标点在遮罩区域内 false=世界坐标点在遮罩区域外 当 inverted = true 时结果会翻转。	-	可选

使用场景

• 控制 UI、音频、动画、物理、灯光、粒子和渲染组件
• 读取组件状态后驱动游戏逻辑
• 批量设置组件属性完成游戏运行时效果

注意事项

• 适合的工作流类型：component、library、method、function、class。
• 目标组件引脚必须连接正确的组件实例。
• 设置类节点通常需要接入执行流，才会真正修改游戏运行时状态。