diff options
Diffstat (limited to 'doc')
76 files changed, 1439 insertions, 479 deletions
diff --git a/doc/classes/@GlobalScope.xml b/doc/classes/@GlobalScope.xml index 09713bce2f..4a6b85f229 100644 --- a/doc/classes/@GlobalScope.xml +++ b/doc/classes/@GlobalScope.xml @@ -16,7 +16,7 @@ <return type="Variant" /> <param index="0" name="x" type="Variant" /> <description> - Returns the absolute value of a [Variant] parameter [param x] (i.e. non-negative value). Variant types [int], [float], [Vector2], [Vector2i], [Vector3] and [Vector3i] are supported. + Returns the absolute value of a [Variant] parameter [param x] (i.e. non-negative value). Supported types: [int], [float], [Vector2], [Vector2i], [Vector3], [Vector3i], [Vector4], [Vector4i]. [codeblock] var a = abs(-1) # a is 1 @@ -36,6 +36,7 @@ var f = abs(Vector3i(-7, -8, -9)) # f is (7, 8, 9) [/codeblock] + [b]Note:[/b] For better type safety, use [method absf], [method absi], [method Vector2.abs], [method Vector2i.abs], [method Vector3.abs], [method Vector3i.abs], [method Vector4.abs], or [method Vector4i.abs]. </description> </method> <method name="absf"> @@ -106,6 +107,17 @@ [/codeblock] </description> </method> + <method name="bezier_derivative"> + <return type="float" /> + <param index="0" name="start" type="float" /> + <param index="1" name="control_1" type="float" /> + <param index="2" name="control_2" type="float" /> + <param index="3" name="end" type="float" /> + <param index="4" name="t" type="float" /> + <description> + Returns the derivative at the given [param t] on a one-dimensional [url=https://en.wikipedia.org/wiki/B%C3%A9zier_curve]Bézier curve[/url] defined by the given [param control_1], [param control_2], and [param end] points. + </description> + </method> <method name="bezier_interpolate"> <return type="float" /> <param index="0" name="start" type="float" /> @@ -114,7 +126,7 @@ <param index="3" name="end" type="float" /> <param index="4" name="t" type="float" /> <description> - Returns the point at the given [param t] on a one-dimensional [url=https://en.wikipedia.org/wiki/B%C3%A9zier_curve]Bezier curve[/url] defined by the given [param control_1], [param control_2], and [param end] points. + Returns the point at the given [param t] on a one-dimensional [url=https://en.wikipedia.org/wiki/B%C3%A9zier_curve]Bézier curve[/url] defined by the given [param control_1], [param control_2], and [param end] points. </description> </method> <method name="bytes_to_var"> @@ -143,7 +155,7 @@ i = ceil(1.001) # i is 2.0 [/codeblock] See also [method floor], [method round], and [method snapped]. - [b]Note:[/b] For better type safety, see [method ceilf], [method ceili], [method Vector2.ceil], [method Vector3.ceil] and [method Vector4.ceil]. + [b]Note:[/b] For better type safety, use [method ceilf], [method ceili], [method Vector2.ceil], [method Vector3.ceil], or [method Vector4.ceil]. </description> </method> <method name="ceilf"> @@ -168,7 +180,7 @@ <param index="1" name="min" type="Variant" /> <param index="2" name="max" type="Variant" /> <description> - Clamps the [param value], returning a [Variant] not less than [param min] and not more than [param max]. Variant types [int], [float], [Vector2], [Vector2i], [Vector3] and [Vector3i] are supported. + Clamps the [param value], returning a [Variant] not less than [param min] and not more than [param max]. Supported types: [int], [float], [Vector2], [Vector2i], [Vector3], [Vector3i], [Vector4], [Vector4i]. [codeblock] var a = clamp(-10, -1, 5) # a is -1 @@ -188,6 +200,7 @@ var f = clamp(Vector3i(-7, -8, -9), Vector3i(-1, 2, 3), Vector3i(-4, -5, -6)) # f is (-4, -5, -6) [/codeblock] + [b]Note:[/b] For better type safety, use [method clampf], [method clampi], [method Vector2.clamp], [method Vector2i.clamp], [method Vector3.clamp], [method Vector3i.clamp], [method Vector4.clamp], or [method Vector4i.clamp]. </description> </method> <method name="clampf"> @@ -367,7 +380,7 @@ a = floor(-2.99) # a is -3.0 [/codeblock] See also [method ceil], [method round], and [method snapped]. - [b]Note:[/b] For better type safety, see [method floorf], [method floori], [method Vector2.floor], [method Vector3.floor] and [method Vector4.floor]. + [b]Note:[/b] For better type safety, use [method floorf], [method floori], [method Vector2.floor], [method Vector3.floor], or [method Vector4.floor]. </description> </method> <method name="floorf"> @@ -527,7 +540,7 @@ <param index="2" name="weight" type="Variant" /> <description> Linearly interpolates between two values by the factor defined in [param weight]. To perform interpolation, [param weight] should be between [code]0.0[/code] and [code]1.0[/code] (inclusive). However, values outside this range are allowed and can be used to perform [i]extrapolation[/i]. If this is not desired, use [method clamp] on the result of this function. - Both [param from] and [param to] must be the same type. Supported types: [float], [Vector2], [Vector3], [Vector4], [Color], [Quaternion], [Basis]. + Both [param from] and [param to] must be the same type. Supported types: [int], [float], [Vector2], [Vector3], [Vector4], [Color], [Quaternion], [Basis]. [codeblock] lerp(0, 4, 0.75) # Returns 3.0 [/codeblock] @@ -783,14 +796,13 @@ </method> <method name="printraw" qualifiers="vararg"> <description> - Prints one or more arguments to strings in the best way possible to console. Unlike [method print], no newline is automatically added at the end. + Prints one or more arguments to strings in the best way possible to the OS terminal. Unlike [method print], no newline is automatically added at the end. [codeblock] printraw("A") printraw("B") printraw("C") - # Prints ABC + # Prints ABC to terminal [/codeblock] - [b]Note:[/b] Due to limitations with Godot's built-in console, this only prints to the terminal. If you need to print in the editor, use another method, such as [method print]. </description> </method> <method name="prints" qualifiers="vararg"> @@ -950,7 +962,7 @@ round(2.6) # Returns 3 [/codeblock] See also [method floor], [method ceil], and [method snapped]. - [b]Note:[/b] For better type safety, use [method roundf], [method roundi], [method Vector2.round], [method Vector3.round] or [method Vector4.round], instead. + [b]Note:[/b] For better type safety, use [method roundf], [method roundi], [method Vector2.round], [method Vector3.round], or [method Vector4.round]. </description> </method> <method name="roundf"> @@ -987,21 +999,22 @@ <return type="Variant" /> <param index="0" name="x" type="Variant" /> <description> - Returns the sign of [param x] as same type of [Variant] as [param x] with each component being -1, 0 and 1 for each negative, zero and positive values respectively. Variant types [int], [float], [Vector2], [Vector2i], [Vector3] and [Vector3i] are supported. + Returns the same type of [Variant] as [param x], with [code]-1[/code] for negative values, [code]1[/code] for positive values, and [code]0[/code] for zeros. Supported types: [int], [float], [Vector2], [Vector2i], [Vector3], [Vector3i], [Vector4], [Vector4i]. [codeblock] sign(-6.0) # Returns -1 sign(0.0) # Returns 0 sign(6.0) # Returns 1 - sign(Vector3(-6.0, 0.0, 6.0) # Returns (-1, 0, 1) + sign(Vector3(-6.0, 0.0, 6.0)) # Returns (-1, 0, 1) [/codeblock] + [b]Note:[/b] For better type safety, use [method signf], [method signi], [method Vector2.sign], [method Vector2i.sign], [method Vector3.sign], [method Vector3i.sign], [method Vector4.sign], or [method Vector4i.sign]. </description> </method> <method name="signf"> <return type="float" /> <param index="0" name="x" type="float" /> <description> - Returns the sign of [param x] as a [float]: -1.0 or 1.0. Returns 0.0 if [param x] is 0.0. + Returns [code]-1.0[/code] if [param x] is negative, [code]1.0[/code] if [param x] is positive, and [code]0.0[/code] if if [param x] is zero. [codeblock] sign(-6.5) # Returns -1.0 sign(0.0) # Returns 0.0 @@ -1013,7 +1026,7 @@ <return type="int" /> <param index="0" name="x" type="int" /> <description> - Returns the sign of [param x] as an [int]: -1 or 1. Returns 0 if [param x] is 0. + Returns [code]-1[/code] if [param x] is negative, [code]1[/code] if [param x] is positive, and [code]0[/code] if if [param x] is zero. [codeblock] sign(-6) # Returns -1 sign(0) # Returns 0 @@ -1063,16 +1076,46 @@ </description> </method> <method name="snapped"> + <return type="Variant" /> + <param index="0" name="x" type="Variant" /> + <param index="1" name="step" type="Variant" /> + <description> + Returns the multiple of [param step] that is the closest to [param x]. This can also be used to round a floating point number to an arbitrary number of decimals. + The returned value is the same type of [Variant] as [param step]. Supported types: [int], [float], [Vector2], [Vector2i], [Vector3], [Vector3i], [Vector4], [Vector4i]. + [codeblock] + snapped(100, 32) # Returns 96 + snapped(3.14159, 0.01) # Returns 3.14 + + snapped(Vector2(34, 70), Vector2(8, 8)) # Returns (32, 72) + [/codeblock] + See also [method ceil], [method floor], and [method round]. + [b]Note:[/b] For better type safety, use [method snappedf], [method snappedi], [method Vector2.snapped], [method Vector2i.snapped], [method Vector3.snapped], [method Vector3i.snapped], [method Vector4.snapped], or [method Vector4i.snapped]. + </description> + </method> + <method name="snappedf"> <return type="float" /> <param index="0" name="x" type="float" /> <param index="1" name="step" type="float" /> <description> - Snaps the float value [param x] to a given [param step]. This can also be used to round a floating point number to an arbitrary number of decimals. + Returns the multiple of [param step] that is the closest to [param x]. This can also be used to round a floating point number to an arbitrary number of decimals. + A type-safe version of [method snapped], returning a [float]. [codeblock] - snapped(100, 32) # Returns 96 - snapped(3.14159, 0.01) # Returns 3.14 + snapped(32.0, 2.5) # Returns 32.5 + snapped(3.14159, 0.01) # Returns 3.14 + [/codeblock] + </description> + </method> + <method name="snappedi"> + <return type="int" /> + <param index="0" name="x" type="float" /> + <param index="1" name="step" type="int" /> + <description> + Returns the multiple of [param step] that is the closest to [param x]. + A type-safe version of [method snapped], returning an [int]. + [codeblock] + snapped(53, 16) # Returns 48 + snapped(4096, 100) # Returns 4100 [/codeblock] - See also [method ceil], [method floor], and [method round]. </description> </method> <method name="sqrt"> @@ -2834,40 +2877,38 @@ </constant> <constant name="PROPERTY_USAGE_STORE_IF_NULL" value="8192" enum="PropertyUsageFlags"> </constant> - <constant name="PROPERTY_USAGE_ANIMATE_AS_TRIGGER" value="16384" enum="PropertyUsageFlags"> - </constant> - <constant name="PROPERTY_USAGE_UPDATE_ALL_IF_MODIFIED" value="32768" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_UPDATE_ALL_IF_MODIFIED" value="16384" enum="PropertyUsageFlags"> </constant> - <constant name="PROPERTY_USAGE_SCRIPT_DEFAULT_VALUE" value="65536" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_SCRIPT_DEFAULT_VALUE" value="32768" enum="PropertyUsageFlags"> </constant> - <constant name="PROPERTY_USAGE_CLASS_IS_ENUM" value="131072" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_CLASS_IS_ENUM" value="65536" enum="PropertyUsageFlags"> </constant> - <constant name="PROPERTY_USAGE_NIL_IS_VARIANT" value="262144" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_NIL_IS_VARIANT" value="131072" enum="PropertyUsageFlags"> </constant> - <constant name="PROPERTY_USAGE_INTERNAL" value="524288" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_INTERNAL" value="262144" enum="PropertyUsageFlags"> </constant> - <constant name="PROPERTY_USAGE_DO_NOT_SHARE_ON_DUPLICATE" value="1048576" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_DO_NOT_SHARE_ON_DUPLICATE" value="524288" enum="PropertyUsageFlags"> If the property is a [Resource], a new copy of it is always created when calling [method Node.duplicate] or [method Resource.duplicate]. </constant> - <constant name="PROPERTY_USAGE_HIGH_END_GFX" value="2097152" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_HIGH_END_GFX" value="1048576" enum="PropertyUsageFlags"> The property is only shown in the editor if modern renderers are supported (GLES3 is excluded). </constant> - <constant name="PROPERTY_USAGE_NODE_PATH_FROM_SCENE_ROOT" value="4194304" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_NODE_PATH_FROM_SCENE_ROOT" value="2097152" enum="PropertyUsageFlags"> </constant> - <constant name="PROPERTY_USAGE_RESOURCE_NOT_PERSISTENT" value="8388608" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_RESOURCE_NOT_PERSISTENT" value="4194304" enum="PropertyUsageFlags"> </constant> - <constant name="PROPERTY_USAGE_KEYING_INCREMENTS" value="16777216" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_KEYING_INCREMENTS" value="8388608" enum="PropertyUsageFlags"> </constant> - <constant name="PROPERTY_USAGE_DEFERRED_SET_RESOURCE" value="33554432" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_DEFERRED_SET_RESOURCE" value="16777216" enum="PropertyUsageFlags"> </constant> - <constant name="PROPERTY_USAGE_EDITOR_INSTANTIATE_OBJECT" value="67108864" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_EDITOR_INSTANTIATE_OBJECT" value="33554432" enum="PropertyUsageFlags"> </constant> - <constant name="PROPERTY_USAGE_EDITOR_BASIC_SETTING" value="134217728" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_EDITOR_BASIC_SETTING" value="67108864" enum="PropertyUsageFlags"> </constant> - <constant name="PROPERTY_USAGE_READ_ONLY" value="268435456" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_READ_ONLY" value="134217728" enum="PropertyUsageFlags"> The property is read-only in the [EditorInspector]. </constant> - <constant name="PROPERTY_USAGE_ARRAY" value="536870912" enum="PropertyUsageFlags"> + <constant name="PROPERTY_USAGE_ARRAY" value="268435456" enum="PropertyUsageFlags"> The property is an array. </constant> <constant name="PROPERTY_USAGE_DEFAULT" value="6" enum="PropertyUsageFlags"> diff --git a/doc/classes/Animation.xml b/doc/classes/Animation.xml index af8d9c416f..d9a1f896f1 100644 --- a/doc/classes/Animation.xml +++ b/doc/classes/Animation.xml @@ -251,15 +251,6 @@ Returns the amount of tracks in the animation. </description> </method> - <method name="method_track_get_key_indices" qualifiers="const"> - <return type="PackedInt32Array" /> - <param index="0" name="track_idx" type="int" /> - <param index="1" name="time_sec" type="float" /> - <param index="2" name="delta" type="float" /> - <description> - Returns all the key indices of a method track, given a position and delta time. - </description> - </method> <method name="method_track_get_name" qualifiers="const"> <return type="StringName" /> <param index="0" name="track_idx" type="int" /> @@ -523,15 +514,6 @@ Swaps the track [param track_idx]'s index position with the track [param with_idx]. </description> </method> - <method name="value_track_get_key_indices" qualifiers="const"> - <return type="PackedInt32Array" /> - <param index="0" name="track_idx" type="int" /> - <param index="1" name="time_sec" type="float" /> - <param index="2" name="delta" type="float" /> - <description> - Returns all the key indices of a value track, given a position and delta time. - </description> - </method> <method name="value_track_get_update_mode" qualifiers="const"> <return type="int" enum="Animation.UpdateMode" /> <param index="0" name="track_idx" type="int" /> @@ -614,15 +596,12 @@ [b]Note:[/b] The result value is always normalized and may not match the key value. </constant> <constant name="UPDATE_CONTINUOUS" value="0" enum="UpdateMode"> - Update between keyframes. + Update between keyframes and hold the value. </constant> <constant name="UPDATE_DISCRETE" value="1" enum="UpdateMode"> - Update at the keyframes and hold the value. - </constant> - <constant name="UPDATE_TRIGGER" value="2" enum="UpdateMode"> Update at the keyframes. </constant> - <constant name="UPDATE_CAPTURE" value="3" enum="UpdateMode"> + <constant name="UPDATE_CAPTURE" value="2" enum="UpdateMode"> Same as linear interpolation, but also interpolates from the current value (i.e. dynamically at runtime) if the first key isn't at 0 seconds. </constant> <constant name="LOOP_NONE" value="0" enum="LoopMode"> @@ -634,5 +613,14 @@ <constant name="LOOP_PINGPONG" value="2" enum="LoopMode"> Repeats playback and reverse playback at both ends of the animation. </constant> + <constant name="LOOPED_FLAG_NONE" value="0" enum="LoopedFlag"> + This flag indicates that the animation proceeds without any looping. + </constant> + <constant name="LOOPED_FLAG_END" value="1" enum="LoopedFlag"> + This flag indicates that the animation has reached the end of the animation and just after loop processed. + </constant> + <constant name="LOOPED_FLAG_START" value="2" enum="LoopedFlag"> + This flag indicates that the animation has reached the start of the animation and just after loop processed. + </constant> </constants> </class> diff --git a/doc/classes/AnimationLibrary.xml b/doc/classes/AnimationLibrary.xml index 769b338063..9be4cda5d6 100644 --- a/doc/classes/AnimationLibrary.xml +++ b/doc/classes/AnimationLibrary.xml @@ -65,6 +65,13 @@ Emitted when an [Animation] is added, under the key [param name]. </description> </signal> + <signal name="animation_changed"> + <param index="0" name="name" type="StringName" /> + <description> + Emitted when there's a change in one of the animations, e.g. tracks are added, moved or have changed paths. [param name] is the key of the animation that was changed. + See also [signal Resource.changed], which this acts as a relay for. + </description> + </signal> <signal name="animation_removed"> <param index="0" name="name" type="StringName" /> <description> diff --git a/doc/classes/AnimationNode.xml b/doc/classes/AnimationNode.xml index b856b5f208..79deb008d2 100644 --- a/doc/classes/AnimationNode.xml +++ b/doc/classes/AnimationNode.xml @@ -53,7 +53,7 @@ <return type="float" /> <param index="0" name="time" type="float" /> <param index="1" name="seek" type="bool" /> - <param index="2" name="seek_root" type="bool" /> + <param index="2" name="is_external_seeking" type="bool" /> <description> When inheriting from [AnimationRootNode], implement this virtual method to run some code when this node is processed. The [param time] parameter is a relative delta, unless [param seek] is [code]true[/code], in which case it is absolute. Here, call the [method blend_input], [method blend_node] or [method blend_animation] functions. You can also use [method get_parameter] and [method set_parameter] to modify local memory. @@ -73,11 +73,12 @@ <param index="1" name="time" type="float" /> <param index="2" name="delta" type="float" /> <param index="3" name="seeked" type="bool" /> - <param index="4" name="seek_root" type="bool" /> + <param index="4" name="is_external_seeking" type="bool" /> <param index="5" name="blend" type="float" /> - <param index="6" name="pingponged" type="int" default="0" /> + <param index="6" name="looped_flag" type="int" enum="Animation.LoopedFlag" default="0" /> <description> Blend an animation by [param blend] amount (name must be valid in the linked [AnimationPlayer]). A [param time] and [param delta] may be passed, as well as whether [param seeked] happened. + A [param looped_flag] is used by internal processing immediately after the loop. See also [enum Animation.LoopedFlag]. </description> </method> <method name="blend_input"> @@ -85,7 +86,7 @@ <param index="0" name="input_index" type="int" /> <param index="1" name="time" type="float" /> <param index="2" name="seek" type="bool" /> - <param index="3" name="seek_root" type="bool" /> + <param index="3" name="is_external_seeking" type="bool" /> <param index="4" name="blend" type="float" /> <param index="5" name="filter" type="int" enum="AnimationNode.FilterAction" default="0" /> <param index="6" name="sync" type="bool" default="true" /> @@ -99,7 +100,7 @@ <param index="1" name="node" type="AnimationNode" /> <param index="2" name="time" type="float" /> <param index="3" name="seek" type="bool" /> - <param index="4" name="seek_root" type="bool" /> + <param index="4" name="is_external_seeking" type="bool" /> <param index="5" name="blend" type="float" /> <param index="6" name="filter" type="int" enum="AnimationNode.FilterAction" default="0" /> <param index="7" name="sync" type="bool" default="true" /> diff --git a/doc/classes/AnimationTree.xml b/doc/classes/AnimationTree.xml index 27797b00b5..21f4b37741 100644 --- a/doc/classes/AnimationTree.xml +++ b/doc/classes/AnimationTree.xml @@ -19,10 +19,66 @@ Manually advance the animations by the specified time (in seconds). </description> </method> - <method name="get_root_motion_transform" qualifiers="const"> - <return type="Transform3D" /> + <method name="get_root_motion_position" qualifiers="const"> + <return type="Vector3" /> <description> - Retrieve the motion of the [member root_motion_track] as a [Transform3D] that can be used elsewhere. If [member root_motion_track] is not a path to a track of type [constant Animation.TYPE_POSITION_3D], [constant Animation.TYPE_SCALE_3D] or [constant Animation.TYPE_ROTATION_3D], returns an identity transformation. See also [member root_motion_track] and [RootMotionView]. + Retrieve the motion of position with the [member root_motion_track] as a [Vector3] that can be used elsewhere. + If [member root_motion_track] is not a path to a track of type [constant Animation.TYPE_POSITION_3D], returns [code]Vector3(0, 0, 0)[/code]. + See also [member root_motion_track] and [RootMotionView]. + The most basic example is applying position to [CharacterBody3D]: + [codeblocks] + [gdscript] + var current_rotation: Quaternion + + func _process(delta): + if Input.is_action_just_pressed("animate"): + current_rotation = get_quaternion() + state_machine.travel("Animate") + var velocity: Vector3 = current_rotation * animation_tree.get_root_motion_position() / delta + set_velocity(velocity) + move_and_slide() + [/gdscript] + [/codeblocks] + </description> + </method> + <method name="get_root_motion_rotation" qualifiers="const"> + <return type="Quaternion" /> + <description> + Retrieve the motion of rotation with the [member root_motion_track] as a [Quaternion] that can be used elsewhere. + If [member root_motion_track] is not a path to a track of type [constant Animation.TYPE_ROTATION_3D], returns [code]Quaternion(0, 0, 0, 1)[/code]. + See also [member root_motion_track] and [RootMotionView]. + The most basic example is applying rotation to [CharacterBody3D]: + [codeblocks] + [gdscript] + func _process(delta): + if Input.is_action_just_pressed("animate"): + state_machine.travel("Animate") + set_quaternion(get_quaternion() * animation_tree.get_root_motion_rotation()) + [/gdscript] + [/codeblocks] + </description> + </method> + <method name="get_root_motion_scale" qualifiers="const"> + <return type="Vector3" /> + <description> + Retrieve the motion of scale with the [member root_motion_track] as a [Vector3] that can be used elsewhere. + If [member root_motion_track] is not a path to a track of type [constant Animation.TYPE_SCALE_3D], returns [code]Vector3(0, 0, 0)[/code]. + See also [member root_motion_track] and [RootMotionView]. + The most basic example is applying scale to [CharacterBody3D]: + [codeblocks] + [gdscript] + var current_scale: Vector3 = Vector3(1, 1, 1) + var scale_accum: Vector3 = Vector3(1, 1, 1) + + func _process(delta): + if Input.is_action_just_pressed("animate"): + current_scale = get_scale() + scale_accum = Vector3(1, 1, 1) + state_machine.travel("Animate") + scale_accum += animation_tree.get_root_motion_scale() + set_scale(current_scale * scale_accum) + [/gdscript] + [/codeblocks] </description> </method> <method name="rename_parameter"> @@ -48,7 +104,7 @@ </member> <member name="root_motion_track" type="NodePath" setter="set_root_motion_track" getter="get_root_motion_track" default="NodePath("")"> The path to the Animation track used for root motion. Paths must be valid scene-tree paths to a node, and must be specified starting from the parent node of the node that will reproduce the animation. To specify a track that controls properties or bones, append its name after the path, separated by [code]":"[/code]. For example, [code]"character/skeleton:ankle"[/code] or [code]"character/mesh:transform/local"[/code]. - If the track has type [constant Animation.TYPE_POSITION_3D], [constant Animation.TYPE_ROTATION_3D] or [constant Animation.TYPE_SCALE_3D] the transformation will be cancelled visually, and the animation will appear to stay in place. See also [method get_root_motion_transform] and [RootMotionView]. + If the track has type [constant Animation.TYPE_POSITION_3D], [constant Animation.TYPE_ROTATION_3D] or [constant Animation.TYPE_SCALE_3D] the transformation will be cancelled visually, and the animation will appear to stay in place. See also [method get_root_motion_position], [method get_root_motion_rotation], [method get_root_motion_scale] and [RootMotionView]. </member> <member name="tree_root" type="AnimationNode" setter="set_tree_root" getter="get_tree_root"> The root animation node of this [AnimationTree]. See [AnimationNode]. diff --git a/doc/classes/Array.xml b/doc/classes/Array.xml index 2ec37651f7..603974d619 100644 --- a/doc/classes/Array.xml +++ b/doc/classes/Array.xml @@ -300,13 +300,6 @@ Searches the array for a value and returns its index or [code]-1[/code] if not found. Optionally, the initial search index can be passed. </description> </method> - <method name="find_last" qualifiers="const"> - <return type="int" /> - <param index="0" name="value" type="Variant" /> - <description> - Searches the array in reverse order for a value and returns its index or [code]-1[/code] if not found. - </description> - </method> <method name="front" qualifiers="const"> <return type="Variant" /> <description> diff --git a/doc/classes/AudioEffectDistortion.xml b/doc/classes/AudioEffectDistortion.xml index 6bd8522459..ef39a9c60e 100644 --- a/doc/classes/AudioEffectDistortion.xml +++ b/doc/classes/AudioEffectDistortion.xml @@ -2,11 +2,11 @@ <class name="AudioEffectDistortion" inherits="AudioEffect" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Adds a distortion audio effect to an Audio bus. - Modify the sound to make it distorted. + Modifies the sound to make it distorted. </brief_description> <description> Different types are available: clip, tan, lo-fi (bit crushing), overdrive, or waveshape. - By distorting the waveform the frequency content change, which will often make the sound "crunchy" or "abrasive". For games, it can simulate sound coming from some saturated device or speaker very efficiently. + By distorting the waveform the frequency content changes, which will often make the sound "crunchy" or "abrasive". For games, it can simulate sound coming from some saturated device or speaker very efficiently. </description> <tutorials> <link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link> @@ -22,10 +22,10 @@ Distortion type. </member> <member name="post_gain" type="float" setter="set_post_gain" getter="get_post_gain" default="0.0"> - Increases or decreases the volume after the effect. Value can range from -80 to 24. + Increases or decreases the volume after the effect, in decibels. Value can range from -80 to 24. </member> <member name="pre_gain" type="float" setter="set_pre_gain" getter="get_pre_gain" default="0.0"> - Increases or decreases the volume before the effect. Value can range from -60 to 60. + Increases or decreases the volume before the effect, in decibels. Value can range from -60 to 60. </member> </members> <constants> @@ -35,10 +35,10 @@ <constant name="MODE_ATAN" value="1" enum="Mode"> </constant> <constant name="MODE_LOFI" value="2" enum="Mode"> - Low-resolution digital distortion effect. You can use it to emulate the sound of early digital audio devices. + Low-resolution digital distortion effect (bit depth reduction). You can use it to emulate the sound of early digital audio devices. </constant> <constant name="MODE_OVERDRIVE" value="3" enum="Mode"> - Emulates the warm distortion produced by a field effect transistor, which is commonly used in solid-state musical instrument amplifiers. + Emulates the warm distortion produced by a field effect transistor, which is commonly used in solid-state musical instrument amplifiers. The [member drive] property has no effect in this mode. </constant> <constant name="MODE_WAVESHAPE" value="4" enum="Mode"> Waveshaper distortions are used mainly by electronic musicians to achieve an extra-abrasive sound. diff --git a/doc/classes/AudioStreamPlayer2D.xml b/doc/classes/AudioStreamPlayer2D.xml index ae86fd0e66..81755b580f 100644 --- a/doc/classes/AudioStreamPlayer2D.xml +++ b/doc/classes/AudioStreamPlayer2D.xml @@ -29,7 +29,7 @@ <return type="void" /> <param index="0" name="from_position" type="float" default="0.0" /> <description> - Plays the audio from the given position [param from_position], in seconds. + Queues the audio to play on the next physics frame, from the given position [param from_position], in seconds. </description> </method> <method name="seek"> @@ -73,7 +73,7 @@ The pitch and the tempo of the audio, as a multiplier of the audio sample's sample rate. </member> <member name="playing" type="bool" setter="_set_playing" getter="is_playing" default="false"> - If [code]true[/code], audio is playing. + If [code]true[/code], audio is playing or is queued to be played (see [method play]). </member> <member name="stream" type="AudioStream" setter="set_stream" getter="get_stream"> The [AudioStream] object to be played. diff --git a/doc/classes/AudioStreamPlayer3D.xml b/doc/classes/AudioStreamPlayer3D.xml index 11d6e9cc7a..f711210ca1 100644 --- a/doc/classes/AudioStreamPlayer3D.xml +++ b/doc/classes/AudioStreamPlayer3D.xml @@ -29,7 +29,7 @@ <return type="void" /> <param index="0" name="from_position" type="float" default="0.0" /> <description> - Plays the audio from the given position [param from_position], in seconds. + Queues the audio to play on the next physics frame, from the given position [param from_position], in seconds. </description> </method> <method name="seek"> @@ -94,7 +94,7 @@ The pitch and the tempo of the audio, as a multiplier of the audio sample's sample rate. </member> <member name="playing" type="bool" setter="_set_playing" getter="is_playing" default="false"> - If [code]true[/code], audio is playing. + If [code]true[/code], audio is playing or is queued to be played (see [method play]). </member> <member name="stream" type="AudioStream" setter="set_stream" getter="get_stream"> The [AudioStream] resource to be played. diff --git a/doc/classes/BaseMaterial3D.xml b/doc/classes/BaseMaterial3D.xml index fbb31cadcd..8a5048de6b 100644 --- a/doc/classes/BaseMaterial3D.xml +++ b/doc/classes/BaseMaterial3D.xml @@ -319,7 +319,7 @@ Texture that controls the strength of the refraction per-pixel. Multiplied by [member refraction_scale]. </member> <member name="refraction_texture_channel" type="int" setter="set_refraction_texture_channel" getter="get_refraction_texture_channel" enum="BaseMaterial3D.TextureChannel" default="0"> - Specifies the channel of the [member ao_texture] in which the ambient occlusion information is stored. This is useful when you store the information for multiple effects in a single texture. For example if you stored metallic in the red channel, roughness in the blue, and ambient occlusion in the green you could reduce the number of textures you use. + Specifies the channel of the [member refraction_texture] in which the refraction information is stored. This is useful when you store the information for multiple effects in a single texture. For example if you stored refraction in the red channel, roughness in the blue, and ambient occlusion in the green you could reduce the number of textures you use. </member> <member name="rim" type="float" setter="set_rim" getter="get_rim" default="1.0"> Sets the strength of the rim lighting effect. @@ -341,7 +341,7 @@ Texture used to control the roughness per-pixel. Multiplied by [member roughness]. </member> <member name="roughness_texture_channel" type="int" setter="set_roughness_texture_channel" getter="get_roughness_texture_channel" enum="BaseMaterial3D.TextureChannel" default="0"> - Specifies the channel of the [member ao_texture] in which the ambient occlusion information is stored. This is useful when you store the information for multiple effects in a single texture. For example if you stored metallic in the red channel, roughness in the blue, and ambient occlusion in the green you could reduce the number of textures you use. + Specifies the channel of the [member roughness_texture] in which the roughness information is stored. This is useful when you store the information for multiple effects in a single texture. For example if you stored metallic in the red channel, roughness in the blue, and ambient occlusion in the green you could reduce the number of textures you use. </member> <member name="shading_mode" type="int" setter="set_shading_mode" getter="get_shading_mode" enum="BaseMaterial3D.ShadingMode" default="1"> Sets whether the shading takes place per-pixel or per-vertex. Per-vertex lighting is faster, making it the best choice for mobile applications, however it looks considerably worse than per-pixel. diff --git a/doc/classes/Callable.xml b/doc/classes/Callable.xml index dd48ee6790..1fb4f91920 100644 --- a/doc/classes/Callable.xml +++ b/doc/classes/Callable.xml @@ -1,10 +1,10 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="Callable" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - An object representing a method in a certain object that can be called. + Built-in type representing a method in an object instance or a standalone function. </brief_description> <description> - [Callable] is a first class object which can be held in variables and passed to functions. It represents a given method in an [Object], and is typically used for signal callbacks. + [Callable] is a built-in [Variant] type that represents a function. It can either be a method within an [Object] instance, or a standalone function not related to any object, like a lambda function. Like all [Variant] types, it can be stored in variables and passed to other functions. It is most commonly used for signal callbacks. [b]Example:[/b] [codeblocks] [gdscript] @@ -32,6 +32,18 @@ } [/csharp] [/codeblocks] + In GDScript, it's possible to create lambda functions within a method. Lambda functions are custom callables that are not associated with an [Object] instance. Optionally, lambda functions can also be named. The name will be displayed in the debugger, or when calling [method get_method]. + [codeblock] + func _init(): + var my_lambda = func (message): + print(message) + + # Prints Hello everyone! + my_lambda.call("Hello everyone!") + + # Prints "Attack!", when the button_pressed signal is emitted. + button_pressed.connect(func(): print("Attack!")) + [/codeblock] </description> <tutorials> </tutorials> @@ -39,7 +51,7 @@ <constructor name="Callable"> <return type="Callable" /> <description> - Constructs a null [Callable] with no object nor method bound. + Constructs an empty [Callable], with no object nor method bound. </description> </constructor> <constructor name="Callable"> @@ -54,7 +66,7 @@ <param index="0" name="object" type="Object" /> <param index="1" name="method" type="StringName" /> <description> - Creates a new [Callable] for the method called [param method] in the specified [param object]. + Creates a new [Callable] for the method named [param method] in the specified [param object]. </description> </constructor> </constructors> @@ -62,7 +74,7 @@ <method name="bind" qualifiers="vararg const"> <return type="Callable" /> <description> - Returns a copy of this [Callable] with the arguments bound. Bound arguments are passed after the arguments supplied by [method call]. + Returns a copy of this [Callable] with one or more arguments bound. When called, the bound arguments are passed [i]after[/i] the arguments supplied by [method call]. </description> </method> <method name="call" qualifiers="vararg const"> @@ -85,13 +97,13 @@ <return type="Variant" /> <param index="0" name="arguments" type="Array" /> <description> - Calls the method represented by this [Callable]. Contrary to [method call], this method does not take a variable number of arguments but expects all arguments to be passed via a single [Array]. + Calls the method represented by this [Callable]. Unlike [method call], this method expects all arguments to be contained inside the [param arguments] [Array]. </description> </method> <method name="get_method" qualifiers="const"> <return type="StringName" /> <description> - Returns the name of the method represented by this [Callable]. + Returns the name of the method represented by this [Callable]. If the callable is a lambda function, returns the function's name. </description> </method> <method name="get_object" qualifiers="const"> @@ -116,7 +128,7 @@ <method name="is_custom" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if this [Callable] is a custom callable whose behavior differs based on implementation details. Custom callables are used in the engine for various reasons. If [code]true[/code], you can't use [method get_method]. + Returns [code]true[/code] if this [Callable] is a custom callable. Custom callables are created from [method bind] or [method unbind]. In GDScript, lambda functions are also custom callables. </description> </method> <method name="is_null" qualifiers="const"> @@ -128,33 +140,33 @@ <method name="is_standard" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if this [Callable] is a standard callable, referencing an object and a method using a [StringName]. + Returns [code]true[/code] if this [Callable] is a standard callable. This method is the opposite of [method is_custom]. Returns [code]false[/code] if this callable is a lambda function. </description> </method> <method name="is_valid" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if the object exists and has a valid function assigned, or is a custom callable. + Returns [code]true[/code] if the callable's object exists and has a valid method name assigned, or is a custom callable. </description> </method> <method name="rpc" qualifiers="vararg const"> <return type="void" /> <description> - Perform an RPC (Remote Procedure Call). This is used for multiplayer and is normally not available unless the function being called has been marked as [i]RPC[/i]. Calling it on unsupported functions will result in an error. + Perform an RPC (Remote Procedure Call). This is used for multiplayer and is normally not available, unless the function being called has been marked as [i]RPC[/i]. Calling this method on unsupported functions will result in an error. </description> </method> <method name="rpc_id" qualifiers="vararg const"> <return type="void" /> <param index="0" name="peer_id" type="int" /> <description> - Perform an RPC (Remote Procedure Call) on a specific peer ID (see multiplayer documentation for reference). This is used for multiplayer and is normally not available unless the function being called has been marked as [i]RPC[/i]. Calling it on unsupported functions will result in an error. + Perform an RPC (Remote Procedure Call) on a specific peer ID (see multiplayer documentation for reference). This is used for multiplayer and is normally not available unless the function being called has been marked as [i]RPC[/i]. Calling this method on unsupported functions will result in an error. </description> </method> <method name="unbind" qualifiers="const"> <return type="Callable" /> <param index="0" name="argcount" type="int" /> <description> - Returns a copy of this [Callable] with the arguments unbound. Calling the returned [Callable] will call the method without the extra arguments that are supplied in the [Callable] on which you are calling this method. + Returns a copy of this [Callable] with the arguments unbound, as defined by [param argcount]. Calling the returned [Callable] will call the method without the extra arguments that are supplied in the [Callable] on which you are calling this method. </description> </method> </methods> diff --git a/doc/classes/CanvasGroup.xml b/doc/classes/CanvasGroup.xml index 3bea8cde21..d2bcf3c7ac 100644 --- a/doc/classes/CanvasGroup.xml +++ b/doc/classes/CanvasGroup.xml @@ -1,8 +1,11 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="CanvasGroup" inherits="Node2D" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> + Merges several 2D nodes into a single draw operation. </brief_description> <description> + Child [CanvasItem] nodes of a [CanvasGroup] are drawn as a single object. It allows to e.g. draw overlapping translucent 2D nodes without blending (set [member CanvasItem.self_modulate] property of [CanvasGroup] to achieve this effect). + [b]Note:[/b] Since [CanvasGroup] and [member CanvasItem.clip_children] both utilize the backbuffer, children of a [CanvasGroup] who have their [member CanvasItem.clip_children] set to anything other than [constant CanvasItem.CLIP_CHILDREN_DISABLED] will not function correctly. </description> <tutorials> </tutorials> diff --git a/doc/classes/CanvasItem.xml b/doc/classes/CanvasItem.xml index a2859552a9..499d53e63c 100644 --- a/doc/classes/CanvasItem.xml +++ b/doc/classes/CanvasItem.xml @@ -510,7 +510,7 @@ <method name="move_to_front"> <return type="void" /> <description> - Moves this node to display on top of its siblings. This has more use in [Control], as [Node2D] can be ordered with [member Node2D.z_index]. + Moves this node to display on top of its siblings. Internally, the node is moved to the bottom of parent's children list. The method has no effect on nodes without a parent. </description> </method> @@ -587,6 +587,17 @@ If [code]true[/code], this [CanvasItem] is drawn. The node is only visible if all of its antecedents are visible as well (in other words, [method is_visible_in_tree] must return [code]true[/code]). [b]Note:[/b] For controls that inherit [Popup], the correct way to make them visible is to call one of the multiple [code]popup*()[/code] functions instead. </member> + <member name="y_sort_enabled" type="bool" setter="set_y_sort_enabled" getter="is_y_sort_enabled" default="false"> + If [code]true[/code], child nodes with the lowest Y position are drawn before those with a higher Y position. If [code]false[/code], Y-sorting is disabled. Y-sorting only affects children that inherit from [CanvasItem]. + You can nest nodes with Y-sorting. Child Y-sorted nodes are sorted in the same space as the parent Y-sort. This feature allows you to organize a scene better or divide it into multiple ones without changing your scene tree. + </member> + <member name="z_as_relative" type="bool" setter="set_z_as_relative" getter="is_z_relative" default="true"> + If [code]true[/code], the node's Z index is relative to its parent's Z index. If this node's Z index is 2 and its parent's effective Z index is 3, then this node's effective Z index will be 2 + 3 = 5. + </member> + <member name="z_index" type="int" setter="set_z_index" getter="get_z_index" default="0"> + Z index. Controls the order in which the nodes render. A node with a higher Z index will display in front of others. Must be between [constant RenderingServer.CANVAS_ITEM_Z_MIN] and [constant RenderingServer.CANVAS_ITEM_Z_MAX] (inclusive). + [b]Note:[/b] Changing the Z index of a [Control] only affects the drawing order, not the order in which input events are handled. This can be useful to implement certain UI animations, e.g. a menu where hovered items are scaled and should overlap others. + </member> </members> <signals> <signal name="draw"> @@ -672,12 +683,16 @@ Represents the size of the [enum TextureRepeat] enum. </constant> <constant name="CLIP_CHILDREN_DISABLED" value="0" enum="ClipChildrenMode"> + Child draws over parent and is not clipped. </constant> <constant name="CLIP_CHILDREN_ONLY" value="1" enum="ClipChildrenMode"> + Parent is used for the purposes of clipping only. Child is clipped to the parent's visible area, parent is not drawn. </constant> <constant name="CLIP_CHILDREN_AND_DRAW" value="2" enum="ClipChildrenMode"> + Parent is used for clipping child, but parent is also drawn underneath child as normal before clipping child to its visible area. </constant> <constant name="CLIP_CHILDREN_MAX" value="3" enum="ClipChildrenMode"> + Represents the size of the [enum ClipChildrenMode] enum. </constant> </constants> </class> diff --git a/doc/classes/CharFXTransform.xml b/doc/classes/CharFXTransform.xml index c98b194a4d..a6f707383f 100644 --- a/doc/classes/CharFXTransform.xml +++ b/doc/classes/CharFXTransform.xml @@ -46,6 +46,9 @@ <member name="range" type="Vector2i" setter="set_range" getter="get_range" default="Vector2i(0, 0)"> Absolute character range in the string, corresponding to the glyph. Setting this property won't affect drawing. </member> + <member name="relative_index" type="int" setter="set_relative_index" getter="get_relative_index" default="0"> + The character offset of the glyph, relative to the current [RichTextEffect] custom block. Setting this property won't affect drawing. + </member> <member name="visible" type="bool" setter="set_visibility" getter="is_visible" default="true"> If [code]true[/code], the character will be drawn. If [code]false[/code], the character will be hidden. Characters around hidden characters will reflow to take the space of hidden characters. If this is not desired, set their [member color] to [code]Color(1, 1, 1, 0)[/code] instead. </member> diff --git a/doc/classes/Curve2D.xml b/doc/classes/Curve2D.xml index ccdf085319..b5e75dff68 100644 --- a/doc/classes/Curve2D.xml +++ b/doc/classes/Curve2D.xml @@ -51,7 +51,7 @@ <return type="Vector2" /> <param index="0" name="to_point" type="Vector2" /> <description> - Returns the closest baked point (in curve's local space) to [param to_point]. + Returns the closest point on baked segments (in curve's local space) to [param to_point]. [param to_point] must be in this curve's local space. </description> </method> @@ -94,7 +94,7 @@ </method> <method name="sample_baked" qualifiers="const"> <return type="Vector2" /> - <param index="0" name="offset" type="float" /> + <param index="0" name="offset" type="float" default="0.0" /> <param index="1" name="cubic" type="bool" default="false" /> <description> Returns a point within the curve at position [param offset], where [param offset] is measured as a pixel distance along the curve. @@ -104,13 +104,10 @@ </method> <method name="sample_baked_with_rotation" qualifiers="const"> <return type="Transform2D" /> - <param index="0" name="offset" type="float" /> + <param index="0" name="offset" type="float" default="0.0" /> <param index="1" name="cubic" type="bool" default="false" /> - <param index="2" name="loop" type="bool" default="true" /> - <param index="3" name="lookahead" type="float" default="4.0" /> <description> Similar to [method sample_baked], but returns [Transform2D] that includes a rotation along the curve. Returns empty transform if length of the curve is [code]0[/code]. - Use [param loop] to smooth the tangent at the end of the curve. [param lookahead] defines the distance to a nearby point for calculating the tangent vector. [codeblock] var transform = curve.sample_baked_with_rotation(offset) position = transform.get_origin() @@ -160,6 +157,13 @@ [param tolerance_degrees] controls how many degrees the midpoint of a segment may deviate from the real curve, before the segment has to be subdivided. </description> </method> + <method name="tessellate_even_length" qualifiers="const"> + <return type="PackedVector2Array" /> + <param index="0" name="max_stages" type="int" default="5" /> + <param index="1" name="tolerance_length" type="float" default="20.0" /> + <description> + </description> + </method> </methods> <members> <member name="bake_interval" type="float" setter="set_bake_interval" getter="get_bake_interval" default="5.0"> diff --git a/doc/classes/Curve3D.xml b/doc/classes/Curve3D.xml index 63134417b1..cfe2036499 100644 --- a/doc/classes/Curve3D.xml +++ b/doc/classes/Curve3D.xml @@ -64,7 +64,7 @@ <return type="Vector3" /> <param index="0" name="to_point" type="Vector3" /> <description> - Returns the closest baked point (in curve's local space) to [param to_point]. + Returns the closest point on baked segments (in curve's local space) to [param to_point]. [param to_point] must be in this curve's local space. </description> </method> @@ -114,7 +114,7 @@ </method> <method name="sample_baked" qualifiers="const"> <return type="Vector3" /> - <param index="0" name="offset" type="float" /> + <param index="0" name="offset" type="float" default="0.0" /> <param index="1" name="cubic" type="bool" default="false" /> <description> Returns a point within the curve at position [param offset], where [param offset] is measured as a distance in 3D units along the curve. @@ -134,7 +134,7 @@ </method> <method name="sample_baked_with_rotation" qualifiers="const"> <return type="Transform3D" /> - <param index="0" name="offset" type="float" /> + <param index="0" name="offset" type="float" default="0.0" /> <param index="1" name="cubic" type="bool" default="false" /> <param index="2" name="apply_tilt" type="bool" default="false" /> <description> @@ -192,6 +192,15 @@ [param tolerance_degrees] controls how many degrees the midpoint of a segment may deviate from the real curve, before the segment has to be subdivided. </description> </method> + <method name="tessellate_even_length" qualifiers="const"> + <return type="PackedVector3Array" /> + <param index="0" name="max_stages" type="int" default="5" /> + <param index="1" name="tolerance_length" type="float" default="0.2" /> + <description> + Returns a list of points along the curve, with almost uniform density. [param max_stages] controls how many subdivisions a curve segment may face before it is considered approximate enough. Each subdivision splits the segment in half, so the default 5 stages may mean up to 32 subdivisions per curve segment. Increase with care! + [param tolerance_length] controls the maximal distance between two neighbouring points, before the segment has to be subdivided. + </description> + </method> </methods> <members> <member name="bake_interval" type="float" setter="set_bake_interval" getter="get_bake_interval" default="0.2"> diff --git a/doc/classes/DirectionalLight2D.xml b/doc/classes/DirectionalLight2D.xml index 7a54980c19..f825a9e082 100644 --- a/doc/classes/DirectionalLight2D.xml +++ b/doc/classes/DirectionalLight2D.xml @@ -1,19 +1,20 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="DirectionalLight2D" inherits="Light2D" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - Directional light from a distance. + Directional 2D light from a distance. </brief_description> <description> A directional light is a type of [Light2D] node that models an infinite number of parallel rays covering the entire scene. It is used for lights with strong intensity that are located far away from the scene (for example: to model sunlight or moonlight). </description> <tutorials> + <link title="2D lights and shadows">$DOCS_URL/tutorials/2d/2d_lights_and_shadows.html</link> </tutorials> <members> <member name="height" type="float" setter="set_height" getter="get_height" default="0.0"> The height of the light. Used with 2D normal mapping. Ranges from 0 (parallel to the plane) to 1 (perpendicular to the plane). </member> <member name="max_distance" type="float" setter="set_max_distance" getter="get_max_distance" default="10000.0"> - Maximum distance this light covers. Increasing this value will make directional shadows visible from further away, at the cost of lower overall shadow detail and performance (due to more objects being included in shadow rendering). + The maximum distance from the camera center objects can be before their shadows are culled (in pixels). Decreasing this value can prevent objects located outside the camera from casting shadows (while also improving performance). [member Camera2D.zoom] is not taken into account by [member max_distance], which means that at higher zoom values, shadows will appear to fade out sooner when zooming onto a given point. </member> </members> </class> diff --git a/doc/classes/DisplayServer.xml b/doc/classes/DisplayServer.xml index 0039301bf6..c59bfbfe4f 100644 --- a/doc/classes/DisplayServer.xml +++ b/doc/classes/DisplayServer.xml @@ -1715,6 +1715,7 @@ <constant name="DISPLAY_HANDLE" value="0" enum="HandleType"> Display handle: - Linux (X11): [code]X11::Display*[/code] for the display. + - Android: [code]EGLDisplay[/code] for the display. </constant> <constant name="WINDOW_HANDLE" value="1" enum="HandleType"> Window handle: diff --git a/doc/classes/EditorInspector.xml b/doc/classes/EditorInspector.xml index 0cda49f1bf..ab35a62794 100644 --- a/doc/classes/EditorInspector.xml +++ b/doc/classes/EditorInspector.xml @@ -7,7 +7,7 @@ This is the control that implements property editing in the editor's Settings dialogs, the Inspector dock, etc. To get the [EditorInspector] used in the editor's Inspector dock, use [method EditorInterface.get_inspector]. [EditorInspector] will show properties in the same order as the array returned by [method Object.get_property_list]. If a property's name is path-like (i.e. if it contains forward slashes), [EditorInspector] will create nested sections for "directories" along the path. For example, if a property is named [code]highlighting/gdscript/node_path_color[/code], it will be shown as "Node Path Color" inside the "GDScript" section nested inside the "Highlighting" section. - If a property has [constant PROPERTY_USAGE_GROUP] usage, it will group subsequent properties whose name starts with the property's hint string. The group ends when a property does not start with that hint string or when a new group starts. An empty group name effectively ends the current group. [EditorInspector] will create a top-level section for each group. For example, if a property with group usage is named [code]Collide With[/code] and its hint string is [code]collide_with_[/code], a subsequent [code]collide_with_area[/code] property will be shown as "Area" inside the "Collide With" section. + If a property has [constant PROPERTY_USAGE_GROUP] usage, it will group subsequent properties whose name starts with the property's hint string. The group ends when a property does not start with that hint string or when a new group starts. An empty group name effectively ends the current group. [EditorInspector] will create a top-level section for each group. For example, if a property with group usage is named [code]Collide With[/code] and its hint string is [code]collide_with_[/code], a subsequent [code]collide_with_area[/code] property will be shown as "Area" inside the "Collide With" section. There is also a special case: when the hint string contains the name of a property, that property is grouped too. This is mainly to help grouping properties like [code]font[/code], [code]font_color[/code] and [code]font_size[/code] (using the hint string [code]font_[/code]). If a property has [constant PROPERTY_USAGE_SUBGROUP] usage, a subgroup will be created in the same way as a group, and a second-level section will be created for each subgroup. [b]Note:[/b] Unlike sections created from path-like property names, [EditorInspector] won't capitalize the name for sections created from groups. So properties with group usage usually use capitalized names instead of snake_cased names. </description> diff --git a/doc/classes/EditorPlugin.xml b/doc/classes/EditorPlugin.xml index 806588d100..adcc87d062 100644 --- a/doc/classes/EditorPlugin.xml +++ b/doc/classes/EditorPlugin.xml @@ -719,44 +719,64 @@ </signals> <constants> <constant name="CONTAINER_TOOLBAR" value="0" enum="CustomControlContainer"> + Main editor toolbar, next to play buttons. </constant> <constant name="CONTAINER_SPATIAL_EDITOR_MENU" value="1" enum="CustomControlContainer"> + The toolbar that appears when 3D editor is active. </constant> <constant name="CONTAINER_SPATIAL_EDITOR_SIDE_LEFT" value="2" enum="CustomControlContainer"> + Left sidebar of the 3D editor. </constant> <constant name="CONTAINER_SPATIAL_EDITOR_SIDE_RIGHT" value="3" enum="CustomControlContainer"> + Right sidebar of the 3D editor. </constant> <constant name="CONTAINER_SPATIAL_EDITOR_BOTTOM" value="4" enum="CustomControlContainer"> + Bottom panel of the 3D editor. </constant> <constant name="CONTAINER_CANVAS_EDITOR_MENU" value="5" enum="CustomControlContainer"> + The toolbar that appears when 2D editor is active. </constant> <constant name="CONTAINER_CANVAS_EDITOR_SIDE_LEFT" value="6" enum="CustomControlContainer"> + Left sidebar of the 2D editor. </constant> <constant name="CONTAINER_CANVAS_EDITOR_SIDE_RIGHT" value="7" enum="CustomControlContainer"> + Right sidebar of the 2D editor. </constant> <constant name="CONTAINER_CANVAS_EDITOR_BOTTOM" value="8" enum="CustomControlContainer"> + Bottom panel of the 2D editor. </constant> <constant name="CONTAINER_INSPECTOR_BOTTOM" value="9" enum="CustomControlContainer"> + Bottom section of the inspector. </constant> <constant name="CONTAINER_PROJECT_SETTING_TAB_LEFT" value="10" enum="CustomControlContainer"> + Tab of Project Settings dialog, to the left of other tabs. </constant> <constant name="CONTAINER_PROJECT_SETTING_TAB_RIGHT" value="11" enum="CustomControlContainer"> + Tab of Project Settings dialog, to the right of other tabs. </constant> <constant name="DOCK_SLOT_LEFT_UL" value="0" enum="DockSlot"> + Dock slot, left side, upper-left (empty in default layout). </constant> <constant name="DOCK_SLOT_LEFT_BL" value="1" enum="DockSlot"> + Dock slot, left side, bottom-left (empty in default layout). </constant> <constant name="DOCK_SLOT_LEFT_UR" value="2" enum="DockSlot"> + Dock slot, left side, upper-right (in default layout includes Scene and Import docks). </constant> <constant name="DOCK_SLOT_LEFT_BR" value="3" enum="DockSlot"> + Dock slot, left side, bottom-right (in default layout includes FileSystem dock). </constant> <constant name="DOCK_SLOT_RIGHT_UL" value="4" enum="DockSlot"> + Dock slot, right side, upper-left (empty in default layout). </constant> <constant name="DOCK_SLOT_RIGHT_BL" value="5" enum="DockSlot"> + Dock slot, right side, bottom-left (empty in default layout). </constant> <constant name="DOCK_SLOT_RIGHT_UR" value="6" enum="DockSlot"> + Dock slot, right side, upper-right (in default layout includes Inspector, Node and History docks). </constant> <constant name="DOCK_SLOT_RIGHT_BR" value="7" enum="DockSlot"> + Dock slot, right side, bottom-right (empty in default layout). </constant> <constant name="DOCK_SLOT_MAX" value="8" enum="DockSlot"> Represents the size of the [enum DockSlot] enum. diff --git a/doc/classes/EditorSceneFormatImporter.xml b/doc/classes/EditorSceneFormatImporter.xml index 6de9c2c5dc..db93cab14c 100644 --- a/doc/classes/EditorSceneFormatImporter.xml +++ b/doc/classes/EditorSceneFormatImporter.xml @@ -39,7 +39,6 @@ <param index="0" name="path" type="String" /> <param index="1" name="flags" type="int" /> <param index="2" name="options" type="Dictionary" /> - <param index="3" name="bake_fps" type="int" /> <description> </description> </method> diff --git a/doc/classes/EditorSettings.xml b/doc/classes/EditorSettings.xml index 07457387a0..865faa13ae 100644 --- a/doc/classes/EditorSettings.xml +++ b/doc/classes/EditorSettings.xml @@ -592,6 +592,9 @@ <member name="interface/theme/custom_theme" type="String" setter="" getter=""> The custom theme resource to use for the editor. Must be a Godot theme resource in [code].tres[/code] or [code].res[/code] format. </member> + <member name="interface/theme/draw_extra_borders" type="bool" setter="" getter=""> + If [code]true[/code], draws additional borders around interactive UI elements in the editor. This is automatically enabled when using the [b]Black (OLED)[/b] theme preset, as this theme preset uses a fully black background. + </member> <member name="interface/theme/icon_and_font_color" type="int" setter="" getter=""> The icon and font color scheme to use in the editor. - [b]Auto[/b] determines the color scheme to use automatically based on [member interface/theme/base_color]. diff --git a/doc/classes/FileAccess.xml b/doc/classes/FileAccess.xml index e52f897164..be0c8fd6ca 100644 --- a/doc/classes/FileAccess.xml +++ b/doc/classes/FileAccess.xml @@ -153,6 +153,20 @@ Returns the last error that happened when trying to perform operations. Compare with the [code]ERR_FILE_*[/code] constants from [enum Error]. </description> </method> + <method name="get_file_as_bytes" qualifiers="static"> + <return type="PackedByteArray" /> + <param index="0" name="path" type="String" /> + <description> + Returns the whole [param path] file contents as a [PackedByteArray] without any decoding. + </description> + </method> + <method name="get_file_as_string" qualifiers="static"> + <return type="String" /> + <param index="0" name="path" type="String" /> + <description> + Returns the whole [param path] file contents as a [String]. Text is interpreted as being UTF-8 encoded. + </description> + </method> <method name="get_float" qualifiers="const"> <return type="float" /> <description> diff --git a/doc/classes/Font.xml b/doc/classes/Font.xml index 6a42b62bcf..761e75339a 100644 --- a/doc/classes/Font.xml +++ b/doc/classes/Font.xml @@ -161,6 +161,12 @@ Returns font family name. </description> </method> + <method name="get_font_stretch" qualifiers="const"> + <return type="int" /> + <description> + Returns font stretch amount, compared to a normal width. A percentage value between [code]50%[/code] and [code]200%[/code]. + </description> + </method> <method name="get_font_style" qualifiers="const"> <return type="int" enum="TextServer.FontStyle" /> <description> @@ -173,6 +179,12 @@ Returns font style name. </description> </method> + <method name="get_font_weight" qualifiers="const"> + <return type="int" /> + <description> + Returns weight (boldness) of the font. A value in the [code]100...999[/code] range, normal font weight is [code]400[/code], bold font weight is [code]700[/code]. + </description> + </method> <method name="get_height" qualifiers="const"> <return type="float" /> <param index="0" name="font_size" type="int" default="16" /> diff --git a/doc/classes/FontFile.xml b/doc/classes/FontFile.xml index 271f6a13e0..1019c271dc 100644 --- a/doc/classes/FontFile.xml +++ b/doc/classes/FontFile.xml @@ -542,6 +542,9 @@ </method> </methods> <members> + <member name="allow_system_fallback" type="bool" setter="set_allow_system_fallback" getter="is_allow_system_fallback" default="true"> + If set to [code]true[/code], system fonts can be automatically used as fallbacks. + </member> <member name="antialiasing" type="int" setter="set_antialiasing" getter="get_antialiasing" enum="TextServer.FontAntialiasing" default="1"> Font anti-aliasing mode. </member> @@ -557,9 +560,15 @@ <member name="font_name" type="String" setter="set_font_name" getter="get_font_name" default=""""> Font family name. </member> + <member name="font_stretch" type="int" setter="set_font_stretch" getter="get_font_stretch" default="100"> + Font stretch amount, compared to a normal width. A percentage value between [code]50%[/code] and [code]200%[/code]. + </member> <member name="font_style" type="int" setter="set_font_style" getter="get_font_style" enum="TextServer.FontStyle" default="0"> Font style flags, see [enum TextServer.FontStyle]. </member> + <member name="font_weight" type="int" setter="set_font_weight" getter="get_font_weight" default="400"> + Weight (boldness) of the font. A value in the [code]100...999[/code] range, normal font weight is [code]400[/code], bold font weight is [code]700[/code]. + </member> <member name="force_autohinter" type="bool" setter="set_force_autohinter" getter="is_force_autohinter" default="false"> If set to [code]true[/code], auto-hinting is supported and preferred over font built-in hinting. Used by dynamic fonts only. </member> diff --git a/doc/classes/GraphEdit.xml b/doc/classes/GraphEdit.xml index 5050ce7715..ea4e4b53ba 100644 --- a/doc/classes/GraphEdit.xml +++ b/doc/classes/GraphEdit.xml @@ -291,7 +291,7 @@ </description> </signal> <signal name="connection_drag_started"> - <param index="0" name="from_node" type="String" /> + <param index="0" name="from_node" type="StringName" /> <param index="1" name="from_port" type="int" /> <param index="2" name="is_output" type="bool" /> <description> diff --git a/doc/classes/HSlider.xml b/doc/classes/HSlider.xml index cb0a8b34db..19bb26a1b0 100644 --- a/doc/classes/HSlider.xml +++ b/doc/classes/HSlider.xml @@ -29,6 +29,7 @@ The background of the area to the left of the grabber. </theme_item> <theme_item name="grabber_area_highlight" data_type="style" type="StyleBox"> + The background of the area to the left of the grabber that displays when it's being hovered or focused. </theme_item> <theme_item name="slider" data_type="style" type="StyleBox"> The background for the whole slider. Determines the height of the [code]grabber_area[/code]. diff --git a/doc/classes/Label.xml b/doc/classes/Label.xml index 615aceac53..cd87b4558f 100644 --- a/doc/classes/Label.xml +++ b/doc/classes/Label.xml @@ -50,6 +50,7 @@ Controls the text's horizontal alignment. Supports left, center, right, and fill, or justify. Set it to one of the [enum HorizontalAlignment] constants. </member> <member name="label_settings" type="LabelSettings" setter="set_label_settings" getter="get_label_settings"> + A [LabelSettings] resource that can be shared between multiple [Label] nodes. Takes priority over theme properties. </member> <member name="language" type="String" setter="set_language" getter="get_language" default=""""> Language code used for line-breaking and text shaping algorithms, if left empty current locale is used instead. @@ -100,7 +101,7 @@ Default text [Color] of the [Label]. </theme_item> <theme_item name="font_outline_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)"> - The tint of text outline. + The color of text outline. </theme_item> <theme_item name="font_shadow_color" data_type="color" type="Color" default="Color(0, 0, 0, 0)"> [Color] of the text's shadow effect. diff --git a/doc/classes/LabelSettings.xml b/doc/classes/LabelSettings.xml index aa972f2cf3..d73cb78295 100644 --- a/doc/classes/LabelSettings.xml +++ b/doc/classes/LabelSettings.xml @@ -1,29 +1,40 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="LabelSettings" inherits="Resource" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> + Collection of common settings to customize label text. </brief_description> <description> + [LabelSettings] is a resource that can be assigned to a [Label] node to customize it. It will take priority over the properties defined in theme. The resource can be shared between multiple labels and swapped on the fly, so it's convenient and flexible way to setup text style. </description> <tutorials> </tutorials> <members> <member name="font" type="Font" setter="set_font" getter="get_font"> + [Font] used for the text. </member> <member name="font_color" type="Color" setter="set_font_color" getter="get_font_color" default="Color(1, 1, 1, 1)"> + Color of the text. </member> <member name="font_size" type="int" setter="set_font_size" getter="get_font_size" default="16"> + Size of the text. </member> <member name="line_spacing" type="float" setter="set_line_spacing" getter="get_line_spacing" default="3.0"> + Vertical space between lines when the text is multiline. </member> <member name="outline_color" type="Color" setter="set_outline_color" getter="get_outline_color" default="Color(1, 1, 1, 1)"> + The color of the outline. </member> <member name="outline_size" type="int" setter="set_outline_size" getter="get_outline_size" default="0"> + Text outline size. </member> <member name="shadow_color" type="Color" setter="set_shadow_color" getter="get_shadow_color" default="Color(0, 0, 0, 0)"> + Color of the shadow effect. If alpha is [code]0[/code], no shadow will be drawn. </member> <member name="shadow_offset" type="Vector2" setter="set_shadow_offset" getter="get_shadow_offset" default="Vector2(1, 1)"> + Offset of the shadow effect, in pixels. </member> <member name="shadow_size" type="int" setter="set_shadow_size" getter="get_shadow_size" default="1"> + Size of the shadow effect. </member> </members> </class> diff --git a/doc/classes/Light2D.xml b/doc/classes/Light2D.xml index 00815758a1..062d532464 100644 --- a/doc/classes/Light2D.xml +++ b/doc/classes/Light2D.xml @@ -4,8 +4,7 @@ Casts light in a 2D environment. </brief_description> <description> - Casts light in a 2D environment. Light is defined by a (usually grayscale) texture, a color, an energy value, a mode (see constants), and various other parameters (range and shadows-related). - [b]Note:[/b] Light2D can also be used as a mask. + Casts light in a 2D environment. A light is defined as a color, an energy value, a mode (see constants), and various other parameters (range and shadows-related). </description> <tutorials> <link title="2D lights and shadows">$DOCS_URL/tutorials/2d/2d_lights_and_shadows.html</link> @@ -14,12 +13,14 @@ <method name="get_height" qualifiers="const"> <return type="float" /> <description> + Returns the light's height, which is used in 2D normal mapping. See [member PointLight2D.height] and [member DirectionalLight2D.height]. </description> </method> <method name="set_height"> <return type="void" /> <param index="0" name="height" type="float" /> <description> + Sets the light's height, which is used in 2D normal mapping. See [member PointLight2D.height] and [member DirectionalLight2D.height]. </description> </method> </methods> @@ -64,7 +65,7 @@ Shadow filter type. See [enum ShadowFilter] for possible values. </member> <member name="shadow_filter_smooth" type="float" setter="set_shadow_smooth" getter="get_shadow_smooth" default="0.0"> - Smoothing value for shadows. + Smoothing value for shadows. Higher values will result in softer shadows, at the cost of visible streaks that can appear in shadow rendering. [member shadow_filter_smooth] only has an effect if [member shadow_filter] is [constant SHADOW_FILTER_PCF5] or [constant SHADOW_FILTER_PCF13]. </member> <member name="shadow_item_cull_mask" type="int" setter="set_item_shadow_cull_mask" getter="get_item_shadow_cull_mask" default="1"> The shadow mask. Used with [LightOccluder2D] to cast shadows. Only occluders with a matching light mask will cast shadows. @@ -72,13 +73,13 @@ </members> <constants> <constant name="SHADOW_FILTER_NONE" value="0" enum="ShadowFilter"> - No filter applies to the shadow map. See [member shadow_filter]. + No filter applies to the shadow map. This provides hard shadow edges and is the fastest to render. See [member shadow_filter]. </constant> <constant name="SHADOW_FILTER_PCF5" value="1" enum="ShadowFilter"> - Percentage closer filtering (5 samples) applies to the shadow map. See [member shadow_filter]. + Percentage closer filtering (5 samples) applies to the shadow map. This is slower compared to hard shadow rendering. See [member shadow_filter]. </constant> <constant name="SHADOW_FILTER_PCF13" value="2" enum="ShadowFilter"> - Percentage closer filtering (13 samples) applies to the shadow map. See [member shadow_filter]. + Percentage closer filtering (13 samples) applies to the shadow map. This is the slowest shadow filtereing mode, and should be used sparingly. See [member shadow_filter]. </constant> <constant name="BLEND_MODE_ADD" value="0" enum="BlendMode"> Adds the value of pixels corresponding to the Light2D to the values of pixels under it. This is the common behavior of a light. diff --git a/doc/classes/Mesh.xml b/doc/classes/Mesh.xml index 640fa9efec..4d3fb7ed5c 100644 --- a/doc/classes/Mesh.xml +++ b/doc/classes/Mesh.xml @@ -97,7 +97,7 @@ </description> </method> <method name="create_convex_shape" qualifiers="const"> - <return type="Shape3D" /> + <return type="ConvexPolygonShape3D" /> <param index="0" name="clean" type="bool" default="true" /> <param index="1" name="simplify" type="bool" default="false" /> <description> @@ -115,7 +115,7 @@ </description> </method> <method name="create_trimesh_shape" qualifiers="const"> - <return type="Shape3D" /> + <return type="ConcavePolygonShape3D" /> <description> Calculate a [ConcavePolygonShape3D] from the mesh. </description> diff --git a/doc/classes/Node.xml b/doc/classes/Node.xml index 21fb9d139c..24df5977f9 100644 --- a/doc/classes/Node.xml +++ b/doc/classes/Node.xml @@ -384,8 +384,11 @@ <method name="get_path_to" qualifiers="const"> <return type="NodePath" /> <param index="0" name="node" type="Node" /> + <param index="1" name="use_unique_path" type="bool" default="false" /> <description> Returns the relative [NodePath] from this node to the specified [param node]. Both nodes must be in the same scene or the function will fail. + If [param use_unique_path] is [code]true[/code], returns the shortest path considering unique node. + [b]Note:[/b] If you get a relative path which starts from a unique node, the path may be longer than a normal relative path due to the addition of the unique node's name. </description> </method> <method name="get_physics_process_delta_time" qualifiers="const"> @@ -535,7 +538,7 @@ [b]Note:[/b] Internal children can only be moved within their expected "internal range" (see [code]internal[/code] parameter in [method add_child]). </description> </method> - <method name="print_orphan_nodes"> + <method name="print_orphan_nodes" qualifiers="static"> <return type="void" /> <description> Prints all orphan nodes (nodes outside the [SceneTree]). Used for debugging. diff --git a/doc/classes/Node2D.xml b/doc/classes/Node2D.xml index 054ab532af..26efe37dce 100644 --- a/doc/classes/Node2D.xml +++ b/doc/classes/Node2D.xml @@ -125,15 +125,5 @@ <member name="transform" type="Transform2D" setter="set_transform" getter="get_transform"> Local [Transform2D]. </member> - <member name="y_sort_enabled" type="bool" setter="set_y_sort_enabled" getter="is_y_sort_enabled" default="false"> - If [code]true[/code], child nodes with the lowest Y position are drawn before those with a higher Y position. If [code]false[/code], Y-sorting is disabled. Y-sorting only affects children that inherit from [CanvasItem]. - You can nest nodes with Y-sorting. Child Y-sorted nodes are sorted in the same space as the parent Y-sort. This feature allows you to organize a scene better or divide it into multiple ones without changing your scene tree. - </member> - <member name="z_as_relative" type="bool" setter="set_z_as_relative" getter="is_z_relative" default="true"> - If [code]true[/code], the node's Z index is relative to its parent's Z index. If this node's Z index is 2 and its parent's effective Z index is 3, then this node's effective Z index will be 2 + 3 = 5. - </member> - <member name="z_index" type="int" setter="set_z_index" getter="get_z_index" default="0"> - Z index. Controls the order in which the nodes render. A node with a higher Z index will display in front of others. Must be between [constant RenderingServer.CANVAS_ITEM_Z_MIN] and [constant RenderingServer.CANVAS_ITEM_Z_MAX] (inclusive). - </member> </members> </class> diff --git a/doc/classes/NodePath.xml b/doc/classes/NodePath.xml index 022b4826ea..c82ed5f143 100644 --- a/doc/classes/NodePath.xml +++ b/doc/classes/NodePath.xml @@ -187,12 +187,14 @@ <return type="bool" /> <param index="0" name="right" type="NodePath" /> <description> + Returns [code]true[/code] if two node paths are not equal. </description> </operator> <operator name="operator =="> <return type="bool" /> <param index="0" name="right" type="NodePath" /> <description> + Returns [code]true[/code] if two node paths are equal, i.e. all node names in the path are the same and in the same order. </description> </operator> </operators> diff --git a/doc/classes/OS.xml b/doc/classes/OS.xml index ea9b83d2aa..0efc6ab399 100644 --- a/doc/classes/OS.xml +++ b/doc/classes/OS.xml @@ -182,10 +182,12 @@ <method name="get_cmdline_user_args"> <return type="PackedStringArray" /> <description> - Similar to [method get_cmdline_args], but this returns the user arguments (any argument passed after the double dash [code]--[/code] argument). These are left untouched by Godot for the user. + Similar to [method get_cmdline_args], but this returns the user arguments (any argument passed after the double dash [code]--[/code] or double plus [code]++[/code] argument). These are left untouched by Godot for the user. [code]++[/code] can be used in situations where [code]--[/code] is intercepted by another program (such as [code]startx[/code]). For example, in the command line below, [code]--fullscreen[/code] will not be returned in [method get_cmdline_user_args] and [code]--level 1[/code] will only be returned in [method get_cmdline_user_args]: [codeblock] godot --fullscreen -- --level 1 + # Or: + godot --fullscreen ++ --level 1 [/codeblock] </description> </method> @@ -392,18 +394,38 @@ <method name="get_system_font_path" qualifiers="const"> <return type="String" /> <param index="0" name="font_name" type="String" /> - <param index="1" name="bold" type="bool" default="false" /> - <param index="2" name="italic" type="bool" default="false" /> + <param index="1" name="weight" type="int" default="400" /> + <param index="2" name="stretch" type="int" default="100" /> + <param index="3" name="italic" type="bool" default="false" /> <description> - Returns path to the system font file with [param font_name] and style. Return empty string if no matching fonts found. - [b]Note:[/b] This method is implemented on iOS, Linux, macOS and Windows. + Returns path to the system font file with [param font_name] and style. Returns empty string if no matching fonts found. + The following aliases can be used to request default fonts: "sans-serif", "serif", "monospace", "cursive", and "fantasy". + [b]Note:[/b] Returned font might have different style if the requested style is not available. + [b]Note:[/b] This method is implemented on Android, iOS, Linux, macOS and Windows. + </description> + </method> + <method name="get_system_font_path_for_text" qualifiers="const"> + <return type="PackedStringArray" /> + <param index="0" name="font_name" type="String" /> + <param index="1" name="text" type="String" /> + <param index="2" name="locale" type="String" default="""" /> + <param index="3" name="script" type="String" default="""" /> + <param index="4" name="weight" type="int" default="400" /> + <param index="5" name="stretch" type="int" default="100" /> + <param index="6" name="italic" type="bool" default="false" /> + <description> + Returns an array of the system substitute font file paths, which are similar to the font with [param font_name] and style for the specified text, locale and script. Returns empty array if no matching fonts found. + The following aliases can be used to request default fonts: "sans-serif", "serif", "monospace", "cursive", and "fantasy". + [b]Note:[/b] Depending on OS, it's not guaranteed that any of the returned fonts is suitable for rendering specified text. Fonts should be loaded and checked in the order they are returned, and the first suitable one used. + [b]Note:[/b] Returned fonts might have different style if the requested style is not available or belong to a different font family. + [b]Note:[/b] This method is implemented on Android, iOS, Linux, macOS and Windows. </description> </method> <method name="get_system_fonts" qualifiers="const"> <return type="PackedStringArray" /> <description> Returns list of font family names available. - [b]Note:[/b] This method is implemented on iOS, Linux, macOS and Windows. + [b]Note:[/b] This method is implemented on Android, iOS, Linux, macOS and Windows. </description> </method> <method name="get_thread_caller_id" qualifiers="const"> diff --git a/doc/classes/Object.xml b/doc/classes/Object.xml index 318f2cfade..5e834b3d91 100644 --- a/doc/classes/Object.xml +++ b/doc/classes/Object.xml @@ -1,33 +1,27 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="Object" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - Base class for all non-built-in types. + Base class for all other classes in the engine. </brief_description> <description> - Every class which is not a built-in type inherits from this class. - You can construct Objects from scripting languages, using [code]Object.new()[/code] in GDScript, or [code]new Object[/code] in C#. - Objects do not manage memory. If a class inherits from Object, you will have to delete instances of it manually. To do so, call the [method free] method from your script or delete the instance from C++. - Some classes that extend Object add memory management. This is the case of [RefCounted], which counts references and deletes itself automatically when no longer referenced. [Node], another fundamental type, deletes all its children when freed from memory. - Objects export properties, which are mainly useful for storage and editing, but not really so much in programming. Properties are exported in [method _get_property_list] and handled in [method _get] and [method _set]. However, scripting languages and C++ have simpler means to export them. - Property membership can be tested directly in GDScript using [code]in[/code]: - [codeblocks] - [gdscript] - var n = Node2D.new() - print("position" in n) # Prints "true". - print("other_property" in n) # Prints "false". - [/gdscript] - [csharp] - var node = new Node2D(); - // C# has no direct equivalent to GDScript's `in` operator here, but we - // can achieve the same behavior by performing `Get` with a null check. - GD.Print(node.Get("position") != null); // Prints "true". - GD.Print(node.Get("other_property") != null); // Prints "false". - [/csharp] - [/codeblocks] - The [code]in[/code] operator will evaluate to [code]true[/code] as long as the key exists, even if the value is [code]null[/code]. - Objects also receive notifications. Notifications are a simple way to notify the object about different events, so they can all be handled together. See [method _notification]. - [b]Note:[/b] Unlike references to a [RefCounted], references to an Object stored in a variable can become invalid without warning. Therefore, it's recommended to use [RefCounted] for data classes instead of [Object]. - [b]Note:[/b] The [code]script[/code] property is not exposed like most properties, but it does have a setter and getter ([code]set_script()[/code] and [code]get_script()[/code]). + An advanced [Variant] type. All classes in the engine inherit from Object. Each class may define new properties, methods or signals, which are available to all inheriting classes. For example, a [Sprite2D] instance is able to call [method Node.add_child] because it inherits from [Node]. + You can create new instances, using [code]Object.new()[/code] in GDScript, or [code]new Object[/code] in C#. + To delete an Object instance, call [method free]. This is necessary for most classes inheriting Object, because they do not manage memory on their own, and will otherwise cause memory leaks when no longer in use. There are a few classes that perform memory management. For example, [RefCounted] (and by extension [Resource]) deletes itself when no longer referenced, and [Node] deletes its children when freed. + Objects can have a [Script] attached to them. Once the [Script] is instantiated, it effectively acts as an extension to the base class, allowing it to define and inherit new properties, methods and signals. + Inside a [Script], [method _get_property_list] may be overriden to customize properties in several ways. This allows them to be available to the editor, display as lists of options, sub-divide into groups, save on disk, etc. Scripting languages offer easier ways to customize properties, such as with the [annotation @GDScript.@export] annotation. + Godot is very dynamic. An object's script, and therefore its properties, methods and signals, can be changed at run-time. Because of this, there can be occasions where, for example, a property required by a method may not exist. To prevent run-time errors, see methods such as [method set], [method get], [method call], [method has_method], [method has_signal], etc. Note that these methods are [b]much[/b] slower than direct references. + In GDScript, you can also check if a given property, method, or signal name exists in an object with the [code]in[/code] operator: + [codeblock] + var node = Node.new() + print("name" in node) # Prints true + print("get_parent" in node) # Prints true + print("tree_entered" in node) # Prints true + print("unknown" in node) # Prints false + [/codeblock] + Notifications are [int] constants commonly sent and received by objects. For example, on every rendered frame, the [SceneTree] notifies nodes inside the tree with a [constant Node.NOTIFICATION_PROCESS]. The nodes receive it and may call [method Node._process] to update. To make use of notifications, see [method notification] and [method _notification]. + Lastly, every object can also contain metadata (data about data). [method set_meta] can be useful to store information that the object itself does not depend on. To keep your code clean, making excessive use of metadata is discouraged. + [b]Note:[/b] Unlike references to a [RefCounted], references to an object stored in a variable can become invalid without being set to [code]null[/code]. To check if an object has been deleted, do [i]not[/i] compare it against [code]null[/code]. Instead, use [method @GlobalScope.is_instance_valid]. It's also recommended to inherit from [RefCounted] for classes storing data instead of [Object]. + [b]Note:[/b] The [code]script[/code] is not exposed like most properties. To set or get an object's [Script] in code, use [method set_script] and [method get_script], respectively. </description> <tutorials> <link title="When and how to avoid using nodes for everything">$DOCS_URL/tutorials/best_practices/node_alternatives.html</link> @@ -38,46 +32,174 @@ <return type="Variant" /> <param index="0" name="property" type="StringName" /> <description> - Virtual method which can be overridden to customize the return value of [method get]. - Returns the given property. Returns [code]null[/code] if the [param property] does not exist. + Override this method to customize the behavior of [method get]. Should return the given [param property]'s value, or [code]null[/code] if the [param property] should be handled normally. + Combined with [method _set] and [method _get_property_list], this method allows defining custom properties, which is particularly useful for editor plugins. Note that a property must be present in [method get_property_list], otherwise this method will not be called. + [codeblocks] + [gdscript] + func _get(property): + if (property == "fake_property"): + print("Getting my property!") + return 4 + + func _get_property_list(): + return [ + { "name": "fake_property", "type": TYPE_INT } + ] + [/gdscript] + [csharp] + public override Variant _Get(StringName property) + { + if (property == "FakeProperty") + { + GD.Print("Getting my property!"); + return 4; + } + return default; + } + + public override Godot.Collections.Array<Godot.Collections.Dictionary> _GetPropertyList() + { + return new Godot.Collections.Array<Godot.Collections.Dictionary>() + { + new Godot.Collections.Dictionary() + { + { "name", "FakeProperty" }, + { "type", (int)Variant.Type.Int } + } + }; + } + [/csharp] + [/codeblocks] </description> </method> <method name="_get_property_list" qualifiers="virtual"> <return type="Dictionary[]" /> <description> - Virtual method which can be overridden to customize the return value of [method get_property_list]. - Returns the object's property list as an [Array] of dictionaries. - Each property's [Dictionary] must contain at least [code]name: String[/code] and [code]type: int[/code] (see [enum Variant.Type]) entries. Optionally, it can also include [code]hint: int[/code] (see [enum PropertyHint]), [code]hint_string: String[/code], and [code]usage: int[/code] (see [enum PropertyUsageFlags]). + Override this method to customize how script properties should be handled by the engine. + Should return a property list, as an [Array] of dictionaries. The result is added to the array of [method get_property_list], and should be formatted in the same way. Each [Dictionary] must at least contain the [code]name[/code] and [code]type[/code] entries. + The example below displays [code]hammer_type[/code] in the Inspector dock, only if [code]holding_hammer[/code] is [code]true[/code]: + [codeblocks] + [gdscript] + @tool + extends Node2D + + @export var holding_hammer = false: + set(value): + holding_hammer = value + notify_property_list_changed() + var hammer_type = 0 + + func _get_property_list(): + # By default, `hammer_type` is not visible in the editor. + var property_usage = PROPERTY_USAGE_NO_EDITOR + + if holding_hammer: + property_usage = PROPERTY_USAGE_DEFAULT + + var properties = [] + properties.append({ + "name": "hammer_type", + "type": TYPE_INT, + "usage": property_usage, # See above assignment. + "hint": PROPERTY_HINT_ENUM, + "hint_string": "Wooden,Iron,Golden,Enchanted" + }) + + return properties + [/gdscript] + [csharp] + [Tool] + public class MyNode2D : Node2D + { + private bool _holdingHammer; + + [Export] + public bool HoldingHammer + { + get => _holdingHammer; + set + { + _holdingHammer = value; + NotifyPropertyListChanged(); + } + } + + public int HammerType { get; set; } + + public override Godot.Collections.Array<Godot.Collections.Dictionary> _GetPropertyList() + { + // By default, `HammerType` is not visible in the editor. + var propertyUsage = PropertyUsageFlags.NoEditor; + + if (HoldingHammer) + { + propertyUsage = PropertyUsageFlags.Default; + } + + var properties = new Godot.Collections.Array<Godot.Collections.Dictionary>(); + properties.Add(new Godot.Collections.Dictionary() + { + { "name", "HammerType" }, + { "type", (int)Variant.Type.Int }, + { "usage", (int)propertyUsage }, // See above assignment. + { "hint", (int)PropertyHint.Enum }, + { "hint_string", "Wooden,Iron,Golden,Enchanted" } + }); + + return properties; + } + } + [/csharp] + [/codeblocks] + [b]Note:[/b] This method is intended for advanced purposes. For most common use cases, the scripting languages offer easier ways to handle properties. See [annotation @GDScript.@export], [annotation @GDScript.@export_enum], [annotation @GDScript.@export_group], etc. + [b]Note:[/b] If the object's script is not [annotation @GDScript.@tool], this method will not be called in the editor. </description> </method> <method name="_init" qualifiers="virtual"> <return type="void" /> <description> - Called when the object is initialized in memory. Can be defined to take in parameters, that are passed in when constructing. - [b]Note:[/b] If [method _init] is defined with required parameters, then explicit construction is the only valid means of creating an Object of the class. If any other means (such as [method PackedScene.instantiate]) is used, then initialization will fail. + Called when the object's script is instantiated, oftentimes after the object is initialized in memory (through [code]Object.new()[/code] in GDScript, or [code]new Object[/code] in C#). It can be also defined to take in parameters. This method is similar to a constructor in most programming languages. + [b]Note:[/b] If [method _init] is defined with [i]required[/i] parameters, the Object with script may only be created directly. If any other means (such as [method PackedScene.instantiate] or [method Node.duplicate]) are used, the script's initialization will fail. </description> </method> <method name="_notification" qualifiers="virtual"> <return type="void" /> <param index="0" name="what" type="int" /> <description> - Called whenever the object receives a notification, which is identified in [param what] by a constant. The base [Object] has two constants [constant NOTIFICATION_POSTINITIALIZE] and [constant NOTIFICATION_PREDELETE], but subclasses such as [Node] define a lot more notifications which are also received by this method. + Called when the object receives a notification, which can be identified in [param what] by comparing it with a constant. See also [method notification]. + [codeblocks] + [gdscript] + func _notification(what): + if what == NOTIFICATION_PREDELETE: + print("Goodbye!") + [/gdscript] + [csharp] + public override void _Notification(long what) + { + if (what == NotificationPredelete) + { + GD.Print("Goodbye!"); + } + } + [/csharp] + [/codeblocks] + [b]Note:[/b] The base [Object] defines a few notifications ([constant NOTIFICATION_POSTINITIALIZE] and [constant NOTIFICATION_PREDELETE]). Inheriting classes such as [Node] define a lot more notifications, which are also received by this method. </description> </method> <method name="_property_can_revert" qualifiers="virtual"> <return type="bool" /> <param index="0" name="property" type="StringName" /> <description> - Virtual methods that can be overridden to customize the property revert behavior in the editor. - Returns [code]true[/code] if the property identified by [code]name[/code] can be reverted to a default value. Override [method _property_get_revert] to return the actual value. + Override this method to customize the given [param property]'s revert behavior. Should return [code]true[/code] if the [param property] can be reverted in the Inspector dock. Use [method _property_get_revert] to specify the [param property]'s default value. + [b]Note:[/b] This method must return consistently, regardless of the current value of the [param property]. </description> </method> <method name="_property_get_revert" qualifiers="virtual"> <return type="Variant" /> <param index="0" name="property" type="StringName" /> <description> - Virtual methods that can be overridden to customize the property revert behavior in the editor. - Returns the default value of the property identified by [code]name[/code]. [method _property_can_revert] must be overridden as well for this method to be called. + Override this method to customize the given [param property]'s revert behavior. Should return the default value for the [param property]. If the default value differs from the [param property]'s current value, a revert icon is displayed in the Inspector dock. + [b]Note:[/b] [method _property_can_revert] must also be overridden for this method to be called. </description> </method> <method name="_set" qualifiers="virtual"> @@ -85,15 +207,58 @@ <param index="0" name="property" type="StringName" /> <param index="1" name="value" type="Variant" /> <description> - Virtual method which can be overridden to customize the return value of [method set]. - Sets a property. Returns [code]true[/code] if the [param property] exists. + Override this method to customize the behavior of [method set]. Should set the [param property] to [param value] and return [code]true[/code], or [code]false[/code] if the [param property] should be handled normally. The [i]exact[/i] way to set the [param property] is up to this method's implementation. + Combined with [method _get] and [method _get_property_list], this method allows defining custom properties, which is particularly useful for editor plugins. Note that a property [i]must[/i] be present in [method get_property_list], otherwise this method will not be called. + [codeblocks] + [gdscript] + func _set(property, value): + if (property == "fake_property"): + print("Setting my property to ", value) + + func _get_property_list(): + return [ + { "name": "fake_property", "type": TYPE_INT } + ] + [/gdscript] + [csharp] + public override void _Set(StringName property, Variant value) + { + if (property == "FakeProperty") + { + GD.Print($"Setting my property to {value}"); + return true; + } + + return false; + } + + public override Godot.Collections.Array<Godot.Collections.Dictionary> _GetPropertyList() + { + return new Godot.Collections.Array<Godot.Collections.Dictionary>() + { + new Godot.Collections.Dictionary() + { + { "name", "FakeProperty" }, + { "type", (int)Variant.Type.Int } + } + }; + } + [/csharp] + [/codeblocks] </description> </method> <method name="_to_string" qualifiers="virtual"> <return type="String" /> <description> - Virtual method which can be overridden to customize the return value of [method to_string], and thus the object's representation where it is converted to a string, e.g. with [code]print(obj)[/code]. - Returns a [String] representing the object. If not overridden, defaults to [code]"[ClassName:RID]"[/code]. + Override this method to customize the return value of [method to_string], and therefore the object's representation as a [String]. + [codeblock] + func _to_string(): + return "Welcome to Godot 4!" + + func _init(): + print(self) # Prints Welcome to Godot 4!" + var a = str(self) # a is "Welcome to Godot 4!" + [/codeblock] </description> </method> <method name="add_user_signal"> @@ -101,15 +266,37 @@ <param index="0" name="signal" type="String" /> <param index="1" name="arguments" type="Array" default="[]" /> <description> - Adds a user-defined [param signal]. Arguments are optional, but can be added as an [Array] of dictionaries, each containing [code]name: String[/code] and [code]type: int[/code] (see [enum Variant.Type]) entries. + Adds a user-defined [param signal]. Optional arguments for the signal can be added as an [Array] of dictionaries, each defining a [code]name[/code] [String] and a [code]type[/code] [int] (see [enum Variant.Type]). See also [method has_user_signal]. + [codeblocks] + [gdscript] + add_user_signal("hurt", [ + { "name": "damage", "type": TYPE_INT }, + { "name": "source", "type": TYPE_OBJECT } + ]) + [/gdscript] + [csharp] + AddUserSignal("Hurt", new Godot.Collections.Array() + { + new Godot.Collections.Dictionary() + { + { "name", "damage" }, + { "type", (int)Variant.Type.Int } + }, + new Godot.Collections.Dictionary() + { + { "name", "source" }, + { "type", (int)Variant.Type.Object } + } + }); + [/csharp] + [/codeblocks] </description> </method> <method name="call" qualifiers="vararg"> <return type="Variant" /> <param index="0" name="method" type="StringName" /> <description> - Calls the [param method] on the object and returns the result. This method supports a variable number of arguments, so parameters are passed as a comma separated list. - [b]Example:[/b] + Calls the [param method] on the object and returns the result. This method supports a variable number of arguments, so parameters can be passed as a comma separated list. [codeblocks] [gdscript] var node = Node3D.new() @@ -120,15 +307,14 @@ node.Call("rotate", new Vector3(1f, 0f, 0f), 1.571f); [/csharp] [/codeblocks] - [b]Note:[/b] In C#, the method name must be specified as snake_case if it is defined by a built-in Godot node. This doesn't apply to user-defined methods where you should use the same convention as in the C# source (typically PascalCase). + [b]Note:[/b] In C#, [param method] must be in snake_case when referring to built-in Godot methods. Prefer using the names exposed in the [code]MethodName[/code] class to avoid allocating a new [StringName] on each call. </description> </method> <method name="call_deferred" qualifiers="vararg"> <return type="Variant" /> <param index="0" name="method" type="StringName" /> <description> - Calls the [param method] on the object during idle time. This method supports a variable number of arguments, so parameters are passed as a comma separated list. - [b]Example:[/b] + Calls the [param method] on the object during idle time. This method supports a variable number of arguments, so parameters can be passed as a comma separated list. [codeblocks] [gdscript] var node = Node3D.new() @@ -139,7 +325,7 @@ node.CallDeferred("rotate", new Vector3(1f, 0f, 0f), 1.571f); [/csharp] [/codeblocks] - [b]Note:[/b] In C#, the method name must be specified as snake_case if it is defined by a built-in Godot node. This doesn't apply to user-defined methods where you should use the same convention as in the C# source (typically PascalCase). + [b]Note:[/b] In C#, [param method] must be in snake_case when referring to built-in Godot methods. Prefer using the names exposed in the [code]MethodName[/code] class to avoid allocating a new [StringName] on each call. </description> </method> <method name="callv"> @@ -147,7 +333,7 @@ <param index="0" name="method" type="StringName" /> <param index="1" name="arg_array" type="Array" /> <description> - Calls the [param method] on the object and returns the result. Contrarily to [method call], this method does not support a variable number of arguments but expects all parameters to be via a single [Array]. + Calls the [param method] on the object and returns the result. Unlike [method call], this method expects all parameters to be contained inside [param arg_array]. [codeblocks] [gdscript] var node = Node3D.new() @@ -158,12 +344,13 @@ node.Callv("rotate", new Godot.Collections.Array { new Vector3(1f, 0f, 0f), 1.571f }); [/csharp] [/codeblocks] + [b]Note:[/b] In C#, [param method] must be in snake_case when referring to built-in Godot methods. Prefer using the names exposed in the [code]MethodName[/code] class to avoid allocating a new [StringName] on each call </description> </method> <method name="can_translate_messages" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if the object can translate strings. See [method set_message_translation] and [method tr]. + Returns [code]true[/code] if the object is allowed to translate messages with [method tr] and [method tr_n]. See also [method set_message_translation]. </description> </method> <method name="connect"> @@ -172,23 +359,23 @@ <param index="1" name="callable" type="Callable" /> <param index="2" name="flags" type="int" default="0" /> <description> - Connects a [param signal] to a [param callable]. Use [param flags] to set deferred or one-shot connections. See [enum ConnectFlags] constants. - A signal can only be connected once to a [Callable]. It will print an error if already connected, unless the signal was connected with [constant CONNECT_REFERENCE_COUNTED]. To avoid this, first, use [method is_connected] to check for existing connections. - If the callable's target is destroyed in the game's lifecycle, the connection will be lost. + Connects a [param signal] by name to a [param callable]. Optional [param flags] can be also added to configure the connection's behavior (see [enum ConnectFlags] constants). + A signal can only be connected once to the same [Callable]. If the signal is already connected, this method returns [constant ERR_INVALID_PARAMETER] and pushes an error message, unless the signal is connected with [constant CONNECT_REFERENCE_COUNTED]. To prevent this, use [method is_connected] first to check for existing connections. + If the [param callable]'s object is freed, the connection will be lost. [b]Examples with recommended syntax:[/b] - Connecting signals is one of the most common operations in Godot and the API gives many options to do so, which are described further down. The code block below shows the recommended approach for both GDScript and C#. + Connecting signals is one of the most common operations in Godot and the API gives many options to do so, which are described further down. The code block below shows the recommended approach. [codeblocks] [gdscript] func _ready(): var button = Button.new() - # `button_down` here is a Signal object, and we thus call the Signal.connect() method, - # not Object.connect(). See discussion below for a more in-depth overview of the API. + # `button_down` here is a Signal variant type, and we thus call the Signal.connect() method, not Object.connect(). + # See discussion below for a more in-depth overview of the API. button.button_down.connect(_on_button_down) - # This assumes that a `Player` class exists which defines a `hit` signal. + # This assumes that a `Player` class exists, which defines a `hit` signal. var player = Player.new() - # We use Signal.connect() again, and we also use the Callable.bind() method which - # returns a new Callable with the parameter binds. + # We use Signal.connect() again, and we also use the Callable.bind() method, + # which returns a new Callable with the parameter binds. player.hit.connect(_on_player_hit.bind("sword", 100)) func _on_button_down(): @@ -204,7 +391,7 @@ // C# supports passing signals as events, so we can use this idiomatic construct: button.ButtonDown += OnButtonDown; - // This assumes that a `Player` class exists which defines a `Hit` signal. + // This assumes that a `Player` class exists, which defines a `Hit` signal. var player = new Player(); // Signals as events (`player.Hit += OnPlayerHit;`) do not support argument binding. You have to use: player.Hit.Connect(OnPlayerHit, new Godot.Collections.Array {"sword", 100 }); @@ -261,44 +448,41 @@ } [/csharp] [/codeblocks] - While all options have the same outcome ([code]button[/code]'s [signal BaseButton.button_down] signal will be connected to [code]_on_button_down[/code]), option 3 offers the best validation: it will print a compile-time error if either the [code]button_down[/code] signal or the [code]_on_button_down[/code] callable are undefined. On the other hand, option 2 only relies on string names and will only be able to validate either names at runtime: it will print a runtime error if [code]"button_down"[/code] doesn't correspond to a signal, or if [code]"_on_button_down"[/code] is not a registered method in the object [code]self[/code]. The main reason for using options 1, 2, or 4 would be if you actually need to use strings (e.g. to connect signals programmatically based on strings read from a configuration file). Otherwise, option 3 is the recommended (and fastest) method. - [b]Parameter bindings and passing:[/b] - For legacy or language-specific reasons, there are also several ways to bind parameters to signals. One can pass a [code]binds[/code] [Array] to [method Object.connect] or [method Signal.connect], or use the recommended [method Callable.bind] method to create a new callable from an existing one, with the given parameter binds. - One can also pass additional parameters when emitting the signal with [method emit_signal]. The examples below show the relationship between those two types of parameters. + While all options have the same outcome ([code]button[/code]'s [signal BaseButton.button_down] signal will be connected to [code]_on_button_down[/code]), [b]option 3[/b] offers the best validation: it will print a compile-time error if either the [code]button_down[/code] [Signal] or the [code]_on_button_down[/code] [Callable] are not defined. On the other hand, [b]option 2[/b] only relies on string names and will only be able to validate either names at runtime: it will print a runtime error if [code]"button_down"[/code] doesn't correspond to a signal, or if [code]"_on_button_down"[/code] is not a registered method in the object [code]self[/code]. The main reason for using options 1, 2, or 4 would be if you actually need to use strings (e.g. to connect signals programmatically based on strings read from a configuration file). Otherwise, option 3 is the recommended (and fastest) method. + [b]Binding and passing parameters:[/b] + The syntax to bind parameters is through [method Callable.bind], which returns a copy of the [Callable] with its parameters bound. + When calling [method emit_signal], the signal parameters can be also passed. The examples below show the relationship between these signal parameters and bound parameters. [codeblocks] [gdscript] func _ready(): - # This assumes that a `Player` class exists which defines a `hit` signal. + # This assumes that a `Player` class exists, which defines a `hit` signal. var player = Player.new() - # Option 1: Using Callable.bind(). player.hit.connect(_on_player_hit.bind("sword", 100)) - # Option 2: Using a `binds` Array in Signal.connect() (same syntax for Object.connect()). - player.hit.connect(_on_player_hit, ["sword", 100]) # Parameters added when emitting the signal are passed first. player.emit_signal("hit", "Dark lord", 5) - # Four arguments, since we pass two when emitting (hit_by, level) - # and two when connecting (weapon_type, damage). + # We pass two arguments when emitting (`hit_by`, `level`), + # and bind two more arguments when connecting (`weapon_type`, `damage`). func _on_player_hit(hit_by, level, weapon_type, damage): print("Hit by %s (level %d) with weapon %s for %d damage." % [hit_by, level, weapon_type, damage]) [/gdscript] [csharp] public override void _Ready() { - // This assumes that a `Player` class exists which defines a `Hit` signal. + // This assumes that a `Player` class exists, which defines a `Hit` signal. var player = new Player(); // Option 1: Using Callable.Bind(). This way we can still use signals as events. player.Hit += OnPlayerHit.Bind("sword", 100); - // Option 2: Using a `binds` Array in Signal.Connect() (same syntax for Object.Connect()). + // Option 2: Using a `binds` Array in Signal.Connect(). player.Hit.Connect(OnPlayerHit, new Godot.Collections.Array{ "sword", 100 }); // Parameters added when emitting the signal are passed first. player.EmitSignal("hit", "Dark lord", 5); } - // Four arguments, since we pass two when emitting (hitBy, level) - // and two when connecting (weaponType, damage). + // We pass two arguments when emitting (`hit_by`, `level`), + // and bind two more arguments when connecting (`weapon_type`, `damage`). private void OnPlayerHit(string hitBy, int level, string weaponType, int damage) { GD.Print(String.Format("Hit by {0} (level {1}) with weapon {2} for {3} damage.", hitBy, level, weaponType, damage)); @@ -312,57 +496,68 @@ <param index="0" name="signal" type="StringName" /> <param index="1" name="callable" type="Callable" /> <description> - Disconnects a [param signal] from a given [param callable]. - If you try to disconnect a connection that does not exist, the method will print an error. Use [method is_connected] to ensure that the connection exists. + Disconnects a [param signal] by name from a given [param callable]. If the connection does not exist, generates an error. Use [method is_connected] to make sure that the connection exists. </description> </method> <method name="emit_signal" qualifiers="vararg"> <return type="int" enum="Error" /> <param index="0" name="signal" type="StringName" /> <description> - Emits the given [param signal]. The signal must exist, so it should be a built-in signal of this class or one of its parent classes, or a user-defined signal. This method supports a variable number of arguments, so parameters are passed as a comma separated list. - [b]Example:[/b] + Emits the given [param signal] by name. The signal must exist, so it should be a built-in signal of this class or one of its inherited classes, or a user-defined signal (see [method add_user_signal]). This method supports a variable number of arguments, so parameters can be passed as a comma separated list. + Returns [constant ERR_UNAVAILABLE] if [param signal] does not exist or the parameters are invalid. [codeblocks] [gdscript] emit_signal("hit", "sword", 100) emit_signal("game_over") [/gdscript] [csharp] - EmitSignal("hit", "sword", 100); - EmitSignal("game_over"); + EmitSignal("Hit", "sword", 100); + EmitSignal("GameOver"); [/csharp] [/codeblocks] + [b]Note:[/b] In C#, [param signal] must be in snake_case when referring to built-in Godot signals. Prefer using the names exposed in the [code]SignalName[/code] class to avoid allocating a new [StringName] on each call. </description> </method> <method name="free"> <return type="void" /> <description> - Deletes the object from memory. Any pre-existing reference to the freed object will become invalid, e.g. [code]is_instance_valid(object)[/code] will return [code]false[/code]. + Deletes the object from memory. Pre-existing references to the object become invalid, and any attempt to access them will result in a run-time error. Checking the references with [method @GlobalScope.is_instance_valid] will return [code]false[/code]. </description> </method> <method name="get" qualifiers="const"> <return type="Variant" /> <param index="0" name="property" type="StringName" /> <description> - Returns the [Variant] value of the given [param property]. If the [param property] doesn't exist, this will return [code]null[/code]. - [b]Note:[/b] In C#, the property name must be specified as snake_case if it is defined by a built-in Godot node. This doesn't apply to user-defined properties where you should use the same convention as in the C# source (typically PascalCase). + Returns the [Variant] value of the given [param property]. If the [param property] does not exist, this method returns [code]null[/code]. + [codeblocks] + [gdscript] + var node = Node2D.new() + node.rotation = 1.5 + var a = node.get("rotation") # a is 1.5 + [/gdscript] + [csharp] + var node = new Node2D(); + node.Rotation = 1.5f; + var a = node.Get("rotation"); // a is 1.5 + [/csharp] + [/codeblocks] + [b]Note:[/b] In C#, [param property] must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the [code]PropertyName[/code] class to avoid allocating a new [StringName] on each call. </description> </method> <method name="get_class" qualifiers="const"> <return type="String" /> <description> - Returns the object's class as a [String]. See also [method is_class]. - [b]Note:[/b] [method get_class] does not take [code]class_name[/code] declarations into account. If the object has a [code]class_name[/code] defined, the base class name will be returned instead. + Returns the object's built-in class name, as a [String]. See also [method is_class]. + [b]Note:[/b] This method ignores [code]class_name[/code] declarations. If this object's script has defined a [code]class_name[/code], the base, built-in class name is returned instead. </description> </method> <method name="get_incoming_connections" qualifiers="const"> <return type="Dictionary[]" /> <description> - Returns an [Array] of dictionaries with information about signals that are connected to the object. - Each [Dictionary] contains three String entries: - - [code]source[/code] is a reference to the signal emitter. - - [code]signal_name[/code] is the name of the connected signal. - - [code]method_name[/code] is the name of the method to which the signal is connected. + Returns an [Array] of signal connections received by this object. Each connection is represented as a [Dictionary] that contains three entries: + - [code]signal[/code] is a reference to the [Signal]; + - [code]callable[/code] is a reference to the [Callable]; + - [code]flags[/code] is a combination of [enum ConnectFlags]. </description> </method> <method name="get_indexed" qualifiers="const"> @@ -371,14 +566,28 @@ <description> Gets the object's property indexed by the given [param property_path]. The path should be a [NodePath] relative to the current object and can use the colon character ([code]:[/code]) to access nested properties. [b]Examples:[/b] [code]"position:x"[/code] or [code]"material:next_pass:blend_mode"[/code]. - [b]Note:[/b] Even though the method takes [NodePath] argument, it doesn't support actual paths to [Node]s in the scene tree, only colon-separated sub-property paths. For the purpose of nodes, use [method Node.get_node_and_resource] instead. + [codeblocks] + [gdscript] + var node = Node2D.new() + node.position = Vector2(5, -10) + var a = node.get_indexed("position") # a is Vector2(5, -10) + var b = node.get_indexed("position:y") # b is -10 + [/gdscript] + [csharp] + var node = new Node2D(); + node.Position = new Vector2(5, -10); + var a = node.GetIndexed("position"); // a is Vector2(5, -10) + var b = node.GetIndexed("position:y"); // b is -10 + [/csharp] + [/codeblocks] + [b]Note:[/b] In C#, [param property_path] must be in snake_case when referring to built-in Godot properties. + [b]Note:[/b] This method does not support actual paths to nodes in the [SceneTree], only sub-property paths. In the context of nodes, use [method Node.get_node_and_resource] instead. </description> </method> <method name="get_instance_id" qualifiers="const"> <return type="int" /> <description> - Returns the object's unique instance ID. - This ID can be saved in [EncodedObjectAsID], and can be used to retrieve the object instance with [method @GlobalScope.instance_from_id]. + Returns the object's unique instance ID. This ID can be saved in [EncodedObjectAsID], and can be used to retrieve this object instance with [method @GlobalScope.instance_from_id]. </description> </method> <method name="get_meta" qualifiers="const"> @@ -386,47 +595,62 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="default" type="Variant" default="null" /> <description> - Returns the object's metadata entry for the given [param name]. - Throws error if the entry does not exist, unless [param default] is not [code]null[/code] (in which case the default value will be returned). See also [method has_meta], [method set_meta] and [method remove_meta]. - [b]Note:[/b] Metadata that has a [param name] starting with an underscore ([code]_[/code]) is considered editor-only. Editor-only metadata is not displayed in the Inspector and should not be edited. + Returns the object's metadata value for the given entry [param name]. If the entry does not exist, returns [param default]. If [param default] is [code]null[/code], an error is also generated. + [b]Note:[/b] Metadata that has a [param name] starting with an underscore ([code]_[/code]) is considered editor-only. Editor-only metadata is not displayed in the Inspector dock and should not be edited. </description> </method> <method name="get_meta_list" qualifiers="const"> <return type="PackedStringArray" /> <description> - Returns the object's metadata as a [PackedStringArray]. + Returns the object's metadata entry names as a [PackedStringArray]. </description> </method> <method name="get_method_list" qualifiers="const"> <return type="Dictionary[]" /> <description> - Returns the object's methods and their signatures as an [Array]. + Returns this object's methods and their signatures as an [Array] of dictionaries. Each [Dictionary] contains the following entries: + - [code]name[/code] is the name of the method, as a [String]; + - [code]args[/code] is an [Array] of dictionaries representing the arguments; + - [code]default_args[/code] is the default arguments as an [Array] of variants; + - [code]flags[/code] is a combination of [enum MethodFlags]; + - [code]id[/code] is the method's internal identifier [int]; + - [code]return[/code] is the returned value, as a [Dictionary]; + [b]Note:[/b] The dictionaries of [code]args[/code] and [code]return[/code] are formatted identically to the results of [method get_property_list], although not all entries are used. </description> </method> <method name="get_property_list" qualifiers="const"> <return type="Dictionary[]" /> <description> - Returns the object's property list as an [Array] of dictionaries. - Each property's [Dictionary] contain at least [code]name: String[/code] and [code]type: int[/code] (see [enum Variant.Type]) entries. Optionally, it can also include [code]hint: int[/code] (see [enum PropertyHint]), [code]hint_string: String[/code], and [code]usage: int[/code] (see [enum PropertyUsageFlags]). + Returns the object's property list as an [Array] of dictionaries. Each [Dictionary] contains the following entries: + - [code]name[/code] is the property's name, as a [String]; + - [code]class_name[/code] is an empty [StringName], unless the property is [constant TYPE_OBJECT] and it inherits from a class; + - [code]type[/code] is the property's type, as an [int] (see [enum Variant.Type]); + - [code]hint[/code] is [i]how[/i] the property is meant to be edited (see [enum PropertyHint]); + - [code]hint_string[/code] depends on the hint (see [enum PropertyHint]); + - [code]usage[/code] is a combination of [enum PropertyUsageFlags]. </description> </method> <method name="get_script" qualifiers="const"> <return type="Variant" /> <description> - Returns the object's [Script] instance, or [code]null[/code] if none is assigned. + Returns the object's [Script] instance, or [code]null[/code] if no script is attached. </description> </method> <method name="get_signal_connection_list" qualifiers="const"> <return type="Dictionary[]" /> <param index="0" name="signal" type="StringName" /> <description> - Returns an [Array] of connections for the given [param signal]. + Returns an [Array] of connections for the given [param signal] name. Each connection is represented as a [Dictionary] that contains three entries: + - [code]signal[/code] is a reference to the [Signal]; + - [code]callable[/code] is a reference to the [Callable]; + - [code]flags[/code] is a combination of [enum ConnectFlags]. </description> </method> <method name="get_signal_list" qualifiers="const"> <return type="Dictionary[]" /> <description> - Returns the list of signals as an [Array] of dictionaries. + Returns the list of existing signals as an [Array] of dictionaries. + [b]Note:[/b] Due of the implementation, each [Dictionary] is formatted very similarly to the returned values of [method get_method_list]. </description> </method> <method name="has_meta" qualifiers="const"> @@ -434,34 +658,36 @@ <param index="0" name="name" type="StringName" /> <description> Returns [code]true[/code] if a metadata entry is found with the given [param name]. See also [method get_meta], [method set_meta] and [method remove_meta]. - [b]Note:[/b] Metadata that has a [param name] starting with an underscore ([code]_[/code]) is considered editor-only. Editor-only metadata is not displayed in the Inspector and should not be edited. + [b]Note:[/b] Metadata that has a [param name] starting with an underscore ([code]_[/code]) is considered editor-only. Editor-only metadata is not displayed in the Inspector and should not be edited, although it can still be found by this method. </description> </method> <method name="has_method" qualifiers="const"> <return type="bool" /> <param index="0" name="method" type="StringName" /> <description> - Returns [code]true[/code] if the object contains the given [param method]. + Returns [code]true[/code] if the the given [param method] name exists in the object. + [b]Note:[/b] In C#, [param method] must be in snake_case when referring to built-in Godot methods. Prefer using the names exposed in the [code]MethodName[/code] class to avoid allocating a new [StringName] on each call. </description> </method> <method name="has_signal" qualifiers="const"> <return type="bool" /> <param index="0" name="signal" type="StringName" /> <description> - Returns [code]true[/code] if the given [param signal] exists. + Returns [code]true[/code] if the given [param signal] name exists in the object. + [b]Note:[/b] In C#, [param signal] must be in snake_case when referring to built-in Godot methods. Prefer using the names exposed in the [code]SignalName[/code] class to avoid allocating a new [StringName] on each call. </description> </method> <method name="has_user_signal" qualifiers="const"> <return type="bool" /> <param index="0" name="signal" type="StringName" /> <description> - Returns [code]true[/code] if the given user-defined [param signal] exists. Only signals added using [method add_user_signal] are taken into account. + Returns [code]true[/code] if the given user-defined [param signal] name exists. Only signals added with [method add_user_signal] are included. </description> </method> <method name="is_blocking_signals" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if signal emission blocking is enabled. + Returns [code]true[/code] if the object is blocking its signals from being emitted. See [method set_block_signals]. </description> </method> <method name="is_class" qualifiers="const"> @@ -469,7 +695,21 @@ <param index="0" name="class" type="String" /> <description> Returns [code]true[/code] if the object inherits from the given [param class]. See also [method get_class]. - [b]Note:[/b] [method is_class] does not take [code]class_name[/code] declarations into account. If the object has a [code]class_name[/code] defined, [method is_class] will return [code]false[/code] for that name. + [codeblocks] + [gdscript] + var sprite2d = Sprite2D.new() + sprite2d.is_class("Sprite2D") # Returns true + sprite2d.is_class("Node") # Returns true + sprite2d.is_class("Node3D") # Returns false + [/gdscript] + [csharp] + var sprite2d = new Sprite2D(); + sprite2d.IsClass("Sprite2D"); // Returns true + sprite2d.IsClass("Node"); // Returns true + sprite2d.IsClass("Node3D"); // Returns false + [/csharp] + [/codeblocks] + [b]Note:[/b] This method ignores [code]class_name[/code] declarations in the object's script. </description> </method> <method name="is_connected" qualifiers="const"> @@ -477,7 +717,8 @@ <param index="0" name="signal" type="StringName" /> <param index="1" name="callable" type="Callable" /> <description> - Returns [code]true[/code] if a connection exists for a given [param signal] and [param callable]. + Returns [code]true[/code] if a connection exists between the given [param signal] name and [param callable]. + [b]Note:[/b] In C#, [param signal] must be in snake_case when referring to built-in Godot methods. Prefer using the names exposed in the [code]SignalName[/code] class to avoid allocating a new [StringName] on each call. </description> </method> <method name="is_queued_for_deletion" qualifiers="const"> @@ -491,21 +732,59 @@ <param index="0" name="what" type="int" /> <param index="1" name="reversed" type="bool" default="false" /> <description> - Send a given notification to the object, which will also trigger a call to the [method _notification] method of all classes that the object inherits from. - If [param reversed] is [code]true[/code], [method _notification] is called first on the object's own class, and then up to its successive parent classes. If [param reversed] is [code]false[/code], [method _notification] is called first on the highest ancestor ([Object] itself), and then down to its successive inheriting classes. + Sends the given [param what] notification to all classes inherited by the object, triggering calls to [method _notification], starting from the highest ancestor (the [Object] class) and going down to the object's script. + If [param reversed] is [code]true[/code], the call order is reversed. + [codeblocks] + [gdscript] + var player = Node2D.new() + player.set_script(load("res://player.gd")) + + player.notification(NOTIFICATION_ENTER_TREE) + # The call order is Object -> Node -> Node2D -> player.gd. + + player.notification(NOTIFICATION_ENTER_TREE, true) + # The call order is player.gd -> Node2D -> Node -> Object. + [/gdscript] + [csharp] + var player = new Node2D(); + player.SetScript(GD.Load("res://player.gd")); + + player.Notification(NotificationEnterTree); + // The call order is Object -> Node -> Node2D -> player.gd. + + player.notification(NotificationEnterTree, true); + // The call order is player.gd -> Node2D -> Node -> Object. + [/csharp] + [/codeblocks] </description> </method> <method name="notify_property_list_changed"> <return type="void" /> <description> - Notify the editor that the property list has changed by emitting the [signal property_list_changed] signal, so that editor plugins can take the new values into account. + Emits the [signal property_list_changed] signal. This is mainly used to refresh the editor, so that the Inspector and editor plugins are properly updated. + </description> + </method> + <method name="property_can_revert" qualifiers="const"> + <return type="bool" /> + <param index="0" name="property" type="StringName" /> + <description> + Returns [code]true[/code] if the given [param property] has a custom default value. Use [method property_get_revert] to get the [param property]'s default value. + [b]Note:[/b] This method is used by the Inspector dock to display a revert icon. The object must implement [method _property_can_revert] to customize the default value. If [method _property_can_revert] is not implemented, this method returns [code]false[/code]. + </description> + </method> + <method name="property_get_revert" qualifiers="const"> + <return type="Variant" /> + <param index="0" name="property" type="StringName" /> + <description> + Returns the custom default value of the given [param property]. Use [method property_can_revert] to check if the [param property] has a custom default value. + [b]Note:[/b] This method is used by the Inspector dock to display a revert icon. The object must implement [method _property_get_revert] to customize the default value. If [method _property_get_revert] is not implemented, this method returns [code]null[/code]. </description> </method> <method name="remove_meta"> <return type="void" /> <param index="0" name="name" type="StringName" /> <description> - Removes a given entry from the object's metadata. See also [method has_meta], [method get_meta] and [method set_meta]. + Removes the given entry [param name] from the object's metadata. See also [method has_meta], [method get_meta] and [method set_meta]. [b]Note:[/b] Metadata that has a [param name] starting with an underscore ([code]_[/code]) is considered editor-only. Editor-only metadata is not displayed in the Inspector and should not be edited. </description> </method> @@ -514,15 +793,27 @@ <param index="0" name="property" type="StringName" /> <param index="1" name="value" type="Variant" /> <description> - Assigns a new value to the given property. If the [param property] does not exist or the given value's type doesn't match, nothing will happen. - [b]Note:[/b] In C#, the property name must be specified as snake_case if it is defined by a built-in Godot node. This doesn't apply to user-defined properties where you should use the same convention as in the C# source (typically PascalCase). + Assigns [param value] to the given [param property]. If the property does not exist or the given [param value]'s type doesn't match, nothing happens. + [codeblocks] + [gdscript] + var node = Node2D.new() + node.set("global_scale", Vector2(8, 2.5)) + print(node.global_scale) # Prints (8, 2.5) + [/gdscript] + [csharp] + var node = new Node2D(); + node.Set("global_scale", new Vector2(8, 2.5)); + GD.Print(node.GlobalScale); // Prints Vector2(8, 2.5) + [/csharp] + [/codeblocks] + [b]Note:[/b] In C#, [param property] must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the [code]PropertyName[/code] class to avoid allocating a new [StringName] on each call. </description> </method> <method name="set_block_signals"> <return type="void" /> <param index="0" name="enable" type="bool" /> <description> - If set to [code]true[/code], signal emission is blocked. + If set to [code]true[/code], the object becomes unable to emit signals. As such, [method emit_signal] and signal connections will not work, until it is set to [code]false[/code]. </description> </method> <method name="set_deferred"> @@ -530,8 +821,30 @@ <param index="0" name="property" type="StringName" /> <param index="1" name="value" type="Variant" /> <description> - Assigns a new value to the given property, after the current frame's physics step. This is equivalent to calling [method set] via [method call_deferred], i.e. [code]call_deferred("set", property, value)[/code]. - [b]Note:[/b] In C#, the property name must be specified as snake_case if it is defined by a built-in Godot node. This doesn't apply to user-defined properties where you should use the same convention as in the C# source (typically PascalCase). + Assigns [param value] to the given [param property], after the current frame's physics step. This is equivalent to calling [method set] through [method call_deferred]. + [codeblocks] + [gdscript] + var node = Node2D.new() + add_child(node) + + node.rotation = 45.0 + node.set_deferred("rotation", 90.0) + print(node.rotation) # Prints 45.0 + + await get_tree().process_frame + print(node.rotation) # Prints 90.0 + [/gdscript] + [csharp] + var node = new Node2D(); + node.Rotation = 45f; + node.SetDeferred("rotation", 90f); + GD.Print(node.Rotation); // Prints 45.0 + + await ToSignal(GetTree(), SceneTree.SignalName.ProcessFrame); + GD.Print(node.Rotation); // Prints 90.0 + [/csharp] + [/codeblocks] + [b]Note:[/b] In C#, [param property] must be in snake_case when referring to built-in Godot properties. Prefer using the names exposed in the [code]PropertyName[/code] class to avoid allocating a new [StringName] on each call. </description> </method> <method name="set_indexed"> @@ -539,29 +852,29 @@ <param index="0" name="property_path" type="NodePath" /> <param index="1" name="value" type="Variant" /> <description> - Assigns a new value to the property identified by the [param property_path]. The path should be a [NodePath] relative to the current object and can use the colon character ([code]:[/code]) to access nested properties. - [b]Example:[/b] + Assigns a new [param value] to the property identified by the [param property_path]. The path should be a [NodePath] relative to this object, and can use the colon character ([code]:[/code]) to access nested properties. [codeblocks] [gdscript] var node = Node2D.new() node.set_indexed("position", Vector2(42, 0)) node.set_indexed("position:y", -10) - print(node.position) # (42, -10) + print(node.position) # Prints (42, -10) [/gdscript] [csharp] var node = new Node2D(); node.SetIndexed("position", new Vector2(42, 0)); node.SetIndexed("position:y", -10); - GD.Print(node.Position); // (42, -10) + GD.Print(node.Position); // Prints (42, -10) [/csharp] [/codeblocks] + [b]Note:[/b] In C#, [param property_path] must be in snake_case when referring to built-in Godot properties. </description> </method> <method name="set_message_translation"> <return type="void" /> <param index="0" name="enable" type="bool" /> <description> - Defines whether the object can translate strings (with calls to [method tr]). Enabled by default. + If set to [code]true[/code], allows the object to translate messages with [method tr] and [method tr_n]. Enabled by default. See also [method can_translate_messages]. </description> </method> <method name="set_meta"> @@ -569,24 +882,23 @@ <param index="0" name="name" type="StringName" /> <param index="1" name="value" type="Variant" /> <description> - Adds, changes or removes a given entry in the object's metadata. Metadata are serialized and can take any [Variant] value. - To remove a given entry from the object's metadata, use [method remove_meta]. Metadata is also removed if its value is set to [code]null[/code]. This means you can also use [code]set_meta("name", null)[/code] to remove metadata for [code]"name"[/code]. See also [method has_meta] and [method get_meta]. - [b]Note:[/b] Metadata that has a [param name] starting with an underscore ([code]_[/code]) is considered editor-only. Editor-only metadata is not displayed in the Inspector and should not be edited. + Adds or changes the entry [param name] inside the object's metadata. The metadata [param value] can be any [Variant], although some types cannot be serialised correctly. + If [param value] is [code]null[/code], the entry is removed. This is the equivalent of using [method remove_meta]. See also [method has_meta] and [method get_meta]. + [b]Note:[/b] Metadata that has a [param name] starting with an underscore ([code]_[/code]) is considered editor-only. Editor-only metadata is not displayed in the Inspector dock and should not be edited. </description> </method> <method name="set_script"> <return type="void" /> <param index="0" name="script" type="Variant" /> <description> - Assigns a script to the object. Each object can have a single script assigned to it, which are used to extend its functionality. - If the object already had a script, the previous script instance will be freed and its variables and state will be lost. The new script's [method _init] method will be called. + Attaches [param script] to the object, and instantiates it. As a result, the script's [method _init] is called. A [Script] is used to extend the object's functionality. + If a script already exists, its instance is detached, and its property values and state are lost. Built-in property values are still kept. </description> </method> <method name="to_string"> <return type="String" /> <description> - Returns a [String] representing the object. If not overridden, defaults to [code]"[ClassName:RID]"[/code]. - Override the method [method _to_string] to customize the [String] representation. + Returns a [String] representing the object. Defaults to [code]"<ClassName#RID>"[/code]. Override [method _to_string] to customize the string representation of the object. </description> </method> <method name="tr" qualifiers="const"> @@ -594,9 +906,9 @@ <param index="0" name="message" type="StringName" /> <param index="1" name="context" type="StringName" default="""" /> <description> - Translates a message using translation catalogs configured in the Project Settings. An additional context could be used to specify the translation context. - Only works if message translation is enabled (which it is by default), otherwise it returns the [param message] unchanged. See [method set_message_translation]. - See [url=$DOCS_URL/tutorials/i18n/internationalizing_games.html]Internationalizing games[/url] for examples of the usage of this method. + Translates a [param message], using the translation catalogs configured in the Project Settings. Further [param context] can be specified to help with the translation. + If [method can_translate_messages] is [code]false[/code], or no translation is available, this method returns the [param message] without changes. See [method set_message_translation]. + For detailed examples, see [url=$DOCS_URL/tutorials/i18n/internationalizing_games.html]Internationalizing games[/url]. </description> </method> <method name="tr_n" qualifiers="const"> @@ -606,43 +918,45 @@ <param index="2" name="n" type="int" /> <param index="3" name="context" type="StringName" default="""" /> <description> - Translates a message involving plurals using translation catalogs configured in the Project Settings. An additional context could be used to specify the translation context. - Only works if message translation is enabled (which it is by default), otherwise it returns the [param message] or [param plural_message] unchanged. See [method set_message_translation]. - The number [param n] is the number or quantity of the plural object. It will be used to guide the translation system to fetch the correct plural form for the selected language. - [b]Note:[/b] Negative and floating-point values usually represent physical entities for which singular and plural don't clearly apply. In such cases, use [method tr]. - See [url=$DOCS_URL/tutorials/i18n/localization_using_gettext.html]Localization using gettext[/url] for examples of the usage of this method. + Translates a [param message] or [param plural_message], using the translation catalogs configured in the Project Settings. Further [param context] can be specified to help with the translation. + If [method can_translate_messages] is [code]false[/code], or no translation is available, this method returns [param message] or [param plural_message], without changes. See [method set_message_translation]. + The [param n] is the number, or amount, of the message's subject. It is used by the translation system to fetch the correct plural form for the current language. + For detailed examples, see [url=$DOCS_URL/tutorials/i18n/localization_using_gettext.html]Localization using gettext[/url]. + [b]Note:[/b] Negative and [float] numbers may not properly apply to some countable subjects. It's recommended handling these cases with [method tr]. </description> </method> </methods> <signals> <signal name="property_list_changed"> <description> + Emitted when [method notify_property_list_changed] is called. </description> </signal> <signal name="script_changed"> <description> - Emitted whenever the object's script is changed. + Emitted when the object's script is changed. + [b]Note:[/b] When this signal is emitted, the new script is not initialized yet. If you need to access the new script, defer connections to this signal with [constant CONNECT_DEFERRED]. </description> </signal> </signals> <constants> <constant name="NOTIFICATION_POSTINITIALIZE" value="0"> - Called right when the object is initialized. Not available in script. + Notification received when the object is initialized, before its script is attached. Used internally. </constant> <constant name="NOTIFICATION_PREDELETE" value="1"> - Called before the object is about to be deleted. + Notification received when the object is about to be deleted. Can act as the deconstructor of some programming languages. </constant> <constant name="CONNECT_DEFERRED" value="1" enum="ConnectFlags"> - Connects a signal in deferred mode. This way, signal emissions are stored in a queue, then set on idle time. + Deferred connections trigger their [Callable]s on idle time, rather than instantly. </constant> <constant name="CONNECT_PERSIST" value="2" enum="ConnectFlags"> - Persisting connections are saved when the object is serialized to file. + Persisting connections are stored when the object is serialized (such as when using [method PackedScene.pack]). In the editor, connections created through the Node dock are always persisting. </constant> <constant name="CONNECT_ONE_SHOT" value="4" enum="ConnectFlags"> One-shot connections disconnect themselves after emission. </constant> <constant name="CONNECT_REFERENCE_COUNTED" value="8" enum="ConnectFlags"> - Connect a signal as reference-counted. This means that a given signal can be connected several times to the same target, and will only be fully disconnected once no references are left. + Reference-counted connections can be assigned to the same [Callable] multiple times. Each disconnection decreases the internal counter. The signal fully disconnects only when the counter reaches 0. </constant> </constants> </class> diff --git a/doc/classes/PhysicalSkyMaterial.xml b/doc/classes/PhysicalSkyMaterial.xml index 9d303d80e5..a8cfb9abc2 100644 --- a/doc/classes/PhysicalSkyMaterial.xml +++ b/doc/classes/PhysicalSkyMaterial.xml @@ -12,27 +12,28 @@ </tutorials> <members> <member name="energy_multiplier" type="float" setter="set_energy_multiplier" getter="get_energy_multiplier" default="1.0"> + The sky's overall brightness multiplier. Higher values result in a brighter sky. </member> <member name="ground_color" type="Color" setter="set_ground_color" getter="get_ground_color" default="Color(0.1, 0.07, 0.034, 1)"> Modulates the [Color] on the bottom half of the sky to represent the ground. </member> <member name="mie_coefficient" type="float" setter="set_mie_coefficient" getter="get_mie_coefficient" default="0.005"> - Controls the strength of mie scattering for the sky. Mie scattering results from light colliding with larger particles (like water). On earth, mie scattering results in a whitish color around the sun and horizon. + Controls the strength of [url=https://en.wikipedia.org/wiki/Mie_scattering]Mie scattering[/url] for the sky. Mie scattering results from light colliding with larger particles (like water). On earth, Mie scattering results in a whitish color around the sun and horizon. </member> <member name="mie_color" type="Color" setter="set_mie_color" getter="get_mie_color" default="Color(0.69, 0.729, 0.812, 1)"> - Controls the [Color] of the mie scattering effect. While not physically accurate, this allows for the creation of alien-looking planets. + Controls the [Color] of the [url=https://en.wikipedia.org/wiki/Mie_scattering]Mie scattering[/url] effect. While not physically accurate, this allows for the creation of alien-looking planets. </member> <member name="mie_eccentricity" type="float" setter="set_mie_eccentricity" getter="get_mie_eccentricity" default="0.8"> - Controls the direction of the mie scattering. A value of [code]1[/code] means that when light hits a particle it's passing through straight forward. A value of [code]-1[/code] means that all light is scatter backwards. + Controls the direction of the [url=https://en.wikipedia.org/wiki/Mie_scattering]Mie scattering[/url]. A value of [code]1[/code] means that when light hits a particle it's passing through straight forward. A value of [code]-1[/code] means that all light is scatter backwards. </member> <member name="night_sky" type="Texture2D" setter="set_night_sky" getter="get_night_sky"> [Texture2D] for the night sky. This is added to the sky, so if it is bright enough, it may be visible during the day. </member> <member name="rayleigh_coefficient" type="float" setter="set_rayleigh_coefficient" getter="get_rayleigh_coefficient" default="2.0"> - Controls the strength of the Rayleigh scattering. Rayleigh scattering results from light colliding with small particles. It is responsible for the blue color of the sky. + Controls the strength of the [url=https://en.wikipedia.org/wiki/Rayleigh_scattering]Rayleigh scattering[/url]. Rayleigh scattering results from light colliding with small particles. It is responsible for the blue color of the sky. </member> <member name="rayleigh_color" type="Color" setter="set_rayleigh_color" getter="get_rayleigh_color" default="Color(0.3, 0.405, 0.6, 1)"> - Controls the [Color] of the Rayleigh scattering. While not physically accurate, this allows for the creation of alien-looking planets. For example, setting this to a red [Color] results in a Mars-looking atmosphere with a corresponding blue sunset. + Controls the [Color] of the [url=https://en.wikipedia.org/wiki/Rayleigh_scattering]Rayleigh scattering[/url]. While not physically accurate, this allows for the creation of alien-looking planets. For example, setting this to a red [Color] results in a Mars-looking atmosphere with a corresponding blue sunset. </member> <member name="sun_disk_scale" type="float" setter="set_sun_disk_scale" getter="get_sun_disk_scale" default="1.0"> Sets the size of the sun disk. Default value is based on Sol's perceived size from Earth. diff --git a/doc/classes/PhysicsPointQueryParameters2D.xml b/doc/classes/PhysicsPointQueryParameters2D.xml index a6cbe2d574..e49d2a9f5f 100644 --- a/doc/classes/PhysicsPointQueryParameters2D.xml +++ b/doc/classes/PhysicsPointQueryParameters2D.xml @@ -22,7 +22,7 @@ The physics layers the query will detect (as a bitmask). By default, all collision layers are detected. 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="exclude" type="RID[]" setter="set_exclude" getter="get_exclude" default="[]"> - The list of objects or object [RID]s that will be excluded from collisions. + The list of object [RID]s that will be excluded from collisions. Use [method CollisionObject2D.get_rid] to get the [RID] associated with a [CollisionObject2D]-derived node. </member> <member name="position" type="Vector2" setter="set_position" getter="get_position" default="Vector2(0, 0)"> The position being queried for, in global coordinates. diff --git a/doc/classes/PhysicsPointQueryParameters3D.xml b/doc/classes/PhysicsPointQueryParameters3D.xml index bedf05ce99..3270d3686d 100644 --- a/doc/classes/PhysicsPointQueryParameters3D.xml +++ b/doc/classes/PhysicsPointQueryParameters3D.xml @@ -18,8 +18,8 @@ <member name="collision_mask" type="int" setter="set_collision_mask" getter="get_collision_mask" default="4294967295"> The physics layers the query will detect (as a bitmask). By default, all collision layers are detected. 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="exclude" type="Array" setter="set_exclude" getter="get_exclude" default="[]"> - The list of objects or object [RID]s that will be excluded from collisions. + <member name="exclude" type="RID[]" setter="set_exclude" getter="get_exclude" default="[]"> + The list of object [RID]s that will be excluded from collisions. Use [method CollisionObject3D.get_rid] to get the [RID] associated with a [CollisionObject3D]-derived node. </member> <member name="position" type="Vector3" setter="set_position" getter="get_position" default="Vector3(0, 0, 0)"> The position being queried for, in global coordinates. diff --git a/doc/classes/PhysicsRayQueryParameters2D.xml b/doc/classes/PhysicsRayQueryParameters2D.xml index d6a2662adc..cf5c31d9ec 100644 --- a/doc/classes/PhysicsRayQueryParameters2D.xml +++ b/doc/classes/PhysicsRayQueryParameters2D.xml @@ -35,7 +35,7 @@ The physics layers the query will detect (as a bitmask). By default, all collision layers are detected. 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="exclude" type="RID[]" setter="set_exclude" getter="get_exclude" default="[]"> - The list of objects or object [RID]s that will be excluded from collisions. + The list of object [RID]s that will be excluded from collisions. Use [method CollisionObject2D.get_rid] to get the [RID] associated with a [CollisionObject2D]-derived node. </member> <member name="from" type="Vector2" setter="set_from" getter="get_from" default="Vector2(0, 0)"> The starting point of the ray being queried for, in global coordinates. diff --git a/doc/classes/PhysicsRayQueryParameters3D.xml b/doc/classes/PhysicsRayQueryParameters3D.xml index 620aa6bf5f..4f70eedb21 100644 --- a/doc/classes/PhysicsRayQueryParameters3D.xml +++ b/doc/classes/PhysicsRayQueryParameters3D.xml @@ -14,7 +14,7 @@ <param index="0" name="from" type="Vector3" /> <param index="1" name="to" type="Vector3" /> <param index="2" name="collision_mask" type="int" default="4294967295" /> - <param index="3" name="exclude" type="Array" default="[]" /> + <param index="3" name="exclude" type="RID[]" default="[]" /> <description> Returns a new, pre-configured [PhysicsRayQueryParameters3D] object. Use it to quickly create query parameters using the most common options. [codeblock] @@ -34,8 +34,8 @@ <member name="collision_mask" type="int" setter="set_collision_mask" getter="get_collision_mask" default="4294967295"> The physics layers the query will detect (as a bitmask). By default, all collision layers are detected. 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="exclude" type="Array" setter="set_exclude" getter="get_exclude" default="[]"> - The list of objects or object [RID]s that will be excluded from collisions. + <member name="exclude" type="RID[]" setter="set_exclude" getter="get_exclude" default="[]"> + The list of object [RID]s that will be excluded from collisions. Use [method CollisionObject3D.get_rid] to get the [RID] associated with a [CollisionObject3D]-derived node. </member> <member name="from" type="Vector3" setter="set_from" getter="get_from" default="Vector3(0, 0, 0)"> The starting point of the ray being queried for, in global coordinates. diff --git a/doc/classes/PhysicsShapeQueryParameters2D.xml b/doc/classes/PhysicsShapeQueryParameters2D.xml index 8dcb329e7e..a73e60c6f5 100644 --- a/doc/classes/PhysicsShapeQueryParameters2D.xml +++ b/doc/classes/PhysicsShapeQueryParameters2D.xml @@ -19,7 +19,7 @@ The physics layers the query will detect (as a bitmask). By default, all collision layers are detected. 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="exclude" type="RID[]" setter="set_exclude" getter="get_exclude" default="[]"> - The list of objects or object [RID]s that will be excluded from collisions. + The list of object [RID]s that will be excluded from collisions. Use [method CollisionObject2D.get_rid] to get the [RID] associated with a [CollisionObject2D]-derived node. </member> <member name="margin" type="float" setter="set_margin" getter="get_margin" default="0.0"> The collision margin for the shape. diff --git a/doc/classes/PhysicsShapeQueryParameters3D.xml b/doc/classes/PhysicsShapeQueryParameters3D.xml index 64100f847b..a3ff1765f9 100644 --- a/doc/classes/PhysicsShapeQueryParameters3D.xml +++ b/doc/classes/PhysicsShapeQueryParameters3D.xml @@ -18,8 +18,8 @@ <member name="collision_mask" type="int" setter="set_collision_mask" getter="get_collision_mask" default="4294967295"> The physics layers the query will detect (as a bitmask). By default, all collision layers are detected. 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="exclude" type="Array" setter="set_exclude" getter="get_exclude" default="[]"> - The list of objects or object [RID]s that will be excluded from collisions. + <member name="exclude" type="RID[]" setter="set_exclude" getter="get_exclude" default="[]"> + The list of object [RID]s that will be excluded from collisions. Use [method CollisionObject3D.get_rid] to get the [RID] associated with a [CollisionObject3D]-derived node. </member> <member name="margin" type="float" setter="set_margin" getter="get_margin" default="0.0"> The collision margin for the shape. diff --git a/doc/classes/PhysicsTestMotionParameters2D.xml b/doc/classes/PhysicsTestMotionParameters2D.xml index 5b969ea869..be5e5a3617 100644 --- a/doc/classes/PhysicsTestMotionParameters2D.xml +++ b/doc/classes/PhysicsTestMotionParameters2D.xml @@ -14,9 +14,9 @@ If set to [code]false[/code], shapes of type [constant PhysicsServer2D.SHAPE_SEPARATION_RAY] are only used for separation when overlapping with other bodies. That's the main use for separation ray shapes. </member> <member name="exclude_bodies" type="RID[]" setter="set_exclude_bodies" getter="get_exclude_bodies" default="[]"> - Optional array of body [RID] to exclude from collision. + Optional array of body [RID] to exclude from collision. Use [method CollisionObject2D.get_rid] to get the [RID] associated with a [CollisionObject2D]-derived node. </member> - <member name="exclude_objects" type="Array" setter="set_exclude_objects" getter="get_exclude_objects" default="[]"> + <member name="exclude_objects" type="int[]" setter="set_exclude_objects" getter="get_exclude_objects" default="[]"> Optional array of object unique instance ID to exclude from collision. See [method Object.get_instance_id]. </member> <member name="from" type="Transform2D" setter="set_from" getter="get_from" default="Transform2D(1, 0, 0, 1, 0, 0)"> diff --git a/doc/classes/PhysicsTestMotionParameters3D.xml b/doc/classes/PhysicsTestMotionParameters3D.xml index ea9bca6a35..be7d05691e 100644 --- a/doc/classes/PhysicsTestMotionParameters3D.xml +++ b/doc/classes/PhysicsTestMotionParameters3D.xml @@ -13,10 +13,10 @@ If set to [code]true[/code], shapes of type [constant PhysicsServer3D.SHAPE_SEPARATION_RAY] are used to detect collisions and can stop the motion. Can be useful when snapping to the ground. If set to [code]false[/code], shapes of type [constant PhysicsServer3D.SHAPE_SEPARATION_RAY] are only used for separation when overlapping with other bodies. That's the main use for separation ray shapes. </member> - <member name="exclude_bodies" type="Array" setter="set_exclude_bodies" getter="get_exclude_bodies" default="[]"> - Optional array of body [RID] to exclude from collision. + <member name="exclude_bodies" type="RID[]" setter="set_exclude_bodies" getter="get_exclude_bodies" default="[]"> + Optional array of body [RID] to exclude from collision. Use [method CollisionObject3D.get_rid] to get the [RID] associated with a [CollisionObject3D]-derived node. </member> - <member name="exclude_objects" type="Array" setter="set_exclude_objects" getter="get_exclude_objects" default="[]"> + <member name="exclude_objects" type="int[]" setter="set_exclude_objects" getter="get_exclude_objects" default="[]"> Optional array of object unique instance ID to exclude from collision. See [method Object.get_instance_id]. </member> <member name="from" type="Transform3D" setter="set_from" getter="get_from" default="Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0)"> diff --git a/doc/classes/PointLight2D.xml b/doc/classes/PointLight2D.xml index 89cabbd428..0c51a78e49 100644 --- a/doc/classes/PointLight2D.xml +++ b/doc/classes/PointLight2D.xml @@ -1,10 +1,13 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="PointLight2D" inherits="Light2D" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> + Positional 2D light source. </brief_description> <description> + Casts light in a 2D environment. This light's shape is defined by a (usually grayscale) texture </description> <tutorials> + <link title="2D lights and shadows">$DOCS_URL/tutorials/2d/2d_lights_and_shadows.html</link> </tutorials> <members> <member name="height" type="float" setter="set_height" getter="get_height" default="0.0"> diff --git a/doc/classes/Popup.xml b/doc/classes/Popup.xml index 3fcf0a9b8f..a56bf77774 100644 --- a/doc/classes/Popup.xml +++ b/doc/classes/Popup.xml @@ -4,7 +4,7 @@ Popup is a base window container for popup-like subwindows. </brief_description> <description> - Popup is a base window container for popup-like subwindows. It's a modal by default (see [member popup_window]) and has helpers for custom popup behavior. + Popup is a base window container for popup-like subwindows. It's a modal by default (see [member Window.popup_window]) and has helpers for custom popup behavior. </description> <tutorials> </tutorials> diff --git a/doc/classes/PopupMenu.xml b/doc/classes/PopupMenu.xml index 0dcb33ac4c..a69163f429 100644 --- a/doc/classes/PopupMenu.xml +++ b/doc/classes/PopupMenu.xml @@ -544,6 +544,7 @@ </signal> <signal name="menu_changed"> <description> + Emitted when any item is added, modified or removed. </description> </signal> </signals> @@ -576,8 +577,10 @@ Width of the single indentation level. </theme_item> <theme_item name="item_end_padding" data_type="constant" type="int" default="2"> + Horizontal padding to the right of the items (or left, in RTL layout). </theme_item> <theme_item name="item_start_padding" data_type="constant" type="int" default="2"> + Horizontal padding to the left of the items (or right, in RTL layout). </theme_item> <theme_item name="outline_size" data_type="constant" type="int" default="0"> The size of the item text outline. diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml index 3478215f4f..1f0a8d91fa 100644 --- a/doc/classes/ProjectSettings.xml +++ b/doc/classes/ProjectSettings.xml @@ -401,7 +401,7 @@ <member name="debug/gdscript/warnings/redundant_await" type="int" setter="" getter="" default="1"> When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when a function that is not a coroutine is called with await. </member> - <member name="debug/gdscript/warnings/return_value_discarded" type="int" setter="" getter="" default="1"> + <member name="debug/gdscript/warnings/return_value_discarded" type="int" setter="" getter="" default="0"> When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when calling a function without using its return value (by assigning it to a variable or using it as a function argument). Such return values are sometimes used to denote possible errors using the [enum Error] enum. </member> <member name="debug/gdscript/warnings/shadowed_global_identifier" type="int" setter="" getter="" default="1"> @@ -839,6 +839,7 @@ [b]Note:[/b] Default [code]ui_*[/code] actions cannot be removed as they are necessary for the internal logic of several [Control]s. The events assigned to the action can however be modified. </member> <member name="input/ui_swap_input_direction" type="Dictionary" setter="" getter=""> + Default [InputEventAction] to swap input direction, i.e. change between left-to-right to right-to-left modes. Affects text-editting controls ([LineEdit], [TextEdit]). </member> <member name="input/ui_text_add_selection_for_next_occurrence" type="Dictionary" setter="" getter=""> If a selection is currently active with the last caret in text fields, searches for the next occurrence of the selection, adds a caret and selects the next occurrence. @@ -2265,7 +2266,20 @@ Set the default Variable Rate Shading (VRS) mode for the main viewport. See [member Viewport.vrs_mode] to change this at runtime, and [enum Viewport.VRSMode] for possible values. </member> <member name="rendering/vrs/texture" type="String" setter="" getter="" default=""""> - If [member rendering/vrs/mode] is set to texture, this is the path to default texture loaded as the VRS image. + If [member rendering/vrs/mode] is set to [b]Texture[/b], this is the path to default texture loaded as the VRS image. + The texture [i]must[/i] use a lossless compression format so that colors can be matched precisely. The following VRS densities are mapped to various colors, with brighter colors representing a lower level of shading precision: + [codeblock] + - 1x1 = rgb(0, 0, 0) - #000000 + - 1x2 = rgb(0, 85, 0) - #005500 + - 2x1 = rgb(85, 0, 0) - #550000 + - 2x2 = rgb(85, 85, 0) - #555500 + - 2x4 = rgb(85, 170, 0) - #55aa00 + - 4x2 = rgb(170, 85, 0) - #aa5500 + - 4x4 = rgb(170, 170, 0) - #aaaa00 + - 4x8 = rgb(170, 255, 0) - #aaff00 - Not supported on most hardware + - 8x4 = rgb(255, 170, 0) - #ffaa00 - Not supported on most hardware + - 8x8 = rgb(255, 255, 0) - #ffff00 - Not supported on most hardware + [/codeblock] </member> <member name="threading/worker_pool/low_priority_thread_ratio" type="float" setter="" getter="" default="0.3"> </member> diff --git a/doc/classes/RDTextureFormat.xml b/doc/classes/RDTextureFormat.xml index 1b70303d2d..3bfcd610a4 100644 --- a/doc/classes/RDTextureFormat.xml +++ b/doc/classes/RDTextureFormat.xml @@ -35,7 +35,7 @@ </member> <member name="texture_type" type="int" setter="set_texture_type" getter="get_texture_type" enum="RenderingDevice.TextureType" default="1"> </member> - <member name="usage_bits" type="int" setter="set_usage_bits" getter="get_usage_bits" default="0"> + <member name="usage_bits" type="int" setter="set_usage_bits" getter="get_usage_bits" enum="RenderingDevice.TextureUsageBits" default="0"> </member> <member name="width" type="int" setter="set_width" getter="get_width" default="1"> </member> diff --git a/doc/classes/RID.xml b/doc/classes/RID.xml index a6523e4c8b..2d40a7be57 100644 --- a/doc/classes/RID.xml +++ b/doc/classes/RID.xml @@ -4,7 +4,8 @@ Handle for a [Resource]'s unique ID. </brief_description> <description> - The RID type is used to access the unique integer ID of a resource. They are opaque, which means they do not grant access to the associated resource by themselves. They are used by and with the low-level Server classes such as [RenderingServer]. + The RID [Variant] type is used to access a low-level resource by its unique ID. RIDs are opaque, which means they do not grant access to the resource by themselves. They are used by the low-level server classes, such as [DisplayServer], [RenderingServer], [TextServer], etc. + A low-level resource may correspond to a high-level [Resource], such as [Texture] or [Mesh]. </description> <tutorials> </tutorials> @@ -27,13 +28,13 @@ <method name="get_id" qualifiers="const"> <return type="int" /> <description> - Returns the ID of the referenced resource. + Returns the ID of the referenced low-level resource. </description> </method> <method name="is_valid" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if [RID] is valid. + Returns [code]true[/code] if the [RID] is not [code]0[/code]. </description> </method> </methods> @@ -42,36 +43,42 @@ <return type="bool" /> <param index="0" name="right" type="RID" /> <description> + Returns [code]true[/code] if the [RID]s are not equal. </description> </operator> <operator name="operator <"> <return type="bool" /> <param index="0" name="right" type="RID" /> <description> + Returns [code]true[/code] if the [RID]'s ID is less than [param right]'s ID. </description> </operator> <operator name="operator <="> <return type="bool" /> <param index="0" name="right" type="RID" /> <description> + Returns [code]true[/code] if the [RID]'s ID is less than or equal to [param right]'s ID. </description> </operator> <operator name="operator =="> <return type="bool" /> <param index="0" name="right" type="RID" /> <description> + Returns [code]true[/code] if both [RID]s are equal, which means they both refer to the same low-level resource. </description> </operator> <operator name="operator >"> <return type="bool" /> <param index="0" name="right" type="RID" /> <description> + Returns [code]true[/code] if the [RID]'s ID is greater than [param right]'s ID. </description> </operator> <operator name="operator >="> <return type="bool" /> <param index="0" name="right" type="RID" /> <description> + Returns [code]true[/code] if the [RID]'s ID is greater than or equal to [param right]'s ID. </description> </operator> </operators> diff --git a/doc/classes/Rect2.xml b/doc/classes/Rect2.xml index 28fe42afae..d39e50d5f0 100644 --- a/doc/classes/Rect2.xml +++ b/doc/classes/Rect2.xml @@ -82,9 +82,9 @@ var rect2 = rect.expand(Vector2(0, -1)) [/gdscript] [csharp] - # position (-3, 2), size (1, 1) + // position (-3, 2), size (1, 1) var rect = new Rect2(new Vector2(-3, 2), new Vector2(1, 1)); - # position (-3, -1), size (3, 4), so we fit both rect and Vector2(0, -1) + // position (-3, -1), size (3, 4), so we fit both rect and Vector2(0, -1) var rect2 = rect.Expand(new Vector2(0, -1)); [/csharp] [/codeblocks] diff --git a/doc/classes/Rect2i.xml b/doc/classes/Rect2i.xml index 6d4c113609..325ead0cfa 100644 --- a/doc/classes/Rect2i.xml +++ b/doc/classes/Rect2i.xml @@ -79,9 +79,9 @@ var rect2 = rect.expand(Vector2i(0, -1)) [/gdscript] [csharp] - # position (-3, 2), size (1, 1) + // position (-3, 2), size (1, 1) var rect = new Rect2i(new Vector2i(-3, 2), new Vector2i(1, 1)); - # position (-3, -1), size (3, 4), so we fit both rect and Vector2i(0, -1) + // position (-3, -1), size (3, 4), so we fit both rect and Vector2i(0, -1) var rect2 = rect.Expand(new Vector2i(0, -1)); [/csharp] [/codeblocks] diff --git a/doc/classes/RenderingDevice.xml b/doc/classes/RenderingDevice.xml index 7b041d3b75..8afe6eb935 100644 --- a/doc/classes/RenderingDevice.xml +++ b/doc/classes/RenderingDevice.xml @@ -9,8 +9,8 @@ <methods> <method name="barrier"> <return type="void" /> - <param index="0" name="from" type="int" default="7" /> - <param index="1" name="to" type="int" default="7" /> + <param index="0" name="from" type="int" enum="RenderingDevice.BarrierMask" default="7" /> + <param index="1" name="to" type="int" enum="RenderingDevice.BarrierMask" default="7" /> <description> </description> </method> @@ -19,7 +19,7 @@ <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" default="7" /> + <param index="3" name="post_barrier" type="int" enum="RenderingDevice.BarrierMask" default="7" /> <description> </description> </method> @@ -35,7 +35,7 @@ <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" default="7" /> + <param index="4" name="post_barrier" type="int" enum="RenderingDevice.BarrierMask" default="7" /> <description> </description> </method> @@ -83,7 +83,7 @@ </method> <method name="compute_list_end"> <return type="void" /> - <param index="0" name="post_barrier" type="int" default="7" /> + <param index="0" name="post_barrier" type="int" enum="RenderingDevice.BarrierMask" default="7" /> <description> </description> </method> @@ -223,7 +223,7 @@ </method> <method name="draw_list_end"> <return type="void" /> - <param index="0" name="post_barrier" type="int" default="7" /> + <param index="0" name="post_barrier" type="int" enum="RenderingDevice.BarrierMask" default="7" /> <description> </description> </method> @@ -534,7 +534,7 @@ <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" default="7" /> + <param index="6" name="post_barrier" type="int" enum="RenderingDevice.BarrierMask" default="7" /> <description> </description> </method> @@ -549,7 +549,7 @@ <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" default="7" /> + <param index="9" name="post_barrier" type="int" enum="RenderingDevice.BarrierMask" default="7" /> <description> </description> </method> @@ -589,7 +589,7 @@ <method name="texture_is_format_supported_for_usage" qualifiers="const"> <return type="bool" /> <param index="0" name="format" type="int" enum="RenderingDevice.DataFormat" /> - <param index="1" name="usage_flags" type="int" /> + <param index="1" name="usage_flags" type="int" enum="RenderingDevice.TextureUsageBits" /> <description> </description> </method> @@ -609,7 +609,7 @@ <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" default="7" /> + <param index="2" name="post_barrier" type="int" enum="RenderingDevice.BarrierMask" default="7" /> <description> </description> </method> @@ -618,7 +618,7 @@ <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" default="7" /> + <param index="3" name="post_barrier" type="int" enum="RenderingDevice.BarrierMask" default="7" /> <description> </description> </method> @@ -669,16 +669,6 @@ </method> </methods> <constants> - <constant name="BARRIER_MASK_RASTER" value="1"> - </constant> - <constant name="BARRIER_MASK_COMPUTE" value="2"> - </constant> - <constant name="BARRIER_MASK_TRANSFER" value="4"> - </constant> - <constant name="BARRIER_MASK_ALL" value="7"> - </constant> - <constant name="BARRIER_MASK_NO_BARRIER" value="8"> - </constant> <constant name="DEVICE_TYPE_OTHER" value="0" enum="DeviceType"> Rendering device type does not match any of the other enum values or is unknown. </constant> @@ -1161,6 +1151,16 @@ </constant> <constant name="DATA_FORMAT_MAX" value="218" enum="DataFormat"> </constant> + <constant name="BARRIER_MASK_RASTER" value="1" enum="BarrierMask" is_bitfield="true"> + </constant> + <constant name="BARRIER_MASK_COMPUTE" value="2" enum="BarrierMask" is_bitfield="true"> + </constant> + <constant name="BARRIER_MASK_TRANSFER" value="4" enum="BarrierMask" is_bitfield="true"> + </constant> + <constant name="BARRIER_MASK_ALL_BARRIERS" value="7" enum="BarrierMask" is_bitfield="true"> + </constant> + <constant name="BARRIER_MASK_NO_BARRIER" value="8" enum="BarrierMask" is_bitfield="true"> + </constant> <constant name="TEXTURE_TYPE_1D" value="0" enum="TextureType"> </constant> <constant name="TEXTURE_TYPE_2D" value="1" enum="TextureType"> @@ -1193,25 +1193,25 @@ </constant> <constant name="TEXTURE_SAMPLES_MAX" value="7" enum="TextureSamples"> </constant> - <constant name="TEXTURE_USAGE_SAMPLING_BIT" value="1" enum="TextureUsageBits"> + <constant name="TEXTURE_USAGE_SAMPLING_BIT" value="1" enum="TextureUsageBits" is_bitfield="true"> </constant> - <constant name="TEXTURE_USAGE_COLOR_ATTACHMENT_BIT" value="2" enum="TextureUsageBits"> + <constant name="TEXTURE_USAGE_COLOR_ATTACHMENT_BIT" value="2" enum="TextureUsageBits" is_bitfield="true"> </constant> - <constant name="TEXTURE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT" value="4" enum="TextureUsageBits"> + <constant name="TEXTURE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT" value="4" enum="TextureUsageBits" is_bitfield="true"> </constant> - <constant name="TEXTURE_USAGE_STORAGE_BIT" value="8" enum="TextureUsageBits"> + <constant name="TEXTURE_USAGE_STORAGE_BIT" value="8" enum="TextureUsageBits" is_bitfield="true"> </constant> - <constant name="TEXTURE_USAGE_STORAGE_ATOMIC_BIT" value="16" enum="TextureUsageBits"> + <constant name="TEXTURE_USAGE_STORAGE_ATOMIC_BIT" value="16" enum="TextureUsageBits" is_bitfield="true"> </constant> - <constant name="TEXTURE_USAGE_CPU_READ_BIT" value="32" enum="TextureUsageBits"> + <constant name="TEXTURE_USAGE_CPU_READ_BIT" value="32" enum="TextureUsageBits" is_bitfield="true"> </constant> - <constant name="TEXTURE_USAGE_CAN_UPDATE_BIT" value="64" enum="TextureUsageBits"> + <constant name="TEXTURE_USAGE_CAN_UPDATE_BIT" value="64" enum="TextureUsageBits" is_bitfield="true"> </constant> - <constant name="TEXTURE_USAGE_CAN_COPY_FROM_BIT" value="128" enum="TextureUsageBits"> + <constant name="TEXTURE_USAGE_CAN_COPY_FROM_BIT" value="128" enum="TextureUsageBits" is_bitfield="true"> </constant> - <constant name="TEXTURE_USAGE_CAN_COPY_TO_BIT" value="256" enum="TextureUsageBits"> + <constant name="TEXTURE_USAGE_CAN_COPY_TO_BIT" value="256" enum="TextureUsageBits" is_bitfield="true"> </constant> - <constant name="TEXTURE_USAGE_INPUT_ATTACHMENT_BIT" value="512" enum="TextureUsageBits"> + <constant name="TEXTURE_USAGE_INPUT_ATTACHMENT_BIT" value="512" enum="TextureUsageBits" is_bitfield="true"> </constant> <constant name="TEXTURE_SWIZZLE_IDENTITY" value="0" enum="TextureSwizzle"> </constant> diff --git a/doc/classes/RichTextLabel.xml b/doc/classes/RichTextLabel.xml index cb2481f705..e222894647 100644 --- a/doc/classes/RichTextLabel.xml +++ b/doc/classes/RichTextLabel.xml @@ -399,6 +399,12 @@ Scrolls the window's top line to match first line of the [param paragraph]. </description> </method> + <method name="scroll_to_selection"> + <return type="void" /> + <description> + Scrolls to the beginning of the current selection. + </description> + </method> <method name="select_all"> <return type="void" /> <description> diff --git a/doc/classes/ScrollContainer.xml b/doc/classes/ScrollContainer.xml index b96b7187e4..af39261e81 100644 --- a/doc/classes/ScrollContainer.xml +++ b/doc/classes/ScrollContainer.xml @@ -49,6 +49,7 @@ Controls whether horizontal scrollbar can be used and when it should be visible. See [enum ScrollMode] for options. </member> <member name="scroll_deadzone" type="int" setter="set_deadzone" getter="get_deadzone" default="0"> + Deadzone for touch scrolling. Lower deadzone makes the scrolling more sensitive. </member> <member name="scroll_horizontal" type="int" setter="set_h_scroll" getter="get_h_scroll" default="0"> The current horizontal scroll value. diff --git a/doc/classes/Signal.xml b/doc/classes/Signal.xml index d99477ee95..3412cd2140 100644 --- a/doc/classes/Signal.xml +++ b/doc/classes/Signal.xml @@ -1,9 +1,29 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="Signal" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - Class representing a signal defined in an object. + Built-in type representing a signal defined in an object. </brief_description> <description> + [Signal] is a built-in [Variant] type that represents a signal of an [Object] instance. Like all [Variant] types, it can be stored in variables and passed to functions. Signals allow all connected [Callable]s (and by extension their respective objects) to listen and react to events, without directly referencing one another. This keeps the code flexible and easier to manage. + In GDScript, signals can be declared with the [code]signal[/code] keyword. In C#, you may use the [code][Signal][/code] attribute on a delegate. + [codeblocks] + [gdscript] + signal attacked + + # Additional arguments may be declared. + # These arguments must be passed when the signal is emitted. + signal item_dropped(item_name, amount) + [/gdscript] + [csharp] + [Signal] + delegate void Attacked(); + + // Additional arguments may be declared. + // These arguments must be passed when the signal is emitted. + [Signal] + delegate void ItemDropped(itemName: string, amount: int); + [/csharp] + [/codeblocks] </description> <tutorials> <link title="Using Signals">$DOCS_URL/getting_started/step_by_step/signals.html</link> @@ -13,7 +33,7 @@ <constructor name="Signal"> <return type="Signal" /> <description> - Constructs a null [Signal] with no object nor signal name bound. + Constructs an empty [Signal] with no object nor signal name bound. </description> </constructor> <constructor name="Signal"> @@ -28,7 +48,7 @@ <param index="0" name="object" type="Object" /> <param index="1" name="signal" type="StringName" /> <description> - Creates a new [Signal] with the name [param signal] in the specified [param object]. + Creates a new [Signal] named [param signal] in the specified [param object]. </description> </constructor> </constructors> @@ -38,12 +58,13 @@ <param index="0" name="callable" type="Callable" /> <param index="1" name="flags" type="int" default="0" /> <description> - Connects this signal to the specified [Callable], optionally providing connection flags. You can provide additional arguments to the connected method call by using [method Callable.bind]. + Connects this signal to the specified [param callable]. Optional [param flags] can be also added to configure the connection's behavior (see [enum Object.ConnectFlags] constants). You can provide additional arguments to the connected [param callable] by using [method Callable.bind]. + A signal can only be connected once to the same [Callable]. If the signal is already connected, returns [constant ERR_INVALID_PARAMETER] and pushes an error message, unless the signal is connected with [constant Object.CONNECT_REFERENCE_COUNTED]. To prevent this, use [method is_connected] first to check for existing connections. [codeblock] for button in $Buttons.get_children(): - button.pressed.connect(on_pressed.bind(button)) + button.pressed.connect(_on_pressed.bind(button)) - func on_pressed(button): + func _on_pressed(button): print(button.name, " was pressed") [/codeblock] </description> @@ -52,13 +73,13 @@ <return type="void" /> <param index="0" name="callable" type="Callable" /> <description> - Disconnects this signal from the specified [Callable]. + Disconnects this signal from the specified [Callable]. If the connection does not exist, generates an error. Use [method is_connected] to make sure that the connection exists. </description> </method> <method name="emit" qualifiers="vararg const"> <return type="void" /> <description> - Emits this signal to all connected objects. + Emits this signal. All [Callable]s connected to this signal will be triggered. This method supports a variable number of arguments, so parameters can be passed as a comma separated list. </description> </method> <method name="get_connections" qualifiers="const"> @@ -95,6 +116,7 @@ <method name="is_null" qualifiers="const"> <return type="bool" /> <description> + Returns [code]true[/code] if the signal's name does not exist in its object, or the object is not valid. </description> </method> </methods> @@ -103,12 +125,14 @@ <return type="bool" /> <param index="0" name="right" type="Signal" /> <description> + Returns [code]true[/code] if the signals do not share the same object and name. </description> </operator> <operator name="operator =="> <return type="bool" /> <param index="0" name="right" type="Signal" /> <description> + Returns [code]true[/code] if both signals share the same object and name. </description> </operator> </operators> diff --git a/doc/classes/SpinBox.xml b/doc/classes/SpinBox.xml index e214867890..7d63747bd2 100644 --- a/doc/classes/SpinBox.xml +++ b/doc/classes/SpinBox.xml @@ -46,6 +46,7 @@ </methods> <members> <member name="alignment" type="int" setter="set_horizontal_alignment" getter="get_horizontal_alignment" enum="HorizontalAlignment" default="0"> + Changes the alignment of the underlying [LineEdit]. </member> <member name="custom_arrow_step" type="float" setter="set_custom_arrow_step" getter="get_custom_arrow_step" default="0.0"> If not [code]0[/code], [code]value[/code] will always be rounded to a multiple of [code]custom_arrow_step[/code] when interacting with the arrow buttons of the [SpinBox]. diff --git a/doc/classes/Sprite3D.xml b/doc/classes/Sprite3D.xml index 956e646702..01671aa04e 100644 --- a/doc/classes/Sprite3D.xml +++ b/doc/classes/Sprite3D.xml @@ -19,6 +19,7 @@ The number of columns in the sprite sheet. </member> <member name="region_enabled" type="bool" setter="set_region_enabled" getter="is_region_enabled" default="false"> + If [code]true[/code], the sprite will use [member region_rect] and display only the specified part of its texture. </member> <member name="region_rect" type="Rect2" setter="set_region_rect" getter="get_region_rect" default="Rect2(0, 0, 0, 0)"> The region of the atlas texture to display. [member region_enabled] must be [code]true[/code]. diff --git a/doc/classes/String.xml b/doc/classes/String.xml index 53040b2753..c186952c74 100644 --- a/doc/classes/String.xml +++ b/doc/classes/String.xml @@ -27,14 +27,14 @@ <return type="String" /> <param index="0" name="from" type="NodePath" /> <description> - Constructs a new String from the given [NodePath]. + Constructs a new [String] from the given [NodePath]. </description> </constructor> <constructor name="String"> <return type="String" /> <param index="0" name="from" type="StringName" /> <description> - Constructs a new String from the given [StringName]. + Constructs a new [String] from the given [StringName]. </description> </constructor> </constructors> @@ -51,7 +51,7 @@ <description> Returns an array containing the bigrams (pairs of consecutive letters) of this string. [codeblock] - print("Bigrams".bigrams()) # Prints "[Bi, ig, gr, ra, am, ms]" + print("Bigrams".bigrams()) # Prints ["Bi", "ig", "gr", "ra", "am", "ms"] [/codeblock] </description> </method> @@ -920,66 +920,88 @@ <return type="bool" /> <param index="0" name="right" type="String" /> <description> + Returns [code]true[/code] if both strings do not contain the same sequence of characters. </description> </operator> <operator name="operator !="> <return type="bool" /> <param index="0" name="right" type="StringName" /> <description> + Returns [code]true[/code] if this [String] is not equivalent to the given [StringName]. </description> </operator> <operator name="operator %"> <return type="String" /> <param index="0" name="right" type="Variant" /> <description> + Formats the [String], replacing the placeholders with one or more parameters. + To pass multiple parameters, [param right] needs to be an [Array]. + [codeblock] + print("I caught %d fishes!" % 2) # Prints "I caught 2 fishes!" + + var my_message = "Travelling to %s, at %2.2f per second." + var location = "Deep Valley" + var speed = 40.3485 + print(my_message % [location, speed]) # Prints "Travelling to Deep Valley, at 40.35 km/h." + [/codeblock] + In C#, there is no direct equivalent to this operator. Use the [method format] method, instead. + For more information, see the [url=$DOCS_URL/tutorials/scripting/gdscript/gdscript_format_string.html]GDScript format strings[/url] tutorial. </description> </operator> <operator name="operator +"> <return type="String" /> <param index="0" name="right" type="String" /> <description> + Appends [param right] at the end of this [String], also known as a string concatenation. </description> </operator> <operator name="operator <"> <return type="bool" /> <param index="0" name="right" type="String" /> <description> + Returns [code]true[/code] if the left [String] comes before [param right] in [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode order[/url], which roughly matches the alphabetical order. Useful for sorting. </description> </operator> <operator name="operator <="> <return type="bool" /> <param index="0" name="right" type="String" /> <description> + Returns [code]true[/code] if the left [String] comes before [param right] in [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode order[/url], which roughly matches the alphabetical order, or if both are equal. </description> </operator> <operator name="operator =="> <return type="bool" /> <param index="0" name="right" type="String" /> <description> + Returns [code]true[/code] if both strings contain the same sequence of characters. </description> </operator> <operator name="operator =="> <return type="bool" /> <param index="0" name="right" type="StringName" /> <description> + Returns [code]true[/code] if this [String] is equivalent to the given [StringName]. </description> </operator> <operator name="operator >"> <return type="bool" /> <param index="0" name="right" type="String" /> <description> + Returns [code]true[/code] if the left [String] comes after [param right] in [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode order[/url], which roughly matches the alphabetical order. Useful for sorting. </description> </operator> <operator name="operator >="> <return type="bool" /> <param index="0" name="right" type="String" /> <description> + Returns [code]true[/code] if the left [String] comes after [param right] in [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode order[/url], which roughly matches the alphabetical order, or if both are equal. </description> </operator> <operator name="operator []"> <return type="String" /> <param index="0" name="index" type="int" /> <description> + Returns a new [String] that only contains the character at [param index]. Indices start from [code]0[/code]. If [param index] is greater or equal to [code]0[/code], the character is fetched starting from the beginning of the string. If [param index] is a negative value, it is fetched starting from the end. Accessing a string out-of-bounds will cause a run-time error, pausing the project execution if run from the editor. </description> </operator> </operators> diff --git a/doc/classes/StringName.xml b/doc/classes/StringName.xml index c40d8929fc..02e9c62cd6 100644 --- a/doc/classes/StringName.xml +++ b/doc/classes/StringName.xml @@ -5,7 +5,7 @@ </brief_description> <description> [StringName]s are immutable strings designed for general-purpose representation of unique names (also called "string interning"). [StringName] ensures that only one instance of a given name exists (so two [StringName]s with the same value are the same object). Comparing them is much faster than with regular [String]s, because only the pointers are compared, not the whole strings. - 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 [StringName] or the literal syntax [code]&"example"[/code]. + 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 [StringName] or, in GDScript, the literal syntax [code]&"example"[/code]. See also [NodePath], which is a similar concept specifically designed to store pre-parsed node paths. </description> <tutorials> @@ -28,7 +28,7 @@ <return type="StringName" /> <param index="0" name="from" type="String" /> <description> - Creates a new [StringName] from the given [String]. [code]StringName("example")[/code] is equivalent to [code]&"example"[/code]. + Creates a new [StringName] from the given [String]. In GDScript, [code]StringName("example")[/code] is equivalent to [code]&"example"[/code]. </description> </constructor> </constructors> @@ -45,48 +45,56 @@ <return type="bool" /> <param index="0" name="right" type="String" /> <description> + Returns [code]true[/code] if this [StringName] is not equivalent to the given [String]. </description> </operator> <operator name="operator !="> <return type="bool" /> <param index="0" name="right" type="StringName" /> <description> + Returns [code]true[/code] if the [StringName] and [param right] do not refer to the same name. Comparisons between [StringName]s are much faster than regular [String] comparisons. </description> </operator> <operator name="operator <"> <return type="bool" /> <param index="0" name="right" type="StringName" /> <description> + Returns [code]true[/code] if the left [String] comes before [param right] in [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode order[/url], which roughly matches the alphabetical order. Useful for sorting. </description> </operator> <operator name="operator <="> <return type="bool" /> <param index="0" name="right" type="StringName" /> <description> + Returns [code]true[/code] if the left [String] comes before [param right] in [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode order[/url], which roughly matches the alphabetical order, or if both are equal. </description> </operator> <operator name="operator =="> <return type="bool" /> <param index="0" name="right" type="String" /> <description> + Returns [code]true[/code] if this [StringName] is equivalent to the given [String]. </description> </operator> <operator name="operator =="> <return type="bool" /> <param index="0" name="right" type="StringName" /> <description> + Returns [code]true[/code] if the [StringName] and [param right] refer to the same name. Comparisons between [StringName]s are much faster than regular [String] comparisons. </description> </operator> <operator name="operator >"> <return type="bool" /> <param index="0" name="right" type="StringName" /> <description> + Returns [code]true[/code] if the left [StringName] comes after [param right] in [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode order[/url], which roughly matches the alphabetical order. Useful for sorting. </description> </operator> <operator name="operator >="> <return type="bool" /> <param index="0" name="right" type="StringName" /> <description> + Returns [code]true[/code] if the left [StringName] comes after [param right] in [url=https://en.wikipedia.org/wiki/List_of_Unicode_characters]Unicode order[/url], which roughly matches the alphabetical order, or if both are equal. </description> </operator> </operators> diff --git a/doc/classes/SystemFont.xml b/doc/classes/SystemFont.xml index b47d6ded7d..20bfd0d8ae 100644 --- a/doc/classes/SystemFont.xml +++ b/doc/classes/SystemFont.xml @@ -7,23 +7,32 @@ <description> [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" and/or "italic" features set. + 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. </description> <tutorials> </tutorials> <members> + <member name="allow_system_fallback" type="bool" setter="set_allow_system_fallback" getter="is_allow_system_fallback" default="true"> + If set to [code]true[/code], system fonts can be automatically used as fallbacks. + </member> <member name="antialiasing" type="int" setter="set_antialiasing" getter="get_antialiasing" enum="TextServer.FontAntialiasing" default="1"> Font anti-aliasing mode. </member> <member name="fallbacks" type="Font[]" setter="set_fallbacks" getter="get_fallbacks" default="[]"> Array of fallback [Font]s. </member> + <member name="font_italic" type="bool" setter="set_font_italic" getter="get_font_italic" default="false"> + If set to [code]true[/code], italic or oblique font is preferred. + </member> <member name="font_names" type="PackedStringArray" setter="set_font_names" getter="get_font_names" default="PackedStringArray()"> Array of font family names to search, first matching font found is used. </member> - <member name="font_style" type="int" setter="set_font_style" getter="get_font_style" enum="TextServer.FontStyle" default="0"> - Font style flags, see [enum TextServer.FontStyle]. + <member name="font_stretch" type="int" setter="set_font_stretch" getter="get_font_stretch" default="100"> + Preferred font stretch amount, compared to a normal width. A percentage value between [code]50%[/code] and [code]200%[/code]. + </member> + <member name="font_weight" type="int" setter="set_font_weight" getter="get_font_weight" default="400"> + Preferred weight (boldness) of the font. A value in the [code]100...999[/code] range, normal font weight is [code]400[/code], bold font weight is [code]700[/code]. </member> <member name="force_autohinter" type="bool" setter="set_force_autohinter" getter="is_force_autohinter" default="false"> If set to [code]true[/code], auto-hinting is supported and preferred over font built-in hinting. diff --git a/doc/classes/TextServer.xml b/doc/classes/TextServer.xml index f4d92ab9b6..b3e55b5cd0 100644 --- a/doc/classes/TextServer.xml +++ b/doc/classes/TextServer.xml @@ -362,6 +362,13 @@ Returns list of the font sizes in the cache. Each size is [code]Vector2i[/code] with font size and outline size. </description> </method> + <method name="font_get_stretch" qualifiers="const"> + <return type="int" /> + <param index="0" name="font_rid" type="RID" /> + <description> + Returns font stretch amount, compared to a normal width. A percentage value between [code]50%[/code] and [code]200%[/code]. + </description> + </method> <method name="font_get_style" qualifiers="const"> <return type="int" enum="TextServer.FontStyle" /> <param index="0" name="font_rid" type="RID" /> @@ -446,6 +453,13 @@ Returns variation coordinates for the specified font cache entry. See [method font_supported_variation_list] for more info. </description> </method> + <method name="font_get_weight" qualifiers="const"> + <return type="int" /> + <param index="0" name="font_rid" type="RID" /> + <description> + Returns weight (boldness) of the font. A value in the [code]100...999[/code] range, normal font weight is [code]400[/code], bold font weight is [code]700[/code]. + </description> + </method> <method name="font_has_char" qualifiers="const"> <return type="bool" /> <param index="0" name="font_rid" type="RID" /> @@ -454,6 +468,13 @@ Returns [code]true[/code] if a Unicode [param char] is available in the font. </description> </method> + <method name="font_is_allow_system_fallback" qualifiers="const"> + <return type="bool" /> + <param index="0" name="font_rid" type="RID" /> + <description> + Returns [code]true[/code] if system fonts can be automatically used as fallbacks. + </description> + </method> <method name="font_is_force_autohinter" qualifiers="const"> <return type="bool" /> <param index="0" name="font_rid" type="RID" /> @@ -556,6 +577,14 @@ Renders the range of characters to the font cache texture. </description> </method> + <method name="font_set_allow_system_fallback"> + <return type="void" /> + <param index="0" name="font_rid" type="RID" /> + <param index="1" name="allow_system_fallback" type="bool" /> + <description> + If set to [code]true[/code], system fonts can be automatically used as fallbacks. + </description> + </method> <method name="font_set_antialiasing"> <return type="void" /> <param index="0" name="font_rid" type="RID" /> @@ -783,12 +812,22 @@ Adds override for [method font_is_script_supported]. </description> </method> + <method name="font_set_stretch"> + <return type="void" /> + <param index="0" name="font_rid" type="RID" /> + <param index="1" name="weight" type="int" /> + <description> + Sets font stretch amount, compared to a normal width. A percentage value between [code]50%[/code] and [code]200%[/code]. + [b]Note:[/b] This value is used for font matching only and will not affect font rendering. Use [method font_set_face_index], [method font_set_variation_coordinates], or [method font_set_transform] instead. + </description> + </method> <method name="font_set_style"> <return type="void" /> <param index="0" name="font_rid" type="RID" /> <param index="1" name="style" type="int" enum="TextServer.FontStyle" /> <description> Sets the font style flags, see [enum FontStyle]. + [b]Note:[/b] This value is used for font matching only and will not affect font rendering. Use [method font_set_face_index], [method font_set_variation_coordinates], [method font_set_embolden], or [method font_set_transform] instead. </description> </method> <method name="font_set_style_name"> @@ -862,6 +901,15 @@ Sets variation coordinates for the specified font cache entry. See [method font_supported_variation_list] for more info. </description> </method> + <method name="font_set_weight"> + <return type="void" /> + <param index="0" name="font_rid" type="RID" /> + <param index="1" name="weight" type="int" /> + <description> + Sets weight (boldness) of the font. A value in the [code]100...999[/code] range, normal font weight is [code]400[/code], bold font weight is [code]700[/code]. + [b]Note:[/b] This value is used for font matching only and will not affect font rendering. Use [method font_set_face_index], [method font_set_variation_coordinates], or [method font_set_embolden] instead. + </description> + </method> <method name="font_supported_feature_list" qualifiers="const"> <return type="Dictionary" /> <param index="0" name="font_rid" type="RID" /> diff --git a/doc/classes/TextServerExtension.xml b/doc/classes/TextServerExtension.xml index 37d2698dd4..4c9817fcd4 100644 --- a/doc/classes/TextServerExtension.xml +++ b/doc/classes/TextServerExtension.xml @@ -9,6 +9,11 @@ <tutorials> </tutorials> <methods> + <method name="_cleanup" qualifiers="virtual"> + <return type="void" /> + <description> + </description> + </method> <method name="_create_font" qualifiers="virtual"> <return type="RID" /> <description> @@ -306,6 +311,12 @@ <description> </description> </method> + <method name="_font_get_stretch" qualifiers="virtual const"> + <return type="int" /> + <param index="0" name="font_rid" type="RID" /> + <description> + </description> + </method> <method name="_font_get_style" qualifiers="virtual const"> <return type="int" enum="TextServer.FontStyle" /> <param index="0" name="font_rid" type="RID" /> @@ -379,6 +390,12 @@ <description> </description> </method> + <method name="_font_get_weight" qualifiers="virtual const"> + <return type="int" /> + <param index="0" name="font_rid" type="RID" /> + <description> + </description> + </method> <method name="_font_has_char" qualifiers="virtual const"> <return type="bool" /> <param index="0" name="font_rid" type="RID" /> @@ -386,6 +403,12 @@ <description> </description> </method> + <method name="_font_is_allow_system_fallback" qualifiers="virtual const"> + <return type="bool" /> + <param index="0" name="font_rid" type="RID" /> + <description> + </description> + </method> <method name="_font_is_force_autohinter" qualifiers="virtual const"> <return type="bool" /> <param index="0" name="font_rid" type="RID" /> @@ -474,6 +497,13 @@ <description> </description> </method> + <method name="_font_set_allow_system_fallback" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="font_rid" type="RID" /> + <param index="1" name="allow_system_fallback" type="bool" /> + <description> + </description> + </method> <method name="_font_set_antialiasing" qualifiers="virtual"> <return type="void" /> <param index="0" name="font_rid" type="RID" /> @@ -680,6 +710,13 @@ <description> </description> </method> + <method name="_font_set_stretch" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="font_rid" type="RID" /> + <param index="1" name="stretch" type="int" /> + <description> + </description> + </method> <method name="_font_set_style" qualifiers="virtual"> <return type="void" /> <param index="0" name="font_rid" type="RID" /> @@ -749,6 +786,13 @@ <description> </description> </method> + <method name="_font_set_weight" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="font_rid" type="RID" /> + <param index="1" name="weight" type="int" /> + <description> + </description> + </method> <method name="_font_supported_feature_list" qualifiers="virtual const"> <return type="Dictionary" /> <param index="0" name="font_rid" type="RID" /> diff --git a/doc/classes/TextureProgressBar.xml b/doc/classes/TextureProgressBar.xml index 54b77bf5eb..d7a9d06a15 100644 --- a/doc/classes/TextureProgressBar.xml +++ b/doc/classes/TextureProgressBar.xml @@ -13,6 +13,7 @@ <return type="int" /> <param index="0" name="margin" type="int" enum="Side" /> <description> + Returns the stretch margin with the specified index. See [member stretch_margin_bottom] and related properties. </description> </method> <method name="set_stretch_margin"> @@ -20,6 +21,7 @@ <param index="0" name="margin" type="int" enum="Side" /> <param index="1" name="value" type="int" /> <description> + Sets the stretch margin with the specified index. See [member stretch_margin_bottom] and related properties. </description> </method> </methods> diff --git a/doc/classes/TileData.xml b/doc/classes/TileData.xml index 798a536a88..f815b8d0c3 100644 --- a/doc/classes/TileData.xml +++ b/doc/classes/TileData.xml @@ -1,8 +1,10 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="TileData" inherits="Object" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> + Settings for a single tile in a [TileSet]. </brief_description> <description> + [TileData] object represents a single tile in a [TileSet]. It is usually edited using the tileset editor, but it can be modified at runtime using [method TileMap._tile_data_runtime_update]. </description> <tutorials> </tutorials> @@ -196,32 +198,43 @@ </methods> <members> <member name="flip_h" type="bool" setter="set_flip_h" getter="get_flip_h" default="false"> + If [code]true[/code], the tile will have its texture flipped horizontally. </member> <member name="flip_v" type="bool" setter="set_flip_v" getter="get_flip_v" default="false"> + If [code]true[/code], the tile will have its texture flipped vertically. </member> <member name="material" type="Material" setter="set_material" getter="get_material"> The [Material] to use for this [TileData]. This can be a [CanvasItemMaterial] to use the default shader, or a [ShaderMaterial] to use a custom shader. </member> <member name="modulate" type="Color" setter="set_modulate" getter="get_modulate" default="Color(1, 1, 1, 1)"> + Color modulation of the tile. </member> <member name="probability" type="float" setter="set_probability" getter="get_probability" default="1.0"> + Relative probability of this tile being selected when drawing a pattern of random tiles. </member> <member name="terrain" type="int" setter="set_terrain" getter="get_terrain" default="-1"> + ID of the terrain from the terrain set that the tile uses. </member> <member name="terrain_set" type="int" setter="set_terrain_set" getter="get_terrain_set" default="-1"> + ID of the terrain set that the tile uses. </member> <member name="texture_offset" type="Vector2i" setter="set_texture_offset" getter="get_texture_offset" default="Vector2i(0, 0)"> + Offsets the position of where the tile is drawn. </member> <member name="transpose" type="bool" setter="set_transpose" getter="get_transpose" default="false"> + If [code]true[/code], the tile will display transposed, i.e. with horizontal and vertical texture UVs swapped. </member> <member name="y_sort_origin" type="int" setter="set_y_sort_origin" getter="get_y_sort_origin" default="0"> + Vertical point of the tile used for determining y-sorted order. </member> <member name="z_index" type="int" setter="set_z_index" getter="get_z_index" default="0"> + Ordering index of this tile, relative to [TileMap]. </member> </members> <signals> <signal name="changed"> <description> + Emitted when any of the properties are changed. </description> </signal> </signals> diff --git a/doc/classes/Tree.xml b/doc/classes/Tree.xml index bf79821e2d..6a016c3ebd 100644 --- a/doc/classes/Tree.xml +++ b/doc/classes/Tree.xml @@ -84,6 +84,7 @@ <return type="int" /> <param index="0" name="column" type="int" /> <description> + Returns the expand ratio assigned to the column. </description> </method> <method name="get_column_title" qualifiers="const"> @@ -223,12 +224,14 @@ <return type="bool" /> <param index="0" name="column" type="int" /> <description> + Returns [code]true[/code] if the column has enabled clipping (see [method set_column_clip_content]). </description> </method> <method name="is_column_expanding" qualifiers="const"> <return type="bool" /> <param index="0" name="column" type="int" /> <description> + Returns [code]true[/code] if the column has enabled expanding (see [method set_column_expand]). </description> </method> <method name="scroll_to_item"> @@ -244,6 +247,7 @@ <param index="0" name="column" type="int" /> <param index="1" name="enable" type="bool" /> <description> + Allows to enable clipping for column's content, making the content size ignored. </description> </method> <method name="set_column_custom_minimum_width"> @@ -259,7 +263,7 @@ <param index="0" name="column" type="int" /> <param index="1" name="expand" type="bool" /> <description> - If [code]true[/code], the column will have the "Expand" flag of [Control]. Columns that have the "Expand" flag will use their "min_width" in a similar fashion to [member Control.size_flags_stretch_ratio]. + If [code]true[/code], the column will have the "Expand" flag of [Control]. Columns that have the "Expand" flag will use their expand ratio in a similar fashion to [member Control.size_flags_stretch_ratio] (see [method set_column_expand_ratio]). </description> </method> <method name="set_column_expand_ratio"> @@ -267,6 +271,7 @@ <param index="0" name="column" type="int" /> <param index="1" name="ratio" type="int" /> <description> + Sets the relative expand ratio for a column. See [method set_column_expand]. </description> </method> <method name="set_column_title"> diff --git a/doc/classes/VSlider.xml b/doc/classes/VSlider.xml index 488154106f..4bc98dea6f 100644 --- a/doc/classes/VSlider.xml +++ b/doc/classes/VSlider.xml @@ -33,7 +33,7 @@ The background of the area below the grabber. </theme_item> <theme_item name="grabber_area_highlight" data_type="style" type="StyleBox"> - The background of the area below the grabber, to the left of the grabber. + The background of the area below the grabber that displays when it's being hovered or focused. </theme_item> <theme_item name="slider" data_type="style" type="StyleBox"> The background for the whole slider. Determines the width of the [code]grabber_area[/code]. diff --git a/doc/classes/Vector2.xml b/doc/classes/Vector2.xml index 5590f82336..1cd73688ee 100644 --- a/doc/classes/Vector2.xml +++ b/doc/classes/Vector2.xml @@ -5,7 +5,8 @@ </brief_description> <description> 2-element structure that can be used to represent positions in 2D space or any other pair of numeric values. - It uses floating-point coordinates. See [Vector2i] for its integer counterpart. + It uses floating-point coordinates. By default, these floating-point values use 32-bit precision, unlike [float] which is always 64-bit. If double precision is needed, compile the engine with the option [code]float=64[/code]. + See [Vector2i] for its integer counterpart. [b]Note:[/b] In a boolean context, a Vector2 will evaluate to [code]false[/code] if it's equal to [code]Vector2(0, 0)[/code]. Otherwise, a Vector2 will always evaluate to [code]true[/code]. </description> <tutorials> @@ -85,6 +86,16 @@ Returns the aspect ratio of this vector, the ratio of [member x] to [member y]. </description> </method> + <method name="bezier_derivative" qualifiers="const"> + <return type="Vector2" /> + <param index="0" name="control_1" type="Vector2" /> + <param index="1" name="control_2" type="Vector2" /> + <param index="2" name="end" type="Vector2" /> + <param index="3" name="t" type="float" /> + <description> + Returns the derivative at the given [param t] on the [url=https://en.wikipedia.org/wiki/B%C3%A9zier_curve]Bézier curve[/url] defined by this vector and the given [param control_1], [param control_2], and [param end] points. + </description> + </method> <method name="bezier_interpolate" qualifiers="const"> <return type="Vector2" /> <param index="0" name="control_1" type="Vector2" /> @@ -92,14 +103,14 @@ <param index="2" name="end" type="Vector2" /> <param index="3" name="t" type="float" /> <description> - Returns the point at the given [param t] on the [url=https://en.wikipedia.org/wiki/B%C3%A9zier_curve]Bezier curve[/url] defined by this vector and the given [param control_1], [param control_2], and [param end] points. + Returns the point at the given [param t] on the [url=https://en.wikipedia.org/wiki/B%C3%A9zier_curve]Bézier curve[/url] defined by this vector and the given [param control_1], [param control_2], and [param end] points. </description> </method> <method name="bounce" qualifiers="const"> <return type="Vector2" /> <param index="0" name="n" type="Vector2" /> <description> - Returns the vector "bounced off" from a plane defined by the given normal. + Returns a new vector "bounced off" from a plane defined by the given normal. </description> </method> <method name="ceil" qualifiers="const"> @@ -276,7 +287,7 @@ <method name="normalized" qualifiers="const"> <return type="Vector2" /> <description> - Returns the vector scaled to unit length. Equivalent to [code]v / v.length()[/code]. + Returns a new vector scaled to unit length. Equivalent to [code]v / v.length()[/code]. </description> </method> <method name="orthogonal" qualifiers="const"> @@ -303,21 +314,21 @@ <return type="Vector2" /> <param index="0" name="b" type="Vector2" /> <description> - Returns this vector projected onto the vector [code]b[/code]. + Returns the result of projecting the vector onto the given vector [param b]. </description> </method> <method name="reflect" qualifiers="const"> <return type="Vector2" /> <param index="0" name="n" type="Vector2" /> <description> - Returns the vector reflected (i.e. mirrored, or symmetric) over a line defined by the given direction vector [param n]. + Returns the result of reflecting the vector from a line defined by the given direction vector [param n]. </description> </method> <method name="rotated" qualifiers="const"> <return type="Vector2" /> <param index="0" name="angle" type="float" /> <description> - Returns the vector rotated by [param angle] (in radians). See also [method @GlobalScope.deg_to_rad]. + Returns the result of rotating this vector by [param angle] (in radians). See also [method @GlobalScope.deg_to_rad]. </description> </method> <method name="round" qualifiers="const"> @@ -329,7 +340,7 @@ <method name="sign" qualifiers="const"> <return type="Vector2" /> <description> - Returns a new vector with each component set to one or negative one, depending on the signs of the components, or zero if the component is zero, by calling [method @GlobalScope.sign] on each component. + Returns a new vector with each component set to [code]1.0[/code] if it's positive, [code]-1.0[/code] if it's negative, and [code]0.0[/code] if it's zero. The result is identical to calling [method @GlobalScope.sign] on each component. </description> </method> <method name="slerp" qualifiers="const"> @@ -345,14 +356,14 @@ <return type="Vector2" /> <param index="0" name="n" type="Vector2" /> <description> - Returns this vector slid along a plane defined by the given normal. + Returns the result of sliding the vector along a plane defined by the given normal. </description> </method> <method name="snapped" qualifiers="const"> <return type="Vector2" /> <param index="0" name="step" type="Vector2" /> <description> - Returns this vector with each component snapped to the nearest multiple of [param step]. This can also be used to round to an arbitrary number of decimals. + Returns a new vector with each component snapped to the nearest multiple of the corresponding component in [param step]. This can also be used to round the components to an arbitrary number of decimals. </description> </method> </methods> diff --git a/doc/classes/Vector2i.xml b/doc/classes/Vector2i.xml index eab880e57f..db6bc8f237 100644 --- a/doc/classes/Vector2i.xml +++ b/doc/classes/Vector2i.xml @@ -5,7 +5,7 @@ </brief_description> <description> 2-element structure that can be used to represent positions in 2D space or any other pair of numeric values. - It uses integer coordinates and is therefore preferable to [Vector2] when exact precision is required. + It uses integer coordinates and is therefore preferable to [Vector2] when exact precision is required. Note that the values are limited to 32 bits, and unlike [Vector2] this cannot be configured with an engine build option. Use [int] or [PackedInt64Array] if 64-bit values are needed. [b]Note:[/b] In a boolean context, a Vector2i will evaluate to [code]false[/code] if it's equal to [code]Vector2i(0, 0)[/code]. Otherwise, a Vector2i will always evaluate to [code]true[/code]. </description> <tutorials> @@ -92,7 +92,14 @@ <method name="sign" qualifiers="const"> <return type="Vector2i" /> <description> - Returns a new vector with each component set to one or negative one, depending on the signs of the components, or zero if the component is zero, by calling [method @GlobalScope.sign] on each component. + Returns a new vector with each component set to [code]1[/code] if it's positive, [code]-1[/code] if it's negative, and [code]0[/code] if it's zero. The result is identical to calling [method @GlobalScope.sign] on each component. + </description> + </method> + <method name="snapped" qualifiers="const"> + <return type="Vector2i" /> + <param index="0" name="step" type="Vector2i" /> + <description> + Returns a new vector with each component snapped to the closest multiple of the corresponding component in [param step]. </description> </method> </methods> diff --git a/doc/classes/Vector3.xml b/doc/classes/Vector3.xml index 1a2cdfe10e..1d7eda6bb9 100644 --- a/doc/classes/Vector3.xml +++ b/doc/classes/Vector3.xml @@ -5,7 +5,8 @@ </brief_description> <description> 3-element structure that can be used to represent positions in 3D space or any other triplet of numeric values. - It uses floating-point coordinates. See [Vector3i] for its integer counterpart. + It uses floating-point coordinates. By default, these floating-point values use 32-bit precision, unlike [float] which is always 64-bit. If double precision is needed, compile the engine with the option [code]float=64[/code]. + See [Vector3i] for its integer counterpart. [b]Note:[/b] In a boolean context, a Vector3 will evaluate to [code]false[/code] if it's equal to [code]Vector3(0, 0, 0)[/code]. Otherwise, a Vector3 will always evaluate to [code]true[/code]. </description> <tutorials> @@ -61,6 +62,16 @@ Returns the unsigned minimum angle to the given vector, in radians. </description> </method> + <method name="bezier_derivative" qualifiers="const"> + <return type="Vector3" /> + <param index="0" name="control_1" type="Vector3" /> + <param index="1" name="control_2" type="Vector3" /> + <param index="2" name="end" type="Vector3" /> + <param index="3" name="t" type="float" /> + <description> + Returns the derivative at the given [param t] on the [url=https://en.wikipedia.org/wiki/B%C3%A9zier_curve]Bézier curve[/url] defined by this vector and the given [param control_1], [param control_2], and [param end] points. + </description> + </method> <method name="bezier_interpolate" qualifiers="const"> <return type="Vector3" /> <param index="0" name="control_1" type="Vector3" /> @@ -68,7 +79,7 @@ <param index="2" name="end" type="Vector3" /> <param index="3" name="t" type="float" /> <description> - Returns the point at the given [param t] on the [url=https://en.wikipedia.org/wiki/B%C3%A9zier_curve]Bezier curve[/url] defined by this vector and the given [param control_1], [param control_2], and [param end] points. + Returns the point at the given [param t] on the [url=https://en.wikipedia.org/wiki/B%C3%A9zier_curve]Bézier curve[/url] defined by this vector and the given [param control_1], [param control_2], and [param end] points. </description> </method> <method name="bounce" qualifiers="const"> @@ -287,14 +298,14 @@ <return type="Vector3" /> <param index="0" name="b" type="Vector3" /> <description> - Returns this vector projected onto the vector [param b]. + Returns the result of projecting the vector onto the given vector [param b]. </description> </method> <method name="reflect" qualifiers="const"> <return type="Vector3" /> <param index="0" name="n" type="Vector3" /> <description> - Returns this vector reflected from a plane defined by the given normal. + Returns the result of reflecting the vector from a plane defined by the given normal [param n]. </description> </method> <method name="rotated" qualifiers="const"> @@ -302,7 +313,7 @@ <param index="0" name="axis" type="Vector3" /> <param index="1" name="angle" type="float" /> <description> - Rotates this vector around a given axis by [param angle] (in radians). The axis must be a normalized vector. + Returns the result of rotating this vector around a given axis by [param angle] (in radians). The axis must be a normalized vector. See also [method @GlobalScope.deg_to_rad]. </description> </method> <method name="round" qualifiers="const"> @@ -314,7 +325,7 @@ <method name="sign" qualifiers="const"> <return type="Vector3" /> <description> - Returns a new vector with each component set to one or negative one, depending on the signs of the components, or zero if the component is zero, by calling [method @GlobalScope.sign] on each component. + Returns a new vector with each component set to [code]1.0[/code] if it's positive, [code]-1.0[/code] if it's negative, and [code]0.0[/code] if it's zero. The result is identical to calling [method @GlobalScope.sign] on each component. </description> </method> <method name="signed_angle_to" qualifiers="const"> @@ -338,14 +349,14 @@ <return type="Vector3" /> <param index="0" name="n" type="Vector3" /> <description> - Returns this vector slid along a plane defined by the given normal. + Returns a new vector slid along a plane defined by the given normal. </description> </method> <method name="snapped" qualifiers="const"> <return type="Vector3" /> <param index="0" name="step" type="Vector3" /> <description> - Returns this vector with each component snapped to the nearest multiple of [param step]. This can also be used to round to an arbitrary number of decimals. + Returns a new vector with each component snapped to the nearest multiple of the corresponding component in [param step]. This can also be used to round the components to an arbitrary number of decimals. </description> </method> </methods> diff --git a/doc/classes/Vector3i.xml b/doc/classes/Vector3i.xml index 1c2a033f7a..5c6dc3c1c5 100644 --- a/doc/classes/Vector3i.xml +++ b/doc/classes/Vector3i.xml @@ -5,7 +5,7 @@ </brief_description> <description> 3-element structure that can be used to represent positions in 3D space or any other triplet of numeric values. - It uses integer coordinates and is therefore preferable to [Vector3] when exact precision is required. + It uses integer coordinates and is therefore preferable to [Vector3] when exact precision is required. Note that the values are limited to 32 bits, and unlike [Vector3] this cannot be configured with an engine build option. Use [int] or [PackedInt64Array] if 64-bit values are needed. [b]Note:[/b] In a boolean context, a Vector3i will evaluate to [code]false[/code] if it's equal to [code]Vector3i(0, 0, 0)[/code]. Otherwise, a Vector3i will always evaluate to [code]true[/code]. </description> <tutorials> @@ -87,7 +87,14 @@ <method name="sign" qualifiers="const"> <return type="Vector3i" /> <description> - Returns the vector with each component set to one or negative one, depending on the signs of the components. + Returns a new vector with each component set to [code]1[/code] if it's positive, [code]-1[/code] if it's negative, and [code]0[/code] if it's zero. The result is identical to calling [method @GlobalScope.sign] on each component. + </description> + </method> + <method name="snapped" qualifiers="const"> + <return type="Vector3i" /> + <param index="0" name="step" type="Vector3i" /> + <description> + Returns a new vector with each component snapped to the closest multiple of the corresponding component in [param step]. </description> </method> </methods> diff --git a/doc/classes/Vector4.xml b/doc/classes/Vector4.xml index 662d0bce3a..d15ae35b59 100644 --- a/doc/classes/Vector4.xml +++ b/doc/classes/Vector4.xml @@ -5,7 +5,8 @@ </brief_description> <description> 4-element structure that can be used to represent any quadruplet of numeric values. - It uses floating-point coordinates. See [Vector4i] for its integer counterpart. + It uses floating-point coordinates. By default, these floating-point values use 32-bit precision, unlike [float] which is always 64-bit. If double precision is needed, compile the engine with the option [code]float=64[/code]. + See [Vector4i] for its integer counterpart. [b]Note:[/b] In a boolean context, a Vector4 will evaluate to [code]false[/code] if it's equal to [code]Vector4(0, 0, 0, 0)[/code]. Otherwise, a Vector4 will always evaluate to [code]true[/code]. </description> <tutorials> @@ -189,21 +190,21 @@ <method name="normalized" qualifiers="const"> <return type="Vector4" /> <description> - Returns the vector scaled to unit length. Equivalent to [code]v / v.length()[/code]. + Returns the result of scaling the vector to unit length. Equivalent to [code]v / v.length()[/code]. </description> </method> <method name="posmod" qualifiers="const"> <return type="Vector4" /> <param index="0" name="mod" type="float" /> <description> - Returns a vector composed of the [method @GlobalScope.fposmod] of this vector's components and [param mod]. + Returns a new vector composed of the [method @GlobalScope.fposmod] of this vector's components and [param mod]. </description> </method> <method name="posmodv" qualifiers="const"> <return type="Vector4" /> <param index="0" name="modv" type="Vector4" /> <description> - Returns a vector composed of the [method @GlobalScope.fposmod] of this vector's components and [param modv]'s components. + Returns a new vector composed of the [method @GlobalScope.fposmod] of this vector's components and [param modv]'s components. </description> </method> <method name="round" qualifiers="const"> @@ -215,14 +216,14 @@ <method name="sign" qualifiers="const"> <return type="Vector4" /> <description> - Returns a new vector with each component set to one or negative one, depending on the signs of the components, or zero if the component is zero, by calling [method @GlobalScope.sign] on each component. + Returns a new vector with each component set to [code]1.0[/code] if it's positive, [code]-1.0[/code] if it's negative, and [code]0.0[/code] if it's zero. The result is identical to calling [method @GlobalScope.sign] on each component. </description> </method> <method name="snapped" qualifiers="const"> <return type="Vector4" /> <param index="0" name="step" type="Vector4" /> <description> - Returns this vector with each component snapped to the nearest multiple of [param step]. This can also be used to round to an arbitrary number of decimals. + Returns a new vector with each component snapped to the nearest multiple of the corresponding component in [param step]. This can also be used to round the components to an arbitrary number of decimals. </description> </method> </methods> diff --git a/doc/classes/Vector4i.xml b/doc/classes/Vector4i.xml index e9ac5b9475..95797df90a 100644 --- a/doc/classes/Vector4i.xml +++ b/doc/classes/Vector4i.xml @@ -5,7 +5,7 @@ </brief_description> <description> 4-element structure that can be used to represent 4D grid coordinates or sets of integers. - It uses integer coordinates. See [Vector4] for its floating-point counterpart. + It uses integer coordinates and is therefore preferable to [Vector4] when exact precision is required. Note that the values are limited to 32 bits, and unlike [Vector4] this cannot be configured with an engine build option. Use [int] or [PackedInt64Array] if 64-bit values are needed. </description> <tutorials> </tutorials> @@ -83,7 +83,14 @@ <method name="sign" qualifiers="const"> <return type="Vector4i" /> <description> - Returns a new vector with each component set to one or negative one, depending on the signs of the components, or zero if the component is zero, by calling [method @GlobalScope.sign] on each component. + Returns a new vector with each component set to [code]1[/code] if it's positive, [code]-1[/code] if it's negative, and [code]0[/code] if it's zero. The result is identical to calling [method @GlobalScope.sign] on each component. + </description> + </method> + <method name="snapped" qualifiers="const"> + <return type="Vector4i" /> + <param index="0" name="step" type="Vector4i" /> + <description> + Returns a new vector with each component snapped to the closest multiple of the corresponding component in [param step]. </description> </method> </methods> diff --git a/doc/classes/Viewport.xml b/doc/classes/Viewport.xml index 78013a8f4b..236d34383f 100644 --- a/doc/classes/Viewport.xml +++ b/doc/classes/Viewport.xml @@ -343,6 +343,19 @@ </member> <member name="vrs_texture" type="Texture2D" setter="set_vrs_texture" getter="get_vrs_texture"> Texture to use when [member vrs_mode] is set to [constant Viewport.VRS_TEXTURE]. + The texture [i]must[/i] use a lossless compression format so that colors can be matched precisely. The following VRS densities are mapped to various colors, with brighter colors representing a lower level of shading precision: + [codeblock] + - 1x1 = rgb(0, 0, 0) - #000000 + - 1x2 = rgb(0, 85, 0) - #005500 + - 2x1 = rgb(85, 0, 0) - #550000 + - 2x2 = rgb(85, 85, 0) - #555500 + - 2x4 = rgb(85, 170, 0) - #55aa00 + - 4x2 = rgb(170, 85, 0) - #aa5500 + - 4x4 = rgb(170, 170, 0) - #aaaa00 + - 4x8 = rgb(170, 255, 0) - #aaff00 - Not supported on most hardware + - 8x4 = rgb(255, 170, 0) - #ffaa00 - Not supported on most hardware + - 8x8 = rgb(255, 255, 0) - #ffff00 - Not supported on most hardware + [/codeblock] </member> <member name="world_2d" type="World2D" setter="set_world_2d" getter="get_world_2d"> The custom [World2D] which can be used as 2D environment source. diff --git a/doc/tools/make_rst.py b/doc/tools/make_rst.py index 9fb60511ae..8960c66acc 100755 --- a/doc/tools/make_rst.py +++ b/doc/tools/make_rst.py @@ -240,7 +240,7 @@ class State: enum_def = class_def.enums[enum] else: - enum_def = EnumDef(enum, is_bitfield) + enum_def = EnumDef(enum, TypeName("int", enum), is_bitfield) class_def.enums[enum] = enum_def enum_def.values[constant_name] = constant_def @@ -458,9 +458,10 @@ class ConstantDef(DefinitionBase): class EnumDef(DefinitionBase): - def __init__(self, name: str, bitfield: bool) -> None: + def __init__(self, name: str, type_name: TypeName, bitfield: bool) -> None: super().__init__("enum", name) + self.type_name = type_name self.values: OrderedDict[str, ConstantDef] = OrderedDict() self.is_bitfield = bitfield @@ -754,7 +755,8 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: f.write(f".. _class_{class_name}:\n\n") f.write(make_heading(class_name, "=", False)) - # Inheritance tree + ### INHERITANCE TREE ### + # Ascendants if class_def.inherits: inherits = class_def.inherits.strip() @@ -788,6 +790,8 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: f.write(make_type(child, state)) f.write("\n\n") + ### INTRODUCTION ### + has_description = False # Brief description @@ -800,7 +804,9 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: if class_def.description is not None and class_def.description.strip() != "": has_description = True + f.write(".. rst-class:: classref-introduction-group\n\n") f.write(make_heading("Description", "-")) + f.write(f"{format_text_block(class_def.description.strip(), class_def, state)}\n\n") if not has_description: @@ -814,14 +820,22 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: # Online tutorials if len(class_def.tutorials) > 0: + f.write(".. rst-class:: classref-introduction-group\n\n") f.write(make_heading("Tutorials", "-")) + for url, title in class_def.tutorials: f.write(f"- {make_link(url, title)}\n\n") - # Properties overview + ### REFERENCE TABLES ### + + # Reused container for reference tables. ml: List[Tuple[Optional[str], ...]] = [] + + # Properties reference table if len(class_def.properties) > 0: + f.write(".. rst-class:: classref-reftable-group\n\n") f.write(make_heading("Properties", "-")) + ml = [] for property_def in class_def.properties.values(): type_rst = property_def.type_name.to_rst(state) @@ -833,76 +847,108 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: else: ref = f":ref:`{property_def.name}<class_{class_name}_property_{property_def.name}>`" ml.append((type_rst, ref, default)) + format_table(f, ml, True) - # Constructors, Methods, Operators overview + # Constructors, Methods, Operators reference tables if len(class_def.constructors) > 0: + f.write(".. rst-class:: classref-reftable-group\n\n") f.write(make_heading("Constructors", "-")) + ml = [] for method_list in class_def.constructors.values(): for m in method_list: ml.append(make_method_signature(class_def, m, "constructor", state)) + format_table(f, ml) if len(class_def.methods) > 0: + f.write(".. rst-class:: classref-reftable-group\n\n") f.write(make_heading("Methods", "-")) + ml = [] for method_list in class_def.methods.values(): for m in method_list: ml.append(make_method_signature(class_def, m, "method", state)) + format_table(f, ml) if len(class_def.operators) > 0: + f.write(".. rst-class:: classref-reftable-group\n\n") f.write(make_heading("Operators", "-")) + ml = [] for method_list in class_def.operators.values(): for m in method_list: ml.append(make_method_signature(class_def, m, "operator", state)) + format_table(f, ml) - # Theme properties + # Theme properties reference table if len(class_def.theme_items) > 0: + f.write(".. rst-class:: classref-reftable-group\n\n") f.write(make_heading("Theme Properties", "-")) - pl: List[Tuple[Optional[str], ...]] = [] + + ml = [] for theme_item_def in class_def.theme_items.values(): ref = f":ref:`{theme_item_def.name}<class_{class_name}_theme_{theme_item_def.data_name}_{theme_item_def.name}>`" - pl.append((theme_item_def.type_name.to_rst(state), ref, theme_item_def.default_value)) - format_table(f, pl, True) + ml.append((theme_item_def.type_name.to_rst(state), ref, theme_item_def.default_value)) + + format_table(f, ml, True) - # Signals + ### DETAILED DESCRIPTIONS ### + + # Signal descriptions if len(class_def.signals) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") f.write(make_heading("Signals", "-")) + index = 0 for signal in class_def.signals.values(): if index != 0: - f.write("----\n\n") + f.write(make_separator()) + + # Create signal signature and anchor point. f.write(f".. _class_{class_name}_signal_{signal.name}:\n\n") + f.write(".. rst-class:: classref-signal\n\n") + _, signature = make_method_signature(class_def, signal, "", state) - f.write(f"- {signature}\n\n") + f.write(f"{signature}\n\n") + + # Add signal description, or a call to action if it's missing. if signal.description is not None and signal.description.strip() != "": f.write(f"{format_text_block(signal.description.strip(), signal, state)}\n\n") + else: + f.write(".. container:: contribute\n\n\t") + f.write( + translate( + "There is currently no description for this signal. Please help us by :ref:`contributing one <doc_updating_the_class_reference>`!" + ) + + "\n\n" + ) index += 1 - # Enums + # Enumeration descriptions if len(class_def.enums) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") f.write(make_heading("Enumerations", "-")) + index = 0 for e in class_def.enums.values(): if index != 0: - f.write("----\n\n") + f.write(make_separator()) + + # Create enumeration signature and anchor point. f.write(f".. _enum_{class_name}_{e.name}:\n\n") - # Sphinx seems to divide the bullet list into individual <ul> tags if we weave the labels into it. - # As such I'll put them all above the list. Won't be perfect but better than making the list visually broken. - # As to why I'm not modifying the reference parser to directly link to the _enum label: - # If somebody gets annoyed enough to fix it, all existing references will magically improve. - for value in e.values.values(): - f.write(f".. _class_{class_name}_constant_{value.name}:\n\n") + f.write(".. rst-class:: classref-enumeration\n\n") if e.is_bitfield: f.write(f"flags **{e.name}**:\n\n") @@ -910,45 +956,66 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: f.write(f"enum **{e.name}**:\n\n") for value in e.values.values(): - f.write(f"- **{value.name}** = **{value.value}**") + # Also create signature and anchor point for each enum constant. + + f.write(f".. _class_{class_name}_constant_{value.name}:\n\n") + f.write(".. rst-class:: classref-enumeration-constant\n\n") + + f.write(f"{e.type_name.to_rst(state)} **{value.name}** = ``{value.value}``\n\n") + + # Add enum constant description. + if value.text is not None and value.text.strip() != "": - # If value.text contains a bullet point list, each entry needs additional indentation - f.write(f" --- {indent_bullets(format_text_block(value.text.strip(), value, state))}") + f.write(f"{format_text_block(value.text.strip(), value, state)}") f.write("\n\n") index += 1 - # Constants + # Constant descriptions if len(class_def.constants) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") f.write(make_heading("Constants", "-")) - # Sphinx seems to divide the bullet list into individual <ul> tags if we weave the labels into it. - # As such I'll put them all above the list. Won't be perfect but better than making the list visually broken. + for constant in class_def.constants.values(): + # Create constant signature and anchor point. + f.write(f".. _class_{class_name}_constant_{constant.name}:\n\n") + f.write(".. rst-class:: classref-constant\n\n") + + f.write(f"**{constant.name}** = ``{constant.value}``\n\n") + + # Add enum constant description. - for constant in class_def.constants.values(): - f.write(f"- **{constant.name}** = **{constant.value}**") if constant.text is not None and constant.text.strip() != "": - f.write(f" --- {format_text_block(constant.text.strip(), constant, state)}") + f.write(f"{format_text_block(constant.text.strip(), constant, state)}") f.write("\n\n") - # Annotations + # Annotation descriptions if len(class_def.annotations) > 0: + f.write(make_separator(True)) f.write(make_heading("Annotations", "-")) + index = 0 for method_list in class_def.annotations.values(): # type: ignore for i, m in enumerate(method_list): if index != 0: - f.write("----\n\n") + f.write(make_separator()) + + # Create annotation signature and anchor point. if i == 0: f.write(f".. _class_{class_name}_annotation_{m.name}:\n\n") + f.write(".. rst-class:: classref-annotation\n\n") + _, signature = make_method_signature(class_def, m, "", state) - f.write(f"- {signature}\n\n") + f.write(f"{signature}\n\n") + + # Add annotation description, or a call to action if it's missing. if m.description is not None and m.description.strip() != "": f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n") @@ -965,7 +1032,10 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: # Property descriptions if any(not p.overrides for p in class_def.properties.values()) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") f.write(make_heading("Property Descriptions", "-")) + index = 0 for property_def in class_def.properties.values(): @@ -973,22 +1043,36 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: continue if index != 0: - f.write("----\n\n") + f.write(make_separator()) + + # Create property signature and anchor point. f.write(f".. _class_{class_name}_property_{property_def.name}:\n\n") - f.write(f"- {property_def.type_name.to_rst(state)} **{property_def.name}**\n\n") + f.write(".. rst-class:: classref-property\n\n") - info: List[Tuple[Optional[str], ...]] = [] - # Not using translate() for now as it breaks table formatting. + property_default = "" if property_def.default_value is not None: - info.append(("*Default*", property_def.default_value)) + property_default = f" = {property_def.default_value}" + f.write(f"{property_def.type_name.to_rst(state)} **{property_def.name}**{property_default}\n\n") + + # Create property setter and getter records. + + property_setget = "" + if property_def.setter is not None and not property_def.setter.startswith("_"): - info.append(("*Setter*", f"{property_def.setter}(value)")) + property_setter = make_setter_signature(class_def, property_def, state) + property_setget += f"- {property_setter}\n" + if property_def.getter is not None and not property_def.getter.startswith("_"): - info.append(("*Getter*", f"{property_def.getter}()")) + property_getter = make_getter_signature(class_def, property_def, state) + property_setget += f"- {property_getter}\n" + + if property_setget != "": + f.write(".. rst-class:: classref-property-setget\n\n") + f.write(property_setget) + f.write("\n") - if len(info) > 0: - format_table(f, info) + # Add property description, or a call to action if it's missing. if property_def.text is not None and property_def.text.strip() != "": f.write(f"{format_text_block(property_def.text.strip(), property_def, state)}\n\n") @@ -1005,19 +1089,28 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: # Constructor, Method, Operator descriptions if len(class_def.constructors) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") f.write(make_heading("Constructor Descriptions", "-")) + index = 0 for method_list in class_def.constructors.values(): for i, m in enumerate(method_list): if index != 0: - f.write("----\n\n") + f.write(make_separator()) + + # Create constructor signature and anchor point. if i == 0: f.write(f".. _class_{class_name}_constructor_{m.name}:\n\n") + f.write(".. rst-class:: classref-constructor\n\n") + ret_type, signature = make_method_signature(class_def, m, "", state) - f.write(f"- {ret_type} {signature}\n\n") + f.write(f"{ret_type} {signature}\n\n") + + # Add constructor description, or a call to action if it's missing. if m.description is not None and m.description.strip() != "": f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n") @@ -1033,19 +1126,28 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: index += 1 if len(class_def.methods) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") f.write(make_heading("Method Descriptions", "-")) + index = 0 for method_list in class_def.methods.values(): for i, m in enumerate(method_list): if index != 0: - f.write("----\n\n") + f.write(make_separator()) + + # Create method signature and anchor point. if i == 0: f.write(f".. _class_{class_name}_method_{m.name}:\n\n") + f.write(".. rst-class:: classref-method\n\n") + ret_type, signature = make_method_signature(class_def, m, "", state) - f.write(f"- {ret_type} {signature}\n\n") + f.write(f"{ret_type} {signature}\n\n") + + # Add method description, or a call to action if it's missing. if m.description is not None and m.description.strip() != "": f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n") @@ -1061,21 +1163,31 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: index += 1 if len(class_def.operators) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") f.write(make_heading("Operator Descriptions", "-")) + index = 0 for method_list in class_def.operators.values(): for i, m in enumerate(method_list): if index != 0: - f.write("----\n\n") + f.write(make_separator()) - if i == 0: - f.write( - f".. _class_{class_name}_operator_{sanitize_operator_name(m.name, state)}_{m.return_type.type_name}:\n\n" - ) + # Create operator signature and anchor point. + + operator_anchor = f".. _class_{class_name}_operator_{sanitize_operator_name(m.name, state)}" + for parameter in m.parameters: + operator_anchor += f"_{parameter.type_name.type_name}" + operator_anchor += f":\n\n" + f.write(operator_anchor) + + f.write(".. rst-class:: classref-operator\n\n") ret_type, signature = make_method_signature(class_def, m, "", state) - f.write(f"- {ret_type} {signature}\n\n") + f.write(f"{ret_type} {signature}\n\n") + + # Add operator description, or a call to action if it's missing. if m.description is not None and m.description.strip() != "": f.write(f"{format_text_block(m.description.strip(), m, state)}\n\n") @@ -1092,23 +1204,27 @@ def make_rst_class(class_def: ClassDef, state: State, dry_run: bool, output_dir: # Theme property descriptions if len(class_def.theme_items) > 0: + f.write(make_separator(True)) + f.write(".. rst-class:: classref-descriptions-group\n\n") f.write(make_heading("Theme Property Descriptions", "-")) + index = 0 for theme_item_def in class_def.theme_items.values(): if index != 0: - f.write("----\n\n") + f.write(make_separator()) + + # Create theme property signature and anchor point. f.write(f".. _class_{class_name}_theme_{theme_item_def.data_name}_{theme_item_def.name}:\n\n") - f.write(f"- {theme_item_def.type_name.to_rst(state)} **{theme_item_def.name}**\n\n") + f.write(".. rst-class:: classref-themeproperty\n\n") - info = [] + theme_item_default = "" if theme_item_def.default_value is not None: - # Not using translate() for now as it breaks table formatting. - info.append(("*Default*", theme_item_def.default_value)) + theme_item_default = f" = {theme_item_def.default_value}" + f.write(f"{theme_item_def.type_name.to_rst(state)} **{theme_item_def.name}**{theme_item_default}\n\n") - if len(info) > 0: - format_table(f, info) + # Add theme property description, or a call to action if it's missing. if theme_item_def.text is not None and theme_item_def.text.strip() != "": f.write(f"{format_text_block(theme_item_def.text.strip(), theme_item_def, state)}\n\n") @@ -1179,7 +1295,10 @@ def make_method_signature( if isinstance(definition, MethodDef) and ref_type != "": if ref_type == "operator": op_name = definition.name.replace("<", "\\<") # So operator "<" gets correctly displayed. - out += f":ref:`{op_name}<class_{class_def.name}_{ref_type}_{sanitize_operator_name(definition.name, state)}_{definition.return_type.type_name}>` " + out += f":ref:`{op_name}<class_{class_def.name}_{ref_type}_{sanitize_operator_name(definition.name, state)}" + for parameter in definition.parameters: + out += f"_{parameter.type_name.type_name}" + out += f">` " else: out += f":ref:`{definition.name}<class_{class_def.name}_{ref_type}_{definition.name}>` " else: @@ -1214,6 +1333,39 @@ def make_method_signature( return ret_type, out +def make_setter_signature(class_def: ClassDef, property_def: PropertyDef, state: State) -> str: + if property_def.setter is None: + return "" + + # If setter is a method available as a method definition, we use that. + if property_def.setter in class_def.methods: + setter = class_def.methods[property_def.setter][0] + # Otherwise we fake it with the information we have available. + else: + setter_params: List[ParameterDef] = [] + setter_params.append(ParameterDef("value", property_def.type_name, None)) + setter = MethodDef(property_def.setter, TypeName("void"), setter_params, None, None) + + ret_type, signature = make_method_signature(class_def, setter, "", state) + return f"{ret_type} {signature}" + + +def make_getter_signature(class_def: ClassDef, property_def: PropertyDef, state: State) -> str: + if property_def.getter is None: + return "" + + # If getter is a method available as a method definition, we use that. + if property_def.getter in class_def.methods: + getter = class_def.methods[property_def.getter][0] + # Otherwise we fake it with the information we have available. + else: + getter_params: List[ParameterDef] = [] + getter = MethodDef(property_def.getter, property_def.type_name, getter_params, None, None) + + ret_type, signature = make_method_signature(class_def, getter, "", state) + return f"{ret_type} {signature}" + + def make_heading(title: str, underline: str, l10n: bool = True) -> str: if l10n: new_title = translate(title) @@ -1245,6 +1397,14 @@ def make_footer() -> str: ) +def make_separator(section_level: bool = False) -> str: + separator_class = "item" + if section_level: + separator_class = "section" + + return f".. rst-class:: classref-{separator_class}-separator\n\n----\n\n" + + def make_link(url: str, title: str) -> str: match = GODOT_DOCS_PATTERN.search(url) if match: @@ -1407,8 +1567,8 @@ def format_text_block( # Tag is a reference to a class. if tag_text in state.classes: if tag_text == state.current_class: - # Don't create a link to the same class, format it as inline code. - tag_text = f"``{tag_text}``" + # Don't create a link to the same class, format it as strong emphasis. + tag_text = f"**{tag_text}**" else: tag_text = make_type(tag_text, state) escape_pre = True @@ -1870,6 +2030,11 @@ def format_table(f: TextIO, data: List[Tuple[Optional[str], ...]], remove_empty_ if len(data) == 0: return + f.write(".. table::\n") + f.write(" :widths: auto\n\n") + + # Calculate the width of each column first, we will use this information + # to properly format RST-style tables. column_sizes = [0] * len(data[0]) for row in data: for i, text in enumerate(row): @@ -1877,14 +2042,21 @@ def format_table(f: TextIO, data: List[Tuple[Optional[str], ...]], remove_empty_ if text_length > column_sizes[i]: column_sizes[i] = text_length + # Each table row is wrapped in two separators, consecutive rows share the same separator. + # All separators, or rather borders, have the same shape and content. We compose it once, + # then reuse it. + sep = "" for size in column_sizes: if size == 0 and remove_empty_columns: continue - sep += "+" + "-" * (size + 2) + sep += "+" + "-" * (size + 2) # Content of each cell is padded by 1 on each side. sep += "+\n" - f.write(sep) + # Draw the first separator. + f.write(f" {sep}") + + # Draw each row and close it with a separator. for row in data: row_text = "|" for i, text in enumerate(row): @@ -1892,8 +2064,10 @@ def format_table(f: TextIO, data: List[Tuple[Optional[str], ...]], remove_empty_ continue row_text += f' {(text or "").ljust(column_sizes[i])} |' row_text += "\n" - f.write(row_text) - f.write(sep) + + f.write(f" {row_text}") + f.write(f" {sep}") + f.write("\n") @@ -1955,24 +2129,5 @@ def sanitize_operator_name(dirty_name: str, state: State) -> str: return clear_name -def indent_bullets(text: str) -> str: - # Take the text and check each line for a bullet point represented by "-". - # Where found, indent the given line by a further "\t". - # Used to properly indent bullet points contained in the description for enum values. - # Ignore the first line - text will be prepended to it so bullet points wouldn't work anyway. - bullet_points = "-" - - lines = text.splitlines(keepends=True) - for line_index, line in enumerate(lines[1:], start=1): - pos = 0 - while pos < len(line) and line[pos] == "\t": - pos += 1 - - if pos < len(line) and line[pos] in bullet_points: - lines[line_index] = f"{line[:pos]}\t{line[pos:]}" - - return "".join(lines) - - if __name__ == "__main__": main() |