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

CollisionShape2D

节点继承关系

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

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 物理体画一个"碰撞轮廓"——没有它，物理引擎不知道你的物体长什么样，其他东西会穿过去。

想象你在玩碰碰车——碰碰车的外壳就是它的"碰撞形状"。Godot 里，每个物理体节点本身只是一个"标记"，需要一个 CollisionShape2D 子节点来告诉物理引擎"这个物体的碰撞边界在哪里、是什么形状"。

必须作为物理体或 Area 的子节点使用，否则无效。

使用频率：★★★★ 维度专用常用——每次使用物理节点时都必须搭配它。

节点用途

• 定义角色、物体、区域的碰撞边界
• 选择合适的碰撞形状（矩形、圆形、胶囊等）

使用场景

典型场景

• 角色碰撞：给 CharacterBody2D 添加胶囊碰撞形状
• 墙壁碰撞：给 StaticBody2D 添加矩形碰撞形状
• 拾取范围：给 Area2D 添加圆形碰撞形状

不适用场景

• 需要手动画不规则碰撞区域 → 使用 CollisionPolygon2D

常用节点搭配

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

典型节点树：

Player (CharacterBody2D)
└── CollisionShape2D ← 赋予碰撞形状
    └── (Shape 资源：CapsuleShape2D)

生效必备素材/资源

资源	类型	说明
碰撞形状资源	Shape2D 资源	赋给 Shape 属性，定义碰撞轮廓

支持的 2D 形状

形状	类名	说明	适合场景
矩形	RectangleShape2D	一个长方形	箱子、平台、墙壁
圆形	CircleShape2D	一个圆	球、简单角色、拾取范围
胶囊	CapsuleShape2D	两头圆的胶囊	人形角色
线段	SegmentShape2D	一条线段	简单边界
分离射线	SeparationRayShape2D	用于防止穿模的射线	快速移动的物体
凸多边形	ConvexPolygonShape2D	凸多边形	简单不规则形状
凹多边形	ConcavePolygonShape2D	凹多边形	仅用于 StaticBody，复杂地形
世界边界	WorldBoundaryShape2D	无限长的直线	游戏世界底部边界

节点属性与信号

核心属性

属性	类型	默认值	继承自	说明
Shape	Shape2D	null	—	碰撞形状资源
Disabled	bool	false	—	是否禁用此碰撞形状
DebugColor	Color	Color(0, 0, 0.6, 0.4)	—	编辑器中的调试显示颜色

信号

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

常用方法

方法	返回值	说明
SetDisabled(disabled)	void	设置是否禁用
GetShape()	Shape2D	获取碰撞形状资源
SetShape(shape)	void	设置碰撞形状资源

代码示例

C

using Godot;

/// <summary>
/// 动态创建碰撞形状的示例
/// </summary>
public partial class DynamicCollision : CharacterBody2D
{
    public override void _Ready()
    {
        // 创建碰撞形状节点
        var collisionShape = new CollisionShape2D();

        // 创建一个胶囊形状
        var shape = new CapsuleShape2D();
        shape.Radius = 16.0f;    // 半径
        shape.Height = 32.0f;    // 高度

        // 把形状赋给碰撞节点
        collisionShape.Shape = shape;

        // 添加为当前节点的子节点
        AddChild(collisionShape);
    }
}

/// <summary>
/// 运行时切换碰撞形状（如蹲下时变矮）
/// </summary>
public partial class PlayerWithCrouch : CharacterBody2D
{
    private CollisionShape2D _collisionShape;
    private CapsuleShape2D _standingShape;  // 站立时的碰撞形状
    private CapsuleShape2D _crouchingShape; // 蹲下时的碰撞形状

    public override void _Ready()
    {
        _collisionShape = GetNode<CollisionShape2D>("CollisionShape2D");

        // 创建站立碰撞形状
        _standingShape = new CapsuleShape2D { Radius = 16f, Height = 48f };
        // 创建蹲下碰撞形状
        _crouchingShape = new CapsuleShape2D { Radius = 16f, Height = 24f };

        _collisionShape.Shape = _standingShape;
    }

    public void Crouch()
    {
        _collisionShape.Shape = _crouchingShape;
    }

    public void StandUp()
    {
        _collisionShape.Shape = _standingShape;
    }
}

GDScript

# 动态创建碰撞形状的示例
extends CharacterBody2D

func _ready() -> void:
	# 创建碰撞形状节点
	var collision_shape := CollisionShape2D.new()

	# 创建一个胶囊形状
	var shape := CapsuleShape2D.new()
	shape.radius = 16.0    # 半径
	shape.height = 32.0    # 高度

	# 把形状赋给碰撞节点
	collision_shape.shape = shape

	# 添加为当前节点的子节点
	add_child(collision_shape)

选择碰撞形状的建议

• 角色：用胶囊（Capsule）——上圆下方，不容易卡角
• 方形物体：用矩形（Rectangle）——简单高效
• 球/弹丸：用圆形（Circle）——最精确
• 复杂地形：用凹多边形（ConcavePolygon）——但只能用在 StaticBody 上
• 一般原则：碰撞形状越简单越好！复杂的形状会严重影响游戏性能