Using Area2D tutorial

tutorials/physics/index.rst

@@ -7,6 +7,7 @@ Physics
 
    physics_introduction
    rigid_body
+   using_area_2d
    using_kinematic_body_2d
    ray-casting
    ragdoll_system

tutorials/physics/using_area_2d.rst

@@ -0,0 +1,140 @@
+.. _doc_using_area_2d:
+
+Using Area2D
+============
+
+Introduction
+------------
+
+Godot offers a number of collision objects to provide both collision detection
+and response. Trying to decide which one to use for your project can be confusing.
+You can avoid problems and simplify development if you understand how each of them
+works and what their pros and cons are. In this tutorial, we'll look at the
+:ref:`Area2D <class_Area2D>` node and show some examples of how it can be used.
+
+.. note:: This document assumes you're familiar with Godot's various physics
+          bodies. Please read :ref:`doc_physics_introduction` first.
+
+What is an area?
+----------------
+
+An Area2D defines a region of 2D space. In this space you can detect other
+:ref:`CollisionObject2D <class_CollisionObject2D>` nodes overlapping, entering,
+and exiting. Areas also allow for overriding local physics properties. We'll
+explore each of these functions below.
+
+Area properties
+---------------
+
+Areas have many properties you can use to customize their behavior.
+
+.. image:: img/area2d_properties.png
+
+The first eight properties are used to configure the area's physics override
+behavior. We'll look at how to use those in the section below.
+
+*Monitoring* and *Monitorable* are used to enable and disable the area.
+
+The "Collision" section is where you configure the area's collision layer(s)
+and mask(s).
+
+The "Audio Bus" section allows you to override audio in the area, for example to
+apply an audio effect when the player moves through.
+
+Note that Area2D extends :ref:`CollisionObject2D <class_CollisionObject2D>`, so it
+also provides properties inherited from that class, such as ``input_pickable``.
+
+Overlap detection
+-----------------
+
+Perhaps the most common use of Area2D nodes is for contact and overlap detection.
+When you need to know that two objects have touched, but don't need physical
+collision, you can use an area to notify you of the contact.
+
+For example, let's say we're making a coin for the player to pick up. The coin is
+not a solid object - the player can't stand on it or push it - we just want it
+to disappear when the player touches it.
+
+Here's the node setup for the coin:
+
+.. image:: img/area2d_coin_nodes.png
+
+To detect the overlap, we'll connect the appropriate signal on the Area2d. Which
+signal to use depends on the player's node type. If the player is another area,
+use ``area_entered``. However, let's assume our player is a ``KinematicBody2D``
+(and therefore a ``CollisionObject2D`` type), so we'll connect the
+``body_entered`` signal.
+
+.. note:: If you're not familiar with using signals, see :ref:`doc_signals` for
+          an introduction.
+
+.. tabs::
+ .. code-tab:: gdscript GDScript
+
+    extends Area2D
+
+    func _on_Coin_body_entered(body):
+        queue_free()
+
+ .. code-tab:: csharp
+
+    public class Coin : Area2D
+    {
+
+        public void OnCoinBodyEntered(PhysicsBody2D body)
+        {
+            QueueFree();
+        }
+    }
+
+Now our player can collect the coins!
+
+Some other usage examples:
+
+- Areas are great for bullets and other projectiles that hit and deal damage, but don't need any other physics such as bouncing.
+- Use a large circular area around an enemy to define its "detect" radius. When the player is outside the area, the enemy can't "see" it.
+- "Security cameras" - In a large level with multiple cameras, attach areas to each camera and activate them when the player enters.
+
+See the :ref:`doc_your_first_game` for an example of using Area2D in a game.
+
+Area influence
+--------------
+
+The second major use for area nodes is to alter physics. By default, the area
+won't do this, but you can enable this with the *Space Override* property. When
+areas overlap, they are processed in *Priority* order (higher priority areas are
+processed first). There are four options for override:
+
+- *Combine* - The area adds its values to what has been calculated so far.
+- *Replace* - The area replaces physics properties, and lower priority areas are ignored.
+- *Combine-Replace* - The area adds its gravity/damping values to whatever has been calculated so far (in priority order), ignoring any lower priority areas.
+- *Replace-Combine* - The area replaces any gravity/damping calculated so far, but keeps calculating the rest of the areas.
+
+Using these properties, you can create very complex behavior with multiple
+overlapping areas.
+
+The physics properties that can be overridden are:
+
+- *Gravity* - Gravity's strength inside the area.
+- *Gravity Vec* - Gravity's direction. This vector does not need to be normalized.
+- *Linear Damp* - How quickly objects stop moving - linear velocity lost per second.
+- *Angular Damp* - How quickly objects stop spinning - angular velocity lost per second.
+
+Point gravity
+~~~~~~~~~~~~~
+
+The *Gravity Point* property allows you to create an "attractor". Gravity in the
+area will be calculated towards a point, given by the *Gravity Vec* property.
+Values are relative to the Area2D, so for example using ``(0, 0)`` will attract
+objects to the center of the area.
+
+Examples
+~~~~~~~~
+
+The example project attached below has three areas demonstrating physics
+override.
+
+.. image:: img/area2d_override.gif
+
+You can download this project here:
+:download:`using_area_2d.zip <files/using_area_2d.zip>`