Merge pull request #2394 from clayjohn/fixes_for_new_docs

First pass at reviewing reduz' new docs

getting_started/step_by_step/ui_introduction_to_the_ui_system.rst

@@ -23,7 +23,7 @@ This guide will get you started with UI design. You will learn:
 -  How to efficiently place and arrange your user interface using
    containers
 -  The five most common containers (at a later time, you can learn more about containers in
-the :ref:`GUI Containers<doc_gui_containers>` documentation page).
+   the :ref:`GUI Containers <doc_gui_containers>` documentation page).
 
 To learn how to control the interface and connect it to other scripts,
 read :ref:`Build your first game UI in Godot <doc_ui_game_user_interface>`.

tutorials/gui/gui_containers.rst

@@ -1,21 +1,23 @@
 .. _doc_gui_containers:
 
 Containers
-===========
+==========
 
-For basic multiple resolution handling for GUIs, :ref:`anchors <size_and_anchors>` are an 
-efficient way to handle different aspect ratios.
+:ref:`Anchors <doc_size_and_anchors>` are an efficient way to handle 
+different aspect ratios for basic multiple resolution handling in GUIs,  
 
-For more complex user interfaces, however, they can become difficult to use. 
+For more complex user interfaces, they can become difficult to use. 
 
-This is often the case of games, such as RPGs, online chats, tycoons or simulations. Another common case where more advanced layout features may be required is in-game tools (or simply just tools). 
+This is often the case of games, such as RPGs, online chats, tycoons or simulations. Another
+common case where more advanced layout features may be required is in-game tools (or simply just tools). 
 
 All these situations require a more capable OS-like user interface, with advanced layout and formatting.
+For that, :ref:`Containers <class_container>` are more useful.
 
-Container Layout
------------------
+Container layout
+----------------
 
-Containers provide a huge amount layout power (as an example, the Godot editor user interface is entirely done using them):
+Containers provide a huge amount of layout power (as an example, the Godot editor user interface is entirely done using them):
 
    .. image:: img/godot_containers.png
 
@@ -23,7 +25,8 @@ When a :ref:`Container <class_Container>`-derived node is used, all children :re
 own positioning ability. This means the *Container* will control their positioning and any attempt to manually alter these
 nodes will be either ignored or invalidated the next time their parent is resized.
 
-Likewise, when a *Container* derived node is resized, all it's children will be re-positioned according to it, with a behavior based on the type of container used:
+Likewise, when a *Container* derived node is resized, all it's children will be re-positioned according to it, 
+with a behavior based on the type of container used:
 
    .. image:: img/container_example.gif
 
@@ -31,7 +34,7 @@ Example of *HBoxContainer* resizing children buttons.
 
 The real strength of containers is that they can be nested (as nodes), allowing the creation of very complex layouts that resize effortlessly.
 
-Size Flags
+Size flags
 ----------
 
 When adding a node to a container, the way the container treats each child depends mainly on their *size flags*. These flags
@@ -41,23 +44,29 @@ can be found by inspecting any control that is a child of a *Container*.
 
 Size flags are independent for vertical and horizontal sizing and not all containers make use of them (but most do):
 
-* **Fill**: Ensures the control *fills* the designated area within the container. No matter if a control *expands* or not (see below), it will only *fill* the designated area when this is toggled on (it is by default).
-* **Expand**: Attempts to use as most space as possible in the parent container (in this each axis). Controls that don't expand will be pushed away by those that do. Between those expanding, the amount of space they take from each other is determined by the *Ratio* (see below).
-* **Shrink Center** When expanding (and if not filling), try to remain at the center of the expanded area (by default it remains at the left or top).
-* **Shrink Center** When expanding (and if not filling), try to remain at the center of the expanded area (by default it remains at the left).
-* **Ratio** Simple ratio of how much expanded controls take up the available space in relation to each other. A control with "2", will take up twice as much available space as one with "1".
+* **Fill**: Ensures the control *fills* the designated area within the container. No matter if 
+  a control *expands* or not (see below), it will only *fill* the designated area when this is toggled on (it is by default).
+* **Expand**: Attempts to use as most space as possible in the parent container (in this each axis). 
+  Controls that don't expand will be pushed away by those that do. Between those expanding, the 
+  amount of space they take from each other is determined by the *Ratio* (see below).
+* **Shrink Center** When expanding (and if not filling), try to remain at the center of the expanded 
+  area (by default it remains at the left or top).
+* **Ratio** Simple ratio of how much expanded controls take up the available space in relation to each 
+  other. A control with "2", will take up twice as much available space as one with "1".
 
 Experimenting with these flags and different containers is recommended to get a better grasp on how they work.
 
-Container Types
+Container types
 ---------------
 
-Godot provides several container types out of the box, they serve multiple different purposes:
+Godot provides several container types out of the box as they serve different purposes:
 
 Box Containers
 ^^^^^^^^^^^^^^
 
-Arrange child controls vertically or horizontally (via :ref:`HBoxContainer <class_HBoxContainer>` and :ref:`VBoxContainer <class_VBoxContainer>`). In the opposite of the designated direction (as in, vertical for an horizontal container), it just expands the children.
+Arrange child controls vertically or horizontally (via :ref:`HBoxContainer <class_HBoxContainer>` and
+:ref:`VBoxContainer <class_VBoxContainer>`). In the opposite of the designated direction
+(as in, vertical for an horizontal container), it just expands the children.
 
    .. image:: img/containers_box.png
 
@@ -66,25 +75,30 @@ These containers make use of the *Ratio* property for children with the *Expand*
 Grid Container
 ^^^^^^^^^^^^^^
 
-Arranges child controls in a grid layout (via :ref:`GridContainer <class_GridContainer>`, amount of columns must be specified). Uses both the vertical and horizontal expand flags.
+Arranges child controls in a grid layout (via :ref:`GridContainer <class_GridContainer>`, amount 
+of columns must be specified). Uses both the vertical and horizontal expand flags.
 
    .. image:: img/containers_grid.png
 
 Margin Container
-^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^
 
-Child controls are expanded towards the bounds of this control (via :ref:`MarginContainer <class_MarginContainer>`). Padding will be
-added on the margins depending on the theme configuration.
+Child controls are expanded towards the bounds of this control (via 
+:ref:`MarginContainer <class_MarginContainer>`). Padding will be added on the margins 
+depending on the theme configuration.
 
    .. image:: img/containers_margin.png
 
-Again, keep in mind that the margins are a *Theme* value, so they need to be edited at the constants overrides section if desired for a single control:
+Again, keep in mind that the margins are a *Theme* value, so they need to be edited at the
+constants overrides section if desired for a single control:
+
    .. image:: img/containers_margin_constants.png
 
 Tab Container
-^^^^^^^^^^^^^^
+^^^^^^^^^^^^^
 
-Allows to place several child controls stacked on top of each other (via :ref:`TabContainer <class_TabContainer>`), with only the *current* one visible. 
+Allows you to place several child controls stacked on top of each other (via 
+:ref:`TabContainer <class_TabContainer>`), with only the *current* one visible. 
 
    .. image:: img/containers_tab.png
 
@@ -97,9 +111,11 @@ The titles are generated from the node names by default (although they can be ov
 Settings such as tab placement and *StyleBox* can be modified in the *TabContainer* theme overrides.
 
 Split Container
-^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^
 
-Accepts only one or two children controls, then places them side to side with a divisor (via :ref:`HSplitContainer <class_HSplitContainer>` and :ref:`VSplitContainer <class_VSplitContainer>`). Respects both horizontal and vertical flags, as well as *Ratio*.
+Accepts only one or two children controls, then places them side to side with a divisor 
+(via :ref:`HSplitContainer <class_HSplitContainer>` and :ref:`VSplitContainer <class_VSplitContainer>`). 
+Respects both horizontal and vertical flags, as well as *Ratio*.
 
    .. image:: img/containers_split.png
 
@@ -111,16 +127,21 @@ The divisor can be dragged around to change the size relation between both child
 PanelContainer
 ^^^^^^^^^^^^^^
 
-Simple container that draws a *StyleBox*, then expands children to cover its whole area (via :ref:`PanelContainer <class_PanelContainer>`, respecting the *StyleBox* margins). It respects both the horizontal and vertical size flags.
+Simple container that draws a *StyleBox*, then expands children to cover its whole area 
+(via :ref:`PanelContainer <class_PanelContainer>`, respecting the *StyleBox* margins). 
+It respects both the horizontal and vertical size flags.
 
    .. image:: img/containers_panel.png
 
 This container is useful as top-level, or just to add custom backgrounds to sections of a layout.
 
 ScrollContainer
-^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^
 
-Accepts a single child node. If this node is bigger than the container, scrollbars will be added to allow panning the node around (via :ref:`ScrollContainer <class_ScrollContainer>`). Both vertical and horizontal size flags are respected, and the behavior can be turned on or off per axis in the properties.
+Accepts a single child node. If this node is bigger than the container, scrollbars will be added 
+to allow panning the node around (via :ref:`ScrollContainer <class_ScrollContainer>`). Both 
+vertical and horizontal size flags are respected, and the behavior can be turned on or off 
+per axis in the properties.
 
    .. image:: img/containers_scroll.png
 
@@ -132,9 +153,10 @@ As in the example above, one of the most common ways to use this container is to
 
 
 ViewportContainer
-^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^
 
-This is a special control that will only accept a single *Viewport* node as child, and it will display it as if it was an image (via :ref:`ViewportContainer <class_ViewportContainer>`).
+This is a special control that will only accept a single *Viewport* node as child, and it will display 
+it as if it was an image (via :ref:`ViewportContainer <class_ViewportContainer>`).
 
 Creating custom Containers
 --------------------------
@@ -157,11 +179,3 @@ to its rect size:
     func set_some_setting():
         # Some setting changed, ask for childre re-sort
         queue_sort()
-
-
-	
-	
-
-
-
-

tutorials/misc/index.rst

@@ -1,3 +1,6 @@
+Miscellaneous
+=============
+
 .. toctree::
    :maxdepth: 1
    :name: toc-learn-features-misc

tutorials/optimization/using_multimesh.rst

@@ -1,40 +1,60 @@
 .. _doc_using_multimesh:
 
-Optimization Using Multimeshes
-============
+Optimization using MultiMeshes
+==============================
 
-For large amount of instances (in the thousands), that need to be constantly processed (and certain amount of control needs to be retained), :ref:`using servers directly<doc_using_servers>` is the recommended optimization.
+For large amount of instances (in the thousands), that need to be constantly processed 
+(and certain amount of control needs to be retained), 
+:ref:`using servers directly <doc_using_servers>` is the recommended optimization.
 
-When the amount of objects reach the dozens of thousands, hundreds of thousands or even millions, none of these approaches are efficient anymore. Still, depending on the requirements, there is one more optimization possible.
+When the amount of objects reach the  hundreds of thousands or millions, 
+none of these approaches are efficient anymore. Still, depending on the requirements, there 
+is one more optimization possible.
 
-
-Multimeshes
+MultiMeshes
 -----------
 
-A :ref:`MultiMesh<class_MultiMesh>` is a single draw primitive that can draw up to millions of objects in one go. It's extremely efficient because it uses the GPU hardware to do this (In OpenGL ES 2.0, it's less efficient because there is no hardware support for it, though).
-
-The only drawback is that there is no *screen* or *frustum* culling possible for individual instances. This means, that millions of objects will be *always* or *never* drawn, depending on the visibility of the whole MultiMesh. It is possible to provide a custom visibility rect for them, but it will always be *all-or-none* visibility.
-
-If the objects are simple enough (just a couple of vertices), this is generally not much of a problem as most modern GPUs are optimized for this use case. A workaround is to create several multimeshes for different areas of the world.
-
-If logic is too simple, it is also possible to execute it inside the vertex shader (using the INSTANCE_ID integer built-in constant). Information to it can be provided via textures (there are floating point :ref:`Image<class_Image>` formats which are ideal for this).
-
-Another alternative is to use GDNative and C++, which should be extremely efficient (it's possible to set the entire state for all objects using linear memory via the :ref:`VisualServer.multimesh_set_as_bulk_array()<class_VisualServer_method_multimesh_set_as_bulk_array>` function. This way, the array can be created with multiple threads, then set in one call, providing high cache efficiency.
-
-Finally, it's not required to have all multimesh instances visible. The amount of visible ones can be controlled with the *MultiMesh.visible_instance_count* property. The typical workflow is to allocate the maximum amount of instances that will be used,
+A :ref:`MultiMesh<class_MultiMesh>` is a single draw primitive that can draw up to millions 
+of objects in one go. It's extremely efficient because it uses the GPU hardware to do this 
+(In OpenGL ES 2.0, it's less efficient because there is no hardware support for it, though).
+
+The only drawback is that there is no *screen* or *frustum* culling possible for individual instances. 
+This means, that millions of objects will be *always* or *never* drawn, depending on the visibility 
+of the whole MultiMesh. It is possible to provide a custom visibility rect for them, but it will always 
+be *all-or-none* visibility.
+
+If the objects are simple enough (just a couple of vertices), this is generally not much of a problem 
+as most modern GPUs are optimized for this use case. A workaround is to create several MultiMeshes 
+for different areas of the world.
+
+It is also possible to execute some logic inside the vertex shader (using the INSTANCE_ID or 
+INSTANCE_CUSTOM built-in constants). For an example of animating thousands of objects in a MultiMesh,
+see the :ref:`Animating thousands of fish <doc_animating_thousands_of_fish>` tutorial. Information 
+to the shader can be provided via textures (there are floating point :ref:`Image<class_Image>` formats 
+which are ideal for this).
+
+Another alternative is to use GDNative and C++, which should be extremely efficient (it's possible 
+to set the entire state for all objects using linear memory via the 
+:ref:`VisualServer.multimesh_set_as_bulk_array() <class_VisualServer_method_multimesh_set_as_bulk_array>` 
+function. This way, the array can be created with multiple threads, then set in one call, providing 
+high cache efficiency.
+
+Finally, it's not required to have all MultiMesh instances visible. The amount of visible ones can be 
+controlled with the *MultiMesh.visible_instance_count* property. The typical workflow is to allocate 
+the maximum amount of instances that will be used,
 then change the amount visible depending on how many are currently needed.
 
 Multimesh Example
------------
+-----------------
 
-Here is a simple example of using a multimesh from code (using GDScript). Other languages may be more efficient for millions of objects, but for a few thousands, GDScript should be fine.
+Here is an example of using a MultiMesh from code (using GDScript). Other languages may be more 
+efficient for millions of objects, but for a few thousands, GDScript should be fine.
 
 .. tabs::
  .. code-tab:: gdscript GDScript
 
     extends MultiMeshInstance
-    
-    
+
     func _ready():
 
         # Create multimesh
@@ -50,5 +70,3 @@ Here is a simple example of using a multimesh from code (using GDScript). Other
         # Set instance transforms
         for i in range(multimesh.visible_instance_count):
             multimesh.set_instance_transform(i,Transform( Basis(), Vector3(i*20,0,0) ) )
-
-

tutorials/optimization/using_servers.rst

@@ -1,63 +1,86 @@
 .. _doc_using_servers:
 
 Optimization Using Servers
-============
+==========================
 
-Engines like Godot provide increased ease of use thanks to it's high level constructs and features. Most of them are accessed and used via the :ref:`Scene System<doc_scene_tree>`. Using nodes and resources simplifies project organization and asset management
-in complex games.
+Engines like Godot provide increased ease of use thanks to it's high level constructs and features. 
+Most of them are accessed and used via the :ref:`Scene System<doc_scene_tree>`. Using nodes and 
+resources simplifies project organization and asset management in complex games.
 
-There are, of course always drawbacks
+There are, of course, always drawbacks:
 
 * There is an extra layer of complexity
 * Performance is lower than using simple APIs directly
 * It is not possible to use multiple threads to control them
 * More memory is needed.
 
-In far most cases, this is not really a problem (Godot is very optimized, and most operations are handled with signals, so no polling is required). Still, sometimes it may be. As an example, dealing with dozens of thousands of instances for something that needs to be processed every frame can pose a bottleneck. 
+In many cases, this is not really a problem (Godot is very optimized, and most operations are handled 
+with signals, so no polling is required). Still, sometimes it can be. For example, dealing with 
+tens of thousands of instances for something that needs to be processed every frame can be a bottleneck. 
 
-This type of situation makes programmers regret they are using a game engine and wish they could go back to a more handcrafted, low level implementation of game code. 
+This type of situation makes programmers regret they are using a game engine and wish they could go 
+back to a more handcrafted, low level implementation of game code. 
 
 Still, Godot is designed to work around this problem.
 
 Servers
 -------
 
-One of the most interesting design decisions for Godot, is the fact that the whole scene system is *optional*. While it's not currently possible to compile it out, it can be completely bypassed.
+One of the most interesting design decisions for Godot, is the fact that the whole scene system is 
+*optional*. While it is not currently possible to compile it out, it can be completely bypassed.
 
-At the core, Godot uses the concept of Servers. They are very low level APIs to control rendering, physics, sound, etc. The scene system is built on top of them and uses them directly. The most common servers are:
+At the core, Godot uses the concept of Servers. They are very low level APIs to control 
+rendering, physics, sound, etc. The scene system is built on top of them and uses them directly. The most common servers are:
 
-* :ref:`Visual Server<class_VisualServer>` handles everything related to graphics.
-* :ref:`PhysicsServer<class_PhysicsServer>` handles everything related to 3D physics.
-* :ref:`Physics2DServer<class_Physics2DServer>` handles everything related to 2D physics.
-* :ref:`AudioServer<class_AudioServer>` handles everything related to audio.
+* :ref:`Visual Server<class_VisualServer>`: handles everything related to graphics.
+* :ref:`PhysicsServer<class_PhysicsServer>`: handles everything related to 3D physics.
+* :ref:`Physics2DServer<class_Physics2DServer>`: handles everything related to 2D physics.
+* :ref:`AudioServer<class_AudioServer>`: handles everything related to audio.
 
-Just explore their APIs and you will realize that the all functions provided are low level implementations of everything Godot allows to do.
+Just explore their APIs and you will realize that the all functions provided are low-level
+implementations of everything Godot allows you to do.
 
 RIDs
 ----
 
-The key to using servers is understanding RID objects (RID means Resource ID). These are opaque handles to the sever implementation. They are allocated and freed manually. Almost every function in the servers requires RIDs to access the actual resource.
+The key to using servers is understanding Resource ID (RID) objects. These are opaque 
+handles to the sever implementation. They are allocated and freed manually. Almost every 
+function in the servers requires RIDs to access the actual resource.
 
-Most Godot nodes and resources contain internally these RIDs from the servers, and they can be obtained with different functions. In fact, anything that inherits :ref:`Resource<class_Resource>` can be directly casted to an RID (not all resources contain an RID, though, in such cases the RID will be empty). In fact, resources can be passed to server APIs as RIDs. Just make sure to keep references to the resources ouside the server, because if the resource is erased, the internal RID is erased too.
+Most Godot nodes and resources contain these RIDs from the servers internally, and they can 
+be obtained with different functions. In fact, anything that inherits :ref:`Resource <class_Resource>` 
+can be directly casted to an RID (not all resources contain an RID, though, in such cases 
+the RID will be empty). In fact, resources can be passed to server APIs as RIDs. Just make 
+sure to keep references to the resources ouside the server, because if the resource is erased, 
+the internal RID is erased too.
 
 For nodes, there are many functions available:
 
-* For CanvasItem, the :ref:`CanvasItem.get_canvas_item()<class_CanvasItem_method_get_canvas_item>` method will return the canvas item RID in the server. 
-* For CanvasLayer, the :ref:`CanvasLayer.get_canvas()<class_CanvasLayer_method_get_canvas>` method will return the canvas RID in the server. 
-* For Viewport, the :ref:`Viewport.get_viewport_rid()<class_Viewport_method_get_viewport_rid>` method will return the viewport RID in the server. 
-* For 3D, the :ref:`World<class_World>` resource (obtainable in the *Viewport* and *Spatial* nodes, contains function to get the *VisualServer Scenario*, and the *PhysicsServer Space*. This allows creating 3D objects directly with the server API and using them.
-* For 2D, the :ref:`World2D<class_World2D>` resource (obtainable in the *Viewport* and *CanvasItem* nodes, contains function to get the *VisualServer Canvas*, and the *Physics2DServer Space*. This allows creating 2D objects directly with the server API and using them.
-* The :ref:`VisualInstance<class_VisualInstance` class, allows getting the scenario *instance* and *instance base* via the :ref:`VisualInstance.get_instance()<class_VisualInstance_method_get_instance>` and :ref:`VisualInstance.get_base()<class_VisualInstance_method_get_base>` respectively.
+* For CanvasItem, the :ref:`CanvasItem.get_canvas_item()<class_CanvasItem_method_get_canvas_item>` 
+  method will return the canvas item RID in the server. 
+* For CanvasLayer, the :ref:`CanvasLayer.get_canvas()<class_CanvasLayer_method_get_canvas>` 
+  method will return the canvas RID in the server. 
+* For Viewport, the :ref:`Viewport.get_viewport_rid()<class_Viewport_method_get_viewport_rid>` 
+  method will return the viewport RID in the server. 
+* For 3D, the :ref:`World<class_World>` resource (obtainable in the *Viewport* and *Spatial* nodes, 
+  contains function to get the *VisualServer Scenario*, and the *PhysicsServer Space*. This 
+  allows creating 3D objects directly with the server API and using them.
+* For 2D, the :ref:`World2D<class_World2D>` resource (obtainable in the *Viewport* and *CanvasItem* 
+  nodes, contains function to get the *VisualServer Canvas*, and the *Physics2DServer Space*. This 
+  allows creating 2D objects directly with the server API and using them.
+* The :ref:`VisualInstance<class_VisualInstance>` class, allows getting the scenario *instance* and 
+  *instance base* via the :ref:`VisualInstance.get_instance()<class_VisualInstance_method_get_instance>` 
+  and :ref:`VisualInstance.get_base()<class_VisualInstance_method_get_base>` respectively.
 
 Just explore the nodes and resources you are familiar with and find the functions to obtain the server *RIDs*. 
 
-It is not advised to control RIDs from objects that already have a node associated. Instead, server functions should always be used for creating and controlling new ones and interacting with the existing ones.
+It is not advised to control RIDs from objects that already have a node associated. Instead, server 
+functions should always be used for creating and controlling new ones and interacting with the existing ones.
 
-Creating a sprite
+Creating a Sprite
 -----------------
 
-This is a simple example of how to create a sprite from code and move it using the low level Canvas Item API.
-
+This is a simple example of how to create a sprite from code and move it using the low-level Canvas Item API.
 
 .. tabs::
  .. code-tab:: gdscript GDScript
@@ -79,7 +102,9 @@ This is a simple example of how to create a sprite from code and move it using t
         var xform = Transform2D().rotated( deg2rad(45) ).translated( Vector2( 20, 30 ) )	
         VisualServer.canvas_item_set_transform( ci_rid, xform )
 
-The Canvas Item API in the server allows you to add draw primitives to it. Once added, they can't be modified. The Item needs to be cleared and the primitives re-added (this is not the case for setting the transform, which can be done as many times as desired).
+The Canvas Item API in the server allows you to add draw primitives to it. Once added, they can't be modified. 
+The Item needs to be cleared and the primitives re-added (this is not the case for setting the transform, 
+which can be done as many times as desired).
 
 Primitives are cleared this way:
 
@@ -89,10 +114,10 @@ Primitives are cleared this way:
     VisualServer.canvas_item_clear( ci_rid )
 	
 
-Instantiating a Mesh into 3D Space
+Instantiating a Mesh into 3D space
 ----------------------------------
 
-The 3D APIs are considerably different than the 2D ones, so the instantiation API must be used.
+The 3D APIs are different than the 2D ones, so the instantiation API must be used.
 
 .. tabs::
  .. code-tab:: gdscript GDScript
@@ -115,8 +140,8 @@ The 3D APIs are considerably different than the 2D ones, so the instantiation AP
         var xform = Transform( Basis(), Vector3(20,100,0) )
         VisualServer.instance_set_transform(instance,xform)
 	
-Creating a 2D Rigid Body and moving a sprite with it
------------------------------------------------------
+Creating a 2D RigidBody and moving a Sprite with it
+----------------------------------------------------
 
 This creates a *RigidBody* using the *Physics2DServer* API, and moves a *Canvas Item*  when the body moves.
 
@@ -151,10 +176,11 @@ The 3D version should be very similar, as 2D and 3D physics servers are identica
 Getting data from the servers
 -----------------------------
 
-Try to **never** request any information from *VisualServer*, *PhysicsServer* or *Physics2DServer* by calling functions unless you know what you are doing. These servers will often run asynchronously for performance and calling any function that returns a value will stall them and force them to process anything pending until the function is actually called. This will severely decrease performance if you call them every frame (and it won't be obvious why).
-
-Because of this, most APIs in such servers are designed so it's not even possible to request information back, until it's actual data that can be saved.
-
-
-
+Try to **never** request any information from *VisualServer*, *PhysicsServer* or *Physics2DServer* 
+by calling functions unless you know what you are doing. These servers will often run asynchronously 
+for performance and calling any function that returns a value will stall them and force them to process 
+anything pending until the function is actually called. This will severely decrease performance if you 
+call them every frame (and it won't be obvious why).
 
+Because of this, most APIs in such servers are designed so it's not even possible to request information 
+back, until it's actual data that can be saved.

tutorials/viewports/multiple_resolutions.rst

@@ -5,10 +5,10 @@ Multiple resolutions
 
 
 The problem of multiple resolutions
-------------------------------------
+-----------------------------------
 
-There are often misunderstandings by developers on how to best support
-multiple resolutions. For Desktop and Console games this is more or less straightforward,
+Developers often have trouble understanding  how to best support multiple resolutions
+in their games. For Desktop and Console games this is more or less straightforward,
 as most screen aspect ratios are 16:9 and resolutions are standard (720,1080,2k,4k,etc).
 
 For mobile games at first it was easy. For many years, the iPhone (and iPad) used the same
@@ -16,32 +16,32 @@ resolution. When *Retina* was implemented, they just doubled the amount of pixel
 (so most developers had assets in default and double resolutions).
 
 Nowadays this is no longer the case, as there are plenty of different screen sizes, densities
-and aspects for mobile, and non conventional sizes are becoming trendy for Desktop,
+and aspect ratios for mobile, and non conventional sizes are becoming trendy for Desktop,
 such as ultra-wide.
 
-For 3D games there is not much of a need to support multiple resolutions (from the aesthetical
+For 3D games there is not much of a need to support multiple resolutions (from the aesthetic
 point of view). The 3D geometry will just fill the screen based on the field-of-view, disregarding
-the aspect. The main reason one may want to support this, in this case, is for *performance* reasons (running
+the aspect ratio. The main reason one may want to support this, in this case, is for *performance* reasons (running
 in lower resolution to increase frames per second).
 
 For 2D and game UIs, this is a different matter, as art needs to be created using specific pixel sizes
 in software such as Photoshop, Gimp, Krita, etc.
 
-Given layouts, aspects, resolutions and pixel densities can change so much, it is no longer possible
+Given layouts, aspect ratios, resolutions and pixel densities can change so much, it is no longer possible
 to design UIs for every specific screen. Another method must be used.
 
 One size fits all
 -----------------
 
-The most common approach nowadays is to just use a single *base* resolution and then fit it to everything else. This resolution is how
-most players are expected to play the game (given their hardware). For mobile, Google has useful `stats <https://developer.android.com/about/dashboards>`_ online,
-and for desktop, Steam `also does<https://store.steampowered.com/hwsurvey/Steam-Hardware-Software-Survey-Welcome-to-Steam>`_.
+The most common approach nowadays is to just use a single *base* resolution and then fit it to everything else.
+This resolution is how most players are expected to play the game (given their hardware). For mobile, Google 
+has useful `stats <https://developer.android.com/about/dashboards>`_ online, and for desktop, 
+Steam `also does <https://store.steampowered.com/hwsurvey/Steam-Hardware-Software-Survey-Welcome-to-Steam>`_.
 
 As an example, Steam shows that the most common *primary display resolution* is 1920x1080, so a sensible approach is to develop a game for this resolution, then handle scaling for different sizes and aspect ratios.
 
 Godot provides a several useful tools to do this easily.
 
-
 Base size
 ---------
 
@@ -232,8 +232,6 @@ To configure stretching at runtime from a script, use the
 Handling aspect ratios
 ^^^^^^^^^^^^^^^^^^^^^^
 
-Once scaling for different resolutions is accounted for, just make sure that your *user interface* also scales for different aspect ratios. This can be easily done using :ref:`anchors <size_and_anchors>` and/or :ref:`anchors <gui_containers>`.
-
-
-
-
+Once scaling for different resolutions is accounted for, just make sure that your *user interface*
+also scales for different aspect ratios. This can be easily done using :ref:`anchors <doc_size_and_anchors>` 
+and/or :ref:`containers <doc_gui_containers>`.