From c40d74e19b4495dc365e3daa2bca59eb53774a06 Mon Sep 17 00:00:00 2001 From: balloonpopper <5151242+balloonpopper@users.noreply.github.com> Date: Mon, 3 Aug 2020 21:47:40 +1000 Subject: [PATCH] Added examples for collision layer masks (#3863) Co-authored-by: Hugo Locurcio Co-authored-by: Balloonpopper --- tutorials/3d/fps_tutorial/part_five.rst | 4 ++- tutorials/physics/physics_introduction.rst | 32 +++++++++++++++++++++- tutorials/physics/ragdoll_system.rst | 2 +- tutorials/physics/ray-casting.rst | 1 + 4 files changed, 36 insertions(+), 3 deletions(-) diff --git a/tutorials/3d/fps_tutorial/part_five.rst b/tutorials/3d/fps_tutorial/part_five.rst index 0736be8ed..f6cabdbca 100644 --- a/tutorials/3d/fps_tutorial/part_five.rst +++ b/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 `. This is so we can cast a ray entirely from code, instead of having to use a :ref:`Raycast ` node. -.. note:: see :ref:`Ray-casting ` for more information on raycasting in Godot. +.. note:: See :ref:`Ray-casting ` for more information on raycasting in Godot. Then we get the center of the screen by dividing the current :ref:`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 `. @@ -537,6 +537,8 @@ the :ref:`RigidBody ` we collided with to ``MODE_STATIC`` so it Finally, we set the grabbed :ref:`RigidBody `'s collision layer and collision mask to ``0``. This will make the grabbed :ref:`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 ` the player is holding. diff --git a/tutorials/physics/physics_introduction.rst b/tutorials/physics/physics_introduction.rst index 9dde1a62e..dd09c472f 100644 --- a/tutorials/physics/physics_introduction.rst +++ b/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 ------ diff --git a/tutorials/physics/ragdoll_system.rst b/tutorials/physics/ragdoll_system.rst index 5ef3120e1..f74afae3f 100644 --- a/tutorials/physics/ragdoll_system.rst +++ b/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`. diff --git a/tutorials/physics/ray-casting.rst b/tutorials/physics/ray-casting.rst index 263d58957..7ce1e24c0 100644 --- a/tutorials/physics/ray-casting.rst +++ b/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 --------------------------