Index · Object → Node → CanvasItem → Node2D → CollisionObject2D → Area2D

Area2D

A region of 2D space that detects other CollisionObject2Ds entering or exiting it.

Class Description

Area2D is a region of 2D space defined by one or multiple CollisionShape2D or CollisionPolygon2D child nodes. It detects when other CollisionObject2Ds 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 PhysicsServer2D might not interact as expected with Area2Ds, and might not emit signals or track objects correctly.

Properties

var angular_damp: float = 1.0

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

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

var angular_damp_space_override: Area2D.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 = 980.0

The area's gravity intensity (in pixels 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: Vector2 = Vector2(0, 1)

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: Vector2 = Vector2(0, 1)

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 pixels in radius with a surface gravity of 4.0 px/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 pixels from the center the gravity will be 1.0 px/s² (twice the distance, 1/4th the gravity), at 50 pixels it will be 16.0 px/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: Area2D.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/2d/default_linear_damp for more details about damping.

var linear_damp_space_override: Area2D.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 World2D's physics is always processed last, after all areas.

Inherited from CollisionObject2D (5)
var input_pickable: bool = true
Inherited from Node2D (12)
var position: Vector2 = Vector2(0, 0)
var rotation: float = 0.0
var scale: Vector2 = Vector2(1, 1)
var skew: float = 0.0
Inherited from CanvasItem (16)
var light_mask: int = 1
var modulate: Color = Color(1, 1, 1, 1)
var self_modulate: Color = Color(1, 1, 1, 1)
var top_level: bool = false
var visible: bool = true
var y_sort_enabled: bool = false
var z_as_relative: bool = true
var z_index: int = 0
Inherited from Node (14)
var owner: Node

Methods

func get_overlapping_areas() -> Area2D[]

Returns a list of intersecting Area2Ds. The overlapping area's CollisionObject2D.collision_layer must be part of this area's CollisionObject2D.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() -> Node2D[]

Returns a list of intersecting PhysicsBody2Ds and TileMaps. The overlapping body's CollisionObject2D.collision_layer must be part of this area's CollisionObject2D.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 has_overlapping_areas() -> bool

Returns true if intersecting any Area2Ds, otherwise returns false. The overlapping area's CollisionObject2D.collision_layer must be part of this area's CollisionObject2D.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 PhysicsBody2Ds or TileMaps, otherwise returns false. The overlapping body's CollisionObject2D.collision_layer must be part of this area's CollisionObject2D.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.

func overlaps_area(area: Node) -> bool

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

Note: The result of this test is not immediate after moving objects. For performance, the 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 Area2D, 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.

The body argument can either be a PhysicsBody2D or a TileMap instance. While TileMaps are not physics bodies themselves, they register their tiles with collision shapes as a virtual physics body.

Inherited from CollisionObject2D (31)
func _input_event(viewport: Viewport, event: InputEvent, shape_idx: int) -> void
func _mouse_enter() -> void
func _mouse_exit() -> void
func _mouse_shape_enter(shape_idx: int) -> void
func _mouse_shape_exit(shape_idx: int) -> 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: Shape2D) -> 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) -> Shape2D
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_one_way_collision(owner_id: int, enable: bool) -> void
func shape_owner_set_one_way_collision_direction(owner_id: int, direction: Vector2) -> void
func shape_owner_set_one_way_collision_margin(owner_id: int, margin: float) -> void
func shape_owner_set_transform(owner_id: int, transform: Transform2D) -> void
Inherited from Node2D (11)
func apply_scale(ratio: Vector2) -> void
func get_angle_to(point: Vector2) -> float
func global_translate(offset: Vector2) -> void
func look_at(point: Vector2) -> void
func move_local_x(delta: float, scaled: bool = false) -> void
func move_local_y(delta: float, scaled: bool = false) -> void
func rotate(radians: float) -> void
func to_global(local_point: Vector2) -> Vector2
func to_local(global_point: Vector2) -> Vector2
func translate(offset: Vector2) -> void
Inherited from CanvasItem (62)
func _draw() -> void
func draw_animation_slice(animation_length: float, slice_begin: float, slice_end: float, offset: float = 0.0) -> void
func draw_arc(center: Vector2, radius: float, start_angle: float, end_angle: float, point_count: int, color: Color, width: float = -1.0, antialiased: bool = false) -> void
func draw_char(font: Font, pos: Vector2, char: String, font_size: int = 16, modulate: Color = Color(1, 1, 1, 1), oversampling: float = 0.0) -> void
func draw_char_outline(font: Font, pos: Vector2, char: String, font_size: int = 16, size: int = -1, modulate: Color = Color(1, 1, 1, 1), oversampling: float = 0.0) -> void
func draw_circle(position: Vector2, radius: float, color: Color, filled: bool = true, width: float = -1.0, antialiased: bool = false) -> void
func draw_colored_polygon(points: PackedVector2Array, color: Color, uvs: PackedVector2Array = PackedVector2Array(), texture: Texture2D = null) -> void
func draw_dashed_line(from: Vector2, to: Vector2, color: Color, width: float = -1.0, dash: float = 2.0, aligned: bool = true, antialiased: bool = false) -> void
func draw_ellipse(position: Vector2, major: float, minor: float, color: Color, filled: bool = true, width: float = -1.0, antialiased: bool = false) -> void
func draw_ellipse_arc(center: Vector2, major: float, minor: float, start_angle: float, end_angle: float, point_count: int, color: Color, width: float = -1.0, antialiased: bool = false) -> void
func draw_end_animation() -> void
func draw_lcd_texture_rect_region(texture: Texture2D, rect: Rect2, src_rect: Rect2, modulate: Color = Color(1, 1, 1, 1)) -> void
func draw_line(from: Vector2, to: Vector2, color: Color, width: float = -1.0, antialiased: bool = false) -> void
func draw_mesh(mesh: Mesh, texture: Texture2D, transform: Transform2D = Transform2D(1, 0, 0, 1, 0, 0), modulate: Color = Color(1, 1, 1, 1)) -> void
func draw_msdf_texture_rect_region(texture: Texture2D, rect: Rect2, src_rect: Rect2, modulate: Color = Color(1, 1, 1, 1), outline: float = 0.0, pixel_range: float = 4.0, scale: float = 1.0) -> void
func draw_multiline(points: PackedVector2Array, color: Color, width: float = -1.0, antialiased: bool = false) -> void
func draw_multiline_colors(points: PackedVector2Array, colors: PackedColorArray, width: float = -1.0, antialiased: bool = false) -> void
func draw_multiline_string(font: Font, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, max_lines: int = -1, modulate: Color = Color(1, 1, 1, 1), brk_flags: TextServer.LineBreakFlag = 3, justification_flags: TextServer.JustificationFlag = 3, direction: TextServer.Direction = 0, orientation: TextServer.Orientation = 0, oversampling: float = 0.0) -> void
func draw_multiline_string_outline(font: Font, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, max_lines: int = -1, size: int = 1, modulate: Color = Color(1, 1, 1, 1), brk_flags: TextServer.LineBreakFlag = 3, justification_flags: TextServer.JustificationFlag = 3, direction: TextServer.Direction = 0, orientation: TextServer.Orientation = 0, oversampling: float = 0.0) -> void
func draw_multimesh(multimesh: MultiMesh, texture: Texture2D) -> void
func draw_polygon(points: PackedVector2Array, colors: PackedColorArray, uvs: PackedVector2Array = PackedVector2Array(), texture: Texture2D = null) -> void
func draw_polyline(points: PackedVector2Array, color: Color, width: float = -1.0, antialiased: bool = false) -> void
func draw_polyline_colors(points: PackedVector2Array, colors: PackedColorArray, width: float = -1.0, antialiased: bool = false) -> void
func draw_primitive(points: PackedVector2Array, colors: PackedColorArray, uvs: PackedVector2Array, texture: Texture2D = null) -> void
func draw_rect(rect: Rect2, color: Color, filled: bool = true, width: float = -1.0, antialiased: bool = false) -> void
func draw_set_transform(position: Vector2, rotation: float = 0.0, scale: Vector2 = Vector2(1, 1)) -> void
func draw_string(font: Font, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, modulate: Color = Color(1, 1, 1, 1), justification_flags: TextServer.JustificationFlag = 3, direction: TextServer.Direction = 0, orientation: TextServer.Orientation = 0, oversampling: float = 0.0) -> void
func draw_string_outline(font: Font, pos: Vector2, text: String, alignment: HorizontalAlignment = 0, width: float = -1, font_size: int = 16, size: int = 1, modulate: Color = Color(1, 1, 1, 1), justification_flags: TextServer.JustificationFlag = 3, direction: TextServer.Direction = 0, orientation: TextServer.Orientation = 0, oversampling: float = 0.0) -> void
func draw_style_box(style_box: StyleBox, rect: Rect2) -> void
func draw_texture(texture: Texture2D, position: Vector2, modulate: Color = Color(1, 1, 1, 1)) -> void
func draw_texture_rect(texture: Texture2D, rect: Rect2, tile: bool, modulate: Color = Color(1, 1, 1, 1), transpose: bool = false) -> void
func draw_texture_rect_region(texture: Texture2D, rect: Rect2, src_rect: Rect2, modulate: Color = Color(1, 1, 1, 1), transpose: bool = false, clip_uv: bool = true) -> void
func force_update_transform() -> void
func get_canvas() -> RID
func hide() -> void
func make_canvas_position_local(viewport_point: Vector2) -> Vector2
func move_to_front() -> void
func queue_redraw() -> void
func set_notify_local_transform(enable: bool) -> void
func set_notify_transform(enable: bool) -> void
func set_visibility_layer_bit(layer: int, enabled: bool) -> void
func show() -> 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: Area2D)

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

signal area_exited(area: Area2D)

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

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

Emitted when a Shape2D 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 PhysicsServer2D.

Example: Get the CollisionShape2D 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: Area2D, area_shape_index: int, local_shape_index: int)

Emitted when a Shape2D 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: Node2D)

Emitted when the received body enters this area. body can be a PhysicsBody2D or a TileMap. TileMaps are detected if their TileSet has collision shapes configured. Requires monitoring to be set to true.

signal body_exited(body: Node2D)

Emitted when the received body exits this area. body can be a PhysicsBody2D or a TileMap. TileMaps are detected if their TileSet has collision shapes configured. Requires monitoring to be set to true.

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

Emitted when a Shape2D of the received body enters a shape of this area. body can be a PhysicsBody2D or a TileMap. TileMaps are detected if their TileSet 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 PhysicsServer2D.

Example: Get the CollisionShape2D 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: Node2D, body_shape_index: int, local_shape_index: int)

Emitted when a Shape2D of the received body exits a shape of this area. body can be a PhysicsBody2D or a TileMap. TileMaps are detected if their TileSet has collision shapes configured. Requires monitoring to be set to true.

See also body_shape_entered.

Inherited from CollisionObject2D (5)
signal input_event(viewport: Node, event: InputEvent, shape_idx: int)
signal mouse_entered()
signal mouse_exited()
signal mouse_shape_entered(shape_idx: int)
signal mouse_shape_exited(shape_idx: int)
Inherited from CanvasItem (4)
signal draw()
signal hidden()
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.