【包教包会】Shader实战——挖洞（Demo演示战斗迷雾、放大镜、新手引导、转场动画）

27185709 · 2025年10月28日 14:36

演示demo：https://gitee.com/szrpf/HoleMask

一、效果演示：

以上所有特效，都是通过挖洞组件HoleMask.ts实现的。

二、功能介绍

首先打开Demo，找到"聚光灯Demo/黑幕"节点的HoleMask组件

类型：决定了挖洞轮廓形状，可以选矩形、椭圆、纹理图采样（类似Mask）
中心：洞的位置
尺寸：洞的宽高
羽化：给挖洞轮廓添加平滑过渡
反向：反向挖洞，即洞里可见，洞外透明
勾选反向后，可以设置洞内像素缩放（放大镜效果）

可通过代码动态修改以上属性，或者调用方法，具体参考Demo
HoleMask无需import，通过gi.HoleMask全局访问，具体参考Demo

三、如何在自己的项目中使用HoleMask

Step 1：复制Demo中这3个文件到自己项目assets目录下，具体层级不限

Step 2：新建一个Sprite节点，HoleMask.mtl拖自定义材质，HoleMask.ts拖组件

Step 3：搞定！编辑器修改挖洞参数，也可以在代码中动态修改

四、实现原理
1、挖椭圆

虽然上图看着是个圆，但需求是能实现任意尺寸，也就是椭圆
计算归一化的椭圆距离：length((flipUv * texSize - center) / halfSize)

当点在椭圆上时，length = 1.0
当点在椭圆内时，length < 1.0
当点在椭圆外时，length > 1.0
边缘距离 ： 1.0 - length(...) 计算到椭圆边缘的距离
椭圆特性 ：使用向量长度自然形成椭圆形状，通过halfSize的x,y比例控制椭圆扁率
效果：创建一个可羽化的椭圆挖洞区域

2、挖矩形

vec2 coord = 1.0 - abs(flipUv * texSize - center) / halfSize;
alpha = min(smoothstep(-fx, fx, coord.x), smoothstep(-fy, fy, coord.y));

坐标转换 ： flipUv * texSize - center 将UV坐标转换到以挖洞中心为原点的像素坐标系
归一化 ： abs(...) / halfSize 计算相对于矩形半宽的归一化坐标，范围[0,1]
边缘距离 ： 1.0 - coord 计算到矩形边缘的距离，越靠近中心值越大
羽化处理 ： smoothstep(-fx, fx, coord.x) 在边缘附近创建平滑过渡
取最小值 ： min(alpha.x, alpha.y) 确保矩形四个边都正确挖洞

效果：创建一个可羽化的矩形挖洞区域

3、挖图片轮廓

vec2 contourUV = (flipUv * texSize - center + halfSize) / size;
contourUV.y = 1.0 - contourUV.y;
alpha = step(ALPHA_THRESHOLD, getColor(contourTexture, contourUV).a);