Added examples for collision layer masks (#3863)

Co-authored-by: Hugo Locurcio <[email protected]>
Co-authored-by: Balloonpopper <[email protected]>

tutorials/3d/fps_tutorial/part_five.rst

@@ -521,7 +521,7 @@ If ``grabbed_object`` is ``null``, we want to see if we can pick up a :ref:`Rigi
 We first get the direct space state from the current :ref:`World <class_World>`. This is so we can cast a ray entirely from code, instead of having to
 use a :ref:`Raycast <class_Raycast>` node.
 
-.. note:: see :ref:`Ray-casting <doc_ray-casting>` for more information on raycasting in Godot.
+.. note:: See :ref:`Ray-casting <doc_ray-casting>` for more information on raycasting in Godot.
 
 Then we get the center of the screen by dividing the current :ref:`Viewport <class_Viewport>` size in half. We then get the ray's origin point and end point using
 ``project_ray_origin`` and ``project_ray_normal`` from the camera. If you want to know more about how these functions work, see :ref:`Ray-casting <doc_ray-casting>`.
@@ -537,6 +537,8 @@ the :ref:`RigidBody <class_RigidBody>` we collided with to ``MODE_STATIC`` so it
 Finally, we set the grabbed :ref:`RigidBody <class_RigidBody>`'s collision layer and collision mask to ``0``.
 This will make the grabbed :ref:`RigidBody <class_RigidBody>` have no collision layer or mask, which means it will not be able to collide with anything as long as we are holding it.
 
+.. note:: See :ref:`doc_physics_introduction_collision_layer_code_example` for more information on Godot collision masks.
+
 ______
 
 If ``grabbed_object`` is not ``null``, then we need to throw the :ref:`RigidBody <class_RigidBody>` the player is holding.

tutorials/physics/physics_introduction.rst

@@ -95,6 +95,8 @@ it will typically be equal to ``0.01666...`` (but not always, see below).
     physics calculations, so that the game behaves correctly if you change the
     physics update rate or if the player's device can't keep up.
 
+.. _doc_physics_introduction_collision_layers_and_masks:
+
 Collision layers and masks
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -123,7 +125,7 @@ be assigned in Project Settings -> Layer Names.
 
 .. image:: img/physics_layer_names.png
 
-**Example:**
+**GUI example:**
 
 You have four node types in your game: Walls, Player, Enemy, and Coin. Both
 Player and Enemy should collide with Walls. The Player node should detect
@@ -138,6 +140,34 @@ interact with. For example, the Player's settings would look like this:
 .. image:: img/player_collision_layers.png
 .. image:: img/player_collision_mask.png
 
+**Code example:**
+
+In function calls, layers are specified as a bitmask. Where a function enables
+all layers by default, the layer mask will be given as ``0x7fffffff``. Your code
+can use binary, hexadecimal, or decimal notation for layer masks, depending
+on your preference.
+
+The code equivalent of the above example where layers 1, 3 and 4 were enabled
+would be as follows:
+
+.. _doc_physics_introduction_collision_layer_code_example:
+
+    # Example: Setting mask value for enabling layers 1, 3 and 4
+
+    # Binary - set the bit corresponding to the layers you want to enable (1, 3, and 4) to 1, set all other bits to 0.
+    # Note: Layer 20 is the first bit, layer 1 is the last. The mask for layers 4,3 and 1 is therefore
+    0b00000000000000001101
+    # (This can be shortened to 0b1101)
+
+    # Hexadecimal equivalent (1101 binary converted to hexadecimal)
+    0x000d
+    # (This value can be shortened to 0xd)
+
+    # Decimal - Add the results of 2 to the power of (layer be enabled-1).
+    # (2^(1-1)) + (2^(3-1)) + (2^(4-1)) = 1 + 4 + 8 = 13
+    pow(2, 1) + pow(2, 3) + pow(2, 4)
+
+
 Area2D
 ------
 

tutorials/physics/ragdoll_system.rst

@@ -83,4 +83,4 @@ Make sure to set up your collision layers and masks properly so the ``KinematicB
 
 .. image:: img/ragdoll_layer.png
 
-For more information, read :ref:`doc_physics_introduction`
+For more information, read :ref:`doc_physics_introduction_collision_layers_and_masks`.

tutorials/physics/ray-casting.rst

@@ -221,6 +221,7 @@ member variable:
         }
     }
 
+See :ref:`doc_physics_introduction_collision_layer_code_example` for details on how to set the collision mask.
 
 3D ray casting from screen
 --------------------------