classref: Sync with current master branch (16a9356)

Author: Godot Organization

classes/[email protected]

@@ -538,6 +538,8 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_NODE_PATH_VALID_TYPES<class_@GlobalSco
 
     @export_node_path("Button", "TouchScreenButton") var some_button
 
+\ **Note:** The type must be a native class or a globally registered script (using the ``class_name`` keyword) that inherits :ref:`Node<class_Node>`.
+
 .. rst-class:: classref-item-separator
 
 ----
@@ -665,7 +667,7 @@ Mark the following method for remote procedure calls. See :doc:`High-level multi
 
 If ``mode`` is set as ``"any_peer"``, allows any peer to call this RPC function. Otherwise, only the authority peer is allowed to call it and ``mode`` should be kept as ``"authority"``. When configuring functions as RPCs with :ref:`Node.rpc_config<class_Node_method_rpc_config>`, each of these modes respectively corresponds to the :ref:`MultiplayerAPI.RPC_MODE_AUTHORITY<class_MultiplayerAPI_constant_RPC_MODE_AUTHORITY>` and :ref:`MultiplayerAPI.RPC_MODE_ANY_PEER<class_MultiplayerAPI_constant_RPC_MODE_ANY_PEER>` RPC modes. See :ref:`RPCMode<enum_MultiplayerAPI_RPCMode>`. If a peer that is not the authority tries to call a function that is only allowed for the authority, the function will not be executed. If the error can be detected locally (when the RPC configuration is consistent between the local and the remote peer), an error message will be displayed on the sender peer. Otherwise, the remote peer will detect the error and print an error there.
 
-If ``sync`` is set as ``"call_remote"``, the function will only be executed on the remote peer, but not locally. To run this function locally too, set ``sync`` to ``"call_local"``. When configuring functions as RPCs with :ref:`Node.rpc_config<class_Node_method_rpc_config>`, this is equivalent to setting `call_local` to `true`.
+If ``sync`` is set as ``"call_remote"``, the function will only be executed on the remote peer, but not locally. To run this function locally too, set ``sync`` to ``"call_local"``. When configuring functions as RPCs with :ref:`Node.rpc_config<class_Node_method_rpc_config>`, this is equivalent to setting ``call_local`` to ``true``.
 
 The ``transfer_mode`` accepted values are ``"unreliable"``, ``"unreliable_ordered"``, or ``"reliable"``. It sets the transfer mode of the underlying :ref:`MultiplayerPeer<class_MultiplayerPeer>`. See :ref:`MultiplayerPeer.transfer_mode<class_MultiplayerPeer_property_transfer_mode>`.
 

classes/[email protected]

@@ -5598,9 +5598,9 @@ Returns a human-readable name for the given :ref:`Error<enum_@GlobalScope_Error>
 
 :ref:`float<class_float>` **exp** **(** :ref:`float<class_float>` x **)**
 
-The natural exponential function. It raises the mathematical constant **e** to the power of ``x`` and returns it.
+The natural exponential function. It raises the mathematical constant *e* to the power of ``x`` and returns it.
 
-\ **e** has an approximate value of 2.71828, and can be obtained with ``exp(1)``.
+\ *e* has an approximate value of 2.71828, and can be obtained with ``exp(1)``.
 
 For exponents to other bases use the method :ref:`pow<class_@GlobalScope_method_pow>`.
 

classes/class_area3d.rst

@@ -23,7 +23,7 @@ Description
 
 This node can also locally alter or override physics parameters (gravity, damping) and route audio to custom audio buses.
 
-\ **Warning:** Using a :ref:`ConcavePolygonShape3D<class_ConcavePolygonShape3D>` inside a :ref:`CollisionShape3D<class_CollisionShape3D>` child of this node (created e.g. by using the *Create Trimesh Collision Sibling* option in the *Mesh* menu that appears when selecting a :ref:`MeshInstance3D<class_MeshInstance3D>` node) may give unexpected results, since this collision shape is hollow. If this is not desired, it has to be split into multiple :ref:`ConvexPolygonShape3D<class_ConvexPolygonShape3D>`\ s or primitive shapes like :ref:`BoxShape3D<class_BoxShape3D>`, or in some cases it may be replaceable by a :ref:`CollisionPolygon3D<class_CollisionPolygon3D>`.
+\ **Warning:** Using a :ref:`ConcavePolygonShape3D<class_ConcavePolygonShape3D>` inside a :ref:`CollisionShape3D<class_CollisionShape3D>` child of this node (created e.g. by using the **Create Trimesh Collision Sibling** option in the **Mesh** menu that appears when selecting a :ref:`MeshInstance3D<class_MeshInstance3D>` node) may give unexpected results, since this collision shape is hollow. If this is not desired, it has to be split into multiple :ref:`ConvexPolygonShape3D<class_ConvexPolygonShape3D>`\ s or primitive shapes like :ref:`BoxShape3D<class_BoxShape3D>`, or in some cases it may be replaceable by a :ref:`CollisionPolygon3D<class_CollisionPolygon3D>`.
 
 .. rst-class:: classref-introduction-group
 

classes/class_astargrid2d.rst

@@ -89,6 +89,10 @@ Methods
    +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    | void                                                | :ref:`clear<class_AStarGrid2D_method_clear>` **(** **)**                                                                                                                    |
    +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+   | void                                                | :ref:`fill_solid_region<class_AStarGrid2D_method_fill_solid_region>` **(** :ref:`Rect2i<class_Rect2i>` region, :ref:`bool<class_bool>` solid=true **)**                     |
+   +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+   | void                                                | :ref:`fill_weight_scale_region<class_AStarGrid2D_method_fill_weight_scale_region>` **(** :ref:`Rect2i<class_Rect2i>` region, :ref:`float<class_float>` weight_scale **)**   |
+   +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    | :ref:`Vector2i[]<class_Vector2i>`                   | :ref:`get_id_path<class_AStarGrid2D_method_get_id_path>` **(** :ref:`Vector2i<class_Vector2i>` from_id, :ref:`Vector2i<class_Vector2i>` to_id **)**                         |
    +-----------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    | :ref:`PackedVector2Array<class_PackedVector2Array>` | :ref:`get_point_path<class_AStarGrid2D_method_get_point_path>` **(** :ref:`Vector2i<class_Vector2i>` from_id, :ref:`Vector2i<class_Vector2i>` to_id **)**                   |
@@ -440,6 +444,34 @@ Clears the grid and sets the :ref:`region<class_AStarGrid2D_property_region>` to
 
 ----
 
+.. _class_AStarGrid2D_method_fill_solid_region:
+
+.. rst-class:: classref-method
+
+void **fill_solid_region** **(** :ref:`Rect2i<class_Rect2i>` region, :ref:`bool<class_bool>` solid=true **)**
+
+Fills the given ``region`` on the grid with the specified value for the solid flag.
+
+\ **Note:** Calling :ref:`update<class_AStarGrid2D_method_update>` is not needed after the call of this function.
+
+.. rst-class:: classref-item-separator
+
+----
+
+.. _class_AStarGrid2D_method_fill_weight_scale_region:
+
+.. rst-class:: classref-method
+
+void **fill_weight_scale_region** **(** :ref:`Rect2i<class_Rect2i>` region, :ref:`float<class_float>` weight_scale **)**
+
+Fills the given ``region`` on the grid with the specified value for the weight scale.
+
+\ **Note:** Calling :ref:`update<class_AStarGrid2D_method_update>` is not needed after the call of this function.
+
+.. rst-class:: classref-item-separator
+
+----
+
 .. _class_AStarGrid2D_method_get_id_path:
 
 .. rst-class:: classref-method

classes/class_audioeffectdelay.rst

@@ -137,7 +137,7 @@ Feedback delay time in milliseconds.
 - void **set_feedback_level_db** **(** :ref:`float<class_float>` value **)**
 - :ref:`float<class_float>` **get_feedback_level_db** **(** **)**
 
-Sound level for ``tap1``.
+Sound level for feedback.
 
 .. rst-class:: classref-item-separator
 
@@ -171,7 +171,7 @@ Low-pass filter for feedback, in Hz. Frequencies below this value are filtered o
 - void **set_tap1_active** **(** :ref:`bool<class_bool>` value **)**
 - :ref:`bool<class_bool>` **is_tap1_active** **(** **)**
 
-If ``true``, ``tap1`` will be enabled.
+If ``true``, the first tap will be enabled.
 
 .. rst-class:: classref-item-separator
 
@@ -188,7 +188,7 @@ If ``true``, ``tap1`` will be enabled.
 - void **set_tap1_delay_ms** **(** :ref:`float<class_float>` value **)**
 - :ref:`float<class_float>` **get_tap1_delay_ms** **(** **)**
 
-``tap1`` delay time in milliseconds.
+First tap delay time in milliseconds.
 
 .. rst-class:: classref-item-separator
 
@@ -205,7 +205,7 @@ If ``true``, ``tap1`` will be enabled.
 - void **set_tap1_level_db** **(** :ref:`float<class_float>` value **)**
 - :ref:`float<class_float>` **get_tap1_level_db** **(** **)**
 
-Sound level for ``tap1``.
+Sound level for the first tap.
 
 .. rst-class:: classref-item-separator
 
@@ -222,7 +222,7 @@ Sound level for ``tap1``.
 - void **set_tap1_pan** **(** :ref:`float<class_float>` value **)**
 - :ref:`float<class_float>` **get_tap1_pan** **(** **)**
 
-Pan position for ``tap1``. Value can range from -1 (fully left) to 1 (fully right).
+Pan position for the first tap. Value can range from -1 (fully left) to 1 (fully right).
 
 .. rst-class:: classref-item-separator
 
@@ -239,7 +239,7 @@ Pan position for ``tap1``. Value can range from -1 (fully left) to 1 (fully righ
 - void **set_tap2_active** **(** :ref:`bool<class_bool>` value **)**
 - :ref:`bool<class_bool>` **is_tap2_active** **(** **)**
 
-If ``true``, ``tap2`` will be enabled.
+If ``true``, the second tap will be enabled.
 
 .. rst-class:: classref-item-separator
 
@@ -256,7 +256,7 @@ If ``true``, ``tap2`` will be enabled.
 - void **set_tap2_delay_ms** **(** :ref:`float<class_float>` value **)**
 - :ref:`float<class_float>` **get_tap2_delay_ms** **(** **)**
 
-**Tap2** delay time in milliseconds.
+Second tap delay time in milliseconds.
 
 .. rst-class:: classref-item-separator
 
@@ -273,7 +273,7 @@ If ``true``, ``tap2`` will be enabled.
 - void **set_tap2_level_db** **(** :ref:`float<class_float>` value **)**
 - :ref:`float<class_float>` **get_tap2_level_db** **(** **)**
 
-Sound level for ``tap2``.
+Sound level for the second tap.
 
 .. rst-class:: classref-item-separator
 
@@ -290,7 +290,7 @@ Sound level for ``tap2``.
 - void **set_tap2_pan** **(** :ref:`float<class_float>` value **)**
 - :ref:`float<class_float>` **get_tap2_pan** **(** **)**
 
-Pan position for ``tap2``. Value can range from -1 (fully left) to 1 (fully right).
+Pan position for the second tap. Value can range from -1 (fully left) to 1 (fully right).
 
 .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
 .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`

classes/class_audioserver.rst

@@ -488,7 +488,7 @@ Returns the names of all audio output devices detected on the system.
 
 :ref:`float<class_float>` **get_output_latency** **(** **)** |const|
 
-Returns the audio driver's output latency.
+Returns the audio driver's output latency. This can be expensive, it is not recommended to call this every frame.
 
 .. rst-class:: classref-item-separator
 

classes/class_basebutton.rst

@@ -66,7 +66,7 @@ Methods
    +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+
    | void                                      | :ref:`_pressed<class_BaseButton_method__pressed>` **(** **)** |virtual|                                                 |
    +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+
-   | void                                      | :ref:`_toggled<class_BaseButton_method__toggled>` **(** :ref:`bool<class_bool>` button_pressed **)** |virtual|          |
+   | void                                      | :ref:`_toggled<class_BaseButton_method__toggled>` **(** :ref:`bool<class_bool>` toggled_on **)** |virtual|              |
    +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+
    | :ref:`DrawMode<enum_BaseButton_DrawMode>` | :ref:`get_draw_mode<class_BaseButton_method_get_draw_mode>` **(** **)** |const|                                         |
    +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------+
@@ -126,9 +126,9 @@ If you need to know the button's pressed state (and :ref:`toggle_mode<class_Base
 
 .. rst-class:: classref-signal
 
-**toggled** **(** :ref:`bool<class_bool>` button_pressed **)**
+**toggled** **(** :ref:`bool<class_bool>` toggled_on **)**
 
-Emitted when the button was just toggled between pressed and normal states (only if :ref:`toggle_mode<class_BaseButton_property_toggle_mode>` is active). The new state is contained in the ``button_pressed`` argument.
+Emitted when the button was just toggled between pressed and normal states (only if :ref:`toggle_mode<class_BaseButton_property_toggle_mode>` is active). The new state is contained in the ``toggled_on`` argument.
 
 .. rst-class:: classref-section-separator
 
@@ -419,7 +419,7 @@ Called when the button is pressed. If you need to know the button's pressed stat
 
 .. rst-class:: classref-method
 
-void **_toggled** **(** :ref:`bool<class_bool>` button_pressed **)** |virtual|
+void **_toggled** **(** :ref:`bool<class_bool>` toggled_on **)** |virtual|
 
 Called when the button is toggled (only if :ref:`toggle_mode<class_BaseButton_property_toggle_mode>` is active).
 

classes/class_bone2d.rst

@@ -192,7 +192,7 @@ void **set_bone_angle** **(** :ref:`float<class_float>` angle **)**
 
 Sets the bone angle for the **Bone2D**. This is typically set to the rotation from the **Bone2D** to a child **Bone2D** node.
 
-\ **Note:** **Note:** This is different from the **Bone2D**'s rotation. The bone's angle is the rotation of the bone shown by the gizmo, which is unaffected by the **Bone2D**'s :ref:`Node2D.transform<class_Node2D_property_transform>`.
+\ **Note:** This is different from the **Bone2D**'s rotation. The bone's angle is the rotation of the bone shown by the gizmo, which is unaffected by the **Bone2D**'s :ref:`Node2D.transform<class_Node2D_property_transform>`.
 
 .. rst-class:: classref-item-separator
 

classes/class_bool.rst

@@ -17,56 +17,62 @@ A built-in boolean type.
 Description
 -----------
 
-A **bool** is always one of two values: ``true`` or ``false``, similar to a switch that is either on or off. Booleans are used in programming for logic in condition statements.
+The **bool** is a built-in :ref:`Variant<class_Variant>` type that may only store one of two values: ``true`` or ``false``. You can imagine it as a switch that can be either turned on or off, or as a binary digit that can either be 1 or 0.
 
-Booleans can be directly used in ``if`` and ``elif`` statements. You don't need to add ``== true`` or ``== false``:
+Booleans can be directly used in ``if``, and other conditional statements:
 
 
 .. tabs::
 
  .. code-tab:: gdscript
 
+    var can_shoot = true
     if can_shoot:
         launch_bullet()
 
  .. code-tab:: csharp
 
+    bool canShoot = true;
     if (canShoot)
     {
-        launchBullet();
+        LaunchBullet();
     }
 
 
 
-Many common methods and operations return **bool**\ s, for example, ``shooting_cooldown <= 0.0`` may evaluate to ``true`` or ``false`` depending on the number's value.
+All comparison operators return booleans (``==``, ``>``, ``<=``, etc.). As such, it is not necessary to compare booleans themselves. You do not need to add ``== true`` or ``== false``.
 
-\ **bool**\ s are usually used with the logical operators ``and``, ``or``, and ``not`` to create complex conditions:
+Booleans can be combined with the logical operators ``and``, ``or``, ``not`` to create complex conditions:
 
 
 .. tabs::
 
  .. code-tab:: gdscript
 
-    if bullets > 0 and not is_reloading:
+    if bullets > 0 and not is_reloading():
         launch_bullet()
 
-    if bullets == 0 or is_reloading:
+    if bullets == 0 or is_reloading():
         play_clack_sound()
 
  .. code-tab:: csharp
 
-    if (bullets > 0 && !isReloading)
+    if (bullets > 0 && !IsReloading())
     {
-        launchBullet();
+        LaunchBullet();
     }
 
-    if (bullets == 0 || isReloading)
+    if (bullets == 0 || IsReloading())
     {
-        playClackSound();
+        PlayClackSound();
     }
 
 
 
+\ **Note:** In modern programming languages, logical operators are evaluated in order. All remaining conditions are skipped if their result would have no effect on the final value. This concept is known as `short-circuit evaluation <https://en.wikipedia.org/wiki/Short-circuit_evaluation>`__ and can be useful to avoid evaluating expensive conditions in some performance-critical cases.
+
+\ **Note:** By convention, built-in methods and properties that return booleans are usually defined as yes-no questions, single adjectives, or similar (:ref:`String.is_empty<class_String_method_is_empty>`, :ref:`Node.can_process<class_Node_method_can_process>`, :ref:`Camera2D.enabled<class_Camera2D_property_enabled>`, etc.).
+
 .. rst-class:: classref-reftable-group
 
 Constructors
@@ -118,7 +124,7 @@ Constructor Descriptions
 
 :ref:`bool<class_bool>` **bool** **(** **)**
 
-Constructs a default-initialized **bool** set to ``false``.
+Constructs a **bool** set to ``false``.
 
 .. rst-class:: classref-item-separator
 
@@ -138,7 +144,7 @@ Constructs a **bool** as a copy of the given **bool**.
 
 :ref:`bool<class_bool>` **bool** **(** :ref:`float<class_float>` from **)**
 
-Cast a :ref:`float<class_float>` value to a boolean value. This method will return ``false`` if ``0.0`` is passed in, and ``true`` for all other values.
+Cast a :ref:`float<class_float>` value to a boolean value. Returns ``false`` if ``from`` is equal to ``0.0`` (including ``-0.0``), and ``true`` for all other values (including :ref:`@GDScript.INF<class_@GDScript_constant_INF>` and :ref:`@GDScript.NAN<class_@GDScript_constant_NAN>`).
 
 .. rst-class:: classref-item-separator
 
@@ -148,7 +154,7 @@ Cast a :ref:`float<class_float>` value to a boolean value. This method will retu
 
 :ref:`bool<class_bool>` **bool** **(** :ref:`int<class_int>` from **)**
 
-Cast an :ref:`int<class_int>` value to a boolean value. This method will return ``false`` if ``0`` is passed in, and ``true`` for all other values.
+Cast an :ref:`int<class_int>` value to a boolean value. Returns ``false`` if ``from`` is equal to ``0``, and ``true`` for all other values.
 
 .. rst-class:: classref-section-separator
 
@@ -165,7 +171,7 @@ Operator Descriptions
 
 :ref:`bool<class_bool>` **operator !=** **(** :ref:`bool<class_bool>` right **)**
 
-Returns ``true`` if two bools are different, i.e. one is ``true`` and the other is ``false``.
+Returns ``true`` if the two booleans are not equal. That is, one is ``true`` and the other is ``false``. This operation can be seen as a logical XOR.
 
 .. rst-class:: classref-item-separator
 
@@ -189,7 +195,7 @@ Returns ``true`` if the left operand is ``false`` and the right operand is ``tru
 
 :ref:`bool<class_bool>` **operator ==** **(** :ref:`bool<class_bool>` right **)**
 
-Returns ``true`` if two bools are equal, i.e. both are ``true`` or both are ``false``.
+Returns ``true`` if the two booleans are equal. That is, both are ``true`` or both are ``false``. This operation can be seen as a logical EQ or XNOR.
 
 .. rst-class:: classref-item-separator