diff --git a/tutorials/physics/files/using_area_2d.zip b/tutorials/physics/files/using_area_2d.zip new file mode 100644 index 000000000..f69bec2a8 Binary files /dev/null and b/tutorials/physics/files/using_area_2d.zip differ diff --git a/tutorials/physics/img/area2d_coin_nodes.png b/tutorials/physics/img/area2d_coin_nodes.png new file mode 100644 index 000000000..fd5a463f6 Binary files /dev/null and b/tutorials/physics/img/area2d_coin_nodes.png differ diff --git a/tutorials/physics/img/area2d_override.gif b/tutorials/physics/img/area2d_override.gif new file mode 100644 index 000000000..3125ea3da Binary files /dev/null and b/tutorials/physics/img/area2d_override.gif differ diff --git a/tutorials/physics/img/area2d_properties.png b/tutorials/physics/img/area2d_properties.png new file mode 100644 index 000000000..446cbbb48 Binary files /dev/null and b/tutorials/physics/img/area2d_properties.png differ diff --git a/tutorials/physics/index.rst b/tutorials/physics/index.rst index a2ac0b669..b1669b55a 100644 --- a/tutorials/physics/index.rst +++ b/tutorials/physics/index.rst @@ -7,6 +7,7 @@ Physics physics_introduction rigid_body + using_area_2d using_kinematic_body_2d ray-casting ragdoll_system diff --git a/tutorials/physics/using_area_2d.rst b/tutorials/physics/using_area_2d.rst new file mode 100644 index 000000000..5c1e2f612 --- /dev/null +++ b/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 ` 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 ` 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 `, 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 ` \ No newline at end of file