Area2D

Inherits: CollisionObject2D < Node2D < CanvasItem < Node < Object

Category: Core

Brief Description

2D area for detection and 2D physics influence.

Member Functions

float get_angular_damp ( ) const
String get_audio_bus_name ( ) const
int get_collision_layer ( ) const
bool get_collision_layer_bit ( int bit ) const
int get_collision_mask ( ) const
bool get_collision_mask_bit ( int bit ) const
float get_gravity ( ) const
float get_gravity_distance_scale ( ) const
Vector2 get_gravity_vector ( ) const
float get_linear_damp ( ) const
Array get_overlapping_areas ( ) const
Array get_overlapping_bodies ( ) const
float get_priority ( ) const
int get_space_override_mode ( ) const
bool is_gravity_a_point ( ) const
bool is_monitorable ( ) const
bool is_monitoring ( ) const
bool is_overriding_audio_bus ( ) const
bool overlaps_area ( Node area ) const
bool overlaps_body ( Node body ) const
void set_angular_damp ( float angular_damp )
void set_audio_bus_name ( String name )
void set_audio_bus_override ( bool enable )
void set_collision_layer ( int collision_layer )
void set_collision_layer_bit ( int bit, bool value )
void set_collision_mask ( int collision_mask )
void set_collision_mask_bit ( int bit, bool value )
void set_gravity ( float gravity )
void set_gravity_distance_scale ( float distance_scale )
void set_gravity_is_point ( bool enable )
void set_gravity_vector ( Vector2 vector )
void set_linear_damp ( float linear_damp )
void set_monitorable ( bool enable )
void set_monitoring ( bool enable )
void set_priority ( float priority )
void set_space_override_mode ( int space_override_mode )

Signals

  • area_entered ( Object area )

Emitted when another area enters.

Emitted when another area exits.

  • area_shape_entered ( int area_id, Object area, int area_shape, int self_shape )

Emitted when another area enters, reporting which shapes overlapped.

  • area_shape_exited ( int area_id, Object area, int area_shape, int self_shape )

Emitted when another area exits, reporting which shapes were overlapping.

  • body_entered ( Object body )

Emitted when a PhysicsBody2D object enters.

Emitted when a PhysicsBody2D object exits.

  • body_shape_entered ( int body_id, Object body, int body_shape, int area_shape )

Emitted when a PhysicsBody2D object enters, reporting which shapes overlapped.

  • body_shape_exited ( int body_id, Object body, int body_shape, int area_shape )

Emitted when a PhysicsBody2D object exits, reporting which shapes were overlapping.

Member Variables

  • float angular_damp - The rate at which objects stop spinning in this area. Represents the angular velocity lost per second. Values range from 0 (no damping) to 1 (full damping).
  • String audio_bus_name - The name of the area’s audio bus.
  • bool audio_bus_override - If true the area’s audio bus overrides the default audio bus. Default value: false.
  • int collision_layer - The area’s physics layer(s). Collidable objects can exist in any of 32 different layers. A contact is detected if object A is in any of the layers that object B scans, or object B is in any layers that object A scans. See also collision_mask.
  • int collision_mask - The physics layers this area scans to determine collision detection.
  • float gravity - The area’s gravity intensity (ranges from -1024 to 1024). This value multiplies the gravity vector. This is useful to alter the force of gravity without altering its direction.
  • float gravity_distance_scale - The falloff factor for point gravity. The greater the value, the faster gravity decreases with distance.
  • bool gravity_point - If true gravity is calculated from a point (set via gravity_vec). Also see space_override. Default value: false.
  • Vector2 gravity_vec - The area’s gravity vector (not normalized). If gravity is a point (see is_gravity_a_point), this will be the point of attraction.
  • float linear_damp - The rate at which objects stop moving in this area. Represents the linear velocity lost per second. Values range from 0 (no damping) to 1 (full damping).
  • bool monitorable - If true other monitoring areas can detect this area. Default value: true.
  • bool monitoring - If true the area detects bodies or areas entering and exiting it. Default value: true.
  • float priority - The area’s priority. Higher priority areas are processed first. Default value: 0.
  • int space_override - Override mode for gravity and damping calculations within this area. See the SPACE_OVERRIDE_* constants for values.

Numeric Constants

  • 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.

Description

2D area that detects CollisionObject2D nodes overlapping, entering, or exiting. Can also alter or override local physics parameters (gravity, damping).

Member Function Description

  • float get_angular_damp ( ) const

Return the angular damp rate.

  • String get_audio_bus_name ( ) const
  • int get_collision_layer ( ) const

Return the physics layer this area is in.

  • bool get_collision_layer_bit ( int bit ) const

Return an individual bit on the layer mask. Describes whether other areas will collide with this one on the given layer.

  • int get_collision_mask ( ) const

Return the physics layers this area will scan to determine collisions.

  • bool get_collision_mask_bit ( int bit ) const

Return an individual bit on the collision mask. Describes whether this area will collide with others on the given layer.

  • float get_gravity ( ) const

Return the gravity intensity.

  • float get_gravity_distance_scale ( ) const

Return the falloff factor for point gravity.

  • Vector2 get_gravity_vector ( ) const

Return the gravity vector. If gravity is a point (see is_gravity_a_point), this will be the attraction center.

  • float get_linear_damp ( ) const

Return the linear damp rate.

  • Array get_overlapping_areas ( ) const

Returns a list of intersecting ``Area2D``s.

  • Array get_overlapping_bodies ( ) const

Returns a list of intersecting PhysicsBody2Ds.

  • float get_priority ( ) const

Return the processing order of this area.

  • int get_space_override_mode ( ) const

Return the space override mode.

  • bool is_gravity_a_point ( ) const

Return whether gravity is a point. A point gravity will attract objects towards it, as opposed to a gravity vector, which moves them in a given direction.

  • bool is_monitorable ( ) const

Return whether this area can be detected by other, monitoring, areas.

  • bool is_monitoring ( ) const

Return whether this area detects bodies/areas entering/exiting it.

  • bool is_overriding_audio_bus ( ) const
  • bool overlaps_area ( Node area ) const

If true the given area overlaps the Area2D.

  • bool overlaps_body ( Node body ) const

If true the given body overlaps the Area2D.

  • void set_angular_damp ( float angular_damp )

Set the rate at which objects stop spinning in this area, if there are not any other forces making it spin. The value is a fraction of its current speed, lost per second. Thus, a value of 1.0 should mean stopping immediately, and 0.0 means the object never stops.

In practice, as the fraction of speed lost gets smaller with each frame, a value of 1.0 does not mean the object will stop in exactly one second. Only when the physics calculations are done at 1 frame per second, it does stop in a second.

  • void set_audio_bus_name ( String name )
  • void set_audio_bus_override ( bool enable )
  • void set_collision_layer ( int collision_layer )

Set the physics layers this area is in.

Collidable objects can exist in any of 32 different layers. These layers are not visual, but more of a tagging system instead. A collidable can use these layers/tags to select with which objects it can collide, using set_collision_mask.

A contact is detected if object A is in any of the layers that object B scans, or object B is in any layer scanned by object A.

  • void set_collision_layer_bit ( int bit, bool value )

Set/clear individual bits on the layer mask. This makes getting an area in/out of only one layer easier.

  • void set_collision_mask ( int collision_mask )

Set the physics layers this area can scan for collisions.

  • void set_collision_mask_bit ( int bit, bool value )

Set/clear individual bits on the collision mask. This makes selecting the areas scanned easier.

  • void set_gravity ( float gravity )

Set the gravity intensity. This is useful to alter the force of gravity without altering its direction.

This value multiplies the gravity vector, whether it is the given vector (set_gravity_vector), or a calculated one (when using a center of gravity).

  • void set_gravity_distance_scale ( float distance_scale )

Set the falloff factor for point gravity. The greater this value is, the faster the strength of gravity decreases with the square of distance.

  • void set_gravity_is_point ( bool enable )

When overriding space parameters, this method sets whether this area has a center of gravity. To set/get the location of the center of gravity, use set_gravity_vector/get_gravity_vector.

  • void set_gravity_vector ( Vector2 vector )

Set the gravity vector. This vector does not have to be normalized.

If gravity is a point (see is_gravity_a_point), this will be the attraction center.

  • void set_linear_damp ( float linear_damp )

Set the rate at which objects stop moving in this area, if there are not any other forces moving it. The value is a fraction of its current speed, lost per second. Thus, a value of 1.0 should mean stopping immediately, and 0.0 means the object never stops.

In practice, as the fraction of speed lost gets smaller with each frame, a value of 1.0 does not mean the object will stop in exactly one second. Only when the physics calculations are done at 1 frame per second, it does stop in a second.

  • void set_monitorable ( bool enable )

Set whether this area can be detected by other, monitoring, areas. Only areas need to be marked as monitorable. Bodies are always so.

  • void set_monitoring ( bool enable )

Set whether this area can detect bodies/areas entering/exiting it.

  • void set_priority ( float priority )

Set the order in which the area is processed. Greater values mean the area gets processed first. This is useful for areas which have a space override different from AREA_SPACE_OVERRIDE_DISABLED or AREA_SPACE_OVERRIDE_COMBINE, as they replace values, and are thus order-dependent.

Areas with the same priority value get evaluated in an unpredictable order, and should be differentiated if evaluation order is to be important.

  • void set_space_override_mode ( int space_override_mode )

Set the space override mode. This mode controls how an area affects gravity and damp.

AREA_SPACE_OVERRIDE_DISABLED: This area does not affect gravity/damp. These are generally areas that exist only to detect collisions, and objects entering or exiting them.

AREA_SPACE_OVERRIDE_COMBINE: This area adds its gravity/damp values to whatever has been calculated so far. This way, many overlapping areas can combine their physics to make interesting effects.

AREA_SPACE_OVERRIDE_COMBINE_REPLACE: This area adds its gravity/damp values to whatever has been calculated so far. Then stops taking into account the rest of the areas, even the default one.

AREA_SPACE_OVERRIDE_REPLACE: This area replaces any gravity/damp, even the default one, and stops taking into account the rest of the areas.

AREA_SPACE_OVERRIDE_REPLACE_COMBINE: This area replaces any gravity/damp calculated so far, but keeps calculating the rest of the areas, down to the default one.