Merge pull request #11135 from willnationsdev/area2d-docs

Area2D Documentation + constants in _bind_methods

2 files changed, 50 insertions, 22 deletions

diff --git a/doc/base/classes.xml b/doc/base/classes.xml
index 2a9350bbdc..16a8b16a6f 100644
--- a/doc/base/classes.xml
+++ b/doc/base/classes.xml
@@ -5083,10 +5083,10 @@
 </class>
 <class name="Area2D" inherits="CollisionObject2D" category="Core">
 	<brief_description>
-		General purpose area detection and influence for 2D physics.
+		2D area that detects nodes that enter or exit it. Can override 2D physics properties within range.
 	</brief_description>
 	<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.
+		2D area that detects nodes that enter or exit it. Change  the 'space_override' property SPACE_OVERRIDE_* to override physics parameters for nodes like [Rigidbody2D]. E.g. gravity, damping... See [CollisionObject2D] for usage.
 	</description>
 	<methods>
 		<method name="get_angular_damp" qualifiers="const">
@@ -5115,14 +5115,14 @@
 			<argument index="0" name="bit" type="int">
 			</argument>
 			<description>
-				Return an individual bit on the layer mask.
+				Return an individual bit on the layer mask. Describes whether other areas will collide with this one on the given layer.
 			</description>
 		</method>
 		<method name="get_collision_mask" qualifiers="const">
 			<return type="int">
 			</return>
 			<description>
-				Return the physics layers this area can scan for collisions.
+				Return the physics layers this area will scan to determine collisions.
 			</description>
 		</method>
 		<method name="get_collision_mask_bit" qualifiers="const">
@@ -5131,7 +5131,7 @@
 			<argument index="0" name="bit" type="int">
 			</argument>
 			<description>
-				Return an individual bit on the collision mask.
+				Return an individual bit on the collision mask. Describes whether this area will collide with others on the given layer.
 			</description>
 		</method>
 		<method name="get_gravity" qualifiers="const">
@@ -5166,14 +5166,14 @@
 			<return type="Array">
 			</return>
 			<description>
-				Return a list of the areas that are totally or partially inside this area.
+				Returns a list of the [Area2D]s that intersect with this area.
 			</description>
 		</method>
 		<method name="get_overlapping_bodies" qualifiers="const">
 			<return type="Array">
 			</return>
 			<description>
-				Return a list of the bodies ([PhysicsBody2D]) that are totally or partially inside this area.
+				Return a list of the [PhysicsBody2D]s that intersect with this area.
 			</description>
 		</method>
 		<method name="get_priority" qualifiers="const">
@@ -5395,33 +5395,50 @@
 		</method>
 	</methods>
 	<members>
-		<member name="angular_damp" type="float" setter="set_angular_damp" getter="get_angular_damp" brief="">
+		<member name="angular_damp" type="float" setter="set_angular_damp" getter="get_angular_damp" brief="rate of spin loss">
+			The rate at which objects stop spinning in this area. Represents the amount of speed lost per second. If 1.0, physics bodies in the area stop rotating immediately. If 0.0, they never slow down. Does not incorporate external forces. The physics-update's rate affects 'angular_damp'.
 		</member>
-		<member name="audio_bus_name" type="String" setter="set_audio_bus" getter="get_audio_bus" brief="">
+		<member name="audio_bus_name" type="String" setter="set_audio_bus" getter="get_audio_bus" brief="name of audio bus">
+			The name of the Area2D's audio bus.
 		</member>
-		<member name="audio_bus_override" type="bool" setter="set_audio_bus_override" getter="is_overriding_audio_bus" brief="">
+		<member name="audio_bus_override" type="bool" setter="set_audio_bus_override" getter="is_overriding_audio_bus" brief="Whether to override audio bus">
+			If [code]true[/code], overrides the default audio bus with the Area2D's. Defaults to [code]false[/code].
 		</member>
-		<member name="collision_layer" type="int" setter="set_collision_layer" getter="get_collision_layer" brief="">
+		<member name="collision_layer" type="int" setter="set_collision_layer" getter="get_collision_layer" brief="others-collide-with-this layers">
+			The physics layer this Area2D 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 [method 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 layers that object A scans.
 		</member>
-		<member name="collision_mask" type="int" setter="set_collision_mask" getter="get_collision_mask" brief="">
+		<member name="collision_mask" type="int" setter="set_collision_mask" getter="get_collision_mask" brief="this-collides-with-others layers">
+			The physics layers this Area2D scans to determine collision detections.
 		</member>
-		<member name="gravity" type="float" setter="set_gravity" getter="get_gravity" brief="">
+		<member name="gravity" type="float" setter="set_gravity" getter="get_gravity" brief="internal gravity intensity">
+			The gravity intensity within the Area2D (ranges -1024 to 1024). 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 ([method set_gravity_vector]), or a calculated one (when using a center of gravity).
 		</member>
-		<member name="gravity_distance_scale" type="float" setter="set_gravity_distance_scale" getter="get_gravity_distance_scale" brief="">
+		<member name="gravity_distance_scale" type="float" setter="set_gravity_distance_scale" getter="get_gravity_distance_scale" brief="gravity drop rate">
+			The falloff factor for point gravity. The greater this value is, the faster the strength of gravity decreases with the square of distance.
 		</member>
-		<member name="gravity_point" type="bool" setter="set_gravity_is_point" getter="is_gravity_a_point" brief="">
+		<member name="gravity_point" type="bool" setter="set_gravity_is_point" getter="is_gravity_a_point" brief="is gravity a point?">
+			If [code]true[/code], calculates gravity from a particular point during a space override (see [method set_space_override_mode]). If a point, [Vector2] position is set with [method set_gravity_vector]. Defaults to [code]false[/code].
 		</member>
-		<member name="gravity_vec" type="Vector2" setter="set_gravity_vector" getter="get_gravity_vector" brief="">
+		<member name="gravity_vec" type="Vector2" setter="set_gravity_vector" getter="get_gravity_vector" brief="gravity non-normalized vector or center-point">
+			The gravitational direction/strength as a vector (not normalized). If gravity is a point (see [method is_gravity_a_point]), this will be the attraction center.
 		</member>
-		<member name="linear_damp" type="float" setter="set_linear_damp" getter="get_linear_damp" brief="">
+		<member name="linear_damp" type="float" setter="set_linear_damp" getter="get_linear_damp" brief="rate of movement loss">
+			The rate at which objects stop spinning in this area. Represents the amount of speed lost per second. If 1.0, physics bodies in the area stop rotating immediately. If 0.0, they never slow down. Does not incorporate external forces. The physics-update's rate affects 'angular_damp'.
 		</member>
-		<member name="monitorable" type="bool" setter="set_monitorable" getter="is_monitorable" brief="">
+		<member name="monitorable" type="bool" setter="set_monitorable" getter="is_monitorable" brief="others cannot detect this?">
+			If [code]true[/code], other monitoring areas can detect this Area2D (is it undetectable at the moment?). Defaults to [code]true[/code].
 		</member>
-		<member name="monitoring" type="bool" setter="set_monitoring" getter="is_monitoring" brief="">
+		<member name="monitoring" type="bool" setter="set_monitoring" getter="is_monitoring" brief="this cannot detect others?">
+			If [code]true[/code], this detects bodies/areas entering/exiting it (can it detect others at the moment?). Defaults to [code]true[/code].
 		</member>
-		<member name="priority" type="float" setter="set_priority" getter="get_priority" brief="">
+		<member name="priority" type="float" setter="set_priority" getter="get_priority" brief="(high) process before others (low)">
+			The processing order for this priority. Ranges from 0 to 128. Defaults to 0. Higher priorities are processed first.
 		</member>
-		<member name="space_override" type="int" setter="set_space_override_mode" getter="get_space_override_mode" brief="" enum="Area2D.SpaceOverride">
+		<member name="space_override" type="int" setter="set_space_override_mode" getter="get_space_override_mode" brief="how to override gravity/damping" enum="Area2D.SpaceOverride">
+			How to override gravity and damping calculations within this Area2D, if at all. Consult the SPACE_OVERRIDE_* constants for available options.
 		</member>
 	</members>
 	<signals>
@@ -5507,6 +5524,11 @@
 		</signal>
 	</signals>
 	<constants>
+		<constant name="SPACE_OVERRIDE_DISABLED" value="0" enum="Area2D.SpaceOverride">This area does not affect gravity/damp. These are areas that exist only to detect collisions and objects entering or exiting them.</constant>
+		<constant name="SPACE_OVERRIDE_COMBINE" value="1" enum="Area2D.SpaceOverride">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.</constant>
+		<constant name="SPACE_OVERRIDE_COMBINE_REPLACE" value="2" enum="Area2D.SpaceOverride">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.</constant>
+		<constant name="SPACE_OVERRIDE_REPLACE" value="3" enum="Area2D.SpaceOverride">This area replaces any gravity/damp, even the default one, and stops taking into account the rest of the areas.</constant>
+		<constant name="SPACE_OVERRIDE_REPLACE_COMBINE" value="4" enum="Area2D.SpaceOverride">This area replaces any gravity/damp calculated so far, but keeps calculating the rest of the areas, down to the default one.</constant>
 	</constants>
 </class>
 <class name="Array" category="Built-In Types">
diff --git a/scene/2d/area_2d.cpp b/scene/2d/area_2d.cpp
index 1124904963..9fc6c8d23a 100644
--- a/scene/2d/area_2d.cpp
+++ b/scene/2d/area_2d.cpp
@@ -596,7 +596,7 @@ void Area2D::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("_area_enter_tree", "id"), &Area2D::_area_enter_tree);
 	ClassDB::bind_method(D_METHOD("_area_exit_tree", "id"), &Area2D::_area_exit_tree);
 
-	ClassDB::bind_method(D_METHOD("set_space_override_mode", "enable"), &Area2D::set_space_override_mode);
+	ClassDB::bind_method(D_METHOD("set_space_override_mode", "space_override_mode"), &Area2D::set_space_override_mode);
 	ClassDB::bind_method(D_METHOD("get_space_override_mode"), &Area2D::get_space_override_mode);
 
 	ClassDB::bind_method(D_METHOD("set_gravity_is_point", "enable"), &Area2D::set_gravity_is_point);
@@ -680,6 +680,12 @@ void Area2D::_bind_methods() {
 	ADD_GROUP("Audio Bus", "audio_bus_");
 	ADD_PROPERTY(PropertyInfo(Variant::BOOL, "audio_bus_override"), "set_audio_bus_override", "is_overriding_audio_bus");
 	ADD_PROPERTY(PropertyInfo(Variant::STRING, "audio_bus_name", PROPERTY_HINT_ENUM, ""), "set_audio_bus", "get_audio_bus");
+
+	BIND_ENUM_CONSTANT(SPACE_OVERRIDE_DISABLED);
+	BIND_ENUM_CONSTANT(SPACE_OVERRIDE_COMBINE);
+	BIND_ENUM_CONSTANT(SPACE_OVERRIDE_COMBINE_REPLACE);
+	BIND_ENUM_CONSTANT(SPACE_OVERRIDE_REPLACE);
+	BIND_ENUM_CONSTANT(SPACE_OVERRIDE_REPLACE_COMBINE);
 }
 
 Area2D::Area2D()