Merge branch 'master' into 3.2

_extensions/godot_descriptions.py

@@ -78,6 +78,9 @@ class DescriptionGenerator:
         # Replace multiple spaces with single spaces
         desc = re.sub("\\s+", " ", desc)
 
+        # Escape double quotes for HTML
+        desc = re.sub('"', """, desc)
+
         return desc
 
     def create_description(self, cutoff_suffix="..."):

_static/js/custom.js

@@ -207,7 +207,7 @@ $(document).ready(() => {
   // a way to add scripts with a "module" attribute.
   const instantPageScript = document.createElement('script');
   instantPageScript.toggleAttribute('module');
-  /*! instant.page v3.0.0 - (C) 2019 Alexandre Dieulot - https://instant.page/license */
+  /*! instant.page v5.1.0 - (C) 2019-2020 Alexandre Dieulot - https://instant.page/license */
-  instantPageScript.innerText = 'let t,e;const n=new Set,o=document.createElement("link"),s=o.relList&&o.relList.supports&&o.relList.supports("prefetch")&&window.IntersectionObserver&&"isIntersecting"in IntersectionObserverEntry.prototype,i="instantAllowQueryString"in document.body.dataset,r="instantAllowExternalLinks"in document.body.dataset,a="instantWhitelist"in document.body.dataset;let c=65,d=!1,l=!1,u=!1;if("instantIntensity"in document.body.dataset){const t=document.body.dataset.instantIntensity;if("mousedown"==t.substr(0,"mousedown".length))d=!0,"mousedown-only"==t&&(l=!0);else if("viewport"==t.substr(0,"viewport".length))navigator.connection&&(navigator.connection.saveData||navigator.connection.effectiveType.includes("2g"))||("viewport"==t?document.documentElement.clientWidth*document.documentElement.clientHeight<45e4&&(u=!0):"viewport-all"==t&&(u=!0));else{const e=parseInt(t);isNaN(e)||(c=e)}}if(s){const n={capture:!0,passive:!0};if(l||document.addEventListener("touchstart",function(t){e=performance.now();const n=t.target.closest("a");if(!f(n))return;h(n.href)},n),d?document.addEventListener("mousedown",function(t){const e=t.target.closest("a");if(!f(e))return;h(e.href)},n):document.addEventListener("mouseover",function(n){if(performance.now()-e<1100)return;const o=n.target.closest("a");if(!f(o))return;o.addEventListener("mouseout",m,{passive:!0}),t=setTimeout(()=>{h(o.href),t=void 0},c)},n),u){let t;(t=window.requestIdleCallback?t=>{requestIdleCallback(t,{timeout:1500})}:t=>{t()})(()=>{const t=new IntersectionObserver(e=>{e.forEach(e=>{if(e.isIntersecting){const n=e.target;t.unobserve(n),h(n.href)}})});document.querySelectorAll("a").forEach(e=>{f(e)&&t.observe(e)})})}}function m(e){e.relatedTarget&&e.target.closest("a")==e.relatedTarget.closest("a")||t&&(clearTimeout(t),t=void 0)}function f(t){if(t&&t.href&&(!a||"instant"in t.dataset)&&(r||t.origin==location.origin||"instant"in t.dataset)&&["http:","https:"].includes(t.protocol)&&("http:"!=t.protocol||"https:"!=location.protocol)&&(i||!t.search||"instant"in t.dataset)&&!(t.hash&&t.pathname+t.search==location.pathname+location.search||"noInstant"in t.dataset))return!0}function h(t){if(n.has(t))return;const e=document.createElement("link");e.rel="prefetch",e.href=t,document.head.appendChild(e),n.add(t)}';
+  instantPageScript.innerText = 'let t,e;const n=new Set,o=document.createElement("link"),i=o.relList&&o.relList.supports&&o.relList.supports("prefetch")&&window.IntersectionObserver&&"isIntersecting"in IntersectionObserverEntry.prototype,s="instantAllowQueryString"in document.body.dataset,a="instantAllowExternalLinks"in document.body.dataset,r="instantWhitelist"in document.body.dataset,c="instantMousedownShortcut"in document.body.dataset,d=1111;let l=65,u=!1,f=!1,m=!1;if("instantIntensity"in document.body.dataset){const t=document.body.dataset.instantIntensity;if("mousedown"==t.substr(0,"mousedown".length))u=!0,"mousedown-only"==t&&(f=!0);else if("viewport"==t.substr(0,"viewport".length))navigator.connection&&(navigator.connection.saveData||navigator.connection.effectiveType&&navigator.connection.effectiveType.includes("2g"))||("viewport"==t?document.documentElement.clientWidth*document.documentElement.clientHeight<45e4&&(m=!0):"viewport-all"==t&&(m=!0));else{const e=parseInt(t);isNaN(e)||(l=e)}}if(i){const n={capture:!0,passive:!0};if(f||document.addEventListener("touchstart",function(t){e=performance.now();const n=t.target.closest("a");if(!h(n))return;v(n.href)},n),u?c||document.addEventListener("mousedown",function(t){const e=t.target.closest("a");if(!h(e))return;v(e.href)},n):document.addEventListener("mouseover",function(n){if(performance.now()-e<d)return;const o=n.target.closest("a");if(!h(o))return;o.addEventListener("mouseout",p,{passive:!0}),t=setTimeout(()=>{v(o.href),t=void 0},l)},n),c&&document.addEventListener("mousedown",function(t){if(performance.now()-e<d)return;const n=t.target.closest("a");if(t.which>1||t.metaKey||t.ctrlKey)return;if(!n)return;n.addEventListener("click",function(t){1337!=t.detail&&t.preventDefault()},{capture:!0,passive:!1,once:!0});const o=new MouseEvent("click",{view:window,bubbles:!0,cancelable:!1,detail:1337});n.dispatchEvent(o)},n),m){let t;(t=window.requestIdleCallback?t=>{requestIdleCallback(t,{timeout:1500})}:t=>{t()})(()=>{const t=new IntersectionObserver(e=>{e.forEach(e=>{if(e.isIntersecting){const n=e.target;t.unobserve(n),v(n.href)}})});document.querySelectorAll("a").forEach(e=>{h(e)&&t.observe(e)})})}}function p(e){e.relatedTarget&&e.target.closest("a")==e.relatedTarget.closest("a")||t&&(clearTimeout(t),t=void 0)}function h(t){if(t&&t.href&&(!r||"instant"in t.dataset)&&(a||t.origin==location.origin||"instant"in t.dataset)&&["http:","https:"].includes(t.protocol)&&("http:"!=t.protocol||"https:"!=location.protocol)&&(s||!t.search||"instant"in t.dataset)&&!(t.hash&&t.pathname+t.search==location.pathname+location.search||"noInstant"in t.dataset))return!0}function v(t){if(n.has(t))return;const e=document.createElement("link");e.rel="prefetch",e.href=t,document.head.appendChild(e),n.add(t)}';
   document.head.appendChild(instantPageScript);
 });

about/index.rst

@@ -7,6 +7,7 @@ About
 
    introduction
    faq
+   troubleshooting
    list_of_features
    docs_changelog
    release_policy

about/troubleshooting.rst

@@ -0,0 +1,85 @@
+.. _doc_troubleshooting:
+
+Troubleshooting
+===============
+
+This page lists common issues encountered when using Godot and possible solutions.
+
+Everything I do in the editor or project manager appears delayed by one frame.
+------------------------------------------------------------------------------
+
+This is a `known bug <https://github.com/godotengine/godot/issues/23069>`__ on
+Intel graphics drivers on Windows. Updating to the latest graphics driver
+version *provided by Intel* should fix the issue.
+
+You should use the graphics driver provided by Intel rather than the one
+provided by your desktop or laptop's manufacturer because their version is often
+outdated.
+
+The grid disappears and meshes turn black when I rotate the 3D camera in the editor.
+------------------------------------------------------------------------------------
+
+This is a `known bug <https://github.com/godotengine/godot/issues/30330>`__ on
+Intel graphics drivers on Windows.
+
+The only workaround, for now, is to switch to the GLES2 renderer. You can switch
+the renderer in the top-right corner of the editor or the Project Settings.
+
+If you use a computer allowing you to switch your graphics card, like NVIDIA
+Optimus, you can use the dedicated graphics card to run Godot.
+
+The editor or project takes a very long time to start.
+------------------------------------------------------
+
+This is a `known bug <https://github.com/godotengine/godot/issues/20566>`__ on
+Windows when you have specific USB peripherals connected. In particular,
+Corsair's iCUE software seems to cause the bug. Try updating your USB
+peripherals' drivers to their latest version. If the bug persists, you need to
+disconnect the faulty peripherals before opening the editor. You can then
+connect the peripheral again.
+
+The Godot editor appears frozen after clicking the system console.
+------------------------------------------------------------------
+
+When running Godot on Windows with the system console enabled, you can
+accidentally enable *selection mode* by clicking inside the command window. This
+Windows-specific behavior pauses the application to let you select text inside
+the system console. Godot cannot override this system-specific behavior.
+
+To solve this, select the system console window and press Enter to leave
+selection mode.
+
+The project window appears blurry, unlike the editor.
+-----------------------------------------------------
+
+Unlike the editor, the project isn't marked as DPI-aware by default. This is
+done to improve performance, especially on integrated graphics, where rendering
+3D scenes in hiDPI is slow.
+
+To resolve this, open **Project > Project Settings** and enable **Display >
+Window > Dpi > Allow Hidpi**. On top of that, make sure your project is
+configured to support :ref:`multiple resolutions <doc_multiple_resolutions>`.
+
+The project window doesn't appear centered when I run the project.
+------------------------------------------------------------------
+
+This is a `known bug <https://github.com/godotengine/godot/issues/13017>`__. To
+resolve this, open **Project > Project Settings** and enable **Display > Window
+> Dpi > Allow Hidpi**. On top of that, make sure your project is configured to
+support :ref:`multiple resolutions <doc_multiple_resolutions>`.
+
+The project works when run from the editor, but fails to load some files when running from an exported copy.
+------------------------------------------------------------------------------------------------------------
+
+This is usually caused by forgetting to specify a filter for non-resource files
+in the Export dialog. By default, Godot will only include actual *resources*
+into the PCK file. Some files commonly used, such as JSON files, are not
+considered resources. For example, if you load ``test.json`` in the exported
+project, you need to specify ``*.json`` in the non-resource export filter. See
+:ref:`doc_exporting_projects_export_mode` for more information.
+
+On Windows, this can also be due to :ref:`case sensitivity
+<doc_project_organization_case_sensitivity>` issues. If you reference a resource
+in your script with a different case than on the filesystem, loading will fail
+once you export the project. This is because the virtual PCK filesystem is
+case-sensitive, while Windows's filesystem is case-insensitive by default.

community/contributing/best_practices_for_engine_contributors.rst

@@ -46,20 +46,19 @@ as source and binary and requires maintenance once it exists. Avoiding the
 addition of anything unnecessary is always considered a good practice in
 software development.
 
-#2: The problem has to exist
+#2: To solve the problem, it has to exist in the first place
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-This is a variation of the previous practice. I believe most developers agree
+This is a variation of the previous practice. Adding anything unnecessary is not
-that adding anything unnecessary is not a good idea, but what constitutes what
+a good idea, but what constitutes what is necessary and what isn't?
-is necessary and what isn't?
 
 .. image:: img/best_practices2.png
 
-The answer to this question is that the problem needs to *exist*. It must not be
+The answer to this question is that the problem needs to *exist* before it can
-speculation or a belief. The user must be using the software as intended to
+be actually solved. It must not be speculation or a belief. The user must be
-create something they *need*. In this process, the user may stumble into a
+using the software as intended to create something they *need*. In this process,
-problem that requires a solution in order to continue, or in order to achieve
+the user may stumble into a problem that requires a solution to proceed, or in
-greater productivity. In this case, *a solution is needed*.
+order to achieve greater productivity. In this case, *a solution is needed*.
 
 Believing that problems may arise in the future and that the software needs to
 be ready to solve them by the time they appear is called *"Future proofing"* and
@@ -68,10 +67,10 @@ its characterized by lines of thought such as:
 - I think it would be useful for users to...
 - I think users will eventually need to...
 
-This is generally considered a bad habit, because trying to solve problems that
+This is generally considered a bad habit because trying to solve problems that
-*don't actually exist* in the present will very often lead to code that will be
+*don't actually exist* in the present will often lead to code that will be
-written but never used, or to code that is considerably more complex to use and
+written but never used, or that is considerably more complex to use and maintain
-maintain than it needs to be.
+than it needs to be.
 
 #3: The problem has to be complex or frequent
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

conf.py

@@ -52,11 +52,6 @@ version = os.getenv("READTHEDOCS_VERSION", "3.2")
 # The full version, including alpha/beta/rc tags
 release = version
 
-# Set this True when the `latest` branch is significantly incompatible with the
-# current `stable` branch, which can lead to confusion for users that land on
-# `latest` instead of `stable`.
-in_dev = False
-
 # Parse Sphinx tags passed from RTD via environment
 env_tags = os.getenv("SPHINX_TAGS")
 if env_tags is not None:
@@ -235,22 +230,6 @@ def godot_get_image_filename_for_language(filename, env):
 
 sphinx.util.i18n.get_image_filename_for_language = godot_get_image_filename_for_language
 
-# Read the Docs adds a note at the top of the page when reading documentation
-# for an old stable version, but not when reading the latest unstable version.
-# We want to add a warning note as the `latest` documentation may not always
-# apply to the current `stable` version.
-if in_dev:
-    rst_prolog = """
-.. attention::
-    You are reading the ``latest`` (unstable) version of this documentation,
-    which may document features not available or compatible with Godot 3.2.x.
-
-    See `this page <https://docs.godotengine.org/{locale}/stable/>`__
-    for the stable version of this documentation.
-""".format(
-        locale=language,
-    )
-
 # Couldn't find a way to retrieve variables nor do advanced string
 # concat from reST, so had to hardcode this in the "epilog" added to
 # all pages. This is used in index.rst to display the Weblate badge.

development/cpp/core_types.rst

@@ -12,7 +12,7 @@ understanding.
 Definitions
 -----------
 
-Godot uses the standard C98 datatypes, such as ``uint8_t``,
+Godot uses the standard C99 datatypes, such as ``uint8_t``,
 ``uint32_t``, ``int64_t``, etc. which are nowadays supported by every
 compiler. Reinventing the wheel for those is not fun, as it makes code
 more difficult to read.

getting_started/step_by_step/your_first_game.rst

@@ -61,7 +61,7 @@ Dock in the lower left corner:
 Player scene
 ------------
 
-The first scene we will make defines the ``Player`` object. One of the benefits
+The first scene will define the ``Player`` object. One of the benefits
 of creating a separate Player scene is that we can test it separately, even
 before we've created other parts of the game.
 
@@ -669,7 +669,8 @@ Main scene
 ----------
 
 Now it's time to bring it all together. Create a new scene and add a
-:ref:`Node <class_Node>` named ``Main``. Click the "Instance" button and select your
+:ref:`Node <class_Node>` named ``Main``. Ensure you create a Node, **not** a
+Node2D. Click the "Instance" button and select your
 saved ``Player.tscn``.
 
 .. image:: img/instance_scene.png
@@ -898,11 +899,11 @@ Note that a new instance must be added to the scene using ``add_child()``.
         mobInstance.Position = mobSpawnLocation.Position;
 
         // Add some randomness to the direction.
-        direction += GD.RandRange(-Mathf.Pi / 4, Mathf.Pi / 4);
+        direction += RandRange(-Mathf.Pi / 4, Mathf.Pi / 4);
         mobInstance.Rotation = direction;
 
         // Choose the velocity.
-        mobInstance.LinearVelocity = new Vector2(GD.RandRange(150f, 250f), 0).Rotated(direction);
+        mobInstance.LinearVelocity = new Vector2(RandRange(150f, 250f), 0).Rotated(direction);
     }
 
 .. important:: Why ``PI``? In functions requiring angles, GDScript uses *radians*,

getting_started/workflow/assets/importing_scenes.rst

@@ -360,6 +360,8 @@ In inherited scenes, the only limitations for modifications are:
 
 Other than that, everything is allowed!
 
+.. _doc_importing_scenes_import_hints:
+
 Import hints
 ------------
 
@@ -433,6 +435,11 @@ reliability.
     on collision empties and set some distinct color for them in Blender's
     **User Preferences > Themes > 3D View > Empty**.
 
+.. seealso::
+
+    See :ref:`doc_collision_shapes_3d` for a comprehensive overview of collision
+    shapes.
+
 Create navigation (-navmesh)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

getting_started/workflow/best_practices/godot_interfaces.rst

@@ -329,7 +329,7 @@ accesses:
       child.set_visible(false)
 
       # Dynamic lookup, checks for method existence first.
-      if child.has("set_visible"):
+      if child.has_method("set_visible"):
           child.set_visible(false)
 
       # Cast check, followed by dynamic lookup
@@ -344,7 +344,7 @@ accesses:
       # If one does not wish to fail these checks without notifying users, one
       # can use an assert instead. These will trigger runtime errors
       # immediately if not true.
-      assert(child.has("set_visible"))
+      assert(child.has_method("set_visible"))
       assert(child.is_in_group("offer"))
       assert(child is CanvasItem)
 

getting_started/workflow/export/exporting_projects.rst

@@ -101,6 +101,8 @@ option in the editor:
 
 .. image:: img/exptemp.png
 
+.. _doc_exporting_projects_export_mode:
+
 Export mode
 ~~~~~~~~~~~
 

getting_started/workflow/project_setup/project_organization.rst

@@ -90,6 +90,8 @@ using the ``load()`` and ``preload()`` methods.
 Ignoring a folder will also automatically hide it from the FileSystem dock,
 which can be useful to reduce clutter.
 
+.. _doc_project_organization_case_sensitivity:
+
 Case sensitivity
 ----------------
 

tutorials/animation/2d_skeletons.rst

@@ -3,6 +3,11 @@
 2D skeletons
 ============
 
+.. warning::
+
+    There are known issues with 2D skeletons on mobile and web platforms with the GLES2 renderer. We
+    recommend using the GLES3 renderer if your project relies on Skeleton2D for now.
+
 Introduction
 ------------
 

tutorials/physics/collision_shapes_3d.rst

@@ -0,0 +1,146 @@
+.. _doc_collision_shapes_3d:
+
+Collision shapes (3D)
+=====================
+
+This guide explains:
+
+- The types of collision shapes available in 3D in Godot.
+- Using a convex or a concave mesh as a collision shape.
+- Performance considerations regarding 3D collisions.
+
+Godot provides many kinds of collision shapes, with different performance and
+accuracy tradeoffs.
+
+You can define the shape of a :ref:`class_PhysicsBody` by adding one or more
+:ref:`CollisionShapes <class_CollisionShape>` as child nodes. Note that you must
+add a :ref:`class_Shape` *resource* to collision shape nodes in the Inspector
+dock.
+
+.. note::
+
+    When you add multiple collision shapes to a single PhysicsBody, you don't
+    have to worry about them overlapping. They won't "collide" with each other.
+
+Primitive collision shapes
+--------------------------
+
+Godot provides the following primitive collision shape types:
+
+- :ref:`class_BoxShape`
+- :ref:`class_SphereShape`
+- :ref:`class_CapsuleShape`
+- :ref:`class_CylinderShape`. It is only available when using the Bullet physics
+  engine.
+
+You can represent the collision of most smaller objects using one or more
+primitive shapes. However, for more complex objects, such as a large ship or a
+whole level, you may need convex or concave shapes instead. More on that below.
+
+We recommend favoring primitive shapes for dynamic objects such as RigidBodies
+and KinematicBodies as their behavior is the most reliable. They often provide
+better performance as well.
+
+Convex collision shapes
+-----------------------
+
+:ref:`Convex collision shapes <class_ConvexPolygonShape>` are a compromise
+between primitive collision shapes and concave collision shapes. They can
+represent shapes of any complexity, but with an important caveat. As their name
+implies, an individual shape can only represent a *convex* shape. For instance,
+a pyramid is *convex*, but a hollow box is *concave*. To define a concave object
+with a single collision shape, you need to use a concave collision shape.
+
+Depending on the object's complexity, you may get better performance by using
+multiple convex shapes instead of a concave collision shape. Godot lets you use
+*convex decomposition* to generate convex shapes that roughly match a hollow
+object. Note this performance advantage no longer applies after a certain amount
+of convex shapes. For large and complex objects such as a whole level, we
+recommend using concave shapes instead.
+
+You can generate one or several convex collision shapes from the editor by
+selecting a MeshInstance and using the **Mesh** menu at the top of the 3D
+viewport. The editor exposes two generation modes:
+
+- **Create Single Convex Collision Sibling** uses the Quickhull algorithm. It
+  creates one CollisionShape node with an automatically generated convex
+  collision shape. Since it only generates a single shape, it provides good
+  performance and is ideal for small objects.
+
+- **Create Multiple Convex Collision Siblings** uses the V-HACD algorithm. It
+  creates several CollisionShape nodes, each with a convex shape. Since it
+  generates multiple shapes, it is more accurate for concave objects at the cost
+  of performance. For objects with medium complexity, it will likely be faster
+  than using a single concave collision shape.
+
+Concave or trimesh collision shapes
+-----------------------------------
+
+:ref:`Concave collision shapes <class_ConcavePolygonShape>`, also called trimesh
+collision shapes, can take any form, from a few triangles to thousands of
+triangles. Concave shapes are the slowest option but are also the most accurate
+in Godot. **You can only use concave shapes within StaticBodies.** They will not
+work with KinematicBodies or RigidBodies unless the RigidBody's mode is Static.
+
+.. note::
+
+    Even though concave shapes offer the most accurate *collision*, contact
+    reporting can be less precise than primitive shapes.
+
+When not using GridMaps for level design, concave shapes are the best approach
+for a level's collision. That said, if your level has small details, you may
+want to exclude those from collision for performance and game feel. To do so,
+you can build a simplified collision mesh in a 3D modeler and have Godot
+generate a collision shape for it automatically. More on that below
+
+Note that unlike primitive and convex shapes, a concave collision shape doesn't
+have an actual "volume". You can place objects both *outside* of the shape as
+well as *inside*.
+
+You can generate a concave collision shape from the editor by selecting a
+MeshInstance and using the **Mesh** menu at the top of the 3D viewport. The
+editor exposes two options:
+
+- **Create Trimesh Static Body** is a convenient option. It creates a StaticBody
+  containing a concave shape matching the mesh's geometry.
+
+- **Create Trimesh Collision Sibling** creates a CollisionShape node with a
+  concave shape matching the mesh's geometry.
+
+.. note::
+
+    Suppose you need to make a RigidBody *slide* on a concave collision shape.
+    In that case, you may notice that sometimes, the RigidBody will bump
+    upwards. To solve this, open **Project > Project Settings** and enable
+    **Physics > 3d > Smooth Trimesh Collision**.
+
+    Once you've enabled smooth trimesh collision, make sure the concave shape is
+    the only shape of your StaticBody and that it's located at its origin
+    without any rotation. This way, the RigidBody should slide perfectly on the
+    StaticBody.
+
+.. seealso::
+
+    Godot can generate collision shapes for your imported 3D scenes
+    automatically. See :ref:`doc_importing_scenes_import_hints` in the
+    documentation for more information.
+
+Performance caveats
+-------------------
+
+You aren't limited to a single collision shape per PhysicsBody. Still, we
+recommend keeping the number of shapes as low as possible to improve
+performance, especially for dynamic objects like RigidBodies and
+KinematicBodies. On top of that, avoid translating, rotating, or scaling
+CollisionShapes to benefit from the physics engine's internal optimizations.
+
+When using a single non-transformed collision shape in a StaticBody, the
+engine's *broad phase* algorithm can discard inactive PhysicsBodies. The *narrow
+phase* will then only have to take into account the active bodies' shapes. If a
+StaticBody has many collision shapes, the broad phase will fail. The narrow
+phase, which is slower, must then perform a collision check against each shape.
+
+If you run into performance issues, you may have to make tradeoffs in terms of
+accuracy. Most games out there don't have a 100% accurate collision. They find
+creative ways to hide it or otherwise make it unnoticeable during normal
+gameplay.

tutorials/physics/index.rst

@@ -13,3 +13,4 @@ Physics
    ragdoll_system
    kinematic_character_2d
    soft_body
+   collision_shapes_3d

tutorials/shading/shading_reference/shading_language.rst

@@ -186,10 +186,11 @@ Using lower precision for some operations can speed up the math involved (at the
 This is rarely needed in the vertex processor function (where full precision is needed most of the time),
 but is often useful in the fragment processor.
 
-Keep in mind that some architectures (mainly mobile) benefit a lot from this, but are also restricted
+Some architectures (mainly mobile) can benefit significantly from this, but
-(conversion between precisions has a cost). Please read the relevant documentation on the target architecture
+there are downsides such as the additional overhead of conversion between
-to find out more. In all honesty though, mobile drivers are buggy, so, to stay out of trouble, make simple
+precisions. Refer to the documentation of the target architecture for further
-shaders without specifying precision unless you *really* need to.
+information. In many cases, mobile drivers cause inconsistent or unexpected
+behavior and it is best to avoid specifying precision unless necessary.
 
 Arrays
 ------