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

CollisionPolygon2D

节点继承关系

继承链：Node → CanvasItem → Node2D → CollisionObject2D → CollisionPolygon2D

CollisionObject2D

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

Node2D

类型	名称	说明
属性	Position	本地位置（相对于父节点）
属性	GlobalPosition	全局位置
属性	Rotation	旋转角度（弧度）
属性	Scale	缩放比例
属性	Skew	倾斜角度（弧度）
方法	Rotate()	旋转指定弧度
方法	ToGlobal()	本地坐标转全局坐标
方法	ToLocal()	全局坐标转本地坐标

CanvasItem

类型	名称	说明
属性	Visible	是否可见
属性	Modulate	整体颜色叠加（乘法）
属性	SelfModulate	自身颜色叠加（不影响子节点）
属性	ZIndex	绘制层级（Z 轴排序）
信号	visibility_changed	可见性变化时触发
方法	GetGlobalMousePosition()	获取鼠标全局坐标

Node

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

定义

用你手动画的点连成一个多边形，作为 2D 碰撞区域——适合不规则的复杂形状。

CollisionShape2D 提供的是规则形状（圆、矩形、胶囊等），但有时候你的物体形状很不规则——比如一个月牙形的平台、一个 L 形的走廊。这时候就可以用 CollisionPolygon2D：你在编辑器里一个点一个点地点，画出精确的碰撞轮廓。

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

节点用途

• 不规则地形（山坡、洞穴）
• L 形、T 形等复杂平台
• 自定义碰撞轮廓

使用场景

典型场景

• 地形碰撞：精确匹配地形的不规则轮廓
• L 形平台：规则形状无法精确表示
• 月牙形区域：弧形的不规则区域

不适用场景

• 简单的矩形/圆形碰撞 → 使用 CollisionShape2D 更高效

常用节点搭配

搭配节点	用途	必需？
StaticBody2D / Area2D / CharacterBody2D 等	父节点	必需有一个

典型节点树：

IrregularPlatform (StaticBody2D)
└── CollisionPolygon2D ← 手动画点定义形状

生效必备素材/资源

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

节点属性与信号

核心属性

属性	类型	默认值	继承自	说明
Polygon	Vector2[]	[]	—	多边形顶点数组
Disabled	bool	false	—	是否禁用
BuildMode	枚举	Solid	—	Solid（实心多边形）/ Segments（线段）
DebugColor	Color	Color(0, 0, 0.6, 0.4)	—	编辑器中的调试显示颜色

信号

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

常用方法

方法	返回值	说明
GetPolygon()	Vector2[]	获取多边形顶点数组
SetPolygon(polygon)	void	设置多边形顶点数组
SetDisabled(disabled)	void	设置是否禁用

代码示例

C

using Godot;

/// <summary>
/// 用代码创建多边形碰撞区域
/// 这里创建一个三角形的碰撞
/// </summary>
public partial class TrianglePlatform : StaticBody2D
{
    public override void _Ready()
    {
        var collisionPolygon = new CollisionPolygon2D();

        // 定义三角形的三个顶点
        collisionPolygon.Polygon = new Vector2[]
        {
            new Vector2(0f, -50f),      // 顶部
            new Vector2(-60f, 30f),     // 左下
            new Vector2(60f, 30f),      // 右下
        };

        AddChild(collisionPolygon);
    }
}

/// <summary>
/// 用代码创建 L 形平台
/// </summary>
public partial class LShapePlatform : StaticBody2D
{
    public override void _Ready()
    {
        var collisionPolygon = new CollisionPolygon2D();

        // 定义 L 形的顶点（逆时针或顺时针都可以）
        collisionPolygon.Polygon = new Vector2[]
        {
            new Vector2(0f, 0f),
            new Vector2(60f, 0f),
            new Vector2(60f, 30f),
            new Vector2(30f, 30f),
            new Vector2(30f, 60f),
            new Vector2(0f, 60f),
        };

        AddChild(collisionPolygon);
    }
}

GDScript

# 用代码创建多边形碰撞区域
# 这里创建一个三角形的碰撞
extends StaticBody2D

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

	# 定义三角形的三个顶点
	collision_polygon.polygon = PackedVector2Array([
		Vector2(0.0, -50.0),     # 顶部
		Vector2(-60.0, 30.0),    # 左下
		Vector2(60.0, 30.0),     # 右下
	])

	add_child(collision_polygon)

CollisionPolygon vs CollisionShape

对比项	CollisionShape	CollisionPolygon
形状	选择预设形状（圆、矩形等）	手动画点，自定义多边形
适合	简单规则形状	复杂不规则形状
性能	更好	稍差（顶点多时）
操作	选形状 + 调参数	在编辑器中点击画点