classref: Sync with current master branch (8ff8216)

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
@@ -856,7 +842,7 @@ Returns a single character (as a :ref:`String<class_String>`) of the given Unico
 
 :ref:`Variant<class_Variant>` **convert** **(** :ref:`Variant<class_Variant>` what, :ref:`int<class_int>` type **)**
 
-*Deprecated.* Use :ref:`@GlobalScope.type_convert<class_@GlobalScope_method_type_convert>` instead.
+**Deprecated:** Use :ref:`@GlobalScope.type_convert<class_@GlobalScope_method_type_convert>` instead.
 
 Converts ``what`` to ``type`` in the best way possible. The ``type`` uses the :ref:`Variant.Type<enum_@GlobalScope_Variant.Type>` values.
 

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
 
@@ -3698,7 +3744,13 @@ Examples:
 
 :ref:`PropertyHint<enum_@GlobalScope_PropertyHint>` **PROPERTY_HINT_NODE_PATH_TO_EDITED_NODE** = ``24``
 
-*Deprecated.* This hint is not used anywhere and will be removed in the future.
+**Deprecated:** This hint is not used anywhere and will be removed in the future.
+
+.. container:: contribute
+
+	There is currently no description for this enum. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!
+
+
 
 .. _class_@GlobalScope_constant_PROPERTY_HINT_OBJECT_TOO_BIG:
 
@@ -3738,9 +3790,13 @@ Hints that a :ref:`String<class_String>` property is a path to a file. Editing i
 
 :ref:`PropertyHint<enum_@GlobalScope_PropertyHint>` **PROPERTY_HINT_INT_IS_OBJECTID** = ``29``
 
-Hints that an :ref:`int<class_int>` property is an object ID.
+**Deprecated:** This hint is not used anywhere and will be removed in the future.
+
+.. container:: contribute
+
+	There is currently no description for this enum. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!
+
 
-\ *Deprecated.* This hint is not used anywhere and will be removed in the future.
 
 .. _class_@GlobalScope_constant_PROPERTY_HINT_INT_IS_POINTER:
 
@@ -3942,9 +3998,13 @@ If this property is modified, all inspector fields will be refreshed.
 
 :ref:`PropertyUsageFlags<enum_@GlobalScope_PropertyUsageFlags>` **PROPERTY_USAGE_SCRIPT_DEFAULT_VALUE** = ``32768``
 
-Signifies a default value from a placeholder script instance.
+**Deprecated:** This hint is not used anywhere and will be removed in the future.
+
+.. container:: contribute
+
+	There is currently no description for this enum. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!
+
 
-\ *Deprecated.* This hint is not used anywhere and will be removed in the future.
 
 .. _class_@GlobalScope_constant_PROPERTY_USAGE_CLASS_IS_ENUM:
 
@@ -4024,9 +4084,13 @@ Inserting an animation key frame of this property will automatically increment t
 
 :ref:`PropertyUsageFlags<enum_@GlobalScope_PropertyUsageFlags>` **PROPERTY_USAGE_DEFERRED_SET_RESOURCE** = ``33554432``
 
-When loading, the resource for this property can be set at the end of loading.
+**Deprecated:** This hint is not used anywhere and will be removed in the future.
+
+.. container:: contribute
+
+	There is currently no description for this enum. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!
+
 
-\ *Deprecated.* This hint is not used anywhere and will be removed in the future.
 
 .. _class_@GlobalScope_constant_PROPERTY_USAGE_EDITOR_INSTANTIATE_OBJECT:
 
@@ -7285,6 +7349,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 +7363,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_animatedtexture.rst

@@ -10,6 +10,8 @@
 AnimatedTexture
 ===============
 
+**Deprecated:** This class may be changed or removed in future versions.
+
 **Inherits:** :ref:`Texture2D<class_Texture2D>` **<** :ref:`Texture<class_Texture>` **<** :ref:`Resource<class_Resource>` **<** :ref:`RefCounted<class_RefCounted>` **<** :ref:`Object<class_Object>`
 
 Proxy texture for simple frame-based animations.
@@ -29,8 +31,6 @@ The playback of the animation is controlled by the :ref:`speed_scale<class_Anima
 
 \ **Warning:** The current implementation is not efficient for the modern renderers.
 
-\ *Deprecated.* This class is deprecated, and might be removed in a future release.
-
 .. rst-class:: classref-reftable-group
 
 Properties

classes/class_animation.rst

@@ -392,7 +392,7 @@ Update at the keyframes.
 
 :ref:`UpdateMode<enum_Animation_UpdateMode>` **UPDATE_CAPTURE** = ``2``
 
-Same as linear interpolation, but also interpolates from the current value (i.e. dynamically at runtime) if the first key isn't at 0 seconds.
+Same as :ref:`UPDATE_CONTINUOUS<class_Animation_constant_UPDATE_CONTINUOUS>` but works as a flag to capture the value of the current object and perform interpolation in some methods. See also :ref:`AnimationMixer.capture<class_AnimationMixer_method_capture>` and :ref:`AnimationPlayer.play_with_capture<class_AnimationPlayer_method_play_with_capture>`.
 
 .. rst-class:: classref-item-separator