Index · Object → Node → Node3D → CollisionObject3D → Area3D

Area3D

A region of 3D space that detects other CollisionObject3Ds entering or exiting it.

Class Description

Area3D is a region of 3D space defined by one or multiple CollisionShape3D or CollisionPolygon3D child nodes. It detects when other CollisionObject3Ds enter or exit it, and it also keeps track of which collision objects haven't exited it yet (i.e. which one are overlapping it).

This node can also locally alter or override physics parameters (gravity, damping) and route audio to custom audio buses.

Note: Areas and bodies created with PhysicsServer3D might not interact as expected with Area3Ds, and might not emit signals or track objects correctly.

Warning: Using a ConcavePolygonShape3D inside a CollisionShape3D child of this node (created e.g. by using the Create Trimesh Collision Sibling option in the Mesh menu that appears when selecting a MeshInstance3D node) may give unexpected results, since this collision shape is hollow. If this is not desired, it has to be split into multiple ConvexPolygonShape3Ds or primitive shapes like BoxShape3D, or in some cases it may be replaceable by a CollisionPolygon3D.

Properties

var angular_damp: float = 0.1

The rate at which objects stop spinning in this area. Represents the angular velocity lost per second.

See ProjectSettings.physics/3d/default_angular_damp for more details about damping.

var angular_damp_space_override: Area3D.SpaceOverride = 0

Override mode for angular damping calculations within this area.

var audio_bus_name: StringName = &"Master"

The name of the area's audio bus.

var audio_bus_override: bool = false

If true, the area's audio bus overrides the default audio bus.

var gravity: float = 9.8

The area's gravity intensity (in meters per second squared). This value multiplies the gravity direction. This is useful to alter the force of gravity without altering its direction.

var gravity_direction: Vector3 = Vector3(0, -1, 0)

The area's gravity vector (not normalized).

var gravity_point: bool = false

If true, gravity is calculated from a point (set via gravity_point_center). See also gravity_space_override.

var gravity_point_center: Vector3 = Vector3(0, -1, 0)

If gravity is a point (see gravity_point), this will be the point of attraction.

var gravity_point_unit_distance: float = 0.0

The distance at which the gravity strength is equal to gravity. For example, on a planet 100 meters in radius with a surface gravity of 4.0 m/s², set the gravity to 4.0 and the unit distance to 100.0. The gravity will have falloff according to the inverse square law, so in the example, at 200 meters from the center the gravity will be 1.0 m/s² (twice the distance, 1/4th the gravity), at 50 meters it will be 16.0 m/s² (half the distance, 4x the gravity), and so on.

The above is true only when the unit distance is a positive number. When this is set to 0.0, the gravity will be constant regardless of distance.

var gravity_space_override: Area3D.SpaceOverride = 0

Override mode for gravity calculations within this area.

var linear_damp: float = 0.1

The rate at which objects stop moving in this area. Represents the linear velocity lost per second.

See ProjectSettings.physics/3d/default_linear_damp for more details about damping.

var linear_damp_space_override: Area3D.SpaceOverride = 0

Override mode for linear damping calculations within this area.

var monitorable: bool = true

If true, other monitoring areas can detect this area.

var monitoring: bool = true

If true, the area detects bodies or areas entering and exiting it.

var priority: int = 0

The area's priority. Higher priority areas are processed first. The World3D's physics is always processed last, after all areas.

var reverb_bus_amount: float = 0.0

The degree to which this area applies reverb to its associated audio. Ranges from 0 to 1 with 0.1 precision.

var reverb_bus_enabled: bool = false

If true, the area applies reverb to its associated audio.

var reverb_bus_name: StringName = &"Master"

The name of the reverb bus to use for this area's associated audio.

var reverb_bus_uniformity: float = 0.0

The degree to which this area's reverb is a uniform effect. Ranges from 0 to 1 with 0.1 precision.

var wind_attenuation_factor: float = 0.0

The exponential rate at which wind force decreases with distance from its origin.

Note: This wind force only applies to SoftBody3D nodes. Other physics bodies are currently not affected by wind.

var wind_force_magnitude: float = 0.0

The magnitude of area-specific wind force.

Note: This wind force only applies to SoftBody3D nodes. Other physics bodies are currently not affected by wind.

var wind_source_path: NodePath = NodePath("")

The Node3D which is used to specify the direction and origin of an area-specific wind force. The direction is opposite to the z-axis of the Node3D's local transform, and its origin is the origin of the Node3D's local transform.

Note: This wind force only applies to SoftBody3D nodes. Other physics bodies are currently not affected by wind.

Inherited from CollisionObject3D (6)
Inherited from Node3D (17)
var position: Vector3 = Vector3(0, 0, 0)
var rotation: Vector3 = Vector3(0, 0, 0)
var rotation_order: EulerOrder = 2
var scale: Vector3 = Vector3(1, 1, 1)
var top_level: bool = false
var transform: Transform3D = Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0)
var visibility_parent: NodePath = NodePath("")
var visible: bool = true
Inherited from Node (14)
var owner: Node

Methods

func get_overlapping_areas() -> Area3D[]

Returns a list of intersecting Area3Ds. The overlapping area's CollisionObject3D.collision_layer must be part of this area's CollisionObject3D.collision_mask in order to be detected.

For performance reasons (collisions are all processed at the same time) this list is modified once during the physics step, not immediately after objects are moved. Consider using signals instead.

func get_overlapping_bodies() -> Node3D[]

Returns a list of intersecting PhysicsBody3Ds, SoftBody3Ds, and GridMaps. The overlapping body's CollisionObject3D.collision_layer must be part of this area's CollisionObject3D.collision_mask in order to be detected.

For performance reasons (collisions are all processed at the same time) this list is modified once during the physics step, not immediately after objects are moved. Consider using signals instead.

Note: Godot Physics does not support reporting overlaps with SoftBody3D, so will not return any such bodies.

func has_overlapping_areas() -> bool

Returns true if intersecting any Area3Ds, otherwise returns false. The overlapping area's CollisionObject3D.collision_layer must be part of this area's CollisionObject3D.collision_mask in order to be detected.

For performance reasons (collisions are all processed at the same time) the list of overlapping areas is modified once during the physics step, not immediately after objects are moved. Consider using signals instead.

func has_overlapping_bodies() -> bool

Returns true if intersecting any PhysicsBody3Ds, SoftBody3Ds, or GridMaps, otherwise returns false. The overlapping body's CollisionObject3D.collision_layer must be part of this area's CollisionObject3D.collision_mask in order to be detected.

For performance reasons (collisions are all processed at the same time) the list of overlapping bodies is modified once during the physics step, not immediately after objects are moved. Consider using signals instead.

Note: Godot Physics does not support reporting overlaps with SoftBody3D, so will not consider such bodies.

func overlaps_area(area: Node) -> bool

Returns true if the given Area3D intersects or overlaps this Area3D, false otherwise.

Note: The result of this test is not immediate after moving objects. For performance, list of overlaps is updated once per frame and before the physics step. Consider using signals instead.

func overlaps_body(body: Node) -> bool

Returns true if the given physics body intersects or overlaps this Area3D, false otherwise.

body argument can either be a PhysicsBody3D, SoftBody3D, or a GridMap instance. While GridMaps are not physics body themselves, they register their tiles with collision shapes as a virtual physics body.

Note: The result of this test is not immediate after moving objects. For performance, list of overlaps is updated once per frame and before the physics step. Consider using signals instead.

Note: Godot Physics does not support reporting overlaps with SoftBody3D, so will return false in such cases.

Inherited from CollisionObject3D (23)
func _input_event(camera: Camera3D, event: InputEvent, event_position: Vector3, normal: Vector3, shape_idx: int) -> void
func _mouse_enter() -> void
func _mouse_exit() -> void
func create_shape_owner(owner: Object) -> int
func get_collision_layer_value(layer_number: int) -> bool
func get_collision_mask_value(layer_number: int) -> bool
func get_rid() -> RID
func is_shape_owner_disabled(owner_id: int) -> bool
func remove_shape_owner(owner_id: int) -> void
func set_collision_layer_value(layer_number: int, value: bool) -> void
func set_collision_mask_value(layer_number: int, value: bool) -> void
func shape_find_owner(shape_index: int) -> int
func shape_owner_add_shape(owner_id: int, shape: Shape3D) -> void
func shape_owner_clear_shapes(owner_id: int) -> void
func shape_owner_get_owner(owner_id: int) -> Object
func shape_owner_get_shape(owner_id: int, shape_id: int) -> Shape3D
func shape_owner_get_shape_index(owner_id: int, shape_id: int) -> int
func shape_owner_remove_shape(owner_id: int, shape_id: int) -> void
func shape_owner_set_disabled(owner_id: int, disabled: bool) -> void
func shape_owner_set_transform(owner_id: int, transform: Transform3D) -> void
Inherited from Node3D (37)
func add_gizmo(gizmo: Node3DGizmo) -> void
func clear_gizmos() -> void
func force_update_transform() -> void
func get_gizmos() -> Node3DGizmo[]
func global_rotate(axis: Vector3, angle: float) -> void
func global_scale(scale: Vector3) -> void
func global_translate(offset: Vector3) -> void
func hide() -> void
func look_at(target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) -> void
func look_at_from_position(position: Vector3, target: Vector3, up: Vector3 = Vector3(0, 1, 0), use_model_front: bool = false) -> void
func orthonormalize() -> void
func rotate(axis: Vector3, angle: float) -> void
func rotate_object_local(axis: Vector3, angle: float) -> void
func rotate_x(angle: float) -> void
func rotate_y(angle: float) -> void
func rotate_z(angle: float) -> void
func scale_object_local(scale: Vector3) -> void
func set_disable_scale(disable: bool) -> void
func set_identity() -> void
func set_notify_local_transform(enable: bool) -> void
func set_notify_transform(enable: bool) -> void
func set_subgizmo_selection(gizmo: Node3DGizmo, id: int, transform: Transform3D) -> void
func show() -> void
func to_global(local_point: Vector3) -> Vector3
func to_local(global_point: Vector3) -> Vector3
func translate(offset: Vector3) -> void
func translate_object_local(offset: Vector3) -> void
func update_gizmos() -> void
Inherited from Node (106)
func _enter_tree() -> void
func _exit_tree() -> void
func _input(event: InputEvent) -> void
func _physics_process(delta: float) -> void
func _process(delta: float) -> void
func _ready() -> void
func _shortcut_input(event: InputEvent) -> void
func _unhandled_input(event: InputEvent) -> void
func _unhandled_key_input(event: InputEvent) -> void
func add_child(node: Node, force_readable_name: bool = false, internal: Node.InternalMode = 0) -> void
func add_sibling(sibling: Node, force_readable_name: bool = false) -> void
func add_to_group(group: StringName, persistent: bool = false) -> void
func atr(message: String, context: StringName = "") -> String
func atr_n(message: String, plural_message: StringName, n: int, context: StringName = "") -> String
func can_process() -> bool
func duplicate(flags: int = 15) -> Node
func find_child(pattern: String, recursive: bool = true, owned: bool = true) -> Node
func find_children(pattern: String, type: String = "", recursive: bool = true, owned: bool = true) -> Node[]
func find_parent(pattern: String) -> Node
func get_child(idx: int, include_internal: bool = false) -> Node
func get_child_count(include_internal: bool = false) -> int
func get_children(include_internal: bool = false) -> Node[]
func get_groups() -> StringName[]
func get_index(include_internal: bool = false) -> int
func get_node(path: NodePath) -> Node
func get_orphan_node_ids() -> int[]
func get_parent() -> Node
func get_path() -> NodePath
func get_path_to(node: Node, use_unique_path: bool = false) -> NodePath
func get_window() -> Window
func has_node(path: NodePath) -> bool
func is_ancestor_of(node: Node) -> bool
func is_greater_than(node: Node) -> bool
func is_in_group(group: StringName) -> bool
func move_child(child_node: Node, to_index: int) -> void
func notify_deferred_thread_group(what: int) -> void
func notify_thread_safe(what: int) -> void
func print_orphan_nodes() -> void
func print_tree() -> void
func print_tree_pretty() -> void
func propagate_call(method: StringName, args: Array = [], parent_first: bool = false) -> void
func propagate_notification(what: int) -> void
func queue_free() -> void
func remove_child(node: Node) -> void
func remove_from_group(group: StringName) -> void
func reparent(new_parent: Node, keep_global_transform: bool = true) -> void
func replace_by(node: Node, keep_groups: bool = false) -> void
func request_ready() -> void
func rpc(method: StringName) -> Error
func rpc_config(method: StringName, config: Variant) -> void
func rpc_id(peer_id: int, method: StringName) -> Error
func set_deferred_thread_group(property: StringName, value: Variant) -> void
func set_display_folded(fold: bool) -> void
func set_editable_instance(node: Node, is_editable: bool) -> void
func set_multiplayer_authority(id: int, recursive: bool = true) -> void
func set_physics_process(enable: bool) -> void
func set_physics_process_internal(enable: bool) -> void
func set_process(enable: bool) -> void
func set_process_input(enable: bool) -> void
func set_process_internal(enable: bool) -> void
func set_process_shortcut_input(enable: bool) -> void
func set_process_unhandled_input(enable: bool) -> void
func set_scene_instance_load_placeholder(load_placeholder: bool) -> void
func set_thread_safe(property: StringName, value: Variant) -> void
Inherited from Object (62)
func _get(property: StringName) -> Variant
func _get_property_list() -> Dictionary[]
func _init() -> void
func _iter_get(iter: Variant) -> Variant
func _iter_init(iter: Array) -> bool
func _iter_next(iter: Array) -> bool
func _notification(what: int) -> void
func _set(property: StringName, value: Variant) -> bool
func _to_string() -> String
func _validate_property(property: Dictionary) -> void
func add_user_signal(signal: String, arguments: Array = []) -> void
func call(method: StringName) -> Variant
func callv(method: StringName, arg_array: Array) -> Variant
func cancel_free() -> void
func connect(signal: StringName, callable: Callable, flags: int = 0) -> Error
func disconnect(signal: StringName, callable: Callable) -> void
func emit_signal(signal: StringName) -> Error
func free() -> void
func get(property: StringName) -> Variant
func get_class() -> String
func get_incoming_connections() -> Dictionary[]
func get_indexed(property_path: NodePath) -> Variant
func get_meta(name: StringName, default: Variant = null) -> Variant
func get_meta_list() -> StringName[]
func get_method_list() -> Dictionary[]
func get_property_list() -> Dictionary[]
func get_signal_connection_list(signal: StringName) -> Dictionary[]
func get_signal_list() -> Dictionary[]
func has_meta(name: StringName) -> bool
func has_method(method: StringName) -> bool
func has_signal(signal: StringName) -> bool
func is_class(class: StringName) -> bool
func is_connected(signal: StringName, callable: Callable) -> bool
func notification(what: int, reversed: bool = false) -> void
func remove_meta(name: StringName) -> void
func remove_user_signal(signal: StringName) -> void
func set(property: StringName, value: Variant) -> void
func set_block_signals(enable: bool) -> void
func set_deferred(property: StringName, value: Variant) -> void
func set_indexed(property_path: NodePath, value: Variant) -> void
func set_message_translation(enable: bool) -> void
func set_meta(name: StringName, value: Variant) -> void
func set_script(script: Variant) -> void
func set_translation_domain(domain: StringName) -> void
func to_string() -> String
func tr(message: StringName, context: StringName = &"") -> String
func tr_n(message: StringName, plural_message: StringName, n: int, context: StringName = &"") -> String

Signals

signal area_entered(area: Area3D)

Emitted when the received area enters this area. Requires monitoring to be set to true.

signal area_exited(area: Area3D)

Emitted when the received area exits this area. Requires monitoring to be set to true.

signal area_shape_entered(area_rid: RID, area: Area3D, area_shape_index: int, local_shape_index: int)

Emitted when a Shape3D of the received area enters a shape of this area. Requires monitoring to be set to true.

local_shape_index and area_shape_index contain indices of the interacting shapes from this area and the other area, respectively. area_rid contains the RID of the other area. These values can be used with the PhysicsServer3D.

Example: Get the CollisionShape3D node from the shape index:

var other_shape_owner = area.shape_find_owner(area_shape_index)
var other_shape_node = area.shape_owner_get_owner(other_shape_owner)

var local_shape_owner = shape_find_owner(local_shape_index)
var local_shape_node = shape_owner_get_owner(local_shape_owner)
signal area_shape_exited(area_rid: RID, area: Area3D, area_shape_index: int, local_shape_index: int)

Emitted when a Shape3D of the received area exits a shape of this area. Requires monitoring to be set to true.

See also area_shape_entered.

signal body_entered(body: Node3D)

Emitted when the received body enters this area. body can be a PhysicsBody3D, SoftBody3D or GridMap. GridMaps are detected if their MeshLibrary has collision shapes configured. Requires monitoring to be set to true.

Note: Godot Physics does not support reporting overlaps with SoftBody3D, so will not emit this signal in such cases.

signal body_exited(body: Node3D)

Emitted when the received body exits this area. body can be a PhysicsBody3D, SoftBody3D or GridMap. GridMaps are detected if their MeshLibrary has collision shapes configured. Requires monitoring to be set to true.

Note: Godot Physics does not support reporting overlaps with SoftBody3D, so will not emit this signal in such cases.

signal body_shape_entered(body_rid: RID, body: Node3D, body_shape_index: int, local_shape_index: int)

Emitted when a Shape3D of the received body enters a shape of this area. body can be a PhysicsBody3D, SoftBody3D or GridMap. GridMaps are detected if their MeshLibrary has collision shapes configured. Requires monitoring to be set to true.

local_shape_index and body_shape_index contain indices of the interacting shapes from this area and the interacting body, respectively. body_rid contains the RID of the body. These values can be used with the PhysicsServer3D.

Note: Godot Physics does not support reporting overlaps with SoftBody3D, so will not emit this signal in such cases.

Example: Get the CollisionShape3D node from the shape index:

var body_shape_owner = body.shape_find_owner(body_shape_index)
var body_shape_node = body.shape_owner_get_owner(body_shape_owner)

var local_shape_owner = shape_find_owner(local_shape_index)
var local_shape_node = shape_owner_get_owner(local_shape_owner)
signal body_shape_exited(body_rid: RID, body: Node3D, body_shape_index: int, local_shape_index: int)

Emitted when a Shape3D of the received body exits a shape of this area. body can be a PhysicsBody3D, SoftBody3D or GridMap. GridMaps are detected if their MeshLibrary has collision shapes configured. Requires monitoring to be set to true.

See also body_shape_entered.

Note: Godot Physics does not support reporting overlaps with SoftBody3D, so will not emit this signal in such cases.

Inherited from CollisionObject3D (3)
signal input_event(camera: Node, event: InputEvent, event_position: Vector3, normal: Vector3, shape_idx: int)
signal mouse_entered()
signal mouse_exited()
Inherited from Node3D (1)
Inherited from Node (11)
signal child_entered_tree(node: Node)
signal child_exiting_tree(node: Node)
signal ready()
signal renamed()
signal replacing_by(node: Node)
signal tree_entered()
signal tree_exited()
signal tree_exiting()
Inherited from Object (2)

Enums & Constants

enum SpaceOverride
SPACE_OVERRIDE_DISABLED = 0

This area does not affect gravity/damping.

SPACE_OVERRIDE_COMBINE = 1

This area adds its gravity/damping values to whatever has been calculated so far (in priority order).

SPACE_OVERRIDE_COMBINE_REPLACE = 2

This area adds its gravity/damping values to whatever has been calculated so far (in priority order), ignoring any lower priority areas.

SPACE_OVERRIDE_REPLACE = 3

This area replaces any gravity/damping, even the defaults, ignoring any lower priority areas.

SPACE_OVERRIDE_REPLACE_COMBINE = 4

This area replaces any gravity/damping calculated so far (in priority order), but keeps calculating the rest of the areas.