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

Area3D

节点继承关系

继承链：Node → Node3D → Area3D

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 空间中看不见的"感应区"——它不会挡住任何东西，但能检测到有东西进来了、出去了。

Area3D 是 Area2D 的 3D 版本，原理完全相同。3D 版本额外支持重力点覆盖功能，可以模拟黑洞、反重力区域等效果。

使用频率：★★★★ 维度专用常用——3D 游戏中非常常用。

节点用途

• 3D 拾取物品（武器、道具）
• 3D 触发区域（触发剧情、过场动画）
• 3D 伤害区域（岩浆、毒气、爆炸范围）
• 3D 检测区域（敌人感知范围）
• 重力区域（反重力区、黑洞效果）

使用场景

典型场景

• 武器拾取：玩家走到武器旁边自动拾取
• 3D 伤害区域：玩家走进岩浆区域持续扣血
• 重力区域：走进某个区域重力反转（3D 独有优势）

不适用场景

• 需要阻挡其他物体 → 使用 StaticBody3D
• 需要自己控制移动的角色 → 使用 CharacterBody3D

常用节点搭配

搭配节点	用途	必需？
CollisionShape3D	定义感应区域的范围	必需
MeshInstance3D	显示区域的可视效果	可选
CSGShape3D	调试用可视化	可选

典型节点树：

PickupItem (Area3D)
├── CollisionShape3D
└── MeshInstance3D

生效必备素材/资源

资源	类型	说明
碰撞形状（如 SphereShape3D）	Shape3D 资源	赋给 CollisionShape3D 子节点

节点属性与信号

监测属性

属性	类型	默认值	继承自	说明
Monitoring	bool	true	—	是否监测其他物体进入/离开
Monitorable	bool	true	—	是否能被其他 Area 监测到
Priority	int	0	—	处理优先级

重力覆盖（3D 独有增强）

属性	类型	默认值	继承自	说明
GravitySpaceOverride	枚举	Disabled	—	重力覆盖模式
GravityDirection	Vector3	(0, -1, 0)	—	自定义重力方向
Gravity	float	9.8	—	自定义重力强度
GravityPoint	bool	false	—	重力是否指向某个点
GravityPointCenter	Vector3	(0, 0, 0)	—	重力中心点坐标
GravityPointUnitDistance	float	0.0	—	重力点衰减距离

碰撞层

属性	类型	默认值	继承自	说明
CollisionLayer	uint	1	CollisionObject3D	所在碰撞层
CollisionMask	uint	1	CollisionObject3D	检测哪些碰撞层

信号

信号	触发时机	继承自	说明
body_entered(body)	有物理体进入区域	Area3D	最常用的信号
body_exited(body)	有物理体离开区域	Area3D	—
area_entered(area)	有其他 Area 进入此区域	Area3D	—
area_exited(area)	有其他 Area 离开此区域	Area3D	—

常用方法

方法	返回值	说明
GetOverlappingBodies()	GodotArray[Node3D]	获取当前区域内所有物理体
GetOverlappingAreas()	GodotArray[Area3D]	获取当前区域内所有 Area
HasOverlappingBodies()	bool	区域内是否有物理体
HasOverlappingAreas()	bool	区域内是否有 Area
OverlapsBody(body)	bool	指定物理体是否在区域内
OverlapsArea(area)	bool	指定 Area 是否在区域内

代码示例

C

using Godot;

/// <summary>
/// 3D 武器拾取区
/// 节点结构：WeaponPickup (Area3D) + CollisionShape3D + MeshInstance3D
/// </summary>
public partial class WeaponPickup : Area3D
{
    [Export] public string ExWeaponName = "Pistol";

    public override void _Ready()
    {
        BodyEntered += OnBodyEntered;
    }

    private void OnBodyEntered(Node3D body)
    {
        if (body is CharacterBody3D player)
        {
            GD.Print($"玩家拾取了武器：{ExWeaponName}");
            // 调用玩家的拾取方法
            player.Call("PickupWeapon", ExWeaponName);
            QueueFree();
        }
    }
}

/// <summary>
/// 3D 反重力区域：走进去重力方向反转
/// 节点结构：AntiGravityZone (Area3D) + CollisionShape3D
/// </summary>
public partial class AntiGravityZone : Area3D
{
    public override void _Ready()
    {
        // 设置重力覆盖
        GravitySpaceOverride = AreaSpaceOverride.Replace;
        Gravity = -9.8f;  // 反向重力
        GravityDirection = Vector3.Up;
    }
}

GDScript

# 3D 武器拾取区
# 节点结构：WeaponPickup (Area3D) + CollisionShape3D + MeshInstance3D
extends Area3D

@export var weapon_name: String = "Pistol"

func _ready() -> void:
	body_entered.connect(_on_body_entered)

func _on_body_entered(body: Node3D) -> void:
	if body is CharacterBody3D:
		print("玩家拾取了武器：%s" % weapon_name)
		# 调用玩家的拾取方法
		body.call("pickup_weapon", weapon_name)
		queue_free()

3D Area 的重力覆盖功能很强大

Area3D 可以覆盖区域内的重力设置，实现：

• 反重力区：Gravity = -9.8，走进去角色会"往上掉"
• 低重力区：Gravity = 1.6（月球重力），模拟月球行走
• 黑洞效果：GravityPoint = true，所有物体会被吸向中心点