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
float	get_gravity ( ) const
float	get_gravity_distance_scale ( ) const
Vector3	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_enabled ( ) const
bool	overlaps_area ( Object area ) const
bool	overlaps_body ( Object body ) const
void	set_angular_damp ( float angular_damp )
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_linear_damp ( float linear_damp )
void	set_monitorable ( bool enable )
void	set_priority ( float priority )
void	set_space_override_mode ( int enable )

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

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

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

• bool overlaps_area ( Object area ) const

Return whether the area passed is totally or partially inside this area.

• bool overlaps_body ( Object body ) const

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