summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/classes/Array.xml26
-rw-r--r--doc/classes/Callable.xml4
-rw-r--r--doc/classes/CanvasGroup.xml1
-rw-r--r--doc/classes/Decal.xml1
-rw-r--r--doc/classes/DisplayServer.xml8
-rw-r--r--doc/classes/EditorImportPlugin.xml10
-rw-r--r--doc/classes/FontFile.xml17
-rw-r--r--doc/classes/FontVariation.xml10
-rw-r--r--doc/classes/Node.xml4
-rw-r--r--doc/classes/Object.xml2
-rw-r--r--doc/classes/OmniLight3D.xml1
-rw-r--r--doc/classes/PrimitiveMesh.xml3
-rw-r--r--doc/classes/ProjectSettings.xml26
-rw-r--r--doc/classes/ReflectionProbe.xml1
-rw-r--r--doc/classes/RenderingServer.xml8
-rw-r--r--doc/classes/RichTextLabel.xml55
-rw-r--r--doc/classes/Signal.xml5
-rw-r--r--doc/classes/SpotLight3D.xml1
-rw-r--r--doc/classes/String.xml2
-rw-r--r--doc/classes/Variant.xml35
-rw-r--r--doc/classes/Viewport.xml4
-rw-r--r--doc/classes/XRInterface.xml37
22 files changed, 221 insertions, 40 deletions
diff --git a/doc/classes/Array.xml b/doc/classes/Array.xml
index 213a2254af..c4fec5a729 100644
--- a/doc/classes/Array.xml
+++ b/doc/classes/Array.xml
@@ -214,7 +214,7 @@
[b]Note:[/b] Calling this function is not the same as writing [code]array[-1][/code]. If the array is empty, accessing by index will pause project execution when running from the editor.
</description>
</method>
- <method name="bsearch">
+ <method name="bsearch" qualifiers="const">
<return type="int" />
<param index="0" name="value" type="Variant" />
<param index="1" name="before" type="bool" default="true" />
@@ -223,7 +223,7 @@
[b]Note:[/b] Calling [method bsearch] on an unsorted array results in unexpected behavior.
</description>
</method>
- <method name="bsearch_custom">
+ <method name="bsearch_custom" qualifiers="const">
<return type="int" />
<param index="0" name="value" type="Variant" />
<param index="1" name="func" type="Callable" />
@@ -276,7 +276,7 @@
array.fill(0) # Initialize the 10 elements to 0.
[/gdscript]
[csharp]
- var array = new Godot.Collections.Array{};
+ var array = new Godot.Collections.Array();
array.Resize(10);
array.Fill(0); // Initialize the 10 elements to 0.
[/csharp]
@@ -347,7 +347,7 @@
print(["inside", 7].has("7")) # False
[/gdscript]
[csharp]
- var arr = new Godot.Collections.Array{"inside", 7};
+ var arr = new Godot.Collections.Array { "inside", 7 };
// has is renamed to Contains
GD.Print(arr.Contains("inside")); // True
GD.Print(arr.Contains("outside")); // False
@@ -364,7 +364,7 @@
[/gdscript]
[csharp]
// As there is no "in" keyword in C#, you have to use Contains
- var array = new Godot.Collections.Array{2, 4, 6, 8};
+ var array = new Godot.Collections.Array { 2, 4, 6, 8 };
if (array.Contains(2))
{
GD.Print("Contains!");
@@ -454,10 +454,16 @@
<return type="Variant" />
<description>
Returns a random value from the target array.
- [codeblock]
+ [codeblocks]
+ [gdscript]
var array: Array[int] = [1, 2, 3, 4]
print(array.pick_random()) # Prints either of the four numbers.
- [/codeblock]
+ [/gdscript]
+ [csharp]
+ var array = new Godot.Collections.Array { 1, 2, 3, 4 };
+ GD.Print(array.PickRandom()); // Prints either of the four numbers.
+ [/csharp]
+ [/codeblocks]
</description>
</method>
<method name="pop_at">
@@ -566,7 +572,7 @@
Returns the slice of the [Array], from [param begin] (inclusive) to [param end] (exclusive), as a new [Array].
The absolute value of [param begin] and [param end] will be clamped to the array size, so the default value for [param end] makes it slice to the size of the array by default (i.e. [code]arr.slice(1)[/code] is a shorthand for [code]arr.slice(1, arr.size())[/code]).
If either [param begin] or [param end] are negative, they will be relative to the end of the array (i.e. [code]arr.slice(0, -2)[/code] is a shorthand for [code]arr.slice(0, arr.size() - 2)[/code]).
- If specified, [param step] is the relative index between source elements. It can be negative, then [param begin] must be higher than [param end]. For example, [code][0, 1, 2, 3, 4, 5].slice(5, 1, -2)[/code] returns [code][5, 3][/code]).
+ If specified, [param step] is the relative index between source elements. It can be negative, then [param begin] must be higher than [param end]. For example, [code][0, 1, 2, 3, 4, 5].slice(5, 1, -2)[/code] returns [code][5, 3][/code].
If [param deep] is true, each element will be copied by value rather than by reference.
</description>
</method>
@@ -583,7 +589,9 @@
print(strings) # Prints [string1, string10, string11, string2]
[/gdscript]
[csharp]
- // There is no sort support for Godot.Collections.Array
+ var strings = new Godot.Collections.Array { "string1", "string2", "string10", "string11" };
+ strings.Sort();
+ GD.Print(strings); // Prints [string1, string10, string11, string2]
[/csharp]
[/codeblocks]
To perform natural order sorting, you can use [method sort_custom] with [method String.naturalnocasecmp_to] as follows:
diff --git a/doc/classes/Callable.xml b/doc/classes/Callable.xml
index 8fc44d7536..50be9b86bf 100644
--- a/doc/classes/Callable.xml
+++ b/doc/classes/Callable.xml
@@ -173,14 +173,14 @@
<method name="rpc" qualifiers="vararg const">
<return type="void" />
<description>
- Perform an RPC (Remote Procedure Call). This is used for multiplayer and is normally not available, unless the function being called has been marked as [i]RPC[/i]. Calling this method on unsupported functions will result in an error.
+ Perform an RPC (Remote Procedure Call). This is used for multiplayer and is normally not available, unless the function being called has been marked as [i]RPC[/i]. Calling this method on unsupported functions will result in an error. See [method Node.rpc].
</description>
</method>
<method name="rpc_id" qualifiers="vararg const">
<return type="void" />
<param index="0" name="peer_id" type="int" />
<description>
- Perform an RPC (Remote Procedure Call) on a specific peer ID (see multiplayer documentation for reference). This is used for multiplayer and is normally not available unless the function being called has been marked as [i]RPC[/i]. Calling this method on unsupported functions will result in an error.
+ Perform an RPC (Remote Procedure Call) on a specific peer ID (see multiplayer documentation for reference). This is used for multiplayer and is normally not available unless the function being called has been marked as [i]RPC[/i]. Calling this method on unsupported functions will result in an error. See [method Node.rpc_id].
</description>
</method>
<method name="unbind" qualifiers="const">
diff --git a/doc/classes/CanvasGroup.xml b/doc/classes/CanvasGroup.xml
index 6eeff8fef3..45f77ba484 100644
--- a/doc/classes/CanvasGroup.xml
+++ b/doc/classes/CanvasGroup.xml
@@ -8,6 +8,7 @@
[b]Note:[/b] The [CanvasGroup] uses a custom shader to read from the backbuffer to draw its children. Assigning a [Material] to the [CanvasGroup] overrides the builtin shader. To duplicate the behavior of the builtin shader in a custom [Shader] use the following:
[codeblock]
shader_type canvas_item;
+ render_mode unshaded;
uniform sampler2D screen_texture : hint_screen_texture, repeat_disable, filter_nearest;
diff --git a/doc/classes/Decal.xml b/doc/classes/Decal.xml
index fb8bc18c1a..b63f6e7252 100644
--- a/doc/classes/Decal.xml
+++ b/doc/classes/Decal.xml
@@ -8,6 +8,7 @@
They are made of an [AABB] and a group of [Texture2D]s specifying [Color], normal, ORM (ambient occlusion, roughness, metallic), and emission. Decals are projected within their [AABB] so altering the orientation of the Decal affects the direction in which they are projected. By default, Decals are projected down (i.e. from positive Y to negative Y).
The [Texture2D]s associated with the Decal are automatically stored in a texture atlas which is used for drawing the decals so all decals can be drawn at once. Godot uses clustered decals, meaning they are stored in cluster data and drawn when the mesh is drawn, they are not drawn as a post-processing effect after.
[b]Note:[/b] Decals cannot affect an underlying material's transparency, regardless of its transparency mode (alpha blend, alpha scissor, alpha hash, opaque pre-pass). This means translucent or transparent areas of a material will remain translucent or transparent even if an opaque decal is applied on them.
+ [b]Note:[/b] When using the Mobile rendering method, decals will only correctly affect meshes whose visibility AABB intersects with the decal's AABB. If using a shader to deform the mesh in a way that makes it go outside its AABB, [member GeometryInstance3D.extra_cull_margin] must be increased on the mesh. Otherwise, the decal may not be visible on the mesh.
</description>
<tutorials>
</tutorials>
diff --git a/doc/classes/DisplayServer.xml b/doc/classes/DisplayServer.xml
index 6f4a7fc13d..55ba1f4f0c 100644
--- a/doc/classes/DisplayServer.xml
+++ b/doc/classes/DisplayServer.xml
@@ -1325,6 +1325,7 @@
<param index="1" name="window_id" type="int" default="0" />
<description>
Sets the maximum size of the window specified by [param window_id] in pixels. Normally, the user will not be able to drag the window to make it smaller than the specified size. See also [method window_get_max_size].
+ [b]Note:[/b] It's recommended to change this value using [member Window.max_size] instead.
[b]Note:[/b] Using third-party tools, it is possible for users to disable window geometry restrictions and therefore bypass this limit.
</description>
</method>
@@ -1334,6 +1335,7 @@
<param index="1" name="window_id" type="int" default="0" />
<description>
Sets the minimum size for the given window to [param min_size] (in pixels). Normally, the user will not be able to drag the window to make it larger than the specified size. See also [method window_get_min_size].
+ [b]Note:[/b] It's recommended to change this value using [member Window.min_size] instead.
[b]Note:[/b] By default, the main window has a minimum size of [code]Vector2i(64, 64)[/code]. This prevents issues that can arise when the window is resized to a near-zero size.
[b]Note:[/b] Using third-party tools, it is possible for users to disable window geometry restrictions and therefore bypass this limit.
</description>
@@ -1403,6 +1405,7 @@
+-------------+ +-------+
[/codeblock]
See also [method window_get_position] and [method window_set_size].
+ [b]Note:[/b] It's recommended to change this value using [member Window.position] instead.
</description>
</method>
<method name="window_set_rect_changed_callback">
@@ -1419,6 +1422,7 @@
<param index="1" name="window_id" type="int" default="0" />
<description>
Sets the size of the given window to [param size] (in pixels). See also [method window_get_size] and [method window_get_position].
+ [b]Note:[/b] It's recommended to change this value using [member Window.size] instead.
</description>
</method>
<method name="window_set_title">
@@ -1427,6 +1431,7 @@
<param index="1" name="window_id" type="int" default="0" />
<description>
Sets the title of the given window to [param title].
+ [b]Note:[/b] It's recommended to change this value using [member Window.title] instead.
[b]Note:[/b] Avoid changing the window title every frame, as this can cause performance issues on certain window managers. Try to change the window title only a few times per second at most.
</description>
</method>
@@ -1436,7 +1441,8 @@
<param index="1" name="parent_window_id" type="int" />
<description>
Sets window transient parent. Transient window is will be destroyed with its transient parent and will return focus to their parent when closed. The transient window is displayed on top of a non-exclusive full-screen parent window. Transient windows can't enter full-screen mode.
- Note that behavior might be different depending on the platform.
+ [b]Note:[/b] It's recommended to change this value using [member Window.transient] instead.
+ [b]Note:[/b] The behavior might be different depending on the platform.
</description>
</method>
<method name="window_set_vsync_mode">
diff --git a/doc/classes/EditorImportPlugin.xml b/doc/classes/EditorImportPlugin.xml
index 6a976d218f..66b61f187e 100644
--- a/doc/classes/EditorImportPlugin.xml
+++ b/doc/classes/EditorImportPlugin.xml
@@ -227,5 +227,15 @@
This method must be overridden to do the actual importing work. See this class' description for an example of overriding this method.
</description>
</method>
+ <method name="append_import_external_resource">
+ <return type="int" enum="Error" />
+ <param index="0" name="path" type="String" />
+ <param index="1" name="custom_options" type="Dictionary" default="{}" />
+ <param index="2" name="custom_importer" type="String" default="&quot;&quot;" />
+ <param index="3" name="generator_parameters" type="Variant" default="null" />
+ <description>
+ This function can only be called during the [method _import] callback and it allows manually importing resources from it. This is useful when the imported file generates external resources that require importing (as example, images). Custom parameters for the ".import" file can be passed via the [param custom_options]. Additionally, in cases where multiple importers can handle a file, the [param custom_importer] ca be specified to force a specific one. This function performs a resource import and returns immediately with a success or error code. [param generator_parameters] defines optional extra metadata which will be stored as [code]generator_parameters[/code] in the [code]remap[/code] section of the [code].import[/code] file, for example to store a md5 hash of the source data.
+ </description>
+ </method>
</methods>
</class>
diff --git a/doc/classes/FontFile.xml b/doc/classes/FontFile.xml
index 69a7627774..a349c2b7b7 100644
--- a/doc/classes/FontFile.xml
+++ b/doc/classes/FontFile.xml
@@ -17,13 +17,13 @@
[codeblocks]
[gdscript]
var f = load("res://BarlowCondensed-Bold.ttf")
- $"Label".set("custom_fonts/font", f)
- $"Label".set("custom_fonts/font_size", 64)
+ $Label.add_theme_font_override("font", f)
+ $Label.add_theme_font_size_override("font_size", 64)
[/gdscript]
[csharp]
var f = ResourceLoader.Load&lt;FontFile&gt;("res://BarlowCondensed-Bold.ttf");
- GetNode("Label").Set("custom_fonts/font", f);
- GetNode("Label").Set("custom_font_sizes/font_size", 64);
+ GetNode("Label").AddThemeFontOverride("font", f);
+ GetNode("Label").AddThemeFontSizeOverride("font_size", 64);
[/csharp]
[/codeblocks]
</description>
@@ -88,6 +88,7 @@
<param index="0" name="cache_index" type="int" />
<param index="1" name="size" type="int" />
<description>
+ Returns the font descent (number of pixels below the baseline).
</description>
</method>
<method name="get_cache_scale" qualifiers="const">
@@ -95,6 +96,7 @@
<param index="0" name="cache_index" type="int" />
<param index="1" name="size" type="int" />
<description>
+ Returns scaling factor of the color bitmap font.
</description>
</method>
<method name="get_cache_underline_position" qualifiers="const">
@@ -102,6 +104,7 @@
<param index="0" name="cache_index" type="int" />
<param index="1" name="size" type="int" />
<description>
+ Returns pixel offset of the underline below the baseline.
</description>
</method>
<method name="get_cache_underline_thickness" qualifiers="const">
@@ -109,6 +112,7 @@
<param index="0" name="cache_index" type="int" />
<param index="1" name="size" type="int" />
<description>
+ Returns thickness of the underline in pixels.
</description>
</method>
<method name="get_embolden" qualifiers="const">
@@ -377,6 +381,7 @@
<param index="1" name="size" type="int" />
<param index="2" name="ascent" type="float" />
<description>
+ Sets the font ascent (number of pixels above the baseline).
</description>
</method>
<method name="set_cache_descent">
@@ -385,6 +390,7 @@
<param index="1" name="size" type="int" />
<param index="2" name="descent" type="float" />
<description>
+ Sets the font descent (number of pixels below the baseline).
</description>
</method>
<method name="set_cache_scale">
@@ -393,6 +399,7 @@
<param index="1" name="size" type="int" />
<param index="2" name="scale" type="float" />
<description>
+ Sets scaling factor of the color bitmap font.
</description>
</method>
<method name="set_cache_underline_position">
@@ -401,6 +408,7 @@
<param index="1" name="size" type="int" />
<param index="2" name="underline_position" type="float" />
<description>
+ Sets pixel offset of the underline below the baseline.
</description>
</method>
<method name="set_cache_underline_thickness">
@@ -409,6 +417,7 @@
<param index="1" name="size" type="int" />
<param index="2" name="underline_thickness" type="float" />
<description>
+ Sets thickness of the underline in pixels.
</description>
</method>
<method name="set_embolden">
diff --git a/doc/classes/FontVariation.xml b/doc/classes/FontVariation.xml
index e0fad126b9..5bc2606adb 100644
--- a/doc/classes/FontVariation.xml
+++ b/doc/classes/FontVariation.xml
@@ -10,16 +10,16 @@
[gdscript]
var fv = FontVariation.new()
fv.set_base_font(load("res://BarlowCondensed-Regular.ttf"))
- fv.set_variation_embolden(1.2);
- $"Label".set("custom_fonts/font", fv)
- $"Label".set("custom_fonts/font_size", 64)
+ fv.set_variation_embolden(1.2)
+ $Label.add_theme_font_override("font", fv)
+ $Label.add_theme_font_size_override("font_size", 64)
[/gdscript]
[csharp]
var fv = new FontVariation();
fv.SetBaseFont(ResourceLoader.Load&lt;FontFile&gt;("res://BarlowCondensed-Regular.ttf"));
fv.SetVariationEmbolden(1.2);
- GetNode("Label").Set("custom_fonts/font", fv);
- GetNode("Label").Set("custom_font_sizes/font_size", 64);
+ GetNode("Label").AddThemeFontOverride("font", fv);
+ GetNode("Label").AddThemeFontSizeOverride("font_size", 64);
[/csharp]
[/codeblocks]
</description>
diff --git a/doc/classes/Node.xml b/doc/classes/Node.xml
index 7c40c189c0..bc43f228a7 100644
--- a/doc/classes/Node.xml
+++ b/doc/classes/Node.xml
@@ -648,7 +648,7 @@
<return type="int" enum="Error" />
<param index="0" name="method" type="StringName" />
<description>
- Sends a remote procedure call request for the given [param method] to peers on the network (and locally), optionally sending all additional arguments as arguments to the method called by the RPC. The call request will only be received by nodes with the same [NodePath], including the exact same node name. Behavior depends on the RPC configuration for the given method, see [method rpc_config]. Methods are not exposed to RPCs by default. Returns [code]null[/code].
+ Sends a remote procedure call request for the given [param method] to peers on the network (and locally), optionally sending all additional arguments as arguments to the method called by the RPC. The call request will only be received by nodes with the same [NodePath], including the exact same node name. Behavior depends on the RPC configuration for the given method, see [method rpc_config] and [annotation @GDScript.@rpc]. Methods are not exposed to RPCs by default. Returns [code]null[/code].
[b]Note:[/b] You can only safely use RPCs on clients after you received the [code]connected_to_server[/code] signal from the [MultiplayerAPI]. You also need to keep track of the connection state, either by the [MultiplayerAPI] signals like [code]server_disconnected[/code] or by checking [code]get_multiplayer().peer.get_connection_status() == CONNECTION_CONNECTED[/code].
</description>
</method>
@@ -666,7 +666,7 @@
channel = 0,
}
[/codeblock]
- See [enum MultiplayerAPI.RPCMode] and [enum MultiplayerPeer.TransferMode]. An alternative is annotating methods and properties with the corresponding annotation ([code]@rpc("any")[/code], [code]@rpc("authority")[/code]). By default, methods are not exposed to networking (and RPCs).
+ See [enum MultiplayerAPI.RPCMode] and [enum MultiplayerPeer.TransferMode]. An alternative is annotating methods and properties with the corresponding [annotation @GDScript.@rpc] annotation ([code]@rpc("any_peer")[/code], [code]@rpc("authority")[/code]). By default, methods are not exposed to networking (and RPCs).
</description>
</method>
<method name="rpc_id" qualifiers="vararg">
diff --git a/doc/classes/Object.xml b/doc/classes/Object.xml
index e30ff6be19..ab7ae82875 100644
--- a/doc/classes/Object.xml
+++ b/doc/classes/Object.xml
@@ -639,7 +639,7 @@
<description>
Returns an [Array] of connections for the given [param signal] name. Each connection is represented as a [Dictionary] that contains three entries:
- [code]signal[/code] is a reference to the [Signal];
- - [code]callable[/code] is a reference to the [Callable];
+ - [code]callable[/code] is a reference to the connected [Callable];
- [code]flags[/code] is a combination of [enum ConnectFlags].
</description>
</method>
diff --git a/doc/classes/OmniLight3D.xml b/doc/classes/OmniLight3D.xml
index f71c81e713..c0e10574c8 100644
--- a/doc/classes/OmniLight3D.xml
+++ b/doc/classes/OmniLight3D.xml
@@ -5,6 +5,7 @@
</brief_description>
<description>
An Omnidirectional light is a type of [Light3D] that emits light in all directions. The light is attenuated by distance and this attenuation can be configured by changing its energy, radius, and attenuation parameters.
+ [b]Note:[/b] When using the Mobile or Compatibility rendering methods, omni lights will only correctly affect meshes whose visibility AABB intersects with the light's AABB. If using a shader to deform the mesh in a way that makes it go outside its AABB, [member GeometryInstance3D.extra_cull_margin] must be increased on the mesh. Otherwise, the light may not be visible on the mesh.
</description>
<tutorials>
<link title="3D lights and shadows">$DOCS_URL/tutorials/3d/lights_and_shadows.html</link>
diff --git a/doc/classes/PrimitiveMesh.xml b/doc/classes/PrimitiveMesh.xml
index b1c8907d8e..b98590d10c 100644
--- a/doc/classes/PrimitiveMesh.xml
+++ b/doc/classes/PrimitiveMesh.xml
@@ -48,7 +48,8 @@
The current [Material] of the primitive mesh.
</member>
<member name="uv2_padding" type="float" setter="set_uv2_padding" getter="get_uv2_padding" default="2.0">
- If [member add_uv2] is set, specifies the padding in pixels applied along seams of the mesh. If at generation the size of the lightmap texture can't be determined, the UVs are calculated assuming a texture size of 1024x1024.
+ If [member add_uv2] is set, specifies the padding in pixels applied along seams of the mesh. Lower padding values allow making better use of the lightmap texture (resulting in higher texel density), but may introduce visible lightmap bleeding along edges.
+ If the size of the lightmap texture can't be determined when generating the mesh, UV2 is calculated assuming a texture size of 1024x1024.
</member>
</members>
</class>
diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml
index e429759e93..c30747eac1 100644
--- a/doc/classes/ProjectSettings.xml
+++ b/doc/classes/ProjectSettings.xml
@@ -60,6 +60,18 @@
Clears the whole configuration (not recommended, may break things).
</description>
</method>
+ <method name="get_global_class_list">
+ <return type="Dictionary[]" />
+ <description>
+ Returns an [Array] of registered global classes. Each global class is represented as a [Dictionary] that contains the following entries:
+ - [code]base[/code] is a name of the base class;
+ - [code]class[/code] is a name of the registered global class;
+ - [code]icon[/code] is a path to a custom icon of the global class, if it has any;
+ - [code]language[/code] is a name of a programming language in which the global class is written;
+ - [code]path[/code] is a path to a file containing the global class.
+ [b]Note:[/b] Both the script and the icon paths are local to the project filesystem, i.e. they start with [code]res://[/code].
+ </description>
+ </method>
<method name="get_order" qualifiers="const">
<return type="int" />
<param index="0" name="name" type="String" />
@@ -405,9 +417,15 @@
<member name="debug/gdscript/warnings/function_used_as_property" type="int" setter="" getter="" default="1">
When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when using a function as if it is a property.
</member>
+ <member name="debug/gdscript/warnings/get_node_default_without_onready" type="int" setter="" getter="" default="2">
+ When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when [method Node.get_node] (or the shorthand [code]$[/code]) is used as default value of a class variable without the [code]@onready[/code] annotation.
+ </member>
<member name="debug/gdscript/warnings/incompatible_ternary" type="int" setter="" getter="" default="1">
When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when a ternary operator may emit values with incompatible types.
</member>
+ <member name="debug/gdscript/warnings/inference_on_variant" type="int" setter="" getter="" default="2">
+ When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when a static inferred type uses a [Variant] as initial value, which makes the static type to also be Variant.
+ </member>
<member name="debug/gdscript/warnings/int_as_enum_without_cast" type="int" setter="" getter="" default="1">
When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when trying to use an integer as an enum without an explicit cast.
</member>
@@ -420,6 +438,12 @@
<member name="debug/gdscript/warnings/narrowing_conversion" type="int" setter="" getter="" default="1">
When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when passing a floating-point value to a function that expects an integer (it will be converted and lose precision).
</member>
+ <member name="debug/gdscript/warnings/native_method_override" type="int" setter="" getter="" default="2">
+ When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when a method in the script overrides a native method, because it may not behave as expected.
+ </member>
+ <member name="debug/gdscript/warnings/onready_with_export" type="int" setter="" getter="" default="2">
+ When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when the [code]@onready[/code] annotation is used together with the [code]@export[/code] annotation, since it may not behave as expected.
+ </member>
<member name="debug/gdscript/warnings/property_used_as_function" type="int" setter="" getter="" default="1">
When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when using a property as if it is a function.
</member>
@@ -477,7 +501,7 @@
<member name="debug/gdscript/warnings/unsafe_property_access" type="int" setter="" getter="" default="0">
When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when accessing a property whose presence is not guaranteed at compile-time in the class.
</member>
- <member name="debug/gdscript/warnings/unsafe_void_return" type="int" setter="" getter="" default="0">
+ <member name="debug/gdscript/warnings/unsafe_void_return" type="int" setter="" getter="" default="1">
When set to [code]warn[/code] or [code]error[/code], produces a warning or an error respectively when returning a call from a [code]void[/code] function when such call cannot be guaranteed to be also [code]void[/code].
</member>
<member name="debug/gdscript/warnings/unused_local_constant" type="int" setter="" getter="" default="1">
diff --git a/doc/classes/ReflectionProbe.xml b/doc/classes/ReflectionProbe.xml
index fa0b1ab00b..e912925cd2 100644
--- a/doc/classes/ReflectionProbe.xml
+++ b/doc/classes/ReflectionProbe.xml
@@ -7,6 +7,7 @@
Captures its surroundings as a cubemap, and stores versions of it with increasing levels of blur to simulate different material roughnesses.
The [ReflectionProbe] is used to create high-quality reflections at a low performance cost (when [member update_mode] is [constant UPDATE_ONCE]). [ReflectionProbe]s can be blended together and with the rest of the scene smoothly. [ReflectionProbe]s can also be combined with [VoxelGI], SDFGI ([member Environment.sdfgi_enabled]) and screen-space reflections ([member Environment.ssr_enabled]) to get more accurate reflections in specific areas. [ReflectionProbe]s render all objects within their [member cull_mask], so updating them can be quite expensive. It is best to update them once with the important static objects and then leave them as-is.
[b]Note:[/b] Unlike [VoxelGI] and SDFGI, [ReflectionProbe]s only source their environment from a [WorldEnvironment] node. If you specify an [Environment] resource within a [Camera3D] node, it will be ignored by the [ReflectionProbe]. This can lead to incorrect lighting within the [ReflectionProbe].
+ [b]Note:[/b] When using the Mobile rendering method, reflection probes will only correctly affect meshes whose visibility AABB intersects with the reflection probe's AABB. If using a shader to deform the mesh in a way that makes it go outside its AABB, [member GeometryInstance3D.extra_cull_margin] must be increased on the mesh. Otherwise, the reflection probe may not be visible on the mesh.
</description>
<tutorials>
<link title="Reflection probes">$DOCS_URL/tutorials/3d/reflection_probes.html</link>
diff --git a/doc/classes/RenderingServer.xml b/doc/classes/RenderingServer.xml
index 4e3a1bc0ef..e5ab3271dc 100644
--- a/doc/classes/RenderingServer.xml
+++ b/doc/classes/RenderingServer.xml
@@ -630,6 +630,14 @@
Sets a light occluder's [Transform2D].
</description>
</method>
+ <method name="canvas_light_set_blend_mode">
+ <return type="void" />
+ <param index="0" name="light" type="RID" />
+ <param index="1" name="mode" type="int" enum="RenderingServer.CanvasLightBlendMode" />
+ <description>
+ Sets the blend mode for the given canvas light. See [enum CanvasLightBlendMode] for options. Equivalent to [member Light2D.blend_mode].
+ </description>
+ </method>
<method name="canvas_light_set_color">
<return type="void" />
<param index="0" name="light" type="RID" />
diff --git a/doc/classes/RichTextLabel.xml b/doc/classes/RichTextLabel.xml
index 1ecc8a1d4e..49bb65b64d 100644
--- a/doc/classes/RichTextLabel.xml
+++ b/doc/classes/RichTextLabel.xml
@@ -106,6 +106,45 @@
<return type="PopupMenu" />
<description>
Returns the [PopupMenu] of this [RichTextLabel]. By default, this menu is displayed when right-clicking on the [RichTextLabel].
+ You can add custom menu items or remove standard ones. Make sure your IDs don't conflict with the standard ones (see [enum MenuItems]). For example:
+ [codeblocks]
+ [gdscript]
+ func _ready():
+ var menu = get_menu()
+ # Remove "Select All" item.
+ menu.remove_item(MENU_SELECT_ALL)
+ # Add custom items.
+ menu.add_separator()
+ menu.add_item("Duplicate Text", MENU_MAX + 1)
+ # Connect callback.
+ menu.id_pressed.connect(_on_item_pressed)
+
+ func _on_item_pressed(id):
+ if id == MENU_MAX + 1:
+ add_text("\n" + get_parsed_text())
+ [/gdscript]
+ [csharp]
+ public override void _Ready()
+ {
+ var menu = GetMenu();
+ // Remove "Select All" item.
+ menu.RemoveItem(RichTextLabel.MenuItems.SelectAll);
+ // Add custom items.
+ menu.AddSeparator();
+ menu.AddItem("Duplicate Text", RichTextLabel.MenuItems.Max + 1);
+ // Add event handler.
+ menu.IdPressed += OnItemPressed;
+ }
+
+ public void OnItemPressed(int id)
+ {
+ if (id == TextEdit.MenuItems.Max + 1)
+ {
+ AddText("\n" + GetParsedText());
+ }
+ }
+ [/csharp]
+ [/codeblocks]
[b]Warning:[/b] This is a required internal node, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their [member Window.visible] property.
</description>
</method>
@@ -193,6 +232,13 @@
If [member threaded] is enabled, returns [code]true[/code] if the background thread has finished text processing, otherwise always return [code]true[/code].
</description>
</method>
+ <method name="menu_option">
+ <return type="void" />
+ <param index="0" name="option" type="int" />
+ <description>
+ Executes a given action as defined in the [enum MenuItems] enum.
+ </description>
+ </method>
<method name="newline">
<return type="void" />
<description>
@@ -633,6 +679,15 @@
</constant>
<constant name="ITEM_CUSTOMFX" value="26" enum="ItemType">
</constant>
+ <constant name="MENU_COPY" value="0" enum="MenuItems">
+ Copies the selected text.
+ </constant>
+ <constant name="MENU_SELECT_ALL" value="1" enum="MenuItems">
+ Selects the whole [RichTextLabel] text.
+ </constant>
+ <constant name="MENU_MAX" value="2" enum="MenuItems">
+ Represents the size of the [enum MenuItems] enum.
+ </constant>
</constants>
<theme_items>
<theme_item name="default_color" data_type="color" type="Color" default="Color(1, 1, 1, 1)">
diff --git a/doc/classes/Signal.xml b/doc/classes/Signal.xml
index 71905e8b2e..cdbeba0220 100644
--- a/doc/classes/Signal.xml
+++ b/doc/classes/Signal.xml
@@ -85,7 +85,10 @@
<method name="get_connections" qualifiers="const">
<return type="Array" />
<description>
- Returns the list of [Callable]s connected to this signal.
+ Returns an [Array] of connections for this signal. Each connection is represented as a [Dictionary] that contains three entries:
+ - [code]signal[/code] is a reference to this signal;
+ - [code]callable[/code] is a reference to the connected [Callable];
+ - [code]flags[/code] is a combination of [enum Object.ConnectFlags].
</description>
</method>
<method name="get_name" qualifiers="const">
diff --git a/doc/classes/SpotLight3D.xml b/doc/classes/SpotLight3D.xml
index 59d36aefab..9dff742748 100644
--- a/doc/classes/SpotLight3D.xml
+++ b/doc/classes/SpotLight3D.xml
@@ -5,6 +5,7 @@
</brief_description>
<description>
A Spotlight is a type of [Light3D] node that emits lights in a specific direction, in the shape of a cone. The light is attenuated through the distance. This attenuation can be configured by changing the energy, radius and attenuation parameters of [Light3D].
+ [b]Note:[/b] When using the Mobile or Compatibility rendering methods, spot lights will only correctly affect meshes whose visibility AABB intersects with the light's AABB. If using a shader to deform the mesh in a way that makes it go outside its AABB, [member GeometryInstance3D.extra_cull_margin] must be increased on the mesh. Otherwise, the light may not be visible on the mesh.
</description>
<tutorials>
<link title="3D lights and shadows">$DOCS_URL/tutorials/3d/lights_and_shadows.html</link>
diff --git a/doc/classes/String.xml b/doc/classes/String.xml
index 143e1f23e9..792cd38741 100644
--- a/doc/classes/String.xml
+++ b/doc/classes/String.xml
@@ -529,7 +529,7 @@
<return type="bool" />
<param index="0" name="expr" type="String" />
<description>
- Does a simple expression match, where [code]*[/code] matches zero or more arbitrary characters and [code]?[/code] matches any single character except a period ([code].[/code]). An empty string or empty expression always evaluates to [code]false[/code].
+ Does a simple expression match (also called "glob" or "globbing"), where [code]*[/code] matches zero or more arbitrary characters and [code]?[/code] matches any single character except a period ([code].[/code]). An empty string or empty expression always evaluates to [code]false[/code].
</description>
</method>
<method name="matchn" qualifiers="const">
diff --git a/doc/classes/Variant.xml b/doc/classes/Variant.xml
index 5416468ab6..390722b7e5 100644
--- a/doc/classes/Variant.xml
+++ b/doc/classes/Variant.xml
@@ -14,16 +14,21 @@
# bar = "Uh oh! I can't make static variables become a different type!"
[/gdscript]
[csharp]
- // ... but C# is statically typed. Once a variable has a type it cannot be changed. However you can use the var keyword in methods to let the compiler decide the type automatically.
- var foo = 2; // Foo is a 32-bit integer (int). Be cautious, integers in GDScript are 64-bit and the direct C# equivalent is "long".
+ // C# is statically typed. Once a variable has a type it cannot be changed. You can use the `var` keyword to let the compiler infer the type automatically.
+ var foo = 2; // Foo is a 32-bit integer (int). Be cautious, integers in GDScript are 64-bit and the direct C# equivalent is `long`.
// foo = "foo was and will always be an integer. It cannot be turned into a string!";
var boo = "Boo is a string!";
- var ref = new Reference(); // var is especially useful when used together with a constructor.
+ var ref = new RefCounted(); // var is especially useful when used together with a constructor.
+
+ // Godot also provides a Variant type that works like an union of all the Variant-compatible types.
+ Variant fooVar = 2; // fooVar is dynamically an integer (stored as a `long` in the Variant type).
+ fooVar = "Now fooVar is a string!";
+ fooVar = new RefCounted(); // fooVar is a GodotObject.
[/csharp]
[/codeblocks]
Godot tracks all scripting API variables within Variants. Without even realizing it, you use Variants all the time. When a particular language enforces its own rules for keeping data typed, then that language is applying its own custom logic over the base Variant scripting API.
- GDScript automatically wrap values in them. It keeps all data in plain Variants by default and then optionally enforces custom static typing rules on variable types.
- - C# is statically typed, but uses the Mono [code]object[/code] type in place of Godot's Variant class when it needs to represent a dynamic value. [code]object[/code] is the Mono runtime's equivalent of the same concept.
+ - C# is statically typed, but uses its own implementation of the [code]Variant[/code] type in place of Godot's Variant class when it needs to represent a dynamic value. A [code]Variant[/code] can be assigned any compatible type implicitly but converting requires an explicit cast.
The global [method @GlobalScope.typeof] function returns the enumerated value of the Variant type stored in the current variable (see [enum Variant.Type]).
[codeblocks]
[gdscript]
@@ -38,18 +43,24 @@
# To get the name of the underlying Object type, you need the `get_class()` method.
print("foo is a(n) %s" % foo.get_class()) # inject the class name into a formatted string.
# Note also that there is not yet any way to get a script's `class_name` string easily.
- # To fetch that value, you can parse the [code]res://.godot/global_script_class_cache.cfg[/code] file with the [ConfigFile] API.
+ # To fetch that value, you can use [member ProjectSettings.get_global_class_list].
# Open your project.godot file to see it up close.
[/gdscript]
[csharp]
- int foo = 2;
- if (foo == null)
+ Variant foo = 2;
+ switch (foo.VariantType)
{
- GD.Print("foo is null");
- }
- if (foo is int)
- {
- GD.Print("foo is an integer");
+ case Variant.Type.Nil:
+ GD.Print("foo is null");
+ break;
+ case Variant.Type.Int:
+ GD.Print("foo is an integer");
+ break;
+ case Variant.Type.Object:
+ // Note that Objects are their own special category.
+ // You can convert a Variant to a GodotObject and use reflection to get its name.
+ GD.Print($"foo is a(n) {foo.AsGodotObject().GetType().Name}");
+ break;
}
[/csharp]
[/codeblocks]
diff --git a/doc/classes/Viewport.xml b/doc/classes/Viewport.xml
index ab2de14638..e76f805e3c 100644
--- a/doc/classes/Viewport.xml
+++ b/doc/classes/Viewport.xml
@@ -277,6 +277,10 @@
<member name="physics_object_picking" type="bool" setter="set_physics_object_picking" getter="get_physics_object_picking" default="false">
If [code]true[/code], the objects rendered by viewport become subjects of mouse picking process.
</member>
+ <member name="physics_object_picking_sort" type="bool" setter="set_physics_object_picking_sort" getter="get_physics_object_picking_sort" default="false">
+ If [code]true[/code], objects receive mouse picking events sorted primarily by their [member CanvasItem.z_index] and secondarily by their position in the scene tree. If [code]false[/code], the order is undetermined.
+ [b]Note:[/b] This setting is disabled by default because of its potential expensive computational cost.
+ </member>
<member name="positional_shadow_atlas_16_bits" type="bool" setter="set_positional_shadow_atlas_16_bits" getter="get_positional_shadow_atlas_16_bits" default="true">
</member>
<member name="positional_shadow_atlas_quad_0" type="int" setter="set_positional_shadow_atlas_quadrant_subdiv" getter="get_positional_shadow_atlas_quadrant_subdiv" enum="Viewport.PositionalShadowAtlasQuadrantSubdiv" default="2">
diff --git a/doc/classes/XRInterface.xml b/doc/classes/XRInterface.xml
index 05d5eb6673..db65ce62f2 100644
--- a/doc/classes/XRInterface.xml
+++ b/doc/classes/XRInterface.xml
@@ -51,6 +51,12 @@
Returns the resolution at which we should render our intermediate results before things like lens distortion are applied by the VR platform.
</description>
</method>
+ <method name="get_supported_environment_blend_modes">
+ <return type="Array" />
+ <description>
+ Returns the an array of supported environment blend modes, see [enum XRInterface.EnvironmentBlendMode].
+ </description>
+ </method>
<method name="get_tracking_status" qualifiers="const">
<return type="int" enum="XRInterface.TrackingStatus" />
<description>
@@ -101,6 +107,28 @@
Is [code]true[/code] if this interface supports passthrough.
</description>
</method>
+ <method name="set_environment_blend_mode">
+ <return type="bool" />
+ <param index="0" name="mode" type="int" enum="XRInterface.EnvironmentBlendMode" />
+ <description>
+ Sets the active environment blend mode.
+ [param mode] is the [enum XRInterface.EnvironmentBlendMode] starting with the next frame.
+ [b]Note:[/b] Not all runtimes support all environment blend modes, so it is important to check this at startup. For example:
+ [codeblock]
+ func _ready():
+ var xr_interface : XRInterface = XRServer.find_interface("OpenXR")
+ if xr_interface and xr_interface.is_initialized():
+ var vp : Viewport = get_viewport()
+ vp.use_xr = true
+ var acceptable_modes = [ XRInterface.XR_ENV_BLEND_MODE_OPAQUE, XRInterface.XR_ENV_BLEND_MODE_ADDITIVE ]
+ var modes = xr_interface.get_supported_environment_blend_modes()
+ for mode in acceptable_modes:
+ if mode in modes:
+ xr_interface.set_environment_blend_mode(mode)
+ break
+ [/codeblock]
+ </description>
+ </method>
<method name="set_play_area_mode">
<return type="bool" />
<param index="0" name="mode" type="int" enum="XRInterface.PlayAreaMode" />
@@ -220,5 +248,14 @@
<constant name="XR_PLAY_AREA_STAGE" value="4" enum="PlayAreaMode">
Same as roomscale but origin point is fixed to the center of the physical space, XRServer.center_on_hmd disabled.
</constant>
+ <constant name="XR_ENV_BLEND_MODE_OPAQUE" value="0" enum="EnvironmentBlendMode">
+ Opaque blend mode. This is typically used for VR devices.
+ </constant>
+ <constant name="XR_ENV_BLEND_MODE_ADDITIVE" value="1" enum="EnvironmentBlendMode">
+ Additive blend mode. This is typically used for AR devices or VR devices with passthrough.
+ </constant>
+ <constant name="XR_ENV_BLEND_MODE_ALPHA_BLEND" value="2" enum="EnvironmentBlendMode">
+ Alpha blend mode. This is typically used for AR or VR devices with passthrough capabilities. The alpha channel controls how much of the passthrough is visible. Alpha of 0.0 means the passthrough is visible and this pixel works in ADDITIVE mode. Alpha of 1.0 means that the passthrough is not visible and this pixel works in OPAQUE mode.
+ </constant>
</constants>
</class>