Area2D¶
Inherits: CollisionObject2D < Node2D < CanvasItem < Node < Object
Category: Core
Brief Description¶
General purpose area detection and influence for 2D physics.
Member Functions¶
Signals¶
- area_enter ( Object area )
- area_enter_shape ( int area_id, Object area, int area_shape, int area_shape )
- area_exit ( Object area )
- area_exit_shape ( int area_id, Object area, int area_shape, int area_shape )
- body_enter ( Object body )
- body_enter_shape ( int body_id, Object body, int body_shape, int area_shape )
- body_exit ( Object body )
- body_exit_shape ( int body_id, Object body, int body_shape, int area_shape )
Description¶
General purpose area detection for 2D physics. Areas can be used for detection of objects that enter/exit them, as well as overriding space parameters (changing gravity, damping, etc). For this, use any space override different from AREA_SPACE_OVERRIDE_DISABLE and point gravity at the center of mass.
Member Function Description¶
- float get_angular_damp ( ) const
Return the angular damp rate.
- int get_collision_mask ( ) const
Return the physics layers this area can scan for collisions.
Return an individual bit on the collision mask.
- 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.
- int get_layer_mask ( ) const
Return the physics layer this area is in.
Return an individual bit on the layer mask.
- float get_linear_damp ( ) const
Return the linear damp rate.
- Array get_overlapping_areas ( ) const
Return a list of the areas that are totally or partially inside this area.
- Array get_overlapping_bodies ( ) const
Return a list of the bodies (PhysicsBody2D) that are totally or partially inside this area.
- 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_enabled ( ) const
Return whether this area detects bodies/areas entering/exiting it.
Return whether the area passed is totally or partially inside this area.
Return whether the body passed is totally or partially inside this area.
- 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_collision_mask ( int collision_mask )
Set the physics layers this area can scan for collisions.
Set/clear individual bits on the collision mask. This makes selecting the areas scanned easier.
- void set_enable_monitoring ( bool enable )
Set whether this area can detect bodies/areas entering/exiting it.
- 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_layer_mask ( int layer_mask )
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.
Set/clear individual bits on the layer mask. This makes getting an area in/out of only one layer easier.
- 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_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 an 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 enable )
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.