140 lines
5.1 KiB
ReStructuredText
140 lines
5.1 KiB
ReStructuredText
.. _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_2d_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>`
|