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

CollisionShape3D

节点继承关系

继承链：Node → Node3D → CollisionObject3D → CollisionShape3D

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 物理体画一个"碰撞轮廓"——没有它，物理引擎不知道你的 3D 物体长什么样。

CollisionShape3D 是 CollisionShape2D 的 3D 版本，原理完全相同。3D 版本支持更多的形状类型，包括凹多面体。

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

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

节点用途

• 定义 3D 角色、物体、区域的碰撞边界
• 选择合适的 3D 碰撞形状

使用场景

典型场景

• 角色碰撞：给 CharacterBody3D 添加胶囊碰撞形状
• 墙壁碰撞：给 StaticBody3D 添加方盒碰撞形状
• 拾取范围：给 Area3D 添加球形碰撞形状

不适用场景

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

常用节点搭配

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

典型节点树：

Player (CharacterBody3D)
└── CollisionShape3D ← 赋予碰撞形状
    └── (Shape 资源：CapsuleShape3D)

生效必备素材/资源

资源	类型	说明
碰撞形状资源	Shape3D 资源	赋给 Shape 属性

支持的 3D 形状

形状	类名	说明	适合场景
方盒	BoxShape3D	一个长方体	箱子、平台、墙壁
球体	SphereShape3D	一个球	球、简单物体
胶囊	CapsuleShape3D	两头圆的胶囊	人形角色
圆柱	CylinderShape3D	一个圆柱	柱子、树干
分离射线	SeparationRayShape3D	用于防止穿模的射线	快速移动的物体
凸多面体	ConvexPolygonShape3D	凸多面体	简单不规则物体
凹多面体	ConcavePolygonShape3D	凹多面体	仅用于 StaticBody，复杂地形
世界边界	WorldBoundaryShape3D	无限大的平面	游戏世界底部边界

节点属性与信号

核心属性

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

信号

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

常用方法

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

代码示例

C

using Godot;

/// <summary>
/// 动态创建 3D 碰撞形状
/// </summary>
public partial class DynamicCollision3D : CharacterBody3D
{
    public override void _Ready()
    {
        // 创建碰撞形状节点
        var collisionShape = new CollisionShape3D();

        // 创建一个胶囊形状
        var shape = new CapsuleShape3D();
        shape.Radius = 0.5f;    // 半径（米）
        shape.Height = 1.8f;    // 高度（米）

        collisionShape.Shape = shape;
        AddChild(collisionShape);
    }
}

/// <summary>
/// 从 3D 模型的网格自动生成碰撞形状（适用于 StaticBody3D）
/// </summary>
public partial class AutoCollider : StaticBody3D
{
    [Export] private MeshInstance3D _meshInstance;

    public override void _Ready()
    {
        if (_meshInstance != null && _meshInstance.Mesh != null)
        {
            // 创建凹多面体碰撞形状（从模型网格生成）
            var shape = _meshInstance.Mesh.CreateTrimeshShape();
            var collisionShape = new CollisionShape3D();
            collisionShape.Shape = shape;
            AddChild(collisionShape);
        }
    }
}

GDScript

# 动态创建 3D 碰撞形状
extends CharacterBody3D

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

	# 创建一个胶囊形状
	var shape := CapsuleShape3D.new()
	shape.radius = 0.5    # 半径（米）
	shape.height = 1.8    # 高度（米）

	collision_shape.shape = shape
	add_child(collision_shape)

从 3D 模型自动生成碰撞形状

StaticBody3D 支持使用 ConcavePolygonShape3D，可以通过模型的 Mesh 自动生成碰撞形状。在编辑器中，选中 MeshInstance3D 节点，在菜单中选择 Mesh → Create Multiple Convex Collision Siblings 或 Create Single Convex Collision Sibling 即可。