Add an introduction page for XR tools

tutorials/xr/basic_xr_locomotion.rst

@@ -3,5 +3,87 @@
 Basic XR Locomotion
 ===================
 
-This is just a placeholder
+For basic locomotion we're going to continue using our Godot XR Tools library. The library contains both basic movement features as more advanced features.
 
+Adding our player body
+----------------------
+
+The first step we need to do is to add a helper node to our :ref:`XROrigin3D <class_xrorigin3d>` node.
+Because XR supports roomscale tracking you can't simply add your XR setup to a :ref:`CharacterBody3D <class_characterbody3d>` node and expect things to work.
+You will run into trouble when the user moves around their physical space and is no longer standing in the center of their room.
+Godot XR Tools embeds the needed logic into a helper node called ``PlayerBody``.
+
+Select your :ref:`XROrigin3D <class_xrorigin3d>` node and click on the ``instantiate Child Scene`` button to add a child scene.
+Select ``addons/godot-xr-tools/player/player_body.tscn`` and add this node.
+
+Adding a floor
+--------------
+
+This node governs the in game movement of your character and will immediately react to gravity.
+So to prevent our player from infinitely falling down we'll quickly add a floor to our scene.
+
+We start by adding a :ref:`StaticBody3D <class_staticbody3d>` node to our root node and we rename this to ``Floor``.
+We add a :ref:`MeshInstance3D <class_meshinstance3d>` node as a child node for our ``Floor``. 
+Then create a new :ref:`PlaneMesh <class_planemesh>` as it's mesh.
+For now we set the size of the mesh to 100 x 100 meters.
+Next we add a :ref:`CollisionShape3D <class_collisionshape3d>` node as a child node for our ``Floor``.
+Then create a ``BoxShape`` as our shape.
+We set the size of this box shape to 100 x 1 x 100 meters.
+We also need to move our collision shape down by 0.5 meters so the top of our box is flush with the floor.
+
+To make it easier to see that we're actually moving around our world, a white floor isn't going to do it.
+For this we add a material to our PlaneMesh and set the albedo to a grid texture we've created with `Wahooneys excellent free texture generator <https://wahooney.itch.io/texture-grid-generator>`_. 
+
+.. image:: img/godot_xr_tools_floor.webp
+
+Direct movement
+---------------
+
+We're going to start adding some basic direct movement to our setup.
+This allows the user to move through the virtual world using joystick input.
+
+.. note::
+  It is important to note that moving through the virtual world while the player is standing still in the real world, can be nausea inducing especially for players who are new to VR.
+  The default settings on our movement functions are fairly conservative.
+  We advise you to stick to these defaults but offer features in game to enable less comfortable settings for more experienced users who are used to playing VR games.
+
+We want to enable this on the right hand controller.
+We do this by adding a subscene to the right hand :ref:`XRController3D <class_xrcontroller3d>` node.
+Select ``addons/godot-xr-tools/functions/movement_direct.tscn`` as the scene to add.
+
+This function adds forward and backwards movement to the player by using the joystick on the right hand controller.
+It has an option to also add left/right strafe but by default this is disabled.
+
+Instead, we are going to add the ability for the player to also turn with this joystick.
+We will add another subscene to our controller node, select ``addons/godot-xr-tools/functions/movement_turn.tscn`` for this.
+
+The turn system by default uses a snap turn approach.
+This means that turning happens in steps.
+This may seem jarring however it is a tried and tested method of combating motion sickness.
+You can easily switch to a mode that offers smooth turning by changing the ``mode`` property on the turn node.
+
+If you run your game at this point in time you will find that you can move through the world freely using the right hand joystick.
+
+Teleport
+--------
+
+An alternative to direct movement that some users find more pleasant is the ability to teleport to another location within your game world.
+Godot XR Tools supports this through the teleport function and we will be adding this to our left hand controller.
+
+Add a new child scene to your left hand :ref:`XRController3D <class_xrcontroller3d>` node by selecting the ``addons/godot-xr-tools/functions/function_teleport.tscn`` scene.
+
+With this scene added the player will be able to teleport around the world by pressing the trigger on the left hand controller, pointing where they want to go, and then releasing the trigger.
+The player can also adjust the orientation by using the left hand controllers joystick.
+
+If you've followed all instructions correctly your scene should now look something like this:
+
+.. image:: img/godot_xr_tools_basic_movement.webp
+
+More advanced movement features
+-------------------------------
+
+Godot XR Tools adds many more movement features such as gliding, a grapple hook implementation, a jetpack, climbing mechanics, etc.
+
+Most work similarly to the basic movement features we've handled so far, simply add the relevant subscene from the plugin to the controller that implements it. 
+
+We'll look at some of these in more detail later on in this tutorial where additional setup is required (such as climbing) but for others please look at Godot XR Tools own help pages for details.

tutorials/xr/index.rst

@@ -10,6 +10,7 @@ Basic Tutorial
 
    setting_up_xr
    deploying_to_android
+   introducing_xr_tools
    basic_xr_locomotion
 
 Advanced topics

tutorials/xr/introducing_xr_tools.rst

@@ -0,0 +1,78 @@
+.. _doc_introducing_xr_tools:
+
+Introducing XR tools
+====================
+
+Out of the box Godot gives you all the basic support to setup an XR project.
+XR specific game mechanics however need to be implemented on top of this foundation.
+While Godot makes this relatively easy this can still be a daunting task.
+
+For this reason Godot has developed a toolkit called `Godot XR Tools <https://github/GodotVR/godot-xr-tools>`_ that implements many of the basic mechanics found in XR games, from locomotion to object interaction to UI interaction. 
+
+This toolkit is designed to work with both OpenXR and WebXR runtimes.
+We'll be using this as a base for our documentation here.
+It helps developers hit the ground running but for more specific use cases building your own logic is just as valid.
+In that case XR tools can help in providing inspiration.
+
+.. note::
+  The current stable release of Godot XR Tools available on the Asset Library is the version for Godot 3.
+  The port of Godot XR Tools for Godot 4 is available for download from the github website.
+  We will walk through the step of downloading and installing it here.
+  We will update the documentation once Godot XR Tools becomes available for Godot 4 through the asset library.
+
+Installing XR Tools
+-------------------
+
+Continuing on from our project we started in :ref:`doc_setting_up_xr` we want to add in the Godot XR Tools library.
+This can be downloaded from the `Godot XR Tools releases page <https://github.com/GodotVR/godot-xr-tools/releases>`_.
+Simply find the latest pre-release for Godot 4 and then under assets download the ``godot-xr-tools.zip`` file.
+
+Once downloaded unzip the file.
+You will notice the files are held within a ``godot-xr-tools`` subfolder.
+Inside of this folder you will find an ``addons`` folder.
+It is this folder that you want to copy in its entirety to your Godot project folder, your project should now look something like this:
+
+.. image:: img/godot_xr_tools_root_folder.webp
+
+Now open up your project in Godot, if you haven't already, and give it a minute or so to import all the resources of the plugin.
+
+Next open the ``Project`` menu and select ``Project Settings..``.
+Now go to the ``Plugins`` tab and enable the plugin.
+
+.. image:: img/godot_xr_tools_enable.webp
+
+Basic hands
+-----------
+
+Just to get a feel of things we're going to add a few standard components that dress up our scene starting with hands for our player.
+
+OpenXR supports full hand tracking however there currently are significant differences in capabilities between the different XR Runtimes.
+
+As a reliable alternative Godot XR Tools comes with a number of rigged hand scenes that react on trigger and grip inputs of your controller.
+These hands come in low and high poly versions, come in a few configurations, a number of animation files to control finger positions and a number of different textures.
+
+In your scene tree select your left hand :ref:`XRController3D <class_xrcontroller3d>` node.
+Now click on the ``instantiate Child Scene`` button to add a child scene.
+And select ``addons/godot-xr-tools/hands/scenes/lowpoly/left_hand_low.tscn``.
+
+As you can see from the path of this scene, low poly models are in the ``lowpoly`` subfolder while high poly models are in the ``highpoly`` subfolder.
+You will want to use the low poly versions if you plan to release your game on mobile devices.
+
+The default hand we chose is just a hand. The other options are:
+
+  * tac_glove - the hand is wearing a glove with fingers exposed
+  * full_glove - the hand is wearing a glove that covers the entire hand
+
+Finally each hand comes in a ``physics`` version.
+This exposes all the bones.
+We'll look at how that can be used in another tutorial.
+
+We repeat the same for the right hand.
+
+.. image:: img/xr_tools_basic_hands.webp
+
+More information
+----------------
+
+We'll continue with adding features to our tutorial project using Godot XR tools in the next couple of pages.
+More detailed information about the toolkit can be found `on the toolkits help pages <https://godotvr.github.io/godot-xr-tools/>`_.