Area

Inherits: CollisionObject < Spatial < Node < Object

Category: Core

Brief Description

General purpose area detection and influence for 3D physics.

Member Functions

float get_angular_damp ( ) const
int get_collision_mask ( ) const
bool get_collision_mask_bit ( int bit ) const
float get_gravity ( ) const
float get_gravity_distance_scale ( ) const
Vector3 get_gravity_vector ( ) const
int get_layer_mask ( ) const
bool get_layer_mask_bit ( int bit ) 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_enabled ( ) const
bool overlaps_area ( Object area ) const
bool overlaps_body ( Object body ) const
void set_angular_damp ( float angular_damp )
void set_collision_mask ( int collision_mask )
void set_collision_mask_bit ( int bit, bool value )
void set_enable_monitoring ( bool enable )
void set_gravity ( float gravity )
void set_gravity_distance_scale ( float distance_scale )
void set_gravity_is_point ( bool enable )
void set_gravity_vector ( Vector3 vector )
void set_layer_mask ( int layer_mask )
void set_layer_mask_bit ( int bit, bool value )
void set_linear_damp ( float linear_damp )
void set_monitorable ( bool enable )
void set_priority ( float priority )
void set_space_override_mode ( int enable )

Signals

Description

General purpose area detection for 3D 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.

  • bool get_collision_mask_bit ( int bit ) const

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.

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

  • bool get_layer_mask_bit ( int bit ) const

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 (PhysicsBody) 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.

  • 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_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 ( Vector3 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.

  • void set_layer_mask_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_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.