classref: Sync with current master branch (4e990cd)

classes/class_@gdscript.rst

@@ -662,7 +662,7 @@ Add a custom icon to the current script. The icon specified at ``icon_path`` is
 
 \ **Note:** As annotations describe their subject, the :ref:`@icon<class_@GDScript_annotation_@icon>` annotation must be placed before the class definition and inheritance.
 
-\ **Note:** Unlike most other annotations, the argument of the :ref:`@icon<class_@GDScript_annotation_@icon>` annotation must be a string literal (constant expressions are not supported).
+\ **Note:** Unlike other annotations, the argument of the :ref:`@icon<class_@GDScript_annotation_@icon>` annotation must be a string literal (constant expressions are not supported).
 
 .. rst-class:: classref-item-separator
 
@@ -748,20 +748,6 @@ Mark the current script as a tool script, allowing it to be loaded and executed
 
 ----
 
-.. _class_@GDScript_annotation_@uid:
-
-.. rst-class:: classref-annotation
-
-**@uid** **(** :ref:`String<class_String>` uid **)**
-
-Stores information about UID of this script. This annotation is auto-generated when saving the script and must not be modified manually. Only applies to scripts saved as separate files (i.e. not built-in).
-
-\ **Note:** Unlike most other annotations, the argument of the :ref:`@uid<class_@GDScript_annotation_@uid>` annotation must be a string literal (constant expressions are not supported).
-
-.. rst-class:: classref-item-separator
-
-----
-
 .. _class_@GDScript_annotation_@warning_ignore:
 
 .. rst-class:: classref-annotation

classes/class_@globalscope.rst

@@ -2393,6 +2393,42 @@ Group Switch key mask.
 
 ----
 
+.. _enum_@GlobalScope_KeyLocation:
+
+.. rst-class:: classref-enumeration
+
+enum **KeyLocation**:
+
+.. _class_@GlobalScope_constant_KEY_LOCATION_UNSPECIFIED:
+
+.. rst-class:: classref-enumeration-constant
+
+:ref:`KeyLocation<enum_@GlobalScope_KeyLocation>` **KEY_LOCATION_UNSPECIFIED** = ``0``
+
+Used for keys which only appear once, or when a comparison doesn't need to differentiate the ``LEFT`` and ``RIGHT`` versions.
+
+For example, when using :ref:`InputEvent.is_match<class_InputEvent_method_is_match>`, an event which has :ref:`KEY_LOCATION_UNSPECIFIED<class_@GlobalScope_constant_KEY_LOCATION_UNSPECIFIED>` will match any :ref:`KeyLocation<enum_@GlobalScope_KeyLocation>` on the passed event.
+
+.. _class_@GlobalScope_constant_KEY_LOCATION_LEFT:
+
+.. rst-class:: classref-enumeration-constant
+
+:ref:`KeyLocation<enum_@GlobalScope_KeyLocation>` **KEY_LOCATION_LEFT** = ``1``
+
+A key which is to the left of its twin.
+
+.. _class_@GlobalScope_constant_KEY_LOCATION_RIGHT:
+
+.. rst-class:: classref-enumeration-constant
+
+:ref:`KeyLocation<enum_@GlobalScope_KeyLocation>` **KEY_LOCATION_RIGHT** = ``2``
+
+A key which is to the right of its twin.
+
+.. rst-class:: classref-item-separator
+
+----
+
 .. _enum_@GlobalScope_MouseButton:
 
 .. rst-class:: classref-enumeration
@@ -2835,151 +2871,161 @@ enum **MIDIMessage**:
 
 :ref:`MIDIMessage<enum_@GlobalScope_MIDIMessage>` **MIDI_MESSAGE_NONE** = ``0``
 
-Enum value which doesn't correspond to any MIDI message. This is used to initialize :ref:`MIDIMessage<enum_@GlobalScope_MIDIMessage>` properties with a generic state.
+Does not correspond to any MIDI message. This is the default value of :ref:`InputEventMIDI.message<class_InputEventMIDI_property_message>`.
 
 .. _class_@GlobalScope_constant_MIDI_MESSAGE_NOTE_OFF:
 
 .. rst-class:: classref-enumeration-constant
 
 :ref:`MIDIMessage<enum_@GlobalScope_MIDIMessage>` **MIDI_MESSAGE_NOTE_OFF** = ``8``
 
-MIDI note OFF message. Not all MIDI devices send this event; some send :ref:`MIDI_MESSAGE_NOTE_ON<class_@GlobalScope_constant_MIDI_MESSAGE_NOTE_ON>` with zero velocity instead. See the documentation of :ref:`InputEventMIDI<class_InputEventMIDI>` for information of how to use MIDI inputs.
+MIDI message sent when a note is released.
+
+\ **Note:** Not all MIDI devices send this message; some may send :ref:`MIDI_MESSAGE_NOTE_ON<class_@GlobalScope_constant_MIDI_MESSAGE_NOTE_ON>` with :ref:`InputEventMIDI.velocity<class_InputEventMIDI_property_velocity>` set to ``0``.
 
 .. _class_@GlobalScope_constant_MIDI_MESSAGE_NOTE_ON:
 
 .. rst-class:: classref-enumeration-constant
 
 :ref:`MIDIMessage<enum_@GlobalScope_MIDIMessage>` **MIDI_MESSAGE_NOTE_ON** = ``9``
 
-MIDI note ON message. Some MIDI devices send this event with velocity zero instead of :ref:`MIDI_MESSAGE_NOTE_OFF<class_@GlobalScope_constant_MIDI_MESSAGE_NOTE_OFF>`, but implementations vary. See the documentation of :ref:`InputEventMIDI<class_InputEventMIDI>` for information of how to use MIDI inputs.
+MIDI message sent when a note is pressed.
 
 .. _class_@GlobalScope_constant_MIDI_MESSAGE_AFTERTOUCH:
 
 .. rst-class:: classref-enumeration-constant
 
 :ref:`MIDIMessage<enum_@GlobalScope_MIDIMessage>` **MIDI_MESSAGE_AFTERTOUCH** = ``10``
 
-MIDI aftertouch message. This message is most often sent by pressing down on the key after it "bottoms out".
+MIDI message sent to indicate a change in pressure while a note is being pressed down, also called aftertouch.
 
 .. _class_@GlobalScope_constant_MIDI_MESSAGE_CONTROL_CHANGE:
 
 .. rst-class:: classref-enumeration-constant
 
 :ref:`MIDIMessage<enum_@GlobalScope_MIDIMessage>` **MIDI_MESSAGE_CONTROL_CHANGE** = ``11``
 
-MIDI control change message. This message is sent when a controller value changes. Controllers include devices such as pedals and levers.
+MIDI message sent when a controller value changes. In a MIDI device, a controller is any input that doesn't play notes. These may include sliders for volume, balance, and panning, as well as switches and pedals. See the `General MIDI specification <https://en.wikipedia.org/wiki/General_MIDI#Controller_events>`__ for a small list.
 
 .. _class_@GlobalScope_constant_MIDI_MESSAGE_PROGRAM_CHANGE:
 
 .. rst-class:: classref-enumeration-constant
 
 :ref:`MIDIMessage<enum_@GlobalScope_MIDIMessage>` **MIDI_MESSAGE_PROGRAM_CHANGE** = ``12``
 
-MIDI program change message. This message sent when the program patch number changes.
+MIDI message sent when the MIDI device changes its current instrument (also called *program* or *preset*).
 
 .. _class_@GlobalScope_constant_MIDI_MESSAGE_CHANNEL_PRESSURE:
 
 .. rst-class:: classref-enumeration-constant
 
 :ref:`MIDIMessage<enum_@GlobalScope_MIDIMessage>` **MIDI_MESSAGE_CHANNEL_PRESSURE** = ``13``
 
-MIDI channel pressure message. This message is most often sent by pressing down on the key after it "bottoms out". This message is different from polyphonic after-touch as it indicates the highest pressure across all keys.
+MIDI message sent to indicate a change in pressure for the whole channel. Some MIDI devices may send this instead of :ref:`MIDI_MESSAGE_AFTERTOUCH<class_@GlobalScope_constant_MIDI_MESSAGE_AFTERTOUCH>`.
 
 .. _class_@GlobalScope_constant_MIDI_MESSAGE_PITCH_BEND:
 
 .. rst-class:: classref-enumeration-constant
 
 :ref:`MIDIMessage<enum_@GlobalScope_MIDIMessage>` **MIDI_MESSAGE_PITCH_BEND** = ``14``
 
-MIDI pitch bend message. This message is sent to indicate a change in the pitch bender (wheel or lever, typically).
+MIDI message sent when the value of the pitch bender changes, usually a wheel on the MIDI device.
 
 .. _class_@GlobalScope_constant_MIDI_MESSAGE_SYSTEM_EXCLUSIVE:
 
 .. rst-class:: classref-enumeration-constant
 
 :ref:`MIDIMessage<enum_@GlobalScope_MIDIMessage>` **MIDI_MESSAGE_SYSTEM_EXCLUSIVE** = ``240``
 
-MIDI system exclusive message. This has behavior exclusive to the device you're receiving input from. Getting this data is not implemented in Godot.
+MIDI system exclusive (SysEx) message. This type of message is not standardized and it's highly dependent on the MIDI device sending it.
+
+\ **Note:** Getting this message's data from :ref:`InputEventMIDI<class_InputEventMIDI>` is not implemented.
 
 .. _class_@GlobalScope_constant_MIDI_MESSAGE_QUARTER_FRAME:
 
 .. rst-class:: classref-enumeration-constant
 
 :ref:`MIDIMessage<enum_@GlobalScope_MIDIMessage>` **MIDI_MESSAGE_QUARTER_FRAME** = ``241``
 
-MIDI quarter frame message. Contains timing information that is used to synchronize MIDI devices. Getting this data is not implemented in Godot.
+MIDI message sent every quarter frame to keep connected MIDI devices synchronized. Related to :ref:`MIDI_MESSAGE_TIMING_CLOCK<class_@GlobalScope_constant_MIDI_MESSAGE_TIMING_CLOCK>`.
+
+\ **Note:** Getting this message's data from :ref:`InputEventMIDI<class_InputEventMIDI>` is not implemented.
 
 .. _class_@GlobalScope_constant_MIDI_MESSAGE_SONG_POSITION_POINTER:
 
 .. rst-class:: classref-enumeration-constant
 
 :ref:`MIDIMessage<enum_@GlobalScope_MIDIMessage>` **MIDI_MESSAGE_SONG_POSITION_POINTER** = ``242``
 
-MIDI song position pointer message. Gives the number of 16th notes since the start of the song. Getting this data is not implemented in Godot.
+MIDI message sent to jump onto a new position in the current sequence or song.
+
+\ **Note:** Getting this message's data from :ref:`InputEventMIDI<class_InputEventMIDI>` is not implemented.
 
 .. _class_@GlobalScope_constant_MIDI_MESSAGE_SONG_SELECT:
 
 .. rst-class:: classref-enumeration-constant
 
 :ref:`MIDIMessage<enum_@GlobalScope_MIDIMessage>` **MIDI_MESSAGE_SONG_SELECT** = ``243``
 
-MIDI song select message. Specifies which sequence or song is to be played. Getting this data is not implemented in Godot.
+MIDI message sent to select a sequence or song to play.
+
+\ **Note:** Getting this message's data from :ref:`InputEventMIDI<class_InputEventMIDI>` is not implemented.
 
 .. _class_@GlobalScope_constant_MIDI_MESSAGE_TUNE_REQUEST:
 
 .. rst-class:: classref-enumeration-constant
 
 :ref:`MIDIMessage<enum_@GlobalScope_MIDIMessage>` **MIDI_MESSAGE_TUNE_REQUEST** = ``246``
 
-MIDI tune request message. Upon receiving a tune request, all analog synthesizers should tune their oscillators.
+MIDI message sent to request a tuning calibration. Used on analog synthesizers. Most modern MIDI devices do not need this message.
 
 .. _class_@GlobalScope_constant_MIDI_MESSAGE_TIMING_CLOCK:
 
 .. rst-class:: classref-enumeration-constant
 
 :ref:`MIDIMessage<enum_@GlobalScope_MIDIMessage>` **MIDI_MESSAGE_TIMING_CLOCK** = ``248``
 
-MIDI timing clock message. Sent 24 times per quarter note when synchronization is required.
+MIDI message sent 24 times after :ref:`MIDI_MESSAGE_QUARTER_FRAME<class_@GlobalScope_constant_MIDI_MESSAGE_QUARTER_FRAME>`, to keep connected MIDI devices synchronized.
 
 .. _class_@GlobalScope_constant_MIDI_MESSAGE_START:
 
 .. rst-class:: classref-enumeration-constant
 
 :ref:`MIDIMessage<enum_@GlobalScope_MIDIMessage>` **MIDI_MESSAGE_START** = ``250``
 
-MIDI start message. Start the current sequence playing. This message will be followed with Timing Clocks.
+MIDI message sent to start the current sequence or song from the beginning.
 
 .. _class_@GlobalScope_constant_MIDI_MESSAGE_CONTINUE:
 
 .. rst-class:: classref-enumeration-constant
 
 :ref:`MIDIMessage<enum_@GlobalScope_MIDIMessage>` **MIDI_MESSAGE_CONTINUE** = ``251``
 
-MIDI continue message. Continue at the point the sequence was stopped.
+MIDI message sent to resume from the point the current sequence or song was paused.
 
 .. _class_@GlobalScope_constant_MIDI_MESSAGE_STOP:
 
 .. rst-class:: classref-enumeration-constant
 
 :ref:`MIDIMessage<enum_@GlobalScope_MIDIMessage>` **MIDI_MESSAGE_STOP** = ``252``
 
-MIDI stop message. Stop the current sequence.
+MIDI message sent to pause the current sequence or song.
 
 .. _class_@GlobalScope_constant_MIDI_MESSAGE_ACTIVE_SENSING:
 
 .. rst-class:: classref-enumeration-constant
 
 :ref:`MIDIMessage<enum_@GlobalScope_MIDIMessage>` **MIDI_MESSAGE_ACTIVE_SENSING** = ``254``
 
-MIDI active sensing message. This message is intended to be sent repeatedly to tell the receiver that a connection is alive.
+MIDI message sent repeatedly while the MIDI device is idle, to tell the receiver that the connection is alive. Most MIDI devices do not send this message.
 
 .. _class_@GlobalScope_constant_MIDI_MESSAGE_SYSTEM_RESET:
 
 .. rst-class:: classref-enumeration-constant
 
 :ref:`MIDIMessage<enum_@GlobalScope_MIDIMessage>` **MIDI_MESSAGE_SYSTEM_RESET** = ``255``
 
-MIDI system reset message. Reset all receivers in the system to power-up status. It should not be sent on power-up itself.
+MIDI message sent to reset a MIDI device to its default state, as if it was just turned on. It should not be sent when the MIDI device is being turned on.
 
 .. rst-class:: classref-item-separator
 
@@ -7285,6 +7331,8 @@ Encodes a :ref:`Variant<class_Variant>` value to a byte array, without encoding
 
 \ **Note:** If you need object serialization, see :ref:`var_to_bytes_with_objects<class_@GlobalScope_method_var_to_bytes_with_objects>`.
 
+\ **Note:** Encoding :ref:`Callable<class_Callable>` is not supported and will result in an empty value, regardless of the data.
+
 .. rst-class:: classref-item-separator
 
 ----
@@ -7297,6 +7345,8 @@ Encodes a :ref:`Variant<class_Variant>` value to a byte array, without encoding
 
 Encodes a :ref:`Variant<class_Variant>` value to a byte array. Encoding objects is allowed (and can potentially include executable code). Deserialization can be done with :ref:`bytes_to_var_with_objects<class_@GlobalScope_method_bytes_to_var_with_objects>`.
 
+\ **Note:** Encoding :ref:`Callable<class_Callable>` is not supported and will result in an empty value, regardless of the data.
+
 .. rst-class:: classref-item-separator
 
 ----

classes/class_animatedsprite2d.rst

@@ -113,6 +113,8 @@ Emitted when :ref:`animation<class_AnimatedSprite2D_property_animation>` changes
 
 Emitted when the animation reaches the end, or the start if it is played in reverse. When the animation finishes, it pauses the playback.
 
+\ **Note:** This signal is not emitted if an animation is looping.
+
 .. rst-class:: classref-item-separator
 
 ----

classes/class_animatedsprite3d.rst

@@ -103,6 +103,8 @@ Emitted when :ref:`animation<class_AnimatedSprite3D_property_animation>` changes
 
 Emitted when the animation reaches the end, or the start if it is played in reverse. When the animation finishes, it pauses the playback.
 
+\ **Note:** This signal is not emitted if an animation is looping.
+
 .. rst-class:: classref-item-separator
 
 ----

classes/class_audioeffect.rst

@@ -14,20 +14,24 @@ AudioEffect
 
 **Inherited By:** :ref:`AudioEffectAmplify<class_AudioEffectAmplify>`, :ref:`AudioEffectCapture<class_AudioEffectCapture>`, :ref:`AudioEffectChorus<class_AudioEffectChorus>`, :ref:`AudioEffectCompressor<class_AudioEffectCompressor>`, :ref:`AudioEffectDelay<class_AudioEffectDelay>`, :ref:`AudioEffectDistortion<class_AudioEffectDistortion>`, :ref:`AudioEffectEQ<class_AudioEffectEQ>`, :ref:`AudioEffectFilter<class_AudioEffectFilter>`, :ref:`AudioEffectLimiter<class_AudioEffectLimiter>`, :ref:`AudioEffectPanner<class_AudioEffectPanner>`, :ref:`AudioEffectPhaser<class_AudioEffectPhaser>`, :ref:`AudioEffectPitchShift<class_AudioEffectPitchShift>`, :ref:`AudioEffectRecord<class_AudioEffectRecord>`, :ref:`AudioEffectReverb<class_AudioEffectReverb>`, :ref:`AudioEffectSpectrumAnalyzer<class_AudioEffectSpectrumAnalyzer>`, :ref:`AudioEffectStereoEnhance<class_AudioEffectStereoEnhance>`
 
-Audio effect for audio.
+Base class for audio effect resources.
 
 .. rst-class:: classref-introduction-group
 
 Description
 -----------
 
-Base resource for audio bus. Applies an audio effect on the bus that the resource is applied on.
+The base :ref:`Resource<class_Resource>` for every audio effect. In the editor, an audio effect can be added to the current bus layout through the Audio panel. At run-time, it is also possible to manipulate audio effects through :ref:`AudioServer.add_bus_effect<class_AudioServer_method_add_bus_effect>`, :ref:`AudioServer.remove_bus_effect<class_AudioServer_method_remove_bus_effect>`, and :ref:`AudioServer.get_bus_effect<class_AudioServer_method_get_bus_effect>`.
+
+When applied on a bus, an audio effect creates a corresponding :ref:`AudioEffectInstance<class_AudioEffectInstance>`. The instance is directly responsible for manipulating the sound, based on the original audio effect's properties.
 
 .. rst-class:: classref-introduction-group
 
 Tutorials
 ---------
 
+- :doc:`Audio buses <../tutorials/audio/audio_buses>`
+
 - `Audio Mic Record Demo <https://godotengine.org/asset-library/asset/527>`__
 
 .. rst-class:: classref-reftable-group
@@ -57,9 +61,21 @@ Method Descriptions
 
 :ref:`AudioEffectInstance<class_AudioEffectInstance>` **_instantiate** **(** **)** |virtual|
 
-.. container:: contribute
+Override this method to customize the :ref:`AudioEffectInstance<class_AudioEffectInstance>` created when this effect is applied on a bus in the editor's Audio panel, or through :ref:`AudioServer.add_bus_effect<class_AudioServer_method_add_bus_effect>`.
+
+::
+
+    extends AudioEffect
+
+    @export var strength = 4.0
+
+    func _instantiate():
+        var effect = CustomAudioEffectInstance.new()
+        effect.base = self
+
+        return effect
 
-	There is currently no description for this method. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!
+\ **Note:** It is recommended to keep a reference to the original **AudioEffect** in the new instance. Depending on the implementation this allows the effect instance to listen for changes at run-time and be modified accordingly.
 
 .. |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_audioeffectinstance.rst

@@ -14,9 +14,21 @@ AudioEffectInstance
 
 **Inherited By:** :ref:`AudioEffectSpectrumAnalyzerInstance<class_AudioEffectSpectrumAnalyzerInstance>`
 
-.. container:: contribute
+Manipulates the audio it receives for a given effect.
 
-	There is currently no description for this class. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!
+.. rst-class:: classref-introduction-group
+
+Description
+-----------
+
+An audio effect instance manipulates the audio it receives for a given effect. This instance is automatically created by an :ref:`AudioEffect<class_AudioEffect>` when it is added to a bus, and should usually not be created directly. If necessary, it can be fetched at run-time with :ref:`AudioServer.get_bus_effect_instance<class_AudioServer_method_get_bus_effect_instance>`.
+
+.. rst-class:: classref-introduction-group
+
+Tutorials
+---------
+
+- :doc:`Audio buses <../tutorials/audio/audio_buses>`
 
 .. rst-class:: classref-reftable-group
 
@@ -47,9 +59,9 @@ Method Descriptions
 
 void **_process** **(** const void* src_buffer, AudioFrame* dst_buffer, :ref:`int<class_int>` frame_count **)** |virtual|
 
-.. container:: contribute
+Called by the :ref:`AudioServer<class_AudioServer>` to process this effect. When :ref:`_process_silence<class_AudioEffectInstance_private_method__process_silence>` is not overridden or it returns ``false``, this method is called only when the bus is active.
 
-	There is currently no description for this method. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!
+\ **Note:** It is not useful to override this method in GDScript or C#. Only GDExtension can take advantage of it.
 
 .. rst-class:: classref-item-separator
 
@@ -61,9 +73,9 @@ void **_process** **(** const void* src_buffer, AudioFrame* dst_buffer, :ref:`in
 
 :ref:`bool<class_bool>` **_process_silence** **(** **)** |virtual| |const|
 
-.. container:: contribute
+Override this method to customize the processing behavior of this effect instance.
 
-	There is currently no description for this method. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!
+Should return ``true`` to force the :ref:`AudioServer<class_AudioServer>` to always call :ref:`_process<class_AudioEffectInstance_private_method__process>`, even if the bus has been muted or cannot otherwise be heard.
 
 .. |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_bone2d.rst

@@ -104,7 +104,7 @@ Method Descriptions
 
 void **apply_rest** **(** **)**
 
-Stores the node's current transforms in :ref:`rest<class_Bone2D_property_rest>`.
+Resets the bone to the rest pose. This is equivalent to setting :ref:`Node2D.transform<class_Node2D_property_transform>` to :ref:`rest<class_Bone2D_property_rest>`.
 
 .. rst-class:: classref-item-separator