diff options
Diffstat (limited to 'doc/classes')
86 files changed, 679 insertions, 196 deletions
diff --git a/doc/classes/@GlobalScope.xml b/doc/classes/@GlobalScope.xml index b06c28311a..77c5a168f3 100644 --- a/doc/classes/@GlobalScope.xml +++ b/doc/classes/@GlobalScope.xml @@ -1393,7 +1393,7 @@ <description> Converts the given [param variant] to the given [param type], using the [enum Variant.Type] values. This method is generous with how it handles types, it can automatically convert between array types, convert numeric [String]s to [int], and converting most things to [String]. If the type conversion cannot be done, this method will return the default value for that type, for example converting [Rect2] to [Vector2] will always return [constant Vector2.ZERO]. This method will never show error messages as long as [param type] is a valid Variant type. - The returned value is a [Variant], but the data inside and the [enum Variant.Type] will be the same as the requested type. + The returned value is a [Variant], but the data inside and its type will be the same as the requested type. [codeblock] type_convert("Hi!", TYPE_INT) # Returns 0 type_convert("123", TYPE_INT) # Returns 123 @@ -1477,7 +1477,7 @@ <return type="Variant" /> <param index="0" name="obj" type="Variant" /> <description> - Returns a weak reference to an object, or [code]null[/code] if [param obj] is invalid. + Returns a [WeakRef] instance holding a weak reference to [param obj]. Returns an empty [WeakRef] instance if [param obj] is [code]null[/code]. Prints an error and returns [code]null[/code] if [param obj] is neither [Object]-derived nor [code]null[/code]. A weak reference to an object is not enough to keep the object alive: when the only remaining references to a referent are weak references, garbage collection is free to destroy the referent and reuse its memory for something else. However, until the object is actually destroyed the weak reference may return the object even if there are no strong references to it. </description> </method> @@ -2823,6 +2823,7 @@ Hints that a [Color] property should be edited without affecting its transparency ([member Color.a] is not editable). </constant> <constant name="PROPERTY_HINT_OBJECT_ID" value="22" enum="PropertyHint"> + Hints that the property's value is an object encoded as object ID, with its type specified in the hint string. Used by the debugger. </constant> <constant name="PROPERTY_HINT_TYPE_STRING" value="23" enum="PropertyHint"> If a property is [String], hints that the property represents a particular type (class). This allows to select a type from the create dialog. The property will store the selected type as a string. @@ -2881,21 +2882,30 @@ [/codeblocks] [b]Note:[/b] The trailing colon is required for properly detecting built-in types. </constant> - <constant name="PROPERTY_HINT_NODE_PATH_TO_EDITED_NODE" value="24" enum="PropertyHint"> + <constant name="PROPERTY_HINT_NODE_PATH_TO_EDITED_NODE" value="24" enum="PropertyHint" is_deprecated="true"> + [i]Deprecated.[/i] This hint is not used anywhere and will be removed in the future. </constant> <constant name="PROPERTY_HINT_OBJECT_TOO_BIG" value="25" enum="PropertyHint"> + Hints that an object is too big to be sent via the debugger. </constant> <constant name="PROPERTY_HINT_NODE_PATH_VALID_TYPES" value="26" enum="PropertyHint"> + Hints that the hint string specifies valid node types for property of type [NodePath]. </constant> <constant name="PROPERTY_HINT_SAVE_FILE" value="27" enum="PropertyHint"> + Hints that a [String] property is a path to a file. Editing it will show a file dialog for picking the path for the file to be saved at. The dialog has access to the project's directory. The hint string can be a set of filters with wildcards like [code]"*.png,*.jpg"[/code]. See also [member FileDialog.filters]. </constant> <constant name="PROPERTY_HINT_GLOBAL_SAVE_FILE" value="28" enum="PropertyHint"> + Hints that a [String] property is a path to a file. Editing it will show a file dialog for picking the path for the file to be saved at. The dialog has access to the entire filesystem. The hint string can be a set of filters with wildcards like [code]"*.png,*.jpg"[/code]. See also [member FileDialog.filters]. </constant> - <constant name="PROPERTY_HINT_INT_IS_OBJECTID" value="29" enum="PropertyHint"> + <constant name="PROPERTY_HINT_INT_IS_OBJECTID" value="29" enum="PropertyHint" is_deprecated="true"> + Hints that an [int] property is an object ID. + [i]Deprecated.[/i] This hint is not used anywhere and will be removed in the future. </constant> <constant name="PROPERTY_HINT_INT_IS_POINTER" value="30" enum="PropertyHint"> + Hints that an [int] property is a pointer. Used by GDExtension. </constant> <constant name="PROPERTY_HINT_ARRAY_TYPE" value="31" enum="PropertyHint"> + Hints that a property is an [Array] with the stored type specified in the hint string. </constant> <constant name="PROPERTY_HINT_LOCALE_ID" value="32" enum="PropertyHint"> Hints that a string property is a locale code. Editing it will show a locale dialog for picking language and country. @@ -2904,6 +2914,7 @@ Hints that a dictionary property is string translation map. Dictionary keys are locale codes and, values are translated strings. </constant> <constant name="PROPERTY_HINT_NODE_TYPE" value="34" enum="PropertyHint"> + Hints that a property is an instance of a [Node]-derived type, optionally specified via the hint string (e.g. [code]"Node2D"[/code]). Editing it will show a dialog for picking a node from the scene. </constant> <constant name="PROPERTY_HINT_HIDE_QUATERNION_EDIT" value="35" enum="PropertyHint"> Hints that a quaternion property should disable the temporary euler editor. @@ -2942,6 +2953,7 @@ Used to group properties together in the editor in a subgroup (under a group). See [EditorInspector]. </constant> <constant name="PROPERTY_USAGE_CLASS_IS_BITFIELD" value="512" enum="PropertyUsageFlags" is_bitfield="true"> + The property is a bitfield, i.e. it contains multiple flags represented as bits. </constant> <constant name="PROPERTY_USAGE_NO_INSTANCE_STATE" value="1024" enum="PropertyUsageFlags" is_bitfield="true"> The property does not save its state in [PackedScene]. @@ -2953,14 +2965,20 @@ The property is a script variable which should be serialized and saved in the scene file. </constant> <constant name="PROPERTY_USAGE_STORE_IF_NULL" value="8192" enum="PropertyUsageFlags" is_bitfield="true"> + The property value of type [Object] will be stored even if its value is [code]null[/code]. </constant> <constant name="PROPERTY_USAGE_UPDATE_ALL_IF_MODIFIED" value="16384" enum="PropertyUsageFlags" is_bitfield="true"> + If this property is modified, all inspector fields will be refreshed. </constant> - <constant name="PROPERTY_USAGE_SCRIPT_DEFAULT_VALUE" value="32768" enum="PropertyUsageFlags" is_bitfield="true"> + <constant name="PROPERTY_USAGE_SCRIPT_DEFAULT_VALUE" value="32768" enum="PropertyUsageFlags" is_bitfield="true" is_deprecated="true"> + Signifies a default value from a placeholder script instance. + [i]Deprecated.[/i] This hint is not used anywhere and will be removed in the future. </constant> <constant name="PROPERTY_USAGE_CLASS_IS_ENUM" value="65536" enum="PropertyUsageFlags" is_bitfield="true"> + The property is an enum, i.e. it only takes named integer constants from its associated enumeration. </constant> <constant name="PROPERTY_USAGE_NIL_IS_VARIANT" value="131072" enum="PropertyUsageFlags" is_bitfield="true"> + If property has [code]nil[/code] as default value, its type will be [Variant]. </constant> <constant name="PROPERTY_USAGE_ARRAY" value="262144" enum="PropertyUsageFlags" is_bitfield="true"> The property is an array. @@ -2975,16 +2993,23 @@ The property is only shown in the editor if modern renderers are supported (the Compatibility rendering method is excluded). </constant> <constant name="PROPERTY_USAGE_NODE_PATH_FROM_SCENE_ROOT" value="4194304" enum="PropertyUsageFlags" is_bitfield="true"> + The [NodePath] property will always be relative to the scene's root. Mostly useful for local resources. </constant> <constant name="PROPERTY_USAGE_RESOURCE_NOT_PERSISTENT" value="8388608" enum="PropertyUsageFlags" is_bitfield="true"> + Use when a resource is created on the fly, i.e. the getter will always return a different instance. [ResourceSaver] needs this information to properly save such resources. </constant> <constant name="PROPERTY_USAGE_KEYING_INCREMENTS" value="16777216" enum="PropertyUsageFlags" is_bitfield="true"> + Inserting an animation key frame of this property will automatically increment the value, allowing to easily keyframe multiple values in a row. </constant> - <constant name="PROPERTY_USAGE_DEFERRED_SET_RESOURCE" value="33554432" enum="PropertyUsageFlags" is_bitfield="true"> + <constant name="PROPERTY_USAGE_DEFERRED_SET_RESOURCE" value="33554432" enum="PropertyUsageFlags" is_bitfield="true" is_deprecated="true"> + When loading, the resource for this property can be set at the end of loading. + [i]Deprecated.[/i] This hint is not used anywhere and will be removed in the future. </constant> <constant name="PROPERTY_USAGE_EDITOR_INSTANTIATE_OBJECT" value="67108864" enum="PropertyUsageFlags" is_bitfield="true"> + When this property is a [Resource] and base object is a [Node], a resource instance will be automatically created whenever the node is created in the editor. </constant> <constant name="PROPERTY_USAGE_EDITOR_BASIC_SETTING" value="134217728" enum="PropertyUsageFlags" is_bitfield="true"> + The property is considered a basic setting and will appear even when advanced mode is disabled. Used for project settings. </constant> <constant name="PROPERTY_USAGE_READ_ONLY" value="268435456" enum="PropertyUsageFlags" is_bitfield="true"> The property is read-only in the [EditorInspector]. diff --git a/doc/classes/AnimationLibrary.xml b/doc/classes/AnimationLibrary.xml index d457a858ab..7f87ea4616 100644 --- a/doc/classes/AnimationLibrary.xml +++ b/doc/classes/AnimationLibrary.xml @@ -54,10 +54,6 @@ </description> </method> </methods> - <members> - <member name="_data" type="Dictionary" setter="_set_data" getter="_get_data" default="{}"> - </member> - </members> <signals> <signal name="animation_added"> <param index="0" name="name" type="StringName" /> diff --git a/doc/classes/Area2D.xml b/doc/classes/Area2D.xml index 6fa8e4ae9f..98110748ef 100644 --- a/doc/classes/Area2D.xml +++ b/doc/classes/Area2D.xml @@ -6,6 +6,7 @@ <description> [Area2D] is a region of 2D space defined by one or multiple [CollisionShape2D] or [CollisionPolygon2D] child nodes. It detects when other [CollisionObject2D]s enter or exit it, and it also keeps track of which collision objects haven't exited it yet (i.e. which one are overlapping it). This node can also locally alter or override physics parameters (gravity, damping) and route audio to custom audio buses. + [b]Note:[/b] Areas and bodies created with [PhysicsServer2D] might not interact as expected with [Area2D]s, and might not emit signals or track objects correctly. </description> <tutorials> <link title="Using Area2D">$DOCS_URL/tutorials/physics/using_area_2d.html</link> diff --git a/doc/classes/Area3D.xml b/doc/classes/Area3D.xml index 4f89e9b015..918869b83d 100644 --- a/doc/classes/Area3D.xml +++ b/doc/classes/Area3D.xml @@ -6,6 +6,7 @@ <description> [Area3D] is a region of 3D space defined by one or multiple [CollisionShape3D] or [CollisionPolygon3D] child nodes. It detects when other [CollisionObject3D]s enter or exit it, and it also keeps track of which collision objects haven't exited it yet (i.e. which one are overlapping it). This node can also locally alter or override physics parameters (gravity, damping) and route audio to custom audio buses. + [b]Note:[/b] Areas and bodies created with [PhysicsServer3D] might not interact as expected with [Area3D]s, and might not emit signals or track objects correctly. [b]Warning:[/b] Using a [ConcavePolygonShape3D] inside a [CollisionShape3D] child of this node (created e.g. by using the [b]Create Trimesh Collision Sibling[/b] option in the [b]Mesh[/b] menu that appears when selecting a [MeshInstance3D] node) may give unexpected results, since this collision shape is hollow. If this is not desired, it has to be split into multiple [ConvexPolygonShape3D]s or primitive shapes like [BoxShape3D], or in some cases it may be replaceable by a [CollisionPolygon3D]. </description> <tutorials> diff --git a/doc/classes/AudioServer.xml b/doc/classes/AudioServer.xml index 21ad817c6c..5b3fcd67d4 100644 --- a/doc/classes/AudioServer.xml +++ b/doc/classes/AudioServer.xml @@ -311,7 +311,7 @@ Name of the current device for audio output (see [method get_output_device_list]). On systems with multiple audio outputs (such as analog, USB and HDMI audio), this can be used to select the audio output device. The value [code]"Default"[/code] will play audio on the system-wide default audio output. If an invalid device name is set, the value will be reverted back to [code]"Default"[/code]. </member> <member name="playback_speed_scale" type="float" setter="set_playback_speed_scale" getter="get_playback_speed_scale" default="1.0"> - Scales the rate at which audio is played (i.e. setting it to [code]0.5[/code] will make the audio be played at half its speed). + Scales the rate at which audio is played (i.e. setting it to [code]0.5[/code] will make the audio be played at half its speed). See also [member Engine.time_scale] to affect the general simulation speed, which is independent from [member AudioServer.playback_speed_scale]. </member> </members> <signals> diff --git a/doc/classes/AudioStreamGenerator.xml b/doc/classes/AudioStreamGenerator.xml index 6949a5d82b..9e91d5c450 100644 --- a/doc/classes/AudioStreamGenerator.xml +++ b/doc/classes/AudioStreamGenerator.xml @@ -6,7 +6,8 @@ <description> [AudioStreamGenerator] is a type of audio stream that does not play back sounds on its own; instead, it expects a script to generate audio data for it. See also [AudioStreamGeneratorPlayback]. Here's a sample on how to use it to generate a sine wave: - [codeblock] + [codeblocks] + [gdscript] var playback # Will hold the AudioStreamGeneratorPlayback. @onready var sample_hz = $AudioStreamPlayer.stream.mix_rate var pulse_hz = 440.0 # The frequency of the sound wave. @@ -24,7 +25,39 @@ for i in range(frames_available): playback.push_frame(Vector2.ONE * sin(phase * TAU)) phase = fmod(phase + increment, 1.0) - [/codeblock] + [/gdscript] + [csharp] + [Export] public AudioStreamPlayer Player { get; set; } + + private AudioStreamGeneratorPlayback _playback; // Will hold the AudioStreamGeneratorPlayback. + private float _sampleHz; + private float _pulseHz = 440.0f; // The frequency of the sound wave. + + public override void _Ready() + { + if (Player.Stream is AudioStreamGenerator generator) // Type as a generator to access MixRate. + { + _sampleHz = generator.MixRate; + Player.Play(); + _playback = (AudioStreamGeneratorPlayback)Player.GetStreamPlayback(); + FillBuffer(); + } + } + + public void FillBuffer() + { + double phase = 0.0; + float increment = _pulseHz / _sampleHz; + int framesAvailable = _playback.GetFramesAvailable(); + + for (int i = 0; i < framesAvailable; i++) + { + _playback.PushFrame(Vector2.One * (float)Mathf.Sin(phase * Mathf.Tau)); + phase = Mathf.PosMod(phase + increment, 1.0); + } + } + [/csharp] + [/codeblocks] In the example above, the "AudioStreamPlayer" node must use an [AudioStreamGenerator] as its stream. The [code]fill_buffer[/code] function provides audio data for approximating a sine wave. See also [AudioEffectSpectrumAnalyzer] for performing real-time audio spectrum analysis. [b]Note:[/b] Due to performance constraints, this class is best used from C# or from a compiled language via GDExtension. If you still want to use this class from GDScript, consider using a lower [member mix_rate] such as 11,025 Hz or 22,050 Hz. diff --git a/doc/classes/AudioStreamGeneratorPlayback.xml b/doc/classes/AudioStreamGeneratorPlayback.xml index 185b89d760..88c5cf6dbe 100644 --- a/doc/classes/AudioStreamGeneratorPlayback.xml +++ b/doc/classes/AudioStreamGeneratorPlayback.xml @@ -33,6 +33,7 @@ <method name="get_skips" qualifiers="const"> <return type="int" /> <description> + Returns the number of times the playback skipped due to a buffer underrun in the audio sample data. This value is reset at the start of the playback. </description> </method> <method name="push_buffer"> diff --git a/doc/classes/AudioStreamWAV.xml b/doc/classes/AudioStreamWAV.xml index c3df946b4b..206b6361cc 100644 --- a/doc/classes/AudioStreamWAV.xml +++ b/doc/classes/AudioStreamWAV.xml @@ -8,6 +8,7 @@ This class can also be used to store dynamically-generated PCM audio data. See also [AudioStreamGenerator] for procedural audio generation. </description> <tutorials> + <link title="Runtime file loading and saving">$DOCS_URL/tutorials/io/runtime_file_loading_and_saving.html</link> </tutorials> <methods> <method name="save_to_wav"> diff --git a/doc/classes/BaseMaterial3D.xml b/doc/classes/BaseMaterial3D.xml index 72bfc2dcc7..653397ebc3 100644 --- a/doc/classes/BaseMaterial3D.xml +++ b/doc/classes/BaseMaterial3D.xml @@ -501,22 +501,22 @@ Represents the size of the [enum TextureParam] enum. </constant> <constant name="TEXTURE_FILTER_NEAREST" value="0" enum="TextureFilter"> - The texture filter reads from the nearest pixel only. The simplest and fastest method of filtering, but the texture will look pixelized. + The texture filter reads from the nearest pixel only. This makes the texture look pixelated from up close, and grainy from a distance (due to mipmaps not being sampled). </constant> <constant name="TEXTURE_FILTER_LINEAR" value="1" enum="TextureFilter"> - The texture filter blends between the nearest 4 pixels. Use this when you want to avoid a pixelated style, but do not want mipmaps. + The texture filter blends between the nearest 4 pixels. This makes the texture look smooth from up close, and grainy from a distance (due to mipmaps not being sampled). </constant> <constant name="TEXTURE_FILTER_NEAREST_WITH_MIPMAPS" value="2" enum="TextureFilter"> - The texture filter reads from the nearest pixel in the nearest mipmap. The fastest way to read from textures with mipmaps. + The texture filter reads from the nearest pixel and blends between the nearest 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]). This makes the texture look pixelated from up close, and smooth from a distance. </constant> <constant name="TEXTURE_FILTER_LINEAR_WITH_MIPMAPS" value="3" enum="TextureFilter"> - The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps. Use this for most cases as mipmaps are important to smooth out pixels that are far from the camera. + The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]). This makes the texture look smooth from up close, and smooth from a distance. </constant> <constant name="TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC" value="4" enum="TextureFilter"> - The texture filter reads from the nearest pixel, but selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. + The texture filter reads from the nearest pixel and blends between 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]) based on the angle between the surface and the camera view. This makes the texture look pixelated from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. </constant> <constant name="TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC" value="5" enum="TextureFilter"> - The texture filter blends between the nearest 4 pixels and selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. This is the slowest of the filtering options, but results in the highest quality texturing. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. + The texture filter blends between the nearest 4 pixels and blends between 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]) based on the angle between the surface and the camera view. This makes the texture look smooth from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. </constant> <constant name="TEXTURE_FILTER_MAX" value="6" enum="TextureFilter"> Represents the size of the [enum TextureFilter] enum. @@ -737,7 +737,7 @@ The object's X axis will always face the camera. </constant> <constant name="BILLBOARD_PARTICLES" value="3" enum="BillboardMode"> - Used for particle systems when assigned to [GPUParticles3D] and [CPUParticles3D] nodes. Enables [code]particles_anim_*[/code] properties. + Used for particle systems when assigned to [GPUParticles3D] and [CPUParticles3D] nodes (flipbook animation). Enables [code]particles_anim_*[/code] properties. The [member ParticleProcessMaterial.anim_speed_min] or [member CPUParticles3D.anim_speed_min] should also be set to a value bigger than zero for the animation to play. </constant> <constant name="TEXTURE_CHANNEL_RED" value="0" enum="TextureChannel"> diff --git a/doc/classes/CPUParticles2D.xml b/doc/classes/CPUParticles2D.xml index 051635cb48..92a57007bd 100644 --- a/doc/classes/CPUParticles2D.xml +++ b/doc/classes/CPUParticles2D.xml @@ -297,7 +297,7 @@ Particles are drawn in the order emitted. </constant> <constant name="DRAW_ORDER_LIFETIME" value="1" enum="DrawOrder"> - Particles are drawn in order of remaining lifetime. + Particles are drawn in order of remaining lifetime. In other words, the particle with the highest lifetime is drawn at the front. </constant> <constant name="PARAM_INITIAL_LINEAR_VELOCITY" value="0" enum="Parameter"> Use with [method set_param_min], [method set_param_max], and [method set_param_curve] to set initial velocity properties. diff --git a/doc/classes/CPUParticles3D.xml b/doc/classes/CPUParticles3D.xml index 9d16f3e8a4..27404b68bb 100644 --- a/doc/classes/CPUParticles3D.xml +++ b/doc/classes/CPUParticles3D.xml @@ -322,7 +322,7 @@ Particles are drawn in the order emitted. </constant> <constant name="DRAW_ORDER_LIFETIME" value="1" enum="DrawOrder"> - Particles are drawn in order of remaining lifetime. + Particles are drawn in order of remaining lifetime. In other words, the particle with the highest lifetime is drawn at the front. </constant> <constant name="DRAW_ORDER_VIEW_DEPTH" value="2" enum="DrawOrder"> Particles are drawn in order of depth. diff --git a/doc/classes/CameraAttributesPhysical.xml b/doc/classes/CameraAttributesPhysical.xml index 69af64b7ff..faedfee712 100644 --- a/doc/classes/CameraAttributesPhysical.xml +++ b/doc/classes/CameraAttributesPhysical.xml @@ -32,7 +32,7 @@ Only available when [member ProjectSettings.rendering/lights_and_shadows/use_physical_light_units] is enabled. </member> <member name="exposure_shutter_speed" type="float" setter="set_shutter_speed" getter="get_shutter_speed" default="100.0"> - Time for shutter to open and close, measured in seconds. A higher value will let in more light leading to a brighter image, while a lower amount will let in less light leading to a darker image. + Time for shutter to open and close, evaluated as [code]1 / shutter_speed[/code] seconds. A higher value will allow less light (leading to a darker image), while a lower value will allow more light (leading to a brighter image). Only available when [member ProjectSettings.rendering/lights_and_shadows/use_physical_light_units] is enabled. </member> <member name="frustum_far" type="float" setter="set_far" getter="get_far" default="4000.0"> diff --git a/doc/classes/CanvasItem.xml b/doc/classes/CanvasItem.xml index 84efd11b43..2f76f64cff 100644 --- a/doc/classes/CanvasItem.xml +++ b/doc/classes/CanvasItem.xml @@ -44,7 +44,7 @@ <param index="7" name="antialiased" type="bool" default="false" /> <description> Draws an unfilled arc between the given angles with a uniform [param color] and [param width] and optional antialiasing (supported only for positive [param width]). The larger the value of [param point_count], the smoother the curve. See also [method draw_circle]. - If [param width] is negative, then the arc is drawn using [constant RenderingServer.PRIMITIVE_LINE_STRIP]. This means that when the CanvasItem is scaled, the arc will remain thin. If this behavior is not desired, then pass a positive [param width] like [code]1.0[/code]. + If [param width] is negative, it will be ignored and the arc will be drawn using [constant RenderingServer.PRIMITIVE_LINE_STRIP]. This means that when the CanvasItem is scaled, the arc will remain thin. If this behavior is not desired, then pass a positive [param width] like [code]1.0[/code]. The arc is drawn from [param start_angle] towards the value of [param end_angle] so in clockwise direction if [code]start_angle < end_angle[/code] and counter-clockwise otherwise. Passing the same angles but in reversed order will produce the same arc. If absolute difference of [param start_angle] and [param end_angle] is greater than [constant @GDScript.TAU] radians, then a full circle arc is drawn (i.e. arc will not overlap itself). </description> </method> @@ -246,7 +246,7 @@ <param index="3" name="antialiased" type="bool" default="false" /> <description> Draws interconnected line segments with a uniform [param color] and [param width] and optional antialiasing (supported only for positive [param width]). When drawing large amounts of lines, this is faster than using individual [method draw_line] calls. To draw disconnected lines, use [method draw_multiline] instead. See also [method draw_polygon]. - If [param width] is negative, the polyline is drawn using [constant RenderingServer.PRIMITIVE_LINE_STRIP]. This means that when the CanvasItem is scaled, the polyline will remain thin. If this behavior is not desired, then pass a positive [param width] like [code]1.0[/code]. + If [param width] is negative, it will be ignored and the polyline will be drawn using [constant RenderingServer.PRIMITIVE_LINE_STRIP]. This means that when the CanvasItem is scaled, the polyline will remain thin. If this behavior is not desired, then pass a positive [param width] like [code]1.0[/code]. </description> </method> <method name="draw_polyline_colors"> @@ -257,7 +257,7 @@ <param index="3" name="antialiased" type="bool" default="false" /> <description> Draws interconnected line segments with a uniform [param width], point-by-point coloring, and optional antialiasing (supported only for positive [param width]). Colors assigned to line points match by index between [param points] and [param colors], i.e. each line segment is filled with a gradient between the colors of the endpoints. When drawing large amounts of lines, this is faster than using individual [method draw_line] calls. To draw disconnected lines, use [method draw_multiline_colors] instead. See also [method draw_polygon]. - If [param width] is negative, then the polyline is drawn using [constant RenderingServer.PRIMITIVE_LINE_STRIP]. This means that when the CanvasItem is scaled, the polyline will remain thin. If this behavior is not desired, then pass a positive [param width] like [code]1.0[/code]. + If [param width] is negative, it will be ignored and the polyline will be drawn using [constant RenderingServer.PRIMITIVE_LINE_STRIP]. This means that when the CanvasItem is scaled, the polyline will remain thin. If this behavior is not desired, then pass a positive [param width] like [code]1.0[/code]. </description> </method> <method name="draw_primitive"> @@ -660,24 +660,26 @@ The [CanvasItem] will inherit the filter from its parent. </constant> <constant name="TEXTURE_FILTER_NEAREST" value="1" enum="TextureFilter"> - The texture filter reads from the nearest pixel only. The simplest and fastest method of filtering. Useful for pixel art. + The texture filter reads from the nearest pixel only. This makes the texture look pixelated from up close, and grainy from a distance (due to mipmaps not being sampled). </constant> <constant name="TEXTURE_FILTER_LINEAR" value="2" enum="TextureFilter"> - The texture filter blends between the nearest four pixels. Use this for most cases where you want to avoid a pixelated style. + The texture filter blends between the nearest 4 pixels. This makes the texture look smooth from up close, and grainy from a distance (due to mipmaps not being sampled). </constant> <constant name="TEXTURE_FILTER_NEAREST_WITH_MIPMAPS" value="3" enum="TextureFilter"> - The texture filter reads from the nearest pixel in the nearest mipmap. This is the fastest way to read from textures with mipmaps. + The texture filter reads from the nearest pixel and blends between the nearest 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]). This makes the texture look pixelated from up close, and smooth from a distance. + Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to [Camera2D] zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. </constant> <constant name="TEXTURE_FILTER_LINEAR_WITH_MIPMAPS" value="4" enum="TextureFilter"> - The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps. Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to [Camera2D] zoom), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. + The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]). This makes the texture look smooth from up close, and smooth from a distance. + Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to [Camera2D] zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. </constant> <constant name="TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC" value="5" enum="TextureFilter"> - The texture filter reads from the nearest pixel, but selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. - [b]Note:[/b] This texture filter is rarely useful in 2D projects. [constant TEXTURE_FILTER_NEAREST_WITH_MIPMAPS] is usually more appropriate. + The texture filter reads from the nearest pixel and blends between 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]) based on the angle between the surface and the camera view. This makes the texture look pixelated from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. + [b]Note:[/b] This texture filter is rarely useful in 2D projects. [constant TEXTURE_FILTER_NEAREST_WITH_MIPMAPS] is usually more appropriate in this case. </constant> <constant name="TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC" value="6" enum="TextureFilter"> - The texture filter blends between the nearest 4 pixels and selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. This is the slowest of the filtering options, but results in the highest quality texturing. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. - [b]Note:[/b] This texture filter is rarely useful in 2D projects. [constant TEXTURE_FILTER_LINEAR_WITH_MIPMAPS] is usually more appropriate. + The texture filter blends between the nearest 4 pixels and blends between 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]) based on the angle between the surface and the camera view. This makes the texture look smooth from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. + [b]Note:[/b] This texture filter is rarely useful in 2D projects. [constant TEXTURE_FILTER_LINEAR_WITH_MIPMAPS] is usually more appropriate in this case. </constant> <constant name="TEXTURE_FILTER_MAX" value="7" enum="TextureFilter"> Represents the size of the [enum TextureFilter] enum. diff --git a/doc/classes/ConcavePolygonShape2D.xml b/doc/classes/ConcavePolygonShape2D.xml index 31e28bc714..6baf0f380f 100644 --- a/doc/classes/ConcavePolygonShape2D.xml +++ b/doc/classes/ConcavePolygonShape2D.xml @@ -5,7 +5,7 @@ </brief_description> <description> A 2D polyline shape, intended for use in physics. Used internally in [CollisionPolygon2D] when it's in [constant CollisionPolygon2D.BUILD_SEGMENTS] mode. - Being just a collection of interconnected line segments, [ConcavePolygonShape2D] is the most freely configurable single 2D shape. It can be used to form polygons of any nature, or even shapes that don't enclose an area. However, [ConvexPolygonShape2D] is [i]hollow[/i] even if the interconnected line segments do enclose an area, which often makes it unsuitable for physics or detection. + Being just a collection of interconnected line segments, [ConcavePolygonShape2D] is the most freely configurable single 2D shape. It can be used to form polygons of any nature, or even shapes that don't enclose an area. However, [ConcavePolygonShape2D] is [i]hollow[/i] even if the interconnected line segments do enclose an area, which often makes it unsuitable for physics or detection. [b]Note:[/b] When used for collision, [ConcavePolygonShape2D] is intended to work with static [CollisionShape2D] nodes like [StaticBody2D] and will likely not behave well for [CharacterBody2D]s or [RigidBody2D]s in a mode other than Static. [b]Warning:[/b] Physics bodies that are small have a chance to clip through this shape when moving fast. This happens because on one frame, the physics body may be on the "outside" of the shape, and on the next frame it may be "inside" it. [ConcavePolygonShape2D] is hollow, so it won't detect a collision. [b]Performance:[/b] Due to its complexity, [ConcavePolygonShape2D] is the slowest 2D collision shape to check collisions against. Its use should generally be limited to level geometry. If the polyline is closed, [CollisionPolygon2D]'s [constant CollisionPolygon2D.BUILD_SOLIDS] mode can be used, which decomposes the polygon into convex ones; see [ConvexPolygonShape2D]'s documentation for instructions. diff --git a/doc/classes/ConcavePolygonShape3D.xml b/doc/classes/ConcavePolygonShape3D.xml index c0d0f43010..7e4df2073f 100644 --- a/doc/classes/ConcavePolygonShape3D.xml +++ b/doc/classes/ConcavePolygonShape3D.xml @@ -5,7 +5,7 @@ </brief_description> <description> A 3D trimesh shape, intended for use in physics. Usually used to provide a shape for a [CollisionShape3D]. - Being just a collection of interconnected triangles, [ConcavePolygonShape3D] is the most freely configurable single 3D shape. It can be used to form polyhedra of any nature, or even shapes that don't enclose a volume. However, [ConvexPolygonShape3D] is [i]hollow[/i] even if the interconnected triangles do enclose a volume, which often makes it unsuitable for physics or detection. + Being just a collection of interconnected triangles, [ConcavePolygonShape3D] is the most freely configurable single 3D shape. It can be used to form polyhedra of any nature, or even shapes that don't enclose a volume. However, [ConcavePolygonShape3D] is [i]hollow[/i] even if the interconnected triangles do enclose a volume, which often makes it unsuitable for physics or detection. [b]Note:[/b] When used for collision, [ConcavePolygonShape3D] is intended to work with static [CollisionShape3D] nodes like [StaticBody3D] and will likely not behave well for [CharacterBody3D]s or [RigidBody3D]s in a mode other than Static. [b]Warning:[/b] Physics bodies that are small have a chance to clip through this shape when moving fast. This happens because on one frame, the physics body may be on the "outside" of the shape, and on the next frame it may be "inside" it. [ConcavePolygonShape3D] is hollow, so it won't detect a collision. [b]Performance:[/b] Due to its complexity, [ConcavePolygonShape3D] is the slowest 3D collision shape to check collisions against. Its use should generally be limited to level geometry. For convex geometry, [ConvexPolygonShape3D] should be used. For dynamic physics bodies that need concave collision, several [ConvexPolygonShape3D]s can be used to represent its collision by using convex decomposition; see [ConvexPolygonShape3D]'s documentation for instructions. diff --git a/doc/classes/Control.xml b/doc/classes/Control.xml index 21d6cb2756..a498bbeed3 100644 --- a/doc/classes/Control.xml +++ b/doc/classes/Control.xml @@ -1104,13 +1104,13 @@ </signal> <signal name="mouse_entered"> <description> - Emitted when the mouse cursor enters the control's visible area, that is not occluded behind other Controls or Windows, provided its [member mouse_filter] lets the event reach it and regardless if it's currently focused or not. + Emitted when the mouse cursor enters the control's (or any child control's) visible area, that is not occluded behind other Controls or Windows, provided its [member mouse_filter] lets the event reach it and regardless if it's currently focused or not. [b]Note:[/b] [member CanvasItem.z_index] doesn't affect, which Control receives the signal. </description> </signal> <signal name="mouse_exited"> <description> - Emitted when the mouse cursor leaves the control's visible area, that is not occluded behind other Controls or Windows, provided its [member mouse_filter] lets the event reach it and regardless if it's currently focused or not. + Emitted when the mouse cursor leaves the control's (and all child control's) visible area, that is not occluded behind other Controls or Windows, provided its [member mouse_filter] lets the event reach it and regardless if it's currently focused or not. [b]Note:[/b] [member CanvasItem.z_index] doesn't affect, which Control receives the signal. [b]Note:[/b] If you want to check whether the mouse truly left the area, ignoring any top nodes, you can use code like this: [codeblock] @@ -1150,12 +1150,24 @@ Sent when the node changes size. Use [member size] to get the new size. </constant> <constant name="NOTIFICATION_MOUSE_ENTER" value="41"> - Sent when the mouse cursor enters the control's visible area, that is not occluded behind other Controls or Windows, provided its [member mouse_filter] lets the event reach it and regardless if it's currently focused or not. - [b]Note:[/b] [member CanvasItem.z_index] doesn't affect, which Control receives the notification. + Sent when the mouse cursor enters the control's (or any child control's) visible area, that is not occluded behind other Controls or Windows, provided its [member mouse_filter] lets the event reach it and regardless if it's currently focused or not. + [b]Note:[/b] [member CanvasItem.z_index] doesn't affect which Control receives the notification. + See also [constant NOTIFICATION_MOUSE_ENTER_SELF]. </constant> <constant name="NOTIFICATION_MOUSE_EXIT" value="42"> + Sent when the mouse cursor leaves the control's (and all child control's) visible area, that is not occluded behind other Controls or Windows, provided its [member mouse_filter] lets the event reach it and regardless if it's currently focused or not. + [b]Note:[/b] [member CanvasItem.z_index] doesn't affect which Control receives the notification. + See also [constant NOTIFICATION_MOUSE_EXIT_SELF]. + </constant> + <constant name="NOTIFICATION_MOUSE_ENTER_SELF" value="60" is_experimental="true"> + Sent when the mouse cursor enters the control's visible area, that is not occluded behind other Controls or Windows, provided its [member mouse_filter] lets the event reach it and regardless if it's currently focused or not. + [b]Note:[/b] [member CanvasItem.z_index] doesn't affect which Control receives the notification. + See also [constant NOTIFICATION_MOUSE_ENTER]. + </constant> + <constant name="NOTIFICATION_MOUSE_EXIT_SELF" value="61" is_experimental="true"> Sent when the mouse cursor leaves the control's visible area, that is not occluded behind other Controls or Windows, provided its [member mouse_filter] lets the event reach it and regardless if it's currently focused or not. - [b]Note:[/b] [member CanvasItem.z_index] doesn't affect, which Control receives the notification. + [b]Note:[/b] [member CanvasItem.z_index] doesn't affect which Control receives the notification. + See also [constant NOTIFICATION_MOUSE_EXIT]. </constant> <constant name="NOTIFICATION_FOCUS_ENTER" value="43"> Sent when the node grabs focus. @@ -1172,10 +1184,12 @@ [b]Note:[/b] As an optimization, this notification won't be sent from changes that occur while this node is outside of the scene tree. Instead, all of the theme item updates can be applied at once when the node enters the scene tree. </constant> <constant name="NOTIFICATION_SCROLL_BEGIN" value="47"> - Sent when this node is inside a [ScrollContainer] which has begun being scrolled. + Sent when this node is inside a [ScrollContainer] which has begun being scrolled when dragging the scrollable area [i]with a touch event[/i]. This notification is [i]not[/i] sent when scrolling by dragging the scrollbar, scrolling with the mouse wheel or scrolling with keyboard/gamepad events. + [b]Note:[/b] This signal is only emitted on Android or iOS, or on desktop/web platforms when [member ProjectSettings.input_devices/pointing/emulate_touch_from_mouse] is enabled. </constant> <constant name="NOTIFICATION_SCROLL_END" value="48"> - Sent when this node is inside a [ScrollContainer] which has stopped being scrolled. + Sent when this node is inside a [ScrollContainer] which has stopped being scrolled when dragging the scrollable area [i]with a touch event[/i]. This notification is [i]not[/i] sent when scrolling by dragging the scrollbar, scrolling with the mouse wheel or scrolling with keyboard/gamepad events. + [b]Note:[/b] This signal is only emitted on Android or iOS, or on desktop/web platforms when [member ProjectSettings.input_devices/pointing/emulate_touch_from_mouse] is enabled. </constant> <constant name="NOTIFICATION_LAYOUT_DIRECTION_CHANGED" value="49"> Sent when control layout direction is changed. @@ -1318,6 +1332,7 @@ </constant> <constant name="MOUSE_FILTER_IGNORE" value="2" enum="MouseFilter"> The control will not receive mouse movement input events and mouse button input events if clicked on through [method _gui_input]. The control will also not receive the [signal mouse_entered] nor [signal mouse_exited] signals. This will not block other controls from receiving these events or firing the signals. Ignored events will not be handled automatically. + [b]Note:[/b] If the control has received [signal mouse_entered] but not [signal mouse_exited], changing the [member mouse_filter] to [constant MOUSE_FILTER_IGNORE] will cause [signal mouse_exited] to be emitted. </constant> <constant name="GROW_DIRECTION_BEGIN" value="0" enum="GrowDirection"> The control will grow to the left or top to make up if its minimum size is changed to be greater than its current size on the respective axis. diff --git a/doc/classes/Dictionary.xml b/doc/classes/Dictionary.xml index b39c5c9699..7a5e51e4ef 100644 --- a/doc/classes/Dictionary.xml +++ b/doc/classes/Dictionary.xml @@ -194,6 +194,14 @@ Returns the corresponding value for the given [param key] in the dictionary. If the [param key] does not exist, returns [param default], or [code]null[/code] if the parameter is omitted. </description> </method> + <method name="get_or_add"> + <return type="Variant" /> + <param index="0" name="key" type="Variant" /> + <param index="1" name="default" type="Variant" default="null" /> + <description> + Gets a value and ensures the key is set. If the [param key] exists in the dictionary, this behaves like [method get]. Otherwise, the [param default] value is inserted into the dictionary and returned. + </description> + </method> <method name="has" qualifiers="const"> <return type="bool" /> <param index="0" name="key" type="Variant" /> @@ -294,6 +302,42 @@ <param index="1" name="overwrite" type="bool" default="false" /> <description> Adds entries from [param dictionary] to this dictionary. By default, duplicate keys are not copied over, unless [param overwrite] is [code]true[/code]. + [codeblocks] + [gdscript] + var dict = { "item": "sword", "quantity": 2 } + var other_dict = { "quantity": 15, "color": "silver" } + + # Overwriting of existing keys is disabled by default. + dict.merge(other_dict) + print(dict) # { "item": "sword", "quantity": 2, "color": "silver" } + + # With overwriting of existing keys enabled. + dict.merge(other_dict, true) + print(dict) # { "item": "sword", "quantity": 15, "color": "silver" } + [/gdscript] + [csharp] + var dict = new Godot.Collections.Dictionary + { + ["item"] = "sword", + ["quantity"] = 2, + }; + + var otherDict = new Godot.Collections.Dictionary + { + ["quantity"] = 15, + ["color"] = "silver", + }; + + // Overwriting of existing keys is disabled by default. + dict.Merge(otherDict); + GD.Print(dict); // { "item": "sword", "quantity": 2, "color": "silver" } + + // With overwriting of existing keys enabled. + dict.Merge(otherDict, true); + GD.Print(dict); // { "item": "sword", "quantity": 15, "color": "silver" } + [/csharp] + [/codeblocks] + [b]Note:[/b] [method merge] is [i]not[/i] recursive. Nested dictionaries are considered as keys that can be overwritten or not depending on the value of [param overwrite], but they will never be merged together. </description> </method> <method name="size" qualifiers="const"> diff --git a/doc/classes/DisplayServer.xml b/doc/classes/DisplayServer.xml index 3c7d66a67b..8436cbf6ee 100644 --- a/doc/classes/DisplayServer.xml +++ b/doc/classes/DisplayServer.xml @@ -235,6 +235,9 @@ [codeblock] "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). [/codeblock] </description> </method> @@ -258,6 +261,9 @@ [codeblock] "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). [/codeblock] </description> </method> @@ -281,6 +287,9 @@ [codeblock] "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). [/codeblock] </description> </method> @@ -305,6 +314,9 @@ [codeblock] "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). [/codeblock] </description> </method> @@ -327,6 +339,9 @@ [codeblock] "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). [/codeblock] </description> </method> @@ -353,6 +368,9 @@ [codeblock] "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). [/codeblock] </description> </method> @@ -376,6 +394,9 @@ [codeblock] "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). [/codeblock] </description> </method> @@ -391,6 +412,9 @@ [codeblock] "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). [/codeblock] </description> </method> @@ -408,6 +432,9 @@ [codeblock] "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). [/codeblock] </description> </method> @@ -421,6 +448,9 @@ [codeblock] "_main" - Main menu (macOS). "_dock" - Dock popup menu (macOS). + "_apple" - Apple menu (macOS, custom items added before "Services"). + "_window" - Window menu (macOS, custom items added after "Bring All to Front"). + "_help" - Help menu (macOS). [/codeblock] </description> </method> @@ -549,6 +579,13 @@ [b]Note:[/b] This method is implemented only on macOS. </description> </method> + <method name="global_menu_get_system_menu_roots" qualifiers="const"> + <return type="Dictionary" /> + <description> + Returns Dictionary of supported system menu IDs and names. + [b]Note:[/b] This method is implemented only on macOS. + </description> + </method> <method name="global_menu_is_item_checkable" qualifiers="const"> <return type="bool" /> <param index="0" name="menu_root" type="String" /> @@ -1085,6 +1122,10 @@ <param index="0" name="name" type="String" /> <description> Set active tablet driver name. + Supported drivers: + - [code]winink[/code]: Windows Ink API, default (Windows 8.1+ required). + - [code]wintab[/code]: Wacom Wintab API (compatible device driver required). + - [code]dummy[/code]: Dummy driver, tablet input is disabled. [b]Note:[/b] This method is implemented only on Windows. </description> </method> @@ -1403,6 +1444,7 @@ <param index="1" name="window_id" type="int" default="0" /> <description> Sets the [param callback] that should be called when files are dropped from the operating system's file manager to the window specified by [param window_id]. + [b]Warning:[/b] Advanced users only! Adding such a callback to a [Window] node will override its default implementation, which can introduce bugs. [b]Note:[/b] This method is implemented on Windows, macOS, Linux (X11) and Web. </description> </method> @@ -1447,6 +1489,7 @@ <param index="1" name="window_id" type="int" default="0" /> <description> Sets the [param callback] that should be called when any [InputEvent] is sent to the window specified by [param window_id]. + [b]Warning:[/b] Advanced users only! Adding such a callback to a [Window] node will override its default implementation, which can introduce bugs. </description> </method> <method name="window_set_input_text_callback"> @@ -1455,6 +1498,7 @@ <param index="1" name="window_id" type="int" default="0" /> <description> Sets the [param callback] that should be called when text is entered using the virtual keyboard to the window specified by [param window_id]. + [b]Warning:[/b] Advanced users only! Adding such a callback to a [Window] node will override its default implementation, which can introduce bugs. </description> </method> <method name="window_set_max_size"> @@ -1552,6 +1596,7 @@ <param index="1" name="window_id" type="int" default="0" /> <description> Sets the [param callback] that will be called when the window specified by [param window_id] is moved or resized. + [b]Warning:[/b] Advanced users only! Adding such a callback to a [Window] node will override its default implementation, which can introduce bugs. </description> </method> <method name="window_set_size"> @@ -1609,6 +1654,7 @@ <param index="1" name="window_id" type="int" default="0" /> <description> Sets the [param callback] that will be called when an event occurs in the window specified by [param window_id]. + [b]Warning:[/b] Advanced users only! Adding such a callback to a [Window] node will override its default implementation, which can introduce bugs. </description> </method> </methods> @@ -1882,30 +1928,30 @@ Max value of the [enum WindowFlags]. </constant> <constant name="WINDOW_EVENT_MOUSE_ENTER" value="0" enum="WindowEvent"> - Sent when the mouse pointer enters the window, see [method window_set_window_event_callback]. + Sent when the mouse pointer enters the window. </constant> <constant name="WINDOW_EVENT_MOUSE_EXIT" value="1" enum="WindowEvent"> - Sent when the mouse pointer exits the window, see [method window_set_window_event_callback]. + Sent when the mouse pointer exits the window. </constant> <constant name="WINDOW_EVENT_FOCUS_IN" value="2" enum="WindowEvent"> - Sent when the window grabs focus, see [method window_set_window_event_callback]. + Sent when the window grabs focus. </constant> <constant name="WINDOW_EVENT_FOCUS_OUT" value="3" enum="WindowEvent"> - Sent when the window loses focus, see [method window_set_window_event_callback]. + Sent when the window loses focus. </constant> <constant name="WINDOW_EVENT_CLOSE_REQUEST" value="4" enum="WindowEvent"> - Sent when the user has attempted to close the window (e.g. close button is pressed), see [method window_set_window_event_callback]. + Sent when the user has attempted to close the window (e.g. close button is pressed). </constant> <constant name="WINDOW_EVENT_GO_BACK_REQUEST" value="5" enum="WindowEvent"> - Sent when the device "Back" button is pressed, see [method window_set_window_event_callback]. + Sent when the device "Back" button is pressed. [b]Note:[/b] This event is implemented only on Android. </constant> <constant name="WINDOW_EVENT_DPI_CHANGE" value="6" enum="WindowEvent"> - Sent when the window is moved to the display with different DPI, or display DPI is changed, see [method window_set_window_event_callback]. + Sent when the window is moved to the display with different DPI, or display DPI is changed. [b]Note:[/b] This flag is implemented only on macOS. </constant> <constant name="WINDOW_EVENT_TITLEBAR_CHANGE" value="7" enum="WindowEvent"> - Sent when the window title bar decoration is changed (e.g. [constant WINDOW_FLAG_EXTEND_TO_TITLE] is set or window entered/exited full screen mode), see [method window_set_window_event_callback]. + Sent when the window title bar decoration is changed (e.g. [constant WINDOW_FLAG_EXTEND_TO_TITLE] is set or window entered/exited full screen mode). [b]Note:[/b] This flag is implemented only on macOS. </constant> <constant name="VSYNC_DISABLED" value="0" enum="VSyncMode"> diff --git a/doc/classes/EditorPlugin.xml b/doc/classes/EditorPlugin.xml index 6f858942aa..50709f9ef5 100644 --- a/doc/classes/EditorPlugin.xml +++ b/doc/classes/EditorPlugin.xml @@ -541,7 +541,7 @@ <param index="0" name="name" type="String" /> <param index="1" name="submenu" type="PopupMenu" /> <description> - Adds a custom [PopupMenu] submenu under [b]Project > Tools >[/b] [param name]. Use [code]remove_tool_menu_item(name)[/code] on plugin clean up to remove the menu. + Adds a custom [PopupMenu] submenu under [b]Project > Tools >[/b] [param name]. Use [method remove_tool_menu_item] on plugin clean up to remove the menu. </description> </method> <method name="add_translation_parser_plugin"> diff --git a/doc/classes/EditorSettings.xml b/doc/classes/EditorSettings.xml index 6edd8af7cc..ec051c0545 100644 --- a/doc/classes/EditorSettings.xml +++ b/doc/classes/EditorSettings.xml @@ -665,8 +665,8 @@ <member name="interface/theme/icon_and_font_color" type="int" setter="" getter=""> The icon and font color scheme to use in the editor. - [b]Auto[/b] determines the color scheme to use automatically based on [member interface/theme/base_color]. - - [b]Dark[/b] makes fonts and icons light (suitable for dark themes). - - [b]Light[/b] makes fonts and icons dark (suitable for light themes). Icon colors are automatically converted by the editor following [url=https://github.com/godotengine/godot/blob/master/editor/editor_themes.cpp#L135]this set of rules[/url]. + - [b]Dark[/b] makes fonts and icons dark (suitable for light themes). Icon colors are automatically converted by the editor following the set of rules defined in [url=https://github.com/godotengine/godot/blob/master/editor/editor_themes.cpp]this file[/url]. + - [b]Light[/b] makes fonts and icons light (suitable for dark themes). </member> <member name="interface/theme/icon_saturation" type="float" setter="" getter=""> The saturation to use for editor icons. Higher values result in more vibrant colors. diff --git a/doc/classes/EditorSpinSlider.xml b/doc/classes/EditorSpinSlider.xml index 6e5ccb4dd0..7108f873e6 100644 --- a/doc/classes/EditorSpinSlider.xml +++ b/doc/classes/EditorSpinSlider.xml @@ -5,6 +5,7 @@ </brief_description> <description> This [Control] node is used in the editor's Inspector dock to allow editing of numeric values. Can be used with [EditorInspectorPlugin] to recreate the same behavior. + If the [member Range.step] value is [code]1[/code], the [EditorSpinSlider] will display up/down arrows, similar to [SpinBox]. If the [member Range.step] value is not [code]1[/code], a slider will be displayed instead. </description> <tutorials> </tutorials> @@ -14,7 +15,7 @@ </member> <member name="focus_mode" type="int" setter="set_focus_mode" getter="get_focus_mode" overrides="Control" enum="Control.FocusMode" default="2" /> <member name="hide_slider" type="bool" setter="set_hide_slider" getter="is_hiding_slider" default="false"> - If [code]true[/code], the slider is hidden. + If [code]true[/code], the slider and up/down arrows are hidden. </member> <member name="label" type="String" setter="set_label" getter="get_label" default=""""> The text that displays to the left of the value. diff --git a/doc/classes/Engine.xml b/doc/classes/Engine.xml index 207cd0bccc..0a544077e4 100644 --- a/doc/classes/Engine.xml +++ b/doc/classes/Engine.xml @@ -307,6 +307,8 @@ </member> <member name="time_scale" type="float" setter="set_time_scale" getter="get_time_scale" default="1.0"> Controls how fast or slow the in-game clock ticks versus the real life one. It defaults to 1.0. A value of 2.0 means the game moves twice as fast as real life, whilst a value of 0.5 means the game moves at half the regular speed. This also affects [Timer] and [SceneTreeTimer] (see [method SceneTree.create_timer] for how to control this). + [b]Note:[/b] This does not affect audio playback speed. Use [member AudioServer.playback_speed_scale] to adjust audio playback speed independently of [member Engine.time_scale]. + [b]Note:[/b] This does not automatically adjust [member physics_ticks_per_second], which means that with time scales above 1.0, physics simulation may become less precise (as each physics tick will stretch over a larger period of engine time). If you're using [member Engine.time_scale] to speed up simulation by a large factor, consider increasing [member physics_ticks_per_second] as well to improve physics reliability. </member> </members> </class> diff --git a/doc/classes/FileAccess.xml b/doc/classes/FileAccess.xml index d1b20a3890..df8ebc12fa 100644 --- a/doc/classes/FileAccess.xml +++ b/doc/classes/FileAccess.xml @@ -39,6 +39,7 @@ </description> <tutorials> <link title="File system">$DOCS_URL/tutorials/scripting/filesystem.html</link> + <link title="Runtime file loading and saving">$DOCS_URL/tutorials/io/runtime_file_loading_and_saving.html</link> <link title="3D Voxel Demo">https://godotengine.org/asset-library/asset/676</link> </tutorials> <methods> diff --git a/doc/classes/FontFile.xml b/doc/classes/FontFile.xml index 53d367817d..87d647486c 100644 --- a/doc/classes/FontFile.xml +++ b/doc/classes/FontFile.xml @@ -28,6 +28,7 @@ [/codeblocks] </description> <tutorials> + <link title="Runtime file loading and saving">$DOCS_URL/tutorials/io/runtime_file_loading_and_saving.html</link> </tutorials> <methods> <method name="clear_cache"> diff --git a/doc/classes/GPUParticles2D.xml b/doc/classes/GPUParticles2D.xml index 54c8689ab0..f4ba305f8b 100644 --- a/doc/classes/GPUParticles2D.xml +++ b/doc/classes/GPUParticles2D.xml @@ -37,6 +37,7 @@ <param index="4" name="flags" type="int" /> <description> Emits a single particle. Whether [param xform], [param velocity], [param color] and [param custom] are applied depends on the value of [param flags]. See [enum EmitFlags]. + The default ParticleProcessMaterial will overwrite [param color] and use the contents of [param custom] as [code](rotation, age, animation, lifetime)[/code]. </description> </method> <method name="restart"> @@ -48,14 +49,16 @@ </methods> <members> <member name="amount" type="int" setter="set_amount" getter="get_amount" default="8"> - Number of particles emitted in one emission cycle. + The number of particles to emit in one emission cycle. The effective emission rate is [code](amount * amount_ratio) / lifetime[/code] particles per second. Higher values will increase GPU requirements, even if not all particles are visible at a given time or if [member amount_ratio] is decreased. + [b]Note:[/b] Changing this value will cause the particle system to restart. To avoid this, change [member amount_ratio] instead. </member> <member name="amount_ratio" type="float" setter="set_amount_ratio" getter="get_amount_ratio" default="1.0"> The ratio of particles that should actually be emitted. If set to a value lower than [code]1.0[/code], this will set the amount of emitted particles throughout the lifetime to [code]amount * amount_ratio[/code]. Unlike changing [member amount], changing [member amount_ratio] while emitting does not affect already-emitted particles and doesn't cause the particle system to restart. [member amount_ratio] can be used to create effects that make the number of emitted particles vary over time. - [b]Note:[/b] Reducing the [member amount_ratio] has no performance benefit, since resources need to be allocated and processed for the total [member amount] of particles regardless of the [member amount_ratio]. + [b]Note:[/b] Reducing the [member amount_ratio] has no performance benefit, since resources need to be allocated and processed for the total [member amount] of particles regardless of the [member amount_ratio]. If you don't intend to change the number of particles emitted while the particles are emitting, make sure [member amount_ratio] is set to [code]1[/code] and change [member amount] to your liking instead. </member> <member name="collision_base_size" type="float" setter="set_collision_base_size" getter="get_collision_base_size" default="1.0"> - Multiplier for particle's collision radius. [code]1.0[/code] corresponds to the size of the sprite. + Multiplier for particle's collision radius. [code]1.0[/code] corresponds to the size of the sprite. If particles appear to sink into the ground when colliding, increase this value. If particles appear to float when colliding, decrease this value. Only effective if [member ParticleProcessMaterial.collision_mode] is [constant ParticleProcessMaterial.COLLISION_RIGID] or [constant ParticleProcessMaterial.COLLISION_HIDE_ON_CONTACT]. + [b]Note:[/b] Particles always have a spherical collision shape. </member> <member name="draw_order" type="int" setter="set_draw_order" getter="get_draw_order" enum="GPUParticles2D.DrawOrder" default="1"> Particle draw order. Uses [enum DrawOrder] values. @@ -74,13 +77,13 @@ </member> <member name="interp_to_end" type="float" setter="set_interp_to_end" getter="get_interp_to_end" default="0.0"> Causes all the particles in this node to interpolate towards the end of their lifetime. - [b]Note[/b]: This only works when used with a [ParticleProcessMaterial]. It needs to be manually implemented for custom process shaders. + [b]Note:[/b] This only works when used with a [ParticleProcessMaterial]. It needs to be manually implemented for custom process shaders. </member> <member name="interpolate" type="bool" setter="set_interpolate" getter="get_interpolate" default="true"> Enables particle interpolation, which makes the particle movement smoother when their [member fixed_fps] is lower than the screen refresh rate. </member> <member name="lifetime" type="float" setter="set_lifetime" getter="get_lifetime" default="1.0"> - Amount of time each particle will exist. + The amount of time each particle will exist (in seconds). The effective emission rate is [code](amount * amount_ratio) / lifetime[/code] particles per second. </member> <member name="local_coords" type="bool" setter="set_use_local_coordinates" getter="get_use_local_coordinates" default="false"> If [code]true[/code], particles use the parent node's coordinate space (known as local coordinates). This will cause particles to move and rotate along the [GPUParticles2D] node (and its parents) when it is moved or rotated. If [code]false[/code], particles use global coordinates; they will not move or rotate along the [GPUParticles2D] node (and its parents) when it is moved or rotated. @@ -101,10 +104,12 @@ Particle system's running speed scaling ratio. A value of [code]0[/code] can be used to pause the particles. </member> <member name="sub_emitter" type="NodePath" setter="set_sub_emitter" getter="get_sub_emitter" default="NodePath("")"> - The [NodePath] to the [GPUParticles2D] used for sub-emissions. + Path to another [GPUParticles2D] node that will be used as a subemitter (see [member ParticleProcessMaterial.sub_emitter_mode]). Subemitters can be used to achieve effects such as fireworks, sparks on collision, bubbles popping into water drops, and more. + [b]Note:[/b] When [member sub_emitter] is set, the target [GPUParticles2D] node will no longer emit particles on its own. </member> <member name="texture" type="Texture2D" setter="set_texture" getter="get_texture"> - Particle texture. If [code]null[/code], particles will be squares. + Particle texture. If [code]null[/code], particles will be squares with a size of 1×1 pixels. + [b]Note:[/b] To use a flipbook texture, assign a new [CanvasItemMaterial] to the [GPUParticles2D]'s [member CanvasItem.material] property, then enable [member CanvasItemMaterial.particles_animation] and set [member CanvasItemMaterial.particles_anim_h_frames], [member CanvasItemMaterial.particles_anim_v_frames], and [member CanvasItemMaterial.particles_anim_loop] to match the flipbook texture. </member> <member name="trail_enabled" type="bool" setter="set_trail_enabled" getter="is_trail_enabled" default="false"> If [code]true[/code], enables particle trails using a mesh skinning system. @@ -137,9 +142,10 @@ Particles are drawn in the order emitted. </constant> <constant name="DRAW_ORDER_LIFETIME" value="1" enum="DrawOrder"> - Particles are drawn in order of remaining lifetime. + Particles are drawn in order of remaining lifetime. In other words, the particle with the highest lifetime is drawn at the front. </constant> <constant name="DRAW_ORDER_REVERSE_LIFETIME" value="2" enum="DrawOrder"> + Particles are drawn in reverse order of remaining lifetime. In other words, the particle with the lowest lifetime is drawn at the front. </constant> <constant name="EMIT_FLAG_POSITION" value="1" enum="EmitFlags"> Particle starts at the specified position. diff --git a/doc/classes/GPUParticles3D.xml b/doc/classes/GPUParticles3D.xml index dc7e51b7d7..d1903b85cd 100644 --- a/doc/classes/GPUParticles3D.xml +++ b/doc/classes/GPUParticles3D.xml @@ -35,6 +35,7 @@ <param index="4" name="flags" type="int" /> <description> Emits a single particle. Whether [param xform], [param velocity], [param color] and [param custom] are applied depends on the value of [param flags]. See [enum EmitFlags]. + The default ParticleProcessMaterial will overwrite [param color] and use the contents of [param custom] as [code](rotation, age, animation, lifetime)[/code]. </description> </method> <method name="get_draw_pass_mesh" qualifiers="const"> @@ -61,13 +62,16 @@ </methods> <members> <member name="amount" type="int" setter="set_amount" getter="get_amount" default="8"> - Number of particles to emit. + The number of particles to emit in one emission cycle. The effective emission rate is [code](amount * amount_ratio) / lifetime[/code] particles per second. Higher values will increase GPU requirements, even if not all particles are visible at a given time or if [member amount_ratio] is decreased. + [b]Note:[/b] Changing this value will cause the particle system to restart. To avoid this, change [member amount_ratio] instead. </member> <member name="amount_ratio" type="float" setter="set_amount_ratio" getter="get_amount_ratio" default="1.0"> The ratio of particles that should actually be emitted. If set to a value lower than [code]1.0[/code], this will set the amount of emitted particles throughout the lifetime to [code]amount * amount_ratio[/code]. Unlike changing [member amount], changing [member amount_ratio] while emitting does not affect already-emitted particles and doesn't cause the particle system to restart. [member amount_ratio] can be used to create effects that make the number of emitted particles vary over time. - [b]Note:[/b] Reducing the [member amount_ratio] has no performance benefit, since resources need to be allocated and processed for the total [member amount] of particles regardless of the [member amount_ratio]. + [b]Note:[/b] Reducing the [member amount_ratio] has no performance benefit, since resources need to be allocated and processed for the total [member amount] of particles regardless of the [member amount_ratio]. If you don't intend to change the number of particles emitted while the particles are emitting, make sure [member amount_ratio] is set to [code]1[/code] and change [member amount] to your liking instead. </member> <member name="collision_base_size" type="float" setter="set_collision_base_size" getter="get_collision_base_size" default="0.01"> + The base diameter for particle collision in meters. If particles appear to sink into the ground when colliding, increase this value. If particles appear to float when colliding, decrease this value. Only effective if [member ParticleProcessMaterial.collision_mode] is [constant ParticleProcessMaterial.COLLISION_RIGID] or [constant ParticleProcessMaterial.COLLISION_HIDE_ON_CONTACT]. + [b]Note:[/b] Particles always have a spherical collision shape. </member> <member name="draw_order" type="int" setter="set_draw_order" getter="get_draw_order" enum="GPUParticles3D.DrawOrder" default="0"> Particle draw order. Uses [enum DrawOrder] values. @@ -104,13 +108,13 @@ </member> <member name="interp_to_end" type="float" setter="set_interp_to_end" getter="get_interp_to_end" default="0.0"> Causes all the particles in this node to interpolate towards the end of their lifetime. - [b]Note[/b]: This only works when used with a [ParticleProcessMaterial]. It needs to be manually implemented for custom process shaders. + [b]Note:[/b] This only works when used with a [ParticleProcessMaterial]. It needs to be manually implemented for custom process shaders. </member> <member name="interpolate" type="bool" setter="set_interpolate" getter="get_interpolate" default="true"> Enables particle interpolation, which makes the particle movement smoother when their [member fixed_fps] is lower than the screen refresh rate. </member> <member name="lifetime" type="float" setter="set_lifetime" getter="get_lifetime" default="1.0"> - Amount of time each particle will exist. + The amount of time each particle will exist (in seconds). The effective emission rate is [code](amount * amount_ratio) / lifetime[/code] particles per second. </member> <member name="local_coords" type="bool" setter="set_use_local_coordinates" getter="get_use_local_coordinates" default="false"> If [code]true[/code], particles use the parent node's coordinate space (known as local coordinates). This will cause particles to move and rotate along the [GPUParticles3D] node (and its parents) when it is moved or rotated. If [code]false[/code], particles use global coordinates; they will not move or rotate along the [GPUParticles3D] node (and its parents) when it is moved or rotated. @@ -131,6 +135,8 @@ Speed scaling ratio. A value of [code]0[/code] can be used to pause the particles. </member> <member name="sub_emitter" type="NodePath" setter="set_sub_emitter" getter="get_sub_emitter" default="NodePath("")"> + Path to another [GPUParticles3D] node that will be used as a subemitter (see [member ParticleProcessMaterial.sub_emitter_mode]). Subemitters can be used to achieve effects such as fireworks, sparks on collision, bubbles popping into water drops, and more. + [b]Note:[/b] When [member sub_emitter] is set, the target [GPUParticles3D] node will no longer emit particles on its own. </member> <member name="trail_enabled" type="bool" setter="set_trail_enabled" getter="is_trail_enabled" default="false"> If [code]true[/code], enables particle trails using a mesh skinning system. Designed to work with [RibbonTrailMesh] and [TubeTrailMesh]. @@ -143,8 +149,9 @@ <member name="transform_align" type="int" setter="set_transform_align" getter="get_transform_align" enum="GPUParticles3D.TransformAlign" default="0"> </member> <member name="visibility_aabb" type="AABB" setter="set_visibility_aabb" getter="get_visibility_aabb" default="AABB(-4, -4, -4, 8, 8, 8)"> - The [AABB] that determines the node's region which needs to be visible on screen for the particle system to be active. + The [AABB] that determines the node's region which needs to be visible on screen for the particle system to be active. [member GeometryInstance3D.extra_cull_margin] is added on each of the AABB's axes. Particle collisions and attraction will only occur within this area. Grow the box if particles suddenly appear/disappear when the node enters/exits the screen. The [AABB] can be grown via code or with the [b]Particles → Generate AABB[/b] editor tool. + [b]Note:[/b] [member visibility_aabb] is overridden by [member GeometryInstance3D.custom_aabb] if that property is set to a non-default value. </member> </members> <signals> @@ -160,9 +167,10 @@ Particles are drawn in the order emitted. </constant> <constant name="DRAW_ORDER_LIFETIME" value="1" enum="DrawOrder"> - Particles are drawn in order of remaining lifetime. + Particles are drawn in order of remaining lifetime. In other words, the particle with the highest lifetime is drawn at the front. </constant> <constant name="DRAW_ORDER_REVERSE_LIFETIME" value="2" enum="DrawOrder"> + Particles are drawn in reverse order of remaining lifetime. In other words, the particle with the lowest lifetime is drawn at the front. </constant> <constant name="DRAW_ORDER_VIEW_DEPTH" value="3" enum="DrawOrder"> Particles are drawn in order of depth. diff --git a/doc/classes/GraphEdit.xml b/doc/classes/GraphEdit.xml index 410efd6389..9765b10d22 100644 --- a/doc/classes/GraphEdit.xml +++ b/doc/classes/GraphEdit.xml @@ -154,7 +154,7 @@ <method name="get_connection_list" qualifiers="const"> <return type="Dictionary[]" /> <description> - Returns an Array containing the list of connections. A connection consists in a structure of the form [code]{ from_port: 0, from: "GraphNode name 0", to_port: 1, to: "GraphNode name 1" }[/code]. + Returns an Array containing the list of connections. A connection consists in a structure of the form [code]{ from_port: 0, from_node: "GraphNode name 0", to_port: 1, to_node: "GraphNode name 1" }[/code]. </description> </method> <method name="get_menu_hbox"> diff --git a/doc/classes/Image.xml b/doc/classes/Image.xml index 310dae6c65..5677999d5d 100644 --- a/doc/classes/Image.xml +++ b/doc/classes/Image.xml @@ -10,6 +10,7 @@ </description> <tutorials> <link title="Importing images">$DOCS_URL/tutorials/assets_pipeline/importing_images.html</link> + <link title="Runtime file loading and saving">$DOCS_URL/tutorials/io/runtime_file_loading_and_saving.html</link> </tutorials> <methods> <method name="adjust_bcs"> @@ -201,8 +202,8 @@ <return type="int" enum="Error" /> <param index="0" name="renormalize" type="bool" default="false" /> <description> - Generates mipmaps for the image. Mipmaps are precalculated lower-resolution copies of the image that are automatically used if the image needs to be scaled down when rendered. They help improve image quality and performance when rendering. This method returns an error if the image is compressed, in a custom format, or if the image's width/height is [code]0[/code]. Enabling [param renormalize] when generating mipmaps for normal textures will make sure all resulting vector values are normalized. - It is possible to check if the image has mipmaps by calling [method has_mipmaps] or [method get_mipmap_count]. + Generates mipmaps for the image. Mipmaps are precalculated lower-resolution copies of the image that are automatically used if the image needs to be scaled down when rendered. They help improve image quality and performance when rendering. This method returns an error if the image is compressed, in a custom format, or if the image's width/height is [code]0[/code]. Enabling [param renormalize] when generating mipmaps for normal map textures will make sure all resulting vector values are normalized. + It is possible to check if the image has mipmaps by calling [method has_mipmaps] or [method get_mipmap_count]. Calling [method generate_mipmaps] on an image that already has mipmaps will replace existing mipmaps in the image. </description> </method> <method name="get_data" qualifiers="const"> @@ -317,6 +318,7 @@ <description> Loads an image from the binary contents of a BMP file. [b]Note:[/b] Godot's BMP module doesn't support 16-bit per pixel images. Only 1-bit, 4-bit, 8-bit, 24-bit, and 32-bit per pixel images are supported. + [b]Note:[/b] This method is only available in engine builds with the BMP module enabled. By default, the BMP module is enabled, but it can be disabled at build-time using the [code]module_bmp_enabled=no[/code] SCons option. </description> </method> <method name="load_from_file" qualifiers="static"> @@ -337,7 +339,9 @@ <return type="int" enum="Error" /> <param index="0" name="buffer" type="PackedByteArray" /> <description> - Loads an image from the binary contents of a KTX file. + Loads an image from the binary contents of a [url=https://github.com/KhronosGroup/KTX-Software]KTX[/url] file. Unlike most image formats, KTX can store VRAM-compressed data and embed mipmaps. + [b]Note:[/b] Godot's libktx implementation only supports 2D images. Cubemaps, texture arrays, and de-padding are not supported. + [b]Note:[/b] This method is only available in engine builds with the KTX module enabled. By default, the KTX module is enabled, but it can be disabled at build-time using the [code]module_ktx_enabled=no[/code] SCons option. </description> </method> <method name="load_png_from_buffer"> @@ -371,6 +375,7 @@ <param index="0" name="buffer" type="PackedByteArray" /> <description> Loads an image from the binary contents of a TGA file. + [b]Note:[/b] This method is only available in engine builds with the TGA module enabled. By default, the TGA module is enabled, but it can be disabled at build-time using the [code]module_tga_enabled=no[/code] SCons option. </description> </method> <method name="load_webp_from_buffer"> @@ -389,7 +394,7 @@ <method name="premultiply_alpha"> <return type="void" /> <description> - Multiplies color values with alpha values. Resulting color values for a pixel are [code](color * alpha)/256[/code]. + Multiplies color values with alpha values. Resulting color values for a pixel are [code](color * alpha)/256[/code]. See also [member CanvasItemMaterial.blend_mode]. </description> </method> <method name="resize"> @@ -481,7 +486,8 @@ <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). + 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. + [b]Note:[/b] The WebP format is limited to a size of 16383×16383 pixels, while PNG can save larger images. </description> </method> <method name="save_webp_to_buffer" qualifiers="const"> @@ -489,7 +495,8 @@ <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). + 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. + [b]Note:[/b] The WebP format is limited to a size of 16383×16383 pixels, while PNG can save larger images. </description> </method> <method name="set_data"> @@ -559,7 +566,7 @@ <method name="shrink_x2"> <return type="void" /> <description> - Shrinks the image by a factor of 2. + Shrinks the image by a factor of 2 on each axis (this divides the pixel count by 4). </description> </method> <method name="srgb_to_linear"> diff --git a/doc/classes/ImporterMesh.xml b/doc/classes/ImporterMesh.xml index 657d5659f8..9bc1bf035e 100644 --- a/doc/classes/ImporterMesh.xml +++ b/doc/classes/ImporterMesh.xml @@ -92,7 +92,7 @@ <return type="Array" /> <param index="0" name="surface_idx" type="int" /> <description> - Returns the arrays for the vertices, normals, uvs, etc. that make up the requested surface. See [method add_surface]. + Returns the arrays for the vertices, normals, UVs, etc. that make up the requested surface. See [method add_surface]. </description> </method> <method name="get_surface_blend_shape_arrays" qualifiers="const"> diff --git a/doc/classes/Input.xml b/doc/classes/Input.xml index e18413810b..fc162b0761 100644 --- a/doc/classes/Input.xml +++ b/doc/classes/Input.xml @@ -198,6 +198,7 @@ If [param exact_match] is [code]false[/code], it ignores additional input modifiers for [InputEventKey] and [InputEventMouseButton] events, and the direction for [InputEventJoypadMotion] events. [b]Note:[/b] Returning [code]true[/code] does not imply that the action is [i]still[/i] pressed. An action can be pressed and released again rapidly, and [code]true[/code] will still be returned so as not to miss input. [b]Note:[/b] Due to keyboard ghosting, [method is_action_just_pressed] may return [code]false[/code] even if one of the action's keys is pressed. See [url=$DOCS_URL/tutorials/inputs/input_examples.html#keyboard-events]Input examples[/url] in the documentation for more information. + [b]Note:[/b] During input handling (e.g. [method Node._input]), use [method InputEvent.is_action_pressed] instead to query the action state of the current event. </description> </method> <method name="is_action_just_released" qualifiers="const"> @@ -208,6 +209,7 @@ Returns [code]true[/code] when the user [i]stops[/i] pressing the action event in the current frame or physics tick. It will only return [code]true[/code] on the frame or tick that the user releases the button. [b]Note:[/b] Returning [code]true[/code] does not imply that the action is [i]still[/i] not pressed. An action can be released and pressed again rapidly, and [code]true[/code] will still be returned so as not to miss input. If [param exact_match] is [code]false[/code], it ignores additional input modifiers for [InputEventKey] and [InputEventMouseButton] events, and the direction for [InputEventJoypadMotion] events. + [b]Note:[/b] During input handling (e.g. [method Node._input]), use [method InputEvent.is_action_released] instead to query the action state of the current event. </description> </method> <method name="is_action_pressed" qualifiers="const"> @@ -406,6 +408,12 @@ </method> </methods> <members> + <member name="emulate_mouse_from_touch" type="bool" setter="set_emulate_mouse_from_touch" getter="is_emulating_mouse_from_touch"> + If [code]true[/code], sends mouse input events when tapping or swiping on the touchscreen. See also [member ProjectSettings.input_devices/pointing/emulate_mouse_from_touch]. + </member> + <member name="emulate_touch_from_mouse" type="bool" setter="set_emulate_touch_from_mouse" getter="is_emulating_touch_from_mouse"> + If [code]true[/code], sends touch input events when clicking or dragging the mouse. See also [member ProjectSettings.input_devices/pointing/emulate_touch_from_mouse]. + </member> <member name="mouse_mode" type="int" setter="set_mouse_mode" getter="get_mouse_mode" enum="Input.MouseMode"> Controls the mouse mode. See [enum MouseMode] for more information. </member> diff --git a/doc/classes/InputEventKey.xml b/doc/classes/InputEventKey.xml index 5c4dc8e65d..48a6804290 100644 --- a/doc/classes/InputEventKey.xml +++ b/doc/classes/InputEventKey.xml @@ -79,7 +79,25 @@ </member> <member name="physical_keycode" type="int" setter="set_physical_keycode" getter="get_physical_keycode" enum="Key" default="0"> Represents the physical location of a key on the 101/102-key US QWERTY keyboard, which corresponds to one of the [enum Key] constants. - To get a human-readable representation of the [InputEventKey], use [code]OS.get_keycode_string(event.keycode)[/code] where [code]event[/code] is the [InputEventKey]. + To get a human-readable representation of the [InputEventKey], use [method OS.get_keycode_string] in combination with [method DisplayServer.keyboard_get_keycode_from_physical]: + [codeblocks] + [gdscript] + func _input(event): + if event is InputEventKey: + var keycode = DisplayServer.keyboard_get_keycode_from_physical(event.physical_keycode) + print(OS.get_keycode_string(keycode)) + [/gdscript] + [csharp] + public override void _Input(InputEvent @event) + { + if (@event is InputEventKey inputEventKey) + { + var keycode = DisplayServer.KeyboardGetKeycodeFromPhysical(inputEventKey.PhysicalKeycode); + GD.Print(OS.GetKeycodeString(keycode)); + } + } + [/csharp] + [/codeblocks] </member> <member name="pressed" type="bool" setter="set_pressed" getter="is_pressed" default="false"> If [code]true[/code], the key's state is pressed. If [code]false[/code], the key's state is released. diff --git a/doc/classes/InputEventMagnifyGesture.xml b/doc/classes/InputEventMagnifyGesture.xml index bf92155139..627344a136 100644 --- a/doc/classes/InputEventMagnifyGesture.xml +++ b/doc/classes/InputEventMagnifyGesture.xml @@ -5,6 +5,7 @@ </brief_description> <description> Stores the factor of a magnifying touch gesture. This is usually performed when the user pinches the touch screen and used for zooming in/out. + [b]Note:[/b] On Android, this requires the [member ProjectSettings.input_devices/pointing/android/enable_pan_and_scale_gestures] project setting to be enabled. </description> <tutorials> <link title="Using InputEvent">$DOCS_URL/tutorials/inputs/inputevent.html</link> diff --git a/doc/classes/InputEventPanGesture.xml b/doc/classes/InputEventPanGesture.xml index 9966550c1a..512b2cce51 100644 --- a/doc/classes/InputEventPanGesture.xml +++ b/doc/classes/InputEventPanGesture.xml @@ -5,6 +5,7 @@ </brief_description> <description> Stores information about pan gestures. A pan gesture is performed when the user swipes the touch screen with two fingers. It's typically used for panning/scrolling. + [b]Note:[/b] On Android, this requires the [member ProjectSettings.input_devices/pointing/android/enable_pan_and_scale_gestures] project setting to be enabled. </description> <tutorials> <link title="Using InputEvent">$DOCS_URL/tutorials/inputs/inputevent.html</link> diff --git a/doc/classes/Label.xml b/doc/classes/Label.xml index f13f1bdcf4..fda45a42c8 100644 --- a/doc/classes/Label.xml +++ b/doc/classes/Label.xml @@ -45,6 +45,9 @@ <member name="clip_text" type="bool" setter="set_clip_text" getter="is_clipping_text" default="false"> If [code]true[/code], the Label only shows the text that fits inside its bounding rectangle and will clip text horizontally. </member> + <member name="ellipsis_char" type="String" setter="set_ellipsis_char" getter="get_ellipsis_char" default=""…""> + Ellipsis character used for text clipping. + </member> <member name="horizontal_alignment" type="int" setter="set_horizontal_alignment" getter="get_horizontal_alignment" enum="HorizontalAlignment" default="0"> Controls the text's horizontal alignment. Supports left, center, right, and fill, or justify. Set it to one of the [enum HorizontalAlignment] constants. </member> diff --git a/doc/classes/LightmapGIData.xml b/doc/classes/LightmapGIData.xml index 09c4383829..db6c9e70ca 100644 --- a/doc/classes/LightmapGIData.xml +++ b/doc/classes/LightmapGIData.xml @@ -54,8 +54,12 @@ </method> </methods> <members> - <member name="light_texture" type="TextureLayered" setter="set_light_texture" getter="get_light_texture"> + <member name="light_texture" type="TextureLayered" setter="set_light_texture" getter="get_light_texture" is_deprecated="true"> The lightmap atlas texture generated by the lightmapper. + [i]Deprecated.[/i] The lightmap atlas can now have multiple textures. See [member lightmap_textures]. + </member> + <member name="lightmap_textures" type="TextureLayered[]" setter="set_lightmap_textures" getter="get_lightmap_textures" default="[]"> + The lightmap atlas textures generated by the lightmapper. </member> </members> </class> diff --git a/doc/classes/Material.xml b/doc/classes/Material.xml index 1118461445..87fa3fd676 100644 --- a/doc/classes/Material.xml +++ b/doc/classes/Material.xml @@ -1,10 +1,11 @@ <?xml version="1.0" encoding="UTF-8" ?> <class name="Material" inherits="Resource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> - Abstract base class for applying visual properties to an object, such as color and roughness. + Virtual base class for applying visual properties to an object, such as color and roughness. </brief_description> <description> [Material] is a base resource used for coloring and shading geometry. All materials inherit from it and almost all [VisualInstance3D] derived nodes carry a [Material]. A few flags and parameters are shared between all material types and are configured here. + Importantly, you can inherit from [Material] to create your own custom material type in script or in GDExtension. </description> <tutorials> <link title="3D Material Testers Demo">https://godotengine.org/asset-library/asset/123</link> @@ -14,21 +15,25 @@ <method name="_can_do_next_pass" qualifiers="virtual const"> <return type="bool" /> <description> + Only exposed for the purpose of overriding. You cannot call this function directly. Used internally to determine if [member next_pass] should be shown in the editor or not. </description> </method> <method name="_can_use_render_priority" qualifiers="virtual const"> <return type="bool" /> <description> + Only exposed for the purpose of overriding. You cannot call this function directly. Used internally to determine if [member render_priority] should be shown in the editor or not. </description> </method> <method name="_get_shader_mode" qualifiers="virtual const"> <return type="int" enum="Shader.Mode" /> <description> + Only exposed for the purpose of overriding. You cannot call this function directly. Used internally by various editor tools. </description> </method> <method name="_get_shader_rid" qualifiers="virtual const"> <return type="RID" /> <description> + Only exposed for the purpose of overriding. You cannot call this function directly. Used internally by various editor tools. Used to access the RID of the [Material]'s [Shader]. </description> </method> <method name="create_placeholder" qualifiers="const"> @@ -40,18 +45,20 @@ <method name="inspect_native_shader_code"> <return type="void" /> <description> + Only available when running in the editor. Opens a popup that visualizes the generated shader code, including all variants and internal shader code. </description> </method> </methods> <members> <member name="next_pass" type="Material" setter="set_next_pass" getter="get_next_pass"> Sets the [Material] to be used for the next pass. This renders the object again using a different material. + [b]Note:[/b] [member next_pass] materials are not necessarily drawn immediately after the source [Material]. Draw order is determined by material properties, [member render_priority], and distance to camera. [b]Note:[/b] This only applies to [StandardMaterial3D]s and [ShaderMaterial]s with type "Spatial". </member> <member name="render_priority" type="int" setter="set_render_priority" getter="get_render_priority"> - Sets the render priority for transparent objects in 3D scenes. Higher priority objects will be sorted in front of lower priority objects. + Sets the render priority for objects in 3D scenes. Higher priority objects will be sorted in front of lower priority objects. In other words, all objects with [member render_priority] [code]1[/code] will render before all objects with [member render_priority] [code]0[/code]). [b]Note:[/b] This only applies to [StandardMaterial3D]s and [ShaderMaterial]s with type "Spatial". - [b]Note:[/b] This only applies to sorting of transparent objects. This will not impact how transparent objects are sorted relative to opaque objects. This is because opaque objects are not sorted, while transparent objects are sorted from back to front (subject to priority). + [b]Note:[/b] This will not impact how transparent objects are sorted relative to opaque objects or how dynamic meshes will be sorted relative to other opaque meshes. This is because all transparent objects are drawn after all opaque objects and all dynamic opaque meshes are drawn before other opaque meshes. </member> </members> <constants> diff --git a/doc/classes/Mesh.xml b/doc/classes/Mesh.xml index 6f06628122..2b2dc63a33 100644 --- a/doc/classes/Mesh.xml +++ b/doc/classes/Mesh.xml @@ -366,6 +366,9 @@ <constant name="ARRAY_FLAG_USES_EMPTY_VERTEX_ARRAY" value="268435456" enum="ArrayFormat" is_bitfield="true"> Flag used to mark that the mesh intentionally contains no vertex array. </constant> + <constant name="ARRAY_FLAG_COMPRESS_ATTRIBUTES" value="536870912" enum="ArrayFormat" is_bitfield="true"> + Flag used to mark that a mesh is using compressed attributes (vertices, normals, tangents, UVs). When this form of compression is enabled, vertex positions will be packed into an RGBA16UNORM attribute and scaled in the vertex shader. The normal and tangent will be packed into an RG16UNORM representing an axis, and a 16-bit float stored in the A-channel of the vertex. UVs will use 16-bit normalized floats instead of full 32-bit signed floats. When using this compression mode you must use either vertices, normals, and tangents or only vertices. You cannot use normals without tangents. Importers will automatically enable this compression if they can. + </constant> <constant name="BLEND_SHAPE_MODE_NORMALIZED" value="0" enum="BlendShapeMode"> Blend shapes are normalized. </constant> diff --git a/doc/classes/MultiplayerAPIExtension.xml b/doc/classes/MultiplayerAPIExtension.xml index 4a2d397260..7f6e7951b2 100644 --- a/doc/classes/MultiplayerAPIExtension.xml +++ b/doc/classes/MultiplayerAPIExtension.xml @@ -15,7 +15,7 @@ var base_multiplayer = SceneMultiplayer.new() func _init(): - # Just passthourgh base signals (copied to var to avoid cyclic reference) + # Just passthrough base signals (copied to var to avoid cyclic reference) var cts = connected_to_server var cf = connection_failed var pc = peer_connected @@ -25,13 +25,16 @@ base_multiplayer.peer_connected.connect(func(id): pc.emit(id)) base_multiplayer.peer_disconnected.connect(func(id): pd.emit(id)) + func _poll(): + return base_multiplayer.poll() + # Log RPC being made and forward it to the default multiplayer. - func _rpc(peer: int, object: Object, method: StringName, args: Array) -> int: # Error + func _rpc(peer: int, object: Object, method: StringName, args: Array) -> Error: print("Got RPC for %d: %s::%s(%s)" % [peer, object, method, args]) return base_multiplayer.rpc(peer, object, method, args) # Log configuration add. E.g. root path (nullptr, NodePath), replication (Node, Spawner|Synchronizer), custom. - func _object_configuration_add(object, config: Variant) -> int: # Error + func _object_configuration_add(object, config: Variant) -> Error: if config is MultiplayerSynchronizer: print("Adding synchronization configuration for %s. Synchronizer: %s" % [object, config]) elif config is MultiplayerSpawner: @@ -39,7 +42,7 @@ return base_multiplayer.object_configuration_add(object, config) # Log configuration remove. E.g. root path (nullptr, NodePath), replication (Node, Spawner|Synchronizer), custom. - func _object_configuration_remove(object, config: Variant) -> int: # Error + func _object_configuration_remove(object, config: Variant) -> Error: if config is MultiplayerSynchronizer: print("Removing synchronization configuration for %s. Synchronizer: %s" % [object, config]) elif config is MultiplayerSpawner: diff --git a/doc/classes/MultiplayerPeer.xml b/doc/classes/MultiplayerPeer.xml index 350fffed32..39980a05e1 100644 --- a/doc/classes/MultiplayerPeer.xml +++ b/doc/classes/MultiplayerPeer.xml @@ -48,7 +48,7 @@ <method name="get_packet_mode" qualifiers="const"> <return type="int" enum="MultiplayerPeer.TransferMode" /> <description> - Returns the [enum MultiplayerPeer.TransferMode] the remote peer used to send the next available packet. See [method PacketPeer.get_available_packet_count]. + Returns the transfer mode the remote peer used to send the next available packet. See [method PacketPeer.get_available_packet_count]. </description> </method> <method name="get_packet_peer" qualifiers="const"> diff --git a/doc/classes/MultiplayerPeerExtension.xml b/doc/classes/MultiplayerPeerExtension.xml index 9b2b5dbc94..8fd6755a7b 100644 --- a/doc/classes/MultiplayerPeerExtension.xml +++ b/doc/classes/MultiplayerPeerExtension.xml @@ -58,7 +58,7 @@ <method name="_get_packet_mode" qualifiers="virtual const"> <return type="int" enum="MultiplayerPeer.TransferMode" /> <description> - Called to get the [enum MultiplayerPeer.TransferMode] the remote peer used to send the next available packet. See [method MultiplayerPeer.get_packet_mode]. + Called to get the transfer mode the remote peer used to send the next available packet. See [method MultiplayerPeer.get_packet_mode]. </description> </method> <method name="_get_packet_peer" qualifiers="virtual const"> diff --git a/doc/classes/NavigationAgent2D.xml b/doc/classes/NavigationAgent2D.xml index 4df8d4143b..fc7faf9260 100644 --- a/doc/classes/NavigationAgent2D.xml +++ b/doc/classes/NavigationAgent2D.xml @@ -84,8 +84,8 @@ <method name="is_navigation_finished"> <return type="bool" /> <description> - Returns [code]true[/code] if the end of the currently loaded navigation path has been reached. - [b]Note:[/b] While true prefer to stop calling update functions like [method get_next_path_position]. This avoids jittering the standing agent due to calling repeated path updates. + Returns [code]true[/code] if the agent's navigation has finished. If the target is reachable, navigation ends when the target is reached. If the target is unreachable, navigation ends when the last waypoint of the path is reached. + [b]Note:[/b] While [code]true[/code] prefer to stop calling update functions like [method get_next_path_position]. This avoids jittering the standing agent due to calling repeated path updates. </description> </method> <method name="is_target_reachable"> @@ -97,7 +97,7 @@ <method name="is_target_reached" qualifiers="const"> <return type="bool" /> <description> - Returns true if [member target_position] is reached. It may not always be possible to reach the target position. It should always be possible to reach the final position though. See [method get_final_position]. + Returns [code]true[/code] if the agent reached the target, i.e. the agent moved within [member target_desired_distance] of the [member target_position]. It may not always be possible to reach the target but it should always be possible to reach the final position. See [method get_final_position]. </description> </method> <method name="set_avoidance_layer_value"> @@ -180,7 +180,7 @@ The distance to search for other agents. </member> <member name="path_desired_distance" type="float" setter="set_path_desired_distance" getter="get_path_desired_distance" default="20.0"> - The distance threshold before a path point is considered to be reached. This allows agents to not have to hit a path point on the path exactly, but only to reach its general area. If this value is set too high, the NavigationAgent will skip points on the path, which can lead to leaving the navigation mesh. If this value is set too low, the NavigationAgent will be stuck in a repath loop because it will constantly overshoot or undershoot the distance to the next point on each physics frame update. + The distance threshold before a path point is considered to be reached. This allows agents to not have to hit a path point on the path exactly, but only to reach its general area. If this value is set too high, the NavigationAgent will skip points on the path, which can lead to it leaving the navigation mesh. If this value is set too low, the NavigationAgent will be stuck in a repath loop because it will constantly overshoot the distance to the next point on each physics frame update. </member> <member name="path_max_distance" type="float" setter="set_path_max_distance" getter="get_path_max_distance" default="100.0"> The maximum distance the agent is allowed away from the ideal path to the final position. This can happen due to trying to avoid collisions. When the maximum distance is exceeded, it recalculates the ideal path. @@ -199,7 +199,9 @@ Does not affect normal pathfinding. To change an actor's pathfinding radius bake [NavigationMesh] resources with a different [member NavigationMesh.agent_radius] property and use different navigation maps for each actor size. </member> <member name="target_desired_distance" type="float" setter="set_target_desired_distance" getter="get_target_desired_distance" default="10.0"> - The distance threshold before the final target point is considered to be reached. This allows agents to not have to hit the point of the final target exactly, but only to reach its general area. If this value is set too low, the NavigationAgent will be stuck in a repath loop because it will constantly overshoot or undershoot the distance to the final target point on each physics frame update. + The distance threshold before the target is considered to be reached. On reaching the target, [signal target_reached] is emitted and navigation ends (see [method is_navigation_finished] and [signal navigation_finished]). + You can make navigation end early by setting this property to a value greater than [member path_desired_distance] (navigation will end before reaching the last waypoint). + You can also make navigation end closer to the target than each individual path position by setting this property to a value lower than [member path_desired_distance] (navigation won't immediately end when reaching the last waypoint). However, if the value set is too low, the agent will be stuck in a repath loop because it will constantly overshoot the distance to the target on each physics frame update. </member> <member name="target_position" type="Vector2" setter="set_target_position" getter="get_target_position" default="Vector2(0, 0)"> If set, a new navigation path from the current agent position to the [member target_position] is requested from the NavigationServer. @@ -218,7 +220,7 @@ <signal name="link_reached"> <param index="0" name="details" type="Dictionary" /> <description> - Notifies when a navigation link has been reached. + Signals that the agent reached a navigation link. Emitted when the agent moves within [member path_desired_distance] of the next position of the path when that position is a navigation link. The details dictionary may contain the following keys depending on the value of [member path_metadata_flags]: - [code]position[/code]: The start position of the link that was reached. - [code]type[/code]: Always [constant NavigationPathQueryResult2D.PATH_SEGMENT_TYPE_LINK]. @@ -230,7 +232,8 @@ </signal> <signal name="navigation_finished"> <description> - Emitted once per loaded path when the agent internal navigation path index reaches the last index of the loaded path array. The agent internal navigation path index can be received with [method get_current_navigation_path_index]. + Signals that the agent's navigation has finished. If the target is reachable, navigation ends when the target is reached. If the target is unreachable, navigation ends when the last waypoint of the path is reached. This signal is emitted only once per loaded path. + This signal will be emitted just after [signal target_reached] when the target is reachable. </description> </signal> <signal name="path_changed"> @@ -243,7 +246,9 @@ </signal> <signal name="target_reached"> <description> - Emitted once per loaded path when the agent's global position is the first time within [member target_desired_distance] to the [member target_position]. + Signals that the agent reached the target, i.e. the agent moved within [member target_desired_distance] of the [member target_position]. This signal is emitted only once per loaded path. + This signal will be emitted just before [signal navigation_finished] when the target is reachable. + It may not always be possible to reach the target but it should always be possible to reach the final position. See [method get_final_position]. </description> </signal> <signal name="velocity_computed"> @@ -255,7 +260,7 @@ <signal name="waypoint_reached"> <param index="0" name="details" type="Dictionary" /> <description> - Notifies when a waypoint along the path has been reached. + Signals that the agent reached a waypoint. Emitted when the agent moves within [member path_desired_distance] of the next position of the path. The details dictionary may contain the following keys depending on the value of [member path_metadata_flags]: - [code]position[/code]: The position of the waypoint that was reached. - [code]type[/code]: The type of navigation primitive (region or link) that contains this waypoint. diff --git a/doc/classes/NavigationAgent3D.xml b/doc/classes/NavigationAgent3D.xml index ec9f679307..cbcf50bb29 100644 --- a/doc/classes/NavigationAgent3D.xml +++ b/doc/classes/NavigationAgent3D.xml @@ -84,8 +84,8 @@ <method name="is_navigation_finished"> <return type="bool" /> <description> - Returns [code]true[/code] if the end of the currently loaded navigation path has been reached. - [b]Note:[/b] While true prefer to stop calling update functions like [method get_next_path_position]. This avoids jittering the standing agent due to calling repeated path updates. + Returns [code]true[/code] if the agent's navigation has finished. If the target is reachable, navigation ends when the target is reached. If the target is unreachable, navigation ends when the last waypoint of the path is reached. + [b]Note:[/b] While [code]true[/code] prefer to stop calling update functions like [method get_next_path_position]. This avoids jittering the standing agent due to calling repeated path updates. </description> </method> <method name="is_target_reachable"> @@ -97,7 +97,7 @@ <method name="is_target_reached" qualifiers="const"> <return type="bool" /> <description> - Returns true if [member target_position] is reached. It may not always be possible to reach the target position. It should always be possible to reach the final position though. See [method get_final_position]. + Returns [code]true[/code] if the agent reached the target, i.e. the agent moved within [member target_desired_distance] of the [member target_position]. It may not always be possible to reach the target but it should always be possible to reach the final position. See [method get_final_position]. </description> </method> <method name="set_avoidance_layer_value"> @@ -183,7 +183,7 @@ The distance to search for other agents. </member> <member name="path_desired_distance" type="float" setter="set_path_desired_distance" getter="get_path_desired_distance" default="1.0"> - The distance threshold before a path point is considered to be reached. This allows agents to not have to hit a path point on the path exactly, but only to reach its general area. If this value is set too high, the NavigationAgent will skip points on the path, which can lead to leaving the navigation mesh. If this value is set too low, the NavigationAgent will be stuck in a repath loop because it will constantly overshoot or undershoot the distance to the next point on each physics frame update. + The distance threshold before a path point is considered to be reached. This allows agents to not have to hit a path point on the path exactly, but only to reach its general area. If this value is set too high, the NavigationAgent will skip points on the path, which can lead to it leaving the navigation mesh. If this value is set too low, the NavigationAgent will be stuck in a repath loop because it will constantly overshoot the distance to the next point on each physics frame update. </member> <member name="path_height_offset" type="float" setter="set_path_height_offset" getter="get_path_height_offset" default="0.0"> The height offset is subtracted from the y-axis value of any vector path position for this NavigationAgent. The NavigationAgent height offset does not change or influence the navigation mesh or pathfinding query result. Additional navigation maps that use regions with navigation meshes that the developer baked with appropriate agent radius or height values are required to support different-sized agents. @@ -205,7 +205,9 @@ Does not affect normal pathfinding. To change an actor's pathfinding radius bake [NavigationMesh] resources with a different [member NavigationMesh.agent_radius] property and use different navigation maps for each actor size. </member> <member name="target_desired_distance" type="float" setter="set_target_desired_distance" getter="get_target_desired_distance" default="1.0"> - The distance threshold before the final target point is considered to be reached. This allows agents to not have to hit the point of the final target exactly, but only to reach its general area. If this value is set too low, the NavigationAgent will be stuck in a repath loop because it will constantly overshoot or undershoot the distance to the final target point on each physics frame update. + The distance threshold before the target is considered to be reached. On reaching the target, [signal target_reached] is emitted and navigation ends (see [method is_navigation_finished] and [signal navigation_finished]). + You can make navigation end early by setting this property to a value greater than [member path_desired_distance] (navigation will end before reaching the last waypoint). + You can also make navigation end closer to the target than each individual path position by setting this property to a value lower than [member path_desired_distance] (navigation won't immediately end when reaching the last waypoint). However, if the value set is too low, the agent will be stuck in a repath loop because it will constantly overshoot the distance to the target on each physics frame update. </member> <member name="target_position" type="Vector3" setter="set_target_position" getter="get_target_position" default="Vector3(0, 0, 0)"> If set, a new navigation path from the current agent position to the [member target_position] is requested from the NavigationServer. @@ -228,7 +230,7 @@ <signal name="link_reached"> <param index="0" name="details" type="Dictionary" /> <description> - Notifies when a navigation link has been reached. + Signals that the agent reached a navigation link. Emitted when the agent moves within [member path_desired_distance] of the next position of the path when that position is a navigation link. The details dictionary may contain the following keys depending on the value of [member path_metadata_flags]: - [code]position[/code]: The start position of the link that was reached. - [code]type[/code]: Always [constant NavigationPathQueryResult3D.PATH_SEGMENT_TYPE_LINK]. @@ -240,7 +242,8 @@ </signal> <signal name="navigation_finished"> <description> - Emitted once per loaded path when the agent internal navigation path index reaches the last index of the loaded path array. The agent internal navigation path index can be received with [method get_current_navigation_path_index]. + Signals that the agent's navigation has finished. If the target is reachable, navigation ends when the target is reached. If the target is unreachable, navigation ends when the last waypoint of the path is reached. This signal is emitted only once per loaded path. + This signal will be emitted just after [signal target_reached] when the target is reachable. </description> </signal> <signal name="path_changed"> @@ -253,7 +256,9 @@ </signal> <signal name="target_reached"> <description> - Emitted once per loaded path when the agent's global position is the first time within [member target_desired_distance] to the [member target_position]. + Signals that the agent reached the target, i.e. the agent moved within [member target_desired_distance] of the [member target_position]. This signal is emitted only once per loaded path. + This signal will be emitted just before [signal navigation_finished] when the target is reachable. + It may not always be possible to reach the target but it should always be possible to reach the final position. See [method get_final_position]. </description> </signal> <signal name="velocity_computed"> @@ -265,7 +270,7 @@ <signal name="waypoint_reached"> <param index="0" name="details" type="Dictionary" /> <description> - Notifies when a waypoint along the path has been reached. + Signals that the agent reached a waypoint. Emitted when the agent moves within [member path_desired_distance] of the next position of the path. The details dictionary may contain the following keys depending on the value of [member path_metadata_flags]: - [code]position[/code]: The position of the waypoint that was reached. - [code]type[/code]: The type of navigation primitive (region or link) that contains this waypoint. diff --git a/doc/classes/NavigationLink2D.xml b/doc/classes/NavigationLink2D.xml index b12051b4f4..75b691aaf4 100644 --- a/doc/classes/NavigationLink2D.xml +++ b/doc/classes/NavigationLink2D.xml @@ -29,6 +29,12 @@ Returns whether or not the specified layer of the [member navigation_layers] bitmask is enabled, given a [param layer_number] between 1 and 32. </description> </method> + <method name="get_rid" qualifiers="const"> + <return type="RID" /> + <description> + Returns the [RID] of this link on the [NavigationServer2D]. + </description> + </method> <method name="set_global_end_position"> <return type="void" /> <param index="0" name="position" type="Vector2" /> diff --git a/doc/classes/NavigationLink3D.xml b/doc/classes/NavigationLink3D.xml index 90eaaaee6d..711c637dc5 100644 --- a/doc/classes/NavigationLink3D.xml +++ b/doc/classes/NavigationLink3D.xml @@ -29,6 +29,12 @@ Returns whether or not the specified layer of the [member navigation_layers] bitmask is enabled, given a [param layer_number] between 1 and 32. </description> </method> + <method name="get_rid" qualifiers="const"> + <return type="RID" /> + <description> + Returns the [RID] of this link on the [NavigationServer3D]. + </description> + </method> <method name="set_global_end_position"> <return type="void" /> <param index="0" name="position" type="Vector3" /> diff --git a/doc/classes/NavigationRegion2D.xml b/doc/classes/NavigationRegion2D.xml index ef660305f4..089359da7a 100644 --- a/doc/classes/NavigationRegion2D.xml +++ b/doc/classes/NavigationRegion2D.xml @@ -43,7 +43,14 @@ Returns the current navigation map [RID] used by this region. </description> </method> - <method name="get_region_rid" qualifiers="const"> + <method name="get_region_rid" qualifiers="const" is_deprecated="true"> + <return type="RID" /> + <description> + Returns the [RID] of this region on the [NavigationServer2D]. + [i]Deprecated.[/i] Use [method get_rid] instead. + </description> + </method> + <method name="get_rid" qualifiers="const"> <return type="RID" /> <description> Returns the [RID] of this region on the [NavigationServer2D]. Combined with [method NavigationServer2D.map_get_closest_point_owner] can be used to identify the [NavigationRegion2D] closest to a point on the merged navigation map. diff --git a/doc/classes/NavigationRegion3D.xml b/doc/classes/NavigationRegion3D.xml index 3257160485..4415c10210 100644 --- a/doc/classes/NavigationRegion3D.xml +++ b/doc/classes/NavigationRegion3D.xml @@ -36,7 +36,14 @@ Returns the current navigation map [RID] used by this region. </description> </method> - <method name="get_region_rid" qualifiers="const"> + <method name="get_region_rid" qualifiers="const" is_deprecated="true"> + <return type="RID" /> + <description> + Returns the [RID] of this region on the [NavigationServer3D]. + [i]Deprecated.[/i] Use [method get_rid] instead. + </description> + </method> + <method name="get_rid" qualifiers="const"> <return type="RID" /> <description> Returns the [RID] of this region on the [NavigationServer3D]. Combined with [method NavigationServer3D.map_get_closest_point_owner] can be used to identify the [NavigationRegion3D] closest to a point on the merged navigation map. diff --git a/doc/classes/NavigationServer2D.xml b/doc/classes/NavigationServer2D.xml index a25f048df3..e1c79ad8a8 100644 --- a/doc/classes/NavigationServer2D.xml +++ b/doc/classes/NavigationServer2D.xml @@ -445,6 +445,17 @@ Returns the navigation path to reach the destination from the origin. [param navigation_layers] is a bitmask of all region navigation layers that are allowed to be in the path. </description> </method> + <method name="map_get_random_point" qualifiers="const"> + <return type="Vector2" /> + <param index="0" name="map" type="RID" /> + <param index="1" name="navigation_layers" type="int" /> + <param index="2" name="uniformly" type="bool" /> + <description> + Returns a random position picked from all map region polygons with matching [param navigation_layers]. + If [param uniformly] is [code]true[/code], all map regions, polygons, and faces are weighted by their surface area (slower). + If [param uniformly] is [code]false[/code], just a random region and a random polygon are picked (faster). + </description> + </method> <method name="map_get_regions" qualifiers="const"> <return type="RID[]" /> <param index="0" name="map" type="RID" /> @@ -681,6 +692,17 @@ Returns the [code]ObjectID[/code] of the object which manages this region. </description> </method> + <method name="region_get_random_point" qualifiers="const"> + <return type="Vector2" /> + <param index="0" name="region" type="RID" /> + <param index="1" name="navigation_layers" type="int" /> + <param index="2" name="uniformly" type="bool" /> + <description> + Returns a random position picked from all region polygons with matching [param navigation_layers]. + If [param uniformly] is [code]true[/code], all region polygons and faces are weighted by their surface area (slower). + If [param uniformly] is [code]false[/code], just a random polygon and face is picked (faster). + </description> + </method> <method name="region_get_travel_cost" qualifiers="const"> <return type="float" /> <param index="0" name="region" type="RID" /> diff --git a/doc/classes/NavigationServer3D.xml b/doc/classes/NavigationServer3D.xml index b56b86f435..46b6697947 100644 --- a/doc/classes/NavigationServer3D.xml +++ b/doc/classes/NavigationServer3D.xml @@ -502,6 +502,17 @@ Returns the navigation path to reach the destination from the origin. [param navigation_layers] is a bitmask of all region navigation layers that are allowed to be in the path. </description> </method> + <method name="map_get_random_point" qualifiers="const"> + <return type="Vector3" /> + <param index="0" name="map" type="RID" /> + <param index="1" name="navigation_layers" type="int" /> + <param index="2" name="uniformly" type="bool" /> + <description> + Returns a random position picked from all map region polygons with matching [param navigation_layers]. + If [param uniformly] is [code]true[/code], all map regions, polygons, and faces are weighted by their surface area (slower). + If [param uniformly] is [code]false[/code], just a random region and a random polygon are picked (faster). + </description> + </method> <method name="map_get_regions" qualifiers="const"> <return type="RID[]" /> <param index="0" name="map" type="RID" /> @@ -793,6 +804,17 @@ Returns the [code]ObjectID[/code] of the object which manages this region. </description> </method> + <method name="region_get_random_point" qualifiers="const"> + <return type="Vector3" /> + <param index="0" name="region" type="RID" /> + <param index="1" name="navigation_layers" type="int" /> + <param index="2" name="uniformly" type="bool" /> + <description> + Returns a random position picked from all region polygons with matching [param navigation_layers]. + If [param uniformly] is [code]true[/code], all region polygons and faces are weighted by their surface area (slower). + If [param uniformly] is [code]false[/code], just a random polygon and face is picked (faster). + </description> + </method> <method name="region_get_travel_cost" qualifiers="const"> <return type="float" /> <param index="0" name="region" type="RID" /> diff --git a/doc/classes/Node.xml b/doc/classes/Node.xml index 98b71e32df..0ace4357fa 100644 --- a/doc/classes/Node.xml +++ b/doc/classes/Node.xml @@ -444,7 +444,7 @@ <method name="get_tree" qualifiers="const"> <return type="SceneTree" /> <description> - Returns the [SceneTree] that contains this node. + Returns the [SceneTree] that contains this node. Returns [code]null[/code] and prints an error if this node is not inside the scene tree. See also [method is_inside_tree]. </description> </method> <method name="get_tree_string"> @@ -1034,7 +1034,7 @@ Notification received every frame when the internal physics process flag is set (see [method set_physics_process_internal]). </constant> <constant name="NOTIFICATION_POST_ENTER_TREE" value="27"> - Notification received when the node is ready, just before [constant NOTIFICATION_READY] is received. Unlike the latter, it's sent every time the node enters tree, instead of only once. + Notification received when the node is ready, just before [constant NOTIFICATION_READY] is received. Unlike the latter, it's sent every time the node enters the tree, instead of only once. </constant> <constant name="NOTIFICATION_DISABLED" value="28"> Notification received when the node is disabled. See [constant PROCESS_MODE_DISABLED]. @@ -1042,9 +1042,6 @@ <constant name="NOTIFICATION_ENABLED" value="29"> Notification received when the node is enabled again after being disabled. See [constant PROCESS_MODE_DISABLED]. </constant> - <constant name="NOTIFICATION_NODE_RECACHE_REQUESTED" value="30"> - Notification received when other nodes in the tree may have been removed/replaced and node pointers may require re-caching. - </constant> <constant name="NOTIFICATION_EDITOR_PRE_SAVE" value="9001"> Notification received right before the scene with the node is saved in the editor. This notification is only sent in the Godot editor and will not occur in exported projects. </constant> diff --git a/doc/classes/OS.xml b/doc/classes/OS.xml index 46c87d63b3..44197dbd0c 100644 --- a/doc/classes/OS.xml +++ b/doc/classes/OS.xml @@ -500,6 +500,7 @@ Returns [code]true[/code] if the feature for the given feature tag is supported in the currently running instance, depending on the platform, build, etc. Can be used to check whether you're currently running a debug build, on a certain platform or arch, etc. Refer to the [url=$DOCS_URL/tutorials/export/feature_tags.html]Feature Tags[/url] documentation for more details. [b]Note:[/b] Tag names are case-sensitive. [b]Note:[/b] On the web platform, one of the following additional tags is defined to indicate host platform: [code]web_android[/code], [code]web_ios[/code], [code]web_linuxbsd[/code], [code]web_macos[/code], or [code]web_windows[/code]. + [b]Note:[/b] On the iOS simulator, the additional [code]simulator[/code] tag is defined. </description> </method> <method name="is_debug_build" qualifiers="const"> @@ -698,6 +699,9 @@ <constant name="RENDERING_DRIVER_OPENGL3" value="1" enum="RenderingDriver"> The OpenGL 3 rendering driver. It uses OpenGL 3.3 Core Profile on desktop platforms, OpenGL ES 3.0 on mobile devices, and WebGL 2.0 on Web. </constant> + <constant name="RENDERING_DRIVER_D3D12" value="2" enum="RenderingDriver"> + The Direct3D 12 rendering driver. + </constant> <constant name="SYSTEM_DIR_DESKTOP" value="0" enum="SystemDir"> Desktop directory path. </constant> diff --git a/doc/classes/PanoramaSkyMaterial.xml b/doc/classes/PanoramaSkyMaterial.xml index 0d041b9b90..9e579cc7e5 100644 --- a/doc/classes/PanoramaSkyMaterial.xml +++ b/doc/classes/PanoramaSkyMaterial.xml @@ -11,6 +11,9 @@ <tutorials> </tutorials> <members> + <member name="energy_multiplier" type="float" setter="set_energy_multiplier" getter="get_energy_multiplier" default="1.0"> + The sky's overall brightness multiplier. Higher values result in a brighter sky. + </member> <member name="filter" type="bool" setter="set_filtering_enabled" getter="is_filtering_enabled" default="true"> A boolean value to determine if the background texture should be filtered or not. </member> diff --git a/doc/classes/ParticleProcessMaterial.xml b/doc/classes/ParticleProcessMaterial.xml index b7f55184f0..aa20260849 100644 --- a/doc/classes/ParticleProcessMaterial.xml +++ b/doc/classes/ParticleProcessMaterial.xml @@ -114,7 +114,7 @@ Minimum equivalent of [member anim_speed_max]. </member> <member name="attractor_interaction_enabled" type="bool" setter="set_attractor_interaction_enabled" getter="is_attractor_interaction_enabled" default="true"> - True if the interaction with particle attractors is enabled. + If [code]true[/code], interaction with particle attractors is enabled. In 3D, attraction only occurs within the area defined by the [GPUParticles3D] node's [member GPUParticles3D.visibility_aabb]. </member> <member name="collision_bounce" type="float" setter="set_collision_bounce" getter="get_collision_bounce"> The particles' bounciness. Values range from [code]0[/code] (no bounce) to [code]1[/code] (full bounciness). Only effective if [member collision_mode] is [constant COLLISION_RIGID]. @@ -124,11 +124,11 @@ </member> <member name="collision_mode" type="int" setter="set_collision_mode" getter="get_collision_mode" enum="ParticleProcessMaterial.CollisionMode" default="0"> The particles' collision mode. - [b]Note:[/b] 3D Particles can only collide with [GPUParticlesCollision3D] nodes, not [PhysicsBody3D] nodes. To make particles collide with various objects, you can add [GPUParticlesCollision3D] nodes as children of [PhysicsBody3D] nodes. + [b]Note:[/b] 3D Particles can only collide with [GPUParticlesCollision3D] nodes, not [PhysicsBody3D] nodes. To make particles collide with various objects, you can add [GPUParticlesCollision3D] nodes as children of [PhysicsBody3D] nodes. In 3D, collisions only occur within the area defined by the [GPUParticles3D] node's [member GPUParticles3D.visibility_aabb]. [b]Note:[/b] 2D Particles can only collide with [LightOccluder2D] nodes, not [PhysicsBody2D] nodes. </member> <member name="collision_use_scale" type="bool" setter="set_collision_use_scale" getter="is_collision_using_scale" default="false"> - Should collision take scale into account. + If [code]true[/code], [member GPUParticles3D.collision_base_size] is multiplied by the particle's effective scale (see [member scale_min], [member scale_max], [member scale_curve], and [member scale_over_velocity_curve]). </member> <member name="color" type="Color" setter="set_color" getter="get_color" default="Color(1, 1, 1, 1)"> Each particle's initial color. If the [GPUParticles2D]'s [code]texture[/code] is defined, it will be multiplied by this color. @@ -316,16 +316,22 @@ Each particle's initial direction range from [code]+spread[/code] to [code]-spread[/code] degrees. </member> <member name="sub_emitter_amount_at_collision" type="int" setter="set_sub_emitter_amount_at_collision" getter="get_sub_emitter_amount_at_collision"> - Sub particle amount on collision. - Maximum amount set in the sub particles emitter. + The amount of particles to spawn from the subemitter node when a collision occurs. When combined with [constant COLLISION_HIDE_ON_CONTACT] on the main particles material, this can be used to achieve effects such as raindrops hitting the ground. + [b]Note:[/b] This value shouldn't exceed [member GPUParticles2D.amount] or [member GPUParticles3D.amount] defined on the [i]subemitter node[/i] (not the main node), relative to the subemitter's particle lifetime. If the number of particles is exceeded, no new particles will spawn from the subemitter until enough particles have expired. </member> <member name="sub_emitter_amount_at_end" type="int" setter="set_sub_emitter_amount_at_end" getter="get_sub_emitter_amount_at_end"> + The amount of particles to spawn from the subemitter node when the particle expires. + [b]Note:[/b] This value shouldn't exceed [member GPUParticles2D.amount] or [member GPUParticles3D.amount] defined on the [i]subemitter node[/i] (not the main node), relative to the subemitter's particle lifetime. If the number of particles is exceeded, no new particles will spawn from the subemitter until enough particles have expired. </member> <member name="sub_emitter_frequency" type="float" setter="set_sub_emitter_frequency" getter="get_sub_emitter_frequency"> + The frequency at which particles should be emitted from the subemitter node. One particle will be spawned every [member sub_emitter_frequency] seconds. + [b]Note:[/b] This value shouldn't exceed [member GPUParticles2D.amount] or [member GPUParticles3D.amount] defined on the [i]subemitter node[/i] (not the main node), relative to the subemitter's particle lifetime. If the number of particles is exceeded, no new particles will spawn from the subemitter until enough particles have expired. </member> <member name="sub_emitter_keep_velocity" type="bool" setter="set_sub_emitter_keep_velocity" getter="get_sub_emitter_keep_velocity" default="false"> + If [code]true[/code], the subemitter inherits the parent particle's velocity when it spawns. </member> <member name="sub_emitter_mode" type="int" setter="set_sub_emitter_mode" getter="get_sub_emitter_mode" enum="ParticleProcessMaterial.SubEmitterMode" default="0"> + The particle subemitter mode (see [member GPUParticles2D.sub_emitter] and [member GPUParticles3D.sub_emitter]). </member> <member name="tangential_accel_curve" type="Texture2D" setter="set_param_texture" getter="get_param_texture"> Each particle's tangential acceleration will vary along this [CurveTexture]. @@ -378,6 +384,7 @@ A [CurveTexture] that defines the maximum velocity of a particle during its lifetime. </member> <member name="velocity_pivot" type="Vector3" setter="set_velocity_pivot" getter="get_velocity_pivot" default="Vector3(0, 0, 0)"> + A pivot point used to calculate radial and orbital velocity of particles. </member> </members> <constants> diff --git a/doc/classes/PopupMenu.xml b/doc/classes/PopupMenu.xml index 6293fcb309..40d5a9f4a2 100644 --- a/doc/classes/PopupMenu.xml +++ b/doc/classes/PopupMenu.xml @@ -186,7 +186,7 @@ <param index="1" name="submenu" type="String" /> <param index="2" name="id" type="int" default="-1" /> <description> - Adds an item that will act as a submenu of the parent [PopupMenu] node when clicked. The [param submenu] argument is the name of the child [PopupMenu] node that will be shown when the item is clicked. + Adds an item that will act as a submenu of the parent [PopupMenu] node when clicked. The [param submenu] argument must be the name of an existing [PopupMenu] that has been added as a child to this node. This submenu will be shown when the item is clicked, hovered for long enough, or activated using the [code]ui_select[/code] or [code]ui_right[/code] input actions. An [param id] can optionally be provided. If no [param id] is provided, one will be created from the index. </description> </method> @@ -346,6 +346,12 @@ Returns [code]true[/code] if the specified item's shortcut is disabled. </description> </method> + <method name="is_system_menu" qualifiers="const"> + <return type="bool" /> + <description> + Returns [code]true[/code] if the menu is bound to the special system menu. + </description> + </method> <method name="remove_item"> <return type="void" /> <param index="0" name="index" type="int" /> @@ -566,6 +572,9 @@ <member name="submenu_popup_delay" type="float" setter="set_submenu_popup_delay" getter="get_submenu_popup_delay" default="0.3"> Sets the delay time in seconds for the submenu item to popup on mouse hovering. If the popup menu is added as a child of another (acting as a submenu), it will inherit the delay time of the parent menu item. </member> + <member name="system_menu_root" type="String" setter="set_system_menu_root" getter="get_system_menu_root" default=""""> + If set to one of the values returned by [method DisplayServer.global_menu_get_system_menu_roots], this [PopupMenu] is bound to the special system menu. Only one [PopupMenu] can be bound to each special menu at a time. + </member> </members> <signals> <signal name="id_focused"> diff --git a/doc/classes/ProceduralSkyMaterial.xml b/doc/classes/ProceduralSkyMaterial.xml index 54bffd009f..3fb9f9059c 100644 --- a/doc/classes/ProceduralSkyMaterial.xml +++ b/doc/classes/ProceduralSkyMaterial.xml @@ -11,6 +11,9 @@ <tutorials> </tutorials> <members> + <member name="energy_multiplier" type="float" setter="set_energy_multiplier" getter="get_energy_multiplier" default="1.0"> + The sky's overall brightness multiplier. Higher values result in a brighter sky. + </member> <member name="ground_bottom_color" type="Color" setter="set_ground_bottom_color" getter="get_ground_bottom_color" default="Color(0.2, 0.169, 0.133, 1)"> Color of the ground at the bottom. Blends with [member ground_horizon_color]. </member> diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml index 69a374fd58..ab92916320 100644 --- a/doc/classes/ProjectSettings.xml +++ b/doc/classes/ProjectSettings.xml @@ -328,7 +328,8 @@ Changes to this setting will only be applied upon restarting the application. </member> <member name="application/run/frame_delay_msec" type="int" setter="" getter="" default="0"> - Forces a delay between frames in the main loop (in milliseconds). This may be useful if you plan to disable vertical synchronization. + Forces a [i]constant[/i] delay between frames in the main loop (in milliseconds). In most situations, [member application/run/max_fps] should be preferred as an FPS limiter as it's more precise. + This setting can be overridden using the [code]--frame-delay <ms;>[/code] command line argument. </member> <member name="application/run/low_processor_mode" type="bool" setter="" getter="" default="false"> If [code]true[/code], enables low-processor usage mode. This setting only works on desktop platforms. The screen is not redrawn if nothing changes visually. This is meant for writing applications and editors, but is pretty useless (and can hurt performance) in most games. @@ -349,7 +350,7 @@ If [member display/window/vsync/vsync_mode] is [code]Enabled[/code], on monitors with variable refresh rate enabled (G-Sync/FreeSync), using a FPS limit a few frames lower than the monitor's refresh rate will [url=https://blurbusters.com/howto-low-lag-vsync-on/]reduce input lag while avoiding tearing[/url]. If [member display/window/vsync/vsync_mode] is [code]Disabled[/code], limiting the FPS to a high value that can be consistently reached on the system can reduce input lag compared to an uncapped framerate. Since this works by ensuring the GPU load is lower than 100%, this latency reduction is only effective in GPU-bottlenecked scenarios, not CPU-bottlenecked scenarios. See also [member physics/common/physics_ticks_per_second]. - This setting can be overridden using the [code]--max-fps <fps;>[/code] command line argument (including with a value of [code]0[/code] for unlimited framerate). + This setting can be overridden using the [code]--max-fps <fps>[/code] command line argument (including with a value of [code]0[/code] for unlimited framerate). [b]Note:[/b] This property is only read when the project starts. To change the rendering FPS cap at runtime, set [member Engine.max_fps] instead. </member> <member name="audio/buses/channel_disable_threshold_db" type="float" setter="" getter="" default="-60.0"> @@ -569,6 +570,7 @@ </member> <member name="debug/gdscript/warnings/untyped_declaration" type="int" setter="" getter="" default="0"> When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when a variable or parameter has no static type, or if a function has no static return type. + [b]Note:[/b] This warning is recommended together with [member EditorSettings.text_editor/completion/add_type_hints] to help achieve type safety. </member> <member name="debug/gdscript/warnings/unused_local_constant" 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 constant is never used. @@ -828,7 +830,7 @@ </member> <member name="display/window/size/window_width_override" type="int" setter="" getter="" default="0"> On desktop platforms, overrides the game's initial window width. See also [member display/window/size/window_height_override], [member display/window/size/viewport_width] and [member display/window/size/viewport_height]. - [b]Note:[/b] By default, or when set to [code]0[/code], the initial window width is the viewport [member display/window/size/viewport_width]. This setting is ignored on iOS, Android, and Web. + [b]Note:[/b] By default, or when set to [code]0[/code], the initial window width is the [member display/window/size/viewport_width]. This setting is ignored on iOS, Android, and Web. </member> <member name="display/window/stretch/aspect" type="String" setter="" getter="" default=""keep""> </member> @@ -843,6 +845,9 @@ </member> <member name="display/window/stretch/scale_mode" type="String" setter="" getter="" default=""fractional""> The policy to use to determine the final scale factor for 2D elements. This affects how [member display/window/stretch/scale] is applied, in addition to the automatic scale factor determined by [member display/window/stretch/mode]. + [b]"fractional"[/b]: The scale factor will not be modified. + [b]"integer"[/b]: The scale factor will be floored to an integer value, which means that the screen size will always be an integer multiple of the base viewport size. This provides a crisp pixel art appearance. + [b]Note:[/b] When using integer scaling with a stretch mode, resizing the window to be smaller than the base viewport size will clip the contents. Consider preventing that by setting [member Window.min_size] to the same value as the base viewport size defined in [member display/window/size/viewport_width] and [member display/window/size/viewport_height]. </member> <member name="display/window/subwindows/embed_subwindows" type="bool" setter="" getter="" default="true"> If [code]true[/code] subwindows are embedded in the main window. @@ -2364,33 +2369,43 @@ <member name="rendering/environment/volumetric_fog/volume_size" type="int" setter="" getter="" default="64"> Base size used to determine size of froxel buffer in the camera X-axis and Y-axis. The final size is scaled by the aspect ratio of the screen, so actual values may differ from what is set. Set a larger size for more detailed fog, set a smaller size for better performance. </member> - <member name="rendering/gl_compatibility/driver" type="String" setter="" getter="" default=""opengl3""> + <member name="rendering/gl_compatibility/driver" type="String" setter="" getter=""> Sets the driver to be used by the renderer when using the Compatibility renderer. This property can not be edited directly, instead, set the driver using the platform-specific overrides. </member> - <member name="rendering/gl_compatibility/driver.android" type="String" setter="" getter="" default=""opengl3""> + <member name="rendering/gl_compatibility/driver.android" type="String" setter="" getter=""> Android override for [member rendering/gl_compatibility/driver]. </member> - <member name="rendering/gl_compatibility/driver.ios" type="String" setter="" getter="" default=""opengl3""> + <member name="rendering/gl_compatibility/driver.ios" type="String" setter="" getter=""> iOS override for [member rendering/gl_compatibility/driver]. </member> - <member name="rendering/gl_compatibility/driver.linuxbsd" type="String" setter="" getter="" default=""opengl3""> + <member name="rendering/gl_compatibility/driver.linuxbsd" type="String" setter="" getter=""> LinuxBSD override for [member rendering/gl_compatibility/driver]. </member> - <member name="rendering/gl_compatibility/driver.macos" type="String" setter="" getter="" default=""opengl3""> + <member name="rendering/gl_compatibility/driver.macos" type="String" setter="" getter=""> macOS override for [member rendering/gl_compatibility/driver]. </member> - <member name="rendering/gl_compatibility/driver.web" type="String" setter="" getter="" default=""opengl3""> + <member name="rendering/gl_compatibility/driver.web" type="String" setter="" getter=""> Web override for [member rendering/gl_compatibility/driver]. </member> - <member name="rendering/gl_compatibility/driver.windows" type="String" setter="" getter="" default=""opengl3""> + <member name="rendering/gl_compatibility/driver.windows" type="String" setter="" getter=""> Windows override for [member rendering/gl_compatibility/driver]. </member> <member name="rendering/gl_compatibility/fallback_to_angle" type="bool" setter="" getter="" default="true"> If [code]true[/code], the compatibility renderer will fall back to ANGLE if native OpenGL is not supported or the device is listed in [member rendering/gl_compatibility/force_angle_on_devices]. + [b]Note:[/b] This setting is implemented only on Windows. </member> - <member name="rendering/gl_compatibility/force_angle_on_devices" type="Array" setter="" getter="" default="[]"> + <member name="rendering/gl_compatibility/fallback_to_gles" type="bool" setter="" getter="" default="true"> + If [code]true[/code], the compatibility renderer will fall back to OpenGLES if desktop OpenGL is not supported. + [b]Note:[/b] This setting is implemented only on Linux/X11. + </member> + <member name="rendering/gl_compatibility/fallback_to_native" type="bool" setter="" getter="" default="true"> + If [code]true[/code], the compatibility renderer will fall back to native OpenGL if ANGLE over Metal is not supported. + [b]Note:[/b] This setting is implemented only on macOS. + </member> + <member name="rendering/gl_compatibility/force_angle_on_devices" type="Array" setter="" getter=""> An [Array] of devices which should always use the ANGLE renderer. Each entry is a [Dictionary] with the following keys: [code]vendor[/code] and [code]name[/code]. [code]name[/code] can be set to [code]*[/code] to add all devices with the specified [code]vendor[/code]. + [b]Note:[/b] This setting is implemented only on Windows. </member> <member name="rendering/gl_compatibility/item_buffer_size" type="int" setter="" getter="" default="16384"> Maximum number of canvas items commands that can be drawn in a single viewport update. If more render commands are issued they will be ignored. Decreasing this limit may improve performance on bandwidth limited devices. Increase this limit if you find that not all objects are being drawn in a frame. @@ -2601,22 +2616,34 @@ <member name="rendering/renderer/rendering_method.web" type="String" setter="" getter="" default=""gl_compatibility""> Override for [member rendering/renderer/rendering_method] on web. </member> - <member name="rendering/rendering_device/driver" type="String" setter="" getter="" default=""vulkan""> + <member name="rendering/rendering_device/d3d12/max_misc_descriptors_per_frame" type="int" setter="" getter="" default="512"> + The number of entries in the miscellaneous descriptors heap the Direct3D 12 rendering driver uses each frame, used for various operations like clearing a texture. + Depending on the complexity of scenes, this value may be lowered or may need to be raised. + </member> + <member name="rendering/rendering_device/d3d12/max_resource_descriptors_per_frame" type="int" setter="" getter="" default="16384"> + The number of entries in the resource descriptors heap the Direct3D 12 rendering driver uses each frame, used for most rendering operations. + Depending on the complexity of scenes, this value may be lowered or may need to be raised. + </member> + <member name="rendering/rendering_device/d3d12/max_sampler_descriptors_per_frame" type="int" setter="" getter="" default="1024"> + The number of entries in the sampler descriptors heap the Direct3D 12 rendering driver uses each frame, used for most rendering operations. + 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. </member> - <member name="rendering/rendering_device/driver.android" type="String" setter="" getter="" default=""vulkan""> + <member name="rendering/rendering_device/driver.android" type="String" setter="" getter=""> Android override for [member rendering/rendering_device/driver]. </member> - <member name="rendering/rendering_device/driver.ios" type="String" setter="" getter="" default=""vulkan""> + <member name="rendering/rendering_device/driver.ios" type="String" setter="" getter=""> iOS override for [member rendering/rendering_device/driver]. </member> - <member name="rendering/rendering_device/driver.linuxbsd" type="String" setter="" getter="" default=""vulkan""> + <member name="rendering/rendering_device/driver.linuxbsd" type="String" setter="" getter=""> LinuxBSD override for [member rendering/rendering_device/driver]. </member> - <member name="rendering/rendering_device/driver.macos" type="String" setter="" getter="" default=""vulkan""> + <member name="rendering/rendering_device/driver.macos" type="String" setter="" getter=""> macOS override for [member rendering/rendering_device/driver]. </member> - <member name="rendering/rendering_device/driver.windows" type="String" setter="" getter="" default=""vulkan""> + <member name="rendering/rendering_device/driver.windows" type="String" setter="" getter=""> Windows override for [member rendering/rendering_device/driver]. </member> <member name="rendering/rendering_device/pipeline_cache/save_chunk_size_mb" type="float" setter="" getter="" default="3.0"> @@ -2684,7 +2711,6 @@ Affects the final texture sharpness by reading from a lower or higher mipmap (also called "texture LOD bias"). Negative values make mipmapped textures sharper but grainier when viewed at a distance, while positive values make mipmapped textures blurrier (even when up close). Enabling temporal antialiasing ([member rendering/anti_aliasing/quality/use_taa]) will automatically apply a [code]-0.5[/code] offset to this value, while enabling FXAA ([member rendering/anti_aliasing/quality/screen_space_aa]) will automatically apply a [code]-0.25[/code] offset to this value. If both TAA and FXAA are enabled at the same time, an offset of [code]-0.75[/code] is applied to this value. [b]Note:[/b] If [member rendering/scaling_3d/scale] is lower than [code]1.0[/code] (exclusive), [member rendering/textures/default_filters/texture_mipmap_bias] is used to adjust the automatic mipmap bias which is calculated internally based on the scale factor. The formula for this is [code]log2(scaling_3d_scale) + mipmap_bias[/code]. - [b]Note:[/b] This property is only read when the project starts. To change the mipmap LOD bias at run-time, set [member Viewport.texture_mipmap_bias] instead. </member> <member name="rendering/textures/default_filters/use_nearest_mipmap_filter" type="bool" setter="" getter="" default="false"> If [code]true[/code], uses nearest-neighbor mipmap filtering when using mipmaps (also called "bilinear filtering"), which will result in visible seams appearing between mipmap stages. This may increase performance in mobile as less memory bandwidth is used. If [code]false[/code], linear mipmap filtering (also called "trilinear filtering") is used. @@ -2764,9 +2790,11 @@ </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]. + [b]Note:[/b] Only works on compatibility renderer. </member> <member name="xr/openxr/foveation_level" type="int" setter="" getter="" default=""0""> Applied foveation level if supported: 0 = off, 1 = low, 2 = medium, 3 = high. + [b]Note:[/b] Only works on compatibility renderer. </member> <member name="xr/openxr/reference_space" type="int" setter="" getter="" default=""1""> Specify the default reference space. diff --git a/doc/classes/RandomNumberGenerator.xml b/doc/classes/RandomNumberGenerator.xml index 383988360f..54f18a1ab4 100644 --- a/doc/classes/RandomNumberGenerator.xml +++ b/doc/classes/RandomNumberGenerator.xml @@ -56,7 +56,7 @@ <method name="randomize"> <return type="void" /> <description> - Setups a time-based seed to for this [RandomNumberGenerator] instance. Unlike the [@GlobalScope] random number generation functions, different [RandomNumberGenerator] instances can use different seeds. + Sets up a time-based seed for this [RandomNumberGenerator] instance. Unlike the [@GlobalScope] random number generation functions, different [RandomNumberGenerator] instances can use different seeds. </description> </method> </methods> diff --git a/doc/classes/RefCounted.xml b/doc/classes/RefCounted.xml index fe10f84449..3ef87e462d 100644 --- a/doc/classes/RefCounted.xml +++ b/doc/classes/RefCounted.xml @@ -6,6 +6,7 @@ <description> Base class for any object that keeps a reference count. [Resource] and many other helper objects inherit this class. Unlike other [Object] types, [RefCounted]s keep an internal reference counter so that they are automatically released when no longer in use, and only then. [RefCounted]s therefore do not need to be freed manually with [method Object.free]. + [RefCounted] instances caught in a cyclic reference will [b]not[/b] be freed automatically. For example, if a node holds a reference to instance [code]A[/code], which directly or indirectly holds a reference back to [code]A[/code], [code]A[/code]'s reference count will be 2. Destruction of the node will leave [code]A[/code] dangling with a reference count of 1, and there will be a memory leak. To prevent this, one of the references in the cycle can be made weak with [method @GlobalScope.weakref]. In the vast majority of use cases, instantiating and using [RefCounted]-derived types is all you need to do. The methods provided in this class are only for advanced users, and can cause issues if misused. [b]Note:[/b] In C#, reference-counted objects will not be freed instantly after they are no longer in use. Instead, garbage collection will run periodically and will free reference-counted objects that are no longer in use. This means that unused ones will linger on for a while before being removed. </description> diff --git a/doc/classes/RenderingServer.xml b/doc/classes/RenderingServer.xml index dd279206ab..a3ec4d25f1 100644 --- a/doc/classes/RenderingServer.xml +++ b/doc/classes/RenderingServer.xml @@ -925,6 +925,14 @@ [b]Note:[/b] When using the OpenGL backend or when running in headless mode, this function always returns [code]null[/code]. </description> </method> + <method name="debug_canvas_item_get_rect"> + <return type="Rect2" /> + <param index="0" name="item" type="RID" /> + <description> + Returns the bounding rectangle for a canvas item in local space, as calculated by the renderer. This bound is used internally for culling. + [b]Warning:[/b] This function is intended for debugging in the editor, and will pass through and return a zero [Rect2] in exported projects. + </description> + </method> <method name="decal_create"> <return type="RID" /> <description> @@ -1362,7 +1370,7 @@ <param index="0" name="swap_buffers" type="bool" default="true" /> <param index="1" name="frame_step" type="float" default="0.0" /> <description> - Forces redrawing of all viewports at once. + Forces redrawing of all viewports at once. Must be called from the main thread. </description> </method> <method name="force_sync"> @@ -3329,7 +3337,7 @@ <return type="int" enum="Image.Format" /> <param index="0" name="texture" type="RID" /> <description> - Returns the [enum Image.Format] for the texture. + Returns the format for the texture. </description> </method> <method name="texture_get_native_handle" qualifiers="const"> @@ -4226,7 +4234,7 @@ Flag used to mark that the mesh does not have a vertex array and instead will infer vertex positions in the shader using indices and other information. </constant> <constant name="ARRAY_FLAG_COMPRESS_ATTRIBUTES" value="536870912" enum="ArrayFormat" is_bitfield="true"> - Flag used to mark that a mesh is using compressed attributes (vertices, normals, tangents, uvs). When this form of compression is enabled, vertex positions will be packed into into an RGBA16UNORM attribute and scaled in the vertex shader. The normal and tangent will be packed into a RG16UNORM representing an axis, and an 16 bit float stored in the A-channel of the vertex. UVs will use 16-bit normalized floats instead of full 32 bit signed floats. When using this compression mode you must either use vertices, normals, and tangents or only vertices. You cannot use normals without tangents. Importers will automatically enable this compression if they can. + Flag used to mark that a mesh is using compressed attributes (vertices, normals, tangents, UVs). When this form of compression is enabled, vertex positions will be packed into an RGBA16UNORM attribute and scaled in the vertex shader. The normal and tangent will be packed into an RG16UNORM representing an axis, and a 16-bit float stored in the A-channel of the vertex. UVs will use 16-bit normalized floats instead of full 32-bit signed floats. When using this compression mode you must use either vertices, normals, and tangents or only vertices. You cannot use normals without tangents. Importers will automatically enable this compression if they can. </constant> <constant name="ARRAY_FLAG_FORMAT_VERSION_BASE" value="35" enum="ArrayFormat" is_bitfield="true"> Flag used to mark the start of the bits used to store the mesh version. @@ -4505,9 +4513,10 @@ Draw particles in the order that they appear in the particles array. </constant> <constant name="PARTICLES_DRAW_ORDER_LIFETIME" value="1" enum="ParticlesDrawOrder"> - Sort particles based on their lifetime. + Sort particles based on their lifetime. In other words, the particle with the highest lifetime is drawn at the front. </constant> <constant name="PARTICLES_DRAW_ORDER_REVERSE_LIFETIME" value="2" enum="ParticlesDrawOrder"> + Sort particles based on the inverse of their lifetime. In other words, the particle with the lowest lifetime is drawn at the front. </constant> <constant name="PARTICLES_DRAW_ORDER_VIEW_DEPTH" value="3" enum="ParticlesDrawOrder"> Sort particles based on their distance to the camera. @@ -4685,7 +4694,10 @@ <constant name="VIEWPORT_RENDER_INFO_TYPE_SHADOW" value="1" enum="ViewportRenderInfoType"> Shadow render pass. Objects will be rendered several times depending on the number of amounts of lights with shadows and the number of directional shadow splits. </constant> - <constant name="VIEWPORT_RENDER_INFO_TYPE_MAX" value="2" enum="ViewportRenderInfoType"> + <constant name="VIEWPORT_RENDER_INFO_TYPE_CANVAS" value="2" enum="ViewportRenderInfoType"> + Canvas item rendering. This includes all 2D rendering. + </constant> + <constant name="VIEWPORT_RENDER_INFO_TYPE_MAX" value="3" enum="ViewportRenderInfoType"> Represents the size of the [enum ViewportRenderInfoType] enum. </constant> <constant name="VIEWPORT_DEBUG_DRAW_DISABLED" value="0" enum="ViewportDebugDraw"> @@ -5129,22 +5141,26 @@ Uses the default filter mode for this [Viewport]. </constant> <constant name="CANVAS_ITEM_TEXTURE_FILTER_NEAREST" value="1" enum="CanvasItemTextureFilter"> - The texture filter reads from the nearest pixel only. The simplest and fastest method of filtering, but the texture will look pixelized. + The texture filter reads from the nearest pixel only. This makes the texture look pixelated from up close, and grainy from a distance (due to mipmaps not being sampled). </constant> <constant name="CANVAS_ITEM_TEXTURE_FILTER_LINEAR" value="2" enum="CanvasItemTextureFilter"> - The texture filter blends between the nearest 4 pixels. Use this when you want to avoid a pixelated style, but do not want mipmaps. + The texture filter blends between the nearest 4 pixels. This makes the texture look smooth from up close, and grainy from a distance (due to mipmaps not being sampled). </constant> <constant name="CANVAS_ITEM_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS" value="3" enum="CanvasItemTextureFilter"> - The texture filter reads from the nearest pixel in the nearest mipmap. The fastest way to read from textures with mipmaps. + The texture filter reads from the nearest pixel and blends between the nearest 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]). This makes the texture look pixelated from up close, and smooth from a distance. + Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to [Camera2D] zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. </constant> <constant name="CANVAS_ITEM_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS" value="4" enum="CanvasItemTextureFilter"> - The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps. + The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]). This makes the texture look smooth from up close, and smooth from a distance. + Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to [Camera2D] zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. </constant> <constant name="CANVAS_ITEM_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC" value="5" enum="CanvasItemTextureFilter"> - The texture filter reads from the nearest pixel, but selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. + The texture filter reads from the nearest pixel and blends between 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]) based on the angle between the surface and the camera view. This makes the texture look pixelated from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. + [b]Note:[/b] This texture filter is rarely useful in 2D projects. [constant CANVAS_ITEM_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS] is usually more appropriate in this case. </constant> <constant name="CANVAS_ITEM_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC" value="6" enum="CanvasItemTextureFilter"> - The texture filter blends between the nearest 4 pixels and selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. This is the slowest of the filtering options, but results in the highest quality texturing. + The texture filter blends between the nearest 4 pixels and blends between 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]) based on the angle between the surface and the camera view. This makes the texture look smooth from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. + [b]Note:[/b] This texture filter is rarely useful in 2D projects. [constant CANVAS_ITEM_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS] is usually more appropriate in this case. </constant> <constant name="CANVAS_ITEM_TEXTURE_FILTER_MAX" value="7" enum="CanvasItemTextureFilter"> Max value for [enum CanvasItemTextureFilter] enum. diff --git a/doc/classes/Resource.xml b/doc/classes/Resource.xml index 75c258253d..49db3f81b4 100644 --- a/doc/classes/Resource.xml +++ b/doc/classes/Resource.xml @@ -4,8 +4,9 @@ Base class for serializable objects. </brief_description> <description> - Resource is the base class for all Godot-specific resource types, serving primarily as data containers. Since they inherit from [RefCounted], resources are reference-counted and freed when no longer in use. They can also be nested within other resources, and saved on disk. Once loaded from disk, further attempts to load a resource by [member resource_path] returns the same reference. [PackedScene], one of the most common [Object]s in a Godot project, is also a resource, uniquely capable of storing and instantiating the [Node]s it contains as many times as desired. + Resource is the base class for all Godot-specific resource types, serving primarily as data containers. Since they inherit from [RefCounted], resources are reference-counted and freed when no longer in use. They can also be nested within other resources, and saved on disk. [PackedScene], one of the most common [Object]s in a Godot project, is also a resource, uniquely capable of storing and instantiating the [Node]s it contains as many times as desired. In GDScript, resources can loaded from disk by their [member resource_path] using [method @GDScript.load] or [method @GDScript.preload]. + The engine keeps a global cache of all loaded resources, referenced by paths (see [method ResourceLoader.has_cached]). A resource will be cached when loaded for the first time and removed from cache once all references are released. When a resource is cached, subsequent loads using its path will return the cached reference. [b]Note:[/b] In C#, resources will not be freed instantly after they are no longer in use. Instead, garbage collection will run periodically and will free resources that are no longer in use. This means that unused resources will linger on for a while before being removed. </description> <tutorials> @@ -92,6 +93,7 @@ </member> <member name="resource_name" type="String" setter="set_name" getter="get_name" default=""""> An optional name for this resource. When defined, its value is displayed to represent the resource in the Inspector dock. For built-in scripts, the name is displayed as part of the tab name in the script editor. + [b]Note:[/b] Some resource formats do not support resource names. You can still set the name in the editor or via code, but it will be lost when the resource is reloaded. For example, only built-in scripts can have a resource name, while scripts stored in separate files cannot. </member> <member name="resource_path" type="String" setter="set_path" getter="get_path" default=""""> The unique path to this resource. If it has been saved to disk, the value will be its filepath. If the resource is exclusively contained within a scene, the value will be the [PackedScene]'s filepath, followed by a unique identifier. diff --git a/doc/classes/ResourceImporterTextureAtlas.xml b/doc/classes/ResourceImporterTextureAtlas.xml index 9f3f642869..b4890218e0 100644 --- a/doc/classes/ResourceImporterTextureAtlas.xml +++ b/doc/classes/ResourceImporterTextureAtlas.xml @@ -22,7 +22,7 @@ [b]Mesh:[/b] Imports the atlas as an [ArrayMesh] resource, keeping the original bitmap visible (but rendered as a polygon). This can be used to reduce fill rate when rendering large transparent sprites, at the cost of slower rendering if there are little to no transparent areas in the sprite. </member> <member name="trim_alpha_border_from_region" type="bool" setter="" getter="" default="true"> - If [code]true[/code], trims the region to exclude fully transparent pixels using a clipping rectangle (which is never rotated). This can be used to save memory. See also [member trim_alpha_border_from_region]. + If [code]true[/code], trims the region to exclude fully transparent pixels using a clipping rectangle (which is never rotated). This can be used to save memory. See also [member crop_to_region]. [b]Note:[/b] Only effective if [member import_mode] is [b]Region[/b]. </member> </members> diff --git a/doc/classes/ResourceLoader.xml b/doc/classes/ResourceLoader.xml index 267594edcb..54e95d8c30 100644 --- a/doc/classes/ResourceLoader.xml +++ b/doc/classes/ResourceLoader.xml @@ -28,6 +28,7 @@ <description> Returns whether a recognized resource exists for the given [param path]. An optional [param type_hint] can be used to further specify the [Resource] type that should be handled by the [ResourceFormatLoader]. Anything that inherits from [Resource] can be used as a type hint, for example [Image]. + [b]Note:[/b] If you use [method Resource.take_over_path], this method will return [code]true[/code] for the taken path even if the resource wasn't saved (i.e. exists only in resource cache). </description> </method> <method name="get_dependencies"> @@ -137,10 +138,13 @@ The resource was loaded successfully and can be accessed via [method load_threaded_get]. </constant> <constant name="CACHE_MODE_IGNORE" value="0" enum="CacheMode"> + The resource is always loaded from disk, even if a cache entry exists for its path, and the newly loaded copy will not be cached. Instances loaded with this mode will exist independently. </constant> <constant name="CACHE_MODE_REUSE" value="1" enum="CacheMode"> + If a resource is cached, returns the cached reference. Otherwise it's loaded from disk. </constant> <constant name="CACHE_MODE_REPLACE" value="2" enum="CacheMode"> + The resource is always loaded from disk, even if a cache entry exists for its path. The cached entry will be replaced by the newly loaded copy. </constant> </constants> </class> diff --git a/doc/classes/ResourceSaver.xml b/doc/classes/ResourceSaver.xml index 7b90781fc5..42c9bd7a3c 100644 --- a/doc/classes/ResourceSaver.xml +++ b/doc/classes/ResourceSaver.xml @@ -42,6 +42,7 @@ Saves a resource to disk to the given path, using a [ResourceFormatSaver] that recognizes the resource object. If [param path] is empty, [ResourceSaver] will try to use [member Resource.resource_path]. The [param flags] bitmask can be specified to customize the save behavior using [enum SaverFlags] flags. Returns [constant OK] on success. + [b]Note:[/b] When the project is running, any generated UID associated with the resource will not be saved as the required code is only executed in editor mode. </description> </method> </methods> diff --git a/doc/classes/RichTextLabel.xml b/doc/classes/RichTextLabel.xml index 405d189c54..c9a48e46b2 100644 --- a/doc/classes/RichTextLabel.xml +++ b/doc/classes/RichTextLabel.xml @@ -764,10 +764,10 @@ The vertical separation of elements in a table. </theme_item> <theme_item name="text_highlight_h_padding" data_type="constant" type="int" default="3"> - The horizontal padding around a highlighting and background color box. + The horizontal padding around boxes drawn by the [code][fgcolor][/code] and [code][bgcolor][/code] tags. This does not affect the appearance of text selection. </theme_item> <theme_item name="text_highlight_v_padding" data_type="constant" type="int" default="3"> - The vertical padding around a highlighting and background color box. + The vertical padding around boxes drawn by the [code][fgcolor][/code] and [code][bgcolor][/code] tags. This does not affect the appearance of text selection. </theme_item> <theme_item name="bold_font" data_type="font" type="Font"> The font used for bold text. diff --git a/doc/classes/SceneTree.xml b/doc/classes/SceneTree.xml index da23eadfd1..1a846140e5 100644 --- a/doc/classes/SceneTree.xml +++ b/doc/classes/SceneTree.xml @@ -42,7 +42,7 @@ <description> Changes the running scene to the one at the given [param path], after loading it into a [PackedScene] and creating a new instance. Returns [constant OK] on success, [constant ERR_CANT_OPEN] if the [param path] cannot be loaded into a [PackedScene], or [constant ERR_CANT_CREATE] if that scene cannot be instantiated. - [b]Note:[/b] The new scene node is added to the tree at the end of the frame. This ensures that both scenes aren't running at the same time, while still freeing the previous scene in a safe way similar to [method Node.queue_free]. As such, you won't be able to access the loaded scene immediately after the [method change_scene_to_file] call. + [b]Note:[/b] See [method change_scene_to_packed] for details on the order of operations. </description> </method> <method name="change_scene_to_packed"> @@ -51,7 +51,10 @@ <description> Changes the running scene to a new instance of the given [PackedScene] (which must be valid). Returns [constant OK] on success, [constant ERR_CANT_CREATE] if the scene cannot be instantiated, or [constant ERR_INVALID_PARAMETER] if the scene is invalid. - [b]Note:[/b] The new scene node is added to the tree at the end of the frame. You won't be able to access it immediately after the [method change_scene_to_packed] call. + [b]Note:[/b] Operations happen in the following order when [method change_scene_to_packed] is called: + 1. The current scene node is immediately removed from the tree. From that point, [method Node.get_tree] called on the current (outgoing) scene will return [code]null[/code]. [member current_scene] will be [code]null[/code], too, because the new scene is not available yet. + 2. At the end of the frame, the formerly current scene, already removed from the tree, will be deleted (freed from memory) and then the new scene will be instantiated and added to the tree. [method Node.get_tree] and [member current_scene] will be back to working as usual. + This ensures that both scenes aren't running at the same time, while still freeing the previous scene in a safe way similar to [method Node.queue_free]. </description> </method> <method name="create_timer"> @@ -119,6 +122,13 @@ Returns the number of nodes in this [SceneTree]. </description> </method> + <method name="get_node_count_in_group" qualifiers="const"> + <return type="int" /> + <param index="0" name="group" type="StringName" /> + <description> + Returns the number of nodes assigned to the given group. + </description> + </method> <method name="get_nodes_in_group"> <return type="Node[]" /> <param index="0" name="group" type="StringName" /> diff --git a/doc/classes/Script.xml b/doc/classes/Script.xml index 28d763585d..fa8e4ef5f2 100644 --- a/doc/classes/Script.xml +++ b/doc/classes/Script.xml @@ -24,6 +24,27 @@ Returns the script directly inherited by this script. </description> </method> + <method name="get_global_name" qualifiers="const"> + <return type="StringName" /> + <description> + Returns the class name associated with the script, if there is one. Returns an empty string otherwise. + To give the script a global name, you can use the [code]class_name[/code] keyword in GDScript and the [code][GlobalClass][/code] attribute in C#. + [codeblocks] + [gdscript] + class_name MyNode + extends Node + [/gdscript] + [csharp] + using Godot; + + [GlobalClass] + public partial class MyNode : Node + { + } + [/csharp] + [/codeblocks] + </description> + </method> <method name="get_instance_base_type" qualifiers="const"> <return type="StringName" /> <description> diff --git a/doc/classes/ShapeCast2D.xml b/doc/classes/ShapeCast2D.xml index a04ffe3881..d71c9ce13a 100644 --- a/doc/classes/ShapeCast2D.xml +++ b/doc/classes/ShapeCast2D.xml @@ -34,7 +34,7 @@ <method name="force_shapecast_update"> <return type="void" /> <description> - Updates the collision information for the shape. Use this method to update the collision information immediately instead of waiting for the next [code]_physics_process[/code] call, for example if the shape or its parent has changed state. + Updates the collision information for the shape immediately, without waiting for the next [code]_physics_process[/code] call. Use this method, for example, when the shape or its parent has changed state. [b]Note:[/b] [code]enabled == true[/code] is not required for this to work. </description> </method> @@ -130,10 +130,10 @@ </methods> <members> <member name="collide_with_areas" type="bool" setter="set_collide_with_areas" getter="is_collide_with_areas_enabled" default="false"> - If [code]true[/code], collision with [Area2D]s will be reported. + If [code]true[/code], collisions with [Area2D]s will be reported. </member> <member name="collide_with_bodies" type="bool" setter="set_collide_with_bodies" getter="is_collide_with_bodies_enabled" default="true"> - If [code]true[/code], collision with [PhysicsBody2D]s will be reported. + If [code]true[/code], collisions with [PhysicsBody2D]s will be reported. </member> <member name="collision_mask" type="int" setter="set_collision_mask" getter="get_collision_mask" default="1"> The shape's collision mask. Only objects in at least one collision layer enabled in the mask will be detected. diff --git a/doc/classes/ShapeCast3D.xml b/doc/classes/ShapeCast3D.xml index ce72944098..e189628f4c 100644 --- a/doc/classes/ShapeCast3D.xml +++ b/doc/classes/ShapeCast3D.xml @@ -34,7 +34,7 @@ <method name="force_shapecast_update"> <return type="void" /> <description> - Updates the collision information for the shape. Use this method to update the collision information immediately instead of waiting for the next [code]_physics_process[/code] call, for example if the shape or its parent has changed state. + Updates the collision information for the shape immediately, without waiting for the next [code]_physics_process[/code] call. Use this method, for example, when the shape or its parent has changed state. [b]Note:[/b] [code]enabled == true[/code] is not required for this to work. </description> </method> @@ -137,10 +137,10 @@ </methods> <members> <member name="collide_with_areas" type="bool" setter="set_collide_with_areas" getter="is_collide_with_areas_enabled" default="false"> - If [code]true[/code], collision with [Area3D]s will be reported. + If [code]true[/code], collisions with [Area3D]s will be reported. </member> <member name="collide_with_bodies" type="bool" setter="set_collide_with_bodies" getter="is_collide_with_bodies_enabled" default="true"> - If [code]true[/code], collision with [PhysicsBody3D]s will be reported. + If [code]true[/code], collisions with [PhysicsBody3D]s will be reported. </member> <member name="collision_mask" type="int" setter="set_collision_mask" getter="get_collision_mask" default="1"> The shape's collision mask. Only objects in at least one collision layer enabled in the mask will be detected. See [url=$DOCS_URL/tutorials/physics/physics_introduction.html#collision-layers-and-masks]Collision layers and masks[/url] in the documentation for more information. diff --git a/doc/classes/Skeleton3D.xml b/doc/classes/Skeleton3D.xml index b4c42ea399..bc3782d1a0 100644 --- a/doc/classes/Skeleton3D.xml +++ b/doc/classes/Skeleton3D.xml @@ -126,18 +126,21 @@ <return type="Vector3" /> <param index="0" name="bone_idx" type="int" /> <description> + Returns the pose position of the bone at [param bone_idx]. The returned [Vector3] is in the local coordinate space of the [Skeleton3D] node. </description> </method> <method name="get_bone_pose_rotation" qualifiers="const"> <return type="Quaternion" /> <param index="0" name="bone_idx" type="int" /> <description> + Returns the pose rotation of the bone at [param bone_idx]. The returned [Quaternion] is local to the bone with respect to the rotation of any parent bones. </description> </method> <method name="get_bone_pose_scale" qualifiers="const"> <return type="Vector3" /> <param index="0" name="bone_idx" type="int" /> <description> + Returns the pose scale of the bone at [param bone_idx]. </description> </method> <method name="get_bone_rest" qualifiers="const"> @@ -265,6 +268,7 @@ <param index="0" name="bone_idx" type="int" /> <param index="1" name="position" type="Vector3" /> <description> + Sets the pose position of the bone at [param bone_idx] to [param position]. [param position] is a [Vector3] describing a position local to the [Skeleton3D] node. </description> </method> <method name="set_bone_pose_rotation"> @@ -272,6 +276,7 @@ <param index="0" name="bone_idx" type="int" /> <param index="1" name="rotation" type="Quaternion" /> <description> + Sets the pose rotation of the bone at [param bone_idx] to [param rotation]. [param rotation] is a [Quaternion] describing a rotation in the bone's local coordinate space with respect to the rotation of any parent bones. </description> </method> <method name="set_bone_pose_scale"> @@ -279,6 +284,7 @@ <param index="0" name="bone_idx" type="int" /> <param index="1" name="scale" type="Vector3" /> <description> + Sets the pose scale of the bone at [param bone_idx] to [param scale]. </description> </method> <method name="set_bone_rest"> diff --git a/doc/classes/Sprite2D.xml b/doc/classes/Sprite2D.xml index 8eb9e26a83..f8622d8f38 100644 --- a/doc/classes/Sprite2D.xml +++ b/doc/classes/Sprite2D.xml @@ -60,13 +60,13 @@ If [code]true[/code], texture is flipped vertically. </member> <member name="frame" type="int" setter="set_frame" getter="get_frame" default="0"> - Current frame to display from sprite sheet. [member hframes] or [member vframes] must be greater than 1. + Current frame to display from sprite sheet. [member hframes] or [member vframes] must be greater than 1. This property is automatically adjusted when [member hframes] or [member vframes] are changed to keep pointing to the same visual frame (same column and row). If that's impossible, this value is reset to [code]0[/code]. </member> <member name="frame_coords" type="Vector2i" setter="set_frame_coords" getter="get_frame_coords" default="Vector2i(0, 0)"> Coordinates of the frame to display from sprite sheet. This is as an alias for the [member frame] property. [member hframes] or [member vframes] must be greater than 1. </member> <member name="hframes" type="int" setter="set_hframes" getter="get_hframes" default="1"> - The number of columns in the sprite sheet. + The number of columns in the sprite sheet. When this property is changed, [member frame] is adjusted so that the same visual frame is maintained (same row and column). If that's impossible, [member frame] is reset to [code]0[/code]. </member> <member name="offset" type="Vector2" setter="set_offset" getter="get_offset" default="Vector2(0, 0)"> The texture's drawing offset. @@ -84,7 +84,7 @@ [Texture2D] object to draw. </member> <member name="vframes" type="int" setter="set_vframes" getter="get_vframes" default="1"> - The number of rows in the sprite sheet. + The number of rows in the sprite sheet. When this property is changed, [member frame] is adjusted so that the same visual frame is maintained (same row and column). If that's impossible, [member frame] is reset to [code]0[/code]. </member> </members> <signals> diff --git a/doc/classes/Sprite3D.xml b/doc/classes/Sprite3D.xml index 9733c5f48a..4b4421aeba 100644 --- a/doc/classes/Sprite3D.xml +++ b/doc/classes/Sprite3D.xml @@ -10,13 +10,13 @@ </tutorials> <members> <member name="frame" type="int" setter="set_frame" getter="get_frame" default="0"> - Current frame to display from sprite sheet. [member hframes] or [member vframes] must be greater than 1. + Current frame to display from sprite sheet. [member hframes] or [member vframes] must be greater than 1. This property is automatically adjusted when [member hframes] or [member vframes] are changed to keep pointing to the same visual frame (same column and row). If that's impossible, this value is reset to [code]0[/code]. </member> <member name="frame_coords" type="Vector2i" setter="set_frame_coords" getter="get_frame_coords" default="Vector2i(0, 0)"> Coordinates of the frame to display from sprite sheet. This is as an alias for the [member frame] property. [member hframes] or [member vframes] must be greater than 1. </member> <member name="hframes" type="int" setter="set_hframes" getter="get_hframes" default="1"> - The number of columns in the sprite sheet. + The number of columns in the sprite sheet. When this property is changed, [member frame] is adjusted so that the same visual frame is maintained (same row and column). If that's impossible, [member frame] is reset to [code]0[/code]. </member> <member name="region_enabled" type="bool" setter="set_region_enabled" getter="is_region_enabled" default="false"> If [code]true[/code], the sprite will use [member region_rect] and display only the specified part of its texture. @@ -28,7 +28,7 @@ [Texture2D] object to draw. If [member GeometryInstance3D.material_override] is used, this will be overridden. The size information is still used. </member> <member name="vframes" type="int" setter="set_vframes" getter="get_vframes" default="1"> - The number of rows in the sprite sheet. + The number of rows in the sprite sheet. When this property is changed, [member frame] is adjusted so that the same visual frame is maintained (same row and column). If that's impossible, [member frame] is reset to [code]0[/code]. </member> </members> <signals> diff --git a/doc/classes/SubViewportContainer.xml b/doc/classes/SubViewportContainer.xml index e7d7883c78..e47e27c0ce 100644 --- a/doc/classes/SubViewportContainer.xml +++ b/doc/classes/SubViewportContainer.xml @@ -11,7 +11,7 @@ <tutorials> </tutorials> <methods> - <method name="_propagate_input_event" qualifiers="virtual const"> + <method name="_propagate_input_event" qualifiers="virtual const" is_experimental="true"> <return type="bool" /> <param index="0" name="event" type="InputEvent" /> <description> diff --git a/doc/classes/TabBar.xml b/doc/classes/TabBar.xml index 9b462b9f50..165b187710 100644 --- a/doc/classes/TabBar.xml +++ b/doc/classes/TabBar.xml @@ -317,7 +317,7 @@ <signal name="tab_selected"> <param index="0" name="tab" type="int" /> <description> - Emitted when a tab is selected via click or script, even if it is the current tab. + Emitted when a tab is selected via click, directional input, or script, even if it is the current tab. </description> </signal> </signals> diff --git a/doc/classes/TabContainer.xml b/doc/classes/TabContainer.xml index 1b0054ef25..b3a9264569 100644 --- a/doc/classes/TabContainer.xml +++ b/doc/classes/TabContainer.xml @@ -243,7 +243,7 @@ <signal name="tab_selected"> <param index="0" name="tab" type="int" /> <description> - Emitted when a tab is selected via click or script, even if it is the current tab. + Emitted when a tab is selected via click, directional input, or script, even if it is the current tab. </description> </signal> </signals> diff --git a/doc/classes/TextLine.xml b/doc/classes/TextLine.xml index e65006716d..2e4a3f7e4c 100644 --- a/doc/classes/TextLine.xml +++ b/doc/classes/TextLine.xml @@ -151,6 +151,9 @@ <member name="direction" type="int" setter="set_direction" getter="get_direction" enum="TextServer.Direction" default="0"> Text writing direction. </member> + <member name="ellipsis_char" type="String" setter="set_ellipsis_char" getter="get_ellipsis_char" default=""…""> + Ellipsis character used for text clipping. + </member> <member name="flags" type="int" setter="set_flags" getter="get_flags" enum="TextServer.JustificationFlag" is_bitfield="true" default="3"> Line alignment rules. For more info see [TextServer]. </member> diff --git a/doc/classes/TextParagraph.xml b/doc/classes/TextParagraph.xml index a8a4c3a764..541078ed22 100644 --- a/doc/classes/TextParagraph.xml +++ b/doc/classes/TextParagraph.xml @@ -274,6 +274,9 @@ <member name="direction" type="int" setter="set_direction" getter="get_direction" enum="TextServer.Direction" default="0"> Text writing direction. </member> + <member name="ellipsis_char" type="String" setter="set_ellipsis_char" getter="get_ellipsis_char" default=""…""> + Ellipsis character used for text clipping. + </member> <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. For more info see [enum TextServer.JustificationFlag]. </member> diff --git a/doc/classes/TextServer.xml b/doc/classes/TextServer.xml index a8a9964b10..09f484f523 100644 --- a/doc/classes/TextServer.xml +++ b/doc/classes/TextServer.xml @@ -155,7 +155,7 @@ <return type="int" /> <param index="0" name="font_rid" type="RID" /> <description> - Recturns an active face index in the TrueType / OpenType collection. + Returns an active face index in the TrueType / OpenType collection. </description> </method> <method name="font_get_fixed_size" qualifiers="const"> @@ -169,7 +169,7 @@ <return type="int" enum="TextServer.FixedSizeScaleMode" /> <param index="0" name="font_rid" type="RID" /> <description> - Returned bitmap font scaling mode. + Returns bitmap font scaling mode. </description> </method> <method name="font_get_generate_mipmaps" qualifiers="const"> @@ -1243,6 +1243,13 @@ Returns array of the composite character boundaries. </description> </method> + <method name="shaped_text_get_custom_ellipsis" qualifiers="const"> + <return type="int" /> + <param index="0" name="shaped" type="RID" /> + <description> + Returns ellipsis character used for text clipping. + </description> + </method> <method name="shaped_text_get_custom_punctuation" qualifiers="const"> <return type="String" /> <param index="0" name="shaped" type="RID" /> @@ -1547,6 +1554,14 @@ Override ranges should cover full source text without overlaps. BiDi algorithm will be used on each range separately. </description> </method> + <method name="shaped_text_set_custom_ellipsis"> + <return type="void" /> + <param index="0" name="shaped" type="RID" /> + <param index="1" name="char" type="int" /> + <description> + Sets ellipsis character used for text clipping. + </description> + </method> <method name="shaped_text_set_custom_punctuation"> <return type="void" /> <param index="0" name="shaped" type="RID" /> diff --git a/doc/classes/TextServerExtension.xml b/doc/classes/TextServerExtension.xml index 267e0b65cb..9555718b26 100644 --- a/doc/classes/TextServerExtension.xml +++ b/doc/classes/TextServerExtension.xml @@ -1073,6 +1073,12 @@ <description> </description> </method> + <method name="_shaped_text_get_custom_ellipsis" qualifiers="virtual const"> + <return type="int" /> + <param index="0" name="shaped" type="RID" /> + <description> + </description> + </method> <method name="_shaped_text_get_custom_punctuation" qualifiers="virtual const"> <return type="String" /> <param index="0" name="shaped" type="RID" /> @@ -1329,6 +1335,13 @@ <description> </description> </method> + <method name="_shaped_text_set_custom_ellipsis" qualifiers="virtual"> + <return type="void" /> + <param index="0" name="shaped" type="RID" /> + <param index="1" name="char" type="int" /> + <description> + </description> + </method> <method name="_shaped_text_set_custom_punctuation" qualifiers="virtual"> <return type="void" /> <param index="0" name="shaped" type="RID" /> diff --git a/doc/classes/TileData.xml b/doc/classes/TileData.xml index 8aa5f1398a..9e833e0236 100644 --- a/doc/classes/TileData.xml +++ b/doc/classes/TileData.xml @@ -70,15 +70,23 @@ <method name="get_navigation_polygon" qualifiers="const"> <return type="NavigationPolygon" /> <param index="0" name="layer_id" type="int" /> + <param index="1" name="flip_h" type="bool" default="false" /> + <param index="2" name="flip_v" type="bool" default="false" /> + <param index="3" name="transpose" type="bool" default="false" /> <description> Returns the navigation polygon of the tile for the TileSet navigation layer with index [param layer_id]. + [param flip_h], [param flip_v], and [param transpose] allow transforming the returned polygon. </description> </method> <method name="get_occluder" qualifiers="const"> <return type="OccluderPolygon2D" /> <param index="0" name="layer_id" type="int" /> + <param index="1" name="flip_h" type="bool" default="false" /> + <param index="2" name="flip_v" type="bool" default="false" /> + <param index="3" name="transpose" type="bool" default="false" /> <description> Returns the occluder polygon of the tile for the TileSet occlusion layer with index [param layer_id]. + [param flip_h], [param flip_v], and [param transpose] allow transforming the returned polygon. </description> </method> <method name="get_terrain_peering_bit" qualifiers="const"> diff --git a/doc/classes/TileSetAtlasSource.xml b/doc/classes/TileSetAtlasSource.xml index 755c266cd9..6f212274f8 100644 --- a/doc/classes/TileSetAtlasSource.xml +++ b/doc/classes/TileSetAtlasSource.xml @@ -90,7 +90,7 @@ <return type="int" enum="TileSetAtlasSource.TileAnimationMode" /> <param index="0" name="atlas_coords" type="Vector2i" /> <description> - Returns the [enum TileAnimationMode] of the tile at [param atlas_coords]. See also [method set_tile_animation_mode]. + Returns the tile animation mode of the tile at [param atlas_coords]. See also [method set_tile_animation_mode]. </description> </method> <method name="get_tile_animation_separation" qualifiers="const"> @@ -239,7 +239,7 @@ <param index="0" name="atlas_coords" type="Vector2i" /> <param index="1" name="mode" type="int" enum="TileSetAtlasSource.TileAnimationMode" /> <description> - Sets the [enum TileAnimationMode] of the tile at [param atlas_coords] to [param mode]. See also [method get_tile_animation_mode]. + Sets the tile animation mode of the tile at [param atlas_coords] to [param mode]. See also [method get_tile_animation_mode]. </description> </method> <method name="set_tile_animation_separation"> diff --git a/doc/classes/Time.xml b/doc/classes/Time.xml index 9dc567562a..79c332327f 100644 --- a/doc/classes/Time.xml +++ b/doc/classes/Time.xml @@ -152,7 +152,9 @@ <method name="get_time_zone_from_system" qualifiers="const"> <return type="Dictionary" /> <description> - Returns the current time zone as a dictionary of keys: [code]bias[/code] and [code]name[/code]. The [code]bias[/code] value is the offset from UTC in minutes, since not all time zones are multiples of an hour from UTC. + Returns the current time zone as a dictionary of keys: [code]bias[/code] and [code]name[/code]. + - [code]bias[/code] is the offset from UTC in minutes, since not all time zones are multiples of an hour from UTC. + - [code]name[/code] is the localized name of the time zone, according to the OS locale settings of the current user. </description> </method> <method name="get_unix_time_from_datetime_dict" qualifiers="const"> diff --git a/doc/classes/VideoStream.xml b/doc/classes/VideoStream.xml index aa4c91bac2..271330a598 100644 --- a/doc/classes/VideoStream.xml +++ b/doc/classes/VideoStream.xml @@ -8,6 +8,7 @@ </description> <tutorials> <link title="Playing videos">$DOCS_URL/tutorials/animation/playing_videos.html</link> + <link title="Runtime file loading and saving">$DOCS_URL/tutorials/io/runtime_file_loading_and_saving.html</link> </tutorials> <methods> <method name="_instantiate_playback" qualifiers="virtual"> diff --git a/doc/classes/VideoStreamPlayer.xml b/doc/classes/VideoStreamPlayer.xml index 0d8776b0b7..f903f171d1 100644 --- a/doc/classes/VideoStreamPlayer.xml +++ b/doc/classes/VideoStreamPlayer.xml @@ -6,7 +6,6 @@ <description> A control used for playback of [VideoStream] resources. Supported video formats are [url=https://www.theora.org/]Ogg Theora[/url] ([code].ogv[/code], [VideoStreamTheora]) and any format exposed via a GDExtension plugin. - [b]Note:[/b] Due to a bug, VideoStreamPlayer does not support localization remapping yet. [b]Warning:[/b] On Web, video playback [i]will[/i] perform poorly due to missing architecture-specific assembly optimizations. </description> <tutorials> diff --git a/doc/classes/Viewport.xml b/doc/classes/Viewport.xml index 0a3ecef39b..6e521c9e14 100644 --- a/doc/classes/Viewport.xml +++ b/doc/classes/Viewport.xml @@ -75,7 +75,7 @@ <return type="int" enum="Viewport.PositionalShadowAtlasQuadrantSubdiv" /> <param index="0" name="quadrant" type="int" /> <description> - Returns the [enum PositionalShadowAtlasQuadrantSubdiv] of the specified quadrant. + Returns the positional shadow atlas quadrant subdivision of the specified quadrant. </description> </method> <method name="get_render_info"> @@ -128,6 +128,13 @@ Returns the [Control] having the focus within this viewport. If no [Control] has the focus, returns null. </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. + 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> <method name="gui_is_drag_successful" qualifiers="const"> <return type="bool" /> <description> @@ -258,11 +265,8 @@ <member name="debug_draw" type="int" setter="set_debug_draw" getter="get_debug_draw" enum="Viewport.DebugDraw" default="0"> The overlay mode for test rendered geometry in debug purposes. </member> - <member name="disable_2d" type="bool" setter="set_disable_2d" getter="is_2d_disabled" default="false"> - If [code]true[/code], disables 2D rendering while keeping 3D rendering. See also [member disable_3d]. - </member> <member name="disable_3d" type="bool" setter="set_disable_3d" getter="is_3d_disabled" default="false"> - If [code]true[/code], disables 3D rendering while keeping 2D rendering. See also [member disable_2d]. + Disable 3D rendering (but keep 2D rendering). </member> <member name="fsr_sharpness" type="float" setter="set_fsr_sharpness" getter="get_fsr_sharpness" default="0.2"> Determines how sharp the upscaled image will be when using the FSR upscaling mode. Sharpness halves with every whole number. Values go from 0.0 (sharpest) to 2.0. Values above 2.0 won't make a visible difference. @@ -563,16 +567,18 @@ Draws the internal resolution buffer of the scene before post-processing is applied. </constant> <constant name="DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_NEAREST" value="0" enum="DefaultCanvasItemTextureFilter"> - The texture filter reads from the nearest pixel only. The simplest and fastest method of filtering, but the texture will look pixelized. + The texture filter reads from the nearest pixel only. This makes the texture look pixelated from up close, and grainy from a distance (due to mipmaps not being sampled). </constant> <constant name="DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_LINEAR" value="1" enum="DefaultCanvasItemTextureFilter"> - The texture filter blends between the nearest 4 pixels. Use this when you want to avoid a pixelated style, but do not want mipmaps. + The texture filter blends between the nearest 4 pixels. This makes the texture look smooth from up close, and grainy from a distance (due to mipmaps not being sampled). </constant> <constant name="DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS" value="2" enum="DefaultCanvasItemTextureFilter"> - The texture filter reads from the nearest pixel in the nearest mipmap. The fastest way to read from textures with mipmaps. + The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]). This makes the texture look smooth from up close, and smooth from a distance. + Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to [Camera2D] zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. </constant> <constant name="DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS" value="3" enum="DefaultCanvasItemTextureFilter"> - The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps. + The texture filter reads from the nearest pixel and blends between the nearest 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]). This makes the texture look pixelated from up close, and smooth from a distance. + Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to [Camera2D] zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. </constant> <constant name="DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_MAX" value="4" enum="DefaultCanvasItemTextureFilter"> Max value for [enum DefaultCanvasItemTextureFilter] enum. diff --git a/doc/classes/VisualShaderNodeTextureParameter.xml b/doc/classes/VisualShaderNodeTextureParameter.xml index 79a0657156..aa64016746 100644 --- a/doc/classes/VisualShaderNodeTextureParameter.xml +++ b/doc/classes/VisualShaderNodeTextureParameter.xml @@ -57,24 +57,26 @@ Sample the texture using the filter determined by the node this shader is attached to. </constant> <constant name="FILTER_NEAREST" value="1" enum="TextureFilter"> - The texture filter reads from the nearest pixel only. The simplest and fastest method of filtering, but the texture will look pixelized. + The texture filter reads from the nearest pixel only. This makes the texture look pixelated from up close, and grainy from a distance (due to mipmaps not being sampled). </constant> <constant name="FILTER_LINEAR" value="2" enum="TextureFilter"> - The texture filter blends between the nearest four pixels. Use this for most cases where you want to avoid a pixelated style. + The texture filter blends between the nearest 4 pixels. This makes the texture look smooth from up close, and grainy from a distance (due to mipmaps not being sampled). </constant> <constant name="FILTER_NEAREST_MIPMAP" value="3" enum="TextureFilter"> - The texture filter reads from the nearest pixel in the nearest mipmap. This is the fastest way to read from textures with mipmaps. + The texture filter reads from the nearest pixel and blends between the nearest 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]). This makes the texture look pixelated from up close, and smooth from a distance. + Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to [Camera2D] zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. </constant> <constant name="FILTER_LINEAR_MIPMAP" value="4" enum="TextureFilter"> - The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps. Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to [Camera2D] zoom), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. + The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]). This makes the texture look smooth from up close, and smooth from a distance. + Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to [Camera2D] zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. </constant> <constant name="FILTER_NEAREST_MIPMAP_ANISOTROPIC" value="5" enum="TextureFilter"> - The texture filter reads from the nearest pixel, but selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. - [b]Note:[/b] This texture filter is rarely useful in 2D projects. [constant FILTER_LINEAR_MIPMAP] is usually more appropriate. + The texture filter reads from the nearest pixel and blends between 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]) based on the angle between the surface and the camera view. This makes the texture look pixelated from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. + [b]Note:[/b] This texture filter is rarely useful in 2D projects. [constant FILTER_NEAREST_MIPMAP] is usually more appropriate in this case. </constant> <constant name="FILTER_LINEAR_MIPMAP_ANISOTROPIC" value="6" enum="TextureFilter"> - The texture filter blends between the nearest 4 pixels and selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. This is the slowest of the filtering options, but results in the highest quality texturing. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. - [b]Note:[/b] This texture filter is rarely useful in 2D projects. [constant FILTER_LINEAR_MIPMAP] is usually more appropriate. + The texture filter blends between the nearest 4 pixels and blends between 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]) based on the angle between the surface and the camera view. This makes the texture look smooth from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level]. + [b]Note:[/b] This texture filter is rarely useful in 2D projects. [constant FILTER_LINEAR_MIPMAP] is usually more appropriate in this case. </constant> <constant name="FILTER_MAX" value="7" enum="TextureFilter"> Represents the size of the [enum TextureFilter] enum. diff --git a/doc/classes/XRInterface.xml b/doc/classes/XRInterface.xml index 99d6e67e51..a7878378dd 100644 --- a/doc/classes/XRInterface.xml +++ b/doc/classes/XRInterface.xml @@ -119,7 +119,7 @@ <param index="0" name="mode" type="int" enum="XRInterface.EnvironmentBlendMode" /> <description> Sets the active environment blend mode. - [param mode] is the [enum XRInterface.EnvironmentBlendMode] starting with the next frame. + [param mode] is the environment blend mode starting with the next frame. [b]Note:[/b] Not all runtimes support all environment blend modes, so it is important to check this at startup. For example: [codeblock] func _ready(): diff --git a/doc/classes/XRInterfaceExtension.xml b/doc/classes/XRInterfaceExtension.xml index ea2bbf4cfb..b2c27bedf3 100644 --- a/doc/classes/XRInterfaceExtension.xml +++ b/doc/classes/XRInterfaceExtension.xml @@ -67,7 +67,7 @@ <method name="_get_play_area_mode" qualifiers="virtual const"> <return type="int" enum="XRInterface.PlayAreaMode" /> <description> - Returns the [enum XRInterface.PlayAreaMode] that sets up our play area. + Returns the play area mode that sets up our play area. </description> </method> <method name="_get_projection_for_view" qualifiers="virtual"> |