noahbackus/godot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

initial commit, 4.5 stable
Some checks failed
🔗 GHA / 📊 Static checks (push) Has been cancelled
Details
🔗 GHA / 🤖 Android (push) Has been cancelled
Details
🔗 GHA / 🍏 iOS (push) Has been cancelled
Details
🔗 GHA / 🐧 Linux (push) Has been cancelled
Details
🔗 GHA / 🍎 macOS (push) Has been cancelled
Details
🔗 GHA / 🏁 Windows (push) Has been cancelled
Details
🔗 GHA / 🌐 Web (push) Has been cancelled
Details

Browse Source
This commit is contained in:
noahbackus
2025-09-16 20:46:46 -04:00
commit 9d30169a8d
13378 changed files with 7050105 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3293
doc/classes/@GlobalScope.xml Normal file
View File

File diff suppressed because it is too large Load Diff

385
doc/classes/AABB.xml Normal file
View File

@@ -0,0 +1,385 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AABB" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
A 3D axis-aligned bounding box.
</brief_description>
<description>
The [AABB] built-in [Variant] type represents an axis-aligned bounding box in a 3D space. It is defined by its [member position] and [member size], which are [Vector3]. It is frequently used for fast overlap tests (see [method intersects]). Although [AABB] itself is axis-aligned, it can be combined with [Transform3D] to represent a rotated or skewed bounding box.
It uses floating-point coordinates. The 2D counterpart to [AABB] is [Rect2]. There is no version of [AABB] that uses integer coordinates.
[b]Note:[/b] Negative values for [member size] are not supported. With negative size, most [AABB] methods do not work correctly. Use [method abs] to get an equivalent [AABB] with a non-negative size.
[b]Note:[/b] In a boolean context, an [AABB] evaluates to [code]false[/code] if both [member position] and [member size] are zero (equal to [constant Vector3.ZERO]). Otherwise, it always evaluates to [code]true[/code].
</description>
<tutorials>
<link title="Math documentation index">$DOCS_URL/tutorials/math/index.html</link>
<link title="Vector math">$DOCS_URL/tutorials/math/vector_math.html</link>
<link title="Advanced vector math">$DOCS_URL/tutorials/math/vectors_advanced.html</link>
</tutorials>
<constructors>
<constructor name="AABB">
<return type="AABB" />
<description>
Constructs an [AABB] with its [member position] and [member size] set to [constant Vector3.ZERO].
</description>
</constructor>
<constructor name="AABB">
<return type="AABB" />
<param index="0" name="from" type="AABB" />
<description>
Constructs an [AABB] as a copy of the given [AABB].
</description>
</constructor>
<constructor name="AABB">
<return type="AABB" />
<param index="0" name="position" type="Vector3" />
<param index="1" name="size" type="Vector3" />
<description>
Constructs an [AABB] by [param position] and [param size].
</description>
</constructor>
</constructors>
<methods>
<method name="abs" qualifiers="const">
<return type="AABB" />
<description>
Returns an [AABB] equivalent to this bounding box, with its width, height, and depth modified to be non-negative values.
[codeblocks]
[gdscript]
var box = AABB(Vector3(5, 0, 5), Vector3(-20, -10, -5))
var absolute = box.abs()
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));
var absolute = box.Abs();
GD.Print(absolute.Position); // Prints (-15, -10, 0)
GD.Print(absolute.Size); // Prints (20, 10, 5)
[/csharp]
[/codeblocks]
[b]Note:[/b] It's recommended to use this method when [member size] is negative, as most other methods in Godot assume that the [member size]'s components are greater than [code]0[/code].
</description>
</method>
<method name="encloses" qualifiers="const">
<return type="bool" />
<param index="0" name="with" type="AABB" />
<description>
Returns [code]true[/code] if this bounding box [i]completely[/i] encloses the [param with] box. The edges of both boxes are included.
[codeblocks]
[gdscript]
var a = AABB(Vector3(0, 0, 0), Vector3(4, 4, 4))
var b = AABB(Vector3(1, 1, 1), Vector3(3, 3, 3))
var c = AABB(Vector3(2, 2, 2), Vector3(8, 8, 8))
print(a.encloses(a)) # Prints true
print(a.encloses(b)) # Prints true
print(a.encloses(c)) # Prints false
[/gdscript]
[csharp]
var a = new Aabb(new Vector3(0, 0, 0), new Vector3(4, 4, 4));
var b = new Aabb(new Vector3(1, 1, 1), new Vector3(3, 3, 3));
var c = new Aabb(new Vector3(2, 2, 2), new Vector3(8, 8, 8));
GD.Print(a.Encloses(a)); // Prints True
GD.Print(a.Encloses(b)); // Prints True
GD.Print(a.Encloses(c)); // Prints False
[/csharp]
[/codeblocks]
</description>
</method>
<method name="expand" qualifiers="const">
<return type="AABB" />
<param index="0" name="to_point" type="Vector3" />
<description>
Returns a copy of this bounding box expanded to align the edges with the given [param to_point], if necessary.
[codeblocks]
[gdscript]
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.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.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));
box = box.Expand(new Vector3(10, 0, 0));
GD.Print(box.Position); // Prints (0, 0, 0)
GD.Print(box.Size); // Prints (10, 2, 5)
box = box.Expand(new Vector3(-5, 0, 5));
GD.Print(box.Position); // Prints (-5, 0, 0)
GD.Print(box.Size); // Prints (15, 2, 5)
[/csharp]
[/codeblocks]
</description>
</method>
<method name="get_center" qualifiers="const">
<return type="Vector3" />
<description>
Returns the center point of the bounding box. This is the same as [code]position + (size / 2.0)[/code].
</description>
</method>
<method name="get_endpoint" qualifiers="const">
<return type="Vector3" />
<param index="0" name="idx" type="int" />
<description>
Returns the position of one of the 8 vertices that compose this bounding box. With an [param idx] of [code]0[/code] this is the same as [member position], and an [param idx] of [code]7[/code] is the same as [member end].
</description>
</method>
<method name="get_longest_axis" qualifiers="const">
<return type="Vector3" />
<description>
Returns the longest normalized axis of this bounding box's [member size], as a [Vector3] ([constant Vector3.RIGHT], [constant Vector3.UP], or [constant Vector3.BACK]).
[codeblocks]
[gdscript]
var box = AABB(Vector3(0, 0, 0), Vector3(2, 4, 8))
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.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 Z
GD.Print(box.GetLongestAxisSize()); // Prints 8
[/csharp]
[/codeblocks]
See also [method get_longest_axis_index] and [method get_longest_axis_size].
</description>
</method>
<method name="get_longest_axis_index" qualifiers="const">
<return type="int" />
<description>
Returns the index to the longest axis of this bounding box's [member size] (see [constant Vector3.AXIS_X], [constant Vector3.AXIS_Y], and [constant Vector3.AXIS_Z]).
For an example, see [method get_longest_axis].
</description>
</method>
<method name="get_longest_axis_size" qualifiers="const">
<return type="float" />
<description>
Returns the longest dimension of this bounding box's [member size].
For an example, see [method get_longest_axis].
</description>
</method>
<method name="get_shortest_axis" qualifiers="const">
<return type="Vector3" />
<description>
Returns the shortest normalized axis of this bounding box's [member size], as a [Vector3] ([constant Vector3.RIGHT], [constant Vector3.UP], or [constant Vector3.BACK]).
[codeblocks]
[gdscript]
var box = AABB(Vector3(0, 0, 0), Vector3(2, 4, 8))
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.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 X
GD.Print(box.GetShortestAxisSize()); // Prints 2
[/csharp]
[/codeblocks]
See also [method get_shortest_axis_index] and [method get_shortest_axis_size].
</description>
</method>
<method name="get_shortest_axis_index" qualifiers="const">
<return type="int" />
<description>
Returns the index to the shortest axis of this bounding box's [member size] (see [constant Vector3.AXIS_X], [constant Vector3.AXIS_Y], and [constant Vector3.AXIS_Z]).
For an example, see [method get_shortest_axis].
</description>
</method>
<method name="get_shortest_axis_size" qualifiers="const">
<return type="float" />
<description>
Returns the shortest dimension of this bounding box's [member size].
For an example, see [method get_shortest_axis].
</description>
</method>
<method name="get_support" qualifiers="const">
<return 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>
</method>
<method name="get_volume" qualifiers="const">
<return type="float" />
<description>
Returns the bounding box's volume. This is equivalent to [code]size.x * size.y * size.z[/code]. See also [method has_volume].
</description>
</method>
<method name="grow" qualifiers="const">
<return type="AABB" />
<param index="0" name="by" type="float" />
<description>
Returns a copy of this bounding box extended on all sides by the given amount [param by]. A negative amount shrinks the box instead.
[codeblocks]
[gdscript]
var a = AABB(Vector3(4, 4, 4), Vector3(8, 8, 8)).grow(4)
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.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);
GD.Print(a.Position); // Prints (0, 0, 0)
GD.Print(a.Size); // Prints (16, 16, 16)
var b = new Aabb(new Vector3(0, 0, 0), new Vector3(8, 4, 2)).Grow(2);
GD.Print(b.Position); // Prints (-2, -2, -2)
GD.Print(b.Size); // Prints (12, 8, 6)
[/csharp]
[/codeblocks]
</description>
</method>
<method name="has_point" qualifiers="const">
<return type="bool" />
<param index="0" name="point" type="Vector3" />
<description>
Returns [code]true[/code] if the bounding box contains the given [param point]. By convention, points exactly on the right, top, and front sides are [b]not[/b] included.
[b]Note:[/b] This method is not reliable for [AABB] with a [i]negative[/i] [member size]. Use [method abs] first to get a valid bounding box.
</description>
</method>
<method name="has_surface" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if this bounding box has a surface or a length, that is, at least one component of [member size] is greater than [code]0[/code]. Otherwise, returns [code]false[/code].
</description>
</method>
<method name="has_volume" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if this bounding box's width, height, and depth are all positive. See also [method get_volume].
</description>
</method>
<method name="intersection" qualifiers="const">
<return type="AABB" />
<param index="0" name="with" type="AABB" />
<description>
Returns the intersection between this bounding box and [param with]. If the boxes do not intersect, returns an empty [AABB]. If the boxes intersect at the edge, returns a flat [AABB] with no volume (see [method has_surface] and [method has_volume]).
[codeblocks]
[gdscript]
var box1 = AABB(Vector3(0, 0, 0), Vector3(5, 2, 8))
var box2 = AABB(Vector3(2, 0, 2), Vector3(8, 4, 4))
var intersection = box1.intersection(box2)
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));
var box2 = new Aabb(new Vector3(2, 0, 2), new Vector3(8, 4, 4));
var intersection = box1.Intersection(box2);
GD.Print(intersection.Position); // Prints (2, 0, 2)
GD.Print(intersection.Size); // Prints (3, 2, 4)
[/csharp]
[/codeblocks]
[b]Note:[/b] If you only need to know whether two bounding boxes are intersecting, use [method intersects], instead.
</description>
</method>
<method name="intersects" qualifiers="const">
<return type="bool" />
<param index="0" name="with" type="AABB" />
<description>
Returns [code]true[/code] if this bounding box overlaps with the box [param with]. The edges of both boxes are [i]always[/i] excluded.
</description>
</method>
<method name="intersects_plane" qualifiers="const">
<return type="bool" />
<param index="0" name="plane" type="Plane" />
<description>
Returns [code]true[/code] if this bounding box is on both sides of the given [param plane].
</description>
</method>
<method name="intersects_ray" qualifiers="const">
<return type="Variant" />
<param index="0" name="from" type="Vector3" />
<param index="1" name="dir" type="Vector3" />
<description>
Returns the first point where this bounding box and the given ray intersect, as a [Vector3]. If no intersection occurs, returns [code]null[/code].
The ray begin at [param from], faces [param dir] and extends towards infinity.
</description>
</method>
<method name="intersects_segment" qualifiers="const">
<return type="Variant" />
<param index="0" name="from" type="Vector3" />
<param index="1" name="to" type="Vector3" />
<description>
Returns the first point where this bounding box and the given segment intersect, as a [Vector3]. If no intersection occurs, returns [code]null[/code].
The segment begins at [param from] and ends at [param to].
</description>
</method>
<method name="is_equal_approx" qualifiers="const">
<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 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 Vector3.is_finite] on the [member position] and the [member size].
</description>
</method>
<method name="merge" qualifiers="const">
<return type="AABB" />
<param index="0" name="with" type="AABB" />
<description>
Returns an [AABB] that encloses both this bounding box and [param with] around the edges. See also [method encloses].
</description>
</method>
</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 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 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-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>
<operator name="operator !=">
<return type="bool" />
<param index="0" name="right" type="AABB" />
<description>
Returns [code]true[/code] if the [member position] or [member size] of both bounding boxes are not equal.
[b]Note:[/b] Due to floating-point precision errors, consider using [method is_equal_approx] instead, which is more reliable.
</description>
</operator>
<operator name="operator *">
<return type="AABB" />
<param index="0" name="right" type="Transform3D" />
<description>
Inversely transforms (multiplies) the [AABB] by the given [Transform3D] transformation matrix, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not).
[code]aabb * transform[/code] is equivalent to [code]transform.inverse() * aabb[/code]. See [method Transform3D.inverse].
For transforming by inverse of an affine transformation (e.g. with scaling) [code]transform.affine_inverse() * aabb[/code] can be used instead. See [method Transform3D.affine_inverse].
</description>
</operator>
<operator name="operator ==">
<return type="bool" />
<param index="0" name="right" type="AABB" />
<description>
Returns [code]true[/code] if both [member position] and [member size] of the bounding boxes are exactly equal, respectively.
[b]Note:[/b] Due to floating-point precision errors, consider using [method is_equal_approx] instead, which is more reliable.
</description>
</operator>
</operators>
</class>

130
doc/classes/AESContext.xml Normal file
View File

@@ -0,0 +1,130 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AESContext" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Provides access to AES encryption/decryption of raw data.
</brief_description>
<description>
This class holds the context information required for encryption and decryption operations with AES (Advanced Encryption Standard). Both AES-ECB and AES-CBC modes are supported.
[codeblocks]
[gdscript]
extends Node
var aes = AESContext.new()
func _ready():
var key = "My secret key!!!" # Key must be either 16 or 32 bytes.
var data = "My secret text!!" # Data size must be multiple of 16 bytes, apply padding if needed.
# Encrypt ECB
aes.start(AESContext.MODE_ECB_ENCRYPT, key.to_utf8_buffer())
var encrypted = aes.update(data.to_utf8_buffer())
aes.finish()
# Decrypt ECB
aes.start(AESContext.MODE_ECB_DECRYPT, key.to_utf8_buffer())
var decrypted = aes.update(encrypted)
aes.finish()
# Check ECB
assert(decrypted == data.to_utf8_buffer())
var iv = "My secret iv!!!!" # IV must be of exactly 16 bytes.
# Encrypt CBC
aes.start(AESContext.MODE_CBC_ENCRYPT, key.to_utf8_buffer(), iv.to_utf8_buffer())
encrypted = aes.update(data.to_utf8_buffer())
aes.finish()
# Decrypt CBC
aes.start(AESContext.MODE_CBC_DECRYPT, key.to_utf8_buffer(), iv.to_utf8_buffer())
decrypted = aes.update(encrypted)
aes.finish()
# Check CBC
assert(decrypted == data.to_utf8_buffer())
[/gdscript]
[csharp]
using Godot;
using System.Diagnostics;
public partial class MyNode : Node
{
private AesContext _aes = new AesContext();
public override void _Ready()
{
string key = "My secret key!!!"; // Key must be either 16 or 32 bytes.
string data = "My secret text!!"; // Data size must be multiple of 16 bytes, apply padding if needed.
// Encrypt ECB
_aes.Start(AesContext.Mode.EcbEncrypt, key.ToUtf8Buffer());
byte[] encrypted = _aes.Update(data.ToUtf8Buffer());
_aes.Finish();
// Decrypt ECB
_aes.Start(AesContext.Mode.EcbDecrypt, key.ToUtf8Buffer());
byte[] decrypted = _aes.Update(encrypted);
_aes.Finish();
// Check ECB
Debug.Assert(decrypted == data.ToUtf8Buffer());
string iv = "My secret iv!!!!"; // IV must be of exactly 16 bytes.
// Encrypt CBC
_aes.Start(AesContext.Mode.EcbEncrypt, key.ToUtf8Buffer(), iv.ToUtf8Buffer());
encrypted = _aes.Update(data.ToUtf8Buffer());
_aes.Finish();
// Decrypt CBC
_aes.Start(AesContext.Mode.EcbDecrypt, key.ToUtf8Buffer(), iv.ToUtf8Buffer());
decrypted = _aes.Update(encrypted);
_aes.Finish();
// Check CBC
Debug.Assert(decrypted == data.ToUtf8Buffer());
}
}
[/csharp]
[/codeblocks]
</description>
<tutorials>
</tutorials>
<methods>
<method name="finish">
<return type="void" />
<description>
Close this AES context so it can be started again. See [method start].
</description>
</method>
<method name="get_iv_state">
<return type="PackedByteArray" />
<description>
Get the current IV state for this context (IV gets updated when calling [method update]). You normally don't need this function.
[b]Note:[/b] This function only makes sense when the context is started with [constant MODE_CBC_ENCRYPT] or [constant MODE_CBC_DECRYPT].
</description>
</method>
<method name="start">
<return type="int" enum="Error" />
<param index="0" name="mode" type="int" enum="AESContext.Mode" />
<param index="1" name="key" type="PackedByteArray" />
<param index="2" name="iv" type="PackedByteArray" default="PackedByteArray()" />
<description>
Start the AES context in the given [param mode]. A [param key] of either 16 or 32 bytes must always be provided, while an [param iv] (initialization vector) of exactly 16 bytes, is only needed when [param mode] is either [constant MODE_CBC_ENCRYPT] or [constant MODE_CBC_DECRYPT].
</description>
</method>
<method name="update">
<return type="PackedByteArray" />
<param index="0" name="src" type="PackedByteArray" />
<description>
Run the desired operation for this AES context. Will return a [PackedByteArray] containing the result of encrypting (or decrypting) the given [param src]. See [method start] for mode of operation.
[b]Note:[/b] The size of [param src] must be a multiple of 16. Apply some padding if needed.
</description>
</method>
</methods>
<constants>
<constant name="MODE_ECB_ENCRYPT" value="0" enum="Mode">
AES electronic codebook encryption mode.
</constant>
<constant name="MODE_ECB_DECRYPT" value="1" enum="Mode">
AES electronic codebook decryption mode.
</constant>
<constant name="MODE_CBC_ENCRYPT" value="2" enum="Mode">
AES cipher blocker chaining encryption mode.
</constant>
<constant name="MODE_CBC_DECRYPT" value="3" enum="Mode">
AES cipher blocker chaining decryption mode.
</constant>
<constant name="MODE_MAX" value="4" enum="Mode">
Maximum value for the mode enum.
</constant>
</constants>
</class>

324
doc/classes/AStar2D.xml Normal file
View File

@@ -0,0 +1,324 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AStar2D" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
An implementation of A* for finding the shortest path between two vertices on a connected graph in 2D space.
</brief_description>
<description>
An implementation of the A* algorithm, used to find the shortest path between two vertices on a connected graph in 2D space.
See [AStar3D] for a more thorough explanation on how to use this class. [AStar2D] is a wrapper for [AStar3D] that enforces 2D coordinates.
</description>
<tutorials>
<link title="Grid-based Navigation with AStarGrid2D Demo">https://godotengine.org/asset-library/asset/2723</link>
</tutorials>
<methods>
<method name="_compute_cost" qualifiers="virtual const">
<return type="float" />
<param index="0" name="from_id" type="int" />
<param index="1" name="to_id" type="int" />
<description>
Called when computing the cost between two connected points.
Note that this function is hidden in the default [AStar2D] class.
</description>
</method>
<method name="_estimate_cost" qualifiers="virtual const">
<return type="float" />
<param index="0" name="from_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.
</description>
</method>
<method name="_filter_neighbor" qualifiers="virtual const">
<return type="bool" />
<param index="0" name="from_id" type="int" />
<param index="1" name="neighbor_id" type="int" />
<description>
Called when neighboring enters processing and if [member neighbor_filter_enabled] is [code]true[/code]. If [code]true[/code] is returned the point will not be processed.
Note that this function is hidden in the default [AStar2D] class.
</description>
</method>
<method name="add_point">
<return type="void" />
<param index="0" name="id" type="int" />
<param index="1" name="position" type="Vector2" />
<param index="2" name="weight_scale" type="float" default="1.0" />
<description>
Adds a new point at the given position with the given identifier. The [param id] must be 0 or larger, and the [param weight_scale] must be 0.0 or greater.
The [param weight_scale] is multiplied by the result of [method _compute_cost] when determining the overall cost of traveling across a segment from a neighboring point to this point. Thus, all else being equal, the algorithm prefers points with lower [param weight_scale]s to form a path.
[codeblocks]
[gdscript]
var astar = AStar2D.new()
astar.add_point(1, Vector2(1, 0), 4) # Adds the point (1, 0) with weight_scale 4 and id 1
[/gdscript]
[csharp]
var astar = new AStar2D();
astar.AddPoint(1, new Vector2(1, 0), 4); // Adds the point (1, 0) with weight_scale 4 and id 1
[/csharp]
[/codeblocks]
If there already exists a point for the given [param id], its position and weight scale are updated to the given values.
</description>
</method>
<method name="are_points_connected" qualifiers="const">
<return type="bool" />
<param index="0" name="id" type="int" />
<param index="1" name="to_id" type="int" />
<param index="2" name="bidirectional" type="bool" default="true" />
<description>
Returns whether there is a connection/segment between the given points. If [param bidirectional] is [code]false[/code], returns whether movement from [param id] to [param to_id] is possible through this segment.
</description>
</method>
<method name="clear">
<return type="void" />
<description>
Clears all the points and segments.
</description>
</method>
<method name="connect_points">
<return type="void" />
<param index="0" name="id" type="int" />
<param index="1" name="to_id" type="int" />
<param index="2" name="bidirectional" type="bool" default="true" />
<description>
Creates a segment between the given points. If [param bidirectional] is [code]false[/code], only movement from [param id] to [param to_id] is allowed, not the reverse direction.
[codeblocks]
[gdscript]
var astar = AStar2D.new()
astar.add_point(1, Vector2(1, 1))
astar.add_point(2, Vector2(0, 5))
astar.connect_points(1, 2, false)
[/gdscript]
[csharp]
var astar = new AStar2D();
astar.AddPoint(1, new Vector2(1, 1));
astar.AddPoint(2, new Vector2(0, 5));
astar.ConnectPoints(1, 2, false);
[/csharp]
[/codeblocks]
</description>
</method>
<method name="disconnect_points">
<return type="void" />
<param index="0" name="id" type="int" />
<param index="1" name="to_id" type="int" />
<param index="2" name="bidirectional" type="bool" default="true" />
<description>
Deletes the segment between the given points. If [param bidirectional] is [code]false[/code], only movement from [param id] to [param to_id] is prevented, and a unidirectional segment possibly remains.
</description>
</method>
<method name="get_available_point_id" qualifiers="const">
<return type="int" />
<description>
Returns the next available point ID with no point associated to it.
</description>
</method>
<method name="get_closest_point" qualifiers="const">
<return type="int" />
<param index="0" name="to_position" type="Vector2" />
<param index="1" name="include_disabled" type="bool" default="false" />
<description>
Returns the ID of the closest point to [param to_position], optionally taking disabled points into account. Returns [code]-1[/code] if there are no points in the points pool.
[b]Note:[/b] If several points are the closest to [param to_position], the one with the smallest ID will be returned, ensuring a deterministic result.
</description>
</method>
<method name="get_closest_position_in_segment" qualifiers="const">
<return type="Vector2" />
<param index="0" name="to_position" type="Vector2" />
<description>
Returns the closest position to [param to_position] that resides inside a segment between two connected points.
[codeblocks]
[gdscript]
var astar = AStar2D.new()
astar.add_point(1, Vector2(0, 0))
astar.add_point(2, Vector2(0, 5))
astar.connect_points(1, 2)
var res = astar.get_closest_position_in_segment(Vector2(3, 3)) # Returns (0, 3)
[/gdscript]
[csharp]
var astar = new AStar2D();
astar.AddPoint(1, new Vector2(0, 0));
astar.AddPoint(2, new Vector2(0, 5));
astar.ConnectPoints(1, 2);
Vector2 res = astar.GetClosestPositionInSegment(new Vector2(3, 3)); // Returns (0, 3)
[/csharp]
[/codeblocks]
The result is in the segment that goes from [code]y = 0[/code] to [code]y = 5[/code]. It's the closest position in the segment to the given point.
</description>
</method>
<method name="get_id_path">
<return type="PackedInt64Array" />
<param index="0" name="from_id" type="int" />
<param index="1" name="to_id" type="int" />
<param index="2" name="allow_partial_path" type="bool" default="false" />
<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()
astar.add_point(1, Vector2(0, 0))
astar.add_point(2, Vector2(0, 1), 1) # Default weight is 1
astar.add_point(3, Vector2(1, 1))
astar.add_point(4, Vector2(2, 0))
astar.connect_points(1, 2, false)
astar.connect_points(2, 3, false)
astar.connect_points(4, 3, false)
astar.connect_points(1, 4, false)
var res = astar.get_id_path(1, 3) # Returns [1, 2, 3]
[/gdscript]
[csharp]
var astar = new AStar2D();
astar.AddPoint(1, new Vector2(0, 0));
astar.AddPoint(2, new Vector2(0, 1), 1); // Default weight is 1
astar.AddPoint(3, new Vector2(1, 1));
astar.AddPoint(4, new Vector2(2, 0));
astar.ConnectPoints(1, 2, false);
astar.ConnectPoints(2, 3, false);
astar.ConnectPoints(4, 3, false);
astar.ConnectPoints(1, 4, false);
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.
</description>
</method>
<method name="get_point_capacity" qualifiers="const">
<return type="int" />
<description>
Returns the capacity of the structure backing the points, useful in conjunction with [method reserve_space].
</description>
</method>
<method name="get_point_connections">
<return type="PackedInt64Array" />
<param index="0" name="id" type="int" />
<description>
Returns an array with the IDs of the points that form the connection with the given point.
[codeblocks]
[gdscript]
var astar = AStar2D.new()
astar.add_point(1, Vector2(0, 0))
astar.add_point(2, Vector2(0, 1))
astar.add_point(3, Vector2(1, 1))
astar.add_point(4, Vector2(2, 0))
astar.connect_points(1, 2, true)
astar.connect_points(1, 3, true)
var neighbors = astar.get_point_connections(1) # Returns [2, 3]
[/gdscript]
[csharp]
var astar = new AStar2D();
astar.AddPoint(1, new Vector2(0, 0));
astar.AddPoint(2, new Vector2(0, 1));
astar.AddPoint(3, new Vector2(1, 1));
astar.AddPoint(4, new Vector2(2, 0));
astar.ConnectPoints(1, 2, true);
astar.ConnectPoints(1, 3, true);
long[] neighbors = astar.GetPointConnections(1); // Returns [2, 3]
[/csharp]
[/codeblocks]
</description>
</method>
<method name="get_point_count" qualifiers="const">
<return type="int" />
<description>
Returns the number of points currently in the points pool.
</description>
</method>
<method name="get_point_ids">
<return type="PackedInt64Array" />
<description>
Returns an array of all point IDs.
</description>
</method>
<method name="get_point_path">
<return type="PackedVector2Array" />
<param index="0" name="from_id" type="int" />
<param index="1" name="to_id" type="int" />
<param index="2" name="allow_partial_path" type="bool" default="false" />
<description>
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; it can only be used from a single [Thread] at a given time. Consider using [Mutex] to ensure exclusive access to one thread to avoid race conditions.
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">
<return type="Vector2" />
<param index="0" name="id" type="int" />
<description>
Returns the position of the point associated with the given [param id].
</description>
</method>
<method name="get_point_weight_scale" qualifiers="const">
<return type="float" />
<param index="0" name="id" type="int" />
<description>
Returns the weight scale of the point associated with the given [param id].
</description>
</method>
<method name="has_point" qualifiers="const">
<return type="bool" />
<param index="0" name="id" type="int" />
<description>
Returns whether a point associated with the given [param id] exists.
</description>
</method>
<method name="is_point_disabled" qualifiers="const">
<return type="bool" />
<param index="0" name="id" type="int" />
<description>
Returns whether a point is disabled or not for pathfinding. By default, all points are enabled.
</description>
</method>
<method name="remove_point">
<return type="void" />
<param index="0" name="id" type="int" />
<description>
Removes the point associated with the given [param id] from the points pool.
</description>
</method>
<method name="reserve_space">
<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.
</description>
</method>
<method name="set_point_disabled">
<return type="void" />
<param index="0" name="id" type="int" />
<param index="1" name="disabled" type="bool" default="true" />
<description>
Disables or enables the specified point for pathfinding. Useful for making a temporary obstacle.
</description>
</method>
<method name="set_point_position">
<return type="void" />
<param index="0" name="id" type="int" />
<param index="1" name="position" type="Vector2" />
<description>
Sets the [param position] for the point with the given [param id].
</description>
</method>
<method name="set_point_weight_scale">
<return type="void" />
<param index="0" name="id" type="int" />
<param index="1" name="weight_scale" type="float" />
<description>
Sets the [param weight_scale] for the point with the given [param id]. The [param weight_scale] is multiplied by the result of [method _compute_cost] when determining the overall cost of traveling across a segment from a neighboring point to this point.
</description>
</method>
</methods>
<members>
<member name="neighbor_filter_enabled" type="bool" setter="set_neighbor_filter_enabled" getter="is_neighbor_filter_enabled" default="false">
If [code]true[/code] enables the filtering of neighbors via [method _filter_neighbor].
</member>
</members>
</class>

363
doc/classes/AStar3D.xml Normal file
View File

@@ -0,0 +1,363 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AStar3D" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
An implementation of A* for finding the shortest path between two vertices on a connected graph in 3D space.
</brief_description>
<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 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_name MyAStar3D
extends AStar3D
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):
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]
using Godot;
[GlobalClass]
public partial class MyAStar3D : AStar3D
{
public override float _ComputeCost(long fromId, long 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)
{
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]
[/codeblocks]
[method _estimate_cost] should return a lower bound of the distance, i.e. [code]_estimate_cost(u, v) &lt;= _compute_cost(u, v)[/code]. This serves as a hint to the algorithm because the custom [method _compute_cost] might be computation-heavy. If this is not the case, make [method _estimate_cost] return the same value as [method _compute_cost] to provide the algorithm with the most accurate information.
If the default [method _estimate_cost] and [method _compute_cost] methods are used, or if the supplied [method _estimate_cost] method returns a lower bound of the cost, then the paths returned by A* will be the lowest-cost paths. Here, the cost of a path equals the sum of the [method _compute_cost] results of all segments in the path multiplied by the [code]weight_scale[/code]s of the endpoints of the respective segments. If the default methods are used and the [code]weight_scale[/code]s of all points are set to [code]1.0[/code], then this equals the sum of Euclidean distances of all segments in the path.
</description>
<tutorials>
</tutorials>
<methods>
<method name="_compute_cost" qualifiers="virtual const">
<return type="float" />
<param index="0" name="from_id" type="int" />
<param index="1" name="to_id" type="int" />
<description>
Called when computing the cost between two connected points.
Note that this function is hidden in the default [AStar3D] class.
</description>
</method>
<method name="_estimate_cost" qualifiers="virtual const">
<return type="float" />
<param index="0" name="from_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.
</description>
</method>
<method name="_filter_neighbor" qualifiers="virtual const">
<return type="bool" />
<param index="0" name="from_id" type="int" />
<param index="1" name="neighbor_id" type="int" />
<description>
Called when neighboring point enters processing and if [member neighbor_filter_enabled] is [code]true[/code]. If [code]true[/code] is returned the point will not be processed.
Note that this function is hidden in the default [AStar3D] class.
</description>
</method>
<method name="add_point">
<return type="void" />
<param index="0" name="id" type="int" />
<param index="1" name="position" type="Vector3" />
<param index="2" name="weight_scale" type="float" default="1.0" />
<description>
Adds a new point at the given position with the given identifier. The [param id] must be 0 or larger, and the [param weight_scale] must be 0.0 or greater.
The [param weight_scale] is multiplied by the result of [method _compute_cost] when determining the overall cost of traveling across a segment from a neighboring point to this point. Thus, all else being equal, the algorithm prefers points with lower [param weight_scale]s to form a path.
[codeblocks]
[gdscript]
var astar = AStar3D.new()
astar.add_point(1, Vector3(1, 0, 0), 4) # Adds the point (1, 0, 0) with weight_scale 4 and id 1
[/gdscript]
[csharp]
var astar = new AStar3D();
astar.AddPoint(1, new Vector3(1, 0, 0), 4); // Adds the point (1, 0, 0) with weight_scale 4 and id 1
[/csharp]
[/codeblocks]
If there already exists a point for the given [param id], its position and weight scale are updated to the given values.
</description>
</method>
<method name="are_points_connected" qualifiers="const">
<return type="bool" />
<param index="0" name="id" type="int" />
<param index="1" name="to_id" type="int" />
<param index="2" name="bidirectional" type="bool" default="true" />
<description>
Returns whether the two given points are directly connected by a segment. If [param bidirectional] is [code]false[/code], returns whether movement from [param id] to [param to_id] is possible through this segment.
</description>
</method>
<method name="clear">
<return type="void" />
<description>
Clears all the points and segments.
</description>
</method>
<method name="connect_points">
<return type="void" />
<param index="0" name="id" type="int" />
<param index="1" name="to_id" type="int" />
<param index="2" name="bidirectional" type="bool" default="true" />
<description>
Creates a segment between the given points. If [param bidirectional] is [code]false[/code], only movement from [param id] to [param to_id] is allowed, not the reverse direction.
[codeblocks]
[gdscript]
var astar = AStar3D.new()
astar.add_point(1, Vector3(1, 1, 0))
astar.add_point(2, Vector3(0, 5, 0))
astar.connect_points(1, 2, false)
[/gdscript]
[csharp]
var astar = new AStar3D();
astar.AddPoint(1, new Vector3(1, 1, 0));
astar.AddPoint(2, new Vector3(0, 5, 0));
astar.ConnectPoints(1, 2, false);
[/csharp]
[/codeblocks]
</description>
</method>
<method name="disconnect_points">
<return type="void" />
<param index="0" name="id" type="int" />
<param index="1" name="to_id" type="int" />
<param index="2" name="bidirectional" type="bool" default="true" />
<description>
Deletes the segment between the given points. If [param bidirectional] is [code]false[/code], only movement from [param id] to [param to_id] is prevented, and a unidirectional segment possibly remains.
</description>
</method>
<method name="get_available_point_id" qualifiers="const">
<return type="int" />
<description>
Returns the next available point ID with no point associated to it.
</description>
</method>
<method name="get_closest_point" qualifiers="const">
<return type="int" />
<param index="0" name="to_position" type="Vector3" />
<param index="1" name="include_disabled" type="bool" default="false" />
<description>
Returns the ID of the closest point to [param to_position], optionally taking disabled points into account. Returns [code]-1[/code] if there are no points in the points pool.
[b]Note:[/b] If several points are the closest to [param to_position], the one with the smallest ID will be returned, ensuring a deterministic result.
</description>
</method>
<method name="get_closest_position_in_segment" qualifiers="const">
<return type="Vector3" />
<param index="0" name="to_position" type="Vector3" />
<description>
Returns the closest position to [param to_position] that resides inside a segment between two connected points.
[codeblocks]
[gdscript]
var astar = AStar3D.new()
astar.add_point(1, Vector3(0, 0, 0))
astar.add_point(2, Vector3(0, 5, 0))
astar.connect_points(1, 2)
var res = astar.get_closest_position_in_segment(Vector3(3, 3, 0)) # Returns (0, 3, 0)
[/gdscript]
[csharp]
var astar = new AStar3D();
astar.AddPoint(1, new Vector3(0, 0, 0));
astar.AddPoint(2, new Vector3(0, 5, 0));
astar.ConnectPoints(1, 2);
Vector3 res = astar.GetClosestPositionInSegment(new Vector3(3, 3, 0)); // Returns (0, 3, 0)
[/csharp]
[/codeblocks]
The result is in the segment that goes from [code]y = 0[/code] to [code]y = 5[/code]. It's the closest position in the segment to the given point.
</description>
</method>
<method name="get_id_path">
<return type="PackedInt64Array" />
<param index="0" name="from_id" type="int" />
<param index="1" name="to_id" type="int" />
<param index="2" name="allow_partial_path" type="bool" default="false" />
<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()
astar.add_point(1, Vector3(0, 0, 0))
astar.add_point(2, Vector3(0, 1, 0), 1) # Default weight is 1
astar.add_point(3, Vector3(1, 1, 0))
astar.add_point(4, Vector3(2, 0, 0))
astar.connect_points(1, 2, false)
astar.connect_points(2, 3, false)
astar.connect_points(4, 3, false)
astar.connect_points(1, 4, false)
var res = astar.get_id_path(1, 3) # Returns [1, 2, 3]
[/gdscript]
[csharp]
var astar = new AStar3D();
astar.AddPoint(1, new Vector3(0, 0, 0));
astar.AddPoint(2, new Vector3(0, 1, 0), 1); // Default weight is 1
astar.AddPoint(3, new Vector3(1, 1, 0));
astar.AddPoint(4, new Vector3(2, 0, 0));
astar.ConnectPoints(1, 2, false);
astar.ConnectPoints(2, 3, false);
astar.ConnectPoints(4, 3, false);
astar.ConnectPoints(1, 4, false);
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.
</description>
</method>
<method name="get_point_capacity" qualifiers="const">
<return type="int" />
<description>
Returns the capacity of the structure backing the points, useful in conjunction with [method reserve_space].
</description>
</method>
<method name="get_point_connections">
<return type="PackedInt64Array" />
<param index="0" name="id" type="int" />
<description>
Returns an array with the IDs of the points that form the connection with the given point.
[codeblocks]
[gdscript]
var astar = AStar3D.new()
astar.add_point(1, Vector3(0, 0, 0))
astar.add_point(2, Vector3(0, 1, 0))
astar.add_point(3, Vector3(1, 1, 0))
astar.add_point(4, Vector3(2, 0, 0))
astar.connect_points(1, 2, true)
astar.connect_points(1, 3, true)
var neighbors = astar.get_point_connections(1) # Returns [2, 3]
[/gdscript]
[csharp]
var astar = new AStar3D();
astar.AddPoint(1, new Vector3(0, 0, 0));
astar.AddPoint(2, new Vector3(0, 1, 0));
astar.AddPoint(3, new Vector3(1, 1, 0));
astar.AddPoint(4, new Vector3(2, 0, 0));
astar.ConnectPoints(1, 2, true);
astar.ConnectPoints(1, 3, true);
long[] neighbors = astar.GetPointConnections(1); // Returns [2, 3]
[/csharp]
[/codeblocks]
</description>
</method>
<method name="get_point_count" qualifiers="const">
<return type="int" />
<description>
Returns the number of points currently in the points pool.
</description>
</method>
<method name="get_point_ids">
<return type="PackedInt64Array" />
<description>
Returns an array of all point IDs.
</description>
</method>
<method name="get_point_path">
<return type="PackedVector3Array" />
<param index="0" name="from_id" type="int" />
<param index="1" name="to_id" type="int" />
<param index="2" name="allow_partial_path" type="bool" default="false" />
<description>
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; it can only be used from a single [Thread] at a given time. Consider using [Mutex] to ensure exclusive access to one thread to avoid race conditions.
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">
<return type="Vector3" />
<param index="0" name="id" type="int" />
<description>
Returns the position of the point associated with the given [param id].
</description>
</method>
<method name="get_point_weight_scale" qualifiers="const">
<return type="float" />
<param index="0" name="id" type="int" />
<description>
Returns the weight scale of the point associated with the given [param id].
</description>
</method>
<method name="has_point" qualifiers="const">
<return type="bool" />
<param index="0" name="id" type="int" />
<description>
Returns whether a point associated with the given [param id] exists.
</description>
</method>
<method name="is_point_disabled" qualifiers="const">
<return type="bool" />
<param index="0" name="id" type="int" />
<description>
Returns whether a point is disabled or not for pathfinding. By default, all points are enabled.
</description>
</method>
<method name="remove_point">
<return type="void" />
<param index="0" name="id" type="int" />
<description>
Removes the point associated with the given [param id] from the points pool.
</description>
</method>
<method name="reserve_space">
<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.
</description>
</method>
<method name="set_point_disabled">
<return type="void" />
<param index="0" name="id" type="int" />
<param index="1" name="disabled" type="bool" default="true" />
<description>
Disables or enables the specified point for pathfinding. Useful for making a temporary obstacle.
</description>
</method>
<method name="set_point_position">
<return type="void" />
<param index="0" name="id" type="int" />
<param index="1" name="position" type="Vector3" />
<description>
Sets the [param position] for the point with the given [param id].
</description>
</method>
<method name="set_point_weight_scale">
<return type="void" />
<param index="0" name="id" type="int" />
<param index="1" name="weight_scale" type="float" />
<description>
Sets the [param weight_scale] for the point with the given [param id]. The [param weight_scale] is multiplied by the result of [method _compute_cost] when determining the overall cost of traveling across a segment from a neighboring point to this point.
</description>
</method>
</methods>
<members>
<member name="neighbor_filter_enabled" type="bool" setter="set_neighbor_filter_enabled" getter="is_neighbor_filter_enabled" default="false">
If [code]true[/code] enables the filtering of neighbors via [method _filter_neighbor].
</member>
</members>
</class>

270
doc/classes/AStarGrid2D.xml Normal file
View File

@@ -0,0 +1,270 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AStarGrid2D" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
An implementation of A* for finding the shortest path between two points on a partial 2D grid.
</brief_description>
<description>
[AStarGrid2D] is a variant of [AStar2D] that is specialized for partial 2D grids. It is simpler to use because it doesn't require you to manually create points and connect them together. This class also supports multiple types of heuristics, modes for diagonal movement, and a jumping mode to speed up calculations.
To use [AStarGrid2D], you only need to set the [member region] of the grid, optionally set the [member cell_size], and then call the [method update] method:
[codeblocks]
[gdscript]
var astar_grid = AStarGrid2D.new()
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)]
[/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)]
[/csharp]
[/codeblocks]
To remove a point from the pathfinding grid, it must be set as "solid" with [method set_point_solid].
</description>
<tutorials>
<link title="Grid-based Navigation with AStarGrid2D Demo">https://godotengine.org/asset-library/asset/2723</link>
</tutorials>
<methods>
<method name="_compute_cost" qualifiers="virtual const">
<return type="float" />
<param index="0" name="from_id" type="Vector2i" />
<param index="1" name="to_id" type="Vector2i" />
<description>
Called when computing the cost between two connected points.
Note that this function is hidden in the default [AStarGrid2D] class.
</description>
</method>
<method name="_estimate_cost" qualifiers="virtual const">
<return type="float" />
<param index="0" name="from_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.
</description>
</method>
<method name="clear">
<return type="void" />
<description>
Clears the grid and sets the [member region] to [code]Rect2i(0, 0, 0, 0)[/code].
</description>
</method>
<method name="fill_solid_region">
<return type="void" />
<param index="0" name="region" type="Rect2i" />
<param index="1" name="solid" type="bool" default="true" />
<description>
Fills the given [param region] on the grid with the specified value for the solid flag.
[b]Note:[/b] Calling [method update] is not needed after the call of this function.
</description>
</method>
<method name="fill_weight_scale_region">
<return type="void" />
<param index="0" name="region" type="Rect2i" />
<param index="1" name="weight_scale" type="float" />
<description>
Fills the given [param region] on the grid with the specified value for the weight scale.
[b]Note:[/b] Calling [method update] is not needed after the call of this function.
</description>
</method>
<method name="get_id_path">
<return type="Vector2i[]" />
<param index="0" name="from_id" type="Vector2i" />
<param index="1" name="to_id" type="Vector2i" />
<param index="2" name="allow_partial_path" type="bool" default="false" />
<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">
<return type="PackedVector2Array" />
<param index="0" name="from_id" type="Vector2i" />
<param index="1" name="to_id" type="Vector2i" />
<param index="2" name="allow_partial_path" type="bool" default="false" />
<description>
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; it can only be used from a single [Thread] at a given time. Consider using [Mutex] to ensure exclusive access to one thread to avoid race conditions.
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">
<return type="Vector2" />
<param index="0" name="id" type="Vector2i" />
<description>
Returns the position of the point associated with the given [param id].
</description>
</method>
<method name="get_point_weight_scale" qualifiers="const">
<return type="float" />
<param index="0" name="id" type="Vector2i" />
<description>
Returns the weight scale of the point associated with the given [param id].
</description>
</method>
<method name="is_dirty" qualifiers="const">
<return type="bool" />
<description>
Indicates that the grid parameters were changed and [method update] needs to be called.
</description>
</method>
<method name="is_in_bounds" qualifiers="const">
<return type="bool" />
<param index="0" name="x" type="int" />
<param index="1" name="y" type="int" />
<description>
Returns [code]true[/code] if the [param x] and [param y] is a valid grid coordinate (id), i.e. if it is inside [member region]. Equivalent to [code]region.has_point(Vector2i(x, y))[/code].
</description>
</method>
<method name="is_in_boundsv" qualifiers="const">
<return type="bool" />
<param index="0" name="id" type="Vector2i" />
<description>
Returns [code]true[/code] if the [param id] vector is a valid grid coordinate, i.e. if it is inside [member region]. Equivalent to [code]region.has_point(id)[/code].
</description>
</method>
<method name="is_point_solid" qualifiers="const">
<return type="bool" />
<param index="0" name="id" type="Vector2i" />
<description>
Returns [code]true[/code] if a point is disabled for pathfinding. By default, all points are enabled.
</description>
</method>
<method name="set_point_solid">
<return type="void" />
<param index="0" name="id" type="Vector2i" />
<param index="1" name="solid" type="bool" default="true" />
<description>
Disables or enables the specified point for pathfinding. Useful for making an obstacle. By default, all points are enabled.
[b]Note:[/b] Calling [method update] is not needed after the call of this function.
</description>
</method>
<method name="set_point_weight_scale">
<return type="void" />
<param index="0" name="id" type="Vector2i" />
<param index="1" name="weight_scale" type="float" />
<description>
Sets the [param weight_scale] for the point with the given [param id]. The [param weight_scale] is multiplied by the result of [method _compute_cost] when determining the overall cost of traveling across a segment from a neighboring point to this point.
[b]Note:[/b] Calling [method update] is not needed after the call of this function.
</description>
</method>
<method name="update">
<return type="void" />
<description>
Updates the internal state of the grid according to the parameters to prepare it to search the path. Needs to be called if parameters like [member region], [member cell_size] or [member offset] are changed. [method is_dirty] will return [code]true[/code] if this is the case and this needs to be called.
[b]Note:[/b] All point data (solidity and weight scale) will be cleared.
</description>
</method>
</methods>
<members>
<member name="cell_shape" type="int" setter="set_cell_shape" getter="get_cell_shape" enum="AStarGrid2D.CellShape" default="0">
The cell shape. Affects how the positions are placed in the grid. If changed, [method update] needs to be called before finding the next path.
</member>
<member name="cell_size" type="Vector2" setter="set_cell_size" getter="get_cell_size" default="Vector2(1, 1)">
The size of the point cell which will be applied to calculate the resulting point position returned by [method get_point_path]. If changed, [method update] needs to be called before finding the next path.
</member>
<member name="default_compute_heuristic" type="int" setter="set_default_compute_heuristic" getter="get_default_compute_heuristic" enum="AStarGrid2D.Heuristic" default="0">
The default [enum Heuristic] which will be used to calculate the cost between two points if [method _compute_cost] was not overridden.
</member>
<member name="default_estimate_heuristic" type="int" setter="set_default_estimate_heuristic" getter="get_default_estimate_heuristic" enum="AStarGrid2D.Heuristic" default="0">
The default [enum Heuristic] which will be used to calculate the cost between the point and the end point if [method _estimate_cost] was not overridden.
</member>
<member name="diagonal_mode" type="int" setter="set_diagonal_mode" getter="get_diagonal_mode" enum="AStarGrid2D.DiagonalMode" default="0">
A specific [enum DiagonalMode] mode which will force the path to avoid or accept the specified diagonals.
</member>
<member name="jumping_enabled" type="bool" setter="set_jumping_enabled" getter="is_jumping_enabled" default="false">
Enables or disables jumping to skip up the intermediate points and speeds up the searching algorithm.
[b]Note:[/b] Currently, toggling it on disables the consideration of weight scaling in pathfinding.
</member>
<member name="offset" type="Vector2" setter="set_offset" getter="get_offset" default="Vector2(0, 0)">
The offset of the grid which will be applied to calculate the resulting point position returned by [method get_point_path]. If changed, [method update] needs to be called before finding the next path.
</member>
<member name="region" type="Rect2i" setter="set_region" getter="get_region" default="Rect2i(0, 0, 0, 0)">
The region of grid cells available for pathfinding. If changed, [method update] needs to be called before finding the next path.
</member>
<member name="size" type="Vector2i" setter="set_size" getter="get_size" default="Vector2i(0, 0)" deprecated="Use [member region] instead.">
The size of the grid (number of cells of size [member cell_size] on each axis). If changed, [method update] needs to be called before finding the next path.
</member>
</members>
<constants>
<constant name="HEURISTIC_EUCLIDEAN" value="0" enum="Heuristic">
The [url=https://en.wikipedia.org/wiki/Euclidean_distance]Euclidean heuristic[/url] to be used for the pathfinding using the following formula:
[codeblock]
dx = abs(to_id.x - from_id.x)
dy = abs(to_id.y - from_id.y)
result = sqrt(dx * dx + dy * dy)
[/codeblock]
[b]Note:[/b] This is also the internal heuristic used in [AStar3D] and [AStar2D] by default (with the inclusion of possible z-axis coordinate).
</constant>
<constant name="HEURISTIC_MANHATTAN" value="1" enum="Heuristic">
The [url=https://en.wikipedia.org/wiki/Taxicab_geometry]Manhattan heuristic[/url] to be used for the pathfinding using the following formula:
[codeblock]
dx = abs(to_id.x - from_id.x)
dy = abs(to_id.y - from_id.y)
result = dx + dy
[/codeblock]
[b]Note:[/b] This heuristic is intended to be used with 4-side orthogonal movements, provided by setting the [member diagonal_mode] to [constant DIAGONAL_MODE_NEVER].
</constant>
<constant name="HEURISTIC_OCTILE" value="2" enum="Heuristic">
The Octile heuristic to be used for the pathfinding using the following formula:
[codeblock]
dx = abs(to_id.x - from_id.x)
dy = abs(to_id.y - from_id.y)
f = sqrt(2) - 1
result = (dx &lt; dy) ? f * dx + dy : f * dy + dx;
[/codeblock]
</constant>
<constant name="HEURISTIC_CHEBYSHEV" value="3" enum="Heuristic">
The [url=https://en.wikipedia.org/wiki/Chebyshev_distance]Chebyshev heuristic[/url] to be used for the pathfinding using the following formula:
[codeblock]
dx = abs(to_id.x - from_id.x)
dy = abs(to_id.y - from_id.y)
result = max(dx, dy)
[/codeblock]
</constant>
<constant name="HEURISTIC_MAX" value="4" enum="Heuristic">
Represents the size of the [enum Heuristic] enum.
</constant>
<constant name="DIAGONAL_MODE_ALWAYS" value="0" enum="DiagonalMode">
The pathfinding algorithm will ignore solid neighbors around the target cell and allow passing using diagonals.
</constant>
<constant name="DIAGONAL_MODE_NEVER" value="1" enum="DiagonalMode">
The pathfinding algorithm will ignore all diagonals and the way will be always orthogonal.
</constant>
<constant name="DIAGONAL_MODE_AT_LEAST_ONE_WALKABLE" value="2" enum="DiagonalMode">
The pathfinding algorithm will avoid using diagonals if at least two obstacles have been placed around the neighboring cells of the specific path segment.
</constant>
<constant name="DIAGONAL_MODE_ONLY_IF_NO_OBSTACLES" value="3" enum="DiagonalMode">
The pathfinding algorithm will avoid using diagonals if any obstacle has been placed around the neighboring cells of the specific path segment.
</constant>
<constant name="DIAGONAL_MODE_MAX" value="4" enum="DiagonalMode">
Represents the size of the [enum DiagonalMode] enum.
</constant>
<constant name="CELL_SHAPE_SQUARE" value="0" enum="CellShape">
Rectangular cell shape.
</constant>
<constant name="CELL_SHAPE_ISOMETRIC_RIGHT" value="1" enum="CellShape">
Diamond cell shape (for isometric look). Cell coordinates layout where the horizontal axis goes up-right, and the vertical one goes down-right.
</constant>
<constant name="CELL_SHAPE_ISOMETRIC_DOWN" value="2" enum="CellShape">
Diamond cell shape (for isometric look). Cell coordinates layout where the horizontal axis goes down-right, and the vertical one goes down-left.
</constant>
<constant name="CELL_SHAPE_MAX" value="3" enum="CellShape">
Represents the size of the [enum CellShape] enum.
</constant>
</constants>
</class>

119
doc/classes/AcceptDialog.xml Normal file
View File

@@ -0,0 +1,119 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AcceptDialog" inherits="Window" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
A base dialog used for user notification.
</brief_description>
<description>
The default use of [AcceptDialog] is to allow it to only be accepted or closed, with the same result. However, the [signal confirmed] and [signal canceled] signals allow to make the two actions different, and the [method add_button] method allows to add custom buttons and actions.
</description>
<tutorials>
</tutorials>
<methods>
<method name="add_button">
<return type="Button" />
<param index="0" name="text" type="String" />
<param index="1" name="right" type="bool" default="false" />
<param index="2" name="action" type="String" default="&quot;&quot;" />
<description>
Adds a button with label [param text] and a custom [param action] to the dialog and returns the created button.
If [param action] is not empty, pressing the button will emit the [signal custom_action] signal with the specified action string.
If [code]true[/code], [param right] will place the button to the right of any sibling buttons.
You can use [method remove_button] method to remove a button created with this method from the dialog.
</description>
</method>
<method name="add_cancel_button">
<return type="Button" />
<param index="0" name="name" type="String" />
<description>
Adds a button with label [param name] and a cancel action to the dialog and returns the created button.
You can use [method remove_button] method to remove a button created with this method from the dialog.
</description>
</method>
<method name="get_label">
<return type="Label" />
<description>
Returns the label used for built-in text.
[b]Warning:[/b] This is a required internal node, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their [member CanvasItem.visible] property.
</description>
</method>
<method name="get_ok_button">
<return type="Button" />
<description>
Returns the OK [Button] instance.
[b]Warning:[/b] This is a required internal node, removing and freeing it may cause a crash. If you wish to hide it or any of its children, use their [member CanvasItem.visible] property.
</description>
</method>
<method name="register_text_enter">
<return type="void" />
<param index="0" name="line_edit" type="LineEdit" />
<description>
Registers a [LineEdit] in the dialog. When the enter key is pressed, the dialog will be accepted.
</description>
</method>
<method name="remove_button">
<return type="void" />
<param index="0" name="button" type="Button" />
<description>
Removes the [param button] from the dialog. Does NOT free the [param button]. The [param button] must be a [Button] added with [method add_button] or [method add_cancel_button] method. After removal, pressing the [param button] will no longer emit this dialog's [signal custom_action] or [signal canceled] signals.
</description>
</method>
</methods>
<members>
<member name="dialog_autowrap" type="bool" setter="set_autowrap" getter="has_autowrap" default="false">
Sets autowrapping for the text in the dialog.
</member>
<member name="dialog_close_on_escape" type="bool" setter="set_close_on_escape" getter="get_close_on_escape" default="true">
If [code]true[/code], the dialog will be hidden when the [code]ui_cancel[/code] action is pressed (by default, this action is bound to [constant KEY_ESCAPE]).
</member>
<member name="dialog_hide_on_ok" type="bool" setter="set_hide_on_ok" getter="get_hide_on_ok" default="true">
If [code]true[/code], the dialog is hidden when the OK button is pressed. You can set it to [code]false[/code] if you want to do e.g. input validation when receiving the [signal confirmed] signal, and handle hiding the dialog in your own logic.
[b]Note:[/b] Some nodes derived from this class can have a different default value, and potentially their own built-in logic overriding this setting. For example [FileDialog] defaults to [code]false[/code], and has its own input validation code that is called when you press OK, which eventually hides the dialog if the input is valid. As such, this property can't be used in [FileDialog] to disable hiding the dialog when pressing OK.
</member>
<member name="dialog_text" type="String" setter="set_text" getter="get_text" default="&quot;&quot;">
The text displayed by the dialog.
</member>
<member name="exclusive" type="bool" setter="set_exclusive" getter="is_exclusive" overrides="Window" default="true" />
<member name="keep_title_visible" type="bool" setter="set_keep_title_visible" getter="get_keep_title_visible" overrides="Window" default="true" />
<member name="maximize_disabled" type="bool" setter="set_flag" getter="get_flag" overrides="Window" default="true" />
<member name="minimize_disabled" type="bool" setter="set_flag" getter="get_flag" overrides="Window" default="true" />
<member name="ok_button_text" type="String" setter="set_ok_button_text" getter="get_ok_button_text" default="&quot;&quot;">
The text displayed by the OK button (see [method get_ok_button]). If empty, a default text will be used.
</member>
<member name="title" type="String" setter="set_title" getter="get_title" overrides="Window" default="&quot;Alert!&quot;" />
<member name="transient" type="bool" setter="set_transient" getter="is_transient" overrides="Window" default="true" />
<member name="visible" type="bool" setter="set_visible" getter="is_visible" overrides="Window" default="false" />
<member name="wrap_controls" type="bool" setter="set_wrap_controls" getter="is_wrapping_controls" overrides="Window" default="true" />
</members>
<signals>
<signal name="canceled">
<description>
Emitted when the dialog is closed or the button created with [method add_cancel_button] is pressed.
</description>
</signal>
<signal name="confirmed">
<description>
Emitted when the dialog is accepted, i.e. the OK button is pressed.
</description>
</signal>
<signal name="custom_action">
<param index="0" name="action" type="StringName" />
<description>
Emitted when a custom button with an action is pressed. See [method add_button].
</description>
</signal>
</signals>
<theme_items>
<theme_item name="buttons_min_height" data_type="constant" type="int" default="0">
The minimum height of each button in the bottom row (such as OK/Cancel) in pixels. This can be increased to make buttons with short texts easier to click/tap.
</theme_item>
<theme_item name="buttons_min_width" data_type="constant" type="int" default="0">
The minimum width of each button in the bottom row (such as OK/Cancel) in pixels. This can be increased to make buttons with short texts easier to click/tap.
</theme_item>
<theme_item name="buttons_separation" data_type="constant" type="int" default="10">
The size of the vertical space between the dialog's content and the button row.
</theme_item>
<theme_item name="panel" data_type="style" type="StyleBox">
The panel that fills the background of the window.
</theme_item>
</theme_items>
</class>

80
doc/classes/AimModifier3D.xml Normal file
View File

@@ -0,0 +1,80 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AimModifier3D" inherits="BoneConstraint3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
The [AimModifier3D] rotates a bone to look at a reference bone.
</brief_description>
<description>
This is a simple version of [LookAtModifier3D] that only allows bone to the reference without advanced options such as angle limitation or time-based interpolation.
The feature is simplified, but instead it is implemented with smooth tracking without euler, see [method set_use_euler].
</description>
<tutorials>
</tutorials>
<methods>
<method name="get_forward_axis" qualifiers="const">
<return type="int" enum="SkeletonModifier3D.BoneAxis" />
<param index="0" name="index" type="int" />
<description>
Returns the forward axis of the bone.
</description>
</method>
<method name="get_primary_rotation_axis" qualifiers="const">
<return type="int" enum="Vector3.Axis" />
<param index="0" name="index" type="int" />
<description>
Returns the axis of the first rotation. It is enabled only if [method is_using_euler] is [code]true[/code].
</description>
</method>
<method name="is_using_euler" qualifiers="const">
<return type="bool" />
<param index="0" name="index" type="int" />
<description>
Returns [code]true[/code] if it provides rotation with using euler.
</description>
</method>
<method name="is_using_secondary_rotation" qualifiers="const">
<return type="bool" />
<param index="0" name="index" type="int" />
<description>
Returns [code]true[/code] if it provides rotation by two axes. It is enabled only if [method is_using_euler] is [code]true[/code].
</description>
</method>
<method name="set_forward_axis">
<return type="void" />
<param index="0" name="index" type="int" />
<param index="1" name="axis" type="int" enum="SkeletonModifier3D.BoneAxis" />
<description>
Sets the forward axis of the bone.
</description>
</method>
<method name="set_primary_rotation_axis">
<return type="void" />
<param index="0" name="index" type="int" />
<param index="1" name="axis" type="int" enum="Vector3.Axis" />
<description>
Sets the axis of the first rotation. It is enabled only if [method is_using_euler] is [code]true[/code].
</description>
</method>
<method name="set_use_euler">
<return type="void" />
<param index="0" name="index" type="int" />
<param index="1" name="enabled" type="bool" />
<description>
If sets [param enabled] to [code]true[/code], it provides rotation with using euler.
If sets [param enabled] to [code]false[/code], it provides rotation with using rotation by arc generated from the forward axis vector and the vector toward the reference.
</description>
</method>
<method name="set_use_secondary_rotation">
<return type="void" />
<param index="0" name="index" type="int" />
<param index="1" name="enabled" type="bool" />
<description>
If sets [param enabled] to [code]true[/code], it provides rotation by two axes. It is enabled only if [method is_using_euler] is [code]true[/code].
</description>
</method>
</methods>
<members>
<member name="setting_count" type="int" setter="set_setting_count" getter="get_setting_count" default="0">
The number of settings in the modifier.
</member>
</members>
</class>

19
doc/classes/AnimatableBody2D.xml Normal file
View File

@@ -0,0 +1,19 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimatableBody2D" inherits="StaticBody2D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
A 2D physics body that can't be moved by external forces. When moved manually, it affects other bodies in its path.
</brief_description>
<description>
An animatable 2D physics body. It can't be moved by external forces or contacts, but can be moved manually by other means such as code, [AnimationMixer]s (with [member AnimationMixer.callback_mode_process] set to [constant AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS]), and [RemoteTransform2D].
When [AnimatableBody2D] is moved, its linear and angular velocity are estimated and used to affect other physics bodies in its path. This makes it useful for moving platforms, doors, and other moving objects.
</description>
<tutorials>
<link title="Physics introduction">$DOCS_URL/tutorials/physics/physics_introduction.html</link>
<link title="Troubleshooting physics issues">$DOCS_URL/tutorials/physics/troubleshooting_physics_issues.html</link>
</tutorials>
<members>
<member name="sync_to_physics" type="bool" setter="set_sync_to_physics" getter="is_sync_to_physics_enabled" default="true">
If [code]true[/code], the body's movement will be synchronized to the physics frame. This is useful when animating movement via [AnimationPlayer], for example on moving platforms. Do [b]not[/b] use together with [method PhysicsBody2D.move_and_collide].
</member>
</members>
</class>

22
doc/classes/AnimatableBody3D.xml Normal file
View File

@@ -0,0 +1,22 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimatableBody3D" inherits="StaticBody3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
A 3D physics body that can't be moved by external forces. When moved manually, it affects other bodies in its path.
</brief_description>
<description>
An animatable 3D physics body. It can't be moved by external forces or contacts, but can be moved manually by other means such as code, [AnimationMixer]s (with [member AnimationMixer.callback_mode_process] set to [constant AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS]), and [RemoteTransform3D].
When [AnimatableBody3D] is moved, its linear and angular velocity are estimated and used to affect other physics bodies in its path. This makes it useful for moving platforms, doors, and other moving objects.
</description>
<tutorials>
<link title="Physics introduction">$DOCS_URL/tutorials/physics/physics_introduction.html</link>
<link title="Troubleshooting physics issues">$DOCS_URL/tutorials/physics/troubleshooting_physics_issues.html</link>
<link title="3D Physics Tests Demo">https://godotengine.org/asset-library/asset/2747</link>
<link title="Third Person Shooter (TPS) Demo">https://godotengine.org/asset-library/asset/2710</link>
<link title="3D Voxel Demo">https://godotengine.org/asset-library/asset/2755</link>
</tutorials>
<members>
<member name="sync_to_physics" type="bool" setter="set_sync_to_physics" getter="is_sync_to_physics_enabled" default="true">
If [code]true[/code], the body's movement will be synchronized to the physics frame. This is useful when animating movement via [AnimationPlayer], for example on moving platforms. Do [b]not[/b] use together with [method PhysicsBody3D.move_and_collide].
</member>
</members>
</class>

138
doc/classes/AnimatedSprite2D.xml Normal file
View File

@@ -0,0 +1,138 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimatedSprite2D" inherits="Node2D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Sprite node that contains multiple textures as frames to play for animation.
</brief_description>
<description>
[AnimatedSprite2D] is similar to the [Sprite2D] node, except it carries multiple textures as animation frames. Animations are created using a [SpriteFrames] resource, which allows you to import image files (or a folder containing said files) to provide the animation frames for the sprite. The [SpriteFrames] resource can be configured in the editor via the SpriteFrames bottom panel.
</description>
<tutorials>
<link title="2D Sprite animation">$DOCS_URL/tutorials/2d/2d_sprite_animation.html</link>
<link title="2D Dodge The Creeps Demo">https://godotengine.org/asset-library/asset/2712</link>
</tutorials>
<methods>
<method name="get_playing_speed" qualifiers="const">
<return type="float" />
<description>
Returns the actual playing speed of current animation or [code]0[/code] if not playing. This speed is the [member speed_scale] property multiplied by [code]custom_speed[/code] argument specified when calling the [method play] method.
Returns a negative value if the current animation is playing backwards.
</description>
</method>
<method name="is_playing" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if an animation is currently playing (even if [member speed_scale] and/or [code]custom_speed[/code] are [code]0[/code]).
</description>
</method>
<method name="pause">
<return type="void" />
<description>
Pauses the currently playing animation. The [member frame] and [member frame_progress] will be kept and calling [method play] or [method play_backwards] without arguments will resume the animation from the current playback position.
See also [method stop].
</description>
</method>
<method name="play">
<return type="void" />
<param index="0" name="name" type="StringName" default="&amp;&quot;&quot;" />
<param index="1" name="custom_speed" type="float" default="1.0" />
<param index="2" name="from_end" type="bool" default="false" />
<description>
Plays the animation with key [param name]. If [param custom_speed] is negative and [param from_end] is [code]true[/code], the animation will play backwards (which is equivalent to calling [method play_backwards]).
If this method is called with that same animation [param name], or with no [param name] parameter, the assigned animation will resume playing if it was paused.
</description>
</method>
<method name="play_backwards">
<return type="void" />
<param index="0" name="name" type="StringName" default="&amp;&quot;&quot;" />
<description>
Plays the animation with key [param name] in reverse.
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="set_frame_and_progress">
<return type="void" />
<param index="0" name="frame" type="int" />
<param index="1" name="progress" type="float" />
<description>
Sets [member frame] and [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]
var current_frame = animated_sprite.get_frame()
var current_progress = animated_sprite.get_frame_progress()
animated_sprite.play("walk_another_skin")
animated_sprite.set_frame_and_progress(current_frame, current_progress)
[/gdscript]
[/codeblocks]
</description>
</method>
<method name="stop">
<return type="void" />
<description>
Stops the currently playing animation. The animation position is reset to [code]0[/code] and the [code]custom_speed[/code] is reset to [code]1.0[/code]. See also [method pause].
</description>
</method>
</methods>
<members>
<member name="animation" type="StringName" setter="set_animation" getter="get_animation" default="&amp;&quot;default&quot;">
The current animation from the [member sprite_frames] resource. If this value is changed, the [member frame] counter and the [member frame_progress] are reset.
</member>
<member name="autoplay" type="String" setter="set_autoplay" getter="get_autoplay" default="&quot;&quot;">
The key of the animation to play when the scene loads.
</member>
<member name="centered" type="bool" setter="set_centered" getter="is_centered" default="true">
If [code]true[/code], texture will be centered.
[b]Note:[/b] For games with a pixel art aesthetic, textures may appear deformed when centered. This is caused by their position being between pixels. To prevent this, set this property to [code]false[/code], or consider enabling [member ProjectSettings.rendering/2d/snap/snap_2d_vertices_to_pixel] and [member ProjectSettings.rendering/2d/snap/snap_2d_transforms_to_pixel].
</member>
<member name="flip_h" type="bool" setter="set_flip_h" getter="is_flipped_h" default="false">
If [code]true[/code], texture is flipped horizontally.
</member>
<member name="flip_v" type="bool" setter="set_flip_v" getter="is_flipped_v" default="false">
If [code]true[/code], texture is flipped vertically.
</member>
<member name="frame" type="int" setter="set_frame" getter="get_frame" default="0">
The displayed animation frame's index. Setting this property also resets [member frame_progress]. If this is not desired, use [method set_frame_and_progress].
</member>
<member name="frame_progress" type="float" setter="set_frame_progress" getter="get_frame_progress" default="0.0">
The progress value between [code]0.0[/code] and [code]1.0[/code] until the current frame transitions to the next frame. If the animation is playing backwards, the value transitions from [code]1.0[/code] to [code]0.0[/code].
</member>
<member name="offset" type="Vector2" setter="set_offset" getter="get_offset" default="Vector2(0, 0)">
The texture's drawing offset.
</member>
<member name="speed_scale" type="float" setter="set_speed_scale" getter="get_speed_scale" default="1.0">
The speed scaling ratio. For example, if this value is [code]1[/code], then the animation plays at normal speed. If it's [code]0.5[/code], then it plays at half speed. If it's [code]2[/code], then it plays at double speed.
If set to a negative value, the animation is played in reverse. If set to [code]0[/code], the animation will not advance.
</member>
<member name="sprite_frames" type="SpriteFrames" setter="set_sprite_frames" getter="get_sprite_frames">
The [SpriteFrames] resource containing the animation(s). Allows you the option to load, edit, clear, make unique and save the states of the [SpriteFrames] resource.
</member>
</members>
<signals>
<signal name="animation_changed">
<description>
Emitted when [member animation] changes.
</description>
</signal>
<signal name="animation_finished">
<description>
Emitted when the animation reaches the end, or the start if it is played in reverse. When the animation finishes, it pauses the playback.
[b]Note:[/b] This signal is not emitted if an animation is looping.
</description>
</signal>
<signal name="animation_looped">
<description>
Emitted when the animation loops.
</description>
</signal>
<signal name="frame_changed">
<description>
Emitted when [member frame] changes.
</description>
</signal>
<signal name="sprite_frames_changed">
<description>
Emitted when [member sprite_frames] changes.
</description>
</signal>
</signals>
</class>

124
doc/classes/AnimatedSprite3D.xml Normal file
View File

@@ -0,0 +1,124 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimatedSprite3D" inherits="SpriteBase3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
2D sprite node in 3D world, that can use multiple 2D textures for animation.
</brief_description>
<description>
[AnimatedSprite3D] is similar to the [Sprite3D] node, except it carries multiple textures as animation [member sprite_frames]. Animations are created using a [SpriteFrames] resource, which allows you to import image files (or a folder containing said files) to provide the animation frames for the sprite. The [SpriteFrames] resource can be configured in the editor via the SpriteFrames bottom panel.
</description>
<tutorials>
<link title="2D Sprite animation (also applies to 3D)">$DOCS_URL/tutorials/2d/2d_sprite_animation.html</link>
</tutorials>
<methods>
<method name="get_playing_speed" qualifiers="const">
<return type="float" />
<description>
Returns the actual playing speed of current animation or [code]0[/code] if not playing. This speed is the [member speed_scale] property multiplied by [code]custom_speed[/code] argument specified when calling the [method play] method.
Returns a negative value if the current animation is playing backwards.
</description>
</method>
<method name="is_playing" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if an animation is currently playing (even if [member speed_scale] and/or [code]custom_speed[/code] are [code]0[/code]).
</description>
</method>
<method name="pause">
<return type="void" />
<description>
Pauses the currently playing animation. The [member frame] and [member frame_progress] will be kept and calling [method play] or [method play_backwards] without arguments will resume the animation from the current playback position.
See also [method stop].
</description>
</method>
<method name="play">
<return type="void" />
<param index="0" name="name" type="StringName" default="&amp;&quot;&quot;" />
<param index="1" name="custom_speed" type="float" default="1.0" />
<param index="2" name="from_end" type="bool" default="false" />
<description>
Plays the animation with key [param name]. If [param custom_speed] is negative and [param from_end] is [code]true[/code], the animation will play backwards (which is equivalent to calling [method play_backwards]).
If this method is called with that same animation [param name], or with no [param name] parameter, the assigned animation will resume playing if it was paused.
</description>
</method>
<method name="play_backwards">
<return type="void" />
<param index="0" name="name" type="StringName" default="&amp;&quot;&quot;" />
<description>
Plays the animation with key [param name] in reverse.
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="set_frame_and_progress">
<return type="void" />
<param index="0" name="frame" type="int" />
<param index="1" name="progress" type="float" />
<description>
Sets [member frame] and [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]
var current_frame = animated_sprite.get_frame()
var current_progress = animated_sprite.get_frame_progress()
animated_sprite.play("walk_another_skin")
animated_sprite.set_frame_and_progress(current_frame, current_progress)
[/gdscript]
[/codeblocks]
</description>
</method>
<method name="stop">
<return type="void" />
<description>
Stops the currently playing animation. The animation position is reset to [code]0[/code] and the [code]custom_speed[/code] is reset to [code]1.0[/code]. See also [method pause].
</description>
</method>
</methods>
<members>
<member name="animation" type="StringName" setter="set_animation" getter="get_animation" default="&amp;&quot;default&quot;">
The current animation from the [member sprite_frames] resource. If this value is changed, the [member frame] counter and the [member frame_progress] are reset.
</member>
<member name="autoplay" type="String" setter="set_autoplay" getter="get_autoplay" default="&quot;&quot;">
The key of the animation to play when the scene loads.
</member>
<member name="frame" type="int" setter="set_frame" getter="get_frame" default="0">
The displayed animation frame's index. Setting this property also resets [member frame_progress]. If this is not desired, use [method set_frame_and_progress].
</member>
<member name="frame_progress" type="float" setter="set_frame_progress" getter="get_frame_progress" default="0.0">
The progress value between [code]0.0[/code] and [code]1.0[/code] until the current frame transitions to the next frame. If the animation is playing backwards, the value transitions from [code]1.0[/code] to [code]0.0[/code].
</member>
<member name="speed_scale" type="float" setter="set_speed_scale" getter="get_speed_scale" default="1.0">
The speed scaling ratio. For example, if this value is [code]1[/code], then the animation plays at normal speed. If it's [code]0.5[/code], then it plays at half speed. If it's [code]2[/code], then it plays at double speed.
If set to a negative value, the animation is played in reverse. If set to [code]0[/code], the animation will not advance.
</member>
<member name="sprite_frames" type="SpriteFrames" setter="set_sprite_frames" getter="get_sprite_frames">
The [SpriteFrames] resource containing the animation(s). Allows you the option to load, edit, clear, make unique and save the states of the [SpriteFrames] resource.
</member>
</members>
<signals>
<signal name="animation_changed">
<description>
Emitted when [member animation] changes.
</description>
</signal>
<signal name="animation_finished">
<description>
Emitted when the animation reaches the end, or the start if it is played in reverse. When the animation finishes, it pauses the playback.
[b]Note:[/b] This signal is not emitted if an animation is looping.
</description>
</signal>
<signal name="animation_looped">
<description>
Emitted when the animation loops.
</description>
</signal>
<signal name="frame_changed">
<description>
Emitted when [member frame] changes.
</description>
</signal>
<signal name="sprite_frames_changed">
<description>
Emitted when [member sprite_frames] changes.
</description>
</signal>
</signals>
</class>

71
doc/classes/AnimatedTexture.xml Normal file
View File

@@ -0,0 +1,71 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimatedTexture" inherits="Texture2D" deprecated="This class does not work properly in current versions and may be removed in the future. There is currently no equivalent workaround." xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Proxy texture for simple frame-based animations.
</brief_description>
<description>
[AnimatedTexture] is a resource format for frame-based animations, where multiple textures can be chained automatically with a predefined delay for each frame. Unlike [AnimationPlayer] or [AnimatedSprite2D], it isn't a [Node], but has the advantage of being usable anywhere a [Texture2D] resource can be used, e.g. in a [TileSet].
The playback of the animation is controlled by the [member speed_scale] property, as well as each frame's duration (see [method set_frame_duration]). The animation loops, i.e. it will restart at frame 0 automatically after playing the last frame.
[AnimatedTexture] currently requires all frame textures to have the same size, otherwise the bigger ones will be cropped to match the smallest one.
[b]Note:[/b] AnimatedTexture doesn't support using [AtlasTexture]s. Each frame needs to be a separate [Texture2D].
[b]Warning:[/b] The current implementation is not efficient for the modern renderers.
</description>
<tutorials>
</tutorials>
<methods>
<method name="get_frame_duration" qualifiers="const">
<return type="float" />
<param index="0" name="frame" type="int" />
<description>
Returns the given [param frame]'s duration, in seconds.
</description>
</method>
<method name="get_frame_texture" qualifiers="const">
<return type="Texture2D" />
<param index="0" name="frame" type="int" />
<description>
Returns the given frame's [Texture2D].
</description>
</method>
<method name="set_frame_duration">
<return type="void" />
<param index="0" name="frame" type="int" />
<param index="1" name="duration" type="float" />
<description>
Sets the duration of any given [param frame]. The final duration is affected by the [member speed_scale]. If set to [code]0[/code], the frame is skipped during playback.
</description>
</method>
<method name="set_frame_texture">
<return type="void" />
<param index="0" name="frame" type="int" />
<param index="1" name="texture" type="Texture2D" />
<description>
Assigns a [Texture2D] to the given frame. Frame IDs start at 0, so the first frame has ID 0, and the last frame of the animation has ID [member frames] - 1.
You can define any number of textures up to [constant MAX_FRAMES], but keep in mind that only frames from 0 to [member frames] - 1 will be part of the animation.
</description>
</method>
</methods>
<members>
<member name="current_frame" type="int" setter="set_current_frame" getter="get_current_frame">
Sets the currently visible frame of the texture. Setting this frame while playing resets the current frame time, so the newly selected frame plays for its whole configured frame duration.
</member>
<member name="frames" type="int" setter="set_frames" getter="get_frames" default="1">
Number of frames to use in the animation. While you can create the frames independently with [method set_frame_texture], you need to set this value for the animation to take new frames into account. The maximum number of frames is [constant MAX_FRAMES].
</member>
<member name="one_shot" type="bool" setter="set_one_shot" getter="get_one_shot" default="false">
If [code]true[/code], the animation will only play once and will not loop back to the first frame after reaching the end. Note that reaching the end will not set [member pause] to [code]true[/code].
</member>
<member name="pause" type="bool" setter="set_pause" getter="get_pause" default="false">
If [code]true[/code], the animation will pause where it currently is (i.e. at [member current_frame]). The animation will continue from where it was paused when changing this property to [code]false[/code].
</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="speed_scale" type="float" setter="set_speed_scale" getter="get_speed_scale" default="1.0">
The animation speed is multiplied by this value. If set to a negative value, the animation is played in reverse.
</member>
</members>
<constants>
<constant name="MAX_FRAMES" value="256">
The maximum number of frames supported by [AnimatedTexture]. If you need more frames in your animation, use [AnimationPlayer] or [AnimatedSprite2D].
</constant>
</constants>
</class>

778
doc/classes/Animation.xml Normal file
View File

@@ -0,0 +1,778 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="Animation" inherits="Resource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Holds data that can be used to animate anything in the engine.
</brief_description>
<description>
This resource holds data that can be used to animate anything in the engine. Animations are divided into tracks and each track must be linked to a node. The state of that node can be changed through time, by adding timed keys (events) to the track.
[codeblocks]
[gdscript]
# This creates an animation that makes the node "Enemy" move to the right by
# 100 pixels in 2.0 seconds.
var animation = Animation.new()
var track_index = animation.add_track(Animation.TYPE_VALUE)
animation.track_set_path(track_index, "Enemy:position:x")
animation.track_insert_key(track_index, 0.0, 0)
animation.track_insert_key(track_index, 2.0, 100)
animation.length = 2.0
[/gdscript]
[csharp]
// This creates an animation that makes the node "Enemy" move to the right by
// 100 pixels in 2.0 seconds.
var animation = new Animation();
int trackIndex = animation.AddTrack(Animation.TrackType.Value);
animation.TrackSetPath(trackIndex, "Enemy:position:x");
animation.TrackInsertKey(trackIndex, 0.0f, 0);
animation.TrackInsertKey(trackIndex, 2.0f, 100);
animation.Length = 2.0f;
[/csharp]
[/codeblocks]
Animations are just data containers, and must be added to nodes such as an [AnimationPlayer] to be played back. Animation tracks have different types, each with its own set of dedicated methods. Check [enum TrackType] to see available types.
[b]Note:[/b] For 3D position/rotation/scale, using the dedicated [constant TYPE_POSITION_3D], [constant TYPE_ROTATION_3D] and [constant TYPE_SCALE_3D] track types instead of [constant TYPE_VALUE] is recommended for performance reasons.
</description>
<tutorials>
<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" />
<param index="1" name="at_position" type="int" default="-1" />
<description>
Adds a track to the Animation.
</description>
</method>
<method name="animation_track_get_key_animation" qualifiers="const">
<return type="StringName" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="key_idx" type="int" />
<description>
Returns the animation name at the key identified by [param key_idx]. The [param track_idx] must be the index of an Animation Track.
</description>
</method>
<method name="animation_track_insert_key">
<return type="int" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="time" type="float" />
<param index="2" name="animation" type="StringName" />
<description>
Inserts a key with value [param animation] at the given [param time] (in seconds). The [param track_idx] must be the index of an Animation Track.
</description>
</method>
<method name="animation_track_set_key_animation">
<return type="void" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="key_idx" type="int" />
<param index="2" name="animation" type="StringName" />
<description>
Sets the key identified by [param key_idx] to value [param animation]. The [param track_idx] must be the index of an Animation Track.
</description>
</method>
<method name="audio_track_get_key_end_offset" qualifiers="const">
<return type="float" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="key_idx" type="int" />
<description>
Returns the end offset of the key identified by [param key_idx]. The [param track_idx] must be the index of an Audio Track.
End offset is the number of seconds cut off at the ending of the audio stream.
</description>
</method>
<method name="audio_track_get_key_start_offset" qualifiers="const">
<return type="float" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="key_idx" type="int" />
<description>
Returns the start offset of the key identified by [param key_idx]. The [param track_idx] must be the index of an Audio Track.
Start offset is the number of seconds cut off at the beginning of the audio stream.
</description>
</method>
<method name="audio_track_get_key_stream" qualifiers="const">
<return type="Resource" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="key_idx" type="int" />
<description>
Returns the audio stream of the key identified by [param key_idx]. The [param track_idx] must be the index of an Audio Track.
</description>
</method>
<method name="audio_track_insert_key">
<return type="int" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="time" type="float" />
<param index="2" name="stream" type="Resource" />
<param index="3" name="start_offset" type="float" default="0" />
<param index="4" name="end_offset" type="float" default="0" />
<description>
Inserts an Audio Track key at the given [param time] in seconds. The [param track_idx] must be the index of an Audio Track.
[param stream] is the [AudioStream] resource to play. [param start_offset] is the number of seconds cut off at the beginning of the audio stream, while [param end_offset] is at the ending.
</description>
</method>
<method name="audio_track_is_use_blend" qualifiers="const">
<return type="bool" />
<param index="0" name="track_idx" type="int" />
<description>
Returns [code]true[/code] if the track at [param track_idx] will be blended with other animations.
</description>
</method>
<method name="audio_track_set_key_end_offset">
<return type="void" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="key_idx" type="int" />
<param index="2" name="offset" type="float" />
<description>
Sets the end offset of the key identified by [param key_idx] to value [param offset]. The [param track_idx] must be the index of an Audio Track.
</description>
</method>
<method name="audio_track_set_key_start_offset">
<return type="void" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="key_idx" type="int" />
<param index="2" name="offset" type="float" />
<description>
Sets the start offset of the key identified by [param key_idx] to value [param offset]. The [param track_idx] must be the index of an Audio Track.
</description>
</method>
<method name="audio_track_set_key_stream">
<return type="void" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="key_idx" type="int" />
<param index="2" name="stream" type="Resource" />
<description>
Sets the stream of the key identified by [param key_idx] to value [param stream]. The [param track_idx] must be the index of an Audio Track.
</description>
</method>
<method name="audio_track_set_use_blend">
<return type="void" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="enable" type="bool" />
<description>
Sets whether the track will be blended with other animations. If [code]true[/code], the audio playback volume changes depending on the blend value.
</description>
</method>
<method name="bezier_track_get_key_in_handle" qualifiers="const">
<return type="Vector2" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="key_idx" type="int" />
<description>
Returns the in handle of the key identified by [param key_idx]. The [param track_idx] must be the index of a Bezier Track.
</description>
</method>
<method name="bezier_track_get_key_out_handle" qualifiers="const">
<return type="Vector2" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="key_idx" type="int" />
<description>
Returns the out handle of the key identified by [param key_idx]. The [param track_idx] must be the index of a Bezier Track.
</description>
</method>
<method name="bezier_track_get_key_value" qualifiers="const">
<return type="float" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="key_idx" type="int" />
<description>
Returns the value of the key identified by [param key_idx]. The [param track_idx] must be the index of a Bezier Track.
</description>
</method>
<method name="bezier_track_insert_key">
<return type="int" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="time" type="float" />
<param index="2" name="value" type="float" />
<param index="3" name="in_handle" type="Vector2" default="Vector2(0, 0)" />
<param index="4" name="out_handle" type="Vector2" default="Vector2(0, 0)" />
<description>
Inserts a Bezier Track key at the given [param time] in seconds. The [param track_idx] must be the index of a Bezier Track.
[param in_handle] is the left-side weight of the added Bezier curve point, [param out_handle] is the right-side one, while [param value] is the actual value at this point.
</description>
</method>
<method name="bezier_track_interpolate" qualifiers="const">
<return type="float" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="time" type="float" />
<description>
Returns the interpolated value at the given [param time] (in seconds). The [param track_idx] must be the index of a Bezier Track.
</description>
</method>
<method name="bezier_track_set_key_in_handle">
<return type="void" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="key_idx" type="int" />
<param index="2" name="in_handle" type="Vector2" />
<param index="3" name="balanced_value_time_ratio" type="float" default="1.0" />
<description>
Sets the in handle of the key identified by [param key_idx] to value [param in_handle]. The [param track_idx] must be the index of a Bezier Track.
</description>
</method>
<method name="bezier_track_set_key_out_handle">
<return type="void" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="key_idx" type="int" />
<param index="2" name="out_handle" type="Vector2" />
<param index="3" name="balanced_value_time_ratio" type="float" default="1.0" />
<description>
Sets the out handle of the key identified by [param key_idx] to value [param out_handle]. The [param track_idx] must be the index of a Bezier Track.
</description>
</method>
<method name="bezier_track_set_key_value">
<return type="void" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="key_idx" type="int" />
<param index="2" name="value" type="float" />
<description>
Sets the value of the key identified by [param key_idx] to the given value. The [param track_idx] must be the index of a Bezier Track.
</description>
</method>
<method name="blend_shape_track_insert_key">
<return type="int" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="time" type="float" />
<param index="2" name="amount" type="float" />
<description>
Inserts a key in a given blend shape track. Returns the key index.
</description>
</method>
<method name="blend_shape_track_interpolate" qualifiers="const">
<return type="float" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="time_sec" type="float" />
<param index="2" name="backward" type="bool" default="false" />
<description>
Returns the interpolated blend shape value at the given time (in seconds). The [param track_idx] must be the index of a blend shape track.
</description>
</method>
<method name="clear">
<return type="void" />
<description>
Clear the animation (clear all tracks and reset all).
</description>
</method>
<method name="compress">
<return type="void" />
<param index="0" name="page_size" type="int" default="8192" />
<param index="1" name="fps" type="int" default="120" />
<param index="2" name="split_tolerance" type="float" default="4.0" />
<description>
Compress the animation and all its tracks in-place. This will make [method track_is_compressed] return [code]true[/code] once called on this [Animation]. Compressed tracks require less memory to be played, and are designed to be used for complex 3D animations (such as cutscenes) imported from external 3D software. Compression is lossy, but the difference is usually not noticeable in real world conditions.
[b]Note:[/b] Compressed tracks have various limitations (such as not being editable from the editor), so only use compressed animations if you actually need them.
</description>
</method>
<method name="copy_track">
<return type="void" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="to_animation" type="Animation" />
<description>
Adds a new track to [param to_animation] that is a copy of the given track from this animation.
</description>
</method>
<method name="find_track" qualifiers="const">
<return type="int" />
<param index="0" name="path" type="NodePath" />
<param index="1" name="type" type="int" enum="Animation.TrackType" />
<description>
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" />
<param index="1" name="key_idx" type="int" />
<description>
Returns the method name of a method track.
</description>
</method>
<method name="method_track_get_params" qualifiers="const">
<return type="Array" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="key_idx" type="int" />
<description>
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" />
<param index="1" name="time" type="float" />
<param index="2" name="position" type="Vector3" />
<description>
Inserts a key in a given 3D position track. Returns the key index.
</description>
</method>
<method name="position_track_interpolate" qualifiers="const">
<return type="Vector3" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="time_sec" type="float" />
<param index="2" name="backward" type="bool" default="false" />
<description>
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" />
<description>
Removes a track by specifying the track index.
</description>
</method>
<method name="rotation_track_insert_key">
<return type="int" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="time" type="float" />
<param index="2" name="rotation" type="Quaternion" />
<description>
Inserts a key in a given 3D rotation track. Returns the key index.
</description>
</method>
<method name="rotation_track_interpolate" qualifiers="const">
<return type="Quaternion" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="time_sec" type="float" />
<param index="2" name="backward" type="bool" default="false" />
<description>
Returns the interpolated rotation value at the given time (in seconds). The [param track_idx] must be the index of a 3D rotation track.
</description>
</method>
<method name="scale_track_insert_key">
<return type="int" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="time" type="float" />
<param index="2" name="scale" type="Vector3" />
<description>
Inserts a key in a given 3D scale track. Returns the key index.
</description>
</method>
<method name="scale_track_interpolate" qualifiers="const">
<return type="Vector3" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="time_sec" type="float" />
<param index="2" name="backward" type="bool" default="false" />
<description>
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" />
<param index="1" name="time" type="float" />
<param index="2" name="find_mode" type="int" enum="Animation.FindMode" default="0" />
<param index="3" name="limit" type="bool" default="false" />
<param index="4" name="backward" type="bool" default="false" />
<description>
Finds the key index by time in a given track. Optionally, only find it if the approx/exact time is given.
If [param limit] is [code]true[/code], it does not return keys outside the animation range.
If [param backward] is [code]true[/code], the direction is reversed in methods that rely on one directional processing.
For example, in case [param find_mode] is [constant FIND_MODE_NEAREST], if there is no key in the current position just after seeked, the first key found is retrieved by searching before the position, but if [param backward] is [code]true[/code], the first key found is retrieved after the position.
</description>
</method>
<method name="track_get_interpolation_loop_wrap" qualifiers="const">
<return type="bool" />
<param index="0" name="track_idx" type="int" />
<description>
Returns [code]true[/code] if the track at [param track_idx] wraps the interpolation loop. New tracks wrap the interpolation loop by default.
</description>
</method>
<method name="track_get_interpolation_type" qualifiers="const">
<return type="int" enum="Animation.InterpolationType" />
<param index="0" name="track_idx" type="int" />
<description>
Returns the interpolation type of a given track.
</description>
</method>
<method name="track_get_key_count" qualifiers="const">
<return type="int" />
<param index="0" name="track_idx" type="int" />
<description>
Returns the number of keys in a given track.
</description>
</method>
<method name="track_get_key_time" qualifiers="const">
<return type="float" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="key_idx" type="int" />
<description>
Returns the time at which the key is located.
</description>
</method>
<method name="track_get_key_transition" qualifiers="const">
<return type="float" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="key_idx" type="int" />
<description>
Returns the transition curve (easing) for a specific key (see the built-in math function [method @GlobalScope.ease]).
</description>
</method>
<method name="track_get_key_value" qualifiers="const">
<return type="Variant" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="key_idx" type="int" />
<description>
Returns the value of a given key in a given track.
</description>
</method>
<method name="track_get_path" qualifiers="const">
<return type="NodePath" />
<param index="0" name="track_idx" type="int" />
<description>
Gets the path of a track. For more information on the path format, see [method track_set_path].
</description>
</method>
<method name="track_get_type" qualifiers="const">
<return type="int" enum="Animation.TrackType" />
<param index="0" name="track_idx" type="int" />
<description>
Gets the type of a track.
</description>
</method>
<method name="track_insert_key">
<return type="int" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="time" type="float" />
<param index="2" name="key" type="Variant" />
<param index="3" name="transition" type="float" default="1" />
<description>
Inserts a generic key in a given track. Returns the key index.
</description>
</method>
<method name="track_is_compressed" qualifiers="const">
<return type="bool" />
<param index="0" name="track_idx" type="int" />
<description>
Returns [code]true[/code] if the track is compressed, [code]false[/code] otherwise. See also [method compress].
</description>
</method>
<method name="track_is_enabled" qualifiers="const">
<return type="bool" />
<param index="0" name="track_idx" type="int" />
<description>
Returns [code]true[/code] if the track at index [param track_idx] is enabled.
</description>
</method>
<method name="track_is_imported" qualifiers="const">
<return type="bool" />
<param index="0" name="track_idx" type="int" />
<description>
Returns [code]true[/code] if the given track is imported. Else, return [code]false[/code].
</description>
</method>
<method name="track_move_down">
<return type="void" />
<param index="0" name="track_idx" type="int" />
<description>
Moves a track down.
</description>
</method>
<method name="track_move_to">
<return type="void" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="to_idx" type="int" />
<description>
Changes the index position of track [param track_idx] to the one defined in [param to_idx].
</description>
</method>
<method name="track_move_up">
<return type="void" />
<param index="0" name="track_idx" type="int" />
<description>
Moves a track up.
</description>
</method>
<method name="track_remove_key">
<return type="void" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="key_idx" type="int" />
<description>
Removes a key by index in a given track.
</description>
</method>
<method name="track_remove_key_at_time">
<return type="void" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="time" type="float" />
<description>
Removes a key at [param time] in a given track.
</description>
</method>
<method name="track_set_enabled">
<return type="void" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="enabled" type="bool" />
<description>
Enables/disables the given track. Tracks are enabled by default.
</description>
</method>
<method name="track_set_imported">
<return type="void" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="imported" type="bool" />
<description>
Sets the given track as imported or not.
</description>
</method>
<method name="track_set_interpolation_loop_wrap">
<return type="void" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="interpolation" type="bool" />
<description>
If [code]true[/code], the track at [param track_idx] wraps the interpolation loop.
</description>
</method>
<method name="track_set_interpolation_type">
<return type="void" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="interpolation" type="int" enum="Animation.InterpolationType" />
<description>
Sets the interpolation type of a given track.
</description>
</method>
<method name="track_set_key_time">
<return type="void" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="key_idx" type="int" />
<param index="2" name="time" type="float" />
<description>
Sets the time of an existing key.
</description>
</method>
<method name="track_set_key_transition">
<return type="void" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="key_idx" type="int" />
<param index="2" name="transition" type="float" />
<description>
Sets the transition curve (easing) for a specific key (see the built-in math function [method @GlobalScope.ease]).
</description>
</method>
<method name="track_set_key_value">
<return type="void" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="key" type="int" />
<param index="2" name="value" type="Variant" />
<description>
Sets the value of an existing key.
</description>
</method>
<method name="track_set_path">
<return type="void" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="path" type="NodePath" />
<description>
Sets the path of a track. Paths must be valid scene-tree paths to a node and must be specified starting from the [member AnimationMixer.root_node] that will reproduce the animation. Tracks that control properties or bones must append their name after the path, separated by [code]":"[/code].
For example, [code]"character/skeleton:ankle"[/code] or [code]"character/mesh:transform/local"[/code].
</description>
</method>
<method name="track_swap">
<return type="void" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="with_idx" type="int" />
<description>
Swaps the track [param track_idx]'s index position with the track [param with_idx].
</description>
</method>
<method name="value_track_get_update_mode" qualifiers="const">
<return type="int" enum="Animation.UpdateMode" />
<param index="0" name="track_idx" type="int" />
<description>
Returns the update mode of a value track.
</description>
</method>
<method name="value_track_interpolate" qualifiers="const">
<return type="Variant" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="time_sec" type="float" />
<param index="2" name="backward" type="bool" default="false" />
<description>
Returns the interpolated value at the given time (in seconds). The [param track_idx] must be the index of a value track.
A [param backward] mainly affects the direction of key retrieval of the track with [constant UPDATE_DISCRETE] converted by [constant AnimationMixer.ANIMATION_CALLBACK_MODE_DISCRETE_FORCE_CONTINUOUS] to match the result with [method track_find_key].
</description>
</method>
<method name="value_track_set_update_mode">
<return type="void" />
<param index="0" name="track_idx" type="int" />
<param index="1" name="mode" type="int" enum="Animation.UpdateMode" />
<description>
Sets the update mode of a value track.
</description>
</method>
</methods>
<members>
<member name="capture_included" type="bool" setter="" getter="is_capture_included" default="false">
Returns [code]true[/code] if the capture track is included. This is a cached readonly value for performance.
</member>
<member name="length" type="float" setter="set_length" getter="get_length" default="1.0">
The total length of the animation (in seconds).
[b]Note:[/b] Length is not delimited by the last key, as this one may be before or after the end to ensure correct interpolation and looping.
</member>
<member name="loop_mode" type="int" setter="set_loop_mode" getter="get_loop_mode" enum="Animation.LoopMode" default="0">
Determines the behavior of both ends of the animation timeline during animation playback. This indicates whether and how the animation should be restarted, and is also used to correctly interpolate animation cycles.
</member>
<member name="step" type="float" setter="set_step" getter="get_step" default="0.033333335">
The animation step value.
</member>
</members>
<constants>
<constant name="TYPE_VALUE" value="0" enum="TrackType">
Value tracks set values in node properties, but only those which can be interpolated. For 3D position/rotation/scale, using the dedicated [constant TYPE_POSITION_3D], [constant TYPE_ROTATION_3D] and [constant TYPE_SCALE_3D] track types instead of [constant TYPE_VALUE] is recommended for performance reasons.
</constant>
<constant name="TYPE_POSITION_3D" value="1" enum="TrackType">
3D position track (values are stored in [Vector3]s).
</constant>
<constant name="TYPE_ROTATION_3D" value="2" enum="TrackType">
3D rotation track (values are stored in [Quaternion]s).
</constant>
<constant name="TYPE_SCALE_3D" value="3" enum="TrackType">
3D scale track (values are stored in [Vector3]s).
</constant>
<constant name="TYPE_BLEND_SHAPE" value="4" enum="TrackType">
Blend shape track.
</constant>
<constant name="TYPE_METHOD" value="5" enum="TrackType">
Method tracks call functions with given arguments per key.
</constant>
<constant name="TYPE_BEZIER" value="6" enum="TrackType">
Bezier tracks are used to interpolate a value using custom curves. They can also be used to animate sub-properties of vectors and colors (e.g. alpha value of a [Color]).
</constant>
<constant name="TYPE_AUDIO" value="7" enum="TrackType">
Audio tracks are used to play an audio stream with either type of [AudioStreamPlayer]. The stream can be trimmed and previewed in the animation.
</constant>
<constant name="TYPE_ANIMATION" value="8" enum="TrackType">
Animation tracks play animations in other [AnimationPlayer] nodes.
</constant>
<constant name="INTERPOLATION_NEAREST" value="0" enum="InterpolationType">
No interpolation (nearest value).
</constant>
<constant name="INTERPOLATION_LINEAR" value="1" enum="InterpolationType">
Linear interpolation.
</constant>
<constant name="INTERPOLATION_CUBIC" value="2" enum="InterpolationType">
Cubic interpolation. This looks smoother than linear interpolation, but is more expensive to interpolate. Stick to [constant INTERPOLATION_LINEAR] for complex 3D animations imported from external software, even if it requires using a higher animation framerate in return.
</constant>
<constant name="INTERPOLATION_LINEAR_ANGLE" value="3" enum="InterpolationType">
Linear interpolation with shortest path rotation.
[b]Note:[/b] The result value is always normalized and may not match the key value.
</constant>
<constant name="INTERPOLATION_CUBIC_ANGLE" value="4" enum="InterpolationType">
Cubic interpolation with shortest path rotation.
[b]Note:[/b] The result value is always normalized and may not match the key value.
</constant>
<constant name="UPDATE_CONTINUOUS" value="0" enum="UpdateMode">
Update between keyframes and hold the value.
</constant>
<constant name="UPDATE_DISCRETE" value="1" enum="UpdateMode">
Update at the keyframes.
</constant>
<constant name="UPDATE_CAPTURE" value="2" enum="UpdateMode">
Same as [constant UPDATE_CONTINUOUS] but works as a flag to capture the value of the current object and perform interpolation in some methods. See also [method AnimationMixer.capture], [member AnimationPlayer.playback_auto_capture], and [method AnimationPlayer.play_with_capture].
</constant>
<constant name="LOOP_NONE" value="0" enum="LoopMode">
At both ends of the animation, the animation will stop playing.
</constant>
<constant name="LOOP_LINEAR" value="1" enum="LoopMode">
At both ends of the animation, the animation will be repeated without changing the playback direction.
</constant>
<constant name="LOOP_PINGPONG" value="2" enum="LoopMode">
Repeats playback and reverse playback at both ends of the animation.
</constant>
<constant name="LOOPED_FLAG_NONE" value="0" enum="LoopedFlag">
This flag indicates that the animation proceeds without any looping.
</constant>
<constant name="LOOPED_FLAG_END" value="1" enum="LoopedFlag">
This flag indicates that the animation has reached the end of the animation and just after loop processed.
</constant>
<constant name="LOOPED_FLAG_START" value="2" enum="LoopedFlag">
This flag indicates that the animation has reached the start of the animation and just after loop processed.
</constant>
<constant name="FIND_MODE_NEAREST" value="0" enum="FindMode">
Finds the nearest time key.
</constant>
<constant name="FIND_MODE_APPROX" value="1" enum="FindMode">
Finds only the key with approximating the time.
</constant>
<constant name="FIND_MODE_EXACT" value="2" enum="FindMode">
Finds only the key with matching the time.
</constant>
</constants>
</class>

91
doc/classes/AnimationLibrary.xml Normal file
View File

@@ -0,0 +1,91 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimationLibrary" inherits="Resource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Container for [Animation] resources.
</brief_description>
<description>
An animation library stores a set of animations accessible through [StringName] keys, for use with [AnimationPlayer] nodes.
</description>
<tutorials>
<link title="Animation tutorial index">$DOCS_URL/tutorials/animation/index.html</link>
</tutorials>
<methods>
<method name="add_animation">
<return type="int" enum="Error" />
<param index="0" name="name" type="StringName" />
<param index="1" name="animation" type="Animation" />
<description>
Adds the [param animation] to the library, accessible by the key [param name].
</description>
</method>
<method name="get_animation" qualifiers="const">
<return type="Animation" />
<param index="0" name="name" type="StringName" />
<description>
Returns the [Animation] with the key [param name]. If the animation does not exist, [code]null[/code] is returned and an error is logged.
</description>
</method>
<method name="get_animation_list" qualifiers="const">
<return type="StringName[]" />
<description>
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" />
<description>
Returns [code]true[/code] if the library stores an [Animation] with [param name] as the key.
</description>
</method>
<method name="remove_animation">
<return type="void" />
<param index="0" name="name" type="StringName" />
<description>
Removes the [Animation] with the key [param name].
</description>
</method>
<method name="rename_animation">
<return type="void" />
<param index="0" name="name" type="StringName" />
<param index="1" name="newname" type="StringName" />
<description>
Changes the key of the [Animation] associated with the key [param name] to [param newname].
</description>
</method>
</methods>
<signals>
<signal name="animation_added">
<param index="0" name="name" type="StringName" />
<description>
Emitted when an [Animation] is added, under the key [param name].
</description>
</signal>
<signal name="animation_changed">
<param index="0" name="name" type="StringName" />
<description>
Emitted when there's a change in one of the animations, e.g. tracks are added, moved or have changed paths. [param name] is the key of the animation that was changed.
See also [signal Resource.changed], which this acts as a relay for.
</description>
</signal>
<signal name="animation_removed">
<param index="0" name="name" type="StringName" />
<description>
Emitted when an [Animation] stored with the key [param name] is removed.
</description>
</signal>
<signal name="animation_renamed">
<param index="0" name="name" type="StringName" />
<param index="1" name="to_name" type="StringName" />
<description>
Emitted when the key for an [Animation] is changed, from [param name] to [param to_name].
</description>
</signal>
</signals>
</class>

411
doc/classes/AnimationMixer.xml Normal file
View File

@@ -0,0 +1,411 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimationMixer" inherits="Node" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Base class for [AnimationPlayer] and [AnimationTree].
</brief_description>
<description>
Base class for [AnimationPlayer] and [AnimationTree] to manage animation lists. It also has general properties and methods for playback and blending.
After instantiating the playback information data within the extended class, the blending is processed by the [AnimationMixer].
</description>
<tutorials>
<link title="Migrating Animations from Godot 4.0 to 4.3">https://godotengine.org/article/migrating-animations-from-godot-4-0-to-4-3/</link>
</tutorials>
<methods>
<method name="_post_process_key_value" qualifiers="virtual const">
<return type="Variant" />
<param index="0" name="animation" type="Animation" />
<param index="1" name="track" type="int" />
<param index="2" name="value" type="Variant" />
<param index="3" name="object_id" type="int" />
<param index="4" name="object_sub_idx" type="int" />
<description>
A virtual function for processing after getting a key during playback.
</description>
</method>
<method name="add_animation_library">
<return type="int" enum="Error" />
<param index="0" name="name" type="StringName" />
<param index="1" name="library" type="AnimationLibrary" />
<description>
Adds [param library] to the animation player, under the key [param name].
AnimationMixer has a global library by default with an empty string as key. For adding an animation to the global library:
[codeblocks]
[gdscript]
var global_library = mixer.get_animation_library("")
global_library.add_animation("animation_name", animation_resource)
[/gdscript]
[/codeblocks]
</description>
</method>
<method name="advance">
<return type="void" />
<param index="0" name="delta" type="float" />
<description>
Manually advance the animations by the specified time (in seconds).
</description>
</method>
<method name="capture">
<return type="void" />
<param index="0" name="name" type="StringName" />
<param index="1" name="duration" type="float" />
<param index="2" name="trans_type" type="int" enum="Tween.TransitionType" default="0" />
<param index="3" name="ease_type" type="int" enum="Tween.EaseType" default="0" />
<description>
If the animation track specified by [param name] has an option [constant Animation.UPDATE_CAPTURE], stores current values of the objects indicated by the track path as a cache. If there is already a captured cache, the old cache is discarded.
After this it will interpolate with current animation blending result during the playback process for the time specified by [param duration], working like a crossfade.
You can specify [param trans_type] as the curve for the interpolation. For better results, it may be appropriate to specify [constant Tween.TRANS_LINEAR] for cases where the first key of the track begins with a non-zero value or where the key value does not change, and [constant Tween.TRANS_QUAD] for cases where the key value changes linearly.
</description>
</method>
<method name="clear_caches">
<return type="void" />
<description>
[AnimationMixer] caches animated nodes. It may not notice if a node disappears; [method clear_caches] forces it to update the cache again.
</description>
</method>
<method name="find_animation" qualifiers="const">
<return type="StringName" />
<param index="0" name="animation" type="Animation" />
<description>
Returns the key of [param animation] or an empty [StringName] if not found.
</description>
</method>
<method name="find_animation_library" qualifiers="const">
<return type="StringName" />
<param index="0" name="animation" type="Animation" />
<description>
Returns the key for the [AnimationLibrary] that contains [param animation] or an empty [StringName] if not found.
</description>
</method>
<method name="get_animation" qualifiers="const">
<return type="Animation" />
<param index="0" name="name" type="StringName" />
<description>
Returns the [Animation] with the key [param name]. If the animation does not exist, [code]null[/code] is returned and an error is logged.
</description>
</method>
<method name="get_animation_library" qualifiers="const">
<return type="AnimationLibrary" />
<param index="0" name="name" type="StringName" />
<description>
Returns the first [AnimationLibrary] with key [param name] or [code]null[/code] if not found.
To get the [AnimationMixer]'s global animation library, use [code]get_animation_library("")[/code].
</description>
</method>
<method name="get_animation_library_list" qualifiers="const">
<return type="StringName[]" />
<description>
Returns the list of stored library keys.
</description>
</method>
<method name="get_animation_list" qualifiers="const">
<return type="PackedStringArray" />
<description>
Returns the list of stored animation keys.
</description>
</method>
<method name="get_root_motion_position" qualifiers="const">
<return type="Vector3" />
<description>
Retrieve the motion delta of position with the [member root_motion_track] as a [Vector3] that can be used elsewhere.
If [member root_motion_track] is not a path to a track of type [constant Animation.TYPE_POSITION_3D], returns [code]Vector3(0, 0, 0)[/code].
See also [member root_motion_track] and [RootMotionView].
The most basic example is applying position to [CharacterBody3D]:
[codeblocks]
[gdscript]
var current_rotation
func _process(delta):
if Input.is_action_just_pressed("animate"):
current_rotation = get_quaternion()
state_machine.travel("Animate")
var velocity = current_rotation * animation_tree.get_root_motion_position() / delta
set_velocity(velocity)
move_and_slide()
[/gdscript]
[/codeblocks]
By using this in combination with [method get_root_motion_rotation_accumulator], you can apply the root motion position more correctly to account for the rotation of the node.
[codeblocks]
[gdscript]
func _process(delta):
if Input.is_action_just_pressed("animate"):
state_machine.travel("Animate")
set_quaternion(get_quaternion() * animation_tree.get_root_motion_rotation())
var velocity = (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], returns 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]
[/codeblocks]
</description>
</method>
<method name="get_root_motion_position_accumulator" qualifiers="const">
<return type="Vector3" />
<description>
Retrieve the blended value of the position tracks with the [member root_motion_track] as a [Vector3] that can be used elsewhere.
This is useful in cases where you want to respect the initial key values of the animation.
For example, if an animation with only one key [code]Vector3(0, 0, 0)[/code] is played in the previous frame and then an animation with only one key [code]Vector3(1, 0, 1)[/code] is played in the next frame, the difference can be calculated as follows:
[codeblocks]
[gdscript]
var prev_root_motion_position_accumulator
func _process(delta):
if Input.is_action_just_pressed("animate"):
state_machine.travel("Animate")
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]
[/codeblocks]
However, if the animation loops, an unintended discrete change may occur, so this is only useful for some simple use cases.
</description>
</method>
<method name="get_root_motion_rotation" qualifiers="const">
<return type="Quaternion" />
<description>
Retrieve the motion delta of rotation with the [member root_motion_track] as a [Quaternion] that can be used elsewhere.
If [member root_motion_track] is not a path to a track of type [constant Animation.TYPE_ROTATION_3D], returns [code]Quaternion(0, 0, 0, 1)[/code].
See also [member root_motion_track] and [RootMotionView].
The most basic example is applying rotation to [CharacterBody3D]:
[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())
[/gdscript]
[/codeblocks]
</description>
</method>
<method name="get_root_motion_rotation_accumulator" qualifiers="const">
<return type="Quaternion" />
<description>
Retrieve the blended value of the rotation tracks with the [member root_motion_track] as a [Quaternion] that can be used elsewhere.
This is necessary to apply the root motion position correctly, taking rotation into account. See also [method get_root_motion_position].
Also, this is useful in cases where you want to respect the initial key values of the animation.
For example, if an animation with only one key [code]Quaternion(0, 0, 0, 1)[/code] is played in the previous frame and then an animation with only one key [code]Quaternion(0, 0.707, 0, 0.707)[/code] is played in the next frame, the difference can be calculated as follows:
[codeblocks]
[gdscript]
var prev_root_motion_rotation_accumulator
func _process(delta):
if Input.is_action_just_pressed("animate"):
state_machine.travel("Animate")
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]
[/codeblocks]
However, if the animation loops, an unintended discrete change may occur, so this is only useful for some simple use cases.
</description>
</method>
<method name="get_root_motion_scale" qualifiers="const">
<return type="Vector3" />
<description>
Retrieve the motion delta of scale with the [member root_motion_track] as a [Vector3] that can be used elsewhere.
If [member root_motion_track] is not a path to a track of type [constant Animation.TYPE_SCALE_3D], returns [code]Vector3(0, 0, 0)[/code].
See also [member root_motion_track] and [RootMotionView].
The most basic example is applying scale to [CharacterBody3D]:
[codeblocks]
[gdscript]
var current_scale = Vector3(1, 1, 1)
var scale_accum = Vector3(1, 1, 1)
func _process(delta):
if Input.is_action_just_pressed("animate"):
current_scale = get_scale()
scale_accum = Vector3(1, 1, 1)
state_machine.travel("Animate")
scale_accum += animation_tree.get_root_motion_scale()
set_scale(current_scale * scale_accum)
[/gdscript]
[/codeblocks]
</description>
</method>
<method name="get_root_motion_scale_accumulator" qualifiers="const">
<return type="Vector3" />
<description>
Retrieve the blended value of the scale tracks with the [member root_motion_track] as a [Vector3] that can be used elsewhere.
For example, if an animation with only one key [code]Vector3(1, 1, 1)[/code] is played in the previous frame and then an animation with only one key [code]Vector3(2, 2, 2)[/code] is played in the next frame, the difference can be calculated as follows:
[codeblocks]
[gdscript]
var prev_root_motion_scale_accumulator
func _process(delta):
if Input.is_action_just_pressed("animate"):
state_machine.travel("Animate")
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]
[/codeblocks]
However, if the animation loops, an unintended discrete change may occur, so this is only useful for some simple use cases.
</description>
</method>
<method name="has_animation" qualifiers="const">
<return type="bool" />
<param index="0" name="name" type="StringName" />
<description>
Returns [code]true[/code] if the [AnimationMixer] stores an [Animation] with key [param name].
</description>
</method>
<method name="has_animation_library" qualifiers="const">
<return type="bool" />
<param index="0" name="name" type="StringName" />
<description>
Returns [code]true[/code] if the [AnimationMixer] stores an [AnimationLibrary] with key [param name].
</description>
</method>
<method name="remove_animation_library">
<return type="void" />
<param index="0" name="name" type="StringName" />
<description>
Removes the [AnimationLibrary] associated with the key [param name].
</description>
</method>
<method name="rename_animation_library">
<return type="void" />
<param index="0" name="name" type="StringName" />
<param index="1" name="newname" type="StringName" />
<description>
Moves the [AnimationLibrary] associated with the key [param name] to the key [param newname].
</description>
</method>
</methods>
<members>
<member name="active" type="bool" setter="set_active" getter="is_active" default="true">
If [code]true[/code], the [AnimationMixer] will be processing.
</member>
<member name="audio_max_polyphony" type="int" setter="set_audio_max_polyphony" getter="get_audio_max_polyphony" default="32">
The number of possible simultaneous sounds for each of the assigned AudioStreamPlayers.
For example, if this value is [code]32[/code] and the animation has two audio tracks, the two [AudioStreamPlayer]s assigned can play simultaneously up to [code]32[/code] voices each.
</member>
<member name="callback_mode_discrete" type="int" setter="set_callback_mode_discrete" getter="get_callback_mode_discrete" enum="AnimationMixer.AnimationCallbackModeDiscrete" default="1">
Ordinarily, tracks can be set to [constant Animation.UPDATE_DISCRETE] to update infrequently, usually when using nearest interpolation.
However, when blending with [constant Animation.UPDATE_CONTINUOUS] several results are considered. The [member callback_mode_discrete] specify it explicitly. See also [enum AnimationCallbackModeDiscrete].
To make the blended results look good, it is recommended to set this to [constant ANIMATION_CALLBACK_MODE_DISCRETE_FORCE_CONTINUOUS] to update every frame during blending. Other values exist for compatibility and they are fine if there is no blending, but not so, may produce artifacts.
</member>
<member name="callback_mode_method" type="int" setter="set_callback_mode_method" getter="get_callback_mode_method" enum="AnimationMixer.AnimationCallbackModeMethod" default="0">
The call mode used for "Call Method" tracks.
</member>
<member name="callback_mode_process" type="int" setter="set_callback_mode_process" getter="get_callback_mode_process" enum="AnimationMixer.AnimationCallbackModeProcess" default="1">
The process notification in which to update animations.
</member>
<member name="deterministic" type="bool" setter="set_deterministic" getter="is_deterministic" default="false">
If [code]true[/code], the blending uses the deterministic algorithm. The total weight is not normalized and the result is accumulated with an initial value ([code]0[/code] or a [code]"RESET"[/code] animation if present).
This means that if the total amount of blending is [code]0.0[/code], the result is equal to the [code]"RESET"[/code] animation.
If the number of tracks between the blended animations is different, the animation with the missing track is treated as if it had the initial value.
If [code]false[/code], The blend does not use the deterministic algorithm. The total weight is normalized and always [code]1.0[/code]. If the number of tracks between the blended animations is different, nothing is done about the animation that is missing a track.
[b]Note:[/b] In [AnimationTree], the blending with [AnimationNodeAdd2], [AnimationNodeAdd3], [AnimationNodeSub2] or the weight greater than [code]1.0[/code] may produce unexpected results.
For example, if [AnimationNodeAdd2] blends two nodes with the amount [code]1.0[/code], then total weight is [code]2.0[/code] but it will be normalized to make the total amount [code]1.0[/code] and the result will be equal to [AnimationNodeBlend2] with the amount [code]0.5[/code].
</member>
<member name="reset_on_save" type="bool" setter="set_reset_on_save_enabled" getter="is_reset_on_save_enabled" default="true">
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" default="false">
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].
</member>
<member name="root_node" type="NodePath" setter="set_root_node" getter="get_root_node" default="NodePath(&quot;..&quot;)">
The node which node path references will travel from.
</member>
</members>
<signals>
<signal name="animation_finished">
<param index="0" name="anim_name" type="StringName" />
<description>
Notifies when an animation finished playing.
[b]Note:[/b] This signal is not emitted if an animation is looping.
</description>
</signal>
<signal name="animation_libraries_updated">
<description>
Notifies when the animation libraries have changed.
</description>
</signal>
<signal name="animation_list_changed">
<description>
Notifies when an animation list is changed.
</description>
</signal>
<signal name="animation_started">
<param index="0" name="anim_name" type="StringName" />
<description>
Notifies when an animation starts playing.
[b]Note:[/b] This signal is not emitted if an animation is looping.
</description>
</signal>
<signal name="caches_cleared">
<description>
Notifies when the caches have been cleared, either automatically, or manually via [method clear_caches].
</description>
</signal>
<signal name="mixer_applied">
<description>
Notifies when the blending result related have been applied to the target objects.
</description>
</signal>
<signal name="mixer_updated">
<description>
Notifies when the property related process have been updated.
</description>
</signal>
</signals>
<constants>
<constant name="ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS" value="0" enum="AnimationCallbackModeProcess">
Process animation during physics frames (see [constant Node.NOTIFICATION_INTERNAL_PHYSICS_PROCESS]). This is especially useful when animating physics bodies.
</constant>
<constant name="ANIMATION_CALLBACK_MODE_PROCESS_IDLE" value="1" enum="AnimationCallbackModeProcess">
Process animation during process frames (see [constant Node.NOTIFICATION_INTERNAL_PROCESS]).
</constant>
<constant name="ANIMATION_CALLBACK_MODE_PROCESS_MANUAL" value="2" enum="AnimationCallbackModeProcess">
Do not process animation. Use [method advance] to process the animation manually.
</constant>
<constant name="ANIMATION_CALLBACK_MODE_METHOD_DEFERRED" value="0" enum="AnimationCallbackModeMethod">
Batch method calls during the animation process, then do the calls after events are processed. This avoids bugs involving deleting nodes or modifying the AnimationPlayer while playing.
</constant>
<constant name="ANIMATION_CALLBACK_MODE_METHOD_IMMEDIATE" value="1" enum="AnimationCallbackModeMethod">
Make method calls immediately when reached in the animation.
</constant>
<constant name="ANIMATION_CALLBACK_MODE_DISCRETE_DOMINANT" value="0" enum="AnimationCallbackModeDiscrete">
An [constant Animation.UPDATE_DISCRETE] track value takes precedence when blending [constant Animation.UPDATE_CONTINUOUS] or [constant Animation.UPDATE_CAPTURE] track values and [constant Animation.UPDATE_DISCRETE] track values.
</constant>
<constant name="ANIMATION_CALLBACK_MODE_DISCRETE_RECESSIVE" value="1" enum="AnimationCallbackModeDiscrete">
An [constant Animation.UPDATE_CONTINUOUS] or [constant Animation.UPDATE_CAPTURE] track value takes precedence when blending the [constant Animation.UPDATE_CONTINUOUS] or [constant Animation.UPDATE_CAPTURE] track values and the [constant Animation.UPDATE_DISCRETE] track values. This is the default behavior for [AnimationPlayer].
</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 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>

248
doc/classes/AnimationNode.xml Normal file
View File

@@ -0,0 +1,248 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimationNode" inherits="Resource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Base class for [AnimationTree] nodes. Not related to scene nodes.
</brief_description>
<description>
Base resource for [AnimationTree] nodes. In general, it's not used directly, but you can create custom ones with custom blending formulas.
Inherit this when creating animation nodes mainly for use in [AnimationNodeBlendTree], otherwise [AnimationRootNode] should be used instead.
You can access the time information as read-only parameter which is processed and stored in the previous frame for all nodes except [AnimationNodeOutput].
[b]Note:[/b] If multiple inputs exist in the [AnimationNode], which time information takes precedence depends on the type of [AnimationNode].
[codeblock]
var current_length = $AnimationTree["parameters/AnimationNodeName/current_length"]
var current_position = $AnimationTree["parameters/AnimationNodeName/current_position"]
var current_delta = $AnimationTree["parameters/AnimationNodeName/current_delta"]
[/codeblock]
</description>
<tutorials>
<link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>
</tutorials>
<methods>
<method name="_get_caption" qualifiers="virtual const">
<return type="String" />
<description>
When inheriting from [AnimationRootNode], implement this virtual method to override the text caption for this animation node.
</description>
</method>
<method name="_get_child_by_name" qualifiers="virtual const">
<return type="AnimationNode" />
<param index="0" name="name" type="StringName" />
<description>
When inheriting from [AnimationRootNode], implement this virtual method to return a child animation node by its [param name].
</description>
</method>
<method name="_get_child_nodes" qualifiers="virtual const">
<return type="Dictionary" />
<description>
When inheriting from [AnimationRootNode], implement this virtual method to return all child animation nodes in order as a [code]name: node[/code] dictionary.
</description>
</method>
<method name="_get_parameter_default_value" qualifiers="virtual const">
<return type="Variant" />
<param index="0" name="parameter" type="StringName" />
<description>
When inheriting from [AnimationRootNode], implement this virtual method to return the default value of a [param 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_parameter_list" qualifiers="virtual const">
<return type="Array" />
<description>
When inheriting from [AnimationRootNode], implement this virtual method to return a list of the properties on this animation node. Parameters are custom local memory used for your animation nodes, given a resource can be reused in multiple trees. Format is similar to [method Object.get_property_list].
</description>
</method>
<method name="_has_filter" qualifiers="virtual const">
<return type="bool" />
<description>
When inheriting from [AnimationRootNode], implement this virtual method to return whether the blend tree editor should display filter editing on this animation node.
</description>
</method>
<method name="_is_parameter_read_only" qualifiers="virtual const">
<return type="bool" />
<param index="0" name="parameter" type="StringName" />
<description>
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" 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" />
<param index="2" name="is_external_seeking" type="bool" />
<param index="3" name="test_only" type="bool" />
<description>
When inheriting from [AnimationRootNode], implement this virtual method to run some code when this animation node is processed. The [param time] parameter is a relative delta, unless [param seek] is [code]true[/code], in which case it is absolute.
Here, call the [method blend_input], [method blend_node] or [method blend_animation] functions. You can also use [method get_parameter] and [method set_parameter] to modify local memory.
This function should return the delta.
</description>
</method>
<method name="add_input">
<return type="bool" />
<param index="0" name="name" type="String" />
<description>
Adds an input to the animation node. This is only useful for animation nodes created for use in an [AnimationNodeBlendTree]. If the addition fails, returns [code]false[/code].
</description>
</method>
<method name="blend_animation">
<return type="void" />
<param index="0" name="animation" type="StringName" />
<param index="1" name="time" type="float" />
<param index="2" name="delta" type="float" />
<param index="3" name="seeked" type="bool" />
<param index="4" name="is_external_seeking" type="bool" />
<param index="5" name="blend" type="float" />
<param index="6" name="looped_flag" type="int" enum="Animation.LoopedFlag" default="0" />
<description>
Blends an animation by [param blend] amount (name must be valid in the linked [AnimationPlayer]). A [param time] and [param delta] may be passed, as well as whether [param seeked] happened.
A [param looped_flag] is used by internal processing immediately after the loop.
</description>
</method>
<method name="blend_input">
<return type="float" />
<param index="0" name="input_index" type="int" />
<param index="1" name="time" type="float" />
<param index="2" name="seek" type="bool" />
<param index="3" name="is_external_seeking" type="bool" />
<param index="4" name="blend" type="float" />
<param index="5" name="filter" type="int" enum="AnimationNode.FilterAction" default="0" />
<param index="6" name="sync" type="bool" default="true" />
<param index="7" name="test_only" type="bool" default="false" />
<description>
Blends an input. This is only useful for animation nodes created for an [AnimationNodeBlendTree]. The [param time] parameter is a relative delta, unless [param seek] is [code]true[/code], in which case it is absolute. A filter mode may be optionally passed.
</description>
</method>
<method name="blend_node">
<return type="float" />
<param index="0" name="name" type="StringName" />
<param index="1" name="node" type="AnimationNode" />
<param index="2" name="time" type="float" />
<param index="3" name="seek" type="bool" />
<param index="4" name="is_external_seeking" type="bool" />
<param index="5" name="blend" type="float" />
<param index="6" name="filter" type="int" enum="AnimationNode.FilterAction" default="0" />
<param index="7" name="sync" type="bool" default="true" />
<param index="8" name="test_only" type="bool" default="false" />
<description>
Blend another animation node (in case this animation node contains child animation nodes). This function is only useful if you inherit from [AnimationRootNode] instead, otherwise editors will not display your animation node for addition.
</description>
</method>
<method name="find_input" qualifiers="const">
<return type="int" />
<param index="0" name="name" type="String" />
<description>
Returns the input index which corresponds to [param name]. If not found, returns [code]-1[/code].
</description>
</method>
<method name="get_input_count" qualifiers="const">
<return type="int" />
<description>
Amount of inputs in this animation node, only useful for animation nodes that go into [AnimationNodeBlendTree].
</description>
</method>
<method name="get_input_name" qualifiers="const">
<return type="String" />
<param index="0" name="input" type="int" />
<description>
Gets the name of an input by index.
</description>
</method>
<method name="get_parameter" qualifiers="const">
<return type="Variant" />
<param index="0" name="name" type="StringName" />
<description>
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 [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">
<return type="void" />
<param index="0" name="index" type="int" />
<description>
Removes an input, call this only when inactive.
</description>
</method>
<method name="set_filter_path">
<return type="void" />
<param index="0" name="path" type="NodePath" />
<param index="1" name="enable" type="bool" />
<description>
Adds or removes a path for the filter.
</description>
</method>
<method name="set_input_name">
<return type="bool" />
<param index="0" name="input" type="int" />
<param index="1" name="name" type="String" />
<description>
Sets the name of the input at the given [param input] index. If the setting fails, returns [code]false[/code].
</description>
</method>
<method name="set_parameter">
<return type="void" />
<param index="0" name="name" type="StringName" />
<param index="1" name="value" type="Variant" />
<description>
Sets a custom parameter. These are used as local memory, because resources can be reused across the tree or scenes.
</description>
</method>
</methods>
<members>
<member name="filter_enabled" type="bool" setter="set_filter_enabled" getter="is_filter_enabled">
If [code]true[/code], filtering is enabled.
</member>
</members>
<signals>
<signal name="animation_node_removed">
<param index="0" name="object_id" type="int" />
<param index="1" name="name" type="String" />
<description>
Emitted by nodes that inherit from this class and that have an internal tree when one of their animation nodes removes. The animation nodes that emit this signal are [AnimationNodeBlendSpace1D], [AnimationNodeBlendSpace2D], [AnimationNodeStateMachine], and [AnimationNodeBlendTree].
</description>
</signal>
<signal name="animation_node_renamed">
<param index="0" name="object_id" type="int" />
<param index="1" name="old_name" type="String" />
<param index="2" name="new_name" type="String" />
<description>
Emitted by nodes that inherit from this class and that have an internal tree when one of their animation node names changes. The animation nodes that emit this signal are [AnimationNodeBlendSpace1D], [AnimationNodeBlendSpace2D], [AnimationNodeStateMachine], and [AnimationNodeBlendTree].
</description>
</signal>
<signal name="tree_changed">
<description>
Emitted by nodes that inherit from this class and that have an internal tree when one of their animation nodes changes. The animation nodes that emit this signal are [AnimationNodeBlendSpace1D], [AnimationNodeBlendSpace2D], [AnimationNodeStateMachine], [AnimationNodeBlendTree] and [AnimationNodeTransition].
</description>
</signal>
</signals>
<constants>
<constant name="FILTER_IGNORE" value="0" enum="FilterAction">
Do not use filtering.
</constant>
<constant name="FILTER_PASS" value="1" enum="FilterAction">
Paths matching the filter will be allowed to pass.
</constant>
<constant name="FILTER_STOP" value="2" enum="FilterAction">
Paths matching the filter will be discarded.
</constant>
<constant name="FILTER_BLEND" value="3" enum="FilterAction">
Paths matching the filter will be blended (by the blend value).
</constant>
</constants>
</class>

14
doc/classes/AnimationNodeAdd2.xml Normal file
View File

@@ -0,0 +1,14 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimationNodeAdd2" inherits="AnimationNodeSync" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Blends two animations additively inside of an [AnimationNodeBlendTree].
</brief_description>
<description>
A resource to add to an [AnimationNodeBlendTree]. Blends two animations additively based on the amount value.
If the amount is greater than [code]1.0[/code], the animation connected to "in" port is blended with the amplified animation connected to "add" port.
If the amount is less than [code]0.0[/code], the animation connected to "in" port is blended with the inverted animation connected to "add" port.
</description>
<tutorials>
<link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>
</tutorials>
</class>

18
doc/classes/AnimationNodeAdd3.xml Normal file
View File

@@ -0,0 +1,18 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimationNodeAdd3" inherits="AnimationNodeSync" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Blends two of three animations additively inside of an [AnimationNodeBlendTree].
</brief_description>
<description>
A resource to add to an [AnimationNodeBlendTree]. Blends two animations out of three additively out of three based on the amount value.
This animation node has three inputs:
- The base animation to add to
- A "-add" animation to blend with when the blend amount is negative
- A "+add" animation to blend with when the blend amount is positive
If the absolute value of the amount is greater than [code]1.0[/code], the animation connected to "in" port is blended with the amplified animation connected to "-add"/"+add" port.
</description>
<tutorials>
<link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>
<link title="Third Person Shooter (TPS) Demo">https://godotengine.org/asset-library/asset/2710</link>
</tutorials>
</class>

53
doc/classes/AnimationNodeAnimation.xml Normal file
View File

@@ -0,0 +1,53 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimationNodeAnimation" inherits="AnimationRootNode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
An input animation for an [AnimationNodeBlendTree].
</brief_description>
<description>
A resource to add to an [AnimationNodeBlendTree]. Only has one output port using the [member animation] property. Used as an input for [AnimationNode]s that blend animations together.
</description>
<tutorials>
<link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>
<link title="3D Platformer Demo">https://godotengine.org/asset-library/asset/2748</link>
<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>
<member name="loop_mode" type="int" setter="set_loop_mode" getter="get_loop_mode" enum="Animation.LoopMode">
If [member use_custom_timeline] is [code]true[/code], override the loop settings of the original [Animation] resource with the value.
[b]Note:[/b] If the [member Animation.loop_mode] isn't set to looping, the [method Animation.track_set_interpolation_loop_wrap] option will not be respected. If you cannot get the expected behavior, consider duplicating the [Animation] resource and changing the loop settings.
</member>
<member name="play_mode" type="int" setter="set_play_mode" getter="get_play_mode" enum="AnimationNodeAnimation.PlayMode" default="0">
Determines the playback direction of the animation.
</member>
<member name="start_offset" type="float" setter="set_start_offset" getter="get_start_offset">
If [member use_custom_timeline] is [code]true[/code], offset the start position of the animation.
This is useful for adjusting which foot steps first in 3D walking animations.
</member>
<member name="stretch_time_scale" type="bool" setter="set_stretch_time_scale" getter="is_stretching_time_scale">
If [code]true[/code], scales the time so that the length specified in [member timeline_length] is one cycle.
This is useful for matching the periods of walking and running animations.
If [code]false[/code], the original animation length is respected. If you set the loop to [member loop_mode], the animation will loop in [member timeline_length].
</member>
<member name="timeline_length" type="float" setter="set_timeline_length" getter="get_timeline_length">
If [member use_custom_timeline] is [code]true[/code], offset the start position of the animation.
</member>
<member name="use_custom_timeline" type="bool" setter="set_use_custom_timeline" getter="is_using_custom_timeline" default="false">
If [code]true[/code], [AnimationNode] provides an animation based on the [Animation] resource with some parameters adjusted.
</member>
</members>
<constants>
<constant name="PLAY_MODE_FORWARD" value="0" enum="PlayMode">
Plays animation in forward direction.
</constant>
<constant name="PLAY_MODE_BACKWARD" value="1" enum="PlayMode">
Plays animation in backward direction.
</constant>
</constants>
</class>

15
doc/classes/AnimationNodeBlend2.xml Normal file
View File

@@ -0,0 +1,15 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimationNodeBlend2" inherits="AnimationNodeSync" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Blends two animations linearly inside of an [AnimationNodeBlendTree].
</brief_description>
<description>
A resource to add to an [AnimationNodeBlendTree]. Blends two animations linearly based on the amount value.
In general, the blend value should be in the [code][0.0, 1.0][/code] range. Values outside of this range can blend amplified or inverted animations, however, [AnimationNodeAdd2] works better for this purpose.
</description>
<tutorials>
<link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>
<link title="3D Platformer Demo">https://godotengine.org/asset-library/asset/2748</link>
<link title="Third Person Shooter (TPS) Demo">https://godotengine.org/asset-library/asset/2710</link>
</tutorials>
</class>

17
doc/classes/AnimationNodeBlend3.xml Normal file
View File

@@ -0,0 +1,17 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimationNodeBlend3" inherits="AnimationNodeSync" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Blends two of three animations linearly inside of an [AnimationNodeBlendTree].
</brief_description>
<description>
A resource to add to an [AnimationNodeBlendTree]. Blends two animations out of three linearly out of three based on the amount value.
This animation node has three inputs:
- The base animation to blend with
- A "-blend" animation to blend with when the blend amount is negative value
- A "+blend" animation to blend with when the blend amount is positive value
In general, the blend value should be in the [code][-1.0, 1.0][/code] range. Values outside of this range can blend amplified animations, however, [AnimationNodeAdd3] works better for this purpose.
</description>
<tutorials>
<link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>
</tutorials>
</class>

100
doc/classes/AnimationNodeBlendSpace1D.xml Normal file
View File

@@ -0,0 +1,100 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimationNodeBlendSpace1D" inherits="AnimationRootNode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
A set of [AnimationRootNode]s placed on a virtual axis, crossfading between the two adjacent ones. Used by [AnimationTree].
</brief_description>
<description>
A resource used by [AnimationNodeBlendTree].
[AnimationNodeBlendSpace1D] represents a virtual axis on which any type of [AnimationRootNode]s can be added using [method add_blend_point]. Outputs the linear blend of the two [AnimationRootNode]s adjacent to the current value.
You can set the extents of the axis with [member min_space] and [member max_space].
</description>
<tutorials>
<link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>
</tutorials>
<methods>
<method name="add_blend_point">
<return type="void" />
<param index="0" name="node" type="AnimationRootNode" />
<param index="1" name="pos" type="float" />
<param index="2" name="at_index" type="int" default="-1" />
<description>
Adds a new point that represents a [param node] on the virtual axis at a given position set by [param pos]. You can insert it at a specific index using the [param at_index] argument. If you use the default value for [param at_index], the point is inserted at the end of the blend points array.
</description>
</method>
<method name="get_blend_point_count" qualifiers="const">
<return type="int" />
<description>
Returns the number of points on the blend axis.
</description>
</method>
<method name="get_blend_point_node" qualifiers="const">
<return type="AnimationRootNode" />
<param index="0" name="point" type="int" />
<description>
Returns the [AnimationNode] referenced by the point at index [param point].
</description>
</method>
<method name="get_blend_point_position" qualifiers="const">
<return type="float" />
<param index="0" name="point" type="int" />
<description>
Returns the position of the point at index [param point].
</description>
</method>
<method name="remove_blend_point">
<return type="void" />
<param index="0" name="point" type="int" />
<description>
Removes the point at index [param point] from the blend axis.
</description>
</method>
<method name="set_blend_point_node">
<return type="void" />
<param index="0" name="point" type="int" />
<param index="1" name="node" type="AnimationRootNode" />
<description>
Changes the [AnimationNode] referenced by the point at index [param point].
</description>
</method>
<method name="set_blend_point_position">
<return type="void" />
<param index="0" name="point" type="int" />
<param index="1" name="pos" type="float" />
<description>
Updates the position of the point at index [param point] on the blend axis.
</description>
</method>
</methods>
<members>
<member name="blend_mode" type="int" setter="set_blend_mode" getter="get_blend_mode" enum="AnimationNodeBlendSpace1D.BlendMode" default="0">
Controls the interpolation between animations.
</member>
<member name="max_space" type="float" setter="set_max_space" getter="get_max_space" default="1.0">
The blend space's axis's upper limit for the points' position. See [method add_blend_point].
</member>
<member name="min_space" type="float" setter="set_min_space" getter="get_min_space" default="-1.0">
The blend space's axis's lower limit for the points' position. See [method add_blend_point].
</member>
<member name="snap" type="float" setter="set_snap" getter="get_snap" default="0.1">
Position increment to snap to when moving a point on the axis.
</member>
<member name="sync" type="bool" setter="set_use_sync" getter="is_using_sync" default="false">
If [code]false[/code], the blended animations' frame are stopped when the blend value is [code]0[/code].
If [code]true[/code], forcing the blended animations to advance frame.
</member>
<member name="value_label" type="String" setter="set_value_label" getter="get_value_label" default="&quot;value&quot;">
Label of the virtual axis of the blend space.
</member>
</members>
<constants>
<constant name="BLEND_MODE_INTERPOLATED" value="0" enum="BlendMode">
The interpolation between animations is linear.
</constant>
<constant name="BLEND_MODE_DISCRETE" value="1" enum="BlendMode">
The blend space plays the animation of the animation node which blending position is closest to. Useful for frame-by-frame 2D animations.
</constant>
<constant name="BLEND_MODE_DISCRETE_CARRY" value="2" enum="BlendMode">
Similar to [constant BLEND_MODE_DISCRETE], but starts the new animation at the last animation's playback position.
</constant>
</constants>
</class>

145
doc/classes/AnimationNodeBlendSpace2D.xml Normal file
View File

@@ -0,0 +1,145 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimationNodeBlendSpace2D" inherits="AnimationRootNode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
A set of [AnimationRootNode]s placed on 2D coordinates, crossfading between the three adjacent ones. Used by [AnimationTree].
</brief_description>
<description>
A resource used by [AnimationNodeBlendTree].
[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>
<link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>
<link title="Third Person Shooter (TPS) Demo">https://godotengine.org/asset-library/asset/2710</link>
</tutorials>
<methods>
<method name="add_blend_point">
<return type="void" />
<param index="0" name="node" type="AnimationRootNode" />
<param index="1" name="pos" type="Vector2" />
<param index="2" name="at_index" type="int" default="-1" />
<description>
Adds a new point that represents a [param node] at the position set by [param pos]. You can insert it at a specific index using the [param at_index] argument. If you use the default value for [param at_index], the point is inserted at the end of the blend points array.
</description>
</method>
<method name="add_triangle">
<return type="void" />
<param index="0" name="x" type="int" />
<param index="1" name="y" type="int" />
<param index="2" name="z" type="int" />
<param index="3" name="at_index" type="int" default="-1" />
<description>
Creates a new triangle using three points [param x], [param y], and [param z]. Triangles can overlap. You can insert the triangle at a specific index using the [param at_index] argument. If you use the default value for [param at_index], the point is inserted at the end of the blend points array.
</description>
</method>
<method name="get_blend_point_count" qualifiers="const">
<return type="int" />
<description>
Returns the number of points in the blend space.
</description>
</method>
<method name="get_blend_point_node" qualifiers="const">
<return type="AnimationRootNode" />
<param index="0" name="point" type="int" />
<description>
Returns the [AnimationRootNode] referenced by the point at index [param point].
</description>
</method>
<method name="get_blend_point_position" qualifiers="const">
<return type="Vector2" />
<param index="0" name="point" type="int" />
<description>
Returns the position of the point at index [param point].
</description>
</method>
<method name="get_triangle_count" qualifiers="const">
<return type="int" />
<description>
Returns the number of triangles in the blend space.
</description>
</method>
<method name="get_triangle_point">
<return type="int" />
<param index="0" name="triangle" type="int" />
<param index="1" name="point" type="int" />
<description>
Returns the position of the point at index [param point] in the triangle of index [param triangle].
</description>
</method>
<method name="remove_blend_point">
<return type="void" />
<param index="0" name="point" type="int" />
<description>
Removes the point at index [param point] from the blend space.
</description>
</method>
<method name="remove_triangle">
<return type="void" />
<param index="0" name="triangle" type="int" />
<description>
Removes the triangle at index [param triangle] from the blend space.
</description>
</method>
<method name="set_blend_point_node">
<return type="void" />
<param index="0" name="point" type="int" />
<param index="1" name="node" type="AnimationRootNode" />
<description>
Changes the [AnimationNode] referenced by the point at index [param point].
</description>
</method>
<method name="set_blend_point_position">
<return type="void" />
<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] in the blend space.
</description>
</method>
</methods>
<members>
<member name="auto_triangles" type="bool" setter="set_auto_triangles" getter="get_auto_triangles" default="true">
If [code]true[/code], the blend space is triangulated automatically. The mesh updates every time you add or remove points with [method add_blend_point] and [method remove_blend_point].
</member>
<member name="blend_mode" type="int" setter="set_blend_mode" getter="get_blend_mode" enum="AnimationNodeBlendSpace2D.BlendMode" default="0">
Controls the interpolation between animations.
</member>
<member name="max_space" type="Vector2" setter="set_max_space" getter="get_max_space" default="Vector2(1, 1)">
The blend space's X and Y axes' upper limit for the points' position. See [method add_blend_point].
</member>
<member name="min_space" type="Vector2" setter="set_min_space" getter="get_min_space" default="Vector2(-1, -1)">
The blend space's X and Y axes' lower limit for the points' position. See [method add_blend_point].
</member>
<member name="snap" type="Vector2" setter="set_snap" getter="get_snap" default="Vector2(0.1, 0.1)">
Position increment to snap to when moving a point.
</member>
<member name="sync" type="bool" setter="set_use_sync" getter="is_using_sync" default="false">
If [code]false[/code], the blended animations' frame are stopped when the blend value is [code]0[/code].
If [code]true[/code], forcing the blended animations to advance frame.
</member>
<member name="x_label" type="String" setter="set_x_label" getter="get_x_label" default="&quot;x&quot;">
Name of the blend space's X axis.
</member>
<member name="y_label" type="String" setter="set_y_label" getter="get_y_label" default="&quot;y&quot;">
Name of the blend space's Y axis.
</member>
</members>
<signals>
<signal name="triangles_updated">
<description>
Emitted every time the blend space's triangles are created, removed, or when one of their vertices changes position.
</description>
</signal>
</signals>
<constants>
<constant name="BLEND_MODE_INTERPOLATED" value="0" enum="BlendMode">
The interpolation between animations is linear.
</constant>
<constant name="BLEND_MODE_DISCRETE" value="1" enum="BlendMode">
The blend space plays the animation of the animation node which blending position is closest to. Useful for frame-by-frame 2D animations.
</constant>
<constant name="BLEND_MODE_DISCRETE_CARRY" value="2" enum="BlendMode">
Similar to [constant BLEND_MODE_DISCRETE], but starts the new animation at the last animation's playback position.
</constant>
</constants>
</class>

124
doc/classes/AnimationNodeBlendTree.xml Normal file
View File

@@ -0,0 +1,124 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimationNodeBlendTree" inherits="AnimationRootNode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
A sub-tree of many type [AnimationNode]s used for complex animations. Used by [AnimationTree].
</brief_description>
<description>
This animation node may contain a sub-tree of any other type animation nodes, such as [AnimationNodeTransition], [AnimationNodeBlend2], [AnimationNodeBlend3], [AnimationNodeOneShot], etc. This is one of the most commonly used animation node roots.
An [AnimationNodeOutput] node named [code]output[/code] is created by default.
</description>
<tutorials>
<link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>
</tutorials>
<methods>
<method name="add_node">
<return type="void" />
<param index="0" name="name" type="StringName" />
<param index="1" name="node" type="AnimationNode" />
<param index="2" name="position" type="Vector2" default="Vector2(0, 0)" />
<description>
Adds an [AnimationNode] at the given [param position]. The [param name] is used to identify the created sub animation node later.
</description>
</method>
<method name="connect_node">
<return type="void" />
<param index="0" name="input_node" type="StringName" />
<param index="1" name="input_index" type="int" />
<param index="2" name="output_node" type="StringName" />
<description>
Connects the output of an [AnimationNode] as input for another [AnimationNode], at the input port specified by [param input_index].
</description>
</method>
<method name="disconnect_node">
<return type="void" />
<param index="0" name="input_node" type="StringName" />
<param index="1" name="input_index" type="int" />
<description>
Disconnects the animation node connected to the specified input.
</description>
</method>
<method name="get_node" qualifiers="const">
<return type="AnimationNode" />
<param index="0" name="name" type="StringName" />
<description>
Returns the sub animation node with the specified [param name].
</description>
</method>
<method name="get_node_list" qualifiers="const">
<return type="StringName[]" />
<description>
Returns a list containing the names of all sub animation nodes in this blend tree.
</description>
</method>
<method name="get_node_position" qualifiers="const">
<return type="Vector2" />
<param index="0" name="name" type="StringName" />
<description>
Returns the position of the sub animation node with the specified [param name].
</description>
</method>
<method name="has_node" qualifiers="const">
<return type="bool" />
<param index="0" name="name" type="StringName" />
<description>
Returns [code]true[/code] if a sub animation node with specified [param name] exists.
</description>
</method>
<method name="remove_node">
<return type="void" />
<param index="0" name="name" type="StringName" />
<description>
Removes a sub animation node.
</description>
</method>
<method name="rename_node">
<return type="void" />
<param index="0" name="name" type="StringName" />
<param index="1" name="new_name" type="StringName" />
<description>
Changes the name of a sub animation node.
</description>
</method>
<method name="set_node_position">
<return type="void" />
<param index="0" name="name" type="StringName" />
<param index="1" name="position" type="Vector2" />
<description>
Modifies the position of a sub animation node.
</description>
</method>
</methods>
<members>
<member name="graph_offset" type="Vector2" setter="set_graph_offset" getter="get_graph_offset" default="Vector2(0, 0)">
The global offset of all sub animation nodes.
</member>
</members>
<signals>
<signal name="node_changed">
<param index="0" name="node_name" type="StringName" />
<description>
Emitted when the input port information is changed.
</description>
</signal>
</signals>
<constants>
<constant name="CONNECTION_OK" value="0">
The connection was successful.
</constant>
<constant name="CONNECTION_ERROR_NO_INPUT" value="1">
The input node is [code]null[/code].
</constant>
<constant name="CONNECTION_ERROR_NO_INPUT_INDEX" value="2">
The specified input port is out of range.
</constant>
<constant name="CONNECTION_ERROR_NO_OUTPUT" value="3">
The output node is [code]null[/code].
</constant>
<constant name="CONNECTION_ERROR_SAME_NODE" value="4">
Input and output nodes are the same.
</constant>
<constant name="CONNECTION_ERROR_CONNECTION_EXISTS" value="5">
The specified connection already exists.
</constant>
</constants>
</class>

38
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 required">
<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>

110
doc/classes/AnimationNodeOneShot.xml Normal file
View File

@@ -0,0 +1,110 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimationNodeOneShot" inherits="AnimationNodeSync" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Plays an animation once in an [AnimationNodeBlendTree].
</brief_description>
<description>
A resource to add to an [AnimationNodeBlendTree]. This animation node will execute a sub-animation and return once it finishes. Blend times for fading in and out can be customized, as well as filters.
After setting the request and changing the animation playback, the one-shot node automatically clears the request on the next process frame by setting its [code]request[/code] value to [constant ONE_SHOT_REQUEST_NONE].
[codeblocks]
[gdscript]
# Play child animation connected to "shot" port.
animation_tree.set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE)
# Alternative syntax (same result as above).
animation_tree["parameters/OneShot/request"] = AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE
# Abort child animation connected to "shot" port.
animation_tree.set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_ABORT)
# Alternative syntax (same result as above).
animation_tree["parameters/OneShot/request"] = AnimationNodeOneShot.ONE_SHOT_REQUEST_ABORT
# Abort child animation with fading out connected to "shot" port.
animation_tree.set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_FADE_OUT)
# Alternative syntax (same result as above).
animation_tree["parameters/OneShot/request"] = AnimationNodeOneShot.ONE_SHOT_REQUEST_FADE_OUT
# Get current state (read-only).
animation_tree.get("parameters/OneShot/active")
# Alternative syntax (same result as above).
animation_tree["parameters/OneShot/active"]
# Get current internal state (read-only).
animation_tree.get("parameters/OneShot/internal_active")
# Alternative syntax (same result as above).
animation_tree["parameters/OneShot/internal_active"]
[/gdscript]
[csharp]
// Play child animation connected to "shot" port.
animationTree.Set("parameters/OneShot/request", (int)AnimationNodeOneShot.OneShotRequest.Fire);
// Abort child animation connected to "shot" port.
animationTree.Set("parameters/OneShot/request", (int)AnimationNodeOneShot.OneShotRequest.Abort);
// Abort child animation with fading out connected to "shot" port.
animationTree.Set("parameters/OneShot/request", (int)AnimationNodeOneShot.OneShotRequest.FadeOut);
// Get current state (read-only).
animationTree.Get("parameters/OneShot/active");
// Get current internal state (read-only).
animationTree.Get("parameters/OneShot/internal_active");
[/csharp]
[/codeblocks]
</description>
<tutorials>
<link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>
<link title="Third Person Shooter (TPS) Demo">https://godotengine.org/asset-library/asset/2710</link>
</tutorials>
<members>
<member name="autorestart" type="bool" setter="set_autorestart" getter="has_autorestart" default="false">
If [code]true[/code], the sub-animation will restart automatically after finishing.
In other words, to start auto restarting, the animation must be played once with the [constant ONE_SHOT_REQUEST_FIRE] request. The [constant ONE_SHOT_REQUEST_ABORT] request stops the auto restarting, but it does not disable the [member autorestart] itself. So, the [constant ONE_SHOT_REQUEST_FIRE] request will start auto restarting again.
</member>
<member name="autorestart_delay" type="float" setter="set_autorestart_delay" getter="get_autorestart_delay" default="1.0">
The delay after which the automatic restart is triggered, in seconds.
</member>
<member name="autorestart_random_delay" type="float" setter="set_autorestart_random_delay" getter="get_autorestart_random_delay" default="0.0">
If [member autorestart] is [code]true[/code], a random additional delay (in seconds) between 0 and this value will be added to [member autorestart_delay].
</member>
<member name="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.
</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. 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 fading has finished.
</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. 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.
[b]Note:[/b] [AnimationNodeOneShot] transitions the current state after the fading has finished.
</member>
<member name="mix_mode" type="int" setter="set_mix_mode" getter="get_mix_mode" enum="AnimationNodeOneShot.MixMode" default="0">
The blend type.
</member>
</members>
<constants>
<constant name="ONE_SHOT_REQUEST_NONE" value="0" enum="OneShotRequest">
The default state of the request. Nothing is done.
</constant>
<constant name="ONE_SHOT_REQUEST_FIRE" value="1" enum="OneShotRequest">
The request to play the animation connected to "shot" port.
</constant>
<constant name="ONE_SHOT_REQUEST_ABORT" value="2" enum="OneShotRequest">
The request to stop the animation connected to "shot" port.
</constant>
<constant name="ONE_SHOT_REQUEST_FADE_OUT" value="3" enum="OneShotRequest">
The request to fade out the animation connected to "shot" port.
</constant>
<constant name="MIX_MODE_BLEND" value="0" enum="MixMode">
Blends two animations. See also [AnimationNodeBlend2].
</constant>
<constant name="MIX_MODE_ADD" value="1" enum="MixMode">
Blends two animations additively. See also [AnimationNodeAdd2].
</constant>
</constants>
</class>

14
doc/classes/AnimationNodeOutput.xml Normal file
View File

@@ -0,0 +1,14 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimationNodeOutput" inherits="AnimationNode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
The animation output node of an [AnimationNodeBlendTree].
</brief_description>
<description>
A node created automatically in an [AnimationNodeBlendTree] that outputs the final animation.
</description>
<tutorials>
<link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>
<link title="3D Platformer Demo">https://godotengine.org/asset-library/asset/2748</link>
<link title="Third Person Shooter (TPS) Demo">https://godotengine.org/asset-library/asset/2710</link>
</tutorials>
</class>

193
doc/classes/AnimationNodeStateMachine.xml Normal file
View File

@@ -0,0 +1,193 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimationNodeStateMachine" inherits="AnimationRootNode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
A state machine with multiple [AnimationRootNode]s, used by [AnimationTree].
</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.
[codeblocks]
[gdscript]
var state_machine = $AnimationTree.get("parameters/playback")
state_machine.travel("some_state")
[/gdscript]
[csharp]
var stateMachine = GetNode&lt;AnimationTree&gt;("AnimationTree").Get("parameters/playback") as AnimationNodeStateMachinePlayback;
stateMachine.Travel("some_state");
[/csharp]
[/codeblocks]
</description>
<tutorials>
<link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>
</tutorials>
<methods>
<method name="add_node">
<return type="void" />
<param index="0" name="name" type="StringName" />
<param index="1" name="node" type="AnimationNode" />
<param index="2" name="position" type="Vector2" default="Vector2(0, 0)" />
<description>
Adds a new animation node to the graph. The [param position] is used for display in the editor.
</description>
</method>
<method name="add_transition">
<return type="void" />
<param index="0" name="from" type="StringName" />
<param index="1" name="to" type="StringName" />
<param index="2" name="transition" type="AnimationNodeStateMachineTransition" />
<description>
Adds a transition between the given animation nodes.
</description>
</method>
<method name="get_graph_offset" qualifiers="const">
<return type="Vector2" />
<description>
Returns the draw offset of the graph. Used for display in the editor.
</description>
</method>
<method name="get_node" qualifiers="const">
<return type="AnimationNode" />
<param index="0" name="name" type="StringName" />
<description>
Returns the animation node with the given name.
</description>
</method>
<method name="get_node_list" qualifiers="const">
<return type="StringName[]" />
<description>
Returns a list containing the names of all animation nodes in this state machine.
</description>
</method>
<method name="get_node_name" qualifiers="const">
<return type="StringName" />
<param index="0" name="node" type="AnimationNode" />
<description>
Returns the given animation node's name.
</description>
</method>
<method name="get_node_position" qualifiers="const">
<return type="Vector2" />
<param index="0" name="name" type="StringName" />
<description>
Returns the given animation node's coordinates. Used for display in the editor.
</description>
</method>
<method name="get_transition" qualifiers="const">
<return type="AnimationNodeStateMachineTransition" />
<param index="0" name="idx" type="int" />
<description>
Returns the given transition.
</description>
</method>
<method name="get_transition_count" qualifiers="const">
<return type="int" />
<description>
Returns the number of connections in the graph.
</description>
</method>
<method name="get_transition_from" qualifiers="const">
<return type="StringName" />
<param index="0" name="idx" type="int" />
<description>
Returns the given transition's start node.
</description>
</method>
<method name="get_transition_to" qualifiers="const">
<return type="StringName" />
<param index="0" name="idx" type="int" />
<description>
Returns the given transition's end node.
</description>
</method>
<method name="has_node" qualifiers="const">
<return type="bool" />
<param index="0" name="name" type="StringName" />
<description>
Returns [code]true[/code] if the graph contains the given animation node.
</description>
</method>
<method name="has_transition" qualifiers="const">
<return type="bool" />
<param index="0" name="from" type="StringName" />
<param index="1" name="to" type="StringName" />
<description>
Returns [code]true[/code] if there is a transition between the given animation nodes.
</description>
</method>
<method name="remove_node">
<return type="void" />
<param index="0" name="name" type="StringName" />
<description>
Deletes the given animation node from the graph.
</description>
</method>
<method name="remove_transition">
<return type="void" />
<param index="0" name="from" type="StringName" />
<param index="1" name="to" type="StringName" />
<description>
Deletes the transition between the two specified animation nodes.
</description>
</method>
<method name="remove_transition_by_index">
<return type="void" />
<param index="0" name="idx" type="int" />
<description>
Deletes the given transition by index.
</description>
</method>
<method name="rename_node">
<return type="void" />
<param index="0" name="name" type="StringName" />
<param index="1" name="new_name" type="StringName" />
<description>
Renames the given animation node.
</description>
</method>
<method name="replace_node">
<return type="void" />
<param index="0" name="name" type="StringName" />
<param index="1" name="node" type="AnimationNode" />
<description>
Replaces the given animation node with a new animation node.
</description>
</method>
<method name="set_graph_offset">
<return type="void" />
<param index="0" name="offset" type="Vector2" />
<description>
Sets the draw offset of the graph. Used for display in the editor.
</description>
</method>
<method name="set_node_position">
<return type="void" />
<param index="0" name="name" type="StringName" />
<param index="1" name="position" type="Vector2" />
<description>
Sets the animation node's coordinates. Used for display in the editor.
</description>
</method>
</methods>
<members>
<member name="allow_transition_to_self" type="bool" setter="set_allow_transition_to_self" getter="is_allow_transition_to_self" default="false">
If [code]true[/code], allows teleport to the self state with [method AnimationNodeStateMachinePlayback.travel]. When the reset option is enabled in [method AnimationNodeStateMachinePlayback.travel], the animation is restarted. If [code]false[/code], nothing happens on the teleportation to the self state.
</member>
<member name="reset_ends" type="bool" setter="set_reset_ends" getter="are_ends_reset" default="false">
If [code]true[/code], treat the cross-fade to the start and end nodes as a blend with the RESET animation.
In most cases, when additional cross-fades are performed in the parent [AnimationNode] of the state machine, setting this property to [code]false[/code] and matching the cross-fade time of the parent [AnimationNode] and the state machine's start node and end node gives good results.
</member>
<member name="state_machine_type" type="int" setter="set_state_machine_type" getter="get_state_machine_type" enum="AnimationNodeStateMachine.StateMachineType" default="0">
This property can define the process of transitions for different use cases. See also [enum AnimationNodeStateMachine.StateMachineType].
</member>
</members>
<constants>
<constant name="STATE_MACHINE_TYPE_ROOT" value="0" enum="StateMachineType">
Seeking to the beginning is treated as playing from the start state. Transition to the end state is treated as exiting the state machine.
</constant>
<constant name="STATE_MACHINE_TYPE_NESTED" value="1" enum="StateMachineType">
Seeking to the beginning is treated as seeking to the beginning of the animation in the current state. Transition to the end state, or the absence of transitions in each state, is treated as exiting the state machine.
</constant>
<constant name="STATE_MACHINE_TYPE_GROUPED" value="2" enum="StateMachineType">
This is a grouped state machine that can be controlled from a parent state machine. It does not work independently. There must be a state machine with [member state_machine_type] of [constant STATE_MACHINE_TYPE_ROOT] or [constant STATE_MACHINE_TYPE_NESTED] in the parent or ancestor.
</constant>
</constants>
</class>

111
doc/classes/AnimationNodeStateMachinePlayback.xml Normal file
View File

@@ -0,0 +1,111 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimationNodeStateMachinePlayback" inherits="Resource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Provides playback control for an [AnimationNodeStateMachine].
</brief_description>
<description>
Allows control of [AnimationTree] state machines created with [AnimationNodeStateMachine]. Retrieve with [code]$AnimationTree.get("parameters/playback")[/code].
[codeblocks]
[gdscript]
var state_machine = $AnimationTree.get("parameters/playback")
state_machine.travel("some_state")
[/gdscript]
[csharp]
var stateMachine = GetNode&lt;AnimationTree&gt;("AnimationTree").Get("parameters/playback").As&lt;AnimationNodeStateMachinePlayback&gt;();
stateMachine.Travel("some_state");
[/csharp]
[/codeblocks]
</description>
<tutorials>
<link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>
</tutorials>
<methods>
<method name="get_current_length" qualifiers="const">
<return type="float" />
<description>
Returns the current state length.
[b]Note:[/b] It is possible that any [AnimationRootNode] can be nodes as well as animations. This means that there can be multiple animations within a single state. Which animation length has priority depends on the nodes connected inside it. Also, if a transition does not reset, the remaining length at that point will be returned.
</description>
</method>
<method name="get_current_node" qualifiers="const">
<return type="StringName" />
<description>
Returns the currently playing animation state.
[b]Note:[/b] When using a cross-fade, the current state changes to the next state immediately after the cross-fade begins.
</description>
</method>
<method name="get_current_play_position" qualifiers="const">
<return type="float" />
<description>
Returns the playback position within the current animation state.
</description>
</method>
<method name="get_fading_from_node" qualifiers="const">
<return type="StringName" />
<description>
Returns the starting state of currently fading animation.
</description>
</method>
<method name="get_travel_path" qualifiers="const">
<return type="StringName[]" />
<description>
Returns the current travel path as computed internally by the A* algorithm.
</description>
</method>
<method name="is_playing" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if an animation is playing.
</description>
</method>
<method name="next">
<return type="void" />
<description>
If there is a next path by travel or auto advance, immediately transitions from the current state to the next state.
</description>
</method>
<method name="start">
<return type="void" />
<param index="0" name="node" type="StringName" />
<param index="1" name="reset" type="bool" default="true" />
<description>
Starts playing the given animation.
If [param reset] is [code]true[/code], the animation is played from the beginning.
</description>
</method>
<method name="stop">
<return type="void" />
<description>
Stops the currently playing animation.
</description>
</method>
<method name="travel">
<return type="void" />
<param index="0" name="to_node" type="StringName" />
<param index="1" name="reset_on_teleport" type="bool" default="true" />
<description>
Transitions from the current state to another one, following the shortest path.
If the path does not connect from the current state, the animation will play after the state teleports.
If [param reset_on_teleport] is [code]true[/code], the animation is played from the beginning when the travel cause a teleportation.
</description>
</method>
</methods>
<members>
<member name="resource_local_to_scene" type="bool" setter="set_local_to_scene" getter="is_local_to_scene" overrides="Resource" default="true" />
</members>
<signals>
<signal name="state_finished">
<param index="0" name="state" type="StringName" />
<description>
Emitted when the [param state] finishes playback. If [param state] is a state machine set to grouped mode, its signals are passed through with its name prefixed.
If there is a crossfade, this will be fired when the influence of the [method get_fading_from_node] animation is no longer present.
</description>
</signal>
<signal name="state_started">
<param index="0" name="state" type="StringName" />
<description>
Emitted when the [param state] starts playback. If [param state] is a state machine set to grouped mode, its signals are passed through with its name prefixed.
</description>
</signal>
</signals>
</class>

78
doc/classes/AnimationNodeStateMachineTransition.xml Normal file
View File

@@ -0,0 +1,78 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimationNodeStateMachineTransition" inherits="Resource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
A transition within an [AnimationNodeStateMachine] connecting two [AnimationRootNode]s.
</brief_description>
<description>
The path generated when using [method AnimationNodeStateMachinePlayback.travel] is limited to the nodes connected by [AnimationNodeStateMachineTransition].
You can set the timing and conditions of the transition in detail.
</description>
<tutorials>
<link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>
</tutorials>
<members>
<member name="advance_condition" type="StringName" setter="set_advance_condition" getter="get_advance_condition" default="&amp;&quot;&quot;">
Turn on auto advance when this condition is set. The provided name will become a boolean parameter on the [AnimationTree] that can be controlled from code (see [url=$DOCS_URL/tutorials/animation/animation_tree.html#controlling-from-code]Using AnimationTree[/url]). For example, if [member AnimationTree.tree_root] is an [AnimationNodeStateMachine] and [member advance_condition] is set to [code]"idle"[/code]:
[codeblocks]
[gdscript]
$animation_tree.set("parameters/conditions/idle", is_on_floor and (linear_velocity.x == 0))
[/gdscript]
[csharp]
GetNode&lt;AnimationTree&gt;("animation_tree").Set("parameters/conditions/idle", IsOnFloor &amp;&amp; (LinearVelocity.X == 0));
[/csharp]
[/codeblocks]
</member>
<member name="advance_expression" type="String" setter="set_advance_expression" getter="get_advance_expression" default="&quot;&quot;">
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 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.
</member>
<member name="priority" type="int" setter="set_priority" getter="get_priority" default="1">
Lower priority transitions are preferred when travelling through the tree via [method AnimationNodeStateMachinePlayback.travel] or [member advance_mode] is set to [constant ADVANCE_MODE_AUTO].
</member>
<member name="reset" type="bool" setter="set_reset" getter="is_reset" default="true">
If [code]true[/code], the destination animation is played back from the beginning when switched.
</member>
<member name="switch_mode" type="int" setter="set_switch_mode" getter="get_switch_mode" enum="AnimationNodeStateMachineTransition.SwitchMode" default="0">
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. 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.
[b]Note:[/b] [AnimationNodeStateMachine] transitions the current state immediately after the start of the fading. The precise remaining time can only be inferred from the main animation. When [AnimationNodeOutput] is considered as the most upstream, so the [member xfade_time] is not scaled depending on the downstream delta. See also [member AnimationNodeOneShot.fadeout_time].
</member>
</members>
<signals>
<signal name="advance_condition_changed">
<description>
Emitted when [member advance_condition] is changed.
</description>
</signal>
</signals>
<constants>
<constant name="SWITCH_MODE_IMMEDIATE" value="0" enum="SwitchMode">
Switch to the next state immediately. The current state will end and blend into the beginning of the new one.
</constant>
<constant name="SWITCH_MODE_SYNC" value="1" enum="SwitchMode">
Switch to the next state immediately, but will seek the new state to the playback position of the old state.
</constant>
<constant name="SWITCH_MODE_AT_END" value="2" enum="SwitchMode">
Wait for the current state playback to end, then switch to the beginning of the next state animation.
</constant>
<constant name="ADVANCE_MODE_DISABLED" value="0" enum="AdvanceMode">
Don't use this transition.
</constant>
<constant name="ADVANCE_MODE_ENABLED" value="1" enum="AdvanceMode">
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 [code]true[/code] (if assigned).
</constant>
</constants>
</class>

15
doc/classes/AnimationNodeSub2.xml Normal file
View File

@@ -0,0 +1,15 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimationNodeSub2" inherits="AnimationNodeSync" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Blends two animations subtractively inside of an [AnimationNodeBlendTree].
</brief_description>
<description>
A resource to add to an [AnimationNodeBlendTree]. Blends two animations subtractively based on the amount value.
This animation node is usually used for pre-calculation to cancel out any extra poses from the animation for the "add" animation source in [AnimationNodeAdd2] or [AnimationNodeAdd3].
In general, the blend value should be in the [code][0.0, 1.0][/code] range, but values outside of this range can be used for amplified or inverted animations.
[b]Note:[/b] This calculation is different from using a negative value in [AnimationNodeAdd2], since the transformation matrices do not satisfy the commutative law. [AnimationNodeSub2] multiplies the transformation matrix of the inverted animation from the left side, while negative [AnimationNodeAdd2] multiplies it from the right side.
</description>
<tutorials>
<link title="AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>
</tutorials>
</class>

18
doc/classes/AnimationNodeSync.xml Normal file
View File

@@ -0,0 +1,18 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimationNodeSync" inherits="AnimationNode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Base class for [AnimationNode]s with multiple input ports that must be synchronized.
</brief_description>
<description>
An animation node used to combine, mix, or blend two or more animations together while keeping them synchronized within an [AnimationTree].
</description>
<tutorials>
<link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>
</tutorials>
<members>
<member name="sync" type="bool" setter="set_use_sync" getter="is_using_sync" default="false">
If [code]false[/code], the blended animations' frame are stopped when the blend value is [code]0[/code].
If [code]true[/code], forcing the blended animations to advance frame.
</member>
</members>
</class>

13
doc/classes/AnimationNodeTimeScale.xml Normal file
View File

@@ -0,0 +1,13 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimationNodeTimeScale" inherits="AnimationNode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
A time-scaling animation node used in [AnimationTree].
</brief_description>
<description>
Allows to scale the speed of the animation (or reverse it) in any child [AnimationNode]s. Setting it to [code]0.0[/code] will pause the animation.
</description>
<tutorials>
<link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>
<link title="3D Platformer Demo">https://godotengine.org/asset-library/asset/2748</link>
</tutorials>
</class>

38
doc/classes/AnimationNodeTimeSeek.xml Normal file
View File

@@ -0,0 +1,38 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimationNodeTimeSeek" inherits="AnimationNode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
A time-seeking animation node used in [AnimationTree].
</brief_description>
<description>
This animation node can be used to cause a seek command to happen to any sub-children of the animation graph. Use to play an [Animation] from the start or a certain playback position inside the [AnimationNodeBlendTree].
After setting the time and changing the animation playback, the time seek node automatically goes into sleep mode on the next process frame by setting its [code]seek_request[/code] value to [code]-1.0[/code].
[codeblocks]
[gdscript]
# Play child animation from the start.
animation_tree.set("parameters/TimeSeek/seek_request", 0.0)
# Alternative syntax (same result as above).
animation_tree["parameters/TimeSeek/seek_request"] = 0.0
# Play child animation from 12 second timestamp.
animation_tree.set("parameters/TimeSeek/seek_request", 12.0)
# Alternative syntax (same result as above).
animation_tree["parameters/TimeSeek/seek_request"] = 12.0
[/gdscript]
[csharp]
// Play child animation from the start.
animationTree.Set("parameters/TimeSeek/seek_request", 0.0);
// Play child animation from 12 second timestamp.
animationTree.Set("parameters/TimeSeek/seek_request", 12.0);
[/csharp]
[/codeblocks]
</description>
<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>

106
doc/classes/AnimationNodeTransition.xml Normal file
View File

@@ -0,0 +1,106 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimationNodeTransition" inherits="AnimationNodeSync" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
A transition within an [AnimationTree] connecting two [AnimationNode]s.
</brief_description>
<description>
Simple state machine for cases which don't require a more advanced [AnimationNodeStateMachine]. Animations can be connected to the inputs and transition times can be specified.
After setting the request and changing the animation playback, the transition node automatically clears the request on the next process frame by setting its [code]transition_request[/code] value to empty.
[b]Note:[/b] When using a cross-fade, [code]current_state[/code] and [code]current_index[/code] change to the next state immediately after the cross-fade begins.
[codeblocks]
[gdscript]
# Play child animation connected to "state_2" port.
animation_tree.set("parameters/Transition/transition_request", "state_2")
# Alternative syntax (same result as above).
animation_tree["parameters/Transition/transition_request"] = "state_2"
# Get current state name (read-only).
animation_tree.get("parameters/Transition/current_state")
# Alternative syntax (same result as above).
animation_tree["parameters/Transition/current_state"]
# Get current state index (read-only).
animation_tree.get("parameters/Transition/current_index")
# Alternative syntax (same result as above).
animation_tree["parameters/Transition/current_index"]
[/gdscript]
[csharp]
// Play child animation connected to "state_2" port.
animationTree.Set("parameters/Transition/transition_request", "state_2");
// Get current state name (read-only).
animationTree.Get("parameters/Transition/current_state");
// Get current state index (read-only).
animationTree.Get("parameters/Transition/current_index");
[/csharp]
[/codeblocks]
</description>
<tutorials>
<link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>
<link title="3D Platformer Demo">https://godotengine.org/asset-library/asset/2748</link>
<link title="Third Person Shooter (TPS) Demo">https://godotengine.org/asset-library/asset/2710</link>
</tutorials>
<methods>
<method name="is_input_loop_broken_at_end" qualifiers="const">
<return type="bool" />
<param index="0" name="input" type="int" />
<description>
Returns whether the animation breaks the loop at the end of the loop cycle for transition.
</description>
</method>
<method name="is_input_reset" qualifiers="const">
<return type="bool" />
<param index="0" name="input" type="int" />
<description>
Returns whether the animation restarts when the animation transitions from the other animation.
</description>
</method>
<method name="is_input_set_as_auto_advance" qualifiers="const">
<return type="bool" />
<param index="0" name="input" type="int" />
<description>
Returns [code]true[/code] if auto-advance is enabled for the given [param input] index.
</description>
</method>
<method name="set_input_as_auto_advance">
<return type="void" />
<param index="0" name="input" type="int" />
<param index="1" name="enable" type="bool" />
<description>
Enables or disables auto-advance for the given [param input] index. If enabled, state changes to the next input after playing the animation once. If enabled for the last input state, it loops to the first.
</description>
</method>
<method name="set_input_break_loop_at_end">
<return type="void" />
<param index="0" name="input" type="int" />
<param index="1" name="enable" type="bool" />
<description>
If [code]true[/code], breaks the loop at the end of the loop cycle for transition, even if the animation is looping.
</description>
</method>
<method name="set_input_reset">
<return type="void" />
<param index="0" name="input" type="int" />
<param index="1" name="enable" type="bool" />
<description>
If [code]true[/code], the destination animation is restarted when the animation transitions.
</description>
</method>
</methods>
<members>
<member name="allow_transition_to_self" type="bool" setter="set_allow_transition_to_self" getter="is_allow_transition_to_self" default="false">
If [code]true[/code], allows transition to the self state. When the reset option is enabled in input, the animation is restarted. If [code]false[/code], nothing happens on the transition to the self state.
</member>
<member name="input_count" type="int" setter="set_input_count" getter="get_input_count" default="0">
The number of enabled input ports for this 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. 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.
[b]Note:[/b] [AnimationNodeTransition] transitions the current state immediately after the start of the fading. The precise remaining time can only be inferred from the main animation. When [AnimationNodeOutput] is considered as the most upstream, so the [member xfade_time] is not scaled depending on the downstream delta. See also [member AnimationNodeOneShot.fadeout_time].
</member>
</members>
</class>

353
doc/classes/AnimationPlayer.xml Normal file
View File

@@ -0,0 +1,353 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimationPlayer" inherits="AnimationMixer" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
A node used for animation playback.
</brief_description>
<description>
An animation player is used for general-purpose playback of animations. It contains a dictionary of [AnimationLibrary] resources and custom blend times between animation transitions.
Some methods and properties use a single key to reference an animation directly. These keys are formatted as the key for the library, followed by a forward slash, then the key for the animation within the library, for example [code]"movement/run"[/code]. If the library's key is an empty string (known as the default library), the forward slash is omitted, being the same key used by the library.
[AnimationPlayer] is better-suited than [Tween] for more complex animations, for example ones with non-trivial timings. It can also be used over [Tween] if the animation track editor is more convenient than doing it in code.
Updating the target properties of animations occurs at the process frame.
</description>
<tutorials>
<link title="2D Sprite animation">$DOCS_URL/tutorials/2d/2d_sprite_animation.html</link>
<link title="Animation documentation index">$DOCS_URL/tutorials/animation/index.html</link>
<link title="Third Person Shooter (TPS) Demo">https://godotengine.org/asset-library/asset/2710</link>
</tutorials>
<methods>
<method name="animation_get_next" qualifiers="const">
<return type="StringName" />
<param index="0" name="animation_from" type="StringName" />
<description>
Returns the key of the animation which is queued to play after the [param animation_from] animation.
</description>
</method>
<method name="animation_set_next">
<return type="void" />
<param index="0" name="animation_from" type="StringName" />
<param index="1" name="animation_to" type="StringName" />
<description>
Triggers the [param animation_to] animation when the [param animation_from] animation completes.
</description>
</method>
<method name="clear_queue">
<return type="void" />
<description>
Clears all queued, unplayed animations.
</description>
</method>
<method name="get_blend_time" qualifiers="const">
<return type="float" />
<param index="0" name="animation_from" type="StringName" />
<param index="1" name="animation_to" type="StringName" />
<description>
Returns the blend time (in seconds) between two animations, referenced by their keys.
</description>
</method>
<method name="get_method_call_mode" qualifiers="const" deprecated="Use [member AnimationMixer.callback_mode_method] instead.">
<return type="int" enum="AnimationPlayer.AnimationMethodCallMode" />
<description>
Returns the call mode used for "Call Method" tracks.
</description>
</method>
<method name="get_playing_speed" qualifiers="const">
<return type="float" />
<description>
Returns the actual playing speed of current animation or [code]0[/code] if not playing. This speed is the [member speed_scale] property multiplied by [code]custom_speed[/code] argument specified when calling the [method play] method.
Returns a negative value if the current animation is playing backwards.
</description>
</method>
<method name="get_process_callback" qualifiers="const" deprecated="Use [member AnimationMixer.callback_mode_process] instead.">
<return type="int" enum="AnimationPlayer.AnimationProcessCallback" />
<description>
Returns the process notification in which to update animations.
</description>
</method>
<method name="get_queue">
<return type="PackedStringArray" />
<description>
Returns a list of the animation keys that are currently queued to play.
</description>
</method>
<method name="get_root" qualifiers="const" deprecated="Use [member AnimationMixer.root_node] instead.">
<return type="NodePath" />
<description>
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 a section.
</description>
</method>
<method name="is_playing" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if an animation is currently playing (even if [member speed_scale] and/or [code]custom_speed[/code] are [code]0[/code]).
</description>
</method>
<method name="pause">
<return type="void" />
<description>
Pauses the currently playing animation. The [member current_animation_position] will be kept and calling [method play] or [method play_backwards] without arguments or with the same animation name as [member assigned_animation] will resume the animation.
See also [method stop].
</description>
</method>
<method name="play">
<return type="void" />
<param index="0" name="name" type="StringName" default="&amp;&quot;&quot;" />
<param index="1" name="custom_blend" type="float" default="-1" />
<param index="2" name="custom_speed" type="float" default="1.0" />
<param index="3" name="from_end" type="bool" default="false" />
<description>
Plays the animation with key [param name]. Custom blend times and speed can be set.
The [param from_end] option only affects when switching to a new animation track, or if the same track but at the start or end. It does not affect resuming playback that was paused in the middle of an animation. If [param custom_speed] is negative and [param from_end] is [code]true[/code], the animation will play backwards (which is equivalent to calling [method play_backwards]).
The [AnimationPlayer] keeps track of its current or last played animation with [member assigned_animation]. If this method is called with that same animation [param name], or with no [param name] parameter, the assigned animation will resume playing if it was paused.
[b]Note:[/b] The animation will be updated the next time the [AnimationPlayer] is processed. If other variables are updated at the same time this is called, they may be updated too early. To perform the update immediately, call [code]advance(0)[/code].
</description>
</method>
<method name="play_backwards">
<return type="void" />
<param index="0" name="name" type="StringName" default="&amp;&quot;&quot;" />
<param index="1" name="custom_blend" type="float" default="-1" />
<description>
Plays the animation with key [param name] in reverse.
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;" />
<param index="1" name="duration" type="float" default="-1.0" />
<param index="2" name="custom_blend" type="float" default="-1" />
<param index="3" name="custom_speed" type="float" default="1.0" />
<param index="4" name="from_end" type="bool" default="false" />
<param index="5" name="trans_type" type="int" enum="Tween.TransitionType" default="0" />
<param index="6" name="ease_type" type="int" enum="Tween.EaseType" default="0" />
<description>
See also [method AnimationMixer.capture].
You can use this method to use more detailed options for capture than those performed by [member playback_auto_capture]. When [member playback_auto_capture] is [code]false[/code], this method is almost the same as the following:
[codeblock]
capture(name, duration, trans_type, ease_type)
play(name, custom_blend, custom_speed, from_end)
[/codeblock]
If [param name] is blank, it specifies [member assigned_animation].
If [param duration] is a negative value, the duration is set to the interval between the current position and the first key, when [param from_end] is [code]true[/code], uses the interval between the current position and the last key instead.
[b]Note:[/b] The [param duration] takes [member speed_scale] into account, but [param custom_speed] does not, because the capture cache is interpolated with the blend result and the result may contain multiple animations.
</description>
</method>
<method name="queue">
<return type="void" />
<param index="0" name="name" type="StringName" />
<description>
Queues an animation for playback once the current animation and all previously queued animations are done.
[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. Does nothing if a section has not been set.
</description>
</method>
<method name="seek">
<return type="void" />
<param index="0" name="seconds" type="float" />
<param index="1" name="update" type="bool" default="false" />
<param index="2" name="update_only" type="bool" default="false" />
<description>
Seeks the animation to the [param seconds] point in time (in seconds). If [param update] is [code]true[/code], the animation updates too, otherwise it updates at process time. Events between the current frame and [param seconds] are skipped.
If [param update_only] is [code]true[/code], the method / audio / animation playback tracks will not be processed.
[b]Note:[/b] Seeking to the end of the animation doesn't emit [signal AnimationMixer.animation_finished]. If you want to skip animation and emit the signal, use [method AnimationMixer.advance].
</description>
</method>
<method name="set_blend_time">
<return type="void" />
<param index="0" name="animation_from" type="StringName" />
<param index="1" name="animation_to" type="StringName" />
<param index="2" name="sec" type="float" />
<description>
Specifies a blend time (in seconds) between two animations, referenced by their keys.
</description>
</method>
<method name="set_method_call_mode" deprecated="Use [member AnimationMixer.callback_mode_method] instead.">
<return type="void" />
<param index="0" name="mode" type="int" enum="AnimationPlayer.AnimationMethodCallMode" />
<description>
Sets the call mode used for "Call Method" tracks.
</description>
</method>
<method name="set_process_callback" deprecated="Use [member AnimationMixer.callback_mode_process] instead.">
<return type="void" />
<param index="0" name="mode" type="int" enum="AnimationPlayer.AnimationProcessCallback" />
<description>
Sets the process notification in which to update animations.
</description>
</method>
<method name="set_root" deprecated="Use [member AnimationMixer.root_node] instead.">
<return type="void" />
<param index="0" name="path" type="NodePath" />
<description>
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" />
<description>
Stops the currently playing animation. The animation position is reset to [code]0[/code] and the [code]custom_speed[/code] is reset to [code]1.0[/code]. See also [method pause].
If [param keep_state] is [code]true[/code], the animation state is not updated visually.
[b]Note:[/b] The method / audio / animation playback tracks will not be processed by this method.
</description>
</method>
</methods>
<members>
<member name="assigned_animation" type="String" setter="set_assigned_animation" getter="get_assigned_animation">
If playing, the current animation's key, otherwise, the animation last played. When set, this changes the animation, but will not play it unless already playing. See also [member current_animation].
</member>
<member name="autoplay" type="String" setter="set_autoplay" getter="get_autoplay" default="&quot;&quot;">
The key of the animation to play when the scene loads.
</member>
<member name="current_animation" type="String" setter="set_current_animation" getter="get_current_animation" default="&quot;&quot;">
The key of the currently playing animation. If no animation is playing, the property's value is an empty string. Changing this value does not restart the animation. See [method play] for more information on playing animations.
[b]Note:[/b] While this property appears in the Inspector, it's not meant to be edited, and it's not saved in the scene. This property is mainly used to get the currently playing animation, and internally for animation playback tracks. For more information, see [Animation].
</member>
<member name="current_animation_length" type="float" setter="" getter="get_current_animation_length">
The length (in seconds) of the currently playing animation.
</member>
<member name="current_animation_position" type="float" setter="" getter="get_current_animation_position">
The position (in seconds) of the currently playing animation.
</member>
<member name="movie_quit_on_finish" type="bool" setter="set_movie_quit_on_finish_enabled" getter="is_movie_quit_on_finish_enabled" default="false">
If [code]true[/code] and the engine is running in Movie Maker mode (see [MovieWriter]), exits the engine with [method SceneTree.quit] as soon as an animation is done playing in this [AnimationPlayer]. A message is printed when the engine quits for this reason.
[b]Note:[/b] This obeys the same logic as the [signal AnimationMixer.animation_finished] signal, so it will not quit the engine if the animation is set to be looping.
</member>
<member name="playback_auto_capture" type="bool" setter="set_auto_capture" getter="is_auto_capture" default="true">
If [code]true[/code], performs [method AnimationMixer.capture] before playback automatically. This means just [method play_with_capture] is executed with default arguments instead of [method play].
[b]Note:[/b] Capture interpolation is only performed if the animation contains a capture track. See also [constant Animation.UPDATE_CAPTURE].
</member>
<member name="playback_auto_capture_duration" type="float" setter="set_auto_capture_duration" getter="get_auto_capture_duration" default="-1.0">
See also [method play_with_capture] and [method AnimationMixer.capture].
If [member playback_auto_capture_duration] is negative value, the duration is set to the interval between the current position and the first key.
</member>
<member name="playback_auto_capture_ease_type" type="int" setter="set_auto_capture_ease_type" getter="get_auto_capture_ease_type" enum="Tween.EaseType" default="0">
The ease type of the capture interpolation. See also [enum Tween.EaseType].
</member>
<member name="playback_auto_capture_transition_type" type="int" setter="set_auto_capture_transition_type" getter="get_auto_capture_transition_type" enum="Tween.TransitionType" default="0">
The transition type of the capture interpolation. See also [enum Tween.TransitionType].
</member>
<member name="playback_default_blend_time" type="float" setter="set_default_blend_time" getter="get_default_blend_time" default="0.0">
The default time in which to blend animations. Ranges from 0 to 4096 with 0.01 precision.
</member>
<member name="speed_scale" type="float" setter="set_speed_scale" getter="get_speed_scale" default="1.0">
The speed scaling ratio. For example, if this value is [code]1[/code], then the animation plays at normal speed. If it's [code]0.5[/code], then it plays at half speed. If it's [code]2[/code], then it plays at double speed.
If set to a negative value, the animation is played in reverse. If set to [code]0[/code], the animation will not advance.
</member>
</members>
<signals>
<signal name="animation_changed">
<param index="0" name="old_name" type="StringName" />
<param index="1" name="new_name" type="StringName" />
<description>
Emitted when a queued animation plays after the previous animation finished. See also [method AnimationPlayer.queue].
[b]Note:[/b] The signal is not emitted when the animation is changed via [method AnimationPlayer.play] or by an [AnimationTree].
</description>
</signal>
<signal name="current_animation_changed">
<param index="0" name="name" type="String" />
<description>
Emitted when [member current_animation] changes.
</description>
</signal>
</signals>
<constants>
<constant name="ANIMATION_PROCESS_PHYSICS" value="0" enum="AnimationProcessCallback" deprecated="See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS].">
</constant>
<constant name="ANIMATION_PROCESS_IDLE" value="1" enum="AnimationProcessCallback" deprecated="See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_IDLE].">
</constant>
<constant name="ANIMATION_PROCESS_MANUAL" value="2" enum="AnimationProcessCallback" deprecated="See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_MANUAL].">
</constant>
<constant name="ANIMATION_METHOD_CALL_DEFERRED" value="0" enum="AnimationMethodCallMode" deprecated="See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_METHOD_DEFERRED].">
</constant>
<constant name="ANIMATION_METHOD_CALL_IMMEDIATE" value="1" enum="AnimationMethodCallMode" deprecated="See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_METHOD_IMMEDIATE].">
</constant>
</constants>
</class>

13
doc/classes/AnimationRootNode.xml Normal file
View File

@@ -0,0 +1,13 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimationRootNode" inherits="AnimationNode" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Base class for [AnimationNode]s that hold one or multiple composite animations. Usually used for [member AnimationTree.tree_root].
</brief_description>
<description>
[AnimationRootNode] is a base class for [AnimationNode]s that hold a complete animation. A complete animation refers to the output of an [AnimationNodeOutput] in an [AnimationNodeBlendTree] or the output of another [AnimationRootNode]. Used for [member AnimationTree.tree_root] or in other [AnimationRootNode]s.
Examples of built-in root nodes include [AnimationNodeBlendTree] (allows blending nodes between each other using various modes), [AnimationNodeStateMachine] (allows to configure blending and transitions between nodes using a state machine pattern), [AnimationNodeBlendSpace2D] (allows linear blending between [b]three[/b] [AnimationNode]s), [AnimationNodeBlendSpace1D] (allows linear blending only between [b]two[/b] [AnimationNode]s).
</description>
<tutorials>
<link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>
</tutorials>
</class>

57
doc/classes/AnimationTree.xml Normal file
View File

@@ -0,0 +1,57 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AnimationTree" inherits="AnimationMixer" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
A node used for advanced animation transitions in an [AnimationPlayer].
</brief_description>
<description>
A node used for advanced animation transitions in an [AnimationPlayer].
[b]Note:[/b] When linked with an [AnimationPlayer], several properties and methods of the corresponding [AnimationPlayer] will not function as expected. Playback and transitions should be handled using only the [AnimationTree] and its constituent [AnimationNode](s). The [AnimationPlayer] node should be used solely for adding, deleting, and editing animations.
</description>
<tutorials>
<link title="Using AnimationTree">$DOCS_URL/tutorials/animation/animation_tree.html</link>
<link title="Third Person Shooter (TPS) Demo">https://godotengine.org/asset-library/asset/2710</link>
</tutorials>
<methods>
<method name="get_process_callback" qualifiers="const" deprecated="Use [member AnimationMixer.callback_mode_process] instead.">
<return type="int" enum="AnimationTree.AnimationProcessCallback" />
<description>
Returns the process notification in which to update animations.
</description>
</method>
<method name="set_process_callback" deprecated="Use [member AnimationMixer.callback_mode_process] instead.">
<return type="void" />
<param index="0" name="mode" type="int" enum="AnimationTree.AnimationProcessCallback" />
<description>
Sets the process notification in which to update animations.
</description>
</method>
</methods>
<members>
<member name="advance_expression_base_node" type="NodePath" setter="set_advance_expression_base_node" getter="get_advance_expression_base_node" default="NodePath(&quot;.&quot;)">
The path to the [Node] used to evaluate the [AnimationNode] [Expression] if one is not explicitly specified internally.
</member>
<member name="anim_player" type="NodePath" setter="set_animation_player" getter="get_animation_player" default="NodePath(&quot;&quot;)">
The path to the [AnimationPlayer] used for animating.
</member>
<member name="callback_mode_discrete" type="int" setter="set_callback_mode_discrete" getter="get_callback_mode_discrete" overrides="AnimationMixer" enum="AnimationMixer.AnimationCallbackModeDiscrete" default="2" />
<member name="deterministic" type="bool" setter="set_deterministic" getter="is_deterministic" overrides="AnimationMixer" default="true" />
<member name="tree_root" type="AnimationRootNode" setter="set_tree_root" getter="get_tree_root">
The root animation node of this [AnimationTree]. See [AnimationRootNode].
</member>
</members>
<signals>
<signal name="animation_player_changed">
<description>
Emitted when the [member anim_player] is changed.
</description>
</signal>
</signals>
<constants>
<constant name="ANIMATION_PROCESS_PHYSICS" value="0" enum="AnimationProcessCallback" deprecated="See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS].">
</constant>
<constant name="ANIMATION_PROCESS_IDLE" value="1" enum="AnimationProcessCallback" deprecated="See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_IDLE].">
</constant>
<constant name="ANIMATION_PROCESS_MANUAL" value="2" enum="AnimationProcessCallback" deprecated="See [constant AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_MANUAL].">
</constant>
</constants>
</class>

217
doc/classes/Area2D.xml Normal file
View File

@@ -0,0 +1,217 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="Area2D" inherits="CollisionObject2D" keywords="trigger" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
A region of 2D space that detects other [CollisionObject2D]s entering or exiting it.
</brief_description>
<description>
[Area2D] is a region of 2D space defined by one or multiple [CollisionShape2D] or [CollisionPolygon2D] child nodes. It detects when other [CollisionObject2D]s enter or exit it, and it also keeps track of which collision objects haven't exited it yet (i.e. which one are overlapping it).
This node can also locally alter or override physics parameters (gravity, damping) and route audio to custom audio buses.
[b]Note:[/b] Areas and bodies created with [PhysicsServer2D] might not interact as expected with [Area2D]s, and might not emit signals or track objects correctly.
</description>
<tutorials>
<link title="Using Area2D">$DOCS_URL/tutorials/physics/using_area_2d.html</link>
<link title="2D Dodge The Creeps Demo">https://godotengine.org/asset-library/asset/2712</link>
<link title="2D Pong Demo">https://godotengine.org/asset-library/asset/2728</link>
<link title="2D Platformer Demo">https://godotengine.org/asset-library/asset/2727</link>
</tutorials>
<methods>
<method name="get_overlapping_areas" qualifiers="const">
<return type="Area2D[]" />
<description>
Returns a list of intersecting [Area2D]s. The overlapping area's [member CollisionObject2D.collision_layer] must be part of this area's [member CollisionObject2D.collision_mask] in order to be detected.
For performance reasons (collisions are all processed at the same time) this list is modified once during the physics step, not immediately after objects are moved. Consider using signals instead.
</description>
</method>
<method name="get_overlapping_bodies" qualifiers="const">
<return type="Node2D[]" />
<description>
Returns a list of intersecting [PhysicsBody2D]s and [TileMap]s. The overlapping body's [member CollisionObject2D.collision_layer] must be part of this area's [member CollisionObject2D.collision_mask] in order to be detected.
For performance reasons (collisions are all processed at the same time) this list is modified once during the physics step, not immediately after objects are moved. Consider using signals instead.
</description>
</method>
<method name="has_overlapping_areas" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if intersecting any [Area2D]s, otherwise returns [code]false[/code]. The overlapping area's [member CollisionObject2D.collision_layer] must be part of this area's [member CollisionObject2D.collision_mask] in order to be detected.
For performance reasons (collisions are all processed at the same time) the list of overlapping areas is modified once during the physics step, not immediately after objects are moved. Consider using signals instead.
</description>
</method>
<method name="has_overlapping_bodies" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if intersecting any [PhysicsBody2D]s or [TileMap]s, otherwise returns [code]false[/code]. The overlapping body's [member CollisionObject2D.collision_layer] must be part of this area's [member CollisionObject2D.collision_mask] in order to be detected.
For performance reasons (collisions are all processed at the same time) the list of overlapping bodies is modified once during the physics step, not immediately after objects are moved. Consider using signals instead.
</description>
</method>
<method name="overlaps_area" qualifiers="const">
<return type="bool" />
<param index="0" name="area" type="Node" />
<description>
Returns [code]true[/code] if the given [Area2D] intersects or overlaps this [Area2D], [code]false[/code] otherwise.
[b]Note:[/b] The result of this test is not immediate after moving objects. For performance, the list of overlaps is updated once per frame and before the physics step. Consider using signals instead.
</description>
</method>
<method name="overlaps_body" qualifiers="const">
<return type="bool" />
<param index="0" name="body" type="Node" />
<description>
Returns [code]true[/code] if the given physics body intersects or overlaps this [Area2D], [code]false[/code] otherwise.
[b]Note:[/b] The result of this test is not immediate after moving objects. For performance, list of overlaps is updated once per frame and before the physics step. Consider using signals instead.
The [param body] argument can either be a [PhysicsBody2D] or a [TileMap] instance. While TileMaps are not physics bodies themselves, they register their tiles with collision shapes as a virtual physics body.
</description>
</method>
</methods>
<members>
<member name="angular_damp" type="float" setter="set_angular_damp" getter="get_angular_damp" default="1.0">
The rate at which objects stop spinning in this area. Represents the angular velocity lost per second.
See [member ProjectSettings.physics/2d/default_angular_damp] for more details about damping.
</member>
<member name="angular_damp_space_override" type="int" setter="set_angular_damp_space_override_mode" getter="get_angular_damp_space_override_mode" enum="Area2D.SpaceOverride" default="0">
Override mode for angular damping calculations within this area.
</member>
<member name="audio_bus_name" type="StringName" setter="set_audio_bus_name" getter="get_audio_bus_name" default="&amp;&quot;Master&quot;">
The name of the area's audio bus.
</member>
<member name="audio_bus_override" type="bool" setter="set_audio_bus_override" getter="is_overriding_audio_bus" default="false">
If [code]true[/code], the area's audio bus overrides the default audio bus.
</member>
<member name="gravity" type="float" setter="set_gravity" getter="get_gravity" default="980.0">
The area's gravity intensity (in pixels per second squared). This value multiplies the gravity direction. This is useful to alter the force of gravity without altering its direction.
</member>
<member name="gravity_direction" type="Vector2" setter="set_gravity_direction" getter="get_gravity_direction" default="Vector2(0, 1)">
The area's gravity vector (not normalized).
</member>
<member name="gravity_point" type="bool" setter="set_gravity_is_point" getter="is_gravity_a_point" default="false">
If [code]true[/code], gravity is calculated from a point (set via [member gravity_point_center]). See also [member gravity_space_override].
</member>
<member name="gravity_point_center" type="Vector2" setter="set_gravity_point_center" getter="get_gravity_point_center" default="Vector2(0, 1)">
If gravity is a point (see [member gravity_point]), this will be the point of attraction.
</member>
<member name="gravity_point_unit_distance" type="float" setter="set_gravity_point_unit_distance" getter="get_gravity_point_unit_distance" default="0.0">
The distance at which the gravity strength is equal to [member gravity]. For example, on a planet 100 pixels in radius with a surface gravity of 4.0 px/s², set the [member gravity] to 4.0 and the unit distance to 100.0. The gravity will have falloff according to the inverse square law, so in the example, at 200 pixels from the center the gravity will be 1.0 px/s² (twice the distance, 1/4th the gravity), at 50 pixels it will be 16.0 px/s² (half the distance, 4x the gravity), and so on.
The above is true only when the unit distance is a positive number. When this is set to 0.0, the gravity will be constant regardless of distance.
</member>
<member name="gravity_space_override" type="int" setter="set_gravity_space_override_mode" getter="get_gravity_space_override_mode" enum="Area2D.SpaceOverride" default="0">
Override mode for gravity calculations within this area.
</member>
<member name="linear_damp" type="float" setter="set_linear_damp" getter="get_linear_damp" default="0.1">
The rate at which objects stop moving in this area. Represents the linear velocity lost per second.
See [member ProjectSettings.physics/2d/default_linear_damp] for more details about damping.
</member>
<member name="linear_damp_space_override" type="int" setter="set_linear_damp_space_override_mode" getter="get_linear_damp_space_override_mode" enum="Area2D.SpaceOverride" default="0">
Override mode for linear damping calculations within this area.
</member>
<member name="monitorable" type="bool" setter="set_monitorable" getter="is_monitorable" default="true">
If [code]true[/code], other monitoring areas can detect this area.
</member>
<member name="monitoring" type="bool" setter="set_monitoring" getter="is_monitoring" default="true">
If [code]true[/code], the area detects bodies or areas entering and exiting it.
</member>
<member name="priority" type="int" setter="set_priority" getter="get_priority" default="0">
The area's priority. Higher priority areas are processed first. The [World2D]'s physics is always processed last, after all areas.
</member>
</members>
<signals>
<signal name="area_entered">
<param index="0" name="area" type="Area2D" />
<description>
Emitted when the received [param area] enters this area. Requires [member monitoring] to be set to [code]true[/code].
</description>
</signal>
<signal name="area_exited">
<param index="0" name="area" type="Area2D" />
<description>
Emitted when the received [param area] exits this area. Requires [member monitoring] to be set to [code]true[/code].
</description>
</signal>
<signal name="area_shape_entered">
<param index="0" name="area_rid" type="RID" />
<param index="1" name="area" type="Area2D" />
<param index="2" name="area_shape_index" type="int" />
<param index="3" name="local_shape_index" type="int" />
<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:[/b] Get the [CollisionShape2D] node from the shape index:
[codeblocks]
[gdscript]
var other_shape_owner = area.shape_find_owner(area_shape_index)
var other_shape_node = area.shape_owner_get_owner(other_shape_owner)
var local_shape_owner = shape_find_owner(local_shape_index)
var local_shape_node = shape_owner_get_owner(local_shape_owner)
[/gdscript]
[/codeblocks]
</description>
</signal>
<signal name="area_shape_exited">
<param index="0" name="area_rid" type="RID" />
<param index="1" name="area" type="Area2D" />
<param index="2" name="area_shape_index" type="int" />
<param index="3" name="local_shape_index" type="int" />
<description>
Emitted when a [Shape2D] of the received [param area] exits a shape of this area. Requires [member monitoring] to be set to [code]true[/code].
See also [signal area_shape_entered].
</description>
</signal>
<signal name="body_entered">
<param index="0" name="body" type="Node2D" />
<description>
Emitted when the received [param body] enters 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].
</description>
</signal>
<signal name="body_exited">
<param index="0" name="body" type="Node2D" />
<description>
Emitted when the received [param body] exits 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].
</description>
</signal>
<signal name="body_shape_entered">
<param index="0" name="body_rid" type="RID" />
<param index="1" name="body" type="Node2D" />
<param index="2" name="body_shape_index" type="int" />
<param index="3" name="local_shape_index" type="int" />
<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:[/b] Get the [CollisionShape2D] node from the shape index:
[codeblocks]
[gdscript]
var body_shape_owner = body.shape_find_owner(body_shape_index)
var body_shape_node = body.shape_owner_get_owner(body_shape_owner)
var local_shape_owner = shape_find_owner(local_shape_index)
var local_shape_node = shape_owner_get_owner(local_shape_owner)
[/gdscript]
[/codeblocks]
</description>
</signal>
<signal name="body_shape_exited">
<param index="0" name="body_rid" type="RID" />
<param index="1" name="body" type="Node2D" />
<param index="2" name="body_shape_index" type="int" />
<param index="3" name="local_shape_index" type="int" />
<description>
Emitted when a [Shape2D] of the received [param body] exits 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].
See also [signal body_shape_entered].
</description>
</signal>
</signals>
<constants>
<constant name="SPACE_OVERRIDE_DISABLED" value="0" enum="SpaceOverride">
This area does not affect gravity/damping.
</constant>
<constant name="SPACE_OVERRIDE_COMBINE" value="1" enum="SpaceOverride">
This area adds its gravity/damping values to whatever has been calculated so far (in [member priority] order).
</constant>
<constant name="SPACE_OVERRIDE_COMBINE_REPLACE" value="2" enum="SpaceOverride">
This area adds its gravity/damping values to whatever has been calculated so far (in [member priority] order), ignoring any lower priority areas.
</constant>
<constant name="SPACE_OVERRIDE_REPLACE" value="3" enum="SpaceOverride">
This area replaces any gravity/damping, even the defaults, ignoring any lower priority areas.
</constant>
<constant name="SPACE_OVERRIDE_REPLACE_COMBINE" value="4" enum="SpaceOverride">
This area replaces any gravity/damping calculated so far (in [member priority] order), but keeps calculating the rest of the areas.
</constant>
</constants>
</class>

241
doc/classes/Area3D.xml Normal file
View File

@@ -0,0 +1,241 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="Area3D" inherits="CollisionObject3D" keywords="trigger" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
A region of 3D space that detects other [CollisionObject3D]s entering or exiting it.
</brief_description>
<description>
[Area3D] is a region of 3D space defined by one or multiple [CollisionShape3D] or [CollisionPolygon3D] child nodes. It detects when other [CollisionObject3D]s enter or exit it, and it also keeps track of which collision objects haven't exited it yet (i.e. which one are overlapping it).
This node can also locally alter or override physics parameters (gravity, damping) and route audio to custom audio buses.
[b]Note:[/b] Areas and bodies created with [PhysicsServer3D] might not interact as expected with [Area3D]s, and might not emit signals or track objects correctly.
[b]Warning:[/b] Using a [ConcavePolygonShape3D] inside a [CollisionShape3D] child of this node (created e.g. by using the [b]Create Trimesh Collision Sibling[/b] option in the [b]Mesh[/b] menu that appears when selecting a [MeshInstance3D] node) may give unexpected results, since this collision shape is hollow. If this is not desired, it has to be split into multiple [ConvexPolygonShape3D]s or primitive shapes like [BoxShape3D], or in some cases it may be replaceable by a [CollisionPolygon3D].
</description>
<tutorials>
<link title="Using Area2D">$DOCS_URL/tutorials/physics/using_area_2d.html</link>
<link title="3D Platformer Demo">https://godotengine.org/asset-library/asset/2748</link>
<link title="GUI in 3D Viewport Demo">https://godotengine.org/asset-library/asset/2807</link>
</tutorials>
<methods>
<method name="get_overlapping_areas" qualifiers="const">
<return type="Area3D[]" />
<description>
Returns a list of intersecting [Area3D]s. The overlapping area's [member CollisionObject3D.collision_layer] must be part of this area's [member CollisionObject3D.collision_mask] in order to be detected.
For performance reasons (collisions are all processed at the same time) this list is modified once during the physics step, not immediately after objects are moved. Consider using signals instead.
</description>
</method>
<method name="get_overlapping_bodies" qualifiers="const">
<return type="Node3D[]" />
<description>
Returns a list of intersecting [PhysicsBody3D]s and [GridMap]s. The overlapping body's [member CollisionObject3D.collision_layer] must be part of this area's [member CollisionObject3D.collision_mask] in order to be detected.
For performance reasons (collisions are all processed at the same time) this list is modified once during the physics step, not immediately after objects are moved. Consider using signals instead.
</description>
</method>
<method name="has_overlapping_areas" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if intersecting any [Area3D]s, otherwise returns [code]false[/code]. The overlapping area's [member CollisionObject3D.collision_layer] must be part of this area's [member CollisionObject3D.collision_mask] in order to be detected.
For performance reasons (collisions are all processed at the same time) the list of overlapping areas is modified once during the physics step, not immediately after objects are moved. Consider using signals instead.
</description>
</method>
<method name="has_overlapping_bodies" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if intersecting any [PhysicsBody3D]s or [GridMap]s, otherwise returns [code]false[/code]. The overlapping body's [member CollisionObject3D.collision_layer] must be part of this area's [member CollisionObject3D.collision_mask] in order to be detected.
For performance reasons (collisions are all processed at the same time) the list of overlapping bodies is modified once during the physics step, not immediately after objects are moved. Consider using signals instead.
</description>
</method>
<method name="overlaps_area" qualifiers="const">
<return type="bool" />
<param index="0" name="area" type="Node" />
<description>
Returns [code]true[/code] if the given [Area3D] intersects or overlaps this [Area3D], [code]false[/code] otherwise.
[b]Note:[/b] The result of this test is not immediate after moving objects. For performance, list of overlaps is updated once per frame and before the physics step. Consider using signals instead.
</description>
</method>
<method name="overlaps_body" qualifiers="const">
<return type="bool" />
<param index="0" name="body" type="Node" />
<description>
Returns [code]true[/code] if the given physics body intersects or overlaps this [Area3D], [code]false[/code] otherwise.
[b]Note:[/b] The result of this test is not immediate after moving objects. For performance, list of overlaps is updated once per frame and before the physics step. Consider using signals instead.
The [param body] argument can either be a [PhysicsBody3D] or a [GridMap] instance. While GridMaps are not physics body themselves, they register their tiles with collision shapes as a virtual physics body.
</description>
</method>
</methods>
<members>
<member name="angular_damp" type="float" setter="set_angular_damp" getter="get_angular_damp" default="0.1">
The rate at which objects stop spinning in this area. Represents the angular velocity lost per second.
See [member ProjectSettings.physics/3d/default_angular_damp] for more details about damping.
</member>
<member name="angular_damp_space_override" type="int" setter="set_angular_damp_space_override_mode" getter="get_angular_damp_space_override_mode" enum="Area3D.SpaceOverride" default="0">
Override mode for angular damping calculations within this area.
</member>
<member name="audio_bus_name" type="StringName" setter="set_audio_bus_name" getter="get_audio_bus_name" default="&amp;&quot;Master&quot;">
The name of the area's audio bus.
</member>
<member name="audio_bus_override" type="bool" setter="set_audio_bus_override" getter="is_overriding_audio_bus" default="false">
If [code]true[/code], the area's audio bus overrides the default audio bus.
</member>
<member name="gravity" type="float" setter="set_gravity" getter="get_gravity" default="9.8">
The area's gravity intensity (in meters per second squared). This value multiplies the gravity direction. This is useful to alter the force of gravity without altering its direction.
</member>
<member name="gravity_direction" type="Vector3" setter="set_gravity_direction" getter="get_gravity_direction" default="Vector3(0, -1, 0)">
The area's gravity vector (not normalized).
</member>
<member name="gravity_point" type="bool" setter="set_gravity_is_point" getter="is_gravity_a_point" default="false">
If [code]true[/code], gravity is calculated from a point (set via [member gravity_point_center]). See also [member gravity_space_override].
</member>
<member name="gravity_point_center" type="Vector3" setter="set_gravity_point_center" getter="get_gravity_point_center" default="Vector3(0, -1, 0)">
If gravity is a point (see [member gravity_point]), this will be the point of attraction.
</member>
<member name="gravity_point_unit_distance" type="float" setter="set_gravity_point_unit_distance" getter="get_gravity_point_unit_distance" default="0.0">
The distance at which the gravity strength is equal to [member gravity]. For example, on a planet 100 meters in radius with a surface gravity of 4.0 m/s², set the [member gravity] to 4.0 and the unit distance to 100.0. The gravity will have falloff according to the inverse square law, so in the example, at 200 meters from the center the gravity will be 1.0 m/s² (twice the distance, 1/4th the gravity), at 50 meters it will be 16.0 m/s² (half the distance, 4x the gravity), and so on.
The above is true only when the unit distance is a positive number. When this is set to 0.0, the gravity will be constant regardless of distance.
</member>
<member name="gravity_space_override" type="int" setter="set_gravity_space_override_mode" getter="get_gravity_space_override_mode" enum="Area3D.SpaceOverride" default="0">
Override mode for gravity calculations within this area.
</member>
<member name="linear_damp" type="float" setter="set_linear_damp" getter="get_linear_damp" default="0.1">
The rate at which objects stop moving in this area. Represents the linear velocity lost per second.
See [member ProjectSettings.physics/3d/default_linear_damp] for more details about damping.
</member>
<member name="linear_damp_space_override" type="int" setter="set_linear_damp_space_override_mode" getter="get_linear_damp_space_override_mode" enum="Area3D.SpaceOverride" default="0">
Override mode for linear damping calculations within this area.
</member>
<member name="monitorable" type="bool" setter="set_monitorable" getter="is_monitorable" default="true">
If [code]true[/code], other monitoring areas can detect this area.
</member>
<member name="monitoring" type="bool" setter="set_monitoring" getter="is_monitoring" default="true">
If [code]true[/code], the area detects bodies or areas entering and exiting it.
</member>
<member name="priority" type="int" setter="set_priority" getter="get_priority" default="0">
The area's priority. Higher priority areas are processed first. The [World3D]'s physics is always processed last, after all areas.
</member>
<member name="reverb_bus_amount" type="float" setter="set_reverb_amount" getter="get_reverb_amount" default="0.0">
The degree to which this area applies reverb to its associated audio. Ranges from [code]0[/code] to [code]1[/code] with [code]0.1[/code] precision.
</member>
<member name="reverb_bus_enabled" type="bool" setter="set_use_reverb_bus" getter="is_using_reverb_bus" default="false">
If [code]true[/code], the area applies reverb to its associated audio.
</member>
<member name="reverb_bus_name" type="StringName" setter="set_reverb_bus_name" getter="get_reverb_bus_name" default="&amp;&quot;Master&quot;">
The name of the reverb bus to use for this area's associated audio.
</member>
<member name="reverb_bus_uniformity" type="float" setter="set_reverb_uniformity" getter="get_reverb_uniformity" default="0.0">
The degree to which this area's reverb is a uniform effect. Ranges from [code]0[/code] to [code]1[/code] with [code]0.1[/code] precision.
</member>
<member name="wind_attenuation_factor" type="float" setter="set_wind_attenuation_factor" getter="get_wind_attenuation_factor" default="0.0">
The exponential rate at which wind force decreases with distance from its origin.
[b]Note:[/b] This wind force only applies to [SoftBody3D] nodes. Other physics bodies are currently not affected by wind.
</member>
<member name="wind_force_magnitude" type="float" setter="set_wind_force_magnitude" getter="get_wind_force_magnitude" default="0.0">
The magnitude of area-specific wind force.
[b]Note:[/b] This wind force only applies to [SoftBody3D] nodes. Other physics bodies are currently not affected by wind.
</member>
<member name="wind_source_path" type="NodePath" setter="set_wind_source_path" getter="get_wind_source_path" default="NodePath(&quot;&quot;)">
The [Node3D] which is used to specify the direction and origin of an area-specific wind force. The direction is opposite to the z-axis of the [Node3D]'s local transform, and its origin is the origin of the [Node3D]'s local transform.
[b]Note:[/b] This wind force only applies to [SoftBody3D] nodes. Other physics bodies are currently not affected by wind.
</member>
</members>
<signals>
<signal name="area_entered">
<param index="0" name="area" type="Area3D" />
<description>
Emitted when the received [param area] enters this area. Requires [member monitoring] to be set to [code]true[/code].
</description>
</signal>
<signal name="area_exited">
<param index="0" name="area" type="Area3D" />
<description>
Emitted when the received [param area] exits this area. Requires [member monitoring] to be set to [code]true[/code].
</description>
</signal>
<signal name="area_shape_entered">
<param index="0" name="area_rid" type="RID" />
<param index="1" name="area" type="Area3D" />
<param index="2" name="area_shape_index" type="int" />
<param index="3" name="local_shape_index" type="int" />
<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:[/b] Get the [CollisionShape3D] node from the shape index:
[codeblocks]
[gdscript]
var other_shape_owner = area.shape_find_owner(area_shape_index)
var other_shape_node = area.shape_owner_get_owner(other_shape_owner)
var local_shape_owner = shape_find_owner(local_shape_index)
var local_shape_node = shape_owner_get_owner(local_shape_owner)
[/gdscript]
[/codeblocks]
</description>
</signal>
<signal name="area_shape_exited">
<param index="0" name="area_rid" type="RID" />
<param index="1" name="area" type="Area3D" />
<param index="2" name="area_shape_index" type="int" />
<param index="3" name="local_shape_index" type="int" />
<description>
Emitted when a [Shape3D] of the received [param area] exits a shape of this area. Requires [member monitoring] to be set to [code]true[/code].
See also [signal area_shape_entered].
</description>
</signal>
<signal name="body_entered">
<param index="0" name="body" type="Node3D" />
<description>
Emitted when the received [param body] enters 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].
</description>
</signal>
<signal name="body_exited">
<param index="0" name="body" type="Node3D" />
<description>
Emitted when the received [param body] exits 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].
</description>
</signal>
<signal name="body_shape_entered">
<param index="0" name="body_rid" type="RID" />
<param index="1" name="body" type="Node3D" />
<param index="2" name="body_shape_index" type="int" />
<param index="3" name="local_shape_index" type="int" />
<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:[/b] Get the [CollisionShape3D] node from the shape index:
[codeblocks]
[gdscript]
var body_shape_owner = body.shape_find_owner(body_shape_index)
var body_shape_node = body.shape_owner_get_owner(body_shape_owner)
var local_shape_owner = shape_find_owner(local_shape_index)
var local_shape_node = shape_owner_get_owner(local_shape_owner)
[/gdscript]
[/codeblocks]
</description>
</signal>
<signal name="body_shape_exited">
<param index="0" name="body_rid" type="RID" />
<param index="1" name="body" type="Node3D" />
<param index="2" name="body_shape_index" type="int" />
<param index="3" name="local_shape_index" type="int" />
<description>
Emitted when a [Shape3D] of the received [param body] exits 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].
See also [signal body_shape_entered].
</description>
</signal>
</signals>
<constants>
<constant name="SPACE_OVERRIDE_DISABLED" value="0" enum="SpaceOverride">
This area does not affect gravity/damping.
</constant>
<constant name="SPACE_OVERRIDE_COMBINE" value="1" enum="SpaceOverride">
This area adds its gravity/damping values to whatever has been calculated so far (in [member priority] order).
</constant>
<constant name="SPACE_OVERRIDE_COMBINE_REPLACE" value="2" enum="SpaceOverride">
This area adds its gravity/damping values to whatever has been calculated so far (in [member priority] order), ignoring any lower priority areas.
</constant>
<constant name="SPACE_OVERRIDE_REPLACE" value="3" enum="SpaceOverride">
This area replaces any gravity/damping, even the defaults, ignoring any lower priority areas.
</constant>
<constant name="SPACE_OVERRIDE_REPLACE_COMBINE" value="4" enum="SpaceOverride">
This area replaces any gravity/damping calculated so far (in [member priority] order), but keeps calculating the rest of the areas.
</constant>
</constants>
</class>

885
doc/classes/Array.xml Normal file
View File

@@ -0,0 +1,885 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="Array" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
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 [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"]
print(array[0]) # Prints "First"
print(array[2]) # Prints 3
print(array[-1]) # Prints "Last"
array[1] = "Second"
print(array[1]) # Prints "Second"
print(array[-3]) # Prints "Second"
[/gdscript]
[csharp]
Godot.Collections.Array array = ["First", 2, 3, "Last"];
GD.Print(array[0]); // Prints "First"
GD.Print(array[2]); // Prints 3
GD.Print(array[^1]); // Prints "Last"
array[1] = "Second";
GD.Print(array[1]); // 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].
[b]Note:[/b] Erasing elements while iterating over arrays is [b]not[/b] supported and will result in unpredictable behavior.
[b]Differences between packed arrays, typed arrays, and untyped arrays:[/b] Packed arrays are generally faster to iterate on and modify compared to a typed array of the same type (e.g. [PackedInt64Array] versus [code]Array[int][/code]). Also, packed arrays consume less memory. As a downside, packed arrays are less flexible as they don't offer as many convenience methods such as [method Array.map]. Typed arrays are in turn faster to iterate on and modify than untyped arrays.
</description>
<tutorials>
</tutorials>
<constructors>
<constructor name="Array">
<return type="Array" />
<description>
Constructs an empty [Array].
</description>
</constructor>
<constructor name="Array">
<return type="Array" />
<param index="0" name="base" type="Array" />
<param index="1" name="type" type="int" />
<param index="2" name="class_name" type="StringName" />
<param index="3" name="script" type="Variant" />
<description>
Creates a typed array from the [param base] array. A typed array can only contain elements of the given type, or that inherit from the given class, as described by this constructor's parameters:
- [param type] is the built-in [Variant] type, as one the [enum Variant.Type] constants.
- [param class_name] is the built-in class name (see [method Object.get_class]).
- [param script] is the associated script. It must be a [Script] instance or [code]null[/code].
If [param type] is not [constant TYPE_OBJECT], [param class_name] must be an empty [StringName] and [param script] must be [code]null[/code].
[codeblock]
class_name Sword
extends Node
class Stats:
pass
func _ready():
var a = Array([], TYPE_INT, "", null) # Array[int]
var b = Array([], TYPE_OBJECT, "Node", null) # Array[Node]
var c = Array([], TYPE_OBJECT, "Node", Sword) # Array[Sword]
var d = Array([], TYPE_OBJECT, "RefCounted", Stats) # Array[Stats]
[/codeblock]
The [param base] array's elements are converted when necessary. If this is not possible or [param base] is already typed, this constructor fails and returns an empty [Array].
In GDScript, this constructor is usually not necessary, as it is possible to create a typed array through static typing:
[codeblock]
var numbers: Array[float] = []
var children: Array[Node] = [$Node, $Sprite2D, $RigidBody3D]
var integers: Array[int] = [0.2, 4.5, -2.0]
print(integers) # Prints [0, 4, -2]
[/codeblock]
</description>
</constructor>
<constructor name="Array">
<return type="Array" />
<param index="0" name="from" type="Array" />
<description>
Returns the same array as [param from]. If you need a copy of the array, use [method duplicate].
</description>
</constructor>
<constructor name="Array">
<return type="Array" />
<param index="0" name="from" type="PackedByteArray" />
<description>
Constructs an array from a [PackedByteArray].
</description>
</constructor>
<constructor name="Array">
<return type="Array" />
<param index="0" name="from" type="PackedColorArray" />
<description>
Constructs an array from a [PackedColorArray].
</description>
</constructor>
<constructor name="Array">
<return type="Array" />
<param index="0" name="from" type="PackedFloat32Array" />
<description>
Constructs an array from a [PackedFloat32Array].
</description>
</constructor>
<constructor name="Array">
<return type="Array" />
<param index="0" name="from" type="PackedFloat64Array" />
<description>
Constructs an array from a [PackedFloat64Array].
</description>
</constructor>
<constructor name="Array">
<return type="Array" />
<param index="0" name="from" type="PackedInt32Array" />
<description>
Constructs an array from a [PackedInt32Array].
</description>
</constructor>
<constructor name="Array">
<return type="Array" />
<param index="0" name="from" type="PackedInt64Array" />
<description>
Constructs an array from a [PackedInt64Array].
</description>
</constructor>
<constructor name="Array">
<return type="Array" />
<param index="0" name="from" type="PackedStringArray" />
<description>
Constructs an array from a [PackedStringArray].
</description>
</constructor>
<constructor name="Array">
<return type="Array" />
<param index="0" name="from" type="PackedVector2Array" />
<description>
Constructs an array from a [PackedVector2Array].
</description>
</constructor>
<constructor name="Array">
<return type="Array" />
<param index="0" name="from" type="PackedVector3Array" />
<description>
Constructs an array from a [PackedVector3Array].
</description>
</constructor>
<constructor name="Array">
<return type="Array" />
<param index="0" name="from" type="PackedVector4Array" />
<description>
Constructs an array from a [PackedVector4Array].
</description>
</constructor>
</constructors>
<methods>
<method name="all" qualifiers="const">
<return type="bool" />
<param index="0" name="method" type="Callable" />
<description>
Calls the given [Callable] on each element in the array and returns [code]true[/code] if the [Callable] returns [code]true[/code] for [i]all[/i] elements in the array. If the [Callable] returns [code]false[/code] for one array element or more, this method returns [code]false[/code].
The [param method] should take one [Variant] parameter (the current array element) and return a [bool].
[codeblocks]
[gdscript]
func greater_than_5(number):
return number &gt; 5
func _ready():
print([6, 10, 6].all(greater_than_5)) # Prints true (3/3 elements evaluate to true).
print([4, 10, 4].all(greater_than_5)) # Prints false (1/3 elements evaluate to true).
print([4, 4, 4].all(greater_than_5)) # Prints false (0/3 elements evaluate to true).
print([].all(greater_than_5)) # Prints true (0/0 elements evaluate to true).
# Same as the first line above, but using a lambda function.
print([6, 10, 6].all(func(element): return element &gt; 5)) # Prints true
[/gdscript]
[csharp]
private static bool GreaterThan5(int number)
{
return number &gt; 5;
}
public override void _Ready()
{
// 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).
GD.Print(new Godot.Collections.Array&gt;int&lt; { 4, 10, 4 }.All(GreaterThan5));
// 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).
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
}
[/csharp]
[/codeblocks]
See also [method any], [method filter], [method map] and [method reduce].
[b]Note:[/b] Unlike relying on the size of an array returned by [method filter], this method will return as early as possible to improve performance (especially with large arrays).
[b]Note:[/b] For an empty array, this method [url=https://en.wikipedia.org/wiki/Vacuous_truth]always[/url] returns [code]true[/code].
</description>
</method>
<method name="any" qualifiers="const">
<return type="bool" />
<param index="0" name="method" type="Callable" />
<description>
Calls the given [Callable] on each element in the array and returns [code]true[/code] if the [Callable] returns [code]true[/code] for [i]one or more[/i] elements in the array. If the [Callable] returns [code]false[/code] for all elements in the array, this method returns [code]false[/code].
The [param method] should take one [Variant] parameter (the current array element) and return a [bool].
[codeblock]
func greater_than_5(number):
return number &gt; 5
func _ready():
print([6, 10, 6].any(greater_than_5)) # Prints true (3 elements evaluate to true).
print([4, 10, 4].any(greater_than_5)) # Prints true (1 elements evaluate to true).
print([4, 4, 4].any(greater_than_5)) # Prints false (0 elements evaluate to true).
print([].any(greater_than_5)) # Prints false (0 elements evaluate to true).
# Same as the first line above, but using a lambda function.
print([6, 10, 6].any(func(number): return number &gt; 5)) # Prints true
[/codeblock]
See also [method all], [method filter], [method map] and [method reduce].
[b]Note:[/b] Unlike relying on the size of an array returned by [method filter], this method will return as early as possible to improve performance (especially with large arrays).
[b]Note:[/b] For an empty array, this method always returns [code]false[/code].
</description>
</method>
<method name="append">
<return type="void" />
<param index="0" name="value" type="Variant" />
<description>
Appends [param value] at the end of the array (alias of [method push_back]).
</description>
</method>
<method name="append_array">
<return type="void" />
<param index="0" name="array" type="Array" />
<description>
Appends another [param array] at the end of this array.
[codeblock]
var numbers = [1, 2, 3]
var extra = [4, 5, 6]
numbers.append_array(extra)
print(numbers) # Prints [1, 2, 3, 4, 5, 6]
[/codeblock]
</description>
</method>
<method name="assign">
<return type="void" />
<param index="0" name="array" type="Array" />
<description>
Assigns elements of another [param array] into the array. Resizes the array to match [param array]. Performs type conversions if the array is typed.
</description>
</method>
<method name="back" qualifiers="const">
<return type="Variant" />
<description>
Returns the last element of the array. If the array is empty, fails and returns [code]null[/code]. See also [method front].
[b]Note:[/b] Unlike with the [code][][/code] operator ([code]array[-1][/code]), an error is generated without stopping project execution.
</description>
</method>
<method name="bsearch" qualifiers="const">
<return type="int" />
<param index="0" name="value" type="Variant" />
<param index="1" name="before" type="bool" default="true" />
<description>
Returns the index of [param value] in the sorted array. If it cannot be found, returns where [param value] should be inserted to keep the array sorted. The algorithm used is [url=https://en.wikipedia.org/wiki/Binary_search_algorithm]binary search[/url].
If [param before] is [code]true[/code] (as by default), the returned index comes before all existing elements equal to [param value] in the array.
[codeblock]
var numbers = [2, 4, 8, 10]
var idx = numbers.bsearch(7)
numbers.insert(idx, 7)
print(numbers) # Prints [2, 4, 7, 8, 10]
var fruits = ["Apple", "Lemon", "Lemon", "Orange"]
print(fruits.bsearch("Lemon", true)) # Prints 1, points at the first "Lemon".
print(fruits.bsearch("Lemon", false)) # Prints 3, points at "Orange".
[/codeblock]
[b]Note:[/b] Calling [method bsearch] on an [i]unsorted[/i] array will result in unexpected behavior. Use [method sort] before calling this method.
</description>
</method>
<method name="bsearch_custom" qualifiers="const">
<return type="int" />
<param index="0" name="value" type="Variant" />
<param index="1" name="func" type="Callable" />
<param index="2" name="before" type="bool" default="true" />
<description>
Returns the index of [param value] in the sorted array. If it cannot be found, returns where [param value] should be inserted to keep the array sorted (using [param func] for the comparisons). The algorithm used is [url=https://en.wikipedia.org/wiki/Binary_search_algorithm]binary search[/url].
Similar to [method sort_custom], [param func] is called as many times as necessary, receiving one array element and [param value] as arguments. The function should return [code]true[/code] if the array element should be [i]behind[/i] [param value], otherwise it should return [code]false[/code].
If [param before] is [code]true[/code] (as by default), the returned index comes before all existing elements equal to [param value] in the array.
[codeblock]
func sort_by_amount(a, b):
if a[1] &lt; b[1]:
return true
return false
func _ready():
var my_items = [["Tomato", 2], ["Kiwi", 5], ["Rice", 9]]
var apple = ["Apple", 5]
# "Apple" is inserted before "Kiwi".
my_items.insert(my_items.bsearch_custom(apple, sort_by_amount, true), apple)
var banana = ["Banana", 5]
# "Banana" is inserted after "Kiwi".
my_items.insert(my_items.bsearch_custom(banana, sort_by_amount, false), banana)
# Prints [["Tomato", 2], ["Apple", 5], ["Kiwi", 5], ["Banana", 5], ["Rice", 9]]
print(my_items)
[/codeblock]
[b]Note:[/b] Calling [method bsearch_custom] on an [i]unsorted[/i] array will result in unexpected behavior. Use [method sort_custom] with [param func] before calling this method.
</description>
</method>
<method name="clear">
<return type="void" />
<description>
Removes all elements from the array. This is equivalent to using [method resize] with a size of [code]0[/code].
</description>
</method>
<method name="count" qualifiers="const">
<return type="int" />
<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">
<return type="Array" />
<param index="0" name="deep" type="bool" default="false" />
<description>
Returns a new copy of the array.
By default, a [b]shallow[/b] copy is returned: all nested [Array], [Dictionary], and [Resource] elements are shared with the original array. Modifying any of those in one array will also affect them in the other.
If [param deep] is [code]true[/code], a [b]deep[/b] copy is returned: all nested arrays and dictionaries are also duplicated (recursively). Any [Resource] is still shared with the original array, though.
</description>
</method>
<method name="duplicate_deep" qualifiers="const">
<return type="Array" />
<param index="0" name="deep_subresources_mode" type="int" default="1" />
<description>
Duplicates this array, deeply, like [method duplicate][code](true)[/code], with extra control over how subresources are handled.
[param deep_subresources_mode] must be one of the values from [enum Resource.DeepDuplicateMode]. By default, only internal resources will be duplicated (recursively).
</description>
</method>
<method name="erase">
<return type="void" />
<param index="0" name="value" type="Variant" />
<description>
Finds and removes the first occurrence of [param value] from the array. If [param value] does not exist in the array, nothing happens. To remove an element by index, use [method remove_at] instead.
[b]Note:[/b] This method shifts every element's index after the removed [param value] back, which may have a noticeable performance cost, especially on larger arrays.
[b]Note:[/b] Erasing elements while iterating over arrays is [b]not[/b] supported and will result in unpredictable behavior.
</description>
</method>
<method name="fill">
<return type="void" />
<param index="0" name="value" type="Variant" />
<description>
Assigns the given [param value] to all elements in the array.
This method can often be combined with [method resize] to create an array with a given size and initialized elements:
[codeblocks]
[gdscript]
var array = []
array.resize(5)
array.fill(2)
print(array) # Prints [2, 2, 2, 2, 2]
[/gdscript]
[csharp]
Godot.Collections.Array array = [];
array.Resize(5);
array.Fill(2);
GD.Print(array); // Prints [2, 2, 2, 2, 2]
[/csharp]
[/codeblocks]
[b]Note:[/b] If [param value] is a [Variant] passed by reference ([Object]-derived, [Array], [Dictionary], etc.), the array will be filled with references to the same [param value], which are not duplicates.
</description>
</method>
<method name="filter" qualifiers="const">
<return type="Array" />
<param index="0" name="method" type="Callable" />
<description>
Calls the given [Callable] on each element in the array and returns a new, filtered [Array].
The [param method] receives one of the array elements as an argument, and should return [code]true[/code] to add the element to the filtered array, or [code]false[/code] to exclude it.
[codeblock]
func is_even(number):
return number % 2 == 0
func _ready():
print([1, 4, 5, 8].filter(is_even)) # Prints [4, 8]
# Same as above, but using a lambda function.
print([1, 4, 5, 8].filter(func(number): return number % 2 == 0))
[/codeblock]
See also [method any], [method all], [method map] and [method reduce].
</description>
</method>
<method name="find" qualifiers="const">
<return type="int" />
<param index="0" name="what" type="Variant" />
<param index="1" name="from" type="int" default="0" />
<description>
Returns the index of the [b]first[/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 end of the array.
[b]Note:[/b] If you just want to know whether the array contains [param what], use [method has] ([code]Contains[/code] in C#). In GDScript, you may also use the [code]in[/code] operator.
[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>
Returns the first element of the array. If the array is empty, fails and returns [code]null[/code]. See also [method back].
[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. If [param index] out-of-bounds or negative, this method fails and returns [code]null[/code].
This method is similar (but not identical) to the [code][][/code] operator. Most notably, when this method fails, it doesn't pause project execution if run from the editor.
</description>
</method>
<method name="get_typed_builtin" qualifiers="const">
<return type="int" />
<description>
Returns the built-in [Variant] type of the typed array as a [enum Variant.Type] constant. If the array is not typed, returns [constant TYPE_NIL]. See also [method is_typed].
</description>
</method>
<method name="get_typed_class_name" qualifiers="const">
<return type="StringName" />
<description>
Returns the [b]built-in[/b] class name of the typed array, if the built-in [Variant] type [constant TYPE_OBJECT]. Otherwise, returns an empty [StringName]. See also [method is_typed] and [method Object.get_class].
</description>
</method>
<method name="get_typed_script" qualifiers="const">
<return type="Variant" />
<description>
Returns the [Script] instance associated with this typed array, or [code]null[/code] if it does not exist. See also [method is_typed].
</description>
</method>
<method name="has" qualifiers="const" keywords="includes, contains">
<return type="bool" />
<param index="0" name="value" type="Variant" />
<description>
Returns [code]true[/code] if the array contains the given [param value].
[codeblocks]
[gdscript]
print(["inside", 7].has("inside")) # Prints true
print(["inside", 7].has("outside")) # Prints false
print(["inside", 7].has(7)) # Prints true
print(["inside", 7].has("7")) # Prints false
[/gdscript]
[csharp]
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
[/csharp]
[/codeblocks]
In GDScript, this is equivalent to the [code]in[/code] operator:
[codeblock]
if 4 in [2, 4, 6, 8]:
print("4 is here!") # Will be printed.
[/codeblock]
[b]Note:[/b] For performance reasons, the search is affected by the [param value]'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="hash" qualifiers="const">
<return type="int" />
<description>
Returns a hashed 32-bit integer value representing the array and its contents.
[b]Note:[/b] Arrays with equal hash values are [i]not[/i] guaranteed to be the same, as a result of hash collisions. On the countrary, arrays with different hash values are guaranteed to be different.
</description>
</method>
<method name="insert">
<return type="int" />
<param index="0" name="position" type="int" />
<param index="1" name="value" type="Variant" />
<description>
Inserts a new element ([param value]) at a given index ([param position]) in the array. [param position] should be between [code]0[/code] and the array's [method size]. If negative, [param position] is considered relative to the end of the array.
Returns [constant OK] on success, or one of the other [enum Error] constants if this method fails.
[b]Note:[/b] Every element's index after [param position] needs to be shifted forward, which may have a noticeable performance cost, especially on larger arrays.
</description>
</method>
<method name="is_empty" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if the array is empty ([code][][/code]). See also [method size].
</description>
</method>
<method name="is_read_only" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if the array is read-only. See [method make_read_only].
In GDScript, arrays are automatically read-only if declared with the [code]const[/code] keyword.
</description>
</method>
<method name="is_same_typed" qualifiers="const">
<return type="bool" />
<param index="0" name="array" type="Array" />
<description>
Returns [code]true[/code] if this array is typed the same as the given [param array]. See also [method is_typed].
</description>
</method>
<method name="is_typed" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if the array is typed. Typed arrays can only contain elements of a specific type, as defined by the typed array constructor. The methods of a typed array are still expected to return a generic [Variant].
In GDScript, it is possible to define a typed array with static typing:
[codeblock]
var numbers: Array[float] = [0.2, 4.2, -2.0]
print(numbers.is_typed()) # Prints true
[/codeblock]
</description>
</method>
<method name="make_read_only">
<return type="void" />
<description>
Makes the array read-only. The array's elements cannot be overridden with different values, and their order cannot change. Does not apply to nested elements, such as dictionaries.
In GDScript, arrays are automatically read-only if declared with the [code]const[/code] keyword.
</description>
</method>
<method name="map" qualifiers="const">
<return type="Array" />
<param index="0" name="method" type="Callable" />
<description>
Calls the given [Callable] for each element in the array and returns a new array filled with values returned by the [param method].
The [param method] should take one [Variant] parameter (the current array element) and can return any [Variant].
[codeblock]
func double(number):
return number * 2
func _ready():
print([1, 2, 3].map(double)) # Prints [2, 4, 6]
# Same as above, but using a lambda function.
print([1, 2, 3].map(func(element): return element * 2))
[/codeblock]
See also [method filter], [method reduce], [method any] and [method all].
</description>
</method>
<method name="max" qualifiers="const">
<return type="Variant" />
<description>
Returns the maximum value contained in the array, if all elements can be compared. Otherwise, returns [code]null[/code]. See also [method min].
To find the maximum value using a custom comparator, you can use [method reduce].
</description>
</method>
<method name="min" qualifiers="const">
<return type="Variant" />
<description>
Returns the minimum value contained in the array, if all elements can be compared. Otherwise, returns [code]null[/code]. See also [method max].
</description>
</method>
<method name="pick_random" qualifiers="const">
<return type="Variant" />
<description>
Returns a random element from the array. Generates an error and returns [code]null[/code] if the array is empty.
[codeblocks]
[gdscript]
# May print 1, 2, 3.25, or "Hi".
print([1, 2, 3.25, "Hi"].pick_random())
[/gdscript]
[csharp]
Godot.Collections.Array array = [1, 2, 3.25f, "Hi"];
GD.Print(array.PickRandom()); // May print 1, 2, 3.25, or "Hi".
[/csharp]
[/codeblocks]
[b]Note:[/b] Like many similar functions in the engine (such as [method @GlobalScope.randi] or [method shuffle]), this method uses a common, global random seed. To get a predictable outcome from this method, see [method @GlobalScope.seed].
</description>
</method>
<method name="pop_at">
<return type="Variant" />
<param index="0" name="position" type="int" />
<description>
Removes and returns the element of the array at index [param position]. If negative, [param position] is considered relative to the end of the array. Returns [code]null[/code] if the array is empty. If [param position] is out of bounds, an error message is also generated.
[b]Note:[/b] This method shifts every element's index after [param position] back, which may have a noticeable performance cost, especially on larger arrays.
</description>
</method>
<method name="pop_back">
<return type="Variant" />
<description>
Removes and returns the last element of the array. Returns [code]null[/code] if the array is empty, without generating an error. See also [method pop_front].
</description>
</method>
<method name="pop_front">
<return type="Variant" />
<description>
Removes and returns the first element of the array. Returns [code]null[/code] if the array is empty, without generating an error. See also [method pop_back].
[b]Note:[/b] This method shifts every other element's index back, which may have a noticeable performance cost, especially on larger arrays.
</description>
</method>
<method name="push_back">
<return type="void" />
<param index="0" name="value" type="Variant" />
<description>
Appends an element at the end of the array. See also [method push_front].
</description>
</method>
<method name="push_front">
<return type="void" />
<param index="0" name="value" type="Variant" />
<description>
Adds an element at the beginning of the array. See also [method push_back].
[b]Note:[/b] This method shifts every other element's index forward, which may have a noticeable performance cost, especially on larger arrays.
</description>
</method>
<method name="reduce" qualifiers="const">
<return type="Variant" />
<param index="0" name="method" type="Callable" />
<param index="1" name="accum" type="Variant" default="null" />
<description>
Calls the given [Callable] for each element in array, accumulates the result in [param accum], then returns it.
The [param method] takes two arguments: the current value of [param accum] and the current array element. If [param accum] is [code]null[/code] (as by default), the iteration will start from the second element, with the first one used as initial value of [param accum].
[codeblock]
func sum(accum, number):
return accum + number
func _ready():
print([1, 2, 3].reduce(sum, 0)) # Prints 6
print([1, 2, 3].reduce(sum, 10)) # Prints 16
# Same as above, but using a lambda function.
print([1, 2, 3].reduce(func(accum, number): return accum + number, 10))
[/codeblock]
If [method max] is not desirable, this method may also be used to implement a custom comparator:
[codeblock]
func _ready():
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 (3, 4)
func is_length_greater(a, b):
return a.length() &gt; b.length()
[/codeblock]
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">
<return type="void" />
<param index="0" name="position" type="int" />
<description>
Removes the element from the array at the given index ([param position]). If the index is out of bounds, this method fails. If the index is negative, [param position] is considered relative to the end of the array.
If you need to return the removed element, use [method pop_at]. To remove an element by value, use [method erase] instead.
[b]Note:[/b] This method shifts every element's index after [param position] back, which may have a noticeable performance cost, especially on larger arrays.
[b]Note:[/b] The [param position] cannot be negative. To remove an element relative to the end of the array, use [code]arr.remove_at(arr.size() - (i + 1))[/code]. To remove the last element from the array, use [code]arr.resize(arr.size() - 1)[/code].
</description>
</method>
<method name="resize">
<return type="int" />
<param index="0" name="size" type="int" />
<description>
Sets the array's number of elements to [param size]. If [param size] is smaller than the array's current size, the elements at the end are removed. If [param size] is greater, new default elements (usually [code]null[/code]) are added, depending on the array's type.
Returns [constant OK] on success, or one of the following [enum Error] constants if this method fails: [constant ERR_LOCKED] if the array is read-only, [constant ERR_INVALID_PARAMETER] if the size is negative, or [constant ERR_OUT_OF_MEMORY] if allocations fail. Use [method size] to find the actual size of the array after resize.
[b]Note:[/b] Calling this method once and assigning the new values is faster than calling [method append] for every new element.
</description>
</method>
<method name="reverse">
<return type="void" />
<description>
Reverses the order of all elements in the array.
</description>
</method>
<method name="rfind" qualifiers="const">
<return type="int" />
<param index="0" name="what" type="Variant" />
<param index="1" name="from" type="int" default="-1" />
<description>
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>
Shuffles all elements of the array in a random order.
[b]Note:[/b] Like many similar functions in the engine (such as [method @GlobalScope.randi] or [method pick_random]), this method uses a common, global random seed. To get a predictable outcome from this method, see [method @GlobalScope.seed].
</description>
</method>
<method name="size" qualifiers="const">
<return type="int" />
<description>
Returns the number of elements in the array. Empty arrays ([code][][/code]) always return [code]0[/code]. See also [method is_empty].
</description>
</method>
<method name="slice" qualifiers="const">
<return type="Array" />
<param index="0" name="begin" type="int" />
<param index="1" name="end" type="int" default="2147483647" />
<param index="2" name="step" type="int" default="1" />
<param index="3" name="deep" type="bool" default="false" />
<description>
Returns a new [Array] containing this array's elements, from index [param begin] (inclusive) to [param end] (exclusive), every [param step] elements.
If either [param begin] or [param end] are negative, their value is relative to the end of the array.
If [param step] is negative, this method iterates through the array in reverse, returning a slice ordered backwards. For this to work, [param begin] must be greater than [param end].
If [param deep] is [code]true[/code], all nested [Array] and [Dictionary] elements in the slice are duplicated from the original, recursively. See also [method duplicate].
[codeblock]
var letters = ["A", "B", "C", "D", "E", "F"]
print(letters.slice(0, 2)) # Prints ["A", "B"]
print(letters.slice(2, -2)) # Prints ["C", "D"]
print(letters.slice(-2, 6)) # Prints ["E", "F"]
print(letters.slice(0, 6, 2)) # Prints ["A", "C", "E"]
print(letters.slice(4, 1, -1)) # Prints ["E", "D", "C"]
[/codeblock]
</description>
</method>
<method name="sort">
<return type="void" />
<description>
Sorts the array in ascending order. The final order is dependent on the "less than" ([code]&lt;[/code]) comparison between elements.
[codeblocks]
[gdscript]
var numbers = [10, 5, 2.5, 8]
numbers.sort()
print(numbers) # Prints [2.5, 5, 8, 10]
[/gdscript]
[csharp]
Godot.Collections.Array numbers = [10, 5, 2.5, 8];
numbers.Sort();
GD.Print(numbers); // Prints [2.5, 5, 8, 10]
[/csharp]
[/codeblocks]
[b]Note:[/b] The sorting algorithm used is not [url=https://en.wikipedia.org/wiki/Sorting_algorithm#Stability]stable[/url]. This means that equivalent elements (such as [code]2[/code] and [code]2.0[/code]) may have their order changed when calling [method sort].
</description>
</method>
<method name="sort_custom">
<return type="void" />
<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]before[/i] the second one, otherwise it should return [code]false[/code].
[codeblock]
func sort_ascending(a, b):
if a[1] &lt; b[1]:
return true
return false
func _ready():
var my_items = [["Tomato", 5], ["Apple", 9], ["Rice", 4]]
my_items.sort_custom(sort_ascending)
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[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:
[codeblock]
var files = ["newfile1", "newfile2", "newfile10", "newfile11"]
files.sort_custom(func(a, b): return a.naturalnocasecmp_to(b) &lt; 0)
print(files) # Prints ["newfile1", "newfile2", "newfile10", "newfile11"]
[/codeblock]
[b]Note:[/b] In C#, this method is not supported.
[b]Note:[/b] The sorting algorithm used is not [url=https://en.wikipedia.org/wiki/Sorting_algorithm#Stability]stable[/url]. This means that values considered equal may have their order changed when calling this method.
[b]Note:[/b] You should not randomize the return value of [param func], as the heapsort algorithm expects a consistent result. Randomizing the return value will result in unexpected behavior.
</description>
</method>
</methods>
<operators>
<operator name="operator !=">
<return type="bool" />
<param index="0" name="right" type="Array" />
<description>
Returns [code]true[/code] if the array's size or its elements are different than [param right]'s.
</description>
</operator>
<operator name="operator +">
<return type="Array" />
<param index="0" name="right" type="Array" />
<description>
Appends the [param right] array to the left operand, creating a new [Array]. This is also known as an array concatenation.
[codeblocks]
[gdscript]
var array1 = ["One", 2]
var array2 = [3, "Four"]
print(array1 + array2) # Prints ["One", 2, 3, "Four"]
[/gdscript]
[csharp]
// Note that concatenation is not possible with C#'s native Array type.
Godot.Collections.Array array1 = ["One", 2];
Godot.Collections.Array array2 = [3, "Four"];
GD.Print(array1 + array2); // Prints ["One", 2, 3, "Four"]
[/csharp]
[/codeblocks]
[b]Note:[/b] For existing arrays, [method append_array] is much more efficient than concatenation and assignment with the [code]+=[/code] operator.
</description>
</operator>
<operator name="operator &lt;">
<return type="bool" />
<param index="0" name="right" type="Array" />
<description>
Compares the elements of both arrays in order, starting from index [code]0[/code] and ending on the last index in common between both arrays. For each pair of elements, returns [code]true[/code] if this array's element is less than [param right]'s, [code]false[/code] if this element is greater. Otherwise, continues to the next pair.
If all searched elements are equal, returns [code]true[/code] if this array's size is less than [param right]'s, otherwise returns [code]false[/code].
</description>
</operator>
<operator name="operator &lt;=">
<return type="bool" />
<param index="0" name="right" type="Array" />
<description>
Compares the elements of both arrays in order, starting from index [code]0[/code] and ending on the last index in common between both arrays. For each pair of elements, returns [code]true[/code] if this array's element is less than [param right]'s, [code]false[/code] if this element is greater. Otherwise, continues to the next pair.
If all searched elements are equal, returns [code]true[/code] if this array's size is less or equal to [param right]'s, otherwise returns [code]false[/code].
</description>
</operator>
<operator name="operator ==">
<return type="bool" />
<param index="0" name="right" type="Array" />
<description>
Compares the left operand [Array] against the [param right] [Array]. Returns [code]true[/code] if the sizes and contents of the arrays are equal, [code]false[/code] otherwise.
</description>
</operator>
<operator name="operator &gt;">
<return type="bool" />
<param index="0" name="right" type="Array" />
<description>
Compares the elements of both arrays in order, starting from index [code]0[/code] and ending on the last index in common between both arrays. For each pair of elements, returns [code]true[/code] if this array's element is greater than [param right]'s, [code]false[/code] if this element is less. Otherwise, continues to the next pair.
If all searched elements are equal, returns [code]true[/code] if this array's size is greater than [param right]'s, otherwise returns [code]false[/code].
</description>
</operator>
<operator name="operator &gt;=">
<return type="bool" />
<param index="0" name="right" type="Array" />
<description>
Compares the elements of both arrays in order, starting from index [code]0[/code] and ending on the last index in common between both arrays. For each pair of elements, returns [code]true[/code] if this array's element is greater than [param right]'s, [code]false[/code] if this element is less. Otherwise, continues to the next pair.
If all searched elements are equal, returns [code]true[/code] if this array's size is greater or equal to [param right]'s, otherwise returns [code]false[/code].
</description>
</operator>
<operator name="operator []">
<return type="Variant" />
<param index="0" name="index" type="int" />
<description>
Returns the [Variant] element at the specified [param index]. Arrays start at index 0. If [param index] is greater or equal to [code]0[/code], the element is fetched starting from the beginning of the array. If [param index] is a negative value, the element is fetched starting from the end. Accessing an array out-of-bounds will cause a run-time error, pausing the project execution if run from the editor.
</description>
</operator>
</operators>
</class>

220
doc/classes/ArrayMesh.xml Normal file
View File

@@ -0,0 +1,220 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="ArrayMesh" inherits="Mesh" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
[Mesh] type that provides utility for constructing a surface from arrays.
</brief_description>
<description>
The [ArrayMesh] is used to construct a [Mesh] by specifying the attributes as arrays.
The most basic example is the creation of a single triangle:
[codeblocks]
[gdscript]
var vertices = PackedVector3Array()
vertices.push_back(Vector3(0, 1, 0))
vertices.push_back(Vector3(1, 0, 0))
vertices.push_back(Vector3(0, 0, 1))
# Initialize the ArrayMesh.
var arr_mesh = ArrayMesh.new()
var arrays = []
arrays.resize(Mesh.ARRAY_MAX)
arrays[Mesh.ARRAY_VERTEX] = vertices
# Create the Mesh.
arr_mesh.add_surface_from_arrays(Mesh.PRIMITIVE_TRIANGLES, arrays)
var m = MeshInstance3D.new()
m.mesh = arr_mesh
[/gdscript]
[csharp]
Vector3[] vertices =
[
new Vector3(0, 1, 0),
new Vector3(1, 0, 0),
new Vector3(0, 0, 1),
];
// Initialize the ArrayMesh.
var arrMesh = new ArrayMesh();
Godot.Collections.Array arrays = [];
arrays.Resize((int)Mesh.ArrayType.Max);
arrays[(int)Mesh.ArrayType.Vertex] = vertices;
// Create the Mesh.
arrMesh.AddSurfaceFromArrays(Mesh.PrimitiveType.Triangles, arrays);
var m = new MeshInstance3D();
m.Mesh = arrMesh;
[/csharp]
[/codeblocks]
The [MeshInstance3D] is ready to be added to the [SceneTree] to be shown.
See also [ImmediateMesh], [MeshDataTool] and [SurfaceTool] for procedural geometry generation.
[b]Note:[/b] Godot uses clockwise [url=https://learnopengl.com/Advanced-OpenGL/Face-culling]winding order[/url] for front faces of triangle primitive modes.
</description>
<tutorials>
<link title="Procedural geometry using the ArrayMesh">$DOCS_URL/tutorials/3d/procedural_geometry/arraymesh.html</link>
</tutorials>
<methods>
<method name="add_blend_shape">
<return type="void" />
<param index="0" name="name" type="StringName" />
<description>
Adds name for a blend shape that will be added with [method add_surface_from_arrays]. Must be called before surface is added.
</description>
</method>
<method name="add_surface_from_arrays">
<return type="void" />
<param index="0" name="primitive" type="int" enum="Mesh.PrimitiveType" />
<param index="1" name="arrays" type="Array" />
<param index="2" name="blend_shapes" type="Array[]" default="[]" />
<param index="3" name="lods" type="Dictionary" default="{}" />
<param index="4" name="flags" type="int" enum="Mesh.ArrayFormat" is_bitfield="true" default="0" />
<description>
Creates a new surface. [method Mesh.get_surface_count] will become the [code]surf_idx[/code] for this new surface.
Surfaces are created to be rendered using a [param primitive], which may be any of the values defined in [enum Mesh.PrimitiveType].
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].
[b]Note:[/b] When using indices, it is recommended to only use points, lines, or triangles.
</description>
</method>
<method name="clear_blend_shapes">
<return type="void" />
<description>
Removes all blend shapes from this [ArrayMesh].
</description>
</method>
<method name="clear_surfaces">
<return type="void" />
<description>
Removes all surfaces from this [ArrayMesh].
</description>
</method>
<method name="get_blend_shape_count" qualifiers="const">
<return type="int" />
<description>
Returns the number of blend shapes that the [ArrayMesh] holds.
</description>
</method>
<method name="get_blend_shape_name" qualifiers="const">
<return type="StringName" />
<param index="0" name="index" type="int" />
<description>
Returns the name of the blend shape at this index.
</description>
</method>
<method name="lightmap_unwrap">
<return type="int" enum="Error" />
<param index="0" name="transform" type="Transform3D" />
<param index="1" name="texel_size" type="float" />
<description>
Performs a UV unwrap on the [ArrayMesh] to prepare the mesh for lightmapping.
</description>
</method>
<method name="regen_normal_maps">
<return type="void" />
<description>
Regenerates tangents for each of the [ArrayMesh]'s surfaces.
</description>
</method>
<method name="set_blend_shape_name">
<return type="void" />
<param index="0" name="index" type="int" />
<param index="1" name="name" type="StringName" />
<description>
Sets the name of the blend shape at this index.
</description>
</method>
<method name="surface_find_by_name" qualifiers="const">
<return type="int" />
<param index="0" name="name" type="String" />
<description>
Returns the index of the first surface with this name held within this [ArrayMesh]. If none are found, -1 is returned.
</description>
</method>
<method name="surface_get_array_index_len" qualifiers="const">
<return type="int" />
<param index="0" name="surf_idx" type="int" />
<description>
Returns the length in indices of the index array in the requested surface (see [method add_surface_from_arrays]).
</description>
</method>
<method name="surface_get_array_len" qualifiers="const">
<return type="int" />
<param index="0" name="surf_idx" type="int" />
<description>
Returns the length in vertices of the vertex array in the requested surface (see [method add_surface_from_arrays]).
</description>
</method>
<method name="surface_get_format" qualifiers="const">
<return type="int" enum="Mesh.ArrayFormat" is_bitfield="true" />
<param index="0" name="surf_idx" type="int" />
<description>
Returns the format mask of the requested surface (see [method add_surface_from_arrays]).
</description>
</method>
<method name="surface_get_name" qualifiers="const">
<return type="String" />
<param index="0" name="surf_idx" type="int" />
<description>
Gets the name assigned to this surface.
</description>
</method>
<method name="surface_get_primitive_type" qualifiers="const">
<return type="int" enum="Mesh.PrimitiveType" />
<param index="0" name="surf_idx" type="int" />
<description>
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" />
<param index="1" name="name" type="String" />
<description>
Sets a name for a given surface.
</description>
</method>
<method name="surface_update_attribute_region">
<return type="void" />
<param index="0" name="surf_idx" type="int" />
<param index="1" name="offset" type="int" />
<param index="2" name="data" type="PackedByteArray" />
<description>
</description>
</method>
<method name="surface_update_skin_region">
<return type="void" />
<param index="0" name="surf_idx" type="int" />
<param index="1" name="offset" type="int" />
<param index="2" name="data" type="PackedByteArray" />
<description>
</description>
</method>
<method name="surface_update_vertex_region">
<return type="void" />
<param index="0" name="surf_idx" type="int" />
<param index="1" name="offset" type="int" />
<param index="2" name="data" type="PackedByteArray" />
<description>
</description>
</method>
</methods>
<members>
<member name="blend_shape_mode" type="int" setter="set_blend_shape_mode" getter="get_blend_shape_mode" enum="Mesh.BlendShapeMode" default="1">
The blend shape mode.
</member>
<member name="custom_aabb" type="AABB" setter="set_custom_aabb" getter="get_custom_aabb" default="AABB(0, 0, 0, 0, 0, 0)">
Overrides the [AABB] with one defined by user for use with frustum culling. Especially useful to avoid unexpected culling when using a shader to offset vertices.
</member>
<member name="shadow_mesh" type="ArrayMesh" setter="set_shadow_mesh" getter="get_shadow_mesh">
An optional mesh which can be used for rendering shadows and the depth prepass. Can be used to increase performance by supplying a mesh with fused vertices and only vertex position data (without normals, UVs, colors, etc.).
[b]Note:[/b] This mesh must have exactly the same vertex positions as the source mesh (including the source mesh's LODs, if present). If vertex positions differ, then the mesh will not draw correctly.
</member>
</members>
</class>

33
doc/classes/ArrayOccluder3D.xml Normal file
View File

@@ -0,0 +1,33 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="ArrayOccluder3D" inherits="Occluder3D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
3D polygon shape for use with occlusion culling in [OccluderInstance3D].
</brief_description>
<description>
[ArrayOccluder3D] stores an arbitrary 3D polygon shape that can be used by the engine's occlusion culling system. This is analogous to [ArrayMesh], but for occluders.
See [OccluderInstance3D]'s documentation for instructions on setting up occlusion culling.
</description>
<tutorials>
<link title="Occlusion culling">$DOCS_URL/tutorials/3d/occlusion_culling.html</link>
</tutorials>
<methods>
<method name="set_arrays">
<return type="void" />
<param index="0" name="vertices" type="PackedVector3Array" />
<param index="1" name="indices" type="PackedInt32Array" />
<description>
Sets [member indices] and [member vertices], while updating the final occluder only once after both values are set.
</description>
</method>
</methods>
<members>
<member name="indices" type="PackedInt32Array" setter="set_indices" getter="get_indices" default="PackedInt32Array()">
The occluder's index position. Indices determine which points from the [member vertices] array should be drawn, and in which order.
[b]Note:[/b] The occluder is always updated after setting this value. If creating occluders procedurally, consider using [method set_arrays] instead to avoid updating the occluder twice when it's created.
</member>
<member name="vertices" type="PackedVector3Array" setter="set_vertices" getter="get_vertices" default="PackedVector3Array()">
The occluder's vertex positions in local 3D coordinates.
[b]Note:[/b] The occluder is always updated after setting this value. If creating occluders procedurally, consider using [method set_arrays] instead to avoid updating the occluder twice when it's created.
</member>
</members>
</class>

50
doc/classes/AspectRatioContainer.xml Normal file
View File

@@ -0,0 +1,50 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AspectRatioContainer" inherits="Container" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
A container that preserves the proportions of its child controls.
</brief_description>
<description>
A container type that arranges its child controls in a way that preserves their proportions automatically when the container is resized. Useful when a container has a dynamic size and the child nodes must adjust their sizes accordingly without losing their aspect ratios.
</description>
<tutorials>
<link title="Using Containers">$DOCS_URL/tutorials/ui/gui_containers.html</link>
</tutorials>
<members>
<member name="alignment_horizontal" type="int" setter="set_alignment_horizontal" getter="get_alignment_horizontal" enum="AspectRatioContainer.AlignmentMode" default="1">
Specifies the horizontal relative position of child controls.
</member>
<member name="alignment_vertical" type="int" setter="set_alignment_vertical" getter="get_alignment_vertical" enum="AspectRatioContainer.AlignmentMode" default="1">
Specifies the vertical relative position of child controls.
</member>
<member name="ratio" type="float" setter="set_ratio" getter="get_ratio" default="1.0">
The aspect ratio to enforce on child controls. This is the width divided by the height. The ratio depends on the [member stretch_mode].
</member>
<member name="stretch_mode" type="int" setter="set_stretch_mode" getter="get_stretch_mode" enum="AspectRatioContainer.StretchMode" default="2">
The stretch mode used to align child controls.
</member>
</members>
<constants>
<constant name="STRETCH_WIDTH_CONTROLS_HEIGHT" value="0" enum="StretchMode">
The height of child controls is automatically adjusted based on the width of the container.
</constant>
<constant name="STRETCH_HEIGHT_CONTROLS_WIDTH" value="1" enum="StretchMode">
The width of child controls is automatically adjusted based on the height of the container.
</constant>
<constant name="STRETCH_FIT" value="2" enum="StretchMode">
The bounding rectangle of child controls is automatically adjusted to fit inside the container while keeping the aspect ratio.
</constant>
<constant name="STRETCH_COVER" value="3" enum="StretchMode">
The width and height of child controls is automatically adjusted to make their bounding rectangle cover the entire area of the container while keeping the aspect ratio.
When the bounding rectangle of child controls exceed the container's size and [member Control.clip_contents] is enabled, this allows to show only the container's area restricted by its own bounding rectangle.
</constant>
<constant name="ALIGNMENT_BEGIN" value="0" enum="AlignmentMode">
Aligns child controls with the beginning (left or top) of the container.
</constant>
<constant name="ALIGNMENT_CENTER" value="1" enum="AlignmentMode">
Aligns child controls with the center of the container.
</constant>
<constant name="ALIGNMENT_END" value="2" enum="AlignmentMode">
Aligns child controls with the end (right or bottom) of the container.
</constant>
</constants>
</class>

28
doc/classes/AtlasTexture.xml Normal file
View File

@@ -0,0 +1,28 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AtlasTexture" inherits="Texture2D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
A texture that crops out part of another Texture2D.
</brief_description>
<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 will not tile properly in nodes such as [TextureRect] or [Sprite2D]. To tile an [AtlasTexture], modify its [member region] instead.
</description>
<tutorials>
</tutorials>
<members>
<member name="atlas" type="Texture2D" setter="set_atlas" getter="get_atlas">
The texture that contains the atlas. Can be any type inheriting from [Texture2D], including another [AtlasTexture].
</member>
<member name="filter_clip" type="bool" setter="set_filter_clip" getter="has_filter_clip" default="false">
If [code]true[/code], the area outside of the [member region] is clipped to avoid bleeding of the surrounding texture pixels.
</member>
<member name="margin" type="Rect2" setter="set_margin" getter="get_margin" default="Rect2(0, 0, 0, 0)">
The margin around the [member region]. Useful for small adjustments. If the [member Rect2.size] of this property ("w" and "h" in the editor) is set, the drawn texture is resized to fit within the margin.
</member>
<member name="region" type="Rect2" setter="set_region" getter="get_region" default="Rect2(0, 0, 0, 0)">
The region used to draw the [member atlas]. If either dimension of the region's size is [code]0[/code], the value from [member atlas] size will be used for that axis instead.
</member>
<member name="resource_local_to_scene" type="bool" setter="set_local_to_scene" getter="is_local_to_scene" overrides="Resource" default="false" />
</members>
</class>

11
doc/classes/AudioBusLayout.xml Normal file
View File

@@ -0,0 +1,11 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioBusLayout" inherits="Resource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Stores information about the audio buses.
</brief_description>
<description>
Stores position, muting, solo, bypass, effects, effect position, volume, and the connections between buses. See [AudioServer] for usage.
</description>
<tutorials>
</tutorials>
</class>

34
doc/classes/AudioEffect.xml Normal file
View File

@@ -0,0 +1,34 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffect" inherits="Resource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Base class for audio effect resources.
</brief_description>
<description>
The base [Resource] for every audio effect. In the editor, an audio effect can be added to the current bus layout through the Audio panel. At run-time, it is also possible to manipulate audio effects through [method AudioServer.add_bus_effect], [method AudioServer.remove_bus_effect], and [method AudioServer.get_bus_effect].
When applied on a bus, an audio effect creates a corresponding [AudioEffectInstance]. The instance is directly responsible for manipulating the sound, based on the original audio effect's properties.
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
<link title="Audio Microphone Record Demo">https://godotengine.org/asset-library/asset/2760</link>
</tutorials>
<methods>
<method name="_instantiate" qualifiers="virtual required">
<return type="AudioEffectInstance" />
<description>
Override this method to customize the [AudioEffectInstance] created when this effect is applied on a bus in the editor's Audio panel, or through [method AudioServer.add_bus_effect].
[codeblock]
extends AudioEffect
@export var strength = 4.0
func _instantiate():
var effect = CustomAudioEffectInstance.new()
effect.base = self
return effect
[/codeblock]
[b]Note:[/b] It is recommended to keep a reference to the original [AudioEffect] in the new instance. Depending on the implementation this allows the effect instance to listen for changes at run-time and be modified accordingly.
</description>
</method>
</methods>
</class>

21
doc/classes/AudioEffectAmplify.xml Normal file
View File

@@ -0,0 +1,21 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectAmplify" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Adds an amplifying audio effect to an audio bus.
</brief_description>
<description>
Increases or decreases the volume being routed through the audio bus.
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
</tutorials>
<members>
<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>

12
doc/classes/AudioEffectBandLimitFilter.xml Normal file
View File

@@ -0,0 +1,12 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectBandLimitFilter" inherits="AudioEffectFilter" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Adds a band limit filter to the audio bus.
</brief_description>
<description>
Limits the frequencies in a range around the [member AudioEffectFilter.cutoff_hz] and allows frequencies outside of this range to pass.
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
</tutorials>
</class>

12
doc/classes/AudioEffectBandPassFilter.xml Normal file
View File

@@ -0,0 +1,12 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectBandPassFilter" inherits="AudioEffectFilter" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Adds a band pass filter to the audio bus.
</brief_description>
<description>
Attenuates the frequencies inside of a range around the [member AudioEffectFilter.cutoff_hz] and cuts frequencies outside of this band.
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
</tutorials>
</class>

68
doc/classes/AudioEffectCapture.xml Normal file
View File

@@ -0,0 +1,68 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectCapture" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Captures audio from an audio bus in real-time.
</brief_description>
<description>
AudioEffectCapture is an AudioEffect which copies all audio frames from the attached audio effect bus into its internal ring buffer.
Application code should consume these audio frames from this ring buffer using [method get_buffer] and process it as needed, for example to capture data from an [AudioStreamMicrophone], implement application-defined effects, or to transmit audio over the network. When capturing audio data from a microphone, the format of the samples will be stereo 32-bit floating-point PCM.
Unlike [AudioEffectRecord], this effect only returns the raw audio samples instead of encoding them into an [AudioStream].
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
</tutorials>
<methods>
<method name="can_get_buffer" qualifiers="const">
<return type="bool" />
<param index="0" name="frames" type="int" />
<description>
Returns [code]true[/code] if at least [param frames] audio frames are available to read in the internal ring buffer.
</description>
</method>
<method name="clear_buffer">
<return type="void" />
<description>
Clears the internal ring buffer.
[b]Note:[/b] Calling this during a capture can cause the loss of samples which causes popping in the playback.
</description>
</method>
<method name="get_buffer">
<return type="PackedVector2Array" />
<param index="0" name="frames" type="int" />
<description>
Gets the next [param frames] audio samples from the internal ring buffer.
Returns a [PackedVector2Array] containing exactly [param frames] audio samples if available, or an empty [PackedVector2Array] if insufficient data was available.
The samples are signed floating-point PCM between [code]-1[/code] and [code]1[/code]. You will have to scale them if you want to use them as 8 or 16-bit integer samples. ([code]v = 0x7fff * samples[0].x[/code])
</description>
</method>
<method name="get_buffer_length_frames" qualifiers="const">
<return type="int" />
<description>
Returns the total size of the internal ring buffer in frames.
</description>
</method>
<method name="get_discarded_frames" qualifiers="const">
<return type="int" />
<description>
Returns the number of audio frames discarded from the audio bus due to full buffer.
</description>
</method>
<method name="get_frames_available" qualifiers="const">
<return type="int" />
<description>
Returns the number of frames available to read using [method get_buffer].
</description>
</method>
<method name="get_pushed_frames" qualifiers="const">
<return type="int" />
<description>
Returns the number of audio frames inserted from the audio bus.
</description>
</method>
</methods>
<members>
<member name="buffer_length" type="float" setter="set_buffer_length" getter="get_buffer_length" default="0.1">
Length of the internal ring buffer, in seconds. Setting the buffer length will have no effect if already initialized.
</member>
</members>
</class>

175
doc/classes/AudioEffectChorus.xml Normal file
View File

@@ -0,0 +1,175 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectChorus" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Adds a chorus audio effect.
</brief_description>
<description>
Adds a chorus audio effect. The effect applies a filter with voices to duplicate the audio source and manipulate it through the filter.
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
</tutorials>
<methods>
<method name="get_voice_cutoff_hz" qualifiers="const">
<return type="float" />
<param index="0" name="voice_idx" type="int" />
<description>
</description>
</method>
<method name="get_voice_delay_ms" qualifiers="const">
<return type="float" />
<param index="0" name="voice_idx" type="int" />
<description>
</description>
</method>
<method name="get_voice_depth_ms" qualifiers="const">
<return type="float" />
<param index="0" name="voice_idx" type="int" />
<description>
</description>
</method>
<method name="get_voice_level_db" qualifiers="const">
<return type="float" />
<param index="0" name="voice_idx" type="int" />
<description>
</description>
</method>
<method name="get_voice_pan" qualifiers="const">
<return type="float" />
<param index="0" name="voice_idx" type="int" />
<description>
</description>
</method>
<method name="get_voice_rate_hz" qualifiers="const">
<return type="float" />
<param index="0" name="voice_idx" type="int" />
<description>
</description>
</method>
<method name="set_voice_cutoff_hz">
<return type="void" />
<param index="0" name="voice_idx" type="int" />
<param index="1" name="cutoff_hz" type="float" />
<description>
</description>
</method>
<method name="set_voice_delay_ms">
<return type="void" />
<param index="0" name="voice_idx" type="int" />
<param index="1" name="delay_ms" type="float" />
<description>
</description>
</method>
<method name="set_voice_depth_ms">
<return type="void" />
<param index="0" name="voice_idx" type="int" />
<param index="1" name="depth_ms" type="float" />
<description>
</description>
</method>
<method name="set_voice_level_db">
<return type="void" />
<param index="0" name="voice_idx" type="int" />
<param index="1" name="level_db" type="float" />
<description>
</description>
</method>
<method name="set_voice_pan">
<return type="void" />
<param index="0" name="voice_idx" type="int" />
<param index="1" name="pan" type="float" />
<description>
</description>
</method>
<method name="set_voice_rate_hz">
<return type="void" />
<param index="0" name="voice_idx" type="int" />
<param index="1" name="rate_hz" type="float" />
<description>
</description>
</method>
</methods>
<members>
<member name="dry" type="float" setter="set_dry" getter="get_dry" default="1.0">
The effect's raw signal.
</member>
<member name="voice/1/cutoff_hz" type="float" setter="set_voice_cutoff_hz" getter="get_voice_cutoff_hz" default="8000.0">
The voice's cutoff frequency.
</member>
<member name="voice/1/delay_ms" type="float" setter="set_voice_delay_ms" getter="get_voice_delay_ms" default="15.0">
The voice's signal delay.
</member>
<member name="voice/1/depth_ms" type="float" setter="set_voice_depth_ms" getter="get_voice_depth_ms" default="2.0">
The voice filter's depth.
</member>
<member name="voice/1/level_db" type="float" setter="set_voice_level_db" getter="get_voice_level_db" default="0.0">
The voice's volume.
</member>
<member name="voice/1/pan" type="float" setter="set_voice_pan" getter="get_voice_pan" default="-0.5">
The voice's pan level.
</member>
<member name="voice/1/rate_hz" type="float" setter="set_voice_rate_hz" getter="get_voice_rate_hz" default="0.8">
The voice's filter rate.
</member>
<member name="voice/2/cutoff_hz" type="float" setter="set_voice_cutoff_hz" getter="get_voice_cutoff_hz" default="8000.0">
The voice's cutoff frequency.
</member>
<member name="voice/2/delay_ms" type="float" setter="set_voice_delay_ms" getter="get_voice_delay_ms" default="20.0">
The voice's signal delay.
</member>
<member name="voice/2/depth_ms" type="float" setter="set_voice_depth_ms" getter="get_voice_depth_ms" default="3.0">
The voice filter's depth.
</member>
<member name="voice/2/level_db" type="float" setter="set_voice_level_db" getter="get_voice_level_db" default="0.0">
The voice's volume.
</member>
<member name="voice/2/pan" type="float" setter="set_voice_pan" getter="get_voice_pan" default="0.5">
The voice's pan level.
</member>
<member name="voice/2/rate_hz" type="float" setter="set_voice_rate_hz" getter="get_voice_rate_hz" default="1.2">
The voice's filter rate.
</member>
<member name="voice/3/cutoff_hz" type="float" setter="set_voice_cutoff_hz" getter="get_voice_cutoff_hz">
The voice's cutoff frequency.
</member>
<member name="voice/3/delay_ms" type="float" setter="set_voice_delay_ms" getter="get_voice_delay_ms">
The voice's signal delay.
</member>
<member name="voice/3/depth_ms" type="float" setter="set_voice_depth_ms" getter="get_voice_depth_ms">
The voice filter's depth.
</member>
<member name="voice/3/level_db" type="float" setter="set_voice_level_db" getter="get_voice_level_db">
The voice's volume.
</member>
<member name="voice/3/pan" type="float" setter="set_voice_pan" getter="get_voice_pan">
The voice's pan level.
</member>
<member name="voice/3/rate_hz" type="float" setter="set_voice_rate_hz" getter="get_voice_rate_hz">
The voice's filter rate.
</member>
<member name="voice/4/cutoff_hz" type="float" setter="set_voice_cutoff_hz" getter="get_voice_cutoff_hz">
The voice's cutoff frequency.
</member>
<member name="voice/4/delay_ms" type="float" setter="set_voice_delay_ms" getter="get_voice_delay_ms">
The voice's signal delay.
</member>
<member name="voice/4/depth_ms" type="float" setter="set_voice_depth_ms" getter="get_voice_depth_ms">
The voice filter's depth.
</member>
<member name="voice/4/level_db" type="float" setter="set_voice_level_db" getter="get_voice_level_db">
The voice's volume.
</member>
<member name="voice/4/pan" type="float" setter="set_voice_pan" getter="get_voice_pan">
The voice's pan level.
</member>
<member name="voice/4/rate_hz" type="float" setter="set_voice_rate_hz" getter="get_voice_rate_hz">
The voice's filter rate.
</member>
<member name="voice_count" type="int" setter="set_voice_count" getter="get_voice_count" default="2">
The number of voices in the effect.
</member>
<member name="wet" type="float" setter="set_wet" getter="get_wet" default="0.5">
The effect's processed signal.
</member>
</members>
</class>

41
doc/classes/AudioEffectCompressor.xml Normal file
View File

@@ -0,0 +1,41 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectCompressor" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Adds a compressor audio effect to an audio bus.
Reduces sounds that exceed a certain threshold level, smooths out the dynamics and increases the overall volume.
</brief_description>
<description>
Dynamic range compressor reduces the level of the sound when the amplitude goes over a certain threshold in Decibels. One of the main uses of a compressor is to increase the dynamic range by clipping as little as possible (when sound goes over 0dB).
Compressor has many uses in the mix:
- In the Master bus to compress the whole output (although an [AudioEffectHardLimiter] is probably better).
- In voice channels to ensure they sound as balanced as possible.
- Sidechained. This can reduce the sound level sidechained with another audio bus for threshold detection. This technique is common in video game mixing to the level of music and SFX while voices are being heard.
- Accentuates transients by using a wider attack, making effects sound more punchy.
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
</tutorials>
<members>
<member name="attack_us" type="float" setter="set_attack_us" getter="get_attack_us" default="20.0">
Compressor's reaction time when the signal exceeds the threshold, in microseconds. Value can range from 20 to 2000.
</member>
<member name="gain" type="float" setter="set_gain" getter="get_gain" default="0.0">
Gain applied to the output signal.
</member>
<member name="mix" type="float" setter="set_mix" getter="get_mix" default="1.0">
Balance between original signal and effect signal. Value can range from 0 (totally dry) to 1 (totally wet).
</member>
<member name="ratio" type="float" setter="set_ratio" getter="get_ratio" default="4.0">
Amount of compression applied to the audio once it passes the threshold level. The higher the ratio, the more the loud parts of the audio will be compressed. Value can range from 1 to 48.
</member>
<member name="release_ms" type="float" setter="set_release_ms" getter="get_release_ms" default="250.0">
Compressor's delay time to stop reducing the signal after the signal level falls below the threshold, in milliseconds. Value can range from 20 to 2000.
</member>
<member name="sidechain" type="StringName" setter="set_sidechain" getter="get_sidechain" default="&amp;&quot;&quot;">
Reduce the sound level using another audio bus for threshold detection.
</member>
<member name="threshold" type="float" setter="set_threshold" getter="get_threshold" default="0.0">
The level above which compression is applied to the audio. Value can range from -60 to 0.
</member>
</members>
</class>

54
doc/classes/AudioEffectDelay.xml Normal file
View File

@@ -0,0 +1,54 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectDelay" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Adds a delay audio effect to an audio bus. Plays input signal back after a period of time.
Two tap delay and feedback options.
</brief_description>
<description>
Plays input signal back after a period of time. The delayed signal may be played back multiple times to create the sound of a repeating, decaying echo. Delay effects range from a subtle echo effect to a pronounced blending of previous sounds with new sounds.
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
</tutorials>
<members>
<member name="dry" type="float" setter="set_dry" getter="get_dry" default="1.0">
Output percent of original sound. At 0, only delayed sounds are output. Value can range from 0 to 1.
</member>
<member name="feedback_active" type="bool" setter="set_feedback_active" getter="is_feedback_active" default="false">
If [code]true[/code], feedback is enabled.
</member>
<member name="feedback_delay_ms" type="float" setter="set_feedback_delay_ms" getter="get_feedback_delay_ms" default="340.0">
Feedback delay time in milliseconds.
</member>
<member name="feedback_level_db" type="float" setter="set_feedback_level_db" getter="get_feedback_level_db" default="-6.0">
Sound level for feedback.
</member>
<member name="feedback_lowpass" type="float" setter="set_feedback_lowpass" getter="get_feedback_lowpass" default="16000.0">
Low-pass filter for feedback, in Hz. Frequencies below this value are filtered out of the source signal.
</member>
<member name="tap1_active" type="bool" setter="set_tap1_active" getter="is_tap1_active" default="true">
If [code]true[/code], the first tap will be enabled.
</member>
<member name="tap1_delay_ms" type="float" setter="set_tap1_delay_ms" getter="get_tap1_delay_ms" default="250.0">
First tap delay time in milliseconds.
</member>
<member name="tap1_level_db" type="float" setter="set_tap1_level_db" getter="get_tap1_level_db" default="-6.0">
Sound level for the first tap.
</member>
<member name="tap1_pan" type="float" setter="set_tap1_pan" getter="get_tap1_pan" default="0.2">
Pan position for the first tap. Value can range from -1 (fully left) to 1 (fully right).
</member>
<member name="tap2_active" type="bool" setter="set_tap2_active" getter="is_tap2_active" default="true">
If [code]true[/code], the second tap will be enabled.
</member>
<member name="tap2_delay_ms" type="float" setter="set_tap2_delay_ms" getter="get_tap2_delay_ms" default="500.0">
Second tap delay time in milliseconds.
</member>
<member name="tap2_level_db" type="float" setter="set_tap2_level_db" getter="get_tap2_level_db" default="-12.0">
Sound level for the second tap.
</member>
<member name="tap2_pan" type="float" setter="set_tap2_pan" getter="get_tap2_pan" default="-0.4">
Pan position for the second tap. Value can range from -1 (fully left) to 1 (fully right).
</member>
</members>
</class>

47
doc/classes/AudioEffectDistortion.xml Normal file
View File

@@ -0,0 +1,47 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectDistortion" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Adds a distortion audio effect to an Audio bus.
Modifies the sound to make it distorted.
</brief_description>
<description>
Different types are available: clip, tan, lo-fi (bit crushing), overdrive, or waveshape.
By distorting the waveform the frequency content changes, which will often make the sound "crunchy" or "abrasive". For games, it can simulate sound coming from some saturated device or speaker very efficiently.
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
</tutorials>
<members>
<member name="drive" type="float" setter="set_drive" getter="get_drive" default="0.0">
Distortion power. Value can range from 0 to 1.
</member>
<member name="keep_hf_hz" type="float" setter="set_keep_hf_hz" getter="get_keep_hf_hz" default="16000.0">
High-pass filter, in Hz. Frequencies higher than this value will not be affected by the distortion. Value can range from 1 to 20000.
</member>
<member name="mode" type="int" setter="set_mode" getter="get_mode" enum="AudioEffectDistortion.Mode" default="0">
Distortion type.
</member>
<member name="post_gain" type="float" setter="set_post_gain" getter="get_post_gain" default="0.0">
Increases or decreases the volume after the effect, in decibels. Value can range from -80 to 24.
</member>
<member name="pre_gain" type="float" setter="set_pre_gain" getter="get_pre_gain" default="0.0">
Increases or decreases the volume before the effect, in decibels. Value can range from -60 to 60.
</member>
</members>
<constants>
<constant name="MODE_CLIP" value="0" enum="Mode">
Digital distortion effect which cuts off peaks at the top and bottom of the waveform.
</constant>
<constant name="MODE_ATAN" value="1" enum="Mode">
</constant>
<constant name="MODE_LOFI" value="2" enum="Mode">
Low-resolution digital distortion effect (bit depth reduction). You can use it to emulate the sound of early digital audio devices.
</constant>
<constant name="MODE_OVERDRIVE" value="3" enum="Mode">
Emulates the warm distortion produced by a field effect transistor, which is commonly used in solid-state musical instrument amplifiers. The [member drive] property has no effect in this mode.
</constant>
<constant name="MODE_WAVESHAPE" value="4" enum="Mode">
Waveshaper distortions are used mainly by electronic musicians to achieve an extra-abrasive sound.
</constant>
</constants>
</class>

36
doc/classes/AudioEffectEQ.xml Normal file
View File

@@ -0,0 +1,36 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectEQ" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Base class for audio equalizers. Gives you control over frequencies.
Use it to create a custom equalizer if [AudioEffectEQ6], [AudioEffectEQ10] or [AudioEffectEQ21] don't fit your needs.
</brief_description>
<description>
AudioEffectEQ gives you control over frequencies. Use it to compensate for existing deficiencies in audio. AudioEffectEQs are useful on the Master bus to completely master a mix and give it more character. They are also useful when a game is run on a mobile device, to adjust the mix to that kind of speakers (it can be added but disabled when headphones are plugged).
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
</tutorials>
<methods>
<method name="get_band_count" qualifiers="const">
<return type="int" />
<description>
Returns the number of bands of the equalizer.
</description>
</method>
<method name="get_band_gain_db" qualifiers="const">
<return type="float" />
<param index="0" name="band_idx" type="int" />
<description>
Returns the band's gain at the specified index, in dB.
</description>
</method>
<method name="set_band_gain_db">
<return type="void" />
<param index="0" name="band_idx" type="int" />
<param index="1" name="volume_db" type="float" />
<description>
Sets band's gain at the specified index, in dB.
</description>
</method>
</methods>
</class>

24
doc/classes/AudioEffectEQ10.xml Normal file
View File

@@ -0,0 +1,24 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectEQ10" inherits="AudioEffectEQ" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Adds a 10-band equalizer audio effect to an Audio bus. Gives you control over frequencies from 31 Hz to 16000 Hz.
Each frequency can be modulated between -60/+24 dB.
</brief_description>
<description>
Frequency bands:
Band 1: 31 Hz
Band 2: 62 Hz
Band 3: 125 Hz
Band 4: 250 Hz
Band 5: 500 Hz
Band 6: 1000 Hz
Band 7: 2000 Hz
Band 8: 4000 Hz
Band 9: 8000 Hz
Band 10: 16000 Hz
See also [AudioEffectEQ], [AudioEffectEQ6], [AudioEffectEQ21].
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
</tutorials>
</class>

35
doc/classes/AudioEffectEQ21.xml Normal file
View File

@@ -0,0 +1,35 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectEQ21" inherits="AudioEffectEQ" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Adds a 21-band equalizer audio effect to an Audio bus. Gives you control over frequencies from 22 Hz to 22000 Hz.
Each frequency can be modulated between -60/+24 dB.
</brief_description>
<description>
Frequency bands:
Band 1: 22 Hz
Band 2: 32 Hz
Band 3: 44 Hz
Band 4: 63 Hz
Band 5: 90 Hz
Band 6: 125 Hz
Band 7: 175 Hz
Band 8: 250 Hz
Band 9: 350 Hz
Band 10: 500 Hz
Band 11: 700 Hz
Band 12: 1000 Hz
Band 13: 1400 Hz
Band 14: 2000 Hz
Band 15: 2800 Hz
Band 16: 4000 Hz
Band 17: 5600 Hz
Band 18: 8000 Hz
Band 19: 11000 Hz
Band 20: 16000 Hz
Band 21: 22000 Hz
See also [AudioEffectEQ], [AudioEffectEQ6], [AudioEffectEQ10].
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
</tutorials>
</class>

20
doc/classes/AudioEffectEQ6.xml Normal file
View File

@@ -0,0 +1,20 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectEQ6" inherits="AudioEffectEQ" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Adds a 6-band equalizer audio effect to an audio bus. Gives you control over frequencies from 32 Hz to 10000 Hz.
Each frequency can be modulated between -60/+24 dB.
</brief_description>
<description>
Frequency bands:
Band 1: 32 Hz
Band 2: 100 Hz
Band 3: 320 Hz
Band 4: 1000 Hz
Band 5: 3200 Hz
Band 6: 10000 Hz
See also [AudioEffectEQ], [AudioEffectEQ10], [AudioEffectEQ21].
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
</tutorials>
</class>

40
doc/classes/AudioEffectFilter.xml Normal file
View File

@@ -0,0 +1,40 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectFilter" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Adds a filter to the audio bus.
</brief_description>
<description>
Allows frequencies other than the [member cutoff_hz] to pass.
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
</tutorials>
<members>
<member name="cutoff_hz" type="float" setter="set_cutoff" getter="get_cutoff" default="2000.0">
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.
</member>
<member name="resonance" type="float" setter="set_resonance" getter="get_resonance" default="0.5">
Amount of boost in the frequency range near the cutoff frequency.
</member>
</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>

24
doc/classes/AudioEffectHardLimiter.xml Normal file
View File

@@ -0,0 +1,24 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectHardLimiter" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Adds a hard limiter audio effect to an Audio bus.
</brief_description>
<description>
A limiter is an effect designed to disallow sound from going over a given dB threshold. Hard limiters predict volume peaks, and will smoothly apply gain reduction when a peak crosses the ceiling threshold to prevent clipping and distortion. It preserves the waveform and prevents it from crossing the ceiling threshold. Adding one in the Master bus is recommended as a safety measure to prevent sudden volume peaks from occurring, and to prevent distortion caused by clipping.
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
</tutorials>
<members>
<member name="ceiling_db" type="float" setter="set_ceiling_db" getter="get_ceiling_db" default="-0.3">
The waveform's maximum allowed value, in decibels. This value can range from [code]-24.0[/code] to [code]0.0[/code].
The default value of [code]-0.3[/code] prevents potential inter-sample peaks (ISP) from crossing over 0 dB, which can cause slight distortion on some older hardware.
</member>
<member name="pre_gain_db" type="float" setter="set_pre_gain_db" getter="get_pre_gain_db" default="0.0">
Gain to apply before limiting, in decibels.
</member>
<member name="release" type="float" setter="set_release" getter="get_release" default="0.1">
Time it takes in seconds for the gain reduction to fully release.
</member>
</members>
</class>

12
doc/classes/AudioEffectHighPassFilter.xml Normal file
View File

@@ -0,0 +1,12 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectHighPassFilter" inherits="AudioEffectFilter" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Adds a high-pass filter to the audio bus.
</brief_description>
<description>
Cuts frequencies lower than the [member AudioEffectFilter.cutoff_hz] and allows higher frequencies to pass.
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
</tutorials>
</class>

12
doc/classes/AudioEffectHighShelfFilter.xml Normal file
View File

@@ -0,0 +1,12 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectHighShelfFilter" inherits="AudioEffectFilter" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Adds a high-shelf filter to the audio bus.
</brief_description>
<description>
Reduces all frequencies above the [member AudioEffectFilter.cutoff_hz].
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
</tutorials>
</class>

31
doc/classes/AudioEffectInstance.xml Normal file
View File

@@ -0,0 +1,31 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectInstance" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Manipulates the audio it receives for a given effect.
</brief_description>
<description>
An audio effect instance manipulates the audio it receives for a given effect. This instance is automatically created by an [AudioEffect] when it is added to a bus, and should usually not be created directly. If necessary, it can be fetched at run-time with [method AudioServer.get_bus_effect_instance].
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
</tutorials>
<methods>
<method name="_process" qualifiers="virtual required">
<return type="void" />
<param index="0" name="src_buffer" type="const void*" />
<param index="1" name="dst_buffer" type="AudioFrame*" />
<param index="2" name="frame_count" type="int" />
<description>
Called by the [AudioServer] to process this effect. When [method _process_silence] is not overridden or it returns [code]false[/code], this method is called only when the bus is active.
[b]Note:[/b] It is not useful to override this method in GDScript or C#. Only GDExtension can take advantage of it.
</description>
</method>
<method name="_process_silence" qualifiers="virtual const">
<return type="bool" />
<description>
Override this method to customize the processing behavior of this effect instance.
Should return [code]true[/code] to force the [AudioServer] to always call [method _process], even if the bus has been muted or cannot otherwise be heard.
</description>
</method>
</methods>
</class>

26
doc/classes/AudioEffectLimiter.xml Normal file
View File

@@ -0,0 +1,26 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectLimiter" inherits="AudioEffect" deprecated="Use [AudioEffectHardLimiter] instead." xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Adds a soft-clip limiter audio effect to an Audio bus.
</brief_description>
<description>
A limiter is similar to a compressor, but it's less flexible and designed to disallow sound going over a given dB threshold. Adding one in the Master bus is always recommended to reduce the effects of clipping.
Soft clipping starts to reduce the peaks a little below the threshold level and progressively increases its effect as the input level increases such that the threshold is never exceeded.
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
</tutorials>
<members>
<member name="ceiling_db" type="float" setter="set_ceiling_db" getter="get_ceiling_db" default="-0.1">
The waveform's maximum allowed value, in decibels. Value can range from -20 to -0.1.
</member>
<member name="soft_clip_db" type="float" setter="set_soft_clip_db" getter="get_soft_clip_db" default="2.0">
Applies a gain to the limited waves, in decibels. Value can range from 0 to 6.
</member>
<member name="soft_clip_ratio" type="float" setter="set_soft_clip_ratio" getter="get_soft_clip_ratio" default="10.0">
</member>
<member name="threshold_db" type="float" setter="set_threshold_db" getter="get_threshold_db" default="0.0">
Threshold from which the limiter begins to be active, in decibels. Value can range from -30 to 0.
</member>
</members>
</class>

12
doc/classes/AudioEffectLowPassFilter.xml Normal file
View File

@@ -0,0 +1,12 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectLowPassFilter" inherits="AudioEffectFilter" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Adds a low-pass filter to the audio bus.
</brief_description>
<description>
Cuts frequencies higher than the [member AudioEffectFilter.cutoff_hz] and allows lower frequencies to pass.
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
</tutorials>
</class>

12
doc/classes/AudioEffectLowShelfFilter.xml Normal file
View File

@@ -0,0 +1,12 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectLowShelfFilter" inherits="AudioEffectFilter" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Adds a low-shelf filter to the audio bus.
</brief_description>
<description>
Reduces all frequencies below the [member AudioEffectFilter.cutoff_hz].
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
</tutorials>
</class>

12
doc/classes/AudioEffectNotchFilter.xml Normal file
View File

@@ -0,0 +1,12 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectNotchFilter" inherits="AudioEffectFilter" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Adds a notch filter to the Audio bus.
</brief_description>
<description>
Attenuates frequencies in a narrow band around the [member AudioEffectFilter.cutoff_hz] and cuts frequencies outside of this range.
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
</tutorials>
</class>

17
doc/classes/AudioEffectPanner.xml Normal file
View File

@@ -0,0 +1,17 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectPanner" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Adds a panner audio effect to an audio bus. Pans sound left or right.
</brief_description>
<description>
Determines how much of an audio signal is sent to the left and right buses.
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
</tutorials>
<members>
<member name="pan" type="float" setter="set_pan" getter="get_pan" default="0.0">
Pan position. Value can range from -1 (fully left) to 1 (fully right).
</member>
</members>
</class>

30
doc/classes/AudioEffectPhaser.xml Normal file
View File

@@ -0,0 +1,30 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectPhaser" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Adds a phaser audio effect to an audio bus.
Combines the original signal with a copy that is slightly out of phase with the original.
</brief_description>
<description>
Combines phase-shifted signals with the original signal. The movement of the phase-shifted signals is controlled using a low-frequency oscillator.
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
</tutorials>
<members>
<member name="depth" type="float" setter="set_depth" getter="get_depth" default="1.0">
Determines how high the filter frequencies sweep. Low value will primarily affect bass frequencies. High value can sweep high into the treble. Value can range from [code]0.1[/code] to [code]4.0[/code].
</member>
<member name="feedback" type="float" setter="set_feedback" getter="get_feedback" default="0.7">
Output percent of modified sound. Value can range from 0.1 to 0.9.
</member>
<member name="range_max_hz" type="float" setter="set_range_max_hz" getter="get_range_max_hz" default="1600.0">
Determines the maximum frequency affected by the LFO modulations, in Hz. Value can range from 10 to 10000.
</member>
<member name="range_min_hz" type="float" setter="set_range_min_hz" getter="get_range_min_hz" default="440.0">
Determines the minimum frequency affected by the LFO modulations, in Hz. Value can range from 10 to 10000.
</member>
<member name="rate_hz" type="float" setter="set_rate_hz" getter="get_rate_hz" default="0.5">
Adjusts the rate in Hz at which the effect sweeps up and down across the frequency range.
</member>
</members>
</class>

44
doc/classes/AudioEffectPitchShift.xml Normal file
View File

@@ -0,0 +1,44 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectPitchShift" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Adds a pitch-shifting audio effect to an audio bus.
Raises or lowers the pitch of original sound.
</brief_description>
<description>
Allows modulation of pitch independently of tempo. All frequencies can be increased/decreased with minimal effect on transients.
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
</tutorials>
<members>
<member name="fft_size" type="int" setter="set_fft_size" getter="get_fft_size" enum="AudioEffectPitchShift.FFTSize" default="3">
The size of the [url=https://en.wikipedia.org/wiki/Fast_Fourier_transform]Fast Fourier transform[/url] buffer. Higher values smooth out the effect over time, but have greater latency. The effects of this higher latency are especially noticeable on sounds that have sudden amplitude changes.
</member>
<member name="oversampling" type="int" setter="set_oversampling" getter="get_oversampling" default="4">
The oversampling factor to use. Higher values result in better quality, but are more demanding on the CPU and may cause audio cracking if the CPU can't keep up.
</member>
<member name="pitch_scale" type="float" setter="set_pitch_scale" getter="get_pitch_scale" default="1.0">
The pitch scale to use. [code]1.0[/code] is the default pitch and plays sounds unaffected. [member pitch_scale] can range from [code]0.0[/code] (infinitely low pitch, inaudible) to [code]16[/code] (16 times higher than the initial pitch).
</member>
</members>
<constants>
<constant name="FFT_SIZE_256" value="0" enum="FFTSize">
Use a buffer of 256 samples for the Fast Fourier transform. Lowest latency, but least stable over time.
</constant>
<constant name="FFT_SIZE_512" value="1" enum="FFTSize">
Use a buffer of 512 samples for the Fast Fourier transform. Low latency, but less stable over time.
</constant>
<constant name="FFT_SIZE_1024" value="2" enum="FFTSize">
Use a buffer of 1024 samples for the Fast Fourier transform. This is a compromise between latency and stability over time.
</constant>
<constant name="FFT_SIZE_2048" value="3" enum="FFTSize">
Use a buffer of 2048 samples for the Fast Fourier transform. High latency, but stable over time.
</constant>
<constant name="FFT_SIZE_4096" value="4" enum="FFTSize">
Use a buffer of 4096 samples for the Fast Fourier transform. Highest latency, but most stable over time.
</constant>
<constant name="FFT_SIZE_MAX" value="5" enum="FFTSize">
Represents the size of the [enum FFTSize] enum.
</constant>
</constants>
</class>

42
doc/classes/AudioEffectRecord.xml Normal file
View File

@@ -0,0 +1,42 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectRecord" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Audio effect used for recording the sound from an audio bus.
</brief_description>
<description>
Allows the user to record the sound from an audio bus into an [AudioStreamWAV]. When used on the "Master" audio bus, this includes all audio output by Godot.
Unlike [AudioEffectCapture], this effect encodes the recording with the given format (8-bit, 16-bit, or compressed) instead of giving access to the raw audio samples.
Can be used (with an [AudioStreamMicrophone]) to record from a microphone.
[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>
<tutorials>
<link title="Recording with microphone">$DOCS_URL/tutorials/audio/recording_with_microphone.html</link>
<link title="Audio Microphone Record Demo">https://godotengine.org/asset-library/asset/2760</link>
</tutorials>
<methods>
<method name="get_recording" qualifiers="const">
<return type="AudioStreamWAV" />
<description>
Returns the recorded sample.
</description>
</method>
<method name="is_recording_active" qualifiers="const">
<return type="bool" />
<description>
Returns whether the recording is active or not.
</description>
</method>
<method name="set_recording_active">
<return type="void" />
<param index="0" name="record" type="bool" />
<description>
If [code]true[/code], the sound will be recorded. Note that restarting the recording will remove the previously recorded sample.
</description>
</method>
</methods>
<members>
<member name="format" type="int" setter="set_format" getter="get_format" enum="AudioStreamWAV.Format" default="1">
Specifies the format in which the sample will be recorded.
</member>
</members>
</class>

39
doc/classes/AudioEffectReverb.xml Normal file
View File

@@ -0,0 +1,39 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectReverb" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Adds a reverberation audio effect to an Audio bus.
</brief_description>
<description>
Simulates the sound of acoustic environments such as rooms, concert halls, caverns, or an open spaces.
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
<link title="Third Person Shooter (TPS) Demo">https://godotengine.org/asset-library/asset/2710</link>
</tutorials>
<members>
<member name="damping" type="float" setter="set_damping" getter="get_damping" default="0.5">
Defines how reflective the imaginary room's walls are. Value can range from 0 to 1.
</member>
<member name="dry" type="float" setter="set_dry" getter="get_dry" default="1.0">
Output percent of original sound. At 0, only modified sound is outputted. Value can range from 0 to 1.
</member>
<member name="hipass" type="float" setter="set_hpf" getter="get_hpf" default="0.0">
High-pass filter passes signals with a frequency higher than a certain cutoff frequency and attenuates signals with frequencies lower than the cutoff frequency. Value can range from 0 to 1.
</member>
<member name="predelay_feedback" type="float" setter="set_predelay_feedback" getter="get_predelay_feedback" default="0.4">
Output percent of predelay. Value can range from 0 to 1.
</member>
<member name="predelay_msec" type="float" setter="set_predelay_msec" getter="get_predelay_msec" default="150.0">
Time between the original signal and the early reflections of the reverb signal, in milliseconds.
</member>
<member name="room_size" type="float" setter="set_room_size" getter="get_room_size" default="0.8">
Dimensions of simulated room. Bigger means more echoes. Value can range from 0 to 1.
</member>
<member name="spread" type="float" setter="set_spread" getter="get_spread" default="1.0">
Widens or narrows the stereo image of the reverb tail. 1 means fully widens. Value can range from 0 to 1.
</member>
<member name="wet" type="float" setter="set_wet" getter="get_wet" default="0.5">
Output percent of modified sound. At 0, only original sound is outputted. Value can range from 0 to 1.
</member>
</members>
</class>

44
doc/classes/AudioEffectSpectrumAnalyzer.xml Normal file
View File

@@ -0,0 +1,44 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectSpectrumAnalyzer" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Audio effect that can be used for real-time audio visualizations.
</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 obtained with [method AudioServer.get_bus_effect_instance].
See also [AudioStreamGenerator] for procedurally generating sounds.
</description>
<tutorials>
<link title="Audio Spectrum Visualizer Demo">https://godotengine.org/asset-library/asset/2762</link>
</tutorials>
<members>
<member name="buffer_length" type="float" setter="set_buffer_length" getter="get_buffer_length" default="2.0">
The length of the buffer to keep (in seconds). Higher values keep data around for longer, but require more memory.
</member>
<member name="fft_size" type="int" setter="set_fft_size" getter="get_fft_size" enum="AudioEffectSpectrumAnalyzer.FFTSize" default="2">
The size of the [url=https://en.wikipedia.org/wiki/Fast_Fourier_transform]Fast Fourier transform[/url] buffer. Higher values smooth out the spectrum analysis over time, but have greater latency. The effects of this higher latency are especially noticeable with sudden amplitude changes.
</member>
<member name="tap_back_pos" type="float" setter="set_tap_back_pos" getter="get_tap_back_pos" default="0.01">
</member>
</members>
<constants>
<constant name="FFT_SIZE_256" value="0" enum="FFTSize">
Use a buffer of 256 samples for the Fast Fourier transform. Lowest latency, but least stable over time.
</constant>
<constant name="FFT_SIZE_512" value="1" enum="FFTSize">
Use a buffer of 512 samples for the Fast Fourier transform. Low latency, but less stable over time.
</constant>
<constant name="FFT_SIZE_1024" value="2" enum="FFTSize">
Use a buffer of 1024 samples for the Fast Fourier transform. This is a compromise between latency and stability over time.
</constant>
<constant name="FFT_SIZE_2048" value="3" enum="FFTSize">
Use a buffer of 2048 samples for the Fast Fourier transform. High latency, but stable over time.
</constant>
<constant name="FFT_SIZE_4096" value="4" enum="FFTSize">
Use a buffer of 4096 samples for the Fast Fourier transform. Highest latency, but most stable over time.
</constant>
<constant name="FFT_SIZE_MAX" value="5" enum="FFTSize">
Represents the size of the [enum FFTSize] enum.
</constant>
</constants>
</class>

33
doc/classes/AudioEffectSpectrumAnalyzerInstance.xml Normal file
View File

@@ -0,0 +1,33 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectSpectrumAnalyzerInstance" inherits="AudioEffectInstance" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Queryable instance of an [AudioEffectSpectrumAnalyzer].
</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 obtained with [method AudioServer.get_bus_effect_instance].
</description>
<tutorials>
<link title="Audio Spectrum Visualizer Demo">https://godotengine.org/asset-library/asset/2762</link>
</tutorials>
<methods>
<method name="get_magnitude_for_frequency_range" qualifiers="const">
<return type="Vector2" />
<param index="0" name="from_hz" type="float" />
<param index="1" name="to_hz" type="float" />
<param index="2" name="mode" type="int" enum="AudioEffectSpectrumAnalyzerInstance.MagnitudeMode" default="1" />
<description>
Returns the magnitude of the frequencies from [param from_hz] to [param to_hz] in linear energy as a Vector2. The [code]x[/code] component of the return value represents the left stereo channel, and [code]y[/code] represents the right channel.
[param mode] determines how the frequency range will be processed.
</description>
</method>
</methods>
<constants>
<constant name="MAGNITUDE_AVERAGE" value="0" enum="MagnitudeMode">
Use the average value across the frequency range as magnitude.
</constant>
<constant name="MAGNITUDE_MAX" value="1" enum="MagnitudeMode">
Use the maximum value of the frequency range as magnitude.
</constant>
</constants>
</class>

23
doc/classes/AudioEffectStereoEnhance.xml Normal file
View File

@@ -0,0 +1,23 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioEffectStereoEnhance" inherits="AudioEffect" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
An audio effect that can be used to adjust the intensity of stereo panning.
</brief_description>
<description>
An audio effect that can be used to adjust the intensity of stereo panning.
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
</tutorials>
<members>
<member name="pan_pullout" type="float" setter="set_pan_pullout" getter="get_pan_pullout" default="1.0">
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>

33
doc/classes/AudioListener2D.xml Normal file
View File

@@ -0,0 +1,33 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioListener2D" inherits="Node2D" keywords="sound" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Overrides the location sounds are heard from.
</brief_description>
<description>
Once added to the scene tree and enabled using [method make_current], this node will override the location sounds are heard from. Only one [AudioListener2D] can be current. Using [method make_current] will disable the previous [AudioListener2D].
If there is no active [AudioListener2D] in the current [Viewport], center of the screen will be used as a hearing point for the audio. [AudioListener2D] needs to be inside [SceneTree] to function.
</description>
<tutorials>
</tutorials>
<methods>
<method name="clear_current">
<return type="void" />
<description>
Disables the [AudioListener2D]. If it's not set as current, this method will have no effect.
</description>
</method>
<method name="is_current" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if this [AudioListener2D] is currently active.
</description>
</method>
<method name="make_current">
<return type="void" />
<description>
Makes the [AudioListener2D] active, setting it as the hearing point for the sounds. If there is already another active [AudioListener2D], it will be disabled.
This method will have no effect if the [AudioListener2D] is not added to [SceneTree].
</description>
</method>
</methods>
</class>

55
doc/classes/AudioListener3D.xml Normal file
View File

@@ -0,0 +1,55 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioListener3D" inherits="Node3D" keywords="sound" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Overrides the location sounds are heard from.
</brief_description>
<description>
Once added to the scene tree and enabled using [method make_current], this node will override the location sounds are heard from. This can be used to listen from a location different from the [Camera3D].
</description>
<tutorials>
</tutorials>
<methods>
<method name="clear_current">
<return type="void" />
<description>
Disables the listener to use the current camera's listener instead.
</description>
</method>
<method name="get_listener_transform" qualifiers="const">
<return type="Transform3D" />
<description>
Returns the listener's global orthonormalized [Transform3D].
</description>
</method>
<method name="is_current" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if the listener was made current using [method make_current], [code]false[/code] otherwise.
[b]Note:[/b] There may be more than one AudioListener3D marked as "current" in the scene tree, but only the one that was made current last will be used.
</description>
</method>
<method name="make_current">
<return type="void" />
<description>
Enables the listener. This will override the current camera's listener.
</description>
</method>
</methods>
<members>
<member name="doppler_tracking" type="int" setter="set_doppler_tracking" getter="get_doppler_tracking" enum="AudioListener3D.DopplerTracking" default="0">
If not [constant DOPPLER_TRACKING_DISABLED], this listener will simulate the [url=https://en.wikipedia.org/wiki/Doppler_effect]Doppler effect[/url] for objects changed in particular [code]_process[/code] methods.
[b]Note:[/b] The Doppler effect will only be heard on [AudioStreamPlayer3D]s if [member AudioStreamPlayer3D.doppler_tracking] is not set to [constant AudioStreamPlayer3D.DOPPLER_TRACKING_DISABLED].
</member>
</members>
<constants>
<constant name="DOPPLER_TRACKING_DISABLED" value="0" enum="DopplerTracking">
Disables [url=https://en.wikipedia.org/wiki/Doppler_effect]Doppler effect[/url] simulation (default).
</constant>
<constant name="DOPPLER_TRACKING_IDLE_STEP" value="1" enum="DopplerTracking">
Simulate [url=https://en.wikipedia.org/wiki/Doppler_effect]Doppler effect[/url] by tracking positions of objects that are changed in [code]_process[/code]. Changes in the relative velocity of this listener compared to those objects affect how audio is perceived (changing the audio's [member AudioStreamPlayer3D.pitch_scale]).
</constant>
<constant name="DOPPLER_TRACKING_PHYSICS_STEP" value="2" enum="DopplerTracking">
Simulate [url=https://en.wikipedia.org/wiki/Doppler_effect]Doppler effect[/url] by tracking positions of objects that are changed in [code]_physics_process[/code]. Changes in the relative velocity of this listener compared to those objects affect how audio is perceived (changing the audio's [member AudioStreamPlayer3D.pitch_scale]).
</constant>
</constants>
</class>

11
doc/classes/AudioSample.xml Normal file
View File

@@ -0,0 +1,11 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioSample" inherits="RefCounted" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Base class for audio samples.
</brief_description>
<description>
Base class for audio samples.
</description>
<tutorials>
</tutorials>
</class>

11
doc/classes/AudioSamplePlayback.xml Normal file
View File

@@ -0,0 +1,11 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioSamplePlayback" inherits="RefCounted" experimental="" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Meta class for playing back audio samples.
</brief_description>
<description>
Meta class for playing back audio samples.
</description>
<tutorials>
</tutorials>
</class>

407
doc/classes/AudioServer.xml Normal file
View File

@@ -0,0 +1,407 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioServer" inherits="Object" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Server interface for low-level audio access.
</brief_description>
<description>
[AudioServer] is a low-level server interface for audio access. It is in charge of creating sample data (playable audio) as well as its playback via a voice interface.
</description>
<tutorials>
<link title="Audio buses">$DOCS_URL/tutorials/audio/audio_buses.html</link>
<link title="Audio Device Changer Demo">https://godotengine.org/asset-library/asset/2758</link>
<link title="Audio Microphone Record Demo">https://godotengine.org/asset-library/asset/2760</link>
<link title="Audio Spectrum Visualizer Demo">https://godotengine.org/asset-library/asset/2762</link>
</tutorials>
<methods>
<method name="add_bus">
<return type="void" />
<param index="0" name="at_position" type="int" default="-1" />
<description>
Adds a bus at [param at_position].
</description>
</method>
<method name="add_bus_effect">
<return type="void" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="effect" type="AudioEffect" />
<param index="2" name="at_position" type="int" default="-1" />
<description>
Adds an [AudioEffect] effect to the bus [param bus_idx] at [param at_position].
</description>
</method>
<method name="generate_bus_layout" qualifiers="const">
<return type="AudioBusLayout" />
<description>
Generates an [AudioBusLayout] using the available buses and effects.
</description>
</method>
<method name="get_bus_channels" qualifiers="const">
<return type="int" />
<param index="0" name="bus_idx" type="int" />
<description>
Returns the number of channels of the bus at index [param bus_idx].
</description>
</method>
<method name="get_bus_effect">
<return type="AudioEffect" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="effect_idx" type="int" />
<description>
Returns the [AudioEffect] at position [param effect_idx] in bus [param bus_idx].
</description>
</method>
<method name="get_bus_effect_count">
<return type="int" />
<param index="0" name="bus_idx" type="int" />
<description>
Returns the number of effects on the bus at [param bus_idx].
</description>
</method>
<method name="get_bus_effect_instance">
<return type="AudioEffectInstance" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="effect_idx" type="int" />
<param index="2" name="channel" type="int" default="0" />
<description>
Returns the [AudioEffectInstance] assigned to the given bus and effect indices (and optionally channel).
</description>
</method>
<method name="get_bus_index" qualifiers="const">
<return type="int" />
<param index="0" name="bus_name" type="StringName" />
<description>
Returns the index of the bus with the name [param bus_name]. Returns [code]-1[/code] if no bus with the specified name exist.
</description>
</method>
<method name="get_bus_name" qualifiers="const">
<return type="String" />
<param index="0" name="bus_idx" type="int" />
<description>
Returns the name of the bus with the index [param bus_idx].
</description>
</method>
<method name="get_bus_peak_volume_left_db" qualifiers="const">
<return type="float" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="channel" type="int" />
<description>
Returns the peak volume of the left speaker at bus index [param bus_idx] and channel index [param channel].
</description>
</method>
<method name="get_bus_peak_volume_right_db" qualifiers="const">
<return type="float" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="channel" type="int" />
<description>
Returns the peak volume of the right speaker at bus index [param bus_idx] and channel index [param channel].
</description>
</method>
<method name="get_bus_send" qualifiers="const">
<return type="StringName" />
<param index="0" name="bus_idx" type="int" />
<description>
Returns the name of the bus that the bus at index [param bus_idx] sends to.
</description>
</method>
<method name="get_bus_volume_db" 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] 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>
Returns the names of all audio input devices detected on the system.
[b]Note:[/b] [member ProjectSettings.audio/driver/enable_input] must be [code]true[/code] for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings.
</description>
</method>
<method name="get_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>
Returns the sample rate at the output of the [AudioServer].
</description>
</method>
<method name="get_output_device_list">
<return type="PackedStringArray" />
<description>
Returns the names of all audio output devices detected on the system.
</description>
</method>
<method name="get_output_latency" qualifiers="const">
<return type="float" />
<description>
Returns the audio driver's effective output latency. This is based on [member ProjectSettings.audio/driver/output_latency], but the exact returned value will differ depending on the operating system and audio driver.
[b]Note:[/b] This can be expensive; it is not recommended to call [method get_output_latency] every frame.
</description>
</method>
<method name="get_speaker_mode" qualifiers="const">
<return type="int" enum="AudioServer.SpeakerMode" />
<description>
Returns the speaker configuration.
</description>
</method>
<method name="get_time_since_last_mix" qualifiers="const">
<return type="float" />
<description>
Returns the relative time since the last mix occurred.
</description>
</method>
<method name="get_time_to_next_mix" qualifiers="const">
<return type="float" />
<description>
Returns the relative time until the next mix occurs.
</description>
</method>
<method name="is_bus_bypassing_effects" qualifiers="const">
<return type="bool" />
<param index="0" name="bus_idx" type="int" />
<description>
If [code]true[/code], the bus at index [param bus_idx] is bypassing effects.
</description>
</method>
<method name="is_bus_effect_enabled" qualifiers="const">
<return type="bool" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="effect_idx" type="int" />
<description>
If [code]true[/code], the effect at index [param effect_idx] on the bus at index [param bus_idx] is enabled.
</description>
</method>
<method name="is_bus_mute" qualifiers="const">
<return type="bool" />
<param index="0" name="bus_idx" type="int" />
<description>
If [code]true[/code], the bus at index [param bus_idx] is muted.
</description>
</method>
<method name="is_bus_solo" qualifiers="const">
<return type="bool" />
<param index="0" name="bus_idx" type="int" />
<description>
If [code]true[/code], the bus at index [param bus_idx] is in solo mode.
</description>
</method>
<method name="is_stream_registered_as_sample" experimental="">
<return type="bool" />
<param index="0" name="stream" type="AudioStream" />
<description>
If [code]true[/code], the stream is registered as a sample. The engine will not have to register it before playing the sample.
If [code]false[/code], the stream will have to be registered before playing it. To prevent lag spikes, register the stream as sample with [method register_stream_as_sample].
</description>
</method>
<method name="lock">
<return type="void" />
<description>
Locks the audio driver's main loop.
[b]Note:[/b] Remember to unlock it afterwards.
</description>
</method>
<method name="move_bus">
<return type="void" />
<param index="0" name="index" type="int" />
<param index="1" name="to_index" type="int" />
<description>
Moves the bus from index [param index] to index [param to_index].
</description>
</method>
<method name="register_stream_as_sample" experimental="">
<return type="void" />
<param index="0" name="stream" type="AudioStream" />
<description>
Forces the registration of a stream as a sample.
[b]Note:[/b] Lag spikes may occur when calling this method, especially on single-threaded builds. It is suggested to call this method while loading assets, where the lag spike could be masked, instead of registering the sample right before it needs to be played.
</description>
</method>
<method name="remove_bus">
<return type="void" />
<param index="0" name="index" type="int" />
<description>
Removes the bus at index [param index].
</description>
</method>
<method name="remove_bus_effect">
<return type="void" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="effect_idx" type="int" />
<description>
Removes the effect at index [param effect_idx] from the bus at index [param bus_idx].
</description>
</method>
<method name="set_bus_bypass_effects">
<return type="void" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="enable" type="bool" />
<description>
If [code]true[/code], the bus at index [param bus_idx] is bypassing effects.
</description>
</method>
<method name="set_bus_effect_enabled">
<return type="void" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="effect_idx" type="int" />
<param index="2" name="enabled" type="bool" />
<description>
If [code]true[/code], the effect at index [param effect_idx] on the bus at index [param bus_idx] is enabled.
</description>
</method>
<method name="set_bus_layout">
<return type="void" />
<param index="0" name="bus_layout" type="AudioBusLayout" />
<description>
Overwrites the currently used [AudioBusLayout].
</description>
</method>
<method name="set_bus_mute">
<return type="void" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="enable" type="bool" />
<description>
If [code]true[/code], the bus at index [param bus_idx] is muted.
</description>
</method>
<method name="set_bus_name">
<return type="void" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="name" type="String" />
<description>
Sets the name of the bus at index [param bus_idx] to [param name].
</description>
</method>
<method name="set_bus_send">
<return type="void" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="send" type="StringName" />
<description>
Connects the output of the bus at [param bus_idx] to the bus named [param send].
</description>
</method>
<method name="set_bus_solo">
<return type="void" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="enable" type="bool" />
<description>
If [code]true[/code], the bus at index [param bus_idx] is in solo mode.
</description>
</method>
<method name="set_bus_volume_db">
<return type="void" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="volume_db" type="float" />
<description>
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">
<return type="void" />
<param index="0" name="enable" type="bool" />
<description>
If set to [code]true[/code], all instances of [AudioStreamPlayback] will call [method AudioStreamPlayback._tag_used_streams] every mix step.
[b]Note:[/b] This is enabled by default in the editor, as it is used by editor plugins for the audio stream previews.
</description>
</method>
<method name="swap_bus_effects">
<return type="void" />
<param index="0" name="bus_idx" type="int" />
<param index="1" name="effect_idx" type="int" />
<param index="2" name="by_effect_idx" type="int" />
<description>
Swaps the position of two effects in bus [param bus_idx].
</description>
</method>
<method name="unlock">
<return type="void" />
<description>
Unlocks the audio driver's main loop. (After locking it, you should always unlock it.)
</description>
</method>
</methods>
<members>
<member name="bus_count" type="int" setter="set_bus_count" getter="get_bus_count" default="1">
Number of available audio buses.
</member>
<member name="input_device" type="String" setter="set_input_device" getter="get_input_device" default="&quot;Default&quot;">
Name of the current device for audio input (see [method get_input_device_list]). On systems with multiple audio inputs (such as analog, USB and HDMI audio), this can be used to select the audio input device. The value [code]"Default"[/code] will record audio on the system-wide default audio input. If an invalid device name is set, the value will be reverted back to [code]"Default"[/code].
[b]Note:[/b] [member ProjectSettings.audio/driver/enable_input] must be [code]true[/code] for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings.
</member>
<member name="output_device" type="String" setter="set_output_device" getter="get_output_device" default="&quot;Default&quot;">
Name of the current device for audio output (see [method get_output_device_list]). On systems with multiple audio outputs (such as analog, USB and HDMI audio), this can be used to select the audio output device. The value [code]"Default"[/code] will play audio on the system-wide default audio output. If an invalid device name is set, the value will be reverted back to [code]"Default"[/code].
</member>
<member name="playback_speed_scale" type="float" setter="set_playback_speed_scale" getter="get_playback_speed_scale" default="1.0">
Scales the rate at which audio is played (i.e. setting it to [code]0.5[/code] will make the audio be played at half its speed). See also [member Engine.time_scale] to affect the general simulation speed, which is independent from [member AudioServer.playback_speed_scale].
</member>
</members>
<signals>
<signal name="bus_layout_changed">
<description>
Emitted when an audio bus is added, deleted, or moved.
</description>
</signal>
<signal name="bus_renamed">
<param index="0" name="bus_index" type="int" />
<param index="1" name="old_name" type="StringName" />
<param index="2" name="new_name" type="StringName" />
<description>
Emitted when the audio bus at [param bus_index] is renamed from [param old_name] to [param new_name].
</description>
</signal>
</signals>
<constants>
<constant name="SPEAKER_MODE_STEREO" value="0" enum="SpeakerMode">
Two or fewer speakers were detected.
</constant>
<constant name="SPEAKER_SURROUND_31" value="1" enum="SpeakerMode">
A 3.1 channel surround setup was detected.
</constant>
<constant name="SPEAKER_SURROUND_51" value="2" enum="SpeakerMode">
A 5.1 channel surround setup was detected.
</constant>
<constant name="SPEAKER_SURROUND_71" value="3" enum="SpeakerMode">
A 7.1 channel surround setup was detected.
</constant>
<constant name="PLAYBACK_TYPE_DEFAULT" value="0" enum="PlaybackType" experimental="">
The playback will be considered of the type declared at [member ProjectSettings.audio/general/default_playback_type].
</constant>
<constant name="PLAYBACK_TYPE_STREAM" value="1" enum="PlaybackType" experimental="">
Force the playback to be considered as a stream.
</constant>
<constant name="PLAYBACK_TYPE_SAMPLE" value="2" enum="PlaybackType" experimental="">
Force the playback to be considered as a sample. This can provide lower latency and more stable playback (with less risk of audio crackling), at the cost of having less flexibility.
[b]Note:[/b] Only currently supported on the web platform.
[b]Note:[/b] [AudioEffect]s are not supported when playback is considered as a sample.
</constant>
<constant name="PLAYBACK_TYPE_MAX" value="3" enum="PlaybackType" experimental="">
Represents the size of the [enum PlaybackType] enum.
</constant>
</constants>
</class>

123
doc/classes/AudioStream.xml Normal file
View File

@@ -0,0 +1,123 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioStream" inherits="Resource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Base class for audio streams.
</brief_description>
<description>
Base class for audio streams. Audio streams are used for sound effects and music playback, and support WAV (via [AudioStreamWAV]) and Ogg (via [AudioStreamOggVorbis]) file formats.
</description>
<tutorials>
<link title="Audio streams">$DOCS_URL/tutorials/audio/audio_streams.html</link>
<link title="Audio Generator Demo">https://godotengine.org/asset-library/asset/2759</link>
<link title="Audio Microphone Record Demo">https://godotengine.org/asset-library/asset/2760</link>
<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>
Overridable method. Should return the total number of beats of this audio stream. Used by the engine to determine the position of every beat.
Ideally, the returned value should be based off the stream's sample rate ([member AudioStreamWAV.mix_rate], for example).
</description>
</method>
<method name="_get_bpm" qualifiers="virtual const">
<return type="float" />
<description>
Overridable method. Should return the tempo of this audio stream, in beats per minute (BPM). Used by the engine to determine the position of every beat.
Ideally, the returned value should be based off the stream's sample rate ([member AudioStreamWAV.mix_rate], for example).
</description>
</method>
<method name="_get_length" qualifiers="virtual const">
<return type="float" />
<description>
Override this method to customize the returned value of [method get_length]. Should return the length of this audio stream, in seconds.
</description>
</method>
<method name="_get_parameter_list" qualifiers="virtual const">
<return type="Dictionary[]" />
<description>
Return the controllable parameters of this stream. This array contains dictionaries with a property info description format (see [method Object.get_property_list]). Additionally, the default value for this parameter must be added tho each dictionary in "default_value" field.
</description>
</method>
<method name="_get_stream_name" qualifiers="virtual const">
<return type="String" />
<description>
Override this method to customize the name assigned to this audio stream. Unused by the engine.
</description>
</method>
<method name="_get_tags" qualifiers="virtual const">
<return type="Dictionary" />
<description>
Override this method to customize the tags for this audio stream. Should return a [Dictionary] of strings with the tag as the key and its content as the value.
Commonly used tags include [code]title[/code], [code]artist[/code], [code]album[/code], [code]tracknumber[/code], and [code]date[/code].
</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 return a new [AudioStreamPlayback] created when the stream is played (such as by an [AudioStreamPlayer]).
</description>
</method>
<method name="_is_monophonic" qualifiers="virtual const">
<return type="bool" />
<description>
Override this method to customize the returned value of [method is_monophonic]. Should return [code]true[/code] if this audio stream only supports one channel.
</description>
</method>
<method name="can_be_sampled" qualifiers="const" experimental="">
<return type="bool" />
<description>
Returns if the current [AudioStream] can be used as a sample. Only static streams can be sampled.
</description>
</method>
<method name="generate_sample" qualifiers="const" experimental="">
<return type="AudioSample" />
<description>
Generates an [AudioSample] based on the current stream.
</description>
</method>
<method name="get_length" qualifiers="const">
<return type="float" />
<description>
Returns the length of the audio stream in seconds. If this stream is an [AudioStreamRandomizer], returns the length of the last played stream. If this stream has an indefinite length (such as for [AudioStreamGenerator] and [AudioStreamMicrophone]), returns [code]0.0[/code].
</description>
</method>
<method name="instantiate_playback">
<return type="AudioStreamPlayback" />
<description>
Returns a newly created [AudioStreamPlayback] intended to play this audio stream. Useful for when you want to extend [method _instantiate_playback] but call [method instantiate_playback] from an internally held AudioStream subresource. An example of this can be found in the source code for [code]AudioStreamRandomPitch::instantiate_playback[/code].
</description>
</method>
<method name="is_meta_stream" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if the stream is a collection of other streams, [code]false[/code] otherwise.
</description>
</method>
<method name="is_monophonic" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if this audio stream only supports one channel ([i]monophony[/i]), or [code]false[/code] if the audio stream supports two or more channels ([i]polyphony[/i]).
</description>
</method>
</methods>
<signals>
<signal name="parameter_list_changed">
<description>
Signal to be emitted to notify when the parameter list changed.
</description>
</signal>
</signals>
</class>

97
doc/classes/AudioStreamGenerator.xml Normal file
View File

@@ -0,0 +1,97 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioStreamGenerator" inherits="AudioStream" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
An audio stream with utilities for procedural sound generation.
</brief_description>
<description>
[AudioStreamGenerator] is a type of audio stream that does not play back sounds on its own; instead, it expects a script to generate audio data for it. See also [AudioStreamGeneratorPlayback].
Here's a sample on how to use it to generate a sine wave:
[codeblocks]
[gdscript]
var playback # Will hold the AudioStreamGeneratorPlayback.
@onready var sample_hz = $AudioStreamPlayer.stream.mix_rate
var pulse_hz = 440.0 # The frequency of the sound wave.
var phase = 0.0
func _ready():
$AudioStreamPlayer.play()
playback = $AudioStreamPlayer.get_stream_playback()
fill_buffer()
func fill_buffer():
var increment = pulse_hz / sample_hz
var frames_available = playback.get_frames_available()
for i in range(frames_available):
playback.push_frame(Vector2.ONE * sin(phase * TAU))
phase = fmod(phase + increment, 1.0)
[/gdscript]
[csharp]
[Export] public AudioStreamPlayer Player { get; set; }
private AudioStreamGeneratorPlayback _playback; // Will hold the AudioStreamGeneratorPlayback.
private float _sampleHz;
private float _pulseHz = 440.0f; // The frequency of the sound wave.
private double phase = 0.0;
public override void _Ready()
{
if (Player.Stream is AudioStreamGenerator generator) // Type as a generator to access MixRate.
{
_sampleHz = generator.MixRate;
Player.Play();
_playback = (AudioStreamGeneratorPlayback)Player.GetStreamPlayback();
FillBuffer();
}
}
public void FillBuffer()
{
float increment = _pulseHz / _sampleHz;
int framesAvailable = _playback.GetFramesAvailable();
for (int i = 0; i &lt; framesAvailable; i++)
{
_playback.PushFrame(Vector2.One * (float)Mathf.Sin(phase * Mathf.Tau));
phase = Mathf.PosMod(phase + increment, 1.0);
}
}
[/csharp]
[/codeblocks]
In the example above, the "AudioStreamPlayer" node must use an [AudioStreamGenerator] as its stream. The [code]fill_buffer[/code] function provides audio data for approximating a sine wave.
See also [AudioEffectSpectrumAnalyzer] for performing real-time audio spectrum analysis.
[b]Note:[/b] Due to performance constraints, this class is best used from C# or from a compiled language via GDExtension. If you still want to use this class from GDScript, consider using a lower [member mix_rate] such as 11,025 Hz or 22,050 Hz.
</description>
<tutorials>
<link title="Audio Generator Demo">https://godotengine.org/asset-library/asset/2759</link>
</tutorials>
<members>
<member name="buffer_length" type="float" setter="set_buffer_length" getter="get_buffer_length" default="0.5">
The length of the buffer to generate (in seconds). Lower values result in less latency, but require the script to generate audio data faster, resulting in increased CPU usage and more risk for audio cracking if the CPU can't keep up.
</member>
<member name="mix_rate" type="float" setter="set_mix_rate" getter="get_mix_rate" default="44100.0">
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>

54
doc/classes/AudioStreamGeneratorPlayback.xml Normal file
View File

@@ -0,0 +1,54 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioStreamGeneratorPlayback" inherits="AudioStreamPlaybackResampled" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Plays back audio generated using [AudioStreamGenerator].
</brief_description>
<description>
This class is meant to be used with [AudioStreamGenerator] to play back the generated audio in real-time.
</description>
<tutorials>
<link title="Audio Generator Demo">https://godotengine.org/asset-library/asset/2759</link>
<link title="Godot 3.2 will get new audio features">https://godotengine.org/article/godot-32-will-get-new-audio-features</link>
</tutorials>
<methods>
<method name="can_push_buffer" qualifiers="const">
<return type="bool" />
<param index="0" name="amount" type="int" />
<description>
Returns [code]true[/code] if a buffer of the size [param amount] can be pushed to the audio sample data buffer without overflowing it, [code]false[/code] otherwise.
</description>
</method>
<method name="clear_buffer">
<return type="void" />
<description>
Clears the audio sample data buffer.
</description>
</method>
<method name="get_frames_available" qualifiers="const">
<return type="int" />
<description>
Returns the number of frames that can be pushed to the audio sample data buffer without overflowing it. If the result is [code]0[/code], the buffer is full.
</description>
</method>
<method name="get_skips" qualifiers="const">
<return type="int" />
<description>
Returns the number of times the playback skipped due to a buffer underrun in the audio sample data. This value is reset at the start of the playback.
</description>
</method>
<method name="push_buffer">
<return type="bool" />
<param index="0" name="frames" type="PackedVector2Array" />
<description>
Pushes several audio data frames to the buffer. This is usually more efficient than [method push_frame] in C# and compiled languages via GDExtension, but [method push_buffer] may be [i]less[/i] efficient in GDScript.
</description>
</method>
<method name="push_frame">
<return type="bool" />
<param index="0" name="frame" type="Vector2" />
<description>
Pushes a single audio data frame to the buffer. This is usually less efficient than [method push_buffer] in C# and compiled languages via GDExtension, but [method push_frame] may be [i]more[/i] efficient in GDScript.
</description>
</method>
</methods>
</class>

14
doc/classes/AudioStreamMicrophone.xml Normal file
View File

@@ -0,0 +1,14 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioStreamMicrophone" inherits="AudioStream" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Plays real-time audio input data.
</brief_description>
<description>
When used directly in an [AudioStreamPlayer] node, [AudioStreamMicrophone] plays back microphone input in real-time. This can be used in conjunction with [AudioEffectCapture] to process the data or save it.
[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>
<tutorials>
<link title="Recording with microphone">$DOCS_URL/tutorials/audio/recording_with_microphone.html</link>
<link title="Audio Mic Record Demo">https://github.com/godotengine/godot-demo-projects/tree/master/audio/mic_record</link>
</tutorials>
</class>

144
doc/classes/AudioStreamPlayback.xml Normal file
View File

@@ -0,0 +1,144 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioStreamPlayback" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Meta class for playing back audio.
</brief_description>
<description>
Can play, loop, pause a scroll through audio. See [AudioStream] and [AudioStreamOggVorbis] for usage.
</description>
<tutorials>
<link title="Audio Generator Demo">https://godotengine.org/asset-library/asset/2759</link>
</tutorials>
<methods>
<method name="_get_loop_count" qualifiers="virtual const">
<return type="int" />
<description>
Overridable method. Should return how many times this audio stream has looped. Most built-in playbacks always return [code]0[/code].
</description>
</method>
<method name="_get_parameter" qualifiers="virtual const">
<return type="Variant" />
<param index="0" name="name" type="StringName" />
<description>
Return the current value of a playback parameter by name (see [method AudioStream._get_parameter_list]).
</description>
</method>
<method name="_get_playback_position" qualifiers="virtual const">
<return type="float" />
<description>
Overridable method. Should return the current progress along the audio stream, in seconds.
</description>
</method>
<method name="_is_playing" qualifiers="virtual const">
<return type="bool" />
<description>
Overridable method. Should return [code]true[/code] if this playback is active and playing its audio stream.
</description>
</method>
<method name="_mix" qualifiers="virtual required">
<return type="int" />
<param index="0" name="buffer" type="AudioFrame*" />
<param index="1" name="rate_scale" type="float" />
<param index="2" name="frames" type="int" />
<description>
Override this method to customize how the audio stream is mixed. This method is called even if the playback is not active.
[b]Note:[/b] It is not useful to override this method in GDScript or C#. Only GDExtension can take advantage of it.
</description>
</method>
<method name="_seek" qualifiers="virtual">
<return type="void" />
<param index="0" name="position" type="float" />
<description>
Override this method to customize what happens when seeking this audio stream at the given [param position], such as by calling [method AudioStreamPlayer.seek].
</description>
</method>
<method name="_set_parameter" qualifiers="virtual">
<return type="void" />
<param index="0" name="name" type="StringName" />
<param index="1" name="value" type="Variant" />
<description>
Set the current value of a playback parameter by name (see [method AudioStream._get_parameter_list]).
</description>
</method>
<method name="_start" qualifiers="virtual">
<return type="void" />
<param index="0" name="from_pos" type="float" />
<description>
Override this method to customize what happens when the playback starts at the given position, such as by calling [method AudioStreamPlayer.play].
</description>
</method>
<method name="_stop" qualifiers="virtual">
<return type="void" />
<description>
Override this method to customize what happens when the playback is stopped, such as by calling [method AudioStreamPlayer.stop].
</description>
</method>
<method name="_tag_used_streams" qualifiers="virtual">
<return type="void" />
<description>
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" />
<description>
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>

63
doc/classes/AudioStreamPlaybackPolyphonic.xml Normal file
View File

@@ -0,0 +1,63 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioStreamPlaybackPolyphonic" inherits="AudioStreamPlayback" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Playback instance for [AudioStreamPolyphonic].
</brief_description>
<description>
Playback instance for [AudioStreamPolyphonic]. After setting the [code]stream[/code] property of [AudioStreamPlayer], [AudioStreamPlayer2D], or [AudioStreamPlayer3D], the playback instance can be obtained by calling [method AudioStreamPlayer.get_stream_playback], [method AudioStreamPlayer2D.get_stream_playback] or [method AudioStreamPlayer3D.get_stream_playback] methods.
</description>
<tutorials>
</tutorials>
<methods>
<method name="is_stream_playing" qualifiers="const">
<return type="bool" />
<param index="0" name="stream" type="int" />
<description>
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">
<return type="int" />
<param index="0" name="stream" type="AudioStream" />
<param index="1" name="from_offset" type="float" default="0" />
<param index="2" name="volume_db" type="float" default="0" />
<param index="3" name="pitch_scale" type="float" default="1.0" />
<param index="4" name="playback_type" type="int" enum="AudioServer.PlaybackType" default="0" />
<param index="5" name="bus" type="StringName" default="&amp;&quot;Master&quot;" />
<description>
Play an [AudioStream] at a given offset, volume, pitch scale, playback type, and bus. Playback starts immediately.
The return value is a unique integer ID that is associated to this playback stream and which can be used to control it.
This ID becomes invalid when the stream ends (if it does not loop), when the [AudioStreamPlaybackPolyphonic] is stopped, or when [method stop_stream] is called.
This function returns [constant INVALID_ID] if the amount of streams currently playing equals [member AudioStreamPolyphonic.polyphony]. If you need a higher amount of maximum polyphony, raise this value.
</description>
</method>
<method name="set_stream_pitch_scale">
<return type="void" />
<param index="0" name="stream" type="int" />
<param index="1" name="pitch_scale" type="float" />
<description>
Change the stream pitch scale. The [param stream] argument is an integer ID returned by [method play_stream].
</description>
</method>
<method name="set_stream_volume">
<return type="void" />
<param index="0" name="stream" type="int" />
<param index="1" name="volume_db" type="float" />
<description>
Change the stream volume (in db). The [param stream] argument is an integer ID returned by [method play_stream].
</description>
</method>
<method name="stop_stream">
<return type="void" />
<param index="0" name="stream" type="int" />
<description>
Stop a stream. The [param stream] argument is an integer ID returned by [method play_stream], which becomes invalid after calling this function.
</description>
</method>
</methods>
<constants>
<constant name="INVALID_ID" value="-1">
Returned by [method play_stream] in case it could not allocate a stream for playback.
</constant>
</constants>
</class>

28
doc/classes/AudioStreamPlaybackResampled.xml Normal file
View File

@@ -0,0 +1,28 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioStreamPlaybackResampled" inherits="AudioStreamPlayback" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
</brief_description>
<description>
</description>
<tutorials>
</tutorials>
<methods>
<method name="_get_stream_sampling_rate" qualifiers="virtual required const">
<return type="float" />
<description>
</description>
</method>
<method name="_mix_resampled" qualifiers="virtual required">
<return type="int" />
<param index="0" name="dst_buffer" type="AudioFrame*" />
<param index="1" name="frame_count" type="int" />
<description>
</description>
</method>
<method name="begin_resample">
<return type="void" />
<description>
</description>
</method>
</methods>
</class>

118
doc/classes/AudioStreamPlayer.xml Normal file
View File

@@ -0,0 +1,118 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioStreamPlayer" inherits="Node" keywords="sound, music, song" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
A node for audio playback.
</brief_description>
<description>
The [AudioStreamPlayer] node plays an audio stream non-positionally. It is ideal for user interfaces, menus, or background music.
To use this node, [member stream] needs to be set to a valid [AudioStream] resource. Playing more than one sound at the same time is also supported, see [member max_polyphony].
If you need to play audio at a specific position, use [AudioStreamPlayer2D] or [AudioStreamPlayer3D] instead.
</description>
<tutorials>
<link title="Audio streams">$DOCS_URL/tutorials/audio/audio_streams.html</link>
<link title="2D Dodge The Creeps Demo">https://godotengine.org/asset-library/asset/2712</link>
<link title="Audio Device Changer Demo">https://godotengine.org/asset-library/asset/2758</link>
<link title="Audio Generator Demo">https://godotengine.org/asset-library/asset/2759</link>
<link title="Audio Microphone Record Demo">https://godotengine.org/asset-library/asset/2760</link>
<link title="Audio Spectrum Visualizer Demo">https://godotengine.org/asset-library/asset/2762</link>
</tutorials>
<methods>
<method name="get_playback_position">
<return type="float" />
<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">
<return type="AudioStreamPlayback" />
<description>
Returns the latest [AudioStreamPlayback] of this node, usually the most recently created by [method play]. If no sounds are playing, this method fails and returns an empty playback.
</description>
</method>
<method name="has_stream_playback">
<return type="bool" />
<description>
Returns [code]true[/code] if any sound is active, even if [member stream_paused] is set to [code]true[/code]. See also [member playing] and [method get_stream_playback].
</description>
</method>
<method name="play">
<return type="void" />
<param index="0" name="from_position" type="float" default="0.0" />
<description>
Plays a sound from the beginning, or the given [param from_position] in seconds.
</description>
</method>
<method name="seek">
<return type="void" />
<param index="0" name="to_position" type="float" />
<description>
Restarts all sounds to be played from the given [param to_position], in seconds. Does nothing if no sounds are playing.
</description>
</method>
<method name="stop">
<return type="void" />
<description>
Stops all sounds from this node.
</description>
</method>
</methods>
<members>
<member name="autoplay" type="bool" setter="set_autoplay" getter="is_autoplay_enabled" default="false">
If [code]true[/code], this node calls [method play] when entering the tree.
</member>
<member name="bus" type="StringName" setter="set_bus" getter="get_bus" default="&amp;&quot;Master&quot;">
The target bus name. All sounds from this node will be playing on this bus.
[b]Note:[/b] At runtime, if no bus with the given name exists, all sounds will fall back on [code]"Master"[/code]. See also [method AudioServer.get_bus_name].
</member>
<member name="max_polyphony" type="int" setter="set_max_polyphony" getter="get_max_polyphony" default="1">
The maximum number of sounds this node can play at the same time. Calling [method play] after this value is reached will cut off the oldest sounds.
</member>
<member name="mix_target" type="int" setter="set_mix_target" getter="get_mix_target" enum="AudioStreamPlayer.MixTarget" default="0">
The mix target channels. Has no effect when two speakers or less are detected (see [enum AudioServer.SpeakerMode]).
</member>
<member name="pitch_scale" type="float" setter="set_pitch_scale" getter="get_pitch_scale" default="1.0">
The audio's pitch and tempo, as a multiplier of the [member stream]'s sample rate. A value of [code]2.0[/code] doubles the audio's pitch, while a value of [code]0.5[/code] halves the pitch.
</member>
<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">
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">
The [AudioStream] resource to be played. Setting this property stops all currently playing sounds. If left empty, the [AudioStreamPlayer] does not work.
</member>
<member name="stream_paused" type="bool" setter="set_stream_paused" getter="get_stream_paused" default="false">
If [code]true[/code], the sounds are paused. Setting [member stream_paused] to [code]false[/code] resumes all sounds.
[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 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>
<signal name="finished">
<description>
Emitted when a sound finishes playing without interruptions. This signal is [i]not[/i] emitted when calling [method stop], or when exiting the tree while sounds are playing.
</description>
</signal>
</signals>
<constants>
<constant name="MIX_TARGET_STEREO" value="0" enum="MixTarget">
The audio will be played only on the first channel. This is the default.
</constant>
<constant name="MIX_TARGET_SURROUND" value="1" enum="MixTarget">
The audio will be played on all surround channels.
</constant>
<constant name="MIX_TARGET_CENTER" value="2" enum="MixTarget">
The audio will be played on the second channel, which is usually the center.
</constant>
</constants>
</class>

108
doc/classes/AudioStreamPlayer2D.xml Normal file
View File

@@ -0,0 +1,108 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioStreamPlayer2D" inherits="Node2D" keywords="sound, sfx" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Plays positional sound in 2D space.
</brief_description>
<description>
Plays audio that is attenuated with distance to the listener.
By default, audio is heard from the screen center. This can be changed by adding an [AudioListener2D] node to the scene and enabling it by calling [method AudioListener2D.make_current] on it.
See also [AudioStreamPlayer] to play a sound non-positionally.
[b]Note:[/b] Hiding an [AudioStreamPlayer2D] node does not disable its audio output. To temporarily disable an [AudioStreamPlayer2D]'s audio output, set [member volume_db] to a very low value like [code]-100[/code] (which isn't audible to human hearing).
</description>
<tutorials>
<link title="Audio streams">$DOCS_URL/tutorials/audio/audio_streams.html</link>
</tutorials>
<methods>
<method name="get_playback_position">
<return type="float" />
<description>
Returns the position in the [AudioStream].
</description>
</method>
<method name="get_stream_playback">
<return type="AudioStreamPlayback" />
<description>
Returns the [AudioStreamPlayback] object associated with this [AudioStreamPlayer2D].
</description>
</method>
<method name="has_stream_playback">
<return type="bool" />
<description>
Returns whether the [AudioStreamPlayer] can return the [AudioStreamPlayback] object or not.
</description>
</method>
<method name="play">
<return type="void" />
<param index="0" name="from_position" type="float" default="0.0" />
<description>
Queues the audio to play on the next physics frame, from the given position [param from_position], in seconds.
</description>
</method>
<method name="seek">
<return type="void" />
<param index="0" name="to_position" type="float" />
<description>
Sets the position from which audio will be played, in seconds.
</description>
</method>
<method name="stop">
<return type="void" />
<description>
Stops the audio.
</description>
</method>
</methods>
<members>
<member name="area_mask" type="int" setter="set_area_mask" getter="get_area_mask" default="1">
Determines which [Area2D] layers affect the sound for reverb and audio bus effects. Areas can be used to redirect [AudioStream]s so that they play in a certain audio bus. An example of how you might use this is making a "water" area so that sounds played in the water are redirected through an audio bus to make them sound like they are being played underwater.
</member>
<member name="attenuation" type="float" setter="set_attenuation" getter="get_attenuation" default="1.0">
The volume is attenuated over distance with this as an exponent.
</member>
<member name="autoplay" type="bool" setter="set_autoplay" getter="is_autoplay_enabled" default="false">
If [code]true[/code], audio plays when added to scene tree.
</member>
<member name="bus" type="StringName" setter="set_bus" getter="get_bus" default="&amp;&quot;Master&quot;">
Bus on which this audio is playing.
[b]Note:[/b] When setting this property, keep in mind that no validation is performed to see if the given name matches an existing bus. This is because audio bus layouts might be loaded after this property is set. If this given name can't be resolved at runtime, it will fall back to [code]"Master"[/code].
</member>
<member name="max_distance" type="float" setter="set_max_distance" getter="get_max_distance" default="2000.0">
Maximum distance from which audio is still hearable.
</member>
<member name="max_polyphony" type="int" setter="set_max_polyphony" getter="get_max_polyphony" default="1">
The maximum number of sounds this node can play at the same time. Playing additional sounds after this value is reached will cut off the oldest sounds.
</member>
<member name="panning_strength" type="float" setter="set_panning_strength" getter="get_panning_strength" default="1.0">
Scales the panning strength for this node by multiplying the base [member ProjectSettings.audio/general/2d_panning_strength] with this factor. Higher values will pan audio from left to right more dramatically than lower values.
</member>
<member name="pitch_scale" type="float" setter="set_pitch_scale" getter="get_pitch_scale" default="1.0">
The pitch and the tempo of the audio, as a multiplier of the audio sample's sample rate.
</member>
<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">
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">
The [AudioStream] object to be played.
</member>
<member name="stream_paused" type="bool" setter="set_stream_paused" getter="get_stream_paused" default="false">
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, 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>
<signal name="finished">
<description>
Emitted when the audio stops playing.
</description>
</signal>
</signals>
</class>

158
doc/classes/AudioStreamPlayer3D.xml Normal file
View File

@@ -0,0 +1,158 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioStreamPlayer3D" inherits="Node3D" keywords="sound, sfx" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Plays positional sound in 3D space.
</brief_description>
<description>
Plays audio with positional sound effects, based on the relative position of the audio listener. Positional effects include distance attenuation, directionality, and the Doppler effect. For greater realism, a low-pass filter is applied to distant sounds. This can be disabled by setting [member attenuation_filter_cutoff_hz] to [code]20500[/code].
By default, audio is heard from the camera position. This can be changed by adding an [AudioListener3D] node to the scene and enabling it by calling [method AudioListener3D.make_current] on it.
See also [AudioStreamPlayer] to play a sound non-positionally.
[b]Note:[/b] Hiding an [AudioStreamPlayer3D] node does not disable its audio output. To temporarily disable an [AudioStreamPlayer3D]'s audio output, set [member volume_db] to a very low value like [code]-100[/code] (which isn't audible to human hearing).
</description>
<tutorials>
<link title="Audio streams">$DOCS_URL/tutorials/audio/audio_streams.html</link>
</tutorials>
<methods>
<method name="get_playback_position">
<return type="float" />
<description>
Returns the position in the [AudioStream].
</description>
</method>
<method name="get_stream_playback">
<return type="AudioStreamPlayback" />
<description>
Returns the [AudioStreamPlayback] object associated with this [AudioStreamPlayer3D].
</description>
</method>
<method name="has_stream_playback">
<return type="bool" />
<description>
Returns whether the [AudioStreamPlayer] can return the [AudioStreamPlayback] object or not.
</description>
</method>
<method name="play">
<return type="void" />
<param index="0" name="from_position" type="float" default="0.0" />
<description>
Queues the audio to play on the next physics frame, from the given position [param from_position], in seconds.
</description>
</method>
<method name="seek">
<return type="void" />
<param index="0" name="to_position" type="float" />
<description>
Sets the position from which audio will be played, in seconds.
</description>
</method>
<method name="stop">
<return type="void" />
<description>
Stops the audio.
</description>
</method>
</methods>
<members>
<member name="area_mask" type="int" setter="set_area_mask" getter="get_area_mask" default="1">
Determines which [Area3D] layers affect the sound for reverb and audio bus effects. Areas can be used to redirect [AudioStream]s so that they play in a certain audio bus. An example of how you might use this is making a "water" area so that sounds played in the water are redirected through an audio bus to make them sound like they are being played underwater.
</member>
<member name="attenuation_filter_cutoff_hz" type="float" setter="set_attenuation_filter_cutoff_hz" getter="get_attenuation_filter_cutoff_hz" default="5000.0">
The cutoff frequency of the attenuation low-pass filter, in Hz. A sound above this frequency is attenuated more than a sound below this frequency. To disable this effect, set this to [code]20500[/code] as this frequency is above the human hearing limit.
</member>
<member name="attenuation_filter_db" type="float" setter="set_attenuation_filter_db" getter="get_attenuation_filter_db" default="-24.0">
Amount how much the filter affects the loudness, in decibels.
</member>
<member name="attenuation_model" type="int" setter="set_attenuation_model" getter="get_attenuation_model" enum="AudioStreamPlayer3D.AttenuationModel" default="0">
Decides if audio should get quieter with distance linearly, quadratically, logarithmically, or not be affected by distance, effectively disabling attenuation.
</member>
<member name="autoplay" type="bool" setter="set_autoplay" getter="is_autoplay_enabled" default="false">
If [code]true[/code], audio plays when the AudioStreamPlayer3D node is added to scene tree.
</member>
<member name="bus" type="StringName" setter="set_bus" getter="get_bus" default="&amp;&quot;Master&quot;">
The bus on which this audio is playing.
[b]Note:[/b] When setting this property, keep in mind that no validation is performed to see if the given name matches an existing bus. This is because audio bus layouts might be loaded after this property is set. If this given name can't be resolved at runtime, it will fall back to [code]"Master"[/code].
</member>
<member name="doppler_tracking" type="int" setter="set_doppler_tracking" getter="get_doppler_tracking" enum="AudioStreamPlayer3D.DopplerTracking" default="0">
Decides in which step the Doppler effect should be calculated.
[b]Note:[/b] If [member doppler_tracking] is not [constant DOPPLER_TRACKING_DISABLED] but the current [Camera3D]/[AudioListener3D] has doppler tracking disabled, the Doppler effect will be heard but will not take the movement of the current listener into account. If accurate Doppler effect is desired, doppler tracking should be enabled on both the [AudioStreamPlayer3D] and the current [Camera3D]/[AudioListener3D].
</member>
<member name="emission_angle_degrees" type="float" setter="set_emission_angle" getter="get_emission_angle" default="45.0">
The angle in which the audio reaches a listener unattenuated.
</member>
<member name="emission_angle_enabled" type="bool" setter="set_emission_angle_enabled" getter="is_emission_angle_enabled" default="false">
If [code]true[/code], the audio should be attenuated according to the direction of the sound.
</member>
<member name="emission_angle_filter_attenuation_db" type="float" setter="set_emission_angle_filter_attenuation_db" getter="get_emission_angle_filter_attenuation_db" default="-12.0">
Attenuation factor used if listener is outside of [member emission_angle_degrees] and [member emission_angle_enabled] is set, in decibels.
</member>
<member name="max_db" type="float" setter="set_max_db" getter="get_max_db" default="3.0">
Sets the absolute maximum of the sound level, in decibels.
</member>
<member name="max_distance" type="float" setter="set_max_distance" getter="get_max_distance" default="0.0">
The distance past which the sound can no longer be heard at all. Only has an effect if set to a value greater than [code]0.0[/code]. [member max_distance] works in tandem with [member unit_size]. However, unlike [member unit_size] whose behavior depends on the [member attenuation_model], [member max_distance] always works in a linear fashion. This can be used to prevent the [AudioStreamPlayer3D] from requiring audio mixing when the listener is far away, which saves CPU resources.
</member>
<member name="max_polyphony" type="int" setter="set_max_polyphony" getter="get_max_polyphony" default="1">
The maximum number of sounds this node can play at the same time. Playing additional sounds after this value is reached will cut off the oldest sounds.
</member>
<member name="panning_strength" type="float" setter="set_panning_strength" getter="get_panning_strength" default="1.0">
Scales the panning strength for this node by multiplying the base [member ProjectSettings.audio/general/3d_panning_strength] by this factor. If the product is [code]0.0[/code] then stereo panning is disabled and the volume is the same for all channels. If the product is [code]1.0[/code] then one of the channels will be muted when the sound is located exactly to the left (or right) of the listener.
Two speaker stereo arrangements implement the [url=https://webaudio.github.io/web-audio-api/#stereopanner-algorithm]WebAudio standard for StereoPannerNode Panning[/url] where the volume is cosine of half the azimuth angle to the ear.
For other speaker arrangements such as the 5.1 and 7.1 the SPCAP (Speaker-Placement Correction Amplitude) algorithm is implemented.
</member>
<member name="pitch_scale" type="float" setter="set_pitch_scale" getter="get_pitch_scale" default="1.0">
The pitch and the tempo of the audio, as a multiplier of the audio sample's sample rate.
</member>
<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">
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">
The [AudioStream] resource to be played.
</member>
<member name="stream_paused" type="bool" setter="set_stream_paused" getter="get_stream_paused" default="false">
If [code]true[/code], the playback is paused. You can resume it by setting [member stream_paused] to [code]false[/code].
</member>
<member name="unit_size" type="float" setter="set_unit_size" getter="get_unit_size" default="10.0">
The factor for the attenuation effect. Higher values make the sound audible over a larger distance.
</member>
<member name="volume_db" type="float" setter="set_volume_db" getter="get_volume_db" default="0.0">
The base sound level 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">
<description>
Emitted when the audio stops playing.
</description>
</signal>
</signals>
<constants>
<constant name="ATTENUATION_INVERSE_DISTANCE" value="0" enum="AttenuationModel">
Attenuation of loudness according to linear distance.
</constant>
<constant name="ATTENUATION_INVERSE_SQUARE_DISTANCE" value="1" enum="AttenuationModel">
Attenuation of loudness according to squared distance.
</constant>
<constant name="ATTENUATION_LOGARITHMIC" value="2" enum="AttenuationModel">
Attenuation of loudness according to logarithmic distance.
</constant>
<constant name="ATTENUATION_DISABLED" value="3" enum="AttenuationModel">
No attenuation of loudness according to distance. The sound will still be heard positionally, unlike an [AudioStreamPlayer]. [constant ATTENUATION_DISABLED] can be combined with a [member max_distance] value greater than [code]0.0[/code] to achieve linear attenuation clamped to a sphere of a defined size.
</constant>
<constant name="DOPPLER_TRACKING_DISABLED" value="0" enum="DopplerTracking">
Disables doppler tracking.
</constant>
<constant name="DOPPLER_TRACKING_IDLE_STEP" value="1" enum="DopplerTracking">
Executes doppler tracking during process frames (see [constant Node.NOTIFICATION_INTERNAL_PROCESS]).
</constant>
<constant name="DOPPLER_TRACKING_PHYSICS_STEP" value="2" enum="DopplerTracking">
Executes doppler tracking during physics frames (see [constant Node.NOTIFICATION_INTERNAL_PHYSICS_PROCESS]).
</constant>
</constants>
</class>

17
doc/classes/AudioStreamPolyphonic.xml Normal file
View File

@@ -0,0 +1,17 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioStreamPolyphonic" inherits="AudioStream" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
AudioStream that lets the user play custom streams at any time from code, simultaneously using a single player.
</brief_description>
<description>
AudioStream that lets the user play custom streams at any time from code, simultaneously using a single player.
Playback control is done via the [AudioStreamPlaybackPolyphonic] instance set inside the player, which can be obtained via [method AudioStreamPlayer.get_stream_playback], [method AudioStreamPlayer2D.get_stream_playback] or [method AudioStreamPlayer3D.get_stream_playback] methods. Obtaining the playback instance is only valid after the [code]stream[/code] property is set as an [AudioStreamPolyphonic] in those players.
</description>
<tutorials>
</tutorials>
<members>
<member name="polyphony" type="int" setter="set_polyphony" getter="get_polyphony" default="32">
Maximum amount of simultaneous streams that can be played.
</member>
</members>
</class>

92
doc/classes/AudioStreamRandomizer.xml Normal file
View File

@@ -0,0 +1,92 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioStreamRandomizer" inherits="AudioStream" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Wraps a pool of audio streams with pitch and volume shifting.
</brief_description>
<description>
Picks a random AudioStream from the pool, depending on the playback mode, and applies random pitch shifting and volume shifting during playback.
</description>
<tutorials>
</tutorials>
<methods>
<method name="add_stream">
<return type="void" />
<param index="0" name="index" type="int" />
<param index="1" name="stream" type="AudioStream" />
<param index="2" name="weight" type="float" default="1.0" />
<description>
Insert a stream at the specified index. If the index is less than zero, the insertion occurs at the end of the underlying pool.
</description>
</method>
<method name="get_stream" qualifiers="const">
<return type="AudioStream" />
<param index="0" name="index" type="int" />
<description>
Returns the stream at the specified index.
</description>
</method>
<method name="get_stream_probability_weight" qualifiers="const">
<return type="float" />
<param index="0" name="index" type="int" />
<description>
Returns the probability weight associated with the stream at the given index.
</description>
</method>
<method name="move_stream">
<return type="void" />
<param index="0" name="index_from" type="int" />
<param index="1" name="index_to" type="int" />
<description>
Move a stream from one index to another.
</description>
</method>
<method name="remove_stream">
<return type="void" />
<param index="0" name="index" type="int" />
<description>
Remove the stream at the specified index.
</description>
</method>
<method name="set_stream">
<return type="void" />
<param index="0" name="index" type="int" />
<param index="1" name="stream" type="AudioStream" />
<description>
Set the AudioStream at the specified index.
</description>
</method>
<method name="set_stream_probability_weight">
<return type="void" />
<param index="0" name="index" type="int" />
<param index="1" name="weight" type="float" />
<description>
Set the probability weight of the stream at the specified index. The higher this value, the more likely that the randomizer will choose this stream during random playback modes.
</description>
</method>
</methods>
<members>
<member name="playback_mode" type="int" setter="set_playback_mode" getter="get_playback_mode" enum="AudioStreamRandomizer.PlaybackMode" default="0">
Controls how this AudioStreamRandomizer picks which AudioStream to play next.
</member>
<member name="random_pitch" type="float" setter="set_random_pitch" getter="get_random_pitch" default="1.0">
The intensity of random pitch variation. A value of 1 means no variation.
</member>
<member name="random_volume_offset_db" type="float" setter="set_random_volume_offset_db" getter="get_random_volume_offset_db" default="0.0">
The intensity of random volume variation. A value of 0 means no variation.
</member>
<member name="streams_count" type="int" setter="set_streams_count" getter="get_streams_count" default="0">
The number of streams in the stream pool.
</member>
</members>
<constants>
<constant name="PLAYBACK_RANDOM_NO_REPEATS" value="0" enum="PlaybackMode">
Pick a stream at random according to the probability weights chosen for each stream, but avoid playing the same stream twice in a row whenever possible. If only 1 sound is present in the pool, the same sound will always play, effectively allowing repeats to occur.
</constant>
<constant name="PLAYBACK_RANDOM" value="1" enum="PlaybackMode">
Pick a stream at random according to the probability weights chosen for each stream. If only 1 sound is present in the pool, the same sound will always play.
</constant>
<constant name="PLAYBACK_SEQUENTIAL" value="2" enum="PlaybackMode">
Play streams in the order they appear in the stream pool. If only 1 sound is present in the pool, the same sound will always play.
</constant>
</constants>
</class>

115
doc/classes/AudioStreamWAV.xml Normal file
View File

@@ -0,0 +1,115 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="AudioStreamWAV" inherits="AudioStream" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Stores audio data loaded from WAV files.
</brief_description>
<description>
AudioStreamWAV stores sound samples loaded from WAV files. To play the stored sound, use an [AudioStreamPlayer] (for non-positional audio) or [AudioStreamPlayer2D]/[AudioStreamPlayer3D] (for positional audio). The sound can be looped.
This class can also be used to store dynamically-generated PCM audio data. See also [AudioStreamGenerator] for procedural audio generation.
</description>
<tutorials>
<link title="Runtime file loading and saving">$DOCS_URL/tutorials/io/runtime_file_loading_and_saving.html</link>
</tutorials>
<methods>
<method name="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 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>
</methods>
<members>
<member name="data" type="PackedByteArray" setter="set_data" getter="get_data" default="PackedByteArray()">
Contains the audio data in bytes.
[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.
</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).
</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).
</member>
<member name="loop_mode" type="int" setter="set_loop_mode" getter="get_loop_mode" enum="AudioStreamWAV.LoopMode" default="0">
The loop mode.
</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.
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 using 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.
</member>
<member name="stereo" type="bool" setter="set_stereo" getter="is_stereo" default="false">
If [code]true[/code], audio is stereo.
</member>
<member name="tags" type="Dictionary" setter="set_tags" getter="get_tags" default="{}">
Contains user-defined tags if found in the WAV data.
Commonly used tags include [code]title[/code], [code]artist[/code], [code]album[/code], [code]tracknumber[/code], and [code]date[/code] ([code]date[/code] does not have a standard date format).
[b]Note:[/b] No tag is [i]guaranteed[/i] to be present in every file, so make sure to account for the keys not always existing.
[b]Note:[/b] Only WAV files using a [code]LIST[/code] chunk with an identifier of [code]INFO[/code] to encode the tags are currently supported.
</member>
</members>
<constants>
<constant name="FORMAT_8_BITS" value="0" enum="Format">
8-bit PCM audio codec.
</constant>
<constant name="FORMAT_16_BITS" value="1" enum="Format">
16-bit PCM audio codec.
</constant>
<constant name="FORMAT_IMA_ADPCM" value="2" enum="Format">
Audio is lossily compressed as IMA ADPCM.
</constant>
<constant name="FORMAT_QOA" value="3" enum="Format">
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.
</constant>
<constant name="LOOP_FORWARD" value="1" enum="LoopMode">
Audio loops the data between [member loop_begin] and [member loop_end], playing forward only.
</constant>
<constant name="LOOP_PINGPONG" value="2" enum="LoopMode">
Audio loops the data between [member loop_begin] and [member loop_end], playing back and forth.
</constant>
<constant name="LOOP_BACKWARD" value="3" enum="LoopMode">
Audio loops the data between [member loop_begin] and [member loop_end], playing backward only.
</constant>
</constants>
</class>

32
doc/classes/BackBufferCopy.xml Normal file
View File

@@ -0,0 +1,32 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="BackBufferCopy" inherits="Node2D" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
A node that copies a region of the screen to a buffer for access in shader code.
</brief_description>
<description>
Node for back-buffering the currently-displayed screen. The region defined in the [BackBufferCopy] node is buffered with the content of the screen it covers, or the entire screen according to the [member copy_mode]. It can be accessed in shader scripts using the screen texture (i.e. a uniform sampler with [code]hint_screen_texture[/code]).
[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">
Buffer mode.
</member>
<member name="rect" type="Rect2" setter="set_rect" getter="get_rect" default="Rect2(-100, -100, 200, 200)">
The area covered by the [BackBufferCopy]. Only used if [member copy_mode] is [constant COPY_MODE_RECT].
</member>
</members>
<constants>
<constant name="COPY_MODE_DISABLED" value="0" enum="CopyMode">
Disables the buffering mode. This means the [BackBufferCopy] node will directly use the portion of screen it covers.
</constant>
<constant name="COPY_MODE_RECT" value="1" enum="CopyMode">
[BackBufferCopy] buffers a rectangular region.
</constant>
<constant name="COPY_MODE_VIEWPORT" value="2" enum="CopyMode">
[BackBufferCopy] buffers the entire screen.
</constant>
</constants>
</class>

132
doc/classes/BaseButton.xml Normal file
View File

@@ -0,0 +1,132 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="BaseButton" inherits="Control" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Abstract base class for GUI buttons.
</brief_description>
<description>
[BaseButton] is an abstract base class for GUI buttons. It doesn't display anything by itself.
</description>
<tutorials>
</tutorials>
<methods>
<method name="_pressed" qualifiers="virtual">
<return type="void" />
<description>
Called when the button is pressed. If you need to know the button's pressed state (and [member toggle_mode] is active), use [method _toggled] instead.
</description>
</method>
<method name="_toggled" qualifiers="virtual">
<return type="void" />
<param index="0" name="toggled_on" type="bool" />
<description>
Called when the button is toggled (only if [member toggle_mode] is active).
</description>
</method>
<method name="get_draw_mode" qualifiers="const">
<return type="int" enum="BaseButton.DrawMode" />
<description>
Returns the visual state used to draw the button. This is useful mainly when implementing your own draw code by either overriding _draw() or connecting to "draw" signal. The visual state of the button is defined by the [enum DrawMode] enum.
</description>
</method>
<method name="is_hovered" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if the mouse has entered the button and has not left it yet.
</description>
</method>
<method name="set_pressed_no_signal">
<return type="void" />
<param index="0" name="pressed" type="bool" />
<description>
Changes the [member button_pressed] state of the button, without emitting [signal toggled]. Use when you just want to change the state of the button without sending the pressed event (e.g. when initializing scene). Only works if [member toggle_mode] is [code]true[/code].
[b]Note:[/b] This method doesn't unpress other buttons in [member button_group].
</description>
</method>
</methods>
<members>
<member name="action_mode" type="int" setter="set_action_mode" getter="get_action_mode" enum="BaseButton.ActionMode" default="1">
Determines when the button is considered clicked.
</member>
<member name="button_group" type="ButtonGroup" setter="set_button_group" getter="get_button_group">
The [ButtonGroup] associated with the button. Not to be confused with node groups.
[b]Note:[/b] The button will be configured as a radio button if a [ButtonGroup] is assigned to it.
</member>
<member name="button_mask" type="int" setter="set_button_mask" getter="get_button_mask" enum="MouseButtonMask" is_bitfield="true" default="1">
Binary mask to choose which mouse buttons this button will respond to.
To allow both left-click and right-click, use [code]MOUSE_BUTTON_MASK_LEFT | MOUSE_BUTTON_MASK_RIGHT[/code].
</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] 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.
[b]Note:[/b] If the button is disabled while held down, [signal button_up] will be emitted.
</member>
<member name="focus_mode" type="int" setter="set_focus_mode" getter="get_focus_mode" overrides="Control" enum="Control.FocusMode" default="2" />
<member name="keep_pressed_outside" type="bool" setter="set_keep_pressed_outside" getter="is_keep_pressed_outside" default="false">
If [code]true[/code], the button stays pressed when moving the cursor outside the button while pressing it.
[b]Note:[/b] This property only affects the button's visual appearance. Signals will be emitted at the same moment regardless of this property's value.
</member>
<member name="shortcut" type="Shortcut" setter="set_shortcut" getter="get_shortcut">
[Shortcut] associated to the button.
</member>
<member name="shortcut_feedback" type="bool" setter="set_shortcut_feedback" getter="is_shortcut_feedback" default="true">
If [code]true[/code], the button will highlight for a short amount of time when its shortcut is activated. If [code]false[/code] and [member toggle_mode] is [code]false[/code], the shortcut will activate without any visual feedback.
</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.
</member>
</members>
<signals>
<signal name="button_down">
<description>
Emitted when the button starts being held down.
</description>
</signal>
<signal name="button_up">
<description>
Emitted when the button stops being held down.
</description>
</signal>
<signal name="pressed">
<description>
Emitted when the button is toggled or pressed. This is on [signal button_down] if [member action_mode] is [constant ACTION_MODE_BUTTON_PRESS] and on [signal button_up] otherwise.
If you need to know the button's pressed state (and [member toggle_mode] is active), use [signal toggled] instead.
</description>
</signal>
<signal name="toggled">
<param index="0" name="toggled_on" type="bool" />
<description>
Emitted when the button was just toggled between pressed and normal states (only if [member toggle_mode] is active). The new state is contained in the [param toggled_on] argument.
</description>
</signal>
</signals>
<constants>
<constant name="DRAW_NORMAL" value="0" enum="DrawMode">
The normal state (i.e. not pressed, not hovered, not toggled and enabled) of buttons.
</constant>
<constant name="DRAW_PRESSED" value="1" enum="DrawMode">
The state of buttons are pressed.
</constant>
<constant name="DRAW_HOVER" value="2" enum="DrawMode">
The state of buttons are hovered.
</constant>
<constant name="DRAW_DISABLED" value="3" enum="DrawMode">
The state of buttons are disabled.
</constant>
<constant name="DRAW_HOVER_PRESSED" value="4" enum="DrawMode">
The state of buttons are both hovered and pressed.
</constant>
<constant name="ACTION_MODE_BUTTON_PRESS" value="0" enum="ActionMode">
Require just a press to consider the button clicked.
</constant>
<constant name="ACTION_MODE_BUTTON_RELEASE" value="1" enum="ActionMode">
Require a press and a subsequent release before considering the button clicked.
</constant>
</constants>
</class>

894
doc/classes/BaseMaterial3D.xml Normal file
View File

@@ -0,0 +1,894 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="BaseMaterial3D" inherits="Material" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Abstract base class for defining the 3D rendering properties of meshes.
</brief_description>
<description>
This class serves as a default material with a wide variety of rendering features and properties without the need to write shader code. See the tutorial below for details.
</description>
<tutorials>
<link title="Standard Material 3D and ORM Material 3D">$DOCS_URL/tutorials/3d/standard_material_3d.html</link>
</tutorials>
<methods>
<method name="get_feature" qualifiers="const">
<return type="bool" />
<param index="0" name="feature" type="int" enum="BaseMaterial3D.Feature" />
<description>
Returns [code]true[/code], if the specified [enum Feature] is enabled.
</description>
</method>
<method name="get_flag" qualifiers="const">
<return type="bool" />
<param index="0" name="flag" type="int" enum="BaseMaterial3D.Flags" />
<description>
Returns [code]true[/code] if the specified flag is enabled.
</description>
</method>
<method name="get_texture" qualifiers="const">
<return type="Texture2D" />
<param index="0" name="param" type="int" enum="BaseMaterial3D.TextureParam" />
<description>
Returns the [Texture2D] associated with the specified [enum TextureParam].
</description>
</method>
<method name="set_feature">
<return type="void" />
<param index="0" name="feature" type="int" enum="BaseMaterial3D.Feature" />
<param index="1" name="enable" type="bool" />
<description>
If [code]true[/code], enables the specified [enum Feature]. Many features that are available in [BaseMaterial3D]s need to be enabled before use. This way the cost for using the feature is only incurred when specified. Features can also be enabled by setting the corresponding member to [code]true[/code].
</description>
</method>
<method name="set_flag">
<return type="void" />
<param index="0" name="flag" type="int" enum="BaseMaterial3D.Flags" />
<param index="1" name="enable" type="bool" />
<description>
If [code]true[/code], enables the specified flag. Flags are optional behavior that can be turned on and off. Only one flag can be enabled at a time with this function, the flag enumerators cannot be bit-masked together to enable or disable multiple flags at once. Flags can also be enabled by setting the corresponding member to [code]true[/code].
</description>
</method>
<method name="set_texture">
<return type="void" />
<param index="0" name="param" type="int" enum="BaseMaterial3D.TextureParam" />
<param index="1" name="texture" type="Texture2D" />
<description>
Sets the texture for the slot specified by [param param].
</description>
</method>
</methods>
<members>
<member name="albedo_color" type="Color" setter="set_albedo" getter="get_albedo" default="Color(1, 1, 1, 1)" keywords="albedo_colour, diffuse_color, diffuse_colour">
The material's base color.
[b]Note:[/b] If [member detail_enabled] is [code]true[/code] and a [member detail_albedo] texture is specified, [member albedo_color] will [i]not[/i] modulate the detail texture. This can be used to color partial areas of a material by not specifying an albedo texture and using a transparent [member detail_albedo] texture instead.
</member>
<member name="albedo_texture" type="Texture2D" setter="set_texture" getter="get_texture" keywords="diffuse_texture">
Texture to multiply by [member albedo_color]. Used for basic texturing of objects.
If the texture appears unexpectedly too dark or too bright, check [member albedo_texture_force_srgb].
</member>
<member name="albedo_texture_force_srgb" type="bool" setter="set_flag" getter="get_flag" default="false" keywords="diffuse_texture_force_srgb">
If [code]true[/code], forces a conversion of the [member albedo_texture] from sRGB color space to linear color space. See also [member vertex_color_is_srgb].
This should only be enabled when needed (typically when using a [ViewportTexture] as [member albedo_texture]). If [member albedo_texture_force_srgb] is [code]true[/code] when it shouldn't be, the texture will appear to be too dark. If [member albedo_texture_force_srgb] is [code]false[/code] when it shouldn't be, the texture will appear to be too bright.
</member>
<member name="albedo_texture_msdf" type="bool" setter="set_flag" getter="get_flag" default="false" keywords="diffuse_texture_force_srgb">
Enables multichannel signed distance field rendering shader. Use [member msdf_pixel_range] and [member msdf_outline_size] to configure MSDF parameters.
</member>
<member name="alpha_antialiasing_edge" type="float" setter="set_alpha_antialiasing_edge" getter="get_alpha_antialiasing_edge">
Threshold at which antialiasing will be applied on the alpha channel.
</member>
<member name="alpha_antialiasing_mode" type="int" setter="set_alpha_antialiasing" getter="get_alpha_antialiasing" enum="BaseMaterial3D.AlphaAntiAliasing">
The type of alpha antialiasing to apply.
</member>
<member name="alpha_hash_scale" type="float" setter="set_alpha_hash_scale" getter="get_alpha_hash_scale">
The hashing scale for Alpha Hash. Recommended values between [code]0[/code] and [code]2[/code].
</member>
<member name="alpha_scissor_threshold" type="float" setter="set_alpha_scissor_threshold" getter="get_alpha_scissor_threshold" keywords="alpha_test_threshold">
Threshold at which the alpha scissor will discard values. Higher values will result in more pixels being discarded. If the material becomes too opaque at a distance, try increasing [member alpha_scissor_threshold]. If the material disappears at a distance, try decreasing [member alpha_scissor_threshold].
</member>
<member name="anisotropy" type="float" setter="set_anisotropy" getter="get_anisotropy" default="0.0">
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 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>
<member name="anisotropy_flowmap" type="Texture2D" setter="set_texture" getter="get_texture">
Texture that offsets the tangent map for anisotropy calculations and optionally controls the anisotropy effect (if an alpha channel is present). The flowmap texture is expected to be a derivative map, with the red channel representing distortion on the X axis and green channel representing distortion on the Y axis. Values below 0.5 will result in negative distortion, whereas values above 0.5 will result in positive distortion.
If present, the texture's alpha channel will be used to multiply the strength of the [member anisotropy] effect. Fully opaque pixels will keep the anisotropy effect's original strength while fully transparent pixels will disable the anisotropy effect entirely. The flowmap texture's blue channel is ignored.
</member>
<member name="ao_enabled" type="bool" setter="set_feature" getter="get_feature" default="false">
If [code]true[/code], ambient occlusion is enabled. Ambient occlusion darkens areas based on the [member ao_texture].
</member>
<member name="ao_light_affect" type="float" setter="set_ao_light_affect" getter="get_ao_light_affect" default="0.0">
Amount that ambient occlusion affects lighting from lights. If [code]0[/code], ambient occlusion only affects ambient light. If [code]1[/code], ambient occlusion affects lights just as much as it affects ambient light. This can be used to impact the strength of the ambient occlusion effect, but typically looks unrealistic.
</member>
<member name="ao_on_uv2" type="bool" setter="set_flag" getter="get_flag" default="false">
If [code]true[/code], use [code]UV2[/code] coordinates to look up from the [member ao_texture].
</member>
<member name="ao_texture" type="Texture2D" setter="set_texture" getter="get_texture">
Texture that defines the amount of ambient occlusion for a given point on the object.
</member>
<member name="ao_texture_channel" type="int" setter="set_ao_texture_channel" getter="get_ao_texture_channel" enum="BaseMaterial3D.TextureChannel" default="0">
Specifies the channel of the [member ao_texture] in which the ambient occlusion information is stored. This is useful when you store the information for multiple effects in a single texture. For example if you stored metallic in the red channel, roughness in the blue, and ambient occlusion in the green you could reduce the number of textures you use.
</member>
<member name="backlight" type="Color" setter="set_backlight" getter="get_backlight" default="Color(0, 0, 0, 1)">
The color used by the backlight effect. Represents the light passing through an object.
</member>
<member name="backlight_enabled" type="bool" setter="set_feature" getter="get_feature" default="false">
If [code]true[/code], the backlight effect is enabled. See also [member subsurf_scatter_transmittance_enabled].
</member>
<member name="backlight_texture" type="Texture2D" setter="set_texture" getter="get_texture">
Texture used to control the backlight effect per-pixel. Added to [member backlight].
</member>
<member name="bent_normal_enabled" type="bool" setter="set_feature" getter="get_feature" default="false">
If [code]true[/code], the bent normal map is enabled. This allows for more accurate indirect lighting and specular occlusion.
</member>
<member name="bent_normal_texture" type="Texture2D" setter="set_texture" getter="get_texture">
Texture that specifies the average direction of incoming ambient light at a given pixel. The [member bent_normal_texture] only uses the red and green channels; the blue and alpha channels are ignored. The normal read from [member bent_normal_texture] is oriented around the surface normal provided by the [Mesh].
[b]Note:[/b] A bent normal map is different from a regular normal map. When baking a bent normal map make sure to use [b]a cosine distribution[/b] for the bent normal map to work correctly.
[b]Note:[/b] The mesh must have both normals and tangents defined in its vertex data. Otherwise, the shading produced by the bent normal map will not look correct. If creating geometry with [SurfaceTool], you can use [method SurfaceTool.generate_normals] and [method SurfaceTool.generate_tangents] to automatically generate normals and tangents respectively.
[b]Note:[/b] Godot expects the bent normal map to use X+, Y+, and Z+ coordinates. See [url=http://wiki.polycount.com/wiki/Normal_Map_Technical_Details#Common_Swizzle_Coordinates]this page[/url] for a comparison of normal map coordinates expected by popular engines.
</member>
<member name="billboard_keep_scale" type="bool" setter="set_flag" getter="get_flag" default="false">
If [code]true[/code], the shader will keep the scale set for the mesh. Otherwise, the scale is lost when billboarding. Only applies when [member billboard_mode] is not [constant BILLBOARD_DISABLED].
</member>
<member name="billboard_mode" type="int" setter="set_billboard_mode" getter="get_billboard_mode" enum="BaseMaterial3D.BillboardMode" default="0">
Controls how the object faces the camera.
[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">
The material's blend mode.
[b]Note:[/b] Values other than [code]Mix[/code] force the object into the transparent pipeline.
</member>
<member name="clearcoat" type="float" setter="set_clearcoat" getter="get_clearcoat" default="1.0">
Sets the strength of the clearcoat effect. Setting to [code]0[/code] looks the same as disabling the clearcoat effect.
</member>
<member name="clearcoat_enabled" type="bool" setter="set_feature" getter="get_feature" default="false">
If [code]true[/code], clearcoat rendering is enabled. Adds a secondary transparent pass to the lighting calculation resulting in an added specular blob. This makes materials appear as if they have a clear layer on them that can be either glossy or rough.
[b]Note:[/b] Clearcoat rendering is not visible if the material's [member shading_mode] is [constant SHADING_MODE_UNSHADED].
</member>
<member name="clearcoat_roughness" type="float" setter="set_clearcoat_roughness" getter="get_clearcoat_roughness" default="0.5">
Sets the roughness of the clearcoat pass. A higher value results in a rougher clearcoat while a lower value results in a smoother clearcoat.
</member>
<member name="clearcoat_texture" type="Texture2D" setter="set_texture" getter="get_texture">
Texture that defines the strength of the clearcoat effect and the glossiness of the clearcoat. Strength is specified in the red channel while glossiness is specified in the green channel.
</member>
<member name="cull_mode" type="int" setter="set_cull_mode" getter="get_cull_mode" enum="BaseMaterial3D.CullMode" default="0">
Determines which side of the triangle to cull depending on whether the triangle faces towards or away from the camera.
</member>
<member name="depth_draw_mode" type="int" setter="set_depth_draw_mode" getter="get_depth_draw_mode" enum="BaseMaterial3D.DepthDrawMode" default="0">
Determines when depth rendering takes place. See also [member transparency].
</member>
<member name="depth_test" type="int" setter="set_depth_test" getter="get_depth_test" enum="BaseMaterial3D.DepthTest" default="0" experimental="May be affected by future rendering pipeline changes.">
Determines which comparison operator is used when testing depth. See [enum DepthTest].
[b]Note:[/b] Changing [member depth_test] to a non-default value only has a visible effect when used on a transparent material, or a material that has [member depth_draw_mode] set to [constant DEPTH_DRAW_DISABLED].
</member>
<member name="detail_albedo" type="Texture2D" setter="set_texture" getter="get_texture">
Texture that specifies the color of the detail overlay. [member detail_albedo]'s alpha channel is used as a mask, even when the material is opaque. To use a dedicated texture as a mask, see [member detail_mask].
[b]Note:[/b] [member detail_albedo] is [i]not[/i] modulated by [member albedo_color].
</member>
<member name="detail_blend_mode" type="int" setter="set_detail_blend_mode" getter="get_detail_blend_mode" enum="BaseMaterial3D.BlendMode" default="0">
Specifies how the [member detail_albedo] should blend with the current [code]ALBEDO[/code].
</member>
<member name="detail_enabled" type="bool" setter="set_feature" getter="get_feature" default="false">
If [code]true[/code], enables the detail overlay. Detail is a second texture that gets mixed over the surface of the object based on [member detail_mask] and [member detail_albedo]'s alpha channel. This can be used to add variation to objects, or to blend between two different albedo/normal textures.
</member>
<member name="detail_mask" type="Texture2D" setter="set_texture" getter="get_texture">
Texture used to specify how the detail textures get blended with the base textures. [member detail_mask] can be used together with [member detail_albedo]'s alpha channel (if any).
</member>
<member name="detail_normal" type="Texture2D" setter="set_texture" getter="get_texture">
Texture that specifies the per-pixel normal of the detail overlay. The [member detail_normal] texture only uses the red and green channels; the blue and alpha channels are ignored. The normal read from [member detail_normal] is oriented around the surface normal provided by the [Mesh].
[b]Note:[/b] Godot expects the normal map to use X+, Y+, and Z+ coordinates. See [url=http://wiki.polycount.com/wiki/Normal_Map_Technical_Details#Common_Swizzle_Coordinates]this page[/url] for a comparison of normal map coordinates expected by popular engines.
</member>
<member name="detail_uv_layer" type="int" setter="set_detail_uv" getter="get_detail_uv" enum="BaseMaterial3D.DetailUV" default="0">
Specifies whether to use [code]UV[/code] or [code]UV2[/code] for the detail layer.
</member>
<member name="diffuse_mode" type="int" setter="set_diffuse_mode" getter="get_diffuse_mode" enum="BaseMaterial3D.DiffuseMode" default="0">
The algorithm used for diffuse light scattering.
</member>
<member name="disable_ambient_light" type="bool" setter="set_flag" getter="get_flag" default="false">
If [code]true[/code], the object receives no ambient light.
</member>
<member name="disable_fog" type="bool" setter="set_flag" getter="get_flag" default="false">
If [code]true[/code], the object will not be affected by fog (neither volumetric nor depth fog). This is useful for unshaded or transparent materials (e.g. particles), which without this setting will be affected even if fully transparent.
</member>
<member name="disable_receive_shadows" type="bool" setter="set_flag" getter="get_flag" default="false">
If [code]true[/code], the object receives no shadow that would otherwise be cast onto it.
</member>
<member name="disable_specular_occlusion" type="bool" setter="set_flag" getter="get_flag" default="false">
If [code]true[/code], disables specular occlusion even if [member ProjectSettings.rendering/reflections/specular_occlusion/enabled] is [code]false[/code].
</member>
<member name="distance_fade_max_distance" type="float" setter="set_distance_fade_max_distance" getter="get_distance_fade_max_distance" default="10.0">
Distance at which the object appears fully opaque.
[b]Note:[/b] If [member distance_fade_max_distance] is less than [member distance_fade_min_distance], the behavior will be reversed. The object will start to fade away at [member distance_fade_max_distance] and will fully disappear once it reaches [member distance_fade_min_distance].
</member>
<member name="distance_fade_min_distance" type="float" setter="set_distance_fade_min_distance" getter="get_distance_fade_min_distance" default="0.0">
Distance at which the object starts to become visible. If the object is less than this distance away, it will be invisible.
[b]Note:[/b] If [member distance_fade_min_distance] is greater than [member distance_fade_max_distance], the behavior will be reversed. The object will start to fade away at [member distance_fade_max_distance] and will fully disappear once it reaches [member distance_fade_min_distance].
</member>
<member name="distance_fade_mode" type="int" setter="set_distance_fade" getter="get_distance_fade" enum="BaseMaterial3D.DistanceFadeMode" default="0">
Specifies which type of fade to use. Can be any of the [enum DistanceFadeMode]s.
</member>
<member name="emission" type="Color" setter="set_emission" getter="get_emission" default="Color(0, 0, 0, 1)">
The emitted light's color. See [member emission_enabled].
</member>
<member name="emission_enabled" type="bool" setter="set_feature" getter="get_feature" default="false">
If [code]true[/code], the body emits light. Emitting light makes the object appear brighter. The object can also cast light on other objects if a [VoxelGI], SDFGI, or [LightmapGI] is used and this object is used in baked lighting.
</member>
<member name="emission_energy_multiplier" type="float" setter="set_emission_energy_multiplier" getter="get_emission_energy_multiplier" default="1.0">
Multiplier for emitted light. See [member emission_enabled].
</member>
<member name="emission_intensity" type="float" setter="set_emission_intensity" getter="get_emission_intensity">
Luminance of emitted light, measured in nits (candela per square meter). Only available when [member ProjectSettings.rendering/lights_and_shadows/use_physical_light_units] is enabled. The default is roughly equivalent to an indoor lightbulb.
</member>
<member name="emission_on_uv2" type="bool" setter="set_flag" getter="get_flag" default="false">
Use [code]UV2[/code] to read from the [member emission_texture].
</member>
<member name="emission_operator" type="int" setter="set_emission_operator" getter="get_emission_operator" enum="BaseMaterial3D.EmissionOperator" default="0">
Sets how [member emission] interacts with [member emission_texture]. Can either add or multiply.
</member>
<member name="emission_texture" type="Texture2D" setter="set_texture" getter="get_texture">
Texture that specifies how much surface emits light at a given point.
</member>
<member name="fixed_size" type="bool" setter="set_flag" getter="get_flag" default="false">
If [code]true[/code], the object is rendered at the same size regardless of distance. The object's size on screen is the same as if the camera was [code]1.0[/code] units away from the object's origin, regardless of the actual distance from the camera. The [Camera3D]'s field of view (or [member Camera3D.size] when in orthogonal/frustum mode) still affects the size the object is drawn at.
</member>
<member name="fov_override" type="float" setter="set_fov_override" getter="get_fov_override" default="75.0">
Overrides the [Camera3D]'s field of view angle (in degrees).
[b]Note:[/b] This behaves as if the field of view is set on a [Camera3D] with [member Camera3D.keep_aspect] set to [constant Camera3D.KEEP_HEIGHT]. Additionally, it may not look correct on a non-perspective camera where the field of view setting is ignored.
</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=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].
</member>
<member name="heightmap_deep_parallax" type="bool" setter="set_heightmap_deep_parallax" getter="is_heightmap_deep_parallax_enabled" default="false">
If [code]true[/code], uses parallax occlusion mapping to represent depth in the material instead of simple offset mapping (see [member heightmap_enabled]). This results in a more convincing depth effect, but is much more expensive on the GPU. Only enable this on materials where it makes a significant visual difference.
</member>
<member name="heightmap_enabled" type="bool" setter="set_feature" getter="get_feature" default="false">
If [code]true[/code], height mapping is enabled (also called "parallax mapping" or "depth mapping"). See also [member normal_enabled]. Height mapping is a demanding feature on the GPU, so it should only be used on materials where it makes a significant visual difference.
[b]Note:[/b] Height mapping is not supported if triplanar mapping is used on the same material. The value of [member heightmap_enabled] will be ignored if [member uv1_triplanar] is enabled.
</member>
<member name="heightmap_flip_binormal" type="bool" setter="set_heightmap_deep_parallax_flip_binormal" getter="get_heightmap_deep_parallax_flip_binormal" default="false">
If [code]true[/code], flips the mesh's binormal vectors when interpreting the height map. If the heightmap effect looks strange when the camera moves (even with a reasonable [member heightmap_scale]), try setting this to [code]true[/code].
</member>
<member name="heightmap_flip_tangent" type="bool" setter="set_heightmap_deep_parallax_flip_tangent" getter="get_heightmap_deep_parallax_flip_tangent" default="false">
If [code]true[/code], flips the mesh's tangent vectors when interpreting the height map. If the heightmap effect looks strange when the camera moves (even with a reasonable [member heightmap_scale]), try setting this to [code]true[/code].
</member>
<member name="heightmap_flip_texture" type="bool" setter="set_flag" getter="get_flag" default="false">
If [code]true[/code], interprets the height map texture as a depth map, with brighter values appearing to be "lower" in altitude compared to darker values.
This can be enabled for compatibility with some materials authored for Godot 3.x. This is not necessary if the Invert import option was used to invert the depth map in Godot 3.x, in which case [member heightmap_flip_texture] should remain [code]false[/code].
</member>
<member name="heightmap_max_layers" type="int" setter="set_heightmap_deep_parallax_max_layers" getter="get_heightmap_deep_parallax_max_layers">
The number of layers to use for parallax occlusion mapping when the camera is up close to the material. Higher values result in a more convincing depth effect, especially in materials that have steep height changes. Higher values have a significant cost on the GPU, so it should only be increased on materials where it makes a significant visual difference.
[b]Note:[/b] Only effective if [member heightmap_deep_parallax] is [code]true[/code].
</member>
<member name="heightmap_min_layers" type="int" setter="set_heightmap_deep_parallax_min_layers" getter="get_heightmap_deep_parallax_min_layers">
The number of layers to use for parallax occlusion mapping when the camera is far away from the material. Higher values result in a more convincing depth effect, especially in materials that have steep height changes. Higher values have a significant cost on the GPU, so it should only be increased on materials where it makes a significant visual difference.
[b]Note:[/b] Only effective if [member heightmap_deep_parallax] is [code]true[/code].
</member>
<member name="heightmap_scale" type="float" setter="set_heightmap_scale" getter="get_heightmap_scale" default="5.0">
The heightmap scale to use for the parallax effect (see [member heightmap_enabled]). The default value is tuned so that the highest point (value = 255) appears to be 5 cm higher than the lowest point (value = 0). Higher values result in a deeper appearance, but may result in artifacts appearing when looking at the material from oblique angles, especially when the camera moves. Negative values can be used to invert the parallax effect, but this is different from inverting the texture using [member heightmap_flip_texture] as the material will also appear to be "closer" to the camera. In most cases, [member heightmap_scale] should be kept to a positive value.
[b]Note:[/b] If the height map effect looks strange regardless of this value, try adjusting [member heightmap_flip_binormal] and [member heightmap_flip_tangent]. See also [member heightmap_texture] for recommendations on authoring heightmap textures, as the way the heightmap texture is authored affects how [member heightmap_scale] behaves.
</member>
<member name="heightmap_texture" type="Texture2D" setter="set_texture" getter="get_texture">
The texture to use as a height map. See also [member heightmap_enabled].
For best results, the texture should be normalized (with [member heightmap_scale] reduced to compensate). In [url=https://gimp.org]GIMP[/url], this can be done using [b]Colors &gt; Auto &gt; Equalize[/b]. If the texture only uses a small part of its available range, the parallax effect may look strange, especially when the camera moves.
[b]Note:[/b] To reduce memory usage and improve loading times, you may be able to use a lower-resolution heightmap texture as most heightmaps are only comprised of low-frequency data.
</member>
<member name="metallic" type="float" setter="set_metallic" getter="get_metallic" default="0.0">
A high value makes the material appear more like a metal. Non-metals use their albedo as the diffuse color and add diffuse to the specular reflection. With non-metals, the reflection appears on top of the albedo color. Metals use their albedo as a multiplier to the specular reflection and set the diffuse color to black resulting in a tinted reflection. Materials work better when fully metal or fully non-metal, values between [code]0[/code] and [code]1[/code] should only be used for blending between metal and non-metal sections. To alter the amount of reflection use [member roughness].
</member>
<member name="metallic_specular" type="float" setter="set_specular" getter="get_specular" default="0.5">
Adjusts the strength of specular reflections. Specular reflections are composed of scene reflections and the specular lobe which is the bright spot that is reflected from light sources. When set to [code]0.0[/code], no specular reflections will be visible. This differs from the [constant SPECULAR_DISABLED] [enum SpecularMode] as [constant SPECULAR_DISABLED] only applies to the specular lobe from the light source.
[b]Note:[/b] Unlike [member metallic], this is not energy-conserving, so it should be left at [code]0.5[/code] in most cases. See also [member roughness].
</member>
<member name="metallic_texture" type="Texture2D" setter="set_texture" getter="get_texture">
Texture used to specify metallic for an object. This is multiplied by [member metallic].
</member>
<member name="metallic_texture_channel" type="int" setter="set_metallic_texture_channel" getter="get_metallic_texture_channel" enum="BaseMaterial3D.TextureChannel" default="0">
Specifies the channel of the [member metallic_texture] in which the metallic information is stored. This is useful when you store the information for multiple effects in a single texture. For example if you stored metallic in the red channel, roughness in the blue, and ambient occlusion in the green you could reduce the number of textures you use.
</member>
<member name="msdf_outline_size" type="float" setter="set_msdf_outline_size" getter="get_msdf_outline_size" default="0.0">
The width of the shape outline.
</member>
<member name="msdf_pixel_range" type="float" setter="set_msdf_pixel_range" getter="get_msdf_pixel_range" default="4.0">
The width of the range around the shape between the minimum and maximum representable signed distance.
</member>
<member name="no_depth_test" type="bool" setter="set_flag" getter="get_flag" default="false">
If [code]true[/code], depth testing is disabled and the object will be drawn in render order.
</member>
<member name="normal_enabled" type="bool" setter="set_feature" getter="get_feature" default="false">
If [code]true[/code], normal mapping is enabled. This has a slight performance cost, especially on mobile GPUs.
</member>
<member name="normal_scale" type="float" setter="set_normal_scale" getter="get_normal_scale" default="1.0">
The strength of the normal map's effect.
</member>
<member name="normal_texture" type="Texture2D" setter="set_texture" getter="get_texture">
Texture used to specify the normal at a given pixel. The [member normal_texture] only uses the red and green channels; the blue and alpha channels are ignored. The normal read from [member normal_texture] is oriented around the surface normal provided by the [Mesh].
[b]Note:[/b] The mesh must have both normals and tangents defined in its vertex data. Otherwise, the normal map won't render correctly and will only appear to darken the whole surface. If creating geometry with [SurfaceTool], you can use [method SurfaceTool.generate_normals] and [method SurfaceTool.generate_tangents] to automatically generate normals and tangents respectively.
[b]Note:[/b] Godot expects the normal map to use X+, Y+, and Z+ coordinates. See [url=http://wiki.polycount.com/wiki/Normal_Map_Technical_Details#Common_Swizzle_Coordinates]this page[/url] for a comparison of normal map coordinates expected by popular engines.
[b]Note:[/b] If [member detail_enabled] is [code]true[/code], the [member detail_albedo] texture is drawn [i]below[/i] the [member normal_texture]. To display a normal map [i]above[/i] the [member detail_albedo] texture, use [member detail_normal] instead.
</member>
<member name="orm_texture" type="Texture2D" setter="set_texture" getter="get_texture">
The Occlusion/Roughness/Metallic texture to use. This is a more efficient replacement of [member ao_texture], [member roughness_texture] and [member metallic_texture] in [ORMMaterial3D]. Ambient occlusion is stored in the red channel. Roughness map is stored in the green channel. Metallic map is stored in the blue channel. The alpha channel is ignored.
</member>
<member name="particles_anim_h_frames" type="int" setter="set_particles_anim_h_frames" getter="get_particles_anim_h_frames">
The number of horizontal frames in the particle sprite sheet. Only enabled when using [constant BILLBOARD_PARTICLES]. See [member billboard_mode].
</member>
<member name="particles_anim_loop" type="bool" setter="set_particles_anim_loop" getter="get_particles_anim_loop">
If [code]true[/code], particle animations are looped. Only enabled when using [constant BILLBOARD_PARTICLES]. See [member billboard_mode].
</member>
<member name="particles_anim_v_frames" type="int" setter="set_particles_anim_v_frames" getter="get_particles_anim_v_frames">
The number of vertical frames in the particle sprite sheet. Only enabled when using [constant BILLBOARD_PARTICLES]. See [member billboard_mode].
</member>
<member name="point_size" type="float" setter="set_point_size" getter="get_point_size" default="1.0">
The point size in pixels. See [member use_point_size].
</member>
<member name="proximity_fade_distance" type="float" setter="set_proximity_fade_distance" getter="get_proximity_fade_distance" default="1.0">
Distance over which the fade effect takes place. The larger the distance the longer it takes for an object to fade.
</member>
<member name="proximity_fade_enabled" type="bool" setter="set_proximity_fade_enabled" getter="is_proximity_fade_enabled" default="false">
If [code]true[/code], the proximity fade effect is enabled. The proximity fade effect fades out each pixel based on its distance to another object.
</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.
</member>
<member name="refraction_texture" type="Texture2D" setter="set_texture" getter="get_texture">
Texture that controls the strength of the refraction per-pixel. Multiplied by [member refraction_scale].
</member>
<member name="refraction_texture_channel" type="int" setter="set_refraction_texture_channel" getter="get_refraction_texture_channel" enum="BaseMaterial3D.TextureChannel" default="0">
Specifies the channel of the [member refraction_texture] in which the refraction information is stored. This is useful when you store the information for multiple effects in a single texture. For example if you stored refraction in the red channel, roughness in the blue, and ambient occlusion in the green you could reduce the number of textures you use.
</member>
<member name="rim" type="float" setter="set_rim" getter="get_rim" default="1.0">
Sets the strength of the rim lighting effect.
</member>
<member name="rim_enabled" type="bool" setter="set_feature" getter="get_feature" default="false">
If [code]true[/code], rim effect is enabled. Rim lighting increases the brightness at glancing angles on an object.
[b]Note:[/b] Rim lighting is not visible if the material's [member shading_mode] is [constant SHADING_MODE_UNSHADED].
</member>
<member name="rim_texture" type="Texture2D" setter="set_texture" getter="get_texture">
Texture used to set the strength of the rim lighting effect per-pixel. Multiplied by [member rim].
</member>
<member name="rim_tint" type="float" setter="set_rim_tint" getter="get_rim_tint" default="0.5">
The amount of to blend light and albedo color when rendering rim effect. If [code]0[/code] the light color is used, while [code]1[/code] means albedo color is used. An intermediate value generally works best.
</member>
<member name="roughness" type="float" setter="set_roughness" getter="get_roughness" default="1.0">
Surface reflection. A value of [code]0[/code] represents a perfect mirror while a value of [code]1[/code] completely blurs the reflection. See also [member metallic].
</member>
<member name="roughness_texture" type="Texture2D" setter="set_texture" getter="get_texture">
Texture used to control the roughness per-pixel. Multiplied by [member roughness].
</member>
<member name="roughness_texture_channel" type="int" setter="set_roughness_texture_channel" getter="get_roughness_texture_channel" enum="BaseMaterial3D.TextureChannel" default="0">
Specifies the channel of the [member roughness_texture] in which the roughness information is stored. This is useful when you store the information for multiple effects in a single texture. For example if you stored metallic in the red channel, roughness in the blue, and ambient occlusion in the green you could reduce the number of textures you use.
</member>
<member name="shading_mode" type="int" setter="set_shading_mode" getter="get_shading_mode" enum="BaseMaterial3D.ShadingMode" default="1">
Sets whether the shading takes place, per-pixel, 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.
</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.
</member>
<member name="specular_mode" type="int" setter="set_specular_mode" getter="get_specular_mode" enum="BaseMaterial3D.SpecularMode" default="0">
The method for rendering the specular blob.
[b]Note:[/b] [member specular_mode] only applies to the specular blob. It does not affect specular reflections from the sky, screen-space reflections, [VoxelGI], SDFGI or [ReflectionProbe]s. To disable reflections from these sources as well, set [member metallic_specular] to [code]0.0[/code] instead.
</member>
<member name="stencil_color" type="Color" setter="set_stencil_effect_color" getter="get_stencil_effect_color" default="Color(0, 0, 0, 1)" experimental="May be affected by future rendering pipeline changes.">
The primary color of the stencil effect.
</member>
<member name="stencil_compare" type="int" setter="set_stencil_compare" getter="get_stencil_compare" enum="BaseMaterial3D.StencilCompare" default="0" experimental="May be affected by future rendering pipeline changes.">
The comparison operator to use for stencil masking operations. See [enum StencilCompare].
</member>
<member name="stencil_flags" type="int" setter="set_stencil_flags" getter="get_stencil_flags" default="0" experimental="May be affected by future rendering pipeline changes.">
The flags dictating how the stencil operation behaves. See [enum StencilFlags].
</member>
<member name="stencil_mode" type="int" setter="set_stencil_mode" getter="get_stencil_mode" enum="BaseMaterial3D.StencilMode" default="0" experimental="May be affected by future rendering pipeline changes.">
The stencil effect mode. See [enum StencilMode].
</member>
<member name="stencil_outline_thickness" type="float" setter="set_stencil_effect_outline_thickness" getter="get_stencil_effect_outline_thickness" default="0.01" experimental="May be affected by future rendering pipeline changes.">
The outline thickness for [constant STENCIL_MODE_OUTLINE].
</member>
<member name="stencil_reference" type="int" setter="set_stencil_reference" getter="get_stencil_reference" default="1" experimental="May be affected by future rendering pipeline changes.">
The stencil reference value (0-255). Typically a power of 2.
</member>
<member name="subsurf_scatter_enabled" type="bool" setter="set_feature" getter="get_feature" default="false">
If [code]true[/code], subsurface scattering is enabled. Emulates light that penetrates an object's surface, is scattered, and then emerges. Subsurface scattering quality is controlled by [member ProjectSettings.rendering/environment/subsurface_scattering/subsurface_scattering_quality].
</member>
<member name="subsurf_scatter_skin_mode" type="bool" setter="set_flag" getter="get_flag" default="false">
If [code]true[/code], subsurface scattering will use a special mode optimized for the color and density of human skin, such as boosting the intensity of the red channel in subsurface scattering.
</member>
<member name="subsurf_scatter_strength" type="float" setter="set_subsurface_scattering_strength" getter="get_subsurface_scattering_strength" default="0.0">
The strength of the subsurface scattering effect. The depth of the effect is also controlled by [member ProjectSettings.rendering/environment/subsurface_scattering/subsurface_scattering_scale], which is set globally.
</member>
<member name="subsurf_scatter_texture" type="Texture2D" setter="set_texture" getter="get_texture">
Texture used to control the subsurface scattering strength. Stored in the red texture channel. Multiplied by [member subsurf_scatter_strength].
</member>
<member name="subsurf_scatter_transmittance_boost" type="float" setter="set_transmittance_boost" getter="get_transmittance_boost" default="0.0">
The intensity of the subsurface scattering transmittance effect.
</member>
<member name="subsurf_scatter_transmittance_color" type="Color" setter="set_transmittance_color" getter="get_transmittance_color" default="Color(1, 1, 1, 1)">
The color to multiply the subsurface scattering transmittance effect with. Ignored if [member subsurf_scatter_skin_mode] is [code]true[/code].
</member>
<member name="subsurf_scatter_transmittance_depth" type="float" setter="set_transmittance_depth" getter="get_transmittance_depth" default="0.1">
The depth of the subsurface scattering transmittance effect.
</member>
<member name="subsurf_scatter_transmittance_enabled" type="bool" setter="set_feature" getter="get_feature" default="false">
If [code]true[/code], enables subsurface scattering transmittance. Only effective if [member subsurf_scatter_enabled] is [code]true[/code]. See also [member backlight_enabled].
</member>
<member name="subsurf_scatter_transmittance_texture" type="Texture2D" setter="set_texture" getter="get_texture">
The texture to use for multiplying the intensity of the subsurface scattering transmittance intensity. See also [member subsurf_scatter_texture]. Ignored if [member subsurf_scatter_skin_mode] is [code]true[/code].
</member>
<member name="texture_filter" type="int" setter="set_texture_filter" getter="get_texture_filter" enum="BaseMaterial3D.TextureFilter" default="3">
Filter flags for the texture.
[b]Note:[/b] [member heightmap_texture] is always sampled with linear filtering, even if nearest-neighbor filtering is selected here. This is to ensure the heightmap effect looks as intended. If you need sharper height transitions between pixels, resize the heightmap texture in an image editor with nearest-neighbor filtering.
</member>
<member name="texture_repeat" type="bool" setter="set_flag" getter="get_flag" default="true">
If [code]true[/code], the texture repeats when exceeding the texture's size. See [constant FLAG_USE_TEXTURE_REPEAT].
</member>
<member name="transparency" type="int" setter="set_transparency" getter="get_transparency" enum="BaseMaterial3D.Transparency" default="0">
The material's transparency mode. Some transparency modes will disable shadow casting. Any transparency mode other than [constant TRANSPARENCY_DISABLED] has a greater performance impact compared to opaque rendering. See also [member blend_mode].
</member>
<member name="use_fov_override" type="bool" setter="set_flag" getter="get_flag" default="false">
If [code]true[/code] use [member fov_override] to override the [Camera3D]'s field of view angle.
</member>
<member name="use_particle_trails" type="bool" setter="set_flag" getter="get_flag" default="false">
If [code]true[/code], enables parts of the shader required for [GPUParticles3D] trails to function. This also requires using a mesh with appropriate skinning, such as [RibbonTrailMesh] or [TubeTrailMesh]. Enabling this feature outside of materials used in [GPUParticles3D] meshes will break material rendering.
</member>
<member name="use_point_size" type="bool" setter="set_flag" getter="get_flag" default="false">
If [code]true[/code], render point size can be changed.
[b]Note:[/b] This is only effective for objects whose geometry is point-based rather than triangle-based. See also [member point_size].
</member>
<member name="use_z_clip_scale" type="bool" setter="set_flag" getter="get_flag" default="false">
If [code]true[/code] use [member z_clip_scale] to scale the object being rendered towards the camera to avoid clipping into things like walls.
</member>
<member name="uv1_offset" type="Vector3" setter="set_uv1_offset" getter="get_uv1_offset" default="Vector3(0, 0, 0)">
How much to offset the [code]UV[/code] coordinates. This amount will be added to [code]UV[/code] in the vertex function. This can be used to offset a texture. The Z component is used when [member uv1_triplanar] is enabled, but it is not used anywhere else.
</member>
<member name="uv1_scale" type="Vector3" setter="set_uv1_scale" getter="get_uv1_scale" default="Vector3(1, 1, 1)">
How much to scale the [code]UV[/code] coordinates. This is multiplied by [code]UV[/code] in the vertex function. The Z component is used when [member uv1_triplanar] is enabled, but it is not used anywhere else.
</member>
<member name="uv1_triplanar" type="bool" setter="set_flag" getter="get_flag" default="false">
If [code]true[/code], instead of using [code]UV[/code] textures will use a triplanar texture lookup to determine how to apply textures. Triplanar uses the orientation of the object's surface to blend between texture coordinates. It reads from the source texture 3 times, once for each axis and then blends between the results based on how closely the pixel aligns with each axis. This is often used for natural features to get a realistic blend of materials. Because triplanar texturing requires many more texture reads per-pixel it is much slower than normal UV texturing. Additionally, because it is blending the texture between the three axes, it is unsuitable when you are trying to achieve crisp texturing.
</member>
<member name="uv1_triplanar_sharpness" type="float" setter="set_uv1_triplanar_blend_sharpness" getter="get_uv1_triplanar_blend_sharpness" default="1.0">
A lower number blends the texture more softly while a higher number blends the texture more sharply.
[b]Note:[/b] [member uv1_triplanar_sharpness] is clamped between [code]0.0[/code] and [code]150.0[/code] (inclusive) as values outside that range can look broken depending on the mesh.
</member>
<member name="uv1_world_triplanar" type="bool" setter="set_flag" getter="get_flag" default="false">
If [code]true[/code], triplanar mapping for [code]UV[/code] is calculated in world space rather than object local space. See also [member uv1_triplanar].
</member>
<member name="uv2_offset" type="Vector3" setter="set_uv2_offset" getter="get_uv2_offset" default="Vector3(0, 0, 0)">
How much to offset the [code]UV2[/code] coordinates. This amount will be added to [code]UV2[/code] in the vertex function. This can be used to offset a texture. The Z component is used when [member uv2_triplanar] is enabled, but it is not used anywhere else.
</member>
<member name="uv2_scale" type="Vector3" setter="set_uv2_scale" getter="get_uv2_scale" default="Vector3(1, 1, 1)">
How much to scale the [code]UV2[/code] coordinates. This is multiplied by [code]UV2[/code] in the vertex function. The Z component is used when [member uv2_triplanar] is enabled, but it is not used anywhere else.
</member>
<member name="uv2_triplanar" type="bool" setter="set_flag" getter="get_flag" default="false">
If [code]true[/code], instead of using [code]UV2[/code] textures will use a triplanar texture lookup to determine how to apply textures. Triplanar uses the orientation of the object's surface to blend between texture coordinates. It reads from the source texture 3 times, once for each axis and then blends between the results based on how closely the pixel aligns with each axis. This is often used for natural features to get a realistic blend of materials. Because triplanar texturing requires many more texture reads per-pixel it is much slower than normal UV texturing. Additionally, because it is blending the texture between the three axes, it is unsuitable when you are trying to achieve crisp texturing.
</member>
<member name="uv2_triplanar_sharpness" type="float" setter="set_uv2_triplanar_blend_sharpness" getter="get_uv2_triplanar_blend_sharpness" default="1.0">
A lower number blends the texture more softly while a higher number blends the texture more sharply.
[b]Note:[/b] [member uv2_triplanar_sharpness] is clamped between [code]0.0[/code] and [code]150.0[/code] (inclusive) as values outside that range can look broken depending on the mesh.
</member>
<member name="uv2_world_triplanar" type="bool" setter="set_flag" getter="get_flag" default="false">
If [code]true[/code], triplanar mapping for [code]UV2[/code] is calculated in world space rather than object local space. See also [member uv2_triplanar].
</member>
<member name="vertex_color_is_srgb" type="bool" setter="set_flag" getter="get_flag" default="false">
If [code]true[/code], vertex colors are considered to be stored in sRGB color space and are converted to linear color space during rendering. If [code]false[/code], vertex colors are considered to be stored in linear color space and are rendered as-is. See also [member albedo_texture_force_srgb].
[b]Note:[/b] Only effective when using the Forward+ and Mobile rendering methods, not Compatibility.
</member>
<member name="vertex_color_use_as_albedo" type="bool" setter="set_flag" getter="get_flag" default="false">
If [code]true[/code], the vertex color is used as albedo color.
</member>
<member name="z_clip_scale" type="float" setter="set_z_clip_scale" getter="get_z_clip_scale" default="1.0">
Scales the object being rendered towards the camera to avoid clipping into things like walls. This is intended to be used for objects that are fixed with respect to the camera like player arms, tools, etc. Lighting and shadows will continue to work correctly when this setting is adjusted, but screen-space effects like SSAO and SSR may break with lower scales. Therefore, try to keep this setting as close to [code]1.0[/code] as possible.
</member>
</members>
<constants>
<constant name="TEXTURE_ALBEDO" value="0" enum="TextureParam">
Texture specifying per-pixel color.
</constant>
<constant name="TEXTURE_METALLIC" value="1" enum="TextureParam">
Texture specifying per-pixel metallic value.
</constant>
<constant name="TEXTURE_ROUGHNESS" value="2" enum="TextureParam">
Texture specifying per-pixel roughness value.
</constant>
<constant name="TEXTURE_EMISSION" value="3" enum="TextureParam">
Texture specifying per-pixel emission color.
</constant>
<constant name="TEXTURE_NORMAL" value="4" enum="TextureParam">
Texture specifying per-pixel normal vector.
</constant>
<constant name="TEXTURE_BENT_NORMAL" value="18" enum="TextureParam">
Texture specifying per-pixel bent normal vector.
</constant>
<constant name="TEXTURE_RIM" value="5" enum="TextureParam">
Texture specifying per-pixel rim value.
</constant>
<constant name="TEXTURE_CLEARCOAT" value="6" enum="TextureParam">
Texture specifying per-pixel clearcoat value.
</constant>
<constant name="TEXTURE_FLOWMAP" value="7" enum="TextureParam">
Texture specifying per-pixel flowmap direction for use with [member anisotropy].
</constant>
<constant name="TEXTURE_AMBIENT_OCCLUSION" value="8" enum="TextureParam">
Texture specifying per-pixel ambient occlusion value.
</constant>
<constant name="TEXTURE_HEIGHTMAP" value="9" enum="TextureParam">
Texture specifying per-pixel height.
</constant>
<constant name="TEXTURE_SUBSURFACE_SCATTERING" value="10" enum="TextureParam">
Texture specifying per-pixel subsurface scattering.
</constant>
<constant name="TEXTURE_SUBSURFACE_TRANSMITTANCE" value="11" enum="TextureParam">
Texture specifying per-pixel transmittance for subsurface scattering.
</constant>
<constant name="TEXTURE_BACKLIGHT" value="12" enum="TextureParam">
Texture specifying per-pixel backlight color.
</constant>
<constant name="TEXTURE_REFRACTION" value="13" enum="TextureParam">
Texture specifying per-pixel refraction strength.
</constant>
<constant name="TEXTURE_DETAIL_MASK" value="14" enum="TextureParam">
Texture specifying per-pixel detail mask blending value.
</constant>
<constant name="TEXTURE_DETAIL_ALBEDO" value="15" enum="TextureParam">
Texture specifying per-pixel detail color.
</constant>
<constant name="TEXTURE_DETAIL_NORMAL" value="16" enum="TextureParam">
Texture specifying per-pixel detail normal.
</constant>
<constant name="TEXTURE_ORM" value="17" enum="TextureParam">
Texture holding ambient occlusion, roughness, and metallic.
</constant>
<constant name="TEXTURE_MAX" value="19" enum="TextureParam">
Represents the size of the [enum TextureParam] enum.
</constant>
<constant name="TEXTURE_FILTER_NEAREST" value="0" enum="TextureFilter">
The texture filter reads from the nearest pixel only. This makes the texture look pixelated from up close, and grainy from a distance (due to mipmaps not being sampled).
</constant>
<constant name="TEXTURE_FILTER_LINEAR" value="1" enum="TextureFilter">
The texture filter blends between the nearest 4 pixels. This makes the texture look smooth from up close, and grainy from a distance (due to mipmaps not being sampled).
</constant>
<constant name="TEXTURE_FILTER_NEAREST_WITH_MIPMAPS" value="2" enum="TextureFilter">
The texture filter reads from the nearest pixel and blends between the nearest 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]). This makes the texture look pixelated from up close, and smooth from a distance.
</constant>
<constant name="TEXTURE_FILTER_LINEAR_WITH_MIPMAPS" value="3" enum="TextureFilter">
The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]). This makes the texture look smooth from up close, and smooth from a distance.
</constant>
<constant name="TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC" value="4" enum="TextureFilter">
The texture filter reads from the nearest pixel and blends between 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]) based on the angle between the surface and the camera view. This makes the texture look pixelated from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level].
</constant>
<constant name="TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC" value="5" enum="TextureFilter">
The texture filter blends between the nearest 4 pixels and blends between 2 mipmaps (or uses the nearest mipmap if [member ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter] is [code]true[/code]) based on the angle between the surface and the camera view. This makes the texture look smooth from up close, and smooth from a distance. Anisotropic filtering improves texture quality on surfaces that are almost in line with the camera, but is slightly slower. The anisotropic filtering level can be changed by adjusting [member ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level].
</constant>
<constant name="TEXTURE_FILTER_MAX" value="6" enum="TextureFilter">
Represents the size of the [enum TextureFilter] enum.
</constant>
<constant name="DETAIL_UV_1" value="0" enum="DetailUV">
Use [code]UV[/code] with the detail texture.
</constant>
<constant name="DETAIL_UV_2" value="1" enum="DetailUV">
Use [code]UV2[/code] with the detail texture.
</constant>
<constant name="TRANSPARENCY_DISABLED" value="0" enum="Transparency">
The material will not use transparency. This is the fastest to render.
</constant>
<constant name="TRANSPARENCY_ALPHA" value="1" enum="Transparency">
The material will use the texture's alpha values for transparency. This is the slowest to render, and disables shadow casting.
</constant>
<constant name="TRANSPARENCY_ALPHA_SCISSOR" value="2" enum="Transparency" keywords="TRANSPARENCY_ALPHA_TEST">
The material will cut off all values below a threshold, the rest will remain opaque. The opaque portions will be rendered in the depth prepass. This is faster to render than alpha blending, but slower than opaque rendering. This also supports casting shadows.
</constant>
<constant name="TRANSPARENCY_ALPHA_HASH" value="3" enum="Transparency">
The material will cut off all values below a spatially-deterministic threshold, the rest will remain opaque. This is faster to render than alpha blending, but slower than opaque rendering. This also supports casting shadows. Alpha hashing is suited for hair rendering.
</constant>
<constant name="TRANSPARENCY_ALPHA_DEPTH_PRE_PASS" value="4" enum="Transparency">
The material will use the texture's alpha value for transparency, but will discard fragments with an alpha of less than 0.99 during the depth prepass and fragments with an alpha less than 0.1 during the shadow pass. This also supports casting shadows.
</constant>
<constant name="TRANSPARENCY_MAX" value="5" enum="Transparency">
Represents the size of the [enum Transparency] enum.
</constant>
<constant name="SHADING_MODE_UNSHADED" value="0" enum="ShadingMode">
The object will not receive shadows. This is the fastest to render, but it disables all interactions with lights.
</constant>
<constant name="SHADING_MODE_PER_PIXEL" value="1" enum="ShadingMode">
The object will be shaded per pixel. Useful for realistic shading 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.
</constant>
<constant name="SHADING_MODE_MAX" value="3" enum="ShadingMode">
Represents the size of the [enum ShadingMode] enum.
</constant>
<constant name="FEATURE_EMISSION" value="0" enum="Feature">
Constant for setting [member emission_enabled].
</constant>
<constant name="FEATURE_NORMAL_MAPPING" value="1" enum="Feature">
Constant for setting [member normal_enabled].
</constant>
<constant name="FEATURE_RIM" value="2" enum="Feature">
Constant for setting [member rim_enabled].
</constant>
<constant name="FEATURE_CLEARCOAT" value="3" enum="Feature">
Constant for setting [member clearcoat_enabled].
</constant>
<constant name="FEATURE_ANISOTROPY" value="4" enum="Feature">
Constant for setting [member anisotropy_enabled].
</constant>
<constant name="FEATURE_AMBIENT_OCCLUSION" value="5" enum="Feature">
Constant for setting [member ao_enabled].
</constant>
<constant name="FEATURE_HEIGHT_MAPPING" value="6" enum="Feature">
Constant for setting [member heightmap_enabled].
</constant>
<constant name="FEATURE_SUBSURFACE_SCATTERING" value="7" enum="Feature">
Constant for setting [member subsurf_scatter_enabled].
</constant>
<constant name="FEATURE_SUBSURFACE_TRANSMITTANCE" value="8" enum="Feature">
Constant for setting [member subsurf_scatter_transmittance_enabled].
</constant>
<constant name="FEATURE_BACKLIGHT" value="9" enum="Feature">
Constant for setting [member backlight_enabled].
</constant>
<constant name="FEATURE_REFRACTION" value="10" enum="Feature">
Constant for setting [member refraction_enabled].
</constant>
<constant name="FEATURE_DETAIL" value="11" enum="Feature">
Constant for setting [member detail_enabled].
</constant>
<constant name="FEATURE_BENT_NORMAL_MAPPING" value="12" enum="Feature">
Constant for setting [member bent_normal_enabled].
</constant>
<constant name="FEATURE_MAX" value="13" enum="Feature">
Represents the size of the [enum Feature] enum.
</constant>
<constant name="BLEND_MODE_MIX" value="0" enum="BlendMode">
Default blend mode. The color of the object is blended over the background based on the object's alpha value.
</constant>
<constant name="BLEND_MODE_ADD" value="1" enum="BlendMode">
The color of the object is added to the background.
</constant>
<constant name="BLEND_MODE_SUB" value="2" enum="BlendMode">
The color of the object is subtracted from the background.
</constant>
<constant name="BLEND_MODE_MUL" value="3" enum="BlendMode">
The color of the object is multiplied by the background.
</constant>
<constant name="BLEND_MODE_PREMULT_ALPHA" value="4" enum="BlendMode">
The color of the object is added to the background and the alpha channel is used to mask out the background. This is effectively a hybrid of the blend mix and add modes, useful for effects like fire where you want the flame to add but the smoke to mix. By default, this works with unshaded materials using premultiplied textures. For shaded materials, use the [code]PREMUL_ALPHA_FACTOR[/code] built-in so that lighting can be modulated as well.
</constant>
<constant name="ALPHA_ANTIALIASING_OFF" value="0" enum="AlphaAntiAliasing">
Disables Alpha AntiAliasing for the material.
</constant>
<constant name="ALPHA_ANTIALIASING_ALPHA_TO_COVERAGE" value="1" enum="AlphaAntiAliasing">
Enables AlphaToCoverage. Alpha values in the material are passed to the AntiAliasing sample mask.
</constant>
<constant name="ALPHA_ANTIALIASING_ALPHA_TO_COVERAGE_AND_TO_ONE" value="2" enum="AlphaAntiAliasing">
Enables AlphaToCoverage and forces all non-zero alpha values to [code]1[/code]. Alpha values in the material are passed to the AntiAliasing sample mask.
</constant>
<constant name="DEPTH_DRAW_OPAQUE_ONLY" value="0" enum="DepthDrawMode">
Default depth draw mode. Depth is drawn only for opaque objects during the opaque prepass (if any) and during the opaque pass.
</constant>
<constant name="DEPTH_DRAW_ALWAYS" value="1" enum="DepthDrawMode">
Objects will write to depth during the opaque and the transparent passes. Transparent objects that are close to the camera may obscure other transparent objects behind them.
[b]Note:[/b] This does not influence whether transparent objects are included in the depth prepass or not. For that, see [enum Transparency].
</constant>
<constant name="DEPTH_DRAW_DISABLED" value="2" enum="DepthDrawMode">
Objects will not write their depth to the depth buffer, even during the depth prepass (if enabled).
</constant>
<constant name="DEPTH_TEST_DEFAULT" value="0" enum="DepthTest">
Depth test will discard the pixel if it is behind other pixels.
</constant>
<constant name="DEPTH_TEST_INVERTED" value="1" enum="DepthTest">
Depth test will discard the pixel if it is in front of other pixels. Useful for stencil effects.
</constant>
<constant name="CULL_BACK" value="0" enum="CullMode">
Default cull mode. The back of the object is culled when not visible. Back face triangles will be culled when facing the camera. This results in only the front side of triangles being drawn. For closed-surface meshes, this means that only the exterior of the mesh will be visible.
</constant>
<constant name="CULL_FRONT" value="1" enum="CullMode">
Front face triangles will be culled when facing the camera. This results in only the back side of triangles being drawn. For closed-surface meshes, this means that the interior of the mesh will be drawn instead of the exterior.
</constant>
<constant name="CULL_DISABLED" value="2" enum="CullMode">
No face culling is performed; both the front face and back face will be visible.
</constant>
<constant name="FLAG_DISABLE_DEPTH_TEST" value="0" enum="Flags">
Disables the depth test, so this object is drawn on top of all others drawn before it. This puts the object in the transparent draw pass where it is sorted based on distance to camera. Objects drawn after it in the draw order may cover it. This also disables writing to depth.
</constant>
<constant name="FLAG_ALBEDO_FROM_VERTEX_COLOR" value="1" enum="Flags">
Set [code]ALBEDO[/code] to the per-vertex color specified in the mesh.
</constant>
<constant name="FLAG_SRGB_VERTEX_COLOR" value="2" enum="Flags">
Vertex colors are considered to be stored in sRGB color space and are converted to linear color space during rendering. See also [member vertex_color_is_srgb].
[b]Note:[/b] Only effective when using the Forward+ and Mobile rendering methods.
</constant>
<constant name="FLAG_USE_POINT_SIZE" value="3" enum="Flags">
Uses point size to alter the size of primitive points. Also changes the albedo texture lookup to use [code]POINT_COORD[/code] instead of [code]UV[/code].
</constant>
<constant name="FLAG_FIXED_SIZE" value="4" enum="Flags">
Object is scaled by depth so that it always appears the same size on screen.
</constant>
<constant name="FLAG_BILLBOARD_KEEP_SCALE" value="5" enum="Flags">
Shader will keep the scale set for the mesh. Otherwise the scale is lost when billboarding. Only applies when [member billboard_mode] is [constant BILLBOARD_ENABLED].
</constant>
<constant name="FLAG_UV1_USE_TRIPLANAR" value="6" enum="Flags">
Use triplanar texture lookup for all texture lookups that would normally use [code]UV[/code].
</constant>
<constant name="FLAG_UV2_USE_TRIPLANAR" value="7" enum="Flags">
Use triplanar texture lookup for all texture lookups that would normally use [code]UV2[/code].
</constant>
<constant name="FLAG_UV1_USE_WORLD_TRIPLANAR" value="8" enum="Flags">
Use triplanar texture lookup for all texture lookups that would normally use [code]UV[/code].
</constant>
<constant name="FLAG_UV2_USE_WORLD_TRIPLANAR" value="9" enum="Flags">
Use triplanar texture lookup for all texture lookups that would normally use [code]UV2[/code].
</constant>
<constant name="FLAG_AO_ON_UV2" value="10" enum="Flags">
Use [code]UV2[/code] coordinates to look up from the [member ao_texture].
</constant>
<constant name="FLAG_EMISSION_ON_UV2" value="11" enum="Flags">
Use [code]UV2[/code] coordinates to look up from the [member emission_texture].
</constant>
<constant name="FLAG_ALBEDO_TEXTURE_FORCE_SRGB" value="12" enum="Flags">
Forces the shader to convert albedo from sRGB space to linear space. See also [member albedo_texture_force_srgb].
</constant>
<constant name="FLAG_DONT_RECEIVE_SHADOWS" value="13" enum="Flags">
Disables receiving shadows from other objects.
</constant>
<constant name="FLAG_DISABLE_AMBIENT_LIGHT" value="14" enum="Flags">
Disables receiving ambient light.
</constant>
<constant name="FLAG_USE_SHADOW_TO_OPACITY" value="15" enum="Flags">
Enables the shadow to opacity feature.
</constant>
<constant name="FLAG_USE_TEXTURE_REPEAT" value="16" enum="Flags">
Enables the texture to repeat when UV coordinates are outside the 0-1 range. If using one of the linear filtering modes, this can result in artifacts at the edges of a texture when the sampler filters across the edges of the texture.
</constant>
<constant name="FLAG_INVERT_HEIGHTMAP" value="17" enum="Flags">
Invert values read from a depth texture to convert them to height values (heightmap).
</constant>
<constant name="FLAG_SUBSURFACE_MODE_SKIN" value="18" enum="Flags">
Enables the skin mode for subsurface scattering which is used to improve the look of subsurface scattering when used for human skin.
</constant>
<constant name="FLAG_PARTICLE_TRAILS_MODE" value="19" enum="Flags">
Enables parts of the shader required for [GPUParticles3D] trails to function. This also requires using a mesh with appropriate skinning, such as [RibbonTrailMesh] or [TubeTrailMesh]. Enabling this feature outside of materials used in [GPUParticles3D] meshes will break material rendering.
</constant>
<constant name="FLAG_ALBEDO_TEXTURE_MSDF" value="20" enum="Flags">
Enables multichannel signed distance field rendering shader.
</constant>
<constant name="FLAG_DISABLE_FOG" value="21" enum="Flags">
Disables receiving depth-based or volumetric fog.
</constant>
<constant name="FLAG_DISABLE_SPECULAR_OCCLUSION" value="22" enum="Flags">
Disables specular occlusion.
</constant>
<constant name="FLAG_USE_Z_CLIP_SCALE" value="23" enum="Flags">
Enables using [member z_clip_scale].
</constant>
<constant name="FLAG_USE_FOV_OVERRIDE" value="24" enum="Flags">
Enables using [member fov_override].
</constant>
<constant name="FLAG_MAX" value="25" enum="Flags">
Represents the size of the [enum Flags] enum.
</constant>
<constant name="DIFFUSE_BURLEY" value="0" enum="DiffuseMode">
Default diffuse scattering algorithm.
</constant>
<constant name="DIFFUSE_LAMBERT" value="1" enum="DiffuseMode">
Diffuse scattering ignores roughness.
</constant>
<constant name="DIFFUSE_LAMBERT_WRAP" value="2" enum="DiffuseMode">
Extends Lambert to cover more than 90 degrees when roughness increases.
</constant>
<constant name="DIFFUSE_TOON" value="3" enum="DiffuseMode">
Uses a hard cut for lighting, with smoothing affected by roughness.
</constant>
<constant name="SPECULAR_SCHLICK_GGX" value="0" enum="SpecularMode">
Default specular blob.
[b]Note:[/b] Forward+ uses multiscattering for more accurate reflections, although the impact of multiscattering is more noticeable on rough metallic surfaces than on smooth, non-metallic surfaces.
[b]Note:[/b] Mobile and Compatibility don't perform multiscattering for performance reasons. Instead, they perform single scattering, which means rough metallic surfaces may look slightly darker than intended.
</constant>
<constant name="SPECULAR_TOON" value="1" enum="SpecularMode">
Toon blob which changes size based on roughness.
</constant>
<constant name="SPECULAR_DISABLED" value="2" enum="SpecularMode">
No specular blob. This is slightly faster to render than other specular modes.
</constant>
<constant name="BILLBOARD_DISABLED" value="0" enum="BillboardMode">
Billboard mode is disabled.
</constant>
<constant name="BILLBOARD_ENABLED" value="1" enum="BillboardMode">
The object's Z axis will always face the camera.
</constant>
<constant name="BILLBOARD_FIXED_Y" value="2" enum="BillboardMode">
The object's X axis will always face the camera.
</constant>
<constant name="BILLBOARD_PARTICLES" value="3" enum="BillboardMode">
Used for particle systems when assigned to [GPUParticles3D] and [CPUParticles3D] nodes (flipbook animation). Enables [code]particles_anim_*[/code] properties.
The [member ParticleProcessMaterial.anim_speed_min] or [member CPUParticles3D.anim_speed_min] should also be set to a value bigger than zero for the animation to play.
</constant>
<constant name="TEXTURE_CHANNEL_RED" value="0" enum="TextureChannel">
Used to read from the red channel of a texture.
</constant>
<constant name="TEXTURE_CHANNEL_GREEN" value="1" enum="TextureChannel">
Used to read from the green channel of a texture.
</constant>
<constant name="TEXTURE_CHANNEL_BLUE" value="2" enum="TextureChannel">
Used to read from the blue channel of a texture.
</constant>
<constant name="TEXTURE_CHANNEL_ALPHA" value="3" enum="TextureChannel">
Used to read from the alpha channel of a texture.
</constant>
<constant name="TEXTURE_CHANNEL_GRAYSCALE" value="4" enum="TextureChannel">
Used to read from the linear (non-perceptual) average of the red, green and blue channels of a texture.
</constant>
<constant name="EMISSION_OP_ADD" value="0" enum="EmissionOperator">
Adds the emission color to the color from the emission texture.
</constant>
<constant name="EMISSION_OP_MULTIPLY" value="1" enum="EmissionOperator">
Multiplies the emission color by the color from the emission texture.
</constant>
<constant name="DISTANCE_FADE_DISABLED" value="0" enum="DistanceFadeMode">
Do not use distance fade.
</constant>
<constant name="DISTANCE_FADE_PIXEL_ALPHA" value="1" enum="DistanceFadeMode">
Smoothly fades the object out based on each pixel's distance from the camera using the alpha channel.
</constant>
<constant name="DISTANCE_FADE_PIXEL_DITHER" value="2" enum="DistanceFadeMode">
Smoothly fades the object out based on each pixel's distance from the camera using a dithering approach. Dithering discards pixels based on a set pattern to smoothly fade without enabling transparency. On certain hardware, this can be faster than [constant DISTANCE_FADE_PIXEL_ALPHA].
</constant>
<constant name="DISTANCE_FADE_OBJECT_DITHER" value="3" enum="DistanceFadeMode">
Smoothly fades the object out based on the object's distance from the camera using a dithering approach. Dithering discards pixels based on a set pattern to smoothly fade without enabling transparency. On certain hardware, this can be faster than [constant DISTANCE_FADE_PIXEL_ALPHA] and [constant DISTANCE_FADE_PIXEL_DITHER].
</constant>
<constant name="STENCIL_MODE_DISABLED" value="0" enum="StencilMode">
Disables stencil operations.
</constant>
<constant name="STENCIL_MODE_OUTLINE" value="1" enum="StencilMode">
Stencil preset which applies an outline to the object.
[b]Note:[/b] Requires a [member Material.next_pass] material which will be automatically applied. Any manual changes made to [member Material.next_pass] will be lost when the stencil properties are modified or the scene is reloaded. To safely apply a [member Material.next_pass] material on a material that uses stencil presets, use [member GeometryInstance3D.material_overlay] instead.
</constant>
<constant name="STENCIL_MODE_XRAY" value="2" enum="StencilMode">
Stencil preset which shows a silhouette of the object behind walls.
[b]Note:[/b] Requires a [member Material.next_pass] material which will be automatically applied. Any manual changes made to [member Material.next_pass] will be lost when the stencil properties are modified or the scene is reloaded. To safely apply a [member Material.next_pass] material on a material that uses stencil presets, use [member GeometryInstance3D.material_overlay] instead.
</constant>
<constant name="STENCIL_MODE_CUSTOM" value="3" enum="StencilMode">
Enables stencil operations without a preset.
</constant>
<constant name="STENCIL_FLAG_READ" value="1" enum="StencilFlags">
The material will only be rendered where it passes a stencil comparison with existing stencil buffer values. See [enum StencilCompare].
</constant>
<constant name="STENCIL_FLAG_WRITE" value="2" enum="StencilFlags">
The material will write the reference value to the stencil buffer where it passes the depth test.
</constant>
<constant name="STENCIL_FLAG_WRITE_DEPTH_FAIL" value="4" enum="StencilFlags">
The material will write the reference value to the stencil buffer where it fails the depth test.
</constant>
<constant name="STENCIL_COMPARE_ALWAYS" value="0" enum="StencilCompare">
Always passes the stencil test.
</constant>
<constant name="STENCIL_COMPARE_LESS" value="1" enum="StencilCompare">
Passes the stencil test when the reference value is less than the existing stencil value.
</constant>
<constant name="STENCIL_COMPARE_EQUAL" value="2" enum="StencilCompare">
Passes the stencil test when the reference value is equal to the existing stencil value.
</constant>
<constant name="STENCIL_COMPARE_LESS_OR_EQUAL" value="3" enum="StencilCompare">
Passes the stencil test when the reference value is less than or equal to the existing stencil value.
</constant>
<constant name="STENCIL_COMPARE_GREATER" value="4" enum="StencilCompare">
Passes the stencil test when the reference value is greater than the existing stencil value.
</constant>
<constant name="STENCIL_COMPARE_NOT_EQUAL" value="5" enum="StencilCompare">
Passes the stencil test when the reference value is not equal to the existing stencil value.
</constant>
<constant name="STENCIL_COMPARE_GREATER_OR_EQUAL" value="6" enum="StencilCompare">
Passes the stencil test when the reference value is greater than or equal to the existing stencil value.
</constant>
</constants>
</class>

546
doc/classes/Basis.xml Normal file
View File

@@ -0,0 +1,546 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="Basis" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
A 3×3 matrix for representing 3D rotation and scale.
</brief_description>
<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.
- [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.
</description>
<tutorials>
<link title="Math documentation index">$DOCS_URL/tutorials/math/index.html</link>
<link title="Matrices and transforms">$DOCS_URL/tutorials/math/matrices_and_transforms.html</link>
<link title="Using 3D transforms">$DOCS_URL/tutorials/3d/using_transforms.html</link>
<link title="Matrix Transform Demo">https://godotengine.org/asset-library/asset/2787</link>
<link title="3D Platformer Demo">https://godotengine.org/asset-library/asset/2748</link>
<link title="3D Voxel Demo">https://godotengine.org/asset-library/asset/2755</link>
<link title="2.5D Game Demo">https://godotengine.org/asset-library/asset/2783</link>
</tutorials>
<constructors>
<constructor name="Basis">
<return type="Basis" />
<description>
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">
<return type="Basis" />
<param index="0" name="from" type="Basis" />
<description>
Constructs a [Basis] as a copy of the given [Basis].
</description>
</constructor>
<constructor name="Basis">
<return type="Basis" />
<param index="0" name="axis" type="Vector3" />
<param index="1" name="angle" type="float" />
<description>
Constructs a [Basis] that only represents rotation, rotated around the [param axis] by the given [param angle], in radians. The axis must be a normalized vector.
[b]Note:[/b] This is the same as using [method rotated] on the [constant IDENTITY] basis. With more than one angle consider using [method from_euler], instead.
</description>
</constructor>
<constructor name="Basis">
<return type="Basis" />
<param index="0" name="from" type="Quaternion" />
<description>
Constructs a [Basis] that only represents rotation from the given [Quaternion].
[b]Note:[/b] Quaternions [i]only[/i] store rotation, not scale. Because of this, conversions from [Basis] to [Quaternion] cannot always be reversed.
</description>
</constructor>
<constructor name="Basis">
<return type="Basis" />
<param index="0" name="x_axis" type="Vector3" />
<param index="1" name="y_axis" type="Vector3" />
<param index="2" name="z_axis" type="Vector3" />
<description>
Constructs a [Basis] from 3 axis vectors. These are the columns of the basis matrix.
</description>
</constructor>
</constructors>
<methods>
<method name="determinant" qualifiers="const">
<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.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>
</method>
<method name="from_euler" qualifiers="static">
<return type="Basis" />
<param index="0" name="euler" type="Vector3" />
<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.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.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)
[/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.
</description>
</method>
<method name="from_scale" qualifiers="static">
<return type="Basis" />
<param index="0" name="scale" type="Vector3" />
<description>
Constructs a new [Basis] that only represents scale, with no rotation or shear, from the given [param scale] vector.
[codeblocks]
[gdscript]
var my_basis = Basis.from_scale(Vector3(2, 4, 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)
[/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].
</description>
</method>
<method name="get_euler" qualifiers="const">
<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. 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>
</method>
<method name="get_rotation_quaternion" qualifiers="const">
<return type="Quaternion" />
<description>
Returns this basis's rotation as a [Quaternion].
[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 value is the scaling factor. It is not affected by rotation.
[codeblocks]
[gdscript]
var my_basis = Basis(
Vector3(2, 0, 0),
Vector3(0, 4, 0),
Vector3(0, 0, 8)
)
# Rotating the Basis in any way preserves its scale.
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.0, 4.0, 8.0)
[/gdscript]
[csharp]
var myBasis = new Basis(
Vector3(2.0f, 0.0f, 0.0f),
Vector3(0.0f, 4.0f, 0.0f),
Vector3(0.0f, 0.0f, 8.0f)
);
// Rotating the Basis in any way preserves its scale.
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)
[/csharp]
[/codeblocks]
[b]Note:[/b] If the value returned by [method determinant] is negative, the scale is also negative.
</description>
</method>
<method name="inverse" qualifiers="const">
<return type="Basis" />
<description>
Returns the [url=https://en.wikipedia.org/wiki/Invertible_matrix]inverse of this basis's matrix[/url].
</description>
</method>
<method name="is_conformal" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if this basis is conformal. A conformal basis is both [i]orthogonal[/i] (the axes are perpendicular to each other) and [i]uniform[/i] (the axes share the same length). This method can be especially useful during physics calculations.
</description>
</method>
<method name="is_equal_approx" qualifiers="const">
<return type="bool" />
<param index="0" name="b" type="Basis" />
<description>
Returns [code]true[/code] if this basis and [param b] are approximately equal, by calling [method @GlobalScope.is_equal_approx] on all vector components.
</description>
</method>
<method name="is_finite" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if this basis is finite, by calling [method @GlobalScope.is_finite] on all vector components.
</description>
</method>
<method name="looking_at" qualifiers="static">
<return type="Basis" />
<param index="0" name="target" type="Vector3" />
<param index="1" name="up" type="Vector3" default="Vector3(0, 1, 0)" />
<param index="2" name="use_model_front" type="bool" default="false" />
<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 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.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]
# Rotate this Node3D every frame.
func _process(delta):
basis = basis.rotated(Vector3.UP, TAU * delta)
basis = basis.rotated(Vector3.RIGHT, TAU * delta)
basis = basis.orthonormalized()
[/gdscript]
[csharp]
// Rotate this Node3D every frame.
public override void _Process(double delta)
{
Basis = Basis.Rotated(Vector3.Up, Mathf.Tau * (float)delta)
.Rotated(Vector3.Right, Mathf.Tau * (float)delta)
.Orthonormalized();
}
[/csharp]
[/codeblocks]
</description>
</method>
<method name="rotated" qualifiers="const">
<return type="Basis" />
<param index="0" name="axis" type="Vector3" />
<param index="1" name="angle" type="float" />
<description>
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
var angle = TAU / 2
my_basis = my_basis.rotated(Vector3.UP, angle) # Rotate around the up axis (yaw).
my_basis = my_basis.rotated(Vector3.RIGHT, angle) # Rotate around the right axis (pitch).
my_basis = my_basis.rotated(Vector3.BACK, angle) # Rotate around the back axis (roll).
[/gdscript]
[csharp]
var myBasis = Basis.Identity;
var angle = Mathf.Tau / 2.0f;
myBasis = myBasis.Rotated(Vector3.Up, angle); // Rotate around the up axis (yaw).
myBasis = myBasis.Rotated(Vector3.Right, angle); // Rotate around the right axis (pitch).
myBasis = myBasis.Rotated(Vector3.Back, angle); // Rotate around the back axis (roll).
[/csharp]
[/codeblocks]
</description>
</method>
<method name="scaled" qualifiers="const">
<return type="Basis" />
<param index="0" name="scale" type="Vector3" />
<description>
Returns this basis with each axis's components scaled by the given [param scale]'s components.
The basis matrix's rows are multiplied by [param scale]'s components. This operation is a global scale (relative to the parent).
[codeblocks]
[gdscript]
var my_basis = Basis(
Vector3(1, 1, 1),
Vector3(2, 2, 2),
Vector3(3, 3, 3)
)
my_basis = my_basis.scaled(Vector3(0, 2, -2))
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(
new Vector3(1.0f, 1.0f, 1.0f),
new Vector3(2.0f, 2.0f, 2.0f),
new Vector3(3.0f, 3.0f, 3.0f)
);
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)
[/csharp]
[/codeblocks]
</description>
</method>
<method name="scaled_local" qualifiers="const">
<return type="Basis" />
<param index="0" name="scale" type="Vector3" />
<description>
Returns this basis with each axis scaled by the corresponding component in the given [param scale].
The basis matrix's columns are multiplied by [param scale]'s components. This operation is a local scale (relative to self).
[codeblocks]
[gdscript]
var my_basis = Basis(
Vector3(1, 1, 1),
Vector3(2, 2, 2),
Vector3(3, 3, 3)
)
my_basis = my_basis.scaled_local(Vector3(0, 2, -2))
print(my_basis.x) # Prints (0.0, 0.0, 0.0)
print(my_basis.y) # Prints (4.0, 4.0, 4.0)
print(my_basis.z) # Prints (-6.0, -6.0, -6.0)
[/gdscript]
[csharp]
var myBasis = new Basis(
new Vector3(1.0f, 1.0f, 1.0f),
new Vector3(2.0f, 2.0f, 2.0f),
new Vector3(3.0f, 3.0f, 3.0f)
);
myBasis = myBasis.ScaledLocal(new Vector3(0.0f, 2.0f, -2.0f));
GD.Print(myBasis.X); // Prints (0, 0, 0)
GD.Print(myBasis.Y); // Prints (4, 4, 4)
GD.Print(myBasis.Z); // Prints (-6, -6, -6)
[/csharp]
[/codeblocks]
</description>
</method>
<method name="slerp" qualifiers="const" keywords="interpolate">
<return type="Basis" />
<param index="0" name="to" type="Basis" />
<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]:
[codeblock]
var start_basis = Basis.IDENTITY
var target_basis = Basis.IDENTITY.rotated(Vector3.UP, TAU / 2)
func _ready():
create_tween().tween_method(interpolate, 0.0, 1.0, 5.0).set_trans(Tween.TRANS_EXPO)
func interpolate(weight):
basis = start_basis.slerp(target_basis, weight)
[/codeblock]
</description>
</method>
<method name="tdotx" qualifiers="const">
<return type="float" />
<param index="0" name="with" type="Vector3" />
<description>
Returns the transposed dot product between [param with] and the [member x] axis (see [method transposed]).
This is equivalent to [code]basis.x.dot(vector)[/code].
</description>
</method>
<method name="tdoty" qualifiers="const">
<return type="float" />
<param index="0" name="with" type="Vector3" />
<description>
Returns the transposed dot product between [param with] and the [member y] axis (see [method transposed]).
This is equivalent to [code]basis.y.dot(vector)[/code].
</description>
</method>
<method name="tdotz" qualifiers="const">
<return type="float" />
<param index="0" name="with" type="Vector3" />
<description>
Returns the transposed dot product between [param with] and the [member z] axis (see [method transposed]).
This is equivalent to [code]basis.z.dot(vector)[/code].
</description>
</method>
<method name="transposed" qualifiers="const">
<return type="Basis" />
<description>
Returns the transposed version of this basis. This turns the basis matrix's columns into rows, and its rows into columns.
[codeblocks]
[gdscript]
var my_basis = Basis(
Vector3(1, 2, 3),
Vector3(4, 5, 6),
Vector3(7, 8, 9)
)
my_basis = my_basis.transposed()
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(
new Vector3(1.0f, 2.0f, 3.0f),
new Vector3(4.0f, 5.0f, 6.0f),
new Vector3(7.0f, 8.0f, 9.0f)
);
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)
[/csharp]
[/codeblocks]
</description>
</method>
</methods>
<members>
<member name="x" type="Vector3" setter="" getter="" default="Vector3(1, 0, 0)">
The basis's X axis, and the column [code]0[/code] of the matrix.
On the identity basis, this vector points right ([constant Vector3.RIGHT]).
</member>
<member name="y" type="Vector3" setter="" getter="" default="Vector3(0, 1, 0)">
The basis's Y axis, and the column [code]1[/code] of the matrix.
On the identity basis, this vector points up ([constant Vector3.UP]).
</member>
<member name="z" type="Vector3" setter="" getter="" default="Vector3(0, 0, 1)">
The basis's Z axis, and the column [code]2[/code] of the matrix.
On the identity basis, this vector points back ([constant Vector3.BACK]).
</member>
</members>
<constants>
<constant name="IDENTITY" value="Basis(1, 0, 0, 0, 1, 0, 0, 0, 1)">
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
print("| X | Y | 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]
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).
When [constant FLIP_X] is multiplied by any basis, it negates the [member Vector3.x] component of all axes (the X row).
</constant>
<constant name="FLIP_Y" value="Basis(1, 0, 0, 0, -1, 0, 0, 0, 1)">
When any basis is multiplied by [constant FLIP_Y], it negates all components of the [member y] axis (the Y column).
When [constant FLIP_Y] is multiplied by any basis, it negates the [member Vector3.y] component of all axes (the Y row).
</constant>
<constant name="FLIP_Z" value="Basis(1, 0, 0, 0, 1, 0, 0, 0, -1)">
When any basis is multiplied by [constant FLIP_Z], it negates all components of the [member z] axis (the Z column).
When [constant FLIP_Z] is multiplied by any basis, it negates the [member Vector3.z] component of all axes (the Z row).
</constant>
</constants>
<operators>
<operator name="operator !=">
<return type="bool" />
<param index="0" name="right" type="Basis" />
<description>
Returns [code]true[/code] if the components of both [Basis] matrices are not equal.
[b]Note:[/b] Due to floating-point precision errors, consider using [method is_equal_approx] instead, which is more reliable.
</description>
</operator>
<operator name="operator *">
<return type="Basis" />
<param index="0" name="right" type="Basis" />
<description>
Transforms (multiplies) the [param right] basis by this basis.
This is the operation performed between parent and child [Node3D]s.
</description>
</operator>
<operator name="operator *">
<return type="Vector3" />
<param index="0" name="right" type="Vector3" />
<description>
Transforms (multiplies) the [param right] vector by this basis, returning a [Vector3].
[codeblocks]
[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.0, 2.0, 6.0)
[/gdscript]
[csharp]
// Basis that swaps the X/Z axes and doubles the scale.
var myBasis = new Basis(new Vector3(0, 2, 0), new Vector3(2, 0, 0), new Vector3(0, 0, 2));
GD.Print(myBasis * new Vector3(1, 2, 3)); // Prints (4, 2, 6)
[/csharp]
[/codeblocks]
</description>
</operator>
<operator name="operator *">
<return type="Basis" />
<param index="0" name="right" type="float" />
<description>
Multiplies all components of the [Basis] by the given [float]. This affects the basis's scale uniformly, resizing all 3 axes by the [param right] value.
</description>
</operator>
<operator name="operator *">
<return type="Basis" />
<param index="0" name="right" type="int" />
<description>
Multiplies all components of the [Basis] by the given [int]. This affects the basis's scale uniformly, resizing all 3 axes by the [param right] value.
</description>
</operator>
<operator name="operator /">
<return type="Basis" />
<param index="0" name="right" type="float" />
<description>
Divides all components of the [Basis] by the given [float]. This affects the basis's scale uniformly, resizing all 3 axes by the [param right] value.
</description>
</operator>
<operator name="operator /">
<return type="Basis" />
<param index="0" name="right" type="int" />
<description>
Divides all components of the [Basis] by the given [int]. This affects the basis's scale uniformly, resizing all 3 axes by the [param right] value.
</description>
</operator>
<operator name="operator ==">
<return type="bool" />
<param index="0" name="right" type="Basis" />
<description>
Returns [code]true[/code] if the components of both [Basis] matrices are exactly equal.
[b]Note:[/b] Due to floating-point precision errors, consider using [method is_equal_approx] instead, which is more reliable.
</description>
</operator>
<operator name="operator []">
<return type="Vector3" />
<param index="0" name="index" type="int" />
<description>
Accesses each axis (column) of this basis by their index. Index [code]0[/code] is the same as [member x], index [code]1[/code] is the same as [member y], and index [code]2[/code] is the same as [member z].
[b]Note:[/b] In C++, this operator accesses the rows of the basis matrix, [i]not[/i] the columns. For the same behavior as scripting languages, use the [code]set_column[/code] and [code]get_column[/code] methods.
</description>
</operator>
</operators>
</class>

114
doc/classes/BitMap.xml Normal file
View File

@@ -0,0 +1,114 @@
<?xml version="1.0" encoding="UTF-8" ?>
<class name="BitMap" inherits="Resource" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Boolean matrix.
</brief_description>
<description>
A two-dimensional array of boolean values, can be used to efficiently store a binary matrix (every matrix element takes only one bit) and query the values using natural cartesian coordinates.
</description>
<tutorials>
</tutorials>
<methods>
<method name="convert_to_image" qualifiers="const">
<return type="Image" />
<description>
Returns an image of the same size as the bitmap and with an [enum Image.Format] of type [constant Image.FORMAT_L8]. [code]true[/code] bits of the bitmap are being converted into white pixels, and [code]false[/code] bits into black.
</description>
</method>
<method name="create">
<return type="void" />
<param index="0" name="size" type="Vector2i" />
<description>
Creates a bitmap with the specified size, filled with [code]false[/code].
</description>
</method>
<method name="create_from_image_alpha">
<return type="void" />
<param index="0" name="image" type="Image" />
<param index="1" name="threshold" type="float" default="0.1" />
<description>
Creates a bitmap that matches the given image dimensions, every element of the bitmap is set to [code]false[/code] if the alpha value of the image at that position is equal to [param threshold] or less, and [code]true[/code] in other case.
</description>
</method>
<method name="get_bit" qualifiers="const">
<return type="bool" />
<param index="0" name="x" type="int" />
<param index="1" name="y" type="int" />
<description>
Returns bitmap's value at the specified position.
</description>
</method>
<method name="get_bitv" qualifiers="const">
<return type="bool" />
<param index="0" name="position" type="Vector2i" />
<description>
Returns bitmap's value at the specified position.
</description>
</method>
<method name="get_size" qualifiers="const">
<return type="Vector2i" />
<description>
Returns bitmap's dimensions.
</description>
</method>
<method name="get_true_bit_count" qualifiers="const">
<return type="int" />
<description>
Returns the number of bitmap elements that are set to [code]true[/code].
</description>
</method>
<method name="grow_mask">
<return type="void" />
<param index="0" name="pixels" type="int" />
<param index="1" name="rect" type="Rect2i" />
<description>
Applies morphological dilation or erosion to the bitmap. If [param pixels] is positive, dilation is applied to the bitmap. If [param pixels] is negative, erosion is applied to the bitmap. [param rect] defines the area where the morphological operation is applied. Pixels located outside the [param rect] are unaffected by [method grow_mask].
</description>
</method>
<method name="opaque_to_polygons" qualifiers="const">
<return type="PackedVector2Array[]" />
<param index="0" name="rect" type="Rect2i" />
<param index="1" name="epsilon" type="float" default="2.0" />
<description>
Creates an [Array] of polygons covering a rectangular portion of the bitmap. It uses a marching squares algorithm, followed by Ramer-Douglas-Peucker (RDP) reduction of the number of vertices. Each polygon is described as a [PackedVector2Array] of its vertices.
To get polygons covering the whole bitmap, pass:
[codeblock]
Rect2(Vector2(), get_size())
[/codeblock]
[param epsilon] is passed to RDP to control how accurately the polygons cover the bitmap: a lower [param epsilon] corresponds to more points in the polygons.
</description>
</method>
<method name="resize">
<return type="void" />
<param index="0" name="new_size" type="Vector2i" />
<description>
Resizes the image to [param new_size].
</description>
</method>
<method name="set_bit">
<return type="void" />
<param index="0" name="x" type="int" />
<param index="1" name="y" type="int" />
<param index="2" name="bit" type="bool" />
<description>
Sets the bitmap's element at the specified position, to the specified value.
</description>
</method>
<method name="set_bit_rect">
<return type="void" />
<param index="0" name="rect" type="Rect2i" />
<param index="1" name="bit" type="bool" />
<description>
Sets a rectangular portion of the bitmap to the specified value.
</description>
</method>
<method name="set_bitv">
<return type="void" />
<param index="0" name="position" type="Vector2i" />
<param index="1" name="bit" type="bool" />
<description>
Sets the bitmap's element at the specified position, to the specified value.
</description>
</method>
</methods>
</class>

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