diff --git a/classes/class_@gdscript.rst b/classes/class_@gdscript.rst index 637da62db00..7772c35b32e 100644 --- a/classes/class_@gdscript.rst +++ b/classes/class_@gdscript.rst @@ -17,9 +17,9 @@ Built-in GDScript constants, functions, and annotations. Description ----------- -A list of GDScript-specific utility functions and annotations accessible from any script. +A list of utility functions and annotations accessible from any script written in GDScript. -For the list of the global functions and constants see :ref:`@GlobalScope`. +For the list of global functions and constants that can be accessed in any scripting language, see :ref:`@GlobalScope`. .. rst-class:: classref-introduction-group @@ -43,7 +43,7 @@ Methods +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`char`\ (\ char\: :ref:`int`\ ) | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Variant` | :ref:`convert`\ (\ what\: :ref:`Variant`, type\: :ref:`int`\ ) | + | :ref:`Variant` | :ref:`convert`\ (\ what\: :ref:`Variant`, type\: :ref:`Variant.Type`\ ) | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Object` | :ref:`dict_to_inst`\ (\ dictionary\: :ref:`Dictionary`\ ) | +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -705,7 +705,67 @@ See also :ref:`@GlobalScope.PROPERTY_USAGE_SUBGROUP`, icon\: :ref:`String` = ""\ ) :ref:`๐Ÿ”—` + +Export a :ref:`Callable` property as a clickable button with the label ``text``. When the button is pressed, the callable is called. + +If ``icon`` is specified, it is used to fetch an icon for the button via :ref:`Control.get_theme_icon`, from the ``"EditorIcons"`` theme type. If ``icon`` is omitted, the default ``"Callable"`` icon is used instead. + +Consider using the :ref:`EditorUndoRedoManager` to allow the action to be reverted safely. + +See also :ref:`@GlobalScope.PROPERTY_HINT_TOOL_BUTTON`. + +:: + + @tool + extends Sprite2D + + @export_tool_button("Hello") var hello_action = hello + @export_tool_button("Randomize the color!", "ColorRect") + var randomize_color_action = randomize_color + + func hello(): + print("Hello world!") + + func randomize_color(): + var undo_redo = EditorInterface.get_editor_undo_redo() + undo_redo.create_action("Randomized Sprite2D Color") + undo_redo.add_do_property(self, &"self_modulate", Color(randf(), randf(), randf())) + undo_redo.add_undo_property(self, &"self_modulate", self_modulate) + undo_redo.commit_action() + +\ **Note:** The property is exported without the :ref:`@GlobalScope.PROPERTY_USAGE_STORAGE` flag because a :ref:`Callable` cannot be properly serialized and stored in a file. + +\ **Note:** In an exported project neither :ref:`EditorInterface` nor :ref:`EditorUndoRedoManager` exist, which may cause some scripts to break. To prevent this, you can use :ref:`Engine.get_singleton` and omit the static type from the variable declaration: + +:: + + var undo_redo = Engine.get_singleton(&"EditorInterface").get_editor_undo_redo() + +\ **Note:** Avoid storing lambda callables in member variables of :ref:`RefCounted`-based classes (e.g. resources), as this can lead to memory leaks. Use only method callables and optionally :ref:`Callable.bind` or :ref:`Callable.unbind`. .. rst-class:: classref-item-separator @@ -899,9 +959,9 @@ Returns a single character (as a :ref:`String`) of the given Unico :: - a = char(65) # a is "A" - a = char(65 + 32) # a is "a" - a = char(8364) # a is "โ‚ฌ" + var upper = char(65) # upper is "A" + var lower = char(65 + 32) # lower is "a" + var euro = char(8364) # euro is "โ‚ฌ" .. rst-class:: classref-item-separator @@ -911,7 +971,7 @@ Returns a single character (as a :ref:`String`) of the given Unico .. rst-class:: classref-method -:ref:`Variant` **convert**\ (\ what\: :ref:`Variant`, type\: :ref:`int`\ ) :ref:`๐Ÿ”—` +:ref:`Variant` **convert**\ (\ what\: :ref:`Variant`, type\: :ref:`Variant.Type`\ ) :ref:`๐Ÿ”—` **Deprecated:** Use :ref:`@GlobalScope.type_convert` instead. @@ -1020,7 +1080,7 @@ Returns ``true`` if ``value`` is an instance of ``type``. The ``type`` value mus Unlike the right operand of the ``is`` operator, ``type`` can be a non-constant value. The ``is`` operator supports more features (such as typed arrays). Use the operator instead of this method if you do not need dynamic type checking. -Examples: +\ **Examples:**\ :: @@ -1047,10 +1107,10 @@ Returns the length of the given Variant ``var``. The length can be the character :: - a = [1, 2, 3, 4] + var a = [1, 2, 3, 4] len(a) # Returns 4 - b = "Hello!" + var b = "Hello!" len(b) # Returns 6 .. rst-class:: classref-item-separator @@ -1166,7 +1226,7 @@ Returns an array with the given range. :ref:`range \ **Note:** Returns an empty array if no value meets the value constraint (e.g. ``range(2, 5, -1)`` or ``range(5, 5, 1)``). -Examples: +\ **Examples:**\ :: diff --git a/classes/class_@globalscope.rst b/classes/class_@globalscope.rst index 2e072c6768f..c06987baa7c 100644 --- a/classes/class_@globalscope.rst +++ b/classes/class_@globalscope.rst @@ -21,7 +21,7 @@ A list of global scope enumerated constants and built-in functions. This is all Singletons are also documented here, since they can be accessed from anywhere. -For the entries related to GDScript which can be accessed in any script see :ref:`@GDScript`. +For the entries that can only be accessed from scripts written in GDScript, see :ref:`@GDScript`. .. note:: @@ -1753,7 +1753,7 @@ Space key. :ref:`Key` **KEY_EXCLAM** = ``33`` -! key. +Exclamation mark (``!``) key. .. _class_@GlobalScope_constant_KEY_QUOTEDBL: @@ -1761,7 +1761,7 @@ Space key. :ref:`Key` **KEY_QUOTEDBL** = ``34`` -" key. +Double quotation mark (``"``) key. .. _class_@GlobalScope_constant_KEY_NUMBERSIGN: @@ -1769,7 +1769,7 @@ Space key. :ref:`Key` **KEY_NUMBERSIGN** = ``35`` -# key. +Number sign or *hash* (``#``) key. .. _class_@GlobalScope_constant_KEY_DOLLAR: @@ -1777,7 +1777,7 @@ Space key. :ref:`Key` **KEY_DOLLAR** = ``36`` -$ key. +Dollar sign (``$``) key. .. _class_@GlobalScope_constant_KEY_PERCENT: @@ -1785,7 +1785,7 @@ $ key. :ref:`Key` **KEY_PERCENT** = ``37`` -% key. +Percent sign (``%``) key. .. _class_@GlobalScope_constant_KEY_AMPERSAND: @@ -1793,7 +1793,7 @@ $ key. :ref:`Key` **KEY_AMPERSAND** = ``38`` -& key. +Ampersand (``&``) key. .. _class_@GlobalScope_constant_KEY_APOSTROPHE: @@ -1801,7 +1801,7 @@ $ key. :ref:`Key` **KEY_APOSTROPHE** = ``39`` -' key. +Apostrophe (``'``) key. .. _class_@GlobalScope_constant_KEY_PARENLEFT: @@ -1809,7 +1809,7 @@ $ key. :ref:`Key` **KEY_PARENLEFT** = ``40`` -( key. +Left parenthesis (``(``) key. .. _class_@GlobalScope_constant_KEY_PARENRIGHT: @@ -1817,7 +1817,7 @@ $ key. :ref:`Key` **KEY_PARENRIGHT** = ``41`` -) key. +Right parenthesis (``)``) key. .. _class_@GlobalScope_constant_KEY_ASTERISK: @@ -1825,7 +1825,7 @@ $ key. :ref:`Key` **KEY_ASTERISK** = ``42`` -\* key. +Asterisk (``*``) key. .. _class_@GlobalScope_constant_KEY_PLUS: @@ -1833,7 +1833,7 @@ $ key. :ref:`Key` **KEY_PLUS** = ``43`` -+ key. +Plus (``+``) key. .. _class_@GlobalScope_constant_KEY_COMMA: @@ -1841,7 +1841,7 @@ $ key. :ref:`Key` **KEY_COMMA** = ``44`` -, key. +Comma (``,``) key. .. _class_@GlobalScope_constant_KEY_MINUS: @@ -1849,7 +1849,7 @@ $ key. :ref:`Key` **KEY_MINUS** = ``45`` -- key. +Minus (``-``) key. .. _class_@GlobalScope_constant_KEY_PERIOD: @@ -1857,7 +1857,7 @@ $ key. :ref:`Key` **KEY_PERIOD** = ``46`` -. key. +Period (``.``) key. .. _class_@GlobalScope_constant_KEY_SLASH: @@ -1865,7 +1865,7 @@ $ key. :ref:`Key` **KEY_SLASH** = ``47`` -/ key. +Slash (``/``) key. .. _class_@GlobalScope_constant_KEY_0: @@ -1953,7 +1953,7 @@ Number 9 key. :ref:`Key` **KEY_COLON** = ``58`` -: key. +Colon (``:``) key. .. _class_@GlobalScope_constant_KEY_SEMICOLON: @@ -1961,7 +1961,7 @@ Number 9 key. :ref:`Key` **KEY_SEMICOLON** = ``59`` -; key. +Semicolon (``;``) key. .. _class_@GlobalScope_constant_KEY_LESS: @@ -1969,7 +1969,7 @@ Number 9 key. :ref:`Key` **KEY_LESS** = ``60`` -< key. +Less-than sign (``<``) key. .. _class_@GlobalScope_constant_KEY_EQUAL: @@ -1977,7 +1977,7 @@ Number 9 key. :ref:`Key` **KEY_EQUAL** = ``61`` -= key. +Equal sign (``=``) key. .. _class_@GlobalScope_constant_KEY_GREATER: @@ -1985,7 +1985,7 @@ Number 9 key. :ref:`Key` **KEY_GREATER** = ``62`` -> key. +Greater-than sign (``>``) key. .. _class_@GlobalScope_constant_KEY_QUESTION: @@ -1993,7 +1993,7 @@ Number 9 key. :ref:`Key` **KEY_QUESTION** = ``63`` -? key. +Question mark (``?``) key. .. _class_@GlobalScope_constant_KEY_AT: @@ -2001,7 +2001,7 @@ Number 9 key. :ref:`Key` **KEY_AT** = ``64`` -@ key. +At sign (``@``) key. .. _class_@GlobalScope_constant_KEY_A: @@ -2217,7 +2217,7 @@ Z key. :ref:`Key` **KEY_BRACKETLEFT** = ``91`` -[ key. +Left bracket (``[lb]``) key. .. _class_@GlobalScope_constant_KEY_BACKSLASH: @@ -2225,7 +2225,7 @@ Z key. :ref:`Key` **KEY_BACKSLASH** = ``92`` -\\ key. +Backslash (``\``) key. .. _class_@GlobalScope_constant_KEY_BRACKETRIGHT: @@ -2233,7 +2233,7 @@ Z key. :ref:`Key` **KEY_BRACKETRIGHT** = ``93`` -] key. +Right bracket (``[rb]``) key. .. _class_@GlobalScope_constant_KEY_ASCIICIRCUM: @@ -2241,7 +2241,7 @@ Z key. :ref:`Key` **KEY_ASCIICIRCUM** = ``94`` -^ key. +Caret (``^``) key. .. _class_@GlobalScope_constant_KEY_UNDERSCORE: @@ -2249,7 +2249,7 @@ Z key. :ref:`Key` **KEY_UNDERSCORE** = ``95`` -\_ key. +Underscore (``_``) key. .. _class_@GlobalScope_constant_KEY_QUOTELEFT: @@ -2257,7 +2257,7 @@ Z key. :ref:`Key` **KEY_QUOTELEFT** = ``96`` -` key. +Backtick (`````) key. .. _class_@GlobalScope_constant_KEY_BRACELEFT: @@ -2265,7 +2265,7 @@ Z key. :ref:`Key` **KEY_BRACELEFT** = ``123`` -{ key. +Left brace (``{``) key. .. _class_@GlobalScope_constant_KEY_BAR: @@ -2273,7 +2273,7 @@ Z key. :ref:`Key` **KEY_BAR** = ``124`` -| key. +Vertical bar or *pipe* (``|``) key. .. _class_@GlobalScope_constant_KEY_BRACERIGHT: @@ -2281,7 +2281,7 @@ Z key. :ref:`Key` **KEY_BRACERIGHT** = ``125`` -} key. +Right brace (``}``) key. .. _class_@GlobalScope_constant_KEY_ASCIITILDE: @@ -2289,7 +2289,7 @@ Z key. :ref:`Key` **KEY_ASCIITILDE** = ``126`` -~ key. +Tilde (``~``) key. .. _class_@GlobalScope_constant_KEY_YEN: @@ -2297,7 +2297,7 @@ Z key. :ref:`Key` **KEY_YEN** = ``165`` -ยฅ key. +Yen symbol (``ยฅ``) key. .. _class_@GlobalScope_constant_KEY_SECTION: @@ -2305,7 +2305,7 @@ Z key. :ref:`Key` **KEY_SECTION** = ``167`` -ยง key. +Section sign (``ยง``) key. .. rst-class:: classref-item-separator @@ -3045,9 +3045,7 @@ enum **Error**: :ref:`๐Ÿ”—` Methods that return :ref:`Error` return :ref:`OK` when no error occurred. -Since :ref:`OK` has value 0, and all other error constants are positive integers, it can also be used in boolean checks. - -\ **Example:**\ +Since :ref:`OK` has value ``0``, and all other error constants are positive integers, it can also be used in boolean checks. :: @@ -3702,7 +3700,7 @@ If a property is :ref:`Array`, hints the editor how to show element -Examples: +\ **Examples:**\ .. tabs:: @@ -3806,6 +3804,14 @@ Hints that an :ref:`int` property is a pointer. Used by GDExtension. Hints that a property is an :ref:`Array` with the stored type specified in the hint string. +.. _class_@GlobalScope_constant_PROPERTY_HINT_DICTIONARY_TYPE: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_DICTIONARY_TYPE** = ``38`` + +Hints that a property is a :ref:`Dictionary` with the stored types specified in the hint string. + .. _class_@GlobalScope_constant_PROPERTY_HINT_LOCALE_ID: .. rst-class:: classref-enumeration-constant @@ -3846,11 +3852,34 @@ Hints that a quaternion property should disable the temporary euler editor. Hints that a string property is a password, and every character is replaced with the secret character. +.. _class_@GlobalScope_constant_PROPERTY_HINT_TOOL_BUTTON: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_TOOL_BUTTON** = ``39`` + +Hints that a :ref:`Callable` property should be displayed as a clickable button. When the button is pressed, the callable is called. The hint string specifies the button text and optionally an icon from the ``"EditorIcons"`` theme type. + +.. code:: text + + "Click me!" - A button with the text "Click me!" and the default "Callable" icon. + "Click me!,ColorRect" - A button with the text "Click me!" and the "ColorRect" icon. + +\ **Note:** A :ref:`Callable` cannot be properly serialized and stored in a file, so it is recommended to use :ref:`PROPERTY_USAGE_EDITOR` instead of :ref:`PROPERTY_USAGE_DEFAULT`. + +.. _class_@GlobalScope_constant_PROPERTY_HINT_ONESHOT: + +.. rst-class:: classref-enumeration-constant + +:ref:`PropertyHint` **PROPERTY_HINT_ONESHOT** = ``40`` + +Hints that a property will be changed on its own after setting, such as :ref:`AudioStreamPlayer.playing` or :ref:`GPUParticles3D.emitting`. + .. _class_@GlobalScope_constant_PROPERTY_HINT_MAX: .. rst-class:: classref-enumeration-constant -:ref:`PropertyHint` **PROPERTY_HINT_MAX** = ``38`` +:ref:`PropertyHint` **PROPERTY_HINT_MAX** = ``41`` Represents the size of the :ref:`PropertyHint` enum. @@ -3966,7 +3995,7 @@ Editing the property prompts the user for restarting the editor. :ref:`PropertyUsageFlags` **PROPERTY_USAGE_SCRIPT_VARIABLE** = ``4096`` -The property is a script variable which should be serialized and saved in the scene file. +The property is a script variable. :ref:`PROPERTY_USAGE_SCRIPT_VARIABLE` can be used to distinguish between exported script variables from built-in variables (which don't have this usage flag). By default, :ref:`PROPERTY_USAGE_SCRIPT_VARIABLE` is **not** applied to variables that are created by overriding :ref:`Object._get_property_list` in a script. .. _class_@GlobalScope_constant_PROPERTY_USAGE_STORE_IF_NULL: @@ -4000,7 +4029,7 @@ If this property is modified, all inspector fields will be refreshed. :ref:`PropertyUsageFlags` **PROPERTY_USAGE_CLASS_IS_ENUM** = ``65536`` -The property is an enum, i.e. it only takes named integer constants from its associated enumeration. +The property is a variable of enum type, i.e. it only takes named integer constants from its associated enumeration. .. _class_@GlobalScope_constant_PROPERTY_USAGE_NIL_IS_VARIANT: @@ -5322,7 +5351,7 @@ Returns the hyperbolic arc (also called inverse) cosine of ``x``, returning a va :ref:`float` **angle_difference**\ (\ from\: :ref:`float`, to\: :ref:`float`\ ) :ref:`๐Ÿ”—` -Returns the difference between the two angles, in the range of ``[-PI, +PI]``. When ``from`` and ``to`` are opposite, returns ``-PI`` if ``from`` is smaller than ``to``, or ``PI`` otherwise. +Returns the difference between the two angles (in radians), in the range of ``[-PI, +PI]``. When ``from`` and ``to`` are opposite, returns ``-PI`` if ``from`` is smaller than ``to``, or ``PI`` otherwise. .. rst-class:: classref-item-separator @@ -5712,7 +5741,7 @@ Returns an "eased" value of ``x`` based on an easing function defined with ``cur .. code:: text - Lower than -1.0 (exclusive): Ease in-out - - 1.0: Linear + - -1.0: Linear - Between -1.0 and 0.0 (exclusive): Ease out-in - 0.0: Constant - Between 0.0 to 1.0 (exclusive): Ease out @@ -6084,9 +6113,9 @@ This function is faster than using :ref:`is_equal_approx` **lerp**\ (\ from\: :ref:`Variant`, to\: :ref:`Variant`, weight\: :ref:`Variant`\ ) :ref:`๐Ÿ”—` -Linearly interpolates between two values by the factor defined in ``weight``. To perform interpolation, ``weight`` should be between ``0.0`` and ``1.0`` (inclusive). However, values outside this range are allowed and can be used to perform *extrapolation*. If this is not desired, use :ref:`clamp` on the result of this function. +Linearly interpolates between two values by the factor defined in ``weight``. To perform interpolation, ``weight`` should be between ``0.0`` and ``1.0`` (inclusive). However, values outside this range are allowed and can be used to perform *extrapolation*. If this is not desired, use :ref:`clampf` to limit ``weight``. -Both ``from`` and ``to`` must be the same type. Supported types: :ref:`int`, :ref:`float`, :ref:`Vector2`, :ref:`Vector3`, :ref:`Vector4`, :ref:`Color`, :ref:`Quaternion`, :ref:`Basis`. +Both ``from`` and ``to`` must be the same type. Supported types: :ref:`int`, :ref:`float`, :ref:`Vector2`, :ref:`Vector3`, :ref:`Vector4`, :ref:`Color`, :ref:`Quaternion`, :ref:`Basis`, :ref:`Transform2D`, :ref:`Transform3D`. :: @@ -6094,7 +6123,7 @@ Both ``from`` and ``to`` must be the same type. Supported types: :ref:`int` which performs the reverse of this operation. To perform eased interpolation with :ref:`lerp`, combine it with :ref:`ease` or :ref:`smoothstep`. See also :ref:`remap` to map a continuous series of values to another. -\ **Note:** For better type safety, use :ref:`lerpf`, :ref:`Vector2.lerp`, :ref:`Vector3.lerp`, :ref:`Vector4.lerp`, :ref:`Color.lerp`, :ref:`Quaternion.slerp` or :ref:`Basis.slerp`. +\ **Note:** For better type safety, use :ref:`lerpf`, :ref:`Vector2.lerp`, :ref:`Vector3.lerp`, :ref:`Vector4.lerp`, :ref:`Color.lerp`, :ref:`Quaternion.slerp`, :ref:`Basis.slerp`, :ref:`Transform2D.interpolate_with`, or :ref:`Transform3D.interpolate_with`. .. rst-class:: classref-item-separator @@ -6150,15 +6179,12 @@ See also :ref:`inverse_lerp` which perfo :ref:`float` **linear_to_db**\ (\ lin\: :ref:`float`\ ) :ref:`๐Ÿ”—` -Converts from linear energy to decibels (audio). This can be used to implement volume sliders that behave as expected (since volume isn't linear). +Converts from linear energy to decibels (audio). Since volume is not normally linear, this can be used to implement volume sliders that behave as expected. -\ **Example:**\ +\ **Example:** Change the Master bus's volume through a :ref:`Slider` node, which ranges from ``0.0`` to ``1.0``: :: - # "Slider" refers to a node that inherits Range such as HSlider or VSlider. - # Its range must be configured to go from 0 to 1. - # Change the bus name if you'd like to change the volume of a specific bus only. AudioServer.set_bus_volume_db(AudioServer.get_bus_index("Master"), linear_to_db($Slider.value)) .. rst-class:: classref-item-separator @@ -6431,7 +6457,7 @@ Converts one or more arguments of any type to string in the best way possible an -\ **Note:** Consider using :ref:`push_error` and :ref:`push_warning` to print error and warning messages instead of :ref:`print` or :ref:`print_rich`. This distinguishes them from print messages used for debugging purposes, while also displaying a stack trace when an error or warning is printed. +\ **Note:** Consider using :ref:`push_error` and :ref:`push_warning` to print error and warning messages instead of :ref:`print` or :ref:`print_rich`. This distinguishes them from print messages used for debugging purposes, while also displaying a stack trace when an error or warning is printed. See also :ref:`Engine.print_to_stdout` and :ref:`ProjectSettings.application/run/disable_stdout`. .. rst-class:: classref-item-separator @@ -6680,8 +6706,8 @@ Given a ``seed``, returns a :ref:`PackedInt64Array` of s var a = rand_from_seed(4) - print(a[0]) # Prints 2879024997 - print(a[1]) # Prints 4 + print(a[0]) # Prints 2879024997 + print(a[1]) # Prints 4 .. rst-class:: classref-item-separator @@ -7020,7 +7046,7 @@ Returns ``-1.0`` if ``x`` is negative, ``1.0`` if ``x`` is positive, and ``0.0`` :ref:`int` **signi**\ (\ x\: :ref:`int`\ ) :ref:`๐Ÿ”—` -Returns ``-1`` if ``x`` is negative, ``1`` if ``x`` is positive, and ``0`` if if ``x`` is zero. +Returns ``-1`` if ``x`` is negative, ``1`` if ``x`` is positive, and ``0`` if ``x`` is zero. :: @@ -7072,9 +7098,11 @@ Returns the hyperbolic sine of ``x``. :ref:`float` **smoothstep**\ (\ from\: :ref:`float`, to\: :ref:`float`, x\: :ref:`float`\ ) :ref:`๐Ÿ”—` -Returns the result of smoothly interpolating the value of ``x`` between ``0`` and ``1``, based on the where ``x`` lies with respect to the edges ``from`` and ``to``. +Returns a smooth cubic Hermite interpolation between ``0`` and ``1``. + +For positive ranges (when ``from <= to``) the return value is ``0`` when ``x <= from``, and ``1`` when ``x >= to``. If ``x`` lies between ``from`` and ``to``, the return value follows an S-shaped curve that smoothly transitions from ``0`` to ``1``. -The return value is ``0`` if ``x <= from``, and ``1`` if ``x >= to``. If ``x`` lies between ``from`` and ``to``, the returned value follows an S-shaped curve that maps ``x`` between ``0`` and ``1``. +For negative ranges (when ``from > to``) the function is mirrored and returns ``1`` when ``x <= to`` and ``0`` when ``x >= from``. This S-shaped curve is the cubic Hermite interpolator, given by ``f(y) = 3*y^2 - 2*y^3`` where ``y = (x-from) / (to-from)``. @@ -7087,7 +7115,9 @@ This S-shaped curve is the cubic Hermite interpolator, given by ``f(y) = 3*y^2 - Compared to :ref:`ease` with a curve value of ``-1.6521``, :ref:`smoothstep` returns the smoothest possible curve with no sudden changes in the derivative. If you need to perform more advanced transitions, use :ref:`Tween` or :ref:`AnimationPlayer`. -\ `Comparison between smoothstep() and ease(x, -1.6521) return values `__ +\ `Comparison between smoothstep() and ease(x, -1.6521) return values `__\ + +\ `Smoothstep() return values with positive, zero, and negative ranges `__ .. rst-class:: classref-item-separator diff --git a/classes/class_aabb.rst b/classes/class_aabb.rst index 4c35ba984c8..47a0d137c12 100644 --- a/classes/class_aabb.rst +++ b/classes/class_aabb.rst @@ -103,7 +103,7 @@ Methods +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`get_shortest_axis_size`\ (\ ) |const| | +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Vector3` | :ref:`get_support`\ (\ dir\: :ref:`Vector3`\ ) |const| | + | :ref:`Vector3` | :ref:`get_support`\ (\ direction\: :ref:`Vector3`\ ) |const| | +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`get_volume`\ (\ ) |const| | +-------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -163,7 +163,7 @@ Property Descriptions :ref:`Vector3` **end** = ``Vector3(0, 0, 0)`` :ref:`๐Ÿ”—` -The ending point. This is usually the corner on the top-right and forward of the bounding box, and is equivalent to ``position + size``. Setting this point affects the :ref:`size`. +The ending point. This is usually the corner on the top-right and back of the bounding box, and is equivalent to ``position + size``. Setting this point affects the :ref:`size`. .. rst-class:: classref-item-separator @@ -175,7 +175,7 @@ The ending point. This is usually the corner on the top-right and forward of the :ref:`Vector3` **position** = ``Vector3(0, 0, 0)`` :ref:`๐Ÿ”—` -The origin point. This is usually the corner on the bottom-left and back of the bounding box. +The origin point. This is usually the corner on the bottom-left and forward of the bounding box. .. rst-class:: classref-item-separator @@ -189,7 +189,7 @@ The origin point. This is usually the corner on the bottom-left and back of the The bounding box's width, height, and depth starting from :ref:`position`. Setting this value also affects the :ref:`end` point. -\ **Note:** It's recommended setting the width, height, and depth to non-negative values. This is because most methods in Godot assume that the :ref:`position` is the bottom-left-back corner, and the :ref:`end` is the top-right-forward corner. To get an equivalent bounding box with non-negative size, use :ref:`abs`. +\ **Note:** It's recommended setting the width, height, and depth to non-negative values. This is because most methods in Godot assume that the :ref:`position` is the bottom-left-forward corner, and the :ref:`end` is the top-right-back corner. To get an equivalent bounding box with non-negative size, use :ref:`abs`. .. rst-class:: classref-section-separator @@ -502,7 +502,7 @@ For an example, see :ref:`get_shortest_axis .. rst-class:: classref-method -:ref:`Vector3` **get_support**\ (\ dir\: :ref:`Vector3`\ ) |const| :ref:`๐Ÿ”—` +:ref:`Vector3` **get_support**\ (\ direction\: :ref:`Vector3`\ ) |const| :ref:`๐Ÿ”—` Returns the vertex's position of this bounding box that's the farthest in the given direction. This point is commonly known as the support point in collision detection algorithms. @@ -692,7 +692,7 @@ The segment begins at ``from`` and ends at ``to``. :ref:`bool` **is_equal_approx**\ (\ aabb\: :ref:`AABB`\ ) |const| :ref:`๐Ÿ”—` -Returns ``true`` if this bounding box and ``aabb`` are approximately equal, by calling :ref:`Vector2.is_equal_approx` on the :ref:`position` and the :ref:`size`. +Returns ``true`` if this bounding box and ``aabb`` are approximately equal, by calling :ref:`Vector3.is_equal_approx` on the :ref:`position` and the :ref:`size`. .. rst-class:: classref-item-separator @@ -704,7 +704,7 @@ Returns ``true`` if this bounding box and ``aabb`` are approximately equal, by c :ref:`bool` **is_finite**\ (\ ) |const| :ref:`๐Ÿ”—` -Returns ``true`` if this bounding box's values are finite, by calling :ref:`Vector2.is_finite` on the :ref:`position` and the :ref:`size`. +Returns ``true`` if this bounding box's values are finite, by calling :ref:`Vector3.is_finite` on the :ref:`position` and the :ref:`size`. .. rst-class:: classref-item-separator diff --git a/classes/class_animatedsprite2d.rst b/classes/class_animatedsprite2d.rst index 8c909164789..dc63037b2c0 100644 --- a/classes/class_animatedsprite2d.rst +++ b/classes/class_animatedsprite2d.rst @@ -413,18 +413,15 @@ This method is a shorthand for :ref:`play` w |void| **set_frame_and_progress**\ (\ frame\: :ref:`int`, progress\: :ref:`float`\ ) :ref:`๐Ÿ”—` -The setter of :ref:`frame` resets the :ref:`frame_progress` to ``0.0`` implicitly, but this method avoids that. +Sets :ref:`frame` the :ref:`frame_progress` to the given values. Unlike setting :ref:`frame`, this method does not reset the :ref:`frame_progress` to ``0.0`` implicitly. -This is useful when you want to carry over the current :ref:`frame_progress` to another :ref:`frame`. - -\ **Example:**\ +\ **Example:** Change the animation while keeping the same :ref:`frame` and :ref:`frame_progress`: .. tabs:: .. code-tab:: gdscript - # Change the animation with keeping the frame index and progress. var current_frame = animated_sprite.get_frame() var current_progress = animated_sprite.get_frame_progress() animated_sprite.play("walk_another_skin") diff --git a/classes/class_animatedsprite3d.rst b/classes/class_animatedsprite3d.rst index 46feb6c7589..744c7ff23bb 100644 --- a/classes/class_animatedsprite3d.rst +++ b/classes/class_animatedsprite3d.rst @@ -333,18 +333,15 @@ This method is a shorthand for :ref:`play` w |void| **set_frame_and_progress**\ (\ frame\: :ref:`int`, progress\: :ref:`float`\ ) :ref:`๐Ÿ”—` -The setter of :ref:`frame` resets the :ref:`frame_progress` to ``0.0`` implicitly, but this method avoids that. +Sets :ref:`frame` the :ref:`frame_progress` to the given values. Unlike setting :ref:`frame`, this method does not reset the :ref:`frame_progress` to ``0.0`` implicitly. -This is useful when you want to carry over the current :ref:`frame_progress` to another :ref:`frame`. - -\ **Example:**\ +\ **Example:** Change the animation while keeping the same :ref:`frame` and :ref:`frame_progress`: .. tabs:: .. code-tab:: gdscript - # Change the animation with keeping the frame index and progress. var current_frame = animated_sprite.get_frame() var current_progress = animated_sprite.get_frame_progress() animated_sprite.play("walk_another_skin") diff --git a/classes/class_animation.rst b/classes/class_animation.rst index c977ca1a26e..94979b016c0 100644 --- a/classes/class_animation.rst +++ b/classes/class_animation.rst @@ -85,6 +85,8 @@ Methods .. table:: :widths: auto + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`add_marker`\ (\ name\: :ref:`StringName`, time\: :ref:`float`\ ) | +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`add_track`\ (\ type\: :ref:`TrackType`, at_position\: :ref:`int` = -1\ ) | +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -140,16 +142,34 @@ Methods +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`find_track`\ (\ path\: :ref:`NodePath`, type\: :ref:`TrackType`\ ) |const| | +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`get_marker_at_time`\ (\ time\: :ref:`float`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Color` | :ref:`get_marker_color`\ (\ name\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedStringArray` | :ref:`get_marker_names`\ (\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_marker_time`\ (\ name\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`get_next_marker`\ (\ time\: :ref:`float`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`get_prev_marker`\ (\ time\: :ref:`float`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_track_count`\ (\ ) |const| | +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_marker`\ (\ name\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`StringName` | :ref:`method_track_get_name`\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| | +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Array` | :ref:`method_track_get_params`\ (\ track_idx\: :ref:`int`, key_idx\: :ref:`int`\ ) |const| | +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`optimize`\ (\ allowed_velocity_err\: :ref:`float` = 0.01, allowed_angular_err\: :ref:`float` = 0.01, precision\: :ref:`int` = 3\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`position_track_insert_key`\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, position\: :ref:`Vector3`\ ) | +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector3` | :ref:`position_track_interpolate`\ (\ track_idx\: :ref:`int`, time_sec\: :ref:`float`, backward\: :ref:`bool` = false\ ) |const| | +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`remove_marker`\ (\ name\: :ref:`StringName`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`remove_track`\ (\ track_idx\: :ref:`int`\ ) | +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`rotation_track_insert_key`\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, rotation\: :ref:`Quaternion`\ ) | @@ -160,6 +180,8 @@ Methods +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Vector3` | :ref:`scale_track_interpolate`\ (\ track_idx\: :ref:`int`, time_sec\: :ref:`float`, backward\: :ref:`bool` = false\ ) |const| | +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_marker_color`\ (\ name\: :ref:`StringName`, color\: :ref:`Color`\ ) | + +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`track_find_key`\ (\ track_idx\: :ref:`int`, time\: :ref:`float`, find_mode\: :ref:`FindMode` = 0, limit\: :ref:`bool` = false, backward\: :ref:`bool` = false\ ) |const| | +------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`track_get_interpolation_loop_wrap`\ (\ track_idx\: :ref:`int`\ ) |const| | @@ -581,6 +603,18 @@ The animation step value. Method Descriptions ------------------- +.. _class_Animation_method_add_marker: + +.. rst-class:: classref-method + +|void| **add_marker**\ (\ name\: :ref:`StringName`, time\: :ref:`float`\ ) :ref:`๐Ÿ”—` + +Adds a marker to this Animation. + +.. rst-class:: classref-item-separator + +---- + .. _class_Animation_method_add_track: .. rst-class:: classref-method @@ -915,6 +949,78 @@ Returns the index of the specified track. If the track is not found, return -1. ---- +.. _class_Animation_method_get_marker_at_time: + +.. rst-class:: classref-method + +:ref:`StringName` **get_marker_at_time**\ (\ time\: :ref:`float`\ ) |const| :ref:`๐Ÿ”—` + +Returns the name of the marker located at the given time. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_get_marker_color: + +.. rst-class:: classref-method + +:ref:`Color` **get_marker_color**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`๐Ÿ”—` + +Returns the given marker's color. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_get_marker_names: + +.. rst-class:: classref-method + +:ref:`PackedStringArray` **get_marker_names**\ (\ ) |const| :ref:`๐Ÿ”—` + +Returns every marker in this Animation, sorted ascending by time. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_get_marker_time: + +.. rst-class:: classref-method + +:ref:`float` **get_marker_time**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`๐Ÿ”—` + +Returns the given marker's time. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_get_next_marker: + +.. rst-class:: classref-method + +:ref:`StringName` **get_next_marker**\ (\ time\: :ref:`float`\ ) |const| :ref:`๐Ÿ”—` + +Returns the closest marker that comes after the given time. If no such marker exists, an empty string is returned. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Animation_method_get_prev_marker: + +.. rst-class:: classref-method + +:ref:`StringName` **get_prev_marker**\ (\ time\: :ref:`float`\ ) |const| :ref:`๐Ÿ”—` + +Returns the closest marker that comes before the given time. If no such marker exists, an empty string is returned. + +.. rst-class:: classref-item-separator + +---- + .. _class_Animation_method_get_track_count: .. rst-class:: classref-method @@ -927,6 +1033,18 @@ Returns the amount of tracks in the animation. ---- +.. _class_Animation_method_has_marker: + +.. rst-class:: classref-method + +:ref:`bool` **has_marker**\ (\ name\: :ref:`StringName`\ ) |const| :ref:`๐Ÿ”—` + +Returns ``true`` if this Animation contains a marker with the given name. + +.. rst-class:: classref-item-separator + +---- + .. _class_Animation_method_method_track_get_name: .. rst-class:: classref-method @@ -951,6 +1069,18 @@ Returns the arguments values to be called on a method track for a given key in a ---- +.. _class_Animation_method_optimize: + +.. rst-class:: classref-method + +|void| **optimize**\ (\ allowed_velocity_err\: :ref:`float` = 0.01, allowed_angular_err\: :ref:`float` = 0.01, precision\: :ref:`int` = 3\ ) :ref:`๐Ÿ”—` + +Optimize the animation and all its tracks in-place. This will preserve only as many keys as are necessary to keep the animation within the specified bounds. + +.. rst-class:: classref-item-separator + +---- + .. _class_Animation_method_position_track_insert_key: .. rst-class:: classref-method @@ -975,6 +1105,18 @@ Returns the interpolated position value at the given time (in seconds). The ``tr ---- +.. _class_Animation_method_remove_marker: + +.. rst-class:: classref-method + +|void| **remove_marker**\ (\ name\: :ref:`StringName`\ ) :ref:`๐Ÿ”—` + +Removes the marker with the given name from this Animation. + +.. rst-class:: classref-item-separator + +---- + .. _class_Animation_method_remove_track: .. rst-class:: classref-method @@ -1035,6 +1177,18 @@ Returns the interpolated scale value at the given time (in seconds). The ``track ---- +.. _class_Animation_method_set_marker_color: + +.. rst-class:: classref-method + +|void| **set_marker_color**\ (\ name\: :ref:`StringName`, color\: :ref:`Color`\ ) :ref:`๐Ÿ”—` + +Sets the given marker's color. + +.. rst-class:: classref-item-separator + +---- + .. _class_Animation_method_track_find_key: .. rst-class:: classref-method diff --git a/classes/class_animationlibrary.rst b/classes/class_animationlibrary.rst index 458c410a0a3..3967684b2f7 100644 --- a/classes/class_animationlibrary.rst +++ b/classes/class_animationlibrary.rst @@ -43,6 +43,8 @@ Methods +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Array`\[:ref:`StringName`\] | :ref:`get_animation_list`\ (\ ) |const| | +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_animation_list_size`\ (\ ) |const| | + +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`has_animation`\ (\ name\: :ref:`StringName`\ ) |const| | +------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`remove_animation`\ (\ name\: :ref:`StringName`\ ) | @@ -150,6 +152,18 @@ Returns the keys for the :ref:`Animation`\ s stored in the libr ---- +.. _class_AnimationLibrary_method_get_animation_list_size: + +.. rst-class:: classref-method + +:ref:`int` **get_animation_list_size**\ (\ ) |const| :ref:`๐Ÿ”—` + +Returns the key count for the :ref:`Animation`\ s stored in the library. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimationLibrary_method_has_animation: .. rst-class:: classref-method diff --git a/classes/class_animationmixer.rst b/classes/class_animationmixer.rst index d970b77d9b7..b85842942f0 100644 --- a/classes/class_animationmixer.rst +++ b/classes/class_animationmixer.rst @@ -55,6 +55,8 @@ Properties +-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+--------------------+ | :ref:`bool` | :ref:`reset_on_save` | ``true`` | +-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+--------------------+ + | :ref:`bool` | :ref:`root_motion_local` | | + +-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+--------------------+ | :ref:`NodePath` | :ref:`root_motion_track` | ``NodePath("")`` | +-----------------------------------------------------------------------------------------+-------------------------------------------------------------------------------------+--------------------+ | :ref:`NodePath` | :ref:`root_node` | ``NodePath("..")`` | @@ -302,7 +304,31 @@ An :ref:`Animation.UPDATE_CONTINUOUS Always treat the :ref:`Animation.UPDATE_DISCRETE` track value as :ref:`Animation.UPDATE_CONTINUOUS` with :ref:`Animation.INTERPOLATION_NEAREST`. This is the default behavior for :ref:`AnimationTree`. -If a value track has non-numeric type key values, it is internally converted to use :ref:`ANIMATION_CALLBACK_MODE_DISCRETE_RECESSIVE` with :ref:`Animation.UPDATE_DISCRETE`. +If a value track has un-interpolatable type key values, it is internally converted to use :ref:`ANIMATION_CALLBACK_MODE_DISCRETE_RECESSIVE` with :ref:`Animation.UPDATE_DISCRETE`. + +Un-interpolatable type list: + +- :ref:`@GlobalScope.TYPE_NIL`\ + +- :ref:`@GlobalScope.TYPE_NODE_PATH`\ + +- :ref:`@GlobalScope.TYPE_RID`\ + +- :ref:`@GlobalScope.TYPE_OBJECT`\ + +- :ref:`@GlobalScope.TYPE_CALLABLE`\ + +- :ref:`@GlobalScope.TYPE_SIGNAL`\ + +- :ref:`@GlobalScope.TYPE_DICTIONARY`\ + +- :ref:`@GlobalScope.TYPE_PACKED_BYTE_ARRAY`\ + +\ :ref:`@GlobalScope.TYPE_BOOL` and :ref:`@GlobalScope.TYPE_INT` are treated as :ref:`@GlobalScope.TYPE_FLOAT` during blending and rounded when the result is retrieved. + +It is same for arrays and vectors with them such as :ref:`@GlobalScope.TYPE_PACKED_INT32_ARRAY` or :ref:`@GlobalScope.TYPE_VECTOR2I`, they are treated as :ref:`@GlobalScope.TYPE_PACKED_FLOAT32_ARRAY` or :ref:`@GlobalScope.TYPE_VECTOR2`. Also note that for arrays, the size is also interpolated. + +\ :ref:`@GlobalScope.TYPE_STRING` and :ref:`@GlobalScope.TYPE_STRING_NAME` are interpolated between character codes and lengths, but note that there is a difference in algorithm between interpolation between keys and interpolation by blending. .. rst-class:: classref-section-separator @@ -450,6 +476,23 @@ This makes it more convenient to preview and edit animations in the editor, as c ---- +.. _class_AnimationMixer_property_root_motion_local: + +.. rst-class:: classref-property + +:ref:`bool` **root_motion_local** :ref:`๐Ÿ”—` + +.. rst-class:: classref-property-setget + +- |void| **set_root_motion_local**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_root_motion_local**\ (\ ) + +If ``true``, :ref:`get_root_motion_position` value is extracted as a local translation value before blending. In other words, it is treated like the translation is done after the rotation. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimationMixer_property_root_motion_track: .. rst-class:: classref-property @@ -660,13 +703,13 @@ The most basic example is applying position to :ref:`CharacterBody3D` is ``true``, return the pre-multiplied translation value with the inverted rotation. + +In this case, the code can be written as follows: + + +.. tabs:: + + .. code-tab:: gdscript + + func _process(delta): + if Input.is_action_just_pressed("animate"): + state_machine.travel("Animate") + set_quaternion(get_quaternion() * animation_tree.get_root_motion_rotation()) + var velocity = get_quaternion() * animation_tree.get_root_motion_position() / delta set_velocity(velocity) move_and_slide() @@ -710,13 +772,13 @@ For example, if an animation with only one key ``Vector3(0, 0, 0)`` is played in .. code-tab:: gdscript - var prev_root_motion_position_accumulator: Vector3 + var prev_root_motion_position_accumulator func _process(delta): if Input.is_action_just_pressed("animate"): state_machine.travel("Animate") - var current_root_motion_position_accumulator: Vector3 = animation_tree.get_root_motion_position_accumulator() - var difference: Vector3 = current_root_motion_position_accumulator - prev_root_motion_position_accumulator + var current_root_motion_position_accumulator = animation_tree.get_root_motion_position_accumulator() + var difference = current_root_motion_position_accumulator - prev_root_motion_position_accumulator prev_root_motion_position_accumulator = current_root_motion_position_accumulator transform.origin += difference @@ -777,13 +839,13 @@ For example, if an animation with only one key ``Quaternion(0, 0, 0, 1)`` is pla .. code-tab:: gdscript - var prev_root_motion_rotation_accumulator: Quaternion + var prev_root_motion_rotation_accumulator func _process(delta): if Input.is_action_just_pressed("animate"): state_machine.travel("Animate") - var current_root_motion_rotation_accumulator: Quaternion = animation_tree.get_root_motion_rotation_accumulator() - var difference: Quaternion = prev_root_motion_rotation_accumulator.inverse() * current_root_motion_rotation_accumulator + var current_root_motion_rotation_accumulator = animation_tree.get_root_motion_rotation_accumulator() + var difference = prev_root_motion_rotation_accumulator.inverse() * current_root_motion_rotation_accumulator prev_root_motion_rotation_accumulator = current_root_motion_rotation_accumulator transform.basis *= Basis(difference) @@ -814,8 +876,8 @@ The most basic example is applying scale to :ref:`CharacterBody3D` | :ref:`_is_parameter_read_only`\ (\ parameter\: :ref:`StringName`\ ) |virtual| |const| | +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`float` | :ref:`_process`\ (\ time\: :ref:`float`, seek\: :ref:`bool`, is_external_seeking\: :ref:`bool`, test_only\: :ref:`bool`\ ) |virtual| |const| | + | :ref:`float` | :ref:`_process`\ (\ time\: :ref:`float`, seek\: :ref:`bool`, is_external_seeking\: :ref:`bool`, test_only\: :ref:`bool`\ ) |virtual| | +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`add_input`\ (\ name\: :ref:`String`\ ) | +-------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -313,7 +313,7 @@ When inheriting from :ref:`AnimationRootNode`, implemen .. rst-class:: classref-method -:ref:`float` **_process**\ (\ time\: :ref:`float`, seek\: :ref:`bool`, is_external_seeking\: :ref:`bool`, test_only\: :ref:`bool`\ ) |virtual| |const| :ref:`๐Ÿ”—` +:ref:`float` **_process**\ (\ time\: :ref:`float`, seek\: :ref:`bool`, is_external_seeking\: :ref:`bool`, test_only\: :ref:`bool`\ ) |virtual| :ref:`๐Ÿ”—` **Deprecated:** Currently this is mostly useless as there is a lack of many APIs to extend AnimationNode by GDScript. It is planned that a more flexible API using structures will be provided in the future. diff --git a/classes/class_animationnodeanimation.rst b/classes/class_animationnodeanimation.rst index d7b220ae231..7f25c8bfb4d 100644 --- a/classes/class_animationnodeanimation.rst +++ b/classes/class_animationnodeanimation.rst @@ -40,6 +40,8 @@ Properties .. table:: :widths: auto + +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+ + | :ref:`bool` | :ref:`advance_on_start` | ``false`` | +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+ | :ref:`StringName` | :ref:`animation` | ``&""`` | +-------------------------------------------------------+---------------------------------------------------------------------------------------+-----------+ @@ -96,6 +98,25 @@ Plays animation in backward direction. Property Descriptions --------------------- +.. _class_AnimationNodeAnimation_property_advance_on_start: + +.. rst-class:: classref-property + +:ref:`bool` **advance_on_start** = ``false`` :ref:`๐Ÿ”—` + +.. rst-class:: classref-property-setget + +- |void| **set_advance_on_start**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_advance_on_start**\ (\ ) + +If ``true``, on receiving a request to play an animation from the start, the first frame is not drawn, but only processed, and playback starts from the next frame. + +See also the notes of :ref:`AnimationPlayer.play`. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimationNodeAnimation_property_animation: .. rst-class:: classref-property diff --git a/classes/class_animationnodeblendspace2d.rst b/classes/class_animationnodeblendspace2d.rst index 506b47bff25..c107fffa9f8 100644 --- a/classes/class_animationnodeblendspace2d.rst +++ b/classes/class_animationnodeblendspace2d.rst @@ -21,7 +21,7 @@ Description A resource used by :ref:`AnimationNodeBlendTree`. -\ :ref:`AnimationNodeBlendSpace1D` represents a virtual 2D space on which :ref:`AnimationRootNode`\ s are placed. Outputs the linear blend of the three adjacent animations using a :ref:`Vector2` weight. Adjacent in this context means the three :ref:`AnimationRootNode`\ s making up the triangle that contains the current value. +\ **AnimationNodeBlendSpace2D** represents a virtual 2D space on which :ref:`AnimationRootNode`\ s are placed. Outputs the linear blend of the three adjacent animations using a :ref:`Vector2` weight. Adjacent in this context means the three :ref:`AnimationRootNode`\ s making up the triangle that contains the current value. You can add vertices to the blend space with :ref:`add_blend_point` and automatically triangulate it by setting :ref:`auto_triangles` to ``true``. Otherwise, use :ref:`add_triangle` and :ref:`remove_triangle` to triangulate the blend space by hand. @@ -426,7 +426,7 @@ Changes the :ref:`AnimationNode` referenced by the point at |void| **set_blend_point_position**\ (\ point\: :ref:`int`, pos\: :ref:`Vector2`\ ) :ref:`๐Ÿ”—` -Updates the position of the point at index ``point`` on the blend axis. +Updates the position of the point at index ``point`` in the blend space. .. |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.)` diff --git a/classes/class_animationnodeoneshot.rst b/classes/class_animationnodeoneshot.rst index 176e75af2e0..62cd8181083 100644 --- a/classes/class_animationnodeoneshot.rst +++ b/classes/class_animationnodeoneshot.rst @@ -272,7 +272,7 @@ If ``true``, breaks the loop at the end of the loop cycle for transition, even i - |void| **set_fadein_curve**\ (\ value\: :ref:`Curve`\ ) - :ref:`Curve` **get_fadein_curve**\ (\ ) -Determines how cross-fading between animations is eased. If empty, the transition will be linear. +Determines how cross-fading between animations is eased. If empty, the transition will be linear. Should be a unit :ref:`Curve`. .. rst-class:: classref-item-separator @@ -308,7 +308,7 @@ The fade-in duration. For example, setting this to ``1.0`` for a 5 second length - |void| **set_fadeout_curve**\ (\ value\: :ref:`Curve`\ ) - :ref:`Curve` **get_fadeout_curve**\ (\ ) -Determines how cross-fading between animations is eased. If empty, the transition will be linear. +Determines how cross-fading between animations is eased. If empty, the transition will be linear. Should be a unit :ref:`Curve`. .. rst-class:: classref-item-separator diff --git a/classes/class_animationnodestatemachine.rst b/classes/class_animationnodestatemachine.rst index f567081cc0b..d5e14462efa 100644 --- a/classes/class_animationnodestatemachine.rst +++ b/classes/class_animationnodestatemachine.rst @@ -21,8 +21,6 @@ Description Contains multiple :ref:`AnimationRootNode`\ s representing animation states, connected in a graph. State transitions can be configured to happen automatically or via code, using a shortest-path algorithm. Retrieve the :ref:`AnimationNodeStateMachinePlayback` object from the :ref:`AnimationTree` node to control it programmatically. -\ **Example:**\ - .. tabs:: diff --git a/classes/class_animationnodestatemachineplayback.rst b/classes/class_animationnodestatemachineplayback.rst index 221d1f62aa3..c1490a096e9 100644 --- a/classes/class_animationnodestatemachineplayback.rst +++ b/classes/class_animationnodestatemachineplayback.rst @@ -21,8 +21,6 @@ Description Allows control of :ref:`AnimationTree` state machines created with :ref:`AnimationNodeStateMachine`. Retrieve with ``$AnimationTree.get("parameters/playback")``. -\ **Example:**\ - .. tabs:: diff --git a/classes/class_animationnodestatemachinetransition.rst b/classes/class_animationnodestatemachinetransition.rst index 1a4973608e7..71c45f7a8cd 100644 --- a/classes/class_animationnodestatemachinetransition.rst +++ b/classes/class_animationnodestatemachinetransition.rst @@ -146,7 +146,7 @@ Only use this transition during :ref:`AnimationNodeStateMachinePlayback.travel` **ADVANCE_MODE_AUTO** = ``2`` -Automatically use this transition if the :ref:`advance_condition` and :ref:`advance_expression` checks are true (if assigned). +Automatically use this transition if the :ref:`advance_condition` and :ref:`advance_expression` checks are ``true`` (if assigned). .. rst-class:: classref-section-separator @@ -215,7 +215,7 @@ Use an expression as a condition for state machine transitions. It is possible t - |void| **set_advance_mode**\ (\ value\: :ref:`AdvanceMode`\ ) - :ref:`AdvanceMode` **get_advance_mode**\ (\ ) -Determines whether the transition should disabled, enabled when using :ref:`AnimationNodeStateMachinePlayback.travel`, or traversed automatically if the :ref:`advance_condition` and :ref:`advance_expression` checks are true (if assigned). +Determines whether the transition should be disabled, enabled when using :ref:`AnimationNodeStateMachinePlayback.travel`, or traversed automatically if the :ref:`advance_condition` and :ref:`advance_expression` checks are ``true`` (if assigned). .. rst-class:: classref-item-separator @@ -300,7 +300,7 @@ The transition type. - |void| **set_xfade_curve**\ (\ value\: :ref:`Curve`\ ) - :ref:`Curve` **get_xfade_curve**\ (\ ) -Ease curve for better control over cross-fade between this state and the next. +Ease curve for better control over cross-fade between this state and the next. Should be a unit :ref:`Curve`. .. rst-class:: classref-item-separator diff --git a/classes/class_animationnodetimeseek.rst b/classes/class_animationnodetimeseek.rst index c9ec75ffdcd..a6c98704efc 100644 --- a/classes/class_animationnodetimeseek.rst +++ b/classes/class_animationnodetimeseek.rst @@ -55,6 +55,40 @@ Tutorials - :doc:`Using AnimationTree <../tutorials/animation/animation_tree>` +.. rst-class:: classref-reftable-group + +Properties +---------- + +.. table:: + :widths: auto + + +-------------------------+------------------------------------------------------------------------------+----------+ + | :ref:`bool` | :ref:`explicit_elapse` | ``true`` | + +-------------------------+------------------------------------------------------------------------------+----------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Property Descriptions +--------------------- + +.. _class_AnimationNodeTimeSeek_property_explicit_elapse: + +.. rst-class:: classref-property + +:ref:`bool` **explicit_elapse** = ``true`` :ref:`๐Ÿ”—` + +.. rst-class:: classref-property-setget + +- |void| **set_explicit_elapse**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **is_explicit_elapse**\ (\ ) + +If ``true``, some processes are executed to handle keys between seeks, such as calculating root motion and finding the nearest discrete key. + .. |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.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` diff --git a/classes/class_animationnodetransition.rst b/classes/class_animationnodetransition.rst index f79beea9972..8b42fc02410 100644 --- a/classes/class_animationnodetransition.rst +++ b/classes/class_animationnodetransition.rst @@ -163,7 +163,7 @@ The number of enabled input ports for this animation node. - |void| **set_xfade_curve**\ (\ value\: :ref:`Curve`\ ) - :ref:`Curve` **get_xfade_curve**\ (\ ) -Determines how cross-fading between animations is eased. If empty, the transition will be linear. +Determines how cross-fading between animations is eased. If empty, the transition will be linear. Should be a unit :ref:`Curve`. .. rst-class:: classref-item-separator diff --git a/classes/class_animationplayer.rst b/classes/class_animationplayer.rst index b11956e6de9..c43c0d34d58 100644 --- a/classes/class_animationplayer.rst +++ b/classes/class_animationplayer.rst @@ -99,6 +99,12 @@ Methods +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`NodePath` | :ref:`get_root`\ (\ ) |const| | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_section_end_time`\ (\ ) |const| | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_section_start_time`\ (\ ) |const| | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`has_section`\ (\ ) |const| | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_playing`\ (\ ) |const| | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`pause`\ (\ ) | @@ -107,10 +113,20 @@ Methods +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`play_backwards`\ (\ name\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`play_section`\ (\ name\: :ref:`StringName` = &"", start_time\: :ref:`float` = -1, end_time\: :ref:`float` = -1, custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`play_section_backwards`\ (\ name\: :ref:`StringName` = &"", start_time\: :ref:`float` = -1, end_time\: :ref:`float` = -1, custom_blend\: :ref:`float` = -1\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`play_section_with_markers`\ (\ name\: :ref:`StringName` = &"", start_marker\: :ref:`StringName` = &"", end_marker\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`play_section_with_markers_backwards`\ (\ name\: :ref:`StringName` = &"", start_marker\: :ref:`StringName` = &"", end_marker\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`play_with_capture`\ (\ name\: :ref:`StringName` = &"", duration\: :ref:`float` = -1.0, custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false, trans_type\: :ref:`TransitionType` = 0, ease_type\: :ref:`EaseType` = 0\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`queue`\ (\ name\: :ref:`StringName`\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`reset_section`\ (\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`seek`\ (\ seconds\: :ref:`float`, update\: :ref:`bool` = false, update_only\: :ref:`bool` = false\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`set_blend_time`\ (\ animation_from\: :ref:`StringName`, animation_to\: :ref:`StringName`, sec\: :ref:`float`\ ) | @@ -121,6 +137,10 @@ Methods +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`set_root`\ (\ path\: :ref:`NodePath`\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_section`\ (\ start_time\: :ref:`float` = -1, end_time\: :ref:`float` = -1\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_section_with_markers`\ (\ start_marker\: :ref:`StringName` = &"", end_marker\: :ref:`StringName` = &""\ ) | + +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`stop`\ (\ keep_state\: :ref:`bool` = false\ ) | +--------------------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -572,6 +592,42 @@ Returns the node which node path references will travel from. ---- +.. _class_AnimationPlayer_method_get_section_end_time: + +.. rst-class:: classref-method + +:ref:`float` **get_section_end_time**\ (\ ) |const| :ref:`๐Ÿ”—` + +Returns the end time of the section currently being played. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_method_get_section_start_time: + +.. rst-class:: classref-method + +:ref:`float` **get_section_start_time**\ (\ ) |const| :ref:`๐Ÿ”—` + +Returns the start time of the section currently being played. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_method_has_section: + +.. rst-class:: classref-method + +:ref:`bool` **has_section**\ (\ ) |const| :ref:`๐Ÿ”—` + +Returns ``true`` if an animation is currently playing with section. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimationPlayer_method_is_playing: .. rst-class:: classref-method @@ -630,6 +686,62 @@ This method is a shorthand for :ref:`play` wi ---- +.. _class_AnimationPlayer_method_play_section: + +.. rst-class:: classref-method + +|void| **play_section**\ (\ name\: :ref:`StringName` = &"", start_time\: :ref:`float` = -1, end_time\: :ref:`float` = -1, custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) :ref:`๐Ÿ”—` + +Plays the animation with key ``name`` and the section starting from ``start_time`` and ending on ``end_time``. See also :ref:`play`. + +Setting ``start_time`` to a value outside the range of the animation means the start of the animation will be used instead, and setting ``end_time`` to a value outside the range of the animation means the end of the animation will be used instead. ``start_time`` cannot be equal to ``end_time``. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_method_play_section_backwards: + +.. rst-class:: classref-method + +|void| **play_section_backwards**\ (\ name\: :ref:`StringName` = &"", start_time\: :ref:`float` = -1, end_time\: :ref:`float` = -1, custom_blend\: :ref:`float` = -1\ ) :ref:`๐Ÿ”—` + +Plays the animation with key ``name`` and the section starting from ``start_time`` and ending on ``end_time`` in reverse. + +This method is a shorthand for :ref:`play_section` with ``custom_speed = -1.0`` and ``from_end = true``, see its description for more information. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_method_play_section_with_markers: + +.. rst-class:: classref-method + +|void| **play_section_with_markers**\ (\ name\: :ref:`StringName` = &"", start_marker\: :ref:`StringName` = &"", end_marker\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1, custom_speed\: :ref:`float` = 1.0, from_end\: :ref:`bool` = false\ ) :ref:`๐Ÿ”—` + +Plays the animation with key ``name`` and the section starting from ``start_marker`` and ending on ``end_marker``. + +If the start marker is empty, the section starts from the beginning of the animation. If the end marker is empty, the section ends on the end of the animation. See also :ref:`play`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_method_play_section_with_markers_backwards: + +.. rst-class:: classref-method + +|void| **play_section_with_markers_backwards**\ (\ name\: :ref:`StringName` = &"", start_marker\: :ref:`StringName` = &"", end_marker\: :ref:`StringName` = &"", custom_blend\: :ref:`float` = -1\ ) :ref:`๐Ÿ”—` + +Plays the animation with key ``name`` and the section starting from ``start_marker`` and ending on ``end_marker`` in reverse. + +This method is a shorthand for :ref:`play_section_with_markers` with ``custom_speed = -1.0`` and ``from_end = true``, see its description for more information. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimationPlayer_method_play_with_capture: .. rst-class:: classref-method @@ -669,6 +781,18 @@ Queues an animation for playback once the current animation and all previously q ---- +.. _class_AnimationPlayer_method_reset_section: + +.. rst-class:: classref-method + +|void| **reset_section**\ (\ ) :ref:`๐Ÿ”—` + +Resets the current section if section is set. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimationPlayer_method_seek: .. rst-class:: classref-method @@ -739,6 +863,32 @@ Sets the node which node path references will travel from. ---- +.. _class_AnimationPlayer_method_set_section: + +.. rst-class:: classref-method + +|void| **set_section**\ (\ start_time\: :ref:`float` = -1, end_time\: :ref:`float` = -1\ ) :ref:`๐Ÿ”—` + +Changes the start and end times of the section being played. The current playback position will be clamped within the new section. See also :ref:`play_section`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AnimationPlayer_method_set_section_with_markers: + +.. rst-class:: classref-method + +|void| **set_section_with_markers**\ (\ start_marker\: :ref:`StringName` = &"", end_marker\: :ref:`StringName` = &""\ ) :ref:`๐Ÿ”—` + +Changes the start and end markers of the section being played. The current playback position will be clamped within the new section. See also :ref:`play_section_with_markers`. + +If the argument is empty, the section uses the beginning or end of the animation. If both are empty, it means that the section is not set. + +.. rst-class:: classref-item-separator + +---- + .. _class_AnimationPlayer_method_stop: .. rst-class:: classref-method diff --git a/classes/class_area2d.rst b/classes/class_area2d.rst index a47df40ffed..e06699e42d5 100644 --- a/classes/class_area2d.rst +++ b/classes/class_area2d.rst @@ -146,7 +146,7 @@ Emitted when a :ref:`Shape2D` of the received ``area`` enters a s \ ``local_shape_index`` and ``area_shape_index`` contain indices of the interacting shapes from this area and the other area, respectively. ``area_rid`` contains the :ref:`RID` of the other area. These values can be used with the :ref:`PhysicsServer2D`. -\ **Example of getting the** :ref:`CollisionShape2D` **node from the shape index:**\ +\ **Example:** Get the :ref:`CollisionShape2D` node from the shape index: .. tabs:: @@ -213,7 +213,7 @@ Emitted when a :ref:`Shape2D` of the received ``body`` enters a s \ ``local_shape_index`` and ``body_shape_index`` contain indices of the interacting shapes from this area and the interacting body, respectively. ``body_rid`` contains the :ref:`RID` of the body. These values can be used with the :ref:`PhysicsServer2D`. -\ **Example of getting the** :ref:`CollisionShape2D` **node from the shape index:**\ +\ **Example:** Get the :ref:`CollisionShape2D` node from the shape index: .. tabs:: diff --git a/classes/class_area3d.rst b/classes/class_area3d.rst index 67d979f8775..9c0b2aaf80c 100644 --- a/classes/class_area3d.rst +++ b/classes/class_area3d.rst @@ -160,7 +160,7 @@ Emitted when a :ref:`Shape3D` of the received ``area`` enters a s \ ``local_shape_index`` and ``area_shape_index`` contain indices of the interacting shapes from this area and the other area, respectively. ``area_rid`` contains the :ref:`RID` of the other area. These values can be used with the :ref:`PhysicsServer3D`. -\ **Example of getting the** :ref:`CollisionShape3D` **node from the shape index:**\ +\ **Example:** Get the :ref:`CollisionShape3D` node from the shape index: .. tabs:: @@ -227,7 +227,7 @@ Emitted when a :ref:`Shape3D` of the received ``body`` enters a s \ ``local_shape_index`` and ``body_shape_index`` contain indices of the interacting shapes from this area and the interacting body, respectively. ``body_rid`` contains the :ref:`RID` of the body. These values can be used with the :ref:`PhysicsServer3D`. -\ **Example of getting the** :ref:`CollisionShape3D` **node from the shape index:**\ +\ **Example:** Get the :ref:`CollisionShape3D` node from the shape index: .. tabs:: diff --git a/classes/class_array.rst b/classes/class_array.rst index f7a93b7a2a0..bb14c5a11be 100644 --- a/classes/class_array.rst +++ b/classes/class_array.rst @@ -17,9 +17,7 @@ A built-in data structure that holds a sequence of elements. Description ----------- -An array data structure that can contain a sequence of elements of any :ref:`Variant` type. Elements are accessed by a numerical index starting at 0. Negative indices are used to count from the back (-1 is the last element, -2 is the second to last, etc.). - -\ **Example:**\ +An array data structure that can contain a sequence of elements of any :ref:`Variant` type. Elements are accessed by a numerical index starting at ``0``. Negative indices are used to count from the back (``-1`` is the last element, ``-2`` is the second to last, etc.). .. tabs:: @@ -133,8 +131,12 @@ Methods +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`find`\ (\ what\: :ref:`Variant`, from\: :ref:`int` = 0\ ) |const| | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`find_custom`\ (\ method\: :ref:`Callable`, from\: :ref:`int` = 0\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`front`\ (\ ) |const| | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`get`\ (\ index\: :ref:`int`\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_typed_builtin`\ (\ ) |const| | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`StringName` | :ref:`get_typed_class_name`\ (\ ) |const| | @@ -185,6 +187,10 @@ Methods +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`rfind`\ (\ what\: :ref:`Variant`, from\: :ref:`int` = -1\ ) |const| | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`rfind_custom`\ (\ method\: :ref:`Callable`, from\: :ref:`int` = -1\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set`\ (\ index\: :ref:`int`, value\: :ref:`Variant`\ ) | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`shuffle`\ (\ ) | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`size`\ (\ ) |const| | @@ -522,7 +528,7 @@ Appends another ``array`` at the end of this array. var numbers = [1, 2, 3] var extra = [4, 5, 6] numbers.append_array(extra) - print(nums) # Prints [1, 2, 3, 4, 5, 6] + print(numbers) # Prints [1, 2, 3, 4, 5, 6] .. rst-class:: classref-item-separator @@ -641,6 +647,8 @@ Removes all elements from the array. This is equivalent to using :ref:`resize`. + .. rst-class:: classref-item-separator ---- @@ -751,6 +759,35 @@ Returns the index of the **first** occurrence of ``what`` in this array, or ``-1 \ **Note:** For performance reasons, the search is affected by ``what``'s :ref:`Variant.Type`. For example, ``7`` (:ref:`int`) and ``7.0`` (:ref:`float`) are not considered equal for this method. +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_find_custom: + +.. rst-class:: classref-method + +:ref:`int` **find_custom**\ (\ method\: :ref:`Callable`, from\: :ref:`int` = 0\ ) |const| :ref:`๐Ÿ”—` + +Returns the index of the **first** element in the array that causes ``method`` to return ``true``, or ``-1`` if there are none. The search's start can be specified with ``from``, continuing to the end of the array. + +\ ``method`` is a callable that takes an element of the array, and returns a :ref:`bool`. + +\ **Note:** If you just want to know whether the array contains *anything* that satisfies ``method``, use :ref:`any`. + + +.. tabs:: + + .. code-tab:: gdscript + + func is_even(number): + return number % 2 == 0 + + func _ready(): + print([1, 3, 4, 7].find_custom(is_even.bind())) # prints 2 + + + .. rst-class:: classref-item-separator ---- @@ -769,6 +806,18 @@ Returns the first element of the array. If the array is empty, fails and returns ---- +.. _class_Array_method_get: + +.. rst-class:: classref-method + +:ref:`Variant` **get**\ (\ index\: :ref:`int`\ ) |const| :ref:`๐Ÿ”—` + +Returns the element at the given ``index`` in the array. This is the same as using the ``[]`` operator (``array[index]``). + +.. rst-class:: classref-item-separator + +---- + .. _class_Array_method_get_typed_builtin: .. rst-class:: classref-method @@ -1131,6 +1180,19 @@ If :ref:`max` is not desirable, this method may also be func is_length_greater(a, b): return a.length() > b.length() +This method can also be used to count how many elements in an array satisfy a certain condition, similar to :ref:`count`: + +:: + + func is_even(number): + return number % 2 == 0 + + func _ready(): + var arr = [1, 2, 3, 4, 5] + # Increment count if it's even, else leaves count the same. + var even_count = arr.reduce(func(count, next): return count + 1 if is_even(next) else count, 0) + print(even_count) # Prints 2 + See also :ref:`map`, :ref:`filter`, :ref:`any` and :ref:`all`. .. rst-class:: classref-item-separator @@ -1195,6 +1257,30 @@ Returns the index of the **last** occurrence of ``what`` in this array, or ``-1` ---- +.. _class_Array_method_rfind_custom: + +.. rst-class:: classref-method + +:ref:`int` **rfind_custom**\ (\ method\: :ref:`Callable`, from\: :ref:`int` = -1\ ) |const| :ref:`๐Ÿ”—` + +Returns the index of the **last** element of the array that causes ``method`` to return ``true``, or ``-1`` if there are none. The search's start can be specified with ``from``, continuing to the beginning of the array. This method is the reverse of :ref:`find_custom`. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Array_method_set: + +.. rst-class:: classref-method + +|void| **set**\ (\ index\: :ref:`int`, value\: :ref:`Variant`\ ) :ref:`๐Ÿ”—` + +Sets the value of the element at the given ``index`` to the given ``value``. This will not change the size of the array, it only changes the value at an index already in the array. This is the same as using the ``[]`` operator (``array[index] = value``). + +.. rst-class:: classref-item-separator + +---- + .. _class_Array_method_shuffle: .. rst-class:: classref-method @@ -1289,7 +1375,7 @@ Sorts the array in ascending order. The final order is dependent on the "less th Sorts the array using a custom :ref:`Callable`. -\ ``func`` is called as many times as necessary, receiving two array elements as arguments. The function should return ``true`` if the first element should be moved *behind* the second one, otherwise it should return ``false``. +\ ``func`` is called as many times as necessary, receiving two array elements as arguments. The function should return ``true`` if the first element should be moved *before* the second one, otherwise it should return ``false``. :: @@ -1304,7 +1390,7 @@ Sorts the array using a custom :ref:`Callable`. print(my_items) # Prints [["Rice", 4], ["Tomato", 5], ["Apple", 9]] # Sort descending, using a lambda function. - my_items.sort_custom(func(a, b): return a[0] > b[0]) + my_items.sort_custom(func(a, b): return a[1] > b[1]) print(my_items) # Prints [["Apple", 9], ["Tomato", 5], ["Rice", 4]] It may also be necessary to use this method to sort strings by natural order, with :ref:`String.naturalnocasecmp_to`, as in the following example: diff --git a/classes/class_astar2d.rst b/classes/class_astar2d.rst index 91eef236561..0d09e9b4711 100644 --- a/classes/class_astar2d.rst +++ b/classes/class_astar2d.rst @@ -34,7 +34,7 @@ Methods +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`_compute_cost`\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) |virtual| |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`float` | :ref:`_estimate_cost`\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) |virtual| |const| | + | :ref:`float` | :ref:`_estimate_cost`\ (\ from_id\: :ref:`int`, end_id\: :ref:`int`\ ) |virtual| |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`add_point`\ (\ id\: :ref:`int`, position\: :ref:`Vector2`, weight_scale\: :ref:`float` = 1.0\ ) | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -110,7 +110,7 @@ Note that this function is hidden in the default **AStar2D** class. .. rst-class:: classref-method -:ref:`float` **_estimate_cost**\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) |virtual| |const| :ref:`๐Ÿ”—` +:ref:`float` **_estimate_cost**\ (\ from_id\: :ref:`int`, end_id\: :ref:`int`\ ) |virtual| |const| :ref:`๐Ÿ”—` Called when estimating the cost between a point and the path's ending point. @@ -289,6 +289,8 @@ Returns an array with the IDs of the points that form the path found by AStar2D If there is no valid path to the target, and ``allow_partial_path`` is ``true``, returns a path to the point closest to the target that can be reached. +\ **Note:** When ``allow_partial_path`` is ``true`` and ``to_id`` is disabled the search may take an unusually long time to finish. + .. tabs:: @@ -319,7 +321,7 @@ If there is no valid path to the target, and ``allow_partial_path`` is ``true``, astar.ConnectPoints(2, 3, false); astar.ConnectPoints(4, 3, false); astar.ConnectPoints(1, 4, false); - int[] res = astar.GetIdPath(1, 3); // Returns [1, 2, 3] + long[] res = astar.GetIdPath(1, 3); // Returns [1, 2, 3] @@ -376,7 +378,7 @@ Returns an array with the IDs of the points that form the connection with the gi astar.ConnectPoints(1, 2, true); astar.ConnectPoints(1, 3, true); - int[] neighbors = astar.GetPointConnections(1); // Returns [2, 3] + long[] neighbors = astar.GetPointConnections(1); // Returns [2, 3] @@ -420,6 +422,8 @@ If there is no valid path to the target, and ``allow_partial_path`` is ``true``, \ **Note:** This method is not thread-safe. If called from a :ref:`Thread`, it will return an empty array and will print an error message. +Additionally, when ``allow_partial_path`` is ``true`` and ``to_id`` is disabled the search may take an unusually long time to finish. + .. rst-class:: classref-item-separator ---- @@ -490,7 +494,7 @@ Removes the point associated with the given ``id`` from the points pool. |void| **reserve_space**\ (\ num_nodes\: :ref:`int`\ ) :ref:`๐Ÿ”—` -Reserves space internally for ``num_nodes`` points, useful if you're adding a known large number of points at once, such as points on a grid. New capacity must be greater or equals to old capacity. +Reserves space internally for ``num_nodes`` points. Useful if you're adding a known large number of points at once, such as points on a grid. The new capacity must be greater or equal to the old capacity. .. rst-class:: classref-item-separator diff --git a/classes/class_astar3d.rst b/classes/class_astar3d.rst index 68a00d86253..6fbb98bc0a6 100644 --- a/classes/class_astar3d.rst +++ b/classes/class_astar3d.rst @@ -71,7 +71,7 @@ Methods +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`_compute_cost`\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) |virtual| |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`float` | :ref:`_estimate_cost`\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) |virtual| |const| | + | :ref:`float` | :ref:`_estimate_cost`\ (\ from_id\: :ref:`int`, end_id\: :ref:`int`\ ) |virtual| |const| | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`add_point`\ (\ id\: :ref:`int`, position\: :ref:`Vector3`, weight_scale\: :ref:`float` = 1.0\ ) | +-----------------------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -147,7 +147,7 @@ Note that this function is hidden in the default **AStar3D** class. .. rst-class:: classref-method -:ref:`float` **_estimate_cost**\ (\ from_id\: :ref:`int`, to_id\: :ref:`int`\ ) |virtual| |const| :ref:`๐Ÿ”—` +:ref:`float` **_estimate_cost**\ (\ from_id\: :ref:`int`, end_id\: :ref:`int`\ ) |virtual| |const| :ref:`๐Ÿ”—` Called when estimating the cost between a point and the path's ending point. @@ -326,6 +326,8 @@ Returns an array with the IDs of the points that form the path found by AStar3D If there is no valid path to the target, and ``allow_partial_path`` is ``true``, returns a path to the point closest to the target that can be reached. +\ **Note:** When ``allow_partial_path`` is ``true`` and ``to_id`` is disabled the search may take an unusually long time to finish. + .. tabs:: @@ -355,7 +357,7 @@ If there is no valid path to the target, and ``allow_partial_path`` is ``true``, astar.ConnectPoints(2, 3, false); astar.ConnectPoints(4, 3, false); astar.ConnectPoints(1, 4, false); - int[] res = astar.GetIdPath(1, 3); // Returns [1, 2, 3] + long[] res = astar.GetIdPath(1, 3); // Returns [1, 2, 3] @@ -411,7 +413,7 @@ Returns an array with the IDs of the points that form the connection with the gi astar.ConnectPoints(1, 2, true); astar.ConnectPoints(1, 3, true); - int[] neighbors = astar.GetPointConnections(1); // Returns [2, 3] + long[] neighbors = astar.GetPointConnections(1); // Returns [2, 3] @@ -455,6 +457,8 @@ If there is no valid path to the target, and ``allow_partial_path`` is ``true``, \ **Note:** This method is not thread-safe. If called from a :ref:`Thread`, it will return an empty array and will print an error message. +Additionally, when ``allow_partial_path`` is ``true`` and ``to_id`` is disabled the search may take an unusually long time to finish. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_astargrid2d.rst b/classes/class_astargrid2d.rst index 770356dc125..91a5427f25e 100644 --- a/classes/class_astargrid2d.rst +++ b/classes/class_astargrid2d.rst @@ -84,39 +84,41 @@ Methods .. table:: :widths: auto - +--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`float` | :ref:`_compute_cost`\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`\ ) |virtual| |const| | - +--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`float` | :ref:`_estimate_cost`\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`\ ) |virtual| |const| | - +--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`clear`\ (\ ) | - +--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`fill_solid_region`\ (\ region\: :ref:`Rect2i`, solid\: :ref:`bool` = true\ ) | - +--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`fill_weight_scale_region`\ (\ region\: :ref:`Rect2i`, weight_scale\: :ref:`float`\ ) | - +--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Array`\[:ref:`Vector2i`\] | :ref:`get_id_path`\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`, allow_partial_path\: :ref:`bool` = false\ ) | - +--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`PackedVector2Array` | :ref:`get_point_path`\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`, allow_partial_path\: :ref:`bool` = false\ ) | - +--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Vector2` | :ref:`get_point_position`\ (\ id\: :ref:`Vector2i`\ ) |const| | - +--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`float` | :ref:`get_point_weight_scale`\ (\ id\: :ref:`Vector2i`\ ) |const| | - +--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`is_dirty`\ (\ ) |const| | - +--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`is_in_bounds`\ (\ x\: :ref:`int`, y\: :ref:`int`\ ) |const| | - +--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`is_in_boundsv`\ (\ id\: :ref:`Vector2i`\ ) |const| | - +--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`is_point_solid`\ (\ id\: :ref:`Vector2i`\ ) |const| | - +--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`set_point_solid`\ (\ id\: :ref:`Vector2i`, solid\: :ref:`bool` = true\ ) | - +--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`set_point_weight_scale`\ (\ id\: :ref:`Vector2i`, weight_scale\: :ref:`float`\ ) | - +--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`update`\ (\ ) | - +--------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`_compute_cost`\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`\ ) |virtual| |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`_estimate_cost`\ (\ from_id\: :ref:`Vector2i`, end_id\: :ref:`Vector2i`\ ) |virtual| |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`clear`\ (\ ) | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`fill_solid_region`\ (\ region\: :ref:`Rect2i`, solid\: :ref:`bool` = true\ ) | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`fill_weight_scale_region`\ (\ region\: :ref:`Rect2i`, weight_scale\: :ref:`float`\ ) | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`Vector2i`\] | :ref:`get_id_path`\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`, allow_partial_path\: :ref:`bool` = false\ ) | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Array`\[:ref:`Dictionary`\] | :ref:`get_point_data_in_region`\ (\ region\: :ref:`Rect2i`\ ) |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedVector2Array` | :ref:`get_point_path`\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`, allow_partial_path\: :ref:`bool` = false\ ) | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Vector2` | :ref:`get_point_position`\ (\ id\: :ref:`Vector2i`\ ) |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_point_weight_scale`\ (\ id\: :ref:`Vector2i`\ ) |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_dirty`\ (\ ) |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_in_bounds`\ (\ x\: :ref:`int`, y\: :ref:`int`\ ) |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_in_boundsv`\ (\ id\: :ref:`Vector2i`\ ) |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_point_solid`\ (\ id\: :ref:`Vector2i`\ ) |const| | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_point_solid`\ (\ id\: :ref:`Vector2i`, solid\: :ref:`bool` = true\ ) | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_point_weight_scale`\ (\ id\: :ref:`Vector2i`, weight_scale\: :ref:`float`\ ) | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`update`\ (\ ) | + +------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -483,7 +485,7 @@ Note that this function is hidden in the default **AStarGrid2D** class. .. rst-class:: classref-method -:ref:`float` **_estimate_cost**\ (\ from_id\: :ref:`Vector2i`, to_id\: :ref:`Vector2i`\ ) |virtual| |const| :ref:`๐Ÿ”—` +:ref:`float` **_estimate_cost**\ (\ from_id\: :ref:`Vector2i`, end_id\: :ref:`Vector2i`\ ) |virtual| |const| :ref:`๐Ÿ”—` Called when estimating the cost between a point and the path's ending point. @@ -543,6 +545,20 @@ Returns an array with the IDs of the points that form the path found by AStar2D If there is no valid path to the target, and ``allow_partial_path`` is ``true``, returns a path to the point closest to the target that can be reached. +\ **Note:** When ``allow_partial_path`` is ``true`` and ``to_id`` is solid the search may take an unusually long time to finish. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AStarGrid2D_method_get_point_data_in_region: + +.. rst-class:: classref-method + +:ref:`Array`\[:ref:`Dictionary`\] **get_point_data_in_region**\ (\ region\: :ref:`Rect2i`\ ) |const| :ref:`๐Ÿ”—` + +Returns an array of dictionaries with point data (``id``: :ref:`Vector2i`, ``position``: :ref:`Vector2`, ``solid``: :ref:`bool`, ``weight_scale``: :ref:`float`) within a ``region``. + .. rst-class:: classref-item-separator ---- @@ -559,6 +575,8 @@ If there is no valid path to the target, and ``allow_partial_path`` is ``true``, \ **Note:** This method is not thread-safe. If called from a :ref:`Thread`, it will return an empty array and will print an error message. +Additionally, when ``allow_partial_path`` is ``true`` and ``to_id`` is solid the search may take an unusually long time to finish. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_atlastexture.rst b/classes/class_atlastexture.rst index 70457128a5c..ff3384aa790 100644 --- a/classes/class_atlastexture.rst +++ b/classes/class_atlastexture.rst @@ -23,7 +23,7 @@ Description Multiple **AtlasTexture** resources can be cropped from the same :ref:`atlas`. Packing many smaller textures into a singular large texture helps to optimize video memory costs and render calls. -\ **Note:** **AtlasTexture** cannot be used in an :ref:`AnimatedTexture`, and may not tile properly in nodes such as :ref:`TextureRect`, when inside other **AtlasTexture** resources. +\ **Note:** **AtlasTexture** cannot be used in an :ref:`AnimatedTexture`, and will not tile properly in nodes such as :ref:`TextureRect` or :ref:`Sprite2D`. To tile an **AtlasTexture**, modify its :ref:`region` instead. .. rst-class:: classref-reftable-group diff --git a/classes/class_audioeffectfilter.rst b/classes/class_audioeffectfilter.rst index b3d55990523..11e939b6640 100644 --- a/classes/class_audioeffectfilter.rst +++ b/classes/class_audioeffectfilter.rst @@ -69,11 +69,7 @@ enum **FilterDB**: :ref:`๐Ÿ”—` :ref:`FilterDB` **FILTER_6DB** = ``0`` -.. container:: contribute - - There is currently no description for this enum. Please help us by :ref:`contributing one `! - - +Cutting off at 6dB per octave. .. _class_AudioEffectFilter_constant_FILTER_12DB: @@ -81,11 +77,7 @@ enum **FilterDB**: :ref:`๐Ÿ”—` :ref:`FilterDB` **FILTER_12DB** = ``1`` -.. container:: contribute - - There is currently no description for this enum. Please help us by :ref:`contributing one `! - - +Cutting off at 12dB per octave. .. _class_AudioEffectFilter_constant_FILTER_18DB: @@ -93,11 +85,7 @@ enum **FilterDB**: :ref:`๐Ÿ”—` :ref:`FilterDB` **FILTER_18DB** = ``2`` -.. container:: contribute - - There is currently no description for this enum. Please help us by :ref:`contributing one `! - - +Cutting off at 18dB per octave. .. _class_AudioEffectFilter_constant_FILTER_24DB: @@ -105,11 +93,7 @@ enum **FilterDB**: :ref:`๐Ÿ”—` :ref:`FilterDB` **FILTER_24DB** = ``3`` -.. container:: contribute - - There is currently no description for this enum. Please help us by :ref:`contributing one `! - - +Cutting off at 24dB per octave. .. rst-class:: classref-section-separator @@ -148,9 +132,7 @@ Threshold frequency for the filter, in Hz. - |void| **set_db**\ (\ value\: :ref:`FilterDB`\ ) - :ref:`FilterDB` **get_db**\ (\ ) -.. container:: contribute - - There is currently no description for this property. Please help us by :ref:`contributing one `! +Steepness of the cutoff curve in dB per octave, also known as the order of the filter. Higher orders have a more aggressive cutoff. .. rst-class:: classref-item-separator diff --git a/classes/class_audioeffectspectrumanalyzer.rst b/classes/class_audioeffectspectrumanalyzer.rst index 2a862c5c0f3..4e01dc5d26d 100644 --- a/classes/class_audioeffectspectrumanalyzer.rst +++ b/classes/class_audioeffectspectrumanalyzer.rst @@ -21,7 +21,7 @@ Description This audio effect does not affect sound output, but can be used for real-time audio visualizations. -This resource configures an :ref:`AudioEffectSpectrumAnalyzerInstance`, which performs the actual analysis at runtime. An instance can be acquired with :ref:`AudioServer.get_bus_effect_instance`. +This resource configures an :ref:`AudioEffectSpectrumAnalyzerInstance`, which performs the actual analysis at runtime. An instance can be obtained with :ref:`AudioServer.get_bus_effect_instance`. See also :ref:`AudioStreamGenerator` for procedurally generating sounds. diff --git a/classes/class_audioeffectspectrumanalyzerinstance.rst b/classes/class_audioeffectspectrumanalyzerinstance.rst index 68c533dcf73..00f953b3935 100644 --- a/classes/class_audioeffectspectrumanalyzerinstance.rst +++ b/classes/class_audioeffectspectrumanalyzerinstance.rst @@ -21,7 +21,7 @@ Description The runtime part of an :ref:`AudioEffectSpectrumAnalyzer`, which can be used to query the magnitude of a frequency range on its host bus. -An instance of this class can be acquired with :ref:`AudioServer.get_bus_effect_instance`. +An instance of this class can be obtained with :ref:`AudioServer.get_bus_effect_instance`. .. rst-class:: classref-introduction-group diff --git a/classes/class_audioeffectstereoenhance.rst b/classes/class_audioeffectstereoenhance.rst index ed98852e81e..2b4b2015ef0 100644 --- a/classes/class_audioeffectstereoenhance.rst +++ b/classes/class_audioeffectstereoenhance.rst @@ -64,7 +64,7 @@ Property Descriptions - |void| **set_pan_pullout**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_pan_pullout**\ (\ ) -Values greater than 1.0 increase intensity of any panning on audio passing through this effect, whereas values less than 1.0 will decrease the panning intensity. A value of 0.0 will downmix audio to mono. +Amplifies the difference between stereo channels, increasing or decreasing existing panning. A value of 0.0 will downmix stereo to mono. Does not affect a mono signal. .. rst-class:: classref-item-separator @@ -81,9 +81,7 @@ Values greater than 1.0 increase intensity of any panning on audio passing throu - |void| **set_surround**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_surround**\ (\ ) -.. container:: contribute - - There is currently no description for this property. Please help us by :ref:`contributing one `! +Widens sound stage through phase shifting in conjunction with :ref:`time_pullout_ms`. Just pans sound to the left channel if :ref:`time_pullout_ms` is 0. .. rst-class:: classref-item-separator @@ -100,9 +98,7 @@ Values greater than 1.0 increase intensity of any panning on audio passing throu - |void| **set_time_pullout**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_time_pullout**\ (\ ) -.. container:: contribute - - There is currently no description for this property. Please help us by :ref:`contributing one `! +Widens sound stage through phase shifting in conjunction with :ref:`surround`. Just delays the right channel if :ref:`surround` is 0. .. |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.)` diff --git a/classes/class_audioserver.rst b/classes/class_audioserver.rst index 5a10f28eec9..aa74e69a2e9 100644 --- a/classes/class_audioserver.rst +++ b/classes/class_audioserver.rst @@ -87,8 +87,12 @@ Methods +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`get_bus_volume_db`\ (\ bus_idx\: :ref:`int`\ ) |const| | +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`get_driver_name`\ (\ ) |const| | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PackedStringArray` | :ref:`get_input_device_list`\ (\ ) | +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_input_mix_rate`\ (\ ) |const| | + +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`float` | :ref:`get_mix_rate`\ (\ ) |const| | +-------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PackedStringArray` | :ref:`get_output_device_list`\ (\ ) | @@ -514,6 +518,18 @@ Returns the volume of the bus at index ``bus_idx`` in dB. ---- +.. _class_AudioServer_method_get_driver_name: + +.. rst-class:: classref-method + +:ref:`String` **get_driver_name**\ (\ ) |const| :ref:`๐Ÿ”—` + +Returns the name of the current audio driver. The default usually depends on the operating system, but may be overridden via the ``--audio-driver`` :doc:`command line argument <../tutorials/editor/command_line_tutorial>`. ``--headless`` also automatically sets the audio driver to ``Dummy``. See also :ref:`ProjectSettings.audio/driver/driver`. + +.. rst-class:: classref-item-separator + +---- + .. _class_AudioServer_method_get_input_device_list: .. rst-class:: classref-method @@ -528,6 +544,18 @@ Returns the names of all audio input devices detected on the system. ---- +.. _class_AudioServer_method_get_input_mix_rate: + +.. rst-class:: classref-method + +:ref:`float` **get_input_mix_rate**\ (\ ) |const| :ref:`๐Ÿ”—` + +Returns the sample rate at the input of the **AudioServer**. + +.. rst-class:: classref-item-separator + +---- + .. _class_AudioServer_method_get_mix_rate: .. rst-class:: classref-method diff --git a/classes/class_audiostream.rst b/classes/class_audiostream.rst index 00ef203ba4d..284aa39ef7a 100644 --- a/classes/class_audiostream.rst +++ b/classes/class_audiostream.rst @@ -168,7 +168,7 @@ Override this method to customize the name assigned to this audio stream. Unused :ref:`AudioStreamPlayback` **_instantiate_playback**\ (\ ) |virtual| |const| :ref:`๐Ÿ”—` -Override this method to customize the returned value of :ref:`instantiate_playback`. Should returned a new :ref:`AudioStreamPlayback` created when the stream is played (such as by an :ref:`AudioStreamPlayer`).. +Override this method to customize the returned value of :ref:`instantiate_playback`. Should return a new :ref:`AudioStreamPlayback` created when the stream is played (such as by an :ref:`AudioStreamPlayer`). .. rst-class:: classref-item-separator diff --git a/classes/class_audiostreaminteractive.rst b/classes/class_audiostreaminteractive.rst index 02e2635cee1..544b64695f4 100644 --- a/classes/class_audiostreaminteractive.rst +++ b/classes/class_audiostreaminteractive.rst @@ -19,7 +19,7 @@ Audio stream that can playback music interactively, combining clips and a transi Description ----------- -This is an audio stream that can playback music interactively, combining clips and a transition table. Clips must be added first, and the transition rules via the :ref:`add_transition`. Additionally, this stream export a property parameter to control the playback via :ref:`AudioStreamPlayer`, :ref:`AudioStreamPlayer2D`, or :ref:`AudioStreamPlayer3D`. +This is an audio stream that can playback music interactively, combining clips and a transition table. Clips must be added first, and then the transition rules via the :ref:`add_transition`. Additionally, this stream exports a property parameter to control the playback via :ref:`AudioStreamPlayer`, :ref:`AudioStreamPlayer2D`, or :ref:`AudioStreamPlayer3D`. The way this is used is by filling a number of clips, then configuring the transition table. From there, clips are selected for playback and the music will smoothly go from the current to the new one while using the corresponding transition rule defined in the transition table. @@ -471,7 +471,7 @@ Return the destination time position for a transition (see :ref:`add_transition< :ref:`bool` **has_transition**\ (\ from_clip\: :ref:`int`, to_clip\: :ref:`int`\ ) |const| :ref:`๐Ÿ”—` -Return true if a given transition exists (was added via :ref:`add_transition`). +Returns ``true`` if a given transition exists (was added via :ref:`add_transition`). .. rst-class:: classref-item-separator diff --git a/classes/class_audiostreamplayback.rst b/classes/class_audiostreamplayback.rst index 76f12f3987b..57a1105990f 100644 --- a/classes/class_audiostreamplayback.rst +++ b/classes/class_audiostreamplayback.rst @@ -59,10 +59,24 @@ Methods +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`_tag_used_streams`\ (\ ) |virtual| | +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_loop_count`\ (\ ) |const| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`float` | :ref:`get_playback_position`\ (\ ) |const| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`AudioSamplePlayback` | :ref:`get_sample_playback`\ (\ ) |const| | +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`is_playing`\ (\ ) |const| | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`PackedVector2Array` | :ref:`mix_audio`\ (\ rate_scale\: :ref:`float`, frames\: :ref:`int`\ ) | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`seek`\ (\ time\: :ref:`float` = 0.0\ ) | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | |void| | :ref:`set_sample_playback`\ (\ playback_sample\: :ref:`AudioSamplePlayback`\ ) | +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`start`\ (\ from_pos\: :ref:`float` = 0.0\ ) | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`stop`\ (\ ) | + +-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -195,6 +209,30 @@ Overridable method. Called whenever the audio stream is mixed if the playback is ---- +.. _class_AudioStreamPlayback_method_get_loop_count: + +.. rst-class:: classref-method + +:ref:`int` **get_loop_count**\ (\ ) |const| :ref:`๐Ÿ”—` + +Returns the number of times the stream has looped. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_method_get_playback_position: + +.. rst-class:: classref-method + +:ref:`float` **get_playback_position**\ (\ ) |const| :ref:`๐Ÿ”—` + +Returns the current position in the stream, in seconds. + +.. rst-class:: classref-item-separator + +---- + .. _class_AudioStreamPlayback_method_get_sample_playback: .. rst-class:: classref-method @@ -209,6 +247,46 @@ Returns the :ref:`AudioSamplePlayback` associated wit ---- +.. _class_AudioStreamPlayback_method_is_playing: + +.. rst-class:: classref-method + +:ref:`bool` **is_playing**\ (\ ) |const| :ref:`๐Ÿ”—` + +Returns ``true`` if the stream is playing. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_method_mix_audio: + +.. rst-class:: classref-method + +:ref:`PackedVector2Array` **mix_audio**\ (\ rate_scale\: :ref:`float`, frames\: :ref:`int`\ ) :ref:`๐Ÿ”—` + +Mixes up to ``frames`` of audio from the stream from the current position, at a rate of ``rate_scale``, advancing the stream. + +Returns a :ref:`PackedVector2Array` where each element holds the left and right channel volume levels of each frame. + +\ **Note:** Can return fewer frames than requested, make sure to use the size of the return value. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_method_seek: + +.. rst-class:: classref-method + +|void| **seek**\ (\ time\: :ref:`float` = 0.0\ ) :ref:`๐Ÿ”—` + +Seeks the stream at the given ``time``, in seconds. + +.. rst-class:: classref-item-separator + +---- + .. _class_AudioStreamPlayback_method_set_sample_playback: .. rst-class:: classref-method @@ -219,6 +297,30 @@ Returns the :ref:`AudioSamplePlayback` associated wit Associates :ref:`AudioSamplePlayback` to this **AudioStreamPlayback** for playing back the audio sample of this stream. +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_method_start: + +.. rst-class:: classref-method + +|void| **start**\ (\ from_pos\: :ref:`float` = 0.0\ ) :ref:`๐Ÿ”—` + +Starts the stream from the given ``from_pos``, in seconds. + +.. rst-class:: classref-item-separator + +---- + +.. _class_AudioStreamPlayback_method_stop: + +.. rst-class:: classref-method + +|void| **stop**\ (\ ) :ref:`๐Ÿ”—` + +Stops the stream. + .. |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.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` diff --git a/classes/class_audiostreamplaybackpolyphonic.rst b/classes/class_audiostreamplaybackpolyphonic.rst index c6d5c216ea8..7ca1d3ce91a 100644 --- a/classes/class_audiostreamplaybackpolyphonic.rst +++ b/classes/class_audiostreamplaybackpolyphonic.rst @@ -73,7 +73,7 @@ Method Descriptions :ref:`bool` **is_stream_playing**\ (\ stream\: :ref:`int`\ ) |const| :ref:`๐Ÿ”—` -Return true whether the stream associated with an integer ID is still playing. Check :ref:`play_stream` for information on when this ID becomes invalid. +Returns ``true`` if the stream associated with the given integer ID is still playing. Check :ref:`play_stream` for information on when this ID becomes invalid. .. rst-class:: classref-item-separator diff --git a/classes/class_audiostreamplayer.rst b/classes/class_audiostreamplayer.rst index 6c7a6c826cd..14b47bfc958 100644 --- a/classes/class_audiostreamplayer.rst +++ b/classes/class_audiostreamplayer.rst @@ -276,6 +276,7 @@ The playback type of the stream player. If set other than to the default value, .. rst-class:: classref-property-setget +- |void| **set_playing**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_playing**\ (\ ) If ``true``, this node is playing sounds. Setting this property has the same effect as :ref:`play` and :ref:`stop`. @@ -354,6 +355,8 @@ Returns the position in the :ref:`AudioStream` of the latest \ **Note:** The position is not always accurate, as the :ref:`AudioServer` does not mix audio every processed frame. To get more accurate results, add :ref:`AudioServer.get_time_since_last_mix` to the returned position. +\ **Note:** This method always returns ``0.0`` if the :ref:`stream` is an :ref:`AudioStreamInteractive`, since it can have multiple clips playing at once. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_audiostreamplayer2d.rst b/classes/class_audiostreamplayer2d.rst index ac52ce133d0..d21a37e4428 100644 --- a/classes/class_audiostreamplayer2d.rst +++ b/classes/class_audiostreamplayer2d.rst @@ -286,6 +286,7 @@ The playback type of the stream player. If set other than to the default value, .. rst-class:: classref-property-setget +- |void| **set_playing**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_playing**\ (\ ) If ``true``, audio is playing or is queued to be played (see :ref:`play`). diff --git a/classes/class_audiostreamplayer3d.rst b/classes/class_audiostreamplayer3d.rst index 1160b7cd272..9ac194f2a98 100644 --- a/classes/class_audiostreamplayer3d.rst +++ b/classes/class_audiostreamplayer3d.rst @@ -502,6 +502,7 @@ The playback type of the stream player. If set other than to the default value, .. rst-class:: classref-property-setget +- |void| **set_playing**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_playing**\ (\ ) If ``true``, audio is playing or is queued to be played (see :ref:`play`). diff --git a/classes/class_audiostreamwav.rst b/classes/class_audiostreamwav.rst index fb21bcccfb9..e61b8c68c31 100644 --- a/classes/class_audiostreamwav.rst +++ b/classes/class_audiostreamwav.rst @@ -87,7 +87,7 @@ enum **Format**: :ref:`๐Ÿ”—` :ref:`Format` **FORMAT_8_BITS** = ``0`` -8-bit audio codec. +8-bit PCM audio codec. .. _class_AudioStreamWAV_constant_FORMAT_16_BITS: @@ -95,7 +95,7 @@ enum **Format**: :ref:`๐Ÿ”—` :ref:`Format` **FORMAT_16_BITS** = ``1`` -16-bit audio codec. +16-bit PCM audio codec. .. _class_AudioStreamWAV_constant_FORMAT_IMA_ADPCM: @@ -103,7 +103,7 @@ enum **Format**: :ref:`๐Ÿ”—` :ref:`Format` **FORMAT_IMA_ADPCM** = ``2`` -Audio is compressed using IMA ADPCM. +Audio is lossily compressed as IMA ADPCM. .. _class_AudioStreamWAV_constant_FORMAT_QOA: @@ -111,7 +111,7 @@ Audio is compressed using IMA ADPCM. :ref:`Format` **FORMAT_QOA** = ``3`` -Audio is compressed as QOA (`Quite OK Audio `__). +Audio is lossily compressed as `Quite OK Audio `__. .. rst-class:: classref-item-separator @@ -177,7 +177,9 @@ Property Descriptions Contains the audio data in bytes. -\ **Note:** This property expects signed PCM8 data. To convert unsigned PCM8 to signed PCM8, subtract 128 from each byte. +\ **Note:** If :ref:`format` is set to :ref:`FORMAT_8_BITS`, this property expects signed 8-bit PCM data. To convert from unsigned 8-bit PCM, subtract 128 from each byte. + +\ **Note:** If :ref:`format` is set to :ref:`FORMAT_QOA`, this property expects data from a full QOA file. **Note:** The returned array is *copied* and any changes to it will not update the original property value. See :ref:`PackedByteArray` for more details. @@ -213,7 +215,7 @@ Audio format. See :ref:`Format` constants for values - |void| **set_loop_begin**\ (\ value\: :ref:`int`\ ) - :ref:`int` **get_loop_begin**\ (\ ) -The loop start point (in number of samples, relative to the beginning of the stream). This information will be imported automatically from the WAV file if present. +The loop start point (in number of samples, relative to the beginning of the stream). .. rst-class:: classref-item-separator @@ -230,7 +232,7 @@ The loop start point (in number of samples, relative to the beginning of the str - |void| **set_loop_end**\ (\ value\: :ref:`int`\ ) - :ref:`int` **get_loop_end**\ (\ ) -The loop end point (in number of samples, relative to the beginning of the stream). This information will be imported automatically from the WAV file if present. +The loop end point (in number of samples, relative to the beginning of the stream). .. rst-class:: classref-item-separator @@ -247,7 +249,7 @@ The loop end point (in number of samples, relative to the beginning of the strea - |void| **set_loop_mode**\ (\ value\: :ref:`LoopMode`\ ) - :ref:`LoopMode` **get_loop_mode**\ (\ ) -The loop mode. This information will be imported automatically from the WAV file if present. See :ref:`LoopMode` constants for values. +The loop mode. See :ref:`LoopMode` constants for values. .. rst-class:: classref-item-separator @@ -302,7 +304,7 @@ Method Descriptions :ref:`Error` **save_to_wav**\ (\ path\: :ref:`String`\ ) :ref:`๐Ÿ”—` -Saves the AudioStreamWAV as a WAV file to ``path``. Samples with IMA ADPCM or QOA formats can't be saved. +Saves the AudioStreamWAV as a WAV file to ``path``. Samples with IMA ADPCM or Quite OK Audio formats can't be saved. \ **Note:** A ``.wav`` extension is automatically appended to ``path`` if it is missing. diff --git a/classes/class_backbuffercopy.rst b/classes/class_backbuffercopy.rst index 0b3ac0b753a..2e5e4324920 100644 --- a/classes/class_backbuffercopy.rst +++ b/classes/class_backbuffercopy.rst @@ -23,6 +23,13 @@ Node for back-buffering the currently-displayed screen. The region defined in th \ **Note:** Since this node inherits from :ref:`Node2D` (and not :ref:`Control`), anchors and margins won't apply to child :ref:`Control`-derived nodes. This can be problematic when resizing the window. To avoid this, add :ref:`Control`-derived nodes as *siblings* to the **BackBufferCopy** node instead of adding them as children. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`Screen-reading shaders <../tutorials/shaders/screen-reading_shaders>` + .. rst-class:: classref-reftable-group Properties diff --git a/classes/class_basebutton.rst b/classes/class_basebutton.rst index acb2d2a0be8..b5f9ec04a12 100644 --- a/classes/class_basebutton.rst +++ b/classes/class_basebutton.rst @@ -288,7 +288,7 @@ To allow both left-click and right-click, use ``MOUSE_BUTTON_MASK_LEFT | MOUSE_B If ``true``, the button's state is pressed. Means the button is pressed down or toggled (if :ref:`toggle_mode` is active). Only works if :ref:`toggle_mode` is ``true``. -\ **Note:** Setting :ref:`button_pressed` will result in :ref:`toggled` to be emitted. If you want to change the pressed state without emitting that signal, use :ref:`set_pressed_no_signal`. +\ **Note:** Changing the value of :ref:`button_pressed` will result in :ref:`toggled` to be emitted. If you want to change the pressed state without emitting that signal, use :ref:`set_pressed_no_signal`. .. rst-class:: classref-item-separator @@ -377,6 +377,8 @@ If ``true``, the button will highlight for a short amount of time when its short If ``true``, the button will add information about its shortcut in the tooltip. +\ **Note:** This property does nothing when the tooltip control is customized using :ref:`Control._make_custom_tooltip`. + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_basematerial3d.rst b/classes/class_basematerial3d.rst index 02634ebaf45..dd1850331b8 100644 --- a/classes/class_basematerial3d.rst +++ b/classes/class_basematerial3d.rst @@ -645,7 +645,7 @@ The object will be shaded per pixel. Useful for realistic shading effects. :ref:`ShadingMode` **SHADING_MODE_PER_VERTEX** = ``2`` -The object will be shaded per vertex. Useful when you want cheaper shaders and do not care about visual quality. Not implemented yet (this mode will act like :ref:`SHADING_MODE_PER_PIXEL`). +The object will be shaded per vertex. Useful when you want cheaper shaders and do not care about visual quality. .. _class_BaseMaterial3D_constant_SHADING_MODE_MAX: @@ -1536,7 +1536,7 @@ The strength of the anisotropy effect. This is multiplied by :ref:`anisotropy_fl - |void| **set_feature**\ (\ feature\: :ref:`Feature`, enable\: :ref:`bool`\ ) - :ref:`bool` **get_feature**\ (\ feature\: :ref:`Feature`\ ) |const| -If ``true``, anisotropy is enabled. Anisotropy changes the shape of the specular blob and aligns it to tangent space. This is useful for brushed aluminium and hair reflections. +If ``true``, anisotropy is enabled. Anisotropy changes the shape of the specular blob and aligns it to tangent space. This is useful for brushed aluminum and hair reflections. \ **Note:** Mesh tangents are needed for anisotropy to work. If the mesh does not contain tangents, the anisotropy effect will appear broken. @@ -1731,8 +1731,6 @@ If ``true``, the shader will keep the scale set for the mesh. Otherwise, the sca Controls how the object faces the camera. See :ref:`BillboardMode`. -\ **Note:** When billboarding is enabled and the material also casts shadows, billboards will face **the** camera in the scene when rendering shadows. In scenes with multiple cameras, the intended shadow cannot be determined and this will result in undefined behavior. See `GitHub Pull Request #72638 `__ for details. - \ **Note:** Billboard mode is not suitable for VR because the left-right vector of the camera is not horizontal when the screen is attached to your head instead of on the table. See `GitHub issue #41567 `__ for details. .. rst-class:: classref-item-separator @@ -2929,8 +2927,6 @@ Specifies the channel of the :ref:`roughness_texture` type is a 3ร—3 `matrix `, :ref:`y`, and :ref:`z`. The length of each axis (:ref:`Vector3.length`) influences the basis's scale, while the direction of all axes influence the rotation. Usually, these axes are perpendicular to one another. However, when you rotate any axis individually, the basis becomes sheared. Applying a sheared basis to a 3D model will make the model appear distorted. -A **Basis** is **orthogonal** if its axes are perpendicular to each other. A basis is **normalized** if the length of every axis is ``1``. A basis is **uniform** if all axes share the same length (see :ref:`get_scale`). A basis is **orthonormal** if it is both orthogonal and normalized, which allows it to only represent rotations. A basis is **conformal** if it is both orthogonal and uniform, which ensures it is not distorted. +A **Basis** is: + +- **Orthogonal** if its axes are perpendicular to each other. + +- **Normalized** if the length of every axis is ``1.0``. + +- **Uniform** if all axes share the same length (see :ref:`get_scale`). + +- **Orthonormal** if it is both orthogonal and normalized, which allows it to only represent rotations (see :ref:`orthonormalized`). + +- **Conformal** if it is both orthogonal and uniform, which ensures it is not distorted. For a general introduction, see the :doc:`Matrices and transforms <../tutorials/math/matrices_and_transforms>` tutorial. @@ -179,7 +189,7 @@ Constants **IDENTITY** = ``Basis(1, 0, 0, 0, 1, 0, 0, 0, 1)`` :ref:`๐Ÿ”—` -The identity basis. This is a basis with no rotation, no shear, and its scale being ``1``. This means that: +The identity **Basis**. This is an orthonormal basis with no rotation, no shear, and a scale of :ref:`Vector3.ONE`. This also means that: - The :ref:`x` points right (:ref:`Vector3.RIGHT`); @@ -189,18 +199,20 @@ The identity basis. This is a basis with no rotation, no shear, and its scale be :: - var basis := Basis.IDENTITY + var basis = Basis.IDENTITY print("| X | Y | Z") - print("| %s | %s | %s" % [basis.x.x, basis.y.x, basis.z.x]) - print("| %s | %s | %s" % [basis.x.y, basis.y.y, basis.z.y]) - print("| %s | %s | %s" % [basis.x.z, basis.y.z, basis.z.z]) + print("| %.f | %.f | %.f" % [basis.x.x, basis.y.x, basis.z.x]) + print("| %.f | %.f | %.f" % [basis.x.y, basis.y.y, basis.z.y]) + print("| %.f | %.f | %.f" % [basis.x.z, basis.y.z, basis.z.z]) # Prints: # | X | Y | Z # | 1 | 0 | 0 # | 0 | 1 | 0 # | 0 | 0 | 1 -This is identical to creating :ref:`Basis` without any parameters. This constant can be used to make your code clearer, and for consistency with C#. +If a :ref:`Vector3` or another **Basis** is transformed (multiplied) by this constant, no transformation occurs. + +\ **Note:** In GDScript, this constant is equivalent to creating a :ref:`Basis` without any arguments. It can be used to make your code clearer, and for consistency with C#. .. _class_Basis_constant_FLIP_X: @@ -294,7 +306,9 @@ Constructor Descriptions :ref:`Basis` **Basis**\ (\ ) :ref:`๐Ÿ”—` -Constructs a **Basis** identical to the :ref:`IDENTITY`. +Constructs a **Basis** identical to :ref:`IDENTITY`. + +\ **Note:** In C#, this constructs a **Basis** with all of its components set to :ref:`Vector3.ZERO`. .. rst-class:: classref-item-separator @@ -357,7 +371,7 @@ Method Descriptions Returns the `determinant `__ of this basis's matrix. For advanced math, this number can be used to determine a few attributes: -- If the determinant is exactly ``0``, the basis is not invertible (see :ref:`inverse`). +- If the determinant is exactly ``0.0``, the basis is not invertible (see :ref:`inverse`). - If the determinant is a negative number, the basis represents a negative scale. @@ -375,9 +389,9 @@ Returns the `determinant `__ of this Constructs a new **Basis** that only represents rotation from the given :ref:`Vector3` of `Euler angles `__, in radians. -- The :ref:`Vector3.x` should contain the angle around the :ref:`x` axis (pitch). +- The :ref:`Vector3.x` should contain the angle around the :ref:`x` axis (pitch); -- The :ref:`Vector3.y` should contain the angle around the :ref:`y` axis (yaw). +- The :ref:`Vector3.y` should contain the angle around the :ref:`y` axis (yaw); - The :ref:`Vector3.z` should contain the angle around the :ref:`z` axis (roll). @@ -389,14 +403,14 @@ Constructs a new **Basis** that only represents rotation from the given :ref:`Ve # Creates a Basis whose z axis points down. var my_basis = Basis.from_euler(Vector3(TAU / 4, 0, 0)) - print(my_basis.z) # Prints (0, -1, 0). + print(my_basis.z) # Prints (0, -1, 0) .. code-tab:: csharp // Creates a Basis whose z axis points down. var myBasis = Basis.FromEuler(new Vector3(Mathf.Tau / 4.0f, 0.0f, 0.0f)); - GD.Print(myBasis.Z); // Prints (0, -1, 0). + GD.Print(myBasis.Z); // Prints (0, -1, 0) @@ -421,17 +435,17 @@ Constructs a new **Basis** that only represents scale, with no rotation or shear var my_basis = Basis.from_scale(Vector3(2, 4, 8)) - print(my_basis.x) # Prints (2, 0, 0). - print(my_basis.y) # Prints (0, 4, 0). - print(my_basis.z) # Prints (0, 0, 8). + print(my_basis.x) # Prints (2, 0, 0) + print(my_basis.y) # Prints (0, 4, 0) + print(my_basis.z) # Prints (0, 0, 8) .. code-tab:: csharp var myBasis = Basis.FromScale(new Vector3(2.0f, 4.0f, 8.0f)); - GD.Print(myBasis.X); // Prints (2, 0, 0). - GD.Print(myBasis.Y); // Prints (0, 4, 0). - GD.Print(myBasis.Z); // Prints (0, 0, 8). + GD.Print(myBasis.X); // Prints (2, 0, 0) + GD.Print(myBasis.Y); // Prints (0, 4, 0) + GD.Print(myBasis.Z); // Prints (0, 0, 8) @@ -447,7 +461,7 @@ Constructs a new **Basis** that only represents scale, with no rotation or shear :ref:`Vector3` **get_euler**\ (\ order\: :ref:`int` = 2\ ) |const| :ref:`๐Ÿ”—` -Returns this basis's rotation as a :ref:`Vector3` of `Euler angles `__, in radians. +Returns this basis's rotation as a :ref:`Vector3` of `Euler angles `__, in radians. For the returned value: - The :ref:`Vector3.x` contains the angle around the :ref:`x` axis (pitch); @@ -457,6 +471,8 @@ Returns this basis's rotation as a :ref:`Vector3` of `Euler angle The order of each consecutive rotation can be changed with ``order`` (see :ref:`EulerOrder` constants). By default, the YXZ convention is used (:ref:`@GlobalScope.EULER_ORDER_YXZ`): Z (roll) is calculated first, then X (pitch), and lastly Y (yaw). When using the opposite method :ref:`from_euler`, this order is reversed. +\ **Note:** For this method to return correctly, the basis needs to be *orthonormal* (see :ref:`orthonormalized`). + \ **Note:** Euler angles are much more intuitive but are not suitable for 3D math. Because of this, consider using the :ref:`get_rotation_quaternion` method instead, which returns a :ref:`Quaternion`. \ **Note:** In the Inspector dock, a basis's rotation is often displayed in Euler angles (in degrees), as is the case with the :ref:`Node3D.rotation` property. @@ -485,7 +501,7 @@ Returns this basis's rotation as a :ref:`Quaternion`. :ref:`Vector3` **get_scale**\ (\ ) |const| :ref:`๐Ÿ”—` -Returns the length of each axis of this basis, as a :ref:`Vector3`. If the basis is not sheared, this is the scaling factor. It is not affected by rotation. +Returns the length of each axis of this basis, as a :ref:`Vector3`. If the basis is not sheared, this value is the scaling factor. It is not affected by rotation. .. tabs:: @@ -501,7 +517,7 @@ Returns the length of each axis of this basis, as a :ref:`Vector3 my_basis = my_basis.rotated(Vector3.UP, TAU / 2) my_basis = my_basis.rotated(Vector3.RIGHT, TAU / 4) - print(my_basis.get_scale()) # Prints (2, 4, 8). + print(my_basis.get_scale()) # Prints (2, 4, 8) .. code-tab:: csharp @@ -514,7 +530,7 @@ Returns the length of each axis of this basis, as a :ref:`Vector3 myBasis = myBasis.Rotated(Vector3.Up, Mathf.Tau / 2.0f); myBasis = myBasis.Rotated(Vector3.Right, Mathf.Tau / 4.0f); - GD.Print(myBasis.Scale); // Prints (2, 4, 8). + GD.Print(myBasis.Scale); // Prints (2, 4, 8) @@ -594,7 +610,7 @@ The up axis (+Y) points as close to the ``up`` vector as possible while staying :ref:`Basis` **orthonormalized**\ (\ ) |const| :ref:`๐Ÿ”—` -Returns the orthonormalized version of this basis. An orthonormal basis is both *orthogonal* (the axes are perpendicular to each other) and *normalized* (the axes have a length of ``1``), which also means it can only represent rotation. +Returns the orthonormalized version of this basis. An orthonormal basis is both *orthogonal* (the axes are perpendicular to each other) and *normalized* (the axes have a length of ``1.0``), which also means it can only represent a rotation. It is often useful to call this method to avoid rounding errors on a rotating basis: @@ -632,9 +648,9 @@ It is often useful to call this method to avoid rounding errors on a rotating ba :ref:`Basis` **rotated**\ (\ axis\: :ref:`Vector3`, angle\: :ref:`float`\ ) |const| :ref:`๐Ÿ”—` -Returns this basis rotated around the given ``axis`` by ``angle`` (in radians). The ``axis`` must be a normalized vector (see :ref:`Vector3.normalized`). +Returns a copy of this basis rotated around the given ``axis`` by the given ``angle`` (in radians). -Positive values rotate this basis clockwise around the axis, while negative values rotate it counterclockwise. +The ``axis`` must be a normalized vector (see :ref:`Vector3.normalized`). If ``angle`` is positive, the basis is rotated counter-clockwise around the axis. .. tabs:: @@ -685,9 +701,9 @@ The basis matrix's rows are multiplied by ``scale``'s components. This operation ) my_basis = my_basis.scaled(Vector3(0, 2, -2)) - print(my_basis.x) # Prints (0, 2, -2). - print(my_basis.y) # Prints (0, 4, -4). - print(my_basis.z) # Prints (0, 6, -6). + print(my_basis.x) # Prints (0, 2, -2) + print(my_basis.y) # Prints (0, 4, -4) + print(my_basis.z) # Prints (0, 6, -6) .. code-tab:: csharp @@ -698,9 +714,9 @@ The basis matrix's rows are multiplied by ``scale``'s components. This operation ); myBasis = myBasis.Scaled(new Vector3(0.0f, 2.0f, -2.0f)); - GD.Print(myBasis.X); // Prints (0, 2, -2). - GD.Print(myBasis.Y); // Prints (0, 4, -4). - GD.Print(myBasis.Z); // Prints (0, 6, -6). + GD.Print(myBasis.X); // Prints (0, 2, -2) + GD.Print(myBasis.Y); // Prints (0, 4, -4) + GD.Print(myBasis.Z); // Prints (0, 6, -6) @@ -716,7 +732,7 @@ The basis matrix's rows are multiplied by ``scale``'s components. This operation Performs a spherical-linear interpolation with the ``to`` basis, given a ``weight``. Both this basis and ``to`` should represent a rotation. -\ **Example:** Smoothly rotate a :ref:`Node3D` to the target basis over time, with a :ref:`Tween`. +\ **Example:** Smoothly rotate a :ref:`Node3D` to the target basis over time, with a :ref:`Tween`: :: @@ -795,9 +811,9 @@ Returns the transposed version of this basis. This turns the basis matrix's colu ) my_basis = my_basis.transposed() - print(my_basis.x) # Prints (1, 4, 7). - print(my_basis.y) # Prints (2, 5, 8). - print(my_basis.z) # Prints (3, 6, 9). + print(my_basis.x) # Prints (1, 4, 7) + print(my_basis.y) # Prints (2, 5, 8) + print(my_basis.z) # Prints (3, 6, 9) .. code-tab:: csharp @@ -808,9 +824,9 @@ Returns the transposed version of this basis. This turns the basis matrix's colu ); myBasis = myBasis.Transposed(); - GD.Print(myBasis.X); // Prints (1, 4, 7). - GD.Print(myBasis.Y); // Prints (2, 5, 8). - GD.Print(myBasis.Z); // Prints (3, 6, 9). + GD.Print(myBasis.X); // Prints (1, 4, 7) + GD.Print(myBasis.Y); // Prints (2, 5, 8) + GD.Print(myBasis.Z); // Prints (3, 6, 9) diff --git a/classes/class_boneattachment3d.rst b/classes/class_boneattachment3d.rst index 5b5475a34a4..94b63075d7e 100644 --- a/classes/class_boneattachment3d.rst +++ b/classes/class_boneattachment3d.rst @@ -48,17 +48,19 @@ Methods .. table:: :widths: auto - +---------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`NodePath` | :ref:`get_external_skeleton`\ (\ ) |const| | - +---------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`bool` | :ref:`get_use_external_skeleton`\ (\ ) |const| | - +---------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`on_skeleton_update`\ (\ ) | - +---------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`set_external_skeleton`\ (\ external_skeleton\: :ref:`NodePath`\ ) | - +---------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ - | |void| | :ref:`set_use_external_skeleton`\ (\ use_external_skeleton\: :ref:`bool`\ ) | - +---------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`NodePath` | :ref:`get_external_skeleton`\ (\ ) |const| | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Skeleton3D` | :ref:`get_skeleton`\ (\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`get_use_external_skeleton`\ (\ ) |const| | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`on_skeleton_update`\ (\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_external_skeleton`\ (\ external_skeleton\: :ref:`NodePath`\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_use_external_skeleton`\ (\ use_external_skeleton\: :ref:`bool`\ ) | + +-------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator @@ -139,6 +141,18 @@ Returns the :ref:`NodePath` to the external :ref:`Skeleton3D` **get_skeleton**\ (\ ) :ref:`๐Ÿ”—` + +Get parent or external :ref:`Skeleton3D` node if found. + +.. rst-class:: classref-item-separator + +---- + .. _class_BoneAttachment3D_method_get_use_external_skeleton: .. rst-class:: classref-method diff --git a/classes/class_button.rst b/classes/class_button.rst index 6d617ac223f..477654634be 100644 --- a/classes/class_button.rst +++ b/classes/class_button.rst @@ -23,7 +23,7 @@ Description **Button** is the standard themed button. It can contain text and an icon, and it will display them according to the current :ref:`Theme`. -\ **Example of creating a button and assigning an action when pressed by code:**\ +\ **Example:** Create a button and connect a method that will be called when the button is pressed: .. tabs:: @@ -33,7 +33,7 @@ Description func _ready(): var button = Button.new() button.text = "Click me" - button.pressed.connect(self._button_pressed) + button.pressed.connect(_button_pressed) add_child(button) func _button_pressed(): @@ -58,7 +58,7 @@ Description See also :ref:`BaseButton` which contains common properties and methods associated with this node. -\ **Note:** Buttons do not interpret touch input and therefore don't support multitouch, since mouse emulation can only press one button at a given time. Use :ref:`TouchScreenButton` for buttons that trigger gameplay movement or actions. +\ **Note:** Buttons do not detect touch input and therefore don't support multitouch, since mouse emulation can only press one button at a given time. Use :ref:`TouchScreenButton` for buttons that trigger gameplay movement or actions. .. rst-class:: classref-introduction-group @@ -144,6 +144,8 @@ Theme Properties +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ | :ref:`int` | :ref:`icon_max_width` | ``0`` | +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ + | :ref:`int` | :ref:`line_spacing` | ``0`` | + +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ | :ref:`int` | :ref:`outline_size` | ``0`` | +-----------------------------------+-----------------------------------------------------------------------------------------+-------------------------------------+ | :ref:`Font` | :ref:`font` | | @@ -587,6 +589,18 @@ The maximum allowed width of the **Button**'s icon. This limit is applied on top ---- +.. _class_Button_theme_constant_line_spacing: + +.. rst-class:: classref-themeproperty + +:ref:`int` **line_spacing** = ``0`` :ref:`๐Ÿ”—` + +Additional vertical spacing between lines (in pixels), spacing is added to line descent. This value can be negative. + +.. rst-class:: classref-item-separator + +---- + .. _class_Button_theme_constant_outline_size: .. rst-class:: classref-themeproperty diff --git a/classes/class_callable.rst b/classes/class_callable.rst index 691f4482ef9..4e6bcfbd1ad 100644 --- a/classes/class_callable.rst +++ b/classes/class_callable.rst @@ -19,8 +19,6 @@ Description **Callable** is a built-in :ref:`Variant` type that represents a function. It can either be a method within an :ref:`Object` instance, or a custom callable used for different purposes (see :ref:`is_custom`). Like all :ref:`Variant` types, it can be stored in variables and passed to other functions. It is most commonly used for signal callbacks. -\ **Example:**\ - .. tabs:: @@ -141,6 +139,8 @@ Methods +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_object_id`\ (\ ) |const| | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_unbound_arguments_count`\ (\ ) |const| | + +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`hash`\ (\ ) |const| | +-------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_custom`\ (\ ) |const| | @@ -337,7 +337,15 @@ Returns the total number of arguments this **Callable** should take, including o :ref:`Array` **get_bound_arguments**\ (\ ) |const| :ref:`๐Ÿ”—` -Return the bound arguments (as long as :ref:`get_bound_arguments_count` is greater than zero), or empty (if :ref:`get_bound_arguments_count` is less than or equal to zero). +Returns the array of arguments bound via successive :ref:`bind` or :ref:`unbind` calls. These arguments will be added *after* the arguments passed to the call, from which :ref:`get_unbound_arguments_count` arguments on the right have been previously excluded. + +:: + + func get_effective_arguments(callable, call_args): + assert(call_args.size() - callable.get_unbound_arguments_count() >= 0) + var result = call_args.slice(0, call_args.size() - callable.get_unbound_arguments_count()) + result.append_array(callable.get_bound_arguments()) + return result .. rst-class:: classref-item-separator @@ -349,7 +357,9 @@ Return the bound arguments (as long as :ref:`get_bound_arguments_count` **get_bound_arguments_count**\ (\ ) |const| :ref:`๐Ÿ”—` -Returns the total amount of arguments bound (or unbound) via successive :ref:`bind` or :ref:`unbind` calls. If the amount of arguments unbound is greater than the ones bound, this function returns a value less than zero. +Returns the total amount of arguments bound via successive :ref:`bind` or :ref:`unbind` calls. This is the same as the size of the array returned by :ref:`get_bound_arguments`. See :ref:`get_bound_arguments` for details. + +\ **Note:** The :ref:`get_bound_arguments_count` and :ref:`get_unbound_arguments_count` methods can both return positive values. .. rst-class:: classref-item-separator @@ -391,6 +401,20 @@ Returns the ID of this **Callable**'s object (see :ref:`Object.get_instance_id` **get_unbound_arguments_count**\ (\ ) |const| :ref:`๐Ÿ”—` + +Returns the total amount of arguments unbound via successive :ref:`bind` or :ref:`unbind` calls. See :ref:`get_bound_arguments` for details. + +\ **Note:** The :ref:`get_bound_arguments_count` and :ref:`get_unbound_arguments_count` methods can both return positive values. + +.. rst-class:: classref-item-separator + +---- + .. _class_Callable_method_hash: .. rst-class:: classref-method @@ -431,7 +455,9 @@ Returns ``true`` if this **Callable** is a custom callable. Custom callables are :ref:`bool` **is_null**\ (\ ) |const| :ref:`๐Ÿ”—` -Returns ``true`` if this **Callable** has no target to call the method on. +Returns ``true`` if this **Callable** has no target to call the method on. Equivalent to ``callable == Callable()``. + +\ **Note:** This is *not* the same as ``not is_valid()`` and using ``not is_null()`` will *not* guarantee that this callable can be called. Use :ref:`is_valid` instead. .. rst-class:: classref-item-separator diff --git a/classes/class_callbacktweener.rst b/classes/class_callbacktweener.rst index b78d9c67348..b65c79a4565 100644 --- a/classes/class_callbacktweener.rst +++ b/classes/class_callbacktweener.rst @@ -54,12 +54,12 @@ Method Descriptions Makes the callback call delayed by given time in seconds. -\ **Example:**\ +\ **Example:** Call :ref:`Node.queue_free` after 2 seconds: :: var tween = get_tree().create_tween() - tween.tween_callback(queue_free).set_delay(2) #this will call queue_free() after 2 seconds + tween.tween_callback(queue_free).set_delay(2) .. |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.)` diff --git a/classes/class_cameraattributes.rst b/classes/class_cameraattributes.rst index 2bbe852e8b0..386753ab34e 100644 --- a/classes/class_cameraattributes.rst +++ b/classes/class_cameraattributes.rst @@ -137,7 +137,11 @@ Multiplier for the exposure amount. A higher value results in a brighter image. - |void| **set_exposure_sensitivity**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_exposure_sensitivity**\ (\ ) -Sensitivity of camera sensors, measured in ISO. A higher sensitivity results in a brighter image. Only available when :ref:`ProjectSettings.rendering/lights_and_shadows/use_physical_light_units` is enabled. When :ref:`auto_exposure_enabled` this can be used as a method of exposure compensation, doubling the value will increase the exposure value (measured in EV100) by 1 stop. +Sensitivity of camera sensors, measured in ISO. A higher sensitivity results in a brighter image. + +If :ref:`auto_exposure_enabled` is ``true``, this can be used as a method of exposure compensation, doubling the value will increase the exposure value (measured in EV100) by 1 stop. + +\ **Note:** Only available when :ref:`ProjectSettings.rendering/lights_and_shadows/use_physical_light_units` is enabled. .. |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.)` diff --git a/classes/class_cameraattributesphysical.rst b/classes/class_cameraattributesphysical.rst index 1399d5f135c..89be06443f1 100644 --- a/classes/class_cameraattributesphysical.rst +++ b/classes/class_cameraattributesphysical.rst @@ -109,7 +109,7 @@ The maximum luminance (in EV100) used when calculating auto exposure. When calcu - |void| **set_auto_exposure_min_exposure_value**\ (\ value\: :ref:`float`\ ) - :ref:`float` **get_auto_exposure_min_exposure_value**\ (\ ) -The minimum luminance luminance (in EV100) used when calculating auto exposure. When calculating scene average luminance, color values will be clamped to at least this value. This limits the auto-exposure from exposing above a certain brightness, resulting in a cut off point where the scene will remain dark. +The minimum luminance (in EV100) used when calculating auto exposure. When calculating scene average luminance, color values will be clamped to at least this value. This limits the auto-exposure from exposing above a certain brightness, resulting in a cut off point where the scene will remain dark. .. rst-class:: classref-item-separator diff --git a/classes/class_camerafeed.rst b/classes/class_camerafeed.rst index 5774048fbc9..c3bb9c13ffe 100644 --- a/classes/class_camerafeed.rst +++ b/classes/class_camerafeed.rst @@ -36,6 +36,8 @@ Properties +---------------------------------------+-----------------------------------------------------------------+------------------------------------+ | :ref:`Transform2D` | :ref:`feed_transform` | ``Transform2D(1, 0, 0, -1, 0, 1)`` | +---------------------------------------+-----------------------------------------------------------------+------------------------------------+ + | :ref:`Array` | :ref:`formats` | ``[]`` | + +---------------------------------------+-----------------------------------------------------------------+------------------------------------+ .. rst-class:: classref-reftable-group @@ -45,15 +47,58 @@ Methods .. table:: :widths: auto - +---------------------------------------------------+-------------------------------------------------------------------------+ - | :ref:`FeedDataType` | :ref:`get_datatype`\ (\ ) |const| | - +---------------------------------------------------+-------------------------------------------------------------------------+ - | :ref:`int` | :ref:`get_id`\ (\ ) |const| | - +---------------------------------------------------+-------------------------------------------------------------------------+ - | :ref:`String` | :ref:`get_name`\ (\ ) |const| | - +---------------------------------------------------+-------------------------------------------------------------------------+ - | :ref:`FeedPosition` | :ref:`get_position`\ (\ ) |const| | - +---------------------------------------------------+-------------------------------------------------------------------------+ + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`FeedDataType` | :ref:`get_datatype`\ (\ ) |const| | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_id`\ (\ ) |const| | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`String` | :ref:`get_name`\ (\ ) |const| | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`FeedPosition` | :ref:`get_position`\ (\ ) |const| | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`int` | :ref:`get_texture_tex_id`\ (\ feed_image_type\: :ref:`FeedImage`\ ) | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_external`\ (\ width\: :ref:`int`, height\: :ref:`int`\ ) | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`bool` | :ref:`set_format`\ (\ index\: :ref:`int`, parameters\: :ref:`Dictionary`\ ) | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_name`\ (\ name\: :ref:`String`\ ) | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_position`\ (\ position\: :ref:`FeedPosition`\ ) | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_rgb_image`\ (\ rgb_image\: :ref:`Image`\ ) | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+ + | |void| | :ref:`set_ycbcr_image`\ (\ ycbcr_image\: :ref:`Image`\ ) | + +---------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------------------+ + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + +Signals +------- + +.. _class_CameraFeed_signal_format_changed: + +.. rst-class:: classref-signal + +**format_changed**\ (\ ) :ref:`๐Ÿ”—` + +Emitted when the format has changed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_signal_frame_changed: + +.. rst-class:: classref-signal + +**frame_changed**\ (\ ) :ref:`๐Ÿ”—` + +Emitted when a new frame is available. .. rst-class:: classref-section-separator @@ -102,6 +147,14 @@ Feed supplies YCbCr images that need to be converted to RGB. Feed supplies separate Y and CbCr images that need to be combined and converted to RGB. +.. _class_CameraFeed_constant_FEED_EXTERNAL: + +.. rst-class:: classref-enumeration-constant + +:ref:`FeedDataType` **FEED_EXTERNAL** = ``4`` + +Feed supplies external image. + .. rst-class:: classref-item-separator ---- @@ -175,6 +228,22 @@ If ``true``, the feed is active. The transform applied to the camera's image. +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_property_formats: + +.. rst-class:: classref-property + +:ref:`Array` **formats** = ``[]`` :ref:`๐Ÿ”—` + +.. rst-class:: classref-property-setget + +- :ref:`Array` **get_formats**\ (\ ) + +Formats supported by the feed. Each entry is a :ref:`Dictionary` describing format parameters. + .. rst-class:: classref-section-separator ---- @@ -228,6 +297,96 @@ Returns the camera's name. Returns the position of camera on the device. +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_method_get_texture_tex_id: + +.. rst-class:: classref-method + +:ref:`int` **get_texture_tex_id**\ (\ feed_image_type\: :ref:`FeedImage`\ ) :ref:`๐Ÿ”—` + +Returns the texture backend ID (usable by some external libraries that need a handle to a texture to write data). + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_method_set_external: + +.. rst-class:: classref-method + +|void| **set_external**\ (\ width\: :ref:`int`, height\: :ref:`int`\ ) :ref:`๐Ÿ”—` + +Sets the feed as external feed provided by another library. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_method_set_format: + +.. rst-class:: classref-method + +:ref:`bool` **set_format**\ (\ index\: :ref:`int`, parameters\: :ref:`Dictionary`\ ) :ref:`๐Ÿ”—` + +Sets the feed format parameters for the given index in the :ref:`formats` array. Returns ``true`` on success. By default YUYV encoded stream is transformed to FEED_RGB. YUYV encoded stream output format can be changed with ``parameters``.output value: + +\ ``separate`` will result in FEED_YCBCR_SEP + +\ ``grayscale`` will result in desaturated FEED_RGB + +\ ``copy`` will result in FEED_YCBCR + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_method_set_name: + +.. rst-class:: classref-method + +|void| **set_name**\ (\ name\: :ref:`String`\ ) :ref:`๐Ÿ”—` + +Sets the camera's name. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_method_set_position: + +.. rst-class:: classref-method + +|void| **set_position**\ (\ position\: :ref:`FeedPosition`\ ) :ref:`๐Ÿ”—` + +Sets the position of this camera. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_method_set_rgb_image: + +.. rst-class:: classref-method + +|void| **set_rgb_image**\ (\ rgb_image\: :ref:`Image`\ ) :ref:`๐Ÿ”—` + +Sets RGB image for this feed. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CameraFeed_method_set_ycbcr_image: + +.. rst-class:: classref-method + +|void| **set_ycbcr_image**\ (\ ycbcr_image\: :ref:`Image`\ ) :ref:`๐Ÿ”—` + +Sets YCbCr image for this feed. + .. |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.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` diff --git a/classes/class_cameraserver.rst b/classes/class_cameraserver.rst index 9d3800bbf74..e662f71daac 100644 --- a/classes/class_cameraserver.rst +++ b/classes/class_cameraserver.rst @@ -23,7 +23,7 @@ The **CameraServer** keeps track of different cameras accessible in Godot. These It is notably used to provide AR modules with a video feed from the camera. -\ **Note:** This class is currently only implemented on macOS and iOS. To get a :ref:`CameraFeed` on iOS, the camera plugin from `godot-ios-plugins `__ is required. On other platforms, no :ref:`CameraFeed`\ s will be available. +\ **Note:** This class is currently only implemented on Linux, macOS, and iOS, on other platforms no :ref:`CameraFeed`\ s will be available. To get a :ref:`CameraFeed` on iOS, the camera plugin from `godot-ios-plugins `__ is required. .. rst-class:: classref-reftable-group diff --git a/classes/class_canvasitem.rst b/classes/class_canvasitem.rst index d5412e78e24..64e59fcab6b 100644 --- a/classes/class_canvasitem.rst +++ b/classes/class_canvasitem.rst @@ -191,7 +191,7 @@ Methods +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`is_visible_in_tree`\ (\ ) |const| | +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ - | :ref:`Vector2` | :ref:`make_canvas_position_local`\ (\ screen_point\: :ref:`Vector2`\ ) |const| | + | :ref:`Vector2` | :ref:`make_canvas_position_local`\ (\ viewport_point\: :ref:`Vector2`\ ) |const| | +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`InputEvent` | :ref:`make_input_local`\ (\ event\: :ref:`InputEvent`\ ) |const| | +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -237,7 +237,7 @@ Emitted when the **CanvasItem** must redraw, *after* the related :ref:`NOTIFICAT **hidden**\ (\ ) :ref:`๐Ÿ”—` -Emitted when becoming hidden. +Emitted when the **CanvasItem** is hidden, i.e. it's no longer visible in the tree (see :ref:`is_visible_in_tree`). .. rst-class:: classref-item-separator @@ -249,7 +249,7 @@ Emitted when becoming hidden. **item_rect_changed**\ (\ ) :ref:`๐Ÿ”—` -Emitted when the item's :ref:`Rect2` boundaries (position or size) have changed, or when an action is taking place that may have impacted these boundaries (e.g. changing :ref:`Sprite2D.texture`). +Emitted when the **CanvasItem**'s boundaries (position or size) change, or when an action took place that may have affected these boundaries (e.g. changing :ref:`Sprite2D.texture`). .. rst-class:: classref-item-separator @@ -261,7 +261,7 @@ Emitted when the item's :ref:`Rect2` boundaries (position or size) **visibility_changed**\ (\ ) :ref:`๐Ÿ”—` -Emitted when the visibility (hidden/visible) changes. +Emitted when the **CanvasItem**'s visibility changes, either because its own :ref:`visible` property changed or because its visibility in the tree changed (see :ref:`is_visible_in_tree`). .. rst-class:: classref-section-separator @@ -529,6 +529,8 @@ Property Descriptions Allows the current node to clip child nodes, essentially acting as a mask. +\ **Note:** Clipping nodes cannot be nested or placed within :ref:`CanvasGroup`\ s. If an ancestor of this node clips its children or is a :ref:`CanvasGroup`, then this node's clip mode should be set to :ref:`CLIP_CHILDREN_DISABLED` to avoid unexpected behavior. + .. rst-class:: classref-item-separator ---- @@ -716,7 +718,7 @@ The rendering layer in which this **CanvasItem** is rendered by :ref:`Viewport`\ ) - :ref:`bool` **is_visible**\ (\ ) -If ``true``, this **CanvasItem** is drawn. The node is only visible if all of its ancestors are visible as well (in other words, :ref:`is_visible_in_tree` must return ``true``). +If ``true``, this **CanvasItem** may be drawn. Whether this **CanvasItem** is actually drawn depends on the visibility of all of its **CanvasItem** ancestors. In other words: this **CanvasItem** will be drawn when :ref:`is_visible_in_tree` returns ``true`` and all **CanvasItem** ancestors share at least one :ref:`visibility_layer` with this **CanvasItem**. \ **Note:** For controls that inherit :ref:`Popup`, the correct way to make them visible is to call one of the multiple ``popup*()`` functions instead. @@ -737,7 +739,7 @@ If ``true``, this **CanvasItem** is drawn. The node is only visible if all of it If ``true``, this and child **CanvasItem** nodes with a higher Y position are rendered in front of nodes with a lower Y position. If ``false``, this and child **CanvasItem** nodes are rendered normally in scene tree order. -With Y-sorting enabled on a parent node ('A') but disabled on a child node ('B'), the child node ('B') is sorted but its children ('C1', 'C2', etc) render together on the same Y position as the child node ('B'). This allows you to organize the render order of a scene without changing the scene tree. +With Y-sorting enabled on a parent node ('A') but disabled on a child node ('B'), the child node ('B') is sorted but its children ('C1', 'C2', etc.) render together on the same Y position as the child node ('B'). This allows you to organize the render order of a scene without changing the scene tree. Nodes sort relative to each other only if they are on the same :ref:`z_index`. @@ -880,6 +882,8 @@ If ``antialiased`` is ``true``, half transparent "feathers" will be attached to Draws a colored polygon of any number of points, convex or concave. Unlike :ref:`draw_polygon`, a single color must be specified for the whole polygon. +\ **Note:** If you frequently redraw the same polygon with a large number of vertices, consider pre-calculating the triangulation with :ref:`Geometry2D.triangulate_polygon` and using :ref:`draw_mesh`, :ref:`draw_multimesh`, or :ref:`RenderingServer.canvas_item_add_triangle_array`. + .. rst-class:: classref-item-separator ---- @@ -1053,6 +1057,8 @@ Draws a :ref:`MultiMesh` in 2D with the provided texture. See : Draws a solid polygon of any number of points, convex or concave. Unlike :ref:`draw_colored_polygon`, each point's color can be changed individually. See also :ref:`draw_polyline` and :ref:`draw_polyline_colors`. If you need more flexibility (such as being able to use bones), use :ref:`RenderingServer.canvas_item_add_triangle_array` instead. +\ **Note:** If you frequently redraw the same polygon with a large number of vertices, consider pre-calculating the triangulation with :ref:`Geometry2D.triangulate_polygon` and using :ref:`draw_mesh`, :ref:`draw_multimesh`, or :ref:`RenderingServer.canvas_item_add_triangle_array`. + .. rst-class:: classref-item-separator ---- @@ -1151,7 +1157,7 @@ Sets a custom transform for drawing via matrix. Anything drawn afterwards will b Draws ``text`` using the specified ``font`` at the ``pos`` (bottom-left corner using the baseline of the font). The text will have its color multiplied by ``modulate``. If ``width`` is greater than or equal to 0, the text will be clipped if it exceeds the specified width. -\ **Example using the default project font:**\ +\ **Example:** Draw "Hello world", using the project's default font: .. tabs:: @@ -1472,6 +1478,8 @@ Returns ``true`` if the node is present in the :ref:`SceneTree` Visibility is checked only in parent nodes that inherit from **CanvasItem**, :ref:`CanvasLayer`, and :ref:`Window`. If the parent is of any other type (such as :ref:`Node`, :ref:`AnimationPlayer`, or :ref:`Node3D`), it is assumed to be visible. +\ **Note:** This method does not take :ref:`visibility_layer` into account, so even if this method returns ``true`` the node might end up not being rendered. + .. rst-class:: classref-item-separator ---- @@ -1480,9 +1488,15 @@ Visibility is checked only in parent nodes that inherit from **CanvasItem**, :re .. rst-class:: classref-method -:ref:`Vector2` **make_canvas_position_local**\ (\ screen_point\: :ref:`Vector2`\ ) |const| :ref:`๐Ÿ”—` +:ref:`Vector2` **make_canvas_position_local**\ (\ viewport_point\: :ref:`Vector2`\ ) |const| :ref:`๐Ÿ”—` + +Transforms ``viewport_point`` from the viewport's coordinates to this node's local coordinates. + +For the opposite operation, use :ref:`get_global_transform_with_canvas`. + +:: -Assigns ``screen_point`` as this node's new local transform. + var viewport_point = get_global_transform_with_canvas() * local_point .. rst-class:: classref-item-separator diff --git a/classes/class_canvaslayer.rst b/classes/class_canvaslayer.rst index ac3e8ce8717..5b40f4504a8 100644 --- a/classes/class_canvaslayer.rst +++ b/classes/class_canvaslayer.rst @@ -140,9 +140,9 @@ The custom :ref:`Viewport` node assigned to the **CanvasLayer**. - |void| **set_follow_viewport**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_following_viewport**\ (\ ) -If enabled, the **CanvasLayer** will use the viewport's transform, so it will move when camera moves instead of being anchored in a fixed position on the screen. +If enabled, the **CanvasLayer** stays in a fixed position on the screen. If disabled, the **CanvasLayer** maintains its position in world space. -Together with :ref:`follow_viewport_scale` it can be used for a pseudo 3D effect. +Together with :ref:`follow_viewport_scale`, this can be used for a pseudo-3D effect. .. rst-class:: classref-item-separator diff --git a/classes/class_canvasmodulate.rst b/classes/class_canvasmodulate.rst index a90a5687fcf..42a739cb129 100644 --- a/classes/class_canvasmodulate.rst +++ b/classes/class_canvasmodulate.rst @@ -24,6 +24,13 @@ Description **CanvasModulate** applies a color tint to all nodes on a canvas. Only one can be used to tint a canvas, but :ref:`CanvasLayer`\ s can be used to render things independently. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`2D lights and shadows <../tutorials/2d/2d_lights_and_shadows>` + .. rst-class:: classref-reftable-group Properties diff --git a/classes/class_characterbody2d.rst b/classes/class_characterbody2d.rst index ea56c53059b..078c9009f22 100644 --- a/classes/class_characterbody2d.rst +++ b/classes/class_characterbody2d.rst @@ -574,7 +574,7 @@ Returns the current real velocity since the last call to :ref:`move_and_slide`, which contains information about a collision that occurred during the last call to :ref:`move_and_slide`. Since the body can collide several times in a single call to :ref:`move_and_slide`, you must specify the index of the collision in the range 0 to (:ref:`get_slide_collision_count` - 1). -\ **Example usage:**\ +\ **Example:** Iterate through the collisions with a ``for`` loop: .. tabs:: diff --git a/classes/class_charfxtransform.rst b/classes/class_charfxtransform.rst index 25c6eebf6fd..fc3d18859e5 100644 --- a/classes/class_charfxtransform.rst +++ b/classes/class_charfxtransform.rst @@ -28,8 +28,6 @@ Tutorials - :doc:`BBCode in RichTextLabel <../tutorials/ui/bbcode_in_richtextlabel>` -- `RichTextEffect test project (third-party) `__ - .. rst-class:: classref-reftable-group Properties diff --git a/classes/class_classdb.rst b/classes/class_classdb.rst index 9c5b481cd22..14724e0be5c 100644 --- a/classes/class_classdb.rst +++ b/classes/class_classdb.rst @@ -32,8 +32,12 @@ Methods +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`can_instantiate`\ (\ class\: :ref:`StringName`\ ) |const| | +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`Variant` | :ref:`class_call_static`\ (\ class\: :ref:`StringName`, method\: :ref:`StringName`, ...\ ) |vararg| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`bool` | :ref:`class_exists`\ (\ class\: :ref:`StringName`\ ) |const| | +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`APIType` | :ref:`class_get_api_type`\ (\ class\: :ref:`StringName`\ ) |const| | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PackedStringArray` | :ref:`class_get_enum_constants`\ (\ class\: :ref:`StringName`, enum\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`PackedStringArray` | :ref:`class_get_enum_list`\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | @@ -52,8 +56,12 @@ Methods +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`class_get_property_default_value`\ (\ class\: :ref:`StringName`, property\: :ref:`StringName`\ ) |const| | +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`class_get_property_getter`\ (\ class\: :ref:`StringName`, property\: :ref:`StringName`\ ) | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Array`\[:ref:`Dictionary`\] | :ref:`class_get_property_list`\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + | :ref:`StringName` | :ref:`class_get_property_setter`\ (\ class\: :ref:`StringName`, property\: :ref:`StringName`\ ) | + +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Dictionary` | :ref:`class_get_signal`\ (\ class\: :ref:`StringName`, signal\: :ref:`StringName`\ ) |const| | +------------------------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Array`\[:ref:`Dictionary`\] | :ref:`class_get_signal_list`\ (\ class\: :ref:`StringName`, no_inheritance\: :ref:`bool` = false\ ) |const| | @@ -89,6 +97,61 @@ Methods .. rst-class:: classref-descriptions-group +Enumerations +------------ + +.. _enum_ClassDB_APIType: + +.. rst-class:: classref-enumeration + +enum **APIType**: :ref:`๐Ÿ”—` + +.. _class_ClassDB_constant_API_CORE: + +.. rst-class:: classref-enumeration-constant + +:ref:`APIType` **API_CORE** = ``0`` + +Native Core class type. + +.. _class_ClassDB_constant_API_EDITOR: + +.. rst-class:: classref-enumeration-constant + +:ref:`APIType` **API_EDITOR** = ``1`` + +Native Editor class type. + +.. _class_ClassDB_constant_API_EXTENSION: + +.. rst-class:: classref-enumeration-constant + +:ref:`APIType` **API_EXTENSION** = ``2`` + +GDExtension class type. + +.. _class_ClassDB_constant_API_EDITOR_EXTENSION: + +.. rst-class:: classref-enumeration-constant + +:ref:`APIType` **API_EDITOR_EXTENSION** = ``3`` + +GDExtension Editor class type. + +.. _class_ClassDB_constant_API_NONE: + +.. rst-class:: classref-enumeration-constant + +:ref:`APIType` **API_NONE** = ``4`` + +Unknown class type. + +.. rst-class:: classref-section-separator + +---- + +.. rst-class:: classref-descriptions-group + Method Descriptions ------------------- @@ -104,6 +167,18 @@ Returns ``true`` if objects can be instantiated from the specified ``class``, ot ---- +.. _class_ClassDB_method_class_call_static: + +.. rst-class:: classref-method + +:ref:`Variant` **class_call_static**\ (\ class\: :ref:`StringName`, method\: :ref:`StringName`, ...\ ) |vararg| :ref:`๐Ÿ”—` + +Calls a static method on a class. + +.. rst-class:: classref-item-separator + +---- + .. _class_ClassDB_method_class_exists: .. rst-class:: classref-method @@ -116,6 +191,18 @@ Returns whether the specified ``class`` is available or not. ---- +.. _class_ClassDB_method_class_get_api_type: + +.. rst-class:: classref-method + +:ref:`APIType` **class_get_api_type**\ (\ class\: :ref:`StringName`\ ) |const| :ref:`๐Ÿ”—` + +Returns the API type of ``class``. See :ref:`APIType`. + +.. rst-class:: classref-item-separator + +---- + .. _class_ClassDB_method_class_get_enum_constants: .. rst-class:: classref-method @@ -226,6 +313,18 @@ Returns the default value of ``property`` of ``class`` or its ancestor classes. ---- +.. _class_ClassDB_method_class_get_property_getter: + +.. rst-class:: classref-method + +:ref:`StringName` **class_get_property_getter**\ (\ class\: :ref:`StringName`, property\: :ref:`StringName`\ ) :ref:`๐Ÿ”—` + +Returns the getter method name of ``property`` of ``class``. + +.. rst-class:: classref-item-separator + +---- + .. _class_ClassDB_method_class_get_property_list: .. rst-class:: classref-method @@ -238,6 +337,18 @@ Returns an array with all the properties of ``class`` or its ancestry if ``no_in ---- +.. _class_ClassDB_method_class_get_property_setter: + +.. rst-class:: classref-method + +:ref:`StringName` **class_get_property_setter**\ (\ class\: :ref:`StringName`, property\: :ref:`StringName`\ ) :ref:`๐Ÿ”—` + +Returns the setter method name of ``property`` of ``class``. + +.. rst-class:: classref-item-separator + +---- + .. _class_ClassDB_method_class_get_signal: .. rst-class:: classref-method diff --git a/classes/class_codeedit.rst b/classes/class_codeedit.rst index 5cfb6a2dc7a..f748b6be313 100644 --- a/classes/class_codeedit.rst +++ b/classes/class_codeedit.rst @@ -280,6 +280,8 @@ Theme Properties +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ | :ref:`Texture2D` | :ref:`can_fold_code_region` | | +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ + | :ref:`Texture2D` | :ref:`completion_color_bg` | | + +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ | :ref:`Texture2D` | :ref:`executing_line` | | +-----------------------------------+----------------------------------------------------------------------------------------------------+-----------------------------------+ | :ref:`Texture2D` | :ref:`folded` | | @@ -318,7 +320,7 @@ Emitted when a breakpoint is added or removed from a line. If the line is moved **code_completion_requested**\ (\ ) :ref:`๐Ÿ”—` -Emitted when the user requests code completion. +Emitted when the user requests code completion. This signal will not be sent if :ref:`_request_code_completion` is overridden or :ref:`code_completion_enabled` is ``false``. .. rst-class:: classref-item-separator @@ -501,7 +503,7 @@ Property Descriptions - |void| **set_auto_brace_completion_enabled**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_auto_brace_completion_enabled**\ (\ ) -Sets whether brace pairs should be autocompleted. +If ``true``, uses :ref:`auto_brace_completion_pairs` to automatically insert the closing brace when the opening brace is inserted by typing or autocompletion. Also automatically removes the closing brace when using backspace on the opening brace. .. rst-class:: classref-item-separator @@ -518,7 +520,7 @@ Sets whether brace pairs should be autocompleted. - |void| **set_highlight_matching_braces_enabled**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_highlight_matching_braces_enabled**\ (\ ) -Highlight mismatching brace pairs. +If ``true``, highlights brace pairs when the caret is on either one, using :ref:`auto_brace_completion_pairs`. If matching, the pairs will be underlined. If a brace is unmatched, it is colored with :ref:`brace_mismatch_color`. .. rst-class:: classref-item-separator @@ -535,7 +537,7 @@ Highlight mismatching brace pairs. - |void| **set_auto_brace_completion_pairs**\ (\ value\: :ref:`Dictionary`\ ) - :ref:`Dictionary` **get_auto_brace_completion_pairs**\ (\ ) -Sets the brace pairs to be autocompleted. +Sets the brace pairs to be autocompleted. For each entry in the dictionary, the key is the opening brace and the value is the closing brace that matches it. A brace is a :ref:`String` made of symbols. See :ref:`auto_brace_completion_enabled` and :ref:`auto_brace_completion_highlight_matching`. .. rst-class:: classref-item-separator @@ -552,7 +554,7 @@ Sets the brace pairs to be autocompleted. - |void| **set_code_completion_enabled**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_code_completion_enabled**\ (\ ) -Sets whether code completion is allowed. +If ``true``, the :ref:`ProjectSettings.input/ui_text_completion_query` action requests code completion. To handle it, see :ref:`_request_code_completion` or :ref:`code_completion_requested`. .. rst-class:: classref-item-separator @@ -620,7 +622,7 @@ Sets the string delimiters. All existing string delimiters will be removed. - |void| **set_draw_bookmarks_gutter**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_drawing_bookmarks_gutter**\ (\ ) -Sets if bookmarked should be drawn in the gutter. This gutter is shared with breakpoints and executing lines. +If ``true``, bookmarks are drawn in the gutter. This gutter is shared with breakpoints and executing lines. See :ref:`set_line_as_bookmarked`. .. rst-class:: classref-item-separator @@ -637,7 +639,7 @@ Sets if bookmarked should be drawn in the gutter. This gutter is shared with bre - |void| **set_draw_breakpoints_gutter**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_drawing_breakpoints_gutter**\ (\ ) -Sets if breakpoints should be drawn in the gutter. This gutter is shared with bookmarks and executing lines. +If ``true``, breakpoints are drawn in the gutter. This gutter is shared with bookmarks and executing lines. Clicking the gutter will toggle the breakpoint for the line, see :ref:`set_line_as_breakpoint`. .. rst-class:: classref-item-separator @@ -654,7 +656,7 @@ Sets if breakpoints should be drawn in the gutter. This gutter is shared with bo - |void| **set_draw_executing_lines_gutter**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_drawing_executing_lines_gutter**\ (\ ) -Sets if executing lines should be marked in the gutter. This gutter is shared with breakpoints and bookmarks lines. +If ``true``, executing lines are marked in the gutter. This gutter is shared with breakpoints and bookmarks. See :ref:`set_line_as_executing`. .. rst-class:: classref-item-separator @@ -671,7 +673,7 @@ Sets if executing lines should be marked in the gutter. This gutter is shared wi - |void| **set_draw_fold_gutter**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_drawing_fold_gutter**\ (\ ) -Sets if foldable lines icons should be drawn in the gutter. +If ``true``, the fold gutter is drawn. In this gutter, the :ref:`can_fold_code_region` icon is drawn for each foldable line (see :ref:`can_fold_line`) and the :ref:`folded_code_region` icon is drawn for each folded line (see :ref:`is_line_folded`). These icons can be clicked to toggle the fold state, see :ref:`toggle_foldable_line`. :ref:`line_folding` must be ``true`` to show icons. .. rst-class:: classref-item-separator @@ -688,7 +690,7 @@ Sets if foldable lines icons should be drawn in the gutter. - |void| **set_draw_line_numbers**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_draw_line_numbers_enabled**\ (\ ) -Sets if line numbers should be drawn in the gutter. +If ``true``, the line number gutter is drawn. Line numbers start at ``1`` and are incremented for each line of text. Clicking and dragging in the line number gutter will select entire lines of text. .. rst-class:: classref-item-separator @@ -705,7 +707,7 @@ Sets if line numbers should be drawn in the gutter. - |void| **set_line_numbers_zero_padded**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_line_numbers_zero_padded**\ (\ ) -Sets if line numbers drawn in the gutter are zero padded. +If ``true``, line numbers drawn in the gutter are zero padded based on the total line count. Requires :ref:`gutters_draw_line_numbers` to be set to ``true``. .. rst-class:: classref-item-separator @@ -722,7 +724,7 @@ Sets if line numbers drawn in the gutter are zero padded. - |void| **set_auto_indent_enabled**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_auto_indent_enabled**\ (\ ) -Sets whether automatic indent are enabled, this will add an extra indent if a prefix or brace is found. +If ``true``, an extra indent is automatically inserted when a new line is added and a prefix in :ref:`indent_automatic_prefixes` is found. If a brace pair opening key is found, the matching closing brace will be moved to another new line (see :ref:`auto_brace_completion_pairs`). .. rst-class:: classref-item-separator @@ -739,7 +741,7 @@ Sets whether automatic indent are enabled, this will add an extra indent if a pr - |void| **set_auto_indent_prefixes**\ (\ value\: :ref:`Array`\[:ref:`String`\]\ ) - :ref:`Array`\[:ref:`String`\] **get_auto_indent_prefixes**\ (\ ) -Prefixes to trigger an automatic indent. +Prefixes to trigger an automatic indent. Used when :ref:`indent_automatic` is set to ``true``. .. rst-class:: classref-item-separator @@ -790,7 +792,7 @@ Use spaces instead of tabs for indentation. - |void| **set_line_folding_enabled**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_line_folding_enabled**\ (\ ) -Sets whether line folding is allowed. +If ``true``, lines can be folded. Otherwise, line folding methods like :ref:`fold_line` will not work and :ref:`can_fold_line` will always return ``false``. See :ref:`gutters_draw_fold_gutter`. .. rst-class:: classref-item-separator @@ -937,7 +939,7 @@ If ``line_only`` is ``true`` or ``end_key`` is an empty :ref:`String` **can_fold_line**\ (\ line\: :ref:`int`\ ) |const| :ref:`๐Ÿ”—` -Returns if the given line is foldable, that is, it has indented lines right below it or a comment / string block. +Returns ``true`` if the given line is foldable. A line is foldable if it is the start of a valid code region (see :ref:`get_code_region_start_tag`), if it is the start of a comment or string block, or if the next non-empty line is more indented (see :ref:`TextEdit.get_indent_level`). .. rst-class:: classref-item-separator @@ -1077,7 +1079,7 @@ Deletes all lines that are selected or have a caret on them. |void| **do_indent**\ (\ ) :ref:`๐Ÿ”—` -Perform an indent as if the user activated the "ui_text_indent" action. +If there is no selection, indentation is inserted at the caret. Otherwise, the selected lines are indented like :ref:`indent_lines`. Equivalent to the :ref:`ProjectSettings.input/ui_text_indent` action. The indentation characters used depend on :ref:`indent_use_spaces` and :ref:`indent_size`. .. rst-class:: classref-item-separator @@ -1305,7 +1307,7 @@ Gets all executing lines. :ref:`Array`\[:ref:`int`\] **get_folded_lines**\ (\ ) |const| :ref:`๐Ÿ”—` -Returns all lines that are current folded. +Returns all lines that are currently folded. .. rst-class:: classref-item-separator @@ -1401,7 +1403,7 @@ Returns ``true`` if string ``start_key`` exists. |void| **indent_lines**\ (\ ) :ref:`๐Ÿ”—` -Indents selected lines, or in the case of no selection the caret line by one. +Indents all lines that are selected or have a caret on them. Uses spaces or a tab depending on :ref:`indent_use_spaces`. See :ref:`unindent_lines`. .. rst-class:: classref-item-separator @@ -1437,7 +1439,7 @@ Returns the delimiter index if ``line`` ``column`` is in a string. If ``column`` :ref:`bool` **is_line_bookmarked**\ (\ line\: :ref:`int`\ ) |const| :ref:`๐Ÿ”—` -Returns whether the line at the specified index is bookmarked or not. +Returns ``true`` if the given line is bookmarked. See :ref:`set_line_as_bookmarked`. .. rst-class:: classref-item-separator @@ -1449,7 +1451,7 @@ Returns whether the line at the specified index is bookmarked or not. :ref:`bool` **is_line_breakpointed**\ (\ line\: :ref:`int`\ ) |const| :ref:`๐Ÿ”—` -Returns whether the line at the specified index is breakpointed or not. +Returns ``true`` if the given line is breakpointed. See :ref:`set_line_as_breakpoint`. .. rst-class:: classref-item-separator @@ -1461,7 +1463,7 @@ Returns whether the line at the specified index is breakpointed or not. :ref:`bool` **is_line_code_region_end**\ (\ line\: :ref:`int`\ ) |const| :ref:`๐Ÿ”—` -Returns whether the line at the specified index is a code region end. +Returns ``true`` if the given line is a code region end. See :ref:`set_code_region_tags`. .. rst-class:: classref-item-separator @@ -1473,7 +1475,7 @@ Returns whether the line at the specified index is a code region end. :ref:`bool` **is_line_code_region_start**\ (\ line\: :ref:`int`\ ) |const| :ref:`๐Ÿ”—` -Returns whether the line at the specified index is a code region start. +Returns ``true`` if the given line is a code region start. See :ref:`set_code_region_tags`. .. rst-class:: classref-item-separator @@ -1485,7 +1487,7 @@ Returns whether the line at the specified index is a code region start. :ref:`bool` **is_line_executing**\ (\ line\: :ref:`int`\ ) |const| :ref:`๐Ÿ”—` -Returns whether the line at the specified index is marked as executing or not. +Returns ``true`` if the given line is marked as executing. See :ref:`set_line_as_executing`. .. rst-class:: classref-item-separator @@ -1497,7 +1499,7 @@ Returns whether the line at the specified index is marked as executing or not. :ref:`bool` **is_line_folded**\ (\ line\: :ref:`int`\ ) |const| :ref:`๐Ÿ”—` -Returns whether the line at the specified index is folded or not. +Returns ``true`` if the given line is folded. See :ref:`fold_line`. .. rst-class:: classref-item-separator @@ -1593,7 +1595,7 @@ Sets the code hint text. Pass an empty string to clear. |void| **set_code_hint_draw_below**\ (\ draw_below\: :ref:`bool`\ ) :ref:`๐Ÿ”—` -Sets if the code hint should draw below the text. +If ``true``, the code hint will draw below the main caret. If ``false``, the code hint will draw above the main caret. See :ref:`set_code_hint`. .. rst-class:: classref-item-separator @@ -1617,7 +1619,7 @@ Sets the code region start and end tags (without comment delimiter). |void| **set_line_as_bookmarked**\ (\ line\: :ref:`int`, bookmarked\: :ref:`bool`\ ) :ref:`๐Ÿ”—` -Sets the line as bookmarked. +Sets the given line as bookmarked. If ``true`` and :ref:`gutters_draw_bookmarks` is ``true``, draws the :ref:`bookmark` icon in the gutter for this line. See :ref:`get_bookmarked_lines` and :ref:`is_line_bookmarked`. .. rst-class:: classref-item-separator @@ -1629,7 +1631,7 @@ Sets the line as bookmarked. |void| **set_line_as_breakpoint**\ (\ line\: :ref:`int`, breakpointed\: :ref:`bool`\ ) :ref:`๐Ÿ”—` -Sets the line as breakpointed. +Sets the given line as a breakpoint. If ``true`` and :ref:`gutters_draw_breakpoints_gutter` is ``true``, draws the :ref:`breakpoint` icon in the gutter for this line. See :ref:`get_breakpointed_lines` and :ref:`is_line_breakpointed`. .. rst-class:: classref-item-separator @@ -1641,7 +1643,7 @@ Sets the line as breakpointed. |void| **set_line_as_executing**\ (\ line\: :ref:`int`, executing\: :ref:`bool`\ ) :ref:`๐Ÿ”—` -Sets the line as executing. +Sets the given line as executing. If ``true`` and :ref:`gutters_draw_executing_lines` is ``true``, draws the :ref:`executing_line` icon in the gutter for this line. See :ref:`get_executing_lines` and :ref:`is_line_executing`. .. rst-class:: classref-item-separator @@ -1689,7 +1691,7 @@ Toggle the folding of the code block on all lines with a caret on them. |void| **unfold_all_lines**\ (\ ) :ref:`๐Ÿ”—` -Unfolds all lines, folded or not. +Unfolds all lines that are folded. .. rst-class:: classref-item-separator @@ -1701,7 +1703,7 @@ Unfolds all lines, folded or not. |void| **unfold_line**\ (\ line\: :ref:`int`\ ) :ref:`๐Ÿ”—` -Unfolds all lines that were previously folded. +Unfolds the given line if it is folded or if it is hidden under a folded line. .. rst-class:: classref-item-separator @@ -1713,7 +1715,7 @@ Unfolds all lines that were previously folded. |void| **unindent_lines**\ (\ ) :ref:`๐Ÿ”—` -Unindents selected lines, or in the case of no selection the caret line by one. Same as performing "ui_text_unindent" action. +Unindents all lines that are selected or have a caret on them. Uses spaces or a tab depending on :ref:`indent_use_spaces`. Equivalent to the :ref:`ProjectSettings.input/ui_text_dedent` action. See :ref:`indent_lines`. .. rst-class:: classref-item-separator @@ -1978,6 +1980,18 @@ Sets a custom :ref:`Texture2D` to draw in the line folding gutt ---- +.. _class_CodeEdit_theme_icon_completion_color_bg: + +.. rst-class:: classref-themeproperty + +:ref:`Texture2D` **completion_color_bg** :ref:`๐Ÿ”—` + +Background panel for the color preview box in autocompletion (visible when the color is translucent). + +.. rst-class:: classref-item-separator + +---- + .. _class_CodeEdit_theme_icon_executing_line: .. rst-class:: classref-themeproperty diff --git a/classes/class_collisionshape3d.rst b/classes/class_collisionshape3d.rst index 38686496911..5d993b01c2b 100644 --- a/classes/class_collisionshape3d.rst +++ b/classes/class_collisionshape3d.rst @@ -44,11 +44,15 @@ Properties .. table:: :widths: auto - +-------------------------------+-----------------------------------------------------------+-----------+ - | :ref:`bool` | :ref:`disabled` | ``false`` | - +-------------------------------+-----------------------------------------------------------+-----------+ - | :ref:`Shape3D` | :ref:`shape` | | - +-------------------------------+-----------------------------------------------------------+-----------+ + +-------------------------------+-----------------------------------------------------------------+-----------------------+ + | :ref:`Color` | :ref:`debug_color` | ``Color(0, 0, 0, 0)`` | + +-------------------------------+-----------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`debug_fill` | ``true`` | + +-------------------------------+-----------------------------------------------------------------+-----------------------+ + | :ref:`bool` | :ref:`disabled` | ``false`` | + +-------------------------------+-----------------------------------------------------------------+-----------------------+ + | :ref:`Shape3D` | :ref:`shape` | | + +-------------------------------+-----------------------------------------------------------------+-----------------------+ .. rst-class:: classref-reftable-group @@ -73,6 +77,40 @@ Methods Property Descriptions --------------------- +.. _class_CollisionShape3D_property_debug_color: + +.. rst-class:: classref-property + +:ref:`Color` **debug_color** = ``Color(0, 0, 0, 0)`` :ref:`๐Ÿ”—` + +.. rst-class:: classref-property-setget + +- |void| **set_debug_color**\ (\ value\: :ref:`Color`\ ) +- :ref:`Color` **get_debug_color**\ (\ ) + +The collision shape color that is displayed in the editor, or in the running project if **Debug > Visible Collision Shapes** is checked at the top of the editor. If this is reset to its default value of ``Color(0, 0, 0, 0)``, the value of :ref:`ProjectSettings.debug/shapes/collision/shape_color` will be used instead. + +.. rst-class:: classref-item-separator + +---- + +.. _class_CollisionShape3D_property_debug_fill: + +.. rst-class:: classref-property + +:ref:`bool` **debug_fill** = ``true`` :ref:`๐Ÿ”—` + +.. rst-class:: classref-property-setget + +- |void| **set_enable_debug_fill**\ (\ value\: :ref:`bool`\ ) +- :ref:`bool` **get_enable_debug_fill**\ (\ ) + +If ``true``, when the shape is displayed, it will show a solid fill color in addition to its wireframe. + +.. rst-class:: classref-item-separator + +---- + .. _class_CollisionShape3D_property_disabled: .. rst-class:: classref-property diff --git a/classes/class_color.rst b/classes/class_color.rst index 08a71e5faf2..8c5b5ffbf9f 100644 --- a/classes/class_color.rst +++ b/classes/class_color.rst @@ -48,29 +48,35 @@ Properties .. table:: :widths: auto - +---------------------------+------------------------------------+---------+ - | :ref:`float` | :ref:`a` | ``1.0`` | - +---------------------------+------------------------------------+---------+ - | :ref:`int` | :ref:`a8` | ``255`` | - +---------------------------+------------------------------------+---------+ - | :ref:`float` | :ref:`b` | ``0.0`` | - +---------------------------+------------------------------------+---------+ - | :ref:`int` | :ref:`b8` | ``0`` | - +---------------------------+------------------------------------+---------+ - | :ref:`float` | :ref:`g` | ``0.0`` | - +---------------------------+------------------------------------+---------+ - | :ref:`int` | :ref:`g8` | ``0`` | - +---------------------------+------------------------------------+---------+ - | :ref:`float` | :ref:`h` | ``0.0`` | - +---------------------------+------------------------------------+---------+ - | :ref:`float` | :ref:`r` | ``0.0`` | - +---------------------------+------------------------------------+---------+ - | :ref:`int` | :ref:`r8` | ``0`` | - +---------------------------+------------------------------------+---------+ - | :ref:`float` | :ref:`s` | ``0.0`` | - +---------------------------+------------------------------------+---------+ - | :ref:`float` | :ref:`v` | ``0.0`` | - +---------------------------+------------------------------------+---------+ + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`a` | ``1.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`int` | :ref:`a8` | ``255`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`b` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`int` | :ref:`b8` | ``0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`g` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`int` | :ref:`g8` | ``0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`h` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`ok_hsl_h` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`ok_hsl_l` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`ok_hsl_s` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`r` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`int` | :ref:`r8` | ``0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`s` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ + | :ref:`float` | :ref:`v` | ``0.0`` | + +---------------------------+------------------------------------------------+---------+ .. rst-class:: classref-reftable-group @@ -1462,6 +1468,42 @@ The HSV hue of this color, on the range 0 to 1. ---- +.. _class_Color_property_ok_hsl_h: + +.. rst-class:: classref-property + +:ref:`float` **ok_hsl_h** = ``0.0`` :ref:`๐Ÿ”—` + +The OKHSL hue of this color, on the range 0 to 1. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Color_property_ok_hsl_l: + +.. rst-class:: classref-property + +:ref:`float` **ok_hsl_l** = ``0.0`` :ref:`๐Ÿ”—` + +The OKHSL lightness of this color, on the range 0 to 1. + +.. rst-class:: classref-item-separator + +---- + +.. _class_Color_property_ok_hsl_s: + +.. rst-class:: classref-property + +:ref:`float` **ok_hsl_s** = ``0.0`` :ref:`๐Ÿ”—` + +The OKHSL saturation of this color, on the range 0 to 1. + +.. rst-class:: classref-item-separator + +---- + .. _class_Color_property_r: .. rst-class:: classref-property @@ -1523,7 +1565,7 @@ Constructor Descriptions Constructs a default **Color** from opaque black. This is the same as :ref:`BLACK`. -\ **Note:** in C#, constructs an empty color with all of its components set to ``0.0`` (transparent black). +\ **Note:** In C#, this constructs a **Color** with all of its components set to ``0.0`` (transparent black). .. rst-class:: classref-item-separator diff --git a/classes/class_compositor.rst b/classes/class_compositor.rst index ec0e40c519f..31533f286bf 100644 --- a/classes/class_compositor.rst +++ b/classes/class_compositor.rst @@ -23,6 +23,13 @@ Description The compositor resource stores attributes used to customize how a :ref:`Viewport` is rendered. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`The Compositor <../tutorials/rendering/compositor>` + .. rst-class:: classref-reftable-group Properties diff --git a/classes/class_compositoreffect.rst b/classes/class_compositoreffect.rst index 9c644ec5d53..e1a8d1dc7d1 100644 --- a/classes/class_compositoreffect.rst +++ b/classes/class_compositoreffect.rst @@ -23,6 +23,13 @@ Description This resource defines a custom rendering effect that can be applied to :ref:`Viewport`\ s through the viewports' :ref:`Environment`. You can implement a callback that is called during rendering at a given stage of the rendering pipeline and allows you to insert additional passes. Note that this callback happens on the rendering thread. CompositorEffect is an abstract base class and must be extended to implement specific rendering logic. +.. rst-class:: classref-introduction-group + +Tutorials +--------- + +- :doc:`The Compositor <../tutorials/rendering/compositor>` + .. rst-class:: classref-reftable-group Properties @@ -112,7 +119,7 @@ The callback is called before our transparent rendering pass, but after our sky :ref:`EffectCallbackType` **EFFECT_CALLBACK_TYPE_POST_TRANSPARENT** = ``4`` -The callback is called after our transparent rendering pass, but before any build in post effects and output to our render target. +The callback is called after our transparent rendering pass, but before any built-in post-processing effects and output to our render target. .. _class_CompositorEffect_constant_EFFECT_CALLBACK_TYPE_MAX: @@ -257,6 +264,19 @@ If ``true`` this triggers normal and roughness data to be output during our dept var render_scene_buffers : RenderSceneBuffersRD = render_data.get_render_scene_buffers() var roughness_buffer = render_scene_buffers.get_texture("forward_clustered", "normal_roughness") +The raw normal and roughness buffer is stored in an optimized format, different than the one available in Spatial shaders. When sampling the buffer, a conversion function must be applied. Use this function, copied from `here `__: + +:: + + vec4 normal_roughness_compatibility(vec4 p_normal_roughness) { + float roughness = p_normal_roughness.w; + if (roughness > 0.5) { + roughness = 1.0 - roughness; + } + roughness /= (127.0 / 255.0); + return vec4(normalize(p_normal_roughness.xyz * 2.0 - 1.0) * 0.5 + 0.5, roughness); + } + .. rst-class:: classref-item-separator ---- diff --git a/classes/class_control.rst b/classes/class_control.rst index c6177e1a018..1c1804e85cb 100644 --- a/classes/class_control.rst +++ b/classes/class_control.rst @@ -25,6 +25,8 @@ Base class for all UI-related nodes. **Control** features a bounding rectangle t For more information on Godot's UI system, anchors, offsets, and containers, see the related tutorials in the manual. To build flexible UIs, you'll need a mix of UI elements that inherit from **Control** and :ref:`Container` nodes. +\ **Note:** Since both :ref:`Node2D` and **Control** inherit from :ref:`CanvasItem`, they share several concepts from the class such as the :ref:`CanvasItem.z_index` and :ref:`CanvasItem.visible` properties. + \ **User Interface nodes and input**\ Godot propagates input events via viewports. Each :ref:`Viewport` is responsible for propagating :ref:`InputEvent`\ s to their child nodes. As the :ref:`SceneTree.root` is a :ref:`Window`, this already happens automatically for all UI elements in your game. @@ -37,7 +39,7 @@ Only one **Control** node can be in focus. Only the node in focus will receive e Sets :ref:`mouse_filter` to :ref:`MOUSE_FILTER_IGNORE` to tell a **Control** node to ignore mouse or touch events. You'll need it if you place an icon on top of a button. -\ :ref:`Theme` resources change the Control's appearance. If you change the :ref:`Theme` on a **Control** node, it affects all of its children. To override some of the theme's parameters, call one of the ``add_theme_*_override`` methods, like :ref:`add_theme_font_override`. You can override the theme with the Inspector. +\ :ref:`Theme` resources change the control's appearance. The :ref:`theme` of a **Control** node affects all of its direct and indirect children (as long as a chain of controls is uninterrupted). To override some of the theme items, call one of the ``add_theme_*_override`` methods, like :ref:`add_theme_font_override`. You can also override theme items in the Inspector. \ **Note:** Theme items are *not* :ref:`Object` properties. This means you can't access their values using :ref:`Object.get` and :ref:`Object.set`. Instead, use the ``get_theme_*`` and ``add_theme_*_override`` methods provided by this class. @@ -143,6 +145,8 @@ Properties +---------------------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ | :ref:`StringName` | :ref:`theme_type_variation` | ``&""`` | +---------------------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ + | :ref:`AutoTranslateMode` | :ref:`tooltip_auto_translate_mode` | ``0`` | + +---------------------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ | :ref:`String` | :ref:`tooltip_text` | ``""`` | +---------------------------------------------------------------------+----------------------------------------------------------------------------------------------+-------------------------------------------------------------------------------+ @@ -894,7 +898,7 @@ enum **MouseFilter**: :ref:`๐Ÿ”—` :ref:`MouseFilter` **MOUSE_FILTER_STOP** = ``0`` -The control will receive mouse movement input events and mouse button input events if clicked on through :ref:`_gui_input`. And the control will receive the :ref:`mouse_entered` and :ref:`mouse_exited` signals. These events are automatically marked as handled, and they will not propagate further to other controls. This also results in blocking signals in other controls. +The control will receive mouse movement input events and mouse button input events if clicked on through :ref:`_gui_input`. The control will also receive the :ref:`mouse_entered` and :ref:`mouse_exited` signals. These events are automatically marked as handled, and they will not propagate further to other controls. This also results in blocking signals in other controls. .. _class_Control_constant_MOUSE_FILTER_PASS: @@ -902,7 +906,9 @@ The control will receive mouse movement input events and mouse button input even :ref:`MouseFilter` **MOUSE_FILTER_PASS** = ``1`` -The control will receive mouse movement input events and mouse button input events if clicked on through :ref:`_gui_input`. And the control will receive the :ref:`mouse_entered` and :ref:`mouse_exited` signals. If this control does not handle the event, the parent control (if any) will be considered, and so on until there is no more parent control to potentially handle it. This also allows signals to fire in other controls. If no control handled it, the event will be passed to :ref:`Node._shortcut_input` for further processing. +The control will receive mouse movement input events and mouse button input events if clicked on through :ref:`_gui_input`. The control will also receive the :ref:`mouse_entered` and :ref:`mouse_exited` signals. + +If this control does not handle the event, the event will propagate up to its parent control if it has one. The event is bubbled up the node hierarchy until it reaches a non-:ref:`CanvasItem`, a control with :ref:`MOUSE_FILTER_STOP`, or a :ref:`CanvasItem` with :ref:`CanvasItem.top_level` enabled. This will allow signals to fire in all controls it reaches. If no control handled it, the event will be passed to :ref:`Node._shortcut_input` for further processing. .. _class_Control_constant_MOUSE_FILTER_IGNORE: @@ -910,7 +916,7 @@ The control will receive mouse movement input events and mouse button input even :ref:`MouseFilter` **MOUSE_FILTER_IGNORE** = ``2`` -The control will not receive mouse movement input events and mouse button input events if clicked on through :ref:`_gui_input`. The control will also not receive the :ref:`mouse_entered` nor :ref:`mouse_exited` signals. This will not block other controls from receiving these events or firing the signals. Ignored events will not be handled automatically. +The control will not receive any mouse movement input events nor mouse button input events through :ref:`_gui_input`. The control will also not receive the :ref:`mouse_entered` nor :ref:`mouse_exited` signals. This will not block other controls from receiving these events or firing the signals. Ignored events will not be handled automatically. If a child has :ref:`MOUSE_FILTER_PASS` and an event was passed to this control, the event will further propagate up to the control's parent. \ **Note:** If the control has received :ref:`mouse_entered` but not :ref:`mouse_exited`, changing the :ref:`mouse_filter` to :ref:`MOUSE_FILTER_IGNORE` will cause :ref:`mouse_exited` to be emitted. @@ -992,11 +998,11 @@ enum **LayoutDirection**: :ref:`๐Ÿ”—` Automatic layout direction, determined from the parent control layout direction. -.. _class_Control_constant_LAYOUT_DIRECTION_LOCALE: +.. _class_Control_constant_LAYOUT_DIRECTION_APPLICATION_LOCALE: .. rst-class:: classref-enumeration-constant -:ref:`LayoutDirection` **LAYOUT_DIRECTION_LOCALE** = ``1`` +:ref:`LayoutDirection` **LAYOUT_DIRECTION_APPLICATION_LOCALE** = ``1`` Automatic layout direction, determined from the current locale. @@ -1016,6 +1022,32 @@ Left-to-right layout direction. Right-to-left layout direction. +.. _class_Control_constant_LAYOUT_DIRECTION_SYSTEM_LOCALE: + +.. rst-class:: classref-enumeration-constant + +:ref:`LayoutDirection` **LAYOUT_DIRECTION_SYSTEM_LOCALE** = ``4`` + +Automatic layout direction, determined from the system locale. + +.. _class_Control_constant_LAYOUT_DIRECTION_MAX: + +.. rst-class:: classref-enumeration-constant + +:ref:`LayoutDirection` **LAYOUT_DIRECTION_MAX** = ``5`` + +Represents the size of the :ref:`LayoutDirection` enum. + +.. _class_Control_constant_LAYOUT_DIRECTION_LOCALE: + +.. rst-class:: classref-enumeration-constant + +:ref:`LayoutDirection` **LAYOUT_DIRECTION_LOCALE** = ``1`` + +**Deprecated:** Use :ref:`LAYOUT_DIRECTION_APPLICATION_LOCALE` instead. + + + .. rst-class:: classref-item-separator ---- @@ -1581,10 +1613,12 @@ Controls whether the control will be able to receive mouse button input events t - |void| **set_force_pass_scroll_events**\ (\ value\: :ref:`bool`\ ) - :ref:`bool` **is_force_pass_scroll_events**\ (\ ) -When enabled, scroll wheel events processed by :ref:`_gui_input` will be passed to the parent control even if :ref:`mouse_filter` is set to :ref:`MOUSE_FILTER_STOP`. As it defaults to true, this allows nested scrollable containers to work out of the box. +When enabled, scroll wheel events processed by :ref:`_gui_input` will be passed to the parent control even if :ref:`mouse_filter` is set to :ref:`MOUSE_FILTER_STOP`. You should disable it on the root of your UI if you do not want scroll events to go to the :ref:`Node._unhandled_input` processing. +\ **Note:** Because this property defaults to ``true``, this allows nested scrollable containers to work out of the box. + .. rst-class:: classref-item-separator ---- @@ -1883,6 +1917,25 @@ When set, this property gives the highest priority to the type of the specified ---- +.. _class_Control_property_tooltip_auto_translate_mode: + +.. rst-class:: classref-property + +:ref:`AutoTranslateMode` **tooltip_auto_translate_mode** = ``0`` :ref:`๐Ÿ”—` + +.. rst-class:: classref-property-setget + +- |void| **set_tooltip_auto_translate_mode**\ (\ value\: :ref:`AutoTranslateMode`\ ) +- :ref:`AutoTranslateMode` **get_tooltip_auto_translate_mode**\ (\ ) + +Defines if tooltip text should automatically change to its translated version depending on the current locale. Uses the same auto translate mode as this control when set to :ref:`Node.AUTO_TRANSLATE_MODE_INHERIT`. + +\ **Note:** Tooltips customized using :ref:`_make_custom_tooltip` do not use this auto translate mode automatically. + +.. rst-class:: classref-item-separator + +---- + .. _class_Control_property_tooltip_text: .. rst-class:: classref-property @@ -1894,7 +1947,9 @@ When set, this property gives the highest priority to the type of the specified - |void| **set_tooltip_text**\ (\ value\: :ref:`String`\ ) - :ref:`String` **get_tooltip_text**\ (\ ) -The default tooltip text. The tooltip appears when the user's mouse cursor stays idle over this control for a few moments, provided that the :ref:`mouse_filter` property is not :ref:`MOUSE_FILTER_IGNORE`. The time required for the tooltip to appear can be changed with the :ref:`ProjectSettings.gui/timers/tooltip_delay_sec` option. See also :ref:`get_tooltip`. +The default tooltip text. The tooltip appears when the user's mouse cursor stays idle over this control for a few moments, provided that the :ref:`mouse_filter` property is not :ref:`MOUSE_FILTER_IGNORE`. The time required for the tooltip to appear can be changed with the :ref:`ProjectSettings.gui/timers/tooltip_delay_sec` setting. + +This string is the default return value of :ref:`get_tooltip`. Override :ref:`_get_tooltip` to generate tooltip text dynamically. Override :ref:`_make_custom_tooltip` to customize the tooltip interface and behavior. The tooltip popup will use either a default implementation, or a custom one that you can provide by overriding :ref:`_make_custom_tooltip`. The default tooltip includes a :ref:`PopupPanel` and :ref:`Label` whose theme properties can be customized using :ref:`Theme` methods with the ``"TooltipPanel"`` and ``"TooltipLabel"`` respectively. For example: @@ -1988,7 +2043,7 @@ Godot calls this method to pass you the ``data`` from a control's :ref:`_get_dra public override bool _CanDropData(Vector2 atPosition, Variant data) { - return data.VariantType == Variant.Type.Dictionary && dict.AsGodotDictionary().ContainsKey("color"); + return data.VariantType == Variant.Type.Dictionary && data.AsGodotDictionary().ContainsKey("color"); } public override void _DropData(Vector2 atPosition, Variant data) @@ -2061,7 +2116,7 @@ If not overridden, defaults to :ref:`Vector2.ZERO`. Virtual method to be implemented by the user. Returns the tooltip text for the position ``at_position`` in control's local coordinates, which will typically appear when the cursor is resting over this control. See :ref:`get_tooltip`. -\ **Note:** If this method returns an empty :ref:`String`, no tooltip is displayed. +\ **Note:** If this method returns an empty :ref:`String` and :ref:`_make_custom_tooltip` is not overridden, no tooltip is displayed. .. rst-class:: classref-item-separator @@ -2073,9 +2128,9 @@ Virtual method to be implemented by the user. Returns the tooltip text for the p |void| **_gui_input**\ (\ event\: :ref:`InputEvent`\ ) |virtual| :ref:`๐Ÿ”—` -Virtual method to be implemented by the user. Use this method to process and accept inputs on UI elements. See :ref:`accept_event`. +Virtual method to be implemented by the user. Override this method to handle and accept inputs on UI elements. See also :ref:`accept_event`. -\ **Example usage for clicking a control:**\ +\ **Example:** Click on the control to print a message: .. tabs:: @@ -2102,19 +2157,19 @@ Virtual method to be implemented by the user. Use this method to process and acc -The event won't trigger if: +If the ``event`` inherits :ref:`InputEventMouse`, this method will **not** be called when: -\* clicking outside the control (see :ref:`_has_point`); +- the control's :ref:`mouse_filter` is set to :ref:`MOUSE_FILTER_IGNORE`; -\* control has :ref:`mouse_filter` set to :ref:`MOUSE_FILTER_IGNORE`; +- the control is obstructed by another control on top, that doesn't have :ref:`mouse_filter` set to :ref:`MOUSE_FILTER_IGNORE`; -\* control is obstructed by another **Control** on top of it, which doesn't have :ref:`mouse_filter` set to :ref:`MOUSE_FILTER_IGNORE`; +- the control's parent has :ref:`mouse_filter` set to :ref:`MOUSE_FILTER_STOP` or has accepted the event; -\* control's parent has :ref:`mouse_filter` set to :ref:`MOUSE_FILTER_STOP` or has accepted the event; +- the control's parent has :ref:`clip_contents` enabled and the ``event``'s position is outside the parent's rectangle; -\* it happens outside the parent's rectangle and the parent has either :ref:`clip_contents` enabled. +- the ``event``'s position is outside the control (see :ref:`_has_point`). -\ **Note:** Event position is relative to the control origin. +\ **Note:** The ``event``'s position is relative to this control's origin. .. rst-class:: classref-item-separator @@ -2142,7 +2197,7 @@ If not overridden, default behavior is checking if the point is within control's :ref:`Object` **_make_custom_tooltip**\ (\ for_text\: :ref:`String`\ ) |virtual| |const| :ref:`๐Ÿ”—` -Virtual method to be implemented by the user. Returns a **Control** node that should be used as a tooltip instead of the default one. The ``for_text`` includes the contents of the :ref:`tooltip_text` property. +Virtual method to be implemented by the user. Returns a **Control** node that should be used as a tooltip instead of the default one. ``for_text`` is the return value of :ref:`get_tooltip`. The returned node must be of type **Control** or Control-derived. It can have child nodes of any type. It is freed when the tooltip disappears, so make sure you always provide a new instance (if you want to use a pre-existing node from your scene tree, you can duplicate it and pass the duplicated instance). When ``null`` or a non-Control node is returned, the default tooltip will be used instead. @@ -2150,9 +2205,11 @@ The returned node will be added as child to a :ref:`PopupPanel \ **Note:** The tooltip is shrunk to minimal size. If you want to ensure it's fully visible, you might want to set its :ref:`custom_minimum_size` to some non-zero value. -\ **Note:** The node (and any relevant children) should be :ref:`CanvasItem.visible` when returned, otherwise, the viewport that instantiates it will not be able to calculate its minimum size reliably. +\ **Note:** The node (and any relevant children) should have their :ref:`CanvasItem.visible` set to ``true`` when returned, otherwise, the viewport that instantiates it will not be able to calculate its minimum size reliably. + +\ **Note:** If overridden, this method is called even if :ref:`get_tooltip` returns an empty string. When this happens with the default tooltip, it is not displayed. To copy this behavior, return ``null`` in this method when ``for_text`` is empty. -\ **Example of usage with a custom-constructed node:**\ +\ **Example:** Use a constructed node as a tooltip: .. tabs:: @@ -2175,7 +2232,7 @@ The returned node will be added as child to a :ref:`PopupPanel -\ **Example of usage with a custom scene instance:**\ +\ **Example:** Usa a scene instance as a tooltip: .. tabs:: @@ -2240,7 +2297,7 @@ Creates a local override for a theme :ref:`Color` with the specifie See also :ref:`get_theme_color`. -\ **Example of overriding a label's color and resetting it later:**\ +\ **Example:** Override a :ref:`Label`'s color and reset it later: .. tabs:: @@ -2335,14 +2392,14 @@ Creates a local override for a theme :ref:`StyleBox` with the sp See also :ref:`get_theme_stylebox`. -\ **Example of modifying a property in a StyleBox by duplicating it:**\ +\ **Example:** Modify a property in a :ref:`StyleBox` by duplicating it: .. tabs:: .. code-tab:: gdscript - # The snippet below assumes the child node MyButton has a StyleBoxFlat assigned. + # The snippet below assumes the child node "MyButton" has a StyleBoxFlat assigned. # Resources are shared across instances, so we need to duplicate it # to avoid modifying the appearance of all other buttons. var new_stylebox_normal = $MyButton.get_theme_stylebox("normal").duplicate() @@ -2354,7 +2411,7 @@ See also :ref:`get_theme_stylebox`. .. code-tab:: csharp - // The snippet below assumes the child node MyButton has a StyleBoxFlat assigned. + // The snippet below assumes the child node "MyButton" has a StyleBoxFlat assigned. // Resources are shared across instances, so we need to duplicate it // to avoid modifying the appearance of all other buttons. StyleBoxFlat newStyleboxNormal = GetNode