diff options
Diffstat (limited to 'doc/classes')
54 files changed, 549 insertions, 165 deletions
diff --git a/doc/classes/@GlobalScope.xml b/doc/classes/@GlobalScope.xml index 8fa15a2736..b74ca4b035 100644 --- a/doc/classes/@GlobalScope.xml +++ b/doc/classes/@GlobalScope.xml @@ -877,6 +877,7 @@ [/codeblocks] [b]Note:[/b] Consider using [method push_error] and [method push_warning] to print error and warning messages instead of [method print] or [method print_rich]. This distinguishes them from print messages used for debugging purposes, while also displaying a stack trace when an error or warning is printed. [b]Note:[/b] On Windows, only Windows 10 and later correctly displays ANSI escape codes in standard output. + [b]Note:[/b] Output displayed in the editor supports clickable [code skip-lint][url=address]text[/url][/code] tags. The [code skip-lint][url][/code] tag's [code]address[/code] value is handled by [method OS.shell_open] when clicked. </description> </method> <method name="print_verbose" qualifiers="vararg"> @@ -1428,6 +1429,7 @@ <description> Encodes a [Variant] value to a byte array, without encoding objects. Deserialization can be done with [method bytes_to_var]. [b]Note:[/b] If you need object serialization, see [method var_to_bytes_with_objects]. + [b]Note:[/b] Encoding [Callable] is not supported and will result in an empty value, regardless of the data. </description> </method> <method name="var_to_bytes_with_objects"> @@ -1435,6 +1437,7 @@ <param index="0" name="variable" type="Variant" /> <description> Encodes a [Variant] value to a byte array. Encoding objects is allowed (and can potentially include executable code). Deserialization can be done with [method bytes_to_var_with_objects]. + [b]Note:[/b] Encoding [Callable] is not supported and will result in an empty value, regardless of the data. </description> </method> <method name="var_to_str"> diff --git a/doc/classes/AABB.xml b/doc/classes/AABB.xml index c1c637d2d6..427d38d421 100644 --- a/doc/classes/AABB.xml +++ b/doc/classes/AABB.xml @@ -4,10 +4,10 @@ A 3D axis-aligned bounding box. </brief_description> <description> - [AABB] consists of a position, a size, and several utility functions. It is typically used for fast overlap tests. - It uses floating-point coordinates. The 2D counterpart to [AABB] is [Rect2]. - Negative values for [member size] are not supported and will not work for most methods. Use [method abs] to get an AABB with a positive size. - [b]Note:[/b] Unlike [Rect2], [AABB] does not have a variant that uses integer coordinates. + The [AABB] built-in [Variant] type represents an axis-aligned bounding box in a 3D space. It is defined by its [member position] and [member size], which are [Vector3]. It is frequently used for fast overlap tests (see [method intersects]). Although [AABB] itself is axis-aligned, it can be combined with [Transform3D] to represent a rotated or skewed bounding box. + It uses floating-point coordinates. The 2D counterpart to [AABB] is [Rect2]. There is no version of [AABB] that uses integer coordinates. + [b]Note:[/b] Negative values for [member size] are not supported. With negative size, most [AABB] methods do not work correctly. Use [method abs] to get an equivalent [AABB] with a non-negative size. + [b]Note:[/b] In a boolean context, a [AABB] evaluates to [code]false[/code] if both [member position] and [member size] are zero (equal to [constant Vector3.ZERO]). Otherwise, it always evaluates to [code]true[/code]. </description> <tutorials> <link title="Math documentation index">$DOCS_URL/tutorials/math/index.html</link> @@ -18,7 +18,7 @@ <constructor name="AABB"> <return type="AABB" /> <description> - Constructs a default-initialized [AABB] with default (zero) values of [member position] and [member size]. + Constructs an [AABB] with its [member position] and [member size] set to [constant Vector3.ZERO]. </description> </constructor> <constructor name="AABB"> @@ -33,7 +33,7 @@ <param index="0" name="position" type="Vector3" /> <param index="1" name="size" type="Vector3" /> <description> - Constructs an [AABB] from a position and size. + Constructs an [AABB] by [param position] and [param size]. </description> </constructor> </constructors> @@ -41,34 +41,78 @@ <method name="abs" qualifiers="const"> <return type="AABB" /> <description> - Returns an AABB with equivalent position and size, modified so that the most-negative corner is the origin and the size is positive. + Returns an [AABB] equivalent to this bounding box, with its width, height, and depth modified to be non-negative values. + [codeblocks] + [gdscript] + var box = AABB(Vector3(5, 0, 5), Vector3(-20, -10, -5)) + var absolute = box.abs() + print(absolute.position) # Prints (-15, -10, 0) + print(absolute.size) # Prints (20, 10, 5) + [/gdscript] + [csharp] + var box = new Aabb(new Vector3(5, 0, 5), new Vector3(-20, -10, -5)); + var absolute = box.Abs(); + GD.Print(absolute.Position); // Prints (-15, -10, 0) + GD.Print(absolute.Size); // Prints (20, 10, 5) + [/csharp] + [/codeblocks] + [b]Note:[/b] It's recommended to use this method when [member size] is negative, as most other methods in Godot assume that the [member size]'s components are greater than [code]0[/code]. </description> </method> <method name="encloses" qualifiers="const"> <return type="bool" /> <param index="0" name="with" type="AABB" /> <description> - Returns [code]true[/code] if this [AABB] completely encloses another one. + Returns [code]true[/code] if this bounding box [i]completely[/i] encloses the [param with] box. The edges of both boxes are included. + [codeblocks] + [gdscript] + var a = AABB(Vector3(0, 0, 0), Vector3(4, 4, 4)) + var b = AABB(Vector3(1, 1, 1), Vector3(3, 3, 3)) + var c = AABB(Vector3(2, 2, 2), Vector3(8, 8, 8)) + + print(a.encloses(a)) # Prints true + print(a.encloses(b)) # Prints true + print(a.encloses(c)) # Prints false + [/gdscript] + [csharp] + var a = new Aabb(new Vector3(0, 0, 0), new Vector3(4, 4, 4)); + var b = new Aabb(new Vector3(1, 1, 1), new Vector3(3, 3, 3)); + var c = new Aabb(new Vector3(2, 2, 2), new Vector3(8, 8, 8)); + + GD.Print(a.Encloses(a)); // Prints True + GD.Print(a.Encloses(b)); // Prints True + GD.Print(a.Encloses(c)); // Prints False + [/csharp] + [/codeblocks] </description> </method> <method name="expand" qualifiers="const"> <return type="AABB" /> <param index="0" name="to_point" type="Vector3" /> <description> - Returns a copy of this [AABB] expanded to include a given point. - [b]Example:[/b] + Returns a copy of this bounding box expanded to align the edges with the given [param to_point], if necessary. [codeblocks] [gdscript] - # position (-3, 2, 0), size (1, 1, 1) - var box = AABB(Vector3(-3, 2, 0), Vector3(1, 1, 1)) - # position (-3, -1, 0), size (3, 4, 2), so we fit both the original AABB and Vector3(0, -1, 2) - var box2 = box.expand(Vector3(0, -1, 2)) + var box = AABB(Vector3(0, 0, 0), Vector3(5, 2, 5)) + + box = box.expand(Vector3(10, 0, 0)) + print(box.position) # Prints (0, 0, 0) + print(box.size) # Prints (10, 2, 5) + + box = box.expand(Vector3(-5, 0, 5)) + print(box.position) # Prints (-5, 0, 0) + print(box.size) # Prints (15, 2, 5) [/gdscript] [csharp] - // position (-3, 2, 0), size (1, 1, 1) - var box = new Aabb(new Vector3(-3, 2, 0), new Vector3(1, 1, 1)); - // position (-3, -1, 0), size (3, 4, 2), so we fit both the original AABB and Vector3(0, -1, 2) - var box2 = box.Expand(new Vector3(0, -1, 2)); + var box = new Aabb(new Vector3(0, 0, 0), new Vector3(5, 2, 5)); + + box = box.Expand(new Vector3(10, 0, 0)); + GD.Print(box.Position); // Prints (0, 0, 0) + GD.Print(box.Size); // Prints (10, 2, 5) + + box = box.Expand(new Vector3(-5, 0, 5)); + GD.Print(box.Position); // Prints (-5, 0, 0) + GD.Print(box.Size); // Prints (15, 2, 5) [/csharp] [/codeblocks] </description> @@ -76,111 +120,188 @@ <method name="get_center" qualifiers="const"> <return type="Vector3" /> <description> - Returns the center of the [AABB], which is equal to [member position] + ([member size] / 2). + Returns the center point of the bounding box. This is the same as [code]position + (size / 2.0)[/code]. </description> </method> <method name="get_endpoint" qualifiers="const"> <return type="Vector3" /> <param index="0" name="idx" type="int" /> <description> - Gets the position of the 8 endpoints of the [AABB] in space. + Returns the position of one of the 8 vertices that compose this bounding box. With a [param idx] of [code]0[/code] this is the same as [member position], and a [param idx] of [code]7[/code] is the same as [member end]. </description> </method> <method name="get_longest_axis" qualifiers="const"> <return type="Vector3" /> <description> - Returns the normalized longest axis of the [AABB]. + Returns the longest 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)) + + print(box.get_longest_axis()) # Prints (0, 0, 1) + print(box.get_longest_axis_index()) # Prints 2 + print(box.get_longest_axis_size()) # Prints 8 + [/gdscript] + [csharp] + var box = new Aabb(new Vector3(0, 0, 0), new Vector3(2, 4, 8)); + + GD.Print(box.GetLongestAxis()); // Prints (0, 0, 1) + GD.Print(box.GetLongestAxisIndex()); // Prints 2 + GD.Print(box.GetLongestAxisSize()); // Prints 8 + [/csharp] + [/codeblocks] + See also [method get_longest_axis_index] and [method get_longest_axis_size]. </description> </method> <method name="get_longest_axis_index" qualifiers="const"> <return type="int" /> <description> - Returns the index of the longest axis of the [AABB] (according to [Vector3]'s [code]AXIS_*[/code] constants). + Returns the index to the longest axis of this bounding box's [member size] (see [constant Vector3.AXIS_X], [constant Vector3.AXIS_Y], and [constant Vector3.AXIS_Z]). + For an example, see [method get_longest_axis]. </description> </method> <method name="get_longest_axis_size" qualifiers="const"> <return type="float" /> <description> - Returns the scalar length of the longest axis of the [AABB]. + Returns the longest dimension of this bounding box's [member size]. + For an example, see [method get_longest_axis]. </description> </method> <method name="get_shortest_axis" qualifiers="const"> <return type="Vector3" /> <description> - Returns the normalized shortest axis of the [AABB]. + 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]). + [codeblocks] + [gdscript] + var box = AABB(Vector3(0, 0, 0), Vector3(2, 4, 8)) + + print(box.get_shortest_axis()) # Prints (1, 0, 0) + print(box.get_shortest_axis_index()) # Prints 0 + print(box.get_shortest_axis_size()) # Prints 2 + [/gdscript] + [csharp] + var box = new Aabb(new Vector3(0, 0, 0), new Vector3(2, 4, 8)); + + GD.Print(box.GetShortestAxis()); // Prints (1, 0, 0) + GD.Print(box.GetShortestAxisIndex()); // Prints 0 + GD.Print(box.GetShortestAxisSize()); // Prints 2 + [/csharp] + [/codeblocks] + See also [method get_shortest_axis_index] and [method get_shortest_axis_size]. </description> </method> <method name="get_shortest_axis_index" qualifiers="const"> <return type="int" /> <description> - Returns the index of the shortest axis of the [AABB] (according to [Vector3]::AXIS* enum). + Returns the index to the shortest axis of this bounding box's [member size] (see [constant Vector3.AXIS_X], [constant Vector3.AXIS_Y], and [constant Vector3.AXIS_Z]). + For an example, see [method get_shortest_axis]. </description> </method> <method name="get_shortest_axis_size" qualifiers="const"> <return type="float" /> <description> - Returns the scalar length of the shortest axis of the [AABB]. + Returns the shortest dimension of this bounding box's [member size]. + For an example, see [method get_shortest_axis]. </description> </method> <method name="get_support" qualifiers="const"> <return type="Vector3" /> <param index="0" name="dir" type="Vector3" /> <description> - Returns the vertex of the AABB that's the farthest in a given direction. This point is commonly known as the support point in collision detection algorithms. + Returns the vertex's position of this bounding box that's the farthest in the given direction. This point is commonly known as the support point in collision detection algorithms. </description> </method> <method name="get_volume" qualifiers="const"> <return type="float" /> <description> - Returns the volume of the [AABB]. + Returns the bounding box's volume. This is equivalent to [code]size.x * size.y * size.z[/code]. See also [method has_volume]. </description> </method> <method name="grow" qualifiers="const"> <return type="AABB" /> <param index="0" name="by" type="float" /> <description> - Returns a copy of the [AABB] grown a given number of units towards all the sides. + Returns a copy of this bounding box extended on all sides by the given amount [param by]. A negative amount shrinks the box instead. + [codeblocks] + [gdscript] + var a = AABB(Vector3(4, 4, 4), Vector3(8, 8, 8)).grow(4) + print(a.position) # Prints (0, 0, 0) + print(a.size) # Prints (16, 16, 16) + + var b = AABB(Vector3(0, 0, 0), Vector3(8, 4, 2)).grow(2) + print(b.position) # Prints (-2, -2, -2) + print(b.size) # Prints (12, 8, 6) + [/gdscript] + [csharp] + var a = new Aabb(new Vector3(4, 4, 4), new Vector3(8, 8, 8)).Grow(4); + GD.Print(a.Position); // Prints (0, 0, 0) + GD.Print(a.Size); // Prints (16, 16, 16) + + var b = new Aabb(new Vector3(0, 0, 0), new Vector3(8, 4, 2)).Grow(2); + GD.Print(b.Position); // Prints (-2, -2, -2) + GD.Print(b.Size); // Prints (12, 8, 6) + [/csharp] + [/codeblocks] </description> </method> <method name="has_point" qualifiers="const"> <return type="bool" /> <param index="0" name="point" type="Vector3" /> <description> - Returns [code]true[/code] if the [AABB] contains a point. Points on the faces of the AABB are considered included, though float-point precision errors may impact the accuracy of such checks. - [b]Note:[/b] This method is not reliable for [AABB] with a [i]negative size[/i]. Use [method abs] to get a positive sized equivalent [AABB] to check for contained points. + Returns [code]true[/code] if the bounding box contains the given [param point]. By convention, points exactly on the right, top, and front sides are [b]not[/b] included. + [b]Note:[/b] This method is not reliable for [AABB] with a [i]negative[/i] [member size]. Use [method abs] first to get a valid bounding box. </description> </method> <method name="has_surface" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if the [AABB] has a surface or a length, and [code]false[/code] if the [AABB] is empty (all components of [member size] are zero or negative). + Returns [code]true[/code] if this bounding box has a surface or a length, that is, at least one component of [member size] is greater than [code]0[/code]. Otherwise, returns [code]false[/code]. </description> </method> <method name="has_volume" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if the [AABB] has a volume, and [code]false[/code] if the [AABB] is flat, empty, or has a negative [member size]. + Returns [code]true[/code] if this bounding box's width, height, and depth are all positive. See also [method get_volume]. </description> </method> <method name="intersection" qualifiers="const"> <return type="AABB" /> <param index="0" name="with" type="AABB" /> <description> - Returns the intersection between two [AABB]. An empty AABB (size [code](0, 0, 0)[/code]) is returned on failure. + Returns the intersection between this bounding box and [param with]. If the boxes do not intersect, returns an empty [AABB]. If the boxes intersect at the edge, returns a flat [AABB] with no volume (see [method has_surface] and [method has_volume]). + [codeblocks] + [gdscript] + var box1 = AABB(Vector3(0, 0, 0), Vector3(5, 2, 8)) + var box2 = AABB(Vector3(2, 0, 2), Vector3(8, 4, 4)) + + var intersection = box1.intersection(box2) + print(intersection.position) # Prints (2, 0, 2) + print(intersection.size) # Prints (3, 2, 4) + [/gdscript] + [csharp] + var box1 = new Aabb(new Vector3(0, 0, 0), new Vector3(5, 2, 8)); + var box2 = new Aabb(new Vector3(2, 0, 2), new Vector3(8, 4, 4)); + + var intersection = box1.Intersection(box2); + GD.Print(intersection.Position); // Prints (2, 0, 2) + GD.Print(intersection.Size); // Prints (3, 2, 4) + [/csharp] + [/codeblocks] + [b]Note:[/b] If you only need to know whether two bounding boxes are intersecting, use [method intersects], instead. </description> </method> <method name="intersects" qualifiers="const"> <return type="bool" /> <param index="0" name="with" type="AABB" /> <description> - Returns [code]true[/code] if the [AABB] overlaps with another. + Returns [code]true[/code] if this bounding box overlaps with the box [param with]. The edges of both boxes are [i]always[/i] excluded. </description> </method> <method name="intersects_plane" qualifiers="const"> <return type="bool" /> <param index="0" name="plane" type="Plane" /> <description> - Returns [code]true[/code] if the [AABB] is on both sides of a plane. + Returns [code]true[/code] if this bounding box is on both sides of the given [param plane]. </description> </method> <method name="intersects_ray" qualifiers="const"> @@ -188,7 +309,8 @@ <param index="0" name="from" type="Vector3" /> <param index="1" name="dir" type="Vector3" /> <description> - Returns the point of intersection of the given ray with this [AABB] or [code]null[/code] if there is no intersection. Ray length is infinite. + Returns the first point where this bounding box and the given ray intersect, as a [Vector3]. If no intersection occurs, returns [code]null[/code]. + The ray begin at [param from], faces [param dir] and extends towards infinity. </description> </method> <method name="intersects_segment" qualifiers="const"> @@ -196,40 +318,41 @@ <param index="0" name="from" type="Vector3" /> <param index="1" name="to" type="Vector3" /> <description> - Returns the point of intersection between [param from] and [param to] with this [AABB] or [code]null[/code] if there is no intersection. + Returns the first point where this bounding box and the given segment intersect, as a [Vector3]. If no intersection occurs, returns [code]null[/code]. + The segment begins at [param from] and ends at [param to]. </description> </method> <method name="is_equal_approx" qualifiers="const"> <return type="bool" /> <param index="0" name="aabb" type="AABB" /> <description> - Returns [code]true[/code] if this [AABB] and [param aabb] are approximately equal, by calling [method @GlobalScope.is_equal_approx] on each component. + Returns [code]true[/code] if this bounding box and [param aabb] are approximately equal, by calling [method Vector2.is_equal_approx] on the [member position] and the [member size]. </description> </method> <method name="is_finite" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if this [AABB] is finite, by calling [method @GlobalScope.is_finite] on each component. + Returns [code]true[/code] if this bounding box's values are finite, by calling [method Vector2.is_finite] on the [member position] and the [member size]. </description> </method> <method name="merge" qualifiers="const"> <return type="AABB" /> <param index="0" name="with" type="AABB" /> <description> - Returns a larger [AABB] that contains both this [AABB] and [param with]. + Returns an [AABB] that encloses both this bounding box and [param with] around the edges. See also [method encloses]. </description> </method> </methods> <members> <member name="end" type="Vector3" setter="" getter="" default="Vector3(0, 0, 0)"> - Ending corner. This is calculated as [code]position + size[/code]. Setting this value will change the size. + The ending point. This is usually the corner on the top-right and forward of the bounding box, and is equivalent to [code]position + size[/code]. Setting this point affects the [member size]. </member> <member name="position" type="Vector3" setter="" getter="" default="Vector3(0, 0, 0)"> - Beginning corner. Typically has values lower than [member end]. + The origin point. This is usually the corner on the bottom-left and back of the bounding box. </member> <member name="size" type="Vector3" setter="" getter="" default="Vector3(0, 0, 0)"> - Size from [member position] to [member end]. Typically, all components are positive. - If the size is negative, you can use [method abs] to fix it. + The bounding box's width, height, and depth starting from [member position]. Setting this value also affects the [member end] point. + [b]Note:[/b] It's recommended setting the width, height, and depth to non-negative values. This is because most methods in Godot assume that the [member position] is the bottom-left-back corner, and the [member end] is the top-right-forward corner. To get an equivalent bounding box with non-negative size, use [method abs]. </member> </members> <operators> @@ -237,7 +360,7 @@ <return type="bool" /> <param index="0" name="right" type="AABB" /> <description> - Returns [code]true[/code] if the AABBs are not equal. + Returns [code]true[/code] if the [member position] or [member size] of both bounding boxes 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> @@ -254,7 +377,7 @@ <return type="bool" /> <param index="0" name="right" type="AABB" /> <description> - Returns [code]true[/code] if the AABBs are exactly equal. + Returns [code]true[/code] if both [member position] and [member size] of the bounding boxes are exactly equal, respectively. [b]Note:[/b] Due to floating-point precision errors, consider using [method is_equal_approx] instead, which is more reliable. </description> </operator> diff --git a/doc/classes/Animation.xml b/doc/classes/Animation.xml index 15f6b16439..2a88e70818 100644 --- a/doc/classes/Animation.xml +++ b/doc/classes/Animation.xml @@ -8,21 +8,23 @@ [codeblocks] [gdscript] # This creates an animation that makes the node "Enemy" move to the right by - # 100 pixels in 0.5 seconds. + # 100 pixels in 2.0 seconds. var animation = Animation.new() var track_index = animation.add_track(Animation.TYPE_VALUE) animation.track_set_path(track_index, "Enemy:position:x") animation.track_insert_key(track_index, 0.0, 0) - animation.track_insert_key(track_index, 0.5, 100) + animation.track_insert_key(track_index, 2.0, 100) + animation.length = 2.0 [/gdscript] [csharp] // This creates an animation that makes the node "Enemy" move to the right by - // 100 pixels in 0.5 seconds. + // 100 pixels in 2.0 seconds. var animation = new Animation(); int trackIndex = animation.AddTrack(Animation.TrackType.Value); animation.TrackSetPath(trackIndex, "Enemy:position:x"); animation.TrackInsertKey(trackIndex, 0.0f, 0); - animation.TrackInsertKey(trackIndex, 0.5f, 100); + animation.TrackInsertKey(trackIndex, 2.0f, 100); + animation.Length = 2.0f; [/csharp] [/codeblocks] Animations are just data containers, and must be added to nodes such as an [AnimationPlayer] to be played back. Animation tracks have different types, each with its own set of dedicated methods. Check [enum TrackType] to see available types. diff --git a/doc/classes/AnimationMixer.xml b/doc/classes/AnimationMixer.xml index 4a489a3ef2..31308c4e20 100644 --- a/doc/classes/AnimationMixer.xml +++ b/doc/classes/AnimationMixer.xml @@ -15,10 +15,10 @@ <param index="0" name="animation" type="Animation" /> <param index="1" name="track" type="int" /> <param index="2" name="value" type="Variant" /> - <param index="3" name="object" type="Object" /> - <param index="4" name="object_idx" type="int" /> + <param index="3" name="object_id" type="int" /> + <param index="4" name="object_sub_idx" type="int" /> <description> - A virtual function for processing after key getting during playback. + A virtual function for processing after getting a key during playback. </description> </method> <method name="add_animation_library"> diff --git a/doc/classes/AnimationNodeStateMachine.xml b/doc/classes/AnimationNodeStateMachine.xml index 1c96110540..86311542ad 100644 --- a/doc/classes/AnimationNodeStateMachine.xml +++ b/doc/classes/AnimationNodeStateMachine.xml @@ -182,7 +182,7 @@ Seeking to the beginning is treated as seeking to the beginning of the animation in the current state. Transition to the end state, or the absence of transitions in each state, is treated as exiting the state machine. </constant> <constant name="STATE_MACHINE_TYPE_GROUPED" value="2" enum="StateMachineType"> - This is a grouped state machine that can be controlled from a parent state machine. It does not work on standalone. There must be a state machine with [member state_machine_type] of [constant STATE_MACHINE_TYPE_ROOT] or [constant STATE_MACHINE_TYPE_NESTED] in the parent or ancestor. + This is a grouped state machine that can be controlled from a parent state machine. It does not work independently. There must be a state machine with [member state_machine_type] of [constant STATE_MACHINE_TYPE_ROOT] or [constant STATE_MACHINE_TYPE_NESTED] in the parent or ancestor. </constant> </constants> </class> diff --git a/doc/classes/Array.xml b/doc/classes/Array.xml index 3252cbf840..39b9dde043 100644 --- a/doc/classes/Array.xml +++ b/doc/classes/Array.xml @@ -479,7 +479,7 @@ <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 untouched 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. + 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. </description> </method> diff --git a/doc/classes/AudioEffectCapture.xml b/doc/classes/AudioEffectCapture.xml index 275e5ab0b6..e17c510907 100644 --- a/doc/classes/AudioEffectCapture.xml +++ b/doc/classes/AudioEffectCapture.xml @@ -6,11 +6,10 @@ <description> AudioEffectCapture is an AudioEffect which copies all audio frames from the attached audio effect bus into its internal ring buffer. Application code should consume these audio frames from this ring buffer using [method get_buffer] and process it as needed, for example to capture data from an [AudioStreamMicrophone], implement application-defined effects, or to transmit audio over the network. When capturing audio data from a microphone, the format of the samples will be stereo 32-bit floating point PCM. - [b]Note:[/b] [member ProjectSettings.audio/driver/enable_input] must be [code]true[/code] for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings. + Unlike [AudioEffectRecord], this effect only returns the raw audio samples instead of encoding them into an [AudioStream]. </description> <tutorials> <link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link> - <link title="Audio Mic Record Demo">https://github.com/godotengine/godot-demo-projects/tree/master/audio/mic_record</link> </tutorials> <methods> <method name="can_get_buffer" qualifiers="const"> diff --git a/doc/classes/AudioEffectPitchShift.xml b/doc/classes/AudioEffectPitchShift.xml index ec60e6a75a..4d4baa34ab 100644 --- a/doc/classes/AudioEffectPitchShift.xml +++ b/doc/classes/AudioEffectPitchShift.xml @@ -18,7 +18,7 @@ The oversampling factor to use. Higher values result in better quality, but are more demanding on the CPU and may cause audio cracking if the CPU can't keep up. </member> <member name="pitch_scale" type="float" setter="set_pitch_scale" getter="get_pitch_scale" default="1.0"> - The pitch scale to use. [code]1.0[/code] is the default pitch and plays sounds unaltered. [member pitch_scale] can range from [code]0.0[/code] (infinitely low pitch, inaudible) to [code]16[/code] (16 times higher than the initial pitch). + The pitch scale to use. [code]1.0[/code] is the default pitch and plays sounds unaffected. [member pitch_scale] can range from [code]0.0[/code] (infinitely low pitch, inaudible) to [code]16[/code] (16 times higher than the initial pitch). </member> </members> <constants> diff --git a/doc/classes/AudioEffectRecord.xml b/doc/classes/AudioEffectRecord.xml index e07d66fa7b..5b43c5ebaa 100644 --- a/doc/classes/AudioEffectRecord.xml +++ b/doc/classes/AudioEffectRecord.xml @@ -4,9 +4,10 @@ Audio effect used for recording the sound from an audio bus. </brief_description> <description> - Allows the user to record the sound from an audio bus. This can include all audio output by Godot when used on the "Master" audio bus. + Allows the user to record the sound from an audio bus into an [AudioStreamWAV]. When used on the "Master" audio bus, this includes all audio output by Godot. + Unlike [AudioEffectCapture], this effect encodes the recording with the given format (8-bit, 16-bit, or compressed) instead of giving access to the raw audio samples. Can be used (with an [AudioStreamMicrophone]) to record from a microphone. - It sets and gets the format in which the audio file will be recorded (8-bit, 16-bit, or compressed). It checks whether or not the recording is active, and if it is, records the sound. It then returns the recorded sample. + [b]Note:[/b] [member ProjectSettings.audio/driver/enable_input] must be [code]true[/code] for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings. </description> <tutorials> <link title="Recording with microphone">$DOCS_URL/tutorials/audio/recording_with_microphone.html</link> diff --git a/doc/classes/AudioStream.xml b/doc/classes/AudioStream.xml index 12e09b235f..6e30775fee 100644 --- a/doc/classes/AudioStream.xml +++ b/doc/classes/AudioStream.xml @@ -28,6 +28,12 @@ <description> </description> </method> + <method name="_get_parameter_list" qualifiers="virtual const"> + <return type="Dictionary[]" /> + <description> + Return the controllable parameters of this stream. This array contains dictionaries with a property info description format (see [method Object.get_property_list]). Additionally, the default value for this parameter must be added tho each dictionary in "default_value" field. + </description> + </method> <method name="_get_stream_name" qualifiers="virtual const"> <return type="String" /> <description> @@ -62,4 +68,11 @@ </description> </method> </methods> + <signals> + <signal name="parameter_list_changed"> + <description> + Signal to be emitted to notify when the parameter list changed. + </description> + </signal> + </signals> </class> diff --git a/doc/classes/AudioStreamPlayback.xml b/doc/classes/AudioStreamPlayback.xml index 7692690b5e..a090989194 100644 --- a/doc/classes/AudioStreamPlayback.xml +++ b/doc/classes/AudioStreamPlayback.xml @@ -15,6 +15,13 @@ <description> </description> </method> + <method name="_get_parameter" qualifiers="virtual const"> + <return type="Variant" /> + <param index="0" name="name" type="StringName" /> + <description> + Return the current value of a playback parameter by name (see [method AudioStream._get_parameter_list]). + </description> + </method> <method name="_get_playback_position" qualifiers="virtual const"> <return type="float" /> <description> @@ -39,6 +46,14 @@ <description> </description> </method> + <method name="_set_parameter" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="name" type="StringName" /> + <param index="1" name="value" type="Variant" /> + <description> + Set the current value of a playback parameter by name (see [method AudioStream._get_parameter_list]). + </description> + </method> <method name="_start" qualifiers="virtual"> <return type="void" /> <param index="0" name="from_pos" type="float" /> diff --git a/doc/classes/CanvasItem.xml b/doc/classes/CanvasItem.xml index 2f76f64cff..6f4dc47fb9 100644 --- a/doc/classes/CanvasItem.xml +++ b/doc/classes/CanvasItem.xml @@ -501,7 +501,7 @@ <method name="is_visible_in_tree" qualifiers="const"> <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 consequently not drawn (see [method _draw]). + 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]). </description> </method> <method name="make_canvas_position_local" qualifiers="const"> diff --git a/doc/classes/CanvasTexture.xml b/doc/classes/CanvasTexture.xml index 1b22adb723..a14f71cc46 100644 --- a/doc/classes/CanvasTexture.xml +++ b/doc/classes/CanvasTexture.xml @@ -5,7 +5,7 @@ </brief_description> <description> [CanvasTexture] is an alternative to [ImageTexture] for 2D rendering. It allows using normal maps and specular maps in any node that inherits from [CanvasItem]. [CanvasTexture] also allows overriding the texture's filter and repeat mode independently of the node's properties (or the project settings). - [b]Note:[/b] [CanvasTexture] cannot be used in 3D rendering. For physically-based materials in 3D, use [BaseMaterial3D] instead. + [b]Note:[/b] [CanvasTexture] cannot be used in 3D. It will not display correctly when applied to any [VisualInstance3D], such as [Sprite3D] or [Decal]. For physically-based materials in 3D, use [BaseMaterial3D] instead. </description> <tutorials> <link title="2D Lights and Shadows">$DOCS_URL/tutorials/2d/2d_lights_and_shadows.html</link> diff --git a/doc/classes/CollisionPolygon2D.xml b/doc/classes/CollisionPolygon2D.xml index d6f3b7cb5d..acb3f66c17 100644 --- a/doc/classes/CollisionPolygon2D.xml +++ b/doc/classes/CollisionPolygon2D.xml @@ -25,6 +25,7 @@ </member> <member name="polygon" type="PackedVector2Array" setter="set_polygon" getter="get_polygon" default="PackedVector2Array()"> The polygon's list of vertices. Each point will be connected to the next, and the final point will be connected to the first. + [b]Note:[/b] The returned vertices are in the local coordinate space of the given [CollisionPolygon2D]. [b]Warning:[/b] The returned value is a clone of the [PackedVector2Array], not a reference. </member> </members> diff --git a/doc/classes/DisplayServer.xml b/doc/classes/DisplayServer.xml index 8436cbf6ee..2d4c2c9682 100644 --- a/doc/classes/DisplayServer.xml +++ b/doc/classes/DisplayServer.xml @@ -1754,7 +1754,7 @@ The ID of the main window spawned by the engine, which can be passed to methods expecting a [code]window_id[/code]. </constant> <constant name="INVALID_WINDOW_ID" value="-1"> - The ID that refers to a nonexisting window. This is be returned by some [DisplayServer] methods if no window matches the requested result. + The ID that refers to a nonexistent window. This is returned by some [DisplayServer] methods if no window matches the requested result. </constant> <constant name="SCREEN_LANDSCAPE" value="0" enum="ScreenOrientation"> Default landscape orientation. @@ -1955,16 +1955,16 @@ [b]Note:[/b] This flag is implemented only on macOS. </constant> <constant name="VSYNC_DISABLED" value="0" enum="VSyncMode"> - No vertical synchronization, which means the engine will display frames as fast as possible (tearing may be visible). Framerate is unlimited (notwithstanding [member Engine.max_fps]). + No vertical synchronization, which means the engine will display frames as fast as possible (tearing may be visible). Framerate is unlimited (regardless of [member Engine.max_fps]). </constant> <constant name="VSYNC_ENABLED" value="1" enum="VSyncMode"> - Default vertical synchronization mode, the image is displayed only on vertical blanking intervals (no tearing is visible). Framerate is limited by the monitor refresh rate (notwithstanding [member Engine.max_fps]). + Default vertical synchronization mode, the image is displayed only on vertical blanking intervals (no tearing is visible). Framerate is limited by the monitor refresh rate (regardless of [member Engine.max_fps]). </constant> <constant name="VSYNC_ADAPTIVE" value="2" enum="VSyncMode"> - Behaves like [constant VSYNC_DISABLED] when the framerate drops below the screen's refresh rate to reduce stuttering (tearing may be visible). Otherwise, vertical synchronization is enabled to avoid tearing. Framerate is limited by the monitor refresh rate (notwithstanding [member Engine.max_fps]). Behaves like [constant VSYNC_ENABLED] when using the Compatibility rendering method. + Behaves like [constant VSYNC_DISABLED] when the framerate drops below the screen's refresh rate to reduce stuttering (tearing may be visible). Otherwise, vertical synchronization is enabled to avoid tearing. Framerate is limited by the monitor refresh rate (regardless of [member Engine.max_fps]). Behaves like [constant VSYNC_ENABLED] when using the Compatibility rendering method. </constant> <constant name="VSYNC_MAILBOX" value="3" enum="VSyncMode"> - Displays the most recent image in the queue on vertical blanking intervals, while rendering to the other images (no tearing is visible). Framerate is unlimited (notwithstanding [member Engine.max_fps]). + Displays the most recent image in the queue on vertical blanking intervals, while rendering to the other images (no tearing is visible). Framerate is unlimited (regardless of [member Engine.max_fps]). Although not guaranteed, the images can be rendered as fast as possible, which may reduce input lag (also called "Fast" V-Sync mode). [constant VSYNC_MAILBOX] works best when at least twice as many frames as the display refresh rate are rendered. Behaves like [constant VSYNC_ENABLED] when using the Compatibility rendering method. </constant> <constant name="DISPLAY_HANDLE" value="0" enum="HandleType"> diff --git a/doc/classes/EditorImportPlugin.xml b/doc/classes/EditorImportPlugin.xml index 82ba956151..88a6eeec26 100644 --- a/doc/classes/EditorImportPlugin.xml +++ b/doc/classes/EditorImportPlugin.xml @@ -120,6 +120,13 @@ <link title="Import plugins">$DOCS_URL/tutorials/plugins/editor/import_plugins.html</link> </tutorials> <methods> + <method name="_can_import_threaded" qualifiers="virtual const"> + <return type="bool" /> + <description> + Tells whether this importer can be run in parallel on threads, or, on the contrary, it's only safe for the editor to call it from the main thread, for one file at a time. + If this method is not overridden, it will return [code]true[/code] by default (i.e., safe for parallel importing). + </description> + </method> <method name="_get_import_options" qualifiers="virtual const"> <return type="Dictionary[]" /> <param index="0" name="path" type="String" /> diff --git a/doc/classes/EditorNode3DGizmo.xml b/doc/classes/EditorNode3DGizmo.xml index 1680400384..7597489601 100644 --- a/doc/classes/EditorNode3DGizmo.xml +++ b/doc/classes/EditorNode3DGizmo.xml @@ -9,6 +9,13 @@ <tutorials> </tutorials> <methods> + <method name="_begin_handle_action" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="id" type="int" /> + <param index="1" name="secondary" type="bool" /> + <description> + </description> + </method> <method name="_commit_handle" qualifiers="virtual"> <return type="void" /> <param index="0" name="id" type="int" /> diff --git a/doc/classes/EditorNode3DGizmoPlugin.xml b/doc/classes/EditorNode3DGizmoPlugin.xml index da7ee17335..8fd7c167d9 100644 --- a/doc/classes/EditorNode3DGizmoPlugin.xml +++ b/doc/classes/EditorNode3DGizmoPlugin.xml @@ -11,6 +11,14 @@ <link title="Node3D gizmo plugins">$DOCS_URL/tutorials/plugins/editor/3d_gizmos.html</link> </tutorials> <methods> + <method name="_begin_handle_action" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="gizmo" type="EditorNode3DGizmo" /> + <param index="1" name="handle_id" type="int" /> + <param index="2" name="secondary" type="bool" /> + <description> + </description> + </method> <method name="_can_be_hidden" qualifiers="virtual const"> <return type="bool" /> <description> diff --git a/doc/classes/EditorPlugin.xml b/doc/classes/EditorPlugin.xml index 148a6541a2..407d64e9a2 100644 --- a/doc/classes/EditorPlugin.xml +++ b/doc/classes/EditorPlugin.xml @@ -759,7 +759,7 @@ <signal name="resource_saved"> <param index="0" name="resource" type="Resource" /> <description> - Emitted when the given [param resource] was saved on disc. + Emitted when the given [param resource] was saved on disc. See also [signal scene_saved]. </description> </signal> <signal name="scene_changed"> @@ -771,7 +771,13 @@ <signal name="scene_closed"> <param index="0" name="filepath" type="String" /> <description> - Emitted when user closes a scene. The argument is file path to a closed scene. + Emitted when user closes a scene. The argument is a file path to the closed scene. + </description> + </signal> + <signal name="scene_saved"> + <param index="0" name="filepath" type="String" /> + <description> + Emitted when a scene was saved on disc. The argument is a file path to the saved scene. See also [signal resource_saved]. </description> </signal> </signals> diff --git a/doc/classes/EditorSettings.xml b/doc/classes/EditorSettings.xml index 5c317a5088..b7f3ec9963 100644 --- a/doc/classes/EditorSettings.xml +++ b/doc/classes/EditorSettings.xml @@ -662,12 +662,16 @@ <member name="interface/theme/accent_color" type="Color" setter="" getter=""> The color to use for "highlighted" user interface elements in the editor (pressed and hovered items). </member> - <member name="interface/theme/additional_spacing" type="float" setter="" getter=""> - The spacing to add for buttons and list items in the editor (in pixels). Increasing this value is useful to improve usability on touch screens, at the cost of reducing the amount of usable screen real estate. + <member name="interface/theme/additional_spacing" type="int" setter="" getter=""> + The extra spacing to add to various GUI elements in the editor (in pixels). Increasing this value is useful to improve usability on touch screens, at the cost of reducing the amount of usable screen real estate. + See also [member interface/theme/spacing_preset]. </member> <member name="interface/theme/base_color" type="Color" setter="" getter=""> The base color to use for user interface elements in the editor. Secondary colors (such as darker/lighter variants) are derived from this color. </member> + <member name="interface/theme/base_spacing" type="int" setter="" getter=""> + The base spacing used by various GUI elements in the editor (in pixels). See also [member interface/theme/spacing_preset]. + </member> <member name="interface/theme/border_size" type="int" setter="" getter=""> The border size to use for interface elements (in pixels). </member> @@ -699,6 +703,9 @@ <member name="interface/theme/relationship_line_opacity" type="float" setter="" getter=""> The opacity to use when drawing relationship lines in the editor's [Tree]-based GUIs (such as the Scene tree dock). </member> + <member name="interface/theme/spacing_preset" type="String" setter="" getter=""> + The editor theme spacing preset to use. See also [member interface/theme/base_spacing] and [member interface/theme/additional_spacing]. + </member> <member name="interface/touchscreen/enable_long_press_as_right_click" type="bool" setter="" getter=""> If [code]true[/code], long press on touchscreen is treated as right click. [b]Note:[/b] Defaults to [code]true[/code] on touchscreen devices. diff --git a/doc/classes/Engine.xml b/doc/classes/Engine.xml index 0a544077e4..653dc4fd88 100644 --- a/doc/classes/Engine.xml +++ b/doc/classes/Engine.xml @@ -293,7 +293,7 @@ Controls the maximum number of physics steps that can be simulated each rendered frame. The default value is tuned to avoid "spiral of death" situations where expensive physics simulations trigger more expensive simulations indefinitely. However, the game will appear to slow down if the rendering FPS is less than [code]1 / max_physics_steps_per_frame[/code] of [member physics_ticks_per_second]. This occurs even if [code]delta[/code] is consistently used in physics calculations. To avoid this, increase [member max_physics_steps_per_frame] if you have increased [member physics_ticks_per_second] significantly above its default value. </member> <member name="physics_jitter_fix" type="float" setter="set_physics_jitter_fix" getter="get_physics_jitter_fix" default="0.5"> - Controls how much physics ticks are synchronized with real time. For 0 or less, the ticks are synchronized. Such values are recommended for network games, where clock synchronization matters. Higher values cause higher deviation of the in-game clock and real clock but smooth out framerate jitters. The default value of 0.5 should be fine for most; values above 2 could cause the game to react to dropped frames with a noticeable delay and are not recommended. + Controls how much physics ticks are synchronized with real time. For 0 or less, the ticks are synchronized. Such values are recommended for network games, where clock synchronization matters. Higher values cause higher deviation of the in-game clock and real clock but smooth out framerate jitters. The default value of 0.5 should be good enough for most; values above 2 could cause the game to react to dropped frames with a noticeable delay and are not recommended. [b]Note:[/b] For best results, when using a custom physics interpolation solution, the physics jitter fix should be disabled by setting [member physics_jitter_fix] to [code]0[/code]. </member> <member name="physics_ticks_per_second" type="int" setter="set_physics_ticks_per_second" getter="get_physics_ticks_per_second" default="60"> diff --git a/doc/classes/GDExtension.xml b/doc/classes/GDExtension.xml index ee55c89131..533b32218f 100644 --- a/doc/classes/GDExtension.xml +++ b/doc/classes/GDExtension.xml @@ -1,31 +1,42 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="GDExtension" inherits="Resource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> + A native library for GDExtension. </brief_description> <description> + The [GDExtension] resource type represents a [url=https://en.wikipedia.org/wiki/Shared_library]shared library[/url] which can expand the functionality of the engine. The [GDExtensionManager] singleton is responsible for loading, reloading, and unloading [GDExtension] resources. + [b]Note:[/b] GDExtension itself is not a scripting language and has no relation to [GDScript] resources. </description> <tutorials> + <link title="GDExtension overview">$DOCS_URL/tutorials/scripting/gdextension/what_is_gdextension.html</link> + <link title="GDExtension example in C++">$DOCS_URL/tutorials/scripting/gdextension/gdextension_cpp_example.html</link> </tutorials> <methods> <method name="close_library"> <return type="void" /> <description> + Closes the current library. + [b]Note:[/b] You normally should not call this method directly. This is handled automatically by [method GDExtensionManager.unload_extension]. </description> </method> <method name="get_minimum_library_initialization_level" qualifiers="const"> <return type="int" enum="GDExtension.InitializationLevel" /> <description> + Returns the lowest level required for this extension to be properly initialized (see the [enum InitializationLevel] enum). </description> </method> <method name="initialize_library"> <return type="void" /> <param index="0" name="level" type="int" enum="GDExtension.InitializationLevel" /> <description> + Initializes the library bound to this GDextension at the given initialization [param level]. + [b]Note:[/b] You normally should not call this method directly. This is handled automatically by [method GDExtensionManager.load_extension]. </description> </method> <method name="is_library_open" qualifiers="const"> <return type="bool" /> <description> + Returns [code]true[/code] if this extension's library has been opened. </description> </method> <method name="open_library"> @@ -33,17 +44,23 @@ <param index="0" name="path" type="String" /> <param index="1" name="entry_symbol" type="String" /> <description> + Opens the library at the specified [param path]. + [b]Note:[/b] You normally should not call this method directly. This is handled automatically by [method GDExtensionManager.load_extension]. </description> </method> </methods> <constants> <constant name="INITIALIZATION_LEVEL_CORE" value="0" enum="InitializationLevel"> + The library is initialized at the same time as the core features of the engine. </constant> <constant name="INITIALIZATION_LEVEL_SERVERS" value="1" enum="InitializationLevel"> + The library is initialized at the same time as the engine's servers (such as [RenderingServer] or [PhysicsServer3D]). </constant> <constant name="INITIALIZATION_LEVEL_SCENE" value="2" enum="InitializationLevel"> + The library is initialized at the same time as the engine's scene-related classes. </constant> <constant name="INITIALIZATION_LEVEL_EDITOR" value="3" enum="InitializationLevel"> + The library is initialized at the same time as the engine's editor classes. Only happens when loading the GDExtension in the editor. </constant> </constants> </class> diff --git a/doc/classes/GDExtensionManager.xml b/doc/classes/GDExtensionManager.xml index 8d2515dc28..1ecb23a03b 100644 --- a/doc/classes/GDExtensionManager.xml +++ b/doc/classes/GDExtensionManager.xml @@ -1,65 +1,82 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="GDExtensionManager" inherits="Object" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> + Provides access to GDExtension functionality. </brief_description> <description> + The GDExtensionManager loads, initializes, and keeps track of all available [GDExtension] libraries in the project. + [b]Note:[/b] Do not worry about GDExtension unless you know what you are doing. </description> <tutorials> + <link title="GDExtension overview">$DOCS_URL/tutorials/scripting/gdextension/what_is_gdextension.html</link> + <link title="GDExtension example in C++">$DOCS_URL/tutorials/scripting/gdextension/gdextension_cpp_example.html</link> </tutorials> <methods> <method name="get_extension"> <return type="GDExtension" /> <param index="0" name="path" type="String" /> <description> + Returns the [GDExtension] at the given file [param path], or [code]null[/code] if it has not been loaded or does not exist. </description> </method> <method name="get_loaded_extensions" qualifiers="const"> <return type="PackedStringArray" /> <description> + Returns the file paths of all currently loaded extensions. </description> </method> <method name="is_extension_loaded" qualifiers="const"> <return type="bool" /> <param index="0" name="path" type="String" /> <description> + Returns [code]true[/code] if the extension at the given file [param path] has already been loaded successfully. See also [method get_loaded_extensions]. </description> </method> <method name="load_extension"> <return type="int" enum="GDExtensionManager.LoadStatus" /> <param index="0" name="path" type="String" /> <description> + Loads an extension by absolute file path. The [param path] needs to point to a valid [GDExtension]. Returns [constant LOAD_STATUS_OK] if successful. </description> </method> <method name="reload_extension"> <return type="int" enum="GDExtensionManager.LoadStatus" /> <param index="0" name="path" type="String" /> <description> + Reloads the extension at the given file path. The [param path] needs to point to a valid [GDExtension], otherwise this method may return either [constant LOAD_STATUS_NOT_LOADED] or [constant LOAD_STATUS_FAILED]. + [b]Note:[/b] You can only reload extensions in the editor. In release builds, this method always fails and returns [constant LOAD_STATUS_FAILED]. </description> </method> <method name="unload_extension"> <return type="int" enum="GDExtensionManager.LoadStatus" /> <param index="0" name="path" type="String" /> <description> + Unloads an extension by file path. The [param path] needs to point to an already loaded [GDExtension], otherwise this method returns [constant LOAD_STATUS_NOT_LOADED]. </description> </method> </methods> <signals> <signal name="extensions_reloaded"> <description> - Emitted after the editor has automatically reloaded any extensions. + Emitted after the editor has finished reloading one or more extensions. </description> </signal> </signals> <constants> <constant name="LOAD_STATUS_OK" value="0" enum="LoadStatus"> + The extension has loaded successfully. </constant> <constant name="LOAD_STATUS_FAILED" value="1" enum="LoadStatus"> + The extension has failed to load, possibly because it does not exist or has missing dependencies. </constant> <constant name="LOAD_STATUS_ALREADY_LOADED" value="2" enum="LoadStatus"> + The extension has already been loaded. </constant> <constant name="LOAD_STATUS_NOT_LOADED" value="3" enum="LoadStatus"> + The extension has not been loaded. </constant> <constant name="LOAD_STATUS_NEEDS_RESTART" value="4" enum="LoadStatus"> + The extension requires the application to restart to fully load. </constant> </constants> </class> diff --git a/doc/classes/GeometryInstance3D.xml b/doc/classes/GeometryInstance3D.xml index 990efbb3a4..6b0d2e4a62 100644 --- a/doc/classes/GeometryInstance3D.xml +++ b/doc/classes/GeometryInstance3D.xml @@ -34,7 +34,7 @@ The selected shadow casting flag. See [enum ShadowCastingSetting] for possible values. </member> <member name="custom_aabb" type="AABB" setter="set_custom_aabb" getter="get_custom_aabb" default="AABB(0, 0, 0, 0, 0, 0)"> - Overrides the bounding box of this node with a custom one. This can be used to avoid the expensive [AABB] recalculation that happens when a skeleton is used with a [MeshInstance3D] or to have fine control over the [MeshInstance3D]'s bounding box. To use the default AABB, set value to an [AABB] with all fields set to [code]0.0[/code]. To avoid frustum culling, set [member custom_aabb] to a very large AABB that covers your entire game world such as [code]AABB(-10000, -10000, -10000, 20000, 20000, 20000)[/code]. To disable all forms of culling (including occlusion culling), call [method RenderingServer.instance_set_ignore_culling] on the [GeometryInstance3D]'s [RID]. + Overrides the bounding box of this node with a custom one. This can be used to avoid the expensive [AABB] recalculation that happens when a skeleton is used with a [MeshInstance3D] or to have precise control over the [MeshInstance3D]'s bounding box. To use the default AABB, set value to an [AABB] with all fields set to [code]0.0[/code]. To avoid frustum culling, set [member custom_aabb] to a very large AABB that covers your entire game world such as [code]AABB(-10000, -10000, -10000, 20000, 20000, 20000)[/code]. To disable all forms of culling (including occlusion culling), call [method RenderingServer.instance_set_ignore_culling] on the [GeometryInstance3D]'s [RID]. </member> <member name="extra_cull_margin" type="float" setter="set_extra_cull_margin" getter="get_extra_cull_margin" default="0.0"> The extra distance added to the GeometryInstance3D's bounding box ([AABB]) to increase its cull box. diff --git a/doc/classes/GraphEdit.xml b/doc/classes/GraphEdit.xml index 95e760be9f..e5952d9f71 100644 --- a/doc/classes/GraphEdit.xml +++ b/doc/classes/GraphEdit.xml @@ -143,7 +143,22 @@ [b]Note:[/b] This method suppresses any other connection request signals apart from [signal connection_drag_ended]. </description> </method> - <method name="get_connection_line"> + <method name="get_closest_connection_at_point" qualifiers="const"> + <return type="Dictionary" /> + <param index="0" name="point" type="Vector2" /> + <param index="1" name="max_distance" type="float" default="4.0" /> + <description> + Returns the closest connection to the given point in screen space. If no connection is found within [param max_distance] pixels, an empty [Dictionary] is returned. + A connection consists in a structure of the form [code]{ from_port: 0, from_node: "GraphNode name 0", to_port: 1, to_node: "GraphNode name 1" }[/code]. + For example, getting a connection at a given mouse position can be achieved like this: + [codeblocks] + [gdscript] + var connection = get_closest_connection_at_point(mouse_event.get_position()) + [/gdscript] + [/codeblocks] + </description> + </method> + <method name="get_connection_line" qualifiers="const"> <return type="PackedVector2Array" /> <param index="0" name="from_node" type="Vector2" /> <param index="1" name="to_node" type="Vector2" /> @@ -154,7 +169,14 @@ <method name="get_connection_list" qualifiers="const"> <return type="Dictionary[]" /> <description> - Returns an Array containing the list of connections. A connection consists in a structure of the form [code]{ from_port: 0, from_node: "GraphNode name 0", to_port: 1, to_node: "GraphNode name 1" }[/code]. + Returns an [Array] containing the list of connections. A connection consists in a structure of the form [code]{ from_port: 0, from_node: "GraphNode name 0", to_port: 1, to_node: "GraphNode name 1" }[/code]. + </description> + </method> + <method name="get_connections_intersecting_with_rect" qualifiers="const"> + <return type="Dictionary[]" /> + <param index="0" name="rect" type="Rect2" /> + <description> + Returns an [Array] containing the list of connections that intersect with the given [Rect2]. A connection consists in a structure of the form [code]{ from_port: 0, from_node: "GraphNode name 0", to_port: 1, to_node: "GraphNode name 1" }[/code]. </description> </method> <method name="get_menu_hbox"> @@ -233,7 +255,7 @@ <member name="connection_lines_curvature" type="float" setter="set_connection_lines_curvature" getter="get_connection_lines_curvature" default="0.5"> The curvature of the lines between the nodes. 0 results in straight lines. </member> - <member name="connection_lines_thickness" type="float" setter="set_connection_lines_thickness" getter="get_connection_lines_thickness" default="2.0"> + <member name="connection_lines_thickness" type="float" setter="set_connection_lines_thickness" getter="get_connection_lines_thickness" default="4.0"> The thickness of the lines between the nodes. </member> <member name="focus_mode" type="int" setter="set_focus_mode" getter="get_focus_mode" overrides="Control" enum="Control.FocusMode" default="2" /> @@ -417,7 +439,16 @@ </constants> <theme_items> <theme_item name="activity" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> - Color of the connection's activity (see [method set_connection_activity]). + Color the connection line is interpolated to based on the activity value of a connection (see [method set_connection_activity]). + </theme_item> + <theme_item name="connection_hover_tint_color" data_type="color" type="Color" default="Color(0, 0, 0, 0.3)"> + Color which is blended with the connection line when the mouse is hovering over it. + </theme_item> + <theme_item name="connection_rim_color" data_type="color" type="Color" default="Color(0.1, 0.1, 0.1, 0.6)"> + Color of the rim around each connection line used for making intersecting lines more distinguishable. + </theme_item> + <theme_item name="connection_valid_target_tint_color" data_type="color" type="Color" default="Color(1, 1, 1, 0.4)"> + Color which is blended with the connection line when the currently dragged connection is hovering over a valid target port. </theme_item> <theme_item name="grid_major" data_type="color" type="Color" default="Color(1, 1, 1, 0.2)"> Color of major grid lines/dots. diff --git a/doc/classes/GraphNode.xml b/doc/classes/GraphNode.xml index 9e1392567a..5bb3a25158 100644 --- a/doc/classes/GraphNode.xml +++ b/doc/classes/GraphNode.xml @@ -116,6 +116,20 @@ Returns the right (output) [Color] of the slot with the given [param slot_index]. </description> </method> + <method name="get_slot_custom_icon_left" qualifiers="const"> + <return type="Texture2D" /> + <param index="0" name="slot_index" type="int" /> + <description> + Returns the left (input) custom [Texture2D] of the slot with the given [param slot_index]. + </description> + </method> + <method name="get_slot_custom_icon_right" qualifiers="const"> + <return type="Texture2D" /> + <param index="0" name="slot_index" type="int" /> + <description> + Returns the right (output) custom [Texture2D] of the slot with the given [param slot_index]. + </description> + </method> <method name="get_slot_type_left" qualifiers="const"> <return type="int" /> <param index="0" name="slot_index" type="int" /> @@ -195,6 +209,22 @@ Sets the [Color] of the right (output) side of the slot with the given [param slot_index] to [param color]. </description> </method> + <method name="set_slot_custom_icon_left"> + <return type="void" /> + <param index="0" name="slot_index" type="int" /> + <param index="1" name="custom_icon" type="Texture2D" /> + <description> + Sets the custom [Texture2D] of the left (input) side of the slot with the given [param slot_index] to [param custom_icon]. + </description> + </method> + <method name="set_slot_custom_icon_right"> + <return type="void" /> + <param index="0" name="slot_index" type="int" /> + <param index="1" name="custom_icon" type="Texture2D" /> + <description> + Sets the custom [Texture2D] of the right (output) side of the slot with the given [param slot_index] to [param custom_icon]. + </description> + </method> <method name="set_slot_draw_stylebox"> <return type="void" /> <param index="0" name="slot_index" type="int" /> diff --git a/doc/classes/Image.xml b/doc/classes/Image.xml index 872277b033..6c1ecb3aea 100644 --- a/doc/classes/Image.xml +++ b/doc/classes/Image.xml @@ -19,6 +19,7 @@ <param index="1" name="contrast" type="float" /> <param index="2" name="saturation" type="float" /> <description> + Adjusts this image's [param brightness], [param contrast], and [param saturation] by the given values. Does not work if the image is compressed (see [method is_compressed]). </description> </method> <method name="blend_rect"> @@ -163,6 +164,7 @@ <return type="int" enum="Image.UsedChannels" /> <param index="0" name="source" type="int" enum="Image.CompressSource" default="0" /> <description> + Returns the color channels used by this image, as one of the [enum UsedChannels] constants. If the image is compressed, the original [param source] must be specified. </description> </method> <method name="fill"> @@ -612,6 +614,7 @@ OpenGL texture format [code]RGBA[/code] with four components, each with a bitdepth of 4. </constant> <constant name="FORMAT_RGB565" value="7" enum="Format"> + OpenGL texture format [code]RGB[/code] with three components. Red and blue have a bitdepth of 5, and green has a bitdepth of 6. </constant> <constant name="FORMAT_RF" value="8" enum="Format"> OpenGL texture format [code]GL_R32F[/code] where there's one component, a 32-bit floating-point value. @@ -696,8 +699,10 @@ [b]Note:[/b] When creating an [ImageTexture], an sRGB to linear color space conversion is performed. </constant> <constant name="FORMAT_ETC2_RA_AS_RG" value="33" enum="Format"> + [url=https://en.wikipedia.org/wiki/Ericsson_Texture_Compression#ETC2_and_EAC]Ericsson Texture Compression format 2[/url] ([code]RGBA8[/code] variant), which compresses RA data and interprets it as two channels (red and green). See also [constant FORMAT_ETC2_RGBA8]. </constant> <constant name="FORMAT_DXT5_RA_AS_RG" value="34" enum="Format"> + The [url=https://en.wikipedia.org/wiki/S3_Texture_Compression]S3TC[/url] texture format also known as Block Compression 3 or BC3, which compresses RA data and interprets it as two channels (red and green). See also [constant FORMAT_DXT5]. </constant> <constant name="FORMAT_ASTC_4x4" value="35" enum="Format"> [url=https://en.wikipedia.org/wiki/Adaptive_scalable_texture_compression]Adaptive Scalable Texture Compression[/url]. This implements the 4x4 (high quality) mode. @@ -761,16 +766,22 @@ Represents the size of the [enum CompressMode] enum. </constant> <constant name="USED_CHANNELS_L" value="0" enum="UsedChannels"> + The image only uses one channel for luminance (grayscale). </constant> <constant name="USED_CHANNELS_LA" value="1" enum="UsedChannels"> + The image uses two channels for luminance and alpha, respectively. </constant> <constant name="USED_CHANNELS_R" value="2" enum="UsedChannels"> + The image only uses the red channel. </constant> <constant name="USED_CHANNELS_RG" value="3" enum="UsedChannels"> + The image uses two channels for red and green. </constant> <constant name="USED_CHANNELS_RGB" value="4" enum="UsedChannels"> + The image uses three channels for red, green, and blue. </constant> <constant name="USED_CHANNELS_RGBA" value="5" enum="UsedChannels"> + The image uses four channels for red, green, blue, and alpha. </constant> <constant name="COMPRESS_SOURCE_GENERIC" value="0" enum="CompressSource"> Source texture (before compression) is a regular texture. Default for all textures. diff --git a/doc/classes/MainLoop.xml b/doc/classes/MainLoop.xml index 4c6c9d3524..b01a3f7a0e 100644 --- a/doc/classes/MainLoop.xml +++ b/doc/classes/MainLoop.xml @@ -5,7 +5,7 @@ </brief_description> <description> [MainLoop] is the abstract base class for a Godot project's game loop. It is inherited by [SceneTree], which is the default game loop implementation used in Godot projects, though it is also possible to write and use one's own [MainLoop] subclass instead of the scene tree. - Upon the application start, a [MainLoop] implementation must be provided to the OS; otherwise, the application will exit. This happens automatically (and a [SceneTree] is created) unless a [MainLoop] [Script] is provided from the command line (with e.g. [code]godot -s my_loop.gd[/code] or the "Main Loop Type" project setting is overwritten. + Upon the application start, a [MainLoop] implementation must be provided to the OS; otherwise, the application will exit. This happens automatically (and a [SceneTree] is created) unless a [MainLoop] [Script] is provided from the command line (with e.g. [code]godot -s my_loop.gd[/code]) or the "Main Loop Type" project setting is overwritten. Here is an example script implementing a simple [MainLoop]: [codeblocks] [gdscript] diff --git a/doc/classes/NavigationServer2D.xml b/doc/classes/NavigationServer2D.xml index 02631841bf..2bb0090282 100644 --- a/doc/classes/NavigationServer2D.xml +++ b/doc/classes/NavigationServer2D.xml @@ -456,7 +456,7 @@ <description> This function immediately forces synchronization of the specified navigation [param map] [RID]. By default navigation maps are only synchronized at the end of each physics frame. This function can be used to immediately (re)calculate all the navigation meshes and region connections of the navigation map. This makes it possible to query a navigation path for a changed map immediately and in the same frame (multiple times if needed). Due to technical restrictions the current NavigationServer command queue will be flushed. This means all already queued update commands for this physics frame will be executed, even those intended for other maps, regions and agents not part of the specified map. The expensive computation of the navigation meshes and region connections of a map will only be done for the specified map. Other maps will receive the normal synchronization at the end of the physics frame. Should the specified map receive changes after the forced update it will update again as well when the other maps receive their update. - Avoidance processing and dispatch of the [code]safe_velocity[/code] signals is untouched by this function and continues to happen for all maps and agents at the end of the physics frame. + Avoidance processing and dispatch of the [code]safe_velocity[/code] signals is unaffected by this function and continues to happen for all maps and agents at the end of the physics frame. [b]Note:[/b] With great power comes great responsibility. This function should only be used by users that really know what they are doing and have a good reason for it. Forcing an immediate update of a navigation map requires locking the NavigationServer and flushing the entire NavigationServer command queue. Not only can this severely impact the performance of a game but it can also introduce bugs if used inappropriately without much foresight. </description> </method> diff --git a/doc/classes/NavigationServer3D.xml b/doc/classes/NavigationServer3D.xml index c04017651c..bff5d63a17 100644 --- a/doc/classes/NavigationServer3D.xml +++ b/doc/classes/NavigationServer3D.xml @@ -495,7 +495,7 @@ <description> This function immediately forces synchronization of the specified navigation [param map] [RID]. By default navigation maps are only synchronized at the end of each physics frame. This function can be used to immediately (re)calculate all the navigation meshes and region connections of the navigation map. This makes it possible to query a navigation path for a changed map immediately and in the same frame (multiple times if needed). Due to technical restrictions the current NavigationServer command queue will be flushed. This means all already queued update commands for this physics frame will be executed, even those intended for other maps, regions and agents not part of the specified map. The expensive computation of the navigation meshes and region connections of a map will only be done for the specified map. Other maps will receive the normal synchronization at the end of the physics frame. Should the specified map receive changes after the forced update it will update again as well when the other maps receive their update. - Avoidance processing and dispatch of the [code]safe_velocity[/code] signals is untouched by this function and continues to happen for all maps and agents at the end of the physics frame. + Avoidance processing and dispatch of the [code]safe_velocity[/code] signals is unaffected by this function and continues to happen for all maps and agents at the end of the physics frame. [b]Note:[/b] With great power comes great responsibility. This function should only be used by users that really know what they are doing and have a good reason for it. Forcing an immediate update of a navigation map requires locking the NavigationServer and flushing the entire NavigationServer command queue. Not only can this severely impact the performance of a game but it can also introduce bugs if used inappropriately without much foresight. </description> </method> diff --git a/doc/classes/Node.xml b/doc/classes/Node.xml index 4d31b5b8ed..5dd3d22062 100644 --- a/doc/classes/Node.xml +++ b/doc/classes/Node.xml @@ -267,7 +267,7 @@ <param index="0" name="idx" type="int" /> <param index="1" name="include_internal" type="bool" default="false" /> <description> - Fetches a child node by its index. Each child node has an index relative its siblings (see [method get_index]). The first child is at index 0. Negative values can also be used to start from the end of the list. This method can be used in combination with [method get_child_count] to iterate over this node's children. + Fetches a child node by its index. Each child node has an index relative its siblings (see [method get_index]). The first child is at index 0. Negative values can also be used to start from the end of the list. This method can be used in combination with [method get_child_count] to iterate over this node's children. If no child exists at the given index, this method returns [code]null[/code] and an error is generated. If [param include_internal] is [code]false[/code], internal children are ignored (see [method add_child]'s [code]internal[/code] parameter). [codeblock] # Assuming the following are children of this node, in order: @@ -739,7 +739,7 @@ <param index="0" name="new_parent" type="Node" /> <param index="1" name="keep_global_transform" type="bool" default="true" /> <description> - Changes the parent of this [Node] to the [param new_parent]. The node needs to already have a parent. + Changes the parent of this [Node] to the [param new_parent]. The node needs to already have a parent. The node's [member owner] is preserved if its owner is still reachable from the new location (i.e., the node is still a descendant of the new parent after the operation). If [param keep_global_transform] is [code]true[/code], the node's global transform will be preserved if supported. [Node2D], [Node3D] and [Control] support this argument (but [Control] keeps only position). </description> </method> diff --git a/doc/classes/PrimitiveMesh.xml b/doc/classes/PrimitiveMesh.xml index d04d8eea52..2b47cd2deb 100644 --- a/doc/classes/PrimitiveMesh.xml +++ b/doc/classes/PrimitiveMesh.xml @@ -12,6 +12,7 @@ <method name="_create_mesh_array" qualifiers="virtual const"> <return type="Array" /> <description> + Override this method to customize how this primitive mesh should be generated. Should return an [Array] where each element is another Array of values required for the mesh (see the [enum Mesh.ArrayType] constants). </description> </method> <method name="get_mesh_arrays" qualifiers="const"> diff --git a/doc/classes/ProceduralSkyMaterial.xml b/doc/classes/ProceduralSkyMaterial.xml index 3fb9f9059c..1503bb2e78 100644 --- a/doc/classes/ProceduralSkyMaterial.xml +++ b/doc/classes/ProceduralSkyMaterial.xml @@ -6,7 +6,7 @@ <description> [ProceduralSkyMaterial] provides a way to create an effective background quickly by defining procedural parameters for the sun, the sky and the ground. The sky and ground are defined by a main color, a color at the horizon, and an easing curve to interpolate between them. Suns are described by a position in the sky, a color, and a max angle from the sun at which the easing curve ends. The max angle therefore defines the size of the sun in the sky. [ProceduralSkyMaterial] supports up to 4 suns, using the color, and energy, direction, and angular distance of the first four [DirectionalLight3D] nodes in the scene. This means that the suns are defined individually by the properties of their corresponding [DirectionalLight3D]s and globally by [member sun_angle_max] and [member sun_curve]. - [ProceduralSkyMaterial] uses a lightweight shader to draw the sky and is therefore suited for real time updates. This makes it a great option for a sky that is simple and computationally cheap, but unrealistic. If you need a more realistic procedural option, use [PhysicalSkyMaterial]. + [ProceduralSkyMaterial] uses a lightweight shader to draw the sky and is therefore suited for real-time updates. This makes it a great option for a sky that is simple and computationally cheap, but unrealistic. If you need a more realistic procedural option, use [PhysicalSkyMaterial]. </description> <tutorials> </tutorials> diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml index b969e3bb8e..cbd797273c 100644 --- a/doc/classes/ProjectSettings.xml +++ b/doc/classes/ProjectSettings.xml @@ -406,7 +406,7 @@ [b]Note:[/b] Enabling TTS can cause addition idle CPU usage and interfere with the sleep mode, so consider disabling it if TTS is not used. </member> <member name="audio/video/video_delay_compensation_ms" type="int" setter="" getter="" default="0"> - Setting to hardcode audio delay when playing video. Best to leave this untouched unless you know what you are doing. + Setting to hardcode audio delay when playing video. Best to leave this unchanged unless you know what you are doing. </member> <member name="collada/use_ambient" type="bool" setter="" getter="" default="false"> If [code]true[/code], ambient lights will be imported from COLLADA models as [DirectionalLight3D]. If [code]false[/code], ambient lights will be ignored. @@ -433,16 +433,18 @@ If canvas item redraw debugging is active, this will be the time the flash will last each time they redraw. </member> <member name="debug/file_logging/enable_file_logging" type="bool" setter="" getter="" default="false"> - If [code]true[/code], logs all output to files. + If [code]true[/code], logs all output and error messages to files. See also [member debug/file_logging/log_path], [member debug/file_logging/max_log_files], and [member application/run/flush_stdout_on_print]. </member> <member name="debug/file_logging/enable_file_logging.pc" type="bool" setter="" getter="" default="true"> Desktop override for [member debug/file_logging/enable_file_logging], as log files are not readily accessible on mobile/Web platforms. </member> <member name="debug/file_logging/log_path" type="String" setter="" getter="" default=""user://logs/godot.log""> Path at which to store log files for the project. Using a path under [code]user://[/code] is recommended. + This can be specified manually on the command line using the [code]--log-file <file>[/code] [url=$DOCS_URL/tutorials/editor/command_line_tutorial.html]command line argument[/url]. If this command line argument is specified, log rotation is automatically disabled (see [member debug/file_logging/max_log_files]). </member> <member name="debug/file_logging/max_log_files" type="int" setter="" getter="" default="5"> - Specifies the maximum number of log files allowed (used for rotation). + Specifies the maximum number of log files allowed (used for rotation). Set to [code]1[/code] to disable log file rotation. + If the [code]--log-file <file>[/code] [url=$DOCS_URL/tutorials/editor/command_line_tutorial.html]command line argument[/url] is used, log rotation is always disabled. </member> <member name="debug/gdscript/warnings/assert_always_false" type="int" setter="" getter="" default="1"> When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when an [code]assert[/code] call always evaluates to false. @@ -810,7 +812,9 @@ Main window can't be focused. No-focus window will ignore all input, except mouse clicks. </member> <member name="display/window/size/resizable" type="bool" setter="" getter="" default="true"> - Allows the window to be resizable by default. + If [code]true[/code], allows the window to be resizable by default. + [b]Note:[/b] This property is only read when the project starts. To change whether the window is resizable at runtime, set [member Window.unresizable] instead on the root Window, which can be retrieved using [code]get_viewport().get_window()[/code]. [member Window.unresizable] takes the opposite value of this setting. + [b]Note:[/b] Certain window managers can be configured to ignore the non-resizable status of a window. Do not rely on this setting as a guarantee that the window will [i]never[/i] be resizable. [b]Note:[/b] This setting is ignored on iOS. </member> <member name="display/window/size/transparent" type="bool" setter="" getter="" default="false"> @@ -2208,7 +2212,7 @@ [b]Note:[/b] This property is only read when the project starts. To change the maximum number of simulated physics steps per frame at runtime, set [member Engine.max_physics_steps_per_frame] instead. </member> <member name="physics/common/physics_jitter_fix" type="float" setter="" getter="" default="0.5"> - Controls how much physics ticks are synchronized with real time. For 0 or less, the ticks are synchronized. Such values are recommended for network games, where clock synchronization matters. Higher values cause higher deviation of in-game clock and real clock, but allows smoothing out framerate jitters. The default value of 0.5 should be fine for most; values above 2 could cause the game to react to dropped frames with a noticeable delay and are not recommended. + Controls how much physics ticks are synchronized with real time. For 0 or less, the ticks are synchronized. Such values are recommended for network games, where clock synchronization matters. Higher values cause higher deviation of in-game clock and real clock, but allows smoothing out framerate jitters. The default value of 0.5 should be good enough for most; values above 2 could cause the game to react to dropped frames with a noticeable delay and are not recommended. [b]Note:[/b] For best results, when using a custom physics interpolation solution, the physics jitter fix should be disabled by setting [member physics/common/physics_jitter_fix] to [code]0[/code]. [b]Note:[/b] This property is only read when the project starts. To change the physics jitter fix at runtime, set [member Engine.physics_jitter_fix] instead. </member> @@ -2534,8 +2538,6 @@ Decreasing this value may improve GPU performance on certain setups, even if the maximum number of clustered elements is never reached in the project. [b]Note:[/b] This setting is only effective when using the Forward+ rendering method, not Mobile and Compatibility. </member> - <member name="rendering/limits/forward_renderer/threaded_render_minimum_instances" type="int" setter="" getter="" default="500"> - </member> <member name="rendering/limits/global_shader_variables/buffer_size" type="int" setter="" getter="" default="65536"> </member> <member name="rendering/limits/opengl/max_lights_per_object" type="int" setter="" getter="" default="8"> @@ -2551,6 +2553,7 @@ [b]Note:[/b] This setting is only effective when using the Compatibility rendering method, not Forward+ and Mobile. </member> <member name="rendering/limits/spatial_indexer/threaded_cull_minimum_instances" type="int" setter="" getter="" default="1000"> + The minimum number of instances that must be present in a scene to enable culling computations on multiple threads. If a scene has fewer instances than this number, culling is done on a single thread. </member> <member name="rendering/limits/spatial_indexer/update_iterations_per_frame" type="int" setter="" getter="" default="10"> </member> @@ -2768,8 +2771,6 @@ <member name="threading/worker_pool/max_threads" type="int" setter="" getter="" default="-1"> Maximum number of threads to be used by [WorkerThreadPool]. Value of [code]-1[/code] means no limit. </member> - <member name="threading/worker_pool/use_system_threads_for_low_priority_tasks" type="bool" setter="" getter="" default="true"> - </member> <member name="xr/openxr/default_action_map" type="String" setter="" getter="" default=""res://openxr_action_map.tres""> Action map configuration to load by default. </member> diff --git a/doc/classes/RDUniform.xml b/doc/classes/RDUniform.xml index 7aab8b2810..77aaf0aae7 100644 --- a/doc/classes/RDUniform.xml +++ b/doc/classes/RDUniform.xml @@ -13,16 +13,19 @@ <return type="void" /> <param index="0" name="id" type="RID" /> <description> + Binds the given id to the uniform. The data associated with the id is then used when the uniform is passed to a shader. </description> </method> <method name="clear_ids"> <return type="void" /> <description> + Unbinds all ids currently bound to the uniform. </description> </method> <method name="get_ids" qualifiers="const"> <return type="RID[]" /> <description> + Returns an array of all ids currently bound to the uniform. </description> </method> </methods> diff --git a/doc/classes/RandomNumberGenerator.xml b/doc/classes/RandomNumberGenerator.xml index 54f18a1ab4..2b6e6af596 100644 --- a/doc/classes/RandomNumberGenerator.xml +++ b/doc/classes/RandomNumberGenerator.xml @@ -6,7 +6,7 @@ <description> RandomNumberGenerator is a class for generating pseudo-random numbers. It currently uses [url=https://www.pcg-random.org/]PCG32[/url]. [b]Note:[/b] The underlying algorithm is an implementation detail and should not be depended upon. - To generate a random float number (within a given range) based on a time-dependant seed: + To generate a random float number (within a given range) based on a time-dependent seed: [codeblock] var rng = RandomNumberGenerator.new() func _ready(): diff --git a/doc/classes/RayCast2D.xml b/doc/classes/RayCast2D.xml index 6144fd8f0b..22e3ae07ba 100644 --- a/doc/classes/RayCast2D.xml +++ b/doc/classes/RayCast2D.xml @@ -74,7 +74,7 @@ <method name="get_collision_point" qualifiers="const"> <return type="Vector2" /> <description> - Returns the collision point at which the ray intersects the closest object. + Returns the collision point at which the ray intersects the closest object. If [member hit_from_inside] is [code]true[/code] and the ray starts inside of a collision shape, this function will return the origin point of the ray. [b]Note:[/b] This point is in the [b]global[/b] coordinate system. </description> </method> diff --git a/doc/classes/RayCast3D.xml b/doc/classes/RayCast3D.xml index 7157ec9b5f..406fed107f 100644 --- a/doc/classes/RayCast3D.xml +++ b/doc/classes/RayCast3D.xml @@ -81,7 +81,7 @@ <method name="get_collision_point" qualifiers="const"> <return type="Vector3" /> <description> - Returns the collision point at which the ray intersects the closest object. + Returns the collision point at which the ray intersects the closest object. If [member hit_from_inside] is [code]true[/code] and the ray starts inside of a collision shape, this function will return the origin point of the ray. [b]Note:[/b] This point is in the [b]global[/b] coordinate system. </description> </method> diff --git a/doc/classes/ReflectionProbe.xml b/doc/classes/ReflectionProbe.xml index f53ddfc3ac..c7d067b94d 100644 --- a/doc/classes/ReflectionProbe.xml +++ b/doc/classes/ReflectionProbe.xml @@ -28,7 +28,8 @@ [b]Note:[/b] To better fit rectangle-shaped rooms that are not aligned to the grid, you can rotate the [ReflectionProbe] node. </member> <member name="cull_mask" type="int" setter="set_cull_mask" getter="get_cull_mask" default="1048575"> - Sets the cull mask which determines what objects are drawn by this probe. Every [VisualInstance3D] with a layer included in this cull mask will be rendered by the probe. To improve performance, it is best to only include large objects which are likely to take up a lot of space in the reflection. + Sets the cull mask which determines what objects are drawn by this probe. Every [VisualInstance3D] with a layer included in this cull mask will be rendered by the probe. It is best to only include large objects which are likely to take up a lot of space in the reflection in order to save on rendering cost. + This can also be used to prevent an object from reflecting upon itself (for instance, a [ReflectionProbe] centered on a vehicle). </member> <member name="enable_shadows" type="bool" setter="set_enable_shadows" getter="are_shadows_enabled" default="false"> If [code]true[/code], computes shadows in the reflection probe. This makes the reflection probe slower to render; you may want to disable this if using the [constant UPDATE_ALWAYS] [member update_mode]. @@ -50,6 +51,9 @@ <member name="origin_offset" type="Vector3" setter="set_origin_offset" getter="get_origin_offset" default="Vector3(0, 0, 0)"> Sets the origin offset to be used when this [ReflectionProbe] is in [member box_projection] mode. This can be set to a non-zero value to ensure a reflection fits a rectangle-shaped room, while reducing the number of objects that "get in the way" of the reflection. </member> + <member name="reflection_mask" type="int" setter="set_reflection_mask" getter="get_reflection_mask" default="1048575"> + Sets the reflection mask which determines what objects have reflections applied from this probe. Every [VisualInstance3D] with a layer included in this reflection mask will have reflections applied from this probe. See also [member cull_mask], which can be used to exclude objects from appearing in the reflection while still making them affected by the [ReflectionProbe]. + </member> <member name="size" type="Vector3" setter="set_size" getter="get_size" default="Vector3(20, 20, 20)"> The size of the reflection probe. The larger the size, the more space covered by the probe, which will lower the perceived resolution. It is best to keep the size only as large as you need it. [b]Note:[/b] To better fit areas that are not aligned to the grid, you can rotate the [ReflectionProbe] node. diff --git a/doc/classes/RenderingDevice.xml b/doc/classes/RenderingDevice.xml index 5ca6d38267..54f3281e17 100644 --- a/doc/classes/RenderingDevice.xml +++ b/doc/classes/RenderingDevice.xml @@ -14,12 +14,12 @@ <link title="Using compute shaders">$DOCS_URL/tutorials/shaders/compute_shaders.html</link> </tutorials> <methods> - <method name="barrier"> + <method name="barrier" is_deprecated="true"> <return type="void" /> <param index="0" name="from" type="int" enum="RenderingDevice.BarrierMask" is_bitfield="true" default="32767" /> <param index="1" name="to" type="int" enum="RenderingDevice.BarrierMask" is_bitfield="true" default="32767" /> <description> - Puts a memory barrier in place. This is used for synchronization to avoid data races. See also [method full_barrier], which may be useful for debugging. + [i]Deprecated.[/i] Barriers are automatically inserted by RenderingDevice. </description> </method> <method name="buffer_clear"> @@ -27,9 +27,8 @@ <param index="0" name="buffer" type="RID" /> <param index="1" name="offset" type="int" /> <param index="2" name="size_bytes" type="int" /> - <param index="3" name="post_barrier" type="int" enum="RenderingDevice.BarrierMask" is_bitfield="true" default="32767" /> <description> - Clears the contents of the [param buffer], clearing [param size_bytes] bytes, starting at [param offset]. Always raises a memory barrier. + Clears the contents of the [param buffer], clearing [param size_bytes] bytes, starting at [param offset]. Prints an error if: - the size isn't a multiple of four - the region specified by [param offset] + [param size_bytes] exceeds the buffer @@ -37,6 +36,21 @@ - a compute list is currently active (created by [method compute_list_begin]) </description> </method> + <method name="buffer_copy"> + <return type="int" enum="Error" /> + <param index="0" name="src_buffer" type="RID" /> + <param index="1" name="dst_buffer" type="RID" /> + <param index="2" name="src_offset" type="int" /> + <param index="3" name="dst_offset" type="int" /> + <param index="4" name="size" type="int" /> + <description> + Copies [param size] bytes from the [param src_buffer] at [param src_offset] into [param dst_buffer] at [param dst_offset]. + Prints an error if: + - [param size] exceeds the size of either [param src_buffer] or [param dst_buffer] at their corresponding offsets + - a draw list is currently active (created by [method draw_list_begin]) + - a compute list is currently active (created by [method compute_list_begin]) + </description> + </method> <method name="buffer_get_data"> <return type="PackedByteArray" /> <param index="0" name="buffer" type="RID" /> @@ -52,9 +66,8 @@ <param index="1" name="offset" type="int" /> <param index="2" name="size_bytes" type="int" /> <param index="3" name="data" type="PackedByteArray" /> - <param index="4" name="post_barrier" type="int" enum="RenderingDevice.BarrierMask" is_bitfield="true" default="32767" /> <description> - Updates a region of [param size_bytes] bytes, starting at [param offset], in the buffer, with the specified [param data]. Raises a memory barrier except when [param post_barrier] is set to [constant BARRIER_MASK_NO_BARRIER]. + Updates a region of [param size_bytes] bytes, starting at [param offset], in the buffer, with the specified [param data]. Prints an error if: - the region specified by [param offset] + [param size_bytes] exceeds the buffer - a draw list is currently active (created by [method draw_list_begin]) @@ -77,10 +90,9 @@ </method> <method name="compute_list_begin"> <return type="int" /> - <param index="0" name="allow_draw_overlap" type="bool" default="false" /> <description> Starts a list of compute commands created with the [code]compute_*[/code] methods. The returned value should be passed to other [code]compute_list_*[/code] functions. - If [param allow_draw_overlap] is [code]true[/code], you may have one draw list running at the same time as one compute list. Multiple compute lists cannot be created at the same time; you must finish the previous compute list first using [method compute_list_end]. + Multiple compute lists cannot be created at the same time; you must finish the previous compute list first using [method compute_list_end]. A simple compute operation might look like this (code is not a complete example): [codeblock] var rd = RenderingDevice.new() @@ -128,7 +140,6 @@ </method> <method name="compute_list_end"> <return type="void" /> - <param index="0" name="post_barrier" type="int" enum="RenderingDevice.BarrierMask" is_bitfield="true" default="32767" /> <description> Finishes a list of compute commands created with the [code]compute_*[/code] methods. </description> @@ -170,7 +181,7 @@ <param index="1" name="color" type="Color" /> <description> Create a command buffer debug label region that can be displayed in third-party tools such as [url=https://renderdoc.org/]RenderDoc[/url]. All regions must be ended with a [method draw_command_end_label] call. When viewed from the linear series of submissions to a single queue, calls to [method draw_command_begin_label] and [method draw_command_end_label] must be matched and balanced. - The [code]VK_EXT_DEBUG_UTILS_EXTENSION_NAME[/code] Vulkan extension must be available and enabled for command buffer debug label region to work. See also [method draw_command_insert_label] and [method draw_command_end_label]. + The [code]VK_EXT_DEBUG_UTILS_EXTENSION_NAME[/code] Vulkan extension must be available and enabled for command buffer debug label region to work. See also [method draw_command_end_label]. </description> </method> <method name="draw_command_end_label"> @@ -179,12 +190,12 @@ Ends the command buffer debug label region started by a [method draw_command_begin_label] call. </description> </method> - <method name="draw_command_insert_label"> + <method name="draw_command_insert_label" is_deprecated="true"> <return type="void" /> <param index="0" name="name" type="String" /> <param index="1" name="color" type="Color" /> <description> - Inserts a command buffer debug label region in the current command buffer. Unlike [method draw_command_begin_label], this region should not be ended with a [method draw_command_end_label] call. + [i]Deprecated.[/i] Inserting labels no longer applies due to command reordering. </description> </method> <method name="draw_list_begin"> @@ -198,7 +209,6 @@ <param index="6" name="clear_depth" type="float" default="1.0" /> <param index="7" name="clear_stencil" type="int" default="0" /> <param index="8" name="region" type="Rect2" default="Rect2(0, 0, 0, 0)" /> - <param index="9" name="storage_textures" type="RID[]" default="[]" /> <description> Starts a list of raster drawing commands created with the [code]draw_*[/code] methods. The returned value should be passed to other [code]draw_list_*[/code] functions. Multiple draw lists cannot be created at the same time; you must finish the previous draw list first using [method draw_list_end]. @@ -232,7 +242,7 @@ [b]Note:[/b] Cannot be used with local RenderingDevices, as these don't have a screen. If called on a local RenderingDevice, [method draw_list_begin_for_screen] returns [constant INVALID_ID]. </description> </method> - <method name="draw_list_begin_split"> + <method name="draw_list_begin_split" is_deprecated="true"> <return type="PackedInt64Array" /> <param index="0" name="framebuffer" type="RID" /> <param index="1" name="splits" type="int" /> @@ -246,7 +256,7 @@ <param index="9" name="region" type="Rect2" default="Rect2(0, 0, 0, 0)" /> <param index="10" name="storage_textures" type="RID[]" default="[]" /> <description> - Variant of [method draw_list_begin] with support for multiple splits. The [param splits] parameter determines how many splits are created. + [i]Deprecated.[/i] Split draw lists are used automatically by RenderingDevice. </description> </method> <method name="draw_list_bind_index_array"> @@ -310,7 +320,6 @@ </method> <method name="draw_list_end"> <return type="void" /> - <param index="0" name="post_barrier" type="int" enum="RenderingDevice.BarrierMask" is_bitfield="true" default="32767" /> <description> Finishes a list of raster drawing commands created with the [code]draw_*[/code] methods. </description> @@ -335,14 +344,14 @@ <method name="draw_list_switch_to_next_pass"> <return type="int" /> <description> - Switches to the next draw pass and returns the split's ID. Equivalent to [method draw_list_switch_to_next_pass_split] with [code]splits[/code] set to [code]1[/code]. + Switches to the next draw pass. </description> </method> - <method name="draw_list_switch_to_next_pass_split"> + <method name="draw_list_switch_to_next_pass_split" is_deprecated="true"> <return type="PackedInt64Array" /> <param index="0" name="splits" type="int" /> <description> - Switches to the next draw pass, with the number of splits allocated specified in [param splits]. The return value is an array containing the ID of each split. For single-split usage, see [method draw_list_switch_to_next_pass]. + [i]Deprecated.[/i] Split draw lists are used automatically by RenderingDevice. </description> </method> <method name="framebuffer_create"> @@ -430,10 +439,10 @@ Tries to free an object in the RenderingDevice. To avoid memory leaks, this should be called after using an object as memory management does not occur automatically when using RenderingDevice directly. </description> </method> - <method name="full_barrier"> + <method name="full_barrier" is_deprecated="true"> <return type="void" /> <description> - Puts a [i]full[/i] memory barrier in place. This is a memory [method barrier] with all flags enabled. [method full_barrier] it should only be used for debugging as it can severely impact performance. + [i]Deprecated.[/i] Barriers are automatically inserted by RenderingDevice. </description> </method> <method name="get_captured_timestamp_cpu_time" qualifiers="const"> @@ -704,7 +713,6 @@ <param index="3" name="mipmap_count" type="int" /> <param index="4" name="base_layer" type="int" /> <param index="5" name="layer_count" type="int" /> - <param index="6" name="post_barrier" type="int" enum="RenderingDevice.BarrierMask" is_bitfield="true" default="32767" /> <description> Clears the specified [param texture] by replacing all of its pixels with the specified [param color]. [param base_mipmap] and [param mipmap_count] determine which mipmaps of the texture are affected by this clear operation, while [param base_layer] and [param layer_count] determine which layers of a 3D texture (or texture array) are affected by this clear operation. For 2D textures (which only have one layer by design), [param base_layer] must be [code]0[/code] and [param layer_count] must be [code]1[/code]. [b]Note:[/b] [param texture] can't be cleared while a draw list that uses it as part of a framebuffer is being created. Ensure the draw list is finalized (and that the color/depth texture using it is not set to [constant FINAL_ACTION_CONTINUE]) to clear this texture. @@ -721,7 +729,6 @@ <param index="6" name="dst_mipmap" type="int" /> <param index="7" name="src_layer" type="int" /> <param index="8" name="dst_layer" type="int" /> - <param index="9" name="post_barrier" type="int" enum="RenderingDevice.BarrierMask" is_bitfield="true" default="32767" /> <description> Copies the [param from_texture] to [param to_texture] with the specified [param from_pos], [param to_pos] and [param size] coordinates. The Z axis of the [param from_pos], [param to_pos] and [param size] must be [code]0[/code] for 2-dimensional textures. Source and destination mipmaps/layers must also be specified, with these parameters being [code]0[/code] for textures without mipmaps or single-layer textures. Returns [constant @GlobalScope.OK] if the texture copy was successful or [constant @GlobalScope.ERR_INVALID_PARAMETER] otherwise. [b]Note:[/b] [param from_texture] texture can't be copied while a draw list that uses it as part of a framebuffer is being created. Ensure the draw list is finalized (and that the color/depth texture using it is not set to [constant FINAL_ACTION_CONTINUE]) to copy this texture. @@ -831,7 +838,6 @@ <return type="int" enum="Error" /> <param index="0" name="from_texture" type="RID" /> <param index="1" name="to_texture" type="RID" /> - <param index="2" name="post_barrier" type="int" enum="RenderingDevice.BarrierMask" is_bitfield="true" default="32767" /> <description> Resolves the [param from_texture] texture onto [param to_texture] with multisample antialiasing enabled. This must be used when rendering a framebuffer for MSAA to work. Returns [constant @GlobalScope.OK] if successful, [constant @GlobalScope.ERR_INVALID_PARAMETER] otherwise. [b]Note:[/b] [param from_texture] and [param to_texture] textures must have the same dimension, format and type (color or depth). @@ -848,7 +854,6 @@ <param index="0" name="texture" type="RID" /> <param index="1" name="layer" type="int" /> <param index="2" name="data" type="PackedByteArray" /> - <param index="3" name="post_barrier" type="int" enum="RenderingDevice.BarrierMask" is_bitfield="true" default="32767" /> <description> Updates texture data with new data, replacing the previous data in place. The updated texture data must have the same dimensions and format. For 2D textures (which only have one layer), [param layer] must be [code]0[/code]. Returns [constant @GlobalScope.OK] if the update was successful, [constant @GlobalScope.ERR_INVALID_PARAMETER] otherwise. [b]Note:[/b] Updating textures is forbidden during creation of a draw or compute list. @@ -2150,39 +2155,48 @@ </constant> <constant name="DYNAMIC_STATE_STENCIL_REFERENCE" value="64" enum="PipelineDynamicStateFlags" is_bitfield="true"> </constant> - <constant name="INITIAL_ACTION_CLEAR" value="0" enum="InitialAction"> - Start rendering and clear the whole framebuffer. + <constant name="INITIAL_ACTION_LOAD" value="0" enum="InitialAction"> + Load the previous contents of the framebuffer. </constant> - <constant name="INITIAL_ACTION_CLEAR_REGION" value="1" enum="InitialAction"> - Start rendering and clear the framebuffer in the specified region. + <constant name="INITIAL_ACTION_CLEAR" value="1" enum="InitialAction"> + Clear the whole framebuffer or its specified region. </constant> - <constant name="INITIAL_ACTION_CLEAR_REGION_CONTINUE" value="2" enum="InitialAction"> - Continue rendering and clear the framebuffer in the specified region. Framebuffer must have been left in [constant FINAL_ACTION_CONTINUE] state as the final action previously. + <constant name="INITIAL_ACTION_DISCARD" value="2" enum="InitialAction"> + Ignore the previous contents of the framebuffer. This is the fastest option if you'll overwrite all of the pixels and don't need to read any of them. </constant> - <constant name="INITIAL_ACTION_KEEP" value="3" enum="InitialAction"> - Start rendering, but keep attached color texture contents. If the framebuffer was previously used to read in a shader, this will automatically insert a layout transition. + <constant name="INITIAL_ACTION_MAX" value="3" enum="InitialAction"> + Represents the size of the [enum InitialAction] enum. </constant> - <constant name="INITIAL_ACTION_DROP" value="4" enum="InitialAction"> - Start rendering, ignore what is there; write above it. In general, this is the fastest option when you will be writing every single pixel and you don't need a clear color. + <constant name="INITIAL_ACTION_CLEAR_REGION" value="1" enum="InitialAction" is_deprecated="true"> + [i]Deprecated.[/i] Use [constant INITIAL_ACTION_CLEAR] instead. </constant> - <constant name="INITIAL_ACTION_CONTINUE" value="5" enum="InitialAction"> - Continue rendering. Framebuffer must have been left in [constant FINAL_ACTION_CONTINUE] state as the final action previously. + <constant name="INITIAL_ACTION_CLEAR_REGION_CONTINUE" value="1" enum="InitialAction" is_deprecated="true"> + [i]Deprecated.[/i] Use [constant INITIAL_ACTION_LOAD] instead. </constant> - <constant name="INITIAL_ACTION_MAX" value="6" enum="InitialAction"> - Represents the size of the [enum InitialAction] enum. + <constant name="INITIAL_ACTION_KEEP" value="0" enum="InitialAction" is_deprecated="true"> + [i]Deprecated.[/i] Use [constant INITIAL_ACTION_LOAD] instead. </constant> - <constant name="FINAL_ACTION_READ" value="0" enum="FinalAction"> - Store the texture for reading and make it read-only if it has the [constant TEXTURE_USAGE_SAMPLING_BIT] bit (only applies to color, depth and stencil attachments). + <constant name="INITIAL_ACTION_DROP" value="2" enum="InitialAction" is_deprecated="true"> + [i]Deprecated.[/i] Use [constant INITIAL_ACTION_DISCARD] instead. </constant> - <constant name="FINAL_ACTION_DISCARD" value="1" enum="FinalAction"> - Discard the texture data and make it read-only if it has the [constant TEXTURE_USAGE_SAMPLING_BIT] bit (only applies to color, depth and stencil attachments). + <constant name="INITIAL_ACTION_CONTINUE" value="0" enum="InitialAction" is_deprecated="true"> + [i]Deprecated.[/i] Use [constant INITIAL_ACTION_LOAD] instead. </constant> - <constant name="FINAL_ACTION_CONTINUE" value="2" enum="FinalAction"> - Store the texture and continue for further processing. Similar to [constant FINAL_ACTION_READ], but does not make the texture read-only if it has the [constant TEXTURE_USAGE_SAMPLING_BIT] bit. + <constant name="FINAL_ACTION_STORE" value="0" enum="FinalAction"> + Store the result of the draw list in the framebuffer. This is generally what you want to do. </constant> - <constant name="FINAL_ACTION_MAX" value="3" enum="FinalAction"> + <constant name="FINAL_ACTION_DISCARD" value="1" enum="FinalAction"> + Discard the contents of the framebuffer. This is the fastest option if you don't need to use the results of the draw list. + </constant> + <constant name="FINAL_ACTION_MAX" value="2" enum="FinalAction"> Represents the size of the [enum FinalAction] enum. </constant> + <constant name="FINAL_ACTION_READ" value="0" enum="FinalAction" is_deprecated="true"> + [i]Deprecated.[/i] Use [constant FINAL_ACTION_STORE] instead. + </constant> + <constant name="FINAL_ACTION_CONTINUE" value="0" enum="FinalAction" is_deprecated="true"> + [i]Deprecated.[/i] Use [constant FINAL_ACTION_STORE] instead. + </constant> <constant name="SHADER_STAGE_VERTEX" value="0" enum="ShaderStage"> Vertex shader stage. This can be used to manipulate vertices from a shader (but not create new vertices). </constant> diff --git a/doc/classes/RenderingServer.xml b/doc/classes/RenderingServer.xml index a3ec4d25f1..4ab511b5a9 100644 --- a/doc/classes/RenderingServer.xml +++ b/doc/classes/RenderingServer.xml @@ -1556,11 +1556,11 @@ Returns [code]true[/code] if changes have been made to the RenderingServer's data. [method force_draw] is usually called if this happens. </description> </method> - <method name="has_feature" qualifiers="const"> + <method name="has_feature" qualifiers="const" is_deprecated="true"> <return type="bool" /> <param index="0" name="feature" type="int" enum="RenderingServer.Features" /> <description> - Not yet implemented. Always returns [code]false[/code]. + [i]Deprecated.[/i] This method has not been used since Godot 3.0. Always returns false. </description> </method> <method name="has_os_feature" qualifiers="const"> @@ -2894,7 +2894,7 @@ <param index="0" name="probe" type="RID" /> <param index="1" name="layers" type="int" /> <description> - Sets the render cull mask for this reflection probe. Only instances with a matching cull mask will be rendered by this probe. Equivalent to [member ReflectionProbe.cull_mask]. + Sets the render cull mask for this reflection probe. Only instances with a matching layer will be reflected by this probe. Equivalent to [member ReflectionProbe.cull_mask]. </description> </method> <method name="reflection_probe_set_enable_box_projection"> @@ -2945,6 +2945,14 @@ Sets the origin offset to be used when this reflection probe is in box project mode. Equivalent to [member ReflectionProbe.origin_offset]. </description> </method> + <method name="reflection_probe_set_reflection_mask"> + <return type="void" /> + <param index="0" name="probe" type="RID" /> + <param index="1" name="layers" type="int" /> + <description> + Sets the render reflection mask for this reflection probe. Only instances with a matching layer will have reflections applied from this probe. Equivalent to [member ReflectionProbe.reflection_mask]. + </description> + </method> <method name="reflection_probe_set_resolution"> <return type="void" /> <param index="0" name="probe" type="RID" /> @@ -5332,11 +5340,11 @@ <constant name="RENDERING_INFO_VIDEO_MEM_USED" value="5" enum="RenderingInfo"> Video memory used (in bytes). When using the Forward+ or mobile rendering backends, this is always greater than the sum of [constant RENDERING_INFO_TEXTURE_MEM_USED] and [constant RENDERING_INFO_BUFFER_MEM_USED], since there is miscellaneous data not accounted for by those two metrics. When using the GL Compatibility backend, this is equal to the sum of [constant RENDERING_INFO_TEXTURE_MEM_USED] and [constant RENDERING_INFO_BUFFER_MEM_USED]. </constant> - <constant name="FEATURE_SHADERS" value="0" enum="Features"> - Hardware supports shaders. This enum is currently unused in Godot 3.x. + <constant name="FEATURE_SHADERS" value="0" enum="Features" is_deprecated="true"> + [i]Deprecated.[/i] This constant has not been used since Godot 3.0. </constant> - <constant name="FEATURE_MULTITHREADED" value="1" enum="Features"> - Hardware supports multithreading. This enum is currently unused in Godot 3.x. + <constant name="FEATURE_MULTITHREADED" value="1" enum="Features" is_deprecated="true"> + [i]Deprecated.[/i] This constant has not been used since Godot 3.0. </constant> </constants> </class> diff --git a/doc/classes/ResourceImporterOBJ.xml b/doc/classes/ResourceImporterOBJ.xml index fa964e5016..55043a311c 100644 --- a/doc/classes/ResourceImporterOBJ.xml +++ b/doc/classes/ResourceImporterOBJ.xml @@ -1,7 +1,7 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="ResourceImporterOBJ" inherits="ResourceImporter" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - Imports an OBJ 3D model as a standalone [Mesh] or scene. + Imports an OBJ 3D model as an independent [Mesh] or scene. </brief_description> <description> Unlike [ResourceImporterScene], [ResourceImporterOBJ] will import a single [Mesh] resource by default instead of importing a [PackedScene]. This makes it easier to use the [Mesh] resource in nodes that expect direct [Mesh] resources, such as [GridMap], [GPUParticles3D] or [CPUParticles3D]. Note that it is still possible to save mesh resources from 3D scenes using the [b]Advanced Import Settings[/b] dialog, regardless of the source format. diff --git a/doc/classes/ResourceImporterScene.xml b/doc/classes/ResourceImporterScene.xml index 1769da9f24..6a88adf421 100644 --- a/doc/classes/ResourceImporterScene.xml +++ b/doc/classes/ResourceImporterScene.xml @@ -4,7 +4,7 @@ Imports a glTF, FBX, Collada or Blender 3D scene. </brief_description> <description> - See also [ResourceImporterOBJ], which is used for OBJ models that can be imported as a standalone [Mesh] or a scene. + See also [ResourceImporterOBJ], which is used for OBJ models that can be imported as an independent [Mesh] or a scene. Additional options (such as extracting individual meshes or materials to files) are available in the [b]Advanced Import Settings[/b] dialog. This dialog can be accessed by double-clicking a 3D scene in the FileSystem dock or by selecting a 3D scene in the FileSystem dock, going to the Import dock and choosing [b]Advanced[/b]. [b]Note:[/b] [ResourceImporterScene] is [i]not[/i] used for [PackedScene]s, such as [code].tscn[/code] and [code].scn[/code] files. </description> diff --git a/doc/classes/SoftBody3D.xml b/doc/classes/SoftBody3D.xml index b5202bd4e3..a4d80a7c3e 100644 --- a/doc/classes/SoftBody3D.xml +++ b/doc/classes/SoftBody3D.xml @@ -41,6 +41,7 @@ <method name="get_physics_rid" qualifiers="const"> <return type="RID" /> <description> + Returns the internal [RID] used by the [PhysicsServer3D] for this body. </description> </method> <method name="get_point_transform"> @@ -100,11 +101,14 @@ [b]Note:[/b] Object A can detect a contact with object B only if object B is in any of the layers that object A scans. See [url=$DOCS_URL/tutorials/physics/physics_introduction.html#collision-layers-and-masks]Collision layers and masks[/url] in the documentation for more information. </member> <member name="damping_coefficient" type="float" setter="set_damping_coefficient" getter="get_damping_coefficient" default="0.01"> + The body's damping coefficient. Higher values will slow down the body more noticeably when forces are applied. </member> <member name="disable_mode" type="int" setter="set_disable_mode" getter="get_disable_mode" enum="SoftBody3D.DisableMode" default="0"> Defines the behavior in physics when [member Node.process_mode] is set to [constant Node.PROCESS_MODE_DISABLED]. See [enum DisableMode] for more details about the different modes. </member> <member name="drag_coefficient" type="float" setter="set_drag_coefficient" getter="get_drag_coefficient" default="0.0"> + The body's drag coefficient. Higher values increase this body's air resistance. + [b]Note:[/b] This value is currently unused by Godot's default physics implementation. </member> <member name="linear_stiffness" type="float" setter="set_linear_stiffness" getter="get_linear_stiffness" default="0.5"> Higher values will result in a stiffer body, while lower values will increase the body's ability to bend. The value can be between [code]0.0[/code] and [code]1.0[/code] (inclusive). @@ -113,6 +117,7 @@ [NodePath] to a [CollisionObject3D] this SoftBody3D should avoid clipping. </member> <member name="pressure_coefficient" type="float" setter="set_pressure_coefficient" getter="get_pressure_coefficient" default="0.0"> + The pressure coefficient of this soft body. Simulate pressure build-up from inside this body. Higher values increase the strength of this effect. </member> <member name="ray_pickable" type="bool" setter="set_ray_pickable" getter="is_ray_pickable" default="true"> If [code]true[/code], the [SoftBody3D] will respond to [RayCast3D]s. diff --git a/doc/classes/String.xml b/doc/classes/String.xml index 277d84ab90..e1b60b1656 100644 --- a/doc/classes/String.xml +++ b/doc/classes/String.xml @@ -96,13 +96,14 @@ [gdscript] "move_local_x".capitalize() # Returns "Move Local X" "sceneFile_path".capitalize() # Returns "Scene File Path" + "2D, FPS, PNG".capitalize() # Returns "2d, Fps, Png" [/gdscript] [csharp] "move_local_x".Capitalize(); // Returns "Move Local X" "sceneFile_path".Capitalize(); // Returns "Scene File Path" + "2D, FPS, PNG".Capitalize(); // Returns "2d, Fps, Png" [/csharp] [/codeblocks] - [b]Note:[/b] This method not the same as the default appearance of properties in the Inspector dock, as it does not capitalize acronyms ([code]"2D"[/code], [code]"FPS"[/code], [code]"PNG"[/code], etc.) as you may expect. </description> </method> <method name="casecmp_to" qualifiers="const"> @@ -949,7 +950,7 @@ <method name="to_lower" qualifiers="const"> <return type="String" /> <description> - Returns the string converted to lowercase. + Returns the string converted to [code]lowercase[/code]. </description> </method> <method name="to_pascal_case" qualifiers="const"> @@ -962,12 +963,25 @@ <return type="String" /> <description> Returns the string converted to [code]snake_case[/code]. + [b]Note:[/b] Numbers followed by a [i]single[/i] letter are not separated in the conversion to keep some words (such as "2D") together. + [codeblocks] + [gdscript] + "Node2D".to_snake_case() # Returns "node_2d" + "2nd place".to_snake_case() # Returns "2_nd_place" + "Texture3DAssetFolder".to_snake_case() # Returns "texture_3d_asset_folder" + [/gdscript] + [csharp] + "Node2D".ToSnakeCase(); // Returns "node_2d" + "2nd place".ToSnakeCase(); // Returns "2_nd_place" + "Texture3DAssetFolder".ToSnakeCase(); // Returns "texture_3d_asset_folder" + [/csharp] + [/codeblocks] </description> </method> <method name="to_upper" qualifiers="const"> <return type="String" /> <description> - Returns the string converted to uppercase. + Returns the string converted to [code]UPPERCASE[/code]. </description> </method> <method name="to_utf8_buffer" qualifiers="const"> diff --git a/doc/classes/StringName.xml b/doc/classes/StringName.xml index 4d9587f7aa..844782eb9a 100644 --- a/doc/classes/StringName.xml +++ b/doc/classes/StringName.xml @@ -8,6 +8,7 @@ You will usually just pass a [String] to methods expecting a [StringName] and it will be automatically converted, but you may occasionally want to construct a [StringName] ahead of time with the [StringName] constructor or, in GDScript, the literal syntax [code]&"example"[/code]. See also [NodePath], which is a similar concept specifically designed to store pre-parsed scene tree paths. All of [String]'s methods are available in this class too. They convert the [StringName] into a string, and they also return a string. This is highly inefficient and should only be used if the string is desired. + [b]Note:[/b] In C#, an explicit conversion to [code]System.String[/code] is required to use the methods listed on this page. Use the [code]ToString()[/code] method to cast a [StringName] to a string, and then use the equivalent methods in [code]System.String[/code] or [code]StringExtensions[/code]. [b]Note:[/b] In a boolean context, a [StringName] will evaluate to [code]false[/code] if it is empty ([code]StringName("")[/code]). Otherwise, a [StringName] will always evaluate to [code]true[/code]. The [code]not[/code] operator cannot be used. Instead, [method is_empty] should be used to check for empty [StringName]s. </description> <tutorials> @@ -90,13 +91,14 @@ [gdscript] "move_local_x".capitalize() # Returns "Move Local X" "sceneFile_path".capitalize() # Returns "Scene File Path" + "2D, FPS, PNG".capitalize() # Returns "2d, Fps, Png" [/gdscript] [csharp] "move_local_x".Capitalize(); // Returns "Move Local X" "sceneFile_path".Capitalize(); // Returns "Scene File Path" + "2D, FPS, PNG".Capitalize(); // Returns "2d, Fps, Png" [/csharp] [/codeblocks] - [b]Note:[/b] This method not the same as the default appearance of properties in the Inspector dock, as it does not capitalize acronyms ([code]"2D"[/code], [code]"FPS"[/code], [code]"PNG"[/code], etc.) as you may expect. </description> </method> <method name="casecmp_to" qualifiers="const"> @@ -856,7 +858,7 @@ <method name="to_lower" qualifiers="const"> <return type="String" /> <description> - Returns the string converted to lowercase. + Returns the string converted to [code]lowercase[/code]. </description> </method> <method name="to_pascal_case" qualifiers="const"> @@ -869,12 +871,25 @@ <return type="String" /> <description> Returns the string converted to [code]snake_case[/code]. + [b]Note:[/b] Numbers followed by a [i]single[/i] letter are not separated in the conversion to keep some words (such as "2D") together. + [codeblocks] + [gdscript] + "Node2D".to_snake_case() # Returns "node_2d" + "2nd place".to_snake_case() # Returns "2_nd_place" + "Texture3DAssetFolder".to_snake_case() # Returns "texture_3d_asset_folder" + [/gdscript] + [csharp] + "Node2D".ToSnakeCase(); // Returns "node_2d" + "2nd place".ToSnakeCase(); // Returns "2_nd_place" + "Texture3DAssetFolder".ToSnakeCase(); // Returns "texture_3d_asset_folder" + [/csharp] + [/codeblocks] </description> </method> <method name="to_upper" qualifiers="const"> <return type="String" /> <description> - Returns the string converted to uppercase. + Returns the string converted to [code]UPPERCASE[/code]. </description> </method> <method name="to_utf8_buffer" qualifiers="const"> diff --git a/doc/classes/SurfaceTool.xml b/doc/classes/SurfaceTool.xml index 5562342eac..32c5f8dff7 100644 --- a/doc/classes/SurfaceTool.xml +++ b/doc/classes/SurfaceTool.xml @@ -125,7 +125,7 @@ <param index="1" name="target_index_count" type="int" default="3" /> <description> Generates a LOD for a given [param nd_threshold] in linear units (square root of quadric error metric), using at most [param target_index_count] indices. - [i]Deprecated.[/i] Unused internally and neglects to preserve normals or UVs. Consider using [method ImporterMesh.generate_lods] instead. + [i]Deprecated.[/i] Unused internally and fails to preserve normals or UVs. Consider using [method ImporterMesh.generate_lods] instead. </description> </method> <method name="generate_normals"> diff --git a/doc/classes/SystemFont.xml b/doc/classes/SystemFont.xml index 239bcc257c..fe93571fbe 100644 --- a/doc/classes/SystemFont.xml +++ b/doc/classes/SystemFont.xml @@ -7,7 +7,7 @@ [SystemFont] loads a font from a system font with the first matching name from [member font_names]. It will attempt to match font style, but it's not guaranteed. The returned font might be part of a font collection or be a variable font with OpenType "weight", "width" and/or "italic" features set. - You can create [FontVariation] of the system font for fine control over its features. + You can create [FontVariation] of the system font for precise control over its features. [b]Note:[/b] This class is implemented on iOS, Linux, macOS and Windows, on other platforms it will fallback to default theme font. </description> <tutorials> diff --git a/doc/classes/TabContainer.xml b/doc/classes/TabContainer.xml index b3a9264569..1f3c3531c6 100644 --- a/doc/classes/TabContainer.xml +++ b/doc/classes/TabContainer.xml @@ -193,6 +193,9 @@ <member name="tab_focus_mode" type="int" setter="set_tab_focus_mode" getter="get_tab_focus_mode" enum="Control.FocusMode" default="2"> The focus access mode for the internal [TabBar] node. </member> + <member name="tabs_position" type="int" setter="set_tabs_position" getter="get_tabs_position" enum="TabContainer.TabPosition" default="0"> + Sets the position of the tab bar. See [enum TabPosition] for details. + </member> <member name="tabs_rearrange_group" type="int" setter="set_tabs_rearrange_group" getter="get_tabs_rearrange_group" default="-1"> [TabContainer]s with the same rearrange group ID will allow dragging the tabs between them. Enable drag with [member drag_to_rearrange_enabled]. Setting this to [code]-1[/code] will disable rearranging between [TabContainer]s. @@ -247,6 +250,17 @@ </description> </signal> </signals> + <constants> + <constant name="POSITION_TOP" value="0" enum="TabPosition"> + Places the tab bar at the top. + </constant> + <constant name="POSITION_BOTTOM" value="1" enum="TabPosition"> + Places the tab bar at the bottom. The tab bar's [StyleBox] will be flipped vertically. + </constant> + <constant name="POSITION_MAX" value="2" enum="TabPosition"> + Represents the size of the [enum TabPosition] enum. + </constant> + </constants> <theme_items> <theme_item name="drop_mark_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> Modulation color for the [theme_item drop_mark] icon. diff --git a/doc/classes/TextEdit.xml b/doc/classes/TextEdit.xml index 4148c4eb09..ea8185fff4 100644 --- a/doc/classes/TextEdit.xml +++ b/doc/classes/TextEdit.xml @@ -1106,7 +1106,7 @@ </member> <member name="caret_move_on_right_click" type="bool" setter="set_move_caret_on_right_click_enabled" getter="is_move_caret_on_right_click_enabled" default="true"> If [code]true[/code], a right-click moves the caret at the mouse position before displaying the context menu. - If [code]false[/code], the context menu disregards mouse location. + If [code]false[/code], the context menu ignores mouse location. </member> <member name="caret_multiple" type="bool" setter="set_multiple_carets_enabled" getter="is_multiple_carets_enabled" default="true"> Sets if multiple carets are allowed. diff --git a/doc/classes/TextServer.xml b/doc/classes/TextServer.xml index 09f484f523..cf4d92d119 100644 --- a/doc/classes/TextServer.xml +++ b/doc/classes/TextServer.xml @@ -1744,6 +1744,7 @@ Vertical BGR subpixel layout. </constant> <constant name="FONT_LCD_SUBPIXEL_LAYOUT_MAX" value="5" enum="FontLCDSubpixelLayout"> + Represents the size of the [enum FontLCDSubpixelLayout] enum. </constant> <constant name="DIRECTION_AUTO" value="0" enum="Direction"> Text direction is determined based on contents and current locale. @@ -1867,6 +1868,7 @@ Determines whether the ellipsis at the end of the text is enforced and may not be hidden. </constant> <constant name="OVERRUN_JUSTIFICATION_AWARE" value="16" enum="TextOverrunFlag" is_bitfield="true"> + Accounts for the text being justified before attempting to trim it (see [enum JustificationFlag]). </constant> <constant name="GRAPHEME_IS_VALID" value="1" enum="GraphemeFlag" is_bitfield="true"> Grapheme is supported by the font, and can be drawn. @@ -2005,6 +2007,7 @@ Spacing at the bottom of the line. </constant> <constant name="SPACING_MAX" value="4" enum="SpacingType"> + Represents the size of the [enum SpacingType] enum. </constant> <constant name="FONT_BOLD" value="1" enum="FontStyle" is_bitfield="true"> Font is bold. diff --git a/doc/classes/Tween.xml b/doc/classes/Tween.xml index 0ecfe53123..b265f8ba11 100644 --- a/doc/classes/Tween.xml +++ b/doc/classes/Tween.xml @@ -5,7 +5,7 @@ </brief_description> <description> Tweens are mostly useful for animations requiring a numerical property to be interpolated over a range of values. The name [i]tween[/i] comes from [i]in-betweening[/i], an animation technique where you specify [i]keyframes[/i] and the computer interpolates the frames that appear between them. Animating something with a [Tween] is called tweening. - [Tween] is more suited than [AnimationPlayer] for animations where you don't know the final values in advance. For example, interpolating a dynamically-chosen camera zoom value is best done with a [Tween]; it would be difficult to do the same thing with an [AnimationPlayer] node. Tweens are also more light-weight than [AnimationPlayer], so they are very much suited for simple animations or general tasks that don't require visual tweaking provided by the editor. They can be used in a fire-and-forget manner for some logic that normally would be done by code. You can e.g. make something shoot periodically by using a looped [CallbackTweener] with a delay. + [Tween] is more suited than [AnimationPlayer] for animations where you don't know the final values in advance. For example, interpolating a dynamically-chosen camera zoom value is best done with a [Tween]; it would be difficult to do the same thing with an [AnimationPlayer] node. Tweens are also more light-weight than [AnimationPlayer], so they are very much suited for simple animations or general tasks that don't require visual tweaking provided by the editor. They can be used in a "fire-and-forget" manner for some logic that normally would be done by code. You can e.g. make something shoot periodically by using a looped [CallbackTweener] with a delay. A [Tween] can be created by using either [method SceneTree.create_tween] or [method Node.create_tween]. [Tween]s created manually (i.e. by using [code]Tween.new()[/code]) are invalid and can't be used for tweening values. A tween animation is created by adding [Tweener]s to the [Tween] object, using [method tween_property], [method tween_interval], [method tween_callback] or [method tween_method]: [codeblocks] diff --git a/doc/classes/Window.xml b/doc/classes/Window.xml index 5f6b1960b7..618a774aae 100644 --- a/doc/classes/Window.xml +++ b/doc/classes/Window.xml @@ -357,10 +357,11 @@ Centers a native window on the current screen and an embedded window on its embedder [Viewport]. </description> </method> - <method name="move_to_foreground"> + <method name="move_to_foreground" is_deprecated="true"> <return type="void" /> <description> Moves the [Window] on top of other windows and focuses it. + [i]Deprecated.[/i] Use [method Window.grab_focus] instead. </description> </method> <method name="popup"> @@ -668,6 +669,9 @@ If [code]true[/code], the [Window] is transient, i.e. it's considered a child of another [Window]. The transient window will be destroyed with its transient parent and will return focus to their parent when closed. The transient window is displayed on top of a non-exclusive full-screen parent window. Transient windows can't enter full-screen mode. Note that behavior might be different depending on the platform. </member> + <member name="transient_to_focused" type="bool" setter="set_transient_to_focused" getter="is_transient_to_focused" default="false"> + If [code]true[/code], and the [Window] is [member transient], this window will (at the time of becoming visible) become transient to the currently focused window instead of the immediate parent window in the hierarchy. Note that the transient parent is assigned at the time this window becomes visible, so changing it afterwards has no effect until re-shown. + </member> <member name="transparent" type="bool" setter="set_flag" getter="get_flag" default="false"> If [code]true[/code], the [Window]'s background can be transparent. This is best used with embedded windows. [b]Note:[/b] Transparency support is implemented on Linux, macOS and Windows, but availability might vary depending on GPU driver, display manager, and compositor capabilities. diff --git a/doc/classes/WorkerThreadPool.xml b/doc/classes/WorkerThreadPool.xml index d6751d31ce..fa1f08b149 100644 --- a/doc/classes/WorkerThreadPool.xml +++ b/doc/classes/WorkerThreadPool.xml @@ -106,7 +106,7 @@ Pauses the thread that calls this method until the task with the given ID is completed. Returns [constant @GlobalScope.OK] if the task could be successfully awaited. Returns [constant @GlobalScope.ERR_INVALID_PARAMETER] if a task with the passed ID does not exist (maybe because it was already awaited and disposed of). - Returns [constant @GlobalScope.ERR_BUSY] if the call is made from another running task and, due to task scheduling, the task to await is at a lower level in the call stack and therefore can't progress. This is an advanced situation that should only matter when some tasks depend on others. + Returns [constant @GlobalScope.ERR_BUSY] if the call is made from another running task and, due to task scheduling, there's potential for deadlocking (e.g., the task to await may be at a lower level in the call stack and therefore can't progress). This is an advanced situation that should only matter when some tasks depend on others (in the current implementation, the tricky case is a task trying to wait on an older one). </description> </method> </methods> |