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

ShapeCast3D

节点继承关系

继承链：Node → Node3D → ShapeCast3D

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 空间中把一个形状沿着一条路径投射出去，检测沿途碰到了什么。

ShapeCast3D 是 ShapeCast2D 的 3D 版本，原理完全相同。3D 版本使用 Vector3 和 3D 形状资源。

使用频率：★★ 偶尔使用——在 3D 中需要"粗射线"检测时使用。

节点用途

• 3D 通道宽度检测
• 3D 碰撞预判
• 3D 汽车前方障碍物检测

使用场景

典型场景

• 3D 通道检测：3D 角色能不能通过一扇窄门
• 3D 汽车碰撞预判：汽车前方有没有障碍物

不适用场景

• 只需一条细线检测 → 使用 RayCast3D

常用节点搭配

搭配节点	用途	必需？
Node3D（作为父节点）	位置锚点	推荐

典型节点树：

Car (RigidBody3D)
└── ObstacleDetector (ShapeCast3D)  ← 检测前方障碍物

生效必备素材/资源

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

节点属性与信号

核心属性

属性	类型	默认值	继承自	说明
Enabled	bool	false	—	是否启用
Shape	Shape3D	null	—	投射的形状
TargetPosition	Vector3	(0, 0, -50)	—	投射目标位置
CollideWithBodies	bool	true	—	是否检测物理体
CollideWithAreas	bool	false	—	是否检测 Area
MaxResults	int	32	—	最大检测结果数
CollisionMask	uint	1	—	碰撞层掩码
ExcludeParent	bool	true	—	是否排除父节点

信号

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

常用方法

方法	返回值	说明
IsColliding()	bool	是否碰到了东西
GetCollisionCount()	int	碰到了多少个物体
GetCollider(index)	Object	获取指定索引的碰撞体
GetCollisionPoint(index)	Vector3	获取指定索引的碰撞点
GetCollisionNormal(index)	Vector3	获取指定索引的碰撞法线
ForceShapecastUpdate()	void	强制立即更新检测结果

代码示例

C

using Godot;

/// <summary>
/// 3D 通道宽度检测
/// 节点结构：Doorway (Node3D) + ShapeCast3D
/// </summary>
public partial class PassageDetector3D : Node3D
{
    private ShapeCast3D _shapeCast;

    public override void _Ready()
    {
        _shapeCast = GetNode<ShapeCast3D>("ShapeCast3D");
        _shapeCast.Enabled = true;

        // 使用和角色一样的碰撞形状
        var shape = new CapsuleShape3D();
        shape.Radius = 0.4f;
        shape.Height = 1.8f;
        _shapeCast.Shape = shape;

        // 向前投射
        _shapeCast.TargetPosition = new Vector3(0f, 0f, -3f);
    }

    public bool IsPassageClear()
    {
        _shapeCast.ForceShapecastUpdate();
        return !_shapeCast.IsColliding();
    }
}

GDScript

# 3D 通道宽度检测
# 节点结构：Doorway (Node3D) + ShapeCast3D
extends Node3D

@onready var shape_cast: ShapeCast3D = $ShapeCast3D

func _ready() -> void:
	shape_cast.enabled = true

	# 使用和角色一样的碰撞形状
	var shape := CapsuleShape3D.new()
	shape.radius = 0.4
	shape.height = 1.8
	shape_cast.shape = shape

	# 向前投射
	shape_cast.target_position = Vector3(0.0, 0.0, -3.0)

func is_passage_clear() -> bool:
	shape_cast.force_shapecast_update()
	return not shape_cast.is_colliding()