diff options
Diffstat (limited to 'doc/classes')
46 files changed, 615 insertions, 332 deletions
diff --git a/doc/classes/@GlobalScope.xml b/doc/classes/@GlobalScope.xml index bcab80ea94..2cd3a51722 100644 --- a/doc/classes/@GlobalScope.xml +++ b/doc/classes/@GlobalScope.xml @@ -2939,10 +2939,10 @@ The property is not stored, and does not display in the editor. This is the default for non-exported properties. </constant> <constant name="PROPERTY_USAGE_STORAGE" value="2" enum="PropertyUsageFlags" is_bitfield="true"> - The property is serialized and saved in the scene file (default). + The property is serialized and saved in the scene file (default for exported properties). </constant> <constant name="PROPERTY_USAGE_EDITOR" value="4" enum="PropertyUsageFlags" is_bitfield="true"> - The property is shown in the [EditorInspector] (default). + The property is shown in the [EditorInspector] (default for exported properties). </constant> <constant name="PROPERTY_USAGE_INTERNAL" value="8" enum="PropertyUsageFlags" is_bitfield="true"> The property is excluded from the class reference. diff --git a/doc/classes/AABB.xml b/doc/classes/AABB.xml index 427d38d421..77c74e17da 100644 --- a/doc/classes/AABB.xml +++ b/doc/classes/AABB.xml @@ -170,7 +170,7 @@ <method name="get_shortest_axis" qualifiers="const"> <return type="Vector3" /> <description> - Returns the shortest normaalized axis of this bounding box's [member size], as a [Vector3] ([constant Vector3.RIGHT], [constant Vector3.UP], or [constant Vector3.BACK]). + Returns the shortest normalized axis of this bounding box's [member size], as a [Vector3] ([constant Vector3.RIGHT], [constant Vector3.UP], or [constant Vector3.BACK]). [codeblocks] [gdscript] var box = AABB(Vector3(0, 0, 0), Vector3(2, 4, 8)) diff --git a/doc/classes/Animation.xml b/doc/classes/Animation.xml index 3b7a6e66fe..80fd52c684 100644 --- a/doc/classes/Animation.xml +++ b/doc/classes/Animation.xml @@ -560,7 +560,7 @@ <param index="0" name="track_idx" type="int" /> <param index="1" name="path" type="NodePath" /> <description> - Sets the path of a track. Paths must be valid scene-tree paths to a node and must be specified starting from the parent node of the node that will reproduce the animation. Tracks that control properties or bones must append their name after the path, separated by [code]":"[/code]. + Sets the path of a track. Paths must be valid scene-tree paths to a node and must be specified starting from the [member AnimationMixer.root_node] that will reproduce the animation. Tracks that control properties or bones must append their name after the path, separated by [code]":"[/code]. For example, [code]"character/skeleton:ankle"[/code] or [code]"character/mesh:transform/local"[/code]. </description> </method> diff --git a/doc/classes/AnimationMixer.xml b/doc/classes/AnimationMixer.xml index c635eba2ab..58ef118e46 100644 --- a/doc/classes/AnimationMixer.xml +++ b/doc/classes/AnimationMixer.xml @@ -27,6 +27,13 @@ <param index="1" name="library" type="AnimationLibrary" /> <description> Adds [param library] to the animation player, under the key [param name]. + AnimationMixer has a global library by default with an empty string as key. For adding an animation to the global library: + [codeblocks] + [gdscript] + var global_library = mixer.get_animation_library("") + global_library.add_animation("animation_name", animation_resource) + [/gdscript] + [/codeblocks] </description> </method> <method name="advance"> @@ -182,10 +189,10 @@ 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_Quaternion_accumulator() + 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 prev_root_motion_rotation_accumulator = current_root_motion_rotation_accumulator - transform.basis *= difference + transform.basis *= Basis(difference) [/gdscript] [/codeblocks] However, if the animation loops, an unintended discrete change may occur, so this is only useful for some simple use cases. @@ -297,8 +304,8 @@ This makes it more convenient to preview and edit animations in the editor, as changes to the scene will not be saved as long as they are set in the reset animation. </member> <member name="root_motion_track" type="NodePath" setter="set_root_motion_track" getter="get_root_motion_track" default="NodePath("")"> - The path to the Animation track used for root motion. Paths must be valid scene-tree paths to a node, and must be specified starting from the parent node of the node that will reproduce the animation. To specify a track that controls properties or bones, append its name after the path, separated by [code]":"[/code]. For example, [code]"character/skeleton:ankle"[/code] or [code]"character/mesh:transform/local"[/code]. - If the track has type [constant Animation.TYPE_POSITION_3D], [constant Animation.TYPE_ROTATION_3D] or [constant Animation.TYPE_SCALE_3D] the transformation will be canceled visually, and the animation will appear to stay in place. See also [method get_root_motion_position], [method get_root_motion_rotation], [method get_root_motion_scale] and [RootMotionView]. + The path to the Animation track used for root motion. Paths must be valid scene-tree paths to a node, and must be specified starting from the parent node of the node that will reproduce the animation. The [member root_motion_track] uses the same format as [method Animation.track_set_path], but note that a bone must be specified. + If the track has type [constant Animation.TYPE_POSITION_3D], [constant Animation.TYPE_ROTATION_3D], or [constant Animation.TYPE_SCALE_3D] the transformation will be canceled visually, and the animation will appear to stay in place. See also [method get_root_motion_position], [method get_root_motion_rotation], [method get_root_motion_scale], and [RootMotionView]. </member> <member name="root_node" type="NodePath" setter="set_root_node" getter="get_root_node" default="NodePath("..")"> The node which node path references will travel from. diff --git a/doc/classes/AnimationPlayer.xml b/doc/classes/AnimationPlayer.xml index 302ca314bb..1ca8ac2fa5 100644 --- a/doc/classes/AnimationPlayer.xml +++ b/doc/classes/AnimationPlayer.xml @@ -135,7 +135,7 @@ <return type="void" /> <param index="0" name="name" type="StringName" /> <description> - Queues an animation for playback once the current one is done. + Queues an animation for playback once the current animation and all previously queued animations are done. [b]Note:[/b] If a looped animation is currently playing, the queued animation will never play unless the looped animation is stopped somehow. </description> </method> diff --git a/doc/classes/Array.xml b/doc/classes/Array.xml index 326b71c588..3731b8dcf1 100644 --- a/doc/classes/Array.xml +++ b/doc/classes/Array.xml @@ -4,41 +4,31 @@ A built-in data structure that holds a sequence of elements. </brief_description> <description> - An array data structure that can contain a sequence of elements of any 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.). + An array data structure that can contain a sequence of elements of any [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.). [b]Example:[/b] [codeblocks] [gdscript] - var array = ["One", 2, 3, "Four"] - print(array[0]) # One. - print(array[2]) # 3. - print(array[-1]) # Four. - array[2] = "Three" - print(array[-2]) # Three. - [/gdscript] - [csharp] - var array = new Godot.Collections.Array{"One", 2, 3, "Four"}; - GD.Print(array[0]); // One. - GD.Print(array[2]); // 3. - GD.Print(array[array.Count - 1]); // Four. - array[2] = "Three"; - GD.Print(array[array.Count - 2]); // Three. - [/csharp] - [/codeblocks] - Arrays can be concatenated using the [code]+[/code] operator: - [codeblocks] - [gdscript] - var array1 = ["One", 2] - var array2 = [3, "Four"] - print(array1 + array2) # ["One", 2, 3, "Four"] + var array = ["First", 2, 3, "Last"] + print(array[0]) # Prints "First" + print(array[2]) # Prints 3 + print(array[-1]) # Prints "Last" + + array[1] = "Second" + print(array[1]) # Prints "Second" + print(array[-3]) # Prints "Second" [/gdscript] [csharp] - // Array concatenation is not possible with C# arrays, but is with Godot.Collections.Array. - var array1 = new Godot.Collections.Array{"One", 2}; - var array2 = new Godot.Collections.Array{3, "Four"}; - GD.Print(array1 + array2); // Prints [One, 2, 3, Four] + var array = new Godot.Collections.Array{"First", 2, 3, "Last"}; + GD.Print(array[0]); // Prints "First" + GD.Print(array[2]); // Prints 3 + GD.Print(array[array.Count - 1]); // Prints "Last" + + array[2] = "Second"; + GD.Print(array[1]); // Prints "Second" + GD.Print(array[array.Count - 3]); // Prints "Second" [/csharp] [/codeblocks] - [b]Note:[/b] Arrays are always passed by reference. To get a copy of an array that can be modified independently of the original array, use [method duplicate]. + [b]Note:[/b] Arrays are always passed by [b]reference[/b]. To get a copy of an array that can be modified independently of the original array, use [method duplicate]. [b]Note:[/b] Erasing elements while iterating over arrays is [b]not[/b] supported and will result in unpredictable behavior. [b]Differences between packed arrays, typed arrays, and untyped arrays:[/b] Packed arrays are generally faster to iterate on and modify compared to a typed array of the same type (e.g. [PackedInt64Array] versus [code]Array[int][/code]). Also, packed arrays consume less memory. As a downside, packed arrays are less flexible as they don't offer as many convenience methods such as [method Array.map]. Typed arrays are in turn faster to iterate on and modify than untyped arrays. </description> @@ -58,29 +48,32 @@ <param index="2" name="class_name" type="StringName" /> <param index="3" name="script" type="Variant" /> <description> - Creates a typed array from the [param base] array. All arguments are required. - - [param type] is the built-in type as a [enum Variant.Type] constant, for example [constant TYPE_INT]. - - [param class_name] is the [b]native[/b] class name, for example [Node]. If [param type] is not [constant TYPE_OBJECT], must be an empty string. - - [param script] is the associated script. Must be a [Script] instance or [code]null[/code]. - Examples: + Creates a typed array from the [param base] array. A typed array can only contain elements of the given type, or that inherit from the given class, as described by this constructor's parameters: + - [param type] is the built-in [Variant] type, as one the [enum Variant.Type] constants. + - [param class_name] is the built-in class name (see [method Object.get_class]). + - [param script] is the associated script. It must be a [Script] instance or [code]null[/code]. + If [param type] is not [constant TYPE_OBJECT], [param class_name] must be an empty [StringName] and [param script] must be [code]null[/code]. [codeblock] - class_name MyNode + class_name Sword extends Node - class MyClass: + class Stats: pass func _ready(): - var a = Array([], TYPE_INT, &"", null) # Array[int] - var b = Array([], TYPE_OBJECT, &"Node", null) # Array[Node] - var c = Array([], TYPE_OBJECT, &"Node", MyNode) # Array[MyNode] - var d = Array([], TYPE_OBJECT, &"RefCounted", MyClass) # Array[MyClass] + var a = Array([], TYPE_INT, "", null) # Array[int] + var b = Array([], TYPE_OBJECT, "Node", null) # Array[Node] + var c = Array([], TYPE_OBJECT, "Node", Sword) # Array[Sword] + var d = Array([], TYPE_OBJECT, "RefCounted", Stats) # Array[Stats] [/codeblock] - [b]Note:[/b] This constructor can be useful if you want to create a typed array on the fly, but you are not required to use it. In GDScript you can use a temporary variable with the static type you need and then pass it: + The [param base] array's elements are converted when necessary. If this is not possible or [param base] is already typed, this constructor fails and returns an empty [Array]. + In GDScript, this constructor is usually not necessary, as it is possible to create a typed array through static typing: [codeblock] - func _ready(): - var a: Array[int] = [] - some_func(a) + var numbers: Array[float] = [] + var children: Array[Node] = [$Node, $Sprite2D, $RigidBody3D] + + var integers: Array[int] = [0.2, 4.5, -2.0] + print(integers) # Prints [0, 4, -2] [/codeblock] </description> </constructor> @@ -167,20 +160,44 @@ <return type="bool" /> <param index="0" name="method" type="Callable" /> <description> - Calls the provided [Callable] on each element in the array and returns [code]true[/code] if the [Callable] returns [code]true[/code] for [i]all[/i] elements in the array. If the [Callable] returns [code]false[/code] for one array element or more, this method returns [code]false[/code]. - The callable's method should take one [Variant] parameter (the current array element) and return a boolean value. - [codeblock] + Calls the given [Callable] on each element in the array and returns [code]true[/code] if the [Callable] returns [code]true[/code] for [i]all[/i] elements in the array. If the [Callable] returns [code]false[/code] for one array element or more, this method returns [code]false[/code]. + The [param method] should take one [Variant] parameter (the current array element) and return a [bool]. + [codeblocks] + [gdscript] + func greater_than_5(number): + return number > 5 + func _ready(): - print([6, 10, 6].all(greater_than_5)) # Prints True (3/3 elements evaluate to `true`). - print([4, 10, 4].all(greater_than_5)) # Prints False (1/3 elements evaluate to `true`). - print([4, 4, 4].all(greater_than_5)) # Prints False (0/3 elements evaluate to `true`). - print([].all(greater_than_5)) # Prints True (0/0 elements evaluate to `true`). + print([6, 10, 6].all(greater_than_5)) # Prints true (3/3 elements evaluate to true). + print([4, 10, 4].all(greater_than_5)) # Prints false (1/3 elements evaluate to true). + print([4, 4, 4].all(greater_than_5)) # Prints false (0/3 elements evaluate to true). + print([].all(greater_than_5)) # Prints true (0/0 elements evaluate to true). + + # Same as the first line above, but using a lambda function. + print([6, 10, 6].all(func(element): return element > 5)) # Prints true + [/gdscript] + [csharp] + private static bool GreaterThan5(int number) + { + return number > 5; + } - print([6, 10, 6].all(func(number): return number > 5)) # Prints True. Same as the first line above, but using lambda function. + public override void _Ready() + { + // Prints true (3/3 elements evaluate to true). + GD.Print(new Godot.Collections.Array>int< { 6, 10, 6 }.All(GreaterThan5)); + // Prints false (1/3 elements evaluate to true). + GD.Print(new Godot.Collections.Array>int< { 4, 10, 4 }.All(GreaterThan5)); + // Prints false (0/3 elements evaluate to true). + GD.Print(new Godot.Collections.Array>int< { 4, 4, 4 }.All(GreaterThan5)); + // Prints true (0/0 elements evaluate to true). + GD.Print(new Godot.Collections.Array>int< { }.All(GreaterThan5)); - func greater_than_5(number): - return number > 5 - [/codeblock] + // Same as the first line above, but using a lambda function. + GD.Print(new Godot.Collections.Array>int< { 6, 10, 6 }.All(element => element > 5)); // Prints true + } + [/csharp] + [/codeblocks] See also [method any], [method filter], [method map] and [method reduce]. [b]Note:[/b] Unlike relying on the size of an array returned by [method filter], this method will return as early as possible to improve performance (especially with large arrays). [b]Note:[/b] For an empty array, this method [url=https://en.wikipedia.org/wiki/Vacuous_truth]always[/url] returns [code]true[/code]. @@ -190,19 +207,20 @@ <return type="bool" /> <param index="0" name="method" type="Callable" /> <description> - Calls the provided [Callable] on each element in the array and returns [code]true[/code] if the [Callable] returns [code]true[/code] for [i]one or more[/i] elements in the array. If the [Callable] returns [code]false[/code] for all elements in the array, this method returns [code]false[/code]. - The callable's method should take one [Variant] parameter (the current array element) and return a boolean value. + Calls the given [Callable] on each element in the array and returns [code]true[/code] if the [Callable] returns [code]true[/code] for [i]one or more[/i] elements in the array. If the [Callable] returns [code]false[/code] for all elements in the array, this method returns [code]false[/code]. + The [param method] should take one [Variant] parameter (the current array element) and return a [bool]. [codeblock] - func _ready(): - print([6, 10, 6].any(greater_than_5)) # Prints True (3 elements evaluate to `true`). - print([4, 10, 4].any(greater_than_5)) # Prints True (1 elements evaluate to `true`). - print([4, 4, 4].any(greater_than_5)) # Prints False (0 elements evaluate to `true`). - print([].any(greater_than_5)) # Prints False (0 elements evaluate to `true`). - - print([6, 10, 6].any(func(number): return number > 5)) # Prints True. Same as the first line above, but using lambda function. - func greater_than_5(number): return number > 5 + + func _ready(): + print([6, 10, 6].any(greater_than_5)) # Prints true (3 elements evaluate to true). + print([4, 10, 4].any(greater_than_5)) # Prints true (1 elements evaluate to true). + print([4, 4, 4].any(greater_than_5)) # Prints false (0 elements evaluate to true). + print([].any(greater_than_5)) # Prints false (0 elements evaluate to true). + + # Same as the first line above, but using a lambda function. + print([6, 10, 6].any(func(number): return number > 5)) # Prints true [/codeblock] See also [method all], [method filter], [method map] and [method reduce]. [b]Note:[/b] Unlike relying on the size of an array returned by [method filter], this method will return as early as possible to improve performance (especially with large arrays). @@ -213,19 +231,19 @@ <return type="void" /> <param index="0" name="value" type="Variant" /> <description> - Appends an element at the end of the array (alias of [method push_back]). + Appends [param value] at the end of the array (alias of [method push_back]). </description> </method> <method name="append_array"> <return type="void" /> <param index="0" name="array" type="Array" /> <description> - Appends another array at the end of this array. + Appends another [param array] at the end of this array. [codeblock] - var array1 = [1, 2, 3] - var array2 = [4, 5, 6] - array1.append_array(array2) - print(array1) # Prints [1, 2, 3, 4, 5, 6]. + var numbers = [1, 2, 3] + var extra = [4, 5, 6] + numbers.append_array(extra) + print(nums) # Prints [1, 2, 3, 4, 5, 6] [/codeblock] </description> </method> @@ -239,8 +257,8 @@ <method name="back" qualifiers="const"> <return type="Variant" /> <description> - Returns the last element of the array. Prints an error and returns [code]null[/code] if the array is empty. - [b]Note:[/b] Calling this function is not the same as writing [code]array[-1][/code]. If the array is empty, accessing by index will pause project execution when running from the editor. + Returns the last element of the array. If the array is empty, fails and returns [code]null[/code]. See also [method front]. + [b]Note:[/b] Unlike with the [code][][/code] operator ([code]array[-1][/code]), an error is generated without stopping project execution. </description> </method> <method name="bsearch" qualifiers="const"> @@ -248,13 +266,20 @@ <param index="0" name="value" type="Variant" /> <param index="1" name="before" type="bool" default="true" /> <description> - Finds the index of an existing value (or the insertion index that maintains sorting order, if the value is not yet present in the array) using binary search. Optionally, a [param before] specifier can be passed. If [code]false[/code], the returned index comes after all existing entries of the value in the array. + Returns the index of [param value] in the sorted array. If it cannot be found, returns where [param value] should be inserted to keep the array sorted. The algorithm used is [url=https://en.wikipedia.org/wiki/Binary_search_algorithm]binary search[/url]. + If [param before] is [code]true[/code] (as by default), the returned index comes before all existing elements equal to [param value] in the array. [codeblock] - var array = ["a", "b", "c", "c", "d", "e"] - print(array.bsearch("c", true)) # Prints 2, at the first matching element. - print(array.bsearch("c", false)) # Prints 4, after the last matching element, pointing to "d". + var numbers = [2, 4, 8, 10] + var idx = numbers.bsearch(7) + + numbers.insert(idx, 7) + print(numbers) # Prints [2, 4, 7, 8, 10] + + var fruits = ["Apple", "Lemon", "Lemon", "Orange"] + print(fruits.bsearch("Lemon", true)) # Prints 1, points at the first "Lemon". + print(fruits.bsearch("Lemon", false)) # Prints 3, points at "Orange". [/codeblock] - [b]Note:[/b] Calling [method bsearch] on an unsorted array results in unexpected behavior. + [b]Note:[/b] Calling [method bsearch] on an [i]unsorted[/i] array will result in unexpected behavior. Use [method sort] before calling this method. </description> </method> <method name="bsearch_custom" qualifiers="const"> @@ -263,15 +288,36 @@ <param index="1" name="func" type="Callable" /> <param index="2" name="before" type="bool" default="true" /> <description> - Finds the index of an existing value (or the insertion index that maintains sorting order, if the value is not yet present in the array) using binary search and a custom comparison method. Optionally, a [param before] specifier can be passed. If [code]false[/code], the returned index comes after all existing entries of the value in the array. The custom method receives two arguments (an element from the array and the value searched for) and must return [code]true[/code] if the first argument is less than the second, and return [code]false[/code] otherwise. - [b]Note:[/b] The custom method must accept the two arguments in any order, you cannot rely on that the first argument will always be from the array. - [b]Note:[/b] Calling [method bsearch_custom] on an unsorted array results in unexpected behavior. + Returns the index of [param value] in the sorted array. If it cannot be found, returns where [param value] should be inserted to keep the array sorted (using [param func] for the comparisons). The algorithm used is [url=https://en.wikipedia.org/wiki/Binary_search_algorithm]binary search[/url]. + Similar to [method sort_custom], [param func] is called as many times as necessary, receiving one array element and [param value] as arguments. The function should return [code]true[/code] if the array element should be [i]behind[/i] [param value], otherwise it should return [code]false[/code]. + If [param before] is [code]true[/code] (as by default), the returned index comes before all existing elements equal to [param value] in the array. + [codeblock] + func sort_by_amount(a, b): + if a[1] < b[1]: + return true + return false + + func _ready(): + var my_items = [["Tomato", 2], ["Kiwi", 5], ["Rice", 9]] + + var apple = ["Apple", 5] + # "Apple" is inserted before "Kiwi". + my_items.insert(my_items.bsearch_custom(apple, sort_by_amount, true), apple) + + var banana = ["Banana", 5] + # "Banana" is inserted after "Kiwi". + my_items.insert(my_items.bsearch_custom(banana, sort_by_amount, false), banana) + + # Prints [["Tomato", 2], ["Apple", 5], ["Kiwi", 5], ["Banana", 5], ["Rice", 9]] + print(my_items) + [/codeblock] + [b]Note:[/b] Calling [method bsearch_custom] on an [i]unsorted[/i] array will result in unexpected behavior. Use [method sort_custom] with [param func] before calling this method. </description> </method> <method name="clear"> <return type="void" /> <description> - Clears the array. This is equivalent to using [method resize] with a size of [code]0[/code]. + Removes all elements from the array. This is equivalent to using [method resize] with a size of [code]0[/code]. </description> </method> <method name="count" qualifiers="const"> @@ -285,53 +331,57 @@ <return type="Array" /> <param index="0" name="deep" type="bool" default="false" /> <description> - Returns a copy of the array. - If [param deep] is [code]true[/code], a deep copy is performed: all nested arrays and dictionaries are duplicated and will not be shared with the original array. If [code]false[/code], a shallow copy is made and references to the original nested arrays and dictionaries are kept, so that modifying a sub-array or dictionary in the copy will also impact those referenced in the source array. Note that any [Object]-derived elements will be shallow copied regardless of the [param deep] setting. + Returns a new copy of the array. + By default, a [b]shallow[/b] copy is returned: all nested [Array] and [Dictionary] elements are shared with the original array. Modifying them in one array will also affect them in the other.[br]If [param deep] is [code]true[/code], a [b]deep[/b] copy is returned: all nested arrays and dictionaries are also duplicated (recursively). </description> </method> <method name="erase"> <return type="void" /> <param index="0" name="value" type="Variant" /> <description> - Removes the first occurrence of a value from the array. If the value does not exist in the array, nothing happens. To remove an element by index, use [method remove_at] instead. - [b]Note:[/b] This method acts in-place and doesn't return a modified array. - [b]Note:[/b] On large arrays, this method will be slower if the removed element is close to the beginning of the array (index 0). This is because all elements placed after the removed element have to be reindexed. - [b]Note:[/b] Do not erase entries while iterating over the array. + Finds and removes the first occurrence of [param value] from the array. If [param value] does not exist in the array, nothing happens. To remove an element by index, use [method remove_at] instead. + [b]Note:[/b] This method shifts every element's index after the removed [param value] back, which may have a noticeable performance cost, especially on larger arrays. + [b]Note:[/b] Erasing elements while iterating over arrays is [b]not[/b] supported and will result in unpredictable behavior. </description> </method> <method name="fill"> <return type="void" /> <param index="0" name="value" type="Variant" /> <description> - Assigns the given value to all elements in the array. This can typically be used together with [method resize] to create an array with a given size and initialized elements: + Assigns the given [param value] to all elements in the array. + This method can often be combined with [method resize] to create an array with a given size and initialized elements: [codeblocks] [gdscript] var array = [] - array.resize(10) - array.fill(0) # Initialize the 10 elements to 0. + array.resize(5) + array.fill(2) + print(array) # Prints [2, 2, 2, 2, 2] [/gdscript] [csharp] var array = new Godot.Collections.Array(); - array.Resize(10); - array.Fill(0); // Initialize the 10 elements to 0. + array.Resize(5); + array.Fill(2); + GD.Print(array); // Prints [2, 2, 2, 2, 2] [/csharp] [/codeblocks] - [b]Note:[/b] If [param value] is of a reference type ([Object]-derived, [Array], [Dictionary], etc.) then the array is filled with the references to the same object, i.e. no duplicates are created. + [b]Note:[/b] If [param value] is a [Variant] passed by reference ([Object]-derived, [Array], [Dictionary], etc.), the array will be filled with references to the same [param value], which are not duplicates. </description> </method> <method name="filter" qualifiers="const"> <return type="Array" /> <param index="0" name="method" type="Callable" /> <description> - Calls the provided [Callable] on each element in the array and returns a new array with the elements for which the method returned [code]true[/code]. - The callable's method should take one [Variant] parameter (the current array element) and return a boolean value. + Calls the given [Callable] on each element in the array and returns a new, filtered [Array]. + The [param method] receives one of the array elements as an argument, and should return [code]true[/code] to add the element to the filtered array, or [code]false[/code] to exclude it. [codeblock] + func is_even(number): + return number % 2 == 0 + func _ready(): - print([1, 2, 3].filter(remove_1)) # Prints [2, 3]. - print([1, 2, 3].filter(func(number): return number != 1)) # Same as above, but using lambda function. + print([1, 4, 5, 8].filter(is_even)) # Prints [4, 8] - func remove_1(number): - return number != 1 + # Same as above, but using a lambda function. + print([1, 4, 5, 8].filter(func(number): return number % 2 == 0)) [/codeblock] See also [method any], [method all], [method map] and [method reduce]. </description> @@ -341,78 +391,70 @@ <param index="0" name="what" type="Variant" /> <param index="1" name="from" type="int" default="0" /> <description> - Searches the array for a value and returns its index or [code]-1[/code] if not found. Optionally, the initial search index can be passed. + Returns the index of the [b]first[/b] occurrence of [param what] in this array, or [code]-1[/code] if there are none. The search's start can be specified with [param from], continuing to the end of the array. + [b]Note:[/b] If you just want to know whether the array contains [param what], use [method has] ([code]Contains[/code] in C#). In GDScript, you may also use the [code]in[/code] operator. + [b]Note:[/b] For performance reasons, the search is affected by [param what]'s [enum Variant.Type]. For example, [code]7[/code] ([int]) and [code]7.0[/code] ([float]) are not considered equal for this method. </description> </method> <method name="front" qualifiers="const"> <return type="Variant" /> <description> - Returns the first element of the array. Prints an error and returns [code]null[/code] if the array is empty. - [b]Note:[/b] Calling this function is not the same as writing [code]array[0][/code]. If the array is empty, accessing by index will pause project execution when running from the editor. + Returns the first element of the array. If the array is empty, fails and returns [code]null[/code]. See also [method back]. + [b]Note:[/b] Unlike with the [code][][/code] operator ([code]array[0][/code]), an error is generated without stopping project execution. </description> </method> <method name="get_typed_builtin" qualifiers="const"> <return type="int" /> <description> - Returns the built-in type of the typed array as a [enum Variant.Type] constant. If the array is not typed, returns [constant TYPE_NIL]. + Returns the built-in [Variant] type of the typed array as a [enum Variant.Type] constant. If the array is not typed, returns [constant TYPE_NIL]. See also [method is_typed]. </description> </method> <method name="get_typed_class_name" qualifiers="const"> <return type="StringName" /> <description> - Returns the [b]native[/b] class name of the typed array if the built-in type is [constant TYPE_OBJECT]. Otherwise, this method returns an empty string. + Returns the [b]built-in[/b] class name of the typed array, if the built-in [Variant] type [constant TYPE_OBJECT]. Otherwise, returns an empty [StringName]. See also [method is_typed] and [method Object.get_class]. </description> </method> <method name="get_typed_script" qualifiers="const"> <return type="Variant" /> <description> - Returns the script associated with the typed array. This method returns a [Script] instance or [code]null[/code]. + Returns the [Script] instance associated with this typed array, or [code]null[/code] if it does not exist. See also [method is_typed]. </description> </method> <method name="has" qualifiers="const" keywords="includes, contains"> <return type="bool" /> <param index="0" name="value" type="Variant" /> <description> - Returns [code]true[/code] if the array contains the given value. + Returns [code]true[/code] if the array contains the given [param value]. [codeblocks] [gdscript] - print(["inside", 7].has("inside")) # True - print(["inside", 7].has("outside")) # False - print(["inside", 7].has(7)) # True - print(["inside", 7].has("7")) # False + print(["inside", 7].has("inside")) # Prints true + print(["inside", 7].has("outside")) # Prints false + print(["inside", 7].has(7)) # Prints true + print(["inside", 7].has("7")) # Prints false [/gdscript] [csharp] var arr = new Godot.Collections.Array { "inside", 7 }; - // has is renamed to Contains - GD.Print(arr.Contains("inside")); // True - GD.Print(arr.Contains("outside")); // False - GD.Print(arr.Contains(7)); // True - GD.Print(arr.Contains("7")); // False - [/csharp] - [/codeblocks] - [b]Note:[/b] This is equivalent to using the [code]in[/code] operator as follows: - [codeblocks] - [gdscript] - # Will evaluate to `true`. - if 2 in [2, 4, 6, 8]: - print("Contains!") - [/gdscript] - [csharp] - // As there is no "in" keyword in C#, you have to use Contains - var array = new Godot.Collections.Array { 2, 4, 6, 8 }; - if (array.Contains(2)) - { - GD.Print("Contains!"); - } + // By C# convention, this method is renamed to `Contains`. + GD.Print(arr.Contains("inside")); // Prints true + GD.Print(arr.Contains("outside")); // Prints false + GD.Print(arr.Contains(7)); // Prints true + GD.Print(arr.Contains("7")); // Prints false [/csharp] [/codeblocks] + In GDScript, this is equivalent to the [code]in[/code] operator: + [codeblock] + if 4 in [2, 4, 6, 8]: + print("4 is here!") # Will be printed. + [/codeblock] + [b]Note:[/b] For performance reasons, the search is affected by the [param value]'s [enum Variant.Type]. For example, [code]7[/code] ([int]) and [code]7.0[/code] ([float]) are not considered equal for this method. </description> </method> <method name="hash" qualifiers="const"> <return type="int" /> <description> Returns a hashed 32-bit integer value representing the array and its contents. - [b]Note:[/b] [Array]s with equal content will always produce identical hash values. However, the reverse is not true. Returning identical hash values does [i]not[/i] imply the arrays are equal, because different arrays can have identical hash values due to hash collisions. + [b]Note:[/b] Arrays with equal hash values are [i]not[/i] guaranteed to be the same, as a result of hash collisions. On the countrary, arrays with different hash values are guaranteed to be different. </description> </method> <method name="insert"> @@ -420,55 +462,64 @@ <param index="0" name="position" type="int" /> <param index="1" name="value" type="Variant" /> <description> - Inserts a new element at a given position in the array. The position must be valid, or at the end of the array ([code]pos == size()[/code]). Returns [constant OK] on success, or one of the other [enum Error] values if the operation failed. - [b]Note:[/b] This method acts in-place and doesn't return a modified array. - [b]Note:[/b] On large arrays, this method will be slower if the inserted element is close to the beginning of the array (index 0). This is because all elements placed after the newly inserted element have to be reindexed. + Inserts a new element ([param value]) at a given index ([param position]) in the array. [param position] should be between [code]0[/code] and the array's [method size]. + Returns [constant OK] on success, or one of the other [enum Error] constants if this method fails. + [b]Note:[/b] Every element's index after [param position] needs to be shifted forward, which may have a noticeable performance cost, especially on larger arrays. </description> </method> <method name="is_empty" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if the array is empty. + Returns [code]true[/code] if the array is empty ([code][][/code]). See also [method size]. </description> </method> <method name="is_read_only" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if the array is read-only. See [method make_read_only]. Arrays are automatically read-only if declared with [code]const[/code] keyword. + Returns [code]true[/code] if the array is read-only. See [method make_read_only]. + In GDScript, arrays are automatically read-only if declared with the [code]const[/code] keyword. </description> </method> <method name="is_same_typed" qualifiers="const"> <return type="bool" /> <param index="0" name="array" type="Array" /> <description> - Returns [code]true[/code] if the array is typed the same as [param array]. + Returns [code]true[/code] if this array is typed the same as the given [param array]. See also [method is_typed]. </description> </method> <method name="is_typed" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if the array is typed. Typed arrays can only store elements of their associated type and provide type safety for the [code][][/code] operator. Methods of typed array still return [Variant]. + Returns [code]true[/code] if the array is typed. Typed arrays can only contain elements of a specific type, as defined by the typed array constructor. The methods of a typed array are still expected to return a generic [Variant]. + In GDScript, it is possible to define a typed array with static typing: + [codeblock] + var numbers: Array[float] = [0.2, 4.2, -2.0] + print(numbers.is_typed()) # Prints true + [/codeblock] </description> </method> <method name="make_read_only"> <return type="void" /> <description> - Makes the array read-only, i.e. disabled modifying of the array's elements. Does not apply to nested content, e.g. content of nested arrays. + Makes the array read-only. The array's elements cannot be overridden with different values, and their order cannot change. Does not apply to nested elements, such as dictionaries. + In GDScript, arrays are automatically read-only if declared with the [code]const[/code] keyword. </description> </method> <method name="map" qualifiers="const"> <return type="Array" /> <param index="0" name="method" type="Callable" /> <description> - Calls the provided [Callable] for each element in the array and returns a new array filled with values returned by the method. - The callable's method should take one [Variant] parameter (the current array element) and can return any [Variant]. + Calls the given [Callable] for each element in the array and returns a new array filled with values returned by the [param method]. + The [param method] should take one [Variant] parameter (the current array element) and can return any [Variant]. [codeblock] + func double(number): + return number * 2 + func _ready(): - print([1, 2, 3].map(negate)) # Prints [-1, -2, -3]. - print([1, 2, 3].map(func(number): return -number)) # Same as above, but using lambda function. + print([1, 2, 3].map(double)) # Prints [2, 4, 6] - func negate(number): - return -number + # Same as above, but using a lambda function. + print([1, 2, 3].map(func(element): return element * 2)) [/codeblock] See also [method filter], [method reduce], [method any] and [method all]. </description> @@ -476,61 +527,52 @@ <method name="max" qualifiers="const"> <return type="Variant" /> <description> - Returns the maximum value contained in the array if all elements are of comparable types. If the elements can't be compared, [code]null[/code] is returned. - To find the maximum value using a custom comparator, you can use [method reduce]. In this example every array element is checked and the first maximum value is returned: - [codeblock] - func _ready(): - var arr = [Vector2(0, 1), Vector2(2, 0), Vector2(1, 1), Vector2(1, 0), Vector2(0, 2)] - # In this example we compare the lengths. - print(arr.reduce(func(max, val): return val if is_length_greater(val, max) else max)) - - func is_length_greater(a, b): - return a.length() > b.length() - [/codeblock] + Returns the maximum value contained in the array, if all elements can be compared. Otherwise, returns [code]null[/code]. See also [method min]. + To find the maximum value using a custom comparator, you can use [method reduce]. </description> </method> <method name="min" qualifiers="const"> <return type="Variant" /> <description> - Returns the minimum value contained in the array if all elements are of comparable types. If the elements can't be compared, [code]null[/code] is returned. - See also [method max] for an example of using a custom comparator. + Returns the minimum value contained in the array, if all elements can be compared. Otherwise, returns [code]null[/code]. See also [method max]. </description> </method> <method name="pick_random" qualifiers="const"> <return type="Variant" /> <description> - Returns a random value from the target array. Prints an error and returns [code]null[/code] if the array is empty. + Returns a random element from the array. Generates an error and returns [code]null[/code] if the array is empty. [codeblocks] [gdscript] - var array: Array[int] = [1, 2, 3, 4] - print(array.pick_random()) # Prints either of the four numbers. + # May print 1, 2, 3.25, or "Hi". + print([1, 2, 3.25, "Hi"].pick_random()) [/gdscript] [csharp] - var array = new Godot.Collections.Array { 1, 2, 3, 4 }; - GD.Print(array.PickRandom()); // Prints either of the four numbers. + var array = new Godot.Collections.Array { 1, 2, 3.25f, "Hi" }; + GD.Print(array.PickRandom()); // May print 1, 2, 3.25, or "Hi". [/csharp] [/codeblocks] + [b]Note:[/b] Like many similar functions in the engine (such as [method @GlobalScope.randi] or [method shuffle]), this method uses a common, global random seed. To get a predictable outcome from this method, see [method @GlobalScope.seed]. </description> </method> <method name="pop_at"> <return type="Variant" /> <param index="0" name="position" type="int" /> <description> - Removes and returns the element of the array at index [param position]. If negative, [param position] is considered relative to the end of the array. Leaves the array unchanged and returns [code]null[/code] if the array is empty or if it's accessed out of bounds. An error message is printed when the array is accessed out of bounds, but not when the array is empty. - [b]Note:[/b] On large arrays, this method can be slower than [method pop_back] as it will reindex the array's elements that are located after the removed element. The larger the array and the lower the index of the removed element, the slower [method pop_at] will be. + Removes and returns the element of the array at index [param position]. If negative, [param position] is considered relative to the end of the array. Returns [code]null[/code] if the array is empty. If [param position] is out of bounds, an error message is also generated. + [b]Note:[/b] This method shifts every element's index after [param position] back, which may have a noticeable performance cost, especially on larger arrays. </description> </method> <method name="pop_back"> <return type="Variant" /> <description> - Removes and returns the last element of the array. Returns [code]null[/code] if the array is empty, without printing an error message. See also [method pop_front]. + Removes and returns the last element of the array. Returns [code]null[/code] if the array is empty, without generating an error. See also [method pop_front]. </description> </method> <method name="pop_front"> <return type="Variant" /> <description> - Removes and returns the first element of the array. Returns [code]null[/code] if the array is empty, without printing an error message. See also [method pop_back]. - [b]Note:[/b] On large arrays, this method is much slower than [method pop_back] as it will reindex all the array's elements every time it's called. The larger the array, the slower [method pop_front] will be. + Removes and returns the first element of the array. Returns [code]null[/code] if the array is empty, without generating an error. See also [method pop_back]. + [b]Note:[/b] This method shifts every other element's index back, which may have a noticeable performance cost, especially on larger arrays. </description> </method> <method name="push_back"> @@ -545,7 +587,7 @@ <param index="0" name="value" type="Variant" /> <description> Adds an element at the beginning of the array. See also [method push_back]. - [b]Note:[/b] On large arrays, this method is much slower than [method push_back] as it will reindex all the array's elements every time it's called. The larger the array, the slower [method push_front] will be. + [b]Note:[/b] This method shifts every other element's index forward, which may have a noticeable performance cost, especially on larger arrays. </description> </method> <method name="reduce" qualifiers="const"> @@ -553,15 +595,29 @@ <param index="0" name="method" type="Callable" /> <param index="1" name="accum" type="Variant" default="null" /> <description> - Calls the provided [Callable] for each element in array and accumulates the result in [param accum]. - The callable's method takes two arguments: the current value of [param accum] and the current array element. If [param accum] is [code]null[/code] (default value), the iteration will start from the second element, with the first one used as initial value of [param accum]. + Calls the given [Callable] for each element in array, accumulates the result in [param accum], then returns it. + The [param method] takes two arguments: the current value of [param accum] and the current array element. If [param accum] is [code]null[/code] (as by default), the iteration will start from the second element, with the first one used as initial value of [param accum]. [codeblock] - func _ready(): - print([1, 2, 3].reduce(sum, 10)) # Prints 16. - print([1, 2, 3].reduce(func(accum, number): return accum + number, 10)) # Same as above, but using lambda function. - func sum(accum, number): return accum + number + + func _ready(): + print([1, 2, 3].reduce(sum, 0)) # Prints 6 + print([1, 2, 3].reduce(sum, 10)) # Prints 16 + + # Same as above, but using a lambda function. + print([1, 2, 3].reduce(func(accum, number): return accum + number, 10)) + [/codeblock] + If [method max] is not desirable, this method may also be used to implement a custom comparator: + [codeblock] + func _ready(): + var arr = [Vector2(5, 0), Vector2(3, 4), Vector2(1, 2)] + + var longest_vec = arr.reduce(func(max, vec): return vec if is_length_greater(vec, max) else max) + print(longest_vec) # Prints Vector2(3, 4). + + func is_length_greater(a, b): + return a.length() > b.length() [/codeblock] See also [method map], [method filter], [method any] and [method all]. </description> @@ -570,25 +626,25 @@ <return type="void" /> <param index="0" name="position" type="int" /> <description> - Removes an element from the array by index. If the index does not exist in the array, nothing happens. To remove an element by searching for its value, use [method erase] instead. - [b]Note:[/b] This method acts in-place and doesn't return a modified array. - [b]Note:[/b] On large arrays, this method will be slower if the removed element is close to the beginning of the array (index 0). This is because all elements placed after the removed element have to be reindexed. - [b]Note:[/b] [param position] cannot be negative. To remove an element relative to the end of the array, use [code]arr.remove_at(arr.size() - (i + 1))[/code]. To remove the last element from the array without returning the value, use [code]arr.resize(arr.size() - 1)[/code]. + Removes the element from the array at the given index ([param position]). If the index is out of bounds, this method fails. + If you need to return the removed element, use [method pop_at]. To remove an element by value, use [method erase] instead. + [b]Note:[/b] This method shifts every element's index after [param position] back, which may have a noticeable performance cost, especially on larger arrays. + [b]Note:[/b] The [param position] cannot be negative. To remove an element relative to the end of the array, use [code]arr.remove_at(arr.size() - (i + 1))[/code]. To remove the last element from the array, use [code]arr.resize(arr.size() - 1)[/code]. </description> </method> <method name="resize"> <return type="int" /> <param index="0" name="size" type="int" /> <description> - Resizes the array to contain a different number of elements. If the array size is smaller, elements are cleared, if bigger, new elements are [code]null[/code]. Returns [constant OK] on success, or one of the other [enum Error] values if the operation failed. - Calling [method resize] once and assigning the new values is faster than adding new elements one by one. - [b]Note:[/b] This method acts in-place and doesn't return a modified array. + Sets the array's number of elements to [param size]. If [param size] is smaller than the array's current size, the elements at the end are removed. If [param size] is greater, new default elements (usually [code]null[/code]) are added, depending on the array's type. + Returns [constant OK] on success, or one of the other [enum Error] constants if this method fails. + [b]Note:[/b] Calling this method once and assigning the new values is faster than calling [method append] for every new element. </description> </method> <method name="reverse"> <return type="void" /> <description> - Reverses the order of the elements in the array. + Reverses the order of all elements in the array. </description> </method> <method name="rfind" qualifiers="const"> @@ -596,19 +652,20 @@ <param index="0" name="what" type="Variant" /> <param index="1" name="from" type="int" default="-1" /> <description> - Searches the array in reverse order. Optionally, a start search index can be passed. If negative, the start index is considered relative to the end of the array. + Returns the index of the [b]last[/b] occurrence of [param what] in this array, or [code]-1[/code] if there are none. The search's start can be specified with [param from], continuing to the beginning of the array. This method is the reverse of [method find]. </description> </method> <method name="shuffle"> <return type="void" /> <description> - Shuffles the array such that the items will have a random order. This method uses the global random number generator common to methods such as [method @GlobalScope.randi]. Call [method @GlobalScope.randomize] to ensure that a new seed will be used each time if you want non-reproducible shuffling. + Shuffles all elements of the array in a random order. + [b]Note:[/b] Like many similar functions in the engine (such as [method @GlobalScope.randi] or [method pick_random]), this method uses a common, global random seed. To get a predictable outcome from this method, see [method @GlobalScope.seed]. </description> </method> <method name="size" qualifiers="const"> <return type="int" /> <description> - Returns the number of elements in the array. + Returns the number of elements in the array. Empty arrays ([code][][/code]) always return [code]0[/code]. See also [method is_empty]. </description> </method> <method name="slice" qualifiers="const"> @@ -618,67 +675,71 @@ <param index="2" name="step" type="int" default="1" /> <param index="3" name="deep" type="bool" default="false" /> <description> - Returns the slice of the [Array], from [param begin] (inclusive) to [param end] (exclusive), as a new [Array]. - The absolute value of [param begin] and [param end] will be clamped to the array size, so the default value for [param end] makes it slice to the size of the array by default (i.e. [code]arr.slice(1)[/code] is a shorthand for [code]arr.slice(1, arr.size())[/code]). - If either [param begin] or [param end] are negative, they will be relative to the end of the array (i.e. [code]arr.slice(0, -2)[/code] is a shorthand for [code]arr.slice(0, arr.size() - 2)[/code]). - If specified, [param step] is the relative index between source elements. It can be negative, then [param begin] must be higher than [param end]. For example, [code][0, 1, 2, 3, 4, 5].slice(5, 1, -2)[/code] returns [code][5, 3][/code]. - If [param deep] is true, each element will be copied by value rather than by reference. - [b]Note:[/b] To include the first element when [param step] is negative, use [code]arr.slice(begin, -arr.size() - 1, step)[/code] (i.e. [code][0, 1, 2].slice(1, -4, -1)[/code] returns [code][1, 0][/code]). + Returns a new [Array] containing this array's elements, from index [param begin] (inclusive) to [param end] (exclusive), every [param step] elements. + If either [param begin] or [param end] are negative, their value is relative to the end of the array. + If [param step] is negative, this method iterates through the array in reverse, returning a slice ordered backwards. For this to work, [param begin] must be greater than [param end]. + If [param deep] is [code]true[/code], all nested [Array] and [Dictionary] elements in the slice are duplicated from the original, recursively. See also [method duplicate]). + [codeblock] + var letters = ["A", "B", "C", "D", "E", "F"] + + print(letters.slice(0, 2)) # Prints ["A", "B"] + print(letters.slice(2, -2)) # Prints ["C", "D"] + print(letters.slice(-2, 6)) # Prints ["E", "F"] + + print(letters.slice(0, 6, 2)) # Prints ["A", "C", "E"] + print(letters.slice(4, 1, -1)) # Prints ["E", "D", "C"] + [/codeblock] </description> </method> <method name="sort"> <return type="void" /> <description> - Sorts the array. - [b]Note:[/b] The sorting algorithm used is not [url=https://en.wikipedia.org/wiki/Sorting_algorithm#Stability]stable[/url]. This means that values considered equal may have their order changed when using [method sort]. - [b]Note:[/b] Strings are sorted in alphabetical order (as opposed to natural order). This may lead to unexpected behavior when sorting an array of strings ending with a sequence of numbers. Consider the following example: + Sorts the array in ascending order. The final order is dependent on the "less than" ([code]>[/code]) comparison between elements. [codeblocks] [gdscript] - var strings = ["string1", "string2", "string10", "string11"] - strings.sort() - print(strings) # Prints [string1, string10, string11, string2] + var numbers = [10, 5, 2.5, 8] + numbers.sort() + print(numbers) # Prints [2.5, 5, 8, 10] [/gdscript] [csharp] - var strings = new Godot.Collections.Array { "string1", "string2", "string10", "string11" }; - strings.Sort(); - GD.Print(strings); // Prints [string1, string10, string11, string2] + var numbers = new Godot.Collections.Array { 10, 5, 2.5, 8 }; + numbers.Sort(); + GD.Print(numbers); // Prints [2.5, 5, 8, 10] [/csharp] [/codeblocks] - To perform natural order sorting, you can use [method sort_custom] with [method String.naturalnocasecmp_to] as follows: - [codeblock] - var strings = ["string1", "string2", "string10", "string11"] - strings.sort_custom(func(a, b): return a.naturalnocasecmp_to(b) < 0) - print(strings) # Prints [string1, string2, string10, string11] - [/codeblock] + [b]Note:[/b] The sorting algorithm used is not [url=https://en.wikipedia.org/wiki/Sorting_algorithm#Stability]stable[/url]. This means that equivalent elements (such as [code]2[/code] and [code]2.0[/code]) may have their order changed when calling [method sort]. </description> </method> <method name="sort_custom"> <return type="void" /> <param index="0" name="func" type="Callable" /> <description> - Sorts the array using a custom method. The custom method receives two arguments (a pair of elements from the array) and must return either [code]true[/code] or [code]false[/code]. For two elements [code]a[/code] and [code]b[/code], if the given method returns [code]true[/code], element [code]b[/code] will be after element [code]a[/code] in the array. - [b]Note:[/b] The sorting algorithm used is not [url=https://en.wikipedia.org/wiki/Sorting_algorithm#Stability]stable[/url]. This means that values considered equal may have their order changed when using [method sort_custom]. - [b]Note:[/b] You cannot randomize the return value as the heapsort algorithm expects a deterministic result. Randomizing the return value will result in unexpected behavior. - [codeblocks] - [gdscript] + Sorts the array using a custom [Callable]. + [param func] is called as many times as necessary, receiving two array elements as arguments. The function should return [code]true[/code] if the first element should be moved [i]behind[/i] the second one, otherwise it should return [code]false[/code]. + [codeblock] func sort_ascending(a, b): - if a[0] < b[0]: + if a[1] < b[1]: return true return false func _ready(): - var my_items = [[5, "Potato"], [9, "Rice"], [4, "Tomato"]] + var my_items = [["Tomato", 5], ["Apple", 9], ["Rice", 4]] my_items.sort_custom(sort_ascending) - print(my_items) # Prints [[4, Tomato], [5, Potato], [9, Rice]]. + print(my_items) # Prints [["Rice", 4], ["Tomato", 5], ["Apple", 9]] - # Descending, lambda version. + # Sort descending, using a lambda function. my_items.sort_custom(func(a, b): return a[0] > b[0]) - print(my_items) # Prints [[9, Rice], [5, Potato], [4, Tomato]]. - [/gdscript] - [csharp] - // There is no custom sort support for Godot.Collections.Array - [/csharp] - [/codeblocks] + print(my_items) # Prints [["Apple", 9], ["Tomato", 5], ["Rice", 4]] + [/codeblock] + It may also be necessary to use this method to sort strings by natural order, with [method String.naturalnocasecmp_to], as in the following example: + [codeblock] + var files = ["newfile1", "newfile2", "newfile10", "newfile11"] + files.sort_custom(func(a, b): return a.naturalnocasecmp_to(b) < 0) + print(files) # Prints ["newfile1", "newfile2", "newfile10", "newfile11"] + [/codeblock] + [b]Note:[/b] In C#, this method is not supported. + [b]Note:[/b] The sorting algorithm used is not [url=https://en.wikipedia.org/wiki/Sorting_algorithm#Stability]stable[/url]. This means that values considered equal may have their order changed when calling this method. + [b]Note:[/b] You should not randomize the return value of [param func], as the heapsort algorithm expects a consistent result. Randomizing the return value will result in unexpected behavior. </description> </method> </methods> @@ -687,28 +748,44 @@ <return type="bool" /> <param index="0" name="right" type="Array" /> <description> - Compares the left operand [Array] against the [param right] [Array]. Returns [code]true[/code] if the sizes or contents of the arrays are [i]not[/i] equal, [code]false[/code] otherwise. + Returns [code]true[/code] if the array's size or its elements are different than [param right]'s. </description> </operator> <operator name="operator +"> <return type="Array" /> <param index="0" name="right" type="Array" /> <description> - Concatenates two [Array]s together, with the [param right] [Array] being added to the end of the [Array] specified in the left operand. For example, [code][1, 2] + [3, 4][/code] results in [code][1, 2, 3, 4][/code]. + Appends the [param right] array to the left operand, creating a new [Array]. This is also known as an array concatenation. + [codeblocks] + [gdscript] + var array1 = ["One", 2] + var array2 = [3, "Four"] + print(array1 + array2) # Prints ["One", 2, 3, "Four"] + [/gdscript] + [csharp] + // Note that concatenation is not possible with C#'s native Array type. + var array1 = new Godot.Collections.Array{"One", 2}; + var array2 = new Godot.Collections.Array{3, "Four"}; + GD.Print(array1 + array2); // Prints ["One", 2, 3, "Four"] + [/csharp] + [/codeblocks] + [b]Note:[/b] For existing arrays, [method append_array] is much more efficient than concatenation and assignment with the [code]+=[/code] operator. </description> </operator> <operator name="operator <"> <return type="bool" /> <param index="0" name="right" type="Array" /> <description> - Performs a comparison for each index between the left operand [Array] and the [param right] [Array], considering the highest common index of both arrays for this comparison: Returns [code]true[/code] on the first occurrence of an element that is less, or [code]false[/code] if the element is greater. Note that depending on the type of data stored, this function may be recursive. If all elements are equal, it compares the length of both arrays and returns [code]false[/code] if the left operand [Array] has fewer elements, otherwise it returns [code]true[/code]. + Compares the elements of both arrays in order, starting from index [code]0[/code] and ending on the last index in common between both arrays. For each pair of elements, returns [code]true[/code] if this array's element is less than [param right]'s, [code]false[/code] if this element is greater. Otherwise, continues to the next pair. + If all searched elements are equal, returns [code]true[/code] if this array's size is less than [param right]'s, otherwise returns [code]false[/code]. </description> </operator> <operator name="operator <="> <return type="bool" /> <param index="0" name="right" type="Array" /> <description> - Performs a comparison for each index between the left operand [Array] and the [param right] [Array], considering the highest common index of both arrays for this comparison: Returns [code]true[/code] on the first occurrence of an element that is less, or [code]false[/code] if the element is greater. Note that depending on the type of data stored, this function may be recursive. If all elements are equal, it compares the length of both arrays and returns [code]true[/code] if the left operand [Array] has the same number of elements or fewer, otherwise it returns [code]false[/code]. + Compares the elements of both arrays in order, starting from index [code]0[/code] and ending on the last index in common between both arrays. For each pair of elements, returns [code]true[/code] if this array's element is less than [param right]'s, [code]false[/code] if this element is greater. Otherwise, continues to the next pair. + If all searched elements are equal, returns [code]true[/code] if this array's size is less or equal to [param right]'s, otherwise returns [code]false[/code]. </description> </operator> <operator name="operator =="> @@ -722,21 +799,23 @@ <return type="bool" /> <param index="0" name="right" type="Array" /> <description> - Performs a comparison for each index between the left operand [Array] and the [param right] [Array], considering the highest common index of both arrays for this comparison: Returns [code]true[/code] on the first occurrence of an element that is greater, or [code]false[/code] if the element is less. Note that depending on the type of data stored, this function may be recursive. If all elements are equal, it compares the length of both arrays and returns [code]true[/code] if the [param right] [Array] has more elements, otherwise it returns [code]false[/code]. + Compares the elements of both arrays in order, starting from index [code]0[/code] and ending on the last index in common between both arrays. For each pair of elements, returns [code]true[/code] if this array's element is greater than [param right]'s, [code]false[/code] if this element is less. Otherwise, continues to the next pair. + If all searched elements are equal, returns [code]true[/code] if this array's size is greater than [param right]'s, otherwise returns [code]false[/code]. </description> </operator> <operator name="operator >="> <return type="bool" /> <param index="0" name="right" type="Array" /> <description> - Performs a comparison for each index between the left operand [Array] and the [param right] [Array], considering the highest common index of both arrays for this comparison: Returns [code]true[/code] on the first occurrence of an element that is greater, or [code]false[/code] if the element is less. Note that depending on the type of data stored, this function may be recursive. If all elements are equal, it compares the length of both arrays and returns [code]true[/code] if the [param right] [Array] has more or the same number of elements, otherwise it returns [code]false[/code]. + Compares the elements of both arrays in order, starting from index [code]0[/code] and ending on the last index in common between both arrays. For each pair of elements, returns [code]true[/code] if this array's element is greater than [param right]'s, [code]false[/code] if this element is less. Otherwise, continues to the next pair. + If all searched elements are equal, returns [code]true[/code] if this array's size is greater or equal to [param right]'s, otherwise returns [code]false[/code]. </description> </operator> <operator name="operator []"> <return type="Variant" /> <param index="0" name="index" type="int" /> <description> - Returns a reference to the element of type [Variant] at the specified location. Arrays start at index 0. [param index] can be a zero or positive value to start from the beginning, or a negative value to start from the end. Out-of-bounds array access causes a run-time error, which will result in an error being printed and the project execution pausing if run from the editor. + Returns the [Variant] element at the specified [param index]. Arrays start at index 0. If [param index] is greater or equal to [code]0[/code], the element is fetched starting from the beginning of the array. If [param index] is a negative value, the element is fetched starting from the end. Accessing an array out-of-bounds will cause a run-time error, pausing the project execution if run from the editor. </description> </operator> </operators> diff --git a/doc/classes/ArrayMesh.xml b/doc/classes/ArrayMesh.xml index 0f6bf89cd7..c80dabb8c0 100644 --- a/doc/classes/ArrayMesh.xml +++ b/doc/classes/ArrayMesh.xml @@ -206,7 +206,8 @@ Overrides the [AABB] with one defined by user for use with frustum culling. Especially useful to avoid unexpected culling when using a shader to offset vertices. </member> <member name="shadow_mesh" type="ArrayMesh" setter="set_shadow_mesh" getter="get_shadow_mesh"> - An optional mesh which is used for rendering shadows and can be used for the depth prepass. Can be used to increase performance of shadow rendering by using a mesh that only contains vertex position data (without normals, UVs, colors, etc.). + An optional mesh which can be used for rendering shadows and the depth prepass. Can be used to increase performance by supplying a mesh with fused vertices and only vertex position data (without normals, UVs, colors, etc.). + [b]Note:[/b] This mesh must have exactly the same vertex positions as the source mesh (including the source mesh's LODs, if present). If vertex positions differ, then the mesh will not draw correctly. </member> </members> </class> diff --git a/doc/classes/AtlasTexture.xml b/doc/classes/AtlasTexture.xml index cea8e13f4c..45877f4003 100644 --- a/doc/classes/AtlasTexture.xml +++ b/doc/classes/AtlasTexture.xml @@ -21,7 +21,7 @@ The margin around the [member region]. Useful for small adjustments. If the [member Rect2.size] of this property ("w" and "h" in the editor) is set, the drawn texture is resized to fit within the margin. </member> <member name="region" type="Rect2" setter="set_region" getter="get_region" default="Rect2(0, 0, 0, 0)"> - The region used to draw the [member atlas]. + The region used to draw the [member atlas]. If either dimension of the region's size is [code]0[/code], the value from [member atlas] size will be used for that axis instead. </member> <member name="resource_local_to_scene" type="bool" setter="set_local_to_scene" getter="is_local_to_scene" overrides="Resource" default="false" /> </members> diff --git a/doc/classes/Basis.xml b/doc/classes/Basis.xml index 41bda1033d..322d2ab9d4 100644 --- a/doc/classes/Basis.xml +++ b/doc/classes/Basis.xml @@ -8,7 +8,7 @@ A [Basis] is composed by 3 axis vectors, each representing a column of the matrix: [member x], [member y], and [member z]. The length of each axis ([method 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 [b]orthogonal[/b] if its axes are perpendicular to each other. A basis is [b]normalized[/b] if the length of every axis is [code]1[/code]. A basis is [b]uniform[/b] if all axes share the same length (see [method get_scale]). A basis is [b]orthonormal[/b] if it is both orthogonal and normalized, which allows it to only represent rotations. A basis is [b]conformal[/b] if it is both orthogonal and uniform, which ensures it is not distorted. For a general introduction, see the [url=$DOCS_URL/tutorials/math/matrices_and_transforms.html]Matrices and transforms[/url] tutorial. - [b]Note:[/b] Godot uses a [url=https://en.wikipedia.org/wiki/Right-hand_rule]right-handed coordinate system[/url], which is a common standard. For directions, the convention for built-in types like [Camera3D] is for -Z to point forward (+X is right, +Y is up, and +Z is back). Other objects may use different direction conventions. For more information, see the [url=$DOCS_URL/tutorials/assets_pipeline/importing_scenes.html#d-asset-direction-conventions]Importing 3D Scenes[/url] tutorial. + [b]Note:[/b] Godot uses a [url=https://en.wikipedia.org/wiki/Right-hand_rule]right-handed coordinate system[/url], which is a common standard. For directions, the convention for built-in types like [Camera3D] is for -Z to point forward (+X is right, +Y is up, and +Z is back). Other objects may use different direction conventions. For more information, see the [url=$DOCS_URL/tutorials/assets_pipeline/importing_3d_scenes/model_export_considerations.html#d-asset-direction-conventions]3D asset direction conventions[/url] tutorial. [b]Note:[/b] The basis matrices are exposed as [url=https://www.mindcontrol.org/~hplus/graphics/matrix-layout.html]column-major[/url] order, which is the same as OpenGL. However, they are stored internally in row-major order, which is the same as DirectX. </description> <tutorials> diff --git a/doc/classes/Button.xml b/doc/classes/Button.xml index 98f25ed573..68fb918904 100644 --- a/doc/classes/Button.xml +++ b/doc/classes/Button.xml @@ -119,7 +119,7 @@ Icon modulate [Color] used when the [Button] is being pressed. </theme_item> <theme_item name="align_to_largest_stylebox" data_type="constant" type="int" default="0"> - This constant acts as a boolean. If [code]true[/code], text and icon are always aligned to the largest stylebox margins, otherwise it's aligned to the current button state stylebox margins. + This constant acts as a boolean. If [code]true[/code], the minimum size of the button and text/icon alignment is always based on the largest stylebox margins, otherwise it's based on the current button state stylebox margins. </theme_item> <theme_item name="h_separation" data_type="constant" type="int" default="4"> The horizontal space between [Button]'s icon and text. Negative values will be treated as [code]0[/code] when used. diff --git a/doc/classes/CanvasItem.xml b/doc/classes/CanvasItem.xml index 207045b065..186ee1b9c4 100644 --- a/doc/classes/CanvasItem.xml +++ b/doc/classes/CanvasItem.xml @@ -525,6 +525,7 @@ <return type="bool" /> <description> Returns [code]true[/code] if the node is present in the [SceneTree], its [member visible] property is [code]true[/code] and all its ancestors are also visible. If any ancestor is hidden, this node will not be visible in the scene tree, and is therefore not drawn (see [method _draw]). + Visibility is checked only in parent nodes that inherit from [CanvasItem], [CanvasLayer], and [Window]. If the parent is of any other type (such as [Node], [AnimationPlayer], or [Node3D]), it is assumed to be visible. </description> </method> <method name="make_canvas_position_local" qualifiers="const"> @@ -623,8 +624,8 @@ [b]Note:[/b] For controls that inherit [Popup], the correct way to make them visible is to call one of the multiple [code]popup*()[/code] functions instead. </member> <member name="y_sort_enabled" type="bool" setter="set_y_sort_enabled" getter="is_y_sort_enabled" default="false"> - If [code]true[/code], this and child [CanvasItem] nodes with a lower Y position are rendered in front of nodes with a higher Y position. If [code]false[/code], 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. + If [code]true[/code], this and child [CanvasItem] nodes with a higher Y position are rendered in front of nodes with a lower Y position. If [code]false[/code], 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. Nodes sort relative to each other only if they are on the same [member z_index]. </member> <member name="z_as_relative" type="bool" setter="set_z_as_relative" getter="is_z_relative" default="true"> diff --git a/doc/classes/DisplayServer.xml b/doc/classes/DisplayServer.xml index ff1c390b3c..0bed5288bd 100644 --- a/doc/classes/DisplayServer.xml +++ b/doc/classes/DisplayServer.xml @@ -20,6 +20,7 @@ <return type="Image" /> <description> Returns the user's clipboard as an image if possible. + [b]Note:[/b] This method uses the copied pixel data, e.g. from a image editing software or a web browser, not an image file copied from file explorer. </description> </method> <method name="clipboard_get_primary" qualifiers="const"> @@ -879,6 +880,12 @@ Registers callables to emit when the menu is respectively about to show or closed. Callback methods should have zero arguments. </description> </method> + <method name="has_additional_outputs" qualifiers="const"> + <return type="bool" /> + <description> + Returns [code]true[/code] if any additional outputs have been registered via [method register_additional_output]. + </description> + </method> <method name="has_feature" qualifiers="const"> <return type="bool" /> <param index="0" name="feature" type="int" enum="DisplayServer.Feature" /> @@ -1022,6 +1029,14 @@ Perform window manager processing, including input flushing. See also [method force_process_and_drop_events], [method Input.flush_buffered_events] and [member Input.use_accumulated_input]. </description> </method> + <method name="register_additional_output"> + <return type="void" /> + <param index="0" name="object" type="Object" /> + <description> + Registers an [Object] which represents an additional output that will be rendered too, beyond normal windows. The [Object] is only used as an identifier, which can be later passed to [method unregister_additional_output]. + This can be used to prevent Godot from skipping rendering when no normal windows are visible. + </description> + </method> <method name="screen_get_dpi" qualifiers="const"> <return type="int" /> <param index="0" name="screen" type="int" default="-1" /> @@ -1352,6 +1367,13 @@ [b]Note:[/b] [member ProjectSettings.audio/general/text_to_speech] should be [code]true[/code] to use text-to-speech. </description> </method> + <method name="unregister_additional_output"> + <return type="void" /> + <param index="0" name="object" type="Object" /> + <description> + Unregisters an [Object] representing an additional output, that was registered via [method register_additional_output]. + </description> + </method> <method name="virtual_keyboard_get_height" qualifiers="const"> <return type="int" /> <description> diff --git a/doc/classes/EditorExportPlugin.xml b/doc/classes/EditorExportPlugin.xml index 3e2b3ea111..9ef911a68d 100644 --- a/doc/classes/EditorExportPlugin.xml +++ b/doc/classes/EditorExportPlugin.xml @@ -17,7 +17,7 @@ <param index="1" name="features" type="PackedStringArray" /> <description> Return [code]true[/code] if this plugin will customize resources based on the platform and features used. - When enabled, [method _get_customization_configuration_hash], [method _customize_resource] and [method _customize_scene] will be called and must be implemented. + When enabled, [method _get_customization_configuration_hash] and [method _customize_resource] will be called and must be implemented. </description> </method> <method name="_begin_customize_scenes" qualifiers="virtual const"> @@ -25,7 +25,8 @@ <param index="0" name="platform" type="EditorExportPlatform" /> <param index="1" name="features" type="PackedStringArray" /> <description> - Return true if this plugin will customize scenes based on the platform and features used. + Return [code]true[/code] if this plugin will customize scenes based on the platform and features used. + When enabled, [method _get_customization_configuration_hash] and [method _customize_scene] will be called and must be implemented. </description> </method> <method name="_customize_resource" qualifiers="virtual"> @@ -81,7 +82,7 @@ <param index="1" name="type" type="String" /> <param index="2" name="features" type="PackedStringArray" /> <description> - Virtual method to be overridden by the user. Called for each exported file, providing arguments that can be used to identify the file. [param path] is the path of the file, [param type] is the [Resource] represented by the file (e.g. [PackedScene]) and [param features] is the list of features for the export. + Virtual method to be overridden by the user. Called for each exported file before [method _customize_resource] and [method _customize_scene]. The arguments can be used to identify the file. [param path] is the path of the file, [param type] is the [Resource] represented by the file (e.g. [PackedScene]), and [param features] is the list of features for the export. Calling [method skip] inside this callback will make the file not included in the export. </description> </method> @@ -231,6 +232,7 @@ <description> Adds a custom file to be exported. [param path] is the virtual path that can be used to load the file, [param file] is the binary data of the file. When called inside [method _export_file] and [param remap] is [code]true[/code], the current file will not be exported, but instead remapped to this custom file. [param remap] is ignored when called in other places. + [param file] will not be imported, so consider using [method _customize_resource] to remap imported resources. </description> </method> <method name="add_ios_bundle_file"> @@ -313,7 +315,7 @@ <method name="skip"> <return type="void" /> <description> - To be called inside [method _export_file], [method _customize_resource], or [method _customize_scene]. Skips the current file, so it's not included in the export. + To be called inside [method _export_file]. Skips the current file, so it's not included in the export. </description> </method> </methods> diff --git a/doc/classes/EditorFileSystem.xml b/doc/classes/EditorFileSystem.xml index 08b40c7800..06fa4be2c8 100644 --- a/doc/classes/EditorFileSystem.xml +++ b/doc/classes/EditorFileSystem.xml @@ -84,6 +84,12 @@ Emitted if a resource is reimported. </description> </signal> + <signal name="resources_reimporting"> + <param index="0" name="resources" type="PackedStringArray" /> + <description> + Emitted before a resource is reimported. + </description> + </signal> <signal name="resources_reload"> <param index="0" name="resources" type="PackedStringArray" /> <description> diff --git a/doc/classes/EditorPlugin.xml b/doc/classes/EditorPlugin.xml index 89b9e7d6c2..c3ea440aea 100644 --- a/doc/classes/EditorPlugin.xml +++ b/doc/classes/EditorPlugin.xml @@ -444,7 +444,7 @@ <param index="2" name="script" type="Script" /> <param index="3" name="icon" type="Texture2D" /> <description> - Adds a custom type, which will appear in the list of nodes or resources. An icon can be optionally passed. + Adds a custom type, which will appear in the list of nodes or resources. When a given node or resource is selected, the base type will be instantiated (e.g. "Node3D", "Control", "Resource"), then the script will be loaded and set to this object. [b]Note:[/b] The base type is the base engine class which this type's class hierarchy inherits, not any custom type parent classes. You can use the virtual method [method _handles] to check if your custom object is being edited by checking the script or using the [code]is[/code] keyword. diff --git a/doc/classes/EditorSettings.xml b/doc/classes/EditorSettings.xml index b4c1647dde..e4dab85038 100644 --- a/doc/classes/EditorSettings.xml +++ b/doc/classes/EditorSettings.xml @@ -396,6 +396,10 @@ <member name="editors/animation/autorename_animation_tracks" type="bool" setter="" getter=""> If [code]true[/code], automatically updates animation tracks' target paths when renaming or reparenting nodes in the Scene tree dock. </member> + <member name="editors/animation/confirm_insert_track" type="bool" setter="" getter=""> + If [code]true[/code], display a confirmation dialog when adding a new track to an animation by pressing the "key" icon next to a property. Holding Shift will bypass the dialog. + If [code]false[/code], the behavior is reversed, i.e. the dialog only appears when Shift is held. + </member> <member name="editors/animation/default_create_bezier_tracks" type="bool" setter="" getter=""> If [code]true[/code], create a Bezier track instead of a standard track when pressing the "key" icon next to a property. Bezier tracks provide more control over animation curves, but are more difficult to adjust quickly. </member> @@ -592,6 +596,16 @@ The path to the directory containing the Open Image Denoise (OIDN) executable, used optionally for denoising lightmaps. It can be downloaded from [url=https://www.openimagedenoise.org/downloads.html]openimagedenoise.org[/url]. To enable this feature for your specific project, use [member ProjectSettings.rendering/lightmapping/denoising/denoiser]. </member> + <member name="input/buffering/agile_event_flushing" type="bool" setter="" getter=""> + If [code]true[/code], input events will be flushed just before every idle and physics frame. + If [code]false[/code], these events will be flushed only once per process frame, between iterations of the engine. + Enabling this setting can greatly improve input responsiveness, especially in devices that struggle to run at the project's intended frame rate. + </member> + <member name="input/buffering/use_accumulated_input" type="bool" setter="" getter=""> + If [code]true[/code], similar input events sent by the operating system are accumulated. When input accumulation is enabled, all input events generated during a frame will be merged and emitted when the frame is done rendering. Therefore, this limits the number of input method calls per second to the rendering FPS. + Input accumulation can be disabled to get slightly more precise/reactive input at the cost of increased CPU usage. + [b]Note:[/b] Input accumulation is [i]enabled[/i] by default. + </member> <member name="interface/editor/accept_dialog_cancel_ok_buttons" type="int" setter="" getter=""> How to position the Cancel and OK buttons in the editor's [AcceptDialog]s. Different platforms have different standard behaviors for this, which can be overridden using this setting. This is useful if you use Godot both on Windows and macOS/Linux and your Godot muscle memory is stronger than your OS specific one. - [b]Auto[/b] follows the platform convention: Cancel first on macOS and Linux, OK first on Windows. @@ -1044,7 +1058,7 @@ [b]Note:[/b] The [url=$DOCS_URL/tutorials/scripting/gdscript/gdscript_styleguide.html]GDScript style guide[/url] recommends using tabs for indentation. It is advised to change this setting only if you need to work on a project that currently uses spaces for indentation. </member> <member name="text_editor/behavior/navigation/custom_word_separators" type="String" setter="" getter=""> - The characters to consider as word delimiters if [member text_editor/behavior/navigation/use_custom_word_separators] is [code]true[/code]. The characters should be defined without separation, for example [code]#_![/code]. + The characters to consider as word delimiters if [member text_editor/behavior/navigation/use_custom_word_separators] is [code]true[/code]. This is in addition to default characters if [member text_editor/behavior/navigation/use_default_word_separators] is [code]true[/code]. The characters should be defined without separation, for example [code]_♥=[/code]. </member> <member name="text_editor/behavior/navigation/drag_and_drop_selection" type="bool" setter="" getter=""> If [code]true[/code], allows drag-and-dropping text in the script editor to move text. Disable this if you find yourself accidentally drag-and-dropping text in the script editor. @@ -1066,10 +1080,10 @@ If [code]true[/code], prevents automatically switching between the Script and 2D/3D screens when selecting a node in the Scene tree dock. </member> <member name="text_editor/behavior/navigation/use_custom_word_separators" type="bool" setter="" getter=""> - If [code]false[/code], using [kbd]Ctrl + Left[/kbd] or [kbd]Ctrl + Right[/kbd] ([kbd]Cmd + Left[/kbd] or [kbd]Cmd + Right[/kbd] on macOS) bindings will use the behavior of [member text_editor/behavior/navigation/use_default_word_separators]. If [code]true[/code], it will also stop the caret if a character within [member text_editor/behavior/navigation/custom_word_separators] is detected. Useful for subword moving. This behavior also will be applied to the behavior of text selection. + If [code]true[/code], uses the characters in [member text_editor/behavior/navigation/custom_word_separators] as word separators for word navigation and operations. This is in addition to the default characters if [member text_editor/behavior/navigation/use_default_word_separators] is also enabled. Word navigation and operations include double-clicking on a word or holding [kbd]Ctrl[/kbd] ([kbd]Cmd[/kbd] on macOS) while pressing [kbd]left[/kbd], [kbd]right[/kbd], [kbd]backspace[/kbd], or [kbd]delete[/kbd]. </member> <member name="text_editor/behavior/navigation/use_default_word_separators" type="bool" setter="" getter=""> - If [code]false[/code], using [kbd]Ctrl + Left[/kbd] or [kbd]Ctrl + Right[/kbd] ([kbd]Cmd + Left[/kbd] or [kbd]Cmd + Right[/kbd] on macOS) bindings will stop moving caret only if a space or punctuation is detected. If [code]true[/code], it will also stop the caret if a character is part of [code]`!"#$%&'()*+,-./:;<=>?@[\]^`{|}~[/code], the Unicode General Punctuation table, or the Unicode CJK Punctuation table. Useful for subword moving. This behavior also will be applied to the behavior of text selection. + If [code]true[/code], uses the characters in [code]`!"#$%&'()*+,-./:;<=>?@[\]^`{|}~[/code], the Unicode General Punctuation table, and the Unicode CJK Punctuation table as word separators for word navigation and operations. If [code]false[/code], a subset of these characters are used and does not include the characters [code]<>$~^=+|[/code]. This is in addition to custom characters if [member text_editor/behavior/navigation/use_custom_word_separators] is also enabled. These characters are used to determine where a word stops. Word navigation and operations include double-clicking on a word or holding [kbd]Ctrl[/kbd] ([kbd]Cmd[/kbd] on macOS) while pressing [kbd]left[/kbd], [kbd]right[/kbd], [kbd]backspace[/kbd], or [kbd]delete[/kbd]. </member> <member name="text_editor/behavior/navigation/v_scroll_speed" type="int" setter="" getter=""> The number of pixels to scroll with every mouse wheel increment. Higher values make the script scroll by faster when using the mouse wheel. @@ -1091,7 +1105,7 @@ The delay in seconds after which autocompletion suggestions should be displayed when the user stops typing. </member> <member name="text_editor/completion/code_complete_enabled" type="bool" setter="" getter=""> - If [code]true[/code], code completion will be triggered automatically after [member text_editor/completion/code_complete_delay]. If [code]false[/code], you can still trigger completion manually by pressing [kbd]Ctrl + Space[/kbd] ([kbd]Cmd + Space[/kbd] on macOS). + If [code]true[/code], code completion will be triggered automatically after [member text_editor/completion/code_complete_delay]. Even if [code]false[/code], code completion can be triggered manually with the [code]ui_text_completion_query[/code] action (by default [kbd]Ctrl + Space[/kbd] or [kbd]Cmd + Space[/kbd] on macOS). </member> <member name="text_editor/completion/colorize_suggestions" type="bool" setter="" getter=""> If [code]true[/code] enables the coloring for some items in the autocompletion suggestions, like vector components. diff --git a/doc/classes/FileDialog.xml b/doc/classes/FileDialog.xml index dec3160ffe..38985e99ae 100644 --- a/doc/classes/FileDialog.xml +++ b/doc/classes/FileDialog.xml @@ -80,12 +80,14 @@ <description> Returns the vertical box container of the dialog, custom controls can be added to it. [b]Warning:[/b] This is a required internal node, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their [member CanvasItem.visible] property. + [b]Note:[/b] Changes to this node are ignored by native file dialogs, use [method add_option] to add custom elements to the dialog instead. </description> </method> <method name="invalidate"> <return type="void" /> <description> Invalidate and update the current dialog content list. + [b]Note:[/b] This method does nothing on native file dialogs. </description> </method> <method name="set_option_default"> @@ -116,10 +118,11 @@ <members> <member name="access" type="int" setter="set_access" getter="get_access" enum="FileDialog.Access" default="0"> The file system access scope. See [enum Access] constants. - [b]Warning:[/b] Currently, in sandboxed environments such as Web builds or sandboxed macOS apps, FileDialog cannot access the host file system. See [url=https://github.com/godotengine/godot-proposals/issues/1123]godot-proposals#1123[/url]. + [b]Warning:[/b] In Web builds, FileDialog cannot access the host file system. In sandboxed Linux and macOS environments, [member use_native_dialog] is automatically used to allow limited access to host file system. </member> <member name="current_dir" type="String" setter="set_current_dir" getter="get_current_dir"> The current working directory of the file dialog. + [b]Note:[/b] For native file dialogs, this property is only treated as a hint and may not be respected by specific OS implementations. </member> <member name="current_file" type="String" setter="set_current_file" getter="get_current_file"> The currently selected file of the file dialog. @@ -142,14 +145,18 @@ </member> <member name="root_subfolder" type="String" setter="set_root_subfolder" getter="get_root_subfolder" default=""""> If non-empty, the given sub-folder will be "root" of this [FileDialog], i.e. user won't be able to go to its parent directory. + [b]Note:[/b] This property is ignored by native file dialogs. </member> <member name="show_hidden_files" type="bool" setter="set_show_hidden_files" getter="is_showing_hidden_files" default="false"> If [code]true[/code], the dialog will show hidden files. + [b]Note:[/b] This property is ignored by native file dialogs on Linux. </member> <member name="title" type="String" setter="set_title" getter="get_title" overrides="Window" default=""Save a File"" /> <member name="use_native_dialog" type="bool" setter="set_use_native_dialog" getter="get_use_native_dialog" default="false"> If [code]true[/code], [member access] is set to [constant ACCESS_FILESYSTEM], and it is supported by the current [DisplayServer], OS native dialog will be used instead of custom one. - [b]Note:[/b] On macOS, sandboxed apps always use native dialogs to access host filesystem. + [b]Note:[/b] On Linux and macOS, sandboxed apps always use native dialogs to access the host file system. + [b]Note:[/b] On macOS, sandboxed apps will save security-scoped bookmarks to retain access to the opened folders across multiple sessions. Use [method OS.get_granted_permissions] to get a list of saved bookmarks. + [b]Note:[/b] Native dialogs are isolated from the base process, file dialog properties can't be modified once the dialog is shown. </member> </members> <signals> diff --git a/doc/classes/GraphEdit.xml b/doc/classes/GraphEdit.xml index 001839d745..670df10a89 100644 --- a/doc/classes/GraphEdit.xml +++ b/doc/classes/GraphEdit.xml @@ -7,6 +7,7 @@ [GraphEdit] provides tools for creation, manipulation, and display of various graphs. Its main purpose in the engine is to power the visual programming systems, such as visual shaders, but it is also available for use in user projects. [GraphEdit] by itself is only an empty container, representing an infinite grid where [GraphNode]s can be placed. Each [GraphNode] represents a node in the graph, a single unit of data in the connected scheme. [GraphEdit], in turn, helps to control various interactions with nodes and between nodes. When the user attempts to connect, disconnect, or delete a [GraphNode], a signal is emitted in the [GraphEdit], but no action is taken by default. It is the responsibility of the programmer utilizing this control to implement the necessary logic to determine how each request should be handled. [b]Performance:[/b] It is greatly advised to enable low-processor usage mode (see [member OS.low_processor_usage_mode]) when using GraphEdits. + [b]Note:[/b] Keep in mind that [method Node.get_children] will also return the connection layer node named [code]_connection_layer[/code] due to technical limitations. This behavior may change in future releases. </description> <tutorials> </tutorials> diff --git a/doc/classes/LightmapGI.xml b/doc/classes/LightmapGI.xml index 6fb15e4d21..e7d44411ef 100644 --- a/doc/classes/LightmapGI.xml +++ b/doc/classes/LightmapGI.xml @@ -137,6 +137,12 @@ <constant name="BAKE_ERROR_TEXTURE_SIZE_TOO_SMALL" value="9" enum="BakeError"> Lightmap baking failed as the maximum texture size is too small to fit some of the meshes marked for baking. </constant> + <constant name="BAKE_ERROR_LIGHTMAP_TOO_SMALL" value="10" enum="BakeError"> + Lightmap baking failed as the lightmap is too small. + </constant> + <constant name="BAKE_ERROR_ATLAS_TOO_SMALL" value="11" enum="BakeError"> + Lightmap baking failed as the lightmap was unable to fit into an atlas. + </constant> <constant name="ENVIRONMENT_MODE_DISABLED" value="0" enum="EnvironmentMode"> Ignore environment lighting when baking lightmaps. </constant> diff --git a/doc/classes/Mesh.xml b/doc/classes/Mesh.xml index 6b5a50d97b..7f4dd5af37 100644 --- a/doc/classes/Mesh.xml +++ b/doc/classes/Mesh.xml @@ -223,6 +223,7 @@ </constant> <constant name="ARRAY_NORMAL" value="1" enum="ArrayType"> [PackedVector3Array] of vertex normals. + [b]Note:[/b] The array has to consist of normal vectors, otherwise they will be normalized by the engine, potentially causing visual discrepancies. </constant> <constant name="ARRAY_TANGENT" value="2" enum="ArrayType"> [PackedFloat32Array] of vertex tangents. Each element in groups of 4 floats, first 3 floats determine the tangent, and the last the binormal direction as -1 or 1. diff --git a/doc/classes/Node.xml b/doc/classes/Node.xml index 2662b34aec..c54219c056 100644 --- a/doc/classes/Node.xml +++ b/doc/classes/Node.xml @@ -1187,7 +1187,7 @@ </constant> <constant name="NOTIFICATION_WM_GO_BACK_REQUEST" value="1007"> Notification received from the OS when a go back request is sent (e.g. pressing the "Back" button on Android). - Implemented only on iOS. + Implemented only on Android. </constant> <constant name="NOTIFICATION_WM_SIZE_CHANGED" value="1008"> Notification received when the window is resized. diff --git a/doc/classes/NodePath.xml b/doc/classes/NodePath.xml index b4969b8906..d0ec81ab45 100644 --- a/doc/classes/NodePath.xml +++ b/doc/classes/NodePath.xml @@ -23,11 +23,12 @@ [/codeblock] Despite their name, node paths may also point to a property: [codeblock] - ^"position" # Points to this object's position. - ^"position:x" # Points to this object's position in the x axis. + ^":position" # Points to this object's position. + ^":position:x" # Points to this object's position in the x axis. ^"Camera3D:rotation:y" # Points to the child Camera3D and its y rotation. ^"/root:size:x" # Points to the root Window and its width. [/codeblock] + In some situations, it's possible to omit the leading [code]:[/code] when pointing to an object's property. As an example, this is the case with [method Object.set_indexed] and [method Tween.tween_property], as those methods call [method NodePath.get_as_property_path] under the hood. However, it's generally recommended to keep the [code]:[/code] prefix. Node paths cannot check whether they are valid and may point to nodes or properties that do not exist. Their meaning depends entirely on the context in which they're used. You usually do not have to worry about the [NodePath] type, as strings are automatically converted to the type when necessary. There are still times when defining node paths is useful. For example, exported [NodePath] properties allow you to easily select any node within the currently edited scene. They are also automatically updated when moving, renaming or deleting nodes in the scene tree editor. See also [annotation @GDScript.@export_node_path]. See also [StringName], which is a similar type designed for optimized strings. diff --git a/doc/classes/OS.xml b/doc/classes/OS.xml index 3d048e2f63..77caea9745 100644 --- a/doc/classes/OS.xml +++ b/doc/classes/OS.xml @@ -283,7 +283,7 @@ <return type="String" /> <description> Returns the file path to the current engine executable. - [b]Note:[/b] On macOS, always use [method create_instance] instead of relying on executable path. + [b]Note:[/b] On macOS, if you want to launch another instance of Godot, always use [method create_instance] instead of relying on the executable path. </description> </method> <method name="get_granted_permissions" qualifiers="const"> diff --git a/doc/classes/Parallax2D.xml b/doc/classes/Parallax2D.xml index 472aeb0bd3..cfd282a723 100644 --- a/doc/classes/Parallax2D.xml +++ b/doc/classes/Parallax2D.xml @@ -8,6 +8,7 @@ [b]Note:[/b] Any changes to this node's position made after it enters the scene tree will be overridden if [member ignore_camera_scroll] is [code]false[/code] or [member screen_offset] is modified. </description> <tutorials> + <link title="2D Parallax">$DOCS_URL/tutorials/2d/2d_parallax.html</link> </tutorials> <members> <member name="autoscroll" type="Vector2" setter="set_autoscroll" getter="get_autoscroll" default="Vector2(0, 0)"> diff --git a/doc/classes/PhysicsPointQueryParameters2D.xml b/doc/classes/PhysicsPointQueryParameters2D.xml index 521e584173..642e87947a 100644 --- a/doc/classes/PhysicsPointQueryParameters2D.xml +++ b/doc/classes/PhysicsPointQueryParameters2D.xml @@ -24,6 +24,7 @@ </member> <member name="exclude" type="RID[]" setter="set_exclude" getter="get_exclude" default="[]"> The list of object [RID]s that will be excluded from collisions. Use [method CollisionObject2D.get_rid] to get the [RID] associated with a [CollisionObject2D]-derived node. + [b]Note:[/b] The returned array is copied and any changes to it will not update the original property value. To update the value you need to modify the returned array, and then assign it to the property again. </member> <member name="position" type="Vector2" setter="set_position" getter="get_position" default="Vector2(0, 0)"> The position being queried for, in global coordinates. diff --git a/doc/classes/PhysicsPointQueryParameters3D.xml b/doc/classes/PhysicsPointQueryParameters3D.xml index 1cbc11bd03..a53300c78d 100644 --- a/doc/classes/PhysicsPointQueryParameters3D.xml +++ b/doc/classes/PhysicsPointQueryParameters3D.xml @@ -20,6 +20,7 @@ </member> <member name="exclude" type="RID[]" setter="set_exclude" getter="get_exclude" default="[]"> The list of object [RID]s that will be excluded from collisions. Use [method CollisionObject3D.get_rid] to get the [RID] associated with a [CollisionObject3D]-derived node. + [b]Note:[/b] The returned array is copied and any changes to it will not update the original property value. To update the value you need to modify the returned array, and then assign it to the property again. </member> <member name="position" type="Vector3" setter="set_position" getter="get_position" default="Vector3(0, 0, 0)"> The position being queried for, in global coordinates. diff --git a/doc/classes/PhysicsRayQueryParameters2D.xml b/doc/classes/PhysicsRayQueryParameters2D.xml index 3d69e092f6..a9738b4690 100644 --- a/doc/classes/PhysicsRayQueryParameters2D.xml +++ b/doc/classes/PhysicsRayQueryParameters2D.xml @@ -36,6 +36,7 @@ </member> <member name="exclude" type="RID[]" setter="set_exclude" getter="get_exclude" default="[]"> The list of object [RID]s that will be excluded from collisions. Use [method CollisionObject2D.get_rid] to get the [RID] associated with a [CollisionObject2D]-derived node. + [b]Note:[/b] The returned array is copied and any changes to it will not update the original property value. To update the value you need to modify the returned array, and then assign it to the property again. </member> <member name="from" type="Vector2" setter="set_from" getter="get_from" default="Vector2(0, 0)"> The starting point of the ray being queried for, in global coordinates. diff --git a/doc/classes/PhysicsRayQueryParameters3D.xml b/doc/classes/PhysicsRayQueryParameters3D.xml index b203b8f555..175b594fb0 100644 --- a/doc/classes/PhysicsRayQueryParameters3D.xml +++ b/doc/classes/PhysicsRayQueryParameters3D.xml @@ -36,6 +36,7 @@ </member> <member name="exclude" type="RID[]" setter="set_exclude" getter="get_exclude" default="[]"> The list of object [RID]s that will be excluded from collisions. Use [method CollisionObject3D.get_rid] to get the [RID] associated with a [CollisionObject3D]-derived node. + [b]Note:[/b] The returned array is copied and any changes to it will not update the original property value. To update the value you need to modify the returned array, and then assign it to the property again. </member> <member name="from" type="Vector3" setter="set_from" getter="get_from" default="Vector3(0, 0, 0)"> The starting point of the ray being queried for, in global coordinates. diff --git a/doc/classes/PhysicsShapeQueryParameters2D.xml b/doc/classes/PhysicsShapeQueryParameters2D.xml index 915d94a54c..3687a4dc5a 100644 --- a/doc/classes/PhysicsShapeQueryParameters2D.xml +++ b/doc/classes/PhysicsShapeQueryParameters2D.xml @@ -20,6 +20,7 @@ </member> <member name="exclude" type="RID[]" setter="set_exclude" getter="get_exclude" default="[]"> The list of object [RID]s that will be excluded from collisions. Use [method CollisionObject2D.get_rid] to get the [RID] associated with a [CollisionObject2D]-derived node. + [b]Note:[/b] The returned array is copied and any changes to it will not update the original property value. To update the value you need to modify the returned array, and then assign it to the property again. </member> <member name="margin" type="float" setter="set_margin" getter="get_margin" default="0.0"> The collision margin for the shape. diff --git a/doc/classes/PhysicsShapeQueryParameters3D.xml b/doc/classes/PhysicsShapeQueryParameters3D.xml index eba2b8287f..f05322f1ab 100644 --- a/doc/classes/PhysicsShapeQueryParameters3D.xml +++ b/doc/classes/PhysicsShapeQueryParameters3D.xml @@ -20,6 +20,7 @@ </member> <member name="exclude" type="RID[]" setter="set_exclude" getter="get_exclude" default="[]"> The list of object [RID]s that will be excluded from collisions. Use [method CollisionObject3D.get_rid] to get the [RID] associated with a [CollisionObject3D]-derived node. + [b]Note:[/b] The returned array is copied and any changes to it will not update the original property value. To update the value you need to modify the returned array, and then assign it to the property again. </member> <member name="margin" type="float" setter="set_margin" getter="get_margin" default="0.0"> The collision margin for the shape. diff --git a/doc/classes/PopupMenu.xml b/doc/classes/PopupMenu.xml index 0f5687f091..004bbe2286 100644 --- a/doc/classes/PopupMenu.xml +++ b/doc/classes/PopupMenu.xml @@ -395,6 +395,12 @@ Returns [code]true[/code] if the specified item's shortcut is disabled. </description> </method> + <method name="is_native_menu" qualifiers="const"> + <return type="bool" /> + <description> + Returns [code]true[/code] if the system native menu is supported and currently used by this [PopupMenu]. + </description> + </method> <method name="is_system_menu" qualifiers="const"> <return type="bool" /> <description> @@ -636,6 +642,7 @@ </member> <member name="prefer_native_menu" type="bool" setter="set_prefer_native_menu" getter="is_prefer_native_menu" default="false"> If [code]true[/code], [MenuBar] will use native menu when supported. + [b]Note:[/b] If [PopupMenu] is linked to [StatusIndicator], [MenuBar], or another [PopupMenu] item it can use native menu regardless of this property, use [method is_native_menu] to check it. </member> <member name="submenu_popup_delay" type="float" setter="set_submenu_popup_delay" getter="get_submenu_popup_delay" default="0.3"> Sets the delay time in seconds for the submenu item to popup on mouse hovering. If the popup menu is added as a child of another (acting as a submenu), it will inherit the delay time of the parent menu item. diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml index b1556783d5..4f7f372864 100644 --- a/doc/classes/ProjectSettings.xml +++ b/doc/classes/ProjectSettings.xml @@ -633,6 +633,9 @@ <member name="debug/settings/profiler/max_functions" type="int" setter="" getter="" default="16384"> Maximum number of functions per frame allowed when profiling. </member> + <member name="debug/settings/profiler/max_timestamp_query_elements" type="int" setter="" getter="" default="256"> + Maximum number of timestamp query elements allowed per frame for visual profiling. + </member> <member name="debug/settings/stdout/print_fps" type="bool" setter="" getter="" default="false"> Print frames per second to standard output every second. </member> @@ -897,8 +900,8 @@ <member name="display/window/stretch/mode" type="String" setter="" getter="" default=""disabled""> Defines how the base size is stretched to fit the resolution of the window or screen. [b]"disabled"[/b]: No stretching happens. One unit in the scene corresponds to one pixel on the screen. In this mode, [member display/window/stretch/aspect] has no effect. Recommended for non-game applications. - [b]"canvas_items"[/b]: The base size specified in width and height in the project settings is stretched to cover the whole screen (taking [member display/window/stretch/aspect] into account). This means that everything is rendered directly at the target resolution. 3D is unaffected, while in 2D, there is no longer a 1:1 correspondence between sprite pixels and screen pixels, which may result in scaling artifacts. Recommended for most games that don't use a pixel art esthetic, although it is possible to use this stretch mode for pixel art games too (especially in 3D). - [b]"viewport"[/b]: The size of the root [Viewport] is set precisely to the base size specified in the Project Settings' Display section. The scene is rendered to this viewport first. Finally, this viewport is scaled to fit the screen (taking [member display/window/stretch/aspect] into account). Recommended for games that use a pixel art esthetic. + [b]"canvas_items"[/b]: The base size specified in width and height in the project settings is stretched to cover the whole screen (taking [member display/window/stretch/aspect] into account). This means that everything is rendered directly at the target resolution. 3D is unaffected, while in 2D, there is no longer a 1:1 correspondence between sprite pixels and screen pixels, which may result in scaling artifacts. Recommended for most games that don't use a pixel art aesthetic, although it is possible to use this stretch mode for pixel art games too (especially in 3D). + [b]"viewport"[/b]: The size of the root [Viewport] is set precisely to the base size specified in the Project Settings' Display section. The scene is rendered to this viewport first. Finally, this viewport is scaled to fit the screen (taking [member display/window/stretch/aspect] into account). Recommended for games that use a pixel art aesthetic. </member> <member name="display/window/stretch/scale" type="float" setter="" getter="" default="1.0"> The scale factor multiplier to use for 2D elements. This multiplies the final scale factor determined by [member display/window/stretch/mode]. If using the [b]Disabled[/b] stretch mode, this scale factor is applied as-is. This can be adjusted to make the UI easier to read on certain displays. @@ -931,8 +934,9 @@ Changing this value allows setting up a multi-project scenario where there are multiple [code].csproj[/code]. Keep in mind that the Godot project is considered one of the C# projects in the workspace and it's root directory should contain the [code]project.godot[/code] and [code].csproj[/code] next to each other. </member> <member name="editor/export/convert_text_resources_to_binary" type="bool" setter="" getter="" default="true"> - If [code]true[/code], text resources are converted to a binary format on export. This decreases file sizes and speeds up loading slightly. - [b]Note:[/b] If [member editor/export/convert_text_resources_to_binary] is [code]true[/code], [method @GDScript.load] will not be able to return the converted files in an exported project. Some file paths within the exported PCK will also change, such as [code]project.godot[/code] becoming [code]project.binary[/code]. If you rely on run-time loading of files present within the PCK, set [member editor/export/convert_text_resources_to_binary] to [code]false[/code]. + If [code]true[/code], text resource ([code]tres[/code]) and text scene ([code]tscn[/code]) files are converted to their corresponding binary format on export. This decreases file sizes and speeds up loading slightly. + [b]Note:[/b] Because a resource's file extension may change in an exported project, it is heavily recommended to use [method @GDScript.load] or [ResourceLoader] instead of [FileAccess] to load resources dynamically. + [b]Note:[/b] The project settings file ([code]project.godot[/code]) will always be converted to binary on export, regardless of this setting. </member> <member name="editor/import/atlas_max_width" type="int" setter="" getter="" default="2048"> The maximum width to use when importing textures as an atlas. The value will be rounded to the nearest power of two when used. Use this to prevent imported textures from growing too large in the other direction. diff --git a/doc/classes/RenderDataExtension.xml b/doc/classes/RenderDataExtension.xml index 9bdab8e101..5c2b75ed1b 100644 --- a/doc/classes/RenderDataExtension.xml +++ b/doc/classes/RenderDataExtension.xml @@ -12,24 +12,25 @@ <method name="_get_camera_attributes" qualifiers="virtual const"> <return type="RID" /> <description> - Implement this in GDExtension to return the [RID] for the implementations camera attributes object. + Implement this in GDExtension to return the [RID] for the implementation's camera attributes object. </description> </method> <method name="_get_environment" qualifiers="virtual const"> <return type="RID" /> <description> + Implement this in GDExtension to return the [RID] of the implementation's environment object. </description> </method> <method name="_get_render_scene_buffers" qualifiers="virtual const"> <return type="RenderSceneBuffers" /> <description> - Implement this in GDExtension to return the [RID] of the implementations environment object. + Implement this in GDExtension to return the implementation's [RenderSceneBuffers] object. </description> </method> <method name="_get_render_scene_data" qualifiers="virtual const"> <return type="RenderSceneData" /> <description> - Implement this in GDExtension to return the implementations [RenderSceneDataExtension] object. + Implement this in GDExtension to return the implementation's [RenderSceneDataExtension] object. </description> </method> </methods> diff --git a/doc/classes/RenderSceneBuffersRD.xml b/doc/classes/RenderSceneBuffersRD.xml index 359f0b33a8..212a65337e 100644 --- a/doc/classes/RenderSceneBuffersRD.xml +++ b/doc/classes/RenderSceneBuffersRD.xml @@ -89,6 +89,12 @@ If [param msaa] is [b]true[/b] and MSAA is enabled, this returns the MSAA variant of the buffer. </description> </method> + <method name="get_fsr_sharpness" qualifiers="const"> + <return type="float" /> + <description> + Returns the FSR sharpness value used while rendering the 3D content (if [method get_scaling_3d_mode] is an FSR mode). + </description> + </method> <method name="get_internal_size" qualifiers="const"> <return type="Vector2i" /> <description> @@ -107,6 +113,24 @@ Returns the render target associated with this buffers object. </description> </method> + <method name="get_scaling_3d_mode" qualifiers="const"> + <return type="int" enum="RenderingServer.ViewportScaling3DMode" /> + <description> + Returns the scaling mode used for upscaling. + </description> + </method> + <method name="get_screen_space_aa" qualifiers="const"> + <return type="int" enum="RenderingServer.ViewportScreenSpaceAA" /> + <description> + Returns the screen-space antialiasing method applied. + </description> + </method> + <method name="get_target_size" qualifiers="const"> + <return type="Vector2i" /> + <description> + Returns the target size of the render buffer (size after upscaling). + </description> + </method> <method name="get_texture" qualifiers="const"> <return type="RID" /> <param index="0" name="context" type="StringName" /> @@ -123,6 +147,12 @@ Returns the texture format information with which a cached texture was created. </description> </method> + <method name="get_texture_samples" qualifiers="const"> + <return type="int" enum="RenderingDevice.TextureSamples" /> + <description> + Returns the number of MSAA samples used. + </description> + </method> <method name="get_texture_slice"> <return type="RID" /> <param index="0" name="context" type="StringName" /> @@ -157,6 +187,12 @@ Returns a specific view of a slice (layer or mipmap) for a cached texture. </description> </method> + <method name="get_use_debanding" qualifiers="const"> + <return type="bool" /> + <description> + Returns [code]true[/code] if debanding is enabled. + </description> + </method> <method name="get_use_taa" qualifiers="const"> <return type="bool" /> <description> diff --git a/doc/classes/RenderingDevice.xml b/doc/classes/RenderingDevice.xml index 3c1061dee9..876f229d0c 100644 --- a/doc/classes/RenderingDevice.xml +++ b/doc/classes/RenderingDevice.xml @@ -1444,10 +1444,10 @@ VRAM-compressed signed red/green channel data format with normalized value. Values are in the [code][-1.0, 1.0][/code] range. The format's precision is 8 bits of red channel and 8 bits of green channel. Using BC5 texture compression (also known as S3TC RGTC). </constant> <constant name="DATA_FORMAT_BC6H_UFLOAT_BLOCK" value="142" enum="DataFormat"> - VRAM-compressed unsigned red/green/blue channel data format with the floating-point value stored as-is. The format's precision is 8 bits of red channel and 8 bits of green channel. Using BC6H texture compression (also known as BPTC HDR). + VRAM-compressed unsigned red/green/blue channel data format with the floating-point value stored as-is. The format's precision is between 10 and 13 bits for the red/green/blue channels. Using BC6H texture compression (also known as BPTC HDR). </constant> <constant name="DATA_FORMAT_BC6H_SFLOAT_BLOCK" value="143" enum="DataFormat"> - VRAM-compressed signed red/green/blue channel data format with the floating-point value stored as-is. The format's precision is between 4 and 7 bits for the red/green/blue channels and between 0 and 8 bits for the alpha channel. Using BC7 texture compression (also known as BPTC HDR). + VRAM-compressed signed red/green/blue channel data format with the floating-point value stored as-is. The format's precision is between 10 and 13 bits for the red/green/blue channels. Using BC6H texture compression (also known as BPTC HDR). </constant> <constant name="DATA_FORMAT_BC7_UNORM_BLOCK" value="144" enum="DataFormat"> VRAM-compressed unsigned red/green/blue/alpha channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. The format's precision is between 4 and 7 bits for the red/green/blue channels and between 0 and 8 bits for the alpha channel. Also known as BPTC LDR. @@ -1477,13 +1477,13 @@ 11-bit VRAM-compressed unsigned red channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. Using ETC2 texture compression. </constant> <constant name="DATA_FORMAT_EAC_R11_SNORM_BLOCK" value="153" enum="DataFormat"> - 11-bit VRAM-compressed signed red channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. Using ETC2 texture compression. + 11-bit VRAM-compressed signed red channel data format with normalized value. Values are in the [code][-1.0, 1.0][/code] range. Using ETC2 texture compression. </constant> <constant name="DATA_FORMAT_EAC_R11G11_UNORM_BLOCK" value="154" enum="DataFormat"> 11-bit VRAM-compressed unsigned red/green channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. Using ETC2 texture compression. </constant> <constant name="DATA_FORMAT_EAC_R11G11_SNORM_BLOCK" value="155" enum="DataFormat"> - 11-bit VRAM-compressed signed red/green channel data format with normalized value. Values are in the [code][0.0, 1.0][/code] range. Using ETC2 texture compression. + 11-bit VRAM-compressed signed red/green channel data format with normalized value. Values are in the [code][-1.0, 1.0][/code] range. Using ETC2 texture compression. </constant> <constant name="DATA_FORMAT_ASTC_4x4_UNORM_BLOCK" value="156" enum="DataFormat"> VRAM-compressed unsigned floating-point data format with normalized value, packed in 4×4 blocks (highest quality). Values are in the [code][0.0, 1.0][/code] range. Using ASTC compression. diff --git a/doc/classes/Resource.xml b/doc/classes/Resource.xml index cec936ac3e..74d083594f 100644 --- a/doc/classes/Resource.xml +++ b/doc/classes/Resource.xml @@ -40,8 +40,11 @@ <param index="0" name="subresources" type="bool" default="false" /> <description> Duplicates this resource, returning a new resource with its [code]export[/code]ed or [constant PROPERTY_USAGE_STORAGE] properties copied from the original. - If [param subresources] is [code]false[/code], a shallow copy is returned; nested resources within subresources are not duplicated and are shared from the original resource. If [param subresources] is [code]true[/code], a deep copy is returned; nested subresources will be duplicated and are not shared. - Subresource properties with the [constant PROPERTY_USAGE_ALWAYS_DUPLICATE] flag are always duplicated even with [param subresources] set to [code]false[/code], and properties with the [constant PROPERTY_USAGE_NEVER_DUPLICATE] flag are never duplicated even with [param subresources] set to [code]true[/code]. + If [param subresources] is [code]false[/code], a shallow copy is returned; nested resources within subresources are not duplicated and are shared with the original resource (with one exception; see below). If [param subresources] is [code]true[/code], a deep copy is returned; nested subresources will be duplicated and are not shared (with two exceptions; see below). + [param subresources] is usually respected, with the following exceptions: + - Subresource properties with the [constant PROPERTY_USAGE_ALWAYS_DUPLICATE] flag are always duplicated. + - Subresource properties with the [constant PROPERTY_USAGE_NEVER_DUPLICATE] flag are never duplicated. + - Subresources inside [Array] and [Dictionary] properties are never duplicated. [b]Note:[/b] For custom resources, this method will fail if [method Object._init] has been defined with required parameters. </description> </method> diff --git a/doc/classes/RichTextLabel.xml b/doc/classes/RichTextLabel.xml index 24d2d26beb..7e0c39ac7c 100644 --- a/doc/classes/RichTextLabel.xml +++ b/doc/classes/RichTextLabel.xml @@ -432,7 +432,7 @@ Adds [code skip-lint][ol][/code] or [code skip-lint][ul][/code] tag to the tag stack. Multiplies [param level] by current [member tab_size] to determine new margin length. </description> </method> - <method name="push_meta"> + <method name="push_meta" keywords="push_url"> <return type="void" /> <param index="0" name="data" type="Variant" /> <param index="1" name="underline_mode" type="int" enum="RichTextLabel.MetaUnderline" default="1" /> @@ -628,7 +628,7 @@ <member name="language" type="String" setter="set_language" getter="get_language" default=""""> Language code used for line-breaking and text shaping algorithms, if left empty current locale is used instead. </member> - <member name="meta_underlined" type="bool" setter="set_meta_underline" getter="is_meta_underlined" default="true"> + <member name="meta_underlined" type="bool" setter="set_meta_underline" getter="is_meta_underlined" default="true" keywords="url_underlined"> If [code]true[/code], the label underlines meta tags such as [code skip-lint][url]{text}[/url][/code]. These tags can call a function when clicked if [signal meta_clicked] is connected to a function. </member> <member name="progress_bar_delay" type="int" setter="set_progress_bar_delay" getter="get_progress_bar_delay" default="1000"> diff --git a/doc/classes/Script.xml b/doc/classes/Script.xml index fa8e4ef5f2..45f0bbb8aa 100644 --- a/doc/classes/Script.xml +++ b/doc/classes/Script.xml @@ -93,6 +93,7 @@ <return type="bool" /> <description> Returns [code]true[/code] if the script contains non-empty source code. + [b]Note:[/b] If a script does not have source code, this does not mean that it is invalid or unusable. For example, a [GDScript] that was exported with binary tokenization has no source code, but still behaves as expected and could be instantiated. This can be checked with [method can_instantiate]. </description> </method> <method name="instance_has" qualifiers="const"> diff --git a/doc/classes/ScriptEditorBase.xml b/doc/classes/ScriptEditorBase.xml index 403608355a..638bc921d6 100644 --- a/doc/classes/ScriptEditorBase.xml +++ b/doc/classes/ScriptEditorBase.xml @@ -72,7 +72,7 @@ </description> </signal> <signal name="request_save_previous_state"> - <param index="0" name="line" type="int" /> + <param index="0" name="state" type="Dictionary" /> <description> Emitted when the user changes current script or moves caret by 10 or more columns within the same script. </description> diff --git a/doc/classes/Skeleton3D.xml b/doc/classes/Skeleton3D.xml index 5829a787a1..cc3f61e1b2 100644 --- a/doc/classes/Skeleton3D.xml +++ b/doc/classes/Skeleton3D.xml @@ -57,11 +57,6 @@ Force updates the bone transform for the bone at [param bone_idx] and all of its children. </description> </method> - <method name="get_animate_physical_bones" qualifiers="const" deprecated=""> - <return type="bool" /> - <description> - </description> - </method> <method name="get_bone_children" qualifiers="const"> <return type="PackedInt32Array" /> <param index="0" name="bone_idx" type="int" /> @@ -239,14 +234,6 @@ Sets all bone poses to rests. </description> </method> - <method name="set_animate_physical_bones" deprecated=""> - <return type="void" /> - <param index="0" name="enabled" type="bool" /> - <description> - This method exists for compatibility with old structures in which the [Skeleton3D] does not have a [PhysicalBoneSimulator3D] as a child, but directly has [PhysicalBone3D]s as children. - In case you need to raycast to it without running [method physical_bones_start_simulation], call this method with [code]enabled == true[/code]. - </description> - </method> <method name="set_bone_enabled"> <return type="void" /> <param index="0" name="bone_idx" type="int" /> @@ -342,6 +329,10 @@ </method> </methods> <members> + <member name="animate_physical_bones" type="bool" setter="set_animate_physical_bones" getter="get_animate_physical_bones" default="true" deprecated=""> + If you follow the recommended workflow and explicitly have [PhysicalBoneSimulator3D] as a child of [Skeleton3D], you can control whether it is affected by raycasting without running [method physical_bones_start_simulation], by its [member SkeletonModifier3D.active]. + However, for old (deprecated) configurations, [Skeleton3D] has an internal virtual [PhysicalBoneSimulator3D] for compatibility. This property controls the internal virtual [PhysicalBoneSimulator3D]'s [member SkeletonModifier3D.active]. + </member> <member name="modifier_callback_mode_process" type="int" setter="set_modifier_callback_mode_process" getter="get_modifier_callback_mode_process" enum="Skeleton3D.ModifierCallbackModeProcess" default="1"> Sets the processing timing for the Modifier. </member> diff --git a/doc/classes/TextParagraph.xml b/doc/classes/TextParagraph.xml index 541078ed22..c6511a2b8e 100644 --- a/doc/classes/TextParagraph.xml +++ b/doc/classes/TextParagraph.xml @@ -175,7 +175,7 @@ <return type="Vector2" /> <param index="0" name="line" type="int" /> <description> - Returns size of the bounding box of the line of text. + Returns size of the bounding box of the line of text. Returned size is rounded up. </description> </method> <method name="get_line_underline_position" qualifiers="const"> diff --git a/doc/classes/TileSetScenesCollectionSource.xml b/doc/classes/TileSetScenesCollectionSource.xml index 9d2742b844..40ad269e83 100644 --- a/doc/classes/TileSetScenesCollectionSource.xml +++ b/doc/classes/TileSetScenesCollectionSource.xml @@ -6,6 +6,32 @@ <description> When placed on a [TileMap], tiles from [TileSetScenesCollectionSource] will automatically instantiate an associated scene at the cell's position in the TileMap. Scenes are instantiated as children of the [TileMap] when it enters the tree. If you add/remove a scene tile in the [TileMap] that is already inside the tree, the [TileMap] will automatically instantiate/free the scene accordingly. + [b]Note:[/b] Scene tiles all occupy one tile slot and instead use alternate tile ID to identify scene index. [method TileSetSource.get_tiles_count] will always return [code]1[/code]. Use [method get_scene_tiles_count] to get a number of scenes in a [TileSetScenesCollectionSource]. + Use this code if you want to find the scene path at a given tile in [TileMapLayer]: + [codeblocks] + [gdscript] + var source_id = tile_map_layer.get_cell_source_id(Vector2i(x, y)) + if source_id > -1: + var scene_source = tile_map_layer.tile_set.get_source(source_id) + if scene_source is TileSetScenesCollectionSource: + var alt_id = tile_map_layer.get_cell_alternative_tile(Vector2i(x, y)) + # The assigned PackedScene. + var scene = scene_source.get_scene_tile_scene(alt_id) + [/gdscript] + [csharp] + int sourceId = tileMapLayer.GetCellSourceId(new Vector2I(x, y)); + if (sourceId > -1) + { + TileSetSource source = tileMapLayer.TileSet.GetSource(sourceId); + if (source is TileSetScenesCollectionSource sceneSource) + { + int altId = tileMapLayer.GetCellAlternativeTile(new Vector2I(x, y)); + // The assigned PackedScene. + PackedScene scene = sceneSource.GetSceneTileScene(altId); + } + } + [/csharp] + [/codeblocks] </description> <tutorials> </tutorials> diff --git a/doc/classes/Transform2D.xml b/doc/classes/Transform2D.xml index 345d0512ff..4158fbe710 100644 --- a/doc/classes/Transform2D.xml +++ b/doc/classes/Transform2D.xml @@ -4,8 +4,10 @@ A 2×3 matrix representing a 2D transformation. </brief_description> <description> - A 2×3 matrix (2 rows, 3 columns) used for 2D linear transformations. It can represent transformations such as translation, rotation, and scaling. It consists of three [Vector2] values: [member x], [member y], and the [member origin]. + The [Transform2D] built-in [Variant] type is a 2×3 [url=https://en.wikipedia.org/wiki/Matrix_(mathematics)]matrix[/url] representing a transformation in 2D space. It contains three [Vector2] values: [member x], [member y], and [member origin]. Together, they can represent translation, rotation, scale, and skew. + The [member x] and [member y] axes form a 2×2 matrix, known as the transform's [b]basis[/b]. The length of each axis ([method Vector2.length]) influences the transform's scale, while the direction of all axes influence the rotation. Usually, both axes are perpendicular to one another. However, when you rotate one axis individually, the transform becomes skewed. Applying a skewed transform to a 2D sprite will make the sprite appear distorted. For a general introduction, see the [url=$DOCS_URL/tutorials/math/matrices_and_transforms.html]Matrices and transforms[/url] tutorial. + [b]Note:[/b] Unlike [Transform3D], there is no 2D equivalent to the [Basis] type. All mentions of "basis" refer to the [member x] and [member y] components of [Transform2D]. </description> <tutorials> <link title="Math documentation index">$DOCS_URL/tutorials/math/index.html</link> @@ -17,7 +19,7 @@ <constructor name="Transform2D"> <return type="Transform2D" /> <description> - Constructs a default-initialized [Transform2D] set to [constant IDENTITY]. + Constructs a [Transform2D] identical to [constant IDENTITY]. </description> </constructor> <constructor name="Transform2D"> @@ -32,7 +34,7 @@ <param index="0" name="rotation" type="float" /> <param index="1" name="position" type="Vector2" /> <description> - Constructs the transform from a given angle (in radians) and position. + Constructs a [Transform2D] from a given angle (in radians) and position. </description> </constructor> <constructor name="Transform2D"> @@ -42,7 +44,7 @@ <param index="2" name="skew" type="float" /> <param index="3" name="position" type="Vector2" /> <description> - Constructs the transform from a given angle (in radians), scale, skew (in radians) and position. + Constructs a [Transform2D] from a given angle (in radians), scale, skew (in radians), and position. </description> </constructor> <constructor name="Transform2D"> @@ -51,7 +53,7 @@ <param index="1" name="y_axis" type="Vector2" /> <param index="2" name="origin" type="Vector2" /> <description> - Constructs the transform from 3 [Vector2] values representing [member x], [member y], and the [member origin] (the three column vectors). + Constructs a [Transform2D] from 3 [Vector2] values representing [member x], [member y], and the [member origin] (the three matrix columns). </description> </constructor> </constructors> @@ -59,56 +61,81 @@ <method name="affine_inverse" qualifiers="const"> <return type="Transform2D" /> <description> - Returns the inverse of the transform, under the assumption that the basis is invertible (must have non-zero determinant). + Returns the inverted version of this transform. Unlike [method inverse], this method works with almost any basis, including non-uniform ones, but is slower. See also [method inverse]. + [b]Note:[/b] For this method to return correctly, the transform's basis needs to have a determinant that is not exactly [code]0[/code] (see [method determinant]). </description> </method> <method name="basis_xform" qualifiers="const"> <return type="Vector2" /> <param index="0" name="v" type="Vector2" /> <description> - Returns a vector transformed (multiplied) by the basis matrix. - This method does not account for translation (the [member origin] vector). + Returns a copy of the [param v] vector, transformed (multiplied) by the transform basis's matrix. Unlike the multiplication operator ([code]*[/code]), this method ignores the [member origin]. </description> </method> <method name="basis_xform_inv" qualifiers="const"> <return type="Vector2" /> <param index="0" name="v" type="Vector2" /> <description> - Returns a vector transformed (multiplied) by the inverse basis matrix, under the assumption that the basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). - This method does not account for translation (the [member origin] vector). - [code]transform.basis_xform_inv(vector)[/code] is equivalent to [code]transform.inverse().basis_xform(vector)[/code]. See [method inverse]. - For non-orthonormal transforms (e.g. with scaling) [code]transform.affine_inverse().basis_xform(vector)[/code] can be used instead. See [method affine_inverse]. + Returns a copy of the [param v] vector, transformed (multiplied) by the inverse transform basis's matrix (see [method inverse]). This method ignores the [member origin]. + [b]Note:[/b] This method assumes that this transform's basis is [i]orthonormal[/i] (see [method orthonormalized]). If the basis is not orthonormal, [code]transform.affine_inverse().basis_xform(vector)[/code] should be used instead (see [method affine_inverse]). </description> </method> <method name="determinant" qualifiers="const"> <return type="float" /> <description> - Returns the determinant of the basis matrix. If the basis is uniformly scaled, then its determinant equals the square of the scale factor. - A negative determinant means the basis was flipped, so one part of the scale is negative. A zero determinant means the basis isn't invertible, and is usually considered invalid. + Returns the [url=https://en.wikipedia.org/wiki/Determinant]determinant[/url] of this transform basis's matrix. For advanced math, this number can be used to determine a few attributes: + - If the determinant is exactly [code]0[/code], the basis is not invertible (see [method inverse]). + - If the determinant is a negative number, the basis represents a negative scale. + [b]Note:[/b] If the basis's scale is the same for every axis, its determinant is always that scale by the power of 2. </description> </method> <method name="get_origin" qualifiers="const"> <return type="Vector2" /> <description> - Returns the transform's origin (translation). + Returns this transform's translation. Equivalent to [member origin]. </description> </method> <method name="get_rotation" qualifiers="const"> <return type="float" /> <description> - Returns the transform's rotation (in radians). + Returns this transform's rotation (in radians). This is equivalent to [member x]'s angle (see [method Vector2.angle]). </description> </method> <method name="get_scale" qualifiers="const"> <return type="Vector2" /> <description> - Returns the scale. + Returns the length of both [member x] and [member y], as a [Vector2]. If this transform's basis is not skewed, this value is the scaling factor. It is not affected by rotation. + [codeblocks] + [gdscript] + var my_transform = Transform2D( + Vector2(2, 0), + Vector2(0, 4), + Vector2(0, 0) + ) + # Rotating the Transform2D in any way preserves its scale. + my_transform = my_transform.rotated(TAU / 2) + + print(my_transform.get_scale()) # Prints (2, 4). + [/gdscript] + [csharp] + var myTransform = new Transform2D( + Vector3(2.0f, 0.0f), + Vector3(0.0f, 4.0f), + Vector3(0.0f, 0.0f) + ); + // Rotating the Transform2D in any way preserves its scale. + myTransform = myTransform.Rotated(Mathf.Tau / 2.0f); + + GD.Print(myTransform.GetScale()); // Prints (2, 4, 8). + [/csharp] + [/codeblocks] + [b]Note:[/b] If the value returned by [method determinant] is negative, the scale is also negative. </description> </method> <method name="get_skew" qualifiers="const"> <return type="float" /> <description> - Returns the transform's skew (in radians). + Returns this transform's skew (in radians). </description> </method> <method name="interpolate_with" qualifiers="const"> @@ -116,19 +143,21 @@ <param index="0" name="xform" type="Transform2D" /> <param index="1" name="weight" type="float" /> <description> - Returns a transform interpolated between this transform and another by a given [param weight] (on the range of 0.0 to 1.0). + Returns the result of the linear interpolation between this transform and [param xform] by the given [param weight]. + The [param weight] should be between [code]0.0[/code] and [code]1.0[/code] (inclusive). Values outside this range are allowed and can be used to perform [i]extrapolation[/i] instead. </description> </method> <method name="inverse" qualifiers="const"> <return type="Transform2D" /> <description> - Returns the inverse of the transform, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). Use [method affine_inverse] for non-orthonormal transforms (e.g. with scaling). + Returns the [url=https://en.wikipedia.org/wiki/Invertible_matrix]inverted version of this transform[/url]. + [b]Note:[/b] For this method to return correctly, the transform's basis needs to be [i]orthonormal[/i] (see [method orthonormalized]). That means, the basis should only represent a rotation. If it does not, use [method affine_inverse] instead. </description> </method> <method name="is_conformal" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if the transform's basis is conformal, meaning it preserves angles and distance ratios, and may only be composed of rotation and uniform scale. Returns [code]false[/code] if the transform's basis has non-uniform scale or shear/skew. This can be used to validate if the transform is non-distorted, which is important for physics and other use cases. + Returns [code]true[/code] if this transform's basis is conformal. A conformal basis is both [i]orthogonal[/i] (the axes are perpendicular to each other) and [i]uniform[/i] (the axes share the same length). This method can be especially useful during physics calculations. </description> </method> <method name="is_equal_approx" qualifiers="const"> @@ -148,14 +177,13 @@ <return type="Transform2D" /> <param index="0" name="target" type="Vector2" default="Vector2(0, 0)" /> <description> - Returns a copy of the transform rotated such that the rotated X-axis points towards the [param target] position. - Operations take place in global space. + Returns a copy of the transform rotated such that the rotated X-axis points towards the [param target] position, in global space. </description> </method> <method name="orthonormalized" qualifiers="const"> <return type="Transform2D" /> <description> - Returns the transform with the basis orthogonal (90 degrees), and normalized axis vectors (scale of 1 or -1). + Returns a copy of this transform with its basis orthonormalized. An orthonormal basis is both [i]orthogonal[/i] (the axes are perpendicular to each other) and [i]normalized[/i] (the axes have a length of [code]1[/code]), which also means it can only represent rotation. </description> </method> <method name="rotated" qualifiers="const"> @@ -215,24 +243,41 @@ </methods> <members> <member name="origin" type="Vector2" setter="" getter="" default="Vector2(0, 0)"> - The origin vector (column 2, the third column). Equivalent to array index [code]2[/code]. The origin vector represents translation. + The translation offset of this transform, and the column [code]2[/code] of the matrix. In 2D space, this can be seen as the position. </member> <member name="x" type="Vector2" setter="" getter="" default="Vector2(1, 0)"> - The basis matrix's X vector (column 0). Equivalent to array index [code]0[/code]. + The transform basis's X axis, and the column [code]0[/code] of the matrix. Combined with [member y], this represents the transform's rotation, scale, and skew. + On the identity transform, this vector points right ([constant Vector2.RIGHT]). </member> <member name="y" type="Vector2" setter="" getter="" default="Vector2(0, 1)"> - The basis matrix's Y vector (column 1). Equivalent to array index [code]1[/code]. + The transform basis's Y axis, and the column [code]1[/code] of the matrix. Combined with [member x], this represents the transform's rotation, scale, and skew. + On the identity transform, this vector points up ([constant Vector2.UP]). </member> </members> <constants> <constant name="IDENTITY" value="Transform2D(1, 0, 0, 1, 0, 0)"> - The identity [Transform2D] with no translation, rotation or scaling applied. When applied to other data structures, [constant IDENTITY] performs no transformation. + The identity [Transform2D]. A transform with no translation, no rotation, and its scale being [code]1[/code]. When multiplied by another [Variant] such as [Rect2] or another [Transform2D], no transformation occurs. This means that: + - The [member x] points right ([constant Vector2.RIGHT]); + - The [member y] points up ([constant Vector2.UP]). + [codeblock] + var transform = Transform2D.IDENTITY + print("| X | Y | Origin") + print("| %s | %s | %s" % [transform.x.x, transform.y.x, transform.origin.x]) + print("| %s | %s | %s" % [transform.x.y, transform.y.y, transform.origin.y]) + # Prints: + # | X | Y | Origin + # | 1 | 0 | 0 + # | 0 | 1 | 0 + [/codeblock] + This is identical to creating [constructor Transform2D] without any parameters. This constant can be used to make your code clearer, and for consistency with C#. </constant> <constant name="FLIP_X" value="Transform2D(-1, 0, 0, 1, 0, 0)"> - The [Transform2D] that will flip something along the X axis. + When any transform is multiplied by [constant FLIP_X], it negates all components of the [member x] axis (the X column). + When [constant FLIP_X] is multiplied by any basis, it negates the [member Vector2.x] component of all axes (the X row). </constant> <constant name="FLIP_Y" value="Transform2D(1, 0, 0, -1, 0, 0)"> - The [Transform2D] that will flip something along the Y axis. + When any transform is multiplied by [constant FLIP_Y], it negates all components of the [member y] axis (the Y column). + When [constant FLIP_Y] is multiplied by any basis, it negates the [member Vector2.y] component of all axes (the Y row). </constant> </constants> <operators> @@ -240,7 +285,7 @@ <return type="bool" /> <param index="0" name="right" type="Transform2D" /> <description> - Returns [code]true[/code] if the transforms are not equal. + Returns [code]true[/code] if the components of both transforms are not equal. [b]Note:[/b] Due to floating-point precision errors, consider using [method is_equal_approx] instead, which is more reliable. </description> </operator> @@ -248,63 +293,69 @@ <return type="PackedVector2Array" /> <param index="0" name="right" type="PackedVector2Array" /> <description> - Transforms (multiplies) each element of the [Vector2] array by the given [Transform2D] matrix. + Transforms (multiplies) every [Vector2] element of the given [PackedVector2Array] by this transformation matrix. + On larger arrays, this operation is much faster than transforming each [Vector2] individually. </description> </operator> <operator name="operator *"> <return type="Rect2" /> <param index="0" name="right" type="Rect2" /> <description> - Transforms (multiplies) the [Rect2] by the given [Transform2D] matrix. + Transforms (multiplies) the [Rect2] by this transformation matrix. </description> </operator> <operator name="operator *"> <return type="Transform2D" /> <param index="0" name="right" type="Transform2D" /> <description> - Composes these two transformation matrices by multiplying them together. This has the effect of transforming the second transform (the child) by the first transform (the parent). + Transforms (multiplies) this transform by the [param right] transform. + This is the operation performed between parent and child [CanvasItem] nodes. + [b]Note:[/b] If you need to only modify one attribute of this transform, consider using one of the following methods, instead: + - For translation, see [method translated] or [method translated_local]. + - For rotation, see [method rotated] or [method rotated_local]. + - For scale, see [method scaled] or [method scaled_local]. </description> </operator> <operator name="operator *"> <return type="Vector2" /> <param index="0" name="right" type="Vector2" /> <description> - Transforms (multiplies) the [Vector2] by the given [Transform2D] matrix. + Transforms (multiplies) the [Vector2] by this transformation matrix. </description> </operator> <operator name="operator *"> <return type="Transform2D" /> <param index="0" name="right" type="float" /> <description> - This operator multiplies all components of the [Transform2D], including the [member origin] vector, which scales it uniformly. + Multiplies all components of the [Transform2D] by the given [float], including the [member origin]. This affects the transform's scale uniformly. </description> </operator> <operator name="operator *"> <return type="Transform2D" /> <param index="0" name="right" type="int" /> <description> - This operator multiplies all components of the [Transform2D], including the [member origin] vector, which scales it uniformly. + Multiplies all components of the [Transform2D] by the given [int], including the [member origin]. This affects the transform's scale uniformly. </description> </operator> <operator name="operator /"> <return type="Transform2D" /> <param index="0" name="right" type="float" /> <description> - This operator divides all components of the [Transform2D], including the [member origin] vector, which inversely scales it uniformly. + Divides all components of the [Transform2D] by the given [float], including the [member origin]. This affects the transform's scale uniformly. </description> </operator> <operator name="operator /"> <return type="Transform2D" /> <param index="0" name="right" type="int" /> <description> - This operator divides all components of the [Transform2D], including the [member origin] vector, which inversely scales it uniformly. + Divides all components of the [Transform2D] by the given [int], including the [member origin]. This affects the transform's scale uniformly. </description> </operator> <operator name="operator =="> <return type="bool" /> <param index="0" name="right" type="Transform2D" /> <description> - Returns [code]true[/code] if the transforms are exactly equal. + Returns [code]true[/code] if the components of both transforms are exactly equal. [b]Note:[/b] Due to floating-point precision errors, consider using [method is_equal_approx] instead, which is more reliable. </description> </operator> @@ -312,7 +363,7 @@ <return type="Vector2" /> <param index="0" name="index" type="int" /> <description> - Access transform components using their index. [code]t[0][/code] is equivalent to [code]t.x[/code], [code]t[1][/code] is equivalent to [code]t.y[/code], and [code]t[2][/code] is equivalent to [code]t.origin[/code]. + Accesses each axis (column) of this transform by their index. Index [code]0[/code] is the same as [member x], index [code]1[/code] is the same as [member y], and index [code]2[/code] is the same as [member origin]. </description> </operator> </operators> diff --git a/doc/classes/Transform3D.xml b/doc/classes/Transform3D.xml index 2a0bbc46af..30c141659a 100644 --- a/doc/classes/Transform3D.xml +++ b/doc/classes/Transform3D.xml @@ -6,7 +6,7 @@ <description> The [Transform3D] built-in [Variant] type is a 3×4 matrix representing a transformation in 3D space. It contains a [Basis], which on its own can represent rotation, scale, and shear. Additionally, combined with its own [member origin], the transform can also represent a translation. For a general introduction, see the [url=$DOCS_URL/tutorials/math/matrices_and_transforms.html]Matrices and transforms[/url] tutorial. - [b]Note:[/b] Godot uses a [url=https://en.wikipedia.org/wiki/Right-hand_rule]right-handed coordinate system[/url], which is a common standard. For directions, the convention for built-in types like [Camera3D] is for -Z to point forward (+X is right, +Y is up, and +Z is back). Other objects may use different direction conventions. For more information, see the [url=$DOCS_URL/tutorials/assets_pipeline/importing_scenes.html#d-asset-direction-conventions]Importing 3D Scenes[/url] tutorial. + [b]Note:[/b] Godot uses a [url=https://en.wikipedia.org/wiki/Right-hand_rule]right-handed coordinate system[/url], which is a common standard. For directions, the convention for built-in types like [Camera3D] is for -Z to point forward (+X is right, +Y is up, and +Z is back). Other objects may use different direction conventions. For more information, see the [url=$DOCS_URL/tutorials/assets_pipeline/importing_3d_scenes/model_export_considerations.html#d-asset-direction-conventions]3D asset direction conventions[/url] tutorial. </description> <tutorials> <link title="Math documentation index">$DOCS_URL/tutorials/math/index.html</link> diff --git a/doc/classes/XRInterface.xml b/doc/classes/XRInterface.xml index 175caca598..68d055ad8d 100644 --- a/doc/classes/XRInterface.xml +++ b/doc/classes/XRInterface.xml @@ -176,6 +176,10 @@ Triggers a haptic pulse on a device associated with this interface. [param action_name] is the name of the action for this pulse. [param tracker_name] is optional and can be used to direct the pulse to a specific device provided that device is bound to this haptic. + [param frequency] is the frequency of the pulse, set to [code]0.0[/code] to have the system use a default frequency. + [param amplitude] is the amplitude of the pulse between [code]0.0[/code] and [code]1.0[/code]. + [param duration_sec] is the duration of the pulse in seconds. + [param delay_sec] is a delay in seconds before the pulse is given. </description> </method> <method name="uninitialize"> diff --git a/doc/classes/XRNode3D.xml b/doc/classes/XRNode3D.xml index dfe5600fcc..82f4fa4ab9 100644 --- a/doc/classes/XRNode3D.xml +++ b/doc/classes/XRNode3D.xml @@ -38,6 +38,10 @@ <description> Triggers a haptic pulse on a device associated with this interface. [param action_name] is the name of the action for this pulse. + [param frequency] is the frequency of the pulse, set to [code]0.0[/code] to have the system use a default frequency. + [param amplitude] is the amplitude of the pulse between [code]0.0[/code] and [code]1.0[/code]. + [param duration_sec] is the duration of the pulse in seconds. + [param delay_sec] is a delay in seconds before the pulse is given. </description> </method> </methods> |