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

CollisionPolygon3D

节点继承关系

继承链：Node → Node3D → CollisionObject3D → CollisionPolygon3D

CollisionObject3D

类型	名称	说明
属性	CollisionLayer	碰撞层——自身所在层
属性	CollisionMask	碰撞掩码——检测哪些层
属性	InputRayPickable	是否可被射线拾取
信号	input_event	碰撞体上接收到输入事件
信号	mouse_entered	鼠标进入碰撞区域
信号	mouse_exited	鼠标离开碰撞区域
方法	GetRid()	获取物理引擎资源 ID

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 碰撞区域。

CollisionPolygon3D 是 CollisionPolygon2D 的 3D 版本。区别在于：2D 版本画的是平面多边形，3D 版本画的是平面多边形然后沿法线方向"挤出"成一定厚度的 3D 体积。

使用频率：★★★ 一般常用——用于 3D 不规则碰撞形状。

节点用途

• 3D 不规则地形碰撞
• 3D 自定义碰撞轮廓

使用场景

典型场景

• 3D 地形碰撞：精确匹配地形的不规则轮廓
• 3D 斜坡：定义斜坡的碰撞面

不适用场景

• 简单的方盒/球形碰撞 → 使用 CollisionShape3D 更高效

常用节点搭配

搭配节点	用途	必需？
StaticBody3D / Area3D 等	父节点	必需有一个

典型节点树：

Terrain (StaticBody3D)
└── CollisionPolygon3D

生效必备素材/资源

无需外部资源，直接在编辑器中画点即可。

节点属性与信号

核心属性

属性	类型	默认值	继承自	说明
Polygon	PackedVector3Array	[]	—	多边形顶点数组
Depth	float	1.0	—	多边形挤出的深度（厚度）
Disabled	bool	false	—	是否禁用
DebugColor	Color	Color(0, 0, 0.6, 0.4)	—	编辑器中的调试显示颜色

信号

信号	触发时机	继承自	说明
无自有信号	—	—	—

常用方法

方法	返回值	说明
GetPolygon()	PackedVector3Array	获取多边形顶点数组
SetPolygon(polygon)	void	设置多边形顶点数组

代码示例

C

using Godot;

/// <summary>
/// 用代码创建 3D 多边形碰撞（一个斜坡）
/// </summary>
public partial class Ramp3D : StaticBody3D
{
    public override void _Ready()
    {
        var collisionPolygon = new CollisionPolygon3D();

        // 定义斜坡的三角形截面
        collisionPolygon.Polygon = new Vector3[]
        {
            new Vector3(0f, 0f, 0f),
            new Vector3(5f, 0f, 0f),
            new Vector3(5f, 3f, 0f),
        };

        // 挤出深度（沿 Z 轴）
        collisionPolygon.Depth = 3.0f;

        AddChild(collisionPolygon);
    }
}

GDScript

# 用代码创建 3D 多边形碰撞（一个斜坡）
extends StaticBody3D

func _ready() -> void:
	var collision_polygon := CollisionPolygon3D.new()

	# 定义斜坡的三角形截面
	collision_polygon.polygon = PackedVector3Array([
		Vector3(0.0, 0.0, 0.0),
		Vector3(5.0, 0.0, 0.0),
		Vector3(5.0, 3.0, 0.0),
	])

	# 挤出深度（沿 Z 轴）
	collision_polygon.depth = 3.0

	add_child(collision_polygon)

3D 碰撞更推荐用 CollisionShape3D

对于 3D 游戏，大多数情况下使用 CollisionShape3D + 预设形状（Box、Capsule、Sphere）或 ConcavePolygonShape3D（从模型生成）会更好。CollisionPolygon3D 主要用于编辑器中快速手绘简单碰撞。