hertog/godot-module-template
Template
2
1
Fork 1
Code Issues 2 Pull requests 2 Projects Releases Packages Wiki Activity Actions

feat: updated engine version to 4.4-rc1

Browse source
This commit is contained in:
Sara 2025-02-23 14:38:14 +01:00
parent ee00efde1f
commit 21ba8e33af
5459 changed files with 1128836 additions and 198305 deletions
Download patch file Download diff file Expand all files Collapse all files

2
engine/doc/Doxyfile
View file

@ -1475,7 +1475,7 @@ EXT_LINKS_IN_WINDOW = NO
FORMULA_FONTSIZE = 10
# Use the FORMULA_TRANPARENT tag to determine whether or not the images
# Use the FORMULA_TRANSPARENT tag to determine whether or not the images
# generated for formulas are transparent PNGs. Transparent PNGs are not
# supported properly for IE 6.0, but are supported on all modern browsers.
#

2
engine/doc/class.xsd
View file

@ -246,6 +246,8 @@
<xs:attribute type="xs:string" name="data_type" />
<xs:attribute type="xs:string" name="type" />
<xs:attribute type="xs:string" name="default" use="optional" />
<xs:attribute type="xs:string" name="deprecated" use="optional" />
<xs:attribute type="xs:string" name="experimental" use="optional" />
<xs:attribute type="xs:string" name="keywords" use="optional" />
</xs:extension>
</xs:simpleContent>

236
engine/doc/classes/@GlobalScope.xml
View file

@ -6,7 +6,7 @@
<description>
A list of global scope enumerated constants and built-in functions. This is all that resides in the globals, constants regarding error codes, keycodes, property hints, etc.
Singletons are also documented here, since they can be accessed from anywhere.
For the entries related to GDScript which can be accessed in any script see [@GDScript].
For the entries that can only be accessed from scripts written in GDScript, see [@GDScript].
</description>
<tutorials>
<link title="Random number generation">$DOCS_URL/tutorials/math/random_number_generation.html</link>
@ -90,7 +90,7 @@
<param index="0" name="from" type="float" />
<param index="1" name="to" type="float" />
<description>
Returns the difference between the two angles, in the range of [code][-PI, +PI][/code]. When [param from] and [param to] are opposite, returns [code]-PI[/code] if [param from] is smaller than [param to], or [code]PI[/code] otherwise.
Returns the difference between the two angles (in radians), in the range of [code][-PI, +PI][/code]. When [param from] and [param to] are opposite, returns [code]-PI[/code] if [param from] is smaller than [param to], or [code]PI[/code] otherwise.
</description>
</method>
<method name="asin">
@ -370,7 +370,7 @@
Returns an "eased" value of [param x] based on an easing function defined with [param curve]. This easing function is based on an exponent. The [param curve] can be any floating-point number, with specific values leading to the following behaviors:
[codeblock lang=text]
- Lower than -1.0 (exclusive): Ease in-out
- 1.0: Linear
- -1.0: Linear
- Between -1.0 and 0.0 (exclusive): Ease out-in
- 0.0: Constant
- Between 0.0 to 1.0 (exclusive): Ease out
@ -388,9 +388,9 @@
Returns a human-readable name for the given [enum Error] code.
[codeblock]
print(OK) # Prints 0
print(error_string(OK)) # Prints OK
print(error_string(ERR_BUSY)) # Prints Busy
print(error_string(ERR_OUT_OF_MEMORY)) # Prints Out of memory
print(error_string(OK)) # Prints "OK"
print(error_string(ERR_BUSY)) # Prints "Busy"
print(error_string(ERR_OUT_OF_MEMORY)) # Prints "Out of memory"
[/codeblock]
</description>
</method>
@ -495,23 +495,23 @@
Returns the [Object] that corresponds to [param instance_id]. All Objects have a unique instance ID. See also [method Object.get_instance_id].
[codeblocks]
[gdscript]
var foo = "bar"
var drink = "water"
func _ready():
var id = get_instance_id()
var inst = instance_from_id(id)
print(inst.foo) # Prints bar
var instance = instance_from_id(id)
print(instance.foo) # Prints "water"
[/gdscript]
[csharp]
public partial class MyNode : Node
{
public string Foo { get; set; } = "bar";
public string Drink { get; set; } = "water";
public override void _Ready()
{
ulong id = GetInstanceId();
var inst = (MyNode)InstanceFromId(Id);
GD.Print(inst.Foo); // Prints bar
var instance = (MyNode)InstanceFromId(Id);
GD.Print(instance.Drink); // Prints "water"
}
}
[/csharp]
@ -621,13 +621,13 @@
<param index="1" name="to" type="Variant" />
<param index="2" name="weight" type="Variant" />
<description>
Linearly interpolates between two values by the factor defined in [param weight]. To perform interpolation, [param weight] should be between [code]0.0[/code] and [code]1.0[/code] (inclusive). However, values outside this range are allowed and can be used to perform [i]extrapolation[/i]. If this is not desired, use [method clamp] on the result of this function.
Both [param from] and [param to] must be the same type. Supported types: [int], [float], [Vector2], [Vector3], [Vector4], [Color], [Quaternion], [Basis].
Linearly interpolates between two values by the factor defined in [param weight]. To perform interpolation, [param weight] should be between [code]0.0[/code] and [code]1.0[/code] (inclusive). However, values outside this range are allowed and can be used to perform [i]extrapolation[/i]. If this is not desired, use [method clampf] to limit [param weight].
Both [param from] and [param to] must be the same type. Supported types: [int], [float], [Vector2], [Vector3], [Vector4], [Color], [Quaternion], [Basis], [Transform2D], [Transform3D].
[codeblock]
lerp(0, 4, 0.75) # Returns 3.0
[/codeblock]
See also [method inverse_lerp] which performs the reverse of this operation. To perform eased interpolation with [method lerp], combine it with [method ease] or [method smoothstep]. See also [method remap] to map a continuous series of values to another.
[b]Note:[/b] For better type safety, use [method lerpf], [method Vector2.lerp], [method Vector3.lerp], [method Vector4.lerp], [method Color.lerp], [method Quaternion.slerp] or [method Basis.slerp].
[b]Note:[/b] For better type safety, use [method lerpf], [method Vector2.lerp], [method Vector3.lerp], [method Vector4.lerp], [method Color.lerp], [method Quaternion.slerp], [method Basis.slerp], [method Transform2D.interpolate_with], or [method Transform3D.interpolate_with].
</description>
</method>
<method name="lerp_angle" keywords="interpolate">
@ -667,12 +667,9 @@
<return type="float" />
<param index="0" name="lin" type="float" />
<description>
Converts from linear energy to decibels (audio). This can be used to implement volume sliders that behave as expected (since volume isn't linear).
[b]Example:[/b]
Converts from linear energy to decibels (audio). Since volume is not normally linear, this can be used to implement volume sliders that behave as expected.
[b]Example:[/b] Change the Master bus's volume through a [Slider] node, which ranges from [code]0.0[/code] to [code]1.0[/code]:
[codeblock]
# "Slider" refers to a node that inherits Range such as HSlider or VSlider.
# Its range must be configured to go from 0 to 1.
# Change the bus name if you'd like to change the volume of a specific bus only.
AudioServer.set_bus_volume_db(AudioServer.get_bus_index("Master"), linear_to_db($Slider.value))
[/codeblock]
</description>
@ -847,34 +844,35 @@
</description>
</method>
<method name="print" qualifiers="vararg">
<return type="void" />
<description>
Converts one or more arguments of any type to string in the best way possible and prints them to the console.
[codeblocks]
[gdscript]
var a = [1, 2, 3]
print("a", "b", a) # Prints ab[1, 2, 3]
print("a", "b", a) # Prints "ab[1, 2, 3]"
[/gdscript]
[csharp]
var a = new Godot.Collections.Array { 1, 2, 3 };
GD.Print("a", "b", a); // Prints ab[1, 2, 3]
Godot.Collections.Array a = [1, 2, 3];
GD.Print("a", "b", a); // Prints "ab[1, 2, 3]"
[/csharp]
[/codeblocks]
[b]Note:[/b] Consider using [method push_error] and [method push_warning] to print error and warning messages instead of [method print] or [method print_rich]. This distinguishes them from print messages used for debugging purposes, while also displaying a stack trace when an error or warning is printed.
[b]Note:[/b] Consider using [method push_error] and [method push_warning] to print error and warning messages instead of [method print] or [method print_rich]. This distinguishes them from print messages used for debugging purposes, while also displaying a stack trace when an error or warning is printed. See also [member Engine.print_to_stdout] and [member ProjectSettings.application/run/disable_stdout].
</description>
</method>
<method name="print_rich" qualifiers="vararg">
<return type="void" />
<description>
Converts one or more arguments of any type to string in the best way possible and prints them to the console.
The following BBCode tags are supported: [code]b[/code], [code]i[/code], [code]u[/code], [code]s[/code], [code]indent[/code], [code]code[/code], [code]url[/code], [code]center[/code], [code]right[/code], [code]color[/code], [code]bgcolor[/code], [code]fgcolor[/code].
Color tags only support the following named colors: [code]black[/code], [code]red[/code], [code]green[/code], [code]yellow[/code], [code]blue[/code], [code]magenta[/code], [code]pink[/code], [code]purple[/code], [code]cyan[/code], [code]white[/code], [code]orange[/code], [code]gray[/code]. Hexadecimal color codes are not supported.
URL tags only support URLs wrapped by a URL tag, not URLs with a different title.
When printing to standard output, the supported subset of BBCode is converted to ANSI escape codes for the terminal emulator to display. Support for ANSI escape codes varies across terminal emulators, especially for italic and strikethrough. In standard output, [code]code[/code] is represented with faint text but without any font change. Unsupported tags are left as-is in standard output.
[codeblocks]
[gdscript skip-lint]
print_rich("[color=green][b]Hello world![/b][/color]") # Prints out "Hello world!" in green with a bold font
print_rich("[color=green][b]Hello world![/b][/color]") # Prints "Hello world!", in green with a bold font.
[/gdscript]
[csharp skip-lint]
GD.PrintRich("[color=green][b]Hello world![/b][/color]"); // Prints out "Hello world!" in green with a bold font
GD.PrintRich("[color=green][b]Hello world![/b][/color]"); // Prints "Hello world!", in green with a bold font.
[/csharp]
[/codeblocks]
[b]Note:[/b] Consider using [method push_error] and [method push_warning] to print error and warning messages instead of [method print] or [method print_rich]. This distinguishes them from print messages used for debugging purposes, while also displaying a stack trace when an error or warning is printed.
@ -883,11 +881,13 @@
</description>
</method>
<method name="print_verbose" qualifiers="vararg">
<return type="void" />
<description>
If verbose mode is enabled ([method OS.is_stdout_verbose] returning [code]true[/code]), converts one or more arguments of any type to string in the best way possible and prints them to the console.
</description>
</method>
<method name="printerr" qualifiers="vararg">
<return type="void" />
<description>
Prints one or more arguments to strings in the best way possible to standard error line.
[codeblocks]
@ -901,74 +901,79 @@
</description>
</method>
<method name="printraw" qualifiers="vararg">
<return type="void" />
<description>
Prints one or more arguments to strings in the best way possible to the OS terminal. Unlike [method print], no newline is automatically added at the end.
[b]Note:[/b] The OS terminal is [i]not[/i] the same as the editor's Output dock. The output sent to the OS terminal can be seen when running Godot from a terminal. On Windows, this requires using the [code]console.exe[/code] executable.
[codeblocks]
[gdscript]
# Prints "ABC" to terminal.
printraw("A")
printraw("B")
printraw("C")
# Prints ABC to terminal
[/gdscript]
[csharp]
// Prints "ABC" to terminal.
GD.PrintRaw("A");
GD.PrintRaw("B");
GD.PrintRaw("C");
// Prints ABC to terminal
[/csharp]
[/codeblocks]
</description>
</method>
<method name="prints" qualifiers="vararg">
<return type="void" />
<description>
Prints one or more arguments to the console with a space between each argument.
[codeblocks]
[gdscript]
prints("A", "B", "C") # Prints A B C
prints("A", "B", "C") # Prints "A B C"
[/gdscript]
[csharp]
GD.PrintS("A", "B", "C"); // Prints A B C
GD.PrintS("A", "B", "C"); // Prints "A B C"
[/csharp]
[/codeblocks]
</description>
</method>
<method name="printt" qualifiers="vararg">
<return type="void" />
<description>
Prints one or more arguments to the console with a tab between each argument.
[codeblocks]
[gdscript]
printt("A", "B", "C") # Prints A B C
printt("A", "B", "C") # Prints "A B C"
[/gdscript]
[csharp]
GD.PrintT("A", "B", "C"); // Prints A B C
GD.PrintT("A", "B", "C"); // Prints "A B C"
[/csharp]
[/codeblocks]
</description>
</method>
<method name="push_error" qualifiers="vararg">
<return type="void" />
<description>
Pushes an error message to Godot's built-in debugger and to the OS terminal.
[codeblocks]
[gdscript]
push_error("test error") # Prints "test error" to debugger and terminal as error call
push_error("test error") # Prints "test error" to debugger and terminal as an error.
[/gdscript]
[csharp]
GD.PushError("test error"); // Prints "test error" to debugger and terminal as error call
GD.PushError("test error"); // Prints "test error" to debugger and terminal as an error.
[/csharp]
[/codeblocks]
[b]Note:[/b] This function does not pause project execution. To print an error message and pause project execution in debug builds, use [code]assert(false, "test error")[/code] instead.
</description>
</method>
<method name="push_warning" qualifiers="vararg">
<return type="void" />
<description>
Pushes a warning message to Godot's built-in debugger and to the OS terminal.
[codeblocks]
[gdscript]
push_warning("test warning") # Prints "test warning" to debugger and terminal as warning call
push_warning("test warning") # Prints "test warning" to debugger and terminal as a warning.
[/gdscript]
[csharp]
GD.PushWarning("test warning"); // Prints "test warning" to debugger and terminal as warning call
GD.PushWarning("test warning"); // Prints "test warning" to debugger and terminal as a warning.
[/csharp]
[/codeblocks]
</description>
@ -994,8 +999,8 @@
[codeblock]
var a = rand_from_seed(4)
print(a[0]) # Prints 2879024997
print(a[1]) # Prints 4
print(a[0]) # Prints 2879024997
print(a[1]) # Prints 4
[/codeblock]
</description>
</method>
@ -1079,6 +1084,7 @@
</description>
</method>
<method name="randomize">
<return type="void" />
<description>
Randomizes the seed (or the internal state) of the random number generator. The current implementation uses a number based on the device's time.
[b]Note:[/b] This function is called automatically when the project is run. If you need to fix the seed to have consistent, reproducible results, use [method seed] to initialize the random number generator.
@ -1155,6 +1161,7 @@
</description>
</method>
<method name="seed">
<return type="void" />
<param index="0" name="base" type="int" />
<description>
Sets the seed for the random number generator to [param base]. Setting the seed manually can ensure consistent, repeatable results for most random functions.
@ -1212,7 +1219,7 @@
<return type="int" />
<param index="0" name="x" type="int" />
<description>
Returns [code]-1[/code] if [param x] is negative, [code]1[/code] if [param x] is positive, and [code]0[/code] if if [param x] is zero.
Returns [code]-1[/code] if [param x] is negative, [code]1[/code] if [param x] is positive, and [code]0[/code] if [param x] is zero.
[codeblock]
signi(-6) # Returns -1
signi(0) # Returns 0
@ -1248,8 +1255,9 @@
<param index="1" name="to" type="float" />
<param index="2" name="x" type="float" />
<description>
Returns the result of smoothly interpolating the value of [param x] between [code]0[/code] and [code]1[/code], based on the where [param x] lies with respect to the edges [param from] and [param to].
The return value is [code]0[/code] if [code]x &lt;= from[/code], and [code]1[/code] if [code]x &gt;= to[/code]. If [param x] lies between [param from] and [param to], the returned value follows an S-shaped curve that maps [param x] between [code]0[/code] and [code]1[/code].
Returns a smooth cubic Hermite interpolation between [code]0[/code] and [code]1[/code].
For positive ranges (when [code]from &lt;= to[/code]) the return value is [code]0[/code] when [code]x &lt;= from[/code], and [code]1[/code] when [code]x &gt;= to[/code]. If [param x] lies between [param from] and [param to], the return value follows an S-shaped curve that smoothly transitions from [code]0[/code] to [code]1[/code].
For negative ranges (when [code]from &gt; to[/code]) the function is mirrored and returns [code]1[/code] when [code]x &lt;= to[/code] and [code]0[/code] when [code]x &gt;= from[/code].
This S-shaped curve is the cubic Hermite interpolator, given by [code]f(y) = 3*y^2 - 2*y^3[/code] where [code]y = (x-from) / (to-from)[/code].
[codeblock]
smoothstep(0, 2, -5.0) # Returns 0.0
@ -1259,6 +1267,7 @@
[/codeblock]
Compared to [method ease] with a curve value of [code]-1.6521[/code], [method smoothstep] returns the smoothest possible curve with no sudden changes in the derivative. If you need to perform more advanced transitions, use [Tween] or [AnimationPlayer].
[url=https://raw.githubusercontent.com/godotengine/godot-docs/master/img/smoothstep_ease_comparison.png]Comparison between smoothstep() and ease(x, -1.6521) return values[/url]
[url=https://raw.githubusercontent.com/godotengine/godot-docs/master/img/smoothstep_range.webp]Smoothstep() return values with positive, zero, and negative ranges[/url]
</description>
</method>
<method name="snapped">
@ -1404,9 +1413,9 @@
<description>
Returns a human-readable name of the given [param type], using the [enum Variant.Type] values.
[codeblock]
print(TYPE_INT) # Prints 2.
print(type_string(TYPE_INT)) # Prints "int".
print(type_string(TYPE_STRING)) # Prints "String".
print(TYPE_INT) # Prints 2
print(type_string(TYPE_INT)) # Prints "int"
print(type_string(TYPE_STRING)) # Prints "String"
[/codeblock]
See also [method typeof].
</description>
@ -1420,10 +1429,10 @@
var json = JSON.new()
json.parse('["a", "b", "c"]')
var result = json.get_data()
if typeof(result) == TYPE_ARRAY:
print(result[0]) # Prints a
if result is Array:
print(result[0]) # Prints "a"
else:
print("Unexpected result")
print("Unexpected result!")
[/codeblock]
See also [method type_string].
</description>
@ -2021,16 +2030,16 @@
Help key.
</constant>
<constant name="KEY_BACK" value="4194376" enum="Key">
Media back key. Not to be confused with the Back button on an Android device.
Back key.
</constant>
<constant name="KEY_FORWARD" value="4194377" enum="Key">
Media forward key.
Forward key.
</constant>
<constant name="KEY_STOP" value="4194378" enum="Key">
Media stop key.
</constant>
<constant name="KEY_REFRESH" value="4194379" enum="Key">
Media refresh key.
Refresh key.
</constant>
<constant name="KEY_VOLUMEDOWN" value="4194380" enum="Key">
Volume down key.
@ -2144,49 +2153,49 @@
Space key.
</constant>
<constant name="KEY_EXCLAM" value="33" enum="Key">
! key.
Exclamation mark ([code]![/code]) key.
</constant>
<constant name="KEY_QUOTEDBL" value="34" enum="Key">
" key.
Double quotation mark ([code]"[/code]) key.
</constant>
<constant name="KEY_NUMBERSIGN" value="35" enum="Key">
# key.
<constant name="KEY_NUMBERSIGN" value="35" enum="Key" keywords="pound, hash">
Number sign or [i]hash[/i] ([code]#[/code]) key.
</constant>
<constant name="KEY_DOLLAR" value="36" enum="Key">
$ key.
Dollar sign ([code]$[/code]) key.
</constant>
<constant name="KEY_PERCENT" value="37" enum="Key">
% key.
Percent sign ([code]%[/code]) key.
</constant>
<constant name="KEY_AMPERSAND" value="38" enum="Key">
&amp; key.
Ampersand ([code]&amp;[/code]) key.
</constant>
<constant name="KEY_APOSTROPHE" value="39" enum="Key">
' key.
Apostrophe ([code]'[/code]) key.
</constant>
<constant name="KEY_PARENLEFT" value="40" enum="Key">
( key.
<constant name="KEY_PARENLEFT" value="40" enum="Key" keywords="open round bracket">
Left parenthesis ([code]([/code]) key.
</constant>
<constant name="KEY_PARENRIGHT" value="41" enum="Key">
) key.
<constant name="KEY_PARENRIGHT" value="41" enum="Key" keywords="close round bracket">
Right parenthesis ([code])[/code]) key.
</constant>
<constant name="KEY_ASTERISK" value="42" enum="Key">
* key.
Asterisk ([code]*[/code]) key.
</constant>
<constant name="KEY_PLUS" value="43" enum="Key">
+ key.
Plus ([code]+[/code]) key.
</constant>
<constant name="KEY_COMMA" value="44" enum="Key">
, key.
Comma ([code],[/code]) key.
</constant>
<constant name="KEY_MINUS" value="45" enum="Key">
- key.
<constant name="KEY_MINUS" value="45" enum="Key" keywords="hyphen">
Minus ([code]-[/code]) key.
</constant>
<constant name="KEY_PERIOD" value="46" enum="Key">
. key.
<constant name="KEY_PERIOD" value="46" enum="Key" keywords="dot">
Period ([code].[/code]) key.
</constant>
<constant name="KEY_SLASH" value="47" enum="Key">
/ key.
Slash ([code]/[/code]) key.
</constant>
<constant name="KEY_0" value="48" enum="Key">
Number 0 key.
@ -2219,25 +2228,25 @@
Number 9 key.
</constant>
<constant name="KEY_COLON" value="58" enum="Key">
: key.
Colon ([code]:[/code]) key.
</constant>
<constant name="KEY_SEMICOLON" value="59" enum="Key">
; key.
Semicolon ([code];[/code]) key.
</constant>
<constant name="KEY_LESS" value="60" enum="Key">
&lt; key.
Less-than sign ([code]&lt;[/code]) key.
</constant>
<constant name="KEY_EQUAL" value="61" enum="Key">
= key.
Equal sign ([code]=[/code]) key.
</constant>
<constant name="KEY_GREATER" value="62" enum="Key">
&gt; key.
Greater-than sign ([code]&gt;[/code]) key.
</constant>
<constant name="KEY_QUESTION" value="63" enum="Key">
? key.
Question mark ([code]?[/code]) key.
</constant>
<constant name="KEY_AT" value="64" enum="Key">
@ key.
<constant name="KEY_AT" value="64" enum="Key" keywords="commercial at">
At sign ([code]@[/code]) key.
</constant>
<constant name="KEY_A" value="65" enum="Key">
A key.
@ -2317,46 +2326,46 @@
<constant name="KEY_Z" value="90" enum="Key">
Z key.
</constant>
<constant name="KEY_BRACKETLEFT" value="91" enum="Key">
[ key.
<constant name="KEY_BRACKETLEFT" value="91" enum="Key" keywords="open square bracket">
Left bracket ([code][lb][/code]) key.
</constant>
<constant name="KEY_BACKSLASH" value="92" enum="Key">
\ key.
Backslash ([code]\[/code]) key.
</constant>
<constant name="KEY_BRACKETRIGHT" value="93" enum="Key">
] key.
<constant name="KEY_BRACKETRIGHT" value="93" enum="Key" keywords="close square bracket">
Right bracket ([code][rb][/code]) key.
</constant>
<constant name="KEY_ASCIICIRCUM" value="94" enum="Key">
^ key.
<constant name="KEY_ASCIICIRCUM" value="94" enum="Key" keywords="caret">
Caret ([code]^[/code]) key.
</constant>
<constant name="KEY_UNDERSCORE" value="95" enum="Key">
_ key.
<constant name="KEY_UNDERSCORE" value="95" enum="Key" keywords="underline">
Underscore ([code]_[/code]) key.
</constant>
<constant name="KEY_QUOTELEFT" value="96" enum="Key">
` key.
<constant name="KEY_QUOTELEFT" value="96" enum="Key" keywords="backtick, backquote">
Backtick ([code]`[/code]) key.
</constant>
<constant name="KEY_BRACELEFT" value="123" enum="Key">
{ key.
<constant name="KEY_BRACELEFT" value="123" enum="Key" keywords="open curly bracket">
Left brace ([code]{[/code]) key.
</constant>
<constant name="KEY_BAR" value="124" enum="Key">
| key.
<constant name="KEY_BAR" value="124" enum="Key" keywords="pipe">
Vertical bar or [i]pipe[/i] ([code]|[/code]) key.
</constant>
<constant name="KEY_BRACERIGHT" value="125" enum="Key">
} key.
<constant name="KEY_BRACERIGHT" value="125" enum="Key" keywords="close curly bracket">
Right brace ([code]}[/code]) key.
</constant>
<constant name="KEY_ASCIITILDE" value="126" enum="Key">
~ key.
Tilde ([code]~[/code]) key.
</constant>
<constant name="KEY_YEN" value="165" enum="Key">
¥ key.
Yen symbol ([code]¥[/code]) key.
</constant>
<constant name="KEY_SECTION" value="167" enum="Key">
§ key.
<constant name="KEY_SECTION" value="167" enum="Key" keywords="silcrow">
Section sign ([code]§[/code]) key.
</constant>
<constant name="KEY_CODE_MASK" value="8388607" enum="KeyModifierMask" is_bitfield="true">
Key Code mask.
</constant>
<constant name="KEY_MODIFIER_MASK" value="532676608" enum="KeyModifierMask" is_bitfield="true">
<constant name="KEY_MODIFIER_MASK" value="2130706432" enum="KeyModifierMask" is_bitfield="true">
Modifier key mask.
</constant>
<constant name="KEY_MASK_CMD_OR_CTRL" value="16777216" enum="KeyModifierMask" is_bitfield="true">
@ -2601,8 +2610,7 @@
</constant>
<constant name="OK" value="0" enum="Error">
Methods that return [enum Error] return [constant OK] when no error occurred.
Since [constant OK] has value 0, and all other error constants are positive integers, it can also be used in boolean checks.
[b]Example:[/b]
Since [constant OK] has value [code]0[/code], and all other error constants are positive integers, it can also be used in boolean checks.
[codeblock]
var error = method_that_returns_error()
if error != OK:
@ -2865,7 +2873,7 @@
hintString = $"{Variant.Type.Array:D}:{Variant.Type.Array:D}:{elemType:D}/{elemHint:D}:{elemHintString}";
[/csharp]
[/codeblocks]
Examples:
[b]Examples:[/b]
[codeblocks]
[gdscript]
hint_string = "%d:" % [TYPE_INT] # Array of integers.
@ -2917,6 +2925,9 @@
<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_DICTIONARY_TYPE" value="38" enum="PropertyHint">
Hints that a property is a [Dictionary] with the stored types 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.
</constant>
@ -2932,7 +2943,18 @@
<constant name="PROPERTY_HINT_PASSWORD" value="36" enum="PropertyHint">
Hints that a string property is a password, and every character is replaced with the secret character.
</constant>
<constant name="PROPERTY_HINT_MAX" value="38" enum="PropertyHint">
<constant name="PROPERTY_HINT_TOOL_BUTTON" value="39" enum="PropertyHint">
Hints that a [Callable] property should be displayed as a clickable button. When the button is pressed, the callable is called. The hint string specifies the button text and optionally an icon from the [code]"EditorIcons"[/code] theme type.
[codeblock lang=text]
"Click me!" - A button with the text "Click me!" and the default "Callable" icon.
"Click me!,ColorRect" - A button with the text "Click me!" and the "ColorRect" icon.
[/codeblock]
[b]Note:[/b] A [Callable] cannot be properly serialized and stored in a file, so it is recommended to use [constant PROPERTY_USAGE_EDITOR] instead of [constant PROPERTY_USAGE_DEFAULT].
</constant>
<constant name="PROPERTY_HINT_ONESHOT" value="40" enum="PropertyHint">
Hints that a property will be changed on its own after setting, such as [member AudioStreamPlayer.playing] or [member GPUParticles3D.emitting].
</constant>
<constant name="PROPERTY_HINT_MAX" value="42" enum="PropertyHint">
Represents the size of the [enum PropertyHint] enum.
</constant>
<constant name="PROPERTY_USAGE_NONE" value="0" enum="PropertyUsageFlags" is_bitfield="true">
@ -2972,7 +2994,7 @@
Editing the property prompts the user for restarting the editor.
</constant>
<constant name="PROPERTY_USAGE_SCRIPT_VARIABLE" value="4096" enum="PropertyUsageFlags" is_bitfield="true">
The property is a script variable which should be serialized and saved in the scene file.
The property is a script variable. [constant PROPERTY_USAGE_SCRIPT_VARIABLE] can be used to distinguish between exported script variables from built-in variables (which don't have this usage flag). By default, [constant PROPERTY_USAGE_SCRIPT_VARIABLE] is [b]not[/b] applied to variables that are created by overriding [method Object._get_property_list] in a script.
</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].
@ -2983,7 +3005,7 @@
<constant name="PROPERTY_USAGE_SCRIPT_DEFAULT_VALUE" value="32768" enum="PropertyUsageFlags" is_bitfield="true" deprecated="This flag is not used by the engine.">
</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.
The property is a variable of enum type, 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].

48
engine/doc/classes/AABB.xml
View file

@ -46,8 +46,8 @@
[gdscript]
var box = AABB(Vector3(5, 0, 5), Vector3(-20, -10, -5))
var absolute = box.abs()
print(absolute.position) # Prints (-15, -10, 0)
print(absolute.size) # Prints (20, 10, 5)
print(absolute.position) # Prints (-15.0, -10.0, 0.0)
print(absolute.size) # Prints (20.0, 10.0, 5.0)
[/gdscript]
[csharp]
var box = new Aabb(new Vector3(5, 0, 5), new Vector3(-20, -10, -5));
@ -96,12 +96,12 @@
var box = AABB(Vector3(0, 0, 0), Vector3(5, 2, 5))
box = box.expand(Vector3(10, 0, 0))
print(box.position) # Prints (0, 0, 0)
print(box.size) # Prints (10, 2, 5)
print(box.position) # Prints (0.0, 0.0, 0.0)
print(box.size) # Prints (10.0, 2.0, 5.0)
box = box.expand(Vector3(-5, 0, 5))
print(box.position) # Prints (-5, 0, 0)
print(box.size) # Prints (15, 2, 5)
print(box.position) # Prints (-5.0, 0.0, 0.0)
print(box.size) # Prints (15.0, 2.0, 5.0)
[/gdscript]
[csharp]
var box = new Aabb(new Vector3(0, 0, 0), new Vector3(5, 2, 5));
@ -138,15 +138,15 @@
[gdscript]
var box = AABB(Vector3(0, 0, 0), Vector3(2, 4, 8))
print(box.get_longest_axis()) # Prints (0, 0, 1)
print(box.get_longest_axis()) # Prints (0.0, 0.0, 1.0)
print(box.get_longest_axis_index()) # Prints 2
print(box.get_longest_axis_size()) # Prints 8
print(box.get_longest_axis_size()) # Prints 8.0
[/gdscript]
[csharp]
var box = new Aabb(new Vector3(0, 0, 0), new Vector3(2, 4, 8));
GD.Print(box.GetLongestAxis()); // Prints (0, 0, 1)
GD.Print(box.GetLongestAxisIndex()); // Prints 2
GD.Print(box.GetLongestAxisIndex()); // Prints Z
GD.Print(box.GetLongestAxisSize()); // Prints 8
[/csharp]
[/codeblocks]
@ -175,15 +175,15 @@
[gdscript]
var box = AABB(Vector3(0, 0, 0), Vector3(2, 4, 8))
print(box.get_shortest_axis()) # Prints (1, 0, 0)
print(box.get_shortest_axis()) # Prints (1.0, 0.0, 0.0)
print(box.get_shortest_axis_index()) # Prints 0
print(box.get_shortest_axis_size()) # Prints 2
print(box.get_shortest_axis_size()) # Prints 2.0
[/gdscript]
[csharp]
var box = new Aabb(new Vector3(0, 0, 0), new Vector3(2, 4, 8));
GD.Print(box.GetShortestAxis()); // Prints (1, 0, 0)
GD.Print(box.GetShortestAxisIndex()); // Prints 0
GD.Print(box.GetShortestAxisIndex()); // Prints X
GD.Print(box.GetShortestAxisSize()); // Prints 2
[/csharp]
[/codeblocks]
@ -206,7 +206,7 @@
</method>
<method name="get_support" qualifiers="const">
<return type="Vector3" />
<param index="0" name="dir" type="Vector3" />
<param index="0" name="direction" type="Vector3" />
<description>
Returns the vertex's position of this bounding box that's the farthest in the given direction. This point is commonly known as the support point in collision detection algorithms.
</description>
@ -225,12 +225,12 @@
[codeblocks]
[gdscript]
var a = AABB(Vector3(4, 4, 4), Vector3(8, 8, 8)).grow(4)
print(a.position) # Prints (0, 0, 0)
print(a.size) # Prints (16, 16, 16)
print(a.position) # Prints (0.0, 0.0, 0.0)
print(a.size) # Prints (16.0, 16.0, 16.0)
var b = AABB(Vector3(0, 0, 0), Vector3(8, 4, 2)).grow(2)
print(b.position) # Prints (-2, -2, -2)
print(b.size) # Prints (12, 8, 6)
print(b.position) # Prints (-2.0, -2.0, -2.0)
print(b.size) # Prints (12.0, 8.0, 6.0)
[/gdscript]
[csharp]
var a = new Aabb(new Vector3(4, 4, 4), new Vector3(8, 8, 8)).Grow(4);
@ -275,8 +275,8 @@
var box2 = AABB(Vector3(2, 0, 2), Vector3(8, 4, 4))
var intersection = box1.intersection(box2)
print(intersection.position) # Prints (2, 0, 2)
print(intersection.size) # Prints (3, 2, 4)
print(intersection.position) # Prints (2.0, 0.0, 2.0)
print(intersection.size) # Prints (3.0, 2.0, 4.0)
[/gdscript]
[csharp]
var box1 = new Aabb(new Vector3(0, 0, 0), new Vector3(5, 2, 8));
@ -326,13 +326,13 @@
<return type="bool" />
<param index="0" name="aabb" type="AABB" />
<description>
Returns [code]true[/code] if this bounding box and [param aabb] are approximately equal, by calling [method Vector2.is_equal_approx] on the [member position] and the [member size].
Returns [code]true[/code] if this bounding box and [param aabb] are approximately equal, by calling [method Vector3.is_equal_approx] on the [member position] and the [member size].
</description>
</method>
<method name="is_finite" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if this bounding box's values are finite, by calling [method Vector2.is_finite] on the [member position] and the [member size].
Returns [code]true[/code] if this bounding box's values are finite, by calling [method Vector3.is_finite] on the [member position] and the [member size].
</description>
</method>
<method name="merge" qualifiers="const">
@ -345,14 +345,14 @@
</methods>
<members>
<member name="end" type="Vector3" setter="" getter="" default="Vector3(0, 0, 0)">
The ending point. This is usually the corner on the top-right and forward of the bounding box, and is equivalent to [code]position + size[/code]. Setting this point affects the [member size].
The ending point. This is usually the corner on the top-right and back of the bounding box, and is equivalent to [code]position + size[/code]. Setting this point affects the [member size].
</member>
<member name="position" type="Vector3" setter="" getter="" default="Vector3(0, 0, 0)">
The origin point. This is usually the corner on the bottom-left and back of the bounding box.
The origin point. This is usually the corner on the bottom-left and forward of the bounding box.
</member>
<member name="size" type="Vector3" setter="" getter="" default="Vector3(0, 0, 0)">
The bounding box's width, height, and depth starting from [member position]. Setting this value also affects the [member end] point.
[b]Note:[/b] It's recommended setting the width, height, and depth to non-negative values. This is because most methods in Godot assume that the [member position] is the bottom-left-back corner, and the [member end] is the top-right-forward corner. To get an equivalent bounding box with non-negative size, use [method abs].
[b]Note:[/b] It's recommended setting the width, height, and depth to non-negative values. This is because most methods in Godot assume that the [member position] is the bottom-left-forward corner, and the [member end] is the top-right-back corner. To get an equivalent bounding box with non-negative size, use [method abs].
</member>
</members>
<operators>

10
engine/doc/classes/AStar2D.xml
View file

@ -22,7 +22,7 @@
<method name="_estimate_cost" qualifiers="virtual const">
<return type="float" />
<param index="0" name="from_id" type="int" />
<param index="1" name="to_id" type="int" />
<param index="1" name="end_id" type="int" />
<description>
Called when estimating the cost between a point and the path's ending point.
Note that this function is hidden in the default [AStar2D] class.
@ -143,6 +143,7 @@
<description>
Returns an array with the IDs of the points that form the path found by AStar2D between the given points. The array is ordered from the starting point to the ending point of the path.
If there is no valid path to the target, and [param allow_partial_path] is [code]true[/code], returns a path to the point closest to the target that can be reached.
[b]Note:[/b] When [param allow_partial_path] is [code]true[/code] and [param to_id] is disabled the search may take an unusually long time to finish.
[codeblocks]
[gdscript]
var astar = AStar2D.new()
@ -169,7 +170,7 @@
astar.ConnectPoints(2, 3, false);
astar.ConnectPoints(4, 3, false);
astar.ConnectPoints(1, 4, false);
int[] res = astar.GetIdPath(1, 3); // Returns [1, 2, 3]
long[] res = astar.GetIdPath(1, 3); // Returns [1, 2, 3]
[/csharp]
[/codeblocks]
If you change the 2nd point's weight to 3, then the result will be [code][1, 4, 3][/code] instead, because now even though the distance is longer, it's "easier" to get through point 4 than through point 2.
@ -209,7 +210,7 @@
astar.ConnectPoints(1, 2, true);
astar.ConnectPoints(1, 3, true);
int[] neighbors = astar.GetPointConnections(1); // Returns [2, 3]
long[] neighbors = astar.GetPointConnections(1); // Returns [2, 3]
[/csharp]
[/codeblocks]
</description>
@ -235,6 +236,7 @@
Returns an array with the points that are in the path found by AStar2D between the given points. The array is ordered from the starting point to the ending point of the path.
If there is no valid path to the target, and [param allow_partial_path] is [code]true[/code], returns a path to the point closest to the target that can be reached.
[b]Note:[/b] This method is not thread-safe. If called from a [Thread], it will return an empty array and will print an error message.
Additionally, when [param allow_partial_path] is [code]true[/code] and [param to_id] is disabled the search may take an unusually long time to finish.
</description>
</method>
<method name="get_point_position" qualifiers="const">
@ -276,7 +278,7 @@
<return type="void" />
<param index="0" name="num_nodes" type="int" />
<description>
Reserves space internally for [param num_nodes] points, useful if you're adding a known large number of points at once, such as points on a grid. New capacity must be greater or equals to old capacity.
Reserves space internally for [param num_nodes] points. Useful if you're adding a known large number of points at once, such as points on a grid. The new capacity must be greater or equal to the old capacity.
</description>
</method>
<method name="set_point_disabled">

41
engine/doc/classes/AStar3D.xml
View file

@ -6,29 +6,42 @@
<description>
A* (A star) is a computer algorithm used in pathfinding and graph traversal, the process of plotting short paths among vertices (points), passing through a given set of edges (segments). It enjoys widespread use due to its performance and accuracy. Godot's A* implementation uses points in 3D space and Euclidean distances by default.
You must add points manually with [method add_point] and create segments manually with [method connect_points]. Once done, you can test if there is a path between two points with the [method are_points_connected] function, get a path containing indices by [method get_id_path], or one containing actual coordinates with [method get_point_path].
It is also possible to use non-Euclidean distances. To do so, create a class that extends [AStar3D] and override methods [method _compute_cost] and [method _estimate_cost]. Both take two indices and return a length, as is shown in the following example.
It is also possible to use non-Euclidean distances. To do so, create a script that extends [AStar3D] and override the methods [method _compute_cost] and [method _estimate_cost]. Both should take two point IDs and return the distance between the corresponding points.
[b]Example:[/b] Use Manhattan distance instead of Euclidean distance:
[codeblocks]
[gdscript]
class MyAStar:
extends AStar3D
class_name MyAStar3D
extends AStar3D
func _compute_cost(u, v):
return abs(u - v)
func _compute_cost(u, v):
var u_pos = get_point_position(u)
var v_pos = get_point_position(v)
return abs(u_pos.x - v_pos.x) + abs(u_pos.y - v_pos.y) + abs(u_pos.z - v_pos.z)
func _estimate_cost(u, v):
return min(0, abs(u - v) - 1)
func _estimate_cost(u, v):
var u_pos = get_point_position(u)
var v_pos = get_point_position(v)
return abs(u_pos.x - v_pos.x) + abs(u_pos.y - v_pos.y) + abs(u_pos.z - v_pos.z)
[/gdscript]
[csharp]
public partial class MyAStar : AStar3D
using Godot;
[GlobalClass]
public partial class MyAStar3D : AStar3D
{
public override float _ComputeCost(long fromId, long toId)
{
return Mathf.Abs((int)(fromId - toId));
Vector3 fromPoint = GetPointPosition(fromId);
Vector3 toPoint = GetPointPosition(toId);
return Mathf.Abs(fromPoint.X - toPoint.X) + Mathf.Abs(fromPoint.Y - toPoint.Y) + Mathf.Abs(fromPoint.Z - toPoint.Z);
}
public override float _EstimateCost(long fromId, long toId)
{
return Mathf.Min(0, Mathf.Abs((int)(fromId - toId)) - 1);
Vector3 fromPoint = GetPointPosition(fromId);
Vector3 toPoint = GetPointPosition(toId);
return Mathf.Abs(fromPoint.X - toPoint.X) + Mathf.Abs(fromPoint.Y - toPoint.Y) + Mathf.Abs(fromPoint.Z - toPoint.Z);
}
}
[/csharp]
@ -51,7 +64,7 @@
<method name="_estimate_cost" qualifiers="virtual const">
<return type="float" />
<param index="0" name="from_id" type="int" />
<param index="1" name="to_id" type="int" />
<param index="1" name="end_id" type="int" />
<description>
Called when estimating the cost between a point and the path's ending point.
Note that this function is hidden in the default [AStar3D] class.
@ -172,6 +185,7 @@
<description>
Returns an array with the IDs of the points that form the path found by AStar3D between the given points. The array is ordered from the starting point to the ending point of the path.
If there is no valid path to the target, and [param allow_partial_path] is [code]true[/code], returns a path to the point closest to the target that can be reached.
[b]Note:[/b] When [param allow_partial_path] is [code]true[/code] and [param to_id] is disabled the search may take an unusually long time to finish.
[codeblocks]
[gdscript]
var astar = AStar3D.new()
@ -197,7 +211,7 @@
astar.ConnectPoints(2, 3, false);
astar.ConnectPoints(4, 3, false);
astar.ConnectPoints(1, 4, false);
int[] res = astar.GetIdPath(1, 3); // Returns [1, 2, 3]
long[] res = astar.GetIdPath(1, 3); // Returns [1, 2, 3]
[/csharp]
[/codeblocks]
If you change the 2nd point's weight to 3, then the result will be [code][1, 4, 3][/code] instead, because now even though the distance is longer, it's "easier" to get through point 4 than through point 2.
@ -236,7 +250,7 @@
astar.ConnectPoints(1, 2, true);
astar.ConnectPoints(1, 3, true);
int[] neighbors = astar.GetPointConnections(1); // Returns [2, 3]
long[] neighbors = astar.GetPointConnections(1); // Returns [2, 3]
[/csharp]
[/codeblocks]
</description>
@ -262,6 +276,7 @@
Returns an array with the points that are in the path found by AStar3D between the given points. The array is ordered from the starting point to the ending point of the path.
If there is no valid path to the target, and [param allow_partial_path] is [code]true[/code], returns a path to the point closest to the target that can be reached.
[b]Note:[/b] This method is not thread-safe. If called from a [Thread], it will return an empty array and will print an error message.
Additionally, when [param allow_partial_path] is [code]true[/code] and [param to_id] is disabled the search may take an unusually long time to finish.
</description>
</method>
<method name="get_point_position" qualifiers="const">

19
engine/doc/classes/AStarGrid2D.xml
View file

@ -12,16 +12,16 @@
astar_grid.region = Rect2i(0, 0, 32, 32)
astar_grid.cell_size = Vector2(16, 16)
astar_grid.update()
print(astar_grid.get_id_path(Vector2i(0, 0), Vector2i(3, 4))) # prints (0, 0), (1, 1), (2, 2), (3, 3), (3, 4)
print(astar_grid.get_point_path(Vector2i(0, 0), Vector2i(3, 4))) # prints (0, 0), (16, 16), (32, 32), (48, 48), (48, 64)
print(astar_grid.get_id_path(Vector2i(0, 0), Vector2i(3, 4))) # Prints [(0, 0), (1, 1), (2, 2), (3, 3), (3, 4)]
print(astar_grid.get_point_path(Vector2i(0, 0), Vector2i(3, 4))) # Prints [(0, 0), (16, 16), (32, 32), (48, 48), (48, 64)]
[/gdscript]
[csharp]
AStarGrid2D astarGrid = new AStarGrid2D();
astarGrid.Region = new Rect2I(0, 0, 32, 32);
astarGrid.CellSize = new Vector2I(16, 16);
astarGrid.Update();
GD.Print(astarGrid.GetIdPath(Vector2I.Zero, new Vector2I(3, 4))); // prints (0, 0), (1, 1), (2, 2), (3, 3), (3, 4)
GD.Print(astarGrid.GetPointPath(Vector2I.Zero, new Vector2I(3, 4))); // prints (0, 0), (16, 16), (32, 32), (48, 48), (48, 64)
GD.Print(astarGrid.GetIdPath(Vector2I.Zero, new Vector2I(3, 4))); // Prints [(0, 0), (1, 1), (2, 2), (3, 3), (3, 4)]
GD.Print(astarGrid.GetPointPath(Vector2I.Zero, new Vector2I(3, 4))); // Prints [(0, 0), (16, 16), (32, 32), (48, 48), (48, 64)]
[/csharp]
[/codeblocks]
To remove a point from the pathfinding grid, it must be set as "solid" with [method set_point_solid].
@ -41,7 +41,7 @@
<method name="_estimate_cost" qualifiers="virtual const">
<return type="float" />
<param index="0" name="from_id" type="Vector2i" />
<param index="1" name="to_id" type="Vector2i" />
<param index="1" name="end_id" type="Vector2i" />
<description>
Called when estimating the cost between a point and the path's ending point.
Note that this function is hidden in the default [AStarGrid2D] class.
@ -79,6 +79,14 @@
<description>
Returns an array with the IDs of the points that form the path found by AStar2D between the given points. The array is ordered from the starting point to the ending point of the path.
If there is no valid path to the target, and [param allow_partial_path] is [code]true[/code], returns a path to the point closest to the target that can be reached.
[b]Note:[/b] When [param allow_partial_path] is [code]true[/code] and [param to_id] is solid the search may take an unusually long time to finish.
</description>
</method>
<method name="get_point_data_in_region" qualifiers="const">
<return type="Dictionary[]" />
<param index="0" name="region" type="Rect2i" />
<description>
Returns an array of dictionaries with point data ([code]id[/code]: [Vector2i], [code]position[/code]: [Vector2], [code]solid[/code]: [bool], [code]weight_scale[/code]: [float]) within a [param region].
</description>
</method>
<method name="get_point_path">
@ -90,6 +98,7 @@
Returns an array with the points that are in the path found by [AStarGrid2D] between the given points. The array is ordered from the starting point to the ending point of the path.
If there is no valid path to the target, and [param allow_partial_path] is [code]true[/code], returns a path to the point closest to the target that can be reached.
[b]Note:[/b] This method is not thread-safe. If called from a [Thread], it will return an empty array and will print an error message.
Additionally, when [param allow_partial_path] is [code]true[/code] and [param to_id] is solid the search may take an unusually long time to finish.
</description>
</method>
<method name="get_point_position" qualifiers="const">

6
engine/doc/classes/AnimatedSprite2D.xml
View file

@ -54,12 +54,10 @@
<param index="0" name="frame" type="int" />
<param index="1" name="progress" type="float" />
<description>
The setter of [member frame] resets the [member frame_progress] to [code]0.0[/code] implicitly, but this method avoids that.
This is useful when you want to carry over the current [member frame_progress] to another [member frame].
[b]Example:[/b]
Sets [member frame] the [member frame_progress] to the given values. Unlike setting [member frame], this method does not reset the [member frame_progress] to [code]0.0[/code] implicitly.
[b]Example:[/b] Change the animation while keeping the same [member frame] and [member frame_progress]:
[codeblocks]
[gdscript]
# Change the animation with keeping the frame index and progress.
var current_frame = animated_sprite.get_frame()
var current_progress = animated_sprite.get_frame_progress()
animated_sprite.play("walk_another_skin")

6
engine/doc/classes/AnimatedSprite3D.xml
View file

@ -53,12 +53,10 @@
<param index="0" name="frame" type="int" />
<param index="1" name="progress" type="float" />
<description>
The setter of [member frame] resets the [member frame_progress] to [code]0.0[/code] implicitly, but this method avoids that.
This is useful when you want to carry over the current [member frame_progress] to another [member frame].
[b]Example:[/b]
Sets [member frame] the [member frame_progress] to the given values. Unlike setting [member frame], this method does not reset the [member frame_progress] to [code]0.0[/code] implicitly.
[b]Example:[/b] Change the animation while keeping the same [member frame] and [member frame_progress]:
[codeblocks]
[gdscript]
# Change the animation with keeping the frame index and progress.
var current_frame = animated_sprite.get_frame()
var current_progress = animated_sprite.get_frame_progress()
animated_sprite.play("walk_another_skin")

80
engine/doc/classes/Animation.xml
View file

@ -34,6 +34,14 @@
<link title="Animation documentation index">$DOCS_URL/tutorials/animation/index.html</link>
</tutorials>
<methods>
<method name="add_marker">
<return type="void" />
<param index="0" name="name" type="StringName" />
<param index="1" name="time" type="float" />
<description>
Adds a marker to this Animation.
</description>
</method>
<method name="add_track">
<return type="int" />
<param index="0" name="type" type="int" enum="Animation.TrackType" />
@ -271,12 +279,60 @@
Returns the index of the specified track. If the track is not found, return -1.
</description>
</method>
<method name="get_marker_at_time" qualifiers="const">
<return type="StringName" />
<param index="0" name="time" type="float" />
<description>
Returns the name of the marker located at the given time.
</description>
</method>
<method name="get_marker_color" qualifiers="const">
<return type="Color" />
<param index="0" name="name" type="StringName" />
<description>
Returns the given marker's color.
</description>
</method>
<method name="get_marker_names" qualifiers="const">
<return type="PackedStringArray" />
<description>
Returns every marker in this Animation, sorted ascending by time.
</description>
</method>
<method name="get_marker_time" qualifiers="const">
<return type="float" />
<param index="0" name="name" type="StringName" />
<description>
Returns the given marker's time.
</description>
</method>
<method name="get_next_marker" qualifiers="const">
<return type="StringName" />
<param index="0" name="time" type="float" />
<description>
Returns the closest marker that comes after the given time. If no such marker exists, an empty string is returned.
</description>
</method>
<method name="get_prev_marker" qualifiers="const">
<return type="StringName" />
<param index="0" name="time" type="float" />
<description>
Returns the closest marker that comes before the given time. If no such marker exists, an empty string is returned.
</description>
</method>
<method name="get_track_count" qualifiers="const">
<return type="int" />
<description>
Returns the amount of tracks in the animation.
</description>
</method>
<method name="has_marker" qualifiers="const">
<return type="bool" />
<param index="0" name="name" type="StringName" />
<description>
Returns [code]true[/code] if this Animation contains a marker with the given name.
</description>
</method>
<method name="method_track_get_name" qualifiers="const">
<return type="StringName" />
<param index="0" name="track_idx" type="int" />
@ -293,6 +349,15 @@
Returns the arguments values to be called on a method track for a given key in a given track.
</description>
</method>
<method name="optimize">
<return type="void" />
<param index="0" name="allowed_velocity_err" type="float" default="0.01" />
<param index="1" name="allowed_angular_err" type="float" default="0.01" />
<param index="2" name="precision" type="int" default="3" />
<description>
Optimize the animation and all its tracks in-place. This will preserve only as many keys as are necessary to keep the animation within the specified bounds.
</description>
</method>
<method name="position_track_insert_key">
<return type="int" />
<param index="0" name="track_idx" type="int" />
@ -311,6 +376,13 @@
Returns the interpolated position value at the given time (in seconds). The [param track_idx] must be the index of a 3D position track.
</description>
</method>
<method name="remove_marker">
<return type="void" />
<param index="0" name="name" type="StringName" />
<description>
Removes the marker with the given name from this Animation.
</description>
</method>
<method name="remove_track">
<return type="void" />
<param index="0" name="track_idx" type="int" />
@ -354,6 +426,14 @@
Returns the interpolated scale value at the given time (in seconds). The [param track_idx] must be the index of a 3D scale track.
</description>
</method>
<method name="set_marker_color">
<return type="void" />
<param index="0" name="name" type="StringName" />
<param index="1" name="color" type="Color" />
<description>
Sets the given marker's color.
</description>
</method>
<method name="track_find_key" qualifiers="const">
<return type="int" />
<param index="0" name="track_idx" type="int" />

6
engine/doc/classes/AnimationLibrary.xml
View file

@ -31,6 +31,12 @@
Returns the keys for the [Animation]s stored in the library.
</description>
</method>
<method name="get_animation_list_size" qualifiers="const">
<return type="int" />
<description>
Returns the key count for the [Animation]s stored in the library.
</description>
</method>
<method name="has_animation" qualifiers="const">
<return type="bool" />
<param index="0" name="name" type="StringName" />

58
engine/doc/classes/AnimationMixer.xml
View file

@ -112,13 +112,13 @@
The most basic example is applying position to [CharacterBody3D]:
[codeblocks]
[gdscript]
var current_rotation: Quaternion
var current_rotation
func _process(delta):
if Input.is_action_just_pressed("animate"):
current_rotation = get_quaternion()
state_machine.travel("Animate")
var velocity: Vector3 = current_rotation * animation_tree.get_root_motion_position() / delta
var velocity = current_rotation * animation_tree.get_root_motion_position() / delta
set_velocity(velocity)
move_and_slide()
[/gdscript]
@ -130,7 +130,20 @@
if Input.is_action_just_pressed("animate"):
state_machine.travel("Animate")
set_quaternion(get_quaternion() * animation_tree.get_root_motion_rotation())
var velocity: Vector3 = (animation_tree.get_root_motion_rotation_accumulator().inverse() * get_quaternion()) * animation_tree.get_root_motion_position() / delta
var velocity = (animation_tree.get_root_motion_rotation_accumulator().inverse() * get_quaternion()) * animation_tree.get_root_motion_position() / delta
set_velocity(velocity)
move_and_slide()
[/gdscript]
[/codeblocks]
If [member root_motion_local] is [code]true[/code], return the pre-multiplied translation value with the inverted rotation.
In this case, the code can be written as follows:
[codeblocks]
[gdscript]
func _process(delta):
if Input.is_action_just_pressed("animate"):
state_machine.travel("Animate")
set_quaternion(get_quaternion() * animation_tree.get_root_motion_rotation())
var velocity = get_quaternion() * animation_tree.get_root_motion_position() / delta
set_velocity(velocity)
move_and_slide()
[/gdscript]
@ -145,13 +158,13 @@
For example, if an animation with only one key [code]Vector3(0, 0, 0)[/code] is played in the previous frame and then an animation with only one key [code]Vector3(1, 0, 1)[/code] is played in the next frame, the difference can be calculated as follows:
[codeblocks]
[gdscript]
var prev_root_motion_position_accumulator: Vector3
var prev_root_motion_position_accumulator
func _process(delta):
if Input.is_action_just_pressed("animate"):
state_machine.travel("Animate")
var current_root_motion_position_accumulator: Vector3 = animation_tree.get_root_motion_position_accumulator()
var difference: Vector3 = current_root_motion_position_accumulator - prev_root_motion_position_accumulator
var current_root_motion_position_accumulator = animation_tree.get_root_motion_position_accumulator()
var difference = current_root_motion_position_accumulator - prev_root_motion_position_accumulator
prev_root_motion_position_accumulator = current_root_motion_position_accumulator
transform.origin += difference
[/gdscript]
@ -185,13 +198,13 @@
For example, if an animation with only one key [code]Quaternion(0, 0, 0, 1)[/code] is played in the previous frame and then an animation with only one key [code]Quaternion(0, 0.707, 0, 0.707)[/code] is played in the next frame, the difference can be calculated as follows:
[codeblocks]
[gdscript]
var prev_root_motion_rotation_accumulator: Quaternion
var prev_root_motion_rotation_accumulator
func _process(delta):
if Input.is_action_just_pressed("animate"):
state_machine.travel("Animate")
var current_root_motion_rotation_accumulator: Quaternion = animation_tree.get_root_motion_rotation_accumulator()
var difference: Quaternion = prev_root_motion_rotation_accumulator.inverse() * current_root_motion_rotation_accumulator
var current_root_motion_rotation_accumulator = animation_tree.get_root_motion_rotation_accumulator()
var difference = prev_root_motion_rotation_accumulator.inverse() * current_root_motion_rotation_accumulator
prev_root_motion_rotation_accumulator = current_root_motion_rotation_accumulator
transform.basis *= Basis(difference)
[/gdscript]
@ -208,8 +221,8 @@
The most basic example is applying scale to [CharacterBody3D]:
[codeblocks]
[gdscript]
var current_scale: Vector3 = Vector3(1, 1, 1)
var scale_accum: Vector3 = Vector3(1, 1, 1)
var current_scale = Vector3(1, 1, 1)
var scale_accum = Vector3(1, 1, 1)
func _process(delta):
if Input.is_action_just_pressed("animate"):
@ -229,13 +242,13 @@
For example, if an animation with only one key [code]Vector3(1, 1, 1)[/code] is played in the previous frame and then an animation with only one key [code]Vector3(2, 2, 2)[/code] is played in the next frame, the difference can be calculated as follows:
[codeblocks]
[gdscript]
var prev_root_motion_scale_accumulator: Vector3
var prev_root_motion_scale_accumulator
func _process(delta):
if Input.is_action_just_pressed("animate"):
state_machine.travel("Animate")
var current_root_motion_scale_accumulator: Vector3 = animation_tree.get_root_motion_scale_accumulator()
var difference: Vector3 = current_root_motion_scale_accumulator - prev_root_motion_scale_accumulator
var current_root_motion_scale_accumulator = animation_tree.get_root_motion_scale_accumulator()
var difference = current_root_motion_scale_accumulator - prev_root_motion_scale_accumulator
prev_root_motion_scale_accumulator = current_root_motion_scale_accumulator
transform.basis = transform.basis.scaled(difference)
[/gdscript]
@ -304,6 +317,9 @@
This is used by the editor. If set to [code]true[/code], the scene will be saved with the effects of the reset animation (the animation with the key [code]"RESET"[/code]) applied as if it had been seeked to time 0, with the editor keeping the values that the scene had before saving.
This makes it more convenient to preview and edit animations in the editor, as changes to the scene will not be saved as long as they are set in the reset animation.
</member>
<member name="root_motion_local" type="bool" setter="set_root_motion_local" getter="is_root_motion_local">
If [code]true[/code], [method get_root_motion_position] value is extracted as a local translation value before blending. In other words, it is treated like the translation is done after the rotation.
</member>
<member name="root_motion_track" type="NodePath" setter="set_root_motion_track" getter="get_root_motion_track" default="NodePath(&quot;&quot;)">
The path to the Animation track used for root motion. Paths must be valid scene-tree paths to a node, and must be specified starting from the parent node of the node that will reproduce the animation. The [member root_motion_track] uses the same format as [method Animation.track_set_path], but note that a bone must be specified.
If the track has type [constant Animation.TYPE_POSITION_3D], [constant Animation.TYPE_ROTATION_3D], or [constant Animation.TYPE_SCALE_3D] the transformation will be canceled visually, and the animation will appear to stay in place. See also [method get_root_motion_position], [method get_root_motion_rotation], [method get_root_motion_scale], and [RootMotionView].
@ -376,7 +392,19 @@
</constant>
<constant name="ANIMATION_CALLBACK_MODE_DISCRETE_FORCE_CONTINUOUS" value="2" enum="AnimationCallbackModeDiscrete">
Always treat the [constant Animation.UPDATE_DISCRETE] track value as [constant Animation.UPDATE_CONTINUOUS] with [constant Animation.INTERPOLATION_NEAREST]. This is the default behavior for [AnimationTree].
If a value track has non-numeric type key values, it is internally converted to use [constant ANIMATION_CALLBACK_MODE_DISCRETE_RECESSIVE] with [constant Animation.UPDATE_DISCRETE].
If a value track has un-interpolatable type key values, it is internally converted to use [constant ANIMATION_CALLBACK_MODE_DISCRETE_RECESSIVE] with [constant Animation.UPDATE_DISCRETE].
Un-interpolatable type list:
- [constant @GlobalScope.TYPE_NIL]
- [constant @GlobalScope.TYPE_NODE_PATH]
- [constant @GlobalScope.TYPE_RID]
- [constant @GlobalScope.TYPE_OBJECT]
- [constant @GlobalScope.TYPE_CALLABLE]
- [constant @GlobalScope.TYPE_SIGNAL]
- [constant @GlobalScope.TYPE_DICTIONARY]
- [constant @GlobalScope.TYPE_PACKED_BYTE_ARRAY]
[constant @GlobalScope.TYPE_BOOL] and [constant @GlobalScope.TYPE_INT] are treated as [constant @GlobalScope.TYPE_FLOAT] during blending and rounded when the result is retrieved.
It is same for arrays and vectors with them such as [constant @GlobalScope.TYPE_PACKED_INT32_ARRAY] or [constant @GlobalScope.TYPE_VECTOR2I], they are treated as [constant @GlobalScope.TYPE_PACKED_FLOAT32_ARRAY] or [constant @GlobalScope.TYPE_VECTOR2]. Also note that for arrays, the size is also interpolated.
[constant @GlobalScope.TYPE_STRING] and [constant @GlobalScope.TYPE_STRING_NAME] are interpolated between character codes and lengths, but note that there is a difference in algorithm between interpolation between keys and interpolation by blending.
</constant>
</constants>
</class>

17
engine/doc/classes/AnimationNode.xml
View file

@ -63,7 +63,7 @@
When inheriting from [AnimationRootNode], implement this virtual method to return whether the [param parameter] is read-only. Parameters are custom local memory used for your animation nodes, given a resource can be reused in multiple trees.
</description>
</method>
<method name="_process" qualifiers="virtual const" deprecated="Currently this is mostly useless as there is a lack of many APIs to extend AnimationNode by GDScript. It is planned that a more flexible API using structures will be provided in the future.">
<method name="_process" qualifiers="virtual" deprecated="Currently this is mostly useless as there is a lack of many APIs to extend AnimationNode by GDScript. It is planned that a more flexible API using structures will be provided in the future.">
<return type="float" />
<param index="0" name="time" type="float" />
<param index="1" name="seek" type="bool" />
@ -152,11 +152,24 @@
Gets the value of a parameter. Parameters are custom local memory used for your animation nodes, given a resource can be reused in multiple trees.
</description>
</method>
<method name="get_processing_animation_tree_instance_id" qualifiers="const">
<return type="int" />
<description>
Returns the object id of the [AnimationTree] that owns this node.
[b]Note:[/b] This method should only be called from within the [method AnimationNodeExtension._process_animation_node] method, and will return an invalid id otherwise.
</description>
</method>
<method name="is_path_filtered" qualifiers="const">
<return type="bool" />
<param index="0" name="path" type="NodePath" />
<description>
Returns whether the given path is filtered.
Returns [code]true[/code] if the given path is filtered.
</description>
</method>
<method name="is_process_testing" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if this animation node is being processed in test-only mode.
</description>
</method>
<method name="remove_input">

4
engine/doc/classes/AnimationNodeAnimation.xml
View file

@ -12,6 +12,10 @@
<link title="Third Person Shooter (TPS) Demo">https://godotengine.org/asset-library/asset/2710</link>
</tutorials>
<members>
<member name="advance_on_start" type="bool" setter="set_advance_on_start" getter="is_advance_on_start" default="false">
If [code]true[/code], on receiving a request to play an animation from the start, the first frame is not drawn, but only processed, and playback starts from the next frame.
See also the notes of [method AnimationPlayer.play].
</member>
<member name="animation" type="StringName" setter="set_animation" getter="get_animation" default="&amp;&quot;&quot;">
Animation to use as an output. It is one of the animations provided by [member AnimationTree.anim_player].
</member>

4
engine/doc/classes/AnimationNodeBlendSpace2D.xml
View file

@ -5,7 +5,7 @@
</brief_description>
<description>
A resource used by [AnimationNodeBlendTree].
[AnimationNodeBlendSpace1D] represents a virtual 2D space on which [AnimationRootNode]s are placed. Outputs the linear blend of the three adjacent animations using a [Vector2] weight. Adjacent in this context means the three [AnimationRootNode]s making up the triangle that contains the current value.
[AnimationNodeBlendSpace2D] represents a virtual 2D space on which [AnimationRootNode]s are placed. Outputs the linear blend of the three adjacent animations using a [Vector2] weight. Adjacent in this context means the three [AnimationRootNode]s making up the triangle that contains the current value.
You can add vertices to the blend space with [method add_blend_point] and automatically triangulate it by setting [member auto_triangles] to [code]true[/code]. Otherwise, use [method add_triangle] and [method remove_triangle] to triangulate the blend space by hand.
</description>
<tutorials>
@ -93,7 +93,7 @@
<param index="0" name="point" type="int" />
<param index="1" name="pos" type="Vector2" />
<description>
Updates the position of the point at index [param point] on the blend axis.
Updates the position of the point at index [param point] in the blend space.
</description>
</method>
</methods>

38
engine/doc/classes/AnimationNodeExtension.xml Normal file
View file

@ -0,0 +1,38 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimationNodeExtension" inherits="AnimationNode" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Base class for extending [AnimationRootNode]s from GDScript, C#, or C++.
</brief_description>
<description>
[AnimationNodeExtension] exposes the APIs of [AnimationRootNode] to allow users to extend it from GDScript, C#, or C++. This class is not meant to be used directly, but to be extended by other classes. It is used to create custom nodes for the [AnimationTree] system.
</description>
<tutorials>
</tutorials>
<methods>
<method name="_process_animation_node" qualifiers="virtual">
<return type="PackedFloat32Array" />
<param index="0" name="playback_info" type="PackedFloat64Array" />
<param index="1" name="test_only" type="bool" />
<description>
A version of the [method AnimationNode._process] method that is meant to be overridden by custom nodes. It returns a [PackedFloat32Array] with the processed animation data.
The [PackedFloat64Array] parameter contains the playback information, containing the following values encoded as floating point numbers (in order): playback time and delta, start and end times, whether a seek was requested (encoded as a float greater than [code]0[/code]), whether the seek request was externally requested (encoded as a float greater than [code]0[/code]), the current [enum Animation.LoopedFlag] (encoded as a float), and the current blend weight.
The function must return a [PackedFloat32Array] of the node's time info, containing the following values (in order): animation length, time position, delta, [enum Animation.LoopMode] (encoded as a float), whether the animation is about to end (encoded as a float greater than [code]0[/code]) and whether the animation is infinite (encoded as a float greater than [code]0[/code]). All values must be included in the returned array.
</description>
</method>
<method name="get_remaining_time" qualifiers="static">
<return type="float" />
<param index="0" name="node_info" type="PackedFloat32Array" />
<param index="1" name="break_loop" type="bool" />
<description>
Returns the animation's remaining time for the given node info. For looping animations, it will only return the remaining time if [param break_loop] is [code]true[/code], a large integer value will be returned otherwise.
</description>
</method>
<method name="is_looping" qualifiers="static">
<return type="bool" />
<param index="0" name="node_info" type="PackedFloat32Array" />
<description>
Returns [code]true[/code] if the animation for the given [param node_info] is looping.
</description>
</method>
</methods>
</class>

4
engine/doc/classes/AnimationNodeOneShot.xml
View file

@ -70,14 +70,14 @@
If [code]true[/code], breaks the loop at the end of the loop cycle for transition, even if the animation is looping.
</member>
<member name="fadein_curve" type="Curve" setter="set_fadein_curve" getter="get_fadein_curve">
Determines how cross-fading between animations is eased. If empty, the transition will be linear.
Determines how cross-fading between animations is eased. If empty, the transition will be linear. Should be a unit [Curve].
</member>
<member name="fadein_time" type="float" setter="set_fadein_time" getter="get_fadein_time" default="0.0">
The fade-in duration. For example, setting this to [code]1.0[/code] for a 5 second length animation will produce a cross-fade that starts at 0 second and ends at 1 second during the animation.
[b]Note:[/b] [AnimationNodeOneShot] transitions the current state after the end of the fading. When [AnimationNodeOutput] is considered as the most upstream, so the [member fadein_time] is scaled depending on the downstream delta. For example, if this value is set to [code]1.0[/code] and a [AnimationNodeTimeScale] with a value of [code]2.0[/code] is chained downstream, the actual processing time will be 0.5 second.
</member>
<member name="fadeout_curve" type="Curve" setter="set_fadeout_curve" getter="get_fadeout_curve">
Determines how cross-fading between animations is eased. If empty, the transition will be linear.
Determines how cross-fading between animations is eased. If empty, the transition will be linear. Should be a unit [Curve].
</member>
<member name="fadeout_time" type="float" setter="set_fadeout_time" getter="get_fadeout_time" default="0.0">
The fade-out duration. For example, setting this to [code]1.0[/code] for a 5 second length animation will produce a cross-fade that starts at 4 second and ends at 5 second during the animation.

1
engine/doc/classes/AnimationNodeStateMachine.xml
View file

@ -5,7 +5,6 @@
</brief_description>
<description>
Contains multiple [AnimationRootNode]s representing animation states, connected in a graph. State transitions can be configured to happen automatically or via code, using a shortest-path algorithm. Retrieve the [AnimationNodeStateMachinePlayback] object from the [AnimationTree] node to control it programmatically.
[b]Example:[/b]
[codeblocks]
[gdscript]
var state_machine = $AnimationTree.get("parameters/playback")

1
engine/doc/classes/AnimationNodeStateMachinePlayback.xml
View file

@ -5,7 +5,6 @@
</brief_description>
<description>
Allows control of [AnimationTree] state machines created with [AnimationNodeStateMachine]. Retrieve with [code]$AnimationTree.get("parameters/playback")[/code].
[b]Example:[/b]
[codeblocks]
[gdscript]
var state_machine = $AnimationTree.get("parameters/playback")

6
engine/doc/classes/AnimationNodeStateMachineTransition.xml
View file

@ -26,7 +26,7 @@
Use an expression as a condition for state machine transitions. It is possible to create complex animation advance conditions for switching between states and gives much greater flexibility for creating complex state machines by directly interfacing with the script code.
</member>
<member name="advance_mode" type="int" setter="set_advance_mode" getter="get_advance_mode" enum="AnimationNodeStateMachineTransition.AdvanceMode" default="1">
Determines whether the transition should disabled, enabled when using [method AnimationNodeStateMachinePlayback.travel], or traversed automatically if the [member advance_condition] and [member advance_expression] checks are true (if assigned).
Determines whether the transition should be disabled, enabled when using [method AnimationNodeStateMachinePlayback.travel], or traversed automatically if the [member advance_condition] and [member advance_expression] checks are [code]true[/code] (if assigned).
</member>
<member name="break_loop_at_end" type="bool" setter="set_break_loop_at_end" getter="is_loop_broken_at_end" default="false">
If [code]true[/code], breaks the loop at the end of the loop cycle for transition, even if the animation is looping.
@ -41,7 +41,7 @@
The transition type.
</member>
<member name="xfade_curve" type="Curve" setter="set_xfade_curve" getter="get_xfade_curve">
Ease curve for better control over cross-fade between this state and the next.
Ease curve for better control over cross-fade between this state and the next. Should be a unit [Curve].
</member>
<member name="xfade_time" type="float" setter="set_xfade_time" getter="get_xfade_time" default="0.0">
The time to cross-fade between this state and the next.
@ -72,7 +72,7 @@
Only use this transition during [method AnimationNodeStateMachinePlayback.travel].
</constant>
<constant name="ADVANCE_MODE_AUTO" value="2" enum="AdvanceMode">
Automatically use this transition if the [member advance_condition] and [member advance_expression] checks are true (if assigned).
Automatically use this transition if the [member advance_condition] and [member advance_expression] checks are [code]true[/code] (if assigned).
</constant>
</constants>
</class>

5
engine/doc/classes/AnimationNodeTimeSeek.xml
View file

@ -30,4 +30,9 @@
<tutorials>
<link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>
</tutorials>
<members>
<member name="explicit_elapse" type="bool" setter="set_explicit_elapse" getter="is_explicit_elapse" default="true">
If [code]true[/code], some processes are executed to handle keys between seeks, such as calculating root motion and finding the nearest discrete key.
</member>
</members>
</class>

2
engine/doc/classes/AnimationNodeTransition.xml
View file

@ -96,7 +96,7 @@
The number of enabled input ports for this animation node.
</member>
<member name="xfade_curve" type="Curve" setter="set_xfade_curve" getter="get_xfade_curve">
Determines how cross-fading between animations is eased. If empty, the transition will be linear.
Determines how cross-fading between animations is eased. If empty, the transition will be linear. Should be a unit [Curve].
</member>
<member name="xfade_time" type="float" setter="set_xfade_time" getter="get_xfade_time" default="0.0">
Cross-fading time (in seconds) between each animation connected to the inputs.

89
engine/doc/classes/AnimationPlayer.xml
View file

@ -75,6 +75,24 @@
Returns the node which node path references will travel from.
</description>
</method>
<method name="get_section_end_time" qualifiers="const">
<return type="float" />
<description>
Returns the end time of the section currently being played.
</description>
</method>
<method name="get_section_start_time" qualifiers="const">
<return type="float" />
<description>
Returns the start time of the section currently being played.
</description>
</method>
<method name="has_section" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if an animation is currently playing with section.
</description>
</method>
<method name="is_playing" qualifiers="const">
<return type="bool" />
<description>
@ -110,6 +128,54 @@
This method is a shorthand for [method play] with [code]custom_speed = -1.0[/code] and [code]from_end = true[/code], so see its description for more information.
</description>
</method>
<method name="play_section">
<return type="void" />
<param index="0" name="name" type="StringName" default="&amp;&quot;&quot;" />
<param index="1" name="start_time" type="float" default="-1" />
<param index="2" name="end_time" type="float" default="-1" />
<param index="3" name="custom_blend" type="float" default="-1" />
<param index="4" name="custom_speed" type="float" default="1.0" />
<param index="5" name="from_end" type="bool" default="false" />
<description>
Plays the animation with key [param name] and the section starting from [param start_time] and ending on [param end_time]. See also [method play].
Setting [param start_time] to a value outside the range of the animation means the start of the animation will be used instead, and setting [param end_time] to a value outside the range of the animation means the end of the animation will be used instead. [param start_time] cannot be equal to [param end_time].
</description>
</method>
<method name="play_section_backwards">
<return type="void" />
<param index="0" name="name" type="StringName" default="&amp;&quot;&quot;" />
<param index="1" name="start_time" type="float" default="-1" />
<param index="2" name="end_time" type="float" default="-1" />
<param index="3" name="custom_blend" type="float" default="-1" />
<description>
Plays the animation with key [param name] and the section starting from [param start_time] and ending on [param end_time] in reverse.
This method is a shorthand for [method play_section] with [code]custom_speed = -1.0[/code] and [code]from_end = true[/code], see its description for more information.
</description>
</method>
<method name="play_section_with_markers">
<return type="void" />
<param index="0" name="name" type="StringName" default="&amp;&quot;&quot;" />
<param index="1" name="start_marker" type="StringName" default="&amp;&quot;&quot;" />
<param index="2" name="end_marker" type="StringName" default="&amp;&quot;&quot;" />
<param index="3" name="custom_blend" type="float" default="-1" />
<param index="4" name="custom_speed" type="float" default="1.0" />
<param index="5" name="from_end" type="bool" default="false" />
<description>
Plays the animation with key [param name] and the section starting from [param start_marker] and ending on [param end_marker].
If the start marker is empty, the section starts from the beginning of the animation. If the end marker is empty, the section ends on the end of the animation. See also [method play].
</description>
</method>
<method name="play_section_with_markers_backwards">
<return type="void" />
<param index="0" name="name" type="StringName" default="&amp;&quot;&quot;" />
<param index="1" name="start_marker" type="StringName" default="&amp;&quot;&quot;" />
<param index="2" name="end_marker" type="StringName" default="&amp;&quot;&quot;" />
<param index="3" name="custom_blend" type="float" default="-1" />
<description>
Plays the animation with key [param name] and the section starting from [param start_marker] and ending on [param end_marker] in reverse.
This method is a shorthand for [method play_section_with_markers] with [code]custom_speed = -1.0[/code] and [code]from_end = true[/code], see its description for more information.
</description>
</method>
<method name="play_with_capture">
<return type="void" />
<param index="0" name="name" type="StringName" default="&amp;&quot;&quot;" />
@ -139,6 +205,12 @@
[b]Note:[/b] If a looped animation is currently playing, the queued animation will never play unless the looped animation is stopped somehow.
</description>
</method>
<method name="reset_section">
<return type="void" />
<description>
Resets the current section if section is set.
</description>
</method>
<method name="seek">
<return type="void" />
<param index="0" name="seconds" type="float" />
@ -180,6 +252,23 @@
Sets the node which node path references will travel from.
</description>
</method>
<method name="set_section">
<return type="void" />
<param index="0" name="start_time" type="float" default="-1" />
<param index="1" name="end_time" type="float" default="-1" />
<description>
Changes the start and end times of the section being played. The current playback position will be clamped within the new section. See also [method play_section].
</description>
</method>
<method name="set_section_with_markers">
<return type="void" />
<param index="0" name="start_marker" type="StringName" default="&amp;&quot;&quot;" />
<param index="1" name="end_marker" type="StringName" default="&amp;&quot;&quot;" />
<description>
Changes the start and end markers of the section being played. The current playback position will be clamped within the new section. See also [method play_section_with_markers].
If the argument is empty, the section uses the beginning or end of the animation. If both are empty, it means that the section is not set.
</description>
</method>
<method name="stop">
<return type="void" />
<param index="0" name="keep_state" type="bool" default="false" />

4
engine/doc/classes/Area2D.xml
View file

@ -132,7 +132,7 @@
<description>
Emitted when a [Shape2D] of the received [param area] enters a shape of this area. Requires [member monitoring] to be set to [code]true[/code].
[param local_shape_index] and [param area_shape_index] contain indices of the interacting shapes from this area and the other area, respectively. [param area_rid] contains the [RID] of the other area. These values can be used with the [PhysicsServer2D].
[b]Example of getting the[/b] [CollisionShape2D] [b]node from the shape index:[/b]
[b]Example:[/b] Get the [CollisionShape2D] node from the shape index:
[codeblocks]
[gdscript]
var other_shape_owner = area.shape_find_owner(area_shape_index)
@ -174,7 +174,7 @@
<description>
Emitted when a [Shape2D] of the received [param body] enters a shape of this area. [param body] can be a [PhysicsBody2D] or a [TileMap]. [TileMap]s are detected if their [TileSet] has collision shapes configured. Requires [member monitoring] to be set to [code]true[/code].
[param local_shape_index] and [param body_shape_index] contain indices of the interacting shapes from this area and the interacting body, respectively. [param body_rid] contains the [RID] of the body. These values can be used with the [PhysicsServer2D].
[b]Example of getting the[/b] [CollisionShape2D] [b]node from the shape index:[/b]
[b]Example:[/b] Get the [CollisionShape2D] node from the shape index:
[codeblocks]
[gdscript]
var body_shape_owner = body.shape_find_owner(body_shape_index)

4
engine/doc/classes/Area3D.xml
View file

@ -156,7 +156,7 @@
<description>
Emitted when a [Shape3D] of the received [param area] enters a shape of this area. Requires [member monitoring] to be set to [code]true[/code].
[param local_shape_index] and [param area_shape_index] contain indices of the interacting shapes from this area and the other area, respectively. [param area_rid] contains the [RID] of the other area. These values can be used with the [PhysicsServer3D].
[b]Example of getting the[/b] [CollisionShape3D] [b]node from the shape index:[/b]
[b]Example:[/b] Get the [CollisionShape3D] node from the shape index:
[codeblocks]
[gdscript]
var other_shape_owner = area.shape_find_owner(area_shape_index)
@ -198,7 +198,7 @@
<description>
Emitted when a [Shape3D] of the received [param body] enters a shape of this area. [param body] can be a [PhysicsBody3D] or a [GridMap]. [GridMap]s are detected if their [MeshLibrary] has collision shapes configured. Requires [member monitoring] to be set to [code]true[/code].
[param local_shape_index] and [param body_shape_index] contain indices of the interacting shapes from this area and the interacting body, respectively. [param body_rid] contains the [RID] of the body. These values can be used with the [PhysicsServer3D].
[b]Example of getting the[/b] [CollisionShape3D] [b]node from the shape index:[/b]
[b]Example:[/b] Get the [CollisionShape3D] node from the shape index:
[codeblocks]
[gdscript]
var body_shape_owner = body.shape_find_owner(body_shape_index)

107
engine/doc/classes/Array.xml
View file

@ -4,8 +4,7 @@
A built-in data structure that holds a sequence of elements.
</brief_description>
<description>
An array data structure that can contain a sequence of elements of any [Variant] type. Elements are accessed by a numerical index starting at 0. Negative indices are used to count from the back (-1 is the last element, -2 is the second to last, etc.).
[b]Example:[/b]
An array data structure that can contain a sequence of elements of any [Variant] type. Elements are accessed by a numerical index starting at [code]0[/code]. Negative indices are used to count from the back ([code]-1[/code] is the last element, [code]-2[/code] is the second to last, etc.).
[codeblocks]
[gdscript]
var array = ["First", 2, 3, "Last"]
@ -18,14 +17,14 @@
print(array[-3]) # Prints "Second"
[/gdscript]
[csharp]
var array = new Godot.Collections.Array{"First", 2, 3, "Last"};
Godot.Collections.Array array = ["First", 2, 3, "Last"];
GD.Print(array[0]); // Prints "First"
GD.Print(array[2]); // Prints 3
GD.Print(array[array.Count - 1]); // Prints "Last"
GD.Print(array[^1]); // Prints "Last"
array[2] = "Second";
array[1] = "Second";
GD.Print(array[1]); // Prints "Second"
GD.Print(array[array.Count - 3]); // Prints "Second"
GD.Print(array[^3]); // Prints "Second"
[/csharp]
[/codeblocks]
[b]Note:[/b] Arrays are always passed by [b]reference[/b]. To get a copy of an array that can be modified independently of the original array, use [method duplicate].
@ -184,17 +183,17 @@
public override void _Ready()
{
// Prints true (3/3 elements evaluate to true).
// Prints True (3/3 elements evaluate to true).
GD.Print(new Godot.Collections.Array&gt;int&lt; { 6, 10, 6 }.All(GreaterThan5));
// Prints false (1/3 elements evaluate to true).
// Prints False (1/3 elements evaluate to true).
GD.Print(new Godot.Collections.Array&gt;int&lt; { 4, 10, 4 }.All(GreaterThan5));
// Prints false (0/3 elements evaluate to true).
// Prints False (0/3 elements evaluate to true).
GD.Print(new Godot.Collections.Array&gt;int&lt; { 4, 4, 4 }.All(GreaterThan5));
// Prints true (0/0 elements evaluate to true).
// Prints True (0/0 elements evaluate to true).
GD.Print(new Godot.Collections.Array&gt;int&lt; { }.All(GreaterThan5));
// Same as the first line above, but using a lambda function.
GD.Print(new Godot.Collections.Array&gt;int&lt; { 6, 10, 6 }.All(element =&gt; element &gt; 5)); // Prints true
GD.Print(new Godot.Collections.Array&gt;int&lt; { 6, 10, 6 }.All(element =&gt; element &gt; 5)); // Prints True
}
[/csharp]
[/codeblocks]
@ -243,7 +242,7 @@
var numbers = [1, 2, 3]
var extra = [4, 5, 6]
numbers.append_array(extra)
print(nums) # Prints [1, 2, 3, 4, 5, 6]
print(numbers) # Prints [1, 2, 3, 4, 5, 6]
[/codeblock]
</description>
</method>
@ -325,6 +324,7 @@
<param index="0" name="value" type="Variant" />
<description>
Returns the number of times an element is in the array.
To count how many elements in an array satisfy a condition, see [method reduce].
</description>
</method>
<method name="duplicate" qualifiers="const">
@ -358,7 +358,7 @@
print(array) # Prints [2, 2, 2, 2, 2]
[/gdscript]
[csharp]
var array = new Godot.Collections.Array();
Godot.Collections.Array array = [];
array.Resize(5);
array.Fill(2);
GD.Print(array); // Prints [2, 2, 2, 2, 2]
@ -396,6 +396,25 @@
[b]Note:[/b] For performance reasons, the search is affected by [param what]'s [enum Variant.Type]. For example, [code]7[/code] ([int]) and [code]7.0[/code] ([float]) are not considered equal for this method.
</description>
</method>
<method name="find_custom" qualifiers="const">
<return type="int" />
<param index="0" name="method" type="Callable" />
<param index="1" name="from" type="int" default="0" />
<description>
Returns the index of the [b]first[/b] element in the array that causes [param method] to return [code]true[/code], or [code]-1[/code] if there are none. The search's start can be specified with [param from], continuing to the end of the array.
[param method] is a callable that takes an element of the array, and returns a [bool].
[b]Note:[/b] If you just want to know whether the array contains [i]anything[/i] that satisfies [param method], use [method any].
[codeblocks]
[gdscript]
func is_even(number):
return number % 2 == 0
func _ready():
print([1, 3, 4, 7].find_custom(is_even.bind())) # Prints 2
[/gdscript]
[/codeblocks]
</description>
</method>
<method name="front" qualifiers="const">
<return type="Variant" />
<description>
@ -403,6 +422,13 @@
[b]Note:[/b] Unlike with the [code][][/code] operator ([code]array[0][/code]), an error is generated without stopping project execution.
</description>
</method>
<method name="get" qualifiers="const">
<return type="Variant" />
<param index="0" name="index" type="int" />
<description>
Returns the element at the given [param index] in the array. This is the same as using the [code][][/code] operator ([code]array[index][/code]).
</description>
</method>
<method name="get_typed_builtin" qualifiers="const">
<return type="int" />
<description>
@ -434,12 +460,12 @@
print(["inside", 7].has("7")) # Prints false
[/gdscript]
[csharp]
var arr = new Godot.Collections.Array { "inside", 7 };
Godot.Collections.Array arr = ["inside", 7];
// By C# convention, this method is renamed to `Contains`.
GD.Print(arr.Contains("inside")); // Prints true
GD.Print(arr.Contains("outside")); // Prints false
GD.Print(arr.Contains(7)); // Prints true
GD.Print(arr.Contains("7")); // Prints false
GD.Print(arr.Contains("inside")); // Prints True
GD.Print(arr.Contains("outside")); // Prints False
GD.Print(arr.Contains(7)); // Prints True
GD.Print(arr.Contains("7")); // Prints False
[/csharp]
[/codeblocks]
In GDScript, this is equivalent to the [code]in[/code] operator:
@ -547,7 +573,7 @@
print([1, 2, 3.25, "Hi"].pick_random())
[/gdscript]
[csharp]
var array = new Godot.Collections.Array { 1, 2, 3.25f, "Hi" };
Godot.Collections.Array array = [1, 2, 3.25f, "Hi"];
GD.Print(array.PickRandom()); // May print 1, 2, 3.25, or "Hi".
[/csharp]
[/codeblocks]
@ -611,15 +637,26 @@
If [method max] is not desirable, this method may also be used to implement a custom comparator:
[codeblock]
func _ready():
var arr = [Vector2(5, 0), Vector2(3, 4), Vector2(1, 2)]
var arr = [Vector2i(5, 0), Vector2i(3, 4), Vector2i(1, 2)]
var longest_vec = arr.reduce(func(max, vec): return vec if is_length_greater(vec, max) else max)
print(longest_vec) # Prints Vector2(3, 4).
print(longest_vec) # Prints (3, 4)
func is_length_greater(a, b):
return a.length() &gt; b.length()
[/codeblock]
See also [method map], [method filter], [method any] and [method all].
This method can also be used to count how many elements in an array satisfy a certain condition, similar to [method count]:
[codeblock]
func is_even(number):
return number % 2 == 0
func _ready():
var arr = [1, 2, 3, 4, 5]
# If the current element is even, increment count, otherwise leave count the same.
var even_count = arr.reduce(func(count, next): return count + 1 if is_even(next) else count, 0)
print(even_count) # Prints 2
[/codeblock]
See also [method map], [method filter], [method any], and [method all].
</description>
</method>
<method name="remove_at">
@ -655,6 +692,22 @@
Returns the index of the [b]last[/b] occurrence of [param what] in this array, or [code]-1[/code] if there are none. The search's start can be specified with [param from], continuing to the beginning of the array. This method is the reverse of [method find].
</description>
</method>
<method name="rfind_custom" qualifiers="const">
<return type="int" />
<param index="0" name="method" type="Callable" />
<param index="1" name="from" type="int" default="-1" />
<description>
Returns the index of the [b]last[/b] element of the array that causes [param method] to return [code]true[/code], or [code]-1[/code] if there are none. The search's start can be specified with [param from], continuing to the beginning of the array. This method is the reverse of [method find_custom].
</description>
</method>
<method name="set">
<return type="void" />
<param index="0" name="index" type="int" />
<param index="1" name="value" type="Variant" />
<description>
Sets the value of the element at the given [param index] to the given [param value]. This will not change the size of the array, it only changes the value at an index already in the array. This is the same as using the [code][][/code] operator ([code]array[index] = value[/code]).
</description>
</method>
<method name="shuffle">
<return type="void" />
<description>
@ -702,7 +755,7 @@
print(numbers) # Prints [2.5, 5, 8, 10]
[/gdscript]
[csharp]
var numbers = new Godot.Collections.Array { 10, 5, 2.5, 8 };
Godot.Collections.Array numbers = [10, 5, 2.5, 8];
numbers.Sort();
GD.Print(numbers); // Prints [2.5, 5, 8, 10]
[/csharp]
@ -715,7 +768,7 @@
<param index="0" name="func" type="Callable" />
<description>
Sorts the array using a custom [Callable].
[param func] is called as many times as necessary, receiving two array elements as arguments. The function should return [code]true[/code] if the first element should be moved [i]behind[/i] the second one, otherwise it should return [code]false[/code].
[param func] is called as many times as necessary, receiving two array elements as arguments. The function should return [code]true[/code] if the first element should be moved [i]before[/i] the second one, otherwise it should return [code]false[/code].
[codeblock]
func sort_ascending(a, b):
if a[1] &lt; b[1]:
@ -728,7 +781,7 @@
print(my_items) # Prints [["Rice", 4], ["Tomato", 5], ["Apple", 9]]
# Sort descending, using a lambda function.
my_items.sort_custom(func(a, b): return a[0] &gt; b[0])
my_items.sort_custom(func(a, b): return a[1] &gt; b[1])
print(my_items) # Prints [["Apple", 9], ["Tomato", 5], ["Rice", 4]]
[/codeblock]
It may also be necessary to use this method to sort strings by natural order, with [method String.naturalnocasecmp_to], as in the following example:
@ -764,8 +817,8 @@
[/gdscript]
[csharp]
// Note that concatenation is not possible with C#'s native Array type.
var array1 = new Godot.Collections.Array{"One", 2};
var array2 = new Godot.Collections.Array{3, "Four"};
Godot.Collections.Array array1 = ["One", 2];
Godot.Collections.Array array2 = [3, "Four"];
GD.Print(array1 + array2); // Prints ["One", 2, 3, "Four"]
[/csharp]
[/codeblocks]

17
engine/doc/classes/ArrayMesh.xml
View file

@ -25,16 +25,16 @@
m.mesh = arr_mesh
[/gdscript]
[csharp]
var vertices = new Vector3[]
{
Vector3[] vertices =
[
new Vector3(0, 1, 0),
new Vector3(1, 0, 0),
new Vector3(0, 0, 1),
};
];
// Initialize the ArrayMesh.
var arrMesh = new ArrayMesh();
var arrays = new Godot.Collections.Array();
Godot.Collections.Array arrays = [];
arrays.Resize((int)Mesh.ArrayType.Max);
arrays[(int)Mesh.ArrayType.Vertex] = vertices;
@ -72,7 +72,7 @@
The [param arrays] argument is an array of arrays. Each of the [constant Mesh.ARRAY_MAX] elements contains an array with some of the mesh data for this surface as described by the corresponding member of [enum Mesh.ArrayType] or [code]null[/code] if it is not used by the surface. For example, [code]arrays[0][/code] is the array of vertices. That first vertex sub-array is always required; the others are optional. Adding an index array puts this surface into "index mode" where the vertex and other arrays become the sources of data and the index array defines the vertex order. All sub-arrays must have the same length as the vertex array (or be an exact multiple of the vertex array's length, when multiple elements of a sub-array correspond to a single vertex) or be empty, except for [constant Mesh.ARRAY_INDEX] if it is used.
The [param blend_shapes] argument is an array of vertex data for each blend shape. Each element is an array of the same structure as [param arrays], but [constant Mesh.ARRAY_VERTEX], [constant Mesh.ARRAY_NORMAL], and [constant Mesh.ARRAY_TANGENT] are set if and only if they are set in [param arrays] and all other entries are [code]null[/code].
The [param lods] argument is a dictionary with [float] keys and [PackedInt32Array] values. Each entry in the dictionary represents an LOD level of the surface, where the value is the [constant Mesh.ARRAY_INDEX] array to use for the LOD level and the key is roughly proportional to the distance at which the LOD stats being used. I.e., increasing the key of an LOD also increases the distance that the objects has to be from the camera before the LOD is used.
The [param flags] argument is the bitwise or of, as required: One value of [enum Mesh.ArrayCustomFormat] left shifted by [code]ARRAY_FORMAT_CUSTOMn_SHIFT[/code] for each custom channel in use, [constant Mesh.ARRAY_FLAG_USE_DYNAMIC_UPDATE], [constant Mesh.ARRAY_FLAG_USE_8_BONE_WEIGHTS], or [constant Mesh.ARRAY_FLAG_USES_EMPTY_VERTEX_ARRAY].
The [param flags] argument is the bitwise OR of, as required: One value of [enum Mesh.ArrayCustomFormat] left shifted by [code]ARRAY_FORMAT_CUSTOMn_SHIFT[/code] for each custom channel in use, [constant Mesh.ARRAY_FLAG_USE_DYNAMIC_UPDATE], [constant Mesh.ARRAY_FLAG_USE_8_BONE_WEIGHTS], or [constant Mesh.ARRAY_FLAG_USES_EMPTY_VERTEX_ARRAY].
[b]Note:[/b] When using indices, it is recommended to only use points, lines, or triangles.
</description>
</method>
@ -165,6 +165,13 @@
Returns the primitive type of the requested surface (see [method add_surface_from_arrays]).
</description>
</method>
<method name="surface_remove">
<return type="void" />
<param index="0" name="surf_idx" type="int" />
<description>
Removes the surface at the given index from the Mesh, shifting surfaces with higher index down by one.
</description>
</method>
<method name="surface_set_name">
<return type="void" />
<param index="0" name="surf_idx" type="int" />

2
engine/doc/classes/AtlasTexture.xml
View file

@ -6,7 +6,7 @@
<description>
[Texture2D] resource that draws only part of its [member atlas] texture, as defined by the [member region]. An additional [member margin] can also be set, which is useful for small adjustments.
Multiple [AtlasTexture] resources can be cropped from the same [member atlas]. Packing many smaller textures into a singular large texture helps to optimize video memory costs and render calls.
[b]Note:[/b] [AtlasTexture] cannot be used in an [AnimatedTexture], and may not tile properly in nodes such as [TextureRect], when inside other [AtlasTexture] resources.
[b]Note:[/b] [AtlasTexture] cannot be used in an [AnimatedTexture], and will not tile properly in nodes such as [TextureRect] or [Sprite2D]. To tile an [AtlasTexture], modify its [member region] instead.
</description>
<tutorials>
</tutorials>

4
engine/doc/classes/AudioEffectAmplify.xml
View file

@ -13,5 +13,9 @@
<member name="volume_db" type="float" setter="set_volume_db" getter="get_volume_db" default="0.0">
Amount of amplification in decibels. Positive values make the sound louder, negative values make it quieter. Value can range from -80 to 24.
</member>
<member name="volume_linear" type="float" setter="set_volume_linear" getter="get_volume_linear">
Amount of amplification as a linear value.
[b]Note:[/b] This member modifies [member volume_db] for convenience. The returned value is equivalent to the result of [method @GlobalScope.db_to_linear] on [member volume_db]. Setting this member is equivalent to setting [member volume_db] to the result of [method @GlobalScope.linear_to_db] on a value.
</member>
</members>
</class>

5
engine/doc/classes/AudioEffectFilter.xml
View file

@ -14,6 +14,7 @@
Threshold frequency for the filter, in Hz.
</member>
<member name="db" type="int" setter="set_db" getter="get_db" enum="AudioEffectFilter.FilterDB" default="0">
Steepness of the cutoff curve in dB per octave, also known as the order of the filter. Higher orders have a more aggressive cutoff.
</member>
<member name="gain" type="float" setter="set_gain" getter="get_gain" default="1.0">
Gain amount of the frequencies after the filter.
@ -24,12 +25,16 @@
</members>
<constants>
<constant name="FILTER_6DB" value="0" enum="FilterDB">
Cutting off at 6dB per octave.
</constant>
<constant name="FILTER_12DB" value="1" enum="FilterDB">
Cutting off at 12dB per octave.
</constant>
<constant name="FILTER_18DB" value="2" enum="FilterDB">
Cutting off at 18dB per octave.
</constant>
<constant name="FILTER_24DB" value="3" enum="FilterDB">
Cutting off at 24dB per octave.
</constant>
</constants>
</class>

2
engine/doc/classes/AudioEffectSpectrumAnalyzer.xml
View file

@ -5,7 +5,7 @@
</brief_description>
<description>
This audio effect does not affect sound output, but can be used for real-time audio visualizations.
This resource configures an [AudioEffectSpectrumAnalyzerInstance], which performs the actual analysis at runtime. An instance can be acquired with [method AudioServer.get_bus_effect_instance].
This resource configures an [AudioEffectSpectrumAnalyzerInstance], which performs the actual analysis at runtime. An instance can be obtained with [method AudioServer.get_bus_effect_instance].
See also [AudioStreamGenerator] for procedurally generating sounds.
</description>
<tutorials>

2
engine/doc/classes/AudioEffectSpectrumAnalyzerInstance.xml
View file

@ -5,7 +5,7 @@
</brief_description>
<description>
The runtime part of an [AudioEffectSpectrumAnalyzer], which can be used to query the magnitude of a frequency range on its host bus.
An instance of this class can be acquired with [method AudioServer.get_bus_effect_instance].
An instance of this class can be obtained with [method AudioServer.get_bus_effect_instance].
</description>
<tutorials>
<link title="Audio Spectrum Visualizer Demo">https://godotengine.org/asset-library/asset/2762</link>

4
engine/doc/classes/AudioEffectStereoEnhance.xml
View file

@ -11,11 +11,13 @@
</tutorials>
<members>
<member name="pan_pullout" type="float" setter="set_pan_pullout" getter="get_pan_pullout" default="1.0">
Values greater than 1.0 increase intensity of any panning on audio passing through this effect, whereas values less than 1.0 will decrease the panning intensity. A value of 0.0 will downmix audio to mono.
Amplifies the difference between stereo channels, increasing or decreasing existing panning. A value of 0.0 will downmix stereo to mono. Does not affect a mono signal.
</member>
<member name="surround" type="float" setter="set_surround" getter="get_surround" default="0.0">
Widens sound stage through phase shifting in conjunction with [member time_pullout_ms]. Just pans sound to the left channel if [member time_pullout_ms] is 0.
</member>
<member name="time_pullout_ms" type="float" setter="set_time_pullout" getter="get_time_pullout" default="0.0">
Widens sound stage through phase shifting in conjunction with [member surround]. Just delays the right channel if [member surround] is 0.
</member>
</members>
</class>

31
engine/doc/classes/AudioServer.xml
View file

@ -110,6 +110,20 @@
Returns the volume of the bus at index [param bus_idx] in dB.
</description>
</method>
<method name="get_bus_volume_linear" qualifiers="const">
<return type="float" />
<param index="0" name="bus_idx" type="int" />
<description>
Returns the volume of the bus at index [param bus_idx] as a linear value.
[b]Note:[/b] The returned value is equivalent to the result of [method @GlobalScope.db_to_linear] on the result of [method get_bus_volume_db].
</description>
</method>
<method name="get_driver_name" qualifiers="const">
<return type="String" />
<description>
Returns the name of the current audio driver. The default usually depends on the operating system, but may be overridden via the [code]--audio-driver[/code] [url=$DOCS_URL/tutorials/editor/command_line_tutorial.html]command line argument[/url]. [code]--headless[/code] also automatically sets the audio driver to [code]Dummy[/code]. See also [member ProjectSettings.audio/driver/driver].
</description>
</method>
<method name="get_input_device_list">
<return type="PackedStringArray" />
<description>
@ -117,6 +131,12 @@
[b]Note:[/b] [member ProjectSettings.audio/driver/enable_input] must be [code]true[/code] for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings.
</description>
</method>
<method name="get_input_mix_rate" qualifiers="const">
<return type="float" />
<description>
Returns the sample rate at the input of the [AudioServer].
</description>
</method>
<method name="get_mix_rate" qualifiers="const">
<return type="float" />
<description>
@ -290,7 +310,16 @@
<param index="0" name="bus_idx" type="int" />
<param index="1" name="volume_db" type="float" />
<description>
Sets the volume of the bus at index [param bus_idx] to [param volume_db].
Sets the volume in decibels of the bus at index [param bus_idx] to [param volume_db].
</description>
</method>
<method name="set_bus_volume_linear">
<return type="void" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="volume_linear" type="float" />
<description>
Sets the volume as a linear value of the bus at index [param bus_idx] to [param volume_linear].
[b]Note:[/b] Using this method is equivalent to calling [method set_bus_volume_db] with the result of [method @GlobalScope.linear_to_db] on a value.
</description>
</method>
<method name="set_enable_tagging_used_audio_streams">

14
engine/doc/classes/AudioStream.xml
View file

@ -13,6 +13,12 @@
<link title="Audio Spectrum Visualizer Demo">https://godotengine.org/asset-library/asset/2762</link>
</tutorials>
<methods>
<method name="_get_bar_beats" qualifiers="virtual const">
<return type="int" />
<description>
Override this method to return the bar beats of this stream.
</description>
</method>
<method name="_get_beat_count" qualifiers="virtual const">
<return type="int" />
<description>
@ -45,10 +51,16 @@
Override this method to customize the name assigned to this audio stream. Unused by the engine.
</description>
</method>
<method name="_has_loop" qualifiers="virtual const">
<return type="bool" />
<description>
Override this method to return [code]true[/code] if this stream has a loop.
</description>
</method>
<method name="_instantiate_playback" qualifiers="virtual const">
<return type="AudioStreamPlayback" />
<description>
Override this method to customize the returned value of [method instantiate_playback]. Should returned a new [AudioStreamPlayback] created when the stream is played (such as by an [AudioStreamPlayer])..
Override this method to customize the returned value of [method instantiate_playback]. Should return a new [AudioStreamPlayback] created when the stream is played (such as by an [AudioStreamPlayer]).
</description>
</method>
<method name="_is_monophonic" qualifiers="virtual const">

23
engine/doc/classes/AudioStreamGenerator.xml
View file

@ -11,6 +11,7 @@
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.
var phase = 0.0
func _ready():
$AudioStreamPlayer.play()
@ -18,7 +19,6 @@
fill_buffer()
func fill_buffer():
var phase = 0.0
var increment = pulse_hz / sample_hz
var frames_available = playback.get_frames_available()
@ -32,6 +32,7 @@
private AudioStreamGeneratorPlayback _playback; // Will hold the AudioStreamGeneratorPlayback.
private float _sampleHz;
private float _pulseHz = 440.0f; // The frequency of the sound wave.
private double phase = 0.0;
public override void _Ready()
{
@ -46,7 +47,6 @@
public void FillBuffer()
{
double phase = 0.0;
float increment = _pulseHz / _sampleHz;
int framesAvailable = _playback.GetFramesAvailable();
@ -73,6 +73,25 @@
The sample rate to use (in Hz). Higher values are more demanding for the CPU to generate, but result in better quality.
In games, common sample rates in use are [code]11025[/code], [code]16000[/code], [code]22050[/code], [code]32000[/code], [code]44100[/code], and [code]48000[/code].
According to the [url=https://en.wikipedia.org/wiki/Nyquist%E2%80%93Shannon_sampling_theorem]Nyquist-Shannon sampling theorem[/url], there is no quality difference to human hearing when going past 40,000 Hz (since most humans can only hear up to ~20,000 Hz, often less). If you are generating lower-pitched sounds such as voices, lower sample rates such as [code]32000[/code] or [code]22050[/code] may be usable with no loss in quality.
[b]Note:[/b] [AudioStreamGenerator] is not automatically resampling input data, to produce expected result [member mix_rate_mode] should match the sampling rate of input data.
[b]Note:[/b] If you are using [AudioEffectCapture] as the source of your data, set [member mix_rate_mode] to [constant MIX_RATE_INPUT] or [constant MIX_RATE_OUTPUT] to automatically match current [AudioServer] mixing rate.
</member>
<member name="mix_rate_mode" type="int" setter="set_mix_rate_mode" getter="get_mix_rate_mode" enum="AudioStreamGenerator.AudioStreamGeneratorMixRate" default="2">
Mixing rate mode. If set to [constant MIX_RATE_CUSTOM], [member mix_rate] is used, otherwise current [AudioServer] mixing rate is used.
</member>
</members>
<constants>
<constant name="MIX_RATE_OUTPUT" value="0" enum="AudioStreamGeneratorMixRate">
Current [AudioServer] output mixing rate.
</constant>
<constant name="MIX_RATE_INPUT" value="1" enum="AudioStreamGeneratorMixRate">
Current [AudioServer] input mixing rate.
</constant>
<constant name="MIX_RATE_CUSTOM" value="2" enum="AudioStreamGeneratorMixRate">
Custom mixing rate, specified by [member mix_rate].
</constant>
<constant name="MIX_RATE_MAX" value="3" enum="AudioStreamGeneratorMixRate">
Maximum value for the mixing rate mode enum.
</constant>
</constants>
</class>

48
engine/doc/classes/AudioStreamPlayback.xml
View file

@ -79,12 +79,47 @@
Overridable method. Called whenever the audio stream is mixed if the playback is active and [method AudioServer.set_enable_tagging_used_audio_streams] has been set to [code]true[/code]. Editor plugins may use this method to "tag" the current position along the audio stream and display it in a preview.
</description>
</method>
<method name="get_loop_count" qualifiers="const">
<return type="int" />
<description>
Returns the number of times the stream has looped.
</description>
</method>
<method name="get_playback_position" qualifiers="const">
<return type="float" />
<description>
Returns the current position in the stream, in seconds.
</description>
</method>
<method name="get_sample_playback" qualifiers="const" experimental="">
<return type="AudioSamplePlayback" />
<description>
Returns the [AudioSamplePlayback] associated with this [AudioStreamPlayback] for playing back the audio sample of this stream.
</description>
</method>
<method name="is_playing" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if the stream is playing.
</description>
</method>
<method name="mix_audio">
<return type="PackedVector2Array" />
<param index="0" name="rate_scale" type="float" />
<param index="1" name="frames" type="int" />
<description>
Mixes up to [param frames] of audio from the stream from the current position, at a rate of [param rate_scale], advancing the stream.
Returns a [PackedVector2Array] where each element holds the left and right channel volume levels of each frame.
[b]Note:[/b] Can return fewer frames than requested, make sure to use the size of the return value.
</description>
</method>
<method name="seek">
<return type="void" />
<param index="0" name="time" type="float" default="0.0" />
<description>
Seeks the stream at the given [param time], in seconds.
</description>
</method>
<method name="set_sample_playback" experimental="">
<return type="void" />
<param index="0" name="playback_sample" type="AudioSamplePlayback" />
@ -92,5 +127,18 @@
Associates [AudioSamplePlayback] to this [AudioStreamPlayback] for playing back the audio sample of this stream.
</description>
</method>
<method name="start">
<return type="void" />
<param index="0" name="from_pos" type="float" default="0.0" />
<description>
Starts the stream from the given [param from_pos], in seconds.
</description>
</method>
<method name="stop">
<return type="void" />
<description>
Stops the stream.
</description>
</method>
</methods>
</class>

2
engine/doc/classes/AudioStreamPlaybackPolyphonic.xml
View file

@ -13,7 +13,7 @@
<return type="bool" />
<param index="0" name="stream" type="int" />
<description>
Return true whether the stream associated with an integer ID is still playing. Check [method play_stream] for information on when this ID becomes invalid.
Returns [code]true[/code] if the stream associated with the given integer ID is still playing. Check [method play_stream] for information on when this ID becomes invalid.
</description>
</method>
<method name="play_stream">

11
engine/doc/classes/AudioStreamPlayer.xml
View file

@ -22,6 +22,7 @@
<description>
Returns the position in the [AudioStream] of the latest sound, in seconds. Returns [code]0.0[/code] if no sounds are playing.
[b]Note:[/b] The position is not always accurate, as the [AudioServer] does not mix audio every processed frame. To get more accurate results, add [method AudioServer.get_time_since_last_mix] to the returned position.
[b]Note:[/b] This method always returns [code]0.0[/code] if the [member stream] is an [AudioStreamInteractive], since it can have multiple clips playing at once.
</description>
</method>
<method name="get_stream_playback">
@ -77,7 +78,7 @@
<member name="playback_type" type="int" setter="set_playback_type" getter="get_playback_type" enum="AudioServer.PlaybackType" default="0" experimental="">
The playback type of the stream player. If set other than to the default value, it will force that playback type.
</member>
<member name="playing" type="bool" setter="_set_playing" getter="is_playing" default="false">
<member name="playing" type="bool" setter="set_playing" getter="is_playing" default="false">
If [code]true[/code], this node is playing sounds. Setting this property has the same effect as [method play] and [method stop].
</member>
<member name="stream" type="AudioStream" setter="set_stream" getter="get_stream">
@ -88,8 +89,12 @@
[b]Note:[/b] This property is automatically changed when exiting or entering the tree, or this node is paused (see [member Node.process_mode]).
</member>
<member name="volume_db" type="float" setter="set_volume_db" getter="get_volume_db" default="0.0">
Volume of sound, in decibel. This is an offset of the [member stream]'s volume.
[b]Note:[/b] To convert between decibel and linear energy (like most volume sliders do), use [method @GlobalScope.db_to_linear] and [method @GlobalScope.linear_to_db].
Volume of sound, in decibels. This is an offset of the [member stream]'s volume.
[b]Note:[/b] To convert between decibel and linear energy (like most volume sliders do), use [member volume_linear], or [method @GlobalScope.db_to_linear] and [method @GlobalScope.linear_to_db].
</member>
<member name="volume_linear" type="float" setter="set_volume_linear" getter="get_volume_linear">
Volume of sound, as a linear value.
[b]Note:[/b] This member modifies [member volume_db] for convenience. The returned value is equivalent to the result of [method @GlobalScope.db_to_linear] on [member volume_db]. Setting this member is equivalent to setting [member volume_db] to the result of [method @GlobalScope.linear_to_db] on a value.
</member>
</members>
<signals>

8
engine/doc/classes/AudioStreamPlayer2D.xml
View file

@ -81,7 +81,7 @@
<member name="playback_type" type="int" setter="set_playback_type" getter="get_playback_type" enum="AudioServer.PlaybackType" default="0" experimental="">
The playback type of the stream player. If set other than to the default value, it will force that playback type.
</member>
<member name="playing" type="bool" setter="_set_playing" getter="is_playing" default="false">
<member name="playing" type="bool" setter="set_playing" getter="is_playing" default="false">
If [code]true[/code], audio is playing or is queued to be played (see [method play]).
</member>
<member name="stream" type="AudioStream" setter="set_stream" getter="get_stream">
@ -91,7 +91,11 @@
If [code]true[/code], the playback is paused. You can resume it by setting [member stream_paused] to [code]false[/code].
</member>
<member name="volume_db" type="float" setter="set_volume_db" getter="get_volume_db" default="0.0">
Base volume before attenuation.
Base volume before attenuation, in decibels.
</member>
<member name="volume_linear" type="float" setter="set_volume_linear" getter="get_volume_linear">
Base volume before attenuation, as a linear value.
[b]Note:[/b] This member modifies [member volume_db] for convenience. The returned value is equivalent to the result of [method @GlobalScope.db_to_linear] on [member volume_db]. Setting this member is equivalent to setting [member volume_db] to the result of [method @GlobalScope.linear_to_db] on a value.
</member>
</members>
<signals>

6
engine/doc/classes/AudioStreamPlayer3D.xml
View file

@ -102,7 +102,7 @@
<member name="playback_type" type="int" setter="set_playback_type" getter="get_playback_type" enum="AudioServer.PlaybackType" default="0" experimental="">
The playback type of the stream player. If set other than to the default value, it will force that playback type.
</member>
<member name="playing" type="bool" setter="_set_playing" getter="is_playing" default="false">
<member name="playing" type="bool" setter="set_playing" getter="is_playing" default="false">
If [code]true[/code], audio is playing or is queued to be played (see [method play]).
</member>
<member name="stream" type="AudioStream" setter="set_stream" getter="get_stream">
@ -117,6 +117,10 @@
<member name="volume_db" type="float" setter="set_volume_db" getter="get_volume_db" default="0.0">
The base sound level before attenuation, in decibels.
</member>
<member name="volume_linear" type="float" setter="set_volume_linear" getter="get_volume_linear">
The base sound level before attenuation, as a linear value.
[b]Note:[/b] This member modifies [member volume_db] for convenience. The returned value is equivalent to the result of [method @GlobalScope.db_to_linear] on [member volume_db]. Setting this member is equivalent to setting [member volume_db] to the result of [method @GlobalScope.linear_to_db] on a value.
</member>
</members>
<signals>
<signal name="finished">

52
engine/doc/classes/AudioStreamWAV.xml
View file

@ -11,11 +11,44 @@
<link title="Runtime file loading and saving">$DOCS_URL/tutorials/io/runtime_file_loading_and_saving.html</link>
</tutorials>
<methods>
<method name="load_from_buffer" qualifiers="static">
<return type="AudioStreamWAV" />
<param index="0" name="stream_data" type="PackedByteArray" />
<param index="1" name="options" type="Dictionary" default="{}" />
<description>
Creates a new [AudioStreamWAV] instance from the given buffer. The buffer must contain WAV data.
The keys and values of [param options] match the properties of [ResourceImporterWAV]. The usage of [param options] is identical to [method AudioStreamWAV.load_from_file].
</description>
</method>
<method name="load_from_file" qualifiers="static">
<return type="AudioStreamWAV" />
<param index="0" name="path" type="String" />
<param index="1" name="options" type="Dictionary" default="{}" />
<description>
Creates a new [AudioStreamWAV] instance from the given file path. The file must be in WAV format.
The keys and values of [param options] match the properties of [ResourceImporterWAV].
[b]Example:[/b] Load the first file dropped as a WAV and play it:
[codeblock]
@onready var audio_player = $AudioStreamPlayer
func _ready():
get_window().files_dropped.connect(_on_files_dropped)
func _on_files_dropped(files):
if files[0].get_extension() == "wav":
audio_player.stream = AudioStreamWAV.load_from_file(files[0], {
"force/max_rate": true,
"force/max_rate_hz": 11025
})
audio_player.play()
[/codeblock]
</description>
</method>
<method name="save_to_wav">
<return type="int" enum="Error" />
<param index="0" name="path" type="String" />
<description>
Saves the AudioStreamWAV as a WAV file to [param path]. Samples with IMA ADPCM or QOA formats can't be saved.
Saves the AudioStreamWAV as a WAV file to [param path]. Samples with IMA ADPCM or Quite OK Audio formats can't be saved.
[b]Note:[/b] A [code].wav[/code] extension is automatically appended to [param path] if it is missing.
</description>
</method>
@ -23,19 +56,20 @@
<members>
<member name="data" type="PackedByteArray" setter="set_data" getter="get_data" default="PackedByteArray()">
Contains the audio data in bytes.
[b]Note:[/b] This property expects signed PCM8 data. To convert unsigned PCM8 to signed PCM8, subtract 128 from each byte.
[b]Note:[/b] If [member format] is set to [constant FORMAT_8_BITS], this property expects signed 8-bit PCM data. To convert from unsigned 8-bit PCM, subtract 128 from each byte.
[b]Note:[/b] If [member format] is set to [constant FORMAT_QOA], this property expects data from a full QOA file.
</member>
<member name="format" type="int" setter="set_format" getter="get_format" enum="AudioStreamWAV.Format" default="0">
Audio format. See [enum Format] constants for values.
</member>
<member name="loop_begin" type="int" setter="set_loop_begin" getter="get_loop_begin" default="0">
The loop start point (in number of samples, relative to the beginning of the stream). This information will be imported automatically from the WAV file if present.
The loop start point (in number of samples, relative to the beginning of the stream).
</member>
<member name="loop_end" type="int" setter="set_loop_end" getter="get_loop_end" default="0">
The loop end point (in number of samples, relative to the beginning of the stream). This information will be imported automatically from the WAV file if present.
The loop end point (in number of samples, relative to the beginning of the stream).
</member>
<member name="loop_mode" type="int" setter="set_loop_mode" getter="get_loop_mode" enum="AudioStreamWAV.LoopMode" default="0">
The loop mode. This information will be imported automatically from the WAV file if present. See [enum LoopMode] constants for values.
The loop mode. See [enum LoopMode] constants for values.
</member>
<member name="mix_rate" type="int" setter="set_mix_rate" getter="get_mix_rate" default="44100">
The sample rate for mixing this audio. Higher values require more storage space, but result in better quality.
@ -48,16 +82,16 @@
</members>
<constants>
<constant name="FORMAT_8_BITS" value="0" enum="Format">
8-bit audio codec.
8-bit PCM audio codec.
</constant>
<constant name="FORMAT_16_BITS" value="1" enum="Format">
16-bit audio codec.
16-bit PCM audio codec.
</constant>
<constant name="FORMAT_IMA_ADPCM" value="2" enum="Format">
Audio is compressed using IMA ADPCM.
Audio is lossily compressed as IMA ADPCM.
</constant>
<constant name="FORMAT_QOA" value="3" enum="Format">
Audio is compressed as QOA ([url=https://qoaformat.org/]Quite OK Audio[/url]).
Audio is lossily compressed as [url=https://qoaformat.org/]Quite OK Audio[/url].
</constant>
<constant name="LOOP_DISABLED" value="0" enum="LoopMode">
Audio does not loop.

1
engine/doc/classes/BackBufferCopy.xml
View file

@ -8,6 +8,7 @@
[b]Note:[/b] Since this node inherits from [Node2D] (and not [Control]), anchors and margins won't apply to child [Control]-derived nodes. This can be problematic when resizing the window. To avoid this, add [Control]-derived nodes as [i]siblings[/i] to the [BackBufferCopy] node instead of adding them as children.
</description>
<tutorials>
<link title="Screen-reading shaders">$DOCS_URL/tutorials/shaders/screen-reading_shaders.html</link>
</tutorials>
<members>
<member name="copy_mode" type="int" setter="set_copy_mode" getter="get_copy_mode" enum="BackBufferCopy.CopyMode" default="1">

3
engine/doc/classes/BaseButton.xml
View file

@ -57,7 +57,7 @@
</member>
<member name="button_pressed" type="bool" setter="set_pressed" getter="is_pressed" default="false">
If [code]true[/code], the button's state is pressed. Means the button is pressed down or toggled (if [member toggle_mode] is active). Only works if [member toggle_mode] is [code]true[/code].
[b]Note:[/b] Setting [member button_pressed] will result in [signal toggled] to be emitted. If you want to change the pressed state without emitting that signal, use [method set_pressed_no_signal].
[b]Note:[/b] Changing the value of [member button_pressed] will result in [signal toggled] to be emitted. If you want to change the pressed state without emitting that signal, use [method set_pressed_no_signal].
</member>
<member name="disabled" type="bool" setter="set_disabled" getter="is_disabled" default="false" keywords="enabled">
If [code]true[/code], the button is in disabled state and can't be clicked or toggled.
@ -75,6 +75,7 @@
</member>
<member name="shortcut_in_tooltip" type="bool" setter="set_shortcut_in_tooltip" getter="is_shortcut_in_tooltip_enabled" default="true">
If [code]true[/code], the button will add information about its shortcut in the tooltip.
[b]Note:[/b] This property does nothing when the tooltip control is customized using [method Control._make_custom_tooltip].
</member>
<member name="toggle_mode" type="bool" setter="set_toggle_mode" getter="is_toggle_mode" default="false">
If [code]true[/code], the button is in toggle mode. Makes the button flip state between pressed and unpressed each time its area is clicked.

9
engine/doc/classes/BaseMaterial3D.xml
View file

@ -88,7 +88,7 @@
The strength of the anisotropy effect. This is multiplied by [member anisotropy_flowmap]'s alpha channel if a texture is defined there and the texture contains an alpha channel.
</member>
<member name="anisotropy_enabled" type="bool" setter="set_feature" getter="get_feature" default="false">
If [code]true[/code], anisotropy is enabled. Anisotropy changes the shape of the specular blob and aligns it to tangent space. This is useful for brushed aluminium and hair reflections.
If [code]true[/code], anisotropy is enabled. Anisotropy changes the shape of the specular blob and aligns it to tangent space. This is useful for brushed aluminum and hair reflections.
[b]Note:[/b] Mesh tangents are needed for anisotropy to work. If the mesh does not contain tangents, the anisotropy effect will appear broken.
[b]Note:[/b] Material anisotropy should not to be confused with anisotropic texture filtering, which can be enabled by setting [member texture_filter] to [constant TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC].
</member>
@ -125,7 +125,6 @@
</member>
<member name="billboard_mode" type="int" setter="set_billboard_mode" getter="get_billboard_mode" enum="BaseMaterial3D.BillboardMode" default="0">
Controls how the object faces the camera. See [enum BillboardMode].
[b]Note:[/b] When billboarding is enabled and the material also casts shadows, billboards will face [b]the[/b] camera in the scene when rendering shadows. In scenes with multiple cameras, the intended shadow cannot be determined and this will result in undefined behavior. See [url=https://github.com/godotengine/godot/pull/72638]GitHub Pull Request #72638[/url] for details.
[b]Note:[/b] Billboard mode is not suitable for VR because the left-right vector of the camera is not horizontal when the screen is attached to your head instead of on the table. See [url=https://github.com/godotengine/godot/issues/41567]GitHub issue #41567[/url] for details.
</member>
<member name="blend_mode" type="int" setter="set_blend_mode" getter="get_blend_mode" enum="BaseMaterial3D.BlendMode" default="0">
@ -220,7 +219,7 @@
</member>
<member name="grow" type="bool" setter="set_grow_enabled" getter="is_grow_enabled" default="false">
If [code]true[/code], enables the vertex grow setting. This can be used to create mesh-based outlines using a second material pass and its [member cull_mode] set to [constant CULL_FRONT]. See also [member grow_amount].
[b]Note:[/b] Vertex growth cannot create new vertices, which means that visible gaps may occur in sharp corners. This can be alleviated by designing the mesh to use smooth normals exclusively using [url=https://wiki.polycount.com/wiki/Face_weighted_normals]face weighted normals[/url] in the 3D authoring software. In this case, grow will be able to join every outline together, just like in the original mesh.
[b]Note:[/b] Vertex growth cannot create new vertices, which means that visible gaps may occur in sharp corners. This can be alleviated by designing the mesh to use smooth normals exclusively using [url=http://wiki.polycount.com/wiki/Face_weighted_normals]face weighted normals[/url] in the 3D authoring software. In this case, grow will be able to join every outline together, just like in the original mesh.
</member>
<member name="grow_amount" type="float" setter="set_grow" getter="get_grow" default="0.0">
Grows object vertices in the direction of their normals. Only effective if [member grow] is [code]true[/code].
@ -316,6 +315,7 @@
</member>
<member name="refraction_enabled" type="bool" setter="set_feature" getter="get_feature" default="false">
If [code]true[/code], the refraction effect is enabled. Distorts transparency based on light from behind the object.
[b]Note:[/b] Refraction is implemented using the screen texture. Only opaque materials will appear in the refraction, since transparent materials do not appear in the screen texture.
</member>
<member name="refraction_scale" type="float" setter="set_refraction" getter="get_refraction" default="0.05">
The strength of the refraction effect.
@ -350,7 +350,6 @@
</member>
<member name="shading_mode" type="int" setter="set_shading_mode" getter="get_shading_mode" enum="BaseMaterial3D.ShadingMode" default="1">
Sets whether the shading takes place, per-pixel, per-vertex or unshaded. Per-vertex lighting is faster, making it the best choice for mobile applications, however it looks considerably worse than per-pixel. Unshaded rendering is the fastest, but disables all interactions with lights.
[b]Note:[/b] Setting the shading mode vertex shading currently has no effect, as vertex shading is not implemented yet.
</member>
<member name="shadow_to_opacity" type="bool" setter="set_flag" getter="get_flag" default="false">
If [code]true[/code], enables the "shadow to opacity" render mode where lighting modifies the alpha so shadowed areas are opaque and non-shadowed areas are transparent. Useful for overlaying shadows onto a camera feed in AR.
@ -553,7 +552,7 @@
The object will be shaded per pixel. Useful for realistic shading effects.
</constant>
<constant name="SHADING_MODE_PER_VERTEX" value="2" enum="ShadingMode">
The object will be shaded per vertex. Useful when you want cheaper shaders and do not care about visual quality. Not implemented yet (this mode will act like [constant SHADING_MODE_PER_PIXEL]).
The object will be shaded per vertex. Useful when you want cheaper shaders and do not care about visual quality.
</constant>
<constant name="SHADING_MODE_MAX" value="3" enum="ShadingMode">
Represents the size of the [enum ShadingMode] enum.

93
engine/doc/classes/Basis.xml
View file

@ -6,7 +6,12 @@
<description>
The [Basis] built-in [Variant] type is a 3×3 [url=https://en.wikipedia.org/wiki/Matrix_(mathematics)]matrix[/url] used to represent 3D rotation, scale, and shear. It is frequently used within a [Transform3D].
A [Basis] is composed by 3 axis vectors, each representing a column of the matrix: [member x], [member y], and [member z]. The length of each axis ([method Vector3.length]) influences the basis's scale, while the direction of all axes influence the rotation. Usually, these axes are perpendicular to one another. However, when you rotate any axis individually, the basis becomes sheared. Applying a sheared basis to a 3D model will make the model appear distorted.
A [Basis] is [b]orthogonal[/b] if its axes are perpendicular to each other. A basis is [b]normalized[/b] if the length of every axis is [code]1[/code]. A basis is [b]uniform[/b] if all axes share the same length (see [method get_scale]). A basis is [b]orthonormal[/b] if it is both orthogonal and normalized, which allows it to only represent rotations. A basis is [b]conformal[/b] if it is both orthogonal and uniform, which ensures it is not distorted.
A [Basis] is:
- [b]Orthogonal[/b] if its axes are perpendicular to each other.
- [b]Normalized[/b] if the length of every axis is [code]1.0[/code].
- [b]Uniform[/b] if all axes share the same length (see [method get_scale]).
- [b]Orthonormal[/b] if it is both orthogonal and normalized, which allows it to only represent rotations (see [method orthonormalized]).
- [b]Conformal[/b] if it is both orthogonal and uniform, which ensures it is not distorted.
For a general introduction, see the [url=$DOCS_URL/tutorials/math/matrices_and_transforms.html]Matrices and transforms[/url] tutorial.
[b]Note:[/b] Godot uses a [url=https://en.wikipedia.org/wiki/Right-hand_rule]right-handed coordinate system[/url], which is a common standard. For directions, the convention for built-in types like [Camera3D] is for -Z to point forward (+X is right, +Y is up, and +Z is back). Other objects may use different direction conventions. For more information, see the [url=$DOCS_URL/tutorials/assets_pipeline/importing_3d_scenes/model_export_considerations.html#d-asset-direction-conventions]3D asset direction conventions[/url] tutorial.
[b]Note:[/b] The basis matrices are exposed as [url=https://www.mindcontrol.org/~hplus/graphics/matrix-layout.html]column-major[/url] order, which is the same as OpenGL. However, they are stored internally in row-major order, which is the same as DirectX.
@ -24,7 +29,8 @@
<constructor name="Basis">
<return type="Basis" />
<description>
Constructs a [Basis] identical to the [constant IDENTITY].
Constructs a [Basis] identical to [constant IDENTITY].
[b]Note:[/b] In C#, this constructs a [Basis] with all of its components set to [constant Vector3.ZERO].
</description>
</constructor>
<constructor name="Basis">
@ -66,7 +72,7 @@
<return type="float" />
<description>
Returns the [url=https://en.wikipedia.org/wiki/Determinant]determinant[/url] of this basis's matrix. For advanced math, this number can be used to determine a few attributes:
- If the determinant is exactly [code]0[/code], the basis is not invertible (see [method inverse]).
- If the determinant is exactly [code]0.0[/code], the basis is not invertible (see [method inverse]).
- If the determinant is a negative number, the basis represents a negative scale.
[b]Note:[/b] If the basis's scale is the same for every axis, its determinant is always that scale by the power of 2.
</description>
@ -77,21 +83,21 @@
<param index="1" name="order" type="int" default="2" />
<description>
Constructs a new [Basis] that only represents rotation from the given [Vector3] of [url=https://en.wikipedia.org/wiki/Euler_angles]Euler angles[/url], in radians.
- The [member Vector3.x] should contain the angle around the [member x] axis (pitch).
- The [member Vector3.y] should contain the angle around the [member y] axis (yaw).
- The [member Vector3.x] should contain the angle around the [member x] axis (pitch);
- The [member Vector3.y] should contain the angle around the [member y] axis (yaw);
- The [member Vector3.z] should contain the angle around the [member z] axis (roll).
[codeblocks]
[gdscript]
# Creates a Basis whose z axis points down.
var my_basis = Basis.from_euler(Vector3(TAU / 4, 0, 0))
print(my_basis.z) # Prints (0, -1, 0).
print(my_basis.z) # Prints (0.0, -1.0, 0.0)
[/gdscript]
[csharp]
// Creates a Basis whose z axis points down.
var myBasis = Basis.FromEuler(new Vector3(Mathf.Tau / 4.0f, 0.0f, 0.0f));
GD.Print(myBasis.Z); // Prints (0, -1, 0).
GD.Print(myBasis.Z); // Prints (0, -1, 0)
[/csharp]
[/codeblocks]
The order of each consecutive rotation can be changed with [param order] (see [enum EulerOrder] constants). By default, the YXZ convention is used ([constant EULER_ORDER_YXZ]): the basis rotates first around the Y axis (yaw), then X (pitch), and lastly Z (roll). When using the opposite method [method get_euler], this order is reversed.
@ -106,16 +112,16 @@
[gdscript]
var my_basis = Basis.from_scale(Vector3(2, 4, 8))
print(my_basis.x) # Prints (2, 0, 0).
print(my_basis.y) # Prints (0, 4, 0).
print(my_basis.z) # Prints (0, 0, 8).
print(my_basis.x) # Prints (2.0, 0.0, 0.0)
print(my_basis.y) # Prints (0.0, 4.0, 0.0)
print(my_basis.z) # Prints (0.0, 0.0, 8.0)
[/gdscript]
[csharp]
var myBasis = Basis.FromScale(new Vector3(2.0f, 4.0f, 8.0f));
GD.Print(myBasis.X); // Prints (2, 0, 0).
GD.Print(myBasis.Y); // Prints (0, 4, 0).
GD.Print(myBasis.Z); // Prints (0, 0, 8).
GD.Print(myBasis.X); // Prints (2, 0, 0)
GD.Print(myBasis.Y); // Prints (0, 4, 0)
GD.Print(myBasis.Z); // Prints (0, 0, 8)
[/csharp]
[/codeblocks]
[b]Note:[/b] In linear algebra, the matrix of this basis is also known as a [url=https://en.wikipedia.org/wiki/Diagonal_matrix]diagonal matrix[/url].
@ -125,11 +131,12 @@
<return type="Vector3" />
<param index="0" name="order" type="int" default="2" />
<description>
Returns this basis's rotation as a [Vector3] of [url=https://en.wikipedia.org/wiki/Euler_angles]Euler angles[/url], in radians.
Returns this basis's rotation as a [Vector3] of [url=https://en.wikipedia.org/wiki/Euler_angles]Euler angles[/url], in radians. For the returned value:
- The [member Vector3.x] contains the angle around the [member x] axis (pitch);
- The [member Vector3.y] contains the angle around the [member y] axis (yaw);
- The [member Vector3.z] contains the angle around the [member z] axis (roll).
The order of each consecutive rotation can be changed with [param order] (see [enum EulerOrder] constants). By default, the YXZ convention is used ([constant EULER_ORDER_YXZ]): Z (roll) is calculated first, then X (pitch), and lastly Y (yaw). When using the opposite method [method from_euler], this order is reversed.
[b]Note:[/b] For this method to return correctly, the basis needs to be [i]orthonormal[/i] (see [method orthonormalized]).
[b]Note:[/b] Euler angles are much more intuitive but are not suitable for 3D math. Because of this, consider using the [method get_rotation_quaternion] method instead, which returns a [Quaternion].
[b]Note:[/b] In the Inspector dock, a basis's rotation is often displayed in Euler angles (in degrees), as is the case with the [member Node3D.rotation] property.
</description>
@ -138,13 +145,13 @@
<return type="Quaternion" />
<description>
Returns this basis's rotation as a [Quaternion].
[b]Note:[/b] Quatenions are much more suitable for 3D math but are less intuitive. For user interfaces, consider using the [method get_euler] method, which returns Euler angles.
[b]Note:[/b] Quaternions are much more suitable for 3D math but are less intuitive. For user interfaces, consider using the [method get_euler] method, which returns Euler angles.
</description>
</method>
<method name="get_scale" qualifiers="const">
<return type="Vector3" />
<description>
Returns the length of each axis of this basis, as a [Vector3]. If the basis is not sheared, this is the scaling factor. It is not affected by rotation.
Returns the length of each axis of this basis, as a [Vector3]. If the basis is not sheared, this value is the scaling factor. It is not affected by rotation.
[codeblocks]
[gdscript]
var my_basis = Basis(
@ -156,7 +163,7 @@
my_basis = my_basis.rotated(Vector3.UP, TAU / 2)
my_basis = my_basis.rotated(Vector3.RIGHT, TAU / 4)
print(my_basis.get_scale()) # Prints (2, 4, 8).
print(my_basis.get_scale()) # Prints (2.0, 4.0, 8.0)
[/gdscript]
[csharp]
var myBasis = new Basis(
@ -168,7 +175,7 @@
myBasis = myBasis.Rotated(Vector3.Up, Mathf.Tau / 2.0f);
myBasis = myBasis.Rotated(Vector3.Right, Mathf.Tau / 4.0f);
GD.Print(myBasis.Scale); // Prints (2, 4, 8).
GD.Print(myBasis.Scale); // Prints (2, 4, 8)
[/csharp]
[/codeblocks]
[b]Note:[/b] If the value returned by [method determinant] is negative, the scale is also negative.
@ -207,13 +214,14 @@
<description>
Creates a new [Basis] with a rotation such that the forward axis (-Z) points towards the [param target] position.
By default, the -Z axis (camera forward) is treated as forward (implies +X is right). If [param use_model_front] is [code]true[/code], the +Z axis (asset front) is treated as forward (implies +X is left) and points toward the [param target] position.
The up axis (+Y) points as close to the [param up] vector as possible while staying perpendicular to the forward axis. The returned basis is orthonormalized (see [method orthonormalized]). The [param target] and [param up] vectors cannot be [constant Vector3.ZERO], and cannot be parallel to each other.
The up axis (+Y) points as close to the [param up] vector as possible while staying perpendicular to the forward axis. The returned basis is orthonormalized (see [method orthonormalized]).
The [param target] and the [param up] cannot be [constant Vector3.ZERO], and shouldn't be colinear to avoid unintended rotation around local Z axis.
</description>
</method>
<method name="orthonormalized" qualifiers="const">
<return type="Basis" />
<description>
Returns the orthonormalized version of this basis. An orthonormal basis is both [i]orthogonal[/i] (the axes are perpendicular to each other) and [i]normalized[/i] (the axes have a length of [code]1[/code]), which also means it can only represent rotation.
Returns the orthonormalized version of this basis. An orthonormal basis is both [i]orthogonal[/i] (the axes are perpendicular to each other) and [i]normalized[/i] (the axes have a length of [code]1.0[/code]), which also means it can only represent a rotation.
It is often useful to call this method to avoid rounding errors on a rotating basis:
[codeblocks]
[gdscript]
@ -241,8 +249,8 @@
<param index="0" name="axis" type="Vector3" />
<param index="1" name="angle" type="float" />
<description>
Returns this basis rotated around the given [param axis] by [param angle] (in radians). The [param axis] must be a normalized vector (see [method Vector3.normalized]).
Positive values rotate this basis clockwise around the axis, while negative values rotate it counterclockwise.
Returns a copy of this basis rotated around the given [param axis] by the given [param angle] (in radians).
The [param axis] must be a normalized vector (see [method Vector3.normalized]). If [param angle] is positive, the basis is rotated counter-clockwise around the axis.
[codeblocks]
[gdscript]
var my_basis = Basis.IDENTITY
@ -278,9 +286,9 @@
)
my_basis = my_basis.scaled(Vector3(0, 2, -2))
print(my_basis.x) # Prints (0, 2, -2).
print(my_basis.y) # Prints (0, 4, -4).
print(my_basis.z) # Prints (0, 6, -6).
print(my_basis.x) # Prints (0.0, 2.0, -2.0)
print(my_basis.y) # Prints (0.0, 4.0, -4.0)
print(my_basis.z) # Prints (0.0, 6.0, -6.0)
[/gdscript]
[csharp]
var myBasis = new Basis(
@ -290,9 +298,9 @@
);
myBasis = myBasis.Scaled(new Vector3(0.0f, 2.0f, -2.0f));
GD.Print(myBasis.X); // Prints (0, 2, -2).
GD.Print(myBasis.Y); // Prints (0, 4, -4).
GD.Print(myBasis.Z); // Prints (0, 6, -6).
GD.Print(myBasis.X); // Prints (0, 2, -2)
GD.Print(myBasis.Y); // Prints (0, 4, -4)
GD.Print(myBasis.Z); // Prints (0, 6, -6)
[/csharp]
[/codeblocks]
</description>
@ -303,7 +311,7 @@
<param index="1" name="weight" type="float" />
<description>
Performs a spherical-linear interpolation with the [param to] basis, given a [param weight]. Both this basis and [param to] should represent a rotation.
[b]Example:[/b] Smoothly rotate a [Node3D] to the target basis over time, with a [Tween].
[b]Example:[/b] Smoothly rotate a [Node3D] to the target basis over time, with a [Tween]:
[codeblock]
var start_basis = Basis.IDENTITY
var target_basis = Basis.IDENTITY.rotated(Vector3.UP, TAU / 2)
@ -353,9 +361,9 @@
)
my_basis = my_basis.transposed()
print(my_basis.x) # Prints (1, 4, 7).
print(my_basis.y) # Prints (2, 5, 8).
print(my_basis.z) # Prints (3, 6, 9).
print(my_basis.x) # Prints (1.0, 4.0, 7.0)
print(my_basis.y) # Prints (2.0, 5.0, 8.0)
print(my_basis.z) # Prints (3.0, 6.0, 9.0)
[/gdscript]
[csharp]
var myBasis = new Basis(
@ -365,9 +373,9 @@
);
myBasis = myBasis.Transposed();
GD.Print(myBasis.X); // Prints (1, 4, 7).
GD.Print(myBasis.Y); // Prints (2, 5, 8).
GD.Print(myBasis.Z); // Prints (3, 6, 9).
GD.Print(myBasis.X); // Prints (1, 4, 7)
GD.Print(myBasis.Y); // Prints (2, 5, 8)
GD.Print(myBasis.Z); // Prints (3, 6, 9)
[/csharp]
[/codeblocks]
</description>
@ -389,23 +397,24 @@
</members>
<constants>
<constant name="IDENTITY" value="Basis(1, 0, 0, 0, 1, 0, 0, 0, 1)">
The identity basis. This is a basis with no rotation, no shear, and its scale being [code]1[/code]. This means that:
The identity [Basis]. This is an orthonormal basis with no rotation, no shear, and a scale of [constant Vector3.ONE]. This also means that:
- The [member x] points right ([constant Vector3.RIGHT]);
- The [member y] points up ([constant Vector3.UP]);
- The [member z] points back ([constant Vector3.BACK]).
[codeblock]
var basis := Basis.IDENTITY
var basis = Basis.IDENTITY
print("| X | Y | Z")
print("| %s | %s | %s" % [basis.x.x, basis.y.x, basis.z.x])
print("| %s | %s | %s" % [basis.x.y, basis.y.y, basis.z.y])
print("| %s | %s | %s" % [basis.x.z, basis.y.z, basis.z.z])
print("| %.f | %.f | %.f" % [basis.x.x, basis.y.x, basis.z.x])
print("| %.f | %.f | %.f" % [basis.x.y, basis.y.y, basis.z.y])
print("| %.f | %.f | %.f" % [basis.x.z, basis.y.z, basis.z.z])
# Prints:
# | X | Y | Z
# | 1 | 0 | 0
# | 0 | 1 | 0
# | 0 | 0 | 1
[/codeblock]
This is identical to creating [constructor Basis] without any parameters. This constant can be used to make your code clearer, and for consistency with C#.
If a [Vector3] or another [Basis] is transformed (multiplied) by this constant, no transformation occurs.
[b]Note:[/b] In GDScript, this constant is equivalent to creating a [constructor Basis] without any arguments. It can be used to make your code clearer, and for consistency with C#.
</constant>
<constant name="FLIP_X" value="Basis(-1, 0, 0, 0, 1, 0, 0, 0, 1)">
When any basis is multiplied by [constant FLIP_X], it negates all components of the [member x] axis (the X column).
@ -446,7 +455,7 @@
[gdscript]
# Basis that swaps the X/Z axes and doubles the scale.
var my_basis = Basis(Vector3(0, 2, 0), Vector3(2, 0, 0), Vector3(0, 0, 2))
print(my_basis * Vector3(1, 2, 3)) # Prints (4, 2, 6)
print(my_basis * Vector3(1, 2, 3)) # Prints (4.0, 2.0, 6.0)
[/gdscript]
[csharp]
// Basis that swaps the X/Z axes and doubles the scale.

6
engine/doc/classes/BoneAttachment3D.xml
View file

@ -15,6 +15,12 @@
Returns the [NodePath] to the external [Skeleton3D] node, if one has been set.
</description>
</method>
<method name="get_skeleton">
<return type="Skeleton3D" />
<description>
Get parent or external [Skeleton3D] node if found.
</description>
</method>
<method name="get_use_external_skeleton" qualifiers="const">
<return type="bool" />
<description>

11
engine/doc/classes/Button.xml
View file

@ -5,13 +5,13 @@
</brief_description>
<description>
[Button] is the standard themed button. It can contain text and an icon, and it will display them according to the current [Theme].
[b]Example of creating a button and assigning an action when pressed by code:[/b]
[b]Example:[/b] Create a button and connect a method that will be called when the button is pressed:
[codeblocks]
[gdscript]
func _ready():
var button = Button.new()
button.text = "Click me"
button.pressed.connect(self._button_pressed)
button.pressed.connect(_button_pressed)
add_child(button)
func _button_pressed():
@ -33,7 +33,7 @@
[/csharp]
[/codeblocks]
See also [BaseButton] which contains common properties and methods associated with this node.
[b]Note:[/b] Buttons do not interpret touch input and therefore don't support multitouch, since mouse emulation can only press one button at a given time. Use [TouchScreenButton] for buttons that trigger gameplay movement or actions.
[b]Note:[/b] Buttons do not detect touch input and therefore don't support multitouch, since mouse emulation can only press one button at a given time. Use [TouchScreenButton] for buttons that trigger gameplay movement or actions.
</description>
<tutorials>
<link title="2D Dodge The Creeps Demo">https://godotengine.org/asset-library/asset/2712</link>
@ -47,7 +47,7 @@
If set to something other than [constant TextServer.AUTOWRAP_OFF], the text gets wrapped inside the node's bounding rectangle.
</member>
<member name="clip_text" type="bool" setter="set_clip_text" getter="get_clip_text" default="false">
When this property is enabled, text that is too large to fit the button is clipped, when disabled the Button will always be wide enough to hold the text.
If [code]true[/code], text that is too large to fit the button is clipped horizontally. If [code]false[/code], the button will always be wide enough to hold the text. The text is not vertically clipped, and the button's height is not affected by this property.
</member>
<member name="expand_icon" type="bool" setter="set_expand_icon" getter="is_expand_icon" default="false">
When enabled, the button's icon will expand/shrink to fit the button's size while keeping its aspect. See also [theme_item icon_max_width].
@ -127,6 +127,9 @@
<theme_item name="icon_max_width" data_type="constant" type="int" default="0">
The maximum allowed width of the [Button]'s icon. This limit is applied on top of the default size of the icon, or its expanded size if [member expand_icon] is [code]true[/code]. The height is adjusted according to the icon's ratio. If the button has additional icons (e.g. [CheckBox]), they will also be limited.
</theme_item>
<theme_item name="line_spacing" data_type="constant" type="int" default="0">
Additional vertical spacing between lines (in pixels), spacing is added to line descent. This value can be negative.
</theme_item>
<theme_item name="outline_size" data_type="constant" type="int" default="0">
The size of the text outline.
[b]Note:[/b] If using a font with [member FontFile.multichannel_signed_distance_field] enabled, its [member FontFile.msdf_pixel_range] must be set to at least [i]twice[/i] the value of [theme_item outline_size] for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended.

51
engine/doc/classes/CPUParticles2D.xml
View file

@ -43,13 +43,23 @@
<return type="bool" />
<param index="0" name="particle_flag" type="int" enum="CPUParticles2D.ParticleFlags" />
<description>
Returns the enabled state of the given flag (see [enum ParticleFlags] for options).
Returns the enabled state of the given particle flag (see [enum ParticleFlags] for options).
</description>
</method>
<method name="request_particles_process">
<return type="void" />
<param index="0" name="process_time" type="float" />
<description>
Requests the particles to process for extra process time during a single frame.
Useful for particle playback, if used in combination with [member use_fixed_seed] or by calling [method restart] with parameter [code]keep_seed[/code] set to [code]true[/code].
</description>
</method>
<method name="restart">
<return type="void" />
<param index="0" name="keep_seed" type="bool" default="false" />
<description>
Restarts the particle emitter.
If [param keep_seed] is [code]true[/code], the current random seed will be preserved. Useful for seeking and playback.
</description>
</method>
<method name="set_param_curve">
@ -57,7 +67,7 @@
<param index="0" name="param" type="int" enum="CPUParticles2D.Parameter" />
<param index="1" name="curve" type="Curve" />
<description>
Sets the [Curve] of the parameter specified by [enum Parameter].
Sets the [Curve] of the parameter specified by [enum Parameter]. Should be a unit [Curve].
</description>
</method>
<method name="set_param_max">
@ -90,7 +100,7 @@
Number of particles emitted in one emission cycle.
</member>
<member name="angle_curve" type="Curve" setter="set_param_curve" getter="get_param_curve">
Each particle's rotation will be animated along this [Curve].
Each particle's rotation will be animated along this [Curve]. Should be a unit [Curve].
</member>
<member name="angle_max" type="float" setter="set_param_max" getter="get_param_max" default="0.0">
Maximum initial rotation applied to each particle, in degrees.
@ -99,7 +109,7 @@
Minimum equivalent of [member angle_max].
</member>
<member name="angular_velocity_curve" type="Curve" setter="set_param_curve" getter="get_param_curve">
Each particle's angular velocity will vary along this [Curve].
Each particle's angular velocity will vary along this [Curve]. Should be a unit [Curve].
</member>
<member name="angular_velocity_max" type="float" setter="set_param_max" getter="get_param_max" default="0.0">
Maximum initial angular velocity (rotation speed) applied to each particle in [i]degrees[/i] per second.
@ -108,7 +118,7 @@
Minimum equivalent of [member angular_velocity_max].
</member>
<member name="anim_offset_curve" type="Curve" setter="set_param_curve" getter="get_param_curve">
Each particle's animation offset will vary along this [Curve].
Each particle's animation offset will vary along this [Curve]. Should be a unit [Curve].
</member>
<member name="anim_offset_max" type="float" setter="set_param_max" getter="get_param_max" default="0.0">
Maximum animation offset that corresponds to frame index in the texture. [code]0[/code] is the first frame, [code]1[/code] is the last one. See [member CanvasItemMaterial.particles_animation].
@ -117,7 +127,7 @@
Minimum equivalent of [member anim_offset_max].
</member>
<member name="anim_speed_curve" type="Curve" setter="set_param_curve" getter="get_param_curve">
Each particle's animation speed will vary along this [Curve].
Each particle's animation speed will vary along this [Curve]. Should be a unit [Curve].
</member>
<member name="anim_speed_max" type="float" setter="set_param_max" getter="get_param_max" default="0.0">
Maximum particle animation speed. Animation speed of [code]1[/code] means that the particles will make full [code]0[/code] to [code]1[/code] offset cycle during lifetime, [code]2[/code] means [code]2[/code] cycles etc.
@ -130,13 +140,13 @@
Each particle's initial color. If [member texture] is defined, it will be multiplied by this color.
</member>
<member name="color_initial_ramp" type="Gradient" setter="set_color_initial_ramp" getter="get_color_initial_ramp">
Each particle's initial color will vary along this [GradientTexture1D] (multiplied with [member color]).
Each particle's initial color will vary along this [Gradient] (multiplied with [member color]).
</member>
<member name="color_ramp" type="Gradient" setter="set_color_ramp" getter="get_color_ramp">
Each particle's color will vary along this [Gradient] (multiplied with [member color]).
Each particle's color will vary along this [Gradient] over its lifetime (multiplied with [member color]).
</member>
<member name="damping_curve" type="Curve" setter="set_param_curve" getter="get_param_curve">
Damping will vary along this [Curve].
Damping will vary along this [Curve]. Should be a unit [Curve].
</member>
<member name="damping_max" type="float" setter="set_param_max" getter="get_param_max" default="0.0">
The maximum rate at which particles lose velocity. For example value of [code]100[/code] means that the particle will go from [code]100[/code] velocity to [code]0[/code] in [code]1[/code] second.
@ -184,7 +194,7 @@
Gravity applied to every particle.
</member>
<member name="hue_variation_curve" type="Curve" setter="set_param_curve" getter="get_param_curve">
Each particle's hue will vary along this [Curve].
Each particle's hue will vary along this [Curve]. Should be a unit [Curve].
</member>
<member name="hue_variation_max" type="float" setter="set_param_max" getter="get_param_max" default="0.0">
Maximum initial hue variation applied to each particle. It will shift the particle color's hue.
@ -205,7 +215,7 @@
Particle lifetime randomness ratio.
</member>
<member name="linear_accel_curve" type="Curve" setter="set_param_curve" getter="get_param_curve">
Each particle's linear acceleration will vary along this [Curve].
Each particle's linear acceleration will vary along this [Curve]. Should be a unit [Curve].
</member>
<member name="linear_accel_max" type="float" setter="set_param_max" getter="get_param_max" default="0.0">
Maximum linear acceleration applied to each particle in the direction of motion.
@ -220,7 +230,7 @@
If [code]true[/code], only one emission cycle occurs. If set [code]true[/code] during a cycle, emission will stop at the cycle's end.
</member>
<member name="orbit_velocity_curve" type="Curve" setter="set_param_curve" getter="get_param_curve">
Each particle's orbital velocity will vary along this [Curve].
Each particle's orbital velocity will vary along this [Curve]. Should be a unit [Curve].
</member>
<member name="orbit_velocity_max" type="float" setter="set_param_max" getter="get_param_max" default="0.0">
Maximum orbital velocity applied to each particle. Makes the particles circle around origin. Specified in number of full rotations around origin per second.
@ -231,11 +241,12 @@
<member name="particle_flag_align_y" type="bool" setter="set_particle_flag" getter="get_particle_flag" default="false">
Align Y axis of particle with the direction of its velocity.
</member>
<member name="physics_interpolation_mode" type="int" setter="set_physics_interpolation_mode" getter="get_physics_interpolation_mode" overrides="Node" enum="Node.PhysicsInterpolationMode" default="2" />
<member name="preprocess" type="float" setter="set_pre_process_time" getter="get_pre_process_time" default="0.0">
Particle system starts as if it had already run for this many seconds.
</member>
<member name="radial_accel_curve" type="Curve" setter="set_param_curve" getter="get_param_curve">
Each particle's radial acceleration will vary along this [Curve].
Each particle's radial acceleration will vary along this [Curve]. Should be a unit [Curve].
</member>
<member name="radial_accel_max" type="float" setter="set_param_max" getter="get_param_max" default="0.0">
Maximum radial acceleration applied to each particle. Makes particle accelerate away from the origin or towards it if negative.
@ -247,7 +258,7 @@
Emission lifetime randomness ratio.
</member>
<member name="scale_amount_curve" type="Curve" setter="set_param_curve" getter="get_param_curve">
Each particle's scale will vary along this [Curve].
Each particle's scale will vary along this [Curve]. Should be a unit [Curve].
</member>
<member name="scale_amount_max" type="float" setter="set_param_max" getter="get_param_max" default="1.0">
Maximum initial scale applied to each particle.
@ -256,13 +267,16 @@
Minimum equivalent of [member scale_amount_max].
</member>
<member name="scale_curve_x" type="Curve" setter="set_scale_curve_x" getter="get_scale_curve_x">
Each particle's horizontal scale will vary along this [Curve].
Each particle's horizontal scale will vary along this [Curve]. Should be a unit [Curve].
[member split_scale] must be enabled.
</member>
<member name="scale_curve_y" type="Curve" setter="set_scale_curve_y" getter="get_scale_curve_y">
Each particle's vertical scale will vary along this [Curve].
Each particle's vertical scale will vary along this [Curve]. Should be a unit [Curve].
[member split_scale] must be enabled.
</member>
<member name="seed" type="int" setter="set_seed" getter="get_seed" default="0">
Sets the random seed used by the particle system. Only effective if [member use_fixed_seed] is [code]true[/code].
</member>
<member name="speed_scale" type="float" setter="set_speed_scale" getter="get_speed_scale" default="1.0">
Particle system's running speed scaling ratio. A value of [code]0[/code] can be used to pause the particles.
</member>
@ -273,7 +287,7 @@
Each particle's initial direction range from [code]+spread[/code] to [code]-spread[/code] degrees.
</member>
<member name="tangential_accel_curve" type="Curve" setter="set_param_curve" getter="get_param_curve">
Each particle's tangential acceleration will vary along this [Curve].
Each particle's tangential acceleration will vary along this [Curve]. Should be a unit [Curve].
</member>
<member name="tangential_accel_max" type="float" setter="set_param_max" getter="get_param_max" default="0.0">
Maximum tangential acceleration applied to each particle. Tangential acceleration is perpendicular to the particle's velocity giving the particles a swirling motion.
@ -284,6 +298,9 @@
<member name="texture" type="Texture2D" setter="set_texture" getter="get_texture">
Particle texture. If [code]null[/code], particles will be squares.
</member>
<member name="use_fixed_seed" type="bool" setter="set_use_fixed_seed" getter="get_use_fixed_seed" default="false">
If [code]true[/code], particles will use the same seed for every simulation using the seed defined in [member seed]. This is useful for situations where the visual outcome should be consistent across replays, for example when using Movie Maker mode.
</member>
</members>
<signals>
<signal name="finished">

54
engine/doc/classes/CPUParticles3D.xml
View file

@ -11,6 +11,12 @@
<link title="Particle systems (3D)">$DOCS_URL/tutorials/3d/particles/index.html</link>
</tutorials>
<methods>
<method name="capture_aabb" qualifiers="const">
<return type="AABB" />
<description>
Returns the axis-aligned bounding box that contains all the particles that are active in the current frame.
</description>
</method>
<method name="convert_from_particles">
<return type="void" />
<param index="0" name="particles" type="Node" />
@ -46,10 +52,20 @@
Returns the enabled state of the given particle flag (see [enum ParticleFlags] for options).
</description>
</method>
<method name="request_particles_process">
<return type="void" />
<param index="0" name="process_time" type="float" />
<description>
Requests the particles to process for extra process time during a single frame.
Useful for particle playback, if used in combination with [member use_fixed_seed] or by calling [method restart] with parameter [code]keep_seed[/code] set to [code]true[/code].
</description>
</method>
<method name="restart">
<return type="void" />
<param index="0" name="keep_seed" type="bool" default="false" />
<description>
Restarts the particle emitter.
If [param keep_seed] is [code]true[/code], the current random seed will be preserved. Useful for seeking and playback.
</description>
</method>
<method name="set_param_curve">
@ -57,7 +73,7 @@
<param index="0" name="param" type="int" enum="CPUParticles3D.Parameter" />
<param index="1" name="curve" type="Curve" />
<description>
Sets the [Curve] of the parameter specified by [enum Parameter].
Sets the [Curve] of the parameter specified by [enum Parameter]. Should be a unit [Curve].
</description>
</method>
<method name="set_param_max">
@ -90,7 +106,7 @@
Number of particles emitted in one emission cycle.
</member>
<member name="angle_curve" type="Curve" setter="set_param_curve" getter="get_param_curve">
Each particle's rotation will be animated along this [Curve].
Each particle's rotation will be animated along this [Curve]. Should be a unit [Curve].
</member>
<member name="angle_max" type="float" setter="set_param_max" getter="get_param_max" default="0.0">
Maximum angle.
@ -99,7 +115,7 @@
Minimum angle.
</member>
<member name="angular_velocity_curve" type="Curve" setter="set_param_curve" getter="get_param_curve">
Each particle's angular velocity (rotation speed) will vary along this [Curve] over its lifetime.
Each particle's angular velocity (rotation speed) will vary along this [Curve] over its lifetime. Should be a unit [Curve].
</member>
<member name="angular_velocity_max" type="float" setter="set_param_max" getter="get_param_max" default="0.0">
Maximum initial angular velocity (rotation speed) applied to each particle in [i]degrees[/i] per second.
@ -108,7 +124,7 @@
Minimum initial angular velocity (rotation speed) applied to each particle in [i]degrees[/i] per second.
</member>
<member name="anim_offset_curve" type="Curve" setter="set_param_curve" getter="get_param_curve">
Each particle's animation offset will vary along this [Curve].
Each particle's animation offset will vary along this [Curve]. Should be a unit [Curve].
</member>
<member name="anim_offset_max" type="float" setter="set_param_max" getter="get_param_max" default="0.0">
Maximum animation offset.
@ -117,7 +133,7 @@
Minimum animation offset.
</member>
<member name="anim_speed_curve" type="Curve" setter="set_param_curve" getter="get_param_curve">
Each particle's animation speed will vary along this [Curve].
Each particle's animation speed will vary along this [Curve]. Should be a unit [Curve].
</member>
<member name="anim_speed_max" type="float" setter="set_param_max" getter="get_param_max" default="0.0">
Maximum particle animation speed.
@ -130,15 +146,15 @@
[b]Note:[/b] [member color] multiplies the particle mesh's vertex colors. To have a visible effect on a [BaseMaterial3D], [member BaseMaterial3D.vertex_color_use_as_albedo] [i]must[/i] be [code]true[/code]. For a [ShaderMaterial], [code]ALBEDO *= COLOR.rgb;[/code] must be inserted in the shader's [code]fragment()[/code] function. Otherwise, [member color] will have no visible effect.
</member>
<member name="color_initial_ramp" type="Gradient" setter="set_color_initial_ramp" getter="get_color_initial_ramp">
Each particle's initial color will vary along this [GradientTexture1D] (multiplied with [member color]).
Each particle's initial color will vary along this [Gradient] (multiplied with [member color]).
[b]Note:[/b] [member color_initial_ramp] multiplies the particle mesh's vertex colors. To have a visible effect on a [BaseMaterial3D], [member BaseMaterial3D.vertex_color_use_as_albedo] [i]must[/i] be [code]true[/code]. For a [ShaderMaterial], [code]ALBEDO *= COLOR.rgb;[/code] must be inserted in the shader's [code]fragment()[/code] function. Otherwise, [member color_initial_ramp] will have no visible effect.
</member>
<member name="color_ramp" type="Gradient" setter="set_color_ramp" getter="get_color_ramp">
Each particle's color will vary along this [GradientTexture1D] over its lifetime (multiplied with [member color]).
Each particle's color will vary along this [Gradient] over its lifetime (multiplied with [member color]).
[b]Note:[/b] [member color_ramp] multiplies the particle mesh's vertex colors. To have a visible effect on a [BaseMaterial3D], [member BaseMaterial3D.vertex_color_use_as_albedo] [i]must[/i] be [code]true[/code]. For a [ShaderMaterial], [code]ALBEDO *= COLOR.rgb;[/code] must be inserted in the shader's [code]fragment()[/code] function. Otherwise, [member color_ramp] will have no visible effect.
</member>
<member name="damping_curve" type="Curve" setter="set_param_curve" getter="get_param_curve">
Damping will vary along this [Curve].
Damping will vary along this [Curve]. Should be a unit [Curve].
</member>
<member name="damping_max" type="float" setter="set_param_max" getter="get_param_max" default="0.0">
Maximum damping.
@ -168,6 +184,10 @@
<member name="emission_ring_axis" type="Vector3" setter="set_emission_ring_axis" getter="get_emission_ring_axis">
The axis of the ring when using the emitter [constant EMISSION_SHAPE_RING].
</member>
<member name="emission_ring_cone_angle" type="float" setter="set_emission_ring_cone_angle" getter="get_emission_ring_cone_angle">
The angle of the cone when using the emitter [constant EMISSION_SHAPE_RING]. The default angle of 90 degrees results in a ring, while an angle of 0 degrees results in a cone. Intermediate values will result in a ring where one end is larger than the other.
[b]Note:[/b] Depending on [member emission_ring_height], the angle may be clamped if the ring's end is reached to form a perfect cone.
</member>
<member name="emission_ring_height" type="float" setter="set_emission_ring_height" getter="get_emission_ring_height">
The height of the ring when using the emitter [constant EMISSION_SHAPE_RING].
</member>
@ -202,7 +222,7 @@
Gravity applied to every particle.
</member>
<member name="hue_variation_curve" type="Curve" setter="set_param_curve" getter="get_param_curve">
Each particle's hue will vary along this [Curve].
Each particle's hue will vary along this [Curve]. Should be a unit [Curve].
</member>
<member name="hue_variation_max" type="float" setter="set_param_max" getter="get_param_max" default="0.0">
Maximum hue variation.
@ -223,7 +243,7 @@
Particle lifetime randomness ratio.
</member>
<member name="linear_accel_curve" type="Curve" setter="set_param_curve" getter="get_param_curve">
Each particle's linear acceleration will vary along this [Curve].
Each particle's linear acceleration will vary along this [Curve]. Should be a unit [Curve].
</member>
<member name="linear_accel_max" type="float" setter="set_param_max" getter="get_param_max" default="0.0">
Maximum linear acceleration.
@ -241,7 +261,7 @@
If [code]true[/code], only one emission cycle occurs. If set [code]true[/code] during a cycle, emission will stop at the cycle's end.
</member>
<member name="orbit_velocity_curve" type="Curve" setter="set_param_curve" getter="get_param_curve">
Each particle's orbital velocity will vary along this [Curve].
Each particle's orbital velocity will vary along this [Curve]. Should be a unit [Curve].
</member>
<member name="orbit_velocity_max" type="float" setter="set_param_max" getter="get_param_max">
Maximum orbit velocity.
@ -262,7 +282,7 @@
Particle system starts as if it had already run for this many seconds.
</member>
<member name="radial_accel_curve" type="Curve" setter="set_param_curve" getter="get_param_curve">
Each particle's radial acceleration will vary along this [Curve].
Each particle's radial acceleration will vary along this [Curve]. Should be a unit [Curve].
</member>
<member name="radial_accel_max" type="float" setter="set_param_max" getter="get_param_max" default="0.0">
Maximum radial acceleration.
@ -274,7 +294,7 @@
Emission lifetime randomness ratio.
</member>
<member name="scale_amount_curve" type="Curve" setter="set_param_curve" getter="get_param_curve">
Each particle's scale will vary along this [Curve].
Each particle's scale will vary along this [Curve]. Should be a unit [Curve].
</member>
<member name="scale_amount_max" type="float" setter="set_param_max" getter="get_param_max" default="1.0">
Maximum scale.
@ -291,6 +311,9 @@
<member name="scale_curve_z" type="Curve" setter="set_scale_curve_z" getter="get_scale_curve_z">
Curve for the scale over life, along the z axis.
</member>
<member name="seed" type="int" setter="set_seed" getter="get_seed" default="0">
Sets the random seed used by the particle system. Only effective if [member use_fixed_seed] is [code]true[/code].
</member>
<member name="speed_scale" type="float" setter="set_speed_scale" getter="get_speed_scale" default="1.0">
Particle system's running speed scaling ratio. A value of [code]0[/code] can be used to pause the particles.
</member>
@ -301,7 +324,7 @@
Each particle's initial direction range from [code]+spread[/code] to [code]-spread[/code] degrees. Applied to X/Z plane and Y/Z planes.
</member>
<member name="tangential_accel_curve" type="Curve" setter="set_param_curve" getter="get_param_curve">
Each particle's tangential acceleration will vary along this [Curve].
Each particle's tangential acceleration will vary along this [Curve]. Should be a unit [Curve].
</member>
<member name="tangential_accel_max" type="float" setter="set_param_max" getter="get_param_max" default="0.0">
Maximum tangent acceleration.
@ -309,6 +332,9 @@
<member name="tangential_accel_min" type="float" setter="set_param_min" getter="get_param_min" default="0.0">
Minimum tangent acceleration.
</member>
<member name="use_fixed_seed" type="bool" setter="set_use_fixed_seed" getter="get_use_fixed_seed" default="false">
If [code]true[/code], particles will use the same seed for every simulation using the seed defined in [member seed]. This is useful for situations where the visual outcome should be consistent across replays, for example when using Movie Maker mode.
</member>
<member name="visibility_aabb" type="AABB" setter="set_visibility_aabb" getter="get_visibility_aabb" default="AABB(0, 0, 0, 0, 0, 0)">
The [AABB] that determines the node's region which needs to be visible on screen for the particle system to be active.
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.

29
engine/doc/classes/Callable.xml
View file

@ -5,7 +5,6 @@
</brief_description>
<description>
[Callable] is a built-in [Variant] type that represents a function. It can either be a method within an [Object] instance, or a custom callable used for different purposes (see [method is_custom]). Like all [Variant] types, it can be stored in variables and passed to other functions. It is most commonly used for signal callbacks.
[b]Example:[/b]
[codeblocks]
[gdscript]
func print_args(arg1, arg2, arg3 = ""):
@ -14,7 +13,7 @@
func test():
var callable = Callable(self, "print_args")
callable.call("hello", "world") # Prints "hello world ".
callable.call(Vector2.UP, 42, callable) # Prints "(0, -1) 42 Node(node.gd)::print_args".
callable.call(Vector2.UP, 42, callable) # Prints "(0.0, -1.0) 42 Node(node.gd)::print_args"
callable.call("invalid") # Invalid call, should have at least 2 arguments.
[/gdscript]
[csharp]
@ -29,7 +28,7 @@
// Invalid calls fail silently.
Callable callable = new Callable(this, MethodName.PrintArgs);
callable.Call("hello", "world"); // Default parameter values are not supported, should have 3 arguments.
callable.Call(Vector2.Up, 42, callable); // Prints "(0, -1) 42 Node(Node.cs)::PrintArgs".
callable.Call(Vector2.Up, 42, callable); // Prints "(0, -1) 42 Node(Node.cs)::PrintArgs"
callable.Call("invalid"); // Invalid call, should have 3 arguments.
}
[/csharp]
@ -40,7 +39,7 @@
var my_lambda = func (message):
print(message)
# Prints Hello everyone!
# Prints "Hello everyone!"
my_lambda.call("Hello everyone!")
# Prints "Attack!", when the button_pressed signal is emitted.
@ -156,13 +155,21 @@
<method name="get_bound_arguments" qualifiers="const">
<return type="Array" />
<description>
Return the bound arguments (as long as [method get_bound_arguments_count] is greater than zero), or empty (if [method get_bound_arguments_count] is less than or equal to zero).
Returns the array of arguments bound via successive [method bind] or [method unbind] calls. These arguments will be added [i]after[/i] the arguments passed to the call, from which [method get_unbound_arguments_count] arguments on the right have been previously excluded.
[codeblock]
func get_effective_arguments(callable, call_args):
assert(call_args.size() - callable.get_unbound_arguments_count() &gt;= 0)
var result = call_args.slice(0, call_args.size() - callable.get_unbound_arguments_count())
result.append_array(callable.get_bound_arguments())
return result
[/codeblock]
</description>
</method>
<method name="get_bound_arguments_count" qualifiers="const">
<return type="int" />
<description>
Returns the total amount of arguments bound (or unbound) via successive [method bind] or [method unbind] calls. If the amount of arguments unbound is greater than the ones bound, this function returns a value less than zero.
Returns the total amount of arguments bound via successive [method bind] or [method unbind] calls. This is the same as the size of the array returned by [method get_bound_arguments]. See [method get_bound_arguments] for details.
[b]Note:[/b] The [method get_bound_arguments_count] and [method get_unbound_arguments_count] methods can both return positive values.
</description>
</method>
<method name="get_method" qualifiers="const">
@ -183,6 +190,13 @@
Returns the ID of this [Callable]'s object (see [method Object.get_instance_id]).
</description>
</method>
<method name="get_unbound_arguments_count" qualifiers="const">
<return type="int" />
<description>
Returns the total amount of arguments unbound via successive [method bind] or [method unbind] calls. See [method get_bound_arguments] for details.
[b]Note:[/b] The [method get_bound_arguments_count] and [method get_unbound_arguments_count] methods can both return positive values.
</description>
</method>
<method name="hash" qualifiers="const">
<return type="int" />
<description>
@ -203,7 +217,8 @@
<method name="is_null" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if this [Callable] has no target to call the method on.
Returns [code]true[/code] if this [Callable] has no target to call the method on. Equivalent to [code]callable == Callable()[/code].
[b]Note:[/b] This is [i]not[/i] the same as [code]not is_valid()[/code] and using [code]not is_null()[/code] will [i]not[/i] guarantee that this callable can be called. Use [method is_valid] instead.
</description>
</method>
<method name="is_standard" qualifiers="const">

4
engine/doc/classes/CallbackTweener.xml
View file

@ -16,10 +16,10 @@
<param index="0" name="delay" type="float" />
<description>
Makes the callback call delayed by given time in seconds.
[b]Example:[/b]
[b]Example:[/b] Call [method Node.queue_free] after 2 seconds:
[codeblock]
var tween = get_tree().create_tween()
tween.tween_callback(queue_free).set_delay(2) #this will call queue_free() after 2 seconds
tween.tween_callback(queue_free).set_delay(2)
[/codeblock]
</description>
</method>

4
engine/doc/classes/CameraAttributes.xml
View file

@ -25,7 +25,9 @@
Multiplier for the exposure amount. A higher value results in a brighter image.
</member>
<member name="exposure_sensitivity" type="float" setter="set_exposure_sensitivity" getter="get_exposure_sensitivity" default="100.0">
Sensitivity of camera sensors, measured in ISO. A higher sensitivity results in a brighter image. Only available when [member ProjectSettings.rendering/lights_and_shadows/use_physical_light_units] is enabled. When [member auto_exposure_enabled] this can be used as a method of exposure compensation, doubling the value will increase the exposure value (measured in EV100) by 1 stop.
Sensitivity of camera sensors, measured in ISO. A higher sensitivity results in a brighter image.
If [member auto_exposure_enabled] is [code]true[/code], this can be used as a method of exposure compensation, doubling the value will increase the exposure value (measured in EV100) by 1 stop.
[b]Note:[/b] Only available when [member ProjectSettings.rendering/lights_and_shadows/use_physical_light_units] is enabled.
</member>
</members>
</class>

2
engine/doc/classes/CameraAttributesPhysical.xml
View file

@ -25,7 +25,7 @@
The maximum luminance (in EV100) used when calculating auto exposure. When calculating scene average luminance, color values will be clamped to at least this value. This limits the auto-exposure from exposing below a certain brightness, resulting in a cut off point where the scene will remain bright.
</member>
<member name="auto_exposure_min_exposure_value" type="float" setter="set_auto_exposure_min_exposure_value" getter="get_auto_exposure_min_exposure_value" default="-8.0">
The minimum luminance luminance (in EV100) used when calculating auto exposure. When calculating scene average luminance, color values will be clamped to at least this value. This limits the auto-exposure from exposing above a certain brightness, resulting in a cut off point where the scene will remain dark.
The minimum luminance (in EV100) used when calculating auto exposure. When calculating scene average luminance, color values will be clamped to at least this value. This limits the auto-exposure from exposing above a certain brightness, resulting in a cut off point where the scene will remain dark.
</member>
<member name="exposure_aperture" type="float" setter="set_aperture" getter="get_aperture" default="16.0">
Size of the aperture of the camera, measured in f-stops. An f-stop is a unitless ratio between the focal length of the camera and the diameter of the aperture. A high aperture setting will result in a smaller aperture which leads to a dimmer image and sharper focus. A low aperture results in a wide aperture which lets in more light resulting in a brighter, less-focused image. Default is appropriate for outdoors at daytime (i.e. for use with a default [DirectionalLight3D]), for indoor lighting, a value between 2 and 4 is more appropriate.

85
engine/doc/classes/CameraFeed.xml
View file

@ -6,10 +6,23 @@
<description>
A camera feed gives you access to a single physical camera attached to your device. When enabled, Godot will start capturing frames from the camera which can then be used. See also [CameraServer].
[b]Note:[/b] Many cameras will return YCbCr images which are split into two textures and need to be combined in a shader. Godot does this automatically for you if you set the environment to show the camera image in the background.
[b]Note:[/b] This class is currently only implemented on Linux, macOS, and iOS. On other platforms no [CameraFeed]s will be available. To get a [CameraFeed] on iOS, the camera plugin from [url=https://github.com/godotengine/godot-ios-plugins]godot-ios-plugins[/url] is required.
</description>
<tutorials>
</tutorials>
<methods>
<method name="_activate_feed" qualifiers="virtual">
<return type="bool" />
<description>
Called when the camera feed is activated.
</description>
</method>
<method name="_deactivate_feed" qualifiers="virtual">
<return type="void" />
<description>
Called when the camera feed is deactivated.
</description>
</method>
<method name="get_datatype" qualifiers="const">
<return type="int" enum="CameraFeed.FeedDataType" />
<description>
@ -34,6 +47,60 @@
Returns the position of camera on the device.
</description>
</method>
<method name="get_texture_tex_id">
<return type="int" />
<param index="0" name="feed_image_type" type="int" enum="CameraServer.FeedImage" />
<description>
Returns the texture backend ID (usable by some external libraries that need a handle to a texture to write data).
</description>
</method>
<method name="set_external">
<return type="void" />
<param index="0" name="width" type="int" />
<param index="1" name="height" type="int" />
<description>
Sets the feed as external feed provided by another library.
</description>
</method>
<method name="set_format">
<return type="bool" />
<param index="0" name="index" type="int" />
<param index="1" name="parameters" type="Dictionary" />
<description>
Sets the feed format parameters for the given index in the [member formats] array. Returns [code]true[/code] on success. By default YUYV encoded stream is transformed to FEED_RGB. YUYV encoded stream output format can be changed with [param parameters].output value:
[code]separate[/code] will result in FEED_YCBCR_SEP
[code]grayscale[/code] will result in desaturated FEED_RGB
[code]copy[/code] will result in FEED_YCBCR
</description>
</method>
<method name="set_name">
<return type="void" />
<param index="0" name="name" type="String" />
<description>
Sets the camera's name.
</description>
</method>
<method name="set_position">
<return type="void" />
<param index="0" name="position" type="int" enum="CameraFeed.FeedPosition" />
<description>
Sets the position of this camera.
</description>
</method>
<method name="set_rgb_image">
<return type="void" />
<param index="0" name="rgb_image" type="Image" />
<description>
Sets RGB image for this feed.
</description>
</method>
<method name="set_ycbcr_image">
<return type="void" />
<param index="0" name="ycbcr_image" type="Image" />
<description>
Sets YCbCr image for this feed.
</description>
</method>
</methods>
<members>
<member name="feed_is_active" type="bool" setter="set_active" getter="is_active" default="false">
@ -42,7 +109,22 @@
<member name="feed_transform" type="Transform2D" setter="set_transform" getter="get_transform" default="Transform2D(1, 0, 0, -1, 0, 1)">
The transform applied to the camera's image.
</member>
<member name="formats" type="Array" setter="" getter="get_formats" default="[]">
Formats supported by the feed. Each entry is a [Dictionary] describing format parameters.
</member>
</members>
<signals>
<signal name="format_changed">
<description>
Emitted when the format has changed.
</description>
</signal>
<signal name="frame_changed">
<description>
Emitted when a new frame is available.
</description>
</signal>
</signals>
<constants>
<constant name="FEED_NOIMAGE" value="0" enum="FeedDataType">
No image set for the feed.
@ -56,6 +138,9 @@
<constant name="FEED_YCBCR_SEP" value="3" enum="FeedDataType">
Feed supplies separate Y and CbCr images that need to be combined and converted to RGB.
</constant>
<constant name="FEED_EXTERNAL" value="4" enum="FeedDataType">
Feed supplies external image.
</constant>
<constant name="FEED_UNSPECIFIED" value="0" enum="FeedPosition">
Unspecified position.
</constant>

2
engine/doc/classes/CameraServer.xml
View file

@ -6,7 +6,7 @@
<description>
The [CameraServer] keeps track of different cameras accessible in Godot. These are external cameras such as webcams or the cameras on your phone.
It is notably used to provide AR modules with a video feed from the camera.
[b]Note:[/b] This class is currently only implemented on macOS and iOS. To get a [CameraFeed] on iOS, the camera plugin from [url=https://github.com/godotengine/godot-ios-plugins]godot-ios-plugins[/url] is required. On other platforms, no [CameraFeed]s will be available.
[b]Note:[/b] This class is currently only implemented on Linux, macOS, and iOS. On other platforms no [CameraFeed]s will be available. To get a [CameraFeed] on iOS, the camera plugin from [url=https://github.com/godotengine/godot-ios-plugins]godot-ios-plugins[/url] is required.
</description>
<tutorials>
</tutorials>

46
engine/doc/classes/CanvasItem.xml
View file

@ -96,6 +96,7 @@
<param index="3" name="texture" type="Texture2D" default="null" />
<description>
Draws a colored polygon of any number of points, convex or concave. Unlike [method draw_polygon], a single color must be specified for the whole polygon.
[b]Note:[/b] If you frequently redraw the same polygon with a large number of vertices, consider pre-calculating the triangulation with [method Geometry2D.triangulate_polygon] and using [method draw_mesh], [method draw_multimesh], or [method RenderingServer.canvas_item_add_triangle_array].
</description>
</method>
<method name="draw_dashed_line">
@ -108,8 +109,9 @@
<param index="5" name="aligned" type="bool" default="true" />
<param index="6" name="antialiased" type="bool" default="false" />
<description>
Draws a dashed line from a 2D point to another, with a given color and width. See also [method draw_multiline] and [method draw_polyline].
Draws a dashed line from a 2D point to another, with a given color and width. See also [method draw_line], [method draw_multiline], and [method draw_polyline].
If [param width] is negative, then a two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the line parts will remain thin. If this behavior is not desired, then pass a positive [param width] like [code]1.0[/code].
[param dash] is the length of each dash in pixels, with the gap between each dash being the same length. If [param aligned] is [code]true[/code], the length of the first and last dashes may be shortened or lengthened to allow the line to begin and end at the precise points defined by [param from] and [param to]. Both ends are always symmetrical when [param aligned] is [code]true[/code]. If [param aligned] is [code]false[/code], all dashes will have the same length, but the line may appear incomplete at the end due to the dash length not dividing evenly into the line length. Only full dashes are drawn when [param aligned] is [code]false[/code].
If [param antialiased] is [code]true[/code], half transparent "feathers" will be attached to the boundary, making outlines smooth.
[b]Note:[/b] [param antialiased] is only effective if [param width] is greater than [code]0.0[/code].
</description>
@ -145,7 +147,7 @@
<param index="3" name="width" type="float" default="-1.0" />
<param index="4" name="antialiased" type="bool" default="false" />
<description>
Draws a line from a 2D point to another, with a given color and width. It can be optionally antialiased. See also [method draw_multiline] and [method draw_polyline].
Draws a line from a 2D point to another, with a given color and width. It can be optionally antialiased. See also [method draw_dashed_line], [method draw_multiline], and [method draw_polyline].
If [param width] is negative, then a two-point primitive will be drawn instead of a four-point one. This means that when the CanvasItem is scaled, the line will remain thin. If this behavior is not desired, then pass a positive [param width] like [code]1.0[/code].
</description>
</method>
@ -251,6 +253,7 @@
<param index="3" name="texture" type="Texture2D" default="null" />
<description>
Draws a solid polygon of any number of points, convex or concave. Unlike [method draw_colored_polygon], each point's color can be changed individually. See also [method draw_polyline] and [method draw_polyline_colors]. If you need more flexibility (such as being able to use bones), use [method RenderingServer.canvas_item_add_triangle_array] instead.
[b]Note:[/b] If you frequently redraw the same polygon with a large number of vertices, consider pre-calculating the triangulation with [method Geometry2D.triangulate_polygon] and using [method draw_mesh], [method draw_multimesh], or [method RenderingServer.canvas_item_add_triangle_array].
</description>
</method>
<method name="draw_polyline">
@ -331,7 +334,7 @@
<param index="9" name="orientation" type="int" enum="TextServer.Orientation" default="0" />
<description>
Draws [param text] using the specified [param font] at the [param pos] (bottom-left corner using the baseline of the font). The text will have its color multiplied by [param modulate]. If [param width] is greater than or equal to 0, the text will be clipped if it exceeds the specified width.
[b]Example using the default project font:[/b]
[b]Example:[/b] Draw "Hello world", using the project's default font:
[codeblocks]
[gdscript]
# If using this method in a script that redraws constantly, move the
@ -459,6 +462,13 @@
Returns the transform from the local coordinate system of this [CanvasItem] to the [Viewport]s coordinate system.
</description>
</method>
<method name="get_instance_shader_parameter" qualifiers="const">
<return type="Variant" />
<param index="0" name="name" type="StringName" />
<description>
Get the value of a shader parameter as set on this instance.
</description>
</method>
<method name="get_local_mouse_position" qualifiers="const">
<return type="Vector2" />
<description>
@ -526,13 +536,18 @@
<description>
Returns [code]true[/code] if the node is present in the [SceneTree], its [member visible] property is [code]true[/code] and all its ancestors are also visible. If any ancestor is hidden, this node will not be visible in the scene tree, and is therefore not drawn (see [method _draw]).
Visibility is checked only in parent nodes that inherit from [CanvasItem], [CanvasLayer], and [Window]. If the parent is of any other type (such as [Node], [AnimationPlayer], or [Node3D]), it is assumed to be visible.
[b]Note:[/b] This method does not take [member visibility_layer] into account, so even if this method returns [code]true[/code], the node might end up not being rendered.
</description>
</method>
<method name="make_canvas_position_local" qualifiers="const">
<return type="Vector2" />
<param index="0" name="screen_point" type="Vector2" />
<param index="0" name="viewport_point" type="Vector2" />
<description>
Assigns [param screen_point] as this node's new local transform.
Transforms [param viewport_point] from the viewport's coordinates to this node's local coordinates.
For the opposite operation, use [method get_global_transform_with_canvas].
[codeblock]
var viewport_point = get_global_transform_with_canvas() * local_point
[/codeblock]
</description>
</method>
<method name="make_input_local" qualifiers="const">
@ -555,6 +570,16 @@
Queues the [CanvasItem] to redraw. During idle time, if [CanvasItem] is visible, [constant NOTIFICATION_DRAW] is sent and [method _draw] is called. This only occurs [b]once[/b] per frame, even if this method has been called multiple times.
</description>
</method>
<method name="set_instance_shader_parameter">
<return type="void" />
<param index="0" name="name" type="StringName" />
<param index="1" name="value" type="Variant" />
<description>
Set the value of a shader uniform for this instance only ([url=$DOCS_URL/tutorials/shaders/shader_reference/shading_language.html#per-instance-uniforms]per-instance uniform[/url]). See also [method ShaderMaterial.set_shader_parameter] to assign a uniform on all instances using the same [ShaderMaterial].
[b]Note:[/b] For a shader uniform to be assignable on a per-instance basis, it [i]must[/i] be defined with [code]instance uniform ...[/code] rather than [code]uniform ...[/code] in the shader code.
[b]Note:[/b] [param name] is case-sensitive and must match the name of the uniform in the code exactly (not the capitalized name in the inspector).
</description>
</method>
<method name="set_notify_local_transform">
<return type="void" />
<param index="0" name="enable" type="bool" />
@ -587,6 +612,7 @@
<members>
<member name="clip_children" type="int" setter="set_clip_children_mode" getter="get_clip_children_mode" enum="CanvasItem.ClipChildrenMode" default="0">
Allows the current node to clip child nodes, essentially acting as a mask.
[b]Note:[/b] Clipping nodes cannot be nested or placed within [CanvasGroup]s. If an ancestor of this node clips its children or is a [CanvasGroup], then this node's clip mode should be set to [constant CLIP_CHILDREN_DISABLED] to avoid unexpected behavior.
</member>
<member name="light_mask" type="int" setter="set_light_mask" getter="get_light_mask" default="1">
The rendering layers in which this [CanvasItem] responds to [Light2D] nodes.
@ -620,12 +646,12 @@
The rendering layer in which this [CanvasItem] is rendered by [Viewport] nodes. A [Viewport] will render a [CanvasItem] if it and all its parents share a layer with the [Viewport]'s canvas cull mask.
</member>
<member name="visible" type="bool" setter="set_visible" getter="is_visible" default="true">
If [code]true[/code], this [CanvasItem] is drawn. The node is only visible if all of its ancestors are visible as well (in other words, [method is_visible_in_tree] must return [code]true[/code]).
If [code]true[/code], this [CanvasItem] may be drawn. Whether this [CanvasItem] is actually drawn depends on the visibility of all of its [CanvasItem] ancestors. In other words: this [CanvasItem] will be drawn when [method is_visible_in_tree] returns [code]true[/code] and all [CanvasItem] ancestors share at least one [member visibility_layer] with this [CanvasItem].
[b]Note:[/b] For controls that inherit [Popup], the correct way to make them visible is to call one of the multiple [code]popup*()[/code] functions instead.
</member>
<member name="y_sort_enabled" type="bool" setter="set_y_sort_enabled" getter="is_y_sort_enabled" default="false">
If [code]true[/code], this and child [CanvasItem] nodes with a higher Y position are rendered in front of nodes with a lower Y position. If [code]false[/code], this and child [CanvasItem] nodes are rendered normally in scene tree order.
With Y-sorting enabled on a parent node ('A') but disabled on a child node ('B'), the child node ('B') is sorted but its children ('C1', 'C2', etc) render together on the same Y position as the child node ('B'). This allows you to organize the render order of a scene without changing the scene tree.
With Y-sorting enabled on a parent node ('A') but disabled on a child node ('B'), the child node ('B') is sorted but its children ('C1', 'C2', etc.) render together on the same Y position as the child node ('B'). This allows you to organize the render order of a scene without changing the scene tree.
Nodes sort relative to each other only if they are on the same [member z_index].
</member>
<member name="z_as_relative" type="bool" setter="set_z_as_relative" getter="is_z_relative" default="true">
@ -645,17 +671,17 @@
</signal>
<signal name="hidden">
<description>
Emitted when becoming hidden.
Emitted when the [CanvasItem] is hidden, i.e. it's no longer visible in the tree (see [method is_visible_in_tree]).
</description>
</signal>
<signal name="item_rect_changed">
<description>
Emitted when the item's [Rect2] boundaries (position or size) have changed, or when an action is taking place that may have impacted these boundaries (e.g. changing [member Sprite2D.texture]).
Emitted when the [CanvasItem]'s boundaries (position or size) change, or when an action took place that may have affected these boundaries (e.g. changing [member Sprite2D.texture]).
</description>
</signal>
<signal name="visibility_changed">
<description>
Emitted when the visibility (hidden/visible) changes.
Emitted when the [CanvasItem]'s visibility changes, either because its own [member visible] property changed or because its visibility in the tree changed (see [method is_visible_in_tree]).
</description>
</signal>
</signals>

4
engine/doc/classes/CanvasLayer.xml
View file

@ -45,8 +45,8 @@
The custom [Viewport] node assigned to the [CanvasLayer]. If [code]null[/code], uses the default viewport instead.
</member>
<member name="follow_viewport_enabled" type="bool" setter="set_follow_viewport" getter="is_following_viewport" default="false">
If enabled, the [CanvasLayer] will use the viewport's transform, so it will move when camera moves instead of being anchored in a fixed position on the screen.
Together with [member follow_viewport_scale] it can be used for a pseudo 3D effect.
If enabled, the [CanvasLayer] stays in a fixed position on the screen. If disabled, the [CanvasLayer] maintains its position in world space.
Together with [member follow_viewport_scale], this can be used for a pseudo-3D effect.
</member>
<member name="follow_viewport_scale" type="float" setter="set_follow_viewport_scale" getter="get_follow_viewport_scale" default="1.0">
Scales the layer when using [member follow_viewport_enabled]. Layers moving into the foreground should have increasing scales, while layers moving into the background should have decreasing scales.

1
engine/doc/classes/CanvasModulate.xml
View file

@ -7,6 +7,7 @@
[CanvasModulate] applies a color tint to all nodes on a canvas. Only one can be used to tint a canvas, but [CanvasLayer]s can be used to render things independently.
</description>
<tutorials>
<link title="2D lights and shadows">$DOCS_URL/tutorials/2d/2d_lights_and_shadows.html</link>
</tutorials>
<members>
<member name="color" type="Color" setter="set_color" getter="get_color" default="Color(1, 1, 1, 1)" keywords="colour">

21
engine/doc/classes/CharFXTransform.xml
View file

@ -8,7 +8,6 @@
</description>
<tutorials>
<link title="BBCode in RichTextLabel">$DOCS_URL/tutorials/ui/bbcode_in_richtextlabel.html</link>
<link title="RichTextEffect test project (third-party)">https://github.com/Eoin-ONeill-Yokai/Godot-Rich-Text-Effect-Test-Project</link>
</tutorials>
<members>
<member name="color" type="Color" setter="set_color" getter="get_color" default="Color(0, 0, 0, 1)" keywords="colour">
@ -26,28 +25,34 @@
[/codeblock]
</member>
<member name="font" type="RID" setter="set_font" getter="get_font" default="RID()">
Font resource used to render glyph.
[TextServer] RID of the font used to render glyph, this value can be used with [code]TextServer.font_*[/code] methods to retrieve font information.
[b]Note:[/b] Read-only. Setting this property won't affect drawing.
</member>
<member name="glyph_count" type="int" setter="set_glyph_count" getter="get_glyph_count" default="0">
Number of glyphs in the grapheme cluster. This value is set in the first glyph of a cluster. Setting this property won't affect drawing.
Number of glyphs in the grapheme cluster. This value is set in the first glyph of a cluster.
[b]Note:[/b] Read-only. Setting this property won't affect drawing.
</member>
<member name="glyph_flags" type="int" setter="set_glyph_flags" getter="get_glyph_flags" default="0">
Glyph flags. See [enum TextServer.GraphemeFlag] for more info. Setting this property won't affect drawing.
Glyph flags. See [enum TextServer.GraphemeFlag] for more info.
[b]Note:[/b] Read-only. Setting this property won't affect drawing.
</member>
<member name="glyph_index" type="int" setter="set_glyph_index" getter="get_glyph_index" default="0">
Font specific glyph index.
Glyph index specific to the [member font]. If you want to replace this glyph, use [method TextServer.font_get_glyph_index] with [member font] to get a new glyph index for a single character.
</member>
<member name="offset" type="Vector2" setter="set_offset" getter="get_offset" default="Vector2(0, 0)">
The position offset the character will be drawn with (in pixels).
</member>
<member name="outline" type="bool" setter="set_outline" getter="is_outline" default="false">
If [code]true[/code], FX transform is called for outline drawing. Setting this property won't affect drawing.
If [code]true[/code], FX transform is called for outline drawing.
[b]Note:[/b] Read-only. Setting this property won't affect drawing.
</member>
<member name="range" type="Vector2i" setter="set_range" getter="get_range" default="Vector2i(0, 0)">
Absolute character range in the string, corresponding to the glyph. Setting this property won't affect drawing.
Absolute character range in the string, corresponding to the glyph.
[b]Note:[/b] Read-only. Setting this property won't affect drawing.
</member>
<member name="relative_index" type="int" setter="set_relative_index" getter="get_relative_index" default="0">
The character offset of the glyph, relative to the current [RichTextEffect] custom block. Setting this property won't affect drawing.
The character offset of the glyph, relative to the current [RichTextEffect] custom block.
[b]Note:[/b] Read-only. Setting this property won't affect drawing.
</member>
<member name="transform" type="Transform2D" setter="set_transform" getter="get_transform" default="Transform2D(1, 0, 0, 1, 0, 0)">
The current transform of the current glyph. It can be overridden (for example, by driving the position and rotation from a curve). You can also alter the existing value to apply transforms on top of other effects.

2
engine/doc/classes/CharacterBody2D.xml
View file

@ -69,7 +69,7 @@
<param index="0" name="slide_idx" type="int" />
<description>
Returns a [KinematicCollision2D], which contains information about a collision that occurred during the last call to [method move_and_slide]. Since the body can collide several times in a single call to [method move_and_slide], you must specify the index of the collision in the range 0 to ([method get_slide_collision_count] - 1).
[b]Example usage:[/b]
[b]Example:[/b] Iterate through the collisions with a [code]for[/code] loop:
[codeblocks]
[gdscript]
for i in get_slide_collision_count():

48
engine/doc/classes/ClassDB.xml
View file

@ -16,6 +16,14 @@
Returns [code]true[/code] if objects can be instantiated from the specified [param class], otherwise returns [code]false[/code].
</description>
</method>
<method name="class_call_static" qualifiers="vararg">
<return type="Variant" />
<param index="0" name="class" type="StringName" />
<param index="1" name="method" type="StringName" />
<description>
Calls a static method on a class.
</description>
</method>
<method name="class_exists" qualifiers="const">
<return type="bool" />
<param index="0" name="class" type="StringName" />
@ -23,6 +31,13 @@
Returns whether the specified [param class] is available or not.
</description>
</method>
<method name="class_get_api_type" qualifiers="const">
<return type="int" enum="ClassDB.APIType" />
<param index="0" name="class" type="StringName" />
<description>
Returns the API type of [param class]. See [enum APIType].
</description>
</method>
<method name="class_get_enum_constants" qualifiers="const">
<return type="PackedStringArray" />
<param index="0" name="class" type="StringName" />
@ -99,6 +114,14 @@
Returns the default value of [param property] of [param class] or its ancestor classes.
</description>
</method>
<method name="class_get_property_getter">
<return type="StringName" />
<param index="0" name="class" type="StringName" />
<param index="1" name="property" type="StringName" />
<description>
Returns the getter method name of [param property] of [param class].
</description>
</method>
<method name="class_get_property_list" qualifiers="const">
<return type="Dictionary[]" />
<param index="0" name="class" type="StringName" />
@ -107,6 +130,14 @@
Returns an array with all the properties of [param class] or its ancestry if [param no_inheritance] is [code]false[/code].
</description>
</method>
<method name="class_get_property_setter">
<return type="StringName" />
<param index="0" name="class" type="StringName" />
<param index="1" name="property" type="StringName" />
<description>
Returns the setter method name of [param property] of [param class].
</description>
</method>
<method name="class_get_signal" qualifiers="const">
<return type="Dictionary" />
<param index="0" name="class" type="StringName" />
@ -218,4 +249,21 @@
</description>
</method>
</methods>
<constants>
<constant name="API_CORE" value="0" enum="APIType">
Native Core class type.
</constant>
<constant name="API_EDITOR" value="1" enum="APIType">
Native Editor class type.
</constant>
<constant name="API_EXTENSION" value="2" enum="APIType">
GDExtension class type.
</constant>
<constant name="API_EDITOR_EXTENSION" value="3" enum="APIType">
GDExtension Editor class type.
</constant>
<constant name="API_NONE" value="4" enum="APIType">
Unknown class type.
</constant>
</constants>
</class>

78
engine/doc/classes/CodeEdit.xml
View file

@ -80,7 +80,7 @@
<return type="bool" />
<param index="0" name="line" type="int" />
<description>
Returns if the given line is foldable, that is, it has indented lines right below it or a comment / string block.
Returns [code]true[/code] if the given line is foldable. A line is foldable if it is the start of a valid code region (see [method get_code_region_start_tag]), if it is the start of a comment or string block, or if the next non-empty line is more indented (see [method TextEdit.get_indent_level]).
</description>
</method>
<method name="cancel_code_completion">
@ -153,7 +153,7 @@
<method name="do_indent">
<return type="void" />
<description>
Perform an indent as if the user activated the "ui_text_indent" action.
If there is no selection, indentation is inserted at the caret. Otherwise, the selected lines are indented like [method indent_lines]. Equivalent to the [member ProjectSettings.input/ui_text_indent] action. The indentation characters used depend on [member indent_use_spaces] and [member indent_size].
</description>
</method>
<method name="duplicate_lines">
@ -276,7 +276,7 @@
<method name="get_folded_lines" qualifiers="const">
<return type="int[]" />
<description>
Returns all lines that are current folded.
Returns all lines that are currently folded.
</description>
</method>
<method name="get_text_for_code_completion" qualifiers="const">
@ -330,7 +330,7 @@
<method name="indent_lines">
<return type="void" />
<description>
Indents selected lines, or in the case of no selection the caret line by one.
Indents all lines that are selected or have a caret on them. Uses spaces or a tab depending on [member indent_use_spaces]. See [method unindent_lines].
</description>
</method>
<method name="is_in_comment" qualifiers="const">
@ -353,42 +353,42 @@
<return type="bool" />
<param index="0" name="line" type="int" />
<description>
Returns whether the line at the specified index is bookmarked or not.
Returns [code]true[/code] if the given line is bookmarked. See [method set_line_as_bookmarked].
</description>
</method>
<method name="is_line_breakpointed" qualifiers="const">
<return type="bool" />
<param index="0" name="line" type="int" />
<description>
Returns whether the line at the specified index is breakpointed or not.
Returns [code]true[/code] if the given line is breakpointed. See [method set_line_as_breakpoint].
</description>
</method>
<method name="is_line_code_region_end" qualifiers="const">
<return type="bool" />
<param index="0" name="line" type="int" />
<description>
Returns whether the line at the specified index is a code region end.
Returns [code]true[/code] if the given line is a code region end. See [method set_code_region_tags].
</description>
</method>
<method name="is_line_code_region_start" qualifiers="const">
<return type="bool" />
<param index="0" name="line" type="int" />
<description>
Returns whether the line at the specified index is a code region start.
Returns [code]true[/code] if the given line is a code region start. See [method set_code_region_tags].
</description>
</method>
<method name="is_line_executing" qualifiers="const">
<return type="bool" />
<param index="0" name="line" type="int" />
<description>
Returns whether the line at the specified index is marked as executing or not.
Returns [code]true[/code] if the given line is marked as executing. See [method set_line_as_executing].
</description>
</method>
<method name="is_line_folded" qualifiers="const">
<return type="bool" />
<param index="0" name="line" type="int" />
<description>
Returns whether the line at the specified index is folded or not.
Returns [code]true[/code] if the given line is folded. See [method fold_line].
</description>
</method>
<method name="move_lines_down">
@ -442,7 +442,7 @@
<return type="void" />
<param index="0" name="draw_below" type="bool" />
<description>
Sets if the code hint should draw below the text.
If [code]true[/code], the code hint will draw below the main caret. If [code]false[/code], the code hint will draw above the main caret. See [method set_code_hint].
</description>
</method>
<method name="set_code_region_tags">
@ -458,7 +458,7 @@
<param index="0" name="line" type="int" />
<param index="1" name="bookmarked" type="bool" />
<description>
Sets the line as bookmarked.
Sets the given line as bookmarked. If [code]true[/code] and [member gutters_draw_bookmarks] is [code]true[/code], draws the [theme_item bookmark] icon in the gutter for this line. See [method get_bookmarked_lines] and [method is_line_bookmarked].
</description>
</method>
<method name="set_line_as_breakpoint">
@ -466,7 +466,7 @@
<param index="0" name="line" type="int" />
<param index="1" name="breakpointed" type="bool" />
<description>
Sets the line as breakpointed.
Sets the given line as a breakpoint. If [code]true[/code] and [member gutters_draw_breakpoints_gutter] is [code]true[/code], draws the [theme_item breakpoint] icon in the gutter for this line. See [method get_breakpointed_lines] and [method is_line_breakpointed].
</description>
</method>
<method name="set_line_as_executing">
@ -474,7 +474,7 @@
<param index="0" name="line" type="int" />
<param index="1" name="executing" type="bool" />
<description>
Sets the line as executing.
Sets the given line as executing. If [code]true[/code] and [member gutters_draw_executing_lines] is [code]true[/code], draws the [theme_item executing_line] icon in the gutter for this line. See [method get_executing_lines] and [method is_line_executing].
</description>
</method>
<method name="set_symbol_lookup_word_as_valid">
@ -500,20 +500,20 @@
<method name="unfold_all_lines">
<return type="void" />
<description>
Unfolds all lines, folded or not.
Unfolds all lines that are folded.
</description>
</method>
<method name="unfold_line">
<return type="void" />
<param index="0" name="line" type="int" />
<description>
Unfolds all lines that were previously folded.
Unfolds the given line if it is folded or if it is hidden under a folded line.
</description>
</method>
<method name="unindent_lines">
<return type="void" />
<description>
Unindents selected lines, or in the case of no selection the caret line by one. Same as performing "ui_text_unindent" action.
Unindents all lines that are selected or have a caret on them. Uses spaces or a tab depending on [member indent_use_spaces]. Equivalent to the [member ProjectSettings.input/ui_text_dedent] action. See [method indent_lines].
</description>
</method>
<method name="update_code_completion_options">
@ -527,16 +527,16 @@
</methods>
<members>
<member name="auto_brace_completion_enabled" type="bool" setter="set_auto_brace_completion_enabled" getter="is_auto_brace_completion_enabled" default="false">
Sets whether brace pairs should be autocompleted.
If [code]true[/code], uses [member auto_brace_completion_pairs] to automatically insert the closing brace when the opening brace is inserted by typing or autocompletion. Also automatically removes the closing brace when using backspace on the opening brace.
</member>
<member name="auto_brace_completion_highlight_matching" type="bool" setter="set_highlight_matching_braces_enabled" getter="is_highlight_matching_braces_enabled" default="false">
Highlight mismatching brace pairs.
If [code]true[/code], highlights brace pairs when the caret is on either one, using [member auto_brace_completion_pairs]. If matching, the pairs will be underlined. If a brace is unmatched, it is colored with [theme_item brace_mismatch_color].
</member>
<member name="auto_brace_completion_pairs" type="Dictionary" setter="set_auto_brace_completion_pairs" getter="get_auto_brace_completion_pairs" default="{ &quot;\&quot;&quot;: &quot;\&quot;&quot;, &quot;&apos;&quot;: &quot;&apos;&quot;, &quot;(&quot;: &quot;)&quot;, &quot;[&quot;: &quot;]&quot;, &quot;{&quot;: &quot;}&quot; }">
Sets the brace pairs to be autocompleted.
Sets the brace pairs to be autocompleted. For each entry in the dictionary, the key is the opening brace and the value is the closing brace that matches it. A brace is a [String] made of symbols. See [member auto_brace_completion_enabled] and [member auto_brace_completion_highlight_matching].
</member>
<member name="code_completion_enabled" type="bool" setter="set_code_completion_enabled" getter="is_code_completion_enabled" default="false">
Sets whether code completion is allowed.
If [code]true[/code], the [member ProjectSettings.input/ui_text_completion_query] action requests code completion. To handle it, see [method _request_code_completion] or [signal code_completion_requested].
</member>
<member name="code_completion_prefixes" type="String[]" setter="set_code_completion_prefixes" getter="get_code_completion_prefixes" default="[]">
Sets prefixes that will trigger code completion.
@ -548,28 +548,28 @@
Sets the string delimiters. All existing string delimiters will be removed.
</member>
<member name="gutters_draw_bookmarks" type="bool" setter="set_draw_bookmarks_gutter" getter="is_drawing_bookmarks_gutter" default="false">
Sets if bookmarked should be drawn in the gutter. This gutter is shared with breakpoints and executing lines.
If [code]true[/code], bookmarks are drawn in the gutter. This gutter is shared with breakpoints and executing lines. See [method set_line_as_bookmarked].
</member>
<member name="gutters_draw_breakpoints_gutter" type="bool" setter="set_draw_breakpoints_gutter" getter="is_drawing_breakpoints_gutter" default="false">
Sets if breakpoints should be drawn in the gutter. This gutter is shared with bookmarks and executing lines.
If [code]true[/code], breakpoints are drawn in the gutter. This gutter is shared with bookmarks and executing lines. Clicking the gutter will toggle the breakpoint for the line, see [method set_line_as_breakpoint].
</member>
<member name="gutters_draw_executing_lines" type="bool" setter="set_draw_executing_lines_gutter" getter="is_drawing_executing_lines_gutter" default="false">
Sets if executing lines should be marked in the gutter. This gutter is shared with breakpoints and bookmarks lines.
If [code]true[/code], executing lines are marked in the gutter. This gutter is shared with breakpoints and bookmarks. See [method set_line_as_executing].
</member>
<member name="gutters_draw_fold_gutter" type="bool" setter="set_draw_fold_gutter" getter="is_drawing_fold_gutter" default="false">
Sets if foldable lines icons should be drawn in the gutter.
If [code]true[/code], the fold gutter is drawn. In this gutter, the [theme_item can_fold_code_region] icon is drawn for each foldable line (see [method can_fold_line]) and the [theme_item folded_code_region] icon is drawn for each folded line (see [method is_line_folded]). These icons can be clicked to toggle the fold state, see [method toggle_foldable_line]. [member line_folding] must be [code]true[/code] to show icons.
</member>
<member name="gutters_draw_line_numbers" type="bool" setter="set_draw_line_numbers" getter="is_draw_line_numbers_enabled" default="false">
Sets if line numbers should be drawn in the gutter.
If [code]true[/code], the line number gutter is drawn. Line numbers start at [code]1[/code] and are incremented for each line of text. Clicking and dragging in the line number gutter will select entire lines of text.
</member>
<member name="gutters_zero_pad_line_numbers" type="bool" setter="set_line_numbers_zero_padded" getter="is_line_numbers_zero_padded" default="false">
Sets if line numbers drawn in the gutter are zero padded.
If [code]true[/code], line numbers drawn in the gutter are zero padded based on the total line count. Requires [member gutters_draw_line_numbers] to be set to [code]true[/code].
</member>
<member name="indent_automatic" type="bool" setter="set_auto_indent_enabled" getter="is_auto_indent_enabled" default="false">
Sets whether automatic indent are enabled, this will add an extra indent if a prefix or brace is found.
If [code]true[/code], an extra indent is automatically inserted when a new line is added and a prefix in [member indent_automatic_prefixes] is found. If a brace pair opening key is found, the matching closing brace will be moved to another new line (see [member auto_brace_completion_pairs]).
</member>
<member name="indent_automatic_prefixes" type="String[]" setter="set_auto_indent_prefixes" getter="get_auto_indent_prefixes" default="[&quot;:&quot;, &quot;{&quot;, &quot;[&quot;, &quot;(&quot;]">
Prefixes to trigger an automatic indent.
Prefixes to trigger an automatic indent. Used when [member indent_automatic] is set to [code]true[/code].
</member>
<member name="indent_size" type="int" setter="set_indent_size" getter="get_indent_size" default="4">
Size of the tabulation indent (one [kbd]Tab[/kbd] press) in characters. If [member indent_use_spaces] is enabled the number of spaces to use.
@ -579,7 +579,7 @@
</member>
<member name="layout_direction" type="int" setter="set_layout_direction" getter="get_layout_direction" overrides="Control" enum="Control.LayoutDirection" default="2" />
<member name="line_folding" type="bool" setter="set_line_folding_enabled" getter="is_line_folding_enabled" default="false">
Sets whether line folding is allowed.
If [code]true[/code], lines can be folded. Otherwise, line folding methods like [method fold_line] will not work and [method can_fold_line] will always return [code]false[/code]. See [member gutters_draw_fold_gutter].
</member>
<member name="line_length_guidelines" type="int[]" setter="set_line_length_guidelines" getter="get_line_length_guidelines" default="[]">
Draws vertical lines at the provided columns. The first entry is considered a main hard guideline and is draw more prominently.
@ -587,6 +587,9 @@
<member name="symbol_lookup_on_click" type="bool" setter="set_symbol_lookup_on_click_enabled" getter="is_symbol_lookup_on_click_enabled" default="false">
Set when a validated word from [signal symbol_validate] is clicked, the [signal symbol_lookup] should be emitted.
</member>
<member name="symbol_tooltip_on_hover" type="bool" setter="set_symbol_tooltip_on_hover_enabled" getter="is_symbol_tooltip_on_hover_enabled" default="false">
Set when a word is hovered, the [signal symbol_hovered] should be emitted.
</member>
<member name="text_direction" type="int" setter="set_text_direction" getter="get_text_direction" overrides="TextEdit" enum="Control.TextDirection" default="1" />
</members>
<signals>
@ -598,7 +601,16 @@
</signal>
<signal name="code_completion_requested">
<description>
Emitted when the user requests code completion.
Emitted when the user requests code completion. This signal will not be sent if [method _request_code_completion] is overridden or [member code_completion_enabled] is [code]false[/code].
</description>
</signal>
<signal name="symbol_hovered">
<param index="0" name="symbol" type="String" />
<param index="1" name="line" type="int" />
<param index="2" name="column" type="int" />
<description>
Emitted when the user hovers over a symbol. Unlike [signal Control.mouse_entered], this signal is not emitted immediately, but when the cursor is over the symbol for [member ProjectSettings.gui/timers/tooltip_delay_sec] seconds.
[b]Note:[/b] [member symbol_tooltip_on_hover] must be [code]true[/code] for this signal to be emitted.
</description>
</signal>
<signal name="symbol_lookup">
@ -613,6 +625,7 @@
<param index="0" name="symbol" type="String" />
<description>
Emitted when the user hovers over a symbol. The symbol should be validated and responded to, by calling [method set_symbol_lookup_word_as_valid].
[b]Note:[/b] [member symbol_lookup_on_click] must be [code]true[/code] for this signal to be emitted.
</description>
</signal>
</signals>
@ -721,6 +734,9 @@
<theme_item name="can_fold_code_region" data_type="icon" type="Texture2D">
Sets a custom [Texture2D] to draw in the line folding gutter when a code region can be folded.
</theme_item>
<theme_item name="completion_color_bg" data_type="icon" type="Texture2D">
Background panel for the color preview box in autocompletion (visible when the color is translucent).
</theme_item>
<theme_item name="executing_line" data_type="icon" type="Texture2D">
Icon to draw in the executing gutter for executing lines.
</theme_item>

2
engine/doc/classes/CollisionPolygon2D.xml
View file

@ -5,7 +5,7 @@
</brief_description>
<description>
A node that provides a polygon shape to a [CollisionObject2D] parent and allows to edit it. The polygon can be concave or convex. This can give a detection shape to an [Area2D], turn [PhysicsBody2D] into a solid object, or give a hollow shape to a [StaticBody2D].
[b]Warning:[/b] A non-uniformly scaled [CollisionShape2D] will likely not behave as expected. Make sure to keep its scale the same on all axes and adjust its shape resource instead.
[b]Warning:[/b] A non-uniformly scaled [CollisionPolygon2D] will likely not behave as expected. Make sure to keep its scale the same on all axes and adjust its polygon instead.
</description>
<tutorials>
</tutorials>

7
engine/doc/classes/CollisionPolygon3D.xml
View file

@ -10,6 +10,13 @@
<tutorials>
</tutorials>
<members>
<member name="debug_color" type="Color" setter="set_debug_color" getter="get_debug_color" default="Color(0, 0, 0, 0)">
The collision shape color that is displayed in the editor, or in the running project if [b]Debug &gt; Visible Collision Shapes[/b] is checked at the top of the editor.
[b]Note:[/b] The default value is [member ProjectSettings.debug/shapes/collision/shape_color]. The [code]Color(0, 0, 0, 0)[/code] value documented here is a placeholder, and not the actual default debug color.
</member>
<member name="debug_fill" type="bool" setter="set_enable_debug_fill" getter="get_enable_debug_fill" default="true">
If [code]true[/code], when the shape is displayed, it will show a solid fill color in addition to its wireframe.
</member>
<member name="depth" type="float" setter="set_depth" getter="get_depth" default="1.0">
Length that the resulting collision extends in either direction perpendicular to its 2D polygon.
</member>

6
engine/doc/classes/CollisionShape2D.xml
View file

@ -13,9 +13,9 @@
<link title="2D Kinematic Character Demo">https://godotengine.org/asset-library/asset/2719</link>
</tutorials>
<members>
<member name="debug_color" type="Color" setter="set_debug_color" getter="get_debug_color" default="Color(0, 0, 0, 1)">
The collision shape debug color.
[b]Note:[/b] The default value is [member ProjectSettings.debug/shapes/collision/shape_color]. The [code]Color(0, 0, 0, 1)[/code] value documented here is a placeholder, and not the actual default debug color.
<member name="debug_color" type="Color" setter="set_debug_color" getter="get_debug_color" default="Color(0, 0, 0, 0)">
The collision shape color that is displayed in the editor, or in the running project if [b]Debug &gt; Visible Collision Shapes[/b] is checked at the top of the editor.
[b]Note:[/b] The default value is [member ProjectSettings.debug/shapes/collision/shape_color]. The [code]Color(0, 0, 0, 0)[/code] value documented here is a placeholder, and not the actual default debug color.
</member>
<member name="disabled" type="bool" setter="set_disabled" getter="is_disabled" default="false" keywords="enabled">
A disabled collision shape has no effect in the world. This property should be changed with [method Object.set_deferred].

7
engine/doc/classes/CollisionShape3D.xml
View file

@ -29,6 +29,13 @@
</method>
</methods>
<members>
<member name="debug_color" type="Color" setter="set_debug_color" getter="get_debug_color" default="Color(0, 0, 0, 0)">
The collision shape color that is displayed in the editor, or in the running project if [b]Debug &gt; Visible Collision Shapes[/b] is checked at the top of the editor.
[b]Note:[/b] The default value is [member ProjectSettings.debug/shapes/collision/shape_color]. The [code]Color(0, 0, 0, 0)[/code] value documented here is a placeholder, and not the actual default debug color.
</member>
<member name="debug_fill" type="bool" setter="set_enable_debug_fill" getter="get_enable_debug_fill" default="true">
If [code]true[/code], when the shape is displayed, it will show a solid fill color in addition to its wireframe.
</member>
<member name="disabled" type="bool" setter="set_disabled" getter="is_disabled" default="false" keywords="enabled">
A disabled collision shape has no effect in the world.
</member>

27
engine/doc/classes/Color.xml
View file

@ -19,7 +19,7 @@
<return type="Color" />
<description>
Constructs a default [Color] from opaque black. This is the same as [constant BLACK].
[b]Note:[/b] in C#, constructs an empty color with all of its components set to [code]0.0[/code] (transparent black).
[b]Note:[/b] In C#, this constructs a [Color] with all of its components set to [code]0.0[/code] (transparent black).
</description>
</constructor>
<constructor name="Color">
@ -177,6 +177,22 @@
[/codeblocks]
</description>
</method>
<method name="from_rgba8" qualifiers="static">
<return type="Color" />
<param index="0" name="r8" type="int" />
<param index="1" name="g8" type="int" />
<param index="2" name="b8" type="int" />
<param index="3" name="a8" type="int" default="255" />
<description>
Returns a [Color] constructed from red ([param r8]), green ([param g8]), blue ([param b8]), and optionally alpha ([param a8]) integer channels, each divided by [code]255.0[/code] for their final value.
[codeblock]
var red = Color.from_rgba8(255, 0, 0) # Same as Color(1, 0, 0).
var dark_blue = Color.from_rgba8(0, 0, 51) # Same as Color(0, 0, 0.2).
var my_color = Color.from_rgba8(306, 255, 0, 102) # Same as Color(1.2, 1, 0, 0.4).
[/codeblock]
[b]Note:[/b] Due to the lower precision of [method from_rgba8] compared to the standard [Color] constructor, a color created with [method from_rgba8] will generally not be equal to the same color created with the standard [Color] constructor. Use [method is_equal_approx] for comparisons to avoid issues with floating-point precision error.
</description>
</method>
<method name="from_rgbe9995" qualifiers="static">
<return type="Color" />
<param index="0" name="rgbe" type="int" />
@ -495,6 +511,15 @@
<member name="h" type="float" setter="" getter="" default="0.0">
The HSV hue of this color, on the range 0 to 1.
</member>
<member name="ok_hsl_h" type="float" setter="" getter="" default="0.0">
The OKHSL hue of this color, on the range 0 to 1.
</member>
<member name="ok_hsl_l" type="float" setter="" getter="" default="0.0">
The OKHSL lightness of this color, on the range 0 to 1.
</member>
<member name="ok_hsl_s" type="float" setter="" getter="" default="0.0">
The OKHSL saturation of this color, on the range 0 to 1.
</member>
<member name="r" type="float" setter="" getter="" default="0.0">
The color's red component, typically on the range of 0 to 1.
</member>

16
engine/doc/classes/ColorPalette.xml Normal file
View file

@ -0,0 +1,16 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="ColorPalette" inherits="Resource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
A resource class for managing a palette of colors, which can be loaded and saved using [ColorPicker].
</brief_description>
<description>
The [ColorPalette] resource is designed to store and manage a collection of colors. This resource is useful in scenarios where a predefined set of colors is required, such as for creating themes, designing user interfaces, or managing game assets. The built-in [ColorPicker] control can also make use of [ColorPalette] without additional code.
</description>
<tutorials>
</tutorials>
<members>
<member name="colors" type="PackedColorArray" setter="set_colors" getter="get_colors" default="PackedColorArray()">
A [PackedColorArray] containing the colors in the palette.
</member>
</members>
</class>

9
engine/doc/classes/ColorPicker.xml
View file

@ -168,21 +168,24 @@
<theme_item name="color_hue" data_type="icon" type="Texture2D">
Custom texture for the hue selection slider on the right.
</theme_item>
<theme_item name="color_okhsl_hue" data_type="icon" type="Texture2D">
Custom texture for the H slider in the OKHSL color mode.
</theme_item>
<theme_item name="expanded_arrow" data_type="icon" type="Texture2D">
The icon for color preset drop down menu when expanded.
</theme_item>
<theme_item name="folded_arrow" data_type="icon" type="Texture2D">
The icon for color preset drop down menu when folded.
</theme_item>
<theme_item name="menu_option" data_type="icon" type="Texture2D">
The icon for color preset option menu.
</theme_item>
<theme_item name="overbright_indicator" data_type="icon" type="Texture2D">
The indicator used to signalize that the color value is outside the 0-1 range.
</theme_item>
<theme_item name="picker_cursor" data_type="icon" type="Texture2D">
The image displayed over the color box/circle (depending on the [member picker_shape]), marking the currently selected color.
</theme_item>
<theme_item name="picker_cursor_bg" data_type="icon" type="Texture2D">
The fill image displayed behind the picker cursor.
</theme_item>
<theme_item name="sample_bg" data_type="icon" type="Texture2D">
Background panel for the color preview box (visible when the color is translucent).
</theme_item>

1
engine/doc/classes/Compositor.xml
View file

@ -7,6 +7,7 @@
The compositor resource stores attributes used to customize how a [Viewport] is rendered.
</description>
<tutorials>
<link title="The Compositor">$DOCS_URL/tutorials/rendering/compositor.html</link>
</tutorials>
<members>
<member name="compositor_effects" type="CompositorEffect[]" setter="set_compositor_effects" getter="get_compositor_effects" default="[]">

22
engine/doc/classes/CompositorEffect.xml
View file

@ -7,6 +7,7 @@
This resource defines a custom rendering effect that can be applied to [Viewport]s through the viewports' [Environment]. You can implement a callback that is called during rendering at a given stage of the rendering pipeline and allows you to insert additional passes. Note that this callback happens on the rendering thread. CompositorEffect is an abstract base class and must be extended to implement specific rendering logic.
</description>
<tutorials>
<link title="The Compositor">$DOCS_URL/tutorials/rendering/compositor.html</link>
</tutorials>
<methods>
<method name="_render_callback" qualifiers="virtual">
@ -23,7 +24,7 @@
If [code]true[/code] and MSAA is enabled, this will trigger a color buffer resolve before the effect is run.
[b]Note:[/b] In [method _render_callback], to access the resolved buffer use:
[codeblock]
var render_scene_buffers : RenderSceneBuffersRD = render_data.get_render_scene_buffers()
var render_scene_buffers = render_data.get_render_scene_buffers()
var color_buffer = render_scene_buffers.get_texture("render_buffers", "color")
[/codeblock]
</member>
@ -31,7 +32,7 @@
If [code]true[/code] and MSAA is enabled, this will trigger a depth buffer resolve before the effect is run.
[b]Note:[/b] In [method _render_callback], to access the resolved buffer use:
[codeblock]
var render_scene_buffers : RenderSceneBuffersRD = render_data.get_render_scene_buffers()
var render_scene_buffers = render_data.get_render_scene_buffers()
var depth_buffer = render_scene_buffers.get_texture("render_buffers", "depth")
[/codeblock]
</member>
@ -45,7 +46,7 @@
If [code]true[/code] this triggers motion vectors being calculated during the opaque render state.
[b]Note:[/b] In [method _render_callback], to access the motion vector buffer use:
[codeblock]
var render_scene_buffers : RenderSceneBuffersRD = render_data.get_render_scene_buffers()
var render_scene_buffers = render_data.get_render_scene_buffers()
var motion_buffer = render_scene_buffers.get_velocity_texture()
[/codeblock]
</member>
@ -53,9 +54,20 @@
If [code]true[/code] this triggers normal and roughness data to be output during our depth pre-pass, only applicable for the Forward+ renderer.
[b]Note:[/b] In [method _render_callback], to access the roughness buffer use:
[codeblock]
var render_scene_buffers : RenderSceneBuffersRD = render_data.get_render_scene_buffers()
var render_scene_buffers = render_data.get_render_scene_buffers()
var roughness_buffer = render_scene_buffers.get_texture("forward_clustered", "normal_roughness")
[/codeblock]
The raw normal and roughness buffer is stored in an optimized format, different than the one available in Spatial shaders. When sampling the buffer, a conversion function must be applied. Use this function, copied from [url=https://github.com/godotengine/godot/blob/da5f39889f155658cef7f7ec3cc1abb94e17d815/servers/rendering/renderer_rd/shaders/forward_clustered/scene_forward_clustered_inc.glsl#L334-L341]here[/url]:
[codeblock]
vec4 normal_roughness_compatibility(vec4 p_normal_roughness) {
float roughness = p_normal_roughness.w;
if (roughness &gt; 0.5) {
roughness = 1.0 - roughness;
}
roughness /= (127.0 / 255.0);
return vec4(normalize(p_normal_roughness.xyz * 2.0 - 1.0) * 0.5 + 0.5, roughness);
}
[/codeblock]
</member>
<member name="needs_separate_specular" type="bool" setter="set_needs_separate_specular" getter="get_needs_separate_specular">
If [code]true[/code] this triggers specular data being rendered to a separate buffer and combined after effects have been applied, only applicable for the Forward+ renderer.
@ -75,7 +87,7 @@
The callback is called before our transparent rendering pass, but after our sky is rendered and we've created our back buffers.
</constant>
<constant name="EFFECT_CALLBACK_TYPE_POST_TRANSPARENT" value="4" enum="EffectCallbackType">
The callback is called after our transparent rendering pass, but before any build in post effects and output to our render target.
The callback is called after our transparent rendering pass, but before any built-in post-processing effects and output to our render target.
</constant>
<constant name="EFFECT_CALLBACK_TYPE_MAX" value="5" enum="EffectCallbackType">
Represents the size of the [enum EffectCallbackType] enum.

91
engine/doc/classes/Control.xml
View file

@ -6,13 +6,14 @@
<description>
Base class for all UI-related nodes. [Control] features a bounding rectangle that defines its extents, an anchor position relative to its parent control or the current viewport, and offsets relative to the anchor. The offsets update automatically when the node, any of its parents, or the screen size change.
For more information on Godot's UI system, anchors, offsets, and containers, see the related tutorials in the manual. To build flexible UIs, you'll need a mix of UI elements that inherit from [Control] and [Container] nodes.
[b]Note:[/b] Since both [Node2D] and [Control] inherit from [CanvasItem], they share several concepts from the class such as the [member CanvasItem.z_index] and [member CanvasItem.visible] properties.
[b]User Interface nodes and input[/b]
Godot propagates input events via viewports. Each [Viewport] is responsible for propagating [InputEvent]s to their child nodes. As the [member SceneTree.root] is a [Window], this already happens automatically for all UI elements in your game.
Input events are propagated through the [SceneTree] from the root node to all child nodes by calling [method Node._input]. For UI elements specifically, it makes more sense to override the virtual method [method _gui_input], which filters out unrelated input events, such as by checking z-order, [member mouse_filter], focus, or if the event was inside of the control's bounding box.
Call [method accept_event] so no other node receives the event. Once you accept an input, it becomes handled so [method Node._unhandled_input] will not process it.
Only one [Control] node can be in focus. Only the node in focus will receive events. To get the focus, call [method grab_focus]. [Control] nodes lose focus when another node grabs it, or if you hide the node in focus.
Sets [member mouse_filter] to [constant MOUSE_FILTER_IGNORE] to tell a [Control] node to ignore mouse or touch events. You'll need it if you place an icon on top of a button.
[Theme] resources change the Control's appearance. If you change the [Theme] on a [Control] node, it affects all of its children. To override some of the theme's parameters, call one of the [code]add_theme_*_override[/code] methods, like [method add_theme_font_override]. You can override the theme with the Inspector.
[Theme] resources change the control's appearance. The [member theme] of a [Control] node affects all of its direct and indirect children (as long as a chain of controls is uninterrupted). To override some of the theme items, call one of the [code]add_theme_*_override[/code] methods, like [method add_theme_font_override]. You can also override theme items in the Inspector.
[b]Note:[/b] Theme items are [i]not[/i] [Object] properties. This means you can't access their values using [method Object.get] and [method Object.set]. Instead, use the [code]get_theme_*[/code] and [code]add_theme_*_override[/code] methods provided by this class.
</description>
<tutorials>
@ -65,7 +66,7 @@
[csharp]
public override bool _CanDropData(Vector2 atPosition, Variant data)
{
return data.VariantType == Variant.Type.Dictionary &amp;&amp; dict.AsGodotDictionary().ContainsKey("color");
return data.VariantType == Variant.Type.Dictionary &amp;&amp; data.AsGodotDictionary().ContainsKey("color");
}
public override void _DropData(Vector2 atPosition, Variant data)
@ -113,15 +114,15 @@
<param index="0" name="at_position" type="Vector2" />
<description>
Virtual method to be implemented by the user. Returns the tooltip text for the position [param at_position] in control's local coordinates, which will typically appear when the cursor is resting over this control. See [method get_tooltip].
[b]Note:[/b] If this method returns an empty [String], no tooltip is displayed.
[b]Note:[/b] If this method returns an empty [String] and [method _make_custom_tooltip] is not overridden, no tooltip is displayed.
</description>
</method>
<method name="_gui_input" qualifiers="virtual">
<return type="void" />
<param index="0" name="event" type="InputEvent" />
<description>
Virtual method to be implemented by the user. Use this method to process and accept inputs on UI elements. See [method accept_event].
[b]Example usage for clicking a control:[/b]
Virtual method to be implemented by the user. Override this method to handle and accept inputs on UI elements. See also [method accept_event].
[b]Example:[/b] Click on the control to print a message:
[codeblocks]
[gdscript]
func _gui_input(event):
@ -142,13 +143,13 @@
}
[/csharp]
[/codeblocks]
The event won't trigger if:
* clicking outside the control (see [method _has_point]);
* control has [member mouse_filter] set to [constant MOUSE_FILTER_IGNORE];
* control is obstructed by another [Control] on top of it, which doesn't have [member mouse_filter] set to [constant MOUSE_FILTER_IGNORE];
* control's parent has [member mouse_filter] set to [constant MOUSE_FILTER_STOP] or has accepted the event;
* it happens outside the parent's rectangle and the parent has either [member clip_contents] enabled.
[b]Note:[/b] Event position is relative to the control origin.
If the [param event] inherits [InputEventMouse], this method will [b]not[/b] be called when:
- the control's [member mouse_filter] is set to [constant MOUSE_FILTER_IGNORE];
- the control is obstructed by another control on top, that doesn't have [member mouse_filter] set to [constant MOUSE_FILTER_IGNORE];
- the control's parent has [member mouse_filter] set to [constant MOUSE_FILTER_STOP] or has accepted the event;
- the control's parent has [member clip_contents] enabled and the [param event]'s position is outside the parent's rectangle;
- the [param event]'s position is outside the control (see [method _has_point]).
[b]Note:[/b] The [param event]'s position is relative to this control's origin.
</description>
</method>
<method name="_has_point" qualifiers="virtual const">
@ -164,12 +165,13 @@
<return type="Object" />
<param index="0" name="for_text" type="String" />
<description>
Virtual method to be implemented by the user. Returns a [Control] node that should be used as a tooltip instead of the default one. The [param for_text] includes the contents of the [member tooltip_text] property.
Virtual method to be implemented by the user. Returns a [Control] node that should be used as a tooltip instead of the default one. [param for_text] is the return value of [method get_tooltip].
The returned node must be of type [Control] or Control-derived. It can have child nodes of any type. It is freed when the tooltip disappears, so make sure you always provide a new instance (if you want to use a pre-existing node from your scene tree, you can duplicate it and pass the duplicated instance). When [code]null[/code] or a non-Control node is returned, the default tooltip will be used instead.
The returned node will be added as child to a [PopupPanel], so you should only provide the contents of that panel. That [PopupPanel] can be themed using [method Theme.set_stylebox] for the type [code]"TooltipPanel"[/code] (see [member tooltip_text] for an example).
[b]Note:[/b] The tooltip is shrunk to minimal size. If you want to ensure it's fully visible, you might want to set its [member custom_minimum_size] to some non-zero value.
[b]Note:[/b] The node (and any relevant children) should be [member CanvasItem.visible] when returned, otherwise, the viewport that instantiates it will not be able to calculate its minimum size reliably.
[b]Example of usage with a custom-constructed node:[/b]
[b]Note:[/b] The node (and any relevant children) should have their [member CanvasItem.visible] set to [code]true[/code] when returned, otherwise, the viewport that instantiates it will not be able to calculate its minimum size reliably.
[b]Note:[/b] If overridden, this method is called even if [method get_tooltip] returns an empty string. When this happens with the default tooltip, it is not displayed. To copy this behavior, return [code]null[/code] in this method when [param for_text] is empty.
[b]Example:[/b] Use a constructed node as a tooltip:
[codeblocks]
[gdscript]
func _make_custom_tooltip(for_text):
@ -186,7 +188,7 @@
}
[/csharp]
[/codeblocks]
[b]Example of usage with a custom scene instance:[/b]
[b]Example:[/b] Usa a scene instance as a tooltip:
[codeblocks]
[gdscript]
func _make_custom_tooltip(for_text):
@ -228,7 +230,7 @@
<description>
Creates a local override for a theme [Color] with the specified [param name]. Local overrides always take precedence when fetching theme items for the control. An override can be removed with [method remove_theme_color_override].
See also [method get_theme_color].
[b]Example of overriding a label's color and resetting it later:[/b]
[b]Example:[/b] Override a [Label]'s color and reset it later:
[codeblocks]
[gdscript]
# Given the child Label node "MyLabel", override its font color with a custom value.
@ -292,10 +294,10 @@
<description>
Creates a local override for a theme [StyleBox] with the specified [param name]. Local overrides always take precedence when fetching theme items for the control. An override can be removed with [method remove_theme_stylebox_override].
See also [method get_theme_stylebox].
[b]Example of modifying a property in a StyleBox by duplicating it:[/b]
[b]Example:[/b] Modify a property in a [StyleBox] by duplicating it:
[codeblocks]
[gdscript]
# The snippet below assumes the child node MyButton has a StyleBoxFlat assigned.
# The snippet below assumes the child node "MyButton" has a StyleBoxFlat assigned.
# Resources are shared across instances, so we need to duplicate it
# to avoid modifying the appearance of all other buttons.
var new_stylebox_normal = $MyButton.get_theme_stylebox("normal").duplicate()
@ -306,7 +308,7 @@
$MyButton.remove_theme_stylebox_override("normal")
[/gdscript]
[csharp]
// The snippet below assumes the child node MyButton has a StyleBoxFlat assigned.
// The snippet below assumes the child node "MyButton" has a StyleBoxFlat assigned.
// Resources are shared across instances, so we need to duplicate it
// to avoid modifying the appearance of all other buttons.
StyleBoxFlat newStyleboxNormal = GetNode&lt;Button&gt;("MyButton").GetThemeStylebox("normal").Duplicate() as StyleBoxFlat;
@ -446,7 +448,7 @@
<description>
Returns the position of this [Control] in global screen coordinates (i.e. taking window position into account). Mostly useful for editor plugins.
Equals to [member global_position] if the window is embedded (see [member Viewport.gui_embed_subwindows]).
[b]Example usage for showing a popup:[/b]
[b]Example:[/b] Show a popup at the mouse position:
[codeblock]
popup_menu.position = get_screen_position() + get_local_mouse_position()
popup_menu.reset_size()
@ -553,13 +555,13 @@
<description>
Returns the tooltip text for the position [param at_position] in control's local coordinates, which will typically appear when the cursor is resting over this control. By default, it returns [member tooltip_text].
This method can be overridden to customize its behavior. See [method _get_tooltip].
[b]Note:[/b] If this method returns an empty [String], no tooltip is displayed.
[b]Note:[/b] If this method returns an empty [String] and [method _make_custom_tooltip] is not overridden, no tooltip is displayed.
</description>
</method>
<method name="grab_click_focus">
<return type="void" />
<description>
Creates an [InputEventMouseButton] that attempts to click the control. If the event is received, the control acquires focus.
Creates an [InputEventMouseButton] that attempts to click the control. If the event is received, the control gains focus.
[codeblocks]
[gdscript]
func _process(delta):
@ -699,7 +701,7 @@
<method name="is_layout_rtl" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if layout is right-to-left.
Returns [code]true[/code] if layout is right-to-left. See also [member layout_direction].
</description>
</method>
<method name="release_focus">
@ -809,9 +811,11 @@
<param index="1" name="can_drop_func" type="Callable" />
<param index="2" name="drop_func" type="Callable" />
<description>
Forwards the handling of this control's [method _get_drag_data], [method _can_drop_data] and [method _drop_data] virtual functions to delegate callables.
For each argument, if not empty, the delegate callable is used, otherwise the local (virtual) function is used.
The function format for each callable should be exactly the same as the virtual functions described above.
Sets the given callables to be used instead of the control's own drag-and-drop virtual methods. If a callable is empty, its respective virtual method is used as normal.
The arguments for each callable should be exactly the same as their respective virtual methods, which would be:
- [param drag_func] corresponds to [method _get_drag_data] and requires a [Vector2];
- [param can_drop_func] corresponds to [method _can_drop_data] and requires both a [Vector2] and a [Variant];
- [param drop_func] corresponds to [method _drop_data] and requires both a [Vector2] and a [Variant].
</description>
</method>
<method name="set_drag_preview">
@ -979,7 +983,7 @@
Controls the direction on the vertical axis in which the control should grow if its vertical minimum size is changed to be greater than its current size, as the control always has to be at least the minimum size.
</member>
<member name="layout_direction" type="int" setter="set_layout_direction" getter="get_layout_direction" enum="Control.LayoutDirection" default="0">
Controls layout direction and text writing direction. Right-to-left layouts are necessary for certain languages (e.g. Arabic and Hebrew).
Controls layout direction and text writing direction. Right-to-left layouts are necessary for certain languages (e.g. Arabic and Hebrew). See also [method is_layout_rtl].
</member>
<member name="localize_numeral_system" type="bool" setter="set_localize_numeral_system" getter="is_localizing_numeral_system" default="true">
If [code]true[/code], automatically converts code line numbers, list indices, [SpinBox] and [ProgressBar] values from the Western Arabic (0..9) to the numeral systems used in current locale.
@ -993,8 +997,9 @@
Controls whether the control will be able to receive mouse button input events through [method _gui_input] and how these events should be handled. Also controls whether the control can receive the [signal mouse_entered], and [signal mouse_exited] signals. See the constants to learn what each does.
</member>
<member name="mouse_force_pass_scroll_events" type="bool" setter="set_force_pass_scroll_events" getter="is_force_pass_scroll_events" default="true">
When enabled, scroll wheel events processed by [method _gui_input] will be passed to the parent control even if [member mouse_filter] is set to [constant MOUSE_FILTER_STOP]. As it defaults to true, this allows nested scrollable containers to work out of the box.
When enabled, scroll wheel events processed by [method _gui_input] will be passed to the parent control even if [member mouse_filter] is set to [constant MOUSE_FILTER_STOP].
You should disable it on the root of your UI if you do not want scroll events to go to the [method Node._unhandled_input] processing.
[b]Note:[/b] Because this property defaults to [code]true[/code], this allows nested scrollable containers to work out of the box.
</member>
<member name="offset_bottom" type="float" setter="set_offset" getter="get_offset" default="0.0">
Distance between the node's bottom edge and its parent control, based on [member anchor_bottom].
@ -1057,8 +1062,13 @@
[b]Note:[/b] To look up [Control]'s own items use various [code]get_theme_*[/code] methods without specifying [code]theme_type[/code].
[b]Note:[/b] Theme items are looked for in the tree order, from branch to root, where each [Control] node is checked for its [member theme] property. The earliest match against any type/class name is returned. The project-level Theme and the default Theme are checked last.
</member>
<member name="tooltip_auto_translate_mode" type="int" setter="set_tooltip_auto_translate_mode" getter="get_tooltip_auto_translate_mode" enum="Node.AutoTranslateMode" default="0">
Defines if tooltip text should automatically change to its translated version depending on the current locale. Uses the same auto translate mode as this control when set to [constant Node.AUTO_TRANSLATE_MODE_INHERIT].
[b]Note:[/b] Tooltips customized using [method _make_custom_tooltip] do not use this auto translate mode automatically.
</member>
<member name="tooltip_text" type="String" setter="set_tooltip_text" getter="get_tooltip_text" default="&quot;&quot;">
The default tooltip text. The tooltip appears when the user's mouse cursor stays idle over this control for a few moments, provided that the [member mouse_filter] property is not [constant MOUSE_FILTER_IGNORE]. The time required for the tooltip to appear can be changed with the [member ProjectSettings.gui/timers/tooltip_delay_sec] option. See also [method get_tooltip].
The default tooltip text. The tooltip appears when the user's mouse cursor stays idle over this control for a few moments, provided that the [member mouse_filter] property is not [constant MOUSE_FILTER_IGNORE]. The time required for the tooltip to appear can be changed with the [member ProjectSettings.gui/timers/tooltip_delay_sec] setting.
This string is the default return value of [method get_tooltip]. Override [method _get_tooltip] to generate tooltip text dynamically. Override [method _make_custom_tooltip] to customize the tooltip interface and behavior.
The tooltip popup will use either a default implementation, or a custom one that you can provide by overriding [method _make_custom_tooltip]. The default tooltip includes a [PopupPanel] and [Label] whose theme properties can be customized using [Theme] methods with the [code]"TooltipPanel"[/code] and [code]"TooltipLabel"[/code] respectively. For example:
[codeblocks]
[gdscript]
@ -1200,7 +1210,7 @@
[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.
Sent when the control layout direction is changed from LTR or RTL or vice versa. This notification is propagated to child Control nodes as result of a change to [member layout_direction].
</constant>
<constant name="CURSOR_ARROW" value="0" enum="CursorShape">
Show the system's arrow mouse cursor when the user hovers the node. Use with [member mouse_default_cursor_shape].
@ -1333,13 +1343,14 @@
Tells the parent [Container] to align the node with its end, either the bottom or the right edge. It is mutually exclusive with [constant SIZE_FILL] and other shrink size flags, but can be used with [constant SIZE_EXPAND] in some containers. Use with [member size_flags_horizontal] and [member size_flags_vertical].
</constant>
<constant name="MOUSE_FILTER_STOP" value="0" enum="MouseFilter">
The control will receive mouse movement input events and mouse button input events if clicked on through [method _gui_input]. And the control will receive the [signal mouse_entered] and [signal mouse_exited] signals. These events are automatically marked as handled, and they will not propagate further to other controls. This also results in blocking signals in other controls.
The control will receive mouse movement input events and mouse button input events if clicked on through [method _gui_input]. The control will also receive the [signal mouse_entered] and [signal mouse_exited] signals. These events are automatically marked as handled, and they will not propagate further to other controls. This also results in blocking signals in other controls.
</constant>
<constant name="MOUSE_FILTER_PASS" value="1" enum="MouseFilter">
The control will receive mouse movement input events and mouse button input events if clicked on through [method _gui_input]. And the control will receive the [signal mouse_entered] and [signal mouse_exited] signals. If this control does not handle the event, the parent control (if any) will be considered, and so on until there is no more parent control to potentially handle it. This also allows signals to fire in other controls. If no control handled it, the event will be passed to [method Node._shortcut_input] for further processing.
The control will receive mouse movement input events and mouse button input events if clicked on through [method _gui_input]. The control will also receive the [signal mouse_entered] and [signal mouse_exited] signals.
If this control does not handle the event, the event will propagate up to its parent control if it has one. The event is bubbled up the node hierarchy until it reaches a non-[CanvasItem], a control with [constant MOUSE_FILTER_STOP], or a [CanvasItem] with [member CanvasItem.top_level] enabled. This will allow signals to fire in all controls it reaches. If no control handled it, the event will be passed to [method Node._shortcut_input] for further processing.
</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.
The control will not receive any mouse movement input events nor mouse button input events 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. If a child has [constant MOUSE_FILTER_PASS] and an event was passed to this control, the event will further propagate up to the control's parent.
[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">
@ -1360,8 +1371,8 @@
<constant name="LAYOUT_DIRECTION_INHERITED" value="0" enum="LayoutDirection">
Automatic layout direction, determined from the parent control layout direction.
</constant>
<constant name="LAYOUT_DIRECTION_LOCALE" value="1" enum="LayoutDirection">
Automatic layout direction, determined from the current locale.
<constant name="LAYOUT_DIRECTION_APPLICATION_LOCALE" value="1" enum="LayoutDirection">
Automatic layout direction, determined from the current locale. Right-to-left layout direction is automatically used for languages that require it such as Arabic and Hebrew, but only if a valid translation file is loaded for the given language (unless said language is configured as a fallback in [member ProjectSettings.internationalization/locale/fallback]). For all other languages (or if no valid translation file is found by Godot), left-to-right layout direction is used. If using [TextServerFallback] ([member ProjectSettings.internationalization/rendering/text_driver]), left-to-right layout direction is always used regardless of the language. Right-to-left layout direction can also be forced using [member ProjectSettings.internationalization/rendering/force_right_to_left_layout_direction].
</constant>
<constant name="LAYOUT_DIRECTION_LTR" value="2" enum="LayoutDirection">
Left-to-right layout direction.
@ -1369,6 +1380,14 @@
<constant name="LAYOUT_DIRECTION_RTL" value="3" enum="LayoutDirection">
Right-to-left layout direction.
</constant>
<constant name="LAYOUT_DIRECTION_SYSTEM_LOCALE" value="4" enum="LayoutDirection">
Automatic layout direction, determined from the system locale. Right-to-left layout direction is automatically used for languages that require it such as Arabic and Hebrew, but only if a valid translation file is loaded for the given language.. For all other languages (or if no valid translation file is found by Godot), left-to-right layout direction is used. If using [TextServerFallback] ([member ProjectSettings.internationalization/rendering/text_driver]), left-to-right layout direction is always used regardless of the language.
</constant>
<constant name="LAYOUT_DIRECTION_MAX" value="5" enum="LayoutDirection">
Represents the size of the [enum LayoutDirection] enum.
</constant>
<constant name="LAYOUT_DIRECTION_LOCALE" value="1" enum="LayoutDirection" deprecated="Use [constant LAYOUT_DIRECTION_APPLICATION_LOCALE] instead.">
</constant>
<constant name="TEXT_DIRECTION_INHERITED" value="3" enum="TextDirection">
Text writing direction is the same as layout direction.
</constant>

23
engine/doc/classes/Cubemap.xml
View file

@ -6,8 +6,27 @@
<description>
A cubemap is made of 6 textures organized in layers. They are typically used for faking reflections in 3D rendering (see [ReflectionProbe]). It can be used to make an object look as if it's reflecting its surroundings. This usually delivers much better performance than other reflection methods.
This resource is typically used as a uniform in custom shaders. Few core Godot methods make use of [Cubemap] resources.
To create such a texture file yourself, reimport your image files using the Godot Editor import presets.
[b]Note:[/b] Godot doesn't support using cubemaps in a [PanoramaSkyMaterial]. You can use [url=https://danilw.github.io/GLSL-howto/cubemap_to_panorama_js/cubemap_to_panorama.html]this tool[/url] to convert a cubemap to an equirectangular sky map.
To create such a texture file yourself, reimport your image files using the Godot Editor import presets. The expected image order is X+, X-, Y+, Y-, Z+, Z- (in Godot's coordinate system, so Y+ is "up" and Z- is "forward"). You can use one of the following templates as a base:
- [url=https://raw.githubusercontent.com/godotengine/godot-docs/master/tutorials/assets_pipeline/img/cubemap_template_2x3.webp]2×3 cubemap template (default layout option)[/url]
- [url=https://raw.githubusercontent.com/godotengine/godot-docs/master/tutorials/assets_pipeline/img/cubemap_template_3x2.webp]3×2 cubemap template[/url]
- [url=https://raw.githubusercontent.com/godotengine/godot-docs/master/tutorials/assets_pipeline/img/cubemap_template_1x6.webp]1×6 cubemap template[/url]
- [url=https://raw.githubusercontent.com/godotengine/godot-docs/master/tutorials/assets_pipeline/img/cubemap_template_6x1.webp]6×1 cubemap template[/url]
[b]Note:[/b] Godot doesn't support using cubemaps in a [PanoramaSkyMaterial]. To use a cubemap as a skybox, convert the default [PanoramaSkyMaterial] to a [ShaderMaterial] using the [b]Convert to ShaderMaterial[/b] resource dropdown option, then replace its code with the following:
[codeblock lang=text]
shader_type sky;
uniform samplerCube source_panorama : filter_linear, source_color, hint_default_black;
uniform float exposure : hint_range(0, 128) = 1.0;
void sky() {
// If importing a cubemap from another engine, you may need to flip one of the `EYEDIR` components below
// by replacing it with `-EYEDIR`.
vec3 eyedir = vec3(EYEDIR.x, EYEDIR.y, EYEDIR.z);
COLOR = texture(source_panorama, eyedir).rgb * exposure;
}
[/codeblock]
After replacing the shader code and saving, specify the imported Cubemap resource in the Shader Parameters section of the ShaderMaterial in the inspector.
Alternatively, you can use [url=https://danilw.github.io/GLSL-howto/cubemap_to_panorama_js/cubemap_to_panorama.html]this tool[/url] to convert a cubemap to an equirectangular sky map and use [PanoramaSkyMaterial] as usual.
</description>
<tutorials>
</tutorials>

2
engine/doc/classes/CubemapArray.xml
View file

@ -7,7 +7,7 @@
[CubemapArray]s are made of an array of [Cubemap]s. Like [Cubemap]s, they are made of multiple textures, the amount of which must be divisible by 6 (one for each face of the cube).
The primary benefit of [CubemapArray]s is that they can be accessed in shader code using a single texture reference. In other words, you can pass multiple [Cubemap]s into a shader using a single [CubemapArray]. [Cubemap]s are allocated in adjacent cache regions on the GPU, which makes [CubemapArray]s the most efficient way to store multiple [Cubemap]s.
[b]Note:[/b] Godot uses [CubemapArray]s internally for many effects, including the [Sky] if you set [member ProjectSettings.rendering/reflections/sky_reflections/texture_array_reflections] to [code]true[/code]. To create such a texture file yourself, reimport your image files using the import presets of the File System dock.
[b]Note:[/b] [CubemapArray] is not supported in the OpenGL 3 rendering backend.
[b]Note:[/b] [CubemapArray] is not supported in the Compatibility renderer.
</description>
<tutorials>
</tutorials>

31
engine/doc/classes/Curve.xml
View file

@ -4,8 +4,8 @@
A mathematical curve.
</brief_description>
<description>
This resource describes a mathematical curve by defining a set of points and tangents at each point. By default, it ranges between [code]0[/code] and [code]1[/code] on the Y axis and positions points relative to the [code]0.5[/code] Y position.
See also [Gradient] which is designed for color interpolation. See also [Curve2D] and [Curve3D].
This resource describes a mathematical curve by defining a set of points and tangents at each point. By default, it ranges between [code]0[/code] and [code]1[/code] on the X and Y axes, but these ranges can be changed.
Please note that many resources and nodes assume they are given [i]unit curves[/i]. A unit curve is a curve whose domain (the X axis) is between [code]0[/code] and [code]1[/code]. Some examples of unit curve usage are [member CPUParticles2D.angle_curve] and [member Line2D.width_curve].
</description>
<tutorials>
</tutorials>
@ -39,6 +39,12 @@
Removes all points from the curve.
</description>
</method>
<method name="get_domain_range" qualifiers="const">
<return type="float" />
<description>
Returns the difference between [member min_domain] and [member max_domain].
</description>
</method>
<method name="get_point_left_mode" qualifiers="const">
<return type="int" enum="Curve.TangentMode" />
<param index="0" name="index" type="int" />
@ -74,6 +80,12 @@
Returns the right tangent angle (in degrees) for the point at [param index].
</description>
</method>
<method name="get_value_range" qualifiers="const">
<return type="float" />
<description>
Returns the difference between [member min_value] and [member max_value].
</description>
</method>
<method name="remove_point">
<return type="void" />
<param index="0" name="index" type="int" />
@ -148,17 +160,28 @@
<member name="bake_resolution" type="int" setter="set_bake_resolution" getter="get_bake_resolution" default="100">
The number of points to include in the baked (i.e. cached) curve data.
</member>
<member name="max_domain" type="float" setter="set_max_domain" getter="get_max_domain" default="1.0">
The maximum domain (x-coordinate) that points can have.
</member>
<member name="max_value" type="float" setter="set_max_value" getter="get_max_value" default="1.0">
The maximum value the curve can reach.
The maximum value (y-coordinate) that points can have. Tangents can cause higher values between points.
</member>
<member name="min_domain" type="float" setter="set_min_domain" getter="get_min_domain" default="0.0">
The minimum domain (x-coordinate) that points can have.
</member>
<member name="min_value" type="float" setter="set_min_value" getter="get_min_value" default="0.0">
The minimum value the curve can reach.
The minimum value (y-coordinate) that points can have. Tangents can cause lower values between points.
</member>
<member name="point_count" type="int" setter="set_point_count" getter="get_point_count" default="0">
The number of points describing the curve.
</member>
</members>
<signals>
<signal name="domain_changed">
<description>
Emitted when [member max_domain] or [member min_domain] is changed.
</description>
</signal>
<signal name="range_changed">
<description>
Emitted when [member max_value] or [member min_value] is changed.

2
engine/doc/classes/Curve2D.xml
View file

@ -88,7 +88,7 @@
<param index="0" name="idx" type="int" />
<param index="1" name="t" type="float" />
<description>
Returns the position between the vertex [param idx] and the vertex [code]idx + 1[/code], where [param t] controls if the point is the first vertex ([code]t = 0.0[/code]), the last vertex ([code]t = 1.0[/code]), or in between. Values of [param t] outside the range ([code]0.0 &gt;= t &lt;=1[/code]) give strange, but predictable results.
Returns the position between the vertex [param idx] and the vertex [code]idx + 1[/code], where [param t] controls if the point is the first vertex ([code]t = 0.0[/code]), the last vertex ([code]t = 1.0[/code]), or in between. Values of [param t] outside the range ([code]0.0 &lt;= t &lt;= 1.0[/code]) give strange, but predictable results.
If [param idx] is out of bounds it is truncated to the first or last vertex, and [param t] is ignored. If the curve has no points, the function sends an error to the console, and returns [code](0, 0)[/code].
</description>
</method>

3
engine/doc/classes/Curve3D.xml
View file

@ -204,6 +204,9 @@
<member name="bake_interval" type="float" setter="set_bake_interval" getter="get_bake_interval" default="0.2">
The distance in meters between two adjacent cached points. Changing it forces the cache to be recomputed the next time the [method get_baked_points] or [method get_baked_length] function is called. The smaller the distance, the more points in the cache and the more memory it will consume, so use with care.
</member>
<member name="closed" type="bool" setter="set_closed" getter="is_closed" default="false">
If [code]true[/code], and the curve has more than 2 control points, the last point and the first one will be connected in a loop.
</member>
<member name="point_count" type="int" setter="set_point_count" getter="get_point_count" default="0">
The number of points describing the curve.
</member>

4
engine/doc/classes/CurveTexture.xml
View file

@ -4,14 +4,14 @@
A 1D texture where pixel brightness corresponds to points on a curve.
</brief_description>
<description>
A 1D texture where pixel brightness corresponds to points on a [Curve] resource, either in grayscale or in red. This visual representation simplifies the task of saving curves as image files.
A 1D texture where pixel brightness corresponds to points on a unit [Curve] resource, either in grayscale or in red. This visual representation simplifies the task of saving curves as image files.
If you need to store up to 3 curves within a single texture, use [CurveXYZTexture] instead. See also [GradientTexture1D] and [GradientTexture2D].
</description>
<tutorials>
</tutorials>
<members>
<member name="curve" type="Curve" setter="set_curve" getter="get_curve">
The [Curve] that is rendered onto the texture.
The [Curve] that is rendered onto the texture. Should be a unit [Curve].
</member>
<member name="resource_local_to_scene" type="bool" setter="set_local_to_scene" getter="is_local_to_scene" overrides="Resource" default="false" />
<member name="texture_mode" type="int" setter="set_texture_mode" getter="get_texture_mode" enum="CurveTexture.TextureMode" default="0">

8
engine/doc/classes/CurveXYZTexture.xml
View file

@ -4,20 +4,20 @@
A 1D texture where the red, green, and blue color channels correspond to points on 3 curves.
</brief_description>
<description>
A 1D texture where the red, green, and blue color channels correspond to points on 3 [Curve] resources. Compared to using separate [CurveTexture]s, this further simplifies the task of saving curves as image files.
A 1D texture where the red, green, and blue color channels correspond to points on 3 unit [Curve] resources. Compared to using separate [CurveTexture]s, this further simplifies the task of saving curves as image files.
If you only need to store one curve within a single texture, use [CurveTexture] instead. See also [GradientTexture1D] and [GradientTexture2D].
</description>
<tutorials>
</tutorials>
<members>
<member name="curve_x" type="Curve" setter="set_curve_x" getter="get_curve_x">
The [Curve] that is rendered onto the texture's red channel.
The [Curve] that is rendered onto the texture's red channel. Should be a unit [Curve].
</member>
<member name="curve_y" type="Curve" setter="set_curve_y" getter="get_curve_y">
The [Curve] that is rendered onto the texture's green channel.
The [Curve] that is rendered onto the texture's green channel. Should be a unit [Curve].
</member>
<member name="curve_z" type="Curve" setter="set_curve_z" getter="get_curve_z">
The [Curve] that is rendered onto the texture's blue channel.
The [Curve] that is rendered onto the texture's blue channel. Should be a unit [Curve].
</member>
<member name="resource_local_to_scene" type="bool" setter="set_local_to_scene" getter="is_local_to_scene" overrides="Resource" default="false" />
<member name="width" type="int" setter="set_width" getter="get_width" default="256">

20
engine/doc/classes/DTLSServer.xml
View file

@ -11,20 +11,20 @@
# server_node.gd
extends Node
var dtls := DTLSServer.new()
var server := UDPServer.new()
var dtls = DTLSServer.new()
var server = UDPServer.new()
var peers = []
func _ready():
server.listen(4242)
var key = load("key.key") # Your private key.
var cert = load("cert.crt") # Your X509 certificate.
dtls.setup(key, cert)
dtls.setup(TlsOptions.server(key, cert))
func _process(delta):
while server.is_connection_available():
var peer: PacketPeerUDP = server.take_connection()
var dtls_peer: PacketPeerDTLS = dtls.take_connection(peer)
var peer = server.take_connection()
var dtls_peer = dtls.take_connection(peer)
if dtls_peer.get_status() != PacketPeerDTLS.STATUS_HANDSHAKING:
continue # It is normal that 50% of the connections fails due to cookie exchange.
print("Peer connected!")
@ -45,19 +45,19 @@
{
private DtlsServer _dtls = new DtlsServer();
private UdpServer _server = new UdpServer();
private Godot.Collections.Array&lt;PacketPeerDtls&gt; _peers = new Godot.Collections.Array&lt;PacketPeerDtls&gt;();
private Godot.Collections.Array&lt;PacketPeerDtls&gt; _peers = [];
public override void _Ready()
{
_server.Listen(4242);
var key = GD.Load&lt;CryptoKey&gt;("key.key"); // Your private key.
var cert = GD.Load&lt;X509Certificate&gt;("cert.crt"); // Your X509 certificate.
_dtls.Setup(key, cert);
_dtls.Setup(TlsOptions.Server(key, cert));
}
public override void _Process(double delta)
{
while (Server.IsConnectionAvailable())
while (_server.IsConnectionAvailable())
{
PacketPeerUdp peer = _server.TakeConnection();
PacketPeerDtls dtlsPeer = _dtls.TakeConnection(peer);
@ -90,8 +90,8 @@
# client_node.gd
extends Node
var dtls := PacketPeerDTLS.new()
var udp := PacketPeerUDP.new()
var dtls = PacketPeerDTLS.new()
var udp = PacketPeerUDP.new()
var connected = false
func _ready():

117
engine/doc/classes/Dictionary.xml
View file

@ -148,6 +148,19 @@
Constructs an empty [Dictionary].
</description>
</constructor>
<constructor name="Dictionary">
<return type="Dictionary" />
<param index="0" name="base" type="Dictionary" />
<param index="1" name="key_type" type="int" />
<param index="2" name="key_class_name" type="StringName" />
<param index="3" name="key_script" type="Variant" />
<param index="4" name="value_type" type="int" />
<param index="5" name="value_class_name" type="StringName" />
<param index="6" name="value_script" type="Variant" />
<description>
Creates a typed dictionary from the [param base] dictionary. A typed dictionary can only contain keys and values of the given types, or that inherit from the given classes, as described by this constructor's parameters.
</description>
</constructor>
<constructor name="Dictionary">
<return type="Dictionary" />
<param index="0" name="from" type="Dictionary" />
@ -157,6 +170,13 @@
</constructor>
</constructors>
<methods>
<method name="assign">
<return type="void" />
<param index="0" name="dictionary" type="Dictionary" />
<description>
Assigns elements of another [param dictionary] into the dictionary. Resizes the dictionary to match [param dictionary]. Performs type conversions if the dictionary is typed.
</description>
</method>
<method name="clear">
<return type="void" />
<description>
@ -202,6 +222,42 @@
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="get_typed_key_builtin" qualifiers="const">
<return type="int" />
<description>
Returns the built-in [Variant] type of the typed dictionary's keys as a [enum Variant.Type] constant. If the keys are not typed, returns [constant TYPE_NIL]. See also [method is_typed_key].
</description>
</method>
<method name="get_typed_key_class_name" qualifiers="const">
<return type="StringName" />
<description>
Returns the [b]built-in[/b] class name of the typed dictionary's keys, if the built-in [Variant] type is [constant TYPE_OBJECT]. Otherwise, returns an empty [StringName]. See also [method is_typed_key] and [method Object.get_class].
</description>
</method>
<method name="get_typed_key_script" qualifiers="const">
<return type="Variant" />
<description>
Returns the [Script] instance associated with this typed dictionary's keys, or [code]null[/code] if it does not exist. See also [method is_typed_key].
</description>
</method>
<method name="get_typed_value_builtin" qualifiers="const">
<return type="int" />
<description>
Returns the built-in [Variant] type of the typed dictionary's values as a [enum Variant.Type] constant. If the values are not typed, returns [constant TYPE_NIL]. See also [method is_typed_value].
</description>
</method>
<method name="get_typed_value_class_name" qualifiers="const">
<return type="StringName" />
<description>
Returns the [b]built-in[/b] class name of the typed dictionary's values, if the built-in [Variant] type is [constant TYPE_OBJECT]. Otherwise, returns an empty [StringName]. See also [method is_typed_value] and [method Object.get_class].
</description>
</method>
<method name="get_typed_value_script" qualifiers="const">
<return type="Variant" />
<description>
Returns the [Script] instance associated with this typed dictionary's values, or [code]null[/code] if it does not exist. See also [method is_typed_value].
</description>
</method>
<method name="has" qualifiers="const">
<return type="bool" />
<param index="0" name="key" type="Variant" />
@ -225,9 +281,9 @@
{ 210, default },
};
GD.Print(myDict.ContainsKey("Godot")); // Prints true
GD.Print(myDict.ContainsKey(210)); // Prints true
GD.Print(myDict.ContainsKey(4)); // Prints false
GD.Print(myDict.ContainsKey("Godot")); // Prints True
GD.Print(myDict.ContainsKey(210)); // Prints True
GD.Print(myDict.ContainsKey(4)); // Prints False
[/csharp]
[/codeblocks]
In GDScript, this is equivalent to the [code]in[/code] operator:
@ -265,7 +321,7 @@
var dict2 = new Godot.Collections.Dictionary{{"A", 10}, {"B", 2}};
// Godot.Collections.Dictionary has no Hash() method. Use GD.Hash() instead.
GD.Print(GD.Hash(dict1) == GD.Hash(dict2)); // Prints true
GD.Print(GD.Hash(dict1) == GD.Hash(dict2)); // Prints True
[/csharp]
[/codeblocks]
[b]Note:[/b] Dictionaries with the same entries but in a different order will not have the same hash.
@ -284,6 +340,45 @@
Returns [code]true[/code] if the dictionary is read-only. See [method make_read_only]. Dictionaries are automatically read-only if declared with [code]const[/code] keyword.
</description>
</method>
<method name="is_same_typed" qualifiers="const">
<return type="bool" />
<param index="0" name="dictionary" type="Dictionary" />
<description>
Returns [code]true[/code] if the dictionary is typed the same as [param dictionary].
</description>
</method>
<method name="is_same_typed_key" qualifiers="const">
<return type="bool" />
<param index="0" name="dictionary" type="Dictionary" />
<description>
Returns [code]true[/code] if the dictionary's keys are typed the same as [param dictionary]'s keys.
</description>
</method>
<method name="is_same_typed_value" qualifiers="const">
<return type="bool" />
<param index="0" name="dictionary" type="Dictionary" />
<description>
Returns [code]true[/code] if the dictionary's values are typed the same as [param dictionary]'s values.
</description>
</method>
<method name="is_typed" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if the dictionary is typed. Typed dictionaries can only store keys/values of their associated type and provide type safety for the [code][][/code] operator. Methods of typed dictionary still return [Variant].
</description>
</method>
<method name="is_typed_key" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if the dictionary's keys are typed.
</description>
</method>
<method name="is_typed_value" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if the dictionary's values are typed.
</description>
</method>
<method name="keys" qualifiers="const">
<return type="Array" />
<description>
@ -365,12 +460,26 @@
Returns [code]true[/code] if the two dictionaries contain the same keys and values, inner [Dictionary] and [Array] keys and values are compared recursively.
</description>
</method>
<method name="set">
<return type="bool" />
<param index="0" name="key" type="Variant" />
<param index="1" name="value" type="Variant" />
<description>
Sets the value of the element at the given [param key] to the given [param value]. This is the same as using the [code][][/code] operator ([code]array[index] = value[/code]).
</description>
</method>
<method name="size" qualifiers="const">
<return type="int" />
<description>
Returns the number of entries in the dictionary. Empty dictionaries ([code]{ }[/code]) always return [code]0[/code]. See also [method is_empty].
</description>
</method>
<method name="sort">
<return type="void" />
<description>
Sorts the dictionary in-place by key. This can be used to ensure dictionaries with the same contents produce equivalent results when getting the [method keys], getting the [method values], and converting to a string. This is also useful when wanting a JSON representation consistent with what is in memory, and useful for storing on a database that requires dictionaries to be sorted.
</description>
</method>
<method name="values" qualifiers="const">
<return type="Array" />
<description>

28
engine/doc/classes/DirAccess.xml
View file

@ -14,7 +14,7 @@
# Static
DirAccess.make_dir_absolute("user://levels/world1")
[/codeblock]
[b]Note:[/b] Many resources types are imported (e.g. textures or sound files), and their source asset will not be included in the exported game, as only the imported version is used. Use [ResourceLoader] to access imported resources.
[b]Note:[/b] Accessing project ("res://") directories once exported may behave unexpectedly as some files are converted to engine-specific formats and their original source files may not be present in the expected PCK package. Because of this, to access resources in an exported project, it is recommended to use [ResourceLoader] instead of [FileAccess].
Here is an example on how to iterate through the files of a directory:
[codeblocks]
[gdscript]
@ -60,6 +60,7 @@
}
[/csharp]
[/codeblocks]
Keep in mind that file names may change or be remapped after export. If you want to see the actual resource file list as it appears in the editor, use [method ResourceLoader.list_directory] instead.
</description>
<tutorials>
<link title="File system">$DOCS_URL/tutorials/scripting/filesystem.html</link>
@ -104,6 +105,17 @@
[b]Note:[/b] This method is implemented on macOS, Linux, and Windows.
</description>
</method>
<method name="create_temp" qualifiers="static">
<return type="DirAccess" />
<param index="0" name="prefix" type="String" default="&quot;&quot;" />
<param index="1" name="keep" type="bool" default="false" />
<description>
Creates a temporary directory. This directory will be freed when the returned [DirAccess] is freed.
If [param prefix] is not empty, it will be prefixed to the directory name, separated by a [code]-[/code].
If [param keep] is [code]true[/code], the directory is not deleted when the returned [DirAccess] is freed.
Returns [code]null[/code] if opening the directory failed. You can use [method get_open_error] to check the error that occurred.
</description>
</method>
<method name="current_is_dir" qualifiers="const">
<return type="bool" />
<description>
@ -115,6 +127,7 @@
<param index="0" name="path" type="String" />
<description>
Returns whether the target directory exists. The argument can be relative to the current directory, or an absolute path.
[b]Note:[/b] The returned [bool] in the editor and after exporting when used on a path in the [code]res://[/code] directory may be different. Some files are converted to engine-specific formats when exported, potentially changing the directory structure.
</description>
</method>
<method name="dir_exists_absolute" qualifiers="static">
@ -122,6 +135,7 @@
<param index="0" name="path" type="String" />
<description>
Static version of [method dir_exists]. Supports only absolute paths.
[b]Note:[/b] The returned [bool] in the editor and after exporting when used on a path in the [code]res://[/code] directory may be different. Some files are converted to engine-specific formats when exported, potentially changing the directory structure.
</description>
</method>
<method name="file_exists">
@ -130,6 +144,7 @@
<description>
Returns whether the target file exists. The argument can be relative to the current directory, or an absolute path.
For a static equivalent, use [method FileAccess.file_exists].
[b]Note:[/b] Many resources types are imported (e.g. textures or sound files), and their source asset will not be included in the exported game, as only the imported version is used. See [method ResourceLoader.exists] for an alternative approach that takes resource remapping into account.
</description>
</method>
<method name="get_current_dir" qualifiers="const">
@ -150,6 +165,7 @@
<description>
Returns a [PackedStringArray] containing filenames of the directory contents, excluding files. The array is sorted alphabetically.
Affected by [member include_hidden] and [member include_navigational].
[b]Note:[/b] The returned directories in the editor and after exporting in the [code]res://[/code] directory may differ as some files are converted to engine-specific formats when exported.
</description>
</method>
<method name="get_directories_at" qualifiers="static">
@ -158,6 +174,7 @@
<description>
Returns a [PackedStringArray] containing filenames of the directory contents, excluding files, at the given [param path]. The array is sorted alphabetically.
Use [method get_directories] if you want more control of what gets included.
[b]Note:[/b] The returned directories in the editor and after exporting in the [code]res://[/code] directory may differ as some files are converted to engine-specific formats when exported.
</description>
</method>
<method name="get_drive_count" qualifiers="static">
@ -193,6 +210,7 @@
<description>
Returns a [PackedStringArray] containing filenames of the directory contents, excluding directories, at the given [param path]. The array is sorted alphabetically.
Use [method get_files] if you want more control of what gets included.
[b]Note:[/b] When used on a [code]res://[/code] path in an exported project, only the files included in the PCK at the given folder level are returned. In practice, this means that since imported resources are stored in a top-level [code].godot/[/code] folder, only paths to [code].gd[/code] and [code].import[/code] files are returned (plus a few other files, such as [code]project.godot[/code] or [code]project.binary[/code] and the project icon). In an exported project, the list of returned files will also vary depending on [member ProjectSettings.editor/export/convert_text_resources_to_binary].
</description>
</method>
<method name="get_next">
@ -214,6 +232,14 @@
Returns the available space on the current directory's disk, in bytes. Returns [code]0[/code] if the platform-specific method to query the available space fails.
</description>
</method>
<method name="is_bundle" qualifiers="const">
<return type="bool" />
<param index="0" name="path" type="String" />
<description>
Returns [code]true[/code] if the directory is a macOS bundle.
[b]Note:[/b] This method is implemented on macOS.
</description>
</method>
<method name="is_case_sensitive" qualifiers="const">
<return type="bool" />
<param index="0" name="path" type="String" />

162
engine/doc/classes/DisplayServer.xml
View file

@ -10,6 +10,13 @@
<tutorials>
</tutorials>
<methods>
<method name="beep" qualifiers="const">
<return type="void" />
<description>
Plays the beep sound from the operative system, if possible. Because it comes from the OS, the beep sound will be audible even if the application is muted. It may also be disabled for the entire OS by the user.
[b]Note:[/b] This method is implemented on macOS, Linux (X11/Wayland), and Windows.
</description>
</method>
<method name="clipboard_get" qualifiers="const">
<return type="String" />
<description>
@ -105,7 +112,7 @@
<param index="3" name="callback" type="Callable" />
<description>
Shows a text input dialog which uses the operating system's native look-and-feel. [param callback] should accept a single [String] parameter which contains the text field's contents.
[b]Note:[/b] This method is implemented if the display server has the [constant FEATURE_NATIVE_DIALOG_INPUT] feature. Supported platforms include macOS and Windows.
[b]Note:[/b] This method is implemented if the display server has the [constant FEATURE_NATIVE_DIALOG_INPUT] feature. Supported platforms include macOS, Windows, and Android.
</description>
</method>
<method name="dialog_show">
@ -116,7 +123,7 @@
<param index="3" name="callback" type="Callable" />
<description>
Shows a text dialog which uses the operating system's native look-and-feel. [param callback] should accept a single [int] parameter which corresponds to the index of the pressed button.
[b]Note:[/b] This method is implemented if the display server has the [constant FEATURE_NATIVE_DIALOG] feature. Supported platforms include macOS and Windows.
[b]Note:[/b] This method is implemented if the display server has the [constant FEATURE_NATIVE_DIALOG] feature. Supported platforms include macOS, Windows, and Android.
</description>
</method>
<method name="enable_for_stealing_focus">
@ -138,12 +145,13 @@
<param index="6" name="callback" type="Callable" />
<description>
Displays OS native dialog for selecting files or directories in the file system.
Each filter string in the [param filters] array should be formatted like this: [code]*.txt,*.doc;Text Files[/code]. The description text of the filter is optional and can be omitted. See also [member FileDialog.filters].
Callbacks have the following arguments: [code]status: bool, selected_paths: PackedStringArray, selected_filter_index: int[/code].
[b]Note:[/b] This method is implemented if the display server has the [constant FEATURE_NATIVE_DIALOG_FILE] feature. Supported platforms include Linux (X11/Wayland), Windows, and macOS.
Each filter string in the [param filters] array should be formatted like this: [code]*.png,*.jpg,*.jpeg;Image Files;image/png,image/jpeg[/code]. The description text of the filter is optional and can be omitted. It is recommended to set both file extension and MIME type. See also [member FileDialog.filters].
Callbacks have the following arguments: [code]status: bool, selected_paths: PackedStringArray, selected_filter_index: int[/code]. [b]On Android,[/b] callback argument [code]selected_filter_index[/code] is always zero.
[b]Note:[/b] This method is implemented if the display server has the [constant FEATURE_NATIVE_DIALOG_FILE] feature. Supported platforms include Linux (X11/Wayland), Windows, macOS, and Android.
[b]Note:[/b] [param current_directory] might be ignored.
[b]Note:[/b] On Linux, [param show_hidden] is ignored.
[b]Note:[/b] On macOS, native file dialogs have no title.
[b]Note:[/b] Embedded file dialog and Windows file dialog support only file extensions, while Android, Linux, and macOS file dialogs also support MIME types.
[b]Note:[/b] On Android and Linux, [param show_hidden] is ignored.
[b]Note:[/b] On Android and macOS, native file dialogs have no title.
[b]Note:[/b] On macOS, sandboxed apps will save security-scoped bookmarks to retain access to the opened folders across multiple sessions. Use [method OS.get_granted_permissions] to get a list of saved bookmarks.
</description>
</method>
@ -160,14 +168,15 @@
<param index="8" name="callback" type="Callable" />
<description>
Displays OS native dialog for selecting files or directories in the file system with additional user selectable options.
Each filter string in the [param filters] array should be formatted like this: [code]*.txt,*.doc;Text Files[/code]. The description text of the filter is optional and can be omitted. See also [member FileDialog.filters].
Each filter string in the [param filters] array should be formatted like this: [code]*.png,*.jpg,*.jpeg;Image Files;image/png,image/jpeg[/code]. The description text of the filter is optional and can be omitted. It is recommended to set both file extension and MIME type. See also [member FileDialog.filters].
[param options] is array of [Dictionary]s with the following keys:
- [code]"name"[/code] - option's name [String].
- [code]"values"[/code] - [PackedStringArray] of values. If empty, boolean option (check box) is used.
- [code]"default"[/code] - default selected option index ([int]) or default boolean value ([bool]).
Callbacks have the following arguments: [code]status: bool, selected_paths: PackedStringArray, selected_filter_index: int, selected_option: Dictionary[/code].
[b]Note:[/b] This method is implemented if the display server has the [constant FEATURE_NATIVE_DIALOG_FILE] feature. Supported platforms include Linux (X11/Wayland), Windows, and macOS.
[b]Note:[/b] This method is implemented if the display server has the [constant FEATURE_NATIVE_DIALOG_FILE_EXTRA] feature. Supported platforms include Linux (X11/Wayland), Windows, and macOS.
[b]Note:[/b] [param current_directory] might be ignored.
[b]Note:[/b] Embedded file dialog and Windows file dialog support only file extensions, while Android, Linux, and macOS file dialogs also support MIME types.
[b]Note:[/b] On Linux (X11), [param show_hidden] is ignored.
[b]Note:[/b] On macOS, native file dialogs have no title.
[b]Note:[/b] On macOS, sandboxed apps will save security-scoped bookmarks to retain access to the opened folders across multiple sessions. Use [method OS.get_granted_permissions] to get a list of saved bookmarks.
@ -184,14 +193,14 @@
<return type="Color" />
<description>
Returns OS theme accent color. Returns [code]Color(0, 0, 0, 0)[/code], if accent color is unknown.
[b]Note:[/b] This method is implemented on macOS and Windows.
[b]Note:[/b] This method is implemented on macOS, Windows, and Android.
</description>
</method>
<method name="get_base_color" qualifiers="const">
<return type="Color" />
<description>
Returns the OS theme base color (default control background). Returns [code]Color(0, 0, 0, 0)[/code] if the base color is unknown.
[b]Note:[/b] This method is implemented on macOS and Windows.
[b]Note:[/b] This method is implemented on macOS, Windows, and Android.
</description>
</method>
<method name="get_display_cutouts" qualifiers="const">
@ -205,6 +214,7 @@
<return type="Rect2i" />
<description>
Returns the unobscured area of the display where interactive controls should be rendered. See also [method get_display_cutouts].
[b]Note:[/b] Currently only implemented on Android and iOS. On other platforms, [code]screen_get_usable_rect(SCREEN_OF_MAIN_WINDOW)[/code] will be returned as a fallback. See also [method screen_get_usable_rect].
</description>
</method>
<method name="get_keyboard_focus_screen" qualifiers="const">
@ -236,7 +246,7 @@
<return type="int" />
<param index="0" name="rect" type="Rect2" />
<description>
Returns index of the screen which contains specified rectangle.
Returns the index of the screen that overlaps the most with the given rectangle. Returns [code]-1[/code] if the rectangle doesn't overlap with any screen or has no area.
</description>
</method>
<method name="get_swap_cancel_ok">
@ -893,6 +903,13 @@
Returns [code]true[/code] if the specified [param feature] is supported by the current [DisplayServer], [code]false[/code] otherwise.
</description>
</method>
<method name="has_hardware_keyboard" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if hardware keyboard is connected.
[b]Note:[/b] This method is implemented on Android and iOS, on other platforms this method always returns [code]true[/code].
</description>
</method>
<method name="help_set_search_callbacks">
<return type="void" />
<param index="0" name="search_callback" type="Callable" />
@ -1064,6 +1081,15 @@
[b]Note:[/b] On macOS, this method requires "Screen Recording" permission, if permission is not granted it will return desktop wallpaper color.
</description>
</method>
<method name="screen_get_image_rect" qualifiers="const">
<return type="Image" />
<param index="0" name="rect" type="Rect2i" />
<description>
Returns screenshot of the screen [param rect].
[b]Note:[/b] This method is implemented on macOS and Windows.
[b]Note:[/b] On macOS, this method requires "Screen Recording" permission, if permission is not granted it will return desktop wallpaper color.
</description>
</method>
<method name="screen_get_max_scale" qualifiers="const">
<return type="float" />
<description>
@ -1127,7 +1153,7 @@
Returns the scale factor of the specified screen by index.
[b]Note:[/b] On macOS, the returned value is [code]2.0[/code] for hiDPI (Retina) screens, and [code]1.0[/code] for all other cases.
[b]Note:[/b] On Linux (Wayland), the returned value is accurate only when [param screen] is [constant SCREEN_OF_MAIN_WINDOW]. Due to API limitations, passing a direct index will return a rounded-up integer, if the screen has a fractional scale (e.g. [code]1.25[/code] would get rounded up to [code]2.0[/code]).
[b]Note:[/b] This method is implemented only on macOS and Linux (Wayland).
[b]Note:[/b] This method is implemented on Android, iOS, Web, macOS, and Linux (Wayland).
</description>
</method>
<method name="screen_get_size" qualifiers="const">
@ -1190,6 +1216,13 @@
[b]Note:[/b] This method is implemented on Android, iOS, macOS, Windows, and Linux (X11/Wayland).
</description>
</method>
<method name="show_emoji_and_symbol_picker" qualifiers="const">
<return type="void" />
<description>
Opens system emoji and symbol picker.
[b]Note:[/b] This method is implemented on macOS and Windows.
</description>
</method>
<method name="status_indicator_get_rect" qualifiers="const">
<return type="Rect2" />
<param index="0" name="id" type="int" />
@ -1676,6 +1709,7 @@
<param index="1" name="window_id" type="int" default="0" />
<description>
Sets window mode for the given window to [param mode]. See [enum WindowMode] for possible values and how each mode behaves.
[b]Note:[/b] On Android, setting it to [constant WINDOW_MODE_FULLSCREEN] or [constant WINDOW_MODE_EXCLUSIVE_FULLSCREEN] will enable immersive mode.
[b]Note:[/b] Setting the window to full screen forcibly sets the borderless flag to [code]true[/code], so make sure to set it back to [code]false[/code] when not wanted.
</description>
</method>
@ -1705,7 +1739,7 @@
DisplayServer.WindowSetMousePassthrough(GetNode&lt;Polygon2D&gt;("Polygon2D").Polygon);
// Reset region to default.
DisplayServer.WindowSetMousePassthrough(new Vector2[] {});
DisplayServer.WindowSetMousePassthrough([]);
[/csharp]
[/codeblocks]
[b]Note:[/b] On Windows, the portion of a window that lies outside the region is not drawn, while on Linux (X11) and macOS it is.
@ -1772,7 +1806,7 @@
<param index="0" name="window_id" type="int" />
<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.
Sets window transient parent. Transient window 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.
[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>
@ -1806,6 +1840,23 @@
[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_start_drag">
<return type="void" />
<param index="0" name="window_id" type="int" default="0" />
<description>
Starts an interactive drag operation on the window with the given [param window_id], using the current mouse position. Call this method when handling a mouse button being pressed to simulate a pressed event on the window's title bar. Using this method allows the window to participate in space switching, tiling, and other system features.
[b]Note:[/b] This method is implemented on Linux (X11/Wayland), macOS, and Windows.
</description>
</method>
<method name="window_start_resize">
<return type="void" />
<param index="0" name="edge" type="int" enum="DisplayServer.WindowResizeEdge" />
<param index="1" name="window_id" type="int" default="0" />
<description>
Starts an interactive resize operation on the window with the given [param window_id], using the current mouse position. Call this method when handling a mouse button being pressed to simulate a pressed event on the window's edge.
[b]Note:[/b] This method is implemented on Linux (X11/Wayland), macOS, and Windows.
</description>
</method>
</methods>
<constants>
<constant name="FEATURE_GLOBAL_MENU" value="0" enum="Feature" deprecated="Use [NativeMenu] or [PopupMenu] instead.">
@ -1881,7 +1932,25 @@
Display server supports spawning text input dialogs using the operating system's native look-and-feel. See [method dialog_input_text]. [b]Windows, macOS[/b]
</constant>
<constant name="FEATURE_NATIVE_DIALOG_FILE" value="25" enum="Feature">
Display server supports spawning dialogs for selecting files or directories using the operating system's native look-and-feel. See [method file_dialog_show] and [method file_dialog_with_options_show]. [b]Windows, macOS, Linux (X11/Wayland)[/b]
Display server supports spawning dialogs for selecting files or directories using the operating system's native look-and-feel. See [method file_dialog_show]. [b]Windows, macOS, Linux (X11/Wayland), Android[/b]
</constant>
<constant name="FEATURE_NATIVE_DIALOG_FILE_EXTRA" value="26" enum="Feature">
The display server supports all features of [constant FEATURE_NATIVE_DIALOG_FILE], with the added functionality of Options and native dialog file access to [code]res://[/code] and [code]user://[/code] paths. See [method file_dialog_show] and [method file_dialog_with_options_show]. [b]Windows, macOS, Linux (X11/Wayland)[/b]
</constant>
<constant name="FEATURE_WINDOW_DRAG" value="27" enum="Feature">
The display server supports initiating window drag and resize operations on demand. See [method window_start_drag] and [method window_start_resize].
</constant>
<constant name="FEATURE_SCREEN_EXCLUDE_FROM_CAPTURE" value="28" enum="Feature">
Display server supports [constant WINDOW_FLAG_EXCLUDE_FROM_CAPTURE] window flag.
</constant>
<constant name="FEATURE_WINDOW_EMBEDDING" value="29" enum="Feature">
Display server supports embedding a window from another process. [b]Windows, Linux (X11)[/b]
</constant>
<constant name="FEATURE_NATIVE_DIALOG_FILE_MIME" value="30" enum="Feature">
Native file selection dialog supports MIME types as filters.
</constant>
<constant name="FEATURE_EMOJI_AND_SYMBOL_PICKER" value="31" enum="Feature">
Display server supports system emoji and symbol picker. [b]Windows, macOS[/b]
</constant>
<constant name="MOUSE_MODE_VISIBLE" value="0" enum="MouseMode">
Makes the mouse cursor visible if it is hidden.
@ -1899,6 +1968,9 @@
<constant name="MOUSE_MODE_CONFINED_HIDDEN" value="4" enum="MouseMode">
Confines the mouse cursor to the game window, and make it hidden.
</constant>
<constant name="MOUSE_MODE_MAX" value="5" enum="MouseMode">
Max value of the [enum MouseMode].
</constant>
<constant name="SCREEN_WITH_MOUSE_FOCUS" value="-4">
Represents the screen containing the mouse pointer.
[b]Note:[/b] On Linux (Wayland), this constant always represents the screen at index [code]0[/code].
@ -2051,6 +2123,7 @@
<constant name="WINDOW_MODE_FULLSCREEN" value="3" enum="WindowMode">
Full screen mode with full multi-window support.
Full screen window covers the entire display area of a screen and has no decorations. The display's video mode is not changed.
[b]On Android:[/b] This enables immersive mode.
[b]On Windows:[/b] Multi-window full-screen mode has a 1px border of the [member ProjectSettings.rendering/environment/defaults/default_clear_color] color.
[b]On macOS:[/b] A new desktop is used to display the running project.
[b]Note:[/b] Regardless of the platform, enabling full screen will change the window size to match the monitor's size. Therefore, make sure your project supports [url=$DOCS_URL/tutorials/rendering/multiple_resolutions.html]multiple resolutions[/url] when enabling full screen mode.
@ -2058,9 +2131,11 @@
<constant name="WINDOW_MODE_EXCLUSIVE_FULLSCREEN" value="4" enum="WindowMode">
A single window full screen mode. This mode has less overhead, but only one window can be open on a given screen at a time (opening a child window or application switching will trigger a full screen transition).
Full screen window covers the entire display area of a screen and has no border or decorations. The display's video mode is not changed.
[b]On Android:[/b] This enables immersive mode.
[b]On Windows:[/b] Depending on video driver, full screen transition might cause screens to go black for a moment.
[b]On macOS:[/b] A new desktop is used to display the running project. Exclusive full screen mode prevents Dock and Menu from showing up when the mouse pointer is hovering the edge of the screen.
[b]On Linux (X11):[/b] Exclusive full screen mode bypasses compositor.
[b]On Linux (Wayland):[/b] Equivalent to [constant WINDOW_MODE_FULLSCREEN].
[b]Note:[/b] Regardless of the platform, enabling full screen will change the window size to match the monitor's size. Therefore, make sure your project supports [url=$DOCS_URL/tutorials/rendering/multiple_resolutions.html]multiple resolutions[/url] when enabling full screen mode.
</constant>
<constant name="WINDOW_FLAG_RESIZE_DISABLED" value="0" enum="WindowFlags">
@ -2092,7 +2167,16 @@
<constant name="WINDOW_FLAG_MOUSE_PASSTHROUGH" value="7" enum="WindowFlags">
All mouse events are passed to the underlying window of the same application.
</constant>
<constant name="WINDOW_FLAG_MAX" value="8" enum="WindowFlags">
<constant name="WINDOW_FLAG_SHARP_CORNERS" value="8" enum="WindowFlags">
Window style is overridden, forcing sharp corners.
[b]Note:[/b] This flag is implemented only on Windows (11).
</constant>
<constant name="WINDOW_FLAG_EXCLUDE_FROM_CAPTURE" value="9" enum="WindowFlags">
Windows is excluded from screenshots taken by [method screen_get_image], [method screen_get_image_rect], and [method screen_get_pixel].
[b]Note:[/b] This flag is implemented on macOS and Windows.
[b]Note:[/b] Setting this flag will [b]NOT[/b] prevent other apps from capturing an image, it should not be used as a security measure.
</constant>
<constant name="WINDOW_FLAG_MAX" value="10" enum="WindowFlags">
Max value of the [enum WindowFlags].
</constant>
<constant name="WINDOW_EVENT_MOUSE_ENTER" value="0" enum="WindowEvent">
@ -2122,6 +2206,33 @@
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="WINDOW_EDGE_TOP_LEFT" value="0" enum="WindowResizeEdge">
Top-left edge of a window.
</constant>
<constant name="WINDOW_EDGE_TOP" value="1" enum="WindowResizeEdge">
Top edge of a window.
</constant>
<constant name="WINDOW_EDGE_TOP_RIGHT" value="2" enum="WindowResizeEdge">
Top-right edge of a window.
</constant>
<constant name="WINDOW_EDGE_LEFT" value="3" enum="WindowResizeEdge">
Left edge of a window.
</constant>
<constant name="WINDOW_EDGE_RIGHT" value="4" enum="WindowResizeEdge">
Right edge of a window.
</constant>
<constant name="WINDOW_EDGE_BOTTOM_LEFT" value="5" enum="WindowResizeEdge">
Bottom-left edge of a window.
</constant>
<constant name="WINDOW_EDGE_BOTTOM" value="6" enum="WindowResizeEdge">
Bottom edge of a window.
</constant>
<constant name="WINDOW_EDGE_BOTTOM_RIGHT" value="7" enum="WindowResizeEdge">
Bottom-right edge of a window.
</constant>
<constant name="WINDOW_EDGE_MAX" value="8" enum="WindowResizeEdge">
Represents the size of the [enum WindowResizeEdge] enum.
</constant>
<constant name="VSYNC_DISABLED" value="0" enum="VSyncMode">
No vertical synchronization, which means the engine will display frames as fast as possible (tearing may be visible). Framerate is unlimited (regardless of [member Engine.max_fps]).
</constant>
@ -2138,29 +2249,42 @@
<constant name="DISPLAY_HANDLE" value="0" enum="HandleType">
Display handle:
- Linux (X11): [code]X11::Display*[/code] for the display.
- Linux (Wayland): [code]wl_display[/code] for the display.
- Android: [code]EGLDisplay[/code] for the display.
</constant>
<constant name="WINDOW_HANDLE" value="1" enum="HandleType">
Window handle:
- Windows: [code]HWND[/code] for the window.
- Linux (X11): [code]X11::Window*[/code] for the window.
- Linux (Wayland): [code]wl_surface[/code] for the window.
- macOS: [code]NSWindow*[/code] for the window.
- iOS: [code]UIViewController*[/code] for the view controller.
- Android: [code]jObject[/code] for the activity.
</constant>
<constant name="WINDOW_VIEW" value="2" enum="HandleType">
Window view:
- Windows: [code]HDC[/code] for the window (only with the GL Compatibility renderer).
- Windows: [code]HDC[/code] for the window (only with the Compatibility renderer).
- macOS: [code]NSView*[/code] for the window main view.
- iOS: [code]UIView*[/code] for the window main view.
</constant>
<constant name="OPENGL_CONTEXT" value="3" enum="HandleType">
OpenGL context (only with the GL Compatibility renderer):
OpenGL context (only with the Compatibility renderer):
- Windows: [code]HGLRC[/code] for the window (native GL), or [code]EGLContext[/code] for the window (ANGLE).
- Linux (X11): [code]GLXContext*[/code] for the window.
- Linux (Wayland): [code]EGLContext[/code] for the window.
- macOS: [code]NSOpenGLContext*[/code] for the window (native GL), or [code]EGLContext[/code] for the window (ANGLE).
- Android: [code]EGLContext[/code] for the window.
</constant>
<constant name="EGL_DISPLAY" value="4" enum="HandleType">
- Windows: [code]EGLDisplay[/code] for the window (ANGLE).
- macOS: [code]EGLDisplay[/code] for the window (ANGLE).
- Linux (Wayland): [code]EGLDisplay[/code] for the window.
</constant>
<constant name="EGL_CONFIG" value="5" enum="HandleType">
- Windows: [code]EGLConfig[/code] for the window (ANGLE).
- macOS: [code]EGLConfig[/code] for the window (ANGLE).
- Linux (Wayland): [code]EGLConfig[/code] for the window.
</constant>
<constant name="TTS_UTTERANCE_STARTED" value="0" enum="TTSUtteranceEvent">
Utterance has begun to be spoken.
</constant>

114
engine/doc/classes/EditorContextMenuPlugin.xml Normal file
View file

@ -0,0 +1,114 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="EditorContextMenuPlugin" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Plugin for adding custom context menus in the editor.
</brief_description>
<description>
[EditorContextMenuPlugin] allows for the addition of custom options in the editor's context menu.
Currently, context menus are supported for three commonly used areas: the file system, scene tree, and editor script list panel.
</description>
<tutorials>
</tutorials>
<methods>
<method name="_popup_menu" qualifiers="virtual">
<return type="void" />
<param index="0" name="paths" type="PackedStringArray" />
<description>
Called when creating a context menu, custom options can be added by using the [method add_context_menu_item] or [method add_context_menu_item_from_shortcut] functions. [param paths] contains currently selected paths (depending on menu), which can be used to conditionally add options.
</description>
</method>
<method name="add_context_menu_item">
<return type="void" />
<param index="0" name="name" type="String" />
<param index="1" name="callback" type="Callable" />
<param index="2" name="icon" type="Texture2D" default="null" />
<description>
Add custom option to the context menu of the plugin's specified slot. When the option is activated, [param callback] will be called. Callback should take single [Array] argument; array contents depend on context menu slot.
[codeblock]
func _popup_menu(paths):
add_context_menu_item("File Custom options", handle, ICON)
[/codeblock]
If you want to assign shortcut to the menu item, use [method add_context_menu_item_from_shortcut] instead.
</description>
</method>
<method name="add_context_menu_item_from_shortcut">
<return type="void" />
<param index="0" name="name" type="String" />
<param index="1" name="shortcut" type="Shortcut" />
<param index="2" name="icon" type="Texture2D" default="null" />
<description>
Add custom option to the context menu of the plugin's specified slot. The option will have the [param shortcut] assigned and reuse its callback. The shortcut has to be registered beforehand with [method add_menu_shortcut].
[codeblock]
func _init():
add_menu_shortcut(SHORTCUT, handle)
func _popup_menu(paths):
add_context_menu_item_from_shortcut("File Custom options", SHORTCUT, ICON)
[/codeblock]
</description>
</method>
<method name="add_context_submenu_item">
<return type="void" />
<param index="0" name="name" type="String" />
<param index="1" name="menu" type="PopupMenu" />
<param index="2" name="icon" type="Texture2D" default="null" />
<description>
Add a submenu to the context menu of the plugin's specified slot. The submenu is not automatically handled, you need to connect to its signals yourself. Also the submenu is freed on every popup, so provide a new [PopupMenu] every time.
[codeblock]
func _popup_menu(paths):
var popup_menu = PopupMenu.new()
popup_menu.add_item("Blue")
popup_menu.add_item("White")
popup_menu.id_pressed.connect(_on_color_submenu_option)
add_context_submenu_item("Set Node Color", popup_menu)
[/codeblock]
</description>
</method>
<method name="add_menu_shortcut">
<return type="void" />
<param index="0" name="shortcut" type="Shortcut" />
<param index="1" name="callback" type="Callable" />
<description>
Registers a shortcut associated with the plugin's context menu. This method should be called once (e.g. in plugin's [method Object._init]). [param callback] will be called when user presses the specified [param shortcut] while the menu's context is in effect (e.g. FileSystem dock is focused). Callback should take single [Array] argument; array contents depend on context menu slot.
[codeblock]
func _init():
add_menu_shortcut(SHORTCUT, handle)
[/codeblock]
</description>
</method>
</methods>
<constants>
<constant name="CONTEXT_SLOT_SCENE_TREE" value="0" enum="ContextMenuSlot">
Context menu of Scene dock. [method _popup_menu] will be called with a list of paths to currently selected nodes, while option callback will receive the list of currently selected nodes.
</constant>
<constant name="CONTEXT_SLOT_FILESYSTEM" value="1" enum="ContextMenuSlot">
Context menu of FileSystem dock. [method _popup_menu] and option callback will be called with list of paths of the currently selected files.
</constant>
<constant name="CONTEXT_SLOT_SCRIPT_EDITOR" value="2" enum="ContextMenuSlot">
Context menu of Script editor's script tabs. [method _popup_menu] will be called with the path to the currently edited script, while option callback will receive reference to that script.
</constant>
<constant name="CONTEXT_SLOT_FILESYSTEM_CREATE" value="3" enum="ContextMenuSlot">
The "Create..." submenu of FileSystem dock's context menu. [method _popup_menu] and option callback will be called with list of paths of the currently selected files.
</constant>
<constant name="CONTEXT_SLOT_SCRIPT_EDITOR_CODE" value="4" enum="ContextMenuSlot">
Context menu of Script editor's code editor. [method _popup_menu] will be called with the path to the [CodeEdit] node. You can fetch it using this code:
[codeblock]
func _popup_menu(paths):
var code_edit = Engine.get_main_loop().root.get_node(paths[0]);
[/codeblock]
The option callback will receive reference to that node. You can use [CodeEdit] methods to perform symbol lookups etc.
</constant>
<constant name="CONTEXT_SLOT_SCENE_TABS" value="5" enum="ContextMenuSlot">
Context menu of scene tabs. [method _popup_menu] will be called with the path of the clicked scene, or empty [PackedStringArray] if the menu was opened on empty space. The option callback will receive the path of the clicked scene, or empty [String] if none was clicked.
</constant>
<constant name="CONTEXT_SLOT_2D_EDITOR" value="6" enum="ContextMenuSlot">
Context menu of 2D editor's basic right-click menu. [method _popup_menu] will be called with paths to all [CanvasItem] nodes under the cursor. You can fetch them using this code:
[codeblock]
func _popup_menu(paths):
var canvas_item = Engine.get_main_loop().root.get_node(paths[0]); # Replace 0 with the desired index.
[/codeblock]
The paths array is empty if there weren't any nodes under cursor. The option callback will receive a typed array of [CanvasItem] nodes.
</constant>
</constants>
</class>

34
engine/doc/classes/EditorDebuggerPlugin.xml
View file

@ -15,18 +15,20 @@
class ExampleEditorDebugger extends EditorDebuggerPlugin:
func _has_capture(prefix):
# Return true if you wish to handle message with this prefix.
return prefix == "my_plugin"
func _has_capture(capture):
# Return true if you wish to handle messages with the prefix "my_plugin:".
return capture == "my_plugin"
func _capture(message, data, session_id):
if message == "my_plugin:ping":
get_session(session_id).send_message("my_plugin:echo", data)
return true
return false
func _setup_session(session_id):
# Add a new tab in the debugger session UI containing a label.
var label = Label.new()
label.name = "Example plugin"
label.name = "Example plugin" # Will be used as the tab title.
label.text = "Example plugin"
var session = get_session(session_id)
# Listens to the session started and stopped signals.
@ -43,6 +45,24 @@
remove_debugger_plugin(debugger)
[/gdscript]
[/codeblocks]
To connect on the running game side, use the [EngineDebugger] singleton:
[codeblocks]
[gdscript]
extends Node
func _ready():
EngineDebugger.register_message_capture("my_plugin", _capture)
EngineDebugger.send_message("my_plugin:ping", ["test"])
func _capture(message, data):
# Note that the "my_plugin:" prefix is not used here.
if message == "echo":
prints("Echo received:", data)
return true
return false
[/gdscript]
[/codeblocks]
[b]Note:[/b] While the game is running, [method @GlobalScope.print] and similar functions [i]called in the editor[/i] do not print anything, the Output Log prints only game messages.
</description>
<tutorials>
</tutorials>
@ -68,7 +88,7 @@
<param index="1" name="data" type="Array" />
<param index="2" name="session_id" type="int" />
<description>
Override this method to process incoming messages. The [param session_id] is the ID of the [EditorDebuggerSession] that received the message (which you can retrieve via [method get_session]).
Override this method to process incoming messages. The [param session_id] is the ID of the [EditorDebuggerSession] that received the [param message]. Use [method get_session] to retrieve the session. This method should return [code]true[/code] if the message is recognized.
</description>
</method>
<method name="_goto_script_line" qualifiers="virtual">
@ -83,14 +103,14 @@
<return type="bool" />
<param index="0" name="capture" type="String" />
<description>
Override this method to enable receiving messages from the debugger. If [param capture] is "my_message" then messages starting with "my_message:" will be passes to the [method _capture] method.
Override this method to enable receiving messages from the debugger. If [param capture] is "my_message" then messages starting with "my_message:" will be passed to the [method _capture] method.
</description>
</method>
<method name="_setup_session" qualifiers="virtual">
<return type="void" />
<param index="0" name="session_id" type="int" />
<description>
Override this method to be notified whenever a new [EditorDebuggerSession] is created (the session may be inactive during this stage).
Override this method to be notified whenever a new [EditorDebuggerSession] is created. Note that the session may be inactive during this stage.
</description>
</method>
<method name="get_session">

2
engine/doc/classes/EditorDebuggerSession.xml
View file

@ -14,7 +14,7 @@
<return type="void" />
<param index="0" name="control" type="Control" />
<description>
Adds the given [param control] to the debug session UI in the debugger bottom panel.
Adds the given [param control] to the debug session UI in the debugger bottom panel. The [param control]'s node name will be used as the tab title.
</description>
</method>
<method name="is_active">

256
engine/doc/classes/EditorExportPlatform.xml
View file

@ -11,11 +11,267 @@
<link title="Console support in Godot">$DOCS_URL/tutorials/platform/consoles.html</link>
</tutorials>
<methods>
<method name="add_message">
<return type="void" />
<param index="0" name="type" type="int" enum="EditorExportPlatform.ExportMessageType" />
<param index="1" name="category" type="String" />
<param index="2" name="message" type="String" />
<description>
Adds a message to the export log that will be displayed when exporting ends.
</description>
</method>
<method name="clear_messages">
<return type="void" />
<description>
Clears the export log.
</description>
</method>
<method name="create_preset">
<return type="EditorExportPreset" />
<description>
Create a new preset for this platform.
</description>
</method>
<method name="export_pack">
<return type="int" enum="Error" />
<param index="0" name="preset" type="EditorExportPreset" />
<param index="1" name="debug" type="bool" />
<param index="2" name="path" type="String" />
<param index="3" name="flags" type="int" enum="EditorExportPlatform.DebugFlags" is_bitfield="true" default="0" />
<description>
Creates a PCK archive at [param path] for the specified [param preset].
</description>
</method>
<method name="export_pack_patch">
<return type="int" enum="Error" />
<param index="0" name="preset" type="EditorExportPreset" />
<param index="1" name="debug" type="bool" />
<param index="2" name="path" type="String" />
<param index="3" name="patches" type="PackedStringArray" default="PackedStringArray()" />
<param index="4" name="flags" type="int" enum="EditorExportPlatform.DebugFlags" is_bitfield="true" default="0" />
<description>
Creates a patch PCK archive at [param path] for the specified [param preset], containing only the files that have changed since the last patch.
[b]Note:[/b] [param patches] is an optional override of the set of patches defined in the export preset. When empty the patches defined in the export preset will be used instead.
</description>
</method>
<method name="export_project">
<return type="int" enum="Error" />
<param index="0" name="preset" type="EditorExportPreset" />
<param index="1" name="debug" type="bool" />
<param index="2" name="path" type="String" />
<param index="3" name="flags" type="int" enum="EditorExportPlatform.DebugFlags" is_bitfield="true" default="0" />
<description>
Creates a full project at [param path] for the specified [param preset].
</description>
</method>
<method name="export_project_files">
<return type="int" enum="Error" />
<param index="0" name="preset" type="EditorExportPreset" />
<param index="1" name="debug" type="bool" />
<param index="2" name="save_cb" type="Callable" />
<param index="3" name="shared_cb" type="Callable" default="Callable()" />
<description>
Exports project files for the specified preset. This method can be used to implement custom export format, other than PCK and ZIP. One of the callbacks is called for each exported file.
[param save_cb] is called for all exported files and have the following arguments: [code]file_path: String[/code], [code]file_data: PackedByteArray[/code], [code]file_index: int[/code], [code]file_count: int[/code], [code]encryption_include_filters: PackedStringArray[/code], [code]encryption_exclude_filters: PackedStringArray[/code], [code]encryption_key: PackedByteArray[/code].
[param shared_cb] is called for exported native shared/static libraries and have the following arguments: [code]file_path: String[/code], [code]tags: PackedStringArray[/code], [code]target_folder: String[/code].
[b]Note:[/b] [code]file_index[/code] and [code]file_count[/code] are intended for progress tracking only and aren't necesserely unique and precise.
</description>
</method>
<method name="export_zip">
<return type="int" enum="Error" />
<param index="0" name="preset" type="EditorExportPreset" />
<param index="1" name="debug" type="bool" />
<param index="2" name="path" type="String" />
<param index="3" name="flags" type="int" enum="EditorExportPlatform.DebugFlags" is_bitfield="true" default="0" />
<description>
Create a ZIP archive at [param path] for the specified [param preset].
</description>
</method>
<method name="export_zip_patch">
<return type="int" enum="Error" />
<param index="0" name="preset" type="EditorExportPreset" />
<param index="1" name="debug" type="bool" />
<param index="2" name="path" type="String" />
<param index="3" name="patches" type="PackedStringArray" default="PackedStringArray()" />
<param index="4" name="flags" type="int" enum="EditorExportPlatform.DebugFlags" is_bitfield="true" default="0" />
<description>
Create a patch ZIP archive at [param path] for the specified [param preset], containing only the files that have changed since the last patch.
[b]Note:[/b] [param patches] is an optional override of the set of patches defined in the export preset. When empty the patches defined in the export preset will be used instead.
</description>
</method>
<method name="find_export_template" qualifiers="const">
<return type="Dictionary" />
<param index="0" name="template_file_name" type="String" />
<description>
Locates export template for the platform, and returns [Dictionary] with the following keys: [code]path: String[/code] and [code]error: String[/code]. This method is provided for convenience and custom export platforms aren't required to use it or keep export templates stored in the same way official templates are.
</description>
</method>
<method name="gen_export_flags">
<return type="PackedStringArray" />
<param index="0" name="flags" type="int" enum="EditorExportPlatform.DebugFlags" is_bitfield="true" />
<description>
Generates array of command line arguments for the default export templates for the debug flags and editor settings.
</description>
</method>
<method name="get_current_presets" qualifiers="const">
<return type="Array" />
<description>
Returns array of [EditorExportPreset]s for this platform.
</description>
</method>
<method name="get_forced_export_files" qualifiers="static">
<return type="PackedStringArray" />
<description>
Returns array of core file names that always should be exported regardless of preset config.
</description>
</method>
<method name="get_internal_export_files">
<return type="Dictionary" />
<param index="0" name="preset" type="EditorExportPreset" />
<param index="1" name="debug" type="bool" />
<description>
Returns additional files that should always be exported regardless of preset configuration, and are not part of the project source. The returned [Dictionary] contains filename keys ([String]) and their corresponding raw data ([PackedByteArray]).
</description>
</method>
<method name="get_message_category" qualifiers="const">
<return type="String" />
<param index="0" name="index" type="int" />
<description>
Returns message category, for the message with [param index].
</description>
</method>
<method name="get_message_count" qualifiers="const">
<return type="int" />
<description>
Returns number of messages in the export log.
</description>
</method>
<method name="get_message_text" qualifiers="const">
<return type="String" />
<param index="0" name="index" type="int" />
<description>
Returns message text, for the message with [param index].
</description>
</method>
<method name="get_message_type" qualifiers="const">
<return type="int" enum="EditorExportPlatform.ExportMessageType" />
<param index="0" name="index" type="int" />
<description>
Returns message type, for the message with [param index].
</description>
</method>
<method name="get_os_name" qualifiers="const">
<return type="String" />
<description>
Returns the name of the export operating system handled by this [EditorExportPlatform] class, as a friendly string. Possible return values are [code]Windows[/code], [code]Linux[/code], [code]macOS[/code], [code]Android[/code], [code]iOS[/code], and [code]Web[/code].
</description>
</method>
<method name="get_worst_message_type" qualifiers="const">
<return type="int" enum="EditorExportPlatform.ExportMessageType" />
<description>
Returns most severe message type currently present in the export log.
</description>
</method>
<method name="save_pack">
<return type="Dictionary" />
<param index="0" name="preset" type="EditorExportPreset" />
<param index="1" name="debug" type="bool" />
<param index="2" name="path" type="String" />
<param index="3" name="embed" type="bool" default="false" />
<description>
Saves PCK archive and returns [Dictionary] with the following keys: [code]result: Error[/code], [code]so_files: Array[/code] (array of the shared/static objects which contains dictionaries with the following keys: [code]path: String[/code], [code]tags: PackedStringArray[/code], and [code]target_folder: String[/code]).
If [param embed] is [code]true[/code], PCK content is appended to the end of [param path] file and return [Dictionary] additionally include following keys: [code]embedded_start: int[/code] (embedded PCK offset) and [code]embedded_size: int[/code] (embedded PCK size).
</description>
</method>
<method name="save_pack_patch">
<return type="Dictionary" />
<param index="0" name="preset" type="EditorExportPreset" />
<param index="1" name="debug" type="bool" />
<param index="2" name="path" type="String" />
<description>
Saves patch PCK archive and returns [Dictionary] with the following keys: [code]result: Error[/code], [code]so_files: Array[/code] (array of the shared/static objects which contains dictionaries with the following keys: [code]path: String[/code], [code]tags: PackedStringArray[/code], and [code]target_folder: String[/code]).
</description>
</method>
<method name="save_zip">
<return type="Dictionary" />
<param index="0" name="preset" type="EditorExportPreset" />
<param index="1" name="debug" type="bool" />
<param index="2" name="path" type="String" />
<description>
Saves ZIP archive and returns [Dictionary] with the following keys: [code]result: Error[/code], [code]so_files: Array[/code] (array of the shared/static objects which contains dictionaries with the following keys: [code]path: String[/code], [code]tags: PackedStringArray[/code], and [code]target_folder: String[/code]).
</description>
</method>
<method name="save_zip_patch">
<return type="Dictionary" />
<param index="0" name="preset" type="EditorExportPreset" />
<param index="1" name="debug" type="bool" />
<param index="2" name="path" type="String" />
<description>
Saves patch ZIP archive and returns [Dictionary] with the following keys: [code]result: Error[/code], [code]so_files: Array[/code] (array of the shared/static objects which contains dictionaries with the following keys: [code]path: String[/code], [code]tags: PackedStringArray[/code], and [code]target_folder: String[/code]).
</description>
</method>
<method name="ssh_push_to_remote" qualifiers="const">
<return type="int" enum="Error" />
<param index="0" name="host" type="String" />
<param index="1" name="port" type="String" />
<param index="2" name="scp_args" type="PackedStringArray" />
<param index="3" name="src_file" type="String" />
<param index="4" name="dst_file" type="String" />
<description>
Uploads specified file over SCP protocol to the remote host.
</description>
</method>
<method name="ssh_run_on_remote" qualifiers="const">
<return type="int" enum="Error" />
<param index="0" name="host" type="String" />
<param index="1" name="port" type="String" />
<param index="2" name="ssh_arg" type="PackedStringArray" />
<param index="3" name="cmd_args" type="String" />
<param index="4" name="output" type="Array" default="[]" />
<param index="5" name="port_fwd" type="int" default="-1" />
<description>
Executes specified command on the remote host via SSH protocol and returns command output in the [param output].
</description>
</method>
<method name="ssh_run_on_remote_no_wait" qualifiers="const">
<return type="int" />
<param index="0" name="host" type="String" />
<param index="1" name="port" type="String" />
<param index="2" name="ssh_args" type="PackedStringArray" />
<param index="3" name="cmd_args" type="String" />
<param index="4" name="port_fwd" type="int" default="-1" />
<description>
Executes specified command on the remote host via SSH protocol and returns process ID (on the remote host) without waiting for command to finish.
</description>
</method>
</methods>
<constants>
<constant name="EXPORT_MESSAGE_NONE" value="0" enum="ExportMessageType">
Invalid message type used as the default value when no type is specified.
</constant>
<constant name="EXPORT_MESSAGE_INFO" value="1" enum="ExportMessageType">
Message type for informational messages that have no effect on the export.
</constant>
<constant name="EXPORT_MESSAGE_WARNING" value="2" enum="ExportMessageType">
Message type for warning messages that should be addressed but still allow to complete the export.
</constant>
<constant name="EXPORT_MESSAGE_ERROR" value="3" enum="ExportMessageType">
Message type for error messages that must be addressed and fail the export.
</constant>
<constant name="DEBUG_FLAG_DUMB_CLIENT" value="1" enum="DebugFlags" is_bitfield="true">
Flag is set if remotely debugged project is expected to use remote file system. If set, [method gen_export_flags] will add [code]--remove-fs[/code] and [code]--remote-fs-password[/code] (if password is set in the editor settings) command line arguments to the list.
</constant>
<constant name="DEBUG_FLAG_REMOTE_DEBUG" value="2" enum="DebugFlags" is_bitfield="true">
Flag is set if remote debug is enabled. If set, [method gen_export_flags] will add [code]--remote-debug[/code] and [code]--breakpoints[/code] (if breakpoints are selected in the script editor or added by the plugin) command line arguments to the list.
</constant>
<constant name="DEBUG_FLAG_REMOTE_DEBUG_LOCALHOST" value="4" enum="DebugFlags" is_bitfield="true">
Flag is set if remotely debugged project is running on the localhost. If set, [method gen_export_flags] will use [code]localhost[/code] instead of [member EditorSettings.network/debug/remote_host] as remote debugger host.
</constant>
<constant name="DEBUG_FLAG_VIEW_COLLISIONS" value="8" enum="DebugFlags" is_bitfield="true">
Flag is set if "Visible Collision Shapes" remote debug option is enabled. If set, [method gen_export_flags] will add [code]--debug-collisions[/code] command line arguments to the list.
</constant>
<constant name="DEBUG_FLAG_VIEW_NAVIGATION" value="16" enum="DebugFlags" is_bitfield="true">
Flag is set if Visible Navigation" remote debug option is enabled. If set, [method gen_export_flags] will add [code]--debug-navigation[/code] command line arguments to the list.
</constant>
</constants>
</class>

310
engine/doc/classes/EditorExportPlatformExtension.xml Normal file
View file

@ -0,0 +1,310 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="EditorExportPlatformExtension" inherits="EditorExportPlatform" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Base class for custom [EditorExportPlatform] implementations (plugins).
</brief_description>
<description>
External [EditorExportPlatform] implementations should inherit from this class.
To use [EditorExportPlatform], register it using the [method EditorPlugin.add_export_platform] method first.
</description>
<tutorials>
</tutorials>
<methods>
<method name="_can_export" qualifiers="virtual const">
<return type="bool" />
<param index="0" name="preset" type="EditorExportPreset" />
<param index="1" name="debug" type="bool" />
<description>
[b]Optional.[/b]
Returns [code]true[/code], if specified [param preset] is valid and can be exported. Use [method set_config_error] and [method set_config_missing_templates] to set error details.
Usual implementation can call [method _has_valid_export_configuration] and [method _has_valid_project_configuration] to determine if export is possible.
</description>
</method>
<method name="_cleanup" qualifiers="virtual">
<return type="void" />
<description>
[b]Optional.[/b]
Called by the editor before platform is unregistered.
</description>
</method>
<method name="_export_pack" qualifiers="virtual">
<return type="int" enum="Error" />
<param index="0" name="preset" type="EditorExportPreset" />
<param index="1" name="debug" type="bool" />
<param index="2" name="path" type="String" />
<param index="3" name="flags" type="int" enum="EditorExportPlatform.DebugFlags" is_bitfield="true" />
<description>
[b]Optional.[/b]
Creates a PCK archive at [param path] for the specified [param preset].
This method is called when "Export PCK/ZIP" button is pressed in the export dialog, with "Export as Patch" disabled, and PCK is selected as a file type.
</description>
</method>
<method name="_export_pack_patch" qualifiers="virtual">
<return type="int" enum="Error" />
<param index="0" name="preset" type="EditorExportPreset" />
<param index="1" name="debug" type="bool" />
<param index="2" name="path" type="String" />
<param index="3" name="patches" type="PackedStringArray" />
<param index="4" name="flags" type="int" enum="EditorExportPlatform.DebugFlags" is_bitfield="true" />
<description>
[b]Optional.[/b]
Creates a patch PCK archive at [param path] for the specified [param preset], containing only the files that have changed since the last patch.
This method is called when "Export PCK/ZIP" button is pressed in the export dialog, with "Export as Patch" enabled, and PCK is selected as a file type.
[b]Note:[/b] The patches provided in [param patches] have already been loaded when this method is called and are merely provided as context. When empty the patches defined in the export preset have been loaded instead.
</description>
</method>
<method name="_export_project" qualifiers="virtual">
<return type="int" enum="Error" />
<param index="0" name="preset" type="EditorExportPreset" />
<param index="1" name="debug" type="bool" />
<param index="2" name="path" type="String" />
<param index="3" name="flags" type="int" enum="EditorExportPlatform.DebugFlags" is_bitfield="true" />
<description>
[b]Required.[/b]
Creates a full project at [param path] for the specified [param preset].
This method is called when "Export" button is pressed in the export dialog.
This method implementation can call [method EditorExportPlatform.save_pack] or [method EditorExportPlatform.save_zip] to use default PCK/ZIP export process, or calls [method EditorExportPlatform.export_project_files] and implement custom callback for processing each exported file.
</description>
</method>
<method name="_export_zip" qualifiers="virtual">
<return type="int" enum="Error" />
<param index="0" name="preset" type="EditorExportPreset" />
<param index="1" name="debug" type="bool" />
<param index="2" name="path" type="String" />
<param index="3" name="flags" type="int" enum="EditorExportPlatform.DebugFlags" is_bitfield="true" />
<description>
[b]Optional.[/b]
Create a ZIP archive at [param path] for the specified [param preset].
This method is called when "Export PCK/ZIP" button is pressed in the export dialog, with "Export as Patch" disabled, and ZIP is selected as a file type.
</description>
</method>
<method name="_export_zip_patch" qualifiers="virtual">
<return type="int" enum="Error" />
<param index="0" name="preset" type="EditorExportPreset" />
<param index="1" name="debug" type="bool" />
<param index="2" name="path" type="String" />
<param index="3" name="patches" type="PackedStringArray" />
<param index="4" name="flags" type="int" enum="EditorExportPlatform.DebugFlags" is_bitfield="true" />
<description>
[b]Optional.[/b]
Create a ZIP archive at [param path] for the specified [param preset], containing only the files that have changed since the last patch.
This method is called when "Export PCK/ZIP" button is pressed in the export dialog, with "Export as Patch" enabled, and ZIP is selected as a file type.
[b]Note:[/b] The patches provided in [param patches] have already been loaded when this method is called and are merely provided as context. When empty the patches defined in the export preset have been loaded instead.
</description>
</method>
<method name="_get_binary_extensions" qualifiers="virtual const">
<return type="PackedStringArray" />
<param index="0" name="preset" type="EditorExportPreset" />
<description>
[b]Required.[/b]
Returns array of supported binary extensions for the full project export.
</description>
</method>
<method name="_get_debug_protocol" qualifiers="virtual const">
<return type="String" />
<description>
[b]Optional.[/b]
Returns protocol used for remote debugging. Default implementation return [code]tcp://[/code].
</description>
</method>
<method name="_get_device_architecture" qualifiers="virtual const">
<return type="String" />
<param index="0" name="device" type="int" />
<description>
[b]Optional.[/b]
Returns device architecture for one-click deploy.
</description>
</method>
<method name="_get_export_option_visibility" qualifiers="virtual const">
<return type="bool" />
<param index="0" name="preset" type="EditorExportPreset" />
<param index="1" name="option" type="String" />
<description>
[b]Optional.[/b]
Validates [param option] and returns visibility for the specified [param preset]. Default implementation return [code]true[/code] for all options.
</description>
</method>
<method name="_get_export_option_warning" qualifiers="virtual const">
<return type="String" />
<param index="0" name="preset" type="EditorExportPreset" />
<param index="1" name="option" type="StringName" />
<description>
[b]Optional.[/b]
Validates [param option] and returns warning message for the specified [param preset]. Default implementation return empty string for all options.
</description>
</method>
<method name="_get_export_options" qualifiers="virtual const">
<return type="Dictionary[]" />
<description>
[b]Optional.[/b]
Returns a property list, as an [Array] of dictionaries. Each [Dictionary] must at least contain the [code]name: StringName[/code] and [code]type: Variant.Type[/code] entries.
Additionally, the following keys are supported:
- [code]hint: PropertyHint[/code]
- [code]hint_string: String[/code]
- [code]usage: PropertyUsageFlags[/code]
- [code]class_name: StringName[/code]
- [code]default_value: Variant[/code], default value of the property.
- [code]update_visibility: bool[/code], if set to [code]true[/code], [method _get_export_option_visibility] is called for each property when this property is changed.
- [code]required: bool[/code], if set to [code]true[/code], this property warnings are critical, and should be resolved to make export possible. This value is a hint for the [method _has_valid_export_configuration] implementation, and not used by the engine directly.
See also [method Object._get_property_list].
</description>
</method>
<method name="_get_logo" qualifiers="virtual const">
<return type="Texture2D" />
<description>
[b]Required.[/b]
Returns platform logo displayed in the export dialog, logo should be 32x32 adjusted to the current editor scale, see [method EditorInterface.get_editor_scale].
</description>
</method>
<method name="_get_name" qualifiers="virtual const">
<return type="String" />
<description>
[b]Required.[/b]
Returns export platform name.
</description>
</method>
<method name="_get_option_icon" qualifiers="virtual const">
<return type="ImageTexture" />
<param index="0" name="device" type="int" />
<description>
[b]Optional.[/b]
Returns one-click deploy menu item icon for the specified [param device], icon should be 16x16 adjusted to the current editor scale, see [method EditorInterface.get_editor_scale].
</description>
</method>
<method name="_get_option_label" qualifiers="virtual const">
<return type="String" />
<param index="0" name="device" type="int" />
<description>
[b]Optional.[/b]
Returns one-click deploy menu item label for the specified [param device].
</description>
</method>
<method name="_get_option_tooltip" qualifiers="virtual const">
<return type="String" />
<param index="0" name="device" type="int" />
<description>
[b]Optional.[/b]
Returns one-click deploy menu item tooltip for the specified [param device].
</description>
</method>
<method name="_get_options_count" qualifiers="virtual const">
<return type="int" />
<description>
[b]Optional.[/b]
Returns number one-click deploy devices (or other one-click option displayed in the menu).
</description>
</method>
<method name="_get_options_tooltip" qualifiers="virtual const">
<return type="String" />
<description>
[b]Optional.[/b]
Returns tooltip of the one-click deploy menu button.
</description>
</method>
<method name="_get_os_name" qualifiers="virtual const">
<return type="String" />
<description>
[b]Required.[/b]
Returns target OS name.
</description>
</method>
<method name="_get_platform_features" qualifiers="virtual const">
<return type="PackedStringArray" />
<description>
[b]Required.[/b]
Returns array of platform specific features.
</description>
</method>
<method name="_get_preset_features" qualifiers="virtual const">
<return type="PackedStringArray" />
<param index="0" name="preset" type="EditorExportPreset" />
<description>
[b]Required.[/b]
Returns array of platform specific features for the specified [param preset].
</description>
</method>
<method name="_get_run_icon" qualifiers="virtual const">
<return type="Texture2D" />
<description>
[b]Optional.[/b]
Returns icon of the one-click deploy menu button, icon should be 16x16 adjusted to the current editor scale, see [method EditorInterface.get_editor_scale].
</description>
</method>
<method name="_has_valid_export_configuration" qualifiers="virtual const">
<return type="bool" />
<param index="0" name="preset" type="EditorExportPreset" />
<param index="1" name="debug" type="bool" />
<description>
[b]Required.[/b]
Returns [code]true[/code] if export configuration is valid.
</description>
</method>
<method name="_has_valid_project_configuration" qualifiers="virtual const">
<return type="bool" />
<param index="0" name="preset" type="EditorExportPreset" />
<description>
[b]Required.[/b]
Returns [code]true[/code] if project configuration is valid.
</description>
</method>
<method name="_is_executable" qualifiers="virtual const">
<return type="bool" />
<param index="0" name="path" type="String" />
<description>
[b]Optional.[/b]
Returns [code]true[/code] if specified file is a valid executable (native executable or script) for the target platform.
</description>
</method>
<method name="_poll_export" qualifiers="virtual">
<return type="bool" />
<description>
[b]Optional.[/b]
Returns [code]true[/code] if one-click deploy options are changed and editor interface should be updated.
</description>
</method>
<method name="_run" qualifiers="virtual">
<return type="int" enum="Error" />
<param index="0" name="preset" type="EditorExportPreset" />
<param index="1" name="device" type="int" />
<param index="2" name="debug_flags" type="int" enum="EditorExportPlatform.DebugFlags" is_bitfield="true" />
<description>
[b]Optional.[/b]
This method is called when [param device] one-click deploy menu option is selected.
Implementation should export project to a temporary location, upload and run it on the specific [param device], or perform another action associated with the menu item.
</description>
</method>
<method name="_should_update_export_options" qualifiers="virtual">
<return type="bool" />
<description>
[b]Optional.[/b]
Returns [code]true[/code] if export options list is changed and presets should be updated.
</description>
</method>
<method name="get_config_error" qualifiers="const">
<return type="String" />
<description>
Returns current configuration error message text. This method should be called only from the [method _can_export], [method _has_valid_export_configuration], or [method _has_valid_project_configuration] implementations.
</description>
</method>
<method name="get_config_missing_templates" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] is export templates are missing from the current configuration. This method should be called only from the [method _can_export], [method _has_valid_export_configuration], or [method _has_valid_project_configuration] implementations.
</description>
</method>
<method name="set_config_error" qualifiers="const">
<return type="void" />
<param index="0" name="error_text" type="String" />
<description>
Sets current configuration error message text. This method should be called only from the [method _can_export], [method _has_valid_export_configuration], or [method _has_valid_project_configuration] implementations.
</description>
</method>
<method name="set_config_missing_templates" qualifiers="const">
<return type="void" />
<param index="0" name="missing_templates" type="bool" />
<description>
Set to [code]true[/code] is export templates are missing from the current configuration. This method should be called only from the [method _can_export], [method _has_valid_export_configuration], or [method _has_valid_project_configuration] implementations.
</description>
</method>
</methods>
</class>

33
engine/doc/classes/EditorExportPlugin.xml
View file

@ -27,6 +27,7 @@
<description>
Return [code]true[/code] if this plugin will customize scenes based on the platform and features used.
When enabled, [method _get_customization_configuration_hash] and [method _customize_scene] will be called and must be implemented.
[b]Note:[/b] [method _customize_scene] will only be called for scenes that have been modified since the last export.
</description>
</method>
<method name="_customize_resource" qualifiers="virtual">
@ -34,9 +35,16 @@
<param index="0" name="resource" type="Resource" />
<param index="1" name="path" type="String" />
<description>
Customize a resource. If changes are made to it, return the same or a new resource. Otherwise, return [code]null[/code].
The [i]path[/i] argument is only used when customizing an actual file, otherwise this means that this resource is part of another one and it will be empty.
Customize a resource. If changes are made to it, return the same or a new resource. Otherwise, return [code]null[/code]. When a new resource is returned, [param resource] will be replaced by a copy of the new resource.
The [param path] argument is only used when customizing an actual file, otherwise this means that this resource is part of another one and it will be empty.
Implementing this method is required if [method _begin_customize_resources] returns [code]true[/code].
[b]Note:[/b] When customizing any of the following types and returning another resource, the other resource should not be skipped using [method skip] in [method _export_file]:
- [AtlasTexture]
- [CompressedCubemap]
- [CompressedCubemapArray]
- [CompressedTexture2D]
- [CompressedTexture2DArray]
- [CompressedTexture3D]
</description>
</method>
<method name="_customize_scene" qualifiers="virtual">
@ -159,6 +167,15 @@
Return a [PackedStringArray] of additional features this preset, for the given [param platform], should have.
</description>
</method>
<method name="_get_export_option_visibility" qualifiers="virtual const">
<return type="bool" />
<param index="0" name="platform" type="EditorExportPlatform" />
<param index="1" name="option" type="String" />
<description>
[b]Optional.[/b]
Validates [param option] and returns the visibility for the specified [param platform]. The default implementation returns [code]true[/code] for all options.
</description>
</method>
<method name="_get_export_option_warning" qualifiers="virtual const">
<return type="String" />
<param index="0" name="platform" type="EditorExportPlatform" />
@ -305,6 +322,18 @@
In case of a directory code-sign will error if you place non code object in directory.
</description>
</method>
<method name="get_export_platform" qualifiers="const">
<return type="EditorExportPlatform" />
<description>
Returns currently used export platform.
</description>
</method>
<method name="get_export_preset" qualifiers="const">
<return type="EditorExportPreset" />
<description>
Returns currently used export preset.
</description>
</method>
<method name="get_option" qualifiers="const">
<return type="Variant" />
<param index="0" name="name" type="StringName" />

192
engine/doc/classes/EditorExportPreset.xml Normal file
View file

@ -0,0 +1,192 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="EditorExportPreset" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Export preset configuration.
</brief_description>
<description>
Export preset configuration. Instances of [EditorExportPreset] by editor UI and intended to be used a read-only configuration passed to the [EditorExportPlatform] methods when exporting the project.
</description>
<tutorials>
</tutorials>
<methods>
<method name="are_advanced_options_enabled" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code], is "Advanced" toggle is enabled in the export dialog.
</description>
</method>
<method name="get_custom_features" qualifiers="const">
<return type="String" />
<description>
Returns string with a comma separated list of custom features.
</description>
</method>
<method name="get_customized_files" qualifiers="const">
<return type="Dictionary" />
<description>
Returns [Dictionary] of files selected in the "Resources" tab of the export dialog. Dictionary keys are file names and values are export mode - [code]"strip[/code], [code]"keep"[/code], or [code]"remove"[/code]. See also [method get_file_export_mode].
</description>
</method>
<method name="get_customized_files_count" qualifiers="const">
<return type="int" />
<description>
Returns number of files selected in the "Resources" tab of the export dialog.
</description>
</method>
<method name="get_encrypt_directory" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code], PCK directory encryption is enabled in the export dialog.
</description>
</method>
<method name="get_encrypt_pck" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code], PCK encryption is enabled in the export dialog.
</description>
</method>
<method name="get_encryption_ex_filter" qualifiers="const">
<return type="String" />
<description>
Returns file filters to exclude during PCK encryption.
</description>
</method>
<method name="get_encryption_in_filter" qualifiers="const">
<return type="String" />
<description>
Returns file filters to include during PCK encryption.
</description>
</method>
<method name="get_encryption_key" qualifiers="const">
<return type="String" />
<description>
Returns PCK encryption key.
</description>
</method>
<method name="get_exclude_filter" qualifiers="const">
<return type="String" />
<description>
Returns file filters to exclude during export.
</description>
</method>
<method name="get_export_filter" qualifiers="const">
<return type="int" enum="EditorExportPreset.ExportFilter" />
<description>
Returns export file filter mode selected in the "Resources" tab of the export dialog.
</description>
</method>
<method name="get_export_path" qualifiers="const">
<return type="String" />
<description>
Returns export target path.
</description>
</method>
<method name="get_file_export_mode" qualifiers="const">
<return type="int" enum="EditorExportPreset.FileExportMode" />
<param index="0" name="path" type="String" />
<param index="1" name="default" type="int" enum="EditorExportPreset.FileExportMode" default="0" />
<description>
Returns file export mode for the specified file.
</description>
</method>
<method name="get_files_to_export" qualifiers="const">
<return type="PackedStringArray" />
<description>
Returns array of files to export.
</description>
</method>
<method name="get_include_filter" qualifiers="const">
<return type="String" />
<description>
Returns file filters to include during export.
</description>
</method>
<method name="get_or_env" qualifiers="const">
<return type="Variant" />
<param index="0" name="name" type="StringName" />
<param index="1" name="env_var" type="String" />
<description>
Returns export option value or value of environment variable if it is set.
</description>
</method>
<method name="get_patches" qualifiers="const">
<return type="PackedStringArray" />
<description>
Returns the list of packs on which to base a patch export on.
</description>
</method>
<method name="get_preset_name" qualifiers="const">
<return type="String" />
<description>
Returns export preset name.
</description>
</method>
<method name="get_script_export_mode" qualifiers="const">
<return type="int" />
<description>
Returns script export mode.
</description>
</method>
<method name="get_version" qualifiers="const">
<return type="String" />
<param index="0" name="name" type="StringName" />
<param index="1" name="windows_version" type="bool" />
<description>
Returns the preset's version number, or fall back to the [member ProjectSettings.application/config/version] project setting if set to an empty string.
If [param windows_version] is [code]true[/code], formats the returned version number to be compatible with Windows executable metadata.
</description>
</method>
<method name="has" qualifiers="const">
<return type="bool" />
<param index="0" name="property" type="StringName" />
<description>
Returns [code]true[/code] if preset has specified property.
</description>
</method>
<method name="has_export_file">
<return type="bool" />
<param index="0" name="path" type="String" />
<description>
Returns [code]true[/code] if specified file is exported.
</description>
</method>
<method name="is_dedicated_server" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if dedicated server export mode is selected in the export dialog.
</description>
</method>
<method name="is_runnable" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if "Runnable" toggle is enabled in the export dialog.
</description>
</method>
</methods>
<constants>
<constant name="EXPORT_ALL_RESOURCES" value="0" enum="ExportFilter">
</constant>
<constant name="EXPORT_SELECTED_SCENES" value="1" enum="ExportFilter">
</constant>
<constant name="EXPORT_SELECTED_RESOURCES" value="2" enum="ExportFilter">
</constant>
<constant name="EXCLUDE_SELECTED_RESOURCES" value="3" enum="ExportFilter">
</constant>
<constant name="EXPORT_CUSTOMIZED" value="4" enum="ExportFilter">
</constant>
<constant name="MODE_FILE_NOT_CUSTOMIZED" value="0" enum="FileExportMode">
</constant>
<constant name="MODE_FILE_STRIP" value="1" enum="FileExportMode">
</constant>
<constant name="MODE_FILE_KEEP" value="2" enum="FileExportMode">
</constant>
<constant name="MODE_FILE_REMOVE" value="3" enum="FileExportMode">
</constant>
<constant name="MODE_SCRIPT_TEXT" value="0" enum="ScriptExportMode">
</constant>
<constant name="MODE_SCRIPT_BINARY_TOKENS" value="1" enum="ScriptExportMode">
</constant>
<constant name="MODE_SCRIPT_BINARY_TOKENS_COMPRESSED" value="2" enum="ScriptExportMode">
</constant>
</constants>
</class>

5
engine/doc/classes/EditorFeatureProfile.xml
View file

@ -121,7 +121,10 @@
<constant name="FEATURE_HISTORY_DOCK" value="7" enum="Feature">
The History dock. If this feature is disabled, the History dock won't be visible.
</constant>
<constant name="FEATURE_MAX" value="8" enum="Feature">
<constant name="FEATURE_GAME" value="8" enum="Feature">
The Game tab, which allows embedding the game window and selecting nodes by clicking inside of it. If this feature is disabled, the Game tab won't display.
</constant>
<constant name="FEATURE_MAX" value="9" enum="Feature">
Represents the size of the [enum Feature] enum.
</constant>
</constants>

28
engine/doc/classes/EditorFileDialog.xml
View file

@ -5,6 +5,7 @@
</brief_description>
<description>
[EditorFileDialog] is an enhanced version of [FileDialog] available only to editor plugins. Additional features include list of favorited/recent files and the ability to see files as thumbnails grid instead of list.
Unlike [FileDialog], [EditorFileDialog] does not have a property for using native dialogs. Instead, native dialogs can be enabled globally via the [member EditorSettings.interface/editor/use_native_file_dialogs] editor setting. They are also enabled automatically when running in sandbox (e.g. on macOS).
</description>
<tutorials>
</tutorials>
@ -37,10 +38,22 @@
Adds the given [param menu] to the side of the file dialog with the given [param title] text on top. Only one side menu is allowed.
</description>
</method>
<method name="clear_filename_filter">
<return type="void" />
<description>
Clear the filter for file names.
</description>
</method>
<method name="clear_filters">
<return type="void" />
<description>
Removes all filters except for "All Files (*)".
Removes all filters except for "All Files (*.*)".
</description>
</method>
<method name="get_filename_filter" qualifiers="const">
<return type="String" />
<description>
Returns the value of the filter for file names.
</description>
</method>
<method name="get_line_edit">
@ -96,6 +109,13 @@
Shows the [EditorFileDialog] at the default size and position for file dialogs in the editor, and selects the file name if there is a current file.
</description>
</method>
<method name="set_filename_filter">
<return type="void" />
<param index="0" name="filter" type="String" />
<description>
Sets the value of the filter for file names.
</description>
</method>
<method name="set_option_default">
<return type="void" />
<param index="0" name="option" type="int" />
@ -168,6 +188,12 @@
Emitted when a file is selected.
</description>
</signal>
<signal name="filename_filter_changed">
<param index="0" name="filter" type="String" />
<description>
Emitted when the filter for file names changes.
</description>
</signal>
<signal name="files_selected">
<param index="0" name="paths" type="PackedStringArray" />
<description>

2
engine/doc/classes/EditorFileSystemImportFormatSupportQuery.xml
View file

@ -24,7 +24,7 @@
<method name="_query" qualifiers="virtual const">
<return type="bool" />
<description>
Query support. Return false if import must not continue.
Query support. Return [code]false[/code] if import must not continue.
</description>
</method>
</methods>

21
engine/doc/classes/EditorImportPlugin.xml
View file

@ -63,7 +63,7 @@
public override string[] _GetRecognizedExtensions()
{
return new string[] { "special", "spec" };
return ["special", "spec"];
}
public override string _GetSaveExtension()
@ -88,14 +88,14 @@
public override Godot.Collections.Array&lt;Godot.Collections.Dictionary&gt; _GetImportOptions(string path, int presetIndex)
{
return new Godot.Collections.Array&lt;Godot.Collections.Dictionary&gt;
{
return
[
new Godot.Collections.Dictionary
{
{ "name", "myOption" },
{ "default_value", false },
}
};
},
];
}
public override Error _Import(string sourceFile, string savePath, Godot.Collections.Dictionary options, Godot.Collections.Array&lt;string&gt; platformVariants, Godot.Collections.Array&lt;string&gt; genFiles)
@ -124,7 +124,14 @@
<return type="bool" />
<description>
Tells whether this importer can be run in parallel on threads, or, on the contrary, it's only safe for the editor to call it from the main thread, for one file at a time.
If this method is not overridden, it will return [code]true[/code] by default (i.e., safe for parallel importing).
If this method is not overridden, it will return [code]false[/code] by default.
If this importer's implementation is thread-safe and can be run in parallel, override this with [code]true[/code] to optimize for concurrency.
</description>
</method>
<method name="_get_format_version" qualifiers="virtual const">
<return type="int" />
<description>
Gets the format version of this importer. Increment this version when making incompatible changes to the format of the imported resources.
</description>
</method>
<method name="_get_import_options" qualifiers="virtual const">
@ -153,7 +160,7 @@
<param index="1" name="option_name" type="StringName" />
<param index="2" name="options" type="Dictionary" />
<description>
This method can be overridden to hide specific import options if conditions are met. This is mainly useful for hiding options that depend on others if one of them is disabled. For example:
This method can be overridden to hide specific import options if conditions are met. This is mainly useful for hiding options that depend on others if one of them is disabled.
[codeblocks]
[gdscript]
func _get_option_visibility(option, options):

23
engine/doc/classes/EditorInspector.xml
View file

@ -14,6 +14,14 @@
<tutorials>
</tutorials>
<methods>
<method name="edit">
<return type="void" />
<param index="0" name="object" type="Object" />
<description>
Shows the properties of the given [param object] in this inspector for editing. To clear the inspector, call this method with [code]null[/code].
[b]Note:[/b] If you want to edit an object in the editor's main inspector, use the [code]edit_*[/code] methods in [EditorInterface] instead.
</description>
</method>
<method name="get_edited_object">
<return type="Object" />
<description>
@ -26,8 +34,23 @@
Gets the path of the currently selected property.
</description>
</method>
<method name="instantiate_property_editor" qualifiers="static">
<return type="EditorProperty" />
<param index="0" name="object" type="Object" />
<param index="1" name="type" type="int" enum="Variant.Type" />
<param index="2" name="path" type="String" />
<param index="3" name="hint" type="int" enum="PropertyHint" />
<param index="4" name="hint_text" type="String" />
<param index="5" name="usage" type="int" />
<param index="6" name="wide" type="bool" default="false" />
<description>
Creates a property editor that can be used by plugin UI to edit the specified property of an [param object].
</description>
</method>
</methods>
<members>
<member name="draw_focus_border" type="bool" setter="set_draw_focus_border" getter="get_draw_focus_border" overrides="ScrollContainer" default="true" />
<member name="focus_mode" type="int" setter="set_focus_mode" getter="get_focus_mode" overrides="Control" enum="Control.FocusMode" default="2" />
<member name="horizontal_scroll_mode" type="int" setter="set_horizontal_scroll_mode" getter="get_horizontal_scroll_mode" overrides="ScrollContainer" enum="ScrollContainer.ScrollMode" default="0" />
</members>
<signals>

58
engine/doc/classes/EditorInterface.xml
View file

@ -117,6 +117,18 @@
[b]Note:[/b] When creating custom editor UI, prefer accessing theme items directly from your GUI nodes using the [code]get_theme_*[/code] methods.
</description>
</method>
<method name="get_editor_toaster" qualifiers="const">
<return type="EditorToaster" />
<description>
Returns the editor's [EditorToaster].
</description>
</method>
<method name="get_editor_undo_redo" qualifiers="const">
<return type="EditorUndoRedoManager" />
<description>
Returns the editor's [EditorUndoRedoManager].
</description>
</method>
<method name="get_editor_viewport_2d" qualifiers="const">
<return type="SubViewport" />
<description>
@ -235,8 +247,9 @@
<method name="open_scene_from_path">
<return type="void" />
<param index="0" name="scene_filepath" type="String" />
<param index="1" name="set_inherited" type="bool" default="false" />
<description>
Opens the scene at the given path.
Opens the scene at the given path. If [param set_inherited] is [code]true[/code], creates a new inherited scene.
</description>
</method>
<method name="play_current_scene">
@ -258,6 +271,23 @@
Plays the main scene.
</description>
</method>
<method name="popup_create_dialog" experimental="">
<return type="void" />
<param index="0" name="callback" type="Callable" />
<param index="1" name="base_type" type="StringName" default="&quot;&quot;" />
<param index="2" name="current_type" type="String" default="&quot;&quot;" />
<param index="3" name="dialog_title" type="String" default="&quot;&quot;" />
<param index="4" name="type_blocklist" type="StringName[]" default="[]" />
<description>
Pops up an editor dialog for creating an object.
The [param callback] must take a single argument of type [StringName] which will contain the type name of the selected object or be empty if no item is selected.
The [param base_type] specifies the base type of objects to display. For example, if you set this to "Resource", all types derived from [Resource] will display in the create dialog.
The [param current_type] will be passed in the search box of the create dialog, and the specified type can be immediately selected when the dialog pops up. If the [param current_type] is not derived from [param base_type], there will be no result of the type in the dialog.
The [param dialog_title] allows you to define a custom title for the dialog. This is useful if you want to accurately hint the usage of the dialog. If the [param dialog_title] is an empty string, the dialog will use "Create New 'Base Type'" as the default title.
The [param type_blocklist] contains a list of type names, and the types in the blocklist will be hidden from the create dialog.
[b]Note:[/b] Trying to list the base type in the [param type_blocklist] will hide all types derived from the base type from the create dialog.
</description>
</method>
<method name="popup_dialog">
<return type="void" />
<param index="0" name="dialog" type="Window" />
@ -295,13 +325,23 @@
See also [method Window.set_unparent_when_invisible].
</description>
</method>
<method name="popup_method_selector">
<return type="void" />
<param index="0" name="object" type="Object" />
<param index="1" name="callback" type="Callable" />
<param index="2" name="current_value" type="String" default="&quot;&quot;" />
<description>
Pops up an editor dialog for selecting a method from [param object]. The [param callback] must take a single argument of type [String] which will contain the name of the selected method or be empty if the dialog is canceled. If [param current_value] is provided, the method will be selected automatically in the method list, if it exists.
</description>
</method>
<method name="popup_node_selector">
<return type="void" />
<param index="0" name="callback" type="Callable" />
<param index="1" name="valid_types" type="StringName[]" default="[]" />
<param index="2" name="current_value" type="Node" default="null" />
<description>
Pops up an editor dialog for selecting a [Node] from the edited scene. The [param callback] must take a single argument of type [NodePath]. It is called on the selected [NodePath] or the empty path [code]^""[/code] if the dialog is canceled. If [param valid_types] is provided, the dialog will only show Nodes that match one of the listed Node types.
[b]Example:[/b]
Pops up an editor dialog for selecting a [Node] from the edited scene. The [param callback] must take a single argument of type [NodePath]. It is called on the selected [NodePath] or the empty path [code]^""[/code] if the dialog is canceled. If [param valid_types] is provided, the dialog will only show Nodes that match one of the listed Node types. If [param current_value] is provided, the Node will be automatically selected in the tree, if it exists.
[b]Example:[/b] Display the node selection dialog as soon as this node is added to the tree for the first time:
[codeblock]
func _ready():
if Engine.is_editor_hint():
@ -320,9 +360,9 @@
<param index="0" name="object" type="Object" />
<param index="1" name="callback" type="Callable" />
<param index="2" name="type_filter" type="PackedInt32Array" default="PackedInt32Array()" />
<param index="3" name="current_value" type="String" default="&quot;&quot;" />
<description>
Pops up an editor dialog for selecting properties from [param object]. The [param callback] must take a single argument of type [NodePath]. It is called on the selected property path (see [method NodePath.get_as_property_path]) or the empty path [code]^""[/code] if the dialog is canceled. If [param type_filter] is provided, the dialog will only show properties that match one of the listed [enum Variant.Type] values.
[b]Example:[/b]
Pops up an editor dialog for selecting properties from [param object]. The [param callback] must take a single argument of type [NodePath]. It is called on the selected property path (see [method NodePath.get_as_property_path]) or the empty path [code]^""[/code] if the dialog is canceled. If [param type_filter] is provided, the dialog will only show properties that match one of the listed [enum Variant.Type] values. If [param current_value] is provided, the property will be selected automatically in the property list, if it exists.
[codeblock]
func _ready():
if Engine.is_editor_hint():
@ -336,6 +376,14 @@
[/codeblock]
</description>
</method>
<method name="popup_quick_open">
<return type="void" />
<param index="0" name="callback" type="Callable" />
<param index="1" name="base_types" type="StringName[]" default="[]" />
<description>
Pops up an editor dialog for quick selecting a resource file. The [param callback] must take a single argument of type [String] which will contain the path of the selected resource or be empty if the dialog is canceled. If [param base_types] is provided, the dialog will only show resources that match these types. Only types deriving from [Resource] are supported.
</description>
</method>
<method name="reload_scene_from_path">
<return type="void" />
<param index="0" name="scene_filepath" type="String" />

2
engine/doc/classes/EditorNode3DGizmoPlugin.xml
View file

@ -54,7 +54,7 @@
<return type="EditorNode3DGizmo" />
<param index="0" name="for_node_3d" type="Node3D" />
<description>
Override this method to return a custom [EditorNode3DGizmo] for the spatial nodes of your choice, return [code]null[/code] for the rest of nodes. See also [method _has_gizmo].
Override this method to return a custom [EditorNode3DGizmo] for the 3D nodes of your choice, return [code]null[/code] for the rest of nodes. See also [method _has_gizmo].
</description>
</method>
<method name="_get_gizmo_name" qualifiers="virtual const">

44
engine/doc/classes/EditorPlugin.xml
View file

@ -104,7 +104,6 @@
<param index="1" name="event" type="InputEvent" />
<description>
Called when there is a root node in the current edited scene, [method _handles] is implemented, and an [InputEvent] happens in the 3D viewport. The return value decides whether the [InputEvent] is consumed or forwarded to other [EditorPlugin]s. See [enum AfterGUIInput] for options.
[b]Example:[/b]
[codeblocks]
[gdscript]
# Prevents the InputEvent from reaching other Editor classes.
@ -119,8 +118,7 @@
}
[/csharp]
[/codeblocks]
Must [code]return EditorPlugin.AFTER_GUI_INPUT_PASS[/code] in order to forward the [InputEvent] to other Editor classes.
[b]Example:[/b]
This method must return [constant AFTER_GUI_INPUT_PASS] in order to forward the [InputEvent] to other Editor classes.
[codeblocks]
[gdscript]
# Consumes InputEventMouseMotion and forwards other InputEvent types.
@ -188,8 +186,7 @@
<return type="bool" />
<param index="0" name="event" type="InputEvent" />
<description>
Called when there is a root node in the current edited scene, [method _handles] is implemented and an [InputEvent] happens in the 2D viewport. Intercepts the [InputEvent], if [code]return true[/code] [EditorPlugin] consumes the [param event], otherwise forwards [param event] to other Editor classes.
[b]Example:[/b]
Called when there is a root node in the current edited scene, [method _handles] is implemented, and an [InputEvent] happens in the 2D viewport. If this method returns [code]true[/code], [param event] is intercepted by this [EditorPlugin], otherwise [param event] is forwarded to other Editor classes.
[codeblocks]
[gdscript]
# Prevents the InputEvent from reaching other Editor classes.
@ -204,8 +201,7 @@
}
[/csharp]
[/codeblocks]
Must [code]return false[/code] in order to forward the [InputEvent] to other Editor classes.
[b]Example:[/b]
This method must return [code]false[/code] in order to forward the [InputEvent] to other Editor classes.
[codeblocks]
[gdscript]
# Consumes InputEventMouseMotion and forwards other InputEvent types.
@ -405,13 +401,22 @@
Adds a script at [param path] to the Autoload list as [param name].
</description>
</method>
<method name="add_context_menu_plugin">
<return type="void" />
<param index="0" name="slot" type="int" enum="EditorContextMenuPlugin.ContextMenuSlot" />
<param index="1" name="plugin" type="EditorContextMenuPlugin" />
<description>
Adds a plugin to the context menu. [param slot] is the context menu where the plugin will be added.
See [enum EditorContextMenuPlugin.ContextMenuSlot] for available context menus. A plugin instance can belong only to a single context menu slot.
</description>
</method>
<method name="add_control_to_bottom_panel">
<return type="Button" />
<param index="0" name="control" type="Control" />
<param index="1" name="title" type="String" />
<param index="2" name="shortcut" type="Shortcut" default="null" />
<description>
Adds a control to the bottom panel (together with Output, Debug, Animation, etc). Returns a reference to the button added. It's up to you to hide/show the button when needed. When your plugin is deactivated, make sure to remove your custom control with [method remove_control_from_bottom_panel] and free it with [method Node.queue_free].
Adds a control to the bottom panel (together with Output, Debug, Animation, etc.). Returns a reference to the button added. It's up to you to hide/show the button when needed. When your plugin is deactivated, make sure to remove your custom control with [method remove_control_from_bottom_panel] and free it with [method Node.queue_free].
Optionally, you can specify a shortcut parameter. When pressed, this shortcut will toggle the bottom panel's visibility. See the default editor bottom panel shortcuts in the Editor Settings for inspiration. Per convention, they all use [kbd]Alt[/kbd] modifier.
</description>
</method>
@ -459,6 +464,13 @@
Adds a [Script] as debugger plugin to the Debugger. The script must extend [EditorDebuggerPlugin].
</description>
</method>
<method name="add_export_platform">
<return type="void" />
<param index="0" name="platform" type="EditorExportPlatform" />
<description>
Registers a new [EditorExportPlatform]. Export platforms provides functionality of exporting to the specific platform.
</description>
</method>
<method name="add_export_plugin">
<return type="void" />
<param index="0" name="plugin" type="EditorExportPlugin" />
@ -621,6 +633,13 @@
Removes an Autoload [param name] from the list.
</description>
</method>
<method name="remove_context_menu_plugin">
<return type="void" />
<param index="0" name="plugin" type="EditorContextMenuPlugin" />
<description>
Removes the specified context menu plugin.
</description>
</method>
<method name="remove_control_from_bottom_panel">
<return type="void" />
<param index="0" name="control" type="Control" />
@ -657,6 +676,13 @@
Removes the debugger plugin with given script from the Debugger.
</description>
</method>
<method name="remove_export_platform">
<return type="void" />
<param index="0" name="platform" type="EditorExportPlatform" />
<description>
Removes an export platform registered by [method add_export_platform].
</description>
</method>
<method name="remove_export_plugin">
<return type="void" />
<param index="0" name="plugin" type="EditorExportPlugin" />
@ -675,7 +701,7 @@
<return type="void" />
<param index="0" name="plugin" type="EditorInspectorPlugin" />
<description>
Removes an inspector plugin registered by [method add_import_plugin]
Removes an inspector plugin registered by [method add_inspector_plugin].
</description>
</method>
<method name="remove_node_3d_gizmo_plugin">

56
engine/doc/classes/EditorProperty.xml
View file

@ -29,6 +29,12 @@
If any of the controls added can gain keyboard focus, add it here. This ensures that focus will be restored if the inspector is refreshed.
</description>
</method>
<method name="deselect">
<return type="void" />
<description>
Draw property as not selected. Used by the inspector.
</description>
</method>
<method name="emit_changed">
<return type="void" />
<param index="0" name="property" type="StringName" />
@ -51,6 +57,19 @@
Gets the edited property. If your editor is for a single property (added via [method EditorInspectorPlugin._parse_property]), then this will return the property.
</description>
</method>
<method name="is_selected" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if property is drawn as selected. Used by the inspector.
</description>
</method>
<method name="select">
<return type="void" />
<param index="0" name="focusable" type="int" default="-1" />
<description>
Draw property as selected. Used by the inspector.
</description>
</method>
<method name="set_bottom_editor">
<return type="void" />
<param index="0" name="editor" type="Control" />
@ -58,6 +77,21 @@
Puts the [param editor] control below the property label. The control must be previously added using [method Node.add_child].
</description>
</method>
<method name="set_label_reference">
<return type="void" />
<param index="0" name="control" type="Control" />
<description>
Used by the inspector, set to a control that will be used as a reference to calculate the size of the label.
</description>
</method>
<method name="set_object_and_property">
<return type="void" />
<param index="0" name="object" type="Object" />
<param index="1" name="property" type="StringName" />
<description>
Assigns object and property to edit.
</description>
</method>
<method name="update_property">
<return type="void" />
<description>
@ -75,6 +109,12 @@
<member name="deletable" type="bool" setter="set_deletable" getter="is_deletable" default="false">
Used by the inspector, set to [code]true[/code] when the property can be deleted by the user.
</member>
<member name="draw_background" type="bool" setter="set_draw_background" getter="is_draw_background" default="true">
Used by the inspector, set to [code]true[/code] when the property label is drawn.
</member>
<member name="draw_label" type="bool" setter="set_draw_label" getter="is_draw_label" default="true">
Used by the inspector, set to [code]true[/code] when the property background is drawn.
</member>
<member name="draw_warning" type="bool" setter="set_draw_warning" getter="is_draw_warning" default="false">
Used by the inspector, set to [code]true[/code] when the property is drawn with the editor theme's warning color. This is used for editable children's properties.
</member>
@ -84,9 +124,18 @@
<member name="label" type="String" setter="set_label" getter="get_label" default="&quot;&quot;">
Set this property to change the label (if you want to show one).
</member>
<member name="name_split_ratio" type="float" setter="set_name_split_ratio" getter="get_name_split_ratio" default="0.5">
Space distribution ratio between the label and the editing field.
</member>
<member name="read_only" type="bool" setter="set_read_only" getter="is_read_only" default="false" keywords="enabled, disabled, editable">
Used by the inspector, set to [code]true[/code] when the property is read-only.
</member>
<member name="selectable" type="bool" setter="set_selectable" getter="is_selectable" default="true">
Used by the inspector, set to [code]true[/code] when the property is selectable.
</member>
<member name="use_folding" type="bool" setter="set_use_folding" getter="is_using_folding" default="false">
Used by the inspector, set to [code]true[/code] when the property is using folding.
</member>
</members>
<signals>
<signal name="multiple_properties_changed">
@ -132,6 +181,13 @@
Emitted when a property was deleted. Used internally.
</description>
</signal>
<signal name="property_favorited">
<param index="0" name="property" type="StringName" />
<param index="1" name="favorited" type="bool" />
<description>
Emit it if you want to mark a property as favorited, making it appear at the top of the inspector.
</description>
</signal>
<signal name="property_keyed">
<param index="0" name="property" type="StringName" />
<description>

Some files were not shown because too many files have changed in this diff Show more