最后同步日期：2026-04-15 | Godot 官方原文 — Decal

Decal

节点继承关系

继承链：Node → Node3D → VisualInstance3D → Decal

VisualInstance3D

类型	名称	说明
属性	Layers	渲染层（可视层掩码）
属性	SortingOffset	排序偏移

Node3D

类型	名称	说明
属性	Position	本地位置（X / Y / Z）
属性	GlobalPosition	全局位置
属性	Rotation	旋转角度（欧拉角，弧度）
属性	Scale	缩放比例
属性	TopLevel	是否脱离父节点的变换
方法	LookAt()	朝向目标点
方法	ToGlobal()	本地坐标转全局坐标
方法	ToLocal()	全局坐标转本地坐标
方法	RotateX/Y/Z()	绕指定轴旋转

Node

类型	名称	说明
属性	Name	节点名称
属性	ProcessMode	处理模式（始终 / 暂停时 / 仅编辑器）
属性	ProcessPriority	处理优先级，数字越小越先执行
信号	ready	节点进入场景树并准备就绪
信号	tree_entered	节点进入场景树
信号	tree_exited	节点完全离开场景树
方法	GetNode<T>()	按路径获取子节点
方法	AddChild()	添加子节点
方法	RemoveChild()	移除子节点
方法	QueueFree()	帧结束后释放节点
方法	GetParent()	获取父节点

定义

贴花节点——把一张图片"贴"到 3D 物体的表面上。就像在墙上贴一张海报，或者在地上画一条裂缝线。Decal 会自动适应物体表面的形状，不管物体表面是平面还是曲面。

打个比方：Decal 就像现实中的贴纸。你把一张贴纸按在墙上，它就紧贴着墙面。如果墙面是弯曲的，贴纸也会跟着弯曲。在游戏里，你可以用 Decal 在地面上画裂缝、在墙上贴涂鸦、在雪地上留脚印。

使用频率：★★ 偶尔使用——需要在物体表面添加细节纹理时使用。

节点用途

• 在地面添加裂缝纹理
• 在墙上添加涂鸦、海报、血迹
• 在雪地/泥地上留下脚印、轮胎痕迹
• 添加弹孔、焦痕等战斗痕迹
• 给物体添加警告标志

使用场景

典型场景

• 射击游戏：子弹击中墙壁留下弹孔
• 恐怖游戏：墙上出现血迹或诡异符号
• 赛车游戏：地面留下刹车痕迹
• 环境装饰：墙上贴海报、地面有水渍

不适用场景

• 需要永久性的纹理 → 直接在模型贴图中绘制
• 2D 游戏 → 不支持

常用节点搭配

搭配节点	用途	必需？
Texture2D 贴图	贴花内容	必需
MeshInstance3D	被贴花的物体	需要

典型节点树：

Room (Node3D)
├── Wall (MeshInstance3D)  ← 被贴花的墙面
├── BulletHole (Decal)     ← 弹孔贴花
└── BloodSplatter (Decal)  ← 血迹贴花

生效必备素材/资源

资源	类型	说明
贴花纹理	Texture2D	赋给 texture_albedo 属性，贴花显示的图片
法线贴图	Texture2D	赋给 texture_normal 属性，给贴花添加凹凸感
透明遮罩	Texture2D	赋给 modulate 或通过材质 alpha 控制，决定贴花哪些部分透明

节点属性与信号

贴花设置

属性	类型	默认值	继承自	说明
texture_albedo	Texture2D	—	—	贴花的基本颜色贴图
texture_normal	Texture2D	—	—	法线贴图，让贴花有凹凸感
texture_emission	Texture2D	—	—	自发光贴图，让贴花部分发光
albedo_mix	float	1.0	—	贴花颜色与物体原色的混合程度
normal_fade	float	0.5	—	法线淡出。当表面法线与贴花方向差异过大时淡出
upper_fade	float	0.3	—	上边缘淡出距离
lower_fade	float	0.3	—	下边缘淡出距离
cull_mask	int	0x7FFFFFFF	—	决定贴花只影响哪些碰撞层上的物体

信号

信号	触发时机	继承自	说明
无自有信号	—	—	Decal 自身不发出信号

常用方法

方法	返回值	说明
GetTextureAlbedo()	Texture2D	获取颜色贴图
SetTextureAlbedo(tex)	void	设置颜色贴图

代码示例

C

using Godot;

/// <summary>
/// 弹孔生成器
/// 射击时在命中点生成贴花
/// </summary>
public partial class BulletHoleSpawner : Node3D
{
    [Export] private PackedScene _bulletHoleScene;
    [Export] public float ExSpread = 0.1f;

    public void SpawnBulletHole(Vector3 position, Vector3 normal)
    {
        var decal = _bulletHoleScene.Instantiate<Decal>();

        // 设置贴花位置
        decal.Position = position + normal * 0.01f; // 稍微偏移避免穿模

        // 让贴花朝向碰撞面的法线方向
        decal.LookAt(position + normal, Vector3.Up);

        // 添加一点随机旋转
        decal.RotateY((float)GD.RandRange(-Mathf.Pi, Mathf.Pi));

        GetParent().AddChild(decal);
    }
}

GDScript

## 弹孔生成器
## 射击时在命中点生成贴花
extends Node3D

@export var bullet_hole_scene: PackedScene
@export var spread: float = 0.1

func spawn_bullet_hole(position: Vector3, normal: Vector3):
    var decal := bullet_hole_scene.instantiate() as Decal

    # 设置贴花位置
    decal.position = position + normal * 0.01  # 稍微偏移避免穿模

    # 让贴花朝向碰撞面的法线方向
    decal.look_at(position + normal, Vector3.UP)

    # 添加一点随机旋转
    decal.rotate_y(randf_range(-PI, PI))

    get_parent().add_child(decal)

使用建议

• Decal 会自动投影到附近的物体表面上，不需要精确对齐
• 使用 cull_mask 可以让贴花只出现在特定的物体上
• normal_fade 可以防止贴花出现在过于陡峭的表面上
• 大量 Decal 会影响性能，建议设置合理的 upper_fade 和 lower_fade 让远处/近处的贴花自然消失