diff options
Diffstat (limited to 'doc/classes')
161 files changed, 1618 insertions, 869 deletions
diff --git a/doc/classes/@GlobalScope.xml b/doc/classes/@GlobalScope.xml index 0d6524ccbe..ed7bdc07fc 100644 --- a/doc/classes/@GlobalScope.xml +++ b/doc/classes/@GlobalScope.xml @@ -803,7 +803,8 @@ Returns the result of [param base] raised to the power of [param exp]. In GDScript, this is the equivalent of the [code]**[/code] operator. [codeblock] - pow(2, 5) # Returns 32 + pow(2, 5) # Returns 32.0 + pow(4, 1.5) # Returns 8.0 [/codeblock] </description> </method> @@ -1139,7 +1140,7 @@ <return type="float" /> <param index="0" name="x" type="float" /> <description> - 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. + 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 [param x] is zero. [codeblock] sign(-6.5) # Returns -1.0 sign(0.0) # Returns 0.0 @@ -1271,7 +1272,13 @@ <method name="str" qualifiers="vararg"> <return type="String" /> <description> - Converts one or more arguments of any [Variant] type to [String] in the best way possible. + Converts one or more arguments of any [Variant] type to a [String] in the best way possible. + [codeblock] + var a = [10, 20, 30] + var b = str(a) + print(len(a)) # Prints 3 (the number of elements in the array). + print(len(b)) # Prints 12 (the length of the string "[10, 20, 30]"). + [/codeblock] </description> </method> <method name="str_to_var"> @@ -1281,14 +1288,14 @@ Converts a formatted [param string] that was returned by [method var_to_str] to the original [Variant]. [codeblocks] [gdscript] - var a = '{ "a": 1, "b": 2 }' # a is a String - var b = str_to_var(a) # b is a Dictionary - print(b["a"]) # Prints 1 + var data = '{ "a": 1, "b": 2 }' # data is a String + var dict = str_to_var(data) # dict is a Dictionary + print(dict["a"]) # Prints 1 [/gdscript] [csharp] - string a = "{ \"a\": 1, \"b\": 2 }"; // a is a string - var b = GD.StrToVar(a).AsGodotDictionary(); // b is a Dictionary - GD.Print(b["a"]); // Prints 1 + string data = "{ \"a\": 1, \"b\": 2 }"; // data is a string + var dict = GD.StrToVar(data).AsGodotDictionary(); // dict is a Dictionary + GD.Print(dict["a"]); // Prints 1 [/csharp] [/codeblocks] </description> @@ -2266,7 +2273,7 @@ Command (on macOS) or Meta/Windows key mask. </constant> <constant name="KEY_MASK_CTRL" value="268435456" enum="KeyModifierMask" is_bitfield="true"> - Ctrl key mask. + Control key mask. </constant> <constant name="KEY_MASK_KPAD" value="536870912" enum="KeyModifierMask" is_bitfield="true"> Keypad key mask. @@ -2287,10 +2294,10 @@ Middle mouse button. </constant> <constant name="MOUSE_BUTTON_WHEEL_UP" value="4" enum="MouseButton"> - Mouse wheel up. + Mouse wheel scrolling up. </constant> <constant name="MOUSE_BUTTON_WHEEL_DOWN" value="5" enum="MouseButton"> - Mouse wheel down. + Mouse wheel scrolling down. </constant> <constant name="MOUSE_BUTTON_WHEEL_LEFT" value="6" enum="MouseButton"> Mouse wheel left button (only present on some mice). @@ -2648,7 +2655,7 @@ </constant> <constant name="PROPERTY_HINT_ENUM" value="2" enum="PropertyHint"> Hints that an [int] or [String] property is an enumerated value to pick in a list specified via a hint string. - The hint string is a comma separated list of names such as [code]"Hello,Something,Else"[/code]. Whitespaces are [b]not[/b] removed from either end of a name. For integer and float properties, the first name in the list has value 0, the next 1, and so on. Explicit values can also be specified by appending [code]:integer[/code] to the name, e.g. [code]"Zero,One,Three:3,Four,Six:6"[/code]. + The hint string is a comma separated list of names such as [code]"Hello,Something,Else"[/code]. Whitespaces are [b]not[/b] removed from either end of a name. For integer properties, the first name in the list has value 0, the next 1, and so on. Explicit values can also be specified by appending [code]:integer[/code] to the name, e.g. [code]"Zero,One,Three:3,Four,Six:6"[/code]. </constant> <constant name="PROPERTY_HINT_ENUM_SUGGESTION" value="3" enum="PropertyHint"> Hints that a [String] property can be an enumerated value to pick in a list specified via a hint string such as [code]"Hello,Something,Else"[/code]. @@ -2661,7 +2668,10 @@ Hints that a vector property should allow its components to be linked. For example, this allows [member Vector2.x] and [member Vector2.y] to be edited together. </constant> <constant name="PROPERTY_HINT_FLAGS" value="6" enum="PropertyHint"> - Hints that an [int] property is a bitmask with named bit flags. For example, to allow toggling bits 0, 1, 2 and 4, the hint could be something like [code]"Bit0,Bit1,Bit2,,Bit4"[/code]. + Hints that an [int] property is a bitmask with named bit flags. + The hint string is a comma separated list of names such as [code]"Bit0,Bit1,Bit2,Bit3"[/code]. Whitespaces are [b]not[/b] removed from either end of a name. The first name in the list has value 1, the next 2, then 4, 8, 16 and so on. Explicit values can also be specified by appending [code]:integer[/code] to the name, e.g. [code]"A:4,B:8,C:16"[/code]. You can also combine several flags ([code]"A:4,B:8,AB:12,C:16"[/code]). + [b]Note:[/b] A flag value must be at least [code]1[/code] and at most [code]2 ** 32 - 1[/code]. + [b]Note:[/b] Unlike [constant PROPERTY_HINT_ENUM], the previous explicit value is not taken into account. For the hint [code]"A:16,B,C"[/code], A is 16, B is 2, C is 4. </constant> <constant name="PROPERTY_HINT_LAYERS_2D_RENDER" value="7" enum="PropertyHint"> Hints that an [int] property is a bitmask using the optionally named 2D render layers. @@ -2751,6 +2761,7 @@ Hints that a string property is a password, and every character is replaced with the secret character. </constant> <constant name="PROPERTY_HINT_MAX" value="37" enum="PropertyHint"> + Represents the size of the [enum PropertyHint] enum. </constant> <constant name="PROPERTY_USAGE_NONE" value="0" enum="PropertyUsageFlags" is_bitfield="true"> The property is not stored, and does not display in the editor. This is the default for non-exported properties. @@ -2809,7 +2820,7 @@ When duplicating a resource with [method Resource.duplicate], and this flag is set on a property of that resource, the property should never be duplicated, regardless of the [code]subresources[/code] bool parameter. </constant> <constant name="PROPERTY_USAGE_HIGH_END_GFX" value="2097152" enum="PropertyUsageFlags" is_bitfield="true"> - The property is only shown in the editor if modern renderers are supported (GLES3 is excluded). + The property is only shown in the editor if modern renderers are supported (the Compatibility rendering method is excluded). </constant> <constant name="PROPERTY_USAGE_NODE_PATH_FROM_SCENE_ROOT" value="4194304" enum="PropertyUsageFlags" is_bitfield="true"> </constant> diff --git a/doc/classes/AESContext.xml b/doc/classes/AESContext.xml index 7f582e4be7..747968ea91 100644 --- a/doc/classes/AESContext.xml +++ b/doc/classes/AESContext.xml @@ -39,39 +39,38 @@ [/gdscript] [csharp] using Godot; - using System; using System.Diagnostics; - public class Example : Node + public partial class MyNode : Node { - public AESContext Aes = new AESContext(); + private AesContext _aes = new AesContext(); public override void _Ready() { string key = "My secret key!!!"; // Key must be either 16 or 32 bytes. string data = "My secret text!!"; // Data size must be multiple of 16 bytes, apply padding if needed. // Encrypt ECB - Aes.Start(AESContext.Mode.EcbEncrypt, key.ToUTF8()); - byte[] encrypted = Aes.Update(data.ToUTF8()); - Aes.Finish(); + _aes.Start(AesContext.Mode.EcbEncrypt, key.ToUtf8()); + byte[] encrypted = _aes.Update(data.ToUtf8()); + _aes.Finish(); // Decrypt ECB - Aes.Start(AESContext.Mode.EcbDecrypt, key.ToUTF8()); - byte[] decrypted = Aes.Update(encrypted); - Aes.Finish(); + _aes.Start(AesContext.Mode.EcbDecrypt, key.ToUtf8()); + byte[] decrypted = _aes.Update(encrypted); + _aes.Finish(); // Check ECB - Debug.Assert(decrypted == data.ToUTF8()); + Debug.Assert(decrypted == data.ToUtf8()); string iv = "My secret iv!!!!"; // IV must be of exactly 16 bytes. // Encrypt CBC - Aes.Start(AESContext.Mode.EcbEncrypt, key.ToUTF8(), iv.ToUTF8()); - encrypted = Aes.Update(data.ToUTF8()); - Aes.Finish(); + _aes.Start(AesContext.Mode.EcbEncrypt, key.ToUtf8(), iv.ToUtf8()); + encrypted = _aes.Update(data.ToUtf8()); + _aes.Finish(); // Decrypt CBC - Aes.Start(AESContext.Mode.EcbDecrypt, key.ToUTF8(), iv.ToUTF8()); - decrypted = Aes.Update(encrypted); - Aes.Finish(); + _aes.Start(AesContext.Mode.EcbDecrypt, key.ToUtf8(), iv.ToUtf8()); + decrypted = _aes.Update(encrypted); + _aes.Finish(); // Check CBC - Debug.Assert(decrypted == data.ToUTF8()); + Debug.Assert(decrypted == data.ToUtf8()); } } [/csharp] diff --git a/doc/classes/AStar2D.xml b/doc/classes/AStar2D.xml index 2414b068e6..d80d784366 100644 --- a/doc/classes/AStar2D.xml +++ b/doc/classes/AStar2D.xml @@ -175,7 +175,7 @@ <method name="get_point_capacity" qualifiers="const"> <return type="int" /> <description> - Returns the capacity of the structure backing the points, useful in conjunction with [code]reserve_space[/code]. + Returns the capacity of the structure backing the points, useful in conjunction with [method reserve_space]. </description> </method> <method name="get_point_connections"> diff --git a/doc/classes/AStar3D.xml b/doc/classes/AStar3D.xml index 4e8394195d..f0481c1745 100644 --- a/doc/classes/AStar3D.xml +++ b/doc/classes/AStar3D.xml @@ -19,15 +19,16 @@ return min(0, abs(u - v) - 1) [/gdscript] [csharp] - public class MyAStar : AStar3D + public partial class MyAStar : AStar3D { - public override float _ComputeCost(int u, int v) + public override float _ComputeCost(long fromId, long toId) { - return Mathf.Abs(u - v); + return Mathf.Abs((int)(fromId - toId)); } - public override float _EstimateCost(int u, int v) + + public override float _EstimateCost(long fromId, long toId) { - return Mathf.Min(0, Mathf.Abs(u - v) - 1); + return Mathf.Min(0, Mathf.Abs((int)(fromId - toId)) - 1); } } [/csharp] diff --git a/doc/classes/AnimatedTexture.xml b/doc/classes/AnimatedTexture.xml index 57a7f86901..052c55dfb6 100644 --- a/doc/classes/AnimatedTexture.xml +++ b/doc/classes/AnimatedTexture.xml @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="AnimatedTexture" inherits="Texture2D" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="AnimatedTexture" inherits="Texture2D" is_deprecated="true" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> Proxy texture for simple frame-based animations. </brief_description> @@ -8,6 +8,7 @@ The playback of the animation is controlled by the [member speed_scale] property, as well as each frame's duration (see [method set_frame_duration]). The animation loops, i.e. it will restart at frame 0 automatically after playing the last frame. [AnimatedTexture] currently requires all frame textures to have the same size, otherwise the bigger ones will be cropped to match the smallest one. [b]Note:[/b] AnimatedTexture doesn't support using [AtlasTexture]s. Each frame needs to be a separate [Texture2D]. + [b]Warning:[/b] AnimatedTexture is deprecated, and might be removed in a future release. Its current implementation is not efficient for the modern renderers. </description> <tutorials> </tutorials> @@ -46,7 +47,7 @@ </methods> <members> <member name="current_frame" type="int" setter="set_current_frame" getter="get_current_frame"> - Sets the currently visible frame of the texture. + Sets the currently visible frame of the texture. Setting this frame while playing resets the current frame time, so the newly selected frame plays for its whole configured frame duration. </member> <member name="frames" type="int" setter="set_frames" getter="get_frames" default="1"> Number of frames to use in the animation. While you can create the frames independently with [method set_frame_texture], you need to set this value for the animation to take new frames into account. The maximum number of frames is [constant MAX_FRAMES]. diff --git a/doc/classes/Animation.xml b/doc/classes/Animation.xml index 74ee13a3d2..9b834f2635 100644 --- a/doc/classes/Animation.xml +++ b/doc/classes/Animation.xml @@ -108,7 +108,7 @@ <return type="bool" /> <param index="0" name="track_idx" type="int" /> <description> - Returns [code]true[/code] if the track at [code]idx[/code] will be blended with other animations. + Returns [code]true[/code] if the track at [param track_idx] will be blended with other animations. </description> </method> <method name="audio_track_set_key_end_offset"> diff --git a/doc/classes/AnimationNode.xml b/doc/classes/AnimationNode.xml index bc65e6013b..4dd83c0d9f 100644 --- a/doc/classes/AnimationNode.xml +++ b/doc/classes/AnimationNode.xml @@ -187,9 +187,24 @@ </member> </members> <signals> + <signal name="animation_node_removed"> + <param index="0" name="object_id" type="int" /> + <param index="1" name="name" type="String" /> + <description> + Emitted by nodes that inherit from this class and that have an internal tree when one of their nodes removes. The nodes that emit this signal are [AnimationNodeBlendSpace1D], [AnimationNodeBlendSpace2D], [AnimationNodeStateMachine], and [AnimationNodeBlendTree]. + </description> + </signal> + <signal name="animation_node_renamed"> + <param index="0" name="object_id" type="int" /> + <param index="1" name="old_name" type="String" /> + <param index="2" name="new_name" type="String" /> + <description> + Emitted by nodes that inherit from this class and that have an internal tree when one of their node names changes. The nodes that emit this signal are [AnimationNodeBlendSpace1D], [AnimationNodeBlendSpace2D], [AnimationNodeStateMachine], and [AnimationNodeBlendTree]. + </description> + </signal> <signal name="tree_changed"> <description> - Emitted by nodes that inherit from this class and that have an internal tree when one of their nodes changes. The nodes that emit this signal are [AnimationNodeBlendSpace1D], [AnimationNodeBlendSpace2D], [AnimationNodeStateMachine], and [AnimationNodeBlendTree]. + Emitted by nodes that inherit from this class and that have an internal tree when one of their nodes changes. The nodes that emit this signal are [AnimationNodeBlendSpace1D], [AnimationNodeBlendSpace2D], [AnimationNodeStateMachine], [AnimationNodeBlendTree] and [AnimationNodeTransition]. </description> </signal> </signals> diff --git a/doc/classes/AnimationNodeAnimation.xml b/doc/classes/AnimationNodeAnimation.xml index 5a8bac1629..93839c6782 100644 --- a/doc/classes/AnimationNodeAnimation.xml +++ b/doc/classes/AnimationNodeAnimation.xml @@ -21,8 +21,10 @@ </members> <constants> <constant name="PLAY_MODE_FORWARD" value="0" enum="PlayMode"> + Plays animation in forward direction. </constant> <constant name="PLAY_MODE_BACKWARD" value="1" enum="PlayMode"> + Plays animation in backward direction. </constant> </constants> </class> diff --git a/doc/classes/AnimationNodeOneShot.xml b/doc/classes/AnimationNodeOneShot.xml index 9e8193868c..713296069d 100644 --- a/doc/classes/AnimationNodeOneShot.xml +++ b/doc/classes/AnimationNodeOneShot.xml @@ -5,6 +5,35 @@ </brief_description> <description> A resource to add to an [AnimationNodeBlendTree]. This node will execute a sub-animation and return once it finishes. Blend times for fading in and out can be customized, as well as filters. + After setting the request and changing the animation playback, the one-shot node automatically clears the request on the next process frame by setting its [code]request[/code] value to [constant ONE_SHOT_REQUEST_NONE]. + [codeblocks] + [gdscript] + # Play child animation connected to "shot" port. + animation_tree.set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE) + # Alternative syntax (same result as above). + animation_tree["parameters/OneShot/request"] = AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE + + # Abort child animation connected to "shot" port. + animation_tree.set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_ABORT) + # Alternative syntax (same result as above). + animation_tree["parameters/OneShot/request"] = AnimationNodeOneShot.ONE_SHOT_REQUEST_ABORT + + # Get current state (read-only). + animation_tree.get("parameters/OneShot/active")) + # Alternative syntax (same result as above). + animation_tree["parameters/OneShot/active"] + [/gdscript] + [csharp] + // Play child animation connected to "shot" port. + animationTree.Set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE); + + // Abort child animation connected to "shot" port. + animationTree.Set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_ABORT); + + // Get current state (read-only). + animationTree.Get("parameters/OneShot/active"); + [/csharp] + [/codeblocks] </description> <tutorials> <link title="AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link> @@ -13,6 +42,7 @@ <members> <member name="autorestart" type="bool" setter="set_autorestart" getter="has_autorestart" default="false"> If [code]true[/code], the sub-animation will restart automatically after finishing. + In other words, to start auto restarting, the animation must be played once with the [constant ONE_SHOT_REQUEST_FIRE] request. The [constant ONE_SHOT_REQUEST_ABORT] request stops the auto restarting, but it does not disable the [member autorestart] itself. So, the [constant ONE_SHOT_REQUEST_FIRE] request will start auto restarting again. </member> <member name="autorestart_delay" type="float" setter="set_autorestart_delay" getter="get_autorestart_delay" default="1.0"> The delay after which the automatic restart is triggered, in seconds. @@ -21,22 +51,30 @@ If [member autorestart] is [code]true[/code], a random additional delay (in seconds) between 0 and this value will be added to [member autorestart_delay]. </member> <member name="fadein_time" type="float" setter="set_fadein_time" getter="get_fadein_time" default="0.0"> + The fade-in duration. For example, setting this to [code]1.0[/code] for a 5 second length animation will produce a crossfade that starts at 0 second and ends at 1 second during the animation. </member> <member name="fadeout_time" type="float" setter="set_fadeout_time" getter="get_fadeout_time" default="0.0"> + The fade-out duration. For example, setting this to [code]1.0[/code] for a 5 second length animation will produce a crossfade that starts at 4 second and ends at 5 second during the animation. </member> <member name="mix_mode" type="int" setter="set_mix_mode" getter="get_mix_mode" enum="AnimationNodeOneShot.MixMode" default="0"> + The blend type. </member> </members> <constants> <constant name="ONE_SHOT_REQUEST_NONE" value="0" enum="OneShotRequest"> + The default state of the request. Nothing is done. </constant> <constant name="ONE_SHOT_REQUEST_FIRE" value="1" enum="OneShotRequest"> + The request to play the animation connected to "shot" port. </constant> <constant name="ONE_SHOT_REQUEST_ABORT" value="2" enum="OneShotRequest"> + The request to stop the animation connected to "shot" port. </constant> <constant name="MIX_MODE_BLEND" value="0" enum="MixMode"> + Blends two animations. See also [AnimationNodeBlend2]. </constant> <constant name="MIX_MODE_ADD" value="1" enum="MixMode"> + Blends two animations additively. See also [AnimationNodeAdd2]. </constant> </constants> </class> diff --git a/doc/classes/AnimationNodeStateMachine.xml b/doc/classes/AnimationNodeStateMachine.xml index 0fb789875f..95891a9061 100644 --- a/doc/classes/AnimationNodeStateMachine.xml +++ b/doc/classes/AnimationNodeStateMachine.xml @@ -161,4 +161,9 @@ </description> </method> </methods> + <members> + <member name="allow_transition_to_self" type="bool" setter="set_allow_transition_to_self" getter="is_allow_transition_to_self" default="false"> + If [code]true[/code], allows teleport to the self state with [method AnimationNodeStateMachinePlayback.travel]. When the reset option is enabled in [method AnimationNodeStateMachinePlayback.travel], the animation is restarted. If [code]false[/code], nothing happens on the teleportation to the self state. + </member> + </members> </class> diff --git a/doc/classes/AnimationNodeStateMachinePlayback.xml b/doc/classes/AnimationNodeStateMachinePlayback.xml index 17a946bb3e..4772c1d819 100644 --- a/doc/classes/AnimationNodeStateMachinePlayback.xml +++ b/doc/classes/AnimationNodeStateMachinePlayback.xml @@ -24,12 +24,15 @@ <method name="get_current_length" qualifiers="const"> <return type="float" /> <description> + Returns the current state length. + [b]Note:[/b] It is possible that any [AnimationRootNode] can be nodes as well as animations. This means that there can be multiple animations within a single state. Which animation length has priority depends on the nodes connected inside it. Also, if a transition does not reset, the remaining length at that point will be returned. </description> </method> <method name="get_current_node" qualifiers="const"> <return type="StringName" /> <description> Returns the currently playing animation state. + [b]Note:[/b] When using a cross-fade, the current state changes to the next state immediately after the cross-fade begins. </description> </method> <method name="get_current_play_position" qualifiers="const"> diff --git a/doc/classes/AnimationNodeStateMachineTransition.xml b/doc/classes/AnimationNodeStateMachineTransition.xml index bccab4613a..537120aec5 100644 --- a/doc/classes/AnimationNodeStateMachineTransition.xml +++ b/doc/classes/AnimationNodeStateMachineTransition.xml @@ -1,8 +1,11 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="AnimationNodeStateMachineTransition" inherits="Resource" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> + A resource to connect each node to make a path for [AnimationNodeStateMachine]. </brief_description> <description> + The path generated when using [method AnimationNodeStateMachinePlayback.travel] is limited to the nodes connected by [AnimationNodeStateMachineTransition]. + You can set the timing and conditions of the transition in detail. </description> <tutorials> <link title="AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link> diff --git a/doc/classes/AnimationNodeSync.xml b/doc/classes/AnimationNodeSync.xml index 21cac11d50..c0e7741ac0 100644 --- a/doc/classes/AnimationNodeSync.xml +++ b/doc/classes/AnimationNodeSync.xml @@ -1,6 +1,7 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="AnimationNodeSync" inherits="AnimationNode" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> + The base class for [AnimationNode] which has more than two input ports and needs to synchronize them. </brief_description> <description> </description> diff --git a/doc/classes/AnimationNodeTimeSeek.xml b/doc/classes/AnimationNodeTimeSeek.xml index 0a7da8ba07..5033059927 100644 --- a/doc/classes/AnimationNodeTimeSeek.xml +++ b/doc/classes/AnimationNodeTimeSeek.xml @@ -4,25 +4,26 @@ A time-seeking animation node to be used with [AnimationTree]. </brief_description> <description> - This node can be used to cause a seek command to happen to any sub-children of the animation graph. Use this node type to play an [Animation] from the start or a certain playback position inside the [AnimationNodeBlendTree]. After setting the time and changing the animation playback, the seek node automatically goes into sleep mode on the next process frame by setting its [code]seek_position[/code] value to [code]-1.0[/code]. + This node can be used to cause a seek command to happen to any sub-children of the animation graph. Use this node type to play an [Animation] from the start or a certain playback position inside the [AnimationNodeBlendTree]. + After setting the time and changing the animation playback, the time seek node automatically goes into sleep mode on the next process frame by setting its [code]seek_request[/code] value to [code]-1.0[/code]. [codeblocks] [gdscript] # Play child animation from the start. - animation_tree.set("parameters/Seek/seek_position", 0.0) + animation_tree.set("parameters/TimeSeek/seek_request", 0.0) # Alternative syntax (same result as above). - animation_tree["parameters/Seek/seek_position"] = 0.0 + animation_tree["parameters/TimeSeek/seek_request"] = 0.0 # Play child animation from 12 second timestamp. - animation_tree.set("parameters/Seek/seek_position", 12.0) + animation_tree.set("parameters/TimeSeek/seek_request", 12.0) # Alternative syntax (same result as above). - animation_tree["parameters/Seek/seek_position"] = 12.0 + animation_tree["parameters/TimeSeek/seek_request"] = 12.0 [/gdscript] [csharp] // Play child animation from the start. - animationTree.Set("parameters/Seek/seek_position", 0.0); + animationTree.Set("parameters/TimeSeek/seek_request", 0.0); // Play child animation from 12 second timestamp. - animationTree.Set("parameters/Seek/seek_position", 12.0); + animationTree.Set("parameters/TimeSeek/seek_request", 12.0); [/csharp] [/codeblocks] </description> diff --git a/doc/classes/AnimationNodeTransition.xml b/doc/classes/AnimationNodeTransition.xml index a067b0a9ba..4eeaf15b53 100644 --- a/doc/classes/AnimationNodeTransition.xml +++ b/doc/classes/AnimationNodeTransition.xml @@ -5,6 +5,36 @@ </brief_description> <description> Simple state machine for cases which don't require a more advanced [AnimationNodeStateMachine]. Animations can be connected to the inputs and transition times can be specified. + After setting the request and changing the animation playback, the transition node automatically clears the request on the next process frame by setting its [code]transition_request[/code] value to empty. + [b]Note:[/b] When using a cross-fade, [code]current_state[/code] and [code]current_index[/code] change to the next state immediately after the cross-fade begins. + [codeblocks] + [gdscript] + # Play child animation connected to "state_2" port. + animation_tree.set("parameters/Transition/transition_request", "state_2") + # Alternative syntax (same result as above). + animation_tree["parameters/Transition/transition_request"] = "state_2" + + # Get current state name (read-only). + animation_tree.get("parameters/Transition/current_state") + # Alternative syntax (same result as above). + animation_tree["parameters/Transition/current_state"] + + # Get current state index (read-only). + animation_tree.get("parameters/Transition/current_index")) + # Alternative syntax (same result as above). + animation_tree["parameters/Transition/current_index"] + [/gdscript] + [csharp] + // Play child animation connected to "state_2" port. + animationTree.Set("parameters/Transition/transition_request", "state_2"); + + // Get current state name (read-only). + animationTree.Get("parameters/Transition/current_state"); + + // Get current state index (read-only). + animationTree.Get("parameters/Transition/current_index"); + [/csharp] + [/codeblocks] </description> <tutorials> <link title="AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link> @@ -44,6 +74,9 @@ </method> </methods> <members> + <member name="allow_transition_to_self" type="bool" setter="set_allow_transition_to_self" getter="is_allow_transition_to_self" default="false"> + If [code]true[/code], allows transition to the self state. When the reset option is enabled in input, the animation is restarted. If [code]false[/code], nothing happens on the transition to the self state. + </member> <member name="input_count" type="int" setter="set_input_count" getter="get_input_count" default="0"> The number of enabled input ports for this node. </member> diff --git a/doc/classes/AnimationRootNode.xml b/doc/classes/AnimationRootNode.xml index d364c15f77..cdcec3787a 100644 --- a/doc/classes/AnimationRootNode.xml +++ b/doc/classes/AnimationRootNode.xml @@ -1,6 +1,7 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="AnimationRootNode" inherits="AnimationNode" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> + The [AnimationNode] which can be set as the root of an [AnimationTree]. </brief_description> <description> </description> diff --git a/doc/classes/AnimationTree.xml b/doc/classes/AnimationTree.xml index 86562c340d..ed98f47f58 100644 --- a/doc/classes/AnimationTree.xml +++ b/doc/classes/AnimationTree.xml @@ -33,7 +33,7 @@ <method name="get_root_motion_position" qualifiers="const"> <return type="Vector3" /> <description> - Retrieve the motion of position with the [member root_motion_track] as a [Vector3] that can be used elsewhere. + Retrieve the motion delta 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]: @@ -50,12 +50,46 @@ move_and_slide() [/gdscript] [/codeblocks] + By using this in combination with [method get_root_motion_position_accumulator], you can apply the root motion position more correctly to account for the rotation of the node. + [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()) + var velocity: Vector3 = (animation_tree.get_root_motion_rotation_accumulator().inverse() * get_quaternion()) * animation_tree.get_root_motion_position() / delta + set_velocity(velocity) + move_and_slide() + [/gdscript] + [/codeblocks] + </description> + </method> + <method name="get_root_motion_position_accumulator" qualifiers="const"> + <return type="Vector3" /> + <description> + Retrieve the blended value of the position tracks with the [member root_motion_track] as a [Vector3] that can be used elsewhere. + This is useful in cases where you want to respect the initial key values of the animation. + For example, if an animation with only one key [code]Vector3(0, 0, 0)[/code] is played in the previous frame and then an animation with only one key [code]Vector3(1, 0, 1)[/code] is played in the next frame, the difference can be calculated as follows: + [codeblocks] + [gdscript] + var prev_root_motion_position_accumulator: Vector3 + + func _process(delta): + if Input.is_action_just_pressed("animate"): + state_machine.travel("Animate") + var current_root_motion_position_accumulator: Vector3 = animation_tree.get_root_motion_position_accumulator() + var difference: Vector3 = current_root_motion_position_accumulator - prev_root_motion_position_accumulator + prev_root_motion_position_accumulator = current_root_motion_position_accumulator + transform.origin += difference + [/gdscript] + [/codeblocks] + However, if the animation loops, an unintended discrete change may occur, so this is only useful for some simple use cases. </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. + Retrieve the motion delta 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]: @@ -69,10 +103,33 @@ [/codeblocks] </description> </method> + <method name="get_root_motion_rotation_accumulator" qualifiers="const"> + <return type="Quaternion" /> + <description> + Retrieve the blended value of the rotation tracks with the [member root_motion_track] as a [Quaternion] that can be used elsewhere. + This is necessary to apply the root motion position correctly, taking rotation into account. See also [method get_root_motion_position]. + Also, this is useful in cases where you want to respect the initial key values of the animation. + For example, if an animation with only one key [code]Quaternion(0, 0, 0, 1)[/code] is played in the previous frame and then an animation with only one key [code]Quaternion(0, 0.707, 0, 0.707)[/code] is played in the next frame, the difference can be calculated as follows: + [codeblocks] + [gdscript] + var prev_root_motion_rotation_accumulator: Quaternion + + func _process(delta): + if Input.is_action_just_pressed("animate"): + state_machine.travel("Animate") + var current_root_motion_rotation_accumulator: Quaternion = animation_tree.get_root_motion_Quaternion_accumulator() + var difference: Quaternion = prev_root_motion_rotation_accumulator.inverse() * current_root_motion_rotation_accumulator + prev_root_motion_rotation_accumulator = current_root_motion_rotation_accumulator + transform.basis *= difference + [/gdscript] + [/codeblocks] + However, if the animation loops, an unintended discrete change may occur, so this is only useful for some simple use cases. + </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. + Retrieve the motion delta 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]: @@ -92,11 +149,25 @@ [/codeblocks] </description> </method> - <method name="rename_parameter"> - <return type="void" /> - <param index="0" name="old_name" type="String" /> - <param index="1" name="new_name" type="String" /> + <method name="get_root_motion_scale_accumulator" qualifiers="const"> + <return type="Vector3" /> <description> + Retrieve the blended value of the scale tracks with the [member root_motion_track] as a [Vector3] that can be used elsewhere. + For example, if an animation with only one key [code]Vector3(1, 1, 1)[/code] is played in the previous frame and then an animation with only one key [code]Vector3(2, 2, 2)[/code] is played in the next frame, the difference can be calculated as follows: + [codeblocks] + [gdscript] + var prev_root_motion_scale_accumulator: Vector3 + + func _process(delta): + if Input.is_action_just_pressed("animate"): + state_machine.travel("Animate") + var current_root_motion_scale_accumulator: Vector3 = animation_tree.get_root_motion_scale_accumulator() + var difference: Vector3 = current_root_motion_scale_accumulator - prev_root_motion_scale_accumulator + prev_root_motion_scale_accumulator = current_root_motion_scale_accumulator + transform.basis = transform.basis.scaled(difference) + [/gdscript] + [/codeblocks] + However, if the animation loops, an unintended discrete change may occur, so this is only useful for some simple use cases. </description> </method> </methods> diff --git a/doc/classes/Area2D.xml b/doc/classes/Area2D.xml index 8a98921a60..100a71abef 100644 --- a/doc/classes/Area2D.xml +++ b/doc/classes/Area2D.xml @@ -1,7 +1,7 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="Area2D" inherits="CollisionObject2D" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - 2D area for detection and physics and audio influence. + 2D area for detection, as well as physics and audio influence. </brief_description> <description> 2D area that detects [CollisionObject2D] nodes overlapping, entering, or exiting. Can also alter or override local physics parameters (gravity, damping) and route audio to custom audio buses. diff --git a/doc/classes/Area3D.xml b/doc/classes/Area3D.xml index bd046b7cb8..cf9e865064 100644 --- a/doc/classes/Area3D.xml +++ b/doc/classes/Area3D.xml @@ -1,7 +1,7 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="Area3D" inherits="CollisionObject3D" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - 3D area for detection and physics and audio influence. + 3D area for detection, as well as physics and audio influence. </brief_description> <description> 3D area that detects [CollisionObject3D] nodes overlapping, entering, or exiting. Can also alter or override local physics parameters (gravity, damping) and route audio to custom audio buses. diff --git a/doc/classes/Array.xml b/doc/classes/Array.xml index 213a2254af..c4fec5a729 100644 --- a/doc/classes/Array.xml +++ b/doc/classes/Array.xml @@ -214,7 +214,7 @@ [b]Note:[/b] Calling this function is not the same as writing [code]array[-1][/code]. If the array is empty, accessing by index will pause project execution when running from the editor. </description> </method> - <method name="bsearch"> + <method name="bsearch" qualifiers="const"> <return type="int" /> <param index="0" name="value" type="Variant" /> <param index="1" name="before" type="bool" default="true" /> @@ -223,7 +223,7 @@ [b]Note:[/b] Calling [method bsearch] on an unsorted array results in unexpected behavior. </description> </method> - <method name="bsearch_custom"> + <method name="bsearch_custom" qualifiers="const"> <return type="int" /> <param index="0" name="value" type="Variant" /> <param index="1" name="func" type="Callable" /> @@ -276,7 +276,7 @@ array.fill(0) # Initialize the 10 elements to 0. [/gdscript] [csharp] - var array = new Godot.Collections.Array{}; + var array = new Godot.Collections.Array(); array.Resize(10); array.Fill(0); // Initialize the 10 elements to 0. [/csharp] @@ -347,7 +347,7 @@ print(["inside", 7].has("7")) # False [/gdscript] [csharp] - var arr = new Godot.Collections.Array{"inside", 7}; + var arr = new Godot.Collections.Array { "inside", 7 }; // has is renamed to Contains GD.Print(arr.Contains("inside")); // True GD.Print(arr.Contains("outside")); // False @@ -364,7 +364,7 @@ [/gdscript] [csharp] // As there is no "in" keyword in C#, you have to use Contains - var array = new Godot.Collections.Array{2, 4, 6, 8}; + var array = new Godot.Collections.Array { 2, 4, 6, 8 }; if (array.Contains(2)) { GD.Print("Contains!"); @@ -454,10 +454,16 @@ <return type="Variant" /> <description> Returns a random value from the target array. - [codeblock] + [codeblocks] + [gdscript] var array: Array[int] = [1, 2, 3, 4] print(array.pick_random()) # Prints either of the four numbers. - [/codeblock] + [/gdscript] + [csharp] + var array = new Godot.Collections.Array { 1, 2, 3, 4 }; + GD.Print(array.PickRandom()); // Prints either of the four numbers. + [/csharp] + [/codeblocks] </description> </method> <method name="pop_at"> @@ -566,7 +572,7 @@ Returns the slice of the [Array], from [param begin] (inclusive) to [param end] (exclusive), as a new [Array]. The absolute value of [param begin] and [param end] will be clamped to the array size, so the default value for [param end] makes it slice to the size of the array by default (i.e. [code]arr.slice(1)[/code] is a shorthand for [code]arr.slice(1, arr.size())[/code]). If either [param begin] or [param end] are negative, they will be relative to the end of the array (i.e. [code]arr.slice(0, -2)[/code] is a shorthand for [code]arr.slice(0, arr.size() - 2)[/code]). - If specified, [param step] is the relative index between source elements. It can be negative, then [param begin] must be higher than [param end]. For example, [code][0, 1, 2, 3, 4, 5].slice(5, 1, -2)[/code] returns [code][5, 3][/code]). + If specified, [param step] is the relative index between source elements. It can be negative, then [param begin] must be higher than [param end]. For example, [code][0, 1, 2, 3, 4, 5].slice(5, 1, -2)[/code] returns [code][5, 3][/code]. If [param deep] is true, each element will be copied by value rather than by reference. </description> </method> @@ -583,7 +589,9 @@ print(strings) # Prints [string1, string10, string11, string2] [/gdscript] [csharp] - // There is no sort support for Godot.Collections.Array + var strings = new Godot.Collections.Array { "string1", "string2", "string10", "string11" }; + strings.Sort(); + GD.Print(strings); // Prints [string1, string10, string11, string2] [/csharp] [/codeblocks] To perform natural order sorting, you can use [method sort_custom] with [method String.naturalnocasecmp_to] as follows: diff --git a/doc/classes/AudioServer.xml b/doc/classes/AudioServer.xml index 36f12dd5c4..ae331f8491 100644 --- a/doc/classes/AudioServer.xml +++ b/doc/classes/AudioServer.xml @@ -29,13 +29,6 @@ Adds an [AudioEffect] effect to the bus [param bus_idx] at [param at_position]. </description> </method> - <method name="capture_get_device_list"> - <return type="PackedStringArray" /> - <description> - Returns the names of all audio input devices detected on the system. - [b]Note:[/b] [member ProjectSettings.audio/driver/enable_input] must be [code]true[/code] for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings. - </description> - </method> <method name="generate_bus_layout" qualifiers="const"> <return type="AudioBusLayout" /> <description> @@ -117,10 +110,11 @@ Returns the volume of the bus at index [param bus_idx] in dB. </description> </method> - <method name="get_device_list"> + <method name="get_input_device_list"> <return type="PackedStringArray" /> <description> - Returns the names of all audio devices detected on the system. + Returns the names of all audio input devices detected on the system. + [b]Note:[/b] [member ProjectSettings.audio/driver/enable_input] must be [code]true[/code] for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings. </description> </method> <method name="get_mix_rate" qualifiers="const"> @@ -129,6 +123,12 @@ Returns the sample rate at the output of the [AudioServer]. </description> </method> + <method name="get_output_device_list"> + <return type="PackedStringArray" /> + <description> + Returns the names of all audio output devices detected on the system. + </description> + </method> <method name="get_output_latency" qualifiers="const"> <return type="float" /> <description> @@ -302,12 +302,12 @@ <member name="bus_count" type="int" setter="set_bus_count" getter="get_bus_count" default="1"> Number of available audio buses. </member> - <member name="capture_device" type="String" setter="capture_set_device" getter="capture_get_device" default=""Default""> - Name of the current device for audio input (see [method capture_get_device_list]). On systems with multiple audio inputs (such as analog, USB and HDMI audio), this can be used to select the audio input device. The value [code]"Default"[/code] will record audio on the system-wide default audio input. If an invalid device name is set, the value will be reverted back to [code]"Default"[/code]. + <member name="input_device" type="String" setter="set_input_device" getter="get_input_device" default=""Default""> + Name of the current device for audio input (see [method get_input_device_list]). On systems with multiple audio inputs (such as analog, USB and HDMI audio), this can be used to select the audio input device. The value [code]"Default"[/code] will record audio on the system-wide default audio input. If an invalid device name is set, the value will be reverted back to [code]"Default"[/code]. [b]Note:[/b] [member ProjectSettings.audio/driver/enable_input] must be [code]true[/code] for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings. </member> - <member name="device" type="String" setter="set_device" getter="get_device" default=""Default""> - Name of the current device for audio output (see [method get_device_list]). On systems with multiple audio outputs (such as analog, USB and HDMI audio), this can be used to select the audio output device. The value [code]"Default"[/code] will play audio on the system-wide default audio output. If an invalid device name is set, the value will be reverted back to [code]"Default"[/code]. + <member name="output_device" type="String" setter="set_output_device" getter="get_output_device" default=""Default""> + Name of the current device for audio output (see [method get_output_device_list]). On systems with multiple audio outputs (such as analog, USB and HDMI audio), this can be used to select the audio output device. The value [code]"Default"[/code] will play audio on the system-wide default audio output. If an invalid device name is set, the value will be reverted back to [code]"Default"[/code]. </member> <member name="playback_speed_scale" type="float" setter="set_playback_speed_scale" getter="get_playback_speed_scale" default="1.0"> Scales the rate at which audio is played (i.e. setting it to [code]0.5[/code] will make the audio be played at half its speed). diff --git a/doc/classes/AudioStreamPlayer2D.xml b/doc/classes/AudioStreamPlayer2D.xml index 18869e87cb..b01a267154 100644 --- a/doc/classes/AudioStreamPlayer2D.xml +++ b/doc/classes/AudioStreamPlayer2D.xml @@ -4,7 +4,7 @@ Plays positional sound in 2D space. </brief_description> <description> - Plays audio that dampens with distance from a given position. + Plays audio that is attenuated with distance to the listener. By default, audio is heard from the screen center. This can be changed by adding an [AudioListener2D] node to the scene and enabling it by calling [method AudioListener2D.make_current] on it. See also [AudioStreamPlayer] to play a sound non-positionally. [b]Note:[/b] Hiding an [AudioStreamPlayer2D] node does not disable its audio output. To temporarily disable an [AudioStreamPlayer2D]'s audio output, set [member volume_db] to a very low value like [code]-100[/code] (which isn't audible to human hearing). @@ -57,7 +57,7 @@ Determines which [Area2D] layers affect the sound for reverb and audio bus effects. Areas can be used to redirect [AudioStream]s so that they play in a certain audio bus. An example of how you might use this is making a "water" area so that sounds played in the water are redirected through an audio bus to make them sound like they are being played underwater. </member> <member name="attenuation" type="float" setter="set_attenuation" getter="get_attenuation" default="1.0"> - Dampens audio over distance with this as an exponent. + The volume is attenuated over distance with this as an exponent. </member> <member name="autoplay" type="bool" setter="set_autoplay" getter="is_autoplay_enabled" default="false"> If [code]true[/code], audio plays when added to scene tree. @@ -88,7 +88,7 @@ If [code]true[/code], the playback is paused. You can resume it by setting [code]stream_paused[/code] to [code]false[/code]. </member> <member name="volume_db" type="float" setter="set_volume_db" getter="get_volume_db" default="0.0"> - Base volume without dampening. + Base volume before attenuation. </member> </members> <signals> diff --git a/doc/classes/AudioStreamPlayer3D.xml b/doc/classes/AudioStreamPlayer3D.xml index d5a06dcad6..bfb5b6f154 100644 --- a/doc/classes/AudioStreamPlayer3D.xml +++ b/doc/classes/AudioStreamPlayer3D.xml @@ -4,7 +4,7 @@ Plays positional sound in 3D space. </brief_description> <description> - Plays a sound effect with directed sound effects, dampens with distance if needed, generates effect of hearable position in space. For greater realism, a low-pass filter is automatically applied to distant sounds. This can be disabled by setting [member attenuation_filter_cutoff_hz] to [code]20500[/code]. + Plays audio with positional sound effects, based on the relative position of the audio listener. Positional effects include distance attenuation, directionality, and the Doppler effect. For greater realism, a low-pass filter is applied to distant sounds. This can be disabled by setting [member attenuation_filter_cutoff_hz] to [code]20500[/code]. By default, audio is heard from the camera position. This can be changed by adding an [AudioListener3D] node to the scene and enabling it by calling [method AudioListener3D.make_current] on it. See also [AudioStreamPlayer] to play a sound non-positionally. [b]Note:[/b] Hiding an [AudioStreamPlayer3D] node does not disable its audio output. To temporarily disable an [AudioStreamPlayer3D]'s audio output, set [member volume_db] to a very low value like [code]-100[/code] (which isn't audible to human hearing). @@ -57,7 +57,7 @@ Determines which [Area3D] layers affect the sound for reverb and audio bus effects. Areas can be used to redirect [AudioStream]s so that they play in a certain audio bus. An example of how you might use this is making a "water" area so that sounds played in the water are redirected through an audio bus to make them sound like they are being played underwater. </member> <member name="attenuation_filter_cutoff_hz" type="float" setter="set_attenuation_filter_cutoff_hz" getter="get_attenuation_filter_cutoff_hz" default="5000.0"> - Dampens audio using a low-pass filter above this frequency, in Hz. To disable the dampening effect entirely, set this to [code]20500[/code] as this frequency is above the human hearing limit. + The cutoff frequency of the attenuation low-pass filter, in Hz. A sound above this frequency is attenuated more than a sound below this frequency. To disable this effect, set this to [code]20500[/code] as this frequency is above the human hearing limit. </member> <member name="attenuation_filter_db" type="float" setter="set_attenuation_filter_db" getter="get_attenuation_filter_db" default="-24.0"> Amount how much the filter affects the loudness, in decibels. @@ -76,13 +76,13 @@ Decides in which step the Doppler effect should be calculated. </member> <member name="emission_angle_degrees" type="float" setter="set_emission_angle" getter="get_emission_angle" default="45.0"> - The angle in which the audio reaches cameras undampened. + The angle in which the audio reaches a listener unattenuated. </member> <member name="emission_angle_enabled" type="bool" setter="set_emission_angle_enabled" getter="is_emission_angle_enabled" default="false"> - If [code]true[/code], the audio should be dampened according to the direction of the sound. + If [code]true[/code], the audio should be attenuated according to the direction of the sound. </member> <member name="emission_angle_filter_attenuation_db" type="float" setter="set_emission_angle_filter_attenuation_db" getter="get_emission_angle_filter_attenuation_db" default="-12.0"> - Dampens audio if camera is outside of [member emission_angle_degrees] and [member emission_angle_enabled] is set by this factor, in decibels. + Attenuation factor used if listener is outside of [member emission_angle_degrees] and [member emission_angle_enabled] is set, in decibels. </member> <member name="max_db" type="float" setter="set_max_db" getter="get_max_db" default="3.0"> Sets the absolute maximum of the soundlevel, in decibels. @@ -112,7 +112,7 @@ The factor for the attenuation effect. Higher values make the sound audible over a larger distance. </member> <member name="volume_db" type="float" setter="set_volume_db" getter="get_volume_db" default="0.0"> - The base sound level unaffected by dampening, in decibels. + The base sound level before attenuation, in decibels. </member> </members> <signals> @@ -124,16 +124,16 @@ </signals> <constants> <constant name="ATTENUATION_INVERSE_DISTANCE" value="0" enum="AttenuationModel"> - Linear dampening of loudness according to distance. + Attenuation of loudness according to linear distance. </constant> <constant name="ATTENUATION_INVERSE_SQUARE_DISTANCE" value="1" enum="AttenuationModel"> - Squared dampening of loudness according to distance. + Attenuation of loudness according to squared distance. </constant> <constant name="ATTENUATION_LOGARITHMIC" value="2" enum="AttenuationModel"> - Logarithmic dampening of loudness according to distance. + Attenuation of loudness according to logarithmic distance. </constant> <constant name="ATTENUATION_DISABLED" value="3" enum="AttenuationModel"> - No dampening of loudness according to distance. The sound will still be heard positionally, unlike an [AudioStreamPlayer]. [constant ATTENUATION_DISABLED] can be combined with a [member max_distance] value greater than [code]0.0[/code] to achieve linear attenuation clamped to a sphere of a defined size. + No attenuation of loudness according to distance. The sound will still be heard positionally, unlike an [AudioStreamPlayer]. [constant ATTENUATION_DISABLED] can be combined with a [member max_distance] value greater than [code]0.0[/code] to achieve linear attenuation clamped to a sphere of a defined size. </constant> <constant name="DOPPLER_TRACKING_DISABLED" value="0" enum="DopplerTracking"> Disables doppler tracking. diff --git a/doc/classes/BaseMaterial3D.xml b/doc/classes/BaseMaterial3D.xml index 60225275f3..6cd8c44269 100644 --- a/doc/classes/BaseMaterial3D.xml +++ b/doc/classes/BaseMaterial3D.xml @@ -121,7 +121,7 @@ Texture used to control the backlight effect per-pixel. Added to [member backlight]. </member> <member name="billboard_keep_scale" type="bool" setter="set_flag" getter="get_flag" default="false"> - If [code]true[/code], the shader will keep the scale set for the mesh. Otherwise, the scale is lost when billboarding. Only applies when [member billboard_mode] is [constant BILLBOARD_ENABLED]. + If [code]true[/code], the shader will keep the scale set for the mesh. Otherwise, the scale is lost when billboarding. Only applies when [member billboard_mode] is not [constant BILLBOARD_DISABLED]. </member> <member name="billboard_mode" type="int" setter="set_billboard_mode" getter="get_billboard_mode" enum="BaseMaterial3D.BillboardMode" default="0"> Controls how the object faces the camera. See [enum BillboardMode]. @@ -215,10 +215,11 @@ If [code]true[/code], the object is rendered at the same size regardless of distance. </member> <member name="grow" type="bool" setter="set_grow_enabled" getter="is_grow_enabled" default="false"> - If [code]true[/code], enables the vertex grow setting. See [member grow_amount]. + If [code]true[/code], enables the vertex grow setting. This can be used to create mesh-based outlines using a second material pass and its [member cull_mode] set to [constant CULL_FRONT]. See also [member grow_amount]. + [b]Note:[/b] Vertex growth cannot create new vertices, which means that visible gaps may occur in sharp corners. This can be alleviated by designing the mesh to use smooth normals exclusively using [url=https://wiki.polycount.com/wiki/Face_weighted_normals]face weighted normals[/url] in the 3D authoring software. In this case, grow will be able to join every outline together, just like in the original mesh. </member> <member name="grow_amount" type="float" setter="set_grow" getter="get_grow" default="0.0"> - Grows object vertices in the direction of their normals. + Grows object vertices in the direction of their normals. Only effective if [member grow] is [code]true[/code]. </member> <member name="heightmap_deep_parallax" type="bool" setter="set_heightmap_deep_parallax" getter="is_heightmap_deep_parallax_enabled" default="false"> If [code]true[/code], uses parallax occlusion mapping to represent depth in the material instead of simple offset mapping (see [member heightmap_enabled]). This results in a more convincing depth effect, but is much more expensive on the GPU. Only enable this on materials where it makes a significant visual difference. @@ -277,7 +278,7 @@ If [code]true[/code], depth testing is disabled and the object will be drawn in render order. </member> <member name="normal_enabled" type="bool" setter="set_feature" getter="get_feature" default="false"> - If [code]true[/code], normal mapping is enabled. + If [code]true[/code], normal mapping is enabled. This has a slight performance cost, especially on mobile GPUs. </member> <member name="normal_scale" type="float" setter="set_normal_scale" getter="get_normal_scale" default="1.0"> The strength of the normal map's effect. @@ -344,7 +345,8 @@ 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. + Sets whether the shading takes place, per-pixel, per-vertex or unshaded. Per-vertex lighting is faster, making it the best choice for mobile applications, however it looks considerably worse than per-pixel. Unshaded rendering is the fastest, but disables all interactions with lights. + [b]Note:[/b] Setting the shading mode vertex shading currently has no effect, as vertex shading is not implemented yet. </member> <member name="shadow_to_opacity" type="bool" setter="set_flag" getter="get_flag" default="false"> If [code]true[/code], enables the "shadow to opacity" render mode where lighting modifies the alpha so shadowed areas are opaque and non-shadowed areas are transparent. Useful for overlaying shadows onto a camera feed in AR. @@ -388,7 +390,7 @@ Repeat flags for the texture. See [enum TextureFilter] for options. </member> <member name="transparency" type="int" setter="set_transparency" getter="get_transparency" enum="BaseMaterial3D.Transparency" default="0"> - If [code]true[/code], transparency is enabled on the body. See also [member blend_mode]. + If [code]true[/code], transparency is enabled on the body. Some transparency modes will disable shadow casting. Any transparency mode other than Disabled has a greater performance impact compared to opaque rendering. See also [member blend_mode]. </member> <member name="use_particle_trails" type="bool" setter="set_flag" getter="get_flag" default="false"> If [code]true[/code], enables parts of the shader required for [GPUParticles3D] trails to function. This also requires using a mesh with appropriate skinning, such as [RibbonTrailMesh] or [TubeTrailMesh]. Enabling this feature outside of materials used in [GPUParticles3D] meshes will break material rendering. @@ -431,7 +433,7 @@ </member> <member name="vertex_color_is_srgb" type="bool" setter="set_flag" getter="get_flag" default="false"> If [code]true[/code], vertex colors are considered to be stored in sRGB color space and are converted to linear color space during rendering. If [code]false[/code], vertex colors are considered to be stored in linear color space and are rendered as-is. See also [member albedo_texture_force_srgb]. - [b]Note:[/b] Only effective when using the Vulkan Clustered or Vulkan Mobile backends. + [b]Note:[/b] Only effective when using the Forward+ and Mobile rendering methods, not Compatibility. </member> <member name="vertex_color_use_as_albedo" type="bool" setter="set_flag" getter="get_flag" default="false"> If [code]true[/code], the vertex color is used as albedo color. @@ -523,31 +525,31 @@ Use [code]UV2[/code] with the detail texture. </constant> <constant name="TRANSPARENCY_DISABLED" value="0" enum="Transparency"> - The material will not use transparency. + The material will not use transparency. This is the fastest to render. </constant> <constant name="TRANSPARENCY_ALPHA" value="1" enum="Transparency"> - The material will use the texture's alpha values for transparency. + The material will use the texture's alpha values for transparency. This is the slowest to render, and disables shadow casting. </constant> <constant name="TRANSPARENCY_ALPHA_SCISSOR" value="2" enum="Transparency"> - The material will cut off all values below a threshold, the rest will remain opaque. The opaque portions will be rendered in the depth prepass. + The material will cut off all values below a threshold, the rest will remain opaque. The opaque portions will be rendered in the depth prepass. This is faster to render than alpha blending, but slower than opaque rendering. This also supports casting shadows. </constant> <constant name="TRANSPARENCY_ALPHA_HASH" value="3" enum="Transparency"> - The material will cut off all values below a spatially-deterministic threshold, the rest will remain opaque. + The material will cut off all values below a spatially-deterministic threshold, the rest will remain opaque. This is faster to render than alpha blending, but slower than opaque rendering. This also supports casting shadows. Alpha hashing is suited for hair rendering. </constant> <constant name="TRANSPARENCY_ALPHA_DEPTH_PRE_PASS" value="4" enum="Transparency"> - The material will use the texture's alpha value for transparency, but will discard fragments with an alpha of less than 0.99 during the depth prepass and fragments with an alpha less than 0.1 during the shadow pass. + The material will use the texture's alpha value for transparency, but will discard fragments with an alpha of less than 0.99 during the depth prepass and fragments with an alpha less than 0.1 during the shadow pass. This also supports casting shadows. </constant> <constant name="TRANSPARENCY_MAX" value="5" enum="Transparency"> Represents the size of the [enum Transparency] enum. </constant> <constant name="SHADING_MODE_UNSHADED" value="0" enum="ShadingMode"> - The object will not receive shadows. + The object will not receive shadows. This is the fastest to render, but it disables all interactions with lights. </constant> <constant name="SHADING_MODE_PER_PIXEL" value="1" enum="ShadingMode"> - The object will be shaded per pixel. Useful for realistic shading effect. + The object will be shaded per pixel. Useful for realistic shading effects. </constant> <constant name="SHADING_MODE_PER_VERTEX" value="2" enum="ShadingMode"> - The object will be shaded per vertex. Useful when you want cheaper shaders and do not care about visual quality. + The object will be shaded per vertex. Useful when you want cheaper shaders and do not care about visual quality. Not implemented yet (this mode will act like [constant SHADING_MODE_PER_PIXEL]). </constant> <constant name="SHADING_MODE_MAX" value="3" enum="ShadingMode"> Represents the size of the [enum ShadingMode] enum. @@ -623,13 +625,13 @@ Objects will not write their depth to the depth buffer, even during the depth prepass (if enabled). </constant> <constant name="CULL_BACK" value="0" enum="CullMode"> - Default cull mode. The back of the object is culled when not visible. Back face triangles will be culled when facing the camera. This results in only the front side of triangles being drawn. For closed-surface meshes this means that only the exterior of the mesh will be visible. + Default cull mode. The back of the object is culled when not visible. Back face triangles will be culled when facing the camera. This results in only the front side of triangles being drawn. For closed-surface meshes, this means that only the exterior of the mesh will be visible. </constant> <constant name="CULL_FRONT" value="1" enum="CullMode"> - Front face triangles will be culled when facing the camera. This results in only the back side of triangles being drawn. For closed-surface meshes this means that the interior of the mesh will be drawn instead of the exterior. + Front face triangles will be culled when facing the camera. This results in only the back side of triangles being drawn. For closed-surface meshes, this means that the interior of the mesh will be drawn instead of the exterior. </constant> <constant name="CULL_DISABLED" value="2" enum="CullMode"> - No culling is performed. + No face culling is performed; both the front face and back face will be visible. </constant> <constant name="FLAG_DISABLE_DEPTH_TEST" value="0" enum="Flags"> Disables the depth test, so this object is drawn on top of all others drawn before it. This puts the object in the transparent draw pass where it is sorted based on distance to camera. Objects drawn after it in the draw order may cover it. This also disables writing to depth. @@ -639,7 +641,7 @@ </constant> <constant name="FLAG_SRGB_VERTEX_COLOR" value="2" enum="Flags"> Vertex colors are considered to be stored in sRGB color space and are converted to linear color space during rendering. See also [member vertex_color_is_srgb]. - [b]Note:[/b] Only effective when using the Vulkan Clustered or Vulkan Mobile backends. + [b]Note:[/b] Only effective when using the Forward+ and Mobile rendering methods. </constant> <constant name="FLAG_USE_POINT_SIZE" value="3" enum="Flags"> Uses point size to alter the size of primitive points. Also changes the albedo texture lookup to use [code]POINT_COORD[/code] instead of [code]UV[/code]. @@ -717,7 +719,7 @@ Toon blob which changes size based on roughness. </constant> <constant name="SPECULAR_DISABLED" value="2" enum="SpecularMode"> - No specular blob. + No specular blob. This is slightly faster to render than other specular modes. </constant> <constant name="BILLBOARD_DISABLED" value="0" enum="BillboardMode"> Billboard mode is disabled. @@ -760,10 +762,10 @@ Smoothly fades the object out based on each pixel's distance from the camera using the alpha channel. </constant> <constant name="DISTANCE_FADE_PIXEL_DITHER" value="2" enum="DistanceFadeMode"> - Smoothly fades the object out based on each pixel's distance from the camera using a dither approach. Dithering discards pixels based on a set pattern to smoothly fade without enabling transparency. On certain hardware this can be faster than [constant DISTANCE_FADE_PIXEL_ALPHA]. + Smoothly fades the object out based on each pixel's distance from the camera using a dithering approach. Dithering discards pixels based on a set pattern to smoothly fade without enabling transparency. On certain hardware, this can be faster than [constant DISTANCE_FADE_PIXEL_ALPHA]. </constant> <constant name="DISTANCE_FADE_OBJECT_DITHER" value="3" enum="DistanceFadeMode"> - Smoothly fades the object out based on the object's distance from the camera using a dither approach. Dithering discards pixels based on a set pattern to smoothly fade without enabling transparency. On certain hardware this can be faster than [constant DISTANCE_FADE_PIXEL_ALPHA]. + Smoothly fades the object out based on the object's distance from the camera using a dithering approach. Dithering discards pixels based on a set pattern to smoothly fade without enabling transparency. On certain hardware, this can be faster than [constant DISTANCE_FADE_PIXEL_ALPHA] and [constant DISTANCE_FADE_PIXEL_DITHER]. </constant> </constants> </class> diff --git a/doc/classes/Bone2D.xml b/doc/classes/Bone2D.xml index d452edd1aa..c421fe1543 100644 --- a/doc/classes/Bone2D.xml +++ b/doc/classes/Bone2D.xml @@ -31,12 +31,6 @@ [b]Note:[/b] This is different from the [code]Bone2D[/code]'s rotation. The bone angle is the rotation of the bone shown by the [code]Bone2D[/code] gizmo, and because [code]Bone2D[/code] bones are based on positions, this can vary from the actual rotation of the [code]Bone2D[/code] node. </description> </method> - <method name="get_default_length" qualifiers="const"> - <return type="float" /> - <description> - Deprecated. Please use [code]get_length[/code] instead. - </description> - </method> <method name="get_index_in_skeleton" qualifiers="const"> <return type="int" /> <description> @@ -70,13 +64,6 @@ [b]Note:[/b] This is different from the [code]Bone2D[/code]'s rotation. The bone angle is the rotation of the bone shown by the [code]Bone2D[/code] gizmo, and because [code]Bone2D[/code] bones are based on positions, this can vary from the actual rotation of the [code]Bone2D[/code] node. </description> </method> - <method name="set_default_length"> - <return type="void" /> - <param index="0" name="default_length" type="float" /> - <description> - Deprecated. Please use [code]set_length[/code] instead. - </description> - </method> <method name="set_length"> <return type="void" /> <param index="0" name="length" type="float" /> diff --git a/doc/classes/BoneAttachment3D.xml b/doc/classes/BoneAttachment3D.xml index dd01de3607..850aa4c2f2 100644 --- a/doc/classes/BoneAttachment3D.xml +++ b/doc/classes/BoneAttachment3D.xml @@ -33,14 +33,14 @@ <return type="void" /> <param index="0" name="external_skeleton" type="NodePath" /> <description> - Sets the [NodePath] to the external skeleton that the BoneAttachment3D node should use. The external [Skeleton3D] node is only used when [code]use_external_skeleton[/code] is set to [code]true[/code]. + Sets the [NodePath] to the external skeleton that the BoneAttachment3D node should use. See [method set_use_external_skeleton] to enable the external [Skeleton3D] node. </description> </method> <method name="set_use_external_skeleton"> <return type="void" /> <param index="0" name="use_external_skeleton" type="bool" /> <description> - Sets whether the BoneAttachment3D node will use an extenral [Skeleton3D] node rather than attenpting to use its parent node as the [Skeleton3D]. When set to [code]true[/code], the BoneAttachment3D node will use the external [Skeleton3D] node set in [code]set_external_skeleton[/code]. + Sets whether the BoneAttachment3D node will use an extenral [Skeleton3D] node rather than attenpting to use its parent node as the [Skeleton3D]. When set to [code]true[/code], the BoneAttachment3D node will use the external [Skeleton3D] node set in [method set_external_skeleton]. </description> </method> </methods> diff --git a/doc/classes/BoxMesh.xml b/doc/classes/BoxMesh.xml index 84e6d6f87d..f8cae0fc72 100644 --- a/doc/classes/BoxMesh.xml +++ b/doc/classes/BoxMesh.xml @@ -5,7 +5,7 @@ </brief_description> <description> Generate an axis-aligned box [PrimitiveMesh]. - The box's UV layout is arranged in a 3×2 layout that allows texturing each face individually. To apply the same texture on all faces, change the material's UV property to [code]Vector3(3, 2, 1)[/code]. + The box's UV layout is arranged in a 3×2 layout that allows texturing each face individually. To apply the same texture on all faces, change the material's UV property to [code]Vector3(3, 2, 1)[/code]. This is equivalent to adding [code]UV *= vec2(3.0, 2.0)[/code] in a vertex shader. [b]Note:[/b] When using a large textured [BoxMesh] (e.g. as a floor), you may stumble upon UV jittering issues depending on the camera angle. To solve this, increase [member subdivide_depth], [member subdivide_height] and [member subdivide_width] until you no longer notice UV jittering. </description> <tutorials> diff --git a/doc/classes/CPUParticles3D.xml b/doc/classes/CPUParticles3D.xml index 3a15a117f5..df31fa9621 100644 --- a/doc/classes/CPUParticles3D.xml +++ b/doc/classes/CPUParticles3D.xml @@ -143,7 +143,7 @@ Maximum damping. </member> <member name="damping_min" type="float" setter="set_param_min" getter="get_param_min" default="0.0"> - Minimum damping + Minimum damping. </member> <member name="direction" type="Vector3" setter="set_direction" getter="get_direction" default="Vector3(1, 0, 0)"> Unit vector specifying the particles' emission direction. diff --git a/doc/classes/Callable.xml b/doc/classes/Callable.xml index 8fc44d7536..50be9b86bf 100644 --- a/doc/classes/Callable.xml +++ b/doc/classes/Callable.xml @@ -173,14 +173,14 @@ <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 this method 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. See [method Node.rpc]. </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 this method 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. See [method Node.rpc_id]. </description> </method> <method name="unbind" qualifiers="const"> diff --git a/doc/classes/Camera2D.xml b/doc/classes/Camera2D.xml index 9315a85e1f..6a99647e46 100644 --- a/doc/classes/Camera2D.xml +++ b/doc/classes/Camera2D.xml @@ -55,6 +55,18 @@ [b]Note:[/b] The returned value is not the same as [member Node2D.global_position], as it is affected by the drag properties. It is also not the same as the current position if [member position_smoothing_enabled] is [code]true[/code] (see [method get_screen_center_position]). </description> </method> + <method name="is_current" qualifiers="const"> + <return type="bool" /> + <description> + Returns [code]true[/code] if this [Camera2D] is the active camera (see [method Viewport.get_camera_2d]). + </description> + </method> + <method name="make_current"> + <return type="void" /> + <description> + Forces this [Camera2D] to become the current active one. [member enabled] must be [code]true[/code]. + </description> + </method> <method name="reset_smoothing"> <return type="void" /> <description> @@ -83,9 +95,6 @@ <member name="anchor_mode" type="int" setter="set_anchor_mode" getter="get_anchor_mode" enum="Camera2D.AnchorMode" default="1"> The Camera2D's anchor point. See [enum AnchorMode] constants. </member> - <member name="current" type="bool" setter="set_current" getter="is_current" default="false"> - If [code]true[/code], the camera acts as the active camera for its [Viewport] ancestor. Only one camera can be current in a given viewport, so setting a different camera in the same viewport [code]current[/code] will disable whatever camera was already active in that viewport. - </member> <member name="custom_viewport" type="Node" setter="set_custom_viewport" getter="get_custom_viewport"> The custom [Viewport] node attached to the [Camera2D]. If [code]null[/code] or not a [Viewport], uses the default viewport instead. </member> @@ -124,6 +133,10 @@ <member name="editor_draw_screen" type="bool" setter="set_screen_drawing_enabled" getter="is_screen_drawing_enabled" default="true"> If [code]true[/code], draws the camera's screen rectangle in the editor. </member> + <member name="enabled" type="bool" setter="set_enabled" getter="is_enabled" default="true"> + Controls whether the camera can be active or not. If [code]true[/code], the [Camera2D] will become the main camera when it enters the scene tree and there is no active camera currently (see [method Viewport.get_camera_2d]). + When the camera is currently active and [member enabled] is set to [code]false[/code], the next enabled [Camera2D] in the scene tree will become active. + </member> <member name="ignore_rotation" type="bool" setter="set_ignore_rotation" getter="is_ignoring_rotation" default="true"> If [code]true[/code], the camera's rendered view is not affected by its [member Node2D.rotation] and [member Node2D.global_rotation]. </member> @@ -165,6 +178,7 @@ </member> <member name="zoom" type="Vector2" setter="set_zoom" getter="get_zoom" default="Vector2(1, 1)"> The camera's zoom. A zoom of [code]Vector(2, 2)[/code] doubles the size seen in the viewport. A zoom of [code]Vector(0.5, 0.5)[/code] halves the size seen in the viewport. + [b]Note:[/b] [member FontFile.oversampling] does [i]not[/i] take [Camera2D] zoom into account. This means that zooming in/out will cause bitmap fonts and rasterized (non-MSDF) dynamic fonts to appear blurry or pixelated unless the font is part of a [CanvasLayer] that makes it ignore camera zoom. To ensure text remains crisp regardless of zoom, you can enable MSDF font rendering by enabling [member ProjectSettings.gui/theme/default_font_multichannel_signed_distance_field] (applies to the default project font only), or enabling [b]Multichannel Signed Distance Field[/b] in the import options of a DynamicFont for custom fonts. On system fonts, [member SystemFont.multichannel_signed_distance_field] can be enabled in the inspector. </member> </members> <constants> diff --git a/doc/classes/CameraAttributesPhysical.xml b/doc/classes/CameraAttributesPhysical.xml index a61e735932..9512fd11a8 100644 --- a/doc/classes/CameraAttributesPhysical.xml +++ b/doc/classes/CameraAttributesPhysical.xml @@ -7,6 +7,7 @@ [CameraAttributesPhysical] is used to set rendering settings based on a physically-based camera's settings. It is responsible for exposure, auto-exposure, and depth of field. When used in a [WorldEnvironment] it provides default settings for exposure, auto-exposure, and depth of field that will be used by all cameras without their own [CameraAttributes], including the editor camera. When used in a [Camera3D] it will override any [CameraAttributes] set in the [WorldEnvironment] and will override the [Camera3D]s [member Camera3D.far], [member Camera3D.near], [member Camera3D.fov], and [member Camera3D.keep_aspect] properties. When used in [VoxelGI] or [LightmapGI], only the exposure settings will be used. The default settings are intended for use in an outdoor environment, tips for settings for use in an indoor environment can be found in each setting's documentation. + [b]Note:[/b] Depth of field blur is only supported in the Forward+ and Mobile rendering methods, not Compatibility. </description> <tutorials> </tutorials> diff --git a/doc/classes/CameraAttributesPractical.xml b/doc/classes/CameraAttributesPractical.xml index 924b02fc79..cd914c9eb7 100644 --- a/doc/classes/CameraAttributesPractical.xml +++ b/doc/classes/CameraAttributesPractical.xml @@ -24,6 +24,7 @@ </member> <member name="dof_blur_far_enabled" type="bool" setter="set_dof_blur_far_enabled" getter="is_dof_blur_far_enabled" default="false"> Enables depth of field blur for objects further than [member dof_blur_far_distance]. Strength of blur is controlled by [member dof_blur_amount] and modulated by [member dof_blur_far_transition]. + [b]Note:[/b] Depth of field blur is only supported in the Forward+ and Mobile rendering methods, not Compatibility. </member> <member name="dof_blur_far_transition" type="float" setter="set_dof_blur_far_transition" getter="get_dof_blur_far_transition" default="5.0"> When positive, distance over which (starting from [member dof_blur_far_distance]) blur effect will scale from 0 to [member dof_blur_amount]. When negative, uses physically-based scaling so depth of field effect will scale from 0 at [member dof_blur_far_distance] and will increase in a physically accurate way as objects get further from the [Camera3D]. @@ -33,6 +34,7 @@ </member> <member name="dof_blur_near_enabled" type="bool" setter="set_dof_blur_near_enabled" getter="is_dof_blur_near_enabled" default="false"> Enables depth of field blur for objects closer than [member dof_blur_near_distance]. Strength of blur is controlled by [member dof_blur_amount] and modulated by [member dof_blur_near_transition]. + [b]Note:[/b] Depth of field blur is only supported in the Forward+ and Mobile rendering methods, not Compatibility. </member> <member name="dof_blur_near_transition" type="float" setter="set_dof_blur_near_transition" getter="get_dof_blur_near_transition" default="1.0"> When positive, distance over which blur effect will scale from 0 to [member dof_blur_amount], ending at [member dof_blur_near_distance]. When negative, uses physically-based scaling so depth of field effect will scale from 0 at [member dof_blur_near_distance] and will increase in a physically accurate way as objects get closer to the [Camera3D]. diff --git a/doc/classes/CanvasGroup.xml b/doc/classes/CanvasGroup.xml index 6eeff8fef3..45f77ba484 100644 --- a/doc/classes/CanvasGroup.xml +++ b/doc/classes/CanvasGroup.xml @@ -8,6 +8,7 @@ [b]Note:[/b] The [CanvasGroup] uses a custom shader to read from the backbuffer to draw its children. Assigning a [Material] to the [CanvasGroup] overrides the builtin shader. To duplicate the behavior of the builtin shader in a custom [Shader] use the following: [codeblock] shader_type canvas_item; + render_mode unshaded; uniform sampler2D screen_texture : hint_screen_texture, repeat_disable, filter_nearest; diff --git a/doc/classes/CanvasItem.xml b/doc/classes/CanvasItem.xml index c3c768c12d..f99d90d32c 100644 --- a/doc/classes/CanvasItem.xml +++ b/doc/classes/CanvasItem.xml @@ -292,6 +292,7 @@ <param index="2" name="scale" type="Vector2" default="Vector2(1, 1)" /> <description> Sets a custom transform for drawing via components. Anything drawn afterwards will be transformed by this. + [b]Note:[/b] [member FontFile.oversampling] does [i]not[/i] take [param scale] into account. This means that scaling up/down will cause bitmap fonts and rasterized (non-MSDF) dynamic fonts to appear blurry or pixelated. To ensure text remains crisp regardless of scale, you can enable MSDF font rendering by enabling [member ProjectSettings.gui/theme/default_font_multichannel_signed_distance_field] (applies to the default project font only), or enabling [b]Multichannel Signed Distance Field[/b] in the import options of a DynamicFont for custom fonts. On system fonts, [member SystemFont.multichannel_signed_distance_field] can be enabled in the inspector. </description> </method> <method name="draw_set_transform_matrix"> diff --git a/doc/classes/CanvasLayer.xml b/doc/classes/CanvasLayer.xml index ce999c06d3..cc8c84d082 100644 --- a/doc/classes/CanvasLayer.xml +++ b/doc/classes/CanvasLayer.xml @@ -50,7 +50,7 @@ Scales the layer when using [member follow_viewport_enabled]. Layers moving into the foreground should have increasing scales, while layers moving into the background should have decreasing scales. </member> <member name="layer" type="int" setter="set_layer" getter="get_layer" default="1"> - Layer index for draw order. Lower values are drawn first. + Layer index for draw order. Lower values are drawn behind higher values. </member> <member name="offset" type="Vector2" setter="set_offset" getter="get_offset" default="Vector2(0, 0)"> The layer's base offset. diff --git a/doc/classes/CharacterBody2D.xml b/doc/classes/CharacterBody2D.xml index 7395556d05..51cc752cae 100644 --- a/doc/classes/CharacterBody2D.xml +++ b/doc/classes/CharacterBody2D.xml @@ -71,10 +71,10 @@ print("Collided with: ", collision.collider.name) [/gdscript] [csharp] - for (int i = 0; i < GetSlideCount(); i++) + for (int i = 0; i < GetSlideCollisionCount(); i++) { KinematicCollision2D collision = GetSlideCollision(i); - GD.Print("Collided with: ", (collision.Collider as Node).Name); + GD.Print("Collided with: ", (collision.GetCollider() as Node).Name); } [/csharp] [/codeblocks] diff --git a/doc/classes/CodeEdit.xml b/doc/classes/CodeEdit.xml index df40d2a4cf..65a6668f43 100644 --- a/doc/classes/CodeEdit.xml +++ b/doc/classes/CodeEdit.xml @@ -62,7 +62,7 @@ <description> Adds a comment delimiter. Both the start and end keys must be symbols. Only the start key has to be unique. - Line only denotes if the region should continue until the end of the line or carry over on to the next line. If the end key is blank this is automatically set to [code]true[/code]. + [param line_only] denotes if the region should continue until the end of the line or carry over on to the next line. If the end key is blank this is automatically set to [code]true[/code]. </description> </method> <method name="add_string_delimiter"> @@ -73,7 +73,7 @@ <description> Adds a string delimiter. Both the start and end keys must be symbols. Only the start key has to be unique. - Line only denotes if the region should continue until the end of the line or carry over on to the next line. If the end key is blank this is automatically set to [code]true[/code]. + [param line_only] denotes if the region should continue until the end of the line or carry over on to the next line. If the end key is blank this is automatically set to [code]true[/code]. </description> </method> <method name="can_fold_line" qualifiers="const"> @@ -486,7 +486,7 @@ Sets whether line folding is allowed. </member> <member name="line_length_guidelines" type="int[]" setter="set_line_length_guidelines" getter="get_line_length_guidelines" default="[]"> - Draws vertical lines at the provided columns. The first entry is considered a main hard guideline and is draw more prominently + Draws vertical lines at the provided columns. The first entry is considered a main hard guideline and is draw more prominently. </member> <member name="symbol_lookup_on_click" type="bool" setter="set_symbol_lookup_on_click_enabled" getter="is_symbol_lookup_on_click_enabled" default="false"> Set when a validated word from [signal symbol_validate] is clicked, the [signal symbol_lookup] should be emitted. diff --git a/doc/classes/CodeHighlighter.xml b/doc/classes/CodeHighlighter.xml index fd1f595fc6..eedd4c1769 100644 --- a/doc/classes/CodeHighlighter.xml +++ b/doc/classes/CodeHighlighter.xml @@ -18,7 +18,7 @@ <description> Adds a color region such as comments or strings. Both the start and end keys must be symbols. Only the start key has to be unique. - Line only denotes if the region should continue until the end of the line or carry over on to the next line. If the end key is blank this is automatically set to [code]true[/code]. + [param line_only] denotes if the region should continue until the end of the line or carry over on to the next line. If the end key is blank this is automatically set to [code]true[/code]. </description> </method> <method name="add_keyword_color"> diff --git a/doc/classes/Color.xml b/doc/classes/Color.xml index 57278d9241..faa658971d 100644 --- a/doc/classes/Color.xml +++ b/doc/classes/Color.xml @@ -203,18 +203,18 @@ <return type="Color" /> <param index="0" name="hex" type="int" /> <description> - Returns the [Color] associated with the provided [param hex] integer in 32-bit ARGB format (8 bits per channel, alpha channel first). + Returns the [Color] associated with the provided [param hex] integer in 32-bit RGBA format (8 bits per channel, alpha channel first). In GDScript and C#, the [int] is best visualized with hexadecimal notation ([code]"0x"[/code] prefix). [codeblocks] [gdscript] - var red = Color.hex(0xffff0000) - var dark_cyan = Color.hex(0xff008b8b) - var my_color = Color.hex(0xa4bbefd2) + var red = Color.hex(0xff0000ff) + var dark_cyan = Color.hex(0x008b8bff) + var my_color = Color.hex(0xbbefd2a4) [/gdscript] [csharp] - var red = new Color(0xffff0000); - var dark_cyan = new Color(0xff008b8b); - var my_color = new Color(0xa4bbefd2); + var red = new Color(0xff0000ff); + var dark_cyan = new Color(0x008b8bff); + var my_color = new Color(0xbbefd2a4); [/csharp] [/codeblocks] </description> @@ -223,7 +223,7 @@ <return type="Color" /> <param index="0" name="hex" type="int" /> <description> - Returns the [Color] associated with the provided [param hex] integer in 64-bit ARGB format (16 bits per channel, alpha channel first). + Returns the [Color] associated with the provided [param hex] integer in 64-bit RGBA format (16 bits per channel, alpha channel first). In GDScript and C#, the [int] is best visualized with hexadecimal notation ([code]"0x"[/code] prefix). </description> </method> @@ -233,7 +233,6 @@ <description> Returns a new color from [param rgba], an HTML hexadecimal color string. [param rgba] is not case-sensitive, and may be prefixed by a hash sign ([code]#[/code]). [param rgba] must be a valid three-digit or six-digit hexadecimal color string, and may contain an alpha channel value. If [param rgba] does not contain an alpha channel value, an alpha channel value of 1.0 is applied. If [param rgba] is invalid, returns an empty color. - [b]Note:[/b] In C#, this method is not implemented. The same functionality is provided by the Color constructor. [codeblocks] [gdscript] var blue = Color.html("#0000ff") # blue is Color(0.0, 0.0, 1.0, 1.0) @@ -264,13 +263,13 @@ Color.html_is_valid("#55aaFF5") # Returns false [/gdscript] [csharp] - Color.IsHtmlValid("#55AAFF"); // Returns true - Color.IsHtmlValid("#55AAFF20"); // Returns true - Color.IsHtmlValid("55AAFF"); // Returns true - Color.IsHtmlValid("#F2C"); // Returns true + Color.HtmlIsValid("#55AAFF"); // Returns true + Color.HtmlIsValid("#55AAFF20"); // Returns true + Color.HtmlIsValid("55AAFF"); // Returns true + Color.HtmlIsValid("#F2C"); // Returns true - Color.IsHtmlValid("#AABBC"); // Returns false - Color.IsHtmlValid("#55aaFF5"); // Returns false + Color.HtmlIsValid("#AABBC"); // Returns false + Color.HtmlIsValid("#55aaFF5"); // Returns false [/csharp] [/codeblocks] </description> diff --git a/doc/classes/Control.xml b/doc/classes/Control.xml index 0d675112b8..f2ab6cb07e 100644 --- a/doc/classes/Control.xml +++ b/doc/classes/Control.xml @@ -37,11 +37,11 @@ return typeof(data) == TYPE_DICTIONARY and data.has("expected") [/gdscript] [csharp] - public override bool CanDropData(Vector2 position, object data) + public override bool _CanDropData(Vector2 atPosition, Variant data) { // Check position if it is relevant to you // Otherwise, just check data - return data is Godot.Collections.Dictionary && (data as Godot.Collections.Dictionary).Contains("expected"); + return data.VariantType == Variant.Type.Dictionary && data.AsGodotDictionary().Contains("expected"); } [/csharp] [/codeblocks] @@ -57,17 +57,19 @@ [gdscript] func _can_drop_data(position, data): return typeof(data) == TYPE_DICTIONARY and data.has("color") + func _drop_data(position, data): var color = data["color"] [/gdscript] [csharp] - public override bool CanDropData(Vector2 position, object data) + public override bool _CanDropData(Vector2 atPosition, Variant data) { - return data is Godot.Collections.Dictionary && (data as Godot.Collections.Dictionary).Contains("color"); + return data.VariantType == Variant.Type.Dictionary && dict.AsGodotDictionary().Contains("color"); } - public override void DropData(Vector2 position, object data) + + public override void _DropData(Vector2 atPosition, Variant data) { - Color color = (Color)(data as Godot.Collections.Dictionary)["color"]; + Color color = data.AsGodotDictionary()["color"].AsColor(); } [/csharp] [/codeblocks] @@ -87,11 +89,11 @@ return mydata [/gdscript] [csharp] - public override object GetDragData(Vector2 position) + public override Variant _GetDragData(Vector2 atPosition) { - object mydata = MakeData(); // This is your custom method generating the drag data. - SetDragPreview(MakePreview(mydata)); // This is your custom method generating the preview of the drag data. - return mydata; + var myData = MakeData(); // This is your custom method generating the drag data. + SetDragPreview(MakePreview(myData)); // This is your custom method generating the preview of the drag data. + return myData; } [/csharp] [/codeblocks] @@ -121,10 +123,9 @@ [csharp] public override void _GuiInput(InputEvent @event) { - if (@event is InputEventMouseButton) + if (@event is InputEventMouseButton mb) { - var mb = @event as InputEventMouseButton; - if (mb.ButtonIndex == (int)ButtonList.Left && mb.Pressed) + if (mb.ButtonIndex == MouseButton.Left && mb.Pressed) { GD.Print("I've been clicked D:"); } @@ -143,11 +144,11 @@ </method> <method name="_has_point" qualifiers="virtual const"> <return type="bool" /> - <param index="0" name="position" type="Vector2" /> + <param index="0" name="point" type="Vector2" /> <description> - Virtual method to be implemented by the user. Returns whether the given [param position] is inside this control. + Virtual method to be implemented by the user. Returns whether the given [param point] is inside this control. If not overridden, default behavior is checking if the point is within control's Rect. - [b]Note:[/b] If you want to check if a point is inside the control, you can use [code]get_rect().has_point(point)[/code]. + [b]Note:[/b] If you want to check if a point is inside the control, you can use [code]Rect2(Vector2.ZERO, size).has_point(point)[/code]. </description> </method> <method name="_make_custom_tooltip" qualifiers="virtual const"> @@ -168,7 +169,7 @@ return label [/gdscript] [csharp] - public override Godot.Control _MakeCustomTooltip(String forText) + public override Control _MakeCustomTooltip(string forText) { var label = new Label(); label.Text = forText; @@ -185,7 +186,7 @@ return tooltip [/gdscript] [csharp] - public override Godot.Control _MakeCustomTooltip(String forText) + public override Control _MakeCustomTooltip(string forText) { Node tooltip = ResourceLoader.Load<PackedScene>("res://some_tooltip_scene.tscn").Instantiate(); tooltip.GetNode<Label>("Label").Text = forText; @@ -229,11 +230,11 @@ [/gdscript] [csharp] // Given the child Label node "MyLabel", override its font color with a custom value. - GetNode<Label>("MyLabel").AddThemeColorOverride("font_color", new Color(1, 0.5f, 0)) + GetNode<Label>("MyLabel").AddThemeColorOverride("font_color", new Color(1, 0.5f, 0)); // Reset the font color of the child label. - GetNode<Label>("MyLabel").RemoveThemeColorOverride("font_color") + GetNode<Label>("MyLabel").RemoveThemeColorOverride("font_color"); // Alternatively it can be overridden with the default value from the Label type. - GetNode<Label>("MyLabel").AddThemeColorOverride("font_color", GetThemeColor("font_color", "Label")) + GetNode<Label>("MyLabel").AddThemeColorOverride("font_color", GetThemeColor("font_color", "Label")); [/csharp] [/codeblocks] </description> @@ -542,12 +543,12 @@ [codeblocks] [gdscript] func _process(delta): - grab_click_focus() #when clicking another Control node, this node will be clicked instead + grab_click_focus() # When clicking another Control node, this node will be clicked instead. [/gdscript] [csharp] - public override void _Process(float delta) + public override void _Process(double delta) { - GrabClickFocus(); //when clicking another Control node, this node will be clicked instead + GrabClickFocus(); // When clicking another Control node, this node will be clicked instead. } [/csharp] [/codeblocks] @@ -557,7 +558,7 @@ <return type="void" /> <description> Steal the focus from another control and become the focused control (see [member focus_mode]). - [b]Note[/b]: Using this method together with [method Callable.call_deferred] makes it more reliable, especially when called inside [method Node._ready]. + [b]Note:[/b] Using this method together with [method Callable.call_deferred] makes it more reliable, especially when called inside [method Node._ready]. </description> </method> <method name="has_focus" qualifiers="const"> @@ -800,7 +801,7 @@ Shows the given control at the mouse pointer. A good time to call this method is in [method _get_drag_data]. The control must not be in the scene tree. You should not free the control, and you should not keep a reference to the control beyond the duration of the drag. It will be deleted automatically after the drag has ended. [codeblocks] [gdscript] - export (Color, RGBA) var color = Color(1, 0, 0, 1) + @export var color = Color(1, 0, 0, 1) func _get_drag_data(position): # Use a control that is not in the tree @@ -812,16 +813,16 @@ [/gdscript] [csharp] [Export] - public Color Color = new Color(1, 0, 0, 1); + private Color _color = new Color(1, 0, 0, 1); - public override object GetDragData(Vector2 position) + public override Variant _GetDragData(Vector2 atPosition) { // Use a control that is not in the tree var cpb = new ColorPickerButton(); - cpb.Color = Color; - cpb.RectSize = new Vector2(50, 50); + cpb.Color = _color; + cpb.Size = new Vector2(50, 50); SetDragPreview(cpb); - return Color; + return _color; } [/csharp] [/codeblocks] @@ -1000,13 +1001,15 @@ </member> <member name="rotation" type="float" setter="set_rotation" getter="get_rotation" default="0.0"> The node's rotation around its pivot, in radians. See [member pivot_offset] to change the pivot's position. + [b]Note:[/b] This property is edited in the inspector in degrees. If you want to use degrees in a script, use [member rotation_degrees]. </member> <member name="rotation_degrees" type="float" setter="set_rotation_degrees" getter="get_rotation_degrees"> Helper property to access [member rotation] in degrees instead of radians. </member> <member name="scale" type="Vector2" setter="set_scale" getter="get_scale" default="Vector2(1, 1)"> The node's scale, relative to its [member size]. Change this property to scale the node around its [member pivot_offset]. The Control's [member tooltip_text] will also scale according to this value. - [b]Note:[/b] This property is mainly intended to be used for animation purposes. Text inside the Control will look pixelated or blurry when the Control is scaled. To support multiple resolutions in your project, use an appropriate viewport stretch mode as described in the [url=$DOCS_URL/tutorials/rendering/multiple_resolutions.html]documentation[/url] instead of scaling Controls individually. + [b]Note:[/b] This property is mainly intended to be used for animation purposes. To support multiple resolutions in your project, use an appropriate viewport stretch mode as described in the [url=$DOCS_URL/tutorials/rendering/multiple_resolutions.html]documentation[/url] instead of scaling Controls individually. + [b]Note:[/b] [member FontFile.oversampling] does [i]not[/i] take [Control] [member scale] into account. This means that scaling up/down will cause bitmap fonts and rasterized (non-MSDF) dynamic fonts to appear blurry or pixelated. To ensure text remains crisp regardless of scale, you can enable MSDF font rendering by enabling [member ProjectSettings.gui/theme/default_font_multichannel_signed_distance_field] (applies to the default project font only), or enabling [b]Multichannel Signed Distance Field[/b] in the import options of a DynamicFont for custom fonts. On system fonts, [member SystemFont.multichannel_signed_distance_field] can be enabled in the inspector. [b]Note:[/b] If the Control node is a child of a [Container] node, the scale will be reset to [code]Vector2(1, 1)[/code] when the scene is instantiated. To set the Control's scale when it's instantiated, wait for one frame using [code]await get_tree().process_frame[/code] then set its [member scale] property. </member> <member name="shortcut_context" type="Node" setter="set_shortcut_context" getter="get_shortcut_context"> diff --git a/doc/classes/Crypto.xml b/doc/classes/Crypto.xml index ade63225dc..a7e7e756c6 100644 --- a/doc/classes/Crypto.xml +++ b/doc/classes/Crypto.xml @@ -9,9 +9,11 @@ [codeblocks] [gdscript] extends Node + var crypto = Crypto.new() var key = CryptoKey.new() var cert = X509Certificate.new() + func _ready(): # Generate new RSA key. key = crypto.generate_rsa(4096) @@ -35,35 +37,35 @@ [/gdscript] [csharp] using Godot; - using System; using System.Diagnostics; - public class CryptoNode : Node + public partial class MyNode : Node { - public Crypto Crypto = new Crypto(); - public CryptoKey Key = new CryptoKey(); - public X509Certificate Cert = new X509Certificate(); + private Crypto _crypto = new Crypto(); + private CryptoKey _key = new CryptoKey(); + private X509Certificate _cert = new X509Certificate(); + public override void _Ready() { // Generate new RSA key. - Key = Crypto.GenerateRsa(4096); + _key = _crypto.GenerateRsa(4096); // Generate new self-signed certificate with the given key. - Cert = Crypto.GenerateSelfSignedCertificate(Key, "CN=mydomain.com,O=My Game Company,C=IT"); + _cert = _crypto.GenerateSelfSignedCertificate(_key, "CN=mydomain.com,O=My Game Company,C=IT"); // Save key and certificate in the user folder. - Key.Save("user://generated.key"); - Cert.Save("user://generated.crt"); + _key.Save("user://generated.key"); + _cert.Save("user://generated.crt"); // Encryption string data = "Some data"; - byte[] encrypted = Crypto.Encrypt(Key, data.ToUTF8()); + byte[] encrypted = _crypto.Encrypt(_key, data.ToUtf8()); // Decryption - byte[] decrypted = Crypto.Decrypt(Key, encrypted); + byte[] decrypted = _crypto.Decrypt(_key, encrypted); // Signing - byte[] signature = Crypto.Sign(HashingContext.HashType.Sha256, Data.SHA256Buffer(), Key); + byte[] signature = _crypto.Sign(HashingContext.HashType.Sha256, Data.Sha256Buffer(), _key); // Verifying - bool verified = Crypto.Verify(HashingContext.HashType.Sha256, Data.SHA256Buffer(), signature, Key); + bool verified = _crypto.Verify(HashingContext.HashType.Sha256, Data.Sha256Buffer(), signature, _key); // Checks Debug.Assert(verified); - Debug.Assert(data.ToUTF8() == decrypted); + Debug.Assert(data.ToUtf8() == decrypted); } } [/csharp] diff --git a/doc/classes/DTLSServer.xml b/doc/classes/DTLSServer.xml index a3a0b0456c..ae1ba10ec7 100644 --- a/doc/classes/DTLSServer.xml +++ b/doc/classes/DTLSServer.xml @@ -38,45 +38,46 @@ p.put_packet("Hello DTLS client".to_utf8()) [/gdscript] [csharp] - using Godot; - using System; // ServerNode.cs - public class ServerNode : Node + using Godot; + + public partial class ServerNode : Node { - public DTLSServer Dtls = new DTLSServer(); - public UDPServer Server = new UDPServer(); - public Godot.Collections.Array<PacketPeerDTLS> Peers = new Godot.Collections.Array<PacketPeerDTLS>(); + private DtlsServer _dtls = new DtlsServer(); + private UdpServer _server = new UdpServer(); + private Godot.Collections.Array<PacketPeerDTLS> _peers = new Godot.Collections.Array<PacketPeerDTLS>(); + public override void _Ready() { - Server.Listen(4242); + _server.Listen(4242); var key = GD.Load<CryptoKey>("key.key"); // Your private key. var cert = GD.Load<X509Certificate>("cert.crt"); // Your X509 certificate. - Dtls.Setup(key, cert); + _dtls.Setup(key, cert); } - public override void _Process(float delta) + public override void _Process(double delta) { while (Server.IsConnectionAvailable()) { - PacketPeerUDP peer = Server.TakeConnection(); - PacketPeerDTLS dtlsPeer = Dtls.TakeConnection(peer); - if (dtlsPeer.GetStatus() != PacketPeerDTLS.Status.Handshaking) + PacketPeerUDP peer = _server.TakeConnection(); + PacketPeerDTLS dtlsPeer = _dtls.TakeConnection(peer); + if (dtlsPeer.GetStatus() != PacketPeerDtls.Status.Handshaking) { continue; // It is normal that 50% of the connections fails due to cookie exchange. } GD.Print("Peer connected!"); - Peers.Add(dtlsPeer); + _peers.Add(dtlsPeer); } - foreach (var p in Peers) + foreach (var p in _peers) { p.Poll(); // Must poll to update the state. - if (p.GetStatus() == PacketPeerDTLS.Status.Connected) + if (p.GetStatus() == PacketPeerDtls.Status.Connected) { while (p.GetAvailablePacketCount() > 0) { - GD.Print("Received Message From Client: " + p.GetPacket().GetStringFromUTF8()); - p.PutPacket("Hello Dtls Client".ToUTF8()); + GD.Print($"Received Message From Client: {p.GetPacket().GetStringFromUtf8()}"); + p.PutPacket("Hello DTLS Client".ToUtf8()); } } } @@ -108,34 +109,36 @@ connected = true [/gdscript] [csharp] + // ClientNode.cs using Godot; using System.Text; - // ClientNode.cs - public class ClientNode : Node + + public partial class ClientNode : Node { - public PacketPeerDTLS Dtls = new PacketPeerDTLS(); - public PacketPeerUDP Udp = new PacketPeerUDP(); - public bool Connected = false; + private PacketPeerDtls _dtls = new PacketPeerDtls(); + private PacketPeerUdp _udp = new PacketPeerUdp(); + private bool _connected = false; + public override void _Ready() { - Udp.ConnectToHost("127.0.0.1", 4242); - Dtls.ConnectToPeer(Udp, false); // Use true in production for certificate validation! + _udp.ConnectToHost("127.0.0.1", 4242); + _dtls.ConnectToPeer(_udp, validateCerts: false); // Use true in production for certificate validation! } - public override void _Process(float delta) + public override void _Process(double delta) { - Dtls.Poll(); - if (Dtls.GetStatus() == PacketPeerDTLS.Status.Connected) + _dtls.Poll(); + if (_dtls.GetStatus() == PacketPeerDtls.Status.Connected) { - if (!Connected) + if (!_connected) { // Try to contact server - Dtls.PutPacket("The Answer Is..42!".ToUTF8()); + _dtls.PutPacket("The Answer Is..42!".ToUtf8()); } - while (Dtls.GetAvailablePacketCount() > 0) + while (_dtls.GetAvailablePacketCount() > 0) { - GD.Print("Connected: " + Dtls.GetPacket().GetStringFromUTF8()); - Connected = true; + GD.Print($"Connected: {_dtls.GetPacket().GetStringFromUtf8()}"); + _connected = true; } } } diff --git a/doc/classes/Decal.xml b/doc/classes/Decal.xml index b9d3f1d81e..824416e4d4 100644 --- a/doc/classes/Decal.xml +++ b/doc/classes/Decal.xml @@ -8,6 +8,8 @@ They are made of an [AABB] and a group of [Texture2D]s specifying [Color], normal, ORM (ambient occlusion, roughness, metallic), and emission. Decals are projected within their [AABB] so altering the orientation of the Decal affects the direction in which they are projected. By default, Decals are projected down (i.e. from positive Y to negative Y). The [Texture2D]s associated with the Decal are automatically stored in a texture atlas which is used for drawing the decals so all decals can be drawn at once. Godot uses clustered decals, meaning they are stored in cluster data and drawn when the mesh is drawn, they are not drawn as a post-processing effect after. [b]Note:[/b] Decals cannot affect an underlying material's transparency, regardless of its transparency mode (alpha blend, alpha scissor, alpha hash, opaque pre-pass). This means translucent or transparent areas of a material will remain translucent or transparent even if an opaque decal is applied on them. + [b]Note:[/b] Decals are only supported in the Forward+ and Mobile rendering methods, not Compatibility. When using the Mobile rendering method, only 8 decals can be displayed on each mesh resource. Attempting to display more than 8 decals on a single mesh resource will result in decals flickering in and out as the camera moves. + [b]Note:[/b] When using the Mobile rendering method, decals will only correctly affect meshes whose visibility AABB intersects with the decal's AABB. If using a shader to deform the mesh in a way that makes it go outside its AABB, [member GeometryInstance3D.extra_cull_margin] must be increased on the mesh. Otherwise, the decal may not be visible on the mesh. </description> <tutorials> </tutorials> @@ -75,9 +77,6 @@ <member name="emission_energy" type="float" setter="set_emission_energy" getter="get_emission_energy" default="1.0"> Energy multiplier for the emission texture. This will make the decal emit light at a higher or lower intensity, independently of the albedo color. See also [member modulate]. </member> - <member name="extents" type="Vector3" setter="set_extents" getter="get_extents" default="Vector3(1, 1, 1)"> - Sets the size of the [AABB] used by the decal. The AABB goes from [code]-extents[/code] to [code]extents[/code]. - </member> <member name="lower_fade" type="float" setter="set_lower_fade" getter="get_lower_fade" default="0.3"> Sets the curve over which the decal will fade as the surface gets further from the center of the [AABB]. Only positive values are valid (negative values will be clamped to [code]0.0[/code]). See also [member upper_fade]. </member> @@ -88,12 +87,16 @@ Fades the Decal if the angle between the Decal's [AABB] and the target surface becomes too large. A value of [code]0[/code] projects the Decal regardless of angle, a value of [code]1[/code] limits the Decal to surfaces that are nearly perpendicular. [b]Note:[/b] Setting [member normal_fade] to a value greater than [code]0.0[/code] has a small performance cost due to the added normal angle computations. </member> + <member name="size" type="Vector3" setter="set_size" getter="get_size" default="Vector3(2, 2, 2)"> + Sets the size of the [AABB] used by the decal. All dimensions must be set to a value greater than zero (they will be clamped to [code]0.001[/code] if this is not the case). The AABB goes from [code]-size/2[/code] to [code]size/2[/code]. + [b]Note:[/b] To improve culling efficiency of "hard surface" decals, set their [member upper_fade] and [member lower_fade] to [code]0.0[/code] and set the Y component of the [member size] as low as possible. This will reduce the decals' AABB size without affecting their appearance. + </member> <member name="texture_albedo" type="Texture2D" setter="set_texture" getter="get_texture"> [Texture2D] with the base [Color] of the Decal. Either this or the [member texture_emission] must be set for the Decal to be visible. Use the alpha channel like a mask to smoothly blend the edges of the decal with the underlying object. [b]Note:[/b] Unlike [BaseMaterial3D] whose filter mode can be adjusted on a per-material basis, the filter mode for [Decal] textures is set globally with [member ProjectSettings.rendering/textures/decals/filter]. </member> <member name="texture_emission" type="Texture2D" setter="set_texture" getter="get_texture"> - [Texture2D] with the emission [Color] of the Decal. Either this or the [member texture_emission] must be set for the Decal to be visible. Use the alpha channel like a mask to smoothly blend the edges of the decal with the underlying object. + [Texture2D] with the emission [Color] of the Decal. Either this or the [member texture_albedo] must be set for the Decal to be visible. Use the alpha channel like a mask to smoothly blend the edges of the decal with the underlying object. [b]Note:[/b] Unlike [BaseMaterial3D] whose filter mode can be adjusted on a per-material basis, the filter mode for [Decal] textures is set globally with [member ProjectSettings.rendering/textures/decals/filter]. </member> <member name="texture_normal" type="Texture2D" setter="set_texture" getter="get_texture"> diff --git a/doc/classes/Dictionary.xml b/doc/classes/Dictionary.xml index 1591aa59bf..a5a50b4c6a 100644 --- a/doc/classes/Dictionary.xml +++ b/doc/classes/Dictionary.xml @@ -51,7 +51,7 @@ [csharp] [Export(PropertyHint.Enum, "White,Yellow,Orange")] public string MyColor { get; set; } - public Godot.Collections.Dictionary pointsDict = new Godot.Collections.Dictionary + private Godot.Collections.Dictionary _pointsDict = new Godot.Collections.Dictionary { {"White", 50}, {"Yellow", 75}, @@ -60,7 +60,7 @@ public override void _Ready() { - int points = (int)pointsDict[MyColor]; + int points = (int)_pointsDict[MyColor]; } [/csharp] [/codeblocks] diff --git a/doc/classes/DirAccess.xml b/doc/classes/DirAccess.xml index 181d2eb485..27f2eb7f2f 100644 --- a/doc/classes/DirAccess.xml +++ b/doc/classes/DirAccess.xml @@ -44,11 +44,11 @@ { if (dir.CurrentIsDir()) { - GD.Print("Found directory: " + fileName); + GD.Print($"Found directory: {fileName}"); } else { - GD.Print("Found file: " + fileName); + GD.Print($"Found file: {fileName}"); } fileName = dir.GetNext(); } diff --git a/doc/classes/DirectionalLight2D.xml b/doc/classes/DirectionalLight2D.xml index f825a9e082..eb710efda2 100644 --- a/doc/classes/DirectionalLight2D.xml +++ b/doc/classes/DirectionalLight2D.xml @@ -5,6 +5,7 @@ </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). + [b]Note:[/b] [DirectionalLight2D] does not support light cull masks (but it supports shadow cull masks). It will always light up 2D nodes, regardless of the 2D node's [member CanvasItem.light_mask]. </description> <tutorials> <link title="2D lights and shadows">$DOCS_URL/tutorials/2d/2d_lights_and_shadows.html</link> diff --git a/doc/classes/DisplayServer.xml b/doc/classes/DisplayServer.xml index 6f4a7fc13d..5f25bd8925 100644 --- a/doc/classes/DisplayServer.xml +++ b/doc/classes/DisplayServer.xml @@ -190,6 +190,7 @@ <description> Adds a new checkable item with text [param label] to the global menu with ID [param menu_root]. Returns index of the inserted item, it's not guaranteed to be the same as [param index] value. + An [param accelerator] can optionally be defined, which is a keyboard shortcut that can be pressed to trigger the menu button even if it's not currently open. The [param accelerator] is generally a combination of [enum KeyModifierMask]s and [enum Key]s using boolean OR such as [code]KEY_MASK_CTRL | KEY_A[/code] ([kbd]Ctrl + A[/kbd]). [b]Note:[/b] The [param callback] and [param key_callback] Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to [param tag]. [b]Note:[/b] This method is implemented on macOS. [b]Supported system menu IDs:[/b] @@ -212,6 +213,7 @@ <description> Adds a new checkable item with text [param label] and icon [param icon] to the global menu with ID [param menu_root]. Returns index of the inserted item, it's not guaranteed to be the same as [param index] value. + An [param accelerator] can optionally be defined, which is a keyboard shortcut that can be pressed to trigger the menu button even if it's not currently open. The [param accelerator] is generally a combination of [enum KeyModifierMask]s and [enum Key]s using boolean OR such as [code]KEY_MASK_CTRL | KEY_A[/code] ([kbd]Ctrl + A[/kbd]). [b]Note:[/b] The [param callback] and [param key_callback] Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to [param tag]. [b]Note:[/b] This method is implemented on macOS. [b]Supported system menu IDs:[/b] @@ -234,6 +236,7 @@ <description> Adds a new item with text [param label] and icon [param icon] to the global menu with ID [param menu_root]. Returns index of the inserted item, it's not guaranteed to be the same as [param index] value. + An [param accelerator] can optionally be defined, which is a keyboard shortcut that can be pressed to trigger the menu button even if it's not currently open. The [param accelerator] is generally a combination of [enum KeyModifierMask]s and [enum Key]s using boolean OR such as [code]KEY_MASK_CTRL | KEY_A[/code] ([kbd]Ctrl + A[/kbd]). [b]Note:[/b] The [param callback] and [param key_callback] Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to [param tag]. [b]Note:[/b] This method is implemented on macOS. [b]Supported system menu IDs:[/b] @@ -256,6 +259,7 @@ <description> Adds a new radio-checkable item with text [param label] and icon [param icon] to the global menu with ID [param menu_root]. Returns index of the inserted item, it's not guaranteed to be the same as [param index] value. + An [param accelerator] can optionally be defined, which is a keyboard shortcut that can be pressed to trigger the menu button even if it's not currently open. The [param accelerator] is generally a combination of [enum KeyModifierMask]s and [enum Key]s using boolean OR such as [code]KEY_MASK_CTRL | KEY_A[/code] ([kbd]Ctrl + A[/kbd]). [b]Note:[/b] Radio-checkable items just display a checkmark, but don't have any built-in checking behavior and must be checked/unchecked manually. See [method global_menu_set_item_checked] for more info on how to control it. [b]Note:[/b] The [param callback] and [param key_callback] Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to [param tag]. [b]Note:[/b] This method is implemented on macOS. @@ -278,6 +282,7 @@ <description> Adds a new item with text [param label] to the global menu with ID [param menu_root]. Returns index of the inserted item, it's not guaranteed to be the same as [param index] value. + An [param accelerator] can optionally be defined, which is a keyboard shortcut that can be pressed to trigger the menu button even if it's not currently open. The [param accelerator] is generally a combination of [enum KeyModifierMask]s and [enum Key]s using boolean OR such as [code]KEY_MASK_CTRL | KEY_A[/code] ([kbd]Ctrl + A[/kbd]). [b]Note:[/b] The [param callback] and [param key_callback] Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to [param tag]. [b]Note:[/b] This method is implemented on macOS. [b]Supported system menu IDs:[/b] @@ -302,6 +307,7 @@ Adds a new item with text [param label] to the global menu with ID [param menu_root]. Contrarily to normal binary items, multistate items can have more than two states, as defined by [param max_states]. Each press or activate of the item will increase the state by one. The default value is defined by [param default_state]. Returns index of the inserted item, it's not guaranteed to be the same as [param index] value. + An [param accelerator] can optionally be defined, which is a keyboard shortcut that can be pressed to trigger the menu button even if it's not currently open. The [param accelerator] is generally a combination of [enum KeyModifierMask]s and [enum Key]s using boolean OR such as [code]KEY_MASK_CTRL | KEY_A[/code] ([kbd]Ctrl + A[/kbd]). [b]Note:[/b] By default, there's no indication of the current item state, it should be changed manually. [b]Note:[/b] The [param callback] and [param key_callback] Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to [param tag]. [b]Note:[/b] This method is implemented on macOS. @@ -324,6 +330,7 @@ <description> Adds a new radio-checkable item with text [param label] to the global menu with ID [param menu_root]. Returns index of the inserted item, it's not guaranteed to be the same as [param index] value. + An [param accelerator] can optionally be defined, which is a keyboard shortcut that can be pressed to trigger the menu button even if it's not currently open. The [param accelerator] is generally a combination of [enum KeyModifierMask]s and [enum Key]s using boolean OR such as [code]KEY_MASK_CTRL | KEY_A[/code] ([kbd]Ctrl + A[/kbd]). [b]Note:[/b] Radio-checkable items just display a checkmark, but don't have any built-in checking behavior and must be checked/unchecked manually. See [method global_menu_set_item_checked] for more info on how to control it. [b]Note:[/b] The [param callback] and [param key_callback] Callables need to accept exactly one Variant parameter, the parameter passed to the Callables will be the value passed to [param tag]. [b]Note:[/b] This method is implemented on macOS. @@ -558,7 +565,7 @@ <param index="1" name="idx" type="int" /> <param index="2" name="keycode" type="int" enum="Key" /> <description> - Sets the accelerator of the item at index [param idx]. + Sets the accelerator of the item at index [param idx]. [param keycode] can be a single [enum Key], or a combination of [enum KeyModifierMask]s and [enum Key]s using boolean OR such as [code]KEY_MASK_CTRL | KEY_A[/code] ([kbd]Ctrl + A[/kbd]). [b]Note:[/b] This method is implemented on macOS. </description> </method> @@ -651,7 +658,7 @@ <param index="1" name="idx" type="int" /> <param index="2" name="checkable" type="bool" /> <description> - Sets the type of the item at the specified index [param idx] to radio button. If [code]false[/code], sets the type of the item to plain text + Sets the type of the item at the specified index [param idx] to radio button. If [code]false[/code], sets the type of the item to plain text. [b]Note:[/b] This is purely cosmetic; you must add the logic for checking/unchecking items in radio groups. [b]Note:[/b] This method is implemented on macOS. </description> @@ -984,6 +991,7 @@ - [code]name[/code] is voice name. - [code]id[/code] is voice identifier. - [code]language[/code] is language code in [code]lang_Variant[/code] format. [code]lang[/code] part is a 2 or 3-letter code based on the ISO-639 standard, in lowercase. And [code]Variant[/code] part is an engine dependent string describing country, region or/and dialect. + Note that Godot depends on system libraries for text-to-speech functionality. These libraries are installed by default on Windows and MacOS, but not on all Linux distributions. If they are not present, this method will return an empty list. This applies to both Godot users on Linux, as well as end-users on Linux running Godot games that use text-to-speech. [b]Note:[/b] This method is implemented on Android, iOS, Web, Linux (X11), macOS, and Windows. </description> </method> @@ -1325,6 +1333,7 @@ <param index="1" name="window_id" type="int" default="0" /> <description> Sets the maximum size of the window specified by [param window_id] in pixels. Normally, the user will not be able to drag the window to make it smaller than the specified size. See also [method window_get_max_size]. + [b]Note:[/b] It's recommended to change this value using [member Window.max_size] instead. [b]Note:[/b] Using third-party tools, it is possible for users to disable window geometry restrictions and therefore bypass this limit. </description> </method> @@ -1334,6 +1343,7 @@ <param index="1" name="window_id" type="int" default="0" /> <description> Sets the minimum size for the given window to [param min_size] (in pixels). Normally, the user will not be able to drag the window to make it larger than the specified size. See also [method window_get_min_size]. + [b]Note:[/b] It's recommended to change this value using [member Window.min_size] instead. [b]Note:[/b] By default, the main window has a minimum size of [code]Vector2i(64, 64)[/code]. This prevents issues that can arise when the window is resized to a near-zero size. [b]Note:[/b] Using third-party tools, it is possible for users to disable window geometry restrictions and therefore bypass this limit. </description> @@ -1403,6 +1413,7 @@ +-------------+ +-------+ [/codeblock] See also [method window_get_position] and [method window_set_size]. + [b]Note:[/b] It's recommended to change this value using [member Window.position] instead. </description> </method> <method name="window_set_rect_changed_callback"> @@ -1419,6 +1430,7 @@ <param index="1" name="window_id" type="int" default="0" /> <description> Sets the size of the given window to [param size] (in pixels). See also [method window_get_size] and [method window_get_position]. + [b]Note:[/b] It's recommended to change this value using [member Window.size] instead. </description> </method> <method name="window_set_title"> @@ -1427,6 +1439,7 @@ <param index="1" name="window_id" type="int" default="0" /> <description> Sets the title of the given window to [param title]. + [b]Note:[/b] It's recommended to change this value using [member Window.title] instead. [b]Note:[/b] Avoid changing the window title every frame, as this can cause performance issues on certain window managers. Try to change the window title only a few times per second at most. </description> </method> @@ -1436,7 +1449,8 @@ <param index="1" name="parent_window_id" type="int" /> <description> Sets window transient parent. Transient window is will be destroyed with its transient parent and will return focus to their parent when closed. The transient window is displayed on top of a non-exclusive full-screen parent window. Transient windows can't enter full-screen mode. - Note that behavior might be different depending on the platform. + [b]Note:[/b] It's recommended to change this value using [member Window.transient] instead. + [b]Note:[/b] The behavior might be different depending on the platform. </description> </method> <method name="window_set_vsync_mode"> @@ -1447,6 +1461,7 @@ Sets the V-Sync mode of the given window. See also [member ProjectSettings.display/window/vsync/vsync_mode]. See [enum DisplayServer.VSyncMode] for possible values and how they affect the behavior of your application. Depending on the platform and used renderer, the engine will fall back to [constant VSYNC_ENABLED] if the desired mode is not supported. + [b]Note:[/b] V-Sync modes other than [constant VSYNC_ENABLED] are only supported in the Forward+ and Mobile rendering methods, not Compatibility. </description> </method> <method name="window_set_window_buttons_offset"> @@ -1609,7 +1624,7 @@ I-beam cursor shape. This is used by default when hovering a control that accepts text input, such as [LineEdit] or [TextEdit]. </constant> <constant name="CURSOR_POINTING_HAND" value="2" enum="CursorShape"> - Pointing hand cursor shape. This is used by default when hovering a [LinkButton] or an URL tag in a [RichTextLabel].⋅ + Pointing hand cursor shape. This is used by default when hovering a [LinkButton] or an URL tag in a [RichTextLabel]. </constant> <constant name="CURSOR_CROSS" value="3" enum="CursorShape"> Crosshair cursor. This is intended to be displayed when the user needs precise aim over an element, such as a rectangle selection tool or a color picker. @@ -1663,7 +1678,7 @@ Minimized window mode, i.e. [Window] is not visible and available on window manager's window list. Normally happens when the minimize button is pressed. </constant> <constant name="WINDOW_MODE_MAXIMIZED" value="2" enum="WindowMode"> - Maximized window mode, i.e. [Window] will occupy whole screen area except task bar and still display its borders. Normally happens when the minimize button is pressed. + Maximized window mode, i.e. [Window] will occupy whole screen area except task bar and still display its borders. Normally happens when the maximize button is pressed. </constant> <constant name="WINDOW_MODE_FULLSCREEN" value="3" enum="WindowMode"> Full screen mode with full multi-window support. @@ -1738,17 +1753,17 @@ [b]Note:[/b] This flag is implemented on macOS. </constant> <constant name="VSYNC_DISABLED" value="0" enum="VSyncMode"> - No vertical synchronization, which means the engine will display frames as fast as possible (tearing may be visible). Framerate is unlimited (nonwithstanding [member Engine.max_fps]). + No vertical synchronization, which means the engine will display frames as fast as possible (tearing may be visible). Framerate is unlimited (nonwithstanding [member Engine.max_fps]). Not supported when using the Compatibility rendering method. </constant> <constant name="VSYNC_ENABLED" value="1" enum="VSyncMode"> Default vertical synchronization mode, the image is displayed only on vertical blanking intervals (no tearing is visible). Framerate is limited by the monitor refresh rate (nonwithstanding [member Engine.max_fps]). </constant> <constant name="VSYNC_ADAPTIVE" value="2" enum="VSyncMode"> - Behaves like [constant VSYNC_DISABLED] when the framerate drops below the screen's refresh rate to reduce stuttering (tearing may be visible). Otherwise, vertical synchronization is enabled to avoid tearing. Framerate is limited by the monitor refresh rate (nonwithstanding [member Engine.max_fps]). + Behaves like [constant VSYNC_DISABLED] when the framerate drops below the screen's refresh rate to reduce stuttering (tearing may be visible). Otherwise, vertical synchronization is enabled to avoid tearing. Framerate is limited by the monitor refresh rate (nonwithstanding [member Engine.max_fps]). Not supported when using the Compatibility rendering method. </constant> <constant name="VSYNC_MAILBOX" value="3" enum="VSyncMode"> Displays the most recent image in the queue on vertical blanking intervals, while rendering to the other images (no tearing is visible). Framerate is unlimited (nonwithstanding [member Engine.max_fps]). - Although not guaranteed, the images can be rendered as fast as possible, which may reduce input lag (also called "Fast" V-Sync mode). [constant VSYNC_MAILBOX] works best when at least twice as many frames as the display refresh rate are rendered. + Although not guaranteed, the images can be rendered as fast as possible, which may reduce input lag (also called "Fast" V-Sync mode). [constant VSYNC_MAILBOX] works best when at least twice as many frames as the display refresh rate are rendered. Not supported when using the Compatibility rendering method. </constant> <constant name="DISPLAY_HANDLE" value="0" enum="HandleType"> Display handle: diff --git a/doc/classes/EditorExportPlugin.xml b/doc/classes/EditorExportPlugin.xml index 3e8ce10aa5..fd76e8ddaa 100644 --- a/doc/classes/EditorExportPlugin.xml +++ b/doc/classes/EditorExportPlugin.xml @@ -87,6 +87,14 @@ Return a hash based on the configuration passed (for both scenes and resources). This helps keep separate caches for separate export configurations. </description> </method> + <method name="_get_export_features" qualifiers="virtual const"> + <return type="PackedStringArray" /> + <param index="0" name="platform" type="EditorExportPlatform" /> + <param index="1" name="debug" type="bool" /> + <description> + Return a [PackedStringArray] of additional features this preset, for the given [param platform], should have. + </description> + </method> <method name="_get_name" qualifiers="virtual const"> <return type="String" /> <description> diff --git a/doc/classes/EditorFileDialog.xml b/doc/classes/EditorFileDialog.xml index 29a8f470a1..7f8808acc7 100644 --- a/doc/classes/EditorFileDialog.xml +++ b/doc/classes/EditorFileDialog.xml @@ -25,6 +25,13 @@ Removes all filters except for "All Files (*)". </description> </method> + <method name="get_line_edit"> + <return type="LineEdit" /> + <description> + Returns the LineEdit for the selected file. + [b]Warning:[/b] This is a required internal node, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their [member CanvasItem.visible] property. + </description> + </method> <method name="get_vbox"> <return type="VBoxContainer" /> <description> @@ -62,6 +69,9 @@ <member name="file_mode" type="int" setter="set_file_mode" getter="get_file_mode" enum="EditorFileDialog.FileMode" default="4"> The dialog's open or save mode, which affects the selection behavior. See [enum FileMode] </member> + <member name="filters" type="PackedStringArray" setter="set_filters" getter="get_filters" default="PackedStringArray()"> + The available file type filters. For example, this shows only [code].png[/code] and [code].gd[/code] files: [code]set_filters(PackedStringArray(["*.png ; PNG Images","*.gd ; GDScript Files"]))[/code]. Multiple file types can also be specified in a single filter. [code]"*.png, *.jpg, *.jpeg ; Supported Images"[/code] will show both PNG and JPEG files when selected. + </member> <member name="show_hidden_files" type="bool" setter="set_show_hidden_files" getter="is_showing_hidden_files" default="false"> If [code]true[/code], hidden files and directories will be visible in the [EditorFileDialog]. This property is synchronized with [member EditorSettings.filesystem/file_dialog/show_hidden_files]. </member> diff --git a/doc/classes/EditorImportPlugin.xml b/doc/classes/EditorImportPlugin.xml index ec9efcc9c4..66b61f187e 100644 --- a/doc/classes/EditorImportPlugin.xml +++ b/doc/classes/EditorImportPlugin.xml @@ -48,61 +48,67 @@ [/gdscript] [csharp] using Godot; - using System; - public class MySpecialPlugin : EditorImportPlugin + public partial class MySpecialPlugin : EditorImportPlugin { - public override String GetImporterName() + public override string _GetImporterName() { return "my.special.plugin"; } - public override String GetVisibleName() + public override string _GetVisibleName() { return "Special Mesh"; } - public override Godot.Collections.Array GetRecognizedExtensions() + public override string[] _GetRecognizedExtensions() { - return new Godot.Collections.Array{"special", "spec"}; + return new string[] { "special", "spec" }; } - public override String GetSaveExtension() + public override string _GetSaveExtension() { return "mesh"; } - public override String GetResourceType() + public override string _GetResourceType() { return "Mesh"; } - public override int GetPresetCount() + public override int _GetPresetCount() { return 1; } - public override String GetPresetName(int i) + public override string _GetPresetName(int presetIndex) { return "Default"; } - public override Godot.Collections.Array GetImportOptions(int i) + public override Godot.Collections.Array<Godot.Collections.Dictionary> _GetImportOptions(string path, int presetIndex) { - return new Godot.Collections.Array{new Godot.Collections.Dictionary{{"name", "myOption"}, {"defaultValue", false}}}; + return new Godot.Collections.Array<Godot.Collections.Dictionary> + { + new Godot.Collections.Dictionary + { + { "name", "myOption" }, + { "defaultValue", false }, + } + }; } - public override int Import(String sourceFile, String savePath, Godot.Collections.Dictionary options, Godot.Collections.Array platformVariants, Godot.Collections.Array genFiles) + public override int _Import(string sourceFile, string savePath, Godot.Collections.Dictionary options, Godot.Collections.Array<string> platformVariants, Godot.Collections.Array<string> genFiles) { - var file = new File(); - if (file.Open(sourceFile, File.ModeFlags.Read) != Error.Ok) + using var file = FileAccess.Open(sourceFile, FileAccess.ModeFlags.Read); + if (file.GetError() != Error.Ok) { return (int)Error.Failed; } var mesh = new ArrayMesh(); // Fill the Mesh with data read in "file", left as an exercise to the reader. - String filename = savePath + "." + GetSaveExtension(); + string filename = $"{savePath}.{_GetSaveExtension()}"; return (int)ResourceSaver.Save(mesh, filename); } } @@ -210,7 +216,7 @@ </description> </method> <method name="_import" qualifiers="virtual const"> - <return type="int" /> + <return type="int" enum="Error" /> <param index="0" name="source_file" type="String" /> <param index="1" name="save_path" type="String" /> <param index="2" name="options" type="Dictionary" /> @@ -221,5 +227,15 @@ This method must be overridden to do the actual importing work. See this class' description for an example of overriding this method. </description> </method> + <method name="append_import_external_resource"> + <return type="int" enum="Error" /> + <param index="0" name="path" type="String" /> + <param index="1" name="custom_options" type="Dictionary" default="{}" /> + <param index="2" name="custom_importer" type="String" default="""" /> + <param index="3" name="generator_parameters" type="Variant" default="null" /> + <description> + This function can only be called during the [method _import] callback and it allows manually importing resources from it. This is useful when the imported file generates external resources that require importing (as example, images). Custom parameters for the ".import" file can be passed via the [param custom_options]. Additionally, in cases where multiple importers can handle a file, the [param custom_importer] ca be specified to force a specific one. This function performs a resource import and returns immediately with a success or error code. [param generator_parameters] defines optional extra metadata which will be stored as [code]generator_parameters[/code] in the [code]remap[/code] section of the [code].import[/code] file, for example to store a md5 hash of the source data. + </description> + </method> </methods> </class> diff --git a/doc/classes/EditorInspectorPlugin.xml b/doc/classes/EditorInspectorPlugin.xml index ba2f7b24bf..bbd383edc0 100644 --- a/doc/classes/EditorInspectorPlugin.xml +++ b/doc/classes/EditorInspectorPlugin.xml @@ -18,7 +18,7 @@ <methods> <method name="_can_handle" qualifiers="virtual const"> <return type="bool" /> - <param index="0" name="object" type="Variant" /> + <param index="0" name="object" type="Object" /> <description> Returns [code]true[/code] if this object can be handled by this plugin. </description> @@ -56,11 +56,11 @@ <method name="_parse_property" qualifiers="virtual"> <return type="bool" /> <param index="0" name="object" type="Object" /> - <param index="1" name="type" type="int" /> + <param index="1" name="type" type="int" enum="Variant.Type" /> <param index="2" name="name" type="String" /> - <param index="3" name="hint_type" type="int" /> + <param index="3" name="hint_type" type="int" enum="PropertyHint" /> <param index="4" name="hint_string" type="String" /> - <param index="5" name="usage_flags" type="int" /> + <param index="5" name="usage_flags" type="int" enum="PropertyUsageFlags" /> <param index="6" name="wide" type="bool" /> <description> Called to allow adding property-specific editors to the property list for [param object]. The added editor control must extend [EditorProperty]. Returning [code]true[/code] removes the built-in editor for this property, otherwise allows to insert a custom editor before the built-in one. diff --git a/doc/classes/EditorNode3DGizmoPlugin.xml b/doc/classes/EditorNode3DGizmoPlugin.xml index 3ab13ec5c0..7c012f8ef6 100644 --- a/doc/classes/EditorNode3DGizmoPlugin.xml +++ b/doc/classes/EditorNode3DGizmoPlugin.xml @@ -138,7 +138,7 @@ <param index="1" name="subgizmo_id" type="int" /> <param index="2" name="transform" type="Transform3D" /> <description> - Override this method to update the node properties during subgizmo editing (see [method _subgizmos_intersect_ray] and [method _subgizmos_intersect_frustum]). The [param transform] is given in the Node3D's local coordinate system. Called for this plugin's active gizmos. + Override this method to update the node properties during subgizmo editing (see [method _subgizmos_intersect_ray] and [method _subgizmos_intersect_frustum]). The [param transform] is given in the Node3D's local coordinate system. Called for this plugin's active gizmos. </description> </method> <method name="_subgizmos_intersect_frustum" qualifiers="virtual const"> @@ -147,7 +147,7 @@ <param index="1" name="camera" type="Camera3D" /> <param index="2" name="frustum_planes" type="Plane[]" /> <description> - Override this method to allow selecting subgizmos using mouse drag box selection. Given a [param camera] and [param frustum_planes], this method should return which subgizmos are contained within the frustums. The [param frustum_planes] argument consists of an [code]Array[/code] with all the [code]Plane[/code]s that make up the selection frustum. The returned value should contain a list of unique subgizmo identifiers, these identifiers can have any non-negative value and will be used in other virtual methods like [method _get_subgizmo_transform] or [method _commit_subgizmos]. Called for this plugin's active gizmos. + Override this method to allow selecting subgizmos using mouse drag box selection. Given a [param camera] and [param frustum_planes], this method should return which subgizmos are contained within the frustums. The [param frustum_planes] argument consists of an [code]Array[/code] with all the [code]Plane[/code]s that make up the selection frustum. The returned value should contain a list of unique subgizmo identifiers, these identifiers can have any non-negative value and will be used in other virtual methods like [method _get_subgizmo_transform] or [method _commit_subgizmos]. Called for this plugin's active gizmos. </description> </method> <method name="_subgizmos_intersect_ray" qualifiers="virtual const"> diff --git a/doc/classes/EditorPlugin.xml b/doc/classes/EditorPlugin.xml index c097c8f685..95c0f8efe1 100644 --- a/doc/classes/EditorPlugin.xml +++ b/doc/classes/EditorPlugin.xml @@ -38,7 +38,7 @@ </method> <method name="_edit" qualifiers="virtual"> <return type="void" /> - <param index="0" name="object" type="Variant" /> + <param index="0" name="object" type="Object" /> <description> This function is used for plugins that edit specific object types (nodes or resources). It requests the editor to edit the given object. [param object] can be [code]null[/code] if the plugin was editing an object, but there is no longer any selected object handled by this plugin. It can be used to cleanup editing state. @@ -69,21 +69,22 @@ return EditorPlugin.AFTER_GUI_INPUT_PASS [/gdscript] [csharp] - public override void _Forward3dDrawOverViewport(Godot.Control overlay) + public override void _Forward3DDrawOverViewport(Control viewportControl) { // Draw a circle at cursor position. - overlay.DrawCircle(overlay.GetLocalMousePosition(), 64, Colors.White); + viewportControl.DrawCircle(viewportControl.GetLocalMousePosition(), 64, Colors.White); } - public override EditorPlugin.AfterGUIInput _Forward3dGuiInput(Godot.Camera3D camera, InputEvent @event) + public override EditorPlugin.AfterGuiInput _Forward3DGuiInput(Camera3D viewportCamera, InputEvent @event) { if (@event is InputEventMouseMotion) { // Redraw viewport when cursor is moved. UpdateOverlays(); - return EditorPlugin.AFTER_GUI_INPUT_STOP; + return EditorPlugin.AfterGuiInput.Stop; } - return EditorPlugin.AFTER_GUI_INPUT_PASS; + return EditorPlugin.AfterGuiInput.Pass; + } [/csharp] [/codeblocks] </description> @@ -111,9 +112,9 @@ [/gdscript] [csharp] // Prevents the InputEvent from reaching other Editor classes. - public override EditorPlugin.AfterGUIInput _Forward3dGuiInput(Camera3D camera, InputEvent @event) + public override EditorPlugin.AfterGuiInput _Forward3DGuiInput(Camera3D camera, InputEvent @event) { - return EditorPlugin.AFTER_GUI_INPUT_STOP; + return EditorPlugin.AfterGuiInput.Stop; } [/csharp] [/codeblocks] @@ -127,9 +128,9 @@ [/gdscript] [csharp] // Consumes InputEventMouseMotion and forwards other InputEvent types. - public override EditorPlugin.AfterGUIInput _Forward3dGuiInput(Camera3D camera, InputEvent @event) + public override EditorPlugin.AfterGuiInput _Forward3DGuiInput(Camera3D camera, InputEvent @event) { - return @event is InputEventMouseMotion ? EditorPlugin.AFTER_GUI_INPUT_STOP : EditorPlugin.AFTER_GUI_INPUT_PASS; + return @event is InputEventMouseMotion ? EditorPlugin.AfterGuiInput.Stop : EditorPlugin.AfterGuiInput.Pass; } [/csharp] [/codeblocks] @@ -154,13 +155,13 @@ return false [/gdscript] [csharp] - public override void ForwardCanvasDrawOverViewport(Godot.Control overlay) + public override void _ForwardCanvasDrawOverViewport(Control viewportControl) { // Draw a circle at cursor position. - overlay.DrawCircle(overlay.GetLocalMousePosition(), 64, Colors.White); + viewportControl.DrawCircle(viewportControl.GetLocalMousePosition(), 64, Colors.White); } - public override bool ForwardCanvasGuiInput(InputEvent @event) + public override bool _ForwardCanvasGuiInput(InputEvent @event) { if (@event is InputEventMouseMotion) { @@ -169,6 +170,7 @@ return true; } return false; + } [/csharp] [/codeblocks] </description> @@ -213,12 +215,13 @@ [/gdscript] [csharp] // Consumes InputEventMouseMotion and forwards other InputEvent types. - public override bool ForwardCanvasGuiInput(InputEvent @event) + public override bool _ForwardCanvasGuiInput(InputEvent @event) { - if (@event is InputEventMouseMotion) { + if (@event is InputEventMouseMotion) + { return true; } - return false + return false; } [/csharp] [/codeblocks] @@ -245,7 +248,7 @@ return get_editor_interface().get_base_control().get_theme_icon("Node", "EditorIcons") [/gdscript] [csharp] - public override Texture2D GetPluginIcon() + public override Texture2D _GetPluginIcon() { // You can use a custom icon: return ResourceLoader.Load<Texture2D>("res://addons/my_plugin/my_plugin_icon.svg"); @@ -292,7 +295,7 @@ </method> <method name="_handles" qualifiers="virtual const"> <return type="bool" /> - <param index="0" name="object" type="Variant" /> + <param index="0" name="object" type="Object" /> <description> Implement this function if your plugin edits a specific type of object (Resource or Node). If you return [code]true[/code], then you will get the functions [method _edit] and [method _make_visible] called when the editor requests them. If you have declared the methods [method _forward_canvas_gui_input] and [method _forward_3d_gui_input] these will be called too. </description> diff --git a/doc/classes/EditorScenePostImport.xml b/doc/classes/EditorScenePostImport.xml index d2ad8d1bed..44bc72ea49 100644 --- a/doc/classes/EditorScenePostImport.xml +++ b/doc/classes/EditorScenePostImport.xml @@ -10,12 +10,14 @@ [gdscript] @tool # Needed so it runs in editor. extends EditorScenePostImport + # This sample changes all node names. # Called right after the scene is imported and gets the root node. func _post_import(scene): # Change all node names to "modified_[oldnodename]" iterate(scene) return scene # Remember to return the imported scene + func iterate(node): if node != null: node.name = "modified_" + node.name @@ -30,17 +32,18 @@ [Tool] public partial class NodeRenamer : EditorScenePostImport { - public override Object _PostImport(Node scene) + public override GodotObject _PostImport(Node scene) { // Change all node names to "modified_[oldnodename]" Iterate(scene); return scene; // Remember to return the imported scene } + public void Iterate(Node node) { if (node != null) { - node.Name = "modified_" + node.Name; + node.Name = $"modified_{node.Name}"; foreach (Node child in node.GetChildren()) { Iterate(child); diff --git a/doc/classes/EditorScript.xml b/doc/classes/EditorScript.xml index a02fd215d8..33d2f40d0b 100644 --- a/doc/classes/EditorScript.xml +++ b/doc/classes/EditorScript.xml @@ -17,10 +17,9 @@ [/gdscript] [csharp] using Godot; - using System; [Tool] - public class HelloEditor : EditorScript + public partial class HelloEditor : EditorScript { public override void _Run() { diff --git a/doc/classes/EditorSettings.xml b/doc/classes/EditorSettings.xml index 72843eb157..86b84849f8 100644 --- a/doc/classes/EditorSettings.xml +++ b/doc/classes/EditorSettings.xml @@ -22,7 +22,7 @@ settings.SetSetting("some/property", Value); // `settings.get("some/property", value)` also works as this class overrides `_get()` internally. settings.GetSetting("some/property"); - Godot.Collections.Array listOfSettings = settings.GetPropertyList(); + Godot.Collections.Array<Godot.Collections.Dictionary> listOfSettings = settings.GetPropertyList(); [/csharp] [/codeblocks] [b]Note:[/b] This class shouldn't be instantiated directly. Instead, access the singleton using [method EditorInterface.get_editor_settings]. @@ -196,7 +196,7 @@ The thumbnail size to use in the FileSystem dock (in pixels). See also [member filesystem/file_dialog/thumbnail_size]. </member> <member name="docks/property_editor/auto_refresh_interval" type="float" setter="" getter=""> - The refresh interval to use for the Inspector dock's properties. The effect of this setting is mainly noticeable when adjusting gizmos in the 2D/3D editor and looking at the inspector at the same time. Lower values make the inspector more often, but take up more CPU time. + The refresh interval to use for the Inspector dock's properties. The effect of this setting is mainly noticeable when adjusting gizmos in the 2D/3D editor and looking at the inspector at the same time. Lower values make the inspector refresh more often, but take up more CPU time. </member> <member name="docks/property_editor/subresource_hue_tint" type="float" setter="" getter=""> The tint intensity to use for the subresources background in the Inspector dock. The tint is used to distinguish between different subresources in the inspector. Higher values result in a more noticeable background color difference. @@ -607,10 +607,6 @@ <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/enable_touchscreen_touch_area" type="bool" setter="" getter=""> - If [code]true[/code], increases the touch area for the UI elements to improve usability on touchscreen devices. - [b]Note:[/b] Defaults to [code]true[/code] on touchscreen devices. - </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]. @@ -627,6 +623,18 @@ <member name="interface/theme/relationship_line_opacity" type="float" setter="" getter=""> The opacity to use when drawing relationship lines in the editor's [Tree]-based GUIs (such as the Scene tree dock). </member> + <member name="interface/touchscreen/enable_long_press_as_right_click" type="bool" setter="" getter=""> + If [code]true[/code], long press on touchscreen is treated as right click. + [b]Note:[/b] Defaults to [code]true[/code] on touchscreen devices. + </member> + <member name="interface/touchscreen/enable_pan_and_scale_gestures" type="bool" setter="" getter=""> + If [code]true[/code], enable two finger pan and scale gestures on touchscreen devices. + [b]Note:[/b] Defaults to [code]true[/code] on touchscreen devices. + </member> + <member name="interface/touchscreen/increase_scrollbar_touch_area" type="bool" setter="" getter=""> + If [code]true[/code], increases the scrollbar touch area to improve usability on touchscreen devices. + [b]Note:[/b] Defaults to [code]true[/code] on touchscreen devices. + </member> <member name="network/debug/remote_host" type="String" setter="" getter=""> The address to listen to when starting the remote debugger. This can be set to [code]0.0.0.0[/code] to allow external clients to connect to the remote debugger (instead of restricting the remote debugger to connections from [code]localhost[/code]). </member> @@ -757,7 +765,7 @@ </member> <member name="text_editor/behavior/indent/type" type="int" setter="" getter=""> The indentation style to use (tabs or spaces). - [b]Note:[/b] The [url=$DOCS_URL/getting_started/scripting/gdscript/gdscript_styleguide.html]GDScript style guide[/url] recommends using tabs for indentation. It is advised to change this setting only if you need to work on a project that currently uses spaces for indentation. + [b]Note:[/b] The [url=$DOCS_URL/tutorials/scripting/gdscript/gdscript_styleguide.html]GDScript style guide[/url] recommends using tabs for indentation. It is advised to change this setting only if you need to work on a project that currently uses spaces for indentation. </member> <member name="text_editor/behavior/navigation/drag_and_drop_selection" type="bool" setter="" getter=""> If [code]true[/code], allows drag-and-dropping text in the script editor to move text. Disable this if you find yourself accidentally drag-and-dropping text in the script editor. diff --git a/doc/classes/EditorTranslationParserPlugin.xml b/doc/classes/EditorTranslationParserPlugin.xml index 89746363d8..40b469de0a 100644 --- a/doc/classes/EditorTranslationParserPlugin.xml +++ b/doc/classes/EditorTranslationParserPlugin.xml @@ -27,27 +27,25 @@ [/gdscript] [csharp] using Godot; - using System; [Tool] - public class CustomParser : EditorTranslationParserPlugin + public partial class CustomParser : EditorTranslationParserPlugin { - public override void ParseFile(string path, Godot.Collections.Array msgids, Godot.Collections.Array msgidsContextPlural) + public override void _ParseFile(string path, Godot.Collections.Array<string> msgids, Godot.Collections.Array<Godot.Collections.Array> msgidsContextPlural) { - var file = new File(); - file.Open(path, File.ModeFlags.Read); + using var file = FileAccess.Open(path, FileAccess.ModeFlags.Read); string text = file.GetAsText(); - string[] splitStrs = text.Split(",", false); - foreach (var s in splitStrs) + string[] splitStrs = text.Split(",", allowEmpty: false); + foreach (string s in splitStrs) { msgids.Add(s); - //GD.Print("Extracted string: " + s) + //GD.Print($"Extracted string: {s}"); } } - public override Godot.Collections.Array GetRecognizedExtensions() + public override string[] _GetRecognizedExtensions() { - return new Godot.Collections.Array{"csv"}; + return new string[] { "csv" }; } } [/csharp] @@ -84,16 +82,16 @@ return ["gd"] [/gdscript] [csharp] - public override void ParseFile(string path, Godot.Collections.Array msgids, Godot.Collections.Array msgidsContextPlural) + public override void _ParseFile(string path, Godot.Collections.Array<string> msgids, Godot.Collections.Array<Godot.Collections.Array> msgidsContextPlural) { var res = ResourceLoader.Load<Script>(path, "Script"); string text = res.SourceCode; // Parsing logic. } - public override Godot.Collections.Array GetRecognizedExtensions() + public override string[] _GetRecognizedExtensions() { - return new Godot.Collections.Array{"gd"}; + return new string[] { "gd" }; } [/csharp] [/codeblocks] diff --git a/doc/classes/Engine.xml b/doc/classes/Engine.xml index d583e07f59..461ffcb2e0 100644 --- a/doc/classes/Engine.xml +++ b/doc/classes/Engine.xml @@ -244,10 +244,14 @@ </description> </method> <method name="register_script_language"> - <return type="void" /> + <return type="int" enum="Error" /> <param index="0" name="language" type="ScriptLanguage" /> <description> Registers a [ScriptLanguage] instance to be available with [code]ScriptServer[/code]. + Returns: + - [constant OK] on success + - [constant ERR_UNAVAILABLE] if [code]ScriptServer[/code] has reached it limit and cannot register any new language + - [constant ERR_ALREADY_EXISTS] if [code]ScriptServer[/code] already contains a language with similar extension/name/type </description> </method> <method name="register_singleton"> @@ -258,6 +262,16 @@ Registers the given object as a singleton, globally available under [param name]. </description> </method> + <method name="unregister_script_language"> + <return type="int" enum="Error" /> + <param index="0" name="language" type="ScriptLanguage" /> + <description> + Unregisters the [ScriptLanguage] instance from [code]ScriptServer[/code]. + Returns: + - [constant OK] on success + - [constant ERR_DOES_NOT_EXIST] if the language is already not registered in [code]ScriptServer[/code] + </description> + </method> <method name="unregister_singleton"> <return type="void" /> <param index="0" name="name" type="StringName" /> diff --git a/doc/classes/Environment.xml b/doc/classes/Environment.xml index 33b6a786ae..7ee1f2dfd4 100644 --- a/doc/classes/Environment.xml +++ b/doc/classes/Environment.xml @@ -46,6 +46,7 @@ </member> <member name="adjustment_enabled" type="bool" setter="set_adjustment_enabled" getter="is_adjustment_enabled" default="false"> If [code]true[/code], enables the [code]adjustment_*[/code] properties provided by this resource. If [code]false[/code], modifications to the [code]adjustment_*[/code] properties will have no effect on the rendered scene. + [b]Note:[/b] Adjustments are only supported in the Forward+ and Mobile rendering methods, not Compatibility. </member> <member name="adjustment_saturation" type="float" setter="set_adjustment_saturation" getter="get_adjustment_saturation" default="1.0"> The global color saturation value of the rendered scene (default value is 1). Effective only if [code]adjustment_enabled[/code] is [code]true[/code]. @@ -118,6 +119,7 @@ </member> <member name="glow_enabled" type="bool" setter="set_glow_enabled" getter="is_glow_enabled" default="false"> If [code]true[/code], the glow effect is enabled. + [b]Note:[/b] Glow is only supported in the Forward+ and Mobile rendering methods, not Compatibility. When using the Mobile rendering method, glow will look different due to the lower dynamic range available in the Mobile rendering method. </member> <member name="glow_hdr_luminance_cap" type="float" setter="set_glow_hdr_luminance_cap" getter="get_glow_hdr_luminance_cap" default="12.0"> The higher threshold of the HDR glow. Areas brighter than this threshold will be clamped for the purposes of the glow effect. @@ -126,10 +128,10 @@ The bleed scale of the HDR glow. </member> <member name="glow_hdr_threshold" type="float" setter="set_glow_hdr_bleed_threshold" getter="get_glow_hdr_bleed_threshold" default="1.0"> - The lower threshold of the HDR glow. When using the OpenGL renderer (which doesn't support HDR), this needs to be below [code]1.0[/code] for glow to be visible. A value of [code]0.9[/code] works well in this case. + The lower threshold of the HDR glow. When using the Mobile rendering method (which only supports a lower dynamic range up to [code]2.0[/code]), this may need to be below [code]1.0[/code] for glow to be visible. A value of [code]0.9[/code] works well in this case. This value also needs to be decreased below [code]1.0[/code] when using glow in 2D, as 2D rendering is performed in SDR. </member> <member name="glow_intensity" type="float" setter="set_glow_intensity" getter="get_glow_intensity" default="0.8"> - The overall brightness multiplier of the glow effect. When using the OpenGL renderer, this should be increased to [code]1.5[/code] to compensate for the lack of HDR rendering. + The overall brightness multiplier of the glow effect. When using the Mobile rendering method (which only supports a lower dynamic range up to [code]2.0[/code]), this should be increased to [code]1.5[/code] to compensate. </member> <member name="glow_levels/1" type="float" setter="set_glow_level" getter="get_glow_level" default="0.0"> The intensity of the 1st level of glow. This is the most "local" level (least blurry). @@ -166,7 +168,7 @@ If [code]true[/code], glow levels will be normalized so that summed together their intensities equal [code]1.0[/code]. </member> <member name="glow_strength" type="float" setter="set_glow_strength" getter="get_glow_strength" default="1.0"> - The strength of the glow effect. This applies as the glow is blurred across the screen and increases the distance and intensity of the blur. When using the OpenGL renderer, this should be increased to 1.3 to compensate for the lack of HDR rendering. + The strength of the glow effect. This applies as the glow is blurred across the screen and increases the distance and intensity of the blur. When using the Mobile rendering method, this should be increased to compensate for the lower dynamic range. </member> <member name="reflected_light_source" type="int" setter="set_reflection_source" getter="get_reflection_source" enum="Environment.ReflectionSource" default="0"> The reflected (specular) light source. @@ -184,6 +186,7 @@ </member> <member name="sdfgi_enabled" type="bool" setter="set_sdfgi_enabled" getter="is_sdfgi_enabled" default="false"> If [code]true[/code], enables signed distance field global illumination for meshes that have their [member GeometryInstance3D.gi_mode] set to [constant GeometryInstance3D.GI_MODE_STATIC]. SDFGI is a real-time global illumination technique that works well with procedurally generated and user-built levels, including in situations where geometry is created during gameplay. The signed distance field is automatically generated around the camera as it moves. Dynamic lights are supported, but dynamic occluders and emissive surfaces are not. + [b]Note:[/b] SDFGI is only supported in the Forward+ rendering method, not Mobile or Compatibility. [b]Performance:[/b] SDFGI is relatively demanding on the GPU and is not suited to low-end hardware such as integrated graphics (consider [LightmapGI] instead). To improve SDFGI performance, enable [member ProjectSettings.rendering/global_illumination/gi/use_half_resolution] in the Project Settings. [b]Note:[/b] Meshes should have sufficiently thick walls to avoid light leaks (avoid one-sided walls). For interior levels, enclose your level geometry in a sufficiently large box and bridge the loops to close the mesh. </member> @@ -230,6 +233,7 @@ </member> <member name="ssao_enabled" type="bool" setter="set_ssao_enabled" getter="is_ssao_enabled" default="false"> If [code]true[/code], the screen-space ambient occlusion effect is enabled. This darkens objects' corners and cavities to simulate ambient light not reaching the entire object as in real life. This works well for small, dynamic objects, but baked lighting or ambient occlusion textures will do a better job at displaying ambient occlusion on large static objects. Godot uses a form of SSAO called Adaptive Screen Space Ambient Occlusion which is itself a form of Horizon Based Ambient Occlusion. + [b]Note:[/b] SSAO is only supported in the Forward+ rendering method, not Mobile or Compatibility. </member> <member name="ssao_horizon" type="float" setter="set_ssao_horizon" getter="get_ssao_horizon" default="0.06"> The threshold for considering whether a given point on a surface is occluded or not represented as an angle from the horizon mapped into the [code]0.0-1.0[/code] range. A value of [code]1.0[/code] results in no occlusion. @@ -251,6 +255,7 @@ </member> <member name="ssil_enabled" type="bool" setter="set_ssil_enabled" getter="is_ssil_enabled" default="false"> If [code]true[/code], the screen-space indirect lighting effect is enabled. Screen space indirect lighting is a form of indirect lighting that allows diffuse light to bounce between nearby objects. Screen-space indirect lighting works very similarly to screen-space ambient occlusion, in that it only affects a limited range. It is intended to be used along with a form of proper global illumination like SDFGI or [VoxelGI]. Screen-space indirect lighting is not affected by individual light's [member Light3D.light_indirect_energy]. + [b]Note:[/b] SSIL is only supported in the Forward+ rendering method, not Mobile or Compatibility. </member> <member name="ssil_intensity" type="float" setter="set_ssil_intensity" getter="get_ssil_intensity" default="1.0"> The brightness multiplier for the screen-space indirect lighting effect. A higher value will result in brighter light. @@ -269,6 +274,7 @@ </member> <member name="ssr_enabled" type="bool" setter="set_ssr_enabled" getter="is_ssr_enabled" default="false"> If [code]true[/code], screen-space reflections are enabled. Screen-space reflections are more accurate than reflections from [VoxelGI]s or [ReflectionProbe]s, but are slower and can't reflect surfaces occluded by others. + [b]Note:[/b] SSR is only supported in the Forward+ rendering method, not Mobile or Compatibility. </member> <member name="ssr_fade_in" type="float" setter="set_ssr_fade_in" getter="get_ssr_fade_in" default="0.15"> The fade-in distance for screen-space reflections. Affects the area from the reflected material to the screen-space reflection). Only positive values are valid (negative values will be clamped to [code]0.0[/code]). @@ -314,7 +320,7 @@ </member> <member name="volumetric_fog_enabled" type="bool" setter="set_volumetric_fog_enabled" getter="is_volumetric_fog_enabled" default="false"> Enables the volumetric fog effect. Volumetric fog uses a screen-aligned froxel buffer to calculate accurate volumetric scattering in the short to medium range. Volumetric fog interacts with [FogVolume]s and lights to calculate localized and global fog. Volumetric fog uses a PBR single-scattering model based on extinction, scattering, and emission which it exposes to users as density, albedo, and emission. - [b]Note:[/b] Volumetric fog is only available in the forward plus renderer. It is not available in the mobile renderer or the compatibility renderer. + [b]Note:[/b] Volumetric fog is only supported in the Forward+ rendering method, not Mobile or Compatibility. </member> <member name="volumetric_fog_gi_inject" type="float" setter="set_volumetric_fog_gi_inject" getter="get_volumetric_fog_gi_inject" default="1.0"> Scales the strength of Global Illumination used in the volumetric fog's albedo color. A value of [code]0.0[/code] means that Global Illumination will not impact the volumetric fog. [member volumetric_fog_gi_inject] has a small performance cost when set above [code]0.0[/code]. diff --git a/doc/classes/Expression.xml b/doc/classes/Expression.xml index 2c7d83a811..fd5a921836 100644 --- a/doc/classes/Expression.xml +++ b/doc/classes/Expression.xml @@ -24,7 +24,7 @@ $LineEdit.text = str(result) [/gdscript] [csharp] - public Expression expression = new Expression(); + private Expression _expression = new Expression(); public override void _Ready() { @@ -33,14 +33,14 @@ private void OnTextEntered(string command) { - Error error = expression.Parse(command); + Error error = _expression.Parse(command); if (error != Error.Ok) { - GD.Print(expression.GetErrorText()); + GD.Print(_expression.GetErrorText()); return; } - object result = expression.Execute(); - if (!expression.HasExecuteFailed()) + Variant result = _expression.Execute(); + if (!_expression.HasExecuteFailed()) { GetNode<LineEdit>("LineEdit").Text = result.ToString(); } diff --git a/doc/classes/FileAccess.xml b/doc/classes/FileAccess.xml index be0c8fd6ca..c85bde681f 100644 --- a/doc/classes/FileAccess.xml +++ b/doc/classes/FileAccess.xml @@ -33,7 +33,7 @@ [/csharp] [/codeblocks] In the example above, the file will be saved in the user data folder as specified in the [url=$DOCS_URL/tutorials/io/data_paths.html]Data paths[/url] documentation. - There is no method to close a file in order to free it from use. Instead, [FileAccess] will close when it's freed, which happens when it goes out of scope or when it gets assigned with [code]null[/code]. In C# the reference must be disposed after we are done using it, this can be done with the [code]using[/code] statement or calling the [code]Dispose[/code] method directly. + [FileAccess] will close when it's freed, which happens when it goes out of scope or when it gets assigned with [code]null[/code]. In C# the reference must be disposed after we are done using it, this can be done with the [code]using[/code] statement or calling the [code]Dispose[/code] method directly. [codeblocks] [gdscript] var file = FileAccess.open("res://something") # File is opened and locked for use. @@ -52,6 +52,13 @@ <link title="3D Voxel Demo">https://godotengine.org/asset-library/asset/676</link> </tutorials> <methods> + <method name="close"> + <return type="void" /> + <description> + Closes the currently opened file and prevents subsequent read/write operations. Use [method flush] to persist the data to disk without closing the file. + [b]Note:[/b] [FileAccess] will automatically close when it's freed, which happens when it goes out of scope or when it gets assigned with [code]null[/code]. In C# the reference must be disposed after we are done using it, this can be done with the [code]using[/code] statement or calling the [code]Dispose[/code] method directly. + </description> + </method> <method name="eof_reached" qualifiers="const"> <return type="bool" /> <description> @@ -249,6 +256,7 @@ <param index="0" name="allow_objects" type="bool" default="false" /> <description> Returns the next [Variant] value from the file. If [param allow_objects] is [code]true[/code], decoding objects is allowed. + Internally, this uses the same decoding mechanism as the [method @GlobalScope.bytes_to_var] method. [b]Warning:[/b] Deserialized objects can contain code which gets executed. Do not use this option if the serialized object comes from untrusted sources to avoid potential security threats such as remote code execution. </description> </method> @@ -348,8 +356,8 @@ f.Seek(0); // Go back to start to read the stored value. ushort read1 = f.Get16(); // 65494 ushort read2 = f.Get16(); // 121 - short converted1 = BitConverter.ToInt16(BitConverter.GetBytes(read1), 0); // -42 - short converted2 = BitConverter.ToInt16(BitConverter.GetBytes(read2), 0); // 121 + short converted1 = (short)read1; // -42 + short converted2 = (short)read2; // 121 } [/csharp] [/codeblocks] @@ -447,6 +455,7 @@ <param index="1" name="full_objects" type="bool" default="false" /> <description> Stores any Variant value in the file. If [param full_objects] is [code]true[/code], encoding objects is allowed (and can potentially include code). + Internally, this uses the same encoding mechanism as the [method @GlobalScope.var_to_bytes] method. [b]Note:[/b] Not all properties are included. Only properties that are configured with the [constant PROPERTY_USAGE_STORAGE] flag set will be serialized. You can add a new usage flag to a property by overriding the [method Object._get_property_list] method in your class. You can also check how property usage is configured by calling [method Object._get_property_list]. See [enum PropertyUsageFlags] for the possible usage flags. </description> </method> diff --git a/doc/classes/FogVolume.xml b/doc/classes/FogVolume.xml index d9fa2e6ebb..e2f9038be5 100644 --- a/doc/classes/FogVolume.xml +++ b/doc/classes/FogVolume.xml @@ -11,16 +11,16 @@ <tutorials> </tutorials> <members> - <member name="extents" type="Vector3" setter="set_extents" getter="get_extents" default="Vector3(1, 1, 1)"> - The size of the [FogVolume] when [member shape] is [constant RenderingServer.FOG_VOLUME_SHAPE_ELLIPSOID], [constant RenderingServer.FOG_VOLUME_SHAPE_CONE], [constant RenderingServer.FOG_VOLUME_SHAPE_CYLINDER] or [constant RenderingServer.FOG_VOLUME_SHAPE_BOX]. - [b]Note:[/b] Thin fog volumes may appear to flicker when the camera moves or rotates. This can be alleviated by increasing [member ProjectSettings.rendering/environment/volumetric_fog/volume_depth] (at a performance cost) or by decreasing [member Environment.volumetric_fog_length] (at no performance cost, but at the cost of lower fog range). Alternatively, the [FogVolume] can be made thicker and use a lower density in the [member material]. - [b]Note:[/b] If [member shape] is [constant RenderingServer.FOG_VOLUME_SHAPE_CONE] or [constant RenderingServer.FOG_VOLUME_SHAPE_CYLINDER], the cone/cylinder will be adjusted to fit within the extents. Non-uniform scaling of cone/cylinder shapes via the [member extents] property is not supported, but you can scale the [FogVolume] node instead. - </member> <member name="material" type="Material" setter="set_material" getter="get_material"> The [Material] used by the [FogVolume]. Can be either a built-in [FogMaterial] or a custom [ShaderMaterial]. </member> <member name="shape" type="int" setter="set_shape" getter="get_shape" enum="RenderingServer.FogVolumeShape" default="3"> The shape of the [FogVolume]. This can be set to either [constant RenderingServer.FOG_VOLUME_SHAPE_ELLIPSOID], [constant RenderingServer.FOG_VOLUME_SHAPE_CONE], [constant RenderingServer.FOG_VOLUME_SHAPE_CYLINDER], [constant RenderingServer.FOG_VOLUME_SHAPE_BOX] or [constant RenderingServer.FOG_VOLUME_SHAPE_WORLD]. </member> + <member name="size" type="Vector3" setter="set_size" getter="get_size" default="Vector3(2, 2, 2)"> + The size of the [FogVolume] when [member shape] is [constant RenderingServer.FOG_VOLUME_SHAPE_ELLIPSOID], [constant RenderingServer.FOG_VOLUME_SHAPE_CONE], [constant RenderingServer.FOG_VOLUME_SHAPE_CYLINDER] or [constant RenderingServer.FOG_VOLUME_SHAPE_BOX]. + [b]Note:[/b] Thin fog volumes may appear to flicker when the camera moves or rotates. This can be alleviated by increasing [member ProjectSettings.rendering/environment/volumetric_fog/volume_depth] (at a performance cost) or by decreasing [member Environment.volumetric_fog_length] (at no performance cost, but at the cost of lower fog range). Alternatively, the [FogVolume] can be made thicker and use a lower density in the [member material]. + [b]Note:[/b] If [member shape] is [constant RenderingServer.FOG_VOLUME_SHAPE_CONE] or [constant RenderingServer.FOG_VOLUME_SHAPE_CYLINDER], the cone/cylinder will be adjusted to fit within the size. Non-uniform scaling of cone/cylinder shapes via the [member size] property is not supported, but you can scale the [FogVolume] node instead. + </member> </members> </class> diff --git a/doc/classes/Font.xml b/doc/classes/Font.xml index 761e75339a..2f1c68c322 100644 --- a/doc/classes/Font.xml +++ b/doc/classes/Font.xml @@ -238,7 +238,7 @@ <param index="5" name="direction" type="int" enum="TextServer.Direction" default="0" /> <param index="6" name="orientation" type="int" enum="TextServer.Orientation" default="0" /> <description> - Returns the size of a bounding box of a single-line string, taking kerning and advance into account. See also [method get_multiline_string_size] and [method draw_string]. + Returns the size of a bounding box of a single-line string, taking kerning, advance and subpixel positioning into account. See also [method get_multiline_string_size] and [method draw_string]. For example, to get the string size as displayed by a single-line Label, use: [codeblocks] [gdscript] @@ -249,6 +249,7 @@ Vector2 stringSize = label.GetThemeFont("font").GetStringSize(label.Text, HorizontalAlignment.Left, -1, label.GetThemeFontSize("font_size")); [/csharp] [/codeblocks] + [b]Note:[/b] Since kerning, advance and subpixel positioning are taken into account by [method get_string_size], using separate [method get_string_size] calls on substrings of a string then adding the results together will return a different result compared to using a single [method get_string_size] call on the full string. [b]Note:[/b] Real height of the string is context-dependent and can be significantly different from the value returned by [method get_height]. </description> </method> diff --git a/doc/classes/FontFile.xml b/doc/classes/FontFile.xml index 69a7627774..a349c2b7b7 100644 --- a/doc/classes/FontFile.xml +++ b/doc/classes/FontFile.xml @@ -17,13 +17,13 @@ [codeblocks] [gdscript] var f = load("res://BarlowCondensed-Bold.ttf") - $"Label".set("custom_fonts/font", f) - $"Label".set("custom_fonts/font_size", 64) + $Label.add_theme_font_override("font", f) + $Label.add_theme_font_size_override("font_size", 64) [/gdscript] [csharp] var f = ResourceLoader.Load<FontFile>("res://BarlowCondensed-Bold.ttf"); - GetNode("Label").Set("custom_fonts/font", f); - GetNode("Label").Set("custom_font_sizes/font_size", 64); + GetNode("Label").AddThemeFontOverride("font", f); + GetNode("Label").AddThemeFontSizeOverride("font_size", 64); [/csharp] [/codeblocks] </description> @@ -88,6 +88,7 @@ <param index="0" name="cache_index" type="int" /> <param index="1" name="size" type="int" /> <description> + Returns the font descent (number of pixels below the baseline). </description> </method> <method name="get_cache_scale" qualifiers="const"> @@ -95,6 +96,7 @@ <param index="0" name="cache_index" type="int" /> <param index="1" name="size" type="int" /> <description> + Returns scaling factor of the color bitmap font. </description> </method> <method name="get_cache_underline_position" qualifiers="const"> @@ -102,6 +104,7 @@ <param index="0" name="cache_index" type="int" /> <param index="1" name="size" type="int" /> <description> + Returns pixel offset of the underline below the baseline. </description> </method> <method name="get_cache_underline_thickness" qualifiers="const"> @@ -109,6 +112,7 @@ <param index="0" name="cache_index" type="int" /> <param index="1" name="size" type="int" /> <description> + Returns thickness of the underline in pixels. </description> </method> <method name="get_embolden" qualifiers="const"> @@ -377,6 +381,7 @@ <param index="1" name="size" type="int" /> <param index="2" name="ascent" type="float" /> <description> + Sets the font ascent (number of pixels above the baseline). </description> </method> <method name="set_cache_descent"> @@ -385,6 +390,7 @@ <param index="1" name="size" type="int" /> <param index="2" name="descent" type="float" /> <description> + Sets the font descent (number of pixels below the baseline). </description> </method> <method name="set_cache_scale"> @@ -393,6 +399,7 @@ <param index="1" name="size" type="int" /> <param index="2" name="scale" type="float" /> <description> + Sets scaling factor of the color bitmap font. </description> </method> <method name="set_cache_underline_position"> @@ -401,6 +408,7 @@ <param index="1" name="size" type="int" /> <param index="2" name="underline_position" type="float" /> <description> + Sets pixel offset of the underline below the baseline. </description> </method> <method name="set_cache_underline_thickness"> @@ -409,6 +417,7 @@ <param index="1" name="size" type="int" /> <param index="2" name="underline_thickness" type="float" /> <description> + Sets thickness of the underline in pixels. </description> </method> <method name="set_embolden"> diff --git a/doc/classes/FontVariation.xml b/doc/classes/FontVariation.xml index e0fad126b9..11286e46a4 100644 --- a/doc/classes/FontVariation.xml +++ b/doc/classes/FontVariation.xml @@ -10,16 +10,16 @@ [gdscript] var fv = FontVariation.new() fv.set_base_font(load("res://BarlowCondensed-Regular.ttf")) - fv.set_variation_embolden(1.2); - $"Label".set("custom_fonts/font", fv) - $"Label".set("custom_fonts/font_size", 64) + fv.set_variation_embolden(1.2) + $Label.add_theme_font_override("font", fv) + $Label.add_theme_font_size_override("font_size", 64) [/gdscript] [csharp] var fv = new FontVariation(); fv.SetBaseFont(ResourceLoader.Load<FontFile>("res://BarlowCondensed-Regular.ttf")); fv.SetVariationEmbolden(1.2); - GetNode("Label").Set("custom_fonts/font", fv); - GetNode("Label").Set("custom_font_sizes/font_size", 64); + GetNode("Label").AddThemeFontOverride("font", fv); + GetNode("Label").AddThemeFontSizeOverride("font_size", 64); [/csharp] [/codeblocks] </description> @@ -49,7 +49,7 @@ Extra spacing at the bottom of the line in pixels. </member> <member name="spacing_glyph" type="int" setter="set_spacing" getter="get_spacing" default="0"> - Extra spacing between graphical glyphs + Extra spacing between graphical glyphs. </member> <member name="spacing_space" type="int" setter="set_spacing" getter="get_spacing" default="0"> Extra width of the space glyphs. diff --git a/doc/classes/GPUParticlesAttractorBox3D.xml b/doc/classes/GPUParticlesAttractorBox3D.xml index 6595428cc2..65a4c6d4a5 100644 --- a/doc/classes/GPUParticlesAttractorBox3D.xml +++ b/doc/classes/GPUParticlesAttractorBox3D.xml @@ -10,8 +10,8 @@ <tutorials> </tutorials> <members> - <member name="extents" type="Vector3" setter="set_extents" getter="get_extents" default="Vector3(1, 1, 1)"> - The attractor box's extents in 3D units. + <member name="size" type="Vector3" setter="set_size" getter="get_size" default="Vector3(2, 2, 2)"> + The attractor box's size in 3D units. </member> </members> </class> diff --git a/doc/classes/GPUParticlesAttractorVectorField3D.xml b/doc/classes/GPUParticlesAttractorVectorField3D.xml index aeadfaf4ab..12e6774471 100644 --- a/doc/classes/GPUParticlesAttractorVectorField3D.xml +++ b/doc/classes/GPUParticlesAttractorVectorField3D.xml @@ -11,12 +11,12 @@ <tutorials> </tutorials> <members> - <member name="extents" type="Vector3" setter="set_extents" getter="get_extents" default="Vector3(1, 1, 1)"> - The extents of the vector field box in 3D units. + <member name="size" type="Vector3" setter="set_size" getter="get_size" default="Vector3(2, 2, 2)"> + The size of the vector field box in 3D units. </member> <member name="texture" type="Texture3D" setter="set_texture" getter="get_texture"> The 3D texture to be used. Values are linearly interpolated between the texture's pixels. - [b]Note:[/b] To get better performance, the 3D texture's resolution should reflect the [member extents] of the attractor. Since particle attraction is usually low-frequency data, the texture can be kept at a low resolution such as 64×64×64. + [b]Note:[/b] To get better performance, the 3D texture's resolution should reflect the [member size] of the attractor. Since particle attraction is usually low-frequency data, the texture can be kept at a low resolution such as 64×64×64. </member> </members> </class> diff --git a/doc/classes/GPUParticlesCollisionBox3D.xml b/doc/classes/GPUParticlesCollisionBox3D.xml index 103be18bfd..737db0ba8a 100644 --- a/doc/classes/GPUParticlesCollisionBox3D.xml +++ b/doc/classes/GPUParticlesCollisionBox3D.xml @@ -11,8 +11,8 @@ <tutorials> </tutorials> <members> - <member name="extents" type="Vector3" setter="set_extents" getter="get_extents" default="Vector3(1, 1, 1)"> - The collision box's extents in 3D units. + <member name="size" type="Vector3" setter="set_size" getter="get_size" default="Vector3(2, 2, 2)"> + The collision box's size in 3D units. </member> </members> </class> diff --git a/doc/classes/GPUParticlesCollisionHeightField3D.xml b/doc/classes/GPUParticlesCollisionHeightField3D.xml index 6e996d5fbd..c8ed78b85e 100644 --- a/doc/classes/GPUParticlesCollisionHeightField3D.xml +++ b/doc/classes/GPUParticlesCollisionHeightField3D.xml @@ -13,9 +13,6 @@ <tutorials> </tutorials> <members> - <member name="extents" type="Vector3" setter="set_extents" getter="get_extents" default="Vector3(1, 1, 1)"> - The collision heightmap's extents in 3D units. To improve heightmap quality, [member extents] should be set as small as possible while covering the parts of the scene you need. - </member> <member name="follow_camera_enabled" type="bool" setter="set_follow_camera_enabled" getter="is_follow_camera_enabled" default="false"> If [code]true[/code], the [GPUParticlesCollisionHeightField3D] will follow the current camera in global space. The [GPUParticlesCollisionHeightField3D] does not need to be a child of the [Camera3D] node for this to work. Following the camera has a performance cost, as it will force the heightmap to update whenever the camera moves. Consider lowering [member resolution] to improve performance if [member follow_camera_enabled] is [code]true[/code]. @@ -23,6 +20,9 @@ <member name="resolution" type="int" setter="set_resolution" getter="get_resolution" enum="GPUParticlesCollisionHeightField3D.Resolution" default="2"> Higher resolutions can represent small details more accurately in large scenes, at the cost of lower performance. If [member update_mode] is [constant UPDATE_MODE_ALWAYS], consider using the lowest resolution possible. </member> + <member name="size" type="Vector3" setter="set_size" getter="get_size" default="Vector3(2, 2, 2)"> + The collision heightmap's size in 3D units. To improve heightmap quality, [member size] should be set as small as possible while covering the parts of the scene you need. + </member> <member name="update_mode" type="int" setter="set_update_mode" getter="get_update_mode" enum="GPUParticlesCollisionHeightField3D.UpdateMode" default="0"> The update policy to use for the generated heightmap. </member> diff --git a/doc/classes/GPUParticlesCollisionSDF3D.xml b/doc/classes/GPUParticlesCollisionSDF3D.xml index 8467cfdda1..dc4a4a2027 100644 --- a/doc/classes/GPUParticlesCollisionSDF3D.xml +++ b/doc/classes/GPUParticlesCollisionSDF3D.xml @@ -6,7 +6,7 @@ <description> Baked signed distance field 3D particle attractor affecting [GPUParticles3D] nodes. Signed distance fields (SDF) allow for efficiently representing approximate collision shapes for convex and concave objects of any shape. This is more flexible than [GPUParticlesCollisionHeightField3D], but it requires a baking step. - [b]Baking:[/b] The signed distance field texture can be baked by selecting the [GPUParticlesCollisionSDF3D] node in the editor, then clicking [b]Bake SDF[/b] at the top of the 3D viewport. Any [i]visible[/i] [MeshInstance3D]s touching the [member extents] will be taken into account for baking, regardless of their [member GeometryInstance3D.gi_mode]. + [b]Baking:[/b] The signed distance field texture can be baked by selecting the [GPUParticlesCollisionSDF3D] node in the editor, then clicking [b]Bake SDF[/b] at the top of the 3D viewport. Any [i]visible[/i] [MeshInstance3D]s within the [member size] will be taken into account for baking, regardless of their [member GeometryInstance3D.gi_mode]. [b]Note:[/b] Baking a [GPUParticlesCollisionSDF3D]'s [member texture] is only possible within the editor, as there is no bake method exposed for use in exported projects. However, it's still possible to load pre-baked [Texture3D]s into its [member texture] property in an exported project. [b]Note:[/b] [member ParticleProcessMaterial.collision_mode] must be [constant ParticleProcessMaterial.COLLISION_RIGID] or [constant ParticleProcessMaterial.COLLISION_HIDE_ON_CONTACT] on the [GPUParticles3D]'s process material for collision to work. [b]Note:[/b] Particle collision only affects [GPUParticles3D], not [CPUParticles3D]. @@ -34,12 +34,12 @@ <member name="bake_mask" type="int" setter="set_bake_mask" getter="get_bake_mask" default="4294967295"> The visual layers to account for when baking the particle collision SDF. Only [MeshInstance3D]s whose [member VisualInstance3D.layers] match with this [member bake_mask] will be included in the generated particle collision SDF. By default, all objects are taken into account for the particle collision SDF baking. </member> - <member name="extents" type="Vector3" setter="set_extents" getter="get_extents" default="Vector3(1, 1, 1)"> - The collision SDF's extents in 3D units. To improve SDF quality, the [member extents] should be set as small as possible while covering the parts of the scene you need. - </member> <member name="resolution" type="int" setter="set_resolution" getter="get_resolution" enum="GPUParticlesCollisionSDF3D.Resolution" default="2"> The bake resolution to use for the signed distance field [member texture]. The texture must be baked again for changes to the [member resolution] property to be effective. Higher resolutions have a greater performance cost and take more time to bake. Higher resolutions also result in larger baked textures, leading to increased VRAM and storage space requirements. To improve performance and reduce bake times, use the lowest resolution possible for the object you're representing the collision of. </member> + <member name="size" type="Vector3" setter="set_size" getter="get_size" default="Vector3(2, 2, 2)"> + The collision SDF's size in 3D units. To improve SDF quality, the [member size] should be set as small as possible while covering the parts of the scene you need. + </member> <member name="texture" type="Texture3D" setter="set_texture" getter="get_texture"> The 3D texture representing the signed distance field. </member> diff --git a/doc/classes/Generic6DOFJoint3D.xml b/doc/classes/Generic6DOFJoint3D.xml index e6058b1bf9..b8151bdc5a 100644 --- a/doc/classes/Generic6DOFJoint3D.xml +++ b/doc/classes/Generic6DOFJoint3D.xml @@ -115,7 +115,7 @@ The minimum rotation in positive direction to break loose and rotate around the X axis. </member> <member name="angular_limit_y/damping" type="float" setter="set_param_y" getter="get_param_y" default="1.0"> - The amount of rotational damping across the Y axis. The lower, the more dampening occurs. + The amount of rotational damping across the Y axis. The lower, the more damping occurs. </member> <member name="angular_limit_y/enabled" type="bool" setter="set_flag_y" getter="get_flag_y" default="true"> If [code]true[/code], rotation across the Y axis is limited. @@ -139,7 +139,7 @@ The minimum rotation in positive direction to break loose and rotate around the Y axis. </member> <member name="angular_limit_z/damping" type="float" setter="set_param_z" getter="get_param_z" default="1.0"> - The amount of rotational damping across the Z axis. The lower, the more dampening occurs. + The amount of rotational damping across the Z axis. The lower, the more damping occurs. </member> <member name="angular_limit_z/enabled" type="bool" setter="set_flag_z" getter="get_flag_z" default="true"> If [code]true[/code], rotation across the Z axis is limited. @@ -357,7 +357,7 @@ The speed of all rotations across the axes. </constant> <constant name="PARAM_ANGULAR_DAMPING" value="13" enum="Param"> - The amount of rotational damping across the axes. The lower, the more dampening occurs. + The amount of rotational damping across the axes. The lower, the more damping occurs. </constant> <constant name="PARAM_ANGULAR_RESTITUTION" value="14" enum="Param"> The amount of rotational restitution across the axes. The lower, the more restitution occurs. diff --git a/doc/classes/Geometry2D.xml b/doc/classes/Geometry2D.xml index 0142018f1a..f015026bc1 100644 --- a/doc/classes/Geometry2D.xml +++ b/doc/classes/Geometry2D.xml @@ -160,14 +160,13 @@ var polygon = PackedVector2Array([Vector2(0, 0), Vector2(100, 0), Vector2(100, 100), Vector2(0, 100)]) var offset = Vector2(50, 50) polygon = Transform2D(0, offset) * polygon - print(polygon) # prints [Vector2(50, 50), Vector2(150, 50), Vector2(150, 150), Vector2(50, 150)] + print(polygon) # prints [(50, 50), (150, 50), (150, 150), (50, 150)] [/gdscript] [csharp] var polygon = new Vector2[] { new Vector2(0, 0), new Vector2(100, 0), new Vector2(100, 100), new Vector2(0, 100) }; var offset = new Vector2(50, 50); - // TODO: This code is not valid right now. Ping @aaronfranke about it before Godot 4.0 is out. - //polygon = (Vector2[]) new Transform2D(0, offset).Xform(polygon); - //GD.Print(polygon); // prints [Vector2(50, 50), Vector2(150, 50), Vector2(150, 150), Vector2(50, 150)] + polygon = new Transform2D(0, offset) * polygon; + GD.Print((Variant)polygon); // prints [(50, 50), (150, 50), (150, 150), (50, 150)] [/csharp] [/codeblocks] </description> diff --git a/doc/classes/GeometryInstance3D.xml b/doc/classes/GeometryInstance3D.xml index 127c5daf95..2bb55a1f40 100644 --- a/doc/classes/GeometryInstance3D.xml +++ b/doc/classes/GeometryInstance3D.xml @@ -46,10 +46,10 @@ [b]Note:[/b] Lights' bake mode will also affect the global illumination rendering. See [member Light3D.light_bake_mode]. </member> <member name="ignore_occlusion_culling" type="bool" setter="set_ignore_occlusion_culling" getter="is_ignoring_occlusion_culling" default="false"> - If [code]true[/code], disables occlusion culling for this instance. Useful for gizmos that must be rendered even when occlusion culling is in use. + If [code]true[/code], disables occlusion culling for this instance. Useful for gizmos that must be rendered even when occlusion culling is in use. </member> <member name="lod_bias" type="float" setter="set_lod_bias" getter="get_lod_bias" default="1.0"> - Changes how quickly the mesh transitions to a lower level of detail. A value of 0 will force the mesh to its lowest level of detail, a value of 1 will use the default settings, and larger values will keep the mesh in a higher level of detail at farther distances. + Changes how quickly the mesh transitions to a lower level of detail. A value of 0 will force the mesh to its lowest level of detail, a value of 1 will use the default settings, and larger values will keep the mesh in a higher level of detail at farther distances. Useful for testing level of detail transitions in the editor. </member> <member name="material_overlay" type="Material" setter="set_material_overlay" getter="get_material_overlay"> diff --git a/doc/classes/GraphEdit.xml b/doc/classes/GraphEdit.xml index ea4e4b53ba..bf8567751e 100644 --- a/doc/classes/GraphEdit.xml +++ b/doc/classes/GraphEdit.xml @@ -1,9 +1,10 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="GraphEdit" inherits="Control" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="GraphEdit" inherits="Control" is_experimental="true" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> GraphEdit is a control responsible for displaying and manipulating graph-like data using [GraphNode]s. It provides access to creation, removal, connection, and disconnection of nodes. </brief_description> <description> + [b]Note:[/b] Please be aware that this node will undergo extensive refactoring in a future 4.x version involving compatibility-breaking API changes. GraphEdit provides tools for creation, manipulation, and display of various graphs. Its main purpose in the engine is to power the visual programming systems, such as visual shaders, but it is also available for use in user projects. GraphEdit by itself is only an empty container, representing an infinite grid where [GraphNode]s can be placed. Each [GraphNode] represent a node in the graph, a single unit of data in the connected scheme. GraphEdit, in turn, helps to control various interactions with nodes and between nodes. When the user attempts to connect, disconnect, or close a [GraphNode], a signal is emitted in the GraphEdit, but no action is taken by default. It is the responsibility of the programmer utilizing this control to implement the necessary logic to determine how each request should be handled. [b]Performance:[/b] It is greatly advised to enable low-processor usage mode (see [member OS.low_processor_usage_mode]) when using GraphEdits. @@ -72,8 +73,9 @@ return from != to [/gdscript] [csharp] - public override bool _IsNodeHoverValid(String from, int fromSlot, String to, int toSlot) { - return from != to; + public override bool _IsNodeHoverValid(StringName fromNode, int fromPort, StringName toNode, int toPort) + { + return fromNode != toNode; } [/csharp] [/codeblocks] diff --git a/doc/classes/GraphNode.xml b/doc/classes/GraphNode.xml index 3f0080ac15..8c0e8dc3c3 100644 --- a/doc/classes/GraphNode.xml +++ b/doc/classes/GraphNode.xml @@ -1,9 +1,10 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="GraphNode" inherits="Container" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="GraphNode" inherits="Container" is_experimental="true" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> GraphNode is a [Container] control that represents a single data unit in a [GraphEdit] graph. You can customize the number, type, and color of left- and right-side connection ports. </brief_description> <description> + [b]Note:[/b] Please be aware that this node will undergo extensive refactoring in a future 4.x version involving compatibility-breaking API changes. GraphNode allows to create nodes for a [GraphEdit] graph with customizable content based on its child [Control]s. GraphNode is a [Container] and is responsible for placing its children on screen. This works similar to [VBoxContainer]. Children, in turn, provide GraphNode with so-called slots, each of which can have a connection port on either side. This is similar to how [TabContainer] uses children to create the tabs. Each GraphNode slot is defined by its index and can provide the node with up to two ports: one on the left, and one on the right. By convention the left port is also referred to as the input port and the right port is referred to as the output port. Each port can be enabled and configured individually, using different type and color. The type is an arbitrary value that you can define using your own considerations. The parent [GraphEdit] will receive this information on each connect and disconnect request. Slots can be configured in the Inspector dock once you add at least one child [Control]. The properties are grouped by each slot's index in the "Slot" section. diff --git a/doc/classes/HMACContext.xml b/doc/classes/HMACContext.xml index 706ee30963..fbdc6b5e64 100644 --- a/doc/classes/HMACContext.xml +++ b/doc/classes/HMACContext.xml @@ -26,25 +26,24 @@ [/gdscript] [csharp] using Godot; - using System; using System.Diagnostics; - public class CryptoNode : Node + public partial class MyNode : Node { - private HMACContext ctx = new HMACContext(); + private HmacContext _ctx = new HmacContext(); public override void _Ready() { - byte[] key = "supersecret".ToUTF8(); - Error err = ctx.Start(HashingContext.HashType.Sha256, key); + byte[] key = "supersecret".ToUtf8(); + Error err = _ctx.Start(HashingContext.HashType.Sha256, key); Debug.Assert(err == Error.Ok); - byte[] msg1 = "this is ".ToUTF8(); - byte[] msg2 = "super duper secret".ToUTF8(); - err = ctx.Update(msg1); + byte[] msg1 = "this is ".ToUtf8(); + byte[] msg2 = "super duper secret".ToUtf8(); + err = _ctx.Update(msg1); Debug.Assert(err == Error.Ok); - err = ctx.Update(msg2); + err = _ctx.Update(msg2); Debug.Assert(err == Error.Ok); - byte[] hmac = ctx.Finish(); + byte[] hmac = _ctx.Finish(); GD.Print(hmac.HexEncode()); } } diff --git a/doc/classes/HTTPClient.xml b/doc/classes/HTTPClient.xml index b7a5cff694..4973f3fddf 100644 --- a/doc/classes/HTTPClient.xml +++ b/doc/classes/HTTPClient.xml @@ -105,7 +105,7 @@ [/gdscript] [csharp] var fields = new Godot.Collections.Dictionary { { "username", "user" }, { "password", "pass" } }; - string queryString = new HTTPClient().QueryStringFromDict(fields); + string queryString = httpClient.QueryStringFromDict(fields); // Returns "username=user&password=pass" [/csharp] [/codeblocks] @@ -117,8 +117,13 @@ # Returns "single=123&not_valued&multiple=22&multiple=33&multiple=44" [/gdscript] [csharp] - var fields = new Godot.Collections.Dictionary{{"single", 123}, {"notValued", null}, {"multiple", new Godot.Collections.Array{22, 33, 44}}}; - string queryString = new HTTPClient().QueryStringFromDict(fields); + var fields = new Godot.Collections.Dictionary + { + { "single", 123 }, + { "notValued", default }, + { "multiple", new Godot.Collections.Array { 22, 33, 44 } }, + }; + string queryString = httpClient.QueryStringFromDict(fields); // Returns "single=123&not_valued&multiple=22&multiple=33&multiple=44" [/csharp] [/codeblocks] @@ -151,7 +156,7 @@ [csharp] var fields = new Godot.Collections.Dictionary { { "username", "user" }, { "password", "pass" } }; string queryString = new HTTPClient().QueryStringFromDict(fields); - string[] headers = {"Content-Type: application/x-www-form-urlencoded", "Content-Length: " + queryString.Length}; + string[] headers = { "Content-Type: application/x-www-form-urlencoded", $"Content-Length: {queryString.Length}" }; var result = new HTTPClient().Request(HTTPClient.Method.Post, "index.php", headers, queryString); [/csharp] [/codeblocks] diff --git a/doc/classes/HTTPRequest.xml b/doc/classes/HTTPRequest.xml index d403acf90c..1905fcd8bb 100644 --- a/doc/classes/HTTPRequest.xml +++ b/doc/classes/HTTPRequest.xml @@ -57,7 +57,7 @@ // Perform a POST request. The URL below returns JSON as of writing. // Note: Don't make simultaneous requests using a single HTTPRequest node. // The snippet below is provided for reference only. - string body = new JSON().Stringify(new Godot.Collections.Dictionary + string body = new Json().Stringify(new Godot.Collections.Dictionary { { "name", "Godette" } }); @@ -69,14 +69,14 @@ } // Called when the HTTP request is completed. - private void HttpRequestCompleted(int result, int responseCode, string[] headers, byte[] body) + private void HttpRequestCompleted(long result, long responseCode, string[] headers, byte[] body) { - var json = new JSON(); - json.Parse(body.GetStringFromUTF8()); - var response = json.GetData() as Godot.Collections.Dictionary; + var json = new Json(); + json.Parse(body.GetStringFromUtf8()); + var response = json.GetData().AsGodotDictionary(); // Will print the user agent string used by the HTTPRequest node (as recognized by httpbin.org). - GD.Print((response["headers"] as Godot.Collections.Dictionary)["User-Agent"]); + GD.Print((response["headers"].AsGodotDictionary())["User-Agent"]); } [/csharp] [/codeblocks] @@ -128,9 +128,9 @@ } // Called when the HTTP request is completed. - private void HttpRequestCompleted(int result, int responseCode, string[] headers, byte[] body) + private void HttpRequestCompleted(long result, long responseCode, string[] headers, byte[] body) { - if (result != (int)HTTPRequest.Result.Success) + if (result != (long)HTTPRequest.Result.Success) { GD.PushError("Image couldn't be downloaded. Try a different image."); } @@ -141,8 +141,7 @@ GD.PushError("Couldn't load the image."); } - var texture = new ImageTexture(); - texture.CreateFromImage(image); + var texture = ImageTexture.CreateFromImage(image); // Display the image in a TextureRect node. var textureRect = new TextureRect(); diff --git a/doc/classes/HashingContext.xml b/doc/classes/HashingContext.xml index 7c2be6f817..5223cbf52f 100644 --- a/doc/classes/HashingContext.xml +++ b/doc/classes/HashingContext.xml @@ -8,7 +8,7 @@ The [enum HashType] enum shows the supported hashing algorithms. [codeblocks] [gdscript] - const CHUNK_SIZE = 102 + const CHUNK_SIZE = 1024 func hash_file(path): # Check that file exists. @@ -32,17 +32,16 @@ public void HashFile(string path) { - var ctx = new HashingContext(); - var file = new File(); - // Start a SHA-256 context. - ctx.Start(HashingContext.HashType.Sha256); // Check that file exists. - if (!file.FileExists(path)) + if (!FileAccess.FileExists(path)) { return; } + // Start a SHA-256 context. + var ctx = new HashingContext(); + ctx.Start(HashingContext.HashType.Sha256); // Open the file to hash. - file.Open(path, File.ModeFlags.Read); + using var file = FileAccess.Open(path, FileAccess.ModeFlags.Read); // Update the context after reading each chunk. while (!file.EofReached()) { @@ -51,8 +50,7 @@ // Get the computed hash. byte[] res = ctx.Finish(); // Print the result as hex string and array. - - GD.PrintT(res.HexEncode(), res); + GD.PrintT(res.HexEncode(), (Variant)res); } [/csharp] [/codeblocks] diff --git a/doc/classes/Image.xml b/doc/classes/Image.xml index 5b07124b91..166ef7a108 100644 --- a/doc/classes/Image.xml +++ b/doc/classes/Image.xml @@ -482,16 +482,14 @@ [gdscript] var img_width = 10 var img_height = 5 - var img = Image.new() - img.create(img_width, img_height, false, Image.FORMAT_RGBA8) + var img = Image.create(img_width, img_height, false, Image.FORMAT_RGBA8) img.set_pixel(1, 2, Color.RED) # Sets the color at (1, 2) to red. [/gdscript] [csharp] int imgWidth = 10; int imgHeight = 5; - var img = new Image(); - img.Create(imgWidth, imgHeight, false, Image.Format.Rgba8); + var img = Image.Create(imgWidth, imgHeight, false, Image.Format.Rgba8); img.SetPixel(1, 2, Colors.Red); // Sets the color at (1, 2) to red. [/csharp] @@ -510,16 +508,14 @@ [gdscript] var img_width = 10 var img_height = 5 - var img = Image.new() - img.create(img_width, img_height, false, Image.FORMAT_RGBA8) + var img = Image.create(img_width, img_height, false, Image.FORMAT_RGBA8) img.set_pixelv(Vector2i(1, 2), Color.RED) # Sets the color at (1, 2) to red. [/gdscript] [csharp] int imgWidth = 10; int imgHeight = 5; - var img = new Image(); - img.Create(imgWidth, imgHeight, false, Image.Format.Rgba8); + var img = Image.Create(imgWidth, imgHeight, false, Image.Format.Rgba8); img.SetPixelv(new Vector2I(1, 2), Colors.Red); // Sets the color at (1, 2) to red. [/csharp] diff --git a/doc/classes/InputEvent.xml b/doc/classes/InputEvent.xml index 043ccdca36..53fb334ede 100644 --- a/doc/classes/InputEvent.xml +++ b/doc/classes/InputEvent.xml @@ -74,7 +74,7 @@ <method name="is_echo" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if this input event is an echo event (only for events of type [InputEventKey]). + Returns [code]true[/code] if this input event is an echo event (only for events of type [InputEventKey]). Any other event type returns [code]false[/code]. </description> </method> <method name="is_match" qualifiers="const"> diff --git a/doc/classes/InputEventMIDI.xml b/doc/classes/InputEventMIDI.xml index 67e7ced2e8..e4ba380741 100644 --- a/doc/classes/InputEventMIDI.xml +++ b/doc/classes/InputEventMIDI.xml @@ -35,9 +35,9 @@ GD.Print(OS.GetConnectedMidiInputs()); } - public override void _Input(InputEvent inputEvent) + public override void _Input(InputEvent @event) { - if (inputEvent is InputEventMIDI midiEvent) + if (@event is InputEventMIDI midiEvent) { PrintMIDIInfo(midiEvent); } @@ -46,14 +46,14 @@ private void PrintMIDIInfo(InputEventMIDI midiEvent) { GD.Print(midiEvent); - GD.Print("Channel " + midiEvent.Channel); - GD.Print("Message " + midiEvent.Message); - GD.Print("Pitch " + midiEvent.Pitch); - GD.Print("Velocity " + midiEvent.Velocity); - GD.Print("Instrument " + midiEvent.Instrument); - GD.Print("Pressure " + midiEvent.Pressure); - GD.Print("Controller number: " + midiEvent.ControllerNumber); - GD.Print("Controller value: " + midiEvent.ControllerValue); + GD.Print($"Channel {midiEvent.Channel}"); + GD.Print($"Message {midiEvent.Message}"); + GD.Print($"Pitch {midiEvent.Pitch}"); + GD.Print($"Velocity {midiEvent.Velocity}"); + GD.Print($"Instrument {midiEvent.Instrument}"); + GD.Print($"Pressure {midiEvent.Pressure}"); + GD.Print($"Controller number: {midiEvent.ControllerNumber}"); + GD.Print($"Controller value: {midiEvent.ControllerValue}"); } [/csharp] [/codeblocks] diff --git a/doc/classes/Light2D.xml b/doc/classes/Light2D.xml index 062d532464..4481131f81 100644 --- a/doc/classes/Light2D.xml +++ b/doc/classes/Light2D.xml @@ -41,7 +41,8 @@ The Light2D's energy value. The larger the value, the stronger the light. </member> <member name="range_item_cull_mask" type="int" setter="set_item_cull_mask" getter="get_item_cull_mask" default="1"> - The layer mask. Only objects with a matching mask will be affected by the Light2D. + The layer mask. Only objects with a matching [member CanvasItem.light_mask] will be affected by the Light2D. See also [member shadow_item_cull_mask], which affects which objects can cast shadows. + [b]Note:[/b] [member range_item_cull_mask] is ignored by [DirectionalLight2D], which will always light a 2D node regardless of the 2D node's [member CanvasItem.light_mask]. </member> <member name="range_layer_max" type="int" setter="set_layer_range_max" getter="get_layer_range_max" default="0"> Maximum layer value of objects that are affected by the Light2D. @@ -68,7 +69,7 @@ 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. + The shadow mask. Used with [LightOccluder2D] to cast shadows. Only occluders with a matching [member CanvasItem.light_mask] will cast shadows. See also [member range_item_cull_mask], which affects which objects can [i]receive[/i] the light. </member> </members> <constants> @@ -79,7 +80,7 @@ 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. This is the slowest shadow filtereing mode, and should be used sparingly. See [member shadow_filter]. + Percentage closer filtering (13 samples) applies to the shadow map. This is the slowest shadow filtering 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/Light3D.xml b/doc/classes/Light3D.xml index 95c39d535e..2a0b2da46c 100644 --- a/doc/classes/Light3D.xml +++ b/doc/classes/Light3D.xml @@ -54,8 +54,9 @@ If [code]true[/code], the light only appears in the editor and will not be visible at runtime. </member> <member name="light_angular_distance" type="float" setter="set_param" getter="get_param" default="0.0"> - The light's angular size in degrees. Increasing this will make shadows softer at greater distances. Only available for [DirectionalLight3D]s. For reference, the Sun from the Earth is approximately [code]0.5[/code]. + The light's angular size in degrees. Increasing this will make shadows softer at greater distances (also called percentage-closer soft shadows, or PCSS). Only available for [DirectionalLight3D]s. For reference, the Sun from the Earth is approximately [code]0.5[/code]. Increasing this value above [code]0.0[/code] for lights with shadows enabled will have a noticeable performance cost due to PCSS. [b]Note:[/b] [member light_angular_distance] is not affected by [member Node3D.scale] (the light's scale or its parent's scale). + [b]Note:[/b] PCSS for directional lights is only supported in the Forward+ rendering method, not Mobile or Compatibility. </member> <member name="light_bake_mode" type="int" setter="set_bake_mode" getter="get_bake_mode" enum="Light3D.BakeMode" default="2"> The light's bake mode. This will affect the global illumination techniques that have an effect on the light's rendering. See [enum BakeMode]. @@ -89,10 +90,12 @@ <member name="light_projector" type="Texture2D" setter="set_projector" getter="get_projector"> [Texture2D] projected by light. [member shadow_enabled] must be on for the projector to work. Light projectors make the light appear as if it is shining through a colored but transparent object, almost like light shining through stained-glass. [b]Note:[/b] Unlike [BaseMaterial3D] whose filter mode can be adjusted on a per-material basis, the filter mode for light projector textures is set globally with [member ProjectSettings.rendering/textures/light_projectors/filter]. + [b]Note:[/b] Light projector textures are only supported in the Forward+ and Mobile rendering methods, not Compatibility. </member> <member name="light_size" type="float" setter="set_param" getter="get_param" default="0.0"> - The size of the light in Godot units. Only available for [OmniLight3D]s and [SpotLight3D]s. Increasing this value will make the light fade out slower and shadows appear blurrier. This can be used to simulate area lights to an extent. + The size of the light in Godot units. Only available for [OmniLight3D]s and [SpotLight3D]s. Increasing this value will make the light fade out slower and shadows appear blurrier (also called percentage-closer soft shadows, or PCSS). This can be used to simulate area lights to an extent. Increasing this value above [code]0.0[/code] for lights with shadows enabled will have a noticeable performance cost due to PCSS. [b]Note:[/b] [member light_size] is not affected by [member Node3D.scale] (the light's scale or its parent's scale). + [b]Note:[/b] PCSS for positional lights is only supported in the Forward+ and Mobile rendering methods, not Compatibility. </member> <member name="light_specular" type="float" setter="set_param" getter="get_param" default="0.5"> The intensity of the specular blob in objects affected by the light. At [code]0[/code], the light becomes a pure diffuse light. When not baking emission, this can be used to avoid unrealistic reflections when placing lights above an emissive surface. diff --git a/doc/classes/MainLoop.xml b/doc/classes/MainLoop.xml index 674adb1772..260efb0eab 100644 --- a/doc/classes/MainLoop.xml +++ b/doc/classes/MainLoop.xml @@ -29,29 +29,28 @@ [/gdscript] [csharp] using Godot; - using System; - public class CustomMainLoop : MainLoop + public partial class CustomMainLoop : MainLoop { - public float TimeElapsed = 0; + private double _timeElapsed = 0; public override void _Initialize() { GD.Print("Initialized:"); - GD.Print($" Starting Time: {TimeElapsed}"); + GD.Print($" Starting Time: {_timeElapsed}"); } - public override bool _Process(float delta) + public override bool _Process(double delta) { - TimeElapsed += delta; + _timeElapsed += delta; // Return true to end the main loop. - return Input.GetMouseButtonMask() != 0 || Input.IsKeyPressed((int)KeyList.Escape); + return Input.GetMouseButtonMask() != 0 || Input.IsKeyPressed(Key.Escape); } private void _Finalize() { GD.Print("Finalized:"); - GD.Print($" End Time: {TimeElapsed}"); + GD.Print($" End Time: {_timeElapsed}"); } } [/csharp] diff --git a/doc/classes/Marshalls.xml b/doc/classes/Marshalls.xml index 1eeb0be7ce..e350f3212f 100644 --- a/doc/classes/Marshalls.xml +++ b/doc/classes/Marshalls.xml @@ -29,6 +29,7 @@ <param index="1" name="allow_objects" type="bool" default="false" /> <description> Returns a decoded [Variant] corresponding to the Base64-encoded string [param base64_str]. If [param allow_objects] is [code]true[/code], decoding objects is allowed. + Internally, this uses the same decoding mechanism as the [method @GlobalScope.bytes_to_var] method. [b]Warning:[/b] Deserialized objects can contain code which gets executed. Do not use this option if the serialized object comes from untrusted sources to avoid potential security threats such as remote code execution. </description> </method> @@ -52,6 +53,7 @@ <param index="1" name="full_objects" type="bool" default="false" /> <description> Returns a Base64-encoded string of the [Variant] [param variant]. If [param full_objects] is [code]true[/code], encoding objects is allowed (and can potentially include code). + Internally, this uses the same encoding mechanism as the [method @GlobalScope.var_to_bytes] method. </description> </method> </methods> diff --git a/doc/classes/MenuBar.xml b/doc/classes/MenuBar.xml index 79876e56a3..fac5eae98c 100644 --- a/doc/classes/MenuBar.xml +++ b/doc/classes/MenuBar.xml @@ -4,7 +4,7 @@ A horizontal menu bar, which displays [PopupMenu]s or system global menu. </brief_description> <description> - New items can be created by adding [PopupMenu] nodes to his node. + New items can be created by adding [PopupMenu] nodes to this node. </description> <tutorials> </tutorials> diff --git a/doc/classes/MultiplayerAPI.xml b/doc/classes/MultiplayerAPI.xml index 020ce4f468..29011cd016 100644 --- a/doc/classes/MultiplayerAPI.xml +++ b/doc/classes/MultiplayerAPI.xml @@ -138,7 +138,7 @@ Used with [method Node.rpc_config] to disable a method or property for all RPC calls, making it unavailable. Default for all methods. </constant> <constant name="RPC_MODE_ANY_PEER" value="1" enum="RPCMode"> - Used with [method Node.rpc_config] to set a method to be callable remotely by any peer. Analogous to the [code]@rpc("any")[/code] annotation. Calls are accepted from all remote peers, no matter if they are node's authority or not. + Used with [method Node.rpc_config] to set a method to be callable remotely by any peer. Analogous to the [code]@rpc("any_peer")[/code] annotation. Calls are accepted from all remote peers, no matter if they are node's authority or not. </constant> <constant name="RPC_MODE_AUTHORITY" value="2" enum="RPCMode"> Used with [method Node.rpc_config] to set a method to be callable remotely only by the current multiplayer authority (which is the server by default). Analogous to the [code]@rpc("authority")[/code] annotation. See [method Node.set_multiplayer_authority]. diff --git a/doc/classes/MultiplayerAPIExtension.xml b/doc/classes/MultiplayerAPIExtension.xml index c4012a920a..b853c32407 100644 --- a/doc/classes/MultiplayerAPIExtension.xml +++ b/doc/classes/MultiplayerAPIExtension.xml @@ -99,7 +99,7 @@ </description> </method> <method name="_object_configuration_add" qualifiers="virtual"> - <return type="int" /> + <return type="int" enum="Error" /> <param index="0" name="object" type="Object" /> <param index="1" name="configuration" type="Variant" /> <description> @@ -107,7 +107,7 @@ </description> </method> <method name="_object_configuration_remove" qualifiers="virtual"> - <return type="int" /> + <return type="int" enum="Error" /> <param index="0" name="object" type="Object" /> <param index="1" name="configuration" type="Variant" /> <description> @@ -115,13 +115,13 @@ </description> </method> <method name="_poll" qualifiers="virtual"> - <return type="int" /> + <return type="int" enum="Error" /> <description> Callback for [method MultiplayerAPI.poll]. </description> </method> <method name="_rpc" qualifiers="virtual"> - <return type="int" /> + <return type="int" enum="Error" /> <param index="0" name="peer" type="int" /> <param index="1" name="object" type="Object" /> <param index="2" name="method" type="StringName" /> diff --git a/doc/classes/NavigationAgent2D.xml b/doc/classes/NavigationAgent2D.xml index 6ae4dc4177..c6d03fb6d8 100644 --- a/doc/classes/NavigationAgent2D.xml +++ b/doc/classes/NavigationAgent2D.xml @@ -111,6 +111,21 @@ <member name="avoidance_enabled" type="bool" setter="set_avoidance_enabled" getter="get_avoidance_enabled" default="false"> If [code]true[/code] the agent is registered for an RVO avoidance callback on the [NavigationServer2D]. When [method NavigationAgent2D.set_velocity] is used and the processing is completed a [code]safe_velocity[/code] Vector2 is received with a signal connection to [signal velocity_computed]. Avoidance processing with many registered agents has a significant performance cost and should only be enabled on agents that currently require it. </member> + <member name="debug_enabled" type="bool" setter="set_debug_enabled" getter="get_debug_enabled" default="false"> + If [code]true[/code] shows debug visuals for this agent. + </member> + <member name="debug_path_custom_color" type="Color" setter="set_debug_path_custom_color" getter="get_debug_path_custom_color" default="Color(1, 1, 1, 1)"> + If [member debug_use_custom] is [code]true[/code] uses this color for this agent instead of global color. + </member> + <member name="debug_path_custom_line_width" type="float" setter="set_debug_path_custom_line_width" getter="get_debug_path_custom_line_width" default="1.0"> + If [member debug_use_custom] is [code]true[/code] uses this line width for rendering paths for this agent instead of global line width. + </member> + <member name="debug_path_custom_point_size" type="float" setter="set_debug_path_custom_point_size" getter="get_debug_path_custom_point_size" default="4.0"> + If [member debug_use_custom] is [code]true[/code] uses this rasterized point size for rendering path points for this agent instead of global point size. + </member> + <member name="debug_use_custom" type="bool" setter="set_debug_use_custom" getter="get_debug_use_custom" default="false"> + If [code]true[/code] uses the defined [member debug_path_custom_color] for this agent instead of global color. + </member> <member name="max_neighbors" type="int" setter="set_max_neighbors" getter="get_max_neighbors" default="10"> The maximum number of neighbors for the agent to consider. </member> @@ -156,6 +171,8 @@ - [code]type[/code]: Always [constant NavigationPathQueryResult2D.PATH_SEGMENT_TYPE_LINK]. - [code]rid[/code]: The [RID] of the link. - [code]owner[/code]: The object which manages the link (usually [NavigationLink2D]). + - [code]link_entry_position[/code]: If [code]owner[/code] is available and the owner is a [NavigationLink2D], it will contain the global position of the link's point the agent is entering. + - [code]link_exit_position[/code]: If [code]owner[/code] is available and the owner is a [NavigationLink2D], it will contain the global position of the link's point which the agent is exiting. </description> </signal> <signal name="navigation_finished"> diff --git a/doc/classes/NavigationAgent3D.xml b/doc/classes/NavigationAgent3D.xml index a22cd6dd46..d2151773da 100644 --- a/doc/classes/NavigationAgent3D.xml +++ b/doc/classes/NavigationAgent3D.xml @@ -114,6 +114,18 @@ <member name="avoidance_enabled" type="bool" setter="set_avoidance_enabled" getter="get_avoidance_enabled" default="false"> If [code]true[/code] the agent is registered for an RVO avoidance callback on the [NavigationServer3D]. When [method NavigationAgent3D.set_velocity] is used and the processing is completed a [code]safe_velocity[/code] Vector3 is received with a signal connection to [signal velocity_computed]. Avoidance processing with many registered agents has a significant performance cost and should only be enabled on agents that currently require it. </member> + <member name="debug_enabled" type="bool" setter="set_debug_enabled" getter="get_debug_enabled" default="false"> + If [code]true[/code] shows debug visuals for this agent. + </member> + <member name="debug_path_custom_color" type="Color" setter="set_debug_path_custom_color" getter="get_debug_path_custom_color" default="Color(1, 1, 1, 1)"> + If [member debug_use_custom] is [code]true[/code] uses this color for this agent instead of global color. + </member> + <member name="debug_path_custom_point_size" type="float" setter="set_debug_path_custom_point_size" getter="get_debug_path_custom_point_size" default="4.0"> + If [member debug_use_custom] is [code]true[/code] uses this rasterized point size for rendering path points for this agent instead of global point size. + </member> + <member name="debug_use_custom" type="bool" setter="set_debug_use_custom" getter="get_debug_use_custom" default="false"> + If [code]true[/code] uses the defined [member debug_path_custom_color] for this agent instead of global color. + </member> <member name="ignore_y" type="bool" setter="set_ignore_y" getter="get_ignore_y" default="true"> Ignores collisions on the Y axis. Must be true to move on a horizontal plane. </member> @@ -132,13 +144,13 @@ <member name="path_desired_distance" type="float" setter="set_path_desired_distance" getter="get_path_desired_distance" default="1.0"> The distance threshold before a path point is considered to be reached. This will allow an agent to not have to hit a path point on the path exactly, but in the area. If this value is set to high the NavigationAgent will skip points on the path which can lead to leaving the navigation mesh. If this value is set to low the NavigationAgent will be stuck in a repath loop cause it will constantly overshoot or undershoot the distance to the next point on each physics frame update. </member> - <member name="path_max_distance" type="float" setter="set_path_max_distance" getter="get_path_max_distance" default="3.0"> + <member name="path_max_distance" type="float" setter="set_path_max_distance" getter="get_path_max_distance" default="5.0"> The maximum distance the agent is allowed away from the ideal path to the final position. This can happen due to trying to avoid collisions. When the maximum distance is exceeded, it recalculates the ideal path. </member> <member name="path_metadata_flags" type="int" setter="set_path_metadata_flags" getter="get_path_metadata_flags" enum="NavigationPathQueryParameters3D.PathMetadataFlags" default="7"> Additional information to return with the navigation path. </member> - <member name="radius" type="float" setter="set_radius" getter="get_radius" default="1.0"> + <member name="radius" type="float" setter="set_radius" getter="get_radius" default="0.5"> The radius of the avoidance agent. This is the "body" of the avoidance agent and not the avoidance maneuver starting radius (which is controlled by [member neighbor_distance]). Does not affect normal pathfinding. To change an actor's pathfinding radius bake [NavigationMesh] resources with a different [member NavigationMesh.agent_radius] property and use different navigation maps for each actor size. </member> @@ -148,7 +160,7 @@ <member name="target_position" type="Vector3" setter="set_target_position" getter="get_target_position" default="Vector3(0, 0, 0)"> The user-defined target position. Setting this property will clear the current navigation path. </member> - <member name="time_horizon" type="float" setter="set_time_horizon" getter="get_time_horizon" default="5.0"> + <member name="time_horizon" type="float" setter="set_time_horizon" getter="get_time_horizon" default="1.0"> The minimal amount of time for which this agent's velocities, that are computed with the collision avoidance algorithm, are safe with respect to other agents. The larger the number, the sooner the agent will respond to other agents, but less freedom in choosing its velocities. Must be positive. </member> </members> @@ -162,6 +174,8 @@ - [code]type[/code]: Always [constant NavigationPathQueryResult3D.PATH_SEGMENT_TYPE_LINK]. - [code]rid[/code]: The [RID] of the link. - [code]owner[/code]: The object which manages the link (usually [NavigationLink3D]). + - [code]link_entry_position[/code]: If [code]owner[/code] is available and the owner is a [NavigationLink2D], it will contain the global position of the link's point the agent is entering. + - [code]link_exit_position[/code]: If [code]owner[/code] is available and the owner is a [NavigationLink2D], it will contain the global position of the link's point which the agent is exiting. </description> </signal> <signal name="navigation_finished"> diff --git a/doc/classes/NavigationLink2D.xml b/doc/classes/NavigationLink2D.xml index b3f4367675..b3768c357c 100644 --- a/doc/classes/NavigationLink2D.xml +++ b/doc/classes/NavigationLink2D.xml @@ -4,12 +4,24 @@ Creates a link between two positions that [NavigationServer2D] can route agents through. </brief_description> <description> - Creates a link between two positions that [NavigationServer2D] can route agents through. Links can be used to express navigation methods that aren't just traveling along the surface of the navigation mesh, like zip-lines, teleporters, or jumping across gaps. + Creates a link between two positions that [NavigationServer2D] can route agents through. Links can be used to express navigation methods that aren't just traveling along the surface of the navigation mesh, like zip-lines, teleporters, or jumping across gaps. </description> <tutorials> <link title="Using NavigationLinks">$DOCS_URL/tutorials/navigation/navigation_using_navigationlinks.html</link> </tutorials> <methods> + <method name="get_global_end_position" qualifiers="const"> + <return type="Vector2" /> + <description> + Returns the [member end_position] that is relative to the link as a global position. + </description> + </method> + <method name="get_global_start_position" qualifiers="const"> + <return type="Vector2" /> + <description> + Returns the [member start_position] that is relative to the link as a global position. + </description> + </method> <method name="get_navigation_layer_value" qualifiers="const"> <return type="bool" /> <param index="0" name="layer_number" type="int" /> @@ -17,6 +29,20 @@ Returns whether or not the specified layer of the [member navigation_layers] bitmask is enabled, given a [code]layer_number[/code] between 1 and 32. </description> </method> + <method name="set_global_end_position"> + <return type="void" /> + <param index="0" name="position" type="Vector2" /> + <description> + Sets the [member end_position] that is relative to the link from a global [param position]. + </description> + </method> + <method name="set_global_start_position"> + <return type="void" /> + <param index="0" name="position" type="Vector2" /> + <description> + Sets the [member start_position] that is relative to the link from a global [param position]. + </description> + </method> <method name="set_navigation_layer_value"> <return type="void" /> <param index="0" name="layer_number" type="int" /> diff --git a/doc/classes/NavigationLink3D.xml b/doc/classes/NavigationLink3D.xml index 4dff226042..63abecf631 100644 --- a/doc/classes/NavigationLink3D.xml +++ b/doc/classes/NavigationLink3D.xml @@ -4,12 +4,24 @@ Creates a link between two positions that [NavigationServer3D] can route agents through. </brief_description> <description> - Creates a link between two positions that [NavigationServer3D] can route agents through. Links can be used to express navigation methods that aren't just traveling along the surface of the navigation mesh, like zip-lines, teleporters, or jumping across gaps. + Creates a link between two positions that [NavigationServer3D] can route agents through. Links can be used to express navigation methods that aren't just traveling along the surface of the navigation mesh, like zip-lines, teleporters, or jumping across gaps. </description> <tutorials> <link title="Using NavigationLinks">$DOCS_URL/tutorials/navigation/navigation_using_navigationlinks.html</link> </tutorials> <methods> + <method name="get_global_end_position" qualifiers="const"> + <return type="Vector3" /> + <description> + Returns the [member end_position] that is relative to the link as a global position. + </description> + </method> + <method name="get_global_start_position" qualifiers="const"> + <return type="Vector3" /> + <description> + Returns the [member start_position] that is relative to the link as a global position. + </description> + </method> <method name="get_navigation_layer_value" qualifiers="const"> <return type="bool" /> <param index="0" name="layer_number" type="int" /> @@ -17,6 +29,20 @@ Returns whether or not the specified layer of the [member navigation_layers] bitmask is enabled, given a [code]layer_number[/code] between 1 and 32. </description> </method> + <method name="set_global_end_position"> + <return type="void" /> + <param index="0" name="position" type="Vector3" /> + <description> + Sets the [member end_position] that is relative to the link from a global [param position]. + </description> + </method> + <method name="set_global_start_position"> + <return type="void" /> + <param index="0" name="position" type="Vector3" /> + <description> + Sets the [member start_position] that is relative to the link from a global [param position]. + </description> + </method> <method name="set_navigation_layer_value"> <return type="void" /> <param index="0" name="layer_number" type="int" /> diff --git a/doc/classes/NavigationPathQueryResult2D.xml b/doc/classes/NavigationPathQueryResult2D.xml index 7bc588619d..2bf7961b35 100644 --- a/doc/classes/NavigationPathQueryResult2D.xml +++ b/doc/classes/NavigationPathQueryResult2D.xml @@ -13,7 +13,7 @@ <method name="reset"> <return type="void" /> <description> - Reset the result object to its initial state. This is useful to reuse the object across multiple queries. + Reset the result object to its initial state. This is useful to reuse the object across multiple queries. </description> </method> </methods> diff --git a/doc/classes/NavigationPathQueryResult3D.xml b/doc/classes/NavigationPathQueryResult3D.xml index 118a597b6c..a49eb14b67 100644 --- a/doc/classes/NavigationPathQueryResult3D.xml +++ b/doc/classes/NavigationPathQueryResult3D.xml @@ -13,7 +13,7 @@ <method name="reset"> <return type="void" /> <description> - Reset the result object to its initial state. This is useful to reuse the object across multiple queries. + Reset the result object to its initial state. This is useful to reuse the object across multiple queries. </description> </method> </methods> diff --git a/doc/classes/NavigationServer2D.xml b/doc/classes/NavigationServer2D.xml index 16f6de5238..103de8eddb 100644 --- a/doc/classes/NavigationServer2D.xml +++ b/doc/classes/NavigationServer2D.xml @@ -1,7 +1,7 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="NavigationServer2D" inherits="Object" is_experimental="true" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - Server interface for low-level 2D navigation access + Server interface for low-level 2D navigation access. </brief_description> <description> NavigationServer2D is the server responsible for all 2D navigation. It handles several objects, namely maps, regions and agents. @@ -126,6 +126,12 @@ Destroys the given RID. </description> </method> + <method name="get_debug_enabled" qualifiers="const"> + <return type="bool" /> + <description> + Returns [code]true[/code] when the NavigationServer has debug enabled. + </description> + </method> <method name="get_maps" qualifiers="const"> <return type="RID[]" /> <description> @@ -520,6 +526,13 @@ Sets the [param travel_cost] for this [param region]. </description> </method> + <method name="set_debug_enabled"> + <return type="void" /> + <param index="0" name="enabled" type="bool" /> + <description> + If [code]true[/code] enables debug mode on the NavigationServer. + </description> + </method> </methods> <signals> <signal name="map_changed"> @@ -528,5 +541,10 @@ Emitted when a navigation map is updated, when a region moves or is modified. </description> </signal> + <signal name="navigation_debug_changed"> + <description> + Emitted when navigation debug settings are changed. Only available in debug builds. + </description> + </signal> </signals> </class> diff --git a/doc/classes/NavigationServer3D.xml b/doc/classes/NavigationServer3D.xml index 340821d41e..0d8cb78ff9 100644 --- a/doc/classes/NavigationServer3D.xml +++ b/doc/classes/NavigationServer3D.xml @@ -1,7 +1,7 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="NavigationServer3D" inherits="Object" is_experimental="true" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - Server interface for low-level 3D navigation access + Server interface for low-level 3D navigation access. </brief_description> <description> NavigationServer3D is the server responsible for all 3D navigation. It handles several objects, namely maps, regions and agents. @@ -126,6 +126,12 @@ Destroys the given RID. </description> </method> + <method name="get_debug_enabled" qualifiers="const"> + <return type="bool" /> + <description> + Returns [code]true[/code] when the NavigationServer has debug enabled. + </description> + </method> <method name="get_maps" qualifiers="const"> <return type="RID[]" /> <description> @@ -422,15 +428,6 @@ Sets the map up direction. </description> </method> - <method name="process"> - <return type="void" /> - <param index="0" name="delta_time" type="float" /> - <description> - Process the collision avoidance agents. - The result of this process is needed by the physics server, so this must be called in the main thread. - [b]Note:[/b] This function is not thread safe. - </description> - </method> <method name="query_path" qualifiers="const"> <return type="void" /> <param index="0" name="parameters" type="NavigationPathQueryParameters3D" /> @@ -584,6 +581,13 @@ Control activation of this server. </description> </method> + <method name="set_debug_enabled"> + <return type="void" /> + <param index="0" name="enabled" type="bool" /> + <description> + If [code]true[/code] enables debug mode on the NavigationServer. + </description> + </method> </methods> <signals> <signal name="map_changed"> diff --git a/doc/classes/NinePatchRect.xml b/doc/classes/NinePatchRect.xml index 1592718c4b..4b406385e1 100644 --- a/doc/classes/NinePatchRect.xml +++ b/doc/classes/NinePatchRect.xml @@ -68,11 +68,9 @@ </constant> <constant name="AXIS_STRETCH_MODE_TILE" value="1" enum="AxisStretchMode"> Repeats the center texture across the NinePatchRect. This won't cause any visible distortion. The texture must be seamless for this to work without displaying artifacts between edges. - [b]Note:[/b] Only supported when using the Vulkan renderer. When using the OpenGL renderer, this will behave like [constant AXIS_STRETCH_MODE_STRETCH]. </constant> <constant name="AXIS_STRETCH_MODE_TILE_FIT" value="2" enum="AxisStretchMode"> Repeats the center texture across the NinePatchRect, but will also stretch the texture to make sure each tile is visible in full. This may cause the texture to be distorted, but less than [constant AXIS_STRETCH_MODE_STRETCH]. The texture must be seamless for this to work without displaying artifacts between edges. - [b]Note:[/b] Only supported when using the Vulkan renderer. When using the OpenGL renderer, this will behave like [constant AXIS_STRETCH_MODE_STRETCH]. </constant> </constants> </class> diff --git a/doc/classes/Node.xml b/doc/classes/Node.xml index 7c40c189c0..bc43f228a7 100644 --- a/doc/classes/Node.xml +++ b/doc/classes/Node.xml @@ -648,7 +648,7 @@ <return type="int" enum="Error" /> <param index="0" name="method" type="StringName" /> <description> - Sends a remote procedure call request for the given [param method] to peers on the network (and locally), optionally sending all additional arguments as arguments to the method called by the RPC. The call request will only be received by nodes with the same [NodePath], including the exact same node name. Behavior depends on the RPC configuration for the given method, see [method rpc_config]. Methods are not exposed to RPCs by default. Returns [code]null[/code]. + Sends a remote procedure call request for the given [param method] to peers on the network (and locally), optionally sending all additional arguments as arguments to the method called by the RPC. The call request will only be received by nodes with the same [NodePath], including the exact same node name. Behavior depends on the RPC configuration for the given method, see [method rpc_config] and [annotation @GDScript.@rpc]. Methods are not exposed to RPCs by default. Returns [code]null[/code]. [b]Note:[/b] You can only safely use RPCs on clients after you received the [code]connected_to_server[/code] signal from the [MultiplayerAPI]. You also need to keep track of the connection state, either by the [MultiplayerAPI] signals like [code]server_disconnected[/code] or by checking [code]get_multiplayer().peer.get_connection_status() == CONNECTION_CONNECTED[/code]. </description> </method> @@ -666,7 +666,7 @@ channel = 0, } [/codeblock] - See [enum MultiplayerAPI.RPCMode] and [enum MultiplayerPeer.TransferMode]. An alternative is annotating methods and properties with the corresponding annotation ([code]@rpc("any")[/code], [code]@rpc("authority")[/code]). By default, methods are not exposed to networking (and RPCs). + See [enum MultiplayerAPI.RPCMode] and [enum MultiplayerPeer.TransferMode]. An alternative is annotating methods and properties with the corresponding [annotation @GDScript.@rpc] annotation ([code]@rpc("any_peer")[/code], [code]@rpc("authority")[/code]). By default, methods are not exposed to networking (and RPCs). </description> </method> <method name="rpc_id" qualifiers="vararg"> diff --git a/doc/classes/Node2D.xml b/doc/classes/Node2D.xml index 9d224f09b1..3b2c52c5bf 100644 --- a/doc/classes/Node2D.xml +++ b/doc/classes/Node2D.xml @@ -116,6 +116,7 @@ </member> <member name="rotation" type="float" setter="set_rotation" getter="get_rotation" default="0.0"> Rotation in radians, relative to the node's parent. + [b]Note:[/b] This property is edited in the inspector in degrees. If you want to use degrees in a script, use [member rotation_degrees]. </member> <member name="rotation_degrees" type="float" setter="set_rotation_degrees" getter="get_rotation_degrees"> Helper property to access [member rotation] in degrees instead of radians. diff --git a/doc/classes/Node3D.xml b/doc/classes/Node3D.xml index 1aa71113e9..61e5c44251 100644 --- a/doc/classes/Node3D.xml +++ b/doc/classes/Node3D.xml @@ -4,7 +4,7 @@ Most basic 3D game object, parent of all 3D-related nodes. </brief_description> <description> - Most basic 3D game object, with a 3D [Transform3D] and visibility settings. All other 3D game objects inherit from Node3D. Use [Node3D] as a parent node to move, scale, rotate and show/hide children in a 3D project. + Most basic 3D game object, with a [Transform3D] and visibility settings. All other 3D game objects inherit from Node3D. Use [Node3D] as a parent node to move, scale, rotate and show/hide children in a 3D project. Affine operations (rotate, scale, translate) happen in parent's local coordinate system, unless the [Node3D] object is set as top-level. Affine operations in this coordinate system correspond to direct affine operations on the [Node3D]'s transform. The word local below refers to this coordinate system. The coordinate system that is attached to the [Node3D] object itself is referred to as object-local coordinate system. [b]Note:[/b] Unless otherwise specified, all methods that have angle parameters must have angles specified as [i]radians[/i]. To convert degrees to radians, use [method @GlobalScope.deg_to_rad]. </description> @@ -289,6 +289,7 @@ <member name="rotation" type="Vector3" setter="set_rotation" getter="get_rotation" default="Vector3(0, 0, 0)"> Rotation part of the local transformation in radians, specified in terms of Euler angles. The angles construct a rotaton in the order specified by the [member rotation_order] property. [b]Note:[/b] In the mathematical sense, rotation is a matrix and not a vector. The three Euler angles, which are the three independent parameters of the Euler-angle parametrization of the rotation matrix, are stored in a [Vector3] data structure not because the rotation is a vector, but only because [Vector3] exists as a convenient data-structure to store 3 floating-point numbers. Therefore, applying affine operations on the rotation "vector" is not meaningful. + [b]Note:[/b] This property is edited in the inspector in degrees. If you want to use degrees in a script, use [member rotation_degrees]. </member> <member name="rotation_degrees" type="Vector3" setter="set_rotation_degrees" getter="get_rotation_degrees"> Helper property to access [member rotation] in degrees instead of radians. diff --git a/doc/classes/OS.xml b/doc/classes/OS.xml index 04895c28a8..ca090d596e 100644 --- a/doc/classes/OS.xml +++ b/doc/classes/OS.xml @@ -553,11 +553,11 @@ [b]Note:[/b] If the user has disabled the recycle bin on their system, the file will be permanently deleted instead. [codeblocks] [gdscript] - var file_to_remove = "user://slot1.sav" + var file_to_remove = "user://slot1.save" OS.move_to_trash(ProjectSettings.globalize_path(file_to_remove)) [/gdscript] [csharp] - var fileToRemove = "user://slot1.sav"; + var fileToRemove = "user://slot1.save"; OS.MoveToTrash(ProjectSettings.GlobalizePath(fileToRemove)); [/csharp] [/codeblocks] diff --git a/doc/classes/Object.xml b/doc/classes/Object.xml index e4607456ca..226a1948e1 100644 --- a/doc/classes/Object.xml +++ b/doc/classes/Object.xml @@ -110,7 +110,7 @@ [/gdscript] [csharp] [Tool] - public class MyNode2D : Node2D + public partial class MyNode2D : Node2D { private bool _holdingHammer; @@ -345,7 +345,7 @@ node.Callv(Node3D.MethodName.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 + [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"> @@ -433,9 +433,9 @@ var button = new Button(); // Option 1: In C#, we can use signals as events and connect with this idiomatic syntax: button.ButtonDown += OnButtonDown; - // Option 2: Object.Connect() with a constructed Callable from a method group. + // Option 2: GodotObject.Connect() with a constructed Callable from a method group. button.Connect(Button.SignalName.ButtonDown, Callable.From(OnButtonDown)); - // Option 3: Object.Connect() with a constructed Callable using a target object and method name. + // Option 3: GodotObject.Connect() with a constructed Callable using a target object and method name. button.Connect(Button.SignalName.ButtonDown, new Callable(this, MethodName.OnButtonDown)); } @@ -639,7 +639,7 @@ <description> 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]callable[/code] is a reference to the connected [Callable]; - [code]flags[/code] is a combination of [enum ConnectFlags]. </description> </method> @@ -700,10 +700,10 @@ 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 + 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. @@ -747,10 +747,10 @@ player.SetScript(GD.Load("res://player.gd")); player.Notification(NotificationEnterTree); - // The call order is Object -> Node -> Node2D -> player.gd. + // The call order is GodotObject -> Node -> Node2D -> player.gd. - player.notification(NotificationEnterTree, true); - // The call order is player.gd -> Node2D -> Node -> Object. + player.Notification(NotificationEnterTree, true); + // The call order is player.gd -> Node2D -> Node -> GodotObject. [/csharp] [/codeblocks] </description> diff --git a/doc/classes/OmniLight3D.xml b/doc/classes/OmniLight3D.xml index f71c81e713..7c5b9aff46 100644 --- a/doc/classes/OmniLight3D.xml +++ b/doc/classes/OmniLight3D.xml @@ -5,13 +5,16 @@ </brief_description> <description> An Omnidirectional light is a type of [Light3D] that emits light in all directions. The light is attenuated by distance and this attenuation can be configured by changing its energy, radius, and attenuation parameters. + [b]Note:[/b] When using the Mobile rendering method, only 8 omni lights can be displayed on each mesh resource. Attempting to display more than 8 omni lights on a single mesh resource will result in omni lights flickering in and out as the camera moves. When using the Compatibility rendering method, only 8 omni lights can be displayed on each mesh resource by default, but this can be increased by adjusting [member ProjectSettings.rendering/limits/opengl/max_lights_per_object]. + [b]Note:[/b] When using the Mobile or Compatibility rendering methods, omni lights will only correctly affect meshes whose visibility AABB intersects with the light's AABB. If using a shader to deform the mesh in a way that makes it go outside its AABB, [member GeometryInstance3D.extra_cull_margin] must be increased on the mesh. Otherwise, the light may not be visible on the mesh. </description> <tutorials> <link title="3D lights and shadows">$DOCS_URL/tutorials/3d/lights_and_shadows.html</link> </tutorials> <members> <member name="omni_attenuation" type="float" setter="set_param" getter="get_param" default="1.0"> - The light's attenuation (drop-off) curve. A number of presets are available in the [b]Inspector[/b] by right-clicking the curve. + The light's attenuation (drop-off) curve. A number of presets are available in the [b]Inspector[/b] by right-clicking the curve. Zero and negative values are allowed but can produce unusual effects. + [b]Note:[/b] Very high [member omni_attenuation] values (typically above 10) can impact performance negatively if the light is made to use a larger [member omni_range] to compensate. This is because culling opportunities will become less common and shading costs will be increased (as the light will cover more pixels on screen while resulting in the same amount of brightness). To improve performance, use the lowest [member omni_attenuation] value possible for the visuals you're trying to achieve. </member> <member name="omni_range" type="float" setter="set_param" getter="get_param" default="5.0"> The light's radius. Note that the effectively lit area may appear to be smaller depending on the [member omni_attenuation] in use. No matter the [member omni_attenuation] in use, the light will never reach anything outside this radius. diff --git a/doc/classes/PackedByteArray.xml b/doc/classes/PackedByteArray.xml index ccf012f82c..c079a70ae5 100644 --- a/doc/classes/PackedByteArray.xml +++ b/doc/classes/PackedByteArray.xml @@ -229,7 +229,7 @@ <param index="0" name="byte_offset" type="int" /> <param index="1" name="value" type="int" /> <description> - Encodes a 32-bit signed integer number as bytes at the index of [param byte_offset] bytes. The array must have at least 2 bytes of space, starting at the offset. + Encodes a 32-bit signed integer number as bytes at the index of [param byte_offset] bytes. The array must have at least 4 bytes of space, starting at the offset. </description> </method> <method name="encode_s64"> @@ -237,7 +237,7 @@ <param index="0" name="byte_offset" type="int" /> <param index="1" name="value" type="int" /> <description> - Encodes a 64-bit signed integer number as bytes at the index of [param byte_offset] bytes. The array must have at least 2 bytes of space, starting at the offset. + Encodes a 64-bit signed integer number as bytes at the index of [param byte_offset] bytes. The array must have at least 8 bytes of space, starting at the offset. </description> </method> <method name="encode_s8"> diff --git a/doc/classes/PackedScene.xml b/doc/classes/PackedScene.xml index 7ca1d5d60d..493fc9e2a8 100644 --- a/doc/classes/PackedScene.xml +++ b/doc/classes/PackedScene.xml @@ -104,7 +104,7 @@ </method> </methods> <members> - <member name="_bundled" type="Dictionary" setter="_set_bundled_scene" getter="_get_bundled_scene" default="{ "conn_count": 0, "conns": PackedInt32Array(), "editable_instances": [], "names": PackedStringArray(), "node_count": 0, "node_paths": [], "nodes": PackedInt32Array(), "variants": [], "version": 2 }"> + <member name="_bundled" type="Dictionary" setter="_set_bundled_scene" getter="_get_bundled_scene" default="{ "conn_count": 0, "conns": PackedInt32Array(), "editable_instances": [], "names": PackedStringArray(), "node_count": 0, "node_paths": [], "nodes": PackedInt32Array(), "variants": [], "version": 3 }"> A dictionary representation of the scene contents. Available keys include "rnames" and "variants" for resources, "node_count", "nodes", "node_paths" for nodes, "editable_instances" for base scene children overrides, "conn_count" and "conns" for signal connections, and "version" for the format style of the PackedScene. </member> diff --git a/doc/classes/PacketPeer.xml b/doc/classes/PacketPeer.xml index ab2bc34672..5dd9c5c9f9 100644 --- a/doc/classes/PacketPeer.xml +++ b/doc/classes/PacketPeer.xml @@ -33,6 +33,7 @@ <param index="0" name="allow_objects" type="bool" default="false" /> <description> Gets a Variant. If [param allow_objects] is [code]true[/code], decoding objects is allowed. + Internally, this uses the same decoding mechanism as the [method @GlobalScope.bytes_to_var] method. [b]Warning:[/b] Deserialized objects can contain code which gets executed. Do not use this option if the serialized object comes from untrusted sources to avoid potential security threats such as remote code execution. </description> </method> @@ -49,6 +50,7 @@ <param index="1" name="full_objects" type="bool" default="false" /> <description> Sends a [Variant] as a packet. If [param full_objects] is [code]true[/code], encoding objects is allowed (and can potentially include code). + Internally, this uses the same encoding mechanism as the [method @GlobalScope.var_to_bytes] method. </description> </method> </methods> diff --git a/doc/classes/PhysicsDirectSpaceState3D.xml b/doc/classes/PhysicsDirectSpaceState3D.xml index cc1cf8a323..f7bc74d9ad 100644 --- a/doc/classes/PhysicsDirectSpaceState3D.xml +++ b/doc/classes/PhysicsDirectSpaceState3D.xml @@ -21,7 +21,7 @@ </description> </method> <method name="collide_shape"> - <return type="PackedVector2Array[]" /> + <return type="PackedVector3Array[]" /> <param index="0" name="parameters" type="PhysicsShapeQueryParameters3D" /> <param index="1" name="max_results" type="int" default="32" /> <description> diff --git a/doc/classes/PhysicsPointQueryParameters2D.xml b/doc/classes/PhysicsPointQueryParameters2D.xml index 76dc816dab..15102830f8 100644 --- a/doc/classes/PhysicsPointQueryParameters2D.xml +++ b/doc/classes/PhysicsPointQueryParameters2D.xml @@ -11,6 +11,7 @@ <members> <member name="canvas_instance_id" type="int" setter="set_canvas_instance_id" getter="get_canvas_instance_id" default="0"> If different from [code]0[/code], restricts the query to a specific canvas layer specified by its instance ID. See [method Object.get_instance_id]. + If [code]0[/code], restricts the query to the Viewport's default canvas layer. </member> <member name="collide_with_areas" type="bool" setter="set_collide_with_areas" getter="is_collide_with_areas_enabled" default="false"> If [code]true[/code], the query will take [Area2D]s into account. diff --git a/doc/classes/PhysicsServer2D.xml b/doc/classes/PhysicsServer2D.xml index 93e88347d4..1fbe77b64b 100644 --- a/doc/classes/PhysicsServer2D.xml +++ b/doc/classes/PhysicsServer2D.xml @@ -4,7 +4,14 @@ Server interface for low-level 2D physics access. </brief_description> <description> - PhysicsServer2D is the server responsible for all 2D physics. It can create many kinds of physics objects, but does not insert them on the node tree. + PhysicsServer2D is the server responsible for all 2D physics. It can directly create and manipulate all physics objects: + - A [i]space[/i] is a self-contained world for a physics simulation. It contains bodies, areas, and joints. Its state can be queried for collision and intersection information, and several parameters of the simulation can be modified. + - A [i]shape[/i] is a geometric figure such as a circle, a rectangle, a capsule, or a polygon. It can be used for collision detection by adding it to a body/area, possibly with an extra transformation relative to the body/area's origin. Bodies/areas can have multiple (transformed) shapes added to them, and a single shape can be added to bodies/areas multiple times with different local transformations. + - A [i]body[/i] is a physical object which can be in static, kinematic, or rigid mode. Its state (such as position and velocity) can be queried and updated. A force integration callback can be set to customize the body's physics. + - An [i]area[/i] is a region in space which can be used to detect bodies and areas entering and exiting it. A body monitoring callback can be set to report entering/exiting body shapes, and similarly an area monitoring callback can be set. Gravity and damping can be overridden within the area by setting area parameters. + - A [i]joint[/i] is a constraint, either between two bodies or on one body relative to a point. Parameters such as the joint bias and the rest length of a spring joint can be adjusted. + Physics objects in the physics server may be created and manipulated independently; they do not have to be tied to nodes in the scene tree. + [b]Note:[/b] All the physics nodes use the physics server internally. Adding a physics node to the scene tree will cause a corresponding physics object to be created in the physics server. A rigid body node registers a callback that updates the node's transform with the transform of the respective body object in the physics server (every physics update). An area node registers a callback to inform the area node about overlaps with the respective area object in the physics server. The raycast node queries the direct state of the relevant space in the physics server. </description> <tutorials> </tutorials> @@ -16,7 +23,7 @@ <param index="2" name="transform" type="Transform2D" default="Transform2D(1, 0, 0, 1, 0, 0)" /> <param index="3" name="disabled" type="bool" default="false" /> <description> - Adds a shape to the area, along with a transform matrix. Shapes are usually referenced by their index, so you should track which shape has a given index. + Adds a shape to the area, with the given local transform. The shape (together with its [param transform] and [param disabled] properties) is added to an array of shapes, and the shapes of an area are usually referenced by their index in this array. </description> </method> <method name="area_attach_canvas_instance_id"> @@ -24,6 +31,7 @@ <param index="0" name="area" type="RID" /> <param index="1" name="id" type="int" /> <description> + Attaches the [code]ObjectID[/code] of a canvas to the area. Use [method Object.get_instance_id] to get the [code]ObjectID[/code] of a [CanvasLayer]. </description> </method> <method name="area_attach_object_instance_id"> @@ -31,47 +39,48 @@ <param index="0" name="area" type="RID" /> <param index="1" name="id" type="int" /> <description> - Assigns the area to a descendant of [Object], so it can exist in the node tree. + Attaches the [code]ObjectID[/code] of an [Object] to the area. Use [method Object.get_instance_id] to get the [code]ObjectID[/code] of a [CollisionObject2D]. </description> </method> <method name="area_clear_shapes"> <return type="void" /> <param index="0" name="area" type="RID" /> <description> - Removes all shapes from an area. It does not delete the shapes, so they can be reassigned later. + Removes all shapes from the area. This does not delete the shapes themselves, so they can continue to be used elsewhere or added back later. </description> </method> <method name="area_create"> <return type="RID" /> <description> - Creates an [Area2D]. After creating an [Area2D] with this method, assign it to a space using [method area_set_space] to use the created [Area2D] in the physics world. + Creates a 2D area object in the physics server, and returns the [RID] that identifies it. Use [method area_add_shape] to add shapes to it, use [method area_set_transform] to set its transform, and use [method area_set_space] to add the area to a space. </description> </method> <method name="area_get_canvas_instance_id" qualifiers="const"> <return type="int" /> <param index="0" name="area" type="RID" /> <description> + Returns the [code]ObjectID[/code] of the canvas attached to the area. Use [method @GlobalScope.instance_from_id] to retrieve a [CanvasLayer] from a nonzero [code]ObjectID[/code]. </description> </method> <method name="area_get_collision_layer" qualifiers="const"> <return type="int" /> <param index="0" name="area" type="RID" /> <description> - Returns the physics layer or layers an area belongs to. + Returns the physics layer or layers the area belongs to, as a bitmask. </description> </method> <method name="area_get_collision_mask" qualifiers="const"> <return type="int" /> <param index="0" name="area" type="RID" /> <description> - Returns the physics layer or layers an area can contact with. + Returns the physics layer or layers the area can contact with, as a bitmask. </description> </method> <method name="area_get_object_instance_id" qualifiers="const"> <return type="int" /> <param index="0" name="area" type="RID" /> <description> - Gets the instance ID of the object the area is assigned to. + Returns the [code]ObjectID[/code] attached to the area. Use [method @GlobalScope.instance_from_id] to retrieve an [Object] from a nonzero [code]ObjectID[/code]. </description> </method> <method name="area_get_param" qualifiers="const"> @@ -79,7 +88,7 @@ <param index="0" name="area" type="RID" /> <param index="1" name="param" type="int" enum="PhysicsServer2D.AreaParameter" /> <description> - Returns an area parameter value. See [enum AreaParameter] for a list of available parameters. + Returns the value of the given area parameter. See [enum AreaParameter] for the list of available parameters. </description> </method> <method name="area_get_shape" qualifiers="const"> @@ -87,14 +96,14 @@ <param index="0" name="area" type="RID" /> <param index="1" name="shape_idx" type="int" /> <description> - Returns the [RID] of the nth shape of an area. + Returns the [RID] of the shape with the given index in the area's array of shapes. </description> </method> <method name="area_get_shape_count" qualifiers="const"> <return type="int" /> <param index="0" name="area" type="RID" /> <description> - Returns the number of shapes assigned to an area. + Returns the number of shapes added to the area. </description> </method> <method name="area_get_shape_transform" qualifiers="const"> @@ -102,21 +111,21 @@ <param index="0" name="area" type="RID" /> <param index="1" name="shape_idx" type="int" /> <description> - Returns the transform matrix of a shape within an area. + Returns the local transform matrix of the shape with the given index in the area's array of shapes. </description> </method> <method name="area_get_space" qualifiers="const"> <return type="RID" /> <param index="0" name="area" type="RID" /> <description> - Returns the space assigned to the area. + Returns the [RID] of the space assigned to the area. Returns [code]RID()[/code] if no space is assigned. </description> </method> <method name="area_get_transform" qualifiers="const"> <return type="Transform2D" /> <param index="0" name="area" type="RID" /> <description> - Returns the transform matrix for an area. + Returns the transform matrix of the area. </description> </method> <method name="area_remove_shape"> @@ -124,7 +133,7 @@ <param index="0" name="area" type="RID" /> <param index="1" name="shape_idx" type="int" /> <description> - Removes a shape from an area. It does not delete the shape, so it can be reassigned later. + Removes the shape with the given index from the area's array of shapes. The shape itself is not deleted, so it can continue to be used elsewhere or added back later. As a result of this operation, the area's shapes which used to have indices higher than [param shape_idx] will have their index decreased by one. </description> </method> <method name="area_set_area_monitor_callback"> @@ -132,6 +141,13 @@ <param index="0" name="area" type="RID" /> <param index="1" name="callback" type="Callable" /> <description> + Sets the area's area monitor callback. This callback will be called when any other (shape of an) area enters or exits (a shape of) the given area, and must take the following five parameters: + 1. an integer [code]status[/code]: either [constant AREA_BODY_ADDED] or [constant AREA_BODY_REMOVED] depending on whether the other area's shape entered or exited the area, + 2. an [RID] [code]area_rid[/code]: the [RID] of the other area that entered or exited the area, + 3. an integer [code]instance_id[/code]: the [code]ObjectID[/code] attached to the other area, + 4. an integer [code]area_shape_idx[/code]: the index of the shape of the other area that entered or exited the area, + 5. an integer [code]self_shape_idx[/code]: the index of the shape of the area where the other area entered or exited. + By counting (or keeping track of) the shapes that enter and exit, it can be determined if an area (with all its shapes) is entering for the first time or exiting for the last time. </description> </method> <method name="area_set_collision_layer"> @@ -139,7 +155,7 @@ <param index="0" name="area" type="RID" /> <param index="1" name="layer" type="int" /> <description> - Assigns the area to one or many physics layers. + Assigns the area to one or many physics layers, via a bitmask. </description> </method> <method name="area_set_collision_mask"> @@ -147,7 +163,7 @@ <param index="0" name="area" type="RID" /> <param index="1" name="mask" type="int" /> <description> - Sets which physics layers the area will monitor. + Sets which physics layers the area will monitor, via a bitmask. </description> </method> <method name="area_set_monitor_callback"> @@ -155,12 +171,13 @@ <param index="0" name="area" type="RID" /> <param index="1" name="callback" type="Callable" /> <description> - Sets the function to call when any body/area enters or exits the area. This callback will be called for any object interacting with the area, and takes five parameters: - 1: [constant AREA_BODY_ADDED] or [constant AREA_BODY_REMOVED], depending on whether the object entered or exited the area. - 2: [RID] of the object that entered/exited the area. - 3: Instance ID of the object that entered/exited the area. - 4: The shape index of the object that entered/exited the area. - 5: The shape index of the area where the object entered/exited. + Sets the area's body monitor callback. This callback will be called when any other (shape of a) body enters or exits (a shape of) the given area, and must take the following five parameters: + 1. an integer [code]status[/code]: either [constant AREA_BODY_ADDED] or [constant AREA_BODY_REMOVED] depending on whether the other body shape entered or exited the area, + 2. an [RID] [code]body_rid[/code]: the [RID] of the body that entered or exited the area, + 3. an integer [code]instance_id[/code]: the [code]ObjectID[/code] attached to the body, + 4. an integer [code]body_shape_idx[/code]: the index of the shape of the body that entered or exited the area, + 5. an integer [code]self_shape_idx[/code]: the index of the shape of the area where the body entered or exited. + By counting (or keeping track of) the shapes that enter and exit, it can be determined if a body (with all its shapes) is entering for the first time or exiting for the last time. </description> </method> <method name="area_set_monitorable"> @@ -168,6 +185,7 @@ <param index="0" name="area" type="RID" /> <param index="1" name="monitorable" type="bool" /> <description> + Sets whether the area is monitorable or not. If [param monitorable] is [code]true[/code], the area monitoring callback of other areas will be called when this area enters or exits them. </description> </method> <method name="area_set_param"> @@ -176,7 +194,7 @@ <param index="1" name="param" type="int" enum="PhysicsServer2D.AreaParameter" /> <param index="2" name="value" type="Variant" /> <description> - Sets the value for an area parameter. See [enum AreaParameter] for a list of available parameters. + Sets the value of the given area parameter. See [enum AreaParameter] for the list of available parameters. </description> </method> <method name="area_set_shape"> @@ -185,7 +203,7 @@ <param index="1" name="shape_idx" type="int" /> <param index="2" name="shape" type="RID" /> <description> - Substitutes a given area shape by another. The old shape is selected by its index, the new one by its [RID]. + Replaces the area's shape at the given index by another shape, while not affecting the [code]transform[/code] and [code]disabled[/code] properties at the same index. </description> </method> <method name="area_set_shape_disabled"> @@ -194,7 +212,7 @@ <param index="1" name="shape_idx" type="int" /> <param index="2" name="disabled" type="bool" /> <description> - Disables a given shape in an area. + Sets the disabled property of the area's shape with the given index. If [param disabled] is [code]true[/code], then the shape will not detect any other shapes entering or exiting it. </description> </method> <method name="area_set_shape_transform"> @@ -203,7 +221,7 @@ <param index="1" name="shape_idx" type="int" /> <param index="2" name="transform" type="Transform2D" /> <description> - Sets the transform matrix for an area shape. + Sets the local transform matrix of the area's shape with the given index. </description> </method> <method name="area_set_space"> @@ -211,7 +229,8 @@ <param index="0" name="area" type="RID" /> <param index="1" name="space" type="RID" /> <description> - Assigns a space to the area. + Adds the area to the given space, after removing the area from the previously assigned space (if any). + [b]Note:[/b] To remove an area from a space without immediately adding it back elsewhere, use [code]PhysicsServer2D.area_set_space(area, RID())[/code]. </description> </method> <method name="area_set_transform"> @@ -219,7 +238,7 @@ <param index="0" name="area" type="RID" /> <param index="1" name="transform" type="Transform2D" /> <description> - Sets the transform matrix for an area. + Sets the transform matrix of the area. </description> </method> <method name="body_add_collision_exception"> @@ -227,7 +246,7 @@ <param index="0" name="body" type="RID" /> <param index="1" name="excepted_body" type="RID" /> <description> - Adds a body to the list of bodies exempt from collisions. + Adds [param excepted_body] to the body's list of collision exceptions, so that collisions with it are ignored. </description> </method> <method name="body_add_constant_central_force"> @@ -235,7 +254,7 @@ <param index="0" name="body" type="RID" /> <param index="1" name="force" type="Vector2" /> <description> - Adds a constant directional force without affecting rotation that keeps being applied over time until cleared with [code]body_set_constant_force(body, Vector2(0, 0))[/code]. + Adds a constant directional force to the body. The force does not affect rotation. The force remains applied over time until cleared with [code]PhysicsServer2D.body_set_constant_force(body, Vector2(0, 0))[/code]. This is equivalent to using [method body_add_constant_force] at the body's center of mass. </description> </method> @@ -245,7 +264,7 @@ <param index="1" name="force" type="Vector2" /> <param index="2" name="position" type="Vector2" default="Vector2(0, 0)" /> <description> - Adds a constant positioned force to the body that keeps being applied over time until cleared with [code]body_set_constant_force(body, Vector2(0, 0))[/code]. + Adds a constant positioned force to the body. The force can affect rotation if [param position] is different from the body's center of mass. The force remains applied over time until cleared with [code]PhysicsServer2D.body_set_constant_force(body, Vector2(0, 0))[/code]. [param position] is the offset from the body origin in global coordinates. </description> </method> @@ -254,7 +273,7 @@ <param index="0" name="body" type="RID" /> <param index="1" name="torque" type="float" /> <description> - Adds a constant rotational force without affecting position that keeps being applied over time until cleared with [code]body_set_constant_torque(body, 0)[/code]. + Adds a constant rotational force to the body. The force does not affect position. The force remains applied over time until cleared with [code]PhysicsServer2D.body_set_constant_torque(body, 0)[/code]. </description> </method> <method name="body_add_shape"> @@ -264,7 +283,7 @@ <param index="2" name="transform" type="Transform2D" default="Transform2D(1, 0, 0, 1, 0, 0)" /> <param index="3" name="disabled" type="bool" default="false" /> <description> - Adds a shape to the body, along with a transform matrix. Shapes are usually referenced by their index, so you should track which shape has a given index. + Adds a shape to the area, with the given local transform. The shape (together with its [param transform] and [param disabled] properties) is added to an array of shapes, and the shapes of a body are usually referenced by their index in this array. </description> </method> <method name="body_apply_central_force"> @@ -272,7 +291,7 @@ <param index="0" name="body" type="RID" /> <param index="1" name="force" type="Vector2" /> <description> - Applies a directional force without affecting rotation. A force is time dependent and meant to be applied every physics update. + Applies a directional force to the body, at the body's center of mass. The force does not affect rotation. A force is time dependent and meant to be applied every physics update. This is equivalent to using [method body_apply_force] at the body's center of mass. </description> </method> @@ -281,7 +300,7 @@ <param index="0" name="body" type="RID" /> <param index="1" name="impulse" type="Vector2" /> <description> - Applies a directional impulse without affecting rotation. + Applies a directional impulse to the body, at the body's center of mass. The impulse does not affect rotation. An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise). This is equivalent to using [method body_apply_impulse] at the body's center of mass. </description> @@ -292,7 +311,7 @@ <param index="1" name="force" type="Vector2" /> <param index="2" name="position" type="Vector2" default="Vector2(0, 0)" /> <description> - Applies a positioned force to the body. A force is time dependent and meant to be applied every physics update. + Applies a positioned force to the body. The force can affect rotation if [param position] is different from the body's center of mass. A force is time dependent and meant to be applied every physics update. [param position] is the offset from the body origin in global coordinates. </description> </method> @@ -302,7 +321,7 @@ <param index="1" name="impulse" type="Vector2" /> <param index="2" name="position" type="Vector2" default="Vector2(0, 0)" /> <description> - Applies a positioned impulse to the body. + Applies a positioned impulse to the body. The impulse can affect rotation if [param position] is different from the body's center of mass. An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise). [param position] is the offset from the body origin in global coordinates. </description> @@ -312,7 +331,7 @@ <param index="0" name="body" type="RID" /> <param index="1" name="torque" type="float" /> <description> - Applies a rotational force without affecting position. A force is time dependent and meant to be applied every physics update. + Applies a rotational force to the body. The force does not affect position. A force is time dependent and meant to be applied every physics update. </description> </method> <method name="body_apply_torque_impulse"> @@ -320,7 +339,7 @@ <param index="0" name="body" type="RID" /> <param index="1" name="impulse" type="float" /> <description> - Applies a rotational impulse to the body without affecting the position. + Applies a rotational impulse to the body. The impulse does not affect position. An impulse is time-independent! Applying an impulse every frame would result in a framerate-dependent force. For this reason, it should only be used when simulating one-time impacts (use the "_force" functions otherwise). </description> </method> @@ -329,6 +348,7 @@ <param index="0" name="body" type="RID" /> <param index="1" name="id" type="int" /> <description> + Attaches the [code]ObjectID[/code] of a canvas to the body. Use [method Object.get_instance_id] to get the [code]ObjectID[/code] of a [CanvasLayer]. </description> </method> <method name="body_attach_object_instance_id"> @@ -336,54 +356,55 @@ <param index="0" name="body" type="RID" /> <param index="1" name="id" type="int" /> <description> - Assigns the area to a descendant of [Object], so it can exist in the node tree. + Attaches the [code]ObjectID[/code] of an [Object] to the body. Use [method Object.get_instance_id] to get the [code]ObjectID[/code] of a [CollisionObject2D]. </description> </method> <method name="body_clear_shapes"> <return type="void" /> <param index="0" name="body" type="RID" /> <description> - Removes all shapes from a body. + Removes all shapes from the body. This does not delete the shapes themselves, so they can continue to be used elsewhere or added back later. </description> </method> <method name="body_create"> <return type="RID" /> <description> - Creates a physics body. + Creates a 2D body object in the physics server, and returns the [RID] that identifies it. Use [method body_add_shape] to add shapes to it, use [method body_set_state] to set its transform, and use [method body_set_space] to add the body to a space. </description> </method> <method name="body_get_canvas_instance_id" qualifiers="const"> <return type="int" /> <param index="0" name="body" type="RID" /> <description> + Returns the [code]ObjectID[/code] of the canvas attached to the body. Use [method @GlobalScope.instance_from_id] to retrieve a [CanvasLayer] from a nonzero [code]ObjectID[/code]. </description> </method> <method name="body_get_collision_layer" qualifiers="const"> <return type="int" /> <param index="0" name="body" type="RID" /> <description> - Returns the physics layer or layers a body belongs to. + Returns the physics layer or layers the body belongs to, as a bitmask. </description> </method> <method name="body_get_collision_mask" qualifiers="const"> <return type="int" /> <param index="0" name="body" type="RID" /> <description> - Returns the physics layer or layers a body can collide with. + Returns the physics layer or layers the body can collide with, as a bitmask. </description> </method> <method name="body_get_collision_priority" qualifiers="const"> <return type="float" /> <param index="0" name="body" type="RID" /> <description> - Returns the body's collision priority. + Returns the body's collision priority. This is used in the depenetration phase of [method body_test_motion]. The higher the priority is, the lower the penetration into the body will be. </description> </method> <method name="body_get_constant_force" qualifiers="const"> <return type="Vector2" /> <param index="0" name="body" type="RID" /> <description> - Returns the body's total constant positional forces applied during each physics update. + Returns the body's total constant positional force applied during each physics update. See [method body_add_constant_force] and [method body_add_constant_central_force]. </description> </method> @@ -391,7 +412,7 @@ <return type="float" /> <param index="0" name="body" type="RID" /> <description> - Returns the body's total constant rotational forces applied during each physics update. + Returns the body's total constant rotational force applied during each physics update. See [method body_add_constant_torque]. </description> </method> @@ -399,35 +420,35 @@ <return type="int" enum="PhysicsServer2D.CCDMode" /> <param index="0" name="body" type="RID" /> <description> - Returns the continuous collision detection mode. + Returns the body's continuous collision detection mode (see [enum CCDMode]). </description> </method> <method name="body_get_direct_state"> <return type="PhysicsDirectBodyState2D" /> <param index="0" name="body" type="RID" /> <description> - Returns the [PhysicsDirectBodyState2D] of the body. Returns [code]null[/code] if the body is destroyed or removed from the physics space. + Returns the [PhysicsDirectBodyState2D] of the body. Returns [code]null[/code] if the body is destroyed or not assigned to a space. </description> </method> <method name="body_get_max_contacts_reported" qualifiers="const"> <return type="int" /> <param index="0" name="body" type="RID" /> <description> - Returns the maximum contacts that can be reported. See [method body_set_max_contacts_reported]. + Returns the maximum number of contacts that the body can report. See [method body_set_max_contacts_reported]. </description> </method> <method name="body_get_mode" qualifiers="const"> <return type="int" enum="PhysicsServer2D.BodyMode" /> <param index="0" name="body" type="RID" /> <description> - Returns the body mode. + Returns the body's mode (see [enum BodyMode]). </description> </method> <method name="body_get_object_instance_id" qualifiers="const"> <return type="int" /> <param index="0" name="body" type="RID" /> <description> - Gets the instance ID of the object the area is assigned to. + Returns the [code]ObjectID[/code] attached to the body. Use [method @GlobalScope.instance_from_id] to retrieve an [Object] from a nonzero [code]ObjectID[/code]. </description> </method> <method name="body_get_param" qualifiers="const"> @@ -435,7 +456,7 @@ <param index="0" name="body" type="RID" /> <param index="1" name="param" type="int" enum="PhysicsServer2D.BodyParameter" /> <description> - Returns the value of a body parameter. See [enum BodyParameter] for a list of available parameters. + Returns the value of the given body parameter. See [enum BodyParameter] for the list of available parameters. </description> </method> <method name="body_get_shape" qualifiers="const"> @@ -443,14 +464,14 @@ <param index="0" name="body" type="RID" /> <param index="1" name="shape_idx" type="int" /> <description> - Returns the [RID] of the nth shape of a body. + Returns the [RID] of the shape with the given index in the body's array of shapes. </description> </method> <method name="body_get_shape_count" qualifiers="const"> <return type="int" /> <param index="0" name="body" type="RID" /> <description> - Returns the number of shapes assigned to a body. + Returns the number of shapes added to the body. </description> </method> <method name="body_get_shape_transform" qualifiers="const"> @@ -458,14 +479,14 @@ <param index="0" name="body" type="RID" /> <param index="1" name="shape_idx" type="int" /> <description> - Returns the transform matrix of a body shape. + Returns the local transform matrix of the shape with the given index in the area's array of shapes. </description> </method> <method name="body_get_space" qualifiers="const"> <return type="RID" /> <param index="0" name="body" type="RID" /> <description> - Returns the [RID] of the space assigned to a body. + Returns the [RID] of the space assigned to the body. Returns [code]RID()[/code] if no space is assigned. </description> </method> <method name="body_get_state" qualifiers="const"> @@ -473,14 +494,14 @@ <param index="0" name="body" type="RID" /> <param index="1" name="state" type="int" enum="PhysicsServer2D.BodyState" /> <description> - Returns a body state. + Returns the value of the given state of the body. See [enum BodyState] for the list of available states. </description> </method> <method name="body_is_omitting_force_integration" qualifiers="const"> <return type="bool" /> <param index="0" name="body" type="RID" /> <description> - Returns whether a body uses a callback function to calculate its own physics (see [method body_set_force_integration_callback]). + Returns [code]true[/code] if the body uses a callback function to calculate its own physics (see [method body_set_force_integration_callback]). </description> </method> <method name="body_remove_collision_exception"> @@ -488,7 +509,7 @@ <param index="0" name="body" type="RID" /> <param index="1" name="excepted_body" type="RID" /> <description> - Removes a body from the list of bodies exempt from collisions. + Removes [param excepted_body] from the body's list of collision exceptions, so that collisions with it are no longer ignored. </description> </method> <method name="body_remove_shape"> @@ -496,14 +517,14 @@ <param index="0" name="body" type="RID" /> <param index="1" name="shape_idx" type="int" /> <description> - Removes a shape from a body. The shape is not deleted, so it can be reused afterwards. + Removes the shape with the given index from the body's array of shapes. The shape itself is not deleted, so it can continue to be used elsewhere or added back later. As a result of this operation, the body's shapes which used to have indices higher than [param shape_idx] will have their index decreased by one. </description> </method> <method name="body_reset_mass_properties"> <return type="void" /> <param index="0" name="body" type="RID" /> <description> - Restores the default inertia and center of mass based on shapes to cancel any custom values previously set using [method body_set_param]. + Restores the default inertia and center of mass of the body based on its shapes. This undoes any custom values previously set using [method body_set_param]. </description> </method> <method name="body_set_axis_velocity"> @@ -511,7 +532,7 @@ <param index="0" name="body" type="RID" /> <param index="1" name="axis_velocity" type="Vector2" /> <description> - Sets an axis velocity. The velocity in the given vector axis will be set as the given vector length. This is useful for jumping behavior. + Modifies the body's linear velocity so that its projection to the axis [code]axis_velocity.normalized()[/code] is exactly [code]axis_velocity.length()[/code]. This is useful for jumping behavior. </description> </method> <method name="body_set_collision_layer"> @@ -519,7 +540,7 @@ <param index="0" name="body" type="RID" /> <param index="1" name="layer" type="int" /> <description> - Sets the physics layer or layers a body belongs to. + Sets the physics layer or layers the body belongs to, via a bitmask. </description> </method> <method name="body_set_collision_mask"> @@ -527,7 +548,7 @@ <param index="0" name="body" type="RID" /> <param index="1" name="mask" type="int" /> <description> - Sets the physics layer or layers a body can collide with. + Sets the physics layer or layers the body can collide with, via a bitmask. </description> </method> <method name="body_set_collision_priority"> @@ -535,7 +556,7 @@ <param index="0" name="body" type="RID" /> <param index="1" name="priority" type="float" /> <description> - Sets the body's collision priority. + Sets the body's collision priority. This is used in the depenetration phase of [method body_test_motion]. The higher the priority is, the lower the penetration into the body will be. </description> </method> <method name="body_set_constant_force"> @@ -543,7 +564,7 @@ <param index="0" name="body" type="RID" /> <param index="1" name="force" type="Vector2" /> <description> - Sets the body's total constant positional forces applied during each physics update. + Sets the body's total constant positional force applied during each physics update. See [method body_add_constant_force] and [method body_add_constant_central_force]. </description> </method> @@ -552,7 +573,7 @@ <param index="0" name="body" type="RID" /> <param index="1" name="torque" type="float" /> <description> - Sets the body's total constant rotational forces applied during each physics update. + Sets the body's total constant rotational force applied during each physics update. See [method body_add_constant_torque]. </description> </method> @@ -562,7 +583,7 @@ <param index="1" name="mode" type="int" enum="PhysicsServer2D.CCDMode" /> <description> Sets the continuous collision detection mode using one of the [enum CCDMode] constants. - Continuous collision detection tries to predict where a moving body will collide, instead of moving it and correcting its movement if it collided. + Continuous collision detection tries to predict where a moving body would collide in between physics updates, instead of moving it and correcting its movement if it collided. </description> </method> <method name="body_set_force_integration_callback"> @@ -571,10 +592,11 @@ <param index="1" name="callable" type="Callable" /> <param index="2" name="userdata" type="Variant" default="null" /> <description> - Sets the function used to calculate physics for an object, if that object allows it (see [method body_set_omit_force_integration]). - The force integration function takes 2 arguments: - [code]state:[/code] [PhysicsDirectBodyState2D] used to retrieve and modify the body's state. - [code]userdata:[/code] Optional user data, if it was passed when calling [code]body_set_force_integration_callback[/code]. + Sets the function used to calculate physics for the body, if that body allows it (see [method body_set_omit_force_integration]). + The force integration function takes the following two parameters: + 1. a [PhysicsDirectBodyState2D] [code]state[/code]: used to retrieve and modify the body's state, + 2. a [Variant] [code]userdata[/code]: optional user data. + [b]Note:[/b] This callback is currently not called in Godot Physics. </description> </method> <method name="body_set_max_contacts_reported"> @@ -582,7 +604,7 @@ <param index="0" name="body" type="RID" /> <param index="1" name="amount" type="int" /> <description> - Sets the maximum contacts to report. Bodies can keep a log of the contacts with other bodies. This is enabled by setting the maximum number of contacts reported to a number greater than 0. + Sets the maximum number of contacts that the body can report. If [param amount] is greater than zero, then the body will keep track of at most this many contacts with other bodies. </description> </method> <method name="body_set_mode"> @@ -590,7 +612,7 @@ <param index="0" name="body" type="RID" /> <param index="1" name="mode" type="int" enum="PhysicsServer2D.BodyMode" /> <description> - Sets the body mode using one of the [enum BodyMode] constants. + Sets the body's mode. See [enum BodyMode] for the list of available modes. </description> </method> <method name="body_set_omit_force_integration"> @@ -598,7 +620,7 @@ <param index="0" name="body" type="RID" /> <param index="1" name="enable" type="bool" /> <description> - Sets whether a body uses a callback function to calculate its own physics (see [method body_set_force_integration_callback]). + Sets whether the body uses a callback function to calculate its own physics (see [method body_set_force_integration_callback]). </description> </method> <method name="body_set_param"> @@ -607,7 +629,7 @@ <param index="1" name="param" type="int" enum="PhysicsServer2D.BodyParameter" /> <param index="2" name="value" type="Variant" /> <description> - Sets a body parameter. See [enum BodyParameter] for a list of available parameters. + Sets the value of the given body parameter. See [enum BodyParameter] for the list of available parameters. </description> </method> <method name="body_set_shape"> @@ -616,7 +638,7 @@ <param index="1" name="shape_idx" type="int" /> <param index="2" name="shape" type="RID" /> <description> - Substitutes a given body shape by another. The old shape is selected by its index, the new one by its [RID]. + Replaces the body's shape at the given index by another shape, while not affecting the [code]transform[/code], [code]disabled[/code], and one-way collision properties at the same index. </description> </method> <method name="body_set_shape_as_one_way_collision"> @@ -626,7 +648,7 @@ <param index="2" name="enable" type="bool" /> <param index="3" name="margin" type="float" /> <description> - Enables one way collision on body if [param enable] is [code]true[/code]. + Sets the one-way collision properties of the body's shape with the given index. If [param enable] is [code]true[/code], the one-way collision direction given by the shape's local upward axis [code]body_get_shape_transform(body, shape_idx).y[/code] will be used to ignore collisions with the shape in the opposite direction, and to ensure depenetration of kinematic bodies happens in this direction. </description> </method> <method name="body_set_shape_disabled"> @@ -635,7 +657,7 @@ <param index="1" name="shape_idx" type="int" /> <param index="2" name="disabled" type="bool" /> <description> - Disables shape in body if [param disabled] is [code]true[/code]. + Sets the disabled property of the body's shape with the given index. If [param disabled] is [code]true[/code], then the shape will be ignored in all collision detection. </description> </method> <method name="body_set_shape_transform"> @@ -644,7 +666,7 @@ <param index="1" name="shape_idx" type="int" /> <param index="2" name="transform" type="Transform2D" /> <description> - Sets the transform matrix for a body shape. + Sets the local transform matrix of the body's shape with the given index. </description> </method> <method name="body_set_space"> @@ -652,7 +674,10 @@ <param index="0" name="body" type="RID" /> <param index="1" name="space" type="RID" /> <description> - Assigns a space to the body (see [method space_create]). + Adds the body to the given space, after removing the body from the previously assigned space (if any). If the body's mode is set to [constant BODY_MODE_RIGID], then adding the body to a space will have the following additional effects: + - If the parameter [constant BODY_PARAM_CENTER_OF_MASS] has never been set explicitly, then the value of that parameter will be recalculated based on the body's shapes. + - If the parameter [constant BODY_PARAM_INERTIA] is set to a value [code]<= 0.0[/code], then the value of that parameter will be recalculated based on the body's shapes, mass, and center of mass. + [b]Note:[/b] To remove a body from a space without immediately adding it back elsewhere, use [code]PhysicsServer2D.body_set_space(body, RID())[/code]. </description> </method> <method name="body_set_state"> @@ -661,8 +686,8 @@ <param index="1" name="state" type="int" enum="PhysicsServer2D.BodyState" /> <param index="2" name="value" type="Variant" /> <description> - Sets a body state using one of the [enum BodyState] constants. - Note that the method doesn't take effect immediately. The state will change on the next physics frame. + Sets the value of a body's state. See [enum BodyState] for the list of available states. + [b]Note:[/b] The state change doesn't take effect immediately. The state will change on the next physics frame. </description> </method> <method name="body_test_motion"> @@ -671,27 +696,31 @@ <param index="1" name="parameters" type="PhysicsTestMotionParameters2D" /> <param index="2" name="result" type="PhysicsTestMotionResult2D" default="null" /> <description> - Returns [code]true[/code] if a collision would result from moving along a motion vector from a given point in space. [PhysicsTestMotionParameters2D] is passed to set motion parameters. [PhysicsTestMotionResult2D] can be passed to return additional information. + Returns [code]true[/code] if a collision would result from moving the body along a motion vector from a given point in space. See [PhysicsTestMotionParameters2D] for the available motion parameters. Optionally a [PhysicsTestMotionResult2D] object can be passed, which will be used to store the information about the resulting collision. </description> </method> <method name="capsule_shape_create"> <return type="RID" /> <description> + Creates a 2D capsule shape in the physics server, and returns the [RID] that identifies it. Use [method shape_set_data] to set the capsule's height and radius. </description> </method> <method name="circle_shape_create"> <return type="RID" /> <description> + Creates a 2D circle shape in the physics server, and returns the [RID] that identifies it. Use [method shape_set_data] to set the circle's radius. </description> </method> <method name="concave_polygon_shape_create"> <return type="RID" /> <description> + Creates a 2D concave polygon shape in the physics server, and returns the [RID] that identifies it. Use [method shape_set_data] to set the concave polygon's segments. </description> </method> <method name="convex_polygon_shape_create"> <return type="RID" /> <description> + Creates a 2D convex polygon shape in the physics server, and returns the [RID] that identifies it. Use [method shape_set_data] to set the convex polygon's points. </description> </method> <method name="damped_spring_joint_get_param" qualifiers="const"> @@ -699,7 +728,7 @@ <param index="0" name="joint" type="RID" /> <param index="1" name="param" type="int" enum="PhysicsServer2D.DampedSpringParam" /> <description> - Returns the value of a damped spring joint parameter. See [enum DampedSpringParam] for a list of available parameters. + Returns the value of the given damped spring joint parameter. See [enum DampedSpringParam] for the list of available parameters. </description> </method> <method name="damped_spring_joint_set_param"> @@ -708,32 +737,34 @@ <param index="1" name="param" type="int" enum="PhysicsServer2D.DampedSpringParam" /> <param index="2" name="value" type="float" /> <description> - Sets a damped spring joint parameter. See [enum DampedSpringParam] for a list of available parameters. + Sets the value of the given damped spring joint parameter. See [enum DampedSpringParam] for the list of available parameters. </description> </method> <method name="free_rid"> <return type="void" /> <param index="0" name="rid" type="RID" /> <description> - Destroys any of the objects created by PhysicsServer2D. If the [RID] passed is not one of the objects that can be created by PhysicsServer2D, an error will be sent to the console. + Destroys any of the objects created by PhysicsServer2D. If the [RID] passed is not one of the objects that can be created by PhysicsServer2D, an error will be printed to the console. </description> </method> <method name="get_process_info"> <return type="int" /> <param index="0" name="process_info" type="int" enum="PhysicsServer2D.ProcessInfo" /> <description> - Returns information about the current state of the 2D physics engine. See [enum ProcessInfo] for a list of available states. + Returns information about the current state of the 2D physics engine. See [enum ProcessInfo] for the list of available states. </description> </method> <method name="joint_clear"> <return type="void" /> <param index="0" name="joint" type="RID" /> <description> + Destroys the joint with the given [RID], creates a new uninitialized joint, and makes the [RID] refer to this new joint. </description> </method> <method name="joint_create"> <return type="RID" /> <description> + Creates a 2D joint in the physics server, and returns the [RID] that identifies it. To set the joint type, use [method joint_make_damped_spring], [method joint_make_groove] or [method joint_make_pin]. Use [method joint_set_param] to set generic joint parameters. </description> </method> <method name="joint_disable_collisions_between_bodies"> @@ -749,14 +780,14 @@ <param index="0" name="joint" type="RID" /> <param index="1" name="param" type="int" enum="PhysicsServer2D.JointParam" /> <description> - Returns the value of a joint parameter. + Returns the value of the given joint parameter. See [enum JointParam] for the list of available parameters. </description> </method> <method name="joint_get_type" qualifiers="const"> <return type="int" enum="PhysicsServer2D.JointType" /> <param index="0" name="joint" type="RID" /> <description> - Returns a joint's type (see [enum JointType]). + Returns the joint's type (see [enum JointType]). </description> </method> <method name="joint_is_disabled_collisions_between_bodies" qualifiers="const"> @@ -774,6 +805,7 @@ <param index="3" name="body_a" type="RID" /> <param index="4" name="body_b" type="RID" /> <description> + Makes the joint a damped spring joint, attached at the point [param anchor_a] (given in global coordinates) on the body [param body_a] and at the point [param anchor_b] (given in global coordinates) on the body [param body_b]. To set the parameters which are specific to the damped spring, see [method damped_spring_joint_set_param]. </description> </method> <method name="joint_make_groove"> @@ -785,6 +817,7 @@ <param index="4" name="body_a" type="RID" /> <param index="5" name="body_b" type="RID" /> <description> + Makes the joint a groove joint. </description> </method> <method name="joint_make_pin"> @@ -794,6 +827,7 @@ <param index="2" name="body_a" type="RID" /> <param index="3" name="body_b" type="RID" /> <description> + Makes the joint a pin joint. If [param body_b] is [code]RID()[/code], then [param body_a] is pinned to the point [param anchor] (given in global coordinates); otherwise, [param body_a] is pinned to [param body_b] at the point [param anchor] (given in global coordinates). To set the parameters which are specific to the pin joint, see [method pin_joint_set_param]. </description> </method> <method name="joint_set_param"> @@ -802,7 +836,7 @@ <param index="1" name="param" type="int" enum="PhysicsServer2D.JointParam" /> <param index="2" name="value" type="float" /> <description> - Sets a joint parameter. See [enum JointParam] for a list of available parameters. + Sets the value of the given joint parameter. See [enum JointParam] for the list of available parameters. </description> </method> <method name="pin_joint_get_param" qualifiers="const"> @@ -825,37 +859,40 @@ <method name="rectangle_shape_create"> <return type="RID" /> <description> + Creates a 2D rectangle shape in the physics server, and returns the [RID] that identifies it. Use [method shape_set_data] to set the rectangle's half-extents. </description> </method> <method name="segment_shape_create"> <return type="RID" /> <description> + Creates a 2D segment shape in the physics server, and returns the [RID] that identifies it. Use [method shape_set_data] to set the segment's start and end points. </description> </method> <method name="separation_ray_shape_create"> <return type="RID" /> <description> + Creates a 2D separation ray shape in the physics server, and returns the [RID] that identifies it. Use [method shape_set_data] to set the shape's [code]length[/code] and [code]slide_on_slope[/code] properties. </description> </method> <method name="set_active"> <return type="void" /> <param index="0" name="active" type="bool" /> <description> - Activates or deactivates the 2D physics engine. + Activates or deactivates the 2D physics server. If [param active] is [code]false[/code], then the physics server will not do anything in its physics step. </description> </method> <method name="shape_get_data" qualifiers="const"> <return type="Variant" /> <param index="0" name="shape" type="RID" /> <description> - Returns the shape data. + Returns the shape data that defines the configuration of the shape, such as the half-extents of a rectangle or the segments of a concave shape. See [method shape_set_data] for the precise format of this data in each case. </description> </method> <method name="shape_get_type" qualifiers="const"> <return type="int" enum="PhysicsServer2D.ShapeType" /> <param index="0" name="shape" type="RID" /> <description> - Returns a shape's type (see [enum ShapeType]). + Returns the shape's type (see [enum ShapeType]). </description> </method> <method name="shape_set_data"> @@ -863,20 +900,29 @@ <param index="0" name="shape" type="RID" /> <param index="1" name="data" type="Variant" /> <description> - Sets the shape data that defines its shape and size. The data to be passed depends on the kind of shape created [method shape_get_type]. + Sets the shape data that defines the configuration of the shape. The [param data] to be passed depends on the shape's type (see [method shape_get_type]): + - [constant SHAPE_WORLD_BOUNDARY]: an array of length two containing a [Vector2] [code]normal[/code] direction and a [code]float[/code] distance [code]d[/code], + - [constant SHAPE_SEPARATION_RAY]: a dictionary containing the key [code]length[/code] with a [code]float[/code] value and the key [code]slide_on_slope[/code] with a [code]bool[/code] value, + - [constant SHAPE_SEGMENT]: a [Rect2] [code]rect[/code] containing the first point of the segment in [code]rect.position[/code] and the second point of the segment in [code]rect.size[/code], + - [constant SHAPE_CIRCLE]: a [code]float[/code] [code]radius[/code], + - [constant SHAPE_RECTANGLE]: a [Vector2] [code]half_extents[/code], + - [constant SHAPE_CAPSULE]: an array of length two (or a [Vector2]) containing a [code]float[/code] [code]height[/code] and a [code]float[/code] [code]radius[/code], + - [constant SHAPE_CONVEX_POLYGON]: either a [PackedVector2Array] of points defining a convex polygon in counterclockwise order (the clockwise outward normal of each segment formed by consecutive points is calculated internally), or a [PackedFloat32Array] of length divisible by four so that every 4-tuple of [code]float[/code]s contains the coordinates of a point followed by the coordinates of the clockwise outward normal vector to the segment between the current point and the next point, + - [constant SHAPE_CONCAVE_POLYGON]: a [PackedVector2Array] of length divisible by two (each pair of points forms one segment). + [b]Warning[/b]: In the case of [constant SHAPE_CONVEX_POLYGON], this method does not check if the points supplied actually form a convex polygon (unlike the [member CollisionPolygon2D.polygon] property). </description> </method> <method name="space_create"> <return type="RID" /> <description> - Creates a space. A space is a collection of parameters for the physics engine that can be assigned to an area or a body. It can be assigned to an area with [method area_set_space], or to a body with [method body_set_space]. + Creates a 2D space in the physics server, and returns the [RID] that identifies it. A space contains bodies and areas, and controls the stepping of the physics simulation of the objects in it. </description> </method> <method name="space_get_direct_state"> <return type="PhysicsDirectSpaceState2D" /> <param index="0" name="space" type="RID" /> <description> - Returns the state of a space, a [PhysicsDirectSpaceState2D]. This object can be used to make collision/intersection queries. + Returns the state of a space, a [PhysicsDirectSpaceState2D]. This object can be used for collision/intersection queries. </description> </method> <method name="space_get_param" qualifiers="const"> @@ -884,14 +930,14 @@ <param index="0" name="space" type="RID" /> <param index="1" name="param" type="int" enum="PhysicsServer2D.SpaceParameter" /> <description> - Returns the value of a space parameter. + Returns the value of the given space parameter. See [enum SpaceParameter] for the list of available parameters. </description> </method> <method name="space_is_active" qualifiers="const"> <return type="bool" /> <param index="0" name="space" type="RID" /> <description> - Returns whether the space is active. + Returns [code]true[/code] if the space is active. </description> </method> <method name="space_set_active"> @@ -899,7 +945,7 @@ <param index="0" name="space" type="RID" /> <param index="1" name="active" type="bool" /> <description> - Marks a space as active. It will not have an effect, unless it is assigned to an area or body. + Activates or deactivates the space. If [param active] is [code]false[/code], then the physics server will not do anything with this space in its physics step. </description> </method> <method name="space_set_param"> @@ -908,42 +954,43 @@ <param index="1" name="param" type="int" enum="PhysicsServer2D.SpaceParameter" /> <param index="2" name="value" type="float" /> <description> - Sets the value for a space parameter. See [enum SpaceParameter] for a list of available parameters. + Sets the value of the given space parameter. See [enum SpaceParameter] for the list of available parameters. </description> </method> <method name="world_boundary_shape_create"> <return type="RID" /> <description> + Creates a 2D world boundary shape in the physics server, and returns the [RID] that identifies it. Use [method shape_set_data] to set the shape's normal direction and distance properties. </description> </method> </methods> <constants> <constant name="SPACE_PARAM_CONTACT_RECYCLE_RADIUS" value="0" enum="SpaceParameter"> - Constant to set/get the maximum distance a pair of bodies has to move before their collision status has to be recalculated. + Constant to set/get the maximum distance a pair of bodies has to move before their collision status has to be recalculated. The default value of this parameter is [member ProjectSettings.physics/2d/solver/contact_recycle_radius]. </constant> <constant name="SPACE_PARAM_CONTACT_MAX_SEPARATION" value="1" enum="SpaceParameter"> - Constant to set/get the maximum distance a shape can be from another before they are considered separated and the contact is discarded. + Constant to set/get the maximum distance a shape can be from another before they are considered separated and the contact is discarded. The default value of this parameter is [member ProjectSettings.physics/2d/solver/contact_max_separation]. </constant> <constant name="SPACE_PARAM_CONTACT_MAX_ALLOWED_PENETRATION" value="2" enum="SpaceParameter"> - Constant to set/get the maximum distance a shape can penetrate another shape before it is considered a collision. + Constant to set/get the maximum distance a shape can penetrate another shape before it is considered a collision. The default value of this parameter is [member ProjectSettings.physics/2d/solver/contact_max_allowed_penetration]. </constant> <constant name="SPACE_PARAM_CONTACT_DEFAULT_BIAS" value="3" enum="SpaceParameter"> - Constant to set/get the default solver bias for all physics contacts. A solver bias is a factor controlling how much two objects "rebound", after overlapping, to avoid leaving them in that state because of numerical imprecision. + Constant to set/get the default solver bias for all physics contacts. A solver bias is a factor controlling how much two objects "rebound", after overlapping, to avoid leaving them in that state because of numerical imprecision. The default value of this parameter is [member ProjectSettings.physics/2d/solver/default_contact_bias]. </constant> <constant name="SPACE_PARAM_BODY_LINEAR_VELOCITY_SLEEP_THRESHOLD" value="4" enum="SpaceParameter"> - Constant to set/get the threshold linear velocity of activity. A body marked as potentially inactive for both linear and angular velocity will be put to sleep after the time given. + Constant to set/get the threshold linear velocity of activity. A body marked as potentially inactive for both linear and angular velocity will be put to sleep after the time given. The default value of this parameter is [member ProjectSettings.physics/2d/sleep_threshold_linear]. </constant> <constant name="SPACE_PARAM_BODY_ANGULAR_VELOCITY_SLEEP_THRESHOLD" value="5" enum="SpaceParameter"> - Constant to set/get the threshold angular velocity of activity. A body marked as potentially inactive for both linear and angular velocity will be put to sleep after the time given. + Constant to set/get the threshold angular velocity of activity. A body marked as potentially inactive for both linear and angular velocity will be put to sleep after the time given. The default value of this parameter is [member ProjectSettings.physics/2d/sleep_threshold_angular]. </constant> <constant name="SPACE_PARAM_BODY_TIME_TO_SLEEP" value="6" enum="SpaceParameter"> - Constant to set/get the maximum time of activity. A body marked as potentially inactive for both linear and angular velocity will be put to sleep after this time. + Constant to set/get the maximum time of activity. A body marked as potentially inactive for both linear and angular velocity will be put to sleep after this time. The default value of this parameter is [member ProjectSettings.physics/2d/time_before_sleep]. </constant> <constant name="SPACE_PARAM_CONSTRAINT_DEFAULT_BIAS" value="7" enum="SpaceParameter"> - Constant to set/get the default solver bias for all physics constraints. A solver bias is a factor controlling how much two objects "rebound", after violating a constraint, to avoid leaving them in that state because of numerical imprecision. + Constant to set/get the default solver bias for all physics constraints. A solver bias is a factor controlling how much two objects "rebound", after violating a constraint, to avoid leaving them in that state because of numerical imprecision. The default value of this parameter is [member ProjectSettings.physics/2d/solver/default_constraint_bias]. </constant> <constant name="SPACE_PARAM_SOLVER_ITERATIONS" value="8" enum="SpaceParameter"> - Constant to set/get the number of solver iterations for all contacts and constraints. The greater the number of iterations, the more accurate the collisions will be. However, a greater number of iterations requires more CPU power, which can decrease performance. + Constant to set/get the number of solver iterations for all contacts and constraints. The greater the number of iterations, the more accurate the collisions will be. However, a greater number of iterations requires more CPU power, which can decrease performance. The default value of this parameter is [member ProjectSettings.physics/2d/solver/solver_iterations]. </constant> <constant name="SHAPE_WORLD_BOUNDARY" value="0" enum="ShapeType"> This is the constant for creating world boundary shapes. A world boundary shape is an [i]infinite[/i] line with an origin point, and a normal. Thus, it can be used for front/behind checks. @@ -964,7 +1011,7 @@ This is the constant for creating capsule shapes. A capsule shape is defined by a radius and a length. It can be used for intersections and inside/outside checks. </constant> <constant name="SHAPE_CONVEX_POLYGON" value="6" enum="ShapeType"> - This is the constant for creating convex polygon shapes. A polygon is defined by a list of points. It can be used for intersections and inside/outside checks. Unlike the [member CollisionPolygon2D.polygon] property, polygons modified with [method shape_set_data] do not verify that the points supplied form is a convex polygon. + This is the constant for creating convex polygon shapes. A polygon is defined by a list of points. It can be used for intersections and inside/outside checks. </constant> <constant name="SHAPE_CONCAVE_POLYGON" value="7" enum="ShapeType"> This is the constant for creating concave polygon shapes. A polygon is defined by a list of points. It can be used for intersections checks, but not for inside/outside checks. @@ -973,35 +1020,35 @@ This constant is used internally by the engine. Any attempt to create this kind of shape results in an error. </constant> <constant name="AREA_PARAM_GRAVITY_OVERRIDE_MODE" value="0" enum="AreaParameter"> - Constant to set/get gravity override mode in an area. See [enum AreaSpaceOverrideMode] for possible values. + Constant to set/get gravity override mode in an area. See [enum AreaSpaceOverrideMode] for possible values. The default value of this parameter is [constant AREA_SPACE_OVERRIDE_DISABLED]. </constant> <constant name="AREA_PARAM_GRAVITY" value="1" enum="AreaParameter"> - Constant to set/get gravity strength in an area. + Constant to set/get gravity strength in an area. The default value of this parameter is [code]9.80665[/code]. </constant> <constant name="AREA_PARAM_GRAVITY_VECTOR" value="2" enum="AreaParameter"> - Constant to set/get gravity vector/center in an area. + Constant to set/get gravity vector/center in an area. The default value of this parameter is [code]Vector2(0, -1)[/code]. </constant> <constant name="AREA_PARAM_GRAVITY_IS_POINT" value="3" enum="AreaParameter"> - Constant to set/get whether the gravity vector of an area is a direction, or a center point. + Constant to set/get whether the gravity vector of an area is a direction, or a center point. The default value of this parameter is [code]false[/code]. </constant> <constant name="AREA_PARAM_GRAVITY_POINT_UNIT_DISTANCE" value="4" enum="AreaParameter"> Constant to set/get the distance at which the gravity strength is equal to the gravity controlled by [constant AREA_PARAM_GRAVITY]. For example, on a planet 100 pixels in radius with a surface gravity of 4.0 px/s², set the gravity to 4.0 and the unit distance to 100.0. The gravity will have falloff according to the inverse square law, so in the example, at 200 pixels from the center the gravity will be 1.0 px/s² (twice the distance, 1/4th the gravity), at 50 pixels it will be 16.0 px/s² (half the distance, 4x the gravity), and so on. - The above is true only when the unit distance is a positive number. When the unit distance is set to 0.0, the gravity will be constant regardless of distance. + The above is true only when the unit distance is a positive number. When the unit distance is set to 0.0, the gravity will be constant regardless of distance. The default value of this parameter is [code]0.0[/code]. </constant> <constant name="AREA_PARAM_LINEAR_DAMP_OVERRIDE_MODE" value="5" enum="AreaParameter"> - Constant to set/get linear damping override mode in an area. See [enum AreaSpaceOverrideMode] for possible values. + Constant to set/get linear damping override mode in an area. See [enum AreaSpaceOverrideMode] for possible values. The default value of this parameter is [constant AREA_SPACE_OVERRIDE_DISABLED]. </constant> <constant name="AREA_PARAM_LINEAR_DAMP" value="6" enum="AreaParameter"> - Constant to set/get the linear damping factor of an area. + Constant to set/get the linear damping factor of an area. The default value of this parameter is [code]0.1[/code]. </constant> <constant name="AREA_PARAM_ANGULAR_DAMP_OVERRIDE_MODE" value="7" enum="AreaParameter"> - Constant to set/get angular damping override mode in an area. See [enum AreaSpaceOverrideMode] for possible values. + Constant to set/get angular damping override mode in an area. See [enum AreaSpaceOverrideMode] for possible values. The default value of this parameter is [constant AREA_SPACE_OVERRIDE_DISABLED]. </constant> <constant name="AREA_PARAM_ANGULAR_DAMP" value="8" enum="AreaParameter"> - Constant to set/get the angular damping factor of an area. + Constant to set/get the angular damping factor of an area. The default value of this parameter is [code]1.0[/code]. </constant> <constant name="AREA_PARAM_PRIORITY" value="9" enum="AreaParameter"> - Constant to set/get the priority (order of processing) of an area. + Constant to set/get the priority (order of processing) of an area. The default value of this parameter is [code]0[/code]. </constant> <constant name="AREA_SPACE_OVERRIDE_DISABLED" value="0" enum="AreaSpaceOverrideMode"> This area does not affect gravity/damp. These are generally areas that exist only to detect collisions, and objects entering or exiting them. @@ -1031,34 +1078,36 @@ Constant for linear rigid bodies. In this mode, a body can not rotate, and only its linear velocity is affected by external forces. </constant> <constant name="BODY_PARAM_BOUNCE" value="0" enum="BodyParameter"> - Constant to set/get a body's bounce factor. + Constant to set/get a body's bounce factor. The default value of this parameter is [code]0.0[/code]. </constant> <constant name="BODY_PARAM_FRICTION" value="1" enum="BodyParameter"> - Constant to set/get a body's friction. + Constant to set/get a body's friction. The default value of this parameter is [code]1.0[/code]. </constant> <constant name="BODY_PARAM_MASS" value="2" enum="BodyParameter"> - Constant to set/get a body's mass. + Constant to set/get a body's mass. The default value of this parameter is [code]1.0[/code]. If the body's mode is set to [constant BODY_MODE_RIGID], then setting this parameter will have the following additional effects: + - If the parameter [constant BODY_PARAM_CENTER_OF_MASS] has never been set explicitly, then the value of that parameter will be recalculated based on the body's shapes. + - If the parameter [constant BODY_PARAM_INERTIA] is set to a value [code]<= 0.0[/code], then the value of that parameter will be recalculated based on the body's shapes, mass, and center of mass. </constant> <constant name="BODY_PARAM_INERTIA" value="3" enum="BodyParameter"> - Constant to set/get a body's inertia. + Constant to set/get a body's inertia. The default value of this parameter is [code]0.0[/code]. If the body's inertia is set to a value [code]<= 0.0[/code], then the inertia will be recalculated based on the body's shapes, mass, and center of mass. </constant> <constant name="BODY_PARAM_CENTER_OF_MASS" value="4" enum="BodyParameter"> - Constant to set/get a body's center of mass position in the body's local coordinate system. + Constant to set/get a body's center of mass position in the body's local coordinate system. The default value of this parameter is [code]Vector2(0,0)[/code]. If this parameter is never set explicitly, then it is recalculated based on the body's shapes when setting the parameter [constant BODY_PARAM_MASS] or when calling [method body_set_space]. </constant> <constant name="BODY_PARAM_GRAVITY_SCALE" value="5" enum="BodyParameter"> - Constant to set/get a body's gravity multiplier. + Constant to set/get a body's gravity multiplier. The default value of this parameter is [code]1.0[/code]. </constant> <constant name="BODY_PARAM_LINEAR_DAMP_MODE" value="6" enum="BodyParameter"> - Constant to set/get a body's linear dampening mode. See [enum BodyDampMode] for possible values. + Constant to set/get a body's linear damping mode. See [enum BodyDampMode] for possible values. The default value of this parameter is [constant BODY_DAMP_MODE_COMBINE]. </constant> <constant name="BODY_PARAM_ANGULAR_DAMP_MODE" value="7" enum="BodyParameter"> - Constant to set/get a body's angular dampening mode. See [enum BodyDampMode] for possible values. + Constant to set/get a body's angular damping mode. See [enum BodyDampMode] for possible values. The default value of this parameter is [constant BODY_DAMP_MODE_COMBINE]. </constant> <constant name="BODY_PARAM_LINEAR_DAMP" value="8" enum="BodyParameter"> - Constant to set/get a body's linear dampening factor. + Constant to set/get a body's linear damping factor. The default value of this parameter is [code]0.0[/code]. </constant> <constant name="BODY_PARAM_ANGULAR_DAMP" value="9" enum="BodyParameter"> - Constant to set/get a body's angular dampening factor. + Constant to set/get a body's angular damping factor. The default value of this parameter is [code]0.0[/code]. </constant> <constant name="BODY_PARAM_MAX" value="10" enum="BodyParameter"> Represents the size of the [enum BodyParameter] enum. @@ -1097,24 +1146,31 @@ Represents the size of the [enum JointType] enum. </constant> <constant name="JOINT_PARAM_BIAS" value="0" enum="JointParam"> + Constant to set/get how fast the joint pulls the bodies back to satisfy the joint constraint. The lower the value, the more the two bodies can pull on the joint. The default value of this parameter is [code]0.0[/code]. + [b]Note:[/b] In Godot Physics, this parameter is only used for pin joints and groove joints. </constant> <constant name="JOINT_PARAM_MAX_BIAS" value="1" enum="JointParam"> + Constant to set/get the maximum speed with which the joint can apply corrections. The default value of this parameter is [code]3.40282e+38[/code]. + [b]Note:[/b] In Godot Physics, this parameter is only used for groove joints. </constant> <constant name="JOINT_PARAM_MAX_FORCE" value="2" enum="JointParam"> + Constant to set/get the maximum force that the joint can use to act on the two bodies. The default value of this parameter is [code]3.40282e+38[/code]. + [b]Note:[/b] In Godot Physics, this parameter is only used for groove joints. </constant> <constant name="PIN_JOINT_SOFTNESS" value="0" enum="PinJointParam"> + Constant to set/get a how much the bond of the pin joint can flex. The default value of this parameter is [code]0.0[/code]. </constant> <constant name="DAMPED_SPRING_REST_LENGTH" value="0" enum="DampedSpringParam"> - Sets the resting length of the spring joint. The joint will always try to go to back this length when pulled apart. + Sets the resting length of the spring joint. The joint will always try to go to back this length when pulled apart. The default value of this parameter is the distance between the joint's anchor points. </constant> <constant name="DAMPED_SPRING_STIFFNESS" value="1" enum="DampedSpringParam"> - Sets the stiffness of the spring joint. The joint applies a force equal to the stiffness times the distance from its resting length. + Sets the stiffness of the spring joint. The joint applies a force equal to the stiffness times the distance from its resting length. The default value of this parameter is [code]20.0[/code]. </constant> <constant name="DAMPED_SPRING_DAMPING" value="2" enum="DampedSpringParam"> - Sets the damping ratio of the spring joint. A value of 0 indicates an undamped spring, while 1 causes the system to reach equilibrium as fast as possible (critical damping). + Sets the damping ratio of the spring joint. A value of 0 indicates an undamped spring, while 1 causes the system to reach equilibrium as fast as possible (critical damping). The default value of this parameter is [code]1.5[/code]. </constant> <constant name="CCD_MODE_DISABLED" value="0" enum="CCDMode"> - Disables continuous collision detection. This is the fastest way to detect body collisions, but can miss small, fast-moving objects. + Disables continuous collision detection. This is the fastest way to detect body collisions, but it can miss small and/or fast-moving objects. </constant> <constant name="CCD_MODE_CAST_RAY" value="1" enum="CCDMode"> Enables continuous collision detection by raycasting. It is faster than shapecasting, but less precise. diff --git a/doc/classes/PhysicsServer3D.xml b/doc/classes/PhysicsServer3D.xml index 5b261d8414..82464d2f99 100644 --- a/doc/classes/PhysicsServer3D.xml +++ b/doc/classes/PhysicsServer3D.xml @@ -1241,7 +1241,7 @@ A factor that gets multiplied onto all rotations across the axes. </constant> <constant name="G6DOF_JOINT_ANGULAR_DAMPING" value="13" enum="G6DOFJointAxisParam"> - The amount of rotational damping across the axes. The lower, the more dampening occurs. + The amount of rotational damping across the axes. The lower, the more damping occurs. </constant> <constant name="G6DOF_JOINT_ANGULAR_RESTITUTION" value="14" enum="G6DOFJointAxisParam"> The amount of rotational restitution across the axes. The lower, the more restitution occurs. @@ -1392,16 +1392,16 @@ Constant to set/get a body's gravity multiplier. </constant> <constant name="BODY_PARAM_LINEAR_DAMP_MODE" value="6" enum="BodyParameter"> - Constant to set/get a body's linear dampening mode. See [enum BodyDampMode] for possible values. + Constant to set/get a body's linear damping mode. See [enum BodyDampMode] for possible values. </constant> <constant name="BODY_PARAM_ANGULAR_DAMP_MODE" value="7" enum="BodyParameter"> - Constant to set/get a body's angular dampening mode. See [enum BodyDampMode] for possible values. + Constant to set/get a body's angular damping mode. See [enum BodyDampMode] for possible values. </constant> <constant name="BODY_PARAM_LINEAR_DAMP" value="8" enum="BodyParameter"> - Constant to set/get a body's linear dampening factor. + Constant to set/get a body's linear damping factor. </constant> <constant name="BODY_PARAM_ANGULAR_DAMP" value="9" enum="BodyParameter"> - Constant to set/get a body's angular dampening factor. + Constant to set/get a body's angular damping factor. </constant> <constant name="BODY_PARAM_MAX" value="10" enum="BodyParameter"> Represents the size of the [enum BodyParameter] enum. diff --git a/doc/classes/PointLight2D.xml b/doc/classes/PointLight2D.xml index 0c51a78e49..dd61082876 100644 --- a/doc/classes/PointLight2D.xml +++ b/doc/classes/PointLight2D.xml @@ -4,7 +4,7 @@ Positional 2D light source. </brief_description> <description> - Casts light in a 2D environment. This light's shape is defined by a (usually grayscale) texture + 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> diff --git a/doc/classes/PopupMenu.xml b/doc/classes/PopupMenu.xml index 8dec4eaf86..97cc05d1a1 100644 --- a/doc/classes/PopupMenu.xml +++ b/doc/classes/PopupMenu.xml @@ -20,7 +20,7 @@ <param index="2" name="accel" type="int" enum="Key" default="0" /> <description> Adds a new checkable item with text [param label]. - An [param id] can optionally be provided, as well as an accelerator ([param accel]). If no [param id] is provided, one will be created from the index. If no [param accel] is provided then the default [code]0[/code] will be assigned to it. See [method get_item_accelerator] for more info on accelerators. + An [param id] can optionally be provided, as well as an accelerator ([param accel]). If no [param id] is provided, one will be created from the index. If no [param accel] is provided, then the default value of 0 (corresponding to [constant @GlobalScope.KEY_NONE]) will be assigned to the item (which means it won't have any accelerator). See [method get_item_accelerator] for more info on accelerators. [b]Note:[/b] Checkable items just display a checkmark, but don't have any built-in checking behavior and must be checked/unchecked manually. See [method set_item_checked] for more info on how to control it. </description> </method> @@ -43,7 +43,7 @@ <param index="3" name="accel" type="int" enum="Key" default="0" /> <description> Adds a new checkable item with text [param label] and icon [param texture]. - An [param id] can optionally be provided, as well as an accelerator ([param accel]). If no [param id] is provided, one will be created from the index. If no [param accel] is provided then the default [code]0[/code] will be assigned to it. See [method get_item_accelerator] for more info on accelerators. + An [param id] can optionally be provided, as well as an accelerator ([param accel]). If no [param id] is provided, one will be created from the index. If no [param accel] is provided, then the default value of 0 (corresponding to [constant @GlobalScope.KEY_NONE]) will be assigned to the item (which means it won't have any accelerator). See [method get_item_accelerator] for more info on accelerators. [b]Note:[/b] Checkable items just display a checkmark, but don't have any built-in checking behavior and must be checked/unchecked manually. See [method set_item_checked] for more info on how to control it. </description> </method> @@ -67,7 +67,7 @@ <param index="3" name="accel" type="int" enum="Key" default="0" /> <description> Adds a new item with text [param label] and icon [param texture]. - An [param id] can optionally be provided, as well as an accelerator ([param accel]). If no [param id] is provided, one will be created from the index. If no [param accel] is provided then the default [code]0[/code] will be assigned to it. See [method get_item_accelerator] for more info on accelerators. + An [param id] can optionally be provided, as well as an accelerator ([param accel]). If no [param id] is provided, one will be created from the index. If no [param accel] is provided, then the default value of 0 (corresponding to [constant @GlobalScope.KEY_NONE]) will be assigned to the item (which means it won't have any accelerator). See [method get_item_accelerator] for more info on accelerators. </description> </method> <method name="add_icon_radio_check_item"> @@ -108,7 +108,7 @@ <param index="2" name="accel" type="int" enum="Key" default="0" /> <description> Adds a new item with text [param label]. - An [param id] can optionally be provided, as well as an accelerator ([param accel]). If no [param id] is provided, one will be created from the index. If no [param accel] is provided then the default [code]0[/code] will be assigned to it. See [method get_item_accelerator] for more info on accelerators. + An [param id] can optionally be provided, as well as an accelerator ([param accel]). If no [param id] is provided, one will be created from the index. If no [param accel] is provided, then the default value of 0 (corresponding to [constant @GlobalScope.KEY_NONE]) will be assigned to the item (which means it won't have any accelerator). See [method get_item_accelerator] for more info on accelerators. [b]Note:[/b] The provided [param id] is used only in [signal id_pressed] and [signal id_focused] signals. It's not related to the [code]index[/code] arguments in e.g. [method set_item_checked]. </description> </method> @@ -122,7 +122,7 @@ <description> Adds a new multistate item with text [param label]. Contrarily to normal binary items, multistate items can have more than two states, as defined by [param max_states]. Each press or activate of the item will increase the state by one. The default value is defined by [param default_state]. - An [param id] can optionally be provided, as well as an accelerator ([param accel]). If no [param id] is provided, one will be created from the index. If no [param accel] is provided then the default [code]0[/code] will be assigned to it. See [method get_item_accelerator] for more info on accelerators. + An [param id] can optionally be provided, as well as an accelerator ([param accel]). If no [param id] is provided, one will be created from the index. If no [param accel] is provided, then the default value of 0 (corresponding to [constant @GlobalScope.KEY_NONE]) will be assigned to the item (which means it won't have any accelerator). See [method get_item_accelerator] for more info on accelerators. </description> </method> <method name="add_radio_check_item"> @@ -132,7 +132,7 @@ <param index="2" name="accel" type="int" enum="Key" default="0" /> <description> Adds a new radio check button with text [param label]. - An [param id] can optionally be provided, as well as an accelerator ([param accel]). If no [param id] is provided, one will be created from the index. If no [param accel] is provided then the default [code]0[/code] will be assigned to it. See [method get_item_accelerator] for more info on accelerators. + An [param id] can optionally be provided, as well as an accelerator ([param accel]). If no [param id] is provided, one will be created from the index. If no [param accel] is provided, then the default value of 0 (corresponding to [constant @GlobalScope.KEY_NONE]) will be assigned to the item (which means it won't have any accelerator). See [method get_item_accelerator] for more info on accelerators. [b]Note:[/b] Checkable items just display a checkmark, but don't have any built-in checking behavior and must be checked/unchecked manually. See [method set_item_checked] for more info on how to control it. </description> </method> @@ -192,7 +192,7 @@ <return type="int" enum="Key" /> <param index="0" name="index" type="int" /> <description> - Returns the accelerator of the item at the given [param index]. Accelerators are special combinations of keys that activate the item, no matter which control is focused. + Returns the accelerator of the item at the given [param index]. An accelerator is a keyboard shortcut that can be pressed to trigger the menu button even if it's not currently open. The return value is an integer which is generally a combination of [enum KeyModifierMask]s and [enum Key]s using boolean OR such as [code]KEY_MASK_CTRL | KEY_A[/code] ([kbd]Ctrl + A[/kbd]). If no accelerator is defined for the specified [param index], [method get_item_accelerator] returns [code]0[/code] (corresponding to [constant @GlobalScope.KEY_NONE]). </description> </method> <method name="get_item_icon" qualifiers="const"> @@ -345,7 +345,7 @@ <param index="0" name="index" type="int" /> <param index="1" name="accel" type="int" enum="Key" /> <description> - Sets the accelerator of the item at the given [param index]. Accelerators are special combinations of keys that activate the item, no matter which control is focused. + Sets the accelerator of the item at the given [param index]. An accelerator is a keyboard shortcut that can be pressed to trigger the menu button even if it's not currently open. [param accel] is generally a combination of [enum KeyModifierMask]s and [enum Key]s using boolean OR such as [code]KEY_MASK_CTRL | KEY_A[/code] ([kbd]Ctrl + A[/kbd]). </description> </method> <method name="set_item_as_checkable"> diff --git a/doc/classes/PrimitiveMesh.xml b/doc/classes/PrimitiveMesh.xml index b1c8907d8e..b98590d10c 100644 --- a/doc/classes/PrimitiveMesh.xml +++ b/doc/classes/PrimitiveMesh.xml @@ -48,7 +48,8 @@ The current [Material] of the primitive mesh. </member> <member name="uv2_padding" type="float" setter="set_uv2_padding" getter="get_uv2_padding" default="2.0"> - If [member add_uv2] is set, specifies the padding in pixels applied along seams of the mesh. If at generation the size of the lightmap texture can't be determined, the UVs are calculated assuming a texture size of 1024x1024. + If [member add_uv2] is set, specifies the padding in pixels applied along seams of the mesh. Lower padding values allow making better use of the lightmap texture (resulting in higher texel density), but may introduce visible lightmap bleeding along edges. + If the size of the lightmap texture can't be determined when generating the mesh, UV2 is calculated assuming a texture size of 1024x1024. </member> </members> </class> diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml index 95bd060fc6..5f6a679b30 100644 --- a/doc/classes/ProjectSettings.xml +++ b/doc/classes/ProjectSettings.xml @@ -60,6 +60,18 @@ Clears the whole configuration (not recommended, may break things). </description> </method> + <method name="get_global_class_list"> + <return type="Dictionary[]" /> + <description> + Returns an [Array] of registered global classes. Each global class is represented as a [Dictionary] that contains the following entries: + - [code]base[/code] is a name of the base class; + - [code]class[/code] is a name of the registered global class; + - [code]icon[/code] is a path to a custom icon of the global class, if it has any; + - [code]language[/code] is a name of a programming language in which the global class is written; + - [code]path[/code] is a path to a file containing the global class. + [b]Note:[/b] Both the script and the icon paths are local to the project filesystem, i.e. they start with [code]res://[/code]. + </description> + </method> <method name="get_order" qualifiers="const"> <return type="int" /> <param index="0" name="name" type="String" /> @@ -405,9 +417,15 @@ <member name="debug/gdscript/warnings/function_used_as_property" type="int" setter="" getter="" default="1"> When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when using a function as if it is a property. </member> + <member name="debug/gdscript/warnings/get_node_default_without_onready" type="int" setter="" getter="" default="2"> + When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when [method Node.get_node] (or the shorthand [code]$[/code]) is used as default value of a class variable without the [code]@onready[/code] annotation. + </member> <member name="debug/gdscript/warnings/incompatible_ternary" 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 ternary operator may emit values with incompatible types. </member> + <member name="debug/gdscript/warnings/inference_on_variant" type="int" setter="" getter="" default="2"> + When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when a static inferred type uses a [Variant] as initial value, which makes the static type to also be Variant. + </member> <member name="debug/gdscript/warnings/int_as_enum_without_cast" type="int" setter="" getter="" default="1"> When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when trying to use an integer as an enum without an explicit cast. </member> @@ -420,6 +438,12 @@ <member name="debug/gdscript/warnings/narrowing_conversion" type="int" setter="" getter="" default="1"> When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when passing a floating-point value to a function that expects an integer (it will be converted and lose precision). </member> + <member name="debug/gdscript/warnings/native_method_override" type="int" setter="" getter="" default="2"> + When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when a method in the script overrides a native method, because it may not behave as expected. + </member> + <member name="debug/gdscript/warnings/onready_with_export" type="int" setter="" getter="" default="2"> + When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when the [code]@onready[/code] annotation is used together with the [code]@export[/code] annotation, since it may not behave as expected. + </member> <member name="debug/gdscript/warnings/property_used_as_function" type="int" setter="" getter="" default="1"> When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when using a property as if it is a function. </member> @@ -450,9 +474,6 @@ <member name="debug/gdscript/warnings/static_called_on_instance" type="int" setter="" getter="" default="1"> When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when calling a static method from an instance of a class instead of from the class directly. </member> - <member name="debug/gdscript/warnings/treat_warnings_as_errors" type="bool" setter="" getter="" default="false"> - If [code]true[/code], all warnings will be reported as if they are errors. - </member> <member name="debug/gdscript/warnings/unassigned_variable" type="int" setter="" getter="" default="1"> When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when using a variable that wasn't previously assigned. </member> @@ -477,7 +498,7 @@ <member name="debug/gdscript/warnings/unsafe_property_access" type="int" setter="" getter="" default="0"> When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when accessing a property whose presence is not guaranteed at compile-time in the class. </member> - <member name="debug/gdscript/warnings/unsafe_void_return" type="int" setter="" getter="" default="0"> + <member name="debug/gdscript/warnings/unsafe_void_return" type="int" setter="" getter="" default="1"> When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when returning a call from a [code]void[/code] function when such call cannot be guaranteed to be also [code]void[/code]. </member> <member name="debug/gdscript/warnings/unused_local_constant" type="int" setter="" getter="" default="1"> @@ -528,9 +549,21 @@ <member name="debug/shapes/collision/shape_color" type="Color" setter="" getter="" default="Color(0, 0.6, 0.7, 0.42)"> Color of the collision shapes, visible when "Visible Collision Shapes" is enabled in the Debug menu. </member> + <member name="debug/shapes/navigation/agent_path_color" type="Color" setter="" getter="" default="Color(1, 0, 0, 1)"> + Color to display enabled navigation agent paths when an agent has debug enabled. + </member> + <member name="debug/shapes/navigation/agent_path_point_size" type="float" setter="" getter="" default="4.0"> + Rasterized size (pixel) used to render navigation agent path points when an agent has debug enabled. + </member> <member name="debug/shapes/navigation/edge_connection_color" type="Color" setter="" getter="" default="Color(1, 0, 1, 1)"> Color to display edge connections between navigation regions, visible when "Visible Navigation" is enabled in the Debug menu. </member> + <member name="debug/shapes/navigation/enable_agent_paths" type="bool" setter="" getter="" default="true"> + If enabled, displays navigation agent paths when an agent has debug enabled. + </member> + <member name="debug/shapes/navigation/enable_agent_paths_xray" type="bool" setter="" getter="" default="true"> + If enabled, displays navigation agent paths through geometry when an agent has debug enabled. + </member> <member name="debug/shapes/navigation/enable_edge_connections" type="bool" setter="" getter="" default="true"> If enabled, displays edge connections between navigation regions when "Visible Navigation" is enabled in the Debug menu. </member> @@ -634,7 +667,7 @@ Main window initial position. [code]0[/code] - "Absolute", [member display/window/size/initial_position] is used to set window position. [code]1[/code] - "Primary Screen Center". - [code]2[/code] - "Other Screen Center", [member display/window/size/initial_screen] is used to set window position. + [code]2[/code] - "Other Screen Center", [member display/window/size/initial_screen] is used to set the screen. </member> <member name="display/window/size/initial_screen" type="int" setter="" getter="" default="0"> Main window initial screen, this settings is used only if [member display/window/size/initial_position_type] is set to "Other Screen Center" ([code]2[/code]). @@ -671,7 +704,8 @@ <member name="display/window/vsync/vsync_mode" type="int" setter="" getter="" default="1"> Sets the V-Sync mode for the main game window. See [enum DisplayServer.VSyncMode] for possible values and how they affect the behavior of your application. - Depending on the platform and used renderer, the engine will fall back to [code]Enabled[/code] if the desired mode is not supported. + Depending on the platform and used renderer, the engine will fall back to [b]Enabled[/b] if the desired mode is not supported. + [b]Note:[/b] V-Sync modes other than [b]Enabled[/b] are only supported in the Forward+ and Mobile rendering methods, not Compatibility. [b]Note:[/b] This property is only read when the project starts. To change the V-Sync mode at runtime, call [method DisplayServer.window_set_vsync_mode] instead. </member> <member name="dotnet/project/assembly_name" type="String" setter="" getter="" default=""""> @@ -770,7 +804,7 @@ Path to a custom [Font] resource to use as default for all GUI elements of the project. </member> <member name="gui/theme/default_font_antialiasing" type="int" setter="" getter="" default="1"> - Font anti-aliasing mode. See [member FontFile.antialiasing], + Font anti-aliasing mode. See [member FontFile.antialiasing]. </member> <member name="gui/theme/default_font_generate_mipmaps" type="bool" setter="" getter="" default="false"> If set to [code]true[/code], the default font will have mipmaps generated. This prevents text from looking grainy when a [Control] is scaled down, or when a [Label3D] is viewed from a long distance (if [member Label3D.texture_filter] is set to a mode that displays mipmaps). @@ -924,16 +958,16 @@ macOS specific override for the shortcut to delete a word. </member> <member name="input/ui_text_caret_add_above" type="Dictionary" setter="" getter=""> - Default [InputEventAction] to add an additional caret above every caret of a text + Default [InputEventAction] to add an additional caret above every caret of a text. </member> <member name="input/ui_text_caret_add_above.macos" type="Dictionary" setter="" getter=""> - macOS specific override for the shortcut to add a caret above every caret + macOS specific override for the shortcut to add a caret above every caret. </member> <member name="input/ui_text_caret_add_below" type="Dictionary" setter="" getter=""> - Default [InputEventAction] to add an additional caret below every caret of a text + Default [InputEventAction] to add an additional caret below every caret of a text. </member> <member name="input/ui_text_caret_add_below.macos" type="Dictionary" setter="" getter=""> - macOS specific override for the shortcut to add a caret below every caret + macOS specific override for the shortcut to add a caret below every caret. </member> <member name="input/ui_text_caret_document_end" type="Dictionary" setter="" getter=""> Default [InputEventAction] to move the text cursor the the end of the text. @@ -1078,6 +1112,9 @@ If no selection is currently active, selects the word currently under the caret in text fields. If a selection is currently active, deselects the current selection. [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_text_select_word_under_caret.macos" type="Dictionary" setter="" getter=""> + macOS specific override for the shortcut to select the word currently under the caret. + </member> <member name="input/ui_text_submit" type="Dictionary" setter="" getter=""> Default [InputEventAction] to submit a text field. [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. @@ -1113,9 +1150,6 @@ <member name="input_devices/pointing/emulate_touch_from_mouse" type="bool" setter="" getter="" default="false"> If [code]true[/code], sends touch input events when clicking or dragging the mouse. </member> - <member name="input_devices/pointing/ios/touch_delay" type="float" setter="" getter="" default="0.15"> - Default delay for touch events. This only affects iOS devices. - </member> <member name="internationalization/locale/fallback" type="String" setter="" getter="" default=""en""> The locale to fall back to if a translation isn't available in a given language. If left empty, [code]en[/code] (English) will be used. </member> @@ -1630,7 +1664,7 @@ Optional name for the 3D render layer 13. If left empty, the layer will display as "Layer 13". </member> <member name="layer_names/3d_render/layer_14" type="String" setter="" getter="" default=""""> - Optional name for the 3D render layer 14. If left empty, the layer will display as "Layer 14" + Optional name for the 3D render layer 14. If left empty, the layer will display as "Layer 14". </member> <member name="layer_names/3d_render/layer_15" type="String" setter="" getter="" default=""""> Optional name for the 3D render layer 15. If left empty, the layer will display as "Layer 15". @@ -1743,7 +1777,7 @@ [/gdscript] [csharp] // Set the default gravity strength to 980. - PhysicsServer2D.AreaSetParam(GetViewport().FindWorld2d().Space, PhysicsServer2D.AreaParameter.Gravity, 980); + PhysicsServer2D.AreaSetParam(GetViewport().FindWorld2D().Space, PhysicsServer2D.AreaParameter.Gravity, 980); [/csharp] [/codeblocks] </member> @@ -1757,7 +1791,7 @@ [/gdscript] [csharp] // Set the default gravity direction to `Vector2(0, 1)`. - PhysicsServer2D.AreaSetParam(GetViewport().FindWorld2d().Space, PhysicsServer2D.AreaParameter.GravityVector, Vector2.Down) + PhysicsServer2D.AreaSetParam(GetViewport().FindWorld2D().Space, PhysicsServer2D.AreaParameter.GravityVector, Vector2.Down) [/csharp] [/codeblocks] </member> @@ -1898,13 +1932,16 @@ </member> <member name="rendering/anti_aliasing/quality/msaa_2d" type="int" setter="" getter="" default="0"> Sets the number of MSAA samples to use for 2D/Canvas rendering (as a power of two). MSAA is used to reduce aliasing around the edges of polygons. A higher MSAA value results in smoother edges but can be significantly slower on some hardware. This has no effect on shader-induced aliasing or texture aliasing. + [b]Note:[/b] MSAA is only supported in the Forward+ and Mobile rendering methods, not Compatibility. </member> <member name="rendering/anti_aliasing/quality/msaa_3d" type="int" setter="" getter="" default="0"> Sets the number of MSAA samples to use for 3D rendering (as a power of two). MSAA is used to reduce aliasing around the edges of polygons. A higher MSAA value results in smoother edges but can be significantly slower on some hardware. See also bilinear scaling 3d [member rendering/scaling_3d/mode] for supersampling, which provides higher quality but is much more expensive. This has no effect on shader-induced aliasing or texture aliasing. + [b]Note:[/b] MSAA is only supported in the Forward+ and Mobile rendering methods, not Compatibility. </member> <member name="rendering/anti_aliasing/quality/screen_space_aa" type="int" setter="" getter="" default="0"> Sets the screen-space antialiasing mode for the default screen [Viewport]. Screen-space antialiasing works by selectively blurring edges in a post-process shader. It differs from MSAA which takes multiple coverage samples while rendering objects. Screen-space AA methods are typically faster than MSAA and will smooth out specular aliasing, but tend to make scenes appear blurry. The blurriness is partially counteracted by automatically using a negative mipmap LOD bias (see [member rendering/textures/default_filters/texture_mipmap_bias]). Another way to combat specular aliasing is to enable [member rendering/anti_aliasing/screen_space_roughness_limiter/enabled]. + [b]Note:[/b] Screen-space antialiasing is only supported in the Forward+ and Mobile rendering methods, not Compatibility. </member> <member name="rendering/anti_aliasing/quality/use_debanding" type="bool" setter="" getter="" default="false"> If [code]true[/code], uses a fast post-processing filter to make banding significantly less visible in 3D. 2D rendering is [i]not[/i] affected by debanding unless the [member Environment.background_mode] is [constant Environment.BG_CANVAS]. @@ -1913,11 +1950,14 @@ </member> <member name="rendering/anti_aliasing/quality/use_taa" type="bool" setter="" getter="" default="false"> Enables Temporal Anti-Aliasing for the default screen [Viewport]. TAA works by jittering the camera and accumulating the images of the last rendered frames, motion vector rendering is used to account for camera and object motion. Enabling TAA can make the image blurrier, which is partially counteracted by automatically using a negative mipmap LOD bias (see [member rendering/textures/default_filters/texture_mipmap_bias]). - [b]Note:[/b] The implementation is not complete yet, some visual instances such as particles and skinned meshes may show artifacts. + [b]Note:[/b] The implementation is not complete yet. Some visual instances such as particles and skinned meshes may show ghosting artifacts in motion. + [b]Note:[/b] TAA is only supported in the Forward+ rendering method, not Mobile or Compatibility. </member> <member name="rendering/anti_aliasing/screen_space_roughness_limiter/amount" type="float" setter="" getter="" default="0.25"> </member> <member name="rendering/anti_aliasing/screen_space_roughness_limiter/enabled" type="bool" setter="" getter="" default="true"> + If [code]true[/code], enables a spatial filter to limit roughness in areas with high-frequency detail. This can help reduce specular aliasing to an extent, though not as much as enabling [member rendering/anti_aliasing/quality/use_taa]. This filter has a small performance cost, so consider disabling it if it doesn't benefit your scene noticeably. + [b]Note:[/b] TAA is only supported in the Forward+ and Mobile rendering methods, not Compatibility. </member> <member name="rendering/anti_aliasing/screen_space_roughness_limiter/limit" type="float" setter="" getter="" default="0.18"> </member> @@ -1935,7 +1975,7 @@ </member> <member name="rendering/driver/depth_prepass/enable" type="bool" setter="" getter="" default="true"> If [code]true[/code], performs a previous depth pass before rendering 3D materials. This increases performance significantly in scenes with high overdraw, when complex materials and lighting are used. However, in scenes with few occluded surfaces, the depth prepass may reduce performance. If your game is viewed from a fixed angle that makes it easy to avoid overdraw (such as top-down or side-scrolling perspective), consider disabling the depth prepass to improve performance. This setting can be changed at run-time to optimize performance depending on the scene currently being viewed. - [b]Note:[/b] Only supported when using the Vulkan Clustered backend or the OpenGL backend. When using Vulkan Mobile there is no depth prepass performed. + [b]Note:[/b] Depth prepass is only supported when using the Forward+ or Compatibility rendering method. When using the Mobile rendering method, there is no depth prepass performed. </member> <member name="rendering/driver/threads/thread_model" type="int" setter="" getter="" default="1"> Thread model for rendering. Rendering on a thread can vastly improve performance, but synchronizing to the main thread can cause a bit more jitter. @@ -2141,12 +2181,15 @@ </member> <member name="rendering/limits/opengl/max_lights_per_object" type="int" setter="" getter="" default="8"> Max number of omnilights and spotlights renderable per object. At the default value of 8, this means that each surface can be affected by up to 8 omnilights and 8 spotlights. This is further limited by hardware support and [member rendering/limits/opengl/max_renderable_lights]. Setting this low will slightly reduce memory usage, may decrease shader compile times, and may result in faster rendering on low-end, mobile, or web devices. + [b]Note:[/b] This setting is only effective when using the Compatibility rendering method, not Forward+ and Mobile. </member> <member name="rendering/limits/opengl/max_renderable_elements" type="int" setter="" getter="" default="65536"> Max number of elements renderable in a frame. If more elements than this are visible per frame, they will not be drawn. Keep in mind elements refer to mesh surfaces and not meshes themselves. Setting this low will slightly reduce memory usage and may decrease shader compile times, particularly on web. For most uses, the default value is suitable, but consider lowering as much as possible on web export. + [b]Note:[/b] This setting is only effective when using the Compatibility rendering method, not Forward+ and Mobile. </member> <member name="rendering/limits/opengl/max_renderable_lights" type="int" setter="" getter="" default="32"> Max number of positional lights renderable in a frame. If more lights than this number are used, they will be ignored. Setting this low will slightly reduce memory usage and may decrease shader compile times, particularly on web. For most uses, the default value is suitable, but consider lowering as much as possible on web export. + [b]Note:[/b] This setting is only effective when using the Compatibility rendering method, not Forward+ and Mobile. </member> <member name="rendering/limits/spatial_indexer/threaded_cull_minimum_instances" type="int" setter="" getter="" default="1000"> </member> @@ -2238,7 +2281,8 @@ Determines how sharp the upscaled image will be when using the FSR upscaling mode. Sharpness halves with every whole number. Values go from 0.0 (sharpest) to 2.0. Values above 2.0 won't make a visible difference. </member> <member name="rendering/scaling_3d/mode" type="int" setter="" getter="" default="0"> - Sets the scaling 3D mode. Bilinear scaling renders at different resolution to either undersample or supersample the viewport. FidelityFX Super Resolution 1.0, abbreviated to FSR, is an upscaling technology that produces high quality images at fast framerates by using a spatially aware upscaling algorithm. FSR is slightly more expensive than bilinear, but it produces significantly higher image quality. FSR should be used where possible. + Sets the scaling 3D mode. Bilinear scaling renders at different resolution to either undersample or supersample the viewport. FidelityFX Super Resolution 1.0, abbreviated to FSR, is an upscaling technology that produces high quality images at fast framerates by using a spatially-aware upscaling algorithm. FSR is slightly more expensive than bilinear, but it produces significantly higher image quality. On particularly low-end GPUs, the added cost of FSR may not be worth it (compared to using bilinear scaling with a slightly higher resolution scale to match performance). + [b]Note:[/b] FSR is only effective when using the Forward+ rendering method, not Mobile or Compatibility. If using an incompatible rendering method, FSR will fall back to bilinear scaling. </member> <member name="rendering/scaling_3d/scale" type="float" setter="" getter="" default="1.0"> Scales the 3D render buffer based on the viewport size uses an image filter specified in [member rendering/scaling_3d/mode] to scale the output image to the full viewport size. Values lower than [code]1.0[/code] can be used to speed up 3D rendering at the cost of quality (undersampling). Values greater than [code]1.0[/code] are only valid for bilinear mode and can be used to improve 3D rendering quality at a high performance cost (supersampling). See also [member rendering/anti_aliasing/quality/msaa_3d] for multi-sample antialiasing, which is significantly cheaper but only smooths the edges of polygons. @@ -2262,9 +2306,11 @@ </member> <member name="rendering/shading/overrides/force_vertex_shading" type="bool" setter="" getter="" default="false"> If [code]true[/code], forces vertex shading for all rendering. This can increase performance a lot, but also reduces quality immensely. Can be used to optimize performance on low-end mobile devices. + [b]Note:[/b] This setting currently has no effect, as vertex shading is not implemented yet. </member> <member name="rendering/shading/overrides/force_vertex_shading.mobile" type="bool" setter="" getter="" default="true"> Lower-end override for [member rendering/shading/overrides/force_vertex_shading] on mobile devices, due to performance concerns or driver support. + [b]Note:[/b] This setting currently has no effect, as vertex shading is not implemented yet. </member> <member name="rendering/textures/decals/filter" type="int" setter="" getter="" default="3"> The filtering quality to use for [Decal] nodes. When using one of the anisotropic filtering modes, the anisotropic filtering level is controlled by [member rendering/textures/default_filters/anisotropic_filtering_level]. @@ -2291,11 +2337,11 @@ <member name="rendering/textures/lossless_compression/force_png" type="bool" setter="" getter="" default="false"> If [code]true[/code], the texture importer will import lossless textures using the PNG format. Otherwise, it will default to using WebP. </member> - <member name="rendering/textures/vram_compression/import_etc2_astc" type="bool" setter="" getter="" default="false"> + <member name="rendering/textures/vram_compression/import_etc2_astc" type="bool" setter="" getter=""> If [code]true[/code], the texture importer will import VRAM-compressed textures using the Ericsson Texture Compression 2 algorithm for lower quality textures and normalmaps and Adaptable Scalable Texture Compression algorithm for high quality textures (in 4x4 block size). [b]Note:[/b] Changing this setting does [i]not[/i] impact textures that were already imported before. To make this setting apply to textures that were already imported, exit the editor, remove the [code].godot/imported/[/code] folder located inside the project folder then restart the editor (see [member application/config/use_hidden_project_data_directory]). </member> - <member name="rendering/textures/vram_compression/import_s3tc_bptc" type="bool" setter="" getter="" default="true"> + <member name="rendering/textures/vram_compression/import_s3tc_bptc" type="bool" setter="" getter=""> If [code]true[/code], the texture importer will import VRAM-compressed textures using the S3 Texture Compression algorithm (DXT1-5) for lower quality textures and the the BPTC algorithm (BC6H and BC7) for high quality textures. This algorithm is only supported on PC desktop platforms and consoles. [b]Note:[/b] Changing this setting does [i]not[/i] impact textures that were already imported before. To make this setting apply to textures that were already imported, exit the editor, remove the [code].godot/imported/[/code] folder located inside the project folder then restart the editor (see [member application/config/use_hidden_project_data_directory]). </member> diff --git a/doc/classes/ReflectionProbe.xml b/doc/classes/ReflectionProbe.xml index fee48dd246..cc48e0612b 100644 --- a/doc/classes/ReflectionProbe.xml +++ b/doc/classes/ReflectionProbe.xml @@ -7,19 +7,21 @@ Captures its surroundings as a cubemap, and stores versions of it with increasing levels of blur to simulate different material roughnesses. The [ReflectionProbe] is used to create high-quality reflections at a low performance cost (when [member update_mode] is [constant UPDATE_ONCE]). [ReflectionProbe]s can be blended together and with the rest of the scene smoothly. [ReflectionProbe]s can also be combined with [VoxelGI], SDFGI ([member Environment.sdfgi_enabled]) and screen-space reflections ([member Environment.ssr_enabled]) to get more accurate reflections in specific areas. [ReflectionProbe]s render all objects within their [member cull_mask], so updating them can be quite expensive. It is best to update them once with the important static objects and then leave them as-is. [b]Note:[/b] Unlike [VoxelGI] and SDFGI, [ReflectionProbe]s only source their environment from a [WorldEnvironment] node. If you specify an [Environment] resource within a [Camera3D] node, it will be ignored by the [ReflectionProbe]. This can lead to incorrect lighting within the [ReflectionProbe]. + [b]Note:[/b] Reflection probes are only supported in the Forward+ and Mobile rendering methods, not Compatibility. When using the Mobile rendering method, only 8 reflection probes can be displayed on each mesh resource. Attempting to display more than 8 reflection probes on a single mesh resource will result in reflection probes flickering in and out as the camera moves. + [b]Note:[/b] When using the Mobile rendering method, reflection probes will only correctly affect meshes whose visibility AABB intersects with the reflection probe's AABB. If using a shader to deform the mesh in a way that makes it go outside its AABB, [member GeometryInstance3D.extra_cull_margin] must be increased on the mesh. Otherwise, the reflection probe may not be visible on the mesh. </description> <tutorials> <link title="Reflection probes">$DOCS_URL/tutorials/3d/reflection_probes.html</link> </tutorials> <members> <member name="ambient_color" type="Color" setter="set_ambient_color" getter="get_ambient_color" default="Color(0, 0, 0, 1)"> - The custom ambient color to use within the [ReflectionProbe]'s [member extents]. Only effective if [member ambient_mode] is [constant AMBIENT_COLOR]. + The custom ambient color to use within the [ReflectionProbe]'s [member size]. Only effective if [member ambient_mode] is [constant AMBIENT_COLOR]. </member> <member name="ambient_color_energy" type="float" setter="set_ambient_color_energy" getter="get_ambient_color_energy" default="1.0"> - The custom ambient color energy to use within the [ReflectionProbe]'s [member extents]. Only effective if [member ambient_mode] is [constant AMBIENT_COLOR]. + The custom ambient color energy to use within the [ReflectionProbe]'s [member size]. Only effective if [member ambient_mode] is [constant AMBIENT_COLOR]. </member> <member name="ambient_mode" type="int" setter="set_ambient_mode" getter="get_ambient_mode" enum="ReflectionProbe.AmbientMode" default="1"> - The ambient color to use within the [ReflectionProbe]'s [member extents]. The ambient color will smoothly blend with other [ReflectionProbe]s and the rest of the scene (outside the [ReflectionProbe]'s [member extents]). + The ambient color to use within the [ReflectionProbe]'s [member size]. The ambient color will smoothly blend with other [ReflectionProbe]s and the rest of the scene (outside the [ReflectionProbe]'s [member size]). </member> <member name="box_projection" type="bool" setter="set_enable_box_projection" getter="is_box_projection_enabled" default="false"> If [code]true[/code], enables box projection. This makes reflections look more correct in rectangle-shaped rooms by offsetting the reflection center depending on the camera's location. @@ -31,10 +33,6 @@ <member name="enable_shadows" type="bool" setter="set_enable_shadows" getter="are_shadows_enabled" default="false"> If [code]true[/code], computes shadows in the reflection probe. This makes the reflection probe slower to render; you may want to disable this if using the [constant UPDATE_ALWAYS] [member update_mode]. </member> - <member name="extents" type="Vector3" setter="set_extents" getter="get_extents" default="Vector3(10, 10, 10)"> - The size of the reflection probe. The larger the extents, the more space covered by the probe, which will lower the perceived resolution. It is best to keep the extents only as large as you need them. - [b]Note:[/b] To better fit areas that are not aligned to the grid, you can rotate the [ReflectionProbe] node. - </member> <member name="intensity" type="float" setter="set_intensity" getter="get_intensity" default="1.0"> Defines the reflection intensity. Intensity modulates the strength of the reflection. </member> @@ -43,7 +41,7 @@ </member> <member name="max_distance" type="float" setter="set_max_distance" getter="get_max_distance" default="0.0"> The maximum distance away from the [ReflectionProbe] an object can be before it is culled. Decrease this to improve performance, especially when using the [constant UPDATE_ALWAYS] [member update_mode]. - [b]Note:[/b] The maximum reflection distance is always at least equal to the [member extents]. This means that decreasing [member max_distance] will not always cull objects from reflections, especially if the reflection probe's [member extents] are already large. + [b]Note:[/b] The maximum reflection distance is always at least equal to the probe's extents. This means that decreasing [member max_distance] will not always cull objects from reflections, especially if the reflection probe's [member size] is already large. </member> <member name="mesh_lod_threshold" type="float" setter="set_mesh_lod_threshold" getter="get_mesh_lod_threshold" default="1.0"> The automatic LOD bias to use for meshes rendered within the [ReflectionProbe] (this is analog to [member Viewport.mesh_lod_threshold]). Higher values will use less detailed versions of meshes that have LOD variations generated. If set to [code]0.0[/code], automatic LOD is disabled. Increase [member mesh_lod_threshold] to improve performance at the cost of geometry detail, especially when using the [constant UPDATE_ALWAYS] [member update_mode]. @@ -52,6 +50,10 @@ <member name="origin_offset" type="Vector3" setter="set_origin_offset" getter="get_origin_offset" default="Vector3(0, 0, 0)"> Sets the origin offset to be used when this [ReflectionProbe] is in [member box_projection] mode. This can be set to a non-zero value to ensure a reflection fits a rectangle-shaped room, while reducing the number of objects that "get in the way" of the reflection. </member> + <member name="size" type="Vector3" setter="set_size" getter="get_size" default="Vector3(20, 20, 20)"> + The size of the reflection probe. The larger the size, the more space covered by the probe, which will lower the perceived resolution. It is best to keep the size only as large as you need it. + [b]Note:[/b] To better fit areas that are not aligned to the grid, you can rotate the [ReflectionProbe] node. + </member> <member name="update_mode" type="int" setter="set_update_mode" getter="get_update_mode" enum="ReflectionProbe.UpdateMode" default="0"> Sets how frequently the [ReflectionProbe] is updated. Can be [constant UPDATE_ONCE] or [constant UPDATE_ALWAYS]. </member> @@ -64,13 +66,13 @@ Update the probe every frame. This provides better results for fast-moving dynamic objects (such as cars). However, it has a significant performance cost. Due to the cost, it's recommended to only use one ReflectionProbe with [constant UPDATE_ALWAYS] at most per scene. For all other use cases, use [constant UPDATE_ONCE]. </constant> <constant name="AMBIENT_DISABLED" value="0" enum="AmbientMode"> - Do not apply any ambient lighting inside the [ReflectionProbe]'s [member extents]. + Do not apply any ambient lighting inside the [ReflectionProbe]'s [member size]. </constant> <constant name="AMBIENT_ENVIRONMENT" value="1" enum="AmbientMode"> - Apply automatically-sourced environment lighting inside the [ReflectionProbe]'s [member extents]. + Apply automatically-sourced environment lighting inside the [ReflectionProbe]'s [member size]. </constant> <constant name="AMBIENT_COLOR" value="2" enum="AmbientMode"> - Apply custom ambient lighting inside the [ReflectionProbe]'s [member extents]. See [member ambient_color] and [member ambient_color_energy]. + Apply custom ambient lighting inside the [ReflectionProbe]'s [member size]. See [member ambient_color] and [member ambient_color_energy]. </constant> </constants> </class> diff --git a/doc/classes/RenderingDevice.xml b/doc/classes/RenderingDevice.xml index f318430611..64be8e6807 100644 --- a/doc/classes/RenderingDevice.xml +++ b/doc/classes/RenderingDevice.xml @@ -1,8 +1,14 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="RenderingDevice" inherits="Object" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> + Abstraction for working with modern low-level graphics APIs. </brief_description> <description> + [RenderingDevice] is an abstraction for working with modern low-level graphics APIs such as Vulkan. + On startup, Godot creates a global [RenderingDevice] which can be retrieved using [method RenderingServer.get_rendering_device]. This global RenderingDevice performs drawing to the screen. + Internally, [RenderingDevice] is used in Godot to provide support for several modern low-level graphics APIs while reducing the amount of code duplication required. + [b]Local RenderingDevices:[/b] Using [method RenderingServer.create_local_rendering_device], you can create "secondary" rendering devices to perform drawing and GPU compute operations on separate threads. + [b]Note:[/b] [RenderingDevice] is not available when running in headless mode or when using the Compatibility rendering method. </description> <tutorials> </tutorials> @@ -26,7 +32,10 @@ <method name="buffer_get_data"> <return type="PackedByteArray" /> <param index="0" name="buffer" type="RID" /> + <param index="1" name="offset_bytes" type="int" default="0" /> + <param index="2" name="size_bytes" type="int" default="0" /> <description> + Returns a copy of the data of the specified [param buffer], optionally [param offset_bytes] and [param size_bytes] can be set to copy only a portion of the buffer. </description> </method> <method name="buffer_update"> @@ -1162,20 +1171,28 @@ <constant name="BARRIER_MASK_NO_BARRIER" value="8" enum="BarrierMask" is_bitfield="true"> </constant> <constant name="TEXTURE_TYPE_1D" value="0" enum="TextureType"> + 1-dimensional texture. </constant> <constant name="TEXTURE_TYPE_2D" value="1" enum="TextureType"> + 2-dimensional texture. </constant> <constant name="TEXTURE_TYPE_3D" value="2" enum="TextureType"> + 3-dimensional texture. </constant> <constant name="TEXTURE_TYPE_CUBE" value="3" enum="TextureType"> + [Cubemap] texture. </constant> <constant name="TEXTURE_TYPE_1D_ARRAY" value="4" enum="TextureType"> + Array of 1-dimensional textures. </constant> <constant name="TEXTURE_TYPE_2D_ARRAY" value="5" enum="TextureType"> + Array of 2-dimensional textures. </constant> <constant name="TEXTURE_TYPE_CUBE_ARRAY" value="6" enum="TextureType"> + Array of [Cubemap] textures. </constant> <constant name="TEXTURE_TYPE_MAX" value="7" enum="TextureType"> + Represents the size of the [enum TextureType] enum. </constant> <constant name="TEXTURE_SAMPLES_1" value="0" enum="TextureSamples"> </constant> @@ -1192,6 +1209,7 @@ <constant name="TEXTURE_SAMPLES_64" value="6" enum="TextureSamples"> </constant> <constant name="TEXTURE_SAMPLES_MAX" value="7" enum="TextureSamples"> + Represents the size of the [enum TextureSamples] enum. </constant> <constant name="TEXTURE_USAGE_SAMPLING_BIT" value="1" enum="TextureUsageBits" is_bitfield="true"> </constant> @@ -1236,8 +1254,10 @@ <constant name="TEXTURE_SLICE_3D" value="2" enum="TextureSliceType"> </constant> <constant name="SAMPLER_FILTER_NEAREST" value="0" enum="SamplerFilter"> + Nearest-neighbor sampler filtering. Sampling at higher resolutions than the source will result in a pixelated look. </constant> <constant name="SAMPLER_FILTER_LINEAR" value="1" enum="SamplerFilter"> + Bilinear sampler filtering. Sampling at higher resolutions than the source will result in a blurry look. </constant> <constant name="SAMPLER_REPEAT_MODE_REPEAT" value="0" enum="SamplerRepeatMode"> </constant> @@ -1298,8 +1318,10 @@ <constant name="UNIFORM_TYPE_MAX" value="10" enum="UniformType"> </constant> <constant name="RENDER_PRIMITIVE_POINTS" value="0" enum="RenderPrimitive"> + Point rendering primitive (with constant size, regardless of distance from camera). </constant> <constant name="RENDER_PRIMITIVE_LINES" value="1" enum="RenderPrimitive"> + Line rendering primitive. </constant> <constant name="RENDER_PRIMITIVE_LINES_WITH_ADJACENCY" value="2" enum="RenderPrimitive"> </constant> @@ -1380,6 +1402,7 @@ <constant name="LOGIC_OP_NO_OP" value="5" enum="LogicOperation"> </constant> <constant name="LOGIC_OP_XOR" value="6" enum="LogicOperation"> + Exclusive or (XOR) logic operation. </constant> <constant name="LOGIC_OP_OR" value="7" enum="LogicOperation"> </constant> @@ -1442,16 +1465,22 @@ <constant name="BLEND_FACTOR_MAX" value="19" enum="BlendFactor"> </constant> <constant name="BLEND_OP_ADD" value="0" enum="BlendOperation"> + Additive blending operation ([code]source + destination[/code]). </constant> <constant name="BLEND_OP_SUBTRACT" value="1" enum="BlendOperation"> + Subtractive blending operation ([code]source - destination[/code]). </constant> <constant name="BLEND_OP_REVERSE_SUBTRACT" value="2" enum="BlendOperation"> + Reverse subtractive blending operation ([code]destination - source[/code]). </constant> <constant name="BLEND_OP_MINIMUM" value="3" enum="BlendOperation"> + Minimum blending operation (keep the lowest value of the two). </constant> <constant name="BLEND_OP_MAXIMUM" value="4" enum="BlendOperation"> + Maximum blending operation (keep the highest value of the two). </constant> <constant name="BLEND_OP_MAX" value="5" enum="BlendOperation"> + Represents the size of the [enum BlendOperation] enum. </constant> <constant name="DYNAMIC_STATE_LINE_WIDTH" value="1" enum="PipelineDynamicStateFlags" is_bitfield="true"> </constant> @@ -1544,12 +1573,16 @@ <constant name="LIMIT_MAX_TEXTURE_ARRAY_LAYERS" value="10" enum="Limit"> </constant> <constant name="LIMIT_MAX_TEXTURE_SIZE_1D" value="11" enum="Limit"> + Maximum supported 1-dimensional texture size (in pixels on a single axis). </constant> <constant name="LIMIT_MAX_TEXTURE_SIZE_2D" value="12" enum="Limit"> + Maximum supported 2-dimensional texture size (in pixels on a single axis). </constant> <constant name="LIMIT_MAX_TEXTURE_SIZE_3D" value="13" enum="Limit"> + Maximum supported 3-dimensional texture size (in pixels on a single axis). </constant> <constant name="LIMIT_MAX_TEXTURE_SIZE_CUBE" value="14" enum="Limit"> + Maximum supported cubemap texture size (in pixels on a single axis of a single face). </constant> <constant name="LIMIT_MAX_TEXTURES_PER_SHADER_STAGE" value="15" enum="Limit"> </constant> @@ -1596,14 +1629,19 @@ <constant name="LIMIT_MAX_VIEWPORT_DIMENSIONS_Y" value="36" enum="Limit"> </constant> <constant name="MEMORY_TEXTURES" value="0" enum="MemoryType"> + Memory taken by textures. </constant> <constant name="MEMORY_BUFFERS" value="1" enum="MemoryType"> + Memory taken by buffers. </constant> <constant name="MEMORY_TOTAL" value="2" enum="MemoryType"> + Total memory taken. This is greater than the sum of [constant MEMORY_TEXTURES] and [constant MEMORY_BUFFERS], as it also includes miscellaneous memory usage. </constant> <constant name="INVALID_ID" value="-1"> + Returned by functions that return an ID if a value is invalid. </constant> <constant name="INVALID_FORMAT_ID" value="-1"> + Returned by functions that return a format ID if a value is invalid. </constant> </constants> </class> diff --git a/doc/classes/RenderingServer.xml b/doc/classes/RenderingServer.xml index 8bb3073000..e5ab3271dc 100644 --- a/doc/classes/RenderingServer.xml +++ b/doc/classes/RenderingServer.xml @@ -4,10 +4,10 @@ Server for anything visible. </brief_description> <description> - Server for anything visible. The rendering server is the API backend for everything visible. The whole scene system mounts on it to display. + The rendering server is the API backend for everything visible. The whole scene system mounts on it to display. The rendering server is completely opaque, the internals are entirely implementation specific and cannot be accessed. - The rendering server can be used to bypass the scene system entirely. - Resources are created using the [code]*_create[/code] functions. + The rendering server can be used to bypass the scene/[Node] system entirely. + Resources are created using the [code]*_create[/code] functions. These functions return [RID]s which are not references to the objects themselves, but opaque [i]pointers[/i] towards these objects. All objects are drawn to a viewport. You can use the [Viewport] attached to the [SceneTree] or you can create one yourself with [method viewport_create]. When using a custom scenario or canvas, the scenario or canvas needs to be attached to the viewport using [method viewport_set_scenario] or [method viewport_attach_canvas]. In 3D, all visual objects must be associated with a scenario. The scenario is a visual representation of the world. If accessing the rendering server from a running game, the scenario can be accessed from the scene tree from any [Node3D] node with [method Node3D.get_world_3d]. Otherwise, a scenario can be created with [method scenario_create]. Similarly, in 2D, a canvas is needed to draw all canvas items. @@ -25,6 +25,7 @@ <param index="1" name="material_overrides" type="RID[]" /> <param index="2" name="image_size" type="Vector2i" /> <description> + Bakes the material data of the Mesh passed in the [param base] parameter with optional [param material_overrides] to a set of [Image]s of size [param image_size]. Returns an array of [Image]s containing material properties as specified in [enum BakeChannels]. </description> </method> <method name="camera_attributes_create"> @@ -43,6 +44,7 @@ <param index="4" name="speed" type="float" /> <param index="5" name="scale" type="float" /> <description> + Sets the parameters to use with the auto-exposure effect. These parameters take on the same meaning as their counterparts in [CameraAttributes] and [CameraAttributesPractical]. </description> </method> <method name="camera_attributes_set_dof_blur"> @@ -56,12 +58,14 @@ <param index="6" name="near_transition" type="float" /> <param index="7" name="amount" type="float" /> <description> + Sets the parameters to use with the DOF blur effect. These parameters take on the same meaning as their counterparts in [CameraAttributesPractical]. </description> </method> <method name="camera_attributes_set_dof_blur_bokeh_shape"> <return type="void" /> <param index="0" name="shape" type="int" enum="RenderingServer.DOFBokehShape" /> <description> + Sets the shape of the DOF bokeh pattern. Different shapes may be used to achieve artistic effect, or to meet performance targets. For more detail on available options see [enum DOFBokehShape]. </description> </method> <method name="camera_attributes_set_dof_blur_quality"> @@ -69,6 +73,7 @@ <param index="0" name="quality" type="int" enum="RenderingServer.DOFBlurQuality" /> <param index="1" name="use_jitter" type="bool" /> <description> + Sets the quality level of the DOF blur effect to one of the options in [enum DOFBlurQuality]. [param use_jitter] can be used to jitter samples taken during the blur pass to hide artifacts at the cost of looking more fuzzy. </description> </method> <method name="camera_attributes_set_exposure"> @@ -102,6 +107,7 @@ <param index="0" name="camera" type="RID" /> <param index="1" name="effects" type="RID" /> <description> + Sets the camera_attributes created with [method camera_attributes_create] to the given camera. </description> </method> <method name="camera_set_cull_mask"> @@ -192,6 +198,7 @@ <param index="2" name="radius" type="float" /> <param index="3" name="color" type="Color" /> <description> + Draws a circle on the [CanvasItem] pointed to by the [param item] [RID]. See also [method CanvasItem.draw_circle]. </description> </method> <method name="canvas_item_add_clip_ignore"> @@ -199,6 +206,7 @@ <param index="0" name="item" type="RID" /> <param index="1" name="ignore" type="bool" /> <description> + If [param ignore] is [code]true[/code], ignore clipping on items drawn with this canvas item until this is called again with [param ignore] set to false. </description> </method> <method name="canvas_item_add_lcd_texture_rect_region"> @@ -209,6 +217,7 @@ <param index="3" name="src_rect" type="Rect2" /> <param index="4" name="modulate" type="Color" /> <description> + See also [method CanvasItem.draw_lcd_texture_rect_region]. </description> </method> <method name="canvas_item_add_line"> @@ -220,6 +229,7 @@ <param index="4" name="width" type="float" default="-1.0" /> <param index="5" name="antialiased" type="bool" default="false" /> <description> + Draws a line on the [CanvasItem] pointed to by the [param item] [RID]. See also [method CanvasItem.draw_line]. </description> </method> <method name="canvas_item_add_mesh"> @@ -230,6 +240,7 @@ <param index="3" name="modulate" type="Color" default="Color(1, 1, 1, 1)" /> <param index="4" name="texture" type="RID" /> <description> + Draws a mesh created with [method mesh_create] with given [param transform], [param modulate] color, and [param texture]. This is used internally by [MeshInstance2D]. </description> </method> <method name="canvas_item_add_msdf_texture_rect_region"> @@ -243,6 +254,7 @@ <param index="6" name="px_range" type="float" default="1.0" /> <param index="7" name="scale" type="float" default="1.0" /> <description> + See also [method CanvasItem.draw_msdf_texture_rect_region]. </description> </method> <method name="canvas_item_add_multimesh"> @@ -251,6 +263,7 @@ <param index="1" name="mesh" type="RID" /> <param index="2" name="texture" type="RID" /> <description> + Draws a 2D [MultiMesh] on the [CanvasItem] pointed to by the [param item] [RID]. See also [method CanvasItem.draw_multimesh]. </description> </method> <method name="canvas_item_add_nine_patch"> @@ -266,6 +279,7 @@ <param index="8" name="draw_center" type="bool" default="true" /> <param index="9" name="modulate" type="Color" default="Color(1, 1, 1, 1)" /> <description> + Draws a nine-patch rectangle on the [CanvasItem] pointed to by the [param item] [RID]. </description> </method> <method name="canvas_item_add_particles"> @@ -274,6 +288,7 @@ <param index="1" name="particles" type="RID" /> <param index="2" name="texture" type="RID" /> <description> + Draws particles on the [CanvasItem] pointed to by the [param item] [RID]. </description> </method> <method name="canvas_item_add_polygon"> @@ -284,6 +299,7 @@ <param index="3" name="uvs" type="PackedVector2Array" default="PackedVector2Array()" /> <param index="4" name="texture" type="RID" /> <description> + Draws a 2D polygon on the [CanvasItem] pointed to by the [param item] [RID]. See also [method CanvasItem.draw_polygon]. </description> </method> <method name="canvas_item_add_polyline"> @@ -294,6 +310,7 @@ <param index="3" name="width" type="float" default="-1.0" /> <param index="4" name="antialiased" type="bool" default="false" /> <description> + Draws a 2D polyline on the [CanvasItem] pointed to by the [param item] [RID]. See also [method CanvasItem.draw_polyline]. </description> </method> <method name="canvas_item_add_primitive"> @@ -304,6 +321,7 @@ <param index="3" name="uvs" type="PackedVector2Array" /> <param index="4" name="texture" type="RID" /> <description> + Draws a 2D primitive on the [CanvasItem] pointed to by the [param item] [RID]. See also [method CanvasItem.draw_primitive]. </description> </method> <method name="canvas_item_add_rect"> @@ -312,6 +330,7 @@ <param index="1" name="rect" type="Rect2" /> <param index="2" name="color" type="Color" /> <description> + Draws a rectangle on the [CanvasItem] pointed to by the [param item] [RID]. See also [method CanvasItem.draw_rect]. </description> </method> <method name="canvas_item_add_set_transform"> @@ -319,6 +338,7 @@ <param index="0" name="item" type="RID" /> <param index="1" name="transform" type="Transform2D" /> <description> + Sets a [Transform2D] that will be used to transform subsequent canvas item commands. </description> </method> <method name="canvas_item_add_texture_rect"> @@ -368,6 +388,7 @@ <method name="canvas_item_create"> <return type="RID" /> <description> + Creates a new [CanvasItem] instance and returns its [RID]. </description> </method> <method name="canvas_item_set_canvas_group_mode"> @@ -609,6 +630,14 @@ Sets a light occluder's [Transform2D]. </description> </method> + <method name="canvas_light_set_blend_mode"> + <return type="void" /> + <param index="0" name="light" type="RID" /> + <param index="1" name="mode" type="int" enum="RenderingServer.CanvasLightBlendMode" /> + <description> + Sets the blend mode for the given canvas light. See [enum CanvasLightBlendMode] for options. Equivalent to [member Light2D.blend_mode]. + </description> + </method> <method name="canvas_light_set_color"> <return type="void" /> <param index="0" name="light" type="RID" /> @@ -877,13 +906,6 @@ <description> </description> </method> - <method name="decal_set_extents"> - <return type="void" /> - <param index="0" name="decal" type="RID" /> - <param index="1" name="extents" type="Vector3" /> - <description> - </description> - </method> <method name="decal_set_fade"> <return type="void" /> <param index="0" name="decal" type="RID" /> @@ -906,6 +928,13 @@ <description> </description> </method> + <method name="decal_set_size"> + <return type="void" /> + <param index="0" name="decal" type="RID" /> + <param index="1" name="size" type="Vector3" /> + <description> + </description> + </method> <method name="decal_set_texture"> <return type="void" /> <param index="0" name="decal" type="RID" /> @@ -1218,14 +1247,6 @@ Creates a new fog volume and allocates an RID. </description> </method> - <method name="fog_volume_set_extents"> - <return type="void" /> - <param index="0" name="fog_volume" type="RID" /> - <param index="1" name="extents" type="Vector3" /> - <description> - Sets the size of the fog volume when shape is [constant RenderingServer.FOG_VOLUME_SHAPE_ELLIPSOID], [constant RenderingServer.FOG_VOLUME_SHAPE_CONE], [constant RenderingServer.FOG_VOLUME_SHAPE_CYLINDER] or [constant RenderingServer.FOG_VOLUME_SHAPE_BOX]. - </description> - </method> <method name="fog_volume_set_material"> <return type="void" /> <param index="0" name="fog_volume" type="RID" /> @@ -1242,6 +1263,14 @@ Sets the shape of the fog volume to either [constant RenderingServer.FOG_VOLUME_SHAPE_ELLIPSOID], [constant RenderingServer.FOG_VOLUME_SHAPE_CONE], [constant RenderingServer.FOG_VOLUME_SHAPE_CYLINDER], [constant RenderingServer.FOG_VOLUME_SHAPE_BOX] or [constant RenderingServer.FOG_VOLUME_SHAPE_WORLD]. </description> </method> + <method name="fog_volume_set_size"> + <return type="void" /> + <param index="0" name="fog_volume" type="RID" /> + <param index="1" name="size" type="Vector3" /> + <description> + Sets the size of the fog volume when shape is [constant RenderingServer.FOG_VOLUME_SHAPE_ELLIPSOID], [constant RenderingServer.FOG_VOLUME_SHAPE_CONE], [constant RenderingServer.FOG_VOLUME_SHAPE_CYLINDER] or [constant RenderingServer.FOG_VOLUME_SHAPE_BOX]. + </description> + </method> <method name="force_draw"> <return type="void" /> <param index="0" name="swap_buffers" type="bool" default="true" /> @@ -1792,6 +1821,7 @@ <method name="lightmap_create"> <return type="RID" /> <description> + Creates a new [LightmapGI] instance. </description> </method> <method name="lightmap_get_probe_capture_bsp_tree" qualifiers="const"> @@ -2655,14 +2685,6 @@ If [code]true[/code], computes shadows in the reflection probe. This makes the reflection much slower to compute. Equivalent to [member ReflectionProbe.enable_shadows]. </description> </method> - <method name="reflection_probe_set_extents"> - <return type="void" /> - <param index="0" name="probe" type="RID" /> - <param index="1" name="extents" type="Vector3" /> - <description> - Sets the size of the area that the reflection probe will capture. Equivalent to [member ReflectionProbe.extents]. - </description> - </method> <method name="reflection_probe_set_intensity"> <return type="void" /> <param index="0" name="probe" type="RID" /> @@ -2701,6 +2723,14 @@ <description> </description> </method> + <method name="reflection_probe_set_size"> + <return type="void" /> + <param index="0" name="probe" type="RID" /> + <param index="1" name="size" type="Vector3" /> + <description> + Sets the size of the area that the reflection probe will capture. Equivalent to [member ReflectionProbe.size]. + </description> + </method> <method name="reflection_probe_set_update_mode"> <return type="void" /> <param index="0" name="probe" type="RID" /> @@ -3250,7 +3280,7 @@ <param index="0" name="viewport" type="RID" /> <param index="1" name="mode" type="int" enum="RenderingServer.ViewportEnvironmentMode" /> <description> - Sets the viewport's environment mode which allows enabling or disabling rendering of 3D environment over 2D canvas. When disabled, 2D will not be affected by the environment. When enabled, 2D will be affected by the environment if the environment background mode is [constant ENV_BG_CANVAS]. The default behaviour is to inherit the setting from the viewport's parent. If the topmost parent is also set to [constant VIEWPORT_ENVIRONMENT_INHERIT], then the behavior will be the same as if it was set to [constant VIEWPORT_ENVIRONMENT_ENABLED]. + Sets the viewport's environment mode which allows enabling or disabling rendering of 3D environment over 2D canvas. When disabled, 2D will not be affected by the environment. When enabled, 2D will be affected by the environment if the environment background mode is [constant ENV_BG_CANVAS]. The default behavior is to inherit the setting from the viewport's parent. If the topmost parent is also set to [constant VIEWPORT_ENVIRONMENT_INHERIT], then the behavior will be the same as if it was set to [constant VIEWPORT_ENVIRONMENT_ENABLED]. </description> </method> <method name="viewport_set_fsr_sharpness"> @@ -4091,10 +4121,10 @@ [FogVolume] will be shaped like an ellipsoid (stretched sphere). </constant> <constant name="FOG_VOLUME_SHAPE_CONE" value="1" enum="FogVolumeShape"> - [FogVolume] will be shaped like a cone pointing upwards (in local coordinates). The cone's angle is set automatically to fill the extents. The cone will be adjusted to fit within the extents. Rotate the [FogVolume] node to reorient the cone. Non-uniform scaling via extents is not supported (scale the [FogVolume] node instead). + [FogVolume] will be shaped like a cone pointing upwards (in local coordinates). The cone's angle is set automatically to fill the size. The cone will be adjusted to fit within the size. Rotate the [FogVolume] node to reorient the cone. Non-uniform scaling via size is not supported (scale the [FogVolume] node instead). </constant> <constant name="FOG_VOLUME_SHAPE_CYLINDER" value="2" enum="FogVolumeShape"> - [FogVolume] will be shaped like an upright cylinder (in local coordinates). Rotate the [FogVolume] node to reorient the cylinder. The cylinder will be adjusted to fit within the extents. Non-uniform scaling via extents is not supported (scale the [FogVolume] node instead). + [FogVolume] will be shaped like an upright cylinder (in local coordinates). Rotate the [FogVolume] node to reorient the cylinder. The cylinder will be adjusted to fit within the size. Non-uniform scaling via size is not supported (scale the [FogVolume] node instead). </constant> <constant name="FOG_VOLUME_SHAPE_BOX" value="3" enum="FogVolumeShape"> [FogVolume] will be shaped like a box. @@ -4565,12 +4595,16 @@ Fade-in the given instance's dependencies when reaching its visibility range limits. </constant> <constant name="BAKE_CHANNEL_ALBEDO_ALPHA" value="0" enum="BakeChannels"> + Index of [Image] in array of [Image]s returned by [method bake_render_uv2]. Image uses [constant Image.FORMAT_RGBA8] and contains albedo color in the [code].rgb[/code] channels and alpha in the [code].a[/code] channel. </constant> <constant name="BAKE_CHANNEL_NORMAL" value="1" enum="BakeChannels"> + Index of [Image] in array of [Image]s returned by [method bake_render_uv2]. Image uses [constant Image.FORMAT_RGBA8] and contains the per-pixel normal of the object in the [code].rgb[/code] channels and nothing in the [code].a[/code] channel. The per-pixel normal is encoded as [code]normal * 0.5 + 0.5[/code]. </constant> <constant name="BAKE_CHANNEL_ORM" value="2" enum="BakeChannels"> + Index of [Image] in array of [Image]s returned by [method bake_render_uv2]. Image uses [constant Image.FORMAT_RGBA8] and contains ambient occlusion (from material and decals only) in the [code].r[/code] channel, roughness in the [code].g[/code] channel, metallic in the [code].b[/code] channel and sub surface scattering amount in the [code].a[/code] channel. </constant> <constant name="BAKE_CHANNEL_EMISSION" value="3" enum="BakeChannels"> + Index of [Image] in array of [Image]s returned by [method bake_render_uv2]. Image uses [constant Image.FORMAT_RGBAH] and contains emission color in the [code].rgb[/code] channels and nothing in the [code].a[/code] channel. </constant> <constant name="CANVAS_TEXTURE_CHANNEL_DIFFUSE" value="0" enum="CanvasTextureChannel"> </constant> diff --git a/doc/classes/ResourceFormatLoader.xml b/doc/classes/ResourceFormatLoader.xml index bb55123b37..1d509d2938 100644 --- a/doc/classes/ResourceFormatLoader.xml +++ b/doc/classes/ResourceFormatLoader.xml @@ -88,7 +88,7 @@ </description> </method> <method name="_rename_dependencies" qualifiers="virtual const"> - <return type="int" /> + <return type="int" enum="Error" /> <param index="0" name="path" type="String" /> <param index="1" name="renames" type="Dictionary" /> <description> diff --git a/doc/classes/ResourceFormatSaver.xml b/doc/classes/ResourceFormatSaver.xml index b0c57bc7cb..7e8e2ec67d 100644 --- a/doc/classes/ResourceFormatSaver.xml +++ b/doc/classes/ResourceFormatSaver.xml @@ -34,7 +34,7 @@ </description> </method> <method name="_save" qualifiers="virtual"> - <return type="int" /> + <return type="int" enum="Error" /> <param index="0" name="resource" type="Resource" /> <param index="1" name="path" type="String" /> <param index="2" name="flags" type="int" /> diff --git a/doc/classes/RichTextEffect.xml b/doc/classes/RichTextEffect.xml index c01546524d..333d34d1b7 100644 --- a/doc/classes/RichTextEffect.xml +++ b/doc/classes/RichTextEffect.xml @@ -13,7 +13,7 @@ [/gdscript] [csharp] // The RichTextEffect will be usable like this: `[example]Some text[/example]` - public string bbcode = "example"; + string bbcode = "example"; [/csharp] [/codeblocks] [b]Note:[/b] As soon as a [RichTextLabel] contains at least one [RichTextEffect], it will continuously process the effect unless the project is paused. This may impact battery life negatively. diff --git a/doc/classes/RichTextLabel.xml b/doc/classes/RichTextLabel.xml index 1ecc8a1d4e..5985af53fc 100644 --- a/doc/classes/RichTextLabel.xml +++ b/doc/classes/RichTextLabel.xml @@ -106,6 +106,45 @@ <return type="PopupMenu" /> <description> Returns the [PopupMenu] of this [RichTextLabel]. By default, this menu is displayed when right-clicking on the [RichTextLabel]. + You can add custom menu items or remove standard ones. Make sure your IDs don't conflict with the standard ones (see [enum MenuItems]). For example: + [codeblocks] + [gdscript] + func _ready(): + var menu = get_menu() + # Remove "Select All" item. + menu.remove_item(MENU_SELECT_ALL) + # Add custom items. + menu.add_separator() + menu.add_item("Duplicate Text", MENU_MAX + 1) + # Connect callback. + menu.id_pressed.connect(_on_item_pressed) + + func _on_item_pressed(id): + if id == MENU_MAX + 1: + add_text("\n" + get_parsed_text()) + [/gdscript] + [csharp] + public override void _Ready() + { + var menu = GetMenu(); + // Remove "Select All" item. + menu.RemoveItem(RichTextLabel.MenuItems.SelectAll); + // Add custom items. + menu.AddSeparator(); + menu.AddItem("Duplicate Text", RichTextLabel.MenuItems.Max + 1); + // Add event handler. + menu.IdPressed += OnItemPressed; + } + + public void OnItemPressed(int id) + { + if (id == TextEdit.MenuItems.Max + 1) + { + AddText("\n" + GetParsedText()); + } + } + [/csharp] + [/codeblocks] [b]Warning:[/b] This is a required internal node, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their [member Window.visible] property. </description> </method> @@ -193,6 +232,13 @@ If [member threaded] is enabled, returns [code]true[/code] if the background thread has finished text processing, otherwise always return [code]true[/code]. </description> </method> + <method name="menu_option"> + <return type="void" /> + <param index="0" name="option" type="int" /> + <description> + Executes a given action as defined in the [enum MenuItems] enum. + </description> + </method> <method name="newline"> <return type="void" /> <description> @@ -327,7 +373,7 @@ <return type="void" /> <param index="0" name="data" type="Variant" /> <description> - Adds a [code][meta][/code] tag to the tag stack. Similar to the BBCode [code][url=something]{text}[/url][/code], but supports non-[String] metadata types. + Adds a meta tag to the tag stack. Similar to the BBCode [code][url=something]{text}[/url][/code], but supports non-[String] metadata types. </description> </method> <method name="push_mono"> @@ -579,59 +625,14 @@ <constant name="LIST_DOTS" value="3" enum="ListType"> Each list item has a filled circle marker. </constant> - <constant name="ITEM_FRAME" value="0" enum="ItemType"> - </constant> - <constant name="ITEM_TEXT" value="1" enum="ItemType"> - </constant> - <constant name="ITEM_IMAGE" value="2" enum="ItemType"> - </constant> - <constant name="ITEM_NEWLINE" value="3" enum="ItemType"> - </constant> - <constant name="ITEM_FONT" value="4" enum="ItemType"> - </constant> - <constant name="ITEM_FONT_SIZE" value="5" enum="ItemType"> - </constant> - <constant name="ITEM_FONT_FEATURES" value="6" enum="ItemType"> - </constant> - <constant name="ITEM_COLOR" value="7" enum="ItemType"> - </constant> - <constant name="ITEM_OUTLINE_SIZE" value="8" enum="ItemType"> - </constant> - <constant name="ITEM_OUTLINE_COLOR" value="9" enum="ItemType"> - </constant> - <constant name="ITEM_UNDERLINE" value="10" enum="ItemType"> - </constant> - <constant name="ITEM_STRIKETHROUGH" value="11" enum="ItemType"> - </constant> - <constant name="ITEM_PARAGRAPH" value="12" enum="ItemType"> - </constant> - <constant name="ITEM_INDENT" value="13" enum="ItemType"> - </constant> - <constant name="ITEM_LIST" value="14" enum="ItemType"> - </constant> - <constant name="ITEM_TABLE" value="15" enum="ItemType"> - </constant> - <constant name="ITEM_FADE" value="16" enum="ItemType"> - </constant> - <constant name="ITEM_SHAKE" value="17" enum="ItemType"> - </constant> - <constant name="ITEM_WAVE" value="18" enum="ItemType"> - </constant> - <constant name="ITEM_TORNADO" value="19" enum="ItemType"> - </constant> - <constant name="ITEM_RAINBOW" value="20" enum="ItemType"> - </constant> - <constant name="ITEM_BGCOLOR" value="21" enum="ItemType"> - </constant> - <constant name="ITEM_FGCOLOR" value="22" enum="ItemType"> - </constant> - <constant name="ITEM_META" value="23" enum="ItemType"> - </constant> - <constant name="ITEM_HINT" value="24" enum="ItemType"> + <constant name="MENU_COPY" value="0" enum="MenuItems"> + Copies the selected text. </constant> - <constant name="ITEM_DROPCAP" value="25" enum="ItemType"> + <constant name="MENU_SELECT_ALL" value="1" enum="MenuItems"> + Selects the whole [RichTextLabel] text. </constant> - <constant name="ITEM_CUSTOMFX" value="26" enum="ItemType"> + <constant name="MENU_MAX" value="2" enum="MenuItems"> + Represents the size of the [enum MenuItems] enum. </constant> </constants> <theme_items> diff --git a/doc/classes/RigidBody2D.xml b/doc/classes/RigidBody2D.xml index 6e3535f14a..937d0910ec 100644 --- a/doc/classes/RigidBody2D.xml +++ b/doc/classes/RigidBody2D.xml @@ -176,6 +176,28 @@ <member name="inertia" type="float" setter="set_inertia" getter="get_inertia" default="0.0"> The body's moment of inertia. This is like mass, but for rotation: it determines how much torque it takes to rotate the body. The moment of inertia is usually computed automatically from the mass and the shapes, but this property allows you to set a custom value. If set to [code]0[/code], inertia is automatically computed (default value). + [b]Note:[/b] This value does not change when inertia is automatically computed. Use [PhysicsServer2D] to get the computed inertia. + [codeblocks] + [gdscript] + @onready var ball = $Ball + + func get_ball_inertia(): + return 1.0 / PhysicsServer2D.body_get_direct_state(ball.get_rid()).inverse_inertia + [/gdscript] + [csharp] + private RigidBody2D _ball; + + public override void _Ready() + { + _ball = GetNode<RigidBody2D>("Ball"); + } + + private float GetBallInertia() + { + return 1.0f / PhysicsServer2D.BodyGetDirectState(_ball.GetRid()).InverseInertia; + } + [/csharp] + [/codeblocks] </member> <member name="linear_damp" type="float" setter="set_linear_damp" getter="get_linear_damp" default="0.0"> Damps the body's movement. By default, the body will use the [b]Default Linear Damp[/b] in [b]Project > Project Settings > Physics > 2d[/b] or any value override set by an [Area2D] the body is in. Depending on [member linear_damp_mode], you can set [member linear_damp] to be added to or to replace the body's damping value. diff --git a/doc/classes/RigidBody3D.xml b/doc/classes/RigidBody3D.xml index 148cdf96ee..a066254b4f 100644 --- a/doc/classes/RigidBody3D.xml +++ b/doc/classes/RigidBody3D.xml @@ -183,6 +183,28 @@ <member name="inertia" type="Vector3" setter="set_inertia" getter="get_inertia" default="Vector3(0, 0, 0)"> The body's moment of inertia. This is like mass, but for rotation: it determines how much torque it takes to rotate the body on each axis. The moment of inertia is usually computed automatically from the mass and the shapes, but this property allows you to set a custom value. If set to [code]Vector3.ZERO[/code], inertia is automatically computed (default value). + [b]Note:[/b] This value does not change when inertia is automatically computed. Use [PhysicsServer3D] to get the computed inertia. + [codeblocks] + [gdscript] + @onready var ball = $Ball + + func get_ball_inertia(): + return PhysicsServer3D.body_get_direct_state(ball.get_rid()).inverse_inertia.inverse() + [/gdscript] + [csharp] + private RigidBody3D _ball; + + public override void _Ready() + { + _ball = GetNode<RigidBody3D>("Ball"); + } + + private Vector3 GetBallInertia() + { + return PhysicsServer3D.BodyGetDirectState(_ball.GetRid()).InverseInertia.Inverse(); + } + [/csharp] + [/codeblocks] </member> <member name="linear_damp" type="float" setter="set_linear_damp" getter="get_linear_damp" default="0.0"> Damps the body's movement. By default, the body will use the [b]Default Linear Damp[/b] in [b]Project > Project Settings > Physics > 3d[/b] or any value override set by an [Area3D] the body is in. Depending on [member linear_damp_mode], you can set [member linear_damp] to be added to or to replace the body's damping value. diff --git a/doc/classes/SceneTree.xml b/doc/classes/SceneTree.xml index bf19ebc23a..6adb37a3f7 100644 --- a/doc/classes/SceneTree.xml +++ b/doc/classes/SceneTree.xml @@ -74,10 +74,10 @@ print("end") [/gdscript] [csharp] - public async void SomeFunction() + public async Task SomeFunction() { GD.Print("start"); - await ToSignal(GetTree().CreateTimer(1.0f), "timeout"); + await ToSignal(GetTree().CreateTimer(1.0f), SceneTreeTimer.SignalName.Timeout); GD.Print("end"); } [/csharp] diff --git a/doc/classes/SceneTreeTimer.xml b/doc/classes/SceneTreeTimer.xml index f28e65c5bf..42b070d7d9 100644 --- a/doc/classes/SceneTreeTimer.xml +++ b/doc/classes/SceneTreeTimer.xml @@ -14,10 +14,10 @@ print("Timer ended.") [/gdscript] [csharp] - public async void SomeFunction() + public async Task SomeFunction() { GD.Print("Timer started."); - await ToSignal(GetTree().CreateTimer(1.0f), "timeout"); + await ToSignal(GetTree().CreateTimer(1.0f), SceneTreeTimer.SignalName.Timeout); GD.Print("Timer ended."); } [/csharp] diff --git a/doc/classes/ScriptExtension.xml b/doc/classes/ScriptExtension.xml index 045eadda41..61034f8e4a 100644 --- a/doc/classes/ScriptExtension.xml +++ b/doc/classes/ScriptExtension.xml @@ -32,6 +32,11 @@ <description> </description> </method> + <method name="_get_global_name" qualifiers="virtual const"> + <return type="StringName" /> + <description> + </description> + </method> <method name="_get_instance_base_type" qualifiers="virtual const"> <return type="StringName" /> <description> diff --git a/doc/classes/Signal.xml b/doc/classes/Signal.xml index 71905e8b2e..cdbeba0220 100644 --- a/doc/classes/Signal.xml +++ b/doc/classes/Signal.xml @@ -85,7 +85,10 @@ <method name="get_connections" qualifiers="const"> <return type="Array" /> <description> - Returns the list of [Callable]s connected to this signal. + Returns an [Array] of connections for this signal. Each connection is represented as a [Dictionary] that contains three entries: + - [code]signal[/code] is a reference to this signal; + - [code]callable[/code] is a reference to the connected [Callable]; + - [code]flags[/code] is a combination of [enum Object.ConnectFlags]. </description> </method> <method name="get_name" qualifiers="const"> diff --git a/doc/classes/Skeleton3D.xml b/doc/classes/Skeleton3D.xml index 70986ba06a..bdd3495798 100644 --- a/doc/classes/Skeleton3D.xml +++ b/doc/classes/Skeleton3D.xml @@ -240,7 +240,7 @@ <description> Sets the global pose transform, [param pose], for the bone at [param bone_idx]. [param amount] is the interpolation strength that will be used when applying the pose, and [param persistent] determines if the applied pose will remain. - [b]Note:[/b] The pose transform needs to be a global pose! To convert a world transform from a [Node3D] to a global bone pose, multiply the [method Transform3D.affine_inverse] of the node's [member Node3D.global_transform] by the desired world transform + [b]Note:[/b] The pose transform needs to be a global pose! To convert a world transform from a [Node3D] to a global bone pose, multiply the [method Transform3D.affine_inverse] of the node's [member Node3D.global_transform] by the desired world transform. </description> </method> <method name="set_bone_name"> diff --git a/doc/classes/SkeletonModification2DJiggle.xml b/doc/classes/SkeletonModification2DJiggle.xml index 3321fffe1b..12f3b9b901 100644 --- a/doc/classes/SkeletonModification2DJiggle.xml +++ b/doc/classes/SkeletonModification2DJiggle.xml @@ -107,7 +107,7 @@ <param index="0" name="joint_idx" type="int" /> <param index="1" name="damping" type="float" /> <description> - Sets the amount of dampening of the Jiggle joint at [param joint_idx]. + Sets the amount of damping of the Jiggle joint at [param joint_idx]. </description> </method> <method name="set_jiggle_joint_gravity"> @@ -160,7 +160,7 @@ </methods> <members> <member name="damping" type="float" setter="set_damping" getter="get_damping" default="0.75"> - The default amount of dampening applied to the Jiggle joints, if they are not overridden. Higher values lead to more of the calculated velocity being applied. + The default amount of damping applied to the Jiggle joints, if they are not overridden. Higher values lead to more of the calculated velocity being applied. </member> <member name="gravity" type="Vector2" setter="set_gravity" getter="get_gravity" default="Vector2(0, 6)"> The default amount of gravity applied to the Jiggle joints, if they are not overridden. diff --git a/doc/classes/SpotLight3D.xml b/doc/classes/SpotLight3D.xml index 59d36aefab..3b32923872 100644 --- a/doc/classes/SpotLight3D.xml +++ b/doc/classes/SpotLight3D.xml @@ -5,6 +5,8 @@ </brief_description> <description> A Spotlight is a type of [Light3D] node that emits lights in a specific direction, in the shape of a cone. The light is attenuated through the distance. This attenuation can be configured by changing the energy, radius and attenuation parameters of [Light3D]. + [b]Note:[/b] When using the Mobile rendering method, only 8 spot lights can be displayed on each mesh resource. Attempting to display more than 8 spot lights on a single mesh resource will result in spot lights flickering in and out as the camera moves. When using the Compatibility rendering method, only 8 spot lights can be displayed on each mesh resource by default, but this can be increased by adjusting [member ProjectSettings.rendering/limits/opengl/max_lights_per_object]. + [b]Note:[/b] When using the Mobile or Compatibility rendering methods, spot lights will only correctly affect meshes whose visibility AABB intersects with the light's AABB. If using a shader to deform the mesh in a way that makes it go outside its AABB, [member GeometryInstance3D.extra_cull_margin] must be increased on the mesh. Otherwise, the light may not be visible on the mesh. </description> <tutorials> <link title="3D lights and shadows">$DOCS_URL/tutorials/3d/lights_and_shadows.html</link> @@ -18,10 +20,11 @@ [b]Note:[/b] [member spot_angle] is not affected by [member Node3D.scale] (the light's scale or its parent's scale). </member> <member name="spot_angle_attenuation" type="float" setter="set_param" getter="get_param" default="1.0"> - The spotlight's angular attenuation curve. + The spotlight's [i]angular[/i] attenuation curve. See also [member spot_attenuation]. </member> <member name="spot_attenuation" type="float" setter="set_param" getter="get_param" default="1.0"> - The spotlight's light energy attenuation curve. + The spotlight's light energy (drop-off) attenuation curve. A number of presets are available in the [b]Inspector[/b] by right-clicking the curve. Zero and negative values are allowed but can produce unusual effects. See also [member spot_angle_attenuation]. + [b]Note:[/b] Very high [member spot_attenuation] values (typically above 10) can impact performance negatively if the light is made to use a larger [member spot_range] to compensate. This is because culling opportunities will become less common and shading costs will be increased (as the light will cover more pixels on screen while resulting in the same amount of brightness). To improve performance, use the lowest [member spot_attenuation] value possible for the visuals you're trying to achieve. </member> <member name="spot_range" type="float" setter="set_param" getter="get_param" default="5.0"> The maximal range that can be reached by the spotlight. Note that the effectively lit area may appear to be smaller depending on the [member spot_attenuation] in use. No matter the [member spot_attenuation] in use, the light will never reach anything outside this range. diff --git a/doc/classes/Sprite2D.xml b/doc/classes/Sprite2D.xml index 235fef0bdd..033dbf51f3 100644 --- a/doc/classes/Sprite2D.xml +++ b/doc/classes/Sprite2D.xml @@ -23,11 +23,11 @@ print("A click!") [/gdscript] [csharp] - public override void _Input(InputEvent inputEvent) + public override void _Input(InputEvent @event) { - if (inputEvent is InputEventMouseButton inputEventMouse) + if (@event is InputEventMouseButton inputEventMouse) { - if (inputEventMouse.Pressed && inputEventMouse.ButtonIndex == (int)ButtonList.Left) + if (inputEventMouse.Pressed && inputEventMouse.ButtonIndex == MouseButton.Left) { if (GetRect().HasPoint(ToLocal(inputEventMouse.Position))) { diff --git a/doc/classes/SpriteFrames.xml b/doc/classes/SpriteFrames.xml index 195f3598d5..59a56e7ca6 100644 --- a/doc/classes/SpriteFrames.xml +++ b/doc/classes/SpriteFrames.xml @@ -73,9 +73,9 @@ <description> Returns a relative duration of the frame [param idx] in the [param anim] animation (defaults to [code]1.0[/code]). For example, a frame with a duration of [code]2.0[/code] is displayed twice as long as a frame with a duration of [code]1.0[/code]. You can calculate the absolute duration (in seconds) of a frame using the following formula: [codeblock] - absolute_duration = relative_duration / (animation_fps * abs(speed_scale)) + absolute_duration = relative_duration / (animation_fps * abs(playing_speed)) [/codeblock] - In this example, [code]speed_scale[/code] refers to either [member AnimatedSprite2D.speed_scale] or [member AnimatedSprite3D.speed_scale]. + In this example, [code]playing_speed[/code] refers to either [method AnimatedSprite2D.get_playing_speed] or [method AnimatedSprite3D.get_playing_speed]. </description> </method> <method name="get_frame_texture" qualifiers="const"> diff --git a/doc/classes/StreamPeer.xml b/doc/classes/StreamPeer.xml index f05b5f7dbf..9a70690122 100644 --- a/doc/classes/StreamPeer.xml +++ b/doc/classes/StreamPeer.xml @@ -109,6 +109,7 @@ <param index="0" name="allow_objects" type="bool" default="false" /> <description> Gets a Variant from the stream. If [param allow_objects] is [code]true[/code], decoding objects is allowed. + Internally, this uses the same decoding mechanism as the [method @GlobalScope.bytes_to_var] method. [b]Warning:[/b] Deserialized objects can contain code which gets executed. Do not use this option if the serialized object comes from untrusted sources to avoid potential security threats such as remote code execution. </description> </method> @@ -223,7 +224,7 @@ put_data("Hello world".to_utf8()) [/gdscript] [csharp] - PutData("Hello World".ToUTF8()); + PutData("Hello World".ToUtf8()); [/csharp] [/codeblocks] </description> @@ -234,6 +235,7 @@ <param index="1" name="full_objects" type="bool" default="false" /> <description> Puts a Variant into the stream. If [param full_objects] is [code]true[/code] encoding objects is allowed (and can potentially include code). + Internally, this uses the same encoding mechanism as the [method @GlobalScope.var_to_bytes] method. </description> </method> </methods> diff --git a/doc/classes/String.xml b/doc/classes/String.xml index 143e1f23e9..53b34332d7 100644 --- a/doc/classes/String.xml +++ b/doc/classes/String.xml @@ -193,8 +193,8 @@ GD.Print("Team".Find("I")); // Prints -1 GD.Print("Potato".Find("t")); // Prints 2 - GD.print("Potato".Find("t", 3)); // Prints 4 - GD.print("Potato".Find("t", 5)); // Prints -1 + GD.Print("Potato".Find("t", 3)); // Prints 4 + GD.Print("Potato".Find("t", 5)); // Prints -1 [/csharp] [/codeblocks] [b]Note:[/b] If you just want to know whether the string contains [param what], use [method contains]. In GDScript, you may also use the [code]in[/code] operator. @@ -230,6 +230,7 @@ print("User {id} is {name}.".format([["id", 42], ["name", "Godot"]])) [/codeblock] See also the [url=$DOCS_URL/tutorials/scripting/gdscript/gdscript_format_string.html]GDScript format string[/url] tutorial. + [b]Note:[/b] In C#, it's recommended to [url=https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/tokens/interpolated]interpolate strings with "$"[/url], instead. </description> </method> <method name="get_base_dir" qualifiers="const"> @@ -480,7 +481,7 @@ var fruits = new string[] {"Apple", "Orange", "Pear", "Kiwi"}; // In C#, this method is static. - GD.Print(string.Join(", ", fruits); // Prints "Apple, Orange, Pear, Kiwi" + GD.Print(string.Join(", ", fruits)); // Prints "Apple, Orange, Pear, Kiwi" GD.Print(string.Join("---", fruits)); // Prints "Apple---Orange---Pear---Kiwi" [/csharp] [/codeblocks] @@ -529,7 +530,7 @@ <return type="bool" /> <param index="0" name="expr" type="String" /> <description> - Does a simple expression match, where [code]*[/code] matches zero or more arbitrary characters and [code]?[/code] matches any single character except a period ([code].[/code]). An empty string or empty expression always evaluates to [code]false[/code]. + Does a simple expression match (also called "glob" or "globbing"), where [code]*[/code] matches zero or more arbitrary characters and [code]?[/code] matches any single character except a period ([code].[/code]). An empty string or empty expression always evaluates to [code]false[/code]. </description> </method> <method name="matchn" qualifiers="const"> @@ -1047,18 +1048,17 @@ <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]. + 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 my_message = "Travelling to %s, at %2.2f km/h." 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. + [b]Note:[/b] In C#, this operator is not available. Instead, see [url=https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/tokens/interpolated]how to interpolate strings with "$"[/url]. </description> </operator> <operator name="operator +"> @@ -1072,6 +1072,7 @@ <return type="String" /> <param index="0" name="right" type="StringName" /> <description> + Appends [param right] at the end of this [String], returning a [String]. This is also known as a string concatenation. </description> </operator> <operator name="operator <"> diff --git a/doc/classes/StringName.xml b/doc/classes/StringName.xml index c103fb2287..4ccb93dab3 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, in GDScript, 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 the [StringName] constructor or, in GDScript, the literal syntax [code]&"example"[/code]. See also [NodePath], which is a similar concept specifically designed to store pre-parsed node paths. Some string methods have corresponding variations. Variations suffixed with [code]n[/code] ([method countn], [method findn], [method replacen], etc.) are [b]case-insensitive[/b] (they make no distinction between uppercase and lowercase letters). Method variations prefixed with [code]r[/code] ([method rfind], [method rsplit], etc.) are reversed, and start from the end of the string, instead of the beginning. [b]Note:[/b] In a boolean context, a [StringName] will evaluate to [code]false[/code] if it is empty ([code]StringName("")[/code]). Otherwise, a [StringName] will always evaluate to [code]true[/code]. @@ -176,8 +176,8 @@ GD.Print("Team".Find("I")); // Prints -1 GD.Print("Potato".Find("t")); // Prints 2 - GD.print("Potato".Find("t", 3)); // Prints 4 - GD.print("Potato".Find("t", 5)); // Prints -1 + GD.Print("Potato".Find("t", 3)); // Prints 4 + GD.Print("Potato".Find("t", 5)); // Prints -1 [/csharp] [/codeblocks] [b]Note:[/b] If you just want to know whether the string contains [param what], use [method contains]. In GDScript, you may also use the [code]in[/code] operator. @@ -213,6 +213,7 @@ print("User {id} is {name}.".format([["id", 42], ["name", "Godot"]])) [/codeblock] See also the [url=$DOCS_URL/tutorials/scripting/gdscript/gdscript_format_string.html]GDScript format string[/url] tutorial. + [b]Note:[/b] In C#, it's recommended to [url=https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/tokens/interpolated]interpolate strings with "$"[/url], instead. </description> </method> <method name="get_base_dir" qualifiers="const"> @@ -455,7 +456,7 @@ var fruits = new string[] {"Apple", "Orange", "Pear", "Kiwi"}; // In C#, this method is static. - GD.Print(string.Join(", ", fruits); // Prints "Apple, Orange, Pear, Kiwi" + GD.Print(string.Join(", ", fruits)); // Prints "Apple, Orange, Pear, Kiwi" GD.Print(string.Join("---", fruits)); // Prints "Apple---Orange---Pear---Kiwi" [/csharp] [/codeblocks] @@ -504,7 +505,7 @@ <return type="bool" /> <param index="0" name="expr" type="String" /> <description> - Does a simple expression match, where [code]*[/code] matches zero or more arbitrary characters and [code]?[/code] matches any single character except a period ([code].[/code]). An empty string or empty expression always evaluates to [code]false[/code]. + Does a simple expression match (also called "glob" or "globbing"), where [code]*[/code] matches zero or more arbitrary characters and [code]?[/code] matches any single character except a period ([code].[/code]). An empty string or empty expression always evaluates to [code]false[/code]. </description> </method> <method name="matchn" qualifiers="const"> @@ -954,18 +955,23 @@ <return type="String" /> <param index="0" name="right" type="Variant" /> <description> + Formats the [StringName], replacing the placeholders with one or more parameters, returning a [String]. To pass multiple parameters, [param right] needs to be an [Array]. + For more information, see the [url=$DOCS_URL/tutorials/scripting/gdscript/gdscript_format_string.html]GDScript format strings[/url] tutorial. + [b]Note:[/b] In C#, this operator is not available. Instead, see [url=https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/tokens/interpolated]how to interpolate strings with "$"[/url]. </description> </operator> <operator name="operator +"> <return type="String" /> <param index="0" name="right" type="String" /> <description> + Appends [param right] at the end of this [StringName], returning a [String]. This is also known as a string concatenation. </description> </operator> <operator name="operator +"> <return type="String" /> <param index="0" name="right" type="StringName" /> <description> + Appends [param right] at the end of this [StringName], returning a [String]. This is also known as a string concatenation. </description> </operator> <operator name="operator <"> diff --git a/doc/classes/StyleBoxFlat.xml b/doc/classes/StyleBoxFlat.xml index d6900f935c..6bcc3c5ea6 100644 --- a/doc/classes/StyleBoxFlat.xml +++ b/doc/classes/StyleBoxFlat.xml @@ -94,7 +94,7 @@ <return type="void" /> <param index="0" name="size" type="float" /> <description> - Sets the expand margin to [param size] pixels for all margins. + Sets the expand margin to [param size] pixels for all sides. </description> </method> </methods> diff --git a/doc/classes/StyleBoxTexture.xml b/doc/classes/StyleBoxTexture.xml index f2f6e59a9e..6a29bf38db 100644 --- a/doc/classes/StyleBoxTexture.xml +++ b/doc/classes/StyleBoxTexture.xml @@ -35,7 +35,7 @@ <return type="void" /> <param index="0" name="size" type="float" /> <description> - Sets the expand margin to [param size] pixels for all margins. + Sets the expand margin to [param size] pixels for all sides. </description> </method> <method name="set_texture_margin"> diff --git a/doc/classes/SubViewport.xml b/doc/classes/SubViewport.xml index 7020cae1de..bb76a82ef3 100644 --- a/doc/classes/SubViewport.xml +++ b/doc/classes/SubViewport.xml @@ -26,6 +26,7 @@ </member> <member name="size" type="Vector2i" setter="set_size" getter="get_size" default="Vector2i(512, 512)"> The width and height of the sub-viewport. Must be set to a value greater than or equal to 2 pixels on both dimensions. Otherwise, nothing will be displayed. + [b]Note:[/b] If the parent node is a [SubViewportContainer] and its [member SubViewportContainer.stretch] is [code]true[/code], the viewport size cannot be changed manually. </member> <member name="size_2d_override" type="Vector2i" setter="set_size_2d_override" getter="get_size_2d_override" default="Vector2i(0, 0)"> The 2D size override of the sub-viewport. If either the width or height is [code]0[/code], the override is disabled. diff --git a/doc/classes/SubViewportContainer.xml b/doc/classes/SubViewportContainer.xml index 77aa7e3ff4..11137222a9 100644 --- a/doc/classes/SubViewportContainer.xml +++ b/doc/classes/SubViewportContainer.xml @@ -13,6 +13,7 @@ <members> <member name="stretch" type="bool" setter="set_stretch" getter="is_stretch_enabled" default="false"> If [code]true[/code], the sub-viewport will be automatically resized to the control's size. + [b]Note:[/b] If [code]true[/code], this will prohibit changing [member SubViewport.size] of its children manually. </member> <member name="stretch_shrink" type="int" setter="set_stretch_shrink" getter="get_stretch_shrink" default="1"> Divides the sub-viewport's effective resolution by this value while preserving its scale. This can be used to speed up rendering. diff --git a/doc/classes/TextEdit.xml b/doc/classes/TextEdit.xml index c309026aaa..be8c4c2485 100644 --- a/doc/classes/TextEdit.xml +++ b/doc/classes/TextEdit.xml @@ -436,7 +436,7 @@ <return type="int" /> <param index="0" name="position" type="Vector2i" /> <description> - Returns the equivalent minimap line at [param position] + Returns the equivalent minimap line at [param position]. </description> </method> <method name="get_minimap_visible_lines" qualifiers="const"> @@ -483,7 +483,7 @@ <method name="get_saved_version" qualifiers="const"> <return type="int" /> <description> - Returns the last tagged saved version from [method tag_saved_version] + Returns the last tagged saved version from [method tag_saved_version]. </description> </method> <method name="get_scroll_pos_for_line" qualifiers="const"> @@ -1054,7 +1054,7 @@ <return type="void" /> <param index="0" name="callback" type="Callable" /> <description> - Provide custom tooltip text. The callback method must take the following args: [code]hovered_word: String[/code] + Provide custom tooltip text. The callback method must take the following args: [code]hovered_word: String[/code]. </description> </method> <method name="start_action"> diff --git a/doc/classes/TextServer.xml b/doc/classes/TextServer.xml index 711fb89217..ad37cf5c86 100644 --- a/doc/classes/TextServer.xml +++ b/doc/classes/TextServer.xml @@ -12,7 +12,7 @@ <method name="create_font"> <return type="RID" /> <description> - Creates new, empty font cache entry resource. To free the resulting resourec, use [method free_rid] method. + Creates new, empty font cache entry resource. To free the resulting resource, use [method free_rid] method. </description> </method> <method name="create_shaped_text"> diff --git a/doc/classes/TextureLayered.xml b/doc/classes/TextureLayered.xml index 8f6dff7acf..7a0940edd4 100644 --- a/doc/classes/TextureLayered.xml +++ b/doc/classes/TextureLayered.xml @@ -8,7 +8,7 @@ Data is set on a per-layer basis. For [Texture2DArray]s, the layer specifies the array layer. All images need to have the same width, height and number of mipmap levels. A [TextureLayered] can be loaded with [method ResourceLoader.load]. - Internally, Godot maps these files to their respective counterparts in the target rendering driver (Vulkan, GLES3). + Internally, Godot maps these files to their respective counterparts in the target rendering driver (Vulkan, OpenGL3). </description> <tutorials> </tutorials> diff --git a/doc/classes/TextureRect.xml b/doc/classes/TextureRect.xml index 460ffbbb80..3500a0ddf5 100644 --- a/doc/classes/TextureRect.xml +++ b/doc/classes/TextureRect.xml @@ -10,8 +10,9 @@ <link title="3D Voxel Demo">https://godotengine.org/asset-library/asset/676</link> </tutorials> <members> - <member name="expand_mode" type="int" setter="set_expand_mode" getter="get_expand_mode" enum="TextureRect.ExpandMode" default="0"> + <member name="expand_mode" type="int" setter="set_expand_mode" getter="get_expand_mode" enum="TextureRect.ExpandMode" default="0" is_experimental="true"> Defines how minimum size is determined based on the texture's size. See [enum ExpandMode] for options. + [b]Note:[/b] Using [constant EXPAND_FIT_WIDTH], [constant EXPAND_FIT_WIDTH_PROPORTIONAL], [constant EXPAND_FIT_HEIGHT] or [constant EXPAND_FIT_HEIGHT_PROPORTIONAL] may result in unstable behavior in some containers. This functionality is being re-evaluated and will change in the future. </member> <member name="flip_h" type="bool" setter="set_flip_h" getter="is_flipped_h" default="false"> If [code]true[/code], texture is flipped horizontally. diff --git a/doc/classes/TileMap.xml b/doc/classes/TileMap.xml index c387bd435b..413cf62f7d 100644 --- a/doc/classes/TileMap.xml +++ b/doc/classes/TileMap.xml @@ -168,6 +168,15 @@ Returns the number of layers in the TileMap. </description> </method> + <method name="get_navigation_map" qualifiers="const"> + <return type="RID" /> + <param index="0" name="layer" type="int" /> + <description> + Returns the [NavigationServer2D] navigation map [RID] currently assigned to the specified TileMap [param layer]. + By default the TileMap uses the default [World2D] navigation map for the first TileMap layer. For each additional TileMap layer a new navigation map is created for the additional layer. + In order to make [NavigationAgent2D] switch between TileMap layer navigation maps use [method NavigationAgent2D.set_navigation_map] with the navigation map received from [method get_navigation_map]. + </description> + </method> <method name="get_neighbor_cell" qualifiers="const"> <return type="Vector2i" /> <param index="0" name="coords" type="Vector2i" /> @@ -188,7 +197,7 @@ <return type="Vector2i[]" /> <param index="0" name="coords" type="Vector2i" /> <description> - Returns the list of all neighbourings cells to the one at [param coords] + Returns the list of all neighbourings cells to the one at [param coords]. </description> </method> <method name="get_used_cells" qualifiers="const"> @@ -205,7 +214,7 @@ <param index="2" name="atlas_coords" type="Vector2i" default="Vector2i(-1, -1)" /> <param index="3" name="alternative_tile" type="int" default="-1" /> <description> - Returns a [Vector2i] array with the positions of all cells containing a tile in the given layer. Tiles may be filtered according to their source ([param source_id]), their atlas coordinates ([param atlas_coords]) or alternative id ([param source_id]). + Returns a [Vector2i] array with the positions of all cells containing a tile in the given layer. Tiles may be filtered according to their source ([param source_id]), their atlas coordinates ([param atlas_coords]) or alternative id ([param alternative_tile]). If a parameter has it's value set to the default one, this parameter is not used to filter a cell. Thus, if all parameters have their respective default value, this method returns the same result as [method get_used_cells]. A cell is considered empty if its source identifier equals -1, its atlas coordinates identifiers is [code]Vector2(-1, -1)[/code] and its alternative identifier is -1. </description> @@ -243,7 +252,7 @@ <param index="1" name="coords_in_pattern" type="Vector2i" /> <param index="2" name="pattern" type="TileMapPattern" /> <description> - Returns for the given coordinate [param coords_in_pattern] in a [TileMapPattern] the corresponding cell coordinates if the pattern was pasted at the [param position_in_tilemap] coordinates (see [method set_pattern]). This mapping is required as in half-offset tile shapes, the mapping might not work by calculating [code]position_in_tile_map + coords_in_pattern[/code] + Returns for the given coordinate [param coords_in_pattern] in a [TileMapPattern] the corresponding cell coordinates if the pattern was pasted at the [param position_in_tilemap] coordinates (see [method set_pattern]). This mapping is required as in half-offset tile shapes, the mapping might not work by calculating [code]position_in_tile_map + coords_in_pattern[/code]. </description> </method> <method name="map_to_local" qualifiers="const"> @@ -279,8 +288,8 @@ <description> Sets the tile indentifiers for the cell on layer [param layer] at coordinates [param coords]. Each tile of the [TileSet] is identified using three parts: - The source identifier [param source_id] identifies a [TileSetSource] identifier. See [method TileSet.set_source_id], - - The atlas coordinates identifier [param atlas_coords] identifies a tile coordinates in the atlas (if the source is a [TileSetAtlasSource]. For [TileSetScenesCollectionSource] it should always be [code]Vector2i(0, 0)[/code]), - - The alternative tile identifier [param alternative_tile] identifies a tile alternative the source is a [TileSetAtlasSource], and the scene for a [TileSetScenesCollectionSource]. + - The atlas coordinates identifier [param atlas_coords] identifies a tile coordinates in the atlas (if the source is a [TileSetAtlasSource]). For [TileSetScenesCollectionSource] it should always be [code]Vector2i(0, 0)[/code]), + - The alternative tile identifier [param alternative_tile] identifies a tile alternative in the atlas (if the source is a [TileSetAtlasSource]), and the scene for a [TileSetScenesCollectionSource]. If [param source_id] is set to [code]-1[/code], [param atlas_coords] to [code]Vector2i(-1, -1)[/code] or [param alternative_tile] to [code]-1[/code], the cell will be erased. An erased cell gets [b]all[/b] its identifiers automatically set to their respective invalid values, namely [code]-1[/code], [code]Vector2i(-1, -1)[/code] and [code]-1[/code]. </description> </method> @@ -366,6 +375,16 @@ If [code]layer[/code] is negative, the layers are accessed from the last one. </description> </method> + <method name="set_navigation_map"> + <return type="void" /> + <param index="0" name="layer" type="int" /> + <param index="1" name="map" type="RID" /> + <description> + Assigns a [NavigationServer2D] navigation map [RID] to the specified TileMap [param layer]. + By default the TileMap uses the default [World2D] navigation map for the first TileMap layer. For each additional TileMap layer a new navigation map is created for the additional layer. + In order to make [NavigationAgent2D] switch between TileMap layer navigation maps use [method NavigationAgent2D.set_navigation_map] with the navigation map received from [method get_navigation_map]. + </description> + </method> <method name="set_pattern"> <return type="void" /> <param index="0" name="layer" type="int" /> diff --git a/doc/classes/Time.xml b/doc/classes/Time.xml index 1abe017a4d..ca2a6bec36 100644 --- a/doc/classes/Time.xml +++ b/doc/classes/Time.xml @@ -64,7 +64,7 @@ <return type="Dictionary" /> <param index="0" name="unix_time_val" type="int" /> <description> - Converts the given Unix timestamp to a dictionary of keys: [code]year[/code], [code]month[/code], [code]day[/code], and [code]weekday[/code]. + Converts the given Unix timestamp to a dictionary of keys: [code]year[/code], [code]month[/code], [code]day[/code], [code]weekday[/code], [code]hour[/code], [code]minute[/code], and [code]second[/code]. The returned Dictionary's values will be the same as the [method get_datetime_dict_from_system] if the Unix timestamp is the current time, with the exception of Daylight Savings Time as it cannot be determined from the epoch. </description> </method> diff --git a/doc/classes/Tree.xml b/doc/classes/Tree.xml index cf28dafcc9..02a2789ea5 100644 --- a/doc/classes/Tree.xml +++ b/doc/classes/Tree.xml @@ -410,11 +410,6 @@ Emitted when an item is collapsed by a click on the folding arrow. </description> </signal> - <signal name="item_custom_button_pressed"> - <description> - Emitted when a custom button is pressed (i.e. in a [constant TreeItem.CELL_MODE_CUSTOM] mode cell). - </description> - </signal> <signal name="item_edited"> <description> Emitted when an item is edited. diff --git a/doc/classes/Tween.xml b/doc/classes/Tween.xml index 9bb92cf362..16e4ce3714 100644 --- a/doc/classes/Tween.xml +++ b/doc/classes/Tween.xml @@ -77,13 +77,13 @@ tween = create_tween() [/gdscript] [csharp] - private Tween tween; + private Tween _tween; public void Animate() { - if (tween != null) - tween.Kill(); // Abort the previous animation - tween = CreateTween(); + if (_tween != null) + _tween.Kill(); // Abort the previous animation + _tween = CreateTween(); } [/csharp] [/codeblocks] diff --git a/doc/classes/UDPServer.xml b/doc/classes/UDPServer.xml index c3a3a49a80..8151ecb625 100644 --- a/doc/classes/UDPServer.xml +++ b/doc/classes/UDPServer.xml @@ -9,7 +9,8 @@ Below a small example of how it can be used: [codeblocks] [gdscript] - class_name Server + # server_node.gd + class_name ServerNode extends Node var server := UDPServer.new() @@ -34,35 +35,35 @@ pass # Do something with the connected peers. [/gdscript] [csharp] + // ServerNode.cs using Godot; - using System; using System.Collections.Generic; - public class Server : Node + public partial class ServerNode : Node { - public UDPServer Server = new UDPServer(); - public List<PacketPeerUDP> Peers = new List<PacketPeerUDP>(); + private UdpServer _server = new UdpServer(); + private List<PacketPeerUdp> _peers = new List<PacketPeerUdp>(); public override void _Ready() { - Server.Listen(4242); + _server.Listen(4242); } - public override void _Process(float delta) + public override void _Process(double delta) { - Server.Poll(); // Important! - if (Server.IsConnectionAvailable()) + _server.Poll(); // Important! + if (_server.IsConnectionAvailable()) { - PacketPeerUDP peer = Server.TakeConnection(); + PacketPeerUdp peer = _server.TakeConnection(); byte[] packet = peer.GetPacket(); - GD.Print($"Accepted Peer: {peer.GetPacketIp()}:{peer.GetPacketPort()}"); - GD.Print($"Received Data: {packet.GetStringFromUTF8()}"); + GD.Print($"Accepted Peer: {peer.GetPacketIP()}:{peer.GetPacketPort()}"); + GD.Print($"Received Data: {packet.GetStringFromUtf8()}"); // Reply so it knows we received the message. peer.PutPacket(packet); // Keep a reference so we can keep contacting the remote peer. - Peers.Add(peer); + _peers.Add(peer); } - foreach (var peer in Peers) + foreach (var peer in _peers) { // Do something with the peers. } @@ -72,7 +73,8 @@ [/codeblocks] [codeblocks] [gdscript] - class_name Client + # client_node.gd + class_name ClientNode extends Node var udp := PacketPeerUDP.new() @@ -90,30 +92,30 @@ connected = true [/gdscript] [csharp] + // ClientNode.cs using Godot; - using System; - public class Client : Node + public partial class ClientNode : Node { - public PacketPeerUDP Udp = new PacketPeerUDP(); - public bool Connected = false; + private PacketPeerUdp _udp = new PacketPeerUdp(); + private bool _connected = false; public override void _Ready() { - Udp.ConnectToHost("127.0.0.1", 4242); + _udp.ConnectToHost("127.0.0.1", 4242); } - public override void _Process(float delta) + public override void _Process(double delta) { - if (!Connected) + if (!_connected) { // Try to contact server - Udp.PutPacket("The Answer Is..42!".ToUTF8()); + _udp.PutPacket("The Answer Is..42!".ToUtf8()); } - if (Udp.GetAvailablePacketCount() > 0) + if (_udp.GetAvailablePacketCount() > 0) { - GD.Print($"Connected: {Udp.GetPacket().GetStringFromUTF8()}"); - Connected = true; + GD.Print($"Connected: {_udp.GetPacket().GetStringFromUtf8()}"); + _connected = true; } } } diff --git a/doc/classes/UndoRedo.xml b/doc/classes/UndoRedo.xml index 6c151ef958..e43bceb941 100644 --- a/doc/classes/UndoRedo.xml +++ b/doc/classes/UndoRedo.xml @@ -27,11 +27,11 @@ undo_redo.commit_action() [/gdscript] [csharp] - public UndoRedo UndoRedo; + private UndoRedo _undoRedo; public override void _Ready() { - UndoRedo = GetUndoRedo(); // Method of EditorPlugin. + _undoRedo = GetUndoRedo(); // Method of EditorPlugin. } public void DoSomething() @@ -47,12 +47,12 @@ private void OnMyButtonPressed() { var node = GetNode<Node2D>("MyNode2D"); - UndoRedo.CreateAction("Move the node"); - UndoRedo.AddDoMethod(this, MethodName.DoSomething); - UndoRedo.AddUndoMethod(this, MethodName.UndoSomething); - UndoRedo.AddDoProperty(node, Node2D.PropertyName.Position, new Vector2(100, 100)); - UndoRedo.AddUndoProperty(node, Node2D.PropertyName.Position, node.Position); - UndoRedo.CommitAction(); + _undoRedo.CreateAction("Move the node"); + _undoRedo.AddDoMethod(new Callable(this, MethodName.DoSomething)); + _undoRedo.AddUndoMethod(new Callable(this, MethodName.UndoSomething)); + _undoRedo.AddDoProperty(node, "position", new Vector2(100, 100)); + _undoRedo.AddUndoProperty(node, "position", node.Position); + _undoRedo.CommitAction(); } [/csharp] [/codeblocks] diff --git a/doc/classes/Variant.xml b/doc/classes/Variant.xml index 5416468ab6..390722b7e5 100644 --- a/doc/classes/Variant.xml +++ b/doc/classes/Variant.xml @@ -14,16 +14,21 @@ # bar = "Uh oh! I can't make static variables become a different type!" [/gdscript] [csharp] - // ... but C# is statically typed. Once a variable has a type it cannot be changed. However you can use the var keyword in methods to let the compiler decide the type automatically. - var foo = 2; // Foo is a 32-bit integer (int). Be cautious, integers in GDScript are 64-bit and the direct C# equivalent is "long". + // C# is statically typed. Once a variable has a type it cannot be changed. You can use the `var` keyword to let the compiler infer the type automatically. + var foo = 2; // Foo is a 32-bit integer (int). Be cautious, integers in GDScript are 64-bit and the direct C# equivalent is `long`. // foo = "foo was and will always be an integer. It cannot be turned into a string!"; var boo = "Boo is a string!"; - var ref = new Reference(); // var is especially useful when used together with a constructor. + var ref = new RefCounted(); // var is especially useful when used together with a constructor. + + // Godot also provides a Variant type that works like an union of all the Variant-compatible types. + Variant fooVar = 2; // fooVar is dynamically an integer (stored as a `long` in the Variant type). + fooVar = "Now fooVar is a string!"; + fooVar = new RefCounted(); // fooVar is a GodotObject. [/csharp] [/codeblocks] Godot tracks all scripting API variables within Variants. Without even realizing it, you use Variants all the time. When a particular language enforces its own rules for keeping data typed, then that language is applying its own custom logic over the base Variant scripting API. - GDScript automatically wrap values in them. It keeps all data in plain Variants by default and then optionally enforces custom static typing rules on variable types. - - C# is statically typed, but uses the Mono [code]object[/code] type in place of Godot's Variant class when it needs to represent a dynamic value. [code]object[/code] is the Mono runtime's equivalent of the same concept. + - C# is statically typed, but uses its own implementation of the [code]Variant[/code] type in place of Godot's Variant class when it needs to represent a dynamic value. A [code]Variant[/code] can be assigned any compatible type implicitly but converting requires an explicit cast. The global [method @GlobalScope.typeof] function returns the enumerated value of the Variant type stored in the current variable (see [enum Variant.Type]). [codeblocks] [gdscript] @@ -38,18 +43,24 @@ # To get the name of the underlying Object type, you need the `get_class()` method. print("foo is a(n) %s" % foo.get_class()) # inject the class name into a formatted string. # Note also that there is not yet any way to get a script's `class_name` string easily. - # To fetch that value, you can parse the [code]res://.godot/global_script_class_cache.cfg[/code] file with the [ConfigFile] API. + # To fetch that value, you can use [member ProjectSettings.get_global_class_list]. # Open your project.godot file to see it up close. [/gdscript] [csharp] - int foo = 2; - if (foo == null) + Variant foo = 2; + switch (foo.VariantType) { - GD.Print("foo is null"); - } - if (foo is int) - { - GD.Print("foo is an integer"); + case Variant.Type.Nil: + GD.Print("foo is null"); + break; + case Variant.Type.Int: + GD.Print("foo is an integer"); + break; + case Variant.Type.Object: + // Note that Objects are their own special category. + // You can convert a Variant to a GodotObject and use reflection to get its name. + GD.Print($"foo is a(n) {foo.AsGodotObject().GetType().Name}"); + break; } [/csharp] [/codeblocks] diff --git a/doc/classes/Viewport.xml b/doc/classes/Viewport.xml index ab2de14638..e76f805e3c 100644 --- a/doc/classes/Viewport.xml +++ b/doc/classes/Viewport.xml @@ -277,6 +277,10 @@ <member name="physics_object_picking" type="bool" setter="set_physics_object_picking" getter="get_physics_object_picking" default="false"> If [code]true[/code], the objects rendered by viewport become subjects of mouse picking process. </member> + <member name="physics_object_picking_sort" type="bool" setter="set_physics_object_picking_sort" getter="get_physics_object_picking_sort" default="false"> + If [code]true[/code], objects receive mouse picking events sorted primarily by their [member CanvasItem.z_index] and secondarily by their position in the scene tree. If [code]false[/code], the order is undetermined. + [b]Note:[/b] This setting is disabled by default because of its potential expensive computational cost. + </member> <member name="positional_shadow_atlas_16_bits" type="bool" setter="set_positional_shadow_atlas_16_bits" getter="get_positional_shadow_atlas_16_bits" default="true"> </member> <member name="positional_shadow_atlas_quad_0" type="int" setter="set_positional_shadow_atlas_quadrant_subdiv" getter="get_positional_shadow_atlas_quadrant_subdiv" enum="Viewport.PositionalShadowAtlasQuadrantSubdiv" default="2"> diff --git a/doc/classes/VisibleOnScreenEnabler2D.xml b/doc/classes/VisibleOnScreenEnabler2D.xml index 8590e9cc9f..68e510a6dc 100644 --- a/doc/classes/VisibleOnScreenEnabler2D.xml +++ b/doc/classes/VisibleOnScreenEnabler2D.xml @@ -24,7 +24,7 @@ Corresponds to [constant Node.PROCESS_MODE_ALWAYS]. </constant> <constant name="ENABLE_MODE_WHEN_PAUSED" value="2" enum="EnableMode"> - Corresponds to [constant Node.PROCESS_MODE_WHEN_PAUSED. + Corresponds to [constant Node.PROCESS_MODE_WHEN_PAUSED]. </constant> </constants> </class> diff --git a/doc/classes/VisibleOnScreenNotifier2D.xml b/doc/classes/VisibleOnScreenNotifier2D.xml index 32cb191067..c6a7bd5690 100644 --- a/doc/classes/VisibleOnScreenNotifier2D.xml +++ b/doc/classes/VisibleOnScreenNotifier2D.xml @@ -6,6 +6,7 @@ <description> The VisibleOnScreenNotifier2D detects when it is visible on the screen. It also notifies when its bounding rectangle enters or exits the screen or a viewport. If you want nodes to be disabled automatically when they exit the screen, use [VisibleOnScreenEnabler2D] instead. + [b]Note:[/b] VisibleOnScreenNotifier2D uses the render culling code to determine whether it's visible on screen, which also means that its [member CanvasItem.visible] must be [code]true[/code] to work correctly. </description> <tutorials> <link title="2D Dodge The Creeps Demo">https://godotengine.org/asset-library/asset/515</link> diff --git a/doc/classes/VisibleOnScreenNotifier3D.xml b/doc/classes/VisibleOnScreenNotifier3D.xml index 6dec09d03f..aecc3dd0d5 100644 --- a/doc/classes/VisibleOnScreenNotifier3D.xml +++ b/doc/classes/VisibleOnScreenNotifier3D.xml @@ -6,7 +6,7 @@ <description> The VisibleOnScreenNotifier3D detects when it is visible on the screen. It also notifies when its bounding rectangle enters or exits the screen or a [Camera3D]'s view. If you want nodes to be disabled automatically when they exit the screen, use [VisibleOnScreenEnabler3D] instead. - [b]Note:[/b] VisibleOnScreenNotifier3D uses an approximate heuristic for performance reasons. It doesn't take walls and other occlusion into account. The heuristic is an implementation detail and may change in future versions. If you need precise visibility checking, use another method such as adding an [Area3D] node as a child of a [Camera3D] node and/or [method Vector3.dot]. + [b]Note:[/b] VisibleOnScreenNotifier3D uses the render culling code to determine whether it's visible on screen, which also means that its [member Node3D.visible] must be [code]true[/code] to work correctly. </description> <tutorials> </tutorials> diff --git a/doc/classes/VisualShaderNodeCustom.xml b/doc/classes/VisualShaderNodeCustom.xml index d96969b383..279295a434 100644 --- a/doc/classes/VisualShaderNodeCustom.xml +++ b/doc/classes/VisualShaderNodeCustom.xml @@ -81,7 +81,7 @@ </description> </method> <method name="_get_input_port_type" qualifiers="virtual const"> - <return type="int" /> + <return type="int" enum="VisualShaderNode.PortType" /> <param index="0" name="port" type="int" /> <description> Override this method to define the returned type of each input port of the associated custom node (see [enum VisualShaderNode.PortType] for possible types). @@ -111,7 +111,7 @@ </description> </method> <method name="_get_output_port_type" qualifiers="virtual const"> - <return type="int" /> + <return type="int" enum="VisualShaderNode.PortType" /> <param index="0" name="port" type="int" /> <description> Override this method to define the returned type of each output port of the associated custom node (see [enum VisualShaderNode.PortType] for possible types). @@ -119,7 +119,7 @@ </description> </method> <method name="_get_return_icon_type" qualifiers="virtual const"> - <return type="int" /> + <return type="int" enum="VisualShaderNode.PortType" /> <description> Override this method to define the return icon of the associated custom node in the Visual Shader Editor's members dialog. Defining this method is [b]optional[/b]. If not overridden, no return icon is shown. diff --git a/doc/classes/VoxelGI.xml b/doc/classes/VoxelGI.xml index 394611b78f..e453fbd855 100644 --- a/doc/classes/VoxelGI.xml +++ b/doc/classes/VoxelGI.xml @@ -5,12 +5,13 @@ </brief_description> <description> [VoxelGI]s are used to provide high-quality real-time indirect light and reflections to scenes. They precompute the effect of objects that emit light and the effect of static geometry to simulate the behavior of complex light in real-time. [VoxelGI]s need to be baked before having a visible effect. However, once baked, dynamic objects will receive light from them. Furthermore, lights can be fully dynamic or baked. + [b]Note:[/b] [VoxelGI] is only supported in the Forward+ rendering method, not Mobile or Compatibility. [b]Procedural generation:[/b] [VoxelGI] can be baked in an exported project, which makes it suitable for procedurally generated or user-built levels as long as all the geometry is generated in advance. For games where geometry is generated at any time during gameplay, SDFGI is more suitable (see [member Environment.sdfgi_enabled]). [b]Performance:[/b] [VoxelGI] is relatively demanding on the GPU and is not suited to low-end hardware such as integrated graphics (consider [LightmapGI] instead). To improve performance, adjust [member ProjectSettings.rendering/global_illumination/voxel_gi/quality] and enable [member ProjectSettings.rendering/global_illumination/gi/use_half_resolution] in the Project Settings. To provide a fallback for low-end hardware, consider adding an option to disable [VoxelGI] in your project's options menus. A [VoxelGI] node can be disabled by hiding it. [b]Note:[/b] Meshes should have sufficiently thick walls to avoid light leaks (avoid one-sided walls). For interior levels, enclose your level geometry in a sufficiently large box and bridge the loops to close the mesh. To further prevent light leaks, you can also strategically place temporary [MeshInstance3D] nodes with their [member GeometryInstance3D.gi_mode] set to [constant GeometryInstance3D.GI_MODE_STATIC]. These temporary nodes can then be hidden after baking the [VoxelGI] node. </description> <tutorials> - <link title="GI probes">$DOCS_URL/tutorials/3d/gi_probes.html</link> + <link title="VoxelGI">$DOCS_URL/tutorials/3d/using_voxel_gi.html</link> <link title="Third Person Shooter Demo">https://godotengine.org/asset-library/asset/678</link> </tutorials> <methods> @@ -38,9 +39,9 @@ <member name="data" type="VoxelGIData" setter="set_probe_data" getter="get_probe_data"> The [VoxelGIData] resource that holds the data for this [VoxelGI]. </member> - <member name="extents" type="Vector3" setter="set_extents" getter="get_extents" default="Vector3(10, 10, 10)"> - The size of the area covered by the [VoxelGI]. If you make the extents larger without increasing the subdivisions with [member subdiv], the size of each cell will increase and result in lower detailed lighting. - [b]Note:[/b] Extents are clamped to 1.0 unit or more on each axis. + <member name="size" type="Vector3" setter="set_size" getter="get_size" default="Vector3(20, 20, 20)"> + The size of the area covered by the [VoxelGI]. If you make the size larger without increasing the subdivisions with [member subdiv], the size of each cell will increase and result in lower detailed lighting. + [b]Note:[/b] Size is clamped to 1.0 unit or more on each axis. </member> <member name="subdiv" type="int" setter="set_subdiv" getter="get_subdiv" enum="VoxelGI.Subdiv" default="1"> Number of times to subdivide the grid that the [VoxelGI] operates on. A higher number results in finer detail and thus higher visual quality, while lower numbers result in better performance. diff --git a/doc/classes/VoxelGIData.xml b/doc/classes/VoxelGIData.xml index bd9df18394..541a3bc4a6 100644 --- a/doc/classes/VoxelGIData.xml +++ b/doc/classes/VoxelGIData.xml @@ -26,8 +26,8 @@ <method name="get_bounds" qualifiers="const"> <return type="AABB" /> <description> - Returns the bounds of the baked voxel data as an [AABB], which should match [member VoxelGI.extents] after being baked (which only contains the size as a [Vector3]). - [b]Note:[/b] If the extents were modified without baking the VoxelGI data, then the value of [method get_bounds] and [member VoxelGI.extents] will not match. + Returns the bounds of the baked voxel data as an [AABB], which should match [member VoxelGI.size] after being baked (which only contains the size as a [Vector3]). + [b]Note:[/b] If the size was modified without baking the VoxelGI data, then the value of [method get_bounds] and [member VoxelGI.size] will not match. </description> </method> <method name="get_data_cells" qualifiers="const"> diff --git a/doc/classes/Window.xml b/doc/classes/Window.xml index c4ea11ab66..92050eaa34 100644 --- a/doc/classes/Window.xml +++ b/doc/classes/Window.xml @@ -358,6 +358,7 @@ <description> Popups the [Window] at the center of the current screen, with optionally given minimum size. If the [Window] is embedded, it will be centered in the parent [Viewport] instead. + [b]Note:[/b] Calling it with the default value of [param minsize] is equivalent to calling it with [member size]. </description> </method> <method name="popup_centered_clamped"> @@ -367,6 +368,7 @@ <description> Popups the [Window] centered inside its parent [Window]. [code]fallback_ratio[/code] determines the maximum size of the [Window], in relation to its parent. + [b]Note:[/b] Calling it with the default value of [param minsize] is equivalent to calling it with [member size]. </description> </method> <method name="popup_centered_ratio"> @@ -614,6 +616,12 @@ This signal can be used to handle window closing, e.g. by connecting it to [method hide]. </description> </signal> + <signal name="dpi_changed"> + <description> + Emitted when the [Window]'s DPI changes as a result of OS-level changes (e.g. moving the window from a Retina display to a lower resolution one). + [b]Note:[/b] Only implemented on macOS. + </description> + </signal> <signal name="files_dropped"> <param index="0" name="files" type="PackedStringArray" /> <description> diff --git a/doc/classes/XRInterface.xml b/doc/classes/XRInterface.xml index 05d5eb6673..cdada35970 100644 --- a/doc/classes/XRInterface.xml +++ b/doc/classes/XRInterface.xml @@ -51,6 +51,12 @@ Returns the resolution at which we should render our intermediate results before things like lens distortion are applied by the VR platform. </description> </method> + <method name="get_supported_environment_blend_modes"> + <return type="Array" /> + <description> + Returns the an array of supported environment blend modes, see [enum XRInterface.EnvironmentBlendMode]. + </description> + </method> <method name="get_tracking_status" qualifiers="const"> <return type="int" enum="XRInterface.TrackingStatus" /> <description> @@ -101,6 +107,28 @@ Is [code]true[/code] if this interface supports passthrough. </description> </method> + <method name="set_environment_blend_mode"> + <return type="bool" /> + <param index="0" name="mode" type="int" enum="XRInterface.EnvironmentBlendMode" /> + <description> + Sets the active environment blend mode. + [param mode] is the [enum XRInterface.EnvironmentBlendMode] starting with the next frame. + [b]Note:[/b] Not all runtimes support all environment blend modes, so it is important to check this at startup. For example: + [codeblock] + func _ready(): + var xr_interface : XRInterface = XRServer.find_interface("OpenXR") + if xr_interface and xr_interface.is_initialized(): + var vp : Viewport = get_viewport() + vp.use_xr = true + var acceptable_modes = [ XRInterface.XR_ENV_BLEND_MODE_OPAQUE, XRInterface.XR_ENV_BLEND_MODE_ADDITIVE ] + var modes = xr_interface.get_supported_environment_blend_modes() + for mode in acceptable_modes: + if mode in modes: + xr_interface.set_environment_blend_mode(mode) + break + [/codeblock] + </description> + </method> <method name="set_play_area_mode"> <return type="bool" /> <param index="0" name="mode" type="int" enum="XRInterface.PlayAreaMode" /> @@ -182,7 +210,7 @@ This interface supports quad rendering (not yet supported by Godot). </constant> <constant name="XR_VR" value="8" enum="Capabilities"> - this interface supports VR. + This interface supports VR. </constant> <constant name="XR_AR" value="16" enum="Capabilities"> This interface supports AR (video background and real world tracking). @@ -220,5 +248,14 @@ <constant name="XR_PLAY_AREA_STAGE" value="4" enum="PlayAreaMode"> Same as roomscale but origin point is fixed to the center of the physical space, XRServer.center_on_hmd disabled. </constant> + <constant name="XR_ENV_BLEND_MODE_OPAQUE" value="0" enum="EnvironmentBlendMode"> + Opaque blend mode. This is typically used for VR devices. + </constant> + <constant name="XR_ENV_BLEND_MODE_ADDITIVE" value="1" enum="EnvironmentBlendMode"> + Additive blend mode. This is typically used for AR devices or VR devices with passthrough. + </constant> + <constant name="XR_ENV_BLEND_MODE_ALPHA_BLEND" value="2" enum="EnvironmentBlendMode"> + Alpha blend mode. This is typically used for AR or VR devices with passthrough capabilities. The alpha channel controls how much of the passthrough is visible. Alpha of 0.0 means the passthrough is visible and this pixel works in ADDITIVE mode. Alpha of 1.0 means that the passthrough is not visible and this pixel works in OPAQUE mode. + </constant> </constants> </class> diff --git a/doc/classes/XRInterfaceExtension.xml b/doc/classes/XRInterfaceExtension.xml index 5ad67a7ea9..b74ac1e469 100644 --- a/doc/classes/XRInterfaceExtension.xml +++ b/doc/classes/XRInterfaceExtension.xml @@ -64,7 +64,7 @@ </description> </method> <method name="_get_play_area_mode" qualifiers="virtual const"> - <return type="int" /> + <return type="int" enum="XRInterface.PlayAreaMode" /> <description> Returns the [enum XRInterface.PlayAreaMode] that sets up our play area. </description> @@ -99,7 +99,7 @@ </description> </method> <method name="_get_tracking_status" qualifiers="virtual const"> - <return type="int" /> + <return type="int" enum="XRInterface.TrackingStatus" /> <description> Returns a [enum XRInterface.TrackingStatus] specifying the current status of our tracking. </description> @@ -177,7 +177,7 @@ </method> <method name="_set_play_area_mode" qualifiers="virtual const"> <return type="bool" /> - <param index="0" name="mode" type="int" /> + <param index="0" name="mode" type="int" enum="XRInterface.PlayAreaMode" /> <description> Set the play area mode for this interface. </description> |