diff options
Diffstat (limited to 'doc/classes')
124 files changed, 840 insertions, 244 deletions
diff --git a/doc/classes/@GlobalScope.xml b/doc/classes/@GlobalScope.xml index 55d00b6cf9..66f15f7494 100644 --- a/doc/classes/@GlobalScope.xml +++ b/doc/classes/@GlobalScope.xml @@ -6,7 +6,7 @@ <description> A list of global scope enumerated constants and built-in functions. This is all that resides in the globals, constants regarding error codes, keycodes, property hints, etc. Singletons are also documented here, since they can be accessed from anywhere. - For the entries related to GDScript which can be accessed in any script see [@GDScript]. + For the entries that can only be accessed from scripts written in GDScript, see [@GDScript]. </description> <tutorials> <link title="Random number generation">$DOCS_URL/tutorials/math/random_number_generation.html</link> diff --git a/doc/classes/AABB.xml b/doc/classes/AABB.xml index 188d9652a8..ae2de055cb 100644 --- a/doc/classes/AABB.xml +++ b/doc/classes/AABB.xml @@ -326,13 +326,13 @@ <return type="bool" /> <param index="0" name="aabb" type="AABB" /> <description> - Returns [code]true[/code] if this bounding box and [param aabb] are approximately equal, by calling [method Vector2.is_equal_approx] on the [member position] and the [member size]. + Returns [code]true[/code] if this bounding box and [param aabb] are approximately equal, by calling [method Vector3.is_equal_approx] on the [member position] and the [member size]. </description> </method> <method name="is_finite" qualifiers="const"> <return type="bool" /> <description> - Returns [code]true[/code] if this bounding box's values are finite, by calling [method Vector2.is_finite] on the [member position] and the [member size]. + Returns [code]true[/code] if this bounding box's values are finite, by calling [method Vector3.is_finite] on the [member position] and the [member size]. </description> </method> <method name="merge" qualifiers="const"> diff --git a/doc/classes/AStar2D.xml b/doc/classes/AStar2D.xml index a41da4c318..044e1206e9 100644 --- a/doc/classes/AStar2D.xml +++ b/doc/classes/AStar2D.xml @@ -278,7 +278,7 @@ <return type="void" /> <param index="0" name="num_nodes" type="int" /> <description> - Reserves space internally for [param num_nodes] points, useful if you're adding a known large number of points at once, such as points on a grid. New capacity must be greater or equals to old capacity. + Reserves space internally for [param num_nodes] points. Useful if you're adding a known large number of points at once, such as points on a grid. The new capacity must be greater or equal to the old capacity. </description> </method> <method name="set_point_disabled"> diff --git a/doc/classes/AnimatedSprite2D.xml b/doc/classes/AnimatedSprite2D.xml index 88e543591a..cc1e9117f9 100644 --- a/doc/classes/AnimatedSprite2D.xml +++ b/doc/classes/AnimatedSprite2D.xml @@ -55,7 +55,7 @@ <param index="1" name="progress" type="float" /> <description> Sets [member frame] the [member frame_progress] to the given values. Unlike setting [member frame], this method does not reset the [member frame_progress] to [code]0.0[/code] implicitly. - [b]Example:[/b] Change the animation while keeping the same [member frame] and [member frame_progress]. + [b]Example:[/b] Change the animation while keeping the same [member frame] and [member frame_progress]: [codeblocks] [gdscript] var current_frame = animated_sprite.get_frame() diff --git a/doc/classes/AnimatedSprite3D.xml b/doc/classes/AnimatedSprite3D.xml index a466fc32ac..1b1f58e5f4 100644 --- a/doc/classes/AnimatedSprite3D.xml +++ b/doc/classes/AnimatedSprite3D.xml @@ -54,7 +54,7 @@ <param index="1" name="progress" type="float" /> <description> Sets [member frame] the [member frame_progress] to the given values. Unlike setting [member frame], this method does not reset the [member frame_progress] to [code]0.0[/code] implicitly. - [b]Example:[/b] Change the animation while keeping the same [member frame] and [member frame_progress]. + [b]Example:[/b] Change the animation while keeping the same [member frame] and [member frame_progress]: [codeblocks] [gdscript] var current_frame = animated_sprite.get_frame() diff --git a/doc/classes/AnimationNode.xml b/doc/classes/AnimationNode.xml index 4e093cb887..3b7cd9adad 100644 --- a/doc/classes/AnimationNode.xml +++ b/doc/classes/AnimationNode.xml @@ -63,7 +63,7 @@ When inheriting from [AnimationRootNode], implement this virtual method to return whether the [param parameter] is read-only. Parameters are custom local memory used for your animation nodes, given a resource can be reused in multiple trees. </description> </method> - <method name="_process" qualifiers="virtual const" deprecated="Currently this is mostly useless as there is a lack of many APIs to extend AnimationNode by GDScript. It is planned that a more flexible API using structures will be provided in the future."> + <method name="_process" qualifiers="virtual" deprecated="Currently this is mostly useless as there is a lack of many APIs to extend AnimationNode by GDScript. It is planned that a more flexible API using structures will be provided in the future."> <return type="float" /> <param index="0" name="time" type="float" /> <param index="1" name="seek" type="bool" /> diff --git a/doc/classes/AnimationNodeStateMachineTransition.xml b/doc/classes/AnimationNodeStateMachineTransition.xml index 7bd0bd7e7e..c729eeebba 100644 --- a/doc/classes/AnimationNodeStateMachineTransition.xml +++ b/doc/classes/AnimationNodeStateMachineTransition.xml @@ -26,7 +26,7 @@ Use an expression as a condition for state machine transitions. It is possible to create complex animation advance conditions for switching between states and gives much greater flexibility for creating complex state machines by directly interfacing with the script code. </member> <member name="advance_mode" type="int" setter="set_advance_mode" getter="get_advance_mode" enum="AnimationNodeStateMachineTransition.AdvanceMode" default="1"> - Determines whether the transition should disabled, enabled when using [method AnimationNodeStateMachinePlayback.travel], or traversed automatically if the [member advance_condition] and [member advance_expression] checks are true (if assigned). + Determines whether the transition should be disabled, enabled when using [method AnimationNodeStateMachinePlayback.travel], or traversed automatically if the [member advance_condition] and [member advance_expression] checks are [code]true[/code] (if assigned). </member> <member name="break_loop_at_end" type="bool" setter="set_break_loop_at_end" getter="is_loop_broken_at_end" default="false"> If [code]true[/code], breaks the loop at the end of the loop cycle for transition, even if the animation is looping. @@ -72,7 +72,7 @@ Only use this transition during [method AnimationNodeStateMachinePlayback.travel]. </constant> <constant name="ADVANCE_MODE_AUTO" value="2" enum="AdvanceMode"> - Automatically use this transition if the [member advance_condition] and [member advance_expression] checks are true (if assigned). + Automatically use this transition if the [member advance_condition] and [member advance_expression] checks are [code]true[/code] (if assigned). </constant> </constants> </class> diff --git a/doc/classes/Area2D.xml b/doc/classes/Area2D.xml index 4ad5db2b67..61a103f20d 100644 --- a/doc/classes/Area2D.xml +++ b/doc/classes/Area2D.xml @@ -132,7 +132,7 @@ <description> Emitted when a [Shape2D] of the received [param area] enters a shape of this area. Requires [member monitoring] to be set to [code]true[/code]. [param local_shape_index] and [param area_shape_index] contain indices of the interacting shapes from this area and the other area, respectively. [param area_rid] contains the [RID] of the other area. These values can be used with the [PhysicsServer2D]. - [b]Example of getting the[/b] [CollisionShape2D] [b]node from the shape index:[/b] + [b]Example:[/b] Get the [CollisionShape2D] node from the shape index: [codeblocks] [gdscript] var other_shape_owner = area.shape_find_owner(area_shape_index) @@ -174,7 +174,7 @@ <description> Emitted when a [Shape2D] of the received [param body] enters a shape of this area. [param body] can be a [PhysicsBody2D] or a [TileMap]. [TileMap]s are detected if their [TileSet] has collision shapes configured. Requires [member monitoring] to be set to [code]true[/code]. [param local_shape_index] and [param body_shape_index] contain indices of the interacting shapes from this area and the interacting body, respectively. [param body_rid] contains the [RID] of the body. These values can be used with the [PhysicsServer2D]. - [b]Example of getting the[/b] [CollisionShape2D] [b]node from the shape index:[/b] + [b]Example:[/b] Get the [CollisionShape2D] node from the shape index: [codeblocks] [gdscript] var body_shape_owner = body.shape_find_owner(body_shape_index) diff --git a/doc/classes/Area3D.xml b/doc/classes/Area3D.xml index 8eedd3cdf2..aac98593ff 100644 --- a/doc/classes/Area3D.xml +++ b/doc/classes/Area3D.xml @@ -156,7 +156,7 @@ <description> Emitted when a [Shape3D] of the received [param area] enters a shape of this area. Requires [member monitoring] to be set to [code]true[/code]. [param local_shape_index] and [param area_shape_index] contain indices of the interacting shapes from this area and the other area, respectively. [param area_rid] contains the [RID] of the other area. These values can be used with the [PhysicsServer3D]. - [b]Example of getting the[/b] [CollisionShape3D] [b]node from the shape index:[/b] + [b]Example:[/b] Get the [CollisionShape3D] node from the shape index: [codeblocks] [gdscript] var other_shape_owner = area.shape_find_owner(area_shape_index) @@ -198,7 +198,7 @@ <description> Emitted when a [Shape3D] of the received [param body] enters a shape of this area. [param body] can be a [PhysicsBody3D] or a [GridMap]. [GridMap]s are detected if their [MeshLibrary] has collision shapes configured. Requires [member monitoring] to be set to [code]true[/code]. [param local_shape_index] and [param body_shape_index] contain indices of the interacting shapes from this area and the interacting body, respectively. [param body_rid] contains the [RID] of the body. These values can be used with the [PhysicsServer3D]. - [b]Example of getting the[/b] [CollisionShape3D] [b]node from the shape index:[/b] + [b]Example:[/b] Get the [CollisionShape3D] node from the shape index: [codeblocks] [gdscript] var body_shape_owner = body.shape_find_owner(body_shape_index) diff --git a/doc/classes/AtlasTexture.xml b/doc/classes/AtlasTexture.xml index 45877f4003..287f2cc19a 100644 --- a/doc/classes/AtlasTexture.xml +++ b/doc/classes/AtlasTexture.xml @@ -6,7 +6,7 @@ <description> [Texture2D] resource that draws only part of its [member atlas] texture, as defined by the [member region]. An additional [member margin] can also be set, which is useful for small adjustments. Multiple [AtlasTexture] resources can be cropped from the same [member atlas]. Packing many smaller textures into a singular large texture helps to optimize video memory costs and render calls. - [b]Note:[/b] [AtlasTexture] cannot be used in an [AnimatedTexture], and may not tile properly in nodes such as [TextureRect], when inside other [AtlasTexture] resources. + [b]Note:[/b] [AtlasTexture] cannot be used in an [AnimatedTexture], and will not tile properly in nodes such as [TextureRect] or [Sprite2D]. To tile an [AtlasTexture], modify its [member region] instead. </description> <tutorials> </tutorials> diff --git a/doc/classes/AudioEffectFilter.xml b/doc/classes/AudioEffectFilter.xml index e5c1f4ccf4..18540de736 100644 --- a/doc/classes/AudioEffectFilter.xml +++ b/doc/classes/AudioEffectFilter.xml @@ -14,6 +14,7 @@ Threshold frequency for the filter, in Hz. </member> <member name="db" type="int" setter="set_db" getter="get_db" enum="AudioEffectFilter.FilterDB" default="0"> + Steepness of the cutoff curve in dB per octave, also known as the order of the filter. Higher orders have a more aggressive cutoff. </member> <member name="gain" type="float" setter="set_gain" getter="get_gain" default="1.0"> Gain amount of the frequencies after the filter. @@ -24,12 +25,16 @@ </members> <constants> <constant name="FILTER_6DB" value="0" enum="FilterDB"> + Cutting off at 6dB per octave. </constant> <constant name="FILTER_12DB" value="1" enum="FilterDB"> + Cutting off at 12dB per octave. </constant> <constant name="FILTER_18DB" value="2" enum="FilterDB"> + Cutting off at 18dB per octave. </constant> <constant name="FILTER_24DB" value="3" enum="FilterDB"> + Cutting off at 24dB per octave. </constant> </constants> </class> diff --git a/doc/classes/AudioEffectStereoEnhance.xml b/doc/classes/AudioEffectStereoEnhance.xml index f009bec5bb..459ae3ebc6 100644 --- a/doc/classes/AudioEffectStereoEnhance.xml +++ b/doc/classes/AudioEffectStereoEnhance.xml @@ -11,11 +11,13 @@ </tutorials> <members> <member name="pan_pullout" type="float" setter="set_pan_pullout" getter="get_pan_pullout" default="1.0"> - Values greater than 1.0 increase intensity of any panning on audio passing through this effect, whereas values less than 1.0 will decrease the panning intensity. A value of 0.0 will downmix audio to mono. + Amplifies the difference between stereo channels, increasing or decreasing existing panning. A value of 0.0 will downmix stereo to mono. Does not affect a mono signal. </member> <member name="surround" type="float" setter="set_surround" getter="get_surround" default="0.0"> + Widens sound stage through phase shifting in conjunction with [member time_pullout_ms]. Just pans sound to the left channel if [member time_pullout_ms] is 0. </member> <member name="time_pullout_ms" type="float" setter="set_time_pullout" getter="get_time_pullout" default="0.0"> + Widens sound stage through phase shifting in conjunction with [member surround]. Just delays the right channel if [member surround] is 0. </member> </members> </class> diff --git a/doc/classes/AudioServer.xml b/doc/classes/AudioServer.xml index 6830c632cf..5def0e7baf 100644 --- a/doc/classes/AudioServer.xml +++ b/doc/classes/AudioServer.xml @@ -110,6 +110,12 @@ Returns the volume of the bus at index [param bus_idx] in dB. </description> </method> + <method name="get_driver_name" qualifiers="const"> + <return type="String" /> + <description> + Returns the name of the current audio driver. The default usually depends on the operating system, but may be overridden via the [code]--audio-driver[/code] [url=$DOCS_URL/tutorials/editor/command_line_tutorial.html]command line argument[/url]. [code]--headless[/code] also automatically sets the audio driver to [code]Dummy[/code]. See also [member ProjectSettings.audio/driver/driver]. + </description> + </method> <method name="get_input_device_list"> <return type="PackedStringArray" /> <description> @@ -117,6 +123,12 @@ [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_input_mix_rate" qualifiers="const"> + <return type="float" /> + <description> + Returns the sample rate at the input of the [AudioServer]. + </description> + </method> <method name="get_mix_rate" qualifiers="const"> <return type="float" /> <description> diff --git a/doc/classes/AudioStreamPlayback.xml b/doc/classes/AudioStreamPlayback.xml index 02f3407f79..f01406d0f1 100644 --- a/doc/classes/AudioStreamPlayback.xml +++ b/doc/classes/AudioStreamPlayback.xml @@ -79,12 +79,47 @@ Overridable method. Called whenever the audio stream is mixed if the playback is active and [method AudioServer.set_enable_tagging_used_audio_streams] has been set to [code]true[/code]. Editor plugins may use this method to "tag" the current position along the audio stream and display it in a preview. </description> </method> + <method name="get_loop_count" qualifiers="const"> + <return type="int" /> + <description> + Returns the number of times the stream has looped. + </description> + </method> + <method name="get_playback_position" qualifiers="const"> + <return type="float" /> + <description> + Returns the current position in the stream, in seconds. + </description> + </method> <method name="get_sample_playback" qualifiers="const" experimental=""> <return type="AudioSamplePlayback" /> <description> Returns the [AudioSamplePlayback] associated with this [AudioStreamPlayback] for playing back the audio sample of this stream. </description> </method> + <method name="is_playing" qualifiers="const"> + <return type="bool" /> + <description> + Returns [code]true[/code] if the stream is playing. + </description> + </method> + <method name="mix_audio"> + <return type="PackedVector2Array" /> + <param index="0" name="rate_scale" type="float" /> + <param index="1" name="frames" type="int" /> + <description> + Mixes up to [param frames] of audio from the stream from the current position, at a rate of [param rate_scale], advancing the stream. + Returns a [PackedVector2Array] where each element holds the left and right channel volume levels of each frame. + [b]Note:[/b] Can return fewer frames than requested, make sure to use the size of the return value. + </description> + </method> + <method name="seek"> + <return type="void" /> + <param index="0" name="time" type="float" default="0.0" /> + <description> + Seeks the stream at the given [param time], in seconds. + </description> + </method> <method name="set_sample_playback" experimental=""> <return type="void" /> <param index="0" name="playback_sample" type="AudioSamplePlayback" /> @@ -92,5 +127,18 @@ Associates [AudioSamplePlayback] to this [AudioStreamPlayback] for playing back the audio sample of this stream. </description> </method> + <method name="start"> + <return type="void" /> + <param index="0" name="from_pos" type="float" default="0.0" /> + <description> + Starts the stream from the given [param from_pos], in seconds. + </description> + </method> + <method name="stop"> + <return type="void" /> + <description> + Stops the stream. + </description> + </method> </methods> </class> diff --git a/doc/classes/AudioStreamPlaybackPolyphonic.xml b/doc/classes/AudioStreamPlaybackPolyphonic.xml index f71762d6a5..894c9b2262 100644 --- a/doc/classes/AudioStreamPlaybackPolyphonic.xml +++ b/doc/classes/AudioStreamPlaybackPolyphonic.xml @@ -13,7 +13,7 @@ <return type="bool" /> <param index="0" name="stream" type="int" /> <description> - Return true whether the stream associated with an integer ID is still playing. Check [method play_stream] for information on when this ID becomes invalid. + Returns [code]true[/code] if the stream associated with the given integer ID is still playing. Check [method play_stream] for information on when this ID becomes invalid. </description> </method> <method name="play_stream"> diff --git a/doc/classes/BackBufferCopy.xml b/doc/classes/BackBufferCopy.xml index 23d6bc3851..eb65765312 100644 --- a/doc/classes/BackBufferCopy.xml +++ b/doc/classes/BackBufferCopy.xml @@ -8,6 +8,7 @@ [b]Note:[/b] Since this node inherits from [Node2D] (and not [Control]), anchors and margins won't apply to child [Control]-derived nodes. This can be problematic when resizing the window. To avoid this, add [Control]-derived nodes as [i]siblings[/i] to the [BackBufferCopy] node instead of adding them as children. </description> <tutorials> + <link title="Screen-reading shaders">$DOCS_URL/tutorials/shaders/screen-reading_shaders.html</link> </tutorials> <members> <member name="copy_mode" type="int" setter="set_copy_mode" getter="get_copy_mode" enum="BackBufferCopy.CopyMode" default="1"> diff --git a/doc/classes/BaseMaterial3D.xml b/doc/classes/BaseMaterial3D.xml index fc8af02869..b4a256c54f 100644 --- a/doc/classes/BaseMaterial3D.xml +++ b/doc/classes/BaseMaterial3D.xml @@ -350,7 +350,6 @@ </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, 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. @@ -553,7 +552,7 @@ 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. Not implemented yet (this mode will act like [constant SHADING_MODE_PER_PIXEL]). + The object will be shaded per vertex. Useful when you want cheaper shaders and do not care about visual quality. </constant> <constant name="SHADING_MODE_MAX" value="3" enum="ShadingMode"> Represents the size of the [enum ShadingMode] enum. diff --git a/doc/classes/Basis.xml b/doc/classes/Basis.xml index 322d2ab9d4..59c1195b00 100644 --- a/doc/classes/Basis.xml +++ b/doc/classes/Basis.xml @@ -25,6 +25,7 @@ <return type="Basis" /> <description> Constructs a [Basis] identical to the [constant IDENTITY]. + [b]Note:[/b] In C#, this constructs a [Basis] with all of its components set to [constant Vector3.ZERO]. </description> </constructor> <constructor name="Basis"> @@ -303,7 +304,7 @@ <param index="1" name="weight" type="float" /> <description> Performs a spherical-linear interpolation with the [param to] basis, given a [param weight]. Both this basis and [param to] should represent a rotation. - [b]Example:[/b] Smoothly rotate a [Node3D] to the target basis over time, with a [Tween]. + [b]Example:[/b] Smoothly rotate a [Node3D] to the target basis over time, with a [Tween]: [codeblock] var start_basis = Basis.IDENTITY var target_basis = Basis.IDENTITY.rotated(Vector3.UP, TAU / 2) diff --git a/doc/classes/Button.xml b/doc/classes/Button.xml index 68fb918904..5b3f86c9f5 100644 --- a/doc/classes/Button.xml +++ b/doc/classes/Button.xml @@ -5,13 +5,13 @@ </brief_description> <description> [Button] is the standard themed button. It can contain text and an icon, and it will display them according to the current [Theme]. - [b]Example of creating a button and assigning an action when pressed by code:[/b] + [b]Example:[/b] Create a button and connect a method that will be called when the button is pressed: [codeblocks] [gdscript] func _ready(): var button = Button.new() button.text = "Click me" - button.pressed.connect(self._button_pressed) + button.pressed.connect(_button_pressed) add_child(button) func _button_pressed(): @@ -33,7 +33,7 @@ [/csharp] [/codeblocks] See also [BaseButton] which contains common properties and methods associated with this node. - [b]Note:[/b] Buttons do not interpret touch input and therefore don't support multitouch, since mouse emulation can only press one button at a given time. Use [TouchScreenButton] for buttons that trigger gameplay movement or actions. + [b]Note:[/b] Buttons do not detect touch input and therefore don't support multitouch, since mouse emulation can only press one button at a given time. Use [TouchScreenButton] for buttons that trigger gameplay movement or actions. </description> <tutorials> <link title="2D Dodge The Creeps Demo">https://godotengine.org/asset-library/asset/2712</link> @@ -127,6 +127,9 @@ <theme_item name="icon_max_width" data_type="constant" type="int" default="0"> The maximum allowed width of the [Button]'s icon. This limit is applied on top of the default size of the icon, or its expanded size if [member expand_icon] is [code]true[/code]. The height is adjusted according to the icon's ratio. If the button has additional icons (e.g. [CheckBox]), they will also be limited. </theme_item> + <theme_item name="line_spacing" data_type="constant" type="int" default="0"> + Additional vertical spacing between lines (in pixels), spacing is added to line descent. This value can be negative. + </theme_item> <theme_item name="outline_size" data_type="constant" type="int" default="0"> The size of the text outline. [b]Note:[/b] If using a font with [member FontFile.multichannel_signed_distance_field] enabled, its [member FontFile.msdf_pixel_range] must be set to at least [i]twice[/i] the value of [theme_item outline_size] for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended. diff --git a/doc/classes/CPUParticles2D.xml b/doc/classes/CPUParticles2D.xml index 99411c73aa..e8fa13fd0d 100644 --- a/doc/classes/CPUParticles2D.xml +++ b/doc/classes/CPUParticles2D.xml @@ -43,7 +43,7 @@ <return type="bool" /> <param index="0" name="particle_flag" type="int" enum="CPUParticles2D.ParticleFlags" /> <description> - Returns the enabled state of the given flag (see [enum ParticleFlags] for options). + Returns the enabled state of the given particle flag (see [enum ParticleFlags] for options). </description> </method> <method name="restart"> diff --git a/doc/classes/CallbackTweener.xml b/doc/classes/CallbackTweener.xml index afb9e70601..3a617d2a43 100644 --- a/doc/classes/CallbackTweener.xml +++ b/doc/classes/CallbackTweener.xml @@ -16,7 +16,7 @@ <param index="0" name="delay" type="float" /> <description> Makes the callback call delayed by given time in seconds. - [b]Example:[/b] Call [method Node.queue_free] after 2 seconds. + [b]Example:[/b] Call [method Node.queue_free] after 2 seconds: [codeblock] var tween = get_tree().create_tween() tween.tween_callback(queue_free).set_delay(2) diff --git a/doc/classes/CameraAttributes.xml b/doc/classes/CameraAttributes.xml index 1b1365eed4..cb5a7778de 100644 --- a/doc/classes/CameraAttributes.xml +++ b/doc/classes/CameraAttributes.xml @@ -25,7 +25,9 @@ Multiplier for the exposure amount. A higher value results in a brighter image. </member> <member name="exposure_sensitivity" type="float" setter="set_exposure_sensitivity" getter="get_exposure_sensitivity" default="100.0"> - Sensitivity of camera sensors, measured in ISO. A higher sensitivity results in a brighter image. Only available when [member ProjectSettings.rendering/lights_and_shadows/use_physical_light_units] is enabled. When [member auto_exposure_enabled] this can be used as a method of exposure compensation, doubling the value will increase the exposure value (measured in EV100) by 1 stop. + Sensitivity of camera sensors, measured in ISO. A higher sensitivity results in a brighter image. + If [member auto_exposure_enabled] is [code]true[/code], this can be used as a method of exposure compensation, doubling the value will increase the exposure value (measured in EV100) by 1 stop. + [b]Note:[/b] Only available when [member ProjectSettings.rendering/lights_and_shadows/use_physical_light_units] is enabled. </member> </members> </class> diff --git a/doc/classes/CameraFeed.xml b/doc/classes/CameraFeed.xml index 2b6db13906..6748fdb95b 100644 --- a/doc/classes/CameraFeed.xml +++ b/doc/classes/CameraFeed.xml @@ -34,6 +34,21 @@ Returns the position of camera on the device. </description> </method> + <method name="get_texture_tex_id"> + <return type="int" /> + <param index="0" name="feed_image_type" type="int" enum="CameraServer.FeedImage" /> + <description> + Returns the texture backend ID (usable by some external libraries that need a handle to a texture to write data). + </description> + </method> + <method name="set_external"> + <return type="void" /> + <param index="0" name="width" type="int" /> + <param index="1" name="height" type="int" /> + <description> + Sets the feed as external feed provided by another library. + </description> + </method> <method name="set_format"> <return type="bool" /> <param index="0" name="index" type="int" /> @@ -110,6 +125,9 @@ <constant name="FEED_YCBCR_SEP" value="3" enum="FeedDataType"> Feed supplies separate Y and CbCr images that need to be combined and converted to RGB. </constant> + <constant name="FEED_EXTERNAL" value="4" enum="FeedDataType"> + Feed supplies external image. + </constant> <constant name="FEED_UNSPECIFIED" value="0" enum="FeedPosition"> Unspecified position. </constant> diff --git a/doc/classes/CanvasItem.xml b/doc/classes/CanvasItem.xml index bc17c8b008..4e6535f3ca 100644 --- a/doc/classes/CanvasItem.xml +++ b/doc/classes/CanvasItem.xml @@ -333,7 +333,7 @@ <param index="9" name="orientation" type="int" enum="TextServer.Orientation" default="0" /> <description> Draws [param text] using the specified [param font] at the [param pos] (bottom-left corner using the baseline of the font). The text will have its color multiplied by [param modulate]. If [param width] is greater than or equal to 0, the text will be clipped if it exceeds the specified width. - [b]Example using the default project font:[/b] + [b]Example:[/b] Draw "Hello world", using the project's default font: [codeblocks] [gdscript] # If using this method in a script that redraws constantly, move the @@ -533,9 +533,13 @@ </method> <method name="make_canvas_position_local" qualifiers="const"> <return type="Vector2" /> - <param index="0" name="screen_point" type="Vector2" /> + <param index="0" name="viewport_point" type="Vector2" /> <description> - Assigns [param screen_point] as this node's new local transform. + Transforms [param viewport_point] from the viewport's coordinates to this node's local coordinates. + For the opposite operation, use [method get_global_transform_with_canvas]. + [codeblock] + var viewport_point = get_global_transform_with_canvas() * local_point + [/codeblock] </description> </method> <method name="make_input_local" qualifiers="const"> @@ -590,6 +594,7 @@ <members> <member name="clip_children" type="int" setter="set_clip_children_mode" getter="get_clip_children_mode" enum="CanvasItem.ClipChildrenMode" default="0"> Allows the current node to clip child nodes, essentially acting as a mask. + [b]Note:[/b] Clipping nodes cannot be nested or placed within [CanvasGroup]s. If an ancestor of this node clips its children or is a [CanvasGroup], then this node's clip mode should be set to [constant CLIP_CHILDREN_DISABLED] to avoid unexpected behavior. </member> <member name="light_mask" type="int" setter="set_light_mask" getter="get_light_mask" default="1"> The rendering layers in which this [CanvasItem] responds to [Light2D] nodes. diff --git a/doc/classes/CharFXTransform.xml b/doc/classes/CharFXTransform.xml index 403033f85d..28f5d38ee4 100644 --- a/doc/classes/CharFXTransform.xml +++ b/doc/classes/CharFXTransform.xml @@ -8,7 +8,6 @@ </description> <tutorials> <link title="BBCode in RichTextLabel">$DOCS_URL/tutorials/ui/bbcode_in_richtextlabel.html</link> - <link title="RichTextEffect test project (third-party)">https://github.com/Eoin-ONeill-Yokai/Godot-Rich-Text-Effect-Test-Project</link> </tutorials> <members> <member name="color" type="Color" setter="set_color" getter="get_color" default="Color(0, 0, 0, 1)" keywords="colour"> diff --git a/doc/classes/CharacterBody2D.xml b/doc/classes/CharacterBody2D.xml index ede4d63cfc..30438be18b 100644 --- a/doc/classes/CharacterBody2D.xml +++ b/doc/classes/CharacterBody2D.xml @@ -69,7 +69,7 @@ <param index="0" name="slide_idx" type="int" /> <description> Returns a [KinematicCollision2D], which contains information about a collision that occurred during the last call to [method move_and_slide]. Since the body can collide several times in a single call to [method move_and_slide], you must specify the index of the collision in the range 0 to ([method get_slide_collision_count] - 1). - [b]Example usage:[/b] + [b]Example:[/b] Iterate through the collisions with a [code]for[/code] loop: [codeblocks] [gdscript] for i in get_slide_collision_count(): diff --git a/doc/classes/ClassDB.xml b/doc/classes/ClassDB.xml index d1b666097c..d01a308e32 100644 --- a/doc/classes/ClassDB.xml +++ b/doc/classes/ClassDB.xml @@ -16,7 +16,7 @@ Returns [code]true[/code] if objects can be instantiated from the specified [param class], otherwise returns [code]false[/code]. </description> </method> - <method name="class_call_static_method" qualifiers="vararg"> + <method name="class_call_static" qualifiers="vararg"> <return type="Variant" /> <param index="0" name="class" type="StringName" /> <param index="1" name="method" type="StringName" /> diff --git a/doc/classes/Color.xml b/doc/classes/Color.xml index 9fe42fff90..546d90fa3c 100644 --- a/doc/classes/Color.xml +++ b/doc/classes/Color.xml @@ -19,7 +19,7 @@ <return type="Color" /> <description> Constructs a default [Color] from opaque black. This is the same as [constant BLACK]. - [b]Note:[/b] in C#, constructs an empty color with all of its components set to [code]0.0[/code] (transparent black). + [b]Note:[/b] In C#, this constructs a [Color] with all of its components set to [code]0.0[/code] (transparent black). </description> </constructor> <constructor name="Color"> @@ -495,6 +495,15 @@ <member name="h" type="float" setter="" getter="" default="0.0"> The HSV hue of this color, on the range 0 to 1. </member> + <member name="ok_hsl_h" type="float" setter="" getter="" default="0.0"> + The OKHSL hue of this color, on the range 0 to 1. + </member> + <member name="ok_hsl_l" type="float" setter="" getter="" default="0.0"> + The OKHSL lightness of this color, on the range 0 to 1. + </member> + <member name="ok_hsl_s" type="float" setter="" getter="" default="0.0"> + The OKHSL saturation of this color, on the range 0 to 1. + </member> <member name="r" type="float" setter="" getter="" default="0.0"> The color's red component, typically on the range of 0 to 1. </member> diff --git a/doc/classes/Control.xml b/doc/classes/Control.xml index 516b01bd7d..80c5f8d96d 100644 --- a/doc/classes/Control.xml +++ b/doc/classes/Control.xml @@ -65,7 +65,7 @@ [csharp] public override bool _CanDropData(Vector2 atPosition, Variant data) { - return data.VariantType == Variant.Type.Dictionary && dict.AsGodotDictionary().ContainsKey("color"); + return data.VariantType == Variant.Type.Dictionary && data.AsGodotDictionary().ContainsKey("color"); } public override void _DropData(Vector2 atPosition, Variant data) @@ -120,8 +120,8 @@ <return type="void" /> <param index="0" name="event" type="InputEvent" /> <description> - Virtual method to be implemented by the user. Use this method to process and accept inputs on UI elements. See [method accept_event]. - [b]Example usage for clicking a control:[/b] + Virtual method to be implemented by the user. Override this method to handle and accept inputs on UI elements. See also [method accept_event]. + [b]Example:[/b] Click on the control to print a message: [codeblocks] [gdscript] func _gui_input(event): @@ -142,13 +142,13 @@ } [/csharp] [/codeblocks] - The event won't trigger if: - * clicking outside the control (see [method _has_point]); - * control has [member mouse_filter] set to [constant MOUSE_FILTER_IGNORE]; - * control is obstructed by another [Control] on top of it, which doesn't have [member mouse_filter] set to [constant MOUSE_FILTER_IGNORE]; - * control's parent has [member mouse_filter] set to [constant MOUSE_FILTER_STOP] or has accepted the event; - * it happens outside the parent's rectangle and the parent has either [member clip_contents] enabled. - [b]Note:[/b] Event position is relative to the control origin. + If the [param event] inherits [InputEventMouse], this method will [b]not[/b] be called when: + - the control's [member mouse_filter] is set to [constant MOUSE_FILTER_IGNORE]; + - the control is obstructed by another control on top, that doesn't have [member mouse_filter] set to [constant MOUSE_FILTER_IGNORE]; + - the control's parent has [member mouse_filter] set to [constant MOUSE_FILTER_STOP] or has accepted the event; + - the control's parent has [member clip_contents] enabled and the [param event]'s position is outside the parent's rectangle; + - the [param event]'s position is outside the control (see [method _has_point]). + [b]Note:[/b] The [param event]'s position is relative to this control's origin. </description> </method> <method name="_has_point" qualifiers="virtual const"> @@ -169,7 +169,7 @@ The returned node will be added as child to a [PopupPanel], so you should only provide the contents of that panel. That [PopupPanel] can be themed using [method Theme.set_stylebox] for the type [code]"TooltipPanel"[/code] (see [member tooltip_text] for an example). [b]Note:[/b] The tooltip is shrunk to minimal size. If you want to ensure it's fully visible, you might want to set its [member custom_minimum_size] to some non-zero value. [b]Note:[/b] The node (and any relevant children) should be [member CanvasItem.visible] when returned, otherwise, the viewport that instantiates it will not be able to calculate its minimum size reliably. - [b]Example of usage with a custom-constructed node:[/b] + [b]Example:[/b] Use a constructed node as a tooltip: [codeblocks] [gdscript] func _make_custom_tooltip(for_text): @@ -186,7 +186,7 @@ } [/csharp] [/codeblocks] - [b]Example of usage with a custom scene instance:[/b] + [b]Example:[/b] Usa a scene instance as a tooltip: [codeblocks] [gdscript] func _make_custom_tooltip(for_text): @@ -228,7 +228,7 @@ <description> Creates a local override for a theme [Color] with the specified [param name]. Local overrides always take precedence when fetching theme items for the control. An override can be removed with [method remove_theme_color_override]. See also [method get_theme_color]. - [b]Example of overriding a label's color and resetting it later:[/b] + [b]Example:[/b] Override a [Label]'s color and reset it later: [codeblocks] [gdscript] # Given the child Label node "MyLabel", override its font color with a custom value. @@ -292,10 +292,10 @@ <description> Creates a local override for a theme [StyleBox] with the specified [param name]. Local overrides always take precedence when fetching theme items for the control. An override can be removed with [method remove_theme_stylebox_override]. See also [method get_theme_stylebox]. - [b]Example of modifying a property in a StyleBox by duplicating it:[/b] + [b]Example:[/b] Modify a property in a [StyleBox] by duplicating it: [codeblocks] [gdscript] - # The snippet below assumes the child node MyButton has a StyleBoxFlat assigned. + # The snippet below assumes the child node "MyButton" has a StyleBoxFlat assigned. # Resources are shared across instances, so we need to duplicate it # to avoid modifying the appearance of all other buttons. var new_stylebox_normal = $MyButton.get_theme_stylebox("normal").duplicate() @@ -306,7 +306,7 @@ $MyButton.remove_theme_stylebox_override("normal") [/gdscript] [csharp] - // The snippet below assumes the child node MyButton has a StyleBoxFlat assigned. + // The snippet below assumes the child node "MyButton" has a StyleBoxFlat assigned. // Resources are shared across instances, so we need to duplicate it // to avoid modifying the appearance of all other buttons. StyleBoxFlat newStyleboxNormal = GetNode<Button>("MyButton").GetThemeStylebox("normal").Duplicate() as StyleBoxFlat; @@ -446,7 +446,7 @@ <description> Returns the position of this [Control] in global screen coordinates (i.e. taking window position into account). Mostly useful for editor plugins. Equals to [member global_position] if the window is embedded (see [member Viewport.gui_embed_subwindows]). - [b]Example usage for showing a popup:[/b] + [b]Example:[/b] Show a popup at the mouse position: [codeblock] popup_menu.position = get_screen_position() + get_local_mouse_position() popup_menu.reset_size() @@ -809,9 +809,11 @@ <param index="1" name="can_drop_func" type="Callable" /> <param index="2" name="drop_func" type="Callable" /> <description> - Forwards the handling of this control's [method _get_drag_data], [method _can_drop_data] and [method _drop_data] virtual functions to delegate callables. - For each argument, if not empty, the delegate callable is used, otherwise the local (virtual) function is used. - The function format for each callable should be exactly the same as the virtual functions described above. + Sets the given callables to be used instead of the control's own drag-and-drop virtual methods. If a callable is empty, its respective virtual method is used as normal. + The arguments for each callable should be exactly the same as their respective virtual methods, which would be: + - [param drag_func] corresponds to [method _get_drag_data] and requires a [Vector2]; + - [param can_drop_func] corresponds to [method _can_drop_data] and requires both a [Vector2] and a [Variant]; + - [param drop_func] corresponds to [method _drop_data] and requires both a [Vector2] and a [Variant]. </description> </method> <method name="set_drag_preview"> @@ -993,8 +995,9 @@ Controls whether the control will be able to receive mouse button input events through [method _gui_input] and how these events should be handled. Also controls whether the control can receive the [signal mouse_entered], and [signal mouse_exited] signals. See the constants to learn what each does. </member> <member name="mouse_force_pass_scroll_events" type="bool" setter="set_force_pass_scroll_events" getter="is_force_pass_scroll_events" default="true"> - When enabled, scroll wheel events processed by [method _gui_input] will be passed to the parent control even if [member mouse_filter] is set to [constant MOUSE_FILTER_STOP]. As it defaults to true, this allows nested scrollable containers to work out of the box. + When enabled, scroll wheel events processed by [method _gui_input] will be passed to the parent control even if [member mouse_filter] is set to [constant MOUSE_FILTER_STOP]. You should disable it on the root of your UI if you do not want scroll events to go to the [method Node._unhandled_input] processing. + [b]Note:[/b] Because this property defaults to [code]true[/code], this allows nested scrollable containers to work out of the box. </member> <member name="offset_bottom" type="float" setter="set_offset" getter="get_offset" default="0.0"> Distance between the node's bottom edge and its parent control, based on [member anchor_bottom]. @@ -1059,7 +1062,7 @@ </member> <member name="tooltip_auto_translate_mode" type="int" setter="set_tooltip_auto_translate_mode" getter="get_tooltip_auto_translate_mode" enum="Node.AutoTranslateMode" default="0"> Defines if tooltip text should automatically change to its translated version depending on the current locale. Uses the same auto translate mode as this control when set to [constant Node.AUTO_TRANSLATE_MODE_INHERIT]. - [b]Note:[/b] When the tooltip is customized using [method _make_custom_tooltip], this auto translate mode is applied automatically to the returned control. + [b]Note:[/b] Tooltips customized using [method _make_custom_tooltip] do not use this auto translate mode automatically. </member> <member name="tooltip_text" type="String" setter="set_tooltip_text" getter="get_tooltip_text" default=""""> The default tooltip text. The tooltip appears when the user's mouse cursor stays idle over this control for a few moments, provided that the [member mouse_filter] property is not [constant MOUSE_FILTER_IGNORE]. The time required for the tooltip to appear can be changed with the [member ProjectSettings.gui/timers/tooltip_delay_sec] option. See also [method get_tooltip]. diff --git a/doc/classes/Cubemap.xml b/doc/classes/Cubemap.xml index b7da3c4ec6..8a850920f7 100644 --- a/doc/classes/Cubemap.xml +++ b/doc/classes/Cubemap.xml @@ -6,8 +6,27 @@ <description> A cubemap is made of 6 textures organized in layers. They are typically used for faking reflections in 3D rendering (see [ReflectionProbe]). It can be used to make an object look as if it's reflecting its surroundings. This usually delivers much better performance than other reflection methods. This resource is typically used as a uniform in custom shaders. Few core Godot methods make use of [Cubemap] resources. - To create such a texture file yourself, reimport your image files using the Godot Editor import presets. - [b]Note:[/b] Godot doesn't support using cubemaps in a [PanoramaSkyMaterial]. You can use [url=https://danilw.github.io/GLSL-howto/cubemap_to_panorama_js/cubemap_to_panorama.html]this tool[/url] to convert a cubemap to an equirectangular sky map. + To create such a texture file yourself, reimport your image files using the Godot Editor import presets. The expected image order is X+, X-, Y+, Y-, Z+, Z- (in Godot's coordinate system, so Y+ is "up" and Z- is "forward"). You can use one of the following templates as a base: + - [url=https://raw.githubusercontent.com/godotengine/godot-docs/master/img/cubemap_template_2x3.webp]2×3 cubemap template (default layout option)[/url] + - [url=https://raw.githubusercontent.com/godotengine/godot-docs/master/img/cubemap_template_3x2.webp]3×2 cubemap template[/url] + - [url=https://raw.githubusercontent.com/godotengine/godot-docs/master/img/cubemap_template_1x6.webp]1×6 cubemap template[/url] + - [url=https://raw.githubusercontent.com/godotengine/godot-docs/master/img/cubemap_template_6x1.webp]6×1 cubemap template[/url] + [b]Note:[/b] Godot doesn't support using cubemaps in a [PanoramaSkyMaterial]. To use a cubemap as a skybox, convert the default [PanoramaSkyMaterial] to a [ShaderMaterial] using the [b]Convert to ShaderMaterial[/b] resource dropdown option, then replace its code with the following: + [codeblock lang=text] + shader_type sky; + + uniform samplerCube source_panorama : filter_linear, source_color, hint_default_black; + uniform float exposure : hint_range(0, 128) = 1.0; + + void sky() { + // If importing a cubemap from another engine, you may need to flip one of the `EYEDIR` components below + // by replacing it with `-EYEDIR`. + vec3 eyedir = vec3(EYEDIR.x, EYEDIR.y, EYEDIR.z); + COLOR = texture(source_panorama, eyedir).rgb * exposure; + } + [/codeblock] + After replacing the shader code and saving, specify the imported Cubemap resource in the Shader Parameters section of the ShaderMaterial in the inspector. + Alternatively, you can use [url=https://danilw.github.io/GLSL-howto/cubemap_to_panorama_js/cubemap_to_panorama.html]this tool[/url] to convert a cubemap to an equirectangular sky map and use [PanoramaSkyMaterial] as usual. </description> <tutorials> </tutorials> diff --git a/doc/classes/DirAccess.xml b/doc/classes/DirAccess.xml index 9c71addf0c..dcd2d527e2 100644 --- a/doc/classes/DirAccess.xml +++ b/doc/classes/DirAccess.xml @@ -60,6 +60,7 @@ } [/csharp] [/codeblocks] + Keep in mind that file names may change or be remapped after export. If you want to see the actual resource file list as it appears in the editor, use [method ResourceLoader.list_directory] instead. </description> <tutorials> <link title="File system">$DOCS_URL/tutorials/scripting/filesystem.html</link> diff --git a/doc/classes/DisplayServer.xml b/doc/classes/DisplayServer.xml index 91151ae869..dafa86d42e 100644 --- a/doc/classes/DisplayServer.xml +++ b/doc/classes/DisplayServer.xml @@ -105,7 +105,7 @@ <param index="3" name="callback" type="Callable" /> <description> Shows a text input dialog which uses the operating system's native look-and-feel. [param callback] should accept a single [String] parameter which contains the text field's contents. - [b]Note:[/b] This method is implemented if the display server has the [constant FEATURE_NATIVE_DIALOG_INPUT] feature. Supported platforms include macOS and Windows. + [b]Note:[/b] This method is implemented if the display server has the [constant FEATURE_NATIVE_DIALOG_INPUT] feature. Supported platforms include macOS, Windows, and Android. </description> </method> <method name="dialog_show"> @@ -139,11 +139,12 @@ <description> Displays OS native dialog for selecting files or directories in the file system. Each filter string in the [param filters] array should be formatted like this: [code]*.txt,*.doc;Text Files[/code]. The description text of the filter is optional and can be omitted. See also [member FileDialog.filters]. - Callbacks have the following arguments: [code]status: bool, selected_paths: PackedStringArray, selected_filter_index: int[/code]. - [b]Note:[/b] This method is implemented if the display server has the [constant FEATURE_NATIVE_DIALOG_FILE] feature. Supported platforms include Linux (X11/Wayland), Windows, and macOS. + Callbacks have the following arguments: [code]status: bool, selected_paths: PackedStringArray, selected_filter_index: int[/code]. [b]On Android,[/b] callback argument [code]selected_filter_index[/code] is always zero. + [b]Note:[/b] This method is implemented if the display server has the [constant FEATURE_NATIVE_DIALOG_FILE] feature. Supported platforms include Linux (X11/Wayland), Windows, macOS, and Android. [b]Note:[/b] [param current_directory] might be ignored. - [b]Note:[/b] On Linux, [param show_hidden] is ignored. - [b]Note:[/b] On macOS, native file dialogs have no title. + [b]Note:[/b] On Android, the filter strings in the [param filters] array should be specified using MIME types, for example:[code]image/png, image/jpeg"[/code]. Additionally, the [param mode] [constant FILE_DIALOG_MODE_OPEN_ANY] is not supported on Android. + [b]Note:[/b] On Android and Linux, [param show_hidden] is ignored. + [b]Note:[/b] On Android and macOS, native file dialogs have no title. [b]Note:[/b] On macOS, sandboxed apps will save security-scoped bookmarks to retain access to the opened folders across multiple sessions. Use [method OS.get_granted_permissions] to get a list of saved bookmarks. </description> </method> @@ -166,7 +167,7 @@ - [code]"values"[/code] - [PackedStringArray] of values. If empty, boolean option (check box) is used. - [code]"default"[/code] - default selected option index ([int]) or default boolean value ([bool]). Callbacks have the following arguments: [code]status: bool, selected_paths: PackedStringArray, selected_filter_index: int, selected_option: Dictionary[/code]. - [b]Note:[/b] This method is implemented if the display server has the [constant FEATURE_NATIVE_DIALOG_FILE] feature. Supported platforms include Linux (X11/Wayland), Windows, and macOS. + [b]Note:[/b] This method is implemented if the display server has the [constant FEATURE_NATIVE_DIALOG_FILE_EXTRA] feature. Supported platforms include Linux (X11/Wayland), Windows, and macOS. [b]Note:[/b] [param current_directory] might be ignored. [b]Note:[/b] On Linux (X11), [param show_hidden] is ignored. [b]Note:[/b] On macOS, native file dialogs have no title. @@ -184,7 +185,7 @@ <return type="Color" /> <description> Returns OS theme accent color. Returns [code]Color(0, 0, 0, 0)[/code], if accent color is unknown. - [b]Note:[/b] This method is implemented on macOS and Windows. + [b]Note:[/b] This method is implemented on macOS, Windows, and Android. </description> </method> <method name="get_base_color" qualifiers="const"> @@ -1683,6 +1684,7 @@ <param index="1" name="window_id" type="int" default="0" /> <description> Sets window mode for the given window to [param mode]. See [enum WindowMode] for possible values and how each mode behaves. + [b]Note:[/b] On Android, setting it to [constant WINDOW_MODE_FULLSCREEN] or [constant WINDOW_MODE_EXCLUSIVE_FULLSCREEN] will enable immersive mode. [b]Note:[/b] Setting the window to full screen forcibly sets the borderless flag to [code]true[/code], so make sure to set it back to [code]false[/code] when not wanted. </description> </method> @@ -1888,7 +1890,10 @@ Display server supports spawning text input dialogs using the operating system's native look-and-feel. See [method dialog_input_text]. [b]Windows, macOS[/b] </constant> <constant name="FEATURE_NATIVE_DIALOG_FILE" value="25" enum="Feature"> - Display server supports spawning dialogs for selecting files or directories using the operating system's native look-and-feel. See [method file_dialog_show] and [method file_dialog_with_options_show]. [b]Windows, macOS, Linux (X11/Wayland)[/b] + Display server supports spawning dialogs for selecting files or directories using the operating system's native look-and-feel. See [method file_dialog_show]. [b]Windows, macOS, Linux (X11/Wayland), Android[/b] + </constant> + <constant name="FEATURE_NATIVE_DIALOG_FILE_EXTRA" value="26" enum="Feature"> + The display server supports all features of [constant FEATURE_NATIVE_DIALOG_FILE], with the added functionality of Options and native dialog file access to [code]res://[/code] and [code]user://[/code] paths. See [method file_dialog_show] and [method file_dialog_with_options_show]. [b]Windows, macOS, Linux (X11/Wayland)[/b] </constant> <constant name="MOUSE_MODE_VISIBLE" value="0" enum="MouseMode"> Makes the mouse cursor visible if it is hidden. @@ -2058,6 +2063,7 @@ <constant name="WINDOW_MODE_FULLSCREEN" value="3" enum="WindowMode"> Full screen mode with full multi-window support. Full screen window covers the entire display area of a screen and has no decorations. The display's video mode is not changed. + [b]On Android:[/b] This enables immersive mode. [b]On Windows:[/b] Multi-window full-screen mode has a 1px border of the [member ProjectSettings.rendering/environment/defaults/default_clear_color] color. [b]On macOS:[/b] A new desktop is used to display the running project. [b]Note:[/b] Regardless of the platform, enabling full screen will change the window size to match the monitor's size. Therefore, make sure your project supports [url=$DOCS_URL/tutorials/rendering/multiple_resolutions.html]multiple resolutions[/url] when enabling full screen mode. @@ -2065,6 +2071,7 @@ <constant name="WINDOW_MODE_EXCLUSIVE_FULLSCREEN" value="4" enum="WindowMode"> A single window full screen mode. This mode has less overhead, but only one window can be open on a given screen at a time (opening a child window or application switching will trigger a full screen transition). Full screen window covers the entire display area of a screen and has no border or decorations. The display's video mode is not changed. + [b]On Android:[/b] This enables immersive mode. [b]On Windows:[/b] Depending on video driver, full screen transition might cause screens to go black for a moment. [b]On macOS:[/b] A new desktop is used to display the running project. Exclusive full screen mode prevents Dock and Menu from showing up when the mouse pointer is hovering the edge of the screen. [b]On Linux (X11):[/b] Exclusive full screen mode bypasses compositor. @@ -2149,12 +2156,14 @@ <constant name="DISPLAY_HANDLE" value="0" enum="HandleType"> Display handle: - Linux (X11): [code]X11::Display*[/code] for the display. + - Linux (Wayland): [code]wl_display[/code] for the display. - Android: [code]EGLDisplay[/code] for the display. </constant> <constant name="WINDOW_HANDLE" value="1" enum="HandleType"> Window handle: - Windows: [code]HWND[/code] for the window. - Linux (X11): [code]X11::Window*[/code] for the window. + - Linux (Wayland): [code]wl_surface[/code] for the window. - macOS: [code]NSWindow*[/code] for the window. - iOS: [code]UIViewController*[/code] for the view controller. - Android: [code]jObject[/code] for the activity. @@ -2169,9 +2178,20 @@ OpenGL context (only with the GL Compatibility renderer): - Windows: [code]HGLRC[/code] for the window (native GL), or [code]EGLContext[/code] for the window (ANGLE). - Linux (X11): [code]GLXContext*[/code] for the window. + - Linux (Wayland): [code]EGLContext[/code] for the window. - macOS: [code]NSOpenGLContext*[/code] for the window (native GL), or [code]EGLContext[/code] for the window (ANGLE). - Android: [code]EGLContext[/code] for the window. </constant> + <constant name="EGL_DISPLAY" value="4" enum="HandleType"> + - Windows: [code]EGLDisplay[/code] for the window (ANGLE). + - macOS: [code]EGLDisplay[/code] for the window (ANGLE). + - Linux (Wayland): [code]EGLDisplay[/code] for the window. + </constant> + <constant name="EGL_CONFIG" value="5" enum="HandleType"> + - Windows: [code]EGLConfig[/code] for the window (ANGLE). + - macOS: [code]EGLConfig[/code] for the window (ANGLE). + - Linux (Wayland): [code]EGLConfig[/code] for the window. + </constant> <constant name="TTS_UTTERANCE_STARTED" value="0" enum="TTSUtteranceEvent"> Utterance has begun to be spoken. </constant> diff --git a/doc/classes/EditorDebuggerPlugin.xml b/doc/classes/EditorDebuggerPlugin.xml index a519e43bc6..d513a4fce0 100644 --- a/doc/classes/EditorDebuggerPlugin.xml +++ b/doc/classes/EditorDebuggerPlugin.xml @@ -15,18 +15,20 @@ class ExampleEditorDebugger extends EditorDebuggerPlugin: - func _has_capture(prefix): - # Return true if you wish to handle message with this prefix. - return prefix == "my_plugin" + func _has_capture(capture): + # Return true if you wish to handle messages with the prefix "my_plugin:". + return capture == "my_plugin" func _capture(message, data, session_id): if message == "my_plugin:ping": get_session(session_id).send_message("my_plugin:echo", data) + return true + return false func _setup_session(session_id): # Add a new tab in the debugger session UI containing a label. var label = Label.new() - label.name = "Example plugin" + label.name = "Example plugin" # Will be used as the tab title. label.text = "Example plugin" var session = get_session(session_id) # Listens to the session started and stopped signals. @@ -43,6 +45,24 @@ remove_debugger_plugin(debugger) [/gdscript] [/codeblocks] + To connect on the running game side, use the [EngineDebugger] singleton: + [codeblocks] + [gdscript] + extends Node + + func _ready(): + EngineDebugger.register_message_capture("my_plugin", _capture) + EngineDebugger.send_message("my_plugin:ping", ["test"]) + + func _capture(message, data): + # Note that the "my_plugin:" prefix is not used here. + if message == "echo": + prints("Echo received:", data) + return true + return false + [/gdscript] + [/codeblocks] + [b]Note:[/b] While the game is running, [method @GlobalScope.print] and similar functions [i]called in the editor[/i] do not print anything, the Output Log prints only game messages. </description> <tutorials> </tutorials> @@ -68,7 +88,7 @@ <param index="1" name="data" type="Array" /> <param index="2" name="session_id" type="int" /> <description> - Override this method to process incoming messages. The [param session_id] is the ID of the [EditorDebuggerSession] that received the message (which you can retrieve via [method get_session]). + Override this method to process incoming messages. The [param session_id] is the ID of the [EditorDebuggerSession] that received the [param message]. Use [method get_session] to retrieve the session. This method should return [code]true[/code] if the message is recognized. </description> </method> <method name="_goto_script_line" qualifiers="virtual"> @@ -90,7 +110,7 @@ <return type="void" /> <param index="0" name="session_id" type="int" /> <description> - Override this method to be notified whenever a new [EditorDebuggerSession] is created (the session may be inactive during this stage). + Override this method to be notified whenever a new [EditorDebuggerSession] is created. Note that the session may be inactive during this stage. </description> </method> <method name="get_session"> diff --git a/doc/classes/EditorDebuggerSession.xml b/doc/classes/EditorDebuggerSession.xml index b4e754cc7e..f5fa3e34d5 100644 --- a/doc/classes/EditorDebuggerSession.xml +++ b/doc/classes/EditorDebuggerSession.xml @@ -14,7 +14,7 @@ <return type="void" /> <param index="0" name="control" type="Control" /> <description> - Adds the given [param control] to the debug session UI in the debugger bottom panel. + Adds the given [param control] to the debug session UI in the debugger bottom panel. The [param control]'s node name will be used as the tab title. </description> </method> <method name="is_active"> diff --git a/doc/classes/EditorExportPlugin.xml b/doc/classes/EditorExportPlugin.xml index aa8e4b3d56..23e3f4139c 100644 --- a/doc/classes/EditorExportPlugin.xml +++ b/doc/classes/EditorExportPlugin.xml @@ -27,6 +27,7 @@ <description> Return [code]true[/code] if this plugin will customize scenes based on the platform and features used. When enabled, [method _get_customization_configuration_hash] and [method _customize_scene] will be called and must be implemented. + [b]Note:[/b] [method _customize_scene] will only be called for scenes that have been modified since the last export. </description> </method> <method name="_customize_resource" qualifiers="virtual"> @@ -34,9 +35,16 @@ <param index="0" name="resource" type="Resource" /> <param index="1" name="path" type="String" /> <description> - Customize a resource. If changes are made to it, return the same or a new resource. Otherwise, return [code]null[/code]. - The [i]path[/i] argument is only used when customizing an actual file, otherwise this means that this resource is part of another one and it will be empty. + Customize a resource. If changes are made to it, return the same or a new resource. Otherwise, return [code]null[/code]. When a new resource is returned, [param resource] will be replaced by a copy of the new resource. + The [param path] argument is only used when customizing an actual file, otherwise this means that this resource is part of another one and it will be empty. Implementing this method is required if [method _begin_customize_resources] returns [code]true[/code]. + [b]Note:[/b] When customizing any of the following types and returning another resource, the other resource should not be skipped using [method skip] in [method _export_file]: + - [AtlasTexture] + - [CompressedCubemap] + - [CompressedCubemapArray] + - [CompressedTexture2D] + - [CompressedTexture2DArray] + - [CompressedTexture3D] </description> </method> <method name="_customize_scene" qualifiers="virtual"> diff --git a/doc/classes/EditorFeatureProfile.xml b/doc/classes/EditorFeatureProfile.xml index 3aa1e63aac..c125c923ef 100644 --- a/doc/classes/EditorFeatureProfile.xml +++ b/doc/classes/EditorFeatureProfile.xml @@ -121,7 +121,10 @@ <constant name="FEATURE_HISTORY_DOCK" value="7" enum="Feature"> The History dock. If this feature is disabled, the History dock won't be visible. </constant> - <constant name="FEATURE_MAX" value="8" enum="Feature"> + <constant name="FEATURE_GAME" value="8" enum="Feature"> + The Game tab, which allows embedding the game window and selecting nodes by clicking inside of it. If this feature is disabled, the Game tab won't display. + </constant> + <constant name="FEATURE_MAX" value="9" enum="Feature"> Represents the size of the [enum Feature] enum. </constant> </constants> diff --git a/doc/classes/EditorFileSystemImportFormatSupportQuery.xml b/doc/classes/EditorFileSystemImportFormatSupportQuery.xml index b1a810fe6e..fc2feca911 100644 --- a/doc/classes/EditorFileSystemImportFormatSupportQuery.xml +++ b/doc/classes/EditorFileSystemImportFormatSupportQuery.xml @@ -24,7 +24,7 @@ <method name="_query" qualifiers="virtual const"> <return type="bool" /> <description> - Query support. Return false if import must not continue. + Query support. Return [code]false[/code] if import must not continue. </description> </method> </methods> diff --git a/doc/classes/EditorImportPlugin.xml b/doc/classes/EditorImportPlugin.xml index 28614b6631..186f249281 100644 --- a/doc/classes/EditorImportPlugin.xml +++ b/doc/classes/EditorImportPlugin.xml @@ -124,7 +124,8 @@ <return type="bool" /> <description> Tells whether this importer can be run in parallel on threads, or, on the contrary, it's only safe for the editor to call it from the main thread, for one file at a time. - If this method is not overridden, it will return [code]true[/code] by default (i.e., safe for parallel importing). + If this method is not overridden, it will return [code]false[/code] by default. + If this importer's implementation is thread-safe and can be run in parallel, override this with [code]true[/code] to optimize for concurrency. </description> </method> <method name="_get_import_options" qualifiers="virtual const"> @@ -153,7 +154,7 @@ <param index="1" name="option_name" type="StringName" /> <param index="2" name="options" type="Dictionary" /> <description> - This method can be overridden to hide specific import options if conditions are met. This is mainly useful for hiding options that depend on others if one of them is disabled. For example: + This method can be overridden to hide specific import options if conditions are met. This is mainly useful for hiding options that depend on others if one of them is disabled. [codeblocks] [gdscript] func _get_option_visibility(option, options): diff --git a/doc/classes/EditorInterface.xml b/doc/classes/EditorInterface.xml index 43059db8b2..0304499a61 100644 --- a/doc/classes/EditorInterface.xml +++ b/doc/classes/EditorInterface.xml @@ -301,6 +301,15 @@ See also [method Window.set_unparent_when_invisible]. </description> </method> + <method name="popup_method_selector"> + <return type="void" /> + <param index="0" name="object" type="Object" /> + <param index="1" name="callback" type="Callable" /> + <param index="2" name="current_value" type="String" default="""" /> + <description> + Pops up an editor dialog for selecting a method from [param object]. The [param callback] must take a single argument of type [String] which will contain the name of the selected method or be empty if the dialog is canceled. If [param current_value] is provided, the method will be selected automatically in the method list, if it exists. + </description> + </method> <method name="popup_node_selector"> <return type="void" /> <param index="0" name="callback" type="Callable" /> diff --git a/doc/classes/EditorProperty.xml b/doc/classes/EditorProperty.xml index 2b1083393f..4ff541f72d 100644 --- a/doc/classes/EditorProperty.xml +++ b/doc/classes/EditorProperty.xml @@ -132,6 +132,13 @@ Emitted when a property was deleted. Used internally. </description> </signal> + <signal name="property_favorited"> + <param index="0" name="property" type="StringName" /> + <param index="1" name="favorited" type="bool" /> + <description> + Emit it if you want to mark a property as favorited, making it appear at the top of the inspector. + </description> + </signal> <signal name="property_keyed"> <param index="0" name="property" type="StringName" /> <description> diff --git a/doc/classes/EditorResourcePreview.xml b/doc/classes/EditorResourcePreview.xml index ed3fdae352..a0c1a43fb2 100644 --- a/doc/classes/EditorResourcePreview.xml +++ b/doc/classes/EditorResourcePreview.xml @@ -32,7 +32,7 @@ <param index="3" name="userdata" type="Variant" /> <description> Queue the [param resource] being edited for preview. Once the preview is ready, the [param receiver]'s [param receiver_func] will be called. The [param receiver_func] must take the following four arguments: [String] path, [Texture2D] preview, [Texture2D] thumbnail_preview, [Variant] userdata. [param userdata] can be anything, and will be returned when [param receiver_func] is called. - [b]Note:[/b] If it was not possible to create the preview the [param receiver_func] will still be called, but the preview will be null. + [b]Note:[/b] If it was not possible to create the preview the [param receiver_func] will still be called, but the preview will be [code]null[/code]. </description> </method> <method name="queue_resource_preview"> @@ -43,7 +43,7 @@ <param index="3" name="userdata" type="Variant" /> <description> Queue a resource file located at [param path] for preview. Once the preview is ready, the [param receiver]'s [param receiver_func] will be called. The [param receiver_func] must take the following four arguments: [String] path, [Texture2D] preview, [Texture2D] thumbnail_preview, [Variant] userdata. [param userdata] can be anything, and will be returned when [param receiver_func] is called. - [b]Note:[/b] If it was not possible to create the preview the [param receiver_func] will still be called, but the preview will be null. + [b]Note:[/b] If it was not possible to create the preview the [param receiver_func] will still be called, but the preview will be [code]null[/code]. </description> </method> <method name="remove_preview_generator"> diff --git a/doc/classes/EditorResourcePreviewGenerator.xml b/doc/classes/EditorResourcePreviewGenerator.xml index 9c9b6d11b2..89bfe836d7 100644 --- a/doc/classes/EditorResourcePreviewGenerator.xml +++ b/doc/classes/EditorResourcePreviewGenerator.xml @@ -4,7 +4,7 @@ Custom generator of previews. </brief_description> <description> - Custom code to generate previews. Please check [code]file_dialog/thumbnail_size[/code] in [EditorSettings] to find out the right size to do previews at. + Custom code to generate previews. Check [member EditorSettings.filesystem/file_dialog/thumbnail_size] to find a proper size to generate previews at. </description> <tutorials> </tutorials> diff --git a/doc/classes/EditorScenePostImport.xml b/doc/classes/EditorScenePostImport.xml index 7325d31fc5..f8938c459c 100644 --- a/doc/classes/EditorScenePostImport.xml +++ b/doc/classes/EditorScenePostImport.xml @@ -5,7 +5,7 @@ </brief_description> <description> Imported scenes can be automatically modified right after import by setting their [b]Custom Script[/b] Import property to a [code]tool[/code] script that inherits from this class. - The [method _post_import] callback receives the imported scene's root node and returns the modified version of the scene. Usage example: + The [method _post_import] callback receives the imported scene's root node and returns the modified version of the scene: [codeblocks] [gdscript] @tool # Needed so it runs in editor. diff --git a/doc/classes/EditorScenePostImportPlugin.xml b/doc/classes/EditorScenePostImportPlugin.xml index 5c1c898c9d..0004ec65c6 100644 --- a/doc/classes/EditorScenePostImportPlugin.xml +++ b/doc/classes/EditorScenePostImportPlugin.xml @@ -28,7 +28,7 @@ <param index="0" name="category" type="int" /> <param index="1" name="option" type="String" /> <description> - Return true whether updating the 3D view of the import dialog needs to be updated if an option has changed. + Should return [code]true[/code] if the 3D view of the import dialog needs to update when changing the given option. </description> </method> <method name="_get_internal_option_visibility" qualifiers="virtual const"> @@ -37,7 +37,7 @@ <param index="1" name="for_animation" type="bool" /> <param index="2" name="option" type="String" /> <description> - Return true or false whether a given option should be visible. Return null to ignore. + Should return [code]true[/code] to show the given option, [code]false[/code] to hide the given option, or [code]null[/code] to ignore. </description> </method> <method name="_get_option_visibility" qualifiers="virtual const"> @@ -46,7 +46,7 @@ <param index="1" name="for_animation" type="bool" /> <param index="2" name="option" type="String" /> <description> - Return true or false whether a given option should be visible. Return null to ignore. + Should return [code]true[/code] to show the given option, [code]false[/code] to hide the given option, or [code]null[/code] to ignore. </description> </method> <method name="_internal_process" qualifiers="virtual"> diff --git a/doc/classes/EditorScript.xml b/doc/classes/EditorScript.xml index bd18852dbc..e342966fe8 100644 --- a/doc/classes/EditorScript.xml +++ b/doc/classes/EditorScript.xml @@ -6,7 +6,7 @@ <description> Scripts extending this class and implementing its [method _run] method can be executed from the Script Editor's [b]File > Run[/b] menu option (or by pressing [kbd]Ctrl + Shift + X[/kbd]) while the editor is running. This is useful for adding custom in-editor functionality to Godot. For more complex additions, consider using [EditorPlugin]s instead. [b]Note:[/b] Extending scripts need to have [code]tool[/code] mode enabled. - [b]Example script:[/b] + [b]Example:[/b] Running the following script prints "Hello from the Godot Editor!": [codeblocks] [gdscript] @tool diff --git a/doc/classes/EditorSettings.xml b/doc/classes/EditorSettings.xml index a5097521dc..15b03ddbd8 100644 --- a/doc/classes/EditorSettings.xml +++ b/doc/classes/EditorSettings.xml @@ -152,7 +152,7 @@ <param index="1" name="value" type="Variant" /> <param index="2" name="update_current" type="bool" /> <description> - Sets the initial value of the setting specified by [param name] to [param value]. This is used to provide a value for the Revert button in the Editor Settings. If [param update_current] is true, the current value of the setting will be set to [param value] as well. + Sets the initial value of the setting specified by [param name] to [param value]. This is used to provide a value for the Revert button in the Editor Settings. If [param update_current] is [code]true[/code], the setting is reset to [param value] as well. </description> </method> <method name="set_project_metadata"> @@ -230,7 +230,7 @@ If [code]true[/code], when a node is deleted with animation tracks referencing it, a confirmation dialog appears before the tracks are deleted. The dialog will appear even when using the "Delete (No Confirm)" shortcut. </member> <member name="docks/scene_tree/ask_before_revoking_unique_name" type="bool" setter="" getter=""> - If [code]true[/code], displays a confirmation dialog before left-clicking the "percent" icon next to a node name in the Scene tree dock. When clicked, this icon revokes the node's scene-unique name, which can impact the behavior of scripts that rely on this scene-unique name due to identifiers not being found anymore. + If [code]true[/code], displays a confirmation dialog after left-clicking the "percent" icon next to a node name in the Scene tree dock. When clicked, this icon revokes the node's scene-unique name, which can impact the behavior of scripts that rely on this scene-unique name due to identifiers not being found anymore. </member> <member name="docks/scene_tree/auto_expand_to_selected" type="bool" setter="" getter=""> If [code]true[/code], the scene tree dock will automatically unfold nodes when a node that has folded parents is selected. @@ -717,9 +717,21 @@ <member name="filesystem/quick_open_dialog/default_display_mode" type="int" setter="" getter=""> If set to [code]Adaptive[/code], the dialog opens in list view or grid view depending on the requested type. If set to [code]Last Used[/code], the display mode will always open the way you last used it. </member> + <member name="filesystem/quick_open_dialog/enable_fuzzy_matching" type="bool" setter="" getter=""> + If [code]true[/code], fuzzy matching of search tokens is allowed. + </member> <member name="filesystem/quick_open_dialog/include_addons" type="bool" setter="" getter=""> If [code]true[/code], results will include files located in the [code]addons[/code] folder. </member> + <member name="filesystem/quick_open_dialog/max_fuzzy_misses" type="int" setter="" getter=""> + The number of allowed missed query characters in a match, if fuzzy matching is enabled. For example, with the default value of 2, [code]foobar[/code] would match [code]foobur[/code] and [code]foob[/code] but not [code]foo[/code]. + </member> + <member name="filesystem/quick_open_dialog/max_results" type="int" setter="" getter=""> + Maximum number of matches to show in dialog. + </member> + <member name="filesystem/quick_open_dialog/show_search_highlight" type="bool" setter="" getter=""> + If [code]true[/code], results will be highlighted with their search matches. + </member> <member name="filesystem/tools/oidn/oidn_denoise_path" type="String" setter="" getter=""> The path to the directory containing the Open Image Denoise (OIDN) executable, used optionally for denoising lightmaps. It can be downloaded from [url=https://www.openimagedenoise.org/downloads.html]openimagedenoise.org[/url]. To enable this feature for your specific project, use [member ProjectSettings.rendering/lightmapping/denoising/denoiser]. @@ -1049,7 +1061,7 @@ Determines whether online features are enabled in the editor, such as the Asset Library or update checks. Disabling these online features helps alleviate privacy concerns by preventing the editor from making HTTP requests to the Godot website or third-party platforms hosting assets from the Asset Library. </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]). + The address to listen to when starting the remote debugger. This can be set to this device's local IP address to allow external clients to connect to the remote debugger (instead of restricting the remote debugger to connections from [code]localhost[/code]). </member> <member name="network/debug/remote_port" type="int" setter="" getter=""> The port to listen to when starting the remote debugger. Godot will try to use port numbers above the configured number if the configured number is already taken by another application. @@ -1079,9 +1091,11 @@ </member> <member name="run/bottom_panel/action_on_play" type="int" setter="" getter=""> The action to execute on the bottom panel when running the project. + [b]Note:[/b] This option won't do anything if the bottom panel switching is locked using the pin button in the corner of the bottom panel. </member> <member name="run/bottom_panel/action_on_stop" type="int" setter="" getter=""> The action to execute on the bottom panel when stopping the project. + [b]Note:[/b] This option won't do anything if the bottom panel switching is locked using the pin button in the corner of the bottom panel. </member> <member name="run/output/always_clear_output_on_play" type="bool" setter="" getter=""> If [code]true[/code], the editor will clear the Output panel when running the project. @@ -1314,6 +1328,9 @@ <member name="text_editor/script_list/group_help_pages" type="bool" setter="" getter=""> If [code]true[/code], class reference pages are grouped together at the bottom of the Script Editor's script list. </member> + <member name="text_editor/script_list/highlight_scene_scripts" type="bool" setter="" getter=""> + If [code]true[/code], the scripts that are used by the current scene are highlighted in the Script Editor's script list. + </member> <member name="text_editor/script_list/list_script_names_as" type="int" setter="" getter=""> Specifies how script paths should be displayed in Script Editor's script list. If using the "Name" option and some scripts share the same file name, more parts of their paths are revealed to avoid conflicts. </member> @@ -1395,7 +1412,7 @@ The script editor's documentation comment color. In GDScript, this is used for comments starting with [code]##[/code]. In C#, this is used for comments starting with [code]///[/code] or [code]/**[/code]. </member> <member name="text_editor/theme/highlighting/engine_type_color" type="Color" setter="" getter=""> - The script editor's engine type color ([Vector2], [Vector3], [Color], ...). + The script editor's engine type color ([Object], [Mesh], [Node], ...). </member> <member name="text_editor/theme/highlighting/executing_line_color" type="Color" setter="" getter=""> The script editor's color for the debugger's executing line icon (displayed in the gutter). diff --git a/doc/classes/EditorTranslationParserPlugin.xml b/doc/classes/EditorTranslationParserPlugin.xml index a47a41594e..43bbeaefa7 100644 --- a/doc/classes/EditorTranslationParserPlugin.xml +++ b/doc/classes/EditorTranslationParserPlugin.xml @@ -69,8 +69,7 @@ msgidsContextPlural.Add(new Godot.Collections.Array{"Only with context", "a friendly context", ""}); [/csharp] [/codeblocks] - [b]Note:[/b] If you override parsing logic for standard script types (GDScript, C#, etc.), it would be better to load the [code]path[/code] argument using [method ResourceLoader.load]. This is because built-in scripts are loaded as [Resource] type, not [FileAccess] type. - For example: + [b]Note:[/b] If you override parsing logic for standard script types (GDScript, C#, etc.), it would be better to load the [code]path[/code] argument using [method ResourceLoader.load]. This is because built-in scripts are loaded as [Resource] type, not [FileAccess] type. For example: [codeblocks] [gdscript] func _parse_file(path, msgids, msgids_context_plural): diff --git a/doc/classes/EditorUndoRedoManager.xml b/doc/classes/EditorUndoRedoManager.xml index 0f8c69a1bb..6a66a35ce8 100644 --- a/doc/classes/EditorUndoRedoManager.xml +++ b/doc/classes/EditorUndoRedoManager.xml @@ -87,7 +87,7 @@ <return type="void" /> <param index="0" name="execute" type="bool" default="true" /> <description> - Commit the action. If [param execute] is true (default), all "do" methods/properties are called/set when this function is called. + Commits the action. If [param execute] is [code]true[/code] (default), all "do" methods/properties are called/set when this function is called. </description> </method> <method name="create_action"> diff --git a/doc/classes/EngineDebugger.xml b/doc/classes/EngineDebugger.xml index bcc1ac5299..3540f098ba 100644 --- a/doc/classes/EngineDebugger.xml +++ b/doc/classes/EngineDebugger.xml @@ -113,7 +113,8 @@ <param index="1" name="callable" type="Callable" /> <description> Registers a message capture with given [param name]. If [param name] is "my_message" then messages starting with "my_message:" will be called with the given callable. - Callable must accept a message string and a data array as argument. If the message and data are valid then callable must return [code]true[/code] otherwise [code]false[/code]. + The callable must accept a message string and a data array as argument. The callable should return [code]true[/code] if the message is recognized. + [b]Note:[/b] The callable will receive the message with the prefix stripped, unlike [method EditorDebuggerPlugin._capture]. See the [EditorDebuggerPlugin] description for an example. </description> </method> <method name="register_profiler"> diff --git a/doc/classes/Environment.xml b/doc/classes/Environment.xml index 1779408a4d..47fc48305b 100644 --- a/doc/classes/Environment.xml +++ b/doc/classes/Environment.xml @@ -182,7 +182,8 @@ [b]Note:[/b] [member glow_map] has no effect when using the Compatibility rendering method, due to this rendering method using a simpler glow implementation optimized for low-end devices. </member> <member name="glow_map_strength" type="float" setter="set_glow_map_strength" getter="get_glow_map_strength" default="0.8"> - How strong of an impact the [member glow_map] should have on the overall glow effect. A strength of [code]0.0[/code] means the glow map has no effect on the overall glow effect. A strength of [code]1.0[/code] means the glow has a full effect on the overall glow effect (and can turn off glow entirely in specific areas of the screen if the glow map has black areas). + How strong of an influence the [member glow_map] should have on the overall glow effect. A strength of [code]0.0[/code] means the glow map has no influence, while a strength of [code]1.0[/code] means the glow map has full influence. + [b]Note:[/b] If the glow map has black areas, a value of [code]1.0[/code] can also turn off the glow effect entirely in specific areas of the screen. [b]Note:[/b] [member glow_map_strength] has no effect when using the Compatibility rendering method, due to this rendering method using a simpler glow implementation optimized for low-end devices. </member> <member name="glow_mix" type="float" setter="set_glow_mix" getter="get_glow_mix" default="0.05"> diff --git a/doc/classes/FileAccess.xml b/doc/classes/FileAccess.xml index 5888e30339..b782937a8a 100644 --- a/doc/classes/FileAccess.xml +++ b/doc/classes/FileAccess.xml @@ -34,7 +34,7 @@ [/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. [FileAccess] will close when it's freed, which happens when it goes out of scope or when it gets assigned with [code]null[/code]. [method close] can be used to close it before then explicitly. In C# the reference must be disposed manually, which can be done with the [code]using[/code] statement or by calling the [code]Dispose[/code] method directly. - [b]Note:[/b] To access project resources once exported, it is recommended to use [ResourceLoader] instead of [FileAccess], as some files are converted to engine-specific formats and their original source files might not be present in the exported PCK package. + [b]Note:[/b] To access project resources once exported, it is recommended to use [ResourceLoader] instead of [FileAccess], as some files are converted to engine-specific formats and their original source files might not be present in the exported PCK package. If using [FileAccess], make sure the file is included in the export by changing its import mode to [b]Keep File (exported as is)[/b] in the Import dock, or, for files where this option is not available, change the non-resource export filter in the Export dialog to include the file's extension (e.g. [code]*.txt[/code]). [b]Note:[/b] Files are automatically closed only if the process exits "normally" (such as by clicking the window manager's close button or pressing [b]Alt + F4[/b]). If you stop the project execution by pressing [b]F8[/b] while the project is running, the file won't be closed as the game process will be killed. You can work around this by calling [method flush] at regular intervals. </description> <tutorials> diff --git a/doc/classes/FileDialog.xml b/doc/classes/FileDialog.xml index 18b8eb1d39..64369bec30 100644 --- a/doc/classes/FileDialog.xml +++ b/doc/classes/FileDialog.xml @@ -146,6 +146,7 @@ </member> <member name="filters" type="PackedStringArray" setter="set_filters" getter="get_filters" default="PackedStringArray()"> The available file type filters. Each filter string in the array should be formatted like this: [code]*.txt,*.doc;Text Files[/code]. The description text of the filter is optional and can be omitted. + [b]Note:[/b] For android native dialog, MIME types are used like this: [code]image/*, application/pdf[/code]. </member> <member name="mode_overrides_title" type="bool" setter="set_mode_overrides_title" getter="is_mode_overriding_title" default="true"> If [code]true[/code], changing the [member file_mode] property will set the window title accordingly (e.g. setting [member file_mode] to [constant FILE_MODE_OPEN_FILE] will change the window title to "Open a File"). @@ -159,12 +160,13 @@ </member> <member name="show_hidden_files" type="bool" setter="set_show_hidden_files" getter="is_showing_hidden_files" default="false"> If [code]true[/code], the dialog will show hidden files. - [b]Note:[/b] This property is ignored by native file dialogs on Linux. + [b]Note:[/b] This property is ignored by native file dialogs on Android and Linux. </member> <member name="size" type="Vector2i" setter="set_size" getter="get_size" overrides="Window" default="Vector2i(640, 360)" /> <member name="title" type="String" setter="set_title" getter="get_title" overrides="Window" default=""Save a File"" /> <member name="use_native_dialog" type="bool" setter="set_use_native_dialog" getter="get_use_native_dialog" default="false"> If [code]true[/code], and if supported by the current [DisplayServer], OS native dialog will be used instead of custom one. + [b]Note:[/b] On Android, it is only supported when using [constant ACCESS_FILESYSTEM]. For access mode [constant ACCESS_RESOURCES] and [constant ACCESS_USERDATA], the system will fall back to custom FileDialog. [b]Note:[/b] On Linux and macOS, sandboxed apps always use native dialogs to access the host file system. [b]Note:[/b] On macOS, sandboxed apps will save security-scoped bookmarks to retain access to the opened folders across multiple sessions. Use [method OS.get_granted_permissions] to get a list of saved bookmarks. [b]Note:[/b] Native dialogs are isolated from the base process, file dialog properties can't be modified once the dialog is shown. diff --git a/doc/classes/GPUParticles2D.xml b/doc/classes/GPUParticles2D.xml index 3c48f5ba31..96232f4277 100644 --- a/doc/classes/GPUParticles2D.xml +++ b/doc/classes/GPUParticles2D.xml @@ -136,7 +136,7 @@ <signal name="finished"> <description> Emitted when all active particles have finished processing. To immediately restart the emission cycle, call [method restart]. - Never emitted when [member one_shot] is disabled, as particles will be emitted and processed continuously. + This signal is never emitted when [member one_shot] is disabled, as particles will be emitted and processed continuously. [b]Note:[/b] For [member one_shot] emitters, due to the particles being computed on the GPU, there may be a short period after receiving the signal during which setting [member emitting] to [code]true[/code] will not restart the emission cycle. This delay is avoided by instead calling [method restart]. </description> </signal> diff --git a/doc/classes/GPUParticles3D.xml b/doc/classes/GPUParticles3D.xml index 61a3b467f1..f5df857391 100644 --- a/doc/classes/GPUParticles3D.xml +++ b/doc/classes/GPUParticles3D.xml @@ -160,8 +160,8 @@ <signals> <signal name="finished"> <description> - Emitted when all active particles have finished processing. To immediately emit new particles, call [method restart]. - Never emitted when [member one_shot] is disabled, as particles will be emitted and processed continuously. + Emitted when all active particles have finished processing. To immediately restart the emission cycle, call [method restart]. + This signal is never emitted when [member one_shot] is disabled, as particles will be emitted and processed continuously. [b]Note:[/b] For [member one_shot] emitters, due to the particles being computed on the GPU, there may be a short period after receiving the signal during which setting [member emitting] to [code]true[/code] will not restart the emission cycle. This delay is avoided by instead calling [method restart]. </description> </signal> diff --git a/doc/classes/GPUParticlesCollision3D.xml b/doc/classes/GPUParticlesCollision3D.xml index 089747b7ee..2d398edd5e 100644 --- a/doc/classes/GPUParticlesCollision3D.xml +++ b/doc/classes/GPUParticlesCollision3D.xml @@ -16,8 +16,8 @@ <members> <member name="cull_mask" type="int" setter="set_cull_mask" getter="get_cull_mask" default="4294967295"> The particle rendering layers ([member VisualInstance3D.layers]) that will be affected by the collision shape. By default, all particles that have [member ParticleProcessMaterial.collision_mode] set to [constant ParticleProcessMaterial.COLLISION_RIGID] or [constant ParticleProcessMaterial.COLLISION_HIDE_ON_CONTACT] will be affected by a collision shape. - After configuring particle nodes accordingly, specific layers can be unchecked to prevent certain particles from being affected by attractors. For example, this can be used if you're using an attractor as part of a spell effect but don't want the attractor to affect unrelated weather particles at the same position. - Particle attraction can also be disabled on a per-process material basis by setting [member ParticleProcessMaterial.attractor_interaction_enabled] on the [GPUParticles3D] node. + After configuring particle nodes accordingly, specific layers can be unchecked to prevent certain particles from being affected by colliders. For example, this can be used if you're using a collider as part of a spell effect but don't want the collider to affect unrelated weather particles at the same position. + Particle collision can also be disabled on a per-process material basis by setting [member ParticleProcessMaterial.collision_mode] on the [GPUParticles3D] node. </member> </members> </class> diff --git a/doc/classes/Geometry2D.xml b/doc/classes/Geometry2D.xml index 2dd76ad989..71e6cf93ae 100644 --- a/doc/classes/Geometry2D.xml +++ b/doc/classes/Geometry2D.xml @@ -9,6 +9,20 @@ <tutorials> </tutorials> <methods> + <method name="bresenham_line"> + <return type="Vector2i[]" /> + <param index="0" name="from" type="Vector2i" /> + <param index="1" name="to" type="Vector2i" /> + <description> + Returns the [url=https://en.wikipedia.org/wiki/Bresenham%27s_line_algorithm]Bresenham line[/url] between the [param from] and [param to] points. A Bresenham line is a series of pixels that draws a line and is always 1-pixel thick on every row and column of the drawing (never more, never less). + Example code to draw a line between two [Marker2D] nodes using a series of [method CanvasItem.draw_rect] calls: + [codeblock] + func _draw(): + for pixel in Geometry2D.bresenham_line($MarkerA.position, $MarkerB.position): + draw_rect(Rect2(pixel, Vector2.ONE), Color.WHITE) + [/codeblock] + </description> + </method> <method name="clip_polygons"> <return type="PackedVector2Array[]" /> <param index="0" name="polygon_a" type="PackedVector2Array" /> diff --git a/doc/classes/GraphNode.xml b/doc/classes/GraphNode.xml index cc3acad6d6..fc8bc15b5c 100644 --- a/doc/classes/GraphNode.xml +++ b/doc/classes/GraphNode.xml @@ -154,7 +154,7 @@ <return type="bool" /> <param index="0" name="slot_index" type="int" /> <description> - Returns true if the background [StyleBox] of the slot with the given [param slot_index] is drawn. + Returns [code]true[/code] if the background [StyleBox] of the slot with the given [param slot_index] is drawn. </description> </method> <method name="is_slot_enabled_left" qualifiers="const"> diff --git a/doc/classes/HTTPClient.xml b/doc/classes/HTTPClient.xml index af98636056..366038e43f 100644 --- a/doc/classes/HTTPClient.xml +++ b/doc/classes/HTTPClient.xml @@ -277,7 +277,11 @@ HTTP status code [code]102 Processing[/code] (WebDAV). Indicates that the server has received and is processing the request, but no response is available yet. </constant> <constant name="RESPONSE_OK" value="200" enum="ResponseCode"> - HTTP status code [code]200 OK[/code]. The request has succeeded. Default response for successful requests. Meaning varies depending on the request. GET: The resource has been fetched and is transmitted in the message body. HEAD: The entity headers are in the message body. POST: The resource describing the result of the action is transmitted in the message body. TRACE: The message body contains the request message as received by the server. + HTTP status code [code]200 OK[/code]. The request has succeeded. Default response for successful requests. Meaning varies depending on the request: + - [constant METHOD_GET]: The resource has been fetched and is transmitted in the message body. + - [constant METHOD_HEAD]: The entity headers are in the message body. + - [constant METHOD_POST]: The resource describing the result of the action is transmitted in the message body. + - [constant METHOD_TRACE]: The message body contains the request message as received by the server. </constant> <constant name="RESPONSE_CREATED" value="201" enum="ResponseCode"> HTTP status code [code]201 Created[/code]. The request has succeeded and a new resource has been created as a result of it. This is typically the response sent after a PUT request. diff --git a/doc/classes/HTTPRequest.xml b/doc/classes/HTTPRequest.xml index 6efa675a71..36f5e82652 100644 --- a/doc/classes/HTTPRequest.xml +++ b/doc/classes/HTTPRequest.xml @@ -8,7 +8,7 @@ Can be used to make HTTP requests, i.e. download or upload files or web content via HTTP. [b]Warning:[/b] See the notes and warnings on [HTTPClient] for limitations, especially regarding TLS security. [b]Note:[/b] When exporting to Android, make sure to enable the [code]INTERNET[/code] permission in the Android export preset before exporting the project or using one-click deploy. Otherwise, network communication of any kind will be blocked by Android. - [b]Example of contacting a REST API and printing one of its returned fields:[/b] + [b]Example:[/b] Contact a REST API and print one of its returned fields: [codeblocks] [gdscript] func _ready(): @@ -80,7 +80,7 @@ } [/csharp] [/codeblocks] - [b]Example of loading and displaying an image using HTTPRequest:[/b] + [b]Example:[/b] Load an image using [HTTPRequest] and display it: [codeblocks] [gdscript] func _ready(): @@ -150,7 +150,7 @@ } [/csharp] [/codeblocks] - [b]Gzipped response bodies[/b]: HTTPRequest will automatically handle decompression of response bodies. A [code]Accept-Encoding[/code] header will be automatically added to each of your requests, unless one is already specified. Any response with a [code]Content-Encoding: gzip[/code] header will automatically be decompressed and delivered to you as uncompressed bytes. + [b]Note:[/b] [HTTPRequest] nodes will automatically handle decompression of response bodies. A [code]Accept-Encoding[/code] header will be automatically added to each of your requests, unless one is already specified. Any response with a [code]Content-Encoding: gzip[/code] header will automatically be decompressed and delivered to you as uncompressed bytes. </description> <tutorials> <link title="Making HTTP requests">$DOCS_URL/tutorials/networking/http_request_class.html</link> @@ -275,6 +275,7 @@ Request successful. </constant> <constant name="RESULT_CHUNKED_BODY_SIZE_MISMATCH" value="1" enum="Result"> + Request failed due to a mismatch between the expected and actual chunked body size during transfer. Possible causes include network errors, server misconfiguration, or issues with chunked encoding. </constant> <constant name="RESULT_CANT_CONNECT" value="2" enum="Result"> Request failed while connecting. @@ -295,6 +296,7 @@ Request exceeded its maximum size limit, see [member body_size_limit]. </constant> <constant name="RESULT_BODY_DECOMPRESS_FAILED" value="8" enum="Result"> + Request failed due to an error while decompressing the response body. Possible causes include unsupported or incorrect compression format, corrupted data, or incomplete transfer. </constant> <constant name="RESULT_REQUEST_FAILED" value="9" enum="Result"> Request failed (currently unused). diff --git a/doc/classes/Image.xml b/doc/classes/Image.xml index 0fd84fb452..4421318be7 100644 --- a/doc/classes/Image.xml +++ b/doc/classes/Image.xml @@ -48,6 +48,7 @@ <param index="2" name="dst" type="Vector2i" /> <description> Copies [param src_rect] from [param src] image to this image at coordinates [param dst], clipped accordingly to both image bounds. This image and [param src] image [b]must[/b] have the same format. [param src_rect] with non-positive size is treated as empty. + [b]Note:[/b] The alpha channel data in [param src] will overwrite the corresponding data in this image at the target position. To blend alpha channels, use [method blend_rect] instead. </description> </method> <method name="blit_rect_mask"> @@ -510,7 +511,7 @@ <param index="1" name="lossy" type="bool" default="false" /> <param index="2" name="quality" type="float" default="0.75" /> <description> - Saves the image as a WebP (Web Picture) file to the file at [param path]. By default it will save lossless. If [param lossy] is true, the image will be saved lossy, using the [param quality] setting between 0.0 and 1.0 (inclusive). Lossless WebP offers more efficient compression than PNG. + Saves the image as a WebP (Web Picture) file to the file at [param path]. By default it will save lossless. If [param lossy] is [code]true[/code], the image will be saved lossy, using the [param quality] setting between [code]0.0[/code] and [code]1.0[/code] (inclusive). Lossless WebP offers more efficient compression than PNG. [b]Note:[/b] The WebP format is limited to a size of 16383×16383 pixels, while PNG can save larger images. </description> </method> @@ -519,7 +520,7 @@ <param index="0" name="lossy" type="bool" default="false" /> <param index="1" name="quality" type="float" default="0.75" /> <description> - Saves the image as a WebP (Web Picture) file to a byte array. By default it will save lossless. If [param lossy] is true, the image will be saved lossy, using the [param quality] setting between 0.0 and 1.0 (inclusive). Lossless WebP offers more efficient compression than PNG. + Saves the image as a WebP (Web Picture) file to a byte array. By default it will save lossless. If [param lossy] is [code]true[/code], the image will be saved lossy, using the [param quality] setting between [code]0.0[/code] and [code]1.0[/code] (inclusive). Lossless WebP offers more efficient compression than PNG. [b]Note:[/b] The WebP format is limited to a size of 16383×16383 pixels, while PNG can save larger images. </description> </method> diff --git a/doc/classes/ImporterMesh.xml b/doc/classes/ImporterMesh.xml index 28ee5710d9..745d7a3d5d 100644 --- a/doc/classes/ImporterMesh.xml +++ b/doc/classes/ImporterMesh.xml @@ -49,7 +49,8 @@ <param index="2" name="bone_transform_array" type="Array" /> <description> Generates all lods for this ImporterMesh. - [param normal_merge_angle] and [param normal_split_angle] are in degrees and used in the same way as the importer settings in [code]lods[/code]. As a good default, use 25 and 60 respectively. + [param normal_merge_angle] is in degrees and used in the same way as the importer settings in [code]lods[/code]. + [param normal_split_angle] is not used and only remains for compatibility with older versions of the API. The number of generated lods can be accessed using [method get_surface_lod_count], and each LOD is available in [method get_surface_lod_size] and [method get_surface_lod_indices]. [param bone_transform_array] is an [Array] which can be either empty or contain [Transform3D]s which, for each of the mesh's bone IDs, will apply mesh skinning when generating the LOD mesh variations. This is usually used to account for discrepancies in scale between the mesh itself and its skinning data. </description> diff --git a/doc/classes/InputEventMouseMotion.xml b/doc/classes/InputEventMouseMotion.xml index bcfe5b70fd..4c1461d03a 100644 --- a/doc/classes/InputEventMouseMotion.xml +++ b/doc/classes/InputEventMouseMotion.xml @@ -5,7 +5,7 @@ </brief_description> <description> Stores information about a mouse or a pen motion. This includes relative position, absolute position, and velocity. See [method Node._input]. - [b]Note:[/b] By default, this event is only emitted once per frame rendered at most. If you need more precise input reporting, set [member Input.use_accumulated_input] to [code]false[/code] to make events emitted as often as possible. If you use InputEventMouseMotion to draw lines, consider implementing [url=https://en.wikipedia.org/wiki/Bresenham%27s_line_algorithm]Bresenham's line algorithm[/url] as well to avoid visible gaps in lines if the user is moving the mouse quickly. + [b]Note:[/b] By default, this event is only emitted once per frame rendered at most. If you need more precise input reporting, set [member Input.use_accumulated_input] to [code]false[/code] to make events emitted as often as possible. If you use InputEventMouseMotion to draw lines, consider using [method Geometry2D.bresenham_line] as well to avoid visible gaps in lines if the user is moving the mouse quickly. [b]Note:[/b] This event may be emitted even when the mouse hasn't moved, either by the operating system or by Godot itself. If you really need to know if the mouse has moved (e.g. to suppress displaying a tooltip), you should check that [code]relative.is_zero_approx()[/code] is [code]false[/code]. </description> <tutorials> diff --git a/doc/classes/Label.xml b/doc/classes/Label.xml index f91006f69a..ae5a62753f 100644 --- a/doc/classes/Label.xml +++ b/doc/classes/Label.xml @@ -122,7 +122,7 @@ [Color] of the text's shadow effect. </theme_item> <theme_item name="line_spacing" data_type="constant" type="int" default="3"> - Vertical space between lines in multiline [Label]. + Additional vertical spacing between lines (in pixels), spacing is added to line descent. This value can be negative. </theme_item> <theme_item name="outline_size" data_type="constant" type="int" default="0"> Text outline size. diff --git a/doc/classes/Label3D.xml b/doc/classes/Label3D.xml index ff26c5490d..7584a1d526 100644 --- a/doc/classes/Label3D.xml +++ b/doc/classes/Label3D.xml @@ -79,7 +79,7 @@ Language code used for line-breaking and text shaping algorithms, if left empty current locale is used instead. </member> <member name="line_spacing" type="float" setter="set_line_spacing" getter="get_line_spacing" default="0.0"> - Vertical space between lines in multiline [Label3D]. + Additional vertical spacing between lines (in pixels), spacing is added to line descent. This value can be negative. </member> <member name="modulate" type="Color" setter="set_modulate" getter="get_modulate" default="Color(1, 1, 1, 1)" keywords="color, colour"> Text [Color] of the [Label3D]. diff --git a/doc/classes/LabelSettings.xml b/doc/classes/LabelSettings.xml index 8cdb30c303..ff7b8e7b0e 100644 --- a/doc/classes/LabelSettings.xml +++ b/doc/classes/LabelSettings.xml @@ -19,7 +19,7 @@ Size of the text. </member> <member name="line_spacing" type="float" setter="set_line_spacing" getter="get_line_spacing" default="3.0"> - Vertical space between lines when the text is multiline. + Additional vertical spacing between lines (in pixels), spacing is added to line descent. This value can be negative. </member> <member name="outline_color" type="Color" setter="set_outline_color" getter="get_outline_color" default="Color(1, 1, 1, 1)"> The color of the outline. diff --git a/doc/classes/Light3D.xml b/doc/classes/Light3D.xml index bda5fb69de..966d0fdcb4 100644 --- a/doc/classes/Light3D.xml +++ b/doc/classes/Light3D.xml @@ -115,6 +115,9 @@ <member name="shadow_blur" type="float" setter="set_param" getter="get_param" default="1.0"> Blurs the edges of the shadow. Can be used to hide pixel artifacts in low-resolution shadow maps. A high value can impact performance, make shadows appear grainy and can cause other unwanted artifacts. Try to keep as near default as possible. </member> + <member name="shadow_caster_mask" type="int" setter="set_shadow_caster_mask" getter="get_shadow_caster_mask" default="4294967295"> + The light will only cast shadows using objects in the selected layers. + </member> <member name="shadow_enabled" type="bool" setter="set_shadow" getter="has_shadow" default="false"> If [code]true[/code], the light will cast real-time shadows. This has a significant performance cost. Only enable shadow rendering when it makes a noticeable difference in the scene's appearance, and consider using [member distance_fade_enabled] to hide the light when far away from the [Camera3D]. </member> diff --git a/doc/classes/LineEdit.xml b/doc/classes/LineEdit.xml index 3e0c328dcb..91c9072f73 100644 --- a/doc/classes/LineEdit.xml +++ b/doc/classes/LineEdit.xml @@ -33,6 +33,7 @@ - [kbd]Cmd + E[/kbd]: Same as [kbd]End[/kbd], move the caret to the end of the line - [kbd]Cmd + Left Arrow[/kbd]: Same as [kbd]Home[/kbd], move the caret to the beginning of the line - [kbd]Cmd + Right Arrow[/kbd]: Same as [kbd]End[/kbd], move the caret to the end of the line + [b]Note:[/b] Caret movement shortcuts listed above are not affected by [member shortcut_keys_enabled]. </description> <tutorials> </tutorials> @@ -334,7 +335,7 @@ If [code]false[/code], it's impossible to select the text using mouse nor keyboard. </member> <member name="shortcut_keys_enabled" type="bool" setter="set_shortcut_keys_enabled" getter="is_shortcut_keys_enabled" default="true"> - If [code]false[/code], using shortcuts will be disabled. + If [code]true[/code], shortcut keys for context menu items are enabled, even if the context menu is disabled. </member> <member name="structured_text_bidi_override" type="int" setter="set_structured_text_bidi_override" getter="get_structured_text_bidi_override" enum="TextServer.StructuredTextParser" default="0"> Set BiDi algorithm override for the structured text. diff --git a/doc/classes/LookAtModifier3D.xml b/doc/classes/LookAtModifier3D.xml new file mode 100644 index 0000000000..e85da06c3a --- /dev/null +++ b/doc/classes/LookAtModifier3D.xml @@ -0,0 +1,156 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="LookAtModifier3D" inherits="SkeletonModifier3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + The [SkeletonModifier3D] rotates a bone to look a target. + </brief_description> + <description> + This [SkeletonModifier3D] rotates a bone to look a target. This is helpful for moving character's head to look at the player, rotating a turret to look at a target, or any other case where you want to make a bone rotate towards something quickly and easily. + When applying multiple [LookAtModifier3D]s, the [LookAtModifier3D] assigned to the parent bone must be put above the [LookAtModifier3D] assigned to the child bone in the list in order for the child bone results to be correct. + </description> + <tutorials> + </tutorials> + <methods> + <method name="get_interpolation_remaining" qualifiers="const"> + <return type="float" /> + <description> + Returns the remaining seconds of the time-based interpolation. + </description> + </method> + <method name="is_interpolating" qualifiers="const"> + <return type="bool" /> + <description> + Returns whether the time-based interpolation is running or not. If [code]true[/code], it is equivalent to [method get_interpolation_remaining] being [code]0[/code]. + This is useful to determine whether a [LookAtModifier3D] can be removed safely. + </description> + </method> + <method name="is_target_within_limitation" qualifiers="const"> + <return type="bool" /> + <description> + Returns whether the target is within the angle limitations. It is useful for unsetting the [member target_node] when the target is outside of the angle limitations. + [b]Note:[/b] The value is updated after [method SkeletonModifier3D._process_modification]. To retrieve this value correctly, we recommend using the signal [signal SkeletonModifier3D.modification_processed]. + </description> + </method> + </methods> + <members> + <member name="bone" type="int" setter="set_bone" getter="get_bone" default="0"> + The bone index of the [Skeleton3D] that the modification will operate on. + </member> + <member name="duration" type="float" setter="set_duration" getter="get_duration" default="0.0"> + The duration of the time-based interpolation. Interpolation is triggered at the following cases: + - When the target node is changed + - When an axis is flipped due to angle limitation + [b]Note:[/b] The flipping occurs when the target is outside the angle limitation and the internally computed secondary rotation axis of the forward vector is flipped. Visually, it occurs when the target is outside the angle limitation and crosses the plane of the [member forward_axis] and [member primary_rotation_axis]. + </member> + <member name="ease_type" type="int" setter="set_ease_type" getter="get_ease_type" enum="Tween.EaseType" default="0"> + The ease type of the time-based interpolation. See also [enum Tween.EaseType]. + </member> + <member name="forward_axis" type="int" setter="set_forward_axis" getter="get_forward_axis" enum="LookAtModifier3D.BoneAxis" default="4"> + The forward axis of the bone. This [SkeletonModifier3D] modifies the bone so that this axis points toward the [member target_node]. + </member> + <member name="origin_bone" type="int" setter="set_origin_bone" getter="get_origin_bone"> + If [member origin_from] is [constant ORIGIN_FROM_SPECIFIC_BONE], the bone global pose position specified for this is used as origin. + </member> + <member name="origin_external_node" type="NodePath" setter="set_origin_external_node" getter="get_origin_external_node"> + If [member origin_from] is [constant ORIGIN_FROM_EXTERNAL_NODE], the global position of the [Node3D] specified for this is used as origin. + </member> + <member name="origin_from" type="int" setter="set_origin_from" getter="get_origin_from" enum="LookAtModifier3D.OriginFrom" default="0"> + This value determines from what origin is retrieved for use in the calculation of the forward vector. + </member> + <member name="origin_offset" type="Vector3" setter="set_origin_offset" getter="get_origin_offset" default="Vector3(0, 0, 0)"> + The offset of the bone pose origin. Matching the origins by offset is useful for cases where multiple bones must always face the same direction, such as the eyes. + [b]Note:[/b] This value indicates the local position of the object set in [member origin_from]. + </member> + <member name="origin_safe_margin" type="float" setter="set_origin_safe_margin" getter="get_origin_safe_margin" default="0.1"> + If the target passes through too close to the origin than this value, time-based interpolation is used even if the target is within the angular limitations, to prevent the angular velocity from becoming too high. + </member> + <member name="primary_damp_threshold" type="float" setter="set_primary_damp_threshold" getter="get_primary_damp_threshold"> + The threshold to start damping for [member primary_limit_angle]. It provides non-linear (b-spline) interpolation, let it feel more resistance the more it rotate to the edge limit. This is useful for simulating the limits of human motion. + If [code]1.0[/code], no damping is performed. If [code]0.0[/code], damping is always performed. + </member> + <member name="primary_limit_angle" type="float" setter="set_primary_limit_angle" getter="get_primary_limit_angle"> + The limit angle of the primary rotation when [member symmetry_limitation] is [code]true[/code]. + </member> + <member name="primary_negative_damp_threshold" type="float" setter="set_primary_negative_damp_threshold" getter="get_primary_negative_damp_threshold"> + The threshold to start damping for [member primary_negative_limit_angle]. + </member> + <member name="primary_negative_limit_angle" type="float" setter="set_primary_negative_limit_angle" getter="get_primary_negative_limit_angle"> + The limit angle of negative side of the primary rotation when [member symmetry_limitation] is [code]false[/code]. + </member> + <member name="primary_positive_damp_threshold" type="float" setter="set_primary_positive_damp_threshold" getter="get_primary_positive_damp_threshold"> + The threshold to start damping for [member primary_positive_limit_angle]. + </member> + <member name="primary_positive_limit_angle" type="float" setter="set_primary_positive_limit_angle" getter="get_primary_positive_limit_angle"> + The limit angle of positive side of the primary rotation when [member symmetry_limitation] is [code]false[/code]. + </member> + <member name="primary_rotation_axis" type="int" setter="set_primary_rotation_axis" getter="get_primary_rotation_axis" enum="Vector3.Axis" default="1"> + The axis of the first rotation. This [SkeletonModifier3D] works by compositing the rotation by Euler angles to prevent to rotate the [member forward_axis]. + </member> + <member name="secondary_damp_threshold" type="float" setter="set_secondary_damp_threshold" getter="get_secondary_damp_threshold"> + The threshold to start damping for [member secondary_limit_angle]. + </member> + <member name="secondary_limit_angle" type="float" setter="set_secondary_limit_angle" getter="get_secondary_limit_angle"> + The limit angle of the secondary rotation when [member symmetry_limitation] is [code]true[/code]. + </member> + <member name="secondary_negative_damp_threshold" type="float" setter="set_secondary_negative_damp_threshold" getter="get_secondary_negative_damp_threshold"> + The threshold to start damping for [member secondary_negative_limit_angle]. + </member> + <member name="secondary_negative_limit_angle" type="float" setter="set_secondary_negative_limit_angle" getter="get_secondary_negative_limit_angle"> + The limit angle of negative side of the secondary rotation when [member symmetry_limitation] is [code]false[/code]. + </member> + <member name="secondary_positive_damp_threshold" type="float" setter="set_secondary_positive_damp_threshold" getter="get_secondary_positive_damp_threshold"> + The threshold to start damping for [member secondary_positive_limit_angle]. + </member> + <member name="secondary_positive_limit_angle" type="float" setter="set_secondary_positive_limit_angle" getter="get_secondary_positive_limit_angle"> + The limit angle of positive side of the secondary rotation when [member symmetry_limitation] is [code]false[/code]. + </member> + <member name="symmetry_limitation" type="bool" setter="set_symmetry_limitation" getter="is_limitation_symmetry"> + If [code]true[/code], the limitations are spread from the bone symmetrically. + If [code]false[/code], the limitation can be specified separately for each side of the bone rest. + </member> + <member name="target_node" type="NodePath" setter="set_target_node" getter="get_target_node" default="NodePath("")"> + The [NodePath] to the node that is the target for the look at modification. This node is what the modification will rotate the bone to. + </member> + <member name="transition_type" type="int" setter="set_transition_type" getter="get_transition_type" enum="Tween.TransitionType" default="0"> + The transition type of the time-based interpolation. See also [enum Tween.TransitionType]. + </member> + <member name="use_angle_limitation" type="bool" setter="set_use_angle_limitation" getter="is_using_angle_limitation" default="false"> + If [code]true[/code], limits the degree of rotation. This helps prevent the character's neck from rotating 360 degrees. + [b]Note:[/b] As with [AnimationTree] blending, interpolation is provided that favors [method Skeleton3D.get_bone_rest]. This means that interpolation does not select the shortest path in some cases. + [b]Note:[/b] Some [member transition_type] may exceed the limitations (e.g. `Back`, `Elastic`, and `Spring`). If interpolation occurs while overshooting the limitations, the result might possibly not respect the bone rest. + </member> + <member name="use_secondary_rotation" type="bool" setter="set_use_secondary_rotation" getter="is_using_secondary_rotation" default="true"> + If [code]true[/code], provides rotation by two axes. + </member> + </members> + <constants> + <constant name="BONE_AXIS_PLUS_X" value="0" enum="BoneAxis"> + Enumerated value for the +X axis. + </constant> + <constant name="BONE_AXIS_MINUS_X" value="1" enum="BoneAxis"> + Enumerated value for the -X axis. + </constant> + <constant name="BONE_AXIS_PLUS_Y" value="2" enum="BoneAxis"> + Enumerated value for the +Y axis. + </constant> + <constant name="BONE_AXIS_MINUS_Y" value="3" enum="BoneAxis"> + Enumerated value for the -Y axis. + </constant> + <constant name="BONE_AXIS_PLUS_Z" value="4" enum="BoneAxis"> + Enumerated value for the +Z axis. + </constant> + <constant name="BONE_AXIS_MINUS_Z" value="5" enum="BoneAxis"> + Enumerated value for the -Z axis. + </constant> + <constant name="ORIGIN_FROM_SELF" value="0" enum="OriginFrom"> + The bone rest position of the bone specified in [member bone] is used as origin. + </constant> + <constant name="ORIGIN_FROM_SPECIFIC_BONE" value="1" enum="OriginFrom"> + The bone global pose position of the bone specified in [member origin_bone] is used as origin. + [b]Note:[/b] It is recommended that you select only the parent bone unless you are familiar with the bone processing process. The specified bone pose at the time the [LookAtModifier3D] is processed is used as a reference. In other words, if you specify a child bone and the [LookAtModifier3D] causes the child bone to move, the rendered result and direction will not match. + </constant> + <constant name="ORIGIN_FROM_EXTERNAL_NODE" value="2" enum="OriginFrom"> + The global position of the [Node3D] specified in [member origin_external_node] is used as origin. + [b]Note:[/b] Same as [constant ORIGIN_FROM_SPECIFIC_BONE], when specifying a [BoneAttachment3D] with a child bone assigned, the rendered result and direction will not match. + </constant> + </constants> +</class> diff --git a/doc/classes/MeshInstance3D.xml b/doc/classes/MeshInstance3D.xml index d8e2c43566..a0a773b90a 100644 --- a/doc/classes/MeshInstance3D.xml +++ b/doc/classes/MeshInstance3D.xml @@ -120,7 +120,7 @@ <param index="1" name="material" type="Material" /> <description> Sets the override [param material] for the specified [param surface] of the [Mesh] resource. This material is associated with this [MeshInstance3D] rather than with [member mesh]. - [b]Note:[/b] This assigns the [Material] associated to the [MeshInstance3D]'s Surface Material Override properties, not the material within the [Mesh] resource. To set the material within the [Mesh] resource, use [method Mesh.surface_get_material] instead. + [b]Note:[/b] This assigns the [Material] associated to the [MeshInstance3D]'s Surface Material Override properties, not the material within the [Mesh] resource. To set the material within the [Mesh] resource, use [method Mesh.surface_set_material] instead. </description> </method> </methods> diff --git a/doc/classes/MultiplayerPeer.xml b/doc/classes/MultiplayerPeer.xml index edb2c39e24..cec9464102 100644 --- a/doc/classes/MultiplayerPeer.xml +++ b/doc/classes/MultiplayerPeer.xml @@ -65,7 +65,7 @@ <method name="is_server_relay_supported" qualifiers="const"> <return type="bool" /> <description> - Returns true if the server can act as a relay in the current configuration (i.e. if the higher level [MultiplayerAPI] should notify connected clients of other peers, and implement a relay protocol to allow communication between them). + Returns [code]true[/code] if the server can act as a relay in the current configuration. That is, if the higher level [MultiplayerAPI] should notify connected clients of other peers, and implement a relay protocol to allow communication between them. </description> </method> <method name="poll"> diff --git a/doc/classes/NavigationServer2D.xml b/doc/classes/NavigationServer2D.xml index 7e78006240..5c19a6b355 100644 --- a/doc/classes/NavigationServer2D.xml +++ b/doc/classes/NavigationServer2D.xml @@ -133,7 +133,7 @@ <return type="bool" /> <param index="0" name="agent" type="RID" /> <description> - Returns true if the map got changed the previous frame. + Returns [code]true[/code] if the map got changed the previous frame. </description> </method> <method name="agent_set_avoidance_callback"> @@ -215,7 +215,7 @@ <param index="0" name="agent" type="RID" /> <param index="1" name="paused" type="bool" /> <description> - If [param paused] is true the specified [param agent] will not be processed, e.g. calculate avoidance velocities or receive avoidance callbacks. + If [param paused] is [code]true[/code] the specified [param agent] will not be processed, e.g. calculate avoidance velocities or receive avoidance callbacks. </description> </method> <method name="agent_set_position"> @@ -573,7 +573,7 @@ <return type="bool" /> <param index="0" name="map" type="RID" /> <description> - Returns true if the map is active. + Returns [code]true[/code] if the map is active. </description> </method> <method name="map_set_active"> @@ -707,7 +707,7 @@ <param index="0" name="obstacle" type="RID" /> <param index="1" name="paused" type="bool" /> <description> - If [param paused] is true the specified [param obstacle] will not be processed, e.g. affect avoidance velocities. + If [param paused] is [code]true[/code] the specified [param obstacle] will not be processed, e.g. affect avoidance velocities. </description> </method> <method name="obstacle_set_position"> diff --git a/doc/classes/NavigationServer3D.xml b/doc/classes/NavigationServer3D.xml index 7e206046d6..66a286758b 100644 --- a/doc/classes/NavigationServer3D.xml +++ b/doc/classes/NavigationServer3D.xml @@ -147,7 +147,7 @@ <return type="bool" /> <param index="0" name="agent" type="RID" /> <description> - Returns true if the map got changed the previous frame. + Returns [code]true[/code] if the map got changed the previous frame. </description> </method> <method name="agent_set_avoidance_callback"> @@ -237,7 +237,7 @@ <param index="0" name="agent" type="RID" /> <param index="1" name="paused" type="bool" /> <description> - If [param paused] is true the specified [param agent] will not be processed, e.g. calculate avoidance velocities or receive avoidance callbacks. + If [param paused] is [code]true[/code] the specified [param agent] will not be processed, e.g. calculate avoidance velocities or receive avoidance callbacks. </description> </method> <method name="agent_set_position"> @@ -645,14 +645,14 @@ <return type="bool" /> <param index="0" name="map" type="RID" /> <description> - Returns true if the navigation [param map] allows navigation regions to use edge connections to connect with other navigation regions within proximity of the navigation map edge connection margin. + Returns [code]true[/code] if the navigation [param map] allows navigation regions to use edge connections to connect with other navigation regions within proximity of the navigation map edge connection margin. </description> </method> <method name="map_is_active" qualifiers="const"> <return type="bool" /> <param index="0" name="map" type="RID" /> <description> - Returns true if the map is active. + Returns [code]true[/code] if the map is active. </description> </method> <method name="map_set_active"> @@ -832,7 +832,7 @@ <param index="0" name="obstacle" type="RID" /> <param index="1" name="paused" type="bool" /> <description> - If [param paused] is true the specified [param obstacle] will not be processed, e.g. affect avoidance velocities. + If [param paused] is [code]true[/code] the specified [param obstacle] will not be processed, e.g. affect avoidance velocities. </description> </method> <method name="obstacle_set_position"> @@ -1023,7 +1023,7 @@ <return type="bool" /> <param index="0" name="region" type="RID" /> <description> - Returns true if the navigation [param region] is set to use edge connections to connect with other navigation regions within proximity of the navigation map edge connection margin. + Returns [code]true[/code] if the navigation [param region] is set to use edge connections to connect with other navigation regions within proximity of the navigation map edge connection margin. </description> </method> <method name="region_owns_point" qualifiers="const"> diff --git a/doc/classes/Node.xml b/doc/classes/Node.xml index c07948b546..3cb76e2926 100644 --- a/doc/classes/Node.xml +++ b/doc/classes/Node.xml @@ -1006,8 +1006,8 @@ [b]Note:[/b] When changing the name, the following characters will be replaced with an underscore: ([code].[/code] [code]:[/code] [code]@[/code] [code]/[/code] [code]"[/code] [code]%[/code]). In particular, the [code]@[/code] character is reserved for auto-generated names. See also [method String.validate_node_name]. </member> <member name="owner" type="Node" setter="set_owner" getter="get_owner"> - The owner of this node. The owner must be an ancestor of this node. When packing the owner node in a [PackedScene], all the nodes it owns are also saved with it. - [b]Note:[/b] In the editor, nodes not owned by the scene root are usually not displayed in the Scene dock, and will [b]not[/b] be saved. To prevent this, remember to set the owner after calling [method add_child]. See also (see [member unique_name_in_owner]) + The owner of this node. The owner must be an ancestor of this node. When packing the owner node in a [PackedScene], all the nodes it owns are also saved with it. See also [member unique_name_in_owner]. + [b]Note:[/b] In the editor, nodes not owned by the scene root are usually not displayed in the Scene dock, and will [b]not[/b] be saved. To prevent this, remember to set the owner after calling [method add_child]. </member> <member name="physics_interpolation_mode" type="int" setter="set_physics_interpolation_mode" getter="get_physics_interpolation_mode" enum="Node.PhysicsInterpolationMode" default="0"> Allows enabling or disabling physics interpolation per node, offering a finer grain of control than turning physics interpolation on and off globally. See [member ProjectSettings.physics/common/physics_interpolation] and [member SceneTree.physics_interpolation] for the global setting. diff --git a/doc/classes/NodePath.xml b/doc/classes/NodePath.xml index d0ec81ab45..628c7106f2 100644 --- a/doc/classes/NodePath.xml +++ b/doc/classes/NodePath.xml @@ -57,7 +57,7 @@ <description> Constructs a [NodePath] from a [String]. The created path is absolute if prefixed with a slash (see [method is_absolute]). The "subnames" optionally included after the path to the target node can point to properties, and can also be nested. - Examples of strings that could be node paths: + The following strings can be valid node paths: [codeblock] # Points to the Sprite2D node. "Level/RigidBody2D/Sprite2D" diff --git a/doc/classes/OS.xml b/doc/classes/OS.xml index 777950c075..49350597f5 100644 --- a/doc/classes/OS.xml +++ b/doc/classes/OS.xml @@ -53,7 +53,7 @@ Creates a new process that runs independently of Godot. It will not terminate when Godot terminates. The path specified in [param path] must exist and be an executable file or macOS [code].app[/code] bundle. The path is resolved based on the current platform. The [param arguments] are used in the given order and separated by a space. On Windows, if [param open_console] is [code]true[/code] and the process is a console app, a new terminal window will be opened. If the process is successfully created, this method returns its process ID, which you can use to monitor the process (and potentially terminate it with [method kill]). Otherwise, this method returns [code]-1[/code]. - For example, running another instance of the project: + [b]Example:[/b] Run another instance of the project: [codeblocks] [gdscript] var pid = OS.create_process(OS.get_executable_path(), []) @@ -184,7 +184,7 @@ Command-line arguments can be written in any form, including both [code]--key value[/code] and [code]--key=value[/code] forms so they can be properly parsed, as long as custom command-line arguments do not conflict with engine arguments. You can also incorporate environment variables using the [method get_environment] method. You can set [member ProjectSettings.editor/run/main_run_args] to define command-line arguments to be passed by the editor when running the project. - Here's a minimal example on how to parse command-line arguments into a [Dictionary] using the [code]--key=value[/code] form for arguments: + [b]Example:[/b] Parse command-line arguments into a [Dictionary] using the [code]--key=value[/code] form for arguments: [codeblocks] [gdscript] var arguments = {} @@ -356,7 +356,7 @@ <return type="String" /> <description> Returns the model name of the current device. - [b]Note:[/b] This method is implemented on Android and iOS. Returns [code]"GenericDevice"[/code] on unsupported platforms. + [b]Note:[/b] This method is implemented on Android, iOS, macOS, and Windows. Returns [code]"GenericDevice"[/code] on unsupported platforms. </description> </method> <method name="get_name" qualifiers="const"> diff --git a/doc/classes/Object.xml b/doc/classes/Object.xml index 2767a11e80..81f666dd16 100644 --- a/doc/classes/Object.xml +++ b/doc/classes/Object.xml @@ -454,7 +454,7 @@ <return type="Variant" /> <param index="0" name="method" type="StringName" /> <description> - Calls the [param method] on the object during idle time. Always returns null, [b]not[/b] the method's result. + Calls the [param method] on the object during idle time. Always returns [code]null[/code], [b]not[/b] the method's result. Idle time happens mainly at the end of process and physics frames. In it, deferred calls will be run until there are none left, which means you can defer calls from other deferred calls and they'll still be run in the current idle time cycle. This means you should not call a method deferred from itself (or from a method called by it), as this causes infinite recursion the same way as if you had called the method directly. This method supports a variable number of arguments, so parameters can be passed as a comma separated list. [codeblocks] @@ -854,7 +854,7 @@ <param index="0" name="signal" type="StringName" /> <description> Returns [code]true[/code] if the given [param signal] name exists in the object. - [b]Note:[/b] In C#, [param signal] must be in snake_case when referring to built-in Godot methods. Prefer using the names exposed in the [code]SignalName[/code] class to avoid allocating a new [StringName] on each call. + [b]Note:[/b] In C#, [param signal] must be in snake_case when referring to built-in Godot signals. Prefer using the names exposed in the [code]SignalName[/code] class to avoid allocating a new [StringName] on each call. </description> </method> <method name="has_user_signal" qualifiers="const"> @@ -898,7 +898,7 @@ <param index="1" name="callable" type="Callable" /> <description> Returns [code]true[/code] if a connection exists between the given [param signal] name and [param callable]. - [b]Note:[/b] In C#, [param signal] must be in snake_case when referring to built-in Godot methods. Prefer using the names exposed in the [code]SignalName[/code] class to avoid allocating a new [StringName] on each call. + [b]Note:[/b] In C#, [param signal] must be in snake_case when referring to built-in Godot signals. Prefer using the names exposed in the [code]SignalName[/code] class to avoid allocating a new [StringName] on each call. </description> </method> <method name="is_queued_for_deletion" qualifiers="const"> diff --git a/doc/classes/OccluderInstance3D.xml b/doc/classes/OccluderInstance3D.xml index 6f45d72249..b3e6366c12 100644 --- a/doc/classes/OccluderInstance3D.xml +++ b/doc/classes/OccluderInstance3D.xml @@ -6,7 +6,7 @@ <description> Occlusion culling can improve rendering performance in closed/semi-open areas by hiding geometry that is occluded by other objects. The occlusion culling system is mostly static. [OccluderInstance3D]s can be moved or hidden at run-time, but doing so will trigger a background recomputation that can take several frames. It is recommended to only move [OccluderInstance3D]s sporadically (e.g. for procedural generation purposes), rather than doing so every frame. - The occlusion culling system works by rendering the occluders on the CPU in parallel using [url=https://www.embree.org/]Embree[/url], drawing the result to a low-resolution buffer then using this to cull 3D nodes individually. In the 3D editor, you can preview the occlusion culling buffer by choosing [b]Perspective > Debug Advanced... > Occlusion Culling Buffer[/b] in the top-left corner of the 3D viewport. The occlusion culling buffer quality can be adjusted in the Project Settings. + The occlusion culling system works by rendering the occluders on the CPU in parallel using [url=https://www.embree.org/]Embree[/url], drawing the result to a low-resolution buffer then using this to cull 3D nodes individually. In the 3D editor, you can preview the occlusion culling buffer by choosing [b]Perspective > Display Advanced... > Occlusion Culling Buffer[/b] in the top-left corner of the 3D viewport. The occlusion culling buffer quality can be adjusted in the Project Settings. [b]Baking:[/b] Select an [OccluderInstance3D] node, then use the [b]Bake Occluders[/b] button at the top of the 3D editor. Only opaque materials will be taken into account; transparent materials (alpha-blended or alpha-tested) will be ignored by the occluder generation. [b]Note:[/b] Occlusion culling is only effective if [member ProjectSettings.rendering/occlusion_culling/use_occlusion_culling] is [code]true[/code]. Enabling occlusion culling has a cost on the CPU. Only enable occlusion culling if you actually plan to use it. Large open scenes with few or no objects blocking the view will generally not benefit much from occlusion culling. Large open scenes generally benefit more from mesh LOD and visibility ranges ([member GeometryInstance3D.visibility_range_begin] and [member GeometryInstance3D.visibility_range_end]) compared to occlusion culling. [b]Note:[/b] Due to memory constraints, occlusion culling is not supported by default in Web export templates. It can be enabled by compiling custom Web export templates with [code]module_raycast_enabled=yes[/code]. diff --git a/doc/classes/PCKPacker.xml b/doc/classes/PCKPacker.xml index ec0300c068..f8f7dbee01 100644 --- a/doc/classes/PCKPacker.xml +++ b/doc/classes/PCKPacker.xml @@ -26,11 +26,18 @@ <methods> <method name="add_file"> <return type="int" enum="Error" /> - <param index="0" name="pck_path" type="String" /> + <param index="0" name="target_path" type="String" /> <param index="1" name="source_path" type="String" /> <param index="2" name="encrypt" type="bool" default="false" /> <description> - Adds the [param source_path] file to the current PCK package at the [param pck_path] internal path (should start with [code]res://[/code]). + Adds the [param source_path] file to the current PCK package at the [param target_path] internal path. The [code]res://[/code] prefix for [param target_path] is optional and stripped internally. + </description> + </method> + <method name="add_file_removal"> + <return type="int" enum="Error" /> + <param index="0" name="target_path" type="String" /> + <description> + Registers a file removal of the [param target_path] internal path to the PCK. This is mainly used for patches. If the file at this path has been loaded from a previous PCK, it will be removed. The [code]res://[/code] prefix for [param target_path] is optional and stripped internally. </description> </method> <method name="flush"> diff --git a/doc/classes/PackedScene.xml b/doc/classes/PackedScene.xml index 415e468e21..baff5fed57 100644 --- a/doc/classes/PackedScene.xml +++ b/doc/classes/PackedScene.xml @@ -7,7 +7,7 @@ A simplified interface to a scene file. Provides access to operations and checks that can be performed on the scene resource itself. Can be used to save a node to a file. When saving, the node as well as all the nodes it owns get saved (see [member Node.owner] property). [b]Note:[/b] The node doesn't need to own itself. - [b]Example of loading a saved scene:[/b] + [b]Example:[/b] Load a saved scene: [codeblocks] [gdscript] # Use load() instead of preload() if the path isn't known at compile-time. @@ -22,7 +22,7 @@ AddChild(scene); [/csharp] [/codeblocks] - [b]Example of saving a node with different owners:[/b] The following example creates 3 objects: [Node2D] ([code]node[/code]), [RigidBody2D] ([code]body[/code]) and [CollisionObject2D] ([code]collision[/code]). [code]collision[/code] is a child of [code]body[/code] which is a child of [code]node[/code]. Only [code]body[/code] is owned by [code]node[/code] and [method pack] will therefore only save those two nodes, but not [code]collision[/code]. + [b]Example:[/b] Save a node with different owners. The following example creates 3 objects: [Node2D] ([code]node[/code]), [RigidBody2D] ([code]body[/code]) and [CollisionObject2D] ([code]collision[/code]). [code]collision[/code] is a child of [code]body[/code] which is a child of [code]node[/code]. Only [code]body[/code] is owned by [code]node[/code] and [method pack] will therefore only save those two nodes, but not [code]collision[/code]. [codeblocks] [gdscript] # Create the objects. diff --git a/doc/classes/PacketPeerUDP.xml b/doc/classes/PacketPeerUDP.xml index 12d3178797..05b6e646c0 100644 --- a/doc/classes/PacketPeerUDP.xml +++ b/doc/classes/PacketPeerUDP.xml @@ -4,7 +4,32 @@ UDP packet peer. </brief_description> <description> - UDP packet peer. Can be used to send raw UDP packets as well as [Variant]s. + UDP packet peer. Can be used to send and receive raw UDP packets as well as [Variant]s. + [b]Example:[/b] Send a packet: + [codeblock] + var peer = PacketPeerUDP.new() + + # Optionally, you can select the local port used to send the packet. + peer.bind(4444) + + peer.set_dest_address("1.1.1.1", 4433) + peer.put_packet("hello".to_utf8_buffer()) + [/codeblock] + [b]Example:[/b] Listen for packets: + [codeblock] + var peer + + func _ready(): + peer = PacketPeerUDP.new() + peer.bind(4433) + + + func _process(_delta): + if peer.get_available_packet_count() > 0: + var array_bytes = peer.get_packet() + var packet_string = array_bytes.get_string_from_ascii() + print("Received message: ", packet_string) + [/codeblock] [b]Note:[/b] When exporting to Android, make sure to enable the [code]INTERNET[/code] permission in the Android export preset before exporting the project or using one-click deploy. Otherwise, network communication of any kind will be blocked by Android. </description> <tutorials> diff --git a/doc/classes/PhysicalBone3D.xml b/doc/classes/PhysicalBone3D.xml index ca1948e8e1..eda9fd6af5 100644 --- a/doc/classes/PhysicalBone3D.xml +++ b/doc/classes/PhysicalBone3D.xml @@ -21,6 +21,9 @@ <return type="void" /> <param index="0" name="impulse" type="Vector3" /> <description> + Applies a directional impulse without affecting 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 "_integrate_forces" functions otherwise). + This is equivalent to using [method apply_impulse] at the body's center of mass. </description> </method> <method name="apply_impulse"> @@ -28,21 +31,27 @@ <param index="0" name="impulse" type="Vector3" /> <param index="1" name="position" type="Vector3" default="Vector3(0, 0, 0)" /> <description> + Applies a positioned impulse to the PhysicsBone3D. + 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 "_integrate_forces" functions otherwise). + [param position] is the offset from the PhysicsBone3D origin in global coordinates. </description> </method> <method name="get_bone_id" qualifiers="const"> <return type="int" /> <description> + Returns the unique identifier of the PhysicsBone3D. </description> </method> <method name="get_simulate_physics"> <return type="bool" /> <description> + Returns [code]true[/code] if the PhysicsBone3D is allowed to simulate physics. </description> </method> <method name="is_simulating_physics"> <return type="bool" /> <description> + Returns [code]true[/code] if the PhysicsBone3D is currently simulating physics. </description> </method> </methods> @@ -75,7 +84,7 @@ The body's friction, from [code]0[/code] (frictionless) to [code]1[/code] (max friction). </member> <member name="gravity_scale" type="float" setter="set_gravity_scale" getter="get_gravity_scale" default="1.0"> - This is multiplied by the global 3D gravity setting found in [b]Project > Project Settings > Physics > 3d[/b] to produce the body's gravity. For example, a value of 1 will be normal gravity, 2 will apply double gravity, and 0.5 will apply half gravity to this object. + This is multiplied by [member ProjectSettings.physics/3d/default_gravity] to produce this body's gravity. For example, a value of [code]1.0[/code] will apply normal gravity, [code]2.0[/code] will apply double the gravity, and [code]0.5[/code] will apply half the gravity to this body. </member> <member name="joint_offset" type="Transform3D" setter="set_joint_offset" getter="get_joint_offset" default="Transform3D(1, 0, 0, 0, 1, 0, 0, 0, 1, 0, 0, 0)"> Sets the joint's transform. @@ -87,7 +96,7 @@ Sets the joint type. See [enum JointType] for possible values. </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. + Damps the body's movement. By default, the body will use [member ProjectSettings.physics/3d/default_linear_damp] or any value override set by an [Area3D] the body is in. Depending on [member linear_damp_mode], [member linear_damp] may be added to or replace the body's damping value. See [member ProjectSettings.physics/3d/default_linear_damp] for more details about damping. </member> <member name="linear_damp_mode" type="int" setter="set_linear_damp_mode" getter="get_linear_damp_mode" enum="PhysicalBone3D.DampMode" default="0"> @@ -108,16 +117,22 @@ In this mode, the body's damping value replaces any value set in areas or the default value. </constant> <constant name="JOINT_TYPE_NONE" value="0" enum="JointType"> + No joint is applied to the PhysicsBone3D. </constant> <constant name="JOINT_TYPE_PIN" value="1" enum="JointType"> + A pin joint is applied to the PhysicsBone3D. </constant> <constant name="JOINT_TYPE_CONE" value="2" enum="JointType"> + A cone joint is applied to the PhysicsBone3D. </constant> <constant name="JOINT_TYPE_HINGE" value="3" enum="JointType"> + A hinge joint is applied to the PhysicsBone3D. </constant> <constant name="JOINT_TYPE_SLIDER" value="4" enum="JointType"> + A slider joint is applied to the PhysicsBone3D. </constant> <constant name="JOINT_TYPE_6DOF" value="5" enum="JointType"> + A 6 degrees of freedom joint is applied to the PhysicsBone3D. </constant> </constants> </class> diff --git a/doc/classes/PopupMenu.xml b/doc/classes/PopupMenu.xml index d73cda7460..9fd47cf7f5 100644 --- a/doc/classes/PopupMenu.xml +++ b/doc/classes/PopupMenu.xml @@ -135,8 +135,6 @@ 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]. 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 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] Multistate items don't update their state automatically and must be done manually. See [method toggle_item_multistate], [method set_item_multistate] and [method get_item_multistate] for more info on how to control it. - Example usage: [codeblock] func _ready(): add_multistate_item("Item", 3, 0) @@ -152,6 +150,7 @@ print("Third state") ) [/codeblock] + [b]Note:[/b] Multistate items don't update their state automatically and must be done manually. See [method toggle_item_multistate], [method set_item_multistate] and [method get_item_multistate] for more info on how to control it. </description> </method> <method name="add_radio_check_item"> diff --git a/doc/classes/PrimitiveMesh.xml b/doc/classes/PrimitiveMesh.xml index 58a8da12da..ba48d2dcf5 100644 --- a/doc/classes/PrimitiveMesh.xml +++ b/doc/classes/PrimitiveMesh.xml @@ -18,7 +18,8 @@ <method name="get_mesh_arrays" qualifiers="const"> <return type="Array" /> <description> - Returns mesh arrays used to constitute surface of [Mesh]. The result can be passed to [method ArrayMesh.add_surface_from_arrays] to create a new surface. For example: + Returns the mesh arrays used to make up the surface of this primitive mesh. + [b]Example:[/b] Pass the result to [method ArrayMesh.add_surface_from_arrays] to create a new surface: [codeblocks] [gdscript] var c = CylinderMesh.new() diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml index 1e571e58a1..91961fcf02 100644 --- a/doc/classes/ProjectSettings.xml +++ b/doc/classes/ProjectSettings.xml @@ -10,6 +10,7 @@ [b]Overriding:[/b] Any project setting can be overridden by creating a file named [code]override.cfg[/code] in the project's root directory. This can also be used in exported projects by placing this file in the same directory as the project binary. Overriding will still take the base project settings' [url=$DOCS_URL/tutorials/export/feature_tags.html]feature tags[/url] in account. Therefore, make sure to [i]also[/i] override the setting with the desired feature tags if you want them to override base project settings on all platforms and configurations. </description> <tutorials> + <link title="Project Settings">$DOCS_URL/tutorials/editor/project_settings.html</link> <link title="3D Physics Tests Demo">https://godotengine.org/asset-library/asset/2747</link> <link title="3D Platformer Demo">https://godotengine.org/asset-library/asset/2748</link> <link title="Operating System Testing Demo">https://godotengine.org/asset-library/asset/2789</link> @@ -102,7 +103,7 @@ <param index="0" name="name" type="StringName" /> <description> Similar to [method get_setting], but applies feature tag overrides if any exists and is valid. - [b]Example:[/b] If the setting override [code]"application/config/name.windows"[/code] exists, and the following code is executed on a [i]Windows[/i] operating system, the overridden setting is printed instead: + [b]Example:[/b] If the setting override [code]"application/config/name.windows"[/code] exists, and the following code is executed on a [i]Windows[/i] operating system, the overridden setting is printed instead: [codeblocks] [gdscript] print(ProjectSettings.get_setting_with_override("application/config/name")) @@ -376,6 +377,7 @@ <member name="audio/driver/driver" type="String" setter="" getter=""> Specifies the audio driver to use. This setting is platform-dependent as each platform supports different audio drivers. If left empty, the default audio driver will be used. The [code]Dummy[/code] audio driver disables all audio playback and recording, which is useful for non-game applications as it reduces CPU usage. It also prevents the engine from appearing as an application playing audio in the OS' audio mixer. + To query the value that is being used at run-time (which may be overridden by command-line arguments or headless mode), use [method AudioServer.get_driver_name]. [b]Note:[/b] The driver in use can be overridden at runtime via the [code]--audio-driver[/code] [url=$DOCS_URL/tutorials/editor/command_line_tutorial.html]command line argument[/url]. </member> <member name="audio/driver/enable_input" type="bool" setter="" getter="" default="false"> @@ -467,10 +469,10 @@ If the [code]--log-file <file>[/code] [url=$DOCS_URL/tutorials/editor/command_line_tutorial.html]command line argument[/url] is used, log rotation is always disabled. </member> <member name="debug/gdscript/warnings/assert_always_false" type="int" setter="" getter="" default="1"> - When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when an [code]assert[/code] call always evaluates to false. + When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when an [code]assert[/code] call always evaluates to [code]false[/code]. </member> <member name="debug/gdscript/warnings/assert_always_true" type="int" setter="" getter="" default="1"> - When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when an [code]assert[/code] call always evaluates to true. + When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when an [code]assert[/code] call always evaluates to [code]true[/code]. </member> <member name="debug/gdscript/warnings/confusable_capture_reassignment" 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 local variable captured by a lambda is reassigned, since this does not modify the outer local variable. @@ -559,10 +561,10 @@ When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when defining a local or member variable, signal, or enum that would have the same name as a built-in function or global class name, thus shadowing it. </member> <member name="debug/gdscript/warnings/shadowed_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 defining a local or member variable that would shadow a member variable that the class defines. + When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when a local variable or local constant shadows a member declared in the current class. </member> <member name="debug/gdscript/warnings/shadowed_variable_base_class" type="int" setter="" getter="" default="1"> - When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when defining a local or subclass member variable that would shadow a variable that is inherited from a parent class. + When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when a local variable or local constant shadows a member declared in a base class. </member> <member name="debug/gdscript/warnings/standalone_expression" 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 an expression that may have no effect on the surrounding code, such as writing [code]2 + 2[/code] as a statement. @@ -816,6 +818,17 @@ <member name="display/window/energy_saving/keep_screen_on" type="bool" setter="" getter="" default="true"> If [code]true[/code], keeps the screen on (even in case of inactivity), so the screensaver does not take over. Works on desktop and mobile platforms. </member> + <member name="display/window/frame_pacing/android/enable_frame_pacing" type="bool" setter="" getter="" default="true"> + Enable Swappy for stable frame pacing on Android. Highly recommended. + [b]Note:[/b] This option will be forced off when using OpenXR. + </member> + <member name="display/window/frame_pacing/android/swappy_mode" type="int" setter="" getter="" default="2"> + Swappy mode to use. The options are: + - pipeline_forced_on: Try to honor [member Engine.max_fps]. Pipelining is always on. This is the same behavior as Desktop PC. + - auto_fps_pipeline_forced_on: Autocalculate max fps. Actual max_fps will be between 0 and [member Engine.max_fps]. While this sounds convenient, beware that Swappy will often downgrade max fps until it finds something that can be met and sustained. That means if your game runs between 40fps and 60fps on a 60hz screen, after some time Swappy will downgrade max fps so that the game renders at perfect 30fps. + - auto_fps_auto_pipeline: Same as auto_fps_pipeline_forced_on, but if Swappy detects that rendering is very fast (e.g. it takes < 8ms to render on a 60hz screen) Swappy will disable pipelining to minimize input latency. This is the default. + [b]Note:[/b] If [member Engine.max_fps] is 0, actual max_fps will considered as to be the screen's refresh rate (often 60hz, 90hz or 120hz depending on device model and OS settings). + </member> <member name="display/window/handheld/orientation" type="int" setter="" getter="" default="0"> The default screen orientation to use on mobile devices. See [enum DisplayServer.ScreenOrientation] for possible values. [b]Note:[/b] When set to a portrait orientation, this project setting does not flip the project resolution's width and height automatically. Instead, you have to set [member display/window/size/viewport_width] and [member display/window/size/viewport_height] accordingly. @@ -2354,6 +2367,10 @@ <member name="rendering/2d/batching/item_buffer_size" type="int" setter="" getter="" default="16384"> Maximum number of canvas item commands that can be batched into a single draw call. </member> + <member name="rendering/2d/batching/uniform_set_cache_size" type="int" setter="" getter="" default="256"> + Maximum number of uniform sets that will be cached by the 2D renderer when batching draw calls. + [b]Note:[/b] A project that uses a large number of unique sprite textures per frame may benefit from increasing this value. + </member> <member name="rendering/2d/sdf/oversize" type="int" setter="" getter="" default="1"> Controls how much of the original viewport size should be covered by the 2D signed distance field. This SDF can be sampled in [CanvasItem] shaders and is used for [GPUParticles2D] collision. Higher values allow portions of occluders located outside the viewport to still be taken into account in the generated signed distance field, at the cost of performance. If you notice particles falling through [LightOccluder2D]s as the occluders leave the viewport, increase this setting. The percentage specified is added on each axis and on both sides. For example, with the default setting of 120%, the signed distance field will cover 20% of the viewport's size outside the viewport on each side (top, right, bottom, left). @@ -2457,10 +2474,10 @@ Number of blur passes to use when computing screen-space ambient occlusion. A higher number will result in a smoother look, but will be slower to compute and will have less high-frequency detail. </member> <member name="rendering/environment/ssao/fadeout_from" type="float" setter="" getter="" default="50.0"> - Distance at which the screen-space ambient occlusion effect starts to fade out. Use this hide ambient occlusion at great distances. + Distance at which the screen-space ambient occlusion effect starts to fade out. Use this hide ambient occlusion from far away. </member> <member name="rendering/environment/ssao/fadeout_to" type="float" setter="" getter="" default="300.0"> - Distance at which the screen-space ambient occlusion is fully faded out. Use this hide ambient occlusion at great distances. + Distance at which the screen-space ambient occlusion is fully faded out. Use this hide ambient occlusion from far away. </member> <member name="rendering/environment/ssao/half_size" type="bool" setter="" getter="" default="true"> If [code]true[/code], screen-space ambient occlusion will be rendered at half size and then upscaled before being added to the scene. This is significantly faster but may miss small details. If [code]false[/code], screen-space ambient occlusion will be rendered at full size. @@ -2475,10 +2492,10 @@ Number of blur passes to use when computing screen-space indirect lighting. A higher number will result in a smoother look, but will be slower to compute and will have less high-frequency detail. </member> <member name="rendering/environment/ssil/fadeout_from" type="float" setter="" getter="" default="50.0"> - Distance at which the screen-space indirect lighting effect starts to fade out. Use this hide screen-space indirect lighting at great distances. + Distance at which the screen-space indirect lighting effect starts to fade out. Use this to hide screen-space indirect lighting from far away. </member> <member name="rendering/environment/ssil/fadeout_to" type="float" setter="" getter="" default="300.0"> - Distance at which the screen-space indirect lighting is fully faded out. Use this hide screen-space indirect lighting at great distances. + Distance at which the screen-space indirect lighting is fully faded out. Use this to hide screen-space indirect lighting from far away. </member> <member name="rendering/environment/ssil/half_size" type="bool" setter="" getter="" default="true"> If [code]true[/code], screen-space indirect lighting will be rendered at half size and then upscaled before being added to the scene. This is significantly faster but may miss small details and may result in some objects appearing to glow at their edges. @@ -2761,6 +2778,8 @@ [b]Forward Plus[/b]: High-end renderer designed for Desktop devices. Has a higher base overhead, but scales well with complex scenes. Not suitable for older devices or mobile. [b]Mobile[/b]: Modern renderer designed for mobile devices. Has a lower base overhead than Forward Plus, but does not scale as well to large scenes with many elements. [b]GL Compatibility[/b]: Low-end renderer designed for older devices. Based on the limitations of the OpenGL 3.3/ OpenGL ES 3.0 / WebGL 2 APIs. + This can be overridden using the [code]--rendering-method <method>[/code] command line argument. + [b]Note:[/b] The actual rendering method may be automatically changed by the engine as a result of a fallback, or a user-specified command line argument. To get the actual rendering method that is used at runtime, use [method RenderingServer.get_current_rendering_method] instead of reading this project setting's value. </member> <member name="rendering/renderer/rendering_method.mobile" type="String" setter="" getter="" default=""mobile""> Override for [member rendering/renderer/rendering_method] on mobile devices. @@ -2784,7 +2803,8 @@ Depending on the complexity of scenes, this value may be lowered or may need to be raised. </member> <member name="rendering/rendering_device/driver" type="String" setter="" getter=""> - Sets the driver to be used by the renderer when using a RenderingDevice-based renderer like the clustered renderer or the mobile renderer. This property can not be edited directly, instead, set the driver using the platform-specific overrides. + Sets the driver to be used by the renderer when using a RenderingDevice-based renderer like the clustered renderer or the mobile renderer. This property can't be edited directly. Instead, set the driver using the platform-specific overrides. This can be overridden using the [code]--rendering-driver <driver>[/code] command line argument. + [b]Note:[/b] The actual rendering driver may be automatically changed by the engine as a result of a fallback, or a user-specified command line argument. To get the actual rendering driver that is used at runtime, use [method RenderingServer.get_current_rendering_driver_name] instead of reading this project setting's value. </member> <member name="rendering/rendering_device/driver.android" type="String" setter="" getter=""> Android override for [member rendering/rendering_device/driver]. @@ -2873,11 +2893,11 @@ 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. </member> <member name="rendering/textures/canvas_textures/default_texture_filter" type="int" setter="" getter="" default="1"> - The default texture filtering mode to use on [CanvasItem]s. + The default texture filtering mode to use for [CanvasItem]s built-in texture. In shaders, this texture is accessed as [code]TEXTURE[/code]. [b]Note:[/b] For pixel art aesthetics, see also [member rendering/2d/snap/snap_2d_vertices_to_pixel] and [member rendering/2d/snap/snap_2d_transforms_to_pixel]. </member> <member name="rendering/textures/canvas_textures/default_texture_repeat" type="int" setter="" getter="" default="0"> - The default texture repeating mode to use on [CanvasItem]s. + The default texture repeating mode to use for [CanvasItem]s built-in texture. In shaders, this texture is accessed as [code]TEXTURE[/code]. </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]. @@ -2997,7 +3017,7 @@ Specify whether OpenXR should be configured for an HMD or a hand held device. </member> <member name="xr/openxr/foveation_dynamic" type="bool" setter="" getter="" default="false"> - If true and foveation is supported, will automatically adjust foveation level based on framerate up to the level set on [member xr/openxr/foveation_level]. + If [code]true[/code] and foveation is supported, will automatically adjust foveation level based on framerate up to the level set on [member xr/openxr/foveation_level]. [b]Note:[/b] Only works on the Compatibility rendering method. </member> <member name="xr/openxr/foveation_level" type="int" setter="" getter="" default=""0""> diff --git a/doc/classes/Projection.xml b/doc/classes/Projection.xml index 1665660da3..f781083abf 100644 --- a/doc/classes/Projection.xml +++ b/doc/classes/Projection.xml @@ -14,7 +14,8 @@ <constructor name="Projection"> <return type="Projection" /> <description> - Constructs a default-initialized [Projection] set to [constant IDENTITY]. + Constructs a default-initialized [Projection] identical to [constant IDENTITY]. + [b]Note:[/b] In C#, this constructs a [Projection] identical to [constant ZERO]. </description> </constructor> <constructor name="Projection"> diff --git a/doc/classes/Quaternion.xml b/doc/classes/Quaternion.xml index 665c6335f2..c74a6453e0 100644 --- a/doc/classes/Quaternion.xml +++ b/doc/classes/Quaternion.xml @@ -22,6 +22,7 @@ <return type="Quaternion" /> <description> Constructs a [Quaternion] identical to the [constant IDENTITY]. + [b]Note:[/b] In C#, this constructs a [Quaternion] with all of its components set to [code]0.0[/code]. </description> </constructor> <constructor name="Quaternion"> diff --git a/doc/classes/RDPipelineDepthStencilState.xml b/doc/classes/RDPipelineDepthStencilState.xml index dc1e70eb55..425890bb8d 100644 --- a/doc/classes/RDPipelineDepthStencilState.xml +++ b/doc/classes/RDPipelineDepthStencilState.xml @@ -34,10 +34,10 @@ The method used for comparing the previous and current depth values. </member> <member name="depth_range_max" type="float" setter="set_depth_range_max" getter="get_depth_range_max" default="0.0"> - The maximum depth that returns true for [member enable_depth_range]. + The maximum depth that returns [code]true[/code] for [member enable_depth_range]. </member> <member name="depth_range_min" type="float" setter="set_depth_range_min" getter="get_depth_range_min" default="0.0"> - The minimum depth that returns true for [member enable_depth_range]. + The minimum depth that returns [code]true[/code] for [member enable_depth_range]. </member> <member name="enable_depth_range" type="bool" setter="set_enable_depth_range" getter="get_enable_depth_range" default="false"> If [code]true[/code], each depth value will be tested to see if it is between [member depth_range_min] and [member depth_range_max]. If it is outside of these values, it is discarded. @@ -46,7 +46,7 @@ If [code]true[/code], enables depth testing which allows objects to be automatically occluded by other objects based on their depth. This also allows objects to be partially occluded by other objects. If [code]false[/code], objects will appear in the order they were drawn (like in Godot's 2D renderer). </member> <member name="enable_depth_write" type="bool" setter="set_enable_depth_write" getter="get_enable_depth_write" default="false"> - If [code]true[/code], writes to the depth buffer whenever the depth test returns true. Only works when enable_depth_test is also true. + If [code]true[/code], writes to the depth buffer whenever the depth test returns [code]true[/code]. Only works when enable_depth_test is also [code]true[/code]. </member> <member name="enable_stencil" type="bool" setter="set_enable_stencil" getter="get_enable_stencil" default="false"> If [code]true[/code], enables stencil testing. There are separate stencil buffers for front-facing triangles and back-facing triangles. See properties that begin with "front_op" and properties with "back_op" for each. diff --git a/doc/classes/RDTextureFormat.xml b/doc/classes/RDTextureFormat.xml index f8de7feda0..ac875ab7c1 100644 --- a/doc/classes/RDTextureFormat.xml +++ b/doc/classes/RDTextureFormat.xml @@ -13,12 +13,14 @@ <return type="void" /> <param index="0" name="format" type="int" enum="RenderingDevice.DataFormat" /> <description> + Adds [param format] as a valid format for the corresponding [RDTextureView]'s [member RDTextureView.format_override] property. If any format is added as shareable, then the main [member format] must also be added. </description> </method> <method name="remove_shareable_format"> <return type="void" /> <param index="0" name="format" type="int" enum="RenderingDevice.DataFormat" /> <description> + Removes [param format] from the list of valid formats that the corresponding [RDTextureView]'s [member RDTextureView.format_override] property can be set to. </description> </method> </methods> diff --git a/doc/classes/RDTextureView.xml b/doc/classes/RDTextureView.xml index 30b6bfedf5..bd8102d553 100644 --- a/doc/classes/RDTextureView.xml +++ b/doc/classes/RDTextureView.xml @@ -10,7 +10,7 @@ </tutorials> <members> <member name="format_override" type="int" setter="set_format_override" getter="get_format_override" enum="RenderingDevice.DataFormat" default="218"> - Optional override for the data format to return sampled values in. The default value of [constant RenderingDevice.DATA_FORMAT_MAX] does not override the format. + Optional override for the data format to return sampled values in. The corresponding [RDTextureFormat] must have had this added as a shareable format. The default value of [constant RenderingDevice.DATA_FORMAT_MAX] does not override the format. </member> <member name="swizzle_a" type="int" setter="set_swizzle_a" getter="get_swizzle_a" enum="RenderingDevice.TextureSwizzle" default="6"> The channel to sample when sampling the alpha channel. diff --git a/doc/classes/RenderSceneBuffersRD.xml b/doc/classes/RenderSceneBuffersRD.xml index 212a65337e..7b5aac5b61 100644 --- a/doc/classes/RenderSceneBuffersRD.xml +++ b/doc/classes/RenderSceneBuffersRD.xml @@ -61,7 +61,7 @@ <param index="1" name="msaa" type="bool" default="false" /> <description> Returns the specified layer from the color texture we are rendering 3D content to. - If [param msaa] is [b]true[/b] and MSAA is enabled, this returns the MSAA variant of the buffer. + If [param msaa] is [code]true[/code] and MSAA is enabled, this returns the MSAA variant of the buffer. </description> </method> <method name="get_color_texture"> @@ -69,7 +69,7 @@ <param index="0" name="msaa" type="bool" default="false" /> <description> Returns the color texture we are rendering 3D content to. If multiview is used this will be a texture array with all views. - If [param msaa] is [b]true[/b] and MSAA is enabled, this returns the MSAA variant of the buffer. + If [param msaa] is [code]true[/code] and MSAA is enabled, this returns the MSAA variant of the buffer. </description> </method> <method name="get_depth_layer"> @@ -78,7 +78,7 @@ <param index="1" name="msaa" type="bool" default="false" /> <description> Returns the specified layer from the depth texture we are rendering 3D content to. - If [param msaa] is [b]true[/b] and MSAA is enabled, this returns the MSAA variant of the buffer. + If [param msaa] is [code]true[/code] and MSAA is enabled, this returns the MSAA variant of the buffer. </description> </method> <method name="get_depth_texture"> @@ -86,7 +86,7 @@ <param index="0" name="msaa" type="bool" default="false" /> <description> Returns the depth texture we are rendering 3D content to. If multiview is used this will be a texture array with all views. - If [param msaa] is [b]true[/b] and MSAA is enabled, this returns the MSAA variant of the buffer. + If [param msaa] is [code]true[/code] and MSAA is enabled, this returns the MSAA variant of the buffer. </description> </method> <method name="get_fsr_sharpness" qualifiers="const"> diff --git a/doc/classes/RenderingDevice.xml b/doc/classes/RenderingDevice.xml index 2ff7e934e9..fe23f79119 100644 --- a/doc/classes/RenderingDevice.xml +++ b/doc/classes/RenderingDevice.xml @@ -324,6 +324,18 @@ Submits [param draw_list] for rendering on the GPU. This is the raster equivalent to [method compute_list_dispatch]. </description> </method> + <method name="draw_list_draw_indirect"> + <return type="void" /> + <param index="0" name="draw_list" type="int" /> + <param index="1" name="use_indices" type="bool" /> + <param index="2" name="buffer" type="RID" /> + <param index="3" name="offset" type="int" default="0" /> + <param index="4" name="draw_count" type="int" default="1" /> + <param index="5" name="stride" type="int" default="0" /> + <description> + Submits [param draw_list] for rendering on the GPU with the given parameters stored in the [param buffer] at [param offset]. Parameters being integers: vertex count, instance count, first vertex, first instance. And when using indices: index count, instance count, first index, vertex offset, first instance. Buffer must have been created with [constant STORAGE_BUFFER_USAGE_DISPATCH_INDIRECT] flag. + </description> + </method> <method name="draw_list_enable_scissor"> <return type="void" /> <param index="0" name="draw_list" type="int" /> diff --git a/doc/classes/RenderingServer.xml b/doc/classes/RenderingServer.xml index 66a69b7902..26f80630bb 100644 --- a/doc/classes/RenderingServer.xml +++ b/doc/classes/RenderingServer.xml @@ -224,7 +224,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. + 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 [code]false[/code]. </description> </method> <method name="canvas_item_add_lcd_texture_rect_region"> @@ -1278,6 +1278,14 @@ Sets the intensity of the background color. </description> </method> + <method name="environment_set_camera_id"> + <return type="void" /> + <param index="0" name="env" type="RID" /> + <param index="1" name="id" type="int" /> + <description> + Sets the camera ID to be used as environment background. + </description> + </method> <method name="environment_set_canvas_max_layer"> <return type="void" /> <param index="0" name="env" type="RID" /> @@ -1540,6 +1548,20 @@ Tries to free an object in the RenderingServer. To avoid memory leaks, this should be called after using an object as memory management does not occur automatically when using RenderingServer directly. </description> </method> + <method name="get_current_rendering_driver_name" qualifiers="const"> + <return type="String" /> + <description> + Returns the name of the current rendering driver. This can be [code]vulkan[/code], [code]d3d12[/code], [code]metal[/code], [code]opengl3[/code], [code]opengl3_es[/code], or [code]opengl3_angle[/code]. See also [method get_current_rendering_method]. + The rendering driver is determined by [member ProjectSettings.rendering/rendering_device/driver], the [code]--rendering-driver[/code] command line argument that overrides this project setting, or an automatic fallback that is applied depending on the hardware. + </description> + </method> + <method name="get_current_rendering_method" qualifiers="const"> + <return type="String" /> + <description> + Returns the name of the current rendering method. This can be [code]forward_plus[/code], [code]mobile[/code], or [code]gl_compatibility[/code]. See also [method get_current_rendering_driver_name]. + The rendering method is determined by [member ProjectSettings.rendering/renderer/rendering_method], the [code]--rendering-method[/code] command line argument that overrides this project setting, or an automatic fallback that is applied depending on the hardware. + </description> + </method> <method name="get_default_clear_color"> <return type="Color" /> <description> @@ -1592,7 +1614,7 @@ <return type="RID" /> <description> Returns the RID of a 256×256 texture with a testing pattern on it (in [constant Image.FORMAT_RGB8] format). This texture will be created and returned on the first call to [method get_test_texture], then it will be cached for subsequent calls. See also [method get_white_texture]. - Example of getting the test texture and applying it to a [Sprite2D] node: + [b]Example:[/b] Get the test texture and apply it to a [Sprite2D] node: [codeblock] var texture_rid = RenderingServer.get_test_texture() var texture = ImageTexture.create_from_image(RenderingServer.texture_2d_get(texture_rid)) @@ -1633,7 +1655,7 @@ <return type="RID" /> <description> Returns the ID of a 4×4 white texture (in [constant Image.FORMAT_RGB8] format). This texture will be created and returned on the first call to [method get_white_texture], then it will be cached for subsequent calls. See also [method get_test_texture]. - Example of getting the white texture and applying it to a [Sprite2D] node: + [b]Example:[/b] Get the white texture and apply it to a [Sprite2D] node: [codeblock] var texture_rid = RenderingServer.get_white_texture() var texture = ImageTexture.create_from_image(RenderingServer.texture_2d_get(texture_rid)) @@ -2137,6 +2159,14 @@ If [code]true[/code], light will cast shadows. Equivalent to [member Light3D.shadow_enabled]. </description> </method> + <method name="light_set_shadow_caster_mask"> + <return type="void" /> + <param index="0" name="light" type="RID" /> + <param index="1" name="mask" type="int" /> + <description> + Sets the shadow caster mask for this 3D light. Shadows will only be cast using objects in the selected layers. Equivalent to [member Light3D.shadow_caster_mask]. + </description> + </method> <method name="lightmap_create"> <return type="RID" /> <description> @@ -2941,7 +2971,7 @@ <param index="0" name="particles" type="RID" /> <param index="1" name="emitting" type="bool" /> <description> - If [code]true[/code], particles will emit over time. Setting to false does not reset the particles, but only stops their emission. Equivalent to [member GPUParticles3D.emitting]. + If [code]true[/code], particles will emit over time. Setting to [code]false[/code] does not reset the particles, but only stops their emission. Equivalent to [member GPUParticles3D.emitting]. </description> </method> <method name="particles_set_explosiveness_ratio"> @@ -3498,7 +3528,7 @@ <param index="0" name="texture" type="RID" /> <description> Returns an [Image] instance from the given [param texture] [RID]. - Example of getting the test texture from [method get_test_texture] and applying it to a [Sprite2D] node: + [b]Example:[/b] Get the test texture from [method get_test_texture] and apply it to a [Sprite2D] node: [codeblock] var texture_rid = RenderingServer.get_test_texture() var texture = ImageTexture.create_from_image(RenderingServer.texture_2d_get(texture_rid)) diff --git a/doc/classes/Resource.xml b/doc/classes/Resource.xml index 18d4047339..0f3a231cb7 100644 --- a/doc/classes/Resource.xml +++ b/doc/classes/Resource.xml @@ -37,7 +37,7 @@ <return type="void" /> <description> Override this method to customize the newly duplicated resource created from [method PackedScene.instantiate], if the original's [member resource_local_to_scene] is set to [code]true[/code]. - [b]Example:[/b] Set a random [code]damage[/code] value to every local resource from an instantiated scene. + [b]Example:[/b] Set a random [code]damage[/code] value to every local resource from an instantiated scene: [codeblock] extends Resource diff --git a/doc/classes/ResourceFormatLoader.xml b/doc/classes/ResourceFormatLoader.xml index 4e4adc86c4..cdbf8b3f9a 100644 --- a/doc/classes/ResourceFormatLoader.xml +++ b/doc/classes/ResourceFormatLoader.xml @@ -57,6 +57,7 @@ <return type="int" /> <param index="0" name="path" type="String" /> <description> + Should return the unique ID for the resource associated with the given path. If this method is not overridden, a [code].uid[/code] file is generated along with the resource file, containing the unique ID. </description> </method> <method name="_handles_type" qualifiers="virtual const"> diff --git a/doc/classes/ResourceImporterOBJ.xml b/doc/classes/ResourceImporterOBJ.xml index a63dddb0e8..084638f62b 100644 --- a/doc/classes/ResourceImporterOBJ.xml +++ b/doc/classes/ResourceImporterOBJ.xml @@ -14,6 +14,19 @@ <member name="force_disable_mesh_compression" type="bool" setter="" getter="" default="false"> If [code]true[/code], mesh compression will not be used. Consider enabling if you notice blocky artifacts in your mesh normals or UVs, or if you have meshes that are larger than a few thousand meters in each direction. </member> + <member name="generate_lightmap_uv2" type="bool" setter="" getter="" default="false"> + If [code]true[/code], generates UV2 on import for [LightmapGI] baking. + </member> + <member name="generate_lightmap_uv2_texel_size" type="float" setter="" getter="" default="0.2"> + Controls the size of each texel on the baked lightmap. A smaller value results in more precise lightmaps, at the cost of larger lightmap sizes and longer bake times. + [b]Note:[/b] Only effective if [member generate_lightmap_uv2] is [code]true[/code]. + </member> + <member name="generate_lods" type="bool" setter="" getter="" default="true"> + If [code]true[/code], generates lower detail variants of the mesh which will be displayed in the distance to improve rendering performance. Not all meshes benefit from LOD, especially if they are never rendered from far away. Disabling this can reduce output file size and speed up importing. See [url=$DOCS_URL/tutorials/3d/mesh_lod.html#doc-mesh-lod]Mesh level of detail (LOD)[/url] for more information. + </member> + <member name="generate_shadow_mesh" type="bool" setter="" getter="" default="true"> + If [code]true[/code], enables the generation of shadow meshes on import. This optimizes shadow rendering without reducing quality by welding vertices together when possible. This in turn reduces the memory bandwidth required to render shadows. Shadow mesh generation currently doesn't support using a lower detail level than the source mesh (but shadow rendering will make use of LODs when relevant). + </member> <member name="generate_tangents" type="bool" setter="" getter="" default="true"> If [code]true[/code], generate vertex tangents using [url=http://www.mikktspace.com/]Mikktspace[/url] if the source mesh doesn't have tangent data. When possible, it's recommended to let the 3D modeling software generate tangents on export instead on relying on this option. Tangents are required for correct display of normal and height maps, along with any material/shader features that require tangents. If you don't need material features that require tangents, disabling this can reduce output file size and speed up importing if the source 3D file doesn't contain tangents. diff --git a/doc/classes/ResourceLoader.xml b/doc/classes/ResourceLoader.xml index 56c3208fc3..ae862dd52f 100644 --- a/doc/classes/ResourceLoader.xml +++ b/doc/classes/ResourceLoader.xml @@ -7,6 +7,7 @@ A singleton used to load resource files from the filesystem. It uses the many [ResourceFormatLoader] classes registered in the engine (either built-in or from a plugin) to load files into memory and convert them to a format that can be used by the engine. [b]Note:[/b] You have to import the files into the engine first to load them using [method load]. If you want to load [Image]s at run-time, you may use [method Image.load]. If you want to import audio files, you can use the snippet described in [member AudioStreamMP3.data]. + [b]Note:[/b] Non-resource files such as plain text files cannot be read using [ResourceLoader]. Use [FileAccess] for those files instead, and be aware that non-resource files are not exported by default (see notes in the [FileAccess] class description for instructions on exporting them). </description> <tutorials> <link title="Operating System Testing Demo">https://godotengine.org/asset-library/asset/2789</link> @@ -74,6 +75,13 @@ Once a resource has been loaded by the engine, it is cached in memory for faster access, and future calls to the [method load] method will use the cached version. The cached resource can be overridden by using [method Resource.take_over_path] on a new resource for that same path. </description> </method> + <method name="list_directory"> + <return type="PackedStringArray" /> + <param index="0" name="directory_path" type="String" /> + <description> + Lists a directory (as example: "res://assets/enemies"), returning all resources contained within. The resource files are the original file names as visible in the editor before exporting. + </description> + </method> <method name="load"> <return type="Resource" /> <param index="0" name="path" type="String" /> @@ -104,7 +112,7 @@ <param index="1" name="progress" type="Array" default="[]" /> <description> Returns the status of a threaded loading operation started with [method load_threaded_request] for the resource at [param path]. See [enum ThreadLoadStatus] for possible return values. - An array variable can optionally be passed via [param progress], and will return a one-element array containing the percentage of completion of the threaded loading. + An array variable can optionally be passed via [param progress], and will return a one-element array containing the ratio of completion of the threaded loading (between [code]0.0[/code] and [code]1.0[/code]). [b]Note:[/b] The recommended way of using this method is to call it during different frames (e.g., in [method Node._process], instead of a loop). </description> </method> diff --git a/doc/classes/RichTextLabel.xml b/doc/classes/RichTextLabel.xml index 4a2cbbc3d8..8472e57840 100644 --- a/doc/classes/RichTextLabel.xml +++ b/doc/classes/RichTextLabel.xml @@ -225,8 +225,8 @@ <return type="void" /> <param index="0" name="effect" type="Variant" /> <description> - Installs a custom effect. This can also be done in the RichTextLabel inspector using the [member custom_effects] property. [param effect] should be a valid [RichTextEffect]. - Example RichTextEffect: + Installs a custom effect. This can also be done in the Inspector through the [member custom_effects] property. [param effect] should be a valid [RichTextEffect]. + [b]Example:[/b] With the following script extending from [RichTextEffect]: [codeblock] # effect.gd class_name MyCustomEffect @@ -236,7 +236,7 @@ # ... [/codeblock] - Registering the above effect in RichTextLabel from script: + The above effect can be installed in [RichTextLabel] from a script: [codeblock] # rich_text_label.gd extends RichTextLabel @@ -810,7 +810,7 @@ The default background color for odd rows. </theme_item> <theme_item name="line_separation" data_type="constant" type="int" default="0"> - The vertical space between lines. + Additional vertical spacing between lines (in pixels), spacing is added to line descent. This value can be negative. </theme_item> <theme_item name="outline_size" data_type="constant" type="int" default="0"> The size of the text outline. diff --git a/doc/classes/RigidBody3D.xml b/doc/classes/RigidBody3D.xml index dae904e2a3..9a299ade57 100644 --- a/doc/classes/RigidBody3D.xml +++ b/doc/classes/RigidBody3D.xml @@ -179,7 +179,7 @@ For a body that is always frozen, use [StaticBody3D] or [AnimatableBody3D] instead. </member> <member name="gravity_scale" type="float" setter="set_gravity_scale" getter="get_gravity_scale" default="1.0"> - This is multiplied by the global 3D gravity setting found in [b]Project > Project Settings > Physics > 3d[/b] to produce RigidBody3D's gravity. For example, a value of 1 will be normal gravity, 2 will apply double gravity, and 0.5 will apply half gravity to this object. + This is multiplied by [member ProjectSettings.physics/3d/default_gravity] to produce this body's gravity. For example, a value of [code]1.0[/code] will apply normal gravity, [code]2.0[/code] will apply double the gravity, and [code]0.5[/code] will apply half the gravity to this body. </member> <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. diff --git a/doc/classes/Shader.xml b/doc/classes/Shader.xml index 1e7f9e5ee5..3fbe1da687 100644 --- a/doc/classes/Shader.xml +++ b/doc/classes/Shader.xml @@ -31,8 +31,8 @@ <return type="Array" /> <param index="0" name="get_groups" type="bool" default="false" /> <description> - Get the list of shader uniforms that can be assigned to a [ShaderMaterial], for use with [method ShaderMaterial.set_shader_parameter] and [method ShaderMaterial.get_shader_parameter]. The parameters returned are contained in dictionaries in a similar format to the ones returned by [method Object.get_property_list]. - If argument [param get_groups] is true, parameter grouping hints will be provided. + Returns the list of shader uniforms that can be assigned to a [ShaderMaterial], for use with [method ShaderMaterial.set_shader_parameter] and [method ShaderMaterial.get_shader_parameter]. The parameters returned are contained in dictionaries in a similar format to the ones returned by [method Object.get_property_list]. + If argument [param get_groups] is [code]true[/code], parameter grouping hints are also included in the list. </description> </method> <method name="inspect_native_shader_code"> diff --git a/doc/classes/Shortcut.xml b/doc/classes/Shortcut.xml index b1e931aef8..c0ff3ebdb5 100644 --- a/doc/classes/Shortcut.xml +++ b/doc/classes/Shortcut.xml @@ -5,7 +5,7 @@ </brief_description> <description> Shortcuts are commonly used for interacting with a [Control] element from an [InputEvent] (also known as hotkeys). - One shortcut can contain multiple [InputEvent]'s, allowing the possibility of triggering one action with multiple different inputs. + One shortcut can contain multiple [InputEvent]s, allowing the possibility of triggering one action with multiple different inputs. </description> <tutorials> </tutorials> diff --git a/doc/classes/SkeletonIK3D.xml b/doc/classes/SkeletonIK3D.xml index 4858a6ce22..dbb099a22b 100644 --- a/doc/classes/SkeletonIK3D.xml +++ b/doc/classes/SkeletonIK3D.xml @@ -31,7 +31,7 @@ <method name="get_parent_skeleton" qualifiers="const"> <return type="Skeleton3D" /> <description> - Returns the parent [Skeleton3D] Node that was present when SkeletonIK entered the [SceneTree]. Returns null if the parent node was not a [Skeleton3D] Node when SkeletonIK3D entered the [SceneTree]. + Returns the parent [Skeleton3D] node that was present when SkeletonIK entered the scene tree. Returns [code]null[/code] if the parent node was not a [Skeleton3D] node when SkeletonIK3D entered the scene tree. </description> </method> <method name="is_running"> diff --git a/doc/classes/SkeletonModification2DTwoBoneIK.xml b/doc/classes/SkeletonModification2DTwoBoneIK.xml index 1c7bb32f4a..d2417ba7bf 100644 --- a/doc/classes/SkeletonModification2DTwoBoneIK.xml +++ b/doc/classes/SkeletonModification2DTwoBoneIK.xml @@ -65,7 +65,7 @@ </methods> <members> <member name="flip_bend_direction" type="bool" setter="set_flip_bend_direction" getter="get_flip_bend_direction" default="false"> - If [code]true[/code], the bones in the modification will blend outward as opposed to inwards when contracting. If [code]false[/code], the bones will bend inwards when contracting. + If [code]true[/code], the bones in the modification will bend outward as opposed to inwards when contracting. If [code]false[/code], the bones will bend inwards when contracting. </member> <member name="target_maximum_distance" type="float" setter="set_target_maximum_distance" getter="get_target_maximum_distance" default="0.0"> The maximum distance the target can be at. If the target is farther than this distance, the modification will solve as if it's at this maximum distance. When set to [code]0[/code], the modification will solve without distance constraints. diff --git a/doc/classes/Slider.xml b/doc/classes/Slider.xml index a4ffa5c1e7..b1e78e8987 100644 --- a/doc/classes/Slider.xml +++ b/doc/classes/Slider.xml @@ -28,12 +28,12 @@ <signal name="drag_ended"> <param index="0" name="value_changed" type="bool" /> <description> - Emitted when dragging stops. If [param value_changed] is true, [member Range.value] is different from the value when you started the dragging. + Emitted when the grabber stops being dragged. If [param value_changed] is [code]true[/code], [member Range.value] is different from the value when the dragging was started. </description> </signal> <signal name="drag_started"> <description> - Emitted when dragging is started. This is emitted before the corresponding [signal Range.value_changed] signal. + Emitted when the grabber starts being dragged. This is emitted before the corresponding [signal Range.value_changed] signal. </description> </signal> </signals> diff --git a/doc/classes/SpringArm3D.xml b/doc/classes/SpringArm3D.xml index 99389fb78d..330317f352 100644 --- a/doc/classes/SpringArm3D.xml +++ b/doc/classes/SpringArm3D.xml @@ -7,6 +7,7 @@ [SpringArm3D] casts a ray or a shape along its Z axis and moves all its direct children to the collision point, with an optional margin. This is useful for 3rd person cameras that move closer to the player when inside a tight space (you may need to exclude the player's collider from the [SpringArm3D]'s collision check). </description> <tutorials> + <link title="Third-person camera with spring arm">$DOCS_URL/tutorials/3d/spring_arm.html</link> </tutorials> <methods> <method name="add_excluded_object"> diff --git a/doc/classes/String.xml b/doc/classes/String.xml index 40f08dafe6..e59734cf03 100644 --- a/doc/classes/String.xml +++ b/doc/classes/String.xml @@ -6,6 +6,7 @@ <description> This is the built-in string Variant type (and the one used by GDScript). Strings may contain any number of Unicode characters, and expose methods useful for manipulating and generating strings. Strings are reference-counted and use a copy-on-write approach (every modification to a string returns a new [String]), so passing them around is cheap in resources. 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. + To convert any Variant to or from a string, see [method @GlobalScope.str], [method @GlobalScope.str_to_var], and [method @GlobalScope.var_to_str]. [b]Note:[/b] In a boolean context, a string will evaluate to [code]false[/code] if it is empty ([code]""[/code]). Otherwise, a string will always evaluate to [code]true[/code]. </description> <tutorials> @@ -247,7 +248,7 @@ <param index="1" name="placeholder" type="String" default=""{_}"" /> <description> Formats the string by replacing all occurrences of [param placeholder] with the elements of [param values]. - [param values] can be a [Dictionary] or an [Array]. Any underscores in [param placeholder] will be replaced with the corresponding keys in advance. Array elements use their index as keys. + [param values] can be a [Dictionary], an [Array] or an [Object]. Any underscores in [param placeholder] will be replaced with the corresponding keys in advance. Array elements use their index as keys. [codeblock] # Prints "Waiting for Godot is a play by Samuel Beckett, and Godot Engine is named after it." var use_array_values = "Waiting for {0} is a play by {1}, and {0} Engine is named after it." @@ -262,13 +263,19 @@ print("User {} is {}.".format([42, "Godot"], "{}")) print("User {id} is {name}.".format([["id", 42], ["name", "Godot"]])) [/codeblock] + When passing an [Object], the property names from [method Object.get_property_list] are used as keys. + [codeblock] + # Prints: Visible true, position (0, 0). + var node = Node2D.new() + print("Visible {visible}, position {position}".format(node)) + [/codeblock] See also the [url=$DOCS_URL/tutorials/scripting/gdscript/gdscript_format_string.html]GDScript format string[/url] tutorial. - [b]Note:[/b] The replacement of placeholders is not done all at once, instead each placeholder is replaced in the order they are passed, this means that if one of the replacement strings contains a key it will also be replaced. This can be very powerful, but can also cause unexpected results if you are not careful. If you do not need to perform replacement in the replacement strings, make sure your replacements do not contain placeholders to ensure reliable results. + [b]Note:[/b] Each replacement is done sequentially for each element of [param values], [b]not[/b] all at once. This means that if any element is inserted and it contains another placeholder, it may be changed by the next replacement. While this can be very useful, it often causes unexpected results. If not necessary, make sure [param values]'s elements do not contain placeholders. [codeblock] - print("{0} {1}".format(["{1}", "x"])) # Prints "x x". - print("{0} {1}".format(["x", "{0}"])) # Prints "x {0}". - print("{foo} {bar}".format({"foo": "{bar}", "bar": "baz"})) # Prints "baz baz". - print("{foo} {bar}".format({"bar": "baz", "foo": "{bar}"})) # Prints "{bar} baz". + print("{0} {1}".format(["{1}", "x"])) # Prints "x x". + print("{0} {1}".format(["x", "{0}"])) # Prints "x {0}". + print("{a} {b}".format({"a": "{b}", "b": "c"})) # Prints "c c". + print("{a} {b}".format({"b": "c", "a": "{b}"})) # Prints "{b} c". [/codeblock] [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> @@ -880,7 +887,7 @@ <return type="float" /> <param index="0" name="text" type="String" /> <description> - Returns the similarity index ([url=https://en.wikipedia.org/wiki/S%C3%B8rensen%E2%80%93Dice_coefficient]Sorensen-Dice coefficient[/url]) of this string compared to another. A result of [code]1.0[/code] means totally similar, while [code]0.0[/code] means totally dissimilar. + Returns the similarity index ([url=https://en.wikipedia.org/wiki/S%C3%B8rensen%E2%80%93Dice_coefficient]Sørensen-Dice coefficient[/url]) of this string compared to another. A result of [code]1.0[/code] means totally similar, while [code]0.0[/code] means totally dissimilar. [codeblock] print("ABC123".similarity("ABC123")) # Prints 1.0 print("ABC123".similarity("XYZ456")) # Prints 0.0 diff --git a/doc/classes/StringName.xml b/doc/classes/StringName.xml index 3a2b492496..4982bc36a8 100644 --- a/doc/classes/StringName.xml +++ b/doc/classes/StringName.xml @@ -247,6 +247,13 @@ 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] Each replacement is done sequentially for each element of [param values], [b]not[/b] all at once. This means that if any element is inserted and it contains another placeholder, it may be changed by the next replacement. While this can be very useful, it often causes unexpected results. If not necessary, make sure [param values]'s elements do not contain placeholders. + [codeblock] + print("{0} {1}".format(["{1}", "x"])) # Prints "x x". + print("{0} {1}".format(["x", "{0}"])) # Prints "x {0}". + print("{a} {b}".format({"a": "{b}", "b": "c"})) # Prints "c c". + print("{a} {b}".format({"b": "c", "a": "{b}"})) # Prints "{b} c". + [/codeblock] [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> @@ -299,7 +306,7 @@ <param index="0" name="delimiter" type="String" /> <param index="1" name="slice" type="int" /> <description> - Splits the string using a [param delimiter] and returns the substring at index [param slice]. Returns an empty string if the [param slice] does not exist. + Splits the string using a [param delimiter] and returns the substring at index [param slice]. Returns the original string if [param delimiter] does not occur in the string. Returns an empty string if the [param slice] does not exist. This is faster than [method split], if you only need one substring. [codeblock] print("i/am/example/hi".get_slice("/", 2)) # Prints "example" @@ -782,7 +789,7 @@ <return type="float" /> <param index="0" name="text" type="String" /> <description> - Returns the similarity index ([url=https://en.wikipedia.org/wiki/S%C3%B8rensen%E2%80%93Dice_coefficient]Sorensen-Dice coefficient[/url]) of this string compared to another. A result of [code]1.0[/code] means totally similar, while [code]0.0[/code] means totally dissimilar. + Returns the similarity index ([url=https://en.wikipedia.org/wiki/S%C3%B8rensen%E2%80%93Dice_coefficient]Sørensen-Dice coefficient[/url]) of this string compared to another. A result of [code]1.0[/code] means totally similar, while [code]0.0[/code] means totally dissimilar. [codeblock] print("ABC123".similarity("ABC123")) # Prints 1.0 print("ABC123".similarity("XYZ456")) # Prints 0.0 @@ -871,7 +878,7 @@ <method name="to_ascii_buffer" qualifiers="const"> <return type="PackedByteArray" /> <description> - Converts the string to an [url=https://en.wikipedia.org/wiki/ASCII]ASCII[/url]/Latin-1 encoded [PackedByteArray]. This method is slightly faster than [method to_utf8_buffer], but replaces all unsupported characters with spaces. + Converts the string to an [url=https://en.wikipedia.org/wiki/ASCII]ASCII[/url]/Latin-1 encoded [PackedByteArray]. This method is slightly faster than [method to_utf8_buffer], but replaces all unsupported characters with spaces. This is the inverse of [method PackedByteArray.get_string_from_ascii]. </description> </method> <method name="to_camel_case" qualifiers="const"> @@ -885,11 +892,11 @@ <description> Converts the string representing a decimal number into a [float]. This method stops on the first non-number character, except the first decimal point ([code].[/code]) and the exponent letter ([code]e[/code]). See also [method is_valid_float]. [codeblock] - var a = "12.35".to_float() # a is 12.35 - var b = "1.2.3".to_float() # b is 1.2 - var c = "12xy3".to_float() # c is 12.0 - var d = "1e3".to_float() # d is 1000.0 - var e = "Hello!".to_int() # e is 0.0 + var a = "12.35".to_float() # a is 12.35 + var b = "1.2.3".to_float() # b is 1.2 + var c = "12xy3".to_float() # c is 12.0 + var d = "1e3".to_float() # d is 1000.0 + var e = "Hello!".to_float() # e is 0.0 [/codeblock] </description> </method> @@ -945,25 +952,25 @@ <method name="to_utf8_buffer" qualifiers="const"> <return type="PackedByteArray" /> <description> - Converts the string to a [url=https://en.wikipedia.org/wiki/UTF-8]UTF-8[/url] encoded [PackedByteArray]. This method is slightly slower than [method to_ascii_buffer], but supports all UTF-8 characters. For most cases, prefer using this method. + Converts the string to a [url=https://en.wikipedia.org/wiki/UTF-8]UTF-8[/url] encoded [PackedByteArray]. This method is slightly slower than [method to_ascii_buffer], but supports all UTF-8 characters. For most cases, prefer using this method. This is the inverse of [method PackedByteArray.get_string_from_utf8]. </description> </method> <method name="to_utf16_buffer" qualifiers="const"> <return type="PackedByteArray" /> <description> - Converts the string to a [url=https://en.wikipedia.org/wiki/UTF-16]UTF-16[/url] encoded [PackedByteArray]. + Converts the string to a [url=https://en.wikipedia.org/wiki/UTF-16]UTF-16[/url] encoded [PackedByteArray]. This is the inverse of [method PackedByteArray.get_string_from_utf16]. </description> </method> <method name="to_utf32_buffer" qualifiers="const"> <return type="PackedByteArray" /> <description> - Converts the string to a [url=https://en.wikipedia.org/wiki/UTF-32]UTF-32[/url] encoded [PackedByteArray]. + Converts the string to a [url=https://en.wikipedia.org/wiki/UTF-32]UTF-32[/url] encoded [PackedByteArray]. This is the inverse of [method PackedByteArray.get_string_from_utf32]. </description> </method> <method name="to_wchar_buffer" qualifiers="const"> <return type="PackedByteArray" /> <description> - Converts the string to a [url=https://en.wikipedia.org/wiki/Wide_character]wide character[/url] ([code]wchar_t[/code], UTF-16 on Windows, UTF-32 on other platforms) encoded [PackedByteArray]. + Converts the string to a [url=https://en.wikipedia.org/wiki/Wide_character]wide character[/url] ([code]wchar_t[/code], UTF-16 on Windows, UTF-32 on other platforms) encoded [PackedByteArray]. This is the inverse of [method PackedByteArray.get_string_from_wchar]. </description> </method> <method name="trim_prefix" qualifiers="const"> @@ -990,7 +997,7 @@ <method name="uri_decode" qualifiers="const"> <return type="String" /> <description> - Decodes the string from its URL-encoded format. This method is meant to properly decode the parameters in a URL when receiving an HTTP request. + Decodes the string from its URL-encoded format. This method is meant to properly decode the parameters in a URL when receiving an HTTP request. See also [method uri_encode]. [codeblocks] [gdscript] var url = "$DOCS_URL/?highlight=Godot%20Engine%3%docs" @@ -1006,7 +1013,7 @@ <method name="uri_encode" qualifiers="const"> <return type="String" /> <description> - Encodes the string to URL-friendly format. This method is meant to properly encode the parameters in a URL when sending an HTTP request. + Encodes the string to URL-friendly format. This method is meant to properly encode the parameters in a URL when sending an HTTP request. See also [method uri_decode]. [codeblocks] [gdscript] var prefix = "$DOCS_URL/?highlight=" diff --git a/doc/classes/StyleBoxTexture.xml b/doc/classes/StyleBoxTexture.xml index 14bceb4d4c..07d4b13f36 100644 --- a/doc/classes/StyleBoxTexture.xml +++ b/doc/classes/StyleBoxTexture.xml @@ -80,9 +80,9 @@ Modulates the color of the texture when this style box is drawn. </member> <member name="region_rect" type="Rect2" setter="set_region_rect" getter="get_region_rect" default="Rect2(0, 0, 0, 0)"> - Species a sub-region of the texture to use. - This is equivalent to first wrapping the texture in an [AtlasTexture] with the same region. - If empty ([code]Rect2(0, 0, 0, 0)[/code]), the whole texture will be used. + The region to use from the [member texture]. + This is equivalent to first wrapping the [member texture] in an [AtlasTexture] with the same region. + If empty ([code]Rect2(0, 0, 0, 0)[/code]), the whole [member texture] is used. </member> <member name="texture" type="Texture2D" setter="set_texture" getter="get_texture"> The texture to use when drawing this style box. diff --git a/doc/classes/SyntaxHighlighter.xml b/doc/classes/SyntaxHighlighter.xml index 27cee26c50..22d20d24e5 100644 --- a/doc/classes/SyntaxHighlighter.xml +++ b/doc/classes/SyntaxHighlighter.xml @@ -41,11 +41,11 @@ <return type="Dictionary" /> <param index="0" name="line" type="int" /> <description> - Returns syntax highlighting data for a single line. If the line is not cached, calls [method _get_line_syntax_highlighting] to calculate the data. - The return [Dictionary] is column number to [Dictionary]. The column number notes the start of a region, the region will end if another region is found, or at the end of the line. The nested [Dictionary] contains the data for that region, currently only the key "color" is supported. - [b]Example return:[/b] + Returns the syntax highlighting data for the line at index [param line]. If the line is not cached, calls [method _get_line_syntax_highlighting] first to calculate the data. + Each entry is a column number containing a nested [Dictionary]. The column number denotes the start of a region, the region will end if another region is found, or at the end of the line. The nested [Dictionary] contains the data for that region. Currently only the key [code]"color"[/code] is supported. + [b]Example:[/b] Possible return value. This means columns [code]0[/code] to [code]4[/code] should be red, and columns [code]5[/code] to the end of the line should be green: [codeblock] - var color_map = { + { 0: { "color": Color(1, 0, 0) }, @@ -54,7 +54,6 @@ } } [/codeblock] - This will color columns 0-4 red, and columns 5-eol in green. </description> </method> <method name="get_text_edit" qualifiers="const"> diff --git a/doc/classes/TextEdit.xml b/doc/classes/TextEdit.xml index 5bf8dc041d..13721d9d62 100644 --- a/doc/classes/TextEdit.xml +++ b/doc/classes/TextEdit.xml @@ -124,7 +124,6 @@ <return type="void" /> <description> Starts an edit for multiple carets. The edit must be ended with [method end_multicaret_edit]. Multicaret edits can be used to edit text at multiple carets and delay merging the carets until the end, so the caret indexes aren't affected immediately. [method begin_multicaret_edit] and [method end_multicaret_edit] can be nested, and the merge will happen at the last [method end_multicaret_edit]. - Example usage: [codeblock] begin_complex_operation() begin_multicaret_edit() @@ -1625,7 +1624,7 @@ The caret's width in pixels. Greater values can be used to improve accessibility by ensuring the caret is easily visible, or to ensure consistency with a large font size. If set to [code]0[/code] or lower, the caret width is automatically set to 1 pixel and multiplied by the display scaling factor. </theme_item> <theme_item name="line_spacing" data_type="constant" type="int" default="4"> - Sets the spacing between the lines. + Additional vertical spacing between lines (in pixels), spacing is added to line descent. This value can be negative. </theme_item> <theme_item name="outline_size" data_type="constant" type="int" default="0"> The size of the text outline. diff --git a/doc/classes/TextMesh.xml b/doc/classes/TextMesh.xml index 898d19aed3..b6b1052af5 100644 --- a/doc/classes/TextMesh.xml +++ b/doc/classes/TextMesh.xml @@ -37,7 +37,7 @@ Language code used for text shaping algorithms, if left empty current locale is used instead. </member> <member name="line_spacing" type="float" setter="set_line_spacing" getter="get_line_spacing" default="0.0"> - Vertical space between lines in multiline [TextMesh]. + Additional vertical spacing between lines (in pixels), spacing is added to line descent. This value can be negative. </member> <member name="offset" type="Vector2" setter="set_offset" getter="get_offset" default="Vector2(0, 0)"> The text drawing offset (in pixels). diff --git a/doc/classes/TextParagraph.xml b/doc/classes/TextParagraph.xml index 46197f19b8..c9ac660b8c 100644 --- a/doc/classes/TextParagraph.xml +++ b/doc/classes/TextParagraph.xml @@ -280,6 +280,9 @@ <member name="justification_flags" type="int" setter="set_justification_flags" getter="get_justification_flags" enum="TextServer.JustificationFlag" is_bitfield="true" default="163"> Line fill alignment rules. See [enum TextServer.JustificationFlag] for more information. </member> + <member name="line_spacing" type="float" setter="set_line_spacing" getter="get_line_spacing" default="0.0"> + Additional vertical spacing between lines (in pixels), spacing is added to line descent. This value can be negative. + </member> <member name="max_lines_visible" type="int" setter="set_max_lines_visible" getter="get_max_lines_visible" default="-1"> Limits the lines of text shown. </member> diff --git a/doc/classes/TileMap.xml b/doc/classes/TileMap.xml index 0995a5a672..4683f063f1 100644 --- a/doc/classes/TileMap.xml +++ b/doc/classes/TileMap.xml @@ -380,7 +380,7 @@ <param index="4" name="ignore_empty_terrains" type="bool" default="true" /> <description> Update all the cells in the [param cells] coordinates array so that they use the given [param terrain] for the given [param terrain_set]. If an updated cell has the same terrain as one of its neighboring cells, this function tries to join the two. This function might update neighboring tiles if needed to create correct terrain transitions. - If [param ignore_empty_terrains] is true, empty terrains will be ignored when trying to find the best fitting tile for the given terrain constraints. + If [param ignore_empty_terrains] is [code]true[/code], empty terrains will be ignored when trying to find the best fitting tile for the given terrain constraints. If [param layer] is negative, the layers are accessed from the last one. [b]Note:[/b] To work correctly, this method requires the TileMap's TileSet to have terrains set up with all required terrain combinations. Otherwise, it may produce unexpected results. </description> @@ -394,7 +394,7 @@ <param index="4" name="ignore_empty_terrains" type="bool" default="true" /> <description> Update all the cells in the [param path] coordinates array so that they use the given [param terrain] for the given [param terrain_set]. The function will also connect two successive cell in the path with the same terrain. This function might update neighboring tiles if needed to create correct terrain transitions. - If [param ignore_empty_terrains] is true, empty terrains will be ignored when trying to find the best fitting tile for the given terrain constraints. + If [param ignore_empty_terrains] is [code]true[/code], empty terrains will be ignored when trying to find the best fitting tile for the given terrain constraints. If [param layer] is negative, the layers are accessed from the last one. [b]Note:[/b] To work correctly, this method requires the TileMap's TileSet to have terrains set up with all required terrain combinations. Otherwise, it may produce unexpected results. </description> diff --git a/doc/classes/TileMapLayer.xml b/doc/classes/TileMapLayer.xml index 135f85de69..43708ca142 100644 --- a/doc/classes/TileMapLayer.xml +++ b/doc/classes/TileMapLayer.xml @@ -22,6 +22,21 @@ [b]Note:[/b] If the properties of [param tile_data] object should change over time, use [method notify_runtime_tile_data_update] to notify the [TileMapLayer] it needs an update. </description> </method> + <method name="_update_cells" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="coords" type="Vector2i[]" /> + <param index="1" name="forced_cleanup" type="bool" /> + <description> + Called when this [TileMapLayer]'s cells need an internal update. This update may be caused from individual cells being modified or by a change in the [member tile_set] (causing all cells to be queued for an update). The first call to this function is always for initializing all the [TileMapLayer]'s cells. [param coords] contains the coordinates of all modified cells, roughly in the order they were modified. [param forced_cleanup] is [code]true[/code] when the [TileMapLayer]'s internals should be fully cleaned up. This is the case when: + - The layer is disabled; + - The layer is not visible; + - [member tile_set] is set to [code]null[/code]; + - The node is removed from the tree; + - The node is freed. + Note that any internal update happening while one of these conditions is verified is considered to be a "cleanup". See also [method update_internals]. + [b]Warning:[/b] Implementing this method may degrade the [TileMapLayer]'s performance. + </description> + </method> <method name="_use_tile_data_runtime_update" qualifiers="virtual"> <return type="bool" /> <param index="0" name="coords" type="Vector2i" /> @@ -120,7 +135,7 @@ <return type="Vector2i[]" /> <param index="0" name="coords" type="Vector2i" /> <description> - Returns the list of all neighboring cells to the one at [param coords]. + Returns the list of all neighboring cells to the one at [param coords]. Any neighboring cell is one that is touching edges, so for a square cell 4 cells would be returned, for a hexagon 6 cells are returned. </description> </method> <method name="get_used_cells" qualifiers="const"> @@ -228,7 +243,7 @@ <param index="3" name="ignore_empty_terrains" type="bool" default="true" /> <description> Update all the cells in the [param cells] coordinates array so that they use the given [param terrain] for the given [param terrain_set]. If an updated cell has the same terrain as one of its neighboring cells, this function tries to join the two. This function might update neighboring tiles if needed to create correct terrain transitions. - If [param ignore_empty_terrains] is true, empty terrains will be ignored when trying to find the best fitting tile for the given terrain constraints. + If [param ignore_empty_terrains] is [code]true[/code], empty terrains will be ignored when trying to find the best fitting tile for the given terrain constraints. [b]Note:[/b] To work correctly, this method requires the [TileMapLayer]'s TileSet to have terrains set up with all required terrain combinations. Otherwise, it may produce unexpected results. </description> </method> @@ -240,7 +255,7 @@ <param index="3" name="ignore_empty_terrains" type="bool" default="true" /> <description> Update all the cells in the [param path] coordinates array so that they use the given [param terrain] for the given [param terrain_set]. The function will also connect two successive cell in the path with the same terrain. This function might update neighboring tiles if needed to create correct terrain transitions. - If [param ignore_empty_terrains] is true, empty terrains will be ignored when trying to find the best fitting tile for the given terrain constraints. + If [param ignore_empty_terrains] is [code]true[/code], empty terrains will be ignored when trying to find the best fitting tile for the given terrain constraints. [b]Note:[/b] To work correctly, this method requires the [TileMapLayer]'s TileSet to have terrains set up with all required terrain combinations. Otherwise, it may produce unexpected results. </description> </method> diff --git a/doc/classes/TileSet.xml b/doc/classes/TileSet.xml index 64cd4fb7b2..19b6e8d92c 100644 --- a/doc/classes/TileSet.xml +++ b/doc/classes/TileSet.xml @@ -4,7 +4,7 @@ Tile library for tilemaps. </brief_description> <description> - A TileSet is a library of tiles for a [TileMap]. A TileSet handles a list of [TileSetSource], each of them storing a set of tiles. + A TileSet is a library of tiles for a [TileMapLayer]. A TileSet handles a list of [TileSetSource], each of them storing a set of tiles. Tiles can either be from a [TileSetAtlasSource], which renders tiles out of a texture with support for physics, navigation, etc., or from a [TileSetScenesCollectionSource], which exposes scene-based tiles. Tiles are referenced by using three IDs: their source ID, their atlas coordinates ID, and their alternative tile ID. A TileSet can be configured so that its tiles expose more or fewer properties. To do so, the TileSet resources use property layers, which you can add or remove depending on your needs. @@ -218,6 +218,13 @@ Returns the collision mask of bodies on the given TileSet's physics layer. </description> </method> + <method name="get_physics_layer_collision_priority" qualifiers="const"> + <return type="float" /> + <param index="0" name="layer_index" type="int" /> + <description> + Returns the collision priority of bodies on the given TileSet's physics layer. + </description> + </method> <method name="get_physics_layer_physics_material" qualifiers="const"> <return type="PhysicsMaterial" /> <param index="0" name="layer_index" type="int" /> @@ -547,7 +554,7 @@ <param index="0" name="layer_index" type="int" /> <param index="1" name="layer" type="int" /> <description> - Sets the physics layer (as in the physics server) for bodies in the given TileSet physics layer. + Sets the collision layer (as in the physics server) for bodies in the given TileSet physics layer. </description> </method> <method name="set_physics_layer_collision_mask"> @@ -555,7 +562,15 @@ <param index="0" name="layer_index" type="int" /> <param index="1" name="mask" type="int" /> <description> - Sets the physics layer (as in the physics server) for bodies in the given TileSet physics layer. + Sets the collision mask for bodies in the given TileSet physics layer. + </description> + </method> + <method name="set_physics_layer_collision_priority"> + <return type="void" /> + <param index="0" name="layer_index" type="int" /> + <param index="1" name="priority" type="float" /> + <description> + Sets the collision priority for bodies in the given TileSet physics layer. </description> </method> <method name="set_physics_layer_physics_material"> diff --git a/doc/classes/Timer.xml b/doc/classes/Timer.xml index f8f9393847..09f3dba8cf 100644 --- a/doc/classes/Timer.xml +++ b/doc/classes/Timer.xml @@ -43,6 +43,7 @@ <member name="autostart" type="bool" setter="set_autostart" getter="has_autostart" default="false"> If [code]true[/code], the timer will start immediately when it enters the scene tree. [b]Note:[/b] After the timer enters the tree, this property is automatically set to [code]false[/code]. + [b]Note:[/b] This property does nothing when the timer is running in the editor. </member> <member name="one_shot" type="bool" setter="set_one_shot" getter="is_one_shot" default="false"> If [code]true[/code], the timer will stop after reaching the end. Otherwise, as by default, the timer will automatically restart. diff --git a/doc/classes/TouchScreenButton.xml b/doc/classes/TouchScreenButton.xml index 5052518583..faeaaba5b6 100644 --- a/doc/classes/TouchScreenButton.xml +++ b/doc/classes/TouchScreenButton.xml @@ -5,7 +5,7 @@ </brief_description> <description> TouchScreenButton allows you to create on-screen buttons for touch devices. It's intended for gameplay use, such as a unit you have to touch to move. Unlike [Button], TouchScreenButton supports multitouch out of the box. Several TouchScreenButtons can be pressed at the same time with touch input. - This node inherits from [Node2D]. Unlike with [Control] nodes, you cannot set anchors on it. If you want to create menus or user interfaces, you may want to use [Button] nodes instead. To make button nodes react to touch events, you can enable the Emulate Mouse option in the Project Settings. + This node inherits from [Node2D]. Unlike with [Control] nodes, you cannot set anchors on it. If you want to create menus or user interfaces, you may want to use [Button] nodes instead. To make button nodes react to touch events, you can enable [member ProjectSettings.input_devices/pointing/emulate_mouse_from_touch] in the Project Settings. You can configure TouchScreenButton to be visible only on touch devices, helping you develop your game both for desktop and mobile devices. </description> <tutorials> diff --git a/doc/classes/Transform2D.xml b/doc/classes/Transform2D.xml index 4158fbe710..665e5e9d67 100644 --- a/doc/classes/Transform2D.xml +++ b/doc/classes/Transform2D.xml @@ -20,6 +20,7 @@ <return type="Transform2D" /> <description> Constructs a [Transform2D] identical to [constant IDENTITY]. + [b]Note:[/b] In C#, this constructs a [Transform2D] with all of its components set to [constant Vector2.ZERO]. </description> </constructor> <constructor name="Transform2D"> @@ -251,14 +252,14 @@ </member> <member name="y" type="Vector2" setter="" getter="" default="Vector2(0, 1)"> The transform basis's Y axis, and the column [code]1[/code] of the matrix. Combined with [member x], this represents the transform's rotation, scale, and skew. - On the identity transform, this vector points up ([constant Vector2.UP]). + On the identity transform, this vector points down ([constant Vector2.DOWN]). </member> </members> <constants> <constant name="IDENTITY" value="Transform2D(1, 0, 0, 1, 0, 0)"> The identity [Transform2D]. A transform with no translation, no rotation, and its scale being [code]1[/code]. When multiplied by another [Variant] such as [Rect2] or another [Transform2D], no transformation occurs. This means that: - The [member x] points right ([constant Vector2.RIGHT]); - - The [member y] points up ([constant Vector2.UP]). + - The [member y] points down ([constant Vector2.DOWN]). [codeblock] var transform = Transform2D.IDENTITY print("| X | Y | Origin") diff --git a/doc/classes/Transform3D.xml b/doc/classes/Transform3D.xml index 30c141659a..98e9d56adb 100644 --- a/doc/classes/Transform3D.xml +++ b/doc/classes/Transform3D.xml @@ -21,6 +21,7 @@ <return type="Transform3D" /> <description> Constructs a [Transform3D] identical to the [constant IDENTITY]. + [b]Note:[/b] In C#, this constructs a [Transform3D] with its [member origin] and the components of its [member basis] set to [constant Vector3.ZERO]. </description> </constructor> <constructor name="Transform3D"> @@ -128,7 +129,7 @@ <param index="1" name="angle" type="float" /> <description> Returns a copy of this transform rotated around the given [param axis] by the given [param angle] (in radians). - The [param axis] must be a normalized vector. + The [param axis] must be a normalized vector in the transform's local coordinate system. For example, to rotate around the local X-axis, use [constant Vector3.RIGHT]. This method is an optimized version of multiplying the given transform [code]X[/code] with a corresponding rotation transform [code]R[/code] from the right, i.e., [code]X * R[/code]. This can be seen as transforming with respect to the local frame. </description> diff --git a/doc/classes/TreeItem.xml b/doc/classes/TreeItem.xml index 132ecc3f92..d04a6f7316 100644 --- a/doc/classes/TreeItem.xml +++ b/doc/classes/TreeItem.xml @@ -267,7 +267,7 @@ <method name="get_next" qualifiers="const"> <return type="TreeItem" /> <description> - Returns the next sibling TreeItem in the tree or a null object if there is none. + Returns the next sibling TreeItem in the tree or a [code]null[/code] object if there is none. </description> </method> <method name="get_next_in_tree"> @@ -289,13 +289,13 @@ <method name="get_parent" qualifiers="const"> <return type="TreeItem" /> <description> - Returns the parent TreeItem or a null object if there is none. + Returns the parent TreeItem or a [code]null[/code] object if there is none. </description> </method> <method name="get_prev"> <return type="TreeItem" /> <description> - Returns the previous sibling TreeItem in the tree or a null object if there is none. + Returns the previous sibling TreeItem in the tree or a [code]null[/code] object if there is none. </description> </method> <method name="get_prev_in_tree"> diff --git a/doc/classes/Tween.xml b/doc/classes/Tween.xml index 86a8130acc..3ad0a73b41 100644 --- a/doc/classes/Tween.xml +++ b/doc/classes/Tween.xml @@ -279,6 +279,22 @@ <return type="void" /> <description> Stops the tweening and resets the [Tween] to its initial state. This will not remove any appended [Tweener]s. + [b]Note:[/b] This does [i]not[/i] reset targets of [PropertyTweener]s to their values when the [Tween] first started. + [codeblock] + var tween = create_tween() + + # Will move from 0 to 500 over 1 second. + position.x = 0.0 + tween.tween_property(self, "position:x", 500, 1.0) + + # Will be at (about) 250 when the timer finishes. + await get_tree().create_timer(0.5).timeout + + # Will now move from (about) 250 to 500 over 1 second, + # thus at half the speed as before. + tween.stop() + tween.play() + [/codeblock] [b]Note:[/b] If a Tween is stopped and not bound to any node, it will exist indefinitely until manually started or invalidated. If you lose a reference to such Tween, you can retrieve it using [method SceneTree.get_processed_tweens]. </description> </method> diff --git a/doc/classes/VideoStreamPlayback.xml b/doc/classes/VideoStreamPlayback.xml index 8b4a7f8d29..17e29ae337 100644 --- a/doc/classes/VideoStreamPlayback.xml +++ b/doc/classes/VideoStreamPlayback.xml @@ -54,7 +54,7 @@ <method name="_play" qualifiers="virtual"> <return type="void" /> <description> - Called in response to [member VideoStreamPlayer.autoplay] or [method VideoStreamPlayer.play]. Note that manual playback may also invoke [method _stop] multiple times before this method is called. [method _is_playing] should return true once playing. + Called in response to [member VideoStreamPlayer.autoplay] or [method VideoStreamPlayer.play]. Note that manual playback may also invoke [method _stop] multiple times before this method is called. [method _is_playing] should return [code]true[/code] once playing. </description> </method> <method name="_seek" qualifiers="virtual"> @@ -81,14 +81,14 @@ <method name="_stop" qualifiers="virtual"> <return type="void" /> <description> - Stops playback. May be called multiple times before [method _play], or in response to [method VideoStreamPlayer.stop]. [method _is_playing] should return false once stopped. + Stops playback. May be called multiple times before [method _play], or in response to [method VideoStreamPlayer.stop]. [method _is_playing] should return [code]false[/code] once stopped. </description> </method> <method name="_update" qualifiers="virtual"> <return type="void" /> <param index="0" name="delta" type="float" /> <description> - Ticks video playback for [param delta] seconds. Called every frame as long as [method _is_paused] and [method _is_playing] return true. + Ticks video playback for [param delta] seconds. Called every frame as long as both [method _is_paused] and [method _is_playing] return [code]true[/code]. </description> </method> <method name="mix_audio"> diff --git a/doc/classes/Viewport.xml b/doc/classes/Viewport.xml index 333e61d03f..c4319fd360 100644 --- a/doc/classes/Viewport.xml +++ b/doc/classes/Viewport.xml @@ -48,7 +48,7 @@ <method name="get_camera_2d" qualifiers="const"> <return type="Camera2D" /> <description> - Returns the currently active 2D camera. Returns null if there are no active cameras. + Returns the currently active 2D camera. Returns [code]null[/code] if there are no active cameras. </description> </method> <method name="get_camera_3d" qualifiers="const"> @@ -144,13 +144,13 @@ <method name="gui_get_focus_owner" qualifiers="const"> <return type="Control" /> <description> - Returns the [Control] having the focus within this viewport. If no [Control] has the focus, returns null. + Returns the currently focused [Control] within this viewport. If no [Control] is focused, returns [code]null[/code]. </description> </method> <method name="gui_get_hovered_control" qualifiers="const"> <return type="Control" /> <description> - Returns the [Control] that the mouse is currently hovering over in this viewport. If no [Control] has the cursor, returns null. + Returns the [Control] that the mouse is currently hovering over in this viewport. If no [Control] has the cursor, returns [code]null[/code]. Typically the leaf [Control] node or deepest level of the subtree which claims hover. This is very useful when used together with [method Node.is_ancestor_of] to find if the mouse is within a control tree. </description> </method> diff --git a/doc/classes/VisualShaderNodeCompare.xml b/doc/classes/VisualShaderNodeCompare.xml index b566ca62f3..9f554dacb4 100644 --- a/doc/classes/VisualShaderNodeCompare.xml +++ b/doc/classes/VisualShaderNodeCompare.xml @@ -69,10 +69,10 @@ Represents the size of the [enum Function] enum. </constant> <constant name="COND_ALL" value="0" enum="Condition"> - The result will be true if all of component in vector satisfy the comparison condition. + The result will be [code]true[/code] if all components in the vector satisfy the comparison condition. </constant> <constant name="COND_ANY" value="1" enum="Condition"> - The result will be true if any of component in vector satisfy the comparison condition. + The result will be [code]true[/code] if any component in the vector satisfies the comparison condition. </constant> <constant name="COND_MAX" value="2" enum="Condition"> Represents the size of the [enum Condition] enum. diff --git a/doc/classes/Window.xml b/doc/classes/Window.xml index 02110f0162..424941b842 100644 --- a/doc/classes/Window.xml +++ b/doc/classes/Window.xml @@ -725,8 +725,6 @@ <param index="0" name="files" type="PackedStringArray" /> <description> Emitted when files are dragged from the OS file manager and dropped in the game window. The argument is a list of file paths. - Note that this method only works with native windows, i.e. the main window and [Window]-derived nodes when [member Viewport.gui_embed_subwindows] is disabled in the main viewport. - Example usage: [codeblock] func _ready(): get_viewport().files_dropped.connect(on_files_dropped) @@ -734,6 +732,7 @@ func on_files_dropped(files): print(files) [/codeblock] + [b]Note:[/b] This signal only works with native windows, i.e. the main window and [Window]-derived nodes when [member Viewport.gui_embed_subwindows] is disabled in the main viewport. </description> </signal> <signal name="focus_entered"> |