classref: Sync with current master branch (1ce6df7)

classes/class_audiostreamplaylist.rst

@@ -12,7 +12,7 @@ AudioStreamPlaylist
 
 **Inherits:** :ref:`AudioStream<class_AudioStream>` **<** :ref:`Resource<class_Resource>` **<** :ref:`RefCounted<class_RefCounted>` **<** :ref:`Object<class_Object>`
 
-:ref:`AudioStream<class_AudioStream>` that includes sub-streams and plays them back like a playslit.
+:ref:`AudioStream<class_AudioStream>` that includes sub-streams and plays them back like a playlist.
 
 .. rst-class:: classref-reftable-group
 
@@ -102,7 +102,7 @@ Fade time used when a stream ends, when going to the next one. Streams are expec
 - |void| **set_loop**\ (\ value\: :ref:`bool<class_bool>`\ )
 - :ref:`bool<class_bool>` **has_loop**\ (\ )
 
-If true, the playlist will loop, otherwise the playlist when end when the last stream is played.
+If ``true``, the playlist will loop, otherwise the playlist will end when the last stream is finished.
 
 .. rst-class:: classref-item-separator
 
@@ -119,7 +119,7 @@ If true, the playlist will loop, otherwise the playlist when end when the last s
 - |void| **set_shuffle**\ (\ value\: :ref:`bool<class_bool>`\ )
 - :ref:`bool<class_bool>` **get_shuffle**\ (\ )
 
-Shuffle the playlist. Streams are played in random order.
+If ``true``, the playlist will shuffle each time playback starts and each time it loops.
 
 .. rst-class:: classref-item-separator
 
@@ -153,7 +153,7 @@ Method Descriptions
 
 :ref:`float<class_float>` **get_bpm**\ (\ ) |const| :ref:`🔗<class_AudioStreamPlaylist_method_get_bpm>`
 
-Return the bpm of the playlist, which can vary depending on the clip being played.
+Returns the BPM of the playlist, which can vary depending on the clip being played.
 
 .. rst-class:: classref-item-separator
 
@@ -165,7 +165,7 @@ Return the bpm of the playlist, which can vary depending on the clip being playe
 
 :ref:`AudioStream<class_AudioStream>` **get_list_stream**\ (\ stream_index\: :ref:`int<class_int>`\ ) |const| :ref:`🔗<class_AudioStreamPlaylist_method_get_list_stream>`
 
-Get the stream at playback position index.
+Returns the stream at playback position index.
 
 .. rst-class:: classref-item-separator
 
@@ -177,7 +177,7 @@ Get the stream at playback position index.
 
 |void| **set_list_stream**\ (\ stream_index\: :ref:`int<class_int>`, audio_stream\: :ref:`AudioStream<class_AudioStream>`\ ) :ref:`🔗<class_AudioStreamPlaylist_method_set_list_stream>`
 
-Set the stream at playback position index.
+Sets the stream at playback position index.
 
 .. |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_nativemenu.rst

@@ -144,6 +144,8 @@ Methods
    +-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    | :ref:`bool<class_bool>`           | :ref:`is_item_radio_checkable<class_NativeMenu_method_is_item_radio_checkable>`\ (\ rid\: :ref:`RID<class_RID>`, idx\: :ref:`int<class_int>`\ ) |const|                                                                                                                                                                                                                                                                                                                               |
    +-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+   | :ref:`bool<class_bool>`           | :ref:`is_opened<class_NativeMenu_method_is_opened>`\ (\ rid\: :ref:`RID<class_RID>`\ ) |const|                                                                                                                                                                                                                                                                                                                                                                                        |
+   +-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    | :ref:`bool<class_bool>`           | :ref:`is_system_menu<class_NativeMenu_method_is_system_menu>`\ (\ rid\: :ref:`RID<class_RID>`\ ) |const|                                                                                                                                                                                                                                                                                                                                                                              |
    +-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
    | |void|                            | :ref:`popup<class_NativeMenu_method_popup>`\ (\ rid\: :ref:`RID<class_RID>`, position\: :ref:`Vector2i<class_Vector2i>`\ )                                                                                                                                                                                                                                                                                                                                                            |
@@ -963,6 +965,20 @@ Returns ``true`` if the item at index ``idx`` has radio button-style checkabilit
 
 ----
 
+.. _class_NativeMenu_method_is_opened:
+
+.. rst-class:: classref-method
+
+:ref:`bool<class_bool>` **is_opened**\ (\ rid\: :ref:`RID<class_RID>`\ ) |const| :ref:`🔗<class_NativeMenu_method_is_opened>`
+
+Returns ``true`` if the menu is currently opened.
+
+\ **Note:** This method is implemented only on macOS.
+
+.. rst-class:: classref-item-separator
+
+----
+
 .. _class_NativeMenu_method_is_system_menu:
 
 .. rst-class:: classref-method
@@ -1291,6 +1307,8 @@ Sets the minimum width of the global menu.
 
 Registers callable to emit when the menu is about to show.
 
+\ **Note:** The OS can simulate menu opening to track menu item changes and global shortcuts, in which case the corresponding close callback is not triggered. Use :ref:`is_opened<class_NativeMenu_method_is_opened>` to check if the menu is currently opened.
+
 \ **Note:** This method is implemented only on macOS.
 
 .. rst-class:: classref-item-separator
@@ -1303,7 +1321,7 @@ Registers callable to emit when the menu is about to show.
 
 |void| **set_popup_open_callback**\ (\ rid\: :ref:`RID<class_RID>`, callback\: :ref:`Callable<class_Callable>`\ ) :ref:`🔗<class_NativeMenu_method_set_popup_open_callback>`
 
-Registers callable to emit when the menu is about to closed.
+Registers callable to emit after the menu is closed.
 
 \ **Note:** This method is implemented only on macOS.
 

classes/class_omnilight3d.rst

@@ -108,9 +108,9 @@ Property Descriptions
 
 Controls the distance attenuation function for omnilights.
 
-A value of ``0.0`` smoothly attenuates light at the edge of the range. A value of ``1.0`` approaches a physical lighting model. A value of ``0.5`` approximates linear attenuation.
+A value of ``0.0`` will maintain a constant brightness through most of the range, but smoothly attenuate the light at the edge of the range. Use a value of ``2.0`` for physically accurate lights as it results in the proper inverse square attenutation.
 
-\ **Note:** Setting it to ``1.0`` may result in distant objects receiving minimal light, even within range. For example, with a range of ``4096``, an object at ``100`` units receives less than ``0.1`` energy.
+\ **Note:** Setting attenuation to ``2.0`` or higher may result in distant objects receiving minimal light, even within range. For example, with a range of ``4096``, an object at ``100`` units is attenuated by a factor of ``0.0001``. With a default brightness of ``1``, the light would not be visible at that distance.
 
 \ **Note:** Using negative or values higher than ``10.0`` may lead to unexpected results.
 

classes/class_physicalskymaterial.rst

@@ -23,8 +23,6 @@ The **PhysicalSkyMaterial** uses the Preetham analytic daylight model to draw a
 
 The **PhysicalSkyMaterial** only supports one sun. The color, energy, and direction of the sun are taken from the first :ref:`DirectionalLight3D<class_DirectionalLight3D>` in the scene tree.
 
-As it is based on a daylight model, the sky fades to black as the sunset ends. If you want a full day/night cycle, you will have to add a night sky by converting this to a :ref:`ShaderMaterial<class_ShaderMaterial>` and adding a night sky directly into the resulting shader.
-
 .. rst-class:: classref-reftable-group
 
 Properties

classes/class_spotlight3d.rst

@@ -116,9 +116,9 @@ The spotlight's *angular* attenuation curve. See also :ref:`spot_attenuation<cla
 
 Controls the distance attenuation function for spotlights.
 
-A value of ``0.0`` smoothly attenuates light at the edge of the range. A value of ``1.0`` approaches a physical lighting model. A value of ``0.5`` approximates linear attenuation.
+A value of ``0.0`` will maintain a constant brightness through most of the range, but smoothly attenuate the light at the edge of the range. Use a value of ``2.0`` for physically accurate lights as it results in the proper inverse square attenutation.
 
-\ **Note:** Setting it to ``1.0`` may result in distant objects receiving minimal light, even within range. For example, with a range of ``4096``, an object at ``100`` units receives less than ``0.1`` energy.
+\ **Note:** Setting attenuation to ``2.0`` or higher may result in distant objects receiving minimal light, even within range. For example, with a range of ``4096``, an object at ``100`` units is attenuated by a factor of ``0.0001``. With a default brightness of ``1``, the light would not be visible at that distance.
 
 \ **Note:** Using negative or values higher than ``10.0`` may lead to unexpected results.
 

classes/class_vector2.rst

@@ -856,7 +856,7 @@ Returns a new vector moved toward ``to`` by the fixed ``delta`` amount. Will not
 
 :ref:`Vector2<class_Vector2>` **normalized**\ (\ ) |const| :ref:`🔗<class_Vector2_method_normalized>`
 
-Returns the result of scaling the vector to unit length. Equivalent to ``v / v.length()``. See also :ref:`is_normalized<class_Vector2_method_is_normalized>`.
+Returns the result of scaling the vector to unit length. Equivalent to ``v / v.length()``. Returns ``(0, 0)`` if ``v.length() == 0``. See also :ref:`is_normalized<class_Vector2_method_is_normalized>`.
 
 \ **Note:** This function may return incorrect values if the input vector length is near zero.
 

classes/class_vector3.rst

@@ -890,7 +890,7 @@ Returns a new vector moved toward ``to`` by the fixed ``delta`` amount. Will not
 
 :ref:`Vector3<class_Vector3>` **normalized**\ (\ ) |const| :ref:`🔗<class_Vector3_method_normalized>`
 
-Returns the result of scaling the vector to unit length. Equivalent to ``v / v.length()``. See also :ref:`is_normalized<class_Vector3_method_is_normalized>`.
+Returns the result of scaling the vector to unit length. Equivalent to ``v / v.length()``. Returns ``(0, 0, 0)`` if ``v.length() == 0``. See also :ref:`is_normalized<class_Vector3_method_is_normalized>`.
 
 \ **Note:** This function may return incorrect values if the input vector length is near zero.
 

classes/class_vector4.rst

@@ -669,7 +669,7 @@ Returns the component-wise minimum of this and ``with``, equivalent to ``Vector4
 
 :ref:`Vector4<class_Vector4>` **normalized**\ (\ ) |const| :ref:`🔗<class_Vector4_method_normalized>`
 
-Returns the result of scaling the vector to unit length. Equivalent to ``v / v.length()``. See also :ref:`is_normalized<class_Vector4_method_is_normalized>`.
+Returns the result of scaling the vector to unit length. Equivalent to ``v / v.length()``. Returns ``(0, 0, 0, 0)`` if ``v.length() == 0``. See also :ref:`is_normalized<class_Vector4_method_is_normalized>`.
 
 \ **Note:** This function may return incorrect values if the input vector length is near zero.