classref: Sync with current master branch (c4fb119f0)

classes/class_@gdscript.rst

@@ -199,7 +199,7 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_DIR<class_@GlobalScope_constant_PROPER
 
 **@export_enum** **(** :ref:`String<class_String>` names, ... **)** |vararg|
 
-Export an :ref:`int<class_int>` or :ref:`String<class_String>` property as an enumerated list of options. If the property is an :ref:`int<class_int>`, then the index of the value is stored, in the same order the values are provided. You can add specific identifiers for allowed values using a colon. If the property is a :ref:`String<class_String>`, then the value is stored.
+Export an :ref:`int<class_int>` or :ref:`String<class_String>` property as an enumerated list of options. If the property is an :ref:`int<class_int>`, then the index of the value is stored, in the same order the values are provided. You can add explicit values using a colon. If the property is a :ref:`String<class_String>`, then the value is stored.
 
 See also :ref:`@GlobalScope.PROPERTY_HINT_ENUM<class_@GlobalScope_constant_PROPERTY_HINT_ENUM>`.
 
@@ -281,6 +281,27 @@ See also :ref:`@GlobalScope.PROPERTY_HINT_FLAGS<class_@GlobalScope_constant_PROP
 
     @export_flags("Fire", "Water", "Earth", "Wind") var spell_elements = 0
 
+You can add explicit values using a colon:
+
+::
+
+    @export_flags("Self:4", "Allies:8", "Foes:16") var spell_targets = 0
+
+You can also combine several flags:
+
+::
+
+    @export_flags("Self:4", "Allies:8", "Self and Allies:12", "Foes:16")
+    var spell_targets = 0
+
+\ **Note:** A flag value must be at least ``1`` and at most ``2 ** 32 - 1``.
+
+\ **Note:** Unlike :ref:`@export_enum<class_@GDScript_annotation_@export_enum>`, the previous explicit value is not taken into account. In the following example, A is 16, B is 2, C is 4.
+
+::
+
+    @export_flags("A:16", "B", "C") var x
+
 .. rst-class:: classref-item-separator
 
 ----

classes/class_@globalscope.rst

@@ -3419,7 +3419,7 @@ Additionally, other keywords can be included: ``"exp"`` for exponential range ed
 
 Hints that an :ref:`int<class_int>` or :ref:`String<class_String>` property is an enumerated value to pick in a list specified via a hint string.
 
-The hint string is a comma separated list of names such as ``"Hello,Something,Else"``. Whitespaces are **not** removed from either end of a name. For integer and float properties, the first name in the list has value 0, the next 1, and so on. Explicit values can also be specified by appending ``:integer`` to the name, e.g. ``"Zero,One,Three:3,Four,Six:6"``.
+The hint string is a comma separated list of names such as ``"Hello,Something,Else"``. Whitespaces are **not** removed from either end of a name. For integer properties, the first name in the list has value 0, the next 1, and so on. Explicit values can also be specified by appending ``:integer`` to the name, e.g. ``"Zero,One,Three:3,Four,Six:6"``.
 
 .. _class_@GlobalScope_constant_PROPERTY_HINT_ENUM_SUGGESTION:
 
@@ -3453,7 +3453,13 @@ Hints that a vector property should allow its components to be linked. For examp
 
 :ref:`PropertyHint<enum_@GlobalScope_PropertyHint>` **PROPERTY_HINT_FLAGS** = ``6``
 
-Hints that an :ref:`int<class_int>` property is a bitmask with named bit flags. For example, to allow toggling bits 0, 1, 2 and 4, the hint could be something like ``"Bit0,Bit1,Bit2,,Bit4"``.
+Hints that an :ref:`int<class_int>` property is a bitmask with named bit flags.
+
+The hint string is a comma separated list of names such as ``"Bit0,Bit1,Bit2,Bit3"``. Whitespaces are **not** removed from either end of a name. The first name in the list has value 1, the next 2, then 4, 8, 16 and so on. Explicit values can also be specified by appending ``:integer`` to the name, e.g. ``"A:4,B:8,C:16"``. You can also combine several flags (``"A:4,B:8,AB:12,C:16"``).
+
+\ **Note:** A flag value must be at least ``1`` and at most ``2 ** 32 - 1``.
+
+\ **Note:** Unlike :ref:`PROPERTY_HINT_ENUM<class_@GlobalScope_constant_PROPERTY_HINT_ENUM>`, the previous explicit value is not taken into account. For the hint ``"A:16,B,C"``, A is 16, B is 2, C is 4.
 
 .. _class_@GlobalScope_constant_PROPERTY_HINT_LAYERS_2D_RENDER:
 

classes/class_audiostreamplayer2d.rst

@@ -19,7 +19,7 @@ Plays positional sound in 2D space.
 Description
 -----------
 
-Plays audio that dampens with distance from a given position.
+Plays audio that is attenuated with distance to the listener.
 
 By default, audio is heard from the screen center. This can be changed by adding an :ref:`AudioListener2D<class_AudioListener2D>` node to the scene and enabling it by calling :ref:`AudioListener2D.make_current<class_AudioListener2D_method_make_current>` on it.
 
@@ -144,7 +144,7 @@ Determines which :ref:`Area2D<class_Area2D>` layers affect the sound for reverb
 - void **set_attenuation** **(** :ref:`float<class_float>` value **)**
 - :ref:`float<class_float>` **get_attenuation** **(** **)**
 
-Dampens audio over distance with this as an exponent.
+The volume is attenuated over distance with this as an exponent.
 
 .. rst-class:: classref-item-separator
 
@@ -315,7 +315,7 @@ If ``true``, the playback is paused. You can resume it by setting ``stream_pause
 - void **set_volume_db** **(** :ref:`float<class_float>` value **)**
 - :ref:`float<class_float>` **get_volume_db** **(** **)**
 
-Base volume without dampening.
+Base volume before attenuation.
 
 .. rst-class:: classref-section-separator
 

classes/class_audiostreamplayer3d.rst

@@ -19,7 +19,7 @@ Plays positional sound in 3D space.
 Description
 -----------
 
-Plays a sound effect with directed sound effects, dampens with distance if needed, generates effect of hearable position in space. For greater realism, a low-pass filter is automatically applied to distant sounds. This can be disabled by setting :ref:`attenuation_filter_cutoff_hz<class_AudioStreamPlayer3D_property_attenuation_filter_cutoff_hz>` to ``20500``.
+Plays audio with positional sound effects, based on the relative position of the audio listener. Positional effects include distance attenuation, directionality, and the Doppler effect. For greater realism, a low-pass filter is applied to distant sounds. This can be disabled by setting :ref:`attenuation_filter_cutoff_hz<class_AudioStreamPlayer3D_property_attenuation_filter_cutoff_hz>` to ``20500``.
 
 By default, audio is heard from the camera position. This can be changed by adding an :ref:`AudioListener3D<class_AudioListener3D>` node to the scene and enabling it by calling :ref:`AudioListener3D.make_current<class_AudioListener3D_method_make_current>` on it.
 
@@ -144,31 +144,31 @@ enum **AttenuationModel**:
 
 :ref:`AttenuationModel<enum_AudioStreamPlayer3D_AttenuationModel>` **ATTENUATION_INVERSE_DISTANCE** = ``0``
 
-Linear dampening of loudness according to distance.
+Attenuation of loudness according to linear distance.
 
 .. _class_AudioStreamPlayer3D_constant_ATTENUATION_INVERSE_SQUARE_DISTANCE:
 
 .. rst-class:: classref-enumeration-constant
 
 :ref:`AttenuationModel<enum_AudioStreamPlayer3D_AttenuationModel>` **ATTENUATION_INVERSE_SQUARE_DISTANCE** = ``1``
 
-Squared dampening of loudness according to distance.
+Attenuation of loudness according to squared distance.
 
 .. _class_AudioStreamPlayer3D_constant_ATTENUATION_LOGARITHMIC:
 
 .. rst-class:: classref-enumeration-constant
 
 :ref:`AttenuationModel<enum_AudioStreamPlayer3D_AttenuationModel>` **ATTENUATION_LOGARITHMIC** = ``2``
 
-Logarithmic dampening of loudness according to distance.
+Attenuation of loudness according to logarithmic distance.
 
 .. _class_AudioStreamPlayer3D_constant_ATTENUATION_DISABLED:
 
 .. rst-class:: classref-enumeration-constant
 
 :ref:`AttenuationModel<enum_AudioStreamPlayer3D_AttenuationModel>` **ATTENUATION_DISABLED** = ``3``
 
-No dampening of loudness according to distance. The sound will still be heard positionally, unlike an :ref:`AudioStreamPlayer<class_AudioStreamPlayer>`. :ref:`ATTENUATION_DISABLED<class_AudioStreamPlayer3D_constant_ATTENUATION_DISABLED>` can be combined with a :ref:`max_distance<class_AudioStreamPlayer3D_property_max_distance>` value greater than ``0.0`` to achieve linear attenuation clamped to a sphere of a defined size.
+No attenuation of loudness according to distance. The sound will still be heard positionally, unlike an :ref:`AudioStreamPlayer<class_AudioStreamPlayer>`. :ref:`ATTENUATION_DISABLED<class_AudioStreamPlayer3D_constant_ATTENUATION_DISABLED>` can be combined with a :ref:`max_distance<class_AudioStreamPlayer3D_property_max_distance>` value greater than ``0.0`` to achieve linear attenuation clamped to a sphere of a defined size.
 
 .. rst-class:: classref-item-separator
 
@@ -241,7 +241,7 @@ Determines which :ref:`Area3D<class_Area3D>` layers affect the sound for reverb
 - void **set_attenuation_filter_cutoff_hz** **(** :ref:`float<class_float>` value **)**
 - :ref:`float<class_float>` **get_attenuation_filter_cutoff_hz** **(** **)**
 
-Dampens audio using a low-pass filter above this frequency, in Hz. To disable the dampening effect entirely, set this to ``20500`` as this frequency is above the human hearing limit.
+The cutoff frequency of the attenuation low-pass filter, in Hz. A sound above this frequency is attenuated more than a sound below this frequency. To disable this effect, set this to ``20500`` as this frequency is above the human hearing limit.
 
 .. rst-class:: classref-item-separator
 
@@ -345,7 +345,7 @@ Decides in which step the Doppler effect should be calculated.
 - void **set_emission_angle** **(** :ref:`float<class_float>` value **)**
 - :ref:`float<class_float>` **get_emission_angle** **(** **)**
 
-The angle in which the audio reaches cameras undampened.
+The angle in which the audio reaches a listener unattenuated.
 
 .. rst-class:: classref-item-separator
 
@@ -362,7 +362,7 @@ The angle in which the audio reaches cameras undampened.
 - void **set_emission_angle_enabled** **(** :ref:`bool<class_bool>` value **)**
 - :ref:`bool<class_bool>` **is_emission_angle_enabled** **(** **)**
 
-If ``true``, the audio should be dampened according to the direction of the sound.
+If ``true``, the audio should be attenuated according to the direction of the sound.
 
 .. rst-class:: classref-item-separator
 
@@ -379,7 +379,7 @@ If ``true``, the audio should be dampened according to the direction of the soun
 - void **set_emission_angle_filter_attenuation_db** **(** :ref:`float<class_float>` value **)**
 - :ref:`float<class_float>` **get_emission_angle_filter_attenuation_db** **(** **)**
 
-Dampens audio if camera is outside of :ref:`emission_angle_degrees<class_AudioStreamPlayer3D_property_emission_angle_degrees>` and :ref:`emission_angle_enabled<class_AudioStreamPlayer3D_property_emission_angle_enabled>` is set by this factor, in decibels.
+Attenuation factor used if listener is outside of :ref:`emission_angle_degrees<class_AudioStreamPlayer3D_property_emission_angle_degrees>` and :ref:`emission_angle_enabled<class_AudioStreamPlayer3D_property_emission_angle_enabled>` is set, in decibels.
 
 .. rst-class:: classref-item-separator
 
@@ -548,7 +548,7 @@ The factor for the attenuation effect. Higher values make the sound audible over
 - void **set_volume_db** **(** :ref:`float<class_float>` value **)**
 - :ref:`float<class_float>` **get_volume_db** **(** **)**
 
-The base sound level unaffected by dampening, in decibels.
+The base sound level before attenuation, in decibels.
 
 .. rst-class:: classref-section-separator