diff --git a/docs/Classes/class_@gdscript.md b/docs/Classes/class_@gdscript.md new file mode 100644 index 00000000..9207b94c --- /dev/null +++ b/docs/Classes/class_@gdscript.md @@ -0,0 +1,1329 @@ + + + + + + + + + +# @GDScript + +Built-in GDScript constants, functions, and annotations. + + + +## Description + +A list of utility functions and annotations accessible from any script written in GDScript. + +For the list of global functions and constants that can be accessed in any scripting language, see [@GlobalScope](class_@globalscope.md). + + + +## Tutorials + +- [GDScript exports](../tutorials/scripting/gdscript/gdscript_exports.md) + + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Color](class_color.md)[Color8](#class_@GDScript_method_Color8)\ (\ r8\: [int](class_int.md), g8\: [int](class_int.md), b8\: [int](class_int.md), a8\: [int](class_int.md) = 255\ )
`void`[assert](#class_@GDScript_method_assert)\ (\ condition\: [bool](class_bool.md), message\: [String](class_string.md) = ""\ )
[String](class_string.md)[char](#class_@GDScript_method_char)\ (\ code\: [int](class_int.md)\ )
[Variant](class_variant.md)[convert](#class_@GDScript_method_convert)\ (\ what\: [Variant](class_variant.md), type\: [Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type)\ )
[Object](class_object.md)[dict_to_inst](#class_@GDScript_method_dict_to_inst)\ (\ dictionary\: [Dictionary](class_dictionary.md)\ )
[Array](class_array.md)[get_stack](#class_@GDScript_method_get_stack)\ (\ )
[Dictionary](class_dictionary.md)[inst_to_dict](#class_@GDScript_method_inst_to_dict)\ (\ instance\: [Object](class_object.md)\ )
[bool](class_bool.md)[is_instance_of](#class_@GDScript_method_is_instance_of)\ (\ value\: [Variant](class_variant.md), type\: [Variant](class_variant.md)\ )
[int](class_int.md)[len](#class_@GDScript_method_len)\ (\ var\: [Variant](class_variant.md)\ )
[Resource](class_resource.md)[load](#class_@GDScript_method_load)\ (\ path\: [String](class_string.md)\ )
[int](class_int.md)[ord](#class_@GDScript_method_ord)\ (\ char\: [String](class_string.md)\ )
[Resource](class_resource.md)[preload](#class_@GDScript_method_preload)\ (\ path\: [String](class_string.md)\ )
`void`[print_debug](#class_@GDScript_method_print_debug)\ (\ ...\ ) vararg
`void`[print_stack](#class_@GDScript_method_print_stack)\ (\ )
[Array](class_array.md)[range](#class_@GDScript_method_range)\ (\ ...\ ) vararg
[bool](class_bool.md)[type_exists](#class_@GDScript_method_type_exists)\ (\ type\: [StringName](class_stringname.md)\ )
+ +
+ + + +## Constants + + + + + +**PI** = `3.14159265358979` [🔗](#class_@GDScript_constant_PI) + +Constant that represents how many times the diameter of a circle fits around its perimeter. This is equivalent to ``TAU / 2``, or 180 degrees in rotations. + + + + + +**TAU** = `6.28318530717959` [🔗](#class_@GDScript_constant_TAU) + +The circle constant, the circumference of the unit circle in radians. This is equivalent to ``PI * 2``, or 360 degrees in rotations. + + + + + +**INF** = `inf` [🔗](#class_@GDScript_constant_INF) + +Positive floating-point infinity. This is the result of floating-point division when the divisor is ``0.0``. For negative infinity, use ``-INF``. Dividing by ``-0.0`` will result in negative infinity if the numerator is positive, so dividing by ``0.0`` is not the same as dividing by ``-0.0`` (despite ``0.0 == -0.0`` returning ``true``). + +\ **Warning:** Numeric infinity is only a concept with floating-point numbers, and has no equivalent for integers. Dividing an integer number by ``0`` will not result in [INF](class_@gdscript.md#class_@GDScript_constant_INF) and will result in a run-time error instead. + + + + + +**NAN** = `nan` [🔗](#class_@GDScript_constant_NAN) + +"Not a Number", an invalid floating-point value. It is returned by some invalid operations, such as dividing floating-point ``0.0`` by ``0.0``. + +\ [NAN](class_@gdscript.md#class_@GDScript_constant_NAN) has special properties, including that ``!=`` always returns ``true``, while other comparison operators always return ``false``. This is true even when comparing with itself (``NAN == NAN`` returns ``false`` and ``NAN != NAN`` returns ``true``). Due to this, you must use [@GlobalScope.is_nan()](class_@globalscope.md#class_@GlobalScope_method_is_nan) to check whether a number is equal to [NAN](class_@gdscript.md#class_@GDScript_constant_NAN). + +\ **Warning:** "Not a Number" is only a concept with floating-point numbers, and has no equivalent for integers. Dividing an integer ``0`` by ``0`` will not result in [NAN](class_@gdscript.md#class_@GDScript_constant_NAN) and will result in a run-time error instead. + +
+ +## Annotations + + + + + +**@abstract**\ (\ ) [🔗](#class_@GDScript_annotation_@abstract) + +Marks a class or a method as abstract. + +An abstract class is a class that cannot be instantiated directly. Instead, it is meant to be inherited by other classes. Attempting to instantiate an abstract class will result in an error. + +An abstract method is a method that has no implementation. Therefore, a newline or a semicolon is expected after the function header. This defines a contract that inheriting classes must conform to, because the method signature must be compatible when overriding. + +Inheriting classes must either provide implementations for all abstract methods, or the inheriting class must be marked as abstract. If a class has at least one abstract method (either its own or an unimplemented inherited one), then it must also be marked as abstract. However, the reverse is not true: an abstract class is allowed to have no abstract methods. + +``` + @abstract class Shape: + @abstract func draw() + + class Circle extends Shape: + func draw(): + print("Drawing a circle.") + + class Square extends Shape: + func draw(): + print("Drawing a square.") +``` + +
+ + + + + +**@export**\ (\ ) [🔗](#class_@GDScript_annotation_@export) + +Mark the following property as exported (editable in the Inspector dock and saved to disk). To control the type of the exported property, use the type hint notation. + +``` + extends Node + + enum Direction {LEFT, RIGHT, UP, DOWN} + + # Built-in types. + @export var string = "" + @export var int_number = 5 + @export var float_number: float = 5 + + # Enums. + @export var type: Variant.Type + @export var format: Image.Format + @export var direction: Direction + + # Resources. + @export var image: Image + @export var custom_resource: CustomResource + + # Nodes. + @export var node: Node + @export var custom_node: CustomNode + + # Typed arrays. + @export var int_array: Array[int] + @export var direction_array: Array[Direction] + @export var image_array: Array[Image] + @export var node_array: Array[Node] +``` + +\ **Note:** Custom resources and nodes should be registered as global classes using ``class_name``, since the Inspector currently only supports global classes. Otherwise, a less specific type will be exported instead. + +\ **Note:** Node export is only supported in [Node](class_node.md)-derived classes and has a number of other limitations. + +
+ + + + + +**@export_category**\ (\ name\: [String](class_string.md)\ ) [🔗](#class_@GDScript_annotation_@export_category) + +Define a new category for the following exported properties. This helps to organize properties in the Inspector dock. + +See also [@GlobalScope.PROPERTY_USAGE_CATEGORY](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_USAGE_CATEGORY). + +``` + @export_category("Statistics") + @export var hp = 30 + @export var speed = 1.25 +``` + +\ **Note:** Categories in the Inspector dock's list usually divide properties coming from different classes (Node, Node2D, Sprite, etc.). For better clarity, it's recommended to use [@export_group](class_@gdscript.md#class_@GDScript_annotation_@export_group) and [@export_subgroup](class_@gdscript.md#class_@GDScript_annotation_@export_subgroup), instead. + +
+ + + + + +**@export_color_no_alpha**\ (\ ) [🔗](#class_@GDScript_annotation_@export_color_no_alpha) + +Export a [Color](class_color.md), [Array](class_array.md)\ \[[Color](class_color.md)\ \], or [PackedColorArray](class_packedcolorarray.md) property without allowing its transparency ([Color.a](class_color.md#class_Color_property_a)) to be edited. + +See also [@GlobalScope.PROPERTY_HINT_COLOR_NO_ALPHA](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_COLOR_NO_ALPHA). + +``` + @export_color_no_alpha var dye_color: Color + @export_color_no_alpha var dye_colors: Array[Color] +``` + +
+ + + + + +**@export_custom**\ (\ hint\: [PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint), hint_string\: [String](class_string.md), usage\: **BitField**\[[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags)\] = 6\ ) [🔗](#class_@GDScript_annotation_@export_custom) + +Allows you to set a custom hint, hint string, and usage flags for the exported property. Note that there's no validation done in GDScript, it will just pass the parameters to the editor. + +``` + @export_custom(PROPERTY_HINT_NONE, "suffix:m") var suffix: Vector3 +``` + +\ **Note:** Regardless of the `usage` value, the [@GlobalScope.PROPERTY_USAGE_SCRIPT_VARIABLE](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_USAGE_SCRIPT_VARIABLE) flag is always added, as with any explicitly declared script variable. + +
+ + + + + +**@export_dir**\ (\ ) [🔗](#class_@GDScript_annotation_@export_dir) + +Export a [String](class_string.md), [Array](class_array.md)\ \[[String](class_string.md)\ \], or [PackedStringArray](class_packedstringarray.md) property as a path to a directory. The path will be limited to the project folder and its subfolders. See [@export_global_dir](class_@gdscript.md#class_@GDScript_annotation_@export_global_dir) to allow picking from the entire filesystem. + +See also [@GlobalScope.PROPERTY_HINT_DIR](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_DIR). + +``` + @export_dir var sprite_folder_path: String + @export_dir var sprite_folder_paths: Array[String] +``` + +
+ + + + + +**@export_enum**\ (\ names\: [String](class_string.md), ...\ ) vararg [🔗](#class_@GDScript_annotation_@export_enum) + +Export an [int](class_int.md), [String](class_string.md), [Array](class_array.md)\ \[[int](class_int.md)\ \], [Array](class_array.md)\ \[[String](class_string.md)\ \], [PackedByteArray](class_packedbytearray.md), [PackedInt32Array](class_packedint32array.md), [PackedInt64Array](class_packedint64array.md), or [PackedStringArray](class_packedstringarray.md) property as an enumerated list of options (or an array of options). If the property is an [int](class_int.md), then the index of the value is stored, in the same order the values are provided. You can add explicit values using a colon. If the property is a [String](class_string.md), then the value is stored. + +See also [@GlobalScope.PROPERTY_HINT_ENUM](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_ENUM). + +``` + @export_enum("Warrior", "Magician", "Thief") var character_class: int + @export_enum("Slow:30", "Average:60", "Very Fast:200") var character_speed: int + @export_enum("Rebecca", "Mary", "Leah") var character_name: String + + @export_enum("Sword", "Spear", "Mace") var character_items: Array[int] + @export_enum("double_jump", "climb", "dash") var character_skills: Array[String] +``` + +If you want to set an initial value, you must specify it explicitly: + +``` + @export_enum("Rebecca", "Mary", "Leah") var character_name: String = "Rebecca" +``` + +If you want to use named GDScript enums, then use [@export](class_@gdscript.md#class_@GDScript_annotation_@export) instead: + +``` + enum CharacterName {REBECCA, MARY, LEAH} + @export var character_name: CharacterName + + enum CharacterItem {SWORD, SPEAR, MACE} + @export var character_items: Array[CharacterItem] +``` + +
+ + + + + +**@export_exp_easing**\ (\ hints\: [String](class_string.md) = "", ...\ ) vararg [🔗](#class_@GDScript_annotation_@export_exp_easing) + +Export a floating-point property with an easing editor widget. Additional hints can be provided to adjust the behavior of the widget. ``"attenuation"`` flips the curve, which makes it more intuitive for editing attenuation properties. ``"positive_only"`` limits values to only be greater than or equal to zero. + +See also [@GlobalScope.PROPERTY_HINT_EXP_EASING](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_EXP_EASING). + +``` + @export_exp_easing var transition_speed + @export_exp_easing("attenuation") var fading_attenuation + @export_exp_easing("positive_only") var effect_power + @export_exp_easing var speeds: Array[float] +``` + +
+ + + + + +**@export_file**\ (\ filter\: [String](class_string.md) = "", ...\ ) vararg [🔗](#class_@GDScript_annotation_@export_file) + +Export a [String](class_string.md), [Array](class_array.md)\ \[[String](class_string.md)\ \], or [PackedStringArray](class_packedstringarray.md) property as a path to a file. The path will be limited to the project folder and its subfolders. See [@export_global_file](class_@gdscript.md#class_@GDScript_annotation_@export_global_file) to allow picking from the entire filesystem. + +If `filter` is provided, only matching files will be available for picking. + +See also [@GlobalScope.PROPERTY_HINT_FILE](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_FILE). + +``` + @export_file var sound_effect_path: String + @export_file("*.txt") var notes_path: String + @export_file var level_paths: Array[String] +``` + +\ **Note:** The file will be stored and referenced as UID, if available. This ensures that the reference is valid even when the file is moved. You can use [ResourceUID](class_resourceuid.md) methods to convert it to path. + +
+ + + + + +**@export_file_path**\ (\ filter\: [String](class_string.md) = "", ...\ ) vararg [🔗](#class_@GDScript_annotation_@export_file_path) + +Same as [@export_file](class_@gdscript.md#class_@GDScript_annotation_@export_file), except the file will be stored as a raw path. This means that it may become invalid when the file is moved. If you are exporting a [Resource](class_resource.md) path, consider using [@export_file](class_@gdscript.md#class_@GDScript_annotation_@export_file) instead. + +
+ + + + + +**@export_flags**\ (\ names\: [String](class_string.md), ...\ ) vararg [🔗](#class_@GDScript_annotation_@export_flags) + +Export an integer property as a bit flag field. This allows to store several "checked" or ``true`` values with one property, and comfortably select them from the Inspector dock. + +See also [@GlobalScope.PROPERTY_HINT_FLAGS](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_FLAGS). + +``` + @export_flags("Fire", "Water", "Earth", "Wind") var spell_elements = 0 +``` + +You can add explicit values using a colon: + +``` + @export_flags("Self:4", "Allies:8", "Foes:16") var spell_targets = 0 +``` + +You can also combine several flags: + +``` + @export_flags("Self:4", "Allies:8", "Self and Allies:12", "Foes:16") + var spell_targets = 0 +``` + +\ **Note:** A flag value must be at least ``1`` and at most ``2 ** 32 - 1``. + +\ **Note:** Unlike [@export_enum](class_@gdscript.md#class_@GDScript_annotation_@export_enum), the previous explicit value is not taken into account. In the following example, A is 16, B is 2, C is 4. + +``` + @export_flags("A:16", "B", "C") var x +``` + +You can also use the annotation on [Array](class_array.md)\ \[[int](class_int.md)\ \], [PackedByteArray](class_packedbytearray.md), [PackedInt32Array](class_packedint32array.md), and [PackedInt64Array](class_packedint64array.md)\ + +``` + @export_flags("Fire", "Water", "Earth", "Wind") var phase_elements: Array[int] +``` + +
+ + + + + +**@export_flags_2d_navigation**\ (\ ) [🔗](#class_@GDScript_annotation_@export_flags_2d_navigation) + +Export an integer property as a bit flag field for 2D navigation layers. The widget in the Inspector dock will use the layer names defined in [ProjectSettings.layer_names/2d_navigation/layer_1](class_projectsettings.md#class_ProjectSettings_property_layer_names/2d_navigation/layer_1). + +See also [@GlobalScope.PROPERTY_HINT_LAYERS_2D_NAVIGATION](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_LAYERS_2D_NAVIGATION). + +``` + @export_flags_2d_navigation var navigation_layers: int + @export_flags_2d_navigation var navigation_layers_array: Array[int] +``` + +
+ + + + + +**@export_flags_2d_physics**\ (\ ) [🔗](#class_@GDScript_annotation_@export_flags_2d_physics) + +Export an integer property as a bit flag field for 2D physics layers. The widget in the Inspector dock will use the layer names defined in [ProjectSettings.layer_names/2d_physics/layer_1](class_projectsettings.md#class_ProjectSettings_property_layer_names/2d_physics/layer_1). + +See also [@GlobalScope.PROPERTY_HINT_LAYERS_2D_PHYSICS](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_LAYERS_2D_PHYSICS). + +``` + @export_flags_2d_physics var physics_layers: int + @export_flags_2d_physics var physics_layers_array: Array[int] +``` + +
+ + + + + +**@export_flags_2d_render**\ (\ ) [🔗](#class_@GDScript_annotation_@export_flags_2d_render) + +Export an integer property as a bit flag field for 2D render layers. The widget in the Inspector dock will use the layer names defined in [ProjectSettings.layer_names/2d_render/layer_1](class_projectsettings.md#class_ProjectSettings_property_layer_names/2d_render/layer_1). + +See also [@GlobalScope.PROPERTY_HINT_LAYERS_2D_RENDER](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_LAYERS_2D_RENDER). + +``` + @export_flags_2d_render var render_layers: int + @export_flags_2d_render var render_layers_array: Array[int] +``` + +
+ + + + + +**@export_flags_3d_navigation**\ (\ ) [🔗](#class_@GDScript_annotation_@export_flags_3d_navigation) + +Export an integer property as a bit flag field for 3D navigation layers. The widget in the Inspector dock will use the layer names defined in [ProjectSettings.layer_names/3d_navigation/layer_1](class_projectsettings.md#class_ProjectSettings_property_layer_names/3d_navigation/layer_1). + +See also [@GlobalScope.PROPERTY_HINT_LAYERS_3D_NAVIGATION](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_LAYERS_3D_NAVIGATION). + +``` + @export_flags_3d_navigation var navigation_layers: int + @export_flags_3d_navigation var navigation_layers_array: Array[int] +``` + +
+ + + + + +**@export_flags_3d_physics**\ (\ ) [🔗](#class_@GDScript_annotation_@export_flags_3d_physics) + +Export an integer property as a bit flag field for 3D physics layers. The widget in the Inspector dock will use the layer names defined in [ProjectSettings.layer_names/3d_physics/layer_1](class_projectsettings.md#class_ProjectSettings_property_layer_names/3d_physics/layer_1). + +See also [@GlobalScope.PROPERTY_HINT_LAYERS_3D_PHYSICS](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_LAYERS_3D_PHYSICS). + +``` + @export_flags_3d_physics var physics_layers: int + @export_flags_3d_physics var physics_layers_array: Array[int] +``` + +
+ + + + + +**@export_flags_3d_render**\ (\ ) [🔗](#class_@GDScript_annotation_@export_flags_3d_render) + +Export an integer property as a bit flag field for 3D render layers. The widget in the Inspector dock will use the layer names defined in [ProjectSettings.layer_names/3d_render/layer_1](class_projectsettings.md#class_ProjectSettings_property_layer_names/3d_render/layer_1). + +See also [@GlobalScope.PROPERTY_HINT_LAYERS_3D_RENDER](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_LAYERS_3D_RENDER). + +``` + @export_flags_3d_render var render_layers: int + @export_flags_3d_render var render_layers_array: Array[int] +``` + +
+ + + + + +**@export_flags_avoidance**\ (\ ) [🔗](#class_@GDScript_annotation_@export_flags_avoidance) + +Export an integer property as a bit flag field for navigation avoidance layers. The widget in the Inspector dock will use the layer names defined in [ProjectSettings.layer_names/avoidance/layer_1](class_projectsettings.md#class_ProjectSettings_property_layer_names/avoidance/layer_1). + +See also [@GlobalScope.PROPERTY_HINT_LAYERS_AVOIDANCE](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_LAYERS_AVOIDANCE). + +``` + @export_flags_avoidance var avoidance_layers: int + @export_flags_avoidance var avoidance_layers_array: Array[int] +``` + +
+ + + + + +**@export_global_dir**\ (\ ) [🔗](#class_@GDScript_annotation_@export_global_dir) + +Export a [String](class_string.md), [Array](class_array.md)\ \[[String](class_string.md)\ \], or [PackedStringArray](class_packedstringarray.md) property as an absolute path to a directory. The path can be picked from the entire filesystem. See [@export_dir](class_@gdscript.md#class_@GDScript_annotation_@export_dir) to limit it to the project folder and its subfolders. + +See also [@GlobalScope.PROPERTY_HINT_GLOBAL_DIR](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_GLOBAL_DIR). + +``` + @export_global_dir var sprite_folder_path: String + @export_global_dir var sprite_folder_paths: Array[String] +``` + +
+ + + + + +**@export_global_file**\ (\ filter\: [String](class_string.md) = "", ...\ ) vararg [🔗](#class_@GDScript_annotation_@export_global_file) + +Export a [String](class_string.md), [Array](class_array.md)\ \[[String](class_string.md)\ \], or [PackedStringArray](class_packedstringarray.md) property as an absolute path to a file. The path can be picked from the entire filesystem. See [@export_file](class_@gdscript.md#class_@GDScript_annotation_@export_file) to limit it to the project folder and its subfolders. + +If `filter` is provided, only matching files will be available for picking. + +See also [@GlobalScope.PROPERTY_HINT_GLOBAL_FILE](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_GLOBAL_FILE). + +``` + @export_global_file var sound_effect_path: String + @export_global_file("*.txt") var notes_path: String + @export_global_file var multiple_paths: Array[String] +``` + +
+ + + + + +**@export_group**\ (\ name\: [String](class_string.md), prefix\: [String](class_string.md) = ""\ ) [🔗](#class_@GDScript_annotation_@export_group) + +Define a new group for the following exported properties. This helps to organize properties in the Inspector dock. Groups can be added with an optional `prefix`, which would make group to only consider properties that have this prefix. The grouping will break on the first property that doesn't have a prefix. The prefix is also removed from the property's name in the Inspector dock. + +If no `prefix` is provided, then every following property will be added to the group. The group ends when then next group or category is defined. You can also force end a group by using this annotation with empty strings for parameters, ``@export_group("", "")``. + +Groups cannot be nested, use [@export_subgroup](class_@gdscript.md#class_@GDScript_annotation_@export_subgroup) to add subgroups within groups. + +See also [@GlobalScope.PROPERTY_USAGE_GROUP](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_USAGE_GROUP). + +``` + @export_group("Racer Properties") + @export var nickname = "Nick" + @export var age = 26 + + @export_group("Car Properties", "car_") + @export var car_label = "Speedy" + @export var car_number = 3 + + @export_group("", "") + @export var ungrouped_number = 3 +``` + +
+ + + + + +**@export_multiline**\ (\ ) [🔗](#class_@GDScript_annotation_@export_multiline) + +Export a [String](class_string.md), [Array](class_array.md)\ \[[String](class_string.md)\ \], [PackedStringArray](class_packedstringarray.md), [Dictionary](class_dictionary.md) or [Array](class_array.md)\ \[[Dictionary](class_dictionary.md)\ \] property with a large [TextEdit](class_textedit.md) widget instead of a [LineEdit](class_lineedit.md). This adds support for multiline content and makes it easier to edit large amount of text stored in the property. + +See also [@GlobalScope.PROPERTY_HINT_MULTILINE_TEXT](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_MULTILINE_TEXT). + +``` + @export_multiline var character_biography + @export_multiline var npc_dialogs: Array[String] +``` + +
+ + + + + +**@export_node_path**\ (\ type\: [String](class_string.md) = "", ...\ ) vararg [🔗](#class_@GDScript_annotation_@export_node_path) + +Export a [NodePath](class_nodepath.md) or [Array](class_array.md)\ \[[NodePath](class_nodepath.md)\ \] property with a filter for allowed node types. + +See also [@GlobalScope.PROPERTY_HINT_NODE_PATH_VALID_TYPES](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_NODE_PATH_VALID_TYPES). + +``` + @export_node_path("Button", "TouchScreenButton") var some_button + @export_node_path("Button", "TouchScreenButton") var many_buttons: Array[NodePath] +``` + +\ **Note:** The type must be a native class or a globally registered script (using the ``class_name`` keyword) that inherits [Node](class_node.md). + +
+ + + + + +**@export_placeholder**\ (\ placeholder\: [String](class_string.md)\ ) [🔗](#class_@GDScript_annotation_@export_placeholder) + +Export a [String](class_string.md), [Array](class_array.md)\ \[[String](class_string.md)\ \], or [PackedStringArray](class_packedstringarray.md) property with a placeholder text displayed in the editor widget when no value is present. + +See also [@GlobalScope.PROPERTY_HINT_PLACEHOLDER_TEXT](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_PLACEHOLDER_TEXT). + +``` + @export_placeholder("Name in lowercase") var character_id: String + @export_placeholder("Name in lowercase") var friend_ids: Array[String] +``` + +
+ + + + + +**@export_range**\ (\ min\: [float](class_float.md), max\: [float](class_float.md), step\: [float](class_float.md) = 1.0, extra_hints\: [String](class_string.md) = "", ...\ ) vararg [🔗](#class_@GDScript_annotation_@export_range) + +Export an [int](class_int.md), [float](class_float.md), [Array](class_array.md)\ \[[int](class_int.md)\ \], [Array](class_array.md)\ \[[float](class_float.md)\ \], [PackedByteArray](class_packedbytearray.md), [PackedInt32Array](class_packedint32array.md), [PackedInt64Array](class_packedint64array.md), [PackedFloat32Array](class_packedfloat32array.md), or [PackedFloat64Array](class_packedfloat64array.md) property as a range value. The range must be defined by `min` and `max`, as well as an optional `step` and a variety of extra hints. The `step` defaults to ``1`` for integer properties. For floating-point numbers this value depends on your [EditorSettings.interface/inspector/default_float_step](class_editorsettings.md#class_EditorSettings_property_interface/inspector/default_float_step) setting. + +If hints ``"or_greater"`` and ``"or_less"`` are provided, the editor widget will not cap the value at range boundaries. The ``"exp"`` hint will make the edited values on range to change exponentially. The ``"hide_slider"`` hint will hide the slider element of the editor widget. + +Hints also allow to indicate the units for the edited value. Using ``"radians_as_degrees"`` you can specify that the actual value is in radians, but should be displayed in degrees in the Inspector dock (the range values are also in degrees). ``"degrees"`` allows to add a degree sign as a unit suffix (the value is unchanged). Finally, a custom suffix can be provided using ``"suffix:unit"``, where "unit" can be any string. + +See also [@GlobalScope.PROPERTY_HINT_RANGE](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_RANGE). + +``` + @export_range(0, 20) var number + @export_range(-10, 20) var number + @export_range(-10, 20, 0.2) var number: float + @export_range(0, 20) var numbers: Array[float] + + @export_range(0, 100, 1, "or_greater") var power_percent + @export_range(0, 100, 1, "or_greater", "or_less") var health_delta + + @export_range(-180, 180, 0.001, "radians_as_degrees") var angle_radians + @export_range(0, 360, 1, "degrees") var angle_degrees + @export_range(-8, 8, 2, "suffix:px") var target_offset +``` + +
+ + + + + +**@export_storage**\ (\ ) [🔗](#class_@GDScript_annotation_@export_storage) + +Export a property with [@GlobalScope.PROPERTY_USAGE_STORAGE](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_USAGE_STORAGE) flag. The property is not displayed in the editor, but it is serialized and stored in the scene or resource file. This can be useful for [@tool](class_@gdscript.md#class_@GDScript_annotation_@tool) scripts. Also the property value is copied when [Resource.duplicate()](class_resource.md#class_Resource_method_duplicate) or [Node.duplicate()](class_node.md#class_Node_method_duplicate) is called, unlike non-exported variables. + +``` + var a # Not stored in the file, not displayed in the editor. + @export_storage var b # Stored in the file, not displayed in the editor. + @export var c: int # Stored in the file, displayed in the editor. +``` + +
+ + + + + +**@export_subgroup**\ (\ name\: [String](class_string.md), prefix\: [String](class_string.md) = ""\ ) [🔗](#class_@GDScript_annotation_@export_subgroup) + +Define a new subgroup for the following exported properties. This helps to organize properties in the Inspector dock. Subgroups work exactly like groups, except they need a parent group to exist. See [@export_group](class_@gdscript.md#class_@GDScript_annotation_@export_group). + +See also [@GlobalScope.PROPERTY_USAGE_SUBGROUP](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_USAGE_SUBGROUP). + +``` + @export_group("Racer Properties") + @export var nickname = "Nick" + @export var age = 26 + + @export_subgroup("Car Properties", "car_") + @export var car_label = "Speedy" + @export var car_number = 3 +``` + +\ **Note:** Subgroups cannot be nested, but you can use the slash separator (``/``) to achieve the desired effect: + +``` + @export_group("Car Properties") + @export_subgroup("Wheels", "wheel_") + @export_subgroup("Wheels/Front", "front_wheel_") + @export var front_wheel_strength = 10 + @export var front_wheel_mobility = 5 + @export_subgroup("Wheels/Rear", "rear_wheel_") + @export var rear_wheel_strength = 8 + @export var rear_wheel_mobility = 3 + @export_subgroup("Wheels", "wheel_") + @export var wheel_material: PhysicsMaterial +``` + +
+ + + + + +**@export_tool_button**\ (\ text\: [String](class_string.md), icon\: [String](class_string.md) = ""\ ) [🔗](#class_@GDScript_annotation_@export_tool_button) + +Export a [Callable](class_callable.md) property as a clickable button with the label `text`. When the button is pressed, the callable is called. + +If `icon` is specified, it is used to fetch an icon for the button via [Control.get_theme_icon()](class_control.md#class_Control_method_get_theme_icon), from the ``"EditorIcons"`` theme type. If `icon` is omitted, the default ``"Callable"`` icon is used instead. + +Consider using the [EditorUndoRedoManager](class_editorundoredomanager.md) to allow the action to be reverted safely. + +See also [@GlobalScope.PROPERTY_HINT_TOOL_BUTTON](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_TOOL_BUTTON). + +``` + @tool + extends Sprite2D + + @export_tool_button("Hello") var hello_action = hello + @export_tool_button("Randomize the color!", "ColorRect") + var randomize_color_action = randomize_color + + func hello(): + print("Hello world!") + + func randomize_color(): + var undo_redo = EditorInterface.get_editor_undo_redo() + undo_redo.create_action("Randomized Sprite2D Color") + undo_redo.add_do_property(self, &"self_modulate", Color(randf(), randf(), randf())) + undo_redo.add_undo_property(self, &"self_modulate", self_modulate) + undo_redo.commit_action() +``` + +\ **Note:** The property is exported without the [@GlobalScope.PROPERTY_USAGE_STORAGE](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_USAGE_STORAGE) flag because a [Callable](class_callable.md) cannot be properly serialized and stored in a file. + +\ **Note:** In an exported project neither [EditorInterface](class_editorinterface.md) nor [EditorUndoRedoManager](class_editorundoredomanager.md) exist, which may cause some scripts to break. To prevent this, you can use [Engine.get_singleton()](class_engine.md#class_Engine_method_get_singleton) and omit the static type from the variable declaration: + +``` + var undo_redo = Engine.get_singleton(&"EditorInterface").get_editor_undo_redo() +``` + +\ **Note:** Avoid storing lambda callables in member variables of [RefCounted](class_refcounted.md)-based classes (e.g. resources), as this can lead to memory leaks. Use only method callables and optionally [Callable.bind()](class_callable.md#class_Callable_method_bind) or [Callable.unbind()](class_callable.md#class_Callable_method_unbind). + +
+ + + + + +**@icon**\ (\ icon_path\: [String](class_string.md)\ ) [🔗](#class_@GDScript_annotation_@icon) + +Add a custom icon to the current script. The icon specified at `icon_path` is displayed in the Scene dock for every node of that class, as well as in various editor dialogs. + +``` + @icon("res://path/to/class/icon.svg") +``` + +\ **Note:** Only the script can have a custom icon. Inner classes are not supported. + +\ **Note:** As annotations describe their subject, the [@icon](class_@gdscript.md#class_@GDScript_annotation_@icon) annotation must be placed before the class definition and inheritance. + +\ **Note:** Unlike most other annotations, the argument of the [@icon](class_@gdscript.md#class_@GDScript_annotation_@icon) annotation must be a string literal (constant expressions are not supported). + +
+ + + + + +**@onready**\ (\ ) [🔗](#class_@GDScript_annotation_@onready) + +Mark the following property as assigned when the [Node](class_node.md) is ready. Values for these properties are not assigned immediately when the node is initialized ([Object._init()](class_object.md#class_Object_private_method__init)), and instead are computed and stored right before [Node._ready()](class_node.md#class_Node_private_method__ready). + +``` + @onready var character_name = $Label +``` + +
+ + + + + +**@rpc**\ (\ mode\: [String](class_string.md) = "authority", sync\: [String](class_string.md) = "call_remote", transfer_mode\: [String](class_string.md) = "unreliable", transfer_channel\: [int](class_int.md) = 0\ ) [🔗](#class_@GDScript_annotation_@rpc) + +Mark the following method for remote procedure calls. See [High-level multiplayer](../tutorials/networking/high_level_multiplayer.md). + +If `mode` is set as ``"any_peer"``, allows any peer to call this RPC function. Otherwise, only the authority peer is allowed to call it and `mode` should be kept as ``"authority"``. When configuring functions as RPCs with [Node.rpc_config()](class_node.md#class_Node_method_rpc_config), each of these modes respectively corresponds to the [MultiplayerAPI.RPC_MODE_AUTHORITY](class_multiplayerapi.md#class_MultiplayerAPI_constant_RPC_MODE_AUTHORITY) and [MultiplayerAPI.RPC_MODE_ANY_PEER](class_multiplayerapi.md#class_MultiplayerAPI_constant_RPC_MODE_ANY_PEER) RPC modes. See [RPCMode](class_multiplayerapi.md#enum_MultiplayerAPI_RPCMode). If a peer that is not the authority tries to call a function that is only allowed for the authority, the function will not be executed. If the error can be detected locally (when the RPC configuration is consistent between the local and the remote peer), an error message will be displayed on the sender peer. Otherwise, the remote peer will detect the error and print an error there. + +If `sync` is set as ``"call_remote"``, the function will only be executed on the remote peer, but not locally. To run this function locally too, set `sync` to ``"call_local"``. When configuring functions as RPCs with [Node.rpc_config()](class_node.md#class_Node_method_rpc_config), this is equivalent to setting ``call_local`` to ``true``. + +The `transfer_mode` accepted values are ``"unreliable"``, ``"unreliable_ordered"``, or ``"reliable"``. It sets the transfer mode of the underlying [MultiplayerPeer](class_multiplayerpeer.md). See [MultiplayerPeer.transfer_mode](class_multiplayerpeer.md#class_MultiplayerPeer_property_transfer_mode). + +The `transfer_channel` defines the channel of the underlying [MultiplayerPeer](class_multiplayerpeer.md). See [MultiplayerPeer.transfer_channel](class_multiplayerpeer.md#class_MultiplayerPeer_property_transfer_channel). + +The order of `mode`, `sync` and `transfer_mode` does not matter, but values related to the same argument must not be used more than once. `transfer_channel` always has to be the 4th argument (you must specify 3 preceding arguments). + +``` + @rpc + func fn(): pass + + @rpc("any_peer", "unreliable_ordered") + func fn_update_pos(): pass + + @rpc("authority", "call_remote", "unreliable", 0) # Equivalent to @rpc + func fn_default(): pass +``` + +\ **Note:** Methods annotated with [@rpc](class_@gdscript.md#class_@GDScript_annotation_@rpc) cannot receive objects which define required parameters in [Object._init()](class_object.md#class_Object_private_method__init). See [Object._init()](class_object.md#class_Object_private_method__init) for more details. + +
+ + + + + +**@static_unload**\ (\ ) [🔗](#class_@GDScript_annotation_@static_unload) + +Make a script with static variables to not persist after all references are lost. If the script is loaded again the static variables will revert to their default values. + +\ **Note:** As annotations describe their subject, the [@static_unload](class_@gdscript.md#class_@GDScript_annotation_@static_unload) annotation must be placed before the class definition and inheritance. + +\ **Warning:** Currently, due to a bug, scripts are never freed, even if [@static_unload](class_@gdscript.md#class_@GDScript_annotation_@static_unload) annotation is used. + +
+ + + + + +**@tool**\ (\ ) [🔗](#class_@GDScript_annotation_@tool) + +Mark the current script as a tool script, allowing it to be loaded and executed by the editor. See [Running code in the editor](../tutorials/plugins/running_code_in_the_editor.md). + +``` + @tool + extends Node +``` + +\ **Note:** As annotations describe their subject, the [@tool](class_@gdscript.md#class_@GDScript_annotation_@tool) annotation must be placed before the class definition and inheritance. + +
+ + + + + +**@warning_ignore**\ (\ warning\: [String](class_string.md), ...\ ) vararg [🔗](#class_@GDScript_annotation_@warning_ignore) + +Mark the following statement to ignore the specified `warning`. See [GDScript warning system](../tutorials/scripting/gdscript/warning_system.md). + +``` + func test(): + print("hello") + return + @warning_ignore("unreachable_code") + print("unreachable") +``` + +See also [@warning_ignore_start](class_@gdscript.md#class_@GDScript_annotation_@warning_ignore_start) and [@warning_ignore_restore](class_@gdscript.md#class_@GDScript_annotation_@warning_ignore_restore). + +
+ + + + + +**@warning_ignore_restore**\ (\ warning\: [String](class_string.md), ...\ ) vararg [🔗](#class_@GDScript_annotation_@warning_ignore_restore) + +Stops ignoring the listed warning types after [@warning_ignore_start](class_@gdscript.md#class_@GDScript_annotation_@warning_ignore_start). Ignoring the specified warning types will be reset to Project Settings. This annotation can be omitted to ignore the warning types until the end of the file. + +\ **Note:** Unlike most other annotations, arguments of the [@warning_ignore_restore](class_@gdscript.md#class_@GDScript_annotation_@warning_ignore_restore) annotation must be string literals (constant expressions are not supported). + +
+ + + + + +**@warning_ignore_start**\ (\ warning\: [String](class_string.md), ...\ ) vararg [🔗](#class_@GDScript_annotation_@warning_ignore_start) + +Starts ignoring the listed warning types until the end of the file or the [@warning_ignore_restore](class_@gdscript.md#class_@GDScript_annotation_@warning_ignore_restore) annotation with the given warning type. + +``` + func test(): + var a = 1 # Warning (if enabled in the Project Settings). + @warning_ignore_start("unused_variable") + var b = 2 # No warning. + var c = 3 # No warning. + @warning_ignore_restore("unused_variable") + var d = 4 # Warning (if enabled in the Project Settings). +``` + +\ **Note:** To suppress a single warning, use [@warning_ignore](class_@gdscript.md#class_@GDScript_annotation_@warning_ignore) instead. + +\ **Note:** Unlike most other annotations, arguments of the [@warning_ignore_start](class_@gdscript.md#class_@GDScript_annotation_@warning_ignore_start) annotation must be string literals (constant expressions are not supported). + +
+ + + +## Method Descriptions + + + + + +[Color](class_color.md) **Color8**\ (\ r8\: [int](class_int.md), g8\: [int](class_int.md), b8\: [int](class_int.md), a8\: [int](class_int.md) = 255\ ) [🔗](#class_@GDScript_method_Color8) + +**Deprecated:** Use [Color.from_rgba8()](class_color.md#class_Color_method_from_rgba8) instead. + +Returns a [Color](class_color.md) constructed from red (`r8`), green (`g8`), blue (`b8`), and optionally alpha (`a8`) integer channels, each divided by ``255.0`` for their final value. Using [Color8()](class_@gdscript.md#class_@GDScript_method_Color8) instead of the standard [Color](class_color.md) constructor is useful when you need to match exact color values in an [Image](class_image.md). + +``` + var red = Color8(255, 0, 0) # Same as Color(1, 0, 0). + var dark_blue = Color8(0, 0, 51) # Same as Color(0, 0, 0.2). + var my_color = Color8(306, 255, 0, 102) # Same as Color(1.2, 1, 0, 0.4). +``` + +\ **Note:** Due to the lower precision of [Color8()](class_@gdscript.md#class_@GDScript_method_Color8) compared to the standard [Color](class_color.md) constructor, a color created with [Color8()](class_@gdscript.md#class_@GDScript_method_Color8) will generally not be equal to the same color created with the standard [Color](class_color.md) constructor. Use [Color.is_equal_approx()](class_color.md#class_Color_method_is_equal_approx) for comparisons to avoid issues with floating-point precision error. + +
+ + + + + +`void` **assert**\ (\ condition\: [bool](class_bool.md), message\: [String](class_string.md) = ""\ ) [🔗](#class_@GDScript_method_assert) + +Asserts that the `condition` is ``true``. If the `condition` is ``false``, an error is generated. When running from the editor, the running project will also be paused until you resume it. This can be used as a stronger form of [@GlobalScope.push_error()](class_@globalscope.md#class_@GlobalScope_method_push_error) for reporting errors to project developers or add-on users. + +An optional `message` can be shown in addition to the generic "Assertion failed" message. You can use this to provide additional details about why the assertion failed. + +\ **Warning:** For performance reasons, the code inside [assert()](class_@gdscript.md#class_@GDScript_method_assert) is only executed in debug builds or when running the project from the editor. Don't include code that has side effects in an [assert()](class_@gdscript.md#class_@GDScript_method_assert) call. Otherwise, the project will behave differently when exported in release mode. + +``` + # Imagine we always want speed to be between 0 and 20. + var speed = -10 + assert(speed < 20) # True, the program will continue. + assert(speed >= 0) # False, the program will stop. + assert(speed >= 0 and speed < 20) # You can also combine the two conditional statements in one check. + assert(speed < 20, "the speed limit is 20") # Show a message. +``` + +\ **Note:** [assert()](class_@gdscript.md#class_@GDScript_method_assert) is a keyword, not a function. So you cannot access it as a [Callable](class_callable.md) or use it inside expressions. + +
+ + + + + +[String](class_string.md) **char**\ (\ code\: [int](class_int.md)\ ) [🔗](#class_@GDScript_method_char) + +Returns a single character (as a [String](class_string.md) of length 1) of the given Unicode code point `code`. + +``` + print(char(65)) # Prints "A" + print(char(129302)) # Prints "🤖" (robot face emoji) +``` + +This is the inverse of [ord()](class_@gdscript.md#class_@GDScript_method_ord). See also [String.chr()](class_string.md#class_String_method_chr) and [String.unicode_at()](class_string.md#class_String_method_unicode_at). + +
+ + + + + +[Variant](class_variant.md) **convert**\ (\ what\: [Variant](class_variant.md), type\: [Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type)\ ) [🔗](#class_@GDScript_method_convert) + +**Deprecated:** Use [@GlobalScope.type_convert()](class_@globalscope.md#class_@GlobalScope_method_type_convert) instead. + +Converts `what` to `type` in the best way possible. The `type` uses the [Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) values. + +``` + var a = [4, 2.5, 1.2] + print(a is Array) # Prints true + + var b = convert(a, TYPE_PACKED_BYTE_ARRAY) + print(b) # Prints [4, 2, 1] + print(b is Array) # Prints false +``` + +
+ + + + + +[Object](class_object.md) **dict_to_inst**\ (\ dictionary\: [Dictionary](class_dictionary.md)\ ) [🔗](#class_@GDScript_method_dict_to_inst) + +**Deprecated:** Consider using [JSON.to_native()](class_json.md#class_JSON_method_to_native) or [Object.get_property_list()](class_object.md#class_Object_method_get_property_list) instead. + +Converts a `dictionary` (created with [inst_to_dict()](class_@gdscript.md#class_@GDScript_method_inst_to_dict)) back to an Object instance. Can be useful for deserializing. + +
+ + + + + +[Array](class_array.md) **get_stack**\ (\ ) [🔗](#class_@GDScript_method_get_stack) + +Returns an array of dictionaries representing the current call stack. + +``` + func _ready(): + foo() + + func foo(): + bar() + + func bar(): + print(get_stack()) +``` + +Starting from ``_ready()``, ``bar()`` would print: + +```text + [{function:bar, line:12, source:res://script.gd}, {function:foo, line:9, source:res://script.gd}, {function:_ready, line:6, source:res://script.gd}] +``` + +See also [print_debug()](class_@gdscript.md#class_@GDScript_method_print_debug), [print_stack()](class_@gdscript.md#class_@GDScript_method_print_stack), and [Engine.capture_script_backtraces()](class_engine.md#class_Engine_method_capture_script_backtraces). + +\ **Note:** By default, backtraces are only available in editor builds and debug builds. To enable them for release builds as well, you need to enable [ProjectSettings.debug/settings/gdscript/always_track_call_stacks](class_projectsettings.md#class_ProjectSettings_property_debug/settings/gdscript/always_track_call_stacks). + +
+ + + + + +[Dictionary](class_dictionary.md) **inst_to_dict**\ (\ instance\: [Object](class_object.md)\ ) [🔗](#class_@GDScript_method_inst_to_dict) + +**Deprecated:** Consider using [JSON.from_native()](class_json.md#class_JSON_method_from_native) or [Object.get_property_list()](class_object.md#class_Object_method_get_property_list) instead. + +Returns the passed `instance` converted to a [Dictionary](class_dictionary.md). Can be useful for serializing. + +``` + var foo = "bar" + func _ready(): + var d = inst_to_dict(self) + print(d.keys()) + print(d.values()) +``` + +Prints out: + +```text + [@subpath, @path, foo] + [, res://test.gd, bar] +``` + +\ **Note:** This function can only be used to serialize objects with an attached [GDScript](class_gdscript.md) stored in a separate file. Objects without an attached script, with a script written in another language, or with a built-in script are not supported. + +\ **Note:** This function is not recursive, which means that nested objects will not be represented as dictionaries. Also, properties passed by reference ([Object](class_object.md), [Dictionary](class_dictionary.md), [Array](class_array.md), and packed arrays) are copied by reference, not duplicated. + +
+ + + + + +[bool](class_bool.md) **is_instance_of**\ (\ value\: [Variant](class_variant.md), type\: [Variant](class_variant.md)\ ) [🔗](#class_@GDScript_method_is_instance_of) + +Returns ``true`` if `value` is an instance of `type`. The `type` value must be one of the following: + +- A constant from the [Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) enumeration, for example [@GlobalScope.TYPE_INT](class_@globalscope.md#class_@GlobalScope_constant_TYPE_INT). + +- An [Object](class_object.md)-derived class which exists in [ClassDB](class_classdb.md), for example [Node](class_node.md). + +- A [Script](class_script.md) (you can use any class, including inner one). + +Unlike the right operand of the ``is`` operator, `type` can be a non-constant value. The ``is`` operator supports more features (such as typed arrays). Use the operator instead of this method if you do not need to check the type dynamically. + +\ **Examples:**\ + +``` + print(is_instance_of(a, TYPE_INT)) + print(is_instance_of(a, Node)) + print(is_instance_of(a, MyClass)) + print(is_instance_of(a, MyClass.InnerClass)) +``` + +\ **Note:** If `value` and/or `type` are freed objects (see [@GlobalScope.is_instance_valid()](class_@globalscope.md#class_@GlobalScope_method_is_instance_valid)), or `type` is not one of the above options, this method will raise a runtime error. + +See also [@GlobalScope.typeof()](class_@globalscope.md#class_@GlobalScope_method_typeof), [type_exists()](class_@gdscript.md#class_@GDScript_method_type_exists), [Array.is_same_typed()](class_array.md#class_Array_method_is_same_typed) (and other [Array](class_array.md) methods). + +
+ + + + + +[int](class_int.md) **len**\ (\ var\: [Variant](class_variant.md)\ ) [🔗](#class_@GDScript_method_len) + +Returns the length of the given Variant `var`. The length can be the character count of a [String](class_string.md) or [StringName](class_stringname.md), the element count of any array type, or the size of a [Dictionary](class_dictionary.md). For every other Variant type, a run-time error is generated and execution is stopped. + +``` + var a = [1, 2, 3, 4] + len(a) # Returns 4 + + var b = "Hello!" + len(b) # Returns 6 +``` + +
+ + + + + +[Resource](class_resource.md) **load**\ (\ path\: [String](class_string.md)\ ) [🔗](#class_@GDScript_method_load) + +Returns a [Resource](class_resource.md) from the filesystem located at the absolute `path`. Unless it's already referenced elsewhere (such as in another script or in the scene), the resource is loaded from disk on function call, which might cause a slight delay, especially when loading large scenes. To avoid unnecessary delays when loading something multiple times, either store the resource in a variable or use [preload()](class_@gdscript.md#class_@GDScript_method_preload). This method is equivalent of using [ResourceLoader.load()](class_resourceloader.md#class_ResourceLoader_method_load) with [ResourceLoader.CACHE_MODE_REUSE](class_resourceloader.md#class_ResourceLoader_constant_CACHE_MODE_REUSE). + +\ **Note:** Resource paths can be obtained by right-clicking on a resource in the FileSystem dock and choosing "Copy Path", or by dragging the file from the FileSystem dock into the current script. + +``` + # Load a scene called "main" located in the root of the project directory and cache it in a variable. + var main = load("res://main.tscn") # main will contain a PackedScene resource. +``` + +\ **Important:** Relative paths are *not* relative to the script calling this method, instead it is prefixed with ``"res://"``. Loading from relative paths might not work as expected. + +This function is a simplified version of [ResourceLoader.load()](class_resourceloader.md#class_ResourceLoader_method_load), which can be used for more advanced scenarios. + +\ **Note:** Files have to be imported into the engine first to load them using this function. If you want to load [Image](class_image.md)\ s at run-time, you may use [Image.load()](class_image.md#class_Image_method_load). If you want to import audio files, you can use the snippet described in [AudioStreamMP3.data](class_audiostreammp3.md#class_AudioStreamMP3_property_data). + +\ **Note:** If [ProjectSettings.editor/export/convert_text_resources_to_binary](class_projectsettings.md#class_ProjectSettings_property_editor/export/convert_text_resources_to_binary) is ``true``, [load()](class_@gdscript.md#class_@GDScript_method_load) will not be able to read converted files in an exported project. If you rely on run-time loading of files present within the PCK, set [ProjectSettings.editor/export/convert_text_resources_to_binary](class_projectsettings.md#class_ProjectSettings_property_editor/export/convert_text_resources_to_binary) to ``false``. + +
+ + + + + +[int](class_int.md) **ord**\ (\ char\: [String](class_string.md)\ ) [🔗](#class_@GDScript_method_ord) + +Returns an integer representing the Unicode code point of the given character `char`, which should be a string of length 1. + +``` + print(ord("A")) # Prints 65 + print(ord("🤖")) # Prints 129302 +``` + +This is the inverse of [char()](class_@gdscript.md#class_@GDScript_method_char). See also [String.chr()](class_string.md#class_String_method_chr) and [String.unicode_at()](class_string.md#class_String_method_unicode_at). + +
+ + + + + +[Resource](class_resource.md) **preload**\ (\ path\: [String](class_string.md)\ ) [🔗](#class_@GDScript_method_preload) + +Returns a [Resource](class_resource.md) from the filesystem located at `path`. During run-time, the resource is loaded when the script is being parsed. This function effectively acts as a reference to that resource. Note that this function requires `path` to be a constant [String](class_string.md). If you want to load a resource from a dynamic/variable path, use [load()](class_@gdscript.md#class_@GDScript_method_load). + +\ **Note:** Resource paths can be obtained by right-clicking on a resource in the Assets Panel and choosing "Copy Path", or by dragging the file from the FileSystem dock into the current script. + +``` + # Create instance of a scene. + var diamond = preload("res://diamond.tscn").instantiate() +``` + +\ **Note:** [preload()](class_@gdscript.md#class_@GDScript_method_preload) is a keyword, not a function. So you cannot access it as a [Callable](class_callable.md). + +
+ + + + + +`void` **print_debug**\ (\ ...\ ) vararg [🔗](#class_@GDScript_method_print_debug) + +Like [@GlobalScope.print()](class_@globalscope.md#class_@GlobalScope_method_print), but includes the current stack frame when running with the debugger turned on. + +The output in the console may look like the following: + +```text + Test print + At: res://test.gd:15:_process() +``` + +See also [print_stack()](class_@gdscript.md#class_@GDScript_method_print_stack), [get_stack()](class_@gdscript.md#class_@GDScript_method_get_stack), and [Engine.capture_script_backtraces()](class_engine.md#class_Engine_method_capture_script_backtraces). + +\ **Note:** By default, backtraces are only available in editor builds and debug builds. To enable them for release builds as well, you need to enable [ProjectSettings.debug/settings/gdscript/always_track_call_stacks](class_projectsettings.md#class_ProjectSettings_property_debug/settings/gdscript/always_track_call_stacks). + +
+ + + + + +`void` **print_stack**\ (\ ) [🔗](#class_@GDScript_method_print_stack) + +Prints a stack trace at the current code location. + +The output in the console may look like the following: + +```text + Frame 0 - res://test.gd:16 in function '_process' +``` + +See also [print_debug()](class_@gdscript.md#class_@GDScript_method_print_debug), [get_stack()](class_@gdscript.md#class_@GDScript_method_get_stack), and [Engine.capture_script_backtraces()](class_engine.md#class_Engine_method_capture_script_backtraces). + +\ **Note:** By default, backtraces are only available in editor builds and debug builds. To enable them for release builds as well, you need to enable [ProjectSettings.debug/settings/gdscript/always_track_call_stacks](class_projectsettings.md#class_ProjectSettings_property_debug/settings/gdscript/always_track_call_stacks). + +
+ + + + + +[Array](class_array.md) **range**\ (\ ...\ ) vararg [🔗](#class_@GDScript_method_range) + +Returns an array with the given range. [range()](class_@gdscript.md#class_@GDScript_method_range) can be called in three ways: + +\ ``range(n: int)``: Starts from 0, increases by steps of 1, and stops *before* ``n``. The argument ``n`` is **exclusive**. + +\ ``range(b: int, n: int)``: Starts from ``b``, increases by steps of 1, and stops *before* ``n``. The arguments ``b`` and ``n`` are **inclusive** and **exclusive**, respectively. + +\ ``range(b: int, n: int, s: int)``: Starts from ``b``, increases/decreases by steps of ``s``, and stops *before* ``n``. The arguments ``b`` and ``n`` are **inclusive** and **exclusive**, respectively. The argument ``s`` **can** be negative, but not ``0``. If ``s`` is ``0``, an error message is printed. + +\ [range()](class_@gdscript.md#class_@GDScript_method_range) converts all arguments to [int](class_int.md) before processing. + +\ **Note:** Returns an empty array if no value meets the value constraint (e.g. ``range(2, 5, -1)`` or ``range(5, 5, 1)``). + +\ **Examples:**\ + +``` + print(range(4)) # Prints [0, 1, 2, 3] + print(range(2, 5)) # Prints [2, 3, 4] + print(range(0, 6, 2)) # Prints [0, 2, 4] + print(range(4, 1, -1)) # Prints [4, 3, 2] +``` + +To iterate over an [Array](class_array.md) backwards, use: + +``` + var array = [3, 6, 9] + for i in range(array.size() - 1, -1, -1): + print(array[i]) +``` + +Output: + +```text + 9 + 6 + 3 +``` + +To iterate over [float](class_float.md), convert them in the loop. + +``` + for i in range (3, 0, -1): + print(i / 10.0) +``` + +Output: + +```text + 0.3 + 0.2 + 0.1 +``` + +
+ + + + + +[bool](class_bool.md) **type_exists**\ (\ type\: [StringName](class_stringname.md)\ ) [🔗](#class_@GDScript_method_type_exists) + +Returns ``true`` if the given [Object](class_object.md)-derived class exists in [ClassDB](class_classdb.md). Note that [Variant](class_variant.md) data types are not registered in [ClassDB](class_classdb.md). + +``` + type_exists("Sprite2D") # Returns true + type_exists("NonExistentClass") # Returns false +``` + diff --git a/docs/Classes/class_@globalscope.md b/docs/Classes/class_@globalscope.md new file mode 100644 index 00000000..353454b0 --- /dev/null +++ b/docs/Classes/class_@globalscope.md @@ -0,0 +1,6686 @@ + + + + + + + + + +# @GlobalScope + +Global scope constants and functions. + + + +## Description + +A list of global scope enumerated constants and built-in functions. This is all that resides in the globals, constants regarding error codes, keycodes, property hints, etc. + +Singletons are also documented here, since they can be accessed from anywhere. + +For the entries that can only be accessed from scripts written in GDScript, see [@GDScript](class_@gdscript.md). + +
+There are notable differences when using this API with C#. See the C# differences documentation for more information. + +
+ + + +## Tutorials + +- [Random number generation](../tutorials/math/random_number_generation.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[AudioServer](class_audioserver.md)[AudioServer](#class_@GlobalScope_property_AudioServer)
[CameraServer](class_cameraserver.md)[CameraServer](#class_@GlobalScope_property_CameraServer)
[ClassDB](class_classdb.md)[ClassDB](#class_@GlobalScope_property_ClassDB)
[DisplayServer](class_displayserver.md)[DisplayServer](#class_@GlobalScope_property_DisplayServer)
[EditorInterface](class_editorinterface.md)[EditorInterface](#class_@GlobalScope_property_EditorInterface)
[Engine](class_engine.md)[Engine](#class_@GlobalScope_property_Engine)
[EngineDebugger](class_enginedebugger.md)[EngineDebugger](#class_@GlobalScope_property_EngineDebugger)
[GDExtensionManager](class_gdextensionmanager.md)[GDExtensionManager](#class_@GlobalScope_property_GDExtensionManager)
[Geometry2D](class_geometry2d.md)[Geometry2D](#class_@GlobalScope_property_Geometry2D)
[Geometry3D](class_geometry3d.md)[Geometry3D](#class_@GlobalScope_property_Geometry3D)
[IP](class_ip.md)[IP](#class_@GlobalScope_property_IP)
[Input](class_input.md)[Input](#class_@GlobalScope_property_Input)
[InputMap](class_inputmap.md)[InputMap](#class_@GlobalScope_property_InputMap)
[JavaClassWrapper](class_javaclasswrapper.md)[JavaClassWrapper](#class_@GlobalScope_property_JavaClassWrapper)
[JavaScriptBridge](class_javascriptbridge.md)[JavaScriptBridge](#class_@GlobalScope_property_JavaScriptBridge)
[MCPBridge](class_mcpbridge.md)[MCPBridge](#class_@GlobalScope_property_MCPBridge)
[MCPServer](class_mcpserver.md)[MCPServer](#class_@GlobalScope_property_MCPServer)
[Marshalls](class_marshalls.md)[Marshalls](#class_@GlobalScope_property_Marshalls)
[NativeMenu](class_nativemenu.md)[NativeMenu](#class_@GlobalScope_property_NativeMenu)
[NavigationMeshGenerator](class_navigationmeshgenerator.md)[NavigationMeshGenerator](#class_@GlobalScope_property_NavigationMeshGenerator)
[NavigationServer2D](class_navigationserver2d.md)[NavigationServer2D](#class_@GlobalScope_property_NavigationServer2D)
[NavigationServer3D](class_navigationserver3d.md)[NavigationServer3D](#class_@GlobalScope_property_NavigationServer3D)
[OS](class_os.md)[OS](#class_@GlobalScope_property_OS)
[Performance](class_performance.md)[Performance](#class_@GlobalScope_property_Performance)
[PhysicsServer2D](class_physicsserver2d.md)[PhysicsServer2D](#class_@GlobalScope_property_PhysicsServer2D)
[PhysicsServer2DManager](class_physicsserver2dmanager.md)[PhysicsServer2DManager](#class_@GlobalScope_property_PhysicsServer2DManager)
[PhysicsServer3D](class_physicsserver3d.md)[PhysicsServer3D](#class_@GlobalScope_property_PhysicsServer3D)
[PhysicsServer3DManager](class_physicsserver3dmanager.md)[PhysicsServer3DManager](#class_@GlobalScope_property_PhysicsServer3DManager)
[ProjectSettings](class_projectsettings.md)[ProjectSettings](#class_@GlobalScope_property_ProjectSettings)
[RenderingServer](class_renderingserver.md)[RenderingServer](#class_@GlobalScope_property_RenderingServer)
[ResourceLoader](class_resourceloader.md)[ResourceLoader](#class_@GlobalScope_property_ResourceLoader)
[ResourceSaver](class_resourcesaver.md)[ResourceSaver](#class_@GlobalScope_property_ResourceSaver)
[ResourceUID](class_resourceuid.md)[ResourceUID](#class_@GlobalScope_property_ResourceUID)
[TextServerManager](class_textservermanager.md)[TextServerManager](#class_@GlobalScope_property_TextServerManager)
[ThemeDB](class_themedb.md)[ThemeDB](#class_@GlobalScope_property_ThemeDB)
[Time](class_time.md)[Time](#class_@GlobalScope_property_Time)
[TranslationServer](class_translationserver.md)[TranslationServer](#class_@GlobalScope_property_TranslationServer)
[WorkerThreadPool](class_workerthreadpool.md)[WorkerThreadPool](#class_@GlobalScope_property_WorkerThreadPool)
[XRServer](class_xrserver.md)[XRServer](#class_@GlobalScope_property_XRServer)
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Variant](class_variant.md)[abs](#class_@GlobalScope_method_abs)\ (\ x\: [Variant](class_variant.md)\ )
[float](class_float.md)[absf](#class_@GlobalScope_method_absf)\ (\ x\: [float](class_float.md)\ )
[int](class_int.md)[absi](#class_@GlobalScope_method_absi)\ (\ x\: [int](class_int.md)\ )
[float](class_float.md)[acos](#class_@GlobalScope_method_acos)\ (\ x\: [float](class_float.md)\ )
[float](class_float.md)[acosh](#class_@GlobalScope_method_acosh)\ (\ x\: [float](class_float.md)\ )
[float](class_float.md)[angle_difference](#class_@GlobalScope_method_angle_difference)\ (\ from\: [float](class_float.md), to\: [float](class_float.md)\ )
[float](class_float.md)[asin](#class_@GlobalScope_method_asin)\ (\ x\: [float](class_float.md)\ )
[float](class_float.md)[asinh](#class_@GlobalScope_method_asinh)\ (\ x\: [float](class_float.md)\ )
[float](class_float.md)[atan](#class_@GlobalScope_method_atan)\ (\ x\: [float](class_float.md)\ )
[float](class_float.md)[atan2](#class_@GlobalScope_method_atan2)\ (\ y\: [float](class_float.md), x\: [float](class_float.md)\ )
[float](class_float.md)[atanh](#class_@GlobalScope_method_atanh)\ (\ x\: [float](class_float.md)\ )
[float](class_float.md)[bezier_derivative](#class_@GlobalScope_method_bezier_derivative)\ (\ start\: [float](class_float.md), control_1\: [float](class_float.md), control_2\: [float](class_float.md), end\: [float](class_float.md), t\: [float](class_float.md)\ )
[float](class_float.md)[bezier_interpolate](#class_@GlobalScope_method_bezier_interpolate)\ (\ start\: [float](class_float.md), control_1\: [float](class_float.md), control_2\: [float](class_float.md), end\: [float](class_float.md), t\: [float](class_float.md)\ )
[Variant](class_variant.md)[bytes_to_var](#class_@GlobalScope_method_bytes_to_var)\ (\ bytes\: [PackedByteArray](class_packedbytearray.md)\ )
[Variant](class_variant.md)[bytes_to_var_with_objects](#class_@GlobalScope_method_bytes_to_var_with_objects)\ (\ bytes\: [PackedByteArray](class_packedbytearray.md)\ )
[Variant](class_variant.md)[ceil](#class_@GlobalScope_method_ceil)\ (\ x\: [Variant](class_variant.md)\ )
[float](class_float.md)[ceilf](#class_@GlobalScope_method_ceilf)\ (\ x\: [float](class_float.md)\ )
[int](class_int.md)[ceili](#class_@GlobalScope_method_ceili)\ (\ x\: [float](class_float.md)\ )
[Variant](class_variant.md)[clamp](#class_@GlobalScope_method_clamp)\ (\ value\: [Variant](class_variant.md), min\: [Variant](class_variant.md), max\: [Variant](class_variant.md)\ )
[float](class_float.md)[clampf](#class_@GlobalScope_method_clampf)\ (\ value\: [float](class_float.md), min\: [float](class_float.md), max\: [float](class_float.md)\ )
[int](class_int.md)[clampi](#class_@GlobalScope_method_clampi)\ (\ value\: [int](class_int.md), min\: [int](class_int.md), max\: [int](class_int.md)\ )
[float](class_float.md)[cos](#class_@GlobalScope_method_cos)\ (\ angle_rad\: [float](class_float.md)\ )
[float](class_float.md)[cosh](#class_@GlobalScope_method_cosh)\ (\ x\: [float](class_float.md)\ )
[float](class_float.md)[cubic_interpolate](#class_@GlobalScope_method_cubic_interpolate)\ (\ from\: [float](class_float.md), to\: [float](class_float.md), pre\: [float](class_float.md), post\: [float](class_float.md), weight\: [float](class_float.md)\ )
[float](class_float.md)[cubic_interpolate_angle](#class_@GlobalScope_method_cubic_interpolate_angle)\ (\ from\: [float](class_float.md), to\: [float](class_float.md), pre\: [float](class_float.md), post\: [float](class_float.md), weight\: [float](class_float.md)\ )
[float](class_float.md)[cubic_interpolate_angle_in_time](#class_@GlobalScope_method_cubic_interpolate_angle_in_time)\ (\ from\: [float](class_float.md), to\: [float](class_float.md), pre\: [float](class_float.md), post\: [float](class_float.md), weight\: [float](class_float.md), to_t\: [float](class_float.md), pre_t\: [float](class_float.md), post_t\: [float](class_float.md)\ )
[float](class_float.md)[cubic_interpolate_in_time](#class_@GlobalScope_method_cubic_interpolate_in_time)\ (\ from\: [float](class_float.md), to\: [float](class_float.md), pre\: [float](class_float.md), post\: [float](class_float.md), weight\: [float](class_float.md), to_t\: [float](class_float.md), pre_t\: [float](class_float.md), post_t\: [float](class_float.md)\ )
[float](class_float.md)[db_to_linear](#class_@GlobalScope_method_db_to_linear)\ (\ db\: [float](class_float.md)\ )
[float](class_float.md)[deg_to_rad](#class_@GlobalScope_method_deg_to_rad)\ (\ deg\: [float](class_float.md)\ )
[float](class_float.md)[ease](#class_@GlobalScope_method_ease)\ (\ x\: [float](class_float.md), curve\: [float](class_float.md)\ )
[String](class_string.md)[error_string](#class_@GlobalScope_method_error_string)\ (\ error\: [int](class_int.md)\ )
[float](class_float.md)[exp](#class_@GlobalScope_method_exp)\ (\ x\: [float](class_float.md)\ )
[Variant](class_variant.md)[floor](#class_@GlobalScope_method_floor)\ (\ x\: [Variant](class_variant.md)\ )
[float](class_float.md)[floorf](#class_@GlobalScope_method_floorf)\ (\ x\: [float](class_float.md)\ )
[int](class_int.md)[floori](#class_@GlobalScope_method_floori)\ (\ x\: [float](class_float.md)\ )
[float](class_float.md)[fmod](#class_@GlobalScope_method_fmod)\ (\ x\: [float](class_float.md), y\: [float](class_float.md)\ )
[float](class_float.md)[fposmod](#class_@GlobalScope_method_fposmod)\ (\ x\: [float](class_float.md), y\: [float](class_float.md)\ )
[int](class_int.md)[hash](#class_@GlobalScope_method_hash)\ (\ variable\: [Variant](class_variant.md)\ )
[Object](class_object.md)[instance_from_id](#class_@GlobalScope_method_instance_from_id)\ (\ instance_id\: [int](class_int.md)\ )
[float](class_float.md)[inverse_lerp](#class_@GlobalScope_method_inverse_lerp)\ (\ from\: [float](class_float.md), to\: [float](class_float.md), weight\: [float](class_float.md)\ )
[bool](class_bool.md)[is_equal_approx](#class_@GlobalScope_method_is_equal_approx)\ (\ a\: [float](class_float.md), b\: [float](class_float.md)\ )
[bool](class_bool.md)[is_finite](#class_@GlobalScope_method_is_finite)\ (\ x\: [float](class_float.md)\ )
[bool](class_bool.md)[is_inf](#class_@GlobalScope_method_is_inf)\ (\ x\: [float](class_float.md)\ )
[bool](class_bool.md)[is_instance_id_valid](#class_@GlobalScope_method_is_instance_id_valid)\ (\ id\: [int](class_int.md)\ )
[bool](class_bool.md)[is_instance_valid](#class_@GlobalScope_method_is_instance_valid)\ (\ instance\: [Variant](class_variant.md)\ )
[bool](class_bool.md)[is_nan](#class_@GlobalScope_method_is_nan)\ (\ x\: [float](class_float.md)\ )
[bool](class_bool.md)[is_same](#class_@GlobalScope_method_is_same)\ (\ a\: [Variant](class_variant.md), b\: [Variant](class_variant.md)\ )
[bool](class_bool.md)[is_zero_approx](#class_@GlobalScope_method_is_zero_approx)\ (\ x\: [float](class_float.md)\ )
[Variant](class_variant.md)[lerp](#class_@GlobalScope_method_lerp)\ (\ from\: [Variant](class_variant.md), to\: [Variant](class_variant.md), weight\: [Variant](class_variant.md)\ )
[float](class_float.md)[lerp_angle](#class_@GlobalScope_method_lerp_angle)\ (\ from\: [float](class_float.md), to\: [float](class_float.md), weight\: [float](class_float.md)\ )
[float](class_float.md)[lerpf](#class_@GlobalScope_method_lerpf)\ (\ from\: [float](class_float.md), to\: [float](class_float.md), weight\: [float](class_float.md)\ )
[float](class_float.md)[linear_to_db](#class_@GlobalScope_method_linear_to_db)\ (\ lin\: [float](class_float.md)\ )
[float](class_float.md)[log](#class_@GlobalScope_method_log)\ (\ x\: [float](class_float.md)\ )
[Variant](class_variant.md)[max](#class_@GlobalScope_method_max)\ (\ ...\ ) vararg
[float](class_float.md)[maxf](#class_@GlobalScope_method_maxf)\ (\ a\: [float](class_float.md), b\: [float](class_float.md)\ )
[int](class_int.md)[maxi](#class_@GlobalScope_method_maxi)\ (\ a\: [int](class_int.md), b\: [int](class_int.md)\ )
[Variant](class_variant.md)[min](#class_@GlobalScope_method_min)\ (\ ...\ ) vararg
[float](class_float.md)[minf](#class_@GlobalScope_method_minf)\ (\ a\: [float](class_float.md), b\: [float](class_float.md)\ )
[int](class_int.md)[mini](#class_@GlobalScope_method_mini)\ (\ a\: [int](class_int.md), b\: [int](class_int.md)\ )
[float](class_float.md)[move_toward](#class_@GlobalScope_method_move_toward)\ (\ from\: [float](class_float.md), to\: [float](class_float.md), delta\: [float](class_float.md)\ )
[int](class_int.md)[nearest_po2](#class_@GlobalScope_method_nearest_po2)\ (\ value\: [int](class_int.md)\ )
[float](class_float.md)[pingpong](#class_@GlobalScope_method_pingpong)\ (\ value\: [float](class_float.md), length\: [float](class_float.md)\ )
[int](class_int.md)[posmod](#class_@GlobalScope_method_posmod)\ (\ x\: [int](class_int.md), y\: [int](class_int.md)\ )
[float](class_float.md)[pow](#class_@GlobalScope_method_pow)\ (\ base\: [float](class_float.md), exp\: [float](class_float.md)\ )
`void`[print](#class_@GlobalScope_method_print)\ (\ ...\ ) vararg
`void`[print_rich](#class_@GlobalScope_method_print_rich)\ (\ ...\ ) vararg
`void`[print_verbose](#class_@GlobalScope_method_print_verbose)\ (\ ...\ ) vararg
`void`[printerr](#class_@GlobalScope_method_printerr)\ (\ ...\ ) vararg
`void`[printraw](#class_@GlobalScope_method_printraw)\ (\ ...\ ) vararg
`void`[prints](#class_@GlobalScope_method_prints)\ (\ ...\ ) vararg
`void`[printt](#class_@GlobalScope_method_printt)\ (\ ...\ ) vararg
`void`[push_error](#class_@GlobalScope_method_push_error)\ (\ ...\ ) vararg
`void`[push_warning](#class_@GlobalScope_method_push_warning)\ (\ ...\ ) vararg
[float](class_float.md)[rad_to_deg](#class_@GlobalScope_method_rad_to_deg)\ (\ rad\: [float](class_float.md)\ )
[PackedInt64Array](class_packedint64array.md)[rand_from_seed](#class_@GlobalScope_method_rand_from_seed)\ (\ seed\: [int](class_int.md)\ )
[float](class_float.md)[randf](#class_@GlobalScope_method_randf)\ (\ )
[float](class_float.md)[randf_range](#class_@GlobalScope_method_randf_range)\ (\ from\: [float](class_float.md), to\: [float](class_float.md)\ )
[float](class_float.md)[randfn](#class_@GlobalScope_method_randfn)\ (\ mean\: [float](class_float.md), deviation\: [float](class_float.md)\ )
[int](class_int.md)[randi](#class_@GlobalScope_method_randi)\ (\ )
[int](class_int.md)[randi_range](#class_@GlobalScope_method_randi_range)\ (\ from\: [int](class_int.md), to\: [int](class_int.md)\ )
`void`[randomize](#class_@GlobalScope_method_randomize)\ (\ )
[float](class_float.md)[remap](#class_@GlobalScope_method_remap)\ (\ value\: [float](class_float.md), istart\: [float](class_float.md), istop\: [float](class_float.md), ostart\: [float](class_float.md), ostop\: [float](class_float.md)\ )
[int](class_int.md)[rid_allocate_id](#class_@GlobalScope_method_rid_allocate_id)\ (\ )
[RID](class_rid.md)[rid_from_int64](#class_@GlobalScope_method_rid_from_int64)\ (\ base\: [int](class_int.md)\ )
[float](class_float.md)[rotate_toward](#class_@GlobalScope_method_rotate_toward)\ (\ from\: [float](class_float.md), to\: [float](class_float.md), delta\: [float](class_float.md)\ )
[Variant](class_variant.md)[round](#class_@GlobalScope_method_round)\ (\ x\: [Variant](class_variant.md)\ )
[float](class_float.md)[roundf](#class_@GlobalScope_method_roundf)\ (\ x\: [float](class_float.md)\ )
[int](class_int.md)[roundi](#class_@GlobalScope_method_roundi)\ (\ x\: [float](class_float.md)\ )
`void`[seed](#class_@GlobalScope_method_seed)\ (\ base\: [int](class_int.md)\ )
[float](class_float.md)[sigmoid](#class_@GlobalScope_method_sigmoid)\ (\ x\: [float](class_float.md)\ )
[float](class_float.md)[sigmoid_affine](#class_@GlobalScope_method_sigmoid_affine)\ (\ x\: [float](class_float.md), amplitude\: [float](class_float.md), y_translation\: [float](class_float.md)\ )
[float](class_float.md)[sigmoid_affine_approx](#class_@GlobalScope_method_sigmoid_affine_approx)\ (\ x\: [float](class_float.md), amplitude\: [float](class_float.md), y_translation\: [float](class_float.md)\ )
[float](class_float.md)[sigmoid_approx](#class_@GlobalScope_method_sigmoid_approx)\ (\ x\: [float](class_float.md)\ )
[Variant](class_variant.md)[sign](#class_@GlobalScope_method_sign)\ (\ x\: [Variant](class_variant.md)\ )
[float](class_float.md)[signf](#class_@GlobalScope_method_signf)\ (\ x\: [float](class_float.md)\ )
[int](class_int.md)[signi](#class_@GlobalScope_method_signi)\ (\ x\: [int](class_int.md)\ )
[float](class_float.md)[sin](#class_@GlobalScope_method_sin)\ (\ angle_rad\: [float](class_float.md)\ )
[float](class_float.md)[sinh](#class_@GlobalScope_method_sinh)\ (\ x\: [float](class_float.md)\ )
[float](class_float.md)[smoothstep](#class_@GlobalScope_method_smoothstep)\ (\ from\: [float](class_float.md), to\: [float](class_float.md), x\: [float](class_float.md)\ )
[Variant](class_variant.md)[snapped](#class_@GlobalScope_method_snapped)\ (\ x\: [Variant](class_variant.md), step\: [Variant](class_variant.md)\ )
[float](class_float.md)[snappedf](#class_@GlobalScope_method_snappedf)\ (\ x\: [float](class_float.md), step\: [float](class_float.md)\ )
[int](class_int.md)[snappedi](#class_@GlobalScope_method_snappedi)\ (\ x\: [float](class_float.md), step\: [int](class_int.md)\ )
[float](class_float.md)[sqrt](#class_@GlobalScope_method_sqrt)\ (\ x\: [float](class_float.md)\ )
[int](class_int.md)[step_decimals](#class_@GlobalScope_method_step_decimals)\ (\ x\: [float](class_float.md)\ )
[String](class_string.md)[str](#class_@GlobalScope_method_str)\ (\ ...\ ) vararg
[Variant](class_variant.md)[str_to_var](#class_@GlobalScope_method_str_to_var)\ (\ string\: [String](class_string.md)\ )
[Variant](class_variant.md)[str_to_var_with_objects](#class_@GlobalScope_method_str_to_var_with_objects)\ (\ string\: [String](class_string.md)\ )
[float](class_float.md)[tan](#class_@GlobalScope_method_tan)\ (\ angle_rad\: [float](class_float.md)\ )
[float](class_float.md)[tanh](#class_@GlobalScope_method_tanh)\ (\ x\: [float](class_float.md)\ )
[Variant](class_variant.md)[type_convert](#class_@GlobalScope_method_type_convert)\ (\ variant\: [Variant](class_variant.md), type\: [int](class_int.md)\ )
[String](class_string.md)[type_string](#class_@GlobalScope_method_type_string)\ (\ type\: [int](class_int.md)\ )
[int](class_int.md)[typeof](#class_@GlobalScope_method_typeof)\ (\ variable\: [Variant](class_variant.md)\ )
[PackedByteArray](class_packedbytearray.md)[var_to_bytes](#class_@GlobalScope_method_var_to_bytes)\ (\ variable\: [Variant](class_variant.md)\ )
[PackedByteArray](class_packedbytearray.md)[var_to_bytes_with_objects](#class_@GlobalScope_method_var_to_bytes_with_objects)\ (\ variable\: [Variant](class_variant.md)\ )
[String](class_string.md)[var_to_str](#class_@GlobalScope_method_var_to_str)\ (\ variable\: [Variant](class_variant.md)\ )
[String](class_string.md)[var_to_str_with_objects](#class_@GlobalScope_method_var_to_str_with_objects)\ (\ variable\: [Variant](class_variant.md)\ )
[Variant](class_variant.md)[weakref](#class_@GlobalScope_method_weakref)\ (\ obj\: [Variant](class_variant.md)\ )
[Variant](class_variant.md)[wrap](#class_@GlobalScope_method_wrap)\ (\ value\: [Variant](class_variant.md), min\: [Variant](class_variant.md), max\: [Variant](class_variant.md)\ )
[float](class_float.md)[wrapf](#class_@GlobalScope_method_wrapf)\ (\ value\: [float](class_float.md), min\: [float](class_float.md), max\: [float](class_float.md)\ )
[int](class_int.md)[wrapi](#class_@GlobalScope_method_wrapi)\ (\ value\: [int](class_int.md), min\: [int](class_int.md), max\: [int](class_int.md)\ )
+ +
+ + + +## Enumerations + + + + + +enum **Side**: [🔗](#enum_@GlobalScope_Side) + + + + + +[Side](class_@globalscope.md#enum_@GlobalScope_Side) **SIDE_LEFT** = `0` + +Left side, usually used for [Control](class_control.md) or [StyleBox](class_stylebox.md)-derived classes. + + + +[Side](class_@globalscope.md#enum_@GlobalScope_Side) **SIDE_TOP** = `1` + +Top side, usually used for [Control](class_control.md) or [StyleBox](class_stylebox.md)-derived classes. + + + +[Side](class_@globalscope.md#enum_@GlobalScope_Side) **SIDE_RIGHT** = `2` + +Right side, usually used for [Control](class_control.md) or [StyleBox](class_stylebox.md)-derived classes. + + + +[Side](class_@globalscope.md#enum_@GlobalScope_Side) **SIDE_BOTTOM** = `3` + +Bottom side, usually used for [Control](class_control.md) or [StyleBox](class_stylebox.md)-derived classes.
+ + + + + +enum **Corner**: [🔗](#enum_@GlobalScope_Corner) + + + + + +[Corner](class_@globalscope.md#enum_@GlobalScope_Corner) **CORNER_TOP_LEFT** = `0` + +Top-left corner. + + + +[Corner](class_@globalscope.md#enum_@GlobalScope_Corner) **CORNER_TOP_RIGHT** = `1` + +Top-right corner. + + + +[Corner](class_@globalscope.md#enum_@GlobalScope_Corner) **CORNER_BOTTOM_RIGHT** = `2` + +Bottom-right corner. + + + +[Corner](class_@globalscope.md#enum_@GlobalScope_Corner) **CORNER_BOTTOM_LEFT** = `3` + +Bottom-left corner.
+ + + + + +enum **Orientation**: [🔗](#enum_@GlobalScope_Orientation) + + + + + +[Orientation](class_@globalscope.md#enum_@GlobalScope_Orientation) **VERTICAL** = `1` + +General vertical alignment, usually used for [Separator](class_separator.md), [ScrollBar](class_scrollbar.md), [Slider](class_slider.md), etc. + + + +[Orientation](class_@globalscope.md#enum_@GlobalScope_Orientation) **HORIZONTAL** = `0` + +General horizontal alignment, usually used for [Separator](class_separator.md), [ScrollBar](class_scrollbar.md), [Slider](class_slider.md), etc.
+ + + + + +enum **ClockDirection**: [🔗](#enum_@GlobalScope_ClockDirection) + + + + + +[ClockDirection](class_@globalscope.md#enum_@GlobalScope_ClockDirection) **CLOCKWISE** = `0` + +Clockwise rotation. Used by some methods (e.g. [Image.rotate_90()](class_image.md#class_Image_method_rotate_90)). + + + +[ClockDirection](class_@globalscope.md#enum_@GlobalScope_ClockDirection) **COUNTERCLOCKWISE** = `1` + +Counter-clockwise rotation. Used by some methods (e.g. [Image.rotate_90()](class_image.md#class_Image_method_rotate_90)).
+ + + + + +enum **HorizontalAlignment**: [🔗](#enum_@GlobalScope_HorizontalAlignment) + + + + + +[HorizontalAlignment](class_@globalscope.md#enum_@GlobalScope_HorizontalAlignment) **HORIZONTAL_ALIGNMENT_LEFT** = `0` + +Horizontal left alignment, usually for text-derived classes. + + + +[HorizontalAlignment](class_@globalscope.md#enum_@GlobalScope_HorizontalAlignment) **HORIZONTAL_ALIGNMENT_CENTER** = `1` + +Horizontal center alignment, usually for text-derived classes. + + + +[HorizontalAlignment](class_@globalscope.md#enum_@GlobalScope_HorizontalAlignment) **HORIZONTAL_ALIGNMENT_RIGHT** = `2` + +Horizontal right alignment, usually for text-derived classes. + + + +[HorizontalAlignment](class_@globalscope.md#enum_@GlobalScope_HorizontalAlignment) **HORIZONTAL_ALIGNMENT_FILL** = `3` + +Expand row to fit width, usually for text-derived classes.
+ + + + + +enum **VerticalAlignment**: [🔗](#enum_@GlobalScope_VerticalAlignment) + + + + + +[VerticalAlignment](class_@globalscope.md#enum_@GlobalScope_VerticalAlignment) **VERTICAL_ALIGNMENT_TOP** = `0` + +Vertical top alignment, usually for text-derived classes. + + + +[VerticalAlignment](class_@globalscope.md#enum_@GlobalScope_VerticalAlignment) **VERTICAL_ALIGNMENT_CENTER** = `1` + +Vertical center alignment, usually for text-derived classes. + + + +[VerticalAlignment](class_@globalscope.md#enum_@GlobalScope_VerticalAlignment) **VERTICAL_ALIGNMENT_BOTTOM** = `2` + +Vertical bottom alignment, usually for text-derived classes. + + + +[VerticalAlignment](class_@globalscope.md#enum_@GlobalScope_VerticalAlignment) **VERTICAL_ALIGNMENT_FILL** = `3` + +Expand rows to fit height, usually for text-derived classes.
+ + + + + +enum **InlineAlignment**: [🔗](#enum_@GlobalScope_InlineAlignment) + + + + + +[InlineAlignment](class_@globalscope.md#enum_@GlobalScope_InlineAlignment) **INLINE_ALIGNMENT_TOP_TO** = `0` + +Aligns the top of the inline object (e.g. image, table) to the position of the text specified by ``INLINE_ALIGNMENT_TO_*`` constant. + + + +[InlineAlignment](class_@globalscope.md#enum_@GlobalScope_InlineAlignment) **INLINE_ALIGNMENT_CENTER_TO** = `1` + +Aligns the center of the inline object (e.g. image, table) to the position of the text specified by ``INLINE_ALIGNMENT_TO_*`` constant. + + + +[InlineAlignment](class_@globalscope.md#enum_@GlobalScope_InlineAlignment) **INLINE_ALIGNMENT_BASELINE_TO** = `3` + +Aligns the baseline (user defined) of the inline object (e.g. image, table) to the position of the text specified by ``INLINE_ALIGNMENT_TO_*`` constant. + + + +[InlineAlignment](class_@globalscope.md#enum_@GlobalScope_InlineAlignment) **INLINE_ALIGNMENT_BOTTOM_TO** = `2` + +Aligns the bottom of the inline object (e.g. image, table) to the position of the text specified by ``INLINE_ALIGNMENT_TO_*`` constant. + + + +[InlineAlignment](class_@globalscope.md#enum_@GlobalScope_InlineAlignment) **INLINE_ALIGNMENT_TO_TOP** = `0` + +Aligns the position of the inline object (e.g. image, table) specified by ``INLINE_ALIGNMENT_*_TO`` constant to the top of the text. + + + +[InlineAlignment](class_@globalscope.md#enum_@GlobalScope_InlineAlignment) **INLINE_ALIGNMENT_TO_CENTER** = `4` + +Aligns the position of the inline object (e.g. image, table) specified by ``INLINE_ALIGNMENT_*_TO`` constant to the center of the text. + + + +[InlineAlignment](class_@globalscope.md#enum_@GlobalScope_InlineAlignment) **INLINE_ALIGNMENT_TO_BASELINE** = `8` + +Aligns the position of the inline object (e.g. image, table) specified by ``INLINE_ALIGNMENT_*_TO`` constant to the baseline of the text. + + + +[InlineAlignment](class_@globalscope.md#enum_@GlobalScope_InlineAlignment) **INLINE_ALIGNMENT_TO_BOTTOM** = `12` + +Aligns inline object (e.g. image, table) to the bottom of the text. + + + +[InlineAlignment](class_@globalscope.md#enum_@GlobalScope_InlineAlignment) **INLINE_ALIGNMENT_TOP** = `0` + +Aligns top of the inline object (e.g. image, table) to the top of the text. Equivalent to ``INLINE_ALIGNMENT_TOP_TO | INLINE_ALIGNMENT_TO_TOP``. + + + +[InlineAlignment](class_@globalscope.md#enum_@GlobalScope_InlineAlignment) **INLINE_ALIGNMENT_CENTER** = `5` + +Aligns center of the inline object (e.g. image, table) to the center of the text. Equivalent to ``INLINE_ALIGNMENT_CENTER_TO | INLINE_ALIGNMENT_TO_CENTER``. + + + +[InlineAlignment](class_@globalscope.md#enum_@GlobalScope_InlineAlignment) **INLINE_ALIGNMENT_BOTTOM** = `14` + +Aligns bottom of the inline object (e.g. image, table) to the bottom of the text. Equivalent to ``INLINE_ALIGNMENT_BOTTOM_TO | INLINE_ALIGNMENT_TO_BOTTOM``. + + + +[InlineAlignment](class_@globalscope.md#enum_@GlobalScope_InlineAlignment) **INLINE_ALIGNMENT_IMAGE_MASK** = `3` + +A bit mask for ``INLINE_ALIGNMENT_*_TO`` alignment constants. + + + +[InlineAlignment](class_@globalscope.md#enum_@GlobalScope_InlineAlignment) **INLINE_ALIGNMENT_TEXT_MASK** = `12` + +A bit mask for ``INLINE_ALIGNMENT_TO_*`` alignment constants.
+ + + + + +enum **EulerOrder**: [🔗](#enum_@GlobalScope_EulerOrder) + + + + + +[EulerOrder](class_@globalscope.md#enum_@GlobalScope_EulerOrder) **EULER_ORDER_XYZ** = `0` + +Specifies that Euler angles should be in XYZ order. When composing, the order is X, Y, Z. When decomposing, the order is reversed, first Z, then Y, and X last. + + + +[EulerOrder](class_@globalscope.md#enum_@GlobalScope_EulerOrder) **EULER_ORDER_XZY** = `1` + +Specifies that Euler angles should be in XZY order. When composing, the order is X, Z, Y. When decomposing, the order is reversed, first Y, then Z, and X last. + + + +[EulerOrder](class_@globalscope.md#enum_@GlobalScope_EulerOrder) **EULER_ORDER_YXZ** = `2` + +Specifies that Euler angles should be in YXZ order. When composing, the order is Y, X, Z. When decomposing, the order is reversed, first Z, then X, and Y last. + + + +[EulerOrder](class_@globalscope.md#enum_@GlobalScope_EulerOrder) **EULER_ORDER_YZX** = `3` + +Specifies that Euler angles should be in YZX order. When composing, the order is Y, Z, X. When decomposing, the order is reversed, first X, then Z, and Y last. + + + +[EulerOrder](class_@globalscope.md#enum_@GlobalScope_EulerOrder) **EULER_ORDER_ZXY** = `4` + +Specifies that Euler angles should be in ZXY order. When composing, the order is Z, X, Y. When decomposing, the order is reversed, first Y, then X, and Z last. + + + +[EulerOrder](class_@globalscope.md#enum_@GlobalScope_EulerOrder) **EULER_ORDER_ZYX** = `5` + +Specifies that Euler angles should be in ZYX order. When composing, the order is Z, Y, X. When decomposing, the order is reversed, first X, then Y, and Z last.
+ + + + + +enum **Key**: [🔗](#enum_@GlobalScope_Key) + + + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_NONE** = `0` + +Enum value which doesn't correspond to any key. This is used to initialize [Key](class_@globalscope.md#enum_@GlobalScope_Key) properties with a generic state. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_SPECIAL** = `4194304` + +Keycodes with this bit applied are non-printable. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_ESCAPE** = `4194305` + +Escape key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_TAB** = `4194306` + +Tab key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_BACKTAB** = `4194307` + +Shift + Tab key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_BACKSPACE** = `4194308` + +Backspace key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_ENTER** = `4194309` + +Return key (on the main keyboard). + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_KP_ENTER** = `4194310` + +Enter key on the numeric keypad. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_INSERT** = `4194311` + +Insert key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_DELETE** = `4194312` + +Delete key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_PAUSE** = `4194313` + +Pause key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_PRINT** = `4194314` + +Print Screen key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_SYSREQ** = `4194315` + +System Request key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_CLEAR** = `4194316` + +Clear key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_HOME** = `4194317` + +Home key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_END** = `4194318` + +End key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_LEFT** = `4194319` + +Left arrow key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_UP** = `4194320` + +Up arrow key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_RIGHT** = `4194321` + +Right arrow key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_DOWN** = `4194322` + +Down arrow key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_PAGEUP** = `4194323` + +Page Up key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_PAGEDOWN** = `4194324` + +Page Down key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_SHIFT** = `4194325` + +Shift key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_CTRL** = `4194326` + +Control key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_META** = `4194327` + +Meta key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_ALT** = `4194328` + +Alt key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_CAPSLOCK** = `4194329` + +Caps Lock key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_NUMLOCK** = `4194330` + +Num Lock key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_SCROLLLOCK** = `4194331` + +Scroll Lock key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F1** = `4194332` + +F1 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F2** = `4194333` + +F2 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F3** = `4194334` + +F3 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F4** = `4194335` + +F4 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F5** = `4194336` + +F5 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F6** = `4194337` + +F6 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F7** = `4194338` + +F7 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F8** = `4194339` + +F8 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F9** = `4194340` + +F9 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F10** = `4194341` + +F10 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F11** = `4194342` + +F11 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F12** = `4194343` + +F12 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F13** = `4194344` + +F13 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F14** = `4194345` + +F14 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F15** = `4194346` + +F15 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F16** = `4194347` + +F16 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F17** = `4194348` + +F17 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F18** = `4194349` + +F18 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F19** = `4194350` + +F19 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F20** = `4194351` + +F20 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F21** = `4194352` + +F21 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F22** = `4194353` + +F22 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F23** = `4194354` + +F23 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F24** = `4194355` + +F24 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F25** = `4194356` + +F25 key. Only supported on macOS and Linux due to a Windows limitation. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F26** = `4194357` + +F26 key. Only supported on macOS and Linux due to a Windows limitation. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F27** = `4194358` + +F27 key. Only supported on macOS and Linux due to a Windows limitation. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F28** = `4194359` + +F28 key. Only supported on macOS and Linux due to a Windows limitation. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F29** = `4194360` + +F29 key. Only supported on macOS and Linux due to a Windows limitation. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F30** = `4194361` + +F30 key. Only supported on macOS and Linux due to a Windows limitation. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F31** = `4194362` + +F31 key. Only supported on macOS and Linux due to a Windows limitation. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F32** = `4194363` + +F32 key. Only supported on macOS and Linux due to a Windows limitation. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F33** = `4194364` + +F33 key. Only supported on macOS and Linux due to a Windows limitation. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F34** = `4194365` + +F34 key. Only supported on macOS and Linux due to a Windows limitation. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F35** = `4194366` + +F35 key. Only supported on macOS and Linux due to a Windows limitation. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_KP_MULTIPLY** = `4194433` + +Multiply (\*) key on the numeric keypad. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_KP_DIVIDE** = `4194434` + +Divide (/) key on the numeric keypad. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_KP_SUBTRACT** = `4194435` + +Subtract (-) key on the numeric keypad. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_KP_PERIOD** = `4194436` + +Period (.) key on the numeric keypad. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_KP_ADD** = `4194437` + +Add (+) key on the numeric keypad. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_KP_0** = `4194438` + +Number 0 on the numeric keypad. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_KP_1** = `4194439` + +Number 1 on the numeric keypad. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_KP_2** = `4194440` + +Number 2 on the numeric keypad. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_KP_3** = `4194441` + +Number 3 on the numeric keypad. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_KP_4** = `4194442` + +Number 4 on the numeric keypad. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_KP_5** = `4194443` + +Number 5 on the numeric keypad. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_KP_6** = `4194444` + +Number 6 on the numeric keypad. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_KP_7** = `4194445` + +Number 7 on the numeric keypad. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_KP_8** = `4194446` + +Number 8 on the numeric keypad. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_KP_9** = `4194447` + +Number 9 on the numeric keypad. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_MENU** = `4194370` + +Context menu key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_HYPER** = `4194371` + +Hyper key. (On Linux/X11 only). + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_HELP** = `4194373` + +Help key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_BACK** = `4194376` + +Back key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_FORWARD** = `4194377` + +Forward key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_STOP** = `4194378` + +Media stop key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_REFRESH** = `4194379` + +Refresh key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_VOLUMEDOWN** = `4194380` + +Volume down key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_VOLUMEMUTE** = `4194381` + +Mute volume key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_VOLUMEUP** = `4194382` + +Volume up key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_MEDIAPLAY** = `4194388` + +Media play key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_MEDIASTOP** = `4194389` + +Media stop key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_MEDIAPREVIOUS** = `4194390` + +Previous song key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_MEDIANEXT** = `4194391` + +Next song key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_MEDIARECORD** = `4194392` + +Media record key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_HOMEPAGE** = `4194393` + +Home page key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_FAVORITES** = `4194394` + +Favorites key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_SEARCH** = `4194395` + +Search key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_STANDBY** = `4194396` + +Standby key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_OPENURL** = `4194397` + +Open URL / Launch Browser key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_LAUNCHMAIL** = `4194398` + +Launch Mail key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_LAUNCHMEDIA** = `4194399` + +Launch Media key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_LAUNCH0** = `4194400` + +Launch Shortcut 0 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_LAUNCH1** = `4194401` + +Launch Shortcut 1 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_LAUNCH2** = `4194402` + +Launch Shortcut 2 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_LAUNCH3** = `4194403` + +Launch Shortcut 3 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_LAUNCH4** = `4194404` + +Launch Shortcut 4 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_LAUNCH5** = `4194405` + +Launch Shortcut 5 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_LAUNCH6** = `4194406` + +Launch Shortcut 6 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_LAUNCH7** = `4194407` + +Launch Shortcut 7 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_LAUNCH8** = `4194408` + +Launch Shortcut 8 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_LAUNCH9** = `4194409` + +Launch Shortcut 9 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_LAUNCHA** = `4194410` + +Launch Shortcut A key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_LAUNCHB** = `4194411` + +Launch Shortcut B key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_LAUNCHC** = `4194412` + +Launch Shortcut C key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_LAUNCHD** = `4194413` + +Launch Shortcut D key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_LAUNCHE** = `4194414` + +Launch Shortcut E key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_LAUNCHF** = `4194415` + +Launch Shortcut F key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_GLOBE** = `4194416` + +"Globe" key on Mac / iPad keyboard. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_KEYBOARD** = `4194417` + +"On-screen keyboard" key on iPad keyboard. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_JIS_EISU** = `4194418` + +英数 key on Mac keyboard. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_JIS_KANA** = `4194419` + +かな key on Mac keyboard. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_UNKNOWN** = `8388607` + +Unknown key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_SPACE** = `32` + +Space key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_EXCLAM** = `33` + +Exclamation mark (``!``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_QUOTEDBL** = `34` + +Double quotation mark (``"``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_NUMBERSIGN** = `35` + +Number sign or *hash* (``#``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_DOLLAR** = `36` + +Dollar sign (``$``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_PERCENT** = `37` + +Percent sign (``%``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_AMPERSAND** = `38` + +Ampersand (``&``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_APOSTROPHE** = `39` + +Apostrophe (``'``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_PARENLEFT** = `40` + +Left parenthesis (``(``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_PARENRIGHT** = `41` + +Right parenthesis (``)``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_ASTERISK** = `42` + +Asterisk (``*``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_PLUS** = `43` + +Plus (``+``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_COMMA** = `44` + +Comma (``,``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_MINUS** = `45` + +Minus (``-``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_PERIOD** = `46` + +Period (``.``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_SLASH** = `47` + +Slash (``/``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_0** = `48` + +Number 0 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_1** = `49` + +Number 1 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_2** = `50` + +Number 2 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_3** = `51` + +Number 3 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_4** = `52` + +Number 4 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_5** = `53` + +Number 5 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_6** = `54` + +Number 6 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_7** = `55` + +Number 7 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_8** = `56` + +Number 8 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_9** = `57` + +Number 9 key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_COLON** = `58` + +Colon (``:``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_SEMICOLON** = `59` + +Semicolon (``;``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_LESS** = `60` + +Less-than sign (``<``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_EQUAL** = `61` + +Equal sign (``=``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_GREATER** = `62` + +Greater-than sign (``>``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_QUESTION** = `63` + +Question mark (``?``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_AT** = `64` + +At sign (``@``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_A** = `65` + +A key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_B** = `66` + +B key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_C** = `67` + +C key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_D** = `68` + +D key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_E** = `69` + +E key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_F** = `70` + +F key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_G** = `71` + +G key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_H** = `72` + +H key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_I** = `73` + +I key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_J** = `74` + +J key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_K** = `75` + +K key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_L** = `76` + +L key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_M** = `77` + +M key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_N** = `78` + +N key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_O** = `79` + +O key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_P** = `80` + +P key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_Q** = `81` + +Q key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_R** = `82` + +R key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_S** = `83` + +S key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_T** = `84` + +T key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_U** = `85` + +U key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_V** = `86` + +V key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_W** = `87` + +W key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_X** = `88` + +X key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_Y** = `89` + +Y key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_Z** = `90` + +Z key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_BRACKETLEFT** = `91` + +Left bracket (``[lb]``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_BACKSLASH** = `92` + +Backslash (``\``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_BRACKETRIGHT** = `93` + +Right bracket (``[rb]``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_ASCIICIRCUM** = `94` + +Caret (``^``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_UNDERSCORE** = `95` + +Underscore (``_``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_QUOTELEFT** = `96` + +Backtick (`````) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_BRACELEFT** = `123` + +Left brace (``{``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_BAR** = `124` + +Vertical bar or *pipe* (``|``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_BRACERIGHT** = `125` + +Right brace (``}``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_ASCIITILDE** = `126` + +Tilde (``~``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_YEN** = `165` + +Yen symbol (``¥``) key. + + + +[Key](class_@globalscope.md#enum_@GlobalScope_Key) **KEY_SECTION** = `167` + +Section sign (``§``) key.
+ + + + + +flags **KeyModifierMask**: [🔗](#enum_@GlobalScope_KeyModifierMask) + + + + + +[KeyModifierMask](class_@globalscope.md#enum_@GlobalScope_KeyModifierMask) **KEY_CODE_MASK** = `8388607` + +Key Code mask. + + + +[KeyModifierMask](class_@globalscope.md#enum_@GlobalScope_KeyModifierMask) **KEY_MODIFIER_MASK** = `2130706432` + +Modifier key mask. + + + +[KeyModifierMask](class_@globalscope.md#enum_@GlobalScope_KeyModifierMask) **KEY_MASK_CMD_OR_CTRL** = `16777216` + +Automatically remapped to [KEY_META](class_@globalscope.md#class_@GlobalScope_constant_KEY_META) on macOS and [KEY_CTRL](class_@globalscope.md#class_@GlobalScope_constant_KEY_CTRL) on other platforms, this mask is never set in the actual events, and should be used for key mapping only. + + + +[KeyModifierMask](class_@globalscope.md#enum_@GlobalScope_KeyModifierMask) **KEY_MASK_SHIFT** = `33554432` + +Shift key mask. + + + +[KeyModifierMask](class_@globalscope.md#enum_@GlobalScope_KeyModifierMask) **KEY_MASK_ALT** = `67108864` + +Alt or Option (on macOS) key mask. + + + +[KeyModifierMask](class_@globalscope.md#enum_@GlobalScope_KeyModifierMask) **KEY_MASK_META** = `134217728` + +Command (on macOS) or Meta/Windows key mask. + + + +[KeyModifierMask](class_@globalscope.md#enum_@GlobalScope_KeyModifierMask) **KEY_MASK_CTRL** = `268435456` + +Control key mask. + + + +[KeyModifierMask](class_@globalscope.md#enum_@GlobalScope_KeyModifierMask) **KEY_MASK_KPAD** = `536870912` + +Keypad key mask. + + + +[KeyModifierMask](class_@globalscope.md#enum_@GlobalScope_KeyModifierMask) **KEY_MASK_GROUP_SWITCH** = `1073741824` + +Group Switch key mask.
+ + + + + +enum **KeyLocation**: [🔗](#enum_@GlobalScope_KeyLocation) + + + + + +[KeyLocation](class_@globalscope.md#enum_@GlobalScope_KeyLocation) **KEY_LOCATION_UNSPECIFIED** = `0` + +Used for keys which only appear once, or when a comparison doesn't need to differentiate the ``LEFT`` and ``RIGHT`` versions. + +For example, when using [InputEvent.is_match()](class_inputevent.md#class_InputEvent_method_is_match), an event which has [KEY_LOCATION_UNSPECIFIED](class_@globalscope.md#class_@GlobalScope_constant_KEY_LOCATION_UNSPECIFIED) will match any [KeyLocation](class_@globalscope.md#enum_@GlobalScope_KeyLocation) on the passed event. + + + +[KeyLocation](class_@globalscope.md#enum_@GlobalScope_KeyLocation) **KEY_LOCATION_LEFT** = `1` + +A key which is to the left of its twin. + + + +[KeyLocation](class_@globalscope.md#enum_@GlobalScope_KeyLocation) **KEY_LOCATION_RIGHT** = `2` + +A key which is to the right of its twin.
+ + + + + +enum **MouseButton**: [🔗](#enum_@GlobalScope_MouseButton) + + + + + +[MouseButton](class_@globalscope.md#enum_@GlobalScope_MouseButton) **MOUSE_BUTTON_NONE** = `0` + +Enum value which doesn't correspond to any mouse button. This is used to initialize [MouseButton](class_@globalscope.md#enum_@GlobalScope_MouseButton) properties with a generic state. + + + +[MouseButton](class_@globalscope.md#enum_@GlobalScope_MouseButton) **MOUSE_BUTTON_LEFT** = `1` + +Primary mouse button, usually assigned to the left button. + + + +[MouseButton](class_@globalscope.md#enum_@GlobalScope_MouseButton) **MOUSE_BUTTON_RIGHT** = `2` + +Secondary mouse button, usually assigned to the right button. + + + +[MouseButton](class_@globalscope.md#enum_@GlobalScope_MouseButton) **MOUSE_BUTTON_MIDDLE** = `3` + +Middle mouse button. + + + +[MouseButton](class_@globalscope.md#enum_@GlobalScope_MouseButton) **MOUSE_BUTTON_WHEEL_UP** = `4` + +Mouse wheel scrolling up. + + + +[MouseButton](class_@globalscope.md#enum_@GlobalScope_MouseButton) **MOUSE_BUTTON_WHEEL_DOWN** = `5` + +Mouse wheel scrolling down. + + + +[MouseButton](class_@globalscope.md#enum_@GlobalScope_MouseButton) **MOUSE_BUTTON_WHEEL_LEFT** = `6` + +Mouse wheel left button (only present on some mice). + + + +[MouseButton](class_@globalscope.md#enum_@GlobalScope_MouseButton) **MOUSE_BUTTON_WHEEL_RIGHT** = `7` + +Mouse wheel right button (only present on some mice). + + + +[MouseButton](class_@globalscope.md#enum_@GlobalScope_MouseButton) **MOUSE_BUTTON_XBUTTON1** = `8` + +Extra mouse button 1. This is sometimes present, usually to the sides of the mouse. + + + +[MouseButton](class_@globalscope.md#enum_@GlobalScope_MouseButton) **MOUSE_BUTTON_XBUTTON2** = `9` + +Extra mouse button 2. This is sometimes present, usually to the sides of the mouse.
+ + + + + +flags **MouseButtonMask**: [🔗](#enum_@GlobalScope_MouseButtonMask) + + + + + +[MouseButtonMask](class_@globalscope.md#enum_@GlobalScope_MouseButtonMask) **MOUSE_BUTTON_MASK_LEFT** = `1` + +Primary mouse button mask, usually for the left button. + + + +[MouseButtonMask](class_@globalscope.md#enum_@GlobalScope_MouseButtonMask) **MOUSE_BUTTON_MASK_RIGHT** = `2` + +Secondary mouse button mask, usually for the right button. + + + +[MouseButtonMask](class_@globalscope.md#enum_@GlobalScope_MouseButtonMask) **MOUSE_BUTTON_MASK_MIDDLE** = `4` + +Middle mouse button mask. + + + +[MouseButtonMask](class_@globalscope.md#enum_@GlobalScope_MouseButtonMask) **MOUSE_BUTTON_MASK_MB_XBUTTON1** = `128` + +Extra mouse button 1 mask. + + + +[MouseButtonMask](class_@globalscope.md#enum_@GlobalScope_MouseButtonMask) **MOUSE_BUTTON_MASK_MB_XBUTTON2** = `256` + +Extra mouse button 2 mask.
+ + + + + +enum **JoyButton**: [🔗](#enum_@GlobalScope_JoyButton) + + + + + +[JoyButton](class_@globalscope.md#enum_@GlobalScope_JoyButton) **JOY_BUTTON_INVALID** = `-1` + +An invalid game controller button. + + + +[JoyButton](class_@globalscope.md#enum_@GlobalScope_JoyButton) **JOY_BUTTON_A** = `0` + +Game controller SDL button A. Corresponds to the bottom action button: Sony Cross, Xbox A, Nintendo B. + + + +[JoyButton](class_@globalscope.md#enum_@GlobalScope_JoyButton) **JOY_BUTTON_B** = `1` + +Game controller SDL button B. Corresponds to the right action button: Sony Circle, Xbox B, Nintendo A. + + + +[JoyButton](class_@globalscope.md#enum_@GlobalScope_JoyButton) **JOY_BUTTON_X** = `2` + +Game controller SDL button X. Corresponds to the left action button: Sony Square, Xbox X, Nintendo Y. + + + +[JoyButton](class_@globalscope.md#enum_@GlobalScope_JoyButton) **JOY_BUTTON_Y** = `3` + +Game controller SDL button Y. Corresponds to the top action button: Sony Triangle, Xbox Y, Nintendo X. + + + +[JoyButton](class_@globalscope.md#enum_@GlobalScope_JoyButton) **JOY_BUTTON_BACK** = `4` + +Game controller SDL back button. Corresponds to the Sony Select, Xbox Back, Nintendo - button. + + + +[JoyButton](class_@globalscope.md#enum_@GlobalScope_JoyButton) **JOY_BUTTON_GUIDE** = `5` + +Game controller SDL guide button. Corresponds to the Sony PS, Xbox Home button. + + + +[JoyButton](class_@globalscope.md#enum_@GlobalScope_JoyButton) **JOY_BUTTON_START** = `6` + +Game controller SDL start button. Corresponds to the Sony Options, Xbox Menu, Nintendo + button. + + + +[JoyButton](class_@globalscope.md#enum_@GlobalScope_JoyButton) **JOY_BUTTON_LEFT_STICK** = `7` + +Game controller SDL left stick button. Corresponds to the Sony L3, Xbox L/LS button. + + + +[JoyButton](class_@globalscope.md#enum_@GlobalScope_JoyButton) **JOY_BUTTON_RIGHT_STICK** = `8` + +Game controller SDL right stick button. Corresponds to the Sony R3, Xbox R/RS button. + + + +[JoyButton](class_@globalscope.md#enum_@GlobalScope_JoyButton) **JOY_BUTTON_LEFT_SHOULDER** = `9` + +Game controller SDL left shoulder button. Corresponds to the Sony L1, Xbox LB button. + + + +[JoyButton](class_@globalscope.md#enum_@GlobalScope_JoyButton) **JOY_BUTTON_RIGHT_SHOULDER** = `10` + +Game controller SDL right shoulder button. Corresponds to the Sony R1, Xbox RB button. + + + +[JoyButton](class_@globalscope.md#enum_@GlobalScope_JoyButton) **JOY_BUTTON_DPAD_UP** = `11` + +Game controller D-pad up button. + + + +[JoyButton](class_@globalscope.md#enum_@GlobalScope_JoyButton) **JOY_BUTTON_DPAD_DOWN** = `12` + +Game controller D-pad down button. + + + +[JoyButton](class_@globalscope.md#enum_@GlobalScope_JoyButton) **JOY_BUTTON_DPAD_LEFT** = `13` + +Game controller D-pad left button. + + + +[JoyButton](class_@globalscope.md#enum_@GlobalScope_JoyButton) **JOY_BUTTON_DPAD_RIGHT** = `14` + +Game controller D-pad right button. + + + +[JoyButton](class_@globalscope.md#enum_@GlobalScope_JoyButton) **JOY_BUTTON_MISC1** = `15` + +Game controller SDL miscellaneous button. Corresponds to Xbox share button, PS5 microphone button, Nintendo Switch capture button. + + + +[JoyButton](class_@globalscope.md#enum_@GlobalScope_JoyButton) **JOY_BUTTON_PADDLE1** = `16` + +Game controller SDL paddle 1 button. + + + +[JoyButton](class_@globalscope.md#enum_@GlobalScope_JoyButton) **JOY_BUTTON_PADDLE2** = `17` + +Game controller SDL paddle 2 button. + + + +[JoyButton](class_@globalscope.md#enum_@GlobalScope_JoyButton) **JOY_BUTTON_PADDLE3** = `18` + +Game controller SDL paddle 3 button. + + + +[JoyButton](class_@globalscope.md#enum_@GlobalScope_JoyButton) **JOY_BUTTON_PADDLE4** = `19` + +Game controller SDL paddle 4 button. + + + +[JoyButton](class_@globalscope.md#enum_@GlobalScope_JoyButton) **JOY_BUTTON_TOUCHPAD** = `20` + +Game controller SDL touchpad button. + + + +[JoyButton](class_@globalscope.md#enum_@GlobalScope_JoyButton) **JOY_BUTTON_SDL_MAX** = `21` + +The number of SDL game controller buttons. + + + +[JoyButton](class_@globalscope.md#enum_@GlobalScope_JoyButton) **JOY_BUTTON_MAX** = `128` + +The maximum number of game controller buttons supported by the engine. The actual limit may be lower on specific platforms: + +- **Android:** Up to 36 buttons. + +- **Linux:** Up to 80 buttons. + +- **Windows** and **macOS:** Up to 128 buttons.
+ + + + + +enum **JoyAxis**: [🔗](#enum_@GlobalScope_JoyAxis) + + + + + +[JoyAxis](class_@globalscope.md#enum_@GlobalScope_JoyAxis) **JOY_AXIS_INVALID** = `-1` + +An invalid game controller axis. + + + +[JoyAxis](class_@globalscope.md#enum_@GlobalScope_JoyAxis) **JOY_AXIS_LEFT_X** = `0` + +Game controller left joystick x-axis. + + + +[JoyAxis](class_@globalscope.md#enum_@GlobalScope_JoyAxis) **JOY_AXIS_LEFT_Y** = `1` + +Game controller left joystick y-axis. + + + +[JoyAxis](class_@globalscope.md#enum_@GlobalScope_JoyAxis) **JOY_AXIS_RIGHT_X** = `2` + +Game controller right joystick x-axis. + + + +[JoyAxis](class_@globalscope.md#enum_@GlobalScope_JoyAxis) **JOY_AXIS_RIGHT_Y** = `3` + +Game controller right joystick y-axis. + + + +[JoyAxis](class_@globalscope.md#enum_@GlobalScope_JoyAxis) **JOY_AXIS_TRIGGER_LEFT** = `4` + +Game controller left trigger axis. + + + +[JoyAxis](class_@globalscope.md#enum_@GlobalScope_JoyAxis) **JOY_AXIS_TRIGGER_RIGHT** = `5` + +Game controller right trigger axis. + + + +[JoyAxis](class_@globalscope.md#enum_@GlobalScope_JoyAxis) **JOY_AXIS_SDL_MAX** = `6` + +The number of SDL game controller axes. + + + +[JoyAxis](class_@globalscope.md#enum_@GlobalScope_JoyAxis) **JOY_AXIS_MAX** = `10` + +The maximum number of game controller axes: OpenVR supports up to 5 Joysticks making a total of 10 axes.
+ + + + + +enum **MIDIMessage**: [🔗](#enum_@GlobalScope_MIDIMessage) + + + + + +[MIDIMessage](class_@globalscope.md#enum_@GlobalScope_MIDIMessage) **MIDI_MESSAGE_NONE** = `0` + +Does not correspond to any MIDI message. This is the default value of [InputEventMIDI.message](class_inputeventmidi.md#class_InputEventMIDI_property_message). + + + +[MIDIMessage](class_@globalscope.md#enum_@GlobalScope_MIDIMessage) **MIDI_MESSAGE_NOTE_OFF** = `8` + +MIDI message sent when a note is released. + +\ **Note:** Not all MIDI devices send this message; some may send [MIDI_MESSAGE_NOTE_ON](class_@globalscope.md#class_@GlobalScope_constant_MIDI_MESSAGE_NOTE_ON) with [InputEventMIDI.velocity](class_inputeventmidi.md#class_InputEventMIDI_property_velocity) set to ``0``. + + + +[MIDIMessage](class_@globalscope.md#enum_@GlobalScope_MIDIMessage) **MIDI_MESSAGE_NOTE_ON** = `9` + +MIDI message sent when a note is pressed. + + + +[MIDIMessage](class_@globalscope.md#enum_@GlobalScope_MIDIMessage) **MIDI_MESSAGE_AFTERTOUCH** = `10` + +MIDI message sent to indicate a change in pressure while a note is being pressed down, also called aftertouch. + + + +[MIDIMessage](class_@globalscope.md#enum_@GlobalScope_MIDIMessage) **MIDI_MESSAGE_CONTROL_CHANGE** = `11` + +MIDI message sent when a controller value changes. In a MIDI device, a controller is any input that doesn't play notes. These may include sliders for volume, balance, and panning, as well as switches and pedals. See the [General MIDI specification](https://en.wikipedia.org/wiki/General_MIDI#Controller_events) for a small list. + + + +[MIDIMessage](class_@globalscope.md#enum_@GlobalScope_MIDIMessage) **MIDI_MESSAGE_PROGRAM_CHANGE** = `12` + +MIDI message sent when the MIDI device changes its current instrument (also called *program* or *preset*). + + + +[MIDIMessage](class_@globalscope.md#enum_@GlobalScope_MIDIMessage) **MIDI_MESSAGE_CHANNEL_PRESSURE** = `13` + +MIDI message sent to indicate a change in pressure for the whole channel. Some MIDI devices may send this instead of [MIDI_MESSAGE_AFTERTOUCH](class_@globalscope.md#class_@GlobalScope_constant_MIDI_MESSAGE_AFTERTOUCH). + + + +[MIDIMessage](class_@globalscope.md#enum_@GlobalScope_MIDIMessage) **MIDI_MESSAGE_PITCH_BEND** = `14` + +MIDI message sent when the value of the pitch bender changes, usually a wheel on the MIDI device. + + + +[MIDIMessage](class_@globalscope.md#enum_@GlobalScope_MIDIMessage) **MIDI_MESSAGE_SYSTEM_EXCLUSIVE** = `240` + +MIDI system exclusive (SysEx) message. This type of message is not standardized and it's highly dependent on the MIDI device sending it. + +\ **Note:** Getting this message's data from [InputEventMIDI](class_inputeventmidi.md) is not implemented. + + + +[MIDIMessage](class_@globalscope.md#enum_@GlobalScope_MIDIMessage) **MIDI_MESSAGE_QUARTER_FRAME** = `241` + +MIDI message sent every quarter frame to keep connected MIDI devices synchronized. Related to [MIDI_MESSAGE_TIMING_CLOCK](class_@globalscope.md#class_@GlobalScope_constant_MIDI_MESSAGE_TIMING_CLOCK). + +\ **Note:** Getting this message's data from [InputEventMIDI](class_inputeventmidi.md) is not implemented. + + + +[MIDIMessage](class_@globalscope.md#enum_@GlobalScope_MIDIMessage) **MIDI_MESSAGE_SONG_POSITION_POINTER** = `242` + +MIDI message sent to jump onto a new position in the current sequence or song. + +\ **Note:** Getting this message's data from [InputEventMIDI](class_inputeventmidi.md) is not implemented. + + + +[MIDIMessage](class_@globalscope.md#enum_@GlobalScope_MIDIMessage) **MIDI_MESSAGE_SONG_SELECT** = `243` + +MIDI message sent to select a sequence or song to play. + +\ **Note:** Getting this message's data from [InputEventMIDI](class_inputeventmidi.md) is not implemented. + + + +[MIDIMessage](class_@globalscope.md#enum_@GlobalScope_MIDIMessage) **MIDI_MESSAGE_TUNE_REQUEST** = `246` + +MIDI message sent to request a tuning calibration. Used on analog synthesizers. Most modern MIDI devices do not need this message. + + + +[MIDIMessage](class_@globalscope.md#enum_@GlobalScope_MIDIMessage) **MIDI_MESSAGE_TIMING_CLOCK** = `248` + +MIDI message sent 24 times after [MIDI_MESSAGE_QUARTER_FRAME](class_@globalscope.md#class_@GlobalScope_constant_MIDI_MESSAGE_QUARTER_FRAME), to keep connected MIDI devices synchronized. + + + +[MIDIMessage](class_@globalscope.md#enum_@GlobalScope_MIDIMessage) **MIDI_MESSAGE_START** = `250` + +MIDI message sent to start the current sequence or song from the beginning. + + + +[MIDIMessage](class_@globalscope.md#enum_@GlobalScope_MIDIMessage) **MIDI_MESSAGE_CONTINUE** = `251` + +MIDI message sent to resume from the point the current sequence or song was paused. + + + +[MIDIMessage](class_@globalscope.md#enum_@GlobalScope_MIDIMessage) **MIDI_MESSAGE_STOP** = `252` + +MIDI message sent to pause the current sequence or song. + + + +[MIDIMessage](class_@globalscope.md#enum_@GlobalScope_MIDIMessage) **MIDI_MESSAGE_ACTIVE_SENSING** = `254` + +MIDI message sent repeatedly while the MIDI device is idle, to tell the receiver that the connection is alive. Most MIDI devices do not send this message. + + + +[MIDIMessage](class_@globalscope.md#enum_@GlobalScope_MIDIMessage) **MIDI_MESSAGE_SYSTEM_RESET** = `255` + +MIDI message sent to reset a MIDI device to its default state, as if it was just turned on. It should not be sent when the MIDI device is being turned on.
+ + + + + +enum **Error**: [🔗](#enum_@GlobalScope_Error) + + + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **OK** = `0` + +Methods that return [Error](class_@globalscope.md#enum_@GlobalScope_Error) return [OK](class_@globalscope.md#class_@GlobalScope_constant_OK) when no error occurred. + +Since [OK](class_@globalscope.md#class_@GlobalScope_constant_OK) has value ``0``, and all other error constants are positive integers, it can also be used in boolean checks. + +``` + var error = method_that_returns_error() + if error != OK: + printerr("Failure!") + + # Or, alternatively: + if error: + printerr("Still failing!") +``` + +\ **Note:** Many functions do not return an error code, but will print error messages to standard output. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **FAILED** = `1` + +Generic error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_UNAVAILABLE** = `2` + +Unavailable error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_UNCONFIGURED** = `3` + +Unconfigured error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_UNAUTHORIZED** = `4` + +Unauthorized error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_PARAMETER_RANGE_ERROR** = `5` + +Parameter range error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_OUT_OF_MEMORY** = `6` + +Out of memory (OOM) error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_FILE_NOT_FOUND** = `7` + +File: Not found error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_FILE_BAD_DRIVE** = `8` + +File: Bad drive error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_FILE_BAD_PATH** = `9` + +File: Bad path error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_FILE_NO_PERMISSION** = `10` + +File: No permission error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_FILE_ALREADY_IN_USE** = `11` + +File: Already in use error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_FILE_CANT_OPEN** = `12` + +File: Can't open error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_FILE_CANT_WRITE** = `13` + +File: Can't write error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_FILE_CANT_READ** = `14` + +File: Can't read error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_FILE_UNRECOGNIZED** = `15` + +File: Unrecognized error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_FILE_CORRUPT** = `16` + +File: Corrupt error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_FILE_MISSING_DEPENDENCIES** = `17` + +File: Missing dependencies error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_FILE_EOF** = `18` + +File: End of file (EOF) error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_CANT_OPEN** = `19` + +Can't open error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_CANT_CREATE** = `20` + +Can't create error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_QUERY_FAILED** = `21` + +Query failed error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_ALREADY_IN_USE** = `22` + +Already in use error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_LOCKED** = `23` + +Locked error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_TIMEOUT** = `24` + +Timeout error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_CANT_CONNECT** = `25` + +Can't connect error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_CANT_RESOLVE** = `26` + +Can't resolve error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_CONNECTION_ERROR** = `27` + +Connection error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_CANT_ACQUIRE_RESOURCE** = `28` + +Can't acquire resource error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_CANT_FORK** = `29` + +Can't fork process error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_INVALID_DATA** = `30` + +Invalid data error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_INVALID_PARAMETER** = `31` + +Invalid parameter error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_ALREADY_EXISTS** = `32` + +Already exists error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_DOES_NOT_EXIST** = `33` + +Does not exist error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_DATABASE_CANT_READ** = `34` + +Database: Read error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_DATABASE_CANT_WRITE** = `35` + +Database: Write error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_COMPILATION_FAILED** = `36` + +Compilation failed error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_METHOD_NOT_FOUND** = `37` + +Method not found error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_LINK_FAILED** = `38` + +Linking failed error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_SCRIPT_FAILED** = `39` + +Script failed error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_CYCLIC_LINK** = `40` + +Cycling link (import cycle) error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_INVALID_DECLARATION** = `41` + +Invalid declaration error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_DUPLICATE_SYMBOL** = `42` + +Duplicate symbol error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_PARSE_ERROR** = `43` + +Parse error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_BUSY** = `44` + +Busy error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_SKIP** = `45` + +Skip error. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_HELP** = `46` + +Help error. Used internally when passing ``--version`` or ``--help`` as executable options. + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_BUG** = `47` + +Bug error, caused by an implementation issue in the method. + +\ **Note:** If a built-in method returns this code, please open an issue on [the GitHub Issue Tracker](https://github.com/redot-engine/redot-engine/issues). + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **ERR_PRINTER_ON_FIRE** = `48` + +Printer on fire error (This is an easter egg, no built-in methods return this error code).
+ + + + + +enum **PropertyHint**: [🔗](#enum_@GlobalScope_PropertyHint) + + + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_NONE** = `0` + +The property has no hint for the editor. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_RANGE** = `1` + +Hints that an [int](class_int.md) or [float](class_float.md) property should be within a range specified via the hint string ``"min,max"`` or ``"min,max,step"``. The hint string can optionally include ``"or_greater"`` and/or ``"or_less"`` to allow manual input going respectively above the max or below the min values. + +\ **Example:** ``"-360,360,1,or_greater,or_less"``. + +Additionally, other keywords can be included: ``"exp"`` for exponential range editing, ``"radians_as_degrees"`` for editing radian angles in degrees (the range values are also in degrees), ``"degrees"`` to hint at an angle and ``"hide_slider"`` to hide the slider. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_ENUM** = `2` + +Hints that an [int](class_int.md) or [String](class_string.md) property is an enumerated value to pick in a list specified via a hint string. + +The hint string is a comma separated list of names such as ``"Hello,Something,Else"``. Whitespaces are **not** removed from either end of a name. For integer properties, the first name in the list has value 0, the next 1, and so on. Explicit values can also be specified by appending ``:integer`` to the name, e.g. ``"Zero,One,Three:3,Four,Six:6"``. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_ENUM_SUGGESTION** = `3` + +Hints that a [String](class_string.md) property can be an enumerated value to pick in a list specified via a hint string such as ``"Hello,Something,Else"``. + +Unlike [PROPERTY_HINT_ENUM](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_ENUM), a property with this hint still accepts arbitrary values and can be empty. The list of values serves to suggest possible values. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_EXP_EASING** = `4` + +Hints that a [float](class_float.md) property should be edited via an exponential easing function. The hint string can include ``"attenuation"`` to flip the curve horizontally and/or ``"positive_only"`` to exclude in/out easing and limit values to be greater than or equal to zero. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_LINK** = `5` + +Hints that a vector property should allow its components to be linked. For example, this allows [Vector2.x](class_vector2.md#class_Vector2_property_x) and [Vector2.y](class_vector2.md#class_Vector2_property_y) to be edited together. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_FLAGS** = `6` + +Hints that an [int](class_int.md) property is a bitmask with named bit flags. + +The hint string is a comma separated list of names such as ``"Bit0,Bit1,Bit2,Bit3"``. Whitespaces are **not** removed from either end of a name. The first name in the list has value 1, the next 2, then 4, 8, 16 and so on. Explicit values can also be specified by appending ``:integer`` to the name, e.g. ``"A:4,B:8,C:16"``. You can also combine several flags (``"A:4,B:8,AB:12,C:16"``). + +\ **Note:** A flag value must be at least ``1`` and at most ``2 ** 32 - 1``. + +\ **Note:** Unlike [PROPERTY_HINT_ENUM](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_ENUM), the previous explicit value is not taken into account. For the hint ``"A:16,B,C"``, A is 16, B is 2, C is 4. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_LAYERS_2D_RENDER** = `7` + +Hints that an [int](class_int.md) property is a bitmask using the optionally named 2D render layers. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_LAYERS_2D_PHYSICS** = `8` + +Hints that an [int](class_int.md) property is a bitmask using the optionally named 2D physics layers. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_LAYERS_2D_NAVIGATION** = `9` + +Hints that an [int](class_int.md) property is a bitmask using the optionally named 2D navigation layers. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_LAYERS_3D_RENDER** = `10` + +Hints that an [int](class_int.md) property is a bitmask using the optionally named 3D render layers. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_LAYERS_3D_PHYSICS** = `11` + +Hints that an [int](class_int.md) property is a bitmask using the optionally named 3D physics layers. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_LAYERS_3D_NAVIGATION** = `12` + +Hints that an [int](class_int.md) property is a bitmask using the optionally named 3D navigation layers. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_LAYERS_AVOIDANCE** = `37` + +Hints that an integer property is a bitmask using the optionally named avoidance layers. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_FILE** = `13` + +Hints that a [String](class_string.md) property is a path to a file. Editing it will show a file dialog for picking the path. The hint string can be a set of filters with wildcards like ``"*.png,*.jpg"``. By default the file will be stored as UID whenever available. You can use [ResourceUID](class_resourceuid.md) methods to convert it back to path. For storing a raw path, use [PROPERTY_HINT_FILE_PATH](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_FILE_PATH). + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_DIR** = `14` + +Hints that a [String](class_string.md) property is a path to a directory. Editing it will show a file dialog for picking the path. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_GLOBAL_FILE** = `15` + +Hints that a [String](class_string.md) property is an absolute path to a file outside the project folder. Editing it will show a file dialog for picking the path. The hint string can be a set of filters with wildcards, like ``"*.png,*.jpg"``. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_GLOBAL_DIR** = `16` + +Hints that a [String](class_string.md) property is an absolute path to a directory outside the project folder. Editing it will show a file dialog for picking the path. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_RESOURCE_TYPE** = `17` + +Hints that a property is an instance of a [Resource](class_resource.md)-derived type, optionally specified via the hint string (e.g. ``"Texture2D"``). Editing it will show a popup menu of valid resource types to instantiate. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_MULTILINE_TEXT** = `18` + +Hints that a [String](class_string.md) property is text with line breaks. Editing it will show a text input field where line breaks can be typed. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_EXPRESSION** = `19` + +Hints that a [String](class_string.md) property is an [Expression](class_expression.md). + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_PLACEHOLDER_TEXT** = `20` + +Hints that a [String](class_string.md) property should show a placeholder text on its input field, if empty. The hint string is the placeholder text to use. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_COLOR_NO_ALPHA** = `21` + +Hints that a [Color](class_color.md) property should be edited without affecting its transparency ([Color.a](class_color.md#class_Color_property_a) is not editable). + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_OBJECT_ID** = `22` + +Hints that the property's value is an object encoded as object ID, with its type specified in the hint string. Used by the debugger. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_TYPE_STRING** = `23` + +If a property is [String](class_string.md), hints that the property represents a particular type (class). This allows to select a type from the create dialog. The property will store the selected type as a string. + +If a property is [Array](class_array.md), hints the editor how to show elements. The ``hint_string`` must encode nested types using ``":"`` and ``"/"``. + +If a property is [Dictionary](class_dictionary.md), hints the editor how to show elements. The ``hint_string`` is the same as [Array](class_array.md), with a ``";"`` separating the key and value. + + + + +```gdscript + # Array of elem_type. + hint_string = "%d:" % [elem_type] + hint_string = "%d/%d:%s" % [elem_type, elem_hint, elem_hint_string] + # Two-dimensional array of elem_type (array of arrays of elem_type). + hint_string = "%d:%d:" % [TYPE_ARRAY, elem_type] + hint_string = "%d:%d/%d:%s" % [TYPE_ARRAY, elem_type, elem_hint, elem_hint_string] + # Three-dimensional array of elem_type (array of arrays of arrays of elem_type). + hint_string = "%d:%d:%d:" % [TYPE_ARRAY, TYPE_ARRAY, elem_type] + hint_string = "%d:%d:%d/%d:%s" % [TYPE_ARRAY, TYPE_ARRAY, elem_type, elem_hint, elem_hint_string] +``` + +```csharp + // Array of elemType. + hintString = $"{elemType:D}:"; + hintString = $"{elemType:}/{elemHint:D}:{elemHintString}"; + // Two-dimensional array of elemType (array of arrays of elemType). + hintString = $"{Variant.Type.Array:D}:{elemType:D}:"; + hintString = $"{Variant.Type.Array:D}:{elemType:D}/{elemHint:D}:{elemHintString}"; + // Three-dimensional array of elemType (array of arrays of arrays of elemType). + hintString = $"{Variant.Type.Array:D}:{Variant.Type.Array:D}:{elemType:D}:"; + hintString = $"{Variant.Type.Array:D}:{Variant.Type.Array:D}:{elemType:D}/{elemHint:D}:{elemHintString}"; +``` + + + +\ **Examples:**\ + + + + +```gdscript + hint_string = "%d:" % [TYPE_INT] # Array of integers. + hint_string = "%d/%d:1,10,1" % [TYPE_INT, PROPERTY_HINT_RANGE] # Array of integers (in range from 1 to 10). + hint_string = "%d/%d:Zero,One,Two" % [TYPE_INT, PROPERTY_HINT_ENUM] # Array of integers (an enum). + hint_string = "%d/%d:Zero,One,Three:3,Six:6" % [TYPE_INT, PROPERTY_HINT_ENUM] # Array of integers (an enum). + hint_string = "%d/%d:*.png" % [TYPE_STRING, PROPERTY_HINT_FILE] # Array of strings (file paths). + hint_string = "%d/%d:Texture2D" % [TYPE_OBJECT, PROPERTY_HINT_RESOURCE_TYPE] # Array of textures. + + hint_string = "%d:%d:" % [TYPE_ARRAY, TYPE_FLOAT] # Two-dimensional array of floats. + hint_string = "%d:%d/%d:" % [TYPE_ARRAY, TYPE_STRING, PROPERTY_HINT_MULTILINE_TEXT] # Two-dimensional array of multiline strings. + hint_string = "%d:%d/%d:-1,1,0.1" % [TYPE_ARRAY, TYPE_FLOAT, PROPERTY_HINT_RANGE] # Two-dimensional array of floats (in range from -1 to 1). + hint_string = "%d:%d/%d:Texture2D" % [TYPE_ARRAY, TYPE_OBJECT, PROPERTY_HINT_RESOURCE_TYPE] # Two-dimensional array of textures. +``` + +```csharp + hintString = $"{Variant.Type.Int:D}/{PropertyHint.Range:D}:1,10,1"; // Array of integers (in range from 1 to 10). + hintString = $"{Variant.Type.Int:D}/{PropertyHint.Enum:D}:Zero,One,Two"; // Array of integers (an enum). + hintString = $"{Variant.Type.Int:D}/{PropertyHint.Enum:D}:Zero,One,Three:3,Six:6"; // Array of integers (an enum). + hintString = $"{Variant.Type.String:D}/{PropertyHint.File:D}:*.png"; // Array of strings (file paths). + hintString = $"{Variant.Type.Object:D}/{PropertyHint.ResourceType:D}:Texture2D"; // Array of textures. + + hintString = $"{Variant.Type.Array:D}:{Variant.Type.Float:D}:"; // Two-dimensional array of floats. + hintString = $"{Variant.Type.Array:D}:{Variant.Type.String:D}/{PropertyHint.MultilineText:D}:"; // Two-dimensional array of multiline strings. + hintString = $"{Variant.Type.Array:D}:{Variant.Type.Float:D}/{PropertyHint.Range:D}:-1,1,0.1"; // Two-dimensional array of floats (in range from -1 to 1). + hintString = $"{Variant.Type.Array:D}:{Variant.Type.Object:D}/{PropertyHint.ResourceType:D}:Texture2D"; // Two-dimensional array of textures. +``` + + + +\ **Note:** The trailing colon is required for properly detecting built-in types. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_NODE_PATH_TO_EDITED_NODE** = `24` + +**Deprecated:** This hint is not used by the engine. + + + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_OBJECT_TOO_BIG** = `25` + +Hints that an object is too big to be sent via the debugger. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_NODE_PATH_VALID_TYPES** = `26` + +Hints that the hint string specifies valid node types for property of type [NodePath](class_nodepath.md). + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_SAVE_FILE** = `27` + +Hints that a [String](class_string.md) property is a path to a file. Editing it will show a file dialog for picking the path for the file to be saved at. The dialog has access to the project's directory. The hint string can be a set of filters with wildcards like ``"*.png,*.jpg"``. See also [FileDialog.filters](class_filedialog.md#class_FileDialog_property_filters). + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_GLOBAL_SAVE_FILE** = `28` + +Hints that a [String](class_string.md) property is a path to a file. Editing it will show a file dialog for picking the path for the file to be saved at. The dialog has access to the entire filesystem. The hint string can be a set of filters with wildcards like ``"*.png,*.jpg"``. See also [FileDialog.filters](class_filedialog.md#class_FileDialog_property_filters). + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_INT_IS_OBJECTID** = `29` + +**Deprecated:** This hint is not used by the engine. + + + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_INT_IS_POINTER** = `30` + +Hints that an [int](class_int.md) property is a pointer. Used by GDExtension. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_ARRAY_TYPE** = `31` + +Hints that a property is an [Array](class_array.md) with the stored type specified in the hint string. The hint string contains the type of the array (e.g. ``"String"``). + +Use the hint string format from [PROPERTY_HINT_TYPE_STRING](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_TYPE_STRING) for more control over the stored type. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_DICTIONARY_TYPE** = `38` + +Hints that a property is a [Dictionary](class_dictionary.md) with the stored types specified in the hint string. The hint string contains the key and value types separated by a semicolon (e.g. ``"int;String"``). + +Use the hint string format from [PROPERTY_HINT_TYPE_STRING](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_TYPE_STRING) for more control over the stored types. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_LOCALE_ID** = `32` + +Hints that a string property is a locale code. Editing it will show a locale dialog for picking language and country. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_LOCALIZABLE_STRING** = `33` + +Hints that a dictionary property is string translation map. Dictionary keys are locale codes and, values are translated strings. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_NODE_TYPE** = `34` + +Hints that a property is an instance of a [Node](class_node.md)-derived type, optionally specified via the hint string (e.g. ``"Node2D"``). Editing it will show a dialog for picking a node from the scene. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_HIDE_QUATERNION_EDIT** = `35` + +Hints that a quaternion property should disable the temporary euler editor. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_PASSWORD** = `36` + +Hints that a string property is a password, and every character is replaced with the secret character. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_TOOL_BUTTON** = `39` + +Hints that a [Callable](class_callable.md) property should be displayed as a clickable button. When the button is pressed, the callable is called. The hint string specifies the button text and optionally an icon from the ``"EditorIcons"`` theme type. + +```text + "Click me!" - A button with the text "Click me!" and the default "Callable" icon. + "Click me!,ColorRect" - A button with the text "Click me!" and the "ColorRect" icon. +``` + +\ **Note:** A [Callable](class_callable.md) cannot be properly serialized and stored in a file, so it is recommended to use [PROPERTY_USAGE_EDITOR](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_USAGE_EDITOR) instead of [PROPERTY_USAGE_DEFAULT](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_USAGE_DEFAULT). + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_ONESHOT** = `40` + +Hints that a property will be changed on its own after setting, such as [AudioStreamPlayer.playing](class_audiostreamplayer.md#class_AudioStreamPlayer_property_playing) or [GPUParticles3D.emitting](class_gpuparticles3d.md#class_GPUParticles3D_property_emitting). + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_GROUP_ENABLE** = `42` + +Hints that a boolean property will enable the feature associated with the group that it occurs in. The property will be displayed as a checkbox on the group header. Only works within a group or subgroup. + +By default, disabling the property hides all properties in the group. Use the optional hint string ``"checkbox_only"`` to disable this behavior. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_INPUT_NAME** = `43` + +Hints that a [String](class_string.md) or [StringName](class_stringname.md) property is the name of an input action. This allows the selection of any action name from the Input Map in the Project Settings. The hint string may contain two options separated by commas: + +- If it contains ``"show_builtin"``, built-in input actions are included in the selection. + +- If it contains ``"loose_mode"``, loose mode is enabled. This allows inserting any action name even if it's not present in the input map. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_FILE_PATH** = `44` + +Like [PROPERTY_HINT_FILE](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_FILE), but the property is stored as a raw path, not UID. That means the reference will be broken if you move the file. Consider using [PROPERTY_HINT_FILE](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_HINT_FILE) when possible. + + + +[PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) **PROPERTY_HINT_MAX** = `45` + +Represents the size of the [PropertyHint](class_@globalscope.md#enum_@GlobalScope_PropertyHint) enum.
+ + + + + +flags **PropertyUsageFlags**: [🔗](#enum_@GlobalScope_PropertyUsageFlags) + + + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_NONE** = `0` + +The property is not stored, and does not display in the editor. This is the default for non-exported properties. + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_STORAGE** = `2` + +The property is serialized and saved in the scene file (default for exported properties). + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_EDITOR** = `4` + +The property is shown in the [EditorInspector](class_editorinspector.md) (default for exported properties). + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_INTERNAL** = `8` + +The property is excluded from the class reference. + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_CHECKABLE** = `16` + +The property can be checked in the [EditorInspector](class_editorinspector.md). + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_CHECKED** = `32` + +The property is checked in the [EditorInspector](class_editorinspector.md). + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_GROUP** = `64` + +Used to group properties together in the editor. See [EditorInspector](class_editorinspector.md). + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_CATEGORY** = `128` + +Used to categorize properties together in the editor. + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_SUBGROUP** = `256` + +Used to group properties together in the editor in a subgroup (under a group). See [EditorInspector](class_editorinspector.md). + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_CLASS_IS_BITFIELD** = `512` + +The property is a bitfield, i.e. it contains multiple flags represented as bits. + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_NO_INSTANCE_STATE** = `1024` + +The property does not save its state in [PackedScene](class_packedscene.md). + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_RESTART_IF_CHANGED** = `2048` + +Editing the property prompts the user for restarting the editor. + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_SCRIPT_VARIABLE** = `4096` + +The property is a script variable. [PROPERTY_USAGE_SCRIPT_VARIABLE](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_USAGE_SCRIPT_VARIABLE) can be used to distinguish between exported script variables from built-in variables (which don't have this usage flag). By default, [PROPERTY_USAGE_SCRIPT_VARIABLE](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_USAGE_SCRIPT_VARIABLE) is **not** applied to variables that are created by overriding [Object._get_property_list()](class_object.md#class_Object_private_method__get_property_list) in a script. + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_STORE_IF_NULL** = `8192` + +The property value of type [Object](class_object.md) will be stored even if its value is ``null``. + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_UPDATE_ALL_IF_MODIFIED** = `16384` + +If this property is modified, all inspector fields will be refreshed. + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_SCRIPT_DEFAULT_VALUE** = `32768` + +**Deprecated:** This flag is not used by the engine. + + + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_CLASS_IS_ENUM** = `65536` + +The property is a variable of enum type, i.e. it only takes named integer constants from its associated enumeration. + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_NIL_IS_VARIANT** = `131072` + +If property has ``nil`` as default value, its type will be [Variant](class_variant.md). + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_ARRAY** = `262144` + +The property is an array. + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_ALWAYS_DUPLICATE** = `524288` + +When duplicating a resource with [Resource.duplicate()](class_resource.md#class_Resource_method_duplicate), and this flag is set on a property of that resource, the property should always be duplicated, regardless of the ``subresources`` bool parameter. + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_NEVER_DUPLICATE** = `1048576` + +When duplicating a resource with [Resource.duplicate()](class_resource.md#class_Resource_method_duplicate), and this flag is set on a property of that resource, the property should never be duplicated, regardless of the ``subresources`` bool parameter. + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_HIGH_END_GFX** = `2097152` + +The property is only shown in the editor if modern renderers are supported (the Compatibility rendering method is excluded). + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_NODE_PATH_FROM_SCENE_ROOT** = `4194304` + +The [NodePath](class_nodepath.md) property will always be relative to the scene's root. Mostly useful for local resources. + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_RESOURCE_NOT_PERSISTENT** = `8388608` + +Use when a resource is created on the fly, i.e. the getter will always return a different instance. [ResourceSaver](class_resourcesaver.md) needs this information to properly save such resources. + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_KEYING_INCREMENTS** = `16777216` + +Inserting an animation key frame of this property will automatically increment the value, allowing to easily keyframe multiple values in a row. + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_DEFERRED_SET_RESOURCE** = `33554432` + +**Deprecated:** This flag is not used by the engine. + + + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_EDITOR_INSTANTIATE_OBJECT** = `67108864` + +When this property is a [Resource](class_resource.md) and base object is a [Node](class_node.md), a resource instance will be automatically created whenever the node is created in the editor. + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_EDITOR_BASIC_SETTING** = `134217728` + +The property is considered a basic setting and will appear even when advanced mode is disabled. Used for project settings. + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_READ_ONLY** = `268435456` + +The property is read-only in the [EditorInspector](class_editorinspector.md). + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_SECRET** = `536870912` + +An export preset property with this flag contains confidential information and is stored separately from the rest of the export preset configuration. + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_DEFAULT** = `6` + +Default usage (storage and editor). + + + +[PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) **PROPERTY_USAGE_NO_EDITOR** = `2` + +Default usage but without showing the property in the editor (storage).
+ + + + + +flags **MethodFlags**: [🔗](#enum_@GlobalScope_MethodFlags) + + + + + +[MethodFlags](class_@globalscope.md#enum_@GlobalScope_MethodFlags) **METHOD_FLAG_NORMAL** = `1` + +Flag for a normal method. + + + +[MethodFlags](class_@globalscope.md#enum_@GlobalScope_MethodFlags) **METHOD_FLAG_EDITOR** = `2` + +Flag for an editor method. + + + +[MethodFlags](class_@globalscope.md#enum_@GlobalScope_MethodFlags) **METHOD_FLAG_CONST** = `4` + +Flag for a constant method. + + + +[MethodFlags](class_@globalscope.md#enum_@GlobalScope_MethodFlags) **METHOD_FLAG_VIRTUAL** = `8` + +Flag for a virtual method. + + + +[MethodFlags](class_@globalscope.md#enum_@GlobalScope_MethodFlags) **METHOD_FLAG_VARARG** = `16` + +Flag for a method with a variable number of arguments. + + + +[MethodFlags](class_@globalscope.md#enum_@GlobalScope_MethodFlags) **METHOD_FLAG_STATIC** = `32` + +Flag for a static method. + + + +[MethodFlags](class_@globalscope.md#enum_@GlobalScope_MethodFlags) **METHOD_FLAG_OBJECT_CORE** = `64` + +Used internally. Allows to not dump core virtual methods (such as [Object._notification()](class_object.md#class_Object_private_method__notification)) to the JSON API. + + + +[MethodFlags](class_@globalscope.md#enum_@GlobalScope_MethodFlags) **METHOD_FLAG_VIRTUAL_REQUIRED** = `128` + +Flag for a virtual method that is required. In GDScript, this flag is set for abstract functions. + + + +[MethodFlags](class_@globalscope.md#enum_@GlobalScope_MethodFlags) **METHOD_FLAGS_DEFAULT** = `1` + +Default method flags (normal).
+ + + + + +enum **Variant.Type**: [🔗](#enum_@GlobalScope_Variant.Type) + + + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_NIL** = `0` + +Variable is ``null``. + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_BOOL** = `1` + +Variable is of type [bool](class_bool.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_INT** = `2` + +Variable is of type [int](class_int.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_FLOAT** = `3` + +Variable is of type [float](class_float.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_STRING** = `4` + +Variable is of type [String](class_string.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_VECTOR2** = `5` + +Variable is of type [Vector2](class_vector2.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_VECTOR2I** = `6` + +Variable is of type [Vector2i](class_vector2i.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_RECT2** = `7` + +Variable is of type [Rect2](class_rect2.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_RECT2I** = `8` + +Variable is of type [Rect2i](class_rect2i.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_VECTOR3** = `9` + +Variable is of type [Vector3](class_vector3.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_VECTOR3I** = `10` + +Variable is of type [Vector3i](class_vector3i.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_TRANSFORM2D** = `11` + +Variable is of type [Transform2D](class_transform2d.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_VECTOR4** = `12` + +Variable is of type [Vector4](class_vector4.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_VECTOR4I** = `13` + +Variable is of type [Vector4i](class_vector4i.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_PLANE** = `14` + +Variable is of type [Plane](class_plane.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_QUATERNION** = `15` + +Variable is of type [Quaternion](class_quaternion.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_AABB** = `16` + +Variable is of type [AABB](class_aabb.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_BASIS** = `17` + +Variable is of type [Basis](class_basis.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_TRANSFORM3D** = `18` + +Variable is of type [Transform3D](class_transform3d.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_PROJECTION** = `19` + +Variable is of type [Projection](class_projection.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_COLOR** = `20` + +Variable is of type [Color](class_color.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_STRING_NAME** = `21` + +Variable is of type [StringName](class_stringname.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_NODE_PATH** = `22` + +Variable is of type [NodePath](class_nodepath.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_RID** = `23` + +Variable is of type [RID](class_rid.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_OBJECT** = `24` + +Variable is of type [Object](class_object.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_CALLABLE** = `25` + +Variable is of type [Callable](class_callable.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_SIGNAL** = `26` + +Variable is of type [Signal](class_signal.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_DICTIONARY** = `27` + +Variable is of type [Dictionary](class_dictionary.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_ARRAY** = `28` + +Variable is of type [Array](class_array.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_PACKED_BYTE_ARRAY** = `29` + +Variable is of type [PackedByteArray](class_packedbytearray.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_PACKED_INT32_ARRAY** = `30` + +Variable is of type [PackedInt32Array](class_packedint32array.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_PACKED_INT64_ARRAY** = `31` + +Variable is of type [PackedInt64Array](class_packedint64array.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_PACKED_FLOAT32_ARRAY** = `32` + +Variable is of type [PackedFloat32Array](class_packedfloat32array.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_PACKED_FLOAT64_ARRAY** = `33` + +Variable is of type [PackedFloat64Array](class_packedfloat64array.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_PACKED_STRING_ARRAY** = `34` + +Variable is of type [PackedStringArray](class_packedstringarray.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_PACKED_VECTOR2_ARRAY** = `35` + +Variable is of type [PackedVector2Array](class_packedvector2array.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_PACKED_VECTOR3_ARRAY** = `36` + +Variable is of type [PackedVector3Array](class_packedvector3array.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_PACKED_COLOR_ARRAY** = `37` + +Variable is of type [PackedColorArray](class_packedcolorarray.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_PACKED_VECTOR4_ARRAY** = `38` + +Variable is of type [PackedVector4Array](class_packedvector4array.md). + + + +[Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) **TYPE_MAX** = `39` + +Represents the size of the [Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) enum.
+ + + + + +enum **Variant.Operator**: [🔗](#enum_@GlobalScope_Variant.Operator) + + + + + +[Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) **OP_EQUAL** = `0` + +Equality operator (``==``). + + + +[Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) **OP_NOT_EQUAL** = `1` + +Inequality operator (``!=``). + + + +[Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) **OP_LESS** = `2` + +Less than operator (``<``). + + + +[Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) **OP_LESS_EQUAL** = `3` + +Less than or equal operator (``<=``). + + + +[Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) **OP_GREATER** = `4` + +Greater than operator (``>``). + + + +[Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) **OP_GREATER_EQUAL** = `5` + +Greater than or equal operator (``>=``). + + + +[Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) **OP_ADD** = `6` + +Addition operator (``+``). + + + +[Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) **OP_SUBTRACT** = `7` + +Subtraction operator (``-``). + + + +[Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) **OP_MULTIPLY** = `8` + +Multiplication operator (``*``). + + + +[Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) **OP_DIVIDE** = `9` + +Division operator (``/``). + + + +[Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) **OP_NEGATE** = `10` + +Unary negation operator (``-``). + + + +[Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) **OP_POSITIVE** = `11` + +Unary plus operator (``+``). + + + +[Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) **OP_MODULE** = `12` + +Remainder/modulo operator (``%``). + + + +[Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) **OP_POWER** = `13` + +Power operator (``**``). + + + +[Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) **OP_SHIFT_LEFT** = `14` + +Left shift operator (``<<``). + + + +[Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) **OP_SHIFT_RIGHT** = `15` + +Right shift operator (``>>``). + + + +[Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) **OP_BIT_AND** = `16` + +Bitwise AND operator (``&``). + + + +[Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) **OP_BIT_OR** = `17` + +Bitwise OR operator (``|``). + + + +[Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) **OP_BIT_XOR** = `18` + +Bitwise XOR operator (``^``). + + + +[Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) **OP_BIT_NEGATE** = `19` + +Bitwise NOT operator (``~``). + + + +[Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) **OP_AND** = `20` + +Logical AND operator (``and`` or ``&&``). + + + +[Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) **OP_OR** = `21` + +Logical OR operator (``or`` or ``||``). + + + +[Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) **OP_XOR** = `22` + +Logical XOR operator (not implemented in GDScript). + + + +[Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) **OP_NOT** = `23` + +Logical NOT operator (``not`` or ``!``). + + + +[Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) **OP_IN** = `24` + +Logical IN operator (``in``). + + + +[Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) **OP_MAX** = `25` + +Represents the size of the [Variant.Operator](class_@globalscope.md#enum_@GlobalScope_Variant.Operator) enum.
+ + + +## Property Descriptions + + + + + +[AudioServer](class_audioserver.md) **AudioServer** [🔗](#class_@GlobalScope_property_AudioServer) + +The [AudioServer](class_audioserver.md) singleton. + +
+ + + + + +[CameraServer](class_cameraserver.md) **CameraServer** [🔗](#class_@GlobalScope_property_CameraServer) + +The [CameraServer](class_cameraserver.md) singleton. + +
+ + + + + +[ClassDB](class_classdb.md) **ClassDB** [🔗](#class_@GlobalScope_property_ClassDB) + +The [ClassDB](class_classdb.md) singleton. + +
+ + + + + +[DisplayServer](class_displayserver.md) **DisplayServer** [🔗](#class_@GlobalScope_property_DisplayServer) + +The [DisplayServer](class_displayserver.md) singleton. + +
+ + + + + +[EditorInterface](class_editorinterface.md) **EditorInterface** [🔗](#class_@GlobalScope_property_EditorInterface) + +The [EditorInterface](class_editorinterface.md) singleton. + +\ **Note:** Only available in editor builds. + +
+ + + + + +[Engine](class_engine.md) **Engine** [🔗](#class_@GlobalScope_property_Engine) + +The [Engine](class_engine.md) singleton. + +
+ + + + + +[EngineDebugger](class_enginedebugger.md) **EngineDebugger** [🔗](#class_@GlobalScope_property_EngineDebugger) + +The [EngineDebugger](class_enginedebugger.md) singleton. + +
+ + + + + +[GDExtensionManager](class_gdextensionmanager.md) **GDExtensionManager** [🔗](#class_@GlobalScope_property_GDExtensionManager) + +The [GDExtensionManager](class_gdextensionmanager.md) singleton. + +
+ + + + + +[Geometry2D](class_geometry2d.md) **Geometry2D** [🔗](#class_@GlobalScope_property_Geometry2D) + +The [Geometry2D](class_geometry2d.md) singleton. + +
+ + + + + +[Geometry3D](class_geometry3d.md) **Geometry3D** [🔗](#class_@GlobalScope_property_Geometry3D) + +The [Geometry3D](class_geometry3d.md) singleton. + +
+ + + + + +[IP](class_ip.md) **IP** [🔗](#class_@GlobalScope_property_IP) + +The [IP](class_ip.md) singleton. + +
+ + + + + +[Input](class_input.md) **Input** [🔗](#class_@GlobalScope_property_Input) + +The [Input](class_input.md) singleton. + +
+ + + + + +[InputMap](class_inputmap.md) **InputMap** [🔗](#class_@GlobalScope_property_InputMap) + +The [InputMap](class_inputmap.md) singleton. + +
+ + + + + +[JavaClassWrapper](class_javaclasswrapper.md) **JavaClassWrapper** [🔗](#class_@GlobalScope_property_JavaClassWrapper) + +The [JavaClassWrapper](class_javaclasswrapper.md) singleton. + +\ **Note:** Only implemented on Android. + +
+ + + + + +[JavaScriptBridge](class_javascriptbridge.md) **JavaScriptBridge** [🔗](#class_@GlobalScope_property_JavaScriptBridge) + +The [JavaScriptBridge](class_javascriptbridge.md) singleton. + +\ **Note:** Only implemented on the Web platform. + +
+ + + + + +[MCPBridge](class_mcpbridge.md) **MCPBridge** [🔗](#class_@GlobalScope_property_MCPBridge) + +
+There is currently no description for this property. Please help us by contributing one! + +
+ +
+ + + + + +[MCPServer](class_mcpserver.md) **MCPServer** [🔗](#class_@GlobalScope_property_MCPServer) + +
+There is currently no description for this property. Please help us by contributing one! + +
+ +
+ + + + + +[Marshalls](class_marshalls.md) **Marshalls** [🔗](#class_@GlobalScope_property_Marshalls) + +The [Marshalls](class_marshalls.md) singleton. + +
+ + + + + +[NativeMenu](class_nativemenu.md) **NativeMenu** [🔗](#class_@GlobalScope_property_NativeMenu) + +The [NativeMenu](class_nativemenu.md) singleton. + +\ **Note:** Only implemented on macOS. + +
+ + + + + +[NavigationMeshGenerator](class_navigationmeshgenerator.md) **NavigationMeshGenerator** [🔗](#class_@GlobalScope_property_NavigationMeshGenerator) + +The [NavigationMeshGenerator](class_navigationmeshgenerator.md) singleton. + +
+ + + + + +[NavigationServer2D](class_navigationserver2d.md) **NavigationServer2D** [🔗](#class_@GlobalScope_property_NavigationServer2D) + +The [NavigationServer2D](class_navigationserver2d.md) singleton. + +
+ + + + + +[NavigationServer3D](class_navigationserver3d.md) **NavigationServer3D** [🔗](#class_@GlobalScope_property_NavigationServer3D) + +The [NavigationServer3D](class_navigationserver3d.md) singleton. + +
+ + + + + +[OS](class_os.md) **OS** [🔗](#class_@GlobalScope_property_OS) + +The [OS](class_os.md) singleton. + +
+ + + + + +[Performance](class_performance.md) **Performance** [🔗](#class_@GlobalScope_property_Performance) + +The [Performance](class_performance.md) singleton. + +
+ + + + + +[PhysicsServer2D](class_physicsserver2d.md) **PhysicsServer2D** [🔗](#class_@GlobalScope_property_PhysicsServer2D) + +The [PhysicsServer2D](class_physicsserver2d.md) singleton. + +
+ + + + + +[PhysicsServer2DManager](class_physicsserver2dmanager.md) **PhysicsServer2DManager** [🔗](#class_@GlobalScope_property_PhysicsServer2DManager) + +The [PhysicsServer2DManager](class_physicsserver2dmanager.md) singleton. + +
+ + + + + +[PhysicsServer3D](class_physicsserver3d.md) **PhysicsServer3D** [🔗](#class_@GlobalScope_property_PhysicsServer3D) + +The [PhysicsServer3D](class_physicsserver3d.md) singleton. + +
+ + + + + +[PhysicsServer3DManager](class_physicsserver3dmanager.md) **PhysicsServer3DManager** [🔗](#class_@GlobalScope_property_PhysicsServer3DManager) + +The [PhysicsServer3DManager](class_physicsserver3dmanager.md) singleton. + +
+ + + + + +[ProjectSettings](class_projectsettings.md) **ProjectSettings** [🔗](#class_@GlobalScope_property_ProjectSettings) + +The [ProjectSettings](class_projectsettings.md) singleton. + +
+ + + + + +[RenderingServer](class_renderingserver.md) **RenderingServer** [🔗](#class_@GlobalScope_property_RenderingServer) + +The [RenderingServer](class_renderingserver.md) singleton. + +
+ + + + + +[ResourceLoader](class_resourceloader.md) **ResourceLoader** [🔗](#class_@GlobalScope_property_ResourceLoader) + +The [ResourceLoader](class_resourceloader.md) singleton. + +
+ + + + + +[ResourceSaver](class_resourcesaver.md) **ResourceSaver** [🔗](#class_@GlobalScope_property_ResourceSaver) + +The [ResourceSaver](class_resourcesaver.md) singleton. + +
+ + + + + +[ResourceUID](class_resourceuid.md) **ResourceUID** [🔗](#class_@GlobalScope_property_ResourceUID) + +The [ResourceUID](class_resourceuid.md) singleton. + +
+ + + + + +[TextServerManager](class_textservermanager.md) **TextServerManager** [🔗](#class_@GlobalScope_property_TextServerManager) + +The [TextServerManager](class_textservermanager.md) singleton. + +
+ + + + + +[ThemeDB](class_themedb.md) **ThemeDB** [🔗](#class_@GlobalScope_property_ThemeDB) + +The [ThemeDB](class_themedb.md) singleton. + +
+ + + + + +[Time](class_time.md) **Time** [🔗](#class_@GlobalScope_property_Time) + +The [Time](class_time.md) singleton. + +
+ + + + + +[TranslationServer](class_translationserver.md) **TranslationServer** [🔗](#class_@GlobalScope_property_TranslationServer) + +The [TranslationServer](class_translationserver.md) singleton. + +
+ + + + + +[WorkerThreadPool](class_workerthreadpool.md) **WorkerThreadPool** [🔗](#class_@GlobalScope_property_WorkerThreadPool) + +The [WorkerThreadPool](class_workerthreadpool.md) singleton. + +
+ + + + + +[XRServer](class_xrserver.md) **XRServer** [🔗](#class_@GlobalScope_property_XRServer) + +The [XRServer](class_xrserver.md) singleton. + +
+ + + +## Method Descriptions + + + + + +[Variant](class_variant.md) **abs**\ (\ x\: [Variant](class_variant.md)\ ) [🔗](#class_@GlobalScope_method_abs) + +Returns the absolute value of a [Variant](class_variant.md) parameter `x` (i.e. non-negative value). Supported types: [int](class_int.md), [float](class_float.md), [Vector2](class_vector2.md), [Vector2i](class_vector2i.md), [Vector3](class_vector3.md), [Vector3i](class_vector3i.md), [Vector4](class_vector4.md), [Vector4i](class_vector4i.md). + +``` + var a = abs(-1) + # a is 1 + + var b = abs(-1.2) + # b is 1.2 + + var c = abs(Vector2(-3.5, -4)) + # c is (3.5, 4) + + var d = abs(Vector2i(-5, -6)) + # d is (5, 6) + + var e = abs(Vector3(-7, 8.5, -3.8)) + # e is (7, 8.5, 3.8) + + var f = abs(Vector3i(-7, -8, -9)) + # f is (7, 8, 9) +``` + +\ **Note:** For better type safety, use [absf()](class_@globalscope.md#class_@GlobalScope_method_absf), [absi()](class_@globalscope.md#class_@GlobalScope_method_absi), [Vector2.abs()](class_vector2.md#class_Vector2_method_abs), [Vector2i.abs()](class_vector2i.md#class_Vector2i_method_abs), [Vector3.abs()](class_vector3.md#class_Vector3_method_abs), [Vector3i.abs()](class_vector3i.md#class_Vector3i_method_abs), [Vector4.abs()](class_vector4.md#class_Vector4_method_abs), or [Vector4i.abs()](class_vector4i.md#class_Vector4i_method_abs). + +
+ + + + + +[float](class_float.md) **absf**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_absf) + +Returns the absolute value of float parameter `x` (i.e. positive value). + +``` + # a is 1.2 + var a = absf(-1.2) +``` + +
+ + + + + +[int](class_int.md) **absi**\ (\ x\: [int](class_int.md)\ ) [🔗](#class_@GlobalScope_method_absi) + +Returns the absolute value of int parameter `x` (i.e. positive value). + +``` + # a is 1 + var a = absi(-1) +``` + +
+ + + + + +[float](class_float.md) **acos**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_acos) + +Returns the arc cosine of `x` in radians. Use to get the angle of cosine `x`. `x` will be clamped between ``-1.0`` and ``1.0`` (inclusive), in order to prevent [acos()](class_@globalscope.md#class_@GlobalScope_method_acos) from returning [@GDScript.NAN](class_@gdscript.md#class_@GDScript_constant_NAN). + +``` + # c is 0.523599 or 30 degrees if converted with rad_to_deg(c) + var c = acos(0.866025) +``` + +
+ + + + + +[float](class_float.md) **acosh**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_acosh) + +Returns the hyperbolic arc (also called inverse) cosine of `x`, returning a value in radians. Use it to get the angle from an angle's cosine in hyperbolic space if `x` is larger or equal to 1. For values of `x` lower than 1, it will return 0, in order to prevent [acosh()](class_@globalscope.md#class_@GlobalScope_method_acosh) from returning [@GDScript.NAN](class_@gdscript.md#class_@GDScript_constant_NAN). + +``` + var a = acosh(2) # Returns 1.31695789692482 + cosh(a) # Returns 2 + + var b = acosh(-1) # Returns 0 +``` + +
+ + + + + +[float](class_float.md) **angle_difference**\ (\ from\: [float](class_float.md), to\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_angle_difference) + +Returns the difference between the two angles (in radians), in the range of ``[-PI, +PI]``. When `from` and `to` are opposite, returns ``-PI`` if `from` is smaller than `to`, or ``PI`` otherwise. + +
+ + + + + +[float](class_float.md) **asin**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_asin) + +Returns the arc sine of `x` in radians. Use to get the angle of sine `x`. `x` will be clamped between ``-1.0`` and ``1.0`` (inclusive), in order to prevent [asin()](class_@globalscope.md#class_@GlobalScope_method_asin) from returning [@GDScript.NAN](class_@gdscript.md#class_@GDScript_constant_NAN). + +``` + # s is 0.523599 or 30 degrees if converted with rad_to_deg(s) + var s = asin(0.5) +``` + +
+ + + + + +[float](class_float.md) **asinh**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_asinh) + +Returns the hyperbolic arc (also called inverse) sine of `x`, returning a value in radians. Use it to get the angle from an angle's sine in hyperbolic space. + +``` + var a = asinh(0.9) # Returns 0.8088669356527824 + sinh(a) # Returns 0.9 +``` + +
+ + + + + +[float](class_float.md) **atan**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_atan) + +Returns the arc tangent of `x` in radians. Use it to get the angle from an angle's tangent in trigonometry. + +The method cannot know in which quadrant the angle should fall. See [atan2()](class_@globalscope.md#class_@GlobalScope_method_atan2) if you have both ``y`` and ``x``. + +``` + var a = atan(0.5) # a is 0.463648 +``` + +If `x` is between ``-PI / 2`` and ``PI / 2`` (inclusive), ``atan(tan(x))`` is equal to `x`. + +
+ + + + + +[float](class_float.md) **atan2**\ (\ y\: [float](class_float.md), x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_atan2) + +Returns the arc tangent of ``y/x`` in radians. Use to get the angle of tangent ``y/x``. To compute the value, the method takes into account the sign of both arguments in order to determine the quadrant. + +Important note: The Y coordinate comes first, by convention. + +``` + var a = atan2(0, -1) # a is 3.141593 +``` + +
+ + + + + +[float](class_float.md) **atanh**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_atanh) + +Returns the hyperbolic arc (also called inverse) tangent of `x`, returning a value in radians. Use it to get the angle from an angle's tangent in hyperbolic space if `x` is between -1 and 1 (non-inclusive). + +In mathematics, the inverse hyperbolic tangent is only defined for -1 < `x` < 1 in the real set, so values equal or lower to -1 for `x` return negative [@GDScript.INF](class_@gdscript.md#class_@GDScript_constant_INF) and values equal or higher than 1 return positive [@GDScript.INF](class_@gdscript.md#class_@GDScript_constant_INF) in order to prevent [atanh()](class_@globalscope.md#class_@GlobalScope_method_atanh) from returning [@GDScript.NAN](class_@gdscript.md#class_@GDScript_constant_NAN). + +``` + var a = atanh(0.9) # Returns 1.47221948958322 + tanh(a) # Returns 0.9 + + var b = atanh(-2) # Returns -inf + tanh(b) # Returns -1 +``` + +
+ + + + + +[float](class_float.md) **bezier_derivative**\ (\ start\: [float](class_float.md), control_1\: [float](class_float.md), control_2\: [float](class_float.md), end\: [float](class_float.md), t\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_bezier_derivative) + +Returns the derivative at the given `t` on a one-dimensional [Bézier curve](https://en.wikipedia.org/wiki/B%C3%A9zier_curve) defined by the given `control_1`, `control_2`, and `end` points. + +
+ + + + + +[float](class_float.md) **bezier_interpolate**\ (\ start\: [float](class_float.md), control_1\: [float](class_float.md), control_2\: [float](class_float.md), end\: [float](class_float.md), t\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_bezier_interpolate) + +Returns the point at the given `t` on a one-dimensional [Bézier curve](https://en.wikipedia.org/wiki/B%C3%A9zier_curve) defined by the given `control_1`, `control_2`, and `end` points. + +
+ + + + + +[Variant](class_variant.md) **bytes_to_var**\ (\ bytes\: [PackedByteArray](class_packedbytearray.md)\ ) [🔗](#class_@GlobalScope_method_bytes_to_var) + +Decodes a byte array back to a [Variant](class_variant.md) value, without decoding objects. + +\ **Note:** If you need object deserialization, see [bytes_to_var_with_objects()](class_@globalscope.md#class_@GlobalScope_method_bytes_to_var_with_objects). + +
+ + + + + +[Variant](class_variant.md) **bytes_to_var_with_objects**\ (\ bytes\: [PackedByteArray](class_packedbytearray.md)\ ) [🔗](#class_@GlobalScope_method_bytes_to_var_with_objects) + +Decodes a byte array back to a [Variant](class_variant.md) value. Decoding objects is allowed. + +\ **Warning:** Deserialized object can contain code which gets executed. Do not use this option if the serialized object comes from untrusted sources to avoid potential security threats (remote code execution). + +
+ + + + + +[Variant](class_variant.md) **ceil**\ (\ x\: [Variant](class_variant.md)\ ) [🔗](#class_@GlobalScope_method_ceil) + +Rounds `x` upward (towards positive infinity), returning the smallest whole number that is not less than `x`. Supported types: [int](class_int.md), [float](class_float.md), [Vector2](class_vector2.md), [Vector2i](class_vector2i.md), [Vector3](class_vector3.md), [Vector3i](class_vector3i.md), [Vector4](class_vector4.md), [Vector4i](class_vector4i.md). + +``` + var i = ceil(1.45) # i is 2.0 + i = ceil(1.001) # i is 2.0 +``` + +See also [floor()](class_@globalscope.md#class_@GlobalScope_method_floor), [round()](class_@globalscope.md#class_@GlobalScope_method_round), and [snapped()](class_@globalscope.md#class_@GlobalScope_method_snapped). + +\ **Note:** For better type safety, use [ceilf()](class_@globalscope.md#class_@GlobalScope_method_ceilf), [ceili()](class_@globalscope.md#class_@GlobalScope_method_ceili), [Vector2.ceil()](class_vector2.md#class_Vector2_method_ceil), [Vector3.ceil()](class_vector3.md#class_Vector3_method_ceil), or [Vector4.ceil()](class_vector4.md#class_Vector4_method_ceil). + +
+ + + + + +[float](class_float.md) **ceilf**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_ceilf) + +Rounds `x` upward (towards positive infinity), returning the smallest whole number that is not less than `x`. + +A type-safe version of [ceil()](class_@globalscope.md#class_@GlobalScope_method_ceil), returning a [float](class_float.md). + +
+ + + + + +[int](class_int.md) **ceili**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_ceili) + +Rounds `x` upward (towards positive infinity), returning the smallest whole number that is not less than `x`. + +A type-safe version of [ceil()](class_@globalscope.md#class_@GlobalScope_method_ceil), returning an [int](class_int.md). + +
+ + + + + +[Variant](class_variant.md) **clamp**\ (\ value\: [Variant](class_variant.md), min\: [Variant](class_variant.md), max\: [Variant](class_variant.md)\ ) [🔗](#class_@GlobalScope_method_clamp) + +Clamps the `value`, returning a [Variant](class_variant.md) not less than `min` and not more than `max`. Any values that can be compared with the less than and greater than operators will work. + +``` + var a = clamp(-10, -1, 5) + # a is -1 + + var b = clamp(8.1, 0.9, 5.5) + # b is 5.5 +``` + +\ **Note:** For better type safety, use [clampf()](class_@globalscope.md#class_@GlobalScope_method_clampf), [clampi()](class_@globalscope.md#class_@GlobalScope_method_clampi), [Vector2.clamp()](class_vector2.md#class_Vector2_method_clamp), [Vector2i.clamp()](class_vector2i.md#class_Vector2i_method_clamp), [Vector3.clamp()](class_vector3.md#class_Vector3_method_clamp), [Vector3i.clamp()](class_vector3i.md#class_Vector3i_method_clamp), [Vector4.clamp()](class_vector4.md#class_Vector4_method_clamp), [Vector4i.clamp()](class_vector4i.md#class_Vector4i_method_clamp), or [Color.clamp()](class_color.md#class_Color_method_clamp) (not currently supported by this method). + +\ **Note:** When using this on vectors it will *not* perform component-wise clamping, and will pick `min` if ``value < min`` or `max` if ``value > max``. To perform component-wise clamping use the methods listed above. + +
+ + + + + +[float](class_float.md) **clampf**\ (\ value\: [float](class_float.md), min\: [float](class_float.md), max\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_clampf) + +Clamps the `value`, returning a [float](class_float.md) not less than `min` and not more than `max`. + +``` + var speed = 42.1 + var a = clampf(speed, 1.0, 20.5) # a is 20.5 + + speed = -10.0 + var b = clampf(speed, -1.0, 1.0) # b is -1.0 +``` + +
+ + + + + +[int](class_int.md) **clampi**\ (\ value\: [int](class_int.md), min\: [int](class_int.md), max\: [int](class_int.md)\ ) [🔗](#class_@GlobalScope_method_clampi) + +Clamps the `value`, returning an [int](class_int.md) not less than `min` and not more than `max`. + +``` + var speed = 42 + var a = clampi(speed, 1, 20) # a is 20 + + speed = -10 + var b = clampi(speed, -1, 1) # b is -1 +``` + +
+ + + + + +[float](class_float.md) **cos**\ (\ angle_rad\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_cos) + +Returns the cosine of angle `angle_rad` in radians. + +``` + cos(PI * 2) # Returns 1.0 + cos(PI) # Returns -1.0 + cos(deg_to_rad(90)) # Returns 0.0 +``` + +
+ + + + + +[float](class_float.md) **cosh**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_cosh) + +Returns the hyperbolic cosine of `x` in radians. + +``` + print(cosh(1)) # Prints 1.543081 +``` + +
+ + + + + +[float](class_float.md) **cubic_interpolate**\ (\ from\: [float](class_float.md), to\: [float](class_float.md), pre\: [float](class_float.md), post\: [float](class_float.md), weight\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_cubic_interpolate) + +Cubic interpolates between two values by the factor defined in `weight` with `pre` and `post` values. + +
+ + + + + +[float](class_float.md) **cubic_interpolate_angle**\ (\ from\: [float](class_float.md), to\: [float](class_float.md), pre\: [float](class_float.md), post\: [float](class_float.md), weight\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_cubic_interpolate_angle) + +Cubic interpolates between two rotation values with shortest path by the factor defined in `weight` with `pre` and `post` values. See also [lerp_angle()](class_@globalscope.md#class_@GlobalScope_method_lerp_angle). + +
+ + + + + +[float](class_float.md) **cubic_interpolate_angle_in_time**\ (\ from\: [float](class_float.md), to\: [float](class_float.md), pre\: [float](class_float.md), post\: [float](class_float.md), weight\: [float](class_float.md), to_t\: [float](class_float.md), pre_t\: [float](class_float.md), post_t\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_cubic_interpolate_angle_in_time) + +Cubic interpolates between two rotation values with shortest path by the factor defined in `weight` with `pre` and `post` values. See also [lerp_angle()](class_@globalscope.md#class_@GlobalScope_method_lerp_angle). + +It can perform smoother interpolation than [cubic_interpolate()](class_@globalscope.md#class_@GlobalScope_method_cubic_interpolate) by the time values. + +
+ + + + + +[float](class_float.md) **cubic_interpolate_in_time**\ (\ from\: [float](class_float.md), to\: [float](class_float.md), pre\: [float](class_float.md), post\: [float](class_float.md), weight\: [float](class_float.md), to_t\: [float](class_float.md), pre_t\: [float](class_float.md), post_t\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_cubic_interpolate_in_time) + +Cubic interpolates between two values by the factor defined in `weight` with `pre` and `post` values. + +It can perform smoother interpolation than [cubic_interpolate()](class_@globalscope.md#class_@GlobalScope_method_cubic_interpolate) by the time values. + +
+ + + + + +[float](class_float.md) **db_to_linear**\ (\ db\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_db_to_linear) + +Converts from decibels to linear energy (audio). + +
+ + + + + +[float](class_float.md) **deg_to_rad**\ (\ deg\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_deg_to_rad) + +Converts an angle expressed in degrees to radians. + +``` + var r = deg_to_rad(180) # r is 3.141593 +``` + +
+ + + + + +[float](class_float.md) **ease**\ (\ x\: [float](class_float.md), curve\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_ease) + +Returns an "eased" value of `x` based on an easing function defined with `curve`. This easing function is based on an exponent. The `curve` can be any floating-point number, with specific values leading to the following behaviors: + +```text + - Lower than -1.0 (exclusive): Ease in-out + - -1.0: Linear + - Between -1.0 and 0.0 (exclusive): Ease out-in + - 0.0: Constant + - Between 0.0 to 1.0 (exclusive): Ease out + - 1.0: Linear + - Greater than 1.0 (exclusive): Ease in +``` + +\ [ease() curve values cheatsheet](https://raw.githubusercontent.com/redot-engine/redot-docs/master/img/ease_cheatsheet.png)\ + +See also [smoothstep()](class_@globalscope.md#class_@GlobalScope_method_smoothstep). If you need to perform more advanced transitions, use [Tween.interpolate_value()](class_tween.md#class_Tween_method_interpolate_value). + +
+ + + + + +[String](class_string.md) **error_string**\ (\ error\: [int](class_int.md)\ ) [🔗](#class_@GlobalScope_method_error_string) + +Returns a human-readable name for the given [Error](class_@globalscope.md#enum_@GlobalScope_Error) code. + +``` + print(OK) # Prints 0 + print(error_string(OK)) # Prints "OK" + print(error_string(ERR_BUSY)) # Prints "Busy" + print(error_string(ERR_OUT_OF_MEMORY)) # Prints "Out of memory" +``` + +
+ + + + + +[float](class_float.md) **exp**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_exp) + +The natural exponential function. It raises the mathematical constant *e* to the power of `x` and returns it. + +\ *e* has an approximate value of 2.71828, and can be obtained with ``exp(1)``. + +For exponents to other bases use the method [pow()](class_@globalscope.md#class_@GlobalScope_method_pow). + +``` + var a = exp(2) # Approximately 7.39 +``` + +
+ + + + + +[Variant](class_variant.md) **floor**\ (\ x\: [Variant](class_variant.md)\ ) [🔗](#class_@GlobalScope_method_floor) + +Rounds `x` downward (towards negative infinity), returning the largest whole number that is not more than `x`. Supported types: [int](class_int.md), [float](class_float.md), [Vector2](class_vector2.md), [Vector2i](class_vector2i.md), [Vector3](class_vector3.md), [Vector3i](class_vector3i.md), [Vector4](class_vector4.md), [Vector4i](class_vector4i.md). + +``` + var a = floor(2.99) # a is 2.0 + a = floor(-2.99) # a is -3.0 +``` + +See also [ceil()](class_@globalscope.md#class_@GlobalScope_method_ceil), [round()](class_@globalscope.md#class_@GlobalScope_method_round), and [snapped()](class_@globalscope.md#class_@GlobalScope_method_snapped). + +\ **Note:** For better type safety, use [floorf()](class_@globalscope.md#class_@GlobalScope_method_floorf), [floori()](class_@globalscope.md#class_@GlobalScope_method_floori), [Vector2.floor()](class_vector2.md#class_Vector2_method_floor), [Vector3.floor()](class_vector3.md#class_Vector3_method_floor), or [Vector4.floor()](class_vector4.md#class_Vector4_method_floor). + +
+ + + + + +[float](class_float.md) **floorf**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_floorf) + +Rounds `x` downward (towards negative infinity), returning the largest whole number that is not more than `x`. + +A type-safe version of [floor()](class_@globalscope.md#class_@GlobalScope_method_floor), returning a [float](class_float.md). + +
+ + + + + +[int](class_int.md) **floori**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_floori) + +Rounds `x` downward (towards negative infinity), returning the largest whole number that is not more than `x`. + +A type-safe version of [floor()](class_@globalscope.md#class_@GlobalScope_method_floor), returning an [int](class_int.md). + +\ **Note:** This function is *not* the same as ``int(x)``, which rounds towards 0. + +
+ + + + + +[float](class_float.md) **fmod**\ (\ x\: [float](class_float.md), y\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_fmod) + +Returns the floating-point remainder of `x` divided by `y`, keeping the sign of `x`. + +``` + var remainder = fmod(7, 5.5) # remainder is 1.5 +``` + +For the integer remainder operation, use the ``%`` operator. + +
+ + + + + +[float](class_float.md) **fposmod**\ (\ x\: [float](class_float.md), y\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_fposmod) + +Returns the floating-point modulus of `x` divided by `y`, wrapping equally in positive and negative. + +``` + print(" (x) (fmod(x, 1.5)) (fposmod(x, 1.5))") + for i in 7: + var x = i * 0.5 - 1.5 + print("%4.1f %4.1f | %4.1f" % [x, fmod(x, 1.5), fposmod(x, 1.5)]) +``` + +Prints: + +```text + (x) (fmod(x, 1.5)) (fposmod(x, 1.5)) + -1.5 -0.0 | 0.0 + -1.0 -1.0 | 0.5 + -0.5 -0.5 | 1.0 + 0.0 0.0 | 0.0 + 0.5 0.5 | 0.5 + 1.0 1.0 | 1.0 + 1.5 0.0 | 0.0 +``` + +
+ + + + + +[int](class_int.md) **hash**\ (\ variable\: [Variant](class_variant.md)\ ) [🔗](#class_@GlobalScope_method_hash) + +Returns the integer hash of the passed `variable`. + + + + +```gdscript + print(hash("a")) # Prints 177670 +``` + +```csharp + GD.Print(GD.Hash("a")); // Prints 177670 +``` + + + +
+ + + + + +[Object](class_object.md) **instance_from_id**\ (\ instance_id\: [int](class_int.md)\ ) [🔗](#class_@GlobalScope_method_instance_from_id) + +Returns the [Object](class_object.md) that corresponds to `instance_id`. All Objects have a unique instance ID. See also [Object.get_instance_id()](class_object.md#class_Object_method_get_instance_id). + + + + +```gdscript + var drink = "water" + + func _ready(): + var id = get_instance_id() + var instance = instance_from_id(id) + print(instance.drink) # Prints "water" +``` + +```csharp + public partial class MyNode : Node + { + public string Drink { get; set; } = "water"; + + public override void _Ready() + { + ulong id = GetInstanceId(); + var instance = (MyNode)InstanceFromId(Id); + GD.Print(instance.Drink); // Prints "water" + } + } +``` + + + +
+ + + + + +[float](class_float.md) **inverse_lerp**\ (\ from\: [float](class_float.md), to\: [float](class_float.md), weight\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_inverse_lerp) + +Returns an interpolation or extrapolation factor considering the range specified in `from` and `to`, and the interpolated value specified in `weight`. The returned value will be between ``0.0`` and ``1.0`` if `weight` is between `from` and `to` (inclusive). If `weight` is located outside this range, then an extrapolation factor will be returned (return value lower than ``0.0`` or greater than ``1.0``). Use [clamp()](class_@globalscope.md#class_@GlobalScope_method_clamp) on the result of [inverse_lerp()](class_@globalscope.md#class_@GlobalScope_method_inverse_lerp) if this is not desired. + +``` + # The interpolation ratio in the `lerp()` call below is 0.75. + var middle = lerp(20, 30, 0.75) + # middle is now 27.5. + + # Now, we pretend to have forgotten the original ratio and want to get it back. + var ratio = inverse_lerp(20, 30, 27.5) + # ratio is now 0.75. +``` + +See also [lerp()](class_@globalscope.md#class_@GlobalScope_method_lerp), which performs the reverse of this operation, and [remap()](class_@globalscope.md#class_@GlobalScope_method_remap) to map a continuous series of values to another. + +
+ + + + + +[bool](class_bool.md) **is_equal_approx**\ (\ a\: [float](class_float.md), b\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_is_equal_approx) + +Returns ``true`` if `a` and `b` are approximately equal to each other. + +Here, "approximately equal" means that `a` and `b` are within a small internal epsilon of each other, which scales with the magnitude of the numbers. + +Infinity values of the same sign are considered equal. + +
+ + + + + +[bool](class_bool.md) **is_finite**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_is_finite) + +Returns whether `x` is a finite value, i.e. it is not [@GDScript.NAN](class_@gdscript.md#class_@GDScript_constant_NAN), positive infinity, or negative infinity. See also [is_inf()](class_@globalscope.md#class_@GlobalScope_method_is_inf) and [is_nan()](class_@globalscope.md#class_@GlobalScope_method_is_nan). + +
+ + + + + +[bool](class_bool.md) **is_inf**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_is_inf) + +Returns ``true`` if `x` is either positive infinity or negative infinity. See also [is_finite()](class_@globalscope.md#class_@GlobalScope_method_is_finite) and [is_nan()](class_@globalscope.md#class_@GlobalScope_method_is_nan). + +
+ + + + + +[bool](class_bool.md) **is_instance_id_valid**\ (\ id\: [int](class_int.md)\ ) [🔗](#class_@GlobalScope_method_is_instance_id_valid) + +Returns ``true`` if the Object that corresponds to `id` is a valid object (e.g. has not been deleted from memory). All Objects have a unique instance ID. + +
+ + + + + +[bool](class_bool.md) **is_instance_valid**\ (\ instance\: [Variant](class_variant.md)\ ) [🔗](#class_@GlobalScope_method_is_instance_valid) + +Returns ``true`` if `instance` is a valid Object (e.g. has not been deleted from memory). + +
+ + + + + +[bool](class_bool.md) **is_nan**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_is_nan) + +Returns ``true`` if `x` is a NaN ("Not a Number" or invalid) value. This method is needed as [@GDScript.NAN](class_@gdscript.md#class_@GDScript_constant_NAN) is not equal to itself, which means ``x == NAN`` can't be used to check whether a value is a NaN. + +
+ + + + + +[bool](class_bool.md) **is_same**\ (\ a\: [Variant](class_variant.md), b\: [Variant](class_variant.md)\ ) [🔗](#class_@GlobalScope_method_is_same) + +Returns ``true``, for value types, if `a` and `b` share the same value. Returns ``true``, for reference types, if the references of `a` and `b` are the same. + +``` + # Vector2 is a value type + var vec2_a = Vector2(0, 0) + var vec2_b = Vector2(0, 0) + var vec2_c = Vector2(1, 1) + is_same(vec2_a, vec2_a) # true + is_same(vec2_a, vec2_b) # true + is_same(vec2_a, vec2_c) # false + + # Array is a reference type + var arr_a = [] + var arr_b = [] + is_same(arr_a, arr_a) # true + is_same(arr_a, arr_b) # false +``` + +These are [Variant](class_variant.md) value types: ``null``, [bool](class_bool.md), [int](class_int.md), [float](class_float.md), [String](class_string.md), [StringName](class_stringname.md), [Vector2](class_vector2.md), [Vector2i](class_vector2i.md), [Vector3](class_vector3.md), [Vector3i](class_vector3i.md), [Vector4](class_vector4.md), [Vector4i](class_vector4i.md), [Rect2](class_rect2.md), [Rect2i](class_rect2i.md), [Transform2D](class_transform2d.md), [Transform3D](class_transform3d.md), [Plane](class_plane.md), [Quaternion](class_quaternion.md), [AABB](class_aabb.md), [Basis](class_basis.md), [Projection](class_projection.md), [Color](class_color.md), [NodePath](class_nodepath.md), [RID](class_rid.md), [Callable](class_callable.md) and [Signal](class_signal.md). + +These are [Variant](class_variant.md) reference types: [Object](class_object.md), [Dictionary](class_dictionary.md), [Array](class_array.md), [PackedByteArray](class_packedbytearray.md), [PackedInt32Array](class_packedint32array.md), [PackedInt64Array](class_packedint64array.md), [PackedFloat32Array](class_packedfloat32array.md), [PackedFloat64Array](class_packedfloat64array.md), [PackedStringArray](class_packedstringarray.md), [PackedVector2Array](class_packedvector2array.md), [PackedVector3Array](class_packedvector3array.md), [PackedVector4Array](class_packedvector4array.md), and [PackedColorArray](class_packedcolorarray.md). + +
+ + + + + +[bool](class_bool.md) **is_zero_approx**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_is_zero_approx) + +Returns ``true`` if `x` is zero or almost zero. The comparison is done using a tolerance calculation with a small internal epsilon. + +This function is faster than using [is_equal_approx()](class_@globalscope.md#class_@GlobalScope_method_is_equal_approx) with one value as zero. + +
+ + + + + +[Variant](class_variant.md) **lerp**\ (\ from\: [Variant](class_variant.md), to\: [Variant](class_variant.md), weight\: [Variant](class_variant.md)\ ) [🔗](#class_@GlobalScope_method_lerp) + +Linearly interpolates between two values by the factor defined in `weight`. To perform interpolation, `weight` should be between ``0.0`` and ``1.0`` (inclusive). However, values outside this range are allowed and can be used to perform *extrapolation*. If this is not desired, use [clampf()](class_@globalscope.md#class_@GlobalScope_method_clampf) to limit `weight`. + +Both `from` and `to` must be the same type. Supported types: [int](class_int.md), [float](class_float.md), [Vector2](class_vector2.md), [Vector3](class_vector3.md), [Vector4](class_vector4.md), [Color](class_color.md), [Quaternion](class_quaternion.md), [Basis](class_basis.md), [Transform2D](class_transform2d.md), [Transform3D](class_transform3d.md). + +``` + lerp(0, 4, 0.75) # Returns 3.0 +``` + +See also [inverse_lerp()](class_@globalscope.md#class_@GlobalScope_method_inverse_lerp) which performs the reverse of this operation. To perform eased interpolation with [lerp()](class_@globalscope.md#class_@GlobalScope_method_lerp), combine it with [ease()](class_@globalscope.md#class_@GlobalScope_method_ease) or [smoothstep()](class_@globalscope.md#class_@GlobalScope_method_smoothstep). See also [remap()](class_@globalscope.md#class_@GlobalScope_method_remap) to map a continuous series of values to another. + +\ **Note:** For better type safety, use [lerpf()](class_@globalscope.md#class_@GlobalScope_method_lerpf), [Vector2.lerp()](class_vector2.md#class_Vector2_method_lerp), [Vector3.lerp()](class_vector3.md#class_Vector3_method_lerp), [Vector4.lerp()](class_vector4.md#class_Vector4_method_lerp), [Color.lerp()](class_color.md#class_Color_method_lerp), [Quaternion.slerp()](class_quaternion.md#class_Quaternion_method_slerp), [Basis.slerp()](class_basis.md#class_Basis_method_slerp), [Transform2D.interpolate_with()](class_transform2d.md#class_Transform2D_method_interpolate_with), or [Transform3D.interpolate_with()](class_transform3d.md#class_Transform3D_method_interpolate_with). + +
+ + + + + +[float](class_float.md) **lerp_angle**\ (\ from\: [float](class_float.md), to\: [float](class_float.md), weight\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_lerp_angle) + +Linearly interpolates between two angles (in radians) by a `weight` value between 0.0 and 1.0. + +Similar to [lerp()](class_@globalscope.md#class_@GlobalScope_method_lerp), but interpolates correctly when the angles wrap around [@GDScript.TAU](class_@gdscript.md#class_@GDScript_constant_TAU). To perform eased interpolation with [lerp_angle()](class_@globalscope.md#class_@GlobalScope_method_lerp_angle), combine it with [ease()](class_@globalscope.md#class_@GlobalScope_method_ease) or [smoothstep()](class_@globalscope.md#class_@GlobalScope_method_smoothstep). + +``` + extends Sprite + var elapsed = 0.0 + func _process(delta): + var min_angle = deg_to_rad(0.0) + var max_angle = deg_to_rad(90.0) + rotation = lerp_angle(min_angle, max_angle, elapsed) + elapsed += delta +``` + +\ **Note:** This function lerps through the shortest path between `from` and `to`. However, when these two angles are approximately ``PI + k * TAU`` apart for any integer ``k``, it's not obvious which way they lerp due to floating-point precision errors. For example, ``lerp_angle(0, PI, weight)`` lerps counter-clockwise, while ``lerp_angle(0, PI + 5 * TAU, weight)`` lerps clockwise. + +
+ + + + + +[float](class_float.md) **lerpf**\ (\ from\: [float](class_float.md), to\: [float](class_float.md), weight\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_lerpf) + +Linearly interpolates between two values by the factor defined in `weight`. To perform interpolation, `weight` should be between ``0.0`` and ``1.0`` (inclusive). However, values outside this range are allowed and can be used to perform *extrapolation*. If this is not desired, use [clampf()](class_@globalscope.md#class_@GlobalScope_method_clampf) on the result of this function. + +``` + lerpf(0, 4, 0.75) # Returns 3.0 +``` + +See also [inverse_lerp()](class_@globalscope.md#class_@GlobalScope_method_inverse_lerp) which performs the reverse of this operation. To perform eased interpolation with [lerp()](class_@globalscope.md#class_@GlobalScope_method_lerp), combine it with [ease()](class_@globalscope.md#class_@GlobalScope_method_ease) or [smoothstep()](class_@globalscope.md#class_@GlobalScope_method_smoothstep). + +
+ + + + + +[float](class_float.md) **linear_to_db**\ (\ lin\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_linear_to_db) + +Converts from linear energy to decibels (audio). Since volume is not normally linear, this can be used to implement volume sliders that behave as expected. + +\ **Example:** Change the Master bus's volume through a [Slider](class_slider.md) node, which ranges from ``0.0`` to ``1.0``: + +``` + AudioServer.set_bus_volume_db(AudioServer.get_bus_index("Master"), linear_to_db($Slider.value)) +``` + +
+ + + + + +[float](class_float.md) **log**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_log) + +Returns the [natural logarithm](https://en.wikipedia.org/wiki/Natural_logarithm) of `x` (base [[i]e[/i]](https://en.wikipedia.org/wiki/E_(mathematical_constant)), with *e* being approximately 2.71828). This is the amount of time needed to reach a certain level of continuous growth. + +\ **Note:** This is not the same as the "log" function on most calculators, which uses a base 10 logarithm. To use base 10 logarithm, use ``log(x) / log(10)``. + +``` + log(10) # Returns 2.302585 +``` + +\ **Note:** The logarithm of ``0`` returns ``-inf``, while negative values return ``-nan``. + +
+ + + + + +[Variant](class_variant.md) **max**\ (\ ...\ ) vararg [🔗](#class_@GlobalScope_method_max) + +Returns the maximum of the given numeric values. This function can take any number of arguments. + +``` + max(1, 7, 3, -6, 5) # Returns 7 +``` + +\ **Note:** When using this on vectors it will *not* perform component-wise maximum, and will pick the largest value when compared using ``x < y``. To perform component-wise maximum, use [Vector2.max()](class_vector2.md#class_Vector2_method_max), [Vector2i.max()](class_vector2i.md#class_Vector2i_method_max), [Vector3.max()](class_vector3.md#class_Vector3_method_max), [Vector3i.max()](class_vector3i.md#class_Vector3i_method_max), [Vector4.max()](class_vector4.md#class_Vector4_method_max), and [Vector4i.max()](class_vector4i.md#class_Vector4i_method_max). + +
+ + + + + +[float](class_float.md) **maxf**\ (\ a\: [float](class_float.md), b\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_maxf) + +Returns the maximum of two [float](class_float.md) values. + +``` + maxf(3.6, 24) # Returns 24.0 + maxf(-3.99, -4) # Returns -3.99 +``` + +
+ + + + + +[int](class_int.md) **maxi**\ (\ a\: [int](class_int.md), b\: [int](class_int.md)\ ) [🔗](#class_@GlobalScope_method_maxi) + +Returns the maximum of two [int](class_int.md) values. + +``` + maxi(1, 2) # Returns 2 + maxi(-3, -4) # Returns -3 +``` + +
+ + + + + +[Variant](class_variant.md) **min**\ (\ ...\ ) vararg [🔗](#class_@GlobalScope_method_min) + +Returns the minimum of the given numeric values. This function can take any number of arguments. + +``` + min(1, 7, 3, -6, 5) # Returns -6 +``` + +\ **Note:** When using this on vectors it will *not* perform component-wise minimum, and will pick the smallest value when compared using ``x < y``. To perform component-wise minimum, use [Vector2.min()](class_vector2.md#class_Vector2_method_min), [Vector2i.min()](class_vector2i.md#class_Vector2i_method_min), [Vector3.min()](class_vector3.md#class_Vector3_method_min), [Vector3i.min()](class_vector3i.md#class_Vector3i_method_min), [Vector4.min()](class_vector4.md#class_Vector4_method_min), and [Vector4i.min()](class_vector4i.md#class_Vector4i_method_min). + +
+ + + + + +[float](class_float.md) **minf**\ (\ a\: [float](class_float.md), b\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_minf) + +Returns the minimum of two [float](class_float.md) values. + +``` + minf(3.6, 24) # Returns 3.6 + minf(-3.99, -4) # Returns -4.0 +``` + +
+ + + + + +[int](class_int.md) **mini**\ (\ a\: [int](class_int.md), b\: [int](class_int.md)\ ) [🔗](#class_@GlobalScope_method_mini) + +Returns the minimum of two [int](class_int.md) values. + +``` + mini(1, 2) # Returns 1 + mini(-3, -4) # Returns -4 +``` + +
+ + + + + +[float](class_float.md) **move_toward**\ (\ from\: [float](class_float.md), to\: [float](class_float.md), delta\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_move_toward) + +Moves `from` toward `to` by the `delta` amount. Will not go past `to`. + +Use a negative `delta` value to move away. + +``` + move_toward(5, 10, 4) # Returns 9 + move_toward(10, 5, 4) # Returns 6 + move_toward(5, 10, 9) # Returns 10 + move_toward(10, 5, -1.5) # Returns 11.5 +``` + +
+ + + + + +[int](class_int.md) **nearest_po2**\ (\ value\: [int](class_int.md)\ ) [🔗](#class_@GlobalScope_method_nearest_po2) + +Returns the smallest integer power of 2 that is greater than or equal to `value`. + +``` + nearest_po2(3) # Returns 4 + nearest_po2(4) # Returns 4 + nearest_po2(5) # Returns 8 + + nearest_po2(0) # Returns 0 (this may not be expected) + nearest_po2(-1) # Returns 0 (this may not be expected) +``` + +\ **Warning:** Due to its implementation, this method returns ``0`` rather than ``1`` for values less than or equal to ``0``, with an exception for `value` being the smallest negative 64-bit integer (``-9223372036854775808``) in which case the `value` is returned unchanged. + +
+ + + + + +[float](class_float.md) **pingpong**\ (\ value\: [float](class_float.md), length\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_pingpong) + +Wraps `value` between ``0`` and the `length`. If the limit is reached, the next value the function returns is decreased to the ``0`` side or increased to the `length` side (like a triangle wave). If `length` is less than zero, it becomes positive. + +``` + pingpong(-3.0, 3.0) # Returns 3.0 + pingpong(-2.0, 3.0) # Returns 2.0 + pingpong(-1.0, 3.0) # Returns 1.0 + pingpong(0.0, 3.0) # Returns 0.0 + pingpong(1.0, 3.0) # Returns 1.0 + pingpong(2.0, 3.0) # Returns 2.0 + pingpong(3.0, 3.0) # Returns 3.0 + pingpong(4.0, 3.0) # Returns 2.0 + pingpong(5.0, 3.0) # Returns 1.0 + pingpong(6.0, 3.0) # Returns 0.0 +``` + +
+ + + + + +[int](class_int.md) **posmod**\ (\ x\: [int](class_int.md), y\: [int](class_int.md)\ ) [🔗](#class_@GlobalScope_method_posmod) + +Returns the integer modulus of `x` divided by `y` that wraps equally in positive and negative. + +``` + print("#(i) (i % 3) (posmod(i, 3))") + for i in range(-3, 4): + print("%2d %2d | %2d" % [i, i % 3, posmod(i, 3)]) +``` + +Prints: + +```text + (i) (i % 3) (posmod(i, 3)) + -3 0 | 0 + -2 -2 | 1 + -1 -1 | 2 + 0 0 | 0 + 1 1 | 1 + 2 2 | 2 + 3 0 | 0 +``` + +
+ + + + + +[float](class_float.md) **pow**\ (\ base\: [float](class_float.md), exp\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_pow) + +Returns the result of `base` raised to the power of `exp`. + +In GDScript, this is the equivalent of the ``**`` operator. + +``` + pow(2, 5) # Returns 32.0 + pow(4, 1.5) # Returns 8.0 +``` + +
+ + + + + +`void` **print**\ (\ ...\ ) vararg [🔗](#class_@GlobalScope_method_print) + +Converts one or more arguments of any type to string in the best way possible and prints them to the console. + + + + +```gdscript + var a = [1, 2, 3] + print("a", "b", a) # Prints "ab[1, 2, 3]" +``` + +```csharp + Godot.Collections.Array a = [1, 2, 3]; + GD.Print("a", "b", a); // Prints "ab[1, 2, 3]" +``` + + + +\ **Note:** Consider using [push_error()](class_@globalscope.md#class_@GlobalScope_method_push_error) and [push_warning()](class_@globalscope.md#class_@GlobalScope_method_push_warning) to print error and warning messages instead of [print()](class_@globalscope.md#class_@GlobalScope_method_print) or [print_rich()](class_@globalscope.md#class_@GlobalScope_method_print_rich). This distinguishes them from print messages used for debugging purposes, while also displaying a stack trace when an error or warning is printed. See also [Engine.print_to_stdout](class_engine.md#class_Engine_property_print_to_stdout) and [ProjectSettings.application/run/disable_stdout](class_projectsettings.md#class_ProjectSettings_property_application/run/disable_stdout). + +
+ + + + + +`void` **print_rich**\ (\ ...\ ) vararg [🔗](#class_@GlobalScope_method_print_rich) + +Converts one or more arguments of any type to string in the best way possible and prints them to the console. + +The following BBCode tags are supported: ``b``, ``i``, ``u``, ``s``, ``indent``, ``code``, ``url``, ``center``, ``right``, ``color``, ``bgcolor``, ``fgcolor``. + +URL tags only support URLs wrapped by a URL tag, not URLs with a different title. + +When printing to standard output, the supported subset of BBCode is converted to ANSI escape codes for the terminal emulator to display. Support for ANSI escape codes varies across terminal emulators, especially for italic and strikethrough. In standard output, ``code`` is represented with faint text but without any font change. Unsupported tags are left as-is in standard output. + + + + +```gdscript + print_rich("[color=green][b]Hello world![/b][/color]") # Prints "Hello world!", in green with a bold font. +``` + +```csharp + GD.PrintRich("[color=green][b]Hello world![/b][/color]"); // Prints "Hello world!", in green with a bold font. +``` + + + +\ **Note:** Consider using [push_error()](class_@globalscope.md#class_@GlobalScope_method_push_error) and [push_warning()](class_@globalscope.md#class_@GlobalScope_method_push_warning) to print error and warning messages instead of [print()](class_@globalscope.md#class_@GlobalScope_method_print) or [print_rich()](class_@globalscope.md#class_@GlobalScope_method_print_rich). This distinguishes them from print messages used for debugging purposes, while also displaying a stack trace when an error or warning is printed. + +\ **Note:** Output displayed in the editor supports clickable ``[url=address]text[/url]`` tags. The ``[url]`` tag's ``address`` value is handled by [OS.shell_open()](class_os.md#class_OS_method_shell_open) when clicked. + +
+ + + + + +`void` **print_verbose**\ (\ ...\ ) vararg [🔗](#class_@GlobalScope_method_print_verbose) + +If verbose mode is enabled ([OS.is_stdout_verbose()](class_os.md#class_OS_method_is_stdout_verbose) returning ``true``), converts one or more arguments of any type to string in the best way possible and prints them to the console. + +
+ + + + + +`void` **printerr**\ (\ ...\ ) vararg [🔗](#class_@GlobalScope_method_printerr) + +Prints one or more arguments to strings in the best way possible to standard error line. + + + + +```gdscript + printerr("prints to stderr") +``` + +```csharp + GD.PrintErr("prints to stderr"); +``` + + + +
+ + + + + +`void` **printraw**\ (\ ...\ ) vararg [🔗](#class_@GlobalScope_method_printraw) + +Prints one or more arguments to strings in the best way possible to the OS terminal. Unlike [print()](class_@globalscope.md#class_@GlobalScope_method_print), no newline is automatically added at the end. + +\ **Note:** The OS terminal is *not* the same as the editor's Output dock. The output sent to the OS terminal can be seen when running Redot from a terminal. On Windows, this requires using the ``console.exe`` executable. + + + + +```gdscript + # Prints "ABC" to terminal. + printraw("A") + printraw("B") + printraw("C") +``` + +```csharp + // Prints "ABC" to terminal. + GD.PrintRaw("A"); + GD.PrintRaw("B"); + GD.PrintRaw("C"); +``` + + + +
+ + + + + +`void` **prints**\ (\ ...\ ) vararg [🔗](#class_@GlobalScope_method_prints) + +Prints one or more arguments to the console with a space between each argument. + + + + +```gdscript + prints("A", "B", "C") # Prints "A B C" +``` + +```csharp + GD.PrintS("A", "B", "C"); // Prints "A B C" +``` + + + +
+ + + + + +`void` **printt**\ (\ ...\ ) vararg [🔗](#class_@GlobalScope_method_printt) + +Prints one or more arguments to the console with a tab between each argument. + + + + +```gdscript + printt("A", "B", "C") # Prints "A B C" +``` + +```csharp + GD.PrintT("A", "B", "C"); // Prints "A B C" +``` + + + +
+ + + + + +`void` **push_error**\ (\ ...\ ) vararg [🔗](#class_@GlobalScope_method_push_error) + +Pushes an error message to Redot's built-in debugger and to the OS terminal. + + + + +```gdscript + push_error("test error") # Prints "test error" to debugger and terminal as an error. +``` + +```csharp + GD.PushError("test error"); // Prints "test error" to debugger and terminal as an error. +``` + + + +\ **Note:** This function does not pause project execution. To print an error message and pause project execution in debug builds, use ``assert(false, "test error")`` instead. + +
+ + + + + +`void` **push_warning**\ (\ ...\ ) vararg [🔗](#class_@GlobalScope_method_push_warning) + +Pushes a warning message to Redot's built-in debugger and to the OS terminal. + + + + +```gdscript + push_warning("test warning") # Prints "test warning" to debugger and terminal as a warning. +``` + +```csharp + GD.PushWarning("test warning"); // Prints "test warning" to debugger and terminal as a warning. +``` + + + +
+ + + + + +[float](class_float.md) **rad_to_deg**\ (\ rad\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_rad_to_deg) + +Converts an angle expressed in radians to degrees. + +``` + rad_to_deg(0.523599) # Returns 30 + rad_to_deg(PI) # Returns 180 + rad_to_deg(PI * 2) # Returns 360 +``` + +
+ + + + + +[PackedInt64Array](class_packedint64array.md) **rand_from_seed**\ (\ seed\: [int](class_int.md)\ ) [🔗](#class_@GlobalScope_method_rand_from_seed) + +Given a `seed`, returns a [PackedInt64Array](class_packedint64array.md) of size ``2``, where its first element is the randomized [int](class_int.md) value, and the second element is the same as `seed`. Passing the same `seed` consistently returns the same array. + +\ **Note:** "Seed" here refers to the internal state of the pseudo random number generator, currently implemented as a 64 bit integer. + +``` + var a = rand_from_seed(4) + + print(a[0]) # Prints 2879024997 + print(a[1]) # Prints 4 +``` + +
+ + + + + +[float](class_float.md) **randf**\ (\ ) [🔗](#class_@GlobalScope_method_randf) + +Returns a random floating-point value between ``0.0`` and ``1.0`` (inclusive). + + + + +```gdscript + randf() # Returns e.g. 0.375671 +``` + +```csharp + GD.Randf(); // Returns e.g. 0.375671 +``` + + + +
+ + + + + +[float](class_float.md) **randf_range**\ (\ from\: [float](class_float.md), to\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_randf_range) + +Returns a random floating-point value between `from` and `to` (inclusive). + + + + +```gdscript + randf_range(0, 20.5) # Returns e.g. 7.45315 + randf_range(-10, 10) # Returns e.g. -3.844535 +``` + +```csharp + GD.RandRange(0.0, 20.5); // Returns e.g. 7.45315 + GD.RandRange(-10.0, 10.0); // Returns e.g. -3.844535 +``` + + + +
+ + + + + +[float](class_float.md) **randfn**\ (\ mean\: [float](class_float.md), deviation\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_randfn) + +Returns a [normally-distributed](https://en.wikipedia.org/wiki/Normal_distribution), pseudo-random floating-point value from the specified `mean` and a standard `deviation`. This is also known as a Gaussian distribution. + +\ **Note:** This method uses the [Box-Muller transform](https://en.wikipedia.org/wiki/Box%E2%80%93Muller_transform) algorithm. + +
+ + + + + +[int](class_int.md) **randi**\ (\ ) [🔗](#class_@GlobalScope_method_randi) + +Returns a random unsigned 32-bit integer. Use remainder to obtain a random value in the interval ``[0, N - 1]`` (where N is smaller than 2^32). + + + + +```gdscript + randi() # Returns random integer between 0 and 2^32 - 1 + randi() % 20 # Returns random integer between 0 and 19 + randi() % 100 # Returns random integer between 0 and 99 + randi() % 100 + 1 # Returns random integer between 1 and 100 +``` + +```csharp + GD.Randi(); // Returns random integer between 0 and 2^32 - 1 + GD.Randi() % 20; // Returns random integer between 0 and 19 + GD.Randi() % 100; // Returns random integer between 0 and 99 + GD.Randi() % 100 + 1; // Returns random integer between 1 and 100 +``` + + + +
+ + + + + +[int](class_int.md) **randi_range**\ (\ from\: [int](class_int.md), to\: [int](class_int.md)\ ) [🔗](#class_@GlobalScope_method_randi_range) + +Returns a random signed 32-bit integer between `from` and `to` (inclusive). If `to` is lesser than `from`, they are swapped. + + + + +```gdscript + randi_range(0, 1) # Returns either 0 or 1 + randi_range(-10, 1000) # Returns random integer between -10 and 1000 +``` + +```csharp + GD.RandRange(0, 1); // Returns either 0 or 1 + GD.RandRange(-10, 1000); // Returns random integer between -10 and 1000 +``` + + + +
+ + + + + +`void` **randomize**\ (\ ) [🔗](#class_@GlobalScope_method_randomize) + +Randomizes the seed (or the internal state) of the random number generator. The current implementation uses a number based on the device's time. + +\ **Note:** This function is called automatically when the project is run. If you need to fix the seed to have consistent, reproducible results, use [seed()](class_@globalscope.md#class_@GlobalScope_method_seed) to initialize the random number generator. + +
+ + + + + +[float](class_float.md) **remap**\ (\ value\: [float](class_float.md), istart\: [float](class_float.md), istop\: [float](class_float.md), ostart\: [float](class_float.md), ostop\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_remap) + +Maps a `value` from range ``[istart, istop]`` to ``[ostart, ostop]``. See also [lerp()](class_@globalscope.md#class_@GlobalScope_method_lerp) and [inverse_lerp()](class_@globalscope.md#class_@GlobalScope_method_inverse_lerp). If `value` is outside ``[istart, istop]``, then the resulting value will also be outside ``[ostart, ostop]``. If this is not desired, use [clamp()](class_@globalscope.md#class_@GlobalScope_method_clamp) on the result of this function. + +``` + remap(75, 0, 100, -1, 1) # Returns 0.5 +``` + +For complex use cases where multiple ranges are needed, consider using [Curve](class_curve.md) or [Gradient](class_gradient.md) instead. + +\ **Note:** If ``istart == istop``, the return value is undefined (most likely NaN, INF, or -INF). + +
+ + + + + +[int](class_int.md) **rid_allocate_id**\ (\ ) [🔗](#class_@GlobalScope_method_rid_allocate_id) + +Allocates a unique ID which can be used by the implementation to construct an RID. This is used mainly from native extensions to implement servers. + +
+ + + + + +[RID](class_rid.md) **rid_from_int64**\ (\ base\: [int](class_int.md)\ ) [🔗](#class_@GlobalScope_method_rid_from_int64) + +Creates an RID from a `base`. This is used mainly from native extensions to build servers. + +
+ + + + + +[float](class_float.md) **rotate_toward**\ (\ from\: [float](class_float.md), to\: [float](class_float.md), delta\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_rotate_toward) + +Rotates `from` toward `to` by the `delta` amount. Will not go past `to`. + +Similar to [move_toward()](class_@globalscope.md#class_@GlobalScope_method_move_toward), but interpolates correctly when the angles wrap around [@GDScript.TAU](class_@gdscript.md#class_@GDScript_constant_TAU). + +If `delta` is negative, this function will rotate away from `to`, toward the opposite angle, and will not go past the opposite angle. + +
+ + + + + +[Variant](class_variant.md) **round**\ (\ x\: [Variant](class_variant.md)\ ) [🔗](#class_@GlobalScope_method_round) + +Rounds `x` to the nearest whole number, with halfway cases rounded away from 0. Supported types: [int](class_int.md), [float](class_float.md), [Vector2](class_vector2.md), [Vector2i](class_vector2i.md), [Vector3](class_vector3.md), [Vector3i](class_vector3i.md), [Vector4](class_vector4.md), [Vector4i](class_vector4i.md). + +``` + round(2.4) # Returns 2 + round(2.5) # Returns 3 + round(2.6) # Returns 3 +``` + +See also [floor()](class_@globalscope.md#class_@GlobalScope_method_floor), [ceil()](class_@globalscope.md#class_@GlobalScope_method_ceil), and [snapped()](class_@globalscope.md#class_@GlobalScope_method_snapped). + +\ **Note:** For better type safety, use [roundf()](class_@globalscope.md#class_@GlobalScope_method_roundf), [roundi()](class_@globalscope.md#class_@GlobalScope_method_roundi), [Vector2.round()](class_vector2.md#class_Vector2_method_round), [Vector3.round()](class_vector3.md#class_Vector3_method_round), or [Vector4.round()](class_vector4.md#class_Vector4_method_round). + +
+ + + + + +[float](class_float.md) **roundf**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_roundf) + +Rounds `x` to the nearest whole number, with halfway cases rounded away from 0. + +A type-safe version of [round()](class_@globalscope.md#class_@GlobalScope_method_round), returning a [float](class_float.md). + +
+ + + + + +[int](class_int.md) **roundi**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_roundi) + +Rounds `x` to the nearest whole number, with halfway cases rounded away from 0. + +A type-safe version of [round()](class_@globalscope.md#class_@GlobalScope_method_round), returning an [int](class_int.md). + +
+ + + + + +`void` **seed**\ (\ base\: [int](class_int.md)\ ) [🔗](#class_@GlobalScope_method_seed) + +Sets the seed for the random number generator to `base`. Setting the seed manually can ensure consistent, repeatable results for most random functions. + + + + +```gdscript + var my_seed = "Redot Rocks".hash() + seed(my_seed) + var a = randf() + randi() + seed(my_seed) + var b = randf() + randi() + # a and b are now identical +``` + +```csharp + ulong mySeed = (ulong)GD.Hash("Redot Rocks"); + GD.Seed(mySeed); + var a = GD.Randf() + GD.Randi(); + GD.Seed(mySeed); + var b = GD.Randf() + GD.Randi(); + // a and b are now identical +``` + + + +
+ + + + + +[float](class_float.md) **sigmoid**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_sigmoid) + +Computes the sigmoid for `x`, which maps the input value into the range (0, 1). + +The sigmoid function is defined as: + +``` + sigmoid(x) = 1 / (1 + exp(-x)) +``` + +This is the most accurate implementation of the sigmoid. + +``` + var result = sigmoid(0.0) # result is 0.5 + var result = sigmoid(1.0) # result is approximately 0.7310 + var result = sigmoid(-1.0) # result is approximately 0.2689 + var result = sigmoid(5.0) # result is approximately 0.9933 +``` + +\ **Note:** For faster but less accurate approximation, see [sigmoid_approx()](class_@globalscope.md#class_@GlobalScope_method_sigmoid_approx). + +
+ + + + + +[float](class_float.md) **sigmoid_affine**\ (\ x\: [float](class_float.md), amplitude\: [float](class_float.md), y_translation\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_sigmoid_affine) + +Computes an affine-transformed sigmoid for `x`, which allows scaling by `amplitude` and translation by `y_translation`. + +The affine sigmoid function is defined as: + +``` + sigmoid_affine(x, amplitude, y_translation) = (amplitude / (1 + exp(-x))) + y_translation +``` + +This function modifies the standard sigmoid by introducing scaling and vertical translation. + +``` + var result = sigmoid_affine(0.0, 1.0, 0.0) # result is 0.5 + var result = sigmoid_affine(1.0, 2.0, -1.0) # result is approximately 0.4621 + var result = sigmoid_affine(-1.0, 3.0, 2.0) # result is approximately 2.8068 + var result = sigmoid_affine(1.0, 2.0, 2.5) # result is approximately 3.9621 +``` + +\ **Note:** This is a more accurate but computationally heavier version of the affine sigmoid. For faster approximations, see [sigmoid_affine_approx()](class_@globalscope.md#class_@GlobalScope_method_sigmoid_affine_approx). + +
+ + + + + +[float](class_float.md) **sigmoid_affine_approx**\ (\ x\: [float](class_float.md), amplitude\: [float](class_float.md), y_translation\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_sigmoid_affine_approx) + +Computes an approximation of the affine-transformed sigmoid function for `x`, allowing scaling by `amplitude` and translation by `y_translation`. + +The approximation function is defined as: + +``` + affine_sigmoid_approx(x, amplitude, y_translation) = amplitude * (0.5 + (x / (4 + abs(x)))) + y_translation +``` + +This function approximates the affine sigmoid, offering faster computation at the cost of some precision. It is useful in performance-sensitive environments where both transformation and speed are needed. + +``` + var result = sigmoid_affine_approx(0.0, 1.0, 0.0) # result is 0.5 + var result = sigmoid_affine_approx(2.0, 2.0, 1.0) # result is approximately 2.6667 + var result = sigmoid_affine_approx(-1.0, 3.0, 0.5) # result is 1.4 + var result = sigmoid_affine_approx(1.0, 2.0, 2.5) # result is 3.9 +``` + +
+ + + + + +[float](class_float.md) **sigmoid_approx**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_sigmoid_approx) + +Computes an approximation of the sigmoid function for `x`, which maps the input value into the range (0, 1). + +The approximation function is defined as: + +``` + sigmoid_approx(x) = 0.5 + (x / (4 + abs(x))) +``` + +This function is faster than the standard [sigmoid()](class_@globalscope.md#class_@GlobalScope_method_sigmoid), especially useful in performance-sensitive environments where a balance between accuracy and speed is desired. + +``` + var result = sigmoid_approx(0.0) # result is 0.5 + var result = sigmoid_approx(2.0) # result is approximately 0.8333 + var result = sigmoid_approx(-1.0) # result is 0.3 + var result = sigmoid_approx(5.0) # result is approximately 1.0555 +``` + +
+ + + + + +[Variant](class_variant.md) **sign**\ (\ x\: [Variant](class_variant.md)\ ) [🔗](#class_@GlobalScope_method_sign) + +Returns the same type of [Variant](class_variant.md) as `x`, with ``-1`` for negative values, ``1`` for positive values, and ``0`` for zeros. For ``nan`` values it returns 0. + +Supported types: [int](class_int.md), [float](class_float.md), [Vector2](class_vector2.md), [Vector2i](class_vector2i.md), [Vector3](class_vector3.md), [Vector3i](class_vector3i.md), [Vector4](class_vector4.md), [Vector4i](class_vector4i.md). + +``` + sign(-6.0) # Returns -1 + sign(0.0) # Returns 0 + sign(6.0) # Returns 1 + sign(NAN) # Returns 0 + + sign(Vector3(-6.0, 0.0, 6.0)) # Returns (-1, 0, 1) +``` + +\ **Note:** For better type safety, use [signf()](class_@globalscope.md#class_@GlobalScope_method_signf), [signi()](class_@globalscope.md#class_@GlobalScope_method_signi), [Vector2.sign()](class_vector2.md#class_Vector2_method_sign), [Vector2i.sign()](class_vector2i.md#class_Vector2i_method_sign), [Vector3.sign()](class_vector3.md#class_Vector3_method_sign), [Vector3i.sign()](class_vector3i.md#class_Vector3i_method_sign), [Vector4.sign()](class_vector4.md#class_Vector4_method_sign), or [Vector4i.sign()](class_vector4i.md#class_Vector4i_method_sign). + +
+ + + + + +[float](class_float.md) **signf**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_signf) + +Returns ``-1.0`` if `x` is negative, ``1.0`` if `x` is positive, and ``0.0`` if `x` is zero. For ``nan`` values of `x` it returns 0.0. + +``` + signf(-6.5) # Returns -1.0 + signf(0.0) # Returns 0.0 + signf(6.5) # Returns 1.0 + signf(NAN) # Returns 0.0 +``` + +
+ + + + + +[int](class_int.md) **signi**\ (\ x\: [int](class_int.md)\ ) [🔗](#class_@GlobalScope_method_signi) + +Returns ``-1`` if `x` is negative, ``1`` if `x` is positive, and ``0`` if `x` is zero. + +``` + signi(-6) # Returns -1 + signi(0) # Returns 0 + signi(6) # Returns 1 +``` + +
+ + + + + +[float](class_float.md) **sin**\ (\ angle_rad\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_sin) + +Returns the sine of angle `angle_rad` in radians. + +``` + sin(0.523599) # Returns 0.5 + sin(deg_to_rad(90)) # Returns 1.0 +``` + +
+ + + + + +[float](class_float.md) **sinh**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_sinh) + +Returns the hyperbolic sine of `x`. + +``` + var a = log(2.0) # Returns 0.693147 + sinh(a) # Returns 0.75 +``` + +
+ + + + + +[float](class_float.md) **smoothstep**\ (\ from\: [float](class_float.md), to\: [float](class_float.md), x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_smoothstep) + +Returns a smooth cubic Hermite interpolation between ``0`` and ``1``. + +For positive ranges (when ``from <= to``) the return value is ``0`` when ``x <= from``, and ``1`` when ``x >= to``. If `x` lies between `from` and `to`, the return value follows an S-shaped curve that smoothly transitions from ``0`` to ``1``. + +For negative ranges (when ``from > to``) the function is mirrored and returns ``1`` when ``x <= to`` and ``0`` when ``x >= from``. + +This S-shaped curve is the cubic Hermite interpolator, given by ``f(y) = 3*y^2 - 2*y^3`` where ``y = (x-from) / (to-from)``. + +``` + smoothstep(0, 2, -5.0) # Returns 0.0 + smoothstep(0, 2, 0.5) # Returns 0.15625 + smoothstep(0, 2, 1.0) # Returns 0.5 + smoothstep(0, 2, 2.0) # Returns 1.0 +``` + +Compared to [ease()](class_@globalscope.md#class_@GlobalScope_method_ease) with a curve value of ``-1.6521``, [smoothstep()](class_@globalscope.md#class_@GlobalScope_method_smoothstep) returns the smoothest possible curve with no sudden changes in the derivative. If you need to perform more advanced transitions, use [Tween](class_tween.md) or [AnimationPlayer](class_animationplayer.md). + +\ [Comparison between smoothstep() and ease(x, -1.6521) return values](https://raw.githubusercontent.com/redot-engine/redot-docs/master/img/smoothstep_ease_comparison.png)\ + +\ [Smoothstep() return values with positive, zero, and negative ranges](https://raw.githubusercontent.com/redot-engine/redot-docs/master/img/smoothstep_range.webp) + +
+ + + + + +[Variant](class_variant.md) **snapped**\ (\ x\: [Variant](class_variant.md), step\: [Variant](class_variant.md)\ ) [🔗](#class_@GlobalScope_method_snapped) + +Returns the multiple of `step` that is the closest to `x`. This can also be used to round a floating-point number to an arbitrary number of decimals. + +The returned value is the same type of [Variant](class_variant.md) as `step`. Supported types: [int](class_int.md), [float](class_float.md), [Vector2](class_vector2.md), [Vector2i](class_vector2i.md), [Vector3](class_vector3.md), [Vector3i](class_vector3i.md), [Vector4](class_vector4.md), [Vector4i](class_vector4i.md). + +``` + snapped(100, 32) # Returns 96 + snapped(3.14159, 0.01) # Returns 3.14 + + snapped(Vector2(34, 70), Vector2(8, 8)) # Returns (32, 72) +``` + +See also [ceil()](class_@globalscope.md#class_@GlobalScope_method_ceil), [floor()](class_@globalscope.md#class_@GlobalScope_method_floor), and [round()](class_@globalscope.md#class_@GlobalScope_method_round). + +\ **Note:** For better type safety, use [snappedf()](class_@globalscope.md#class_@GlobalScope_method_snappedf), [snappedi()](class_@globalscope.md#class_@GlobalScope_method_snappedi), [Vector2.snapped()](class_vector2.md#class_Vector2_method_snapped), [Vector2i.snapped()](class_vector2i.md#class_Vector2i_method_snapped), [Vector3.snapped()](class_vector3.md#class_Vector3_method_snapped), [Vector3i.snapped()](class_vector3i.md#class_Vector3i_method_snapped), [Vector4.snapped()](class_vector4.md#class_Vector4_method_snapped), or [Vector4i.snapped()](class_vector4i.md#class_Vector4i_method_snapped). + +
+ + + + + +[float](class_float.md) **snappedf**\ (\ x\: [float](class_float.md), step\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_snappedf) + +Returns the multiple of `step` that is the closest to `x`. This can also be used to round a floating-point number to an arbitrary number of decimals. + +A type-safe version of [snapped()](class_@globalscope.md#class_@GlobalScope_method_snapped), returning a [float](class_float.md). + +``` + snappedf(32.0, 2.5) # Returns 32.5 + snappedf(3.14159, 0.01) # Returns 3.14 +``` + +
+ + + + + +[int](class_int.md) **snappedi**\ (\ x\: [float](class_float.md), step\: [int](class_int.md)\ ) [🔗](#class_@GlobalScope_method_snappedi) + +Returns the multiple of `step` that is the closest to `x`. + +A type-safe version of [snapped()](class_@globalscope.md#class_@GlobalScope_method_snapped), returning an [int](class_int.md). + +``` + snappedi(53, 16) # Returns 48 + snappedi(4096, 100) # Returns 4100 +``` + +
+ + + + + +[float](class_float.md) **sqrt**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_sqrt) + +Returns the square root of `x`, where `x` is a non-negative number. + +``` + sqrt(9) # Returns 3 + sqrt(10.24) # Returns 3.2 + sqrt(-1) # Returns NaN +``` + +\ **Note:** Negative values of `x` return NaN ("Not a Number"). In C#, if you need negative inputs, use ``System.Numerics.Complex``. + +
+ + + + + +[int](class_int.md) **step_decimals**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_step_decimals) + +Returns the position of the first non-zero digit, after the decimal point. Note that the maximum return value is 10, which is a design decision in the implementation. + +``` + var n = step_decimals(5) # n is 0 + n = step_decimals(1.0005) # n is 4 + n = step_decimals(0.000000005) # n is 9 +``` + +
+ + + + + +[String](class_string.md) **str**\ (\ ...\ ) vararg [🔗](#class_@GlobalScope_method_str) + +Converts one or more arguments of any [Variant](class_variant.md) type to a [String](class_string.md) in the best way possible. + +``` + var a = [10, 20, 30] + var b = str(a) + print(len(a)) # Prints 3 (the number of elements in the array). + print(len(b)) # Prints 12 (the length of the string "[10, 20, 30]"). +``` + +
+ + + + + +[Variant](class_variant.md) **str_to_var**\ (\ string\: [String](class_string.md)\ ) [🔗](#class_@GlobalScope_method_str_to_var) + +Converts a formatted `string` that was returned by [var_to_str()](class_@globalscope.md#class_@GlobalScope_method_var_to_str) to the equivalent [Variant](class_variant.md), without decoding objects. + +\ **Note:** If you need object deserialization, see [str_to_var_with_objects()](class_@globalscope.md#class_@GlobalScope_method_str_to_var_with_objects). + + + + +```gdscript + var data = '{ "a": 1, "b": 2 }' # data is a String + var dict = str_to_var(data) # dict is a Dictionary + print(dict["a"]) # Prints 1 +``` + +```csharp + string data = "{ \"a\": 1, \"b\": 2 }"; // data is a string + var dict = GD.StrToVar(data).AsGodotDictionary(); // dict is a Dictionary + GD.Print(dict["a"]); // Prints 1 +``` + + + +
+ + + + + +[Variant](class_variant.md) **str_to_var_with_objects**\ (\ string\: [String](class_string.md)\ ) [🔗](#class_@GlobalScope_method_str_to_var_with_objects) + +Converts a formatted `string` that was returned by [var_to_str_with_objects()](class_@globalscope.md#class_@GlobalScope_method_var_to_str_with_objects) to the equivalent [Variant](class_variant.md). Decoding objects is allowed. + +\ **Warning:** Deserialized object can contain code which gets executed. Do not use this option if the serialized object comes from untrusted sources to avoid potential security threats (remote code execution). + +
+ + + + + +[float](class_float.md) **tan**\ (\ angle_rad\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_tan) + +Returns the tangent of angle `angle_rad` in radians. + +``` + tan(deg_to_rad(45)) # Returns 1 +``` + +
+ + + + + +[float](class_float.md) **tanh**\ (\ x\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_tanh) + +Returns the hyperbolic tangent of `x`. + +``` + var a = log(2.0) # Returns 0.693147 + tanh(a) # Returns 0.6 +``` + +
+ + + + + +[Variant](class_variant.md) **type_convert**\ (\ variant\: [Variant](class_variant.md), type\: [int](class_int.md)\ ) [🔗](#class_@GlobalScope_method_type_convert) + +Converts the given `variant` to the given `type`, using the [Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) values. This method is generous with how it handles types, it can automatically convert between array types, convert numeric [String](class_string.md)\ s to [int](class_int.md), and converting most things to [String](class_string.md). + +If the type conversion cannot be done, this method will return the default value for that type, for example converting [Rect2](class_rect2.md) to [Vector2](class_vector2.md) will always return [Vector2.ZERO](class_vector2.md#class_Vector2_constant_ZERO). This method will never show error messages as long as `type` is a valid Variant type. + +The returned value is a [Variant](class_variant.md), but the data inside and its type will be the same as the requested type. + +``` + type_convert("Hi!", TYPE_INT) # Returns 0 + type_convert("123", TYPE_INT) # Returns 123 + type_convert(123.4, TYPE_INT) # Returns 123 + type_convert(5, TYPE_VECTOR2) # Returns (0, 0) + type_convert("Hi!", TYPE_NIL) # Returns null +``` + +
+ + + + + +[String](class_string.md) **type_string**\ (\ type\: [int](class_int.md)\ ) [🔗](#class_@GlobalScope_method_type_string) + +Returns a human-readable name of the given `type`, using the [Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) values. + +``` + print(TYPE_INT) # Prints 2 + print(type_string(TYPE_INT)) # Prints "int" + print(type_string(TYPE_STRING)) # Prints "String" +``` + +See also [typeof()](class_@globalscope.md#class_@GlobalScope_method_typeof). + +
+ + + + + +[int](class_int.md) **typeof**\ (\ variable\: [Variant](class_variant.md)\ ) [🔗](#class_@GlobalScope_method_typeof) + +Returns the internal type of the given `variable`, using the [Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) values. + +``` + var json = JSON.new() + json.parse('["a", "b", "c"]') + var result = json.get_data() + if result is Array: + print(result[0]) # Prints "a" + else: + print("Unexpected result!") +``` + +See also [type_string()](class_@globalscope.md#class_@GlobalScope_method_type_string). + +
+ + + + + +[PackedByteArray](class_packedbytearray.md) **var_to_bytes**\ (\ variable\: [Variant](class_variant.md)\ ) [🔗](#class_@GlobalScope_method_var_to_bytes) + +Encodes a [Variant](class_variant.md) value to a byte array, without encoding objects. Deserialization can be done with [bytes_to_var()](class_@globalscope.md#class_@GlobalScope_method_bytes_to_var). + +\ **Note:** If you need object serialization, see [var_to_bytes_with_objects()](class_@globalscope.md#class_@GlobalScope_method_var_to_bytes_with_objects). + +\ **Note:** Encoding [Callable](class_callable.md) is not supported and will result in an empty value, regardless of the data. + +
+ + + + + +[PackedByteArray](class_packedbytearray.md) **var_to_bytes_with_objects**\ (\ variable\: [Variant](class_variant.md)\ ) [🔗](#class_@GlobalScope_method_var_to_bytes_with_objects) + +Encodes a [Variant](class_variant.md) value to a byte array. Encoding objects is allowed (and can potentially include executable code). Deserialization can be done with [bytes_to_var_with_objects()](class_@globalscope.md#class_@GlobalScope_method_bytes_to_var_with_objects). + +\ **Note:** Encoding [Callable](class_callable.md) is not supported and will result in an empty value, regardless of the data. + +
+ + + + + +[String](class_string.md) **var_to_str**\ (\ variable\: [Variant](class_variant.md)\ ) [🔗](#class_@GlobalScope_method_var_to_str) + +Converts a [Variant](class_variant.md) `variable` to a formatted [String](class_string.md) that can then be parsed using [str_to_var()](class_@globalscope.md#class_@GlobalScope_method_str_to_var), without encoding objects. + +\ **Note:** If you need object serialization, see [var_to_str_with_objects()](class_@globalscope.md#class_@GlobalScope_method_var_to_str_with_objects). + + + + +```gdscript + var a = { "a": 1, "b": 2 } + print(var_to_str(a)) +``` + +```csharp + var a = new Godot.Collections.Dictionary { ["a"] = 1, ["b"] = 2 }; + GD.Print(GD.VarToStr(a)); +``` + + + +Prints: + +```text + { + "a": 1, + "b": 2 + } +``` + +\ **Note:** Converting [Signal](class_signal.md) or [Callable](class_callable.md) is not supported and will result in an empty value for these types, regardless of their data. + +
+ + + + + +[String](class_string.md) **var_to_str_with_objects**\ (\ variable\: [Variant](class_variant.md)\ ) [🔗](#class_@GlobalScope_method_var_to_str_with_objects) + +Converts a [Variant](class_variant.md) `variable` to a formatted [String](class_string.md) that can then be parsed using [str_to_var_with_objects()](class_@globalscope.md#class_@GlobalScope_method_str_to_var_with_objects). Encoding objects is allowed (and can potentially include executable code). + +
+ + + + + +[Variant](class_variant.md) **weakref**\ (\ obj\: [Variant](class_variant.md)\ ) [🔗](#class_@GlobalScope_method_weakref) + +Returns a [WeakRef](class_weakref.md) instance holding a weak reference to `obj`. Returns an empty [WeakRef](class_weakref.md) instance if `obj` is ``null``. Prints an error and returns ``null`` if `obj` is neither [Object](class_object.md)-derived nor ``null``. + +A weak reference to an object is not enough to keep the object alive: when the only remaining references to a referent are weak references, garbage collection is free to destroy the referent and reuse its memory for something else. However, until the object is actually destroyed the weak reference may return the object even if there are no strong references to it. + +
+ + + + + +[Variant](class_variant.md) **wrap**\ (\ value\: [Variant](class_variant.md), min\: [Variant](class_variant.md), max\: [Variant](class_variant.md)\ ) [🔗](#class_@GlobalScope_method_wrap) + +Wraps the [Variant](class_variant.md) `value` between `min` and `max`. `min` is *inclusive* while `max` is *exclusive*. This can be used for creating loop-like behavior or infinite surfaces. + +Variant types [int](class_int.md) and [float](class_float.md) are supported. If any of the arguments is [float](class_float.md), this function returns a [float](class_float.md), otherwise it returns an [int](class_int.md). + +``` + var a = wrap(4, 5, 10) + # a is 9 (int) + + var a = wrap(7, 5, 10) + # a is 7 (int) + + var a = wrap(10.5, 5, 10) + # a is 5.5 (float) +``` + +
+ + + + + +[float](class_float.md) **wrapf**\ (\ value\: [float](class_float.md), min\: [float](class_float.md), max\: [float](class_float.md)\ ) [🔗](#class_@GlobalScope_method_wrapf) + +Wraps the float `value` between `min` and `max`. `min` is *inclusive* while `max` is *exclusive*. This can be used for creating loop-like behavior or infinite surfaces. + +``` + # Infinite loop between 5.0 and 9.9 + value = wrapf(value + 0.1, 5.0, 10.0) +``` + +``` + # Infinite rotation (in radians) + angle = wrapf(angle + 0.1, 0.0, TAU) +``` + +``` + # Infinite rotation (in radians) + angle = wrapf(angle + 0.1, -PI, PI) +``` + +\ **Note:** If `min` is ``0``, this is equivalent to [fposmod()](class_@globalscope.md#class_@GlobalScope_method_fposmod), so prefer using that instead. [wrapf()](class_@globalscope.md#class_@GlobalScope_method_wrapf) is more flexible than using the [fposmod()](class_@globalscope.md#class_@GlobalScope_method_fposmod) approach by giving the user control over the minimum value. + +
+ + + + + +[int](class_int.md) **wrapi**\ (\ value\: [int](class_int.md), min\: [int](class_int.md), max\: [int](class_int.md)\ ) [🔗](#class_@GlobalScope_method_wrapi) + +Wraps the integer `value` between `min` and `max`. `min` is *inclusive* while `max` is *exclusive*. This can be used for creating loop-like behavior or infinite surfaces. + +``` + # Infinite loop between 5 and 9 + frame = wrapi(frame + 1, 5, 10) +``` + +``` + # result is -2 + var result = wrapi(-6, -5, -1) +``` + diff --git a/docs/Classes/class_aabb.md b/docs/Classes/class_aabb.md new file mode 100644 index 00000000..71ff7af7 --- /dev/null +++ b/docs/Classes/class_aabb.md @@ -0,0 +1,770 @@ + + + + + + + + + +# AABB + +A 3D axis-aligned bounding box. + + + +## Description + +The **AABB** built-in [Variant](class_variant.md) type represents an axis-aligned bounding box in a 3D space. It is defined by its [position](class_aabb.md#class_AABB_property_position) and [size](class_aabb.md#class_AABB_property_size), which are [Vector3](class_vector3.md). It is frequently used for fast overlap tests (see [intersects()](class_aabb.md#class_AABB_method_intersects)). Although **AABB** itself is axis-aligned, it can be combined with [Transform3D](class_transform3d.md) to represent a rotated or skewed bounding box. + +It uses floating-point coordinates. The 2D counterpart to **AABB** is [Rect2](class_rect2.md). There is no version of **AABB** that uses integer coordinates. + +\ **Note:** Negative values for [size](class_aabb.md#class_AABB_property_size) are not supported. With negative size, most **AABB** methods do not work correctly. Use [abs()](class_aabb.md#class_AABB_method_abs) to get an equivalent **AABB** with a non-negative size. + +\ **Note:** In a boolean context, an **AABB** evaluates to ``false`` if both [position](class_aabb.md#class_AABB_property_position) and [size](class_aabb.md#class_AABB_property_size) are zero (equal to [Vector3.ZERO](class_vector3.md#class_Vector3_constant_ZERO)). Otherwise, it always evaluates to ``true``. + +
+There are notable differences when using this API with C#. See the C# differences documentation for more information. + +
+ + + +## Tutorials + +- [Math documentation index](../tutorials/math/index.md) + +- [Vector math](../tutorials/math/vector_math.md) + +- [Advanced vector math](../tutorials/math/vectors_advanced.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + +
[Vector3](class_vector3.md)[end](#class_AABB_property_end)`Vector3(0, 0, 0)`
[Vector3](class_vector3.md)[position](#class_AABB_property_position)`Vector3(0, 0, 0)`
[Vector3](class_vector3.md)[size](#class_AABB_property_size)`Vector3(0, 0, 0)`
+ + + +## Constructors + + + + + + + + + + + + + + + + + + +
[AABB](class_aabb.md)[AABB](#class_AABB_constructor_AABB)\ (\ )
[AABB](class_aabb.md)[AABB](#class_AABB_constructor_AABB)\ (\ from\: [AABB](class_aabb.md)\ )
[AABB](class_aabb.md)[AABB](#class_AABB_constructor_AABB)\ (\ position\: [Vector3](class_vector3.md), size\: [Vector3](class_vector3.md)\ )
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[AABB](class_aabb.md)[abs](#class_AABB_method_abs)\ (\ ) const
[bool](class_bool.md)[encloses](#class_AABB_method_encloses)\ (\ with\: [AABB](class_aabb.md)\ ) const
[AABB](class_aabb.md)[expand](#class_AABB_method_expand)\ (\ to_point\: [Vector3](class_vector3.md)\ ) const
[Vector3](class_vector3.md)[get_center](#class_AABB_method_get_center)\ (\ ) const
[Vector3](class_vector3.md)[get_endpoint](#class_AABB_method_get_endpoint)\ (\ idx\: [int](class_int.md)\ ) const
[Vector3](class_vector3.md)[get_longest_axis](#class_AABB_method_get_longest_axis)\ (\ ) const
[int](class_int.md)[get_longest_axis_index](#class_AABB_method_get_longest_axis_index)\ (\ ) const
[float](class_float.md)[get_longest_axis_size](#class_AABB_method_get_longest_axis_size)\ (\ ) const
[Vector3](class_vector3.md)[get_shortest_axis](#class_AABB_method_get_shortest_axis)\ (\ ) const
[int](class_int.md)[get_shortest_axis_index](#class_AABB_method_get_shortest_axis_index)\ (\ ) const
[float](class_float.md)[get_shortest_axis_size](#class_AABB_method_get_shortest_axis_size)\ (\ ) const
[Vector3](class_vector3.md)[get_support](#class_AABB_method_get_support)\ (\ direction\: [Vector3](class_vector3.md)\ ) const
[float](class_float.md)[get_volume](#class_AABB_method_get_volume)\ (\ ) const
[AABB](class_aabb.md)[grow](#class_AABB_method_grow)\ (\ by\: [float](class_float.md)\ ) const
[bool](class_bool.md)[has_point](#class_AABB_method_has_point)\ (\ point\: [Vector3](class_vector3.md)\ ) const
[bool](class_bool.md)[has_surface](#class_AABB_method_has_surface)\ (\ ) const
[bool](class_bool.md)[has_volume](#class_AABB_method_has_volume)\ (\ ) const
[AABB](class_aabb.md)[intersection](#class_AABB_method_intersection)\ (\ with\: [AABB](class_aabb.md)\ ) const
[bool](class_bool.md)[intersects](#class_AABB_method_intersects)\ (\ with\: [AABB](class_aabb.md)\ ) const
[bool](class_bool.md)[intersects_plane](#class_AABB_method_intersects_plane)\ (\ plane\: [Plane](class_plane.md)\ ) const
[Variant](class_variant.md)[intersects_ray](#class_AABB_method_intersects_ray)\ (\ from\: [Vector3](class_vector3.md), dir\: [Vector3](class_vector3.md)\ ) const
[Variant](class_variant.md)[intersects_segment](#class_AABB_method_intersects_segment)\ (\ from\: [Vector3](class_vector3.md), to\: [Vector3](class_vector3.md)\ ) const
[bool](class_bool.md)[is_equal_approx](#class_AABB_method_is_equal_approx)\ (\ aabb\: [AABB](class_aabb.md)\ ) const
[bool](class_bool.md)[is_finite](#class_AABB_method_is_finite)\ (\ ) const
[AABB](class_aabb.md)[merge](#class_AABB_method_merge)\ (\ with\: [AABB](class_aabb.md)\ ) const
+ + + +## Operators + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[operator !=](#class_AABB_operator_neq_AABB)\ (\ right\: [AABB](class_aabb.md)\ )
[AABB](class_aabb.md)[operator *](#class_AABB_operator_mul_Transform3D)\ (\ right\: [Transform3D](class_transform3d.md)\ )
[bool](class_bool.md)[operator ==](#class_AABB_operator_eq_AABB)\ (\ right\: [AABB](class_aabb.md)\ )
+ +
+ + + +## Property Descriptions + + + + + +[Vector3](class_vector3.md) **end** = `Vector3(0, 0, 0)` [🔗](#class_AABB_property_end) + +The ending point. This is usually the corner on the top-right and back of the bounding box, and is equivalent to ``position + size``. Setting this point affects the [size](class_aabb.md#class_AABB_property_size). + +
+ + + + + +[Vector3](class_vector3.md) **position** = `Vector3(0, 0, 0)` [🔗](#class_AABB_property_position) + +The origin point. This is usually the corner on the bottom-left and forward of the bounding box. + +
+ + + + + +[Vector3](class_vector3.md) **size** = `Vector3(0, 0, 0)` [🔗](#class_AABB_property_size) + +The bounding box's width, height, and depth starting from [position](class_aabb.md#class_AABB_property_position). Setting this value also affects the [end](class_aabb.md#class_AABB_property_end) point. + +\ **Note:** It's recommended setting the width, height, and depth to non-negative values. This is because most methods in Redot assume that the [position](class_aabb.md#class_AABB_property_position) is the bottom-left-forward corner, and the [end](class_aabb.md#class_AABB_property_end) is the top-right-back corner. To get an equivalent bounding box with non-negative size, use [abs()](class_aabb.md#class_AABB_method_abs). + +
+ + + +## Constructor Descriptions + + + + + +[AABB](class_aabb.md) **AABB**\ (\ ) [🔗](#class_AABB_constructor_AABB) + +Constructs an **AABB** with its [position](class_aabb.md#class_AABB_property_position) and [size](class_aabb.md#class_AABB_property_size) set to [Vector3.ZERO](class_vector3.md#class_Vector3_constant_ZERO). + +
+ + + +[AABB](class_aabb.md) **AABB**\ (\ from\: [AABB](class_aabb.md)\ ) + +Constructs an **AABB** as a copy of the given **AABB**. + +
+ + + +[AABB](class_aabb.md) **AABB**\ (\ position\: [Vector3](class_vector3.md), size\: [Vector3](class_vector3.md)\ ) + +Constructs an **AABB** by `position` and `size`. + +
+ + + +## Method Descriptions + + + + + +[AABB](class_aabb.md) **abs**\ (\ ) const [🔗](#class_AABB_method_abs) + +Returns an **AABB** equivalent to this bounding box, with its width, height, and depth modified to be non-negative values. + + + + +```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) +``` + +```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) +``` + + + +\ **Note:** It's recommended to use this method when [size](class_aabb.md#class_AABB_property_size) is negative, as most other methods in Redot assume that the [size](class_aabb.md#class_AABB_property_size)'s components are greater than ``0``. + +
+ + + + + +[bool](class_bool.md) **encloses**\ (\ with\: [AABB](class_aabb.md)\ ) const [🔗](#class_AABB_method_encloses) + +Returns ``true`` if this bounding box *completely* encloses the `with` box. The edges of both boxes are included. + + + + +```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 +``` + +```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 +``` + + + +
+ + + + + +[AABB](class_aabb.md) **expand**\ (\ to_point\: [Vector3](class_vector3.md)\ ) const [🔗](#class_AABB_method_expand) + +Returns a copy of this bounding box expanded to align the edges with the given `to_point`, if necessary. + + + + +```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) +``` + +```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) +``` + + + +
+ + + + + +[Vector3](class_vector3.md) **get_center**\ (\ ) const [🔗](#class_AABB_method_get_center) + +Returns the center point of the bounding box. This is the same as ``position + (size / 2.0)``. + +
+ + + + + +[Vector3](class_vector3.md) **get_endpoint**\ (\ idx\: [int](class_int.md)\ ) const [🔗](#class_AABB_method_get_endpoint) + +Returns the position of one of the 8 vertices that compose this bounding box. With an `idx` of ``0`` this is the same as [position](class_aabb.md#class_AABB_property_position), and an `idx` of ``7`` is the same as [end](class_aabb.md#class_AABB_property_end). + +
+ + + + + +[Vector3](class_vector3.md) **get_longest_axis**\ (\ ) const [🔗](#class_AABB_method_get_longest_axis) + +Returns the longest normalized axis of this bounding box's [size](class_aabb.md#class_AABB_property_size), as a [Vector3](class_vector3.md) ([Vector3.RIGHT](class_vector3.md#class_Vector3_constant_RIGHT), [Vector3.UP](class_vector3.md#class_Vector3_constant_UP), or [Vector3.BACK](class_vector3.md#class_Vector3_constant_BACK)). + + + + +```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 +``` + +```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 +``` + + + +See also [get_longest_axis_index()](class_aabb.md#class_AABB_method_get_longest_axis_index) and [get_longest_axis_size()](class_aabb.md#class_AABB_method_get_longest_axis_size). + +
+ + + + + +[int](class_int.md) **get_longest_axis_index**\ (\ ) const [🔗](#class_AABB_method_get_longest_axis_index) + +Returns the index to the longest axis of this bounding box's [size](class_aabb.md#class_AABB_property_size) (see [Vector3.AXIS_X](class_vector3.md#class_Vector3_constant_AXIS_X), [Vector3.AXIS_Y](class_vector3.md#class_Vector3_constant_AXIS_Y), and [Vector3.AXIS_Z](class_vector3.md#class_Vector3_constant_AXIS_Z)). + +For an example, see [get_longest_axis()](class_aabb.md#class_AABB_method_get_longest_axis). + +
+ + + + + +[float](class_float.md) **get_longest_axis_size**\ (\ ) const [🔗](#class_AABB_method_get_longest_axis_size) + +Returns the longest dimension of this bounding box's [size](class_aabb.md#class_AABB_property_size). + +For an example, see [get_longest_axis()](class_aabb.md#class_AABB_method_get_longest_axis). + +
+ + + + + +[Vector3](class_vector3.md) **get_shortest_axis**\ (\ ) const [🔗](#class_AABB_method_get_shortest_axis) + +Returns the shortest normalized axis of this bounding box's [size](class_aabb.md#class_AABB_property_size), as a [Vector3](class_vector3.md) ([Vector3.RIGHT](class_vector3.md#class_Vector3_constant_RIGHT), [Vector3.UP](class_vector3.md#class_Vector3_constant_UP), or [Vector3.BACK](class_vector3.md#class_Vector3_constant_BACK)). + + + + +```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 +``` + +```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 +``` + + + +See also [get_shortest_axis_index()](class_aabb.md#class_AABB_method_get_shortest_axis_index) and [get_shortest_axis_size()](class_aabb.md#class_AABB_method_get_shortest_axis_size). + +
+ + + + + +[int](class_int.md) **get_shortest_axis_index**\ (\ ) const [🔗](#class_AABB_method_get_shortest_axis_index) + +Returns the index to the shortest axis of this bounding box's [size](class_aabb.md#class_AABB_property_size) (see [Vector3.AXIS_X](class_vector3.md#class_Vector3_constant_AXIS_X), [Vector3.AXIS_Y](class_vector3.md#class_Vector3_constant_AXIS_Y), and [Vector3.AXIS_Z](class_vector3.md#class_Vector3_constant_AXIS_Z)). + +For an example, see [get_shortest_axis()](class_aabb.md#class_AABB_method_get_shortest_axis). + +
+ + + + + +[float](class_float.md) **get_shortest_axis_size**\ (\ ) const [🔗](#class_AABB_method_get_shortest_axis_size) + +Returns the shortest dimension of this bounding box's [size](class_aabb.md#class_AABB_property_size). + +For an example, see [get_shortest_axis()](class_aabb.md#class_AABB_method_get_shortest_axis). + +
+ + + + + +[Vector3](class_vector3.md) **get_support**\ (\ direction\: [Vector3](class_vector3.md)\ ) const [🔗](#class_AABB_method_get_support) + +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. + +
+ + + + + +[float](class_float.md) **get_volume**\ (\ ) const [🔗](#class_AABB_method_get_volume) + +Returns the bounding box's volume. This is equivalent to ``size.x * size.y * size.z``. See also [has_volume()](class_aabb.md#class_AABB_method_has_volume). + +
+ + + + + +[AABB](class_aabb.md) **grow**\ (\ by\: [float](class_float.md)\ ) const [🔗](#class_AABB_method_grow) + +Returns a copy of this bounding box extended on all sides by the given amount `by`. A negative amount shrinks the box instead. + + + + +```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) +``` + +```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) +``` + + + +
+ + + + + +[bool](class_bool.md) **has_point**\ (\ point\: [Vector3](class_vector3.md)\ ) const [🔗](#class_AABB_method_has_point) + +Returns ``true`` if the bounding box contains the given `point`. By convention, points exactly on the right, top, and front sides are **not** included. + +\ **Note:** This method is not reliable for **AABB** with a *negative* [size](class_aabb.md#class_AABB_property_size). Use [abs()](class_aabb.md#class_AABB_method_abs) first to get a valid bounding box. + +
+ + + + + +[bool](class_bool.md) **has_surface**\ (\ ) const [🔗](#class_AABB_method_has_surface) + +Returns ``true`` if this bounding box has a surface or a length, that is, at least one component of [size](class_aabb.md#class_AABB_property_size) is greater than ``0``. Otherwise, returns ``false``. + +
+ + + + + +[bool](class_bool.md) **has_volume**\ (\ ) const [🔗](#class_AABB_method_has_volume) + +Returns ``true`` if this bounding box's width, height, and depth are all positive. See also [get_volume()](class_aabb.md#class_AABB_method_get_volume). + +
+ + + + + +[AABB](class_aabb.md) **intersection**\ (\ with\: [AABB](class_aabb.md)\ ) const [🔗](#class_AABB_method_intersection) + +Returns the intersection between this bounding box and `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 [has_surface()](class_aabb.md#class_AABB_method_has_surface) and [has_volume()](class_aabb.md#class_AABB_method_has_volume)). + + + + +```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) +``` + +```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) +``` + + + +\ **Note:** If you only need to know whether two bounding boxes are intersecting, use [intersects()](class_aabb.md#class_AABB_method_intersects), instead. + +
+ + + + + +[bool](class_bool.md) **intersects**\ (\ with\: [AABB](class_aabb.md)\ ) const [🔗](#class_AABB_method_intersects) + +Returns ``true`` if this bounding box overlaps with the box `with`. The edges of both boxes are *always* excluded. + +
+ + + + + +[bool](class_bool.md) **intersects_plane**\ (\ plane\: [Plane](class_plane.md)\ ) const [🔗](#class_AABB_method_intersects_plane) + +Returns ``true`` if this bounding box is on both sides of the given `plane`. + +
+ + + + + +[Variant](class_variant.md) **intersects_ray**\ (\ from\: [Vector3](class_vector3.md), dir\: [Vector3](class_vector3.md)\ ) const [🔗](#class_AABB_method_intersects_ray) + +Returns the first point where this bounding box and the given ray intersect, as a [Vector3](class_vector3.md). If no intersection occurs, returns ``null``. + +The ray begin at `from`, faces `dir` and extends towards infinity. + +
+ + + + + +[Variant](class_variant.md) **intersects_segment**\ (\ from\: [Vector3](class_vector3.md), to\: [Vector3](class_vector3.md)\ ) const [🔗](#class_AABB_method_intersects_segment) + +Returns the first point where this bounding box and the given segment intersect, as a [Vector3](class_vector3.md). If no intersection occurs, returns ``null``. + +The segment begins at `from` and ends at `to`. + +
+ + + + + +[bool](class_bool.md) **is_equal_approx**\ (\ aabb\: [AABB](class_aabb.md)\ ) const [🔗](#class_AABB_method_is_equal_approx) + +Returns ``true`` if this bounding box and `aabb` are approximately equal, by calling [Vector3.is_equal_approx()](class_vector3.md#class_Vector3_method_is_equal_approx) on the [position](class_aabb.md#class_AABB_property_position) and the [size](class_aabb.md#class_AABB_property_size). + +
+ + + + + +[bool](class_bool.md) **is_finite**\ (\ ) const [🔗](#class_AABB_method_is_finite) + +Returns ``true`` if this bounding box's values are finite, by calling [Vector3.is_finite()](class_vector3.md#class_Vector3_method_is_finite) on the [position](class_aabb.md#class_AABB_property_position) and the [size](class_aabb.md#class_AABB_property_size). + +
+ + + + + +[AABB](class_aabb.md) **merge**\ (\ with\: [AABB](class_aabb.md)\ ) const [🔗](#class_AABB_method_merge) + +Returns an **AABB** that encloses both this bounding box and `with` around the edges. See also [encloses()](class_aabb.md#class_AABB_method_encloses). + +
+ + + +## Operator Descriptions + + + + + +[bool](class_bool.md) **operator !=**\ (\ right\: [AABB](class_aabb.md)\ ) [🔗](#class_AABB_operator_neq_AABB) + +Returns ``true`` if the [position](class_aabb.md#class_AABB_property_position) or [size](class_aabb.md#class_AABB_property_size) of both bounding boxes are not equal. + +\ **Note:** Due to floating-point precision errors, consider using [is_equal_approx()](class_aabb.md#class_AABB_method_is_equal_approx) instead, which is more reliable. + +
+ + + + + +[AABB](class_aabb.md) **operator ***\ (\ right\: [Transform3D](class_transform3d.md)\ ) [🔗](#class_AABB_operator_mul_Transform3D) + +Inversely transforms (multiplies) the **AABB** by the given [Transform3D](class_transform3d.md) transformation matrix, under the assumption that the transformation basis is orthonormal (i.e. rotation/reflection is fine, scaling/skew is not). + +\ ``aabb * transform`` is equivalent to ``transform.inverse() * aabb``. See [Transform3D.inverse()](class_transform3d.md#class_Transform3D_method_inverse). + +For transforming by inverse of an affine transformation (e.g. with scaling) ``transform.affine_inverse() * aabb`` can be used instead. See [Transform3D.affine_inverse()](class_transform3d.md#class_Transform3D_method_affine_inverse). + +
+ + + + + +[bool](class_bool.md) **operator ==**\ (\ right\: [AABB](class_aabb.md)\ ) [🔗](#class_AABB_operator_eq_AABB) + +Returns ``true`` if both [position](class_aabb.md#class_AABB_property_position) and [size](class_aabb.md#class_AABB_property_size) of the bounding boxes are exactly equal, respectively. + +\ **Note:** Due to floating-point precision errors, consider using [is_equal_approx()](class_aabb.md#class_AABB_method_is_equal_approx) instead, which is more reliable. + diff --git a/docs/Classes/class_acceptdialog.md b/docs/Classes/class_acceptdialog.md new file mode 100644 index 00000000..d77e8e04 --- /dev/null +++ b/docs/Classes/class_acceptdialog.md @@ -0,0 +1,400 @@ + + + + + + + + + +# AcceptDialog + +**Inherits:** [Window](class_window.md) **<** [Viewport](class_viewport.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +**Inherited By:** [ConfirmationDialog](class_confirmationdialog.md) + +A base dialog used for user notification. + + + +## Description + +The default use of **AcceptDialog** is to allow it to only be accepted or closed, with the same result. However, the [confirmed](class_acceptdialog.md#class_AcceptDialog_signal_confirmed) and [canceled](class_acceptdialog.md#class_AcceptDialog_signal_canceled) signals allow to make the two actions different, and the [add_button()](class_acceptdialog.md#class_AcceptDialog_method_add_button) method allows to add custom buttons and actions. + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[dialog_autowrap](#class_AcceptDialog_property_dialog_autowrap)`false`
[bool](class_bool.md)[dialog_close_on_escape](#class_AcceptDialog_property_dialog_close_on_escape)`true`
[bool](class_bool.md)[dialog_hide_on_ok](#class_AcceptDialog_property_dialog_hide_on_ok)`true`
[String](class_string.md)[dialog_text](#class_AcceptDialog_property_dialog_text)`""`
[bool](class_bool.md)exclusive`true` (overrides [Window.exclusive](class_window.md#class_Window_property_exclusive))
[bool](class_bool.md)keep_title_visible`true` (overrides [Window.keep_title_visible](class_window.md#class_Window_property_keep_title_visible))
[bool](class_bool.md)maximize_disabled`true` (overrides [Window.maximize_disabled](class_window.md#class_Window_property_maximize_disabled))
[bool](class_bool.md)minimize_disabled`true` (overrides [Window.minimize_disabled](class_window.md#class_Window_property_minimize_disabled))
[String](class_string.md)[ok_button_text](#class_AcceptDialog_property_ok_button_text)`""`
[String](class_string.md)title`"Alert!"` (overrides [Window.title](class_window.md#class_Window_property_title))
[bool](class_bool.md)transient`true` (overrides [Window.transient](class_window.md#class_Window_property_transient))
[bool](class_bool.md)visible`false` (overrides [Window.visible](class_window.md#class_Window_property_visible))
[bool](class_bool.md)wrap_controls`true` (overrides [Window.wrap_controls](class_window.md#class_Window_property_wrap_controls))
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Button](class_button.md)[add_button](#class_AcceptDialog_method_add_button)\ (\ text\: [String](class_string.md), right\: [bool](class_bool.md) = false, action\: [String](class_string.md) = ""\ )
[Button](class_button.md)[add_cancel_button](#class_AcceptDialog_method_add_cancel_button)\ (\ name\: [String](class_string.md)\ )
[Label](class_label.md)[get_label](#class_AcceptDialog_method_get_label)\ (\ )
[Button](class_button.md)[get_ok_button](#class_AcceptDialog_method_get_ok_button)\ (\ )
`void`[register_text_enter](#class_AcceptDialog_method_register_text_enter)\ (\ line_edit\: [LineEdit](class_lineedit.md)\ )
`void`[remove_button](#class_AcceptDialog_method_remove_button)\ (\ button\: [Button](class_button.md)\ )
+ + + +## Theme Properties + + + + + + + + + + + + + + + + + + + + + + + + + + +
[int](class_int.md)[buttons_min_height](#class_AcceptDialog_theme_constant_buttons_min_height)`0`
[int](class_int.md)[buttons_min_width](#class_AcceptDialog_theme_constant_buttons_min_width)`0`
[int](class_int.md)[buttons_separation](#class_AcceptDialog_theme_constant_buttons_separation)`10`
[StyleBox](class_stylebox.md)[panel](#class_AcceptDialog_theme_style_panel)
+ +
+ + + +## Signals + + + + + +**canceled**\ (\ ) [🔗](#class_AcceptDialog_signal_canceled) + +Emitted when the dialog is closed or the button created with [add_cancel_button()](class_acceptdialog.md#class_AcceptDialog_method_add_cancel_button) is pressed. + +
+ + + + + +**confirmed**\ (\ ) [🔗](#class_AcceptDialog_signal_confirmed) + +Emitted when the dialog is accepted, i.e. the OK button is pressed. + +
+ + + + + +**custom_action**\ (\ action\: [StringName](class_stringname.md)\ ) [🔗](#class_AcceptDialog_signal_custom_action) + +Emitted when a custom button with an action is pressed. See [add_button()](class_acceptdialog.md#class_AcceptDialog_method_add_button). + +
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **dialog_autowrap** = `false` [🔗](#class_AcceptDialog_property_dialog_autowrap) + + + +- `void` **set_autowrap**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **has_autowrap**\ (\ ) + +Sets autowrapping for the text in the dialog. + +
+ + + + + +[bool](class_bool.md) **dialog_close_on_escape** = `true` [🔗](#class_AcceptDialog_property_dialog_close_on_escape) + + + +- `void` **set_close_on_escape**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_close_on_escape**\ (\ ) + +If ``true``, the dialog will be hidden when the ``ui_cancel`` action is pressed (by default, this action is bound to [@GlobalScope.KEY_ESCAPE](class_@globalscope.md#class_@GlobalScope_constant_KEY_ESCAPE)). + +
+ + + + + +[bool](class_bool.md) **dialog_hide_on_ok** = `true` [🔗](#class_AcceptDialog_property_dialog_hide_on_ok) + + + +- `void` **set_hide_on_ok**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_hide_on_ok**\ (\ ) + +If ``true``, the dialog is hidden when the OK button is pressed. You can set it to ``false`` if you want to do e.g. input validation when receiving the [confirmed](class_acceptdialog.md#class_AcceptDialog_signal_confirmed) signal, and handle hiding the dialog in your own logic. + +\ **Note:** 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](class_filedialog.md) defaults to ``false``, 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](class_filedialog.md) to disable hiding the dialog when pressing OK. + +
+ + + + + +[String](class_string.md) **dialog_text** = `""` [🔗](#class_AcceptDialog_property_dialog_text) + + + +- `void` **set_text**\ (\ value\: [String](class_string.md)\ ) +- [String](class_string.md) **get_text**\ (\ ) + +The text displayed by the dialog. + +
+ + + + + +[String](class_string.md) **ok_button_text** = `""` [🔗](#class_AcceptDialog_property_ok_button_text) + + + +- `void` **set_ok_button_text**\ (\ value\: [String](class_string.md)\ ) +- [String](class_string.md) **get_ok_button_text**\ (\ ) + +The text displayed by the OK button (see [get_ok_button()](class_acceptdialog.md#class_AcceptDialog_method_get_ok_button)). If empty, a default text will be used. + +
+ + + +## Method Descriptions + + + + + +[Button](class_button.md) **add_button**\ (\ text\: [String](class_string.md), right\: [bool](class_bool.md) = false, action\: [String](class_string.md) = ""\ ) [🔗](#class_AcceptDialog_method_add_button) + +Adds a button with label `text` and a custom `action` to the dialog and returns the created button. + +If `action` is not empty, pressing the button will emit the [custom_action](class_acceptdialog.md#class_AcceptDialog_signal_custom_action) signal with the specified action string. + +If ``true``, `right` will place the button to the right of any sibling buttons. + +You can use [remove_button()](class_acceptdialog.md#class_AcceptDialog_method_remove_button) method to remove a button created with this method from the dialog. + +
+ + + + + +[Button](class_button.md) **add_cancel_button**\ (\ name\: [String](class_string.md)\ ) [🔗](#class_AcceptDialog_method_add_cancel_button) + +Adds a button with label `name` and a cancel action to the dialog and returns the created button. + +You can use [remove_button()](class_acceptdialog.md#class_AcceptDialog_method_remove_button) method to remove a button created with this method from the dialog. + +
+ + + + + +[Label](class_label.md) **get_label**\ (\ ) [🔗](#class_AcceptDialog_method_get_label) + +Returns the label used for built-in text. + +\ **Warning:** 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 [CanvasItem.visible](class_canvasitem.md#class_CanvasItem_property_visible) property. + +
+ + + + + +[Button](class_button.md) **get_ok_button**\ (\ ) [🔗](#class_AcceptDialog_method_get_ok_button) + +Returns the OK [Button](class_button.md) instance. + +\ **Warning:** 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 [CanvasItem.visible](class_canvasitem.md#class_CanvasItem_property_visible) property. + +
+ + + + + +`void` **register_text_enter**\ (\ line_edit\: [LineEdit](class_lineedit.md)\ ) [🔗](#class_AcceptDialog_method_register_text_enter) + +Registers a [LineEdit](class_lineedit.md) in the dialog. When the enter key is pressed, the dialog will be accepted. + +
+ + + + + +`void` **remove_button**\ (\ button\: [Button](class_button.md)\ ) [🔗](#class_AcceptDialog_method_remove_button) + +Removes the `button` from the dialog. Does NOT free the `button`. The `button` must be a [Button](class_button.md) added with [add_button()](class_acceptdialog.md#class_AcceptDialog_method_add_button) or [add_cancel_button()](class_acceptdialog.md#class_AcceptDialog_method_add_cancel_button) method. After removal, pressing the `button` will no longer emit this dialog's [custom_action](class_acceptdialog.md#class_AcceptDialog_signal_custom_action) or [canceled](class_acceptdialog.md#class_AcceptDialog_signal_canceled) signals. + +
+ + + +## Theme Property Descriptions + + + + + +[int](class_int.md) **buttons_min_height** = `0` [🔗](#class_AcceptDialog_theme_constant_buttons_min_height) + +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. + +
+ + + + + +[int](class_int.md) **buttons_min_width** = `0` [🔗](#class_AcceptDialog_theme_constant_buttons_min_width) + +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. + +
+ + + + + +[int](class_int.md) **buttons_separation** = `10` [🔗](#class_AcceptDialog_theme_constant_buttons_separation) + +The size of the vertical space between the dialog's content and the button row. + +
+ + + + + +[StyleBox](class_stylebox.md) **panel** [🔗](#class_AcceptDialog_theme_style_panel) + +The panel that fills the background of the window. + diff --git a/docs/Classes/class_aescontext.md b/docs/Classes/class_aescontext.md new file mode 100644 index 00000000..42213d52 --- /dev/null +++ b/docs/Classes/class_aescontext.md @@ -0,0 +1,213 @@ + + + + + + + + + +# AESContext + +**Inherits:** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Provides access to AES encryption/decryption of raw data. + + + +## 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. + + + + +```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()) +``` + +```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()); + } + } +``` + + + + + +## Methods + + + + + + + + + + + + + + + + + + + + + + +
`void`[finish](#class_AESContext_method_finish)\ (\ )
[PackedByteArray](class_packedbytearray.md)[get_iv_state](#class_AESContext_method_get_iv_state)\ (\ )
[Error](class_@globalscope.md#enum_@GlobalScope_Error)[start](#class_AESContext_method_start)\ (\ mode\: [Mode](class_aescontext.md#enum_AESContext_Mode), key\: [PackedByteArray](class_packedbytearray.md), iv\: [PackedByteArray](class_packedbytearray.md) = PackedByteArray()\ )
[PackedByteArray](class_packedbytearray.md)[update](#class_AESContext_method_update)\ (\ src\: [PackedByteArray](class_packedbytearray.md)\ )
+ +
+ + + +## Enumerations + + + + + +enum **Mode**: [🔗](#enum_AESContext_Mode) + + + + + +[Mode](class_aescontext.md#enum_AESContext_Mode) **MODE_ECB_ENCRYPT** = `0` + +AES electronic codebook encryption mode. + + + +[Mode](class_aescontext.md#enum_AESContext_Mode) **MODE_ECB_DECRYPT** = `1` + +AES electronic codebook decryption mode. + + + +[Mode](class_aescontext.md#enum_AESContext_Mode) **MODE_CBC_ENCRYPT** = `2` + +AES cipher blocker chaining encryption mode. + + + +[Mode](class_aescontext.md#enum_AESContext_Mode) **MODE_CBC_DECRYPT** = `3` + +AES cipher blocker chaining decryption mode. + + + +[Mode](class_aescontext.md#enum_AESContext_Mode) **MODE_MAX** = `4` + +Maximum value for the mode enum.
+ + + +## Method Descriptions + + + + + +`void` **finish**\ (\ ) [🔗](#class_AESContext_method_finish) + +Close this AES context so it can be started again. See [start()](class_aescontext.md#class_AESContext_method_start). + +
+ + + + + +[PackedByteArray](class_packedbytearray.md) **get_iv_state**\ (\ ) [🔗](#class_AESContext_method_get_iv_state) + +Get the current IV state for this context (IV gets updated when calling [update()](class_aescontext.md#class_AESContext_method_update)). You normally don't need this function. + +\ **Note:** This function only makes sense when the context is started with [MODE_CBC_ENCRYPT](class_aescontext.md#class_AESContext_constant_MODE_CBC_ENCRYPT) or [MODE_CBC_DECRYPT](class_aescontext.md#class_AESContext_constant_MODE_CBC_DECRYPT). + +
+ + + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **start**\ (\ mode\: [Mode](class_aescontext.md#enum_AESContext_Mode), key\: [PackedByteArray](class_packedbytearray.md), iv\: [PackedByteArray](class_packedbytearray.md) = PackedByteArray()\ ) [🔗](#class_AESContext_method_start) + +Start the AES context in the given `mode`. A `key` of either 16 or 32 bytes must always be provided, while an `iv` (initialization vector) of exactly 16 bytes, is only needed when `mode` is either [MODE_CBC_ENCRYPT](class_aescontext.md#class_AESContext_constant_MODE_CBC_ENCRYPT) or [MODE_CBC_DECRYPT](class_aescontext.md#class_AESContext_constant_MODE_CBC_DECRYPT). + +
+ + + + + +[PackedByteArray](class_packedbytearray.md) **update**\ (\ src\: [PackedByteArray](class_packedbytearray.md)\ ) [🔗](#class_AESContext_method_update) + +Run the desired operation for this AES context. Will return a [PackedByteArray](class_packedbytearray.md) containing the result of encrypting (or decrypting) the given `src`. See [start()](class_aescontext.md#class_AESContext_method_start) for mode of operation. + +\ **Note:** The size of `src` must be a multiple of 16. Apply some padding if needed. + diff --git a/docs/Classes/class_aimmodifier3d.md b/docs/Classes/class_aimmodifier3d.md new file mode 100644 index 00000000..37b8e0e9 --- /dev/null +++ b/docs/Classes/class_aimmodifier3d.md @@ -0,0 +1,187 @@ + + + + + + + + + +# AimModifier3D + +**Inherits:** [BoneConstraint3D](class_boneconstraint3d.md) **<** [SkeletonModifier3D](class_skeletonmodifier3d.md) **<** [Node3D](class_node3d.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +The **AimModifier3D** rotates a bone to look at a reference bone. + + + +## Description + +This is a simple version of [LookAtModifier3D](class_lookatmodifier3d.md) 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 [set_use_euler()](class_aimmodifier3d.md#class_AimModifier3D_method_set_use_euler). + + + +## Properties + + + + + + + + + + + +
[int](class_int.md)[setting_count](#class_AimModifier3D_property_setting_count)`0`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[BoneAxis](class_skeletonmodifier3d.md#enum_SkeletonModifier3D_BoneAxis)[get_forward_axis](#class_AimModifier3D_method_get_forward_axis)\ (\ index\: [int](class_int.md)\ ) const
[Axis](class_vector3.md#enum_Vector3_Axis)[get_primary_rotation_axis](#class_AimModifier3D_method_get_primary_rotation_axis)\ (\ index\: [int](class_int.md)\ ) const
[bool](class_bool.md)[is_using_euler](#class_AimModifier3D_method_is_using_euler)\ (\ index\: [int](class_int.md)\ ) const
[bool](class_bool.md)[is_using_secondary_rotation](#class_AimModifier3D_method_is_using_secondary_rotation)\ (\ index\: [int](class_int.md)\ ) const
`void`[set_forward_axis](#class_AimModifier3D_method_set_forward_axis)\ (\ index\: [int](class_int.md), axis\: [BoneAxis](class_skeletonmodifier3d.md#enum_SkeletonModifier3D_BoneAxis)\ )
`void`[set_primary_rotation_axis](#class_AimModifier3D_method_set_primary_rotation_axis)\ (\ index\: [int](class_int.md), axis\: [Axis](class_vector3.md#enum_Vector3_Axis)\ )
`void`[set_use_euler](#class_AimModifier3D_method_set_use_euler)\ (\ index\: [int](class_int.md), enabled\: [bool](class_bool.md)\ )
`void`[set_use_secondary_rotation](#class_AimModifier3D_method_set_use_secondary_rotation)\ (\ index\: [int](class_int.md), enabled\: [bool](class_bool.md)\ )
+ +
+ + + +## Property Descriptions + + + + + +[int](class_int.md) **setting_count** = `0` [🔗](#class_AimModifier3D_property_setting_count) + + + +- `void` **set_setting_count**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_setting_count**\ (\ ) + +The number of settings in the modifier. + +
+ + + +## Method Descriptions + + + + + +[BoneAxis](class_skeletonmodifier3d.md#enum_SkeletonModifier3D_BoneAxis) **get_forward_axis**\ (\ index\: [int](class_int.md)\ ) const [🔗](#class_AimModifier3D_method_get_forward_axis) + +Returns the forward axis of the bone. + +
+ + + + + +[Axis](class_vector3.md#enum_Vector3_Axis) **get_primary_rotation_axis**\ (\ index\: [int](class_int.md)\ ) const [🔗](#class_AimModifier3D_method_get_primary_rotation_axis) + +Returns the axis of the first rotation. It is enabled only if [is_using_euler()](class_aimmodifier3d.md#class_AimModifier3D_method_is_using_euler) is ``true``. + +
+ + + + + +[bool](class_bool.md) **is_using_euler**\ (\ index\: [int](class_int.md)\ ) const [🔗](#class_AimModifier3D_method_is_using_euler) + +Returns ``true`` if it provides rotation with using euler. + +
+ + + + + +[bool](class_bool.md) **is_using_secondary_rotation**\ (\ index\: [int](class_int.md)\ ) const [🔗](#class_AimModifier3D_method_is_using_secondary_rotation) + +Returns ``true`` if it provides rotation by two axes. It is enabled only if [is_using_euler()](class_aimmodifier3d.md#class_AimModifier3D_method_is_using_euler) is ``true``. + +
+ + + + + +`void` **set_forward_axis**\ (\ index\: [int](class_int.md), axis\: [BoneAxis](class_skeletonmodifier3d.md#enum_SkeletonModifier3D_BoneAxis)\ ) [🔗](#class_AimModifier3D_method_set_forward_axis) + +Sets the forward axis of the bone. + +
+ + + + + +`void` **set_primary_rotation_axis**\ (\ index\: [int](class_int.md), axis\: [Axis](class_vector3.md#enum_Vector3_Axis)\ ) [🔗](#class_AimModifier3D_method_set_primary_rotation_axis) + +Sets the axis of the first rotation. It is enabled only if [is_using_euler()](class_aimmodifier3d.md#class_AimModifier3D_method_is_using_euler) is ``true``. + +
+ + + + + +`void` **set_use_euler**\ (\ index\: [int](class_int.md), enabled\: [bool](class_bool.md)\ ) [🔗](#class_AimModifier3D_method_set_use_euler) + +If sets `enabled` to ``true``, it provides rotation with using euler. + +If sets `enabled` to ``false``, it provides rotation with using rotation by arc generated from the forward axis vector and the vector toward the reference. + +
+ + + + + +`void` **set_use_secondary_rotation**\ (\ index\: [int](class_int.md), enabled\: [bool](class_bool.md)\ ) [🔗](#class_AimModifier3D_method_set_use_secondary_rotation) + +If sets `enabled` to ``true``, it provides rotation by two axes. It is enabled only if [is_using_euler()](class_aimmodifier3d.md#class_AimModifier3D_method_is_using_euler) is ``true``. + diff --git a/docs/Classes/class_animatablebody2d.md b/docs/Classes/class_animatablebody2d.md new file mode 100644 index 00000000..6bcdca54 --- /dev/null +++ b/docs/Classes/class_animatablebody2d.md @@ -0,0 +1,66 @@ + + + + + + + + + +# AnimatableBody2D + +**Inherits:** [StaticBody2D](class_staticbody2d.md) **<** [PhysicsBody2D](class_physicsbody2d.md) **<** [CollisionObject2D](class_collisionobject2d.md) **<** [Node2D](class_node2d.md) **<** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +A 2D physics body that can't be moved by external forces. When moved manually, it affects other bodies in its path. + + + +## 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](class_animationmixer.md)\ s (with [AnimationMixer.callback_mode_process](class_animationmixer.md#class_AnimationMixer_property_callback_mode_process) set to [AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS](class_animationmixer.md#class_AnimationMixer_constant_ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS)), and [RemoteTransform2D](class_remotetransform2d.md). + +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. + + + +## Tutorials + +- [Physics introduction](../tutorials/physics/physics_introduction.md) + +- [Troubleshooting physics issues](../tutorials/physics/troubleshooting_physics_issues.md) + + + +## Properties + + + + + + + + + + + +
[bool](class_bool.md)[sync_to_physics](#class_AnimatableBody2D_property_sync_to_physics)`true`
+ +
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **sync_to_physics** = `true` [🔗](#class_AnimatableBody2D_property_sync_to_physics) + + + +- `void` **set_sync_to_physics**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_sync_to_physics_enabled**\ (\ ) + +If ``true``, the body's movement will be synchronized to the physics frame. This is useful when animating movement via [AnimationPlayer](class_animationplayer.md), for example on moving platforms. Do **not** use together with [PhysicsBody2D.move_and_collide()](class_physicsbody2d.md#class_PhysicsBody2D_method_move_and_collide). + diff --git a/docs/Classes/class_animatablebody3d.md b/docs/Classes/class_animatablebody3d.md new file mode 100644 index 00000000..f81546f6 --- /dev/null +++ b/docs/Classes/class_animatablebody3d.md @@ -0,0 +1,72 @@ + + + + + + + + + +# AnimatableBody3D + +**Inherits:** [StaticBody3D](class_staticbody3d.md) **<** [PhysicsBody3D](class_physicsbody3d.md) **<** [CollisionObject3D](class_collisionobject3d.md) **<** [Node3D](class_node3d.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +A 3D physics body that can't be moved by external forces. When moved manually, it affects other bodies in its path. + + + +## 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](class_animationmixer.md)\ s (with [AnimationMixer.callback_mode_process](class_animationmixer.md#class_AnimationMixer_property_callback_mode_process) set to [AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS](class_animationmixer.md#class_AnimationMixer_constant_ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS)), and [RemoteTransform3D](class_remotetransform3d.md). + +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. + + + +## Tutorials + +- [Physics introduction](../tutorials/physics/physics_introduction.md) + +- [Troubleshooting physics issues](../tutorials/physics/troubleshooting_physics_issues.md) + +- [3D Physics Tests Demo](https://godotengine.org/asset-library/asset/2747) + +- [Third Person Shooter (TPS) Demo](https://godotengine.org/asset-library/asset/2710) + +- [3D Voxel Demo](https://godotengine.org/asset-library/asset/2755) + + + +## Properties + + + + + + + + + + + +
[bool](class_bool.md)[sync_to_physics](#class_AnimatableBody3D_property_sync_to_physics)`true`
+ +
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **sync_to_physics** = `true` [🔗](#class_AnimatableBody3D_property_sync_to_physics) + + + +- `void` **set_sync_to_physics**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_sync_to_physics_enabled**\ (\ ) + +If ``true``, the body's movement will be synchronized to the physics frame. This is useful when animating movement via [AnimationPlayer](class_animationplayer.md), for example on moving platforms. Do **not** use together with [PhysicsBody3D.move_and_collide()](class_physicsbody3d.md#class_PhysicsBody3D_method_move_and_collide). + diff --git a/docs/Classes/class_animatedsprite2d.md b/docs/Classes/class_animatedsprite2d.md new file mode 100644 index 00000000..a0dce629 --- /dev/null +++ b/docs/Classes/class_animatedsprite2d.md @@ -0,0 +1,439 @@ + + + + + + + + + +# AnimatedSprite2D + +**Inherits:** [Node2D](class_node2d.md) **<** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +Sprite node that contains multiple textures as frames to play for animation. + + + +## Description + +**AnimatedSprite2D** is similar to the [Sprite2D](class_sprite2d.md) node, except it carries multiple textures as animation frames. Animations are created using a [SpriteFrames](class_spriteframes.md) resource, which allows you to import image files (or a folder containing said files) to provide the animation frames for the sprite. The [SpriteFrames](class_spriteframes.md) resource can be configured in the editor via the SpriteFrames bottom panel. + + + +## Tutorials + +- [2D Sprite animation](../tutorials/2d/2d_sprite_animation.md) + +- [2D Dodge The Creeps Demo](https://godotengine.org/asset-library/asset/2712) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[StringName](class_stringname.md)[animation](#class_AnimatedSprite2D_property_animation)`&"default"`
[String](class_string.md)[autoplay](#class_AnimatedSprite2D_property_autoplay)`""`
[bool](class_bool.md)[centered](#class_AnimatedSprite2D_property_centered)`true`
[bool](class_bool.md)[flip_h](#class_AnimatedSprite2D_property_flip_h)`false`
[bool](class_bool.md)[flip_v](#class_AnimatedSprite2D_property_flip_v)`false`
[int](class_int.md)[frame](#class_AnimatedSprite2D_property_frame)`0`
[float](class_float.md)[frame_progress](#class_AnimatedSprite2D_property_frame_progress)`0.0`
[Vector2](class_vector2.md)[offset](#class_AnimatedSprite2D_property_offset)`Vector2(0, 0)`
[float](class_float.md)[speed_scale](#class_AnimatedSprite2D_property_speed_scale)`1.0`
[SpriteFrames](class_spriteframes.md)[sprite_frames](#class_AnimatedSprite2D_property_sprite_frames)
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[get_playing_speed](#class_AnimatedSprite2D_method_get_playing_speed)\ (\ ) const
[bool](class_bool.md)[is_playing](#class_AnimatedSprite2D_method_is_playing)\ (\ ) const
`void`[pause](#class_AnimatedSprite2D_method_pause)\ (\ )
`void`[play](#class_AnimatedSprite2D_method_play)\ (\ name\: [StringName](class_stringname.md) = &"", custom_speed\: [float](class_float.md) = 1.0, from_end\: [bool](class_bool.md) = false\ )
`void`[play_backwards](#class_AnimatedSprite2D_method_play_backwards)\ (\ name\: [StringName](class_stringname.md) = &""\ )
`void`[set_frame_and_progress](#class_AnimatedSprite2D_method_set_frame_and_progress)\ (\ frame\: [int](class_int.md), progress\: [float](class_float.md)\ )
`void`[stop](#class_AnimatedSprite2D_method_stop)\ (\ )
+ +
+ + + +## Signals + + + + + +**animation_changed**\ (\ ) [🔗](#class_AnimatedSprite2D_signal_animation_changed) + +Emitted when [animation](class_animatedsprite2d.md#class_AnimatedSprite2D_property_animation) changes. + +
+ + + + + +**animation_finished**\ (\ ) [🔗](#class_AnimatedSprite2D_signal_animation_finished) + +Emitted when the animation reaches the end, or the start if it is played in reverse. When the animation finishes, it pauses the playback. + +\ **Note:** This signal is not emitted if an animation is looping. + +
+ + + + + +**animation_looped**\ (\ ) [🔗](#class_AnimatedSprite2D_signal_animation_looped) + +Emitted when the animation loops. + +
+ + + + + +**frame_changed**\ (\ ) [🔗](#class_AnimatedSprite2D_signal_frame_changed) + +Emitted when [frame](class_animatedsprite2d.md#class_AnimatedSprite2D_property_frame) changes. + +
+ + + + + +**sprite_frames_changed**\ (\ ) [🔗](#class_AnimatedSprite2D_signal_sprite_frames_changed) + +Emitted when [sprite_frames](class_animatedsprite2d.md#class_AnimatedSprite2D_property_sprite_frames) changes. + +
+ + + +## Property Descriptions + + + + + +[StringName](class_stringname.md) **animation** = `&"default"` [🔗](#class_AnimatedSprite2D_property_animation) + + + +- `void` **set_animation**\ (\ value\: [StringName](class_stringname.md)\ ) +- [StringName](class_stringname.md) **get_animation**\ (\ ) + +The current animation from the [sprite_frames](class_animatedsprite2d.md#class_AnimatedSprite2D_property_sprite_frames) resource. If this value is changed, the [frame](class_animatedsprite2d.md#class_AnimatedSprite2D_property_frame) counter and the [frame_progress](class_animatedsprite2d.md#class_AnimatedSprite2D_property_frame_progress) are reset. + +
+ + + + + +[String](class_string.md) **autoplay** = `""` [🔗](#class_AnimatedSprite2D_property_autoplay) + + + +- `void` **set_autoplay**\ (\ value\: [String](class_string.md)\ ) +- [String](class_string.md) **get_autoplay**\ (\ ) + +The key of the animation to play when the scene loads. + +
+ + + + + +[bool](class_bool.md) **centered** = `true` [🔗](#class_AnimatedSprite2D_property_centered) + + + +- `void` **set_centered**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_centered**\ (\ ) + +If ``true``, texture will be centered. + +\ **Note:** 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 ``false``, or consider enabling [ProjectSettings.rendering/2d/snap/snap_2d_vertices_to_pixel](class_projectsettings.md#class_ProjectSettings_property_rendering/2d/snap/snap_2d_vertices_to_pixel) and [ProjectSettings.rendering/2d/snap/snap_2d_transforms_to_pixel](class_projectsettings.md#class_ProjectSettings_property_rendering/2d/snap/snap_2d_transforms_to_pixel). + +
+ + + + + +[bool](class_bool.md) **flip_h** = `false` [🔗](#class_AnimatedSprite2D_property_flip_h) + + + +- `void` **set_flip_h**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_flipped_h**\ (\ ) + +If ``true``, texture is flipped horizontally. + +
+ + + + + +[bool](class_bool.md) **flip_v** = `false` [🔗](#class_AnimatedSprite2D_property_flip_v) + + + +- `void` **set_flip_v**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_flipped_v**\ (\ ) + +If ``true``, texture is flipped vertically. + +
+ + + + + +[int](class_int.md) **frame** = `0` [🔗](#class_AnimatedSprite2D_property_frame) + + + +- `void` **set_frame**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_frame**\ (\ ) + +The displayed animation frame's index. Setting this property also resets [frame_progress](class_animatedsprite2d.md#class_AnimatedSprite2D_property_frame_progress). If this is not desired, use [set_frame_and_progress()](class_animatedsprite2d.md#class_AnimatedSprite2D_method_set_frame_and_progress). + +
+ + + + + +[float](class_float.md) **frame_progress** = `0.0` [🔗](#class_AnimatedSprite2D_property_frame_progress) + + + +- `void` **set_frame_progress**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_frame_progress**\ (\ ) + +The progress value between ``0.0`` and ``1.0`` until the current frame transitions to the next frame. If the animation is playing backwards, the value transitions from ``1.0`` to ``0.0``. + +
+ + + + + +[Vector2](class_vector2.md) **offset** = `Vector2(0, 0)` [🔗](#class_AnimatedSprite2D_property_offset) + + + +- `void` **set_offset**\ (\ value\: [Vector2](class_vector2.md)\ ) +- [Vector2](class_vector2.md) **get_offset**\ (\ ) + +The texture's drawing offset. + +
+ + + + + +[float](class_float.md) **speed_scale** = `1.0` [🔗](#class_AnimatedSprite2D_property_speed_scale) + + + +- `void` **set_speed_scale**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_speed_scale**\ (\ ) + +The speed scaling ratio. For example, if this value is ``1``, then the animation plays at normal speed. If it's ``0.5``, then it plays at half speed. If it's ``2``, then it plays at double speed. + +If set to a negative value, the animation is played in reverse. If set to ``0``, the animation will not advance. + +
+ + + + + +[SpriteFrames](class_spriteframes.md) **sprite_frames** [🔗](#class_AnimatedSprite2D_property_sprite_frames) + + + +- `void` **set_sprite_frames**\ (\ value\: [SpriteFrames](class_spriteframes.md)\ ) +- [SpriteFrames](class_spriteframes.md) **get_sprite_frames**\ (\ ) + +The [SpriteFrames](class_spriteframes.md) resource containing the animation(s). Allows you the option to load, edit, clear, make unique and save the states of the [SpriteFrames](class_spriteframes.md) resource. + +
+ + + +## Method Descriptions + + + + + +[float](class_float.md) **get_playing_speed**\ (\ ) const [🔗](#class_AnimatedSprite2D_method_get_playing_speed) + +Returns the actual playing speed of current animation or ``0`` if not playing. This speed is the [speed_scale](class_animatedsprite2d.md#class_AnimatedSprite2D_property_speed_scale) property multiplied by ``custom_speed`` argument specified when calling the [play()](class_animatedsprite2d.md#class_AnimatedSprite2D_method_play) method. + +Returns a negative value if the current animation is playing backwards. + +
+ + + + + +[bool](class_bool.md) **is_playing**\ (\ ) const [🔗](#class_AnimatedSprite2D_method_is_playing) + +Returns ``true`` if an animation is currently playing (even if [speed_scale](class_animatedsprite2d.md#class_AnimatedSprite2D_property_speed_scale) and/or ``custom_speed`` are ``0``). + +
+ + + + + +`void` **pause**\ (\ ) [🔗](#class_AnimatedSprite2D_method_pause) + +Pauses the currently playing animation. The [frame](class_animatedsprite2d.md#class_AnimatedSprite2D_property_frame) and [frame_progress](class_animatedsprite2d.md#class_AnimatedSprite2D_property_frame_progress) will be kept and calling [play()](class_animatedsprite2d.md#class_AnimatedSprite2D_method_play) or [play_backwards()](class_animatedsprite2d.md#class_AnimatedSprite2D_method_play_backwards) without arguments will resume the animation from the current playback position. + +See also [stop()](class_animatedsprite2d.md#class_AnimatedSprite2D_method_stop). + +
+ + + + + +`void` **play**\ (\ name\: [StringName](class_stringname.md) = &"", custom_speed\: [float](class_float.md) = 1.0, from_end\: [bool](class_bool.md) = false\ ) [🔗](#class_AnimatedSprite2D_method_play) + +Plays the animation with key `name`. If `custom_speed` is negative and `from_end` is ``true``, the animation will play backwards (which is equivalent to calling [play_backwards()](class_animatedsprite2d.md#class_AnimatedSprite2D_method_play_backwards)). + +If this method is called with that same animation `name`, or with no `name` parameter, the assigned animation will resume playing if it was paused. + +
+ + + + + +`void` **play_backwards**\ (\ name\: [StringName](class_stringname.md) = &""\ ) [🔗](#class_AnimatedSprite2D_method_play_backwards) + +Plays the animation with key `name` in reverse. + +This method is a shorthand for [play()](class_animatedsprite2d.md#class_AnimatedSprite2D_method_play) with ``custom_speed = -1.0`` and ``from_end = true``, so see its description for more information. + +
+ + + + + +`void` **set_frame_and_progress**\ (\ frame\: [int](class_int.md), progress\: [float](class_float.md)\ ) [🔗](#class_AnimatedSprite2D_method_set_frame_and_progress) + +Sets [frame](class_animatedsprite2d.md#class_AnimatedSprite2D_property_frame) and [frame_progress](class_animatedsprite2d.md#class_AnimatedSprite2D_property_frame_progress) to the given values. Unlike setting [frame](class_animatedsprite2d.md#class_AnimatedSprite2D_property_frame), this method does not reset the [frame_progress](class_animatedsprite2d.md#class_AnimatedSprite2D_property_frame_progress) to ``0.0`` implicitly. + +\ **Example:** Change the animation while keeping the same [frame](class_animatedsprite2d.md#class_AnimatedSprite2D_property_frame) and [frame_progress](class_animatedsprite2d.md#class_AnimatedSprite2D_property_frame_progress): + + + + +```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) +``` + + + +
+ + + + + +`void` **stop**\ (\ ) [🔗](#class_AnimatedSprite2D_method_stop) + +Stops the currently playing animation. The animation position is reset to ``0`` and the ``custom_speed`` is reset to ``1.0``. See also [pause()](class_animatedsprite2d.md#class_AnimatedSprite2D_method_pause). + diff --git a/docs/Classes/class_animatedsprite3d.md b/docs/Classes/class_animatedsprite3d.md new file mode 100644 index 00000000..bc09b651 --- /dev/null +++ b/docs/Classes/class_animatedsprite3d.md @@ -0,0 +1,355 @@ + + + + + + + + + +# AnimatedSprite3D + +**Inherits:** [SpriteBase3D](class_spritebase3d.md) **<** [GeometryInstance3D](class_geometryinstance3d.md) **<** [VisualInstance3D](class_visualinstance3d.md) **<** [Node3D](class_node3d.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +2D sprite node in 3D world, that can use multiple 2D textures for animation. + + + +## Description + +**AnimatedSprite3D** is similar to the [Sprite3D](class_sprite3d.md) node, except it carries multiple textures as animation [sprite_frames](class_animatedsprite3d.md#class_AnimatedSprite3D_property_sprite_frames). Animations are created using a [SpriteFrames](class_spriteframes.md) resource, which allows you to import image files (or a folder containing said files) to provide the animation frames for the sprite. The [SpriteFrames](class_spriteframes.md) resource can be configured in the editor via the SpriteFrames bottom panel. + + + +## Tutorials + +- [2D Sprite animation (also applies to 3D)](../tutorials/2d/2d_sprite_animation.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[StringName](class_stringname.md)[animation](#class_AnimatedSprite3D_property_animation)`&"default"`
[String](class_string.md)[autoplay](#class_AnimatedSprite3D_property_autoplay)`""`
[int](class_int.md)[frame](#class_AnimatedSprite3D_property_frame)`0`
[float](class_float.md)[frame_progress](#class_AnimatedSprite3D_property_frame_progress)`0.0`
[float](class_float.md)[speed_scale](#class_AnimatedSprite3D_property_speed_scale)`1.0`
[SpriteFrames](class_spriteframes.md)[sprite_frames](#class_AnimatedSprite3D_property_sprite_frames)
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[get_playing_speed](#class_AnimatedSprite3D_method_get_playing_speed)\ (\ ) const
[bool](class_bool.md)[is_playing](#class_AnimatedSprite3D_method_is_playing)\ (\ ) const
`void`[pause](#class_AnimatedSprite3D_method_pause)\ (\ )
`void`[play](#class_AnimatedSprite3D_method_play)\ (\ name\: [StringName](class_stringname.md) = &"", custom_speed\: [float](class_float.md) = 1.0, from_end\: [bool](class_bool.md) = false\ )
`void`[play_backwards](#class_AnimatedSprite3D_method_play_backwards)\ (\ name\: [StringName](class_stringname.md) = &""\ )
`void`[set_frame_and_progress](#class_AnimatedSprite3D_method_set_frame_and_progress)\ (\ frame\: [int](class_int.md), progress\: [float](class_float.md)\ )
`void`[stop](#class_AnimatedSprite3D_method_stop)\ (\ )
+ +
+ + + +## Signals + + + + + +**animation_changed**\ (\ ) [🔗](#class_AnimatedSprite3D_signal_animation_changed) + +Emitted when [animation](class_animatedsprite3d.md#class_AnimatedSprite3D_property_animation) changes. + +
+ + + + + +**animation_finished**\ (\ ) [🔗](#class_AnimatedSprite3D_signal_animation_finished) + +Emitted when the animation reaches the end, or the start if it is played in reverse. When the animation finishes, it pauses the playback. + +\ **Note:** This signal is not emitted if an animation is looping. + +
+ + + + + +**animation_looped**\ (\ ) [🔗](#class_AnimatedSprite3D_signal_animation_looped) + +Emitted when the animation loops. + +
+ + + + + +**frame_changed**\ (\ ) [🔗](#class_AnimatedSprite3D_signal_frame_changed) + +Emitted when [frame](class_animatedsprite3d.md#class_AnimatedSprite3D_property_frame) changes. + +
+ + + + + +**sprite_frames_changed**\ (\ ) [🔗](#class_AnimatedSprite3D_signal_sprite_frames_changed) + +Emitted when [sprite_frames](class_animatedsprite3d.md#class_AnimatedSprite3D_property_sprite_frames) changes. + +
+ + + +## Property Descriptions + + + + + +[StringName](class_stringname.md) **animation** = `&"default"` [🔗](#class_AnimatedSprite3D_property_animation) + + + +- `void` **set_animation**\ (\ value\: [StringName](class_stringname.md)\ ) +- [StringName](class_stringname.md) **get_animation**\ (\ ) + +The current animation from the [sprite_frames](class_animatedsprite3d.md#class_AnimatedSprite3D_property_sprite_frames) resource. If this value is changed, the [frame](class_animatedsprite3d.md#class_AnimatedSprite3D_property_frame) counter and the [frame_progress](class_animatedsprite3d.md#class_AnimatedSprite3D_property_frame_progress) are reset. + +
+ + + + + +[String](class_string.md) **autoplay** = `""` [🔗](#class_AnimatedSprite3D_property_autoplay) + + + +- `void` **set_autoplay**\ (\ value\: [String](class_string.md)\ ) +- [String](class_string.md) **get_autoplay**\ (\ ) + +The key of the animation to play when the scene loads. + +
+ + + + + +[int](class_int.md) **frame** = `0` [🔗](#class_AnimatedSprite3D_property_frame) + + + +- `void` **set_frame**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_frame**\ (\ ) + +The displayed animation frame's index. Setting this property also resets [frame_progress](class_animatedsprite3d.md#class_AnimatedSprite3D_property_frame_progress). If this is not desired, use [set_frame_and_progress()](class_animatedsprite3d.md#class_AnimatedSprite3D_method_set_frame_and_progress). + +
+ + + + + +[float](class_float.md) **frame_progress** = `0.0` [🔗](#class_AnimatedSprite3D_property_frame_progress) + + + +- `void` **set_frame_progress**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_frame_progress**\ (\ ) + +The progress value between ``0.0`` and ``1.0`` until the current frame transitions to the next frame. If the animation is playing backwards, the value transitions from ``1.0`` to ``0.0``. + +
+ + + + + +[float](class_float.md) **speed_scale** = `1.0` [🔗](#class_AnimatedSprite3D_property_speed_scale) + + + +- `void` **set_speed_scale**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_speed_scale**\ (\ ) + +The speed scaling ratio. For example, if this value is ``1``, then the animation plays at normal speed. If it's ``0.5``, then it plays at half speed. If it's ``2``, then it plays at double speed. + +If set to a negative value, the animation is played in reverse. If set to ``0``, the animation will not advance. + +
+ + + + + +[SpriteFrames](class_spriteframes.md) **sprite_frames** [🔗](#class_AnimatedSprite3D_property_sprite_frames) + + + +- `void` **set_sprite_frames**\ (\ value\: [SpriteFrames](class_spriteframes.md)\ ) +- [SpriteFrames](class_spriteframes.md) **get_sprite_frames**\ (\ ) + +The [SpriteFrames](class_spriteframes.md) resource containing the animation(s). Allows you the option to load, edit, clear, make unique and save the states of the [SpriteFrames](class_spriteframes.md) resource. + +
+ + + +## Method Descriptions + + + + + +[float](class_float.md) **get_playing_speed**\ (\ ) const [🔗](#class_AnimatedSprite3D_method_get_playing_speed) + +Returns the actual playing speed of current animation or ``0`` if not playing. This speed is the [speed_scale](class_animatedsprite3d.md#class_AnimatedSprite3D_property_speed_scale) property multiplied by ``custom_speed`` argument specified when calling the [play()](class_animatedsprite3d.md#class_AnimatedSprite3D_method_play) method. + +Returns a negative value if the current animation is playing backwards. + +
+ + + + + +[bool](class_bool.md) **is_playing**\ (\ ) const [🔗](#class_AnimatedSprite3D_method_is_playing) + +Returns ``true`` if an animation is currently playing (even if [speed_scale](class_animatedsprite3d.md#class_AnimatedSprite3D_property_speed_scale) and/or ``custom_speed`` are ``0``). + +
+ + + + + +`void` **pause**\ (\ ) [🔗](#class_AnimatedSprite3D_method_pause) + +Pauses the currently playing animation. The [frame](class_animatedsprite3d.md#class_AnimatedSprite3D_property_frame) and [frame_progress](class_animatedsprite3d.md#class_AnimatedSprite3D_property_frame_progress) will be kept and calling [play()](class_animatedsprite3d.md#class_AnimatedSprite3D_method_play) or [play_backwards()](class_animatedsprite3d.md#class_AnimatedSprite3D_method_play_backwards) without arguments will resume the animation from the current playback position. + +See also [stop()](class_animatedsprite3d.md#class_AnimatedSprite3D_method_stop). + +
+ + + + + +`void` **play**\ (\ name\: [StringName](class_stringname.md) = &"", custom_speed\: [float](class_float.md) = 1.0, from_end\: [bool](class_bool.md) = false\ ) [🔗](#class_AnimatedSprite3D_method_play) + +Plays the animation with key `name`. If `custom_speed` is negative and `from_end` is ``true``, the animation will play backwards (which is equivalent to calling [play_backwards()](class_animatedsprite3d.md#class_AnimatedSprite3D_method_play_backwards)). + +If this method is called with that same animation `name`, or with no `name` parameter, the assigned animation will resume playing if it was paused. + +
+ + + + + +`void` **play_backwards**\ (\ name\: [StringName](class_stringname.md) = &""\ ) [🔗](#class_AnimatedSprite3D_method_play_backwards) + +Plays the animation with key `name` in reverse. + +This method is a shorthand for [play()](class_animatedsprite3d.md#class_AnimatedSprite3D_method_play) with ``custom_speed = -1.0`` and ``from_end = true``, so see its description for more information. + +
+ + + + + +`void` **set_frame_and_progress**\ (\ frame\: [int](class_int.md), progress\: [float](class_float.md)\ ) [🔗](#class_AnimatedSprite3D_method_set_frame_and_progress) + +Sets [frame](class_animatedsprite3d.md#class_AnimatedSprite3D_property_frame) and [frame_progress](class_animatedsprite3d.md#class_AnimatedSprite3D_property_frame_progress) to the given values. Unlike setting [frame](class_animatedsprite3d.md#class_AnimatedSprite3D_property_frame), this method does not reset the [frame_progress](class_animatedsprite3d.md#class_AnimatedSprite3D_property_frame_progress) to ``0.0`` implicitly. + +\ **Example:** Change the animation while keeping the same [frame](class_animatedsprite3d.md#class_AnimatedSprite3D_property_frame) and [frame_progress](class_animatedsprite3d.md#class_AnimatedSprite3D_property_frame_progress): + + + + +```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) +``` + + + +
+ + + + + +`void` **stop**\ (\ ) [🔗](#class_AnimatedSprite3D_method_stop) + +Stops the currently playing animation. The animation position is reset to ``0`` and the ``custom_speed`` is reset to ``1.0``. See also [pause()](class_animatedsprite3d.md#class_AnimatedSprite3D_method_pause). + diff --git a/docs/Classes/class_animatedtexture.md b/docs/Classes/class_animatedtexture.md new file mode 100644 index 00000000..e85e5d94 --- /dev/null +++ b/docs/Classes/class_animatedtexture.md @@ -0,0 +1,280 @@ + + + + + + + + + +# AnimatedTexture + +**Deprecated:** This class does not work properly in current versions and may be removed in the future. There is currently no equivalent workaround. + +**Inherits:** [Texture2D](class_texture2d.md) **<** [Texture](class_texture.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Proxy texture for simple frame-based animations. + + + +## 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](class_animationplayer.md) or [AnimatedSprite2D](class_animatedsprite2d.md), it isn't a [Node](class_node.md), but has the advantage of being usable anywhere a [Texture2D](class_texture2d.md) resource can be used, e.g. in a [TileSet](class_tileset.md). + +The playback of the animation is controlled by the [speed_scale](class_animatedtexture.md#class_AnimatedTexture_property_speed_scale) property, as well as each frame's duration (see [set_frame_duration()](class_animatedtexture.md#class_AnimatedTexture_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. + +\ **Note:** AnimatedTexture doesn't support using [AtlasTexture](class_atlastexture.md)\ s. Each frame needs to be a separate [Texture2D](class_texture2d.md). + +\ **Warning:** The current implementation is not efficient for the modern renderers. + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[int](class_int.md)[current_frame](#class_AnimatedTexture_property_current_frame)
[int](class_int.md)[frames](#class_AnimatedTexture_property_frames)`1`
[bool](class_bool.md)[one_shot](#class_AnimatedTexture_property_one_shot)`false`
[bool](class_bool.md)[pause](#class_AnimatedTexture_property_pause)`false`
[bool](class_bool.md)resource_local_to_scene`false` (overrides [Resource.resource_local_to_scene](class_resource.md#class_Resource_property_resource_local_to_scene))
[float](class_float.md)[speed_scale](#class_AnimatedTexture_property_speed_scale)`1.0`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[AnimatedTexture](class_animatedtexture.md)[create_from_image_frames](#class_AnimatedTexture_method_create_from_image_frames)\ (\ image_frames\: [ImageFrames](class_imageframes.md)\ ) static
[float](class_float.md)[get_frame_duration](#class_AnimatedTexture_method_get_frame_duration)\ (\ frame\: [int](class_int.md)\ ) const
[Texture2D](class_texture2d.md)[get_frame_texture](#class_AnimatedTexture_method_get_frame_texture)\ (\ frame\: [int](class_int.md)\ ) const
[ImageFrames](class_imageframes.md)[make_image_frames](#class_AnimatedTexture_method_make_image_frames)\ (\ ) const
`void`[set_frame_duration](#class_AnimatedTexture_method_set_frame_duration)\ (\ frame\: [int](class_int.md), duration\: [float](class_float.md)\ )
`void`[set_frame_texture](#class_AnimatedTexture_method_set_frame_texture)\ (\ frame\: [int](class_int.md), texture\: [Texture2D](class_texture2d.md)\ )
`void`[set_from_image_frames](#class_AnimatedTexture_method_set_from_image_frames)\ (\ image_frames\: [ImageFrames](class_imageframes.md)\ )
+ +
+ + + +## Constants + + + + + +**MAX_FRAMES** = `256` [🔗](#class_AnimatedTexture_constant_MAX_FRAMES) + +The maximum number of frames supported by **AnimatedTexture**. If you need more frames in your animation, use [AnimationPlayer](class_animationplayer.md) or [AnimatedSprite2D](class_animatedsprite2d.md). + +
+ + + +## Property Descriptions + + + + + +[int](class_int.md) **current_frame** [🔗](#class_AnimatedTexture_property_current_frame) + + + +- `void` **set_current_frame**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **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. + +
+ + + + + +[int](class_int.md) **frames** = `1` [🔗](#class_AnimatedTexture_property_frames) + + + +- `void` **set_frames**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_frames**\ (\ ) + +Number of frames to use in the animation. While you can create the frames independently with [set_frame_texture()](class_animatedtexture.md#class_AnimatedTexture_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 [MAX_FRAMES](class_animatedtexture.md#class_AnimatedTexture_constant_MAX_FRAMES). + +
+ + + + + +[bool](class_bool.md) **one_shot** = `false` [🔗](#class_AnimatedTexture_property_one_shot) + + + +- `void` **set_one_shot**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_one_shot**\ (\ ) + +If ``true``, 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 [pause](class_animatedtexture.md#class_AnimatedTexture_property_pause) to ``true``. + +
+ + + + + +[bool](class_bool.md) **pause** = `false` [🔗](#class_AnimatedTexture_property_pause) + + + +- `void` **set_pause**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_pause**\ (\ ) + +If ``true``, the animation will pause where it currently is (i.e. at [current_frame](class_animatedtexture.md#class_AnimatedTexture_property_current_frame)). The animation will continue from where it was paused when changing this property to ``false``. + +
+ + + + + +[float](class_float.md) **speed_scale** = `1.0` [🔗](#class_AnimatedTexture_property_speed_scale) + + + +- `void` **set_speed_scale**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_speed_scale**\ (\ ) + +The animation speed is multiplied by this value. If set to a negative value, the animation is played in reverse. + +
+ + + +## Method Descriptions + + + + + +[AnimatedTexture](class_animatedtexture.md) **create_from_image_frames**\ (\ image_frames\: [ImageFrames](class_imageframes.md)\ ) static [🔗](#class_AnimatedTexture_method_create_from_image_frames) + +Creates a new **AnimatedTexture** and initializes it by allocating and setting the data from an [ImageFrames](class_imageframes.md). This function will ignore all frames beyond [MAX_FRAMES](class_animatedtexture.md#class_AnimatedTexture_constant_MAX_FRAMES) - 1. + +
+ + + + + +[float](class_float.md) **get_frame_duration**\ (\ frame\: [int](class_int.md)\ ) const [🔗](#class_AnimatedTexture_method_get_frame_duration) + +Returns the given `frame`'s duration, in seconds. + +
+ + + + + +[Texture2D](class_texture2d.md) **get_frame_texture**\ (\ frame\: [int](class_int.md)\ ) const [🔗](#class_AnimatedTexture_method_get_frame_texture) + +Returns the given frame's [Texture2D](class_texture2d.md). + +
+ + + + + +[ImageFrames](class_imageframes.md) **make_image_frames**\ (\ ) const [🔗](#class_AnimatedTexture_method_make_image_frames) + +Creates a new [ImageFrames](class_imageframes.md) object from contents. + +
+ + + + + +`void` **set_frame_duration**\ (\ frame\: [int](class_int.md), duration\: [float](class_float.md)\ ) [🔗](#class_AnimatedTexture_method_set_frame_duration) + +Sets the duration of any given `frame`. The final duration is affected by the [speed_scale](class_animatedtexture.md#class_AnimatedTexture_property_speed_scale). If set to ``0``, the frame is skipped during playback. + +
+ + + + + +`void` **set_frame_texture**\ (\ frame\: [int](class_int.md), texture\: [Texture2D](class_texture2d.md)\ ) [🔗](#class_AnimatedTexture_method_set_frame_texture) + +Assigns a [Texture2D](class_texture2d.md) 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 [frames](class_animatedtexture.md#class_AnimatedTexture_property_frames) - 1. + +You can define any number of textures up to [MAX_FRAMES](class_animatedtexture.md#class_AnimatedTexture_constant_MAX_FRAMES), but keep in mind that only frames from 0 to [frames](class_animatedtexture.md#class_AnimatedTexture_property_frames) - 1 will be part of the animation. + +
+ + + + + +`void` **set_from_image_frames**\ (\ image_frames\: [ImageFrames](class_imageframes.md)\ ) [🔗](#class_AnimatedTexture_method_set_from_image_frames) + +Replaces the texture's data with a new [ImageFrames](class_imageframes.md). This function will ignore all frames beyond [MAX_FRAMES](class_animatedtexture.md#class_AnimatedTexture_constant_MAX_FRAMES) - 1. + diff --git a/docs/Classes/class_animation.md b/docs/Classes/class_animation.md new file mode 100644 index 00000000..66d43661 --- /dev/null +++ b/docs/Classes/class_animation.md @@ -0,0 +1,1493 @@ + + + + + + + + + +# Animation + +**Inherits:** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Holds data that can be used to animate anything in the engine. + + + +## 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. + + + + +```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 +``` + +```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; +``` + + + +Animations are just data containers, and must be added to nodes such as an [AnimationPlayer](class_animationplayer.md) to be played back. Animation tracks have different types, each with its own set of dedicated methods. Check [TrackType](class_animation.md#enum_Animation_TrackType) to see available types. + +\ **Note:** For 3D position/rotation/scale, using the dedicated [TYPE_POSITION_3D](class_animation.md#class_Animation_constant_TYPE_POSITION_3D), [TYPE_ROTATION_3D](class_animation.md#class_Animation_constant_TYPE_ROTATION_3D) and [TYPE_SCALE_3D](class_animation.md#class_Animation_constant_TYPE_SCALE_3D) track types instead of [TYPE_VALUE](class_animation.md#class_Animation_constant_TYPE_VALUE) is recommended for performance reasons. + + + +## Tutorials + +- [Animation documentation index](../tutorials/animation/index.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[capture_included](#class_Animation_property_capture_included)`false`
[float](class_float.md)[length](#class_Animation_property_length)`1.0`
[LoopMode](class_animation.md#enum_Animation_LoopMode)[loop_mode](#class_Animation_property_loop_mode)`0`
[float](class_float.md)[step](#class_Animation_property_step)`0.033333335`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
`void`[add_marker](#class_Animation_method_add_marker)\ (\ name\: [StringName](class_stringname.md), time\: [float](class_float.md)\ )
[int](class_int.md)[add_track](#class_Animation_method_add_track)\ (\ type\: [TrackType](class_animation.md#enum_Animation_TrackType), at_position\: [int](class_int.md) = -1\ )
[StringName](class_stringname.md)[animation_track_get_key_animation](#class_Animation_method_animation_track_get_key_animation)\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md)\ ) const
[int](class_int.md)[animation_track_insert_key](#class_Animation_method_animation_track_insert_key)\ (\ track_idx\: [int](class_int.md), time\: [float](class_float.md), animation\: [StringName](class_stringname.md)\ )
`void`[animation_track_set_key_animation](#class_Animation_method_animation_track_set_key_animation)\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md), animation\: [StringName](class_stringname.md)\ )
[float](class_float.md)[audio_track_get_key_end_offset](#class_Animation_method_audio_track_get_key_end_offset)\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md)\ ) const
[float](class_float.md)[audio_track_get_key_start_offset](#class_Animation_method_audio_track_get_key_start_offset)\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md)\ ) const
[Resource](class_resource.md)[audio_track_get_key_stream](#class_Animation_method_audio_track_get_key_stream)\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md)\ ) const
[int](class_int.md)[audio_track_insert_key](#class_Animation_method_audio_track_insert_key)\ (\ track_idx\: [int](class_int.md), time\: [float](class_float.md), stream\: [Resource](class_resource.md), start_offset\: [float](class_float.md) = 0, end_offset\: [float](class_float.md) = 0\ )
[bool](class_bool.md)[audio_track_is_use_blend](#class_Animation_method_audio_track_is_use_blend)\ (\ track_idx\: [int](class_int.md)\ ) const
`void`[audio_track_set_key_end_offset](#class_Animation_method_audio_track_set_key_end_offset)\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md), offset\: [float](class_float.md)\ )
`void`[audio_track_set_key_start_offset](#class_Animation_method_audio_track_set_key_start_offset)\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md), offset\: [float](class_float.md)\ )
`void`[audio_track_set_key_stream](#class_Animation_method_audio_track_set_key_stream)\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md), stream\: [Resource](class_resource.md)\ )
`void`[audio_track_set_use_blend](#class_Animation_method_audio_track_set_use_blend)\ (\ track_idx\: [int](class_int.md), enable\: [bool](class_bool.md)\ )
[Vector2](class_vector2.md)[bezier_track_get_key_in_handle](#class_Animation_method_bezier_track_get_key_in_handle)\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md)\ ) const
[Vector2](class_vector2.md)[bezier_track_get_key_out_handle](#class_Animation_method_bezier_track_get_key_out_handle)\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md)\ ) const
[float](class_float.md)[bezier_track_get_key_value](#class_Animation_method_bezier_track_get_key_value)\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md)\ ) const
[int](class_int.md)[bezier_track_insert_key](#class_Animation_method_bezier_track_insert_key)\ (\ track_idx\: [int](class_int.md), time\: [float](class_float.md), value\: [float](class_float.md), in_handle\: [Vector2](class_vector2.md) = Vector2(0, 0), out_handle\: [Vector2](class_vector2.md) = Vector2(0, 0)\ )
[float](class_float.md)[bezier_track_interpolate](#class_Animation_method_bezier_track_interpolate)\ (\ track_idx\: [int](class_int.md), time\: [float](class_float.md)\ ) const
`void`[bezier_track_set_key_in_handle](#class_Animation_method_bezier_track_set_key_in_handle)\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md), in_handle\: [Vector2](class_vector2.md), balanced_value_time_ratio\: [float](class_float.md) = 1.0\ )
`void`[bezier_track_set_key_out_handle](#class_Animation_method_bezier_track_set_key_out_handle)\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md), out_handle\: [Vector2](class_vector2.md), balanced_value_time_ratio\: [float](class_float.md) = 1.0\ )
`void`[bezier_track_set_key_value](#class_Animation_method_bezier_track_set_key_value)\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md), value\: [float](class_float.md)\ )
[int](class_int.md)[blend_shape_track_insert_key](#class_Animation_method_blend_shape_track_insert_key)\ (\ track_idx\: [int](class_int.md), time\: [float](class_float.md), amount\: [float](class_float.md)\ )
[float](class_float.md)[blend_shape_track_interpolate](#class_Animation_method_blend_shape_track_interpolate)\ (\ track_idx\: [int](class_int.md), time_sec\: [float](class_float.md), backward\: [bool](class_bool.md) = false\ ) const
`void`[clear](#class_Animation_method_clear)\ (\ )
`void`[compress](#class_Animation_method_compress)\ (\ page_size\: [int](class_int.md) = 8192, fps\: [int](class_int.md) = 120, split_tolerance\: [float](class_float.md) = 4.0\ )
`void`[copy_track](#class_Animation_method_copy_track)\ (\ track_idx\: [int](class_int.md), to_animation\: [Animation](class_animation.md)\ )
[int](class_int.md)[find_track](#class_Animation_method_find_track)\ (\ path\: [NodePath](class_nodepath.md), type\: [TrackType](class_animation.md#enum_Animation_TrackType)\ ) const
[StringName](class_stringname.md)[get_marker_at_time](#class_Animation_method_get_marker_at_time)\ (\ time\: [float](class_float.md)\ ) const
[Color](class_color.md)[get_marker_color](#class_Animation_method_get_marker_color)\ (\ name\: [StringName](class_stringname.md)\ ) const
[PackedStringArray](class_packedstringarray.md)[get_marker_names](#class_Animation_method_get_marker_names)\ (\ ) const
[float](class_float.md)[get_marker_time](#class_Animation_method_get_marker_time)\ (\ name\: [StringName](class_stringname.md)\ ) const
[StringName](class_stringname.md)[get_next_marker](#class_Animation_method_get_next_marker)\ (\ time\: [float](class_float.md)\ ) const
[StringName](class_stringname.md)[get_prev_marker](#class_Animation_method_get_prev_marker)\ (\ time\: [float](class_float.md)\ ) const
[int](class_int.md)[get_track_count](#class_Animation_method_get_track_count)\ (\ ) const
[bool](class_bool.md)[has_marker](#class_Animation_method_has_marker)\ (\ name\: [StringName](class_stringname.md)\ ) const
[StringName](class_stringname.md)[method_track_get_name](#class_Animation_method_method_track_get_name)\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md)\ ) const
[Array](class_array.md)[method_track_get_params](#class_Animation_method_method_track_get_params)\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md)\ ) const
`void`[optimize](#class_Animation_method_optimize)\ (\ allowed_velocity_err\: [float](class_float.md) = 0.01, allowed_angular_err\: [float](class_float.md) = 0.01, precision\: [int](class_int.md) = 3\ )
[int](class_int.md)[position_track_insert_key](#class_Animation_method_position_track_insert_key)\ (\ track_idx\: [int](class_int.md), time\: [float](class_float.md), position\: [Vector3](class_vector3.md)\ )
[Vector3](class_vector3.md)[position_track_interpolate](#class_Animation_method_position_track_interpolate)\ (\ track_idx\: [int](class_int.md), time_sec\: [float](class_float.md), backward\: [bool](class_bool.md) = false\ ) const
`void`[remove_marker](#class_Animation_method_remove_marker)\ (\ name\: [StringName](class_stringname.md)\ )
`void`[remove_track](#class_Animation_method_remove_track)\ (\ track_idx\: [int](class_int.md)\ )
[int](class_int.md)[rotation_track_insert_key](#class_Animation_method_rotation_track_insert_key)\ (\ track_idx\: [int](class_int.md), time\: [float](class_float.md), rotation\: [Quaternion](class_quaternion.md)\ )
[Quaternion](class_quaternion.md)[rotation_track_interpolate](#class_Animation_method_rotation_track_interpolate)\ (\ track_idx\: [int](class_int.md), time_sec\: [float](class_float.md), backward\: [bool](class_bool.md) = false\ ) const
[int](class_int.md)[scale_track_insert_key](#class_Animation_method_scale_track_insert_key)\ (\ track_idx\: [int](class_int.md), time\: [float](class_float.md), scale\: [Vector3](class_vector3.md)\ )
[Vector3](class_vector3.md)[scale_track_interpolate](#class_Animation_method_scale_track_interpolate)\ (\ track_idx\: [int](class_int.md), time_sec\: [float](class_float.md), backward\: [bool](class_bool.md) = false\ ) const
`void`[set_marker_color](#class_Animation_method_set_marker_color)\ (\ name\: [StringName](class_stringname.md), color\: [Color](class_color.md)\ )
[int](class_int.md)[track_find_key](#class_Animation_method_track_find_key)\ (\ track_idx\: [int](class_int.md), time\: [float](class_float.md), find_mode\: [FindMode](class_animation.md#enum_Animation_FindMode) = 0, limit\: [bool](class_bool.md) = false, backward\: [bool](class_bool.md) = false\ ) const
[bool](class_bool.md)[track_get_interpolation_loop_wrap](#class_Animation_method_track_get_interpolation_loop_wrap)\ (\ track_idx\: [int](class_int.md)\ ) const
[InterpolationType](class_animation.md#enum_Animation_InterpolationType)[track_get_interpolation_type](#class_Animation_method_track_get_interpolation_type)\ (\ track_idx\: [int](class_int.md)\ ) const
[int](class_int.md)[track_get_key_count](#class_Animation_method_track_get_key_count)\ (\ track_idx\: [int](class_int.md)\ ) const
[float](class_float.md)[track_get_key_time](#class_Animation_method_track_get_key_time)\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md)\ ) const
[float](class_float.md)[track_get_key_transition](#class_Animation_method_track_get_key_transition)\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md)\ ) const
[Variant](class_variant.md)[track_get_key_value](#class_Animation_method_track_get_key_value)\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md)\ ) const
[NodePath](class_nodepath.md)[track_get_path](#class_Animation_method_track_get_path)\ (\ track_idx\: [int](class_int.md)\ ) const
[TrackType](class_animation.md#enum_Animation_TrackType)[track_get_type](#class_Animation_method_track_get_type)\ (\ track_idx\: [int](class_int.md)\ ) const
[int](class_int.md)[track_insert_key](#class_Animation_method_track_insert_key)\ (\ track_idx\: [int](class_int.md), time\: [float](class_float.md), key\: [Variant](class_variant.md), transition\: [float](class_float.md) = 1\ )
[bool](class_bool.md)[track_is_compressed](#class_Animation_method_track_is_compressed)\ (\ track_idx\: [int](class_int.md)\ ) const
[bool](class_bool.md)[track_is_enabled](#class_Animation_method_track_is_enabled)\ (\ track_idx\: [int](class_int.md)\ ) const
[bool](class_bool.md)[track_is_imported](#class_Animation_method_track_is_imported)\ (\ track_idx\: [int](class_int.md)\ ) const
`void`[track_move_down](#class_Animation_method_track_move_down)\ (\ track_idx\: [int](class_int.md)\ )
`void`[track_move_to](#class_Animation_method_track_move_to)\ (\ track_idx\: [int](class_int.md), to_idx\: [int](class_int.md)\ )
`void`[track_move_up](#class_Animation_method_track_move_up)\ (\ track_idx\: [int](class_int.md)\ )
`void`[track_remove_key](#class_Animation_method_track_remove_key)\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md)\ )
`void`[track_remove_key_at_time](#class_Animation_method_track_remove_key_at_time)\ (\ track_idx\: [int](class_int.md), time\: [float](class_float.md)\ )
`void`[track_set_enabled](#class_Animation_method_track_set_enabled)\ (\ track_idx\: [int](class_int.md), enabled\: [bool](class_bool.md)\ )
`void`[track_set_imported](#class_Animation_method_track_set_imported)\ (\ track_idx\: [int](class_int.md), imported\: [bool](class_bool.md)\ )
`void`[track_set_interpolation_loop_wrap](#class_Animation_method_track_set_interpolation_loop_wrap)\ (\ track_idx\: [int](class_int.md), interpolation\: [bool](class_bool.md)\ )
`void`[track_set_interpolation_type](#class_Animation_method_track_set_interpolation_type)\ (\ track_idx\: [int](class_int.md), interpolation\: [InterpolationType](class_animation.md#enum_Animation_InterpolationType)\ )
`void`[track_set_key_time](#class_Animation_method_track_set_key_time)\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md), time\: [float](class_float.md)\ )
`void`[track_set_key_transition](#class_Animation_method_track_set_key_transition)\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md), transition\: [float](class_float.md)\ )
`void`[track_set_key_value](#class_Animation_method_track_set_key_value)\ (\ track_idx\: [int](class_int.md), key\: [int](class_int.md), value\: [Variant](class_variant.md)\ )
`void`[track_set_path](#class_Animation_method_track_set_path)\ (\ track_idx\: [int](class_int.md), path\: [NodePath](class_nodepath.md)\ )
`void`[track_swap](#class_Animation_method_track_swap)\ (\ track_idx\: [int](class_int.md), with_idx\: [int](class_int.md)\ )
[UpdateMode](class_animation.md#enum_Animation_UpdateMode)[value_track_get_update_mode](#class_Animation_method_value_track_get_update_mode)\ (\ track_idx\: [int](class_int.md)\ ) const
[Variant](class_variant.md)[value_track_interpolate](#class_Animation_method_value_track_interpolate)\ (\ track_idx\: [int](class_int.md), time_sec\: [float](class_float.md), backward\: [bool](class_bool.md) = false\ ) const
`void`[value_track_set_update_mode](#class_Animation_method_value_track_set_update_mode)\ (\ track_idx\: [int](class_int.md), mode\: [UpdateMode](class_animation.md#enum_Animation_UpdateMode)\ )
+ +
+ + + +## Enumerations + + + + + +enum **TrackType**: [🔗](#enum_Animation_TrackType) + + + + + +[TrackType](class_animation.md#enum_Animation_TrackType) **TYPE_VALUE** = `0` + +Value tracks set values in node properties, but only those which can be interpolated. For 3D position/rotation/scale, using the dedicated [TYPE_POSITION_3D](class_animation.md#class_Animation_constant_TYPE_POSITION_3D), [TYPE_ROTATION_3D](class_animation.md#class_Animation_constant_TYPE_ROTATION_3D) and [TYPE_SCALE_3D](class_animation.md#class_Animation_constant_TYPE_SCALE_3D) track types instead of [TYPE_VALUE](class_animation.md#class_Animation_constant_TYPE_VALUE) is recommended for performance reasons. + + + +[TrackType](class_animation.md#enum_Animation_TrackType) **TYPE_POSITION_3D** = `1` + +3D position track (values are stored in [Vector3](class_vector3.md)\ s). + + + +[TrackType](class_animation.md#enum_Animation_TrackType) **TYPE_ROTATION_3D** = `2` + +3D rotation track (values are stored in [Quaternion](class_quaternion.md)\ s). + + + +[TrackType](class_animation.md#enum_Animation_TrackType) **TYPE_SCALE_3D** = `3` + +3D scale track (values are stored in [Vector3](class_vector3.md)\ s). + + + +[TrackType](class_animation.md#enum_Animation_TrackType) **TYPE_BLEND_SHAPE** = `4` + +Blend shape track. + + + +[TrackType](class_animation.md#enum_Animation_TrackType) **TYPE_METHOD** = `5` + +Method tracks call functions with given arguments per key. + + + +[TrackType](class_animation.md#enum_Animation_TrackType) **TYPE_BEZIER** = `6` + +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](class_color.md)). + + + +[TrackType](class_animation.md#enum_Animation_TrackType) **TYPE_AUDIO** = `7` + +Audio tracks are used to play an audio stream with either type of [AudioStreamPlayer](class_audiostreamplayer.md). The stream can be trimmed and previewed in the animation. + + + +[TrackType](class_animation.md#enum_Animation_TrackType) **TYPE_ANIMATION** = `8` + +Animation tracks play animations in other [AnimationPlayer](class_animationplayer.md) nodes.
+ + + + + +enum **InterpolationType**: [🔗](#enum_Animation_InterpolationType) + + + + + +[InterpolationType](class_animation.md#enum_Animation_InterpolationType) **INTERPOLATION_NEAREST** = `0` + +No interpolation (nearest value). + + + +[InterpolationType](class_animation.md#enum_Animation_InterpolationType) **INTERPOLATION_LINEAR** = `1` + +Linear interpolation. + + + +[InterpolationType](class_animation.md#enum_Animation_InterpolationType) **INTERPOLATION_CUBIC** = `2` + +Cubic interpolation. This looks smoother than linear interpolation, but is more expensive to interpolate. Stick to [INTERPOLATION_LINEAR](class_animation.md#class_Animation_constant_INTERPOLATION_LINEAR) for complex 3D animations imported from external software, even if it requires using a higher animation framerate in return. + + + +[InterpolationType](class_animation.md#enum_Animation_InterpolationType) **INTERPOLATION_LINEAR_ANGLE** = `3` + +Linear interpolation with shortest path rotation. + +\ **Note:** The result value is always normalized and may not match the key value. + + + +[InterpolationType](class_animation.md#enum_Animation_InterpolationType) **INTERPOLATION_CUBIC_ANGLE** = `4` + +Cubic interpolation with shortest path rotation. + +\ **Note:** The result value is always normalized and may not match the key value.
+ + + + + +enum **UpdateMode**: [🔗](#enum_Animation_UpdateMode) + + + + + +[UpdateMode](class_animation.md#enum_Animation_UpdateMode) **UPDATE_CONTINUOUS** = `0` + +Update between keyframes and hold the value. + + + +[UpdateMode](class_animation.md#enum_Animation_UpdateMode) **UPDATE_DISCRETE** = `1` + +Update at the keyframes. + + + +[UpdateMode](class_animation.md#enum_Animation_UpdateMode) **UPDATE_CAPTURE** = `2` + +Same as [UPDATE_CONTINUOUS](class_animation.md#class_Animation_constant_UPDATE_CONTINUOUS) but works as a flag to capture the value of the current object and perform interpolation in some methods. See also [AnimationMixer.capture()](class_animationmixer.md#class_AnimationMixer_method_capture), [AnimationPlayer.playback_auto_capture](class_animationplayer.md#class_AnimationPlayer_property_playback_auto_capture), and [AnimationPlayer.play_with_capture()](class_animationplayer.md#class_AnimationPlayer_method_play_with_capture).
+ + + + + +enum **LoopMode**: [🔗](#enum_Animation_LoopMode) + + + + + +[LoopMode](class_animation.md#enum_Animation_LoopMode) **LOOP_NONE** = `0` + +At both ends of the animation, the animation will stop playing. + + + +[LoopMode](class_animation.md#enum_Animation_LoopMode) **LOOP_LINEAR** = `1` + +At both ends of the animation, the animation will be repeated without changing the playback direction. + + + +[LoopMode](class_animation.md#enum_Animation_LoopMode) **LOOP_PINGPONG** = `2` + +Repeats playback and reverse playback at both ends of the animation.
+ + + + + +enum **LoopedFlag**: [🔗](#enum_Animation_LoopedFlag) + + + + + +[LoopedFlag](class_animation.md#enum_Animation_LoopedFlag) **LOOPED_FLAG_NONE** = `0` + +This flag indicates that the animation proceeds without any looping. + + + +[LoopedFlag](class_animation.md#enum_Animation_LoopedFlag) **LOOPED_FLAG_END** = `1` + +This flag indicates that the animation has reached the end of the animation and just after loop processed. + + + +[LoopedFlag](class_animation.md#enum_Animation_LoopedFlag) **LOOPED_FLAG_START** = `2` + +This flag indicates that the animation has reached the start of the animation and just after loop processed.
+ + + + + +enum **FindMode**: [🔗](#enum_Animation_FindMode) + + + + + +[FindMode](class_animation.md#enum_Animation_FindMode) **FIND_MODE_NEAREST** = `0` + +Finds the nearest time key. + + + +[FindMode](class_animation.md#enum_Animation_FindMode) **FIND_MODE_APPROX** = `1` + +Finds only the key with approximating the time. + + + +[FindMode](class_animation.md#enum_Animation_FindMode) **FIND_MODE_EXACT** = `2` + +Finds only the key with matching the time.
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **capture_included** = `false` [🔗](#class_Animation_property_capture_included) + + + +- [bool](class_bool.md) **is_capture_included**\ (\ ) + +Returns ``true`` if the capture track is included. This is a cached readonly value for performance. + +
+ + + + + +[float](class_float.md) **length** = `1.0` [🔗](#class_Animation_property_length) + + + +- `void` **set_length**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_length**\ (\ ) + +The total length of the animation (in seconds). + +\ **Note:** Length is not delimited by the last key, as this one may be before or after the end to ensure correct interpolation and looping. + +
+ + + + + +[LoopMode](class_animation.md#enum_Animation_LoopMode) **loop_mode** = `0` [🔗](#class_Animation_property_loop_mode) + + + +- `void` **set_loop_mode**\ (\ value\: [LoopMode](class_animation.md#enum_Animation_LoopMode)\ ) +- [LoopMode](class_animation.md#enum_Animation_LoopMode) **get_loop_mode**\ (\ ) + +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. + +
+ + + + + +[float](class_float.md) **step** = `0.033333335` [🔗](#class_Animation_property_step) + + + +- `void` **set_step**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_step**\ (\ ) + +The animation step value. + +
+ + + +## Method Descriptions + + + + + +`void` **add_marker**\ (\ name\: [StringName](class_stringname.md), time\: [float](class_float.md)\ ) [🔗](#class_Animation_method_add_marker) + +Adds a marker to this Animation. + +
+ + + + + +[int](class_int.md) **add_track**\ (\ type\: [TrackType](class_animation.md#enum_Animation_TrackType), at_position\: [int](class_int.md) = -1\ ) [🔗](#class_Animation_method_add_track) + +Adds a track to the Animation. + +
+ + + + + +[StringName](class_stringname.md) **animation_track_get_key_animation**\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md)\ ) const [🔗](#class_Animation_method_animation_track_get_key_animation) + +Returns the animation name at the key identified by `key_idx`. The `track_idx` must be the index of an Animation Track. + +
+ + + + + +[int](class_int.md) **animation_track_insert_key**\ (\ track_idx\: [int](class_int.md), time\: [float](class_float.md), animation\: [StringName](class_stringname.md)\ ) [🔗](#class_Animation_method_animation_track_insert_key) + +Inserts a key with value `animation` at the given `time` (in seconds). The `track_idx` must be the index of an Animation Track. + +
+ + + + + +`void` **animation_track_set_key_animation**\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md), animation\: [StringName](class_stringname.md)\ ) [🔗](#class_Animation_method_animation_track_set_key_animation) + +Sets the key identified by `key_idx` to value `animation`. The `track_idx` must be the index of an Animation Track. + +
+ + + + + +[float](class_float.md) **audio_track_get_key_end_offset**\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md)\ ) const [🔗](#class_Animation_method_audio_track_get_key_end_offset) + +Returns the end offset of the key identified by `key_idx`. The `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. + +
+ + + + + +[float](class_float.md) **audio_track_get_key_start_offset**\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md)\ ) const [🔗](#class_Animation_method_audio_track_get_key_start_offset) + +Returns the start offset of the key identified by `key_idx`. The `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. + +
+ + + + + +[Resource](class_resource.md) **audio_track_get_key_stream**\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md)\ ) const [🔗](#class_Animation_method_audio_track_get_key_stream) + +Returns the audio stream of the key identified by `key_idx`. The `track_idx` must be the index of an Audio Track. + +
+ + + + + +[int](class_int.md) **audio_track_insert_key**\ (\ track_idx\: [int](class_int.md), time\: [float](class_float.md), stream\: [Resource](class_resource.md), start_offset\: [float](class_float.md) = 0, end_offset\: [float](class_float.md) = 0\ ) [🔗](#class_Animation_method_audio_track_insert_key) + +Inserts an Audio Track key at the given `time` in seconds. The `track_idx` must be the index of an Audio Track. + +\ `stream` is the [AudioStream](class_audiostream.md) resource to play. `start_offset` is the number of seconds cut off at the beginning of the audio stream, while `end_offset` is at the ending. + +
+ + + + + +[bool](class_bool.md) **audio_track_is_use_blend**\ (\ track_idx\: [int](class_int.md)\ ) const [🔗](#class_Animation_method_audio_track_is_use_blend) + +Returns ``true`` if the track at `track_idx` will be blended with other animations. + +
+ + + + + +`void` **audio_track_set_key_end_offset**\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md), offset\: [float](class_float.md)\ ) [🔗](#class_Animation_method_audio_track_set_key_end_offset) + +Sets the end offset of the key identified by `key_idx` to value `offset`. The `track_idx` must be the index of an Audio Track. + +
+ + + + + +`void` **audio_track_set_key_start_offset**\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md), offset\: [float](class_float.md)\ ) [🔗](#class_Animation_method_audio_track_set_key_start_offset) + +Sets the start offset of the key identified by `key_idx` to value `offset`. The `track_idx` must be the index of an Audio Track. + +
+ + + + + +`void` **audio_track_set_key_stream**\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md), stream\: [Resource](class_resource.md)\ ) [🔗](#class_Animation_method_audio_track_set_key_stream) + +Sets the stream of the key identified by `key_idx` to value `stream`. The `track_idx` must be the index of an Audio Track. + +
+ + + + + +`void` **audio_track_set_use_blend**\ (\ track_idx\: [int](class_int.md), enable\: [bool](class_bool.md)\ ) [🔗](#class_Animation_method_audio_track_set_use_blend) + +Sets whether the track will be blended with other animations. If ``true``, the audio playback volume changes depending on the blend value. + +
+ + + + + +[Vector2](class_vector2.md) **bezier_track_get_key_in_handle**\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md)\ ) const [🔗](#class_Animation_method_bezier_track_get_key_in_handle) + +Returns the in handle of the key identified by `key_idx`. The `track_idx` must be the index of a Bezier Track. + +
+ + + + + +[Vector2](class_vector2.md) **bezier_track_get_key_out_handle**\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md)\ ) const [🔗](#class_Animation_method_bezier_track_get_key_out_handle) + +Returns the out handle of the key identified by `key_idx`. The `track_idx` must be the index of a Bezier Track. + +
+ + + + + +[float](class_float.md) **bezier_track_get_key_value**\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md)\ ) const [🔗](#class_Animation_method_bezier_track_get_key_value) + +Returns the value of the key identified by `key_idx`. The `track_idx` must be the index of a Bezier Track. + +
+ + + + + +[int](class_int.md) **bezier_track_insert_key**\ (\ track_idx\: [int](class_int.md), time\: [float](class_float.md), value\: [float](class_float.md), in_handle\: [Vector2](class_vector2.md) = Vector2(0, 0), out_handle\: [Vector2](class_vector2.md) = Vector2(0, 0)\ ) [🔗](#class_Animation_method_bezier_track_insert_key) + +Inserts a Bezier Track key at the given `time` in seconds. The `track_idx` must be the index of a Bezier Track. + +\ `in_handle` is the left-side weight of the added Bezier curve point, `out_handle` is the right-side one, while `value` is the actual value at this point. + +
+ + + + + +[float](class_float.md) **bezier_track_interpolate**\ (\ track_idx\: [int](class_int.md), time\: [float](class_float.md)\ ) const [🔗](#class_Animation_method_bezier_track_interpolate) + +Returns the interpolated value at the given `time` (in seconds). The `track_idx` must be the index of a Bezier Track. + +
+ + + + + +`void` **bezier_track_set_key_in_handle**\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md), in_handle\: [Vector2](class_vector2.md), balanced_value_time_ratio\: [float](class_float.md) = 1.0\ ) [🔗](#class_Animation_method_bezier_track_set_key_in_handle) + +Sets the in handle of the key identified by `key_idx` to value `in_handle`. The `track_idx` must be the index of a Bezier Track. + +
+ + + + + +`void` **bezier_track_set_key_out_handle**\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md), out_handle\: [Vector2](class_vector2.md), balanced_value_time_ratio\: [float](class_float.md) = 1.0\ ) [🔗](#class_Animation_method_bezier_track_set_key_out_handle) + +Sets the out handle of the key identified by `key_idx` to value `out_handle`. The `track_idx` must be the index of a Bezier Track. + +
+ + + + + +`void` **bezier_track_set_key_value**\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md), value\: [float](class_float.md)\ ) [🔗](#class_Animation_method_bezier_track_set_key_value) + +Sets the value of the key identified by `key_idx` to the given value. The `track_idx` must be the index of a Bezier Track. + +
+ + + + + +[int](class_int.md) **blend_shape_track_insert_key**\ (\ track_idx\: [int](class_int.md), time\: [float](class_float.md), amount\: [float](class_float.md)\ ) [🔗](#class_Animation_method_blend_shape_track_insert_key) + +Inserts a key in a given blend shape track. Returns the key index. + +
+ + + + + +[float](class_float.md) **blend_shape_track_interpolate**\ (\ track_idx\: [int](class_int.md), time_sec\: [float](class_float.md), backward\: [bool](class_bool.md) = false\ ) const [🔗](#class_Animation_method_blend_shape_track_interpolate) + +Returns the interpolated blend shape value at the given time (in seconds). The `track_idx` must be the index of a blend shape track. + +
+ + + + + +`void` **clear**\ (\ ) [🔗](#class_Animation_method_clear) + +Clear the animation (clear all tracks and reset all). + +
+ + + + + +`void` **compress**\ (\ page_size\: [int](class_int.md) = 8192, fps\: [int](class_int.md) = 120, split_tolerance\: [float](class_float.md) = 4.0\ ) [🔗](#class_Animation_method_compress) + +Compress the animation and all its tracks in-place. This will make [track_is_compressed()](class_animation.md#class_Animation_method_track_is_compressed) return ``true`` 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. + +\ **Note:** Compressed tracks have various limitations (such as not being editable from the editor), so only use compressed animations if you actually need them. + +
+ + + + + +`void` **copy_track**\ (\ track_idx\: [int](class_int.md), to_animation\: [Animation](class_animation.md)\ ) [🔗](#class_Animation_method_copy_track) + +Adds a new track to `to_animation` that is a copy of the given track from this animation. + +
+ + + + + +[int](class_int.md) **find_track**\ (\ path\: [NodePath](class_nodepath.md), type\: [TrackType](class_animation.md#enum_Animation_TrackType)\ ) const [🔗](#class_Animation_method_find_track) + +Returns the index of the specified track. If the track is not found, return -1. + +
+ + + + + +[StringName](class_stringname.md) **get_marker_at_time**\ (\ time\: [float](class_float.md)\ ) const [🔗](#class_Animation_method_get_marker_at_time) + +Returns the name of the marker located at the given time. + +
+ + + + + +[Color](class_color.md) **get_marker_color**\ (\ name\: [StringName](class_stringname.md)\ ) const [🔗](#class_Animation_method_get_marker_color) + +Returns the given marker's color. + +
+ + + + + +[PackedStringArray](class_packedstringarray.md) **get_marker_names**\ (\ ) const [🔗](#class_Animation_method_get_marker_names) + +Returns every marker in this Animation, sorted ascending by time. + +
+ + + + + +[float](class_float.md) **get_marker_time**\ (\ name\: [StringName](class_stringname.md)\ ) const [🔗](#class_Animation_method_get_marker_time) + +Returns the given marker's time. + +
+ + + + + +[StringName](class_stringname.md) **get_next_marker**\ (\ time\: [float](class_float.md)\ ) const [🔗](#class_Animation_method_get_next_marker) + +Returns the closest marker that comes after the given time. If no such marker exists, an empty string is returned. + +
+ + + + + +[StringName](class_stringname.md) **get_prev_marker**\ (\ time\: [float](class_float.md)\ ) const [🔗](#class_Animation_method_get_prev_marker) + +Returns the closest marker that comes before the given time. If no such marker exists, an empty string is returned. + +
+ + + + + +[int](class_int.md) **get_track_count**\ (\ ) const [🔗](#class_Animation_method_get_track_count) + +Returns the amount of tracks in the animation. + +
+ + + + + +[bool](class_bool.md) **has_marker**\ (\ name\: [StringName](class_stringname.md)\ ) const [🔗](#class_Animation_method_has_marker) + +Returns ``true`` if this Animation contains a marker with the given name. + +
+ + + + + +[StringName](class_stringname.md) **method_track_get_name**\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md)\ ) const [🔗](#class_Animation_method_method_track_get_name) + +Returns the method name of a method track. + +
+ + + + + +[Array](class_array.md) **method_track_get_params**\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md)\ ) const [🔗](#class_Animation_method_method_track_get_params) + +Returns the arguments values to be called on a method track for a given key in a given track. + +
+ + + + + +`void` **optimize**\ (\ allowed_velocity_err\: [float](class_float.md) = 0.01, allowed_angular_err\: [float](class_float.md) = 0.01, precision\: [int](class_int.md) = 3\ ) [🔗](#class_Animation_method_optimize) + +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. + +
+ + + + + +[int](class_int.md) **position_track_insert_key**\ (\ track_idx\: [int](class_int.md), time\: [float](class_float.md), position\: [Vector3](class_vector3.md)\ ) [🔗](#class_Animation_method_position_track_insert_key) + +Inserts a key in a given 3D position track. Returns the key index. + +
+ + + + + +[Vector3](class_vector3.md) **position_track_interpolate**\ (\ track_idx\: [int](class_int.md), time_sec\: [float](class_float.md), backward\: [bool](class_bool.md) = false\ ) const [🔗](#class_Animation_method_position_track_interpolate) + +Returns the interpolated position value at the given time (in seconds). The `track_idx` must be the index of a 3D position track. + +
+ + + + + +`void` **remove_marker**\ (\ name\: [StringName](class_stringname.md)\ ) [🔗](#class_Animation_method_remove_marker) + +Removes the marker with the given name from this Animation. + +
+ + + + + +`void` **remove_track**\ (\ track_idx\: [int](class_int.md)\ ) [🔗](#class_Animation_method_remove_track) + +Removes a track by specifying the track index. + +
+ + + + + +[int](class_int.md) **rotation_track_insert_key**\ (\ track_idx\: [int](class_int.md), time\: [float](class_float.md), rotation\: [Quaternion](class_quaternion.md)\ ) [🔗](#class_Animation_method_rotation_track_insert_key) + +Inserts a key in a given 3D rotation track. Returns the key index. + +
+ + + + + +[Quaternion](class_quaternion.md) **rotation_track_interpolate**\ (\ track_idx\: [int](class_int.md), time_sec\: [float](class_float.md), backward\: [bool](class_bool.md) = false\ ) const [🔗](#class_Animation_method_rotation_track_interpolate) + +Returns the interpolated rotation value at the given time (in seconds). The `track_idx` must be the index of a 3D rotation track. + +
+ + + + + +[int](class_int.md) **scale_track_insert_key**\ (\ track_idx\: [int](class_int.md), time\: [float](class_float.md), scale\: [Vector3](class_vector3.md)\ ) [🔗](#class_Animation_method_scale_track_insert_key) + +Inserts a key in a given 3D scale track. Returns the key index. + +
+ + + + + +[Vector3](class_vector3.md) **scale_track_interpolate**\ (\ track_idx\: [int](class_int.md), time_sec\: [float](class_float.md), backward\: [bool](class_bool.md) = false\ ) const [🔗](#class_Animation_method_scale_track_interpolate) + +Returns the interpolated scale value at the given time (in seconds). The `track_idx` must be the index of a 3D scale track. + +
+ + + + + +`void` **set_marker_color**\ (\ name\: [StringName](class_stringname.md), color\: [Color](class_color.md)\ ) [🔗](#class_Animation_method_set_marker_color) + +Sets the given marker's color. + +
+ + + + + +[int](class_int.md) **track_find_key**\ (\ track_idx\: [int](class_int.md), time\: [float](class_float.md), find_mode\: [FindMode](class_animation.md#enum_Animation_FindMode) = 0, limit\: [bool](class_bool.md) = false, backward\: [bool](class_bool.md) = false\ ) const [🔗](#class_Animation_method_track_find_key) + +Finds the key index by time in a given track. Optionally, only find it if the approx/exact time is given. + +If `limit` is ``true``, it does not return keys outside the animation range. + +If `backward` is ``true``, the direction is reversed in methods that rely on one directional processing. + +For example, in case `find_mode` is [FIND_MODE_NEAREST](class_animation.md#class_Animation_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 `backward` is ``true``, the first key found is retrieved after the position. + +
+ + + + + +[bool](class_bool.md) **track_get_interpolation_loop_wrap**\ (\ track_idx\: [int](class_int.md)\ ) const [🔗](#class_Animation_method_track_get_interpolation_loop_wrap) + +Returns ``true`` if the track at `track_idx` wraps the interpolation loop. New tracks wrap the interpolation loop by default. + +
+ + + + + +[InterpolationType](class_animation.md#enum_Animation_InterpolationType) **track_get_interpolation_type**\ (\ track_idx\: [int](class_int.md)\ ) const [🔗](#class_Animation_method_track_get_interpolation_type) + +Returns the interpolation type of a given track. + +
+ + + + + +[int](class_int.md) **track_get_key_count**\ (\ track_idx\: [int](class_int.md)\ ) const [🔗](#class_Animation_method_track_get_key_count) + +Returns the number of keys in a given track. + +
+ + + + + +[float](class_float.md) **track_get_key_time**\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md)\ ) const [🔗](#class_Animation_method_track_get_key_time) + +Returns the time at which the key is located. + +
+ + + + + +[float](class_float.md) **track_get_key_transition**\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md)\ ) const [🔗](#class_Animation_method_track_get_key_transition) + +Returns the transition curve (easing) for a specific key (see the built-in math function [@GlobalScope.ease()](class_@globalscope.md#class_@GlobalScope_method_ease)). + +
+ + + + + +[Variant](class_variant.md) **track_get_key_value**\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md)\ ) const [🔗](#class_Animation_method_track_get_key_value) + +Returns the value of a given key in a given track. + +
+ + + + + +[NodePath](class_nodepath.md) **track_get_path**\ (\ track_idx\: [int](class_int.md)\ ) const [🔗](#class_Animation_method_track_get_path) + +Gets the path of a track. For more information on the path format, see [track_set_path()](class_animation.md#class_Animation_method_track_set_path). + +
+ + + + + +[TrackType](class_animation.md#enum_Animation_TrackType) **track_get_type**\ (\ track_idx\: [int](class_int.md)\ ) const [🔗](#class_Animation_method_track_get_type) + +Gets the type of a track. + +
+ + + + + +[int](class_int.md) **track_insert_key**\ (\ track_idx\: [int](class_int.md), time\: [float](class_float.md), key\: [Variant](class_variant.md), transition\: [float](class_float.md) = 1\ ) [🔗](#class_Animation_method_track_insert_key) + +Inserts a generic key in a given track. Returns the key index. + +
+ + + + + +[bool](class_bool.md) **track_is_compressed**\ (\ track_idx\: [int](class_int.md)\ ) const [🔗](#class_Animation_method_track_is_compressed) + +Returns ``true`` if the track is compressed, ``false`` otherwise. See also [compress()](class_animation.md#class_Animation_method_compress). + +
+ + + + + +[bool](class_bool.md) **track_is_enabled**\ (\ track_idx\: [int](class_int.md)\ ) const [🔗](#class_Animation_method_track_is_enabled) + +Returns ``true`` if the track at index `track_idx` is enabled. + +
+ + + + + +[bool](class_bool.md) **track_is_imported**\ (\ track_idx\: [int](class_int.md)\ ) const [🔗](#class_Animation_method_track_is_imported) + +Returns ``true`` if the given track is imported. Else, return ``false``. + +
+ + + + + +`void` **track_move_down**\ (\ track_idx\: [int](class_int.md)\ ) [🔗](#class_Animation_method_track_move_down) + +Moves a track down. + +
+ + + + + +`void` **track_move_to**\ (\ track_idx\: [int](class_int.md), to_idx\: [int](class_int.md)\ ) [🔗](#class_Animation_method_track_move_to) + +Changes the index position of track `track_idx` to the one defined in `to_idx`. + +
+ + + + + +`void` **track_move_up**\ (\ track_idx\: [int](class_int.md)\ ) [🔗](#class_Animation_method_track_move_up) + +Moves a track up. + +
+ + + + + +`void` **track_remove_key**\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md)\ ) [🔗](#class_Animation_method_track_remove_key) + +Removes a key by index in a given track. + +
+ + + + + +`void` **track_remove_key_at_time**\ (\ track_idx\: [int](class_int.md), time\: [float](class_float.md)\ ) [🔗](#class_Animation_method_track_remove_key_at_time) + +Removes a key at `time` in a given track. + +
+ + + + + +`void` **track_set_enabled**\ (\ track_idx\: [int](class_int.md), enabled\: [bool](class_bool.md)\ ) [🔗](#class_Animation_method_track_set_enabled) + +Enables/disables the given track. Tracks are enabled by default. + +
+ + + + + +`void` **track_set_imported**\ (\ track_idx\: [int](class_int.md), imported\: [bool](class_bool.md)\ ) [🔗](#class_Animation_method_track_set_imported) + +Sets the given track as imported or not. + +
+ + + + + +`void` **track_set_interpolation_loop_wrap**\ (\ track_idx\: [int](class_int.md), interpolation\: [bool](class_bool.md)\ ) [🔗](#class_Animation_method_track_set_interpolation_loop_wrap) + +If ``true``, the track at `track_idx` wraps the interpolation loop. + +
+ + + + + +`void` **track_set_interpolation_type**\ (\ track_idx\: [int](class_int.md), interpolation\: [InterpolationType](class_animation.md#enum_Animation_InterpolationType)\ ) [🔗](#class_Animation_method_track_set_interpolation_type) + +Sets the interpolation type of a given track. + +
+ + + + + +`void` **track_set_key_time**\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md), time\: [float](class_float.md)\ ) [🔗](#class_Animation_method_track_set_key_time) + +Sets the time of an existing key. + +
+ + + + + +`void` **track_set_key_transition**\ (\ track_idx\: [int](class_int.md), key_idx\: [int](class_int.md), transition\: [float](class_float.md)\ ) [🔗](#class_Animation_method_track_set_key_transition) + +Sets the transition curve (easing) for a specific key (see the built-in math function [@GlobalScope.ease()](class_@globalscope.md#class_@GlobalScope_method_ease)). + +
+ + + + + +`void` **track_set_key_value**\ (\ track_idx\: [int](class_int.md), key\: [int](class_int.md), value\: [Variant](class_variant.md)\ ) [🔗](#class_Animation_method_track_set_key_value) + +Sets the value of an existing key. + +
+ + + + + +`void` **track_set_path**\ (\ track_idx\: [int](class_int.md), path\: [NodePath](class_nodepath.md)\ ) [🔗](#class_Animation_method_track_set_path) + +Sets the path of a track. Paths must be valid scene-tree paths to a node and must be specified starting from the [AnimationMixer.root_node](class_animationmixer.md#class_AnimationMixer_property_root_node) that will reproduce the animation. Tracks that control properties or bones must append their name after the path, separated by ``":"``. + +For example, ``"character/skeleton:ankle"`` or ``"character/mesh:transform/local"``. + +
+ + + + + +`void` **track_swap**\ (\ track_idx\: [int](class_int.md), with_idx\: [int](class_int.md)\ ) [🔗](#class_Animation_method_track_swap) + +Swaps the track `track_idx`'s index position with the track `with_idx`. + +
+ + + + + +[UpdateMode](class_animation.md#enum_Animation_UpdateMode) **value_track_get_update_mode**\ (\ track_idx\: [int](class_int.md)\ ) const [🔗](#class_Animation_method_value_track_get_update_mode) + +Returns the update mode of a value track. + +
+ + + + + +[Variant](class_variant.md) **value_track_interpolate**\ (\ track_idx\: [int](class_int.md), time_sec\: [float](class_float.md), backward\: [bool](class_bool.md) = false\ ) const [🔗](#class_Animation_method_value_track_interpolate) + +Returns the interpolated value at the given time (in seconds). The `track_idx` must be the index of a value track. + +A `backward` mainly affects the direction of key retrieval of the track with [UPDATE_DISCRETE](class_animation.md#class_Animation_constant_UPDATE_DISCRETE) converted by [AnimationMixer.ANIMATION_CALLBACK_MODE_DISCRETE_FORCE_CONTINUOUS](class_animationmixer.md#class_AnimationMixer_constant_ANIMATION_CALLBACK_MODE_DISCRETE_FORCE_CONTINUOUS) to match the result with [track_find_key()](class_animation.md#class_Animation_method_track_find_key). + +
+ + + + + +`void` **value_track_set_update_mode**\ (\ track_idx\: [int](class_int.md), mode\: [UpdateMode](class_animation.md#enum_Animation_UpdateMode)\ ) [🔗](#class_Animation_method_value_track_set_update_mode) + +Sets the update mode of a value track. + diff --git a/docs/Classes/class_animationlibrary.md b/docs/Classes/class_animationlibrary.md new file mode 100644 index 00000000..1e004047 --- /dev/null +++ b/docs/Classes/class_animationlibrary.md @@ -0,0 +1,186 @@ + + + + + + + + + +# AnimationLibrary + +**Inherits:** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Container for [Animation](class_animation.md) resources. + + + +## Description + +An animation library stores a set of animations accessible through [StringName](class_stringname.md) keys, for use with [AnimationPlayer](class_animationplayer.md) nodes. + + + +## Tutorials + +- [Animation tutorial index](../tutorials/animation/index.md) + + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Error](class_@globalscope.md#enum_@GlobalScope_Error)[add_animation](#class_AnimationLibrary_method_add_animation)\ (\ name\: [StringName](class_stringname.md), animation\: [Animation](class_animation.md)\ )
[Animation](class_animation.md)[get_animation](#class_AnimationLibrary_method_get_animation)\ (\ name\: [StringName](class_stringname.md)\ ) const
[Array](class_array.md)\[[StringName](class_stringname.md)\][get_animation_list](#class_AnimationLibrary_method_get_animation_list)\ (\ ) const
[int](class_int.md)[get_animation_list_size](#class_AnimationLibrary_method_get_animation_list_size)\ (\ ) const
[bool](class_bool.md)[has_animation](#class_AnimationLibrary_method_has_animation)\ (\ name\: [StringName](class_stringname.md)\ ) const
`void`[remove_animation](#class_AnimationLibrary_method_remove_animation)\ (\ name\: [StringName](class_stringname.md)\ )
`void`[rename_animation](#class_AnimationLibrary_method_rename_animation)\ (\ name\: [StringName](class_stringname.md), newname\: [StringName](class_stringname.md)\ )
+ +
+ + + +## Signals + + + + + +**animation_added**\ (\ name\: [StringName](class_stringname.md)\ ) [🔗](#class_AnimationLibrary_signal_animation_added) + +Emitted when an [Animation](class_animation.md) is added, under the key `name`. + +
+ + + + + +**animation_changed**\ (\ name\: [StringName](class_stringname.md)\ ) [🔗](#class_AnimationLibrary_signal_animation_changed) + +Emitted when there's a change in one of the animations, e.g. tracks are added, moved or have changed paths. `name` is the key of the animation that was changed. + +See also [Resource.changed](class_resource.md#class_Resource_signal_changed), which this acts as a relay for. + +
+ + + + + +**animation_removed**\ (\ name\: [StringName](class_stringname.md)\ ) [🔗](#class_AnimationLibrary_signal_animation_removed) + +Emitted when an [Animation](class_animation.md) stored with the key `name` is removed. + +
+ + + + + +**animation_renamed**\ (\ name\: [StringName](class_stringname.md), to_name\: [StringName](class_stringname.md)\ ) [🔗](#class_AnimationLibrary_signal_animation_renamed) + +Emitted when the key for an [Animation](class_animation.md) is changed, from `name` to `to_name`. + +
+ + + +## Method Descriptions + + + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **add_animation**\ (\ name\: [StringName](class_stringname.md), animation\: [Animation](class_animation.md)\ ) [🔗](#class_AnimationLibrary_method_add_animation) + +Adds the `animation` to the library, accessible by the key `name`. + +
+ + + + + +[Animation](class_animation.md) **get_animation**\ (\ name\: [StringName](class_stringname.md)\ ) const [🔗](#class_AnimationLibrary_method_get_animation) + +Returns the [Animation](class_animation.md) with the key `name`. If the animation does not exist, ``null`` is returned and an error is logged. + +
+ + + + + +[Array](class_array.md)\[[StringName](class_stringname.md)\] **get_animation_list**\ (\ ) const [🔗](#class_AnimationLibrary_method_get_animation_list) + +Returns the keys for the [Animation](class_animation.md)\ s stored in the library. + +
+ + + + + +[int](class_int.md) **get_animation_list_size**\ (\ ) const [🔗](#class_AnimationLibrary_method_get_animation_list_size) + +Returns the key count for the [Animation](class_animation.md)\ s stored in the library. + +
+ + + + + +[bool](class_bool.md) **has_animation**\ (\ name\: [StringName](class_stringname.md)\ ) const [🔗](#class_AnimationLibrary_method_has_animation) + +Returns ``true`` if the library stores an [Animation](class_animation.md) with `name` as the key. + +
+ + + + + +`void` **remove_animation**\ (\ name\: [StringName](class_stringname.md)\ ) [🔗](#class_AnimationLibrary_method_remove_animation) + +Removes the [Animation](class_animation.md) with the key `name`. + +
+ + + + + +`void` **rename_animation**\ (\ name\: [StringName](class_stringname.md), newname\: [StringName](class_stringname.md)\ ) [🔗](#class_AnimationLibrary_method_rename_animation) + +Changes the key of the [Animation](class_animation.md) associated with the key `name` to `newname`. + diff --git a/docs/Classes/class_animationmixer.md b/docs/Classes/class_animationmixer.md new file mode 100644 index 00000000..d8ca000f --- /dev/null +++ b/docs/Classes/class_animationmixer.md @@ -0,0 +1,943 @@ + + + + + + + + + +# AnimationMixer + +**Inherits:** [Node](class_node.md) **<** [Object](class_object.md) + +**Inherited By:** [AnimationPlayer](class_animationplayer.md), [AnimationTree](class_animationtree.md) + +Base class for [AnimationPlayer](class_animationplayer.md) and [AnimationTree](class_animationtree.md). + + + +## Description + +Base class for [AnimationPlayer](class_animationplayer.md) and [AnimationTree](class_animationtree.md) 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**. + + + +## Tutorials + +- [Migrating Animations from Redot 4.0 to 4.3](https://godotengine.org/article/migrating-animations-from-godot-4-0-to-4-3/) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[active](#class_AnimationMixer_property_active)`true`
[int](class_int.md)[audio_max_polyphony](#class_AnimationMixer_property_audio_max_polyphony)`32`
[AnimationCallbackModeDiscrete](class_animationmixer.md#enum_AnimationMixer_AnimationCallbackModeDiscrete)[callback_mode_discrete](#class_AnimationMixer_property_callback_mode_discrete)`1`
[AnimationCallbackModeMethod](class_animationmixer.md#enum_AnimationMixer_AnimationCallbackModeMethod)[callback_mode_method](#class_AnimationMixer_property_callback_mode_method)`0`
[AnimationCallbackModeProcess](class_animationmixer.md#enum_AnimationMixer_AnimationCallbackModeProcess)[callback_mode_process](#class_AnimationMixer_property_callback_mode_process)`1`
[bool](class_bool.md)[deterministic](#class_AnimationMixer_property_deterministic)`false`
[bool](class_bool.md)[reset_on_save](#class_AnimationMixer_property_reset_on_save)`true`
[bool](class_bool.md)[root_motion_local](#class_AnimationMixer_property_root_motion_local)`false`
[NodePath](class_nodepath.md)[root_motion_track](#class_AnimationMixer_property_root_motion_track)`NodePath("")`
[NodePath](class_nodepath.md)[root_node](#class_AnimationMixer_property_root_node)`NodePath("..")`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Variant](class_variant.md)[_post_process_key_value](#class_AnimationMixer_private_method__post_process_key_value)\ (\ animation\: [Animation](class_animation.md), track\: [int](class_int.md), value\: [Variant](class_variant.md), object_id\: [int](class_int.md), object_sub_idx\: [int](class_int.md)\ ) virtual const
[Error](class_@globalscope.md#enum_@GlobalScope_Error)[add_animation_library](#class_AnimationMixer_method_add_animation_library)\ (\ name\: [StringName](class_stringname.md), library\: [AnimationLibrary](class_animationlibrary.md)\ )
`void`[advance](#class_AnimationMixer_method_advance)\ (\ delta\: [float](class_float.md)\ )
`void`[capture](#class_AnimationMixer_method_capture)\ (\ name\: [StringName](class_stringname.md), duration\: [float](class_float.md), trans_type\: [TransitionType](class_tween.md#enum_Tween_TransitionType) = 0, ease_type\: [EaseType](class_tween.md#enum_Tween_EaseType) = 0\ )
`void`[clear_caches](#class_AnimationMixer_method_clear_caches)\ (\ )
[StringName](class_stringname.md)[find_animation](#class_AnimationMixer_method_find_animation)\ (\ animation\: [Animation](class_animation.md)\ ) const
[StringName](class_stringname.md)[find_animation_library](#class_AnimationMixer_method_find_animation_library)\ (\ animation\: [Animation](class_animation.md)\ ) const
[Animation](class_animation.md)[get_animation](#class_AnimationMixer_method_get_animation)\ (\ name\: [StringName](class_stringname.md)\ ) const
[AnimationLibrary](class_animationlibrary.md)[get_animation_library](#class_AnimationMixer_method_get_animation_library)\ (\ name\: [StringName](class_stringname.md)\ ) const
[Array](class_array.md)\[[StringName](class_stringname.md)\][get_animation_library_list](#class_AnimationMixer_method_get_animation_library_list)\ (\ ) const
[PackedStringArray](class_packedstringarray.md)[get_animation_list](#class_AnimationMixer_method_get_animation_list)\ (\ ) const
[Vector3](class_vector3.md)[get_root_motion_position](#class_AnimationMixer_method_get_root_motion_position)\ (\ ) const
[Vector3](class_vector3.md)[get_root_motion_position_accumulator](#class_AnimationMixer_method_get_root_motion_position_accumulator)\ (\ ) const
[Quaternion](class_quaternion.md)[get_root_motion_rotation](#class_AnimationMixer_method_get_root_motion_rotation)\ (\ ) const
[Quaternion](class_quaternion.md)[get_root_motion_rotation_accumulator](#class_AnimationMixer_method_get_root_motion_rotation_accumulator)\ (\ ) const
[Vector3](class_vector3.md)[get_root_motion_scale](#class_AnimationMixer_method_get_root_motion_scale)\ (\ ) const
[Vector3](class_vector3.md)[get_root_motion_scale_accumulator](#class_AnimationMixer_method_get_root_motion_scale_accumulator)\ (\ ) const
[bool](class_bool.md)[has_animation](#class_AnimationMixer_method_has_animation)\ (\ name\: [StringName](class_stringname.md)\ ) const
[bool](class_bool.md)[has_animation_library](#class_AnimationMixer_method_has_animation_library)\ (\ name\: [StringName](class_stringname.md)\ ) const
`void`[remove_animation_library](#class_AnimationMixer_method_remove_animation_library)\ (\ name\: [StringName](class_stringname.md)\ )
`void`[rename_animation_library](#class_AnimationMixer_method_rename_animation_library)\ (\ name\: [StringName](class_stringname.md), newname\: [StringName](class_stringname.md)\ )
+ +
+ + + +## Signals + + + + + +**animation_finished**\ (\ anim_name\: [StringName](class_stringname.md)\ ) [🔗](#class_AnimationMixer_signal_animation_finished) + +Notifies when an animation finished playing. + +\ **Note:** This signal is not emitted if an animation is looping. + +
+ + + + + +**animation_libraries_updated**\ (\ ) [🔗](#class_AnimationMixer_signal_animation_libraries_updated) + +Notifies when the animation libraries have changed. + +
+ + + + + +**animation_list_changed**\ (\ ) [🔗](#class_AnimationMixer_signal_animation_list_changed) + +Notifies when an animation list is changed. + +
+ + + + + +**animation_started**\ (\ anim_name\: [StringName](class_stringname.md)\ ) [🔗](#class_AnimationMixer_signal_animation_started) + +Notifies when an animation starts playing. + +\ **Note:** This signal is not emitted if an animation is looping. + +
+ + + + + +**caches_cleared**\ (\ ) [🔗](#class_AnimationMixer_signal_caches_cleared) + +Notifies when the caches have been cleared, either automatically, or manually via [clear_caches()](class_animationmixer.md#class_AnimationMixer_method_clear_caches). + +
+ + + + + +**mixer_applied**\ (\ ) [🔗](#class_AnimationMixer_signal_mixer_applied) + +Notifies when the blending result related have been applied to the target objects. + +
+ + + + + +**mixer_updated**\ (\ ) [🔗](#class_AnimationMixer_signal_mixer_updated) + +Notifies when the property related process have been updated. + +
+ + + +## Enumerations + + + + + +enum **AnimationCallbackModeProcess**: [🔗](#enum_AnimationMixer_AnimationCallbackModeProcess) + + + + + +[AnimationCallbackModeProcess](class_animationmixer.md#enum_AnimationMixer_AnimationCallbackModeProcess) **ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS** = `0` + +Process animation during physics frames (see [Node.NOTIFICATION_INTERNAL_PHYSICS_PROCESS](class_node.md#class_Node_constant_NOTIFICATION_INTERNAL_PHYSICS_PROCESS)). This is especially useful when animating physics bodies. + + + +[AnimationCallbackModeProcess](class_animationmixer.md#enum_AnimationMixer_AnimationCallbackModeProcess) **ANIMATION_CALLBACK_MODE_PROCESS_IDLE** = `1` + +Process animation during process frames (see [Node.NOTIFICATION_INTERNAL_PROCESS](class_node.md#class_Node_constant_NOTIFICATION_INTERNAL_PROCESS)). + + + +[AnimationCallbackModeProcess](class_animationmixer.md#enum_AnimationMixer_AnimationCallbackModeProcess) **ANIMATION_CALLBACK_MODE_PROCESS_MANUAL** = `2` + +Do not process animation. Use [advance()](class_animationmixer.md#class_AnimationMixer_method_advance) to process the animation manually.
+ + + + + +enum **AnimationCallbackModeMethod**: [🔗](#enum_AnimationMixer_AnimationCallbackModeMethod) + + + + + +[AnimationCallbackModeMethod](class_animationmixer.md#enum_AnimationMixer_AnimationCallbackModeMethod) **ANIMATION_CALLBACK_MODE_METHOD_DEFERRED** = `0` + +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. + + + +[AnimationCallbackModeMethod](class_animationmixer.md#enum_AnimationMixer_AnimationCallbackModeMethod) **ANIMATION_CALLBACK_MODE_METHOD_IMMEDIATE** = `1` + +Make method calls immediately when reached in the animation.
+ + + + + +enum **AnimationCallbackModeDiscrete**: [🔗](#enum_AnimationMixer_AnimationCallbackModeDiscrete) + + + + + +[AnimationCallbackModeDiscrete](class_animationmixer.md#enum_AnimationMixer_AnimationCallbackModeDiscrete) **ANIMATION_CALLBACK_MODE_DISCRETE_DOMINANT** = `0` + +An [Animation.UPDATE_DISCRETE](class_animation.md#class_Animation_constant_UPDATE_DISCRETE) track value takes precedence when blending [Animation.UPDATE_CONTINUOUS](class_animation.md#class_Animation_constant_UPDATE_CONTINUOUS) or [Animation.UPDATE_CAPTURE](class_animation.md#class_Animation_constant_UPDATE_CAPTURE) track values and [Animation.UPDATE_DISCRETE](class_animation.md#class_Animation_constant_UPDATE_DISCRETE) track values. + + + +[AnimationCallbackModeDiscrete](class_animationmixer.md#enum_AnimationMixer_AnimationCallbackModeDiscrete) **ANIMATION_CALLBACK_MODE_DISCRETE_RECESSIVE** = `1` + +An [Animation.UPDATE_CONTINUOUS](class_animation.md#class_Animation_constant_UPDATE_CONTINUOUS) or [Animation.UPDATE_CAPTURE](class_animation.md#class_Animation_constant_UPDATE_CAPTURE) track value takes precedence when blending the [Animation.UPDATE_CONTINUOUS](class_animation.md#class_Animation_constant_UPDATE_CONTINUOUS) or [Animation.UPDATE_CAPTURE](class_animation.md#class_Animation_constant_UPDATE_CAPTURE) track values and the [Animation.UPDATE_DISCRETE](class_animation.md#class_Animation_constant_UPDATE_DISCRETE) track values. This is the default behavior for [AnimationPlayer](class_animationplayer.md). + + + +[AnimationCallbackModeDiscrete](class_animationmixer.md#enum_AnimationMixer_AnimationCallbackModeDiscrete) **ANIMATION_CALLBACK_MODE_DISCRETE_FORCE_CONTINUOUS** = `2` + +Always treat the [Animation.UPDATE_DISCRETE](class_animation.md#class_Animation_constant_UPDATE_DISCRETE) track value as [Animation.UPDATE_CONTINUOUS](class_animation.md#class_Animation_constant_UPDATE_CONTINUOUS) with [Animation.INTERPOLATION_NEAREST](class_animation.md#class_Animation_constant_INTERPOLATION_NEAREST). This is the default behavior for [AnimationTree](class_animationtree.md). + +If a value track has un-interpolatable type key values, it is internally converted to use [ANIMATION_CALLBACK_MODE_DISCRETE_RECESSIVE](class_animationmixer.md#class_AnimationMixer_constant_ANIMATION_CALLBACK_MODE_DISCRETE_RECESSIVE) with [Animation.UPDATE_DISCRETE](class_animation.md#class_Animation_constant_UPDATE_DISCRETE). + +Un-interpolatable type list: + +- [@GlobalScope.TYPE_NIL](class_@globalscope.md#class_@GlobalScope_constant_TYPE_NIL)\ + +- [@GlobalScope.TYPE_NODE_PATH](class_@globalscope.md#class_@GlobalScope_constant_TYPE_NODE_PATH)\ + +- [@GlobalScope.TYPE_RID](class_@globalscope.md#class_@GlobalScope_constant_TYPE_RID)\ + +- [@GlobalScope.TYPE_OBJECT](class_@globalscope.md#class_@GlobalScope_constant_TYPE_OBJECT)\ + +- [@GlobalScope.TYPE_CALLABLE](class_@globalscope.md#class_@GlobalScope_constant_TYPE_CALLABLE)\ + +- [@GlobalScope.TYPE_SIGNAL](class_@globalscope.md#class_@GlobalScope_constant_TYPE_SIGNAL)\ + +- [@GlobalScope.TYPE_DICTIONARY](class_@globalscope.md#class_@GlobalScope_constant_TYPE_DICTIONARY)\ + +- [@GlobalScope.TYPE_PACKED_BYTE_ARRAY](class_@globalscope.md#class_@GlobalScope_constant_TYPE_PACKED_BYTE_ARRAY)\ + +\ [@GlobalScope.TYPE_BOOL](class_@globalscope.md#class_@GlobalScope_constant_TYPE_BOOL) and [@GlobalScope.TYPE_INT](class_@globalscope.md#class_@GlobalScope_constant_TYPE_INT) are treated as [@GlobalScope.TYPE_FLOAT](class_@globalscope.md#class_@GlobalScope_constant_TYPE_FLOAT) during blending and rounded when the result is retrieved. + +It is same for arrays and vectors with them such as [@GlobalScope.TYPE_PACKED_INT32_ARRAY](class_@globalscope.md#class_@GlobalScope_constant_TYPE_PACKED_INT32_ARRAY) or [@GlobalScope.TYPE_VECTOR2I](class_@globalscope.md#class_@GlobalScope_constant_TYPE_VECTOR2I), they are treated as [@GlobalScope.TYPE_PACKED_FLOAT32_ARRAY](class_@globalscope.md#class_@GlobalScope_constant_TYPE_PACKED_FLOAT32_ARRAY) or [@GlobalScope.TYPE_VECTOR2](class_@globalscope.md#class_@GlobalScope_constant_TYPE_VECTOR2). Also note that for arrays, the size is also interpolated. + +\ [@GlobalScope.TYPE_STRING](class_@globalscope.md#class_@GlobalScope_constant_TYPE_STRING) and [@GlobalScope.TYPE_STRING_NAME](class_@globalscope.md#class_@GlobalScope_constant_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.
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **active** = `true` [🔗](#class_AnimationMixer_property_active) + + + +- `void` **set_active**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_active**\ (\ ) + +If ``true``, the **AnimationMixer** will be processing. + +
+ + + + + +[int](class_int.md) **audio_max_polyphony** = `32` [🔗](#class_AnimationMixer_property_audio_max_polyphony) + + + +- `void` **set_audio_max_polyphony**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_audio_max_polyphony**\ (\ ) + +The number of possible simultaneous sounds for each of the assigned AudioStreamPlayers. + +For example, if this value is ``32`` and the animation has two audio tracks, the two [AudioStreamPlayer](class_audiostreamplayer.md)\ s assigned can play simultaneously up to ``32`` voices each. + +
+ + + + + +[AnimationCallbackModeDiscrete](class_animationmixer.md#enum_AnimationMixer_AnimationCallbackModeDiscrete) **callback_mode_discrete** = `1` [🔗](#class_AnimationMixer_property_callback_mode_discrete) + + + +- `void` **set_callback_mode_discrete**\ (\ value\: [AnimationCallbackModeDiscrete](class_animationmixer.md#enum_AnimationMixer_AnimationCallbackModeDiscrete)\ ) +- [AnimationCallbackModeDiscrete](class_animationmixer.md#enum_AnimationMixer_AnimationCallbackModeDiscrete) **get_callback_mode_discrete**\ (\ ) + +Ordinarily, tracks can be set to [Animation.UPDATE_DISCRETE](class_animation.md#class_Animation_constant_UPDATE_DISCRETE) to update infrequently, usually when using nearest interpolation. + +However, when blending with [Animation.UPDATE_CONTINUOUS](class_animation.md#class_Animation_constant_UPDATE_CONTINUOUS) several results are considered. The [callback_mode_discrete](class_animationmixer.md#class_AnimationMixer_property_callback_mode_discrete) specify it explicitly. See also [AnimationCallbackModeDiscrete](class_animationmixer.md#enum_AnimationMixer_AnimationCallbackModeDiscrete). + +To make the blended results look good, it is recommended to set this to [ANIMATION_CALLBACK_MODE_DISCRETE_FORCE_CONTINUOUS](class_animationmixer.md#class_AnimationMixer_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. + +
+ + + + + +[AnimationCallbackModeMethod](class_animationmixer.md#enum_AnimationMixer_AnimationCallbackModeMethod) **callback_mode_method** = `0` [🔗](#class_AnimationMixer_property_callback_mode_method) + + + +- `void` **set_callback_mode_method**\ (\ value\: [AnimationCallbackModeMethod](class_animationmixer.md#enum_AnimationMixer_AnimationCallbackModeMethod)\ ) +- [AnimationCallbackModeMethod](class_animationmixer.md#enum_AnimationMixer_AnimationCallbackModeMethod) **get_callback_mode_method**\ (\ ) + +The call mode used for "Call Method" tracks. + +
+ + + + + +[AnimationCallbackModeProcess](class_animationmixer.md#enum_AnimationMixer_AnimationCallbackModeProcess) **callback_mode_process** = `1` [🔗](#class_AnimationMixer_property_callback_mode_process) + + + +- `void` **set_callback_mode_process**\ (\ value\: [AnimationCallbackModeProcess](class_animationmixer.md#enum_AnimationMixer_AnimationCallbackModeProcess)\ ) +- [AnimationCallbackModeProcess](class_animationmixer.md#enum_AnimationMixer_AnimationCallbackModeProcess) **get_callback_mode_process**\ (\ ) + +The process notification in which to update animations. + +
+ + + + + +[bool](class_bool.md) **deterministic** = `false` [🔗](#class_AnimationMixer_property_deterministic) + + + +- `void` **set_deterministic**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_deterministic**\ (\ ) + +If ``true``, the blending uses the deterministic algorithm. The total weight is not normalized and the result is accumulated with an initial value (``0`` or a ``"RESET"`` animation if present). + +This means that if the total amount of blending is ``0.0``, the result is equal to the ``"RESET"`` 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 ``false``, The blend does not use the deterministic algorithm. The total weight is normalized and always ``1.0``. If the number of tracks between the blended animations is different, nothing is done about the animation that is missing a track. + +\ **Note:** In [AnimationTree](class_animationtree.md), the blending with [AnimationNodeAdd2](class_animationnodeadd2.md), [AnimationNodeAdd3](class_animationnodeadd3.md), [AnimationNodeSub2](class_animationnodesub2.md) or the weight greater than ``1.0`` may produce unexpected results. + +For example, if [AnimationNodeAdd2](class_animationnodeadd2.md) blends two nodes with the amount ``1.0``, then total weight is ``2.0`` but it will be normalized to make the total amount ``1.0`` and the result will be equal to [AnimationNodeBlend2](class_animationnodeblend2.md) with the amount ``0.5``. + +
+ + + + + +[bool](class_bool.md) **reset_on_save** = `true` [🔗](#class_AnimationMixer_property_reset_on_save) + + + +- `void` **set_reset_on_save_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_reset_on_save_enabled**\ (\ ) + +This is used by the editor. If set to ``true``, the scene will be saved with the effects of the reset animation (the animation with the key ``"RESET"``) 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. + +
+ + + + + +[bool](class_bool.md) **root_motion_local** = `false` [🔗](#class_AnimationMixer_property_root_motion_local) + + + +- `void` **set_root_motion_local**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_root_motion_local**\ (\ ) + +If ``true``, [get_root_motion_position()](class_animationmixer.md#class_AnimationMixer_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. + +
+ + + + + +[NodePath](class_nodepath.md) **root_motion_track** = `NodePath("")` [🔗](#class_AnimationMixer_property_root_motion_track) + + + +- `void` **set_root_motion_track**\ (\ value\: [NodePath](class_nodepath.md)\ ) +- [NodePath](class_nodepath.md) **get_root_motion_track**\ (\ ) + +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 [root_motion_track](class_animationmixer.md#class_AnimationMixer_property_root_motion_track) uses the same format as [Animation.track_set_path()](class_animation.md#class_Animation_method_track_set_path), but note that a bone must be specified. + +If the track has type [Animation.TYPE_POSITION_3D](class_animation.md#class_Animation_constant_TYPE_POSITION_3D), [Animation.TYPE_ROTATION_3D](class_animation.md#class_Animation_constant_TYPE_ROTATION_3D), or [Animation.TYPE_SCALE_3D](class_animation.md#class_Animation_constant_TYPE_SCALE_3D) the transformation will be canceled visually, and the animation will appear to stay in place. See also [get_root_motion_position()](class_animationmixer.md#class_AnimationMixer_method_get_root_motion_position), [get_root_motion_rotation()](class_animationmixer.md#class_AnimationMixer_method_get_root_motion_rotation), [get_root_motion_scale()](class_animationmixer.md#class_AnimationMixer_method_get_root_motion_scale), and [RootMotionView](class_rootmotionview.md). + +
+ + + + + +[NodePath](class_nodepath.md) **root_node** = `NodePath("..")` [🔗](#class_AnimationMixer_property_root_node) + + + +- `void` **set_root_node**\ (\ value\: [NodePath](class_nodepath.md)\ ) +- [NodePath](class_nodepath.md) **get_root_node**\ (\ ) + +The node which node path references will travel from. + +
+ + + +## Method Descriptions + + + + + +[Variant](class_variant.md) **_post_process_key_value**\ (\ animation\: [Animation](class_animation.md), track\: [int](class_int.md), value\: [Variant](class_variant.md), object_id\: [int](class_int.md), object_sub_idx\: [int](class_int.md)\ ) virtual const [🔗](#class_AnimationMixer_private_method__post_process_key_value) + +A virtual function for processing after getting a key during playback. + +
+ + + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **add_animation_library**\ (\ name\: [StringName](class_stringname.md), library\: [AnimationLibrary](class_animationlibrary.md)\ ) [🔗](#class_AnimationMixer_method_add_animation_library) + +Adds `library` to the animation player, under the key `name`. + +AnimationMixer has a global library by default with an empty string as key. For adding an animation to the global library: + + + + +```gdscript + var global_library = mixer.get_animation_library("") + global_library.add_animation("animation_name", animation_resource) +``` + + + +
+ + + + + +`void` **advance**\ (\ delta\: [float](class_float.md)\ ) [🔗](#class_AnimationMixer_method_advance) + +Manually advance the animations by the specified time (in seconds). + +
+ + + + + +`void` **capture**\ (\ name\: [StringName](class_stringname.md), duration\: [float](class_float.md), trans_type\: [TransitionType](class_tween.md#enum_Tween_TransitionType) = 0, ease_type\: [EaseType](class_tween.md#enum_Tween_EaseType) = 0\ ) [🔗](#class_AnimationMixer_method_capture) + +If the animation track specified by `name` has an option [Animation.UPDATE_CAPTURE](class_animation.md#class_Animation_constant_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 `duration`, working like a crossfade. + +You can specify `trans_type` as the curve for the interpolation. For better results, it may be appropriate to specify [Tween.TRANS_LINEAR](class_tween.md#class_Tween_constant_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 [Tween.TRANS_QUAD](class_tween.md#class_Tween_constant_TRANS_QUAD) for cases where the key value changes linearly. + +
+ + + + + +`void` **clear_caches**\ (\ ) [🔗](#class_AnimationMixer_method_clear_caches) + +**AnimationMixer** caches animated nodes. It may not notice if a node disappears; [clear_caches()](class_animationmixer.md#class_AnimationMixer_method_clear_caches) forces it to update the cache again. + +
+ + + + + +[StringName](class_stringname.md) **find_animation**\ (\ animation\: [Animation](class_animation.md)\ ) const [🔗](#class_AnimationMixer_method_find_animation) + +Returns the key of `animation` or an empty [StringName](class_stringname.md) if not found. + +
+ + + + + +[StringName](class_stringname.md) **find_animation_library**\ (\ animation\: [Animation](class_animation.md)\ ) const [🔗](#class_AnimationMixer_method_find_animation_library) + +Returns the key for the [AnimationLibrary](class_animationlibrary.md) that contains `animation` or an empty [StringName](class_stringname.md) if not found. + +
+ + + + + +[Animation](class_animation.md) **get_animation**\ (\ name\: [StringName](class_stringname.md)\ ) const [🔗](#class_AnimationMixer_method_get_animation) + +Returns the [Animation](class_animation.md) with the key `name`. If the animation does not exist, ``null`` is returned and an error is logged. + +
+ + + + + +[AnimationLibrary](class_animationlibrary.md) **get_animation_library**\ (\ name\: [StringName](class_stringname.md)\ ) const [🔗](#class_AnimationMixer_method_get_animation_library) + +Returns the first [AnimationLibrary](class_animationlibrary.md) with key `name` or ``null`` if not found. + +To get the **AnimationMixer**'s global animation library, use ``get_animation_library("")``. + +
+ + + + + +[Array](class_array.md)\[[StringName](class_stringname.md)\] **get_animation_library_list**\ (\ ) const [🔗](#class_AnimationMixer_method_get_animation_library_list) + +Returns the list of stored library keys. + +
+ + + + + +[PackedStringArray](class_packedstringarray.md) **get_animation_list**\ (\ ) const [🔗](#class_AnimationMixer_method_get_animation_list) + +Returns the list of stored animation keys. + +
+ + + + + +[Vector3](class_vector3.md) **get_root_motion_position**\ (\ ) const [🔗](#class_AnimationMixer_method_get_root_motion_position) + +Retrieve the motion delta of position with the [root_motion_track](class_animationmixer.md#class_AnimationMixer_property_root_motion_track) as a [Vector3](class_vector3.md) that can be used elsewhere. + +If [root_motion_track](class_animationmixer.md#class_AnimationMixer_property_root_motion_track) is not a path to a track of type [Animation.TYPE_POSITION_3D](class_animation.md#class_Animation_constant_TYPE_POSITION_3D), returns ``Vector3(0, 0, 0)``. + +See also [root_motion_track](class_animationmixer.md#class_AnimationMixer_property_root_motion_track) and [RootMotionView](class_rootmotionview.md). + +The most basic example is applying position to [CharacterBody3D](class_characterbody3d.md): + + + + +```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() +``` + + + +By using this in combination with [get_root_motion_rotation_accumulator()](class_animationmixer.md#class_AnimationMixer_method_get_root_motion_rotation_accumulator), you can apply the root motion position more correctly to account for the rotation of the node. + + + + +```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() +``` + + + +If [root_motion_local](class_animationmixer.md#class_AnimationMixer_property_root_motion_local) is ``true``, returns the pre-multiplied translation value with the inverted rotation. + +In this case, the code can be written as follows: + + + + +```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() +``` + + + +
+ + + + + +[Vector3](class_vector3.md) **get_root_motion_position_accumulator**\ (\ ) const [🔗](#class_AnimationMixer_method_get_root_motion_position_accumulator) + +Retrieve the blended value of the position tracks with the [root_motion_track](class_animationmixer.md#class_AnimationMixer_property_root_motion_track) as a [Vector3](class_vector3.md) 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 ``Vector3(0, 0, 0)`` is played in the previous frame and then an animation with only one key ``Vector3(1, 0, 1)`` is played in the next frame, the difference can be calculated as follows: + + + + +```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 +``` + + + +However, if the animation loops, an unintended discrete change may occur, so this is only useful for some simple use cases. + +
+ + + + + +[Quaternion](class_quaternion.md) **get_root_motion_rotation**\ (\ ) const [🔗](#class_AnimationMixer_method_get_root_motion_rotation) + +Retrieve the motion delta of rotation with the [root_motion_track](class_animationmixer.md#class_AnimationMixer_property_root_motion_track) as a [Quaternion](class_quaternion.md) that can be used elsewhere. + +If [root_motion_track](class_animationmixer.md#class_AnimationMixer_property_root_motion_track) is not a path to a track of type [Animation.TYPE_ROTATION_3D](class_animation.md#class_Animation_constant_TYPE_ROTATION_3D), returns ``Quaternion(0, 0, 0, 1)``. + +See also [root_motion_track](class_animationmixer.md#class_AnimationMixer_property_root_motion_track) and [RootMotionView](class_rootmotionview.md). + +The most basic example is applying rotation to [CharacterBody3D](class_characterbody3d.md): + + + + +```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()) +``` + + + +
+ + + + + +[Quaternion](class_quaternion.md) **get_root_motion_rotation_accumulator**\ (\ ) const [🔗](#class_AnimationMixer_method_get_root_motion_rotation_accumulator) + +Retrieve the blended value of the rotation tracks with the [root_motion_track](class_animationmixer.md#class_AnimationMixer_property_root_motion_track) as a [Quaternion](class_quaternion.md) that can be used elsewhere. + +This is necessary to apply the root motion position correctly, taking rotation into account. See also [get_root_motion_position()](class_animationmixer.md#class_AnimationMixer_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 ``Quaternion(0, 0, 0, 1)`` is played in the previous frame and then an animation with only one key ``Quaternion(0, 0.707, 0, 0.707)`` is played in the next frame, the difference can be calculated as follows: + + + + +```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) +``` + + + +However, if the animation loops, an unintended discrete change may occur, so this is only useful for some simple use cases. + +
+ + + + + +[Vector3](class_vector3.md) **get_root_motion_scale**\ (\ ) const [🔗](#class_AnimationMixer_method_get_root_motion_scale) + +Retrieve the motion delta of scale with the [root_motion_track](class_animationmixer.md#class_AnimationMixer_property_root_motion_track) as a [Vector3](class_vector3.md) that can be used elsewhere. + +If [root_motion_track](class_animationmixer.md#class_AnimationMixer_property_root_motion_track) is not a path to a track of type [Animation.TYPE_SCALE_3D](class_animation.md#class_Animation_constant_TYPE_SCALE_3D), returns ``Vector3(0, 0, 0)``. + +See also [root_motion_track](class_animationmixer.md#class_AnimationMixer_property_root_motion_track) and [RootMotionView](class_rootmotionview.md). + +The most basic example is applying scale to [CharacterBody3D](class_characterbody3d.md): + + + + +```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) +``` + + + +
+ + + + + +[Vector3](class_vector3.md) **get_root_motion_scale_accumulator**\ (\ ) const [🔗](#class_AnimationMixer_method_get_root_motion_scale_accumulator) + +Retrieve the blended value of the scale tracks with the [root_motion_track](class_animationmixer.md#class_AnimationMixer_property_root_motion_track) as a [Vector3](class_vector3.md) that can be used elsewhere. + +For example, if an animation with only one key ``Vector3(1, 1, 1)`` is played in the previous frame and then an animation with only one key ``Vector3(2, 2, 2)`` is played in the next frame, the difference can be calculated as follows: + + + + +```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) +``` + + + +However, if the animation loops, an unintended discrete change may occur, so this is only useful for some simple use cases. + +
+ + + + + +[bool](class_bool.md) **has_animation**\ (\ name\: [StringName](class_stringname.md)\ ) const [🔗](#class_AnimationMixer_method_has_animation) + +Returns ``true`` if the **AnimationMixer** stores an [Animation](class_animation.md) with key `name`. + +
+ + + + + +[bool](class_bool.md) **has_animation_library**\ (\ name\: [StringName](class_stringname.md)\ ) const [🔗](#class_AnimationMixer_method_has_animation_library) + +Returns ``true`` if the **AnimationMixer** stores an [AnimationLibrary](class_animationlibrary.md) with key `name`. + +
+ + + + + +`void` **remove_animation_library**\ (\ name\: [StringName](class_stringname.md)\ ) [🔗](#class_AnimationMixer_method_remove_animation_library) + +Removes the [AnimationLibrary](class_animationlibrary.md) associated with the key `name`. + +
+ + + + + +`void` **rename_animation_library**\ (\ name\: [StringName](class_stringname.md), newname\: [StringName](class_stringname.md)\ ) [🔗](#class_AnimationMixer_method_rename_animation_library) + +Moves the [AnimationLibrary](class_animationlibrary.md) associated with the key `name` to the key `newname`. + diff --git a/docs/Classes/class_animationnode.md b/docs/Classes/class_animationnode.md new file mode 100644 index 00000000..1ac32267 --- /dev/null +++ b/docs/Classes/class_animationnode.md @@ -0,0 +1,492 @@ + + + + + + + + + +# AnimationNode + +**Inherits:** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +**Inherited By:** [AnimationNodeExtension](class_animationnodeextension.md), [AnimationNodeOutput](class_animationnodeoutput.md), [AnimationNodeSync](class_animationnodesync.md), [AnimationNodeTimeScale](class_animationnodetimescale.md), [AnimationNodeTimeSeek](class_animationnodetimeseek.md), [AnimationRootNode](class_animationrootnode.md) + +Base class for [AnimationTree](class_animationtree.md) nodes. Not related to scene nodes. + + + +## Description + +Base resource for [AnimationTree](class_animationtree.md) 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](class_animationnodeblendtree.md), otherwise [AnimationRootNode](class_animationrootnode.md) 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](class_animationnodeoutput.md). + +\ **Note:** If multiple inputs exist in the **AnimationNode**, which time information takes precedence depends on the type of **AnimationNode**. + +``` + var current_length = $AnimationTree["parameters/AnimationNodeName/current_length"] + var current_position = $AnimationTree["parameters/AnimationNodeName/current_position"] + var current_delta = $AnimationTree["parameters/AnimationNodeName/current_delta"] +``` + + + +## Tutorials + +- [Using AnimationTree](../tutorials/animation/animation_tree.md) + + + +## Properties + + + + + + + + + + +
[bool](class_bool.md)[filter_enabled](#class_AnimationNode_property_filter_enabled)
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[String](class_string.md)[_get_caption](#class_AnimationNode_private_method__get_caption)\ (\ ) virtual const
[AnimationNode](class_animationnode.md)[_get_child_by_name](#class_AnimationNode_private_method__get_child_by_name)\ (\ name\: [StringName](class_stringname.md)\ ) virtual const
[Dictionary](class_dictionary.md)[_get_child_nodes](#class_AnimationNode_private_method__get_child_nodes)\ (\ ) virtual const
[Variant](class_variant.md)[_get_parameter_default_value](#class_AnimationNode_private_method__get_parameter_default_value)\ (\ parameter\: [StringName](class_stringname.md)\ ) virtual const
[Array](class_array.md)[_get_parameter_list](#class_AnimationNode_private_method__get_parameter_list)\ (\ ) virtual const
[bool](class_bool.md)[_has_filter](#class_AnimationNode_private_method__has_filter)\ (\ ) virtual const
[bool](class_bool.md)[_is_parameter_read_only](#class_AnimationNode_private_method__is_parameter_read_only)\ (\ parameter\: [StringName](class_stringname.md)\ ) virtual const
[float](class_float.md)[_process](#class_AnimationNode_private_method__process)\ (\ time\: [float](class_float.md), seek\: [bool](class_bool.md), is_external_seeking\: [bool](class_bool.md), test_only\: [bool](class_bool.md)\ ) virtual
[bool](class_bool.md)[add_input](#class_AnimationNode_method_add_input)\ (\ name\: [String](class_string.md)\ )
`void`[blend_animation](#class_AnimationNode_method_blend_animation)\ (\ animation\: [StringName](class_stringname.md), time\: [float](class_float.md), delta\: [float](class_float.md), seeked\: [bool](class_bool.md), is_external_seeking\: [bool](class_bool.md), blend\: [float](class_float.md), looped_flag\: [LoopedFlag](class_animation.md#enum_Animation_LoopedFlag) = 0\ )
[float](class_float.md)[blend_input](#class_AnimationNode_method_blend_input)\ (\ input_index\: [int](class_int.md), time\: [float](class_float.md), seek\: [bool](class_bool.md), is_external_seeking\: [bool](class_bool.md), blend\: [float](class_float.md), filter\: [FilterAction](class_animationnode.md#enum_AnimationNode_FilterAction) = 0, sync\: [bool](class_bool.md) = true, test_only\: [bool](class_bool.md) = false\ )
[float](class_float.md)[blend_node](#class_AnimationNode_method_blend_node)\ (\ name\: [StringName](class_stringname.md), node\: [AnimationNode](class_animationnode.md), time\: [float](class_float.md), seek\: [bool](class_bool.md), is_external_seeking\: [bool](class_bool.md), blend\: [float](class_float.md), filter\: [FilterAction](class_animationnode.md#enum_AnimationNode_FilterAction) = 0, sync\: [bool](class_bool.md) = true, test_only\: [bool](class_bool.md) = false\ )
[int](class_int.md)[find_input](#class_AnimationNode_method_find_input)\ (\ name\: [String](class_string.md)\ ) const
[int](class_int.md)[get_input_count](#class_AnimationNode_method_get_input_count)\ (\ ) const
[String](class_string.md)[get_input_name](#class_AnimationNode_method_get_input_name)\ (\ input\: [int](class_int.md)\ ) const
[Variant](class_variant.md)[get_parameter](#class_AnimationNode_method_get_parameter)\ (\ name\: [StringName](class_stringname.md)\ ) const
[int](class_int.md)[get_processing_animation_tree_instance_id](#class_AnimationNode_method_get_processing_animation_tree_instance_id)\ (\ ) const
[bool](class_bool.md)[is_path_filtered](#class_AnimationNode_method_is_path_filtered)\ (\ path\: [NodePath](class_nodepath.md)\ ) const
[bool](class_bool.md)[is_process_testing](#class_AnimationNode_method_is_process_testing)\ (\ ) const
`void`[remove_input](#class_AnimationNode_method_remove_input)\ (\ index\: [int](class_int.md)\ )
`void`[set_filter_path](#class_AnimationNode_method_set_filter_path)\ (\ path\: [NodePath](class_nodepath.md), enable\: [bool](class_bool.md)\ )
[bool](class_bool.md)[set_input_name](#class_AnimationNode_method_set_input_name)\ (\ input\: [int](class_int.md), name\: [String](class_string.md)\ )
`void`[set_parameter](#class_AnimationNode_method_set_parameter)\ (\ name\: [StringName](class_stringname.md), value\: [Variant](class_variant.md)\ )
+ +
+ + + +## Signals + + + + + +**animation_node_removed**\ (\ object_id\: [int](class_int.md), name\: [String](class_string.md)\ ) [🔗](#class_AnimationNode_signal_animation_node_removed) + +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](class_animationnodeblendspace1d.md), [AnimationNodeBlendSpace2D](class_animationnodeblendspace2d.md), [AnimationNodeStateMachine](class_animationnodestatemachine.md), and [AnimationNodeBlendTree](class_animationnodeblendtree.md). + +
+ + + + + +**animation_node_renamed**\ (\ object_id\: [int](class_int.md), old_name\: [String](class_string.md), new_name\: [String](class_string.md)\ ) [🔗](#class_AnimationNode_signal_animation_node_renamed) + +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](class_animationnodeblendspace1d.md), [AnimationNodeBlendSpace2D](class_animationnodeblendspace2d.md), [AnimationNodeStateMachine](class_animationnodestatemachine.md), and [AnimationNodeBlendTree](class_animationnodeblendtree.md). + +
+ + + + + +**tree_changed**\ (\ ) [🔗](#class_AnimationNode_signal_tree_changed) + +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](class_animationnodeblendspace1d.md), [AnimationNodeBlendSpace2D](class_animationnodeblendspace2d.md), [AnimationNodeStateMachine](class_animationnodestatemachine.md), [AnimationNodeBlendTree](class_animationnodeblendtree.md) and [AnimationNodeTransition](class_animationnodetransition.md). + +
+ + + +## Enumerations + + + + + +enum **FilterAction**: [🔗](#enum_AnimationNode_FilterAction) + + + + + +[FilterAction](class_animationnode.md#enum_AnimationNode_FilterAction) **FILTER_IGNORE** = `0` + +Do not use filtering. + + + +[FilterAction](class_animationnode.md#enum_AnimationNode_FilterAction) **FILTER_PASS** = `1` + +Paths matching the filter will be allowed to pass. + + + +[FilterAction](class_animationnode.md#enum_AnimationNode_FilterAction) **FILTER_STOP** = `2` + +Paths matching the filter will be discarded. + + + +[FilterAction](class_animationnode.md#enum_AnimationNode_FilterAction) **FILTER_BLEND** = `3` + +Paths matching the filter will be blended (by the blend value).
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **filter_enabled** [🔗](#class_AnimationNode_property_filter_enabled) + + + +- `void` **set_filter_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_filter_enabled**\ (\ ) + +If ``true``, filtering is enabled. + +
+ + + +## Method Descriptions + + + + + +[String](class_string.md) **_get_caption**\ (\ ) virtual const [🔗](#class_AnimationNode_private_method__get_caption) + +When inheriting from [AnimationRootNode](class_animationrootnode.md), implement this virtual method to override the text caption for this animation node. + +
+ + + + + +[AnimationNode](class_animationnode.md) **_get_child_by_name**\ (\ name\: [StringName](class_stringname.md)\ ) virtual const [🔗](#class_AnimationNode_private_method__get_child_by_name) + +When inheriting from [AnimationRootNode](class_animationrootnode.md), implement this virtual method to return a child animation node by its `name`. + +
+ + + + + +[Dictionary](class_dictionary.md) **_get_child_nodes**\ (\ ) virtual const [🔗](#class_AnimationNode_private_method__get_child_nodes) + +When inheriting from [AnimationRootNode](class_animationrootnode.md), implement this virtual method to return all child animation nodes in order as a ``name: node`` dictionary. + +
+ + + + + +[Variant](class_variant.md) **_get_parameter_default_value**\ (\ parameter\: [StringName](class_stringname.md)\ ) virtual const [🔗](#class_AnimationNode_private_method__get_parameter_default_value) + +When inheriting from [AnimationRootNode](class_animationrootnode.md), implement this virtual method to return the default value of a `parameter`. Parameters are custom local memory used for your animation nodes, given a resource can be reused in multiple trees. + +
+ + + + + +[Array](class_array.md) **_get_parameter_list**\ (\ ) virtual const [🔗](#class_AnimationNode_private_method__get_parameter_list) + +When inheriting from [AnimationRootNode](class_animationrootnode.md), 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 [Object.get_property_list()](class_object.md#class_Object_method_get_property_list). + +
+ + + + + +[bool](class_bool.md) **_has_filter**\ (\ ) virtual const [🔗](#class_AnimationNode_private_method__has_filter) + +When inheriting from [AnimationRootNode](class_animationrootnode.md), implement this virtual method to return whether the blend tree editor should display filter editing on this animation node. + +
+ + + + + +[bool](class_bool.md) **_is_parameter_read_only**\ (\ parameter\: [StringName](class_stringname.md)\ ) virtual const [🔗](#class_AnimationNode_private_method__is_parameter_read_only) + +When inheriting from [AnimationRootNode](class_animationrootnode.md), implement this virtual method to return whether the `parameter` is read-only. Parameters are custom local memory used for your animation nodes, given a resource can be reused in multiple trees. + +
+ + + + + +[float](class_float.md) **_process**\ (\ time\: [float](class_float.md), seek\: [bool](class_bool.md), is_external_seeking\: [bool](class_bool.md), test_only\: [bool](class_bool.md)\ ) virtual [🔗](#class_AnimationNode_private_method__process) + +**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. + +When inheriting from [AnimationRootNode](class_animationrootnode.md), implement this virtual method to run some code when this animation node is processed. The `time` parameter is a relative delta, unless `seek` is ``true``, in which case it is absolute. + +Here, call the [blend_input()](class_animationnode.md#class_AnimationNode_method_blend_input), [blend_node()](class_animationnode.md#class_AnimationNode_method_blend_node) or [blend_animation()](class_animationnode.md#class_AnimationNode_method_blend_animation) functions. You can also use [get_parameter()](class_animationnode.md#class_AnimationNode_method_get_parameter) and [set_parameter()](class_animationnode.md#class_AnimationNode_method_set_parameter) to modify local memory. + +This function should return the delta. + +
+ + + + + +[bool](class_bool.md) **add_input**\ (\ name\: [String](class_string.md)\ ) [🔗](#class_AnimationNode_method_add_input) + +Adds an input to the animation node. This is only useful for animation nodes created for use in an [AnimationNodeBlendTree](class_animationnodeblendtree.md). If the addition fails, returns ``false``. + +
+ + + + + +`void` **blend_animation**\ (\ animation\: [StringName](class_stringname.md), time\: [float](class_float.md), delta\: [float](class_float.md), seeked\: [bool](class_bool.md), is_external_seeking\: [bool](class_bool.md), blend\: [float](class_float.md), looped_flag\: [LoopedFlag](class_animation.md#enum_Animation_LoopedFlag) = 0\ ) [🔗](#class_AnimationNode_method_blend_animation) + +Blends an animation by `blend` amount (name must be valid in the linked [AnimationPlayer](class_animationplayer.md)). A `time` and `delta` may be passed, as well as whether `seeked` happened. + +A `looped_flag` is used by internal processing immediately after the loop. + +
+ + + + + +[float](class_float.md) **blend_input**\ (\ input_index\: [int](class_int.md), time\: [float](class_float.md), seek\: [bool](class_bool.md), is_external_seeking\: [bool](class_bool.md), blend\: [float](class_float.md), filter\: [FilterAction](class_animationnode.md#enum_AnimationNode_FilterAction) = 0, sync\: [bool](class_bool.md) = true, test_only\: [bool](class_bool.md) = false\ ) [🔗](#class_AnimationNode_method_blend_input) + +Blends an input. This is only useful for animation nodes created for an [AnimationNodeBlendTree](class_animationnodeblendtree.md). The `time` parameter is a relative delta, unless `seek` is ``true``, in which case it is absolute. A filter mode may be optionally passed. + +
+ + + + + +[float](class_float.md) **blend_node**\ (\ name\: [StringName](class_stringname.md), node\: [AnimationNode](class_animationnode.md), time\: [float](class_float.md), seek\: [bool](class_bool.md), is_external_seeking\: [bool](class_bool.md), blend\: [float](class_float.md), filter\: [FilterAction](class_animationnode.md#enum_AnimationNode_FilterAction) = 0, sync\: [bool](class_bool.md) = true, test_only\: [bool](class_bool.md) = false\ ) [🔗](#class_AnimationNode_method_blend_node) + +Blend another animation node (in case this animation node contains child animation nodes). This function is only useful if you inherit from [AnimationRootNode](class_animationrootnode.md) instead, otherwise editors will not display your animation node for addition. + +
+ + + + + +[int](class_int.md) **find_input**\ (\ name\: [String](class_string.md)\ ) const [🔗](#class_AnimationNode_method_find_input) + +Returns the input index which corresponds to `name`. If not found, returns ``-1``. + +
+ + + + + +[int](class_int.md) **get_input_count**\ (\ ) const [🔗](#class_AnimationNode_method_get_input_count) + +Amount of inputs in this animation node, only useful for animation nodes that go into [AnimationNodeBlendTree](class_animationnodeblendtree.md). + +
+ + + + + +[String](class_string.md) **get_input_name**\ (\ input\: [int](class_int.md)\ ) const [🔗](#class_AnimationNode_method_get_input_name) + +Gets the name of an input by index. + +
+ + + + + +[Variant](class_variant.md) **get_parameter**\ (\ name\: [StringName](class_stringname.md)\ ) const [🔗](#class_AnimationNode_method_get_parameter) + +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. + +
+ + + + + +[int](class_int.md) **get_processing_animation_tree_instance_id**\ (\ ) const [🔗](#class_AnimationNode_method_get_processing_animation_tree_instance_id) + +Returns the object id of the [AnimationTree](class_animationtree.md) that owns this node. + +\ **Note:** This method should only be called from within the [AnimationNodeExtension._process_animation_node()](class_animationnodeextension.md#class_AnimationNodeExtension_private_method__process_animation_node) method, and will return an invalid id otherwise. + +
+ + + + + +[bool](class_bool.md) **is_path_filtered**\ (\ path\: [NodePath](class_nodepath.md)\ ) const [🔗](#class_AnimationNode_method_is_path_filtered) + +Returns ``true`` if the given path is filtered. + +
+ + + + + +[bool](class_bool.md) **is_process_testing**\ (\ ) const [🔗](#class_AnimationNode_method_is_process_testing) + +Returns ``true`` if this animation node is being processed in test-only mode. + +
+ + + + + +`void` **remove_input**\ (\ index\: [int](class_int.md)\ ) [🔗](#class_AnimationNode_method_remove_input) + +Removes an input, call this only when inactive. + +
+ + + + + +`void` **set_filter_path**\ (\ path\: [NodePath](class_nodepath.md), enable\: [bool](class_bool.md)\ ) [🔗](#class_AnimationNode_method_set_filter_path) + +Adds or removes a path for the filter. + +
+ + + + + +[bool](class_bool.md) **set_input_name**\ (\ input\: [int](class_int.md), name\: [String](class_string.md)\ ) [🔗](#class_AnimationNode_method_set_input_name) + +Sets the name of the input at the given `input` index. If the setting fails, returns ``false``. + +
+ + + + + +`void` **set_parameter**\ (\ name\: [StringName](class_stringname.md), value\: [Variant](class_variant.md)\ ) [🔗](#class_AnimationNode_method_set_parameter) + +Sets a custom parameter. These are used as local memory, because resources can be reused across the tree or scenes. + diff --git a/docs/Classes/class_animationnodeadd2.md b/docs/Classes/class_animationnodeadd2.md new file mode 100644 index 00000000..aa0e4322 --- /dev/null +++ b/docs/Classes/class_animationnodeadd2.md @@ -0,0 +1,31 @@ + + + + + + + + + +# AnimationNodeAdd2 + +**Inherits:** [AnimationNodeSync](class_animationnodesync.md) **<** [AnimationNode](class_animationnode.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Blends two animations additively inside of an [AnimationNodeBlendTree](class_animationnodeblendtree.md). + + + +## Description + +A resource to add to an [AnimationNodeBlendTree](class_animationnodeblendtree.md). Blends two animations additively based on the amount value. + +If the amount is greater than ``1.0``, the animation connected to "in" port is blended with the amplified animation connected to "add" port. + +If the amount is less than ``0.0``, the animation connected to "in" port is blended with the inverted animation connected to "add" port. + + + +## Tutorials + +- [Using AnimationTree](../tutorials/animation/animation_tree.md) + diff --git a/docs/Classes/class_animationnodeadd3.md b/docs/Classes/class_animationnodeadd3.md new file mode 100644 index 00000000..8cde8be7 --- /dev/null +++ b/docs/Classes/class_animationnodeadd3.md @@ -0,0 +1,39 @@ + + + + + + + + + +# AnimationNodeAdd3 + +**Inherits:** [AnimationNodeSync](class_animationnodesync.md) **<** [AnimationNode](class_animationnode.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Blends two of three animations additively inside of an [AnimationNodeBlendTree](class_animationnodeblendtree.md). + + + +## Description + +A resource to add to an [AnimationNodeBlendTree](class_animationnodeblendtree.md). 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 ``1.0``, the animation connected to "in" port is blended with the amplified animation connected to "-add"/"+add" port. + + + +## Tutorials + +- [Using AnimationTree](../tutorials/animation/animation_tree.md) + +- [Third Person Shooter (TPS) Demo](https://godotengine.org/asset-library/asset/2710) + diff --git a/docs/Classes/class_animationnodeanimation.md b/docs/Classes/class_animationnodeanimation.md new file mode 100644 index 00000000..c0eb85f1 --- /dev/null +++ b/docs/Classes/class_animationnodeanimation.md @@ -0,0 +1,240 @@ + + + + + + + + + +# AnimationNodeAnimation + +**Inherits:** [AnimationRootNode](class_animationrootnode.md) **<** [AnimationNode](class_animationnode.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +An input animation for an [AnimationNodeBlendTree](class_animationnodeblendtree.md). + + + +## Description + +A resource to add to an [AnimationNodeBlendTree](class_animationnodeblendtree.md). Only has one output port using the [animation](class_animationnodeanimation.md#class_AnimationNodeAnimation_property_animation) property. Used as an input for [AnimationNode](class_animationnode.md)\ s that blend animations together. + + + +## Tutorials + +- [Using AnimationTree](../tutorials/animation/animation_tree.md) + +- [3D Platformer Demo](https://godotengine.org/asset-library/asset/2748) + +- [Third Person Shooter (TPS) Demo](https://godotengine.org/asset-library/asset/2710) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[advance_on_start](#class_AnimationNodeAnimation_property_advance_on_start)`false`
[StringName](class_stringname.md)[animation](#class_AnimationNodeAnimation_property_animation)`&""`
[LoopMode](class_animation.md#enum_Animation_LoopMode)[loop_mode](#class_AnimationNodeAnimation_property_loop_mode)
[PlayMode](class_animationnodeanimation.md#enum_AnimationNodeAnimation_PlayMode)[play_mode](#class_AnimationNodeAnimation_property_play_mode)`0`
[float](class_float.md)[start_offset](#class_AnimationNodeAnimation_property_start_offset)
[bool](class_bool.md)[stretch_time_scale](#class_AnimationNodeAnimation_property_stretch_time_scale)
[float](class_float.md)[timeline_length](#class_AnimationNodeAnimation_property_timeline_length)
[bool](class_bool.md)[use_custom_timeline](#class_AnimationNodeAnimation_property_use_custom_timeline)`false`
+ +
+ + + +## Enumerations + + + + + +enum **PlayMode**: [🔗](#enum_AnimationNodeAnimation_PlayMode) + + + + + +[PlayMode](class_animationnodeanimation.md#enum_AnimationNodeAnimation_PlayMode) **PLAY_MODE_FORWARD** = `0` + +Plays animation in forward direction. + + + +[PlayMode](class_animationnodeanimation.md#enum_AnimationNodeAnimation_PlayMode) **PLAY_MODE_BACKWARD** = `1` + +Plays animation in backward direction.
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **advance_on_start** = `false` [🔗](#class_AnimationNodeAnimation_property_advance_on_start) + + + +- `void` **set_advance_on_start**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_advance_on_start**\ (\ ) + +If ``true``, 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 [AnimationPlayer.play()](class_animationplayer.md#class_AnimationPlayer_method_play). + +
+ + + + + +[StringName](class_stringname.md) **animation** = `&""` [🔗](#class_AnimationNodeAnimation_property_animation) + + + +- `void` **set_animation**\ (\ value\: [StringName](class_stringname.md)\ ) +- [StringName](class_stringname.md) **get_animation**\ (\ ) + +Animation to use as an output. It is one of the animations provided by [AnimationTree.anim_player](class_animationtree.md#class_AnimationTree_property_anim_player). + +
+ + + + + +[LoopMode](class_animation.md#enum_Animation_LoopMode) **loop_mode** [🔗](#class_AnimationNodeAnimation_property_loop_mode) + + + +- `void` **set_loop_mode**\ (\ value\: [LoopMode](class_animation.md#enum_Animation_LoopMode)\ ) +- [LoopMode](class_animation.md#enum_Animation_LoopMode) **get_loop_mode**\ (\ ) + +If [use_custom_timeline](class_animationnodeanimation.md#class_AnimationNodeAnimation_property_use_custom_timeline) is ``true``, override the loop settings of the original [Animation](class_animation.md) resource with the value. + +\ **Note:** If the [Animation.loop_mode](class_animation.md#class_Animation_property_loop_mode) isn't set to looping, the [Animation.track_set_interpolation_loop_wrap()](class_animation.md#class_Animation_method_track_set_interpolation_loop_wrap) option will not be respected. If you cannot get the expected behavior, consider duplicating the [Animation](class_animation.md) resource and changing the loop settings. + +
+ + + + + +[PlayMode](class_animationnodeanimation.md#enum_AnimationNodeAnimation_PlayMode) **play_mode** = `0` [🔗](#class_AnimationNodeAnimation_property_play_mode) + + + +- `void` **set_play_mode**\ (\ value\: [PlayMode](class_animationnodeanimation.md#enum_AnimationNodeAnimation_PlayMode)\ ) +- [PlayMode](class_animationnodeanimation.md#enum_AnimationNodeAnimation_PlayMode) **get_play_mode**\ (\ ) + +Determines the playback direction of the animation. + +
+ + + + + +[float](class_float.md) **start_offset** [🔗](#class_AnimationNodeAnimation_property_start_offset) + + + +- `void` **set_start_offset**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_start_offset**\ (\ ) + +If [use_custom_timeline](class_animationnodeanimation.md#class_AnimationNodeAnimation_property_use_custom_timeline) is ``true``, offset the start position of the animation. + +This is useful for adjusting which foot steps first in 3D walking animations. + +
+ + + + + +[bool](class_bool.md) **stretch_time_scale** [🔗](#class_AnimationNodeAnimation_property_stretch_time_scale) + + + +- `void` **set_stretch_time_scale**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_stretching_time_scale**\ (\ ) + +If ``true``, scales the time so that the length specified in [timeline_length](class_animationnodeanimation.md#class_AnimationNodeAnimation_property_timeline_length) is one cycle. + +This is useful for matching the periods of walking and running animations. + +If ``false``, the original animation length is respected. If you set the loop to [loop_mode](class_animationnodeanimation.md#class_AnimationNodeAnimation_property_loop_mode), the animation will loop in [timeline_length](class_animationnodeanimation.md#class_AnimationNodeAnimation_property_timeline_length). + +
+ + + + + +[float](class_float.md) **timeline_length** [🔗](#class_AnimationNodeAnimation_property_timeline_length) + + + +- `void` **set_timeline_length**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_timeline_length**\ (\ ) + +If [use_custom_timeline](class_animationnodeanimation.md#class_AnimationNodeAnimation_property_use_custom_timeline) is ``true``, offset the start position of the animation. + +
+ + + + + +[bool](class_bool.md) **use_custom_timeline** = `false` [🔗](#class_AnimationNodeAnimation_property_use_custom_timeline) + + + +- `void` **set_use_custom_timeline**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_using_custom_timeline**\ (\ ) + +If ``true``, [AnimationNode](class_animationnode.md) provides an animation based on the [Animation](class_animation.md) resource with some parameters adjusted. + diff --git a/docs/Classes/class_animationnodeblend2.md b/docs/Classes/class_animationnodeblend2.md new file mode 100644 index 00000000..8ff22507 --- /dev/null +++ b/docs/Classes/class_animationnodeblend2.md @@ -0,0 +1,33 @@ + + + + + + + + + +# AnimationNodeBlend2 + +**Inherits:** [AnimationNodeSync](class_animationnodesync.md) **<** [AnimationNode](class_animationnode.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Blends two animations linearly inside of an [AnimationNodeBlendTree](class_animationnodeblendtree.md). + + + +## Description + +A resource to add to an [AnimationNodeBlendTree](class_animationnodeblendtree.md). Blends two animations linearly based on the amount value. + +In general, the blend value should be in the ``[0.0, 1.0]`` range. Values outside of this range can blend amplified or inverted animations, however, [AnimationNodeAdd2](class_animationnodeadd2.md) works better for this purpose. + + + +## Tutorials + +- [Using AnimationTree](../tutorials/animation/animation_tree.md) + +- [3D Platformer Demo](https://godotengine.org/asset-library/asset/2748) + +- [Third Person Shooter (TPS) Demo](https://godotengine.org/asset-library/asset/2710) + diff --git a/docs/Classes/class_animationnodeblend3.md b/docs/Classes/class_animationnodeblend3.md new file mode 100644 index 00000000..0fcaac59 --- /dev/null +++ b/docs/Classes/class_animationnodeblend3.md @@ -0,0 +1,37 @@ + + + + + + + + + +# AnimationNodeBlend3 + +**Inherits:** [AnimationNodeSync](class_animationnodesync.md) **<** [AnimationNode](class_animationnode.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Blends two of three animations linearly inside of an [AnimationNodeBlendTree](class_animationnodeblendtree.md). + + + +## Description + +A resource to add to an [AnimationNodeBlendTree](class_animationnodeblendtree.md). 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 ``[-1.0, 1.0]`` range. Values outside of this range can blend amplified animations, however, [AnimationNodeAdd3](class_animationnodeadd3.md) works better for this purpose. + + + +## Tutorials + +- [Using AnimationTree](../tutorials/animation/animation_tree.md) + diff --git a/docs/Classes/class_animationnodeblendspace1d.md b/docs/Classes/class_animationnodeblendspace1d.md new file mode 100644 index 00000000..c3c191a1 --- /dev/null +++ b/docs/Classes/class_animationnodeblendspace1d.md @@ -0,0 +1,311 @@ + + + + + + + + + +# AnimationNodeBlendSpace1D + +**Inherits:** [AnimationRootNode](class_animationrootnode.md) **<** [AnimationNode](class_animationnode.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +A set of [AnimationRootNode](class_animationrootnode.md)\ s placed on a virtual axis, crossfading between the two adjacent ones. Used by [AnimationTree](class_animationtree.md). + + + +## Description + +A resource used by [AnimationNodeBlendTree](class_animationnodeblendtree.md). + +\ **AnimationNodeBlendSpace1D** represents a virtual axis on which any type of [AnimationRootNode](class_animationrootnode.md)\ s can be added using [add_blend_point()](class_animationnodeblendspace1d.md#class_AnimationNodeBlendSpace1D_method_add_blend_point). Outputs the linear blend of the two [AnimationRootNode](class_animationrootnode.md)\ s adjacent to the current value. + +You can set the extents of the axis with [min_space](class_animationnodeblendspace1d.md#class_AnimationNodeBlendSpace1D_property_min_space) and [max_space](class_animationnodeblendspace1d.md#class_AnimationNodeBlendSpace1D_property_max_space). + + + +## Tutorials + +- [Using AnimationTree](../tutorials/animation/animation_tree.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[BlendMode](class_animationnodeblendspace1d.md#enum_AnimationNodeBlendSpace1D_BlendMode)[blend_mode](#class_AnimationNodeBlendSpace1D_property_blend_mode)`0`
[float](class_float.md)[max_space](#class_AnimationNodeBlendSpace1D_property_max_space)`1.0`
[float](class_float.md)[min_space](#class_AnimationNodeBlendSpace1D_property_min_space)`-1.0`
[float](class_float.md)[snap](#class_AnimationNodeBlendSpace1D_property_snap)`0.1`
[bool](class_bool.md)[sync](#class_AnimationNodeBlendSpace1D_property_sync)`false`
[String](class_string.md)[value_label](#class_AnimationNodeBlendSpace1D_property_value_label)`"value"`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
`void`[add_blend_point](#class_AnimationNodeBlendSpace1D_method_add_blend_point)\ (\ node\: [AnimationRootNode](class_animationrootnode.md), pos\: [float](class_float.md), at_index\: [int](class_int.md) = -1\ )
[int](class_int.md)[get_blend_point_count](#class_AnimationNodeBlendSpace1D_method_get_blend_point_count)\ (\ ) const
[AnimationRootNode](class_animationrootnode.md)[get_blend_point_node](#class_AnimationNodeBlendSpace1D_method_get_blend_point_node)\ (\ point\: [int](class_int.md)\ ) const
[float](class_float.md)[get_blend_point_position](#class_AnimationNodeBlendSpace1D_method_get_blend_point_position)\ (\ point\: [int](class_int.md)\ ) const
`void`[remove_blend_point](#class_AnimationNodeBlendSpace1D_method_remove_blend_point)\ (\ point\: [int](class_int.md)\ )
`void`[set_blend_point_node](#class_AnimationNodeBlendSpace1D_method_set_blend_point_node)\ (\ point\: [int](class_int.md), node\: [AnimationRootNode](class_animationrootnode.md)\ )
`void`[set_blend_point_position](#class_AnimationNodeBlendSpace1D_method_set_blend_point_position)\ (\ point\: [int](class_int.md), pos\: [float](class_float.md)\ )
+ +
+ + + +## Enumerations + + + + + +enum **BlendMode**: [🔗](#enum_AnimationNodeBlendSpace1D_BlendMode) + + + + + +[BlendMode](class_animationnodeblendspace1d.md#enum_AnimationNodeBlendSpace1D_BlendMode) **BLEND_MODE_INTERPOLATED** = `0` + +The interpolation between animations is linear. + + + +[BlendMode](class_animationnodeblendspace1d.md#enum_AnimationNodeBlendSpace1D_BlendMode) **BLEND_MODE_DISCRETE** = `1` + +The blend space plays the animation of the animation node which blending position is closest to. Useful for frame-by-frame 2D animations. + + + +[BlendMode](class_animationnodeblendspace1d.md#enum_AnimationNodeBlendSpace1D_BlendMode) **BLEND_MODE_DISCRETE_CARRY** = `2` + +Similar to [BLEND_MODE_DISCRETE](class_animationnodeblendspace1d.md#class_AnimationNodeBlendSpace1D_constant_BLEND_MODE_DISCRETE), but starts the new animation at the last animation's playback position.
+ + + +## Property Descriptions + + + + + +[BlendMode](class_animationnodeblendspace1d.md#enum_AnimationNodeBlendSpace1D_BlendMode) **blend_mode** = `0` [🔗](#class_AnimationNodeBlendSpace1D_property_blend_mode) + + + +- `void` **set_blend_mode**\ (\ value\: [BlendMode](class_animationnodeblendspace1d.md#enum_AnimationNodeBlendSpace1D_BlendMode)\ ) +- [BlendMode](class_animationnodeblendspace1d.md#enum_AnimationNodeBlendSpace1D_BlendMode) **get_blend_mode**\ (\ ) + +Controls the interpolation between animations. + +
+ + + + + +[float](class_float.md) **max_space** = `1.0` [🔗](#class_AnimationNodeBlendSpace1D_property_max_space) + + + +- `void` **set_max_space**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_max_space**\ (\ ) + +The blend space's axis's upper limit for the points' position. See [add_blend_point()](class_animationnodeblendspace1d.md#class_AnimationNodeBlendSpace1D_method_add_blend_point). + +
+ + + + + +[float](class_float.md) **min_space** = `-1.0` [🔗](#class_AnimationNodeBlendSpace1D_property_min_space) + + + +- `void` **set_min_space**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_min_space**\ (\ ) + +The blend space's axis's lower limit for the points' position. See [add_blend_point()](class_animationnodeblendspace1d.md#class_AnimationNodeBlendSpace1D_method_add_blend_point). + +
+ + + + + +[float](class_float.md) **snap** = `0.1` [🔗](#class_AnimationNodeBlendSpace1D_property_snap) + + + +- `void` **set_snap**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_snap**\ (\ ) + +Position increment to snap to when moving a point on the axis. + +
+ + + + + +[bool](class_bool.md) **sync** = `false` [🔗](#class_AnimationNodeBlendSpace1D_property_sync) + + + +- `void` **set_use_sync**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_using_sync**\ (\ ) + +If ``false``, the blended animations' frame are stopped when the blend value is ``0``. + +If ``true``, forcing the blended animations to advance frame. + +
+ + + + + +[String](class_string.md) **value_label** = `"value"` [🔗](#class_AnimationNodeBlendSpace1D_property_value_label) + + + +- `void` **set_value_label**\ (\ value\: [String](class_string.md)\ ) +- [String](class_string.md) **get_value_label**\ (\ ) + +Label of the virtual axis of the blend space. + +
+ + + +## Method Descriptions + + + + + +`void` **add_blend_point**\ (\ node\: [AnimationRootNode](class_animationrootnode.md), pos\: [float](class_float.md), at_index\: [int](class_int.md) = -1\ ) [🔗](#class_AnimationNodeBlendSpace1D_method_add_blend_point) + +Adds a new point that represents a `node` on the virtual axis at a given position set by `pos`. You can insert it at a specific index using the `at_index` argument. If you use the default value for `at_index`, the point is inserted at the end of the blend points array. + +
+ + + + + +[int](class_int.md) **get_blend_point_count**\ (\ ) const [🔗](#class_AnimationNodeBlendSpace1D_method_get_blend_point_count) + +Returns the number of points on the blend axis. + +
+ + + + + +[AnimationRootNode](class_animationrootnode.md) **get_blend_point_node**\ (\ point\: [int](class_int.md)\ ) const [🔗](#class_AnimationNodeBlendSpace1D_method_get_blend_point_node) + +Returns the [AnimationNode](class_animationnode.md) referenced by the point at index `point`. + +
+ + + + + +[float](class_float.md) **get_blend_point_position**\ (\ point\: [int](class_int.md)\ ) const [🔗](#class_AnimationNodeBlendSpace1D_method_get_blend_point_position) + +Returns the position of the point at index `point`. + +
+ + + + + +`void` **remove_blend_point**\ (\ point\: [int](class_int.md)\ ) [🔗](#class_AnimationNodeBlendSpace1D_method_remove_blend_point) + +Removes the point at index `point` from the blend axis. + +
+ + + + + +`void` **set_blend_point_node**\ (\ point\: [int](class_int.md), node\: [AnimationRootNode](class_animationrootnode.md)\ ) [🔗](#class_AnimationNodeBlendSpace1D_method_set_blend_point_node) + +Changes the [AnimationNode](class_animationnode.md) referenced by the point at index `point`. + +
+ + + + + +`void` **set_blend_point_position**\ (\ point\: [int](class_int.md), pos\: [float](class_float.md)\ ) [🔗](#class_AnimationNodeBlendSpace1D_method_set_blend_point_position) + +Updates the position of the point at index `point` on the blend axis. + diff --git a/docs/Classes/class_animationnodeblendspace2d.md b/docs/Classes/class_animationnodeblendspace2d.md new file mode 100644 index 00000000..70582bd8 --- /dev/null +++ b/docs/Classes/class_animationnodeblendspace2d.md @@ -0,0 +1,423 @@ + + + + + + + + + +# AnimationNodeBlendSpace2D + +**Inherits:** [AnimationRootNode](class_animationrootnode.md) **<** [AnimationNode](class_animationnode.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +A set of [AnimationRootNode](class_animationrootnode.md)\ s placed on 2D coordinates, crossfading between the three adjacent ones. Used by [AnimationTree](class_animationtree.md). + + + +## Description + +A resource used by [AnimationNodeBlendTree](class_animationnodeblendtree.md). + +\ **AnimationNodeBlendSpace2D** represents a virtual 2D space on which [AnimationRootNode](class_animationrootnode.md)\ s are placed. Outputs the linear blend of the three adjacent animations using a [Vector2](class_vector2.md) weight. Adjacent in this context means the three [AnimationRootNode](class_animationrootnode.md)\ s making up the triangle that contains the current value. + +You can add vertices to the blend space with [add_blend_point()](class_animationnodeblendspace2d.md#class_AnimationNodeBlendSpace2D_method_add_blend_point) and automatically triangulate it by setting [auto_triangles](class_animationnodeblendspace2d.md#class_AnimationNodeBlendSpace2D_property_auto_triangles) to ``true``. Otherwise, use [add_triangle()](class_animationnodeblendspace2d.md#class_AnimationNodeBlendSpace2D_method_add_triangle) and [remove_triangle()](class_animationnodeblendspace2d.md#class_AnimationNodeBlendSpace2D_method_remove_triangle) to triangulate the blend space by hand. + + + +## Tutorials + +- [Using AnimationTree](../tutorials/animation/animation_tree.md) + +- [Third Person Shooter (TPS) Demo](https://godotengine.org/asset-library/asset/2710) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[auto_triangles](#class_AnimationNodeBlendSpace2D_property_auto_triangles)`true`
[BlendMode](class_animationnodeblendspace2d.md#enum_AnimationNodeBlendSpace2D_BlendMode)[blend_mode](#class_AnimationNodeBlendSpace2D_property_blend_mode)`0`
[Vector2](class_vector2.md)[max_space](#class_AnimationNodeBlendSpace2D_property_max_space)`Vector2(1, 1)`
[Vector2](class_vector2.md)[min_space](#class_AnimationNodeBlendSpace2D_property_min_space)`Vector2(-1, -1)`
[Vector2](class_vector2.md)[snap](#class_AnimationNodeBlendSpace2D_property_snap)`Vector2(0.1, 0.1)`
[bool](class_bool.md)[sync](#class_AnimationNodeBlendSpace2D_property_sync)`false`
[String](class_string.md)[x_label](#class_AnimationNodeBlendSpace2D_property_x_label)`"x"`
[String](class_string.md)[y_label](#class_AnimationNodeBlendSpace2D_property_y_label)`"y"`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
`void`[add_blend_point](#class_AnimationNodeBlendSpace2D_method_add_blend_point)\ (\ node\: [AnimationRootNode](class_animationrootnode.md), pos\: [Vector2](class_vector2.md), at_index\: [int](class_int.md) = -1\ )
`void`[add_triangle](#class_AnimationNodeBlendSpace2D_method_add_triangle)\ (\ x\: [int](class_int.md), y\: [int](class_int.md), z\: [int](class_int.md), at_index\: [int](class_int.md) = -1\ )
[int](class_int.md)[get_blend_point_count](#class_AnimationNodeBlendSpace2D_method_get_blend_point_count)\ (\ ) const
[AnimationRootNode](class_animationrootnode.md)[get_blend_point_node](#class_AnimationNodeBlendSpace2D_method_get_blend_point_node)\ (\ point\: [int](class_int.md)\ ) const
[Vector2](class_vector2.md)[get_blend_point_position](#class_AnimationNodeBlendSpace2D_method_get_blend_point_position)\ (\ point\: [int](class_int.md)\ ) const
[int](class_int.md)[get_triangle_count](#class_AnimationNodeBlendSpace2D_method_get_triangle_count)\ (\ ) const
[int](class_int.md)[get_triangle_point](#class_AnimationNodeBlendSpace2D_method_get_triangle_point)\ (\ triangle\: [int](class_int.md), point\: [int](class_int.md)\ )
`void`[remove_blend_point](#class_AnimationNodeBlendSpace2D_method_remove_blend_point)\ (\ point\: [int](class_int.md)\ )
`void`[remove_triangle](#class_AnimationNodeBlendSpace2D_method_remove_triangle)\ (\ triangle\: [int](class_int.md)\ )
`void`[set_blend_point_node](#class_AnimationNodeBlendSpace2D_method_set_blend_point_node)\ (\ point\: [int](class_int.md), node\: [AnimationRootNode](class_animationrootnode.md)\ )
`void`[set_blend_point_position](#class_AnimationNodeBlendSpace2D_method_set_blend_point_position)\ (\ point\: [int](class_int.md), pos\: [Vector2](class_vector2.md)\ )
+ +
+ + + +## Signals + + + + + +**triangles_updated**\ (\ ) [🔗](#class_AnimationNodeBlendSpace2D_signal_triangles_updated) + +Emitted every time the blend space's triangles are created, removed, or when one of their vertices changes position. + +
+ + + +## Enumerations + + + + + +enum **BlendMode**: [🔗](#enum_AnimationNodeBlendSpace2D_BlendMode) + + + + + +[BlendMode](class_animationnodeblendspace2d.md#enum_AnimationNodeBlendSpace2D_BlendMode) **BLEND_MODE_INTERPOLATED** = `0` + +The interpolation between animations is linear. + + + +[BlendMode](class_animationnodeblendspace2d.md#enum_AnimationNodeBlendSpace2D_BlendMode) **BLEND_MODE_DISCRETE** = `1` + +The blend space plays the animation of the animation node which blending position is closest to. Useful for frame-by-frame 2D animations. + + + +[BlendMode](class_animationnodeblendspace2d.md#enum_AnimationNodeBlendSpace2D_BlendMode) **BLEND_MODE_DISCRETE_CARRY** = `2` + +Similar to [BLEND_MODE_DISCRETE](class_animationnodeblendspace2d.md#class_AnimationNodeBlendSpace2D_constant_BLEND_MODE_DISCRETE), but starts the new animation at the last animation's playback position.
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **auto_triangles** = `true` [🔗](#class_AnimationNodeBlendSpace2D_property_auto_triangles) + + + +- `void` **set_auto_triangles**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_auto_triangles**\ (\ ) + +If ``true``, the blend space is triangulated automatically. The mesh updates every time you add or remove points with [add_blend_point()](class_animationnodeblendspace2d.md#class_AnimationNodeBlendSpace2D_method_add_blend_point) and [remove_blend_point()](class_animationnodeblendspace2d.md#class_AnimationNodeBlendSpace2D_method_remove_blend_point). + +
+ + + + + +[BlendMode](class_animationnodeblendspace2d.md#enum_AnimationNodeBlendSpace2D_BlendMode) **blend_mode** = `0` [🔗](#class_AnimationNodeBlendSpace2D_property_blend_mode) + + + +- `void` **set_blend_mode**\ (\ value\: [BlendMode](class_animationnodeblendspace2d.md#enum_AnimationNodeBlendSpace2D_BlendMode)\ ) +- [BlendMode](class_animationnodeblendspace2d.md#enum_AnimationNodeBlendSpace2D_BlendMode) **get_blend_mode**\ (\ ) + +Controls the interpolation between animations. + +
+ + + + + +[Vector2](class_vector2.md) **max_space** = `Vector2(1, 1)` [🔗](#class_AnimationNodeBlendSpace2D_property_max_space) + + + +- `void` **set_max_space**\ (\ value\: [Vector2](class_vector2.md)\ ) +- [Vector2](class_vector2.md) **get_max_space**\ (\ ) + +The blend space's X and Y axes' upper limit for the points' position. See [add_blend_point()](class_animationnodeblendspace2d.md#class_AnimationNodeBlendSpace2D_method_add_blend_point). + +
+ + + + + +[Vector2](class_vector2.md) **min_space** = `Vector2(-1, -1)` [🔗](#class_AnimationNodeBlendSpace2D_property_min_space) + + + +- `void` **set_min_space**\ (\ value\: [Vector2](class_vector2.md)\ ) +- [Vector2](class_vector2.md) **get_min_space**\ (\ ) + +The blend space's X and Y axes' lower limit for the points' position. See [add_blend_point()](class_animationnodeblendspace2d.md#class_AnimationNodeBlendSpace2D_method_add_blend_point). + +
+ + + + + +[Vector2](class_vector2.md) **snap** = `Vector2(0.1, 0.1)` [🔗](#class_AnimationNodeBlendSpace2D_property_snap) + + + +- `void` **set_snap**\ (\ value\: [Vector2](class_vector2.md)\ ) +- [Vector2](class_vector2.md) **get_snap**\ (\ ) + +Position increment to snap to when moving a point. + +
+ + + + + +[bool](class_bool.md) **sync** = `false` [🔗](#class_AnimationNodeBlendSpace2D_property_sync) + + + +- `void` **set_use_sync**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_using_sync**\ (\ ) + +If ``false``, the blended animations' frame are stopped when the blend value is ``0``. + +If ``true``, forcing the blended animations to advance frame. + +
+ + + + + +[String](class_string.md) **x_label** = `"x"` [🔗](#class_AnimationNodeBlendSpace2D_property_x_label) + + + +- `void` **set_x_label**\ (\ value\: [String](class_string.md)\ ) +- [String](class_string.md) **get_x_label**\ (\ ) + +Name of the blend space's X axis. + +
+ + + + + +[String](class_string.md) **y_label** = `"y"` [🔗](#class_AnimationNodeBlendSpace2D_property_y_label) + + + +- `void` **set_y_label**\ (\ value\: [String](class_string.md)\ ) +- [String](class_string.md) **get_y_label**\ (\ ) + +Name of the blend space's Y axis. + +
+ + + +## Method Descriptions + + + + + +`void` **add_blend_point**\ (\ node\: [AnimationRootNode](class_animationrootnode.md), pos\: [Vector2](class_vector2.md), at_index\: [int](class_int.md) = -1\ ) [🔗](#class_AnimationNodeBlendSpace2D_method_add_blend_point) + +Adds a new point that represents a `node` at the position set by `pos`. You can insert it at a specific index using the `at_index` argument. If you use the default value for `at_index`, the point is inserted at the end of the blend points array. + +
+ + + + + +`void` **add_triangle**\ (\ x\: [int](class_int.md), y\: [int](class_int.md), z\: [int](class_int.md), at_index\: [int](class_int.md) = -1\ ) [🔗](#class_AnimationNodeBlendSpace2D_method_add_triangle) + +Creates a new triangle using three points `x`, `y`, and `z`. Triangles can overlap. You can insert the triangle at a specific index using the `at_index` argument. If you use the default value for `at_index`, the point is inserted at the end of the blend points array. + +
+ + + + + +[int](class_int.md) **get_blend_point_count**\ (\ ) const [🔗](#class_AnimationNodeBlendSpace2D_method_get_blend_point_count) + +Returns the number of points in the blend space. + +
+ + + + + +[AnimationRootNode](class_animationrootnode.md) **get_blend_point_node**\ (\ point\: [int](class_int.md)\ ) const [🔗](#class_AnimationNodeBlendSpace2D_method_get_blend_point_node) + +Returns the [AnimationRootNode](class_animationrootnode.md) referenced by the point at index `point`. + +
+ + + + + +[Vector2](class_vector2.md) **get_blend_point_position**\ (\ point\: [int](class_int.md)\ ) const [🔗](#class_AnimationNodeBlendSpace2D_method_get_blend_point_position) + +Returns the position of the point at index `point`. + +
+ + + + + +[int](class_int.md) **get_triangle_count**\ (\ ) const [🔗](#class_AnimationNodeBlendSpace2D_method_get_triangle_count) + +Returns the number of triangles in the blend space. + +
+ + + + + +[int](class_int.md) **get_triangle_point**\ (\ triangle\: [int](class_int.md), point\: [int](class_int.md)\ ) [🔗](#class_AnimationNodeBlendSpace2D_method_get_triangle_point) + +Returns the position of the point at index `point` in the triangle of index `triangle`. + +
+ + + + + +`void` **remove_blend_point**\ (\ point\: [int](class_int.md)\ ) [🔗](#class_AnimationNodeBlendSpace2D_method_remove_blend_point) + +Removes the point at index `point` from the blend space. + +
+ + + + + +`void` **remove_triangle**\ (\ triangle\: [int](class_int.md)\ ) [🔗](#class_AnimationNodeBlendSpace2D_method_remove_triangle) + +Removes the triangle at index `triangle` from the blend space. + +
+ + + + + +`void` **set_blend_point_node**\ (\ point\: [int](class_int.md), node\: [AnimationRootNode](class_animationrootnode.md)\ ) [🔗](#class_AnimationNodeBlendSpace2D_method_set_blend_point_node) + +Changes the [AnimationNode](class_animationnode.md) referenced by the point at index `point`. + +
+ + + + + +`void` **set_blend_point_position**\ (\ point\: [int](class_int.md), pos\: [Vector2](class_vector2.md)\ ) [🔗](#class_AnimationNodeBlendSpace2D_method_set_blend_point_position) + +Updates the position of the point at index `point` in the blend space. + diff --git a/docs/Classes/class_animationnodeblendtree.md b/docs/Classes/class_animationnodeblendtree.md new file mode 100644 index 00000000..a0f9acb1 --- /dev/null +++ b/docs/Classes/class_animationnodeblendtree.md @@ -0,0 +1,287 @@ + + + + + + + + + +# AnimationNodeBlendTree + +**Inherits:** [AnimationRootNode](class_animationrootnode.md) **<** [AnimationNode](class_animationnode.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +A sub-tree of many type [AnimationNode](class_animationnode.md)\ s used for complex animations. Used by [AnimationTree](class_animationtree.md). + + + +## Description + +This animation node may contain a sub-tree of any other type animation nodes, such as [AnimationNodeTransition](class_animationnodetransition.md), [AnimationNodeBlend2](class_animationnodeblend2.md), [AnimationNodeBlend3](class_animationnodeblend3.md), [AnimationNodeOneShot](class_animationnodeoneshot.md), etc. This is one of the most commonly used animation node roots. + +An [AnimationNodeOutput](class_animationnodeoutput.md) node named ``output`` is created by default. + + + +## Tutorials + +- [Using AnimationTree](../tutorials/animation/animation_tree.md) + + + +## Properties + + + + + + + + + + + +
[Vector2](class_vector2.md)[graph_offset](#class_AnimationNodeBlendTree_property_graph_offset)`Vector2(0, 0)`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
`void`[add_node](#class_AnimationNodeBlendTree_method_add_node)\ (\ name\: [StringName](class_stringname.md), node\: [AnimationNode](class_animationnode.md), position\: [Vector2](class_vector2.md) = Vector2(0, 0)\ )
`void`[connect_node](#class_AnimationNodeBlendTree_method_connect_node)\ (\ input_node\: [StringName](class_stringname.md), input_index\: [int](class_int.md), output_node\: [StringName](class_stringname.md)\ )
`void`[disconnect_node](#class_AnimationNodeBlendTree_method_disconnect_node)\ (\ input_node\: [StringName](class_stringname.md), input_index\: [int](class_int.md)\ )
[AnimationNode](class_animationnode.md)[get_node](#class_AnimationNodeBlendTree_method_get_node)\ (\ name\: [StringName](class_stringname.md)\ ) const
[Array](class_array.md)\[[StringName](class_stringname.md)\][get_node_list](#class_AnimationNodeBlendTree_method_get_node_list)\ (\ ) const
[Vector2](class_vector2.md)[get_node_position](#class_AnimationNodeBlendTree_method_get_node_position)\ (\ name\: [StringName](class_stringname.md)\ ) const
[bool](class_bool.md)[has_node](#class_AnimationNodeBlendTree_method_has_node)\ (\ name\: [StringName](class_stringname.md)\ ) const
`void`[remove_node](#class_AnimationNodeBlendTree_method_remove_node)\ (\ name\: [StringName](class_stringname.md)\ )
`void`[rename_node](#class_AnimationNodeBlendTree_method_rename_node)\ (\ name\: [StringName](class_stringname.md), new_name\: [StringName](class_stringname.md)\ )
`void`[set_node_position](#class_AnimationNodeBlendTree_method_set_node_position)\ (\ name\: [StringName](class_stringname.md), position\: [Vector2](class_vector2.md)\ )
+ +
+ + + +## Signals + + + + + +**node_changed**\ (\ node_name\: [StringName](class_stringname.md)\ ) [🔗](#class_AnimationNodeBlendTree_signal_node_changed) + +Emitted when the input port information is changed. + +
+ + + +## Constants + + + + + +**CONNECTION_OK** = `0` [🔗](#class_AnimationNodeBlendTree_constant_CONNECTION_OK) + +The connection was successful. + + + + + +**CONNECTION_ERROR_NO_INPUT** = `1` [🔗](#class_AnimationNodeBlendTree_constant_CONNECTION_ERROR_NO_INPUT) + +The input node is ``null``. + + + + + +**CONNECTION_ERROR_NO_INPUT_INDEX** = `2` [🔗](#class_AnimationNodeBlendTree_constant_CONNECTION_ERROR_NO_INPUT_INDEX) + +The specified input port is out of range. + + + + + +**CONNECTION_ERROR_NO_OUTPUT** = `3` [🔗](#class_AnimationNodeBlendTree_constant_CONNECTION_ERROR_NO_OUTPUT) + +The output node is ``null``. + + + + + +**CONNECTION_ERROR_SAME_NODE** = `4` [🔗](#class_AnimationNodeBlendTree_constant_CONNECTION_ERROR_SAME_NODE) + +Input and output nodes are the same. + + + + + +**CONNECTION_ERROR_CONNECTION_EXISTS** = `5` [🔗](#class_AnimationNodeBlendTree_constant_CONNECTION_ERROR_CONNECTION_EXISTS) + +The specified connection already exists. + +
+ + + +## Property Descriptions + + + + + +[Vector2](class_vector2.md) **graph_offset** = `Vector2(0, 0)` [🔗](#class_AnimationNodeBlendTree_property_graph_offset) + + + +- `void` **set_graph_offset**\ (\ value\: [Vector2](class_vector2.md)\ ) +- [Vector2](class_vector2.md) **get_graph_offset**\ (\ ) + +The global offset of all sub animation nodes. + +
+ + + +## Method Descriptions + + + + + +`void` **add_node**\ (\ name\: [StringName](class_stringname.md), node\: [AnimationNode](class_animationnode.md), position\: [Vector2](class_vector2.md) = Vector2(0, 0)\ ) [🔗](#class_AnimationNodeBlendTree_method_add_node) + +Adds an [AnimationNode](class_animationnode.md) at the given `position`. The `name` is used to identify the created sub animation node later. + +
+ + + + + +`void` **connect_node**\ (\ input_node\: [StringName](class_stringname.md), input_index\: [int](class_int.md), output_node\: [StringName](class_stringname.md)\ ) [🔗](#class_AnimationNodeBlendTree_method_connect_node) + +Connects the output of an [AnimationNode](class_animationnode.md) as input for another [AnimationNode](class_animationnode.md), at the input port specified by `input_index`. + +
+ + + + + +`void` **disconnect_node**\ (\ input_node\: [StringName](class_stringname.md), input_index\: [int](class_int.md)\ ) [🔗](#class_AnimationNodeBlendTree_method_disconnect_node) + +Disconnects the animation node connected to the specified input. + +
+ + + + + +[AnimationNode](class_animationnode.md) **get_node**\ (\ name\: [StringName](class_stringname.md)\ ) const [🔗](#class_AnimationNodeBlendTree_method_get_node) + +Returns the sub animation node with the specified `name`. + +
+ + + + + +[Array](class_array.md)\[[StringName](class_stringname.md)\] **get_node_list**\ (\ ) const [🔗](#class_AnimationNodeBlendTree_method_get_node_list) + +Returns a list containing the names of all sub animation nodes in this blend tree. + +
+ + + + + +[Vector2](class_vector2.md) **get_node_position**\ (\ name\: [StringName](class_stringname.md)\ ) const [🔗](#class_AnimationNodeBlendTree_method_get_node_position) + +Returns the position of the sub animation node with the specified `name`. + +
+ + + + + +[bool](class_bool.md) **has_node**\ (\ name\: [StringName](class_stringname.md)\ ) const [🔗](#class_AnimationNodeBlendTree_method_has_node) + +Returns ``true`` if a sub animation node with specified `name` exists. + +
+ + + + + +`void` **remove_node**\ (\ name\: [StringName](class_stringname.md)\ ) [🔗](#class_AnimationNodeBlendTree_method_remove_node) + +Removes a sub animation node. + +
+ + + + + +`void` **rename_node**\ (\ name\: [StringName](class_stringname.md), new_name\: [StringName](class_stringname.md)\ ) [🔗](#class_AnimationNodeBlendTree_method_rename_node) + +Changes the name of a sub animation node. + +
+ + + + + +`void` **set_node_position**\ (\ name\: [StringName](class_stringname.md), position\: [Vector2](class_vector2.md)\ ) [🔗](#class_AnimationNodeBlendTree_method_set_node_position) + +Modifies the position of a sub animation node. + diff --git a/docs/Classes/class_animationnodeextension.md b/docs/Classes/class_animationnodeextension.md new file mode 100644 index 00000000..865c3521 --- /dev/null +++ b/docs/Classes/class_animationnodeextension.md @@ -0,0 +1,84 @@ + + + + + + + + + +# AnimationNodeExtension + +**Experimental:** This class may be changed or removed in future versions. + +**Inherits:** [AnimationNode](class_animationnode.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Base class for extending [AnimationRootNode](class_animationrootnode.md)\ s from GDScript, C#, or C++. + + + +## Description + +**AnimationNodeExtension** exposes the APIs of [AnimationRootNode](class_animationrootnode.md) 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](class_animationtree.md) system. + + + +## Methods + + + + + + + + + + + + + + + + + + +
[PackedFloat32Array](class_packedfloat32array.md)[_process_animation_node](#class_AnimationNodeExtension_private_method__process_animation_node)\ (\ playback_info\: [PackedFloat64Array](class_packedfloat64array.md), test_only\: [bool](class_bool.md)\ ) virtual required
[float](class_float.md)[get_remaining_time](#class_AnimationNodeExtension_method_get_remaining_time)\ (\ node_info\: [PackedFloat32Array](class_packedfloat32array.md), break_loop\: [bool](class_bool.md)\ ) static
[bool](class_bool.md)[is_looping](#class_AnimationNodeExtension_method_is_looping)\ (\ node_info\: [PackedFloat32Array](class_packedfloat32array.md)\ ) static
+ +
+ + + +## Method Descriptions + + + + + +[PackedFloat32Array](class_packedfloat32array.md) **_process_animation_node**\ (\ playback_info\: [PackedFloat64Array](class_packedfloat64array.md), test_only\: [bool](class_bool.md)\ ) virtual required [🔗](#class_AnimationNodeExtension_private_method__process_animation_node) + +A version of the [AnimationNode._process()](class_animationnode.md#class_AnimationNode_private_method__process) method that is meant to be overridden by custom nodes. It returns a [PackedFloat32Array](class_packedfloat32array.md) with the processed animation data. + +The [PackedFloat64Array](class_packedfloat64array.md) 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 ``0``), whether the seek request was externally requested (encoded as a float greater than ``0``), the current [LoopedFlag](class_animation.md#enum_Animation_LoopedFlag) (encoded as a float), and the current blend weight. + +The function must return a [PackedFloat32Array](class_packedfloat32array.md) of the node's time info, containing the following values (in order): animation length, time position, delta, [LoopMode](class_animation.md#enum_Animation_LoopMode) (encoded as a float), whether the animation is about to end (encoded as a float greater than ``0``) and whether the animation is infinite (encoded as a float greater than ``0``). All values must be included in the returned array. + +
+ + + + + +[float](class_float.md) **get_remaining_time**\ (\ node_info\: [PackedFloat32Array](class_packedfloat32array.md), break_loop\: [bool](class_bool.md)\ ) static [🔗](#class_AnimationNodeExtension_method_get_remaining_time) + +Returns the animation's remaining time for the given node info. For looping animations, it will only return the remaining time if `break_loop` is ``true``, a large integer value will be returned otherwise. + +
+ + + + + +[bool](class_bool.md) **is_looping**\ (\ node_info\: [PackedFloat32Array](class_packedfloat32array.md)\ ) static [🔗](#class_AnimationNodeExtension_method_is_looping) + +Returns ``true`` if the animation for the given `node_info` is looping. + diff --git a/docs/Classes/class_animationnodeoneshot.md b/docs/Classes/class_animationnodeoneshot.md new file mode 100644 index 00000000..9dfdcd7c --- /dev/null +++ b/docs/Classes/class_animationnodeoneshot.md @@ -0,0 +1,337 @@ + + + + + + + + + +# AnimationNodeOneShot + +**Inherits:** [AnimationNodeSync](class_animationnodesync.md) **<** [AnimationNode](class_animationnode.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Plays an animation once in an [AnimationNodeBlendTree](class_animationnodeblendtree.md). + + + +## Description + +A resource to add to an [AnimationNodeBlendTree](class_animationnodeblendtree.md). 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 ``request`` value to [ONE_SHOT_REQUEST_NONE](class_animationnodeoneshot.md#class_AnimationNodeOneShot_constant_ONE_SHOT_REQUEST_NONE). + + + + +```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"] +``` + +```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"); +``` + + + + + +## Tutorials + +- [Using AnimationTree](../tutorials/animation/animation_tree.md) + +- [Third Person Shooter (TPS) Demo](https://godotengine.org/asset-library/asset/2710) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[autorestart](#class_AnimationNodeOneShot_property_autorestart)`false`
[float](class_float.md)[autorestart_delay](#class_AnimationNodeOneShot_property_autorestart_delay)`1.0`
[float](class_float.md)[autorestart_random_delay](#class_AnimationNodeOneShot_property_autorestart_random_delay)`0.0`
[bool](class_bool.md)[break_loop_at_end](#class_AnimationNodeOneShot_property_break_loop_at_end)`false`
[Curve](class_curve.md)[fadein_curve](#class_AnimationNodeOneShot_property_fadein_curve)
[float](class_float.md)[fadein_time](#class_AnimationNodeOneShot_property_fadein_time)`0.0`
[Curve](class_curve.md)[fadeout_curve](#class_AnimationNodeOneShot_property_fadeout_curve)
[float](class_float.md)[fadeout_time](#class_AnimationNodeOneShot_property_fadeout_time)`0.0`
[MixMode](class_animationnodeoneshot.md#enum_AnimationNodeOneShot_MixMode)[mix_mode](#class_AnimationNodeOneShot_property_mix_mode)`0`
+ +
+ + + +## Enumerations + + + + + +enum **OneShotRequest**: [🔗](#enum_AnimationNodeOneShot_OneShotRequest) + + + + + +[OneShotRequest](class_animationnodeoneshot.md#enum_AnimationNodeOneShot_OneShotRequest) **ONE_SHOT_REQUEST_NONE** = `0` + +The default state of the request. Nothing is done. + + + +[OneShotRequest](class_animationnodeoneshot.md#enum_AnimationNodeOneShot_OneShotRequest) **ONE_SHOT_REQUEST_FIRE** = `1` + +The request to play the animation connected to "shot" port. + + + +[OneShotRequest](class_animationnodeoneshot.md#enum_AnimationNodeOneShot_OneShotRequest) **ONE_SHOT_REQUEST_ABORT** = `2` + +The request to stop the animation connected to "shot" port. + + + +[OneShotRequest](class_animationnodeoneshot.md#enum_AnimationNodeOneShot_OneShotRequest) **ONE_SHOT_REQUEST_FADE_OUT** = `3` + +The request to fade out the animation connected to "shot" port.
+ + + + + +enum **MixMode**: [🔗](#enum_AnimationNodeOneShot_MixMode) + + + + + +[MixMode](class_animationnodeoneshot.md#enum_AnimationNodeOneShot_MixMode) **MIX_MODE_BLEND** = `0` + +Blends two animations. See also [AnimationNodeBlend2](class_animationnodeblend2.md). + + + +[MixMode](class_animationnodeoneshot.md#enum_AnimationNodeOneShot_MixMode) **MIX_MODE_ADD** = `1` + +Blends two animations additively. See also [AnimationNodeAdd2](class_animationnodeadd2.md).
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **autorestart** = `false` [🔗](#class_AnimationNodeOneShot_property_autorestart) + + + +- `void` **set_autorestart**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **has_autorestart**\ (\ ) + +If ``true``, the sub-animation will restart automatically after finishing. + +In other words, to start auto restarting, the animation must be played once with the [ONE_SHOT_REQUEST_FIRE](class_animationnodeoneshot.md#class_AnimationNodeOneShot_constant_ONE_SHOT_REQUEST_FIRE) request. The [ONE_SHOT_REQUEST_ABORT](class_animationnodeoneshot.md#class_AnimationNodeOneShot_constant_ONE_SHOT_REQUEST_ABORT) request stops the auto restarting, but it does not disable the [autorestart](class_animationnodeoneshot.md#class_AnimationNodeOneShot_property_autorestart) itself. So, the [ONE_SHOT_REQUEST_FIRE](class_animationnodeoneshot.md#class_AnimationNodeOneShot_constant_ONE_SHOT_REQUEST_FIRE) request will start auto restarting again. + +
+ + + + + +[float](class_float.md) **autorestart_delay** = `1.0` [🔗](#class_AnimationNodeOneShot_property_autorestart_delay) + + + +- `void` **set_autorestart_delay**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_autorestart_delay**\ (\ ) + +The delay after which the automatic restart is triggered, in seconds. + +
+ + + + + +[float](class_float.md) **autorestart_random_delay** = `0.0` [🔗](#class_AnimationNodeOneShot_property_autorestart_random_delay) + + + +- `void` **set_autorestart_random_delay**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_autorestart_random_delay**\ (\ ) + +If [autorestart](class_animationnodeoneshot.md#class_AnimationNodeOneShot_property_autorestart) is ``true``, a random additional delay (in seconds) between 0 and this value will be added to [autorestart_delay](class_animationnodeoneshot.md#class_AnimationNodeOneShot_property_autorestart_delay). + +
+ + + + + +[bool](class_bool.md) **break_loop_at_end** = `false` [🔗](#class_AnimationNodeOneShot_property_break_loop_at_end) + + + +- `void` **set_break_loop_at_end**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_loop_broken_at_end**\ (\ ) + +If ``true``, breaks the loop at the end of the loop cycle for transition, even if the animation is looping. + +
+ + + + + +[Curve](class_curve.md) **fadein_curve** [🔗](#class_AnimationNodeOneShot_property_fadein_curve) + + + +- `void` **set_fadein_curve**\ (\ value\: [Curve](class_curve.md)\ ) +- [Curve](class_curve.md) **get_fadein_curve**\ (\ ) + +Determines how cross-fading between animations is eased. If empty, the transition will be linear. Should be a unit [Curve](class_curve.md). + +
+ + + + + +[float](class_float.md) **fadein_time** = `0.0` [🔗](#class_AnimationNodeOneShot_property_fadein_time) + + + +- `void` **set_fadein_time**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_fadein_time**\ (\ ) + +The fade-in duration. For example, setting this to ``1.0`` for a 5 second length animation will produce a cross-fade that starts at 0 second and ends at 1 second during the animation. + +\ **Note:** **AnimationNodeOneShot** transitions the current state after the fading has finished. + +
+ + + + + +[Curve](class_curve.md) **fadeout_curve** [🔗](#class_AnimationNodeOneShot_property_fadeout_curve) + + + +- `void` **set_fadeout_curve**\ (\ value\: [Curve](class_curve.md)\ ) +- [Curve](class_curve.md) **get_fadeout_curve**\ (\ ) + +Determines how cross-fading between animations is eased. If empty, the transition will be linear. Should be a unit [Curve](class_curve.md). + +
+ + + + + +[float](class_float.md) **fadeout_time** = `0.0` [🔗](#class_AnimationNodeOneShot_property_fadeout_time) + + + +- `void` **set_fadeout_time**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_fadeout_time**\ (\ ) + +The fade-out duration. For example, setting this to ``1.0`` for a 5 second length animation will produce a cross-fade that starts at 4 second and ends at 5 second during the animation. + +\ **Note:** **AnimationNodeOneShot** transitions the current state after the fading has finished. + +
+ + + + + +[MixMode](class_animationnodeoneshot.md#enum_AnimationNodeOneShot_MixMode) **mix_mode** = `0` [🔗](#class_AnimationNodeOneShot_property_mix_mode) + + + +- `void` **set_mix_mode**\ (\ value\: [MixMode](class_animationnodeoneshot.md#enum_AnimationNodeOneShot_MixMode)\ ) +- [MixMode](class_animationnodeoneshot.md#enum_AnimationNodeOneShot_MixMode) **get_mix_mode**\ (\ ) + +The blend type. + diff --git a/docs/Classes/class_animationnodeoutput.md b/docs/Classes/class_animationnodeoutput.md new file mode 100644 index 00000000..6b1cc743 --- /dev/null +++ b/docs/Classes/class_animationnodeoutput.md @@ -0,0 +1,31 @@ + + + + + + + + + +# AnimationNodeOutput + +**Inherits:** [AnimationNode](class_animationnode.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +The animation output node of an [AnimationNodeBlendTree](class_animationnodeblendtree.md). + + + +## Description + +A node created automatically in an [AnimationNodeBlendTree](class_animationnodeblendtree.md) that outputs the final animation. + + + +## Tutorials + +- [Using AnimationTree](../tutorials/animation/animation_tree.md) + +- [3D Platformer Demo](https://godotengine.org/asset-library/asset/2748) + +- [Third Person Shooter (TPS) Demo](https://godotengine.org/asset-library/asset/2710) + diff --git a/docs/Classes/class_animationnodestatemachine.md b/docs/Classes/class_animationnodestatemachine.md new file mode 100644 index 00000000..546b1801 --- /dev/null +++ b/docs/Classes/class_animationnodestatemachine.md @@ -0,0 +1,444 @@ + + + + + + + + + +# AnimationNodeStateMachine + +**Inherits:** [AnimationRootNode](class_animationrootnode.md) **<** [AnimationNode](class_animationnode.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +A state machine with multiple [AnimationRootNode](class_animationrootnode.md)\ s, used by [AnimationTree](class_animationtree.md). + + + +## Description + +Contains multiple [AnimationRootNode](class_animationrootnode.md)\ 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](class_animationnodestatemachineplayback.md) object from the [AnimationTree](class_animationtree.md) node to control it programmatically. + + + + +```gdscript + var state_machine = $AnimationTree.get("parameters/playback") + state_machine.travel("some_state") +``` + +```csharp + var stateMachine = GetNode("AnimationTree").Get("parameters/playback") as AnimationNodeStateMachinePlayback; + stateMachine.Travel("some_state"); +``` + + + + + +## Tutorials + +- [Using AnimationTree](../tutorials/animation/animation_tree.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[allow_transition_to_self](#class_AnimationNodeStateMachine_property_allow_transition_to_self)`false`
[bool](class_bool.md)[reset_ends](#class_AnimationNodeStateMachine_property_reset_ends)`false`
[StateMachineType](class_animationnodestatemachine.md#enum_AnimationNodeStateMachine_StateMachineType)[state_machine_type](#class_AnimationNodeStateMachine_property_state_machine_type)`0`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
`void`[add_node](#class_AnimationNodeStateMachine_method_add_node)\ (\ name\: [StringName](class_stringname.md), node\: [AnimationNode](class_animationnode.md), position\: [Vector2](class_vector2.md) = Vector2(0, 0)\ )
`void`[add_transition](#class_AnimationNodeStateMachine_method_add_transition)\ (\ from\: [StringName](class_stringname.md), to\: [StringName](class_stringname.md), transition\: [AnimationNodeStateMachineTransition](class_animationnodestatemachinetransition.md)\ )
[Vector2](class_vector2.md)[get_graph_offset](#class_AnimationNodeStateMachine_method_get_graph_offset)\ (\ ) const
[AnimationNode](class_animationnode.md)[get_node](#class_AnimationNodeStateMachine_method_get_node)\ (\ name\: [StringName](class_stringname.md)\ ) const
[Array](class_array.md)\[[StringName](class_stringname.md)\][get_node_list](#class_AnimationNodeStateMachine_method_get_node_list)\ (\ ) const
[StringName](class_stringname.md)[get_node_name](#class_AnimationNodeStateMachine_method_get_node_name)\ (\ node\: [AnimationNode](class_animationnode.md)\ ) const
[Vector2](class_vector2.md)[get_node_position](#class_AnimationNodeStateMachine_method_get_node_position)\ (\ name\: [StringName](class_stringname.md)\ ) const
[AnimationNodeStateMachineTransition](class_animationnodestatemachinetransition.md)[get_transition](#class_AnimationNodeStateMachine_method_get_transition)\ (\ idx\: [int](class_int.md)\ ) const
[int](class_int.md)[get_transition_count](#class_AnimationNodeStateMachine_method_get_transition_count)\ (\ ) const
[StringName](class_stringname.md)[get_transition_from](#class_AnimationNodeStateMachine_method_get_transition_from)\ (\ idx\: [int](class_int.md)\ ) const
[StringName](class_stringname.md)[get_transition_to](#class_AnimationNodeStateMachine_method_get_transition_to)\ (\ idx\: [int](class_int.md)\ ) const
[bool](class_bool.md)[has_node](#class_AnimationNodeStateMachine_method_has_node)\ (\ name\: [StringName](class_stringname.md)\ ) const
[bool](class_bool.md)[has_transition](#class_AnimationNodeStateMachine_method_has_transition)\ (\ from\: [StringName](class_stringname.md), to\: [StringName](class_stringname.md)\ ) const
`void`[remove_node](#class_AnimationNodeStateMachine_method_remove_node)\ (\ name\: [StringName](class_stringname.md)\ )
`void`[remove_transition](#class_AnimationNodeStateMachine_method_remove_transition)\ (\ from\: [StringName](class_stringname.md), to\: [StringName](class_stringname.md)\ )
`void`[remove_transition_by_index](#class_AnimationNodeStateMachine_method_remove_transition_by_index)\ (\ idx\: [int](class_int.md)\ )
`void`[rename_node](#class_AnimationNodeStateMachine_method_rename_node)\ (\ name\: [StringName](class_stringname.md), new_name\: [StringName](class_stringname.md)\ )
`void`[replace_node](#class_AnimationNodeStateMachine_method_replace_node)\ (\ name\: [StringName](class_stringname.md), node\: [AnimationNode](class_animationnode.md)\ )
`void`[set_graph_offset](#class_AnimationNodeStateMachine_method_set_graph_offset)\ (\ offset\: [Vector2](class_vector2.md)\ )
`void`[set_node_position](#class_AnimationNodeStateMachine_method_set_node_position)\ (\ name\: [StringName](class_stringname.md), position\: [Vector2](class_vector2.md)\ )
+ +
+ + + +## Enumerations + + + + + +enum **StateMachineType**: [🔗](#enum_AnimationNodeStateMachine_StateMachineType) + + + + + +[StateMachineType](class_animationnodestatemachine.md#enum_AnimationNodeStateMachine_StateMachineType) **STATE_MACHINE_TYPE_ROOT** = `0` + +Seeking to the beginning is treated as playing from the start state. Transition to the end state is treated as exiting the state machine. + + + +[StateMachineType](class_animationnodestatemachine.md#enum_AnimationNodeStateMachine_StateMachineType) **STATE_MACHINE_TYPE_NESTED** = `1` + +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. + + + +[StateMachineType](class_animationnodestatemachine.md#enum_AnimationNodeStateMachine_StateMachineType) **STATE_MACHINE_TYPE_GROUPED** = `2` + +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 [state_machine_type](class_animationnodestatemachine.md#class_AnimationNodeStateMachine_property_state_machine_type) of [STATE_MACHINE_TYPE_ROOT](class_animationnodestatemachine.md#class_AnimationNodeStateMachine_constant_STATE_MACHINE_TYPE_ROOT) or [STATE_MACHINE_TYPE_NESTED](class_animationnodestatemachine.md#class_AnimationNodeStateMachine_constant_STATE_MACHINE_TYPE_NESTED) in the parent or ancestor.
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **allow_transition_to_self** = `false` [🔗](#class_AnimationNodeStateMachine_property_allow_transition_to_self) + + + +- `void` **set_allow_transition_to_self**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_allow_transition_to_self**\ (\ ) + +If ``true``, allows teleport to the self state with [AnimationNodeStateMachinePlayback.travel()](class_animationnodestatemachineplayback.md#class_AnimationNodeStateMachinePlayback_method_travel). When the reset option is enabled in [AnimationNodeStateMachinePlayback.travel()](class_animationnodestatemachineplayback.md#class_AnimationNodeStateMachinePlayback_method_travel), the animation is restarted. If ``false``, nothing happens on the teleportation to the self state. + +
+ + + + + +[bool](class_bool.md) **reset_ends** = `false` [🔗](#class_AnimationNodeStateMachine_property_reset_ends) + + + +- `void` **set_reset_ends**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **are_ends_reset**\ (\ ) + +If ``true``, 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](class_animationnode.md) of the state machine, setting this property to ``false`` and matching the cross-fade time of the parent [AnimationNode](class_animationnode.md) and the state machine's start node and end node gives good results. + +
+ + + + + +[StateMachineType](class_animationnodestatemachine.md#enum_AnimationNodeStateMachine_StateMachineType) **state_machine_type** = `0` [🔗](#class_AnimationNodeStateMachine_property_state_machine_type) + + + +- `void` **set_state_machine_type**\ (\ value\: [StateMachineType](class_animationnodestatemachine.md#enum_AnimationNodeStateMachine_StateMachineType)\ ) +- [StateMachineType](class_animationnodestatemachine.md#enum_AnimationNodeStateMachine_StateMachineType) **get_state_machine_type**\ (\ ) + +This property can define the process of transitions for different use cases. See also [StateMachineType](class_animationnodestatemachine.md#enum_AnimationNodeStateMachine_StateMachineType). + +
+ + + +## Method Descriptions + + + + + +`void` **add_node**\ (\ name\: [StringName](class_stringname.md), node\: [AnimationNode](class_animationnode.md), position\: [Vector2](class_vector2.md) = Vector2(0, 0)\ ) [🔗](#class_AnimationNodeStateMachine_method_add_node) + +Adds a new animation node to the graph. The `position` is used for display in the editor. + +
+ + + + + +`void` **add_transition**\ (\ from\: [StringName](class_stringname.md), to\: [StringName](class_stringname.md), transition\: [AnimationNodeStateMachineTransition](class_animationnodestatemachinetransition.md)\ ) [🔗](#class_AnimationNodeStateMachine_method_add_transition) + +Adds a transition between the given animation nodes. + +
+ + + + + +[Vector2](class_vector2.md) **get_graph_offset**\ (\ ) const [🔗](#class_AnimationNodeStateMachine_method_get_graph_offset) + +Returns the draw offset of the graph. Used for display in the editor. + +
+ + + + + +[AnimationNode](class_animationnode.md) **get_node**\ (\ name\: [StringName](class_stringname.md)\ ) const [🔗](#class_AnimationNodeStateMachine_method_get_node) + +Returns the animation node with the given name. + +
+ + + + + +[Array](class_array.md)\[[StringName](class_stringname.md)\] **get_node_list**\ (\ ) const [🔗](#class_AnimationNodeStateMachine_method_get_node_list) + +Returns a list containing the names of all animation nodes in this state machine. + +
+ + + + + +[StringName](class_stringname.md) **get_node_name**\ (\ node\: [AnimationNode](class_animationnode.md)\ ) const [🔗](#class_AnimationNodeStateMachine_method_get_node_name) + +Returns the given animation node's name. + +
+ + + + + +[Vector2](class_vector2.md) **get_node_position**\ (\ name\: [StringName](class_stringname.md)\ ) const [🔗](#class_AnimationNodeStateMachine_method_get_node_position) + +Returns the given animation node's coordinates. Used for display in the editor. + +
+ + + + + +[AnimationNodeStateMachineTransition](class_animationnodestatemachinetransition.md) **get_transition**\ (\ idx\: [int](class_int.md)\ ) const [🔗](#class_AnimationNodeStateMachine_method_get_transition) + +Returns the given transition. + +
+ + + + + +[int](class_int.md) **get_transition_count**\ (\ ) const [🔗](#class_AnimationNodeStateMachine_method_get_transition_count) + +Returns the number of connections in the graph. + +
+ + + + + +[StringName](class_stringname.md) **get_transition_from**\ (\ idx\: [int](class_int.md)\ ) const [🔗](#class_AnimationNodeStateMachine_method_get_transition_from) + +Returns the given transition's start node. + +
+ + + + + +[StringName](class_stringname.md) **get_transition_to**\ (\ idx\: [int](class_int.md)\ ) const [🔗](#class_AnimationNodeStateMachine_method_get_transition_to) + +Returns the given transition's end node. + +
+ + + + + +[bool](class_bool.md) **has_node**\ (\ name\: [StringName](class_stringname.md)\ ) const [🔗](#class_AnimationNodeStateMachine_method_has_node) + +Returns ``true`` if the graph contains the given animation node. + +
+ + + + + +[bool](class_bool.md) **has_transition**\ (\ from\: [StringName](class_stringname.md), to\: [StringName](class_stringname.md)\ ) const [🔗](#class_AnimationNodeStateMachine_method_has_transition) + +Returns ``true`` if there is a transition between the given animation nodes. + +
+ + + + + +`void` **remove_node**\ (\ name\: [StringName](class_stringname.md)\ ) [🔗](#class_AnimationNodeStateMachine_method_remove_node) + +Deletes the given animation node from the graph. + +
+ + + + + +`void` **remove_transition**\ (\ from\: [StringName](class_stringname.md), to\: [StringName](class_stringname.md)\ ) [🔗](#class_AnimationNodeStateMachine_method_remove_transition) + +Deletes the transition between the two specified animation nodes. + +
+ + + + + +`void` **remove_transition_by_index**\ (\ idx\: [int](class_int.md)\ ) [🔗](#class_AnimationNodeStateMachine_method_remove_transition_by_index) + +Deletes the given transition by index. + +
+ + + + + +`void` **rename_node**\ (\ name\: [StringName](class_stringname.md), new_name\: [StringName](class_stringname.md)\ ) [🔗](#class_AnimationNodeStateMachine_method_rename_node) + +Renames the given animation node. + +
+ + + + + +`void` **replace_node**\ (\ name\: [StringName](class_stringname.md), node\: [AnimationNode](class_animationnode.md)\ ) [🔗](#class_AnimationNodeStateMachine_method_replace_node) + +Replaces the given animation node with a new animation node. + +
+ + + + + +`void` **set_graph_offset**\ (\ offset\: [Vector2](class_vector2.md)\ ) [🔗](#class_AnimationNodeStateMachine_method_set_graph_offset) + +Sets the draw offset of the graph. Used for display in the editor. + +
+ + + + + +`void` **set_node_position**\ (\ name\: [StringName](class_stringname.md), position\: [Vector2](class_vector2.md)\ ) [🔗](#class_AnimationNodeStateMachine_method_set_node_position) + +Sets the animation node's coordinates. Used for display in the editor. + diff --git a/docs/Classes/class_animationnodestatemachineplayback.md b/docs/Classes/class_animationnodestatemachineplayback.md new file mode 100644 index 00000000..523e6e7c --- /dev/null +++ b/docs/Classes/class_animationnodestatemachineplayback.md @@ -0,0 +1,249 @@ + + + + + + + + + +# AnimationNodeStateMachinePlayback + +**Inherits:** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Provides playback control for an [AnimationNodeStateMachine](class_animationnodestatemachine.md). + + + +## Description + +Allows control of [AnimationTree](class_animationtree.md) state machines created with [AnimationNodeStateMachine](class_animationnodestatemachine.md). Retrieve with ``$AnimationTree.get("parameters/playback")``. + + + + +```gdscript + var state_machine = $AnimationTree.get("parameters/playback") + state_machine.travel("some_state") +``` + +```csharp + var stateMachine = GetNode("AnimationTree").Get("parameters/playback").As(); + stateMachine.Travel("some_state"); +``` + + + + + +## Tutorials + +- [Using AnimationTree](../tutorials/animation/animation_tree.md) + + + +## Properties + + + + + + + + + + + +
[bool](class_bool.md)resource_local_to_scene`true` (overrides [Resource.resource_local_to_scene](class_resource.md#class_Resource_property_resource_local_to_scene))
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[get_current_length](#class_AnimationNodeStateMachinePlayback_method_get_current_length)\ (\ ) const
[StringName](class_stringname.md)[get_current_node](#class_AnimationNodeStateMachinePlayback_method_get_current_node)\ (\ ) const
[float](class_float.md)[get_current_play_position](#class_AnimationNodeStateMachinePlayback_method_get_current_play_position)\ (\ ) const
[StringName](class_stringname.md)[get_fading_from_node](#class_AnimationNodeStateMachinePlayback_method_get_fading_from_node)\ (\ ) const
[Array](class_array.md)\[[StringName](class_stringname.md)\][get_travel_path](#class_AnimationNodeStateMachinePlayback_method_get_travel_path)\ (\ ) const
[bool](class_bool.md)[is_playing](#class_AnimationNodeStateMachinePlayback_method_is_playing)\ (\ ) const
`void`[next](#class_AnimationNodeStateMachinePlayback_method_next)\ (\ )
`void`[start](#class_AnimationNodeStateMachinePlayback_method_start)\ (\ node\: [StringName](class_stringname.md), reset\: [bool](class_bool.md) = true\ )
`void`[stop](#class_AnimationNodeStateMachinePlayback_method_stop)\ (\ )
`void`[travel](#class_AnimationNodeStateMachinePlayback_method_travel)\ (\ to_node\: [StringName](class_stringname.md), reset_on_teleport\: [bool](class_bool.md) = true\ )
+ +
+ + + +## Signals + + + + + +**state_finished**\ (\ state\: [StringName](class_stringname.md)\ ) [🔗](#class_AnimationNodeStateMachinePlayback_signal_state_finished) + +Emitted when the `state` finishes playback. If `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 [get_fading_from_node()](class_animationnodestatemachineplayback.md#class_AnimationNodeStateMachinePlayback_method_get_fading_from_node) animation is no longer present. + +
+ + + + + +**state_started**\ (\ state\: [StringName](class_stringname.md)\ ) [🔗](#class_AnimationNodeStateMachinePlayback_signal_state_started) + +Emitted when the `state` starts playback. If `state` is a state machine set to grouped mode, its signals are passed through with its name prefixed. + +
+ + + +## Method Descriptions + + + + + +[float](class_float.md) **get_current_length**\ (\ ) const [🔗](#class_AnimationNodeStateMachinePlayback_method_get_current_length) + +Returns the current state length. + +\ **Note:** It is possible that any [AnimationRootNode](class_animationrootnode.md) 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. + +
+ + + + + +[StringName](class_stringname.md) **get_current_node**\ (\ ) const [🔗](#class_AnimationNodeStateMachinePlayback_method_get_current_node) + +Returns the currently playing animation state. + +\ **Note:** When using a cross-fade, the current state changes to the next state immediately after the cross-fade begins. + +
+ + + + + +[float](class_float.md) **get_current_play_position**\ (\ ) const [🔗](#class_AnimationNodeStateMachinePlayback_method_get_current_play_position) + +Returns the playback position within the current animation state. + +
+ + + + + +[StringName](class_stringname.md) **get_fading_from_node**\ (\ ) const [🔗](#class_AnimationNodeStateMachinePlayback_method_get_fading_from_node) + +Returns the starting state of currently fading animation. + +
+ + + + + +[Array](class_array.md)\[[StringName](class_stringname.md)\] **get_travel_path**\ (\ ) const [🔗](#class_AnimationNodeStateMachinePlayback_method_get_travel_path) + +Returns the current travel path as computed internally by the A\* algorithm. + +
+ + + + + +[bool](class_bool.md) **is_playing**\ (\ ) const [🔗](#class_AnimationNodeStateMachinePlayback_method_is_playing) + +Returns ``true`` if an animation is playing. + +
+ + + + + +`void` **next**\ (\ ) [🔗](#class_AnimationNodeStateMachinePlayback_method_next) + +If there is a next path by travel or auto advance, immediately transitions from the current state to the next state. + +
+ + + + + +`void` **start**\ (\ node\: [StringName](class_stringname.md), reset\: [bool](class_bool.md) = true\ ) [🔗](#class_AnimationNodeStateMachinePlayback_method_start) + +Starts playing the given animation. + +If `reset` is ``true``, the animation is played from the beginning. + +
+ + + + + +`void` **stop**\ (\ ) [🔗](#class_AnimationNodeStateMachinePlayback_method_stop) + +Stops the currently playing animation. + +
+ + + + + +`void` **travel**\ (\ to_node\: [StringName](class_stringname.md), reset_on_teleport\: [bool](class_bool.md) = true\ ) [🔗](#class_AnimationNodeStateMachinePlayback_method_travel) + +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 `reset_on_teleport` is ``true``, the animation is played from the beginning when the travel cause a teleportation. + diff --git a/docs/Classes/class_animationnodestatemachinetransition.md b/docs/Classes/class_animationnodestatemachinetransition.md new file mode 100644 index 00000000..a44dee9b --- /dev/null +++ b/docs/Classes/class_animationnodestatemachinetransition.md @@ -0,0 +1,309 @@ + + + + + + + + + +# AnimationNodeStateMachineTransition + +**Inherits:** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +A transition within an [AnimationNodeStateMachine](class_animationnodestatemachine.md) connecting two [AnimationRootNode](class_animationrootnode.md)\ s. + + + +## Description + +The path generated when using [AnimationNodeStateMachinePlayback.travel()](class_animationnodestatemachineplayback.md#class_AnimationNodeStateMachinePlayback_method_travel) is limited to the nodes connected by **AnimationNodeStateMachineTransition**. + +You can set the timing and conditions of the transition in detail. + + + +## Tutorials + +- [Using AnimationTree](../tutorials/animation/animation_tree.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[StringName](class_stringname.md)[advance_condition](#class_AnimationNodeStateMachineTransition_property_advance_condition)`&""`
[String](class_string.md)[advance_expression](#class_AnimationNodeStateMachineTransition_property_advance_expression)`""`
[AdvanceMode](class_animationnodestatemachinetransition.md#enum_AnimationNodeStateMachineTransition_AdvanceMode)[advance_mode](#class_AnimationNodeStateMachineTransition_property_advance_mode)`1`
[bool](class_bool.md)[break_loop_at_end](#class_AnimationNodeStateMachineTransition_property_break_loop_at_end)`false`
[int](class_int.md)[priority](#class_AnimationNodeStateMachineTransition_property_priority)`1`
[bool](class_bool.md)[reset](#class_AnimationNodeStateMachineTransition_property_reset)`true`
[SwitchMode](class_animationnodestatemachinetransition.md#enum_AnimationNodeStateMachineTransition_SwitchMode)[switch_mode](#class_AnimationNodeStateMachineTransition_property_switch_mode)`0`
[Curve](class_curve.md)[xfade_curve](#class_AnimationNodeStateMachineTransition_property_xfade_curve)
[float](class_float.md)[xfade_time](#class_AnimationNodeStateMachineTransition_property_xfade_time)`0.0`
+ +
+ + + +## Signals + + + + + +**advance_condition_changed**\ (\ ) [🔗](#class_AnimationNodeStateMachineTransition_signal_advance_condition_changed) + +Emitted when [advance_condition](class_animationnodestatemachinetransition.md#class_AnimationNodeStateMachineTransition_property_advance_condition) is changed. + +
+ + + +## Enumerations + + + + + +enum **SwitchMode**: [🔗](#enum_AnimationNodeStateMachineTransition_SwitchMode) + + + + + +[SwitchMode](class_animationnodestatemachinetransition.md#enum_AnimationNodeStateMachineTransition_SwitchMode) **SWITCH_MODE_IMMEDIATE** = `0` + +Switch to the next state immediately. The current state will end and blend into the beginning of the new one. + + + +[SwitchMode](class_animationnodestatemachinetransition.md#enum_AnimationNodeStateMachineTransition_SwitchMode) **SWITCH_MODE_SYNC** = `1` + +Switch to the next state immediately, but will seek the new state to the playback position of the old state. + + + +[SwitchMode](class_animationnodestatemachinetransition.md#enum_AnimationNodeStateMachineTransition_SwitchMode) **SWITCH_MODE_AT_END** = `2` + +Wait for the current state playback to end, then switch to the beginning of the next state animation.
+ + + + + +enum **AdvanceMode**: [🔗](#enum_AnimationNodeStateMachineTransition_AdvanceMode) + + + + + +[AdvanceMode](class_animationnodestatemachinetransition.md#enum_AnimationNodeStateMachineTransition_AdvanceMode) **ADVANCE_MODE_DISABLED** = `0` + +Don't use this transition. + + + +[AdvanceMode](class_animationnodestatemachinetransition.md#enum_AnimationNodeStateMachineTransition_AdvanceMode) **ADVANCE_MODE_ENABLED** = `1` + +Only use this transition during [AnimationNodeStateMachinePlayback.travel()](class_animationnodestatemachineplayback.md#class_AnimationNodeStateMachinePlayback_method_travel). + + + +[AdvanceMode](class_animationnodestatemachinetransition.md#enum_AnimationNodeStateMachineTransition_AdvanceMode) **ADVANCE_MODE_AUTO** = `2` + +Automatically use this transition if the [advance_condition](class_animationnodestatemachinetransition.md#class_AnimationNodeStateMachineTransition_property_advance_condition) and [advance_expression](class_animationnodestatemachinetransition.md#class_AnimationNodeStateMachineTransition_property_advance_expression) checks are ``true`` (if assigned).
+ + + +## Property Descriptions + + + + + +[StringName](class_stringname.md) **advance_condition** = `&""` [🔗](#class_AnimationNodeStateMachineTransition_property_advance_condition) + + + +- `void` **set_advance_condition**\ (\ value\: [StringName](class_stringname.md)\ ) +- [StringName](class_stringname.md) **get_advance_condition**\ (\ ) + +Turn on auto advance when this condition is set. The provided name will become a boolean parameter on the [AnimationTree](class_animationtree.md) that can be controlled from code (see [Using AnimationTree](../tutorials/animation/animation_tree.md#controlling-from-code)). For example, if [AnimationTree.tree_root](class_animationtree.md#class_AnimationTree_property_tree_root) is an [AnimationNodeStateMachine](class_animationnodestatemachine.md) and [advance_condition](class_animationnodestatemachinetransition.md#class_AnimationNodeStateMachineTransition_property_advance_condition) is set to ``"idle"``: + + + + +```gdscript + $animation_tree.set("parameters/conditions/idle", is_on_floor and (linear_velocity.x == 0)) +``` + +```csharp + GetNode("animation_tree").Set("parameters/conditions/idle", IsOnFloor && (LinearVelocity.X == 0)); +``` + + + +
+ + + + + +[String](class_string.md) **advance_expression** = `""` [🔗](#class_AnimationNodeStateMachineTransition_property_advance_expression) + + + +- `void` **set_advance_expression**\ (\ value\: [String](class_string.md)\ ) +- [String](class_string.md) **get_advance_expression**\ (\ ) + +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. + +
+ + + + + +[AdvanceMode](class_animationnodestatemachinetransition.md#enum_AnimationNodeStateMachineTransition_AdvanceMode) **advance_mode** = `1` [🔗](#class_AnimationNodeStateMachineTransition_property_advance_mode) + + + +- `void` **set_advance_mode**\ (\ value\: [AdvanceMode](class_animationnodestatemachinetransition.md#enum_AnimationNodeStateMachineTransition_AdvanceMode)\ ) +- [AdvanceMode](class_animationnodestatemachinetransition.md#enum_AnimationNodeStateMachineTransition_AdvanceMode) **get_advance_mode**\ (\ ) + +Determines whether the transition should be disabled, enabled when using [AnimationNodeStateMachinePlayback.travel()](class_animationnodestatemachineplayback.md#class_AnimationNodeStateMachinePlayback_method_travel), or traversed automatically if the [advance_condition](class_animationnodestatemachinetransition.md#class_AnimationNodeStateMachineTransition_property_advance_condition) and [advance_expression](class_animationnodestatemachinetransition.md#class_AnimationNodeStateMachineTransition_property_advance_expression) checks are ``true`` (if assigned). + +
+ + + + + +[bool](class_bool.md) **break_loop_at_end** = `false` [🔗](#class_AnimationNodeStateMachineTransition_property_break_loop_at_end) + + + +- `void` **set_break_loop_at_end**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_loop_broken_at_end**\ (\ ) + +If ``true``, breaks the loop at the end of the loop cycle for transition, even if the animation is looping. + +
+ + + + + +[int](class_int.md) **priority** = `1` [🔗](#class_AnimationNodeStateMachineTransition_property_priority) + + + +- `void` **set_priority**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_priority**\ (\ ) + +Lower priority transitions are preferred when travelling through the tree via [AnimationNodeStateMachinePlayback.travel()](class_animationnodestatemachineplayback.md#class_AnimationNodeStateMachinePlayback_method_travel) or [advance_mode](class_animationnodestatemachinetransition.md#class_AnimationNodeStateMachineTransition_property_advance_mode) is set to [ADVANCE_MODE_AUTO](class_animationnodestatemachinetransition.md#class_AnimationNodeStateMachineTransition_constant_ADVANCE_MODE_AUTO). + +
+ + + + + +[bool](class_bool.md) **reset** = `true` [🔗](#class_AnimationNodeStateMachineTransition_property_reset) + + + +- `void` **set_reset**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_reset**\ (\ ) + +If ``true``, the destination animation is played back from the beginning when switched. + +
+ + + + + +[SwitchMode](class_animationnodestatemachinetransition.md#enum_AnimationNodeStateMachineTransition_SwitchMode) **switch_mode** = `0` [🔗](#class_AnimationNodeStateMachineTransition_property_switch_mode) + + + +- `void` **set_switch_mode**\ (\ value\: [SwitchMode](class_animationnodestatemachinetransition.md#enum_AnimationNodeStateMachineTransition_SwitchMode)\ ) +- [SwitchMode](class_animationnodestatemachinetransition.md#enum_AnimationNodeStateMachineTransition_SwitchMode) **get_switch_mode**\ (\ ) + +The transition type. + +
+ + + + + +[Curve](class_curve.md) **xfade_curve** [🔗](#class_AnimationNodeStateMachineTransition_property_xfade_curve) + + + +- `void` **set_xfade_curve**\ (\ value\: [Curve](class_curve.md)\ ) +- [Curve](class_curve.md) **get_xfade_curve**\ (\ ) + +Ease curve for better control over cross-fade between this state and the next. Should be a unit [Curve](class_curve.md). + +
+ + + + + +[float](class_float.md) **xfade_time** = `0.0` [🔗](#class_AnimationNodeStateMachineTransition_property_xfade_time) + + + +- `void` **set_xfade_time**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_xfade_time**\ (\ ) + +The time to cross-fade between this state and the next. + +\ **Note:** [AnimationNodeStateMachine](class_animationnodestatemachine.md) 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](class_animationnodeoutput.md) is considered as the most upstream, so the [xfade_time](class_animationnodestatemachinetransition.md#class_AnimationNodeStateMachineTransition_property_xfade_time) is not scaled depending on the downstream delta. See also [AnimationNodeOneShot.fadeout_time](class_animationnodeoneshot.md#class_AnimationNodeOneShot_property_fadeout_time). + diff --git a/docs/Classes/class_animationnodesub2.md b/docs/Classes/class_animationnodesub2.md new file mode 100644 index 00000000..3f98ac58 --- /dev/null +++ b/docs/Classes/class_animationnodesub2.md @@ -0,0 +1,33 @@ + + + + + + + + + +# AnimationNodeSub2 + +**Inherits:** [AnimationNodeSync](class_animationnodesync.md) **<** [AnimationNode](class_animationnode.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Blends two animations subtractively inside of an [AnimationNodeBlendTree](class_animationnodeblendtree.md). + + + +## Description + +A resource to add to an [AnimationNodeBlendTree](class_animationnodeblendtree.md). 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](class_animationnodeadd2.md) or [AnimationNodeAdd3](class_animationnodeadd3.md). + +In general, the blend value should be in the ``[0.0, 1.0]`` range, but values outside of this range can be used for amplified or inverted animations. + +\ **Note:** This calculation is different from using a negative value in [AnimationNodeAdd2](class_animationnodeadd2.md), 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](class_animationnodeadd2.md) multiplies it from the right side. + + + +## Tutorials + +- [AnimationTree](../tutorials/animation/animation_tree.md) + diff --git a/docs/Classes/class_animationnodesync.md b/docs/Classes/class_animationnodesync.md new file mode 100644 index 00000000..1b734c0b --- /dev/null +++ b/docs/Classes/class_animationnodesync.md @@ -0,0 +1,66 @@ + + + + + + + + + +# AnimationNodeSync + +**Inherits:** [AnimationNode](class_animationnode.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +**Inherited By:** [AnimationNodeAdd2](class_animationnodeadd2.md), [AnimationNodeAdd3](class_animationnodeadd3.md), [AnimationNodeBlend2](class_animationnodeblend2.md), [AnimationNodeBlend3](class_animationnodeblend3.md), [AnimationNodeOneShot](class_animationnodeoneshot.md), [AnimationNodeSub2](class_animationnodesub2.md), [AnimationNodeTransition](class_animationnodetransition.md) + +Base class for [AnimationNode](class_animationnode.md)\ s with multiple input ports that must be synchronized. + + + +## Description + +An animation node used to combine, mix, or blend two or more animations together while keeping them synchronized within an [AnimationTree](class_animationtree.md). + + + +## Tutorials + +- [Using AnimationTree](../tutorials/animation/animation_tree.md) + + + +## Properties + + + + + + + + + + + +
[bool](class_bool.md)[sync](#class_AnimationNodeSync_property_sync)`false`
+ +
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **sync** = `false` [🔗](#class_AnimationNodeSync_property_sync) + + + +- `void` **set_use_sync**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_using_sync**\ (\ ) + +If ``false``, the blended animations' frame are stopped when the blend value is ``0``. + +If ``true``, forcing the blended animations to advance frame. + diff --git a/docs/Classes/class_animationnodetimescale.md b/docs/Classes/class_animationnodetimescale.md new file mode 100644 index 00000000..55aa1d0a --- /dev/null +++ b/docs/Classes/class_animationnodetimescale.md @@ -0,0 +1,29 @@ + + + + + + + + + +# AnimationNodeTimeScale + +**Inherits:** [AnimationNode](class_animationnode.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +A time-scaling animation node used in [AnimationTree](class_animationtree.md). + + + +## Description + +Allows to scale the speed of the animation (or reverse it) in any child [AnimationNode](class_animationnode.md)\ s. Setting it to ``0.0`` will pause the animation. + + + +## Tutorials + +- [Using AnimationTree](../tutorials/animation/animation_tree.md) + +- [3D Platformer Demo](https://godotengine.org/asset-library/asset/2748) + diff --git a/docs/Classes/class_animationnodetimeseek.md b/docs/Classes/class_animationnodetimeseek.md new file mode 100644 index 00000000..64015dc3 --- /dev/null +++ b/docs/Classes/class_animationnodetimeseek.md @@ -0,0 +1,89 @@ + + + + + + + + + +# AnimationNodeTimeSeek + +**Inherits:** [AnimationNode](class_animationnode.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +A time-seeking animation node used in [AnimationTree](class_animationtree.md). + + + +## 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](class_animation.md) from the start or a certain playback position inside the [AnimationNodeBlendTree](class_animationnodeblendtree.md). + +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 ``seek_request`` value to ``-1.0``. + + + + +```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 +``` + +```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); +``` + + + + + +## Tutorials + +- [Using AnimationTree](../tutorials/animation/animation_tree.md) + + + +## Properties + + + + + + + + + + + +
[bool](class_bool.md)[explicit_elapse](#class_AnimationNodeTimeSeek_property_explicit_elapse)`true`
+ +
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **explicit_elapse** = `true` [🔗](#class_AnimationNodeTimeSeek_property_explicit_elapse) + + + +- `void` **set_explicit_elapse**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_explicit_elapse**\ (\ ) + +If ``true``, some processes are executed to handle keys between seeks, such as calculating root motion and finding the nearest discrete key. + diff --git a/docs/Classes/class_animationnodetransition.md b/docs/Classes/class_animationnodetransition.md new file mode 100644 index 00000000..b127e46b --- /dev/null +++ b/docs/Classes/class_animationnodetransition.md @@ -0,0 +1,264 @@ + + + + + + + + + +# AnimationNodeTransition + +**Inherits:** [AnimationNodeSync](class_animationnodesync.md) **<** [AnimationNode](class_animationnode.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +A transition within an [AnimationTree](class_animationtree.md) connecting two [AnimationNode](class_animationnode.md)\ s. + + + +## Description + +Simple state machine for cases which don't require a more advanced [AnimationNodeStateMachine](class_animationnodestatemachine.md). 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 ``transition_request`` value to empty. + +\ **Note:** When using a cross-fade, ``current_state`` and ``current_index`` change to the next state immediately after the cross-fade begins. + + + + +```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"] +``` + +```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"); +``` + + + + + +## Tutorials + +- [Using AnimationTree](../tutorials/animation/animation_tree.md) + +- [3D Platformer Demo](https://godotengine.org/asset-library/asset/2748) + +- [Third Person Shooter (TPS) Demo](https://godotengine.org/asset-library/asset/2710) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[allow_transition_to_self](#class_AnimationNodeTransition_property_allow_transition_to_self)`false`
[int](class_int.md)[input_count](#class_AnimationNodeTransition_property_input_count)`0`
[Curve](class_curve.md)[xfade_curve](#class_AnimationNodeTransition_property_xfade_curve)
[float](class_float.md)[xfade_time](#class_AnimationNodeTransition_property_xfade_time)`0.0`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[is_input_loop_broken_at_end](#class_AnimationNodeTransition_method_is_input_loop_broken_at_end)\ (\ input\: [int](class_int.md)\ ) const
[bool](class_bool.md)[is_input_reset](#class_AnimationNodeTransition_method_is_input_reset)\ (\ input\: [int](class_int.md)\ ) const
[bool](class_bool.md)[is_input_set_as_auto_advance](#class_AnimationNodeTransition_method_is_input_set_as_auto_advance)\ (\ input\: [int](class_int.md)\ ) const
`void`[set_input_as_auto_advance](#class_AnimationNodeTransition_method_set_input_as_auto_advance)\ (\ input\: [int](class_int.md), enable\: [bool](class_bool.md)\ )
`void`[set_input_break_loop_at_end](#class_AnimationNodeTransition_method_set_input_break_loop_at_end)\ (\ input\: [int](class_int.md), enable\: [bool](class_bool.md)\ )
`void`[set_input_reset](#class_AnimationNodeTransition_method_set_input_reset)\ (\ input\: [int](class_int.md), enable\: [bool](class_bool.md)\ )
+ +
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **allow_transition_to_self** = `false` [🔗](#class_AnimationNodeTransition_property_allow_transition_to_self) + + + +- `void` **set_allow_transition_to_self**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_allow_transition_to_self**\ (\ ) + +If ``true``, allows transition to the self state. When the reset option is enabled in input, the animation is restarted. If ``false``, nothing happens on the transition to the self state. + +
+ + + + + +[int](class_int.md) **input_count** = `0` [🔗](#class_AnimationNodeTransition_property_input_count) + + + +- `void` **set_input_count**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_input_count**\ (\ ) + +The number of enabled input ports for this animation node. + +
+ + + + + +[Curve](class_curve.md) **xfade_curve** [🔗](#class_AnimationNodeTransition_property_xfade_curve) + + + +- `void` **set_xfade_curve**\ (\ value\: [Curve](class_curve.md)\ ) +- [Curve](class_curve.md) **get_xfade_curve**\ (\ ) + +Determines how cross-fading between animations is eased. If empty, the transition will be linear. Should be a unit [Curve](class_curve.md). + +
+ + + + + +[float](class_float.md) **xfade_time** = `0.0` [🔗](#class_AnimationNodeTransition_property_xfade_time) + + + +- `void` **set_xfade_time**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_xfade_time**\ (\ ) + +Cross-fading time (in seconds) between each animation connected to the inputs. + +\ **Note:** **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](class_animationnodeoutput.md) is considered as the most upstream, so the [xfade_time](class_animationnodetransition.md#class_AnimationNodeTransition_property_xfade_time) is not scaled depending on the downstream delta. See also [AnimationNodeOneShot.fadeout_time](class_animationnodeoneshot.md#class_AnimationNodeOneShot_property_fadeout_time). + +
+ + + +## Method Descriptions + + + + + +[bool](class_bool.md) **is_input_loop_broken_at_end**\ (\ input\: [int](class_int.md)\ ) const [🔗](#class_AnimationNodeTransition_method_is_input_loop_broken_at_end) + +Returns whether the animation breaks the loop at the end of the loop cycle for transition. + +
+ + + + + +[bool](class_bool.md) **is_input_reset**\ (\ input\: [int](class_int.md)\ ) const [🔗](#class_AnimationNodeTransition_method_is_input_reset) + +Returns whether the animation restarts when the animation transitions from the other animation. + +
+ + + + + +[bool](class_bool.md) **is_input_set_as_auto_advance**\ (\ input\: [int](class_int.md)\ ) const [🔗](#class_AnimationNodeTransition_method_is_input_set_as_auto_advance) + +Returns ``true`` if auto-advance is enabled for the given `input` index. + +
+ + + + + +`void` **set_input_as_auto_advance**\ (\ input\: [int](class_int.md), enable\: [bool](class_bool.md)\ ) [🔗](#class_AnimationNodeTransition_method_set_input_as_auto_advance) + +Enables or disables auto-advance for the given `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. + +
+ + + + + +`void` **set_input_break_loop_at_end**\ (\ input\: [int](class_int.md), enable\: [bool](class_bool.md)\ ) [🔗](#class_AnimationNodeTransition_method_set_input_break_loop_at_end) + +If ``true``, breaks the loop at the end of the loop cycle for transition, even if the animation is looping. + +
+ + + + + +`void` **set_input_reset**\ (\ input\: [int](class_int.md), enable\: [bool](class_bool.md)\ ) [🔗](#class_AnimationNodeTransition_method_set_input_reset) + +If ``true``, the destination animation is restarted when the animation transitions. + diff --git a/docs/Classes/class_animationplayer.md b/docs/Classes/class_animationplayer.md new file mode 100644 index 00000000..bb839366 --- /dev/null +++ b/docs/Classes/class_animationplayer.md @@ -0,0 +1,892 @@ + + + + + + + + + +# AnimationPlayer + +**Inherits:** [AnimationMixer](class_animationmixer.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +A node used for animation playback. + + + +## Description + +An animation player is used for general-purpose playback of animations. It contains a dictionary of [AnimationLibrary](class_animationlibrary.md) 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 ``"movement/run"``. 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](class_tween.md) for more complex animations, for example ones with non-trivial timings. It can also be used over [Tween](class_tween.md) if the animation track editor is more convenient than doing it in code. + +Updating the target properties of animations occurs at the process frame. + + + +## Tutorials + +- [2D Sprite animation](../tutorials/2d/2d_sprite_animation.md) + +- [Animation documentation index](../tutorials/animation/index.md) + +- [Third Person Shooter (TPS) Demo](https://godotengine.org/asset-library/asset/2710) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[String](class_string.md)[assigned_animation](#class_AnimationPlayer_property_assigned_animation)
[String](class_string.md)[autoplay](#class_AnimationPlayer_property_autoplay)`""`
[String](class_string.md)[current_animation](#class_AnimationPlayer_property_current_animation)`""`
[float](class_float.md)[current_animation_length](#class_AnimationPlayer_property_current_animation_length)
[float](class_float.md)[current_animation_position](#class_AnimationPlayer_property_current_animation_position)
[bool](class_bool.md)[movie_quit_on_finish](#class_AnimationPlayer_property_movie_quit_on_finish)`false`
[bool](class_bool.md)[playback_auto_capture](#class_AnimationPlayer_property_playback_auto_capture)`true`
[float](class_float.md)[playback_auto_capture_duration](#class_AnimationPlayer_property_playback_auto_capture_duration)`-1.0`
[EaseType](class_tween.md#enum_Tween_EaseType)[playback_auto_capture_ease_type](#class_AnimationPlayer_property_playback_auto_capture_ease_type)`0`
[TransitionType](class_tween.md#enum_Tween_TransitionType)[playback_auto_capture_transition_type](#class_AnimationPlayer_property_playback_auto_capture_transition_type)`0`
[float](class_float.md)[playback_default_blend_time](#class_AnimationPlayer_property_playback_default_blend_time)`0.0`
[float](class_float.md)[speed_scale](#class_AnimationPlayer_property_speed_scale)`1.0`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[StringName](class_stringname.md)[animation_get_next](#class_AnimationPlayer_method_animation_get_next)\ (\ animation_from\: [StringName](class_stringname.md)\ ) const
`void`[animation_set_next](#class_AnimationPlayer_method_animation_set_next)\ (\ animation_from\: [StringName](class_stringname.md), animation_to\: [StringName](class_stringname.md)\ )
`void`[clear_queue](#class_AnimationPlayer_method_clear_queue)\ (\ )
[float](class_float.md)[get_blend_time](#class_AnimationPlayer_method_get_blend_time)\ (\ animation_from\: [StringName](class_stringname.md), animation_to\: [StringName](class_stringname.md)\ ) const
[AnimationMethodCallMode](class_animationplayer.md#enum_AnimationPlayer_AnimationMethodCallMode)[get_method_call_mode](#class_AnimationPlayer_method_get_method_call_mode)\ (\ ) const
[float](class_float.md)[get_playing_speed](#class_AnimationPlayer_method_get_playing_speed)\ (\ ) const
[AnimationProcessCallback](class_animationplayer.md#enum_AnimationPlayer_AnimationProcessCallback)[get_process_callback](#class_AnimationPlayer_method_get_process_callback)\ (\ ) const
[PackedStringArray](class_packedstringarray.md)[get_queue](#class_AnimationPlayer_method_get_queue)\ (\ )
[NodePath](class_nodepath.md)[get_root](#class_AnimationPlayer_method_get_root)\ (\ ) const
[float](class_float.md)[get_section_end_time](#class_AnimationPlayer_method_get_section_end_time)\ (\ ) const
[float](class_float.md)[get_section_start_time](#class_AnimationPlayer_method_get_section_start_time)\ (\ ) const
[bool](class_bool.md)[has_section](#class_AnimationPlayer_method_has_section)\ (\ ) const
[bool](class_bool.md)[is_playing](#class_AnimationPlayer_method_is_playing)\ (\ ) const
`void`[pause](#class_AnimationPlayer_method_pause)\ (\ )
`void`[play](#class_AnimationPlayer_method_play)\ (\ name\: [StringName](class_stringname.md) = &"", custom_blend\: [float](class_float.md) = -1, custom_speed\: [float](class_float.md) = 1.0, from_end\: [bool](class_bool.md) = false\ )
`void`[play_backwards](#class_AnimationPlayer_method_play_backwards)\ (\ name\: [StringName](class_stringname.md) = &"", custom_blend\: [float](class_float.md) = -1\ )
`void`[play_section](#class_AnimationPlayer_method_play_section)\ (\ name\: [StringName](class_stringname.md) = &"", start_time\: [float](class_float.md) = -1, end_time\: [float](class_float.md) = -1, custom_blend\: [float](class_float.md) = -1, custom_speed\: [float](class_float.md) = 1.0, from_end\: [bool](class_bool.md) = false\ )
`void`[play_section_backwards](#class_AnimationPlayer_method_play_section_backwards)\ (\ name\: [StringName](class_stringname.md) = &"", start_time\: [float](class_float.md) = -1, end_time\: [float](class_float.md) = -1, custom_blend\: [float](class_float.md) = -1\ )
`void`[play_section_with_markers](#class_AnimationPlayer_method_play_section_with_markers)\ (\ name\: [StringName](class_stringname.md) = &"", start_marker\: [StringName](class_stringname.md) = &"", end_marker\: [StringName](class_stringname.md) = &"", custom_blend\: [float](class_float.md) = -1, custom_speed\: [float](class_float.md) = 1.0, from_end\: [bool](class_bool.md) = false\ )
`void`[play_section_with_markers_backwards](#class_AnimationPlayer_method_play_section_with_markers_backwards)\ (\ name\: [StringName](class_stringname.md) = &"", start_marker\: [StringName](class_stringname.md) = &"", end_marker\: [StringName](class_stringname.md) = &"", custom_blend\: [float](class_float.md) = -1\ )
`void`[play_with_capture](#class_AnimationPlayer_method_play_with_capture)\ (\ name\: [StringName](class_stringname.md) = &"", duration\: [float](class_float.md) = -1.0, custom_blend\: [float](class_float.md) = -1, custom_speed\: [float](class_float.md) = 1.0, from_end\: [bool](class_bool.md) = false, trans_type\: [TransitionType](class_tween.md#enum_Tween_TransitionType) = 0, ease_type\: [EaseType](class_tween.md#enum_Tween_EaseType) = 0\ )
`void`[queue](#class_AnimationPlayer_method_queue)\ (\ name\: [StringName](class_stringname.md)\ )
`void`[reset_section](#class_AnimationPlayer_method_reset_section)\ (\ )
`void`[seek](#class_AnimationPlayer_method_seek)\ (\ seconds\: [float](class_float.md), update\: [bool](class_bool.md) = false, update_only\: [bool](class_bool.md) = false\ )
`void`[set_blend_time](#class_AnimationPlayer_method_set_blend_time)\ (\ animation_from\: [StringName](class_stringname.md), animation_to\: [StringName](class_stringname.md), sec\: [float](class_float.md)\ )
`void`[set_method_call_mode](#class_AnimationPlayer_method_set_method_call_mode)\ (\ mode\: [AnimationMethodCallMode](class_animationplayer.md#enum_AnimationPlayer_AnimationMethodCallMode)\ )
`void`[set_process_callback](#class_AnimationPlayer_method_set_process_callback)\ (\ mode\: [AnimationProcessCallback](class_animationplayer.md#enum_AnimationPlayer_AnimationProcessCallback)\ )
`void`[set_root](#class_AnimationPlayer_method_set_root)\ (\ path\: [NodePath](class_nodepath.md)\ )
`void`[set_section](#class_AnimationPlayer_method_set_section)\ (\ start_time\: [float](class_float.md) = -1, end_time\: [float](class_float.md) = -1\ )
`void`[set_section_with_markers](#class_AnimationPlayer_method_set_section_with_markers)\ (\ start_marker\: [StringName](class_stringname.md) = &"", end_marker\: [StringName](class_stringname.md) = &""\ )
`void`[stop](#class_AnimationPlayer_method_stop)\ (\ keep_state\: [bool](class_bool.md) = false\ )
+ +
+ + + +## Signals + + + + + +**animation_changed**\ (\ old_name\: [StringName](class_stringname.md), new_name\: [StringName](class_stringname.md)\ ) [🔗](#class_AnimationPlayer_signal_animation_changed) + +Emitted when a queued animation plays after the previous animation finished. See also [queue()](class_animationplayer.md#class_AnimationPlayer_method_queue). + +\ **Note:** The signal is not emitted when the animation is changed via [play()](class_animationplayer.md#class_AnimationPlayer_method_play) or by an [AnimationTree](class_animationtree.md). + +
+ + + + + +**current_animation_changed**\ (\ name\: [String](class_string.md)\ ) [🔗](#class_AnimationPlayer_signal_current_animation_changed) + +Emitted when [current_animation](class_animationplayer.md#class_AnimationPlayer_property_current_animation) changes. + +
+ + + +## Enumerations + + + + + +enum **AnimationProcessCallback**: [🔗](#enum_AnimationPlayer_AnimationProcessCallback) + + + + + +[AnimationProcessCallback](class_animationplayer.md#enum_AnimationPlayer_AnimationProcessCallback) **ANIMATION_PROCESS_PHYSICS** = `0` + +**Deprecated:** See [AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS](class_animationmixer.md#class_AnimationMixer_constant_ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS). + + + + + +[AnimationProcessCallback](class_animationplayer.md#enum_AnimationPlayer_AnimationProcessCallback) **ANIMATION_PROCESS_IDLE** = `1` + +**Deprecated:** See [AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_IDLE](class_animationmixer.md#class_AnimationMixer_constant_ANIMATION_CALLBACK_MODE_PROCESS_IDLE). + + + + + +[AnimationProcessCallback](class_animationplayer.md#enum_AnimationPlayer_AnimationProcessCallback) **ANIMATION_PROCESS_MANUAL** = `2` + +**Deprecated:** See [AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_MANUAL](class_animationmixer.md#class_AnimationMixer_constant_ANIMATION_CALLBACK_MODE_PROCESS_MANUAL). + +
+ + + + + +enum **AnimationMethodCallMode**: [🔗](#enum_AnimationPlayer_AnimationMethodCallMode) + + + + + +[AnimationMethodCallMode](class_animationplayer.md#enum_AnimationPlayer_AnimationMethodCallMode) **ANIMATION_METHOD_CALL_DEFERRED** = `0` + +**Deprecated:** See [AnimationMixer.ANIMATION_CALLBACK_MODE_METHOD_DEFERRED](class_animationmixer.md#class_AnimationMixer_constant_ANIMATION_CALLBACK_MODE_METHOD_DEFERRED). + + + + + +[AnimationMethodCallMode](class_animationplayer.md#enum_AnimationPlayer_AnimationMethodCallMode) **ANIMATION_METHOD_CALL_IMMEDIATE** = `1` + +**Deprecated:** See [AnimationMixer.ANIMATION_CALLBACK_MODE_METHOD_IMMEDIATE](class_animationmixer.md#class_AnimationMixer_constant_ANIMATION_CALLBACK_MODE_METHOD_IMMEDIATE). + +
+ + + +## Property Descriptions + + + + + +[String](class_string.md) **assigned_animation** [🔗](#class_AnimationPlayer_property_assigned_animation) + + + +- `void` **set_assigned_animation**\ (\ value\: [String](class_string.md)\ ) +- [String](class_string.md) **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 [current_animation](class_animationplayer.md#class_AnimationPlayer_property_current_animation). + +
+ + + + + +[String](class_string.md) **autoplay** = `""` [🔗](#class_AnimationPlayer_property_autoplay) + + + +- `void` **set_autoplay**\ (\ value\: [String](class_string.md)\ ) +- [String](class_string.md) **get_autoplay**\ (\ ) + +The key of the animation to play when the scene loads. + +
+ + + + + +[String](class_string.md) **current_animation** = `""` [🔗](#class_AnimationPlayer_property_current_animation) + + + +- `void` **set_current_animation**\ (\ value\: [String](class_string.md)\ ) +- [String](class_string.md) **get_current_animation**\ (\ ) + +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 [play()](class_animationplayer.md#class_AnimationPlayer_method_play) for more information on playing animations. + +\ **Note:** 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](class_animation.md). + +
+ + + + + +[float](class_float.md) **current_animation_length** [🔗](#class_AnimationPlayer_property_current_animation_length) + + + +- [float](class_float.md) **get_current_animation_length**\ (\ ) + +The length (in seconds) of the currently playing animation. + +
+ + + + + +[float](class_float.md) **current_animation_position** [🔗](#class_AnimationPlayer_property_current_animation_position) + + + +- [float](class_float.md) **get_current_animation_position**\ (\ ) + +The position (in seconds) of the currently playing animation. + +
+ + + + + +[bool](class_bool.md) **movie_quit_on_finish** = `false` [🔗](#class_AnimationPlayer_property_movie_quit_on_finish) + + + +- `void` **set_movie_quit_on_finish_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_movie_quit_on_finish_enabled**\ (\ ) + +If ``true`` and the engine is running in Movie Maker mode (see [MovieWriter](class_moviewriter.md)), exits the engine with [SceneTree.quit()](class_scenetree.md#class_SceneTree_method_quit) as soon as an animation is done playing in this **AnimationPlayer**. A message is printed when the engine quits for this reason. + +\ **Note:** This obeys the same logic as the [AnimationMixer.animation_finished](class_animationmixer.md#class_AnimationMixer_signal_animation_finished) signal, so it will not quit the engine if the animation is set to be looping. + +
+ + + + + +[bool](class_bool.md) **playback_auto_capture** = `true` [🔗](#class_AnimationPlayer_property_playback_auto_capture) + + + +- `void` **set_auto_capture**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_auto_capture**\ (\ ) + +If ``true``, performs [AnimationMixer.capture()](class_animationmixer.md#class_AnimationMixer_method_capture) before playback automatically. This means just [play_with_capture()](class_animationplayer.md#class_AnimationPlayer_method_play_with_capture) is executed with default arguments instead of [play()](class_animationplayer.md#class_AnimationPlayer_method_play). + +\ **Note:** Capture interpolation is only performed if the animation contains a capture track. See also [Animation.UPDATE_CAPTURE](class_animation.md#class_Animation_constant_UPDATE_CAPTURE). + +
+ + + + + +[float](class_float.md) **playback_auto_capture_duration** = `-1.0` [🔗](#class_AnimationPlayer_property_playback_auto_capture_duration) + + + +- `void` **set_auto_capture_duration**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_auto_capture_duration**\ (\ ) + +See also [play_with_capture()](class_animationplayer.md#class_AnimationPlayer_method_play_with_capture) and [AnimationMixer.capture()](class_animationmixer.md#class_AnimationMixer_method_capture). + +If [playback_auto_capture_duration](class_animationplayer.md#class_AnimationPlayer_property_playback_auto_capture_duration) is negative value, the duration is set to the interval between the current position and the first key. + +
+ + + + + +[EaseType](class_tween.md#enum_Tween_EaseType) **playback_auto_capture_ease_type** = `0` [🔗](#class_AnimationPlayer_property_playback_auto_capture_ease_type) + + + +- `void` **set_auto_capture_ease_type**\ (\ value\: [EaseType](class_tween.md#enum_Tween_EaseType)\ ) +- [EaseType](class_tween.md#enum_Tween_EaseType) **get_auto_capture_ease_type**\ (\ ) + +The ease type of the capture interpolation. See also [EaseType](class_tween.md#enum_Tween_EaseType). + +
+ + + + + +[TransitionType](class_tween.md#enum_Tween_TransitionType) **playback_auto_capture_transition_type** = `0` [🔗](#class_AnimationPlayer_property_playback_auto_capture_transition_type) + + + +- `void` **set_auto_capture_transition_type**\ (\ value\: [TransitionType](class_tween.md#enum_Tween_TransitionType)\ ) +- [TransitionType](class_tween.md#enum_Tween_TransitionType) **get_auto_capture_transition_type**\ (\ ) + +The transition type of the capture interpolation. See also [TransitionType](class_tween.md#enum_Tween_TransitionType). + +
+ + + + + +[float](class_float.md) **playback_default_blend_time** = `0.0` [🔗](#class_AnimationPlayer_property_playback_default_blend_time) + + + +- `void` **set_default_blend_time**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_default_blend_time**\ (\ ) + +The default time in which to blend animations. Ranges from 0 to 4096 with 0.01 precision. + +
+ + + + + +[float](class_float.md) **speed_scale** = `1.0` [🔗](#class_AnimationPlayer_property_speed_scale) + + + +- `void` **set_speed_scale**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_speed_scale**\ (\ ) + +The speed scaling ratio. For example, if this value is ``1``, then the animation plays at normal speed. If it's ``0.5``, then it plays at half speed. If it's ``2``, then it plays at double speed. + +If set to a negative value, the animation is played in reverse. If set to ``0``, the animation will not advance. + +
+ + + +## Method Descriptions + + + + + +[StringName](class_stringname.md) **animation_get_next**\ (\ animation_from\: [StringName](class_stringname.md)\ ) const [🔗](#class_AnimationPlayer_method_animation_get_next) + +Returns the key of the animation which is queued to play after the `animation_from` animation. + +
+ + + + + +`void` **animation_set_next**\ (\ animation_from\: [StringName](class_stringname.md), animation_to\: [StringName](class_stringname.md)\ ) [🔗](#class_AnimationPlayer_method_animation_set_next) + +Triggers the `animation_to` animation when the `animation_from` animation completes. + +
+ + + + + +`void` **clear_queue**\ (\ ) [🔗](#class_AnimationPlayer_method_clear_queue) + +Clears all queued, unplayed animations. + +
+ + + + + +[float](class_float.md) **get_blend_time**\ (\ animation_from\: [StringName](class_stringname.md), animation_to\: [StringName](class_stringname.md)\ ) const [🔗](#class_AnimationPlayer_method_get_blend_time) + +Returns the blend time (in seconds) between two animations, referenced by their keys. + +
+ + + + + +[AnimationMethodCallMode](class_animationplayer.md#enum_AnimationPlayer_AnimationMethodCallMode) **get_method_call_mode**\ (\ ) const [🔗](#class_AnimationPlayer_method_get_method_call_mode) + +**Deprecated:** Use [AnimationMixer.callback_mode_method](class_animationmixer.md#class_AnimationMixer_property_callback_mode_method) instead. + +Returns the call mode used for "Call Method" tracks. + +
+ + + + + +[float](class_float.md) **get_playing_speed**\ (\ ) const [🔗](#class_AnimationPlayer_method_get_playing_speed) + +Returns the actual playing speed of current animation or ``0`` if not playing. This speed is the [speed_scale](class_animationplayer.md#class_AnimationPlayer_property_speed_scale) property multiplied by ``custom_speed`` argument specified when calling the [play()](class_animationplayer.md#class_AnimationPlayer_method_play) method. + +Returns a negative value if the current animation is playing backwards. + +
+ + + + + +[AnimationProcessCallback](class_animationplayer.md#enum_AnimationPlayer_AnimationProcessCallback) **get_process_callback**\ (\ ) const [🔗](#class_AnimationPlayer_method_get_process_callback) + +**Deprecated:** Use [AnimationMixer.callback_mode_process](class_animationmixer.md#class_AnimationMixer_property_callback_mode_process) instead. + +Returns the process notification in which to update animations. + +
+ + + + + +[PackedStringArray](class_packedstringarray.md) **get_queue**\ (\ ) [🔗](#class_AnimationPlayer_method_get_queue) + +Returns a list of the animation keys that are currently queued to play. + +
+ + + + + +[NodePath](class_nodepath.md) **get_root**\ (\ ) const [🔗](#class_AnimationPlayer_method_get_root) + +**Deprecated:** Use [AnimationMixer.root_node](class_animationmixer.md#class_AnimationMixer_property_root_node) instead. + +Returns the node which node path references will travel from. + +
+ + + + + +[float](class_float.md) **get_section_end_time**\ (\ ) const [🔗](#class_AnimationPlayer_method_get_section_end_time) + +Returns the end time of the section currently being played. + +
+ + + + + +[float](class_float.md) **get_section_start_time**\ (\ ) const [🔗](#class_AnimationPlayer_method_get_section_start_time) + +Returns the start time of the section currently being played. + +
+ + + + + +[bool](class_bool.md) **has_section**\ (\ ) const [🔗](#class_AnimationPlayer_method_has_section) + +Returns ``true`` if an animation is currently playing with a section. + +
+ + + + + +[bool](class_bool.md) **is_playing**\ (\ ) const [🔗](#class_AnimationPlayer_method_is_playing) + +Returns ``true`` if an animation is currently playing (even if [speed_scale](class_animationplayer.md#class_AnimationPlayer_property_speed_scale) and/or ``custom_speed`` are ``0``). + +
+ + + + + +`void` **pause**\ (\ ) [🔗](#class_AnimationPlayer_method_pause) + +Pauses the currently playing animation. The [current_animation_position](class_animationplayer.md#class_AnimationPlayer_property_current_animation_position) will be kept and calling [play()](class_animationplayer.md#class_AnimationPlayer_method_play) or [play_backwards()](class_animationplayer.md#class_AnimationPlayer_method_play_backwards) without arguments or with the same animation name as [assigned_animation](class_animationplayer.md#class_AnimationPlayer_property_assigned_animation) will resume the animation. + +See also [stop()](class_animationplayer.md#class_AnimationPlayer_method_stop). + +
+ + + + + +`void` **play**\ (\ name\: [StringName](class_stringname.md) = &"", custom_blend\: [float](class_float.md) = -1, custom_speed\: [float](class_float.md) = 1.0, from_end\: [bool](class_bool.md) = false\ ) [🔗](#class_AnimationPlayer_method_play) + +Plays the animation with key `name`. Custom blend times and speed can be set. + +The `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 `custom_speed` is negative and `from_end` is ``true``, the animation will play backwards (which is equivalent to calling [play_backwards()](class_animationplayer.md#class_AnimationPlayer_method_play_backwards)). + +The **AnimationPlayer** keeps track of its current or last played animation with [assigned_animation](class_animationplayer.md#class_AnimationPlayer_property_assigned_animation). If this method is called with that same animation `name`, or with no `name` parameter, the assigned animation will resume playing if it was paused. + +\ **Note:** 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 ``advance(0)``. + +
+ + + + + +`void` **play_backwards**\ (\ name\: [StringName](class_stringname.md) = &"", custom_blend\: [float](class_float.md) = -1\ ) [🔗](#class_AnimationPlayer_method_play_backwards) + +Plays the animation with key `name` in reverse. + +This method is a shorthand for [play()](class_animationplayer.md#class_AnimationPlayer_method_play) with ``custom_speed = -1.0`` and ``from_end = true``, so see its description for more information. + +
+ + + + + +`void` **play_section**\ (\ name\: [StringName](class_stringname.md) = &"", start_time\: [float](class_float.md) = -1, end_time\: [float](class_float.md) = -1, custom_blend\: [float](class_float.md) = -1, custom_speed\: [float](class_float.md) = 1.0, from_end\: [bool](class_bool.md) = false\ ) [🔗](#class_AnimationPlayer_method_play_section) + +Plays the animation with key `name` and the section starting from `start_time` and ending on `end_time`. See also [play()](class_animationplayer.md#class_AnimationPlayer_method_play). + +Setting `start_time` to a value outside the range of the animation means the start of the animation will be used instead, and setting `end_time` to a value outside the range of the animation means the end of the animation will be used instead. `start_time` cannot be equal to `end_time`. + +
+ + + + + +`void` **play_section_backwards**\ (\ name\: [StringName](class_stringname.md) = &"", start_time\: [float](class_float.md) = -1, end_time\: [float](class_float.md) = -1, custom_blend\: [float](class_float.md) = -1\ ) [🔗](#class_AnimationPlayer_method_play_section_backwards) + +Plays the animation with key `name` and the section starting from `start_time` and ending on `end_time` in reverse. + +This method is a shorthand for [play_section()](class_animationplayer.md#class_AnimationPlayer_method_play_section) with ``custom_speed = -1.0`` and ``from_end = true``, see its description for more information. + +
+ + + + + +`void` **play_section_with_markers**\ (\ name\: [StringName](class_stringname.md) = &"", start_marker\: [StringName](class_stringname.md) = &"", end_marker\: [StringName](class_stringname.md) = &"", custom_blend\: [float](class_float.md) = -1, custom_speed\: [float](class_float.md) = 1.0, from_end\: [bool](class_bool.md) = false\ ) [🔗](#class_AnimationPlayer_method_play_section_with_markers) + +Plays the animation with key `name` and the section starting from `start_marker` and ending on `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 [play()](class_animationplayer.md#class_AnimationPlayer_method_play). + +
+ + + + + +`void` **play_section_with_markers_backwards**\ (\ name\: [StringName](class_stringname.md) = &"", start_marker\: [StringName](class_stringname.md) = &"", end_marker\: [StringName](class_stringname.md) = &"", custom_blend\: [float](class_float.md) = -1\ ) [🔗](#class_AnimationPlayer_method_play_section_with_markers_backwards) + +Plays the animation with key `name` and the section starting from `start_marker` and ending on `end_marker` in reverse. + +This method is a shorthand for [play_section_with_markers()](class_animationplayer.md#class_AnimationPlayer_method_play_section_with_markers) with ``custom_speed = -1.0`` and ``from_end = true``, see its description for more information. + +
+ + + + + +`void` **play_with_capture**\ (\ name\: [StringName](class_stringname.md) = &"", duration\: [float](class_float.md) = -1.0, custom_blend\: [float](class_float.md) = -1, custom_speed\: [float](class_float.md) = 1.0, from_end\: [bool](class_bool.md) = false, trans_type\: [TransitionType](class_tween.md#enum_Tween_TransitionType) = 0, ease_type\: [EaseType](class_tween.md#enum_Tween_EaseType) = 0\ ) [🔗](#class_AnimationPlayer_method_play_with_capture) + +See also [AnimationMixer.capture()](class_animationmixer.md#class_AnimationMixer_method_capture). + +You can use this method to use more detailed options for capture than those performed by [playback_auto_capture](class_animationplayer.md#class_AnimationPlayer_property_playback_auto_capture). When [playback_auto_capture](class_animationplayer.md#class_AnimationPlayer_property_playback_auto_capture) is ``false``, this method is almost the same as the following: + +``` + capture(name, duration, trans_type, ease_type) + play(name, custom_blend, custom_speed, from_end) +``` + +If `name` is blank, it specifies [assigned_animation](class_animationplayer.md#class_AnimationPlayer_property_assigned_animation). + +If `duration` is a negative value, the duration is set to the interval between the current position and the first key, when `from_end` is ``true``, uses the interval between the current position and the last key instead. + +\ **Note:** The `duration` takes [speed_scale](class_animationplayer.md#class_AnimationPlayer_property_speed_scale) into account, but `custom_speed` does not, because the capture cache is interpolated with the blend result and the result may contain multiple animations. + +
+ + + + + +`void` **queue**\ (\ name\: [StringName](class_stringname.md)\ ) [🔗](#class_AnimationPlayer_method_queue) + +Queues an animation for playback once the current animation and all previously queued animations are done. + +\ **Note:** If a looped animation is currently playing, the queued animation will never play unless the looped animation is stopped somehow. + +
+ + + + + +`void` **reset_section**\ (\ ) [🔗](#class_AnimationPlayer_method_reset_section) + +Resets the current section. Does nothing if a section has not been set. + +
+ + + + + +`void` **seek**\ (\ seconds\: [float](class_float.md), update\: [bool](class_bool.md) = false, update_only\: [bool](class_bool.md) = false\ ) [🔗](#class_AnimationPlayer_method_seek) + +Seeks the animation to the `seconds` point in time (in seconds). If `update` is ``true``, the animation updates too, otherwise it updates at process time. Events between the current frame and `seconds` are skipped. + +If `update_only` is ``true``, the method / audio / animation playback tracks will not be processed. + +\ **Note:** Seeking to the end of the animation doesn't emit [AnimationMixer.animation_finished](class_animationmixer.md#class_AnimationMixer_signal_animation_finished). If you want to skip animation and emit the signal, use [AnimationMixer.advance()](class_animationmixer.md#class_AnimationMixer_method_advance). + +
+ + + + + +`void` **set_blend_time**\ (\ animation_from\: [StringName](class_stringname.md), animation_to\: [StringName](class_stringname.md), sec\: [float](class_float.md)\ ) [🔗](#class_AnimationPlayer_method_set_blend_time) + +Specifies a blend time (in seconds) between two animations, referenced by their keys. + +
+ + + + + +`void` **set_method_call_mode**\ (\ mode\: [AnimationMethodCallMode](class_animationplayer.md#enum_AnimationPlayer_AnimationMethodCallMode)\ ) [🔗](#class_AnimationPlayer_method_set_method_call_mode) + +**Deprecated:** Use [AnimationMixer.callback_mode_method](class_animationmixer.md#class_AnimationMixer_property_callback_mode_method) instead. + +Sets the call mode used for "Call Method" tracks. + +
+ + + + + +`void` **set_process_callback**\ (\ mode\: [AnimationProcessCallback](class_animationplayer.md#enum_AnimationPlayer_AnimationProcessCallback)\ ) [🔗](#class_AnimationPlayer_method_set_process_callback) + +**Deprecated:** Use [AnimationMixer.callback_mode_process](class_animationmixer.md#class_AnimationMixer_property_callback_mode_process) instead. + +Sets the process notification in which to update animations. + +
+ + + + + +`void` **set_root**\ (\ path\: [NodePath](class_nodepath.md)\ ) [🔗](#class_AnimationPlayer_method_set_root) + +**Deprecated:** Use [AnimationMixer.root_node](class_animationmixer.md#class_AnimationMixer_property_root_node) instead. + +Sets the node which node path references will travel from. + +
+ + + + + +`void` **set_section**\ (\ start_time\: [float](class_float.md) = -1, end_time\: [float](class_float.md) = -1\ ) [🔗](#class_AnimationPlayer_method_set_section) + +Changes the start and end times of the section being played. The current playback position will be clamped within the new section. See also [play_section()](class_animationplayer.md#class_AnimationPlayer_method_play_section). + +
+ + + + + +`void` **set_section_with_markers**\ (\ start_marker\: [StringName](class_stringname.md) = &"", end_marker\: [StringName](class_stringname.md) = &""\ ) [🔗](#class_AnimationPlayer_method_set_section_with_markers) + +Changes the start and end markers of the section being played. The current playback position will be clamped within the new section. See also [play_section_with_markers()](class_animationplayer.md#class_AnimationPlayer_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. + +
+ + + + + +`void` **stop**\ (\ keep_state\: [bool](class_bool.md) = false\ ) [🔗](#class_AnimationPlayer_method_stop) + +Stops the currently playing animation. The animation position is reset to ``0`` and the ``custom_speed`` is reset to ``1.0``. See also [pause()](class_animationplayer.md#class_AnimationPlayer_method_pause). + +If `keep_state` is ``true``, the animation state is not updated visually. + +\ **Note:** The method / audio / animation playback tracks will not be processed by this method. + diff --git a/docs/Classes/class_animationrootnode.md b/docs/Classes/class_animationrootnode.md new file mode 100644 index 00000000..2a4cd2cc --- /dev/null +++ b/docs/Classes/class_animationrootnode.md @@ -0,0 +1,31 @@ + + + + + + + + + +# AnimationRootNode + +**Inherits:** [AnimationNode](class_animationnode.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +**Inherited By:** [AnimationNodeAnimation](class_animationnodeanimation.md), [AnimationNodeBlendSpace1D](class_animationnodeblendspace1d.md), [AnimationNodeBlendSpace2D](class_animationnodeblendspace2d.md), [AnimationNodeBlendTree](class_animationnodeblendtree.md), [AnimationNodeStateMachine](class_animationnodestatemachine.md) + +Base class for [AnimationNode](class_animationnode.md)\ s that hold one or multiple composite animations. Usually used for [AnimationTree.tree_root](class_animationtree.md#class_AnimationTree_property_tree_root). + + + +## Description + +**AnimationRootNode** is a base class for [AnimationNode](class_animationnode.md)\ s that hold a complete animation. A complete animation refers to the output of an [AnimationNodeOutput](class_animationnodeoutput.md) in an [AnimationNodeBlendTree](class_animationnodeblendtree.md) or the output of another **AnimationRootNode**. Used for [AnimationTree.tree_root](class_animationtree.md#class_AnimationTree_property_tree_root) or in other **AnimationRootNode**\ s. + +Examples of built-in root nodes include [AnimationNodeBlendTree](class_animationnodeblendtree.md) (allows blending nodes between each other using various modes), [AnimationNodeStateMachine](class_animationnodestatemachine.md) (allows to configure blending and transitions between nodes using a state machine pattern), [AnimationNodeBlendSpace2D](class_animationnodeblendspace2d.md) (allows linear blending between **three** [AnimationNode](class_animationnode.md)\ s), [AnimationNodeBlendSpace1D](class_animationnodeblendspace1d.md) (allows linear blending only between **two** [AnimationNode](class_animationnode.md)\ s). + + + +## Tutorials + +- [Using AnimationTree](../tutorials/animation/animation_tree.md) + diff --git a/docs/Classes/class_animationtree.md b/docs/Classes/class_animationtree.md new file mode 100644 index 00000000..9b4e81e0 --- /dev/null +++ b/docs/Classes/class_animationtree.md @@ -0,0 +1,213 @@ + + + + + + + + + +# AnimationTree + +**Inherits:** [AnimationMixer](class_animationmixer.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +A node used for advanced animation transitions in an [AnimationPlayer](class_animationplayer.md). + + + +## Description + +A node used for advanced animation transitions in an [AnimationPlayer](class_animationplayer.md). + +\ **Note:** When linked with an [AnimationPlayer](class_animationplayer.md), several properties and methods of the corresponding [AnimationPlayer](class_animationplayer.md) will not function as expected. Playback and transitions should be handled using only the **AnimationTree** and its constituent [AnimationNode](class_animationnode.md)\ (s). The [AnimationPlayer](class_animationplayer.md) node should be used solely for adding, deleting, and editing animations. + + + +## Tutorials + +- [Using AnimationTree](../tutorials/animation/animation_tree.md) + +- [Third Person Shooter (TPS) Demo](https://godotengine.org/asset-library/asset/2710) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[NodePath](class_nodepath.md)[advance_expression_base_node](#class_AnimationTree_property_advance_expression_base_node)`NodePath(".")`
[NodePath](class_nodepath.md)[anim_player](#class_AnimationTree_property_anim_player)`NodePath("")`
[AnimationCallbackModeDiscrete](class_animationmixer.md#enum_AnimationMixer_AnimationCallbackModeDiscrete)callback_mode_discrete`2` (overrides [AnimationMixer.callback_mode_discrete](class_animationmixer.md#class_AnimationMixer_property_callback_mode_discrete))
[bool](class_bool.md)deterministic`true` (overrides [AnimationMixer.deterministic](class_animationmixer.md#class_AnimationMixer_property_deterministic))
[AnimationRootNode](class_animationrootnode.md)[tree_root](#class_AnimationTree_property_tree_root)
+ + + +## Methods + + + + + + + + + + + + + + +
[AnimationProcessCallback](class_animationtree.md#enum_AnimationTree_AnimationProcessCallback)[get_process_callback](#class_AnimationTree_method_get_process_callback)\ (\ ) const
`void`[set_process_callback](#class_AnimationTree_method_set_process_callback)\ (\ mode\: [AnimationProcessCallback](class_animationtree.md#enum_AnimationTree_AnimationProcessCallback)\ )
+ +
+ + + +## Signals + + + + + +**animation_player_changed**\ (\ ) [🔗](#class_AnimationTree_signal_animation_player_changed) + +Emitted when the [anim_player](class_animationtree.md#class_AnimationTree_property_anim_player) is changed. + +
+ + + +## Enumerations + + + + + +enum **AnimationProcessCallback**: [🔗](#enum_AnimationTree_AnimationProcessCallback) + + + + + +[AnimationProcessCallback](class_animationtree.md#enum_AnimationTree_AnimationProcessCallback) **ANIMATION_PROCESS_PHYSICS** = `0` + +**Deprecated:** See [AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS](class_animationmixer.md#class_AnimationMixer_constant_ANIMATION_CALLBACK_MODE_PROCESS_PHYSICS). + + + + + +[AnimationProcessCallback](class_animationtree.md#enum_AnimationTree_AnimationProcessCallback) **ANIMATION_PROCESS_IDLE** = `1` + +**Deprecated:** See [AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_IDLE](class_animationmixer.md#class_AnimationMixer_constant_ANIMATION_CALLBACK_MODE_PROCESS_IDLE). + + + + + +[AnimationProcessCallback](class_animationtree.md#enum_AnimationTree_AnimationProcessCallback) **ANIMATION_PROCESS_MANUAL** = `2` + +**Deprecated:** See [AnimationMixer.ANIMATION_CALLBACK_MODE_PROCESS_MANUAL](class_animationmixer.md#class_AnimationMixer_constant_ANIMATION_CALLBACK_MODE_PROCESS_MANUAL). + +
+ + + +## Property Descriptions + + + + + +[NodePath](class_nodepath.md) **advance_expression_base_node** = `NodePath(".")` [🔗](#class_AnimationTree_property_advance_expression_base_node) + + + +- `void` **set_advance_expression_base_node**\ (\ value\: [NodePath](class_nodepath.md)\ ) +- [NodePath](class_nodepath.md) **get_advance_expression_base_node**\ (\ ) + +The path to the [Node](class_node.md) used to evaluate the [AnimationNode](class_animationnode.md) [Expression](class_expression.md) if one is not explicitly specified internally. + +
+ + + + + +[NodePath](class_nodepath.md) **anim_player** = `NodePath("")` [🔗](#class_AnimationTree_property_anim_player) + + + +- `void` **set_animation_player**\ (\ value\: [NodePath](class_nodepath.md)\ ) +- [NodePath](class_nodepath.md) **get_animation_player**\ (\ ) + +The path to the [AnimationPlayer](class_animationplayer.md) used for animating. + +
+ + + + + +[AnimationRootNode](class_animationrootnode.md) **tree_root** [🔗](#class_AnimationTree_property_tree_root) + + + +- `void` **set_tree_root**\ (\ value\: [AnimationRootNode](class_animationrootnode.md)\ ) +- [AnimationRootNode](class_animationrootnode.md) **get_tree_root**\ (\ ) + +The root animation node of this **AnimationTree**. See [AnimationRootNode](class_animationrootnode.md). + +
+ + + +## Method Descriptions + + + + + +[AnimationProcessCallback](class_animationtree.md#enum_AnimationTree_AnimationProcessCallback) **get_process_callback**\ (\ ) const [🔗](#class_AnimationTree_method_get_process_callback) + +**Deprecated:** Use [AnimationMixer.callback_mode_process](class_animationmixer.md#class_AnimationMixer_property_callback_mode_process) instead. + +Returns the process notification in which to update animations. + +
+ + + + + +`void` **set_process_callback**\ (\ mode\: [AnimationProcessCallback](class_animationtree.md#enum_AnimationTree_AnimationProcessCallback)\ ) [🔗](#class_AnimationTree_method_set_process_callback) + +**Deprecated:** Use [AnimationMixer.callback_mode_process](class_animationmixer.md#class_AnimationMixer_property_callback_mode_process) instead. + +Sets the process notification in which to update animations. + diff --git a/docs/Classes/class_area2d.md b/docs/Classes/class_area2d.md new file mode 100644 index 00000000..33a0341e --- /dev/null +++ b/docs/Classes/class_area2d.md @@ -0,0 +1,637 @@ + + + + + + + + + + + +# Area2D + +**Inherits:** [CollisionObject2D](class_collisionobject2d.md) **<** [Node2D](class_node2d.md) **<** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +A region of 2D space that detects other [CollisionObject2D](class_collisionobject2d.md)\ s entering or exiting it. + + + +## Description + +**Area2D** is a region of 2D space defined by one or multiple [CollisionShape2D](class_collisionshape2d.md) or [CollisionPolygon2D](class_collisionpolygon2d.md) child nodes. It detects when other [CollisionObject2D](class_collisionobject2d.md)\ 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. + +\ **Note:** Areas and bodies created with [PhysicsServer2D](class_physicsserver2d.md) might not interact as expected with **Area2D**\ s, and might not emit signals or track objects correctly. + + + +## Tutorials + +- [Using Area2D](../tutorials/physics/using_area_2d.md) + +- [2D Dodge The Creeps Demo](https://godotengine.org/asset-library/asset/2712) + +- [2D Pong Demo](https://godotengine.org/asset-library/asset/2728) + +- [2D Platformer Demo](https://godotengine.org/asset-library/asset/2727) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[angular_damp](#class_Area2D_property_angular_damp)`1.0`
[SpaceOverride](class_area2d.md#enum_Area2D_SpaceOverride)[angular_damp_space_override](#class_Area2D_property_angular_damp_space_override)`0`
[StringName](class_stringname.md)[audio_bus_name](#class_Area2D_property_audio_bus_name)`&"Master"`
[bool](class_bool.md)[audio_bus_override](#class_Area2D_property_audio_bus_override)`false`
[float](class_float.md)[gravity](#class_Area2D_property_gravity)`980.0`
[Vector2](class_vector2.md)[gravity_direction](#class_Area2D_property_gravity_direction)`Vector2(0, 1)`
[bool](class_bool.md)[gravity_point](#class_Area2D_property_gravity_point)`false`
[Vector2](class_vector2.md)[gravity_point_center](#class_Area2D_property_gravity_point_center)`Vector2(0, 1)`
[float](class_float.md)[gravity_point_unit_distance](#class_Area2D_property_gravity_point_unit_distance)`0.0`
[SpaceOverride](class_area2d.md#enum_Area2D_SpaceOverride)[gravity_space_override](#class_Area2D_property_gravity_space_override)`0`
[float](class_float.md)[linear_damp](#class_Area2D_property_linear_damp)`0.1`
[SpaceOverride](class_area2d.md#enum_Area2D_SpaceOverride)[linear_damp_space_override](#class_Area2D_property_linear_damp_space_override)`0`
[bool](class_bool.md)[monitorable](#class_Area2D_property_monitorable)`true`
[bool](class_bool.md)[monitoring](#class_Area2D_property_monitoring)`true`
[int](class_int.md)[priority](#class_Area2D_property_priority)`0`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Array](class_array.md)\[[Area2D](class_area2d.md)\][get_overlapping_areas](#class_Area2D_method_get_overlapping_areas)\ (\ ) const
[Array](class_array.md)\[[Node2D](class_node2d.md)\][get_overlapping_bodies](#class_Area2D_method_get_overlapping_bodies)\ (\ ) const
[bool](class_bool.md)[has_overlapping_areas](#class_Area2D_method_has_overlapping_areas)\ (\ ) const
[bool](class_bool.md)[has_overlapping_bodies](#class_Area2D_method_has_overlapping_bodies)\ (\ ) const
[bool](class_bool.md)[overlaps_area](#class_Area2D_method_overlaps_area)\ (\ area\: [Node](class_node.md)\ ) const
[bool](class_bool.md)[overlaps_body](#class_Area2D_method_overlaps_body)\ (\ body\: [Node](class_node.md)\ ) const
+ +
+ + + +## Signals + + + + + +**area_entered**\ (\ area\: [Area2D](class_area2d.md)\ ) [🔗](#class_Area2D_signal_area_entered) + +Emitted when the received `area` enters this area. Requires [monitoring](class_area2d.md#class_Area2D_property_monitoring) to be set to ``true``. + +
+ + + + + +**area_exited**\ (\ area\: [Area2D](class_area2d.md)\ ) [🔗](#class_Area2D_signal_area_exited) + +Emitted when the received `area` exits this area. Requires [monitoring](class_area2d.md#class_Area2D_property_monitoring) to be set to ``true``. + +
+ + + + + +**area_shape_entered**\ (\ area_rid\: [RID](class_rid.md), area\: [Area2D](class_area2d.md), area_shape_index\: [int](class_int.md), local_shape_index\: [int](class_int.md)\ ) [🔗](#class_Area2D_signal_area_shape_entered) + +Emitted when a [Shape2D](class_shape2d.md) of the received `area` enters a shape of this area. Requires [monitoring](class_area2d.md#class_Area2D_property_monitoring) to be set to ``true``. + +\ `local_shape_index` and `area_shape_index` contain indices of the interacting shapes from this area and the other area, respectively. `area_rid` contains the [RID](class_rid.md) of the other area. These values can be used with the [PhysicsServer2D](class_physicsserver2d.md). + +\ **Example:** Get the [CollisionShape2D](class_collisionshape2d.md) node from the shape index: + + + + +```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) +``` + + + +
+ + + + + +**area_shape_exited**\ (\ area_rid\: [RID](class_rid.md), area\: [Area2D](class_area2d.md), area_shape_index\: [int](class_int.md), local_shape_index\: [int](class_int.md)\ ) [🔗](#class_Area2D_signal_area_shape_exited) + +Emitted when a [Shape2D](class_shape2d.md) of the received `area` exits a shape of this area. Requires [monitoring](class_area2d.md#class_Area2D_property_monitoring) to be set to ``true``. + +See also [area_shape_entered](class_area2d.md#class_Area2D_signal_area_shape_entered). + +
+ + + + + +**body_entered**\ (\ body\: [Node2D](class_node2d.md)\ ) [🔗](#class_Area2D_signal_body_entered) + +Emitted when the received `body` enters this area. `body` can be a [PhysicsBody2D](class_physicsbody2d.md) or a [TileMap](class_tilemap.md). [TileMap](class_tilemap.md)\ s are detected if their [TileSet](class_tileset.md) has collision shapes configured. Requires [monitoring](class_area2d.md#class_Area2D_property_monitoring) to be set to ``true``. + +
+ + + + + +**body_exited**\ (\ body\: [Node2D](class_node2d.md)\ ) [🔗](#class_Area2D_signal_body_exited) + +Emitted when the received `body` exits this area. `body` can be a [PhysicsBody2D](class_physicsbody2d.md) or a [TileMap](class_tilemap.md). [TileMap](class_tilemap.md)\ s are detected if their [TileSet](class_tileset.md) has collision shapes configured. Requires [monitoring](class_area2d.md#class_Area2D_property_monitoring) to be set to ``true``. + +
+ + + + + +**body_shape_entered**\ (\ body_rid\: [RID](class_rid.md), body\: [Node2D](class_node2d.md), body_shape_index\: [int](class_int.md), local_shape_index\: [int](class_int.md)\ ) [🔗](#class_Area2D_signal_body_shape_entered) + +Emitted when a [Shape2D](class_shape2d.md) of the received `body` enters a shape of this area. `body` can be a [PhysicsBody2D](class_physicsbody2d.md) or a [TileMap](class_tilemap.md). [TileMap](class_tilemap.md)\ s are detected if their [TileSet](class_tileset.md) has collision shapes configured. Requires [monitoring](class_area2d.md#class_Area2D_property_monitoring) to be set to ``true``. + +\ `local_shape_index` and `body_shape_index` contain indices of the interacting shapes from this area and the interacting body, respectively. `body_rid` contains the [RID](class_rid.md) of the body. These values can be used with the [PhysicsServer2D](class_physicsserver2d.md). + +\ **Example:** Get the [CollisionShape2D](class_collisionshape2d.md) node from the shape index: + + + + +```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) +``` + + + +
+ + + + + +**body_shape_exited**\ (\ body_rid\: [RID](class_rid.md), body\: [Node2D](class_node2d.md), body_shape_index\: [int](class_int.md), local_shape_index\: [int](class_int.md)\ ) [🔗](#class_Area2D_signal_body_shape_exited) + +Emitted when a [Shape2D](class_shape2d.md) of the received `body` exits a shape of this area. `body` can be a [PhysicsBody2D](class_physicsbody2d.md) or a [TileMap](class_tilemap.md). [TileMap](class_tilemap.md)\ s are detected if their [TileSet](class_tileset.md) has collision shapes configured. Requires [monitoring](class_area2d.md#class_Area2D_property_monitoring) to be set to ``true``. + +See also [body_shape_entered](class_area2d.md#class_Area2D_signal_body_shape_entered). + +
+ + + +## Enumerations + + + + + +enum **SpaceOverride**: [🔗](#enum_Area2D_SpaceOverride) + + + + + +[SpaceOverride](class_area2d.md#enum_Area2D_SpaceOverride) **SPACE_OVERRIDE_DISABLED** = `0` + +This area does not affect gravity/damping. + + + +[SpaceOverride](class_area2d.md#enum_Area2D_SpaceOverride) **SPACE_OVERRIDE_COMBINE** = `1` + +This area adds its gravity/damping values to whatever has been calculated so far (in [priority](class_area2d.md#class_Area2D_property_priority) order). + + + +[SpaceOverride](class_area2d.md#enum_Area2D_SpaceOverride) **SPACE_OVERRIDE_COMBINE_REPLACE** = `2` + +This area adds its gravity/damping values to whatever has been calculated so far (in [priority](class_area2d.md#class_Area2D_property_priority) order), ignoring any lower priority areas. + + + +[SpaceOverride](class_area2d.md#enum_Area2D_SpaceOverride) **SPACE_OVERRIDE_REPLACE** = `3` + +This area replaces any gravity/damping, even the defaults, ignoring any lower priority areas. + + + +[SpaceOverride](class_area2d.md#enum_Area2D_SpaceOverride) **SPACE_OVERRIDE_REPLACE_COMBINE** = `4` + +This area replaces any gravity/damping calculated so far (in [priority](class_area2d.md#class_Area2D_property_priority) order), but keeps calculating the rest of the areas.
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **angular_damp** = `1.0` [🔗](#class_Area2D_property_angular_damp) + + + +- `void` **set_angular_damp**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_angular_damp**\ (\ ) + +The rate at which objects stop spinning in this area. Represents the angular velocity lost per second. + +See [ProjectSettings.physics/2d/default_angular_damp](class_projectsettings.md#class_ProjectSettings_property_physics/2d/default_angular_damp) for more details about damping. + +
+ + + + + +[SpaceOverride](class_area2d.md#enum_Area2D_SpaceOverride) **angular_damp_space_override** = `0` [🔗](#class_Area2D_property_angular_damp_space_override) + + + +- `void` **set_angular_damp_space_override_mode**\ (\ value\: [SpaceOverride](class_area2d.md#enum_Area2D_SpaceOverride)\ ) +- [SpaceOverride](class_area2d.md#enum_Area2D_SpaceOverride) **get_angular_damp_space_override_mode**\ (\ ) + +Override mode for angular damping calculations within this area. + +
+ + + + + +[StringName](class_stringname.md) **audio_bus_name** = `&"Master"` [🔗](#class_Area2D_property_audio_bus_name) + + + +- `void` **set_audio_bus_name**\ (\ value\: [StringName](class_stringname.md)\ ) +- [StringName](class_stringname.md) **get_audio_bus_name**\ (\ ) + +The name of the area's audio bus. + +
+ + + + + +[bool](class_bool.md) **audio_bus_override** = `false` [🔗](#class_Area2D_property_audio_bus_override) + + + +- `void` **set_audio_bus_override**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_overriding_audio_bus**\ (\ ) + +If ``true``, the area's audio bus overrides the default audio bus. + +
+ + + + + +[float](class_float.md) **gravity** = `980.0` [🔗](#class_Area2D_property_gravity) + + + +- `void` **set_gravity**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_gravity**\ (\ ) + +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. + +
+ + + + + +[Vector2](class_vector2.md) **gravity_direction** = `Vector2(0, 1)` [🔗](#class_Area2D_property_gravity_direction) + + + +- `void` **set_gravity_direction**\ (\ value\: [Vector2](class_vector2.md)\ ) +- [Vector2](class_vector2.md) **get_gravity_direction**\ (\ ) + +The area's gravity vector (not normalized). + +
+ + + + + +[bool](class_bool.md) **gravity_point** = `false` [🔗](#class_Area2D_property_gravity_point) + + + +- `void` **set_gravity_is_point**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_gravity_a_point**\ (\ ) + +If ``true``, gravity is calculated from a point (set via [gravity_point_center](class_area2d.md#class_Area2D_property_gravity_point_center)). See also [gravity_space_override](class_area2d.md#class_Area2D_property_gravity_space_override). + +
+ + + + + +[Vector2](class_vector2.md) **gravity_point_center** = `Vector2(0, 1)` [🔗](#class_Area2D_property_gravity_point_center) + + + +- `void` **set_gravity_point_center**\ (\ value\: [Vector2](class_vector2.md)\ ) +- [Vector2](class_vector2.md) **get_gravity_point_center**\ (\ ) + +If gravity is a point (see [gravity_point](class_area2d.md#class_Area2D_property_gravity_point)), this will be the point of attraction. + +
+ + + + + +[float](class_float.md) **gravity_point_unit_distance** = `0.0` [🔗](#class_Area2D_property_gravity_point_unit_distance) + + + +- `void` **set_gravity_point_unit_distance**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_gravity_point_unit_distance**\ (\ ) + +The distance at which the gravity strength is equal to [gravity](class_area2d.md#class_Area2D_property_gravity). For example, on a planet 100 pixels in radius with a surface gravity of 4.0 px/s², set the [gravity](class_area2d.md#class_Area2D_property_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. + +
+ + + + + +[SpaceOverride](class_area2d.md#enum_Area2D_SpaceOverride) **gravity_space_override** = `0` [🔗](#class_Area2D_property_gravity_space_override) + + + +- `void` **set_gravity_space_override_mode**\ (\ value\: [SpaceOverride](class_area2d.md#enum_Area2D_SpaceOverride)\ ) +- [SpaceOverride](class_area2d.md#enum_Area2D_SpaceOverride) **get_gravity_space_override_mode**\ (\ ) + +Override mode for gravity calculations within this area. + +
+ + + + + +[float](class_float.md) **linear_damp** = `0.1` [🔗](#class_Area2D_property_linear_damp) + + + +- `void` **set_linear_damp**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_linear_damp**\ (\ ) + +The rate at which objects stop moving in this area. Represents the linear velocity lost per second. + +See [ProjectSettings.physics/2d/default_linear_damp](class_projectsettings.md#class_ProjectSettings_property_physics/2d/default_linear_damp) for more details about damping. + +
+ + + + + +[SpaceOverride](class_area2d.md#enum_Area2D_SpaceOverride) **linear_damp_space_override** = `0` [🔗](#class_Area2D_property_linear_damp_space_override) + + + +- `void` **set_linear_damp_space_override_mode**\ (\ value\: [SpaceOverride](class_area2d.md#enum_Area2D_SpaceOverride)\ ) +- [SpaceOverride](class_area2d.md#enum_Area2D_SpaceOverride) **get_linear_damp_space_override_mode**\ (\ ) + +Override mode for linear damping calculations within this area. + +
+ + + + + +[bool](class_bool.md) **monitorable** = `true` [🔗](#class_Area2D_property_monitorable) + + + +- `void` **set_monitorable**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_monitorable**\ (\ ) + +If ``true``, other monitoring areas can detect this area. + +
+ + + + + +[bool](class_bool.md) **monitoring** = `true` [🔗](#class_Area2D_property_monitoring) + + + +- `void` **set_monitoring**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_monitoring**\ (\ ) + +If ``true``, the area detects bodies or areas entering and exiting it. + +
+ + + + + +[int](class_int.md) **priority** = `0` [🔗](#class_Area2D_property_priority) + + + +- `void` **set_priority**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_priority**\ (\ ) + +The area's priority. Higher priority areas are processed first. The [World2D](class_world2d.md)'s physics is always processed last, after all areas. + +
+ + + +## Method Descriptions + + + + + +[Array](class_array.md)\[[Area2D](class_area2d.md)\] **get_overlapping_areas**\ (\ ) const [🔗](#class_Area2D_method_get_overlapping_areas) + +Returns a list of intersecting **Area2D**\ s. The overlapping area's [CollisionObject2D.collision_layer](class_collisionobject2d.md#class_CollisionObject2D_property_collision_layer) must be part of this area's [CollisionObject2D.collision_mask](class_collisionobject2d.md#class_CollisionObject2D_property_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. + +
+ + + + + +[Array](class_array.md)\[[Node2D](class_node2d.md)\] **get_overlapping_bodies**\ (\ ) const [🔗](#class_Area2D_method_get_overlapping_bodies) + +Returns a list of intersecting [PhysicsBody2D](class_physicsbody2d.md)\ s and [TileMap](class_tilemap.md)\ s. The overlapping body's [CollisionObject2D.collision_layer](class_collisionobject2d.md#class_CollisionObject2D_property_collision_layer) must be part of this area's [CollisionObject2D.collision_mask](class_collisionobject2d.md#class_CollisionObject2D_property_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. + +
+ + + + + +[bool](class_bool.md) **has_overlapping_areas**\ (\ ) const [🔗](#class_Area2D_method_has_overlapping_areas) + +Returns ``true`` if intersecting any **Area2D**\ s, otherwise returns ``false``. The overlapping area's [CollisionObject2D.collision_layer](class_collisionobject2d.md#class_CollisionObject2D_property_collision_layer) must be part of this area's [CollisionObject2D.collision_mask](class_collisionobject2d.md#class_CollisionObject2D_property_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. + +
+ + + + + +[bool](class_bool.md) **has_overlapping_bodies**\ (\ ) const [🔗](#class_Area2D_method_has_overlapping_bodies) + +Returns ``true`` if intersecting any [PhysicsBody2D](class_physicsbody2d.md)\ s or [TileMap](class_tilemap.md)\ s, otherwise returns ``false``. The overlapping body's [CollisionObject2D.collision_layer](class_collisionobject2d.md#class_CollisionObject2D_property_collision_layer) must be part of this area's [CollisionObject2D.collision_mask](class_collisionobject2d.md#class_CollisionObject2D_property_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. + +
+ + + + + +[bool](class_bool.md) **overlaps_area**\ (\ area\: [Node](class_node.md)\ ) const [🔗](#class_Area2D_method_overlaps_area) + +Returns ``true`` if the given **Area2D** intersects or overlaps this **Area2D**, ``false`` otherwise. + +\ **Note:** 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. + +
+ + + + + +[bool](class_bool.md) **overlaps_body**\ (\ body\: [Node](class_node.md)\ ) const [🔗](#class_Area2D_method_overlaps_body) + +Returns ``true`` if the given physics body intersects or overlaps this **Area2D**, ``false`` otherwise. + +\ **Note:** 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 `body` argument can either be a [PhysicsBody2D](class_physicsbody2d.md) or a [TileMap](class_tilemap.md) instance. While TileMaps are not physics bodies themselves, they register their tiles with collision shapes as a virtual physics body. + diff --git a/docs/Classes/class_area3d.md b/docs/Classes/class_area3d.md new file mode 100644 index 00000000..d3a7e9df --- /dev/null +++ b/docs/Classes/class_area3d.md @@ -0,0 +1,783 @@ + + + + + + + + + + + +# Area3D + +**Inherits:** [CollisionObject3D](class_collisionobject3d.md) **<** [Node3D](class_node3d.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +A region of 3D space that detects other [CollisionObject3D](class_collisionobject3d.md)\ s entering or exiting it. + + + +## Description + +**Area3D** is a region of 3D space defined by one or multiple [CollisionShape3D](class_collisionshape3d.md) or [CollisionPolygon3D](class_collisionpolygon3d.md) child nodes. It detects when other [CollisionObject3D](class_collisionobject3d.md)\ 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. + +\ **Note:** Areas and bodies created with [PhysicsServer3D](class_physicsserver3d.md) might not interact as expected with **Area3D**\ s, and might not emit signals or track objects correctly. + +\ **Warning:** Using a [ConcavePolygonShape3D](class_concavepolygonshape3d.md) inside a [CollisionShape3D](class_collisionshape3d.md) child of this node (created e.g. by using the **Create Trimesh Collision Sibling** option in the **Mesh** menu that appears when selecting a [MeshInstance3D](class_meshinstance3d.md) node) may give unexpected results, since this collision shape is hollow. If this is not desired, it has to be split into multiple [ConvexPolygonShape3D](class_convexpolygonshape3d.md)\ s or primitive shapes like [BoxShape3D](class_boxshape3d.md), or in some cases it may be replaceable by a [CollisionPolygon3D](class_collisionpolygon3d.md). + + + +## Tutorials + +- [Using Area2D](../tutorials/physics/using_area_2d.md) + +- [3D Platformer Demo](https://godotengine.org/asset-library/asset/2748) + +- [GUI in 3D Viewport Demo](https://godotengine.org/asset-library/asset/2807) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[angular_damp](#class_Area3D_property_angular_damp)`0.1`
[SpaceOverride](class_area3d.md#enum_Area3D_SpaceOverride)[angular_damp_space_override](#class_Area3D_property_angular_damp_space_override)`0`
[StringName](class_stringname.md)[audio_bus_name](#class_Area3D_property_audio_bus_name)`&"Master"`
[bool](class_bool.md)[audio_bus_override](#class_Area3D_property_audio_bus_override)`false`
[float](class_float.md)[gravity](#class_Area3D_property_gravity)`9.8`
[Vector3](class_vector3.md)[gravity_direction](#class_Area3D_property_gravity_direction)`Vector3(0, -1, 0)`
[bool](class_bool.md)[gravity_point](#class_Area3D_property_gravity_point)`false`
[Vector3](class_vector3.md)[gravity_point_center](#class_Area3D_property_gravity_point_center)`Vector3(0, -1, 0)`
[float](class_float.md)[gravity_point_unit_distance](#class_Area3D_property_gravity_point_unit_distance)`0.0`
[SpaceOverride](class_area3d.md#enum_Area3D_SpaceOverride)[gravity_space_override](#class_Area3D_property_gravity_space_override)`0`
[float](class_float.md)[linear_damp](#class_Area3D_property_linear_damp)`0.1`
[SpaceOverride](class_area3d.md#enum_Area3D_SpaceOverride)[linear_damp_space_override](#class_Area3D_property_linear_damp_space_override)`0`
[bool](class_bool.md)[monitorable](#class_Area3D_property_monitorable)`true`
[bool](class_bool.md)[monitoring](#class_Area3D_property_monitoring)`true`
[int](class_int.md)[priority](#class_Area3D_property_priority)`0`
[float](class_float.md)[reverb_bus_amount](#class_Area3D_property_reverb_bus_amount)`0.0`
[bool](class_bool.md)[reverb_bus_enabled](#class_Area3D_property_reverb_bus_enabled)`false`
[StringName](class_stringname.md)[reverb_bus_name](#class_Area3D_property_reverb_bus_name)`&"Master"`
[float](class_float.md)[reverb_bus_uniformity](#class_Area3D_property_reverb_bus_uniformity)`0.0`
[float](class_float.md)[wind_attenuation_factor](#class_Area3D_property_wind_attenuation_factor)`0.0`
[float](class_float.md)[wind_force_magnitude](#class_Area3D_property_wind_force_magnitude)`0.0`
[NodePath](class_nodepath.md)[wind_source_path](#class_Area3D_property_wind_source_path)`NodePath("")`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Array](class_array.md)\[[Area3D](class_area3d.md)\][get_overlapping_areas](#class_Area3D_method_get_overlapping_areas)\ (\ ) const
[Array](class_array.md)\[[Node3D](class_node3d.md)\][get_overlapping_bodies](#class_Area3D_method_get_overlapping_bodies)\ (\ ) const
[bool](class_bool.md)[has_overlapping_areas](#class_Area3D_method_has_overlapping_areas)\ (\ ) const
[bool](class_bool.md)[has_overlapping_bodies](#class_Area3D_method_has_overlapping_bodies)\ (\ ) const
[bool](class_bool.md)[overlaps_area](#class_Area3D_method_overlaps_area)\ (\ area\: [Node](class_node.md)\ ) const
[bool](class_bool.md)[overlaps_body](#class_Area3D_method_overlaps_body)\ (\ body\: [Node](class_node.md)\ ) const
+ +
+ + + +## Signals + + + + + +**area_entered**\ (\ area\: [Area3D](class_area3d.md)\ ) [🔗](#class_Area3D_signal_area_entered) + +Emitted when the received `area` enters this area. Requires [monitoring](class_area3d.md#class_Area3D_property_monitoring) to be set to ``true``. + +
+ + + + + +**area_exited**\ (\ area\: [Area3D](class_area3d.md)\ ) [🔗](#class_Area3D_signal_area_exited) + +Emitted when the received `area` exits this area. Requires [monitoring](class_area3d.md#class_Area3D_property_monitoring) to be set to ``true``. + +
+ + + + + +**area_shape_entered**\ (\ area_rid\: [RID](class_rid.md), area\: [Area3D](class_area3d.md), area_shape_index\: [int](class_int.md), local_shape_index\: [int](class_int.md)\ ) [🔗](#class_Area3D_signal_area_shape_entered) + +Emitted when a [Shape3D](class_shape3d.md) of the received `area` enters a shape of this area. Requires [monitoring](class_area3d.md#class_Area3D_property_monitoring) to be set to ``true``. + +\ `local_shape_index` and `area_shape_index` contain indices of the interacting shapes from this area and the other area, respectively. `area_rid` contains the [RID](class_rid.md) of the other area. These values can be used with the [PhysicsServer3D](class_physicsserver3d.md). + +\ **Example:** Get the [CollisionShape3D](class_collisionshape3d.md) node from the shape index: + + + + +```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) +``` + + + +
+ + + + + +**area_shape_exited**\ (\ area_rid\: [RID](class_rid.md), area\: [Area3D](class_area3d.md), area_shape_index\: [int](class_int.md), local_shape_index\: [int](class_int.md)\ ) [🔗](#class_Area3D_signal_area_shape_exited) + +Emitted when a [Shape3D](class_shape3d.md) of the received `area` exits a shape of this area. Requires [monitoring](class_area3d.md#class_Area3D_property_monitoring) to be set to ``true``. + +See also [area_shape_entered](class_area3d.md#class_Area3D_signal_area_shape_entered). + +
+ + + + + +**body_entered**\ (\ body\: [Node3D](class_node3d.md)\ ) [🔗](#class_Area3D_signal_body_entered) + +Emitted when the received `body` enters this area. `body` can be a [PhysicsBody3D](class_physicsbody3d.md) or a [GridMap](class_gridmap.md). [GridMap](class_gridmap.md)\ s are detected if their [MeshLibrary](class_meshlibrary.md) has collision shapes configured. Requires [monitoring](class_area3d.md#class_Area3D_property_monitoring) to be set to ``true``. + +
+ + + + + +**body_exited**\ (\ body\: [Node3D](class_node3d.md)\ ) [🔗](#class_Area3D_signal_body_exited) + +Emitted when the received `body` exits this area. `body` can be a [PhysicsBody3D](class_physicsbody3d.md) or a [GridMap](class_gridmap.md). [GridMap](class_gridmap.md)\ s are detected if their [MeshLibrary](class_meshlibrary.md) has collision shapes configured. Requires [monitoring](class_area3d.md#class_Area3D_property_monitoring) to be set to ``true``. + +
+ + + + + +**body_shape_entered**\ (\ body_rid\: [RID](class_rid.md), body\: [Node3D](class_node3d.md), body_shape_index\: [int](class_int.md), local_shape_index\: [int](class_int.md)\ ) [🔗](#class_Area3D_signal_body_shape_entered) + +Emitted when a [Shape3D](class_shape3d.md) of the received `body` enters a shape of this area. `body` can be a [PhysicsBody3D](class_physicsbody3d.md) or a [GridMap](class_gridmap.md). [GridMap](class_gridmap.md)\ s are detected if their [MeshLibrary](class_meshlibrary.md) has collision shapes configured. Requires [monitoring](class_area3d.md#class_Area3D_property_monitoring) to be set to ``true``. + +\ `local_shape_index` and `body_shape_index` contain indices of the interacting shapes from this area and the interacting body, respectively. `body_rid` contains the [RID](class_rid.md) of the body. These values can be used with the [PhysicsServer3D](class_physicsserver3d.md). + +\ **Example:** Get the [CollisionShape3D](class_collisionshape3d.md) node from the shape index: + + + + +```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) +``` + + + +
+ + + + + +**body_shape_exited**\ (\ body_rid\: [RID](class_rid.md), body\: [Node3D](class_node3d.md), body_shape_index\: [int](class_int.md), local_shape_index\: [int](class_int.md)\ ) [🔗](#class_Area3D_signal_body_shape_exited) + +Emitted when a [Shape3D](class_shape3d.md) of the received `body` exits a shape of this area. `body` can be a [PhysicsBody3D](class_physicsbody3d.md) or a [GridMap](class_gridmap.md). [GridMap](class_gridmap.md)\ s are detected if their [MeshLibrary](class_meshlibrary.md) has collision shapes configured. Requires [monitoring](class_area3d.md#class_Area3D_property_monitoring) to be set to ``true``. + +See also [body_shape_entered](class_area3d.md#class_Area3D_signal_body_shape_entered). + +
+ + + +## Enumerations + + + + + +enum **SpaceOverride**: [🔗](#enum_Area3D_SpaceOverride) + + + + + +[SpaceOverride](class_area3d.md#enum_Area3D_SpaceOverride) **SPACE_OVERRIDE_DISABLED** = `0` + +This area does not affect gravity/damping. + + + +[SpaceOverride](class_area3d.md#enum_Area3D_SpaceOverride) **SPACE_OVERRIDE_COMBINE** = `1` + +This area adds its gravity/damping values to whatever has been calculated so far (in [priority](class_area3d.md#class_Area3D_property_priority) order). + + + +[SpaceOverride](class_area3d.md#enum_Area3D_SpaceOverride) **SPACE_OVERRIDE_COMBINE_REPLACE** = `2` + +This area adds its gravity/damping values to whatever has been calculated so far (in [priority](class_area3d.md#class_Area3D_property_priority) order), ignoring any lower priority areas. + + + +[SpaceOverride](class_area3d.md#enum_Area3D_SpaceOverride) **SPACE_OVERRIDE_REPLACE** = `3` + +This area replaces any gravity/damping, even the defaults, ignoring any lower priority areas. + + + +[SpaceOverride](class_area3d.md#enum_Area3D_SpaceOverride) **SPACE_OVERRIDE_REPLACE_COMBINE** = `4` + +This area replaces any gravity/damping calculated so far (in [priority](class_area3d.md#class_Area3D_property_priority) order), but keeps calculating the rest of the areas.
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **angular_damp** = `0.1` [🔗](#class_Area3D_property_angular_damp) + + + +- `void` **set_angular_damp**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_angular_damp**\ (\ ) + +The rate at which objects stop spinning in this area. Represents the angular velocity lost per second. + +See [ProjectSettings.physics/3d/default_angular_damp](class_projectsettings.md#class_ProjectSettings_property_physics/3d/default_angular_damp) for more details about damping. + +
+ + + + + +[SpaceOverride](class_area3d.md#enum_Area3D_SpaceOverride) **angular_damp_space_override** = `0` [🔗](#class_Area3D_property_angular_damp_space_override) + + + +- `void` **set_angular_damp_space_override_mode**\ (\ value\: [SpaceOverride](class_area3d.md#enum_Area3D_SpaceOverride)\ ) +- [SpaceOverride](class_area3d.md#enum_Area3D_SpaceOverride) **get_angular_damp_space_override_mode**\ (\ ) + +Override mode for angular damping calculations within this area. + +
+ + + + + +[StringName](class_stringname.md) **audio_bus_name** = `&"Master"` [🔗](#class_Area3D_property_audio_bus_name) + + + +- `void` **set_audio_bus_name**\ (\ value\: [StringName](class_stringname.md)\ ) +- [StringName](class_stringname.md) **get_audio_bus_name**\ (\ ) + +The name of the area's audio bus. + +
+ + + + + +[bool](class_bool.md) **audio_bus_override** = `false` [🔗](#class_Area3D_property_audio_bus_override) + + + +- `void` **set_audio_bus_override**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_overriding_audio_bus**\ (\ ) + +If ``true``, the area's audio bus overrides the default audio bus. + +
+ + + + + +[float](class_float.md) **gravity** = `9.8` [🔗](#class_Area3D_property_gravity) + + + +- `void` **set_gravity**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_gravity**\ (\ ) + +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. + +
+ + + + + +[Vector3](class_vector3.md) **gravity_direction** = `Vector3(0, -1, 0)` [🔗](#class_Area3D_property_gravity_direction) + + + +- `void` **set_gravity_direction**\ (\ value\: [Vector3](class_vector3.md)\ ) +- [Vector3](class_vector3.md) **get_gravity_direction**\ (\ ) + +The area's gravity vector (not normalized). + +
+ + + + + +[bool](class_bool.md) **gravity_point** = `false` [🔗](#class_Area3D_property_gravity_point) + + + +- `void` **set_gravity_is_point**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_gravity_a_point**\ (\ ) + +If ``true``, gravity is calculated from a point (set via [gravity_point_center](class_area3d.md#class_Area3D_property_gravity_point_center)). See also [gravity_space_override](class_area3d.md#class_Area3D_property_gravity_space_override). + +
+ + + + + +[Vector3](class_vector3.md) **gravity_point_center** = `Vector3(0, -1, 0)` [🔗](#class_Area3D_property_gravity_point_center) + + + +- `void` **set_gravity_point_center**\ (\ value\: [Vector3](class_vector3.md)\ ) +- [Vector3](class_vector3.md) **get_gravity_point_center**\ (\ ) + +If gravity is a point (see [gravity_point](class_area3d.md#class_Area3D_property_gravity_point)), this will be the point of attraction. + +
+ + + + + +[float](class_float.md) **gravity_point_unit_distance** = `0.0` [🔗](#class_Area3D_property_gravity_point_unit_distance) + + + +- `void` **set_gravity_point_unit_distance**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_gravity_point_unit_distance**\ (\ ) + +The distance at which the gravity strength is equal to [gravity](class_area3d.md#class_Area3D_property_gravity). For example, on a planet 100 meters in radius with a surface gravity of 4.0 m/s², set the [gravity](class_area3d.md#class_Area3D_property_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. + +
+ + + + + +[SpaceOverride](class_area3d.md#enum_Area3D_SpaceOverride) **gravity_space_override** = `0` [🔗](#class_Area3D_property_gravity_space_override) + + + +- `void` **set_gravity_space_override_mode**\ (\ value\: [SpaceOverride](class_area3d.md#enum_Area3D_SpaceOverride)\ ) +- [SpaceOverride](class_area3d.md#enum_Area3D_SpaceOverride) **get_gravity_space_override_mode**\ (\ ) + +Override mode for gravity calculations within this area. + +
+ + + + + +[float](class_float.md) **linear_damp** = `0.1` [🔗](#class_Area3D_property_linear_damp) + + + +- `void` **set_linear_damp**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_linear_damp**\ (\ ) + +The rate at which objects stop moving in this area. Represents the linear velocity lost per second. + +See [ProjectSettings.physics/3d/default_linear_damp](class_projectsettings.md#class_ProjectSettings_property_physics/3d/default_linear_damp) for more details about damping. + +
+ + + + + +[SpaceOverride](class_area3d.md#enum_Area3D_SpaceOverride) **linear_damp_space_override** = `0` [🔗](#class_Area3D_property_linear_damp_space_override) + + + +- `void` **set_linear_damp_space_override_mode**\ (\ value\: [SpaceOverride](class_area3d.md#enum_Area3D_SpaceOverride)\ ) +- [SpaceOverride](class_area3d.md#enum_Area3D_SpaceOverride) **get_linear_damp_space_override_mode**\ (\ ) + +Override mode for linear damping calculations within this area. + +
+ + + + + +[bool](class_bool.md) **monitorable** = `true` [🔗](#class_Area3D_property_monitorable) + + + +- `void` **set_monitorable**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_monitorable**\ (\ ) + +If ``true``, other monitoring areas can detect this area. + +
+ + + + + +[bool](class_bool.md) **monitoring** = `true` [🔗](#class_Area3D_property_monitoring) + + + +- `void` **set_monitoring**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_monitoring**\ (\ ) + +If ``true``, the area detects bodies or areas entering and exiting it. + +
+ + + + + +[int](class_int.md) **priority** = `0` [🔗](#class_Area3D_property_priority) + + + +- `void` **set_priority**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_priority**\ (\ ) + +The area's priority. Higher priority areas are processed first. The [World3D](class_world3d.md)'s physics is always processed last, after all areas. + +
+ + + + + +[float](class_float.md) **reverb_bus_amount** = `0.0` [🔗](#class_Area3D_property_reverb_bus_amount) + + + +- `void` **set_reverb_amount**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_reverb_amount**\ (\ ) + +The degree to which this area applies reverb to its associated audio. Ranges from ``0`` to ``1`` with ``0.1`` precision. + +
+ + + + + +[bool](class_bool.md) **reverb_bus_enabled** = `false` [🔗](#class_Area3D_property_reverb_bus_enabled) + + + +- `void` **set_use_reverb_bus**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_using_reverb_bus**\ (\ ) + +If ``true``, the area applies reverb to its associated audio. + +
+ + + + + +[StringName](class_stringname.md) **reverb_bus_name** = `&"Master"` [🔗](#class_Area3D_property_reverb_bus_name) + + + +- `void` **set_reverb_bus_name**\ (\ value\: [StringName](class_stringname.md)\ ) +- [StringName](class_stringname.md) **get_reverb_bus_name**\ (\ ) + +The name of the reverb bus to use for this area's associated audio. + +
+ + + + + +[float](class_float.md) **reverb_bus_uniformity** = `0.0` [🔗](#class_Area3D_property_reverb_bus_uniformity) + + + +- `void` **set_reverb_uniformity**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_reverb_uniformity**\ (\ ) + +The degree to which this area's reverb is a uniform effect. Ranges from ``0`` to ``1`` with ``0.1`` precision. + +
+ + + + + +[float](class_float.md) **wind_attenuation_factor** = `0.0` [🔗](#class_Area3D_property_wind_attenuation_factor) + + + +- `void` **set_wind_attenuation_factor**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_wind_attenuation_factor**\ (\ ) + +The exponential rate at which wind force decreases with distance from its origin. + +\ **Note:** This wind force only applies to [SoftBody3D](class_softbody3d.md) nodes. Other physics bodies are currently not affected by wind. + +
+ + + + + +[float](class_float.md) **wind_force_magnitude** = `0.0` [🔗](#class_Area3D_property_wind_force_magnitude) + + + +- `void` **set_wind_force_magnitude**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_wind_force_magnitude**\ (\ ) + +The magnitude of area-specific wind force. + +\ **Note:** This wind force only applies to [SoftBody3D](class_softbody3d.md) nodes. Other physics bodies are currently not affected by wind. + +
+ + + + + +[NodePath](class_nodepath.md) **wind_source_path** = `NodePath("")` [🔗](#class_Area3D_property_wind_source_path) + + + +- `void` **set_wind_source_path**\ (\ value\: [NodePath](class_nodepath.md)\ ) +- [NodePath](class_nodepath.md) **get_wind_source_path**\ (\ ) + +The [Node3D](class_node3d.md) 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](class_node3d.md)'s local transform, and its origin is the origin of the [Node3D](class_node3d.md)'s local transform. + +\ **Note:** This wind force only applies to [SoftBody3D](class_softbody3d.md) nodes. Other physics bodies are currently not affected by wind. + +
+ + + +## Method Descriptions + + + + + +[Array](class_array.md)\[[Area3D](class_area3d.md)\] **get_overlapping_areas**\ (\ ) const [🔗](#class_Area3D_method_get_overlapping_areas) + +Returns a list of intersecting **Area3D**\ s. The overlapping area's [CollisionObject3D.collision_layer](class_collisionobject3d.md#class_CollisionObject3D_property_collision_layer) must be part of this area's [CollisionObject3D.collision_mask](class_collisionobject3d.md#class_CollisionObject3D_property_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. + +
+ + + + + +[Array](class_array.md)\[[Node3D](class_node3d.md)\] **get_overlapping_bodies**\ (\ ) const [🔗](#class_Area3D_method_get_overlapping_bodies) + +Returns a list of intersecting [PhysicsBody3D](class_physicsbody3d.md)\ s and [GridMap](class_gridmap.md)\ s. The overlapping body's [CollisionObject3D.collision_layer](class_collisionobject3d.md#class_CollisionObject3D_property_collision_layer) must be part of this area's [CollisionObject3D.collision_mask](class_collisionobject3d.md#class_CollisionObject3D_property_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. + +
+ + + + + +[bool](class_bool.md) **has_overlapping_areas**\ (\ ) const [🔗](#class_Area3D_method_has_overlapping_areas) + +Returns ``true`` if intersecting any **Area3D**\ s, otherwise returns ``false``. The overlapping area's [CollisionObject3D.collision_layer](class_collisionobject3d.md#class_CollisionObject3D_property_collision_layer) must be part of this area's [CollisionObject3D.collision_mask](class_collisionobject3d.md#class_CollisionObject3D_property_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. + +
+ + + + + +[bool](class_bool.md) **has_overlapping_bodies**\ (\ ) const [🔗](#class_Area3D_method_has_overlapping_bodies) + +Returns ``true`` if intersecting any [PhysicsBody3D](class_physicsbody3d.md)\ s or [GridMap](class_gridmap.md)\ s, otherwise returns ``false``. The overlapping body's [CollisionObject3D.collision_layer](class_collisionobject3d.md#class_CollisionObject3D_property_collision_layer) must be part of this area's [CollisionObject3D.collision_mask](class_collisionobject3d.md#class_CollisionObject3D_property_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. + +
+ + + + + +[bool](class_bool.md) **overlaps_area**\ (\ area\: [Node](class_node.md)\ ) const [🔗](#class_Area3D_method_overlaps_area) + +Returns ``true`` if the given **Area3D** intersects or overlaps this **Area3D**, ``false`` otherwise. + +\ **Note:** 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. + +
+ + + + + +[bool](class_bool.md) **overlaps_body**\ (\ body\: [Node](class_node.md)\ ) const [🔗](#class_Area3D_method_overlaps_body) + +Returns ``true`` if the given physics body intersects or overlaps this **Area3D**, ``false`` otherwise. + +\ **Note:** 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 `body` argument can either be a [PhysicsBody3D](class_physicsbody3d.md) or a [GridMap](class_gridmap.md) instance. While GridMaps are not physics body themselves, they register their tiles with collision shapes as a virtual physics body. + diff --git a/docs/Classes/class_array.md b/docs/Classes/class_array.md new file mode 100644 index 00000000..6f908d26 --- /dev/null +++ b/docs/Classes/class_array.md @@ -0,0 +1,1561 @@ + + + + + + + + + +# Array + +A built-in data structure that holds a sequence of elements. + + + +## Description + +An array data structure that can contain a sequence of elements of any [Variant](class_variant.md) type by default. Values can optionally be constrained to a specific type by creating a *typed array*. Elements are accessed by a numerical index starting at ``0``. Negative indices are used to count from the back (``-1`` is the last element, ``-2`` is the second to last, etc.). + + + + +```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" + + # This typed array can only contain integers. + # Attempting to add any other type will result in an error. + var typed_array: Array[int] = [1, 2, 3] +``` + +```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" + + // This typed array can only contain integers. + // Attempting to add any other type will result in an error. + Godot.Collections.Array typedArray = [1, 2, 3]; +``` + + + +\ **Note:** Arrays are always passed by **reference**. To get a copy of an array that can be modified independently of the original array, use [duplicate()](class_array.md#class_Array_method_duplicate). + +\ **Note:** Erasing elements while iterating over arrays is **not** supported and will result in unpredictable behavior. + +\ **Differences between packed arrays, typed arrays, and untyped arrays:** Packed arrays are generally faster to iterate on and modify compared to a typed array of the same type (e.g. [PackedInt64Array](class_packedint64array.md) versus ``Array[int]``). 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 [map()](class_array.md#class_Array_method_map). Typed arrays are in turn faster to iterate on and modify than untyped arrays. + +
+There are notable differences when using this API with C#. See the C# differences documentation for more information. + +
+ + + +## Constructors + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Array](class_array.md)[Array](#class_Array_constructor_Array)\ (\ )
[Array](class_array.md)[Array](#class_Array_constructor_Array)\ (\ base\: [Array](class_array.md), type\: [int](class_int.md), class_name\: [StringName](class_stringname.md), script\: [Variant](class_variant.md)\ )
[Array](class_array.md)[Array](#class_Array_constructor_Array)\ (\ from\: [Array](class_array.md)\ )
[Array](class_array.md)[Array](#class_Array_constructor_Array)\ (\ from\: [PackedByteArray](class_packedbytearray.md)\ )
[Array](class_array.md)[Array](#class_Array_constructor_Array)\ (\ from\: [PackedColorArray](class_packedcolorarray.md)\ )
[Array](class_array.md)[Array](#class_Array_constructor_Array)\ (\ from\: [PackedFloat32Array](class_packedfloat32array.md)\ )
[Array](class_array.md)[Array](#class_Array_constructor_Array)\ (\ from\: [PackedFloat64Array](class_packedfloat64array.md)\ )
[Array](class_array.md)[Array](#class_Array_constructor_Array)\ (\ from\: [PackedInt32Array](class_packedint32array.md)\ )
[Array](class_array.md)[Array](#class_Array_constructor_Array)\ (\ from\: [PackedInt64Array](class_packedint64array.md)\ )
[Array](class_array.md)[Array](#class_Array_constructor_Array)\ (\ from\: [PackedStringArray](class_packedstringarray.md)\ )
[Array](class_array.md)[Array](#class_Array_constructor_Array)\ (\ from\: [PackedVector2Array](class_packedvector2array.md)\ )
[Array](class_array.md)[Array](#class_Array_constructor_Array)\ (\ from\: [PackedVector3Array](class_packedvector3array.md)\ )
[Array](class_array.md)[Array](#class_Array_constructor_Array)\ (\ from\: [PackedVector4Array](class_packedvector4array.md)\ )
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[all](#class_Array_method_all)\ (\ method\: [Callable](class_callable.md)\ ) const
[bool](class_bool.md)[any](#class_Array_method_any)\ (\ method\: [Callable](class_callable.md)\ ) const
`void`[append](#class_Array_method_append)\ (\ value\: [Variant](class_variant.md)\ )
`void`[append_array](#class_Array_method_append_array)\ (\ array\: [Array](class_array.md)\ )
`void`[assign](#class_Array_method_assign)\ (\ array\: [Array](class_array.md)\ )
[Variant](class_variant.md)[back](#class_Array_method_back)\ (\ ) const
[int](class_int.md)[bsearch](#class_Array_method_bsearch)\ (\ value\: [Variant](class_variant.md), before\: [bool](class_bool.md) = true\ ) const
[int](class_int.md)[bsearch_custom](#class_Array_method_bsearch_custom)\ (\ value\: [Variant](class_variant.md), func\: [Callable](class_callable.md), before\: [bool](class_bool.md) = true\ ) const
`void`[clear](#class_Array_method_clear)\ (\ )
[int](class_int.md)[count](#class_Array_method_count)\ (\ value\: [Variant](class_variant.md)\ ) const
[Array](class_array.md)[duplicate](#class_Array_method_duplicate)\ (\ deep\: [bool](class_bool.md) = false\ ) const
[Array](class_array.md)[duplicate_deep](#class_Array_method_duplicate_deep)\ (\ deep_subresources_mode\: [int](class_int.md) = 1\ ) const
`void`[erase](#class_Array_method_erase)\ (\ value\: [Variant](class_variant.md)\ )
`void`[fill](#class_Array_method_fill)\ (\ value\: [Variant](class_variant.md)\ )
[Array](class_array.md)[filter](#class_Array_method_filter)\ (\ method\: [Callable](class_callable.md)\ ) const
[int](class_int.md)[find](#class_Array_method_find)\ (\ what\: [Variant](class_variant.md), from\: [int](class_int.md) = 0\ ) const
[int](class_int.md)[find_custom](#class_Array_method_find_custom)\ (\ method\: [Callable](class_callable.md), from\: [int](class_int.md) = 0\ ) const
[Variant](class_variant.md)[front](#class_Array_method_front)\ (\ ) const
[Variant](class_variant.md)[get](#class_Array_method_get)\ (\ index\: [int](class_int.md)\ ) const
[int](class_int.md)[get_typed_builtin](#class_Array_method_get_typed_builtin)\ (\ ) const
[StringName](class_stringname.md)[get_typed_class_name](#class_Array_method_get_typed_class_name)\ (\ ) const
[Variant](class_variant.md)[get_typed_script](#class_Array_method_get_typed_script)\ (\ ) const
[bool](class_bool.md)[has](#class_Array_method_has)\ (\ value\: [Variant](class_variant.md)\ ) const
[int](class_int.md)[hash](#class_Array_method_hash)\ (\ ) const
[int](class_int.md)[insert](#class_Array_method_insert)\ (\ position\: [int](class_int.md), value\: [Variant](class_variant.md)\ )
[bool](class_bool.md)[is_empty](#class_Array_method_is_empty)\ (\ ) const
[bool](class_bool.md)[is_read_only](#class_Array_method_is_read_only)\ (\ ) const
[bool](class_bool.md)[is_same_typed](#class_Array_method_is_same_typed)\ (\ array\: [Array](class_array.md)\ ) const
[bool](class_bool.md)[is_typed](#class_Array_method_is_typed)\ (\ ) const
`void`[make_read_only](#class_Array_method_make_read_only)\ (\ )
[Array](class_array.md)[map](#class_Array_method_map)\ (\ method\: [Callable](class_callable.md)\ ) const
[Variant](class_variant.md)[max](#class_Array_method_max)\ (\ ) const
[Variant](class_variant.md)[min](#class_Array_method_min)\ (\ ) const
[Variant](class_variant.md)[pick_random](#class_Array_method_pick_random)\ (\ ) const
[Variant](class_variant.md)[pop_at](#class_Array_method_pop_at)\ (\ position\: [int](class_int.md)\ )
[Variant](class_variant.md)[pop_back](#class_Array_method_pop_back)\ (\ )
[Variant](class_variant.md)[pop_front](#class_Array_method_pop_front)\ (\ )
`void`[push_back](#class_Array_method_push_back)\ (\ value\: [Variant](class_variant.md)\ )
`void`[push_front](#class_Array_method_push_front)\ (\ value\: [Variant](class_variant.md)\ )
[Variant](class_variant.md)[reduce](#class_Array_method_reduce)\ (\ method\: [Callable](class_callable.md), accum\: [Variant](class_variant.md) = null\ ) const
`void`[remove_at](#class_Array_method_remove_at)\ (\ position\: [int](class_int.md)\ )
[int](class_int.md)[resize](#class_Array_method_resize)\ (\ size\: [int](class_int.md)\ )
`void`[reverse](#class_Array_method_reverse)\ (\ )
[int](class_int.md)[rfind](#class_Array_method_rfind)\ (\ what\: [Variant](class_variant.md), from\: [int](class_int.md) = -1\ ) const
[int](class_int.md)[rfind_custom](#class_Array_method_rfind_custom)\ (\ method\: [Callable](class_callable.md), from\: [int](class_int.md) = -1\ ) const
`void`[set](#class_Array_method_set)\ (\ index\: [int](class_int.md), value\: [Variant](class_variant.md)\ )
`void`[shuffle](#class_Array_method_shuffle)\ (\ )
[int](class_int.md)[size](#class_Array_method_size)\ (\ ) const
[Array](class_array.md)[slice](#class_Array_method_slice)\ (\ begin\: [int](class_int.md), end\: [int](class_int.md) = 2147483647, step\: [int](class_int.md) = 1, deep\: [bool](class_bool.md) = false\ ) const
`void`[sort](#class_Array_method_sort)\ (\ )
`void`[sort_custom](#class_Array_method_sort_custom)\ (\ func\: [Callable](class_callable.md)\ )
+ + + +## Operators + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[operator !=](#class_Array_operator_neq_Array)\ (\ right\: [Array](class_array.md)\ )
[Array](class_array.md)[operator +](#class_Array_operator_sum_Array)\ (\ right\: [Array](class_array.md)\ )
[bool](class_bool.md)[operator \<](#class_Array_operator_lt_Array)\ (\ right\: [Array](class_array.md)\ )
[bool](class_bool.md)[operator \<=](#class_Array_operator_lte_Array)\ (\ right\: [Array](class_array.md)\ )
[bool](class_bool.md)[operator ==](#class_Array_operator_eq_Array)\ (\ right\: [Array](class_array.md)\ )
[bool](class_bool.md)[operator >](#class_Array_operator_gt_Array)\ (\ right\: [Array](class_array.md)\ )
[bool](class_bool.md)[operator >=](#class_Array_operator_gte_Array)\ (\ right\: [Array](class_array.md)\ )
[Variant](class_variant.md)[operator []](#class_Array_operator_idx_int)\ (\ index\: [int](class_int.md)\ )
+ +
+ + + +## Constructor Descriptions + + + + + +[Array](class_array.md) **Array**\ (\ ) [🔗](#class_Array_constructor_Array) + +Constructs an empty **Array**. + +
+ + + +[Array](class_array.md) **Array**\ (\ base\: [Array](class_array.md), type\: [int](class_int.md), class_name\: [StringName](class_stringname.md), script\: [Variant](class_variant.md)\ ) + +Creates a typed array from the `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: + +- `type` is the built-in [Variant](class_variant.md) type, as one the [Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) constants. + +- `class_name` is the built-in class name (see [Object.get_class()](class_object.md#class_Object_method_get_class)). + +- `script` is the associated script. It must be a [Script](class_script.md) instance or ``null``. + +If `type` is not [@GlobalScope.TYPE_OBJECT](class_@globalscope.md#class_@GlobalScope_constant_TYPE_OBJECT), `class_name` must be an empty [StringName](class_stringname.md) and `script` must be ``null``. + +``` + 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] +``` + +The `base` array's elements are converted when necessary. If this is not possible or `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: + +``` + 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] +``` + +
+ + + +[Array](class_array.md) **Array**\ (\ from\: [Array](class_array.md)\ ) + +Returns the same array as `from`. If you need a copy of the array, use [duplicate()](class_array.md#class_Array_method_duplicate). + +
+ + + +[Array](class_array.md) **Array**\ (\ from\: [PackedByteArray](class_packedbytearray.md)\ ) + +Constructs an array from a [PackedByteArray](class_packedbytearray.md). + +
+ + + +[Array](class_array.md) **Array**\ (\ from\: [PackedColorArray](class_packedcolorarray.md)\ ) + +Constructs an array from a [PackedColorArray](class_packedcolorarray.md). + +
+ + + +[Array](class_array.md) **Array**\ (\ from\: [PackedFloat32Array](class_packedfloat32array.md)\ ) + +Constructs an array from a [PackedFloat32Array](class_packedfloat32array.md). + +
+ + + +[Array](class_array.md) **Array**\ (\ from\: [PackedFloat64Array](class_packedfloat64array.md)\ ) + +Constructs an array from a [PackedFloat64Array](class_packedfloat64array.md). + +
+ + + +[Array](class_array.md) **Array**\ (\ from\: [PackedInt32Array](class_packedint32array.md)\ ) + +Constructs an array from a [PackedInt32Array](class_packedint32array.md). + +
+ + + +[Array](class_array.md) **Array**\ (\ from\: [PackedInt64Array](class_packedint64array.md)\ ) + +Constructs an array from a [PackedInt64Array](class_packedint64array.md). + +
+ + + +[Array](class_array.md) **Array**\ (\ from\: [PackedStringArray](class_packedstringarray.md)\ ) + +Constructs an array from a [PackedStringArray](class_packedstringarray.md). + +
+ + + +[Array](class_array.md) **Array**\ (\ from\: [PackedVector2Array](class_packedvector2array.md)\ ) + +Constructs an array from a [PackedVector2Array](class_packedvector2array.md). + +
+ + + +[Array](class_array.md) **Array**\ (\ from\: [PackedVector3Array](class_packedvector3array.md)\ ) + +Constructs an array from a [PackedVector3Array](class_packedvector3array.md). + +
+ + + +[Array](class_array.md) **Array**\ (\ from\: [PackedVector4Array](class_packedvector4array.md)\ ) + +Constructs an array from a [PackedVector4Array](class_packedvector4array.md). + +
+ + + +## Method Descriptions + + + + + +[bool](class_bool.md) **all**\ (\ method\: [Callable](class_callable.md)\ ) const [🔗](#class_Array_method_all) + +Calls the given [Callable](class_callable.md) on each element in the array and returns ``true`` if the [Callable](class_callable.md) returns ``true`` for *all* elements in the array. If the [Callable](class_callable.md) returns ``false`` for one array element or more, this method returns ``false``. + +The `method` should take one [Variant](class_variant.md) parameter (the current array element) and return a [bool](class_bool.md). + + + + +```gdscript + func greater_than_5(number): + return number > 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 > 5)) # Prints true +``` + +```csharp + private static bool GreaterThan5(int number) + { + return number > 5; + } + + public override void _Ready() + { + // Prints True (3/3 elements evaluate to true). + GD.Print(new Godot.Collections.Array>int< { 6, 10, 6 }.All(GreaterThan5)); + // Prints False (1/3 elements evaluate to true). + GD.Print(new Godot.Collections.Array>int< { 4, 10, 4 }.All(GreaterThan5)); + // Prints False (0/3 elements evaluate to true). + GD.Print(new Godot.Collections.Array>int< { 4, 4, 4 }.All(GreaterThan5)); + // Prints True (0/0 elements evaluate to true). + GD.Print(new Godot.Collections.Array>int< { }.All(GreaterThan5)); + + // Same as the first line above, but using a lambda function. + GD.Print(new Godot.Collections.Array>int< { 6, 10, 6 }.All(element => element > 5)); // Prints True + } +``` + + + +See also [any()](class_array.md#class_Array_method_any), [filter()](class_array.md#class_Array_method_filter), [map()](class_array.md#class_Array_method_map) and [reduce()](class_array.md#class_Array_method_reduce). + +\ **Note:** Unlike relying on the size of an array returned by [filter()](class_array.md#class_Array_method_filter), this method will return as early as possible to improve performance (especially with large arrays). + +\ **Note:** For an empty array, this method [always](https://en.wikipedia.org/wiki/Vacuous_truth) returns ``true``. + +
+ + + + + +[bool](class_bool.md) **any**\ (\ method\: [Callable](class_callable.md)\ ) const [🔗](#class_Array_method_any) + +Calls the given [Callable](class_callable.md) on each element in the array and returns ``true`` if the [Callable](class_callable.md) returns ``true`` for *one or more* elements in the array. If the [Callable](class_callable.md) returns ``false`` for all elements in the array, this method returns ``false``. + +The `method` should take one [Variant](class_variant.md) parameter (the current array element) and return a [bool](class_bool.md). + +``` + func greater_than_5(number): + return number > 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 > 5)) # Prints true +``` + +See also [all()](class_array.md#class_Array_method_all), [filter()](class_array.md#class_Array_method_filter), [map()](class_array.md#class_Array_method_map) and [reduce()](class_array.md#class_Array_method_reduce). + +\ **Note:** Unlike relying on the size of an array returned by [filter()](class_array.md#class_Array_method_filter), this method will return as early as possible to improve performance (especially with large arrays). + +\ **Note:** For an empty array, this method always returns ``false``. + +
+ + + + + +`void` **append**\ (\ value\: [Variant](class_variant.md)\ ) [🔗](#class_Array_method_append) + +Appends `value` at the end of the array (alias of [push_back()](class_array.md#class_Array_method_push_back)). + +
+ + + + + +`void` **append_array**\ (\ array\: [Array](class_array.md)\ ) [🔗](#class_Array_method_append_array) + +Appends another `array` at the end of this array. + +``` + var numbers = [1, 2, 3] + var extra = [4, 5, 6] + numbers.append_array(extra) + print(numbers) # Prints [1, 2, 3, 4, 5, 6] +``` + +
+ + + + + +`void` **assign**\ (\ array\: [Array](class_array.md)\ ) [🔗](#class_Array_method_assign) + +Assigns elements of another `array` into the array. Resizes the array to match `array`. Performs type conversions if the array is typed. + +
+ + + + + +[Variant](class_variant.md) **back**\ (\ ) const [🔗](#class_Array_method_back) + +Returns the last element of the array. If the array is empty, fails and returns ``null``. See also [front()](class_array.md#class_Array_method_front). + +\ **Note:** Unlike with the ``[]`` operator (``array[-1]``), an error is generated without stopping project execution. + +
+ + + + + +[int](class_int.md) **bsearch**\ (\ value\: [Variant](class_variant.md), before\: [bool](class_bool.md) = true\ ) const [🔗](#class_Array_method_bsearch) + +Returns the index of `value` in the sorted array. If it cannot be found, returns where `value` should be inserted to keep the array sorted. The algorithm used is [binary search](https://en.wikipedia.org/wiki/Binary_search_algorithm). + +If `before` is ``true`` (as by default), the returned index comes before all existing elements equal to `value` in the array. + +``` + 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". +``` + +\ **Note:** Calling [bsearch()](class_array.md#class_Array_method_bsearch) on an *unsorted* array will result in unexpected behavior. Use [sort()](class_array.md#class_Array_method_sort) before calling this method. + +
+ + + + + +[int](class_int.md) **bsearch_custom**\ (\ value\: [Variant](class_variant.md), func\: [Callable](class_callable.md), before\: [bool](class_bool.md) = true\ ) const [🔗](#class_Array_method_bsearch_custom) + +Returns the index of `value` in the sorted array. If it cannot be found, returns where `value` should be inserted to keep the array sorted (using `func` for the comparisons). The algorithm used is [binary search](https://en.wikipedia.org/wiki/Binary_search_algorithm). + +Similar to [sort_custom()](class_array.md#class_Array_method_sort_custom), `func` is called as many times as necessary, receiving one array element and `value` as arguments. The function should return ``true`` if the array element should be *behind* `value`, otherwise it should return ``false``. + +If `before` is ``true`` (as by default), the returned index comes before all existing elements equal to `value` in the array. + +``` + func sort_by_amount(a, b): + if a[1] < 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) +``` + +\ **Note:** Calling [bsearch_custom()](class_array.md#class_Array_method_bsearch_custom) on an *unsorted* array will result in unexpected behavior. Use [sort_custom()](class_array.md#class_Array_method_sort_custom) with `func` before calling this method. + +
+ + + + + +`void` **clear**\ (\ ) [🔗](#class_Array_method_clear) + +Removes all elements from the array. This is equivalent to using [resize()](class_array.md#class_Array_method_resize) with a size of ``0``. + +
+ + + + + +[int](class_int.md) **count**\ (\ value\: [Variant](class_variant.md)\ ) const [🔗](#class_Array_method_count) + +Returns the number of times an element is in the array. + +To count how many elements in an array satisfy a condition, see [reduce()](class_array.md#class_Array_method_reduce). + +
+ + + + + +[Array](class_array.md) **duplicate**\ (\ deep\: [bool](class_bool.md) = false\ ) const [🔗](#class_Array_method_duplicate) + +Returns a new copy of the array. + +By default, a **shallow** copy is returned: all nested **Array**, [Dictionary](class_dictionary.md), and [Resource](class_resource.md) elements are shared with the original array. Modifying any of those in one array will also affect them in the other. + +If `deep` is ``true``, a **deep** copy is returned: all nested arrays and dictionaries are also duplicated (recursively). Any [Resource](class_resource.md) is still shared with the original array, though. + +
+ + + + + +[Array](class_array.md) **duplicate_deep**\ (\ deep_subresources_mode\: [int](class_int.md) = 1\ ) const [🔗](#class_Array_method_duplicate_deep) + +Duplicates this array, deeply, like [duplicate()](class_array.md#class_Array_method_duplicate)\ ``(true)``, with extra control over how subresources are handled. + +\ `deep_subresources_mode` must be one of the values from [DeepDuplicateMode](class_resource.md#enum_Resource_DeepDuplicateMode). By default, only internal resources will be duplicated (recursively). + +
+ + + + + +`void` **erase**\ (\ value\: [Variant](class_variant.md)\ ) [🔗](#class_Array_method_erase) + +Finds and removes the first occurrence of `value` from the array. If `value` does not exist in the array, nothing happens. To remove an element by index, use [remove_at()](class_array.md#class_Array_method_remove_at) instead. + +\ **Note:** This method shifts every element's index after the removed `value` back, which may have a noticeable performance cost, especially on larger arrays. + +\ **Note:** Erasing elements while iterating over arrays is **not** supported and will result in unpredictable behavior. + +
+ + + + + +`void` **fill**\ (\ value\: [Variant](class_variant.md)\ ) [🔗](#class_Array_method_fill) + +Assigns the given `value` to all elements in the array. + +This method can often be combined with [resize()](class_array.md#class_Array_method_resize) to create an array with a given size and initialized elements: + + + + +```gdscript + var array = [] + array.resize(5) + array.fill(2) + print(array) # Prints [2, 2, 2, 2, 2] +``` + +```csharp + Godot.Collections.Array array = []; + array.Resize(5); + array.Fill(2); + GD.Print(array); // Prints [2, 2, 2, 2, 2] +``` + + + +\ **Note:** If `value` is a [Variant](class_variant.md) passed by reference ([Object](class_object.md)-derived, **Array**, [Dictionary](class_dictionary.md), etc.), the array will be filled with references to the same `value`, which are not duplicates. + +
+ + + + + +[Array](class_array.md) **filter**\ (\ method\: [Callable](class_callable.md)\ ) const [🔗](#class_Array_method_filter) + +Calls the given [Callable](class_callable.md) on each element in the array and returns a new, filtered **Array**. + +The `method` receives one of the array elements as an argument, and should return ``true`` to add the element to the filtered array, or ``false`` to exclude it. + +``` + 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)) +``` + +See also [any()](class_array.md#class_Array_method_any), [all()](class_array.md#class_Array_method_all), [map()](class_array.md#class_Array_method_map) and [reduce()](class_array.md#class_Array_method_reduce). + +
+ + + + + +[int](class_int.md) **find**\ (\ what\: [Variant](class_variant.md), from\: [int](class_int.md) = 0\ ) const [🔗](#class_Array_method_find) + +Returns the index of the **first** occurrence of `what` in this array, or ``-1`` if there are none. The search's start can be specified with `from`, continuing to the end of the array. + +\ **Note:** If you just want to know whether the array contains `what`, use [has()](class_array.md#class_Array_method_has) (``Contains`` in C#). In GDScript, you may also use the ``in`` operator. + +\ **Note:** For performance reasons, the search is affected by `what`'s [Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type). For example, ``7`` ([int](class_int.md)) and ``7.0`` ([float](class_float.md)) are not considered equal for this method. + +
+ + + + + +[int](class_int.md) **find_custom**\ (\ method\: [Callable](class_callable.md), from\: [int](class_int.md) = 0\ ) const [🔗](#class_Array_method_find_custom) + +Returns the index of the **first** element in the array that causes `method` to return ``true``, or ``-1`` if there are none. The search's start can be specified with `from`, continuing to the end of the array. + +\ `method` is a callable that takes an element of the array, and returns a [bool](class_bool.md). + +\ **Note:** If you just want to know whether the array contains *anything* that satisfies `method`, use [any()](class_array.md#class_Array_method_any). + + + + +```gdscript + func is_even(number): + return number % 2 == 0 + + func _ready(): + print([1, 3, 4, 7].find_custom(is_even.bind())) # Prints 2 +``` + + + +
+ + + + + +[Variant](class_variant.md) **front**\ (\ ) const [🔗](#class_Array_method_front) + +Returns the first element of the array. If the array is empty, fails and returns ``null``. See also [back()](class_array.md#class_Array_method_back). + +\ **Note:** Unlike with the ``[]`` operator (``array[0]``), an error is generated without stopping project execution. + +
+ + + + + +[Variant](class_variant.md) **get**\ (\ index\: [int](class_int.md)\ ) const [🔗](#class_Array_method_get) + +Returns the element at the given `index` in the array. If `index` out-of-bounds or negative, this method fails and returns ``null``. + +This method is similar (but not identical) to the ``[]`` operator. Most notably, when this method fails, it doesn't pause project execution if run from the editor. + +
+ + + + + +[int](class_int.md) **get_typed_builtin**\ (\ ) const [🔗](#class_Array_method_get_typed_builtin) + +Returns the built-in [Variant](class_variant.md) type of the typed array as a [Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type) constant. If the array is not typed, returns [@GlobalScope.TYPE_NIL](class_@globalscope.md#class_@GlobalScope_constant_TYPE_NIL). See also [is_typed()](class_array.md#class_Array_method_is_typed). + +
+ + + + + +[StringName](class_stringname.md) **get_typed_class_name**\ (\ ) const [🔗](#class_Array_method_get_typed_class_name) + +Returns the **built-in** class name of the typed array, if the built-in [Variant](class_variant.md) type [@GlobalScope.TYPE_OBJECT](class_@globalscope.md#class_@GlobalScope_constant_TYPE_OBJECT). Otherwise, returns an empty [StringName](class_stringname.md). See also [is_typed()](class_array.md#class_Array_method_is_typed) and [Object.get_class()](class_object.md#class_Object_method_get_class). + +
+ + + + + +[Variant](class_variant.md) **get_typed_script**\ (\ ) const [🔗](#class_Array_method_get_typed_script) + +Returns the [Script](class_script.md) instance associated with this typed array, or ``null`` if it does not exist. See also [is_typed()](class_array.md#class_Array_method_is_typed). + +
+ + + + + +[bool](class_bool.md) **has**\ (\ value\: [Variant](class_variant.md)\ ) const [🔗](#class_Array_method_has) + +Returns ``true`` if the array contains the given `value`. + + + + +```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 +``` + +```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 +``` + + + +In GDScript, this is equivalent to the ``in`` operator: + +``` + if 4 in [2, 4, 6, 8]: + print("4 is here!") # Will be printed. +``` + +\ **Note:** For performance reasons, the search is affected by the `value`'s [Variant.Type](class_@globalscope.md#enum_@GlobalScope_Variant.Type). For example, ``7`` ([int](class_int.md)) and ``7.0`` ([float](class_float.md)) are not considered equal for this method. + +
+ + + + + +[int](class_int.md) **hash**\ (\ ) const [🔗](#class_Array_method_hash) + +Returns a hashed 32-bit integer value representing the array and its contents. + +\ **Note:** Arrays with equal hash values are *not* guaranteed to be the same, as a result of hash collisions. On the countrary, arrays with different hash values are guaranteed to be different. + +
+ + + + + +[int](class_int.md) **insert**\ (\ position\: [int](class_int.md), value\: [Variant](class_variant.md)\ ) [🔗](#class_Array_method_insert) + +Inserts a new element (`value`) at a given index (`position`) in the array. `position` should be between ``0`` and the array's [size()](class_array.md#class_Array_method_size). If negative, `position` is considered relative to the end of the array. + +Returns [@GlobalScope.OK](class_@globalscope.md#class_@GlobalScope_constant_OK) on success, or one of the other [Error](class_@globalscope.md#enum_@GlobalScope_Error) constants if this method fails. + +\ **Note:** Every element's index after `position` needs to be shifted forward, which may have a noticeable performance cost, especially on larger arrays. + +
+ + + + + +[bool](class_bool.md) **is_empty**\ (\ ) const [🔗](#class_Array_method_is_empty) + +Returns ``true`` if the array is empty (``[]``). See also [size()](class_array.md#class_Array_method_size). + +
+ + + + + +[bool](class_bool.md) **is_read_only**\ (\ ) const [🔗](#class_Array_method_is_read_only) + +Returns ``true`` if the array is read-only. See [make_read_only()](class_array.md#class_Array_method_make_read_only). + +In GDScript, arrays are automatically read-only if declared with the ``const`` keyword. + +
+ + + + + +[bool](class_bool.md) **is_same_typed**\ (\ array\: [Array](class_array.md)\ ) const [🔗](#class_Array_method_is_same_typed) + +Returns ``true`` if this array is typed the same as the given `array`. See also [is_typed()](class_array.md#class_Array_method_is_typed). + +
+ + + + + +[bool](class_bool.md) **is_typed**\ (\ ) const [🔗](#class_Array_method_is_typed) + +Returns ``true`` 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](class_variant.md). + +In GDScript, it is possible to define a typed array with static typing: + +``` + var numbers: Array[float] = [0.2, 4.2, -2.0] + print(numbers.is_typed()) # Prints true +``` + +
+ + + + + +`void` **make_read_only**\ (\ ) [🔗](#class_Array_method_make_read_only) + +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 ``const`` keyword. + +
+ + + + + +[Array](class_array.md) **map**\ (\ method\: [Callable](class_callable.md)\ ) const [🔗](#class_Array_method_map) + +Calls the given [Callable](class_callable.md) for each element in the array and returns a new array filled with values returned by the `method`. + +The `method` should take one [Variant](class_variant.md) parameter (the current array element) and can return any [Variant](class_variant.md). + +``` + 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)) +``` + +See also [filter()](class_array.md#class_Array_method_filter), [reduce()](class_array.md#class_Array_method_reduce), [any()](class_array.md#class_Array_method_any) and [all()](class_array.md#class_Array_method_all). + +
+ + + + + +[Variant](class_variant.md) **max**\ (\ ) const [🔗](#class_Array_method_max) + +Returns the maximum value contained in the array, if all elements can be compared. Otherwise, returns ``null``. See also [min()](class_array.md#class_Array_method_min). + +To find the maximum value using a custom comparator, you can use [reduce()](class_array.md#class_Array_method_reduce). + +
+ + + + + +[Variant](class_variant.md) **min**\ (\ ) const [🔗](#class_Array_method_min) + +Returns the minimum value contained in the array, if all elements can be compared. Otherwise, returns ``null``. See also [max()](class_array.md#class_Array_method_max). + +
+ + + + + +[Variant](class_variant.md) **pick_random**\ (\ ) const [🔗](#class_Array_method_pick_random) + +Returns a random element from the array. Generates an error and returns ``null`` if the array is empty. + + + + +```gdscript + # May print 1, 2, 3.25, or "Hi". + print([1, 2, 3.25, "Hi"].pick_random()) +``` + +```csharp + Godot.Collections.Array array = [1, 2, 3.25f, "Hi"]; + GD.Print(array.PickRandom()); // May print 1, 2, 3.25, or "Hi". +``` + + + +\ **Note:** Like many similar functions in the engine (such as [@GlobalScope.randi()](class_@globalscope.md#class_@GlobalScope_method_randi) or [shuffle()](class_array.md#class_Array_method_shuffle)), this method uses a common, global random seed. To get a predictable outcome from this method, see [@GlobalScope.seed()](class_@globalscope.md#class_@GlobalScope_method_seed). + +
+ + + + + +[Variant](class_variant.md) **pop_at**\ (\ position\: [int](class_int.md)\ ) [🔗](#class_Array_method_pop_at) + +Removes and returns the element of the array at index `position`. If negative, `position` is considered relative to the end of the array. Returns ``null`` if the array is empty. If `position` is out of bounds, an error message is also generated. + +\ **Note:** This method shifts every element's index after `position` back, which may have a noticeable performance cost, especially on larger arrays. + +
+ + + + + +[Variant](class_variant.md) **pop_back**\ (\ ) [🔗](#class_Array_method_pop_back) + +Removes and returns the last element of the array. Returns ``null`` if the array is empty, without generating an error. See also [pop_front()](class_array.md#class_Array_method_pop_front). + +
+ + + + + +[Variant](class_variant.md) **pop_front**\ (\ ) [🔗](#class_Array_method_pop_front) + +Removes and returns the first element of the array. Returns ``null`` if the array is empty, without generating an error. See also [pop_back()](class_array.md#class_Array_method_pop_back). + +\ **Note:** This method shifts every other element's index back, which may have a noticeable performance cost, especially on larger arrays. + +
+ + + + + +`void` **push_back**\ (\ value\: [Variant](class_variant.md)\ ) [🔗](#class_Array_method_push_back) + +Appends an element at the end of the array. See also [push_front()](class_array.md#class_Array_method_push_front). + +
+ + + + + +`void` **push_front**\ (\ value\: [Variant](class_variant.md)\ ) [🔗](#class_Array_method_push_front) + +Adds an element at the beginning of the array. See also [push_back()](class_array.md#class_Array_method_push_back). + +\ **Note:** This method shifts every other element's index forward, which may have a noticeable performance cost, especially on larger arrays. + +
+ + + + + +[Variant](class_variant.md) **reduce**\ (\ method\: [Callable](class_callable.md), accum\: [Variant](class_variant.md) = null\ ) const [🔗](#class_Array_method_reduce) + +Calls the given [Callable](class_callable.md) for each element in array, accumulates the result in `accum`, then returns it. + +The `method` takes two arguments: the current value of `accum` and the current array element. If `accum` is ``null`` (as by default), the iteration will start from the second element, with the first one used as initial value of `accum`. + +``` + 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)) +``` + +If [max()](class_array.md#class_Array_method_max) is not desirable, this method may also be used to implement a custom comparator: + +``` + 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() > b.length() +``` + +This method can also be used to count how many elements in an array satisfy a certain condition, similar to [count()](class_array.md#class_Array_method_count): + +``` + 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 +``` + +See also [map()](class_array.md#class_Array_method_map), [filter()](class_array.md#class_Array_method_filter), [any()](class_array.md#class_Array_method_any), and [all()](class_array.md#class_Array_method_all). + +
+ + + + + +`void` **remove_at**\ (\ position\: [int](class_int.md)\ ) [🔗](#class_Array_method_remove_at) + +Removes the element from the array at the given index (`position`). If the index is out of bounds, this method fails. If the index is negative, `position` is considered relative to the end of the array. + +If you need to return the removed element, use [pop_at()](class_array.md#class_Array_method_pop_at). To remove an element by value, use [erase()](class_array.md#class_Array_method_erase) instead. + +\ **Note:** This method shifts every element's index after `position` back, which may have a noticeable performance cost, especially on larger arrays. + +
+ + + + + +[int](class_int.md) **resize**\ (\ size\: [int](class_int.md)\ ) [🔗](#class_Array_method_resize) + +Sets the array's number of elements to `size`. If `size` is smaller than the array's current size, the elements at the end are removed. If `size` is greater, new default elements (usually ``null``) are added, depending on the array's type. + +Returns [@GlobalScope.OK](class_@globalscope.md#class_@GlobalScope_constant_OK) on success, or one of the following [Error](class_@globalscope.md#enum_@GlobalScope_Error) constants if this method fails: [@GlobalScope.ERR_LOCKED](class_@globalscope.md#class_@GlobalScope_constant_ERR_LOCKED) if the array is read-only, [@GlobalScope.ERR_INVALID_PARAMETER](class_@globalscope.md#class_@GlobalScope_constant_ERR_INVALID_PARAMETER) if the size is negative, or [@GlobalScope.ERR_OUT_OF_MEMORY](class_@globalscope.md#class_@GlobalScope_constant_ERR_OUT_OF_MEMORY) if allocations fail. Use [size()](class_array.md#class_Array_method_size) to find the actual size of the array after resize. + +\ **Note:** Calling this method once and assigning the new values is faster than calling [append()](class_array.md#class_Array_method_append) for every new element. + +
+ + + + + +`void` **reverse**\ (\ ) [🔗](#class_Array_method_reverse) + +Reverses the order of all elements in the array. + +
+ + + + + +[int](class_int.md) **rfind**\ (\ what\: [Variant](class_variant.md), from\: [int](class_int.md) = -1\ ) const [🔗](#class_Array_method_rfind) + +Returns the index of the **last** occurrence of `what` in this array, or ``-1`` if there are none. The search's start can be specified with `from`, continuing to the beginning of the array. This method is the reverse of [find()](class_array.md#class_Array_method_find). + +
+ + + + + +[int](class_int.md) **rfind_custom**\ (\ method\: [Callable](class_callable.md), from\: [int](class_int.md) = -1\ ) const [🔗](#class_Array_method_rfind_custom) + +Returns the index of the **last** element of the array that causes `method` to return ``true``, or ``-1`` if there are none. The search's start can be specified with `from`, continuing to the beginning of the array. This method is the reverse of [find_custom()](class_array.md#class_Array_method_find_custom). + +
+ + + + + +`void` **set**\ (\ index\: [int](class_int.md), value\: [Variant](class_variant.md)\ ) [🔗](#class_Array_method_set) + +Sets the value of the element at the given `index` to the given `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 ``[]`` operator (``array[index] = value``). + +
+ + + + + +`void` **shuffle**\ (\ ) [🔗](#class_Array_method_shuffle) + +Shuffles all elements of the array in a random order. + +\ **Note:** Like many similar functions in the engine (such as [@GlobalScope.randi()](class_@globalscope.md#class_@GlobalScope_method_randi) or [pick_random()](class_array.md#class_Array_method_pick_random)), this method uses a common, global random seed. To get a predictable outcome from this method, see [@GlobalScope.seed()](class_@globalscope.md#class_@GlobalScope_method_seed). + +
+ + + + + +[int](class_int.md) **size**\ (\ ) const [🔗](#class_Array_method_size) + +Returns the number of elements in the array. Empty arrays (``[]``) always return ``0``. See also [is_empty()](class_array.md#class_Array_method_is_empty). + +
+ + + + + +[Array](class_array.md) **slice**\ (\ begin\: [int](class_int.md), end\: [int](class_int.md) = 2147483647, step\: [int](class_int.md) = 1, deep\: [bool](class_bool.md) = false\ ) const [🔗](#class_Array_method_slice) + +Returns a new **Array** containing this array's elements, from index `begin` (inclusive) to `end` (exclusive), every `step` elements. + +If either `begin` or `end` are negative, their value is relative to the end of the array. + +If `step` is negative, this method iterates through the array in reverse, returning a slice ordered backwards. For this to work, `begin` must be greater than `end`. + +If `deep` is ``true``, all nested **Array** and [Dictionary](class_dictionary.md) elements in the slice are duplicated from the original, recursively. See also [duplicate()](class_array.md#class_Array_method_duplicate). + +``` + 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"] +``` + +
+ + + + + +`void` **sort**\ (\ ) [🔗](#class_Array_method_sort) + +Sorts the array in ascending order. The final order is dependent on the "less than" (``<``) comparison between elements. + + + + +```gdscript + var numbers = [10, 5, 2.5, 8] + numbers.sort() + print(numbers) # Prints [2.5, 5, 8, 10] +``` + +```csharp + Godot.Collections.Array numbers = [10, 5, 2.5, 8]; + numbers.Sort(); + GD.Print(numbers); // Prints [2.5, 5, 8, 10] +``` + + + +\ **Note:** The sorting algorithm used is not [stable](https://en.wikipedia.org/wiki/Sorting_algorithm#Stability). This means that equivalent elements (such as ``2`` and ``2.0``) may have their order changed when calling [sort()](class_array.md#class_Array_method_sort). + +
+ + + + + +`void` **sort_custom**\ (\ func\: [Callable](class_callable.md)\ ) [🔗](#class_Array_method_sort_custom) + +Sorts the array using a custom [Callable](class_callable.md). + +\ `func` is called as many times as necessary, receiving two array elements as arguments. The function should return ``true`` if the first element should be moved *before* the second one, otherwise it should return ``false``. + +``` + func sort_ascending(a, b): + if a[1] < 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] > b[1]) + print(my_items) # Prints [["Apple", 9], ["Tomato", 5], ["Rice", 4]] +``` + +It may also be necessary to use this method to sort strings by natural order, with [String.naturalnocasecmp_to()](class_string.md#class_String_method_naturalnocasecmp_to), as in the following example: + +``` + var files = ["newfile1", "newfile2", "newfile10", "newfile11"] + files.sort_custom(func(a, b): return a.naturalnocasecmp_to(b) < 0) + print(files) # Prints ["newfile1", "newfile2", "newfile10", "newfile11"] +``` + +\ **Note:** In C#, this method is not supported. + +\ **Note:** The sorting algorithm used is not [stable](https://en.wikipedia.org/wiki/Sorting_algorithm#Stability). This means that values considered equal may have their order changed when calling this method. + +\ **Note:** You should not randomize the return value of `func`, as the heapsort algorithm expects a consistent result. Randomizing the return value will result in unexpected behavior. + +
+ + + +## Operator Descriptions + + + + + +[bool](class_bool.md) **operator !=**\ (\ right\: [Array](class_array.md)\ ) [🔗](#class_Array_operator_neq_Array) + +Returns ``true`` if the array's size or its elements are different than `right`'s. + +
+ + + + + +[Array](class_array.md) **operator +**\ (\ right\: [Array](class_array.md)\ ) [🔗](#class_Array_operator_sum_Array) + +Appends the `right` array to the left operand, creating a new **Array**. This is also known as an array concatenation. + + + + +```gdscript + var array1 = ["One", 2] + var array2 = [3, "Four"] + print(array1 + array2) # Prints ["One", 2, 3, "Four"] +``` + +```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"] +``` + + + +\ **Note:** For existing arrays, [append_array()](class_array.md#class_Array_method_append_array) is much more efficient than concatenation and assignment with the ``+=`` operator. + +
+ + + + + +[bool](class_bool.md) **operator <**\ (\ right\: [Array](class_array.md)\ ) [🔗](#class_Array_operator_lt_Array) + +Compares the elements of both arrays in order, starting from index ``0`` and ending on the last index in common between both arrays. For each pair of elements, returns ``true`` if this array's element is less than `right`'s, ``false`` if this element is greater. Otherwise, continues to the next pair. + +If all searched elements are equal, returns ``true`` if this array's size is less than `right`'s, otherwise returns ``false``. + +
+ + + + + +[bool](class_bool.md) **operator <=**\ (\ right\: [Array](class_array.md)\ ) [🔗](#class_Array_operator_lte_Array) + +Compares the elements of both arrays in order, starting from index ``0`` and ending on the last index in common between both arrays. For each pair of elements, returns ``true`` if this array's element is less than `right`'s, ``false`` if this element is greater. Otherwise, continues to the next pair. + +If all searched elements are equal, returns ``true`` if this array's size is less or equal to `right`'s, otherwise returns ``false``. + +
+ + + + + +[bool](class_bool.md) **operator ==**\ (\ right\: [Array](class_array.md)\ ) [🔗](#class_Array_operator_eq_Array) + +Compares the left operand **Array** against the `right` **Array**. Returns ``true`` if the sizes and contents of the arrays are equal, ``false`` otherwise. + +
+ + + + + +[bool](class_bool.md) **operator >**\ (\ right\: [Array](class_array.md)\ ) [🔗](#class_Array_operator_gt_Array) + +Compares the elements of both arrays in order, starting from index ``0`` and ending on the last index in common between both arrays. For each pair of elements, returns ``true`` if this array's element is greater than `right`'s, ``false`` if this element is less. Otherwise, continues to the next pair. + +If all searched elements are equal, returns ``true`` if this array's size is greater than `right`'s, otherwise returns ``false``. + +
+ + + + + +[bool](class_bool.md) **operator >=**\ (\ right\: [Array](class_array.md)\ ) [🔗](#class_Array_operator_gte_Array) + +Compares the elements of both arrays in order, starting from index ``0`` and ending on the last index in common between both arrays. For each pair of elements, returns ``true`` if this array's element is greater than `right`'s, ``false`` if this element is less. Otherwise, continues to the next pair. + +If all searched elements are equal, returns ``true`` if this array's size is greater or equal to `right`'s, otherwise returns ``false``. + +
+ + + + + +[Variant](class_variant.md) **operator []**\ (\ index\: [int](class_int.md)\ ) [🔗](#class_Array_operator_idx_int) + +Returns the [Variant](class_variant.md) element at the specified `index`. Arrays start at index 0. If `index` is greater or equal to ``0``, the element is fetched starting from the beginning of the array. If `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. + diff --git a/docs/Classes/class_arraymesh.md b/docs/Classes/class_arraymesh.md new file mode 100644 index 00000000..c84ac546 --- /dev/null +++ b/docs/Classes/class_arraymesh.md @@ -0,0 +1,471 @@ + + + + + + + + + +# ArrayMesh + +**Inherits:** [Mesh](class_mesh.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +[Mesh](class_mesh.md) type that provides utility for constructing a surface from arrays. + + + +## Description + +The **ArrayMesh** is used to construct a [Mesh](class_mesh.md) by specifying the attributes as arrays. + +The most basic example is the creation of a single triangle: + + + + +```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 +``` + +```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; +``` + + + +The [MeshInstance3D](class_meshinstance3d.md) is ready to be added to the [SceneTree](class_scenetree.md) to be shown. + +See also [ImmediateMesh](class_immediatemesh.md), [MeshDataTool](class_meshdatatool.md) and [SurfaceTool](class_surfacetool.md) for procedural geometry generation. + +\ **Note:** Redot uses clockwise [winding order](https://learnopengl.com/Advanced-OpenGL/Face-culling) for front faces of triangle primitive modes. + + + +## Tutorials + +- [Procedural geometry using the ArrayMesh](../tutorials/3d/procedural_geometry/arraymesh.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + +
[BlendShapeMode](class_mesh.md#enum_Mesh_BlendShapeMode)[blend_shape_mode](#class_ArrayMesh_property_blend_shape_mode)`1`
[AABB](class_aabb.md)[custom_aabb](#class_ArrayMesh_property_custom_aabb)`AABB(0, 0, 0, 0, 0, 0)`
[ArrayMesh](class_arraymesh.md)[shadow_mesh](#class_ArrayMesh_property_shadow_mesh)
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
`void`[add_blend_shape](#class_ArrayMesh_method_add_blend_shape)\ (\ name\: [StringName](class_stringname.md)\ )
`void`[add_surface_from_arrays](#class_ArrayMesh_method_add_surface_from_arrays)\ (\ primitive\: [PrimitiveType](class_mesh.md#enum_Mesh_PrimitiveType), arrays\: [Array](class_array.md), blend_shapes\: [Array](class_array.md)\[[Array](class_array.md)\] = [], lods\: [Dictionary](class_dictionary.md) = {}, flags\: **BitField**\[[ArrayFormat](class_mesh.md#enum_Mesh_ArrayFormat)\] = 0\ )
`void`[clear_blend_shapes](#class_ArrayMesh_method_clear_blend_shapes)\ (\ )
`void`[clear_surfaces](#class_ArrayMesh_method_clear_surfaces)\ (\ )
[int](class_int.md)[get_blend_shape_count](#class_ArrayMesh_method_get_blend_shape_count)\ (\ ) const
[StringName](class_stringname.md)[get_blend_shape_name](#class_ArrayMesh_method_get_blend_shape_name)\ (\ index\: [int](class_int.md)\ ) const
[Error](class_@globalscope.md#enum_@GlobalScope_Error)[lightmap_unwrap](#class_ArrayMesh_method_lightmap_unwrap)\ (\ transform\: [Transform3D](class_transform3d.md), texel_size\: [float](class_float.md)\ )
`void`[regen_normal_maps](#class_ArrayMesh_method_regen_normal_maps)\ (\ )
`void`[set_blend_shape_name](#class_ArrayMesh_method_set_blend_shape_name)\ (\ index\: [int](class_int.md), name\: [StringName](class_stringname.md)\ )
[int](class_int.md)[surface_find_by_name](#class_ArrayMesh_method_surface_find_by_name)\ (\ name\: [String](class_string.md)\ ) const
[int](class_int.md)[surface_get_array_index_len](#class_ArrayMesh_method_surface_get_array_index_len)\ (\ surf_idx\: [int](class_int.md)\ ) const
[int](class_int.md)[surface_get_array_len](#class_ArrayMesh_method_surface_get_array_len)\ (\ surf_idx\: [int](class_int.md)\ ) const
**BitField**\[[ArrayFormat](class_mesh.md#enum_Mesh_ArrayFormat)\][surface_get_format](#class_ArrayMesh_method_surface_get_format)\ (\ surf_idx\: [int](class_int.md)\ ) const
[String](class_string.md)[surface_get_name](#class_ArrayMesh_method_surface_get_name)\ (\ surf_idx\: [int](class_int.md)\ ) const
[PrimitiveType](class_mesh.md#enum_Mesh_PrimitiveType)[surface_get_primitive_type](#class_ArrayMesh_method_surface_get_primitive_type)\ (\ surf_idx\: [int](class_int.md)\ ) const
`void`[surface_remove](#class_ArrayMesh_method_surface_remove)\ (\ surf_idx\: [int](class_int.md)\ )
`void`[surface_set_name](#class_ArrayMesh_method_surface_set_name)\ (\ surf_idx\: [int](class_int.md), name\: [String](class_string.md)\ )
`void`[surface_update_attribute_region](#class_ArrayMesh_method_surface_update_attribute_region)\ (\ surf_idx\: [int](class_int.md), offset\: [int](class_int.md), data\: [PackedByteArray](class_packedbytearray.md)\ )
`void`[surface_update_skin_region](#class_ArrayMesh_method_surface_update_skin_region)\ (\ surf_idx\: [int](class_int.md), offset\: [int](class_int.md), data\: [PackedByteArray](class_packedbytearray.md)\ )
`void`[surface_update_vertex_region](#class_ArrayMesh_method_surface_update_vertex_region)\ (\ surf_idx\: [int](class_int.md), offset\: [int](class_int.md), data\: [PackedByteArray](class_packedbytearray.md)\ )
+ +
+ + + +## Property Descriptions + + + + + +[BlendShapeMode](class_mesh.md#enum_Mesh_BlendShapeMode) **blend_shape_mode** = `1` [🔗](#class_ArrayMesh_property_blend_shape_mode) + + + +- `void` **set_blend_shape_mode**\ (\ value\: [BlendShapeMode](class_mesh.md#enum_Mesh_BlendShapeMode)\ ) +- [BlendShapeMode](class_mesh.md#enum_Mesh_BlendShapeMode) **get_blend_shape_mode**\ (\ ) + +The blend shape mode. + +
+ + + + + +[AABB](class_aabb.md) **custom_aabb** = `AABB(0, 0, 0, 0, 0, 0)` [🔗](#class_ArrayMesh_property_custom_aabb) + + + +- `void` **set_custom_aabb**\ (\ value\: [AABB](class_aabb.md)\ ) +- [AABB](class_aabb.md) **get_custom_aabb**\ (\ ) + +Overrides the [AABB](class_aabb.md) with one defined by user for use with frustum culling. Especially useful to avoid unexpected culling when using a shader to offset vertices. + +
+ + + + + +[ArrayMesh](class_arraymesh.md) **shadow_mesh** [🔗](#class_ArrayMesh_property_shadow_mesh) + + + +- `void` **set_shadow_mesh**\ (\ value\: [ArrayMesh](class_arraymesh.md)\ ) +- [ArrayMesh](class_arraymesh.md) **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.). + +\ **Note:** 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. + +
+ + + +## Method Descriptions + + + + + +`void` **add_blend_shape**\ (\ name\: [StringName](class_stringname.md)\ ) [🔗](#class_ArrayMesh_method_add_blend_shape) + +Adds name for a blend shape that will be added with [add_surface_from_arrays()](class_arraymesh.md#class_ArrayMesh_method_add_surface_from_arrays). Must be called before surface is added. + +
+ + + + + +`void` **add_surface_from_arrays**\ (\ primitive\: [PrimitiveType](class_mesh.md#enum_Mesh_PrimitiveType), arrays\: [Array](class_array.md), blend_shapes\: [Array](class_array.md)\[[Array](class_array.md)\] = [], lods\: [Dictionary](class_dictionary.md) = {}, flags\: **BitField**\[[ArrayFormat](class_mesh.md#enum_Mesh_ArrayFormat)\] = 0\ ) [🔗](#class_ArrayMesh_method_add_surface_from_arrays) + +Creates a new surface. [Mesh.get_surface_count()](class_mesh.md#class_Mesh_method_get_surface_count) will become the ``surf_idx`` for this new surface. + +Surfaces are created to be rendered using a `primitive`, which may be any of the values defined in [PrimitiveType](class_mesh.md#enum_Mesh_PrimitiveType). + +The `arrays` argument is an array of arrays. Each of the [Mesh.ARRAY_MAX](class_mesh.md#class_Mesh_constant_ARRAY_MAX) elements contains an array with some of the mesh data for this surface as described by the corresponding member of [ArrayType](class_mesh.md#enum_Mesh_ArrayType) or ``null`` if it is not used by the surface. For example, ``arrays[0]`` 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 [Mesh.ARRAY_INDEX](class_mesh.md#class_Mesh_constant_ARRAY_INDEX) if it is used. + +The `blend_shapes` argument is an array of vertex data for each blend shape. Each element is an array of the same structure as `arrays`, but [Mesh.ARRAY_VERTEX](class_mesh.md#class_Mesh_constant_ARRAY_VERTEX), [Mesh.ARRAY_NORMAL](class_mesh.md#class_Mesh_constant_ARRAY_NORMAL), and [Mesh.ARRAY_TANGENT](class_mesh.md#class_Mesh_constant_ARRAY_TANGENT) are set if and only if they are set in `arrays` and all other entries are ``null``. + +The `lods` argument is a dictionary with [float](class_float.md) keys and [PackedInt32Array](class_packedint32array.md) values. Each entry in the dictionary represents an LOD level of the surface, where the value is the [Mesh.ARRAY_INDEX](class_mesh.md#class_Mesh_constant_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 `flags` argument is the bitwise OR of, as required: One value of [ArrayCustomFormat](class_mesh.md#enum_Mesh_ArrayCustomFormat) left shifted by ``ARRAY_FORMAT_CUSTOMn_SHIFT`` for each custom channel in use, [Mesh.ARRAY_FLAG_USE_DYNAMIC_UPDATE](class_mesh.md#class_Mesh_constant_ARRAY_FLAG_USE_DYNAMIC_UPDATE), [Mesh.ARRAY_FLAG_USE_8_BONE_WEIGHTS](class_mesh.md#class_Mesh_constant_ARRAY_FLAG_USE_8_BONE_WEIGHTS), or [Mesh.ARRAY_FLAG_USES_EMPTY_VERTEX_ARRAY](class_mesh.md#class_Mesh_constant_ARRAY_FLAG_USES_EMPTY_VERTEX_ARRAY). + +\ **Note:** When using indices, it is recommended to only use points, lines, or triangles. + +
+ + + + + +`void` **clear_blend_shapes**\ (\ ) [🔗](#class_ArrayMesh_method_clear_blend_shapes) + +Removes all blend shapes from this **ArrayMesh**. + +
+ + + + + +`void` **clear_surfaces**\ (\ ) [🔗](#class_ArrayMesh_method_clear_surfaces) + +Removes all surfaces from this **ArrayMesh**. + +
+ + + + + +[int](class_int.md) **get_blend_shape_count**\ (\ ) const [🔗](#class_ArrayMesh_method_get_blend_shape_count) + +Returns the number of blend shapes that the **ArrayMesh** holds. + +
+ + + + + +[StringName](class_stringname.md) **get_blend_shape_name**\ (\ index\: [int](class_int.md)\ ) const [🔗](#class_ArrayMesh_method_get_blend_shape_name) + +Returns the name of the blend shape at this index. + +
+ + + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **lightmap_unwrap**\ (\ transform\: [Transform3D](class_transform3d.md), texel_size\: [float](class_float.md)\ ) [🔗](#class_ArrayMesh_method_lightmap_unwrap) + +Performs a UV unwrap on the **ArrayMesh** to prepare the mesh for lightmapping. + +
+ + + + + +`void` **regen_normal_maps**\ (\ ) [🔗](#class_ArrayMesh_method_regen_normal_maps) + +Regenerates tangents for each of the **ArrayMesh**'s surfaces. + +
+ + + + + +`void` **set_blend_shape_name**\ (\ index\: [int](class_int.md), name\: [StringName](class_stringname.md)\ ) [🔗](#class_ArrayMesh_method_set_blend_shape_name) + +Sets the name of the blend shape at this index. + +
+ + + + + +[int](class_int.md) **surface_find_by_name**\ (\ name\: [String](class_string.md)\ ) const [🔗](#class_ArrayMesh_method_surface_find_by_name) + +Returns the index of the first surface with this name held within this **ArrayMesh**. If none are found, -1 is returned. + +
+ + + + + +[int](class_int.md) **surface_get_array_index_len**\ (\ surf_idx\: [int](class_int.md)\ ) const [🔗](#class_ArrayMesh_method_surface_get_array_index_len) + +Returns the length in indices of the index array in the requested surface (see [add_surface_from_arrays()](class_arraymesh.md#class_ArrayMesh_method_add_surface_from_arrays)). + +
+ + + + + +[int](class_int.md) **surface_get_array_len**\ (\ surf_idx\: [int](class_int.md)\ ) const [🔗](#class_ArrayMesh_method_surface_get_array_len) + +Returns the length in vertices of the vertex array in the requested surface (see [add_surface_from_arrays()](class_arraymesh.md#class_ArrayMesh_method_add_surface_from_arrays)). + +
+ + + + + +**BitField**\[[ArrayFormat](class_mesh.md#enum_Mesh_ArrayFormat)\] **surface_get_format**\ (\ surf_idx\: [int](class_int.md)\ ) const [🔗](#class_ArrayMesh_method_surface_get_format) + +Returns the format mask of the requested surface (see [add_surface_from_arrays()](class_arraymesh.md#class_ArrayMesh_method_add_surface_from_arrays)). + +
+ + + + + +[String](class_string.md) **surface_get_name**\ (\ surf_idx\: [int](class_int.md)\ ) const [🔗](#class_ArrayMesh_method_surface_get_name) + +Gets the name assigned to this surface. + +
+ + + + + +[PrimitiveType](class_mesh.md#enum_Mesh_PrimitiveType) **surface_get_primitive_type**\ (\ surf_idx\: [int](class_int.md)\ ) const [🔗](#class_ArrayMesh_method_surface_get_primitive_type) + +Returns the primitive type of the requested surface (see [add_surface_from_arrays()](class_arraymesh.md#class_ArrayMesh_method_add_surface_from_arrays)). + +
+ + + + + +`void` **surface_remove**\ (\ surf_idx\: [int](class_int.md)\ ) [🔗](#class_ArrayMesh_method_surface_remove) + +Removes the surface at the given index from the Mesh, shifting surfaces with higher index down by one. + +
+ + + + + +`void` **surface_set_name**\ (\ surf_idx\: [int](class_int.md), name\: [String](class_string.md)\ ) [🔗](#class_ArrayMesh_method_surface_set_name) + +Sets a name for a given surface. + +
+ + + + + +`void` **surface_update_attribute_region**\ (\ surf_idx\: [int](class_int.md), offset\: [int](class_int.md), data\: [PackedByteArray](class_packedbytearray.md)\ ) [🔗](#class_ArrayMesh_method_surface_update_attribute_region) + +
+There is currently no description for this method. Please help us by contributing one! + +
+ +
+ + + + + +`void` **surface_update_skin_region**\ (\ surf_idx\: [int](class_int.md), offset\: [int](class_int.md), data\: [PackedByteArray](class_packedbytearray.md)\ ) [🔗](#class_ArrayMesh_method_surface_update_skin_region) + +
+There is currently no description for this method. Please help us by contributing one! + +
+ +
+ + + + + +`void` **surface_update_vertex_region**\ (\ surf_idx\: [int](class_int.md), offset\: [int](class_int.md), data\: [PackedByteArray](class_packedbytearray.md)\ ) [🔗](#class_ArrayMesh_method_surface_update_vertex_region) + +
+There is currently no description for this method. Please help us by contributing one! + +
+ diff --git a/docs/Classes/class_arrayoccluder3d.md b/docs/Classes/class_arrayoccluder3d.md new file mode 100644 index 00000000..1ee3a0e4 --- /dev/null +++ b/docs/Classes/class_arrayoccluder3d.md @@ -0,0 +1,121 @@ + + + + + + + + + +# ArrayOccluder3D + +**Inherits:** [Occluder3D](class_occluder3d.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +3D polygon shape for use with occlusion culling in [OccluderInstance3D](class_occluderinstance3d.md). + + + +## Description + +**ArrayOccluder3D** stores an arbitrary 3D polygon shape that can be used by the engine's occlusion culling system. This is analogous to [ArrayMesh](class_arraymesh.md), but for occluders. + +See [OccluderInstance3D](class_occluderinstance3d.md)'s documentation for instructions on setting up occlusion culling. + + + +## Tutorials + +- [Occlusion culling](../tutorials/3d/occlusion_culling.md) + + + +## Properties + + + + + + + + + + + + + + + + +
[PackedInt32Array](class_packedint32array.md)[indices](#class_ArrayOccluder3D_property_indices)`PackedInt32Array()`
[PackedVector3Array](class_packedvector3array.md)[vertices](#class_ArrayOccluder3D_property_vertices)`PackedVector3Array()`
+ + + +## Methods + + + + + + + + + + +
`void`[set_arrays](#class_ArrayOccluder3D_method_set_arrays)\ (\ vertices\: [PackedVector3Array](class_packedvector3array.md), indices\: [PackedInt32Array](class_packedint32array.md)\ )
+ +
+ + + +## Property Descriptions + + + + + +[PackedInt32Array](class_packedint32array.md) **indices** = `PackedInt32Array()` [🔗](#class_ArrayOccluder3D_property_indices) + + + +- `void` **set_indices**\ (\ value\: [PackedInt32Array](class_packedint32array.md)\ ) +- [PackedInt32Array](class_packedint32array.md) **get_indices**\ (\ ) + +The occluder's index position. Indices determine which points from the [vertices](class_arrayoccluder3d.md#class_ArrayOccluder3D_property_vertices) array should be drawn, and in which order. + +\ **Note:** The occluder is always updated after setting this value. If creating occluders procedurally, consider using [set_arrays()](class_arrayoccluder3d.md#class_ArrayOccluder3D_method_set_arrays) instead to avoid updating the occluder twice when it's created. + +**Note:** The returned array is *copied* and any changes to it will not update the original property value. See [PackedInt32Array](class_packedint32array.md) for more details. + +
+ + + + + +[PackedVector3Array](class_packedvector3array.md) **vertices** = `PackedVector3Array()` [🔗](#class_ArrayOccluder3D_property_vertices) + + + +- `void` **set_vertices**\ (\ value\: [PackedVector3Array](class_packedvector3array.md)\ ) +- [PackedVector3Array](class_packedvector3array.md) **get_vertices**\ (\ ) + +The occluder's vertex positions in local 3D coordinates. + +\ **Note:** The occluder is always updated after setting this value. If creating occluders procedurally, consider using [set_arrays()](class_arrayoccluder3d.md#class_ArrayOccluder3D_method_set_arrays) instead to avoid updating the occluder twice when it's created. + +**Note:** The returned array is *copied* and any changes to it will not update the original property value. See [PackedVector3Array](class_packedvector3array.md) for more details. + +
+ + + +## Method Descriptions + + + + + +`void` **set_arrays**\ (\ vertices\: [PackedVector3Array](class_packedvector3array.md), indices\: [PackedInt32Array](class_packedint32array.md)\ ) [🔗](#class_ArrayOccluder3D_method_set_arrays) + +Sets [indices](class_arrayoccluder3d.md#class_ArrayOccluder3D_property_indices) and [vertices](class_arrayoccluder3d.md#class_ArrayOccluder3D_property_vertices), while updating the final occluder only once after both values are set. + diff --git a/docs/Classes/class_aspectratiocontainer.md b/docs/Classes/class_aspectratiocontainer.md new file mode 100644 index 00000000..7c89503f --- /dev/null +++ b/docs/Classes/class_aspectratiocontainer.md @@ -0,0 +1,186 @@ + + + + + + + + + +# AspectRatioContainer + +**Inherits:** [Container](class_container.md) **<** [Control](class_control.md) **<** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +A container that preserves the proportions of its child controls. + + + +## 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. + + + +## Tutorials + +- [Using Containers](../tutorials/ui/gui_containers.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + +
[AlignmentMode](class_aspectratiocontainer.md#enum_AspectRatioContainer_AlignmentMode)[alignment_horizontal](#class_AspectRatioContainer_property_alignment_horizontal)`1`
[AlignmentMode](class_aspectratiocontainer.md#enum_AspectRatioContainer_AlignmentMode)[alignment_vertical](#class_AspectRatioContainer_property_alignment_vertical)`1`
[float](class_float.md)[ratio](#class_AspectRatioContainer_property_ratio)`1.0`
[StretchMode](class_aspectratiocontainer.md#enum_AspectRatioContainer_StretchMode)[stretch_mode](#class_AspectRatioContainer_property_stretch_mode)`2`
+ +
+ + + +## Enumerations + + + + + +enum **StretchMode**: [🔗](#enum_AspectRatioContainer_StretchMode) + + + + + +[StretchMode](class_aspectratiocontainer.md#enum_AspectRatioContainer_StretchMode) **STRETCH_WIDTH_CONTROLS_HEIGHT** = `0` + +The height of child controls is automatically adjusted based on the width of the container. + + + +[StretchMode](class_aspectratiocontainer.md#enum_AspectRatioContainer_StretchMode) **STRETCH_HEIGHT_CONTROLS_WIDTH** = `1` + +The width of child controls is automatically adjusted based on the height of the container. + + + +[StretchMode](class_aspectratiocontainer.md#enum_AspectRatioContainer_StretchMode) **STRETCH_FIT** = `2` + +The bounding rectangle of child controls is automatically adjusted to fit inside the container while keeping the aspect ratio. + + + +[StretchMode](class_aspectratiocontainer.md#enum_AspectRatioContainer_StretchMode) **STRETCH_COVER** = `3` + +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 [Control.clip_contents](class_control.md#class_Control_property_clip_contents) is enabled, this allows to show only the container's area restricted by its own bounding rectangle.
+ + + + + +enum **AlignmentMode**: [🔗](#enum_AspectRatioContainer_AlignmentMode) + + + + + +[AlignmentMode](class_aspectratiocontainer.md#enum_AspectRatioContainer_AlignmentMode) **ALIGNMENT_BEGIN** = `0` + +Aligns child controls with the beginning (left or top) of the container. + + + +[AlignmentMode](class_aspectratiocontainer.md#enum_AspectRatioContainer_AlignmentMode) **ALIGNMENT_CENTER** = `1` + +Aligns child controls with the center of the container. + + + +[AlignmentMode](class_aspectratiocontainer.md#enum_AspectRatioContainer_AlignmentMode) **ALIGNMENT_END** = `2` + +Aligns child controls with the end (right or bottom) of the container.
+ + + +## Property Descriptions + + + + + +[AlignmentMode](class_aspectratiocontainer.md#enum_AspectRatioContainer_AlignmentMode) **alignment_horizontal** = `1` [🔗](#class_AspectRatioContainer_property_alignment_horizontal) + + + +- `void` **set_alignment_horizontal**\ (\ value\: [AlignmentMode](class_aspectratiocontainer.md#enum_AspectRatioContainer_AlignmentMode)\ ) +- [AlignmentMode](class_aspectratiocontainer.md#enum_AspectRatioContainer_AlignmentMode) **get_alignment_horizontal**\ (\ ) + +Specifies the horizontal relative position of child controls. + +
+ + + + + +[AlignmentMode](class_aspectratiocontainer.md#enum_AspectRatioContainer_AlignmentMode) **alignment_vertical** = `1` [🔗](#class_AspectRatioContainer_property_alignment_vertical) + + + +- `void` **set_alignment_vertical**\ (\ value\: [AlignmentMode](class_aspectratiocontainer.md#enum_AspectRatioContainer_AlignmentMode)\ ) +- [AlignmentMode](class_aspectratiocontainer.md#enum_AspectRatioContainer_AlignmentMode) **get_alignment_vertical**\ (\ ) + +Specifies the vertical relative position of child controls. + +
+ + + + + +[float](class_float.md) **ratio** = `1.0` [🔗](#class_AspectRatioContainer_property_ratio) + + + +- `void` **set_ratio**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_ratio**\ (\ ) + +The aspect ratio to enforce on child controls. This is the width divided by the height. The ratio depends on the [stretch_mode](class_aspectratiocontainer.md#class_AspectRatioContainer_property_stretch_mode). + +
+ + + + + +[StretchMode](class_aspectratiocontainer.md#enum_AspectRatioContainer_StretchMode) **stretch_mode** = `2` [🔗](#class_AspectRatioContainer_property_stretch_mode) + + + +- `void` **set_stretch_mode**\ (\ value\: [StretchMode](class_aspectratiocontainer.md#enum_AspectRatioContainer_StretchMode)\ ) +- [StretchMode](class_aspectratiocontainer.md#enum_AspectRatioContainer_StretchMode) **get_stretch_mode**\ (\ ) + +The stretch mode used to align child controls. + diff --git a/docs/Classes/class_astar2d.md b/docs/Classes/class_astar2d.md new file mode 100644 index 00000000..998f8a2a --- /dev/null +++ b/docs/Classes/class_astar2d.md @@ -0,0 +1,589 @@ + + + + + + + + + +# AStar2D + +**Inherits:** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +An implementation of A\* for finding the shortest path between two vertices on a connected graph in 2D space. + + + +## 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](class_astar3d.md) for a more thorough explanation on how to use this class. **AStar2D** is a wrapper for [AStar3D](class_astar3d.md) that enforces 2D coordinates. + + + +## Tutorials + +- [Grid-based Navigation with AStarGrid2D Demo](https://godotengine.org/asset-library/asset/2723) + + + +## Properties + + + + + + + + + + + +
[bool](class_bool.md)[neighbor_filter_enabled](#class_AStar2D_property_neighbor_filter_enabled)`false`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[_compute_cost](#class_AStar2D_private_method__compute_cost)\ (\ from_id\: [int](class_int.md), to_id\: [int](class_int.md)\ ) virtual const
[float](class_float.md)[_estimate_cost](#class_AStar2D_private_method__estimate_cost)\ (\ from_id\: [int](class_int.md), end_id\: [int](class_int.md)\ ) virtual const
[bool](class_bool.md)[_filter_neighbor](#class_AStar2D_private_method__filter_neighbor)\ (\ from_id\: [int](class_int.md), neighbor_id\: [int](class_int.md)\ ) virtual const
`void`[add_point](#class_AStar2D_method_add_point)\ (\ id\: [int](class_int.md), position\: [Vector2](class_vector2.md), weight_scale\: [float](class_float.md) = 1.0\ )
[bool](class_bool.md)[are_points_connected](#class_AStar2D_method_are_points_connected)\ (\ id\: [int](class_int.md), to_id\: [int](class_int.md), bidirectional\: [bool](class_bool.md) = true\ ) const
`void`[clear](#class_AStar2D_method_clear)\ (\ )
`void`[connect_points](#class_AStar2D_method_connect_points)\ (\ id\: [int](class_int.md), to_id\: [int](class_int.md), bidirectional\: [bool](class_bool.md) = true\ )
`void`[disconnect_points](#class_AStar2D_method_disconnect_points)\ (\ id\: [int](class_int.md), to_id\: [int](class_int.md), bidirectional\: [bool](class_bool.md) = true\ )
[int](class_int.md)[get_available_point_id](#class_AStar2D_method_get_available_point_id)\ (\ ) const
[int](class_int.md)[get_closest_point](#class_AStar2D_method_get_closest_point)\ (\ to_position\: [Vector2](class_vector2.md), include_disabled\: [bool](class_bool.md) = false\ ) const
[Vector2](class_vector2.md)[get_closest_position_in_segment](#class_AStar2D_method_get_closest_position_in_segment)\ (\ to_position\: [Vector2](class_vector2.md)\ ) const
[PackedInt64Array](class_packedint64array.md)[get_id_path](#class_AStar2D_method_get_id_path)\ (\ from_id\: [int](class_int.md), to_id\: [int](class_int.md), allow_partial_path\: [bool](class_bool.md) = false\ )
[int](class_int.md)[get_point_capacity](#class_AStar2D_method_get_point_capacity)\ (\ ) const
[PackedInt64Array](class_packedint64array.md)[get_point_connections](#class_AStar2D_method_get_point_connections)\ (\ id\: [int](class_int.md)\ )
[int](class_int.md)[get_point_count](#class_AStar2D_method_get_point_count)\ (\ ) const
[PackedInt64Array](class_packedint64array.md)[get_point_ids](#class_AStar2D_method_get_point_ids)\ (\ )
[PackedVector2Array](class_packedvector2array.md)[get_point_path](#class_AStar2D_method_get_point_path)\ (\ from_id\: [int](class_int.md), to_id\: [int](class_int.md), allow_partial_path\: [bool](class_bool.md) = false\ )
[Vector2](class_vector2.md)[get_point_position](#class_AStar2D_method_get_point_position)\ (\ id\: [int](class_int.md)\ ) const
[float](class_float.md)[get_point_weight_scale](#class_AStar2D_method_get_point_weight_scale)\ (\ id\: [int](class_int.md)\ ) const
[bool](class_bool.md)[has_point](#class_AStar2D_method_has_point)\ (\ id\: [int](class_int.md)\ ) const
[bool](class_bool.md)[is_point_disabled](#class_AStar2D_method_is_point_disabled)\ (\ id\: [int](class_int.md)\ ) const
`void`[remove_point](#class_AStar2D_method_remove_point)\ (\ id\: [int](class_int.md)\ )
`void`[reserve_space](#class_AStar2D_method_reserve_space)\ (\ num_nodes\: [int](class_int.md)\ )
`void`[set_point_disabled](#class_AStar2D_method_set_point_disabled)\ (\ id\: [int](class_int.md), disabled\: [bool](class_bool.md) = true\ )
`void`[set_point_position](#class_AStar2D_method_set_point_position)\ (\ id\: [int](class_int.md), position\: [Vector2](class_vector2.md)\ )
`void`[set_point_weight_scale](#class_AStar2D_method_set_point_weight_scale)\ (\ id\: [int](class_int.md), weight_scale\: [float](class_float.md)\ )
+ +
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **neighbor_filter_enabled** = `false` [🔗](#class_AStar2D_property_neighbor_filter_enabled) + + + +- `void` **set_neighbor_filter_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_neighbor_filter_enabled**\ (\ ) + +If ``true`` enables the filtering of neighbors via [_filter_neighbor()](class_astar2d.md#class_AStar2D_private_method__filter_neighbor). + +
+ + + +## Method Descriptions + + + + + +[float](class_float.md) **_compute_cost**\ (\ from_id\: [int](class_int.md), to_id\: [int](class_int.md)\ ) virtual const [🔗](#class_AStar2D_private_method__compute_cost) + +Called when computing the cost between two connected points. + +Note that this function is hidden in the default **AStar2D** class. + +
+ + + + + +[float](class_float.md) **_estimate_cost**\ (\ from_id\: [int](class_int.md), end_id\: [int](class_int.md)\ ) virtual const [🔗](#class_AStar2D_private_method__estimate_cost) + +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. + +
+ + + + + +[bool](class_bool.md) **_filter_neighbor**\ (\ from_id\: [int](class_int.md), neighbor_id\: [int](class_int.md)\ ) virtual const [🔗](#class_AStar2D_private_method__filter_neighbor) + +Called when neighboring enters processing and if [neighbor_filter_enabled](class_astar2d.md#class_AStar2D_property_neighbor_filter_enabled) is ``true``. If ``true`` is returned the point will not be processed. + +Note that this function is hidden in the default **AStar2D** class. + +
+ + + + + +`void` **add_point**\ (\ id\: [int](class_int.md), position\: [Vector2](class_vector2.md), weight_scale\: [float](class_float.md) = 1.0\ ) [🔗](#class_AStar2D_method_add_point) + +Adds a new point at the given position with the given identifier. The `id` must be 0 or larger, and the `weight_scale` must be 0.0 or greater. + +The `weight_scale` is multiplied by the result of [_compute_cost()](class_astar2d.md#class_AStar2D_private_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 `weight_scale`\ s to form a path. + + + + +```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 +``` + +```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 +``` + + + +If there already exists a point for the given `id`, its position and weight scale are updated to the given values. + +
+ + + + + +[bool](class_bool.md) **are_points_connected**\ (\ id\: [int](class_int.md), to_id\: [int](class_int.md), bidirectional\: [bool](class_bool.md) = true\ ) const [🔗](#class_AStar2D_method_are_points_connected) + +Returns whether there is a connection/segment between the given points. If `bidirectional` is ``false``, returns whether movement from `id` to `to_id` is possible through this segment. + +
+ + + + + +`void` **clear**\ (\ ) [🔗](#class_AStar2D_method_clear) + +Clears all the points and segments. + +
+ + + + + +`void` **connect_points**\ (\ id\: [int](class_int.md), to_id\: [int](class_int.md), bidirectional\: [bool](class_bool.md) = true\ ) [🔗](#class_AStar2D_method_connect_points) + +Creates a segment between the given points. If `bidirectional` is ``false``, only movement from `id` to `to_id` is allowed, not the reverse direction. + + + + +```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) +``` + +```csharp + var astar = new AStar2D(); + astar.AddPoint(1, new Vector2(1, 1)); + astar.AddPoint(2, new Vector2(0, 5)); + astar.ConnectPoints(1, 2, false); +``` + + + +
+ + + + + +`void` **disconnect_points**\ (\ id\: [int](class_int.md), to_id\: [int](class_int.md), bidirectional\: [bool](class_bool.md) = true\ ) [🔗](#class_AStar2D_method_disconnect_points) + +Deletes the segment between the given points. If `bidirectional` is ``false``, only movement from `id` to `to_id` is prevented, and a unidirectional segment possibly remains. + +
+ + + + + +[int](class_int.md) **get_available_point_id**\ (\ ) const [🔗](#class_AStar2D_method_get_available_point_id) + +Returns the next available point ID with no point associated to it. + +
+ + + + + +[int](class_int.md) **get_closest_point**\ (\ to_position\: [Vector2](class_vector2.md), include_disabled\: [bool](class_bool.md) = false\ ) const [🔗](#class_AStar2D_method_get_closest_point) + +Returns the ID of the closest point to `to_position`, optionally taking disabled points into account. Returns ``-1`` if there are no points in the points pool. + +\ **Note:** If several points are the closest to `to_position`, the one with the smallest ID will be returned, ensuring a deterministic result. + +
+ + + + + +[Vector2](class_vector2.md) **get_closest_position_in_segment**\ (\ to_position\: [Vector2](class_vector2.md)\ ) const [🔗](#class_AStar2D_method_get_closest_position_in_segment) + +Returns the closest position to `to_position` that resides inside a segment between two connected points. + + + + +```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) +``` + +```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) +``` + + + +The result is in the segment that goes from ``y = 0`` to ``y = 5``. It's the closest position in the segment to the given point. + +
+ + + + + +[PackedInt64Array](class_packedint64array.md) **get_id_path**\ (\ from_id\: [int](class_int.md), to_id\: [int](class_int.md), allow_partial_path\: [bool](class_bool.md) = false\ ) [🔗](#class_AStar2D_method_get_id_path) + +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 `allow_partial_path` is ``true``, returns a path to the point closest to the target that can be reached. + +\ **Note:** When `allow_partial_path` is ``true`` and `to_id` is disabled the search may take an unusually long time to finish. + + + + +```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] +``` + +```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] +``` + + + +If you change the 2nd point's weight to 3, then the result will be ``[1, 4, 3]`` instead, because now even though the distance is longer, it's "easier" to get through point 4 than through point 2. + +
+ + + + + +[int](class_int.md) **get_point_capacity**\ (\ ) const [🔗](#class_AStar2D_method_get_point_capacity) + +Returns the capacity of the structure backing the points, useful in conjunction with [reserve_space()](class_astar2d.md#class_AStar2D_method_reserve_space). + +
+ + + + + +[PackedInt64Array](class_packedint64array.md) **get_point_connections**\ (\ id\: [int](class_int.md)\ ) [🔗](#class_AStar2D_method_get_point_connections) + +Returns an array with the IDs of the points that form the connection with the given point. + + + + +```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] +``` + +```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] +``` + + + +
+ + + + + +[int](class_int.md) **get_point_count**\ (\ ) const [🔗](#class_AStar2D_method_get_point_count) + +Returns the number of points currently in the points pool. + +
+ + + + + +[PackedInt64Array](class_packedint64array.md) **get_point_ids**\ (\ ) [🔗](#class_AStar2D_method_get_point_ids) + +Returns an array of all point IDs. + +
+ + + + + +[PackedVector2Array](class_packedvector2array.md) **get_point_path**\ (\ from_id\: [int](class_int.md), to_id\: [int](class_int.md), allow_partial_path\: [bool](class_bool.md) = false\ ) [🔗](#class_AStar2D_method_get_point_path) + +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 `allow_partial_path` is ``true``, returns a path to the point closest to the target that can be reached. + +\ **Note:** This method is not thread-safe; it can only be used from a single [Thread](class_thread.md) at a given time. Consider using [Mutex](class_mutex.md) to ensure exclusive access to one thread to avoid race conditions. + +Additionally, when `allow_partial_path` is ``true`` and `to_id` is disabled the search may take an unusually long time to finish. + +
+ + + + + +[Vector2](class_vector2.md) **get_point_position**\ (\ id\: [int](class_int.md)\ ) const [🔗](#class_AStar2D_method_get_point_position) + +Returns the position of the point associated with the given `id`. + +
+ + + + + +[float](class_float.md) **get_point_weight_scale**\ (\ id\: [int](class_int.md)\ ) const [🔗](#class_AStar2D_method_get_point_weight_scale) + +Returns the weight scale of the point associated with the given `id`. + +
+ + + + + +[bool](class_bool.md) **has_point**\ (\ id\: [int](class_int.md)\ ) const [🔗](#class_AStar2D_method_has_point) + +Returns whether a point associated with the given `id` exists. + +
+ + + + + +[bool](class_bool.md) **is_point_disabled**\ (\ id\: [int](class_int.md)\ ) const [🔗](#class_AStar2D_method_is_point_disabled) + +Returns whether a point is disabled or not for pathfinding. By default, all points are enabled. + +
+ + + + + +`void` **remove_point**\ (\ id\: [int](class_int.md)\ ) [🔗](#class_AStar2D_method_remove_point) + +Removes the point associated with the given `id` from the points pool. + +
+ + + + + +`void` **reserve_space**\ (\ num_nodes\: [int](class_int.md)\ ) [🔗](#class_AStar2D_method_reserve_space) + +Reserves space internally for `num_nodes` points. Useful if you're adding a known large number of points at once, such as points on a grid. + +
+ + + + + +`void` **set_point_disabled**\ (\ id\: [int](class_int.md), disabled\: [bool](class_bool.md) = true\ ) [🔗](#class_AStar2D_method_set_point_disabled) + +Disables or enables the specified point for pathfinding. Useful for making a temporary obstacle. + +
+ + + + + +`void` **set_point_position**\ (\ id\: [int](class_int.md), position\: [Vector2](class_vector2.md)\ ) [🔗](#class_AStar2D_method_set_point_position) + +Sets the `position` for the point with the given `id`. + +
+ + + + + +`void` **set_point_weight_scale**\ (\ id\: [int](class_int.md), weight_scale\: [float](class_float.md)\ ) [🔗](#class_AStar2D_method_set_point_weight_scale) + +Sets the `weight_scale` for the point with the given `id`. The `weight_scale` is multiplied by the result of [_compute_cost()](class_astar2d.md#class_AStar2D_private_method__compute_cost) when determining the overall cost of traveling across a segment from a neighboring point to this point. + diff --git a/docs/Classes/class_astar3d.md b/docs/Classes/class_astar3d.md new file mode 100644 index 00000000..97228cd4 --- /dev/null +++ b/docs/Classes/class_astar3d.md @@ -0,0 +1,632 @@ + + + + + + + + + +# AStar3D + +**Inherits:** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +An implementation of A\* for finding the shortest path between two vertices on a connected graph in 3D space. + + + +## 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. Redot's A\* implementation uses points in 3D space and Euclidean distances by default. + +You must add points manually with [add_point()](class_astar3d.md#class_AStar3D_method_add_point) and create segments manually with [connect_points()](class_astar3d.md#class_AStar3D_method_connect_points). Once done, you can test if there is a path between two points with the [are_points_connected()](class_astar3d.md#class_AStar3D_method_are_points_connected) function, get a path containing indices by [get_id_path()](class_astar3d.md#class_AStar3D_method_get_id_path), or one containing actual coordinates with [get_point_path()](class_astar3d.md#class_AStar3D_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 [_compute_cost()](class_astar3d.md#class_AStar3D_private_method__compute_cost) and [_estimate_cost()](class_astar3d.md#class_AStar3D_private_method__estimate_cost). Both should take two point IDs and return the distance between the corresponding points. + +\ **Example:** Use Manhattan distance instead of Euclidean distance: + + + + +```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) +``` + +```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); + } + } +``` + + + +\ [_estimate_cost()](class_astar3d.md#class_AStar3D_private_method__estimate_cost) should return a lower bound of the distance, i.e. ``_estimate_cost(u, v) <= _compute_cost(u, v)``. This serves as a hint to the algorithm because the custom [_compute_cost()](class_astar3d.md#class_AStar3D_private_method__compute_cost) might be computation-heavy. If this is not the case, make [_estimate_cost()](class_astar3d.md#class_AStar3D_private_method__estimate_cost) return the same value as [_compute_cost()](class_astar3d.md#class_AStar3D_private_method__compute_cost) to provide the algorithm with the most accurate information. + +If the default [_estimate_cost()](class_astar3d.md#class_AStar3D_private_method__estimate_cost) and [_compute_cost()](class_astar3d.md#class_AStar3D_private_method__compute_cost) methods are used, or if the supplied [_estimate_cost()](class_astar3d.md#class_AStar3D_private_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 [_compute_cost()](class_astar3d.md#class_AStar3D_private_method__compute_cost) results of all segments in the path multiplied by the ``weight_scale``\ s of the endpoints of the respective segments. If the default methods are used and the ``weight_scale``\ s of all points are set to ``1.0``, then this equals the sum of Euclidean distances of all segments in the path. + + + +## Properties + + + + + + + + + + + +
[bool](class_bool.md)[neighbor_filter_enabled](#class_AStar3D_property_neighbor_filter_enabled)`false`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[_compute_cost](#class_AStar3D_private_method__compute_cost)\ (\ from_id\: [int](class_int.md), to_id\: [int](class_int.md)\ ) virtual const
[float](class_float.md)[_estimate_cost](#class_AStar3D_private_method__estimate_cost)\ (\ from_id\: [int](class_int.md), end_id\: [int](class_int.md)\ ) virtual const
[bool](class_bool.md)[_filter_neighbor](#class_AStar3D_private_method__filter_neighbor)\ (\ from_id\: [int](class_int.md), neighbor_id\: [int](class_int.md)\ ) virtual const
`void`[add_point](#class_AStar3D_method_add_point)\ (\ id\: [int](class_int.md), position\: [Vector3](class_vector3.md), weight_scale\: [float](class_float.md) = 1.0\ )
[bool](class_bool.md)[are_points_connected](#class_AStar3D_method_are_points_connected)\ (\ id\: [int](class_int.md), to_id\: [int](class_int.md), bidirectional\: [bool](class_bool.md) = true\ ) const
`void`[clear](#class_AStar3D_method_clear)\ (\ )
`void`[connect_points](#class_AStar3D_method_connect_points)\ (\ id\: [int](class_int.md), to_id\: [int](class_int.md), bidirectional\: [bool](class_bool.md) = true\ )
`void`[disconnect_points](#class_AStar3D_method_disconnect_points)\ (\ id\: [int](class_int.md), to_id\: [int](class_int.md), bidirectional\: [bool](class_bool.md) = true\ )
[int](class_int.md)[get_available_point_id](#class_AStar3D_method_get_available_point_id)\ (\ ) const
[int](class_int.md)[get_closest_point](#class_AStar3D_method_get_closest_point)\ (\ to_position\: [Vector3](class_vector3.md), include_disabled\: [bool](class_bool.md) = false\ ) const
[Vector3](class_vector3.md)[get_closest_position_in_segment](#class_AStar3D_method_get_closest_position_in_segment)\ (\ to_position\: [Vector3](class_vector3.md)\ ) const
[PackedInt64Array](class_packedint64array.md)[get_id_path](#class_AStar3D_method_get_id_path)\ (\ from_id\: [int](class_int.md), to_id\: [int](class_int.md), allow_partial_path\: [bool](class_bool.md) = false\ )
[int](class_int.md)[get_point_capacity](#class_AStar3D_method_get_point_capacity)\ (\ ) const
[PackedInt64Array](class_packedint64array.md)[get_point_connections](#class_AStar3D_method_get_point_connections)\ (\ id\: [int](class_int.md)\ )
[int](class_int.md)[get_point_count](#class_AStar3D_method_get_point_count)\ (\ ) const
[PackedInt64Array](class_packedint64array.md)[get_point_ids](#class_AStar3D_method_get_point_ids)\ (\ )
[PackedVector3Array](class_packedvector3array.md)[get_point_path](#class_AStar3D_method_get_point_path)\ (\ from_id\: [int](class_int.md), to_id\: [int](class_int.md), allow_partial_path\: [bool](class_bool.md) = false\ )
[Vector3](class_vector3.md)[get_point_position](#class_AStar3D_method_get_point_position)\ (\ id\: [int](class_int.md)\ ) const
[float](class_float.md)[get_point_weight_scale](#class_AStar3D_method_get_point_weight_scale)\ (\ id\: [int](class_int.md)\ ) const
[bool](class_bool.md)[has_point](#class_AStar3D_method_has_point)\ (\ id\: [int](class_int.md)\ ) const
[bool](class_bool.md)[is_point_disabled](#class_AStar3D_method_is_point_disabled)\ (\ id\: [int](class_int.md)\ ) const
`void`[remove_point](#class_AStar3D_method_remove_point)\ (\ id\: [int](class_int.md)\ )
`void`[reserve_space](#class_AStar3D_method_reserve_space)\ (\ num_nodes\: [int](class_int.md)\ )
`void`[set_point_disabled](#class_AStar3D_method_set_point_disabled)\ (\ id\: [int](class_int.md), disabled\: [bool](class_bool.md) = true\ )
`void`[set_point_position](#class_AStar3D_method_set_point_position)\ (\ id\: [int](class_int.md), position\: [Vector3](class_vector3.md)\ )
`void`[set_point_weight_scale](#class_AStar3D_method_set_point_weight_scale)\ (\ id\: [int](class_int.md), weight_scale\: [float](class_float.md)\ )
+ +
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **neighbor_filter_enabled** = `false` [🔗](#class_AStar3D_property_neighbor_filter_enabled) + + + +- `void` **set_neighbor_filter_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_neighbor_filter_enabled**\ (\ ) + +If ``true`` enables the filtering of neighbors via [_filter_neighbor()](class_astar3d.md#class_AStar3D_private_method__filter_neighbor). + +
+ + + +## Method Descriptions + + + + + +[float](class_float.md) **_compute_cost**\ (\ from_id\: [int](class_int.md), to_id\: [int](class_int.md)\ ) virtual const [🔗](#class_AStar3D_private_method__compute_cost) + +Called when computing the cost between two connected points. + +Note that this function is hidden in the default **AStar3D** class. + +
+ + + + + +[float](class_float.md) **_estimate_cost**\ (\ from_id\: [int](class_int.md), end_id\: [int](class_int.md)\ ) virtual const [🔗](#class_AStar3D_private_method__estimate_cost) + +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. + +
+ + + + + +[bool](class_bool.md) **_filter_neighbor**\ (\ from_id\: [int](class_int.md), neighbor_id\: [int](class_int.md)\ ) virtual const [🔗](#class_AStar3D_private_method__filter_neighbor) + +Called when neighboring point enters processing and if [neighbor_filter_enabled](class_astar3d.md#class_AStar3D_property_neighbor_filter_enabled) is ``true``. If ``true`` is returned the point will not be processed. + +Note that this function is hidden in the default **AStar3D** class. + +
+ + + + + +`void` **add_point**\ (\ id\: [int](class_int.md), position\: [Vector3](class_vector3.md), weight_scale\: [float](class_float.md) = 1.0\ ) [🔗](#class_AStar3D_method_add_point) + +Adds a new point at the given position with the given identifier. The `id` must be 0 or larger, and the `weight_scale` must be 0.0 or greater. + +The `weight_scale` is multiplied by the result of [_compute_cost()](class_astar3d.md#class_AStar3D_private_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 `weight_scale`\ s to form a path. + + + + +```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 +``` + +```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 +``` + + + +If there already exists a point for the given `id`, its position and weight scale are updated to the given values. + +
+ + + + + +[bool](class_bool.md) **are_points_connected**\ (\ id\: [int](class_int.md), to_id\: [int](class_int.md), bidirectional\: [bool](class_bool.md) = true\ ) const [🔗](#class_AStar3D_method_are_points_connected) + +Returns whether the two given points are directly connected by a segment. If `bidirectional` is ``false``, returns whether movement from `id` to `to_id` is possible through this segment. + +
+ + + + + +`void` **clear**\ (\ ) [🔗](#class_AStar3D_method_clear) + +Clears all the points and segments. + +
+ + + + + +`void` **connect_points**\ (\ id\: [int](class_int.md), to_id\: [int](class_int.md), bidirectional\: [bool](class_bool.md) = true\ ) [🔗](#class_AStar3D_method_connect_points) + +Creates a segment between the given points. If `bidirectional` is ``false``, only movement from `id` to `to_id` is allowed, not the reverse direction. + + + + +```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) +``` + +```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); +``` + + + +
+ + + + + +`void` **disconnect_points**\ (\ id\: [int](class_int.md), to_id\: [int](class_int.md), bidirectional\: [bool](class_bool.md) = true\ ) [🔗](#class_AStar3D_method_disconnect_points) + +Deletes the segment between the given points. If `bidirectional` is ``false``, only movement from `id` to `to_id` is prevented, and a unidirectional segment possibly remains. + +
+ + + + + +[int](class_int.md) **get_available_point_id**\ (\ ) const [🔗](#class_AStar3D_method_get_available_point_id) + +Returns the next available point ID with no point associated to it. + +
+ + + + + +[int](class_int.md) **get_closest_point**\ (\ to_position\: [Vector3](class_vector3.md), include_disabled\: [bool](class_bool.md) = false\ ) const [🔗](#class_AStar3D_method_get_closest_point) + +Returns the ID of the closest point to `to_position`, optionally taking disabled points into account. Returns ``-1`` if there are no points in the points pool. + +\ **Note:** If several points are the closest to `to_position`, the one with the smallest ID will be returned, ensuring a deterministic result. + +
+ + + + + +[Vector3](class_vector3.md) **get_closest_position_in_segment**\ (\ to_position\: [Vector3](class_vector3.md)\ ) const [🔗](#class_AStar3D_method_get_closest_position_in_segment) + +Returns the closest position to `to_position` that resides inside a segment between two connected points. + + + + +```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) +``` + +```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) +``` + + + +The result is in the segment that goes from ``y = 0`` to ``y = 5``. It's the closest position in the segment to the given point. + +
+ + + + + +[PackedInt64Array](class_packedint64array.md) **get_id_path**\ (\ from_id\: [int](class_int.md), to_id\: [int](class_int.md), allow_partial_path\: [bool](class_bool.md) = false\ ) [🔗](#class_AStar3D_method_get_id_path) + +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 `allow_partial_path` is ``true``, returns a path to the point closest to the target that can be reached. + +\ **Note:** When `allow_partial_path` is ``true`` and `to_id` is disabled the search may take an unusually long time to finish. + + + + +```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] +``` + +```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] +``` + + + +If you change the 2nd point's weight to 3, then the result will be ``[1, 4, 3]`` instead, because now even though the distance is longer, it's "easier" to get through point 4 than through point 2. + +
+ + + + + +[int](class_int.md) **get_point_capacity**\ (\ ) const [🔗](#class_AStar3D_method_get_point_capacity) + +Returns the capacity of the structure backing the points, useful in conjunction with [reserve_space()](class_astar3d.md#class_AStar3D_method_reserve_space). + +
+ + + + + +[PackedInt64Array](class_packedint64array.md) **get_point_connections**\ (\ id\: [int](class_int.md)\ ) [🔗](#class_AStar3D_method_get_point_connections) + +Returns an array with the IDs of the points that form the connection with the given point. + + + + +```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] +``` + +```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] +``` + + + +
+ + + + + +[int](class_int.md) **get_point_count**\ (\ ) const [🔗](#class_AStar3D_method_get_point_count) + +Returns the number of points currently in the points pool. + +
+ + + + + +[PackedInt64Array](class_packedint64array.md) **get_point_ids**\ (\ ) [🔗](#class_AStar3D_method_get_point_ids) + +Returns an array of all point IDs. + +
+ + + + + +[PackedVector3Array](class_packedvector3array.md) **get_point_path**\ (\ from_id\: [int](class_int.md), to_id\: [int](class_int.md), allow_partial_path\: [bool](class_bool.md) = false\ ) [🔗](#class_AStar3D_method_get_point_path) + +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 `allow_partial_path` is ``true``, returns a path to the point closest to the target that can be reached. + +\ **Note:** This method is not thread-safe; it can only be used from a single [Thread](class_thread.md) at a given time. Consider using [Mutex](class_mutex.md) to ensure exclusive access to one thread to avoid race conditions. + +Additionally, when `allow_partial_path` is ``true`` and `to_id` is disabled the search may take an unusually long time to finish. + +
+ + + + + +[Vector3](class_vector3.md) **get_point_position**\ (\ id\: [int](class_int.md)\ ) const [🔗](#class_AStar3D_method_get_point_position) + +Returns the position of the point associated with the given `id`. + +
+ + + + + +[float](class_float.md) **get_point_weight_scale**\ (\ id\: [int](class_int.md)\ ) const [🔗](#class_AStar3D_method_get_point_weight_scale) + +Returns the weight scale of the point associated with the given `id`. + +
+ + + + + +[bool](class_bool.md) **has_point**\ (\ id\: [int](class_int.md)\ ) const [🔗](#class_AStar3D_method_has_point) + +Returns whether a point associated with the given `id` exists. + +
+ + + + + +[bool](class_bool.md) **is_point_disabled**\ (\ id\: [int](class_int.md)\ ) const [🔗](#class_AStar3D_method_is_point_disabled) + +Returns whether a point is disabled or not for pathfinding. By default, all points are enabled. + +
+ + + + + +`void` **remove_point**\ (\ id\: [int](class_int.md)\ ) [🔗](#class_AStar3D_method_remove_point) + +Removes the point associated with the given `id` from the points pool. + +
+ + + + + +`void` **reserve_space**\ (\ num_nodes\: [int](class_int.md)\ ) [🔗](#class_AStar3D_method_reserve_space) + +Reserves space internally for `num_nodes` points. Useful if you're adding a known large number of points at once, such as points on a grid. + +
+ + + + + +`void` **set_point_disabled**\ (\ id\: [int](class_int.md), disabled\: [bool](class_bool.md) = true\ ) [🔗](#class_AStar3D_method_set_point_disabled) + +Disables or enables the specified point for pathfinding. Useful for making a temporary obstacle. + +
+ + + + + +`void` **set_point_position**\ (\ id\: [int](class_int.md), position\: [Vector3](class_vector3.md)\ ) [🔗](#class_AStar3D_method_set_point_position) + +Sets the `position` for the point with the given `id`. + +
+ + + + + +`void` **set_point_weight_scale**\ (\ id\: [int](class_int.md), weight_scale\: [float](class_float.md)\ ) [🔗](#class_AStar3D_method_set_point_weight_scale) + +Sets the `weight_scale` for the point with the given `id`. The `weight_scale` is multiplied by the result of [_compute_cost()](class_astar3d.md#class_AStar3D_private_method__compute_cost) when determining the overall cost of traveling across a segment from a neighboring point to this point. + diff --git a/docs/Classes/class_astargrid2d.md b/docs/Classes/class_astargrid2d.md new file mode 100644 index 00000000..85472992 --- /dev/null +++ b/docs/Classes/class_astargrid2d.md @@ -0,0 +1,691 @@ + + + + + + + + + +# AStarGrid2D + +**Inherits:** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +An implementation of A\* for finding the shortest path between two points on a partial 2D grid. + + + +## Description + +**AStarGrid2D** is a variant of [AStar2D](class_astar2d.md) 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 [region](class_astargrid2d.md#class_AStarGrid2D_property_region) of the grid, optionally set the [cell_size](class_astargrid2d.md#class_AStarGrid2D_property_cell_size), and then call the [update()](class_astargrid2d.md#class_AStarGrid2D_method_update) method: + + + + +```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)] +``` + +```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)] +``` + + + +To remove a point from the pathfinding grid, it must be set as "solid" with [set_point_solid()](class_astargrid2d.md#class_AStarGrid2D_method_set_point_solid). + + + +## Tutorials + +- [Grid-based Navigation with AStarGrid2D Demo](https://godotengine.org/asset-library/asset/2723) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[CellShape](class_astargrid2d.md#enum_AStarGrid2D_CellShape)[cell_shape](#class_AStarGrid2D_property_cell_shape)`0`
[Vector2](class_vector2.md)[cell_size](#class_AStarGrid2D_property_cell_size)`Vector2(1, 1)`
[Heuristic](class_astargrid2d.md#enum_AStarGrid2D_Heuristic)[default_compute_heuristic](#class_AStarGrid2D_property_default_compute_heuristic)`0`
[Heuristic](class_astargrid2d.md#enum_AStarGrid2D_Heuristic)[default_estimate_heuristic](#class_AStarGrid2D_property_default_estimate_heuristic)`0`
[DiagonalMode](class_astargrid2d.md#enum_AStarGrid2D_DiagonalMode)[diagonal_mode](#class_AStarGrid2D_property_diagonal_mode)`0`
[bool](class_bool.md)[jumping_enabled](#class_AStarGrid2D_property_jumping_enabled)`false`
[int](class_int.md)[max_traversals](#class_AStarGrid2D_property_max_traversals)`0`
[Vector2](class_vector2.md)[offset](#class_AStarGrid2D_property_offset)`Vector2(0, 0)`
[Rect2i](class_rect2i.md)[region](#class_AStarGrid2D_property_region)`Rect2i(0, 0, 0, 0)`
[Vector2i](class_vector2i.md)[size](#class_AStarGrid2D_property_size)`Vector2i(0, 0)`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[_compute_cost](#class_AStarGrid2D_private_method__compute_cost)\ (\ from_id\: [Vector2i](class_vector2i.md), to_id\: [Vector2i](class_vector2i.md)\ ) virtual const
[float](class_float.md)[_estimate_cost](#class_AStarGrid2D_private_method__estimate_cost)\ (\ from_id\: [Vector2i](class_vector2i.md), end_id\: [Vector2i](class_vector2i.md)\ ) virtual const
`void`[clear](#class_AStarGrid2D_method_clear)\ (\ )
`void`[fill_solid_region](#class_AStarGrid2D_method_fill_solid_region)\ (\ region\: [Rect2i](class_rect2i.md), solid\: [bool](class_bool.md) = true\ )
`void`[fill_weight_scale_region](#class_AStarGrid2D_method_fill_weight_scale_region)\ (\ region\: [Rect2i](class_rect2i.md), weight_scale\: [float](class_float.md)\ )
[Array](class_array.md)\[[Vector2i](class_vector2i.md)\][get_id_path](#class_AStarGrid2D_method_get_id_path)\ (\ from_id\: [Vector2i](class_vector2i.md), to_id\: [Vector2i](class_vector2i.md), allow_partial_path\: [bool](class_bool.md) = false\ )
[Array](class_array.md)\[[Dictionary](class_dictionary.md)\][get_point_data_in_region](#class_AStarGrid2D_method_get_point_data_in_region)\ (\ region\: [Rect2i](class_rect2i.md)\ ) const
[PackedVector2Array](class_packedvector2array.md)[get_point_path](#class_AStarGrid2D_method_get_point_path)\ (\ from_id\: [Vector2i](class_vector2i.md), to_id\: [Vector2i](class_vector2i.md), allow_partial_path\: [bool](class_bool.md) = false\ )
[Vector2](class_vector2.md)[get_point_position](#class_AStarGrid2D_method_get_point_position)\ (\ id\: [Vector2i](class_vector2i.md)\ ) const
[float](class_float.md)[get_point_weight_scale](#class_AStarGrid2D_method_get_point_weight_scale)\ (\ id\: [Vector2i](class_vector2i.md)\ ) const
[bool](class_bool.md)[is_dirty](#class_AStarGrid2D_method_is_dirty)\ (\ ) const
[bool](class_bool.md)[is_in_bounds](#class_AStarGrid2D_method_is_in_bounds)\ (\ x\: [int](class_int.md), y\: [int](class_int.md)\ ) const
[bool](class_bool.md)[is_in_boundsv](#class_AStarGrid2D_method_is_in_boundsv)\ (\ id\: [Vector2i](class_vector2i.md)\ ) const
[bool](class_bool.md)[is_point_solid](#class_AStarGrid2D_method_is_point_solid)\ (\ id\: [Vector2i](class_vector2i.md)\ ) const
`void`[set_point_solid](#class_AStarGrid2D_method_set_point_solid)\ (\ id\: [Vector2i](class_vector2i.md), solid\: [bool](class_bool.md) = true\ )
`void`[set_point_weight_scale](#class_AStarGrid2D_method_set_point_weight_scale)\ (\ id\: [Vector2i](class_vector2i.md), weight_scale\: [float](class_float.md)\ )
`void`[update](#class_AStarGrid2D_method_update)\ (\ )
+ +
+ + + +## Enumerations + + + + + +enum **Heuristic**: [🔗](#enum_AStarGrid2D_Heuristic) + + + + + +[Heuristic](class_astargrid2d.md#enum_AStarGrid2D_Heuristic) **HEURISTIC_EUCLIDEAN** = `0` + +The [Euclidean heuristic](https://en.wikipedia.org/wiki/Euclidean_distance) to be used for the pathfinding using the following formula: + +``` + dx = abs(to_id.x - from_id.x) + dy = abs(to_id.y - from_id.y) + result = sqrt(dx * dx + dy * dy) +``` + +\ **Note:** This is also the internal heuristic used in [AStar3D](class_astar3d.md) and [AStar2D](class_astar2d.md) by default (with the inclusion of possible z-axis coordinate). + + + +[Heuristic](class_astargrid2d.md#enum_AStarGrid2D_Heuristic) **HEURISTIC_MANHATTAN** = `1` + +The [Manhattan heuristic](https://en.wikipedia.org/wiki/Taxicab_geometry) to be used for the pathfinding using the following formula: + +``` + dx = abs(to_id.x - from_id.x) + dy = abs(to_id.y - from_id.y) + result = dx + dy +``` + +\ **Note:** This heuristic is intended to be used with 4-side orthogonal movements, provided by setting the [diagonal_mode](class_astargrid2d.md#class_AStarGrid2D_property_diagonal_mode) to [DIAGONAL_MODE_NEVER](class_astargrid2d.md#class_AStarGrid2D_constant_DIAGONAL_MODE_NEVER). + + + +[Heuristic](class_astargrid2d.md#enum_AStarGrid2D_Heuristic) **HEURISTIC_OCTILE** = `2` + +The Octile heuristic to be used for the pathfinding using the following formula: + +``` + dx = abs(to_id.x - from_id.x) + dy = abs(to_id.y - from_id.y) + f = sqrt(2) - 1 + result = (dx < dy) ? f * dx + dy : f * dy + dx; +``` + + + +[Heuristic](class_astargrid2d.md#enum_AStarGrid2D_Heuristic) **HEURISTIC_CHEBYSHEV** = `3` + +The [Chebyshev heuristic](https://en.wikipedia.org/wiki/Chebyshev_distance) to be used for the pathfinding using the following formula: + +``` + dx = abs(to_id.x - from_id.x) + dy = abs(to_id.y - from_id.y) + result = max(dx, dy) +``` + + + +[Heuristic](class_astargrid2d.md#enum_AStarGrid2D_Heuristic) **HEURISTIC_MAX** = `4` + +Represents the size of the [Heuristic](class_astargrid2d.md#enum_AStarGrid2D_Heuristic) enum.
+ + + + + +enum **DiagonalMode**: [🔗](#enum_AStarGrid2D_DiagonalMode) + + + + + +[DiagonalMode](class_astargrid2d.md#enum_AStarGrid2D_DiagonalMode) **DIAGONAL_MODE_ALWAYS** = `0` + +The pathfinding algorithm will ignore solid neighbors around the target cell and allow passing using diagonals. + + + +[DiagonalMode](class_astargrid2d.md#enum_AStarGrid2D_DiagonalMode) **DIAGONAL_MODE_NEVER** = `1` + +The pathfinding algorithm will ignore all diagonals and the way will be always orthogonal. + + + +[DiagonalMode](class_astargrid2d.md#enum_AStarGrid2D_DiagonalMode) **DIAGONAL_MODE_AT_LEAST_ONE_WALKABLE** = `2` + +The pathfinding algorithm will avoid using diagonals if at least two obstacles have been placed around the neighboring cells of the specific path segment. + + + +[DiagonalMode](class_astargrid2d.md#enum_AStarGrid2D_DiagonalMode) **DIAGONAL_MODE_ONLY_IF_NO_OBSTACLES** = `3` + +The pathfinding algorithm will avoid using diagonals if any obstacle has been placed around the neighboring cells of the specific path segment. + + + +[DiagonalMode](class_astargrid2d.md#enum_AStarGrid2D_DiagonalMode) **DIAGONAL_MODE_MAX** = `4` + +Represents the size of the [DiagonalMode](class_astargrid2d.md#enum_AStarGrid2D_DiagonalMode) enum.
+ + + + + +enum **CellShape**: [🔗](#enum_AStarGrid2D_CellShape) + + + + + +[CellShape](class_astargrid2d.md#enum_AStarGrid2D_CellShape) **CELL_SHAPE_SQUARE** = `0` + +Rectangular cell shape. + + + +[CellShape](class_astargrid2d.md#enum_AStarGrid2D_CellShape) **CELL_SHAPE_ISOMETRIC_RIGHT** = `1` + +Diamond cell shape (for isometric look). Cell coordinates layout where the horizontal axis goes up-right, and the vertical one goes down-right. + + + +[CellShape](class_astargrid2d.md#enum_AStarGrid2D_CellShape) **CELL_SHAPE_ISOMETRIC_DOWN** = `2` + +Diamond cell shape (for isometric look). Cell coordinates layout where the horizontal axis goes down-right, and the vertical one goes down-left. + + + +[CellShape](class_astargrid2d.md#enum_AStarGrid2D_CellShape) **CELL_SHAPE_MAX** = `3` + +Represents the size of the [CellShape](class_astargrid2d.md#enum_AStarGrid2D_CellShape) enum.
+ + + +## Property Descriptions + + + + + +[CellShape](class_astargrid2d.md#enum_AStarGrid2D_CellShape) **cell_shape** = `0` [🔗](#class_AStarGrid2D_property_cell_shape) + + + +- `void` **set_cell_shape**\ (\ value\: [CellShape](class_astargrid2d.md#enum_AStarGrid2D_CellShape)\ ) +- [CellShape](class_astargrid2d.md#enum_AStarGrid2D_CellShape) **get_cell_shape**\ (\ ) + +The cell shape. Affects how the positions are placed in the grid. If changed, [update()](class_astargrid2d.md#class_AStarGrid2D_method_update) needs to be called before finding the next path. + +
+ + + + + +[Vector2](class_vector2.md) **cell_size** = `Vector2(1, 1)` [🔗](#class_AStarGrid2D_property_cell_size) + + + +- `void` **set_cell_size**\ (\ value\: [Vector2](class_vector2.md)\ ) +- [Vector2](class_vector2.md) **get_cell_size**\ (\ ) + +The size of the point cell which will be applied to calculate the resulting point position returned by [get_point_path()](class_astargrid2d.md#class_AStarGrid2D_method_get_point_path). If changed, [update()](class_astargrid2d.md#class_AStarGrid2D_method_update) needs to be called before finding the next path. + +
+ + + + + +[Heuristic](class_astargrid2d.md#enum_AStarGrid2D_Heuristic) **default_compute_heuristic** = `0` [🔗](#class_AStarGrid2D_property_default_compute_heuristic) + + + +- `void` **set_default_compute_heuristic**\ (\ value\: [Heuristic](class_astargrid2d.md#enum_AStarGrid2D_Heuristic)\ ) +- [Heuristic](class_astargrid2d.md#enum_AStarGrid2D_Heuristic) **get_default_compute_heuristic**\ (\ ) + +The default [Heuristic](class_astargrid2d.md#enum_AStarGrid2D_Heuristic) which will be used to calculate the cost between two points if [_compute_cost()](class_astargrid2d.md#class_AStarGrid2D_private_method__compute_cost) was not overridden. + +
+ + + + + +[Heuristic](class_astargrid2d.md#enum_AStarGrid2D_Heuristic) **default_estimate_heuristic** = `0` [🔗](#class_AStarGrid2D_property_default_estimate_heuristic) + + + +- `void` **set_default_estimate_heuristic**\ (\ value\: [Heuristic](class_astargrid2d.md#enum_AStarGrid2D_Heuristic)\ ) +- [Heuristic](class_astargrid2d.md#enum_AStarGrid2D_Heuristic) **get_default_estimate_heuristic**\ (\ ) + +The default [Heuristic](class_astargrid2d.md#enum_AStarGrid2D_Heuristic) which will be used to calculate the cost between the point and the end point if [_estimate_cost()](class_astargrid2d.md#class_AStarGrid2D_private_method__estimate_cost) was not overridden. + +
+ + + + + +[DiagonalMode](class_astargrid2d.md#enum_AStarGrid2D_DiagonalMode) **diagonal_mode** = `0` [🔗](#class_AStarGrid2D_property_diagonal_mode) + + + +- `void` **set_diagonal_mode**\ (\ value\: [DiagonalMode](class_astargrid2d.md#enum_AStarGrid2D_DiagonalMode)\ ) +- [DiagonalMode](class_astargrid2d.md#enum_AStarGrid2D_DiagonalMode) **get_diagonal_mode**\ (\ ) + +A specific [DiagonalMode](class_astargrid2d.md#enum_AStarGrid2D_DiagonalMode) mode which will force the path to avoid or accept the specified diagonals. + +
+ + + + + +[bool](class_bool.md) **jumping_enabled** = `false` [🔗](#class_AStarGrid2D_property_jumping_enabled) + + + +- `void` **set_jumping_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_jumping_enabled**\ (\ ) + +Enables or disables jumping to skip up the intermediate points and speeds up the searching algorithm. + +\ **Note:** Currently, toggling it on disables the consideration of weight scaling in pathfinding. + +
+ + + + + +[int](class_int.md) **max_traversals** = `0` [🔗](#class_AStarGrid2D_property_max_traversals) + + + +- `void` **set_max_traversals**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_max_traversals**\ (\ ) + +The maximum number of points to traverse before giving up. If set to ``0``, the search will continue until the end point is reached or the whole grid is traversed. + +
+ + + + + +[Vector2](class_vector2.md) **offset** = `Vector2(0, 0)` [🔗](#class_AStarGrid2D_property_offset) + + + +- `void` **set_offset**\ (\ value\: [Vector2](class_vector2.md)\ ) +- [Vector2](class_vector2.md) **get_offset**\ (\ ) + +The offset of the grid which will be applied to calculate the resulting point position returned by [get_point_path()](class_astargrid2d.md#class_AStarGrid2D_method_get_point_path). If changed, [update()](class_astargrid2d.md#class_AStarGrid2D_method_update) needs to be called before finding the next path. + +
+ + + + + +[Rect2i](class_rect2i.md) **region** = `Rect2i(0, 0, 0, 0)` [🔗](#class_AStarGrid2D_property_region) + + + +- `void` **set_region**\ (\ value\: [Rect2i](class_rect2i.md)\ ) +- [Rect2i](class_rect2i.md) **get_region**\ (\ ) + +The region of grid cells available for pathfinding. If changed, [update()](class_astargrid2d.md#class_AStarGrid2D_method_update) needs to be called before finding the next path. + +
+ + + + + +[Vector2i](class_vector2i.md) **size** = `Vector2i(0, 0)` [🔗](#class_AStarGrid2D_property_size) + + + +- `void` **set_size**\ (\ value\: [Vector2i](class_vector2i.md)\ ) +- [Vector2i](class_vector2i.md) **get_size**\ (\ ) + +**Deprecated:** Use [region](class_astargrid2d.md#class_AStarGrid2D_property_region) instead. + +The size of the grid (number of cells of size [cell_size](class_astargrid2d.md#class_AStarGrid2D_property_cell_size) on each axis). If changed, [update()](class_astargrid2d.md#class_AStarGrid2D_method_update) needs to be called before finding the next path. + +
+ + + +## Method Descriptions + + + + + +[float](class_float.md) **_compute_cost**\ (\ from_id\: [Vector2i](class_vector2i.md), to_id\: [Vector2i](class_vector2i.md)\ ) virtual const [🔗](#class_AStarGrid2D_private_method__compute_cost) + +Called when computing the cost between two connected points. + +Note that this function is hidden in the default **AStarGrid2D** class. + +
+ + + + + +[float](class_float.md) **_estimate_cost**\ (\ from_id\: [Vector2i](class_vector2i.md), end_id\: [Vector2i](class_vector2i.md)\ ) virtual const [🔗](#class_AStarGrid2D_private_method__estimate_cost) + +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. + +
+ + + + + +`void` **clear**\ (\ ) [🔗](#class_AStarGrid2D_method_clear) + +Clears the grid and sets the [region](class_astargrid2d.md#class_AStarGrid2D_property_region) to ``Rect2i(0, 0, 0, 0)``. + +
+ + + + + +`void` **fill_solid_region**\ (\ region\: [Rect2i](class_rect2i.md), solid\: [bool](class_bool.md) = true\ ) [🔗](#class_AStarGrid2D_method_fill_solid_region) + +Fills the given `region` on the grid with the specified value for the solid flag. + +\ **Note:** Calling [update()](class_astargrid2d.md#class_AStarGrid2D_method_update) is not needed after the call of this function. + +
+ + + + + +`void` **fill_weight_scale_region**\ (\ region\: [Rect2i](class_rect2i.md), weight_scale\: [float](class_float.md)\ ) [🔗](#class_AStarGrid2D_method_fill_weight_scale_region) + +Fills the given `region` on the grid with the specified value for the weight scale. + +\ **Note:** Calling [update()](class_astargrid2d.md#class_AStarGrid2D_method_update) is not needed after the call of this function. + +
+ + + + + +[Array](class_array.md)\[[Vector2i](class_vector2i.md)\] **get_id_path**\ (\ from_id\: [Vector2i](class_vector2i.md), to_id\: [Vector2i](class_vector2i.md), allow_partial_path\: [bool](class_bool.md) = false\ ) [🔗](#class_AStarGrid2D_method_get_id_path) + +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 `allow_partial_path` is ``true``, returns a path to the point closest to the target that can be reached. + +\ **Note:** When `allow_partial_path` is ``true`` and `to_id` is solid the search may take an unusually long time to finish. + +
+ + + + + +[Array](class_array.md)\[[Dictionary](class_dictionary.md)\] **get_point_data_in_region**\ (\ region\: [Rect2i](class_rect2i.md)\ ) const [🔗](#class_AStarGrid2D_method_get_point_data_in_region) + +Returns an array of dictionaries with point data (``id``: [Vector2i](class_vector2i.md), ``position``: [Vector2](class_vector2.md), ``solid``: [bool](class_bool.md), ``weight_scale``: [float](class_float.md)) within a `region`. + +
+ + + + + +[PackedVector2Array](class_packedvector2array.md) **get_point_path**\ (\ from_id\: [Vector2i](class_vector2i.md), to_id\: [Vector2i](class_vector2i.md), allow_partial_path\: [bool](class_bool.md) = false\ ) [🔗](#class_AStarGrid2D_method_get_point_path) + +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 `allow_partial_path` is ``true``, returns a path to the point closest to the target that can be reached. + +\ **Note:** This method is not thread-safe; it can only be used from a single [Thread](class_thread.md) at a given time. Consider using [Mutex](class_mutex.md) to ensure exclusive access to one thread to avoid race conditions. + +Additionally, when `allow_partial_path` is ``true`` and `to_id` is solid the search may take an unusually long time to finish. + +
+ + + + + +[Vector2](class_vector2.md) **get_point_position**\ (\ id\: [Vector2i](class_vector2i.md)\ ) const [🔗](#class_AStarGrid2D_method_get_point_position) + +Returns the position of the point associated with the given `id`. + +
+ + + + + +[float](class_float.md) **get_point_weight_scale**\ (\ id\: [Vector2i](class_vector2i.md)\ ) const [🔗](#class_AStarGrid2D_method_get_point_weight_scale) + +Returns the weight scale of the point associated with the given `id`. + +
+ + + + + +[bool](class_bool.md) **is_dirty**\ (\ ) const [🔗](#class_AStarGrid2D_method_is_dirty) + +Indicates that the grid parameters were changed and [update()](class_astargrid2d.md#class_AStarGrid2D_method_update) needs to be called. + +
+ + + + + +[bool](class_bool.md) **is_in_bounds**\ (\ x\: [int](class_int.md), y\: [int](class_int.md)\ ) const [🔗](#class_AStarGrid2D_method_is_in_bounds) + +Returns ``true`` if the `x` and `y` is a valid grid coordinate (id), i.e. if it is inside [region](class_astargrid2d.md#class_AStarGrid2D_property_region). Equivalent to ``region.has_point(Vector2i(x, y))``. + +
+ + + + + +[bool](class_bool.md) **is_in_boundsv**\ (\ id\: [Vector2i](class_vector2i.md)\ ) const [🔗](#class_AStarGrid2D_method_is_in_boundsv) + +Returns ``true`` if the `id` vector is a valid grid coordinate, i.e. if it is inside [region](class_astargrid2d.md#class_AStarGrid2D_property_region). Equivalent to ``region.has_point(id)``. + +
+ + + + + +[bool](class_bool.md) **is_point_solid**\ (\ id\: [Vector2i](class_vector2i.md)\ ) const [🔗](#class_AStarGrid2D_method_is_point_solid) + +Returns ``true`` if a point is disabled for pathfinding. By default, all points are enabled. + +
+ + + + + +`void` **set_point_solid**\ (\ id\: [Vector2i](class_vector2i.md), solid\: [bool](class_bool.md) = true\ ) [🔗](#class_AStarGrid2D_method_set_point_solid) + +Disables or enables the specified point for pathfinding. Useful for making an obstacle. By default, all points are enabled. + +\ **Note:** Calling [update()](class_astargrid2d.md#class_AStarGrid2D_method_update) is not needed after the call of this function. + +
+ + + + + +`void` **set_point_weight_scale**\ (\ id\: [Vector2i](class_vector2i.md), weight_scale\: [float](class_float.md)\ ) [🔗](#class_AStarGrid2D_method_set_point_weight_scale) + +Sets the `weight_scale` for the point with the given `id`. The `weight_scale` is multiplied by the result of [_compute_cost()](class_astargrid2d.md#class_AStarGrid2D_private_method__compute_cost) when determining the overall cost of traveling across a segment from a neighboring point to this point. + +\ **Note:** Calling [update()](class_astargrid2d.md#class_AStarGrid2D_method_update) is not needed after the call of this function. + +
+ + + + + +`void` **update**\ (\ ) [🔗](#class_AStarGrid2D_method_update) + +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 [region](class_astargrid2d.md#class_AStarGrid2D_property_region), [cell_size](class_astargrid2d.md#class_AStarGrid2D_property_cell_size) or [offset](class_astargrid2d.md#class_AStarGrid2D_property_offset) are changed. [is_dirty()](class_astargrid2d.md#class_AStarGrid2D_method_is_dirty) will return ``true`` if this is the case and this needs to be called. + +\ **Note:** All point data (solidity and weight scale) will be cleared. + diff --git a/docs/Classes/class_atlastexture.md b/docs/Classes/class_atlastexture.md new file mode 100644 index 00000000..adbbe3b3 --- /dev/null +++ b/docs/Classes/class_atlastexture.md @@ -0,0 +1,125 @@ + + + + + + + + + +# AtlasTexture + +**Inherits:** [Texture2D](class_texture2d.md) **<** [Texture](class_texture.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +A texture that crops out part of another Texture2D. + + + +## Description + +[Texture2D](class_texture2d.md) resource that draws only part of its [atlas](class_atlastexture.md#class_AtlasTexture_property_atlas) texture, as defined by the [region](class_atlastexture.md#class_AtlasTexture_property_region). An additional [margin](class_atlastexture.md#class_AtlasTexture_property_margin) can also be set, which is useful for small adjustments. + +Multiple **AtlasTexture** resources can be cropped from the same [atlas](class_atlastexture.md#class_AtlasTexture_property_atlas). Packing many smaller textures into a singular large texture helps to optimize video memory costs and render calls. + +\ **Note:** **AtlasTexture** cannot be used in an [AnimatedTexture](class_animatedtexture.md), and will not tile properly in nodes such as [TextureRect](class_texturerect.md) or [Sprite2D](class_sprite2d.md). To tile an **AtlasTexture**, modify its [region](class_atlastexture.md#class_AtlasTexture_property_region) instead. + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Texture2D](class_texture2d.md)[atlas](#class_AtlasTexture_property_atlas)
[bool](class_bool.md)[filter_clip](#class_AtlasTexture_property_filter_clip)`false`
[Rect2](class_rect2.md)[margin](#class_AtlasTexture_property_margin)`Rect2(0, 0, 0, 0)`
[Rect2](class_rect2.md)[region](#class_AtlasTexture_property_region)`Rect2(0, 0, 0, 0)`
[bool](class_bool.md)resource_local_to_scene`false` (overrides [Resource.resource_local_to_scene](class_resource.md#class_Resource_property_resource_local_to_scene))
+ +
+ + + +## Property Descriptions + + + + + +[Texture2D](class_texture2d.md) **atlas** [🔗](#class_AtlasTexture_property_atlas) + + + +- `void` **set_atlas**\ (\ value\: [Texture2D](class_texture2d.md)\ ) +- [Texture2D](class_texture2d.md) **get_atlas**\ (\ ) + +The texture that contains the atlas. Can be any type inheriting from [Texture2D](class_texture2d.md), including another **AtlasTexture**. + +
+ + + + + +[bool](class_bool.md) **filter_clip** = `false` [🔗](#class_AtlasTexture_property_filter_clip) + + + +- `void` **set_filter_clip**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **has_filter_clip**\ (\ ) + +If ``true``, the area outside of the [region](class_atlastexture.md#class_AtlasTexture_property_region) is clipped to avoid bleeding of the surrounding texture pixels. + +
+ + + + + +[Rect2](class_rect2.md) **margin** = `Rect2(0, 0, 0, 0)` [🔗](#class_AtlasTexture_property_margin) + + + +- `void` **set_margin**\ (\ value\: [Rect2](class_rect2.md)\ ) +- [Rect2](class_rect2.md) **get_margin**\ (\ ) + +The margin around the [region](class_atlastexture.md#class_AtlasTexture_property_region). Useful for small adjustments. If the [Rect2.size](class_rect2.md#class_Rect2_property_size) of this property ("w" and "h" in the editor) is set, the drawn texture is resized to fit within the margin. + +
+ + + + + +[Rect2](class_rect2.md) **region** = `Rect2(0, 0, 0, 0)` [🔗](#class_AtlasTexture_property_region) + + + +- `void` **set_region**\ (\ value\: [Rect2](class_rect2.md)\ ) +- [Rect2](class_rect2.md) **get_region**\ (\ ) + +The region used to draw the [atlas](class_atlastexture.md#class_AtlasTexture_property_atlas). If either dimension of the region's size is ``0``, the value from [atlas](class_atlastexture.md#class_AtlasTexture_property_atlas) size will be used for that axis instead. + diff --git a/docs/Classes/class_audiobuslayout.md b/docs/Classes/class_audiobuslayout.md new file mode 100644 index 00000000..02e35898 --- /dev/null +++ b/docs/Classes/class_audiobuslayout.md @@ -0,0 +1,21 @@ + + + + + + + + + +# AudioBusLayout + +**Inherits:** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Stores information about the audio buses. + + + +## Description + +Stores position, muting, solo, bypass, effects, effect position, volume, and the connections between buses. See [AudioServer](class_audioserver.md) for usage. + diff --git a/docs/Classes/class_audioeffect.md b/docs/Classes/class_audioeffect.md new file mode 100644 index 00000000..6a528afd --- /dev/null +++ b/docs/Classes/class_audioeffect.md @@ -0,0 +1,76 @@ + + + + + + + + + +# AudioEffect + +**Inherits:** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +**Inherited By:** [AudioEffectAmplify](class_audioeffectamplify.md), [AudioEffectCapture](class_audioeffectcapture.md), [AudioEffectChorus](class_audioeffectchorus.md), [AudioEffectCompressor](class_audioeffectcompressor.md), [AudioEffectDelay](class_audioeffectdelay.md), [AudioEffectDistortion](class_audioeffectdistortion.md), [AudioEffectEQ](class_audioeffecteq.md), [AudioEffectFilter](class_audioeffectfilter.md), [AudioEffectHardLimiter](class_audioeffecthardlimiter.md), [AudioEffectLimiter](class_audioeffectlimiter.md), [AudioEffectPanner](class_audioeffectpanner.md), [AudioEffectPhaser](class_audioeffectphaser.md), [AudioEffectPitchShift](class_audioeffectpitchshift.md), [AudioEffectRecord](class_audioeffectrecord.md), [AudioEffectReverb](class_audioeffectreverb.md), [AudioEffectSpectrumAnalyzer](class_audioeffectspectrumanalyzer.md), [AudioEffectStereoEnhance](class_audioeffectstereoenhance.md) + +Base class for audio effect resources. + + + +## Description + +The base [Resource](class_resource.md) 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 [AudioServer.add_bus_effect()](class_audioserver.md#class_AudioServer_method_add_bus_effect), [AudioServer.remove_bus_effect()](class_audioserver.md#class_AudioServer_method_remove_bus_effect), and [AudioServer.get_bus_effect()](class_audioserver.md#class_AudioServer_method_get_bus_effect). + +When applied on a bus, an audio effect creates a corresponding [AudioEffectInstance](class_audioeffectinstance.md). The instance is directly responsible for manipulating the sound, based on the original audio effect's properties. + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + +- [Audio Microphone Record Demo](https://godotengine.org/asset-library/asset/2760) + + + +## Methods + + + + + + + + + + +
[AudioEffectInstance](class_audioeffectinstance.md)[_instantiate](#class_AudioEffect_private_method__instantiate)\ (\ ) virtual required
+ +
+ + + +## Method Descriptions + + + + + +[AudioEffectInstance](class_audioeffectinstance.md) **_instantiate**\ (\ ) virtual required [🔗](#class_AudioEffect_private_method__instantiate) + +Override this method to customize the [AudioEffectInstance](class_audioeffectinstance.md) created when this effect is applied on a bus in the editor's Audio panel, or through [AudioServer.add_bus_effect()](class_audioserver.md#class_AudioServer_method_add_bus_effect). + +``` + extends AudioEffect + + @export var strength = 4.0 + + func _instantiate(): + var effect = CustomAudioEffectInstance.new() + effect.base = self + + return effect +``` + +\ **Note:** 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. + diff --git a/docs/Classes/class_audioeffectamplify.md b/docs/Classes/class_audioeffectamplify.md new file mode 100644 index 00000000..a6921890 --- /dev/null +++ b/docs/Classes/class_audioeffectamplify.md @@ -0,0 +1,84 @@ + + + + + + + + + +# AudioEffectAmplify + +**Inherits:** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Adds an amplifying audio effect to an audio bus. + + + +## Description + +Increases or decreases the volume being routed through the audio bus. + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + + + +## Properties + + + + + + + + + + + + + + + + +
[float](class_float.md)[volume_db](#class_AudioEffectAmplify_property_volume_db)`0.0`
[float](class_float.md)[volume_linear](#class_AudioEffectAmplify_property_volume_linear)
+ +
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **volume_db** = `0.0` [🔗](#class_AudioEffectAmplify_property_volume_db) + + + +- `void` **set_volume_db**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_volume_db**\ (\ ) + +Amount of amplification in decibels. Positive values make the sound louder, negative values make it quieter. Value can range from -80 to 24. + +
+ + + + + +[float](class_float.md) **volume_linear** [🔗](#class_AudioEffectAmplify_property_volume_linear) + + + +- `void` **set_volume_linear**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_volume_linear**\ (\ ) + +Amount of amplification as a linear value. + +\ **Note:** This member modifies [volume_db](class_audioeffectamplify.md#class_AudioEffectAmplify_property_volume_db) for convenience. The returned value is equivalent to the result of [@GlobalScope.db_to_linear()](class_@globalscope.md#class_@GlobalScope_method_db_to_linear) on [volume_db](class_audioeffectamplify.md#class_AudioEffectAmplify_property_volume_db). Setting this member is equivalent to setting [volume_db](class_audioeffectamplify.md#class_AudioEffectAmplify_property_volume_db) to the result of [@GlobalScope.linear_to_db()](class_@globalscope.md#class_@GlobalScope_method_linear_to_db) on a value. + diff --git a/docs/Classes/class_audioeffectbandlimitfilter.md b/docs/Classes/class_audioeffectbandlimitfilter.md new file mode 100644 index 00000000..e78a722b --- /dev/null +++ b/docs/Classes/class_audioeffectbandlimitfilter.md @@ -0,0 +1,27 @@ + + + + + + + + + +# AudioEffectBandLimitFilter + +**Inherits:** [AudioEffectFilter](class_audioeffectfilter.md) **<** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Adds a band limit filter to the audio bus. + + + +## Description + +Limits the frequencies in a range around the [AudioEffectFilter.cutoff_hz](class_audioeffectfilter.md#class_AudioEffectFilter_property_cutoff_hz) and allows frequencies outside of this range to pass. + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + diff --git a/docs/Classes/class_audioeffectbandpassfilter.md b/docs/Classes/class_audioeffectbandpassfilter.md new file mode 100644 index 00000000..cd626a87 --- /dev/null +++ b/docs/Classes/class_audioeffectbandpassfilter.md @@ -0,0 +1,27 @@ + + + + + + + + + +# AudioEffectBandPassFilter + +**Inherits:** [AudioEffectFilter](class_audioeffectfilter.md) **<** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Adds a band pass filter to the audio bus. + + + +## Description + +Attenuates the frequencies inside of a range around the [AudioEffectFilter.cutoff_hz](class_audioeffectfilter.md#class_AudioEffectFilter_property_cutoff_hz) and cuts frequencies outside of this band. + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + diff --git a/docs/Classes/class_audioeffectcapture.md b/docs/Classes/class_audioeffectcapture.md new file mode 100644 index 00000000..a0ef21fe --- /dev/null +++ b/docs/Classes/class_audioeffectcapture.md @@ -0,0 +1,185 @@ + + + + + + + + + +# AudioEffectCapture + +**Inherits:** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Captures audio from an audio bus in real-time. + + + +## 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 [get_buffer()](class_audioeffectcapture.md#class_AudioEffectCapture_method_get_buffer) and process it as needed, for example to capture data from an [AudioStreamMicrophone](class_audiostreammicrophone.md), 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](class_audioeffectrecord.md), this effect only returns the raw audio samples instead of encoding them into an [AudioStream](class_audiostream.md). + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + + + +## Properties + + + + + + + + + + + +
[float](class_float.md)[buffer_length](#class_AudioEffectCapture_property_buffer_length)`0.1`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[can_get_buffer](#class_AudioEffectCapture_method_can_get_buffer)\ (\ frames\: [int](class_int.md)\ ) const
`void`[clear_buffer](#class_AudioEffectCapture_method_clear_buffer)\ (\ )
[PackedVector2Array](class_packedvector2array.md)[get_buffer](#class_AudioEffectCapture_method_get_buffer)\ (\ frames\: [int](class_int.md)\ )
[int](class_int.md)[get_buffer_length_frames](#class_AudioEffectCapture_method_get_buffer_length_frames)\ (\ ) const
[int](class_int.md)[get_discarded_frames](#class_AudioEffectCapture_method_get_discarded_frames)\ (\ ) const
[int](class_int.md)[get_frames_available](#class_AudioEffectCapture_method_get_frames_available)\ (\ ) const
[int](class_int.md)[get_pushed_frames](#class_AudioEffectCapture_method_get_pushed_frames)\ (\ ) const
+ +
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **buffer_length** = `0.1` [🔗](#class_AudioEffectCapture_property_buffer_length) + + + +- `void` **set_buffer_length**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_buffer_length**\ (\ ) + +Length of the internal ring buffer, in seconds. Setting the buffer length will have no effect if already initialized. + +
+ + + +## Method Descriptions + + + + + +[bool](class_bool.md) **can_get_buffer**\ (\ frames\: [int](class_int.md)\ ) const [🔗](#class_AudioEffectCapture_method_can_get_buffer) + +Returns ``true`` if at least `frames` audio frames are available to read in the internal ring buffer. + +
+ + + + + +`void` **clear_buffer**\ (\ ) [🔗](#class_AudioEffectCapture_method_clear_buffer) + +Clears the internal ring buffer. + +\ **Note:** Calling this during a capture can cause the loss of samples which causes popping in the playback. + +
+ + + + + +[PackedVector2Array](class_packedvector2array.md) **get_buffer**\ (\ frames\: [int](class_int.md)\ ) [🔗](#class_AudioEffectCapture_method_get_buffer) + +Gets the next `frames` audio samples from the internal ring buffer. + +Returns a [PackedVector2Array](class_packedvector2array.md) containing exactly `frames` audio samples if available, or an empty [PackedVector2Array](class_packedvector2array.md) if insufficient data was available. + +The samples are signed floating-point PCM between ``-1`` and ``1``. You will have to scale them if you want to use them as 8 or 16-bit integer samples. (``v = 0x7fff * samples[0].x``) + +
+ + + + + +[int](class_int.md) **get_buffer_length_frames**\ (\ ) const [🔗](#class_AudioEffectCapture_method_get_buffer_length_frames) + +Returns the total size of the internal ring buffer in frames. + +
+ + + + + +[int](class_int.md) **get_discarded_frames**\ (\ ) const [🔗](#class_AudioEffectCapture_method_get_discarded_frames) + +Returns the number of audio frames discarded from the audio bus due to full buffer. + +
+ + + + + +[int](class_int.md) **get_frames_available**\ (\ ) const [🔗](#class_AudioEffectCapture_method_get_frames_available) + +Returns the number of frames available to read using [get_buffer()](class_audioeffectcapture.md#class_AudioEffectCapture_method_get_buffer). + +
+ + + + + +[int](class_int.md) **get_pushed_frames**\ (\ ) const [🔗](#class_AudioEffectCapture_method_get_pushed_frames) + +Returns the number of audio frames inserted from the audio bus. + diff --git a/docs/Classes/class_audioeffectchorus.md b/docs/Classes/class_audioeffectchorus.md new file mode 100644 index 00000000..37a272df --- /dev/null +++ b/docs/Classes/class_audioeffectchorus.md @@ -0,0 +1,801 @@ + + + + + + + + + +# AudioEffectChorus + +**Inherits:** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Adds a chorus audio effect. + + + +## Description + +Adds a chorus audio effect. The effect applies a filter with voices to duplicate the audio source and manipulate it through the filter. + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[dry](#class_AudioEffectChorus_property_dry)`1.0`
[float](class_float.md)[voice/1/cutoff_hz](#class_AudioEffectChorus_property_voice/1/cutoff_hz)`8000.0`
[float](class_float.md)[voice/1/delay_ms](#class_AudioEffectChorus_property_voice/1/delay_ms)`15.0`
[float](class_float.md)[voice/1/depth_ms](#class_AudioEffectChorus_property_voice/1/depth_ms)`2.0`
[float](class_float.md)[voice/1/level_db](#class_AudioEffectChorus_property_voice/1/level_db)`0.0`
[float](class_float.md)[voice/1/pan](#class_AudioEffectChorus_property_voice/1/pan)`-0.5`
[float](class_float.md)[voice/1/rate_hz](#class_AudioEffectChorus_property_voice/1/rate_hz)`0.8`
[float](class_float.md)[voice/2/cutoff_hz](#class_AudioEffectChorus_property_voice/2/cutoff_hz)`8000.0`
[float](class_float.md)[voice/2/delay_ms](#class_AudioEffectChorus_property_voice/2/delay_ms)`20.0`
[float](class_float.md)[voice/2/depth_ms](#class_AudioEffectChorus_property_voice/2/depth_ms)`3.0`
[float](class_float.md)[voice/2/level_db](#class_AudioEffectChorus_property_voice/2/level_db)`0.0`
[float](class_float.md)[voice/2/pan](#class_AudioEffectChorus_property_voice/2/pan)`0.5`
[float](class_float.md)[voice/2/rate_hz](#class_AudioEffectChorus_property_voice/2/rate_hz)`1.2`
[float](class_float.md)[voice/3/cutoff_hz](#class_AudioEffectChorus_property_voice/3/cutoff_hz)
[float](class_float.md)[voice/3/delay_ms](#class_AudioEffectChorus_property_voice/3/delay_ms)
[float](class_float.md)[voice/3/depth_ms](#class_AudioEffectChorus_property_voice/3/depth_ms)
[float](class_float.md)[voice/3/level_db](#class_AudioEffectChorus_property_voice/3/level_db)
[float](class_float.md)[voice/3/pan](#class_AudioEffectChorus_property_voice/3/pan)
[float](class_float.md)[voice/3/rate_hz](#class_AudioEffectChorus_property_voice/3/rate_hz)
[float](class_float.md)[voice/4/cutoff_hz](#class_AudioEffectChorus_property_voice/4/cutoff_hz)
[float](class_float.md)[voice/4/delay_ms](#class_AudioEffectChorus_property_voice/4/delay_ms)
[float](class_float.md)[voice/4/depth_ms](#class_AudioEffectChorus_property_voice/4/depth_ms)
[float](class_float.md)[voice/4/level_db](#class_AudioEffectChorus_property_voice/4/level_db)
[float](class_float.md)[voice/4/pan](#class_AudioEffectChorus_property_voice/4/pan)
[float](class_float.md)[voice/4/rate_hz](#class_AudioEffectChorus_property_voice/4/rate_hz)
[int](class_int.md)[voice_count](#class_AudioEffectChorus_property_voice_count)`2`
[float](class_float.md)[wet](#class_AudioEffectChorus_property_wet)`0.5`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[get_voice_cutoff_hz](#class_AudioEffectChorus_method_get_voice_cutoff_hz)\ (\ voice_idx\: [int](class_int.md)\ ) const
[float](class_float.md)[get_voice_delay_ms](#class_AudioEffectChorus_method_get_voice_delay_ms)\ (\ voice_idx\: [int](class_int.md)\ ) const
[float](class_float.md)[get_voice_depth_ms](#class_AudioEffectChorus_method_get_voice_depth_ms)\ (\ voice_idx\: [int](class_int.md)\ ) const
[float](class_float.md)[get_voice_level_db](#class_AudioEffectChorus_method_get_voice_level_db)\ (\ voice_idx\: [int](class_int.md)\ ) const
[float](class_float.md)[get_voice_pan](#class_AudioEffectChorus_method_get_voice_pan)\ (\ voice_idx\: [int](class_int.md)\ ) const
[float](class_float.md)[get_voice_rate_hz](#class_AudioEffectChorus_method_get_voice_rate_hz)\ (\ voice_idx\: [int](class_int.md)\ ) const
`void`[set_voice_cutoff_hz](#class_AudioEffectChorus_method_set_voice_cutoff_hz)\ (\ voice_idx\: [int](class_int.md), cutoff_hz\: [float](class_float.md)\ )
`void`[set_voice_delay_ms](#class_AudioEffectChorus_method_set_voice_delay_ms)\ (\ voice_idx\: [int](class_int.md), delay_ms\: [float](class_float.md)\ )
`void`[set_voice_depth_ms](#class_AudioEffectChorus_method_set_voice_depth_ms)\ (\ voice_idx\: [int](class_int.md), depth_ms\: [float](class_float.md)\ )
`void`[set_voice_level_db](#class_AudioEffectChorus_method_set_voice_level_db)\ (\ voice_idx\: [int](class_int.md), level_db\: [float](class_float.md)\ )
`void`[set_voice_pan](#class_AudioEffectChorus_method_set_voice_pan)\ (\ voice_idx\: [int](class_int.md), pan\: [float](class_float.md)\ )
`void`[set_voice_rate_hz](#class_AudioEffectChorus_method_set_voice_rate_hz)\ (\ voice_idx\: [int](class_int.md), rate_hz\: [float](class_float.md)\ )
+ +
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **dry** = `1.0` [🔗](#class_AudioEffectChorus_property_dry) + + + +- `void` **set_dry**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_dry**\ (\ ) + +The effect's raw signal. + +
+ + + + + +[float](class_float.md) **voice/1/cutoff_hz** = `8000.0` [🔗](#class_AudioEffectChorus_property_voice/1/cutoff_hz) + + + +- `void` **set_voice_cutoff_hz**\ (\ voice_idx\: [int](class_int.md), cutoff_hz\: [float](class_float.md)\ ) +- [float](class_float.md) **get_voice_cutoff_hz**\ (\ voice_idx\: [int](class_int.md)\ ) const + +The voice's cutoff frequency. + +
+ + + + + +[float](class_float.md) **voice/1/delay_ms** = `15.0` [🔗](#class_AudioEffectChorus_property_voice/1/delay_ms) + + + +- `void` **set_voice_delay_ms**\ (\ voice_idx\: [int](class_int.md), delay_ms\: [float](class_float.md)\ ) +- [float](class_float.md) **get_voice_delay_ms**\ (\ voice_idx\: [int](class_int.md)\ ) const + +The voice's signal delay. + +
+ + + + + +[float](class_float.md) **voice/1/depth_ms** = `2.0` [🔗](#class_AudioEffectChorus_property_voice/1/depth_ms) + + + +- `void` **set_voice_depth_ms**\ (\ voice_idx\: [int](class_int.md), depth_ms\: [float](class_float.md)\ ) +- [float](class_float.md) **get_voice_depth_ms**\ (\ voice_idx\: [int](class_int.md)\ ) const + +The voice filter's depth. + +
+ + + + + +[float](class_float.md) **voice/1/level_db** = `0.0` [🔗](#class_AudioEffectChorus_property_voice/1/level_db) + + + +- `void` **set_voice_level_db**\ (\ voice_idx\: [int](class_int.md), level_db\: [float](class_float.md)\ ) +- [float](class_float.md) **get_voice_level_db**\ (\ voice_idx\: [int](class_int.md)\ ) const + +The voice's volume. + +
+ + + + + +[float](class_float.md) **voice/1/pan** = `-0.5` [🔗](#class_AudioEffectChorus_property_voice/1/pan) + + + +- `void` **set_voice_pan**\ (\ voice_idx\: [int](class_int.md), pan\: [float](class_float.md)\ ) +- [float](class_float.md) **get_voice_pan**\ (\ voice_idx\: [int](class_int.md)\ ) const + +The voice's pan level. + +
+ + + + + +[float](class_float.md) **voice/1/rate_hz** = `0.8` [🔗](#class_AudioEffectChorus_property_voice/1/rate_hz) + + + +- `void` **set_voice_rate_hz**\ (\ voice_idx\: [int](class_int.md), rate_hz\: [float](class_float.md)\ ) +- [float](class_float.md) **get_voice_rate_hz**\ (\ voice_idx\: [int](class_int.md)\ ) const + +The voice's filter rate. + +
+ + + + + +[float](class_float.md) **voice/2/cutoff_hz** = `8000.0` [🔗](#class_AudioEffectChorus_property_voice/2/cutoff_hz) + + + +- `void` **set_voice_cutoff_hz**\ (\ voice_idx\: [int](class_int.md), cutoff_hz\: [float](class_float.md)\ ) +- [float](class_float.md) **get_voice_cutoff_hz**\ (\ voice_idx\: [int](class_int.md)\ ) const + +The voice's cutoff frequency. + +
+ + + + + +[float](class_float.md) **voice/2/delay_ms** = `20.0` [🔗](#class_AudioEffectChorus_property_voice/2/delay_ms) + + + +- `void` **set_voice_delay_ms**\ (\ voice_idx\: [int](class_int.md), delay_ms\: [float](class_float.md)\ ) +- [float](class_float.md) **get_voice_delay_ms**\ (\ voice_idx\: [int](class_int.md)\ ) const + +The voice's signal delay. + +
+ + + + + +[float](class_float.md) **voice/2/depth_ms** = `3.0` [🔗](#class_AudioEffectChorus_property_voice/2/depth_ms) + + + +- `void` **set_voice_depth_ms**\ (\ voice_idx\: [int](class_int.md), depth_ms\: [float](class_float.md)\ ) +- [float](class_float.md) **get_voice_depth_ms**\ (\ voice_idx\: [int](class_int.md)\ ) const + +The voice filter's depth. + +
+ + + + + +[float](class_float.md) **voice/2/level_db** = `0.0` [🔗](#class_AudioEffectChorus_property_voice/2/level_db) + + + +- `void` **set_voice_level_db**\ (\ voice_idx\: [int](class_int.md), level_db\: [float](class_float.md)\ ) +- [float](class_float.md) **get_voice_level_db**\ (\ voice_idx\: [int](class_int.md)\ ) const + +The voice's volume. + +
+ + + + + +[float](class_float.md) **voice/2/pan** = `0.5` [🔗](#class_AudioEffectChorus_property_voice/2/pan) + + + +- `void` **set_voice_pan**\ (\ voice_idx\: [int](class_int.md), pan\: [float](class_float.md)\ ) +- [float](class_float.md) **get_voice_pan**\ (\ voice_idx\: [int](class_int.md)\ ) const + +The voice's pan level. + +
+ + + + + +[float](class_float.md) **voice/2/rate_hz** = `1.2` [🔗](#class_AudioEffectChorus_property_voice/2/rate_hz) + + + +- `void` **set_voice_rate_hz**\ (\ voice_idx\: [int](class_int.md), rate_hz\: [float](class_float.md)\ ) +- [float](class_float.md) **get_voice_rate_hz**\ (\ voice_idx\: [int](class_int.md)\ ) const + +The voice's filter rate. + +
+ + + + + +[float](class_float.md) **voice/3/cutoff_hz** [🔗](#class_AudioEffectChorus_property_voice/3/cutoff_hz) + + + +- `void` **set_voice_cutoff_hz**\ (\ voice_idx\: [int](class_int.md), cutoff_hz\: [float](class_float.md)\ ) +- [float](class_float.md) **get_voice_cutoff_hz**\ (\ voice_idx\: [int](class_int.md)\ ) const + +The voice's cutoff frequency. + +
+ + + + + +[float](class_float.md) **voice/3/delay_ms** [🔗](#class_AudioEffectChorus_property_voice/3/delay_ms) + + + +- `void` **set_voice_delay_ms**\ (\ voice_idx\: [int](class_int.md), delay_ms\: [float](class_float.md)\ ) +- [float](class_float.md) **get_voice_delay_ms**\ (\ voice_idx\: [int](class_int.md)\ ) const + +The voice's signal delay. + +
+ + + + + +[float](class_float.md) **voice/3/depth_ms** [🔗](#class_AudioEffectChorus_property_voice/3/depth_ms) + + + +- `void` **set_voice_depth_ms**\ (\ voice_idx\: [int](class_int.md), depth_ms\: [float](class_float.md)\ ) +- [float](class_float.md) **get_voice_depth_ms**\ (\ voice_idx\: [int](class_int.md)\ ) const + +The voice filter's depth. + +
+ + + + + +[float](class_float.md) **voice/3/level_db** [🔗](#class_AudioEffectChorus_property_voice/3/level_db) + + + +- `void` **set_voice_level_db**\ (\ voice_idx\: [int](class_int.md), level_db\: [float](class_float.md)\ ) +- [float](class_float.md) **get_voice_level_db**\ (\ voice_idx\: [int](class_int.md)\ ) const + +The voice's volume. + +
+ + + + + +[float](class_float.md) **voice/3/pan** [🔗](#class_AudioEffectChorus_property_voice/3/pan) + + + +- `void` **set_voice_pan**\ (\ voice_idx\: [int](class_int.md), pan\: [float](class_float.md)\ ) +- [float](class_float.md) **get_voice_pan**\ (\ voice_idx\: [int](class_int.md)\ ) const + +The voice's pan level. + +
+ + + + + +[float](class_float.md) **voice/3/rate_hz** [🔗](#class_AudioEffectChorus_property_voice/3/rate_hz) + + + +- `void` **set_voice_rate_hz**\ (\ voice_idx\: [int](class_int.md), rate_hz\: [float](class_float.md)\ ) +- [float](class_float.md) **get_voice_rate_hz**\ (\ voice_idx\: [int](class_int.md)\ ) const + +The voice's filter rate. + +
+ + + + + +[float](class_float.md) **voice/4/cutoff_hz** [🔗](#class_AudioEffectChorus_property_voice/4/cutoff_hz) + + + +- `void` **set_voice_cutoff_hz**\ (\ voice_idx\: [int](class_int.md), cutoff_hz\: [float](class_float.md)\ ) +- [float](class_float.md) **get_voice_cutoff_hz**\ (\ voice_idx\: [int](class_int.md)\ ) const + +The voice's cutoff frequency. + +
+ + + + + +[float](class_float.md) **voice/4/delay_ms** [🔗](#class_AudioEffectChorus_property_voice/4/delay_ms) + + + +- `void` **set_voice_delay_ms**\ (\ voice_idx\: [int](class_int.md), delay_ms\: [float](class_float.md)\ ) +- [float](class_float.md) **get_voice_delay_ms**\ (\ voice_idx\: [int](class_int.md)\ ) const + +The voice's signal delay. + +
+ + + + + +[float](class_float.md) **voice/4/depth_ms** [🔗](#class_AudioEffectChorus_property_voice/4/depth_ms) + + + +- `void` **set_voice_depth_ms**\ (\ voice_idx\: [int](class_int.md), depth_ms\: [float](class_float.md)\ ) +- [float](class_float.md) **get_voice_depth_ms**\ (\ voice_idx\: [int](class_int.md)\ ) const + +The voice filter's depth. + +
+ + + + + +[float](class_float.md) **voice/4/level_db** [🔗](#class_AudioEffectChorus_property_voice/4/level_db) + + + +- `void` **set_voice_level_db**\ (\ voice_idx\: [int](class_int.md), level_db\: [float](class_float.md)\ ) +- [float](class_float.md) **get_voice_level_db**\ (\ voice_idx\: [int](class_int.md)\ ) const + +The voice's volume. + +
+ + + + + +[float](class_float.md) **voice/4/pan** [🔗](#class_AudioEffectChorus_property_voice/4/pan) + + + +- `void` **set_voice_pan**\ (\ voice_idx\: [int](class_int.md), pan\: [float](class_float.md)\ ) +- [float](class_float.md) **get_voice_pan**\ (\ voice_idx\: [int](class_int.md)\ ) const + +The voice's pan level. + +
+ + + + + +[float](class_float.md) **voice/4/rate_hz** [🔗](#class_AudioEffectChorus_property_voice/4/rate_hz) + + + +- `void` **set_voice_rate_hz**\ (\ voice_idx\: [int](class_int.md), rate_hz\: [float](class_float.md)\ ) +- [float](class_float.md) **get_voice_rate_hz**\ (\ voice_idx\: [int](class_int.md)\ ) const + +The voice's filter rate. + +
+ + + + + +[int](class_int.md) **voice_count** = `2` [🔗](#class_AudioEffectChorus_property_voice_count) + + + +- `void` **set_voice_count**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_voice_count**\ (\ ) + +The number of voices in the effect. + +
+ + + + + +[float](class_float.md) **wet** = `0.5` [🔗](#class_AudioEffectChorus_property_wet) + + + +- `void` **set_wet**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_wet**\ (\ ) + +The effect's processed signal. + +
+ + + +## Method Descriptions + + + + + +[float](class_float.md) **get_voice_cutoff_hz**\ (\ voice_idx\: [int](class_int.md)\ ) const [🔗](#class_AudioEffectChorus_method_get_voice_cutoff_hz) + +
+There is currently no description for this method. Please help us by contributing one! + +
+ +
+ + + + + +[float](class_float.md) **get_voice_delay_ms**\ (\ voice_idx\: [int](class_int.md)\ ) const [🔗](#class_AudioEffectChorus_method_get_voice_delay_ms) + +
+There is currently no description for this method. Please help us by contributing one! + +
+ +
+ + + + + +[float](class_float.md) **get_voice_depth_ms**\ (\ voice_idx\: [int](class_int.md)\ ) const [🔗](#class_AudioEffectChorus_method_get_voice_depth_ms) + +
+There is currently no description for this method. Please help us by contributing one! + +
+ +
+ + + + + +[float](class_float.md) **get_voice_level_db**\ (\ voice_idx\: [int](class_int.md)\ ) const [🔗](#class_AudioEffectChorus_method_get_voice_level_db) + +
+There is currently no description for this method. Please help us by contributing one! + +
+ +
+ + + + + +[float](class_float.md) **get_voice_pan**\ (\ voice_idx\: [int](class_int.md)\ ) const [🔗](#class_AudioEffectChorus_method_get_voice_pan) + +
+There is currently no description for this method. Please help us by contributing one! + +
+ +
+ + + + + +[float](class_float.md) **get_voice_rate_hz**\ (\ voice_idx\: [int](class_int.md)\ ) const [🔗](#class_AudioEffectChorus_method_get_voice_rate_hz) + +
+There is currently no description for this method. Please help us by contributing one! + +
+ +
+ + + + + +`void` **set_voice_cutoff_hz**\ (\ voice_idx\: [int](class_int.md), cutoff_hz\: [float](class_float.md)\ ) [🔗](#class_AudioEffectChorus_method_set_voice_cutoff_hz) + +
+There is currently no description for this method. Please help us by contributing one! + +
+ +
+ + + + + +`void` **set_voice_delay_ms**\ (\ voice_idx\: [int](class_int.md), delay_ms\: [float](class_float.md)\ ) [🔗](#class_AudioEffectChorus_method_set_voice_delay_ms) + +
+There is currently no description for this method. Please help us by contributing one! + +
+ +
+ + + + + +`void` **set_voice_depth_ms**\ (\ voice_idx\: [int](class_int.md), depth_ms\: [float](class_float.md)\ ) [🔗](#class_AudioEffectChorus_method_set_voice_depth_ms) + +
+There is currently no description for this method. Please help us by contributing one! + +
+ +
+ + + + + +`void` **set_voice_level_db**\ (\ voice_idx\: [int](class_int.md), level_db\: [float](class_float.md)\ ) [🔗](#class_AudioEffectChorus_method_set_voice_level_db) + +
+There is currently no description for this method. Please help us by contributing one! + +
+ +
+ + + + + +`void` **set_voice_pan**\ (\ voice_idx\: [int](class_int.md), pan\: [float](class_float.md)\ ) [🔗](#class_AudioEffectChorus_method_set_voice_pan) + +
+There is currently no description for this method. Please help us by contributing one! + +
+ +
+ + + + + +`void` **set_voice_rate_hz**\ (\ voice_idx\: [int](class_int.md), rate_hz\: [float](class_float.md)\ ) [🔗](#class_AudioEffectChorus_method_set_voice_rate_hz) + +
+There is currently no description for this method. Please help us by contributing one! + +
+ diff --git a/docs/Classes/class_audioeffectcompressor.md b/docs/Classes/class_audioeffectcompressor.md new file mode 100644 index 00000000..bb1db89f --- /dev/null +++ b/docs/Classes/class_audioeffectcompressor.md @@ -0,0 +1,194 @@ + + + + + + + + + +# AudioEffectCompressor + +**Inherits:** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +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. + + + +## 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](class_audioeffecthardlimiter.md) 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. + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[attack_us](#class_AudioEffectCompressor_property_attack_us)`20.0`
[float](class_float.md)[gain](#class_AudioEffectCompressor_property_gain)`0.0`
[float](class_float.md)[mix](#class_AudioEffectCompressor_property_mix)`1.0`
[float](class_float.md)[ratio](#class_AudioEffectCompressor_property_ratio)`4.0`
[float](class_float.md)[release_ms](#class_AudioEffectCompressor_property_release_ms)`250.0`
[StringName](class_stringname.md)[sidechain](#class_AudioEffectCompressor_property_sidechain)`&""`
[float](class_float.md)[threshold](#class_AudioEffectCompressor_property_threshold)`0.0`
+ +
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **attack_us** = `20.0` [🔗](#class_AudioEffectCompressor_property_attack_us) + + + +- `void` **set_attack_us**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_attack_us**\ (\ ) + +Compressor's reaction time when the signal exceeds the threshold, in microseconds. Value can range from 20 to 2000. + +
+ + + + + +[float](class_float.md) **gain** = `0.0` [🔗](#class_AudioEffectCompressor_property_gain) + + + +- `void` **set_gain**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_gain**\ (\ ) + +Gain applied to the output signal. + +
+ + + + + +[float](class_float.md) **mix** = `1.0` [🔗](#class_AudioEffectCompressor_property_mix) + + + +- `void` **set_mix**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_mix**\ (\ ) + +Balance between original signal and effect signal. Value can range from 0 (totally dry) to 1 (totally wet). + +
+ + + + + +[float](class_float.md) **ratio** = `4.0` [🔗](#class_AudioEffectCompressor_property_ratio) + + + +- `void` **set_ratio**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_ratio**\ (\ ) + +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. + +
+ + + + + +[float](class_float.md) **release_ms** = `250.0` [🔗](#class_AudioEffectCompressor_property_release_ms) + + + +- `void` **set_release_ms**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_release_ms**\ (\ ) + +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. + +
+ + + + + +[StringName](class_stringname.md) **sidechain** = `&""` [🔗](#class_AudioEffectCompressor_property_sidechain) + + + +- `void` **set_sidechain**\ (\ value\: [StringName](class_stringname.md)\ ) +- [StringName](class_stringname.md) **get_sidechain**\ (\ ) + +Reduce the sound level using another audio bus for threshold detection. + +
+ + + + + +[float](class_float.md) **threshold** = `0.0` [🔗](#class_AudioEffectCompressor_property_threshold) + + + +- `void` **set_threshold**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_threshold**\ (\ ) + +The level above which compression is applied to the audio. Value can range from -60 to 0. + diff --git a/docs/Classes/class_audioeffectdelay.md b/docs/Classes/class_audioeffectdelay.md new file mode 100644 index 00000000..87c33561 --- /dev/null +++ b/docs/Classes/class_audioeffectdelay.md @@ -0,0 +1,304 @@ + + + + + + + + + +# AudioEffectDelay + +**Inherits:** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Adds a delay audio effect to an audio bus. Plays input signal back after a period of time. + +Two tap delay and feedback options. + + + +## 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. + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[dry](#class_AudioEffectDelay_property_dry)`1.0`
[bool](class_bool.md)[feedback_active](#class_AudioEffectDelay_property_feedback_active)`false`
[float](class_float.md)[feedback_delay_ms](#class_AudioEffectDelay_property_feedback_delay_ms)`340.0`
[float](class_float.md)[feedback_level_db](#class_AudioEffectDelay_property_feedback_level_db)`-6.0`
[float](class_float.md)[feedback_lowpass](#class_AudioEffectDelay_property_feedback_lowpass)`16000.0`
[bool](class_bool.md)[tap1_active](#class_AudioEffectDelay_property_tap1_active)`true`
[float](class_float.md)[tap1_delay_ms](#class_AudioEffectDelay_property_tap1_delay_ms)`250.0`
[float](class_float.md)[tap1_level_db](#class_AudioEffectDelay_property_tap1_level_db)`-6.0`
[float](class_float.md)[tap1_pan](#class_AudioEffectDelay_property_tap1_pan)`0.2`
[bool](class_bool.md)[tap2_active](#class_AudioEffectDelay_property_tap2_active)`true`
[float](class_float.md)[tap2_delay_ms](#class_AudioEffectDelay_property_tap2_delay_ms)`500.0`
[float](class_float.md)[tap2_level_db](#class_AudioEffectDelay_property_tap2_level_db)`-12.0`
[float](class_float.md)[tap2_pan](#class_AudioEffectDelay_property_tap2_pan)`-0.4`
+ +
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **dry** = `1.0` [🔗](#class_AudioEffectDelay_property_dry) + + + +- `void` **set_dry**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_dry**\ (\ ) + +Output percent of original sound. At 0, only delayed sounds are output. Value can range from 0 to 1. + +
+ + + + + +[bool](class_bool.md) **feedback_active** = `false` [🔗](#class_AudioEffectDelay_property_feedback_active) + + + +- `void` **set_feedback_active**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_feedback_active**\ (\ ) + +If ``true``, feedback is enabled. + +
+ + + + + +[float](class_float.md) **feedback_delay_ms** = `340.0` [🔗](#class_AudioEffectDelay_property_feedback_delay_ms) + + + +- `void` **set_feedback_delay_ms**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_feedback_delay_ms**\ (\ ) + +Feedback delay time in milliseconds. + +
+ + + + + +[float](class_float.md) **feedback_level_db** = `-6.0` [🔗](#class_AudioEffectDelay_property_feedback_level_db) + + + +- `void` **set_feedback_level_db**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_feedback_level_db**\ (\ ) + +Sound level for feedback. + +
+ + + + + +[float](class_float.md) **feedback_lowpass** = `16000.0` [🔗](#class_AudioEffectDelay_property_feedback_lowpass) + + + +- `void` **set_feedback_lowpass**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_feedback_lowpass**\ (\ ) + +Low-pass filter for feedback, in Hz. Frequencies below this value are filtered out of the source signal. + +
+ + + + + +[bool](class_bool.md) **tap1_active** = `true` [🔗](#class_AudioEffectDelay_property_tap1_active) + + + +- `void` **set_tap1_active**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_tap1_active**\ (\ ) + +If ``true``, the first tap will be enabled. + +
+ + + + + +[float](class_float.md) **tap1_delay_ms** = `250.0` [🔗](#class_AudioEffectDelay_property_tap1_delay_ms) + + + +- `void` **set_tap1_delay_ms**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_tap1_delay_ms**\ (\ ) + +First tap delay time in milliseconds. + +
+ + + + + +[float](class_float.md) **tap1_level_db** = `-6.0` [🔗](#class_AudioEffectDelay_property_tap1_level_db) + + + +- `void` **set_tap1_level_db**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_tap1_level_db**\ (\ ) + +Sound level for the first tap. + +
+ + + + + +[float](class_float.md) **tap1_pan** = `0.2` [🔗](#class_AudioEffectDelay_property_tap1_pan) + + + +- `void` **set_tap1_pan**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_tap1_pan**\ (\ ) + +Pan position for the first tap. Value can range from -1 (fully left) to 1 (fully right). + +
+ + + + + +[bool](class_bool.md) **tap2_active** = `true` [🔗](#class_AudioEffectDelay_property_tap2_active) + + + +- `void` **set_tap2_active**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_tap2_active**\ (\ ) + +If ``true``, the second tap will be enabled. + +
+ + + + + +[float](class_float.md) **tap2_delay_ms** = `500.0` [🔗](#class_AudioEffectDelay_property_tap2_delay_ms) + + + +- `void` **set_tap2_delay_ms**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_tap2_delay_ms**\ (\ ) + +Second tap delay time in milliseconds. + +
+ + + + + +[float](class_float.md) **tap2_level_db** = `-12.0` [🔗](#class_AudioEffectDelay_property_tap2_level_db) + + + +- `void` **set_tap2_level_db**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_tap2_level_db**\ (\ ) + +Sound level for the second tap. + +
+ + + + + +[float](class_float.md) **tap2_pan** = `-0.4` [🔗](#class_AudioEffectDelay_property_tap2_pan) + + + +- `void` **set_tap2_pan**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_tap2_pan**\ (\ ) + +Pan position for the second tap. Value can range from -1 (fully left) to 1 (fully right). + diff --git a/docs/Classes/class_audioeffectdistortion.md b/docs/Classes/class_audioeffectdistortion.md new file mode 100644 index 00000000..c38e915f --- /dev/null +++ b/docs/Classes/class_audioeffectdistortion.md @@ -0,0 +1,193 @@ + + + + + + + + + +# AudioEffectDistortion + +**Inherits:** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Adds a distortion audio effect to an Audio bus. + +Modifies the sound to make it distorted. + + + +## 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. + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[drive](#class_AudioEffectDistortion_property_drive)`0.0`
[float](class_float.md)[keep_hf_hz](#class_AudioEffectDistortion_property_keep_hf_hz)`16000.0`
[Mode](class_audioeffectdistortion.md#enum_AudioEffectDistortion_Mode)[mode](#class_AudioEffectDistortion_property_mode)`0`
[float](class_float.md)[post_gain](#class_AudioEffectDistortion_property_post_gain)`0.0`
[float](class_float.md)[pre_gain](#class_AudioEffectDistortion_property_pre_gain)`0.0`
+ +
+ + + +## Enumerations + + + + + +enum **Mode**: [🔗](#enum_AudioEffectDistortion_Mode) + + + + + +[Mode](class_audioeffectdistortion.md#enum_AudioEffectDistortion_Mode) **MODE_CLIP** = `0` + +Digital distortion effect which cuts off peaks at the top and bottom of the waveform. + + + +[Mode](class_audioeffectdistortion.md#enum_AudioEffectDistortion_Mode) **MODE_ATAN** = `1` + +
+There is currently no description for this enum. Please help us by contributing one! + +
+ + + + + +[Mode](class_audioeffectdistortion.md#enum_AudioEffectDistortion_Mode) **MODE_LOFI** = `2` + +Low-resolution digital distortion effect (bit depth reduction). You can use it to emulate the sound of early digital audio devices. + + + +[Mode](class_audioeffectdistortion.md#enum_AudioEffectDistortion_Mode) **MODE_OVERDRIVE** = `3` + +Emulates the warm distortion produced by a field effect transistor, which is commonly used in solid-state musical instrument amplifiers. The [drive](class_audioeffectdistortion.md#class_AudioEffectDistortion_property_drive) property has no effect in this mode. + + + +[Mode](class_audioeffectdistortion.md#enum_AudioEffectDistortion_Mode) **MODE_WAVESHAPE** = `4` + +Waveshaper distortions are used mainly by electronic musicians to achieve an extra-abrasive sound.
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **drive** = `0.0` [🔗](#class_AudioEffectDistortion_property_drive) + + + +- `void` **set_drive**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_drive**\ (\ ) + +Distortion power. Value can range from 0 to 1. + +
+ + + + + +[float](class_float.md) **keep_hf_hz** = `16000.0` [🔗](#class_AudioEffectDistortion_property_keep_hf_hz) + + + +- `void` **set_keep_hf_hz**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_keep_hf_hz**\ (\ ) + +High-pass filter, in Hz. Frequencies higher than this value will not be affected by the distortion. Value can range from 1 to 20000. + +
+ + + + + +[Mode](class_audioeffectdistortion.md#enum_AudioEffectDistortion_Mode) **mode** = `0` [🔗](#class_AudioEffectDistortion_property_mode) + + + +- `void` **set_mode**\ (\ value\: [Mode](class_audioeffectdistortion.md#enum_AudioEffectDistortion_Mode)\ ) +- [Mode](class_audioeffectdistortion.md#enum_AudioEffectDistortion_Mode) **get_mode**\ (\ ) + +Distortion type. + +
+ + + + + +[float](class_float.md) **post_gain** = `0.0` [🔗](#class_AudioEffectDistortion_property_post_gain) + + + +- `void` **set_post_gain**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_post_gain**\ (\ ) + +Increases or decreases the volume after the effect, in decibels. Value can range from -80 to 24. + +
+ + + + + +[float](class_float.md) **pre_gain** = `0.0` [🔗](#class_AudioEffectDistortion_property_pre_gain) + + + +- `void` **set_pre_gain**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_pre_gain**\ (\ ) + +Increases or decreases the volume before the effect, in decibels. Value can range from -60 to 60. + diff --git a/docs/Classes/class_audioeffecteq.md b/docs/Classes/class_audioeffecteq.md new file mode 100644 index 00000000..c3423be0 --- /dev/null +++ b/docs/Classes/class_audioeffecteq.md @@ -0,0 +1,88 @@ + + + + + + + + + +# AudioEffectEQ + +**Inherits:** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +**Inherited By:** [AudioEffectEQ10](class_audioeffecteq10.md), [AudioEffectEQ21](class_audioeffecteq21.md), [AudioEffectEQ6](class_audioeffecteq6.md) + +Base class for audio equalizers. Gives you control over frequencies. + +Use it to create a custom equalizer if [AudioEffectEQ6](class_audioeffecteq6.md), [AudioEffectEQ10](class_audioeffecteq10.md) or [AudioEffectEQ21](class_audioeffecteq21.md) don't fit your needs. + + + +## 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). + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + + + +## Methods + + + + + + + + + + + + + + + + + + +
[int](class_int.md)[get_band_count](#class_AudioEffectEQ_method_get_band_count)\ (\ ) const
[float](class_float.md)[get_band_gain_db](#class_AudioEffectEQ_method_get_band_gain_db)\ (\ band_idx\: [int](class_int.md)\ ) const
`void`[set_band_gain_db](#class_AudioEffectEQ_method_set_band_gain_db)\ (\ band_idx\: [int](class_int.md), volume_db\: [float](class_float.md)\ )
+ +
+ + + +## Method Descriptions + + + + + +[int](class_int.md) **get_band_count**\ (\ ) const [🔗](#class_AudioEffectEQ_method_get_band_count) + +Returns the number of bands of the equalizer. + +
+ + + + + +[float](class_float.md) **get_band_gain_db**\ (\ band_idx\: [int](class_int.md)\ ) const [🔗](#class_AudioEffectEQ_method_get_band_gain_db) + +Returns the band's gain at the specified index, in dB. + +
+ + + + + +`void` **set_band_gain_db**\ (\ band_idx\: [int](class_int.md), volume_db\: [float](class_float.md)\ ) [🔗](#class_AudioEffectEQ_method_set_band_gain_db) + +Sets band's gain at the specified index, in dB. + diff --git a/docs/Classes/class_audioeffecteq10.md b/docs/Classes/class_audioeffecteq10.md new file mode 100644 index 00000000..29304c3a --- /dev/null +++ b/docs/Classes/class_audioeffecteq10.md @@ -0,0 +1,51 @@ + + + + + + + + + +# AudioEffectEQ10 + +**Inherits:** [AudioEffectEQ](class_audioeffecteq.md) **<** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +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. + + + +## 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](class_audioeffecteq.md), [AudioEffectEQ6](class_audioeffecteq6.md), [AudioEffectEQ21](class_audioeffecteq21.md). + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + diff --git a/docs/Classes/class_audioeffecteq21.md b/docs/Classes/class_audioeffecteq21.md new file mode 100644 index 00000000..c415d3d2 --- /dev/null +++ b/docs/Classes/class_audioeffecteq21.md @@ -0,0 +1,73 @@ + + + + + + + + + +# AudioEffectEQ21 + +**Inherits:** [AudioEffectEQ](class_audioeffecteq.md) **<** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +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. + + + +## 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](class_audioeffecteq.md), [AudioEffectEQ6](class_audioeffecteq6.md), [AudioEffectEQ10](class_audioeffecteq10.md). + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + diff --git a/docs/Classes/class_audioeffecteq6.md b/docs/Classes/class_audioeffecteq6.md new file mode 100644 index 00000000..e9c86fa5 --- /dev/null +++ b/docs/Classes/class_audioeffecteq6.md @@ -0,0 +1,43 @@ + + + + + + + + + +# AudioEffectEQ6 + +**Inherits:** [AudioEffectEQ](class_audioeffecteq.md) **<** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +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. + + + +## 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](class_audioeffecteq.md), [AudioEffectEQ10](class_audioeffecteq10.md), [AudioEffectEQ21](class_audioeffecteq21.md). + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + diff --git a/docs/Classes/class_audioeffectfilter.md b/docs/Classes/class_audioeffectfilter.md new file mode 100644 index 00000000..84c23425 --- /dev/null +++ b/docs/Classes/class_audioeffectfilter.md @@ -0,0 +1,160 @@ + + + + + + + + + +# AudioEffectFilter + +**Inherits:** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +**Inherited By:** [AudioEffectBandLimitFilter](class_audioeffectbandlimitfilter.md), [AudioEffectBandPassFilter](class_audioeffectbandpassfilter.md), [AudioEffectHighPassFilter](class_audioeffecthighpassfilter.md), [AudioEffectHighShelfFilter](class_audioeffecthighshelffilter.md), [AudioEffectLowPassFilter](class_audioeffectlowpassfilter.md), [AudioEffectLowShelfFilter](class_audioeffectlowshelffilter.md), [AudioEffectNotchFilter](class_audioeffectnotchfilter.md) + +Adds a filter to the audio bus. + + + +## Description + +Allows frequencies other than the [cutoff_hz](class_audioeffectfilter.md#class_AudioEffectFilter_property_cutoff_hz) to pass. + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[cutoff_hz](#class_AudioEffectFilter_property_cutoff_hz)`2000.0`
[FilterDB](class_audioeffectfilter.md#enum_AudioEffectFilter_FilterDB)[db](#class_AudioEffectFilter_property_db)`0`
[float](class_float.md)[gain](#class_AudioEffectFilter_property_gain)`1.0`
[float](class_float.md)[resonance](#class_AudioEffectFilter_property_resonance)`0.5`
+ +
+ + + +## Enumerations + + + + + +enum **FilterDB**: [🔗](#enum_AudioEffectFilter_FilterDB) + + + + + +[FilterDB](class_audioeffectfilter.md#enum_AudioEffectFilter_FilterDB) **FILTER_6DB** = `0` + +Cutting off at 6dB per octave. + + + +[FilterDB](class_audioeffectfilter.md#enum_AudioEffectFilter_FilterDB) **FILTER_12DB** = `1` + +Cutting off at 12dB per octave. + + + +[FilterDB](class_audioeffectfilter.md#enum_AudioEffectFilter_FilterDB) **FILTER_18DB** = `2` + +Cutting off at 18dB per octave. + + + +[FilterDB](class_audioeffectfilter.md#enum_AudioEffectFilter_FilterDB) **FILTER_24DB** = `3` + +Cutting off at 24dB per octave.
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **cutoff_hz** = `2000.0` [🔗](#class_AudioEffectFilter_property_cutoff_hz) + + + +- `void` **set_cutoff**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_cutoff**\ (\ ) + +Threshold frequency for the filter, in Hz. + +
+ + + + + +[FilterDB](class_audioeffectfilter.md#enum_AudioEffectFilter_FilterDB) **db** = `0` [🔗](#class_AudioEffectFilter_property_db) + + + +- `void` **set_db**\ (\ value\: [FilterDB](class_audioeffectfilter.md#enum_AudioEffectFilter_FilterDB)\ ) +- [FilterDB](class_audioeffectfilter.md#enum_AudioEffectFilter_FilterDB) **get_db**\ (\ ) + +Steepness of the cutoff curve in dB per octave, also known as the order of the filter. Higher orders have a more aggressive cutoff. + +
+ + + + + +[float](class_float.md) **gain** = `1.0` [🔗](#class_AudioEffectFilter_property_gain) + + + +- `void` **set_gain**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_gain**\ (\ ) + +Gain amount of the frequencies after the filter. + +
+ + + + + +[float](class_float.md) **resonance** = `0.5` [🔗](#class_AudioEffectFilter_property_resonance) + + + +- `void` **set_resonance**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_resonance**\ (\ ) + +Amount of boost in the frequency range near the cutoff frequency. + diff --git a/docs/Classes/class_audioeffecthardlimiter.md b/docs/Classes/class_audioeffecthardlimiter.md new file mode 100644 index 00000000..be99b560 --- /dev/null +++ b/docs/Classes/class_audioeffecthardlimiter.md @@ -0,0 +1,104 @@ + + + + + + + + + +# AudioEffectHardLimiter + +**Inherits:** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Adds a hard limiter audio effect to an Audio bus. + + + +## 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. + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[ceiling_db](#class_AudioEffectHardLimiter_property_ceiling_db)`-0.3`
[float](class_float.md)[pre_gain_db](#class_AudioEffectHardLimiter_property_pre_gain_db)`0.0`
[float](class_float.md)[release](#class_AudioEffectHardLimiter_property_release)`0.1`
+ +
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **ceiling_db** = `-0.3` [🔗](#class_AudioEffectHardLimiter_property_ceiling_db) + + + +- `void` **set_ceiling_db**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_ceiling_db**\ (\ ) + +The waveform's maximum allowed value, in decibels. This value can range from ``-24.0`` to ``0.0``. + +The default value of ``-0.3`` prevents potential inter-sample peaks (ISP) from crossing over 0 dB, which can cause slight distortion on some older hardware. + +
+ + + + + +[float](class_float.md) **pre_gain_db** = `0.0` [🔗](#class_AudioEffectHardLimiter_property_pre_gain_db) + + + +- `void` **set_pre_gain_db**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_pre_gain_db**\ (\ ) + +Gain to apply before limiting, in decibels. + +
+ + + + + +[float](class_float.md) **release** = `0.1` [🔗](#class_AudioEffectHardLimiter_property_release) + + + +- `void` **set_release**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_release**\ (\ ) + +Time it takes in seconds for the gain reduction to fully release. + diff --git a/docs/Classes/class_audioeffecthighpassfilter.md b/docs/Classes/class_audioeffecthighpassfilter.md new file mode 100644 index 00000000..cdc40e4d --- /dev/null +++ b/docs/Classes/class_audioeffecthighpassfilter.md @@ -0,0 +1,27 @@ + + + + + + + + + +# AudioEffectHighPassFilter + +**Inherits:** [AudioEffectFilter](class_audioeffectfilter.md) **<** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Adds a high-pass filter to the audio bus. + + + +## Description + +Cuts frequencies lower than the [AudioEffectFilter.cutoff_hz](class_audioeffectfilter.md#class_AudioEffectFilter_property_cutoff_hz) and allows higher frequencies to pass. + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + diff --git a/docs/Classes/class_audioeffecthighshelffilter.md b/docs/Classes/class_audioeffecthighshelffilter.md new file mode 100644 index 00000000..35a8a7ee --- /dev/null +++ b/docs/Classes/class_audioeffecthighshelffilter.md @@ -0,0 +1,27 @@ + + + + + + + + + +# AudioEffectHighShelfFilter + +**Inherits:** [AudioEffectFilter](class_audioeffectfilter.md) **<** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Adds a high-shelf filter to the audio bus. + + + +## Description + +Reduces all frequencies above the [AudioEffectFilter.cutoff_hz](class_audioeffectfilter.md#class_AudioEffectFilter_property_cutoff_hz). + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + diff --git a/docs/Classes/class_audioeffectinstance.md b/docs/Classes/class_audioeffectinstance.md new file mode 100644 index 00000000..f351dfb2 --- /dev/null +++ b/docs/Classes/class_audioeffectinstance.md @@ -0,0 +1,76 @@ + + + + + + + + + +# AudioEffectInstance + +**Inherits:** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +**Inherited By:** [AudioEffectSpectrumAnalyzerInstance](class_audioeffectspectrumanalyzerinstance.md) + +Manipulates the audio it receives for a given effect. + + + +## Description + +An audio effect instance manipulates the audio it receives for a given effect. This instance is automatically created by an [AudioEffect](class_audioeffect.md) when it is added to a bus, and should usually not be created directly. If necessary, it can be fetched at run-time with [AudioServer.get_bus_effect_instance()](class_audioserver.md#class_AudioServer_method_get_bus_effect_instance). + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + + + +## Methods + + + + + + + + + + + + + + +
`void`[_process](#class_AudioEffectInstance_private_method__process)\ (\ src_buffer\: `const void*`, dst_buffer\: `AudioFrame*`, frame_count\: [int](class_int.md)\ ) virtual required
[bool](class_bool.md)[_process_silence](#class_AudioEffectInstance_private_method__process_silence)\ (\ ) virtual const
+ +
+ + + +## Method Descriptions + + + + + +`void` **_process**\ (\ src_buffer\: `const void*`, dst_buffer\: `AudioFrame*`, frame_count\: [int](class_int.md)\ ) virtual required [🔗](#class_AudioEffectInstance_private_method__process) + +Called by the [AudioServer](class_audioserver.md) to process this effect. When [_process_silence()](class_audioeffectinstance.md#class_AudioEffectInstance_private_method__process_silence) is not overridden or it returns ``false``, this method is called only when the bus is active. + +\ **Note:** It is not useful to override this method in GDScript or C#. Only GDExtension can take advantage of it. + +
+ + + + + +[bool](class_bool.md) **_process_silence**\ (\ ) virtual const [🔗](#class_AudioEffectInstance_private_method__process_silence) + +Override this method to customize the processing behavior of this effect instance. + +Should return ``true`` to force the [AudioServer](class_audioserver.md) to always call [_process()](class_audioeffectinstance.md#class_AudioEffectInstance_private_method__process), even if the bus has been muted or cannot otherwise be heard. + diff --git a/docs/Classes/class_audioeffectlimiter.md b/docs/Classes/class_audioeffectlimiter.md new file mode 100644 index 00000000..2a03cbd2 --- /dev/null +++ b/docs/Classes/class_audioeffectlimiter.md @@ -0,0 +1,129 @@ + + + + + + + + + +# AudioEffectLimiter + +**Deprecated:** Use [AudioEffectHardLimiter](class_audioeffecthardlimiter.md) instead. + +**Inherits:** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Adds a soft-clip limiter audio effect to an Audio bus. + + + +## 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. + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[ceiling_db](#class_AudioEffectLimiter_property_ceiling_db)`-0.1`
[float](class_float.md)[soft_clip_db](#class_AudioEffectLimiter_property_soft_clip_db)`2.0`
[float](class_float.md)[soft_clip_ratio](#class_AudioEffectLimiter_property_soft_clip_ratio)`10.0`
[float](class_float.md)[threshold_db](#class_AudioEffectLimiter_property_threshold_db)`0.0`
+ +
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **ceiling_db** = `-0.1` [🔗](#class_AudioEffectLimiter_property_ceiling_db) + + + +- `void` **set_ceiling_db**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_ceiling_db**\ (\ ) + +The waveform's maximum allowed value, in decibels. Value can range from -20 to -0.1. + +
+ + + + + +[float](class_float.md) **soft_clip_db** = `2.0` [🔗](#class_AudioEffectLimiter_property_soft_clip_db) + + + +- `void` **set_soft_clip_db**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_soft_clip_db**\ (\ ) + +Applies a gain to the limited waves, in decibels. Value can range from 0 to 6. + +
+ + + + + +[float](class_float.md) **soft_clip_ratio** = `10.0` [🔗](#class_AudioEffectLimiter_property_soft_clip_ratio) + + + +- `void` **set_soft_clip_ratio**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_soft_clip_ratio**\ (\ ) + +
+There is currently no description for this property. Please help us by contributing one! + +
+ +
+ + + + + +[float](class_float.md) **threshold_db** = `0.0` [🔗](#class_AudioEffectLimiter_property_threshold_db) + + + +- `void` **set_threshold_db**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_threshold_db**\ (\ ) + +Threshold from which the limiter begins to be active, in decibels. Value can range from -30 to 0. + diff --git a/docs/Classes/class_audioeffectlowpassfilter.md b/docs/Classes/class_audioeffectlowpassfilter.md new file mode 100644 index 00000000..44edaa3a --- /dev/null +++ b/docs/Classes/class_audioeffectlowpassfilter.md @@ -0,0 +1,27 @@ + + + + + + + + + +# AudioEffectLowPassFilter + +**Inherits:** [AudioEffectFilter](class_audioeffectfilter.md) **<** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Adds a low-pass filter to the audio bus. + + + +## Description + +Cuts frequencies higher than the [AudioEffectFilter.cutoff_hz](class_audioeffectfilter.md#class_AudioEffectFilter_property_cutoff_hz) and allows lower frequencies to pass. + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + diff --git a/docs/Classes/class_audioeffectlowshelffilter.md b/docs/Classes/class_audioeffectlowshelffilter.md new file mode 100644 index 00000000..1ce9e1f1 --- /dev/null +++ b/docs/Classes/class_audioeffectlowshelffilter.md @@ -0,0 +1,27 @@ + + + + + + + + + +# AudioEffectLowShelfFilter + +**Inherits:** [AudioEffectFilter](class_audioeffectfilter.md) **<** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Adds a low-shelf filter to the audio bus. + + + +## Description + +Reduces all frequencies below the [AudioEffectFilter.cutoff_hz](class_audioeffectfilter.md#class_AudioEffectFilter_property_cutoff_hz). + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + diff --git a/docs/Classes/class_audioeffectnotchfilter.md b/docs/Classes/class_audioeffectnotchfilter.md new file mode 100644 index 00000000..972206fa --- /dev/null +++ b/docs/Classes/class_audioeffectnotchfilter.md @@ -0,0 +1,27 @@ + + + + + + + + + +# AudioEffectNotchFilter + +**Inherits:** [AudioEffectFilter](class_audioeffectfilter.md) **<** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Adds a notch filter to the Audio bus. + + + +## Description + +Attenuates frequencies in a narrow band around the [AudioEffectFilter.cutoff_hz](class_audioeffectfilter.md#class_AudioEffectFilter_property_cutoff_hz) and cuts frequencies outside of this range. + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + diff --git a/docs/Classes/class_audioeffectpanner.md b/docs/Classes/class_audioeffectpanner.md new file mode 100644 index 00000000..178c6b60 --- /dev/null +++ b/docs/Classes/class_audioeffectpanner.md @@ -0,0 +1,62 @@ + + + + + + + + + +# AudioEffectPanner + +**Inherits:** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Adds a panner audio effect to an audio bus. Pans sound left or right. + + + +## Description + +Determines how much of an audio signal is sent to the left and right buses. + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + + + +## Properties + + + + + + + + + + + +
[float](class_float.md)[pan](#class_AudioEffectPanner_property_pan)`0.0`
+ +
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **pan** = `0.0` [🔗](#class_AudioEffectPanner_property_pan) + + + +- `void` **set_pan**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_pan**\ (\ ) + +Pan position. Value can range from -1 (fully left) to 1 (fully right). + diff --git a/docs/Classes/class_audioeffectphaser.md b/docs/Classes/class_audioeffectphaser.md new file mode 100644 index 00000000..59c4c1a8 --- /dev/null +++ b/docs/Classes/class_audioeffectphaser.md @@ -0,0 +1,144 @@ + + + + + + + + + +# AudioEffectPhaser + +**Inherits:** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +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. + + + +## Description + +Combines phase-shifted signals with the original signal. The movement of the phase-shifted signals is controlled using a low-frequency oscillator. + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[depth](#class_AudioEffectPhaser_property_depth)`1.0`
[float](class_float.md)[feedback](#class_AudioEffectPhaser_property_feedback)`0.7`
[float](class_float.md)[range_max_hz](#class_AudioEffectPhaser_property_range_max_hz)`1600.0`
[float](class_float.md)[range_min_hz](#class_AudioEffectPhaser_property_range_min_hz)`440.0`
[float](class_float.md)[rate_hz](#class_AudioEffectPhaser_property_rate_hz)`0.5`
+ +
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **depth** = `1.0` [🔗](#class_AudioEffectPhaser_property_depth) + + + +- `void` **set_depth**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_depth**\ (\ ) + +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 ``0.1`` to ``4.0``. + +
+ + + + + +[float](class_float.md) **feedback** = `0.7` [🔗](#class_AudioEffectPhaser_property_feedback) + + + +- `void` **set_feedback**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_feedback**\ (\ ) + +Output percent of modified sound. Value can range from 0.1 to 0.9. + +
+ + + + + +[float](class_float.md) **range_max_hz** = `1600.0` [🔗](#class_AudioEffectPhaser_property_range_max_hz) + + + +- `void` **set_range_max_hz**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_range_max_hz**\ (\ ) + +Determines the maximum frequency affected by the LFO modulations, in Hz. Value can range from 10 to 10000. + +
+ + + + + +[float](class_float.md) **range_min_hz** = `440.0` [🔗](#class_AudioEffectPhaser_property_range_min_hz) + + + +- `void` **set_range_min_hz**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_range_min_hz**\ (\ ) + +Determines the minimum frequency affected by the LFO modulations, in Hz. Value can range from 10 to 10000. + +
+ + + + + +[float](class_float.md) **rate_hz** = `0.5` [🔗](#class_AudioEffectPhaser_property_rate_hz) + + + +- `void` **set_rate_hz**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_rate_hz**\ (\ ) + +Adjusts the rate in Hz at which the effect sweeps up and down across the frequency range. + diff --git a/docs/Classes/class_audioeffectpitchshift.md b/docs/Classes/class_audioeffectpitchshift.md new file mode 100644 index 00000000..b5cce92a --- /dev/null +++ b/docs/Classes/class_audioeffectpitchshift.md @@ -0,0 +1,152 @@ + + + + + + + + + +# AudioEffectPitchShift + +**Inherits:** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Adds a pitch-shifting audio effect to an audio bus. + +Raises or lowers the pitch of original sound. + + + +## Description + +Allows modulation of pitch independently of tempo. All frequencies can be increased/decreased with minimal effect on transients. + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + +
[FFTSize](class_audioeffectpitchshift.md#enum_AudioEffectPitchShift_FFTSize)[fft_size](#class_AudioEffectPitchShift_property_fft_size)`3`
[int](class_int.md)[oversampling](#class_AudioEffectPitchShift_property_oversampling)`4`
[float](class_float.md)[pitch_scale](#class_AudioEffectPitchShift_property_pitch_scale)`1.0`
+ +
+ + + +## Enumerations + + + + + +enum **FFTSize**: [🔗](#enum_AudioEffectPitchShift_FFTSize) + + + + + +[FFTSize](class_audioeffectpitchshift.md#enum_AudioEffectPitchShift_FFTSize) **FFT_SIZE_256** = `0` + +Use a buffer of 256 samples for the Fast Fourier transform. Lowest latency, but least stable over time. + + + +[FFTSize](class_audioeffectpitchshift.md#enum_AudioEffectPitchShift_FFTSize) **FFT_SIZE_512** = `1` + +Use a buffer of 512 samples for the Fast Fourier transform. Low latency, but less stable over time. + + + +[FFTSize](class_audioeffectpitchshift.md#enum_AudioEffectPitchShift_FFTSize) **FFT_SIZE_1024** = `2` + +Use a buffer of 1024 samples for the Fast Fourier transform. This is a compromise between latency and stability over time. + + + +[FFTSize](class_audioeffectpitchshift.md#enum_AudioEffectPitchShift_FFTSize) **FFT_SIZE_2048** = `3` + +Use a buffer of 2048 samples for the Fast Fourier transform. High latency, but stable over time. + + + +[FFTSize](class_audioeffectpitchshift.md#enum_AudioEffectPitchShift_FFTSize) **FFT_SIZE_4096** = `4` + +Use a buffer of 4096 samples for the Fast Fourier transform. Highest latency, but most stable over time. + + + +[FFTSize](class_audioeffectpitchshift.md#enum_AudioEffectPitchShift_FFTSize) **FFT_SIZE_MAX** = `5` + +Represents the size of the [FFTSize](class_audioeffectpitchshift.md#enum_AudioEffectPitchShift_FFTSize) enum.
+ + + +## Property Descriptions + + + + + +[FFTSize](class_audioeffectpitchshift.md#enum_AudioEffectPitchShift_FFTSize) **fft_size** = `3` [🔗](#class_AudioEffectPitchShift_property_fft_size) + + + +- `void` **set_fft_size**\ (\ value\: [FFTSize](class_audioeffectpitchshift.md#enum_AudioEffectPitchShift_FFTSize)\ ) +- [FFTSize](class_audioeffectpitchshift.md#enum_AudioEffectPitchShift_FFTSize) **get_fft_size**\ (\ ) + +The size of the [Fast Fourier transform](https://en.wikipedia.org/wiki/Fast_Fourier_transform) 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. + +
+ + + + + +[int](class_int.md) **oversampling** = `4` [🔗](#class_AudioEffectPitchShift_property_oversampling) + + + +- `void` **set_oversampling**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_oversampling**\ (\ ) + +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. + +
+ + + + + +[float](class_float.md) **pitch_scale** = `1.0` [🔗](#class_AudioEffectPitchShift_property_pitch_scale) + + + +- `void` **set_pitch_scale**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_pitch_scale**\ (\ ) + +The pitch scale to use. ``1.0`` is the default pitch and plays sounds unaffected. [pitch_scale](class_audioeffectpitchshift.md#class_AudioEffectPitchShift_property_pitch_scale) can range from ``0.0`` (infinitely low pitch, inaudible) to ``16`` (16 times higher than the initial pitch). + diff --git a/docs/Classes/class_audioeffectrecord.md b/docs/Classes/class_audioeffectrecord.md new file mode 100644 index 00000000..04c9f908 --- /dev/null +++ b/docs/Classes/class_audioeffectrecord.md @@ -0,0 +1,127 @@ + + + + + + + + + +# AudioEffectRecord + +**Inherits:** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Audio effect used for recording the sound from an audio bus. + + + +## Description + +Allows the user to record the sound from an audio bus into an [AudioStreamWAV](class_audiostreamwav.md). When used on the "Master" audio bus, this includes all audio output by Redot. + +Unlike [AudioEffectCapture](class_audioeffectcapture.md), 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](class_audiostreammicrophone.md)) to record from a microphone. + +\ **Note:** [ProjectSettings.audio/driver/enable_input](class_projectsettings.md#class_ProjectSettings_property_audio/driver/enable_input) must be ``true`` for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings. + + + +## Tutorials + +- [Recording with microphone](../tutorials/audio/recording_with_microphone.md) + +- [Audio Microphone Record Demo](https://godotengine.org/asset-library/asset/2760) + + + +## Properties + + + + + + + + + + + +
[Format](class_audiostreamwav.md#enum_AudioStreamWAV_Format)[format](#class_AudioEffectRecord_property_format)`1`
+ + + +## Methods + + + + + + + + + + + + + + + + + + +
[AudioStreamWAV](class_audiostreamwav.md)[get_recording](#class_AudioEffectRecord_method_get_recording)\ (\ ) const
[bool](class_bool.md)[is_recording_active](#class_AudioEffectRecord_method_is_recording_active)\ (\ ) const
`void`[set_recording_active](#class_AudioEffectRecord_method_set_recording_active)\ (\ record\: [bool](class_bool.md)\ )
+ +
+ + + +## Property Descriptions + + + + + +[Format](class_audiostreamwav.md#enum_AudioStreamWAV_Format) **format** = `1` [🔗](#class_AudioEffectRecord_property_format) + + + +- `void` **set_format**\ (\ value\: [Format](class_audiostreamwav.md#enum_AudioStreamWAV_Format)\ ) +- [Format](class_audiostreamwav.md#enum_AudioStreamWAV_Format) **get_format**\ (\ ) + +Specifies the format in which the sample will be recorded. + +
+ + + +## Method Descriptions + + + + + +[AudioStreamWAV](class_audiostreamwav.md) **get_recording**\ (\ ) const [🔗](#class_AudioEffectRecord_method_get_recording) + +Returns the recorded sample. + +
+ + + + + +[bool](class_bool.md) **is_recording_active**\ (\ ) const [🔗](#class_AudioEffectRecord_method_is_recording_active) + +Returns whether the recording is active or not. + +
+ + + + + +`void` **set_recording_active**\ (\ record\: [bool](class_bool.md)\ ) [🔗](#class_AudioEffectRecord_method_set_recording_active) + +If ``true``, the sound will be recorded. Note that restarting the recording will remove the previously recorded sample. + diff --git a/docs/Classes/class_audioeffectreverb.md b/docs/Classes/class_audioeffectreverb.md new file mode 100644 index 00000000..0ce81d5a --- /dev/null +++ b/docs/Classes/class_audioeffectreverb.md @@ -0,0 +1,204 @@ + + + + + + + + + +# AudioEffectReverb + +**Inherits:** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Adds a reverberation audio effect to an Audio bus. + + + +## Description + +Simulates the sound of acoustic environments such as rooms, concert halls, caverns, or an open spaces. + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + +- [Third Person Shooter (TPS) Demo](https://godotengine.org/asset-library/asset/2710) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[damping](#class_AudioEffectReverb_property_damping)`0.5`
[float](class_float.md)[dry](#class_AudioEffectReverb_property_dry)`1.0`
[float](class_float.md)[hipass](#class_AudioEffectReverb_property_hipass)`0.0`
[float](class_float.md)[predelay_feedback](#class_AudioEffectReverb_property_predelay_feedback)`0.4`
[float](class_float.md)[predelay_msec](#class_AudioEffectReverb_property_predelay_msec)`150.0`
[float](class_float.md)[room_size](#class_AudioEffectReverb_property_room_size)`0.8`
[float](class_float.md)[spread](#class_AudioEffectReverb_property_spread)`1.0`
[float](class_float.md)[wet](#class_AudioEffectReverb_property_wet)`0.5`
+ +
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **damping** = `0.5` [🔗](#class_AudioEffectReverb_property_damping) + + + +- `void` **set_damping**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_damping**\ (\ ) + +Defines how reflective the imaginary room's walls are. Value can range from 0 to 1. + +
+ + + + + +[float](class_float.md) **dry** = `1.0` [🔗](#class_AudioEffectReverb_property_dry) + + + +- `void` **set_dry**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_dry**\ (\ ) + +Output percent of original sound. At 0, only modified sound is outputted. Value can range from 0 to 1. + +
+ + + + + +[float](class_float.md) **hipass** = `0.0` [🔗](#class_AudioEffectReverb_property_hipass) + + + +- `void` **set_hpf**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_hpf**\ (\ ) + +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. + +
+ + + + + +[float](class_float.md) **predelay_feedback** = `0.4` [🔗](#class_AudioEffectReverb_property_predelay_feedback) + + + +- `void` **set_predelay_feedback**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_predelay_feedback**\ (\ ) + +Output percent of predelay. Value can range from 0 to 1. + +
+ + + + + +[float](class_float.md) **predelay_msec** = `150.0` [🔗](#class_AudioEffectReverb_property_predelay_msec) + + + +- `void` **set_predelay_msec**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_predelay_msec**\ (\ ) + +Time between the original signal and the early reflections of the reverb signal, in milliseconds. + +
+ + + + + +[float](class_float.md) **room_size** = `0.8` [🔗](#class_AudioEffectReverb_property_room_size) + + + +- `void` **set_room_size**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_room_size**\ (\ ) + +Dimensions of simulated room. Bigger means more echoes. Value can range from 0 to 1. + +
+ + + + + +[float](class_float.md) **spread** = `1.0` [🔗](#class_AudioEffectReverb_property_spread) + + + +- `void` **set_spread**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_spread**\ (\ ) + +Widens or narrows the stereo image of the reverb tail. 1 means fully widens. Value can range from 0 to 1. + +
+ + + + + +[float](class_float.md) **wet** = `0.5` [🔗](#class_AudioEffectReverb_property_wet) + + + +- `void` **set_wet**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_wet**\ (\ ) + +Output percent of modified sound. At 0, only original sound is outputted. Value can range from 0 to 1. + diff --git a/docs/Classes/class_audioeffectspectrumanalyzer.md b/docs/Classes/class_audioeffectspectrumanalyzer.md new file mode 100644 index 00000000..71bfe3f7 --- /dev/null +++ b/docs/Classes/class_audioeffectspectrumanalyzer.md @@ -0,0 +1,157 @@ + + + + + + + + + +# AudioEffectSpectrumAnalyzer + +**Inherits:** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Audio effect that can be used for real-time audio visualizations. + + + +## Description + +This audio effect does not affect sound output, but can be used for real-time audio visualizations. + +This resource configures an [AudioEffectSpectrumAnalyzerInstance](class_audioeffectspectrumanalyzerinstance.md), which performs the actual analysis at runtime. An instance can be obtained with [AudioServer.get_bus_effect_instance()](class_audioserver.md#class_AudioServer_method_get_bus_effect_instance). + +See also [AudioStreamGenerator](class_audiostreamgenerator.md) for procedurally generating sounds. + + + +## Tutorials + +- [Audio Spectrum Visualizer Demo](https://godotengine.org/asset-library/asset/2762) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[buffer_length](#class_AudioEffectSpectrumAnalyzer_property_buffer_length)`2.0`
[FFTSize](class_audioeffectspectrumanalyzer.md#enum_AudioEffectSpectrumAnalyzer_FFTSize)[fft_size](#class_AudioEffectSpectrumAnalyzer_property_fft_size)`2`
[float](class_float.md)[tap_back_pos](#class_AudioEffectSpectrumAnalyzer_property_tap_back_pos)`0.01`
+ +
+ + + +## Enumerations + + + + + +enum **FFTSize**: [🔗](#enum_AudioEffectSpectrumAnalyzer_FFTSize) + + + + + +[FFTSize](class_audioeffectspectrumanalyzer.md#enum_AudioEffectSpectrumAnalyzer_FFTSize) **FFT_SIZE_256** = `0` + +Use a buffer of 256 samples for the Fast Fourier transform. Lowest latency, but least stable over time. + + + +[FFTSize](class_audioeffectspectrumanalyzer.md#enum_AudioEffectSpectrumAnalyzer_FFTSize) **FFT_SIZE_512** = `1` + +Use a buffer of 512 samples for the Fast Fourier transform. Low latency, but less stable over time. + + + +[FFTSize](class_audioeffectspectrumanalyzer.md#enum_AudioEffectSpectrumAnalyzer_FFTSize) **FFT_SIZE_1024** = `2` + +Use a buffer of 1024 samples for the Fast Fourier transform. This is a compromise between latency and stability over time. + + + +[FFTSize](class_audioeffectspectrumanalyzer.md#enum_AudioEffectSpectrumAnalyzer_FFTSize) **FFT_SIZE_2048** = `3` + +Use a buffer of 2048 samples for the Fast Fourier transform. High latency, but stable over time. + + + +[FFTSize](class_audioeffectspectrumanalyzer.md#enum_AudioEffectSpectrumAnalyzer_FFTSize) **FFT_SIZE_4096** = `4` + +Use a buffer of 4096 samples for the Fast Fourier transform. Highest latency, but most stable over time. + + + +[FFTSize](class_audioeffectspectrumanalyzer.md#enum_AudioEffectSpectrumAnalyzer_FFTSize) **FFT_SIZE_MAX** = `5` + +Represents the size of the [FFTSize](class_audioeffectspectrumanalyzer.md#enum_AudioEffectSpectrumAnalyzer_FFTSize) enum.
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **buffer_length** = `2.0` [🔗](#class_AudioEffectSpectrumAnalyzer_property_buffer_length) + + + +- `void` **set_buffer_length**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_buffer_length**\ (\ ) + +The length of the buffer to keep (in seconds). Higher values keep data around for longer, but require more memory. + +
+ + + + + +[FFTSize](class_audioeffectspectrumanalyzer.md#enum_AudioEffectSpectrumAnalyzer_FFTSize) **fft_size** = `2` [🔗](#class_AudioEffectSpectrumAnalyzer_property_fft_size) + + + +- `void` **set_fft_size**\ (\ value\: [FFTSize](class_audioeffectspectrumanalyzer.md#enum_AudioEffectSpectrumAnalyzer_FFTSize)\ ) +- [FFTSize](class_audioeffectspectrumanalyzer.md#enum_AudioEffectSpectrumAnalyzer_FFTSize) **get_fft_size**\ (\ ) + +The size of the [Fast Fourier transform](https://en.wikipedia.org/wiki/Fast_Fourier_transform) 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. + +
+ + + + + +[float](class_float.md) **tap_back_pos** = `0.01` [🔗](#class_AudioEffectSpectrumAnalyzer_property_tap_back_pos) + + + +- `void` **set_tap_back_pos**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_tap_back_pos**\ (\ ) + +
+There is currently no description for this property. Please help us by contributing one! + +
+ diff --git a/docs/Classes/class_audioeffectspectrumanalyzerinstance.md b/docs/Classes/class_audioeffectspectrumanalyzerinstance.md new file mode 100644 index 00000000..3b437bee --- /dev/null +++ b/docs/Classes/class_audioeffectspectrumanalyzerinstance.md @@ -0,0 +1,84 @@ + + + + + + + + + +# AudioEffectSpectrumAnalyzerInstance + +**Inherits:** [AudioEffectInstance](class_audioeffectinstance.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Queryable instance of an [AudioEffectSpectrumAnalyzer](class_audioeffectspectrumanalyzer.md). + + + +## Description + +The runtime part of an [AudioEffectSpectrumAnalyzer](class_audioeffectspectrumanalyzer.md), 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 [AudioServer.get_bus_effect_instance()](class_audioserver.md#class_AudioServer_method_get_bus_effect_instance). + + + +## Tutorials + +- [Audio Spectrum Visualizer Demo](https://godotengine.org/asset-library/asset/2762) + + + +## Methods + + + + + + + + + + +
[Vector2](class_vector2.md)[get_magnitude_for_frequency_range](#class_AudioEffectSpectrumAnalyzerInstance_method_get_magnitude_for_frequency_range)\ (\ from_hz\: [float](class_float.md), to_hz\: [float](class_float.md), mode\: [MagnitudeMode](class_audioeffectspectrumanalyzerinstance.md#enum_AudioEffectSpectrumAnalyzerInstance_MagnitudeMode) = 1\ ) const
+ +
+ + + +## Enumerations + + + + + +enum **MagnitudeMode**: [🔗](#enum_AudioEffectSpectrumAnalyzerInstance_MagnitudeMode) + + + + + +[MagnitudeMode](class_audioeffectspectrumanalyzerinstance.md#enum_AudioEffectSpectrumAnalyzerInstance_MagnitudeMode) **MAGNITUDE_AVERAGE** = `0` + +Use the average value across the frequency range as magnitude. + + + +[MagnitudeMode](class_audioeffectspectrumanalyzerinstance.md#enum_AudioEffectSpectrumAnalyzerInstance_MagnitudeMode) **MAGNITUDE_MAX** = `1` + +Use the maximum value of the frequency range as magnitude.
+ + + +## Method Descriptions + + + + + +[Vector2](class_vector2.md) **get_magnitude_for_frequency_range**\ (\ from_hz\: [float](class_float.md), to_hz\: [float](class_float.md), mode\: [MagnitudeMode](class_audioeffectspectrumanalyzerinstance.md#enum_AudioEffectSpectrumAnalyzerInstance_MagnitudeMode) = 1\ ) const [🔗](#class_AudioEffectSpectrumAnalyzerInstance_method_get_magnitude_for_frequency_range) + +Returns the magnitude of the frequencies from `from_hz` to `to_hz` in linear energy as a Vector2. The ``x`` component of the return value represents the left stereo channel, and ``y`` represents the right channel. + +\ `mode` determines how the frequency range will be processed. + diff --git a/docs/Classes/class_audioeffectstereoenhance.md b/docs/Classes/class_audioeffectstereoenhance.md new file mode 100644 index 00000000..f1f1608d --- /dev/null +++ b/docs/Classes/class_audioeffectstereoenhance.md @@ -0,0 +1,102 @@ + + + + + + + + + +# AudioEffectStereoEnhance + +**Inherits:** [AudioEffect](class_audioeffect.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +An audio effect that can be used to adjust the intensity of stereo panning. + + + +## Description + +An audio effect that can be used to adjust the intensity of stereo panning. + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[pan_pullout](#class_AudioEffectStereoEnhance_property_pan_pullout)`1.0`
[float](class_float.md)[surround](#class_AudioEffectStereoEnhance_property_surround)`0.0`
[float](class_float.md)[time_pullout_ms](#class_AudioEffectStereoEnhance_property_time_pullout_ms)`0.0`
+ +
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **pan_pullout** = `1.0` [🔗](#class_AudioEffectStereoEnhance_property_pan_pullout) + + + +- `void` **set_pan_pullout**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_pan_pullout**\ (\ ) + +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. + +
+ + + + + +[float](class_float.md) **surround** = `0.0` [🔗](#class_AudioEffectStereoEnhance_property_surround) + + + +- `void` **set_surround**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_surround**\ (\ ) + +Widens sound stage through phase shifting in conjunction with [time_pullout_ms](class_audioeffectstereoenhance.md#class_AudioEffectStereoEnhance_property_time_pullout_ms). Just pans sound to the left channel if [time_pullout_ms](class_audioeffectstereoenhance.md#class_AudioEffectStereoEnhance_property_time_pullout_ms) is 0. + +
+ + + + + +[float](class_float.md) **time_pullout_ms** = `0.0` [🔗](#class_AudioEffectStereoEnhance_property_time_pullout_ms) + + + +- `void` **set_time_pullout**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_time_pullout**\ (\ ) + +Widens sound stage through phase shifting in conjunction with [surround](class_audioeffectstereoenhance.md#class_AudioEffectStereoEnhance_property_surround). Just delays the right channel if [surround](class_audioeffectstereoenhance.md#class_AudioEffectStereoEnhance_property_surround) is 0. + diff --git a/docs/Classes/class_audiolistener2d.md b/docs/Classes/class_audiolistener2d.md new file mode 100644 index 00000000..2b3b4ce7 --- /dev/null +++ b/docs/Classes/class_audiolistener2d.md @@ -0,0 +1,84 @@ + + + + + + + + + + + +# AudioListener2D + +**Inherits:** [Node2D](class_node2d.md) **<** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +Overrides the location sounds are heard from. + + + +## Description + +Once added to the scene tree and enabled using [make_current()](class_audiolistener2d.md#class_AudioListener2D_method_make_current), this node will override the location sounds are heard from. Only one **AudioListener2D** can be current. Using [make_current()](class_audiolistener2d.md#class_AudioListener2D_method_make_current) will disable the previous **AudioListener2D**. + +If there is no active **AudioListener2D** in the current [Viewport](class_viewport.md), center of the screen will be used as a hearing point for the audio. **AudioListener2D** needs to be inside [SceneTree](class_scenetree.md) to function. + + + +## Methods + + + + + + + + + + + + + + + + + + +
`void`[clear_current](#class_AudioListener2D_method_clear_current)\ (\ )
[bool](class_bool.md)[is_current](#class_AudioListener2D_method_is_current)\ (\ ) const
`void`[make_current](#class_AudioListener2D_method_make_current)\ (\ )
+ +
+ + + +## Method Descriptions + + + + + +`void` **clear_current**\ (\ ) [🔗](#class_AudioListener2D_method_clear_current) + +Disables the **AudioListener2D**. If it's not set as current, this method will have no effect. + +
+ + + + + +[bool](class_bool.md) **is_current**\ (\ ) const [🔗](#class_AudioListener2D_method_is_current) + +Returns ``true`` if this **AudioListener2D** is currently active. + +
+ + + + + +`void` **make_current**\ (\ ) [🔗](#class_AudioListener2D_method_make_current) + +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](class_scenetree.md). + diff --git a/docs/Classes/class_audiolistener3d.md b/docs/Classes/class_audiolistener3d.md new file mode 100644 index 00000000..1b75aa42 --- /dev/null +++ b/docs/Classes/class_audiolistener3d.md @@ -0,0 +1,163 @@ + + + + + + + + + + + +# AudioListener3D + +**Inherits:** [Node3D](class_node3d.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +Overrides the location sounds are heard from. + + + +## Description + +Once added to the scene tree and enabled using [make_current()](class_audiolistener3d.md#class_AudioListener3D_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](class_camera3d.md). + + + +## Properties + + + + + + + + + + + +
[DopplerTracking](class_audiolistener3d.md#enum_AudioListener3D_DopplerTracking)[doppler_tracking](#class_AudioListener3D_property_doppler_tracking)`0`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + +
`void`[clear_current](#class_AudioListener3D_method_clear_current)\ (\ )
[Transform3D](class_transform3d.md)[get_listener_transform](#class_AudioListener3D_method_get_listener_transform)\ (\ ) const
[bool](class_bool.md)[is_current](#class_AudioListener3D_method_is_current)\ (\ ) const
`void`[make_current](#class_AudioListener3D_method_make_current)\ (\ )
+ +
+ + + +## Enumerations + + + + + +enum **DopplerTracking**: [🔗](#enum_AudioListener3D_DopplerTracking) + + + + + +[DopplerTracking](class_audiolistener3d.md#enum_AudioListener3D_DopplerTracking) **DOPPLER_TRACKING_DISABLED** = `0` + +Disables [Doppler effect](https://en.wikipedia.org/wiki/Doppler_effect) simulation (default). + + + +[DopplerTracking](class_audiolistener3d.md#enum_AudioListener3D_DopplerTracking) **DOPPLER_TRACKING_IDLE_STEP** = `1` + +Simulate [Doppler effect](https://en.wikipedia.org/wiki/Doppler_effect) by tracking positions of objects that are changed in ``_process``. Changes in the relative velocity of this listener compared to those objects affect how audio is perceived (changing the audio's [AudioStreamPlayer3D.pitch_scale](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_property_pitch_scale)). + + + +[DopplerTracking](class_audiolistener3d.md#enum_AudioListener3D_DopplerTracking) **DOPPLER_TRACKING_PHYSICS_STEP** = `2` + +Simulate [Doppler effect](https://en.wikipedia.org/wiki/Doppler_effect) by tracking positions of objects that are changed in ``_physics_process``. Changes in the relative velocity of this listener compared to those objects affect how audio is perceived (changing the audio's [AudioStreamPlayer3D.pitch_scale](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_property_pitch_scale)).
+ + + +## Property Descriptions + + + + + +[DopplerTracking](class_audiolistener3d.md#enum_AudioListener3D_DopplerTracking) **doppler_tracking** = `0` [🔗](#class_AudioListener3D_property_doppler_tracking) + + + +- `void` **set_doppler_tracking**\ (\ value\: [DopplerTracking](class_audiolistener3d.md#enum_AudioListener3D_DopplerTracking)\ ) +- [DopplerTracking](class_audiolistener3d.md#enum_AudioListener3D_DopplerTracking) **get_doppler_tracking**\ (\ ) + +If not [DOPPLER_TRACKING_DISABLED](class_audiolistener3d.md#class_AudioListener3D_constant_DOPPLER_TRACKING_DISABLED), this listener will simulate the [Doppler effect](https://en.wikipedia.org/wiki/Doppler_effect) for objects changed in particular ``_process`` methods. + +\ **Note:** The Doppler effect will only be heard on [AudioStreamPlayer3D](class_audiostreamplayer3d.md)\ s if [AudioStreamPlayer3D.doppler_tracking](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_property_doppler_tracking) is not set to [AudioStreamPlayer3D.DOPPLER_TRACKING_DISABLED](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_constant_DOPPLER_TRACKING_DISABLED). + +
+ + + +## Method Descriptions + + + + + +`void` **clear_current**\ (\ ) [🔗](#class_AudioListener3D_method_clear_current) + +Disables the listener to use the current camera's listener instead. + +
+ + + + + +[Transform3D](class_transform3d.md) **get_listener_transform**\ (\ ) const [🔗](#class_AudioListener3D_method_get_listener_transform) + +Returns the listener's global orthonormalized [Transform3D](class_transform3d.md). + +
+ + + + + +[bool](class_bool.md) **is_current**\ (\ ) const [🔗](#class_AudioListener3D_method_is_current) + +Returns ``true`` if the listener was made current using [make_current()](class_audiolistener3d.md#class_AudioListener3D_method_make_current), ``false`` otherwise. + +\ **Note:** 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. + +
+ + + + + +`void` **make_current**\ (\ ) [🔗](#class_AudioListener3D_method_make_current) + +Enables the listener. This will override the current camera's listener. + diff --git a/docs/Classes/class_audiosample.md b/docs/Classes/class_audiosample.md new file mode 100644 index 00000000..6a581d01 --- /dev/null +++ b/docs/Classes/class_audiosample.md @@ -0,0 +1,23 @@ + + + + + + + + + +# AudioSample + +**Experimental:** This class may be changed or removed in future versions. + +**Inherits:** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Base class for audio samples. + + + +## Description + +Base class for audio samples. + diff --git a/docs/Classes/class_audiosampleplayback.md b/docs/Classes/class_audiosampleplayback.md new file mode 100644 index 00000000..f8b7b900 --- /dev/null +++ b/docs/Classes/class_audiosampleplayback.md @@ -0,0 +1,23 @@ + + + + + + + + + +# AudioSamplePlayback + +**Experimental:** This class may be changed or removed in future versions. + +**Inherits:** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Meta class for playing back audio samples. + + + +## Description + +Meta class for playing back audio samples. + diff --git a/docs/Classes/class_audioserver.md b/docs/Classes/class_audioserver.md new file mode 100644 index 00000000..948f8435 --- /dev/null +++ b/docs/Classes/class_audioserver.md @@ -0,0 +1,899 @@ + + + + + + + + + +# AudioServer + +**Inherits:** [Object](class_object.md) + +Server interface for low-level audio access. + + + +## 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. + + + +## Tutorials + +- [Audio buses](../tutorials/audio/audio_buses.md) + +- [Audio Device Changer Demo](https://godotengine.org/asset-library/asset/2758) + +- [Audio Microphone Record Demo](https://godotengine.org/asset-library/asset/2760) + +- [Audio Spectrum Visualizer Demo](https://godotengine.org/asset-library/asset/2762) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + +
[int](class_int.md)[bus_count](#class_AudioServer_property_bus_count)`1`
[String](class_string.md)[input_device](#class_AudioServer_property_input_device)`"Default"`
[String](class_string.md)[output_device](#class_AudioServer_property_output_device)`"Default"`
[float](class_float.md)[playback_speed_scale](#class_AudioServer_property_playback_speed_scale)`1.0`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
`void`[add_bus](#class_AudioServer_method_add_bus)\ (\ at_position\: [int](class_int.md) = -1\ )
`void`[add_bus_effect](#class_AudioServer_method_add_bus_effect)\ (\ bus_idx\: [int](class_int.md), effect\: [AudioEffect](class_audioeffect.md), at_position\: [int](class_int.md) = -1\ )
[AudioBusLayout](class_audiobuslayout.md)[generate_bus_layout](#class_AudioServer_method_generate_bus_layout)\ (\ ) const
[int](class_int.md)[get_bus_channels](#class_AudioServer_method_get_bus_channels)\ (\ bus_idx\: [int](class_int.md)\ ) const
[AudioEffect](class_audioeffect.md)[get_bus_effect](#class_AudioServer_method_get_bus_effect)\ (\ bus_idx\: [int](class_int.md), effect_idx\: [int](class_int.md)\ )
[int](class_int.md)[get_bus_effect_count](#class_AudioServer_method_get_bus_effect_count)\ (\ bus_idx\: [int](class_int.md)\ )
[AudioEffectInstance](class_audioeffectinstance.md)[get_bus_effect_instance](#class_AudioServer_method_get_bus_effect_instance)\ (\ bus_idx\: [int](class_int.md), effect_idx\: [int](class_int.md), channel\: [int](class_int.md) = 0\ )
[int](class_int.md)[get_bus_index](#class_AudioServer_method_get_bus_index)\ (\ bus_name\: [StringName](class_stringname.md)\ ) const
[String](class_string.md)[get_bus_name](#class_AudioServer_method_get_bus_name)\ (\ bus_idx\: [int](class_int.md)\ ) const
[float](class_float.md)[get_bus_peak_volume_left_db](#class_AudioServer_method_get_bus_peak_volume_left_db)\ (\ bus_idx\: [int](class_int.md), channel\: [int](class_int.md)\ ) const
[float](class_float.md)[get_bus_peak_volume_right_db](#class_AudioServer_method_get_bus_peak_volume_right_db)\ (\ bus_idx\: [int](class_int.md), channel\: [int](class_int.md)\ ) const
[StringName](class_stringname.md)[get_bus_send](#class_AudioServer_method_get_bus_send)\ (\ bus_idx\: [int](class_int.md)\ ) const
[float](class_float.md)[get_bus_volume_db](#class_AudioServer_method_get_bus_volume_db)\ (\ bus_idx\: [int](class_int.md)\ ) const
[float](class_float.md)[get_bus_volume_linear](#class_AudioServer_method_get_bus_volume_linear)\ (\ bus_idx\: [int](class_int.md)\ ) const
[String](class_string.md)[get_driver_name](#class_AudioServer_method_get_driver_name)\ (\ ) const
[PackedStringArray](class_packedstringarray.md)[get_input_device_list](#class_AudioServer_method_get_input_device_list)\ (\ )
[float](class_float.md)[get_input_mix_rate](#class_AudioServer_method_get_input_mix_rate)\ (\ ) const
[float](class_float.md)[get_mix_rate](#class_AudioServer_method_get_mix_rate)\ (\ ) const
[PackedStringArray](class_packedstringarray.md)[get_output_device_list](#class_AudioServer_method_get_output_device_list)\ (\ )
[float](class_float.md)[get_output_latency](#class_AudioServer_method_get_output_latency)\ (\ ) const
[SpeakerMode](class_audioserver.md#enum_AudioServer_SpeakerMode)[get_speaker_mode](#class_AudioServer_method_get_speaker_mode)\ (\ ) const
[float](class_float.md)[get_time_since_last_mix](#class_AudioServer_method_get_time_since_last_mix)\ (\ ) const
[float](class_float.md)[get_time_to_next_mix](#class_AudioServer_method_get_time_to_next_mix)\ (\ ) const
[bool](class_bool.md)[is_bus_bypassing_effects](#class_AudioServer_method_is_bus_bypassing_effects)\ (\ bus_idx\: [int](class_int.md)\ ) const
[bool](class_bool.md)[is_bus_effect_enabled](#class_AudioServer_method_is_bus_effect_enabled)\ (\ bus_idx\: [int](class_int.md), effect_idx\: [int](class_int.md)\ ) const
[bool](class_bool.md)[is_bus_mute](#class_AudioServer_method_is_bus_mute)\ (\ bus_idx\: [int](class_int.md)\ ) const
[bool](class_bool.md)[is_bus_solo](#class_AudioServer_method_is_bus_solo)\ (\ bus_idx\: [int](class_int.md)\ ) const
[bool](class_bool.md)[is_stream_registered_as_sample](#class_AudioServer_method_is_stream_registered_as_sample)\ (\ stream\: [AudioStream](class_audiostream.md)\ )
`void`[lock](#class_AudioServer_method_lock)\ (\ )
`void`[move_bus](#class_AudioServer_method_move_bus)\ (\ index\: [int](class_int.md), to_index\: [int](class_int.md)\ )
`void`[register_stream_as_sample](#class_AudioServer_method_register_stream_as_sample)\ (\ stream\: [AudioStream](class_audiostream.md)\ )
`void`[remove_bus](#class_AudioServer_method_remove_bus)\ (\ index\: [int](class_int.md)\ )
`void`[remove_bus_effect](#class_AudioServer_method_remove_bus_effect)\ (\ bus_idx\: [int](class_int.md), effect_idx\: [int](class_int.md)\ )
`void`[set_bus_bypass_effects](#class_AudioServer_method_set_bus_bypass_effects)\ (\ bus_idx\: [int](class_int.md), enable\: [bool](class_bool.md)\ )
`void`[set_bus_effect_enabled](#class_AudioServer_method_set_bus_effect_enabled)\ (\ bus_idx\: [int](class_int.md), effect_idx\: [int](class_int.md), enabled\: [bool](class_bool.md)\ )
`void`[set_bus_layout](#class_AudioServer_method_set_bus_layout)\ (\ bus_layout\: [AudioBusLayout](class_audiobuslayout.md)\ )
`void`[set_bus_mute](#class_AudioServer_method_set_bus_mute)\ (\ bus_idx\: [int](class_int.md), enable\: [bool](class_bool.md)\ )
`void`[set_bus_name](#class_AudioServer_method_set_bus_name)\ (\ bus_idx\: [int](class_int.md), name\: [String](class_string.md)\ )
`void`[set_bus_send](#class_AudioServer_method_set_bus_send)\ (\ bus_idx\: [int](class_int.md), send\: [StringName](class_stringname.md)\ )
`void`[set_bus_solo](#class_AudioServer_method_set_bus_solo)\ (\ bus_idx\: [int](class_int.md), enable\: [bool](class_bool.md)\ )
`void`[set_bus_volume_db](#class_AudioServer_method_set_bus_volume_db)\ (\ bus_idx\: [int](class_int.md), volume_db\: [float](class_float.md)\ )
`void`[set_bus_volume_linear](#class_AudioServer_method_set_bus_volume_linear)\ (\ bus_idx\: [int](class_int.md), volume_linear\: [float](class_float.md)\ )
`void`[set_enable_tagging_used_audio_streams](#class_AudioServer_method_set_enable_tagging_used_audio_streams)\ (\ enable\: [bool](class_bool.md)\ )
`void`[swap_bus_effects](#class_AudioServer_method_swap_bus_effects)\ (\ bus_idx\: [int](class_int.md), effect_idx\: [int](class_int.md), by_effect_idx\: [int](class_int.md)\ )
`void`[unlock](#class_AudioServer_method_unlock)\ (\ )
+ +
+ + + +## Signals + + + + + +**bus_layout_changed**\ (\ ) [🔗](#class_AudioServer_signal_bus_layout_changed) + +Emitted when an audio bus is added, deleted, or moved. + +
+ + + + + +**bus_renamed**\ (\ bus_index\: [int](class_int.md), old_name\: [StringName](class_stringname.md), new_name\: [StringName](class_stringname.md)\ ) [🔗](#class_AudioServer_signal_bus_renamed) + +Emitted when the audio bus at `bus_index` is renamed from `old_name` to `new_name`. + +
+ + + +## Enumerations + + + + + +enum **SpeakerMode**: [🔗](#enum_AudioServer_SpeakerMode) + + + + + +[SpeakerMode](class_audioserver.md#enum_AudioServer_SpeakerMode) **SPEAKER_MODE_STEREO** = `0` + +Two or fewer speakers were detected. + + + +[SpeakerMode](class_audioserver.md#enum_AudioServer_SpeakerMode) **SPEAKER_SURROUND_31** = `1` + +A 3.1 channel surround setup was detected. + + + +[SpeakerMode](class_audioserver.md#enum_AudioServer_SpeakerMode) **SPEAKER_SURROUND_51** = `2` + +A 5.1 channel surround setup was detected. + + + +[SpeakerMode](class_audioserver.md#enum_AudioServer_SpeakerMode) **SPEAKER_SURROUND_71** = `3` + +A 7.1 channel surround setup was detected.
+ + + + + +enum **PlaybackType**: [🔗](#enum_AudioServer_PlaybackType) + + + + + +[PlaybackType](class_audioserver.md#enum_AudioServer_PlaybackType) **PLAYBACK_TYPE_DEFAULT** = `0` + +**Experimental:** This constant may be changed or removed in future versions. + +The playback will be considered of the type declared at [ProjectSettings.audio/general/default_playback_type](class_projectsettings.md#class_ProjectSettings_property_audio/general/default_playback_type). + + + +[PlaybackType](class_audioserver.md#enum_AudioServer_PlaybackType) **PLAYBACK_TYPE_STREAM** = `1` + +**Experimental:** This constant may be changed or removed in future versions. + +Force the playback to be considered as a stream. + + + +[PlaybackType](class_audioserver.md#enum_AudioServer_PlaybackType) **PLAYBACK_TYPE_SAMPLE** = `2` + +**Experimental:** This constant may be changed or removed in future versions. + +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. + +\ **Note:** Only currently supported on the web platform. + +\ **Note:** [AudioEffect](class_audioeffect.md)\ s are not supported when playback is considered as a sample. + + + +[PlaybackType](class_audioserver.md#enum_AudioServer_PlaybackType) **PLAYBACK_TYPE_MAX** = `3` + +**Experimental:** This constant may be changed or removed in future versions. + +Represents the size of the [PlaybackType](class_audioserver.md#enum_AudioServer_PlaybackType) enum.
+ + + +## Property Descriptions + + + + + +[int](class_int.md) **bus_count** = `1` [🔗](#class_AudioServer_property_bus_count) + + + +- `void` **set_bus_count**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_bus_count**\ (\ ) + +Number of available audio buses. + +
+ + + + + +[String](class_string.md) **input_device** = `"Default"` [🔗](#class_AudioServer_property_input_device) + + + +- `void` **set_input_device**\ (\ value\: [String](class_string.md)\ ) +- [String](class_string.md) **get_input_device**\ (\ ) + +Name of the current device for audio input (see [get_input_device_list()](class_audioserver.md#class_AudioServer_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 ``"Default"`` will record audio on the system-wide default audio input. If an invalid device name is set, the value will be reverted back to ``"Default"``. + +\ **Note:** [ProjectSettings.audio/driver/enable_input](class_projectsettings.md#class_ProjectSettings_property_audio/driver/enable_input) must be ``true`` for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings. + +
+ + + + + +[String](class_string.md) **output_device** = `"Default"` [🔗](#class_AudioServer_property_output_device) + + + +- `void` **set_output_device**\ (\ value\: [String](class_string.md)\ ) +- [String](class_string.md) **get_output_device**\ (\ ) + +Name of the current device for audio output (see [get_output_device_list()](class_audioserver.md#class_AudioServer_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 ``"Default"`` will play audio on the system-wide default audio output. If an invalid device name is set, the value will be reverted back to ``"Default"``. + +
+ + + + + +[float](class_float.md) **playback_speed_scale** = `1.0` [🔗](#class_AudioServer_property_playback_speed_scale) + + + +- `void` **set_playback_speed_scale**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_playback_speed_scale**\ (\ ) + +Scales the rate at which audio is played (i.e. setting it to ``0.5`` will make the audio be played at half its speed). See also [Engine.time_scale](class_engine.md#class_Engine_property_time_scale) to affect the general simulation speed, which is independent from [playback_speed_scale](class_audioserver.md#class_AudioServer_property_playback_speed_scale). + +
+ + + +## Method Descriptions + + + + + +`void` **add_bus**\ (\ at_position\: [int](class_int.md) = -1\ ) [🔗](#class_AudioServer_method_add_bus) + +Adds a bus at `at_position`. + +
+ + + + + +`void` **add_bus_effect**\ (\ bus_idx\: [int](class_int.md), effect\: [AudioEffect](class_audioeffect.md), at_position\: [int](class_int.md) = -1\ ) [🔗](#class_AudioServer_method_add_bus_effect) + +Adds an [AudioEffect](class_audioeffect.md) effect to the bus `bus_idx` at `at_position`. + +
+ + + + + +[AudioBusLayout](class_audiobuslayout.md) **generate_bus_layout**\ (\ ) const [🔗](#class_AudioServer_method_generate_bus_layout) + +Generates an [AudioBusLayout](class_audiobuslayout.md) using the available buses and effects. + +
+ + + + + +[int](class_int.md) **get_bus_channels**\ (\ bus_idx\: [int](class_int.md)\ ) const [🔗](#class_AudioServer_method_get_bus_channels) + +Returns the number of channels of the bus at index `bus_idx`. + +
+ + + + + +[AudioEffect](class_audioeffect.md) **get_bus_effect**\ (\ bus_idx\: [int](class_int.md), effect_idx\: [int](class_int.md)\ ) [🔗](#class_AudioServer_method_get_bus_effect) + +Returns the [AudioEffect](class_audioeffect.md) at position `effect_idx` in bus `bus_idx`. + +
+ + + + + +[int](class_int.md) **get_bus_effect_count**\ (\ bus_idx\: [int](class_int.md)\ ) [🔗](#class_AudioServer_method_get_bus_effect_count) + +Returns the number of effects on the bus at `bus_idx`. + +
+ + + + + +[AudioEffectInstance](class_audioeffectinstance.md) **get_bus_effect_instance**\ (\ bus_idx\: [int](class_int.md), effect_idx\: [int](class_int.md), channel\: [int](class_int.md) = 0\ ) [🔗](#class_AudioServer_method_get_bus_effect_instance) + +Returns the [AudioEffectInstance](class_audioeffectinstance.md) assigned to the given bus and effect indices (and optionally channel). + +
+ + + + + +[int](class_int.md) **get_bus_index**\ (\ bus_name\: [StringName](class_stringname.md)\ ) const [🔗](#class_AudioServer_method_get_bus_index) + +Returns the index of the bus with the name `bus_name`. Returns ``-1`` if no bus with the specified name exist. + +
+ + + + + +[String](class_string.md) **get_bus_name**\ (\ bus_idx\: [int](class_int.md)\ ) const [🔗](#class_AudioServer_method_get_bus_name) + +Returns the name of the bus with the index `bus_idx`. + +
+ + + + + +[float](class_float.md) **get_bus_peak_volume_left_db**\ (\ bus_idx\: [int](class_int.md), channel\: [int](class_int.md)\ ) const [🔗](#class_AudioServer_method_get_bus_peak_volume_left_db) + +Returns the peak volume of the left speaker at bus index `bus_idx` and channel index `channel`. + +
+ + + + + +[float](class_float.md) **get_bus_peak_volume_right_db**\ (\ bus_idx\: [int](class_int.md), channel\: [int](class_int.md)\ ) const [🔗](#class_AudioServer_method_get_bus_peak_volume_right_db) + +Returns the peak volume of the right speaker at bus index `bus_idx` and channel index `channel`. + +
+ + + + + +[StringName](class_stringname.md) **get_bus_send**\ (\ bus_idx\: [int](class_int.md)\ ) const [🔗](#class_AudioServer_method_get_bus_send) + +Returns the name of the bus that the bus at index `bus_idx` sends to. + +
+ + + + + +[float](class_float.md) **get_bus_volume_db**\ (\ bus_idx\: [int](class_int.md)\ ) const [🔗](#class_AudioServer_method_get_bus_volume_db) + +Returns the volume of the bus at index `bus_idx` in dB. + +
+ + + + + +[float](class_float.md) **get_bus_volume_linear**\ (\ bus_idx\: [int](class_int.md)\ ) const [🔗](#class_AudioServer_method_get_bus_volume_linear) + +Returns the volume of the bus at index `bus_idx` as a linear value. + +\ **Note:** The returned value is equivalent to the result of [@GlobalScope.db_to_linear()](class_@globalscope.md#class_@GlobalScope_method_db_to_linear) on the result of [get_bus_volume_db()](class_audioserver.md#class_AudioServer_method_get_bus_volume_db). + +
+ + + + + +[String](class_string.md) **get_driver_name**\ (\ ) const [🔗](#class_AudioServer_method_get_driver_name) + +Returns the name of the current audio driver. The default usually depends on the operating system, but may be overridden via the ``--audio-driver`` [command line argument](../tutorials/editor/command_line_tutorial.md). ``--headless`` also automatically sets the audio driver to ``Dummy``. See also [ProjectSettings.audio/driver/driver](class_projectsettings.md#class_ProjectSettings_property_audio/driver/driver). + +
+ + + + + +[PackedStringArray](class_packedstringarray.md) **get_input_device_list**\ (\ ) [🔗](#class_AudioServer_method_get_input_device_list) + +Returns the names of all audio input devices detected on the system. + +\ **Note:** [ProjectSettings.audio/driver/enable_input](class_projectsettings.md#class_ProjectSettings_property_audio/driver/enable_input) must be ``true`` for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings. + +
+ + + + + +[float](class_float.md) **get_input_mix_rate**\ (\ ) const [🔗](#class_AudioServer_method_get_input_mix_rate) + +Returns the sample rate at the input of the **AudioServer**. + +
+ + + + + +[float](class_float.md) **get_mix_rate**\ (\ ) const [🔗](#class_AudioServer_method_get_mix_rate) + +Returns the sample rate at the output of the **AudioServer**. + +
+ + + + + +[PackedStringArray](class_packedstringarray.md) **get_output_device_list**\ (\ ) [🔗](#class_AudioServer_method_get_output_device_list) + +Returns the names of all audio output devices detected on the system. + +
+ + + + + +[float](class_float.md) **get_output_latency**\ (\ ) const [🔗](#class_AudioServer_method_get_output_latency) + +Returns the audio driver's effective output latency. This is based on [ProjectSettings.audio/driver/output_latency](class_projectsettings.md#class_ProjectSettings_property_audio/driver/output_latency), but the exact returned value will differ depending on the operating system and audio driver. + +\ **Note:** This can be expensive; it is not recommended to call [get_output_latency()](class_audioserver.md#class_AudioServer_method_get_output_latency) every frame. + +
+ + + + + +[SpeakerMode](class_audioserver.md#enum_AudioServer_SpeakerMode) **get_speaker_mode**\ (\ ) const [🔗](#class_AudioServer_method_get_speaker_mode) + +Returns the speaker configuration. + +
+ + + + + +[float](class_float.md) **get_time_since_last_mix**\ (\ ) const [🔗](#class_AudioServer_method_get_time_since_last_mix) + +Returns the relative time since the last mix occurred. + +
+ + + + + +[float](class_float.md) **get_time_to_next_mix**\ (\ ) const [🔗](#class_AudioServer_method_get_time_to_next_mix) + +Returns the relative time until the next mix occurs. + +
+ + + + + +[bool](class_bool.md) **is_bus_bypassing_effects**\ (\ bus_idx\: [int](class_int.md)\ ) const [🔗](#class_AudioServer_method_is_bus_bypassing_effects) + +If ``true``, the bus at index `bus_idx` is bypassing effects. + +
+ + + + + +[bool](class_bool.md) **is_bus_effect_enabled**\ (\ bus_idx\: [int](class_int.md), effect_idx\: [int](class_int.md)\ ) const [🔗](#class_AudioServer_method_is_bus_effect_enabled) + +If ``true``, the effect at index `effect_idx` on the bus at index `bus_idx` is enabled. + +
+ + + + + +[bool](class_bool.md) **is_bus_mute**\ (\ bus_idx\: [int](class_int.md)\ ) const [🔗](#class_AudioServer_method_is_bus_mute) + +If ``true``, the bus at index `bus_idx` is muted. + +
+ + + + + +[bool](class_bool.md) **is_bus_solo**\ (\ bus_idx\: [int](class_int.md)\ ) const [🔗](#class_AudioServer_method_is_bus_solo) + +If ``true``, the bus at index `bus_idx` is in solo mode. + +
+ + + + + +[bool](class_bool.md) **is_stream_registered_as_sample**\ (\ stream\: [AudioStream](class_audiostream.md)\ ) [🔗](#class_AudioServer_method_is_stream_registered_as_sample) + +**Experimental:** This method may be changed or removed in future versions. + +If ``true``, the stream is registered as a sample. The engine will not have to register it before playing the sample. + +If ``false``, the stream will have to be registered before playing it. To prevent lag spikes, register the stream as sample with [register_stream_as_sample()](class_audioserver.md#class_AudioServer_method_register_stream_as_sample). + +
+ + + + + +`void` **lock**\ (\ ) [🔗](#class_AudioServer_method_lock) + +Locks the audio driver's main loop. + +\ **Note:** Remember to unlock it afterwards. + +
+ + + + + +`void` **move_bus**\ (\ index\: [int](class_int.md), to_index\: [int](class_int.md)\ ) [🔗](#class_AudioServer_method_move_bus) + +Moves the bus from index `index` to index `to_index`. + +
+ + + + + +`void` **register_stream_as_sample**\ (\ stream\: [AudioStream](class_audiostream.md)\ ) [🔗](#class_AudioServer_method_register_stream_as_sample) + +**Experimental:** This method may be changed or removed in future versions. + +Forces the registration of a stream as a sample. + +\ **Note:** 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. + +
+ + + + + +`void` **remove_bus**\ (\ index\: [int](class_int.md)\ ) [🔗](#class_AudioServer_method_remove_bus) + +Removes the bus at index `index`. + +
+ + + + + +`void` **remove_bus_effect**\ (\ bus_idx\: [int](class_int.md), effect_idx\: [int](class_int.md)\ ) [🔗](#class_AudioServer_method_remove_bus_effect) + +Removes the effect at index `effect_idx` from the bus at index `bus_idx`. + +
+ + + + + +`void` **set_bus_bypass_effects**\ (\ bus_idx\: [int](class_int.md), enable\: [bool](class_bool.md)\ ) [🔗](#class_AudioServer_method_set_bus_bypass_effects) + +If ``true``, the bus at index `bus_idx` is bypassing effects. + +
+ + + + + +`void` **set_bus_effect_enabled**\ (\ bus_idx\: [int](class_int.md), effect_idx\: [int](class_int.md), enabled\: [bool](class_bool.md)\ ) [🔗](#class_AudioServer_method_set_bus_effect_enabled) + +If ``true``, the effect at index `effect_idx` on the bus at index `bus_idx` is enabled. + +
+ + + + + +`void` **set_bus_layout**\ (\ bus_layout\: [AudioBusLayout](class_audiobuslayout.md)\ ) [🔗](#class_AudioServer_method_set_bus_layout) + +Overwrites the currently used [AudioBusLayout](class_audiobuslayout.md). + +
+ + + + + +`void` **set_bus_mute**\ (\ bus_idx\: [int](class_int.md), enable\: [bool](class_bool.md)\ ) [🔗](#class_AudioServer_method_set_bus_mute) + +If ``true``, the bus at index `bus_idx` is muted. + +
+ + + + + +`void` **set_bus_name**\ (\ bus_idx\: [int](class_int.md), name\: [String](class_string.md)\ ) [🔗](#class_AudioServer_method_set_bus_name) + +Sets the name of the bus at index `bus_idx` to `name`. + +
+ + + + + +`void` **set_bus_send**\ (\ bus_idx\: [int](class_int.md), send\: [StringName](class_stringname.md)\ ) [🔗](#class_AudioServer_method_set_bus_send) + +Connects the output of the bus at `bus_idx` to the bus named `send`. + +
+ + + + + +`void` **set_bus_solo**\ (\ bus_idx\: [int](class_int.md), enable\: [bool](class_bool.md)\ ) [🔗](#class_AudioServer_method_set_bus_solo) + +If ``true``, the bus at index `bus_idx` is in solo mode. + +
+ + + + + +`void` **set_bus_volume_db**\ (\ bus_idx\: [int](class_int.md), volume_db\: [float](class_float.md)\ ) [🔗](#class_AudioServer_method_set_bus_volume_db) + +Sets the volume in decibels of the bus at index `bus_idx` to `volume_db`. + +
+ + + + + +`void` **set_bus_volume_linear**\ (\ bus_idx\: [int](class_int.md), volume_linear\: [float](class_float.md)\ ) [🔗](#class_AudioServer_method_set_bus_volume_linear) + +Sets the volume as a linear value of the bus at index `bus_idx` to `volume_linear`. + +\ **Note:** Using this method is equivalent to calling [set_bus_volume_db()](class_audioserver.md#class_AudioServer_method_set_bus_volume_db) with the result of [@GlobalScope.linear_to_db()](class_@globalscope.md#class_@GlobalScope_method_linear_to_db) on a value. + +
+ + + + + +`void` **set_enable_tagging_used_audio_streams**\ (\ enable\: [bool](class_bool.md)\ ) [🔗](#class_AudioServer_method_set_enable_tagging_used_audio_streams) + +If set to ``true``, all instances of [AudioStreamPlayback](class_audiostreamplayback.md) will call [AudioStreamPlayback._tag_used_streams()](class_audiostreamplayback.md#class_AudioStreamPlayback_private_method__tag_used_streams) every mix step. + +\ **Note:** This is enabled by default in the editor, as it is used by editor plugins for the audio stream previews. + +
+ + + + + +`void` **swap_bus_effects**\ (\ bus_idx\: [int](class_int.md), effect_idx\: [int](class_int.md), by_effect_idx\: [int](class_int.md)\ ) [🔗](#class_AudioServer_method_swap_bus_effects) + +Swaps the position of two effects in bus `bus_idx`. + +
+ + + + + +`void` **unlock**\ (\ ) [🔗](#class_AudioServer_method_unlock) + +Unlocks the audio driver's main loop. (After locking it, you should always unlock it.) + diff --git a/docs/Classes/class_audiostream.md b/docs/Classes/class_audiostream.md new file mode 100644 index 00000000..29d1b5c6 --- /dev/null +++ b/docs/Classes/class_audiostream.md @@ -0,0 +1,298 @@ + + + + + + + + + +# AudioStream + +**Inherits:** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +**Inherited By:** [AudioStreamGenerator](class_audiostreamgenerator.md), [AudioStreamInteractive](class_audiostreaminteractive.md), [AudioStreamMicrophone](class_audiostreammicrophone.md), [AudioStreamMP3](class_audiostreammp3.md), [AudioStreamOggVorbis](class_audiostreamoggvorbis.md), [AudioStreamPlaylist](class_audiostreamplaylist.md), [AudioStreamPolyphonic](class_audiostreampolyphonic.md), [AudioStreamRandomizer](class_audiostreamrandomizer.md), [AudioStreamSynchronized](class_audiostreamsynchronized.md), [AudioStreamWAV](class_audiostreamwav.md) + +Base class for audio streams. + + + +## Description + +Base class for audio streams. Audio streams are used for sound effects and music playback, and support WAV (via [AudioStreamWAV](class_audiostreamwav.md)) and Ogg (via [AudioStreamOggVorbis](class_audiostreamoggvorbis.md)) file formats. + + + +## Tutorials + +- [Audio streams](../tutorials/audio/audio_streams.md) + +- [Audio Generator Demo](https://godotengine.org/asset-library/asset/2759) + +- [Audio Microphone Record Demo](https://godotengine.org/asset-library/asset/2760) + +- [Audio Spectrum Visualizer Demo](https://godotengine.org/asset-library/asset/2762) + + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[int](class_int.md)[_get_bar_beats](#class_AudioStream_private_method__get_bar_beats)\ (\ ) virtual const
[int](class_int.md)[_get_beat_count](#class_AudioStream_private_method__get_beat_count)\ (\ ) virtual const
[float](class_float.md)[_get_bpm](#class_AudioStream_private_method__get_bpm)\ (\ ) virtual const
[float](class_float.md)[_get_length](#class_AudioStream_private_method__get_length)\ (\ ) virtual const
[Array](class_array.md)\[[Dictionary](class_dictionary.md)\][_get_parameter_list](#class_AudioStream_private_method__get_parameter_list)\ (\ ) virtual const
[String](class_string.md)[_get_stream_name](#class_AudioStream_private_method__get_stream_name)\ (\ ) virtual const
[Dictionary](class_dictionary.md)[_get_tags](#class_AudioStream_private_method__get_tags)\ (\ ) virtual const
[bool](class_bool.md)[_has_loop](#class_AudioStream_private_method__has_loop)\ (\ ) virtual const
[AudioStreamPlayback](class_audiostreamplayback.md)[_instantiate_playback](#class_AudioStream_private_method__instantiate_playback)\ (\ ) virtual const
[bool](class_bool.md)[_is_monophonic](#class_AudioStream_private_method__is_monophonic)\ (\ ) virtual const
[bool](class_bool.md)[can_be_sampled](#class_AudioStream_method_can_be_sampled)\ (\ ) const
[AudioSample](class_audiosample.md)[generate_sample](#class_AudioStream_method_generate_sample)\ (\ ) const
[float](class_float.md)[get_length](#class_AudioStream_method_get_length)\ (\ ) const
[AudioStreamPlayback](class_audiostreamplayback.md)[instantiate_playback](#class_AudioStream_method_instantiate_playback)\ (\ )
[bool](class_bool.md)[is_meta_stream](#class_AudioStream_method_is_meta_stream)\ (\ ) const
[bool](class_bool.md)[is_monophonic](#class_AudioStream_method_is_monophonic)\ (\ ) const
+ +
+ + + +## Signals + + + + + +**parameter_list_changed**\ (\ ) [🔗](#class_AudioStream_signal_parameter_list_changed) + +Signal to be emitted to notify when the parameter list changed. + +
+ + + +## Method Descriptions + + + + + +[int](class_int.md) **_get_bar_beats**\ (\ ) virtual const [🔗](#class_AudioStream_private_method__get_bar_beats) + +Override this method to return the bar beats of this stream. + +
+ + + + + +[int](class_int.md) **_get_beat_count**\ (\ ) virtual const [🔗](#class_AudioStream_private_method__get_beat_count) + +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 ([AudioStreamWAV.mix_rate](class_audiostreamwav.md#class_AudioStreamWAV_property_mix_rate), for example). + +
+ + + + + +[float](class_float.md) **_get_bpm**\ (\ ) virtual const [🔗](#class_AudioStream_private_method__get_bpm) + +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 ([AudioStreamWAV.mix_rate](class_audiostreamwav.md#class_AudioStreamWAV_property_mix_rate), for example). + +
+ + + + + +[float](class_float.md) **_get_length**\ (\ ) virtual const [🔗](#class_AudioStream_private_method__get_length) + +Override this method to customize the returned value of [get_length()](class_audiostream.md#class_AudioStream_method_get_length). Should return the length of this audio stream, in seconds. + +
+ + + + + +[Array](class_array.md)\[[Dictionary](class_dictionary.md)\] **_get_parameter_list**\ (\ ) virtual const [🔗](#class_AudioStream_private_method__get_parameter_list) + +Return the controllable parameters of this stream. This array contains dictionaries with a property info description format (see [Object.get_property_list()](class_object.md#class_Object_method_get_property_list)). Additionally, the default value for this parameter must be added tho each dictionary in "default_value" field. + +
+ + + + + +[String](class_string.md) **_get_stream_name**\ (\ ) virtual const [🔗](#class_AudioStream_private_method__get_stream_name) + +Override this method to customize the name assigned to this audio stream. Unused by the engine. + +
+ + + + + +[Dictionary](class_dictionary.md) **_get_tags**\ (\ ) virtual const [🔗](#class_AudioStream_private_method__get_tags) + +Override this method to customize the tags for this audio stream. Should return a [Dictionary](class_dictionary.md) of strings with the tag as the key and its content as the value. + +Commonly used tags include ``title``, ``artist``, ``album``, ``tracknumber``, and ``date``. + +
+ + + + + +[bool](class_bool.md) **_has_loop**\ (\ ) virtual const [🔗](#class_AudioStream_private_method__has_loop) + +Override this method to return ``true`` if this stream has a loop. + +
+ + + + + +[AudioStreamPlayback](class_audiostreamplayback.md) **_instantiate_playback**\ (\ ) virtual const [🔗](#class_AudioStream_private_method__instantiate_playback) + +Override this method to customize the returned value of [instantiate_playback()](class_audiostream.md#class_AudioStream_method_instantiate_playback). Should return a new [AudioStreamPlayback](class_audiostreamplayback.md) created when the stream is played (such as by an [AudioStreamPlayer](class_audiostreamplayer.md)). + +
+ + + + + +[bool](class_bool.md) **_is_monophonic**\ (\ ) virtual const [🔗](#class_AudioStream_private_method__is_monophonic) + +Override this method to customize the returned value of [is_monophonic()](class_audiostream.md#class_AudioStream_method_is_monophonic). Should return ``true`` if this audio stream only supports one channel. + +
+ + + + + +[bool](class_bool.md) **can_be_sampled**\ (\ ) const [🔗](#class_AudioStream_method_can_be_sampled) + +**Experimental:** This method may be changed or removed in future versions. + +Returns if the current **AudioStream** can be used as a sample. Only static streams can be sampled. + +
+ + + + + +[AudioSample](class_audiosample.md) **generate_sample**\ (\ ) const [🔗](#class_AudioStream_method_generate_sample) + +**Experimental:** This method may be changed or removed in future versions. + +Generates an [AudioSample](class_audiosample.md) based on the current stream. + +
+ + + + + +[float](class_float.md) **get_length**\ (\ ) const [🔗](#class_AudioStream_method_get_length) + +Returns the length of the audio stream in seconds. If this stream is an [AudioStreamRandomizer](class_audiostreamrandomizer.md), returns the length of the last played stream. If this stream has an indefinite length (such as for [AudioStreamGenerator](class_audiostreamgenerator.md) and [AudioStreamMicrophone](class_audiostreammicrophone.md)), returns ``0.0``. + +
+ + + + + +[AudioStreamPlayback](class_audiostreamplayback.md) **instantiate_playback**\ (\ ) [🔗](#class_AudioStream_method_instantiate_playback) + +Returns a newly created [AudioStreamPlayback](class_audiostreamplayback.md) intended to play this audio stream. Useful for when you want to extend [_instantiate_playback()](class_audiostream.md#class_AudioStream_private_method__instantiate_playback) but call [instantiate_playback()](class_audiostream.md#class_AudioStream_method_instantiate_playback) from an internally held AudioStream subresource. An example of this can be found in the source code for ``AudioStreamRandomPitch::instantiate_playback``. + +
+ + + + + +[bool](class_bool.md) **is_meta_stream**\ (\ ) const [🔗](#class_AudioStream_method_is_meta_stream) + +Returns ``true`` if the stream is a collection of other streams, ``false`` otherwise. + +
+ + + + + +[bool](class_bool.md) **is_monophonic**\ (\ ) const [🔗](#class_AudioStream_method_is_monophonic) + +Returns ``true`` if this audio stream only supports one channel (*monophony*), or ``false`` if the audio stream supports two or more channels (*polyphony*). + diff --git a/docs/Classes/class_audiostreamgenerator.md b/docs/Classes/class_audiostreamgenerator.md new file mode 100644 index 00000000..55573790 --- /dev/null +++ b/docs/Classes/class_audiostreamgenerator.md @@ -0,0 +1,211 @@ + + + + + + + + + +# AudioStreamGenerator + +**Inherits:** [AudioStream](class_audiostream.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +An audio stream with utilities for procedural sound generation. + + + +## 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](class_audiostreamgeneratorplayback.md). + +Here's a sample on how to use it to generate a sine wave: + + + + +```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) +``` + +```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 < framesAvailable; i++) + { + _playback.PushFrame(Vector2.One * (float)Mathf.Sin(phase * Mathf.Tau)); + phase = Mathf.PosMod(phase + increment, 1.0); + } + } +``` + + + +In the example above, the "AudioStreamPlayer" node must use an **AudioStreamGenerator** as its stream. The ``fill_buffer`` function provides audio data for approximating a sine wave. + +See also [AudioEffectSpectrumAnalyzer](class_audioeffectspectrumanalyzer.md) for performing real-time audio spectrum analysis. + +\ **Note:** 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 [mix_rate](class_audiostreamgenerator.md#class_AudioStreamGenerator_property_mix_rate) such as 11,025 Hz or 22,050 Hz. + + + +## Tutorials + +- [Audio Generator Demo](https://godotengine.org/asset-library/asset/2759) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[buffer_length](#class_AudioStreamGenerator_property_buffer_length)`0.5`
[float](class_float.md)[mix_rate](#class_AudioStreamGenerator_property_mix_rate)`44100.0`
[AudioStreamGeneratorMixRate](class_audiostreamgenerator.md#enum_AudioStreamGenerator_AudioStreamGeneratorMixRate)[mix_rate_mode](#class_AudioStreamGenerator_property_mix_rate_mode)`2`
+ +
+ + + +## Enumerations + + + + + +enum **AudioStreamGeneratorMixRate**: [🔗](#enum_AudioStreamGenerator_AudioStreamGeneratorMixRate) + + + + + +[AudioStreamGeneratorMixRate](class_audiostreamgenerator.md#enum_AudioStreamGenerator_AudioStreamGeneratorMixRate) **MIX_RATE_OUTPUT** = `0` + +Current [AudioServer](class_audioserver.md) output mixing rate. + + + +[AudioStreamGeneratorMixRate](class_audiostreamgenerator.md#enum_AudioStreamGenerator_AudioStreamGeneratorMixRate) **MIX_RATE_INPUT** = `1` + +Current [AudioServer](class_audioserver.md) input mixing rate. + + + +[AudioStreamGeneratorMixRate](class_audiostreamgenerator.md#enum_AudioStreamGenerator_AudioStreamGeneratorMixRate) **MIX_RATE_CUSTOM** = `2` + +Custom mixing rate, specified by [mix_rate](class_audiostreamgenerator.md#class_AudioStreamGenerator_property_mix_rate). + + + +[AudioStreamGeneratorMixRate](class_audiostreamgenerator.md#enum_AudioStreamGenerator_AudioStreamGeneratorMixRate) **MIX_RATE_MAX** = `3` + +Maximum value for the mixing rate mode enum.
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **buffer_length** = `0.5` [🔗](#class_AudioStreamGenerator_property_buffer_length) + + + +- `void` **set_buffer_length**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_buffer_length**\ (\ ) + +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. + +
+ + + + + +[float](class_float.md) **mix_rate** = `44100.0` [🔗](#class_AudioStreamGenerator_property_mix_rate) + + + +- `void` **set_mix_rate**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_mix_rate**\ (\ ) + +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 ``11025``, ``16000``, ``22050``, ``32000``, ``44100``, and ``48000``. + +According to the [Nyquist-Shannon sampling theorem](https://en.wikipedia.org/wiki/Nyquist%E2%80%93Shannon_sampling_theorem), 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 ``32000`` or ``22050`` may be usable with no loss in quality. + +\ **Note:** **AudioStreamGenerator** is not automatically resampling input data, to produce expected result [mix_rate_mode](class_audiostreamgenerator.md#class_AudioStreamGenerator_property_mix_rate_mode) should match the sampling rate of input data. + +\ **Note:** If you are using [AudioEffectCapture](class_audioeffectcapture.md) as the source of your data, set [mix_rate_mode](class_audiostreamgenerator.md#class_AudioStreamGenerator_property_mix_rate_mode) to [MIX_RATE_INPUT](class_audiostreamgenerator.md#class_AudioStreamGenerator_constant_MIX_RATE_INPUT) or [MIX_RATE_OUTPUT](class_audiostreamgenerator.md#class_AudioStreamGenerator_constant_MIX_RATE_OUTPUT) to automatically match current [AudioServer](class_audioserver.md) mixing rate. + +
+ + + + + +[AudioStreamGeneratorMixRate](class_audiostreamgenerator.md#enum_AudioStreamGenerator_AudioStreamGeneratorMixRate) **mix_rate_mode** = `2` [🔗](#class_AudioStreamGenerator_property_mix_rate_mode) + + + +- `void` **set_mix_rate_mode**\ (\ value\: [AudioStreamGeneratorMixRate](class_audiostreamgenerator.md#enum_AudioStreamGenerator_AudioStreamGeneratorMixRate)\ ) +- [AudioStreamGeneratorMixRate](class_audiostreamgenerator.md#enum_AudioStreamGenerator_AudioStreamGeneratorMixRate) **get_mix_rate_mode**\ (\ ) + +Mixing rate mode. If set to [MIX_RATE_CUSTOM](class_audiostreamgenerator.md#class_AudioStreamGenerator_constant_MIX_RATE_CUSTOM), [mix_rate](class_audiostreamgenerator.md#class_AudioStreamGenerator_property_mix_rate) is used, otherwise current [AudioServer](class_audioserver.md) mixing rate is used. + diff --git a/docs/Classes/class_audiostreamgeneratorplayback.md b/docs/Classes/class_audiostreamgeneratorplayback.md new file mode 100644 index 00000000..57e02e57 --- /dev/null +++ b/docs/Classes/class_audiostreamgeneratorplayback.md @@ -0,0 +1,128 @@ + + + + + + + + + +# AudioStreamGeneratorPlayback + +**Inherits:** [AudioStreamPlaybackResampled](class_audiostreamplaybackresampled.md) **<** [AudioStreamPlayback](class_audiostreamplayback.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Plays back audio generated using [AudioStreamGenerator](class_audiostreamgenerator.md). + + + +## Description + +This class is meant to be used with [AudioStreamGenerator](class_audiostreamgenerator.md) to play back the generated audio in real-time. + + + +## Tutorials + +- [Audio Generator Demo](https://godotengine.org/asset-library/asset/2759) + +- [Godot 3.2 will get new audio features](https://godotengine.org/article/godot-32-will-get-new-audio-features) + + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[can_push_buffer](#class_AudioStreamGeneratorPlayback_method_can_push_buffer)\ (\ amount\: [int](class_int.md)\ ) const
`void`[clear_buffer](#class_AudioStreamGeneratorPlayback_method_clear_buffer)\ (\ )
[int](class_int.md)[get_frames_available](#class_AudioStreamGeneratorPlayback_method_get_frames_available)\ (\ ) const
[int](class_int.md)[get_skips](#class_AudioStreamGeneratorPlayback_method_get_skips)\ (\ ) const
[bool](class_bool.md)[push_buffer](#class_AudioStreamGeneratorPlayback_method_push_buffer)\ (\ frames\: [PackedVector2Array](class_packedvector2array.md)\ )
[bool](class_bool.md)[push_frame](#class_AudioStreamGeneratorPlayback_method_push_frame)\ (\ frame\: [Vector2](class_vector2.md)\ )
+ +
+ + + +## Method Descriptions + + + + + +[bool](class_bool.md) **can_push_buffer**\ (\ amount\: [int](class_int.md)\ ) const [🔗](#class_AudioStreamGeneratorPlayback_method_can_push_buffer) + +Returns ``true`` if a buffer of the size `amount` can be pushed to the audio sample data buffer without overflowing it, ``false`` otherwise. + +
+ + + + + +`void` **clear_buffer**\ (\ ) [🔗](#class_AudioStreamGeneratorPlayback_method_clear_buffer) + +Clears the audio sample data buffer. + +
+ + + + + +[int](class_int.md) **get_frames_available**\ (\ ) const [🔗](#class_AudioStreamGeneratorPlayback_method_get_frames_available) + +Returns the number of frames that can be pushed to the audio sample data buffer without overflowing it. If the result is ``0``, the buffer is full. + +
+ + + + + +[int](class_int.md) **get_skips**\ (\ ) const [🔗](#class_AudioStreamGeneratorPlayback_method_get_skips) + +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. + +
+ + + + + +[bool](class_bool.md) **push_buffer**\ (\ frames\: [PackedVector2Array](class_packedvector2array.md)\ ) [🔗](#class_AudioStreamGeneratorPlayback_method_push_buffer) + +Pushes several audio data frames to the buffer. This is usually more efficient than [push_frame()](class_audiostreamgeneratorplayback.md#class_AudioStreamGeneratorPlayback_method_push_frame) in C# and compiled languages via GDExtension, but [push_buffer()](class_audiostreamgeneratorplayback.md#class_AudioStreamGeneratorPlayback_method_push_buffer) may be *less* efficient in GDScript. + +
+ + + + + +[bool](class_bool.md) **push_frame**\ (\ frame\: [Vector2](class_vector2.md)\ ) [🔗](#class_AudioStreamGeneratorPlayback_method_push_frame) + +Pushes a single audio data frame to the buffer. This is usually less efficient than [push_buffer()](class_audiostreamgeneratorplayback.md#class_AudioStreamGeneratorPlayback_method_push_buffer) in C# and compiled languages via GDExtension, but [push_frame()](class_audiostreamgeneratorplayback.md#class_AudioStreamGeneratorPlayback_method_push_frame) may be *more* efficient in GDScript. + diff --git a/docs/Classes/class_audiostreaminteractive.md b/docs/Classes/class_audiostreaminteractive.md new file mode 100644 index 00000000..7b58e428 --- /dev/null +++ b/docs/Classes/class_audiostreaminteractive.md @@ -0,0 +1,507 @@ + + + + + + + + + +# AudioStreamInteractive + +**Inherits:** [AudioStream](class_audiostream.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Audio stream that can playback music interactively, combining clips and a transition table. + + + +## Description + +This is an audio stream that can playback music interactively, combining clips and a transition table. Clips must be added first, and then the transition rules via the [add_transition()](class_audiostreaminteractive.md#class_AudioStreamInteractive_method_add_transition). Additionally, this stream exports a property parameter to control the playback via [AudioStreamPlayer](class_audiostreamplayer.md), [AudioStreamPlayer2D](class_audiostreamplayer2d.md), or [AudioStreamPlayer3D](class_audiostreamplayer3d.md). + +The way this is used is by filling a number of clips, then configuring the transition table. From there, clips are selected for playback and the music will smoothly go from the current to the new one while using the corresponding transition rule defined in the transition table. + + + +## Properties + + + + + + + + + + + + + + + + +
[int](class_int.md)[clip_count](#class_AudioStreamInteractive_property_clip_count)`0`
[int](class_int.md)[initial_clip](#class_AudioStreamInteractive_property_initial_clip)`0`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
`void`[add_transition](#class_AudioStreamInteractive_method_add_transition)\ (\ from_clip\: [int](class_int.md), to_clip\: [int](class_int.md), from_time\: [TransitionFromTime](class_audiostreaminteractive.md#enum_AudioStreamInteractive_TransitionFromTime), to_time\: [TransitionToTime](class_audiostreaminteractive.md#enum_AudioStreamInteractive_TransitionToTime), fade_mode\: [FadeMode](class_audiostreaminteractive.md#enum_AudioStreamInteractive_FadeMode), fade_beats\: [float](class_float.md), use_filler_clip\: [bool](class_bool.md) = false, filler_clip\: [int](class_int.md) = -1, hold_previous\: [bool](class_bool.md) = false\ )
`void`[erase_transition](#class_AudioStreamInteractive_method_erase_transition)\ (\ from_clip\: [int](class_int.md), to_clip\: [int](class_int.md)\ )
[AutoAdvanceMode](class_audiostreaminteractive.md#enum_AudioStreamInteractive_AutoAdvanceMode)[get_clip_auto_advance](#class_AudioStreamInteractive_method_get_clip_auto_advance)\ (\ clip_index\: [int](class_int.md)\ ) const
[int](class_int.md)[get_clip_auto_advance_next_clip](#class_AudioStreamInteractive_method_get_clip_auto_advance_next_clip)\ (\ clip_index\: [int](class_int.md)\ ) const
[StringName](class_stringname.md)[get_clip_name](#class_AudioStreamInteractive_method_get_clip_name)\ (\ clip_index\: [int](class_int.md)\ ) const
[AudioStream](class_audiostream.md)[get_clip_stream](#class_AudioStreamInteractive_method_get_clip_stream)\ (\ clip_index\: [int](class_int.md)\ ) const
[float](class_float.md)[get_transition_fade_beats](#class_AudioStreamInteractive_method_get_transition_fade_beats)\ (\ from_clip\: [int](class_int.md), to_clip\: [int](class_int.md)\ ) const
[FadeMode](class_audiostreaminteractive.md#enum_AudioStreamInteractive_FadeMode)[get_transition_fade_mode](#class_AudioStreamInteractive_method_get_transition_fade_mode)\ (\ from_clip\: [int](class_int.md), to_clip\: [int](class_int.md)\ ) const
[int](class_int.md)[get_transition_filler_clip](#class_AudioStreamInteractive_method_get_transition_filler_clip)\ (\ from_clip\: [int](class_int.md), to_clip\: [int](class_int.md)\ ) const
[TransitionFromTime](class_audiostreaminteractive.md#enum_AudioStreamInteractive_TransitionFromTime)[get_transition_from_time](#class_AudioStreamInteractive_method_get_transition_from_time)\ (\ from_clip\: [int](class_int.md), to_clip\: [int](class_int.md)\ ) const
[PackedInt32Array](class_packedint32array.md)[get_transition_list](#class_AudioStreamInteractive_method_get_transition_list)\ (\ ) const
[TransitionToTime](class_audiostreaminteractive.md#enum_AudioStreamInteractive_TransitionToTime)[get_transition_to_time](#class_AudioStreamInteractive_method_get_transition_to_time)\ (\ from_clip\: [int](class_int.md), to_clip\: [int](class_int.md)\ ) const
[bool](class_bool.md)[has_transition](#class_AudioStreamInteractive_method_has_transition)\ (\ from_clip\: [int](class_int.md), to_clip\: [int](class_int.md)\ ) const
[bool](class_bool.md)[is_transition_holding_previous](#class_AudioStreamInteractive_method_is_transition_holding_previous)\ (\ from_clip\: [int](class_int.md), to_clip\: [int](class_int.md)\ ) const
[bool](class_bool.md)[is_transition_using_filler_clip](#class_AudioStreamInteractive_method_is_transition_using_filler_clip)\ (\ from_clip\: [int](class_int.md), to_clip\: [int](class_int.md)\ ) const
`void`[set_clip_auto_advance](#class_AudioStreamInteractive_method_set_clip_auto_advance)\ (\ clip_index\: [int](class_int.md), mode\: [AutoAdvanceMode](class_audiostreaminteractive.md#enum_AudioStreamInteractive_AutoAdvanceMode)\ )
`void`[set_clip_auto_advance_next_clip](#class_AudioStreamInteractive_method_set_clip_auto_advance_next_clip)\ (\ clip_index\: [int](class_int.md), auto_advance_next_clip\: [int](class_int.md)\ )
`void`[set_clip_name](#class_AudioStreamInteractive_method_set_clip_name)\ (\ clip_index\: [int](class_int.md), name\: [StringName](class_stringname.md)\ )
`void`[set_clip_stream](#class_AudioStreamInteractive_method_set_clip_stream)\ (\ clip_index\: [int](class_int.md), stream\: [AudioStream](class_audiostream.md)\ )
+ +
+ + + +## Enumerations + + + + + +enum **TransitionFromTime**: [🔗](#enum_AudioStreamInteractive_TransitionFromTime) + + + + + +[TransitionFromTime](class_audiostreaminteractive.md#enum_AudioStreamInteractive_TransitionFromTime) **TRANSITION_FROM_TIME_IMMEDIATE** = `0` + +Start transition as soon as possible, don't wait for any specific time position. + + + +[TransitionFromTime](class_audiostreaminteractive.md#enum_AudioStreamInteractive_TransitionFromTime) **TRANSITION_FROM_TIME_NEXT_BEAT** = `1` + +Transition when the clip playback position reaches the next beat. + + + +[TransitionFromTime](class_audiostreaminteractive.md#enum_AudioStreamInteractive_TransitionFromTime) **TRANSITION_FROM_TIME_NEXT_BAR** = `2` + +Transition when the clip playback position reaches the next bar. + + + +[TransitionFromTime](class_audiostreaminteractive.md#enum_AudioStreamInteractive_TransitionFromTime) **TRANSITION_FROM_TIME_END** = `3` + +Transition when the current clip finished playing.
+ + + + + +enum **TransitionToTime**: [🔗](#enum_AudioStreamInteractive_TransitionToTime) + + + + + +[TransitionToTime](class_audiostreaminteractive.md#enum_AudioStreamInteractive_TransitionToTime) **TRANSITION_TO_TIME_SAME_POSITION** = `0` + +Transition to the same position in the destination clip. This is useful when both clips have exactly the same length and the music should fade between them. + + + +[TransitionToTime](class_audiostreaminteractive.md#enum_AudioStreamInteractive_TransitionToTime) **TRANSITION_TO_TIME_START** = `1` + +Transition to the start of the destination clip.
+ + + + + +enum **FadeMode**: [🔗](#enum_AudioStreamInteractive_FadeMode) + + + + + +[FadeMode](class_audiostreaminteractive.md#enum_AudioStreamInteractive_FadeMode) **FADE_DISABLED** = `0` + +Do not use fade for the transition. This is useful when transitioning from a clip-end to clip-beginning, and each clip has their begin/end. + + + +[FadeMode](class_audiostreaminteractive.md#enum_AudioStreamInteractive_FadeMode) **FADE_IN** = `1` + +Use a fade-in in the next clip, let the current clip finish. + + + +[FadeMode](class_audiostreaminteractive.md#enum_AudioStreamInteractive_FadeMode) **FADE_OUT** = `2` + +Use a fade-out in the current clip, the next clip will start by itself. + + + +[FadeMode](class_audiostreaminteractive.md#enum_AudioStreamInteractive_FadeMode) **FADE_CROSS** = `3` + +Use a cross-fade between clips. + + + +[FadeMode](class_audiostreaminteractive.md#enum_AudioStreamInteractive_FadeMode) **FADE_AUTOMATIC** = `4` + +Use automatic fade logic depending on the transition from/to. It is recommended to use this by default.
+ + + + + +enum **AutoAdvanceMode**: [🔗](#enum_AudioStreamInteractive_AutoAdvanceMode) + + + + + +[AutoAdvanceMode](class_audiostreaminteractive.md#enum_AudioStreamInteractive_AutoAdvanceMode) **AUTO_ADVANCE_DISABLED** = `0` + +Disable auto-advance (default). + + + +[AutoAdvanceMode](class_audiostreaminteractive.md#enum_AudioStreamInteractive_AutoAdvanceMode) **AUTO_ADVANCE_ENABLED** = `1` + +Enable auto-advance, a clip must be specified. + + + +[AutoAdvanceMode](class_audiostreaminteractive.md#enum_AudioStreamInteractive_AutoAdvanceMode) **AUTO_ADVANCE_RETURN_TO_HOLD** = `2` + +Enable auto-advance, but instead of specifying a clip, the playback will return to hold (see [add_transition()](class_audiostreaminteractive.md#class_AudioStreamInteractive_method_add_transition)).
+ + + +## Constants + + + + + +**CLIP_ANY** = `-1` [🔗](#class_AudioStreamInteractive_constant_CLIP_ANY) + +This constant describes that any clip is valid for a specific transition as either source or destination. + +
+ + + +## Property Descriptions + + + + + +[int](class_int.md) **clip_count** = `0` [🔗](#class_AudioStreamInteractive_property_clip_count) + + + +- `void` **set_clip_count**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_clip_count**\ (\ ) + +Amount of clips contained in this interactive player. + +
+ + + + + +[int](class_int.md) **initial_clip** = `0` [🔗](#class_AudioStreamInteractive_property_initial_clip) + + + +- `void` **set_initial_clip**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_initial_clip**\ (\ ) + +Index of the initial clip, which will be played first when this stream is played. + +
+ + + +## Method Descriptions + + + + + +`void` **add_transition**\ (\ from_clip\: [int](class_int.md), to_clip\: [int](class_int.md), from_time\: [TransitionFromTime](class_audiostreaminteractive.md#enum_AudioStreamInteractive_TransitionFromTime), to_time\: [TransitionToTime](class_audiostreaminteractive.md#enum_AudioStreamInteractive_TransitionToTime), fade_mode\: [FadeMode](class_audiostreaminteractive.md#enum_AudioStreamInteractive_FadeMode), fade_beats\: [float](class_float.md), use_filler_clip\: [bool](class_bool.md) = false, filler_clip\: [int](class_int.md) = -1, hold_previous\: [bool](class_bool.md) = false\ ) [🔗](#class_AudioStreamInteractive_method_add_transition) + +Add a transition between two clips. Provide the indices of the source and destination clips, or use the [CLIP_ANY](class_audiostreaminteractive.md#class_AudioStreamInteractive_constant_CLIP_ANY) constant to indicate that transition happens to/from any clip to this one. + +\* `from_time` indicates the moment in the current clip the transition will begin after triggered. + +\* `to_time` indicates the time in the next clip that the playback will start from. + +\* `fade_mode` indicates how the fade will happen between clips. If unsure, just use [FADE_AUTOMATIC](class_audiostreaminteractive.md#class_AudioStreamInteractive_constant_FADE_AUTOMATIC) which uses the most common type of fade for each situation. + +\* `fade_beats` indicates how many beats the fade will take. Using decimals is allowed. + +\* `use_filler_clip` indicates that there will be a filler clip used between the source and destination clips. + +\* `filler_clip` the index of the filler clip. + +\* If `hold_previous` is used, then this clip will be remembered. This can be used together with [AUTO_ADVANCE_RETURN_TO_HOLD](class_audiostreaminteractive.md#class_AudioStreamInteractive_constant_AUTO_ADVANCE_RETURN_TO_HOLD) to return to this clip after another is done playing. + +
+ + + + + +`void` **erase_transition**\ (\ from_clip\: [int](class_int.md), to_clip\: [int](class_int.md)\ ) [🔗](#class_AudioStreamInteractive_method_erase_transition) + +Erase a transition by providing `from_clip` and `to_clip` clip indices. [CLIP_ANY](class_audiostreaminteractive.md#class_AudioStreamInteractive_constant_CLIP_ANY) can be used for either argument or both. + +
+ + + + + +[AutoAdvanceMode](class_audiostreaminteractive.md#enum_AudioStreamInteractive_AutoAdvanceMode) **get_clip_auto_advance**\ (\ clip_index\: [int](class_int.md)\ ) const [🔗](#class_AudioStreamInteractive_method_get_clip_auto_advance) + +Return whether a clip has auto-advance enabled. See [set_clip_auto_advance()](class_audiostreaminteractive.md#class_AudioStreamInteractive_method_set_clip_auto_advance). + +
+ + + + + +[int](class_int.md) **get_clip_auto_advance_next_clip**\ (\ clip_index\: [int](class_int.md)\ ) const [🔗](#class_AudioStreamInteractive_method_get_clip_auto_advance_next_clip) + +Return the clip towards which the clip referenced by `clip_index` will auto-advance to. + +
+ + + + + +[StringName](class_stringname.md) **get_clip_name**\ (\ clip_index\: [int](class_int.md)\ ) const [🔗](#class_AudioStreamInteractive_method_get_clip_name) + +Return the name of a clip. + +
+ + + + + +[AudioStream](class_audiostream.md) **get_clip_stream**\ (\ clip_index\: [int](class_int.md)\ ) const [🔗](#class_AudioStreamInteractive_method_get_clip_stream) + +Return the [AudioStream](class_audiostream.md) associated with a clip. + +
+ + + + + +[float](class_float.md) **get_transition_fade_beats**\ (\ from_clip\: [int](class_int.md), to_clip\: [int](class_int.md)\ ) const [🔗](#class_AudioStreamInteractive_method_get_transition_fade_beats) + +Return the time (in beats) for a transition (see [add_transition()](class_audiostreaminteractive.md#class_AudioStreamInteractive_method_add_transition)). + +
+ + + + + +[FadeMode](class_audiostreaminteractive.md#enum_AudioStreamInteractive_FadeMode) **get_transition_fade_mode**\ (\ from_clip\: [int](class_int.md), to_clip\: [int](class_int.md)\ ) const [🔗](#class_AudioStreamInteractive_method_get_transition_fade_mode) + +Return the mode for a transition (see [add_transition()](class_audiostreaminteractive.md#class_AudioStreamInteractive_method_add_transition)). + +
+ + + + + +[int](class_int.md) **get_transition_filler_clip**\ (\ from_clip\: [int](class_int.md), to_clip\: [int](class_int.md)\ ) const [🔗](#class_AudioStreamInteractive_method_get_transition_filler_clip) + +Return the filler clip for a transition (see [add_transition()](class_audiostreaminteractive.md#class_AudioStreamInteractive_method_add_transition)). + +
+ + + + + +[TransitionFromTime](class_audiostreaminteractive.md#enum_AudioStreamInteractive_TransitionFromTime) **get_transition_from_time**\ (\ from_clip\: [int](class_int.md), to_clip\: [int](class_int.md)\ ) const [🔗](#class_AudioStreamInteractive_method_get_transition_from_time) + +Return the source time position for a transition (see [add_transition()](class_audiostreaminteractive.md#class_AudioStreamInteractive_method_add_transition)). + +
+ + + + + +[PackedInt32Array](class_packedint32array.md) **get_transition_list**\ (\ ) const [🔗](#class_AudioStreamInteractive_method_get_transition_list) + +Return the list of transitions (from, to interleaved). + +
+ + + + + +[TransitionToTime](class_audiostreaminteractive.md#enum_AudioStreamInteractive_TransitionToTime) **get_transition_to_time**\ (\ from_clip\: [int](class_int.md), to_clip\: [int](class_int.md)\ ) const [🔗](#class_AudioStreamInteractive_method_get_transition_to_time) + +Return the destination time position for a transition (see [add_transition()](class_audiostreaminteractive.md#class_AudioStreamInteractive_method_add_transition)). + +
+ + + + + +[bool](class_bool.md) **has_transition**\ (\ from_clip\: [int](class_int.md), to_clip\: [int](class_int.md)\ ) const [🔗](#class_AudioStreamInteractive_method_has_transition) + +Returns ``true`` if a given transition exists (was added via [add_transition()](class_audiostreaminteractive.md#class_AudioStreamInteractive_method_add_transition)). + +
+ + + + + +[bool](class_bool.md) **is_transition_holding_previous**\ (\ from_clip\: [int](class_int.md), to_clip\: [int](class_int.md)\ ) const [🔗](#class_AudioStreamInteractive_method_is_transition_holding_previous) + +Return whether a transition uses the *hold previous* functionality (see [add_transition()](class_audiostreaminteractive.md#class_AudioStreamInteractive_method_add_transition)). + +
+ + + + + +[bool](class_bool.md) **is_transition_using_filler_clip**\ (\ from_clip\: [int](class_int.md), to_clip\: [int](class_int.md)\ ) const [🔗](#class_AudioStreamInteractive_method_is_transition_using_filler_clip) + +Return whether a transition uses the *filler clip* functionality (see [add_transition()](class_audiostreaminteractive.md#class_AudioStreamInteractive_method_add_transition)). + +
+ + + + + +`void` **set_clip_auto_advance**\ (\ clip_index\: [int](class_int.md), mode\: [AutoAdvanceMode](class_audiostreaminteractive.md#enum_AudioStreamInteractive_AutoAdvanceMode)\ ) [🔗](#class_AudioStreamInteractive_method_set_clip_auto_advance) + +Set whether a clip will auto-advance by changing the auto-advance mode. + +
+ + + + + +`void` **set_clip_auto_advance_next_clip**\ (\ clip_index\: [int](class_int.md), auto_advance_next_clip\: [int](class_int.md)\ ) [🔗](#class_AudioStreamInteractive_method_set_clip_auto_advance_next_clip) + +Set the index of the next clip towards which this clip will auto advance to when finished. If the clip being played loops, then auto-advance will be ignored. + +
+ + + + + +`void` **set_clip_name**\ (\ clip_index\: [int](class_int.md), name\: [StringName](class_stringname.md)\ ) [🔗](#class_AudioStreamInteractive_method_set_clip_name) + +Set the name of the current clip (for easier identification). + +
+ + + + + +`void` **set_clip_stream**\ (\ clip_index\: [int](class_int.md), stream\: [AudioStream](class_audiostream.md)\ ) [🔗](#class_AudioStreamInteractive_method_set_clip_stream) + +Set the [AudioStream](class_audiostream.md) associated with the current clip. + diff --git a/docs/Classes/class_audiostreammicrophone.md b/docs/Classes/class_audiostreammicrophone.md new file mode 100644 index 00000000..8297799e --- /dev/null +++ b/docs/Classes/class_audiostreammicrophone.md @@ -0,0 +1,31 @@ + + + + + + + + + +# AudioStreamMicrophone + +**Inherits:** [AudioStream](class_audiostream.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Plays real-time audio input data. + + + +## Description + +When used directly in an [AudioStreamPlayer](class_audiostreamplayer.md) node, **AudioStreamMicrophone** plays back microphone input in real-time. This can be used in conjunction with [AudioEffectCapture](class_audioeffectcapture.md) to process the data or save it. + +\ **Note:** [ProjectSettings.audio/driver/enable_input](class_projectsettings.md#class_ProjectSettings_property_audio/driver/enable_input) must be ``true`` for audio input to work. See also that setting's description for caveats related to permissions and operating system privacy settings. + + + +## Tutorials + +- [Recording with microphone](../tutorials/audio/recording_with_microphone.md) + +- [Audio Mic Record Demo](https://github.com/Redot-Engine/redot-demo-projects/tree/master/audio/mic_record) + diff --git a/docs/Classes/class_audiostreammp3.md b/docs/Classes/class_audiostreammp3.md new file mode 100644 index 00000000..0ca89b1e --- /dev/null +++ b/docs/Classes/class_audiostreammp3.md @@ -0,0 +1,237 @@ + + + + + + + + + +# AudioStreamMP3 + +**Inherits:** [AudioStream](class_audiostream.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +MP3 audio stream driver. + + + +## Description + +MP3 audio stream driver. See [data](class_audiostreammp3.md#class_AudioStreamMP3_property_data) if you want to load an MP3 file at run-time. + +\ **Note:** This class can optionally support legacy MP1 and MP2 formats, provided that the engine is compiled with the ``minimp3_extra_formats=yes`` SCons option. These extra formats are not enabled by default. + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[int](class_int.md)[bar_beats](#class_AudioStreamMP3_property_bar_beats)`4`
[int](class_int.md)[beat_count](#class_AudioStreamMP3_property_beat_count)`0`
[float](class_float.md)[bpm](#class_AudioStreamMP3_property_bpm)`0.0`
[PackedByteArray](class_packedbytearray.md)[data](#class_AudioStreamMP3_property_data)`PackedByteArray()`
[bool](class_bool.md)[loop](#class_AudioStreamMP3_property_loop)`false`
[float](class_float.md)[loop_offset](#class_AudioStreamMP3_property_loop_offset)`0.0`
+ + + +## Methods + + + + + + + + + + + + + + +
[AudioStreamMP3](class_audiostreammp3.md)[load_from_buffer](#class_AudioStreamMP3_method_load_from_buffer)\ (\ stream_data\: [PackedByteArray](class_packedbytearray.md)\ ) static
[AudioStreamMP3](class_audiostreammp3.md)[load_from_file](#class_AudioStreamMP3_method_load_from_file)\ (\ path\: [String](class_string.md)\ ) static
+ +
+ + + +## Property Descriptions + + + + + +[int](class_int.md) **bar_beats** = `4` [🔗](#class_AudioStreamMP3_property_bar_beats) + + + +- `void` **set_bar_beats**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_bar_beats**\ (\ ) + +
+There is currently no description for this property. Please help us by contributing one! + +
+ +
+ + + + + +[int](class_int.md) **beat_count** = `0` [🔗](#class_AudioStreamMP3_property_beat_count) + + + +- `void` **set_beat_count**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_beat_count**\ (\ ) + +
+There is currently no description for this property. Please help us by contributing one! + +
+ +
+ + + + + +[float](class_float.md) **bpm** = `0.0` [🔗](#class_AudioStreamMP3_property_bpm) + + + +- `void` **set_bpm**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_bpm**\ (\ ) + +
+There is currently no description for this property. Please help us by contributing one! + +
+ +
+ + + + + +[PackedByteArray](class_packedbytearray.md) **data** = `PackedByteArray()` [🔗](#class_AudioStreamMP3_property_data) + + + +- `void` **set_data**\ (\ value\: [PackedByteArray](class_packedbytearray.md)\ ) +- [PackedByteArray](class_packedbytearray.md) **get_data**\ (\ ) + +Contains the audio data in bytes. + +You can load a file without having to import it beforehand using the code snippet below. Keep in mind that this snippet loads the whole file into memory and may not be ideal for huge files (hundreds of megabytes or more). + + + + +```gdscript + func load_mp3(path): + var file = FileAccess.open(path, FileAccess.READ) + var sound = AudioStreamMP3.new() + sound.data = file.get_buffer(file.get_length()) + return sound +``` + +```csharp + public AudioStreamMP3 LoadMP3(string path) + { + using var file = FileAccess.Open(path, FileAccess.ModeFlags.Read); + var sound = new AudioStreamMP3(); + sound.Data = file.GetBuffer(file.GetLength()); + return sound; + } +``` + + + +**Note:** The returned array is *copied* and any changes to it will not update the original property value. See [PackedByteArray](class_packedbytearray.md) for more details. + +
+ + + + + +[bool](class_bool.md) **loop** = `false` [🔗](#class_AudioStreamMP3_property_loop) + + + +- `void` **set_loop**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **has_loop**\ (\ ) + +If ``true``, the stream will automatically loop when it reaches the end. + +
+ + + + + +[float](class_float.md) **loop_offset** = `0.0` [🔗](#class_AudioStreamMP3_property_loop_offset) + + + +- `void` **set_loop_offset**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_loop_offset**\ (\ ) + +Time in seconds at which the stream starts after being looped. + +
+ + + +## Method Descriptions + + + + + +[AudioStreamMP3](class_audiostreammp3.md) **load_from_buffer**\ (\ stream_data\: [PackedByteArray](class_packedbytearray.md)\ ) static [🔗](#class_AudioStreamMP3_method_load_from_buffer) + +Creates a new **AudioStreamMP3** instance from the given buffer. The buffer must contain MP3 data. + +
+ + + + + +[AudioStreamMP3](class_audiostreammp3.md) **load_from_file**\ (\ path\: [String](class_string.md)\ ) static [🔗](#class_AudioStreamMP3_method_load_from_file) + +Creates a new **AudioStreamMP3** instance from the given file path. The file must be in MP3 format. + diff --git a/docs/Classes/class_audiostreamoggvorbis.md b/docs/Classes/class_audiostreamoggvorbis.md new file mode 100644 index 00000000..01731df4 --- /dev/null +++ b/docs/Classes/class_audiostreamoggvorbis.md @@ -0,0 +1,238 @@ + + + + + + + + + +# AudioStreamOggVorbis + +**Inherits:** [AudioStream](class_audiostream.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +A class representing an Ogg Vorbis audio stream. + + + +## Description + +The AudioStreamOggVorbis class is a specialized [AudioStream](class_audiostream.md) for handling Ogg Vorbis file formats. It offers functionality for loading and playing back Ogg Vorbis files, as well as managing looping and other playback properties. This class is part of the audio stream system, which also supports WAV files through the [AudioStreamWAV](class_audiostreamwav.md) class. + + + +## Tutorials + +- [Runtime file loading and saving](../tutorials/io/runtime_file_loading_and_saving.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[int](class_int.md)[bar_beats](#class_AudioStreamOggVorbis_property_bar_beats)`4`
[int](class_int.md)[beat_count](#class_AudioStreamOggVorbis_property_beat_count)`0`
[float](class_float.md)[bpm](#class_AudioStreamOggVorbis_property_bpm)`0.0`
[bool](class_bool.md)[loop](#class_AudioStreamOggVorbis_property_loop)`false`
[float](class_float.md)[loop_offset](#class_AudioStreamOggVorbis_property_loop_offset)`0.0`
[OggPacketSequence](class_oggpacketsequence.md)[packet_sequence](#class_AudioStreamOggVorbis_property_packet_sequence)
[Dictionary](class_dictionary.md)[tags](#class_AudioStreamOggVorbis_property_tags)`{}`
+ + + +## Methods + + + + + + + + + + + + + + +
[AudioStreamOggVorbis](class_audiostreamoggvorbis.md)[load_from_buffer](#class_AudioStreamOggVorbis_method_load_from_buffer)\ (\ stream_data\: [PackedByteArray](class_packedbytearray.md)\ ) static
[AudioStreamOggVorbis](class_audiostreamoggvorbis.md)[load_from_file](#class_AudioStreamOggVorbis_method_load_from_file)\ (\ path\: [String](class_string.md)\ ) static
+ +
+ + + +## Property Descriptions + + + + + +[int](class_int.md) **bar_beats** = `4` [🔗](#class_AudioStreamOggVorbis_property_bar_beats) + + + +- `void` **set_bar_beats**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_bar_beats**\ (\ ) + +
+There is currently no description for this property. Please help us by contributing one! + +
+ +
+ + + + + +[int](class_int.md) **beat_count** = `0` [🔗](#class_AudioStreamOggVorbis_property_beat_count) + + + +- `void` **set_beat_count**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_beat_count**\ (\ ) + +
+There is currently no description for this property. Please help us by contributing one! + +
+ +
+ + + + + +[float](class_float.md) **bpm** = `0.0` [🔗](#class_AudioStreamOggVorbis_property_bpm) + + + +- `void` **set_bpm**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_bpm**\ (\ ) + +
+There is currently no description for this property. Please help us by contributing one! + +
+ +
+ + + + + +[bool](class_bool.md) **loop** = `false` [🔗](#class_AudioStreamOggVorbis_property_loop) + + + +- `void` **set_loop**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **has_loop**\ (\ ) + +If ``true``, the audio will play again from the specified [loop_offset](class_audiostreamoggvorbis.md#class_AudioStreamOggVorbis_property_loop_offset) once it is done playing. Useful for ambient sounds and background music. + +
+ + + + + +[float](class_float.md) **loop_offset** = `0.0` [🔗](#class_AudioStreamOggVorbis_property_loop_offset) + + + +- `void` **set_loop_offset**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_loop_offset**\ (\ ) + +Time in seconds at which the stream starts after being looped. + +
+ + + + + +[OggPacketSequence](class_oggpacketsequence.md) **packet_sequence** [🔗](#class_AudioStreamOggVorbis_property_packet_sequence) + + + +- `void` **set_packet_sequence**\ (\ value\: [OggPacketSequence](class_oggpacketsequence.md)\ ) +- [OggPacketSequence](class_oggpacketsequence.md) **get_packet_sequence**\ (\ ) + +Contains the raw Ogg data for this stream. + +
+ + + + + +[Dictionary](class_dictionary.md) **tags** = `{}` [🔗](#class_AudioStreamOggVorbis_property_tags) + + + +- `void` **set_tags**\ (\ value\: [Dictionary](class_dictionary.md)\ ) +- [Dictionary](class_dictionary.md) **get_tags**\ (\ ) + +Contains user-defined tags if found in the Ogg Vorbis data. + +Commonly used tags include ``title``, ``artist``, ``album``, ``tracknumber``, and ``date`` (``date`` does not have a standard date format). + +\ **Note:** No tag is *guaranteed* to be present in every file, so make sure to account for the keys not always existing. + +
+ + + +## Method Descriptions + + + + + +[AudioStreamOggVorbis](class_audiostreamoggvorbis.md) **load_from_buffer**\ (\ stream_data\: [PackedByteArray](class_packedbytearray.md)\ ) static [🔗](#class_AudioStreamOggVorbis_method_load_from_buffer) + +Creates a new **AudioStreamOggVorbis** instance from the given buffer. The buffer must contain Ogg Vorbis data. + +
+ + + + + +[AudioStreamOggVorbis](class_audiostreamoggvorbis.md) **load_from_file**\ (\ path\: [String](class_string.md)\ ) static [🔗](#class_AudioStreamOggVorbis_method_load_from_file) + +Creates a new **AudioStreamOggVorbis** instance from the given file path. The file must be in Ogg Vorbis format. + diff --git a/docs/Classes/class_audiostreamplayback.md b/docs/Classes/class_audiostreamplayback.md new file mode 100644 index 00000000..45b98247 --- /dev/null +++ b/docs/Classes/class_audiostreamplayback.md @@ -0,0 +1,320 @@ + + + + + + + + + +# AudioStreamPlayback + +**Inherits:** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +**Inherited By:** [AudioStreamPlaybackInteractive](class_audiostreamplaybackinteractive.md), [AudioStreamPlaybackPlaylist](class_audiostreamplaybackplaylist.md), [AudioStreamPlaybackPolyphonic](class_audiostreamplaybackpolyphonic.md), [AudioStreamPlaybackResampled](class_audiostreamplaybackresampled.md), [AudioStreamPlaybackSynchronized](class_audiostreamplaybacksynchronized.md) + +Meta class for playing back audio. + + + +## Description + +Can play, loop, pause a scroll through audio. See [AudioStream](class_audiostream.md) and [AudioStreamOggVorbis](class_audiostreamoggvorbis.md) for usage. + + + +## Tutorials + +- [Audio Generator Demo](https://godotengine.org/asset-library/asset/2759) + + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[int](class_int.md)[_get_loop_count](#class_AudioStreamPlayback_private_method__get_loop_count)\ (\ ) virtual const
[Variant](class_variant.md)[_get_parameter](#class_AudioStreamPlayback_private_method__get_parameter)\ (\ name\: [StringName](class_stringname.md)\ ) virtual const
[float](class_float.md)[_get_playback_position](#class_AudioStreamPlayback_private_method__get_playback_position)\ (\ ) virtual const
[bool](class_bool.md)[_is_playing](#class_AudioStreamPlayback_private_method__is_playing)\ (\ ) virtual const
[int](class_int.md)[_mix](#class_AudioStreamPlayback_private_method__mix)\ (\ buffer\: `AudioFrame*`, rate_scale\: [float](class_float.md), frames\: [int](class_int.md)\ ) virtual required
`void`[_seek](#class_AudioStreamPlayback_private_method__seek)\ (\ position\: [float](class_float.md)\ ) virtual
`void`[_set_parameter](#class_AudioStreamPlayback_private_method__set_parameter)\ (\ name\: [StringName](class_stringname.md), value\: [Variant](class_variant.md)\ ) virtual
`void`[_start](#class_AudioStreamPlayback_private_method__start)\ (\ from_pos\: [float](class_float.md)\ ) virtual
`void`[_stop](#class_AudioStreamPlayback_private_method__stop)\ (\ ) virtual
`void`[_tag_used_streams](#class_AudioStreamPlayback_private_method__tag_used_streams)\ (\ ) virtual
[int](class_int.md)[get_loop_count](#class_AudioStreamPlayback_method_get_loop_count)\ (\ ) const
[float](class_float.md)[get_playback_position](#class_AudioStreamPlayback_method_get_playback_position)\ (\ ) const
[AudioSamplePlayback](class_audiosampleplayback.md)[get_sample_playback](#class_AudioStreamPlayback_method_get_sample_playback)\ (\ ) const
[bool](class_bool.md)[is_playing](#class_AudioStreamPlayback_method_is_playing)\ (\ ) const
[PackedVector2Array](class_packedvector2array.md)[mix_audio](#class_AudioStreamPlayback_method_mix_audio)\ (\ rate_scale\: [float](class_float.md), frames\: [int](class_int.md)\ )
`void`[seek](#class_AudioStreamPlayback_method_seek)\ (\ time\: [float](class_float.md) = 0.0\ )
`void`[set_sample_playback](#class_AudioStreamPlayback_method_set_sample_playback)\ (\ playback_sample\: [AudioSamplePlayback](class_audiosampleplayback.md)\ )
`void`[start](#class_AudioStreamPlayback_method_start)\ (\ from_pos\: [float](class_float.md) = 0.0\ )
`void`[stop](#class_AudioStreamPlayback_method_stop)\ (\ )
+ +
+ + + +## Method Descriptions + + + + + +[int](class_int.md) **_get_loop_count**\ (\ ) virtual const [🔗](#class_AudioStreamPlayback_private_method__get_loop_count) + +Overridable method. Should return how many times this audio stream has looped. Most built-in playbacks always return ``0``. + +
+ + + + + +[Variant](class_variant.md) **_get_parameter**\ (\ name\: [StringName](class_stringname.md)\ ) virtual const [🔗](#class_AudioStreamPlayback_private_method__get_parameter) + +Return the current value of a playback parameter by name (see [AudioStream._get_parameter_list()](class_audiostream.md#class_AudioStream_private_method__get_parameter_list)). + +
+ + + + + +[float](class_float.md) **_get_playback_position**\ (\ ) virtual const [🔗](#class_AudioStreamPlayback_private_method__get_playback_position) + +Overridable method. Should return the current progress along the audio stream, in seconds. + +
+ + + + + +[bool](class_bool.md) **_is_playing**\ (\ ) virtual const [🔗](#class_AudioStreamPlayback_private_method__is_playing) + +Overridable method. Should return ``true`` if this playback is active and playing its audio stream. + +
+ + + + + +[int](class_int.md) **_mix**\ (\ buffer\: `AudioFrame*`, rate_scale\: [float](class_float.md), frames\: [int](class_int.md)\ ) virtual required [🔗](#class_AudioStreamPlayback_private_method__mix) + +Override this method to customize how the audio stream is mixed. This method is called even if the playback is not active. + +\ **Note:** It is not useful to override this method in GDScript or C#. Only GDExtension can take advantage of it. + +
+ + + + + +`void` **_seek**\ (\ position\: [float](class_float.md)\ ) virtual [🔗](#class_AudioStreamPlayback_private_method__seek) + +Override this method to customize what happens when seeking this audio stream at the given `position`, such as by calling [AudioStreamPlayer.seek()](class_audiostreamplayer.md#class_AudioStreamPlayer_method_seek). + +
+ + + + + +`void` **_set_parameter**\ (\ name\: [StringName](class_stringname.md), value\: [Variant](class_variant.md)\ ) virtual [🔗](#class_AudioStreamPlayback_private_method__set_parameter) + +Set the current value of a playback parameter by name (see [AudioStream._get_parameter_list()](class_audiostream.md#class_AudioStream_private_method__get_parameter_list)). + +
+ + + + + +`void` **_start**\ (\ from_pos\: [float](class_float.md)\ ) virtual [🔗](#class_AudioStreamPlayback_private_method__start) + +Override this method to customize what happens when the playback starts at the given position, such as by calling [AudioStreamPlayer.play()](class_audiostreamplayer.md#class_AudioStreamPlayer_method_play). + +
+ + + + + +`void` **_stop**\ (\ ) virtual [🔗](#class_AudioStreamPlayback_private_method__stop) + +Override this method to customize what happens when the playback is stopped, such as by calling [AudioStreamPlayer.stop()](class_audiostreamplayer.md#class_AudioStreamPlayer_method_stop). + +
+ + + + + +`void` **_tag_used_streams**\ (\ ) virtual [🔗](#class_AudioStreamPlayback_private_method__tag_used_streams) + +Overridable method. Called whenever the audio stream is mixed if the playback is active and [AudioServer.set_enable_tagging_used_audio_streams()](class_audioserver.md#class_AudioServer_method_set_enable_tagging_used_audio_streams) has been set to ``true``. Editor plugins may use this method to "tag" the current position along the audio stream and display it in a preview. + +
+ + + + + +[int](class_int.md) **get_loop_count**\ (\ ) const [🔗](#class_AudioStreamPlayback_method_get_loop_count) + +Returns the number of times the stream has looped. + +
+ + + + + +[float](class_float.md) **get_playback_position**\ (\ ) const [🔗](#class_AudioStreamPlayback_method_get_playback_position) + +Returns the current position in the stream, in seconds. + +
+ + + + + +[AudioSamplePlayback](class_audiosampleplayback.md) **get_sample_playback**\ (\ ) const [🔗](#class_AudioStreamPlayback_method_get_sample_playback) + +**Experimental:** This method may be changed or removed in future versions. + +Returns the [AudioSamplePlayback](class_audiosampleplayback.md) associated with this **AudioStreamPlayback** for playing back the audio sample of this stream. + +
+ + + + + +[bool](class_bool.md) **is_playing**\ (\ ) const [🔗](#class_AudioStreamPlayback_method_is_playing) + +Returns ``true`` if the stream is playing. + +
+ + + + + +[PackedVector2Array](class_packedvector2array.md) **mix_audio**\ (\ rate_scale\: [float](class_float.md), frames\: [int](class_int.md)\ ) [🔗](#class_AudioStreamPlayback_method_mix_audio) + +Mixes up to `frames` of audio from the stream from the current position, at a rate of `rate_scale`, advancing the stream. + +Returns a [PackedVector2Array](class_packedvector2array.md) where each element holds the left and right channel volume levels of each frame. + +\ **Note:** Can return fewer frames than requested, make sure to use the size of the return value. + +
+ + + + + +`void` **seek**\ (\ time\: [float](class_float.md) = 0.0\ ) [🔗](#class_AudioStreamPlayback_method_seek) + +Seeks the stream at the given `time`, in seconds. + +
+ + + + + +`void` **set_sample_playback**\ (\ playback_sample\: [AudioSamplePlayback](class_audiosampleplayback.md)\ ) [🔗](#class_AudioStreamPlayback_method_set_sample_playback) + +**Experimental:** This method may be changed or removed in future versions. + +Associates [AudioSamplePlayback](class_audiosampleplayback.md) to this **AudioStreamPlayback** for playing back the audio sample of this stream. + +
+ + + + + +`void` **start**\ (\ from_pos\: [float](class_float.md) = 0.0\ ) [🔗](#class_AudioStreamPlayback_method_start) + +Starts the stream from the given `from_pos`, in seconds. + +
+ + + + + +`void` **stop**\ (\ ) [🔗](#class_AudioStreamPlayback_method_stop) + +Stops the stream. + diff --git a/docs/Classes/class_audiostreamplaybackinteractive.md b/docs/Classes/class_audiostreamplaybackinteractive.md new file mode 100644 index 00000000..8e357068 --- /dev/null +++ b/docs/Classes/class_audiostreamplaybackinteractive.md @@ -0,0 +1,89 @@ + + + + + + + + + +# AudioStreamPlaybackInteractive + +**Inherits:** [AudioStreamPlayback](class_audiostreamplayback.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Playback component of [AudioStreamInteractive](class_audiostreaminteractive.md). + + + +## Description + +Playback component of [AudioStreamInteractive](class_audiostreaminteractive.md). Contains functions to change the currently played clip. + + + +## Methods + + + + + + + + + + + + + + + + + + +
[int](class_int.md)[get_current_clip_index](#class_AudioStreamPlaybackInteractive_method_get_current_clip_index)\ (\ ) const
`void`[switch_to_clip](#class_AudioStreamPlaybackInteractive_method_switch_to_clip)\ (\ clip_index\: [int](class_int.md)\ )
`void`[switch_to_clip_by_name](#class_AudioStreamPlaybackInteractive_method_switch_to_clip_by_name)\ (\ clip_name\: [StringName](class_stringname.md)\ )
+ +
+ + + +## Method Descriptions + + + + + +[int](class_int.md) **get_current_clip_index**\ (\ ) const [🔗](#class_AudioStreamPlaybackInteractive_method_get_current_clip_index) + +Return the index of the currently playing clip. You can use this to get the name of the currently playing clip with [AudioStreamInteractive.get_clip_name()](class_audiostreaminteractive.md#class_AudioStreamInteractive_method_get_clip_name). + +\ **Example:** Get the currently playing clip name from inside an [AudioStreamPlayer](class_audiostreamplayer.md) node. + + + + +```gdscript + var playing_clip_name = stream.get_clip_name(get_stream_playback().get_current_clip_index()) +``` + + + +
+ + + + + +`void` **switch_to_clip**\ (\ clip_index\: [int](class_int.md)\ ) [🔗](#class_AudioStreamPlaybackInteractive_method_switch_to_clip) + +Switch to a clip (by index). + +
+ + + + + +`void` **switch_to_clip_by_name**\ (\ clip_name\: [StringName](class_stringname.md)\ ) [🔗](#class_AudioStreamPlaybackInteractive_method_switch_to_clip_by_name) + +Switch to a clip (by name). + diff --git a/docs/Classes/class_audiostreamplaybackoggvorbis.md b/docs/Classes/class_audiostreamplaybackoggvorbis.md new file mode 100644 index 00000000..4257bb96 --- /dev/null +++ b/docs/Classes/class_audiostreamplaybackoggvorbis.md @@ -0,0 +1,18 @@ + + + + + + + + + +# AudioStreamPlaybackOggVorbis + +**Inherits:** [AudioStreamPlaybackResampled](class_audiostreamplaybackresampled.md) **<** [AudioStreamPlayback](class_audiostreamplayback.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +
+There is currently no description for this class. Please help us by contributing one! + +
+ diff --git a/docs/Classes/class_audiostreamplaybackplaylist.md b/docs/Classes/class_audiostreamplaybackplaylist.md new file mode 100644 index 00000000..5fe15568 --- /dev/null +++ b/docs/Classes/class_audiostreamplaybackplaylist.md @@ -0,0 +1,15 @@ + + + + + + + + + +# AudioStreamPlaybackPlaylist + +**Inherits:** [AudioStreamPlayback](class_audiostreamplayback.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Playback class used for [AudioStreamPlaylist](class_audiostreamplaylist.md). + diff --git a/docs/Classes/class_audiostreamplaybackpolyphonic.md b/docs/Classes/class_audiostreamplaybackpolyphonic.md new file mode 100644 index 00000000..2c3b7453 --- /dev/null +++ b/docs/Classes/class_audiostreamplaybackpolyphonic.md @@ -0,0 +1,126 @@ + + + + + + + + + +# AudioStreamPlaybackPolyphonic + +**Inherits:** [AudioStreamPlayback](class_audiostreamplayback.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Playback instance for [AudioStreamPolyphonic](class_audiostreampolyphonic.md). + + + +## Description + +Playback instance for [AudioStreamPolyphonic](class_audiostreampolyphonic.md). After setting the ``stream`` property of [AudioStreamPlayer](class_audiostreamplayer.md), [AudioStreamPlayer2D](class_audiostreamplayer2d.md), or [AudioStreamPlayer3D](class_audiostreamplayer3d.md), the playback instance can be obtained by calling [AudioStreamPlayer.get_stream_playback()](class_audiostreamplayer.md#class_AudioStreamPlayer_method_get_stream_playback), [AudioStreamPlayer2D.get_stream_playback()](class_audiostreamplayer2d.md#class_AudioStreamPlayer2D_method_get_stream_playback) or [AudioStreamPlayer3D.get_stream_playback()](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_method_get_stream_playback) methods. + + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[is_stream_playing](#class_AudioStreamPlaybackPolyphonic_method_is_stream_playing)\ (\ stream\: [int](class_int.md)\ ) const
[int](class_int.md)[play_stream](#class_AudioStreamPlaybackPolyphonic_method_play_stream)\ (\ stream\: [AudioStream](class_audiostream.md), from_offset\: [float](class_float.md) = 0, volume_db\: [float](class_float.md) = 0, pitch_scale\: [float](class_float.md) = 1.0, playback_type\: [PlaybackType](class_audioserver.md#enum_AudioServer_PlaybackType) = 0, bus\: [StringName](class_stringname.md) = &"Master"\ )
`void`[set_stream_pitch_scale](#class_AudioStreamPlaybackPolyphonic_method_set_stream_pitch_scale)\ (\ stream\: [int](class_int.md), pitch_scale\: [float](class_float.md)\ )
`void`[set_stream_volume](#class_AudioStreamPlaybackPolyphonic_method_set_stream_volume)\ (\ stream\: [int](class_int.md), volume_db\: [float](class_float.md)\ )
`void`[stop_stream](#class_AudioStreamPlaybackPolyphonic_method_stop_stream)\ (\ stream\: [int](class_int.md)\ )
+ +
+ + + +## Constants + + + + + +**INVALID_ID** = `-1` [🔗](#class_AudioStreamPlaybackPolyphonic_constant_INVALID_ID) + +Returned by [play_stream()](class_audiostreamplaybackpolyphonic.md#class_AudioStreamPlaybackPolyphonic_method_play_stream) in case it could not allocate a stream for playback. + +
+ + + +## Method Descriptions + + + + + +[bool](class_bool.md) **is_stream_playing**\ (\ stream\: [int](class_int.md)\ ) const [🔗](#class_AudioStreamPlaybackPolyphonic_method_is_stream_playing) + +Returns ``true`` if the stream associated with the given integer ID is still playing. Check [play_stream()](class_audiostreamplaybackpolyphonic.md#class_AudioStreamPlaybackPolyphonic_method_play_stream) for information on when this ID becomes invalid. + +
+ + + + + +[int](class_int.md) **play_stream**\ (\ stream\: [AudioStream](class_audiostream.md), from_offset\: [float](class_float.md) = 0, volume_db\: [float](class_float.md) = 0, pitch_scale\: [float](class_float.md) = 1.0, playback_type\: [PlaybackType](class_audioserver.md#enum_AudioServer_PlaybackType) = 0, bus\: [StringName](class_stringname.md) = &"Master"\ ) [🔗](#class_AudioStreamPlaybackPolyphonic_method_play_stream) + +Play an [AudioStream](class_audiostream.md) 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 [stop_stream()](class_audiostreamplaybackpolyphonic.md#class_AudioStreamPlaybackPolyphonic_method_stop_stream) is called. + +This function returns [INVALID_ID](class_audiostreamplaybackpolyphonic.md#class_AudioStreamPlaybackPolyphonic_constant_INVALID_ID) if the amount of streams currently playing equals [AudioStreamPolyphonic.polyphony](class_audiostreampolyphonic.md#class_AudioStreamPolyphonic_property_polyphony). If you need a higher amount of maximum polyphony, raise this value. + +
+ + + + + +`void` **set_stream_pitch_scale**\ (\ stream\: [int](class_int.md), pitch_scale\: [float](class_float.md)\ ) [🔗](#class_AudioStreamPlaybackPolyphonic_method_set_stream_pitch_scale) + +Change the stream pitch scale. The `stream` argument is an integer ID returned by [play_stream()](class_audiostreamplaybackpolyphonic.md#class_AudioStreamPlaybackPolyphonic_method_play_stream). + +
+ + + + + +`void` **set_stream_volume**\ (\ stream\: [int](class_int.md), volume_db\: [float](class_float.md)\ ) [🔗](#class_AudioStreamPlaybackPolyphonic_method_set_stream_volume) + +Change the stream volume (in db). The `stream` argument is an integer ID returned by [play_stream()](class_audiostreamplaybackpolyphonic.md#class_AudioStreamPlaybackPolyphonic_method_play_stream). + +
+ + + + + +`void` **stop_stream**\ (\ stream\: [int](class_int.md)\ ) [🔗](#class_AudioStreamPlaybackPolyphonic_method_stop_stream) + +Stop a stream. The `stream` argument is an integer ID returned by [play_stream()](class_audiostreamplaybackpolyphonic.md#class_AudioStreamPlaybackPolyphonic_method_play_stream), which becomes invalid after calling this function. + diff --git a/docs/Classes/class_audiostreamplaybackresampled.md b/docs/Classes/class_audiostreamplaybackresampled.md new file mode 100644 index 00000000..fad2a41a --- /dev/null +++ b/docs/Classes/class_audiostreamplaybackresampled.md @@ -0,0 +1,86 @@ + + + + + + + + + +# AudioStreamPlaybackResampled + +**Inherits:** [AudioStreamPlayback](class_audiostreamplayback.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +**Inherited By:** [AudioStreamGeneratorPlayback](class_audiostreamgeneratorplayback.md), [AudioStreamPlaybackOggVorbis](class_audiostreamplaybackoggvorbis.md) + +
+There is currently no description for this class. Please help us by contributing one! + +
+ + + +## Methods + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[_get_stream_sampling_rate](#class_AudioStreamPlaybackResampled_private_method__get_stream_sampling_rate)\ (\ ) virtual required const
[int](class_int.md)[_mix_resampled](#class_AudioStreamPlaybackResampled_private_method__mix_resampled)\ (\ dst_buffer\: `AudioFrame*`, frame_count\: [int](class_int.md)\ ) virtual required
`void`[begin_resample](#class_AudioStreamPlaybackResampled_method_begin_resample)\ (\ )
+ +
+ + + +## Method Descriptions + + + + + +[float](class_float.md) **_get_stream_sampling_rate**\ (\ ) virtual required const [🔗](#class_AudioStreamPlaybackResampled_private_method__get_stream_sampling_rate) + +
+There is currently no description for this method. Please help us by contributing one! + +
+ +
+ + + + + +[int](class_int.md) **_mix_resampled**\ (\ dst_buffer\: `AudioFrame*`, frame_count\: [int](class_int.md)\ ) virtual required [🔗](#class_AudioStreamPlaybackResampled_private_method__mix_resampled) + +
+There is currently no description for this method. Please help us by contributing one! + +
+ +
+ + + + + +`void` **begin_resample**\ (\ ) [🔗](#class_AudioStreamPlaybackResampled_method_begin_resample) + +
+There is currently no description for this method. Please help us by contributing one! + +
+ diff --git a/docs/Classes/class_audiostreamplaybacksynchronized.md b/docs/Classes/class_audiostreamplaybacksynchronized.md new file mode 100644 index 00000000..159acbd5 --- /dev/null +++ b/docs/Classes/class_audiostreamplaybacksynchronized.md @@ -0,0 +1,18 @@ + + + + + + + + + +# AudioStreamPlaybackSynchronized + +**Inherits:** [AudioStreamPlayback](class_audiostreamplayback.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +
+There is currently no description for this class. Please help us by contributing one! + +
+ diff --git a/docs/Classes/class_audiostreamplayer.md b/docs/Classes/class_audiostreamplayer.md new file mode 100644 index 00000000..48f1974c --- /dev/null +++ b/docs/Classes/class_audiostreamplayer.md @@ -0,0 +1,435 @@ + + + + + + + + + + + +# AudioStreamPlayer + +**Inherits:** [Node](class_node.md) **<** [Object](class_object.md) + +A node for audio playback. + + + +## Description + +The **AudioStreamPlayer** node plays an audio stream non-positionally. It is ideal for user interfaces, menus, or background music. + +To use this node, [stream](class_audiostreamplayer.md#class_AudioStreamPlayer_property_stream) needs to be set to a valid [AudioStream](class_audiostream.md) resource. Playing more than one sound at the same time is also supported, see [max_polyphony](class_audiostreamplayer.md#class_AudioStreamPlayer_property_max_polyphony). + +If you need to play audio at a specific position, use [AudioStreamPlayer2D](class_audiostreamplayer2d.md) or [AudioStreamPlayer3D](class_audiostreamplayer3d.md) instead. + + + +## Tutorials + +- [Audio streams](../tutorials/audio/audio_streams.md) + +- [2D Dodge The Creeps Demo](https://godotengine.org/asset-library/asset/2712) + +- [Audio Device Changer Demo](https://godotengine.org/asset-library/asset/2758) + +- [Audio Generator Demo](https://godotengine.org/asset-library/asset/2759) + +- [Audio Microphone Record Demo](https://godotengine.org/asset-library/asset/2760) + +- [Audio Spectrum Visualizer Demo](https://godotengine.org/asset-library/asset/2762) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[autoplay](#class_AudioStreamPlayer_property_autoplay)`false`
[StringName](class_stringname.md)[bus](#class_AudioStreamPlayer_property_bus)`&"Master"`
[int](class_int.md)[max_polyphony](#class_AudioStreamPlayer_property_max_polyphony)`1`
[MixTarget](class_audiostreamplayer.md#enum_AudioStreamPlayer_MixTarget)[mix_target](#class_AudioStreamPlayer_property_mix_target)`0`
[float](class_float.md)[pitch_scale](#class_AudioStreamPlayer_property_pitch_scale)`1.0`
[PlaybackType](class_audioserver.md#enum_AudioServer_PlaybackType)[playback_type](#class_AudioStreamPlayer_property_playback_type)`0`
[bool](class_bool.md)[playing](#class_AudioStreamPlayer_property_playing)`false`
[AudioStream](class_audiostream.md)[stream](#class_AudioStreamPlayer_property_stream)
[bool](class_bool.md)[stream_paused](#class_AudioStreamPlayer_property_stream_paused)`false`
[float](class_float.md)[volume_db](#class_AudioStreamPlayer_property_volume_db)`0.0`
[float](class_float.md)[volume_linear](#class_AudioStreamPlayer_property_volume_linear)
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[get_playback_position](#class_AudioStreamPlayer_method_get_playback_position)\ (\ )
[AudioStreamPlayback](class_audiostreamplayback.md)[get_stream_playback](#class_AudioStreamPlayer_method_get_stream_playback)\ (\ )
[bool](class_bool.md)[has_stream_playback](#class_AudioStreamPlayer_method_has_stream_playback)\ (\ )
`void`[play](#class_AudioStreamPlayer_method_play)\ (\ from_position\: [float](class_float.md) = 0.0\ )
`void`[seek](#class_AudioStreamPlayer_method_seek)\ (\ to_position\: [float](class_float.md)\ )
`void`[stop](#class_AudioStreamPlayer_method_stop)\ (\ )
+ +
+ + + +## Signals + + + + + +**finished**\ (\ ) [🔗](#class_AudioStreamPlayer_signal_finished) + +Emitted when a sound finishes playing without interruptions. This signal is *not* emitted when calling [stop()](class_audiostreamplayer.md#class_AudioStreamPlayer_method_stop), or when exiting the tree while sounds are playing. + +
+ + + +## Enumerations + + + + + +enum **MixTarget**: [🔗](#enum_AudioStreamPlayer_MixTarget) + + + + + +[MixTarget](class_audiostreamplayer.md#enum_AudioStreamPlayer_MixTarget) **MIX_TARGET_STEREO** = `0` + +The audio will be played only on the first channel. This is the default. + + + +[MixTarget](class_audiostreamplayer.md#enum_AudioStreamPlayer_MixTarget) **MIX_TARGET_SURROUND** = `1` + +The audio will be played on all surround channels. + + + +[MixTarget](class_audiostreamplayer.md#enum_AudioStreamPlayer_MixTarget) **MIX_TARGET_CENTER** = `2` + +The audio will be played on the second channel, which is usually the center.
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **autoplay** = `false` [🔗](#class_AudioStreamPlayer_property_autoplay) + + + +- `void` **set_autoplay**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_autoplay_enabled**\ (\ ) + +If ``true``, this node calls [play()](class_audiostreamplayer.md#class_AudioStreamPlayer_method_play) when entering the tree. + +
+ + + + + +[StringName](class_stringname.md) **bus** = `&"Master"` [🔗](#class_AudioStreamPlayer_property_bus) + + + +- `void` **set_bus**\ (\ value\: [StringName](class_stringname.md)\ ) +- [StringName](class_stringname.md) **get_bus**\ (\ ) + +The target bus name. All sounds from this node will be playing on this bus. + +\ **Note:** At runtime, if no bus with the given name exists, all sounds will fall back on ``"Master"``. See also [AudioServer.get_bus_name()](class_audioserver.md#class_AudioServer_method_get_bus_name). + +
+ + + + + +[int](class_int.md) **max_polyphony** = `1` [🔗](#class_AudioStreamPlayer_property_max_polyphony) + + + +- `void` **set_max_polyphony**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_max_polyphony**\ (\ ) + +The maximum number of sounds this node can play at the same time. Calling [play()](class_audiostreamplayer.md#class_AudioStreamPlayer_method_play) after this value is reached will cut off the oldest sounds. + +
+ + + + + +[MixTarget](class_audiostreamplayer.md#enum_AudioStreamPlayer_MixTarget) **mix_target** = `0` [🔗](#class_AudioStreamPlayer_property_mix_target) + + + +- `void` **set_mix_target**\ (\ value\: [MixTarget](class_audiostreamplayer.md#enum_AudioStreamPlayer_MixTarget)\ ) +- [MixTarget](class_audiostreamplayer.md#enum_AudioStreamPlayer_MixTarget) **get_mix_target**\ (\ ) + +The mix target channels. Has no effect when two speakers or less are detected (see [SpeakerMode](class_audioserver.md#enum_AudioServer_SpeakerMode)). + +
+ + + + + +[float](class_float.md) **pitch_scale** = `1.0` [🔗](#class_AudioStreamPlayer_property_pitch_scale) + + + +- `void` **set_pitch_scale**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_pitch_scale**\ (\ ) + +The audio's pitch and tempo, as a multiplier of the [stream](class_audiostreamplayer.md#class_AudioStreamPlayer_property_stream)'s sample rate. A value of ``2.0`` doubles the audio's pitch, while a value of ``0.5`` halves the pitch. + +
+ + + + + +[PlaybackType](class_audioserver.md#enum_AudioServer_PlaybackType) **playback_type** = `0` [🔗](#class_AudioStreamPlayer_property_playback_type) + + + +- `void` **set_playback_type**\ (\ value\: [PlaybackType](class_audioserver.md#enum_AudioServer_PlaybackType)\ ) +- [PlaybackType](class_audioserver.md#enum_AudioServer_PlaybackType) **get_playback_type**\ (\ ) + +**Experimental:** This property may be changed or removed in future versions. + +The playback type of the stream player. If set other than to the default value, it will force that playback type. + +
+ + + + + +[bool](class_bool.md) **playing** = `false` [🔗](#class_AudioStreamPlayer_property_playing) + + + +- `void` **set_playing**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_playing**\ (\ ) + +If ``true``, this node is playing sounds. Setting this property has the same effect as [play()](class_audiostreamplayer.md#class_AudioStreamPlayer_method_play) and [stop()](class_audiostreamplayer.md#class_AudioStreamPlayer_method_stop). + +
+ + + + + +[AudioStream](class_audiostream.md) **stream** [🔗](#class_AudioStreamPlayer_property_stream) + + + +- `void` **set_stream**\ (\ value\: [AudioStream](class_audiostream.md)\ ) +- [AudioStream](class_audiostream.md) **get_stream**\ (\ ) + +The [AudioStream](class_audiostream.md) resource to be played. Setting this property stops all currently playing sounds. If left empty, the **AudioStreamPlayer** does not work. + +
+ + + + + +[bool](class_bool.md) **stream_paused** = `false` [🔗](#class_AudioStreamPlayer_property_stream_paused) + + + +- `void` **set_stream_paused**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_stream_paused**\ (\ ) + +If ``true``, the sounds are paused. Setting [stream_paused](class_audiostreamplayer.md#class_AudioStreamPlayer_property_stream_paused) to ``false`` resumes all sounds. + +\ **Note:** This property is automatically changed when exiting or entering the tree, or this node is paused (see [Node.process_mode](class_node.md#class_Node_property_process_mode)). + +
+ + + + + +[float](class_float.md) **volume_db** = `0.0` [🔗](#class_AudioStreamPlayer_property_volume_db) + + + +- `void` **set_volume_db**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_volume_db**\ (\ ) + +Volume of sound, in decibels. This is an offset of the [stream](class_audiostreamplayer.md#class_AudioStreamPlayer_property_stream)'s volume. + +\ **Note:** To convert between decibel and linear energy (like most volume sliders do), use [volume_linear](class_audiostreamplayer.md#class_AudioStreamPlayer_property_volume_linear), or [@GlobalScope.db_to_linear()](class_@globalscope.md#class_@GlobalScope_method_db_to_linear) and [@GlobalScope.linear_to_db()](class_@globalscope.md#class_@GlobalScope_method_linear_to_db). + +
+ + + + + +[float](class_float.md) **volume_linear** [🔗](#class_AudioStreamPlayer_property_volume_linear) + + + +- `void` **set_volume_linear**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_volume_linear**\ (\ ) + +Volume of sound, as a linear value. + +\ **Note:** This member modifies [volume_db](class_audiostreamplayer.md#class_AudioStreamPlayer_property_volume_db) for convenience. The returned value is equivalent to the result of [@GlobalScope.db_to_linear()](class_@globalscope.md#class_@GlobalScope_method_db_to_linear) on [volume_db](class_audiostreamplayer.md#class_AudioStreamPlayer_property_volume_db). Setting this member is equivalent to setting [volume_db](class_audiostreamplayer.md#class_AudioStreamPlayer_property_volume_db) to the result of [@GlobalScope.linear_to_db()](class_@globalscope.md#class_@GlobalScope_method_linear_to_db) on a value. + +
+ + + +## Method Descriptions + + + + + +[float](class_float.md) **get_playback_position**\ (\ ) [🔗](#class_AudioStreamPlayer_method_get_playback_position) + +Returns the position in the [AudioStream](class_audiostream.md) of the latest sound, in seconds. Returns ``0.0`` if no sounds are playing. + +\ **Note:** The position is not always accurate, as the [AudioServer](class_audioserver.md) does not mix audio every processed frame. To get more accurate results, add [AudioServer.get_time_since_last_mix()](class_audioserver.md#class_AudioServer_method_get_time_since_last_mix) to the returned position. + +\ **Note:** This method always returns ``0.0`` if the [stream](class_audiostreamplayer.md#class_AudioStreamPlayer_property_stream) is an [AudioStreamInteractive](class_audiostreaminteractive.md), since it can have multiple clips playing at once. + +
+ + + + + +[AudioStreamPlayback](class_audiostreamplayback.md) **get_stream_playback**\ (\ ) [🔗](#class_AudioStreamPlayer_method_get_stream_playback) + +Returns the latest [AudioStreamPlayback](class_audiostreamplayback.md) of this node, usually the most recently created by [play()](class_audiostreamplayer.md#class_AudioStreamPlayer_method_play). If no sounds are playing, this method fails and returns an empty playback. + +
+ + + + + +[bool](class_bool.md) **has_stream_playback**\ (\ ) [🔗](#class_AudioStreamPlayer_method_has_stream_playback) + +Returns ``true`` if any sound is active, even if [stream_paused](class_audiostreamplayer.md#class_AudioStreamPlayer_property_stream_paused) is set to ``true``. See also [playing](class_audiostreamplayer.md#class_AudioStreamPlayer_property_playing) and [get_stream_playback()](class_audiostreamplayer.md#class_AudioStreamPlayer_method_get_stream_playback). + +
+ + + + + +`void` **play**\ (\ from_position\: [float](class_float.md) = 0.0\ ) [🔗](#class_AudioStreamPlayer_method_play) + +Plays a sound from the beginning, or the given `from_position` in seconds. + +
+ + + + + +`void` **seek**\ (\ to_position\: [float](class_float.md)\ ) [🔗](#class_AudioStreamPlayer_method_seek) + +Restarts all sounds to be played from the given `to_position`, in seconds. Does nothing if no sounds are playing. + +
+ + + + + +`void` **stop**\ (\ ) [🔗](#class_AudioStreamPlayer_method_stop) + +Stops all sounds from this node. + diff --git a/docs/Classes/class_audiostreamplayer2d.md b/docs/Classes/class_audiostreamplayer2d.md new file mode 100644 index 00000000..d3f2c2bc --- /dev/null +++ b/docs/Classes/class_audiostreamplayer2d.md @@ -0,0 +1,449 @@ + + + + + + + + + + + +# AudioStreamPlayer2D + +**Inherits:** [Node2D](class_node2d.md) **<** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +Plays positional sound in 2D space. + + + +## 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](class_audiolistener2d.md) node to the scene and enabling it by calling [AudioListener2D.make_current()](class_audiolistener2d.md#class_AudioListener2D_method_make_current) on it. + +See also [AudioStreamPlayer](class_audiostreamplayer.md) to play a sound non-positionally. + +\ **Note:** Hiding an **AudioStreamPlayer2D** node does not disable its audio output. To temporarily disable an **AudioStreamPlayer2D**'s audio output, set [volume_db](class_audiostreamplayer2d.md#class_AudioStreamPlayer2D_property_volume_db) to a very low value like ``-100`` (which isn't audible to human hearing). + + + +## Tutorials + +- [Audio streams](../tutorials/audio/audio_streams.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[int](class_int.md)[area_mask](#class_AudioStreamPlayer2D_property_area_mask)`1`
[float](class_float.md)[attenuation](#class_AudioStreamPlayer2D_property_attenuation)`1.0`
[bool](class_bool.md)[autoplay](#class_AudioStreamPlayer2D_property_autoplay)`false`
[StringName](class_stringname.md)[bus](#class_AudioStreamPlayer2D_property_bus)`&"Master"`
[float](class_float.md)[max_distance](#class_AudioStreamPlayer2D_property_max_distance)`2000.0`
[int](class_int.md)[max_polyphony](#class_AudioStreamPlayer2D_property_max_polyphony)`1`
[float](class_float.md)[panning_strength](#class_AudioStreamPlayer2D_property_panning_strength)`1.0`
[float](class_float.md)[pitch_scale](#class_AudioStreamPlayer2D_property_pitch_scale)`1.0`
[PlaybackType](class_audioserver.md#enum_AudioServer_PlaybackType)[playback_type](#class_AudioStreamPlayer2D_property_playback_type)`0`
[bool](class_bool.md)[playing](#class_AudioStreamPlayer2D_property_playing)`false`
[AudioStream](class_audiostream.md)[stream](#class_AudioStreamPlayer2D_property_stream)
[bool](class_bool.md)[stream_paused](#class_AudioStreamPlayer2D_property_stream_paused)`false`
[float](class_float.md)[volume_db](#class_AudioStreamPlayer2D_property_volume_db)`0.0`
[float](class_float.md)[volume_linear](#class_AudioStreamPlayer2D_property_volume_linear)
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[get_playback_position](#class_AudioStreamPlayer2D_method_get_playback_position)\ (\ )
[AudioStreamPlayback](class_audiostreamplayback.md)[get_stream_playback](#class_AudioStreamPlayer2D_method_get_stream_playback)\ (\ )
[bool](class_bool.md)[has_stream_playback](#class_AudioStreamPlayer2D_method_has_stream_playback)\ (\ )
`void`[play](#class_AudioStreamPlayer2D_method_play)\ (\ from_position\: [float](class_float.md) = 0.0\ )
`void`[seek](#class_AudioStreamPlayer2D_method_seek)\ (\ to_position\: [float](class_float.md)\ )
`void`[stop](#class_AudioStreamPlayer2D_method_stop)\ (\ )
+ +
+ + + +## Signals + + + + + +**finished**\ (\ ) [🔗](#class_AudioStreamPlayer2D_signal_finished) + +Emitted when the audio stops playing. + +
+ + + +## Property Descriptions + + + + + +[int](class_int.md) **area_mask** = `1` [🔗](#class_AudioStreamPlayer2D_property_area_mask) + + + +- `void` **set_area_mask**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_area_mask**\ (\ ) + +Determines which [Area2D](class_area2d.md) layers affect the sound for reverb and audio bus effects. Areas can be used to redirect [AudioStream](class_audiostream.md)\ 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. + +
+ + + + + +[float](class_float.md) **attenuation** = `1.0` [🔗](#class_AudioStreamPlayer2D_property_attenuation) + + + +- `void` **set_attenuation**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_attenuation**\ (\ ) + +The volume is attenuated over distance with this as an exponent. + +
+ + + + + +[bool](class_bool.md) **autoplay** = `false` [🔗](#class_AudioStreamPlayer2D_property_autoplay) + + + +- `void` **set_autoplay**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_autoplay_enabled**\ (\ ) + +If ``true``, audio plays when added to scene tree. + +
+ + + + + +[StringName](class_stringname.md) **bus** = `&"Master"` [🔗](#class_AudioStreamPlayer2D_property_bus) + + + +- `void` **set_bus**\ (\ value\: [StringName](class_stringname.md)\ ) +- [StringName](class_stringname.md) **get_bus**\ (\ ) + +Bus on which this audio is playing. + +\ **Note:** 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 ``"Master"``. + +
+ + + + + +[float](class_float.md) **max_distance** = `2000.0` [🔗](#class_AudioStreamPlayer2D_property_max_distance) + + + +- `void` **set_max_distance**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_max_distance**\ (\ ) + +Maximum distance from which audio is still hearable. + +
+ + + + + +[int](class_int.md) **max_polyphony** = `1` [🔗](#class_AudioStreamPlayer2D_property_max_polyphony) + + + +- `void` **set_max_polyphony**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_max_polyphony**\ (\ ) + +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. + +
+ + + + + +[float](class_float.md) **panning_strength** = `1.0` [🔗](#class_AudioStreamPlayer2D_property_panning_strength) + + + +- `void` **set_panning_strength**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_panning_strength**\ (\ ) + +Scales the panning strength for this node by multiplying the base [ProjectSettings.audio/general/2d_panning_strength](class_projectsettings.md#class_ProjectSettings_property_audio/general/2d_panning_strength) with this factor. Higher values will pan audio from left to right more dramatically than lower values. + +
+ + + + + +[float](class_float.md) **pitch_scale** = `1.0` [🔗](#class_AudioStreamPlayer2D_property_pitch_scale) + + + +- `void` **set_pitch_scale**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_pitch_scale**\ (\ ) + +The pitch and the tempo of the audio, as a multiplier of the audio sample's sample rate. + +
+ + + + + +[PlaybackType](class_audioserver.md#enum_AudioServer_PlaybackType) **playback_type** = `0` [🔗](#class_AudioStreamPlayer2D_property_playback_type) + + + +- `void` **set_playback_type**\ (\ value\: [PlaybackType](class_audioserver.md#enum_AudioServer_PlaybackType)\ ) +- [PlaybackType](class_audioserver.md#enum_AudioServer_PlaybackType) **get_playback_type**\ (\ ) + +**Experimental:** This property may be changed or removed in future versions. + +The playback type of the stream player. If set other than to the default value, it will force that playback type. + +
+ + + + + +[bool](class_bool.md) **playing** = `false` [🔗](#class_AudioStreamPlayer2D_property_playing) + + + +- `void` **set_playing**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_playing**\ (\ ) + +If ``true``, audio is playing or is queued to be played (see [play()](class_audiostreamplayer2d.md#class_AudioStreamPlayer2D_method_play)). + +
+ + + + + +[AudioStream](class_audiostream.md) **stream** [🔗](#class_AudioStreamPlayer2D_property_stream) + + + +- `void` **set_stream**\ (\ value\: [AudioStream](class_audiostream.md)\ ) +- [AudioStream](class_audiostream.md) **get_stream**\ (\ ) + +The [AudioStream](class_audiostream.md) object to be played. + +
+ + + + + +[bool](class_bool.md) **stream_paused** = `false` [🔗](#class_AudioStreamPlayer2D_property_stream_paused) + + + +- `void` **set_stream_paused**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_stream_paused**\ (\ ) + +If ``true``, the playback is paused. You can resume it by setting [stream_paused](class_audiostreamplayer2d.md#class_AudioStreamPlayer2D_property_stream_paused) to ``false``. + +
+ + + + + +[float](class_float.md) **volume_db** = `0.0` [🔗](#class_AudioStreamPlayer2D_property_volume_db) + + + +- `void` **set_volume_db**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_volume_db**\ (\ ) + +Base volume before attenuation, in decibels. + +
+ + + + + +[float](class_float.md) **volume_linear** [🔗](#class_AudioStreamPlayer2D_property_volume_linear) + + + +- `void` **set_volume_linear**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_volume_linear**\ (\ ) + +Base volume before attenuation, as a linear value. + +\ **Note:** This member modifies [volume_db](class_audiostreamplayer2d.md#class_AudioStreamPlayer2D_property_volume_db) for convenience. The returned value is equivalent to the result of [@GlobalScope.db_to_linear()](class_@globalscope.md#class_@GlobalScope_method_db_to_linear) on [volume_db](class_audiostreamplayer2d.md#class_AudioStreamPlayer2D_property_volume_db). Setting this member is equivalent to setting [volume_db](class_audiostreamplayer2d.md#class_AudioStreamPlayer2D_property_volume_db) to the result of [@GlobalScope.linear_to_db()](class_@globalscope.md#class_@GlobalScope_method_linear_to_db) on a value. + +
+ + + +## Method Descriptions + + + + + +[float](class_float.md) **get_playback_position**\ (\ ) [🔗](#class_AudioStreamPlayer2D_method_get_playback_position) + +Returns the position in the [AudioStream](class_audiostream.md). + +
+ + + + + +[AudioStreamPlayback](class_audiostreamplayback.md) **get_stream_playback**\ (\ ) [🔗](#class_AudioStreamPlayer2D_method_get_stream_playback) + +Returns the [AudioStreamPlayback](class_audiostreamplayback.md) object associated with this **AudioStreamPlayer2D**. + +
+ + + + + +[bool](class_bool.md) **has_stream_playback**\ (\ ) [🔗](#class_AudioStreamPlayer2D_method_has_stream_playback) + +Returns whether the [AudioStreamPlayer](class_audiostreamplayer.md) can return the [AudioStreamPlayback](class_audiostreamplayback.md) object or not. + +
+ + + + + +`void` **play**\ (\ from_position\: [float](class_float.md) = 0.0\ ) [🔗](#class_AudioStreamPlayer2D_method_play) + +Queues the audio to play on the next physics frame, from the given position `from_position`, in seconds. + +
+ + + + + +`void` **seek**\ (\ to_position\: [float](class_float.md)\ ) [🔗](#class_AudioStreamPlayer2D_method_seek) + +Sets the position from which audio will be played, in seconds. + +
+ + + + + +`void` **stop**\ (\ ) [🔗](#class_AudioStreamPlayer2D_method_stop) + +Stops the audio. + diff --git a/docs/Classes/class_audiostreamplayer3d.md b/docs/Classes/class_audiostreamplayer3d.md new file mode 100644 index 00000000..d5d3c61a --- /dev/null +++ b/docs/Classes/class_audiostreamplayer3d.md @@ -0,0 +1,677 @@ + + + + + + + + + + + +# AudioStreamPlayer3D + +**Inherits:** [Node3D](class_node3d.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +Plays positional sound in 3D space. + + + +## 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 [attenuation_filter_cutoff_hz](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_property_attenuation_filter_cutoff_hz) to ``20500``. + +By default, audio is heard from the camera position. This can be changed by adding an [AudioListener3D](class_audiolistener3d.md) node to the scene and enabling it by calling [AudioListener3D.make_current()](class_audiolistener3d.md#class_AudioListener3D_method_make_current) on it. + +See also [AudioStreamPlayer](class_audiostreamplayer.md) to play a sound non-positionally. + +\ **Note:** Hiding an **AudioStreamPlayer3D** node does not disable its audio output. To temporarily disable an **AudioStreamPlayer3D**'s audio output, set [volume_db](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_property_volume_db) to a very low value like ``-100`` (which isn't audible to human hearing). + + + +## Tutorials + +- [Audio streams](../tutorials/audio/audio_streams.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[int](class_int.md)[area_mask](#class_AudioStreamPlayer3D_property_area_mask)`1`
[float](class_float.md)[attenuation_filter_cutoff_hz](#class_AudioStreamPlayer3D_property_attenuation_filter_cutoff_hz)`5000.0`
[float](class_float.md)[attenuation_filter_db](#class_AudioStreamPlayer3D_property_attenuation_filter_db)`-24.0`
[AttenuationModel](class_audiostreamplayer3d.md#enum_AudioStreamPlayer3D_AttenuationModel)[attenuation_model](#class_AudioStreamPlayer3D_property_attenuation_model)`0`
[bool](class_bool.md)[autoplay](#class_AudioStreamPlayer3D_property_autoplay)`false`
[StringName](class_stringname.md)[bus](#class_AudioStreamPlayer3D_property_bus)`&"Master"`
[DopplerTracking](class_audiostreamplayer3d.md#enum_AudioStreamPlayer3D_DopplerTracking)[doppler_tracking](#class_AudioStreamPlayer3D_property_doppler_tracking)`0`
[float](class_float.md)[emission_angle_degrees](#class_AudioStreamPlayer3D_property_emission_angle_degrees)`45.0`
[bool](class_bool.md)[emission_angle_enabled](#class_AudioStreamPlayer3D_property_emission_angle_enabled)`false`
[float](class_float.md)[emission_angle_filter_attenuation_db](#class_AudioStreamPlayer3D_property_emission_angle_filter_attenuation_db)`-12.0`
[float](class_float.md)[max_db](#class_AudioStreamPlayer3D_property_max_db)`3.0`
[float](class_float.md)[max_distance](#class_AudioStreamPlayer3D_property_max_distance)`0.0`
[int](class_int.md)[max_polyphony](#class_AudioStreamPlayer3D_property_max_polyphony)`1`
[float](class_float.md)[panning_strength](#class_AudioStreamPlayer3D_property_panning_strength)`1.0`
[float](class_float.md)[pitch_scale](#class_AudioStreamPlayer3D_property_pitch_scale)`1.0`
[PlaybackType](class_audioserver.md#enum_AudioServer_PlaybackType)[playback_type](#class_AudioStreamPlayer3D_property_playback_type)`0`
[bool](class_bool.md)[playing](#class_AudioStreamPlayer3D_property_playing)`false`
[AudioStream](class_audiostream.md)[stream](#class_AudioStreamPlayer3D_property_stream)
[bool](class_bool.md)[stream_paused](#class_AudioStreamPlayer3D_property_stream_paused)`false`
[float](class_float.md)[unit_size](#class_AudioStreamPlayer3D_property_unit_size)`10.0`
[float](class_float.md)[volume_db](#class_AudioStreamPlayer3D_property_volume_db)`0.0`
[float](class_float.md)[volume_linear](#class_AudioStreamPlayer3D_property_volume_linear)
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[get_playback_position](#class_AudioStreamPlayer3D_method_get_playback_position)\ (\ )
[AudioStreamPlayback](class_audiostreamplayback.md)[get_stream_playback](#class_AudioStreamPlayer3D_method_get_stream_playback)\ (\ )
[bool](class_bool.md)[has_stream_playback](#class_AudioStreamPlayer3D_method_has_stream_playback)\ (\ )
`void`[play](#class_AudioStreamPlayer3D_method_play)\ (\ from_position\: [float](class_float.md) = 0.0\ )
`void`[seek](#class_AudioStreamPlayer3D_method_seek)\ (\ to_position\: [float](class_float.md)\ )
`void`[stop](#class_AudioStreamPlayer3D_method_stop)\ (\ )
+ +
+ + + +## Signals + + + + + +**finished**\ (\ ) [🔗](#class_AudioStreamPlayer3D_signal_finished) + +Emitted when the audio stops playing. + +
+ + + +## Enumerations + + + + + +enum **AttenuationModel**: [🔗](#enum_AudioStreamPlayer3D_AttenuationModel) + + + + + +[AttenuationModel](class_audiostreamplayer3d.md#enum_AudioStreamPlayer3D_AttenuationModel) **ATTENUATION_INVERSE_DISTANCE** = `0` + +Attenuation of loudness according to linear distance. + + + +[AttenuationModel](class_audiostreamplayer3d.md#enum_AudioStreamPlayer3D_AttenuationModel) **ATTENUATION_INVERSE_SQUARE_DISTANCE** = `1` + +Attenuation of loudness according to squared distance. + + + +[AttenuationModel](class_audiostreamplayer3d.md#enum_AudioStreamPlayer3D_AttenuationModel) **ATTENUATION_LOGARITHMIC** = `2` + +Attenuation of loudness according to logarithmic distance. + + + +[AttenuationModel](class_audiostreamplayer3d.md#enum_AudioStreamPlayer3D_AttenuationModel) **ATTENUATION_DISABLED** = `3` + +No attenuation of loudness according to distance. The sound will still be heard positionally, unlike an [AudioStreamPlayer](class_audiostreamplayer.md). [ATTENUATION_DISABLED](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_constant_ATTENUATION_DISABLED) can be combined with a [max_distance](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_property_max_distance) value greater than ``0.0`` to achieve linear attenuation clamped to a sphere of a defined size.
+ + + + + +enum **DopplerTracking**: [🔗](#enum_AudioStreamPlayer3D_DopplerTracking) + + + + + +[DopplerTracking](class_audiostreamplayer3d.md#enum_AudioStreamPlayer3D_DopplerTracking) **DOPPLER_TRACKING_DISABLED** = `0` + +Disables doppler tracking. + + + +[DopplerTracking](class_audiostreamplayer3d.md#enum_AudioStreamPlayer3D_DopplerTracking) **DOPPLER_TRACKING_IDLE_STEP** = `1` + +Executes doppler tracking during process frames (see [Node.NOTIFICATION_INTERNAL_PROCESS](class_node.md#class_Node_constant_NOTIFICATION_INTERNAL_PROCESS)). + + + +[DopplerTracking](class_audiostreamplayer3d.md#enum_AudioStreamPlayer3D_DopplerTracking) **DOPPLER_TRACKING_PHYSICS_STEP** = `2` + +Executes doppler tracking during physics frames (see [Node.NOTIFICATION_INTERNAL_PHYSICS_PROCESS](class_node.md#class_Node_constant_NOTIFICATION_INTERNAL_PHYSICS_PROCESS)).
+ + + +## Property Descriptions + + + + + +[int](class_int.md) **area_mask** = `1` [🔗](#class_AudioStreamPlayer3D_property_area_mask) + + + +- `void` **set_area_mask**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_area_mask**\ (\ ) + +Determines which [Area3D](class_area3d.md) layers affect the sound for reverb and audio bus effects. Areas can be used to redirect [AudioStream](class_audiostream.md)\ 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. + +
+ + + + + +[float](class_float.md) **attenuation_filter_cutoff_hz** = `5000.0` [🔗](#class_AudioStreamPlayer3D_property_attenuation_filter_cutoff_hz) + + + +- `void` **set_attenuation_filter_cutoff_hz**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_attenuation_filter_cutoff_hz**\ (\ ) + +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 ``20500`` as this frequency is above the human hearing limit. + +
+ + + + + +[float](class_float.md) **attenuation_filter_db** = `-24.0` [🔗](#class_AudioStreamPlayer3D_property_attenuation_filter_db) + + + +- `void` **set_attenuation_filter_db**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_attenuation_filter_db**\ (\ ) + +Amount how much the filter affects the loudness, in decibels. + +
+ + + + + +[AttenuationModel](class_audiostreamplayer3d.md#enum_AudioStreamPlayer3D_AttenuationModel) **attenuation_model** = `0` [🔗](#class_AudioStreamPlayer3D_property_attenuation_model) + + + +- `void` **set_attenuation_model**\ (\ value\: [AttenuationModel](class_audiostreamplayer3d.md#enum_AudioStreamPlayer3D_AttenuationModel)\ ) +- [AttenuationModel](class_audiostreamplayer3d.md#enum_AudioStreamPlayer3D_AttenuationModel) **get_attenuation_model**\ (\ ) + +Decides if audio should get quieter with distance linearly, quadratically, logarithmically, or not be affected by distance, effectively disabling attenuation. + +
+ + + + + +[bool](class_bool.md) **autoplay** = `false` [🔗](#class_AudioStreamPlayer3D_property_autoplay) + + + +- `void` **set_autoplay**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_autoplay_enabled**\ (\ ) + +If ``true``, audio plays when the AudioStreamPlayer3D node is added to scene tree. + +
+ + + + + +[StringName](class_stringname.md) **bus** = `&"Master"` [🔗](#class_AudioStreamPlayer3D_property_bus) + + + +- `void` **set_bus**\ (\ value\: [StringName](class_stringname.md)\ ) +- [StringName](class_stringname.md) **get_bus**\ (\ ) + +The bus on which this audio is playing. + +\ **Note:** 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 ``"Master"``. + +
+ + + + + +[DopplerTracking](class_audiostreamplayer3d.md#enum_AudioStreamPlayer3D_DopplerTracking) **doppler_tracking** = `0` [🔗](#class_AudioStreamPlayer3D_property_doppler_tracking) + + + +- `void` **set_doppler_tracking**\ (\ value\: [DopplerTracking](class_audiostreamplayer3d.md#enum_AudioStreamPlayer3D_DopplerTracking)\ ) +- [DopplerTracking](class_audiostreamplayer3d.md#enum_AudioStreamPlayer3D_DopplerTracking) **get_doppler_tracking**\ (\ ) + +Decides in which step the Doppler effect should be calculated. + +\ **Note:** If [doppler_tracking](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_property_doppler_tracking) is not [DOPPLER_TRACKING_DISABLED](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_constant_DOPPLER_TRACKING_DISABLED) but the current [Camera3D](class_camera3d.md)/[AudioListener3D](class_audiolistener3d.md) 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](class_camera3d.md)/[AudioListener3D](class_audiolistener3d.md). + +
+ + + + + +[float](class_float.md) **emission_angle_degrees** = `45.0` [🔗](#class_AudioStreamPlayer3D_property_emission_angle_degrees) + + + +- `void` **set_emission_angle**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_emission_angle**\ (\ ) + +The angle in which the audio reaches a listener unattenuated. + +
+ + + + + +[bool](class_bool.md) **emission_angle_enabled** = `false` [🔗](#class_AudioStreamPlayer3D_property_emission_angle_enabled) + + + +- `void` **set_emission_angle_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_emission_angle_enabled**\ (\ ) + +If ``true``, the audio should be attenuated according to the direction of the sound. + +
+ + + + + +[float](class_float.md) **emission_angle_filter_attenuation_db** = `-12.0` [🔗](#class_AudioStreamPlayer3D_property_emission_angle_filter_attenuation_db) + + + +- `void` **set_emission_angle_filter_attenuation_db**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_emission_angle_filter_attenuation_db**\ (\ ) + +Attenuation factor used if listener is outside of [emission_angle_degrees](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_property_emission_angle_degrees) and [emission_angle_enabled](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_property_emission_angle_enabled) is set, in decibels. + +
+ + + + + +[float](class_float.md) **max_db** = `3.0` [🔗](#class_AudioStreamPlayer3D_property_max_db) + + + +- `void` **set_max_db**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_max_db**\ (\ ) + +Sets the absolute maximum of the sound level, in decibels. + +
+ + + + + +[float](class_float.md) **max_distance** = `0.0` [🔗](#class_AudioStreamPlayer3D_property_max_distance) + + + +- `void` **set_max_distance**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_max_distance**\ (\ ) + +The distance past which the sound can no longer be heard at all. Only has an effect if set to a value greater than ``0.0``. [max_distance](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_property_max_distance) works in tandem with [unit_size](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_property_unit_size). However, unlike [unit_size](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_property_unit_size) whose behavior depends on the [attenuation_model](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_property_attenuation_model), [max_distance](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_property_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. + +
+ + + + + +[int](class_int.md) **max_polyphony** = `1` [🔗](#class_AudioStreamPlayer3D_property_max_polyphony) + + + +- `void` **set_max_polyphony**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_max_polyphony**\ (\ ) + +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. + +
+ + + + + +[float](class_float.md) **panning_strength** = `1.0` [🔗](#class_AudioStreamPlayer3D_property_panning_strength) + + + +- `void` **set_panning_strength**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_panning_strength**\ (\ ) + +Scales the panning strength for this node by multiplying the base [ProjectSettings.audio/general/3d_panning_strength](class_projectsettings.md#class_ProjectSettings_property_audio/general/3d_panning_strength) by this factor. If the product is ``0.0`` then stereo panning is disabled and the volume is the same for all channels. If the product is ``1.0`` 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 [WebAudio standard for StereoPannerNode Panning](https://webaudio.github.io/web-audio-api/#stereopanner-algorithm) 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. + +
+ + + + + +[float](class_float.md) **pitch_scale** = `1.0` [🔗](#class_AudioStreamPlayer3D_property_pitch_scale) + + + +- `void` **set_pitch_scale**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_pitch_scale**\ (\ ) + +The pitch and the tempo of the audio, as a multiplier of the audio sample's sample rate. + +
+ + + + + +[PlaybackType](class_audioserver.md#enum_AudioServer_PlaybackType) **playback_type** = `0` [🔗](#class_AudioStreamPlayer3D_property_playback_type) + + + +- `void` **set_playback_type**\ (\ value\: [PlaybackType](class_audioserver.md#enum_AudioServer_PlaybackType)\ ) +- [PlaybackType](class_audioserver.md#enum_AudioServer_PlaybackType) **get_playback_type**\ (\ ) + +**Experimental:** This property may be changed or removed in future versions. + +The playback type of the stream player. If set other than to the default value, it will force that playback type. + +
+ + + + + +[bool](class_bool.md) **playing** = `false` [🔗](#class_AudioStreamPlayer3D_property_playing) + + + +- `void` **set_playing**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_playing**\ (\ ) + +If ``true``, audio is playing or is queued to be played (see [play()](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_method_play)). + +
+ + + + + +[AudioStream](class_audiostream.md) **stream** [🔗](#class_AudioStreamPlayer3D_property_stream) + + + +- `void` **set_stream**\ (\ value\: [AudioStream](class_audiostream.md)\ ) +- [AudioStream](class_audiostream.md) **get_stream**\ (\ ) + +The [AudioStream](class_audiostream.md) resource to be played. + +
+ + + + + +[bool](class_bool.md) **stream_paused** = `false` [🔗](#class_AudioStreamPlayer3D_property_stream_paused) + + + +- `void` **set_stream_paused**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_stream_paused**\ (\ ) + +If ``true``, the playback is paused. You can resume it by setting [stream_paused](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_property_stream_paused) to ``false``. + +
+ + + + + +[float](class_float.md) **unit_size** = `10.0` [🔗](#class_AudioStreamPlayer3D_property_unit_size) + + + +- `void` **set_unit_size**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_unit_size**\ (\ ) + +The factor for the attenuation effect. Higher values make the sound audible over a larger distance. + +
+ + + + + +[float](class_float.md) **volume_db** = `0.0` [🔗](#class_AudioStreamPlayer3D_property_volume_db) + + + +- `void` **set_volume_db**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_volume_db**\ (\ ) + +The base sound level before attenuation, in decibels. + +
+ + + + + +[float](class_float.md) **volume_linear** [🔗](#class_AudioStreamPlayer3D_property_volume_linear) + + + +- `void` **set_volume_linear**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_volume_linear**\ (\ ) + +The base sound level before attenuation, as a linear value. + +\ **Note:** This member modifies [volume_db](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_property_volume_db) for convenience. The returned value is equivalent to the result of [@GlobalScope.db_to_linear()](class_@globalscope.md#class_@GlobalScope_method_db_to_linear) on [volume_db](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_property_volume_db). Setting this member is equivalent to setting [volume_db](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_property_volume_db) to the result of [@GlobalScope.linear_to_db()](class_@globalscope.md#class_@GlobalScope_method_linear_to_db) on a value. + +
+ + + +## Method Descriptions + + + + + +[float](class_float.md) **get_playback_position**\ (\ ) [🔗](#class_AudioStreamPlayer3D_method_get_playback_position) + +Returns the position in the [AudioStream](class_audiostream.md). + +
+ + + + + +[AudioStreamPlayback](class_audiostreamplayback.md) **get_stream_playback**\ (\ ) [🔗](#class_AudioStreamPlayer3D_method_get_stream_playback) + +Returns the [AudioStreamPlayback](class_audiostreamplayback.md) object associated with this **AudioStreamPlayer3D**. + +
+ + + + + +[bool](class_bool.md) **has_stream_playback**\ (\ ) [🔗](#class_AudioStreamPlayer3D_method_has_stream_playback) + +Returns whether the [AudioStreamPlayer](class_audiostreamplayer.md) can return the [AudioStreamPlayback](class_audiostreamplayback.md) object or not. + +
+ + + + + +`void` **play**\ (\ from_position\: [float](class_float.md) = 0.0\ ) [🔗](#class_AudioStreamPlayer3D_method_play) + +Queues the audio to play on the next physics frame, from the given position `from_position`, in seconds. + +
+ + + + + +`void` **seek**\ (\ to_position\: [float](class_float.md)\ ) [🔗](#class_AudioStreamPlayer3D_method_seek) + +Sets the position from which audio will be played, in seconds. + +
+ + + + + +`void` **stop**\ (\ ) [🔗](#class_AudioStreamPlayer3D_method_stop) + +Stops the audio. + diff --git a/docs/Classes/class_audiostreamplaylist.md b/docs/Classes/class_audiostreamplaylist.md new file mode 100644 index 00000000..5889e421 --- /dev/null +++ b/docs/Classes/class_audiostreamplaylist.md @@ -0,0 +1,181 @@ + + + + + + + + + +# AudioStreamPlaylist + +**Inherits:** [AudioStream](class_audiostream.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +[AudioStream](class_audiostream.md) that includes sub-streams and plays them back like a playlist. + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[fade_time](#class_AudioStreamPlaylist_property_fade_time)`0.3`
[bool](class_bool.md)[loop](#class_AudioStreamPlaylist_property_loop)`true`
[bool](class_bool.md)[shuffle](#class_AudioStreamPlaylist_property_shuffle)`false`
[int](class_int.md)[stream_count](#class_AudioStreamPlaylist_property_stream_count)`0`
+ + + +## Methods + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[get_bpm](#class_AudioStreamPlaylist_method_get_bpm)\ (\ ) const
[AudioStream](class_audiostream.md)[get_list_stream](#class_AudioStreamPlaylist_method_get_list_stream)\ (\ stream_index\: [int](class_int.md)\ ) const
`void`[set_list_stream](#class_AudioStreamPlaylist_method_set_list_stream)\ (\ stream_index\: [int](class_int.md), audio_stream\: [AudioStream](class_audiostream.md)\ )
+ +
+ + + +## Constants + + + + + +**MAX_STREAMS** = `64` [🔗](#class_AudioStreamPlaylist_constant_MAX_STREAMS) + +Maximum amount of streams supported in the playlist. + +
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **fade_time** = `0.3` [🔗](#class_AudioStreamPlaylist_property_fade_time) + + + +- `void` **set_fade_time**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_fade_time**\ (\ ) + +Fade time used when a stream ends, when going to the next one. Streams are expected to have an extra bit of audio after the end to help with fading. + +
+ + + + + +[bool](class_bool.md) **loop** = `true` [🔗](#class_AudioStreamPlaylist_property_loop) + + + +- `void` **set_loop**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **has_loop**\ (\ ) + +If ``true``, the playlist will loop, otherwise the playlist will end when the last stream is finished. + +
+ + + + + +[bool](class_bool.md) **shuffle** = `false` [🔗](#class_AudioStreamPlaylist_property_shuffle) + + + +- `void` **set_shuffle**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_shuffle**\ (\ ) + +If ``true``, the playlist will shuffle each time playback starts and each time it loops. + +
+ + + + + +[int](class_int.md) **stream_count** = `0` [🔗](#class_AudioStreamPlaylist_property_stream_count) + + + +- `void` **set_stream_count**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_stream_count**\ (\ ) + +Amount of streams in the playlist. + +
+ + + +## Method Descriptions + + + + + +[float](class_float.md) **get_bpm**\ (\ ) const [🔗](#class_AudioStreamPlaylist_method_get_bpm) + +Returns the BPM of the playlist, which can vary depending on the clip being played. + +
+ + + + + +[AudioStream](class_audiostream.md) **get_list_stream**\ (\ stream_index\: [int](class_int.md)\ ) const [🔗](#class_AudioStreamPlaylist_method_get_list_stream) + +Returns the stream at playback position index. + +
+ + + + + +`void` **set_list_stream**\ (\ stream_index\: [int](class_int.md), audio_stream\: [AudioStream](class_audiostream.md)\ ) [🔗](#class_AudioStreamPlaylist_method_set_list_stream) + +Sets the stream at playback position index. + diff --git a/docs/Classes/class_audiostreampolyphonic.md b/docs/Classes/class_audiostreampolyphonic.md new file mode 100644 index 00000000..10d7ed6e --- /dev/null +++ b/docs/Classes/class_audiostreampolyphonic.md @@ -0,0 +1,58 @@ + + + + + + + + + +# AudioStreamPolyphonic + +**Inherits:** [AudioStream](class_audiostream.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +AudioStream that lets the user play custom streams at any time from code, simultaneously using a single player. + + + +## 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](class_audiostreamplaybackpolyphonic.md) instance set inside the player, which can be obtained via [AudioStreamPlayer.get_stream_playback()](class_audiostreamplayer.md#class_AudioStreamPlayer_method_get_stream_playback), [AudioStreamPlayer2D.get_stream_playback()](class_audiostreamplayer2d.md#class_AudioStreamPlayer2D_method_get_stream_playback) or [AudioStreamPlayer3D.get_stream_playback()](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_method_get_stream_playback) methods. Obtaining the playback instance is only valid after the ``stream`` property is set as an **AudioStreamPolyphonic** in those players. + + + +## Properties + + + + + + + + + + + +
[int](class_int.md)[polyphony](#class_AudioStreamPolyphonic_property_polyphony)`32`
+ +
+ + + +## Property Descriptions + + + + + +[int](class_int.md) **polyphony** = `32` [🔗](#class_AudioStreamPolyphonic_property_polyphony) + + + +- `void` **set_polyphony**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_polyphony**\ (\ ) + +Maximum amount of simultaneous streams that can be played. + diff --git a/docs/Classes/class_audiostreamrandomizer.md b/docs/Classes/class_audiostreamrandomizer.md new file mode 100644 index 00000000..7adc7c28 --- /dev/null +++ b/docs/Classes/class_audiostreamrandomizer.md @@ -0,0 +1,259 @@ + + + + + + + + + +# AudioStreamRandomizer + +**Inherits:** [AudioStream](class_audiostream.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Wraps a pool of audio streams with pitch and volume shifting. + + + +## Description + +Picks a random AudioStream from the pool, depending on the playback mode, and applies random pitch shifting and volume shifting during playback. + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + +
[PlaybackMode](class_audiostreamrandomizer.md#enum_AudioStreamRandomizer_PlaybackMode)[playback_mode](#class_AudioStreamRandomizer_property_playback_mode)`0`
[float](class_float.md)[random_pitch](#class_AudioStreamRandomizer_property_random_pitch)`1.0`
[float](class_float.md)[random_volume_offset_db](#class_AudioStreamRandomizer_property_random_volume_offset_db)`0.0`
[int](class_int.md)[streams_count](#class_AudioStreamRandomizer_property_streams_count)`0`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
`void`[add_stream](#class_AudioStreamRandomizer_method_add_stream)\ (\ index\: [int](class_int.md), stream\: [AudioStream](class_audiostream.md), weight\: [float](class_float.md) = 1.0\ )
[AudioStream](class_audiostream.md)[get_stream](#class_AudioStreamRandomizer_method_get_stream)\ (\ index\: [int](class_int.md)\ ) const
[float](class_float.md)[get_stream_probability_weight](#class_AudioStreamRandomizer_method_get_stream_probability_weight)\ (\ index\: [int](class_int.md)\ ) const
`void`[move_stream](#class_AudioStreamRandomizer_method_move_stream)\ (\ index_from\: [int](class_int.md), index_to\: [int](class_int.md)\ )
`void`[remove_stream](#class_AudioStreamRandomizer_method_remove_stream)\ (\ index\: [int](class_int.md)\ )
`void`[set_stream](#class_AudioStreamRandomizer_method_set_stream)\ (\ index\: [int](class_int.md), stream\: [AudioStream](class_audiostream.md)\ )
`void`[set_stream_probability_weight](#class_AudioStreamRandomizer_method_set_stream_probability_weight)\ (\ index\: [int](class_int.md), weight\: [float](class_float.md)\ )
+ +
+ + + +## Enumerations + + + + + +enum **PlaybackMode**: [🔗](#enum_AudioStreamRandomizer_PlaybackMode) + + + + + +[PlaybackMode](class_audiostreamrandomizer.md#enum_AudioStreamRandomizer_PlaybackMode) **PLAYBACK_RANDOM_NO_REPEATS** = `0` + +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. + + + +[PlaybackMode](class_audiostreamrandomizer.md#enum_AudioStreamRandomizer_PlaybackMode) **PLAYBACK_RANDOM** = `1` + +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. + + + +[PlaybackMode](class_audiostreamrandomizer.md#enum_AudioStreamRandomizer_PlaybackMode) **PLAYBACK_SEQUENTIAL** = `2` + +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.
+ + + +## Property Descriptions + + + + + +[PlaybackMode](class_audiostreamrandomizer.md#enum_AudioStreamRandomizer_PlaybackMode) **playback_mode** = `0` [🔗](#class_AudioStreamRandomizer_property_playback_mode) + + + +- `void` **set_playback_mode**\ (\ value\: [PlaybackMode](class_audiostreamrandomizer.md#enum_AudioStreamRandomizer_PlaybackMode)\ ) +- [PlaybackMode](class_audiostreamrandomizer.md#enum_AudioStreamRandomizer_PlaybackMode) **get_playback_mode**\ (\ ) + +Controls how this AudioStreamRandomizer picks which AudioStream to play next. + +
+ + + + + +[float](class_float.md) **random_pitch** = `1.0` [🔗](#class_AudioStreamRandomizer_property_random_pitch) + + + +- `void` **set_random_pitch**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_random_pitch**\ (\ ) + +The intensity of random pitch variation. A value of 1 means no variation. + +
+ + + + + +[float](class_float.md) **random_volume_offset_db** = `0.0` [🔗](#class_AudioStreamRandomizer_property_random_volume_offset_db) + + + +- `void` **set_random_volume_offset_db**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_random_volume_offset_db**\ (\ ) + +The intensity of random volume variation. A value of 0 means no variation. + +
+ + + + + +[int](class_int.md) **streams_count** = `0` [🔗](#class_AudioStreamRandomizer_property_streams_count) + + + +- `void` **set_streams_count**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_streams_count**\ (\ ) + +The number of streams in the stream pool. + +
+ + + +## Method Descriptions + + + + + +`void` **add_stream**\ (\ index\: [int](class_int.md), stream\: [AudioStream](class_audiostream.md), weight\: [float](class_float.md) = 1.0\ ) [🔗](#class_AudioStreamRandomizer_method_add_stream) + +Insert a stream at the specified index. If the index is less than zero, the insertion occurs at the end of the underlying pool. + +
+ + + + + +[AudioStream](class_audiostream.md) **get_stream**\ (\ index\: [int](class_int.md)\ ) const [🔗](#class_AudioStreamRandomizer_method_get_stream) + +Returns the stream at the specified index. + +
+ + + + + +[float](class_float.md) **get_stream_probability_weight**\ (\ index\: [int](class_int.md)\ ) const [🔗](#class_AudioStreamRandomizer_method_get_stream_probability_weight) + +Returns the probability weight associated with the stream at the given index. + +
+ + + + + +`void` **move_stream**\ (\ index_from\: [int](class_int.md), index_to\: [int](class_int.md)\ ) [🔗](#class_AudioStreamRandomizer_method_move_stream) + +Move a stream from one index to another. + +
+ + + + + +`void` **remove_stream**\ (\ index\: [int](class_int.md)\ ) [🔗](#class_AudioStreamRandomizer_method_remove_stream) + +Remove the stream at the specified index. + +
+ + + + + +`void` **set_stream**\ (\ index\: [int](class_int.md), stream\: [AudioStream](class_audiostream.md)\ ) [🔗](#class_AudioStreamRandomizer_method_set_stream) + +Set the AudioStream at the specified index. + +
+ + + + + +`void` **set_stream_probability_weight**\ (\ index\: [int](class_int.md), weight\: [float](class_float.md)\ ) [🔗](#class_AudioStreamRandomizer_method_set_stream_probability_weight) + +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. + diff --git a/docs/Classes/class_audiostreamsynchronized.md b/docs/Classes/class_audiostreamsynchronized.md new file mode 100644 index 00000000..9fe5a2cd --- /dev/null +++ b/docs/Classes/class_audiostreamsynchronized.md @@ -0,0 +1,141 @@ + + + + + + + + + +# AudioStreamSynchronized + +**Inherits:** [AudioStream](class_audiostream.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Stream that can be fitted with sub-streams, which will be played in-sync. + + + +## Description + +This is a stream that can be fitted with sub-streams, which will be played in-sync. The streams begin at exactly the same time when play is pressed, and will end when the last of them ends. If one of the sub-streams loops, then playback will continue. + + + +## Properties + + + + + + + + + + + +
[int](class_int.md)[stream_count](#class_AudioStreamSynchronized_property_stream_count)`0`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + +
[AudioStream](class_audiostream.md)[get_sync_stream](#class_AudioStreamSynchronized_method_get_sync_stream)\ (\ stream_index\: [int](class_int.md)\ ) const
[float](class_float.md)[get_sync_stream_volume](#class_AudioStreamSynchronized_method_get_sync_stream_volume)\ (\ stream_index\: [int](class_int.md)\ ) const
`void`[set_sync_stream](#class_AudioStreamSynchronized_method_set_sync_stream)\ (\ stream_index\: [int](class_int.md), audio_stream\: [AudioStream](class_audiostream.md)\ )
`void`[set_sync_stream_volume](#class_AudioStreamSynchronized_method_set_sync_stream_volume)\ (\ stream_index\: [int](class_int.md), volume_db\: [float](class_float.md)\ )
+ +
+ + + +## Constants + + + + + +**MAX_STREAMS** = `32` [🔗](#class_AudioStreamSynchronized_constant_MAX_STREAMS) + +Maximum amount of streams that can be synchronized. + +
+ + + +## Property Descriptions + + + + + +[int](class_int.md) **stream_count** = `0` [🔗](#class_AudioStreamSynchronized_property_stream_count) + + + +- `void` **set_stream_count**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_stream_count**\ (\ ) + +Set the total amount of streams that will be played back synchronized. + +
+ + + +## Method Descriptions + + + + + +[AudioStream](class_audiostream.md) **get_sync_stream**\ (\ stream_index\: [int](class_int.md)\ ) const [🔗](#class_AudioStreamSynchronized_method_get_sync_stream) + +Get one of the synchronized streams, by index. + +
+ + + + + +[float](class_float.md) **get_sync_stream_volume**\ (\ stream_index\: [int](class_int.md)\ ) const [🔗](#class_AudioStreamSynchronized_method_get_sync_stream_volume) + +Get the volume of one of the synchronized streams, by index. + +
+ + + + + +`void` **set_sync_stream**\ (\ stream_index\: [int](class_int.md), audio_stream\: [AudioStream](class_audiostream.md)\ ) [🔗](#class_AudioStreamSynchronized_method_set_sync_stream) + +Set one of the synchronized streams, by index. + +
+ + + + + +`void` **set_sync_stream_volume**\ (\ stream_index\: [int](class_int.md), volume_db\: [float](class_float.md)\ ) [🔗](#class_AudioStreamSynchronized_method_set_sync_stream_volume) + +Set the volume of one of the synchronized streams, by index. + diff --git a/docs/Classes/class_audiostreamwav.md b/docs/Classes/class_audiostreamwav.md new file mode 100644 index 00000000..0a8c971f --- /dev/null +++ b/docs/Classes/class_audiostreamwav.md @@ -0,0 +1,368 @@ + + + + + + + + + +# AudioStreamWAV + +**Inherits:** [AudioStream](class_audiostream.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Stores audio data loaded from WAV files. + + + +## Description + +AudioStreamWAV stores sound samples loaded from WAV files. To play the stored sound, use an [AudioStreamPlayer](class_audiostreamplayer.md) (for non-positional audio) or [AudioStreamPlayer2D](class_audiostreamplayer2d.md)/[AudioStreamPlayer3D](class_audiostreamplayer3d.md) (for positional audio). The sound can be looped. + +This class can also be used to store dynamically-generated PCM audio data. See also [AudioStreamGenerator](class_audiostreamgenerator.md) for procedural audio generation. + + + +## Tutorials + +- [Runtime file loading and saving](../tutorials/io/runtime_file_loading_and_saving.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[PackedByteArray](class_packedbytearray.md)[data](#class_AudioStreamWAV_property_data)`PackedByteArray()`
[Format](class_audiostreamwav.md#enum_AudioStreamWAV_Format)[format](#class_AudioStreamWAV_property_format)`0`
[int](class_int.md)[loop_begin](#class_AudioStreamWAV_property_loop_begin)`0`
[int](class_int.md)[loop_end](#class_AudioStreamWAV_property_loop_end)`0`
[LoopMode](class_audiostreamwav.md#enum_AudioStreamWAV_LoopMode)[loop_mode](#class_AudioStreamWAV_property_loop_mode)`0`
[int](class_int.md)[mix_rate](#class_AudioStreamWAV_property_mix_rate)`44100`
[bool](class_bool.md)[stereo](#class_AudioStreamWAV_property_stereo)`false`
[Dictionary](class_dictionary.md)[tags](#class_AudioStreamWAV_property_tags)`{}`
+ + + +## Methods + + + + + + + + + + + + + + + + + + +
[AudioStreamWAV](class_audiostreamwav.md)[load_from_buffer](#class_AudioStreamWAV_method_load_from_buffer)\ (\ stream_data\: [PackedByteArray](class_packedbytearray.md), options\: [Dictionary](class_dictionary.md) = {}\ ) static
[AudioStreamWAV](class_audiostreamwav.md)[load_from_file](#class_AudioStreamWAV_method_load_from_file)\ (\ path\: [String](class_string.md), options\: [Dictionary](class_dictionary.md) = {}\ ) static
[Error](class_@globalscope.md#enum_@GlobalScope_Error)[save_to_wav](#class_AudioStreamWAV_method_save_to_wav)\ (\ path\: [String](class_string.md)\ )
+ +
+ + + +## Enumerations + + + + + +enum **Format**: [🔗](#enum_AudioStreamWAV_Format) + + + + + +[Format](class_audiostreamwav.md#enum_AudioStreamWAV_Format) **FORMAT_8_BITS** = `0` + +8-bit PCM audio codec. + + + +[Format](class_audiostreamwav.md#enum_AudioStreamWAV_Format) **FORMAT_16_BITS** = `1` + +16-bit PCM audio codec. + + + +[Format](class_audiostreamwav.md#enum_AudioStreamWAV_Format) **FORMAT_IMA_ADPCM** = `2` + +Audio is lossily compressed as IMA ADPCM. + + + +[Format](class_audiostreamwav.md#enum_AudioStreamWAV_Format) **FORMAT_QOA** = `3` + +Audio is lossily compressed as [Quite OK Audio](https://qoaformat.org/).
+ + + + + +enum **LoopMode**: [🔗](#enum_AudioStreamWAV_LoopMode) + + + + + +[LoopMode](class_audiostreamwav.md#enum_AudioStreamWAV_LoopMode) **LOOP_DISABLED** = `0` + +Audio does not loop. + + + +[LoopMode](class_audiostreamwav.md#enum_AudioStreamWAV_LoopMode) **LOOP_FORWARD** = `1` + +Audio loops the data between [loop_begin](class_audiostreamwav.md#class_AudioStreamWAV_property_loop_begin) and [loop_end](class_audiostreamwav.md#class_AudioStreamWAV_property_loop_end), playing forward only. + + + +[LoopMode](class_audiostreamwav.md#enum_AudioStreamWAV_LoopMode) **LOOP_PINGPONG** = `2` + +Audio loops the data between [loop_begin](class_audiostreamwav.md#class_AudioStreamWAV_property_loop_begin) and [loop_end](class_audiostreamwav.md#class_AudioStreamWAV_property_loop_end), playing back and forth. + + + +[LoopMode](class_audiostreamwav.md#enum_AudioStreamWAV_LoopMode) **LOOP_BACKWARD** = `3` + +Audio loops the data between [loop_begin](class_audiostreamwav.md#class_AudioStreamWAV_property_loop_begin) and [loop_end](class_audiostreamwav.md#class_AudioStreamWAV_property_loop_end), playing backward only.
+ + + +## Property Descriptions + + + + + +[PackedByteArray](class_packedbytearray.md) **data** = `PackedByteArray()` [🔗](#class_AudioStreamWAV_property_data) + + + +- `void` **set_data**\ (\ value\: [PackedByteArray](class_packedbytearray.md)\ ) +- [PackedByteArray](class_packedbytearray.md) **get_data**\ (\ ) + +Contains the audio data in bytes. + +\ **Note:** If [format](class_audiostreamwav.md#class_AudioStreamWAV_property_format) is set to [FORMAT_8_BITS](class_audiostreamwav.md#class_AudioStreamWAV_constant_FORMAT_8_BITS), this property expects signed 8-bit PCM data. To convert from unsigned 8-bit PCM, subtract 128 from each byte. + +\ **Note:** If [format](class_audiostreamwav.md#class_AudioStreamWAV_property_format) is set to [FORMAT_QOA](class_audiostreamwav.md#class_AudioStreamWAV_constant_FORMAT_QOA), this property expects data from a full QOA file. + +**Note:** The returned array is *copied* and any changes to it will not update the original property value. See [PackedByteArray](class_packedbytearray.md) for more details. + +
+ + + + + +[Format](class_audiostreamwav.md#enum_AudioStreamWAV_Format) **format** = `0` [🔗](#class_AudioStreamWAV_property_format) + + + +- `void` **set_format**\ (\ value\: [Format](class_audiostreamwav.md#enum_AudioStreamWAV_Format)\ ) +- [Format](class_audiostreamwav.md#enum_AudioStreamWAV_Format) **get_format**\ (\ ) + +Audio format. + +
+ + + + + +[int](class_int.md) **loop_begin** = `0` [🔗](#class_AudioStreamWAV_property_loop_begin) + + + +- `void` **set_loop_begin**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_loop_begin**\ (\ ) + +The loop start point (in number of samples, relative to the beginning of the stream). + +
+ + + + + +[int](class_int.md) **loop_end** = `0` [🔗](#class_AudioStreamWAV_property_loop_end) + + + +- `void` **set_loop_end**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_loop_end**\ (\ ) + +The loop end point (in number of samples, relative to the beginning of the stream). + +
+ + + + + +[LoopMode](class_audiostreamwav.md#enum_AudioStreamWAV_LoopMode) **loop_mode** = `0` [🔗](#class_AudioStreamWAV_property_loop_mode) + + + +- `void` **set_loop_mode**\ (\ value\: [LoopMode](class_audiostreamwav.md#enum_AudioStreamWAV_LoopMode)\ ) +- [LoopMode](class_audiostreamwav.md#enum_AudioStreamWAV_LoopMode) **get_loop_mode**\ (\ ) + +The loop mode. + +
+ + + + + +[int](class_int.md) **mix_rate** = `44100` [🔗](#class_AudioStreamWAV_property_mix_rate) + + + +- `void` **set_mix_rate**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_mix_rate**\ (\ ) + +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 ``11025``, ``16000``, ``22050``, ``32000``, ``44100``, and ``48000``. + +According to the [Nyquist-Shannon sampling theorem](https://en.wikipedia.org/wiki/Nyquist%E2%80%93Shannon_sampling_theorem), 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 ``32000`` or ``22050`` may be usable with no loss in quality. + +
+ + + + + +[bool](class_bool.md) **stereo** = `false` [🔗](#class_AudioStreamWAV_property_stereo) + + + +- `void` **set_stereo**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_stereo**\ (\ ) + +If ``true``, audio is stereo. + +
+ + + + + +[Dictionary](class_dictionary.md) **tags** = `{}` [🔗](#class_AudioStreamWAV_property_tags) + + + +- `void` **set_tags**\ (\ value\: [Dictionary](class_dictionary.md)\ ) +- [Dictionary](class_dictionary.md) **get_tags**\ (\ ) + +Contains user-defined tags if found in the WAV data. + +Commonly used tags include ``title``, ``artist``, ``album``, ``tracknumber``, and ``date`` (``date`` does not have a standard date format). + +\ **Note:** No tag is *guaranteed* to be present in every file, so make sure to account for the keys not always existing. + +\ **Note:** Only WAV files using a ``LIST`` chunk with an identifier of ``INFO`` to encode the tags are currently supported. + +
+ + + +## Method Descriptions + + + + + +[AudioStreamWAV](class_audiostreamwav.md) **load_from_buffer**\ (\ stream_data\: [PackedByteArray](class_packedbytearray.md), options\: [Dictionary](class_dictionary.md) = {}\ ) static [🔗](#class_AudioStreamWAV_method_load_from_buffer) + +Creates a new **AudioStreamWAV** instance from the given buffer. The buffer must contain WAV data. + +The keys and values of `options` match the properties of [ResourceImporterWAV](class_resourceimporterwav.md). The usage of `options` is identical to [load_from_file()](class_audiostreamwav.md#class_AudioStreamWAV_method_load_from_file). + +
+ + + + + +[AudioStreamWAV](class_audiostreamwav.md) **load_from_file**\ (\ path\: [String](class_string.md), options\: [Dictionary](class_dictionary.md) = {}\ ) static [🔗](#class_AudioStreamWAV_method_load_from_file) + +Creates a new **AudioStreamWAV** instance from the given file path. The file must be in WAV format. + +The keys and values of `options` match the properties of [ResourceImporterWAV](class_resourceimporterwav.md). + +\ **Example:** Load the first file dropped as a WAV and play it: + +``` + @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() +``` + +
+ + + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **save_to_wav**\ (\ path\: [String](class_string.md)\ ) [🔗](#class_AudioStreamWAV_method_save_to_wav) + +Saves the AudioStreamWAV as a WAV file to `path`. Samples with IMA ADPCM or Quite OK Audio formats can't be saved. + +\ **Note:** A ``.wav`` extension is automatically appended to `path` if it is missing. + diff --git a/docs/Classes/class_backbuffercopy.md b/docs/Classes/class_backbuffercopy.md new file mode 100644 index 00000000..906ee754 --- /dev/null +++ b/docs/Classes/class_backbuffercopy.md @@ -0,0 +1,114 @@ + + + + + + + + + +# BackBufferCopy + +**Inherits:** [Node2D](class_node2d.md) **<** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +A node that copies a region of the screen to a buffer for access in shader code. + + + +## 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 [copy_mode](class_backbuffercopy.md#class_BackBufferCopy_property_copy_mode). It can be accessed in shader scripts using the screen texture (i.e. a uniform sampler with ``hint_screen_texture``). + +\ **Note:** Since this node inherits from [Node2D](class_node2d.md) (and not [Control](class_control.md)), anchors and margins won't apply to child [Control](class_control.md)-derived nodes. This can be problematic when resizing the window. To avoid this, add [Control](class_control.md)-derived nodes as *siblings* to the **BackBufferCopy** node instead of adding them as children. + + + +## Tutorials + +- [Screen-reading shaders](../tutorials/shaders/screen-reading_shaders.md) + + + +## Properties + + + + + + + + + + + + + + + + +
[CopyMode](class_backbuffercopy.md#enum_BackBufferCopy_CopyMode)[copy_mode](#class_BackBufferCopy_property_copy_mode)`1`
[Rect2](class_rect2.md)[rect](#class_BackBufferCopy_property_rect)`Rect2(-100, -100, 200, 200)`
+ +
+ + + +## Enumerations + + + + + +enum **CopyMode**: [🔗](#enum_BackBufferCopy_CopyMode) + + + + + +[CopyMode](class_backbuffercopy.md#enum_BackBufferCopy_CopyMode) **COPY_MODE_DISABLED** = `0` + +Disables the buffering mode. This means the **BackBufferCopy** node will directly use the portion of screen it covers. + + + +[CopyMode](class_backbuffercopy.md#enum_BackBufferCopy_CopyMode) **COPY_MODE_RECT** = `1` + +**BackBufferCopy** buffers a rectangular region. + + + +[CopyMode](class_backbuffercopy.md#enum_BackBufferCopy_CopyMode) **COPY_MODE_VIEWPORT** = `2` + +**BackBufferCopy** buffers the entire screen.
+ + + +## Property Descriptions + + + + + +[CopyMode](class_backbuffercopy.md#enum_BackBufferCopy_CopyMode) **copy_mode** = `1` [🔗](#class_BackBufferCopy_property_copy_mode) + + + +- `void` **set_copy_mode**\ (\ value\: [CopyMode](class_backbuffercopy.md#enum_BackBufferCopy_CopyMode)\ ) +- [CopyMode](class_backbuffercopy.md#enum_BackBufferCopy_CopyMode) **get_copy_mode**\ (\ ) + +Buffer mode. + +
+ + + + + +[Rect2](class_rect2.md) **rect** = `Rect2(-100, -100, 200, 200)` [🔗](#class_BackBufferCopy_property_rect) + + + +- `void` **set_rect**\ (\ value\: [Rect2](class_rect2.md)\ ) +- [Rect2](class_rect2.md) **get_rect**\ (\ ) + +The area covered by the **BackBufferCopy**. Only used if [copy_mode](class_backbuffercopy.md#class_BackBufferCopy_property_copy_mode) is [COPY_MODE_RECT](class_backbuffercopy.md#class_BackBufferCopy_constant_COPY_MODE_RECT). + diff --git a/docs/Classes/class_basebutton.md b/docs/Classes/class_basebutton.md new file mode 100644 index 00000000..b9075e87 --- /dev/null +++ b/docs/Classes/class_basebutton.md @@ -0,0 +1,450 @@ + + + + + + + + + +# BaseButton + +**Inherits:** [Control](class_control.md) **<** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +**Inherited By:** [Button](class_button.md), [LinkButton](class_linkbutton.md), [TextureButton](class_texturebutton.md) + +Abstract base class for GUI buttons. + + + +## Description + +**BaseButton** is an abstract base class for GUI buttons. It doesn't display anything by itself. + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[ActionMode](class_basebutton.md#enum_BaseButton_ActionMode)[action_mode](#class_BaseButton_property_action_mode)`1`
[ButtonGroup](class_buttongroup.md)[button_group](#class_BaseButton_property_button_group)
**BitField**\[[MouseButtonMask](class_@globalscope.md#enum_@GlobalScope_MouseButtonMask)\][button_mask](#class_BaseButton_property_button_mask)`1`
[bool](class_bool.md)[button_pressed](#class_BaseButton_property_button_pressed)`false`
[bool](class_bool.md)[disabled](#class_BaseButton_property_disabled)`false`
[FocusMode](class_control.md#enum_Control_FocusMode)focus_mode`2` (overrides [Control.focus_mode](class_control.md#class_Control_property_focus_mode))
[bool](class_bool.md)[keep_pressed_outside](#class_BaseButton_property_keep_pressed_outside)`false`
[Shortcut](class_shortcut.md)[shortcut](#class_BaseButton_property_shortcut)
[bool](class_bool.md)[shortcut_feedback](#class_BaseButton_property_shortcut_feedback)`true`
[bool](class_bool.md)[shortcut_in_tooltip](#class_BaseButton_property_shortcut_in_tooltip)`true`
[bool](class_bool.md)[toggle_mode](#class_BaseButton_property_toggle_mode)`false`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + +
`void`[_pressed](#class_BaseButton_private_method__pressed)\ (\ ) virtual
`void`[_toggled](#class_BaseButton_private_method__toggled)\ (\ toggled_on\: [bool](class_bool.md)\ ) virtual
[DrawMode](class_basebutton.md#enum_BaseButton_DrawMode)[get_draw_mode](#class_BaseButton_method_get_draw_mode)\ (\ ) const
[bool](class_bool.md)[is_hovered](#class_BaseButton_method_is_hovered)\ (\ ) const
`void`[set_pressed_no_signal](#class_BaseButton_method_set_pressed_no_signal)\ (\ pressed\: [bool](class_bool.md)\ )
+ +
+ + + +## Signals + + + + + +**button_down**\ (\ ) [🔗](#class_BaseButton_signal_button_down) + +Emitted when the button starts being held down. + +
+ + + + + +**button_up**\ (\ ) [🔗](#class_BaseButton_signal_button_up) + +Emitted when the button stops being held down. + +
+ + + + + +**pressed**\ (\ ) [🔗](#class_BaseButton_signal_pressed) + +Emitted when the button is toggled or pressed. This is on [button_down](class_basebutton.md#class_BaseButton_signal_button_down) if [action_mode](class_basebutton.md#class_BaseButton_property_action_mode) is [ACTION_MODE_BUTTON_PRESS](class_basebutton.md#class_BaseButton_constant_ACTION_MODE_BUTTON_PRESS) and on [button_up](class_basebutton.md#class_BaseButton_signal_button_up) otherwise. + +If you need to know the button's pressed state (and [toggle_mode](class_basebutton.md#class_BaseButton_property_toggle_mode) is active), use [toggled](class_basebutton.md#class_BaseButton_signal_toggled) instead. + +
+ + + + + +**toggled**\ (\ toggled_on\: [bool](class_bool.md)\ ) [🔗](#class_BaseButton_signal_toggled) + +Emitted when the button was just toggled between pressed and normal states (only if [toggle_mode](class_basebutton.md#class_BaseButton_property_toggle_mode) is active). The new state is contained in the `toggled_on` argument. + +
+ + + +## Enumerations + + + + + +enum **DrawMode**: [🔗](#enum_BaseButton_DrawMode) + + + + + +[DrawMode](class_basebutton.md#enum_BaseButton_DrawMode) **DRAW_NORMAL** = `0` + +The normal state (i.e. not pressed, not hovered, not toggled and enabled) of buttons. + + + +[DrawMode](class_basebutton.md#enum_BaseButton_DrawMode) **DRAW_PRESSED** = `1` + +The state of buttons are pressed. + + + +[DrawMode](class_basebutton.md#enum_BaseButton_DrawMode) **DRAW_HOVER** = `2` + +The state of buttons are hovered. + + + +[DrawMode](class_basebutton.md#enum_BaseButton_DrawMode) **DRAW_DISABLED** = `3` + +The state of buttons are disabled. + + + +[DrawMode](class_basebutton.md#enum_BaseButton_DrawMode) **DRAW_HOVER_PRESSED** = `4` + +The state of buttons are both hovered and pressed.
+ + + + + +enum **ActionMode**: [🔗](#enum_BaseButton_ActionMode) + + + + + +[ActionMode](class_basebutton.md#enum_BaseButton_ActionMode) **ACTION_MODE_BUTTON_PRESS** = `0` + +Require just a press to consider the button clicked. + + + +[ActionMode](class_basebutton.md#enum_BaseButton_ActionMode) **ACTION_MODE_BUTTON_RELEASE** = `1` + +Require a press and a subsequent release before considering the button clicked.
+ + + +## Property Descriptions + + + + + +[ActionMode](class_basebutton.md#enum_BaseButton_ActionMode) **action_mode** = `1` [🔗](#class_BaseButton_property_action_mode) + + + +- `void` **set_action_mode**\ (\ value\: [ActionMode](class_basebutton.md#enum_BaseButton_ActionMode)\ ) +- [ActionMode](class_basebutton.md#enum_BaseButton_ActionMode) **get_action_mode**\ (\ ) + +Determines when the button is considered clicked. + +
+ + + + + +[ButtonGroup](class_buttongroup.md) **button_group** [🔗](#class_BaseButton_property_button_group) + + + +- `void` **set_button_group**\ (\ value\: [ButtonGroup](class_buttongroup.md)\ ) +- [ButtonGroup](class_buttongroup.md) **get_button_group**\ (\ ) + +The [ButtonGroup](class_buttongroup.md) associated with the button. Not to be confused with node groups. + +\ **Note:** The button will be configured as a radio button if a [ButtonGroup](class_buttongroup.md) is assigned to it. + +
+ + + + + +**BitField**\[[MouseButtonMask](class_@globalscope.md#enum_@GlobalScope_MouseButtonMask)\] **button_mask** = `1` [🔗](#class_BaseButton_property_button_mask) + + + +- `void` **set_button_mask**\ (\ value\: **BitField**\[[MouseButtonMask](class_@globalscope.md#enum_@GlobalScope_MouseButtonMask)\]\ ) +- **BitField**\[[MouseButtonMask](class_@globalscope.md#enum_@GlobalScope_MouseButtonMask)\] **get_button_mask**\ (\ ) + +Binary mask to choose which mouse buttons this button will respond to. + +To allow both left-click and right-click, use ``MOUSE_BUTTON_MASK_LEFT | MOUSE_BUTTON_MASK_RIGHT``. + +
+ + + + + +[bool](class_bool.md) **button_pressed** = `false` [🔗](#class_BaseButton_property_button_pressed) + + + +- `void` **set_pressed**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_pressed**\ (\ ) + +If ``true``, the button's state is pressed. Means the button is pressed down or toggled (if [toggle_mode](class_basebutton.md#class_BaseButton_property_toggle_mode) is active). Only works if [toggle_mode](class_basebutton.md#class_BaseButton_property_toggle_mode) is ``true``. + +\ **Note:** Changing the value of [button_pressed](class_basebutton.md#class_BaseButton_property_button_pressed) will result in [toggled](class_basebutton.md#class_BaseButton_signal_toggled) to be emitted. If you want to change the pressed state without emitting that signal, use [set_pressed_no_signal()](class_basebutton.md#class_BaseButton_method_set_pressed_no_signal). + +
+ + + + + +[bool](class_bool.md) **disabled** = `false` [🔗](#class_BaseButton_property_disabled) + + + +- `void` **set_disabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_disabled**\ (\ ) + +If ``true``, the button is in disabled state and can't be clicked or toggled. + +\ **Note:** If the button is disabled while held down, [button_up](class_basebutton.md#class_BaseButton_signal_button_up) will be emitted. + +
+ + + + + +[bool](class_bool.md) **keep_pressed_outside** = `false` [🔗](#class_BaseButton_property_keep_pressed_outside) + + + +- `void` **set_keep_pressed_outside**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_keep_pressed_outside**\ (\ ) + +If ``true``, the button stays pressed when moving the cursor outside the button while pressing it. + +\ **Note:** This property only affects the button's visual appearance. Signals will be emitted at the same moment regardless of this property's value. + +
+ + + + + +[Shortcut](class_shortcut.md) **shortcut** [🔗](#class_BaseButton_property_shortcut) + + + +- `void` **set_shortcut**\ (\ value\: [Shortcut](class_shortcut.md)\ ) +- [Shortcut](class_shortcut.md) **get_shortcut**\ (\ ) + +[Shortcut](class_shortcut.md) associated to the button. + +
+ + + + + +[bool](class_bool.md) **shortcut_feedback** = `true` [🔗](#class_BaseButton_property_shortcut_feedback) + + + +- `void` **set_shortcut_feedback**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_shortcut_feedback**\ (\ ) + +If ``true``, the button will highlight for a short amount of time when its shortcut is activated. If ``false`` and [toggle_mode](class_basebutton.md#class_BaseButton_property_toggle_mode) is ``false``, the shortcut will activate without any visual feedback. + +
+ + + + + +[bool](class_bool.md) **shortcut_in_tooltip** = `true` [🔗](#class_BaseButton_property_shortcut_in_tooltip) + + + +- `void` **set_shortcut_in_tooltip**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_shortcut_in_tooltip_enabled**\ (\ ) + +If ``true``, the button will add information about its shortcut in the tooltip. + +\ **Note:** This property does nothing when the tooltip control is customized using [Control._make_custom_tooltip()](class_control.md#class_Control_private_method__make_custom_tooltip). + +
+ + + + + +[bool](class_bool.md) **toggle_mode** = `false` [🔗](#class_BaseButton_property_toggle_mode) + + + +- `void` **set_toggle_mode**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_toggle_mode**\ (\ ) + +If ``true``, the button is in toggle mode. Makes the button flip state between pressed and unpressed each time its area is clicked. + +
+ + + +## Method Descriptions + + + + + +`void` **_pressed**\ (\ ) virtual [🔗](#class_BaseButton_private_method__pressed) + +Called when the button is pressed. If you need to know the button's pressed state (and [toggle_mode](class_basebutton.md#class_BaseButton_property_toggle_mode) is active), use [_toggled()](class_basebutton.md#class_BaseButton_private_method__toggled) instead. + +
+ + + + + +`void` **_toggled**\ (\ toggled_on\: [bool](class_bool.md)\ ) virtual [🔗](#class_BaseButton_private_method__toggled) + +Called when the button is toggled (only if [toggle_mode](class_basebutton.md#class_BaseButton_property_toggle_mode) is active). + +
+ + + + + +[DrawMode](class_basebutton.md#enum_BaseButton_DrawMode) **get_draw_mode**\ (\ ) const [🔗](#class_BaseButton_method_get_draw_mode) + +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 [DrawMode](class_basebutton.md#enum_BaseButton_DrawMode) enum. + +
+ + + + + +[bool](class_bool.md) **is_hovered**\ (\ ) const [🔗](#class_BaseButton_method_is_hovered) + +Returns ``true`` if the mouse has entered the button and has not left it yet. + +
+ + + + + +`void` **set_pressed_no_signal**\ (\ pressed\: [bool](class_bool.md)\ ) [🔗](#class_BaseButton_method_set_pressed_no_signal) + +Changes the [button_pressed](class_basebutton.md#class_BaseButton_property_button_pressed) state of the button, without emitting [toggled](class_basebutton.md#class_BaseButton_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 [toggle_mode](class_basebutton.md#class_BaseButton_property_toggle_mode) is ``true``. + +\ **Note:** This method doesn't unpress other buttons in [button_group](class_basebutton.md#class_BaseButton_property_button_group). + diff --git a/docs/Classes/class_basematerial3d.md b/docs/Classes/class_basematerial3d.md new file mode 100644 index 00000000..558864c1 --- /dev/null +++ b/docs/Classes/class_basematerial3d.md @@ -0,0 +1,3827 @@ + + + + + + + + + +# BaseMaterial3D + +**Inherits:** [Material](class_material.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +**Inherited By:** [ORMMaterial3D](class_ormmaterial3d.md), [StandardMaterial3D](class_standardmaterial3d.md) + +Abstract base class for defining the 3D rendering properties of meshes. + + + +## 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. + + + +## Tutorials + +- [Standard Material 3D and ORM Material 3D](../tutorials/3d/standard_material_3d.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Color](class_color.md)[albedo_color](#class_BaseMaterial3D_property_albedo_color)`Color(1, 1, 1, 1)`
[Texture2D](class_texture2d.md)[albedo_texture](#class_BaseMaterial3D_property_albedo_texture)
[bool](class_bool.md)[albedo_texture_force_srgb](#class_BaseMaterial3D_property_albedo_texture_force_srgb)`false`
[bool](class_bool.md)[albedo_texture_msdf](#class_BaseMaterial3D_property_albedo_texture_msdf)`false`
[float](class_float.md)[alpha_antialiasing_edge](#class_BaseMaterial3D_property_alpha_antialiasing_edge)
[AlphaAntiAliasing](class_basematerial3d.md#enum_BaseMaterial3D_AlphaAntiAliasing)[alpha_antialiasing_mode](#class_BaseMaterial3D_property_alpha_antialiasing_mode)
[float](class_float.md)[alpha_hash_scale](#class_BaseMaterial3D_property_alpha_hash_scale)
[float](class_float.md)[alpha_scissor_threshold](#class_BaseMaterial3D_property_alpha_scissor_threshold)
[float](class_float.md)[anisotropy](#class_BaseMaterial3D_property_anisotropy)`0.0`
[bool](class_bool.md)[anisotropy_enabled](#class_BaseMaterial3D_property_anisotropy_enabled)`false`
[Texture2D](class_texture2d.md)[anisotropy_flowmap](#class_BaseMaterial3D_property_anisotropy_flowmap)
[bool](class_bool.md)[ao_enabled](#class_BaseMaterial3D_property_ao_enabled)`false`
[float](class_float.md)[ao_light_affect](#class_BaseMaterial3D_property_ao_light_affect)`0.0`
[bool](class_bool.md)[ao_on_uv2](#class_BaseMaterial3D_property_ao_on_uv2)`false`
[Texture2D](class_texture2d.md)[ao_texture](#class_BaseMaterial3D_property_ao_texture)
[TextureChannel](class_basematerial3d.md#enum_BaseMaterial3D_TextureChannel)[ao_texture_channel](#class_BaseMaterial3D_property_ao_texture_channel)`0`
[Color](class_color.md)[backlight](#class_BaseMaterial3D_property_backlight)`Color(0, 0, 0, 1)`
[bool](class_bool.md)[backlight_enabled](#class_BaseMaterial3D_property_backlight_enabled)`false`
[Texture2D](class_texture2d.md)[backlight_texture](#class_BaseMaterial3D_property_backlight_texture)
[bool](class_bool.md)[bent_normal_enabled](#class_BaseMaterial3D_property_bent_normal_enabled)`false`
[Texture2D](class_texture2d.md)[bent_normal_texture](#class_BaseMaterial3D_property_bent_normal_texture)
[bool](class_bool.md)[billboard_keep_scale](#class_BaseMaterial3D_property_billboard_keep_scale)`false`
[BillboardMode](class_basematerial3d.md#enum_BaseMaterial3D_BillboardMode)[billboard_mode](#class_BaseMaterial3D_property_billboard_mode)`0`
[BlendMode](class_basematerial3d.md#enum_BaseMaterial3D_BlendMode)[blend_mode](#class_BaseMaterial3D_property_blend_mode)`0`
[float](class_float.md)[clearcoat](#class_BaseMaterial3D_property_clearcoat)`1.0`
[bool](class_bool.md)[clearcoat_enabled](#class_BaseMaterial3D_property_clearcoat_enabled)`false`
[float](class_float.md)[clearcoat_roughness](#class_BaseMaterial3D_property_clearcoat_roughness)`0.5`
[Texture2D](class_texture2d.md)[clearcoat_texture](#class_BaseMaterial3D_property_clearcoat_texture)
[CullMode](class_basematerial3d.md#enum_BaseMaterial3D_CullMode)[cull_mode](#class_BaseMaterial3D_property_cull_mode)`0`
[DepthDrawMode](class_basematerial3d.md#enum_BaseMaterial3D_DepthDrawMode)[depth_draw_mode](#class_BaseMaterial3D_property_depth_draw_mode)`0`
[DepthTest](class_basematerial3d.md#enum_BaseMaterial3D_DepthTest)[depth_test](#class_BaseMaterial3D_property_depth_test)`0`
[Texture2D](class_texture2d.md)[detail_albedo](#class_BaseMaterial3D_property_detail_albedo)
[BlendMode](class_basematerial3d.md#enum_BaseMaterial3D_BlendMode)[detail_blend_mode](#class_BaseMaterial3D_property_detail_blend_mode)`0`
[bool](class_bool.md)[detail_enabled](#class_BaseMaterial3D_property_detail_enabled)`false`
[Texture2D](class_texture2d.md)[detail_mask](#class_BaseMaterial3D_property_detail_mask)
[Texture2D](class_texture2d.md)[detail_normal](#class_BaseMaterial3D_property_detail_normal)
[DetailUV](class_basematerial3d.md#enum_BaseMaterial3D_DetailUV)[detail_uv_layer](#class_BaseMaterial3D_property_detail_uv_layer)`0`
[DiffuseMode](class_basematerial3d.md#enum_BaseMaterial3D_DiffuseMode)[diffuse_mode](#class_BaseMaterial3D_property_diffuse_mode)`0`
[bool](class_bool.md)[disable_ambient_light](#class_BaseMaterial3D_property_disable_ambient_light)`false`
[bool](class_bool.md)[disable_fog](#class_BaseMaterial3D_property_disable_fog)`false`
[bool](class_bool.md)[disable_receive_shadows](#class_BaseMaterial3D_property_disable_receive_shadows)`false`
[bool](class_bool.md)[disable_specular_occlusion](#class_BaseMaterial3D_property_disable_specular_occlusion)`false`
[float](class_float.md)[distance_fade_max_distance](#class_BaseMaterial3D_property_distance_fade_max_distance)`10.0`
[float](class_float.md)[distance_fade_min_distance](#class_BaseMaterial3D_property_distance_fade_min_distance)`0.0`
[DistanceFadeMode](class_basematerial3d.md#enum_BaseMaterial3D_DistanceFadeMode)[distance_fade_mode](#class_BaseMaterial3D_property_distance_fade_mode)`0`
[Color](class_color.md)[emission](#class_BaseMaterial3D_property_emission)`Color(0, 0, 0, 1)`
[bool](class_bool.md)[emission_enabled](#class_BaseMaterial3D_property_emission_enabled)`false`
[float](class_float.md)[emission_energy_multiplier](#class_BaseMaterial3D_property_emission_energy_multiplier)`1.0`
[float](class_float.md)[emission_intensity](#class_BaseMaterial3D_property_emission_intensity)
[bool](class_bool.md)[emission_on_uv2](#class_BaseMaterial3D_property_emission_on_uv2)`false`
[EmissionOperator](class_basematerial3d.md#enum_BaseMaterial3D_EmissionOperator)[emission_operator](#class_BaseMaterial3D_property_emission_operator)`0`
[Texture2D](class_texture2d.md)[emission_texture](#class_BaseMaterial3D_property_emission_texture)
[bool](class_bool.md)[fixed_size](#class_BaseMaterial3D_property_fixed_size)`false`
[float](class_float.md)[fov_override](#class_BaseMaterial3D_property_fov_override)`75.0`
[bool](class_bool.md)[grow](#class_BaseMaterial3D_property_grow)`false`
[float](class_float.md)[grow_amount](#class_BaseMaterial3D_property_grow_amount)`0.0`
[bool](class_bool.md)[heightmap_deep_parallax](#class_BaseMaterial3D_property_heightmap_deep_parallax)`false`
[bool](class_bool.md)[heightmap_enabled](#class_BaseMaterial3D_property_heightmap_enabled)`false`
[bool](class_bool.md)[heightmap_flip_binormal](#class_BaseMaterial3D_property_heightmap_flip_binormal)`false`
[bool](class_bool.md)[heightmap_flip_tangent](#class_BaseMaterial3D_property_heightmap_flip_tangent)`false`
[bool](class_bool.md)[heightmap_flip_texture](#class_BaseMaterial3D_property_heightmap_flip_texture)`false`
[int](class_int.md)[heightmap_max_layers](#class_BaseMaterial3D_property_heightmap_max_layers)
[int](class_int.md)[heightmap_min_layers](#class_BaseMaterial3D_property_heightmap_min_layers)
[float](class_float.md)[heightmap_scale](#class_BaseMaterial3D_property_heightmap_scale)`5.0`
[Texture2D](class_texture2d.md)[heightmap_texture](#class_BaseMaterial3D_property_heightmap_texture)
[float](class_float.md)[metallic](#class_BaseMaterial3D_property_metallic)`0.0`
[float](class_float.md)[metallic_specular](#class_BaseMaterial3D_property_metallic_specular)`0.5`
[Texture2D](class_texture2d.md)[metallic_texture](#class_BaseMaterial3D_property_metallic_texture)
[TextureChannel](class_basematerial3d.md#enum_BaseMaterial3D_TextureChannel)[metallic_texture_channel](#class_BaseMaterial3D_property_metallic_texture_channel)`0`
[float](class_float.md)[msdf_outline_size](#class_BaseMaterial3D_property_msdf_outline_size)`0.0`
[float](class_float.md)[msdf_pixel_range](#class_BaseMaterial3D_property_msdf_pixel_range)`4.0`
[bool](class_bool.md)[no_depth_test](#class_BaseMaterial3D_property_no_depth_test)`false`
[bool](class_bool.md)[normal_enabled](#class_BaseMaterial3D_property_normal_enabled)`false`
[float](class_float.md)[normal_scale](#class_BaseMaterial3D_property_normal_scale)`1.0`
[Texture2D](class_texture2d.md)[normal_texture](#class_BaseMaterial3D_property_normal_texture)
[Texture2D](class_texture2d.md)[orm_texture](#class_BaseMaterial3D_property_orm_texture)
[int](class_int.md)[particles_anim_h_frames](#class_BaseMaterial3D_property_particles_anim_h_frames)
[bool](class_bool.md)[particles_anim_loop](#class_BaseMaterial3D_property_particles_anim_loop)
[int](class_int.md)[particles_anim_v_frames](#class_BaseMaterial3D_property_particles_anim_v_frames)
[float](class_float.md)[point_size](#class_BaseMaterial3D_property_point_size)`1.0`
[float](class_float.md)[proximity_fade_distance](#class_BaseMaterial3D_property_proximity_fade_distance)`1.0`
[bool](class_bool.md)[proximity_fade_enabled](#class_BaseMaterial3D_property_proximity_fade_enabled)`false`
[bool](class_bool.md)[refraction_enabled](#class_BaseMaterial3D_property_refraction_enabled)`false`
[float](class_float.md)[refraction_scale](#class_BaseMaterial3D_property_refraction_scale)`0.05`
[Texture2D](class_texture2d.md)[refraction_texture](#class_BaseMaterial3D_property_refraction_texture)
[TextureChannel](class_basematerial3d.md#enum_BaseMaterial3D_TextureChannel)[refraction_texture_channel](#class_BaseMaterial3D_property_refraction_texture_channel)`0`
[float](class_float.md)[rim](#class_BaseMaterial3D_property_rim)`1.0`
[bool](class_bool.md)[rim_enabled](#class_BaseMaterial3D_property_rim_enabled)`false`
[Texture2D](class_texture2d.md)[rim_texture](#class_BaseMaterial3D_property_rim_texture)
[float](class_float.md)[rim_tint](#class_BaseMaterial3D_property_rim_tint)`0.5`
[float](class_float.md)[roughness](#class_BaseMaterial3D_property_roughness)`1.0`
[Texture2D](class_texture2d.md)[roughness_texture](#class_BaseMaterial3D_property_roughness_texture)
[TextureChannel](class_basematerial3d.md#enum_BaseMaterial3D_TextureChannel)[roughness_texture_channel](#class_BaseMaterial3D_property_roughness_texture_channel)`0`
[ShadingMode](class_basematerial3d.md#enum_BaseMaterial3D_ShadingMode)[shading_mode](#class_BaseMaterial3D_property_shading_mode)`1`
[bool](class_bool.md)[shadow_to_opacity](#class_BaseMaterial3D_property_shadow_to_opacity)`false`
[SpecularMode](class_basematerial3d.md#enum_BaseMaterial3D_SpecularMode)[specular_mode](#class_BaseMaterial3D_property_specular_mode)`0`
[Color](class_color.md)[stencil_color](#class_BaseMaterial3D_property_stencil_color)`Color(0, 0, 0, 1)`
[StencilCompare](class_basematerial3d.md#enum_BaseMaterial3D_StencilCompare)[stencil_compare](#class_BaseMaterial3D_property_stencil_compare)`0`
[int](class_int.md)[stencil_flags](#class_BaseMaterial3D_property_stencil_flags)`0`
[StencilMode](class_basematerial3d.md#enum_BaseMaterial3D_StencilMode)[stencil_mode](#class_BaseMaterial3D_property_stencil_mode)`0`
[float](class_float.md)[stencil_outline_thickness](#class_BaseMaterial3D_property_stencil_outline_thickness)`0.01`
[int](class_int.md)[stencil_reference](#class_BaseMaterial3D_property_stencil_reference)`1`
[bool](class_bool.md)[subsurf_scatter_enabled](#class_BaseMaterial3D_property_subsurf_scatter_enabled)`false`
[bool](class_bool.md)[subsurf_scatter_skin_mode](#class_BaseMaterial3D_property_subsurf_scatter_skin_mode)`false`
[float](class_float.md)[subsurf_scatter_strength](#class_BaseMaterial3D_property_subsurf_scatter_strength)`0.0`
[Texture2D](class_texture2d.md)[subsurf_scatter_texture](#class_BaseMaterial3D_property_subsurf_scatter_texture)
[float](class_float.md)[subsurf_scatter_transmittance_boost](#class_BaseMaterial3D_property_subsurf_scatter_transmittance_boost)`0.0`
[Color](class_color.md)[subsurf_scatter_transmittance_color](#class_BaseMaterial3D_property_subsurf_scatter_transmittance_color)`Color(1, 1, 1, 1)`
[float](class_float.md)[subsurf_scatter_transmittance_depth](#class_BaseMaterial3D_property_subsurf_scatter_transmittance_depth)`0.1`
[bool](class_bool.md)[subsurf_scatter_transmittance_enabled](#class_BaseMaterial3D_property_subsurf_scatter_transmittance_enabled)`false`
[Texture2D](class_texture2d.md)[subsurf_scatter_transmittance_texture](#class_BaseMaterial3D_property_subsurf_scatter_transmittance_texture)
[TextureFilter](class_basematerial3d.md#enum_BaseMaterial3D_TextureFilter)[texture_filter](#class_BaseMaterial3D_property_texture_filter)`3`
[bool](class_bool.md)[texture_repeat](#class_BaseMaterial3D_property_texture_repeat)`true`
[Transparency](class_basematerial3d.md#enum_BaseMaterial3D_Transparency)[transparency](#class_BaseMaterial3D_property_transparency)`0`
[bool](class_bool.md)[use_fov_override](#class_BaseMaterial3D_property_use_fov_override)`false`
[bool](class_bool.md)[use_particle_trails](#class_BaseMaterial3D_property_use_particle_trails)`false`
[bool](class_bool.md)[use_point_size](#class_BaseMaterial3D_property_use_point_size)`false`
[bool](class_bool.md)[use_z_clip_scale](#class_BaseMaterial3D_property_use_z_clip_scale)`false`
[Vector3](class_vector3.md)[uv1_offset](#class_BaseMaterial3D_property_uv1_offset)`Vector3(0, 0, 0)`
[Vector3](class_vector3.md)[uv1_scale](#class_BaseMaterial3D_property_uv1_scale)`Vector3(1, 1, 1)`
[bool](class_bool.md)[uv1_triplanar](#class_BaseMaterial3D_property_uv1_triplanar)`false`
[float](class_float.md)[uv1_triplanar_sharpness](#class_BaseMaterial3D_property_uv1_triplanar_sharpness)`1.0`
[bool](class_bool.md)[uv1_world_triplanar](#class_BaseMaterial3D_property_uv1_world_triplanar)`false`
[Vector3](class_vector3.md)[uv2_offset](#class_BaseMaterial3D_property_uv2_offset)`Vector3(0, 0, 0)`
[Vector3](class_vector3.md)[uv2_scale](#class_BaseMaterial3D_property_uv2_scale)`Vector3(1, 1, 1)`
[bool](class_bool.md)[uv2_triplanar](#class_BaseMaterial3D_property_uv2_triplanar)`false`
[float](class_float.md)[uv2_triplanar_sharpness](#class_BaseMaterial3D_property_uv2_triplanar_sharpness)`1.0`
[bool](class_bool.md)[uv2_world_triplanar](#class_BaseMaterial3D_property_uv2_world_triplanar)`false`
[bool](class_bool.md)[vertex_color_is_srgb](#class_BaseMaterial3D_property_vertex_color_is_srgb)`false`
[bool](class_bool.md)[vertex_color_use_as_albedo](#class_BaseMaterial3D_property_vertex_color_use_as_albedo)`false`
[float](class_float.md)[z_clip_scale](#class_BaseMaterial3D_property_z_clip_scale)`1.0`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[get_feature](#class_BaseMaterial3D_method_get_feature)\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature)\ ) const
[bool](class_bool.md)[get_flag](#class_BaseMaterial3D_method_get_flag)\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const
[Texture2D](class_texture2d.md)[get_texture](#class_BaseMaterial3D_method_get_texture)\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam)\ ) const
`void`[set_feature](#class_BaseMaterial3D_method_set_feature)\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature), enable\: [bool](class_bool.md)\ )
`void`[set_flag](#class_BaseMaterial3D_method_set_flag)\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ )
`void`[set_texture](#class_BaseMaterial3D_method_set_texture)\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam), texture\: [Texture2D](class_texture2d.md)\ )
+ +
+ + + +## Enumerations + + + + + +enum **TextureParam**: [🔗](#enum_BaseMaterial3D_TextureParam) + + + + + +[TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam) **TEXTURE_ALBEDO** = `0` + +Texture specifying per-pixel color. + + + +[TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam) **TEXTURE_METALLIC** = `1` + +Texture specifying per-pixel metallic value. + + + +[TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam) **TEXTURE_ROUGHNESS** = `2` + +Texture specifying per-pixel roughness value. + + + +[TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam) **TEXTURE_EMISSION** = `3` + +Texture specifying per-pixel emission color. + + + +[TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam) **TEXTURE_NORMAL** = `4` + +Texture specifying per-pixel normal vector. + + + +[TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam) **TEXTURE_BENT_NORMAL** = `18` + +Texture specifying per-pixel bent normal vector. + + + +[TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam) **TEXTURE_RIM** = `5` + +Texture specifying per-pixel rim value. + + + +[TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam) **TEXTURE_CLEARCOAT** = `6` + +Texture specifying per-pixel clearcoat value. + + + +[TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam) **TEXTURE_FLOWMAP** = `7` + +Texture specifying per-pixel flowmap direction for use with [anisotropy](class_basematerial3d.md#class_BaseMaterial3D_property_anisotropy). + + + +[TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam) **TEXTURE_AMBIENT_OCCLUSION** = `8` + +Texture specifying per-pixel ambient occlusion value. + + + +[TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam) **TEXTURE_HEIGHTMAP** = `9` + +Texture specifying per-pixel height. + + + +[TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam) **TEXTURE_SUBSURFACE_SCATTERING** = `10` + +Texture specifying per-pixel subsurface scattering. + + + +[TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam) **TEXTURE_SUBSURFACE_TRANSMITTANCE** = `11` + +Texture specifying per-pixel transmittance for subsurface scattering. + + + +[TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam) **TEXTURE_BACKLIGHT** = `12` + +Texture specifying per-pixel backlight color. + + + +[TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam) **TEXTURE_REFRACTION** = `13` + +Texture specifying per-pixel refraction strength. + + + +[TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam) **TEXTURE_DETAIL_MASK** = `14` + +Texture specifying per-pixel detail mask blending value. + + + +[TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam) **TEXTURE_DETAIL_ALBEDO** = `15` + +Texture specifying per-pixel detail color. + + + +[TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam) **TEXTURE_DETAIL_NORMAL** = `16` + +Texture specifying per-pixel detail normal. + + + +[TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam) **TEXTURE_ORM** = `17` + +Texture holding ambient occlusion, roughness, and metallic. + + + +[TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam) **TEXTURE_MAX** = `19` + +Represents the size of the [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam) enum.
+ + + + + +enum **TextureFilter**: [🔗](#enum_BaseMaterial3D_TextureFilter) + + + + + +[TextureFilter](class_basematerial3d.md#enum_BaseMaterial3D_TextureFilter) **TEXTURE_FILTER_NEAREST** = `0` + +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). + + + +[TextureFilter](class_basematerial3d.md#enum_BaseMaterial3D_TextureFilter) **TEXTURE_FILTER_LINEAR** = `1` + +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). + + + +[TextureFilter](class_basematerial3d.md#enum_BaseMaterial3D_TextureFilter) **TEXTURE_FILTER_NEAREST_WITH_MIPMAPS** = `2` + +The texture filter reads from the nearest pixel and blends between the nearest 2 mipmaps (or uses the nearest mipmap if [ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter](class_projectsettings.md#class_ProjectSettings_property_rendering/textures/default_filters/use_nearest_mipmap_filter) is ``true``). This makes the texture look pixelated from up close, and smooth from a distance. + + + +[TextureFilter](class_basematerial3d.md#enum_BaseMaterial3D_TextureFilter) **TEXTURE_FILTER_LINEAR_WITH_MIPMAPS** = `3` + +The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps (or uses the nearest mipmap if [ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter](class_projectsettings.md#class_ProjectSettings_property_rendering/textures/default_filters/use_nearest_mipmap_filter) is ``true``). This makes the texture look smooth from up close, and smooth from a distance. + + + +[TextureFilter](class_basematerial3d.md#enum_BaseMaterial3D_TextureFilter) **TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC** = `4` + +The texture filter reads from the nearest pixel and blends between 2 mipmaps (or uses the nearest mipmap if [ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter](class_projectsettings.md#class_ProjectSettings_property_rendering/textures/default_filters/use_nearest_mipmap_filter) is ``true``) 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 [ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level](class_projectsettings.md#class_ProjectSettings_property_rendering/textures/default_filters/anisotropic_filtering_level). + + + +[TextureFilter](class_basematerial3d.md#enum_BaseMaterial3D_TextureFilter) **TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC** = `5` + +The texture filter blends between the nearest 4 pixels and blends between 2 mipmaps (or uses the nearest mipmap if [ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter](class_projectsettings.md#class_ProjectSettings_property_rendering/textures/default_filters/use_nearest_mipmap_filter) is ``true``) 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 [ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level](class_projectsettings.md#class_ProjectSettings_property_rendering/textures/default_filters/anisotropic_filtering_level). + + + +[TextureFilter](class_basematerial3d.md#enum_BaseMaterial3D_TextureFilter) **TEXTURE_FILTER_MAX** = `6` + +Represents the size of the [TextureFilter](class_basematerial3d.md#enum_BaseMaterial3D_TextureFilter) enum.
+ + + + + +enum **DetailUV**: [🔗](#enum_BaseMaterial3D_DetailUV) + + + + + +[DetailUV](class_basematerial3d.md#enum_BaseMaterial3D_DetailUV) **DETAIL_UV_1** = `0` + +Use ``UV`` with the detail texture. + + + +[DetailUV](class_basematerial3d.md#enum_BaseMaterial3D_DetailUV) **DETAIL_UV_2** = `1` + +Use ``UV2`` with the detail texture.
+ + + + + +enum **Transparency**: [🔗](#enum_BaseMaterial3D_Transparency) + + + + + +[Transparency](class_basematerial3d.md#enum_BaseMaterial3D_Transparency) **TRANSPARENCY_DISABLED** = `0` + +The material will not use transparency. This is the fastest to render. + + + +[Transparency](class_basematerial3d.md#enum_BaseMaterial3D_Transparency) **TRANSPARENCY_ALPHA** = `1` + +The material will use the texture's alpha values for transparency. This is the slowest to render, and disables shadow casting. + + + +[Transparency](class_basematerial3d.md#enum_BaseMaterial3D_Transparency) **TRANSPARENCY_ALPHA_SCISSOR** = `2` + +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. + + + +[Transparency](class_basematerial3d.md#enum_BaseMaterial3D_Transparency) **TRANSPARENCY_ALPHA_HASH** = `3` + +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. + + + +[Transparency](class_basematerial3d.md#enum_BaseMaterial3D_Transparency) **TRANSPARENCY_ALPHA_DEPTH_PRE_PASS** = `4` + +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. + + + +[Transparency](class_basematerial3d.md#enum_BaseMaterial3D_Transparency) **TRANSPARENCY_MAX** = `5` + +Represents the size of the [Transparency](class_basematerial3d.md#enum_BaseMaterial3D_Transparency) enum.
+ + + + + +enum **ShadingMode**: [🔗](#enum_BaseMaterial3D_ShadingMode) + + + + + +[ShadingMode](class_basematerial3d.md#enum_BaseMaterial3D_ShadingMode) **SHADING_MODE_UNSHADED** = `0` + +The object will not receive shadows. This is the fastest to render, but it disables all interactions with lights. + + + +[ShadingMode](class_basematerial3d.md#enum_BaseMaterial3D_ShadingMode) **SHADING_MODE_PER_PIXEL** = `1` + +The object will be shaded per pixel. Useful for realistic shading effects. + + + +[ShadingMode](class_basematerial3d.md#enum_BaseMaterial3D_ShadingMode) **SHADING_MODE_PER_VERTEX** = `2` + +The object will be shaded per vertex. Useful when you want cheaper shaders and do not care about visual quality. + + + +[ShadingMode](class_basematerial3d.md#enum_BaseMaterial3D_ShadingMode) **SHADING_MODE_MAX** = `3` + +Represents the size of the [ShadingMode](class_basematerial3d.md#enum_BaseMaterial3D_ShadingMode) enum.
+ + + + + +enum **Feature**: [🔗](#enum_BaseMaterial3D_Feature) + + + + + +[Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature) **FEATURE_EMISSION** = `0` + +Constant for setting [emission_enabled](class_basematerial3d.md#class_BaseMaterial3D_property_emission_enabled). + + + +[Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature) **FEATURE_NORMAL_MAPPING** = `1` + +Constant for setting [normal_enabled](class_basematerial3d.md#class_BaseMaterial3D_property_normal_enabled). + + + +[Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature) **FEATURE_RIM** = `2` + +Constant for setting [rim_enabled](class_basematerial3d.md#class_BaseMaterial3D_property_rim_enabled). + + + +[Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature) **FEATURE_CLEARCOAT** = `3` + +Constant for setting [clearcoat_enabled](class_basematerial3d.md#class_BaseMaterial3D_property_clearcoat_enabled). + + + +[Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature) **FEATURE_ANISOTROPY** = `4` + +Constant for setting [anisotropy_enabled](class_basematerial3d.md#class_BaseMaterial3D_property_anisotropy_enabled). + + + +[Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature) **FEATURE_AMBIENT_OCCLUSION** = `5` + +Constant for setting [ao_enabled](class_basematerial3d.md#class_BaseMaterial3D_property_ao_enabled). + + + +[Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature) **FEATURE_HEIGHT_MAPPING** = `6` + +Constant for setting [heightmap_enabled](class_basematerial3d.md#class_BaseMaterial3D_property_heightmap_enabled). + + + +[Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature) **FEATURE_SUBSURFACE_SCATTERING** = `7` + +Constant for setting [subsurf_scatter_enabled](class_basematerial3d.md#class_BaseMaterial3D_property_subsurf_scatter_enabled). + + + +[Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature) **FEATURE_SUBSURFACE_TRANSMITTANCE** = `8` + +Constant for setting [subsurf_scatter_transmittance_enabled](class_basematerial3d.md#class_BaseMaterial3D_property_subsurf_scatter_transmittance_enabled). + + + +[Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature) **FEATURE_BACKLIGHT** = `9` + +Constant for setting [backlight_enabled](class_basematerial3d.md#class_BaseMaterial3D_property_backlight_enabled). + + + +[Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature) **FEATURE_REFRACTION** = `10` + +Constant for setting [refraction_enabled](class_basematerial3d.md#class_BaseMaterial3D_property_refraction_enabled). + + + +[Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature) **FEATURE_DETAIL** = `11` + +Constant for setting [detail_enabled](class_basematerial3d.md#class_BaseMaterial3D_property_detail_enabled). + + + +[Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature) **FEATURE_BENT_NORMAL_MAPPING** = `12` + +Constant for setting [bent_normal_enabled](class_basematerial3d.md#class_BaseMaterial3D_property_bent_normal_enabled). + + + +[Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature) **FEATURE_MAX** = `13` + +Represents the size of the [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature) enum.
+ + + + + +enum **BlendMode**: [🔗](#enum_BaseMaterial3D_BlendMode) + + + + + +[BlendMode](class_basematerial3d.md#enum_BaseMaterial3D_BlendMode) **BLEND_MODE_MIX** = `0` + +Default blend mode. The color of the object is blended over the background based on the object's alpha value. + + + +[BlendMode](class_basematerial3d.md#enum_BaseMaterial3D_BlendMode) **BLEND_MODE_ADD** = `1` + +The color of the object is added to the background. + + + +[BlendMode](class_basematerial3d.md#enum_BaseMaterial3D_BlendMode) **BLEND_MODE_SUB** = `2` + +The color of the object is subtracted from the background. + + + +[BlendMode](class_basematerial3d.md#enum_BaseMaterial3D_BlendMode) **BLEND_MODE_MUL** = `3` + +The color of the object is multiplied by the background. + + + +[BlendMode](class_basematerial3d.md#enum_BaseMaterial3D_BlendMode) **BLEND_MODE_PREMULT_ALPHA** = `4` + +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 ``PREMUL_ALPHA_FACTOR`` built-in so that lighting can be modulated as well.
+ + + + + +enum **AlphaAntiAliasing**: [🔗](#enum_BaseMaterial3D_AlphaAntiAliasing) + + + + + +[AlphaAntiAliasing](class_basematerial3d.md#enum_BaseMaterial3D_AlphaAntiAliasing) **ALPHA_ANTIALIASING_OFF** = `0` + +Disables Alpha AntiAliasing for the material. + + + +[AlphaAntiAliasing](class_basematerial3d.md#enum_BaseMaterial3D_AlphaAntiAliasing) **ALPHA_ANTIALIASING_ALPHA_TO_COVERAGE** = `1` + +Enables AlphaToCoverage. Alpha values in the material are passed to the AntiAliasing sample mask. + + + +[AlphaAntiAliasing](class_basematerial3d.md#enum_BaseMaterial3D_AlphaAntiAliasing) **ALPHA_ANTIALIASING_ALPHA_TO_COVERAGE_AND_TO_ONE** = `2` + +Enables AlphaToCoverage and forces all non-zero alpha values to ``1``. Alpha values in the material are passed to the AntiAliasing sample mask.
+ + + + + +enum **DepthDrawMode**: [🔗](#enum_BaseMaterial3D_DepthDrawMode) + + + + + +[DepthDrawMode](class_basematerial3d.md#enum_BaseMaterial3D_DepthDrawMode) **DEPTH_DRAW_OPAQUE_ONLY** = `0` + +Default depth draw mode. Depth is drawn only for opaque objects during the opaque prepass (if any) and during the opaque pass. + + + +[DepthDrawMode](class_basematerial3d.md#enum_BaseMaterial3D_DepthDrawMode) **DEPTH_DRAW_ALWAYS** = `1` + +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. + +\ **Note:** This does not influence whether transparent objects are included in the depth prepass or not. For that, see [Transparency](class_basematerial3d.md#enum_BaseMaterial3D_Transparency). + + + +[DepthDrawMode](class_basematerial3d.md#enum_BaseMaterial3D_DepthDrawMode) **DEPTH_DRAW_DISABLED** = `2` + +Objects will not write their depth to the depth buffer, even during the depth prepass (if enabled).
+ + + + + +enum **DepthTest**: [🔗](#enum_BaseMaterial3D_DepthTest) + + + + + +[DepthTest](class_basematerial3d.md#enum_BaseMaterial3D_DepthTest) **DEPTH_TEST_DEFAULT** = `0` + +Depth test will discard the pixel if it is behind other pixels. + + + +[DepthTest](class_basematerial3d.md#enum_BaseMaterial3D_DepthTest) **DEPTH_TEST_INVERTED** = `1` + +Depth test will discard the pixel if it is in front of other pixels. Useful for stencil effects.
+ + + + + +enum **CullMode**: [🔗](#enum_BaseMaterial3D_CullMode) + + + + + +[CullMode](class_basematerial3d.md#enum_BaseMaterial3D_CullMode) **CULL_BACK** = `0` + +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. + + + +[CullMode](class_basematerial3d.md#enum_BaseMaterial3D_CullMode) **CULL_FRONT** = `1` + +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. + + + +[CullMode](class_basematerial3d.md#enum_BaseMaterial3D_CullMode) **CULL_DISABLED** = `2` + +No face culling is performed; both the front face and back face will be visible.
+ + + + + +enum **Flags**: [🔗](#enum_BaseMaterial3D_Flags) + + + + + +[Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) **FLAG_DISABLE_DEPTH_TEST** = `0` + +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. + + + +[Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) **FLAG_ALBEDO_FROM_VERTEX_COLOR** = `1` + +Set ``ALBEDO`` to the per-vertex color specified in the mesh. + + + +[Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) **FLAG_SRGB_VERTEX_COLOR** = `2` + +Vertex colors are considered to be stored in sRGB color space and are converted to linear color space during rendering. See also [vertex_color_is_srgb](class_basematerial3d.md#class_BaseMaterial3D_property_vertex_color_is_srgb). + +\ **Note:** Only effective when using the Forward+ and Mobile rendering methods. + + + +[Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) **FLAG_USE_POINT_SIZE** = `3` + +Uses point size to alter the size of primitive points. Also changes the albedo texture lookup to use ``POINT_COORD`` instead of ``UV``. + + + +[Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) **FLAG_FIXED_SIZE** = `4` + +Object is scaled by depth so that it always appears the same size on screen. + + + +[Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) **FLAG_BILLBOARD_KEEP_SCALE** = `5` + +Shader will keep the scale set for the mesh. Otherwise the scale is lost when billboarding. Only applies when [billboard_mode](class_basematerial3d.md#class_BaseMaterial3D_property_billboard_mode) is [BILLBOARD_ENABLED](class_basematerial3d.md#class_BaseMaterial3D_constant_BILLBOARD_ENABLED). + + + +[Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) **FLAG_UV1_USE_TRIPLANAR** = `6` + +Use triplanar texture lookup for all texture lookups that would normally use ``UV``. + + + +[Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) **FLAG_UV2_USE_TRIPLANAR** = `7` + +Use triplanar texture lookup for all texture lookups that would normally use ``UV2``. + + + +[Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) **FLAG_UV1_USE_WORLD_TRIPLANAR** = `8` + +Use triplanar texture lookup for all texture lookups that would normally use ``UV``. + + + +[Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) **FLAG_UV2_USE_WORLD_TRIPLANAR** = `9` + +Use triplanar texture lookup for all texture lookups that would normally use ``UV2``. + + + +[Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) **FLAG_AO_ON_UV2** = `10` + +Use ``UV2`` coordinates to look up from the [ao_texture](class_basematerial3d.md#class_BaseMaterial3D_property_ao_texture). + + + +[Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) **FLAG_EMISSION_ON_UV2** = `11` + +Use ``UV2`` coordinates to look up from the [emission_texture](class_basematerial3d.md#class_BaseMaterial3D_property_emission_texture). + + + +[Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) **FLAG_ALBEDO_TEXTURE_FORCE_SRGB** = `12` + +Forces the shader to convert albedo from sRGB space to linear space. See also [albedo_texture_force_srgb](class_basematerial3d.md#class_BaseMaterial3D_property_albedo_texture_force_srgb). + + + +[Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) **FLAG_DONT_RECEIVE_SHADOWS** = `13` + +Disables receiving shadows from other objects. + + + +[Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) **FLAG_DISABLE_AMBIENT_LIGHT** = `14` + +Disables receiving ambient light. + + + +[Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) **FLAG_USE_SHADOW_TO_OPACITY** = `15` + +Enables the shadow to opacity feature. + + + +[Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) **FLAG_USE_TEXTURE_REPEAT** = `16` + +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. + + + +[Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) **FLAG_INVERT_HEIGHTMAP** = `17` + +Invert values read from a depth texture to convert them to height values (heightmap). + + + +[Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) **FLAG_SUBSURFACE_MODE_SKIN** = `18` + +Enables the skin mode for subsurface scattering which is used to improve the look of subsurface scattering when used for human skin. + + + +[Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) **FLAG_PARTICLE_TRAILS_MODE** = `19` + +Enables parts of the shader required for [GPUParticles3D](class_gpuparticles3d.md) trails to function. This also requires using a mesh with appropriate skinning, such as [RibbonTrailMesh](class_ribbontrailmesh.md) or [TubeTrailMesh](class_tubetrailmesh.md). Enabling this feature outside of materials used in [GPUParticles3D](class_gpuparticles3d.md) meshes will break material rendering. + + + +[Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) **FLAG_ALBEDO_TEXTURE_MSDF** = `20` + +Enables multichannel signed distance field rendering shader. + + + +[Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) **FLAG_DISABLE_FOG** = `21` + +Disables receiving depth-based or volumetric fog. + + + +[Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) **FLAG_DISABLE_SPECULAR_OCCLUSION** = `22` + +Disables specular occlusion. + + + +[Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) **FLAG_USE_Z_CLIP_SCALE** = `23` + +Enables using [z_clip_scale](class_basematerial3d.md#class_BaseMaterial3D_property_z_clip_scale). + + + +[Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) **FLAG_USE_FOV_OVERRIDE** = `24` + +Enables using [fov_override](class_basematerial3d.md#class_BaseMaterial3D_property_fov_override). + + + +[Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) **FLAG_MAX** = `25` + +Represents the size of the [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags) enum.
+ + + + + +enum **DiffuseMode**: [🔗](#enum_BaseMaterial3D_DiffuseMode) + + + + + +[DiffuseMode](class_basematerial3d.md#enum_BaseMaterial3D_DiffuseMode) **DIFFUSE_BURLEY** = `0` + +Default diffuse scattering algorithm. + + + +[DiffuseMode](class_basematerial3d.md#enum_BaseMaterial3D_DiffuseMode) **DIFFUSE_LAMBERT** = `1` + +Diffuse scattering ignores roughness. + + + +[DiffuseMode](class_basematerial3d.md#enum_BaseMaterial3D_DiffuseMode) **DIFFUSE_LAMBERT_WRAP** = `2` + +Extends Lambert to cover more than 90 degrees when roughness increases. + + + +[DiffuseMode](class_basematerial3d.md#enum_BaseMaterial3D_DiffuseMode) **DIFFUSE_TOON** = `3` + +Uses a hard cut for lighting, with smoothing affected by roughness.
+ + + + + +enum **SpecularMode**: [🔗](#enum_BaseMaterial3D_SpecularMode) + + + + + +[SpecularMode](class_basematerial3d.md#enum_BaseMaterial3D_SpecularMode) **SPECULAR_SCHLICK_GGX** = `0` + +Default specular blob. + +\ **Note:** 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. + +\ **Note:** 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. + + + +[SpecularMode](class_basematerial3d.md#enum_BaseMaterial3D_SpecularMode) **SPECULAR_TOON** = `1` + +Toon blob which changes size based on roughness. + + + +[SpecularMode](class_basematerial3d.md#enum_BaseMaterial3D_SpecularMode) **SPECULAR_DISABLED** = `2` + +No specular blob. This is slightly faster to render than other specular modes.
+ + + + + +enum **BillboardMode**: [🔗](#enum_BaseMaterial3D_BillboardMode) + + + + + +[BillboardMode](class_basematerial3d.md#enum_BaseMaterial3D_BillboardMode) **BILLBOARD_DISABLED** = `0` + +Billboard mode is disabled. + + + +[BillboardMode](class_basematerial3d.md#enum_BaseMaterial3D_BillboardMode) **BILLBOARD_ENABLED** = `1` + +The object's Z axis will always face the camera. + + + +[BillboardMode](class_basematerial3d.md#enum_BaseMaterial3D_BillboardMode) **BILLBOARD_FIXED_Y** = `2` + +The object's X axis will always face the camera. + + + +[BillboardMode](class_basematerial3d.md#enum_BaseMaterial3D_BillboardMode) **BILLBOARD_PARTICLES** = `3` + +Used for particle systems when assigned to [GPUParticles3D](class_gpuparticles3d.md) and [CPUParticles3D](class_cpuparticles3d.md) nodes (flipbook animation). Enables ``particles_anim_*`` properties. + +The [ParticleProcessMaterial.anim_speed_min](class_particleprocessmaterial.md#class_ParticleProcessMaterial_property_anim_speed_min) or [CPUParticles3D.anim_speed_min](class_cpuparticles3d.md#class_CPUParticles3D_property_anim_speed_min) should also be set to a value bigger than zero for the animation to play.
+ + + + + +enum **TextureChannel**: [🔗](#enum_BaseMaterial3D_TextureChannel) + + + + + +[TextureChannel](class_basematerial3d.md#enum_BaseMaterial3D_TextureChannel) **TEXTURE_CHANNEL_RED** = `0` + +Used to read from the red channel of a texture. + + + +[TextureChannel](class_basematerial3d.md#enum_BaseMaterial3D_TextureChannel) **TEXTURE_CHANNEL_GREEN** = `1` + +Used to read from the green channel of a texture. + + + +[TextureChannel](class_basematerial3d.md#enum_BaseMaterial3D_TextureChannel) **TEXTURE_CHANNEL_BLUE** = `2` + +Used to read from the blue channel of a texture. + + + +[TextureChannel](class_basematerial3d.md#enum_BaseMaterial3D_TextureChannel) **TEXTURE_CHANNEL_ALPHA** = `3` + +Used to read from the alpha channel of a texture. + + + +[TextureChannel](class_basematerial3d.md#enum_BaseMaterial3D_TextureChannel) **TEXTURE_CHANNEL_GRAYSCALE** = `4` + +Used to read from the linear (non-perceptual) average of the red, green and blue channels of a texture.
+ + + + + +enum **EmissionOperator**: [🔗](#enum_BaseMaterial3D_EmissionOperator) + + + + + +[EmissionOperator](class_basematerial3d.md#enum_BaseMaterial3D_EmissionOperator) **EMISSION_OP_ADD** = `0` + +Adds the emission color to the color from the emission texture. + + + +[EmissionOperator](class_basematerial3d.md#enum_BaseMaterial3D_EmissionOperator) **EMISSION_OP_MULTIPLY** = `1` + +Multiplies the emission color by the color from the emission texture.
+ + + + + +enum **DistanceFadeMode**: [🔗](#enum_BaseMaterial3D_DistanceFadeMode) + + + + + +[DistanceFadeMode](class_basematerial3d.md#enum_BaseMaterial3D_DistanceFadeMode) **DISTANCE_FADE_DISABLED** = `0` + +Do not use distance fade. + + + +[DistanceFadeMode](class_basematerial3d.md#enum_BaseMaterial3D_DistanceFadeMode) **DISTANCE_FADE_PIXEL_ALPHA** = `1` + +Smoothly fades the object out based on each pixel's distance from the camera using the alpha channel. + + + +[DistanceFadeMode](class_basematerial3d.md#enum_BaseMaterial3D_DistanceFadeMode) **DISTANCE_FADE_PIXEL_DITHER** = `2` + +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 [DISTANCE_FADE_PIXEL_ALPHA](class_basematerial3d.md#class_BaseMaterial3D_constant_DISTANCE_FADE_PIXEL_ALPHA). + + + +[DistanceFadeMode](class_basematerial3d.md#enum_BaseMaterial3D_DistanceFadeMode) **DISTANCE_FADE_OBJECT_DITHER** = `3` + +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 [DISTANCE_FADE_PIXEL_ALPHA](class_basematerial3d.md#class_BaseMaterial3D_constant_DISTANCE_FADE_PIXEL_ALPHA) and [DISTANCE_FADE_PIXEL_DITHER](class_basematerial3d.md#class_BaseMaterial3D_constant_DISTANCE_FADE_PIXEL_DITHER).
+ + + + + +enum **StencilMode**: [🔗](#enum_BaseMaterial3D_StencilMode) + + + + + +[StencilMode](class_basematerial3d.md#enum_BaseMaterial3D_StencilMode) **STENCIL_MODE_DISABLED** = `0` + +Disables stencil operations. + + + +[StencilMode](class_basematerial3d.md#enum_BaseMaterial3D_StencilMode) **STENCIL_MODE_OUTLINE** = `1` + +Stencil preset which applies an outline to the object. + +\ **Note:** Requires a [Material.next_pass](class_material.md#class_Material_property_next_pass) material which will be automatically applied. Any manual changes made to [Material.next_pass](class_material.md#class_Material_property_next_pass) will be lost when the stencil properties are modified or the scene is reloaded. To safely apply a [Material.next_pass](class_material.md#class_Material_property_next_pass) material on a material that uses stencil presets, use [GeometryInstance3D.material_overlay](class_geometryinstance3d.md#class_GeometryInstance3D_property_material_overlay) instead. + + + +[StencilMode](class_basematerial3d.md#enum_BaseMaterial3D_StencilMode) **STENCIL_MODE_XRAY** = `2` + +Stencil preset which shows a silhouette of the object behind walls. + +\ **Note:** Requires a [Material.next_pass](class_material.md#class_Material_property_next_pass) material which will be automatically applied. Any manual changes made to [Material.next_pass](class_material.md#class_Material_property_next_pass) will be lost when the stencil properties are modified or the scene is reloaded. To safely apply a [Material.next_pass](class_material.md#class_Material_property_next_pass) material on a material that uses stencil presets, use [GeometryInstance3D.material_overlay](class_geometryinstance3d.md#class_GeometryInstance3D_property_material_overlay) instead. + + + +[StencilMode](class_basematerial3d.md#enum_BaseMaterial3D_StencilMode) **STENCIL_MODE_CUSTOM** = `3` + +Enables stencil operations without a preset.
+ + + + + +enum **StencilFlags**: [🔗](#enum_BaseMaterial3D_StencilFlags) + + + + + +[StencilFlags](class_basematerial3d.md#enum_BaseMaterial3D_StencilFlags) **STENCIL_FLAG_READ** = `1` + +The material will only be rendered where it passes a stencil comparison with existing stencil buffer values. See [StencilCompare](class_basematerial3d.md#enum_BaseMaterial3D_StencilCompare). + + + +[StencilFlags](class_basematerial3d.md#enum_BaseMaterial3D_StencilFlags) **STENCIL_FLAG_WRITE** = `2` + +The material will write the reference value to the stencil buffer where it passes the depth test. + + + +[StencilFlags](class_basematerial3d.md#enum_BaseMaterial3D_StencilFlags) **STENCIL_FLAG_WRITE_DEPTH_FAIL** = `4` + +The material will write the reference value to the stencil buffer where it fails the depth test.
+ + + + + +enum **StencilCompare**: [🔗](#enum_BaseMaterial3D_StencilCompare) + + + + + +[StencilCompare](class_basematerial3d.md#enum_BaseMaterial3D_StencilCompare) **STENCIL_COMPARE_ALWAYS** = `0` + +Always passes the stencil test. + + + +[StencilCompare](class_basematerial3d.md#enum_BaseMaterial3D_StencilCompare) **STENCIL_COMPARE_LESS** = `1` + +Passes the stencil test when the reference value is less than the existing stencil value. + + + +[StencilCompare](class_basematerial3d.md#enum_BaseMaterial3D_StencilCompare) **STENCIL_COMPARE_EQUAL** = `2` + +Passes the stencil test when the reference value is equal to the existing stencil value. + + + +[StencilCompare](class_basematerial3d.md#enum_BaseMaterial3D_StencilCompare) **STENCIL_COMPARE_LESS_OR_EQUAL** = `3` + +Passes the stencil test when the reference value is less than or equal to the existing stencil value. + + + +[StencilCompare](class_basematerial3d.md#enum_BaseMaterial3D_StencilCompare) **STENCIL_COMPARE_GREATER** = `4` + +Passes the stencil test when the reference value is greater than the existing stencil value. + + + +[StencilCompare](class_basematerial3d.md#enum_BaseMaterial3D_StencilCompare) **STENCIL_COMPARE_NOT_EQUAL** = `5` + +Passes the stencil test when the reference value is not equal to the existing stencil value. + + + +[StencilCompare](class_basematerial3d.md#enum_BaseMaterial3D_StencilCompare) **STENCIL_COMPARE_GREATER_OR_EQUAL** = `6` + +Passes the stencil test when the reference value is greater than or equal to the existing stencil value.
+ + + +## Property Descriptions + + + + + +[Color](class_color.md) **albedo_color** = `Color(1, 1, 1, 1)` [🔗](#class_BaseMaterial3D_property_albedo_color) + + + +- `void` **set_albedo**\ (\ value\: [Color](class_color.md)\ ) +- [Color](class_color.md) **get_albedo**\ (\ ) + +The material's base color. + +\ **Note:** If [detail_enabled](class_basematerial3d.md#class_BaseMaterial3D_property_detail_enabled) is ``true`` and a [detail_albedo](class_basematerial3d.md#class_BaseMaterial3D_property_detail_albedo) texture is specified, [albedo_color](class_basematerial3d.md#class_BaseMaterial3D_property_albedo_color) will *not* 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 [detail_albedo](class_basematerial3d.md#class_BaseMaterial3D_property_detail_albedo) texture instead. + +
+ + + + + +[Texture2D](class_texture2d.md) **albedo_texture** [🔗](#class_BaseMaterial3D_property_albedo_texture) + + + +- `void` **set_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam), texture\: [Texture2D](class_texture2d.md)\ ) +- [Texture2D](class_texture2d.md) **get_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam)\ ) const + +Texture to multiply by [albedo_color](class_basematerial3d.md#class_BaseMaterial3D_property_albedo_color). Used for basic texturing of objects. + +If the texture appears unexpectedly too dark or too bright, check [albedo_texture_force_srgb](class_basematerial3d.md#class_BaseMaterial3D_property_albedo_texture_force_srgb). + +
+ + + + + +[bool](class_bool.md) **albedo_texture_force_srgb** = `false` [🔗](#class_BaseMaterial3D_property_albedo_texture_force_srgb) + + + +- `void` **set_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const + +If ``true``, forces a conversion of the [albedo_texture](class_basematerial3d.md#class_BaseMaterial3D_property_albedo_texture) from sRGB color space to linear color space. See also [vertex_color_is_srgb](class_basematerial3d.md#class_BaseMaterial3D_property_vertex_color_is_srgb). + +This should only be enabled when needed (typically when using a [ViewportTexture](class_viewporttexture.md) as [albedo_texture](class_basematerial3d.md#class_BaseMaterial3D_property_albedo_texture)). If [albedo_texture_force_srgb](class_basematerial3d.md#class_BaseMaterial3D_property_albedo_texture_force_srgb) is ``true`` when it shouldn't be, the texture will appear to be too dark. If [albedo_texture_force_srgb](class_basematerial3d.md#class_BaseMaterial3D_property_albedo_texture_force_srgb) is ``false`` when it shouldn't be, the texture will appear to be too bright. + +
+ + + + + +[bool](class_bool.md) **albedo_texture_msdf** = `false` [🔗](#class_BaseMaterial3D_property_albedo_texture_msdf) + + + +- `void` **set_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const + +Enables multichannel signed distance field rendering shader. Use [msdf_pixel_range](class_basematerial3d.md#class_BaseMaterial3D_property_msdf_pixel_range) and [msdf_outline_size](class_basematerial3d.md#class_BaseMaterial3D_property_msdf_outline_size) to configure MSDF parameters. + +
+ + + + + +[float](class_float.md) **alpha_antialiasing_edge** [🔗](#class_BaseMaterial3D_property_alpha_antialiasing_edge) + + + +- `void` **set_alpha_antialiasing_edge**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_alpha_antialiasing_edge**\ (\ ) + +Threshold at which antialiasing will be applied on the alpha channel. + +
+ + + + + +[AlphaAntiAliasing](class_basematerial3d.md#enum_BaseMaterial3D_AlphaAntiAliasing) **alpha_antialiasing_mode** [🔗](#class_BaseMaterial3D_property_alpha_antialiasing_mode) + + + +- `void` **set_alpha_antialiasing**\ (\ value\: [AlphaAntiAliasing](class_basematerial3d.md#enum_BaseMaterial3D_AlphaAntiAliasing)\ ) +- [AlphaAntiAliasing](class_basematerial3d.md#enum_BaseMaterial3D_AlphaAntiAliasing) **get_alpha_antialiasing**\ (\ ) + +The type of alpha antialiasing to apply. + +
+ + + + + +[float](class_float.md) **alpha_hash_scale** [🔗](#class_BaseMaterial3D_property_alpha_hash_scale) + + + +- `void` **set_alpha_hash_scale**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_alpha_hash_scale**\ (\ ) + +The hashing scale for Alpha Hash. Recommended values between ``0`` and ``2``. + +
+ + + + + +[float](class_float.md) **alpha_scissor_threshold** [🔗](#class_BaseMaterial3D_property_alpha_scissor_threshold) + + + +- `void` **set_alpha_scissor_threshold**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_alpha_scissor_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 [alpha_scissor_threshold](class_basematerial3d.md#class_BaseMaterial3D_property_alpha_scissor_threshold). If the material disappears at a distance, try decreasing [alpha_scissor_threshold](class_basematerial3d.md#class_BaseMaterial3D_property_alpha_scissor_threshold). + +
+ + + + + +[float](class_float.md) **anisotropy** = `0.0` [🔗](#class_BaseMaterial3D_property_anisotropy) + + + +- `void` **set_anisotropy**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_anisotropy**\ (\ ) + +The strength of the anisotropy effect. This is multiplied by [anisotropy_flowmap](class_basematerial3d.md#class_BaseMaterial3D_property_anisotropy_flowmap)'s alpha channel if a texture is defined there and the texture contains an alpha channel. + +
+ + + + + +[bool](class_bool.md) **anisotropy_enabled** = `false` [🔗](#class_BaseMaterial3D_property_anisotropy_enabled) + + + +- `void` **set_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature)\ ) const + +If ``true``, 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. + +\ **Note:** Mesh tangents are needed for anisotropy to work. If the mesh does not contain tangents, the anisotropy effect will appear broken. + +\ **Note:** Material anisotropy should not to be confused with anisotropic texture filtering, which can be enabled by setting [texture_filter](class_basematerial3d.md#class_BaseMaterial3D_property_texture_filter) to [TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC](class_basematerial3d.md#class_BaseMaterial3D_constant_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC). + +
+ + + + + +[Texture2D](class_texture2d.md) **anisotropy_flowmap** [🔗](#class_BaseMaterial3D_property_anisotropy_flowmap) + + + +- `void` **set_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam), texture\: [Texture2D](class_texture2d.md)\ ) +- [Texture2D](class_texture2d.md) **get_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam)\ ) const + +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 [anisotropy](class_basematerial3d.md#class_BaseMaterial3D_property_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. + +
+ + + + + +[bool](class_bool.md) **ao_enabled** = `false` [🔗](#class_BaseMaterial3D_property_ao_enabled) + + + +- `void` **set_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature)\ ) const + +If ``true``, ambient occlusion is enabled. Ambient occlusion darkens areas based on the [ao_texture](class_basematerial3d.md#class_BaseMaterial3D_property_ao_texture). + +
+ + + + + +[float](class_float.md) **ao_light_affect** = `0.0` [🔗](#class_BaseMaterial3D_property_ao_light_affect) + + + +- `void` **set_ao_light_affect**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_ao_light_affect**\ (\ ) + +Amount that ambient occlusion affects lighting from lights. If ``0``, ambient occlusion only affects ambient light. If ``1``, 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. + +
+ + + + + +[bool](class_bool.md) **ao_on_uv2** = `false` [🔗](#class_BaseMaterial3D_property_ao_on_uv2) + + + +- `void` **set_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const + +If ``true``, use ``UV2`` coordinates to look up from the [ao_texture](class_basematerial3d.md#class_BaseMaterial3D_property_ao_texture). + +
+ + + + + +[Texture2D](class_texture2d.md) **ao_texture** [🔗](#class_BaseMaterial3D_property_ao_texture) + + + +- `void` **set_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam), texture\: [Texture2D](class_texture2d.md)\ ) +- [Texture2D](class_texture2d.md) **get_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam)\ ) const + +Texture that defines the amount of ambient occlusion for a given point on the object. + +
+ + + + + +[TextureChannel](class_basematerial3d.md#enum_BaseMaterial3D_TextureChannel) **ao_texture_channel** = `0` [🔗](#class_BaseMaterial3D_property_ao_texture_channel) + + + +- `void` **set_ao_texture_channel**\ (\ value\: [TextureChannel](class_basematerial3d.md#enum_BaseMaterial3D_TextureChannel)\ ) +- [TextureChannel](class_basematerial3d.md#enum_BaseMaterial3D_TextureChannel) **get_ao_texture_channel**\ (\ ) + +Specifies the channel of the [ao_texture](class_basematerial3d.md#class_BaseMaterial3D_property_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. + +
+ + + + + +[Color](class_color.md) **backlight** = `Color(0, 0, 0, 1)` [🔗](#class_BaseMaterial3D_property_backlight) + + + +- `void` **set_backlight**\ (\ value\: [Color](class_color.md)\ ) +- [Color](class_color.md) **get_backlight**\ (\ ) + +The color used by the backlight effect. Represents the light passing through an object. + +
+ + + + + +[bool](class_bool.md) **backlight_enabled** = `false` [🔗](#class_BaseMaterial3D_property_backlight_enabled) + + + +- `void` **set_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature)\ ) const + +If ``true``, the backlight effect is enabled. See also [subsurf_scatter_transmittance_enabled](class_basematerial3d.md#class_BaseMaterial3D_property_subsurf_scatter_transmittance_enabled). + +
+ + + + + +[Texture2D](class_texture2d.md) **backlight_texture** [🔗](#class_BaseMaterial3D_property_backlight_texture) + + + +- `void` **set_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam), texture\: [Texture2D](class_texture2d.md)\ ) +- [Texture2D](class_texture2d.md) **get_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam)\ ) const + +Texture used to control the backlight effect per-pixel. Added to [backlight](class_basematerial3d.md#class_BaseMaterial3D_property_backlight). + +
+ + + + + +[bool](class_bool.md) **bent_normal_enabled** = `false` [🔗](#class_BaseMaterial3D_property_bent_normal_enabled) + + + +- `void` **set_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature)\ ) const + +If ``true``, the bent normal map is enabled. This allows for more accurate indirect lighting and specular occlusion. + +
+ + + + + +[Texture2D](class_texture2d.md) **bent_normal_texture** [🔗](#class_BaseMaterial3D_property_bent_normal_texture) + + + +- `void` **set_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam), texture\: [Texture2D](class_texture2d.md)\ ) +- [Texture2D](class_texture2d.md) **get_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam)\ ) const + +Texture that specifies the average direction of incoming ambient light at a given pixel. The [bent_normal_texture](class_basematerial3d.md#class_BaseMaterial3D_property_bent_normal_texture) only uses the red and green channels; the blue and alpha channels are ignored. The normal read from [bent_normal_texture](class_basematerial3d.md#class_BaseMaterial3D_property_bent_normal_texture) is oriented around the surface normal provided by the [Mesh](class_mesh.md). + +\ **Note:** A bent normal map is different from a regular normal map. When baking a bent normal map make sure to use **a cosine distribution** for the bent normal map to work correctly. + +\ **Note:** 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](class_surfacetool.md), you can use [SurfaceTool.generate_normals()](class_surfacetool.md#class_SurfaceTool_method_generate_normals) and [SurfaceTool.generate_tangents()](class_surfacetool.md#class_SurfaceTool_method_generate_tangents) to automatically generate normals and tangents respectively. + +\ **Note:** Redot expects the bent normal map to use X+, Y+, and Z+ coordinates. See [this page](http://wiki.polycount.com/wiki/Normal_Map_Technical_Details#Common_Swizzle_Coordinates) for a comparison of normal map coordinates expected by popular engines. + +
+ + + + + +[bool](class_bool.md) **billboard_keep_scale** = `false` [🔗](#class_BaseMaterial3D_property_billboard_keep_scale) + + + +- `void` **set_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const + +If ``true``, the shader will keep the scale set for the mesh. Otherwise, the scale is lost when billboarding. Only applies when [billboard_mode](class_basematerial3d.md#class_BaseMaterial3D_property_billboard_mode) is not [BILLBOARD_DISABLED](class_basematerial3d.md#class_BaseMaterial3D_constant_BILLBOARD_DISABLED). + +
+ + + + + +[BillboardMode](class_basematerial3d.md#enum_BaseMaterial3D_BillboardMode) **billboard_mode** = `0` [🔗](#class_BaseMaterial3D_property_billboard_mode) + + + +- `void` **set_billboard_mode**\ (\ value\: [BillboardMode](class_basematerial3d.md#enum_BaseMaterial3D_BillboardMode)\ ) +- [BillboardMode](class_basematerial3d.md#enum_BaseMaterial3D_BillboardMode) **get_billboard_mode**\ (\ ) + +Controls how the object faces the camera. + +\ **Note:** 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 [GitHub issue #41567](https://github.com/godotengine/godot/issues/41567) for details. + +
+ + + + + +[BlendMode](class_basematerial3d.md#enum_BaseMaterial3D_BlendMode) **blend_mode** = `0` [🔗](#class_BaseMaterial3D_property_blend_mode) + + + +- `void` **set_blend_mode**\ (\ value\: [BlendMode](class_basematerial3d.md#enum_BaseMaterial3D_BlendMode)\ ) +- [BlendMode](class_basematerial3d.md#enum_BaseMaterial3D_BlendMode) **get_blend_mode**\ (\ ) + +The material's blend mode. + +\ **Note:** Values other than ``Mix`` force the object into the transparent pipeline. + +
+ + + + + +[float](class_float.md) **clearcoat** = `1.0` [🔗](#class_BaseMaterial3D_property_clearcoat) + + + +- `void` **set_clearcoat**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_clearcoat**\ (\ ) + +Sets the strength of the clearcoat effect. Setting to ``0`` looks the same as disabling the clearcoat effect. + +
+ + + + + +[bool](class_bool.md) **clearcoat_enabled** = `false` [🔗](#class_BaseMaterial3D_property_clearcoat_enabled) + + + +- `void` **set_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature)\ ) const + +If ``true``, 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. + +\ **Note:** Clearcoat rendering is not visible if the material's [shading_mode](class_basematerial3d.md#class_BaseMaterial3D_property_shading_mode) is [SHADING_MODE_UNSHADED](class_basematerial3d.md#class_BaseMaterial3D_constant_SHADING_MODE_UNSHADED). + +
+ + + + + +[float](class_float.md) **clearcoat_roughness** = `0.5` [🔗](#class_BaseMaterial3D_property_clearcoat_roughness) + + + +- `void` **set_clearcoat_roughness**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_clearcoat_roughness**\ (\ ) + +Sets the roughness of the clearcoat pass. A higher value results in a rougher clearcoat while a lower value results in a smoother clearcoat. + +
+ + + + + +[Texture2D](class_texture2d.md) **clearcoat_texture** [🔗](#class_BaseMaterial3D_property_clearcoat_texture) + + + +- `void` **set_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam), texture\: [Texture2D](class_texture2d.md)\ ) +- [Texture2D](class_texture2d.md) **get_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam)\ ) const + +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. + +
+ + + + + +[CullMode](class_basematerial3d.md#enum_BaseMaterial3D_CullMode) **cull_mode** = `0` [🔗](#class_BaseMaterial3D_property_cull_mode) + + + +- `void` **set_cull_mode**\ (\ value\: [CullMode](class_basematerial3d.md#enum_BaseMaterial3D_CullMode)\ ) +- [CullMode](class_basematerial3d.md#enum_BaseMaterial3D_CullMode) **get_cull_mode**\ (\ ) + +Determines which side of the triangle to cull depending on whether the triangle faces towards or away from the camera. + +
+ + + + + +[DepthDrawMode](class_basematerial3d.md#enum_BaseMaterial3D_DepthDrawMode) **depth_draw_mode** = `0` [🔗](#class_BaseMaterial3D_property_depth_draw_mode) + + + +- `void` **set_depth_draw_mode**\ (\ value\: [DepthDrawMode](class_basematerial3d.md#enum_BaseMaterial3D_DepthDrawMode)\ ) +- [DepthDrawMode](class_basematerial3d.md#enum_BaseMaterial3D_DepthDrawMode) **get_depth_draw_mode**\ (\ ) + +Determines when depth rendering takes place. See also [transparency](class_basematerial3d.md#class_BaseMaterial3D_property_transparency). + +
+ + + + + +[DepthTest](class_basematerial3d.md#enum_BaseMaterial3D_DepthTest) **depth_test** = `0` [🔗](#class_BaseMaterial3D_property_depth_test) + + + +- `void` **set_depth_test**\ (\ value\: [DepthTest](class_basematerial3d.md#enum_BaseMaterial3D_DepthTest)\ ) +- [DepthTest](class_basematerial3d.md#enum_BaseMaterial3D_DepthTest) **get_depth_test**\ (\ ) + +**Experimental:** May be affected by future rendering pipeline changes. + +Determines which comparison operator is used when testing depth. See [DepthTest](class_basematerial3d.md#enum_BaseMaterial3D_DepthTest). + +\ **Note:** Changing [depth_test](class_basematerial3d.md#class_BaseMaterial3D_property_depth_test) to a non-default value only has a visible effect when used on a transparent material, or a material that has [depth_draw_mode](class_basematerial3d.md#class_BaseMaterial3D_property_depth_draw_mode) set to [DEPTH_DRAW_DISABLED](class_basematerial3d.md#class_BaseMaterial3D_constant_DEPTH_DRAW_DISABLED). + +
+ + + + + +[Texture2D](class_texture2d.md) **detail_albedo** [🔗](#class_BaseMaterial3D_property_detail_albedo) + + + +- `void` **set_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam), texture\: [Texture2D](class_texture2d.md)\ ) +- [Texture2D](class_texture2d.md) **get_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam)\ ) const + +Texture that specifies the color of the detail overlay. [detail_albedo](class_basematerial3d.md#class_BaseMaterial3D_property_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 [detail_mask](class_basematerial3d.md#class_BaseMaterial3D_property_detail_mask). + +\ **Note:** [detail_albedo](class_basematerial3d.md#class_BaseMaterial3D_property_detail_albedo) is *not* modulated by [albedo_color](class_basematerial3d.md#class_BaseMaterial3D_property_albedo_color). + +
+ + + + + +[BlendMode](class_basematerial3d.md#enum_BaseMaterial3D_BlendMode) **detail_blend_mode** = `0` [🔗](#class_BaseMaterial3D_property_detail_blend_mode) + + + +- `void` **set_detail_blend_mode**\ (\ value\: [BlendMode](class_basematerial3d.md#enum_BaseMaterial3D_BlendMode)\ ) +- [BlendMode](class_basematerial3d.md#enum_BaseMaterial3D_BlendMode) **get_detail_blend_mode**\ (\ ) + +Specifies how the [detail_albedo](class_basematerial3d.md#class_BaseMaterial3D_property_detail_albedo) should blend with the current ``ALBEDO``. + +
+ + + + + +[bool](class_bool.md) **detail_enabled** = `false` [🔗](#class_BaseMaterial3D_property_detail_enabled) + + + +- `void` **set_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature)\ ) const + +If ``true``, enables the detail overlay. Detail is a second texture that gets mixed over the surface of the object based on [detail_mask](class_basematerial3d.md#class_BaseMaterial3D_property_detail_mask) and [detail_albedo](class_basematerial3d.md#class_BaseMaterial3D_property_detail_albedo)'s alpha channel. This can be used to add variation to objects, or to blend between two different albedo/normal textures. + +
+ + + + + +[Texture2D](class_texture2d.md) **detail_mask** [🔗](#class_BaseMaterial3D_property_detail_mask) + + + +- `void` **set_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam), texture\: [Texture2D](class_texture2d.md)\ ) +- [Texture2D](class_texture2d.md) **get_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam)\ ) const + +Texture used to specify how the detail textures get blended with the base textures. [detail_mask](class_basematerial3d.md#class_BaseMaterial3D_property_detail_mask) can be used together with [detail_albedo](class_basematerial3d.md#class_BaseMaterial3D_property_detail_albedo)'s alpha channel (if any). + +
+ + + + + +[Texture2D](class_texture2d.md) **detail_normal** [🔗](#class_BaseMaterial3D_property_detail_normal) + + + +- `void` **set_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam), texture\: [Texture2D](class_texture2d.md)\ ) +- [Texture2D](class_texture2d.md) **get_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam)\ ) const + +Texture that specifies the per-pixel normal of the detail overlay. The [detail_normal](class_basematerial3d.md#class_BaseMaterial3D_property_detail_normal) texture only uses the red and green channels; the blue and alpha channels are ignored. The normal read from [detail_normal](class_basematerial3d.md#class_BaseMaterial3D_property_detail_normal) is oriented around the surface normal provided by the [Mesh](class_mesh.md). + +\ **Note:** Redot expects the normal map to use X+, Y+, and Z+ coordinates. See [this page](http://wiki.polycount.com/wiki/Normal_Map_Technical_Details#Common_Swizzle_Coordinates) for a comparison of normal map coordinates expected by popular engines. + +
+ + + + + +[DetailUV](class_basematerial3d.md#enum_BaseMaterial3D_DetailUV) **detail_uv_layer** = `0` [🔗](#class_BaseMaterial3D_property_detail_uv_layer) + + + +- `void` **set_detail_uv**\ (\ value\: [DetailUV](class_basematerial3d.md#enum_BaseMaterial3D_DetailUV)\ ) +- [DetailUV](class_basematerial3d.md#enum_BaseMaterial3D_DetailUV) **get_detail_uv**\ (\ ) + +Specifies whether to use ``UV`` or ``UV2`` for the detail layer. + +
+ + + + + +[DiffuseMode](class_basematerial3d.md#enum_BaseMaterial3D_DiffuseMode) **diffuse_mode** = `0` [🔗](#class_BaseMaterial3D_property_diffuse_mode) + + + +- `void` **set_diffuse_mode**\ (\ value\: [DiffuseMode](class_basematerial3d.md#enum_BaseMaterial3D_DiffuseMode)\ ) +- [DiffuseMode](class_basematerial3d.md#enum_BaseMaterial3D_DiffuseMode) **get_diffuse_mode**\ (\ ) + +The algorithm used for diffuse light scattering. + +
+ + + + + +[bool](class_bool.md) **disable_ambient_light** = `false` [🔗](#class_BaseMaterial3D_property_disable_ambient_light) + + + +- `void` **set_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const + +If ``true``, the object receives no ambient light. + +
+ + + + + +[bool](class_bool.md) **disable_fog** = `false` [🔗](#class_BaseMaterial3D_property_disable_fog) + + + +- `void` **set_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const + +If ``true``, 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. + +
+ + + + + +[bool](class_bool.md) **disable_receive_shadows** = `false` [🔗](#class_BaseMaterial3D_property_disable_receive_shadows) + + + +- `void` **set_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const + +If ``true``, the object receives no shadow that would otherwise be cast onto it. + +
+ + + + + +[bool](class_bool.md) **disable_specular_occlusion** = `false` [🔗](#class_BaseMaterial3D_property_disable_specular_occlusion) + + + +- `void` **set_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const + +If ``true``, disables specular occlusion even if [ProjectSettings.rendering/reflections/specular_occlusion/enabled](class_projectsettings.md#class_ProjectSettings_property_rendering/reflections/specular_occlusion/enabled) is ``false``. + +
+ + + + + +[float](class_float.md) **distance_fade_max_distance** = `10.0` [🔗](#class_BaseMaterial3D_property_distance_fade_max_distance) + + + +- `void` **set_distance_fade_max_distance**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_distance_fade_max_distance**\ (\ ) + +Distance at which the object appears fully opaque. + +\ **Note:** If [distance_fade_max_distance](class_basematerial3d.md#class_BaseMaterial3D_property_distance_fade_max_distance) is less than [distance_fade_min_distance](class_basematerial3d.md#class_BaseMaterial3D_property_distance_fade_min_distance), the behavior will be reversed. The object will start to fade away at [distance_fade_max_distance](class_basematerial3d.md#class_BaseMaterial3D_property_distance_fade_max_distance) and will fully disappear once it reaches [distance_fade_min_distance](class_basematerial3d.md#class_BaseMaterial3D_property_distance_fade_min_distance). + +
+ + + + + +[float](class_float.md) **distance_fade_min_distance** = `0.0` [🔗](#class_BaseMaterial3D_property_distance_fade_min_distance) + + + +- `void` **set_distance_fade_min_distance**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_distance_fade_min_distance**\ (\ ) + +Distance at which the object starts to become visible. If the object is less than this distance away, it will be invisible. + +\ **Note:** If [distance_fade_min_distance](class_basematerial3d.md#class_BaseMaterial3D_property_distance_fade_min_distance) is greater than [distance_fade_max_distance](class_basematerial3d.md#class_BaseMaterial3D_property_distance_fade_max_distance), the behavior will be reversed. The object will start to fade away at [distance_fade_max_distance](class_basematerial3d.md#class_BaseMaterial3D_property_distance_fade_max_distance) and will fully disappear once it reaches [distance_fade_min_distance](class_basematerial3d.md#class_BaseMaterial3D_property_distance_fade_min_distance). + +
+ + + + + +[DistanceFadeMode](class_basematerial3d.md#enum_BaseMaterial3D_DistanceFadeMode) **distance_fade_mode** = `0` [🔗](#class_BaseMaterial3D_property_distance_fade_mode) + + + +- `void` **set_distance_fade**\ (\ value\: [DistanceFadeMode](class_basematerial3d.md#enum_BaseMaterial3D_DistanceFadeMode)\ ) +- [DistanceFadeMode](class_basematerial3d.md#enum_BaseMaterial3D_DistanceFadeMode) **get_distance_fade**\ (\ ) + +Specifies which type of fade to use. Can be any of the [DistanceFadeMode](class_basematerial3d.md#enum_BaseMaterial3D_DistanceFadeMode)\ s. + +
+ + + + + +[Color](class_color.md) **emission** = `Color(0, 0, 0, 1)` [🔗](#class_BaseMaterial3D_property_emission) + + + +- `void` **set_emission**\ (\ value\: [Color](class_color.md)\ ) +- [Color](class_color.md) **get_emission**\ (\ ) + +The emitted light's color. See [emission_enabled](class_basematerial3d.md#class_BaseMaterial3D_property_emission_enabled). + +
+ + + + + +[bool](class_bool.md) **emission_enabled** = `false` [🔗](#class_BaseMaterial3D_property_emission_enabled) + + + +- `void` **set_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature)\ ) const + +If ``true``, the body emits light. Emitting light makes the object appear brighter. The object can also cast light on other objects if a [VoxelGI](class_voxelgi.md), SDFGI, or [LightmapGI](class_lightmapgi.md) is used and this object is used in baked lighting. + +
+ + + + + +[float](class_float.md) **emission_energy_multiplier** = `1.0` [🔗](#class_BaseMaterial3D_property_emission_energy_multiplier) + + + +- `void` **set_emission_energy_multiplier**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_emission_energy_multiplier**\ (\ ) + +Multiplier for emitted light. See [emission_enabled](class_basematerial3d.md#class_BaseMaterial3D_property_emission_enabled). + +
+ + + + + +[float](class_float.md) **emission_intensity** [🔗](#class_BaseMaterial3D_property_emission_intensity) + + + +- `void` **set_emission_intensity**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_emission_intensity**\ (\ ) + +Luminance of emitted light, measured in nits (candela per square meter). Only available when [ProjectSettings.rendering/lights_and_shadows/use_physical_light_units](class_projectsettings.md#class_ProjectSettings_property_rendering/lights_and_shadows/use_physical_light_units) is enabled. The default is roughly equivalent to an indoor lightbulb. + +
+ + + + + +[bool](class_bool.md) **emission_on_uv2** = `false` [🔗](#class_BaseMaterial3D_property_emission_on_uv2) + + + +- `void` **set_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const + +Use ``UV2`` to read from the [emission_texture](class_basematerial3d.md#class_BaseMaterial3D_property_emission_texture). + +
+ + + + + +[EmissionOperator](class_basematerial3d.md#enum_BaseMaterial3D_EmissionOperator) **emission_operator** = `0` [🔗](#class_BaseMaterial3D_property_emission_operator) + + + +- `void` **set_emission_operator**\ (\ value\: [EmissionOperator](class_basematerial3d.md#enum_BaseMaterial3D_EmissionOperator)\ ) +- [EmissionOperator](class_basematerial3d.md#enum_BaseMaterial3D_EmissionOperator) **get_emission_operator**\ (\ ) + +Sets how [emission](class_basematerial3d.md#class_BaseMaterial3D_property_emission) interacts with [emission_texture](class_basematerial3d.md#class_BaseMaterial3D_property_emission_texture). Can either add or multiply. + +
+ + + + + +[Texture2D](class_texture2d.md) **emission_texture** [🔗](#class_BaseMaterial3D_property_emission_texture) + + + +- `void` **set_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam), texture\: [Texture2D](class_texture2d.md)\ ) +- [Texture2D](class_texture2d.md) **get_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam)\ ) const + +Texture that specifies how much surface emits light at a given point. + +
+ + + + + +[bool](class_bool.md) **fixed_size** = `false` [🔗](#class_BaseMaterial3D_property_fixed_size) + + + +- `void` **set_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const + +If ``true``, 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 ``1.0`` units away from the object's origin, regardless of the actual distance from the camera. The [Camera3D](class_camera3d.md)'s field of view (or [Camera3D.size](class_camera3d.md#class_Camera3D_property_size) when in orthogonal/frustum mode) still affects the size the object is drawn at. + +
+ + + + + +[float](class_float.md) **fov_override** = `75.0` [🔗](#class_BaseMaterial3D_property_fov_override) + + + +- `void` **set_fov_override**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_fov_override**\ (\ ) + +Overrides the [Camera3D](class_camera3d.md)'s field of view angle (in degrees). + +\ **Note:** This behaves as if the field of view is set on a [Camera3D](class_camera3d.md) with [Camera3D.keep_aspect](class_camera3d.md#class_Camera3D_property_keep_aspect) set to [Camera3D.KEEP_HEIGHT](class_camera3d.md#class_Camera3D_constant_KEEP_HEIGHT). Additionally, it may not look correct on a non-perspective camera where the field of view setting is ignored. + +
+ + + + + +[bool](class_bool.md) **grow** = `false` [🔗](#class_BaseMaterial3D_property_grow) + + + +- `void` **set_grow_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_grow_enabled**\ (\ ) + +If ``true``, enables the vertex grow setting. This can be used to create mesh-based outlines using a second material pass and its [cull_mode](class_basematerial3d.md#class_BaseMaterial3D_property_cull_mode) set to [CULL_FRONT](class_basematerial3d.md#class_BaseMaterial3D_constant_CULL_FRONT). See also [grow_amount](class_basematerial3d.md#class_BaseMaterial3D_property_grow_amount). + +\ **Note:** 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 [face weighted normals](http://wiki.polycount.com/wiki/Face_weighted_normals) in the 3D authoring software. In this case, grow will be able to join every outline together, just like in the original mesh. + +
+ + + + + +[float](class_float.md) **grow_amount** = `0.0` [🔗](#class_BaseMaterial3D_property_grow_amount) + + + +- `void` **set_grow**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_grow**\ (\ ) + +Grows object vertices in the direction of their normals. Only effective if [grow](class_basematerial3d.md#class_BaseMaterial3D_property_grow) is ``true``. + +
+ + + + + +[bool](class_bool.md) **heightmap_deep_parallax** = `false` [🔗](#class_BaseMaterial3D_property_heightmap_deep_parallax) + + + +- `void` **set_heightmap_deep_parallax**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_heightmap_deep_parallax_enabled**\ (\ ) + +If ``true``, uses parallax occlusion mapping to represent depth in the material instead of simple offset mapping (see [heightmap_enabled](class_basematerial3d.md#class_BaseMaterial3D_property_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. + +
+ + + + + +[bool](class_bool.md) **heightmap_enabled** = `false` [🔗](#class_BaseMaterial3D_property_heightmap_enabled) + + + +- `void` **set_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature)\ ) const + +If ``true``, height mapping is enabled (also called "parallax mapping" or "depth mapping"). See also [normal_enabled](class_basematerial3d.md#class_BaseMaterial3D_property_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. + +\ **Note:** Height mapping is not supported if triplanar mapping is used on the same material. The value of [heightmap_enabled](class_basematerial3d.md#class_BaseMaterial3D_property_heightmap_enabled) will be ignored if [uv1_triplanar](class_basematerial3d.md#class_BaseMaterial3D_property_uv1_triplanar) is enabled. + +
+ + + + + +[bool](class_bool.md) **heightmap_flip_binormal** = `false` [🔗](#class_BaseMaterial3D_property_heightmap_flip_binormal) + + + +- `void` **set_heightmap_deep_parallax_flip_binormal**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_heightmap_deep_parallax_flip_binormal**\ (\ ) + +If ``true``, 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 [heightmap_scale](class_basematerial3d.md#class_BaseMaterial3D_property_heightmap_scale)), try setting this to ``true``. + +
+ + + + + +[bool](class_bool.md) **heightmap_flip_tangent** = `false` [🔗](#class_BaseMaterial3D_property_heightmap_flip_tangent) + + + +- `void` **set_heightmap_deep_parallax_flip_tangent**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_heightmap_deep_parallax_flip_tangent**\ (\ ) + +If ``true``, 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 [heightmap_scale](class_basematerial3d.md#class_BaseMaterial3D_property_heightmap_scale)), try setting this to ``true``. + +
+ + + + + +[bool](class_bool.md) **heightmap_flip_texture** = `false` [🔗](#class_BaseMaterial3D_property_heightmap_flip_texture) + + + +- `void` **set_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const + +If ``true``, 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 [heightmap_flip_texture](class_basematerial3d.md#class_BaseMaterial3D_property_heightmap_flip_texture) should remain ``false``. + +
+ + + + + +[int](class_int.md) **heightmap_max_layers** [🔗](#class_BaseMaterial3D_property_heightmap_max_layers) + + + +- `void` **set_heightmap_deep_parallax_max_layers**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **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. + +\ **Note:** Only effective if [heightmap_deep_parallax](class_basematerial3d.md#class_BaseMaterial3D_property_heightmap_deep_parallax) is ``true``. + +
+ + + + + +[int](class_int.md) **heightmap_min_layers** [🔗](#class_BaseMaterial3D_property_heightmap_min_layers) + + + +- `void` **set_heightmap_deep_parallax_min_layers**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **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. + +\ **Note:** Only effective if [heightmap_deep_parallax](class_basematerial3d.md#class_BaseMaterial3D_property_heightmap_deep_parallax) is ``true``. + +
+ + + + + +[float](class_float.md) **heightmap_scale** = `5.0` [🔗](#class_BaseMaterial3D_property_heightmap_scale) + + + +- `void` **set_heightmap_scale**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_heightmap_scale**\ (\ ) + +The heightmap scale to use for the parallax effect (see [heightmap_enabled](class_basematerial3d.md#class_BaseMaterial3D_property_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 [heightmap_flip_texture](class_basematerial3d.md#class_BaseMaterial3D_property_heightmap_flip_texture) as the material will also appear to be "closer" to the camera. In most cases, [heightmap_scale](class_basematerial3d.md#class_BaseMaterial3D_property_heightmap_scale) should be kept to a positive value. + +\ **Note:** If the height map effect looks strange regardless of this value, try adjusting [heightmap_flip_binormal](class_basematerial3d.md#class_BaseMaterial3D_property_heightmap_flip_binormal) and [heightmap_flip_tangent](class_basematerial3d.md#class_BaseMaterial3D_property_heightmap_flip_tangent). See also [heightmap_texture](class_basematerial3d.md#class_BaseMaterial3D_property_heightmap_texture) for recommendations on authoring heightmap textures, as the way the heightmap texture is authored affects how [heightmap_scale](class_basematerial3d.md#class_BaseMaterial3D_property_heightmap_scale) behaves. + +
+ + + + + +[Texture2D](class_texture2d.md) **heightmap_texture** [🔗](#class_BaseMaterial3D_property_heightmap_texture) + + + +- `void` **set_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam), texture\: [Texture2D](class_texture2d.md)\ ) +- [Texture2D](class_texture2d.md) **get_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam)\ ) const + +The texture to use as a height map. See also [heightmap_enabled](class_basematerial3d.md#class_BaseMaterial3D_property_heightmap_enabled). + +For best results, the texture should be normalized (with [heightmap_scale](class_basematerial3d.md#class_BaseMaterial3D_property_heightmap_scale) reduced to compensate). In [GIMP](https://gimp.org), this can be done using **Colors > Auto > Equalize**. If the texture only uses a small part of its available range, the parallax effect may look strange, especially when the camera moves. + +\ **Note:** 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. + +
+ + + + + +[float](class_float.md) **metallic** = `0.0` [🔗](#class_BaseMaterial3D_property_metallic) + + + +- `void` **set_metallic**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_metallic**\ (\ ) + +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 ``0`` and ``1`` should only be used for blending between metal and non-metal sections. To alter the amount of reflection use [roughness](class_basematerial3d.md#class_BaseMaterial3D_property_roughness). + +
+ + + + + +[float](class_float.md) **metallic_specular** = `0.5` [🔗](#class_BaseMaterial3D_property_metallic_specular) + + + +- `void` **set_specular**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_specular**\ (\ ) + +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 ``0.0``, no specular reflections will be visible. This differs from the [SPECULAR_DISABLED](class_basematerial3d.md#class_BaseMaterial3D_constant_SPECULAR_DISABLED) [SpecularMode](class_basematerial3d.md#enum_BaseMaterial3D_SpecularMode) as [SPECULAR_DISABLED](class_basematerial3d.md#class_BaseMaterial3D_constant_SPECULAR_DISABLED) only applies to the specular lobe from the light source. + +\ **Note:** Unlike [metallic](class_basematerial3d.md#class_BaseMaterial3D_property_metallic), this is not energy-conserving, so it should be left at ``0.5`` in most cases. See also [roughness](class_basematerial3d.md#class_BaseMaterial3D_property_roughness). + +
+ + + + + +[Texture2D](class_texture2d.md) **metallic_texture** [🔗](#class_BaseMaterial3D_property_metallic_texture) + + + +- `void` **set_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam), texture\: [Texture2D](class_texture2d.md)\ ) +- [Texture2D](class_texture2d.md) **get_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam)\ ) const + +Texture used to specify metallic for an object. This is multiplied by [metallic](class_basematerial3d.md#class_BaseMaterial3D_property_metallic). + +
+ + + + + +[TextureChannel](class_basematerial3d.md#enum_BaseMaterial3D_TextureChannel) **metallic_texture_channel** = `0` [🔗](#class_BaseMaterial3D_property_metallic_texture_channel) + + + +- `void` **set_metallic_texture_channel**\ (\ value\: [TextureChannel](class_basematerial3d.md#enum_BaseMaterial3D_TextureChannel)\ ) +- [TextureChannel](class_basematerial3d.md#enum_BaseMaterial3D_TextureChannel) **get_metallic_texture_channel**\ (\ ) + +Specifies the channel of the [metallic_texture](class_basematerial3d.md#class_BaseMaterial3D_property_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. + +
+ + + + + +[float](class_float.md) **msdf_outline_size** = `0.0` [🔗](#class_BaseMaterial3D_property_msdf_outline_size) + + + +- `void` **set_msdf_outline_size**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_msdf_outline_size**\ (\ ) + +The width of the shape outline. + +
+ + + + + +[float](class_float.md) **msdf_pixel_range** = `4.0` [🔗](#class_BaseMaterial3D_property_msdf_pixel_range) + + + +- `void` **set_msdf_pixel_range**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_msdf_pixel_range**\ (\ ) + +The width of the range around the shape between the minimum and maximum representable signed distance. + +
+ + + + + +[bool](class_bool.md) **no_depth_test** = `false` [🔗](#class_BaseMaterial3D_property_no_depth_test) + + + +- `void` **set_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const + +If ``true``, depth testing is disabled and the object will be drawn in render order. + +
+ + + + + +[bool](class_bool.md) **normal_enabled** = `false` [🔗](#class_BaseMaterial3D_property_normal_enabled) + + + +- `void` **set_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature)\ ) const + +If ``true``, normal mapping is enabled. This has a slight performance cost, especially on mobile GPUs. + +
+ + + + + +[float](class_float.md) **normal_scale** = `1.0` [🔗](#class_BaseMaterial3D_property_normal_scale) + + + +- `void` **set_normal_scale**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_normal_scale**\ (\ ) + +The strength of the normal map's effect. + +
+ + + + + +[Texture2D](class_texture2d.md) **normal_texture** [🔗](#class_BaseMaterial3D_property_normal_texture) + + + +- `void` **set_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam), texture\: [Texture2D](class_texture2d.md)\ ) +- [Texture2D](class_texture2d.md) **get_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam)\ ) const + +Texture used to specify the normal at a given pixel. The [normal_texture](class_basematerial3d.md#class_BaseMaterial3D_property_normal_texture) only uses the red and green channels; the blue and alpha channels are ignored. The normal read from [normal_texture](class_basematerial3d.md#class_BaseMaterial3D_property_normal_texture) is oriented around the surface normal provided by the [Mesh](class_mesh.md). + +\ **Note:** 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](class_surfacetool.md), you can use [SurfaceTool.generate_normals()](class_surfacetool.md#class_SurfaceTool_method_generate_normals) and [SurfaceTool.generate_tangents()](class_surfacetool.md#class_SurfaceTool_method_generate_tangents) to automatically generate normals and tangents respectively. + +\ **Note:** Redot expects the normal map to use X+, Y+, and Z+ coordinates. See [this page](http://wiki.polycount.com/wiki/Normal_Map_Technical_Details#Common_Swizzle_Coordinates) for a comparison of normal map coordinates expected by popular engines. + +\ **Note:** If [detail_enabled](class_basematerial3d.md#class_BaseMaterial3D_property_detail_enabled) is ``true``, the [detail_albedo](class_basematerial3d.md#class_BaseMaterial3D_property_detail_albedo) texture is drawn *below* the [normal_texture](class_basematerial3d.md#class_BaseMaterial3D_property_normal_texture). To display a normal map *above* the [detail_albedo](class_basematerial3d.md#class_BaseMaterial3D_property_detail_albedo) texture, use [detail_normal](class_basematerial3d.md#class_BaseMaterial3D_property_detail_normal) instead. + +
+ + + + + +[Texture2D](class_texture2d.md) **orm_texture** [🔗](#class_BaseMaterial3D_property_orm_texture) + + + +- `void` **set_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam), texture\: [Texture2D](class_texture2d.md)\ ) +- [Texture2D](class_texture2d.md) **get_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam)\ ) const + +The Occlusion/Roughness/Metallic texture to use. This is a more efficient replacement of [ao_texture](class_basematerial3d.md#class_BaseMaterial3D_property_ao_texture), [roughness_texture](class_basematerial3d.md#class_BaseMaterial3D_property_roughness_texture) and [metallic_texture](class_basematerial3d.md#class_BaseMaterial3D_property_metallic_texture) in [ORMMaterial3D](class_ormmaterial3d.md). 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. + +
+ + + + + +[int](class_int.md) **particles_anim_h_frames** [🔗](#class_BaseMaterial3D_property_particles_anim_h_frames) + + + +- `void` **set_particles_anim_h_frames**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_particles_anim_h_frames**\ (\ ) + +The number of horizontal frames in the particle sprite sheet. Only enabled when using [BILLBOARD_PARTICLES](class_basematerial3d.md#class_BaseMaterial3D_constant_BILLBOARD_PARTICLES). See [billboard_mode](class_basematerial3d.md#class_BaseMaterial3D_property_billboard_mode). + +
+ + + + + +[bool](class_bool.md) **particles_anim_loop** [🔗](#class_BaseMaterial3D_property_particles_anim_loop) + + + +- `void` **set_particles_anim_loop**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_particles_anim_loop**\ (\ ) + +If ``true``, particle animations are looped. Only enabled when using [BILLBOARD_PARTICLES](class_basematerial3d.md#class_BaseMaterial3D_constant_BILLBOARD_PARTICLES). See [billboard_mode](class_basematerial3d.md#class_BaseMaterial3D_property_billboard_mode). + +
+ + + + + +[int](class_int.md) **particles_anim_v_frames** [🔗](#class_BaseMaterial3D_property_particles_anim_v_frames) + + + +- `void` **set_particles_anim_v_frames**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_particles_anim_v_frames**\ (\ ) + +The number of vertical frames in the particle sprite sheet. Only enabled when using [BILLBOARD_PARTICLES](class_basematerial3d.md#class_BaseMaterial3D_constant_BILLBOARD_PARTICLES). See [billboard_mode](class_basematerial3d.md#class_BaseMaterial3D_property_billboard_mode). + +
+ + + + + +[float](class_float.md) **point_size** = `1.0` [🔗](#class_BaseMaterial3D_property_point_size) + + + +- `void` **set_point_size**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_point_size**\ (\ ) + +The point size in pixels. See [use_point_size](class_basematerial3d.md#class_BaseMaterial3D_property_use_point_size). + +
+ + + + + +[float](class_float.md) **proximity_fade_distance** = `1.0` [🔗](#class_BaseMaterial3D_property_proximity_fade_distance) + + + +- `void` **set_proximity_fade_distance**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_proximity_fade_distance**\ (\ ) + +Distance over which the fade effect takes place. The larger the distance the longer it takes for an object to fade. + +
+ + + + + +[bool](class_bool.md) **proximity_fade_enabled** = `false` [🔗](#class_BaseMaterial3D_property_proximity_fade_enabled) + + + +- `void` **set_proximity_fade_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_proximity_fade_enabled**\ (\ ) + +If ``true``, the proximity fade effect is enabled. The proximity fade effect fades out each pixel based on its distance to another object. + +
+ + + + + +[bool](class_bool.md) **refraction_enabled** = `false` [🔗](#class_BaseMaterial3D_property_refraction_enabled) + + + +- `void` **set_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature)\ ) const + +If ``true``, the refraction effect is enabled. Distorts transparency based on light from behind the object. + +\ **Note:** 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. + +
+ + + + + +[float](class_float.md) **refraction_scale** = `0.05` [🔗](#class_BaseMaterial3D_property_refraction_scale) + + + +- `void` **set_refraction**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_refraction**\ (\ ) + +The strength of the refraction effect. + +
+ + + + + +[Texture2D](class_texture2d.md) **refraction_texture** [🔗](#class_BaseMaterial3D_property_refraction_texture) + + + +- `void` **set_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam), texture\: [Texture2D](class_texture2d.md)\ ) +- [Texture2D](class_texture2d.md) **get_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam)\ ) const + +Texture that controls the strength of the refraction per-pixel. Multiplied by [refraction_scale](class_basematerial3d.md#class_BaseMaterial3D_property_refraction_scale). + +
+ + + + + +[TextureChannel](class_basematerial3d.md#enum_BaseMaterial3D_TextureChannel) **refraction_texture_channel** = `0` [🔗](#class_BaseMaterial3D_property_refraction_texture_channel) + + + +- `void` **set_refraction_texture_channel**\ (\ value\: [TextureChannel](class_basematerial3d.md#enum_BaseMaterial3D_TextureChannel)\ ) +- [TextureChannel](class_basematerial3d.md#enum_BaseMaterial3D_TextureChannel) **get_refraction_texture_channel**\ (\ ) + +Specifies the channel of the [refraction_texture](class_basematerial3d.md#class_BaseMaterial3D_property_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. + +
+ + + + + +[float](class_float.md) **rim** = `1.0` [🔗](#class_BaseMaterial3D_property_rim) + + + +- `void` **set_rim**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_rim**\ (\ ) + +Sets the strength of the rim lighting effect. + +
+ + + + + +[bool](class_bool.md) **rim_enabled** = `false` [🔗](#class_BaseMaterial3D_property_rim_enabled) + + + +- `void` **set_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature)\ ) const + +If ``true``, rim effect is enabled. Rim lighting increases the brightness at glancing angles on an object. + +\ **Note:** Rim lighting is not visible if the material's [shading_mode](class_basematerial3d.md#class_BaseMaterial3D_property_shading_mode) is [SHADING_MODE_UNSHADED](class_basematerial3d.md#class_BaseMaterial3D_constant_SHADING_MODE_UNSHADED). + +
+ + + + + +[Texture2D](class_texture2d.md) **rim_texture** [🔗](#class_BaseMaterial3D_property_rim_texture) + + + +- `void` **set_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam), texture\: [Texture2D](class_texture2d.md)\ ) +- [Texture2D](class_texture2d.md) **get_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam)\ ) const + +Texture used to set the strength of the rim lighting effect per-pixel. Multiplied by [rim](class_basematerial3d.md#class_BaseMaterial3D_property_rim). + +
+ + + + + +[float](class_float.md) **rim_tint** = `0.5` [🔗](#class_BaseMaterial3D_property_rim_tint) + + + +- `void` **set_rim_tint**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_rim_tint**\ (\ ) + +The amount of to blend light and albedo color when rendering rim effect. If ``0`` the light color is used, while ``1`` means albedo color is used. An intermediate value generally works best. + +
+ + + + + +[float](class_float.md) **roughness** = `1.0` [🔗](#class_BaseMaterial3D_property_roughness) + + + +- `void` **set_roughness**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_roughness**\ (\ ) + +Surface reflection. A value of ``0`` represents a perfect mirror while a value of ``1`` completely blurs the reflection. See also [metallic](class_basematerial3d.md#class_BaseMaterial3D_property_metallic). + +
+ + + + + +[Texture2D](class_texture2d.md) **roughness_texture** [🔗](#class_BaseMaterial3D_property_roughness_texture) + + + +- `void` **set_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam), texture\: [Texture2D](class_texture2d.md)\ ) +- [Texture2D](class_texture2d.md) **get_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam)\ ) const + +Texture used to control the roughness per-pixel. Multiplied by [roughness](class_basematerial3d.md#class_BaseMaterial3D_property_roughness). + +
+ + + + + +[TextureChannel](class_basematerial3d.md#enum_BaseMaterial3D_TextureChannel) **roughness_texture_channel** = `0` [🔗](#class_BaseMaterial3D_property_roughness_texture_channel) + + + +- `void` **set_roughness_texture_channel**\ (\ value\: [TextureChannel](class_basematerial3d.md#enum_BaseMaterial3D_TextureChannel)\ ) +- [TextureChannel](class_basematerial3d.md#enum_BaseMaterial3D_TextureChannel) **get_roughness_texture_channel**\ (\ ) + +Specifies the channel of the [roughness_texture](class_basematerial3d.md#class_BaseMaterial3D_property_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. + +
+ + + + + +[ShadingMode](class_basematerial3d.md#enum_BaseMaterial3D_ShadingMode) **shading_mode** = `1` [🔗](#class_BaseMaterial3D_property_shading_mode) + + + +- `void` **set_shading_mode**\ (\ value\: [ShadingMode](class_basematerial3d.md#enum_BaseMaterial3D_ShadingMode)\ ) +- [ShadingMode](class_basematerial3d.md#enum_BaseMaterial3D_ShadingMode) **get_shading_mode**\ (\ ) + +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. + +
+ + + + + +[bool](class_bool.md) **shadow_to_opacity** = `false` [🔗](#class_BaseMaterial3D_property_shadow_to_opacity) + + + +- `void` **set_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const + +If ``true``, 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. + +
+ + + + + +[SpecularMode](class_basematerial3d.md#enum_BaseMaterial3D_SpecularMode) **specular_mode** = `0` [🔗](#class_BaseMaterial3D_property_specular_mode) + + + +- `void` **set_specular_mode**\ (\ value\: [SpecularMode](class_basematerial3d.md#enum_BaseMaterial3D_SpecularMode)\ ) +- [SpecularMode](class_basematerial3d.md#enum_BaseMaterial3D_SpecularMode) **get_specular_mode**\ (\ ) + +The method for rendering the specular blob. + +\ **Note:** [specular_mode](class_basematerial3d.md#class_BaseMaterial3D_property_specular_mode) only applies to the specular blob. It does not affect specular reflections from the sky, screen-space reflections, [VoxelGI](class_voxelgi.md), SDFGI or [ReflectionProbe](class_reflectionprobe.md)\ s. To disable reflections from these sources as well, set [metallic_specular](class_basematerial3d.md#class_BaseMaterial3D_property_metallic_specular) to ``0.0`` instead. + +
+ + + + + +[Color](class_color.md) **stencil_color** = `Color(0, 0, 0, 1)` [🔗](#class_BaseMaterial3D_property_stencil_color) + + + +- `void` **set_stencil_effect_color**\ (\ value\: [Color](class_color.md)\ ) +- [Color](class_color.md) **get_stencil_effect_color**\ (\ ) + +**Experimental:** May be affected by future rendering pipeline changes. + +The primary color of the stencil effect. + +
+ + + + + +[StencilCompare](class_basematerial3d.md#enum_BaseMaterial3D_StencilCompare) **stencil_compare** = `0` [🔗](#class_BaseMaterial3D_property_stencil_compare) + + + +- `void` **set_stencil_compare**\ (\ value\: [StencilCompare](class_basematerial3d.md#enum_BaseMaterial3D_StencilCompare)\ ) +- [StencilCompare](class_basematerial3d.md#enum_BaseMaterial3D_StencilCompare) **get_stencil_compare**\ (\ ) + +**Experimental:** May be affected by future rendering pipeline changes. + +The comparison operator to use for stencil masking operations. See [StencilCompare](class_basematerial3d.md#enum_BaseMaterial3D_StencilCompare). + +
+ + + + + +[int](class_int.md) **stencil_flags** = `0` [🔗](#class_BaseMaterial3D_property_stencil_flags) + + + +- `void` **set_stencil_flags**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_stencil_flags**\ (\ ) + +**Experimental:** May be affected by future rendering pipeline changes. + +The flags dictating how the stencil operation behaves. See [StencilFlags](class_basematerial3d.md#enum_BaseMaterial3D_StencilFlags). + +
+ + + + + +[StencilMode](class_basematerial3d.md#enum_BaseMaterial3D_StencilMode) **stencil_mode** = `0` [🔗](#class_BaseMaterial3D_property_stencil_mode) + + + +- `void` **set_stencil_mode**\ (\ value\: [StencilMode](class_basematerial3d.md#enum_BaseMaterial3D_StencilMode)\ ) +- [StencilMode](class_basematerial3d.md#enum_BaseMaterial3D_StencilMode) **get_stencil_mode**\ (\ ) + +**Experimental:** May be affected by future rendering pipeline changes. + +The stencil effect mode. See [StencilMode](class_basematerial3d.md#enum_BaseMaterial3D_StencilMode). + +
+ + + + + +[float](class_float.md) **stencil_outline_thickness** = `0.01` [🔗](#class_BaseMaterial3D_property_stencil_outline_thickness) + + + +- `void` **set_stencil_effect_outline_thickness**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_stencil_effect_outline_thickness**\ (\ ) + +**Experimental:** May be affected by future rendering pipeline changes. + +The outline thickness for [STENCIL_MODE_OUTLINE](class_basematerial3d.md#class_BaseMaterial3D_constant_STENCIL_MODE_OUTLINE). + +
+ + + + + +[int](class_int.md) **stencil_reference** = `1` [🔗](#class_BaseMaterial3D_property_stencil_reference) + + + +- `void` **set_stencil_reference**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_stencil_reference**\ (\ ) + +**Experimental:** May be affected by future rendering pipeline changes. + +The stencil reference value (0-255). Typically a power of 2. + +
+ + + + + +[bool](class_bool.md) **subsurf_scatter_enabled** = `false` [🔗](#class_BaseMaterial3D_property_subsurf_scatter_enabled) + + + +- `void` **set_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature)\ ) const + +If ``true``, subsurface scattering is enabled. Emulates light that penetrates an object's surface, is scattered, and then emerges. Subsurface scattering quality is controlled by [ProjectSettings.rendering/environment/subsurface_scattering/subsurface_scattering_quality](class_projectsettings.md#class_ProjectSettings_property_rendering/environment/subsurface_scattering/subsurface_scattering_quality). + +\ **Note:** Subsurface scattering is not supported on viewports that have a transparent background (where [Viewport.transparent_bg](class_viewport.md#class_Viewport_property_transparent_bg) is ``true``). + +
+ + + + + +[bool](class_bool.md) **subsurf_scatter_skin_mode** = `false` [🔗](#class_BaseMaterial3D_property_subsurf_scatter_skin_mode) + + + +- `void` **set_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const + +If ``true``, 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. + +
+ + + + + +[float](class_float.md) **subsurf_scatter_strength** = `0.0` [🔗](#class_BaseMaterial3D_property_subsurf_scatter_strength) + + + +- `void` **set_subsurface_scattering_strength**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_subsurface_scattering_strength**\ (\ ) + +The strength of the subsurface scattering effect. The depth of the effect is also controlled by [ProjectSettings.rendering/environment/subsurface_scattering/subsurface_scattering_scale](class_projectsettings.md#class_ProjectSettings_property_rendering/environment/subsurface_scattering/subsurface_scattering_scale), which is set globally. + +
+ + + + + +[Texture2D](class_texture2d.md) **subsurf_scatter_texture** [🔗](#class_BaseMaterial3D_property_subsurf_scatter_texture) + + + +- `void` **set_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam), texture\: [Texture2D](class_texture2d.md)\ ) +- [Texture2D](class_texture2d.md) **get_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam)\ ) const + +Texture used to control the subsurface scattering strength. Stored in the red texture channel. Multiplied by [subsurf_scatter_strength](class_basematerial3d.md#class_BaseMaterial3D_property_subsurf_scatter_strength). + +
+ + + + + +[float](class_float.md) **subsurf_scatter_transmittance_boost** = `0.0` [🔗](#class_BaseMaterial3D_property_subsurf_scatter_transmittance_boost) + + + +- `void` **set_transmittance_boost**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_transmittance_boost**\ (\ ) + +The intensity of the subsurface scattering transmittance effect. + +
+ + + + + +[Color](class_color.md) **subsurf_scatter_transmittance_color** = `Color(1, 1, 1, 1)` [🔗](#class_BaseMaterial3D_property_subsurf_scatter_transmittance_color) + + + +- `void` **set_transmittance_color**\ (\ value\: [Color](class_color.md)\ ) +- [Color](class_color.md) **get_transmittance_color**\ (\ ) + +The color to multiply the subsurface scattering transmittance effect with. Ignored if [subsurf_scatter_skin_mode](class_basematerial3d.md#class_BaseMaterial3D_property_subsurf_scatter_skin_mode) is ``true``. + +
+ + + + + +[float](class_float.md) **subsurf_scatter_transmittance_depth** = `0.1` [🔗](#class_BaseMaterial3D_property_subsurf_scatter_transmittance_depth) + + + +- `void` **set_transmittance_depth**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_transmittance_depth**\ (\ ) + +The depth of the subsurface scattering transmittance effect. + +
+ + + + + +[bool](class_bool.md) **subsurf_scatter_transmittance_enabled** = `false` [🔗](#class_BaseMaterial3D_property_subsurf_scatter_transmittance_enabled) + + + +- `void` **set_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature)\ ) const + +If ``true``, enables subsurface scattering transmittance. Only effective if [subsurf_scatter_enabled](class_basematerial3d.md#class_BaseMaterial3D_property_subsurf_scatter_enabled) is ``true``. See also [backlight_enabled](class_basematerial3d.md#class_BaseMaterial3D_property_backlight_enabled). + +
+ + + + + +[Texture2D](class_texture2d.md) **subsurf_scatter_transmittance_texture** [🔗](#class_BaseMaterial3D_property_subsurf_scatter_transmittance_texture) + + + +- `void` **set_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam), texture\: [Texture2D](class_texture2d.md)\ ) +- [Texture2D](class_texture2d.md) **get_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam)\ ) const + +The texture to use for multiplying the intensity of the subsurface scattering transmittance intensity. See also [subsurf_scatter_texture](class_basematerial3d.md#class_BaseMaterial3D_property_subsurf_scatter_texture). Ignored if [subsurf_scatter_skin_mode](class_basematerial3d.md#class_BaseMaterial3D_property_subsurf_scatter_skin_mode) is ``true``. + +
+ + + + + +[TextureFilter](class_basematerial3d.md#enum_BaseMaterial3D_TextureFilter) **texture_filter** = `3` [🔗](#class_BaseMaterial3D_property_texture_filter) + + + +- `void` **set_texture_filter**\ (\ value\: [TextureFilter](class_basematerial3d.md#enum_BaseMaterial3D_TextureFilter)\ ) +- [TextureFilter](class_basematerial3d.md#enum_BaseMaterial3D_TextureFilter) **get_texture_filter**\ (\ ) + +Filter flags for the texture. + +\ **Note:** [heightmap_texture](class_basematerial3d.md#class_BaseMaterial3D_property_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. + +
+ + + + + +[bool](class_bool.md) **texture_repeat** = `true` [🔗](#class_BaseMaterial3D_property_texture_repeat) + + + +- `void` **set_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const + +If ``true``, the texture repeats when exceeding the texture's size. See [FLAG_USE_TEXTURE_REPEAT](class_basematerial3d.md#class_BaseMaterial3D_constant_FLAG_USE_TEXTURE_REPEAT). + +
+ + + + + +[Transparency](class_basematerial3d.md#enum_BaseMaterial3D_Transparency) **transparency** = `0` [🔗](#class_BaseMaterial3D_property_transparency) + + + +- `void` **set_transparency**\ (\ value\: [Transparency](class_basematerial3d.md#enum_BaseMaterial3D_Transparency)\ ) +- [Transparency](class_basematerial3d.md#enum_BaseMaterial3D_Transparency) **get_transparency**\ (\ ) + +The material's transparency mode. Some transparency modes will disable shadow casting. Any transparency mode other than [TRANSPARENCY_DISABLED](class_basematerial3d.md#class_BaseMaterial3D_constant_TRANSPARENCY_DISABLED) has a greater performance impact compared to opaque rendering. See also [blend_mode](class_basematerial3d.md#class_BaseMaterial3D_property_blend_mode). + +
+ + + + + +[bool](class_bool.md) **use_fov_override** = `false` [🔗](#class_BaseMaterial3D_property_use_fov_override) + + + +- `void` **set_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const + +If ``true`` use [fov_override](class_basematerial3d.md#class_BaseMaterial3D_property_fov_override) to override the [Camera3D](class_camera3d.md)'s field of view angle. + +
+ + + + + +[bool](class_bool.md) **use_particle_trails** = `false` [🔗](#class_BaseMaterial3D_property_use_particle_trails) + + + +- `void` **set_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const + +If ``true``, enables parts of the shader required for [GPUParticles3D](class_gpuparticles3d.md) trails to function. This also requires using a mesh with appropriate skinning, such as [RibbonTrailMesh](class_ribbontrailmesh.md) or [TubeTrailMesh](class_tubetrailmesh.md). Enabling this feature outside of materials used in [GPUParticles3D](class_gpuparticles3d.md) meshes will break material rendering. + +
+ + + + + +[bool](class_bool.md) **use_point_size** = `false` [🔗](#class_BaseMaterial3D_property_use_point_size) + + + +- `void` **set_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const + +If ``true``, render point size can be changed. + +\ **Note:** This is only effective for objects whose geometry is point-based rather than triangle-based. See also [point_size](class_basematerial3d.md#class_BaseMaterial3D_property_point_size). + +
+ + + + + +[bool](class_bool.md) **use_z_clip_scale** = `false` [🔗](#class_BaseMaterial3D_property_use_z_clip_scale) + + + +- `void` **set_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const + +If ``true`` use [z_clip_scale](class_basematerial3d.md#class_BaseMaterial3D_property_z_clip_scale) to scale the object being rendered towards the camera to avoid clipping into things like walls. + +
+ + + + + +[Vector3](class_vector3.md) **uv1_offset** = `Vector3(0, 0, 0)` [🔗](#class_BaseMaterial3D_property_uv1_offset) + + + +- `void` **set_uv1_offset**\ (\ value\: [Vector3](class_vector3.md)\ ) +- [Vector3](class_vector3.md) **get_uv1_offset**\ (\ ) + +How much to offset the ``UV`` coordinates. This amount will be added to ``UV`` in the vertex function. This can be used to offset a texture. The Z component is used when [uv1_triplanar](class_basematerial3d.md#class_BaseMaterial3D_property_uv1_triplanar) is enabled, but it is not used anywhere else. + +
+ + + + + +[Vector3](class_vector3.md) **uv1_scale** = `Vector3(1, 1, 1)` [🔗](#class_BaseMaterial3D_property_uv1_scale) + + + +- `void` **set_uv1_scale**\ (\ value\: [Vector3](class_vector3.md)\ ) +- [Vector3](class_vector3.md) **get_uv1_scale**\ (\ ) + +How much to scale the ``UV`` coordinates. This is multiplied by ``UV`` in the vertex function. The Z component is used when [uv1_triplanar](class_basematerial3d.md#class_BaseMaterial3D_property_uv1_triplanar) is enabled, but it is not used anywhere else. + +
+ + + + + +[bool](class_bool.md) **uv1_triplanar** = `false` [🔗](#class_BaseMaterial3D_property_uv1_triplanar) + + + +- `void` **set_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const + +If ``true``, instead of using ``UV`` 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. + +
+ + + + + +[float](class_float.md) **uv1_triplanar_sharpness** = `1.0` [🔗](#class_BaseMaterial3D_property_uv1_triplanar_sharpness) + + + +- `void` **set_uv1_triplanar_blend_sharpness**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_uv1_triplanar_blend_sharpness**\ (\ ) + +A lower number blends the texture more softly while a higher number blends the texture more sharply. + +\ **Note:** [uv1_triplanar_sharpness](class_basematerial3d.md#class_BaseMaterial3D_property_uv1_triplanar_sharpness) is clamped between ``0.0`` and ``150.0`` (inclusive) as values outside that range can look broken depending on the mesh. + +
+ + + + + +[bool](class_bool.md) **uv1_world_triplanar** = `false` [🔗](#class_BaseMaterial3D_property_uv1_world_triplanar) + + + +- `void` **set_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const + +If ``true``, triplanar mapping for ``UV`` is calculated in world space rather than object local space. See also [uv1_triplanar](class_basematerial3d.md#class_BaseMaterial3D_property_uv1_triplanar). + +
+ + + + + +[Vector3](class_vector3.md) **uv2_offset** = `Vector3(0, 0, 0)` [🔗](#class_BaseMaterial3D_property_uv2_offset) + + + +- `void` **set_uv2_offset**\ (\ value\: [Vector3](class_vector3.md)\ ) +- [Vector3](class_vector3.md) **get_uv2_offset**\ (\ ) + +How much to offset the ``UV2`` coordinates. This amount will be added to ``UV2`` in the vertex function. This can be used to offset a texture. The Z component is used when [uv2_triplanar](class_basematerial3d.md#class_BaseMaterial3D_property_uv2_triplanar) is enabled, but it is not used anywhere else. + +
+ + + + + +[Vector3](class_vector3.md) **uv2_scale** = `Vector3(1, 1, 1)` [🔗](#class_BaseMaterial3D_property_uv2_scale) + + + +- `void` **set_uv2_scale**\ (\ value\: [Vector3](class_vector3.md)\ ) +- [Vector3](class_vector3.md) **get_uv2_scale**\ (\ ) + +How much to scale the ``UV2`` coordinates. This is multiplied by ``UV2`` in the vertex function. The Z component is used when [uv2_triplanar](class_basematerial3d.md#class_BaseMaterial3D_property_uv2_triplanar) is enabled, but it is not used anywhere else. + +
+ + + + + +[bool](class_bool.md) **uv2_triplanar** = `false` [🔗](#class_BaseMaterial3D_property_uv2_triplanar) + + + +- `void` **set_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const + +If ``true``, instead of using ``UV2`` 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. + +
+ + + + + +[float](class_float.md) **uv2_triplanar_sharpness** = `1.0` [🔗](#class_BaseMaterial3D_property_uv2_triplanar_sharpness) + + + +- `void` **set_uv2_triplanar_blend_sharpness**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_uv2_triplanar_blend_sharpness**\ (\ ) + +A lower number blends the texture more softly while a higher number blends the texture more sharply. + +\ **Note:** [uv2_triplanar_sharpness](class_basematerial3d.md#class_BaseMaterial3D_property_uv2_triplanar_sharpness) is clamped between ``0.0`` and ``150.0`` (inclusive) as values outside that range can look broken depending on the mesh. + +
+ + + + + +[bool](class_bool.md) **uv2_world_triplanar** = `false` [🔗](#class_BaseMaterial3D_property_uv2_world_triplanar) + + + +- `void` **set_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const + +If ``true``, triplanar mapping for ``UV2`` is calculated in world space rather than object local space. See also [uv2_triplanar](class_basematerial3d.md#class_BaseMaterial3D_property_uv2_triplanar). + +
+ + + + + +[bool](class_bool.md) **vertex_color_is_srgb** = `false` [🔗](#class_BaseMaterial3D_property_vertex_color_is_srgb) + + + +- `void` **set_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const + +If ``true``, vertex colors are considered to be stored in sRGB color space and are converted to linear color space during rendering. If ``false``, vertex colors are considered to be stored in linear color space and are rendered as-is. See also [albedo_texture_force_srgb](class_basematerial3d.md#class_BaseMaterial3D_property_albedo_texture_force_srgb). + +\ **Note:** Only effective when using the Forward+ and Mobile rendering methods, not Compatibility. + +
+ + + + + +[bool](class_bool.md) **vertex_color_use_as_albedo** = `false` [🔗](#class_BaseMaterial3D_property_vertex_color_use_as_albedo) + + + +- `void` **set_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const + +If ``true``, the vertex color is used as albedo color. + +
+ + + + + +[float](class_float.md) **z_clip_scale** = `1.0` [🔗](#class_BaseMaterial3D_property_z_clip_scale) + + + +- `void` **set_z_clip_scale**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_z_clip_scale**\ (\ ) + +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 ``1.0`` as possible. + +
+ + + +## Method Descriptions + + + + + +[bool](class_bool.md) **get_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature)\ ) const [🔗](#class_BaseMaterial3D_method_get_feature) + +Returns ``true``, if the specified [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature) is enabled. + +
+ + + + + +[bool](class_bool.md) **get_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags)\ ) const [🔗](#class_BaseMaterial3D_method_get_flag) + +Returns ``true`` if the specified flag is enabled. + +
+ + + + + +[Texture2D](class_texture2d.md) **get_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam)\ ) const [🔗](#class_BaseMaterial3D_method_get_texture) + +Returns the [Texture2D](class_texture2d.md) associated with the specified [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam). + +
+ + + + + +`void` **set_feature**\ (\ feature\: [Feature](class_basematerial3d.md#enum_BaseMaterial3D_Feature), enable\: [bool](class_bool.md)\ ) [🔗](#class_BaseMaterial3D_method_set_feature) + +If ``true``, enables the specified [Feature](class_basematerial3d.md#enum_BaseMaterial3D_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 ``true``. + +
+ + + + + +`void` **set_flag**\ (\ flag\: [Flags](class_basematerial3d.md#enum_BaseMaterial3D_Flags), enable\: [bool](class_bool.md)\ ) [🔗](#class_BaseMaterial3D_method_set_flag) + +If ``true``, 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 ``true``. + +
+ + + + + +`void` **set_texture**\ (\ param\: [TextureParam](class_basematerial3d.md#enum_BaseMaterial3D_TextureParam), texture\: [Texture2D](class_texture2d.md)\ ) [🔗](#class_BaseMaterial3D_method_set_texture) + +Sets the texture for the slot specified by `param`. + diff --git a/docs/Classes/class_basis.md b/docs/Classes/class_basis.md new file mode 100644 index 00000000..551c42d0 --- /dev/null +++ b/docs/Classes/class_basis.md @@ -0,0 +1,1016 @@ + + + + + + + + + +# Basis + +A 3×3 matrix for representing 3D rotation and scale. + + + +## Description + +The **Basis** built-in [Variant](class_variant.md) type is a 3×3 [matrix](https://en.wikipedia.org/wiki/Matrix_(mathematics)) used to represent 3D rotation, scale, and shear. It is frequently used within a [Transform3D](class_transform3d.md). + +A **Basis** is composed by 3 axis vectors, each representing a column of the matrix: [x](class_basis.md#class_Basis_property_x), [y](class_basis.md#class_Basis_property_y), and [z](class_basis.md#class_Basis_property_z). The length of each axis ([Vector3.length()](class_vector3.md#class_Vector3_method_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: + +- **Orthogonal** if its axes are perpendicular to each other. + +- **Normalized** if the length of every axis is ``1.0``. + +- **Uniform** if all axes share the same length (see [get_scale()](class_basis.md#class_Basis_method_get_scale)). + +- **Orthonormal** if it is both orthogonal and normalized, which allows it to only represent rotations (see [orthonormalized()](class_basis.md#class_Basis_method_orthonormalized)). + +- **Conformal** if it is both orthogonal and uniform, which ensures it is not distorted. + +For a general introduction, see the [Matrices and transforms](../tutorials/math/matrices_and_transforms.md) tutorial. + +\ **Note:** Redot uses a [right-handed coordinate system](https://en.wikipedia.org/wiki/Right-hand_rule), which is a common standard. For directions, the convention for built-in types like [Camera3D](class_camera3d.md) 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 [3D asset direction conventions](../tutorials/assets_pipeline/importing_3d_scenes/model_export_considerations.md#d-asset-direction-conventions) tutorial. + +\ **Note:** The basis matrices are exposed as [column-major](https://www.mindcontrol.org/~hplus/graphics/matrix-layout.html) order, which is the same as OpenGL. However, they are stored internally in row-major order, which is the same as DirectX. + +
+There are notable differences when using this API with C#. See the C# differences documentation for more information. + +
+ + + +## Tutorials + +- [Math documentation index](../tutorials/math/index.md) + +- [Matrices and transforms](../tutorials/math/matrices_and_transforms.md) + +- [Using 3D transforms](../tutorials/3d/using_transforms.md) + +- [Matrix Transform Demo](https://godotengine.org/asset-library/asset/2787) + +- [3D Platformer Demo](https://godotengine.org/asset-library/asset/2748) + +- [3D Voxel Demo](https://godotengine.org/asset-library/asset/2755) + +- [2.5D Game Demo](https://godotengine.org/asset-library/asset/2783) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + +
[Vector3](class_vector3.md)[x](#class_Basis_property_x)`Vector3(1, 0, 0)`
[Vector3](class_vector3.md)[y](#class_Basis_property_y)`Vector3(0, 1, 0)`
[Vector3](class_vector3.md)[z](#class_Basis_property_z)`Vector3(0, 0, 1)`
+ + + +## Constructors + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Basis](class_basis.md)[Basis](#class_Basis_constructor_Basis)\ (\ )
[Basis](class_basis.md)[Basis](#class_Basis_constructor_Basis)\ (\ from\: [Basis](class_basis.md)\ )
[Basis](class_basis.md)[Basis](#class_Basis_constructor_Basis)\ (\ axis\: [Vector3](class_vector3.md), angle\: [float](class_float.md)\ )
[Basis](class_basis.md)[Basis](#class_Basis_constructor_Basis)\ (\ from\: [Quaternion](class_quaternion.md)\ )
[Basis](class_basis.md)[Basis](#class_Basis_constructor_Basis)\ (\ x_axis\: [Vector3](class_vector3.md), y_axis\: [Vector3](class_vector3.md), z_axis\: [Vector3](class_vector3.md)\ )
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[determinant](#class_Basis_method_determinant)\ (\ ) const
[Basis](class_basis.md)[from_euler](#class_Basis_method_from_euler)\ (\ euler\: [Vector3](class_vector3.md), order\: [int](class_int.md) = 2\ ) static
[Basis](class_basis.md)[from_scale](#class_Basis_method_from_scale)\ (\ scale\: [Vector3](class_vector3.md)\ ) static
[Vector3](class_vector3.md)[get_euler](#class_Basis_method_get_euler)\ (\ order\: [int](class_int.md) = 2\ ) const
[Quaternion](class_quaternion.md)[get_rotation_quaternion](#class_Basis_method_get_rotation_quaternion)\ (\ ) const
[Vector3](class_vector3.md)[get_scale](#class_Basis_method_get_scale)\ (\ ) const
[Basis](class_basis.md)[inverse](#class_Basis_method_inverse)\ (\ ) const
[bool](class_bool.md)[is_conformal](#class_Basis_method_is_conformal)\ (\ ) const
[bool](class_bool.md)[is_equal_approx](#class_Basis_method_is_equal_approx)\ (\ b\: [Basis](class_basis.md)\ ) const
[bool](class_bool.md)[is_finite](#class_Basis_method_is_finite)\ (\ ) const
[Basis](class_basis.md)[looking_at](#class_Basis_method_looking_at)\ (\ target\: [Vector3](class_vector3.md), up\: [Vector3](class_vector3.md) = Vector3(0, 1, 0), use_model_front\: [bool](class_bool.md) = false\ ) static
[Basis](class_basis.md)[orthonormalized](#class_Basis_method_orthonormalized)\ (\ ) const
[Basis](class_basis.md)[rotated](#class_Basis_method_rotated)\ (\ axis\: [Vector3](class_vector3.md), angle\: [float](class_float.md)\ ) const
[Basis](class_basis.md)[scaled](#class_Basis_method_scaled)\ (\ scale\: [Vector3](class_vector3.md)\ ) const
[Basis](class_basis.md)[scaled_local](#class_Basis_method_scaled_local)\ (\ scale\: [Vector3](class_vector3.md)\ ) const
[Basis](class_basis.md)[slerp](#class_Basis_method_slerp)\ (\ to\: [Basis](class_basis.md), weight\: [float](class_float.md)\ ) const
[float](class_float.md)[tdotx](#class_Basis_method_tdotx)\ (\ with\: [Vector3](class_vector3.md)\ ) const
[float](class_float.md)[tdoty](#class_Basis_method_tdoty)\ (\ with\: [Vector3](class_vector3.md)\ ) const
[float](class_float.md)[tdotz](#class_Basis_method_tdotz)\ (\ with\: [Vector3](class_vector3.md)\ ) const
[Basis](class_basis.md)[transposed](#class_Basis_method_transposed)\ (\ ) const
+ + + +## Operators + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[operator !=](#class_Basis_operator_neq_Basis)\ (\ right\: [Basis](class_basis.md)\ )
[Basis](class_basis.md)[operator *](#class_Basis_operator_mul_Basis)\ (\ right\: [Basis](class_basis.md)\ )
[Vector3](class_vector3.md)[operator *](#class_Basis_operator_mul_Vector3)\ (\ right\: [Vector3](class_vector3.md)\ )
[Basis](class_basis.md)[operator *](#class_Basis_operator_mul_float)\ (\ right\: [float](class_float.md)\ )
[Basis](class_basis.md)[operator *](#class_Basis_operator_mul_int)\ (\ right\: [int](class_int.md)\ )
[Basis](class_basis.md)[operator /](#class_Basis_operator_div_float)\ (\ right\: [float](class_float.md)\ )
[Basis](class_basis.md)[operator /](#class_Basis_operator_div_int)\ (\ right\: [int](class_int.md)\ )
[bool](class_bool.md)[operator ==](#class_Basis_operator_eq_Basis)\ (\ right\: [Basis](class_basis.md)\ )
[Vector3](class_vector3.md)[operator []](#class_Basis_operator_idx_int)\ (\ index\: [int](class_int.md)\ )
+ +
+ + + +## Constants + + + + + +**IDENTITY** = `Basis(1, 0, 0, 0, 1, 0, 0, 0, 1)` [🔗](#class_Basis_constant_IDENTITY) + +The identity **Basis**. This is an orthonormal basis with no rotation, no shear, and a scale of [Vector3.ONE](class_vector3.md#class_Vector3_constant_ONE). This also means that: + +- The [x](class_basis.md#class_Basis_property_x) points right ([Vector3.RIGHT](class_vector3.md#class_Vector3_constant_RIGHT)); + +- The [y](class_basis.md#class_Basis_property_y) points up ([Vector3.UP](class_vector3.md#class_Vector3_constant_UP)); + +- The [z](class_basis.md#class_Basis_property_z) points back ([Vector3.BACK](class_vector3.md#class_Vector3_constant_BACK)). + +``` + 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 +``` + +If a [Vector3](class_vector3.md) or another **Basis** is transformed (multiplied) by this constant, no transformation occurs. + +\ **Note:** In GDScript, this constant is equivalent to creating a [Basis](class_basis.md#class_Basis_constructor_Basis) without any arguments. It can be used to make your code clearer, and for consistency with C#. + + + + + +**FLIP_X** = `Basis(-1, 0, 0, 0, 1, 0, 0, 0, 1)` [🔗](#class_Basis_constant_FLIP_X) + +When any basis is multiplied by [FLIP_X](class_basis.md#class_Basis_constant_FLIP_X), it negates all components of the [x](class_basis.md#class_Basis_property_x) axis (the X column). + +When [FLIP_X](class_basis.md#class_Basis_constant_FLIP_X) is multiplied by any basis, it negates the [Vector3.x](class_vector3.md#class_Vector3_property_x) component of all axes (the X row). + + + + + +**FLIP_Y** = `Basis(1, 0, 0, 0, -1, 0, 0, 0, 1)` [🔗](#class_Basis_constant_FLIP_Y) + +When any basis is multiplied by [FLIP_Y](class_basis.md#class_Basis_constant_FLIP_Y), it negates all components of the [y](class_basis.md#class_Basis_property_y) axis (the Y column). + +When [FLIP_Y](class_basis.md#class_Basis_constant_FLIP_Y) is multiplied by any basis, it negates the [Vector3.y](class_vector3.md#class_Vector3_property_y) component of all axes (the Y row). + + + + + +**FLIP_Z** = `Basis(1, 0, 0, 0, 1, 0, 0, 0, -1)` [🔗](#class_Basis_constant_FLIP_Z) + +When any basis is multiplied by [FLIP_Z](class_basis.md#class_Basis_constant_FLIP_Z), it negates all components of the [z](class_basis.md#class_Basis_property_z) axis (the Z column). + +When [FLIP_Z](class_basis.md#class_Basis_constant_FLIP_Z) is multiplied by any basis, it negates the [Vector3.z](class_vector3.md#class_Vector3_property_z) component of all axes (the Z row). + +
+ + + +## Property Descriptions + + + + + +[Vector3](class_vector3.md) **x** = `Vector3(1, 0, 0)` [🔗](#class_Basis_property_x) + +The basis's X axis, and the column ``0`` of the matrix. + +On the identity basis, this vector points right ([Vector3.RIGHT](class_vector3.md#class_Vector3_constant_RIGHT)). + +
+ + + + + +[Vector3](class_vector3.md) **y** = `Vector3(0, 1, 0)` [🔗](#class_Basis_property_y) + +The basis's Y axis, and the column ``1`` of the matrix. + +On the identity basis, this vector points up ([Vector3.UP](class_vector3.md#class_Vector3_constant_UP)). + +
+ + + + + +[Vector3](class_vector3.md) **z** = `Vector3(0, 0, 1)` [🔗](#class_Basis_property_z) + +The basis's Z axis, and the column ``2`` of the matrix. + +On the identity basis, this vector points back ([Vector3.BACK](class_vector3.md#class_Vector3_constant_BACK)). + +
+ + + +## Constructor Descriptions + + + + + +[Basis](class_basis.md) **Basis**\ (\ ) [🔗](#class_Basis_constructor_Basis) + +Constructs a **Basis** identical to [IDENTITY](class_basis.md#class_Basis_constant_IDENTITY). + +\ **Note:** In C#, this constructs a **Basis** with all of its components set to [Vector3.ZERO](class_vector3.md#class_Vector3_constant_ZERO). + +
+ + + +[Basis](class_basis.md) **Basis**\ (\ from\: [Basis](class_basis.md)\ ) + +Constructs a **Basis** as a copy of the given **Basis**. + +
+ + + +[Basis](class_basis.md) **Basis**\ (\ axis\: [Vector3](class_vector3.md), angle\: [float](class_float.md)\ ) + +Constructs a **Basis** that only represents rotation, rotated around the `axis` by the given `angle`, in radians. The axis must be a normalized vector. + +\ **Note:** This is the same as using [rotated()](class_basis.md#class_Basis_method_rotated) on the [IDENTITY](class_basis.md#class_Basis_constant_IDENTITY) basis. With more than one angle consider using [from_euler()](class_basis.md#class_Basis_method_from_euler), instead. + +
+ + + +[Basis](class_basis.md) **Basis**\ (\ from\: [Quaternion](class_quaternion.md)\ ) + +Constructs a **Basis** that only represents rotation from the given [Quaternion](class_quaternion.md). + +\ **Note:** Quaternions *only* store rotation, not scale. Because of this, conversions from **Basis** to [Quaternion](class_quaternion.md) cannot always be reversed. + +
+ + + +[Basis](class_basis.md) **Basis**\ (\ x_axis\: [Vector3](class_vector3.md), y_axis\: [Vector3](class_vector3.md), z_axis\: [Vector3](class_vector3.md)\ ) + +Constructs a **Basis** from 3 axis vectors. These are the columns of the basis matrix. + +
+ + + +## Method Descriptions + + + + + +[float](class_float.md) **determinant**\ (\ ) const [🔗](#class_Basis_method_determinant) + +Returns the [determinant](https://en.wikipedia.org/wiki/Determinant) of this basis's matrix. For advanced math, this number can be used to determine a few attributes: + +- If the determinant is exactly ``0.0``, the basis is not invertible (see [inverse()](class_basis.md#class_Basis_method_inverse)). + +- If the determinant is a negative number, the basis represents a negative scale. + +\ **Note:** If the basis's scale is the same for every axis, its determinant is always that scale by the power of 3. + +
+ + + + + +[Basis](class_basis.md) **from_euler**\ (\ euler\: [Vector3](class_vector3.md), order\: [int](class_int.md) = 2\ ) static [🔗](#class_Basis_method_from_euler) + +Constructs a new **Basis** that only represents rotation from the given [Vector3](class_vector3.md) of [Euler angles](https://en.wikipedia.org/wiki/Euler_angles), in radians. + +- The [Vector3.x](class_vector3.md#class_Vector3_property_x) should contain the angle around the [x](class_basis.md#class_Basis_property_x) axis (pitch); + +- The [Vector3.y](class_vector3.md#class_Vector3_property_y) should contain the angle around the [y](class_basis.md#class_Basis_property_y) axis (yaw); + +- The [Vector3.z](class_vector3.md#class_Vector3_property_z) should contain the angle around the [z](class_basis.md#class_Basis_property_z) axis (roll). + + + + +```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) +``` + +```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) +``` + + + +The order of each consecutive rotation can be changed with `order` (see [EulerOrder](class_@globalscope.md#enum_@GlobalScope_EulerOrder) constants). By default, the YXZ convention is used ([@GlobalScope.EULER_ORDER_YXZ](class_@globalscope.md#class_@GlobalScope_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 [get_euler()](class_basis.md#class_Basis_method_get_euler), this order is reversed. + +
+ + + + + +[Basis](class_basis.md) **from_scale**\ (\ scale\: [Vector3](class_vector3.md)\ ) static [🔗](#class_Basis_method_from_scale) + +Constructs a new **Basis** that only represents scale, with no rotation or shear, from the given `scale` vector. + + + + +```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) +``` + +```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) +``` + + + +\ **Note:** In linear algebra, the matrix of this basis is also known as a [diagonal matrix](https://en.wikipedia.org/wiki/Diagonal_matrix). + +
+ + + + + +[Vector3](class_vector3.md) **get_euler**\ (\ order\: [int](class_int.md) = 2\ ) const [🔗](#class_Basis_method_get_euler) + +Returns this basis's rotation as a [Vector3](class_vector3.md) of [Euler angles](https://en.wikipedia.org/wiki/Euler_angles), in radians. For the returned value: + +- The [Vector3.x](class_vector3.md#class_Vector3_property_x) contains the angle around the [x](class_basis.md#class_Basis_property_x) axis (pitch); + +- The [Vector3.y](class_vector3.md#class_Vector3_property_y) contains the angle around the [y](class_basis.md#class_Basis_property_y) axis (yaw); + +- The [Vector3.z](class_vector3.md#class_Vector3_property_z) contains the angle around the [z](class_basis.md#class_Basis_property_z) axis (roll). + +The order of each consecutive rotation can be changed with `order` (see [EulerOrder](class_@globalscope.md#enum_@GlobalScope_EulerOrder) constants). By default, the YXZ convention is used ([@GlobalScope.EULER_ORDER_YXZ](class_@globalscope.md#class_@GlobalScope_constant_EULER_ORDER_YXZ)): Z (roll) is calculated first, then X (pitch), and lastly Y (yaw). When using the opposite method [from_euler()](class_basis.md#class_Basis_method_from_euler), this order is reversed. + +\ **Note:** For this method to return correctly, the basis needs to be *orthonormal* (see [orthonormalized()](class_basis.md#class_Basis_method_orthonormalized)). + +\ **Note:** Euler angles are much more intuitive but are not suitable for 3D math. Because of this, consider using the [get_rotation_quaternion()](class_basis.md#class_Basis_method_get_rotation_quaternion) method instead, which returns a [Quaternion](class_quaternion.md). + +\ **Note:** In the Inspector dock, a basis's rotation is often displayed in Euler angles (in degrees), as is the case with the [Node3D.rotation](class_node3d.md#class_Node3D_property_rotation) property. + +
+ + + + + +[Quaternion](class_quaternion.md) **get_rotation_quaternion**\ (\ ) const [🔗](#class_Basis_method_get_rotation_quaternion) + +Returns this basis's rotation as a [Quaternion](class_quaternion.md). + +\ **Note:** Quaternions are much more suitable for 3D math but are less intuitive. For user interfaces, consider using the [get_euler()](class_basis.md#class_Basis_method_get_euler) method, which returns Euler angles. + +
+ + + + + +[Vector3](class_vector3.md) **get_scale**\ (\ ) const [🔗](#class_Basis_method_get_scale) + +Returns the length of each axis of this basis, as a [Vector3](class_vector3.md). If the basis is not sheared, this value is the scaling factor. It is not affected by rotation. + + + + +```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) +``` + +```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) +``` + + + +\ **Note:** If the value returned by [determinant()](class_basis.md#class_Basis_method_determinant) is negative, the scale is also negative. + +
+ + + + + +[Basis](class_basis.md) **inverse**\ (\ ) const [🔗](#class_Basis_method_inverse) + +Returns the [inverse of this basis's matrix](https://en.wikipedia.org/wiki/Invertible_matrix). + +
+ + + + + +[bool](class_bool.md) **is_conformal**\ (\ ) const [🔗](#class_Basis_method_is_conformal) + +Returns ``true`` if this basis is conformal. A conformal basis is both *orthogonal* (the axes are perpendicular to each other) and *uniform* (the axes share the same length). This method can be especially useful during physics calculations. + +
+ + + + + +[bool](class_bool.md) **is_equal_approx**\ (\ b\: [Basis](class_basis.md)\ ) const [🔗](#class_Basis_method_is_equal_approx) + +Returns ``true`` if this basis and `b` are approximately equal, by calling [@GlobalScope.is_equal_approx()](class_@globalscope.md#class_@GlobalScope_method_is_equal_approx) on all vector components. + +
+ + + + + +[bool](class_bool.md) **is_finite**\ (\ ) const [🔗](#class_Basis_method_is_finite) + +Returns ``true`` if this basis is finite, by calling [@GlobalScope.is_finite()](class_@globalscope.md#class_@GlobalScope_method_is_finite) on all vector components. + +
+ + + + + +[Basis](class_basis.md) **looking_at**\ (\ target\: [Vector3](class_vector3.md), up\: [Vector3](class_vector3.md) = Vector3(0, 1, 0), use_model_front\: [bool](class_bool.md) = false\ ) static [🔗](#class_Basis_method_looking_at) + +Creates a new **Basis** with a rotation such that the forward axis (-Z) points towards the `target` position. + +By default, the -Z axis (camera forward) is treated as forward (implies +X is right). If `use_model_front` is ``true``, the +Z axis (asset front) is treated as forward (implies +X is left) and points toward the `target` position. + +The up axis (+Y) points as close to the `up` vector as possible while staying perpendicular to the forward axis. The returned basis is orthonormalized (see [orthonormalized()](class_basis.md#class_Basis_method_orthonormalized)). + +The `target` and the `up` cannot be [Vector3.ZERO](class_vector3.md#class_Vector3_constant_ZERO), and shouldn't be colinear to avoid unintended rotation around local Z axis. + +
+ + + + + +[Basis](class_basis.md) **orthonormalized**\ (\ ) const [🔗](#class_Basis_method_orthonormalized) + +Returns the orthonormalized version of this basis. An orthonormal basis is both *orthogonal* (the axes are perpendicular to each other) and *normalized* (the axes have a length of ``1.0``), 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: + + + + +```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() +``` + +```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(); + } +``` + + + +
+ + + + + +[Basis](class_basis.md) **rotated**\ (\ axis\: [Vector3](class_vector3.md), angle\: [float](class_float.md)\ ) const [🔗](#class_Basis_method_rotated) + +Returns a copy of this basis rotated around the given `axis` by the given `angle` (in radians). + +The `axis` must be a normalized vector (see [Vector3.normalized()](class_vector3.md#class_Vector3_method_normalized)). If `angle` is positive, the basis is rotated counter-clockwise around the axis. + + + + +```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). +``` + +```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). +``` + + + +
+ + + + + +[Basis](class_basis.md) **scaled**\ (\ scale\: [Vector3](class_vector3.md)\ ) const [🔗](#class_Basis_method_scaled) + +Returns this basis with each axis's components scaled by the given `scale`'s components. + +The basis matrix's rows are multiplied by `scale`'s components. This operation is a global scale (relative to the parent). + + + + +```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) +``` + +```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) +``` + + + +
+ + + + + +[Basis](class_basis.md) **scaled_local**\ (\ scale\: [Vector3](class_vector3.md)\ ) const [🔗](#class_Basis_method_scaled_local) + +Returns this basis with each axis scaled by the corresponding component in the given `scale`. + +The basis matrix's columns are multiplied by `scale`'s components. This operation is a local scale (relative to self). + + + + +```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) +``` + +```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) +``` + + + +
+ + + + + +[Basis](class_basis.md) **slerp**\ (\ to\: [Basis](class_basis.md), weight\: [float](class_float.md)\ ) const [🔗](#class_Basis_method_slerp) + +Performs a spherical-linear interpolation with the `to` basis, given a `weight`. Both this basis and `to` should represent a rotation. + +\ **Example:** Smoothly rotate a [Node3D](class_node3d.md) to the target basis over time, with a [Tween](class_tween.md): + +``` + 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) +``` + +
+ + + + + +[float](class_float.md) **tdotx**\ (\ with\: [Vector3](class_vector3.md)\ ) const [🔗](#class_Basis_method_tdotx) + +Returns the transposed dot product between `with` and the [x](class_basis.md#class_Basis_property_x) axis (see [transposed()](class_basis.md#class_Basis_method_transposed)). + +This is equivalent to ``basis.x.dot(vector)``. + +
+ + + + + +[float](class_float.md) **tdoty**\ (\ with\: [Vector3](class_vector3.md)\ ) const [🔗](#class_Basis_method_tdoty) + +Returns the transposed dot product between `with` and the [y](class_basis.md#class_Basis_property_y) axis (see [transposed()](class_basis.md#class_Basis_method_transposed)). + +This is equivalent to ``basis.y.dot(vector)``. + +
+ + + + + +[float](class_float.md) **tdotz**\ (\ with\: [Vector3](class_vector3.md)\ ) const [🔗](#class_Basis_method_tdotz) + +Returns the transposed dot product between `with` and the [z](class_basis.md#class_Basis_property_z) axis (see [transposed()](class_basis.md#class_Basis_method_transposed)). + +This is equivalent to ``basis.z.dot(vector)``. + +
+ + + + + +[Basis](class_basis.md) **transposed**\ (\ ) const [🔗](#class_Basis_method_transposed) + +Returns the transposed version of this basis. This turns the basis matrix's columns into rows, and its rows into columns. + + + + +```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) +``` + +```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) +``` + + + +
+ + + +## Operator Descriptions + + + + + +[bool](class_bool.md) **operator !=**\ (\ right\: [Basis](class_basis.md)\ ) [🔗](#class_Basis_operator_neq_Basis) + +Returns ``true`` if the components of both **Basis** matrices are not equal. + +\ **Note:** Due to floating-point precision errors, consider using [is_equal_approx()](class_basis.md#class_Basis_method_is_equal_approx) instead, which is more reliable. + +
+ + + + + +[Basis](class_basis.md) **operator ***\ (\ right\: [Basis](class_basis.md)\ ) [🔗](#class_Basis_operator_mul_Basis) + +Transforms (multiplies) the `right` basis by this basis. + +This is the operation performed between parent and child [Node3D](class_node3d.md)\ s. + +
+ + + + + +[Vector3](class_vector3.md) **operator ***\ (\ right\: [Vector3](class_vector3.md)\ ) [🔗](#class_Basis_operator_mul_Vector3) + +Transforms (multiplies) the `right` vector by this basis, returning a [Vector3](class_vector3.md). + + + + +```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) +``` + +```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) +``` + + + +
+ + + + + +[Basis](class_basis.md) **operator ***\ (\ right\: [float](class_float.md)\ ) [🔗](#class_Basis_operator_mul_float) + +Multiplies all components of the **Basis** by the given [float](class_float.md). This affects the basis's scale uniformly, resizing all 3 axes by the `right` value. + +
+ + + + + +[Basis](class_basis.md) **operator ***\ (\ right\: [int](class_int.md)\ ) [🔗](#class_Basis_operator_mul_int) + +Multiplies all components of the **Basis** by the given [int](class_int.md). This affects the basis's scale uniformly, resizing all 3 axes by the `right` value. + +
+ + + + + +[Basis](class_basis.md) **operator /**\ (\ right\: [float](class_float.md)\ ) [🔗](#class_Basis_operator_div_float) + +Divides all components of the **Basis** by the given [float](class_float.md). This affects the basis's scale uniformly, resizing all 3 axes by the `right` value. + +
+ + + + + +[Basis](class_basis.md) **operator /**\ (\ right\: [int](class_int.md)\ ) [🔗](#class_Basis_operator_div_int) + +Divides all components of the **Basis** by the given [int](class_int.md). This affects the basis's scale uniformly, resizing all 3 axes by the `right` value. + +
+ + + + + +[bool](class_bool.md) **operator ==**\ (\ right\: [Basis](class_basis.md)\ ) [🔗](#class_Basis_operator_eq_Basis) + +Returns ``true`` if the components of both **Basis** matrices are exactly equal. + +\ **Note:** Due to floating-point precision errors, consider using [is_equal_approx()](class_basis.md#class_Basis_method_is_equal_approx) instead, which is more reliable. + +
+ + + + + +[Vector3](class_vector3.md) **operator []**\ (\ index\: [int](class_int.md)\ ) [🔗](#class_Basis_operator_idx_int) + +Accesses each axis (column) of this basis by their index. Index ``0`` is the same as [x](class_basis.md#class_Basis_property_x), index ``1`` is the same as [y](class_basis.md#class_Basis_property_y), and index ``2`` is the same as [z](class_basis.md#class_Basis_property_z). + +\ **Note:** In C++, this operator accesses the rows of the basis matrix, *not* the columns. For the same behavior as scripting languages, use the ``set_column`` and ``get_column`` methods. + diff --git a/docs/Classes/class_bitmap.md b/docs/Classes/class_bitmap.md new file mode 100644 index 00000000..a83d5493 --- /dev/null +++ b/docs/Classes/class_bitmap.md @@ -0,0 +1,226 @@ + + + + + + + + + +# BitMap + +**Inherits:** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Boolean matrix. + + + +## 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. + + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Image](class_image.md)[convert_to_image](#class_BitMap_method_convert_to_image)\ (\ ) const
`void`[create](#class_BitMap_method_create)\ (\ size\: [Vector2i](class_vector2i.md)\ )
`void`[create_from_image_alpha](#class_BitMap_method_create_from_image_alpha)\ (\ image\: [Image](class_image.md), threshold\: [float](class_float.md) = 0.1\ )
[bool](class_bool.md)[get_bit](#class_BitMap_method_get_bit)\ (\ x\: [int](class_int.md), y\: [int](class_int.md)\ ) const
[bool](class_bool.md)[get_bitv](#class_BitMap_method_get_bitv)\ (\ position\: [Vector2i](class_vector2i.md)\ ) const
[Vector2i](class_vector2i.md)[get_size](#class_BitMap_method_get_size)\ (\ ) const
[int](class_int.md)[get_true_bit_count](#class_BitMap_method_get_true_bit_count)\ (\ ) const
`void`[grow_mask](#class_BitMap_method_grow_mask)\ (\ pixels\: [int](class_int.md), rect\: [Rect2i](class_rect2i.md)\ )
[Array](class_array.md)\[[PackedVector2Array](class_packedvector2array.md)\][opaque_to_polygons](#class_BitMap_method_opaque_to_polygons)\ (\ rect\: [Rect2i](class_rect2i.md), epsilon\: [float](class_float.md) = 2.0\ ) const
`void`[resize](#class_BitMap_method_resize)\ (\ new_size\: [Vector2i](class_vector2i.md)\ )
`void`[set_bit](#class_BitMap_method_set_bit)\ (\ x\: [int](class_int.md), y\: [int](class_int.md), bit\: [bool](class_bool.md)\ )
`void`[set_bit_rect](#class_BitMap_method_set_bit_rect)\ (\ rect\: [Rect2i](class_rect2i.md), bit\: [bool](class_bool.md)\ )
`void`[set_bitv](#class_BitMap_method_set_bitv)\ (\ position\: [Vector2i](class_vector2i.md), bit\: [bool](class_bool.md)\ )
+ +
+ + + +## Method Descriptions + + + + + +[Image](class_image.md) **convert_to_image**\ (\ ) const [🔗](#class_BitMap_method_convert_to_image) + +Returns an image of the same size as the bitmap and with an [Format](class_image.md#enum_Image_Format) of type [Image.FORMAT_L8](class_image.md#class_Image_constant_FORMAT_L8). ``true`` bits of the bitmap are being converted into white pixels, and ``false`` bits into black. + +
+ + + + + +`void` **create**\ (\ size\: [Vector2i](class_vector2i.md)\ ) [🔗](#class_BitMap_method_create) + +Creates a bitmap with the specified size, filled with ``false``. + +
+ + + + + +`void` **create_from_image_alpha**\ (\ image\: [Image](class_image.md), threshold\: [float](class_float.md) = 0.1\ ) [🔗](#class_BitMap_method_create_from_image_alpha) + +Creates a bitmap that matches the given image dimensions, every element of the bitmap is set to ``false`` if the alpha value of the image at that position is equal to `threshold` or less, and ``true`` in other case. + +
+ + + + + +[bool](class_bool.md) **get_bit**\ (\ x\: [int](class_int.md), y\: [int](class_int.md)\ ) const [🔗](#class_BitMap_method_get_bit) + +Returns bitmap's value at the specified position. + +
+ + + + + +[bool](class_bool.md) **get_bitv**\ (\ position\: [Vector2i](class_vector2i.md)\ ) const [🔗](#class_BitMap_method_get_bitv) + +Returns bitmap's value at the specified position. + +
+ + + + + +[Vector2i](class_vector2i.md) **get_size**\ (\ ) const [🔗](#class_BitMap_method_get_size) + +Returns bitmap's dimensions. + +
+ + + + + +[int](class_int.md) **get_true_bit_count**\ (\ ) const [🔗](#class_BitMap_method_get_true_bit_count) + +Returns the number of bitmap elements that are set to ``true``. + +
+ + + + + +`void` **grow_mask**\ (\ pixels\: [int](class_int.md), rect\: [Rect2i](class_rect2i.md)\ ) [🔗](#class_BitMap_method_grow_mask) + +Applies morphological dilation or erosion to the bitmap. If `pixels` is positive, dilation is applied to the bitmap. If `pixels` is negative, erosion is applied to the bitmap. `rect` defines the area where the morphological operation is applied. Pixels located outside the `rect` are unaffected by [grow_mask()](class_bitmap.md#class_BitMap_method_grow_mask). + +
+ + + + + +[Array](class_array.md)\[[PackedVector2Array](class_packedvector2array.md)\] **opaque_to_polygons**\ (\ rect\: [Rect2i](class_rect2i.md), epsilon\: [float](class_float.md) = 2.0\ ) const [🔗](#class_BitMap_method_opaque_to_polygons) + +Creates an [Array](class_array.md) 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](class_packedvector2array.md) of its vertices. + +To get polygons covering the whole bitmap, pass: + +``` + Rect2(Vector2(), get_size()) +``` + +\ `epsilon` is passed to RDP to control how accurately the polygons cover the bitmap: a lower `epsilon` corresponds to more points in the polygons. + +
+ + + + + +`void` **resize**\ (\ new_size\: [Vector2i](class_vector2i.md)\ ) [🔗](#class_BitMap_method_resize) + +Resizes the image to `new_size`. + +
+ + + + + +`void` **set_bit**\ (\ x\: [int](class_int.md), y\: [int](class_int.md), bit\: [bool](class_bool.md)\ ) [🔗](#class_BitMap_method_set_bit) + +Sets the bitmap's element at the specified position, to the specified value. + +
+ + + + + +`void` **set_bit_rect**\ (\ rect\: [Rect2i](class_rect2i.md), bit\: [bool](class_bool.md)\ ) [🔗](#class_BitMap_method_set_bit_rect) + +Sets a rectangular portion of the bitmap to the specified value. + +
+ + + + + +`void` **set_bitv**\ (\ position\: [Vector2i](class_vector2i.md), bit\: [bool](class_bool.md)\ ) [🔗](#class_BitMap_method_set_bitv) + +Sets the bitmap's element at the specified position, to the specified value. + diff --git a/docs/Classes/class_bone2d.md b/docs/Classes/class_bone2d.md new file mode 100644 index 00000000..d817fb27 --- /dev/null +++ b/docs/Classes/class_bone2d.md @@ -0,0 +1,207 @@ + + + + + + + + + +# Bone2D + +**Inherits:** [Node2D](class_node2d.md) **<** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +A joint used with [Skeleton2D](class_skeleton2d.md) to control and animate other nodes. + + + +## Description + +A hierarchy of **Bone2D**\ s can be bound to a [Skeleton2D](class_skeleton2d.md) to control and animate other [Node2D](class_node2d.md) nodes. + +You can use **Bone2D** and [Skeleton2D](class_skeleton2d.md) nodes to animate 2D meshes created with the [Polygon2D](class_polygon2d.md) UV editor. + +Each bone has a [rest](class_bone2d.md#class_Bone2D_property_rest) transform that you can reset to with [apply_rest()](class_bone2d.md#class_Bone2D_method_apply_rest). These rest poses are relative to the bone's parent. + +If in the editor, you can set the rest pose of an entire skeleton using a menu option, from the code, you need to iterate over the bones to set their individual rest poses. + + + +## Properties + + + + + + + + + + + +
[Transform2D](class_transform2d.md)[rest](#class_Bone2D_property_rest)`Transform2D(0, 0, 0, 0, 0, 0)`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
`void`[apply_rest](#class_Bone2D_method_apply_rest)\ (\ )
[bool](class_bool.md)[get_autocalculate_length_and_angle](#class_Bone2D_method_get_autocalculate_length_and_angle)\ (\ ) const
[float](class_float.md)[get_bone_angle](#class_Bone2D_method_get_bone_angle)\ (\ ) const
[int](class_int.md)[get_index_in_skeleton](#class_Bone2D_method_get_index_in_skeleton)\ (\ ) const
[float](class_float.md)[get_length](#class_Bone2D_method_get_length)\ (\ ) const
[Transform2D](class_transform2d.md)[get_skeleton_rest](#class_Bone2D_method_get_skeleton_rest)\ (\ ) const
`void`[set_autocalculate_length_and_angle](#class_Bone2D_method_set_autocalculate_length_and_angle)\ (\ auto_calculate\: [bool](class_bool.md)\ )
`void`[set_bone_angle](#class_Bone2D_method_set_bone_angle)\ (\ angle\: [float](class_float.md)\ )
`void`[set_length](#class_Bone2D_method_set_length)\ (\ length\: [float](class_float.md)\ )
+ +
+ + + +## Property Descriptions + + + + + +[Transform2D](class_transform2d.md) **rest** = `Transform2D(0, 0, 0, 0, 0, 0)` [🔗](#class_Bone2D_property_rest) + + + +- `void` **set_rest**\ (\ value\: [Transform2D](class_transform2d.md)\ ) +- [Transform2D](class_transform2d.md) **get_rest**\ (\ ) + +Rest transform of the bone. You can reset the node's transforms to this value using [apply_rest()](class_bone2d.md#class_Bone2D_method_apply_rest). + +
+ + + +## Method Descriptions + + + + + +`void` **apply_rest**\ (\ ) [🔗](#class_Bone2D_method_apply_rest) + +Resets the bone to the rest pose. This is equivalent to setting [Node2D.transform](class_node2d.md#class_Node2D_property_transform) to [rest](class_bone2d.md#class_Bone2D_property_rest). + +
+ + + + + +[bool](class_bool.md) **get_autocalculate_length_and_angle**\ (\ ) const [🔗](#class_Bone2D_method_get_autocalculate_length_and_angle) + +Returns whether this **Bone2D** is going to autocalculate its length and bone angle using its first **Bone2D** child node, if one exists. If there are no **Bone2D** children, then it cannot autocalculate these values and will print a warning. + +
+ + + + + +[float](class_float.md) **get_bone_angle**\ (\ ) const [🔗](#class_Bone2D_method_get_bone_angle) + +Returns the angle of the bone in the **Bone2D**. + +\ **Note:** This is different from the **Bone2D**'s rotation. The bone's angle is the rotation of the bone shown by the gizmo, which is unaffected by the **Bone2D**'s [Node2D.transform](class_node2d.md#class_Node2D_property_transform). + +
+ + + + + +[int](class_int.md) **get_index_in_skeleton**\ (\ ) const [🔗](#class_Bone2D_method_get_index_in_skeleton) + +Returns the node's index as part of the entire skeleton. See [Skeleton2D](class_skeleton2d.md). + +
+ + + + + +[float](class_float.md) **get_length**\ (\ ) const [🔗](#class_Bone2D_method_get_length) + +Returns the length of the bone in the **Bone2D** node. + +
+ + + + + +[Transform2D](class_transform2d.md) **get_skeleton_rest**\ (\ ) const [🔗](#class_Bone2D_method_get_skeleton_rest) + +Returns the node's [rest](class_bone2d.md#class_Bone2D_property_rest) [Transform2D](class_transform2d.md) if it doesn't have a parent, or its rest pose relative to its parent. + +
+ + + + + +`void` **set_autocalculate_length_and_angle**\ (\ auto_calculate\: [bool](class_bool.md)\ ) [🔗](#class_Bone2D_method_set_autocalculate_length_and_angle) + +When set to ``true``, the **Bone2D** node will attempt to automatically calculate the bone angle and length using the first child **Bone2D** node, if one exists. If none exist, the **Bone2D** cannot automatically calculate these values and will print a warning. + +
+ + + + + +`void` **set_bone_angle**\ (\ angle\: [float](class_float.md)\ ) [🔗](#class_Bone2D_method_set_bone_angle) + +Sets the bone angle for the **Bone2D**. This is typically set to the rotation from the **Bone2D** to a child **Bone2D** node. + +\ **Note:** This is different from the **Bone2D**'s rotation. The bone's angle is the rotation of the bone shown by the gizmo, which is unaffected by the **Bone2D**'s [Node2D.transform](class_node2d.md#class_Node2D_property_transform). + +
+ + + + + +`void` **set_length**\ (\ length\: [float](class_float.md)\ ) [🔗](#class_Bone2D_method_set_length) + +Sets the length of the bone in the **Bone2D**. + diff --git a/docs/Classes/class_boneattachment3d.md b/docs/Classes/class_boneattachment3d.md new file mode 100644 index 00000000..52063913 --- /dev/null +++ b/docs/Classes/class_boneattachment3d.md @@ -0,0 +1,188 @@ + + + + + + + + + + + +# BoneAttachment3D + +**Inherits:** [Node3D](class_node3d.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +А node that dynamically copies or overrides the 3D transform of a bone in its parent [Skeleton3D](class_skeleton3d.md). + + + +## Description + +This node selects a bone in a [Skeleton3D](class_skeleton3d.md) and attaches to it. This means that the **BoneAttachment3D** node will either dynamically copy or override the 3D transform of the selected bone. + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[int](class_int.md)[bone_idx](#class_BoneAttachment3D_property_bone_idx)`-1`
[String](class_string.md)[bone_name](#class_BoneAttachment3D_property_bone_name)`""`
[NodePath](class_nodepath.md)[external_skeleton](#class_BoneAttachment3D_property_external_skeleton)
[bool](class_bool.md)[override_pose](#class_BoneAttachment3D_property_override_pose)`false`
[PhysicsInterpolationMode](class_node.md#enum_Node_PhysicsInterpolationMode)physics_interpolation_mode`2` (overrides [Node.physics_interpolation_mode](class_node.md#class_Node_property_physics_interpolation_mode))
[bool](class_bool.md)[use_external_skeleton](#class_BoneAttachment3D_property_use_external_skeleton)`false`
+ + + +## Methods + + + + + + + + + + + + + + +
[Skeleton3D](class_skeleton3d.md)[get_skeleton](#class_BoneAttachment3D_method_get_skeleton)\ (\ )
`void`[on_skeleton_update](#class_BoneAttachment3D_method_on_skeleton_update)\ (\ )
+ +
+ + + +## Property Descriptions + + + + + +[int](class_int.md) **bone_idx** = `-1` [🔗](#class_BoneAttachment3D_property_bone_idx) + + + +- `void` **set_bone_idx**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_bone_idx**\ (\ ) + +The index of the attached bone. + +
+ + + + + +[String](class_string.md) **bone_name** = `""` [🔗](#class_BoneAttachment3D_property_bone_name) + + + +- `void` **set_bone_name**\ (\ value\: [String](class_string.md)\ ) +- [String](class_string.md) **get_bone_name**\ (\ ) + +The name of the attached bone. + +
+ + + + + +[NodePath](class_nodepath.md) **external_skeleton** [🔗](#class_BoneAttachment3D_property_external_skeleton) + + + +- `void` **set_external_skeleton**\ (\ value\: [NodePath](class_nodepath.md)\ ) +- [NodePath](class_nodepath.md) **get_external_skeleton**\ (\ ) + +The [NodePath](class_nodepath.md) to the external [Skeleton3D](class_skeleton3d.md) node. + +
+ + + + + +[bool](class_bool.md) **override_pose** = `false` [🔗](#class_BoneAttachment3D_property_override_pose) + + + +- `void` **set_override_pose**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_override_pose**\ (\ ) + +Whether the **BoneAttachment3D** node will override the bone pose of the bone it is attached to. When set to ``true``, the **BoneAttachment3D** node can change the pose of the bone. When set to ``false``, the **BoneAttachment3D** will always be set to the bone's transform. + +\ **Note:** This override performs interruptively in the skeleton update process using signals due to the old design. It may cause unintended behavior when used at the same time with [SkeletonModifier3D](class_skeletonmodifier3d.md). + +
+ + + + + +[bool](class_bool.md) **use_external_skeleton** = `false` [🔗](#class_BoneAttachment3D_property_use_external_skeleton) + + + +- `void` **set_use_external_skeleton**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_use_external_skeleton**\ (\ ) + +Whether the **BoneAttachment3D** node will use an external [Skeleton3D](class_skeleton3d.md) node rather than attempting to use its parent node as the [Skeleton3D](class_skeleton3d.md). When set to ``true``, the **BoneAttachment3D** node will use the external [Skeleton3D](class_skeleton3d.md) node set in [external_skeleton](class_boneattachment3d.md#class_BoneAttachment3D_property_external_skeleton). + +
+ + + +## Method Descriptions + + + + + +[Skeleton3D](class_skeleton3d.md) **get_skeleton**\ (\ ) [🔗](#class_BoneAttachment3D_method_get_skeleton) + +Returns the parent or external [Skeleton3D](class_skeleton3d.md) node if it exists, otherwise returns ``null``. + +
+ + + + + +`void` **on_skeleton_update**\ (\ ) [🔗](#class_BoneAttachment3D_method_on_skeleton_update) + +A function that is called automatically when the [Skeleton3D](class_skeleton3d.md) is updated. This function is where the **BoneAttachment3D** node updates its position so it is correctly bound when it is *not* set to override the bone pose. + diff --git a/docs/Classes/class_boneconstraint3d.md b/docs/Classes/class_boneconstraint3d.md new file mode 100644 index 00000000..064b0339 --- /dev/null +++ b/docs/Classes/class_boneconstraint3d.md @@ -0,0 +1,228 @@ + + + + + + + + + +# BoneConstraint3D + +**Inherits:** [SkeletonModifier3D](class_skeletonmodifier3d.md) **<** [Node3D](class_node3d.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +**Inherited By:** [AimModifier3D](class_aimmodifier3d.md), [ConvertTransformModifier3D](class_converttransformmodifier3d.md), [CopyTransformModifier3D](class_copytransformmodifier3d.md) + +A node that may modify Skeleton3D's bone with associating the two bones. + + + +## Description + +Base class of [SkeletonModifier3D](class_skeletonmodifier3d.md) that modifies the bone set in [set_apply_bone()](class_boneconstraint3d.md#class_BoneConstraint3D_method_set_apply_bone) based on the transform of the bone retrieved by [get_reference_bone()](class_boneconstraint3d.md#class_BoneConstraint3D_method_get_reference_bone). + + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
`void`[clear_setting](#class_BoneConstraint3D_method_clear_setting)\ (\ )
[float](class_float.md)[get_amount](#class_BoneConstraint3D_method_get_amount)\ (\ index\: [int](class_int.md)\ ) const
[int](class_int.md)[get_apply_bone](#class_BoneConstraint3D_method_get_apply_bone)\ (\ index\: [int](class_int.md)\ ) const
[String](class_string.md)[get_apply_bone_name](#class_BoneConstraint3D_method_get_apply_bone_name)\ (\ index\: [int](class_int.md)\ ) const
[int](class_int.md)[get_reference_bone](#class_BoneConstraint3D_method_get_reference_bone)\ (\ index\: [int](class_int.md)\ ) const
[String](class_string.md)[get_reference_bone_name](#class_BoneConstraint3D_method_get_reference_bone_name)\ (\ index\: [int](class_int.md)\ ) const
[int](class_int.md)[get_setting_count](#class_BoneConstraint3D_method_get_setting_count)\ (\ ) const
`void`[set_amount](#class_BoneConstraint3D_method_set_amount)\ (\ index\: [int](class_int.md), amount\: [float](class_float.md)\ )
`void`[set_apply_bone](#class_BoneConstraint3D_method_set_apply_bone)\ (\ index\: [int](class_int.md), bone\: [int](class_int.md)\ )
`void`[set_apply_bone_name](#class_BoneConstraint3D_method_set_apply_bone_name)\ (\ index\: [int](class_int.md), bone_name\: [String](class_string.md)\ )
`void`[set_reference_bone](#class_BoneConstraint3D_method_set_reference_bone)\ (\ index\: [int](class_int.md), bone\: [int](class_int.md)\ )
`void`[set_reference_bone_name](#class_BoneConstraint3D_method_set_reference_bone_name)\ (\ index\: [int](class_int.md), bone_name\: [String](class_string.md)\ )
`void`[set_setting_count](#class_BoneConstraint3D_method_set_setting_count)\ (\ count\: [int](class_int.md)\ )
+ +
+ + + +## Method Descriptions + + + + + +`void` **clear_setting**\ (\ ) [🔗](#class_BoneConstraint3D_method_clear_setting) + +Clear all settings. + +
+ + + + + +[float](class_float.md) **get_amount**\ (\ index\: [int](class_int.md)\ ) const [🔗](#class_BoneConstraint3D_method_get_amount) + +Returns the apply amount of the setting at `index`. + +
+ + + + + +[int](class_int.md) **get_apply_bone**\ (\ index\: [int](class_int.md)\ ) const [🔗](#class_BoneConstraint3D_method_get_apply_bone) + +Returns the apply bone of the setting at `index`. This bone will be modified. + +
+ + + + + +[String](class_string.md) **get_apply_bone_name**\ (\ index\: [int](class_int.md)\ ) const [🔗](#class_BoneConstraint3D_method_get_apply_bone_name) + +Returns the apply bone name of the setting at `index`. This bone will be modified. + +
+ + + + + +[int](class_int.md) **get_reference_bone**\ (\ index\: [int](class_int.md)\ ) const [🔗](#class_BoneConstraint3D_method_get_reference_bone) + +Returns the reference bone of the setting at `index`. + +This bone will be only referenced and not modified by this modifier. + +
+ + + + + +[String](class_string.md) **get_reference_bone_name**\ (\ index\: [int](class_int.md)\ ) const [🔗](#class_BoneConstraint3D_method_get_reference_bone_name) + +Returns the reference bone name of the setting at `index`. + +This bone will be only referenced and not modified by this modifier. + +
+ + + + + +[int](class_int.md) **get_setting_count**\ (\ ) const [🔗](#class_BoneConstraint3D_method_get_setting_count) + +Returns the number of settings in the modifier. + +
+ + + + + +`void` **set_amount**\ (\ index\: [int](class_int.md), amount\: [float](class_float.md)\ ) [🔗](#class_BoneConstraint3D_method_set_amount) + +Sets the apply amount of the setting at `index` to `amount`. + +
+ + + + + +`void` **set_apply_bone**\ (\ index\: [int](class_int.md), bone\: [int](class_int.md)\ ) [🔗](#class_BoneConstraint3D_method_set_apply_bone) + +Sets the apply bone of the setting at `index` to `bone`. This bone will be modified. + +
+ + + + + +`void` **set_apply_bone_name**\ (\ index\: [int](class_int.md), bone_name\: [String](class_string.md)\ ) [🔗](#class_BoneConstraint3D_method_set_apply_bone_name) + +Sets the apply bone of the setting at `index` to `bone_name`. This bone will be modified. + +
+ + + + + +`void` **set_reference_bone**\ (\ index\: [int](class_int.md), bone\: [int](class_int.md)\ ) [🔗](#class_BoneConstraint3D_method_set_reference_bone) + +Sets the reference bone of the setting at `index` to `bone`. + +This bone will be only referenced and not modified by this modifier. + +
+ + + + + +`void` **set_reference_bone_name**\ (\ index\: [int](class_int.md), bone_name\: [String](class_string.md)\ ) [🔗](#class_BoneConstraint3D_method_set_reference_bone_name) + +Sets the reference bone of the setting at `index` to `bone_name`. + +This bone will be only referenced and not modified by this modifier. + +
+ + + + + +`void` **set_setting_count**\ (\ count\: [int](class_int.md)\ ) [🔗](#class_BoneConstraint3D_method_set_setting_count) + +Sets the number of settings in the modifier. + diff --git a/docs/Classes/class_bonemap.md b/docs/Classes/class_bonemap.md new file mode 100644 index 00000000..4b92d2c4 --- /dev/null +++ b/docs/Classes/class_bonemap.md @@ -0,0 +1,150 @@ + + + + + + + + + +# BoneMap + +**Inherits:** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Describes a mapping of bone names for retargeting [Skeleton3D](class_skeleton3d.md) into common names defined by a [SkeletonProfile](class_skeletonprofile.md). + + + +## Description + +This class contains a dictionary that uses a list of bone names in [SkeletonProfile](class_skeletonprofile.md) as key names. + +By assigning the actual [Skeleton3D](class_skeleton3d.md) bone name as the key value, it maps the [Skeleton3D](class_skeleton3d.md) to the [SkeletonProfile](class_skeletonprofile.md). + + + +## Tutorials + +- [Retargeting 3D Skeletons](../tutorials/assets_pipeline/retargeting_3d_skeletons.md) + + + +## Properties + + + + + + + + + + +
[SkeletonProfile](class_skeletonprofile.md)[profile](#class_BoneMap_property_profile)
+ + + +## Methods + + + + + + + + + + + + + + + + + + +
[StringName](class_stringname.md)[find_profile_bone_name](#class_BoneMap_method_find_profile_bone_name)\ (\ skeleton_bone_name\: [StringName](class_stringname.md)\ ) const
[StringName](class_stringname.md)[get_skeleton_bone_name](#class_BoneMap_method_get_skeleton_bone_name)\ (\ profile_bone_name\: [StringName](class_stringname.md)\ ) const
`void`[set_skeleton_bone_name](#class_BoneMap_method_set_skeleton_bone_name)\ (\ profile_bone_name\: [StringName](class_stringname.md), skeleton_bone_name\: [StringName](class_stringname.md)\ )
+ +
+ + + +## Signals + + + + + +**bone_map_updated**\ (\ ) [🔗](#class_BoneMap_signal_bone_map_updated) + +This signal is emitted when change the key value in the **BoneMap**. This is used to validate mapping and to update **BoneMap** editor. + +
+ + + + + +**profile_updated**\ (\ ) [🔗](#class_BoneMap_signal_profile_updated) + +This signal is emitted when change the value in profile or change the reference of profile. This is used to update key names in the **BoneMap** and to redraw the **BoneMap** editor. + +
+ + + +## Property Descriptions + + + + + +[SkeletonProfile](class_skeletonprofile.md) **profile** [🔗](#class_BoneMap_property_profile) + + + +- `void` **set_profile**\ (\ value\: [SkeletonProfile](class_skeletonprofile.md)\ ) +- [SkeletonProfile](class_skeletonprofile.md) **get_profile**\ (\ ) + +A [SkeletonProfile](class_skeletonprofile.md) of the mapping target. Key names in the **BoneMap** are synchronized with it. + +
+ + + +## Method Descriptions + + + + + +[StringName](class_stringname.md) **find_profile_bone_name**\ (\ skeleton_bone_name\: [StringName](class_stringname.md)\ ) const [🔗](#class_BoneMap_method_find_profile_bone_name) + +Returns a profile bone name having `skeleton_bone_name`. If not found, an empty [StringName](class_stringname.md) will be returned. + +In the retargeting process, the returned bone name is the bone name of the target skeleton. + +
+ + + + + +[StringName](class_stringname.md) **get_skeleton_bone_name**\ (\ profile_bone_name\: [StringName](class_stringname.md)\ ) const [🔗](#class_BoneMap_method_get_skeleton_bone_name) + +Returns a skeleton bone name is mapped to `profile_bone_name`. + +In the retargeting process, the returned bone name is the bone name of the source skeleton. + +
+ + + + + +`void` **set_skeleton_bone_name**\ (\ profile_bone_name\: [StringName](class_stringname.md), skeleton_bone_name\: [StringName](class_stringname.md)\ ) [🔗](#class_BoneMap_method_set_skeleton_bone_name) + +Maps a skeleton bone name to `profile_bone_name`. + +In the retargeting process, the setting bone name is the bone name of the source skeleton. + diff --git a/docs/Classes/class_bool.md b/docs/Classes/class_bool.md new file mode 100644 index 00000000..8e7650be --- /dev/null +++ b/docs/Classes/class_bool.md @@ -0,0 +1,209 @@ + + + + + + + + + +# bool + +A built-in boolean type. + + + +## Description + +The **bool** is a built-in [Variant](class_variant.md) type that may only store one of two values: ``true`` or ``false``. You can imagine it as a switch that can be either turned on or off, or as a binary digit that can either be 1 or 0. + +Booleans can be directly used in ``if``, and other conditional statements: + + + + +```gdscript + var can_shoot = true + if can_shoot: + launch_bullet() +``` + +```csharp + bool canShoot = true; + if (canShoot) + { + LaunchBullet(); + } +``` + + + +All comparison operators return booleans (``==``, ``>``, ``<=``, etc.). As such, it is not necessary to compare booleans themselves. You do not need to add ``== true`` or ``== false``. + +Booleans can be combined with the logical operators ``and``, ``or``, ``not`` to create complex conditions: + + + + +```gdscript + if bullets > 0 and not is_reloading(): + launch_bullet() + + if bullets == 0 or is_reloading(): + play_clack_sound() +``` + +```csharp + if (bullets > 0 && !IsReloading()) + { + LaunchBullet(); + } + + if (bullets == 0 || IsReloading()) + { + PlayClackSound(); + } +``` + + + +\ **Note:** In modern programming languages, logical operators are evaluated in order. All remaining conditions are skipped if their result would have no effect on the final value. This concept is known as [short-circuit evaluation](https://en.wikipedia.org/wiki/Short-circuit_evaluation) and can be useful to avoid evaluating expensive conditions in some performance-critical cases. + +\ **Note:** By convention, built-in methods and properties that return booleans are usually defined as yes-no questions, single adjectives, or similar ([String.is_empty()](class_string.md#class_String_method_is_empty), [Node.can_process()](class_node.md#class_Node_method_can_process), [Camera2D.enabled](class_camera2d.md#class_Camera2D_property_enabled), etc.). + + + +## Constructors + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[bool](#class_bool_constructor_bool)\ (\ )
[bool](class_bool.md)[bool](#class_bool_constructor_bool)\ (\ from\: [bool](class_bool.md)\ )
[bool](class_bool.md)[bool](#class_bool_constructor_bool)\ (\ from\: [float](class_float.md)\ )
[bool](class_bool.md)[bool](#class_bool_constructor_bool)\ (\ from\: [int](class_int.md)\ )
+ + + +## Operators + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[operator !=](#class_bool_operator_neq_bool)\ (\ right\: [bool](class_bool.md)\ )
[bool](class_bool.md)[operator \<](#class_bool_operator_lt_bool)\ (\ right\: [bool](class_bool.md)\ )
[bool](class_bool.md)[operator ==](#class_bool_operator_eq_bool)\ (\ right\: [bool](class_bool.md)\ )
[bool](class_bool.md)[operator >](#class_bool_operator_gt_bool)\ (\ right\: [bool](class_bool.md)\ )
+ +
+ + + +## Constructor Descriptions + + + + + +[bool](class_bool.md) **bool**\ (\ ) [🔗](#class_bool_constructor_bool) + +Constructs a **bool** set to ``false``. + +
+ + + +[bool](class_bool.md) **bool**\ (\ from\: [bool](class_bool.md)\ ) + +Constructs a **bool** as a copy of the given **bool**. + +
+ + + +[bool](class_bool.md) **bool**\ (\ from\: [float](class_float.md)\ ) + +Cast a [float](class_float.md) value to a boolean value. Returns ``false`` if `from` is equal to ``0.0`` (including ``-0.0``), and ``true`` for all other values (including [@GDScript.INF](class_@gdscript.md#class_@GDScript_constant_INF) and [@GDScript.NAN](class_@gdscript.md#class_@GDScript_constant_NAN)). + +
+ + + +[bool](class_bool.md) **bool**\ (\ from\: [int](class_int.md)\ ) + +Cast an [int](class_int.md) value to a boolean value. Returns ``false`` if `from` is equal to ``0``, and ``true`` for all other values. + +
+ + + +## Operator Descriptions + + + + + +[bool](class_bool.md) **operator !=**\ (\ right\: [bool](class_bool.md)\ ) [🔗](#class_bool_operator_neq_bool) + +Returns ``true`` if the two booleans are not equal. That is, one is ``true`` and the other is ``false``. This operation can be seen as a logical XOR. + +
+ + + + + +[bool](class_bool.md) **operator <**\ (\ right\: [bool](class_bool.md)\ ) [🔗](#class_bool_operator_lt_bool) + +Returns ``true`` if the left operand is ``false`` and the right operand is ``true``. + +
+ + + + + +[bool](class_bool.md) **operator ==**\ (\ right\: [bool](class_bool.md)\ ) [🔗](#class_bool_operator_eq_bool) + +Returns ``true`` if the two booleans are equal. That is, both are ``true`` or both are ``false``. This operation can be seen as a logical EQ or XNOR. + +
+ + + + + +[bool](class_bool.md) **operator >**\ (\ right\: [bool](class_bool.md)\ ) [🔗](#class_bool_operator_gt_bool) + +Returns ``true`` if the left operand is ``true`` and the right operand is ``false``. + diff --git a/docs/Classes/class_boxcontainer.md b/docs/Classes/class_boxcontainer.md new file mode 100644 index 00000000..7024cf43 --- /dev/null +++ b/docs/Classes/class_boxcontainer.md @@ -0,0 +1,175 @@ + + + + + + + + + +# BoxContainer + +**Inherits:** [Container](class_container.md) **<** [Control](class_control.md) **<** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +**Inherited By:** [HBoxContainer](class_hboxcontainer.md), [VBoxContainer](class_vboxcontainer.md) + +A container that arranges its child controls horizontally or vertically. + + + +## Description + +A container that arranges its child controls horizontally or vertically, rearranging them automatically when their minimum size changes. + + + +## Tutorials + +- [Using Containers](../tutorials/ui/gui_containers.md) + + + +## Properties + + + + + + + + + + + + + + + + +
[AlignmentMode](class_boxcontainer.md#enum_BoxContainer_AlignmentMode)[alignment](#class_BoxContainer_property_alignment)`0`
[bool](class_bool.md)[vertical](#class_BoxContainer_property_vertical)`false`
+ + + +## Methods + + + + + + + + + + +
[Control](class_control.md)[add_spacer](#class_BoxContainer_method_add_spacer)\ (\ begin\: [bool](class_bool.md)\ )
+ + + +## Theme Properties + + + + + + + + + + + +
[int](class_int.md)[separation](#class_BoxContainer_theme_constant_separation)`4`
+ +
+ + + +## Enumerations + + + + + +enum **AlignmentMode**: [🔗](#enum_BoxContainer_AlignmentMode) + + + + + +[AlignmentMode](class_boxcontainer.md#enum_BoxContainer_AlignmentMode) **ALIGNMENT_BEGIN** = `0` + +The child controls will be arranged at the beginning of the container, i.e. top if orientation is vertical, left if orientation is horizontal (right for RTL layout). + + + +[AlignmentMode](class_boxcontainer.md#enum_BoxContainer_AlignmentMode) **ALIGNMENT_CENTER** = `1` + +The child controls will be centered in the container. + + + +[AlignmentMode](class_boxcontainer.md#enum_BoxContainer_AlignmentMode) **ALIGNMENT_END** = `2` + +The child controls will be arranged at the end of the container, i.e. bottom if orientation is vertical, right if orientation is horizontal (left for RTL layout).
+ + + +## Property Descriptions + + + + + +[AlignmentMode](class_boxcontainer.md#enum_BoxContainer_AlignmentMode) **alignment** = `0` [🔗](#class_BoxContainer_property_alignment) + + + +- `void` **set_alignment**\ (\ value\: [AlignmentMode](class_boxcontainer.md#enum_BoxContainer_AlignmentMode)\ ) +- [AlignmentMode](class_boxcontainer.md#enum_BoxContainer_AlignmentMode) **get_alignment**\ (\ ) + +The alignment of the container's children (must be one of [ALIGNMENT_BEGIN](class_boxcontainer.md#class_BoxContainer_constant_ALIGNMENT_BEGIN), [ALIGNMENT_CENTER](class_boxcontainer.md#class_BoxContainer_constant_ALIGNMENT_CENTER), or [ALIGNMENT_END](class_boxcontainer.md#class_BoxContainer_constant_ALIGNMENT_END)). + +
+ + + + + +[bool](class_bool.md) **vertical** = `false` [🔗](#class_BoxContainer_property_vertical) + + + +- `void` **set_vertical**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_vertical**\ (\ ) + +If ``true``, the **BoxContainer** will arrange its children vertically, rather than horizontally. + +Can't be changed when using [HBoxContainer](class_hboxcontainer.md) and [VBoxContainer](class_vboxcontainer.md). + +
+ + + +## Method Descriptions + + + + + +[Control](class_control.md) **add_spacer**\ (\ begin\: [bool](class_bool.md)\ ) [🔗](#class_BoxContainer_method_add_spacer) + +Adds a [Control](class_control.md) node to the box as a spacer. If `begin` is ``true``, it will insert the [Control](class_control.md) node in front of all other children. + +
+ + + +## Theme Property Descriptions + + + + + +[int](class_int.md) **separation** = `4` [🔗](#class_BoxContainer_theme_constant_separation) + +The space between the **BoxContainer**'s elements, in pixels. + diff --git a/docs/Classes/class_boxmesh.md b/docs/Classes/class_boxmesh.md new file mode 100644 index 00000000..1e95b89b --- /dev/null +++ b/docs/Classes/class_boxmesh.md @@ -0,0 +1,120 @@ + + + + + + + + + +# BoxMesh + +**Inherits:** [PrimitiveMesh](class_primitivemesh.md) **<** [Mesh](class_mesh.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Generate an axis-aligned box [PrimitiveMesh](class_primitivemesh.md). + + + +## Description + +Generate an axis-aligned box [PrimitiveMesh](class_primitivemesh.md). + +The box's UV layout is arranged in a 3×2 layout that allows texturing each face individually. To apply the same texture on all faces, change the material's UV property to ``Vector3(3, 2, 1)``. This is equivalent to adding ``UV *= vec2(3.0, 2.0)`` in a vertex shader. + +\ **Note:** When using a large textured **BoxMesh** (e.g. as a floor), you may stumble upon UV jittering issues depending on the camera angle. To solve this, increase [subdivide_depth](class_boxmesh.md#class_BoxMesh_property_subdivide_depth), [subdivide_height](class_boxmesh.md#class_BoxMesh_property_subdivide_height) and [subdivide_width](class_boxmesh.md#class_BoxMesh_property_subdivide_width) until you no longer notice UV jittering. + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Vector3](class_vector3.md)[size](#class_BoxMesh_property_size)`Vector3(1, 1, 1)`
[int](class_int.md)[subdivide_depth](#class_BoxMesh_property_subdivide_depth)`0`
[int](class_int.md)[subdivide_height](#class_BoxMesh_property_subdivide_height)`0`
[int](class_int.md)[subdivide_width](#class_BoxMesh_property_subdivide_width)`0`
+ +
+ + + +## Property Descriptions + + + + + +[Vector3](class_vector3.md) **size** = `Vector3(1, 1, 1)` [🔗](#class_BoxMesh_property_size) + + + +- `void` **set_size**\ (\ value\: [Vector3](class_vector3.md)\ ) +- [Vector3](class_vector3.md) **get_size**\ (\ ) + +The box's width, height and depth. + +
+ + + + + +[int](class_int.md) **subdivide_depth** = `0` [🔗](#class_BoxMesh_property_subdivide_depth) + + + +- `void` **set_subdivide_depth**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_subdivide_depth**\ (\ ) + +Number of extra edge loops inserted along the Z axis. + +
+ + + + + +[int](class_int.md) **subdivide_height** = `0` [🔗](#class_BoxMesh_property_subdivide_height) + + + +- `void` **set_subdivide_height**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_subdivide_height**\ (\ ) + +Number of extra edge loops inserted along the Y axis. + +
+ + + + + +[int](class_int.md) **subdivide_width** = `0` [🔗](#class_BoxMesh_property_subdivide_width) + + + +- `void` **set_subdivide_width**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_subdivide_width**\ (\ ) + +Number of extra edge loops inserted along the X axis. + diff --git a/docs/Classes/class_boxoccluder3d.md b/docs/Classes/class_boxoccluder3d.md new file mode 100644 index 00000000..642cbaa1 --- /dev/null +++ b/docs/Classes/class_boxoccluder3d.md @@ -0,0 +1,64 @@ + + + + + + + + + +# BoxOccluder3D + +**Inherits:** [Occluder3D](class_occluder3d.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Cuboid shape for use with occlusion culling in [OccluderInstance3D](class_occluderinstance3d.md). + + + +## Description + +**BoxOccluder3D** stores a cuboid shape that can be used by the engine's occlusion culling system. + +See [OccluderInstance3D](class_occluderinstance3d.md)'s documentation for instructions on setting up occlusion culling. + + + +## Tutorials + +- [Occlusion culling](../tutorials/3d/occlusion_culling.md) + + + +## Properties + + + + + + + + + + + +
[Vector3](class_vector3.md)[size](#class_BoxOccluder3D_property_size)`Vector3(1, 1, 1)`
+ +
+ + + +## Property Descriptions + + + + + +[Vector3](class_vector3.md) **size** = `Vector3(1, 1, 1)` [🔗](#class_BoxOccluder3D_property_size) + + + +- `void` **set_size**\ (\ value\: [Vector3](class_vector3.md)\ ) +- [Vector3](class_vector3.md) **get_size**\ (\ ) + +The box's size in 3D units. + diff --git a/docs/Classes/class_boxshape3d.md b/docs/Classes/class_boxshape3d.md new file mode 100644 index 00000000..9020cf7e --- /dev/null +++ b/docs/Classes/class_boxshape3d.md @@ -0,0 +1,68 @@ + + + + + + + + + +# BoxShape3D + +**Inherits:** [Shape3D](class_shape3d.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +A 3D box shape used for physics collision. + + + +## Description + +A 3D box shape, intended for use in physics. Usually used to provide a shape for a [CollisionShape3D](class_collisionshape3d.md). + +\ **Performance:** **BoxShape3D** is fast to check collisions against. It is faster than [CapsuleShape3D](class_capsuleshape3d.md) and [CylinderShape3D](class_cylindershape3d.md), but slower than [SphereShape3D](class_sphereshape3d.md). + + + +## Tutorials + +- [3D Physics Tests Demo](https://godotengine.org/asset-library/asset/2747) + +- [3D Kinematic Character Demo](https://godotengine.org/asset-library/asset/2739) + +- [3D Platformer Demo](https://godotengine.org/asset-library/asset/2748) + + + +## Properties + + + + + + + + + + + +
[Vector3](class_vector3.md)[size](#class_BoxShape3D_property_size)`Vector3(1, 1, 1)`
+ +
+ + + +## Property Descriptions + + + + + +[Vector3](class_vector3.md) **size** = `Vector3(1, 1, 1)` [🔗](#class_BoxShape3D_property_size) + + + +- `void` **set_size**\ (\ value\: [Vector3](class_vector3.md)\ ) +- [Vector3](class_vector3.md) **get_size**\ (\ ) + +The box's width, height and depth. + diff --git a/docs/Classes/class_button.md b/docs/Classes/class_button.md new file mode 100644 index 00000000..21fc6795 --- /dev/null +++ b/docs/Classes/class_button.md @@ -0,0 +1,842 @@ + + + + + + + + + +# Button + +**Inherits:** [BaseButton](class_basebutton.md) **<** [Control](class_control.md) **<** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +**Inherited By:** [CheckBox](class_checkbox.md), [CheckButton](class_checkbutton.md), [ColorPickerButton](class_colorpickerbutton.md), [MenuButton](class_menubutton.md), [OptionButton](class_optionbutton.md) + +A themed button that can contain text and an icon. + + + +## Description + +**Button** is the standard themed button. It can contain text and an icon, and it will display them according to the current [Theme](class_theme.md). + +\ **Example:** Create a button and connect a method that will be called when the button is pressed: + + + + +```gdscript + func _ready(): + var button = Button.new() + button.text = "Click me" + button.pressed.connect(_button_pressed) + add_child(button) + + func _button_pressed(): + print("Hello world!") +``` + +```csharp + public override void _Ready() + { + var button = new Button(); + button.Text = "Click me"; + button.Pressed += ButtonPressed; + AddChild(button); + } + + private void ButtonPressed() + { + GD.Print("Hello world!"); + } +``` + + + +See also [BaseButton](class_basebutton.md) which contains common properties and methods associated with this node. + +\ **Note:** Buttons do not detect touch input and therefore don't support multitouch, since mouse emulation can only press one button at a given time. Use [TouchScreenButton](class_touchscreenbutton.md) for buttons that trigger gameplay movement or actions. + + + +## Tutorials + +- [2D Dodge The Creeps Demo](https://godotengine.org/asset-library/asset/2712) + +- [Operating System Testing Demo](https://godotengine.org/asset-library/asset/2789) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[HorizontalAlignment](class_@globalscope.md#enum_@GlobalScope_HorizontalAlignment)[alignment](#class_Button_property_alignment)`1`
[AutowrapMode](class_textserver.md#enum_TextServer_AutowrapMode)[autowrap_mode](#class_Button_property_autowrap_mode)`0`
**BitField**\[[LineBreakFlag](class_textserver.md#enum_TextServer_LineBreakFlag)\][autowrap_trim_flags](#class_Button_property_autowrap_trim_flags)`128`
[bool](class_bool.md)[clip_text](#class_Button_property_clip_text)`false`
[bool](class_bool.md)[expand_icon](#class_Button_property_expand_icon)`false`
[bool](class_bool.md)[flat](#class_Button_property_flat)`false`
[Texture2D](class_texture2d.md)[icon](#class_Button_property_icon)
[HorizontalAlignment](class_@globalscope.md#enum_@GlobalScope_HorizontalAlignment)[icon_alignment](#class_Button_property_icon_alignment)`0`
[String](class_string.md)[language](#class_Button_property_language)`""`
[String](class_string.md)[text](#class_Button_property_text)`""`
[TextDirection](class_control.md#enum_Control_TextDirection)[text_direction](#class_Button_property_text_direction)`0`
[OverrunBehavior](class_textserver.md#enum_TextServer_OverrunBehavior)[text_overrun_behavior](#class_Button_property_text_overrun_behavior)`0`
[VerticalAlignment](class_@globalscope.md#enum_@GlobalScope_VerticalAlignment)[vertical_icon_alignment](#class_Button_property_vertical_icon_alignment)`1`
+ + + +## Theme Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Color](class_color.md)[font_color](#class_Button_theme_color_font_color)`Color(0.875, 0.875, 0.875, 1)`
[Color](class_color.md)[font_disabled_color](#class_Button_theme_color_font_disabled_color)`Color(0.875, 0.875, 0.875, 0.5)`
[Color](class_color.md)[font_focus_color](#class_Button_theme_color_font_focus_color)`Color(0.95, 0.95, 0.95, 1)`
[Color](class_color.md)[font_hover_color](#class_Button_theme_color_font_hover_color)`Color(0.95, 0.95, 0.95, 1)`
[Color](class_color.md)[font_hover_pressed_color](#class_Button_theme_color_font_hover_pressed_color)`Color(1, 1, 1, 1)`
[Color](class_color.md)[font_outline_color](#class_Button_theme_color_font_outline_color)`Color(0, 0, 0, 1)`
[Color](class_color.md)[font_pressed_color](#class_Button_theme_color_font_pressed_color)`Color(1, 1, 1, 1)`
[Color](class_color.md)[icon_disabled_color](#class_Button_theme_color_icon_disabled_color)`Color(1, 1, 1, 0.4)`
[Color](class_color.md)[icon_focus_color](#class_Button_theme_color_icon_focus_color)`Color(1, 1, 1, 1)`
[Color](class_color.md)[icon_hover_color](#class_Button_theme_color_icon_hover_color)`Color(1, 1, 1, 1)`
[Color](class_color.md)[icon_hover_pressed_color](#class_Button_theme_color_icon_hover_pressed_color)`Color(1, 1, 1, 1)`
[Color](class_color.md)[icon_normal_color](#class_Button_theme_color_icon_normal_color)`Color(1, 1, 1, 1)`
[Color](class_color.md)[icon_pressed_color](#class_Button_theme_color_icon_pressed_color)`Color(1, 1, 1, 1)`
[int](class_int.md)[align_to_largest_stylebox](#class_Button_theme_constant_align_to_largest_stylebox)`0`
[int](class_int.md)[h_separation](#class_Button_theme_constant_h_separation)`4`
[int](class_int.md)[icon_max_width](#class_Button_theme_constant_icon_max_width)`0`
[int](class_int.md)[line_spacing](#class_Button_theme_constant_line_spacing)`0`
[int](class_int.md)[outline_size](#class_Button_theme_constant_outline_size)`0`
[Font](class_font.md)[font](#class_Button_theme_font_font)
[int](class_int.md)[font_size](#class_Button_theme_font_size_font_size)
[Texture2D](class_texture2d.md)[icon](#class_Button_theme_icon_icon)
[StyleBox](class_stylebox.md)[disabled](#class_Button_theme_style_disabled)
[StyleBox](class_stylebox.md)[disabled_mirrored](#class_Button_theme_style_disabled_mirrored)
[StyleBox](class_stylebox.md)[focus](#class_Button_theme_style_focus)
[StyleBox](class_stylebox.md)[hover](#class_Button_theme_style_hover)
[StyleBox](class_stylebox.md)[hover_mirrored](#class_Button_theme_style_hover_mirrored)
[StyleBox](class_stylebox.md)[hover_pressed](#class_Button_theme_style_hover_pressed)
[StyleBox](class_stylebox.md)[hover_pressed_mirrored](#class_Button_theme_style_hover_pressed_mirrored)
[StyleBox](class_stylebox.md)[normal](#class_Button_theme_style_normal)
[StyleBox](class_stylebox.md)[normal_mirrored](#class_Button_theme_style_normal_mirrored)
[StyleBox](class_stylebox.md)[pressed](#class_Button_theme_style_pressed)
[StyleBox](class_stylebox.md)[pressed_mirrored](#class_Button_theme_style_pressed_mirrored)
+ +
+ + + +## Property Descriptions + + + + + +[HorizontalAlignment](class_@globalscope.md#enum_@GlobalScope_HorizontalAlignment) **alignment** = `1` [🔗](#class_Button_property_alignment) + + + +- `void` **set_text_alignment**\ (\ value\: [HorizontalAlignment](class_@globalscope.md#enum_@GlobalScope_HorizontalAlignment)\ ) +- [HorizontalAlignment](class_@globalscope.md#enum_@GlobalScope_HorizontalAlignment) **get_text_alignment**\ (\ ) + +Text alignment policy for the button's text. + +
+ + + + + +[AutowrapMode](class_textserver.md#enum_TextServer_AutowrapMode) **autowrap_mode** = `0` [🔗](#class_Button_property_autowrap_mode) + + + +- `void` **set_autowrap_mode**\ (\ value\: [AutowrapMode](class_textserver.md#enum_TextServer_AutowrapMode)\ ) +- [AutowrapMode](class_textserver.md#enum_TextServer_AutowrapMode) **get_autowrap_mode**\ (\ ) + +If set to something other than [TextServer.AUTOWRAP_OFF](class_textserver.md#class_TextServer_constant_AUTOWRAP_OFF), the text gets wrapped inside the node's bounding rectangle. + +
+ + + + + +**BitField**\[[LineBreakFlag](class_textserver.md#enum_TextServer_LineBreakFlag)\] **autowrap_trim_flags** = `128` [🔗](#class_Button_property_autowrap_trim_flags) + + + +- `void` **set_autowrap_trim_flags**\ (\ value\: **BitField**\[[LineBreakFlag](class_textserver.md#enum_TextServer_LineBreakFlag)\]\ ) +- **BitField**\[[LineBreakFlag](class_textserver.md#enum_TextServer_LineBreakFlag)\] **get_autowrap_trim_flags**\ (\ ) + +Autowrap space trimming flags. See [TextServer.BREAK_TRIM_START_EDGE_SPACES](class_textserver.md#class_TextServer_constant_BREAK_TRIM_START_EDGE_SPACES) and [TextServer.BREAK_TRIM_END_EDGE_SPACES](class_textserver.md#class_TextServer_constant_BREAK_TRIM_END_EDGE_SPACES) for more info. + +
+ + + + + +[bool](class_bool.md) **clip_text** = `false` [🔗](#class_Button_property_clip_text) + + + +- `void` **set_clip_text**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_clip_text**\ (\ ) + +If ``true``, text that is too large to fit the button is clipped horizontally. If ``false``, the button will always be wide enough to hold the text. The text is not vertically clipped, and the button's height is not affected by this property. + +
+ + + + + +[bool](class_bool.md) **expand_icon** = `false` [🔗](#class_Button_property_expand_icon) + + + +- `void` **set_expand_icon**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_expand_icon**\ (\ ) + +When enabled, the button's icon will expand/shrink to fit the button's size while keeping its aspect. See also [icon_max_width](class_button.md#class_Button_theme_constant_icon_max_width). + +
+ + + + + +[bool](class_bool.md) **flat** = `false` [🔗](#class_Button_property_flat) + + + +- `void` **set_flat**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_flat**\ (\ ) + +Flat buttons don't display decoration. + +
+ + + + + +[Texture2D](class_texture2d.md) **icon** [🔗](#class_Button_property_icon) + + + +- `void` **set_button_icon**\ (\ value\: [Texture2D](class_texture2d.md)\ ) +- [Texture2D](class_texture2d.md) **get_button_icon**\ (\ ) + +Button's icon, if text is present the icon will be placed before the text. + +To edit margin and spacing of the icon, use [h_separation](class_button.md#class_Button_theme_constant_h_separation) theme property and ``content_margin_*`` properties of the used [StyleBox](class_stylebox.md)\ es. + +
+ + + + + +[HorizontalAlignment](class_@globalscope.md#enum_@GlobalScope_HorizontalAlignment) **icon_alignment** = `0` [🔗](#class_Button_property_icon_alignment) + + + +- `void` **set_icon_alignment**\ (\ value\: [HorizontalAlignment](class_@globalscope.md#enum_@GlobalScope_HorizontalAlignment)\ ) +- [HorizontalAlignment](class_@globalscope.md#enum_@GlobalScope_HorizontalAlignment) **get_icon_alignment**\ (\ ) + +Specifies if the icon should be aligned horizontally to the left, right, or center of a button. Uses the same [HorizontalAlignment](class_@globalscope.md#enum_@GlobalScope_HorizontalAlignment) constants as the text alignment. If centered horizontally and vertically, text will draw on top of the icon. + +
+ + + + + +[String](class_string.md) **language** = `""` [🔗](#class_Button_property_language) + + + +- `void` **set_language**\ (\ value\: [String](class_string.md)\ ) +- [String](class_string.md) **get_language**\ (\ ) + +Language code used for line-breaking and text shaping algorithms, if left empty current locale is used instead. + +
+ + + + + +[String](class_string.md) **text** = `""` [🔗](#class_Button_property_text) + + + +- `void` **set_text**\ (\ value\: [String](class_string.md)\ ) +- [String](class_string.md) **get_text**\ (\ ) + +The button's text that will be displayed inside the button's area. + +
+ + + + + +[TextDirection](class_control.md#enum_Control_TextDirection) **text_direction** = `0` [🔗](#class_Button_property_text_direction) + + + +- `void` **set_text_direction**\ (\ value\: [TextDirection](class_control.md#enum_Control_TextDirection)\ ) +- [TextDirection](class_control.md#enum_Control_TextDirection) **get_text_direction**\ (\ ) + +Base text writing direction. + +
+ + + + + +[OverrunBehavior](class_textserver.md#enum_TextServer_OverrunBehavior) **text_overrun_behavior** = `0` [🔗](#class_Button_property_text_overrun_behavior) + + + +- `void` **set_text_overrun_behavior**\ (\ value\: [OverrunBehavior](class_textserver.md#enum_TextServer_OverrunBehavior)\ ) +- [OverrunBehavior](class_textserver.md#enum_TextServer_OverrunBehavior) **get_text_overrun_behavior**\ (\ ) + +Sets the clipping behavior when the text exceeds the node's bounding rectangle. + +
+ + + + + +[VerticalAlignment](class_@globalscope.md#enum_@GlobalScope_VerticalAlignment) **vertical_icon_alignment** = `1` [🔗](#class_Button_property_vertical_icon_alignment) + + + +- `void` **set_vertical_icon_alignment**\ (\ value\: [VerticalAlignment](class_@globalscope.md#enum_@GlobalScope_VerticalAlignment)\ ) +- [VerticalAlignment](class_@globalscope.md#enum_@GlobalScope_VerticalAlignment) **get_vertical_icon_alignment**\ (\ ) + +Specifies if the icon should be aligned vertically to the top, bottom, or center of a button. Uses the same [VerticalAlignment](class_@globalscope.md#enum_@GlobalScope_VerticalAlignment) constants as the text alignment. If centered horizontally and vertically, text will draw on top of the icon. + +
+ + + +## Theme Property Descriptions + + + + + +[Color](class_color.md) **font_color** = `Color(0.875, 0.875, 0.875, 1)` [🔗](#class_Button_theme_color_font_color) + +Default text [Color](class_color.md) of the **Button**. + +
+ + + + + +[Color](class_color.md) **font_disabled_color** = `Color(0.875, 0.875, 0.875, 0.5)` [🔗](#class_Button_theme_color_font_disabled_color) + +Text [Color](class_color.md) used when the **Button** is disabled. + +
+ + + + + +[Color](class_color.md) **font_focus_color** = `Color(0.95, 0.95, 0.95, 1)` [🔗](#class_Button_theme_color_font_focus_color) + +Text [Color](class_color.md) used when the **Button** is focused. Only replaces the normal text color of the button. Disabled, hovered, and pressed states take precedence over this color. + +
+ + + + + +[Color](class_color.md) **font_hover_color** = `Color(0.95, 0.95, 0.95, 1)` [🔗](#class_Button_theme_color_font_hover_color) + +Text [Color](class_color.md) used when the **Button** is being hovered. + +
+ + + + + +[Color](class_color.md) **font_hover_pressed_color** = `Color(1, 1, 1, 1)` [🔗](#class_Button_theme_color_font_hover_pressed_color) + +Text [Color](class_color.md) used when the **Button** is being hovered and pressed. + +
+ + + + + +[Color](class_color.md) **font_outline_color** = `Color(0, 0, 0, 1)` [🔗](#class_Button_theme_color_font_outline_color) + +The tint of text outline of the **Button**. + +
+ + + + + +[Color](class_color.md) **font_pressed_color** = `Color(1, 1, 1, 1)` [🔗](#class_Button_theme_color_font_pressed_color) + +Text [Color](class_color.md) used when the **Button** is being pressed. + +
+ + + + + +[Color](class_color.md) **icon_disabled_color** = `Color(1, 1, 1, 0.4)` [🔗](#class_Button_theme_color_icon_disabled_color) + +Icon modulate [Color](class_color.md) used when the **Button** is disabled. + +
+ + + + + +[Color](class_color.md) **icon_focus_color** = `Color(1, 1, 1, 1)` [🔗](#class_Button_theme_color_icon_focus_color) + +Icon modulate [Color](class_color.md) used when the **Button** is focused. Only replaces the normal modulate color of the button. Disabled, hovered, and pressed states take precedence over this color. + +
+ + + + + +[Color](class_color.md) **icon_hover_color** = `Color(1, 1, 1, 1)` [🔗](#class_Button_theme_color_icon_hover_color) + +Icon modulate [Color](class_color.md) used when the **Button** is being hovered. + +
+ + + + + +[Color](class_color.md) **icon_hover_pressed_color** = `Color(1, 1, 1, 1)` [🔗](#class_Button_theme_color_icon_hover_pressed_color) + +Icon modulate [Color](class_color.md) used when the **Button** is being hovered and pressed. + +
+ + + + + +[Color](class_color.md) **icon_normal_color** = `Color(1, 1, 1, 1)` [🔗](#class_Button_theme_color_icon_normal_color) + +Default icon modulate [Color](class_color.md) of the **Button**. + +
+ + + + + +[Color](class_color.md) **icon_pressed_color** = `Color(1, 1, 1, 1)` [🔗](#class_Button_theme_color_icon_pressed_color) + +Icon modulate [Color](class_color.md) used when the **Button** is being pressed. + +
+ + + + + +[int](class_int.md) **align_to_largest_stylebox** = `0` [🔗](#class_Button_theme_constant_align_to_largest_stylebox) + +This constant acts as a boolean. If ``true``, the minimum size of the button and text/icon alignment is always based on the largest stylebox margins, otherwise it's based on the current button state stylebox margins. + +
+ + + + + +[int](class_int.md) **h_separation** = `4` [🔗](#class_Button_theme_constant_h_separation) + +The horizontal space between **Button**'s icon and text. Negative values will be treated as ``0`` when used. + +
+ + + + + +[int](class_int.md) **icon_max_width** = `0` [🔗](#class_Button_theme_constant_icon_max_width) + +The maximum allowed width of the **Button**'s icon. This limit is applied on top of the default size of the icon, or its expanded size if [expand_icon](class_button.md#class_Button_property_expand_icon) is ``true``. The height is adjusted according to the icon's ratio. If the button has additional icons (e.g. [CheckBox](class_checkbox.md)), they will also be limited. + +
+ + + + + +[int](class_int.md) **line_spacing** = `0` [🔗](#class_Button_theme_constant_line_spacing) + +Additional vertical spacing between lines (in pixels), spacing is added to line descent. This value can be negative. + +
+ + + + + +[int](class_int.md) **outline_size** = `0` [🔗](#class_Button_theme_constant_outline_size) + +The size of the text outline. + +\ **Note:** If using a font with [FontFile.multichannel_signed_distance_field](class_fontfile.md#class_FontFile_property_multichannel_signed_distance_field) enabled, its [FontFile.msdf_pixel_range](class_fontfile.md#class_FontFile_property_msdf_pixel_range) must be set to at least *twice* the value of [outline_size](class_button.md#class_Button_theme_constant_outline_size) for outline rendering to look correct. Otherwise, the outline may appear to be cut off earlier than intended. + +
+ + + + + +[Font](class_font.md) **font** [🔗](#class_Button_theme_font_font) + +[Font](class_font.md) of the **Button**'s text. + +
+ + + + + +[int](class_int.md) **font_size** [🔗](#class_Button_theme_font_size_font_size) + +Font size of the **Button**'s text. + +
+ + + + + +[Texture2D](class_texture2d.md) **icon** [🔗](#class_Button_theme_icon_icon) + +Default icon for the **Button**. Appears only if [icon](class_button.md#class_Button_property_icon) is not assigned. + +
+ + + + + +[StyleBox](class_stylebox.md) **disabled** [🔗](#class_Button_theme_style_disabled) + +[StyleBox](class_stylebox.md) used when the **Button** is disabled. + +
+ + + + + +[StyleBox](class_stylebox.md) **disabled_mirrored** [🔗](#class_Button_theme_style_disabled_mirrored) + +[StyleBox](class_stylebox.md) used when the **Button** is disabled (for right-to-left layouts). + +
+ + + + + +[StyleBox](class_stylebox.md) **focus** [🔗](#class_Button_theme_style_focus) + +[StyleBox](class_stylebox.md) used when the **Button** is focused. The [focus](class_button.md#class_Button_theme_style_focus) [StyleBox](class_stylebox.md) is displayed *over* the base [StyleBox](class_stylebox.md), so a partially transparent [StyleBox](class_stylebox.md) should be used to ensure the base [StyleBox](class_stylebox.md) remains visible. A [StyleBox](class_stylebox.md) that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a [StyleBoxEmpty](class_styleboxempty.md) resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons. + +
+ + + + + +[StyleBox](class_stylebox.md) **hover** [🔗](#class_Button_theme_style_hover) + +[StyleBox](class_stylebox.md) used when the **Button** is being hovered. + +
+ + + + + +[StyleBox](class_stylebox.md) **hover_mirrored** [🔗](#class_Button_theme_style_hover_mirrored) + +[StyleBox](class_stylebox.md) used when the **Button** is being hovered (for right-to-left layouts). + +
+ + + + + +[StyleBox](class_stylebox.md) **hover_pressed** [🔗](#class_Button_theme_style_hover_pressed) + +[StyleBox](class_stylebox.md) used when the **Button** is being pressed and hovered at the same time. + +
+ + + + + +[StyleBox](class_stylebox.md) **hover_pressed_mirrored** [🔗](#class_Button_theme_style_hover_pressed_mirrored) + +[StyleBox](class_stylebox.md) used when the **Button** is being pressed and hovered at the same time (for right-to-left layouts). + +
+ + + + + +[StyleBox](class_stylebox.md) **normal** [🔗](#class_Button_theme_style_normal) + +Default [StyleBox](class_stylebox.md) for the **Button**. + +
+ + + + + +[StyleBox](class_stylebox.md) **normal_mirrored** [🔗](#class_Button_theme_style_normal_mirrored) + +Default [StyleBox](class_stylebox.md) for the **Button** (for right-to-left layouts). + +
+ + + + + +[StyleBox](class_stylebox.md) **pressed** [🔗](#class_Button_theme_style_pressed) + +[StyleBox](class_stylebox.md) used when the **Button** is being pressed. + +
+ + + + + +[StyleBox](class_stylebox.md) **pressed_mirrored** [🔗](#class_Button_theme_style_pressed_mirrored) + +[StyleBox](class_stylebox.md) used when the **Button** is being pressed (for right-to-left layouts). + diff --git a/docs/Classes/class_buttongroup.md b/docs/Classes/class_buttongroup.md new file mode 100644 index 00000000..2f5a82c6 --- /dev/null +++ b/docs/Classes/class_buttongroup.md @@ -0,0 +1,122 @@ + + + + + + + + + + + +# ButtonGroup + +**Inherits:** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +A group of buttons that doesn't allow more than one button to be pressed at a time. + + + +## Description + +A group of [BaseButton](class_basebutton.md)-derived buttons. The buttons in a **ButtonGroup** are treated like radio buttons: No more than one button can be pressed at a time. Some types of buttons (such as [CheckBox](class_checkbox.md)) may have a special appearance in this state. + +Every member of a **ButtonGroup** should have [BaseButton.toggle_mode](class_basebutton.md#class_BaseButton_property_toggle_mode) set to ``true``. + + + +## Properties + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[allow_unpress](#class_ButtonGroup_property_allow_unpress)`false`
[bool](class_bool.md)resource_local_to_scene`true` (overrides [Resource.resource_local_to_scene](class_resource.md#class_Resource_property_resource_local_to_scene))
+ + + +## Methods + + + + + + + + + + + + + + +
[Array](class_array.md)\[[BaseButton](class_basebutton.md)\][get_buttons](#class_ButtonGroup_method_get_buttons)\ (\ )
[BaseButton](class_basebutton.md)[get_pressed_button](#class_ButtonGroup_method_get_pressed_button)\ (\ )
+ +
+ + + +## Signals + + + + + +**pressed**\ (\ button\: [BaseButton](class_basebutton.md)\ ) [🔗](#class_ButtonGroup_signal_pressed) + +Emitted when one of the buttons of the group is pressed. + +
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **allow_unpress** = `false` [🔗](#class_ButtonGroup_property_allow_unpress) + + + +- `void` **set_allow_unpress**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_allow_unpress**\ (\ ) + +If ``true``, it is possible to unpress all buttons in this **ButtonGroup**. + +
+ + + +## Method Descriptions + + + + + +[Array](class_array.md)\[[BaseButton](class_basebutton.md)\] **get_buttons**\ (\ ) [🔗](#class_ButtonGroup_method_get_buttons) + +Returns an [Array](class_array.md) of [Button](class_button.md)\ s who have this as their **ButtonGroup** (see [BaseButton.button_group](class_basebutton.md#class_BaseButton_property_button_group)). + +
+ + + + + +[BaseButton](class_basebutton.md) **get_pressed_button**\ (\ ) [🔗](#class_ButtonGroup_method_get_pressed_button) + +Returns the current pressed button. + diff --git a/docs/Classes/class_callable.md b/docs/Classes/class_callable.md new file mode 100644 index 00000000..7a2350be --- /dev/null +++ b/docs/Classes/class_callable.md @@ -0,0 +1,557 @@ + + + + + + + + + +# Callable + +A built-in type representing a method or a standalone function. + + + +## Description + +**Callable** is a built-in [Variant](class_variant.md) type that represents a function. It can either be a method within an [Object](class_object.md) instance, or a custom callable used for different purposes (see [is_custom()](class_callable.md#class_Callable_method_is_custom)). Like all [Variant](class_variant.md) types, it can be stored in variables and passed to other functions. It is most commonly used for signal callbacks. + + + + +```gdscript + func print_args(arg1, arg2, arg3 = ""): + prints(arg1, arg2, arg3) + + func test(): + var callable = Callable(self, "print_args") + callable.call("hello", "world") # Prints "hello world ". + callable.call(Vector2.UP, 42, callable) # Prints "(0.0, -1.0) 42 Node(node.gd)::print_args" + callable.call("invalid") # Invalid call, should have at least 2 arguments. +``` + +```csharp + // Default parameter values are not supported. + public void PrintArgs(Variant arg1, Variant arg2, Variant arg3 = default) + { + GD.PrintS(arg1, arg2, arg3); + } + + public void Test() + { + // Invalid calls fail silently. + Callable callable = new Callable(this, MethodName.PrintArgs); + callable.Call("hello", "world"); // Default parameter values are not supported, should have 3 arguments. + callable.Call(Vector2.Up, 42, callable); // Prints "(0, -1) 42 Node(Node.cs)::PrintArgs" + callable.Call("invalid"); // Invalid call, should have 3 arguments. + } +``` + + + +In GDScript, it's possible to create lambda functions within a method. Lambda functions are custom callables that are not associated with an [Object](class_object.md) instance. Optionally, lambda functions can also be named. The name will be displayed in the debugger, or when calling [get_method()](class_callable.md#class_Callable_method_get_method). + +``` + func _init(): + var my_lambda = func (message): + print(message) + + # Prints "Hello everyone!" + my_lambda.call("Hello everyone!") + + # Prints "Attack!", when the button_pressed signal is emitted. + button_pressed.connect(func(): print("Attack!")) +``` + +In GDScript, you can access methods and global functions as **Callable**\ s: + +``` + tween.tween_callback(node.queue_free) # Object methods. + tween.tween_callback(array.clear) # Methods of built-in types. + tween.tween_callback(print.bind("Test")) # Global functions. +``` + +\ **Note:** [Dictionary](class_dictionary.md) does not support the above due to ambiguity with keys. + +``` + var dictionary = { "hello": "world" } + + # This will not work, `clear` is treated as a key. + tween.tween_callback(dictionary.clear) + + # This will work. + tween.tween_callback(Callable.create(dictionary, "clear")) +``` + +
+There are notable differences when using this API with C#. See the C# differences documentation for more information. + +
+ + + +## Constructors + + + + + + + + + + + + + + + + + + +
[Callable](class_callable.md)[Callable](#class_Callable_constructor_Callable)\ (\ )
[Callable](class_callable.md)[Callable](#class_Callable_constructor_Callable)\ (\ from\: [Callable](class_callable.md)\ )
[Callable](class_callable.md)[Callable](#class_Callable_constructor_Callable)\ (\ object\: [Object](class_object.md), method\: [StringName](class_stringname.md)\ )
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Callable](class_callable.md)[bind](#class_Callable_method_bind)\ (\ ...\ ) vararg const
[Callable](class_callable.md)[bindv](#class_Callable_method_bindv)\ (\ arguments\: [Array](class_array.md)\ )
[Variant](class_variant.md)[call](#class_Callable_method_call)\ (\ ...\ ) vararg const
`void`[call_deferred](#class_Callable_method_call_deferred)\ (\ ...\ ) vararg const
[Variant](class_variant.md)[callv](#class_Callable_method_callv)\ (\ arguments\: [Array](class_array.md)\ ) const
[Callable](class_callable.md)[create](#class_Callable_method_create)\ (\ variant\: [Variant](class_variant.md), method\: [StringName](class_stringname.md)\ ) static
[int](class_int.md)[get_argument_count](#class_Callable_method_get_argument_count)\ (\ ) const
[Array](class_array.md)[get_bound_arguments](#class_Callable_method_get_bound_arguments)\ (\ ) const
[int](class_int.md)[get_bound_arguments_count](#class_Callable_method_get_bound_arguments_count)\ (\ ) const
[StringName](class_stringname.md)[get_method](#class_Callable_method_get_method)\ (\ ) const
[Object](class_object.md)[get_object](#class_Callable_method_get_object)\ (\ ) const
[int](class_int.md)[get_object_id](#class_Callable_method_get_object_id)\ (\ ) const
[int](class_int.md)[get_unbound_arguments_count](#class_Callable_method_get_unbound_arguments_count)\ (\ ) const
[int](class_int.md)[hash](#class_Callable_method_hash)\ (\ ) const
[bool](class_bool.md)[is_custom](#class_Callable_method_is_custom)\ (\ ) const
[bool](class_bool.md)[is_null](#class_Callable_method_is_null)\ (\ ) const
[bool](class_bool.md)[is_standard](#class_Callable_method_is_standard)\ (\ ) const
[bool](class_bool.md)[is_valid](#class_Callable_method_is_valid)\ (\ ) const
`void`[rpc](#class_Callable_method_rpc)\ (\ ...\ ) vararg const
`void`[rpc_id](#class_Callable_method_rpc_id)\ (\ peer_id\: [int](class_int.md), ...\ ) vararg const
[Callable](class_callable.md)[unbind](#class_Callable_method_unbind)\ (\ argcount\: [int](class_int.md)\ ) const
+ + + +## Operators + + + + + + + + + + + + + + +
[bool](class_bool.md)[operator !=](#class_Callable_operator_neq_Callable)\ (\ right\: [Callable](class_callable.md)\ )
[bool](class_bool.md)[operator ==](#class_Callable_operator_eq_Callable)\ (\ right\: [Callable](class_callable.md)\ )
+ +
+ + + +## Constructor Descriptions + + + + + +[Callable](class_callable.md) **Callable**\ (\ ) [🔗](#class_Callable_constructor_Callable) + +Constructs an empty **Callable**, with no object nor method bound. + +
+ + + +[Callable](class_callable.md) **Callable**\ (\ from\: [Callable](class_callable.md)\ ) + +Constructs a **Callable** as a copy of the given **Callable**. + +
+ + + +[Callable](class_callable.md) **Callable**\ (\ object\: [Object](class_object.md), method\: [StringName](class_stringname.md)\ ) + +Creates a new **Callable** for the method named `method` in the specified `object`. + +\ **Note:** For methods of built-in [Variant](class_variant.md) types, use [create()](class_callable.md#class_Callable_method_create) instead. + +
+ + + +## Method Descriptions + + + + + +[Callable](class_callable.md) **bind**\ (\ ...\ ) vararg const [🔗](#class_Callable_method_bind) + +Returns a copy of this **Callable** with one or more arguments bound. When called, the bound arguments are passed *after* the arguments supplied by [call()](class_callable.md#class_Callable_method_call). See also [unbind()](class_callable.md#class_Callable_method_unbind). + +\ **Note:** When this method is chained with other similar methods, the order in which the argument list is modified is read from right to left. + +
+ + + + + +[Callable](class_callable.md) **bindv**\ (\ arguments\: [Array](class_array.md)\ ) [🔗](#class_Callable_method_bindv) + +Returns a copy of this **Callable** with one or more arguments bound, reading them from an array. When called, the bound arguments are passed *after* the arguments supplied by [call()](class_callable.md#class_Callable_method_call). See also [unbind()](class_callable.md#class_Callable_method_unbind). + +\ **Note:** When this method is chained with other similar methods, the order in which the argument list is modified is read from right to left. + +
+ + + + + +[Variant](class_variant.md) **call**\ (\ ...\ ) vararg const [🔗](#class_Callable_method_call) + +Calls the method represented by this **Callable**. Arguments can be passed and should match the method's signature. + +
+ + + + + +`void` **call_deferred**\ (\ ...\ ) vararg const [🔗](#class_Callable_method_call_deferred) + +Calls the method represented by this **Callable** in deferred mode, i.e. at the end of the current frame. Arguments can be passed and should match the method's signature. + + + + +```gdscript + func _ready(): + grab_focus.call_deferred() +``` + +```csharp + public override void _Ready() + { + Callable.From(GrabFocus).CallDeferred(); + } +``` + + + +\ **Note:** Deferred calls are processed at idle time. Idle time happens mainly at the end of process and physics frames. In it, deferred calls will be run until there are none left, which means you can defer calls from other deferred calls and they'll still be run in the current idle time cycle. This means you should not call a method deferred from itself (or from a method called by it), as this causes infinite recursion the same way as if you had called the method directly. + +See also [Object.call_deferred()](class_object.md#class_Object_method_call_deferred). + +
+ + + + + +[Variant](class_variant.md) **callv**\ (\ arguments\: [Array](class_array.md)\ ) const [🔗](#class_Callable_method_callv) + +Calls the method represented by this **Callable**. Unlike [call()](class_callable.md#class_Callable_method_call), this method expects all arguments to be contained inside the `arguments` [Array](class_array.md). + +
+ + + + + +[Callable](class_callable.md) **create**\ (\ variant\: [Variant](class_variant.md), method\: [StringName](class_stringname.md)\ ) static [🔗](#class_Callable_method_create) + +Creates a new **Callable** for the method named `method` in the specified `variant`. To represent a method of a built-in [Variant](class_variant.md) type, a custom callable is used (see [is_custom()](class_callable.md#class_Callable_method_is_custom)). If `variant` is [Object](class_object.md), then a standard callable will be created instead. + +\ **Note:** This method is always necessary for the [Dictionary](class_dictionary.md) type, as property syntax is used to access its entries. You may also use this method when `variant`'s type is not known in advance (for polymorphism). + +
+ + + + + +[int](class_int.md) **get_argument_count**\ (\ ) const [🔗](#class_Callable_method_get_argument_count) + +Returns the total number of arguments this **Callable** should take, including optional arguments. This means that any arguments bound with [bind()](class_callable.md#class_Callable_method_bind) are *subtracted* from the result, and any arguments unbound with [unbind()](class_callable.md#class_Callable_method_unbind) are *added* to the result. + +
+ + + + + +[Array](class_array.md) **get_bound_arguments**\ (\ ) const [🔗](#class_Callable_method_get_bound_arguments) + +Returns the array of arguments bound via successive [bind()](class_callable.md#class_Callable_method_bind) or [unbind()](class_callable.md#class_Callable_method_unbind) calls. These arguments will be added *after* the arguments passed to the call, from which [get_unbound_arguments_count()](class_callable.md#class_Callable_method_get_unbound_arguments_count) arguments on the right have been previously excluded. + +``` + func get_effective_arguments(callable, call_args): + assert(call_args.size() - callable.get_unbound_arguments_count() >= 0) + var result = call_args.slice(0, call_args.size() - callable.get_unbound_arguments_count()) + result.append_array(callable.get_bound_arguments()) + return result +``` + +
+ + + + + +[int](class_int.md) **get_bound_arguments_count**\ (\ ) const [🔗](#class_Callable_method_get_bound_arguments_count) + +Returns the total amount of arguments bound via successive [bind()](class_callable.md#class_Callable_method_bind) or [unbind()](class_callable.md#class_Callable_method_unbind) calls. This is the same as the size of the array returned by [get_bound_arguments()](class_callable.md#class_Callable_method_get_bound_arguments). See [get_bound_arguments()](class_callable.md#class_Callable_method_get_bound_arguments) for details. + +\ **Note:** The [get_bound_arguments_count()](class_callable.md#class_Callable_method_get_bound_arguments_count) and [get_unbound_arguments_count()](class_callable.md#class_Callable_method_get_unbound_arguments_count) methods can both return positive values. + +
+ + + + + +[StringName](class_stringname.md) **get_method**\ (\ ) const [🔗](#class_Callable_method_get_method) + +Returns the name of the method represented by this **Callable**. If the callable is a GDScript lambda function, returns the function's name or ``""``. + +
+ + + + + +[Object](class_object.md) **get_object**\ (\ ) const [🔗](#class_Callable_method_get_object) + +Returns the object on which this **Callable** is called. + +
+ + + + + +[int](class_int.md) **get_object_id**\ (\ ) const [🔗](#class_Callable_method_get_object_id) + +Returns the ID of this **Callable**'s object (see [Object.get_instance_id()](class_object.md#class_Object_method_get_instance_id)). + +
+ + + + + +[int](class_int.md) **get_unbound_arguments_count**\ (\ ) const [🔗](#class_Callable_method_get_unbound_arguments_count) + +Returns the total amount of arguments unbound via successive [bind()](class_callable.md#class_Callable_method_bind) or [unbind()](class_callable.md#class_Callable_method_unbind) calls. See [get_bound_arguments()](class_callable.md#class_Callable_method_get_bound_arguments) for details. + +\ **Note:** The [get_bound_arguments_count()](class_callable.md#class_Callable_method_get_bound_arguments_count) and [get_unbound_arguments_count()](class_callable.md#class_Callable_method_get_unbound_arguments_count) methods can both return positive values. + +
+ + + + + +[int](class_int.md) **hash**\ (\ ) const [🔗](#class_Callable_method_hash) + +Returns the 32-bit hash value of this **Callable**'s object. + +\ **Note:** **Callable**\ s with equal content will always produce identical hash values. However, the reverse is not true. Returning identical hash values does *not* imply the callables are equal, because different callables can have identical hash values due to hash collisions. The engine uses a 32-bit hash algorithm for [hash()](class_callable.md#class_Callable_method_hash). + +
+ + + + + +[bool](class_bool.md) **is_custom**\ (\ ) const [🔗](#class_Callable_method_is_custom) + +Returns ``true`` if this **Callable** is a custom callable. Custom callables are used: + +- for binding/unbinding arguments (see [bind()](class_callable.md#class_Callable_method_bind) and [unbind()](class_callable.md#class_Callable_method_unbind)); + +- for representing methods of built-in [Variant](class_variant.md) types (see [create()](class_callable.md#class_Callable_method_create)); + +- for representing global, lambda, and RPC functions in GDScript; + +- for other purposes in the core, GDExtension, and C#. + +
+ + + + + +[bool](class_bool.md) **is_null**\ (\ ) const [🔗](#class_Callable_method_is_null) + +Returns ``true`` if this **Callable** has no target to call the method on. Equivalent to ``callable == Callable()``. + +\ **Note:** This is *not* the same as ``not is_valid()`` and using ``not is_null()`` will *not* guarantee that this callable can be called. Use [is_valid()](class_callable.md#class_Callable_method_is_valid) instead. + +
+ + + + + +[bool](class_bool.md) **is_standard**\ (\ ) const [🔗](#class_Callable_method_is_standard) + +Returns ``true`` if this **Callable** is a standard callable. This method is the opposite of [is_custom()](class_callable.md#class_Callable_method_is_custom). Returns ``false`` if this callable is a lambda function. + +
+ + + + + +[bool](class_bool.md) **is_valid**\ (\ ) const [🔗](#class_Callable_method_is_valid) + +Returns ``true`` if the callable's object exists and has a valid method name assigned, or is a custom callable. + +
+ + + + + +`void` **rpc**\ (\ ...\ ) vararg const [🔗](#class_Callable_method_rpc) + +Perform an RPC (Remote Procedure Call) on all connected peers. This is used for multiplayer and is normally not available, unless the function being called has been marked as *RPC* (using [@GDScript.@rpc](class_@gdscript.md#class_@GDScript_annotation_@rpc) or [Node.rpc_config()](class_node.md#class_Node_method_rpc_config)). Calling this method on unsupported functions will result in an error. See [Node.rpc()](class_node.md#class_Node_method_rpc). + +
+ + + + + +`void` **rpc_id**\ (\ peer_id\: [int](class_int.md), ...\ ) vararg const [🔗](#class_Callable_method_rpc_id) + +Perform an RPC (Remote Procedure Call) on a specific peer ID (see multiplayer documentation for reference). This is used for multiplayer and is normally not available unless the function being called has been marked as *RPC* (using [@GDScript.@rpc](class_@gdscript.md#class_@GDScript_annotation_@rpc) or [Node.rpc_config()](class_node.md#class_Node_method_rpc_config)). Calling this method on unsupported functions will result in an error. See [Node.rpc_id()](class_node.md#class_Node_method_rpc_id). + +
+ + + + + +[Callable](class_callable.md) **unbind**\ (\ argcount\: [int](class_int.md)\ ) const [🔗](#class_Callable_method_unbind) + +Returns a copy of this **Callable** with a number of arguments unbound. In other words, when the new callable is called the last few arguments supplied by the user are ignored, according to `argcount`. The remaining arguments are passed to the callable. This allows to use the original callable in a context that attempts to pass more arguments than this callable can handle, e.g. a signal with a fixed number of arguments. See also [bind()](class_callable.md#class_Callable_method_bind). + +\ **Note:** When this method is chained with other similar methods, the order in which the argument list is modified is read from right to left. + +``` + func _ready(): + foo.unbind(1).call(1, 2) # Calls foo(1). + foo.bind(3, 4).unbind(1).call(1, 2) # Calls foo(1, 3, 4), note that it does not change the arguments from bind. +``` + +
+ + + +## Operator Descriptions + + + + + +[bool](class_bool.md) **operator !=**\ (\ right\: [Callable](class_callable.md)\ ) [🔗](#class_Callable_operator_neq_Callable) + +Returns ``true`` if both **Callable**\ s invoke different targets. + +
+ + + + + +[bool](class_bool.md) **operator ==**\ (\ right\: [Callable](class_callable.md)\ ) [🔗](#class_Callable_operator_eq_Callable) + +Returns ``true`` if both **Callable**\ s invoke the same custom target. + diff --git a/docs/Classes/class_callbacktweener.md b/docs/Classes/class_callbacktweener.md new file mode 100644 index 00000000..74f39556 --- /dev/null +++ b/docs/Classes/class_callbacktweener.md @@ -0,0 +1,61 @@ + + + + + + + + + +# CallbackTweener + +**Inherits:** [Tweener](class_tweener.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Calls the specified method after optional delay. + + + +## Description + +**CallbackTweener** is used to call a method in a tweening sequence. See [Tween.tween_callback()](class_tween.md#class_Tween_method_tween_callback) for more usage information. + +The tweener will finish automatically if the callback's target object is freed. + +\ **Note:** [Tween.tween_callback()](class_tween.md#class_Tween_method_tween_callback) is the only correct way to create **CallbackTweener**. Any **CallbackTweener** created manually will not function correctly. + + + +## Methods + + + + + + + + + + +
[CallbackTweener](class_callbacktweener.md)[set_delay](#class_CallbackTweener_method_set_delay)\ (\ delay\: [float](class_float.md)\ )
+ +
+ + + +## Method Descriptions + + + + + +[CallbackTweener](class_callbacktweener.md) **set_delay**\ (\ delay\: [float](class_float.md)\ ) [🔗](#class_CallbackTweener_method_set_delay) + +Makes the callback call delayed by given time in seconds. + +\ **Example:** Call [Node.queue_free()](class_node.md#class_Node_method_queue_free) after 2 seconds: + +``` + var tween = get_tree().create_tween() + tween.tween_callback(queue_free).set_delay(2) +``` + diff --git a/docs/Classes/class_camera2d.md b/docs/Classes/class_camera2d.md new file mode 100644 index 00000000..354b55d8 --- /dev/null +++ b/docs/Classes/class_camera2d.md @@ -0,0 +1,859 @@ + + + + + + + + + +# Camera2D + +**Inherits:** [Node2D](class_node2d.md) **<** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +Camera node for 2D scenes. + + + +## Description + +Camera node for 2D scenes. It forces the screen (current layer) to scroll following this node. This makes it easier (and faster) to program scrollable scenes than manually changing the position of [CanvasItem](class_canvasitem.md)-based nodes. + +Cameras register themselves in the nearest [Viewport](class_viewport.md) node (when ascending the tree). Only one camera can be active per viewport. If no viewport is available ascending the tree, the camera will register in the global viewport. + +This node is intended to be a simple helper to get things going quickly, but more functionality may be desired to change how the camera works. To make your own custom camera node, inherit it from [Node2D](class_node2d.md) and change the transform of the canvas by setting [Viewport.canvas_transform](class_viewport.md#class_Viewport_property_canvas_transform) in [Viewport](class_viewport.md) (you can obtain the current [Viewport](class_viewport.md) by using [Node.get_viewport()](class_node.md#class_Node_method_get_viewport)). + +Note that the **Camera2D** node's [Node2D.global_position](class_node2d.md#class_Node2D_property_global_position) doesn't represent the actual position of the screen, which may differ due to applied smoothing or limits. You can use [get_screen_center_position()](class_camera2d.md#class_Camera2D_method_get_screen_center_position) to get the real position. Same for the node's [Node2D.global_rotation](class_node2d.md#class_Node2D_property_global_rotation) which may be different due to applied rotation smoothing. You can use [get_screen_rotation()](class_camera2d.md#class_Camera2D_method_get_screen_rotation) to get the current rotation of the screen. + + + +## Tutorials + +- [2D Platformer Demo](https://godotengine.org/asset-library/asset/2727) + +- [2D Isometric Demo](https://godotengine.org/asset-library/asset/2718) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[AnchorMode](class_camera2d.md#enum_Camera2D_AnchorMode)[anchor_mode](#class_Camera2D_property_anchor_mode)`1`
[Node](class_node.md)[custom_viewport](#class_Camera2D_property_custom_viewport)
[float](class_float.md)[drag_bottom_margin](#class_Camera2D_property_drag_bottom_margin)`0.2`
[bool](class_bool.md)[drag_horizontal_enabled](#class_Camera2D_property_drag_horizontal_enabled)`false`
[float](class_float.md)[drag_horizontal_offset](#class_Camera2D_property_drag_horizontal_offset)`0.0`
[float](class_float.md)[drag_left_margin](#class_Camera2D_property_drag_left_margin)`0.2`
[float](class_float.md)[drag_right_margin](#class_Camera2D_property_drag_right_margin)`0.2`
[float](class_float.md)[drag_top_margin](#class_Camera2D_property_drag_top_margin)`0.2`
[bool](class_bool.md)[drag_vertical_enabled](#class_Camera2D_property_drag_vertical_enabled)`false`
[float](class_float.md)[drag_vertical_offset](#class_Camera2D_property_drag_vertical_offset)`0.0`
[bool](class_bool.md)[editor_draw_drag_margin](#class_Camera2D_property_editor_draw_drag_margin)`false`
[bool](class_bool.md)[editor_draw_limits](#class_Camera2D_property_editor_draw_limits)`false`
[bool](class_bool.md)[editor_draw_screen](#class_Camera2D_property_editor_draw_screen)`true`
[bool](class_bool.md)[enabled](#class_Camera2D_property_enabled)`true`
[bool](class_bool.md)[ignore_rotation](#class_Camera2D_property_ignore_rotation)`true`
[int](class_int.md)[limit_bottom](#class_Camera2D_property_limit_bottom)`10000000`
[bool](class_bool.md)[limit_enabled](#class_Camera2D_property_limit_enabled)`true`
[int](class_int.md)[limit_left](#class_Camera2D_property_limit_left)`-10000000`
[int](class_int.md)[limit_right](#class_Camera2D_property_limit_right)`10000000`
[bool](class_bool.md)[limit_smoothed](#class_Camera2D_property_limit_smoothed)`false`
[int](class_int.md)[limit_top](#class_Camera2D_property_limit_top)`-10000000`
[Vector2](class_vector2.md)[offset](#class_Camera2D_property_offset)`Vector2(0, 0)`
[bool](class_bool.md)[position_smoothing_enabled](#class_Camera2D_property_position_smoothing_enabled)`false`
[float](class_float.md)[position_smoothing_speed](#class_Camera2D_property_position_smoothing_speed)`5.0`
[Camera2DProcessCallback](class_camera2d.md#enum_Camera2D_Camera2DProcessCallback)[process_callback](#class_Camera2D_property_process_callback)`1`
[bool](class_bool.md)[rotation_smoothing_enabled](#class_Camera2D_property_rotation_smoothing_enabled)`false`
[float](class_float.md)[rotation_smoothing_speed](#class_Camera2D_property_rotation_smoothing_speed)`5.0`
[Vector2](class_vector2.md)[zoom](#class_Camera2D_property_zoom)`Vector2(1, 1)`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
`void`[align](#class_Camera2D_method_align)\ (\ )
`void`[force_update_scroll](#class_Camera2D_method_force_update_scroll)\ (\ )
[float](class_float.md)[get_drag_margin](#class_Camera2D_method_get_drag_margin)\ (\ margin\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const
[int](class_int.md)[get_limit](#class_Camera2D_method_get_limit)\ (\ margin\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const
[Vector2](class_vector2.md)[get_screen_center_position](#class_Camera2D_method_get_screen_center_position)\ (\ ) const
[float](class_float.md)[get_screen_rotation](#class_Camera2D_method_get_screen_rotation)\ (\ ) const
[Vector2](class_vector2.md)[get_target_position](#class_Camera2D_method_get_target_position)\ (\ ) const
[bool](class_bool.md)[is_current](#class_Camera2D_method_is_current)\ (\ ) const
`void`[make_current](#class_Camera2D_method_make_current)\ (\ )
`void`[reset_smoothing](#class_Camera2D_method_reset_smoothing)\ (\ )
`void`[set_drag_margin](#class_Camera2D_method_set_drag_margin)\ (\ margin\: [Side](class_@globalscope.md#enum_@GlobalScope_Side), drag_margin\: [float](class_float.md)\ )
`void`[set_limit](#class_Camera2D_method_set_limit)\ (\ margin\: [Side](class_@globalscope.md#enum_@GlobalScope_Side), limit\: [int](class_int.md)\ )
+ +
+ + + +## Enumerations + + + + + +enum **AnchorMode**: [🔗](#enum_Camera2D_AnchorMode) + + + + + +[AnchorMode](class_camera2d.md#enum_Camera2D_AnchorMode) **ANCHOR_MODE_FIXED_TOP_LEFT** = `0` + +The camera's position is fixed so that the top-left corner is always at the origin. + + + +[AnchorMode](class_camera2d.md#enum_Camera2D_AnchorMode) **ANCHOR_MODE_DRAG_CENTER** = `1` + +The camera's position takes into account vertical/horizontal offsets and the screen size.
+ + + + + +enum **Camera2DProcessCallback**: [🔗](#enum_Camera2D_Camera2DProcessCallback) + + + + + +[Camera2DProcessCallback](class_camera2d.md#enum_Camera2D_Camera2DProcessCallback) **CAMERA2D_PROCESS_PHYSICS** = `0` + +The camera updates during physics frames (see [Node.NOTIFICATION_INTERNAL_PHYSICS_PROCESS](class_node.md#class_Node_constant_NOTIFICATION_INTERNAL_PHYSICS_PROCESS)). + + + +[Camera2DProcessCallback](class_camera2d.md#enum_Camera2D_Camera2DProcessCallback) **CAMERA2D_PROCESS_IDLE** = `1` + +The camera updates during process frames (see [Node.NOTIFICATION_INTERNAL_PROCESS](class_node.md#class_Node_constant_NOTIFICATION_INTERNAL_PROCESS)).
+ + + +## Property Descriptions + + + + + +[AnchorMode](class_camera2d.md#enum_Camera2D_AnchorMode) **anchor_mode** = `1` [🔗](#class_Camera2D_property_anchor_mode) + + + +- `void` **set_anchor_mode**\ (\ value\: [AnchorMode](class_camera2d.md#enum_Camera2D_AnchorMode)\ ) +- [AnchorMode](class_camera2d.md#enum_Camera2D_AnchorMode) **get_anchor_mode**\ (\ ) + +The Camera2D's anchor point. + +
+ + + + + +[Node](class_node.md) **custom_viewport** [🔗](#class_Camera2D_property_custom_viewport) + + + +- `void` **set_custom_viewport**\ (\ value\: [Node](class_node.md)\ ) +- [Node](class_node.md) **get_custom_viewport**\ (\ ) + +The custom [Viewport](class_viewport.md) node attached to the **Camera2D**. If ``null`` or not a [Viewport](class_viewport.md), uses the default viewport instead. + +
+ + + + + +[float](class_float.md) **drag_bottom_margin** = `0.2` [🔗](#class_Camera2D_property_drag_bottom_margin) + + + +- `void` **set_drag_margin**\ (\ margin\: [Side](class_@globalscope.md#enum_@GlobalScope_Side), drag_margin\: [float](class_float.md)\ ) +- [float](class_float.md) **get_drag_margin**\ (\ margin\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const + +Bottom margin needed to drag the camera. A value of ``1`` makes the camera move only when reaching the bottom edge of the screen. + +
+ + + + + +[bool](class_bool.md) **drag_horizontal_enabled** = `false` [🔗](#class_Camera2D_property_drag_horizontal_enabled) + + + +- `void` **set_drag_horizontal_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_drag_horizontal_enabled**\ (\ ) + +If ``true``, the camera only moves when reaching the horizontal (left and right) drag margins. If ``false``, the camera moves horizontally regardless of margins. + +
+ + + + + +[float](class_float.md) **drag_horizontal_offset** = `0.0` [🔗](#class_Camera2D_property_drag_horizontal_offset) + + + +- `void` **set_drag_horizontal_offset**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_drag_horizontal_offset**\ (\ ) + +The relative horizontal drag offset of the camera between the right (``-1``) and left (``1``) drag margins. + +\ **Note:** Used to set the initial horizontal drag offset; determine the current offset; or force the current offset. It's not automatically updated when [drag_horizontal_enabled](class_camera2d.md#class_Camera2D_property_drag_horizontal_enabled) is ``true`` or the drag margins are changed. + +
+ + + + + +[float](class_float.md) **drag_left_margin** = `0.2` [🔗](#class_Camera2D_property_drag_left_margin) + + + +- `void` **set_drag_margin**\ (\ margin\: [Side](class_@globalscope.md#enum_@GlobalScope_Side), drag_margin\: [float](class_float.md)\ ) +- [float](class_float.md) **get_drag_margin**\ (\ margin\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const + +Left margin needed to drag the camera. A value of ``1`` makes the camera move only when reaching the left edge of the screen. + +
+ + + + + +[float](class_float.md) **drag_right_margin** = `0.2` [🔗](#class_Camera2D_property_drag_right_margin) + + + +- `void` **set_drag_margin**\ (\ margin\: [Side](class_@globalscope.md#enum_@GlobalScope_Side), drag_margin\: [float](class_float.md)\ ) +- [float](class_float.md) **get_drag_margin**\ (\ margin\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const + +Right margin needed to drag the camera. A value of ``1`` makes the camera move only when reaching the right edge of the screen. + +
+ + + + + +[float](class_float.md) **drag_top_margin** = `0.2` [🔗](#class_Camera2D_property_drag_top_margin) + + + +- `void` **set_drag_margin**\ (\ margin\: [Side](class_@globalscope.md#enum_@GlobalScope_Side), drag_margin\: [float](class_float.md)\ ) +- [float](class_float.md) **get_drag_margin**\ (\ margin\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const + +Top margin needed to drag the camera. A value of ``1`` makes the camera move only when reaching the top edge of the screen. + +
+ + + + + +[bool](class_bool.md) **drag_vertical_enabled** = `false` [🔗](#class_Camera2D_property_drag_vertical_enabled) + + + +- `void` **set_drag_vertical_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_drag_vertical_enabled**\ (\ ) + +If ``true``, the camera only moves when reaching the vertical (top and bottom) drag margins. If ``false``, the camera moves vertically regardless of the drag margins. + +
+ + + + + +[float](class_float.md) **drag_vertical_offset** = `0.0` [🔗](#class_Camera2D_property_drag_vertical_offset) + + + +- `void` **set_drag_vertical_offset**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_drag_vertical_offset**\ (\ ) + +The relative vertical drag offset of the camera between the bottom (``-1``) and top (``1``) drag margins. + +\ **Note:** Used to set the initial vertical drag offset; determine the current offset; or force the current offset. It's not automatically updated when [drag_vertical_enabled](class_camera2d.md#class_Camera2D_property_drag_vertical_enabled) is ``true`` or the drag margins are changed. + +
+ + + + + +[bool](class_bool.md) **editor_draw_drag_margin** = `false` [🔗](#class_Camera2D_property_editor_draw_drag_margin) + + + +- `void` **set_margin_drawing_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_margin_drawing_enabled**\ (\ ) + +If ``true``, draws the camera's drag margin rectangle in the editor. + +
+ + + + + +[bool](class_bool.md) **editor_draw_limits** = `false` [🔗](#class_Camera2D_property_editor_draw_limits) + + + +- `void` **set_limit_drawing_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_limit_drawing_enabled**\ (\ ) + +If ``true``, draws the camera's limits rectangle in the editor. + +
+ + + + + +[bool](class_bool.md) **editor_draw_screen** = `true` [🔗](#class_Camera2D_property_editor_draw_screen) + + + +- `void` **set_screen_drawing_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_screen_drawing_enabled**\ (\ ) + +If ``true``, draws the camera's screen rectangle in the editor. + +
+ + + + + +[bool](class_bool.md) **enabled** = `true` [🔗](#class_Camera2D_property_enabled) + + + +- `void` **set_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_enabled**\ (\ ) + +Controls whether the camera can be active or not. If ``true``, the **Camera2D** will become the main camera when it enters the scene tree and there is no active camera currently (see [Viewport.get_camera_2d()](class_viewport.md#class_Viewport_method_get_camera_2d)). + +When the camera is currently active and [enabled](class_camera2d.md#class_Camera2D_property_enabled) is set to ``false``, the next enabled **Camera2D** in the scene tree will become active. + +
+ + + + + +[bool](class_bool.md) **ignore_rotation** = `true` [🔗](#class_Camera2D_property_ignore_rotation) + + + +- `void` **set_ignore_rotation**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_ignoring_rotation**\ (\ ) + +If ``true``, the camera's rendered view is not affected by its [Node2D.rotation](class_node2d.md#class_Node2D_property_rotation) and [Node2D.global_rotation](class_node2d.md#class_Node2D_property_global_rotation). + +
+ + + + + +[int](class_int.md) **limit_bottom** = `10000000` [🔗](#class_Camera2D_property_limit_bottom) + + + +- `void` **set_limit**\ (\ margin\: [Side](class_@globalscope.md#enum_@GlobalScope_Side), limit\: [int](class_int.md)\ ) +- [int](class_int.md) **get_limit**\ (\ margin\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const + +Bottom scroll limit in pixels. The camera stops moving when reaching this value, but [offset](class_camera2d.md#class_Camera2D_property_offset) can push the view past the limit. + +
+ + + + + +[bool](class_bool.md) **limit_enabled** = `true` [🔗](#class_Camera2D_property_limit_enabled) + + + +- `void` **set_limit_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_limit_enabled**\ (\ ) + +If ``true``, the limits will be enabled. Disabling this will allow the camera to focus anywhere, when the four ``limit_*`` properties will not work. + +
+ + + + + +[int](class_int.md) **limit_left** = `-10000000` [🔗](#class_Camera2D_property_limit_left) + + + +- `void` **set_limit**\ (\ margin\: [Side](class_@globalscope.md#enum_@GlobalScope_Side), limit\: [int](class_int.md)\ ) +- [int](class_int.md) **get_limit**\ (\ margin\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const + +Left scroll limit in pixels. The camera stops moving when reaching this value, but [offset](class_camera2d.md#class_Camera2D_property_offset) can push the view past the limit. + +
+ + + + + +[int](class_int.md) **limit_right** = `10000000` [🔗](#class_Camera2D_property_limit_right) + + + +- `void` **set_limit**\ (\ margin\: [Side](class_@globalscope.md#enum_@GlobalScope_Side), limit\: [int](class_int.md)\ ) +- [int](class_int.md) **get_limit**\ (\ margin\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const + +Right scroll limit in pixels. The camera stops moving when reaching this value, but [offset](class_camera2d.md#class_Camera2D_property_offset) can push the view past the limit. + +
+ + + + + +[bool](class_bool.md) **limit_smoothed** = `false` [🔗](#class_Camera2D_property_limit_smoothed) + + + +- `void` **set_limit_smoothing_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_limit_smoothing_enabled**\ (\ ) + +If ``true``, the camera smoothly stops when reaches its limits. + +This property has no effect if [position_smoothing_enabled](class_camera2d.md#class_Camera2D_property_position_smoothing_enabled) is ``false``. + +\ **Note:** To immediately update the camera's position to be within limits without smoothing, even with this setting enabled, invoke [reset_smoothing()](class_camera2d.md#class_Camera2D_method_reset_smoothing). + +
+ + + + + +[int](class_int.md) **limit_top** = `-10000000` [🔗](#class_Camera2D_property_limit_top) + + + +- `void` **set_limit**\ (\ margin\: [Side](class_@globalscope.md#enum_@GlobalScope_Side), limit\: [int](class_int.md)\ ) +- [int](class_int.md) **get_limit**\ (\ margin\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const + +Top scroll limit in pixels. The camera stops moving when reaching this value, but [offset](class_camera2d.md#class_Camera2D_property_offset) can push the view past the limit. + +
+ + + + + +[Vector2](class_vector2.md) **offset** = `Vector2(0, 0)` [🔗](#class_Camera2D_property_offset) + + + +- `void` **set_offset**\ (\ value\: [Vector2](class_vector2.md)\ ) +- [Vector2](class_vector2.md) **get_offset**\ (\ ) + +The camera's relative offset. Useful for looking around or camera shake animations. The offsetted camera can go past the limits defined in [limit_top](class_camera2d.md#class_Camera2D_property_limit_top), [limit_bottom](class_camera2d.md#class_Camera2D_property_limit_bottom), [limit_left](class_camera2d.md#class_Camera2D_property_limit_left) and [limit_right](class_camera2d.md#class_Camera2D_property_limit_right). + +
+ + + + + +[bool](class_bool.md) **position_smoothing_enabled** = `false` [🔗](#class_Camera2D_property_position_smoothing_enabled) + + + +- `void` **set_position_smoothing_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_position_smoothing_enabled**\ (\ ) + +If ``true``, the camera's view smoothly moves towards its target position at [position_smoothing_speed](class_camera2d.md#class_Camera2D_property_position_smoothing_speed). + +
+ + + + + +[float](class_float.md) **position_smoothing_speed** = `5.0` [🔗](#class_Camera2D_property_position_smoothing_speed) + + + +- `void` **set_position_smoothing_speed**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_position_smoothing_speed**\ (\ ) + +Speed in pixels per second of the camera's smoothing effect when [position_smoothing_enabled](class_camera2d.md#class_Camera2D_property_position_smoothing_enabled) is ``true``. + +
+ + + + + +[Camera2DProcessCallback](class_camera2d.md#enum_Camera2D_Camera2DProcessCallback) **process_callback** = `1` [🔗](#class_Camera2D_property_process_callback) + + + +- `void` **set_process_callback**\ (\ value\: [Camera2DProcessCallback](class_camera2d.md#enum_Camera2D_Camera2DProcessCallback)\ ) +- [Camera2DProcessCallback](class_camera2d.md#enum_Camera2D_Camera2DProcessCallback) **get_process_callback**\ (\ ) + +The camera's process callback. + +
+ + + + + +[bool](class_bool.md) **rotation_smoothing_enabled** = `false` [🔗](#class_Camera2D_property_rotation_smoothing_enabled) + + + +- `void` **set_rotation_smoothing_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_rotation_smoothing_enabled**\ (\ ) + +If ``true``, the camera's view smoothly rotates, via asymptotic smoothing, to align with its target rotation at [rotation_smoothing_speed](class_camera2d.md#class_Camera2D_property_rotation_smoothing_speed). + +\ **Note:** This property has no effect if [ignore_rotation](class_camera2d.md#class_Camera2D_property_ignore_rotation) is ``true``. + +
+ + + + + +[float](class_float.md) **rotation_smoothing_speed** = `5.0` [🔗](#class_Camera2D_property_rotation_smoothing_speed) + + + +- `void` **set_rotation_smoothing_speed**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_rotation_smoothing_speed**\ (\ ) + +The angular, asymptotic speed of the camera's rotation smoothing effect when [rotation_smoothing_enabled](class_camera2d.md#class_Camera2D_property_rotation_smoothing_enabled) is ``true``. + +
+ + + + + +[Vector2](class_vector2.md) **zoom** = `Vector2(1, 1)` [🔗](#class_Camera2D_property_zoom) + + + +- `void` **set_zoom**\ (\ value\: [Vector2](class_vector2.md)\ ) +- [Vector2](class_vector2.md) **get_zoom**\ (\ ) + +The camera's zoom. Higher values are more zoomed in. For example, a zoom of ``Vector2(2.0, 2.0)`` will be twice as zoomed in on each axis (the view covers an area four times smaller). In contrast, a zoom of ``Vector2(0.5, 0.5)`` will be twice as zoomed out on each axis (the view covers an area four times larger). The X and Y components should generally always be set to the same value, unless you wish to stretch the camera view. + +\ **Note:** [FontFile.oversampling](class_fontfile.md#class_FontFile_property_oversampling) does *not* take **Camera2D** zoom into account. This means that zooming in/out will cause bitmap fonts and rasterized (non-MSDF) dynamic fonts to appear blurry or pixelated unless the font is part of a [CanvasLayer](class_canvaslayer.md) that makes it ignore camera zoom. To ensure text remains crisp regardless of zoom, you can enable MSDF font rendering by enabling [ProjectSettings.gui/theme/default_font_multichannel_signed_distance_field](class_projectsettings.md#class_ProjectSettings_property_gui/theme/default_font_multichannel_signed_distance_field) (applies to the default project font only), or enabling **Multichannel Signed Distance Field** in the import options of a DynamicFont for custom fonts. On system fonts, [SystemFont.multichannel_signed_distance_field](class_systemfont.md#class_SystemFont_property_multichannel_signed_distance_field) can be enabled in the inspector. + +
+ + + +## Method Descriptions + + + + + +`void` **align**\ (\ ) [🔗](#class_Camera2D_method_align) + +Aligns the camera to the tracked node. + +
+ + + + + +`void` **force_update_scroll**\ (\ ) [🔗](#class_Camera2D_method_force_update_scroll) + +Forces the camera to update scroll immediately. + +
+ + + + + +[float](class_float.md) **get_drag_margin**\ (\ margin\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const [🔗](#class_Camera2D_method_get_drag_margin) + +Returns the specified [Side](class_@globalscope.md#enum_@GlobalScope_Side)'s margin. See also [drag_bottom_margin](class_camera2d.md#class_Camera2D_property_drag_bottom_margin), [drag_top_margin](class_camera2d.md#class_Camera2D_property_drag_top_margin), [drag_left_margin](class_camera2d.md#class_Camera2D_property_drag_left_margin), and [drag_right_margin](class_camera2d.md#class_Camera2D_property_drag_right_margin). + +
+ + + + + +[int](class_int.md) **get_limit**\ (\ margin\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const [🔗](#class_Camera2D_method_get_limit) + +Returns the camera limit for the specified [Side](class_@globalscope.md#enum_@GlobalScope_Side). See also [limit_bottom](class_camera2d.md#class_Camera2D_property_limit_bottom), [limit_top](class_camera2d.md#class_Camera2D_property_limit_top), [limit_left](class_camera2d.md#class_Camera2D_property_limit_left), and [limit_right](class_camera2d.md#class_Camera2D_property_limit_right). + +
+ + + + + +[Vector2](class_vector2.md) **get_screen_center_position**\ (\ ) const [🔗](#class_Camera2D_method_get_screen_center_position) + +Returns the center of the screen from this camera's point of view, in global coordinates. + +\ **Note:** The exact targeted position of the camera may be different. See [get_target_position()](class_camera2d.md#class_Camera2D_method_get_target_position). + +
+ + + + + +[float](class_float.md) **get_screen_rotation**\ (\ ) const [🔗](#class_Camera2D_method_get_screen_rotation) + +Returns the current screen rotation from this camera's point of view. + +\ **Note:** The screen rotation can be different from [Node2D.global_rotation](class_node2d.md#class_Node2D_property_global_rotation) if the camera is rotating smoothly due to [rotation_smoothing_enabled](class_camera2d.md#class_Camera2D_property_rotation_smoothing_enabled). + +
+ + + + + +[Vector2](class_vector2.md) **get_target_position**\ (\ ) const [🔗](#class_Camera2D_method_get_target_position) + +Returns this camera's target position, in global coordinates. + +\ **Note:** The returned value is not the same as [Node2D.global_position](class_node2d.md#class_Node2D_property_global_position), as it is affected by the drag properties. It is also not the same as the current position if [position_smoothing_enabled](class_camera2d.md#class_Camera2D_property_position_smoothing_enabled) is ``true`` (see [get_screen_center_position()](class_camera2d.md#class_Camera2D_method_get_screen_center_position)). + +
+ + + + + +[bool](class_bool.md) **is_current**\ (\ ) const [🔗](#class_Camera2D_method_is_current) + +Returns ``true`` if this **Camera2D** is the active camera (see [Viewport.get_camera_2d()](class_viewport.md#class_Viewport_method_get_camera_2d)). + +
+ + + + + +`void` **make_current**\ (\ ) [🔗](#class_Camera2D_method_make_current) + +Forces this **Camera2D** to become the current active one. [enabled](class_camera2d.md#class_Camera2D_property_enabled) must be ``true``. + +
+ + + + + +`void` **reset_smoothing**\ (\ ) [🔗](#class_Camera2D_method_reset_smoothing) + +Sets the camera's position immediately to its current smoothing destination. + +This method has no effect if [position_smoothing_enabled](class_camera2d.md#class_Camera2D_property_position_smoothing_enabled) is ``false``. + +
+ + + + + +`void` **set_drag_margin**\ (\ margin\: [Side](class_@globalscope.md#enum_@GlobalScope_Side), drag_margin\: [float](class_float.md)\ ) [🔗](#class_Camera2D_method_set_drag_margin) + +Sets the specified [Side](class_@globalscope.md#enum_@GlobalScope_Side)'s margin. See also [drag_bottom_margin](class_camera2d.md#class_Camera2D_property_drag_bottom_margin), [drag_top_margin](class_camera2d.md#class_Camera2D_property_drag_top_margin), [drag_left_margin](class_camera2d.md#class_Camera2D_property_drag_left_margin), and [drag_right_margin](class_camera2d.md#class_Camera2D_property_drag_right_margin). + +
+ + + + + +`void` **set_limit**\ (\ margin\: [Side](class_@globalscope.md#enum_@GlobalScope_Side), limit\: [int](class_int.md)\ ) [🔗](#class_Camera2D_method_set_limit) + +Sets the camera limit for the specified [Side](class_@globalscope.md#enum_@GlobalScope_Side). See also [limit_bottom](class_camera2d.md#class_Camera2D_property_limit_bottom), [limit_top](class_camera2d.md#class_Camera2D_property_limit_top), [limit_left](class_camera2d.md#class_Camera2D_property_limit_left), and [limit_right](class_camera2d.md#class_Camera2D_property_limit_right). + diff --git a/docs/Classes/class_camera3d.md b/docs/Classes/class_camera3d.md new file mode 100644 index 00000000..78a33b3f --- /dev/null +++ b/docs/Classes/class_camera3d.md @@ -0,0 +1,736 @@ + + + + + + + + + +# Camera3D + +**Inherits:** [Node3D](class_node3d.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +**Inherited By:** [XRCamera3D](class_xrcamera3d.md) + +Camera node, displays from a point of view. + + + +## Description + +**Camera3D** is a special node that displays what is visible from its current location. Cameras register themselves in the nearest [Viewport](class_viewport.md) node (when ascending the tree). Only one camera can be active per viewport. If no viewport is available ascending the tree, the camera will register in the global viewport. In other words, a camera just provides 3D display capabilities to a [Viewport](class_viewport.md), and, without one, a scene registered in that [Viewport](class_viewport.md) (or higher viewports) can't be displayed. + + + +## Tutorials + +- [Third Person Shooter (TPS) Demo](https://godotengine.org/asset-library/asset/2710) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[CameraAttributes](class_cameraattributes.md)[attributes](#class_Camera3D_property_attributes)
[Compositor](class_compositor.md)[compositor](#class_Camera3D_property_compositor)
[int](class_int.md)[cull_mask](#class_Camera3D_property_cull_mask)`1048575`
[bool](class_bool.md)[current](#class_Camera3D_property_current)`false`
[DopplerTracking](class_camera3d.md#enum_Camera3D_DopplerTracking)[doppler_tracking](#class_Camera3D_property_doppler_tracking)`0`
[Environment](class_environment.md)[environment](#class_Camera3D_property_environment)
[float](class_float.md)[far](#class_Camera3D_property_far)`4000.0`
[float](class_float.md)[fov](#class_Camera3D_property_fov)`75.0`
[Vector2](class_vector2.md)[frustum_offset](#class_Camera3D_property_frustum_offset)`Vector2(0, 0)`
[float](class_float.md)[h_offset](#class_Camera3D_property_h_offset)`0.0`
[KeepAspect](class_camera3d.md#enum_Camera3D_KeepAspect)[keep_aspect](#class_Camera3D_property_keep_aspect)`1`
[float](class_float.md)[near](#class_Camera3D_property_near)`0.05`
[ProjectionType](class_camera3d.md#enum_Camera3D_ProjectionType)[projection](#class_Camera3D_property_projection)`0`
[float](class_float.md)[size](#class_Camera3D_property_size)`1.0`
[float](class_float.md)[v_offset](#class_Camera3D_property_v_offset)`0.0`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
`void`[clear_current](#class_Camera3D_method_clear_current)\ (\ enable_next\: [bool](class_bool.md) = true\ )
[Projection](class_projection.md)[get_camera_projection](#class_Camera3D_method_get_camera_projection)\ (\ ) const
[RID](class_rid.md)[get_camera_rid](#class_Camera3D_method_get_camera_rid)\ (\ ) const
[Transform3D](class_transform3d.md)[get_camera_transform](#class_Camera3D_method_get_camera_transform)\ (\ ) const
[bool](class_bool.md)[get_cull_mask_value](#class_Camera3D_method_get_cull_mask_value)\ (\ layer_number\: [int](class_int.md)\ ) const
[Array](class_array.md)\[[Plane](class_plane.md)\][get_frustum](#class_Camera3D_method_get_frustum)\ (\ ) const
[RID](class_rid.md)[get_pyramid_shape_rid](#class_Camera3D_method_get_pyramid_shape_rid)\ (\ )
[bool](class_bool.md)[is_position_behind](#class_Camera3D_method_is_position_behind)\ (\ world_point\: [Vector3](class_vector3.md)\ ) const
[bool](class_bool.md)[is_position_in_frustum](#class_Camera3D_method_is_position_in_frustum)\ (\ world_point\: [Vector3](class_vector3.md)\ ) const
`void`[make_current](#class_Camera3D_method_make_current)\ (\ )
[Vector3](class_vector3.md)[project_local_ray_normal](#class_Camera3D_method_project_local_ray_normal)\ (\ screen_point\: [Vector2](class_vector2.md)\ ) const
[Vector3](class_vector3.md)[project_position](#class_Camera3D_method_project_position)\ (\ screen_point\: [Vector2](class_vector2.md), z_depth\: [float](class_float.md)\ ) const
[Vector3](class_vector3.md)[project_ray_normal](#class_Camera3D_method_project_ray_normal)\ (\ screen_point\: [Vector2](class_vector2.md)\ ) const
[Vector3](class_vector3.md)[project_ray_origin](#class_Camera3D_method_project_ray_origin)\ (\ screen_point\: [Vector2](class_vector2.md)\ ) const
`void`[set_cull_mask_value](#class_Camera3D_method_set_cull_mask_value)\ (\ layer_number\: [int](class_int.md), value\: [bool](class_bool.md)\ )
`void`[set_frustum](#class_Camera3D_method_set_frustum)\ (\ size\: [float](class_float.md), offset\: [Vector2](class_vector2.md), z_near\: [float](class_float.md), z_far\: [float](class_float.md)\ )
`void`[set_orthogonal](#class_Camera3D_method_set_orthogonal)\ (\ size\: [float](class_float.md), z_near\: [float](class_float.md), z_far\: [float](class_float.md)\ )
`void`[set_perspective](#class_Camera3D_method_set_perspective)\ (\ fov\: [float](class_float.md), z_near\: [float](class_float.md), z_far\: [float](class_float.md)\ )
[Vector2](class_vector2.md)[unproject_position](#class_Camera3D_method_unproject_position)\ (\ world_point\: [Vector3](class_vector3.md)\ ) const
+ +
+ + + +## Enumerations + + + + + +enum **ProjectionType**: [🔗](#enum_Camera3D_ProjectionType) + + + + + +[ProjectionType](class_camera3d.md#enum_Camera3D_ProjectionType) **PROJECTION_PERSPECTIVE** = `0` + +Perspective projection. Objects on the screen becomes smaller when they are far away. + + + +[ProjectionType](class_camera3d.md#enum_Camera3D_ProjectionType) **PROJECTION_ORTHOGONAL** = `1` + +Orthogonal projection, also known as orthographic projection. Objects remain the same size on the screen no matter how far away they are. + + + +[ProjectionType](class_camera3d.md#enum_Camera3D_ProjectionType) **PROJECTION_FRUSTUM** = `2` + +Frustum projection. This mode allows adjusting [frustum_offset](class_camera3d.md#class_Camera3D_property_frustum_offset) to create "tilted frustum" effects.
+ + + + + +enum **KeepAspect**: [🔗](#enum_Camera3D_KeepAspect) + + + + + +[KeepAspect](class_camera3d.md#enum_Camera3D_KeepAspect) **KEEP_WIDTH** = `0` + +Preserves the horizontal aspect ratio; also known as Vert- scaling. This is usually the best option for projects running in portrait mode, as taller aspect ratios will benefit from a wider vertical FOV. + + + +[KeepAspect](class_camera3d.md#enum_Camera3D_KeepAspect) **KEEP_HEIGHT** = `1` + +Preserves the vertical aspect ratio; also known as Hor+ scaling. This is usually the best option for projects running in landscape mode, as wider aspect ratios will automatically benefit from a wider horizontal FOV.
+ + + + + +enum **DopplerTracking**: [🔗](#enum_Camera3D_DopplerTracking) + + + + + +[DopplerTracking](class_camera3d.md#enum_Camera3D_DopplerTracking) **DOPPLER_TRACKING_DISABLED** = `0` + +Disables [Doppler effect](https://en.wikipedia.org/wiki/Doppler_effect) simulation (default). + + + +[DopplerTracking](class_camera3d.md#enum_Camera3D_DopplerTracking) **DOPPLER_TRACKING_IDLE_STEP** = `1` + +Simulate [Doppler effect](https://en.wikipedia.org/wiki/Doppler_effect) by tracking positions of objects that are changed in ``_process``. Changes in the relative velocity of this camera compared to those objects affect how audio is perceived (changing the audio's [AudioStreamPlayer3D.pitch_scale](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_property_pitch_scale)). + + + +[DopplerTracking](class_camera3d.md#enum_Camera3D_DopplerTracking) **DOPPLER_TRACKING_PHYSICS_STEP** = `2` + +Simulate [Doppler effect](https://en.wikipedia.org/wiki/Doppler_effect) by tracking positions of objects that are changed in ``_physics_process``. Changes in the relative velocity of this camera compared to those objects affect how audio is perceived (changing the audio's [AudioStreamPlayer3D.pitch_scale](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_property_pitch_scale)).
+ + + +## Property Descriptions + + + + + +[CameraAttributes](class_cameraattributes.md) **attributes** [🔗](#class_Camera3D_property_attributes) + + + +- `void` **set_attributes**\ (\ value\: [CameraAttributes](class_cameraattributes.md)\ ) +- [CameraAttributes](class_cameraattributes.md) **get_attributes**\ (\ ) + +The [CameraAttributes](class_cameraattributes.md) to use for this camera. + +
+ + + + + +[Compositor](class_compositor.md) **compositor** [🔗](#class_Camera3D_property_compositor) + + + +- `void` **set_compositor**\ (\ value\: [Compositor](class_compositor.md)\ ) +- [Compositor](class_compositor.md) **get_compositor**\ (\ ) + +The [Compositor](class_compositor.md) to use for this camera. + +
+ + + + + +[int](class_int.md) **cull_mask** = `1048575` [🔗](#class_Camera3D_property_cull_mask) + + + +- `void` **set_cull_mask**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_cull_mask**\ (\ ) + +The culling mask that describes which [VisualInstance3D.layers](class_visualinstance3d.md#class_VisualInstance3D_property_layers) are rendered by this camera. By default, all 20 user-visible layers are rendered. + +\ **Note:** Since the [cull_mask](class_camera3d.md#class_Camera3D_property_cull_mask) allows for 32 layers to be stored in total, there are an additional 12 layers that are only used internally by the engine and aren't exposed in the editor. Setting [cull_mask](class_camera3d.md#class_Camera3D_property_cull_mask) using a script allows you to toggle those reserved layers, which can be useful for editor plugins. + +To adjust [cull_mask](class_camera3d.md#class_Camera3D_property_cull_mask) more easily using a script, use [get_cull_mask_value()](class_camera3d.md#class_Camera3D_method_get_cull_mask_value) and [set_cull_mask_value()](class_camera3d.md#class_Camera3D_method_set_cull_mask_value). + +\ **Note:** [VoxelGI](class_voxelgi.md), SDFGI and [LightmapGI](class_lightmapgi.md) will always take all layers into account to determine what contributes to global illumination. If this is an issue, set [GeometryInstance3D.gi_mode](class_geometryinstance3d.md#class_GeometryInstance3D_property_gi_mode) to [GeometryInstance3D.GI_MODE_DISABLED](class_geometryinstance3d.md#class_GeometryInstance3D_constant_GI_MODE_DISABLED) for meshes and [Light3D.light_bake_mode](class_light3d.md#class_Light3D_property_light_bake_mode) to [Light3D.BAKE_DISABLED](class_light3d.md#class_Light3D_constant_BAKE_DISABLED) for lights to exclude them from global illumination. + +
+ + + + + +[bool](class_bool.md) **current** = `false` [🔗](#class_Camera3D_property_current) + + + +- `void` **set_current**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_current**\ (\ ) + +If ``true``, the ancestor [Viewport](class_viewport.md) is currently using this camera. + +If multiple cameras are in the scene, one will always be made current. For example, if two **Camera3D** nodes are present in the scene and only one is current, setting one camera's [current](class_camera3d.md#class_Camera3D_property_current) to ``false`` will cause the other camera to be made current. + +
+ + + + + +[DopplerTracking](class_camera3d.md#enum_Camera3D_DopplerTracking) **doppler_tracking** = `0` [🔗](#class_Camera3D_property_doppler_tracking) + + + +- `void` **set_doppler_tracking**\ (\ value\: [DopplerTracking](class_camera3d.md#enum_Camera3D_DopplerTracking)\ ) +- [DopplerTracking](class_camera3d.md#enum_Camera3D_DopplerTracking) **get_doppler_tracking**\ (\ ) + +If not [DOPPLER_TRACKING_DISABLED](class_camera3d.md#class_Camera3D_constant_DOPPLER_TRACKING_DISABLED), this camera will simulate the [Doppler effect](https://en.wikipedia.org/wiki/Doppler_effect) for objects changed in particular ``_process`` methods. + +\ **Note:** The Doppler effect will only be heard on [AudioStreamPlayer3D](class_audiostreamplayer3d.md)\ s if [AudioStreamPlayer3D.doppler_tracking](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_property_doppler_tracking) is not set to [AudioStreamPlayer3D.DOPPLER_TRACKING_DISABLED](class_audiostreamplayer3d.md#class_AudioStreamPlayer3D_constant_DOPPLER_TRACKING_DISABLED). + +
+ + + + + +[Environment](class_environment.md) **environment** [🔗](#class_Camera3D_property_environment) + + + +- `void` **set_environment**\ (\ value\: [Environment](class_environment.md)\ ) +- [Environment](class_environment.md) **get_environment**\ (\ ) + +The [Environment](class_environment.md) to use for this camera. + +
+ + + + + +[float](class_float.md) **far** = `4000.0` [🔗](#class_Camera3D_property_far) + + + +- `void` **set_far**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_far**\ (\ ) + +The distance to the far culling boundary for this camera relative to its local Z axis. Higher values allow the camera to see further away, while decreasing [far](class_camera3d.md#class_Camera3D_property_far) can improve performance if it results in objects being partially or fully culled. + +
+ + + + + +[float](class_float.md) **fov** = `75.0` [🔗](#class_Camera3D_property_fov) + + + +- `void` **set_fov**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_fov**\ (\ ) + +The camera's field of view angle (in degrees). Only applicable in perspective mode. Since [keep_aspect](class_camera3d.md#class_Camera3D_property_keep_aspect) locks one axis, [fov](class_camera3d.md#class_Camera3D_property_fov) sets the other axis' field of view angle. + +For reference, the default vertical field of view value (``75.0``) is equivalent to a horizontal FOV of: + +- ~91.31 degrees in a 4:3 viewport + +- ~101.67 degrees in a 16:10 viewport + +- ~107.51 degrees in a 16:9 viewport + +- ~121.63 degrees in a 21:9 viewport + +
+ + + + + +[Vector2](class_vector2.md) **frustum_offset** = `Vector2(0, 0)` [🔗](#class_Camera3D_property_frustum_offset) + + + +- `void` **set_frustum_offset**\ (\ value\: [Vector2](class_vector2.md)\ ) +- [Vector2](class_vector2.md) **get_frustum_offset**\ (\ ) + +The camera's frustum offset. This can be changed from the default to create "tilted frustum" effects such as [Y-shearing](https://zdoom.org/wiki/Y-shearing). + +\ **Note:** Only effective if [projection](class_camera3d.md#class_Camera3D_property_projection) is [PROJECTION_FRUSTUM](class_camera3d.md#class_Camera3D_constant_PROJECTION_FRUSTUM). + +
+ + + + + +[float](class_float.md) **h_offset** = `0.0` [🔗](#class_Camera3D_property_h_offset) + + + +- `void` **set_h_offset**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_h_offset**\ (\ ) + +The horizontal (X) offset of the camera viewport. + +
+ + + + + +[KeepAspect](class_camera3d.md#enum_Camera3D_KeepAspect) **keep_aspect** = `1` [🔗](#class_Camera3D_property_keep_aspect) + + + +- `void` **set_keep_aspect_mode**\ (\ value\: [KeepAspect](class_camera3d.md#enum_Camera3D_KeepAspect)\ ) +- [KeepAspect](class_camera3d.md#enum_Camera3D_KeepAspect) **get_keep_aspect_mode**\ (\ ) + +The axis to lock during [fov](class_camera3d.md#class_Camera3D_property_fov)/[size](class_camera3d.md#class_Camera3D_property_size) adjustments. Can be either [KEEP_WIDTH](class_camera3d.md#class_Camera3D_constant_KEEP_WIDTH) or [KEEP_HEIGHT](class_camera3d.md#class_Camera3D_constant_KEEP_HEIGHT). + +
+ + + + + +[float](class_float.md) **near** = `0.05` [🔗](#class_Camera3D_property_near) + + + +- `void` **set_near**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_near**\ (\ ) + +The distance to the near culling boundary for this camera relative to its local Z axis. Lower values allow the camera to see objects more up close to its origin, at the cost of lower precision across the *entire* range. Values lower than the default can lead to increased Z-fighting. + +
+ + + + + +[ProjectionType](class_camera3d.md#enum_Camera3D_ProjectionType) **projection** = `0` [🔗](#class_Camera3D_property_projection) + + + +- `void` **set_projection**\ (\ value\: [ProjectionType](class_camera3d.md#enum_Camera3D_ProjectionType)\ ) +- [ProjectionType](class_camera3d.md#enum_Camera3D_ProjectionType) **get_projection**\ (\ ) + +The camera's projection mode. In [PROJECTION_PERSPECTIVE](class_camera3d.md#class_Camera3D_constant_PROJECTION_PERSPECTIVE) mode, objects' Z distance from the camera's local space scales their perceived size. + +
+ + + + + +[float](class_float.md) **size** = `1.0` [🔗](#class_Camera3D_property_size) + + + +- `void` **set_size**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_size**\ (\ ) + +The camera's size in meters measured as the diameter of the width or height, depending on [keep_aspect](class_camera3d.md#class_Camera3D_property_keep_aspect). Only applicable in orthogonal and frustum modes. + +
+ + + + + +[float](class_float.md) **v_offset** = `0.0` [🔗](#class_Camera3D_property_v_offset) + + + +- `void` **set_v_offset**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_v_offset**\ (\ ) + +The vertical (Y) offset of the camera viewport. + +
+ + + +## Method Descriptions + + + + + +`void` **clear_current**\ (\ enable_next\: [bool](class_bool.md) = true\ ) [🔗](#class_Camera3D_method_clear_current) + +If this is the current camera, remove it from being current. If `enable_next` is ``true``, request to make the next camera current, if any. + +
+ + + + + +[Projection](class_projection.md) **get_camera_projection**\ (\ ) const [🔗](#class_Camera3D_method_get_camera_projection) + +Returns the projection matrix that this camera uses to render to its associated viewport. The camera must be part of the scene tree to function. + +
+ + + + + +[RID](class_rid.md) **get_camera_rid**\ (\ ) const [🔗](#class_Camera3D_method_get_camera_rid) + +Returns the camera's RID from the [RenderingServer](class_renderingserver.md). + +
+ + + + + +[Transform3D](class_transform3d.md) **get_camera_transform**\ (\ ) const [🔗](#class_Camera3D_method_get_camera_transform) + +Returns the transform of the camera plus the vertical ([v_offset](class_camera3d.md#class_Camera3D_property_v_offset)) and horizontal ([h_offset](class_camera3d.md#class_Camera3D_property_h_offset)) offsets; and any other adjustments made to the position and orientation of the camera by subclassed cameras such as [XRCamera3D](class_xrcamera3d.md). + +
+ + + + + +[bool](class_bool.md) **get_cull_mask_value**\ (\ layer_number\: [int](class_int.md)\ ) const [🔗](#class_Camera3D_method_get_cull_mask_value) + +Returns whether or not the specified layer of the [cull_mask](class_camera3d.md#class_Camera3D_property_cull_mask) is enabled, given a `layer_number` between 1 and 20. + +
+ + + + + +[Array](class_array.md)\[[Plane](class_plane.md)\] **get_frustum**\ (\ ) const [🔗](#class_Camera3D_method_get_frustum) + +Returns the camera's frustum planes in world space units as an array of [Plane](class_plane.md)\ s in the following order: near, far, left, top, right, bottom. Not to be confused with [frustum_offset](class_camera3d.md#class_Camera3D_property_frustum_offset). + +
+ + + + + +[RID](class_rid.md) **get_pyramid_shape_rid**\ (\ ) [🔗](#class_Camera3D_method_get_pyramid_shape_rid) + +Returns the RID of a pyramid shape encompassing the camera's view frustum, ignoring the camera's near plane. The tip of the pyramid represents the position of the camera. + +
+ + + + + +[bool](class_bool.md) **is_position_behind**\ (\ world_point\: [Vector3](class_vector3.md)\ ) const [🔗](#class_Camera3D_method_is_position_behind) + +Returns ``true`` if the given position is behind the camera (the blue part of the linked diagram). [See this diagram](https://raw.githubusercontent.com/Redot-Engine/redot-docs/master/img/camera3d_position_frustum.png) for an overview of position query methods. + +\ **Note:** A position which returns ``false`` may still be outside the camera's field of view. + +
+ + + + + +[bool](class_bool.md) **is_position_in_frustum**\ (\ world_point\: [Vector3](class_vector3.md)\ ) const [🔗](#class_Camera3D_method_is_position_in_frustum) + +Returns ``true`` if the given position is inside the camera's frustum (the green part of the linked diagram). [See this diagram](https://raw.githubusercontent.com/Redot-Engine/redot-docs/master/img/camera3d_position_frustum.png) for an overview of position query methods. + +
+ + + + + +`void` **make_current**\ (\ ) [🔗](#class_Camera3D_method_make_current) + +Makes this camera the current camera for the [Viewport](class_viewport.md) (see class description). If the camera node is outside the scene tree, it will attempt to become current once it's added. + +
+ + + + + +[Vector3](class_vector3.md) **project_local_ray_normal**\ (\ screen_point\: [Vector2](class_vector2.md)\ ) const [🔗](#class_Camera3D_method_project_local_ray_normal) + +Returns a normal vector from the screen point location directed along the camera. Orthogonal cameras are normalized. Perspective cameras account for perspective, screen width/height, etc. + +
+ + + + + +[Vector3](class_vector3.md) **project_position**\ (\ screen_point\: [Vector2](class_vector2.md), z_depth\: [float](class_float.md)\ ) const [🔗](#class_Camera3D_method_project_position) + +Returns the 3D point in world space that maps to the given 2D coordinate in the [Viewport](class_viewport.md) rectangle on a plane that is the given `z_depth` distance into the scene away from the camera. + +
+ + + + + +[Vector3](class_vector3.md) **project_ray_normal**\ (\ screen_point\: [Vector2](class_vector2.md)\ ) const [🔗](#class_Camera3D_method_project_ray_normal) + +Returns a normal vector in world space, that is the result of projecting a point on the [Viewport](class_viewport.md) rectangle by the inverse camera projection. This is useful for casting rays in the form of (origin, normal) for object intersection or picking. + +
+ + + + + +[Vector3](class_vector3.md) **project_ray_origin**\ (\ screen_point\: [Vector2](class_vector2.md)\ ) const [🔗](#class_Camera3D_method_project_ray_origin) + +Returns a 3D position in world space, that is the result of projecting a point on the [Viewport](class_viewport.md) rectangle by the inverse camera projection. This is useful for casting rays in the form of (origin, normal) for object intersection or picking. + +
+ + + + + +`void` **set_cull_mask_value**\ (\ layer_number\: [int](class_int.md), value\: [bool](class_bool.md)\ ) [🔗](#class_Camera3D_method_set_cull_mask_value) + +Based on `value`, enables or disables the specified layer in the [cull_mask](class_camera3d.md#class_Camera3D_property_cull_mask), given a `layer_number` between 1 and 20. + +
+ + + + + +`void` **set_frustum**\ (\ size\: [float](class_float.md), offset\: [Vector2](class_vector2.md), z_near\: [float](class_float.md), z_far\: [float](class_float.md)\ ) [🔗](#class_Camera3D_method_set_frustum) + +Sets the camera projection to frustum mode (see [PROJECTION_FRUSTUM](class_camera3d.md#class_Camera3D_constant_PROJECTION_FRUSTUM)), by specifying a `size`, an `offset`, and the `z_near` and `z_far` clip planes in world space units. See also [frustum_offset](class_camera3d.md#class_Camera3D_property_frustum_offset). + +
+ + + + + +`void` **set_orthogonal**\ (\ size\: [float](class_float.md), z_near\: [float](class_float.md), z_far\: [float](class_float.md)\ ) [🔗](#class_Camera3D_method_set_orthogonal) + +Sets the camera projection to orthogonal mode (see [PROJECTION_ORTHOGONAL](class_camera3d.md#class_Camera3D_constant_PROJECTION_ORTHOGONAL)), by specifying a `size`, and the `z_near` and `z_far` clip planes in world space units. + +As a hint, 3D games that look 2D often use this projection, with `size` specified in pixels. + +
+ + + + + +`void` **set_perspective**\ (\ fov\: [float](class_float.md), z_near\: [float](class_float.md), z_far\: [float](class_float.md)\ ) [🔗](#class_Camera3D_method_set_perspective) + +Sets the camera projection to perspective mode (see [PROJECTION_PERSPECTIVE](class_camera3d.md#class_Camera3D_constant_PROJECTION_PERSPECTIVE)), by specifying a `fov` (field of view) angle in degrees, and the `z_near` and `z_far` clip planes in world space units. + +
+ + + + + +[Vector2](class_vector2.md) **unproject_position**\ (\ world_point\: [Vector3](class_vector3.md)\ ) const [🔗](#class_Camera3D_method_unproject_position) + +Returns the 2D coordinate in the [Viewport](class_viewport.md) rectangle that maps to the given 3D point in world space. + +\ **Note:** When using this to position GUI elements over a 3D viewport, use [is_position_behind()](class_camera3d.md#class_Camera3D_method_is_position_behind) to prevent them from appearing if the 3D point is behind the camera: + +``` + # This code block is part of a script that inherits from Node3D. + # `control` is a reference to a node inheriting from Control. + control.visible = not get_viewport().get_camera_3d().is_position_behind(global_transform.origin) + control.position = get_viewport().get_camera_3d().unproject_position(global_transform.origin) +``` + diff --git a/docs/Classes/class_cameraattributes.md b/docs/Classes/class_cameraattributes.md new file mode 100644 index 00000000..6a6269f2 --- /dev/null +++ b/docs/Classes/class_cameraattributes.md @@ -0,0 +1,148 @@ + + + + + + + + + +# CameraAttributes + +**Inherits:** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +**Inherited By:** [CameraAttributesPhysical](class_cameraattributesphysical.md), [CameraAttributesPractical](class_cameraattributespractical.md) + +Parent class for camera settings. + + + +## Description + +Controls camera-specific attributes such as depth of field and exposure override. + +When used in a [WorldEnvironment](class_worldenvironment.md) it provides default settings for exposure, auto-exposure, and depth of field that will be used by all cameras without their own **CameraAttributes**, including the editor camera. When used in a [Camera3D](class_camera3d.md) it will override any **CameraAttributes** set in the [WorldEnvironment](class_worldenvironment.md). When used in [VoxelGI](class_voxelgi.md) or [LightmapGI](class_lightmapgi.md), only the exposure settings will be used. + +See also [Environment](class_environment.md) for general 3D environment settings. + +This is a pure virtual class that is inherited by [CameraAttributesPhysical](class_cameraattributesphysical.md) and [CameraAttributesPractical](class_cameraattributespractical.md). + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[auto_exposure_enabled](#class_CameraAttributes_property_auto_exposure_enabled)`false`
[float](class_float.md)[auto_exposure_scale](#class_CameraAttributes_property_auto_exposure_scale)`0.4`
[float](class_float.md)[auto_exposure_speed](#class_CameraAttributes_property_auto_exposure_speed)`0.5`
[float](class_float.md)[exposure_multiplier](#class_CameraAttributes_property_exposure_multiplier)`1.0`
[float](class_float.md)[exposure_sensitivity](#class_CameraAttributes_property_exposure_sensitivity)`100.0`
+ +
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **auto_exposure_enabled** = `false` [🔗](#class_CameraAttributes_property_auto_exposure_enabled) + + + +- `void` **set_auto_exposure_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_auto_exposure_enabled**\ (\ ) + +If ``true``, enables the tonemapping auto exposure mode of the scene renderer. If ``true``, the renderer will automatically determine the exposure setting to adapt to the scene's illumination and the observed light. + +
+ + + + + +[float](class_float.md) **auto_exposure_scale** = `0.4` [🔗](#class_CameraAttributes_property_auto_exposure_scale) + + + +- `void` **set_auto_exposure_scale**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_auto_exposure_scale**\ (\ ) + +The scale of the auto exposure effect. Affects the intensity of auto exposure. + +
+ + + + + +[float](class_float.md) **auto_exposure_speed** = `0.5` [🔗](#class_CameraAttributes_property_auto_exposure_speed) + + + +- `void` **set_auto_exposure_speed**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_auto_exposure_speed**\ (\ ) + +The speed of the auto exposure effect. Affects the time needed for the camera to perform auto exposure. + +
+ + + + + +[float](class_float.md) **exposure_multiplier** = `1.0` [🔗](#class_CameraAttributes_property_exposure_multiplier) + + + +- `void` **set_exposure_multiplier**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_exposure_multiplier**\ (\ ) + +Multiplier for the exposure amount. A higher value results in a brighter image. + +
+ + + + + +[float](class_float.md) **exposure_sensitivity** = `100.0` [🔗](#class_CameraAttributes_property_exposure_sensitivity) + + + +- `void` **set_exposure_sensitivity**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_exposure_sensitivity**\ (\ ) + +Sensitivity of camera sensors, measured in ISO. A higher sensitivity results in a brighter image. + +If [auto_exposure_enabled](class_cameraattributes.md#class_CameraAttributes_property_auto_exposure_enabled) is ``true``, this can be used as a method of exposure compensation, doubling the value will increase the exposure value (measured in EV100) by 1 stop. + +\ **Note:** Only available when [ProjectSettings.rendering/lights_and_shadows/use_physical_light_units](class_projectsettings.md#class_ProjectSettings_property_rendering/lights_and_shadows/use_physical_light_units) is enabled. + diff --git a/docs/Classes/class_cameraattributesphysical.md b/docs/Classes/class_cameraattributesphysical.md new file mode 100644 index 00000000..01062b71 --- /dev/null +++ b/docs/Classes/class_cameraattributesphysical.md @@ -0,0 +1,241 @@ + + + + + + + + + +# CameraAttributesPhysical + +**Inherits:** [CameraAttributes](class_cameraattributes.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Physically-based camera settings. + + + +## Description + +**CameraAttributesPhysical** is used to set rendering settings based on a physically-based camera's settings. It is responsible for exposure, auto-exposure, and depth of field. + +When used in a [WorldEnvironment](class_worldenvironment.md) it provides default settings for exposure, auto-exposure, and depth of field that will be used by all cameras without their own [CameraAttributes](class_cameraattributes.md), including the editor camera. When used in a [Camera3D](class_camera3d.md) it will override any [CameraAttributes](class_cameraattributes.md) set in the [WorldEnvironment](class_worldenvironment.md) and will override the [Camera3D](class_camera3d.md)\ s [Camera3D.far](class_camera3d.md#class_Camera3D_property_far), [Camera3D.near](class_camera3d.md#class_Camera3D_property_near), [Camera3D.fov](class_camera3d.md#class_Camera3D_property_fov), and [Camera3D.keep_aspect](class_camera3d.md#class_Camera3D_property_keep_aspect) properties. When used in [VoxelGI](class_voxelgi.md) or [LightmapGI](class_lightmapgi.md), only the exposure settings will be used. + +The default settings are intended for use in an outdoor environment, tips for settings for use in an indoor environment can be found in each setting's documentation. + +\ **Note:** Depth of field blur is only supported in the Forward+ and Mobile rendering methods, not Compatibility. + + + +## Tutorials + +- [Physical light and camera units](../tutorials/3d/physical_light_and_camera_units.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[auto_exposure_max_exposure_value](#class_CameraAttributesPhysical_property_auto_exposure_max_exposure_value)`10.0`
[float](class_float.md)[auto_exposure_min_exposure_value](#class_CameraAttributesPhysical_property_auto_exposure_min_exposure_value)`-8.0`
[float](class_float.md)[exposure_aperture](#class_CameraAttributesPhysical_property_exposure_aperture)`16.0`
[float](class_float.md)[exposure_shutter_speed](#class_CameraAttributesPhysical_property_exposure_shutter_speed)`100.0`
[float](class_float.md)[frustum_far](#class_CameraAttributesPhysical_property_frustum_far)`4000.0`
[float](class_float.md)[frustum_focal_length](#class_CameraAttributesPhysical_property_frustum_focal_length)`35.0`
[float](class_float.md)[frustum_focus_distance](#class_CameraAttributesPhysical_property_frustum_focus_distance)`10.0`
[float](class_float.md)[frustum_near](#class_CameraAttributesPhysical_property_frustum_near)`0.05`
+ + + +## Methods + + + + + + + + + + +
[float](class_float.md)[get_fov](#class_CameraAttributesPhysical_method_get_fov)\ (\ ) const
+ +
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **auto_exposure_max_exposure_value** = `10.0` [🔗](#class_CameraAttributesPhysical_property_auto_exposure_max_exposure_value) + + + +- `void` **set_auto_exposure_max_exposure_value**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_auto_exposure_max_exposure_value**\ (\ ) + +The maximum luminance (in EV100) used when calculating auto exposure. When calculating scene average luminance, color values will be clamped to at least this value. This limits the auto-exposure from exposing below a certain brightness, resulting in a cut off point where the scene will remain bright. + +
+ + + + + +[float](class_float.md) **auto_exposure_min_exposure_value** = `-8.0` [🔗](#class_CameraAttributesPhysical_property_auto_exposure_min_exposure_value) + + + +- `void` **set_auto_exposure_min_exposure_value**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_auto_exposure_min_exposure_value**\ (\ ) + +The minimum luminance (in EV100) used when calculating auto exposure. When calculating scene average luminance, color values will be clamped to at least this value. This limits the auto-exposure from exposing above a certain brightness, resulting in a cut off point where the scene will remain dark. + +
+ + + + + +[float](class_float.md) **exposure_aperture** = `16.0` [🔗](#class_CameraAttributesPhysical_property_exposure_aperture) + + + +- `void` **set_aperture**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_aperture**\ (\ ) + +Size of the aperture of the camera, measured in f-stops. An f-stop is a unitless ratio between the focal length of the camera and the diameter of the aperture. A high aperture setting will result in a smaller aperture which leads to a dimmer image and sharper focus. A low aperture results in a wide aperture which lets in more light resulting in a brighter, less-focused image. Default is appropriate for outdoors at daytime (i.e. for use with a default [DirectionalLight3D](class_directionallight3d.md)), for indoor lighting, a value between 2 and 4 is more appropriate. + +Only available when [ProjectSettings.rendering/lights_and_shadows/use_physical_light_units](class_projectsettings.md#class_ProjectSettings_property_rendering/lights_and_shadows/use_physical_light_units) is enabled. + +
+ + + + + +[float](class_float.md) **exposure_shutter_speed** = `100.0` [🔗](#class_CameraAttributesPhysical_property_exposure_shutter_speed) + + + +- `void` **set_shutter_speed**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_shutter_speed**\ (\ ) + +Time for shutter to open and close, evaluated as ``1 / shutter_speed`` seconds. A higher value will allow less light (leading to a darker image), while a lower value will allow more light (leading to a brighter image). + +Only available when [ProjectSettings.rendering/lights_and_shadows/use_physical_light_units](class_projectsettings.md#class_ProjectSettings_property_rendering/lights_and_shadows/use_physical_light_units) is enabled. + +
+ + + + + +[float](class_float.md) **frustum_far** = `4000.0` [🔗](#class_CameraAttributesPhysical_property_frustum_far) + + + +- `void` **set_far**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_far**\ (\ ) + +Override value for [Camera3D.far](class_camera3d.md#class_Camera3D_property_far). Used internally when calculating depth of field. When attached to a [Camera3D](class_camera3d.md) as its [Camera3D.attributes](class_camera3d.md#class_Camera3D_property_attributes), it will override the [Camera3D.far](class_camera3d.md#class_Camera3D_property_far) property. + +
+ + + + + +[float](class_float.md) **frustum_focal_length** = `35.0` [🔗](#class_CameraAttributesPhysical_property_frustum_focal_length) + + + +- `void` **set_focal_length**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_focal_length**\ (\ ) + +Distance between camera lens and camera aperture, measured in millimeters. Controls field of view and depth of field. A larger focal length will result in a smaller field of view and a narrower depth of field meaning fewer objects will be in focus. A smaller focal length will result in a wider field of view and a larger depth of field meaning more objects will be in focus. When attached to a [Camera3D](class_camera3d.md) as its [Camera3D.attributes](class_camera3d.md#class_Camera3D_property_attributes), it will override the [Camera3D.fov](class_camera3d.md#class_Camera3D_property_fov) property and the [Camera3D.keep_aspect](class_camera3d.md#class_Camera3D_property_keep_aspect) property. + +
+ + + + + +[float](class_float.md) **frustum_focus_distance** = `10.0` [🔗](#class_CameraAttributesPhysical_property_frustum_focus_distance) + + + +- `void` **set_focus_distance**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_focus_distance**\ (\ ) + +Distance from camera of object that will be in focus, measured in meters. Internally this will be clamped to be at least 1 millimeter larger than [frustum_focal_length](class_cameraattributesphysical.md#class_CameraAttributesPhysical_property_frustum_focal_length). + +
+ + + + + +[float](class_float.md) **frustum_near** = `0.05` [🔗](#class_CameraAttributesPhysical_property_frustum_near) + + + +- `void` **set_near**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_near**\ (\ ) + +Override value for [Camera3D.near](class_camera3d.md#class_Camera3D_property_near). Used internally when calculating depth of field. When attached to a [Camera3D](class_camera3d.md) as its [Camera3D.attributes](class_camera3d.md#class_Camera3D_property_attributes), it will override the [Camera3D.near](class_camera3d.md#class_Camera3D_property_near) property. + +
+ + + +## Method Descriptions + + + + + +[float](class_float.md) **get_fov**\ (\ ) const [🔗](#class_CameraAttributesPhysical_method_get_fov) + +Returns the vertical field of view that corresponds to the [frustum_focal_length](class_cameraattributesphysical.md#class_CameraAttributesPhysical_property_frustum_focal_length). This value is calculated internally whenever [frustum_focal_length](class_cameraattributesphysical.md#class_CameraAttributesPhysical_property_frustum_focal_length) is changed. + diff --git a/docs/Classes/class_cameraattributespractical.md b/docs/Classes/class_cameraattributespractical.md new file mode 100644 index 00000000..7ea218c4 --- /dev/null +++ b/docs/Classes/class_cameraattributespractical.md @@ -0,0 +1,226 @@ + + + + + + + + + +# CameraAttributesPractical + +**Inherits:** [CameraAttributes](class_cameraattributes.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Camera settings in an easy to use format. + + + +## Description + +Controls camera-specific attributes such as auto-exposure, depth of field, and exposure override. + +When used in a [WorldEnvironment](class_worldenvironment.md) it provides default settings for exposure, auto-exposure, and depth of field that will be used by all cameras without their own [CameraAttributes](class_cameraattributes.md), including the editor camera. When used in a [Camera3D](class_camera3d.md) it will override any [CameraAttributes](class_cameraattributes.md) set in the [WorldEnvironment](class_worldenvironment.md). When used in [VoxelGI](class_voxelgi.md) or [LightmapGI](class_lightmapgi.md), only the exposure settings will be used. + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[auto_exposure_max_sensitivity](#class_CameraAttributesPractical_property_auto_exposure_max_sensitivity)`800.0`
[float](class_float.md)[auto_exposure_min_sensitivity](#class_CameraAttributesPractical_property_auto_exposure_min_sensitivity)`0.0`
[float](class_float.md)[dof_blur_amount](#class_CameraAttributesPractical_property_dof_blur_amount)`0.1`
[float](class_float.md)[dof_blur_far_distance](#class_CameraAttributesPractical_property_dof_blur_far_distance)`10.0`
[bool](class_bool.md)[dof_blur_far_enabled](#class_CameraAttributesPractical_property_dof_blur_far_enabled)`false`
[float](class_float.md)[dof_blur_far_transition](#class_CameraAttributesPractical_property_dof_blur_far_transition)`5.0`
[float](class_float.md)[dof_blur_near_distance](#class_CameraAttributesPractical_property_dof_blur_near_distance)`2.0`
[bool](class_bool.md)[dof_blur_near_enabled](#class_CameraAttributesPractical_property_dof_blur_near_enabled)`false`
[float](class_float.md)[dof_blur_near_transition](#class_CameraAttributesPractical_property_dof_blur_near_transition)`1.0`
+ +
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **auto_exposure_max_sensitivity** = `800.0` [🔗](#class_CameraAttributesPractical_property_auto_exposure_max_sensitivity) + + + +- `void` **set_auto_exposure_max_sensitivity**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_auto_exposure_max_sensitivity**\ (\ ) + +The maximum sensitivity (in ISO) used when calculating auto exposure. When calculating scene average luminance, color values will be clamped to at least this value. This limits the auto-exposure from exposing below a certain brightness, resulting in a cut off point where the scene will remain bright. + +
+ + + + + +[float](class_float.md) **auto_exposure_min_sensitivity** = `0.0` [🔗](#class_CameraAttributesPractical_property_auto_exposure_min_sensitivity) + + + +- `void` **set_auto_exposure_min_sensitivity**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_auto_exposure_min_sensitivity**\ (\ ) + +The minimum sensitivity (in ISO) used when calculating auto exposure. When calculating scene average luminance, color values will be clamped to at least this value. This limits the auto-exposure from exposing above a certain brightness, resulting in a cut off point where the scene will remain dark. + +
+ + + + + +[float](class_float.md) **dof_blur_amount** = `0.1` [🔗](#class_CameraAttributesPractical_property_dof_blur_amount) + + + +- `void` **set_dof_blur_amount**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_dof_blur_amount**\ (\ ) + +Sets the maximum amount of blur. When using physically-based blur amounts, will instead act as a multiplier. High values lead to an increased amount of blurriness, but can be much more expensive to calculate. It is best to keep this as low as possible for a given art style. + +
+ + + + + +[float](class_float.md) **dof_blur_far_distance** = `10.0` [🔗](#class_CameraAttributesPractical_property_dof_blur_far_distance) + + + +- `void` **set_dof_blur_far_distance**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_dof_blur_far_distance**\ (\ ) + +Objects further from the [Camera3D](class_camera3d.md) by this amount will be blurred by the depth of field effect. Measured in meters. + +
+ + + + + +[bool](class_bool.md) **dof_blur_far_enabled** = `false` [🔗](#class_CameraAttributesPractical_property_dof_blur_far_enabled) + + + +- `void` **set_dof_blur_far_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_dof_blur_far_enabled**\ (\ ) + +Enables depth of field blur for objects further than [dof_blur_far_distance](class_cameraattributespractical.md#class_CameraAttributesPractical_property_dof_blur_far_distance). Strength of blur is controlled by [dof_blur_amount](class_cameraattributespractical.md#class_CameraAttributesPractical_property_dof_blur_amount) and modulated by [dof_blur_far_transition](class_cameraattributespractical.md#class_CameraAttributesPractical_property_dof_blur_far_transition). + +\ **Note:** Depth of field blur is only supported in the Forward+ and Mobile rendering methods, not Compatibility. + +\ **Note:** Depth of field blur is not supported on viewports that have a transparent background (where [Viewport.transparent_bg](class_viewport.md#class_Viewport_property_transparent_bg) is ``true``). + +
+ + + + + +[float](class_float.md) **dof_blur_far_transition** = `5.0` [🔗](#class_CameraAttributesPractical_property_dof_blur_far_transition) + + + +- `void` **set_dof_blur_far_transition**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_dof_blur_far_transition**\ (\ ) + +When positive, distance over which (starting from [dof_blur_far_distance](class_cameraattributespractical.md#class_CameraAttributesPractical_property_dof_blur_far_distance)) blur effect will scale from 0 to [dof_blur_amount](class_cameraattributespractical.md#class_CameraAttributesPractical_property_dof_blur_amount). When negative, uses physically-based scaling so depth of field effect will scale from 0 at [dof_blur_far_distance](class_cameraattributespractical.md#class_CameraAttributesPractical_property_dof_blur_far_distance) and will increase in a physically accurate way as objects get further from the [Camera3D](class_camera3d.md). + +
+ + + + + +[float](class_float.md) **dof_blur_near_distance** = `2.0` [🔗](#class_CameraAttributesPractical_property_dof_blur_near_distance) + + + +- `void` **set_dof_blur_near_distance**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_dof_blur_near_distance**\ (\ ) + +Objects closer from the [Camera3D](class_camera3d.md) by this amount will be blurred by the depth of field effect. Measured in meters. + +
+ + + + + +[bool](class_bool.md) **dof_blur_near_enabled** = `false` [🔗](#class_CameraAttributesPractical_property_dof_blur_near_enabled) + + + +- `void` **set_dof_blur_near_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_dof_blur_near_enabled**\ (\ ) + +Enables depth of field blur for objects closer than [dof_blur_near_distance](class_cameraattributespractical.md#class_CameraAttributesPractical_property_dof_blur_near_distance). Strength of blur is controlled by [dof_blur_amount](class_cameraattributespractical.md#class_CameraAttributesPractical_property_dof_blur_amount) and modulated by [dof_blur_near_transition](class_cameraattributespractical.md#class_CameraAttributesPractical_property_dof_blur_near_transition). + +\ **Note:** Depth of field blur is only supported in the Forward+ and Mobile rendering methods, not Compatibility. + +\ **Note:** Depth of field blur is not supported on viewports that have a transparent background (where [Viewport.transparent_bg](class_viewport.md#class_Viewport_property_transparent_bg) is ``true``). + +
+ + + + + +[float](class_float.md) **dof_blur_near_transition** = `1.0` [🔗](#class_CameraAttributesPractical_property_dof_blur_near_transition) + + + +- `void` **set_dof_blur_near_transition**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_dof_blur_near_transition**\ (\ ) + +When positive, distance over which blur effect will scale from 0 to [dof_blur_amount](class_cameraattributespractical.md#class_CameraAttributesPractical_property_dof_blur_amount), ending at [dof_blur_near_distance](class_cameraattributespractical.md#class_CameraAttributesPractical_property_dof_blur_near_distance). When negative, uses physically-based scaling so depth of field effect will scale from 0 at [dof_blur_near_distance](class_cameraattributespractical.md#class_CameraAttributesPractical_property_dof_blur_near_distance) and will increase in a physically accurate way as objects get closer to the [Camera3D](class_camera3d.md). + diff --git a/docs/Classes/class_camerafeed.md b/docs/Classes/class_camerafeed.md new file mode 100644 index 00000000..98e6337f --- /dev/null +++ b/docs/Classes/class_camerafeed.md @@ -0,0 +1,394 @@ + + + + + + + + + +# CameraFeed + +**Inherits:** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +A camera feed gives you access to a single physical camera attached to your device. + + + +## Description + +A camera feed gives you access to a single physical camera attached to your device. When enabled, Redot will start capturing frames from the camera which can then be used. See also [CameraServer](class_cameraserver.md). + +\ **Note:** Many cameras will return YCbCr images which are split into two textures and need to be combined in a shader. Redot does this automatically for you if you set the environment to show the camera image in the background. + +\ **Note:** This class is currently only implemented on Linux, Android, macOS, and iOS. On other platforms no **CameraFeed**\ s will be available. To get a **CameraFeed** on iOS, the camera plugin from [godot-ios-plugins](https://github.com/godotengine/godot-ios-plugins) is required. + + + +## Properties + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[feed_is_active](#class_CameraFeed_property_feed_is_active)`false`
[Transform2D](class_transform2d.md)[feed_transform](#class_CameraFeed_property_feed_transform)`Transform2D(1, 0, 0, -1, 0, 1)`
[Array](class_array.md)[formats](#class_CameraFeed_property_formats)`[]`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[_activate_feed](#class_CameraFeed_private_method__activate_feed)\ (\ ) virtual
`void`[_deactivate_feed](#class_CameraFeed_private_method__deactivate_feed)\ (\ ) virtual
[FeedDataType](class_camerafeed.md#enum_CameraFeed_FeedDataType)[get_datatype](#class_CameraFeed_method_get_datatype)\ (\ ) const
[int](class_int.md)[get_id](#class_CameraFeed_method_get_id)\ (\ ) const
[String](class_string.md)[get_name](#class_CameraFeed_method_get_name)\ (\ ) const
[FeedPosition](class_camerafeed.md#enum_CameraFeed_FeedPosition)[get_position](#class_CameraFeed_method_get_position)\ (\ ) const
[int](class_int.md)[get_texture_tex_id](#class_CameraFeed_method_get_texture_tex_id)\ (\ feed_image_type\: [FeedImage](class_cameraserver.md#enum_CameraServer_FeedImage)\ )
`void`[set_external](#class_CameraFeed_method_set_external)\ (\ width\: [int](class_int.md), height\: [int](class_int.md)\ )
[bool](class_bool.md)[set_format](#class_CameraFeed_method_set_format)\ (\ index\: [int](class_int.md), parameters\: [Dictionary](class_dictionary.md)\ )
`void`[set_name](#class_CameraFeed_method_set_name)\ (\ name\: [String](class_string.md)\ )
`void`[set_position](#class_CameraFeed_method_set_position)\ (\ position\: [FeedPosition](class_camerafeed.md#enum_CameraFeed_FeedPosition)\ )
`void`[set_rgb_image](#class_CameraFeed_method_set_rgb_image)\ (\ rgb_image\: [Image](class_image.md)\ )
`void`[set_ycbcr_image](#class_CameraFeed_method_set_ycbcr_image)\ (\ ycbcr_image\: [Image](class_image.md)\ )
+ +
+ + + +## Signals + + + + + +**format_changed**\ (\ ) [🔗](#class_CameraFeed_signal_format_changed) + +Emitted when the format has changed. + +
+ + + + + +**frame_changed**\ (\ ) [🔗](#class_CameraFeed_signal_frame_changed) + +Emitted when a new frame is available. + +
+ + + +## Enumerations + + + + + +enum **FeedDataType**: [🔗](#enum_CameraFeed_FeedDataType) + + + + + +[FeedDataType](class_camerafeed.md#enum_CameraFeed_FeedDataType) **FEED_NOIMAGE** = `0` + +No image set for the feed. + + + +[FeedDataType](class_camerafeed.md#enum_CameraFeed_FeedDataType) **FEED_RGB** = `1` + +Feed supplies RGB images. + + + +[FeedDataType](class_camerafeed.md#enum_CameraFeed_FeedDataType) **FEED_YCBCR** = `2` + +Feed supplies YCbCr images that need to be converted to RGB. + + + +[FeedDataType](class_camerafeed.md#enum_CameraFeed_FeedDataType) **FEED_YCBCR_SEP** = `3` + +Feed supplies separate Y and CbCr images that need to be combined and converted to RGB. + + + +[FeedDataType](class_camerafeed.md#enum_CameraFeed_FeedDataType) **FEED_EXTERNAL** = `4` + +Feed supplies external image.
+ + + + + +enum **FeedPosition**: [🔗](#enum_CameraFeed_FeedPosition) + + + + + +[FeedPosition](class_camerafeed.md#enum_CameraFeed_FeedPosition) **FEED_UNSPECIFIED** = `0` + +Unspecified position. + + + +[FeedPosition](class_camerafeed.md#enum_CameraFeed_FeedPosition) **FEED_FRONT** = `1` + +Camera is mounted at the front of the device. + + + +[FeedPosition](class_camerafeed.md#enum_CameraFeed_FeedPosition) **FEED_BACK** = `2` + +Camera is mounted at the back of the device.
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **feed_is_active** = `false` [🔗](#class_CameraFeed_property_feed_is_active) + + + +- `void` **set_active**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_active**\ (\ ) + +If ``true``, the feed is active. + +
+ + + + + +[Transform2D](class_transform2d.md) **feed_transform** = `Transform2D(1, 0, 0, -1, 0, 1)` [🔗](#class_CameraFeed_property_feed_transform) + + + +- `void` **set_transform**\ (\ value\: [Transform2D](class_transform2d.md)\ ) +- [Transform2D](class_transform2d.md) **get_transform**\ (\ ) + +The transform applied to the camera's image. + +
+ + + + + +[Array](class_array.md) **formats** = `[]` [🔗](#class_CameraFeed_property_formats) + + + +- [Array](class_array.md) **get_formats**\ (\ ) + +Formats supported by the feed. Each entry is a [Dictionary](class_dictionary.md) describing format parameters. + +
+ + + +## Method Descriptions + + + + + +[bool](class_bool.md) **_activate_feed**\ (\ ) virtual [🔗](#class_CameraFeed_private_method__activate_feed) + +Called when the camera feed is activated. + +
+ + + + + +`void` **_deactivate_feed**\ (\ ) virtual [🔗](#class_CameraFeed_private_method__deactivate_feed) + +Called when the camera feed is deactivated. + +
+ + + + + +[FeedDataType](class_camerafeed.md#enum_CameraFeed_FeedDataType) **get_datatype**\ (\ ) const [🔗](#class_CameraFeed_method_get_datatype) + +Returns feed image data type. + +
+ + + + + +[int](class_int.md) **get_id**\ (\ ) const [🔗](#class_CameraFeed_method_get_id) + +Returns the unique ID for this feed. + +
+ + + + + +[String](class_string.md) **get_name**\ (\ ) const [🔗](#class_CameraFeed_method_get_name) + +Returns the camera's name. + +
+ + + + + +[FeedPosition](class_camerafeed.md#enum_CameraFeed_FeedPosition) **get_position**\ (\ ) const [🔗](#class_CameraFeed_method_get_position) + +Returns the position of camera on the device. + +
+ + + + + +[int](class_int.md) **get_texture_tex_id**\ (\ feed_image_type\: [FeedImage](class_cameraserver.md#enum_CameraServer_FeedImage)\ ) [🔗](#class_CameraFeed_method_get_texture_tex_id) + +Returns the texture backend ID (usable by some external libraries that need a handle to a texture to write data). + +
+ + + + + +`void` **set_external**\ (\ width\: [int](class_int.md), height\: [int](class_int.md)\ ) [🔗](#class_CameraFeed_method_set_external) + +Sets the feed as external feed provided by another library. + +
+ + + + + +[bool](class_bool.md) **set_format**\ (\ index\: [int](class_int.md), parameters\: [Dictionary](class_dictionary.md)\ ) [🔗](#class_CameraFeed_method_set_format) + +Sets the feed format parameters for the given `index` in the [formats](class_camerafeed.md#class_CameraFeed_property_formats) array. Returns ``true`` on success. By default, the YUYV encoded stream is transformed to [FEED_RGB](class_camerafeed.md#class_CameraFeed_constant_FEED_RGB). The YUYV encoded stream output format can be changed by setting `parameters`'s ``output`` entry to one of the following: + +- ``"separate"`` will result in [FEED_YCBCR_SEP](class_camerafeed.md#class_CameraFeed_constant_FEED_YCBCR_SEP); + +- ``"grayscale"`` will result in desaturated [FEED_RGB](class_camerafeed.md#class_CameraFeed_constant_FEED_RGB); + +- ``"copy"`` will result in [FEED_YCBCR](class_camerafeed.md#class_CameraFeed_constant_FEED_YCBCR). + +
+ + + + + +`void` **set_name**\ (\ name\: [String](class_string.md)\ ) [🔗](#class_CameraFeed_method_set_name) + +Sets the camera's name. + +
+ + + + + +`void` **set_position**\ (\ position\: [FeedPosition](class_camerafeed.md#enum_CameraFeed_FeedPosition)\ ) [🔗](#class_CameraFeed_method_set_position) + +Sets the position of this camera. + +
+ + + + + +`void` **set_rgb_image**\ (\ rgb_image\: [Image](class_image.md)\ ) [🔗](#class_CameraFeed_method_set_rgb_image) + +Sets RGB image for this feed. + +
+ + + + + +`void` **set_ycbcr_image**\ (\ ycbcr_image\: [Image](class_image.md)\ ) [🔗](#class_CameraFeed_method_set_ycbcr_image) + +Sets YCbCr image for this feed. + diff --git a/docs/Classes/class_cameraserver.md b/docs/Classes/class_cameraserver.md new file mode 100644 index 00000000..432fb22b --- /dev/null +++ b/docs/Classes/class_cameraserver.md @@ -0,0 +1,246 @@ + + + + + + + + + +# CameraServer + +**Inherits:** [Object](class_object.md) + +Server keeping track of different cameras accessible in Redot. + + + +## Description + +The **CameraServer** keeps track of different cameras accessible in Redot. These are external cameras such as webcams or the cameras on your phone. + +It is notably used to provide AR modules with a video feed from the camera. + +\ **Note:** This class is currently only implemented on Linux, Android, macOS, and iOS. On other platforms no [CameraFeed](class_camerafeed.md)\ s will be available. To get a [CameraFeed](class_camerafeed.md) on iOS, the camera plugin from [godot-ios-plugins](https://github.com/godotengine/godot-ios-plugins) is required. + + + +## Properties + + + + + + + + + + + +
[bool](class_bool.md)[monitoring_feeds](#class_CameraServer_property_monitoring_feeds)`false`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + +
`void`[add_feed](#class_CameraServer_method_add_feed)\ (\ feed\: [CameraFeed](class_camerafeed.md)\ )
[Array](class_array.md)\[[CameraFeed](class_camerafeed.md)\][feeds](#class_CameraServer_method_feeds)\ (\ )
[CameraFeed](class_camerafeed.md)[get_feed](#class_CameraServer_method_get_feed)\ (\ index\: [int](class_int.md)\ )
[int](class_int.md)[get_feed_count](#class_CameraServer_method_get_feed_count)\ (\ )
`void`[remove_feed](#class_CameraServer_method_remove_feed)\ (\ feed\: [CameraFeed](class_camerafeed.md)\ )
+ +
+ + + +## Signals + + + + + +**camera_feed_added**\ (\ id\: [int](class_int.md)\ ) [🔗](#class_CameraServer_signal_camera_feed_added) + +Emitted when a [CameraFeed](class_camerafeed.md) is added (e.g. a webcam is plugged in). + +
+ + + + + +**camera_feed_removed**\ (\ id\: [int](class_int.md)\ ) [🔗](#class_CameraServer_signal_camera_feed_removed) + +Emitted when a [CameraFeed](class_camerafeed.md) is removed (e.g. a webcam is unplugged). + +
+ + + + + +**camera_feeds_updated**\ (\ ) [🔗](#class_CameraServer_signal_camera_feeds_updated) + +Emitted when camera feeds are updated. + +
+ + + +## Enumerations + + + + + +enum **FeedImage**: [🔗](#enum_CameraServer_FeedImage) + + + + + +[FeedImage](class_cameraserver.md#enum_CameraServer_FeedImage) **FEED_RGBA_IMAGE** = `0` + +The RGBA camera image. + + + +[FeedImage](class_cameraserver.md#enum_CameraServer_FeedImage) **FEED_YCBCR_IMAGE** = `0` + +The [YCbCr](https://en.wikipedia.org/wiki/YCbCr) camera image. + + + +[FeedImage](class_cameraserver.md#enum_CameraServer_FeedImage) **FEED_Y_IMAGE** = `0` + +The Y component camera image. + + + +[FeedImage](class_cameraserver.md#enum_CameraServer_FeedImage) **FEED_CBCR_IMAGE** = `1` + +The CbCr component camera image.
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **monitoring_feeds** = `false` [🔗](#class_CameraServer_property_monitoring_feeds) + + + +- `void` **set_monitoring_feeds**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_monitoring_feeds**\ (\ ) + +If ``true``, the server is actively monitoring available camera feeds. + +This has a performance cost, so only set it to ``true`` when you're actively accessing the camera. + +\ **Note:** After setting it to ``true``, you can receive updated camera feeds through the [camera_feeds_updated](class_cameraserver.md#class_CameraServer_signal_camera_feeds_updated) signal. + + + + +```gdscript + func _ready(): + CameraServer.camera_feeds_updated.connect(_on_camera_feeds_updated) + CameraServer.monitoring_feeds = true + + func _on_camera_feeds_updated(): + var feeds = CameraServer.feeds() +``` + +```csharp + public override void _Ready() + { + CameraServer.CameraFeedsUpdated += OnCameraFeedsUpdated; + CameraServer.MonitoringFeeds = true; + } + + void OnCameraFeedsUpdated() + { + var feeds = CameraServer.Feeds(); + } +``` + + + +
+ + + +## Method Descriptions + + + + + +`void` **add_feed**\ (\ feed\: [CameraFeed](class_camerafeed.md)\ ) [🔗](#class_CameraServer_method_add_feed) + +Adds the camera `feed` to the camera server. + +
+ + + + + +[Array](class_array.md)\[[CameraFeed](class_camerafeed.md)\] **feeds**\ (\ ) [🔗](#class_CameraServer_method_feeds) + +Returns an array of [CameraFeed](class_camerafeed.md)\ s. + +
+ + + + + +[CameraFeed](class_camerafeed.md) **get_feed**\ (\ index\: [int](class_int.md)\ ) [🔗](#class_CameraServer_method_get_feed) + +Returns the [CameraFeed](class_camerafeed.md) corresponding to the camera with the given `index`. + +
+ + + + + +[int](class_int.md) **get_feed_count**\ (\ ) [🔗](#class_CameraServer_method_get_feed_count) + +Returns the number of [CameraFeed](class_camerafeed.md)\ s registered. + +
+ + + + + +`void` **remove_feed**\ (\ feed\: [CameraFeed](class_camerafeed.md)\ ) [🔗](#class_CameraServer_method_remove_feed) + +Removes the specified camera `feed`. + diff --git a/docs/Classes/class_cameratexture.md b/docs/Classes/class_cameratexture.md new file mode 100644 index 00000000..56b1a9a8 --- /dev/null +++ b/docs/Classes/class_cameratexture.md @@ -0,0 +1,103 @@ + + + + + + + + + +# CameraTexture + +**Inherits:** [Texture2D](class_texture2d.md) **<** [Texture](class_texture.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Texture provided by a [CameraFeed](class_camerafeed.md). + + + +## Description + +This texture gives access to the camera texture provided by a [CameraFeed](class_camerafeed.md). + +\ **Note:** Many cameras supply YCbCr images which need to be converted in a shader. + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + +
[int](class_int.md)[camera_feed_id](#class_CameraTexture_property_camera_feed_id)`0`
[bool](class_bool.md)[camera_is_active](#class_CameraTexture_property_camera_is_active)`false`
[bool](class_bool.md)resource_local_to_scene`false` (overrides [Resource.resource_local_to_scene](class_resource.md#class_Resource_property_resource_local_to_scene))
[FeedImage](class_cameraserver.md#enum_CameraServer_FeedImage)[which_feed](#class_CameraTexture_property_which_feed)`0`
+ +
+ + + +## Property Descriptions + + + + + +[int](class_int.md) **camera_feed_id** = `0` [🔗](#class_CameraTexture_property_camera_feed_id) + + + +- `void` **set_camera_feed_id**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_camera_feed_id**\ (\ ) + +The ID of the [CameraFeed](class_camerafeed.md) for which we want to display the image. + +
+ + + + + +[bool](class_bool.md) **camera_is_active** = `false` [🔗](#class_CameraTexture_property_camera_is_active) + + + +- `void` **set_camera_active**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_camera_active**\ (\ ) + +Convenience property that gives access to the active property of the [CameraFeed](class_camerafeed.md). + +
+ + + + + +[FeedImage](class_cameraserver.md#enum_CameraServer_FeedImage) **which_feed** = `0` [🔗](#class_CameraTexture_property_which_feed) + + + +- `void` **set_which_feed**\ (\ value\: [FeedImage](class_cameraserver.md#enum_CameraServer_FeedImage)\ ) +- [FeedImage](class_cameraserver.md#enum_CameraServer_FeedImage) **get_which_feed**\ (\ ) + +Which image within the [CameraFeed](class_camerafeed.md) we want access to, important if the camera image is split in a Y and CbCr component. + diff --git a/docs/Classes/class_canvasgroup.md b/docs/Classes/class_canvasgroup.md new file mode 100644 index 00000000..d3eb3ee9 --- /dev/null +++ b/docs/Classes/class_canvasgroup.md @@ -0,0 +1,117 @@ + + + + + + + + + +# CanvasGroup + +**Inherits:** [Node2D](class_node2d.md) **<** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +Merges several 2D nodes into a single draw operation. + + + +## Description + +Child [CanvasItem](class_canvasitem.md) nodes of a **CanvasGroup** are drawn as a single object. It allows to e.g. draw overlapping translucent 2D nodes without blending (set [CanvasItem.self_modulate](class_canvasitem.md#class_CanvasItem_property_self_modulate) property of **CanvasGroup** to achieve this effect). + +\ **Note:** The **CanvasGroup** uses a custom shader to read from the backbuffer to draw its children. Assigning a [Material](class_material.md) to the **CanvasGroup** overrides the builtin shader. To duplicate the behavior of the builtin shader in a custom [Shader](class_shader.md) use the following: + +``` + shader_type canvas_item; + render_mode unshaded; + + uniform sampler2D screen_texture : hint_screen_texture, repeat_disable, filter_nearest; + + void fragment() { + vec4 c = textureLod(screen_texture, SCREEN_UV, 0.0); + + if (c.a > 0.0001) { + c.rgb /= c.a; + } + + COLOR *= c; + } +``` + +\ **Note:** Since **CanvasGroup** and [CanvasItem.clip_children](class_canvasitem.md#class_CanvasItem_property_clip_children) both utilize the backbuffer, children of a **CanvasGroup** who have their [CanvasItem.clip_children](class_canvasitem.md#class_CanvasItem_property_clip_children) set to anything other than [CanvasItem.CLIP_CHILDREN_DISABLED](class_canvasitem.md#class_CanvasItem_constant_CLIP_CHILDREN_DISABLED) will not function correctly. + + + +## Properties + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[clear_margin](#class_CanvasGroup_property_clear_margin)`10.0`
[float](class_float.md)[fit_margin](#class_CanvasGroup_property_fit_margin)`10.0`
[bool](class_bool.md)[use_mipmaps](#class_CanvasGroup_property_use_mipmaps)`false`
+ +
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **clear_margin** = `10.0` [🔗](#class_CanvasGroup_property_clear_margin) + + + +- `void` **set_clear_margin**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_clear_margin**\ (\ ) + +Sets the size of the margin used to expand the clearing rect of this **CanvasGroup**. This expands the area of the backbuffer that will be used by the **CanvasGroup**. A smaller margin will reduce the area of the backbuffer used which can increase performance, however if [use_mipmaps](class_canvasgroup.md#class_CanvasGroup_property_use_mipmaps) is enabled, a small margin may result in mipmap errors at the edge of the **CanvasGroup**. Accordingly, this should be left as small as possible, but should be increased if artifacts appear along the edges of the canvas group. + +
+ + + + + +[float](class_float.md) **fit_margin** = `10.0` [🔗](#class_CanvasGroup_property_fit_margin) + + + +- `void` **set_fit_margin**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_fit_margin**\ (\ ) + +Sets the size of a margin used to expand the drawable rect of this **CanvasGroup**. The size of the **CanvasGroup** is determined by fitting a rect around its children then expanding that rect by [fit_margin](class_canvasgroup.md#class_CanvasGroup_property_fit_margin). This increases both the backbuffer area used and the area covered by the **CanvasGroup** both of which can reduce performance. This should be kept as small as possible and should only be expanded when an increased size is needed (e.g. for custom shader effects). + +
+ + + + + +[bool](class_bool.md) **use_mipmaps** = `false` [🔗](#class_CanvasGroup_property_use_mipmaps) + + + +- `void` **set_use_mipmaps**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_using_mipmaps**\ (\ ) + +If ``true``, calculates mipmaps for the backbuffer before drawing the **CanvasGroup** so that mipmaps can be used in a custom [ShaderMaterial](class_shadermaterial.md) attached to the **CanvasGroup**. Generating mipmaps has a performance cost so this should not be enabled unless required. + diff --git a/docs/Classes/class_canvasitem.md b/docs/Classes/class_canvasitem.md new file mode 100644 index 00000000..388eed6b --- /dev/null +++ b/docs/Classes/class_canvasitem.md @@ -0,0 +1,1599 @@ + + + + + + + + + +# CanvasItem + +**Inherits:** [Node](class_node.md) **<** [Object](class_object.md) + +**Inherited By:** [Control](class_control.md), [Node2D](class_node2d.md) + +Abstract base class for everything in 2D space. + + + +## Description + +Abstract base class for everything in 2D space. Canvas items are laid out in a tree; children inherit and extend their parent's transform. **CanvasItem** is extended by [Control](class_control.md) for GUI-related nodes, and by [Node2D](class_node2d.md) for 2D game objects. + +Any **CanvasItem** can draw. For this, [queue_redraw()](class_canvasitem.md#class_CanvasItem_method_queue_redraw) is called by the engine, then [NOTIFICATION_DRAW](class_canvasitem.md#class_CanvasItem_constant_NOTIFICATION_DRAW) will be received on idle time to request a redraw. Because of this, canvas items don't need to be redrawn on every frame, improving the performance significantly. Several functions for drawing on the **CanvasItem** are provided (see ``draw_*`` functions). However, they can only be used inside [_draw()](class_canvasitem.md#class_CanvasItem_private_method__draw), its corresponding [Object._notification()](class_object.md#class_Object_private_method__notification) or methods connected to the [draw](class_canvasitem.md#class_CanvasItem_signal_draw) signal. + +Canvas items are drawn in tree order on their canvas layer. By default, children are on top of their parents, so a root **CanvasItem** will be drawn behind everything. This behavior can be changed on a per-item basis. + +A **CanvasItem** can be hidden, which will also hide its children. By adjusting various other properties of a **CanvasItem**, you can also modulate its color (via [modulate](class_canvasitem.md#class_CanvasItem_property_modulate) or [self_modulate](class_canvasitem.md#class_CanvasItem_property_self_modulate)), change its Z-index, blend mode, and more. + +Note that properties like transform, modulation, and visibility are only propagated to *direct* **CanvasItem** child nodes. If there is a non-**CanvasItem** node in between, like [Node](class_node.md) or [AnimationPlayer](class_animationplayer.md), the **CanvasItem** nodes below will have an independent position and [modulate](class_canvasitem.md#class_CanvasItem_property_modulate) chain. See also [top_level](class_canvasitem.md#class_CanvasItem_property_top_level). + + + +## Tutorials + +- [Viewport and canvas transforms](../tutorials/2d/2d_transforms.md) + +- [Custom drawing in 2D](../tutorials/2d/custom_drawing_in_2d.md) + +- [Audio Spectrum Visualizer Demo](https://godotengine.org/asset-library/asset/2762) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[ClipChildrenMode](class_canvasitem.md#enum_CanvasItem_ClipChildrenMode)[clip_children](#class_CanvasItem_property_clip_children)`0`
[int](class_int.md)[light_mask](#class_CanvasItem_property_light_mask)`1`
[Material](class_material.md)[material](#class_CanvasItem_property_material)
[Color](class_color.md)[modulate](#class_CanvasItem_property_modulate)`Color(1, 1, 1, 1)`
[Color](class_color.md)[self_modulate](#class_CanvasItem_property_self_modulate)`Color(1, 1, 1, 1)`
[bool](class_bool.md)[show_behind_parent](#class_CanvasItem_property_show_behind_parent)`false`
[TextureFilter](class_canvasitem.md#enum_CanvasItem_TextureFilter)[texture_filter](#class_CanvasItem_property_texture_filter)`0`
[TextureRepeat](class_canvasitem.md#enum_CanvasItem_TextureRepeat)[texture_repeat](#class_CanvasItem_property_texture_repeat)`0`
[bool](class_bool.md)[top_level](#class_CanvasItem_property_top_level)`false`
[bool](class_bool.md)[use_parent_material](#class_CanvasItem_property_use_parent_material)`false`
[int](class_int.md)[visibility_layer](#class_CanvasItem_property_visibility_layer)`1`
[bool](class_bool.md)[visible](#class_CanvasItem_property_visible)`true`
[bool](class_bool.md)[y_sort_enabled](#class_CanvasItem_property_y_sort_enabled)`false`
[bool](class_bool.md)[z_as_relative](#class_CanvasItem_property_z_as_relative)`true`
[int](class_int.md)[z_index](#class_CanvasItem_property_z_index)`0`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
`void`[_draw](#class_CanvasItem_private_method__draw)\ (\ ) virtual
`void`[draw_animation_slice](#class_CanvasItem_method_draw_animation_slice)\ (\ animation_length\: [float](class_float.md), slice_begin\: [float](class_float.md), slice_end\: [float](class_float.md), offset\: [float](class_float.md) = 0.0\ )
`void`[draw_arc](#class_CanvasItem_method_draw_arc)\ (\ center\: [Vector2](class_vector2.md), radius\: [float](class_float.md), start_angle\: [float](class_float.md), end_angle\: [float](class_float.md), point_count\: [int](class_int.md), color\: [Color](class_color.md), width\: [float](class_float.md) = -1.0, antialiased\: [bool](class_bool.md) = false\ )
`void`[draw_char](#class_CanvasItem_method_draw_char)\ (\ font\: [Font](class_font.md), pos\: [Vector2](class_vector2.md), char\: [String](class_string.md), font_size\: [int](class_int.md) = 16, modulate\: [Color](class_color.md) = Color(1, 1, 1, 1), oversampling\: [float](class_float.md) = 0.0\ ) const
`void`[draw_char_outline](#class_CanvasItem_method_draw_char_outline)\ (\ font\: [Font](class_font.md), pos\: [Vector2](class_vector2.md), char\: [String](class_string.md), font_size\: [int](class_int.md) = 16, size\: [int](class_int.md) = -1, modulate\: [Color](class_color.md) = Color(1, 1, 1, 1), oversampling\: [float](class_float.md) = 0.0\ ) const
`void`[draw_circle](#class_CanvasItem_method_draw_circle)\ (\ position\: [Vector2](class_vector2.md), radius\: [float](class_float.md), color\: [Color](class_color.md), filled\: [bool](class_bool.md) = true, width\: [float](class_float.md) = -1.0, antialiased\: [bool](class_bool.md) = false\ )
`void`[draw_colored_polygon](#class_CanvasItem_method_draw_colored_polygon)\ (\ points\: [PackedVector2Array](class_packedvector2array.md), color\: [Color](class_color.md), uvs\: [PackedVector2Array](class_packedvector2array.md) = PackedVector2Array(), texture\: [Texture2D](class_texture2d.md) = null\ )
`void`[draw_dashed_line](#class_CanvasItem_method_draw_dashed_line)\ (\ from\: [Vector2](class_vector2.md), to\: [Vector2](class_vector2.md), color\: [Color](class_color.md), width\: [float](class_float.md) = -1.0, dash\: [float](class_float.md) = 2.0, aligned\: [bool](class_bool.md) = true, antialiased\: [bool](class_bool.md) = false\ )
`void`[draw_end_animation](#class_CanvasItem_method_draw_end_animation)\ (\ )
`void`[draw_lcd_texture_rect_region](#class_CanvasItem_method_draw_lcd_texture_rect_region)\ (\ texture\: [Texture2D](class_texture2d.md), rect\: [Rect2](class_rect2.md), src_rect\: [Rect2](class_rect2.md), modulate\: [Color](class_color.md) = Color(1, 1, 1, 1)\ )
`void`[draw_line](#class_CanvasItem_method_draw_line)\ (\ from\: [Vector2](class_vector2.md), to\: [Vector2](class_vector2.md), color\: [Color](class_color.md), width\: [float](class_float.md) = -1.0, antialiased\: [bool](class_bool.md) = false\ )
`void`[draw_mesh](#class_CanvasItem_method_draw_mesh)\ (\ mesh\: [Mesh](class_mesh.md), texture\: [Texture2D](class_texture2d.md), transform\: [Transform2D](class_transform2d.md) = Transform2D(1, 0, 0, 1, 0, 0), modulate\: [Color](class_color.md) = Color(1, 1, 1, 1)\ )
`void`[draw_msdf_texture_rect_region](#class_CanvasItem_method_draw_msdf_texture_rect_region)\ (\ texture\: [Texture2D](class_texture2d.md), rect\: [Rect2](class_rect2.md), src_rect\: [Rect2](class_rect2.md), modulate\: [Color](class_color.md) = Color(1, 1, 1, 1), outline\: [float](class_float.md) = 0.0, pixel_range\: [float](class_float.md) = 4.0, scale\: [float](class_float.md) = 1.0\ )
`void`[draw_multiline](#class_CanvasItem_method_draw_multiline)\ (\ points\: [PackedVector2Array](class_packedvector2array.md), color\: [Color](class_color.md), width\: [float](class_float.md) = -1.0, antialiased\: [bool](class_bool.md) = false\ )
`void`[draw_multiline_colors](#class_CanvasItem_method_draw_multiline_colors)\ (\ points\: [PackedVector2Array](class_packedvector2array.md), colors\: [PackedColorArray](class_packedcolorarray.md), width\: [float](class_float.md) = -1.0, antialiased\: [bool](class_bool.md) = false\ )
`void`[draw_multiline_string](#class_CanvasItem_method_draw_multiline_string)\ (\ font\: [Font](class_font.md), pos\: [Vector2](class_vector2.md), text\: [String](class_string.md), alignment\: [HorizontalAlignment](class_@globalscope.md#enum_@GlobalScope_HorizontalAlignment) = 0, width\: [float](class_float.md) = -1, font_size\: [int](class_int.md) = 16, max_lines\: [int](class_int.md) = -1, modulate\: [Color](class_color.md) = Color(1, 1, 1, 1), brk_flags\: **BitField**\[[LineBreakFlag](class_textserver.md#enum_TextServer_LineBreakFlag)\] = 3, justification_flags\: **BitField**\[[JustificationFlag](class_textserver.md#enum_TextServer_JustificationFlag)\] = 3, direction\: [Direction](class_textserver.md#enum_TextServer_Direction) = 0, orientation\: [Orientation](class_textserver.md#enum_TextServer_Orientation) = 0, oversampling\: [float](class_float.md) = 0.0\ ) const
`void`[draw_multiline_string_outline](#class_CanvasItem_method_draw_multiline_string_outline)\ (\ font\: [Font](class_font.md), pos\: [Vector2](class_vector2.md), text\: [String](class_string.md), alignment\: [HorizontalAlignment](class_@globalscope.md#enum_@GlobalScope_HorizontalAlignment) = 0, width\: [float](class_float.md) = -1, font_size\: [int](class_int.md) = 16, max_lines\: [int](class_int.md) = -1, size\: [int](class_int.md) = 1, modulate\: [Color](class_color.md) = Color(1, 1, 1, 1), brk_flags\: **BitField**\[[LineBreakFlag](class_textserver.md#enum_TextServer_LineBreakFlag)\] = 3, justification_flags\: **BitField**\[[JustificationFlag](class_textserver.md#enum_TextServer_JustificationFlag)\] = 3, direction\: [Direction](class_textserver.md#enum_TextServer_Direction) = 0, orientation\: [Orientation](class_textserver.md#enum_TextServer_Orientation) = 0, oversampling\: [float](class_float.md) = 0.0\ ) const
`void`[draw_multimesh](#class_CanvasItem_method_draw_multimesh)\ (\ multimesh\: [MultiMesh](class_multimesh.md), texture\: [Texture2D](class_texture2d.md)\ )
`void`[draw_polygon](#class_CanvasItem_method_draw_polygon)\ (\ points\: [PackedVector2Array](class_packedvector2array.md), colors\: [PackedColorArray](class_packedcolorarray.md), uvs\: [PackedVector2Array](class_packedvector2array.md) = PackedVector2Array(), texture\: [Texture2D](class_texture2d.md) = null\ )
`void`[draw_polyline](#class_CanvasItem_method_draw_polyline)\ (\ points\: [PackedVector2Array](class_packedvector2array.md), color\: [Color](class_color.md), width\: [float](class_float.md) = -1.0, antialiased\: [bool](class_bool.md) = false\ )
`void`[draw_polyline_colors](#class_CanvasItem_method_draw_polyline_colors)\ (\ points\: [PackedVector2Array](class_packedvector2array.md), colors\: [PackedColorArray](class_packedcolorarray.md), width\: [float](class_float.md) = -1.0, antialiased\: [bool](class_bool.md) = false\ )
`void`[draw_primitive](#class_CanvasItem_method_draw_primitive)\ (\ points\: [PackedVector2Array](class_packedvector2array.md), colors\: [PackedColorArray](class_packedcolorarray.md), uvs\: [PackedVector2Array](class_packedvector2array.md), texture\: [Texture2D](class_texture2d.md) = null\ )
`void`[draw_rect](#class_CanvasItem_method_draw_rect)\ (\ rect\: [Rect2](class_rect2.md), color\: [Color](class_color.md), filled\: [bool](class_bool.md) = true, width\: [float](class_float.md) = -1.0, antialiased\: [bool](class_bool.md) = false\ )
`void`[draw_set_transform](#class_CanvasItem_method_draw_set_transform)\ (\ position\: [Vector2](class_vector2.md), rotation\: [float](class_float.md) = 0.0, scale\: [Vector2](class_vector2.md) = Vector2(1, 1)\ )
`void`[draw_set_transform_matrix](#class_CanvasItem_method_draw_set_transform_matrix)\ (\ xform\: [Transform2D](class_transform2d.md)\ )
`void`[draw_string](#class_CanvasItem_method_draw_string)\ (\ font\: [Font](class_font.md), pos\: [Vector2](class_vector2.md), text\: [String](class_string.md), alignment\: [HorizontalAlignment](class_@globalscope.md#enum_@GlobalScope_HorizontalAlignment) = 0, width\: [float](class_float.md) = -1, font_size\: [int](class_int.md) = 16, modulate\: [Color](class_color.md) = Color(1, 1, 1, 1), justification_flags\: **BitField**\[[JustificationFlag](class_textserver.md#enum_TextServer_JustificationFlag)\] = 3, direction\: [Direction](class_textserver.md#enum_TextServer_Direction) = 0, orientation\: [Orientation](class_textserver.md#enum_TextServer_Orientation) = 0, oversampling\: [float](class_float.md) = 0.0\ ) const
`void`[draw_string_outline](#class_CanvasItem_method_draw_string_outline)\ (\ font\: [Font](class_font.md), pos\: [Vector2](class_vector2.md), text\: [String](class_string.md), alignment\: [HorizontalAlignment](class_@globalscope.md#enum_@GlobalScope_HorizontalAlignment) = 0, width\: [float](class_float.md) = -1, font_size\: [int](class_int.md) = 16, size\: [int](class_int.md) = 1, modulate\: [Color](class_color.md) = Color(1, 1, 1, 1), justification_flags\: **BitField**\[[JustificationFlag](class_textserver.md#enum_TextServer_JustificationFlag)\] = 3, direction\: [Direction](class_textserver.md#enum_TextServer_Direction) = 0, orientation\: [Orientation](class_textserver.md#enum_TextServer_Orientation) = 0, oversampling\: [float](class_float.md) = 0.0\ ) const
`void`[draw_style_box](#class_CanvasItem_method_draw_style_box)\ (\ style_box\: [StyleBox](class_stylebox.md), rect\: [Rect2](class_rect2.md)\ )
`void`[draw_texture](#class_CanvasItem_method_draw_texture)\ (\ texture\: [Texture2D](class_texture2d.md), position\: [Vector2](class_vector2.md), modulate\: [Color](class_color.md) = Color(1, 1, 1, 1)\ )
`void`[draw_texture_rect](#class_CanvasItem_method_draw_texture_rect)\ (\ texture\: [Texture2D](class_texture2d.md), rect\: [Rect2](class_rect2.md), tile\: [bool](class_bool.md), modulate\: [Color](class_color.md) = Color(1, 1, 1, 1), transpose\: [bool](class_bool.md) = false\ )
`void`[draw_texture_rect_region](#class_CanvasItem_method_draw_texture_rect_region)\ (\ texture\: [Texture2D](class_texture2d.md), rect\: [Rect2](class_rect2.md), src_rect\: [Rect2](class_rect2.md), modulate\: [Color](class_color.md) = Color(1, 1, 1, 1), transpose\: [bool](class_bool.md) = false, clip_uv\: [bool](class_bool.md) = true\ )
`void`[force_update_transform](#class_CanvasItem_method_force_update_transform)\ (\ )
[RID](class_rid.md)[get_canvas](#class_CanvasItem_method_get_canvas)\ (\ ) const
[RID](class_rid.md)[get_canvas_item](#class_CanvasItem_method_get_canvas_item)\ (\ ) const
[CanvasLayer](class_canvaslayer.md)[get_canvas_layer_node](#class_CanvasItem_method_get_canvas_layer_node)\ (\ ) const
[Transform2D](class_transform2d.md)[get_canvas_transform](#class_CanvasItem_method_get_canvas_transform)\ (\ ) const
[Vector2](class_vector2.md)[get_global_mouse_position](#class_CanvasItem_method_get_global_mouse_position)\ (\ ) const
[Transform2D](class_transform2d.md)[get_global_transform](#class_CanvasItem_method_get_global_transform)\ (\ ) const
[Transform2D](class_transform2d.md)[get_global_transform_with_canvas](#class_CanvasItem_method_get_global_transform_with_canvas)\ (\ ) const
[Variant](class_variant.md)[get_instance_shader_parameter](#class_CanvasItem_method_get_instance_shader_parameter)\ (\ name\: [StringName](class_stringname.md)\ ) const
[Vector2](class_vector2.md)[get_local_mouse_position](#class_CanvasItem_method_get_local_mouse_position)\ (\ ) const
[Transform2D](class_transform2d.md)[get_screen_transform](#class_CanvasItem_method_get_screen_transform)\ (\ ) const
[Transform2D](class_transform2d.md)[get_transform](#class_CanvasItem_method_get_transform)\ (\ ) const
[Rect2](class_rect2.md)[get_viewport_rect](#class_CanvasItem_method_get_viewport_rect)\ (\ ) const
[Transform2D](class_transform2d.md)[get_viewport_transform](#class_CanvasItem_method_get_viewport_transform)\ (\ ) const
[bool](class_bool.md)[get_visibility_layer_bit](#class_CanvasItem_method_get_visibility_layer_bit)\ (\ layer\: [int](class_int.md)\ ) const
[World2D](class_world2d.md)[get_world_2d](#class_CanvasItem_method_get_world_2d)\ (\ ) const
`void`[hide](#class_CanvasItem_method_hide)\ (\ )
[bool](class_bool.md)[is_local_transform_notification_enabled](#class_CanvasItem_method_is_local_transform_notification_enabled)\ (\ ) const
[bool](class_bool.md)[is_transform_notification_enabled](#class_CanvasItem_method_is_transform_notification_enabled)\ (\ ) const
[bool](class_bool.md)[is_visible_in_tree](#class_CanvasItem_method_is_visible_in_tree)\ (\ ) const
[Vector2](class_vector2.md)[make_canvas_position_local](#class_CanvasItem_method_make_canvas_position_local)\ (\ viewport_point\: [Vector2](class_vector2.md)\ ) const
[InputEvent](class_inputevent.md)[make_input_local](#class_CanvasItem_method_make_input_local)\ (\ event\: [InputEvent](class_inputevent.md)\ ) const
`void`[move_to_front](#class_CanvasItem_method_move_to_front)\ (\ )
`void`[queue_redraw](#class_CanvasItem_method_queue_redraw)\ (\ )
`void`[set_instance_shader_parameter](#class_CanvasItem_method_set_instance_shader_parameter)\ (\ name\: [StringName](class_stringname.md), value\: [Variant](class_variant.md)\ )
`void`[set_notify_local_transform](#class_CanvasItem_method_set_notify_local_transform)\ (\ enable\: [bool](class_bool.md)\ )
`void`[set_notify_transform](#class_CanvasItem_method_set_notify_transform)\ (\ enable\: [bool](class_bool.md)\ )
`void`[set_visibility_layer_bit](#class_CanvasItem_method_set_visibility_layer_bit)\ (\ layer\: [int](class_int.md), enabled\: [bool](class_bool.md)\ )
`void`[show](#class_CanvasItem_method_show)\ (\ )
+ +
+ + + +## Signals + + + + + +**draw**\ (\ ) [🔗](#class_CanvasItem_signal_draw) + +Emitted when the **CanvasItem** must redraw, *after* the related [NOTIFICATION_DRAW](class_canvasitem.md#class_CanvasItem_constant_NOTIFICATION_DRAW) notification, and *before* [_draw()](class_canvasitem.md#class_CanvasItem_private_method__draw) is called. + +\ **Note:** Deferred connections do not allow drawing through the ``draw_*`` methods. + +
+ + + + + +**hidden**\ (\ ) [🔗](#class_CanvasItem_signal_hidden) + +Emitted when this node becomes hidden, i.e. it's no longer visible in the tree (see [is_visible_in_tree()](class_canvasitem.md#class_CanvasItem_method_is_visible_in_tree)). + +
+ + + + + +**item_rect_changed**\ (\ ) [🔗](#class_CanvasItem_signal_item_rect_changed) + +Emitted when the **CanvasItem**'s boundaries (position or size) change, or when an action took place that may have affected these boundaries (e.g. changing [Sprite2D.texture](class_sprite2d.md#class_Sprite2D_property_texture)). + +
+ + + + + +**visibility_changed**\ (\ ) [🔗](#class_CanvasItem_signal_visibility_changed) + +Emitted when the **CanvasItem**'s visibility changes, either because its own [visible](class_canvasitem.md#class_CanvasItem_property_visible) property changed or because its visibility in the tree changed (see [is_visible_in_tree()](class_canvasitem.md#class_CanvasItem_method_is_visible_in_tree)). + +This signal is emitted *after* the related [NOTIFICATION_VISIBILITY_CHANGED](class_canvasitem.md#class_CanvasItem_constant_NOTIFICATION_VISIBILITY_CHANGED) notification. + +
+ + + +## Enumerations + + + + + +enum **TextureFilter**: [🔗](#enum_CanvasItem_TextureFilter) + + + + + +[TextureFilter](class_canvasitem.md#enum_CanvasItem_TextureFilter) **TEXTURE_FILTER_PARENT_NODE** = `0` + +The **CanvasItem** will inherit the filter from its parent. + + + +[TextureFilter](class_canvasitem.md#enum_CanvasItem_TextureFilter) **TEXTURE_FILTER_NEAREST** = `1` + +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). + + + +[TextureFilter](class_canvasitem.md#enum_CanvasItem_TextureFilter) **TEXTURE_FILTER_LINEAR** = `2` + +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). + + + +[TextureFilter](class_canvasitem.md#enum_CanvasItem_TextureFilter) **TEXTURE_FILTER_NEAREST_WITH_MIPMAPS** = `3` + +The texture filter reads from the nearest pixel and blends between the nearest 2 mipmaps (or uses the nearest mipmap if [ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter](class_projectsettings.md#class_ProjectSettings_property_rendering/textures/default_filters/use_nearest_mipmap_filter) is ``true``). This makes the texture look pixelated from up close, and smooth from a distance. + +Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to [Camera2D](class_camera2d.md) zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. + + + +[TextureFilter](class_canvasitem.md#enum_CanvasItem_TextureFilter) **TEXTURE_FILTER_LINEAR_WITH_MIPMAPS** = `4` + +The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps (or uses the nearest mipmap if [ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter](class_projectsettings.md#class_ProjectSettings_property_rendering/textures/default_filters/use_nearest_mipmap_filter) is ``true``). This makes the texture look smooth from up close, and smooth from a distance. + +Use this for non-pixel art textures that may be viewed at a low scale (e.g. due to [Camera2D](class_camera2d.md) zoom or sprite scaling), as mipmaps are important to smooth out pixels that are smaller than on-screen pixels. + + + +[TextureFilter](class_canvasitem.md#enum_CanvasItem_TextureFilter) **TEXTURE_FILTER_NEAREST_WITH_MIPMAPS_ANISOTROPIC** = `5` + +The texture filter reads from the nearest pixel and blends between 2 mipmaps (or uses the nearest mipmap if [ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter](class_projectsettings.md#class_ProjectSettings_property_rendering/textures/default_filters/use_nearest_mipmap_filter) is ``true``) 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 [ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level](class_projectsettings.md#class_ProjectSettings_property_rendering/textures/default_filters/anisotropic_filtering_level). + +\ **Note:** This texture filter is rarely useful in 2D projects. [TEXTURE_FILTER_NEAREST_WITH_MIPMAPS](class_canvasitem.md#class_CanvasItem_constant_TEXTURE_FILTER_NEAREST_WITH_MIPMAPS) is usually more appropriate in this case. + + + +[TextureFilter](class_canvasitem.md#enum_CanvasItem_TextureFilter) **TEXTURE_FILTER_LINEAR_WITH_MIPMAPS_ANISOTROPIC** = `6` + +The texture filter blends between the nearest 4 pixels and blends between 2 mipmaps (or uses the nearest mipmap if [ProjectSettings.rendering/textures/default_filters/use_nearest_mipmap_filter](class_projectsettings.md#class_ProjectSettings_property_rendering/textures/default_filters/use_nearest_mipmap_filter) is ``true``) 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 [ProjectSettings.rendering/textures/default_filters/anisotropic_filtering_level](class_projectsettings.md#class_ProjectSettings_property_rendering/textures/default_filters/anisotropic_filtering_level). + +\ **Note:** This texture filter is rarely useful in 2D projects. [TEXTURE_FILTER_LINEAR_WITH_MIPMAPS](class_canvasitem.md#class_CanvasItem_constant_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS) is usually more appropriate in this case. + + + +[TextureFilter](class_canvasitem.md#enum_CanvasItem_TextureFilter) **TEXTURE_FILTER_MAX** = `7` + +Represents the size of the [TextureFilter](class_canvasitem.md#enum_CanvasItem_TextureFilter) enum.
+ + + + + +enum **TextureRepeat**: [🔗](#enum_CanvasItem_TextureRepeat) + + + + + +[TextureRepeat](class_canvasitem.md#enum_CanvasItem_TextureRepeat) **TEXTURE_REPEAT_PARENT_NODE** = `0` + +The **CanvasItem** will inherit the filter from its parent. + + + +[TextureRepeat](class_canvasitem.md#enum_CanvasItem_TextureRepeat) **TEXTURE_REPEAT_DISABLED** = `1` + +The texture does not repeat. Sampling the texture outside its extents will result in "stretching" of the edge pixels. You can avoid this by ensuring a 1-pixel fully transparent border on each side of the texture. + + + +[TextureRepeat](class_canvasitem.md#enum_CanvasItem_TextureRepeat) **TEXTURE_REPEAT_ENABLED** = `2` + +The texture repeats when exceeding the texture's size. + + + +[TextureRepeat](class_canvasitem.md#enum_CanvasItem_TextureRepeat) **TEXTURE_REPEAT_MIRROR** = `3` + +The texture repeats when the exceeding the texture's size in a "2×2 tiled mode". Repeated textures at even positions are mirrored. + + + +[TextureRepeat](class_canvasitem.md#enum_CanvasItem_TextureRepeat) **TEXTURE_REPEAT_MAX** = `4` + +Represents the size of the [TextureRepeat](class_canvasitem.md#enum_CanvasItem_TextureRepeat) enum.
+ + + + + +enum **ClipChildrenMode**: [🔗](#enum_CanvasItem_ClipChildrenMode) + + + + + +[ClipChildrenMode](class_canvasitem.md#enum_CanvasItem_ClipChildrenMode) **CLIP_CHILDREN_DISABLED** = `0` + +Children are drawn over this node and are not clipped. + + + +[ClipChildrenMode](class_canvasitem.md#enum_CanvasItem_ClipChildrenMode) **CLIP_CHILDREN_ONLY** = `1` + +This node is used as a mask and is **not** drawn. The mask is based on this node's alpha channel: Opaque pixels are kept, transparent pixels are discarded, and semi-transparent pixels are blended in according to their opacity. Children are clipped to this node's drawn area. + + + +[ClipChildrenMode](class_canvasitem.md#enum_CanvasItem_ClipChildrenMode) **CLIP_CHILDREN_AND_DRAW** = `2` + +This node is used as a mask and is also drawn. The mask is based on this node's alpha channel: Opaque pixels are kept, transparent pixels are discarded, and semi-transparent pixels are blended in according to their opacity. Children are clipped to the parent's drawn area. + + + +[ClipChildrenMode](class_canvasitem.md#enum_CanvasItem_ClipChildrenMode) **CLIP_CHILDREN_MAX** = `3` + +Represents the size of the [ClipChildrenMode](class_canvasitem.md#enum_CanvasItem_ClipChildrenMode) enum.
+ + + +## Constants + + + + + +**NOTIFICATION_TRANSFORM_CHANGED** = `2000` [🔗](#class_CanvasItem_constant_NOTIFICATION_TRANSFORM_CHANGED) + +Notification received when this node's global transform changes, if [is_transform_notification_enabled()](class_canvasitem.md#class_CanvasItem_method_is_transform_notification_enabled) is ``true``. See also [set_notify_transform()](class_canvasitem.md#class_CanvasItem_method_set_notify_transform) and [get_transform()](class_canvasitem.md#class_CanvasItem_method_get_transform). + +\ **Note:** Many canvas items such as [Camera2D](class_camera2d.md) or [CollisionObject2D](class_collisionobject2d.md) automatically enable this in order to function correctly. + + + + + +**NOTIFICATION_LOCAL_TRANSFORM_CHANGED** = `35` [🔗](#class_CanvasItem_constant_NOTIFICATION_LOCAL_TRANSFORM_CHANGED) + +Notification received when this node's transform changes, if [is_local_transform_notification_enabled()](class_canvasitem.md#class_CanvasItem_method_is_local_transform_notification_enabled) is ``true``. This is not received when a parent [Node2D](class_node2d.md)'s transform changes. See also [set_notify_local_transform()](class_canvasitem.md#class_CanvasItem_method_set_notify_local_transform). + +\ **Note:** Many canvas items such as [Camera2D](class_camera2d.md) or [CollisionShape2D](class_collisionshape2d.md) automatically enable this in order to function correctly. + + + + + +**NOTIFICATION_DRAW** = `30` [🔗](#class_CanvasItem_constant_NOTIFICATION_DRAW) + +The **CanvasItem** is requested to draw (see [_draw()](class_canvasitem.md#class_CanvasItem_private_method__draw)). + + + + + +**NOTIFICATION_VISIBILITY_CHANGED** = `31` [🔗](#class_CanvasItem_constant_NOTIFICATION_VISIBILITY_CHANGED) + +Notification received when this node's visibility changes (see [visible](class_canvasitem.md#class_CanvasItem_property_visible) and [is_visible_in_tree()](class_canvasitem.md#class_CanvasItem_method_is_visible_in_tree)). + +This notification is received *before* the related [visibility_changed](class_canvasitem.md#class_CanvasItem_signal_visibility_changed) signal. + + + + + +**NOTIFICATION_ENTER_CANVAS** = `32` [🔗](#class_CanvasItem_constant_NOTIFICATION_ENTER_CANVAS) + +The **CanvasItem** has entered the canvas. + + + + + +**NOTIFICATION_EXIT_CANVAS** = `33` [🔗](#class_CanvasItem_constant_NOTIFICATION_EXIT_CANVAS) + +The **CanvasItem** has exited the canvas. + + + + + +**NOTIFICATION_WORLD_2D_CHANGED** = `36` [🔗](#class_CanvasItem_constant_NOTIFICATION_WORLD_2D_CHANGED) + +Notification received when this **CanvasItem** is registered to a new [World2D](class_world2d.md) (see [get_world_2d()](class_canvasitem.md#class_CanvasItem_method_get_world_2d)). + +
+ + + +## Property Descriptions + + + + + +[ClipChildrenMode](class_canvasitem.md#enum_CanvasItem_ClipChildrenMode) **clip_children** = `0` [🔗](#class_CanvasItem_property_clip_children) + + + +- `void` **set_clip_children_mode**\ (\ value\: [ClipChildrenMode](class_canvasitem.md#enum_CanvasItem_ClipChildrenMode)\ ) +- [ClipChildrenMode](class_canvasitem.md#enum_CanvasItem_ClipChildrenMode) **get_clip_children_mode**\ (\ ) + +The mode in which this node clips its children, acting as a mask. + +\ **Note:** Clipping nodes cannot be nested or placed within a [CanvasGroup](class_canvasgroup.md). If an ancestor of this node clips its children or is a [CanvasGroup](class_canvasgroup.md), then this node's clip mode should be set to [CLIP_CHILDREN_DISABLED](class_canvasitem.md#class_CanvasItem_constant_CLIP_CHILDREN_DISABLED) to avoid unexpected behavior. + +
+ + + + + +[int](class_int.md) **light_mask** = `1` [🔗](#class_CanvasItem_property_light_mask) + + + +- `void` **set_light_mask**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_light_mask**\ (\ ) + +The rendering layers in which this **CanvasItem** responds to [Light2D](class_light2d.md) nodes. + +
+ + + + + +[Material](class_material.md) **material** [🔗](#class_CanvasItem_property_material) + + + +- `void` **set_material**\ (\ value\: [Material](class_material.md)\ ) +- [Material](class_material.md) **get_material**\ (\ ) + +The material applied to this **CanvasItem**. + +
+ + + + + +[Color](class_color.md) **modulate** = `Color(1, 1, 1, 1)` [🔗](#class_CanvasItem_property_modulate) + + + +- `void` **set_modulate**\ (\ value\: [Color](class_color.md)\ ) +- [Color](class_color.md) **get_modulate**\ (\ ) + +The color applied to this **CanvasItem**. This property does affect child **CanvasItem**\ s, unlike [self_modulate](class_canvasitem.md#class_CanvasItem_property_self_modulate) which only affects the node itself. + +
+ + + + + +[Color](class_color.md) **self_modulate** = `Color(1, 1, 1, 1)` [🔗](#class_CanvasItem_property_self_modulate) + + + +- `void` **set_self_modulate**\ (\ value\: [Color](class_color.md)\ ) +- [Color](class_color.md) **get_self_modulate**\ (\ ) + +The color applied to this **CanvasItem**. This property does **not** affect child **CanvasItem**\ s, unlike [modulate](class_canvasitem.md#class_CanvasItem_property_modulate) which affects both the node itself and its children. + +\ **Note:** Internal children are also not affected by this property (see the ``include_internal`` parameter in [Node.add_child()](class_node.md#class_Node_method_add_child)). For built-in nodes this includes sliders in [ColorPicker](class_colorpicker.md), and the tab bar in [TabContainer](class_tabcontainer.md). + +
+ + + + + +[bool](class_bool.md) **show_behind_parent** = `false` [🔗](#class_CanvasItem_property_show_behind_parent) + + + +- `void` **set_draw_behind_parent**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_draw_behind_parent_enabled**\ (\ ) + +If ``true``, this node draws behind its parent. + +
+ + + + + +[TextureFilter](class_canvasitem.md#enum_CanvasItem_TextureFilter) **texture_filter** = `0` [🔗](#class_CanvasItem_property_texture_filter) + + + +- `void` **set_texture_filter**\ (\ value\: [TextureFilter](class_canvasitem.md#enum_CanvasItem_TextureFilter)\ ) +- [TextureFilter](class_canvasitem.md#enum_CanvasItem_TextureFilter) **get_texture_filter**\ (\ ) + +The filtering mode used to render this **CanvasItem**'s texture(s). + +
+ + + + + +[TextureRepeat](class_canvasitem.md#enum_CanvasItem_TextureRepeat) **texture_repeat** = `0` [🔗](#class_CanvasItem_property_texture_repeat) + + + +- `void` **set_texture_repeat**\ (\ value\: [TextureRepeat](class_canvasitem.md#enum_CanvasItem_TextureRepeat)\ ) +- [TextureRepeat](class_canvasitem.md#enum_CanvasItem_TextureRepeat) **get_texture_repeat**\ (\ ) + +The repeating mode used to render this **CanvasItem**'s texture(s). It affects what happens when the texture is sampled outside its extents, for example by setting a [Sprite2D.region_rect](class_sprite2d.md#class_Sprite2D_property_region_rect) that is larger than the texture or assigning [Polygon2D](class_polygon2d.md) UV points outside the texture. + +\ **Note:** [TextureRect](class_texturerect.md) is not affected by [texture_repeat](class_canvasitem.md#class_CanvasItem_property_texture_repeat), as it uses its own texture repeating implementation. + +
+ + + + + +[bool](class_bool.md) **top_level** = `false` [🔗](#class_CanvasItem_property_top_level) + + + +- `void` **set_as_top_level**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_set_as_top_level**\ (\ ) + +If ``true``, this **CanvasItem** will *not* inherit its transform from parent **CanvasItem**\ s. Its draw order will also be changed to make it draw on top of other **CanvasItem**\ s that do not have [top_level](class_canvasitem.md#class_CanvasItem_property_top_level) set to ``true``. The **CanvasItem** will effectively act as if it was placed as a child of a bare [Node](class_node.md). + +
+ + + + + +[bool](class_bool.md) **use_parent_material** = `false` [🔗](#class_CanvasItem_property_use_parent_material) + + + +- `void` **set_use_parent_material**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_use_parent_material**\ (\ ) + +If ``true``, the parent **CanvasItem**'s [material](class_canvasitem.md#class_CanvasItem_property_material) is used as this node's material. + +
+ + + + + +[int](class_int.md) **visibility_layer** = `1` [🔗](#class_CanvasItem_property_visibility_layer) + + + +- `void` **set_visibility_layer**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_visibility_layer**\ (\ ) + +The rendering layer in which this **CanvasItem** is rendered by [Viewport](class_viewport.md) nodes. A [Viewport](class_viewport.md) will render a **CanvasItem** if it and all its parents share a layer with the [Viewport](class_viewport.md)'s canvas cull mask. + +
+ + + + + +[bool](class_bool.md) **visible** = `true` [🔗](#class_CanvasItem_property_visible) + + + +- `void` **set_visible**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_visible**\ (\ ) + +If ``true``, this **CanvasItem** may be drawn. Whether this **CanvasItem** is actually drawn depends on the visibility of all of its **CanvasItem** ancestors. In other words: this **CanvasItem** will be drawn when [is_visible_in_tree()](class_canvasitem.md#class_CanvasItem_method_is_visible_in_tree) returns ``true`` and all **CanvasItem** ancestors share at least one [visibility_layer](class_canvasitem.md#class_CanvasItem_property_visibility_layer) with this **CanvasItem**. + +\ **Note:** For controls that inherit [Popup](class_popup.md), the correct way to make them visible is to call one of the multiple ``popup*()`` functions instead. + +
+ + + + + +[bool](class_bool.md) **y_sort_enabled** = `false` [🔗](#class_CanvasItem_property_y_sort_enabled) + + + +- `void` **set_y_sort_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_y_sort_enabled**\ (\ ) + +If ``true``, this and child **CanvasItem** nodes with a higher Y position are rendered in front of nodes with a lower Y position. If ``false``, this and child **CanvasItem** nodes are rendered normally in scene tree order. + +With Y-sorting enabled on a parent node ('A') but disabled on a child node ('B'), the child node ('B') is sorted but its children ('C1', 'C2', etc.) render together on the same Y position as the child node ('B'). This allows you to organize the render order of a scene without changing the scene tree. + +Nodes sort relative to each other only if they are on the same [z_index](class_canvasitem.md#class_CanvasItem_property_z_index). + +
+ + + + + +[bool](class_bool.md) **z_as_relative** = `true` [🔗](#class_CanvasItem_property_z_as_relative) + + + +- `void` **set_z_as_relative**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_z_relative**\ (\ ) + +If ``true``, this node's final Z index is relative to its parent's Z index. + +For example, if [z_index](class_canvasitem.md#class_CanvasItem_property_z_index) is ``2`` and its parent's final Z index is ``3``, then this node's final Z index will be ``5`` (``2 + 3``). + +
+ + + + + +[int](class_int.md) **z_index** = `0` [🔗](#class_CanvasItem_property_z_index) + + + +- `void` **set_z_index**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_z_index**\ (\ ) + +The order in which this node is drawn. A node with a higher Z index will display in front of others. Must be between [RenderingServer.CANVAS_ITEM_Z_MIN](class_renderingserver.md#class_RenderingServer_constant_CANVAS_ITEM_Z_MIN) and [RenderingServer.CANVAS_ITEM_Z_MAX](class_renderingserver.md#class_RenderingServer_constant_CANVAS_ITEM_Z_MAX) (inclusive). + +\ **Note:** The Z index does **not** affect the order in which **CanvasItem** nodes are processed or the way input events are handled. This is especially important to keep in mind for [Control](class_control.md) nodes. + +
+ + + +## Method Descriptions + + + + + +`void` **_draw**\ (\ ) virtual [🔗](#class_CanvasItem_private_method__draw) + +Called when **CanvasItem** has been requested to redraw (after [queue_redraw()](class_canvasitem.md#class_CanvasItem_method_queue_redraw) is called, either manually or by the engine). + +Corresponds to the [NOTIFICATION_DRAW](class_canvasitem.md#class_CanvasItem_constant_NOTIFICATION_DRAW) notification in [Object._notification()](class_object.md#class_Object_private_method__notification). + +
+ + + + + +`void` **draw_animation_slice**\ (\ animation_length\: [float](class_float.md), slice_begin\: [float](class_float.md), slice_end\: [float](class_float.md), offset\: [float](class_float.md) = 0.0\ ) [🔗](#class_CanvasItem_method_draw_animation_slice) + +Subsequent drawing commands will be ignored unless they fall within the specified animation slice. This is a faster way to implement animations that loop on background rather than redrawing constantly. + +
+ + + + + +`void` **draw_arc**\ (\ center\: [Vector2](class_vector2.md), radius\: [float](class_float.md), start_angle\: [float](class_float.md), end_angle\: [float](class_float.md), point_count\: [int](class_int.md), color\: [Color](class_color.md), width\: [float](class_float.md) = -1.0, antialiased\: [bool](class_bool.md) = false\ ) [🔗](#class_CanvasItem_method_draw_arc) + +Draws an unfilled arc between the given angles with a uniform `color` and `width` and optional antialiasing (supported only for positive `width`). The larger the value of `point_count`, the smoother the curve. `center` is defined in local space. See also [draw_circle()](class_canvasitem.md#class_CanvasItem_method_draw_circle). + +If `width` is negative, it will be ignored and the arc will be drawn using [RenderingServer.PRIMITIVE_LINE_STRIP](class_renderingserver.md#class_RenderingServer_constant_PRIMITIVE_LINE_STRIP). This means that when the CanvasItem is scaled, the arc will remain thin. If this behavior is not desired, then pass a positive `width` like ``1.0``. + +The arc is drawn from `start_angle` towards the value of `end_angle` so in clockwise direction if ``start_angle < end_angle`` and counter-clockwise otherwise. Passing the same angles but in reversed order will produce the same arc. If absolute difference of `start_angle` and `end_angle` is greater than [@GDScript.TAU](class_@gdscript.md#class_@GDScript_constant_TAU) radians, then a full circle arc is drawn (i.e. arc will not overlap itself). + +
+ + + + + +`void` **draw_char**\ (\ font\: [Font](class_font.md), pos\: [Vector2](class_vector2.md), char\: [String](class_string.md), font_size\: [int](class_int.md) = 16, modulate\: [Color](class_color.md) = Color(1, 1, 1, 1), oversampling\: [float](class_float.md) = 0.0\ ) const [🔗](#class_CanvasItem_method_draw_char) + +Draws a string first character using a custom font. If `oversampling` is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used. `pos` is defined in local space. + +
+ + + + + +`void` **draw_char_outline**\ (\ font\: [Font](class_font.md), pos\: [Vector2](class_vector2.md), char\: [String](class_string.md), font_size\: [int](class_int.md) = 16, size\: [int](class_int.md) = -1, modulate\: [Color](class_color.md) = Color(1, 1, 1, 1), oversampling\: [float](class_float.md) = 0.0\ ) const [🔗](#class_CanvasItem_method_draw_char_outline) + +Draws a string first character outline using a custom font. If `oversampling` is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used. `pos` is defined in local space. + +
+ + + + + +`void` **draw_circle**\ (\ position\: [Vector2](class_vector2.md), radius\: [float](class_float.md), color\: [Color](class_color.md), filled\: [bool](class_bool.md) = true, width\: [float](class_float.md) = -1.0, antialiased\: [bool](class_bool.md) = false\ ) [🔗](#class_CanvasItem_method_draw_circle) + +Draws a circle, with `position` defined in local space. See also [draw_arc()](class_canvasitem.md#class_CanvasItem_method_draw_arc), [draw_polyline()](class_canvasitem.md#class_CanvasItem_method_draw_polyline), and [draw_polygon()](class_canvasitem.md#class_CanvasItem_method_draw_polygon). + +If `filled` is ``true``, the circle will be filled with the `color` specified. If `filled` is ``false``, the circle will be drawn as a stroke with the `color` and `width` specified. + +If `width` is negative, then two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the lines will remain thin. If this behavior is not desired, then pass a positive `width` like ``1.0``. + +If `antialiased` is ``true``, half transparent "feathers" will be attached to the boundary, making outlines smooth. + +\ **Note:** `width` is only effective if `filled` is ``false``. + +
+ + + + + +`void` **draw_colored_polygon**\ (\ points\: [PackedVector2Array](class_packedvector2array.md), color\: [Color](class_color.md), uvs\: [PackedVector2Array](class_packedvector2array.md) = PackedVector2Array(), texture\: [Texture2D](class_texture2d.md) = null\ ) [🔗](#class_CanvasItem_method_draw_colored_polygon) + +Draws a colored polygon of any number of points, convex or concave. The points in the `points` array are defined in local space. Unlike [draw_polygon()](class_canvasitem.md#class_CanvasItem_method_draw_polygon), a single color must be specified for the whole polygon. + +\ **Note:** If you frequently redraw the same polygon with a large number of vertices, consider pre-calculating the triangulation with [Geometry2D.triangulate_polygon()](class_geometry2d.md#class_Geometry2D_method_triangulate_polygon) and using [draw_mesh()](class_canvasitem.md#class_CanvasItem_method_draw_mesh), [draw_multimesh()](class_canvasitem.md#class_CanvasItem_method_draw_multimesh), or [RenderingServer.canvas_item_add_triangle_array()](class_renderingserver.md#class_RenderingServer_method_canvas_item_add_triangle_array). + +
+ + + + + +`void` **draw_dashed_line**\ (\ from\: [Vector2](class_vector2.md), to\: [Vector2](class_vector2.md), color\: [Color](class_color.md), width\: [float](class_float.md) = -1.0, dash\: [float](class_float.md) = 2.0, aligned\: [bool](class_bool.md) = true, antialiased\: [bool](class_bool.md) = false\ ) [🔗](#class_CanvasItem_method_draw_dashed_line) + +Draws a dashed line from a 2D point to another, with a given color and width. The `from` and `to` positions are defined in local space. See also [draw_line()](class_canvasitem.md#class_CanvasItem_method_draw_line), [draw_multiline()](class_canvasitem.md#class_CanvasItem_method_draw_multiline), and [draw_polyline()](class_canvasitem.md#class_CanvasItem_method_draw_polyline). + +If `width` is negative, then a two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the line parts will remain thin. If this behavior is not desired, then pass a positive `width` like ``1.0``. + +\ `dash` is the length of each dash in pixels, with the gap between each dash being the same length. If `aligned` is ``true``, the length of the first and last dashes may be shortened or lengthened to allow the line to begin and end at the precise points defined by `from` and `to`. Both ends are always symmetrical when `aligned` is ``true``. If `aligned` is ``false``, all dashes will have the same length, but the line may appear incomplete at the end due to the dash length not dividing evenly into the line length. Only full dashes are drawn when `aligned` is ``false``. + +If `antialiased` is ``true``, half transparent "feathers" will be attached to the boundary, making outlines smooth. + +\ **Note:** `antialiased` is only effective if `width` is greater than ``0.0``. + +
+ + + + + +`void` **draw_end_animation**\ (\ ) [🔗](#class_CanvasItem_method_draw_end_animation) + +After submitting all animations slices via [draw_animation_slice()](class_canvasitem.md#class_CanvasItem_method_draw_animation_slice), this function can be used to revert drawing to its default state (all subsequent drawing commands will be visible). If you don't care about this particular use case, usage of this function after submitting the slices is not required. + +
+ + + + + +`void` **draw_lcd_texture_rect_region**\ (\ texture\: [Texture2D](class_texture2d.md), rect\: [Rect2](class_rect2.md), src_rect\: [Rect2](class_rect2.md), modulate\: [Color](class_color.md) = Color(1, 1, 1, 1)\ ) [🔗](#class_CanvasItem_method_draw_lcd_texture_rect_region) + +Draws a textured rectangle region of the font texture with LCD subpixel anti-aliasing at a given position, optionally modulated by a color. The `rect` is defined in local space. + +Texture is drawn using the following blend operation, blend mode of the [CanvasItemMaterial](class_canvasitemmaterial.md) is ignored: + +``` + dst.r = texture.r * modulate.r * modulate.a + dst.r * (1.0 - texture.r * modulate.a); + dst.g = texture.g * modulate.g * modulate.a + dst.g * (1.0 - texture.g * modulate.a); + dst.b = texture.b * modulate.b * modulate.a + dst.b * (1.0 - texture.b * modulate.a); + dst.a = modulate.a + dst.a * (1.0 - modulate.a); +``` + +
+ + + + + +`void` **draw_line**\ (\ from\: [Vector2](class_vector2.md), to\: [Vector2](class_vector2.md), color\: [Color](class_color.md), width\: [float](class_float.md) = -1.0, antialiased\: [bool](class_bool.md) = false\ ) [🔗](#class_CanvasItem_method_draw_line) + +Draws a line from a 2D point to another, with a given color and width. It can be optionally antialiased. The `from` and `to` positions are defined in local space. See also [draw_dashed_line()](class_canvasitem.md#class_CanvasItem_method_draw_dashed_line), [draw_multiline()](class_canvasitem.md#class_CanvasItem_method_draw_multiline), and [draw_polyline()](class_canvasitem.md#class_CanvasItem_method_draw_polyline). + +If `width` is negative, then a two-point primitive will be drawn instead of a four-point one. This means that when the CanvasItem is scaled, the line will remain thin. If this behavior is not desired, then pass a positive `width` like ``1.0``. + +
+ + + + + +`void` **draw_mesh**\ (\ mesh\: [Mesh](class_mesh.md), texture\: [Texture2D](class_texture2d.md), transform\: [Transform2D](class_transform2d.md) = Transform2D(1, 0, 0, 1, 0, 0), modulate\: [Color](class_color.md) = Color(1, 1, 1, 1)\ ) [🔗](#class_CanvasItem_method_draw_mesh) + +Draws a [Mesh](class_mesh.md) in 2D, using the provided texture. See [MeshInstance2D](class_meshinstance2d.md) for related documentation. The `transform` is defined in local space. + +
+ + + + + +`void` **draw_msdf_texture_rect_region**\ (\ texture\: [Texture2D](class_texture2d.md), rect\: [Rect2](class_rect2.md), src_rect\: [Rect2](class_rect2.md), modulate\: [Color](class_color.md) = Color(1, 1, 1, 1), outline\: [float](class_float.md) = 0.0, pixel_range\: [float](class_float.md) = 4.0, scale\: [float](class_float.md) = 1.0\ ) [🔗](#class_CanvasItem_method_draw_msdf_texture_rect_region) + +Draws a textured rectangle region of the multichannel signed distance field texture at a given position, optionally modulated by a color. The `rect` is defined in local space. See [FontFile.multichannel_signed_distance_field](class_fontfile.md#class_FontFile_property_multichannel_signed_distance_field) for more information and caveats about MSDF font rendering. + +If `outline` is positive, each alpha channel value of pixel in region is set to maximum value of true distance in the `outline` radius. + +Value of the `pixel_range` should the same that was used during distance field texture generation. + +
+ + + + + +`void` **draw_multiline**\ (\ points\: [PackedVector2Array](class_packedvector2array.md), color\: [Color](class_color.md), width\: [float](class_float.md) = -1.0, antialiased\: [bool](class_bool.md) = false\ ) [🔗](#class_CanvasItem_method_draw_multiline) + +Draws multiple disconnected lines with a uniform `width` and `color`. Each line is defined by two consecutive points from `points` array in local space, i.e. i-th segment consists of ``points[2 * i]``, ``points[2 * i + 1]`` endpoints. When drawing large amounts of lines, this is faster than using individual [draw_line()](class_canvasitem.md#class_CanvasItem_method_draw_line) calls. To draw interconnected lines, use [draw_polyline()](class_canvasitem.md#class_CanvasItem_method_draw_polyline) instead. + +If `width` is negative, then two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the lines will remain thin. If this behavior is not desired, then pass a positive `width` like ``1.0``. + +\ **Note:** `antialiased` is only effective if `width` is greater than ``0.0``. + +
+ + + + + +`void` **draw_multiline_colors**\ (\ points\: [PackedVector2Array](class_packedvector2array.md), colors\: [PackedColorArray](class_packedcolorarray.md), width\: [float](class_float.md) = -1.0, antialiased\: [bool](class_bool.md) = false\ ) [🔗](#class_CanvasItem_method_draw_multiline_colors) + +Draws multiple disconnected lines with a uniform `width` and segment-by-segment coloring. Each segment is defined by two consecutive points from `points` array in local space and a corresponding color from `colors` array, i.e. i-th segment consists of ``points[2 * i]``, ``points[2 * i + 1]`` endpoints and has ``colors[i]`` color. When drawing large amounts of lines, this is faster than using individual [draw_line()](class_canvasitem.md#class_CanvasItem_method_draw_line) calls. To draw interconnected lines, use [draw_polyline_colors()](class_canvasitem.md#class_CanvasItem_method_draw_polyline_colors) instead. + +If `width` is negative, then two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the lines will remain thin. If this behavior is not desired, then pass a positive `width` like ``1.0``. + +\ **Note:** `antialiased` is only effective if `width` is greater than ``0.0``. + +
+ + + + + +`void` **draw_multiline_string**\ (\ font\: [Font](class_font.md), pos\: [Vector2](class_vector2.md), text\: [String](class_string.md), alignment\: [HorizontalAlignment](class_@globalscope.md#enum_@GlobalScope_HorizontalAlignment) = 0, width\: [float](class_float.md) = -1, font_size\: [int](class_int.md) = 16, max_lines\: [int](class_int.md) = -1, modulate\: [Color](class_color.md) = Color(1, 1, 1, 1), brk_flags\: **BitField**\[[LineBreakFlag](class_textserver.md#enum_TextServer_LineBreakFlag)\] = 3, justification_flags\: **BitField**\[[JustificationFlag](class_textserver.md#enum_TextServer_JustificationFlag)\] = 3, direction\: [Direction](class_textserver.md#enum_TextServer_Direction) = 0, orientation\: [Orientation](class_textserver.md#enum_TextServer_Orientation) = 0, oversampling\: [float](class_float.md) = 0.0\ ) const [🔗](#class_CanvasItem_method_draw_multiline_string) + +Breaks `text` into lines and draws it using the specified `font` at the `pos` in local space (top-left corner). The text will have its color multiplied by `modulate`. If `width` is greater than or equal to 0, the text will be clipped if it exceeds the specified width. If `oversampling` is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used. + +
+ + + + + +`void` **draw_multiline_string_outline**\ (\ font\: [Font](class_font.md), pos\: [Vector2](class_vector2.md), text\: [String](class_string.md), alignment\: [HorizontalAlignment](class_@globalscope.md#enum_@GlobalScope_HorizontalAlignment) = 0, width\: [float](class_float.md) = -1, font_size\: [int](class_int.md) = 16, max_lines\: [int](class_int.md) = -1, size\: [int](class_int.md) = 1, modulate\: [Color](class_color.md) = Color(1, 1, 1, 1), brk_flags\: **BitField**\[[LineBreakFlag](class_textserver.md#enum_TextServer_LineBreakFlag)\] = 3, justification_flags\: **BitField**\[[JustificationFlag](class_textserver.md#enum_TextServer_JustificationFlag)\] = 3, direction\: [Direction](class_textserver.md#enum_TextServer_Direction) = 0, orientation\: [Orientation](class_textserver.md#enum_TextServer_Orientation) = 0, oversampling\: [float](class_float.md) = 0.0\ ) const [🔗](#class_CanvasItem_method_draw_multiline_string_outline) + +Breaks `text` to the lines and draws text outline using the specified `font` at the `pos` in local space (top-left corner). The text will have its color multiplied by `modulate`. If `width` is greater than or equal to 0, the text will be clipped if it exceeds the specified width. If `oversampling` is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used. + +
+ + + + + +`void` **draw_multimesh**\ (\ multimesh\: [MultiMesh](class_multimesh.md), texture\: [Texture2D](class_texture2d.md)\ ) [🔗](#class_CanvasItem_method_draw_multimesh) + +Draws a [MultiMesh](class_multimesh.md) in 2D with the provided texture. See [MultiMeshInstance2D](class_multimeshinstance2d.md) for related documentation. + +
+ + + + + +`void` **draw_polygon**\ (\ points\: [PackedVector2Array](class_packedvector2array.md), colors\: [PackedColorArray](class_packedcolorarray.md), uvs\: [PackedVector2Array](class_packedvector2array.md) = PackedVector2Array(), texture\: [Texture2D](class_texture2d.md) = null\ ) [🔗](#class_CanvasItem_method_draw_polygon) + +Draws a solid polygon of any number of points, convex or concave. Unlike [draw_colored_polygon()](class_canvasitem.md#class_CanvasItem_method_draw_colored_polygon), each point's color can be changed individually. The `points` array is defined in local space. See also [draw_polyline()](class_canvasitem.md#class_CanvasItem_method_draw_polyline) and [draw_polyline_colors()](class_canvasitem.md#class_CanvasItem_method_draw_polyline_colors). If you need more flexibility (such as being able to use bones), use [RenderingServer.canvas_item_add_triangle_array()](class_renderingserver.md#class_RenderingServer_method_canvas_item_add_triangle_array) instead. + +\ **Note:** If you frequently redraw the same polygon with a large number of vertices, consider pre-calculating the triangulation with [Geometry2D.triangulate_polygon()](class_geometry2d.md#class_Geometry2D_method_triangulate_polygon) and using [draw_mesh()](class_canvasitem.md#class_CanvasItem_method_draw_mesh), [draw_multimesh()](class_canvasitem.md#class_CanvasItem_method_draw_multimesh), or [RenderingServer.canvas_item_add_triangle_array()](class_renderingserver.md#class_RenderingServer_method_canvas_item_add_triangle_array). + +
+ + + + + +`void` **draw_polyline**\ (\ points\: [PackedVector2Array](class_packedvector2array.md), color\: [Color](class_color.md), width\: [float](class_float.md) = -1.0, antialiased\: [bool](class_bool.md) = false\ ) [🔗](#class_CanvasItem_method_draw_polyline) + +Draws interconnected line segments with a uniform `color` and `width` and optional antialiasing (supported only for positive `width`). The `points` array is defined in local space. When drawing large amounts of lines, this is faster than using individual [draw_line()](class_canvasitem.md#class_CanvasItem_method_draw_line) calls. To draw disconnected lines, use [draw_multiline()](class_canvasitem.md#class_CanvasItem_method_draw_multiline) instead. See also [draw_polygon()](class_canvasitem.md#class_CanvasItem_method_draw_polygon). + +If `width` is negative, it will be ignored and the polyline will be drawn using [RenderingServer.PRIMITIVE_LINE_STRIP](class_renderingserver.md#class_RenderingServer_constant_PRIMITIVE_LINE_STRIP). This means that when the CanvasItem is scaled, the polyline will remain thin. If this behavior is not desired, then pass a positive `width` like ``1.0``. + +
+ + + + + +`void` **draw_polyline_colors**\ (\ points\: [PackedVector2Array](class_packedvector2array.md), colors\: [PackedColorArray](class_packedcolorarray.md), width\: [float](class_float.md) = -1.0, antialiased\: [bool](class_bool.md) = false\ ) [🔗](#class_CanvasItem_method_draw_polyline_colors) + +Draws interconnected line segments with a uniform `width`, point-by-point coloring, and optional antialiasing (supported only for positive `width`). Colors assigned to line points match by index between `points` and `colors`, i.e. each line segment is filled with a gradient between the colors of the endpoints. The `points` array is defined in local space. When drawing large amounts of lines, this is faster than using individual [draw_line()](class_canvasitem.md#class_CanvasItem_method_draw_line) calls. To draw disconnected lines, use [draw_multiline_colors()](class_canvasitem.md#class_CanvasItem_method_draw_multiline_colors) instead. See also [draw_polygon()](class_canvasitem.md#class_CanvasItem_method_draw_polygon). + +If `width` is negative, it will be ignored and the polyline will be drawn using [RenderingServer.PRIMITIVE_LINE_STRIP](class_renderingserver.md#class_RenderingServer_constant_PRIMITIVE_LINE_STRIP). This means that when the CanvasItem is scaled, the polyline will remain thin. If this behavior is not desired, then pass a positive `width` like ``1.0``. + +
+ + + + + +`void` **draw_primitive**\ (\ points\: [PackedVector2Array](class_packedvector2array.md), colors\: [PackedColorArray](class_packedcolorarray.md), uvs\: [PackedVector2Array](class_packedvector2array.md), texture\: [Texture2D](class_texture2d.md) = null\ ) [🔗](#class_CanvasItem_method_draw_primitive) + +Draws a custom primitive. 1 point for a point, 2 points for a line, 3 points for a triangle, and 4 points for a quad. If 0 points or more than 4 points are specified, nothing will be drawn and an error message will be printed. The `points` array is defined in local space. See also [draw_line()](class_canvasitem.md#class_CanvasItem_method_draw_line), [draw_polyline()](class_canvasitem.md#class_CanvasItem_method_draw_polyline), [draw_polygon()](class_canvasitem.md#class_CanvasItem_method_draw_polygon), and [draw_rect()](class_canvasitem.md#class_CanvasItem_method_draw_rect). + +
+ + + + + +`void` **draw_rect**\ (\ rect\: [Rect2](class_rect2.md), color\: [Color](class_color.md), filled\: [bool](class_bool.md) = true, width\: [float](class_float.md) = -1.0, antialiased\: [bool](class_bool.md) = false\ ) [🔗](#class_CanvasItem_method_draw_rect) + +Draws a rectangle. If `filled` is ``true``, the rectangle will be filled with the `color` specified. If `filled` is ``false``, the rectangle will be drawn as a stroke with the `color` and `width` specified. The `rect` is specified in local space. See also [draw_texture_rect()](class_canvasitem.md#class_CanvasItem_method_draw_texture_rect). + +If `width` is negative, then two-point primitives will be drawn instead of a four-point ones. This means that when the CanvasItem is scaled, the lines will remain thin. If this behavior is not desired, then pass a positive `width` like ``1.0``. + +If `antialiased` is ``true``, half transparent "feathers" will be attached to the boundary, making outlines smooth. + +\ **Note:** `width` is only effective if `filled` is ``false``. + +\ **Note:** Unfilled rectangles drawn with a negative `width` may not display perfectly. For example, corners may be missing or brighter due to overlapping lines (for a translucent `color`). + +
+ + + + + +`void` **draw_set_transform**\ (\ position\: [Vector2](class_vector2.md), rotation\: [float](class_float.md) = 0.0, scale\: [Vector2](class_vector2.md) = Vector2(1, 1)\ ) [🔗](#class_CanvasItem_method_draw_set_transform) + +Sets a custom local transform for drawing via components. Anything drawn afterwards will be transformed by this. + +\ **Note:** [FontFile.oversampling](class_fontfile.md#class_FontFile_property_oversampling) does *not* take `scale` into account. This means that scaling up/down will cause bitmap fonts and rasterized (non-MSDF) dynamic fonts to appear blurry or pixelated. To ensure text remains crisp regardless of scale, you can enable MSDF font rendering by enabling [ProjectSettings.gui/theme/default_font_multichannel_signed_distance_field](class_projectsettings.md#class_ProjectSettings_property_gui/theme/default_font_multichannel_signed_distance_field) (applies to the default project font only), or enabling **Multichannel Signed Distance Field** in the import options of a DynamicFont for custom fonts. On system fonts, [SystemFont.multichannel_signed_distance_field](class_systemfont.md#class_SystemFont_property_multichannel_signed_distance_field) can be enabled in the inspector. + +
+ + + + + +`void` **draw_set_transform_matrix**\ (\ xform\: [Transform2D](class_transform2d.md)\ ) [🔗](#class_CanvasItem_method_draw_set_transform_matrix) + +Sets a custom local transform for drawing via matrix. Anything drawn afterwards will be transformed by this. + +
+ + + + + +`void` **draw_string**\ (\ font\: [Font](class_font.md), pos\: [Vector2](class_vector2.md), text\: [String](class_string.md), alignment\: [HorizontalAlignment](class_@globalscope.md#enum_@GlobalScope_HorizontalAlignment) = 0, width\: [float](class_float.md) = -1, font_size\: [int](class_int.md) = 16, modulate\: [Color](class_color.md) = Color(1, 1, 1, 1), justification_flags\: **BitField**\[[JustificationFlag](class_textserver.md#enum_TextServer_JustificationFlag)\] = 3, direction\: [Direction](class_textserver.md#enum_TextServer_Direction) = 0, orientation\: [Orientation](class_textserver.md#enum_TextServer_Orientation) = 0, oversampling\: [float](class_float.md) = 0.0\ ) const [🔗](#class_CanvasItem_method_draw_string) + +Draws `text` using the specified `font` at the `pos` in local space (bottom-left corner using the baseline of the font). The text will have its color multiplied by `modulate`. If `width` is greater than or equal to 0, the text will be clipped if it exceeds the specified width. If `oversampling` is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used. + +\ **Example:** Draw "Hello world", using the project's default font: + + + + +```gdscript + # If using this method in a script that redraws constantly, move the + # `default_font` declaration to a member variable assigned in `_ready()` + # so the Control is only created once. + var default_font = ThemeDB.fallback_font + var default_font_size = ThemeDB.fallback_font_size + draw_string(default_font, Vector2(64, 64), "Hello world", HORIZONTAL_ALIGNMENT_LEFT, -1, default_font_size) +``` + +```csharp + // If using this method in a script that redraws constantly, move the + // `default_font` declaration to a member variable assigned in `_Ready()` + // so the Control is only created once. + Font defaultFont = ThemeDB.FallbackFont; + int defaultFontSize = ThemeDB.FallbackFontSize; + DrawString(defaultFont, new Vector2(64, 64), "Hello world", HORIZONTAL_ALIGNMENT_LEFT, -1, defaultFontSize); +``` + + + +See also [Font.draw_string()](class_font.md#class_Font_method_draw_string). + +
+ + + + + +`void` **draw_string_outline**\ (\ font\: [Font](class_font.md), pos\: [Vector2](class_vector2.md), text\: [String](class_string.md), alignment\: [HorizontalAlignment](class_@globalscope.md#enum_@GlobalScope_HorizontalAlignment) = 0, width\: [float](class_float.md) = -1, font_size\: [int](class_int.md) = 16, size\: [int](class_int.md) = 1, modulate\: [Color](class_color.md) = Color(1, 1, 1, 1), justification_flags\: **BitField**\[[JustificationFlag](class_textserver.md#enum_TextServer_JustificationFlag)\] = 3, direction\: [Direction](class_textserver.md#enum_TextServer_Direction) = 0, orientation\: [Orientation](class_textserver.md#enum_TextServer_Orientation) = 0, oversampling\: [float](class_float.md) = 0.0\ ) const [🔗](#class_CanvasItem_method_draw_string_outline) + +Draws `text` outline using the specified `font` at the `pos` in local space (bottom-left corner using the baseline of the font). The text will have its color multiplied by `modulate`. If `width` is greater than or equal to 0, the text will be clipped if it exceeds the specified width. If `oversampling` is greater than zero, it is used as font oversampling factor, otherwise viewport oversampling settings are used. + +
+ + + + + +`void` **draw_style_box**\ (\ style_box\: [StyleBox](class_stylebox.md), rect\: [Rect2](class_rect2.md)\ ) [🔗](#class_CanvasItem_method_draw_style_box) + +Draws a styled rectangle. The `rect` is defined in local space. + +
+ + + + + +`void` **draw_texture**\ (\ texture\: [Texture2D](class_texture2d.md), position\: [Vector2](class_vector2.md), modulate\: [Color](class_color.md) = Color(1, 1, 1, 1)\ ) [🔗](#class_CanvasItem_method_draw_texture) + +Draws a texture at a given position. The `position` is defined in local space. + +
+ + + + + +`void` **draw_texture_rect**\ (\ texture\: [Texture2D](class_texture2d.md), rect\: [Rect2](class_rect2.md), tile\: [bool](class_bool.md), modulate\: [Color](class_color.md) = Color(1, 1, 1, 1), transpose\: [bool](class_bool.md) = false\ ) [🔗](#class_CanvasItem_method_draw_texture_rect) + +Draws a textured rectangle at a given position, optionally modulated by a color. The `rect` is defined in local space. If `transpose` is ``true``, the texture will have its X and Y coordinates swapped. See also [draw_rect()](class_canvasitem.md#class_CanvasItem_method_draw_rect) and [draw_texture_rect_region()](class_canvasitem.md#class_CanvasItem_method_draw_texture_rect_region). + +
+ + + + + +`void` **draw_texture_rect_region**\ (\ texture\: [Texture2D](class_texture2d.md), rect\: [Rect2](class_rect2.md), src_rect\: [Rect2](class_rect2.md), modulate\: [Color](class_color.md) = Color(1, 1, 1, 1), transpose\: [bool](class_bool.md) = false, clip_uv\: [bool](class_bool.md) = true\ ) [🔗](#class_CanvasItem_method_draw_texture_rect_region) + +Draws a textured rectangle from a texture's region (specified by `src_rect`) at a given position in local space, optionally modulated by a color. If `transpose` is ``true``, the texture will have its X and Y coordinates swapped. See also [draw_texture_rect()](class_canvasitem.md#class_CanvasItem_method_draw_texture_rect). + +
+ + + + + +`void` **force_update_transform**\ (\ ) [🔗](#class_CanvasItem_method_force_update_transform) + +Forces the node's transform to update. Fails if the node is not inside the tree. See also [get_transform()](class_canvasitem.md#class_CanvasItem_method_get_transform). + +\ **Note:** For performance reasons, transform changes are usually accumulated and applied *once* at the end of the frame. The update propagates through **CanvasItem** children, as well. Therefore, use this method only when you need an up-to-date transform (such as during physics operations). + +
+ + + + + +[RID](class_rid.md) **get_canvas**\ (\ ) const [🔗](#class_CanvasItem_method_get_canvas) + +Returns the [RID](class_rid.md) of the [World2D](class_world2d.md) canvas where this node is registered to, used by the [RenderingServer](class_renderingserver.md). + +
+ + + + + +[RID](class_rid.md) **get_canvas_item**\ (\ ) const [🔗](#class_CanvasItem_method_get_canvas_item) + +Returns the internal canvas item [RID](class_rid.md) used by the [RenderingServer](class_renderingserver.md) for this node. + +
+ + + + + +[CanvasLayer](class_canvaslayer.md) **get_canvas_layer_node**\ (\ ) const [🔗](#class_CanvasItem_method_get_canvas_layer_node) + +Returns the [CanvasLayer](class_canvaslayer.md) that contains this node, or ``null`` if the node is not in any [CanvasLayer](class_canvaslayer.md). + +
+ + + + + +[Transform2D](class_transform2d.md) **get_canvas_transform**\ (\ ) const [🔗](#class_CanvasItem_method_get_canvas_transform) + +Returns the transform of this node, converted from its registered canvas's coordinate system to its viewport's coordinate system. See also [Node.get_viewport()](class_node.md#class_Node_method_get_viewport). + +
+ + + + + +[Vector2](class_vector2.md) **get_global_mouse_position**\ (\ ) const [🔗](#class_CanvasItem_method_get_global_mouse_position) + +Returns mouse cursor's global position relative to the [CanvasLayer](class_canvaslayer.md) that contains this node. + +\ **Note:** For screen-space coordinates (e.g. when using a non-embedded [Popup](class_popup.md)), you can use [DisplayServer.mouse_get_position()](class_displayserver.md#class_DisplayServer_method_mouse_get_position). + +
+ + + + + +[Transform2D](class_transform2d.md) **get_global_transform**\ (\ ) const [🔗](#class_CanvasItem_method_get_global_transform) + +Returns the global transform matrix of this item, i.e. the combined transform up to the topmost **CanvasItem** node. The topmost item is a **CanvasItem** that either has no parent, has non-**CanvasItem** parent or it has [top_level](class_canvasitem.md#class_CanvasItem_property_top_level) enabled. + +
+ + + + + +[Transform2D](class_transform2d.md) **get_global_transform_with_canvas**\ (\ ) const [🔗](#class_CanvasItem_method_get_global_transform_with_canvas) + +Returns the transform from the local coordinate system of this **CanvasItem** to the [Viewport](class_viewport.md)\ s coordinate system. + +
+ + + + + +[Variant](class_variant.md) **get_instance_shader_parameter**\ (\ name\: [StringName](class_stringname.md)\ ) const [🔗](#class_CanvasItem_method_get_instance_shader_parameter) + +Get the value of a shader parameter as set on this instance. + +
+ + + + + +[Vector2](class_vector2.md) **get_local_mouse_position**\ (\ ) const [🔗](#class_CanvasItem_method_get_local_mouse_position) + +Returns the mouse's position in this **CanvasItem** using the local coordinate system of this **CanvasItem**. + +
+ + + + + +[Transform2D](class_transform2d.md) **get_screen_transform**\ (\ ) const [🔗](#class_CanvasItem_method_get_screen_transform) + +Returns the transform of this **CanvasItem** in global screen coordinates (i.e. taking window position into account). Mostly useful for editor plugins. + +Equals to [get_global_transform()](class_canvasitem.md#class_CanvasItem_method_get_global_transform) if the window is embedded (see [Viewport.gui_embed_subwindows](class_viewport.md#class_Viewport_property_gui_embed_subwindows)). + +
+ + + + + +[Transform2D](class_transform2d.md) **get_transform**\ (\ ) const [🔗](#class_CanvasItem_method_get_transform) + +Returns the transform matrix of this **CanvasItem**. + +
+ + + + + +[Rect2](class_rect2.md) **get_viewport_rect**\ (\ ) const [🔗](#class_CanvasItem_method_get_viewport_rect) + +Returns this node's viewport boundaries as a [Rect2](class_rect2.md). See also [Node.get_viewport()](class_node.md#class_Node_method_get_viewport). + +
+ + + + + +[Transform2D](class_transform2d.md) **get_viewport_transform**\ (\ ) const [🔗](#class_CanvasItem_method_get_viewport_transform) + +Returns the transform of this node, converted from its registered canvas's coordinate system to its viewport embedder's coordinate system. See also [Viewport.get_final_transform()](class_viewport.md#class_Viewport_method_get_final_transform) and [Node.get_viewport()](class_node.md#class_Node_method_get_viewport). + +
+ + + + + +[bool](class_bool.md) **get_visibility_layer_bit**\ (\ layer\: [int](class_int.md)\ ) const [🔗](#class_CanvasItem_method_get_visibility_layer_bit) + +Returns ``true`` if the layer at the given index is set in [visibility_layer](class_canvasitem.md#class_CanvasItem_property_visibility_layer). + +
+ + + + + +[World2D](class_world2d.md) **get_world_2d**\ (\ ) const [🔗](#class_CanvasItem_method_get_world_2d) + +Returns the [World2D](class_world2d.md) this node is registered to. + +Usually, this is the same as this node's viewport (see [Node.get_viewport()](class_node.md#class_Node_method_get_viewport) and [Viewport.find_world_2d()](class_viewport.md#class_Viewport_method_find_world_2d)). + +
+ + + + + +`void` **hide**\ (\ ) [🔗](#class_CanvasItem_method_hide) + +Hide the **CanvasItem** if it's currently visible. This is equivalent to setting [visible](class_canvasitem.md#class_CanvasItem_property_visible) to ``false``. + +
+ + + + + +[bool](class_bool.md) **is_local_transform_notification_enabled**\ (\ ) const [🔗](#class_CanvasItem_method_is_local_transform_notification_enabled) + +Returns ``true`` if the node receives [NOTIFICATION_LOCAL_TRANSFORM_CHANGED](class_canvasitem.md#class_CanvasItem_constant_NOTIFICATION_LOCAL_TRANSFORM_CHANGED) whenever its local transform changes. This is enabled with [set_notify_local_transform()](class_canvasitem.md#class_CanvasItem_method_set_notify_local_transform). + +
+ + + + + +[bool](class_bool.md) **is_transform_notification_enabled**\ (\ ) const [🔗](#class_CanvasItem_method_is_transform_notification_enabled) + +Returns ``true`` if the node receives [NOTIFICATION_TRANSFORM_CHANGED](class_canvasitem.md#class_CanvasItem_constant_NOTIFICATION_TRANSFORM_CHANGED) whenever its global transform changes. This is enabled with [set_notify_transform()](class_canvasitem.md#class_CanvasItem_method_set_notify_transform). + +
+ + + + + +[bool](class_bool.md) **is_visible_in_tree**\ (\ ) const [🔗](#class_CanvasItem_method_is_visible_in_tree) + +Returns ``true`` if the node is present in the [SceneTree](class_scenetree.md), its [visible](class_canvasitem.md#class_CanvasItem_property_visible) property is ``true`` and all its ancestors are also visible. If any ancestor is hidden, this node will not be visible in the scene tree, and is therefore not drawn (see [_draw()](class_canvasitem.md#class_CanvasItem_private_method__draw)). + +Visibility is checked only in parent nodes that inherit from **CanvasItem**, [CanvasLayer](class_canvaslayer.md), and [Window](class_window.md). If the parent is of any other type (such as [Node](class_node.md), [AnimationPlayer](class_animationplayer.md), or [Node3D](class_node3d.md)), it is assumed to be visible. + +\ **Note:** This method does not take [visibility_layer](class_canvasitem.md#class_CanvasItem_property_visibility_layer) into account, so even if this method returns ``true``, the node might end up not being rendered. + +
+ + + + + +[Vector2](class_vector2.md) **make_canvas_position_local**\ (\ viewport_point\: [Vector2](class_vector2.md)\ ) const [🔗](#class_CanvasItem_method_make_canvas_position_local) + +Transforms `viewport_point` from the viewport's coordinates to this node's local coordinates. + +For the opposite operation, use [get_global_transform_with_canvas()](class_canvasitem.md#class_CanvasItem_method_get_global_transform_with_canvas). + +``` + var viewport_point = get_global_transform_with_canvas() * local_point +``` + +
+ + + + + +[InputEvent](class_inputevent.md) **make_input_local**\ (\ event\: [InputEvent](class_inputevent.md)\ ) const [🔗](#class_CanvasItem_method_make_input_local) + +Returns a copy of the given `event` with its coordinates converted from global space to this **CanvasItem**'s local space. If not possible, returns the same [InputEvent](class_inputevent.md) unchanged. + +
+ + + + + +`void` **move_to_front**\ (\ ) [🔗](#class_CanvasItem_method_move_to_front) + +Moves this node below its siblings, usually causing the node to draw on top of its siblings. Does nothing if this node does not have a parent. See also [Node.move_child()](class_node.md#class_Node_method_move_child). + +
+ + + + + +`void` **queue_redraw**\ (\ ) [🔗](#class_CanvasItem_method_queue_redraw) + +Queues the **CanvasItem** to redraw. During idle time, if **CanvasItem** is visible, [NOTIFICATION_DRAW](class_canvasitem.md#class_CanvasItem_constant_NOTIFICATION_DRAW) is sent and [_draw()](class_canvasitem.md#class_CanvasItem_private_method__draw) is called. This only occurs **once** per frame, even if this method has been called multiple times. + +
+ + + + + +`void` **set_instance_shader_parameter**\ (\ name\: [StringName](class_stringname.md), value\: [Variant](class_variant.md)\ ) [🔗](#class_CanvasItem_method_set_instance_shader_parameter) + +Set the value of a shader uniform for this instance only ([per-instance uniform](../tutorials/shaders/shader_reference/shading_language.md#per-instance-uniforms)). See also [ShaderMaterial.set_shader_parameter()](class_shadermaterial.md#class_ShaderMaterial_method_set_shader_parameter) to assign a uniform on all instances using the same [ShaderMaterial](class_shadermaterial.md). + +\ **Note:** For a shader uniform to be assignable on a per-instance basis, it *must* be defined with ``instance uniform ...`` rather than ``uniform ...`` in the shader code. + +\ **Note:** `name` is case-sensitive and must match the name of the uniform in the code exactly (not the capitalized name in the inspector). + +
+ + + + + +`void` **set_notify_local_transform**\ (\ enable\: [bool](class_bool.md)\ ) [🔗](#class_CanvasItem_method_set_notify_local_transform) + +If ``true``, the node will receive [NOTIFICATION_LOCAL_TRANSFORM_CHANGED](class_canvasitem.md#class_CanvasItem_constant_NOTIFICATION_LOCAL_TRANSFORM_CHANGED) whenever its local transform changes. + +\ **Note:** Many canvas items such as [Bone2D](class_bone2d.md) or [CollisionShape2D](class_collisionshape2d.md) automatically enable this in order to function correctly. + +
+ + + + + +`void` **set_notify_transform**\ (\ enable\: [bool](class_bool.md)\ ) [🔗](#class_CanvasItem_method_set_notify_transform) + +If ``true``, the node will receive [NOTIFICATION_TRANSFORM_CHANGED](class_canvasitem.md#class_CanvasItem_constant_NOTIFICATION_TRANSFORM_CHANGED) whenever global transform changes. + +\ **Note:** Many canvas items such as [Camera2D](class_camera2d.md) or [Light2D](class_light2d.md) automatically enable this in order to function correctly. + +
+ + + + + +`void` **set_visibility_layer_bit**\ (\ layer\: [int](class_int.md), enabled\: [bool](class_bool.md)\ ) [🔗](#class_CanvasItem_method_set_visibility_layer_bit) + +Set/clear individual bits on the rendering visibility layer. This simplifies editing this **CanvasItem**'s visibility layer. + +
+ + + + + +`void` **show**\ (\ ) [🔗](#class_CanvasItem_method_show) + +Show the **CanvasItem** if it's currently hidden. This is equivalent to setting [visible](class_canvasitem.md#class_CanvasItem_property_visible) to ``true``. + +\ **Note:** For controls that inherit [Popup](class_popup.md), the correct way to make them visible is to call one of the multiple ``popup*()`` functions instead. + diff --git a/docs/Classes/class_canvasitemmaterial.md b/docs/Classes/class_canvasitemmaterial.md new file mode 100644 index 00000000..88a13e89 --- /dev/null +++ b/docs/Classes/class_canvasitemmaterial.md @@ -0,0 +1,232 @@ + + + + + + + + + +# CanvasItemMaterial + +**Inherits:** [Material](class_material.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +A material for [CanvasItem](class_canvasitem.md)\ s. + + + +## Description + +**CanvasItemMaterial**\ s provide a means of modifying the textures associated with a CanvasItem. They specialize in describing blend and lighting behaviors for textures. Use a [ShaderMaterial](class_shadermaterial.md) to more fully customize a material's interactions with a [CanvasItem](class_canvasitem.md). + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[BlendMode](class_canvasitemmaterial.md#enum_CanvasItemMaterial_BlendMode)[blend_mode](#class_CanvasItemMaterial_property_blend_mode)`0`
[LightMode](class_canvasitemmaterial.md#enum_CanvasItemMaterial_LightMode)[light_mode](#class_CanvasItemMaterial_property_light_mode)`0`
[int](class_int.md)[particles_anim_h_frames](#class_CanvasItemMaterial_property_particles_anim_h_frames)
[bool](class_bool.md)[particles_anim_loop](#class_CanvasItemMaterial_property_particles_anim_loop)
[int](class_int.md)[particles_anim_v_frames](#class_CanvasItemMaterial_property_particles_anim_v_frames)
[bool](class_bool.md)[particles_animation](#class_CanvasItemMaterial_property_particles_animation)`false`
+ +
+ + + +## Enumerations + + + + + +enum **BlendMode**: [🔗](#enum_CanvasItemMaterial_BlendMode) + + + + + +[BlendMode](class_canvasitemmaterial.md#enum_CanvasItemMaterial_BlendMode) **BLEND_MODE_MIX** = `0` + +Mix blending mode. Colors are assumed to be independent of the alpha (opacity) value. + + + +[BlendMode](class_canvasitemmaterial.md#enum_CanvasItemMaterial_BlendMode) **BLEND_MODE_ADD** = `1` + +Additive blending mode. + + + +[BlendMode](class_canvasitemmaterial.md#enum_CanvasItemMaterial_BlendMode) **BLEND_MODE_SUB** = `2` + +Subtractive blending mode. + + + +[BlendMode](class_canvasitemmaterial.md#enum_CanvasItemMaterial_BlendMode) **BLEND_MODE_MUL** = `3` + +Multiplicative blending mode. + + + +[BlendMode](class_canvasitemmaterial.md#enum_CanvasItemMaterial_BlendMode) **BLEND_MODE_PREMULT_ALPHA** = `4` + +Mix blending mode. Colors are assumed to be premultiplied by the alpha (opacity) value.
+ + + + + +enum **LightMode**: [🔗](#enum_CanvasItemMaterial_LightMode) + + + + + +[LightMode](class_canvasitemmaterial.md#enum_CanvasItemMaterial_LightMode) **LIGHT_MODE_NORMAL** = `0` + +Render the material using both light and non-light sensitive material properties. + + + +[LightMode](class_canvasitemmaterial.md#enum_CanvasItemMaterial_LightMode) **LIGHT_MODE_UNSHADED** = `1` + +Render the material as if there were no light. + + + +[LightMode](class_canvasitemmaterial.md#enum_CanvasItemMaterial_LightMode) **LIGHT_MODE_LIGHT_ONLY** = `2` + +Render the material as if there were only light.
+ + + +## Property Descriptions + + + + + +[BlendMode](class_canvasitemmaterial.md#enum_CanvasItemMaterial_BlendMode) **blend_mode** = `0` [🔗](#class_CanvasItemMaterial_property_blend_mode) + + + +- `void` **set_blend_mode**\ (\ value\: [BlendMode](class_canvasitemmaterial.md#enum_CanvasItemMaterial_BlendMode)\ ) +- [BlendMode](class_canvasitemmaterial.md#enum_CanvasItemMaterial_BlendMode) **get_blend_mode**\ (\ ) + +The manner in which a material's rendering is applied to underlying textures. + +
+ + + + + +[LightMode](class_canvasitemmaterial.md#enum_CanvasItemMaterial_LightMode) **light_mode** = `0` [🔗](#class_CanvasItemMaterial_property_light_mode) + + + +- `void` **set_light_mode**\ (\ value\: [LightMode](class_canvasitemmaterial.md#enum_CanvasItemMaterial_LightMode)\ ) +- [LightMode](class_canvasitemmaterial.md#enum_CanvasItemMaterial_LightMode) **get_light_mode**\ (\ ) + +The manner in which material reacts to lighting. + +
+ + + + + +[int](class_int.md) **particles_anim_h_frames** [🔗](#class_CanvasItemMaterial_property_particles_anim_h_frames) + + + +- `void` **set_particles_anim_h_frames**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_particles_anim_h_frames**\ (\ ) + +The number of columns in the spritesheet assigned as [Texture2D](class_texture2d.md) for a [GPUParticles2D](class_gpuparticles2d.md) or [CPUParticles2D](class_cpuparticles2d.md). + +\ **Note:** This property is only used and visible in the editor if [particles_animation](class_canvasitemmaterial.md#class_CanvasItemMaterial_property_particles_animation) is ``true``. + +
+ + + + + +[bool](class_bool.md) **particles_anim_loop** [🔗](#class_CanvasItemMaterial_property_particles_anim_loop) + + + +- `void` **set_particles_anim_loop**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_particles_anim_loop**\ (\ ) + +If ``true``, the particles animation will loop. + +\ **Note:** This property is only used and visible in the editor if [particles_animation](class_canvasitemmaterial.md#class_CanvasItemMaterial_property_particles_animation) is ``true``. + +
+ + + + + +[int](class_int.md) **particles_anim_v_frames** [🔗](#class_CanvasItemMaterial_property_particles_anim_v_frames) + + + +- `void` **set_particles_anim_v_frames**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_particles_anim_v_frames**\ (\ ) + +The number of rows in the spritesheet assigned as [Texture2D](class_texture2d.md) for a [GPUParticles2D](class_gpuparticles2d.md) or [CPUParticles2D](class_cpuparticles2d.md). + +\ **Note:** This property is only used and visible in the editor if [particles_animation](class_canvasitemmaterial.md#class_CanvasItemMaterial_property_particles_animation) is ``true``. + +
+ + + + + +[bool](class_bool.md) **particles_animation** = `false` [🔗](#class_CanvasItemMaterial_property_particles_animation) + + + +- `void` **set_particles_animation**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_particles_animation**\ (\ ) + +If ``true``, enable spritesheet-based animation features when assigned to [GPUParticles2D](class_gpuparticles2d.md) and [CPUParticles2D](class_cpuparticles2d.md) nodes. The [ParticleProcessMaterial.anim_speed_max](class_particleprocessmaterial.md#class_ParticleProcessMaterial_property_anim_speed_max) or [CPUParticles2D.anim_speed_max](class_cpuparticles2d.md#class_CPUParticles2D_property_anim_speed_max) should also be set to a positive value for the animation to play. + +This property (and other ``particles_anim_*`` properties that depend on it) has no effect on other types of nodes. + diff --git a/docs/Classes/class_canvaslayer.md b/docs/Classes/class_canvaslayer.md new file mode 100644 index 00000000..04d1f948 --- /dev/null +++ b/docs/Classes/class_canvaslayer.md @@ -0,0 +1,327 @@ + + + + + + + + + +# CanvasLayer + +**Inherits:** [Node](class_node.md) **<** [Object](class_object.md) + +**Inherited By:** [ParallaxBackground](class_parallaxbackground.md) + +A node used for independent rendering of objects within a 2D scene. + + + +## Description + +[CanvasItem](class_canvasitem.md)-derived nodes that are direct or indirect children of a **CanvasLayer** will be drawn in that layer. The layer is a numeric index that defines the draw order. The default 2D scene renders with index ``0``, so a **CanvasLayer** with index ``-1`` will be drawn below, and a **CanvasLayer** with index ``1`` will be drawn above. This order will hold regardless of the [CanvasItem.z_index](class_canvasitem.md#class_CanvasItem_property_z_index) of the nodes within each layer. + +\ **CanvasLayer**\ s can be hidden and they can also optionally follow the viewport. This makes them useful for HUDs like health bar overlays (on layers ``1`` and higher) or backgrounds (on layers ``-1`` and lower). + +\ **Note:** Embedded [Window](class_window.md)\ s are placed on layer ``1024``. [CanvasItem](class_canvasitem.md)\ s on layers ``1025`` and higher appear in front of embedded windows. + +\ **Note:** Each **CanvasLayer** is drawn on one specific [Viewport](class_viewport.md) and cannot be shared between multiple [Viewport](class_viewport.md)\ s, see [custom_viewport](class_canvaslayer.md#class_CanvasLayer_property_custom_viewport). When using multiple [Viewport](class_viewport.md)\ s, for example in a split-screen game, you need to create an individual **CanvasLayer** for each [Viewport](class_viewport.md) you want it to be drawn on. + + + +## Tutorials + +- [Viewport and canvas transforms](../tutorials/2d/2d_transforms.md) + +- [Canvas layers](../tutorials/2d/canvas_layers.md) + +- [2D Dodge The Creeps Demo](https://godotengine.org/asset-library/asset/2712) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Node](class_node.md)[custom_viewport](#class_CanvasLayer_property_custom_viewport)
[bool](class_bool.md)[follow_viewport_enabled](#class_CanvasLayer_property_follow_viewport_enabled)`false`
[float](class_float.md)[follow_viewport_scale](#class_CanvasLayer_property_follow_viewport_scale)`1.0`
[int](class_int.md)[layer](#class_CanvasLayer_property_layer)`1`
[Vector2](class_vector2.md)[offset](#class_CanvasLayer_property_offset)`Vector2(0, 0)`
[float](class_float.md)[rotation](#class_CanvasLayer_property_rotation)`0.0`
[Vector2](class_vector2.md)[scale](#class_CanvasLayer_property_scale)`Vector2(1, 1)`
[Transform2D](class_transform2d.md)[transform](#class_CanvasLayer_property_transform)`Transform2D(1, 0, 0, 1, 0, 0)`
[bool](class_bool.md)[visible](#class_CanvasLayer_property_visible)`true`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + +
[RID](class_rid.md)[get_canvas](#class_CanvasLayer_method_get_canvas)\ (\ ) const
[Transform2D](class_transform2d.md)[get_final_transform](#class_CanvasLayer_method_get_final_transform)\ (\ ) const
`void`[hide](#class_CanvasLayer_method_hide)\ (\ )
`void`[show](#class_CanvasLayer_method_show)\ (\ )
+ +
+ + + +## Signals + + + + + +**visibility_changed**\ (\ ) [🔗](#class_CanvasLayer_signal_visibility_changed) + +Emitted when visibility of the layer is changed. See [visible](class_canvaslayer.md#class_CanvasLayer_property_visible). + +
+ + + +## Property Descriptions + + + + + +[Node](class_node.md) **custom_viewport** [🔗](#class_CanvasLayer_property_custom_viewport) + + + +- `void` **set_custom_viewport**\ (\ value\: [Node](class_node.md)\ ) +- [Node](class_node.md) **get_custom_viewport**\ (\ ) + +The custom [Viewport](class_viewport.md) node assigned to the **CanvasLayer**. If ``null``, uses the default viewport instead. + +
+ + + + + +[bool](class_bool.md) **follow_viewport_enabled** = `false` [🔗](#class_CanvasLayer_property_follow_viewport_enabled) + + + +- `void` **set_follow_viewport**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_following_viewport**\ (\ ) + +If enabled, the **CanvasLayer** maintains its position in world space. If disabled, the **CanvasLayer** stays in a fixed position on the screen. + +Together with [follow_viewport_scale](class_canvaslayer.md#class_CanvasLayer_property_follow_viewport_scale), this can be used for a pseudo-3D effect. + +
+ + + + + +[float](class_float.md) **follow_viewport_scale** = `1.0` [🔗](#class_CanvasLayer_property_follow_viewport_scale) + + + +- `void` **set_follow_viewport_scale**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_follow_viewport_scale**\ (\ ) + +Scales the layer when using [follow_viewport_enabled](class_canvaslayer.md#class_CanvasLayer_property_follow_viewport_enabled). Layers moving into the foreground should have increasing scales, while layers moving into the background should have decreasing scales. + +
+ + + + + +[int](class_int.md) **layer** = `1` [🔗](#class_CanvasLayer_property_layer) + + + +- `void` **set_layer**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_layer**\ (\ ) + +Layer index for draw order. Lower values are drawn behind higher values. + +\ **Note:** If multiple CanvasLayers have the same layer index, [CanvasItem](class_canvasitem.md) children of one CanvasLayer are drawn behind the [CanvasItem](class_canvasitem.md) children of the other CanvasLayer. Which CanvasLayer is drawn in front is non-deterministic. + +\ **Note:** The layer index should be between [RenderingServer.CANVAS_LAYER_MIN](class_renderingserver.md#class_RenderingServer_constant_CANVAS_LAYER_MIN) and [RenderingServer.CANVAS_LAYER_MAX](class_renderingserver.md#class_RenderingServer_constant_CANVAS_LAYER_MAX) (inclusive). Any other value will wrap around. + +
+ + + + + +[Vector2](class_vector2.md) **offset** = `Vector2(0, 0)` [🔗](#class_CanvasLayer_property_offset) + + + +- `void` **set_offset**\ (\ value\: [Vector2](class_vector2.md)\ ) +- [Vector2](class_vector2.md) **get_offset**\ (\ ) + +The layer's base offset. + +
+ + + + + +[float](class_float.md) **rotation** = `0.0` [🔗](#class_CanvasLayer_property_rotation) + + + +- `void` **set_rotation**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_rotation**\ (\ ) + +The layer's rotation in radians. + +
+ + + + + +[Vector2](class_vector2.md) **scale** = `Vector2(1, 1)` [🔗](#class_CanvasLayer_property_scale) + + + +- `void` **set_scale**\ (\ value\: [Vector2](class_vector2.md)\ ) +- [Vector2](class_vector2.md) **get_scale**\ (\ ) + +The layer's scale. + +
+ + + + + +[Transform2D](class_transform2d.md) **transform** = `Transform2D(1, 0, 0, 1, 0, 0)` [🔗](#class_CanvasLayer_property_transform) + + + +- `void` **set_transform**\ (\ value\: [Transform2D](class_transform2d.md)\ ) +- [Transform2D](class_transform2d.md) **get_transform**\ (\ ) + +The layer's transform. + +
+ + + + + +[bool](class_bool.md) **visible** = `true` [🔗](#class_CanvasLayer_property_visible) + + + +- `void` **set_visible**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_visible**\ (\ ) + +If ``false``, any [CanvasItem](class_canvasitem.md) under this **CanvasLayer** will be hidden. + +Unlike [CanvasItem.visible](class_canvasitem.md#class_CanvasItem_property_visible), visibility of a **CanvasLayer** isn't propagated to underlying layers. + +
+ + + +## Method Descriptions + + + + + +[RID](class_rid.md) **get_canvas**\ (\ ) const [🔗](#class_CanvasLayer_method_get_canvas) + +Returns the RID of the canvas used by this layer. + +
+ + + + + +[Transform2D](class_transform2d.md) **get_final_transform**\ (\ ) const [🔗](#class_CanvasLayer_method_get_final_transform) + +Returns the transform from the **CanvasLayer**\ s coordinate system to the [Viewport](class_viewport.md)\ s coordinate system. + +
+ + + + + +`void` **hide**\ (\ ) [🔗](#class_CanvasLayer_method_hide) + +Hides any [CanvasItem](class_canvasitem.md) under this **CanvasLayer**. This is equivalent to setting [visible](class_canvaslayer.md#class_CanvasLayer_property_visible) to ``false``. + +
+ + + + + +`void` **show**\ (\ ) [🔗](#class_CanvasLayer_method_show) + +Shows any [CanvasItem](class_canvasitem.md) under this **CanvasLayer**. This is equivalent to setting [visible](class_canvaslayer.md#class_CanvasLayer_property_visible) to ``true``. + diff --git a/docs/Classes/class_canvasmodulate.md b/docs/Classes/class_canvasmodulate.md new file mode 100644 index 00000000..fe8cdcd6 --- /dev/null +++ b/docs/Classes/class_canvasmodulate.md @@ -0,0 +1,64 @@ + + + + + + + + + + + +# CanvasModulate + +**Inherits:** [Node2D](class_node2d.md) **<** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +A node that applies a color tint to a canvas. + + + +## Description + +**CanvasModulate** applies a color tint to all nodes on a canvas. Only one can be used to tint a canvas, but [CanvasLayer](class_canvaslayer.md)\ s can be used to render things independently. + + + +## Tutorials + +- [2D lights and shadows](../tutorials/2d/2d_lights_and_shadows.md) + + + +## Properties + + + + + + + + + + + +
[Color](class_color.md)[color](#class_CanvasModulate_property_color)`Color(1, 1, 1, 1)`
+ +
+ + + +## Property Descriptions + + + + + +[Color](class_color.md) **color** = `Color(1, 1, 1, 1)` [🔗](#class_CanvasModulate_property_color) + + + +- `void` **set_color**\ (\ value\: [Color](class_color.md)\ ) +- [Color](class_color.md) **get_color**\ (\ ) + +The tint color to apply. + diff --git a/docs/Classes/class_canvastexture.md b/docs/Classes/class_canvastexture.md new file mode 100644 index 00000000..3d275c3f --- /dev/null +++ b/docs/Classes/class_canvastexture.md @@ -0,0 +1,191 @@ + + + + + + + + + +# CanvasTexture + +**Inherits:** [Texture2D](class_texture2d.md) **<** [Texture](class_texture.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Texture with optional normal and specular maps for use in 2D rendering. + + + +## Description + +**CanvasTexture** is an alternative to [ImageTexture](class_imagetexture.md) for 2D rendering. It allows using normal maps and specular maps in any node that inherits from [CanvasItem](class_canvasitem.md). **CanvasTexture** also allows overriding the texture's filter and repeat mode independently of the node's properties (or the project settings). + +\ **Note:** **CanvasTexture** cannot be used in 3D. It will not display correctly when applied to any [VisualInstance3D](class_visualinstance3d.md), such as [Sprite3D](class_sprite3d.md) or [Decal](class_decal.md). For physically-based materials in 3D, use [BaseMaterial3D](class_basematerial3d.md) instead. + + + +## Tutorials + +- [2D Lights and Shadows](../tutorials/2d/2d_lights_and_shadows.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Texture2D](class_texture2d.md)[diffuse_texture](#class_CanvasTexture_property_diffuse_texture)
[Texture2D](class_texture2d.md)[normal_texture](#class_CanvasTexture_property_normal_texture)
[bool](class_bool.md)resource_local_to_scene`false` (overrides [Resource.resource_local_to_scene](class_resource.md#class_Resource_property_resource_local_to_scene))
[Color](class_color.md)[specular_color](#class_CanvasTexture_property_specular_color)`Color(1, 1, 1, 1)`
[float](class_float.md)[specular_shininess](#class_CanvasTexture_property_specular_shininess)`1.0`
[Texture2D](class_texture2d.md)[specular_texture](#class_CanvasTexture_property_specular_texture)
[TextureFilter](class_canvasitem.md#enum_CanvasItem_TextureFilter)[texture_filter](#class_CanvasTexture_property_texture_filter)`0`
[TextureRepeat](class_canvasitem.md#enum_CanvasItem_TextureRepeat)[texture_repeat](#class_CanvasTexture_property_texture_repeat)`0`
+ +
+ + + +## Property Descriptions + + + + + +[Texture2D](class_texture2d.md) **diffuse_texture** [🔗](#class_CanvasTexture_property_diffuse_texture) + + + +- `void` **set_diffuse_texture**\ (\ value\: [Texture2D](class_texture2d.md)\ ) +- [Texture2D](class_texture2d.md) **get_diffuse_texture**\ (\ ) + +The diffuse (color) texture to use. This is the main texture you want to set in most cases. + +
+ + + + + +[Texture2D](class_texture2d.md) **normal_texture** [🔗](#class_CanvasTexture_property_normal_texture) + + + +- `void` **set_normal_texture**\ (\ value\: [Texture2D](class_texture2d.md)\ ) +- [Texture2D](class_texture2d.md) **get_normal_texture**\ (\ ) + +The normal map texture to use. Only has a visible effect if [Light2D](class_light2d.md)\ s are affecting this **CanvasTexture**. + +\ **Note:** Redot expects the normal map to use X+, Y+, and Z+ coordinates. See [this page](http://wiki.polycount.com/wiki/Normal_Map_Technical_Details#Common_Swizzle_Coordinates) for a comparison of normal map coordinates expected by popular engines. + +
+ + + + + +[Color](class_color.md) **specular_color** = `Color(1, 1, 1, 1)` [🔗](#class_CanvasTexture_property_specular_color) + + + +- `void` **set_specular_color**\ (\ value\: [Color](class_color.md)\ ) +- [Color](class_color.md) **get_specular_color**\ (\ ) + +The multiplier for specular reflection colors. The [Light2D](class_light2d.md)'s color is also taken into account when determining the reflection color. Only has a visible effect if [Light2D](class_light2d.md)\ s are affecting this **CanvasTexture**. + +
+ + + + + +[float](class_float.md) **specular_shininess** = `1.0` [🔗](#class_CanvasTexture_property_specular_shininess) + + + +- `void` **set_specular_shininess**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_specular_shininess**\ (\ ) + +The specular exponent for [Light2D](class_light2d.md) specular reflections. Higher values result in a more glossy/"wet" look, with reflections becoming more localized and less visible overall. The default value of ``1.0`` disables specular reflections entirely. Only has a visible effect if [Light2D](class_light2d.md)\ s are affecting this **CanvasTexture**. + +
+ + + + + +[Texture2D](class_texture2d.md) **specular_texture** [🔗](#class_CanvasTexture_property_specular_texture) + + + +- `void` **set_specular_texture**\ (\ value\: [Texture2D](class_texture2d.md)\ ) +- [Texture2D](class_texture2d.md) **get_specular_texture**\ (\ ) + +The specular map to use for [Light2D](class_light2d.md) specular reflections. This should be a grayscale or colored texture, with brighter areas resulting in a higher [specular_shininess](class_canvastexture.md#class_CanvasTexture_property_specular_shininess) value. Using a colored [specular_texture](class_canvastexture.md#class_CanvasTexture_property_specular_texture) allows controlling specular shininess on a per-channel basis. Only has a visible effect if [Light2D](class_light2d.md)\ s are affecting this **CanvasTexture**. + +
+ + + + + +[TextureFilter](class_canvasitem.md#enum_CanvasItem_TextureFilter) **texture_filter** = `0` [🔗](#class_CanvasTexture_property_texture_filter) + + + +- `void` **set_texture_filter**\ (\ value\: [TextureFilter](class_canvasitem.md#enum_CanvasItem_TextureFilter)\ ) +- [TextureFilter](class_canvasitem.md#enum_CanvasItem_TextureFilter) **get_texture_filter**\ (\ ) + +The texture filtering mode to use when drawing this **CanvasTexture**. + +
+ + + + + +[TextureRepeat](class_canvasitem.md#enum_CanvasItem_TextureRepeat) **texture_repeat** = `0` [🔗](#class_CanvasTexture_property_texture_repeat) + + + +- `void` **set_texture_repeat**\ (\ value\: [TextureRepeat](class_canvasitem.md#enum_CanvasItem_TextureRepeat)\ ) +- [TextureRepeat](class_canvasitem.md#enum_CanvasItem_TextureRepeat) **get_texture_repeat**\ (\ ) + +The texture repeat mode to use when drawing this **CanvasTexture**. + diff --git a/docs/Classes/class_capsulemesh.md b/docs/Classes/class_capsulemesh.md new file mode 100644 index 00000000..15697e47 --- /dev/null +++ b/docs/Classes/class_capsulemesh.md @@ -0,0 +1,120 @@ + + + + + + + + + +# CapsuleMesh + +**Inherits:** [PrimitiveMesh](class_primitivemesh.md) **<** [Mesh](class_mesh.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Class representing a capsule-shaped [PrimitiveMesh](class_primitivemesh.md). + + + +## Description + +Class representing a capsule-shaped [PrimitiveMesh](class_primitivemesh.md). + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[height](#class_CapsuleMesh_property_height)`2.0`
[int](class_int.md)[radial_segments](#class_CapsuleMesh_property_radial_segments)`64`
[float](class_float.md)[radius](#class_CapsuleMesh_property_radius)`0.5`
[int](class_int.md)[rings](#class_CapsuleMesh_property_rings)`8`
+ +
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **height** = `2.0` [🔗](#class_CapsuleMesh_property_height) + + + +- `void` **set_height**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_height**\ (\ ) + +Total height of the capsule mesh (including the hemispherical ends). + +\ **Note:** The [height](class_capsulemesh.md#class_CapsuleMesh_property_height) of a capsule must be at least twice its [radius](class_capsulemesh.md#class_CapsuleMesh_property_radius). Otherwise, the capsule becomes a circle. If the [height](class_capsulemesh.md#class_CapsuleMesh_property_height) is less than twice the [radius](class_capsulemesh.md#class_CapsuleMesh_property_radius), the properties adjust to a valid value. + +
+ + + + + +[int](class_int.md) **radial_segments** = `64` [🔗](#class_CapsuleMesh_property_radial_segments) + + + +- `void` **set_radial_segments**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_radial_segments**\ (\ ) + +Number of radial segments on the capsule mesh. + +
+ + + + + +[float](class_float.md) **radius** = `0.5` [🔗](#class_CapsuleMesh_property_radius) + + + +- `void` **set_radius**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_radius**\ (\ ) + +Radius of the capsule mesh. + +\ **Note:** The [radius](class_capsulemesh.md#class_CapsuleMesh_property_radius) of a capsule cannot be greater than half of its [height](class_capsulemesh.md#class_CapsuleMesh_property_height). Otherwise, the capsule becomes a circle. If the [radius](class_capsulemesh.md#class_CapsuleMesh_property_radius) is greater than half of the [height](class_capsulemesh.md#class_CapsuleMesh_property_height), the properties adjust to a valid value. + +
+ + + + + +[int](class_int.md) **rings** = `8` [🔗](#class_CapsuleMesh_property_rings) + + + +- `void` **set_rings**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_rings**\ (\ ) + +Number of rings along the height of the capsule. + diff --git a/docs/Classes/class_capsuleshape2d.md b/docs/Classes/class_capsuleshape2d.md new file mode 100644 index 00000000..c2eac209 --- /dev/null +++ b/docs/Classes/class_capsuleshape2d.md @@ -0,0 +1,102 @@ + + + + + + + + + +# CapsuleShape2D + +**Inherits:** [Shape2D](class_shape2d.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +A 2D capsule shape used for physics collision. + + + +## Description + +A 2D capsule shape, intended for use in physics. Usually used to provide a shape for a [CollisionShape2D](class_collisionshape2d.md). + +\ **Performance:** **CapsuleShape2D** is fast to check collisions against, but it is slower than [RectangleShape2D](class_rectangleshape2d.md) and [CircleShape2D](class_circleshape2d.md). + + + +## Properties + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[height](#class_CapsuleShape2D_property_height)`30.0`
[float](class_float.md)[mid_height](#class_CapsuleShape2D_property_mid_height)
[float](class_float.md)[radius](#class_CapsuleShape2D_property_radius)`10.0`
+ +
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **height** = `30.0` [🔗](#class_CapsuleShape2D_property_height) + + + +- `void` **set_height**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_height**\ (\ ) + +The capsule's full height, including the semicircles. + +\ **Note:** The [height](class_capsuleshape2d.md#class_CapsuleShape2D_property_height) of a capsule must be at least twice its [radius](class_capsuleshape2d.md#class_CapsuleShape2D_property_radius). Otherwise, the capsule becomes a circle. If the [height](class_capsuleshape2d.md#class_CapsuleShape2D_property_height) is less than twice the [radius](class_capsuleshape2d.md#class_CapsuleShape2D_property_radius), the properties adjust to a valid value. + +
+ + + + + +[float](class_float.md) **mid_height** [🔗](#class_CapsuleShape2D_property_mid_height) + + + +- `void` **set_mid_height**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_mid_height**\ (\ ) + +The capsule's height, excluding the semicircles. This is the height of the central rectangular part in the middle of the capsule, and is the distance between the centers of the two semicircles. This is a wrapper for [height](class_capsuleshape2d.md#class_CapsuleShape2D_property_height). + +
+ + + + + +[float](class_float.md) **radius** = `10.0` [🔗](#class_CapsuleShape2D_property_radius) + + + +- `void` **set_radius**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_radius**\ (\ ) + +The capsule's radius. + +\ **Note:** The [radius](class_capsuleshape2d.md#class_CapsuleShape2D_property_radius) of a capsule cannot be greater than half of its [height](class_capsuleshape2d.md#class_CapsuleShape2D_property_height). Otherwise, the capsule becomes a circle. If the [radius](class_capsuleshape2d.md#class_CapsuleShape2D_property_radius) is greater than half of the [height](class_capsuleshape2d.md#class_CapsuleShape2D_property_height), the properties adjust to a valid value. + diff --git a/docs/Classes/class_capsuleshape3d.md b/docs/Classes/class_capsuleshape3d.md new file mode 100644 index 00000000..237860aa --- /dev/null +++ b/docs/Classes/class_capsuleshape3d.md @@ -0,0 +1,108 @@ + + + + + + + + + +# CapsuleShape3D + +**Inherits:** [Shape3D](class_shape3d.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +A 3D capsule shape used for physics collision. + + + +## Description + +A 3D capsule shape, intended for use in physics. Usually used to provide a shape for a [CollisionShape3D](class_collisionshape3d.md). + +\ **Performance:** **CapsuleShape3D** is fast to check collisions against. It is faster than [CylinderShape3D](class_cylindershape3d.md), but slower than [SphereShape3D](class_sphereshape3d.md) and [BoxShape3D](class_boxshape3d.md). + + + +## Tutorials + +- [3D Physics Tests Demo](https://godotengine.org/asset-library/asset/2747) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[height](#class_CapsuleShape3D_property_height)`2.0`
[float](class_float.md)[mid_height](#class_CapsuleShape3D_property_mid_height)
[float](class_float.md)[radius](#class_CapsuleShape3D_property_radius)`0.5`
+ +
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **height** = `2.0` [🔗](#class_CapsuleShape3D_property_height) + + + +- `void` **set_height**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_height**\ (\ ) + +The capsule's full height, including the hemispheres. + +\ **Note:** The [height](class_capsuleshape3d.md#class_CapsuleShape3D_property_height) of a capsule must be at least twice its [radius](class_capsuleshape3d.md#class_CapsuleShape3D_property_radius). Otherwise, the capsule becomes a sphere. If the [height](class_capsuleshape3d.md#class_CapsuleShape3D_property_height) is less than twice the [radius](class_capsuleshape3d.md#class_CapsuleShape3D_property_radius), the properties adjust to a valid value. + +
+ + + + + +[float](class_float.md) **mid_height** [🔗](#class_CapsuleShape3D_property_mid_height) + + + +- `void` **set_mid_height**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_mid_height**\ (\ ) + +The capsule's height, excluding the hemispheres. This is the height of the central cylindrical part in the middle of the capsule, and is the distance between the centers of the two hemispheres. This is a wrapper for [height](class_capsuleshape3d.md#class_CapsuleShape3D_property_height). + +
+ + + + + +[float](class_float.md) **radius** = `0.5` [🔗](#class_CapsuleShape3D_property_radius) + + + +- `void` **set_radius**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_radius**\ (\ ) + +The capsule's radius. + +\ **Note:** The [radius](class_capsuleshape3d.md#class_CapsuleShape3D_property_radius) of a capsule cannot be greater than half of its [height](class_capsuleshape3d.md#class_CapsuleShape3D_property_height). Otherwise, the capsule becomes a sphere. If the [radius](class_capsuleshape3d.md#class_CapsuleShape3D_property_radius) is greater than half of the [height](class_capsuleshape3d.md#class_CapsuleShape3D_property_height), the properties adjust to a valid value. + diff --git a/docs/Classes/class_centercontainer.md b/docs/Classes/class_centercontainer.md new file mode 100644 index 00000000..3994172f --- /dev/null +++ b/docs/Classes/class_centercontainer.md @@ -0,0 +1,62 @@ + + + + + + + + + +# CenterContainer + +**Inherits:** [Container](class_container.md) **<** [Control](class_control.md) **<** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +A container that keeps child controls in its center. + + + +## Description + +**CenterContainer** is a container that keeps all of its child controls in its center at their minimum size. + + + +## Tutorials + +- [Using Containers](../tutorials/ui/gui_containers.md) + + + +## Properties + + + + + + + + + + + +
[bool](class_bool.md)[use_top_left](#class_CenterContainer_property_use_top_left)`false`
+ +
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **use_top_left** = `false` [🔗](#class_CenterContainer_property_use_top_left) + + + +- `void` **set_use_top_left**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_using_top_left**\ (\ ) + +If ``true``, centers children relative to the **CenterContainer**'s top left corner. + diff --git a/docs/Classes/class_characterbody2d.md b/docs/Classes/class_characterbody2d.md new file mode 100644 index 00000000..eb73bfb4 --- /dev/null +++ b/docs/Classes/class_characterbody2d.md @@ -0,0 +1,720 @@ + + + + + + + + + +# CharacterBody2D + +**Inherits:** [PhysicsBody2D](class_physicsbody2d.md) **<** [CollisionObject2D](class_collisionobject2d.md) **<** [Node2D](class_node2d.md) **<** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +A 2D physics body specialized for characters moved by script. + + + +## Description + +**CharacterBody2D** is a specialized class for physics bodies that are meant to be user-controlled. They are not affected by physics at all, but they affect other physics bodies in their path. They are mainly used to provide high-level API to move objects with wall and slope detection ([move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide) method) in addition to the general collision detection provided by [PhysicsBody2D.move_and_collide()](class_physicsbody2d.md#class_PhysicsBody2D_method_move_and_collide). This makes it useful for highly configurable physics bodies that must move in specific ways and collide with the world, as is often the case with user-controlled characters. + +For game objects that don't require complex movement or collision detection, such as moving platforms, [AnimatableBody2D](class_animatablebody2d.md) is simpler to configure. + + + +## Tutorials + +- [Physics introduction](../tutorials/physics/physics_introduction.md) + +- [Troubleshooting physics issues](../tutorials/physics/troubleshooting_physics_issues.md) + +- [Kinematic character (2D)](../tutorials/physics/kinematic_character_2d.md) + +- [Using CharacterBody2D](../tutorials/physics/using_character_body_2d.md) + +- [2D Kinematic Character Demo](https://godotengine.org/asset-library/asset/2719) + +- [2D Platformer Demo](https://godotengine.org/asset-library/asset/2727) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[floor_block_on_wall](#class_CharacterBody2D_property_floor_block_on_wall)`true`
[bool](class_bool.md)[floor_constant_speed](#class_CharacterBody2D_property_floor_constant_speed)`false`
[float](class_float.md)[floor_max_angle](#class_CharacterBody2D_property_floor_max_angle)`0.7853982`
[float](class_float.md)[floor_snap_length](#class_CharacterBody2D_property_floor_snap_length)`1.0`
[bool](class_bool.md)[floor_stop_on_slope](#class_CharacterBody2D_property_floor_stop_on_slope)`true`
[int](class_int.md)[max_slides](#class_CharacterBody2D_property_max_slides)`4`
[MotionMode](class_characterbody2d.md#enum_CharacterBody2D_MotionMode)[motion_mode](#class_CharacterBody2D_property_motion_mode)`0`
[int](class_int.md)[platform_floor_layers](#class_CharacterBody2D_property_platform_floor_layers)`4294967295`
[PlatformOnLeave](class_characterbody2d.md#enum_CharacterBody2D_PlatformOnLeave)[platform_on_leave](#class_CharacterBody2D_property_platform_on_leave)`0`
[int](class_int.md)[platform_wall_layers](#class_CharacterBody2D_property_platform_wall_layers)`0`
[float](class_float.md)[safe_margin](#class_CharacterBody2D_property_safe_margin)`0.08`
[bool](class_bool.md)[slide_on_ceiling](#class_CharacterBody2D_property_slide_on_ceiling)`true`
[Vector2](class_vector2.md)[up_direction](#class_CharacterBody2D_property_up_direction)`Vector2(0, -1)`
[Vector2](class_vector2.md)[velocity](#class_CharacterBody2D_property_velocity)`Vector2(0, 0)`
[float](class_float.md)[wall_min_slide_angle](#class_CharacterBody2D_property_wall_min_slide_angle)`0.2617994`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
`void`[apply_floor_snap](#class_CharacterBody2D_method_apply_floor_snap)\ (\ )
[float](class_float.md)[get_floor_angle](#class_CharacterBody2D_method_get_floor_angle)\ (\ up_direction\: [Vector2](class_vector2.md) = Vector2(0, -1)\ ) const
[Vector2](class_vector2.md)[get_floor_normal](#class_CharacterBody2D_method_get_floor_normal)\ (\ ) const
[Vector2](class_vector2.md)[get_last_motion](#class_CharacterBody2D_method_get_last_motion)\ (\ ) const
[KinematicCollision2D](class_kinematiccollision2d.md)[get_last_slide_collision](#class_CharacterBody2D_method_get_last_slide_collision)\ (\ )
[Vector2](class_vector2.md)[get_platform_velocity](#class_CharacterBody2D_method_get_platform_velocity)\ (\ ) const
[Vector2](class_vector2.md)[get_position_delta](#class_CharacterBody2D_method_get_position_delta)\ (\ ) const
[Vector2](class_vector2.md)[get_real_velocity](#class_CharacterBody2D_method_get_real_velocity)\ (\ ) const
[KinematicCollision2D](class_kinematiccollision2d.md)[get_slide_collision](#class_CharacterBody2D_method_get_slide_collision)\ (\ slide_idx\: [int](class_int.md)\ )
[int](class_int.md)[get_slide_collision_count](#class_CharacterBody2D_method_get_slide_collision_count)\ (\ ) const
[Vector2](class_vector2.md)[get_wall_normal](#class_CharacterBody2D_method_get_wall_normal)\ (\ ) const
[bool](class_bool.md)[is_on_ceiling](#class_CharacterBody2D_method_is_on_ceiling)\ (\ ) const
[bool](class_bool.md)[is_on_ceiling_only](#class_CharacterBody2D_method_is_on_ceiling_only)\ (\ ) const
[bool](class_bool.md)[is_on_floor](#class_CharacterBody2D_method_is_on_floor)\ (\ ) const
[bool](class_bool.md)[is_on_floor_only](#class_CharacterBody2D_method_is_on_floor_only)\ (\ ) const
[bool](class_bool.md)[is_on_wall](#class_CharacterBody2D_method_is_on_wall)\ (\ ) const
[bool](class_bool.md)[is_on_wall_only](#class_CharacterBody2D_method_is_on_wall_only)\ (\ ) const
[bool](class_bool.md)[move_and_slide](#class_CharacterBody2D_method_move_and_slide)\ (\ )
+ +
+ + + +## Enumerations + + + + + +enum **MotionMode**: [🔗](#enum_CharacterBody2D_MotionMode) + + + + + +[MotionMode](class_characterbody2d.md#enum_CharacterBody2D_MotionMode) **MOTION_MODE_GROUNDED** = `0` + +Apply when notions of walls, ceiling and floor are relevant. In this mode the body motion will react to slopes (acceleration/slowdown). This mode is suitable for sided games like platformers. + + + +[MotionMode](class_characterbody2d.md#enum_CharacterBody2D_MotionMode) **MOTION_MODE_FLOATING** = `1` + +Apply when there is no notion of floor or ceiling. All collisions will be reported as ``on_wall``. In this mode, when you slide, the speed will always be constant. This mode is suitable for top-down games.
+ + + + + +enum **PlatformOnLeave**: [🔗](#enum_CharacterBody2D_PlatformOnLeave) + + + + + +[PlatformOnLeave](class_characterbody2d.md#enum_CharacterBody2D_PlatformOnLeave) **PLATFORM_ON_LEAVE_ADD_VELOCITY** = `0` + +Add the last platform velocity to the [velocity](class_characterbody2d.md#class_CharacterBody2D_property_velocity) when you leave a moving platform. + + + +[PlatformOnLeave](class_characterbody2d.md#enum_CharacterBody2D_PlatformOnLeave) **PLATFORM_ON_LEAVE_ADD_UPWARD_VELOCITY** = `1` + +Add the last platform velocity to the [velocity](class_characterbody2d.md#class_CharacterBody2D_property_velocity) when you leave a moving platform, but any downward motion is ignored. It's useful to keep full jump height even when the platform is moving down. + + + +[PlatformOnLeave](class_characterbody2d.md#enum_CharacterBody2D_PlatformOnLeave) **PLATFORM_ON_LEAVE_DO_NOTHING** = `2` + +Do nothing when leaving a platform.
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **floor_block_on_wall** = `true` [🔗](#class_CharacterBody2D_property_floor_block_on_wall) + + + +- `void` **set_floor_block_on_wall_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_floor_block_on_wall_enabled**\ (\ ) + +If ``true``, the body will be able to move on the floor only. This option avoids to be able to walk on walls, it will however allow to slide down along them. + +
+ + + + + +[bool](class_bool.md) **floor_constant_speed** = `false` [🔗](#class_CharacterBody2D_property_floor_constant_speed) + + + +- `void` **set_floor_constant_speed_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_floor_constant_speed_enabled**\ (\ ) + +If ``false`` (by default), the body will move faster on downward slopes and slower on upward slopes. + +If ``true``, the body will always move at the same speed on the ground no matter the slope. Note that you need to use [floor_snap_length](class_characterbody2d.md#class_CharacterBody2D_property_floor_snap_length) to stick along a downward slope at constant speed. + +
+ + + + + +[float](class_float.md) **floor_max_angle** = `0.7853982` [🔗](#class_CharacterBody2D_property_floor_max_angle) + + + +- `void` **set_floor_max_angle**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_floor_max_angle**\ (\ ) + +Maximum angle (in radians) where a slope is still considered a floor (or a ceiling), rather than a wall, when calling [move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide). The default value equals 45 degrees. + +
+ + + + + +[float](class_float.md) **floor_snap_length** = `1.0` [🔗](#class_CharacterBody2D_property_floor_snap_length) + + + +- `void` **set_floor_snap_length**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_floor_snap_length**\ (\ ) + +Sets a snapping distance. When set to a value different from ``0.0``, the body is kept attached to slopes when calling [move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide). The snapping vector is determined by the given distance along the opposite direction of the [up_direction](class_characterbody2d.md#class_CharacterBody2D_property_up_direction). + +As long as the snapping vector is in contact with the ground and the body moves against [up_direction](class_characterbody2d.md#class_CharacterBody2D_property_up_direction), the body will remain attached to the surface. Snapping is not applied if the body moves along [up_direction](class_characterbody2d.md#class_CharacterBody2D_property_up_direction), meaning it contains vertical rising velocity, so it will be able to detach from the ground when jumping or when the body is pushed up by something. If you want to apply a snap without taking into account the velocity, use [apply_floor_snap()](class_characterbody2d.md#class_CharacterBody2D_method_apply_floor_snap). + +
+ + + + + +[bool](class_bool.md) **floor_stop_on_slope** = `true` [🔗](#class_CharacterBody2D_property_floor_stop_on_slope) + + + +- `void` **set_floor_stop_on_slope_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_floor_stop_on_slope_enabled**\ (\ ) + +If ``true``, the body will not slide on slopes when calling [move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide) when the body is standing still. + +If ``false``, the body will slide on floor's slopes when [velocity](class_characterbody2d.md#class_CharacterBody2D_property_velocity) applies a downward force. + +
+ + + + + +[int](class_int.md) **max_slides** = `4` [🔗](#class_CharacterBody2D_property_max_slides) + + + +- `void` **set_max_slides**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_max_slides**\ (\ ) + +Maximum number of times the body can change direction before it stops when calling [move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide). Must be greater than zero. + +
+ + + + + +[MotionMode](class_characterbody2d.md#enum_CharacterBody2D_MotionMode) **motion_mode** = `0` [🔗](#class_CharacterBody2D_property_motion_mode) + + + +- `void` **set_motion_mode**\ (\ value\: [MotionMode](class_characterbody2d.md#enum_CharacterBody2D_MotionMode)\ ) +- [MotionMode](class_characterbody2d.md#enum_CharacterBody2D_MotionMode) **get_motion_mode**\ (\ ) + +Sets the motion mode which defines the behavior of [move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide). + +
+ + + + + +[int](class_int.md) **platform_floor_layers** = `4294967295` [🔗](#class_CharacterBody2D_property_platform_floor_layers) + + + +- `void` **set_platform_floor_layers**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_platform_floor_layers**\ (\ ) + +Collision layers that will be included for detecting floor bodies that will act as moving platforms to be followed by the **CharacterBody2D**. By default, all floor bodies are detected and propagate their velocity. + +
+ + + + + +[PlatformOnLeave](class_characterbody2d.md#enum_CharacterBody2D_PlatformOnLeave) **platform_on_leave** = `0` [🔗](#class_CharacterBody2D_property_platform_on_leave) + + + +- `void` **set_platform_on_leave**\ (\ value\: [PlatformOnLeave](class_characterbody2d.md#enum_CharacterBody2D_PlatformOnLeave)\ ) +- [PlatformOnLeave](class_characterbody2d.md#enum_CharacterBody2D_PlatformOnLeave) **get_platform_on_leave**\ (\ ) + +Sets the behavior to apply when you leave a moving platform. By default, to be physically accurate, when you leave the last platform velocity is applied. + +
+ + + + + +[int](class_int.md) **platform_wall_layers** = `0` [🔗](#class_CharacterBody2D_property_platform_wall_layers) + + + +- `void` **set_platform_wall_layers**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_platform_wall_layers**\ (\ ) + +Collision layers that will be included for detecting wall bodies that will act as moving platforms to be followed by the **CharacterBody2D**. By default, all wall bodies are ignored. + +
+ + + + + +[float](class_float.md) **safe_margin** = `0.08` [🔗](#class_CharacterBody2D_property_safe_margin) + + + +- `void` **set_safe_margin**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_safe_margin**\ (\ ) + +Extra margin used for collision recovery when calling [move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide). + +If the body is at least this close to another body, it will consider them to be colliding and will be pushed away before performing the actual motion. + +A higher value means it's more flexible for detecting collision, which helps with consistently detecting walls and floors. + +A lower value forces the collision algorithm to use more exact detection, so it can be used in cases that specifically require precision, e.g at very low scale to avoid visible jittering, or for stability with a stack of character bodies. + +
+ + + + + +[bool](class_bool.md) **slide_on_ceiling** = `true` [🔗](#class_CharacterBody2D_property_slide_on_ceiling) + + + +- `void` **set_slide_on_ceiling_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_slide_on_ceiling_enabled**\ (\ ) + +If ``true``, during a jump against the ceiling, the body will slide, if ``false`` it will be stopped and will fall vertically. + +
+ + + + + +[Vector2](class_vector2.md) **up_direction** = `Vector2(0, -1)` [🔗](#class_CharacterBody2D_property_up_direction) + + + +- `void` **set_up_direction**\ (\ value\: [Vector2](class_vector2.md)\ ) +- [Vector2](class_vector2.md) **get_up_direction**\ (\ ) + +Vector pointing upwards, used to determine what is a wall and what is a floor (or a ceiling) when calling [move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide). Defaults to [Vector2.UP](class_vector2.md#class_Vector2_constant_UP). As the vector will be normalized it can't be equal to [Vector2.ZERO](class_vector2.md#class_Vector2_constant_ZERO), if you want all collisions to be reported as walls, consider using [MOTION_MODE_FLOATING](class_characterbody2d.md#class_CharacterBody2D_constant_MOTION_MODE_FLOATING) as [motion_mode](class_characterbody2d.md#class_CharacterBody2D_property_motion_mode). + +
+ + + + + +[Vector2](class_vector2.md) **velocity** = `Vector2(0, 0)` [🔗](#class_CharacterBody2D_property_velocity) + + + +- `void` **set_velocity**\ (\ value\: [Vector2](class_vector2.md)\ ) +- [Vector2](class_vector2.md) **get_velocity**\ (\ ) + +Current velocity vector in pixels per second, used and modified during calls to [move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide). + +This property should not be set to a value multiplied by ``delta``, because this happens internally in [move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide). Otherwise, the simulation will run at an incorrect speed. + +
+ + + + + +[float](class_float.md) **wall_min_slide_angle** = `0.2617994` [🔗](#class_CharacterBody2D_property_wall_min_slide_angle) + + + +- `void` **set_wall_min_slide_angle**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_wall_min_slide_angle**\ (\ ) + +Minimum angle (in radians) where the body is allowed to slide when it encounters a wall. The default value equals 15 degrees. This property only affects movement when [motion_mode](class_characterbody2d.md#class_CharacterBody2D_property_motion_mode) is [MOTION_MODE_FLOATING](class_characterbody2d.md#class_CharacterBody2D_constant_MOTION_MODE_FLOATING). + +
+ + + +## Method Descriptions + + + + + +`void` **apply_floor_snap**\ (\ ) [🔗](#class_CharacterBody2D_method_apply_floor_snap) + +Allows to manually apply a snap to the floor regardless of the body's velocity. This function does nothing when [is_on_floor()](class_characterbody2d.md#class_CharacterBody2D_method_is_on_floor) returns ``true``. + +
+ + + + + +[float](class_float.md) **get_floor_angle**\ (\ up_direction\: [Vector2](class_vector2.md) = Vector2(0, -1)\ ) const [🔗](#class_CharacterBody2D_method_get_floor_angle) + +Returns the floor's collision angle at the last collision point according to `up_direction`, which is [Vector2.UP](class_vector2.md#class_Vector2_constant_UP) by default. This value is always positive and only valid after calling [move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide) and when [is_on_floor()](class_characterbody2d.md#class_CharacterBody2D_method_is_on_floor) returns ``true``. + +
+ + + + + +[Vector2](class_vector2.md) **get_floor_normal**\ (\ ) const [🔗](#class_CharacterBody2D_method_get_floor_normal) + +Returns the collision normal of the floor at the last collision point. Only valid after calling [move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide) and when [is_on_floor()](class_characterbody2d.md#class_CharacterBody2D_method_is_on_floor) returns ``true``. + +\ **Warning:** The collision normal is not always the same as the surface normal. + +
+ + + + + +[Vector2](class_vector2.md) **get_last_motion**\ (\ ) const [🔗](#class_CharacterBody2D_method_get_last_motion) + +Returns the last motion applied to the **CharacterBody2D** during the last call to [move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide). The movement can be split into multiple motions when sliding occurs, and this method return the last one, which is useful to retrieve the current direction of the movement. + +
+ + + + + +[KinematicCollision2D](class_kinematiccollision2d.md) **get_last_slide_collision**\ (\ ) [🔗](#class_CharacterBody2D_method_get_last_slide_collision) + +Returns a [KinematicCollision2D](class_kinematiccollision2d.md), which contains information about the latest collision that occurred during the last call to [move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide). + +
+ + + + + +[Vector2](class_vector2.md) **get_platform_velocity**\ (\ ) const [🔗](#class_CharacterBody2D_method_get_platform_velocity) + +Returns the linear velocity of the platform at the last collision point. Only valid after calling [move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide). + +
+ + + + + +[Vector2](class_vector2.md) **get_position_delta**\ (\ ) const [🔗](#class_CharacterBody2D_method_get_position_delta) + +Returns the travel (position delta) that occurred during the last call to [move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide). + +
+ + + + + +[Vector2](class_vector2.md) **get_real_velocity**\ (\ ) const [🔗](#class_CharacterBody2D_method_get_real_velocity) + +Returns the current real velocity since the last call to [move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide). For example, when you climb a slope, you will move diagonally even though the velocity is horizontal. This method returns the diagonal movement, as opposed to [velocity](class_characterbody2d.md#class_CharacterBody2D_property_velocity) which returns the requested velocity. + +
+ + + + + +[KinematicCollision2D](class_kinematiccollision2d.md) **get_slide_collision**\ (\ slide_idx\: [int](class_int.md)\ ) [🔗](#class_CharacterBody2D_method_get_slide_collision) + +Returns a [KinematicCollision2D](class_kinematiccollision2d.md), which contains information about a collision that occurred during the last call to [move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide). Since the body can collide several times in a single call to [move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide), you must specify the index of the collision in the range 0 to ([get_slide_collision_count()](class_characterbody2d.md#class_CharacterBody2D_method_get_slide_collision_count) - 1). + +\ **Example:** Iterate through the collisions with a ``for`` loop: + + + + +```gdscript + for i in get_slide_collision_count(): + var collision = get_slide_collision(i) + print("Collided with: ", collision.get_collider().name) +``` + +```csharp + for (int i = 0; i < GetSlideCollisionCount(); i++) + { + KinematicCollision2D collision = GetSlideCollision(i); + GD.Print("Collided with: ", (collision.GetCollider() as Node).Name); + } +``` + + + +
+ + + + + +[int](class_int.md) **get_slide_collision_count**\ (\ ) const [🔗](#class_CharacterBody2D_method_get_slide_collision_count) + +Returns the number of times the body collided and changed direction during the last call to [move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide). + +
+ + + + + +[Vector2](class_vector2.md) **get_wall_normal**\ (\ ) const [🔗](#class_CharacterBody2D_method_get_wall_normal) + +Returns the collision normal of the wall at the last collision point. Only valid after calling [move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide) and when [is_on_wall()](class_characterbody2d.md#class_CharacterBody2D_method_is_on_wall) returns ``true``. + +\ **Warning:** The collision normal is not always the same as the surface normal. + +
+ + + + + +[bool](class_bool.md) **is_on_ceiling**\ (\ ) const [🔗](#class_CharacterBody2D_method_is_on_ceiling) + +Returns ``true`` if the body collided with the ceiling on the last call of [move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide). Otherwise, returns ``false``. The [up_direction](class_characterbody2d.md#class_CharacterBody2D_property_up_direction) and [floor_max_angle](class_characterbody2d.md#class_CharacterBody2D_property_floor_max_angle) are used to determine whether a surface is "ceiling" or not. + +
+ + + + + +[bool](class_bool.md) **is_on_ceiling_only**\ (\ ) const [🔗](#class_CharacterBody2D_method_is_on_ceiling_only) + +Returns ``true`` if the body collided only with the ceiling on the last call of [move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide). Otherwise, returns ``false``. The [up_direction](class_characterbody2d.md#class_CharacterBody2D_property_up_direction) and [floor_max_angle](class_characterbody2d.md#class_CharacterBody2D_property_floor_max_angle) are used to determine whether a surface is "ceiling" or not. + +
+ + + + + +[bool](class_bool.md) **is_on_floor**\ (\ ) const [🔗](#class_CharacterBody2D_method_is_on_floor) + +Returns ``true`` if the body collided with the floor on the last call of [move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide). Otherwise, returns ``false``. The [up_direction](class_characterbody2d.md#class_CharacterBody2D_property_up_direction) and [floor_max_angle](class_characterbody2d.md#class_CharacterBody2D_property_floor_max_angle) are used to determine whether a surface is "floor" or not. + +
+ + + + + +[bool](class_bool.md) **is_on_floor_only**\ (\ ) const [🔗](#class_CharacterBody2D_method_is_on_floor_only) + +Returns ``true`` if the body collided only with the floor on the last call of [move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide). Otherwise, returns ``false``. The [up_direction](class_characterbody2d.md#class_CharacterBody2D_property_up_direction) and [floor_max_angle](class_characterbody2d.md#class_CharacterBody2D_property_floor_max_angle) are used to determine whether a surface is "floor" or not. + +
+ + + + + +[bool](class_bool.md) **is_on_wall**\ (\ ) const [🔗](#class_CharacterBody2D_method_is_on_wall) + +Returns ``true`` if the body collided with a wall on the last call of [move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide). Otherwise, returns ``false``. The [up_direction](class_characterbody2d.md#class_CharacterBody2D_property_up_direction) and [floor_max_angle](class_characterbody2d.md#class_CharacterBody2D_property_floor_max_angle) are used to determine whether a surface is "wall" or not. + +
+ + + + + +[bool](class_bool.md) **is_on_wall_only**\ (\ ) const [🔗](#class_CharacterBody2D_method_is_on_wall_only) + +Returns ``true`` if the body collided only with a wall on the last call of [move_and_slide()](class_characterbody2d.md#class_CharacterBody2D_method_move_and_slide). Otherwise, returns ``false``. The [up_direction](class_characterbody2d.md#class_CharacterBody2D_property_up_direction) and [floor_max_angle](class_characterbody2d.md#class_CharacterBody2D_property_floor_max_angle) are used to determine whether a surface is "wall" or not. + +
+ + + + + +[bool](class_bool.md) **move_and_slide**\ (\ ) [🔗](#class_CharacterBody2D_method_move_and_slide) + +Moves the body based on [velocity](class_characterbody2d.md#class_CharacterBody2D_property_velocity). If the body collides with another, it will slide along the other body (by default only on floor) rather than stop immediately. If the other body is a **CharacterBody2D** or [RigidBody2D](class_rigidbody2d.md), it will also be affected by the motion of the other body. You can use this to make moving and rotating platforms, or to make nodes push other nodes. + +This method should be used in [Node._physics_process()](class_node.md#class_Node_private_method__physics_process) (or in a method called by [Node._physics_process()](class_node.md#class_Node_private_method__physics_process)), as it uses the physics step's ``delta`` value automatically in calculations. Otherwise, the simulation will run at an incorrect speed. + +Modifies [velocity](class_characterbody2d.md#class_CharacterBody2D_property_velocity) if a slide collision occurred. To get the latest collision call [get_last_slide_collision()](class_characterbody2d.md#class_CharacterBody2D_method_get_last_slide_collision), for detailed information about collisions that occurred, use [get_slide_collision()](class_characterbody2d.md#class_CharacterBody2D_method_get_slide_collision). + +When the body touches a moving platform, the platform's velocity is automatically added to the body motion. If a collision occurs due to the platform's motion, it will always be first in the slide collisions. + +The general behavior and available properties change according to the [motion_mode](class_characterbody2d.md#class_CharacterBody2D_property_motion_mode). + +Returns ``true`` if the body collided, otherwise, returns ``false``. + diff --git a/docs/Classes/class_characterbody3d.md b/docs/Classes/class_characterbody3d.md new file mode 100644 index 00000000..f052bcf8 --- /dev/null +++ b/docs/Classes/class_characterbody3d.md @@ -0,0 +1,713 @@ + + + + + + + + + +# CharacterBody3D + +**Inherits:** [PhysicsBody3D](class_physicsbody3d.md) **<** [CollisionObject3D](class_collisionobject3d.md) **<** [Node3D](class_node3d.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +A 3D physics body specialized for characters moved by script. + + + +## Description + +**CharacterBody3D** is a specialized class for physics bodies that are meant to be user-controlled. They are not affected by physics at all, but they affect other physics bodies in their path. They are mainly used to provide high-level API to move objects with wall and slope detection ([move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide) method) in addition to the general collision detection provided by [PhysicsBody3D.move_and_collide()](class_physicsbody3d.md#class_PhysicsBody3D_method_move_and_collide). This makes it useful for highly configurable physics bodies that must move in specific ways and collide with the world, as is often the case with user-controlled characters. + +For game objects that don't require complex movement or collision detection, such as moving platforms, [AnimatableBody3D](class_animatablebody3d.md) is simpler to configure. + + + +## Tutorials + +- [Physics introduction](../tutorials/physics/physics_introduction.md) + +- [Troubleshooting physics issues](../tutorials/physics/troubleshooting_physics_issues.md) + +- [Kinematic character (2D)](../tutorials/physics/kinematic_character_2d.md) + +- [3D Kinematic Character Demo](https://godotengine.org/asset-library/asset/2739) + +- [3D Platformer Demo](https://godotengine.org/asset-library/asset/2748) + +- [3D Voxel Demo](https://godotengine.org/asset-library/asset/2755) + +- [Third Person Shooter (TPS) Demo](https://godotengine.org/asset-library/asset/2710) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[floor_block_on_wall](#class_CharacterBody3D_property_floor_block_on_wall)`true`
[bool](class_bool.md)[floor_constant_speed](#class_CharacterBody3D_property_floor_constant_speed)`false`
[float](class_float.md)[floor_max_angle](#class_CharacterBody3D_property_floor_max_angle)`0.7853982`
[float](class_float.md)[floor_snap_length](#class_CharacterBody3D_property_floor_snap_length)`0.1`
[bool](class_bool.md)[floor_stop_on_slope](#class_CharacterBody3D_property_floor_stop_on_slope)`true`
[int](class_int.md)[max_slides](#class_CharacterBody3D_property_max_slides)`6`
[MotionMode](class_characterbody3d.md#enum_CharacterBody3D_MotionMode)[motion_mode](#class_CharacterBody3D_property_motion_mode)`0`
[int](class_int.md)[platform_floor_layers](#class_CharacterBody3D_property_platform_floor_layers)`4294967295`
[PlatformOnLeave](class_characterbody3d.md#enum_CharacterBody3D_PlatformOnLeave)[platform_on_leave](#class_CharacterBody3D_property_platform_on_leave)`0`
[int](class_int.md)[platform_wall_layers](#class_CharacterBody3D_property_platform_wall_layers)`0`
[float](class_float.md)[safe_margin](#class_CharacterBody3D_property_safe_margin)`0.001`
[bool](class_bool.md)[slide_on_ceiling](#class_CharacterBody3D_property_slide_on_ceiling)`true`
[Vector3](class_vector3.md)[up_direction](#class_CharacterBody3D_property_up_direction)`Vector3(0, 1, 0)`
[Vector3](class_vector3.md)[velocity](#class_CharacterBody3D_property_velocity)`Vector3(0, 0, 0)`
[float](class_float.md)[wall_min_slide_angle](#class_CharacterBody3D_property_wall_min_slide_angle)`0.2617994`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
`void`[apply_floor_snap](#class_CharacterBody3D_method_apply_floor_snap)\ (\ )
[float](class_float.md)[get_floor_angle](#class_CharacterBody3D_method_get_floor_angle)\ (\ up_direction\: [Vector3](class_vector3.md) = Vector3(0, 1, 0)\ ) const
[Vector3](class_vector3.md)[get_floor_normal](#class_CharacterBody3D_method_get_floor_normal)\ (\ ) const
[Vector3](class_vector3.md)[get_last_motion](#class_CharacterBody3D_method_get_last_motion)\ (\ ) const
[KinematicCollision3D](class_kinematiccollision3d.md)[get_last_slide_collision](#class_CharacterBody3D_method_get_last_slide_collision)\ (\ )
[Vector3](class_vector3.md)[get_platform_angular_velocity](#class_CharacterBody3D_method_get_platform_angular_velocity)\ (\ ) const
[Vector3](class_vector3.md)[get_platform_velocity](#class_CharacterBody3D_method_get_platform_velocity)\ (\ ) const
[Vector3](class_vector3.md)[get_position_delta](#class_CharacterBody3D_method_get_position_delta)\ (\ ) const
[Vector3](class_vector3.md)[get_real_velocity](#class_CharacterBody3D_method_get_real_velocity)\ (\ ) const
[KinematicCollision3D](class_kinematiccollision3d.md)[get_slide_collision](#class_CharacterBody3D_method_get_slide_collision)\ (\ slide_idx\: [int](class_int.md)\ )
[int](class_int.md)[get_slide_collision_count](#class_CharacterBody3D_method_get_slide_collision_count)\ (\ ) const
[Vector3](class_vector3.md)[get_wall_normal](#class_CharacterBody3D_method_get_wall_normal)\ (\ ) const
[bool](class_bool.md)[is_on_ceiling](#class_CharacterBody3D_method_is_on_ceiling)\ (\ ) const
[bool](class_bool.md)[is_on_ceiling_only](#class_CharacterBody3D_method_is_on_ceiling_only)\ (\ ) const
[bool](class_bool.md)[is_on_floor](#class_CharacterBody3D_method_is_on_floor)\ (\ ) const
[bool](class_bool.md)[is_on_floor_only](#class_CharacterBody3D_method_is_on_floor_only)\ (\ ) const
[bool](class_bool.md)[is_on_wall](#class_CharacterBody3D_method_is_on_wall)\ (\ ) const
[bool](class_bool.md)[is_on_wall_only](#class_CharacterBody3D_method_is_on_wall_only)\ (\ ) const
[bool](class_bool.md)[move_and_slide](#class_CharacterBody3D_method_move_and_slide)\ (\ )
+ +
+ + + +## Enumerations + + + + + +enum **MotionMode**: [🔗](#enum_CharacterBody3D_MotionMode) + + + + + +[MotionMode](class_characterbody3d.md#enum_CharacterBody3D_MotionMode) **MOTION_MODE_GROUNDED** = `0` + +Apply when notions of walls, ceiling and floor are relevant. In this mode the body motion will react to slopes (acceleration/slowdown). This mode is suitable for grounded games like platformers. + + + +[MotionMode](class_characterbody3d.md#enum_CharacterBody3D_MotionMode) **MOTION_MODE_FLOATING** = `1` + +Apply when there is no notion of floor or ceiling. All collisions will be reported as ``on_wall``. In this mode, when you slide, the speed will always be constant. This mode is suitable for games without ground like space games.
+ + + + + +enum **PlatformOnLeave**: [🔗](#enum_CharacterBody3D_PlatformOnLeave) + + + + + +[PlatformOnLeave](class_characterbody3d.md#enum_CharacterBody3D_PlatformOnLeave) **PLATFORM_ON_LEAVE_ADD_VELOCITY** = `0` + +Add the last platform velocity to the [velocity](class_characterbody3d.md#class_CharacterBody3D_property_velocity) when you leave a moving platform. + + + +[PlatformOnLeave](class_characterbody3d.md#enum_CharacterBody3D_PlatformOnLeave) **PLATFORM_ON_LEAVE_ADD_UPWARD_VELOCITY** = `1` + +Add the last platform velocity to the [velocity](class_characterbody3d.md#class_CharacterBody3D_property_velocity) when you leave a moving platform, but any downward motion is ignored. It's useful to keep full jump height even when the platform is moving down. + + + +[PlatformOnLeave](class_characterbody3d.md#enum_CharacterBody3D_PlatformOnLeave) **PLATFORM_ON_LEAVE_DO_NOTHING** = `2` + +Do nothing when leaving a platform.
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **floor_block_on_wall** = `true` [🔗](#class_CharacterBody3D_property_floor_block_on_wall) + + + +- `void` **set_floor_block_on_wall_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_floor_block_on_wall_enabled**\ (\ ) + +If ``true``, the body will be able to move on the floor only. This option avoids to be able to walk on walls, it will however allow to slide down along them. + +
+ + + + + +[bool](class_bool.md) **floor_constant_speed** = `false` [🔗](#class_CharacterBody3D_property_floor_constant_speed) + + + +- `void` **set_floor_constant_speed_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_floor_constant_speed_enabled**\ (\ ) + +If ``false`` (by default), the body will move faster on downward slopes and slower on upward slopes. + +If ``true``, the body will always move at the same speed on the ground no matter the slope. Note that you need to use [floor_snap_length](class_characterbody3d.md#class_CharacterBody3D_property_floor_snap_length) to stick along a downward slope at constant speed. + +
+ + + + + +[float](class_float.md) **floor_max_angle** = `0.7853982` [🔗](#class_CharacterBody3D_property_floor_max_angle) + + + +- `void` **set_floor_max_angle**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_floor_max_angle**\ (\ ) + +Maximum angle (in radians) where a slope is still considered a floor (or a ceiling), rather than a wall, when calling [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide). The default value equals 45 degrees. + +
+ + + + + +[float](class_float.md) **floor_snap_length** = `0.1` [🔗](#class_CharacterBody3D_property_floor_snap_length) + + + +- `void` **set_floor_snap_length**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_floor_snap_length**\ (\ ) + +Sets a snapping distance. When set to a value different from ``0.0``, the body is kept attached to slopes when calling [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide). The snapping vector is determined by the given distance along the opposite direction of the [up_direction](class_characterbody3d.md#class_CharacterBody3D_property_up_direction). + +As long as the snapping vector is in contact with the ground and the body moves against [up_direction](class_characterbody3d.md#class_CharacterBody3D_property_up_direction), the body will remain attached to the surface. Snapping is not applied if the body moves along [up_direction](class_characterbody3d.md#class_CharacterBody3D_property_up_direction), meaning it contains vertical rising velocity, so it will be able to detach from the ground when jumping or when the body is pushed up by something. If you want to apply a snap without taking into account the velocity, use [apply_floor_snap()](class_characterbody3d.md#class_CharacterBody3D_method_apply_floor_snap). + +
+ + + + + +[bool](class_bool.md) **floor_stop_on_slope** = `true` [🔗](#class_CharacterBody3D_property_floor_stop_on_slope) + + + +- `void` **set_floor_stop_on_slope_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_floor_stop_on_slope_enabled**\ (\ ) + +If ``true``, the body will not slide on slopes when calling [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide) when the body is standing still. + +If ``false``, the body will slide on floor's slopes when [velocity](class_characterbody3d.md#class_CharacterBody3D_property_velocity) applies a downward force. + +
+ + + + + +[int](class_int.md) **max_slides** = `6` [🔗](#class_CharacterBody3D_property_max_slides) + + + +- `void` **set_max_slides**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_max_slides**\ (\ ) + +Maximum number of times the body can change direction before it stops when calling [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide). Must be greater than zero. + +
+ + + + + +[MotionMode](class_characterbody3d.md#enum_CharacterBody3D_MotionMode) **motion_mode** = `0` [🔗](#class_CharacterBody3D_property_motion_mode) + + + +- `void` **set_motion_mode**\ (\ value\: [MotionMode](class_characterbody3d.md#enum_CharacterBody3D_MotionMode)\ ) +- [MotionMode](class_characterbody3d.md#enum_CharacterBody3D_MotionMode) **get_motion_mode**\ (\ ) + +Sets the motion mode which defines the behavior of [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide). + +
+ + + + + +[int](class_int.md) **platform_floor_layers** = `4294967295` [🔗](#class_CharacterBody3D_property_platform_floor_layers) + + + +- `void` **set_platform_floor_layers**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_platform_floor_layers**\ (\ ) + +Collision layers that will be included for detecting floor bodies that will act as moving platforms to be followed by the **CharacterBody3D**. By default, all floor bodies are detected and propagate their velocity. + +
+ + + + + +[PlatformOnLeave](class_characterbody3d.md#enum_CharacterBody3D_PlatformOnLeave) **platform_on_leave** = `0` [🔗](#class_CharacterBody3D_property_platform_on_leave) + + + +- `void` **set_platform_on_leave**\ (\ value\: [PlatformOnLeave](class_characterbody3d.md#enum_CharacterBody3D_PlatformOnLeave)\ ) +- [PlatformOnLeave](class_characterbody3d.md#enum_CharacterBody3D_PlatformOnLeave) **get_platform_on_leave**\ (\ ) + +Sets the behavior to apply when you leave a moving platform. By default, to be physically accurate, when you leave the last platform velocity is applied. + +
+ + + + + +[int](class_int.md) **platform_wall_layers** = `0` [🔗](#class_CharacterBody3D_property_platform_wall_layers) + + + +- `void` **set_platform_wall_layers**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_platform_wall_layers**\ (\ ) + +Collision layers that will be included for detecting wall bodies that will act as moving platforms to be followed by the **CharacterBody3D**. By default, all wall bodies are ignored. + +
+ + + + + +[float](class_float.md) **safe_margin** = `0.001` [🔗](#class_CharacterBody3D_property_safe_margin) + + + +- `void` **set_safe_margin**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_safe_margin**\ (\ ) + +Extra margin used for collision recovery when calling [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide). + +If the body is at least this close to another body, it will consider them to be colliding and will be pushed away before performing the actual motion. + +A higher value means it's more flexible for detecting collision, which helps with consistently detecting walls and floors. + +A lower value forces the collision algorithm to use more exact detection, so it can be used in cases that specifically require precision, e.g at very low scale to avoid visible jittering, or for stability with a stack of character bodies. + +
+ + + + + +[bool](class_bool.md) **slide_on_ceiling** = `true` [🔗](#class_CharacterBody3D_property_slide_on_ceiling) + + + +- `void` **set_slide_on_ceiling_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_slide_on_ceiling_enabled**\ (\ ) + +If ``true``, during a jump against the ceiling, the body will slide, if ``false`` it will be stopped and will fall vertically. + +
+ + + + + +[Vector3](class_vector3.md) **up_direction** = `Vector3(0, 1, 0)` [🔗](#class_CharacterBody3D_property_up_direction) + + + +- `void` **set_up_direction**\ (\ value\: [Vector3](class_vector3.md)\ ) +- [Vector3](class_vector3.md) **get_up_direction**\ (\ ) + +Vector pointing upwards, used to determine what is a wall and what is a floor (or a ceiling) when calling [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide). Defaults to [Vector3.UP](class_vector3.md#class_Vector3_constant_UP). As the vector will be normalized it can't be equal to [Vector3.ZERO](class_vector3.md#class_Vector3_constant_ZERO), if you want all collisions to be reported as walls, consider using [MOTION_MODE_FLOATING](class_characterbody3d.md#class_CharacterBody3D_constant_MOTION_MODE_FLOATING) as [motion_mode](class_characterbody3d.md#class_CharacterBody3D_property_motion_mode). + +
+ + + + + +[Vector3](class_vector3.md) **velocity** = `Vector3(0, 0, 0)` [🔗](#class_CharacterBody3D_property_velocity) + + + +- `void` **set_velocity**\ (\ value\: [Vector3](class_vector3.md)\ ) +- [Vector3](class_vector3.md) **get_velocity**\ (\ ) + +Current velocity vector (typically meters per second), used and modified during calls to [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide). + +This property should not be set to a value multiplied by ``delta``, because this happens internally in [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide). Otherwise, the simulation will run at an incorrect speed. + +
+ + + + + +[float](class_float.md) **wall_min_slide_angle** = `0.2617994` [🔗](#class_CharacterBody3D_property_wall_min_slide_angle) + + + +- `void` **set_wall_min_slide_angle**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_wall_min_slide_angle**\ (\ ) + +Minimum angle (in radians) where the body is allowed to slide when it encounters a wall. The default value equals 15 degrees. When [motion_mode](class_characterbody3d.md#class_CharacterBody3D_property_motion_mode) is [MOTION_MODE_GROUNDED](class_characterbody3d.md#class_CharacterBody3D_constant_MOTION_MODE_GROUNDED), it only affects movement if [floor_block_on_wall](class_characterbody3d.md#class_CharacterBody3D_property_floor_block_on_wall) is ``true``. + +
+ + + +## Method Descriptions + + + + + +`void` **apply_floor_snap**\ (\ ) [🔗](#class_CharacterBody3D_method_apply_floor_snap) + +Allows to manually apply a snap to the floor regardless of the body's velocity. This function does nothing when [is_on_floor()](class_characterbody3d.md#class_CharacterBody3D_method_is_on_floor) returns ``true``. + +
+ + + + + +[float](class_float.md) **get_floor_angle**\ (\ up_direction\: [Vector3](class_vector3.md) = Vector3(0, 1, 0)\ ) const [🔗](#class_CharacterBody3D_method_get_floor_angle) + +Returns the floor's collision angle at the last collision point according to `up_direction`, which is [Vector3.UP](class_vector3.md#class_Vector3_constant_UP) by default. This value is always positive and only valid after calling [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide) and when [is_on_floor()](class_characterbody3d.md#class_CharacterBody3D_method_is_on_floor) returns ``true``. + +
+ + + + + +[Vector3](class_vector3.md) **get_floor_normal**\ (\ ) const [🔗](#class_CharacterBody3D_method_get_floor_normal) + +Returns the collision normal of the floor at the last collision point. Only valid after calling [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide) and when [is_on_floor()](class_characterbody3d.md#class_CharacterBody3D_method_is_on_floor) returns ``true``. + +\ **Warning:** The collision normal is not always the same as the surface normal. + +
+ + + + + +[Vector3](class_vector3.md) **get_last_motion**\ (\ ) const [🔗](#class_CharacterBody3D_method_get_last_motion) + +Returns the last motion applied to the **CharacterBody3D** during the last call to [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide). The movement can be split into multiple motions when sliding occurs, and this method return the last one, which is useful to retrieve the current direction of the movement. + +
+ + + + + +[KinematicCollision3D](class_kinematiccollision3d.md) **get_last_slide_collision**\ (\ ) [🔗](#class_CharacterBody3D_method_get_last_slide_collision) + +Returns a [KinematicCollision3D](class_kinematiccollision3d.md), which contains information about the latest collision that occurred during the last call to [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide). + +
+ + + + + +[Vector3](class_vector3.md) **get_platform_angular_velocity**\ (\ ) const [🔗](#class_CharacterBody3D_method_get_platform_angular_velocity) + +Returns the angular velocity of the platform at the last collision point. Only valid after calling [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide). + +
+ + + + + +[Vector3](class_vector3.md) **get_platform_velocity**\ (\ ) const [🔗](#class_CharacterBody3D_method_get_platform_velocity) + +Returns the linear velocity of the platform at the last collision point. Only valid after calling [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide). + +
+ + + + + +[Vector3](class_vector3.md) **get_position_delta**\ (\ ) const [🔗](#class_CharacterBody3D_method_get_position_delta) + +Returns the travel (position delta) that occurred during the last call to [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide). + +
+ + + + + +[Vector3](class_vector3.md) **get_real_velocity**\ (\ ) const [🔗](#class_CharacterBody3D_method_get_real_velocity) + +Returns the current real velocity since the last call to [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide). For example, when you climb a slope, you will move diagonally even though the velocity is horizontal. This method returns the diagonal movement, as opposed to [velocity](class_characterbody3d.md#class_CharacterBody3D_property_velocity) which returns the requested velocity. + +
+ + + + + +[KinematicCollision3D](class_kinematiccollision3d.md) **get_slide_collision**\ (\ slide_idx\: [int](class_int.md)\ ) [🔗](#class_CharacterBody3D_method_get_slide_collision) + +Returns a [KinematicCollision3D](class_kinematiccollision3d.md), which contains information about a collision that occurred during the last call to [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide). Since the body can collide several times in a single call to [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide), you must specify the index of the collision in the range 0 to ([get_slide_collision_count()](class_characterbody3d.md#class_CharacterBody3D_method_get_slide_collision_count) - 1). + +
+ + + + + +[int](class_int.md) **get_slide_collision_count**\ (\ ) const [🔗](#class_CharacterBody3D_method_get_slide_collision_count) + +Returns the number of times the body collided and changed direction during the last call to [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide). + +
+ + + + + +[Vector3](class_vector3.md) **get_wall_normal**\ (\ ) const [🔗](#class_CharacterBody3D_method_get_wall_normal) + +Returns the collision normal of the wall at the last collision point. Only valid after calling [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide) and when [is_on_wall()](class_characterbody3d.md#class_CharacterBody3D_method_is_on_wall) returns ``true``. + +\ **Warning:** The collision normal is not always the same as the surface normal. + +
+ + + + + +[bool](class_bool.md) **is_on_ceiling**\ (\ ) const [🔗](#class_CharacterBody3D_method_is_on_ceiling) + +Returns ``true`` if the body collided with the ceiling on the last call of [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide). Otherwise, returns ``false``. The [up_direction](class_characterbody3d.md#class_CharacterBody3D_property_up_direction) and [floor_max_angle](class_characterbody3d.md#class_CharacterBody3D_property_floor_max_angle) are used to determine whether a surface is "ceiling" or not. + +
+ + + + + +[bool](class_bool.md) **is_on_ceiling_only**\ (\ ) const [🔗](#class_CharacterBody3D_method_is_on_ceiling_only) + +Returns ``true`` if the body collided only with the ceiling on the last call of [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide). Otherwise, returns ``false``. The [up_direction](class_characterbody3d.md#class_CharacterBody3D_property_up_direction) and [floor_max_angle](class_characterbody3d.md#class_CharacterBody3D_property_floor_max_angle) are used to determine whether a surface is "ceiling" or not. + +
+ + + + + +[bool](class_bool.md) **is_on_floor**\ (\ ) const [🔗](#class_CharacterBody3D_method_is_on_floor) + +Returns ``true`` if the body collided with the floor on the last call of [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide). Otherwise, returns ``false``. The [up_direction](class_characterbody3d.md#class_CharacterBody3D_property_up_direction) and [floor_max_angle](class_characterbody3d.md#class_CharacterBody3D_property_floor_max_angle) are used to determine whether a surface is "floor" or not. + +
+ + + + + +[bool](class_bool.md) **is_on_floor_only**\ (\ ) const [🔗](#class_CharacterBody3D_method_is_on_floor_only) + +Returns ``true`` if the body collided only with the floor on the last call of [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide). Otherwise, returns ``false``. The [up_direction](class_characterbody3d.md#class_CharacterBody3D_property_up_direction) and [floor_max_angle](class_characterbody3d.md#class_CharacterBody3D_property_floor_max_angle) are used to determine whether a surface is "floor" or not. + +
+ + + + + +[bool](class_bool.md) **is_on_wall**\ (\ ) const [🔗](#class_CharacterBody3D_method_is_on_wall) + +Returns ``true`` if the body collided with a wall on the last call of [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide). Otherwise, returns ``false``. The [up_direction](class_characterbody3d.md#class_CharacterBody3D_property_up_direction) and [floor_max_angle](class_characterbody3d.md#class_CharacterBody3D_property_floor_max_angle) are used to determine whether a surface is "wall" or not. + +
+ + + + + +[bool](class_bool.md) **is_on_wall_only**\ (\ ) const [🔗](#class_CharacterBody3D_method_is_on_wall_only) + +Returns ``true`` if the body collided only with a wall on the last call of [move_and_slide()](class_characterbody3d.md#class_CharacterBody3D_method_move_and_slide). Otherwise, returns ``false``. The [up_direction](class_characterbody3d.md#class_CharacterBody3D_property_up_direction) and [floor_max_angle](class_characterbody3d.md#class_CharacterBody3D_property_floor_max_angle) are used to determine whether a surface is "wall" or not. + +
+ + + + + +[bool](class_bool.md) **move_and_slide**\ (\ ) [🔗](#class_CharacterBody3D_method_move_and_slide) + +Moves the body based on [velocity](class_characterbody3d.md#class_CharacterBody3D_property_velocity). If the body collides with another, it will slide along the other body rather than stop immediately. If the other body is a **CharacterBody3D** or [RigidBody3D](class_rigidbody3d.md), it will also be affected by the motion of the other body. You can use this to make moving and rotating platforms, or to make nodes push other nodes. + +This method should be used in [Node._physics_process()](class_node.md#class_Node_private_method__physics_process) (or in a method called by [Node._physics_process()](class_node.md#class_Node_private_method__physics_process)), as it uses the physics step's ``delta`` value automatically in calculations. Otherwise, the simulation will run at an incorrect speed. + +Modifies [velocity](class_characterbody3d.md#class_CharacterBody3D_property_velocity) if a slide collision occurred. To get the latest collision call [get_last_slide_collision()](class_characterbody3d.md#class_CharacterBody3D_method_get_last_slide_collision), for more detailed information about collisions that occurred, use [get_slide_collision()](class_characterbody3d.md#class_CharacterBody3D_method_get_slide_collision). + +When the body touches a moving platform, the platform's velocity is automatically added to the body motion. If a collision occurs due to the platform's motion, it will always be first in the slide collisions. + +Returns ``true`` if the body collided, otherwise, returns ``false``. + diff --git a/docs/Classes/class_charfxtransform.md b/docs/Classes/class_charfxtransform.md new file mode 100644 index 00000000..72994d0f --- /dev/null +++ b/docs/Classes/class_charfxtransform.md @@ -0,0 +1,322 @@ + + + + + + + + + +# CharFXTransform + +**Inherits:** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Controls how an individual character will be displayed in a [RichTextEffect](class_richtexteffect.md). + + + +## Description + +By setting various properties on this object, you can control how individual characters will be displayed in a [RichTextEffect](class_richtexteffect.md). + + + +## Tutorials + +- [BBCode in RichTextLabel](../tutorials/ui/bbcode_in_richtextlabel.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Color](class_color.md)[color](#class_CharFXTransform_property_color)`Color(0, 0, 0, 1)`
[float](class_float.md)[elapsed_time](#class_CharFXTransform_property_elapsed_time)`0.0`
[Dictionary](class_dictionary.md)[env](#class_CharFXTransform_property_env)`{}`
[RID](class_rid.md)[font](#class_CharFXTransform_property_font)`RID()`
[int](class_int.md)[glyph_count](#class_CharFXTransform_property_glyph_count)`0`
[int](class_int.md)[glyph_flags](#class_CharFXTransform_property_glyph_flags)`0`
[int](class_int.md)[glyph_index](#class_CharFXTransform_property_glyph_index)`0`
[Vector2](class_vector2.md)[offset](#class_CharFXTransform_property_offset)`Vector2(0, 0)`
[bool](class_bool.md)[outline](#class_CharFXTransform_property_outline)`false`
[Vector2i](class_vector2i.md)[range](#class_CharFXTransform_property_range)`Vector2i(0, 0)`
[int](class_int.md)[relative_index](#class_CharFXTransform_property_relative_index)`0`
[Transform2D](class_transform2d.md)[transform](#class_CharFXTransform_property_transform)`Transform2D(1, 0, 0, 1, 0, 0)`
[bool](class_bool.md)[visible](#class_CharFXTransform_property_visible)`true`
+ +
+ + + +## Property Descriptions + + + + + +[Color](class_color.md) **color** = `Color(0, 0, 0, 1)` [🔗](#class_CharFXTransform_property_color) + + + +- `void` **set_color**\ (\ value\: [Color](class_color.md)\ ) +- [Color](class_color.md) **get_color**\ (\ ) + +The color the character will be drawn with. + +
+ + + + + +[float](class_float.md) **elapsed_time** = `0.0` [🔗](#class_CharFXTransform_property_elapsed_time) + + + +- `void` **set_elapsed_time**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_elapsed_time**\ (\ ) + +The time elapsed since the [RichTextLabel](class_richtextlabel.md) was added to the scene tree (in seconds). Time stops when the [RichTextLabel](class_richtextlabel.md) is paused (see [Node.process_mode](class_node.md#class_Node_property_process_mode)). Resets when the text in the [RichTextLabel](class_richtextlabel.md) is changed. + +\ **Note:** Time still passes while the [RichTextLabel](class_richtextlabel.md) is hidden. + +
+ + + + + +[Dictionary](class_dictionary.md) **env** = `{}` [🔗](#class_CharFXTransform_property_env) + + + +- `void` **set_environment**\ (\ value\: [Dictionary](class_dictionary.md)\ ) +- [Dictionary](class_dictionary.md) **get_environment**\ (\ ) + +Contains the arguments passed in the opening BBCode tag. By default, arguments are strings; if their contents match a type such as [bool](class_bool.md), [int](class_int.md) or [float](class_float.md), they will be converted automatically. Color codes in the form ``#rrggbb`` or ``#rgb`` will be converted to an opaque [Color](class_color.md). String arguments may not contain spaces, even if they're quoted. If present, quotes will also be present in the final string. + +For example, the opening BBCode tag ``[example foo=hello bar=true baz=42 color=#ffffff]`` will map to the following [Dictionary](class_dictionary.md): + +``` + {"foo": "hello", "bar": true, "baz": 42, "color": Color(1, 1, 1, 1)} +``` + +
+ + + + + +[RID](class_rid.md) **font** = `RID()` [🔗](#class_CharFXTransform_property_font) + + + +- `void` **set_font**\ (\ value\: [RID](class_rid.md)\ ) +- [RID](class_rid.md) **get_font**\ (\ ) + +[TextServer](class_textserver.md) RID of the font used to render glyph, this value can be used with ``TextServer.font_*`` methods to retrieve font information. + +\ **Note:** Read-only. Setting this property won't affect drawing. + +
+ + + + + +[int](class_int.md) **glyph_count** = `0` [🔗](#class_CharFXTransform_property_glyph_count) + + + +- `void` **set_glyph_count**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_glyph_count**\ (\ ) + +Number of glyphs in the grapheme cluster. This value is set in the first glyph of a cluster. + +\ **Note:** Read-only. Setting this property won't affect drawing. + +
+ + + + + +[int](class_int.md) **glyph_flags** = `0` [🔗](#class_CharFXTransform_property_glyph_flags) + + + +- `void` **set_glyph_flags**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_glyph_flags**\ (\ ) + +Glyph flags. See [GraphemeFlag](class_textserver.md#enum_TextServer_GraphemeFlag) for more info. + +\ **Note:** Read-only. Setting this property won't affect drawing. + +
+ + + + + +[int](class_int.md) **glyph_index** = `0` [🔗](#class_CharFXTransform_property_glyph_index) + + + +- `void` **set_glyph_index**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_glyph_index**\ (\ ) + +Glyph index specific to the [font](class_charfxtransform.md#class_CharFXTransform_property_font). If you want to replace this glyph, use [TextServer.font_get_glyph_index()](class_textserver.md#class_TextServer_method_font_get_glyph_index) with [font](class_charfxtransform.md#class_CharFXTransform_property_font) to get a new glyph index for a single character. + +
+ + + + + +[Vector2](class_vector2.md) **offset** = `Vector2(0, 0)` [🔗](#class_CharFXTransform_property_offset) + + + +- `void` **set_offset**\ (\ value\: [Vector2](class_vector2.md)\ ) +- [Vector2](class_vector2.md) **get_offset**\ (\ ) + +The position offset the character will be drawn with (in pixels). + +
+ + + + + +[bool](class_bool.md) **outline** = `false` [🔗](#class_CharFXTransform_property_outline) + + + +- `void` **set_outline**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_outline**\ (\ ) + +If ``true``, FX transform is called for outline drawing. + +\ **Note:** Read-only. Setting this property won't affect drawing. + +
+ + + + + +[Vector2i](class_vector2i.md) **range** = `Vector2i(0, 0)` [🔗](#class_CharFXTransform_property_range) + + + +- `void` **set_range**\ (\ value\: [Vector2i](class_vector2i.md)\ ) +- [Vector2i](class_vector2i.md) **get_range**\ (\ ) + +Absolute character range in the string, corresponding to the glyph. + +\ **Note:** Read-only. Setting this property won't affect drawing. + +
+ + + + + +[int](class_int.md) **relative_index** = `0` [🔗](#class_CharFXTransform_property_relative_index) + + + +- `void` **set_relative_index**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_relative_index**\ (\ ) + +The character offset of the glyph, relative to the current [RichTextEffect](class_richtexteffect.md) custom block. + +\ **Note:** Read-only. Setting this property won't affect drawing. + +
+ + + + + +[Transform2D](class_transform2d.md) **transform** = `Transform2D(1, 0, 0, 1, 0, 0)` [🔗](#class_CharFXTransform_property_transform) + + + +- `void` **set_transform**\ (\ value\: [Transform2D](class_transform2d.md)\ ) +- [Transform2D](class_transform2d.md) **get_transform**\ (\ ) + +The current transform of the current glyph. It can be overridden (for example, by driving the position and rotation from a curve). You can also alter the existing value to apply transforms on top of other effects. + +
+ + + + + +[bool](class_bool.md) **visible** = `true` [🔗](#class_CharFXTransform_property_visible) + + + +- `void` **set_visibility**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_visible**\ (\ ) + +If ``true``, the character will be drawn. If ``false``, the character will be hidden. Characters around hidden characters will reflow to take the space of hidden characters. If this is not desired, set their [color](class_charfxtransform.md#class_CharFXTransform_property_color) to ``Color(1, 1, 1, 0)`` instead. + diff --git a/docs/Classes/class_checkbox.md b/docs/Classes/class_checkbox.md new file mode 100644 index 00000000..d919afc4 --- /dev/null +++ b/docs/Classes/class_checkbox.md @@ -0,0 +1,226 @@ + + + + + + + + + +# CheckBox + +**Inherits:** [Button](class_button.md) **<** [BaseButton](class_basebutton.md) **<** [Control](class_control.md) **<** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +A button that represents a binary choice. + + + +## Description + +**CheckBox** allows the user to choose one of only two possible options. It's similar to [CheckButton](class_checkbutton.md) in functionality, but it has a different appearance. To follow established UX patterns, it's recommended to use **CheckBox** when toggling it has **no** immediate effect on something. For example, it could be used when toggling it will only do something once a confirmation button is pressed. + +See also [BaseButton](class_basebutton.md) which contains common properties and methods associated with this node. + +When [BaseButton.button_group](class_basebutton.md#class_BaseButton_property_button_group) specifies a [ButtonGroup](class_buttongroup.md), **CheckBox** changes its appearance to that of a radio button and uses the various ``radio_*`` theme properties. + + + +## Properties + + + + + + + + + + + + + + + + +
[HorizontalAlignment](class_@globalscope.md#enum_@GlobalScope_HorizontalAlignment)alignment`0` (overrides [Button.alignment](class_button.md#class_Button_property_alignment))
[bool](class_bool.md)toggle_mode`true` (overrides [BaseButton.toggle_mode](class_basebutton.md#class_BaseButton_property_toggle_mode))
+ + + +## Theme Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Color](class_color.md)[checkbox_checked_color](#class_CheckBox_theme_color_checkbox_checked_color)`Color(1, 1, 1, 1)`
[Color](class_color.md)[checkbox_unchecked_color](#class_CheckBox_theme_color_checkbox_unchecked_color)`Color(1, 1, 1, 1)`
[int](class_int.md)[check_v_offset](#class_CheckBox_theme_constant_check_v_offset)`0`
[Texture2D](class_texture2d.md)[checked](#class_CheckBox_theme_icon_checked)
[Texture2D](class_texture2d.md)[checked_disabled](#class_CheckBox_theme_icon_checked_disabled)
[Texture2D](class_texture2d.md)[radio_checked](#class_CheckBox_theme_icon_radio_checked)
[Texture2D](class_texture2d.md)[radio_checked_disabled](#class_CheckBox_theme_icon_radio_checked_disabled)
[Texture2D](class_texture2d.md)[radio_unchecked](#class_CheckBox_theme_icon_radio_unchecked)
[Texture2D](class_texture2d.md)[radio_unchecked_disabled](#class_CheckBox_theme_icon_radio_unchecked_disabled)
[Texture2D](class_texture2d.md)[unchecked](#class_CheckBox_theme_icon_unchecked)
[Texture2D](class_texture2d.md)[unchecked_disabled](#class_CheckBox_theme_icon_unchecked_disabled)
+ +
+ + + +## Theme Property Descriptions + + + + + +[Color](class_color.md) **checkbox_checked_color** = `Color(1, 1, 1, 1)` [🔗](#class_CheckBox_theme_color_checkbox_checked_color) + +The color of the checked icon when the checkbox is pressed. + +
+ + + + + +[Color](class_color.md) **checkbox_unchecked_color** = `Color(1, 1, 1, 1)` [🔗](#class_CheckBox_theme_color_checkbox_unchecked_color) + +The color of the unchecked icon when the checkbox is not pressed. + +
+ + + + + +[int](class_int.md) **check_v_offset** = `0` [🔗](#class_CheckBox_theme_constant_check_v_offset) + +The vertical offset used when rendering the check icons (in pixels). + +
+ + + + + +[Texture2D](class_texture2d.md) **checked** [🔗](#class_CheckBox_theme_icon_checked) + +The check icon to display when the **CheckBox** is checked. + +
+ + + + + +[Texture2D](class_texture2d.md) **checked_disabled** [🔗](#class_CheckBox_theme_icon_checked_disabled) + +The check icon to display when the **CheckBox** is checked and is disabled. + +
+ + + + + +[Texture2D](class_texture2d.md) **radio_checked** [🔗](#class_CheckBox_theme_icon_radio_checked) + +The check icon to display when the **CheckBox** is configured as a radio button and is checked. + +
+ + + + + +[Texture2D](class_texture2d.md) **radio_checked_disabled** [🔗](#class_CheckBox_theme_icon_radio_checked_disabled) + +The check icon to display when the **CheckBox** is configured as a radio button, is disabled, and is unchecked. + +
+ + + + + +[Texture2D](class_texture2d.md) **radio_unchecked** [🔗](#class_CheckBox_theme_icon_radio_unchecked) + +The check icon to display when the **CheckBox** is configured as a radio button and is unchecked. + +
+ + + + + +[Texture2D](class_texture2d.md) **radio_unchecked_disabled** [🔗](#class_CheckBox_theme_icon_radio_unchecked_disabled) + +The check icon to display when the **CheckBox** is configured as a radio button, is disabled, and is unchecked. + +
+ + + + + +[Texture2D](class_texture2d.md) **unchecked** [🔗](#class_CheckBox_theme_icon_unchecked) + +The check icon to display when the **CheckBox** is unchecked. + +
+ + + + + +[Texture2D](class_texture2d.md) **unchecked_disabled** [🔗](#class_CheckBox_theme_icon_unchecked_disabled) + +The check icon to display when the **CheckBox** is unchecked and is disabled. + diff --git a/docs/Classes/class_checkbutton.md b/docs/Classes/class_checkbutton.md new file mode 100644 index 00000000..cc456642 --- /dev/null +++ b/docs/Classes/class_checkbutton.md @@ -0,0 +1,226 @@ + + + + + + + + + + + +# CheckButton + +**Inherits:** [Button](class_button.md) **<** [BaseButton](class_basebutton.md) **<** [Control](class_control.md) **<** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +A button that represents a binary choice. + + + +## Description + +**CheckButton** is a toggle button displayed as a check field. It's similar to [CheckBox](class_checkbox.md) in functionality, but it has a different appearance. To follow established UX patterns, it's recommended to use **CheckButton** when toggling it has an **immediate** effect on something. For example, it can be used when pressing it shows or hides advanced settings, without asking the user to confirm this action. + +See also [BaseButton](class_basebutton.md) which contains common properties and methods associated with this node. + + + +## Properties + + + + + + + + + + + + + + + + +
[HorizontalAlignment](class_@globalscope.md#enum_@GlobalScope_HorizontalAlignment)alignment`0` (overrides [Button.alignment](class_button.md#class_Button_property_alignment))
[bool](class_bool.md)toggle_mode`true` (overrides [BaseButton.toggle_mode](class_basebutton.md#class_BaseButton_property_toggle_mode))
+ + + +## Theme Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Color](class_color.md)[button_checked_color](#class_CheckButton_theme_color_button_checked_color)`Color(1, 1, 1, 1)`
[Color](class_color.md)[button_unchecked_color](#class_CheckButton_theme_color_button_unchecked_color)`Color(1, 1, 1, 1)`
[int](class_int.md)[check_v_offset](#class_CheckButton_theme_constant_check_v_offset)`0`
[Texture2D](class_texture2d.md)[checked](#class_CheckButton_theme_icon_checked)
[Texture2D](class_texture2d.md)[checked_disabled](#class_CheckButton_theme_icon_checked_disabled)
[Texture2D](class_texture2d.md)[checked_disabled_mirrored](#class_CheckButton_theme_icon_checked_disabled_mirrored)
[Texture2D](class_texture2d.md)[checked_mirrored](#class_CheckButton_theme_icon_checked_mirrored)
[Texture2D](class_texture2d.md)[unchecked](#class_CheckButton_theme_icon_unchecked)
[Texture2D](class_texture2d.md)[unchecked_disabled](#class_CheckButton_theme_icon_unchecked_disabled)
[Texture2D](class_texture2d.md)[unchecked_disabled_mirrored](#class_CheckButton_theme_icon_unchecked_disabled_mirrored)
[Texture2D](class_texture2d.md)[unchecked_mirrored](#class_CheckButton_theme_icon_unchecked_mirrored)
+ +
+ + + +## Theme Property Descriptions + + + + + +[Color](class_color.md) **button_checked_color** = `Color(1, 1, 1, 1)` [🔗](#class_CheckButton_theme_color_button_checked_color) + +The color of the checked icon when the checkbox is pressed. + +
+ + + + + +[Color](class_color.md) **button_unchecked_color** = `Color(1, 1, 1, 1)` [🔗](#class_CheckButton_theme_color_button_unchecked_color) + +The color of the unchecked icon when the checkbox is not pressed. + +
+ + + + + +[int](class_int.md) **check_v_offset** = `0` [🔗](#class_CheckButton_theme_constant_check_v_offset) + +The vertical offset used when rendering the toggle icons (in pixels). + +
+ + + + + +[Texture2D](class_texture2d.md) **checked** [🔗](#class_CheckButton_theme_icon_checked) + +The icon to display when the **CheckButton** is checked (for left-to-right layouts). + +
+ + + + + +[Texture2D](class_texture2d.md) **checked_disabled** [🔗](#class_CheckButton_theme_icon_checked_disabled) + +The icon to display when the **CheckButton** is checked and disabled (for left-to-right layouts). + +
+ + + + + +[Texture2D](class_texture2d.md) **checked_disabled_mirrored** [🔗](#class_CheckButton_theme_icon_checked_disabled_mirrored) + +The icon to display when the **CheckButton** is checked and disabled (for right-to-left layouts). + +
+ + + + + +[Texture2D](class_texture2d.md) **checked_mirrored** [🔗](#class_CheckButton_theme_icon_checked_mirrored) + +The icon to display when the **CheckButton** is checked (for right-to-left layouts). + +
+ + + + + +[Texture2D](class_texture2d.md) **unchecked** [🔗](#class_CheckButton_theme_icon_unchecked) + +The icon to display when the **CheckButton** is unchecked (for left-to-right layouts). + +
+ + + + + +[Texture2D](class_texture2d.md) **unchecked_disabled** [🔗](#class_CheckButton_theme_icon_unchecked_disabled) + +The icon to display when the **CheckButton** is unchecked and disabled (for left-to-right layouts). + +
+ + + + + +[Texture2D](class_texture2d.md) **unchecked_disabled_mirrored** [🔗](#class_CheckButton_theme_icon_unchecked_disabled_mirrored) + +The icon to display when the **CheckButton** is unchecked and disabled (for right-to-left layouts). + +
+ + + + + +[Texture2D](class_texture2d.md) **unchecked_mirrored** [🔗](#class_CheckButton_theme_icon_unchecked_mirrored) + +The icon to display when the **CheckButton** is unchecked (for right-to-left layouts). + diff --git a/docs/Classes/class_circleshape2d.md b/docs/Classes/class_circleshape2d.md new file mode 100644 index 00000000..296bd735 --- /dev/null +++ b/docs/Classes/class_circleshape2d.md @@ -0,0 +1,58 @@ + + + + + + + + + +# CircleShape2D + +**Inherits:** [Shape2D](class_shape2d.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +A 2D circle shape used for physics collision. + + + +## Description + +A 2D circle shape, intended for use in physics. Usually used to provide a shape for a [CollisionShape2D](class_collisionshape2d.md). + +\ **Performance:** **CircleShape2D** is fast to check collisions against. It is faster than [RectangleShape2D](class_rectangleshape2d.md) and [CapsuleShape2D](class_capsuleshape2d.md). + + + +## Properties + + + + + + + + + + + +
[float](class_float.md)[radius](#class_CircleShape2D_property_radius)`10.0`
+ +
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **radius** = `10.0` [🔗](#class_CircleShape2D_property_radius) + + + +- `void` **set_radius**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_radius**\ (\ ) + +The circle's radius. + diff --git a/docs/Classes/class_classdb.md b/docs/Classes/class_classdb.md new file mode 100644 index 00000000..56e9fdfe --- /dev/null +++ b/docs/Classes/class_classdb.md @@ -0,0 +1,550 @@ + + + + + + + + + +# ClassDB + +**Inherits:** [Object](class_object.md) + +A class information repository. + + + +## Description + +Provides access to metadata stored for every available engine class. + +\ **Note:** Script-defined classes with ``class_name`` are not part of **ClassDB**, so they will not return reflection data such as a method or property list. However, [GDExtension](class_gdextension.md)-defined classes *are* part of **ClassDB**, so they will return reflection data. + + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[can_instantiate](#class_ClassDB_method_can_instantiate)\ (\ class\: [StringName](class_stringname.md)\ ) const
[Variant](class_variant.md)[class_call_static](#class_ClassDB_method_class_call_static)\ (\ class\: [StringName](class_stringname.md), method\: [StringName](class_stringname.md), ...\ ) vararg
[bool](class_bool.md)[class_exists](#class_ClassDB_method_class_exists)\ (\ class\: [StringName](class_stringname.md)\ ) const
[APIType](class_classdb.md#enum_ClassDB_APIType)[class_get_api_type](#class_ClassDB_method_class_get_api_type)\ (\ class\: [StringName](class_stringname.md)\ ) const
[PackedStringArray](class_packedstringarray.md)[class_get_enum_constants](#class_ClassDB_method_class_get_enum_constants)\ (\ class\: [StringName](class_stringname.md), enum\: [StringName](class_stringname.md), no_inheritance\: [bool](class_bool.md) = false\ ) const
[PackedStringArray](class_packedstringarray.md)[class_get_enum_list](#class_ClassDB_method_class_get_enum_list)\ (\ class\: [StringName](class_stringname.md), no_inheritance\: [bool](class_bool.md) = false\ ) const
[int](class_int.md)[class_get_integer_constant](#class_ClassDB_method_class_get_integer_constant)\ (\ class\: [StringName](class_stringname.md), name\: [StringName](class_stringname.md)\ ) const
[StringName](class_stringname.md)[class_get_integer_constant_enum](#class_ClassDB_method_class_get_integer_constant_enum)\ (\ class\: [StringName](class_stringname.md), name\: [StringName](class_stringname.md), no_inheritance\: [bool](class_bool.md) = false\ ) const
[PackedStringArray](class_packedstringarray.md)[class_get_integer_constant_list](#class_ClassDB_method_class_get_integer_constant_list)\ (\ class\: [StringName](class_stringname.md), no_inheritance\: [bool](class_bool.md) = false\ ) const
[int](class_int.md)[class_get_method_argument_count](#class_ClassDB_method_class_get_method_argument_count)\ (\ class\: [StringName](class_stringname.md), method\: [StringName](class_stringname.md), no_inheritance\: [bool](class_bool.md) = false\ ) const
[Array](class_array.md)\[[Dictionary](class_dictionary.md)\][class_get_method_list](#class_ClassDB_method_class_get_method_list)\ (\ class\: [StringName](class_stringname.md), no_inheritance\: [bool](class_bool.md) = false\ ) const
[Variant](class_variant.md)[class_get_property](#class_ClassDB_method_class_get_property)\ (\ object\: [Object](class_object.md), property\: [StringName](class_stringname.md)\ ) const
[Variant](class_variant.md)[class_get_property_default_value](#class_ClassDB_method_class_get_property_default_value)\ (\ class\: [StringName](class_stringname.md), property\: [StringName](class_stringname.md)\ ) const
[StringName](class_stringname.md)[class_get_property_getter](#class_ClassDB_method_class_get_property_getter)\ (\ class\: [StringName](class_stringname.md), property\: [StringName](class_stringname.md)\ )
[Array](class_array.md)\[[Dictionary](class_dictionary.md)\][class_get_property_list](#class_ClassDB_method_class_get_property_list)\ (\ class\: [StringName](class_stringname.md), no_inheritance\: [bool](class_bool.md) = false\ ) const
[StringName](class_stringname.md)[class_get_property_setter](#class_ClassDB_method_class_get_property_setter)\ (\ class\: [StringName](class_stringname.md), property\: [StringName](class_stringname.md)\ )
[Dictionary](class_dictionary.md)[class_get_signal](#class_ClassDB_method_class_get_signal)\ (\ class\: [StringName](class_stringname.md), signal\: [StringName](class_stringname.md)\ ) const
[Array](class_array.md)\[[Dictionary](class_dictionary.md)\][class_get_signal_list](#class_ClassDB_method_class_get_signal_list)\ (\ class\: [StringName](class_stringname.md), no_inheritance\: [bool](class_bool.md) = false\ ) const
[bool](class_bool.md)[class_has_enum](#class_ClassDB_method_class_has_enum)\ (\ class\: [StringName](class_stringname.md), name\: [StringName](class_stringname.md), no_inheritance\: [bool](class_bool.md) = false\ ) const
[bool](class_bool.md)[class_has_integer_constant](#class_ClassDB_method_class_has_integer_constant)\ (\ class\: [StringName](class_stringname.md), name\: [StringName](class_stringname.md)\ ) const
[bool](class_bool.md)[class_has_method](#class_ClassDB_method_class_has_method)\ (\ class\: [StringName](class_stringname.md), method\: [StringName](class_stringname.md), no_inheritance\: [bool](class_bool.md) = false\ ) const
[bool](class_bool.md)[class_has_signal](#class_ClassDB_method_class_has_signal)\ (\ class\: [StringName](class_stringname.md), signal\: [StringName](class_stringname.md)\ ) const
[Error](class_@globalscope.md#enum_@GlobalScope_Error)[class_override_api_type](#class_ClassDB_method_class_override_api_type)\ (\ class\: [StringName](class_stringname.md), api\: [APIType](class_classdb.md#enum_ClassDB_APIType)\ ) const
[Error](class_@globalscope.md#enum_@GlobalScope_Error)[class_set_property](#class_ClassDB_method_class_set_property)\ (\ object\: [Object](class_object.md), property\: [StringName](class_stringname.md), value\: [Variant](class_variant.md)\ ) const
[PackedStringArray](class_packedstringarray.md)[get_class_list](#class_ClassDB_method_get_class_list)\ (\ ) const
[APIType](class_classdb.md#enum_ClassDB_APIType)[get_current_api](#class_ClassDB_method_get_current_api)\ (\ ) const
[PackedStringArray](class_packedstringarray.md)[get_inheriters_from_class](#class_ClassDB_method_get_inheriters_from_class)\ (\ class\: [StringName](class_stringname.md)\ ) const
[StringName](class_stringname.md)[get_parent_class](#class_ClassDB_method_get_parent_class)\ (\ class\: [StringName](class_stringname.md)\ ) const
[Variant](class_variant.md)[instantiate](#class_ClassDB_method_instantiate)\ (\ class\: [StringName](class_stringname.md)\ ) const
[bool](class_bool.md)[is_class_enabled](#class_ClassDB_method_is_class_enabled)\ (\ class\: [StringName](class_stringname.md)\ ) const
[bool](class_bool.md)[is_class_enum_bitfield](#class_ClassDB_method_is_class_enum_bitfield)\ (\ class\: [StringName](class_stringname.md), enum\: [StringName](class_stringname.md), no_inheritance\: [bool](class_bool.md) = false\ ) const
[bool](class_bool.md)[is_parent_class](#class_ClassDB_method_is_parent_class)\ (\ class\: [StringName](class_stringname.md), inherits\: [StringName](class_stringname.md)\ ) const
`void`[set_current_api](#class_ClassDB_method_set_current_api)\ (\ api\: [APIType](class_classdb.md#enum_ClassDB_APIType)\ ) const
+ +
+ + + +## Enumerations + + + + + +enum **APIType**: [🔗](#enum_ClassDB_APIType) + + + + + +[APIType](class_classdb.md#enum_ClassDB_APIType) **API_CORE** = `0` + +Native Core class type. + + + +[APIType](class_classdb.md#enum_ClassDB_APIType) **API_EDITOR** = `1` + +Native Editor class type. + + + +[APIType](class_classdb.md#enum_ClassDB_APIType) **API_EXTENSION** = `2` + +GDExtension class type. + + + +[APIType](class_classdb.md#enum_ClassDB_APIType) **API_EDITOR_EXTENSION** = `3` + +GDExtension Editor class type. + + + +[APIType](class_classdb.md#enum_ClassDB_APIType) **API_NONE** = `4` + +Unknown class type.
+ + + +## Method Descriptions + + + + + +[bool](class_bool.md) **can_instantiate**\ (\ class\: [StringName](class_stringname.md)\ ) const [🔗](#class_ClassDB_method_can_instantiate) + +Returns ``true`` if objects can be instantiated from the specified `class`, otherwise returns ``false``. + +
+ + + + + +[Variant](class_variant.md) **class_call_static**\ (\ class\: [StringName](class_stringname.md), method\: [StringName](class_stringname.md), ...\ ) vararg [🔗](#class_ClassDB_method_class_call_static) + +Calls a static method on a class. + +
+ + + + + +[bool](class_bool.md) **class_exists**\ (\ class\: [StringName](class_stringname.md)\ ) const [🔗](#class_ClassDB_method_class_exists) + +Returns whether the specified `class` is available or not. + +
+ + + + + +[APIType](class_classdb.md#enum_ClassDB_APIType) **class_get_api_type**\ (\ class\: [StringName](class_stringname.md)\ ) const [🔗](#class_ClassDB_method_class_get_api_type) + +Returns the API type of the specified `class`. + +
+ + + + + +[PackedStringArray](class_packedstringarray.md) **class_get_enum_constants**\ (\ class\: [StringName](class_stringname.md), enum\: [StringName](class_stringname.md), no_inheritance\: [bool](class_bool.md) = false\ ) const [🔗](#class_ClassDB_method_class_get_enum_constants) + +Returns an array with all the keys in `enum` of `class` or its ancestry. + +
+ + + + + +[PackedStringArray](class_packedstringarray.md) **class_get_enum_list**\ (\ class\: [StringName](class_stringname.md), no_inheritance\: [bool](class_bool.md) = false\ ) const [🔗](#class_ClassDB_method_class_get_enum_list) + +Returns an array with all the enums of `class` or its ancestry. + +
+ + + + + +[int](class_int.md) **class_get_integer_constant**\ (\ class\: [StringName](class_stringname.md), name\: [StringName](class_stringname.md)\ ) const [🔗](#class_ClassDB_method_class_get_integer_constant) + +Returns the value of the integer constant `name` of `class` or its ancestry. Always returns 0 when the constant could not be found. + +
+ + + + + +[StringName](class_stringname.md) **class_get_integer_constant_enum**\ (\ class\: [StringName](class_stringname.md), name\: [StringName](class_stringname.md), no_inheritance\: [bool](class_bool.md) = false\ ) const [🔗](#class_ClassDB_method_class_get_integer_constant_enum) + +Returns which enum the integer constant `name` of `class` or its ancestry belongs to. + +
+ + + + + +[PackedStringArray](class_packedstringarray.md) **class_get_integer_constant_list**\ (\ class\: [StringName](class_stringname.md), no_inheritance\: [bool](class_bool.md) = false\ ) const [🔗](#class_ClassDB_method_class_get_integer_constant_list) + +Returns an array with the names all the integer constants of `class` or its ancestry. + +
+ + + + + +[int](class_int.md) **class_get_method_argument_count**\ (\ class\: [StringName](class_stringname.md), method\: [StringName](class_stringname.md), no_inheritance\: [bool](class_bool.md) = false\ ) const [🔗](#class_ClassDB_method_class_get_method_argument_count) + +Returns the number of arguments of the method `method` of `class` or its ancestry if `no_inheritance` is ``false``. + +
+ + + + + +[Array](class_array.md)\[[Dictionary](class_dictionary.md)\] **class_get_method_list**\ (\ class\: [StringName](class_stringname.md), no_inheritance\: [bool](class_bool.md) = false\ ) const [🔗](#class_ClassDB_method_class_get_method_list) + +Returns an array with all the methods of `class` or its ancestry if `no_inheritance` is ``false``. Every element of the array is a [Dictionary](class_dictionary.md) with the following keys: ``args``, ``default_args``, ``flags``, ``id``, ``name``, ``return: (class_name, hint, hint_string, name, type, usage)``. + +\ **Note:** In exported release builds the debug info is not available, so the returned dictionaries will contain only method names. + +
+ + + + + +[Variant](class_variant.md) **class_get_property**\ (\ object\: [Object](class_object.md), property\: [StringName](class_stringname.md)\ ) const [🔗](#class_ClassDB_method_class_get_property) + +Returns the value of `property` of `object` or its ancestry. + +
+ + + + + +[Variant](class_variant.md) **class_get_property_default_value**\ (\ class\: [StringName](class_stringname.md), property\: [StringName](class_stringname.md)\ ) const [🔗](#class_ClassDB_method_class_get_property_default_value) + +Returns the default value of `property` of `class` or its ancestor classes. + +
+ + + + + +[StringName](class_stringname.md) **class_get_property_getter**\ (\ class\: [StringName](class_stringname.md), property\: [StringName](class_stringname.md)\ ) [🔗](#class_ClassDB_method_class_get_property_getter) + +Returns the getter method name of `property` of `class`. + +
+ + + + + +[Array](class_array.md)\[[Dictionary](class_dictionary.md)\] **class_get_property_list**\ (\ class\: [StringName](class_stringname.md), no_inheritance\: [bool](class_bool.md) = false\ ) const [🔗](#class_ClassDB_method_class_get_property_list) + +Returns an array with all the properties of `class` or its ancestry if `no_inheritance` is ``false``. + +
+ + + + + +[StringName](class_stringname.md) **class_get_property_setter**\ (\ class\: [StringName](class_stringname.md), property\: [StringName](class_stringname.md)\ ) [🔗](#class_ClassDB_method_class_get_property_setter) + +Returns the setter method name of `property` of `class`. + +
+ + + + + +[Dictionary](class_dictionary.md) **class_get_signal**\ (\ class\: [StringName](class_stringname.md), signal\: [StringName](class_stringname.md)\ ) const [🔗](#class_ClassDB_method_class_get_signal) + +Returns the `signal` data of `class` or its ancestry. The returned value is a [Dictionary](class_dictionary.md) with the following keys: ``args``, ``default_args``, ``flags``, ``id``, ``name``, ``return: (class_name, hint, hint_string, name, type, usage)``. + +
+ + + + + +[Array](class_array.md)\[[Dictionary](class_dictionary.md)\] **class_get_signal_list**\ (\ class\: [StringName](class_stringname.md), no_inheritance\: [bool](class_bool.md) = false\ ) const [🔗](#class_ClassDB_method_class_get_signal_list) + +Returns an array with all the signals of `class` or its ancestry if `no_inheritance` is ``false``. Every element of the array is a [Dictionary](class_dictionary.md) as described in [class_get_signal()](class_classdb.md#class_ClassDB_method_class_get_signal). + +
+ + + + + +[bool](class_bool.md) **class_has_enum**\ (\ class\: [StringName](class_stringname.md), name\: [StringName](class_stringname.md), no_inheritance\: [bool](class_bool.md) = false\ ) const [🔗](#class_ClassDB_method_class_has_enum) + +Returns whether `class` or its ancestry has an enum called `name` or not. + +
+ + + + + +[bool](class_bool.md) **class_has_integer_constant**\ (\ class\: [StringName](class_stringname.md), name\: [StringName](class_stringname.md)\ ) const [🔗](#class_ClassDB_method_class_has_integer_constant) + +Returns whether `class` or its ancestry has an integer constant called `name` or not. + +
+ + + + + +[bool](class_bool.md) **class_has_method**\ (\ class\: [StringName](class_stringname.md), method\: [StringName](class_stringname.md), no_inheritance\: [bool](class_bool.md) = false\ ) const [🔗](#class_ClassDB_method_class_has_method) + +Returns whether `class` (or its ancestry if `no_inheritance` is ``false``) has a method called `method` or not. + +
+ + + + + +[bool](class_bool.md) **class_has_signal**\ (\ class\: [StringName](class_stringname.md), signal\: [StringName](class_stringname.md)\ ) const [🔗](#class_ClassDB_method_class_has_signal) + +Returns whether `class` or its ancestry has a signal called `signal` or not. + +
+ + + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **class_override_api_type**\ (\ class\: [StringName](class_stringname.md), api\: [APIType](class_classdb.md#enum_ClassDB_APIType)\ ) const [🔗](#class_ClassDB_method_class_override_api_type) + +Overrides the API type of `class` to `api`. See [APIType](class_classdb.md#enum_ClassDB_APIType). + +\ **Note:** This should only be used with a thorough understanding of its implications. + +
+ + + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **class_set_property**\ (\ object\: [Object](class_object.md), property\: [StringName](class_stringname.md), value\: [Variant](class_variant.md)\ ) const [🔗](#class_ClassDB_method_class_set_property) + +Sets `property` value of `object` to `value`. + +
+ + + + + +[PackedStringArray](class_packedstringarray.md) **get_class_list**\ (\ ) const [🔗](#class_ClassDB_method_get_class_list) + +Returns the names of all engine classes available. + +\ **Note:** Script-defined classes with ``class_name`` are not included in this list. Use [ProjectSettings.get_global_class_list()](class_projectsettings.md#class_ProjectSettings_method_get_global_class_list) to get a list of script-defined classes instead. + +
+ + + + + +[APIType](class_classdb.md#enum_ClassDB_APIType) **get_current_api**\ (\ ) const [🔗](#class_ClassDB_method_get_current_api) + +Returns the currently active API type. See [APIType](class_classdb.md#enum_ClassDB_APIType). + +
+ + + + + +[PackedStringArray](class_packedstringarray.md) **get_inheriters_from_class**\ (\ class\: [StringName](class_stringname.md)\ ) const [🔗](#class_ClassDB_method_get_inheriters_from_class) + +Returns the names of all engine classes that directly or indirectly inherit from `class`. + +
+ + + + + +[StringName](class_stringname.md) **get_parent_class**\ (\ class\: [StringName](class_stringname.md)\ ) const [🔗](#class_ClassDB_method_get_parent_class) + +Returns the parent class of `class`. + +
+ + + + + +[Variant](class_variant.md) **instantiate**\ (\ class\: [StringName](class_stringname.md)\ ) const [🔗](#class_ClassDB_method_instantiate) + +Creates an instance of `class`. + +
+ + + + + +[bool](class_bool.md) **is_class_enabled**\ (\ class\: [StringName](class_stringname.md)\ ) const [🔗](#class_ClassDB_method_is_class_enabled) + +Returns whether this `class` is enabled or not. + +
+ + + + + +[bool](class_bool.md) **is_class_enum_bitfield**\ (\ class\: [StringName](class_stringname.md), enum\: [StringName](class_stringname.md), no_inheritance\: [bool](class_bool.md) = false\ ) const [🔗](#class_ClassDB_method_is_class_enum_bitfield) + +Returns whether `class` (or its ancestor classes if `no_inheritance` is ``false``) has an enum called `enum` that is a bitfield. + +
+ + + + + +[bool](class_bool.md) **is_parent_class**\ (\ class\: [StringName](class_stringname.md), inherits\: [StringName](class_stringname.md)\ ) const [🔗](#class_ClassDB_method_is_parent_class) + +Returns whether `inherits` is an ancestor of `class` or not. + +
+ + + + + +`void` **set_current_api**\ (\ api\: [APIType](class_classdb.md#enum_ClassDB_APIType)\ ) const [🔗](#class_ClassDB_method_set_current_api) + +Sets the globally active API type to `api`. See [APIType](class_classdb.md#enum_ClassDB_APIType). + +\ **Note:** This should only be used with a thorough understanding of its implications. + diff --git a/docs/Classes/class_codeedit.md b/docs/Classes/class_codeedit.md new file mode 100644 index 00000000..30dedde8 --- /dev/null +++ b/docs/Classes/class_codeedit.md @@ -0,0 +1,2092 @@ + + + + + + + + + +# CodeEdit + +**Inherits:** [TextEdit](class_textedit.md) **<** [Control](class_control.md) **<** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +A multiline text editor designed for editing code. + + + +## Description + +CodeEdit is a specialized [TextEdit](class_textedit.md) designed for editing plain text code files. It has many features commonly found in code editors such as line numbers, line folding, code completion, indent management, and string/comment management. + +\ **Note:** Regardless of locale, **CodeEdit** will by default always use left-to-right text direction to correctly display source code. + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[auto_brace_completion_enabled](#class_CodeEdit_property_auto_brace_completion_enabled)`false`
[bool](class_bool.md)[auto_brace_completion_highlight_matching](#class_CodeEdit_property_auto_brace_completion_highlight_matching)`false`
[Dictionary](class_dictionary.md)[auto_brace_completion_pairs](#class_CodeEdit_property_auto_brace_completion_pairs)`{ "\"": "\"", "'": "'", "(": ")", "[": "]", "{": "}" }`
[bool](class_bool.md)[code_completion_enabled](#class_CodeEdit_property_code_completion_enabled)`false`
[Array](class_array.md)\[[String](class_string.md)\][code_completion_prefixes](#class_CodeEdit_property_code_completion_prefixes)`[]`
[Array](class_array.md)\[[String](class_string.md)\][delimiter_comments](#class_CodeEdit_property_delimiter_comments)`[]`
[Array](class_array.md)\[[String](class_string.md)\][delimiter_strings](#class_CodeEdit_property_delimiter_strings)`["' '", "\" \""]`
[bool](class_bool.md)[gutters_draw_bookmarks](#class_CodeEdit_property_gutters_draw_bookmarks)`false`
[bool](class_bool.md)[gutters_draw_breakpoints_gutter](#class_CodeEdit_property_gutters_draw_breakpoints_gutter)`false`
[bool](class_bool.md)[gutters_draw_executing_lines](#class_CodeEdit_property_gutters_draw_executing_lines)`false`
[bool](class_bool.md)[gutters_draw_fold_gutter](#class_CodeEdit_property_gutters_draw_fold_gutter)`false`
[bool](class_bool.md)[gutters_draw_line_numbers](#class_CodeEdit_property_gutters_draw_line_numbers)`false`
[bool](class_bool.md)[gutters_zero_pad_line_numbers](#class_CodeEdit_property_gutters_zero_pad_line_numbers)`false`
[bool](class_bool.md)[indent_automatic](#class_CodeEdit_property_indent_automatic)`false`
[Array](class_array.md)\[[String](class_string.md)\][indent_automatic_prefixes](#class_CodeEdit_property_indent_automatic_prefixes)`[":", "{", "[", "("]`
[int](class_int.md)[indent_size](#class_CodeEdit_property_indent_size)`4`
[bool](class_bool.md)[indent_use_spaces](#class_CodeEdit_property_indent_use_spaces)`false`
[LayoutDirection](class_control.md#enum_Control_LayoutDirection)layout_direction`2` (overrides [Control.layout_direction](class_control.md#class_Control_property_layout_direction))
[bool](class_bool.md)[line_folding](#class_CodeEdit_property_line_folding)`false`
[Array](class_array.md)\[[int](class_int.md)\][line_length_guidelines](#class_CodeEdit_property_line_length_guidelines)`[]`
[bool](class_bool.md)[symbol_lookup_on_click](#class_CodeEdit_property_symbol_lookup_on_click)`false`
[bool](class_bool.md)[symbol_tooltip_on_hover](#class_CodeEdit_property_symbol_tooltip_on_hover)`false`
[TextDirection](class_control.md#enum_Control_TextDirection)text_direction`1` (overrides [TextEdit.text_direction](class_textedit.md#class_TextEdit_property_text_direction))
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
`void`[_confirm_code_completion](#class_CodeEdit_private_method__confirm_code_completion)\ (\ replace\: [bool](class_bool.md)\ ) virtual
[Array](class_array.md)\[[Dictionary](class_dictionary.md)\][_filter_code_completion_candidates](#class_CodeEdit_private_method__filter_code_completion_candidates)\ (\ candidates\: [Array](class_array.md)\[[Dictionary](class_dictionary.md)\]\ ) virtual const
`void`[_request_code_completion](#class_CodeEdit_private_method__request_code_completion)\ (\ force\: [bool](class_bool.md)\ ) virtual
`void`[add_auto_brace_completion_pair](#class_CodeEdit_method_add_auto_brace_completion_pair)\ (\ start_key\: [String](class_string.md), end_key\: [String](class_string.md)\ )
`void`[add_code_completion_option](#class_CodeEdit_method_add_code_completion_option)\ (\ type\: [CodeCompletionKind](class_codeedit.md#enum_CodeEdit_CodeCompletionKind), display_text\: [String](class_string.md), insert_text\: [String](class_string.md), text_color\: [Color](class_color.md) = Color(1, 1, 1, 1), icon\: [Resource](class_resource.md) = null, value\: [Variant](class_variant.md) = null, location\: [int](class_int.md) = 1024\ )
`void`[add_comment_delimiter](#class_CodeEdit_method_add_comment_delimiter)\ (\ start_key\: [String](class_string.md), end_key\: [String](class_string.md), line_only\: [bool](class_bool.md) = false\ )
`void`[add_string_delimiter](#class_CodeEdit_method_add_string_delimiter)\ (\ start_key\: [String](class_string.md), end_key\: [String](class_string.md), line_only\: [bool](class_bool.md) = false\ )
[bool](class_bool.md)[can_fold_line](#class_CodeEdit_method_can_fold_line)\ (\ line\: [int](class_int.md)\ ) const
`void`[cancel_code_completion](#class_CodeEdit_method_cancel_code_completion)\ (\ )
`void`[clear_bookmarked_lines](#class_CodeEdit_method_clear_bookmarked_lines)\ (\ )
`void`[clear_breakpointed_lines](#class_CodeEdit_method_clear_breakpointed_lines)\ (\ )
`void`[clear_comment_delimiters](#class_CodeEdit_method_clear_comment_delimiters)\ (\ )
`void`[clear_executing_lines](#class_CodeEdit_method_clear_executing_lines)\ (\ )
`void`[clear_string_delimiters](#class_CodeEdit_method_clear_string_delimiters)\ (\ )
`void`[confirm_code_completion](#class_CodeEdit_method_confirm_code_completion)\ (\ replace\: [bool](class_bool.md) = false\ )
`void`[convert_indent](#class_CodeEdit_method_convert_indent)\ (\ from_line\: [int](class_int.md) = -1, to_line\: [int](class_int.md) = -1\ )
`void`[create_code_region](#class_CodeEdit_method_create_code_region)\ (\ )
`void`[delete_lines](#class_CodeEdit_method_delete_lines)\ (\ )
`void`[do_indent](#class_CodeEdit_method_do_indent)\ (\ )
`void`[duplicate_lines](#class_CodeEdit_method_duplicate_lines)\ (\ )
`void`[duplicate_selection](#class_CodeEdit_method_duplicate_selection)\ (\ )
`void`[fold_all_lines](#class_CodeEdit_method_fold_all_lines)\ (\ )
`void`[fold_line](#class_CodeEdit_method_fold_line)\ (\ line\: [int](class_int.md)\ )
[String](class_string.md)[get_auto_brace_completion_close_key](#class_CodeEdit_method_get_auto_brace_completion_close_key)\ (\ open_key\: [String](class_string.md)\ ) const
[PackedInt32Array](class_packedint32array.md)[get_bookmarked_lines](#class_CodeEdit_method_get_bookmarked_lines)\ (\ ) const
[PackedInt32Array](class_packedint32array.md)[get_breakpointed_lines](#class_CodeEdit_method_get_breakpointed_lines)\ (\ ) const
[Dictionary](class_dictionary.md)[get_code_completion_option](#class_CodeEdit_method_get_code_completion_option)\ (\ index\: [int](class_int.md)\ ) const
[Array](class_array.md)\[[Dictionary](class_dictionary.md)\][get_code_completion_options](#class_CodeEdit_method_get_code_completion_options)\ (\ ) const
[int](class_int.md)[get_code_completion_selected_index](#class_CodeEdit_method_get_code_completion_selected_index)\ (\ ) const
[String](class_string.md)[get_code_region_end_tag](#class_CodeEdit_method_get_code_region_end_tag)\ (\ ) const
[String](class_string.md)[get_code_region_start_tag](#class_CodeEdit_method_get_code_region_start_tag)\ (\ ) const
[String](class_string.md)[get_delimiter_end_key](#class_CodeEdit_method_get_delimiter_end_key)\ (\ delimiter_index\: [int](class_int.md)\ ) const
[Vector2](class_vector2.md)[get_delimiter_end_position](#class_CodeEdit_method_get_delimiter_end_position)\ (\ line\: [int](class_int.md), column\: [int](class_int.md)\ ) const
[String](class_string.md)[get_delimiter_start_key](#class_CodeEdit_method_get_delimiter_start_key)\ (\ delimiter_index\: [int](class_int.md)\ ) const
[Vector2](class_vector2.md)[get_delimiter_start_position](#class_CodeEdit_method_get_delimiter_start_position)\ (\ line\: [int](class_int.md), column\: [int](class_int.md)\ ) const
[PackedInt32Array](class_packedint32array.md)[get_executing_lines](#class_CodeEdit_method_get_executing_lines)\ (\ ) const
[Array](class_array.md)\[[int](class_int.md)\][get_folded_lines](#class_CodeEdit_method_get_folded_lines)\ (\ ) const
[String](class_string.md)[get_text_for_code_completion](#class_CodeEdit_method_get_text_for_code_completion)\ (\ ) const
[String](class_string.md)[get_text_for_symbol_lookup](#class_CodeEdit_method_get_text_for_symbol_lookup)\ (\ ) const
[String](class_string.md)[get_text_with_cursor_char](#class_CodeEdit_method_get_text_with_cursor_char)\ (\ line\: [int](class_int.md), column\: [int](class_int.md)\ ) const
[bool](class_bool.md)[has_auto_brace_completion_close_key](#class_CodeEdit_method_has_auto_brace_completion_close_key)\ (\ close_key\: [String](class_string.md)\ ) const
[bool](class_bool.md)[has_auto_brace_completion_open_key](#class_CodeEdit_method_has_auto_brace_completion_open_key)\ (\ open_key\: [String](class_string.md)\ ) const
[bool](class_bool.md)[has_comment_delimiter](#class_CodeEdit_method_has_comment_delimiter)\ (\ start_key\: [String](class_string.md)\ ) const
[bool](class_bool.md)[has_string_delimiter](#class_CodeEdit_method_has_string_delimiter)\ (\ start_key\: [String](class_string.md)\ ) const
`void`[indent_lines](#class_CodeEdit_method_indent_lines)\ (\ )
[int](class_int.md)[is_in_comment](#class_CodeEdit_method_is_in_comment)\ (\ line\: [int](class_int.md), column\: [int](class_int.md) = -1\ ) const
[int](class_int.md)[is_in_string](#class_CodeEdit_method_is_in_string)\ (\ line\: [int](class_int.md), column\: [int](class_int.md) = -1\ ) const
[bool](class_bool.md)[is_line_bookmarked](#class_CodeEdit_method_is_line_bookmarked)\ (\ line\: [int](class_int.md)\ ) const
[bool](class_bool.md)[is_line_breakpointed](#class_CodeEdit_method_is_line_breakpointed)\ (\ line\: [int](class_int.md)\ ) const
[bool](class_bool.md)[is_line_code_region_end](#class_CodeEdit_method_is_line_code_region_end)\ (\ line\: [int](class_int.md)\ ) const
[bool](class_bool.md)[is_line_code_region_start](#class_CodeEdit_method_is_line_code_region_start)\ (\ line\: [int](class_int.md)\ ) const
[bool](class_bool.md)[is_line_executing](#class_CodeEdit_method_is_line_executing)\ (\ line\: [int](class_int.md)\ ) const
[bool](class_bool.md)[is_line_folded](#class_CodeEdit_method_is_line_folded)\ (\ line\: [int](class_int.md)\ ) const
`void`[move_lines_down](#class_CodeEdit_method_move_lines_down)\ (\ )
`void`[move_lines_up](#class_CodeEdit_method_move_lines_up)\ (\ )
`void`[remove_comment_delimiter](#class_CodeEdit_method_remove_comment_delimiter)\ (\ start_key\: [String](class_string.md)\ )
`void`[remove_string_delimiter](#class_CodeEdit_method_remove_string_delimiter)\ (\ start_key\: [String](class_string.md)\ )
`void`[request_code_completion](#class_CodeEdit_method_request_code_completion)\ (\ force\: [bool](class_bool.md) = false\ )
`void`[set_code_completion_selected_index](#class_CodeEdit_method_set_code_completion_selected_index)\ (\ index\: [int](class_int.md)\ )
`void`[set_code_hint](#class_CodeEdit_method_set_code_hint)\ (\ code_hint\: [String](class_string.md)\ )
`void`[set_code_hint_draw_below](#class_CodeEdit_method_set_code_hint_draw_below)\ (\ draw_below\: [bool](class_bool.md)\ )
`void`[set_code_region_tags](#class_CodeEdit_method_set_code_region_tags)\ (\ start\: [String](class_string.md) = "region", end\: [String](class_string.md) = "endregion"\ )
`void`[set_line_as_bookmarked](#class_CodeEdit_method_set_line_as_bookmarked)\ (\ line\: [int](class_int.md), bookmarked\: [bool](class_bool.md)\ )
`void`[set_line_as_breakpoint](#class_CodeEdit_method_set_line_as_breakpoint)\ (\ line\: [int](class_int.md), breakpointed\: [bool](class_bool.md)\ )
`void`[set_line_as_executing](#class_CodeEdit_method_set_line_as_executing)\ (\ line\: [int](class_int.md), executing\: [bool](class_bool.md)\ )
`void`[set_symbol_lookup_word_as_valid](#class_CodeEdit_method_set_symbol_lookup_word_as_valid)\ (\ valid\: [bool](class_bool.md)\ )
`void`[toggle_foldable_line](#class_CodeEdit_method_toggle_foldable_line)\ (\ line\: [int](class_int.md)\ )
`void`[toggle_foldable_lines_at_carets](#class_CodeEdit_method_toggle_foldable_lines_at_carets)\ (\ )
`void`[unfold_all_lines](#class_CodeEdit_method_unfold_all_lines)\ (\ )
`void`[unfold_line](#class_CodeEdit_method_unfold_line)\ (\ line\: [int](class_int.md)\ )
`void`[unindent_lines](#class_CodeEdit_method_unindent_lines)\ (\ )
`void`[update_code_completion_options](#class_CodeEdit_method_update_code_completion_options)\ (\ force\: [bool](class_bool.md)\ )
+ + + +## Theme Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Color](class_color.md)[bookmark_color](#class_CodeEdit_theme_color_bookmark_color)`Color(0.5, 0.64, 1, 0.8)`
[Color](class_color.md)[brace_mismatch_color](#class_CodeEdit_theme_color_brace_mismatch_color)`Color(1, 0.2, 0.2, 1)`
[Color](class_color.md)[breakpoint_color](#class_CodeEdit_theme_color_breakpoint_color)`Color(0.9, 0.29, 0.3, 1)`
[Color](class_color.md)[code_folding_color](#class_CodeEdit_theme_color_code_folding_color)`Color(0.8, 0.8, 0.8, 0.8)`
[Color](class_color.md)[completion_background_color](#class_CodeEdit_theme_color_completion_background_color)`Color(0.17, 0.16, 0.2, 1)`
[Color](class_color.md)[completion_existing_color](#class_CodeEdit_theme_color_completion_existing_color)`Color(0.87, 0.87, 0.87, 0.13)`
[Color](class_color.md)[completion_scroll_color](#class_CodeEdit_theme_color_completion_scroll_color)`Color(1, 1, 1, 0.29)`
[Color](class_color.md)[completion_scroll_hovered_color](#class_CodeEdit_theme_color_completion_scroll_hovered_color)`Color(1, 1, 1, 0.4)`
[Color](class_color.md)[completion_selected_color](#class_CodeEdit_theme_color_completion_selected_color)`Color(0.26, 0.26, 0.27, 1)`
[Color](class_color.md)[executing_line_color](#class_CodeEdit_theme_color_executing_line_color)`Color(0.98, 0.89, 0.27, 1)`
[Color](class_color.md)[folded_code_region_color](#class_CodeEdit_theme_color_folded_code_region_color)`Color(0.68, 0.46, 0.77, 0.2)`
[Color](class_color.md)[line_length_guideline_color](#class_CodeEdit_theme_color_line_length_guideline_color)`Color(0.3, 0.5, 0.8, 0.1)`
[Color](class_color.md)[line_number_color](#class_CodeEdit_theme_color_line_number_color)`Color(0.67, 0.67, 0.67, 0.4)`
[int](class_int.md)[completion_lines](#class_CodeEdit_theme_constant_completion_lines)`7`
[int](class_int.md)[completion_max_width](#class_CodeEdit_theme_constant_completion_max_width)`50`
[int](class_int.md)[completion_scroll_width](#class_CodeEdit_theme_constant_completion_scroll_width)`6`
[Texture2D](class_texture2d.md)[bookmark](#class_CodeEdit_theme_icon_bookmark)
[Texture2D](class_texture2d.md)[breakpoint](#class_CodeEdit_theme_icon_breakpoint)
[Texture2D](class_texture2d.md)[can_fold](#class_CodeEdit_theme_icon_can_fold)
[Texture2D](class_texture2d.md)[can_fold_code_region](#class_CodeEdit_theme_icon_can_fold_code_region)
[Texture2D](class_texture2d.md)[completion_color_bg](#class_CodeEdit_theme_icon_completion_color_bg)
[Texture2D](class_texture2d.md)[executing_line](#class_CodeEdit_theme_icon_executing_line)
[Texture2D](class_texture2d.md)[folded](#class_CodeEdit_theme_icon_folded)
[Texture2D](class_texture2d.md)[folded_code_region](#class_CodeEdit_theme_icon_folded_code_region)
[Texture2D](class_texture2d.md)[folded_eol_icon](#class_CodeEdit_theme_icon_folded_eol_icon)
[StyleBox](class_stylebox.md)[completion](#class_CodeEdit_theme_style_completion)
+ +
+ + + +## Signals + + + + + +**breakpoint_toggled**\ (\ line\: [int](class_int.md)\ ) [🔗](#class_CodeEdit_signal_breakpoint_toggled) + +Emitted when a breakpoint is added or removed from a line. If the line is removed via backspace, a signal is emitted at the old line. + +
+ + + + + +**code_completion_requested**\ (\ ) [🔗](#class_CodeEdit_signal_code_completion_requested) + +Emitted when the user requests code completion. This signal will not be sent if [_request_code_completion()](class_codeedit.md#class_CodeEdit_private_method__request_code_completion) is overridden or [code_completion_enabled](class_codeedit.md#class_CodeEdit_property_code_completion_enabled) is ``false``. + +
+ + + + + +**symbol_hovered**\ (\ symbol\: [String](class_string.md), line\: [int](class_int.md), column\: [int](class_int.md)\ ) [🔗](#class_CodeEdit_signal_symbol_hovered) + +Emitted when the user hovers over a symbol. Unlike [Control.mouse_entered](class_control.md#class_Control_signal_mouse_entered), this signal is not emitted immediately, but when the cursor is over the symbol for [ProjectSettings.gui/timers/tooltip_delay_sec](class_projectsettings.md#class_ProjectSettings_property_gui/timers/tooltip_delay_sec) seconds. + +\ **Note:** [symbol_tooltip_on_hover](class_codeedit.md#class_CodeEdit_property_symbol_tooltip_on_hover) must be ``true`` for this signal to be emitted. + +
+ + + + + +**symbol_lookup**\ (\ symbol\: [String](class_string.md), line\: [int](class_int.md), column\: [int](class_int.md)\ ) [🔗](#class_CodeEdit_signal_symbol_lookup) + +Emitted when the user has clicked on a valid symbol. + +
+ + + + + +**symbol_validate**\ (\ symbol\: [String](class_string.md)\ ) [🔗](#class_CodeEdit_signal_symbol_validate) + +Emitted when the user hovers over a symbol. The symbol should be validated and responded to, by calling [set_symbol_lookup_word_as_valid()](class_codeedit.md#class_CodeEdit_method_set_symbol_lookup_word_as_valid). + +\ **Note:** [symbol_lookup_on_click](class_codeedit.md#class_CodeEdit_property_symbol_lookup_on_click) must be ``true`` for this signal to be emitted. + +
+ + + +## Enumerations + + + + + +enum **CodeCompletionKind**: [🔗](#enum_CodeEdit_CodeCompletionKind) + + + + + +[CodeCompletionKind](class_codeedit.md#enum_CodeEdit_CodeCompletionKind) **KIND_CLASS** = `0` + +Marks the option as a class. + + + +[CodeCompletionKind](class_codeedit.md#enum_CodeEdit_CodeCompletionKind) **KIND_FUNCTION** = `1` + +Marks the option as a function. + + + +[CodeCompletionKind](class_codeedit.md#enum_CodeEdit_CodeCompletionKind) **KIND_SIGNAL** = `2` + +Marks the option as a Redot signal. + + + +[CodeCompletionKind](class_codeedit.md#enum_CodeEdit_CodeCompletionKind) **KIND_VARIABLE** = `3` + +Marks the option as a variable. + + + +[CodeCompletionKind](class_codeedit.md#enum_CodeEdit_CodeCompletionKind) **KIND_MEMBER** = `4` + +Marks the option as a member. + + + +[CodeCompletionKind](class_codeedit.md#enum_CodeEdit_CodeCompletionKind) **KIND_ENUM** = `5` + +Marks the option as an enum entry. + + + +[CodeCompletionKind](class_codeedit.md#enum_CodeEdit_CodeCompletionKind) **KIND_CONSTANT** = `6` + +Marks the option as a constant. + + + +[CodeCompletionKind](class_codeedit.md#enum_CodeEdit_CodeCompletionKind) **KIND_NODE_PATH** = `7` + +Marks the option as a Redot node path. + + + +[CodeCompletionKind](class_codeedit.md#enum_CodeEdit_CodeCompletionKind) **KIND_FILE_PATH** = `8` + +Marks the option as a file path. + + + +[CodeCompletionKind](class_codeedit.md#enum_CodeEdit_CodeCompletionKind) **KIND_PLAIN_TEXT** = `9` + +Marks the option as unclassified or plain text.
+ + + + + +enum **CodeCompletionLocation**: [🔗](#enum_CodeEdit_CodeCompletionLocation) + + + + + +[CodeCompletionLocation](class_codeedit.md#enum_CodeEdit_CodeCompletionLocation) **LOCATION_LOCAL** = `0` + +The option is local to the location of the code completion query - e.g. a local variable. Subsequent value of location represent options from the outer class, the exact value represent how far they are (in terms of inner classes). + + + +[CodeCompletionLocation](class_codeedit.md#enum_CodeEdit_CodeCompletionLocation) **LOCATION_PARENT_MASK** = `256` + +The option is from the containing class or a parent class, relative to the location of the code completion query. Perform a bitwise OR with the class depth (e.g. ``0`` for the local class, ``1`` for the parent, ``2`` for the grandparent, etc.) to store the depth of an option in the class or a parent class. + + + +[CodeCompletionLocation](class_codeedit.md#enum_CodeEdit_CodeCompletionLocation) **LOCATION_OTHER_USER_CODE** = `512` + +The option is from user code which is not local and not in a derived class (e.g. Autoload Singletons). + + + +[CodeCompletionLocation](class_codeedit.md#enum_CodeEdit_CodeCompletionLocation) **LOCATION_OTHER** = `1024` + +The option is from other engine code, not covered by the other enum constants - e.g. built-in classes.
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **auto_brace_completion_enabled** = `false` [🔗](#class_CodeEdit_property_auto_brace_completion_enabled) + + + +- `void` **set_auto_brace_completion_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_auto_brace_completion_enabled**\ (\ ) + +If ``true``, uses [auto_brace_completion_pairs](class_codeedit.md#class_CodeEdit_property_auto_brace_completion_pairs) to automatically insert the closing brace when the opening brace is inserted by typing or autocompletion. Also automatically removes the closing brace when using backspace on the opening brace. + +
+ + + + + +[bool](class_bool.md) **auto_brace_completion_highlight_matching** = `false` [🔗](#class_CodeEdit_property_auto_brace_completion_highlight_matching) + + + +- `void` **set_highlight_matching_braces_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_highlight_matching_braces_enabled**\ (\ ) + +If ``true``, highlights brace pairs when the caret is on either one, using [auto_brace_completion_pairs](class_codeedit.md#class_CodeEdit_property_auto_brace_completion_pairs). If matching, the pairs will be underlined. If a brace is unmatched, it is colored with [brace_mismatch_color](class_codeedit.md#class_CodeEdit_theme_color_brace_mismatch_color). + +
+ + + + + +[Dictionary](class_dictionary.md) **auto_brace_completion_pairs** = `{ "\"": "\"", "'": "'", "(": ")", "[": "]", "{": "}" }` [🔗](#class_CodeEdit_property_auto_brace_completion_pairs) + + + +- `void` **set_auto_brace_completion_pairs**\ (\ value\: [Dictionary](class_dictionary.md)\ ) +- [Dictionary](class_dictionary.md) **get_auto_brace_completion_pairs**\ (\ ) + +Sets the brace pairs to be autocompleted. For each entry in the dictionary, the key is the opening brace and the value is the closing brace that matches it. A brace is a [String](class_string.md) made of symbols. See [auto_brace_completion_enabled](class_codeedit.md#class_CodeEdit_property_auto_brace_completion_enabled) and [auto_brace_completion_highlight_matching](class_codeedit.md#class_CodeEdit_property_auto_brace_completion_highlight_matching). + +
+ + + + + +[bool](class_bool.md) **code_completion_enabled** = `false` [🔗](#class_CodeEdit_property_code_completion_enabled) + + + +- `void` **set_code_completion_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_code_completion_enabled**\ (\ ) + +If ``true``, the [ProjectSettings.input/ui_text_completion_query](class_projectsettings.md#class_ProjectSettings_property_input/ui_text_completion_query) action requests code completion. To handle it, see [_request_code_completion()](class_codeedit.md#class_CodeEdit_private_method__request_code_completion) or [code_completion_requested](class_codeedit.md#class_CodeEdit_signal_code_completion_requested). + +
+ + + + + +[Array](class_array.md)\[[String](class_string.md)\] **code_completion_prefixes** = `[]` [🔗](#class_CodeEdit_property_code_completion_prefixes) + + + +- `void` **set_code_completion_prefixes**\ (\ value\: [Array](class_array.md)\[[String](class_string.md)\]\ ) +- [Array](class_array.md)\[[String](class_string.md)\] **get_code_completion_prefixes**\ (\ ) + +Sets prefixes that will trigger code completion. + +
+ + + + + +[Array](class_array.md)\[[String](class_string.md)\] **delimiter_comments** = `[]` [🔗](#class_CodeEdit_property_delimiter_comments) + + + +- `void` **set_comment_delimiters**\ (\ value\: [Array](class_array.md)\[[String](class_string.md)\]\ ) +- [Array](class_array.md)\[[String](class_string.md)\] **get_comment_delimiters**\ (\ ) + +Sets the comment delimiters. All existing comment delimiters will be removed. + +
+ + + + + +[Array](class_array.md)\[[String](class_string.md)\] **delimiter_strings** = `["' '", "\" \""]` [🔗](#class_CodeEdit_property_delimiter_strings) + + + +- `void` **set_string_delimiters**\ (\ value\: [Array](class_array.md)\[[String](class_string.md)\]\ ) +- [Array](class_array.md)\[[String](class_string.md)\] **get_string_delimiters**\ (\ ) + +Sets the string delimiters. All existing string delimiters will be removed. + +
+ + + + + +[bool](class_bool.md) **gutters_draw_bookmarks** = `false` [🔗](#class_CodeEdit_property_gutters_draw_bookmarks) + + + +- `void` **set_draw_bookmarks_gutter**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_drawing_bookmarks_gutter**\ (\ ) + +If ``true``, bookmarks are drawn in the gutter. This gutter is shared with breakpoints and executing lines. See [set_line_as_bookmarked()](class_codeedit.md#class_CodeEdit_method_set_line_as_bookmarked). + +
+ + + + + +[bool](class_bool.md) **gutters_draw_breakpoints_gutter** = `false` [🔗](#class_CodeEdit_property_gutters_draw_breakpoints_gutter) + + + +- `void` **set_draw_breakpoints_gutter**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_drawing_breakpoints_gutter**\ (\ ) + +If ``true``, breakpoints are drawn in the gutter. This gutter is shared with bookmarks and executing lines. Clicking the gutter will toggle the breakpoint for the line, see [set_line_as_breakpoint()](class_codeedit.md#class_CodeEdit_method_set_line_as_breakpoint). + +
+ + + + + +[bool](class_bool.md) **gutters_draw_executing_lines** = `false` [🔗](#class_CodeEdit_property_gutters_draw_executing_lines) + + + +- `void` **set_draw_executing_lines_gutter**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_drawing_executing_lines_gutter**\ (\ ) + +If ``true``, executing lines are marked in the gutter. This gutter is shared with breakpoints and bookmarks. See [set_line_as_executing()](class_codeedit.md#class_CodeEdit_method_set_line_as_executing). + +
+ + + + + +[bool](class_bool.md) **gutters_draw_fold_gutter** = `false` [🔗](#class_CodeEdit_property_gutters_draw_fold_gutter) + + + +- `void` **set_draw_fold_gutter**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_drawing_fold_gutter**\ (\ ) + +If ``true``, the fold gutter is drawn. In this gutter, the [can_fold_code_region](class_codeedit.md#class_CodeEdit_theme_icon_can_fold_code_region) icon is drawn for each foldable line (see [can_fold_line()](class_codeedit.md#class_CodeEdit_method_can_fold_line)) and the [folded_code_region](class_codeedit.md#class_CodeEdit_theme_icon_folded_code_region) icon is drawn for each folded line (see [is_line_folded()](class_codeedit.md#class_CodeEdit_method_is_line_folded)). These icons can be clicked to toggle the fold state, see [toggle_foldable_line()](class_codeedit.md#class_CodeEdit_method_toggle_foldable_line). [line_folding](class_codeedit.md#class_CodeEdit_property_line_folding) must be ``true`` to show icons. + +
+ + + + + +[bool](class_bool.md) **gutters_draw_line_numbers** = `false` [🔗](#class_CodeEdit_property_gutters_draw_line_numbers) + + + +- `void` **set_draw_line_numbers**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_draw_line_numbers_enabled**\ (\ ) + +If ``true``, the line number gutter is drawn. Line numbers start at ``1`` and are incremented for each line of text. Clicking and dragging in the line number gutter will select entire lines of text. + +
+ + + + + +[bool](class_bool.md) **gutters_zero_pad_line_numbers** = `false` [🔗](#class_CodeEdit_property_gutters_zero_pad_line_numbers) + + + +- `void` **set_line_numbers_zero_padded**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_line_numbers_zero_padded**\ (\ ) + +If ``true``, line numbers drawn in the gutter are zero padded based on the total line count. Requires [gutters_draw_line_numbers](class_codeedit.md#class_CodeEdit_property_gutters_draw_line_numbers) to be set to ``true``. + +
+ + + + + +[bool](class_bool.md) **indent_automatic** = `false` [🔗](#class_CodeEdit_property_indent_automatic) + + + +- `void` **set_auto_indent_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_auto_indent_enabled**\ (\ ) + +If ``true``, an extra indent is automatically inserted when a new line is added and a prefix in [indent_automatic_prefixes](class_codeedit.md#class_CodeEdit_property_indent_automatic_prefixes) is found. If a brace pair opening key is found, the matching closing brace will be moved to another new line (see [auto_brace_completion_pairs](class_codeedit.md#class_CodeEdit_property_auto_brace_completion_pairs)). + +
+ + + + + +[Array](class_array.md)\[[String](class_string.md)\] **indent_automatic_prefixes** = `[":", "{", "[", "("]` [🔗](#class_CodeEdit_property_indent_automatic_prefixes) + + + +- `void` **set_auto_indent_prefixes**\ (\ value\: [Array](class_array.md)\[[String](class_string.md)\]\ ) +- [Array](class_array.md)\[[String](class_string.md)\] **get_auto_indent_prefixes**\ (\ ) + +Prefixes to trigger an automatic indent. Used when [indent_automatic](class_codeedit.md#class_CodeEdit_property_indent_automatic) is set to ``true``. + +
+ + + + + +[int](class_int.md) **indent_size** = `4` [🔗](#class_CodeEdit_property_indent_size) + + + +- `void` **set_indent_size**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_indent_size**\ (\ ) + +Size of the tabulation indent (one :kbd:`Tab` press) in characters. If [indent_use_spaces](class_codeedit.md#class_CodeEdit_property_indent_use_spaces) is enabled the number of spaces to use. + +
+ + + + + +[bool](class_bool.md) **indent_use_spaces** = `false` [🔗](#class_CodeEdit_property_indent_use_spaces) + + + +- `void` **set_indent_using_spaces**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_indent_using_spaces**\ (\ ) + +Use spaces instead of tabs for indentation. + +
+ + + + + +[bool](class_bool.md) **line_folding** = `false` [🔗](#class_CodeEdit_property_line_folding) + + + +- `void` **set_line_folding_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_line_folding_enabled**\ (\ ) + +If ``true``, lines can be folded. Otherwise, line folding methods like [fold_line()](class_codeedit.md#class_CodeEdit_method_fold_line) will not work and [can_fold_line()](class_codeedit.md#class_CodeEdit_method_can_fold_line) will always return ``false``. See [gutters_draw_fold_gutter](class_codeedit.md#class_CodeEdit_property_gutters_draw_fold_gutter). + +
+ + + + + +[Array](class_array.md)\[[int](class_int.md)\] **line_length_guidelines** = `[]` [🔗](#class_CodeEdit_property_line_length_guidelines) + + + +- `void` **set_line_length_guidelines**\ (\ value\: [Array](class_array.md)\[[int](class_int.md)\]\ ) +- [Array](class_array.md)\[[int](class_int.md)\] **get_line_length_guidelines**\ (\ ) + +Draws vertical lines at the provided columns. The first entry is considered a main hard guideline and is drawn more prominently. + +
+ + + + + +[bool](class_bool.md) **symbol_lookup_on_click** = `false` [🔗](#class_CodeEdit_property_symbol_lookup_on_click) + + + +- `void` **set_symbol_lookup_on_click_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_symbol_lookup_on_click_enabled**\ (\ ) + +Set when a validated word from [symbol_validate](class_codeedit.md#class_CodeEdit_signal_symbol_validate) is clicked, the [symbol_lookup](class_codeedit.md#class_CodeEdit_signal_symbol_lookup) should be emitted. + +
+ + + + + +[bool](class_bool.md) **symbol_tooltip_on_hover** = `false` [🔗](#class_CodeEdit_property_symbol_tooltip_on_hover) + + + +- `void` **set_symbol_tooltip_on_hover_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_symbol_tooltip_on_hover_enabled**\ (\ ) + +If ``true``, the [symbol_hovered](class_codeedit.md#class_CodeEdit_signal_symbol_hovered) signal is emitted when hovering over a word. + +
+ + + +## Method Descriptions + + + + + +`void` **_confirm_code_completion**\ (\ replace\: [bool](class_bool.md)\ ) virtual [🔗](#class_CodeEdit_private_method__confirm_code_completion) + +Override this method to define how the selected entry should be inserted. If `replace` is ``true``, any existing text should be replaced. + +
+ + + + + +[Array](class_array.md)\[[Dictionary](class_dictionary.md)\] **_filter_code_completion_candidates**\ (\ candidates\: [Array](class_array.md)\[[Dictionary](class_dictionary.md)\]\ ) virtual const [🔗](#class_CodeEdit_private_method__filter_code_completion_candidates) + +Override this method to define what items in `candidates` should be displayed. + +Both `candidates` and the return is an [Array](class_array.md) of [Dictionary](class_dictionary.md), see [get_code_completion_option()](class_codeedit.md#class_CodeEdit_method_get_code_completion_option) for [Dictionary](class_dictionary.md) content. + +
+ + + + + +`void` **_request_code_completion**\ (\ force\: [bool](class_bool.md)\ ) virtual [🔗](#class_CodeEdit_private_method__request_code_completion) + +Override this method to define what happens when the user requests code completion. If `force` is ``true``, any checks should be bypassed. + +
+ + + + + +`void` **add_auto_brace_completion_pair**\ (\ start_key\: [String](class_string.md), end_key\: [String](class_string.md)\ ) [🔗](#class_CodeEdit_method_add_auto_brace_completion_pair) + +Adds a brace pair. + +Both the start and end keys must be symbols. Only the start key has to be unique. + +
+ + + + + +`void` **add_code_completion_option**\ (\ type\: [CodeCompletionKind](class_codeedit.md#enum_CodeEdit_CodeCompletionKind), display_text\: [String](class_string.md), insert_text\: [String](class_string.md), text_color\: [Color](class_color.md) = Color(1, 1, 1, 1), icon\: [Resource](class_resource.md) = null, value\: [Variant](class_variant.md) = null, location\: [int](class_int.md) = 1024\ ) [🔗](#class_CodeEdit_method_add_code_completion_option) + +Submits an item to the queue of potential candidates for the autocomplete menu. Call [update_code_completion_options()](class_codeedit.md#class_CodeEdit_method_update_code_completion_options) to update the list. + +\ `location` indicates location of the option relative to the location of the code completion query. See [CodeCompletionLocation](class_codeedit.md#enum_CodeEdit_CodeCompletionLocation) for how to set this value. + +\ **Note:** This list will replace all current candidates. + +
+ + + + + +`void` **add_comment_delimiter**\ (\ start_key\: [String](class_string.md), end_key\: [String](class_string.md), line_only\: [bool](class_bool.md) = false\ ) [🔗](#class_CodeEdit_method_add_comment_delimiter) + +Adds a comment delimiter from `start_key` to `end_key`. Both keys should be symbols, and `start_key` must not be shared with other delimiters. + +If `line_only` is ``true`` or `end_key` is an empty [String](class_string.md), the region does not carry over to the next line. + +
+ + + + + +`void` **add_string_delimiter**\ (\ start_key\: [String](class_string.md), end_key\: [String](class_string.md), line_only\: [bool](class_bool.md) = false\ ) [🔗](#class_CodeEdit_method_add_string_delimiter) + +Defines a string delimiter from `start_key` to `end_key`. Both keys should be symbols, and `start_key` must not be shared with other delimiters. + +If `line_only` is ``true`` or `end_key` is an empty [String](class_string.md), the region does not carry over to the next line. + +
+ + + + + +[bool](class_bool.md) **can_fold_line**\ (\ line\: [int](class_int.md)\ ) const [🔗](#class_CodeEdit_method_can_fold_line) + +Returns ``true`` if the given line is foldable. A line is foldable if it is the start of a valid code region (see [get_code_region_start_tag()](class_codeedit.md#class_CodeEdit_method_get_code_region_start_tag)), if it is the start of a comment or string block, or if the next non-empty line is more indented (see [TextEdit.get_indent_level()](class_textedit.md#class_TextEdit_method_get_indent_level)). + +
+ + + + + +`void` **cancel_code_completion**\ (\ ) [🔗](#class_CodeEdit_method_cancel_code_completion) + +Cancels the autocomplete menu. + +
+ + + + + +`void` **clear_bookmarked_lines**\ (\ ) [🔗](#class_CodeEdit_method_clear_bookmarked_lines) + +Clears all bookmarked lines. + +
+ + + + + +`void` **clear_breakpointed_lines**\ (\ ) [🔗](#class_CodeEdit_method_clear_breakpointed_lines) + +Clears all breakpointed lines. + +
+ + + + + +`void` **clear_comment_delimiters**\ (\ ) [🔗](#class_CodeEdit_method_clear_comment_delimiters) + +Removes all comment delimiters. + +
+ + + + + +`void` **clear_executing_lines**\ (\ ) [🔗](#class_CodeEdit_method_clear_executing_lines) + +Clears all executed lines. + +
+ + + + + +`void` **clear_string_delimiters**\ (\ ) [🔗](#class_CodeEdit_method_clear_string_delimiters) + +Removes all string delimiters. + +
+ + + + + +`void` **confirm_code_completion**\ (\ replace\: [bool](class_bool.md) = false\ ) [🔗](#class_CodeEdit_method_confirm_code_completion) + +Inserts the selected entry into the text. If `replace` is ``true``, any existing text is replaced rather than merged. + +
+ + + + + +`void` **convert_indent**\ (\ from_line\: [int](class_int.md) = -1, to_line\: [int](class_int.md) = -1\ ) [🔗](#class_CodeEdit_method_convert_indent) + +Converts the indents of lines between `from_line` and `to_line` to tabs or spaces as set by [indent_use_spaces](class_codeedit.md#class_CodeEdit_property_indent_use_spaces). + +Values of ``-1`` convert the entire text. + +
+ + + + + +`void` **create_code_region**\ (\ ) [🔗](#class_CodeEdit_method_create_code_region) + +Creates a new code region with the selection. At least one single line comment delimiter have to be defined (see [add_comment_delimiter()](class_codeedit.md#class_CodeEdit_method_add_comment_delimiter)). + +A code region is a part of code that is highlighted when folded and can help organize your script. + +Code region start and end tags can be customized (see [set_code_region_tags()](class_codeedit.md#class_CodeEdit_method_set_code_region_tags)). + +Code regions are delimited using start and end tags (respectively ``region`` and ``endregion`` by default) preceded by one line comment delimiter. (eg. ``#region`` and ``#endregion``) + +
+ + + + + +`void` **delete_lines**\ (\ ) [🔗](#class_CodeEdit_method_delete_lines) + +Deletes all lines that are selected or have a caret on them. + +
+ + + + + +`void` **do_indent**\ (\ ) [🔗](#class_CodeEdit_method_do_indent) + +If there is no selection, indentation is inserted at the caret. Otherwise, the selected lines are indented like [indent_lines()](class_codeedit.md#class_CodeEdit_method_indent_lines). Equivalent to the [ProjectSettings.input/ui_text_indent](class_projectsettings.md#class_ProjectSettings_property_input/ui_text_indent) action. The indentation characters used depend on [indent_use_spaces](class_codeedit.md#class_CodeEdit_property_indent_use_spaces) and [indent_size](class_codeedit.md#class_CodeEdit_property_indent_size). + +
+ + + + + +`void` **duplicate_lines**\ (\ ) [🔗](#class_CodeEdit_method_duplicate_lines) + +Duplicates all lines currently selected with any caret. Duplicates the entire line beneath the current one no matter where the caret is within the line. + +
+ + + + + +`void` **duplicate_selection**\ (\ ) [🔗](#class_CodeEdit_method_duplicate_selection) + +Duplicates all selected text and duplicates all lines with a caret on them. + +
+ + + + + +`void` **fold_all_lines**\ (\ ) [🔗](#class_CodeEdit_method_fold_all_lines) + +Folds all lines that are possible to be folded (see [can_fold_line()](class_codeedit.md#class_CodeEdit_method_can_fold_line)). + +
+ + + + + +`void` **fold_line**\ (\ line\: [int](class_int.md)\ ) [🔗](#class_CodeEdit_method_fold_line) + +Folds the given line, if possible (see [can_fold_line()](class_codeedit.md#class_CodeEdit_method_can_fold_line)). + +
+ + + + + +[String](class_string.md) **get_auto_brace_completion_close_key**\ (\ open_key\: [String](class_string.md)\ ) const [🔗](#class_CodeEdit_method_get_auto_brace_completion_close_key) + +Gets the matching auto brace close key for `open_key`. + +
+ + + + + +[PackedInt32Array](class_packedint32array.md) **get_bookmarked_lines**\ (\ ) const [🔗](#class_CodeEdit_method_get_bookmarked_lines) + +Gets all bookmarked lines. + +
+ + + + + +[PackedInt32Array](class_packedint32array.md) **get_breakpointed_lines**\ (\ ) const [🔗](#class_CodeEdit_method_get_breakpointed_lines) + +Gets all breakpointed lines. + +
+ + + + + +[Dictionary](class_dictionary.md) **get_code_completion_option**\ (\ index\: [int](class_int.md)\ ) const [🔗](#class_CodeEdit_method_get_code_completion_option) + +Gets the completion option at `index`. The return [Dictionary](class_dictionary.md) has the following key-values: + +\ ``kind``: [CodeCompletionKind](class_codeedit.md#enum_CodeEdit_CodeCompletionKind)\ + +\ ``display_text``: Text that is shown on the autocomplete menu. + +\ ``insert_text``: Text that is to be inserted when this item is selected. + +\ ``font_color``: Color of the text on the autocomplete menu. + +\ ``icon``: Icon to draw on the autocomplete menu. + +\ ``default_value``: Value of the symbol. + +
+ + + + + +[Array](class_array.md)\[[Dictionary](class_dictionary.md)\] **get_code_completion_options**\ (\ ) const [🔗](#class_CodeEdit_method_get_code_completion_options) + +Gets all completion options, see [get_code_completion_option()](class_codeedit.md#class_CodeEdit_method_get_code_completion_option) for return content. + +
+ + + + + +[int](class_int.md) **get_code_completion_selected_index**\ (\ ) const [🔗](#class_CodeEdit_method_get_code_completion_selected_index) + +Gets the index of the current selected completion option. + +
+ + + + + +[String](class_string.md) **get_code_region_end_tag**\ (\ ) const [🔗](#class_CodeEdit_method_get_code_region_end_tag) + +Returns the code region end tag (without comment delimiter). + +
+ + + + + +[String](class_string.md) **get_code_region_start_tag**\ (\ ) const [🔗](#class_CodeEdit_method_get_code_region_start_tag) + +Returns the code region start tag (without comment delimiter). + +
+ + + + + +[String](class_string.md) **get_delimiter_end_key**\ (\ delimiter_index\: [int](class_int.md)\ ) const [🔗](#class_CodeEdit_method_get_delimiter_end_key) + +Gets the end key for a string or comment region index. + +
+ + + + + +[Vector2](class_vector2.md) **get_delimiter_end_position**\ (\ line\: [int](class_int.md), column\: [int](class_int.md)\ ) const [🔗](#class_CodeEdit_method_get_delimiter_end_position) + +If `line` `column` is in a string or comment, returns the end position of the region. If not or no end could be found, both [Vector2](class_vector2.md) values will be ``-1``. + +
+ + + + + +[String](class_string.md) **get_delimiter_start_key**\ (\ delimiter_index\: [int](class_int.md)\ ) const [🔗](#class_CodeEdit_method_get_delimiter_start_key) + +Gets the start key for a string or comment region index. + +
+ + + + + +[Vector2](class_vector2.md) **get_delimiter_start_position**\ (\ line\: [int](class_int.md), column\: [int](class_int.md)\ ) const [🔗](#class_CodeEdit_method_get_delimiter_start_position) + +If `line` `column` is in a string or comment, returns the start position of the region. If not or no start could be found, both [Vector2](class_vector2.md) values will be ``-1``. + +
+ + + + + +[PackedInt32Array](class_packedint32array.md) **get_executing_lines**\ (\ ) const [🔗](#class_CodeEdit_method_get_executing_lines) + +Gets all executing lines. + +
+ + + + + +[Array](class_array.md)\[[int](class_int.md)\] **get_folded_lines**\ (\ ) const [🔗](#class_CodeEdit_method_get_folded_lines) + +Returns all lines that are currently folded. + +
+ + + + + +[String](class_string.md) **get_text_for_code_completion**\ (\ ) const [🔗](#class_CodeEdit_method_get_text_for_code_completion) + +Returns the full text with char ``0xFFFF`` at the caret location. + +
+ + + + + +[String](class_string.md) **get_text_for_symbol_lookup**\ (\ ) const [🔗](#class_CodeEdit_method_get_text_for_symbol_lookup) + +Returns the full text with char ``0xFFFF`` at the cursor location. + +
+ + + + + +[String](class_string.md) **get_text_with_cursor_char**\ (\ line\: [int](class_int.md), column\: [int](class_int.md)\ ) const [🔗](#class_CodeEdit_method_get_text_with_cursor_char) + +Returns the full text with char ``0xFFFF`` at the specified location. + +
+ + + + + +[bool](class_bool.md) **has_auto_brace_completion_close_key**\ (\ close_key\: [String](class_string.md)\ ) const [🔗](#class_CodeEdit_method_has_auto_brace_completion_close_key) + +Returns ``true`` if close key `close_key` exists. + +
+ + + + + +[bool](class_bool.md) **has_auto_brace_completion_open_key**\ (\ open_key\: [String](class_string.md)\ ) const [🔗](#class_CodeEdit_method_has_auto_brace_completion_open_key) + +Returns ``true`` if open key `open_key` exists. + +
+ + + + + +[bool](class_bool.md) **has_comment_delimiter**\ (\ start_key\: [String](class_string.md)\ ) const [🔗](#class_CodeEdit_method_has_comment_delimiter) + +Returns ``true`` if comment `start_key` exists. + +
+ + + + + +[bool](class_bool.md) **has_string_delimiter**\ (\ start_key\: [String](class_string.md)\ ) const [🔗](#class_CodeEdit_method_has_string_delimiter) + +Returns ``true`` if string `start_key` exists. + +
+ + + + + +`void` **indent_lines**\ (\ ) [🔗](#class_CodeEdit_method_indent_lines) + +Indents all lines that are selected or have a caret on them. Uses spaces or a tab depending on [indent_use_spaces](class_codeedit.md#class_CodeEdit_property_indent_use_spaces). See [unindent_lines()](class_codeedit.md#class_CodeEdit_method_unindent_lines). + +
+ + + + + +[int](class_int.md) **is_in_comment**\ (\ line\: [int](class_int.md), column\: [int](class_int.md) = -1\ ) const [🔗](#class_CodeEdit_method_is_in_comment) + +Returns delimiter index if `line` `column` is in a comment. If `column` is not provided, will return delimiter index if the entire `line` is a comment. Otherwise ``-1``. + +
+ + + + + +[int](class_int.md) **is_in_string**\ (\ line\: [int](class_int.md), column\: [int](class_int.md) = -1\ ) const [🔗](#class_CodeEdit_method_is_in_string) + +Returns the delimiter index if `line` `column` is in a string. If `column` is not provided, will return the delimiter index if the entire `line` is a string. Otherwise ``-1``. + +
+ + + + + +[bool](class_bool.md) **is_line_bookmarked**\ (\ line\: [int](class_int.md)\ ) const [🔗](#class_CodeEdit_method_is_line_bookmarked) + +Returns ``true`` if the given line is bookmarked. See [set_line_as_bookmarked()](class_codeedit.md#class_CodeEdit_method_set_line_as_bookmarked). + +
+ + + + + +[bool](class_bool.md) **is_line_breakpointed**\ (\ line\: [int](class_int.md)\ ) const [🔗](#class_CodeEdit_method_is_line_breakpointed) + +Returns ``true`` if the given line is breakpointed. See [set_line_as_breakpoint()](class_codeedit.md#class_CodeEdit_method_set_line_as_breakpoint). + +
+ + + + + +[bool](class_bool.md) **is_line_code_region_end**\ (\ line\: [int](class_int.md)\ ) const [🔗](#class_CodeEdit_method_is_line_code_region_end) + +Returns ``true`` if the given line is a code region end. See [set_code_region_tags()](class_codeedit.md#class_CodeEdit_method_set_code_region_tags). + +
+ + + + + +[bool](class_bool.md) **is_line_code_region_start**\ (\ line\: [int](class_int.md)\ ) const [🔗](#class_CodeEdit_method_is_line_code_region_start) + +Returns ``true`` if the given line is a code region start. See [set_code_region_tags()](class_codeedit.md#class_CodeEdit_method_set_code_region_tags). + +
+ + + + + +[bool](class_bool.md) **is_line_executing**\ (\ line\: [int](class_int.md)\ ) const [🔗](#class_CodeEdit_method_is_line_executing) + +Returns ``true`` if the given line is marked as executing. See [set_line_as_executing()](class_codeedit.md#class_CodeEdit_method_set_line_as_executing). + +
+ + + + + +[bool](class_bool.md) **is_line_folded**\ (\ line\: [int](class_int.md)\ ) const [🔗](#class_CodeEdit_method_is_line_folded) + +Returns ``true`` if the given line is folded. See [fold_line()](class_codeedit.md#class_CodeEdit_method_fold_line). + +
+ + + + + +`void` **move_lines_down**\ (\ ) [🔗](#class_CodeEdit_method_move_lines_down) + +Moves all lines down that are selected or have a caret on them. + +
+ + + + + +`void` **move_lines_up**\ (\ ) [🔗](#class_CodeEdit_method_move_lines_up) + +Moves all lines up that are selected or have a caret on them. + +
+ + + + + +`void` **remove_comment_delimiter**\ (\ start_key\: [String](class_string.md)\ ) [🔗](#class_CodeEdit_method_remove_comment_delimiter) + +Removes the comment delimiter with `start_key`. + +
+ + + + + +`void` **remove_string_delimiter**\ (\ start_key\: [String](class_string.md)\ ) [🔗](#class_CodeEdit_method_remove_string_delimiter) + +Removes the string delimiter with `start_key`. + +
+ + + + + +`void` **request_code_completion**\ (\ force\: [bool](class_bool.md) = false\ ) [🔗](#class_CodeEdit_method_request_code_completion) + +Emits [code_completion_requested](class_codeedit.md#class_CodeEdit_signal_code_completion_requested), if `force` is ``true`` will bypass all checks. Otherwise will check that the caret is in a word or in front of a prefix. Will ignore the request if all current options are of type file path, node path, or signal. + +
+ + + + + +`void` **set_code_completion_selected_index**\ (\ index\: [int](class_int.md)\ ) [🔗](#class_CodeEdit_method_set_code_completion_selected_index) + +Sets the current selected completion option. + +
+ + + + + +`void` **set_code_hint**\ (\ code_hint\: [String](class_string.md)\ ) [🔗](#class_CodeEdit_method_set_code_hint) + +Sets the code hint text. Pass an empty string to clear. + +
+ + + + + +`void` **set_code_hint_draw_below**\ (\ draw_below\: [bool](class_bool.md)\ ) [🔗](#class_CodeEdit_method_set_code_hint_draw_below) + +If ``true``, the code hint will draw below the main caret. If ``false``, the code hint will draw above the main caret. See [set_code_hint()](class_codeedit.md#class_CodeEdit_method_set_code_hint). + +
+ + + + + +`void` **set_code_region_tags**\ (\ start\: [String](class_string.md) = "region", end\: [String](class_string.md) = "endregion"\ ) [🔗](#class_CodeEdit_method_set_code_region_tags) + +Sets the code region start and end tags (without comment delimiter). + +
+ + + + + +`void` **set_line_as_bookmarked**\ (\ line\: [int](class_int.md), bookmarked\: [bool](class_bool.md)\ ) [🔗](#class_CodeEdit_method_set_line_as_bookmarked) + +Sets the given line as bookmarked. If ``true`` and [gutters_draw_bookmarks](class_codeedit.md#class_CodeEdit_property_gutters_draw_bookmarks) is ``true``, draws the [bookmark](class_codeedit.md#class_CodeEdit_theme_icon_bookmark) icon in the gutter for this line. See [get_bookmarked_lines()](class_codeedit.md#class_CodeEdit_method_get_bookmarked_lines) and [is_line_bookmarked()](class_codeedit.md#class_CodeEdit_method_is_line_bookmarked). + +
+ + + + + +`void` **set_line_as_breakpoint**\ (\ line\: [int](class_int.md), breakpointed\: [bool](class_bool.md)\ ) [🔗](#class_CodeEdit_method_set_line_as_breakpoint) + +Sets the given line as a breakpoint. If ``true`` and [gutters_draw_breakpoints_gutter](class_codeedit.md#class_CodeEdit_property_gutters_draw_breakpoints_gutter) is ``true``, draws the [breakpoint](class_codeedit.md#class_CodeEdit_theme_icon_breakpoint) icon in the gutter for this line. See [get_breakpointed_lines()](class_codeedit.md#class_CodeEdit_method_get_breakpointed_lines) and [is_line_breakpointed()](class_codeedit.md#class_CodeEdit_method_is_line_breakpointed). + +
+ + + + + +`void` **set_line_as_executing**\ (\ line\: [int](class_int.md), executing\: [bool](class_bool.md)\ ) [🔗](#class_CodeEdit_method_set_line_as_executing) + +Sets the given line as executing. If ``true`` and [gutters_draw_executing_lines](class_codeedit.md#class_CodeEdit_property_gutters_draw_executing_lines) is ``true``, draws the [executing_line](class_codeedit.md#class_CodeEdit_theme_icon_executing_line) icon in the gutter for this line. See [get_executing_lines()](class_codeedit.md#class_CodeEdit_method_get_executing_lines) and [is_line_executing()](class_codeedit.md#class_CodeEdit_method_is_line_executing). + +
+ + + + + +`void` **set_symbol_lookup_word_as_valid**\ (\ valid\: [bool](class_bool.md)\ ) [🔗](#class_CodeEdit_method_set_symbol_lookup_word_as_valid) + +Sets the symbol emitted by [symbol_validate](class_codeedit.md#class_CodeEdit_signal_symbol_validate) as a valid lookup. + +
+ + + + + +`void` **toggle_foldable_line**\ (\ line\: [int](class_int.md)\ ) [🔗](#class_CodeEdit_method_toggle_foldable_line) + +Toggle the folding of the code block at the given line. + +
+ + + + + +`void` **toggle_foldable_lines_at_carets**\ (\ ) [🔗](#class_CodeEdit_method_toggle_foldable_lines_at_carets) + +Toggle the folding of the code block on all lines with a caret on them. + +
+ + + + + +`void` **unfold_all_lines**\ (\ ) [🔗](#class_CodeEdit_method_unfold_all_lines) + +Unfolds all lines that are folded. + +
+ + + + + +`void` **unfold_line**\ (\ line\: [int](class_int.md)\ ) [🔗](#class_CodeEdit_method_unfold_line) + +Unfolds the given line if it is folded or if it is hidden under a folded line. + +
+ + + + + +`void` **unindent_lines**\ (\ ) [🔗](#class_CodeEdit_method_unindent_lines) + +Unindents all lines that are selected or have a caret on them. Uses spaces or a tab depending on [indent_use_spaces](class_codeedit.md#class_CodeEdit_property_indent_use_spaces). Equivalent to the [ProjectSettings.input/ui_text_dedent](class_projectsettings.md#class_ProjectSettings_property_input/ui_text_dedent) action. See [indent_lines()](class_codeedit.md#class_CodeEdit_method_indent_lines). + +
+ + + + + +`void` **update_code_completion_options**\ (\ force\: [bool](class_bool.md)\ ) [🔗](#class_CodeEdit_method_update_code_completion_options) + +Submits all completion options added with [add_code_completion_option()](class_codeedit.md#class_CodeEdit_method_add_code_completion_option). Will try to force the autocomplete menu to popup, if `force` is ``true``. + +\ **Note:** This will replace all current candidates. + +
+ + + +## Theme Property Descriptions + + + + + +[Color](class_color.md) **bookmark_color** = `Color(0.5, 0.64, 1, 0.8)` [🔗](#class_CodeEdit_theme_color_bookmark_color) + +[Color](class_color.md) of the bookmark icon for bookmarked lines. + +
+ + + + + +[Color](class_color.md) **brace_mismatch_color** = `Color(1, 0.2, 0.2, 1)` [🔗](#class_CodeEdit_theme_color_brace_mismatch_color) + +[Color](class_color.md) of the text to highlight mismatched braces. + +
+ + + + + +[Color](class_color.md) **breakpoint_color** = `Color(0.9, 0.29, 0.3, 1)` [🔗](#class_CodeEdit_theme_color_breakpoint_color) + +[Color](class_color.md) of the breakpoint icon for bookmarked lines. + +
+ + + + + +[Color](class_color.md) **code_folding_color** = `Color(0.8, 0.8, 0.8, 0.8)` [🔗](#class_CodeEdit_theme_color_code_folding_color) + +[Color](class_color.md) for all icons related to line folding. + +
+ + + + + +[Color](class_color.md) **completion_background_color** = `Color(0.17, 0.16, 0.2, 1)` [🔗](#class_CodeEdit_theme_color_completion_background_color) + +Sets the background [Color](class_color.md) for the code completion popup. + +
+ + + + + +[Color](class_color.md) **completion_existing_color** = `Color(0.87, 0.87, 0.87, 0.13)` [🔗](#class_CodeEdit_theme_color_completion_existing_color) + +Background highlight [Color](class_color.md) for matching text in code completion options. + +
+ + + + + +[Color](class_color.md) **completion_scroll_color** = `Color(1, 1, 1, 0.29)` [🔗](#class_CodeEdit_theme_color_completion_scroll_color) + +[Color](class_color.md) of the scrollbar in the code completion popup. + +
+ + + + + +[Color](class_color.md) **completion_scroll_hovered_color** = `Color(1, 1, 1, 0.4)` [🔗](#class_CodeEdit_theme_color_completion_scroll_hovered_color) + +[Color](class_color.md) of the scrollbar in the code completion popup when hovered. + +
+ + + + + +[Color](class_color.md) **completion_selected_color** = `Color(0.26, 0.26, 0.27, 1)` [🔗](#class_CodeEdit_theme_color_completion_selected_color) + +Background highlight [Color](class_color.md) for the current selected option item in the code completion popup. + +
+ + + + + +[Color](class_color.md) **executing_line_color** = `Color(0.98, 0.89, 0.27, 1)` [🔗](#class_CodeEdit_theme_color_executing_line_color) + +[Color](class_color.md) of the executing icon for executing lines. + +
+ + + + + +[Color](class_color.md) **folded_code_region_color** = `Color(0.68, 0.46, 0.77, 0.2)` [🔗](#class_CodeEdit_theme_color_folded_code_region_color) + +[Color](class_color.md) of background line highlight for folded code region. + +
+ + + + + +[Color](class_color.md) **line_length_guideline_color** = `Color(0.3, 0.5, 0.8, 0.1)` [🔗](#class_CodeEdit_theme_color_line_length_guideline_color) + +[Color](class_color.md) of the main line length guideline, secondary guidelines will have 50% alpha applied. + +
+ + + + + +[Color](class_color.md) **line_number_color** = `Color(0.67, 0.67, 0.67, 0.4)` [🔗](#class_CodeEdit_theme_color_line_number_color) + +Sets the [Color](class_color.md) of line numbers. + +
+ + + + + +[int](class_int.md) **completion_lines** = `7` [🔗](#class_CodeEdit_theme_constant_completion_lines) + +Max number of options to display in the code completion popup at any one time. + +
+ + + + + +[int](class_int.md) **completion_max_width** = `50` [🔗](#class_CodeEdit_theme_constant_completion_max_width) + +Max width of options in the code completion popup. Options longer than this will be cut off. + +
+ + + + + +[int](class_int.md) **completion_scroll_width** = `6` [🔗](#class_CodeEdit_theme_constant_completion_scroll_width) + +Width of the scrollbar in the code completion popup. + +
+ + + + + +[Texture2D](class_texture2d.md) **bookmark** [🔗](#class_CodeEdit_theme_icon_bookmark) + +Sets a custom [Texture2D](class_texture2d.md) to draw in the bookmark gutter for bookmarked lines. + +
+ + + + + +[Texture2D](class_texture2d.md) **breakpoint** [🔗](#class_CodeEdit_theme_icon_breakpoint) + +Sets a custom [Texture2D](class_texture2d.md) to draw in the breakpoint gutter for breakpointed lines. + +
+ + + + + +[Texture2D](class_texture2d.md) **can_fold** [🔗](#class_CodeEdit_theme_icon_can_fold) + +Sets a custom [Texture2D](class_texture2d.md) to draw in the line folding gutter when a line can be folded. + +
+ + + + + +[Texture2D](class_texture2d.md) **can_fold_code_region** [🔗](#class_CodeEdit_theme_icon_can_fold_code_region) + +Sets a custom [Texture2D](class_texture2d.md) to draw in the line folding gutter when a code region can be folded. + +
+ + + + + +[Texture2D](class_texture2d.md) **completion_color_bg** [🔗](#class_CodeEdit_theme_icon_completion_color_bg) + +Background panel for the color preview box in autocompletion (visible when the color is translucent). + +
+ + + + + +[Texture2D](class_texture2d.md) **executing_line** [🔗](#class_CodeEdit_theme_icon_executing_line) + +Icon to draw in the executing gutter for executing lines. + +
+ + + + + +[Texture2D](class_texture2d.md) **folded** [🔗](#class_CodeEdit_theme_icon_folded) + +Sets a custom [Texture2D](class_texture2d.md) to draw in the line folding gutter when a line is folded and can be unfolded. + +
+ + + + + +[Texture2D](class_texture2d.md) **folded_code_region** [🔗](#class_CodeEdit_theme_icon_folded_code_region) + +Sets a custom [Texture2D](class_texture2d.md) to draw in the line folding gutter when a code region is folded and can be unfolded. + +
+ + + + + +[Texture2D](class_texture2d.md) **folded_eol_icon** [🔗](#class_CodeEdit_theme_icon_folded_eol_icon) + +Sets a custom [Texture2D](class_texture2d.md) to draw at the end of a folded line. + +
+ + + + + +[StyleBox](class_stylebox.md) **completion** [🔗](#class_CodeEdit_theme_style_completion) + +[StyleBox](class_stylebox.md) for the code completion popup. + diff --git a/docs/Classes/class_codehighlighter.md b/docs/Classes/class_codehighlighter.md new file mode 100644 index 00000000..51692ec3 --- /dev/null +++ b/docs/Classes/class_codehighlighter.md @@ -0,0 +1,395 @@ + + + + + + + + + +# CodeHighlighter + +**Inherits:** [SyntaxHighlighter](class_syntaxhighlighter.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +A syntax highlighter intended for code. + + + +## Description + +By adjusting various properties of this resource, you can change the colors of strings, comments, numbers, and other text patterns inside a [TextEdit](class_textedit.md) control. + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Dictionary](class_dictionary.md)[color_regions](#class_CodeHighlighter_property_color_regions)`{}`
[Color](class_color.md)[function_color](#class_CodeHighlighter_property_function_color)`Color(0, 0, 0, 1)`
[Dictionary](class_dictionary.md)[keyword_colors](#class_CodeHighlighter_property_keyword_colors)`{}`
[Dictionary](class_dictionary.md)[member_keyword_colors](#class_CodeHighlighter_property_member_keyword_colors)`{}`
[Color](class_color.md)[member_variable_color](#class_CodeHighlighter_property_member_variable_color)`Color(0, 0, 0, 1)`
[Color](class_color.md)[number_color](#class_CodeHighlighter_property_number_color)`Color(0, 0, 0, 1)`
[Color](class_color.md)[symbol_color](#class_CodeHighlighter_property_symbol_color)`Color(0, 0, 0, 1)`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
`void`[add_color_region](#class_CodeHighlighter_method_add_color_region)\ (\ start_key\: [String](class_string.md), end_key\: [String](class_string.md), color\: [Color](class_color.md), line_only\: [bool](class_bool.md) = false\ )
`void`[add_keyword_color](#class_CodeHighlighter_method_add_keyword_color)\ (\ keyword\: [String](class_string.md), color\: [Color](class_color.md)\ )
`void`[add_member_keyword_color](#class_CodeHighlighter_method_add_member_keyword_color)\ (\ member_keyword\: [String](class_string.md), color\: [Color](class_color.md)\ )
`void`[clear_color_regions](#class_CodeHighlighter_method_clear_color_regions)\ (\ )
`void`[clear_keyword_colors](#class_CodeHighlighter_method_clear_keyword_colors)\ (\ )
`void`[clear_member_keyword_colors](#class_CodeHighlighter_method_clear_member_keyword_colors)\ (\ )
[Color](class_color.md)[get_keyword_color](#class_CodeHighlighter_method_get_keyword_color)\ (\ keyword\: [String](class_string.md)\ ) const
[Color](class_color.md)[get_member_keyword_color](#class_CodeHighlighter_method_get_member_keyword_color)\ (\ member_keyword\: [String](class_string.md)\ ) const
[bool](class_bool.md)[has_color_region](#class_CodeHighlighter_method_has_color_region)\ (\ start_key\: [String](class_string.md)\ ) const
[bool](class_bool.md)[has_keyword_color](#class_CodeHighlighter_method_has_keyword_color)\ (\ keyword\: [String](class_string.md)\ ) const
[bool](class_bool.md)[has_member_keyword_color](#class_CodeHighlighter_method_has_member_keyword_color)\ (\ member_keyword\: [String](class_string.md)\ ) const
`void`[remove_color_region](#class_CodeHighlighter_method_remove_color_region)\ (\ start_key\: [String](class_string.md)\ )
`void`[remove_keyword_color](#class_CodeHighlighter_method_remove_keyword_color)\ (\ keyword\: [String](class_string.md)\ )
`void`[remove_member_keyword_color](#class_CodeHighlighter_method_remove_member_keyword_color)\ (\ member_keyword\: [String](class_string.md)\ )
+ +
+ + + +## Property Descriptions + + + + + +[Dictionary](class_dictionary.md) **color_regions** = `{}` [🔗](#class_CodeHighlighter_property_color_regions) + + + +- `void` **set_color_regions**\ (\ value\: [Dictionary](class_dictionary.md)\ ) +- [Dictionary](class_dictionary.md) **get_color_regions**\ (\ ) + +Sets the color regions. All existing regions will be removed. The [Dictionary](class_dictionary.md) key is the region start and end key, separated by a space. The value is the region color. + +
+ + + + + +[Color](class_color.md) **function_color** = `Color(0, 0, 0, 1)` [🔗](#class_CodeHighlighter_property_function_color) + + + +- `void` **set_function_color**\ (\ value\: [Color](class_color.md)\ ) +- [Color](class_color.md) **get_function_color**\ (\ ) + +Sets color for functions. A function is a non-keyword string followed by a '('. + +
+ + + + + +[Dictionary](class_dictionary.md) **keyword_colors** = `{}` [🔗](#class_CodeHighlighter_property_keyword_colors) + + + +- `void` **set_keyword_colors**\ (\ value\: [Dictionary](class_dictionary.md)\ ) +- [Dictionary](class_dictionary.md) **get_keyword_colors**\ (\ ) + +Sets the keyword colors. All existing keywords will be removed. The [Dictionary](class_dictionary.md) key is the keyword. The value is the keyword color. + +
+ + + + + +[Dictionary](class_dictionary.md) **member_keyword_colors** = `{}` [🔗](#class_CodeHighlighter_property_member_keyword_colors) + + + +- `void` **set_member_keyword_colors**\ (\ value\: [Dictionary](class_dictionary.md)\ ) +- [Dictionary](class_dictionary.md) **get_member_keyword_colors**\ (\ ) + +Sets the member keyword colors. All existing member keyword will be removed. The [Dictionary](class_dictionary.md) key is the member keyword. The value is the member keyword color. + +
+ + + + + +[Color](class_color.md) **member_variable_color** = `Color(0, 0, 0, 1)` [🔗](#class_CodeHighlighter_property_member_variable_color) + + + +- `void` **set_member_variable_color**\ (\ value\: [Color](class_color.md)\ ) +- [Color](class_color.md) **get_member_variable_color**\ (\ ) + +Sets color for member variables. A member variable is non-keyword, non-function string proceeded with a '.'. + +
+ + + + + +[Color](class_color.md) **number_color** = `Color(0, 0, 0, 1)` [🔗](#class_CodeHighlighter_property_number_color) + + + +- `void` **set_number_color**\ (\ value\: [Color](class_color.md)\ ) +- [Color](class_color.md) **get_number_color**\ (\ ) + +Sets the color for numbers. + +
+ + + + + +[Color](class_color.md) **symbol_color** = `Color(0, 0, 0, 1)` [🔗](#class_CodeHighlighter_property_symbol_color) + + + +- `void` **set_symbol_color**\ (\ value\: [Color](class_color.md)\ ) +- [Color](class_color.md) **get_symbol_color**\ (\ ) + +Sets the color for symbols. + +
+ + + +## Method Descriptions + + + + + +`void` **add_color_region**\ (\ start_key\: [String](class_string.md), end_key\: [String](class_string.md), color\: [Color](class_color.md), line_only\: [bool](class_bool.md) = false\ ) [🔗](#class_CodeHighlighter_method_add_color_region) + +Adds a color region (such as for comments or strings) from `start_key` to `end_key`. Both keys should be symbols, and `start_key` must not be shared with other delimiters. + +If `line_only` is ``true`` or `end_key` is an empty [String](class_string.md), the region does not carry over to the next line. + +
+ + + + + +`void` **add_keyword_color**\ (\ keyword\: [String](class_string.md), color\: [Color](class_color.md)\ ) [🔗](#class_CodeHighlighter_method_add_keyword_color) + +Sets the color for a keyword. + +The keyword cannot contain any symbols except '\_'. + +
+ + + + + +`void` **add_member_keyword_color**\ (\ member_keyword\: [String](class_string.md), color\: [Color](class_color.md)\ ) [🔗](#class_CodeHighlighter_method_add_member_keyword_color) + +Sets the color for a member keyword. + +The member keyword cannot contain any symbols except '\_'. + +It will not be highlighted if preceded by a '.'. + +
+ + + + + +`void` **clear_color_regions**\ (\ ) [🔗](#class_CodeHighlighter_method_clear_color_regions) + +Removes all color regions. + +
+ + + + + +`void` **clear_keyword_colors**\ (\ ) [🔗](#class_CodeHighlighter_method_clear_keyword_colors) + +Removes all keywords. + +
+ + + + + +`void` **clear_member_keyword_colors**\ (\ ) [🔗](#class_CodeHighlighter_method_clear_member_keyword_colors) + +Removes all member keywords. + +
+ + + + + +[Color](class_color.md) **get_keyword_color**\ (\ keyword\: [String](class_string.md)\ ) const [🔗](#class_CodeHighlighter_method_get_keyword_color) + +Returns the color for a keyword. + +
+ + + + + +[Color](class_color.md) **get_member_keyword_color**\ (\ member_keyword\: [String](class_string.md)\ ) const [🔗](#class_CodeHighlighter_method_get_member_keyword_color) + +Returns the color for a member keyword. + +
+ + + + + +[bool](class_bool.md) **has_color_region**\ (\ start_key\: [String](class_string.md)\ ) const [🔗](#class_CodeHighlighter_method_has_color_region) + +Returns ``true`` if the start key exists, else ``false``. + +
+ + + + + +[bool](class_bool.md) **has_keyword_color**\ (\ keyword\: [String](class_string.md)\ ) const [🔗](#class_CodeHighlighter_method_has_keyword_color) + +Returns ``true`` if the keyword exists, else ``false``. + +
+ + + + + +[bool](class_bool.md) **has_member_keyword_color**\ (\ member_keyword\: [String](class_string.md)\ ) const [🔗](#class_CodeHighlighter_method_has_member_keyword_color) + +Returns ``true`` if the member keyword exists, else ``false``. + +
+ + + + + +`void` **remove_color_region**\ (\ start_key\: [String](class_string.md)\ ) [🔗](#class_CodeHighlighter_method_remove_color_region) + +Removes the color region that uses that start key. + +
+ + + + + +`void` **remove_keyword_color**\ (\ keyword\: [String](class_string.md)\ ) [🔗](#class_CodeHighlighter_method_remove_keyword_color) + +Removes the keyword. + +
+ + + + + +`void` **remove_member_keyword_color**\ (\ member_keyword\: [String](class_string.md)\ ) [🔗](#class_CodeHighlighter_method_remove_member_keyword_color) + +Removes the member keyword. + diff --git a/docs/Classes/class_collisionobject2d.md b/docs/Classes/class_collisionobject2d.md new file mode 100644 index 00000000..76774b56 --- /dev/null +++ b/docs/Classes/class_collisionobject2d.md @@ -0,0 +1,659 @@ + + + + + + + + + +# CollisionObject2D + +**Inherits:** [Node2D](class_node2d.md) **<** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +**Inherited By:** [Area2D](class_area2d.md), [PhysicsBody2D](class_physicsbody2d.md) + +Abstract base class for 2D physics objects. + + + +## Description + +Abstract base class for 2D physics objects. **CollisionObject2D** can hold any number of [Shape2D](class_shape2d.md)\ s for collision. Each shape must be assigned to a *shape owner*. Shape owners are not nodes and do not appear in the editor, but are accessible through code using the ``shape_owner_*`` methods. + +\ **Note:** Only collisions between objects within the same canvas ([Viewport](class_viewport.md) canvas or [CanvasLayer](class_canvaslayer.md)) are supported. The behavior of collisions between objects in different canvases is undefined. + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[int](class_int.md)[collision_layer](#class_CollisionObject2D_property_collision_layer)`1`
[int](class_int.md)[collision_mask](#class_CollisionObject2D_property_collision_mask)`1`
[float](class_float.md)[collision_priority](#class_CollisionObject2D_property_collision_priority)`1.0`
[DisableMode](class_collisionobject2d.md#enum_CollisionObject2D_DisableMode)[disable_mode](#class_CollisionObject2D_property_disable_mode)`0`
[bool](class_bool.md)[input_pickable](#class_CollisionObject2D_property_input_pickable)`true`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
`void`[_input_event](#class_CollisionObject2D_private_method__input_event)\ (\ viewport\: [Viewport](class_viewport.md), event\: [InputEvent](class_inputevent.md), shape_idx\: [int](class_int.md)\ ) virtual
`void`[_mouse_enter](#class_CollisionObject2D_private_method__mouse_enter)\ (\ ) virtual
`void`[_mouse_exit](#class_CollisionObject2D_private_method__mouse_exit)\ (\ ) virtual
`void`[_mouse_shape_enter](#class_CollisionObject2D_private_method__mouse_shape_enter)\ (\ shape_idx\: [int](class_int.md)\ ) virtual
`void`[_mouse_shape_exit](#class_CollisionObject2D_private_method__mouse_shape_exit)\ (\ shape_idx\: [int](class_int.md)\ ) virtual
[int](class_int.md)[create_shape_owner](#class_CollisionObject2D_method_create_shape_owner)\ (\ owner\: [Object](class_object.md)\ )
[bool](class_bool.md)[get_collision_layer_value](#class_CollisionObject2D_method_get_collision_layer_value)\ (\ layer_number\: [int](class_int.md)\ ) const
[bool](class_bool.md)[get_collision_mask_value](#class_CollisionObject2D_method_get_collision_mask_value)\ (\ layer_number\: [int](class_int.md)\ ) const
[RID](class_rid.md)[get_rid](#class_CollisionObject2D_method_get_rid)\ (\ ) const
[float](class_float.md)[get_shape_owner_one_way_collision_margin](#class_CollisionObject2D_method_get_shape_owner_one_way_collision_margin)\ (\ owner_id\: [int](class_int.md)\ ) const
[PackedInt32Array](class_packedint32array.md)[get_shape_owners](#class_CollisionObject2D_method_get_shape_owners)\ (\ )
[bool](class_bool.md)[is_shape_owner_disabled](#class_CollisionObject2D_method_is_shape_owner_disabled)\ (\ owner_id\: [int](class_int.md)\ ) const
[bool](class_bool.md)[is_shape_owner_one_way_collision_enabled](#class_CollisionObject2D_method_is_shape_owner_one_way_collision_enabled)\ (\ owner_id\: [int](class_int.md)\ ) const
`void`[remove_shape_owner](#class_CollisionObject2D_method_remove_shape_owner)\ (\ owner_id\: [int](class_int.md)\ )
`void`[set_collision_layer_value](#class_CollisionObject2D_method_set_collision_layer_value)\ (\ layer_number\: [int](class_int.md), value\: [bool](class_bool.md)\ )
`void`[set_collision_mask_value](#class_CollisionObject2D_method_set_collision_mask_value)\ (\ layer_number\: [int](class_int.md), value\: [bool](class_bool.md)\ )
[int](class_int.md)[shape_find_owner](#class_CollisionObject2D_method_shape_find_owner)\ (\ shape_index\: [int](class_int.md)\ ) const
`void`[shape_owner_add_shape](#class_CollisionObject2D_method_shape_owner_add_shape)\ (\ owner_id\: [int](class_int.md), shape\: [Shape2D](class_shape2d.md)\ )
`void`[shape_owner_clear_shapes](#class_CollisionObject2D_method_shape_owner_clear_shapes)\ (\ owner_id\: [int](class_int.md)\ )
[Object](class_object.md)[shape_owner_get_owner](#class_CollisionObject2D_method_shape_owner_get_owner)\ (\ owner_id\: [int](class_int.md)\ ) const
[Shape2D](class_shape2d.md)[shape_owner_get_shape](#class_CollisionObject2D_method_shape_owner_get_shape)\ (\ owner_id\: [int](class_int.md), shape_id\: [int](class_int.md)\ ) const
[int](class_int.md)[shape_owner_get_shape_count](#class_CollisionObject2D_method_shape_owner_get_shape_count)\ (\ owner_id\: [int](class_int.md)\ ) const
[int](class_int.md)[shape_owner_get_shape_index](#class_CollisionObject2D_method_shape_owner_get_shape_index)\ (\ owner_id\: [int](class_int.md), shape_id\: [int](class_int.md)\ ) const
[Transform2D](class_transform2d.md)[shape_owner_get_transform](#class_CollisionObject2D_method_shape_owner_get_transform)\ (\ owner_id\: [int](class_int.md)\ ) const
`void`[shape_owner_remove_shape](#class_CollisionObject2D_method_shape_owner_remove_shape)\ (\ owner_id\: [int](class_int.md), shape_id\: [int](class_int.md)\ )
`void`[shape_owner_set_disabled](#class_CollisionObject2D_method_shape_owner_set_disabled)\ (\ owner_id\: [int](class_int.md), disabled\: [bool](class_bool.md)\ )
`void`[shape_owner_set_one_way_collision](#class_CollisionObject2D_method_shape_owner_set_one_way_collision)\ (\ owner_id\: [int](class_int.md), enable\: [bool](class_bool.md)\ )
`void`[shape_owner_set_one_way_collision_margin](#class_CollisionObject2D_method_shape_owner_set_one_way_collision_margin)\ (\ owner_id\: [int](class_int.md), margin\: [float](class_float.md)\ )
`void`[shape_owner_set_transform](#class_CollisionObject2D_method_shape_owner_set_transform)\ (\ owner_id\: [int](class_int.md), transform\: [Transform2D](class_transform2d.md)\ )
+ +
+ + + +## Signals + + + + + +**input_event**\ (\ viewport\: [Node](class_node.md), event\: [InputEvent](class_inputevent.md), shape_idx\: [int](class_int.md)\ ) [🔗](#class_CollisionObject2D_signal_input_event) + +Emitted when an input event occurs. Requires [input_pickable](class_collisionobject2d.md#class_CollisionObject2D_property_input_pickable) to be ``true`` and at least one [collision_layer](class_collisionobject2d.md#class_CollisionObject2D_property_collision_layer) bit to be set. See [_input_event()](class_collisionobject2d.md#class_CollisionObject2D_private_method__input_event) for details. + +
+ + + + + +**mouse_entered**\ (\ ) [🔗](#class_CollisionObject2D_signal_mouse_entered) + +Emitted when the mouse pointer enters any of this object's shapes. Requires [input_pickable](class_collisionobject2d.md#class_CollisionObject2D_property_input_pickable) to be ``true`` and at least one [collision_layer](class_collisionobject2d.md#class_CollisionObject2D_property_collision_layer) bit to be set. Note that moving between different shapes within a single **CollisionObject2D** won't cause this signal to be emitted. + +\ **Note:** Due to the lack of continuous collision detection, this signal may not be emitted in the expected order if the mouse moves fast enough and the **CollisionObject2D**'s area is small. This signal may also not be emitted if another **CollisionObject2D** is overlapping the **CollisionObject2D** in question. + +
+ + + + + +**mouse_exited**\ (\ ) [🔗](#class_CollisionObject2D_signal_mouse_exited) + +Emitted when the mouse pointer exits all this object's shapes. Requires [input_pickable](class_collisionobject2d.md#class_CollisionObject2D_property_input_pickable) to be ``true`` and at least one [collision_layer](class_collisionobject2d.md#class_CollisionObject2D_property_collision_layer) bit to be set. Note that moving between different shapes within a single **CollisionObject2D** won't cause this signal to be emitted. + +\ **Note:** Due to the lack of continuous collision detection, this signal may not be emitted in the expected order if the mouse moves fast enough and the **CollisionObject2D**'s area is small. This signal may also not be emitted if another **CollisionObject2D** is overlapping the **CollisionObject2D** in question. + +
+ + + + + +**mouse_shape_entered**\ (\ shape_idx\: [int](class_int.md)\ ) [🔗](#class_CollisionObject2D_signal_mouse_shape_entered) + +Emitted when the mouse pointer enters any of this object's shapes or moves from one shape to another. `shape_idx` is the child index of the newly entered [Shape2D](class_shape2d.md). Requires [input_pickable](class_collisionobject2d.md#class_CollisionObject2D_property_input_pickable) to be ``true`` and at least one [collision_layer](class_collisionobject2d.md#class_CollisionObject2D_property_collision_layer) bit to be set. + +
+ + + + + +**mouse_shape_exited**\ (\ shape_idx\: [int](class_int.md)\ ) [🔗](#class_CollisionObject2D_signal_mouse_shape_exited) + +Emitted when the mouse pointer exits any of this object's shapes. `shape_idx` is the child index of the exited [Shape2D](class_shape2d.md). Requires [input_pickable](class_collisionobject2d.md#class_CollisionObject2D_property_input_pickable) to be ``true`` and at least one [collision_layer](class_collisionobject2d.md#class_CollisionObject2D_property_collision_layer) bit to be set. + +
+ + + +## Enumerations + + + + + +enum **DisableMode**: [🔗](#enum_CollisionObject2D_DisableMode) + + + + + +[DisableMode](class_collisionobject2d.md#enum_CollisionObject2D_DisableMode) **DISABLE_MODE_REMOVE** = `0` + +When [Node.process_mode](class_node.md#class_Node_property_process_mode) is set to [Node.PROCESS_MODE_DISABLED](class_node.md#class_Node_constant_PROCESS_MODE_DISABLED), remove from the physics simulation to stop all physics interactions with this **CollisionObject2D**. + +Automatically re-added to the physics simulation when the [Node](class_node.md) is processed again. + + + +[DisableMode](class_collisionobject2d.md#enum_CollisionObject2D_DisableMode) **DISABLE_MODE_MAKE_STATIC** = `1` + +When [Node.process_mode](class_node.md#class_Node_property_process_mode) is set to [Node.PROCESS_MODE_DISABLED](class_node.md#class_Node_constant_PROCESS_MODE_DISABLED), make the body static. Doesn't affect [Area2D](class_area2d.md). [PhysicsBody2D](class_physicsbody2d.md) can't be affected by forces or other bodies while static. + +Automatically set [PhysicsBody2D](class_physicsbody2d.md) back to its original mode when the [Node](class_node.md) is processed again. + + + +[DisableMode](class_collisionobject2d.md#enum_CollisionObject2D_DisableMode) **DISABLE_MODE_KEEP_ACTIVE** = `2` + +When [Node.process_mode](class_node.md#class_Node_property_process_mode) is set to [Node.PROCESS_MODE_DISABLED](class_node.md#class_Node_constant_PROCESS_MODE_DISABLED), do not affect the physics simulation.
+ + + +## Property Descriptions + + + + + +[int](class_int.md) **collision_layer** = `1` [🔗](#class_CollisionObject2D_property_collision_layer) + + + +- `void` **set_collision_layer**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_collision_layer**\ (\ ) + +The physics layers this CollisionObject2D is in. Collision objects can exist in one or more of 32 different layers. See also [collision_mask](class_collisionobject2d.md#class_CollisionObject2D_property_collision_mask). + +\ **Note:** Object A can detect a contact with object B only if object B is in any of the layers that object A scans. See [Collision layers and masks](../tutorials/physics/physics_introduction.md#collision-layers-and-masks) in the documentation for more information. + +
+ + + + + +[int](class_int.md) **collision_mask** = `1` [🔗](#class_CollisionObject2D_property_collision_mask) + + + +- `void` **set_collision_mask**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_collision_mask**\ (\ ) + +The physics layers this CollisionObject2D scans. Collision objects can scan one or more of 32 different layers. See also [collision_layer](class_collisionobject2d.md#class_CollisionObject2D_property_collision_layer). + +\ **Note:** Object A can detect a contact with object B only if object B is in any of the layers that object A scans. See [Collision layers and masks](../tutorials/physics/physics_introduction.md#collision-layers-and-masks) in the documentation for more information. + +
+ + + + + +[float](class_float.md) **collision_priority** = `1.0` [🔗](#class_CollisionObject2D_property_collision_priority) + + + +- `void` **set_collision_priority**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_collision_priority**\ (\ ) + +The priority used to solve colliding when occurring penetration. The higher the priority is, the lower the penetration into the object will be. This can for example be used to prevent the player from breaking through the boundaries of a level. + +
+ + + + + +[DisableMode](class_collisionobject2d.md#enum_CollisionObject2D_DisableMode) **disable_mode** = `0` [🔗](#class_CollisionObject2D_property_disable_mode) + + + +- `void` **set_disable_mode**\ (\ value\: [DisableMode](class_collisionobject2d.md#enum_CollisionObject2D_DisableMode)\ ) +- [DisableMode](class_collisionobject2d.md#enum_CollisionObject2D_DisableMode) **get_disable_mode**\ (\ ) + +Defines the behavior in physics when [Node.process_mode](class_node.md#class_Node_property_process_mode) is set to [Node.PROCESS_MODE_DISABLED](class_node.md#class_Node_constant_PROCESS_MODE_DISABLED). + +
+ + + + + +[bool](class_bool.md) **input_pickable** = `true` [🔗](#class_CollisionObject2D_property_input_pickable) + + + +- `void` **set_pickable**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_pickable**\ (\ ) + +If ``true``, this object is pickable. A pickable object can detect the mouse pointer entering/leaving, and if the mouse is inside it, report input events. Requires at least one [collision_layer](class_collisionobject2d.md#class_CollisionObject2D_property_collision_layer) bit to be set. + +
+ + + +## Method Descriptions + + + + + +`void` **_input_event**\ (\ viewport\: [Viewport](class_viewport.md), event\: [InputEvent](class_inputevent.md), shape_idx\: [int](class_int.md)\ ) virtual [🔗](#class_CollisionObject2D_private_method__input_event) + +Accepts unhandled [InputEvent](class_inputevent.md)\ s. `shape_idx` is the child index of the clicked [Shape2D](class_shape2d.md). Connect to [input_event](class_collisionobject2d.md#class_CollisionObject2D_signal_input_event) to easily pick up these events. + +\ **Note:** [_input_event()](class_collisionobject2d.md#class_CollisionObject2D_private_method__input_event) requires [input_pickable](class_collisionobject2d.md#class_CollisionObject2D_property_input_pickable) to be ``true`` and at least one [collision_layer](class_collisionobject2d.md#class_CollisionObject2D_property_collision_layer) bit to be set. + +
+ + + + + +`void` **_mouse_enter**\ (\ ) virtual [🔗](#class_CollisionObject2D_private_method__mouse_enter) + +Called when the mouse pointer enters any of this object's shapes. Requires [input_pickable](class_collisionobject2d.md#class_CollisionObject2D_property_input_pickable) to be ``true`` and at least one [collision_layer](class_collisionobject2d.md#class_CollisionObject2D_property_collision_layer) bit to be set. Note that moving between different shapes within a single **CollisionObject2D** won't cause this function to be called. + +
+ + + + + +`void` **_mouse_exit**\ (\ ) virtual [🔗](#class_CollisionObject2D_private_method__mouse_exit) + +Called when the mouse pointer exits all this object's shapes. Requires [input_pickable](class_collisionobject2d.md#class_CollisionObject2D_property_input_pickable) to be ``true`` and at least one [collision_layer](class_collisionobject2d.md#class_CollisionObject2D_property_collision_layer) bit to be set. Note that moving between different shapes within a single **CollisionObject2D** won't cause this function to be called. + +
+ + + + + +`void` **_mouse_shape_enter**\ (\ shape_idx\: [int](class_int.md)\ ) virtual [🔗](#class_CollisionObject2D_private_method__mouse_shape_enter) + +Called when the mouse pointer enters any of this object's shapes or moves from one shape to another. `shape_idx` is the child index of the newly entered [Shape2D](class_shape2d.md). Requires [input_pickable](class_collisionobject2d.md#class_CollisionObject2D_property_input_pickable) to be ``true`` and at least one [collision_layer](class_collisionobject2d.md#class_CollisionObject2D_property_collision_layer) bit to be called. + +
+ + + + + +`void` **_mouse_shape_exit**\ (\ shape_idx\: [int](class_int.md)\ ) virtual [🔗](#class_CollisionObject2D_private_method__mouse_shape_exit) + +Called when the mouse pointer exits any of this object's shapes. `shape_idx` is the child index of the exited [Shape2D](class_shape2d.md). Requires [input_pickable](class_collisionobject2d.md#class_CollisionObject2D_property_input_pickable) to be ``true`` and at least one [collision_layer](class_collisionobject2d.md#class_CollisionObject2D_property_collision_layer) bit to be called. + +
+ + + + + +[int](class_int.md) **create_shape_owner**\ (\ owner\: [Object](class_object.md)\ ) [🔗](#class_CollisionObject2D_method_create_shape_owner) + +Creates a new shape owner for the given object. Returns ``owner_id`` of the new owner for future reference. + +
+ + + + + +[bool](class_bool.md) **get_collision_layer_value**\ (\ layer_number\: [int](class_int.md)\ ) const [🔗](#class_CollisionObject2D_method_get_collision_layer_value) + +Returns whether or not the specified layer of the [collision_layer](class_collisionobject2d.md#class_CollisionObject2D_property_collision_layer) is enabled, given a `layer_number` between 1 and 32. + +
+ + + + + +[bool](class_bool.md) **get_collision_mask_value**\ (\ layer_number\: [int](class_int.md)\ ) const [🔗](#class_CollisionObject2D_method_get_collision_mask_value) + +Returns whether or not the specified layer of the [collision_mask](class_collisionobject2d.md#class_CollisionObject2D_property_collision_mask) is enabled, given a `layer_number` between 1 and 32. + +
+ + + + + +[RID](class_rid.md) **get_rid**\ (\ ) const [🔗](#class_CollisionObject2D_method_get_rid) + +Returns the object's [RID](class_rid.md). + +
+ + + + + +[float](class_float.md) **get_shape_owner_one_way_collision_margin**\ (\ owner_id\: [int](class_int.md)\ ) const [🔗](#class_CollisionObject2D_method_get_shape_owner_one_way_collision_margin) + +Returns the ``one_way_collision_margin`` of the shape owner identified by given `owner_id`. + +
+ + + + + +[PackedInt32Array](class_packedint32array.md) **get_shape_owners**\ (\ ) [🔗](#class_CollisionObject2D_method_get_shape_owners) + +Returns an [Array](class_array.md) of ``owner_id`` identifiers. You can use these ids in other methods that take ``owner_id`` as an argument. + +
+ + + + + +[bool](class_bool.md) **is_shape_owner_disabled**\ (\ owner_id\: [int](class_int.md)\ ) const [🔗](#class_CollisionObject2D_method_is_shape_owner_disabled) + +If ``true``, the shape owner and its shapes are disabled. + +
+ + + + + +[bool](class_bool.md) **is_shape_owner_one_way_collision_enabled**\ (\ owner_id\: [int](class_int.md)\ ) const [🔗](#class_CollisionObject2D_method_is_shape_owner_one_way_collision_enabled) + +Returns ``true`` if collisions for the shape owner originating from this **CollisionObject2D** will not be reported to collided with **CollisionObject2D**\ s. + +
+ + + + + +`void` **remove_shape_owner**\ (\ owner_id\: [int](class_int.md)\ ) [🔗](#class_CollisionObject2D_method_remove_shape_owner) + +Removes the given shape owner. + +
+ + + + + +`void` **set_collision_layer_value**\ (\ layer_number\: [int](class_int.md), value\: [bool](class_bool.md)\ ) [🔗](#class_CollisionObject2D_method_set_collision_layer_value) + +Based on `value`, enables or disables the specified layer in the [collision_layer](class_collisionobject2d.md#class_CollisionObject2D_property_collision_layer), given a `layer_number` between 1 and 32. + +
+ + + + + +`void` **set_collision_mask_value**\ (\ layer_number\: [int](class_int.md), value\: [bool](class_bool.md)\ ) [🔗](#class_CollisionObject2D_method_set_collision_mask_value) + +Based on `value`, enables or disables the specified layer in the [collision_mask](class_collisionobject2d.md#class_CollisionObject2D_property_collision_mask), given a `layer_number` between 1 and 32. + +
+ + + + + +[int](class_int.md) **shape_find_owner**\ (\ shape_index\: [int](class_int.md)\ ) const [🔗](#class_CollisionObject2D_method_shape_find_owner) + +Returns the ``owner_id`` of the given shape. + +
+ + + + + +`void` **shape_owner_add_shape**\ (\ owner_id\: [int](class_int.md), shape\: [Shape2D](class_shape2d.md)\ ) [🔗](#class_CollisionObject2D_method_shape_owner_add_shape) + +Adds a [Shape2D](class_shape2d.md) to the shape owner. + +
+ + + + + +`void` **shape_owner_clear_shapes**\ (\ owner_id\: [int](class_int.md)\ ) [🔗](#class_CollisionObject2D_method_shape_owner_clear_shapes) + +Removes all shapes from the shape owner. + +
+ + + + + +[Object](class_object.md) **shape_owner_get_owner**\ (\ owner_id\: [int](class_int.md)\ ) const [🔗](#class_CollisionObject2D_method_shape_owner_get_owner) + +Returns the parent object of the given shape owner. + +
+ + + + + +[Shape2D](class_shape2d.md) **shape_owner_get_shape**\ (\ owner_id\: [int](class_int.md), shape_id\: [int](class_int.md)\ ) const [🔗](#class_CollisionObject2D_method_shape_owner_get_shape) + +Returns the [Shape2D](class_shape2d.md) with the given ID from the given shape owner. + +
+ + + + + +[int](class_int.md) **shape_owner_get_shape_count**\ (\ owner_id\: [int](class_int.md)\ ) const [🔗](#class_CollisionObject2D_method_shape_owner_get_shape_count) + +Returns the number of shapes the given shape owner contains. + +
+ + + + + +[int](class_int.md) **shape_owner_get_shape_index**\ (\ owner_id\: [int](class_int.md), shape_id\: [int](class_int.md)\ ) const [🔗](#class_CollisionObject2D_method_shape_owner_get_shape_index) + +Returns the child index of the [Shape2D](class_shape2d.md) with the given ID from the given shape owner. + +
+ + + + + +[Transform2D](class_transform2d.md) **shape_owner_get_transform**\ (\ owner_id\: [int](class_int.md)\ ) const [🔗](#class_CollisionObject2D_method_shape_owner_get_transform) + +Returns the shape owner's [Transform2D](class_transform2d.md). + +
+ + + + + +`void` **shape_owner_remove_shape**\ (\ owner_id\: [int](class_int.md), shape_id\: [int](class_int.md)\ ) [🔗](#class_CollisionObject2D_method_shape_owner_remove_shape) + +Removes a shape from the given shape owner. + +
+ + + + + +`void` **shape_owner_set_disabled**\ (\ owner_id\: [int](class_int.md), disabled\: [bool](class_bool.md)\ ) [🔗](#class_CollisionObject2D_method_shape_owner_set_disabled) + +If ``true``, disables the given shape owner. + +
+ + + + + +`void` **shape_owner_set_one_way_collision**\ (\ owner_id\: [int](class_int.md), enable\: [bool](class_bool.md)\ ) [🔗](#class_CollisionObject2D_method_shape_owner_set_one_way_collision) + +If `enable` is ``true``, collisions for the shape owner originating from this **CollisionObject2D** will not be reported to collided with **CollisionObject2D**\ s. + +
+ + + + + +`void` **shape_owner_set_one_way_collision_margin**\ (\ owner_id\: [int](class_int.md), margin\: [float](class_float.md)\ ) [🔗](#class_CollisionObject2D_method_shape_owner_set_one_way_collision_margin) + +Sets the ``one_way_collision_margin`` of the shape owner identified by given `owner_id` to `margin` pixels. + +
+ + + + + +`void` **shape_owner_set_transform**\ (\ owner_id\: [int](class_int.md), transform\: [Transform2D](class_transform2d.md)\ ) [🔗](#class_CollisionObject2D_method_shape_owner_set_transform) + +Sets the [Transform2D](class_transform2d.md) of the given shape owner. + diff --git a/docs/Classes/class_collisionobject3d.md b/docs/Classes/class_collisionobject3d.md new file mode 100644 index 00000000..f6f603b6 --- /dev/null +++ b/docs/Classes/class_collisionobject3d.md @@ -0,0 +1,575 @@ + + + + + + + + + +# CollisionObject3D + +**Inherits:** [Node3D](class_node3d.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +**Inherited By:** [Area3D](class_area3d.md), [PhysicsBody3D](class_physicsbody3d.md) + +Abstract base class for 3D physics objects. + + + +## Description + +Abstract base class for 3D physics objects. **CollisionObject3D** can hold any number of [Shape3D](class_shape3d.md)\ s for collision. Each shape must be assigned to a *shape owner*. Shape owners are not nodes and do not appear in the editor, but are accessible through code using the ``shape_owner_*`` methods. + +\ **Warning:** With a non-uniform scale, this node will likely not behave as expected. It is advised to keep its scale the same on all axes and adjust its collision shape(s) instead. + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[int](class_int.md)[collision_layer](#class_CollisionObject3D_property_collision_layer)`1`
[int](class_int.md)[collision_mask](#class_CollisionObject3D_property_collision_mask)`1`
[float](class_float.md)[collision_priority](#class_CollisionObject3D_property_collision_priority)`1.0`
[DisableMode](class_collisionobject3d.md#enum_CollisionObject3D_DisableMode)[disable_mode](#class_CollisionObject3D_property_disable_mode)`0`
[bool](class_bool.md)[input_capture_on_drag](#class_CollisionObject3D_property_input_capture_on_drag)`false`
[bool](class_bool.md)[input_ray_pickable](#class_CollisionObject3D_property_input_ray_pickable)`true`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
`void`[_input_event](#class_CollisionObject3D_private_method__input_event)\ (\ camera\: [Camera3D](class_camera3d.md), event\: [InputEvent](class_inputevent.md), event_position\: [Vector3](class_vector3.md), normal\: [Vector3](class_vector3.md), shape_idx\: [int](class_int.md)\ ) virtual
`void`[_mouse_enter](#class_CollisionObject3D_private_method__mouse_enter)\ (\ ) virtual
`void`[_mouse_exit](#class_CollisionObject3D_private_method__mouse_exit)\ (\ ) virtual
[int](class_int.md)[create_shape_owner](#class_CollisionObject3D_method_create_shape_owner)\ (\ owner\: [Object](class_object.md)\ )
[bool](class_bool.md)[get_collision_layer_value](#class_CollisionObject3D_method_get_collision_layer_value)\ (\ layer_number\: [int](class_int.md)\ ) const
[bool](class_bool.md)[get_collision_mask_value](#class_CollisionObject3D_method_get_collision_mask_value)\ (\ layer_number\: [int](class_int.md)\ ) const
[RID](class_rid.md)[get_rid](#class_CollisionObject3D_method_get_rid)\ (\ ) const
[PackedInt32Array](class_packedint32array.md)[get_shape_owners](#class_CollisionObject3D_method_get_shape_owners)\ (\ )
[bool](class_bool.md)[is_shape_owner_disabled](#class_CollisionObject3D_method_is_shape_owner_disabled)\ (\ owner_id\: [int](class_int.md)\ ) const
`void`[remove_shape_owner](#class_CollisionObject3D_method_remove_shape_owner)\ (\ owner_id\: [int](class_int.md)\ )
`void`[set_collision_layer_value](#class_CollisionObject3D_method_set_collision_layer_value)\ (\ layer_number\: [int](class_int.md), value\: [bool](class_bool.md)\ )
`void`[set_collision_mask_value](#class_CollisionObject3D_method_set_collision_mask_value)\ (\ layer_number\: [int](class_int.md), value\: [bool](class_bool.md)\ )
[int](class_int.md)[shape_find_owner](#class_CollisionObject3D_method_shape_find_owner)\ (\ shape_index\: [int](class_int.md)\ ) const
`void`[shape_owner_add_shape](#class_CollisionObject3D_method_shape_owner_add_shape)\ (\ owner_id\: [int](class_int.md), shape\: [Shape3D](class_shape3d.md)\ )
`void`[shape_owner_clear_shapes](#class_CollisionObject3D_method_shape_owner_clear_shapes)\ (\ owner_id\: [int](class_int.md)\ )
[Object](class_object.md)[shape_owner_get_owner](#class_CollisionObject3D_method_shape_owner_get_owner)\ (\ owner_id\: [int](class_int.md)\ ) const
[Shape3D](class_shape3d.md)[shape_owner_get_shape](#class_CollisionObject3D_method_shape_owner_get_shape)\ (\ owner_id\: [int](class_int.md), shape_id\: [int](class_int.md)\ ) const
[int](class_int.md)[shape_owner_get_shape_count](#class_CollisionObject3D_method_shape_owner_get_shape_count)\ (\ owner_id\: [int](class_int.md)\ ) const
[int](class_int.md)[shape_owner_get_shape_index](#class_CollisionObject3D_method_shape_owner_get_shape_index)\ (\ owner_id\: [int](class_int.md), shape_id\: [int](class_int.md)\ ) const
[Transform3D](class_transform3d.md)[shape_owner_get_transform](#class_CollisionObject3D_method_shape_owner_get_transform)\ (\ owner_id\: [int](class_int.md)\ ) const
`void`[shape_owner_remove_shape](#class_CollisionObject3D_method_shape_owner_remove_shape)\ (\ owner_id\: [int](class_int.md), shape_id\: [int](class_int.md)\ )
`void`[shape_owner_set_disabled](#class_CollisionObject3D_method_shape_owner_set_disabled)\ (\ owner_id\: [int](class_int.md), disabled\: [bool](class_bool.md)\ )
`void`[shape_owner_set_transform](#class_CollisionObject3D_method_shape_owner_set_transform)\ (\ owner_id\: [int](class_int.md), transform\: [Transform3D](class_transform3d.md)\ )
+ +
+ + + +## Signals + + + + + +**input_event**\ (\ camera\: [Node](class_node.md), event\: [InputEvent](class_inputevent.md), event_position\: [Vector3](class_vector3.md), normal\: [Vector3](class_vector3.md), shape_idx\: [int](class_int.md)\ ) [🔗](#class_CollisionObject3D_signal_input_event) + +Emitted when the object receives an unhandled [InputEvent](class_inputevent.md). `event_position` is the location in world space of the mouse pointer on the surface of the shape with index `shape_idx` and `normal` is the normal vector of the surface at that point. + +
+ + + + + +**mouse_entered**\ (\ ) [🔗](#class_CollisionObject3D_signal_mouse_entered) + +Emitted when the mouse pointer enters any of this object's shapes. Requires [input_ray_pickable](class_collisionobject3d.md#class_CollisionObject3D_property_input_ray_pickable) to be ``true`` and at least one [collision_layer](class_collisionobject3d.md#class_CollisionObject3D_property_collision_layer) bit to be set. + +\ **Note:** Due to the lack of continuous collision detection, this signal may not be emitted in the expected order if the mouse moves fast enough and the **CollisionObject3D**'s area is small. This signal may also not be emitted if another **CollisionObject3D** is overlapping the **CollisionObject3D** in question. + +
+ + + + + +**mouse_exited**\ (\ ) [🔗](#class_CollisionObject3D_signal_mouse_exited) + +Emitted when the mouse pointer exits all this object's shapes. Requires [input_ray_pickable](class_collisionobject3d.md#class_CollisionObject3D_property_input_ray_pickable) to be ``true`` and at least one [collision_layer](class_collisionobject3d.md#class_CollisionObject3D_property_collision_layer) bit to be set. + +\ **Note:** Due to the lack of continuous collision detection, this signal may not be emitted in the expected order if the mouse moves fast enough and the **CollisionObject3D**'s area is small. This signal may also not be emitted if another **CollisionObject3D** is overlapping the **CollisionObject3D** in question. + +
+ + + +## Enumerations + + + + + +enum **DisableMode**: [🔗](#enum_CollisionObject3D_DisableMode) + + + + + +[DisableMode](class_collisionobject3d.md#enum_CollisionObject3D_DisableMode) **DISABLE_MODE_REMOVE** = `0` + +When [Node.process_mode](class_node.md#class_Node_property_process_mode) is set to [Node.PROCESS_MODE_DISABLED](class_node.md#class_Node_constant_PROCESS_MODE_DISABLED), remove from the physics simulation to stop all physics interactions with this **CollisionObject3D**. + +Automatically re-added to the physics simulation when the [Node](class_node.md) is processed again. + + + +[DisableMode](class_collisionobject3d.md#enum_CollisionObject3D_DisableMode) **DISABLE_MODE_MAKE_STATIC** = `1` + +When [Node.process_mode](class_node.md#class_Node_property_process_mode) is set to [Node.PROCESS_MODE_DISABLED](class_node.md#class_Node_constant_PROCESS_MODE_DISABLED), make the body static. Doesn't affect [Area3D](class_area3d.md). [PhysicsBody3D](class_physicsbody3d.md) can't be affected by forces or other bodies while static. + +Automatically set [PhysicsBody3D](class_physicsbody3d.md) back to its original mode when the [Node](class_node.md) is processed again. + + + +[DisableMode](class_collisionobject3d.md#enum_CollisionObject3D_DisableMode) **DISABLE_MODE_KEEP_ACTIVE** = `2` + +When [Node.process_mode](class_node.md#class_Node_property_process_mode) is set to [Node.PROCESS_MODE_DISABLED](class_node.md#class_Node_constant_PROCESS_MODE_DISABLED), do not affect the physics simulation.
+ + + +## Property Descriptions + + + + + +[int](class_int.md) **collision_layer** = `1` [🔗](#class_CollisionObject3D_property_collision_layer) + + + +- `void` **set_collision_layer**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_collision_layer**\ (\ ) + +The physics layers this CollisionObject3D **is in**. Collision objects can exist in one or more of 32 different layers. See also [collision_mask](class_collisionobject3d.md#class_CollisionObject3D_property_collision_mask). + +\ **Note:** Object A can detect a contact with object B only if object B is in any of the layers that object A scans. See [Collision layers and masks](../tutorials/physics/physics_introduction.md#collision-layers-and-masks) in the documentation for more information. + +
+ + + + + +[int](class_int.md) **collision_mask** = `1` [🔗](#class_CollisionObject3D_property_collision_mask) + + + +- `void` **set_collision_mask**\ (\ value\: [int](class_int.md)\ ) +- [int](class_int.md) **get_collision_mask**\ (\ ) + +The physics layers this CollisionObject3D **scans**. Collision objects can scan one or more of 32 different layers. See also [collision_layer](class_collisionobject3d.md#class_CollisionObject3D_property_collision_layer). + +\ **Note:** Object A can detect a contact with object B only if object B is in any of the layers that object A scans. See [Collision layers and masks](../tutorials/physics/physics_introduction.md#collision-layers-and-masks) in the documentation for more information. + +
+ + + + + +[float](class_float.md) **collision_priority** = `1.0` [🔗](#class_CollisionObject3D_property_collision_priority) + + + +- `void` **set_collision_priority**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_collision_priority**\ (\ ) + +The priority used to solve colliding when occurring penetration. The higher the priority is, the lower the penetration into the object will be. This can for example be used to prevent the player from breaking through the boundaries of a level. + +
+ + + + + +[DisableMode](class_collisionobject3d.md#enum_CollisionObject3D_DisableMode) **disable_mode** = `0` [🔗](#class_CollisionObject3D_property_disable_mode) + + + +- `void` **set_disable_mode**\ (\ value\: [DisableMode](class_collisionobject3d.md#enum_CollisionObject3D_DisableMode)\ ) +- [DisableMode](class_collisionobject3d.md#enum_CollisionObject3D_DisableMode) **get_disable_mode**\ (\ ) + +Defines the behavior in physics when [Node.process_mode](class_node.md#class_Node_property_process_mode) is set to [Node.PROCESS_MODE_DISABLED](class_node.md#class_Node_constant_PROCESS_MODE_DISABLED). + +
+ + + + + +[bool](class_bool.md) **input_capture_on_drag** = `false` [🔗](#class_CollisionObject3D_property_input_capture_on_drag) + + + +- `void` **set_capture_input_on_drag**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_capture_input_on_drag**\ (\ ) + +If ``true``, the **CollisionObject3D** will continue to receive input events as the mouse is dragged across its shapes. + +
+ + + + + +[bool](class_bool.md) **input_ray_pickable** = `true` [🔗](#class_CollisionObject3D_property_input_ray_pickable) + + + +- `void` **set_ray_pickable**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_ray_pickable**\ (\ ) + +If ``true``, this object is pickable. A pickable object can detect the mouse pointer entering/leaving, and if the mouse is inside it, report input events. Requires at least one [collision_layer](class_collisionobject3d.md#class_CollisionObject3D_property_collision_layer) bit to be set. + +
+ + + +## Method Descriptions + + + + + +`void` **_input_event**\ (\ camera\: [Camera3D](class_camera3d.md), event\: [InputEvent](class_inputevent.md), event_position\: [Vector3](class_vector3.md), normal\: [Vector3](class_vector3.md), shape_idx\: [int](class_int.md)\ ) virtual [🔗](#class_CollisionObject3D_private_method__input_event) + +Receives unhandled [InputEvent](class_inputevent.md)\ s. `event_position` is the location in world space of the mouse pointer on the surface of the shape with index `shape_idx` and `normal` is the normal vector of the surface at that point. Connect to the [input_event](class_collisionobject3d.md#class_CollisionObject3D_signal_input_event) signal to easily pick up these events. + +\ **Note:** [_input_event()](class_collisionobject3d.md#class_CollisionObject3D_private_method__input_event) requires [input_ray_pickable](class_collisionobject3d.md#class_CollisionObject3D_property_input_ray_pickable) to be ``true`` and at least one [collision_layer](class_collisionobject3d.md#class_CollisionObject3D_property_collision_layer) bit to be set. + +
+ + + + + +`void` **_mouse_enter**\ (\ ) virtual [🔗](#class_CollisionObject3D_private_method__mouse_enter) + +Called when the mouse pointer enters any of this object's shapes. Requires [input_ray_pickable](class_collisionobject3d.md#class_CollisionObject3D_property_input_ray_pickable) to be ``true`` and at least one [collision_layer](class_collisionobject3d.md#class_CollisionObject3D_property_collision_layer) bit to be set. Note that moving between different shapes within a single **CollisionObject3D** won't cause this function to be called. + +
+ + + + + +`void` **_mouse_exit**\ (\ ) virtual [🔗](#class_CollisionObject3D_private_method__mouse_exit) + +Called when the mouse pointer exits all this object's shapes. Requires [input_ray_pickable](class_collisionobject3d.md#class_CollisionObject3D_property_input_ray_pickable) to be ``true`` and at least one [collision_layer](class_collisionobject3d.md#class_CollisionObject3D_property_collision_layer) bit to be set. Note that moving between different shapes within a single **CollisionObject3D** won't cause this function to be called. + +
+ + + + + +[int](class_int.md) **create_shape_owner**\ (\ owner\: [Object](class_object.md)\ ) [🔗](#class_CollisionObject3D_method_create_shape_owner) + +Creates a new shape owner for the given object. Returns ``owner_id`` of the new owner for future reference. + +
+ + + + + +[bool](class_bool.md) **get_collision_layer_value**\ (\ layer_number\: [int](class_int.md)\ ) const [🔗](#class_CollisionObject3D_method_get_collision_layer_value) + +Returns whether or not the specified layer of the [collision_layer](class_collisionobject3d.md#class_CollisionObject3D_property_collision_layer) is enabled, given a `layer_number` between 1 and 32. + +
+ + + + + +[bool](class_bool.md) **get_collision_mask_value**\ (\ layer_number\: [int](class_int.md)\ ) const [🔗](#class_CollisionObject3D_method_get_collision_mask_value) + +Returns whether or not the specified layer of the [collision_mask](class_collisionobject3d.md#class_CollisionObject3D_property_collision_mask) is enabled, given a `layer_number` between 1 and 32. + +
+ + + + + +[RID](class_rid.md) **get_rid**\ (\ ) const [🔗](#class_CollisionObject3D_method_get_rid) + +Returns the object's [RID](class_rid.md). + +
+ + + + + +[PackedInt32Array](class_packedint32array.md) **get_shape_owners**\ (\ ) [🔗](#class_CollisionObject3D_method_get_shape_owners) + +Returns an [Array](class_array.md) of ``owner_id`` identifiers. You can use these ids in other methods that take ``owner_id`` as an argument. + +
+ + + + + +[bool](class_bool.md) **is_shape_owner_disabled**\ (\ owner_id\: [int](class_int.md)\ ) const [🔗](#class_CollisionObject3D_method_is_shape_owner_disabled) + +If ``true``, the shape owner and its shapes are disabled. + +
+ + + + + +`void` **remove_shape_owner**\ (\ owner_id\: [int](class_int.md)\ ) [🔗](#class_CollisionObject3D_method_remove_shape_owner) + +Removes the given shape owner. + +
+ + + + + +`void` **set_collision_layer_value**\ (\ layer_number\: [int](class_int.md), value\: [bool](class_bool.md)\ ) [🔗](#class_CollisionObject3D_method_set_collision_layer_value) + +Based on `value`, enables or disables the specified layer in the [collision_layer](class_collisionobject3d.md#class_CollisionObject3D_property_collision_layer), given a `layer_number` between 1 and 32. + +
+ + + + + +`void` **set_collision_mask_value**\ (\ layer_number\: [int](class_int.md), value\: [bool](class_bool.md)\ ) [🔗](#class_CollisionObject3D_method_set_collision_mask_value) + +Based on `value`, enables or disables the specified layer in the [collision_mask](class_collisionobject3d.md#class_CollisionObject3D_property_collision_mask), given a `layer_number` between 1 and 32. + +
+ + + + + +[int](class_int.md) **shape_find_owner**\ (\ shape_index\: [int](class_int.md)\ ) const [🔗](#class_CollisionObject3D_method_shape_find_owner) + +Returns the ``owner_id`` of the given shape. + +
+ + + + + +`void` **shape_owner_add_shape**\ (\ owner_id\: [int](class_int.md), shape\: [Shape3D](class_shape3d.md)\ ) [🔗](#class_CollisionObject3D_method_shape_owner_add_shape) + +Adds a [Shape3D](class_shape3d.md) to the shape owner. + +
+ + + + + +`void` **shape_owner_clear_shapes**\ (\ owner_id\: [int](class_int.md)\ ) [🔗](#class_CollisionObject3D_method_shape_owner_clear_shapes) + +Removes all shapes from the shape owner. + +
+ + + + + +[Object](class_object.md) **shape_owner_get_owner**\ (\ owner_id\: [int](class_int.md)\ ) const [🔗](#class_CollisionObject3D_method_shape_owner_get_owner) + +Returns the parent object of the given shape owner. + +
+ + + + + +[Shape3D](class_shape3d.md) **shape_owner_get_shape**\ (\ owner_id\: [int](class_int.md), shape_id\: [int](class_int.md)\ ) const [🔗](#class_CollisionObject3D_method_shape_owner_get_shape) + +Returns the [Shape3D](class_shape3d.md) with the given ID from the given shape owner. + +
+ + + + + +[int](class_int.md) **shape_owner_get_shape_count**\ (\ owner_id\: [int](class_int.md)\ ) const [🔗](#class_CollisionObject3D_method_shape_owner_get_shape_count) + +Returns the number of shapes the given shape owner contains. + +
+ + + + + +[int](class_int.md) **shape_owner_get_shape_index**\ (\ owner_id\: [int](class_int.md), shape_id\: [int](class_int.md)\ ) const [🔗](#class_CollisionObject3D_method_shape_owner_get_shape_index) + +Returns the child index of the [Shape3D](class_shape3d.md) with the given ID from the given shape owner. + +
+ + + + + +[Transform3D](class_transform3d.md) **shape_owner_get_transform**\ (\ owner_id\: [int](class_int.md)\ ) const [🔗](#class_CollisionObject3D_method_shape_owner_get_transform) + +Returns the shape owner's [Transform3D](class_transform3d.md). + +
+ + + + + +`void` **shape_owner_remove_shape**\ (\ owner_id\: [int](class_int.md), shape_id\: [int](class_int.md)\ ) [🔗](#class_CollisionObject3D_method_shape_owner_remove_shape) + +Removes a shape from the given shape owner. + +
+ + + + + +`void` **shape_owner_set_disabled**\ (\ owner_id\: [int](class_int.md), disabled\: [bool](class_bool.md)\ ) [🔗](#class_CollisionObject3D_method_shape_owner_set_disabled) + +If ``true``, disables the given shape owner. + +
+ + + + + +`void` **shape_owner_set_transform**\ (\ owner_id\: [int](class_int.md), transform\: [Transform3D](class_transform3d.md)\ ) [🔗](#class_CollisionObject3D_method_shape_owner_set_transform) + +Sets the [Transform3D](class_transform3d.md) of the given shape owner. + diff --git a/docs/Classes/class_collisionpolygon2d.md b/docs/Classes/class_collisionpolygon2d.md new file mode 100644 index 00000000..a26a171f --- /dev/null +++ b/docs/Classes/class_collisionpolygon2d.md @@ -0,0 +1,168 @@ + + + + + + + + + +# CollisionPolygon2D + +**Inherits:** [Node2D](class_node2d.md) **<** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +A node that provides a polygon shape to a [CollisionObject2D](class_collisionobject2d.md) parent. + + + +## Description + +A node that provides a polygon shape to a [CollisionObject2D](class_collisionobject2d.md) parent and allows to edit it. The polygon can be concave or convex. This can give a detection shape to an [Area2D](class_area2d.md), turn [PhysicsBody2D](class_physicsbody2d.md) into a solid object, or give a hollow shape to a [StaticBody2D](class_staticbody2d.md). + +\ **Warning:** A non-uniformly scaled **CollisionPolygon2D** will likely not behave as expected. Make sure to keep its scale the same on all axes and adjust its polygon instead. + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[BuildMode](class_collisionpolygon2d.md#enum_CollisionPolygon2D_BuildMode)[build_mode](#class_CollisionPolygon2D_property_build_mode)`0`
[bool](class_bool.md)[disabled](#class_CollisionPolygon2D_property_disabled)`false`
[bool](class_bool.md)[one_way_collision](#class_CollisionPolygon2D_property_one_way_collision)`false`
[float](class_float.md)[one_way_collision_margin](#class_CollisionPolygon2D_property_one_way_collision_margin)`1.0`
[PackedVector2Array](class_packedvector2array.md)[polygon](#class_CollisionPolygon2D_property_polygon)`PackedVector2Array()`
+ +
+ + + +## Enumerations + + + + + +enum **BuildMode**: [🔗](#enum_CollisionPolygon2D_BuildMode) + + + + + +[BuildMode](class_collisionpolygon2d.md#enum_CollisionPolygon2D_BuildMode) **BUILD_SOLIDS** = `0` + +Collisions will include the polygon and its contained area. In this mode the node has the same effect as several [ConvexPolygonShape2D](class_convexpolygonshape2d.md) nodes, one for each convex shape in the convex decomposition of the polygon (but without the overhead of multiple nodes). + + + +[BuildMode](class_collisionpolygon2d.md#enum_CollisionPolygon2D_BuildMode) **BUILD_SEGMENTS** = `1` + +Collisions will only include the polygon edges. In this mode the node has the same effect as a single [ConcavePolygonShape2D](class_concavepolygonshape2d.md) made of segments, with the restriction that each segment (after the first one) starts where the previous one ends, and the last one ends where the first one starts (forming a closed but hollow polygon).
+ + + +## Property Descriptions + + + + + +[BuildMode](class_collisionpolygon2d.md#enum_CollisionPolygon2D_BuildMode) **build_mode** = `0` [🔗](#class_CollisionPolygon2D_property_build_mode) + + + +- `void` **set_build_mode**\ (\ value\: [BuildMode](class_collisionpolygon2d.md#enum_CollisionPolygon2D_BuildMode)\ ) +- [BuildMode](class_collisionpolygon2d.md#enum_CollisionPolygon2D_BuildMode) **get_build_mode**\ (\ ) + +Collision build mode. + +
+ + + + + +[bool](class_bool.md) **disabled** = `false` [🔗](#class_CollisionPolygon2D_property_disabled) + + + +- `void` **set_disabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_disabled**\ (\ ) + +If ``true``, no collisions will be detected. This property should be changed with [Object.set_deferred()](class_object.md#class_Object_method_set_deferred). + +
+ + + + + +[bool](class_bool.md) **one_way_collision** = `false` [🔗](#class_CollisionPolygon2D_property_one_way_collision) + + + +- `void` **set_one_way_collision**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_one_way_collision_enabled**\ (\ ) + +If ``true``, only edges that face up, relative to **CollisionPolygon2D**'s rotation, will collide with other objects. + +\ **Note:** This property has no effect if this **CollisionPolygon2D** is a child of an [Area2D](class_area2d.md) node. + +
+ + + + + +[float](class_float.md) **one_way_collision_margin** = `1.0` [🔗](#class_CollisionPolygon2D_property_one_way_collision_margin) + + + +- `void` **set_one_way_collision_margin**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_one_way_collision_margin**\ (\ ) + +The margin used for one-way collision (in pixels). Higher values will make the shape thicker, and work better for colliders that enter the polygon at a high velocity. + +
+ + + + + +[PackedVector2Array](class_packedvector2array.md) **polygon** = `PackedVector2Array()` [🔗](#class_CollisionPolygon2D_property_polygon) + + + +- `void` **set_polygon**\ (\ value\: [PackedVector2Array](class_packedvector2array.md)\ ) +- [PackedVector2Array](class_packedvector2array.md) **get_polygon**\ (\ ) + +The polygon's list of vertices. Each point will be connected to the next, and the final point will be connected to the first. + +\ **Note:** The returned vertices are in the local coordinate space of the given **CollisionPolygon2D**. + +**Note:** The returned array is *copied* and any changes to it will not update the original property value. See [PackedVector2Array](class_packedvector2array.md) for more details. + diff --git a/docs/Classes/class_collisionpolygon3d.md b/docs/Classes/class_collisionpolygon3d.md new file mode 100644 index 00000000..ae938178 --- /dev/null +++ b/docs/Classes/class_collisionpolygon3d.md @@ -0,0 +1,162 @@ + + + + + + + + + +# CollisionPolygon3D + +**Inherits:** [Node3D](class_node3d.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +A node that provides a thickened polygon shape (a prism) to a [CollisionObject3D](class_collisionobject3d.md) parent. + + + +## Description + +A node that provides a thickened polygon shape (a prism) to a [CollisionObject3D](class_collisionobject3d.md) parent and allows to edit it. The polygon can be concave or convex. This can give a detection shape to an [Area3D](class_area3d.md) or turn [PhysicsBody3D](class_physicsbody3d.md) into a solid object. + +\ **Warning:** A non-uniformly scaled [CollisionShape3D](class_collisionshape3d.md) will likely not behave as expected. Make sure to keep its scale the same on all axes and adjust its shape resource instead. + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Color](class_color.md)[debug_color](#class_CollisionPolygon3D_property_debug_color)`Color(0, 0, 0, 0)`
[bool](class_bool.md)[debug_fill](#class_CollisionPolygon3D_property_debug_fill)`true`
[float](class_float.md)[depth](#class_CollisionPolygon3D_property_depth)`1.0`
[bool](class_bool.md)[disabled](#class_CollisionPolygon3D_property_disabled)`false`
[float](class_float.md)[margin](#class_CollisionPolygon3D_property_margin)`0.04`
[PackedVector2Array](class_packedvector2array.md)[polygon](#class_CollisionPolygon3D_property_polygon)`PackedVector2Array()`
+ +
+ + + +## Property Descriptions + + + + + +[Color](class_color.md) **debug_color** = `Color(0, 0, 0, 0)` [🔗](#class_CollisionPolygon3D_property_debug_color) + + + +- `void` **set_debug_color**\ (\ value\: [Color](class_color.md)\ ) +- [Color](class_color.md) **get_debug_color**\ (\ ) + +The collision shape color that is displayed in the editor, or in the running project if **Debug > Visible Collision Shapes** is checked at the top of the editor. + +\ **Note:** The default value is [ProjectSettings.debug/shapes/collision/shape_color](class_projectsettings.md#class_ProjectSettings_property_debug/shapes/collision/shape_color). The ``Color(0, 0, 0, 0)`` value documented here is a placeholder, and not the actual default debug color. + +
+ + + + + +[bool](class_bool.md) **debug_fill** = `true` [🔗](#class_CollisionPolygon3D_property_debug_fill) + + + +- `void` **set_enable_debug_fill**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_enable_debug_fill**\ (\ ) + +If ``true``, when the shape is displayed, it will show a solid fill color in addition to its wireframe. + +
+ + + + + +[float](class_float.md) **depth** = `1.0` [🔗](#class_CollisionPolygon3D_property_depth) + + + +- `void` **set_depth**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_depth**\ (\ ) + +Length that the resulting collision extends in either direction perpendicular to its 2D polygon. + +
+ + + + + +[bool](class_bool.md) **disabled** = `false` [🔗](#class_CollisionPolygon3D_property_disabled) + + + +- `void` **set_disabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_disabled**\ (\ ) + +If ``true``, no collision will be produced. This property should be changed with [Object.set_deferred()](class_object.md#class_Object_method_set_deferred). + +
+ + + + + +[float](class_float.md) **margin** = `0.04` [🔗](#class_CollisionPolygon3D_property_margin) + + + +- `void` **set_margin**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_margin**\ (\ ) + +The collision margin for the generated [Shape3D](class_shape3d.md). See [Shape3D.margin](class_shape3d.md#class_Shape3D_property_margin) for more details. + +
+ + + + + +[PackedVector2Array](class_packedvector2array.md) **polygon** = `PackedVector2Array()` [🔗](#class_CollisionPolygon3D_property_polygon) + + + +- `void` **set_polygon**\ (\ value\: [PackedVector2Array](class_packedvector2array.md)\ ) +- [PackedVector2Array](class_packedvector2array.md) **get_polygon**\ (\ ) + +Array of vertices which define the 2D polygon in the local XY plane. + +**Note:** The returned array is *copied* and any changes to it will not update the original property value. See [PackedVector2Array](class_packedvector2array.md) for more details. + diff --git a/docs/Classes/class_collisionshape2d.md b/docs/Classes/class_collisionshape2d.md new file mode 100644 index 00000000..9cea9812 --- /dev/null +++ b/docs/Classes/class_collisionshape2d.md @@ -0,0 +1,152 @@ + + + + + + + + + +# CollisionShape2D + +**Inherits:** [Node2D](class_node2d.md) **<** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +A node that provides a [Shape2D](class_shape2d.md) to a [CollisionObject2D](class_collisionobject2d.md) parent. + + + +## Description + +A node that provides a [Shape2D](class_shape2d.md) to a [CollisionObject2D](class_collisionobject2d.md) parent and allows to edit it. This can give a detection shape to an [Area2D](class_area2d.md) or turn a [PhysicsBody2D](class_physicsbody2d.md) into a solid object. + + + +## Tutorials + +- [Physics introduction](../tutorials/physics/physics_introduction.md) + +- [2D Dodge The Creeps Demo](https://godotengine.org/asset-library/asset/2712) + +- [2D Pong Demo](https://godotengine.org/asset-library/asset/2728) + +- [2D Kinematic Character Demo](https://godotengine.org/asset-library/asset/2719) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Color](class_color.md)[debug_color](#class_CollisionShape2D_property_debug_color)`Color(0, 0, 0, 0)`
[bool](class_bool.md)[disabled](#class_CollisionShape2D_property_disabled)`false`
[bool](class_bool.md)[one_way_collision](#class_CollisionShape2D_property_one_way_collision)`false`
[float](class_float.md)[one_way_collision_margin](#class_CollisionShape2D_property_one_way_collision_margin)`1.0`
[Shape2D](class_shape2d.md)[shape](#class_CollisionShape2D_property_shape)
+ +
+ + + +## Property Descriptions + + + + + +[Color](class_color.md) **debug_color** = `Color(0, 0, 0, 0)` [🔗](#class_CollisionShape2D_property_debug_color) + + + +- `void` **set_debug_color**\ (\ value\: [Color](class_color.md)\ ) +- [Color](class_color.md) **get_debug_color**\ (\ ) + +The collision shape color that is displayed in the editor, or in the running project if **Debug > Visible Collision Shapes** is checked at the top of the editor. + +\ **Note:** The default value is [ProjectSettings.debug/shapes/collision/shape_color](class_projectsettings.md#class_ProjectSettings_property_debug/shapes/collision/shape_color). The ``Color(0, 0, 0, 0)`` value documented here is a placeholder, and not the actual default debug color. + +
+ + + + + +[bool](class_bool.md) **disabled** = `false` [🔗](#class_CollisionShape2D_property_disabled) + + + +- `void` **set_disabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_disabled**\ (\ ) + +A disabled collision shape has no effect in the world. This property should be changed with [Object.set_deferred()](class_object.md#class_Object_method_set_deferred). + +
+ + + + + +[bool](class_bool.md) **one_way_collision** = `false` [🔗](#class_CollisionShape2D_property_one_way_collision) + + + +- `void` **set_one_way_collision**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_one_way_collision_enabled**\ (\ ) + +Sets whether this collision shape should only detect collision on one side (top or bottom). + +\ **Note:** This property has no effect if this **CollisionShape2D** is a child of an [Area2D](class_area2d.md) node. + +
+ + + + + +[float](class_float.md) **one_way_collision_margin** = `1.0` [🔗](#class_CollisionShape2D_property_one_way_collision_margin) + + + +- `void` **set_one_way_collision_margin**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_one_way_collision_margin**\ (\ ) + +The margin used for one-way collision (in pixels). Higher values will make the shape thicker, and work better for colliders that enter the shape at a high velocity. + +
+ + + + + +[Shape2D](class_shape2d.md) **shape** [🔗](#class_CollisionShape2D_property_shape) + + + +- `void` **set_shape**\ (\ value\: [Shape2D](class_shape2d.md)\ ) +- [Shape2D](class_shape2d.md) **get_shape**\ (\ ) + +The actual shape owned by this collision shape. + diff --git a/docs/Classes/class_collisionshape3d.md b/docs/Classes/class_collisionshape3d.md new file mode 100644 index 00000000..95b8adee --- /dev/null +++ b/docs/Classes/class_collisionshape3d.md @@ -0,0 +1,177 @@ + + + + + + + + + +# CollisionShape3D + +**Inherits:** [Node3D](class_node3d.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +A node that provides a [Shape3D](class_shape3d.md) to a [CollisionObject3D](class_collisionobject3d.md) parent. + + + +## Description + +A node that provides a [Shape3D](class_shape3d.md) to a [CollisionObject3D](class_collisionobject3d.md) parent and allows to edit it. This can give a detection shape to an [Area3D](class_area3d.md) or turn a [PhysicsBody3D](class_physicsbody3d.md) into a solid object. + +\ **Warning:** A non-uniformly scaled **CollisionShape3D** will likely not behave as expected. Make sure to keep its scale the same on all axes and adjust its [shape](class_collisionshape3d.md#class_CollisionShape3D_property_shape) resource instead. + + + +## Tutorials + +- [Physics introduction](../tutorials/physics/physics_introduction.md) + +- [3D Kinematic Character Demo](https://godotengine.org/asset-library/asset/2739) + +- [3D Platformer Demo](https://godotengine.org/asset-library/asset/2748) + +- [Third Person Shooter (TPS) Demo](https://godotengine.org/asset-library/asset/2710) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Color](class_color.md)[debug_color](#class_CollisionShape3D_property_debug_color)`Color(0, 0, 0, 0)`
[bool](class_bool.md)[debug_fill](#class_CollisionShape3D_property_debug_fill)`true`
[bool](class_bool.md)[disabled](#class_CollisionShape3D_property_disabled)`false`
[Shape3D](class_shape3d.md)[shape](#class_CollisionShape3D_property_shape)
+ + + +## Methods + + + + + + + + + + + + + + +
`void`[make_convex_from_siblings](#class_CollisionShape3D_method_make_convex_from_siblings)\ (\ )
`void`[resource_changed](#class_CollisionShape3D_method_resource_changed)\ (\ resource\: [Resource](class_resource.md)\ )
+ +
+ + + +## Property Descriptions + + + + + +[Color](class_color.md) **debug_color** = `Color(0, 0, 0, 0)` [🔗](#class_CollisionShape3D_property_debug_color) + + + +- `void` **set_debug_color**\ (\ value\: [Color](class_color.md)\ ) +- [Color](class_color.md) **get_debug_color**\ (\ ) + +The collision shape color that is displayed in the editor, or in the running project if **Debug > Visible Collision Shapes** is checked at the top of the editor. + +\ **Note:** The default value is [ProjectSettings.debug/shapes/collision/shape_color](class_projectsettings.md#class_ProjectSettings_property_debug/shapes/collision/shape_color). The ``Color(0, 0, 0, 0)`` value documented here is a placeholder, and not the actual default debug color. + +
+ + + + + +[bool](class_bool.md) **debug_fill** = `true` [🔗](#class_CollisionShape3D_property_debug_fill) + + + +- `void` **set_enable_debug_fill**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_enable_debug_fill**\ (\ ) + +If ``true``, when the shape is displayed, it will show a solid fill color in addition to its wireframe. + +
+ + + + + +[bool](class_bool.md) **disabled** = `false` [🔗](#class_CollisionShape3D_property_disabled) + + + +- `void` **set_disabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_disabled**\ (\ ) + +A disabled collision shape has no effect in the world. This property should be changed with [Object.set_deferred()](class_object.md#class_Object_method_set_deferred). + +
+ + + + + +[Shape3D](class_shape3d.md) **shape** [🔗](#class_CollisionShape3D_property_shape) + + + +- `void` **set_shape**\ (\ value\: [Shape3D](class_shape3d.md)\ ) +- [Shape3D](class_shape3d.md) **get_shape**\ (\ ) + +The actual shape owned by this collision shape. + +
+ + + +## Method Descriptions + + + + + +`void` **make_convex_from_siblings**\ (\ ) [🔗](#class_CollisionShape3D_method_make_convex_from_siblings) + +Sets the collision shape's shape to the addition of all its convexed [MeshInstance3D](class_meshinstance3d.md) siblings geometry. + +
+ + + + + +`void` **resource_changed**\ (\ resource\: [Resource](class_resource.md)\ ) [🔗](#class_CollisionShape3D_method_resource_changed) + +**Deprecated:** Use [Resource.changed](class_resource.md#class_Resource_signal_changed) instead. + +This method does nothing. + diff --git a/docs/Classes/class_color.md b/docs/Classes/class_color.md new file mode 100644 index 00000000..eb256c93 --- /dev/null +++ b/docs/Classes/class_color.md @@ -0,0 +1,2470 @@ + + + + + + + + + +# Color + +A color represented in RGBA format. + + + +## Description + +A color represented in RGBA format by a red ([r](class_color.md#class_Color_property_r)), green ([g](class_color.md#class_Color_property_g)), blue ([b](class_color.md#class_Color_property_b)), and alpha ([a](class_color.md#class_Color_property_a)) component. Each component is a 32-bit floating-point value, usually ranging from ``0.0`` to ``1.0``. Some properties (such as [CanvasItem.modulate](class_canvasitem.md#class_CanvasItem_property_modulate)) may support values greater than ``1.0``, for overbright or HDR (High Dynamic Range) colors. + +Colors can be created in various ways: By the various **Color** constructors, by static methods such as [from_hsv()](class_color.md#class_Color_method_from_hsv), and by using a name from the set of standardized colors based on [X11 color names](https://en.wikipedia.org/wiki/X11_color_names) with the addition of [TRANSPARENT](class_color.md#class_Color_constant_TRANSPARENT). GDScript also provides [@GDScript.Color8()](class_@gdscript.md#class_@GDScript_method_Color8), which uses integers from ``0`` to ``255`` and doesn't support overbright colors. + +Color data may be stored in many color spaces and encodings. The [srgb_to_linear()](class_color.md#class_Color_method_srgb_to_linear) and [linear_to_srgb()](class_color.md#class_Color_method_linear_to_srgb) methods can convert between nonlinear sRGB encoding and linear RGB encoding. + +\ **Note:** In a boolean context, a Color will evaluate to ``false`` if it is equal to ``Color(0, 0, 0, 1)`` (opaque black). Otherwise, a Color will always evaluate to ``true``. + +\ [Color constants cheatsheet](https://raw.githubusercontent.com/redot-engine/redot-docs/master/img/color_constants.png) + +
+There are notable differences when using this API with C#. See the C# differences documentation for more information. + +
+ + + +## Tutorials + +- [2D GD Paint Demo](https://godotengine.org/asset-library/asset/2768) + +- [Tween Interpolation Demo](https://godotengine.org/asset-library/asset/2733) + +- [GUI Drag And Drop Demo](https://godotengine.org/asset-library/asset/2767) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[a](#class_Color_property_a)`1.0`
[int](class_int.md)[a8](#class_Color_property_a8)`255`
[float](class_float.md)[b](#class_Color_property_b)`0.0`
[int](class_int.md)[b8](#class_Color_property_b8)`0`
[float](class_float.md)[g](#class_Color_property_g)`0.0`
[int](class_int.md)[g8](#class_Color_property_g8)`0`
[float](class_float.md)[h](#class_Color_property_h)`0.0`
[float](class_float.md)[ok_hsl_h](#class_Color_property_ok_hsl_h)`0.0`
[float](class_float.md)[ok_hsl_l](#class_Color_property_ok_hsl_l)`0.0`
[float](class_float.md)[ok_hsl_s](#class_Color_property_ok_hsl_s)`0.0`
[float](class_float.md)[r](#class_Color_property_r)`0.0`
[int](class_int.md)[r8](#class_Color_property_r8)`0`
[float](class_float.md)[s](#class_Color_property_s)`0.0`
[float](class_float.md)[v](#class_Color_property_v)`0.0`
+ + + +## Constructors + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Color](class_color.md)[Color](#class_Color_constructor_Color)\ (\ )
[Color](class_color.md)[Color](#class_Color_constructor_Color)\ (\ from\: [Color](class_color.md), alpha\: [float](class_float.md)\ )
[Color](class_color.md)[Color](#class_Color_constructor_Color)\ (\ from\: [Color](class_color.md)\ )
[Color](class_color.md)[Color](#class_Color_constructor_Color)\ (\ code\: [String](class_string.md)\ )
[Color](class_color.md)[Color](#class_Color_constructor_Color)\ (\ code\: [String](class_string.md), alpha\: [float](class_float.md)\ )
[Color](class_color.md)[Color](#class_Color_constructor_Color)\ (\ r\: [float](class_float.md), g\: [float](class_float.md), b\: [float](class_float.md)\ )
[Color](class_color.md)[Color](#class_Color_constructor_Color)\ (\ r\: [float](class_float.md), g\: [float](class_float.md), b\: [float](class_float.md), a\: [float](class_float.md)\ )
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Color](class_color.md)[blend](#class_Color_method_blend)\ (\ over\: [Color](class_color.md)\ ) const
[Color](class_color.md)[clamp](#class_Color_method_clamp)\ (\ min\: [Color](class_color.md) = Color(0, 0, 0, 0), max\: [Color](class_color.md) = Color(1, 1, 1, 1)\ ) const
[Color](class_color.md)[darkened](#class_Color_method_darkened)\ (\ amount\: [float](class_float.md)\ ) const
[Color](class_color.md)[from_hsv](#class_Color_method_from_hsv)\ (\ h\: [float](class_float.md), s\: [float](class_float.md), v\: [float](class_float.md), alpha\: [float](class_float.md) = 1.0\ ) static
[Color](class_color.md)[from_ok_hsl](#class_Color_method_from_ok_hsl)\ (\ h\: [float](class_float.md), s\: [float](class_float.md), l\: [float](class_float.md), alpha\: [float](class_float.md) = 1.0\ ) static
[Color](class_color.md)[from_rgba8](#class_Color_method_from_rgba8)\ (\ r8\: [int](class_int.md), g8\: [int](class_int.md), b8\: [int](class_int.md), a8\: [int](class_int.md) = 255\ ) static
[Color](class_color.md)[from_rgbe9995](#class_Color_method_from_rgbe9995)\ (\ rgbe\: [int](class_int.md)\ ) static
[Color](class_color.md)[from_string](#class_Color_method_from_string)\ (\ str\: [String](class_string.md), default\: [Color](class_color.md)\ ) static
[float](class_float.md)[get_luminance](#class_Color_method_get_luminance)\ (\ ) const
[Color](class_color.md)[hex](#class_Color_method_hex)\ (\ hex\: [int](class_int.md)\ ) static
[Color](class_color.md)[hex64](#class_Color_method_hex64)\ (\ hex\: [int](class_int.md)\ ) static
[Color](class_color.md)[html](#class_Color_method_html)\ (\ rgba\: [String](class_string.md)\ ) static
[bool](class_bool.md)[html_is_valid](#class_Color_method_html_is_valid)\ (\ color\: [String](class_string.md)\ ) static
[Color](class_color.md)[inverted](#class_Color_method_inverted)\ (\ ) const
[bool](class_bool.md)[is_equal_approx](#class_Color_method_is_equal_approx)\ (\ to\: [Color](class_color.md)\ ) const
[Color](class_color.md)[lerp](#class_Color_method_lerp)\ (\ to\: [Color](class_color.md), weight\: [float](class_float.md)\ ) const
[Color](class_color.md)[lightened](#class_Color_method_lightened)\ (\ amount\: [float](class_float.md)\ ) const
[Color](class_color.md)[linear_to_srgb](#class_Color_method_linear_to_srgb)\ (\ ) const
[Color](class_color.md)[srgb_to_linear](#class_Color_method_srgb_to_linear)\ (\ ) const
[int](class_int.md)[to_abgr32](#class_Color_method_to_abgr32)\ (\ ) const
[int](class_int.md)[to_abgr64](#class_Color_method_to_abgr64)\ (\ ) const
[int](class_int.md)[to_argb32](#class_Color_method_to_argb32)\ (\ ) const
[int](class_int.md)[to_argb64](#class_Color_method_to_argb64)\ (\ ) const
[String](class_string.md)[to_html](#class_Color_method_to_html)\ (\ with_alpha\: [bool](class_bool.md) = true\ ) const
[int](class_int.md)[to_rgba32](#class_Color_method_to_rgba32)\ (\ ) const
[int](class_int.md)[to_rgba64](#class_Color_method_to_rgba64)\ (\ ) const
+ + + +## Operators + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[operator !=](#class_Color_operator_neq_Color)\ (\ right\: [Color](class_color.md)\ )
[Color](class_color.md)[operator *](#class_Color_operator_mul_Color)\ (\ right\: [Color](class_color.md)\ )
[Color](class_color.md)[operator *](#class_Color_operator_mul_float)\ (\ right\: [float](class_float.md)\ )
[Color](class_color.md)[operator *](#class_Color_operator_mul_int)\ (\ right\: [int](class_int.md)\ )
[Color](class_color.md)[operator +](#class_Color_operator_sum_Color)\ (\ right\: [Color](class_color.md)\ )
[Color](class_color.md)[operator -](#class_Color_operator_dif_Color)\ (\ right\: [Color](class_color.md)\ )
[Color](class_color.md)[operator /](#class_Color_operator_div_Color)\ (\ right\: [Color](class_color.md)\ )
[Color](class_color.md)[operator /](#class_Color_operator_div_float)\ (\ right\: [float](class_float.md)\ )
[Color](class_color.md)[operator /](#class_Color_operator_div_int)\ (\ right\: [int](class_int.md)\ )
[bool](class_bool.md)[operator ==](#class_Color_operator_eq_Color)\ (\ right\: [Color](class_color.md)\ )
[float](class_float.md)[operator []](#class_Color_operator_idx_int)\ (\ index\: [int](class_int.md)\ )
[Color](class_color.md)[operator unary+](#class_Color_operator_unplus)\ (\ )
[Color](class_color.md)[operator unary-](#class_Color_operator_unminus)\ (\ )
+ +
+ + + +## Constants + + + + + +**ALICE_BLUE** = `Color(0.9411765, 0.972549, 1, 1)` [🔗](#class_Color_constant_ALICE_BLUE) + +Alice blue color. + + + + + +**ANTIQUE_WHITE** = `Color(0.98039216, 0.92156863, 0.84313726, 1)` [🔗](#class_Color_constant_ANTIQUE_WHITE) + +Antique white color. + + + + + +**AQUA** = `Color(0, 1, 1, 1)` [🔗](#class_Color_constant_AQUA) + +Aqua color. + + + + + +**AQUAMARINE** = `Color(0.49803922, 1, 0.83137256, 1)` [🔗](#class_Color_constant_AQUAMARINE) + +Aquamarine color. + + + + + +**AZURE** = `Color(0.9411765, 1, 1, 1)` [🔗](#class_Color_constant_AZURE) + +Azure color. + + + + + +**BEIGE** = `Color(0.9607843, 0.9607843, 0.8627451, 1)` [🔗](#class_Color_constant_BEIGE) + +Beige color. + + + + + +**BISQUE** = `Color(1, 0.89411765, 0.76862746, 1)` [🔗](#class_Color_constant_BISQUE) + +Bisque color. + + + + + +**BLACK** = `Color(0, 0, 0, 1)` [🔗](#class_Color_constant_BLACK) + +Black color. In GDScript, this is the default value of any color. + + + + + +**BLANCHED_ALMOND** = `Color(1, 0.92156863, 0.8039216, 1)` [🔗](#class_Color_constant_BLANCHED_ALMOND) + +Blanched almond color. + + + + + +**BLUE** = `Color(0, 0, 1, 1)` [🔗](#class_Color_constant_BLUE) + +Blue color. + + + + + +**BLUE_VIOLET** = `Color(0.5411765, 0.16862746, 0.8862745, 1)` [🔗](#class_Color_constant_BLUE_VIOLET) + +Blue violet color. + + + + + +**BROWN** = `Color(0.64705884, 0.16470589, 0.16470589, 1)` [🔗](#class_Color_constant_BROWN) + +Brown color. + + + + + +**BURLYWOOD** = `Color(0.87058824, 0.72156864, 0.5294118, 1)` [🔗](#class_Color_constant_BURLYWOOD) + +Burlywood color. + + + + + +**CADET_BLUE** = `Color(0.37254903, 0.61960787, 0.627451, 1)` [🔗](#class_Color_constant_CADET_BLUE) + +Cadet blue color. + + + + + +**CHARTREUSE** = `Color(0.49803922, 1, 0, 1)` [🔗](#class_Color_constant_CHARTREUSE) + +Chartreuse color. + + + + + +**CHOCOLATE** = `Color(0.8235294, 0.4117647, 0.11764706, 1)` [🔗](#class_Color_constant_CHOCOLATE) + +Chocolate color. + + + + + +**CORAL** = `Color(1, 0.49803922, 0.3137255, 1)` [🔗](#class_Color_constant_CORAL) + +Coral color. + + + + + +**CORNFLOWER_BLUE** = `Color(0.39215687, 0.58431375, 0.92941177, 1)` [🔗](#class_Color_constant_CORNFLOWER_BLUE) + +Cornflower blue color. + + + + + +**CORNSILK** = `Color(1, 0.972549, 0.8627451, 1)` [🔗](#class_Color_constant_CORNSILK) + +Cornsilk color. + + + + + +**CRIMSON** = `Color(0.8627451, 0.078431375, 0.23529412, 1)` [🔗](#class_Color_constant_CRIMSON) + +Crimson color. + + + + + +**CYAN** = `Color(0, 1, 1, 1)` [🔗](#class_Color_constant_CYAN) + +Cyan color. + + + + + +**DARK_BLUE** = `Color(0, 0, 0.54509807, 1)` [🔗](#class_Color_constant_DARK_BLUE) + +Dark blue color. + + + + + +**DARK_CYAN** = `Color(0, 0.54509807, 0.54509807, 1)` [🔗](#class_Color_constant_DARK_CYAN) + +Dark cyan color. + + + + + +**DARK_GOLDENROD** = `Color(0.72156864, 0.5254902, 0.043137256, 1)` [🔗](#class_Color_constant_DARK_GOLDENROD) + +Dark goldenrod color. + + + + + +**DARK_GRAY** = `Color(0.6627451, 0.6627451, 0.6627451, 1)` [🔗](#class_Color_constant_DARK_GRAY) + +Dark gray color. + + + + + +**DARK_GREEN** = `Color(0, 0.39215687, 0, 1)` [🔗](#class_Color_constant_DARK_GREEN) + +Dark green color. + + + + + +**DARK_KHAKI** = `Color(0.7411765, 0.7176471, 0.41960785, 1)` [🔗](#class_Color_constant_DARK_KHAKI) + +Dark khaki color. + + + + + +**DARK_MAGENTA** = `Color(0.54509807, 0, 0.54509807, 1)` [🔗](#class_Color_constant_DARK_MAGENTA) + +Dark magenta color. + + + + + +**DARK_OLIVE_GREEN** = `Color(0.33333334, 0.41960785, 0.18431373, 1)` [🔗](#class_Color_constant_DARK_OLIVE_GREEN) + +Dark olive green color. + + + + + +**DARK_ORANGE** = `Color(1, 0.54901963, 0, 1)` [🔗](#class_Color_constant_DARK_ORANGE) + +Dark orange color. + + + + + +**DARK_ORCHID** = `Color(0.6, 0.19607843, 0.8, 1)` [🔗](#class_Color_constant_DARK_ORCHID) + +Dark orchid color. + + + + + +**DARK_RED** = `Color(0.54509807, 0, 0, 1)` [🔗](#class_Color_constant_DARK_RED) + +Dark red color. + + + + + +**DARK_SALMON** = `Color(0.9137255, 0.5882353, 0.47843137, 1)` [🔗](#class_Color_constant_DARK_SALMON) + +Dark salmon color. + + + + + +**DARK_SEA_GREEN** = `Color(0.56078434, 0.7372549, 0.56078434, 1)` [🔗](#class_Color_constant_DARK_SEA_GREEN) + +Dark sea green color. + + + + + +**DARK_SLATE_BLUE** = `Color(0.28235295, 0.23921569, 0.54509807, 1)` [🔗](#class_Color_constant_DARK_SLATE_BLUE) + +Dark slate blue color. + + + + + +**DARK_SLATE_GRAY** = `Color(0.18431373, 0.30980393, 0.30980393, 1)` [🔗](#class_Color_constant_DARK_SLATE_GRAY) + +Dark slate gray color. + + + + + +**DARK_TURQUOISE** = `Color(0, 0.80784315, 0.81960785, 1)` [🔗](#class_Color_constant_DARK_TURQUOISE) + +Dark turquoise color. + + + + + +**DARK_VIOLET** = `Color(0.5803922, 0, 0.827451, 1)` [🔗](#class_Color_constant_DARK_VIOLET) + +Dark violet color. + + + + + +**DEEP_PINK** = `Color(1, 0.078431375, 0.5764706, 1)` [🔗](#class_Color_constant_DEEP_PINK) + +Deep pink color. + + + + + +**DEEP_SKY_BLUE** = `Color(0, 0.7490196, 1, 1)` [🔗](#class_Color_constant_DEEP_SKY_BLUE) + +Deep sky blue color. + + + + + +**DIM_GRAY** = `Color(0.4117647, 0.4117647, 0.4117647, 1)` [🔗](#class_Color_constant_DIM_GRAY) + +Dim gray color. + + + + + +**DODGER_BLUE** = `Color(0.11764706, 0.5647059, 1, 1)` [🔗](#class_Color_constant_DODGER_BLUE) + +Dodger blue color. + + + + + +**FIREBRICK** = `Color(0.69803923, 0.13333334, 0.13333334, 1)` [🔗](#class_Color_constant_FIREBRICK) + +Firebrick color. + + + + + +**FLORAL_WHITE** = `Color(1, 0.98039216, 0.9411765, 1)` [🔗](#class_Color_constant_FLORAL_WHITE) + +Floral white color. + + + + + +**FOREST_GREEN** = `Color(0.13333334, 0.54509807, 0.13333334, 1)` [🔗](#class_Color_constant_FOREST_GREEN) + +Forest green color. + + + + + +**FUCHSIA** = `Color(1, 0, 1, 1)` [🔗](#class_Color_constant_FUCHSIA) + +Fuchsia color. + + + + + +**GAINSBORO** = `Color(0.8627451, 0.8627451, 0.8627451, 1)` [🔗](#class_Color_constant_GAINSBORO) + +Gainsboro color. + + + + + +**GHOST_WHITE** = `Color(0.972549, 0.972549, 1, 1)` [🔗](#class_Color_constant_GHOST_WHITE) + +Ghost white color. + + + + + +**GOLD** = `Color(1, 0.84313726, 0, 1)` [🔗](#class_Color_constant_GOLD) + +Gold color. + + + + + +**GOLDENROD** = `Color(0.85490197, 0.64705884, 0.1254902, 1)` [🔗](#class_Color_constant_GOLDENROD) + +Goldenrod color. + + + + + +**GRAY** = `Color(0.74509805, 0.74509805, 0.74509805, 1)` [🔗](#class_Color_constant_GRAY) + +Gray color. + + + + + +**GREEN** = `Color(0, 1, 0, 1)` [🔗](#class_Color_constant_GREEN) + +Green color. + + + + + +**GREEN_YELLOW** = `Color(0.6784314, 1, 0.18431373, 1)` [🔗](#class_Color_constant_GREEN_YELLOW) + +Green yellow color. + + + + + +**HONEYDEW** = `Color(0.9411765, 1, 0.9411765, 1)` [🔗](#class_Color_constant_HONEYDEW) + +Honeydew color. + + + + + +**HOT_PINK** = `Color(1, 0.4117647, 0.7058824, 1)` [🔗](#class_Color_constant_HOT_PINK) + +Hot pink color. + + + + + +**INDIAN_RED** = `Color(0.8039216, 0.36078432, 0.36078432, 1)` [🔗](#class_Color_constant_INDIAN_RED) + +Indian red color. + + + + + +**INDIGO** = `Color(0.29411766, 0, 0.50980395, 1)` [🔗](#class_Color_constant_INDIGO) + +Indigo color. + + + + + +**IVORY** = `Color(1, 1, 0.9411765, 1)` [🔗](#class_Color_constant_IVORY) + +Ivory color. + + + + + +**KHAKI** = `Color(0.9411765, 0.9019608, 0.54901963, 1)` [🔗](#class_Color_constant_KHAKI) + +Khaki color. + + + + + +**LAVENDER** = `Color(0.9019608, 0.9019608, 0.98039216, 1)` [🔗](#class_Color_constant_LAVENDER) + +Lavender color. + + + + + +**LAVENDER_BLUSH** = `Color(1, 0.9411765, 0.9607843, 1)` [🔗](#class_Color_constant_LAVENDER_BLUSH) + +Lavender blush color. + + + + + +**LAWN_GREEN** = `Color(0.4862745, 0.9882353, 0, 1)` [🔗](#class_Color_constant_LAWN_GREEN) + +Lawn green color. + + + + + +**LEMON_CHIFFON** = `Color(1, 0.98039216, 0.8039216, 1)` [🔗](#class_Color_constant_LEMON_CHIFFON) + +Lemon chiffon color. + + + + + +**LIGHT_BLUE** = `Color(0.6784314, 0.84705883, 0.9019608, 1)` [🔗](#class_Color_constant_LIGHT_BLUE) + +Light blue color. + + + + + +**LIGHT_CORAL** = `Color(0.9411765, 0.5019608, 0.5019608, 1)` [🔗](#class_Color_constant_LIGHT_CORAL) + +Light coral color. + + + + + +**LIGHT_CYAN** = `Color(0.8784314, 1, 1, 1)` [🔗](#class_Color_constant_LIGHT_CYAN) + +Light cyan color. + + + + + +**LIGHT_GOLDENROD** = `Color(0.98039216, 0.98039216, 0.8235294, 1)` [🔗](#class_Color_constant_LIGHT_GOLDENROD) + +Light goldenrod color. + + + + + +**LIGHT_GRAY** = `Color(0.827451, 0.827451, 0.827451, 1)` [🔗](#class_Color_constant_LIGHT_GRAY) + +Light gray color. + + + + + +**LIGHT_GREEN** = `Color(0.5647059, 0.93333334, 0.5647059, 1)` [🔗](#class_Color_constant_LIGHT_GREEN) + +Light green color. + + + + + +**LIGHT_PINK** = `Color(1, 0.7137255, 0.75686276, 1)` [🔗](#class_Color_constant_LIGHT_PINK) + +Light pink color. + + + + + +**LIGHT_SALMON** = `Color(1, 0.627451, 0.47843137, 1)` [🔗](#class_Color_constant_LIGHT_SALMON) + +Light salmon color. + + + + + +**LIGHT_SEA_GREEN** = `Color(0.1254902, 0.69803923, 0.6666667, 1)` [🔗](#class_Color_constant_LIGHT_SEA_GREEN) + +Light sea green color. + + + + + +**LIGHT_SKY_BLUE** = `Color(0.5294118, 0.80784315, 0.98039216, 1)` [🔗](#class_Color_constant_LIGHT_SKY_BLUE) + +Light sky blue color. + + + + + +**LIGHT_SLATE_GRAY** = `Color(0.46666667, 0.53333336, 0.6, 1)` [🔗](#class_Color_constant_LIGHT_SLATE_GRAY) + +Light slate gray color. + + + + + +**LIGHT_STEEL_BLUE** = `Color(0.6901961, 0.76862746, 0.87058824, 1)` [🔗](#class_Color_constant_LIGHT_STEEL_BLUE) + +Light steel blue color. + + + + + +**LIGHT_YELLOW** = `Color(1, 1, 0.8784314, 1)` [🔗](#class_Color_constant_LIGHT_YELLOW) + +Light yellow color. + + + + + +**LIME** = `Color(0, 1, 0, 1)` [🔗](#class_Color_constant_LIME) + +Lime color. + + + + + +**LIME_GREEN** = `Color(0.19607843, 0.8039216, 0.19607843, 1)` [🔗](#class_Color_constant_LIME_GREEN) + +Lime green color. + + + + + +**LINEN** = `Color(0.98039216, 0.9411765, 0.9019608, 1)` [🔗](#class_Color_constant_LINEN) + +Linen color. + + + + + +**MAGENTA** = `Color(1, 0, 1, 1)` [🔗](#class_Color_constant_MAGENTA) + +Magenta color. + + + + + +**MAROON** = `Color(0.6901961, 0.1882353, 0.3764706, 1)` [🔗](#class_Color_constant_MAROON) + +Maroon color. + + + + + +**MEDIUM_AQUAMARINE** = `Color(0.4, 0.8039216, 0.6666667, 1)` [🔗](#class_Color_constant_MEDIUM_AQUAMARINE) + +Medium aquamarine color. + + + + + +**MEDIUM_BLUE** = `Color(0, 0, 0.8039216, 1)` [🔗](#class_Color_constant_MEDIUM_BLUE) + +Medium blue color. + + + + + +**MEDIUM_ORCHID** = `Color(0.7294118, 0.33333334, 0.827451, 1)` [🔗](#class_Color_constant_MEDIUM_ORCHID) + +Medium orchid color. + + + + + +**MEDIUM_PURPLE** = `Color(0.5764706, 0.4392157, 0.85882354, 1)` [🔗](#class_Color_constant_MEDIUM_PURPLE) + +Medium purple color. + + + + + +**MEDIUM_SEA_GREEN** = `Color(0.23529412, 0.7019608, 0.44313726, 1)` [🔗](#class_Color_constant_MEDIUM_SEA_GREEN) + +Medium sea green color. + + + + + +**MEDIUM_SLATE_BLUE** = `Color(0.48235294, 0.40784314, 0.93333334, 1)` [🔗](#class_Color_constant_MEDIUM_SLATE_BLUE) + +Medium slate blue color. + + + + + +**MEDIUM_SPRING_GREEN** = `Color(0, 0.98039216, 0.6039216, 1)` [🔗](#class_Color_constant_MEDIUM_SPRING_GREEN) + +Medium spring green color. + + + + + +**MEDIUM_TURQUOISE** = `Color(0.28235295, 0.81960785, 0.8, 1)` [🔗](#class_Color_constant_MEDIUM_TURQUOISE) + +Medium turquoise color. + + + + + +**MEDIUM_VIOLET_RED** = `Color(0.78039217, 0.08235294, 0.52156866, 1)` [🔗](#class_Color_constant_MEDIUM_VIOLET_RED) + +Medium violet red color. + + + + + +**MIDNIGHT_BLUE** = `Color(0.09803922, 0.09803922, 0.4392157, 1)` [🔗](#class_Color_constant_MIDNIGHT_BLUE) + +Midnight blue color. + + + + + +**MINT_CREAM** = `Color(0.9607843, 1, 0.98039216, 1)` [🔗](#class_Color_constant_MINT_CREAM) + +Mint cream color. + + + + + +**MISTY_ROSE** = `Color(1, 0.89411765, 0.88235295, 1)` [🔗](#class_Color_constant_MISTY_ROSE) + +Misty rose color. + + + + + +**MOCCASIN** = `Color(1, 0.89411765, 0.70980394, 1)` [🔗](#class_Color_constant_MOCCASIN) + +Moccasin color. + + + + + +**NAVAJO_WHITE** = `Color(1, 0.87058824, 0.6784314, 1)` [🔗](#class_Color_constant_NAVAJO_WHITE) + +Navajo white color. + + + + + +**NAVY_BLUE** = `Color(0, 0, 0.5019608, 1)` [🔗](#class_Color_constant_NAVY_BLUE) + +Navy blue color. + + + + + +**OLD_LACE** = `Color(0.99215686, 0.9607843, 0.9019608, 1)` [🔗](#class_Color_constant_OLD_LACE) + +Old lace color. + + + + + +**OLIVE** = `Color(0.5019608, 0.5019608, 0, 1)` [🔗](#class_Color_constant_OLIVE) + +Olive color. + + + + + +**OLIVE_DRAB** = `Color(0.41960785, 0.5568628, 0.13725491, 1)` [🔗](#class_Color_constant_OLIVE_DRAB) + +Olive drab color. + + + + + +**ORANGE** = `Color(1, 0.64705884, 0, 1)` [🔗](#class_Color_constant_ORANGE) + +Orange color. + + + + + +**ORANGE_RED** = `Color(1, 0.27058825, 0, 1)` [🔗](#class_Color_constant_ORANGE_RED) + +Orange red color. + + + + + +**ORCHID** = `Color(0.85490197, 0.4392157, 0.8392157, 1)` [🔗](#class_Color_constant_ORCHID) + +Orchid color. + + + + + +**PALE_GOLDENROD** = `Color(0.93333334, 0.9098039, 0.6666667, 1)` [🔗](#class_Color_constant_PALE_GOLDENROD) + +Pale goldenrod color. + + + + + +**PALE_GREEN** = `Color(0.59607846, 0.9843137, 0.59607846, 1)` [🔗](#class_Color_constant_PALE_GREEN) + +Pale green color. + + + + + +**PALE_TURQUOISE** = `Color(0.6862745, 0.93333334, 0.93333334, 1)` [🔗](#class_Color_constant_PALE_TURQUOISE) + +Pale turquoise color. + + + + + +**PALE_VIOLET_RED** = `Color(0.85882354, 0.4392157, 0.5764706, 1)` [🔗](#class_Color_constant_PALE_VIOLET_RED) + +Pale violet red color. + + + + + +**PAPAYA_WHIP** = `Color(1, 0.9372549, 0.8352941, 1)` [🔗](#class_Color_constant_PAPAYA_WHIP) + +Papaya whip color. + + + + + +**PEACH_PUFF** = `Color(1, 0.85490197, 0.7254902, 1)` [🔗](#class_Color_constant_PEACH_PUFF) + +Peach puff color. + + + + + +**PERU** = `Color(0.8039216, 0.52156866, 0.24705882, 1)` [🔗](#class_Color_constant_PERU) + +Peru color. + + + + + +**PINK** = `Color(1, 0.7529412, 0.79607844, 1)` [🔗](#class_Color_constant_PINK) + +Pink color. + + + + + +**PLUM** = `Color(0.8666667, 0.627451, 0.8666667, 1)` [🔗](#class_Color_constant_PLUM) + +Plum color. + + + + + +**POWDER_BLUE** = `Color(0.6901961, 0.8784314, 0.9019608, 1)` [🔗](#class_Color_constant_POWDER_BLUE) + +Powder blue color. + + + + + +**PURPLE** = `Color(0.627451, 0.1254902, 0.9411765, 1)` [🔗](#class_Color_constant_PURPLE) + +Purple color. + + + + + +**REBECCA_PURPLE** = `Color(0.4, 0.2, 0.6, 1)` [🔗](#class_Color_constant_REBECCA_PURPLE) + +Rebecca purple color. + + + + + +**RED** = `Color(1, 0, 0, 1)` [🔗](#class_Color_constant_RED) + +Red color. + + + + + +**ROSY_BROWN** = `Color(0.7372549, 0.56078434, 0.56078434, 1)` [🔗](#class_Color_constant_ROSY_BROWN) + +Rosy brown color. + + + + + +**ROYAL_BLUE** = `Color(0.25490198, 0.4117647, 0.88235295, 1)` [🔗](#class_Color_constant_ROYAL_BLUE) + +Royal blue color. + + + + + +**SADDLE_BROWN** = `Color(0.54509807, 0.27058825, 0.07450981, 1)` [🔗](#class_Color_constant_SADDLE_BROWN) + +Saddle brown color. + + + + + +**SALMON** = `Color(0.98039216, 0.5019608, 0.44705883, 1)` [🔗](#class_Color_constant_SALMON) + +Salmon color. + + + + + +**SANDY_BROWN** = `Color(0.95686275, 0.6431373, 0.3764706, 1)` [🔗](#class_Color_constant_SANDY_BROWN) + +Sandy brown color. + + + + + +**SEA_GREEN** = `Color(0.18039216, 0.54509807, 0.34117648, 1)` [🔗](#class_Color_constant_SEA_GREEN) + +Sea green color. + + + + + +**SEASHELL** = `Color(1, 0.9607843, 0.93333334, 1)` [🔗](#class_Color_constant_SEASHELL) + +Seashell color. + + + + + +**SIENNA** = `Color(0.627451, 0.32156864, 0.1764706, 1)` [🔗](#class_Color_constant_SIENNA) + +Sienna color. + + + + + +**SILVER** = `Color(0.7529412, 0.7529412, 0.7529412, 1)` [🔗](#class_Color_constant_SILVER) + +Silver color. + + + + + +**SKY_BLUE** = `Color(0.5294118, 0.80784315, 0.92156863, 1)` [🔗](#class_Color_constant_SKY_BLUE) + +Sky blue color. + + + + + +**SLATE_BLUE** = `Color(0.41568628, 0.3529412, 0.8039216, 1)` [🔗](#class_Color_constant_SLATE_BLUE) + +Slate blue color. + + + + + +**SLATE_GRAY** = `Color(0.4392157, 0.5019608, 0.5647059, 1)` [🔗](#class_Color_constant_SLATE_GRAY) + +Slate gray color. + + + + + +**SNOW** = `Color(1, 0.98039216, 0.98039216, 1)` [🔗](#class_Color_constant_SNOW) + +Snow color. + + + + + +**SPRING_GREEN** = `Color(0, 1, 0.49803922, 1)` [🔗](#class_Color_constant_SPRING_GREEN) + +Spring green color. + + + + + +**STEEL_BLUE** = `Color(0.27450982, 0.50980395, 0.7058824, 1)` [🔗](#class_Color_constant_STEEL_BLUE) + +Steel blue color. + + + + + +**TAN** = `Color(0.8235294, 0.7058824, 0.54901963, 1)` [🔗](#class_Color_constant_TAN) + +Tan color. + + + + + +**TEAL** = `Color(0, 0.5019608, 0.5019608, 1)` [🔗](#class_Color_constant_TEAL) + +Teal color. + + + + + +**THISTLE** = `Color(0.84705883, 0.7490196, 0.84705883, 1)` [🔗](#class_Color_constant_THISTLE) + +Thistle color. + + + + + +**TOMATO** = `Color(1, 0.3882353, 0.2784314, 1)` [🔗](#class_Color_constant_TOMATO) + +Tomato color. + + + + + +**TRANSPARENT** = `Color(1, 1, 1, 0)` [🔗](#class_Color_constant_TRANSPARENT) + +Transparent color (white with zero alpha). + + + + + +**TURQUOISE** = `Color(0.2509804, 0.8784314, 0.8156863, 1)` [🔗](#class_Color_constant_TURQUOISE) + +Turquoise color. + + + + + +**VIOLET** = `Color(0.93333334, 0.50980395, 0.93333334, 1)` [🔗](#class_Color_constant_VIOLET) + +Violet color. + + + + + +**WEB_GRAY** = `Color(0.5019608, 0.5019608, 0.5019608, 1)` [🔗](#class_Color_constant_WEB_GRAY) + +Web gray color. + + + + + +**WEB_GREEN** = `Color(0, 0.5019608, 0, 1)` [🔗](#class_Color_constant_WEB_GREEN) + +Web green color. + + + + + +**WEB_MAROON** = `Color(0.5019608, 0, 0, 1)` [🔗](#class_Color_constant_WEB_MAROON) + +Web maroon color. + + + + + +**WEB_PURPLE** = `Color(0.5019608, 0, 0.5019608, 1)` [🔗](#class_Color_constant_WEB_PURPLE) + +Web purple color. + + + + + +**WHEAT** = `Color(0.9607843, 0.87058824, 0.7019608, 1)` [🔗](#class_Color_constant_WHEAT) + +Wheat color. + + + + + +**WHITE** = `Color(1, 1, 1, 1)` [🔗](#class_Color_constant_WHITE) + +White color. + + + + + +**WHITE_SMOKE** = `Color(0.9607843, 0.9607843, 0.9607843, 1)` [🔗](#class_Color_constant_WHITE_SMOKE) + +White smoke color. + + + + + +**YELLOW** = `Color(1, 1, 0, 1)` [🔗](#class_Color_constant_YELLOW) + +Yellow color. + + + + + +**YELLOW_GREEN** = `Color(0.6039216, 0.8039216, 0.19607843, 1)` [🔗](#class_Color_constant_YELLOW_GREEN) + +Yellow green color. + +
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **a** = `1.0` [🔗](#class_Color_property_a) + +The color's alpha component, typically on the range of 0 to 1. A value of 0 means that the color is fully transparent. A value of 1 means that the color is fully opaque. + +\ **Note:** The alpha channel is always stored with linear encoding, regardless of the color space of the other color channels. The [linear_to_srgb()](class_color.md#class_Color_method_linear_to_srgb) and [srgb_to_linear()](class_color.md#class_Color_method_srgb_to_linear) methods do not affect the alpha channel. + +
+ + + + + +[int](class_int.md) **a8** = `255` [🔗](#class_Color_property_a8) + +Wrapper for [a](class_color.md#class_Color_property_a) that uses the range 0 to 255, instead of 0 to 1. + +
+ + + + + +[float](class_float.md) **b** = `0.0` [🔗](#class_Color_property_b) + +The color's blue component, typically on the range of 0 to 1. + +
+ + + + + +[int](class_int.md) **b8** = `0` [🔗](#class_Color_property_b8) + +Wrapper for [b](class_color.md#class_Color_property_b) that uses the range 0 to 255, instead of 0 to 1. + +
+ + + + + +[float](class_float.md) **g** = `0.0` [🔗](#class_Color_property_g) + +The color's green component, typically on the range of 0 to 1. + +
+ + + + + +[int](class_int.md) **g8** = `0` [🔗](#class_Color_property_g8) + +Wrapper for [g](class_color.md#class_Color_property_g) that uses the range 0 to 255, instead of 0 to 1. + +
+ + + + + +[float](class_float.md) **h** = `0.0` [🔗](#class_Color_property_h) + +The HSV hue of this color, on the range 0 to 1. + +
+ + + + + +[float](class_float.md) **ok_hsl_h** = `0.0` [🔗](#class_Color_property_ok_hsl_h) + +The OKHSL hue of this color, on the range 0 to 1. + +
+ + + + + +[float](class_float.md) **ok_hsl_l** = `0.0` [🔗](#class_Color_property_ok_hsl_l) + +The OKHSL lightness of this color, on the range 0 to 1. + +
+ + + + + +[float](class_float.md) **ok_hsl_s** = `0.0` [🔗](#class_Color_property_ok_hsl_s) + +The OKHSL saturation of this color, on the range 0 to 1. + +
+ + + + + +[float](class_float.md) **r** = `0.0` [🔗](#class_Color_property_r) + +The color's red component, typically on the range of 0 to 1. + +
+ + + + + +[int](class_int.md) **r8** = `0` [🔗](#class_Color_property_r8) + +Wrapper for [r](class_color.md#class_Color_property_r) that uses the range 0 to 255, instead of 0 to 1. + +
+ + + + + +[float](class_float.md) **s** = `0.0` [🔗](#class_Color_property_s) + +The HSV saturation of this color, on the range 0 to 1. + +
+ + + + + +[float](class_float.md) **v** = `0.0` [🔗](#class_Color_property_v) + +The HSV value (brightness) of this color, on the range 0 to 1. + +
+ + + +## Constructor Descriptions + + + + + +[Color](class_color.md) **Color**\ (\ ) [🔗](#class_Color_constructor_Color) + +Constructs a default **Color** from opaque black. This is the same as [BLACK](class_color.md#class_Color_constant_BLACK). + +\ **Note:** In C#, this constructs a **Color** with all of its components set to ``0.0`` (transparent black). + +
+ + + +[Color](class_color.md) **Color**\ (\ from\: [Color](class_color.md), alpha\: [float](class_float.md)\ ) + +Constructs a **Color** from the existing color, with [a](class_color.md#class_Color_property_a) set to the given `alpha` value. + + + + +```gdscript + var red = Color(Color.RED, 0.2) # 20% opaque red. +``` + +```csharp + var red = new Color(Colors.Red, 0.2f); // 20% opaque red. +``` + + + +
+ + + +[Color](class_color.md) **Color**\ (\ from\: [Color](class_color.md)\ ) + +Constructs a **Color** as a copy of the given **Color**. + +
+ + + +[Color](class_color.md) **Color**\ (\ code\: [String](class_string.md)\ ) + +Constructs a **Color** either from an HTML color code or from a standardized color name. The supported color names are the same as the constants. + +
+ + + +[Color](class_color.md) **Color**\ (\ code\: [String](class_string.md), alpha\: [float](class_float.md)\ ) + +Constructs a **Color** either from an HTML color code or from a standardized color name, with `alpha` on the range of 0.0 to 1.0. The supported color names are the same as the constants. + +
+ + + +[Color](class_color.md) **Color**\ (\ r\: [float](class_float.md), g\: [float](class_float.md), b\: [float](class_float.md)\ ) + +Constructs a **Color** from RGB values, typically between 0.0 and 1.0. [a](class_color.md#class_Color_property_a) is set to 1.0. + + + + +```gdscript + var color = Color(0.2, 1.0, 0.7) # Similar to `Color8(51, 255, 178, 255)` +``` + +```csharp + var color = new Color(0.2f, 1.0f, 0.7f); // Similar to `Color.Color8(51, 255, 178, 255)` +``` + + + +
+ + + +[Color](class_color.md) **Color**\ (\ r\: [float](class_float.md), g\: [float](class_float.md), b\: [float](class_float.md), a\: [float](class_float.md)\ ) + +Constructs a **Color** from RGBA values, typically between 0.0 and 1.0. + + + + +```gdscript + var color = Color(0.2, 1.0, 0.7, 0.8) # Similar to `Color8(51, 255, 178, 204)` +``` + +```csharp + var color = new Color(0.2f, 1.0f, 0.7f, 0.8f); // Similar to `Color.Color8(51, 255, 178, 255, 204)` +``` + + + +
+ + + +## Method Descriptions + + + + + +[Color](class_color.md) **blend**\ (\ over\: [Color](class_color.md)\ ) const [🔗](#class_Color_method_blend) + +Returns a new color resulting from overlaying this color over the given color. In a painting program, you can imagine it as the `over` color painted over this color (including alpha). + + + + +```gdscript + var bg = Color(0.0, 1.0, 0.0, 0.5) # Green with alpha of 50% + var fg = Color(1.0, 0.0, 0.0, 0.5) # Red with alpha of 50% + var blended_color = bg.blend(fg) # Brown with alpha of 75% +``` + +```csharp + var bg = new Color(0.0f, 1.0f, 0.0f, 0.5f); // Green with alpha of 50% + var fg = new Color(1.0f, 0.0f, 0.0f, 0.5f); // Red with alpha of 50% + Color blendedColor = bg.Blend(fg); // Brown with alpha of 75% +``` + + + +
+ + + + + +[Color](class_color.md) **clamp**\ (\ min\: [Color](class_color.md) = Color(0, 0, 0, 0), max\: [Color](class_color.md) = Color(1, 1, 1, 1)\ ) const [🔗](#class_Color_method_clamp) + +Returns a new color with all components clamped between the components of `min` and `max`, by running [@GlobalScope.clamp()](class_@globalscope.md#class_@GlobalScope_method_clamp) on each component. + +
+ + + + + +[Color](class_color.md) **darkened**\ (\ amount\: [float](class_float.md)\ ) const [🔗](#class_Color_method_darkened) + +Returns a new color resulting from making this color darker by the specified `amount` (ratio from 0.0 to 1.0). See also [lightened()](class_color.md#class_Color_method_lightened). + + + + +```gdscript + var green = Color(0.0, 1.0, 0.0) + var darkgreen = green.darkened(0.2) # 20% darker than regular green +``` + +```csharp + var green = new Color(0.0f, 1.0f, 0.0f); + Color darkgreen = green.Darkened(0.2f); // 20% darker than regular green +``` + + + +
+ + + + + +[Color](class_color.md) **from_hsv**\ (\ h\: [float](class_float.md), s\: [float](class_float.md), v\: [float](class_float.md), alpha\: [float](class_float.md) = 1.0\ ) static [🔗](#class_Color_method_from_hsv) + +Constructs a color from an [HSV profile](https://en.wikipedia.org/wiki/HSL_and_HSV). The hue (`h`), saturation (`s`), and value (`v`) are typically between 0.0 and 1.0. + + + + +```gdscript + var color = Color.from_hsv(0.58, 0.5, 0.79, 0.8) +``` + +```csharp + var color = Color.FromHsv(0.58f, 0.5f, 0.79f, 0.8f); +``` + + + +
+ + + + + +[Color](class_color.md) **from_ok_hsl**\ (\ h\: [float](class_float.md), s\: [float](class_float.md), l\: [float](class_float.md), alpha\: [float](class_float.md) = 1.0\ ) static [🔗](#class_Color_method_from_ok_hsl) + +Constructs a color from an [OK HSL profile](https://bottosson.github.io/posts/colorpicker/). The hue (`h`), saturation (`s`), and lightness (`l`) are typically between 0.0 and 1.0. + + + + +```gdscript + var color = Color.from_ok_hsl(0.58, 0.5, 0.79, 0.8) +``` + +```csharp + var color = Color.FromOkHsl(0.58f, 0.5f, 0.79f, 0.8f); +``` + + + +
+ + + + + +[Color](class_color.md) **from_rgba8**\ (\ r8\: [int](class_int.md), g8\: [int](class_int.md), b8\: [int](class_int.md), a8\: [int](class_int.md) = 255\ ) static [🔗](#class_Color_method_from_rgba8) + +Returns a **Color** constructed from red (`r8`), green (`g8`), blue (`b8`), and optionally alpha (`a8`) integer channels, each divided by ``255.0`` for their final value. + +``` + var red = Color.from_rgba8(255, 0, 0) # Same as Color(1, 0, 0). + var dark_blue = Color.from_rgba8(0, 0, 51) # Same as Color(0, 0, 0.2). + var my_color = Color.from_rgba8(306, 255, 0, 102) # Same as Color(1.2, 1, 0, 0.4). +``` + +\ **Note:** Due to the lower precision of [from_rgba8()](class_color.md#class_Color_method_from_rgba8) compared to the standard **Color** constructor, a color created with [from_rgba8()](class_color.md#class_Color_method_from_rgba8) will generally not be equal to the same color created with the standard **Color** constructor. Use [is_equal_approx()](class_color.md#class_Color_method_is_equal_approx) for comparisons to avoid issues with floating-point precision error. + +
+ + + + + +[Color](class_color.md) **from_rgbe9995**\ (\ rgbe\: [int](class_int.md)\ ) static [🔗](#class_Color_method_from_rgbe9995) + +Decodes a **Color** from an RGBE9995 format integer. See [Image.FORMAT_RGBE9995](class_image.md#class_Image_constant_FORMAT_RGBE9995). + +
+ + + + + +[Color](class_color.md) **from_string**\ (\ str\: [String](class_string.md), default\: [Color](class_color.md)\ ) static [🔗](#class_Color_method_from_string) + +Creates a **Color** from the given string, which can be either an HTML color code or a named color (case-insensitive). Returns `default` if the color cannot be inferred from the string. + +If you want to create a color from String in a constant expression, use the equivalent constructor instead (i.e. ``Color("color string")``). + +
+ + + + + +[float](class_float.md) **get_luminance**\ (\ ) const [🔗](#class_Color_method_get_luminance) + +Returns the light intensity of the color, as a value between 0.0 and 1.0 (inclusive). This is useful when determining light or dark color. Colors with a luminance smaller than 0.5 can be generally considered dark. + +\ **Note:** [get_luminance()](class_color.md#class_Color_method_get_luminance) relies on the color being in the linear color space to return an accurate relative luminance value. If the color is in the sRGB color space, use [srgb_to_linear()](class_color.md#class_Color_method_srgb_to_linear) to convert it to the linear color space first. + +
+ + + + + +[Color](class_color.md) **hex**\ (\ hex\: [int](class_int.md)\ ) static [🔗](#class_Color_method_hex) + +Returns the **Color** associated with the provided `hex` integer in 32-bit RGBA format (8 bits per channel). This method is the inverse of [to_rgba32()](class_color.md#class_Color_method_to_rgba32). + +In GDScript and C#, the [int](class_int.md) is best visualized with hexadecimal notation (``"0x"`` prefix, making it ``"0xRRGGBBAA"``). + + + + +```gdscript + var red = Color.hex(0xff0000ff) + var dark_cyan = Color.hex(0x008b8bff) + var my_color = Color.hex(0xbbefd2a4) +``` + +```csharp + var red = new Color(0xff0000ff); + var dark_cyan = new Color(0x008b8bff); + var my_color = new Color(0xbbefd2a4); +``` + + + +If you want to use hex notation in a constant expression, use the equivalent constructor instead (i.e. ``Color(0xRRGGBBAA)``). + +
+ + + + + +[Color](class_color.md) **hex64**\ (\ hex\: [int](class_int.md)\ ) static [🔗](#class_Color_method_hex64) + +Returns the **Color** associated with the provided `hex` integer in 64-bit RGBA format (16 bits per channel). This method is the inverse of [to_rgba64()](class_color.md#class_Color_method_to_rgba64). + +In GDScript and C#, the [int](class_int.md) is best visualized with hexadecimal notation (``"0x"`` prefix, making it ``"0xRRRRGGGGBBBBAAAA"``). + +
+ + + + + +[Color](class_color.md) **html**\ (\ rgba\: [String](class_string.md)\ ) static [🔗](#class_Color_method_html) + +Returns a new color from `rgba`, an HTML hexadecimal color string. `rgba` is not case-sensitive, and may be prefixed by a hash sign (``#``). + +\ `rgba` must be a valid three-digit or six-digit hexadecimal color string, and may contain an alpha channel value. If `rgba` does not contain an alpha channel value, an alpha channel value of 1.0 is applied. If `rgba` is invalid, returns an empty color. + + + + +```gdscript + var blue = Color.html("#0000ff") # blue is Color(0.0, 0.0, 1.0, 1.0) + var green = Color.html("#0F0") # green is Color(0.0, 1.0, 0.0, 1.0) + var col = Color.html("663399cc") # col is Color(0.4, 0.2, 0.6, 0.8) +``` + +```csharp + var blue = Color.FromHtml("#0000ff"); // blue is Color(0.0, 0.0, 1.0, 1.0) + var green = Color.FromHtml("#0F0"); // green is Color(0.0, 1.0, 0.0, 1.0) + var col = Color.FromHtml("663399cc"); // col is Color(0.4, 0.2, 0.6, 0.8) +``` + + + +
+ + + + + +[bool](class_bool.md) **html_is_valid**\ (\ color\: [String](class_string.md)\ ) static [🔗](#class_Color_method_html_is_valid) + +Returns ``true`` if `color` is a valid HTML hexadecimal color string. The string must be a hexadecimal value (case-insensitive) of either 3, 4, 6 or 8 digits, and may be prefixed by a hash sign (``#``). This method is identical to [String.is_valid_html_color()](class_string.md#class_String_method_is_valid_html_color). + + + + +```gdscript + Color.html_is_valid("#55aaFF") # Returns true + Color.html_is_valid("#55AAFF20") # Returns true + Color.html_is_valid("55AAFF") # Returns true + Color.html_is_valid("#F2C") # Returns true + + Color.html_is_valid("#AABBC") # Returns false + Color.html_is_valid("#55aaFF5") # Returns false +``` + +```csharp + Color.HtmlIsValid("#55AAFF"); // Returns true + Color.HtmlIsValid("#55AAFF20"); // Returns true + Color.HtmlIsValid("55AAFF"); // Returns true + Color.HtmlIsValid("#F2C"); // Returns true + + Color.HtmlIsValid("#AABBC"); // Returns false + Color.HtmlIsValid("#55aaFF5"); // Returns false +``` + + + +
+ + + + + +[Color](class_color.md) **inverted**\ (\ ) const [🔗](#class_Color_method_inverted) + +Returns the color with its [r](class_color.md#class_Color_property_r), [g](class_color.md#class_Color_property_g), and [b](class_color.md#class_Color_property_b) components inverted (``(1 - r, 1 - g, 1 - b, a)``). + + + + +```gdscript + var black = Color.WHITE.inverted() + var color = Color(0.3, 0.4, 0.9) + var inverted_color = color.inverted() # Equivalent to `Color(0.7, 0.6, 0.1)` +``` + +```csharp + var black = Colors.White.Inverted(); + var color = new Color(0.3f, 0.4f, 0.9f); + Color invertedColor = color.Inverted(); // Equivalent to `new Color(0.7f, 0.6f, 0.1f)` +``` + + + +
+ + + + + +[bool](class_bool.md) **is_equal_approx**\ (\ to\: [Color](class_color.md)\ ) const [🔗](#class_Color_method_is_equal_approx) + +Returns ``true`` if this color and `to` are approximately equal, by running [@GlobalScope.is_equal_approx()](class_@globalscope.md#class_@GlobalScope_method_is_equal_approx) on each component. + +
+ + + + + +[Color](class_color.md) **lerp**\ (\ to\: [Color](class_color.md), weight\: [float](class_float.md)\ ) const [🔗](#class_Color_method_lerp) + +Returns the linear interpolation between this color's components and `to`'s components. The interpolation factor `weight` should be between 0.0 and 1.0 (inclusive). See also [@GlobalScope.lerp()](class_@globalscope.md#class_@GlobalScope_method_lerp). + + + + +```gdscript + var red = Color(1.0, 0.0, 0.0) + var aqua = Color(0.0, 1.0, 0.8) + + red.lerp(aqua, 0.2) # Returns Color(0.8, 0.2, 0.16) + red.lerp(aqua, 0.5) # Returns Color(0.5, 0.5, 0.4) + red.lerp(aqua, 1.0) # Returns Color(0.0, 1.0, 0.8) +``` + +```csharp + var red = new Color(1.0f, 0.0f, 0.0f); + var aqua = new Color(0.0f, 1.0f, 0.8f); + + red.Lerp(aqua, 0.2f); // Returns Color(0.8f, 0.2f, 0.16f) + red.Lerp(aqua, 0.5f); // Returns Color(0.5f, 0.5f, 0.4f) + red.Lerp(aqua, 1.0f); // Returns Color(0.0f, 1.0f, 0.8f) +``` + + + +
+ + + + + +[Color](class_color.md) **lightened**\ (\ amount\: [float](class_float.md)\ ) const [🔗](#class_Color_method_lightened) + +Returns a new color resulting from making this color lighter by the specified `amount`, which should be a ratio from 0.0 to 1.0. See also [darkened()](class_color.md#class_Color_method_darkened). + + + + +```gdscript + var green = Color(0.0, 1.0, 0.0) + var light_green = green.lightened(0.2) # 20% lighter than regular green +``` + +```csharp + var green = new Color(0.0f, 1.0f, 0.0f); + Color lightGreen = green.Lightened(0.2f); // 20% lighter than regular green +``` + + + +
+ + + + + +[Color](class_color.md) **linear_to_srgb**\ (\ ) const [🔗](#class_Color_method_linear_to_srgb) + +Returns the color converted to the [sRGB](https://en.wikipedia.org/wiki/SRGB) color space. This method assumes the original color is in the linear color space. See also [srgb_to_linear()](class_color.md#class_Color_method_srgb_to_linear) which performs the opposite operation. + +\ **Note:** The color's [a](class_color.md#class_Color_property_a)\ lpha channel is not affected. The alpha channel is always stored with linear encoding, regardless of the color space of the other color channels. + +
+ + + + + +[Color](class_color.md) **srgb_to_linear**\ (\ ) const [🔗](#class_Color_method_srgb_to_linear) + +Returns the color converted to the linear color space. This method assumes the original color already is in the sRGB color space. See also [linear_to_srgb()](class_color.md#class_Color_method_linear_to_srgb) which performs the opposite operation. + +\ **Note:** The color's [a](class_color.md#class_Color_property_a)\ lpha channel is not affected. The alpha channel is always stored with linear encoding, regardless of the color space of the other color channels. + +
+ + + + + +[int](class_int.md) **to_abgr32**\ (\ ) const [🔗](#class_Color_method_to_abgr32) + +Returns the color converted to a 32-bit integer in ABGR format (each component is 8 bits). ABGR is the reversed version of the default RGBA format. + + + + +```gdscript + var color = Color(1, 0.5, 0.2) + print(color.to_abgr32()) # Prints 4281565439 +``` + +```csharp + var color = new Color(1.0f, 0.5f, 0.2f); + GD.Print(color.ToAbgr32()); // Prints 4281565439 +``` + + + +
+ + + + + +[int](class_int.md) **to_abgr64**\ (\ ) const [🔗](#class_Color_method_to_abgr64) + +Returns the color converted to a 64-bit integer in ABGR format (each component is 16 bits). ABGR is the reversed version of the default RGBA format. + + + + +```gdscript + var color = Color(1, 0.5, 0.2) + print(color.to_abgr64()) # Prints -225178692812801 +``` + +```csharp + var color = new Color(1.0f, 0.5f, 0.2f); + GD.Print(color.ToAbgr64()); // Prints -225178692812801 +``` + + + +
+ + + + + +[int](class_int.md) **to_argb32**\ (\ ) const [🔗](#class_Color_method_to_argb32) + +Returns the color converted to a 32-bit integer in ARGB format (each component is 8 bits). ARGB is more compatible with DirectX. + + + + +```gdscript + var color = Color(1, 0.5, 0.2) + print(color.to_argb32()) # Prints 4294934323 +``` + +```csharp + var color = new Color(1.0f, 0.5f, 0.2f); + GD.Print(color.ToArgb32()); // Prints 4294934323 +``` + + + +
+ + + + + +[int](class_int.md) **to_argb64**\ (\ ) const [🔗](#class_Color_method_to_argb64) + +Returns the color converted to a 64-bit integer in ARGB format (each component is 16 bits). ARGB is more compatible with DirectX. + + + + +```gdscript + var color = Color(1, 0.5, 0.2) + print(color.to_argb64()) # Prints -2147470541 +``` + +```csharp + var color = new Color(1.0f, 0.5f, 0.2f); + GD.Print(color.ToArgb64()); // Prints -2147470541 +``` + + + +
+ + + + + +[String](class_string.md) **to_html**\ (\ with_alpha\: [bool](class_bool.md) = true\ ) const [🔗](#class_Color_method_to_html) + +Returns the color converted to an HTML hexadecimal color [String](class_string.md) in RGBA format, without the hash (``#``) prefix. + +Setting `with_alpha` to ``false``, excludes alpha from the hexadecimal string, using RGB format instead of RGBA format. + + + + +```gdscript + var white = Color(1, 1, 1, 0.5) + var with_alpha = white.to_html() # Returns "ffffff7f" + var without_alpha = white.to_html(false) # Returns "ffffff" +``` + +```csharp + var white = new Color(1, 1, 1, 0.5f); + string withAlpha = white.ToHtml(); // Returns "ffffff7f" + string withoutAlpha = white.ToHtml(false); // Returns "ffffff" +``` + + + +
+ + + + + +[int](class_int.md) **to_rgba32**\ (\ ) const [🔗](#class_Color_method_to_rgba32) + +Returns the color converted to a 32-bit integer in RGBA format (each component is 8 bits). RGBA is Redot's default format. This method is the inverse of [hex()](class_color.md#class_Color_method_hex). + + + + +```gdscript + var color = Color(1, 0.5, 0.2) + print(color.to_rgba32()) # Prints 4286526463 +``` + +```csharp + var color = new Color(1, 0.5f, 0.2f); + GD.Print(color.ToRgba32()); // Prints 4286526463 +``` + + + +
+ + + + + +[int](class_int.md) **to_rgba64**\ (\ ) const [🔗](#class_Color_method_to_rgba64) + +Returns the color converted to a 64-bit integer in RGBA format (each component is 16 bits). RGBA is Redot's default format. This method is the inverse of [hex64()](class_color.md#class_Color_method_hex64). + + + + +```gdscript + var color = Color(1, 0.5, 0.2) + print(color.to_rgba64()) # Prints -140736629309441 +``` + +```csharp + var color = new Color(1, 0.5f, 0.2f); + GD.Print(color.ToRgba64()); // Prints -140736629309441 +``` + + + +
+ + + +## Operator Descriptions + + + + + +[bool](class_bool.md) **operator !=**\ (\ right\: [Color](class_color.md)\ ) [🔗](#class_Color_operator_neq_Color) + +Returns ``true`` if the colors are not exactly equal. + +\ **Note:** Due to floating-point precision errors, consider using [is_equal_approx()](class_color.md#class_Color_method_is_equal_approx) instead, which is more reliable. + +
+ + + + + +[Color](class_color.md) **operator ***\ (\ right\: [Color](class_color.md)\ ) [🔗](#class_Color_operator_mul_Color) + +Multiplies each component of the **Color** by the components of the given **Color**. + +
+ + + + + +[Color](class_color.md) **operator ***\ (\ right\: [float](class_float.md)\ ) [🔗](#class_Color_operator_mul_float) + +Multiplies each component of the **Color** by the given [float](class_float.md). + +
+ + + + + +[Color](class_color.md) **operator ***\ (\ right\: [int](class_int.md)\ ) [🔗](#class_Color_operator_mul_int) + +Multiplies each component of the **Color** by the given [int](class_int.md). + +
+ + + + + +[Color](class_color.md) **operator +**\ (\ right\: [Color](class_color.md)\ ) [🔗](#class_Color_operator_sum_Color) + +Adds each component of the **Color** with the components of the given **Color**. + +
+ + + + + +[Color](class_color.md) **operator -**\ (\ right\: [Color](class_color.md)\ ) [🔗](#class_Color_operator_dif_Color) + +Subtracts each component of the **Color** by the components of the given **Color**. + +
+ + + + + +[Color](class_color.md) **operator /**\ (\ right\: [Color](class_color.md)\ ) [🔗](#class_Color_operator_div_Color) + +Divides each component of the **Color** by the components of the given **Color**. + +
+ + + + + +[Color](class_color.md) **operator /**\ (\ right\: [float](class_float.md)\ ) [🔗](#class_Color_operator_div_float) + +Divides each component of the **Color** by the given [float](class_float.md). + +
+ + + + + +[Color](class_color.md) **operator /**\ (\ right\: [int](class_int.md)\ ) [🔗](#class_Color_operator_div_int) + +Divides each component of the **Color** by the given [int](class_int.md). + +
+ + + + + +[bool](class_bool.md) **operator ==**\ (\ right\: [Color](class_color.md)\ ) [🔗](#class_Color_operator_eq_Color) + +Returns ``true`` if the colors are exactly equal. + +\ **Note:** Due to floating-point precision errors, consider using [is_equal_approx()](class_color.md#class_Color_method_is_equal_approx) instead, which is more reliable. + +
+ + + + + +[float](class_float.md) **operator []**\ (\ index\: [int](class_int.md)\ ) [🔗](#class_Color_operator_idx_int) + +Access color components using their index. ``[0]`` is equivalent to [r](class_color.md#class_Color_property_r), ``[1]`` is equivalent to [g](class_color.md#class_Color_property_g), ``[2]`` is equivalent to [b](class_color.md#class_Color_property_b), and ``[3]`` is equivalent to [a](class_color.md#class_Color_property_a). + +
+ + + + + +[Color](class_color.md) **operator unary+**\ (\ ) [🔗](#class_Color_operator_unplus) + +Returns the same value as if the ``+`` was not there. Unary ``+`` does nothing, but sometimes it can make your code more readable. + +
+ + + + + +[Color](class_color.md) **operator unary-**\ (\ ) [🔗](#class_Color_operator_unminus) + +Inverts the given color. This is equivalent to ``Color.WHITE - c`` or ``Color(1 - c.r, 1 - c.g, 1 - c.b, 1 - c.a)``. Unlike with [inverted()](class_color.md#class_Color_method_inverted), the [a](class_color.md#class_Color_property_a) component is inverted, too. + diff --git a/docs/Classes/class_colorpalette.md b/docs/Classes/class_colorpalette.md new file mode 100644 index 00000000..5daf92b7 --- /dev/null +++ b/docs/Classes/class_colorpalette.md @@ -0,0 +1,58 @@ + + + + + + + + + +# ColorPalette + +**Inherits:** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +A resource class for managing a palette of colors, which can be loaded and saved using [ColorPicker](class_colorpicker.md). + + + +## Description + +The **ColorPalette** resource is designed to store and manage a collection of colors. This resource is useful in scenarios where a predefined set of colors is required, such as for creating themes, designing user interfaces, or managing game assets. The built-in [ColorPicker](class_colorpicker.md) control can also make use of **ColorPalette** without additional code. + + + +## Properties + + + + + + + + + + + +
[PackedColorArray](class_packedcolorarray.md)[colors](#class_ColorPalette_property_colors)`PackedColorArray()`
+ +
+ + + +## Property Descriptions + + + + + +[PackedColorArray](class_packedcolorarray.md) **colors** = `PackedColorArray()` [🔗](#class_ColorPalette_property_colors) + + + +- `void` **set_colors**\ (\ value\: [PackedColorArray](class_packedcolorarray.md)\ ) +- [PackedColorArray](class_packedcolorarray.md) **get_colors**\ (\ ) + +A [PackedColorArray](class_packedcolorarray.md) containing the colors in the palette. + +**Note:** The returned array is *copied* and any changes to it will not update the original property value. See [PackedColorArray](class_packedcolorarray.md) for more details. + diff --git a/docs/Classes/class_colorpicker.md b/docs/Classes/class_colorpicker.md new file mode 100644 index 00000000..08459860 --- /dev/null +++ b/docs/Classes/class_colorpicker.md @@ -0,0 +1,979 @@ + + + + + + + + + +# ColorPicker + +**Inherits:** [VBoxContainer](class_vboxcontainer.md) **<** [BoxContainer](class_boxcontainer.md) **<** [Container](class_container.md) **<** [Control](class_control.md) **<** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +A widget that provides an interface for selecting or modifying a color. + + + +## Description + +A widget that provides an interface for selecting or modifying a color. It can optionally provide functionalities like a color sampler (eyedropper), color modes, and presets. + +\ **Note:** This control is the color picker widget itself. You can use a [ColorPickerButton](class_colorpickerbutton.md) instead if you need a button that brings up a **ColorPicker** in a popup. + + + +## Tutorials + +- [Tween Interpolation Demo](https://godotengine.org/asset-library/asset/2733) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[can_add_swatches](#class_ColorPicker_property_can_add_swatches)`true`
[Color](class_color.md)[color](#class_ColorPicker_property_color)`Color(1, 1, 1, 1)`
[ColorModeType](class_colorpicker.md#enum_ColorPicker_ColorModeType)[color_mode](#class_ColorPicker_property_color_mode)`0`
[bool](class_bool.md)[color_modes_visible](#class_ColorPicker_property_color_modes_visible)`true`
[bool](class_bool.md)[deferred_mode](#class_ColorPicker_property_deferred_mode)`false`
[bool](class_bool.md)[display_old_color](#class_ColorPicker_property_display_old_color)`false`
[bool](class_bool.md)[edit_alpha](#class_ColorPicker_property_edit_alpha)`true`
[bool](class_bool.md)[edit_intensity](#class_ColorPicker_property_edit_intensity)`true`
[bool](class_bool.md)[hex_visible](#class_ColorPicker_property_hex_visible)`true`
[Color](class_color.md)[old_color](#class_ColorPicker_property_old_color)`Color(0, 0, 0, 1)`
[PickerShapeType](class_colorpicker.md#enum_ColorPicker_PickerShapeType)[picker_shape](#class_ColorPicker_property_picker_shape)`0`
[bool](class_bool.md)[presets_visible](#class_ColorPicker_property_presets_visible)`true`
[bool](class_bool.md)[sampler_visible](#class_ColorPicker_property_sampler_visible)`true`
[bool](class_bool.md)[sliders_visible](#class_ColorPicker_property_sliders_visible)`true`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
`void`[add_preset](#class_ColorPicker_method_add_preset)\ (\ color\: [Color](class_color.md)\ )
`void`[add_recent_preset](#class_ColorPicker_method_add_recent_preset)\ (\ color\: [Color](class_color.md)\ )
`void`[erase_preset](#class_ColorPicker_method_erase_preset)\ (\ color\: [Color](class_color.md)\ )
`void`[erase_recent_preset](#class_ColorPicker_method_erase_recent_preset)\ (\ color\: [Color](class_color.md)\ )
[PackedColorArray](class_packedcolorarray.md)[get_presets](#class_ColorPicker_method_get_presets)\ (\ ) const
[PackedColorArray](class_packedcolorarray.md)[get_recent_presets](#class_ColorPicker_method_get_recent_presets)\ (\ ) const
+ + + +## Theme Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Color](class_color.md)[focused_not_editing_cursor_color](#class_ColorPicker_theme_color_focused_not_editing_cursor_color)`Color(1, 1, 1, 0.275)`
[int](class_int.md)[center_slider_grabbers](#class_ColorPicker_theme_constant_center_slider_grabbers)`1`
[int](class_int.md)[h_width](#class_ColorPicker_theme_constant_h_width)`30`
[int](class_int.md)[label_width](#class_ColorPicker_theme_constant_label_width)`10`
[int](class_int.md)[margin](#class_ColorPicker_theme_constant_margin)`4`
[int](class_int.md)[sv_height](#class_ColorPicker_theme_constant_sv_height)`256`
[int](class_int.md)[sv_width](#class_ColorPicker_theme_constant_sv_width)`256`
[Texture2D](class_texture2d.md)[add_preset](#class_ColorPicker_theme_icon_add_preset)
[Texture2D](class_texture2d.md)[bar_arrow](#class_ColorPicker_theme_icon_bar_arrow)
[Texture2D](class_texture2d.md)[color_hue](#class_ColorPicker_theme_icon_color_hue)
[Texture2D](class_texture2d.md)[color_script](#class_ColorPicker_theme_icon_color_script)
[Texture2D](class_texture2d.md)[expanded_arrow](#class_ColorPicker_theme_icon_expanded_arrow)
[Texture2D](class_texture2d.md)[folded_arrow](#class_ColorPicker_theme_icon_folded_arrow)
[Texture2D](class_texture2d.md)[menu_option](#class_ColorPicker_theme_icon_menu_option)
[Texture2D](class_texture2d.md)[overbright_indicator](#class_ColorPicker_theme_icon_overbright_indicator)
[Texture2D](class_texture2d.md)[picker_cursor](#class_ColorPicker_theme_icon_picker_cursor)
[Texture2D](class_texture2d.md)[picker_cursor_bg](#class_ColorPicker_theme_icon_picker_cursor_bg)
[Texture2D](class_texture2d.md)[sample_bg](#class_ColorPicker_theme_icon_sample_bg)
[Texture2D](class_texture2d.md)[sample_revert](#class_ColorPicker_theme_icon_sample_revert)
[Texture2D](class_texture2d.md)[screen_picker](#class_ColorPicker_theme_icon_screen_picker)
[Texture2D](class_texture2d.md)[shape_circle](#class_ColorPicker_theme_icon_shape_circle)
[Texture2D](class_texture2d.md)[shape_rect](#class_ColorPicker_theme_icon_shape_rect)
[Texture2D](class_texture2d.md)[shape_rect_wheel](#class_ColorPicker_theme_icon_shape_rect_wheel)
[Texture2D](class_texture2d.md)[wheel_picker_cursor](#class_ColorPicker_theme_icon_wheel_picker_cursor)
[StyleBox](class_stylebox.md)[picker_focus_circle](#class_ColorPicker_theme_style_picker_focus_circle)
[StyleBox](class_stylebox.md)[picker_focus_rectangle](#class_ColorPicker_theme_style_picker_focus_rectangle)
[StyleBox](class_stylebox.md)[sample_focus](#class_ColorPicker_theme_style_sample_focus)
+ +
+ + + +## Signals + + + + + +**color_changed**\ (\ color\: [Color](class_color.md)\ ) [🔗](#class_ColorPicker_signal_color_changed) + +Emitted when the color is changed. + +
+ + + + + +**preset_added**\ (\ color\: [Color](class_color.md)\ ) [🔗](#class_ColorPicker_signal_preset_added) + +Emitted when a preset is added. + +
+ + + + + +**preset_removed**\ (\ color\: [Color](class_color.md)\ ) [🔗](#class_ColorPicker_signal_preset_removed) + +Emitted when a preset is removed. + +
+ + + +## Enumerations + + + + + +enum **ColorModeType**: [🔗](#enum_ColorPicker_ColorModeType) + + + + + +[ColorModeType](class_colorpicker.md#enum_ColorPicker_ColorModeType) **MODE_RGB** = `0` + +Allows editing the color with Red/Green/Blue sliders in sRGB color space. + + + +[ColorModeType](class_colorpicker.md#enum_ColorPicker_ColorModeType) **MODE_HSV** = `1` + +Allows editing the color with Hue/Saturation/Value sliders. + + + +[ColorModeType](class_colorpicker.md#enum_ColorPicker_ColorModeType) **MODE_RAW** = `2` + +**Deprecated:** This is replaced by [MODE_LINEAR](class_colorpicker.md#class_ColorPicker_constant_MODE_LINEAR). + + + + + +[ColorModeType](class_colorpicker.md#enum_ColorPicker_ColorModeType) **MODE_LINEAR** = `2` + +Allows editing the color with Red/Green/Blue sliders in linear color space. + + + +[ColorModeType](class_colorpicker.md#enum_ColorPicker_ColorModeType) **MODE_OKHSL** = `3` + +Allows editing the color with Hue/Saturation/Lightness sliders. + +OKHSL is a new color space similar to HSL but that better match perception by leveraging the Oklab color space which is designed to be simple to use, while doing a good job at predicting perceived lightness, chroma and hue. + +\ [Okhsv and Okhsl color spaces](https://bottosson.github.io/posts/colorpicker/)
+ + + + + +enum **PickerShapeType**: [🔗](#enum_ColorPicker_PickerShapeType) + + + + + +[PickerShapeType](class_colorpicker.md#enum_ColorPicker_PickerShapeType) **SHAPE_HSV_RECTANGLE** = `0` + +HSV Color Model rectangle color space. + + + +[PickerShapeType](class_colorpicker.md#enum_ColorPicker_PickerShapeType) **SHAPE_HSV_WHEEL** = `1` + +HSV Color Model rectangle color space with a wheel. + + + +[PickerShapeType](class_colorpicker.md#enum_ColorPicker_PickerShapeType) **SHAPE_VHS_CIRCLE** = `2` + +HSV Color Model circle color space. Use Saturation as a radius. + + + +[PickerShapeType](class_colorpicker.md#enum_ColorPicker_PickerShapeType) **SHAPE_OKHSL_CIRCLE** = `3` + +HSL OK Color Model circle color space. + + + +[PickerShapeType](class_colorpicker.md#enum_ColorPicker_PickerShapeType) **SHAPE_NONE** = `4` + +The color space shape and the shape select button are hidden. Can't be selected from the shapes popup. + + + +[PickerShapeType](class_colorpicker.md#enum_ColorPicker_PickerShapeType) **SHAPE_OK_HS_RECTANGLE** = `5` + +OKHSL Color Model rectangle with constant lightness. + + + +[PickerShapeType](class_colorpicker.md#enum_ColorPicker_PickerShapeType) **SHAPE_OK_HL_RECTANGLE** = `6` + +OKHSL Color Model rectangle with constant saturation.
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **can_add_swatches** = `true` [🔗](#class_ColorPicker_property_can_add_swatches) + + + +- `void` **set_can_add_swatches**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **are_swatches_enabled**\ (\ ) + +If ``true``, it's possible to add presets under Swatches. If ``false``, the button to add presets is disabled. + +
+ + + + + +[Color](class_color.md) **color** = `Color(1, 1, 1, 1)` [🔗](#class_ColorPicker_property_color) + + + +- `void` **set_pick_color**\ (\ value\: [Color](class_color.md)\ ) +- [Color](class_color.md) **get_pick_color**\ (\ ) + +The currently selected color. + +
+ + + + + +[ColorModeType](class_colorpicker.md#enum_ColorPicker_ColorModeType) **color_mode** = `0` [🔗](#class_ColorPicker_property_color_mode) + + + +- `void` **set_color_mode**\ (\ value\: [ColorModeType](class_colorpicker.md#enum_ColorPicker_ColorModeType)\ ) +- [ColorModeType](class_colorpicker.md#enum_ColorPicker_ColorModeType) **get_color_mode**\ (\ ) + +The currently selected color mode. + +
+ + + + + +[bool](class_bool.md) **color_modes_visible** = `true` [🔗](#class_ColorPicker_property_color_modes_visible) + + + +- `void` **set_modes_visible**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **are_modes_visible**\ (\ ) + +If ``true``, the color mode buttons are visible. + +
+ + + + + +[bool](class_bool.md) **deferred_mode** = `false` [🔗](#class_ColorPicker_property_deferred_mode) + + + +- `void` **set_deferred_mode**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_deferred_mode**\ (\ ) + +If ``true``, the color will apply only after the user releases the mouse button, otherwise it will apply immediately even in mouse motion event (which can cause performance issues). + +
+ + + + + +[bool](class_bool.md) **display_old_color** = `false` [🔗](#class_ColorPicker_property_display_old_color) + + + +- `void` **set_display_old_color**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_displaying_old_color**\ (\ ) + +If ``true``, [old_color](class_colorpicker.md#class_ColorPicker_property_old_color) will be displayed instead of [color](class_colorpicker.md#class_ColorPicker_property_color). + +
+ + + + + +[bool](class_bool.md) **edit_alpha** = `true` [🔗](#class_ColorPicker_property_edit_alpha) + + + +- `void` **set_edit_alpha**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_editing_alpha**\ (\ ) + +If ``true``, shows an alpha channel slider (opacity). + +
+ + + + + +[bool](class_bool.md) **edit_intensity** = `true` [🔗](#class_ColorPicker_property_edit_intensity) + + + +- `void` **set_edit_intensity**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_editing_intensity**\ (\ ) + +If ``true``, shows an intensity slider. The intensity is applied as follows: multiply the color by ``2 ** intensity`` in linear RGB space, and then convert it back to sRGB. + +
+ + + + + +[bool](class_bool.md) **hex_visible** = `true` [🔗](#class_ColorPicker_property_hex_visible) + + + +- `void` **set_hex_visible**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_hex_visible**\ (\ ) + +If ``true``, the hex color code input field is visible. + +
+ + + + + +[Color](class_color.md) **old_color** = `Color(0, 0, 0, 1)` [🔗](#class_ColorPicker_property_old_color) + + + +- `void` **set_old_color**\ (\ value\: [Color](class_color.md)\ ) +- [Color](class_color.md) **get_old_color**\ (\ ) + +The currently stored old color. See also [display_old_color](class_colorpicker.md#class_ColorPicker_property_display_old_color). + +
+ + + + + +[PickerShapeType](class_colorpicker.md#enum_ColorPicker_PickerShapeType) **picker_shape** = `0` [🔗](#class_ColorPicker_property_picker_shape) + + + +- `void` **set_picker_shape**\ (\ value\: [PickerShapeType](class_colorpicker.md#enum_ColorPicker_PickerShapeType)\ ) +- [PickerShapeType](class_colorpicker.md#enum_ColorPicker_PickerShapeType) **get_picker_shape**\ (\ ) + +The shape of the color space view. + +
+ + + + + +[bool](class_bool.md) **presets_visible** = `true` [🔗](#class_ColorPicker_property_presets_visible) + + + +- `void` **set_presets_visible**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **are_presets_visible**\ (\ ) + +If ``true``, the Swatches and Recent Colors presets are visible. + +
+ + + + + +[bool](class_bool.md) **sampler_visible** = `true` [🔗](#class_ColorPicker_property_sampler_visible) + + + +- `void` **set_sampler_visible**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_sampler_visible**\ (\ ) + +If ``true``, the color sampler and color preview are visible. + +
+ + + + + +[bool](class_bool.md) **sliders_visible** = `true` [🔗](#class_ColorPicker_property_sliders_visible) + + + +- `void` **set_sliders_visible**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **are_sliders_visible**\ (\ ) + +If ``true``, the color sliders are visible. + +
+ + + +## Method Descriptions + + + + + +`void` **add_preset**\ (\ color\: [Color](class_color.md)\ ) [🔗](#class_ColorPicker_method_add_preset) + +Adds the given color to a list of color presets. The presets are displayed in the color picker and the user will be able to select them. + +\ **Note:** The presets list is only for *this* color picker. + +
+ + + + + +`void` **add_recent_preset**\ (\ color\: [Color](class_color.md)\ ) [🔗](#class_ColorPicker_method_add_recent_preset) + +Adds the given color to a list of color recent presets so that it can be picked later. Recent presets are the colors that were picked recently, a new preset is automatically created and added to recent presets when you pick a new color. + +\ **Note:** The recent presets list is only for *this* color picker. + +
+ + + + + +`void` **erase_preset**\ (\ color\: [Color](class_color.md)\ ) [🔗](#class_ColorPicker_method_erase_preset) + +Removes the given color from the list of color presets of this color picker. + +
+ + + + + +`void` **erase_recent_preset**\ (\ color\: [Color](class_color.md)\ ) [🔗](#class_ColorPicker_method_erase_recent_preset) + +Removes the given color from the list of color recent presets of this color picker. + +
+ + + + + +[PackedColorArray](class_packedcolorarray.md) **get_presets**\ (\ ) const [🔗](#class_ColorPicker_method_get_presets) + +Returns the list of colors in the presets of the color picker. + +
+ + + + + +[PackedColorArray](class_packedcolorarray.md) **get_recent_presets**\ (\ ) const [🔗](#class_ColorPicker_method_get_recent_presets) + +Returns the list of colors in the recent presets of the color picker. + +
+ + + +## Theme Property Descriptions + + + + + +[Color](class_color.md) **focused_not_editing_cursor_color** = `Color(1, 1, 1, 0.275)` [🔗](#class_ColorPicker_theme_color_focused_not_editing_cursor_color) + +Color of rectangle or circle drawn when a picker shape part is focused but not editable via keyboard or joypad. Displayed *over* the picker shape, so a partially transparent color should be used to ensure the picker shape remains visible. + +
+ + + + + +[int](class_int.md) **center_slider_grabbers** = `1` [🔗](#class_ColorPicker_theme_constant_center_slider_grabbers) + +Overrides the [Slider.center_grabber](class_slider.md#class_Slider_theme_constant_center_grabber) theme property of the sliders. + +
+ + + + + +[int](class_int.md) **h_width** = `30` [🔗](#class_ColorPicker_theme_constant_h_width) + +The width of the hue selection slider. + +
+ + + + + +[int](class_int.md) **label_width** = `10` [🔗](#class_ColorPicker_theme_constant_label_width) + +The minimum width of the color labels next to sliders. + +
+ + + + + +[int](class_int.md) **margin** = `4` [🔗](#class_ColorPicker_theme_constant_margin) + +The margin around the **ColorPicker**. + +
+ + + + + +[int](class_int.md) **sv_height** = `256` [🔗](#class_ColorPicker_theme_constant_sv_height) + +The height of the saturation-value selection box. + +
+ + + + + +[int](class_int.md) **sv_width** = `256` [🔗](#class_ColorPicker_theme_constant_sv_width) + +The width of the saturation-value selection box. + +
+ + + + + +[Texture2D](class_texture2d.md) **add_preset** [🔗](#class_ColorPicker_theme_icon_add_preset) + +The icon for the "Add Preset" button. + +
+ + + + + +[Texture2D](class_texture2d.md) **bar_arrow** [🔗](#class_ColorPicker_theme_icon_bar_arrow) + +The texture for the arrow grabber. + +
+ + + + + +[Texture2D](class_texture2d.md) **color_hue** [🔗](#class_ColorPicker_theme_icon_color_hue) + +Custom texture for the hue selection slider on the right. + +
+ + + + + +[Texture2D](class_texture2d.md) **color_script** [🔗](#class_ColorPicker_theme_icon_color_script) + +The icon for the button that switches color text to hexadecimal. + +
+ + + + + +[Texture2D](class_texture2d.md) **expanded_arrow** [🔗](#class_ColorPicker_theme_icon_expanded_arrow) + +The icon for color preset drop down menu when expanded. + +
+ + + + + +[Texture2D](class_texture2d.md) **folded_arrow** [🔗](#class_ColorPicker_theme_icon_folded_arrow) + +The icon for color preset drop down menu when folded. + +
+ + + + + +[Texture2D](class_texture2d.md) **menu_option** [🔗](#class_ColorPicker_theme_icon_menu_option) + +The icon for color preset option menu. + +
+ + + + + +[Texture2D](class_texture2d.md) **overbright_indicator** [🔗](#class_ColorPicker_theme_icon_overbright_indicator) + +The indicator used to signalize that the color value is outside the 0-1 range. + +
+ + + + + +[Texture2D](class_texture2d.md) **picker_cursor** [🔗](#class_ColorPicker_theme_icon_picker_cursor) + +The image displayed over the color box/circle (depending on the [picker_shape](class_colorpicker.md#class_ColorPicker_property_picker_shape)), marking the currently selected color. + +
+ + + + + +[Texture2D](class_texture2d.md) **picker_cursor_bg** [🔗](#class_ColorPicker_theme_icon_picker_cursor_bg) + +The fill image displayed behind the picker cursor. + +
+ + + + + +[Texture2D](class_texture2d.md) **sample_bg** [🔗](#class_ColorPicker_theme_icon_sample_bg) + +Background panel for the color preview box (visible when the color is translucent). + +
+ + + + + +[Texture2D](class_texture2d.md) **sample_revert** [🔗](#class_ColorPicker_theme_icon_sample_revert) + +The icon for the revert button (visible on the middle of the "old" color when it differs from the currently selected color). This icon is modulated with a dark color if the "old" color is bright enough, so the icon should be bright to ensure visibility in both scenarios. + +
+ + + + + +[Texture2D](class_texture2d.md) **screen_picker** [🔗](#class_ColorPicker_theme_icon_screen_picker) + +The icon for the screen color picker button. + +
+ + + + + +[Texture2D](class_texture2d.md) **shape_circle** [🔗](#class_ColorPicker_theme_icon_shape_circle) + +The icon for circular picker shapes. + +
+ + + + + +[Texture2D](class_texture2d.md) **shape_rect** [🔗](#class_ColorPicker_theme_icon_shape_rect) + +The icon for rectangular picker shapes. + +
+ + + + + +[Texture2D](class_texture2d.md) **shape_rect_wheel** [🔗](#class_ColorPicker_theme_icon_shape_rect_wheel) + +The icon for rectangular wheel picker shapes. + +
+ + + + + +[Texture2D](class_texture2d.md) **wheel_picker_cursor** [🔗](#class_ColorPicker_theme_icon_wheel_picker_cursor) + +The image displayed over the color wheel (depending on the [picker_shape](class_colorpicker.md#class_ColorPicker_property_picker_shape) being [SHAPE_HSV_WHEEL](class_colorpicker.md#class_ColorPicker_constant_SHAPE_HSV_WHEEL)), marking the currently selected hue. This icon is rotated from the right side of the wheel. + +
+ + + + + +[StyleBox](class_stylebox.md) **picker_focus_circle** [🔗](#class_ColorPicker_theme_style_picker_focus_circle) + +The [StyleBox](class_stylebox.md) used when the circle-shaped part of the picker is focused. Displayed *over* the picker shape, so a partially transparent [StyleBox](class_stylebox.md) should be used to ensure the picker shape remains visible. A [StyleBox](class_stylebox.md) that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a [StyleBoxEmpty](class_styleboxempty.md) resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons. + +
+ + + + + +[StyleBox](class_stylebox.md) **picker_focus_rectangle** [🔗](#class_ColorPicker_theme_style_picker_focus_rectangle) + +The [StyleBox](class_stylebox.md) used when the rectangle-shaped part of the picker is focused. Displayed *over* the picker shape, so a partially transparent [StyleBox](class_stylebox.md) should be used to ensure the picker shape remains visible. A [StyleBox](class_stylebox.md) that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a [StyleBoxEmpty](class_styleboxempty.md) resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons. + +
+ + + + + +[StyleBox](class_stylebox.md) **sample_focus** [🔗](#class_ColorPicker_theme_style_sample_focus) + +The [StyleBox](class_stylebox.md) used for the old color sample part when it is focused. Displayed *over* the sample, so a partially transparent [StyleBox](class_stylebox.md) should be used to ensure the picker shape remains visible. A [StyleBox](class_stylebox.md) that represents an outline or an underline works well for this purpose. To disable the focus visual effect, assign a [StyleBoxEmpty](class_styleboxempty.md) resource. Note that disabling the focus visual effect will harm keyboard/controller navigation usability, so this is not recommended for accessibility reasons. + diff --git a/docs/Classes/class_colorpickerbutton.md b/docs/Classes/class_colorpickerbutton.md new file mode 100644 index 00000000..c6a20dfc --- /dev/null +++ b/docs/Classes/class_colorpickerbutton.md @@ -0,0 +1,223 @@ + + + + + + + + + +# ColorPickerButton + +**Inherits:** [Button](class_button.md) **<** [BaseButton](class_basebutton.md) **<** [Control](class_control.md) **<** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +A button that brings up a [ColorPicker](class_colorpicker.md) when pressed. + + + +## Description + +Encapsulates a [ColorPicker](class_colorpicker.md), making it accessible by pressing a button. Pressing the button will toggle the [ColorPicker](class_colorpicker.md)'s visibility. + +See also [BaseButton](class_basebutton.md) which contains common properties and methods associated with this node. + +\ **Note:** By default, the button may not be wide enough for the color preview swatch to be visible. Make sure to set [Control.custom_minimum_size](class_control.md#class_Control_property_custom_minimum_size) to a big enough value to give the button enough space. + + + +## Tutorials + +- [2D GD Paint Demo](https://godotengine.org/asset-library/asset/2768) + +- [GUI Drag And Drop Demo](https://godotengine.org/asset-library/asset/2767) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Color](class_color.md)[color](#class_ColorPickerButton_property_color)`Color(0, 0, 0, 1)`
[bool](class_bool.md)[edit_alpha](#class_ColorPickerButton_property_edit_alpha)`true`
[bool](class_bool.md)[edit_intensity](#class_ColorPickerButton_property_edit_intensity)`true`
[bool](class_bool.md)toggle_mode`true` (overrides [BaseButton.toggle_mode](class_basebutton.md#class_BaseButton_property_toggle_mode))
+ + + +## Methods + + + + + + + + + + + + + + +
[ColorPicker](class_colorpicker.md)[get_picker](#class_ColorPickerButton_method_get_picker)\ (\ )
[PopupPanel](class_popuppanel.md)[get_popup](#class_ColorPickerButton_method_get_popup)\ (\ )
+ + + +## Theme Properties + + + + + + + + + + +
[Texture2D](class_texture2d.md)[bg](#class_ColorPickerButton_theme_icon_bg)
+ +
+ + + +## Signals + + + + + +**color_changed**\ (\ color\: [Color](class_color.md)\ ) [🔗](#class_ColorPickerButton_signal_color_changed) + +Emitted when the color changes. + +
+ + + + + +**picker_created**\ (\ ) [🔗](#class_ColorPickerButton_signal_picker_created) + +Emitted when the [ColorPicker](class_colorpicker.md) is created (the button is pressed for the first time). + +
+ + + + + +**popup_closed**\ (\ ) [🔗](#class_ColorPickerButton_signal_popup_closed) + +Emitted when the [ColorPicker](class_colorpicker.md) is closed. + +
+ + + +## Property Descriptions + + + + + +[Color](class_color.md) **color** = `Color(0, 0, 0, 1)` [🔗](#class_ColorPickerButton_property_color) + + + +- `void` **set_pick_color**\ (\ value\: [Color](class_color.md)\ ) +- [Color](class_color.md) **get_pick_color**\ (\ ) + +The currently selected color. + +
+ + + + + +[bool](class_bool.md) **edit_alpha** = `true` [🔗](#class_ColorPickerButton_property_edit_alpha) + + + +- `void` **set_edit_alpha**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_editing_alpha**\ (\ ) + +If ``true``, the alpha channel in the displayed [ColorPicker](class_colorpicker.md) will be visible. + +
+ + + + + +[bool](class_bool.md) **edit_intensity** = `true` [🔗](#class_ColorPickerButton_property_edit_intensity) + + + +- `void` **set_edit_intensity**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_editing_intensity**\ (\ ) + +If ``true``, the intensity slider in the displayed [ColorPicker](class_colorpicker.md) will be visible. + +
+ + + +## Method Descriptions + + + + + +[ColorPicker](class_colorpicker.md) **get_picker**\ (\ ) [🔗](#class_ColorPickerButton_method_get_picker) + +Returns the [ColorPicker](class_colorpicker.md) that this node toggles. + +\ **Warning:** 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 [CanvasItem.visible](class_canvasitem.md#class_CanvasItem_property_visible) property. + +
+ + + + + +[PopupPanel](class_popuppanel.md) **get_popup**\ (\ ) [🔗](#class_ColorPickerButton_method_get_popup) + +Returns the control's [PopupPanel](class_popuppanel.md) which allows you to connect to popup signals. This allows you to handle events when the ColorPicker is shown or hidden. + +\ **Warning:** 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 [Window.visible](class_window.md#class_Window_property_visible) property. + +
+ + + +## Theme Property Descriptions + + + + + +[Texture2D](class_texture2d.md) **bg** [🔗](#class_ColorPickerButton_theme_icon_bg) + +The background of the color preview rect on the button. + diff --git a/docs/Classes/class_colorrect.md b/docs/Classes/class_colorrect.md new file mode 100644 index 00000000..f54016f0 --- /dev/null +++ b/docs/Classes/class_colorrect.md @@ -0,0 +1,62 @@ + + + + + + + + + +# ColorRect + +**Inherits:** [Control](class_control.md) **<** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +A control that displays a solid color rectangle. + + + +## Description + +Displays a rectangle filled with a solid [color](class_colorrect.md#class_ColorRect_property_color). If you need to display the border alone, consider using a [Panel](class_panel.md) instead. + + + +## Tutorials + +- [2D Dodge The Creeps Demo](https://godotengine.org/asset-library/asset/2712) + + + +## Properties + + + + + + + + + + + +
[Color](class_color.md)[color](#class_ColorRect_property_color)`Color(1, 1, 1, 1)`
+ +
+ + + +## Property Descriptions + + + + + +[Color](class_color.md) **color** = `Color(1, 1, 1, 1)` [🔗](#class_ColorRect_property_color) + + + +- `void` **set_color**\ (\ value\: [Color](class_color.md)\ ) +- [Color](class_color.md) **get_color**\ (\ ) + +The fill color of the rectangle. + diff --git a/docs/Classes/class_compositor.md b/docs/Classes/class_compositor.md new file mode 100644 index 00000000..5cd9ce19 --- /dev/null +++ b/docs/Classes/class_compositor.md @@ -0,0 +1,64 @@ + + + + + + + + + +# Compositor + +**Experimental:** More customization of the rendering pipeline will be added in the future. + +**Inherits:** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Stores attributes used to customize how a Viewport is rendered. + + + +## Description + +The compositor resource stores attributes used to customize how a [Viewport](class_viewport.md) is rendered. + + + +## Tutorials + +- [The Compositor](../tutorials/rendering/compositor.md) + + + +## Properties + + + + + + + + + + + +
[Array](class_array.md)\[[CompositorEffect](class_compositoreffect.md)\][compositor_effects](#class_Compositor_property_compositor_effects)`[]`
+ +
+ + + +## Property Descriptions + + + + + +[Array](class_array.md)\[[CompositorEffect](class_compositoreffect.md)\] **compositor_effects** = `[]` [🔗](#class_Compositor_property_compositor_effects) + + + +- `void` **set_compositor_effects**\ (\ value\: [Array](class_array.md)\[[CompositorEffect](class_compositoreffect.md)\]\ ) +- [Array](class_array.md)\[[CompositorEffect](class_compositoreffect.md)\] **get_compositor_effects**\ (\ ) + +The custom [CompositorEffect](class_compositoreffect.md)\ s that are applied during rendering of viewports using this compositor. + diff --git a/docs/Classes/class_compositoreffect.md b/docs/Classes/class_compositoreffect.md new file mode 100644 index 00000000..d46e9fc2 --- /dev/null +++ b/docs/Classes/class_compositoreffect.md @@ -0,0 +1,295 @@ + + + + + + + + + +# CompositorEffect + +**Experimental:** The implementation may change as more of the rendering internals are exposed over time. + +**Inherits:** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +This resource allows for creating a custom rendering effect. + + + +## Description + +This resource defines a custom rendering effect that can be applied to [Viewport](class_viewport.md)\ s through the viewports' [Environment](class_environment.md). You can implement a callback that is called during rendering at a given stage of the rendering pipeline and allows you to insert additional passes. Note that this callback happens on the rendering thread. CompositorEffect is an abstract base class and must be extended to implement specific rendering logic. + + + +## Tutorials + +- [The Compositor](../tutorials/rendering/compositor.md) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[bool](class_bool.md)[access_resolved_color](#class_CompositorEffect_property_access_resolved_color)
[bool](class_bool.md)[access_resolved_depth](#class_CompositorEffect_property_access_resolved_depth)
[EffectCallbackType](class_compositoreffect.md#enum_CompositorEffect_EffectCallbackType)[effect_callback_type](#class_CompositorEffect_property_effect_callback_type)
[bool](class_bool.md)[enabled](#class_CompositorEffect_property_enabled)
[bool](class_bool.md)[needs_motion_vectors](#class_CompositorEffect_property_needs_motion_vectors)
[bool](class_bool.md)[needs_normal_roughness](#class_CompositorEffect_property_needs_normal_roughness)
[bool](class_bool.md)[needs_separate_specular](#class_CompositorEffect_property_needs_separate_specular)
+ + + +## Methods + + + + + + + + + + +
`void`[_render_callback](#class_CompositorEffect_private_method__render_callback)\ (\ effect_callback_type\: [int](class_int.md), render_data\: [RenderData](class_renderdata.md)\ ) virtual
+ +
+ + + +## Enumerations + + + + + +enum **EffectCallbackType**: [🔗](#enum_CompositorEffect_EffectCallbackType) + + + + + +[EffectCallbackType](class_compositoreffect.md#enum_CompositorEffect_EffectCallbackType) **EFFECT_CALLBACK_TYPE_PRE_OPAQUE** = `0` + +The callback is called before our opaque rendering pass, but after depth prepass (if applicable). + + + +[EffectCallbackType](class_compositoreffect.md#enum_CompositorEffect_EffectCallbackType) **EFFECT_CALLBACK_TYPE_POST_OPAQUE** = `1` + +The callback is called after our opaque rendering pass, but before our sky is rendered. + + + +[EffectCallbackType](class_compositoreffect.md#enum_CompositorEffect_EffectCallbackType) **EFFECT_CALLBACK_TYPE_POST_SKY** = `2` + +The callback is called after our sky is rendered, but before our back buffers are created (and if enabled, before subsurface scattering and/or screen space reflections). + + + +[EffectCallbackType](class_compositoreffect.md#enum_CompositorEffect_EffectCallbackType) **EFFECT_CALLBACK_TYPE_PRE_TRANSPARENT** = `3` + +The callback is called before our transparent rendering pass, but after our sky is rendered and we've created our back buffers. + + + +[EffectCallbackType](class_compositoreffect.md#enum_CompositorEffect_EffectCallbackType) **EFFECT_CALLBACK_TYPE_POST_TRANSPARENT** = `4` + +The callback is called after our transparent rendering pass, but before any built-in post-processing effects and output to our render target. + + + +[EffectCallbackType](class_compositoreffect.md#enum_CompositorEffect_EffectCallbackType) **EFFECT_CALLBACK_TYPE_MAX** = `5` + +Represents the size of the [EffectCallbackType](class_compositoreffect.md#enum_CompositorEffect_EffectCallbackType) enum.
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **access_resolved_color** [🔗](#class_CompositorEffect_property_access_resolved_color) + + + +- `void` **set_access_resolved_color**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_access_resolved_color**\ (\ ) + +If ``true`` and MSAA is enabled, this will trigger a color buffer resolve before the effect is run. + +\ **Note:** In [_render_callback()](class_compositoreffect.md#class_CompositorEffect_private_method__render_callback), to access the resolved buffer use: + +``` + var render_scene_buffers = render_data.get_render_scene_buffers() + var color_buffer = render_scene_buffers.get_texture("render_buffers", "color") +``` + +
+ + + + + +[bool](class_bool.md) **access_resolved_depth** [🔗](#class_CompositorEffect_property_access_resolved_depth) + + + +- `void` **set_access_resolved_depth**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_access_resolved_depth**\ (\ ) + +If ``true`` and MSAA is enabled, this will trigger a depth buffer resolve before the effect is run. + +\ **Note:** In [_render_callback()](class_compositoreffect.md#class_CompositorEffect_private_method__render_callback), to access the resolved buffer use: + +``` + var render_scene_buffers = render_data.get_render_scene_buffers() + var depth_buffer = render_scene_buffers.get_texture("render_buffers", "depth") +``` + +
+ + + + + +[EffectCallbackType](class_compositoreffect.md#enum_CompositorEffect_EffectCallbackType) **effect_callback_type** [🔗](#class_CompositorEffect_property_effect_callback_type) + + + +- `void` **set_effect_callback_type**\ (\ value\: [EffectCallbackType](class_compositoreffect.md#enum_CompositorEffect_EffectCallbackType)\ ) +- [EffectCallbackType](class_compositoreffect.md#enum_CompositorEffect_EffectCallbackType) **get_effect_callback_type**\ (\ ) + +The type of effect that is implemented, determines at what stage of rendering the callback is called. + +
+ + + + + +[bool](class_bool.md) **enabled** [🔗](#class_CompositorEffect_property_enabled) + + + +- `void` **set_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_enabled**\ (\ ) + +If ``true`` this rendering effect is applied to any viewport it is added to. + +
+ + + + + +[bool](class_bool.md) **needs_motion_vectors** [🔗](#class_CompositorEffect_property_needs_motion_vectors) + + + +- `void` **set_needs_motion_vectors**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_needs_motion_vectors**\ (\ ) + +If ``true`` this triggers motion vectors being calculated during the opaque render state. + +\ **Note:** In [_render_callback()](class_compositoreffect.md#class_CompositorEffect_private_method__render_callback), to access the motion vector buffer use: + +``` + var render_scene_buffers = render_data.get_render_scene_buffers() + var motion_buffer = render_scene_buffers.get_velocity_texture() +``` + +
+ + + + + +[bool](class_bool.md) **needs_normal_roughness** [🔗](#class_CompositorEffect_property_needs_normal_roughness) + + + +- `void` **set_needs_normal_roughness**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_needs_normal_roughness**\ (\ ) + +If ``true`` this triggers normal and roughness data to be output during our depth pre-pass, only applicable for the Forward+ renderer. + +\ **Note:** In [_render_callback()](class_compositoreffect.md#class_CompositorEffect_private_method__render_callback), to access the roughness buffer use: + +``` + var render_scene_buffers = render_data.get_render_scene_buffers() + var roughness_buffer = render_scene_buffers.get_texture("forward_clustered", "normal_roughness") +``` + +The raw normal and roughness buffer is stored in an optimized format, different than the one available in Spatial shaders. When sampling the buffer, a conversion function must be applied. Use this function, copied from [here](https://github.com/Redot-Engine/redot-engine/blob/da5f39889f155658cef7f7ec3cc1abb94e17d815/servers/rendering/renderer_rd/shaders/forward_clustered/scene_forward_clustered_inc.glsl#L334-L341): + +``` + vec4 normal_roughness_compatibility(vec4 p_normal_roughness) { + float roughness = p_normal_roughness.w; + if (roughness > 0.5) { + roughness = 1.0 - roughness; + } + roughness /= (127.0 / 255.0); + return vec4(normalize(p_normal_roughness.xyz * 2.0 - 1.0) * 0.5 + 0.5, roughness); + } +``` + +
+ + + + + +[bool](class_bool.md) **needs_separate_specular** [🔗](#class_CompositorEffect_property_needs_separate_specular) + + + +- `void` **set_needs_separate_specular**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **get_needs_separate_specular**\ (\ ) + +If ``true`` this triggers specular data being rendered to a separate buffer and combined after effects have been applied, only applicable for the Forward+ renderer. + +
+ + + +## Method Descriptions + + + + + +`void` **_render_callback**\ (\ effect_callback_type\: [int](class_int.md), render_data\: [RenderData](class_renderdata.md)\ ) virtual [🔗](#class_CompositorEffect_private_method__render_callback) + +Implement this function with your custom rendering code. `effect_callback_type` should always match the effect callback type you've specified in [effect_callback_type](class_compositoreffect.md#class_CompositorEffect_property_effect_callback_type). `render_data` provides access to the rendering state, it is only valid during rendering and should not be stored. + diff --git a/docs/Classes/class_compressedcubemap.md b/docs/Classes/class_compressedcubemap.md new file mode 100644 index 00000000..aec5c841 --- /dev/null +++ b/docs/Classes/class_compressedcubemap.md @@ -0,0 +1,37 @@ + + + + + + + + + +# CompressedCubemap + +**Inherits:** [CompressedTextureLayered](class_compressedtexturelayered.md) **<** [TextureLayered](class_texturelayered.md) **<** [Texture](class_texture.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +An optionally compressed [Cubemap](class_cubemap.md). + + + +## Description + +A cubemap that is loaded from a ``.ccube`` file. This file format is internal to Redot; it is created by importing other image formats with the import system. **CompressedCubemap** can use one of 4 compression methods: + +- Lossless (WebP or PNG, uncompressed on the GPU) + +- Lossy (WebP, uncompressed on the GPU) + +- VRAM Compressed (compressed on the GPU) + +- VRAM Uncompressed (uncompressed on the GPU) + +- Basis Universal (compressed on the GPU. Lower file sizes than VRAM Compressed, but slower to compress and lower quality than VRAM Compressed) + +Only **VRAM Compressed** actually reduces the memory usage on the GPU. The **Lossless** and **Lossy** compression methods will reduce the required storage on disk, but they will not reduce memory usage on the GPU as the texture is sent to the GPU uncompressed. + +Using **VRAM Compressed** also improves loading times, as VRAM-compressed textures are faster to load compared to textures using lossless or lossy compression. VRAM compression can exhibit noticeable artifacts and is intended to be used for 3D rendering, not 2D. + +See [Cubemap](class_cubemap.md) for a general description of cubemaps. + diff --git a/docs/Classes/class_compressedcubemaparray.md b/docs/Classes/class_compressedcubemaparray.md new file mode 100644 index 00000000..fca97d70 --- /dev/null +++ b/docs/Classes/class_compressedcubemaparray.md @@ -0,0 +1,37 @@ + + + + + + + + + +# CompressedCubemapArray + +**Inherits:** [CompressedTextureLayered](class_compressedtexturelayered.md) **<** [TextureLayered](class_texturelayered.md) **<** [Texture](class_texture.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +An optionally compressed [CubemapArray](class_cubemaparray.md). + + + +## Description + +A cubemap array that is loaded from a ``.ccubearray`` file. This file format is internal to Redot; it is created by importing other image formats with the import system. **CompressedCubemapArray** can use one of 4 compression methods: + +- Lossless (WebP or PNG, uncompressed on the GPU) + +- Lossy (WebP, uncompressed on the GPU) + +- VRAM Compressed (compressed on the GPU) + +- VRAM Uncompressed (uncompressed on the GPU) + +- Basis Universal (compressed on the GPU. Lower file sizes than VRAM Compressed, but slower to compress and lower quality than VRAM Compressed) + +Only **VRAM Compressed** actually reduces the memory usage on the GPU. The **Lossless** and **Lossy** compression methods will reduce the required storage on disk, but they will not reduce memory usage on the GPU as the texture is sent to the GPU uncompressed. + +Using **VRAM Compressed** also improves loading times, as VRAM-compressed textures are faster to load compared to textures using lossless or lossy compression. VRAM compression can exhibit noticeable artifacts and is intended to be used for 3D rendering, not 2D. + +See [CubemapArray](class_cubemaparray.md) for a general description of cubemap arrays. + diff --git a/docs/Classes/class_compressedtexture2d.md b/docs/Classes/class_compressedtexture2d.md new file mode 100644 index 00000000..1b5b406c --- /dev/null +++ b/docs/Classes/class_compressedtexture2d.md @@ -0,0 +1,104 @@ + + + + + + + + + +# CompressedTexture2D + +**Inherits:** [Texture2D](class_texture2d.md) **<** [Texture](class_texture.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Texture with 2 dimensions, optionally compressed. + + + +## Description + +A texture that is loaded from a ``.ctex`` file. This file format is internal to Redot; it is created by importing other image formats with the import system. **CompressedTexture2D** can use one of 4 compression methods (including a lack of any compression): + +- Lossless (WebP or PNG, uncompressed on the GPU) + +- Lossy (WebP, uncompressed on the GPU) + +- VRAM Compressed (compressed on the GPU) + +- VRAM Uncompressed (uncompressed on the GPU) + +- Basis Universal (compressed on the GPU. Lower file sizes than VRAM Compressed, but slower to compress and lower quality than VRAM Compressed) + +Only **VRAM Compressed** actually reduces the memory usage on the GPU. The **Lossless** and **Lossy** compression methods will reduce the required storage on disk, but they will not reduce memory usage on the GPU as the texture is sent to the GPU uncompressed. + +Using **VRAM Compressed** also improves loading times, as VRAM-compressed textures are faster to load compared to textures using lossless or lossy compression. VRAM compression can exhibit noticeable artifacts and is intended to be used for 3D rendering, not 2D. + + + +## Properties + + + + + + + + + + + + + + + + +
[String](class_string.md)[load_path](#class_CompressedTexture2D_property_load_path)`""`
[bool](class_bool.md)resource_local_to_scene`false` (overrides [Resource.resource_local_to_scene](class_resource.md#class_Resource_property_resource_local_to_scene))
+ + + +## Methods + + + + + + + + + + +
[Error](class_@globalscope.md#enum_@GlobalScope_Error)[load](#class_CompressedTexture2D_method_load)\ (\ path\: [String](class_string.md)\ )
+ +
+ + + +## Property Descriptions + + + + + +[String](class_string.md) **load_path** = `""` [🔗](#class_CompressedTexture2D_property_load_path) + + + +- [Error](class_@globalscope.md#enum_@GlobalScope_Error) **load**\ (\ path\: [String](class_string.md)\ ) +- [String](class_string.md) **get_load_path**\ (\ ) + +The **CompressedTexture2D**'s file path to a ``.ctex`` file. + +
+ + + +## Method Descriptions + + + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **load**\ (\ path\: [String](class_string.md)\ ) [🔗](#class_CompressedTexture2D_method_load) + +Loads the texture from the specified `path`. + diff --git a/docs/Classes/class_compressedtexture2darray.md b/docs/Classes/class_compressedtexture2darray.md new file mode 100644 index 00000000..d51d0769 --- /dev/null +++ b/docs/Classes/class_compressedtexture2darray.md @@ -0,0 +1,37 @@ + + + + + + + + + +# CompressedTexture2DArray + +**Inherits:** [CompressedTextureLayered](class_compressedtexturelayered.md) **<** [TextureLayered](class_texturelayered.md) **<** [Texture](class_texture.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Array of 2-dimensional textures, optionally compressed. + + + +## Description + +A texture array that is loaded from a ``.ctexarray`` file. This file format is internal to Redot; it is created by importing other image formats with the import system. **CompressedTexture2DArray** can use one of 4 compression methods: + +- Lossless (WebP or PNG, uncompressed on the GPU) + +- Lossy (WebP, uncompressed on the GPU) + +- VRAM Compressed (compressed on the GPU) + +- VRAM Uncompressed (uncompressed on the GPU) + +- Basis Universal (compressed on the GPU. Lower file sizes than VRAM Compressed, but slower to compress and lower quality than VRAM Compressed) + +Only **VRAM Compressed** actually reduces the memory usage on the GPU. The **Lossless** and **Lossy** compression methods will reduce the required storage on disk, but they will not reduce memory usage on the GPU as the texture is sent to the GPU uncompressed. + +Using **VRAM Compressed** also improves loading times, as VRAM-compressed textures are faster to load compared to textures using lossless or lossy compression. VRAM compression can exhibit noticeable artifacts and is intended to be used for 3D rendering, not 2D. + +See [Texture2DArray](class_texture2darray.md) for a general description of texture arrays. + diff --git a/docs/Classes/class_compressedtexture3d.md b/docs/Classes/class_compressedtexture3d.md new file mode 100644 index 00000000..6d02c93a --- /dev/null +++ b/docs/Classes/class_compressedtexture3d.md @@ -0,0 +1,89 @@ + + + + + + + + + +# CompressedTexture3D + +**Inherits:** [Texture3D](class_texture3d.md) **<** [Texture](class_texture.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Texture with 3 dimensions, optionally compressed. + + + +## Description + +**CompressedTexture3D** is the VRAM-compressed counterpart of [ImageTexture3D](class_imagetexture3d.md). The file extension for **CompressedTexture3D** files is ``.ctex3d``. This file format is internal to Redot; it is created by importing other image formats with the import system. + +\ **CompressedTexture3D** uses VRAM compression, which allows to reduce memory usage on the GPU when rendering the texture. This also improves loading times, as VRAM-compressed textures are faster to load compared to textures using lossless compression. VRAM compression can exhibit noticeable artifacts and is intended to be used for 3D rendering, not 2D. + +See [Texture3D](class_texture3d.md) for a general description of 3D textures. + + + +## Properties + + + + + + + + + + + +
[String](class_string.md)[load_path](#class_CompressedTexture3D_property_load_path)`""`
+ + + +## Methods + + + + + + + + + + +
[Error](class_@globalscope.md#enum_@GlobalScope_Error)[load](#class_CompressedTexture3D_method_load)\ (\ path\: [String](class_string.md)\ )
+ +
+ + + +## Property Descriptions + + + + + +[String](class_string.md) **load_path** = `""` [🔗](#class_CompressedTexture3D_property_load_path) + + + +- [Error](class_@globalscope.md#enum_@GlobalScope_Error) **load**\ (\ path\: [String](class_string.md)\ ) +- [String](class_string.md) **get_load_path**\ (\ ) + +The **CompressedTexture3D**'s file path to a ``.ctex3d`` file. + +
+ + + +## Method Descriptions + + + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **load**\ (\ path\: [String](class_string.md)\ ) [🔗](#class_CompressedTexture3D_method_load) + +Loads the texture from the specified `path`. + diff --git a/docs/Classes/class_compressedtexturelayered.md b/docs/Classes/class_compressedtexturelayered.md new file mode 100644 index 00000000..e5ad5d85 --- /dev/null +++ b/docs/Classes/class_compressedtexturelayered.md @@ -0,0 +1,87 @@ + + + + + + + + + +# CompressedTextureLayered + +**Inherits:** [TextureLayered](class_texturelayered.md) **<** [Texture](class_texture.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +**Inherited By:** [CompressedCubemap](class_compressedcubemap.md), [CompressedCubemapArray](class_compressedcubemaparray.md), [CompressedTexture2DArray](class_compressedtexture2darray.md) + +Base class for texture arrays that can optionally be compressed. + + + +## Description + +Base class for [CompressedTexture2DArray](class_compressedtexture2darray.md) and [CompressedTexture3D](class_compressedtexture3d.md). Cannot be used directly, but contains all the functions necessary for accessing the derived resource types. See also [TextureLayered](class_texturelayered.md). + + + +## Properties + + + + + + + + + + + +
[String](class_string.md)[load_path](#class_CompressedTextureLayered_property_load_path)`""`
+ + + +## Methods + + + + + + + + + + +
[Error](class_@globalscope.md#enum_@GlobalScope_Error)[load](#class_CompressedTextureLayered_method_load)\ (\ path\: [String](class_string.md)\ )
+ +
+ + + +## Property Descriptions + + + + + +[String](class_string.md) **load_path** = `""` [🔗](#class_CompressedTextureLayered_property_load_path) + + + +- [Error](class_@globalscope.md#enum_@GlobalScope_Error) **load**\ (\ path\: [String](class_string.md)\ ) +- [String](class_string.md) **get_load_path**\ (\ ) + +The path the texture should be loaded from. + +
+ + + +## Method Descriptions + + + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **load**\ (\ path\: [String](class_string.md)\ ) [🔗](#class_CompressedTextureLayered_method_load) + +Loads the texture at `path`. + diff --git a/docs/Classes/class_concavepolygonshape2d.md b/docs/Classes/class_concavepolygonshape2d.md new file mode 100644 index 00000000..30c7a9be --- /dev/null +++ b/docs/Classes/class_concavepolygonshape2d.md @@ -0,0 +1,66 @@ + + + + + + + + + +# ConcavePolygonShape2D + +**Inherits:** [Shape2D](class_shape2d.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +A 2D polyline shape used for physics collision. + + + +## Description + +A 2D polyline shape, intended for use in physics. Used internally in [CollisionPolygon2D](class_collisionpolygon2d.md) when it's in [CollisionPolygon2D.BUILD_SEGMENTS](class_collisionpolygon2d.md#class_CollisionPolygon2D_constant_BUILD_SEGMENTS) mode. + +Being just a collection of interconnected line segments, **ConcavePolygonShape2D** is the most freely configurable single 2D shape. It can be used to form polygons of any nature, or even shapes that don't enclose an area. However, **ConcavePolygonShape2D** is *hollow* even if the interconnected line segments do enclose an area, which often makes it unsuitable for physics or detection. + +\ **Note:** When used for collision, **ConcavePolygonShape2D** is intended to work with static [CollisionShape2D](class_collisionshape2d.md) nodes like [StaticBody2D](class_staticbody2d.md) and will likely not behave well for [CharacterBody2D](class_characterbody2d.md)\ s or [RigidBody2D](class_rigidbody2d.md)\ s in a mode other than Static. + +\ **Warning:** Physics bodies that are small have a chance to clip through this shape when moving fast. This happens because on one frame, the physics body may be on the "outside" of the shape, and on the next frame it may be "inside" it. **ConcavePolygonShape2D** is hollow, so it won't detect a collision. + +\ **Performance:** Due to its complexity, **ConcavePolygonShape2D** is the slowest 2D collision shape to check collisions against. Its use should generally be limited to level geometry. If the polyline is closed, [CollisionPolygon2D](class_collisionpolygon2d.md)'s [CollisionPolygon2D.BUILD_SOLIDS](class_collisionpolygon2d.md#class_CollisionPolygon2D_constant_BUILD_SOLIDS) mode can be used, which decomposes the polygon into convex ones; see [ConvexPolygonShape2D](class_convexpolygonshape2d.md)'s documentation for instructions. + + + +## Properties + + + + + + + + + + + +
[PackedVector2Array](class_packedvector2array.md)[segments](#class_ConcavePolygonShape2D_property_segments)`PackedVector2Array()`
+ +
+ + + +## Property Descriptions + + + + + +[PackedVector2Array](class_packedvector2array.md) **segments** = `PackedVector2Array()` [🔗](#class_ConcavePolygonShape2D_property_segments) + + + +- `void` **set_segments**\ (\ value\: [PackedVector2Array](class_packedvector2array.md)\ ) +- [PackedVector2Array](class_packedvector2array.md) **get_segments**\ (\ ) + +The array of points that make up the **ConcavePolygonShape2D**'s line segments. The array (of length divisible by two) is naturally divided into pairs (one pair for each segment); each pair consists of the starting point of a segment and the endpoint of a segment. + +**Note:** The returned array is *copied* and any changes to it will not update the original property value. See [PackedVector2Array](class_packedvector2array.md) for more details. + diff --git a/docs/Classes/class_concavepolygonshape3d.md b/docs/Classes/class_concavepolygonshape3d.md new file mode 100644 index 00000000..979d9025 --- /dev/null +++ b/docs/Classes/class_concavepolygonshape3d.md @@ -0,0 +1,113 @@ + + + + + + + + + +# ConcavePolygonShape3D + +**Inherits:** [Shape3D](class_shape3d.md) **<** [Resource](class_resource.md) **<** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +A 3D trimesh shape used for physics collision. + + + +## Description + +A 3D trimesh shape, intended for use in physics. Usually used to provide a shape for a [CollisionShape3D](class_collisionshape3d.md). + +Being just a collection of interconnected triangles, **ConcavePolygonShape3D** is the most freely configurable single 3D shape. It can be used to form polyhedra of any nature, or even shapes that don't enclose a volume. However, **ConcavePolygonShape3D** is *hollow* even if the interconnected triangles do enclose a volume, which often makes it unsuitable for physics or detection. + +\ **Note:** When used for collision, **ConcavePolygonShape3D** is intended to work with static [CollisionShape3D](class_collisionshape3d.md) nodes like [StaticBody3D](class_staticbody3d.md) and will likely not behave well for [CharacterBody3D](class_characterbody3d.md)\ s or [RigidBody3D](class_rigidbody3d.md)\ s in a mode other than Static. + +\ **Warning:** Physics bodies that are small have a chance to clip through this shape when moving fast. This happens because on one frame, the physics body may be on the "outside" of the shape, and on the next frame it may be "inside" it. **ConcavePolygonShape3D** is hollow, so it won't detect a collision. + +\ **Performance:** Due to its complexity, **ConcavePolygonShape3D** is the slowest 3D collision shape to check collisions against. Its use should generally be limited to level geometry. For convex geometry, [ConvexPolygonShape3D](class_convexpolygonshape3d.md) should be used. For dynamic physics bodies that need concave collision, several [ConvexPolygonShape3D](class_convexpolygonshape3d.md)\ s can be used to represent its collision by using convex decomposition; see [ConvexPolygonShape3D](class_convexpolygonshape3d.md)'s documentation for instructions. + + + +## Tutorials + +- [3D Physics Tests Demo](https://godotengine.org/asset-library/asset/2747) + + + +## Properties + + + + + + + + + + + +
[bool](class_bool.md)[backface_collision](#class_ConcavePolygonShape3D_property_backface_collision)`false`
+ + + +## Methods + + + + + + + + + + + + + + +
[PackedVector3Array](class_packedvector3array.md)[get_faces](#class_ConcavePolygonShape3D_method_get_faces)\ (\ ) const
`void`[set_faces](#class_ConcavePolygonShape3D_method_set_faces)\ (\ faces\: [PackedVector3Array](class_packedvector3array.md)\ )
+ +
+ + + +## Property Descriptions + + + + + +[bool](class_bool.md) **backface_collision** = `false` [🔗](#class_ConcavePolygonShape3D_property_backface_collision) + + + +- `void` **set_backface_collision_enabled**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_backface_collision_enabled**\ (\ ) + +If set to ``true``, collisions occur on both sides of the concave shape faces. Otherwise they occur only along the face normals. + +
+ + + +## Method Descriptions + + + + + +[PackedVector3Array](class_packedvector3array.md) **get_faces**\ (\ ) const [🔗](#class_ConcavePolygonShape3D_method_get_faces) + +Returns the faces of the trimesh shape as an array of vertices. The array (of length divisible by three) is naturally divided into triples; each triple of vertices defines a triangle. + +
+ + + + + +`void` **set_faces**\ (\ faces\: [PackedVector3Array](class_packedvector3array.md)\ ) [🔗](#class_ConcavePolygonShape3D_method_set_faces) + +Sets the faces of the trimesh shape from an array of vertices. The `faces` array should be composed of triples such that each triple of vertices defines a triangle. + diff --git a/docs/Classes/class_conetwistjoint3d.md b/docs/Classes/class_conetwistjoint3d.md new file mode 100644 index 00000000..8918873e --- /dev/null +++ b/docs/Classes/class_conetwistjoint3d.md @@ -0,0 +1,247 @@ + + + + + + + + + +# ConeTwistJoint3D + +**Inherits:** [Joint3D](class_joint3d.md) **<** [Node3D](class_node3d.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +A physics joint that connects two 3D physics bodies in a way that simulates a ball-and-socket joint. + + + +## Description + +A physics joint that connects two 3D physics bodies in a way that simulates a ball-and-socket joint. The twist axis is initiated as the X axis of the **ConeTwistJoint3D**. Once the physics bodies swing, the twist axis is calculated as the middle of the X axes of the joint in the local space of the two physics bodies. Useful for limbs like shoulders and hips, lamps hanging off a ceiling, etc. + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[float](class_float.md)[bias](#class_ConeTwistJoint3D_property_bias)`0.3`
[float](class_float.md)[relaxation](#class_ConeTwistJoint3D_property_relaxation)`1.0`
[float](class_float.md)[softness](#class_ConeTwistJoint3D_property_softness)`0.8`
[float](class_float.md)[swing_span](#class_ConeTwistJoint3D_property_swing_span)`0.7853982`
[float](class_float.md)[twist_span](#class_ConeTwistJoint3D_property_twist_span)`3.1415927`
+ + + +## Methods + + + + + + + + + + + + + + +
[float](class_float.md)[get_param](#class_ConeTwistJoint3D_method_get_param)\ (\ param\: [Param](class_conetwistjoint3d.md#enum_ConeTwistJoint3D_Param)\ ) const
`void`[set_param](#class_ConeTwistJoint3D_method_set_param)\ (\ param\: [Param](class_conetwistjoint3d.md#enum_ConeTwistJoint3D_Param), value\: [float](class_float.md)\ )
+ +
+ + + +## Enumerations + + + + + +enum **Param**: [🔗](#enum_ConeTwistJoint3D_Param) + + + + + +[Param](class_conetwistjoint3d.md#enum_ConeTwistJoint3D_Param) **PARAM_SWING_SPAN** = `0` + +Swing is rotation from side to side, around the axis perpendicular to the twist axis. + +The swing span defines, how much rotation will not get corrected along the swing axis. + +Could be defined as looseness in the **ConeTwistJoint3D**. + +If below 0.05, this behavior is locked. + + + +[Param](class_conetwistjoint3d.md#enum_ConeTwistJoint3D_Param) **PARAM_TWIST_SPAN** = `1` + +Twist is the rotation around the twist axis, this value defined how far the joint can twist. + +Twist is locked if below 0.05. + + + +[Param](class_conetwistjoint3d.md#enum_ConeTwistJoint3D_Param) **PARAM_BIAS** = `2` + +The speed with which the swing or twist will take place. + +The higher, the faster. + + + +[Param](class_conetwistjoint3d.md#enum_ConeTwistJoint3D_Param) **PARAM_SOFTNESS** = `3` + +The ease with which the joint starts to twist. If it's too low, it takes more force to start twisting the joint. + + + +[Param](class_conetwistjoint3d.md#enum_ConeTwistJoint3D_Param) **PARAM_RELAXATION** = `4` + +Defines, how fast the swing- and twist-speed-difference on both sides gets synced. + + + +[Param](class_conetwistjoint3d.md#enum_ConeTwistJoint3D_Param) **PARAM_MAX** = `5` + +Represents the size of the [Param](class_conetwistjoint3d.md#enum_ConeTwistJoint3D_Param) enum.
+ + + +## Property Descriptions + + + + + +[float](class_float.md) **bias** = `0.3` [🔗](#class_ConeTwistJoint3D_property_bias) + + + +- `void` **set_param**\ (\ param\: [Param](class_conetwistjoint3d.md#enum_ConeTwistJoint3D_Param), value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_param**\ (\ param\: [Param](class_conetwistjoint3d.md#enum_ConeTwistJoint3D_Param)\ ) const + +The speed with which the swing or twist will take place. + +The higher, the faster. + +
+ + + + + +[float](class_float.md) **relaxation** = `1.0` [🔗](#class_ConeTwistJoint3D_property_relaxation) + + + +- `void` **set_param**\ (\ param\: [Param](class_conetwistjoint3d.md#enum_ConeTwistJoint3D_Param), value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_param**\ (\ param\: [Param](class_conetwistjoint3d.md#enum_ConeTwistJoint3D_Param)\ ) const + +Defines, how fast the swing- and twist-speed-difference on both sides gets synced. + +
+ + + + + +[float](class_float.md) **softness** = `0.8` [🔗](#class_ConeTwistJoint3D_property_softness) + + + +- `void` **set_param**\ (\ param\: [Param](class_conetwistjoint3d.md#enum_ConeTwistJoint3D_Param), value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_param**\ (\ param\: [Param](class_conetwistjoint3d.md#enum_ConeTwistJoint3D_Param)\ ) const + +The ease with which the joint starts to twist. If it's too low, it takes more force to start twisting the joint. + +
+ + + + + +[float](class_float.md) **swing_span** = `0.7853982` [🔗](#class_ConeTwistJoint3D_property_swing_span) + + + +- `void` **set_param**\ (\ param\: [Param](class_conetwistjoint3d.md#enum_ConeTwistJoint3D_Param), value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_param**\ (\ param\: [Param](class_conetwistjoint3d.md#enum_ConeTwistJoint3D_Param)\ ) const + +Swing is rotation from side to side, around the axis perpendicular to the twist axis. + +The swing span defines, how much rotation will not get corrected along the swing axis. + +Could be defined as looseness in the **ConeTwistJoint3D**. + +If below 0.05, this behavior is locked. + +
+ + + + + +[float](class_float.md) **twist_span** = `3.1415927` [🔗](#class_ConeTwistJoint3D_property_twist_span) + + + +- `void` **set_param**\ (\ param\: [Param](class_conetwistjoint3d.md#enum_ConeTwistJoint3D_Param), value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_param**\ (\ param\: [Param](class_conetwistjoint3d.md#enum_ConeTwistJoint3D_Param)\ ) const + +Twist is the rotation around the twist axis, this value defined how far the joint can twist. + +Twist is locked if below 0.05. + +
+ + + +## Method Descriptions + + + + + +[float](class_float.md) **get_param**\ (\ param\: [Param](class_conetwistjoint3d.md#enum_ConeTwistJoint3D_Param)\ ) const [🔗](#class_ConeTwistJoint3D_method_get_param) + +Returns the value of the specified parameter. + +
+ + + + + +`void` **set_param**\ (\ param\: [Param](class_conetwistjoint3d.md#enum_ConeTwistJoint3D_Param), value\: [float](class_float.md)\ ) [🔗](#class_ConeTwistJoint3D_method_set_param) + +Sets the value of the specified parameter. + diff --git a/docs/Classes/class_configfile.md b/docs/Classes/class_configfile.md new file mode 100644 index 00000000..aba610c0 --- /dev/null +++ b/docs/Classes/class_configfile.md @@ -0,0 +1,405 @@ + + + + + + + + + +# ConfigFile + +**Inherits:** [RefCounted](class_refcounted.md) **<** [Object](class_object.md) + +Helper class to handle INI-style files. + + + +## Description + +This helper class can be used to store [Variant](class_variant.md) values on the filesystem using INI-style formatting. The stored values are identified by a section and a key: + +```text + [section] + some_key=42 + string_example="Hello World3D!" + a_vector=Vector3(1, 0, 2) +``` + +The stored data can be saved to or parsed from a file, though ConfigFile objects can also be used directly without accessing the filesystem. + +The following example shows how to create a simple **ConfigFile** and save it on disc: + + + + +```gdscript + # Create new ConfigFile object. + var config = ConfigFile.new() + + # Store some values. + config.set_value("Player1", "player_name", "Steve") + config.set_value("Player1", "best_score", 10) + config.set_value("Player2", "player_name", "V3geta") + config.set_value("Player2", "best_score", 9001) + + # Save it to a file (overwrite if already exists). + config.save("user://scores.cfg") +``` + +```csharp + // Create new ConfigFile object. + var config = new ConfigFile(); + + // Store some values. + config.SetValue("Player1", "player_name", "Steve"); + config.SetValue("Player1", "best_score", 10); + config.SetValue("Player2", "player_name", "V3geta"); + config.SetValue("Player2", "best_score", 9001); + + // Save it to a file (overwrite if already exists). + config.Save("user://scores.cfg"); +``` + + + +This example shows how the above file could be loaded: + + + + +```gdscript + var score_data = {} + var config = ConfigFile.new() + + # Load data from a file. + var err = config.load("user://scores.cfg") + + # If the file didn't load, ignore it. + if err != OK: + return + + # Iterate over all sections. + for player in config.get_sections(): + # Fetch the data for each section. + var player_name = config.get_value(player, "player_name") + var player_score = config.get_value(player, "best_score") + score_data[player_name] = player_score +``` + +```csharp + var score_data = new Godot.Collections.Dictionary(); + var config = new ConfigFile(); + + // Load data from a file. + Error err = config.Load("user://scores.cfg"); + + // If the file didn't load, ignore it. + if (err != Error.Ok) + { + return; + } + + // Iterate over all sections. + foreach (String player in config.GetSections()) + { + // Fetch the data for each section. + var player_name = (String)config.GetValue(player, "player_name"); + var player_score = (int)config.GetValue(player, "best_score"); + score_data[player_name] = player_score; + } +``` + + + +Any operation that mutates the ConfigFile such as [set_value()](class_configfile.md#class_ConfigFile_method_set_value), [clear()](class_configfile.md#class_ConfigFile_method_clear), or [erase_section()](class_configfile.md#class_ConfigFile_method_erase_section), only changes what is loaded in memory. If you want to write the change to a file, you have to save the changes with [save()](class_configfile.md#class_ConfigFile_method_save), [save_encrypted()](class_configfile.md#class_ConfigFile_method_save_encrypted), or [save_encrypted_pass()](class_configfile.md#class_ConfigFile_method_save_encrypted_pass). + +Keep in mind that section and property names can't contain spaces. Anything after a space will be ignored on save and on load. + +ConfigFiles can also contain manually written comment lines starting with a semicolon (``;``). Those lines will be ignored when parsing the file. Note that comments will be lost when saving the ConfigFile. This can still be useful for dedicated server configuration files, which are typically never overwritten without explicit user action. + +\ **Note:** The file extension given to a ConfigFile does not have any impact on its formatting or behavior. By convention, the ``.cfg`` extension is used here, but any other extension such as ``.ini`` is also valid. Since neither ``.cfg`` nor ``.ini`` are standardized, Redot's ConfigFile formatting may differ from files written by other programs. + + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
`void`[clear](#class_ConfigFile_method_clear)\ (\ )
[String](class_string.md)[encode_to_text](#class_ConfigFile_method_encode_to_text)\ (\ full_objects\: [bool](class_bool.md) = false\ ) const
`void`[erase_section](#class_ConfigFile_method_erase_section)\ (\ section\: [String](class_string.md)\ )
`void`[erase_section_key](#class_ConfigFile_method_erase_section_key)\ (\ section\: [String](class_string.md), key\: [String](class_string.md)\ )
[PackedStringArray](class_packedstringarray.md)[get_section_keys](#class_ConfigFile_method_get_section_keys)\ (\ section\: [String](class_string.md)\ ) const
[PackedStringArray](class_packedstringarray.md)[get_sections](#class_ConfigFile_method_get_sections)\ (\ ) const
[Variant](class_variant.md)[get_value](#class_ConfigFile_method_get_value)\ (\ section\: [String](class_string.md), key\: [String](class_string.md), default\: [Variant](class_variant.md) = null\ ) const
[bool](class_bool.md)[has_section](#class_ConfigFile_method_has_section)\ (\ section\: [String](class_string.md)\ ) const
[bool](class_bool.md)[has_section_key](#class_ConfigFile_method_has_section_key)\ (\ section\: [String](class_string.md), key\: [String](class_string.md)\ ) const
[Error](class_@globalscope.md#enum_@GlobalScope_Error)[load](#class_ConfigFile_method_load)\ (\ path\: [String](class_string.md), allow_objects\: [bool](class_bool.md) = false\ )
[Error](class_@globalscope.md#enum_@GlobalScope_Error)[load_encrypted](#class_ConfigFile_method_load_encrypted)\ (\ path\: [String](class_string.md), key\: [PackedByteArray](class_packedbytearray.md), allow_objects\: [bool](class_bool.md) = false\ )
[Error](class_@globalscope.md#enum_@GlobalScope_Error)[load_encrypted_pass](#class_ConfigFile_method_load_encrypted_pass)\ (\ path\: [String](class_string.md), password\: [String](class_string.md), allow_objects\: [bool](class_bool.md) = false\ )
[Error](class_@globalscope.md#enum_@GlobalScope_Error)[parse](#class_ConfigFile_method_parse)\ (\ data\: [String](class_string.md), allow_objects\: [bool](class_bool.md) = false\ )
[Error](class_@globalscope.md#enum_@GlobalScope_Error)[save](#class_ConfigFile_method_save)\ (\ path\: [String](class_string.md), full_objects\: [bool](class_bool.md) = false\ )
[Error](class_@globalscope.md#enum_@GlobalScope_Error)[save_encrypted](#class_ConfigFile_method_save_encrypted)\ (\ path\: [String](class_string.md), key\: [PackedByteArray](class_packedbytearray.md), full_objects\: [bool](class_bool.md) = false\ )
[Error](class_@globalscope.md#enum_@GlobalScope_Error)[save_encrypted_pass](#class_ConfigFile_method_save_encrypted_pass)\ (\ path\: [String](class_string.md), password\: [String](class_string.md), full_objects\: [bool](class_bool.md) = false\ )
`void`[set_value](#class_ConfigFile_method_set_value)\ (\ section\: [String](class_string.md), key\: [String](class_string.md), value\: [Variant](class_variant.md)\ )
+ +
+ + + +## Method Descriptions + + + + + +`void` **clear**\ (\ ) [🔗](#class_ConfigFile_method_clear) + +Removes the entire contents of the config. + +
+ + + + + +[String](class_string.md) **encode_to_text**\ (\ full_objects\: [bool](class_bool.md) = false\ ) const [🔗](#class_ConfigFile_method_encode_to_text) + +Obtain the text version of this config file (the same text that would be written to a file). If `full_objects` is ``true``, encoding objects is allowed (and can potentially include code). + +Internally, this uses the same encoding mechanism as the [@GlobalScope.var_to_str()](class_@globalscope.md#class_@GlobalScope_method_var_to_str) and [@GlobalScope.var_to_str_with_objects()](class_@globalscope.md#class_@GlobalScope_method_var_to_str_with_objects) methods. + +\ **Note:** Not all properties are included. Only properties that are configured with the [@GlobalScope.PROPERTY_USAGE_STORAGE](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_USAGE_STORAGE) flag set will be serialized. You can add an usage flag to a property by overriding the [Object._validate_property()](class_object.md#class_Object_private_method__validate_property) method in your class. In GDScript you can also use the [@GDScript.@export](class_@gdscript.md#class_@GDScript_annotation_@export) annotation. See [PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) for the possible usage flags. + +
+ + + + + +`void` **erase_section**\ (\ section\: [String](class_string.md)\ ) [🔗](#class_ConfigFile_method_erase_section) + +Deletes the specified section along with all the key-value pairs inside. Raises an error if the section does not exist. + +
+ + + + + +`void` **erase_section_key**\ (\ section\: [String](class_string.md), key\: [String](class_string.md)\ ) [🔗](#class_ConfigFile_method_erase_section_key) + +Deletes the specified key in a section. Raises an error if either the section or the key do not exist. + +
+ + + + + +[PackedStringArray](class_packedstringarray.md) **get_section_keys**\ (\ section\: [String](class_string.md)\ ) const [🔗](#class_ConfigFile_method_get_section_keys) + +Returns an array of all defined key identifiers in the specified section. Raises an error and returns an empty array if the section does not exist. + +
+ + + + + +[PackedStringArray](class_packedstringarray.md) **get_sections**\ (\ ) const [🔗](#class_ConfigFile_method_get_sections) + +Returns an array of all defined section identifiers. + +
+ + + + + +[Variant](class_variant.md) **get_value**\ (\ section\: [String](class_string.md), key\: [String](class_string.md), default\: [Variant](class_variant.md) = null\ ) const [🔗](#class_ConfigFile_method_get_value) + +Returns the current value for the specified section and key. If either the section or the key do not exist, the method returns the fallback `default` value. If `default` is not specified or set to ``null``, an error is also raised. + +
+ + + + + +[bool](class_bool.md) **has_section**\ (\ section\: [String](class_string.md)\ ) const [🔗](#class_ConfigFile_method_has_section) + +Returns ``true`` if the specified section exists. + +
+ + + + + +[bool](class_bool.md) **has_section_key**\ (\ section\: [String](class_string.md), key\: [String](class_string.md)\ ) const [🔗](#class_ConfigFile_method_has_section_key) + +Returns ``true`` if the specified section-key pair exists. + +
+ + + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **load**\ (\ path\: [String](class_string.md), allow_objects\: [bool](class_bool.md) = false\ ) [🔗](#class_ConfigFile_method_load) + +Loads the config file specified as a parameter. The file's contents are parsed and loaded in the **ConfigFile** object which the method was called on. If `allow_objects` is ``true``, decoding objects is allowed. + +Returns [@GlobalScope.OK](class_@globalscope.md#class_@GlobalScope_constant_OK) on success, or one of the other [Error](class_@globalscope.md#enum_@GlobalScope_Error) values if the operation failed. + +Internally, this uses the same decoding mechanism as the [@GlobalScope.str_to_var()](class_@globalscope.md#class_@GlobalScope_method_str_to_var) and [@GlobalScope.str_to_var_with_objects()](class_@globalscope.md#class_@GlobalScope_method_str_to_var_with_objects) methods. + +\ **Warning:** Deserialized objects can contain code which gets executed. Do not use this option if the serialized object comes from untrusted sources to avoid potential security threats such as remote code execution. + +
+ + + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **load_encrypted**\ (\ path\: [String](class_string.md), key\: [PackedByteArray](class_packedbytearray.md), allow_objects\: [bool](class_bool.md) = false\ ) [🔗](#class_ConfigFile_method_load_encrypted) + +Loads the encrypted config file specified as a parameter, using the provided `key` to decrypt it. The file's contents are parsed and loaded in the **ConfigFile** object which the method was called on. + +See [load()](class_configfile.md#class_ConfigFile_method_load) for details. + +
+ + + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **load_encrypted_pass**\ (\ path\: [String](class_string.md), password\: [String](class_string.md), allow_objects\: [bool](class_bool.md) = false\ ) [🔗](#class_ConfigFile_method_load_encrypted_pass) + +Loads the encrypted config file specified as a parameter, using the provided `password` to decrypt it. The file's contents are parsed and loaded in the **ConfigFile** object which the method was called on. + +See [load()](class_configfile.md#class_ConfigFile_method_load) for details. + +
+ + + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **parse**\ (\ data\: [String](class_string.md), allow_objects\: [bool](class_bool.md) = false\ ) [🔗](#class_ConfigFile_method_parse) + +Parses the passed string as the contents of a config file. The string is parsed and loaded in the ConfigFile object which the method was called on. If `allow_objects` is ``true``, decoding objects is allowed. + +Returns [@GlobalScope.OK](class_@globalscope.md#class_@GlobalScope_constant_OK) on success, or one of the other [Error](class_@globalscope.md#enum_@GlobalScope_Error) values if the operation failed. + +Internally, this uses the same decoding mechanism as the [@GlobalScope.str_to_var()](class_@globalscope.md#class_@GlobalScope_method_str_to_var) and [@GlobalScope.str_to_var_with_objects()](class_@globalscope.md#class_@GlobalScope_method_str_to_var_with_objects) methods. + +\ **Warning:** Deserialized objects can contain code which gets executed. Do not use this option if the serialized object comes from untrusted sources to avoid potential security threats such as remote code execution. + +
+ + + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **save**\ (\ path\: [String](class_string.md), full_objects\: [bool](class_bool.md) = false\ ) [🔗](#class_ConfigFile_method_save) + +Saves the contents of the **ConfigFile** object to the file specified as a parameter. The output file uses an INI-style structure. If `full_objects` is ``true``, encoding objects is allowed (and can potentially include code). + +Returns [@GlobalScope.OK](class_@globalscope.md#class_@GlobalScope_constant_OK) on success, or one of the other [Error](class_@globalscope.md#enum_@GlobalScope_Error) values if the operation failed. + +Internally, this uses the same encoding mechanism as the [@GlobalScope.var_to_str()](class_@globalscope.md#class_@GlobalScope_method_var_to_str) and [@GlobalScope.var_to_str_with_objects()](class_@globalscope.md#class_@GlobalScope_method_var_to_str_with_objects) method. + +\ **Note:** Not all properties are included. Only properties that are configured with the [@GlobalScope.PROPERTY_USAGE_STORAGE](class_@globalscope.md#class_@GlobalScope_constant_PROPERTY_USAGE_STORAGE) flag set will be serialized. You can add an usage flag to a property by overriding the [Object._validate_property()](class_object.md#class_Object_private_method__validate_property) method in your class. In GDScript you can also use the [@GDScript.@export](class_@gdscript.md#class_@GDScript_annotation_@export) annotation. See [PropertyUsageFlags](class_@globalscope.md#enum_@GlobalScope_PropertyUsageFlags) for the possible usage flags. + +
+ + + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **save_encrypted**\ (\ path\: [String](class_string.md), key\: [PackedByteArray](class_packedbytearray.md), full_objects\: [bool](class_bool.md) = false\ ) [🔗](#class_ConfigFile_method_save_encrypted) + +Saves the contents of the **ConfigFile** object to the AES-256 encrypted file specified as a parameter, using the provided `key` to encrypt it. The output file uses an INI-style structure. + +See [save()](class_configfile.md#class_ConfigFile_method_save) for details. + +
+ + + + + +[Error](class_@globalscope.md#enum_@GlobalScope_Error) **save_encrypted_pass**\ (\ path\: [String](class_string.md), password\: [String](class_string.md), full_objects\: [bool](class_bool.md) = false\ ) [🔗](#class_ConfigFile_method_save_encrypted_pass) + +Saves the contents of the **ConfigFile** object to the AES-256 encrypted file specified as a parameter, using the provided `password` to encrypt it. The output file uses an INI-style structure. + +See [save()](class_configfile.md#class_ConfigFile_method_save) for details. + +
+ + + + + +`void` **set_value**\ (\ section\: [String](class_string.md), key\: [String](class_string.md), value\: [Variant](class_variant.md)\ ) [🔗](#class_ConfigFile_method_set_value) + +Assigns a value to the specified key of the specified section. If either the section or the key do not exist, they are created. Passing a ``null`` value deletes the specified key if it exists, and deletes the section if it ends up empty once the key has been removed. + diff --git a/docs/Classes/class_confirmationdialog.md b/docs/Classes/class_confirmationdialog.md new file mode 100644 index 00000000..68bb45ef --- /dev/null +++ b/docs/Classes/class_confirmationdialog.md @@ -0,0 +1,119 @@ + + + + + + + + + +# ConfirmationDialog + +**Inherits:** [AcceptDialog](class_acceptdialog.md) **<** [Window](class_window.md) **<** [Viewport](class_viewport.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +**Inherited By:** [EditorCommandPalette](class_editorcommandpalette.md), [EditorFileDialog](class_editorfiledialog.md), [FileDialog](class_filedialog.md), [ScriptCreateDialog](class_scriptcreatedialog.md) + +A dialog used for confirmation of actions. + + + +## Description + +A dialog used for confirmation of actions. This window is similar to [AcceptDialog](class_acceptdialog.md), but pressing its Cancel button can have a different outcome from pressing the OK button. The order of the two buttons varies depending on the host OS. + +To get cancel action, you can use: + + + + +```gdscript + get_cancel_button().pressed.connect(_on_canceled) +``` + +```csharp + GetCancelButton().Pressed += OnCanceled; +``` + + + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + +
[String](class_string.md)[cancel_button_text](#class_ConfirmationDialog_property_cancel_button_text)`"Cancel"`
[Vector2i](class_vector2i.md)min_size`Vector2i(200, 70)` (overrides [Window.min_size](class_window.md#class_Window_property_min_size))
[Vector2i](class_vector2i.md)size`Vector2i(200, 100)` (overrides [Window.size](class_window.md#class_Window_property_size))
[String](class_string.md)title`"Please Confirm..."` (overrides [Window.title](class_window.md#class_Window_property_title))
+ + + +## Methods + + + + + + + + + + +
[Button](class_button.md)[get_cancel_button](#class_ConfirmationDialog_method_get_cancel_button)\ (\ )
+ +
+ + + +## Property Descriptions + + + + + +[String](class_string.md) **cancel_button_text** = `"Cancel"` [🔗](#class_ConfirmationDialog_property_cancel_button_text) + + + +- `void` **set_cancel_button_text**\ (\ value\: [String](class_string.md)\ ) +- [String](class_string.md) **get_cancel_button_text**\ (\ ) + +The text displayed by the cancel button (see [get_cancel_button()](class_confirmationdialog.md#class_ConfirmationDialog_method_get_cancel_button)). + +
+ + + +## Method Descriptions + + + + + +[Button](class_button.md) **get_cancel_button**\ (\ ) [🔗](#class_ConfirmationDialog_method_get_cancel_button) + +Returns the cancel button. + +\ **Warning:** 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 [CanvasItem.visible](class_canvasitem.md#class_CanvasItem_property_visible) property. + diff --git a/docs/Classes/class_container.md b/docs/Classes/class_container.md new file mode 100644 index 00000000..69477af5 --- /dev/null +++ b/docs/Classes/class_container.md @@ -0,0 +1,166 @@ + + + + + + + + + +# Container + +**Inherits:** [Control](class_control.md) **<** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +**Inherited By:** [AspectRatioContainer](class_aspectratiocontainer.md), [BoxContainer](class_boxcontainer.md), [CenterContainer](class_centercontainer.md), [EditorProperty](class_editorproperty.md), [FlowContainer](class_flowcontainer.md), [FoldableContainer](class_foldablecontainer.md), [GraphElement](class_graphelement.md), [GridContainer](class_gridcontainer.md), [MarginContainer](class_margincontainer.md), [PanelContainer](class_panelcontainer.md), [ScrollContainer](class_scrollcontainer.md), [SplitContainer](class_splitcontainer.md), [SubViewportContainer](class_subviewportcontainer.md), [TabContainer](class_tabcontainer.md) + +Base class for all GUI containers. + + + +## Description + +Base class for all GUI containers. A **Container** automatically arranges its child controls in a certain way. This class can be inherited to make custom container types. + + + +## Tutorials + +- [Using Containers](../tutorials/ui/gui_containers.md) + + + +## Properties + + + + + + + + + + + +
[MouseFilter](class_control.md#enum_Control_MouseFilter)mouse_filter`1` (overrides [Control.mouse_filter](class_control.md#class_Control_property_mouse_filter))
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + +
[PackedInt32Array](class_packedint32array.md)[_get_allowed_size_flags_horizontal](#class_Container_private_method__get_allowed_size_flags_horizontal)\ (\ ) virtual const
[PackedInt32Array](class_packedint32array.md)[_get_allowed_size_flags_vertical](#class_Container_private_method__get_allowed_size_flags_vertical)\ (\ ) virtual const
`void`[fit_child_in_rect](#class_Container_method_fit_child_in_rect)\ (\ child\: [Control](class_control.md), rect\: [Rect2](class_rect2.md)\ )
`void`[queue_sort](#class_Container_method_queue_sort)\ (\ )
+ +
+ + + +## Signals + + + + + +**pre_sort_children**\ (\ ) [🔗](#class_Container_signal_pre_sort_children) + +Emitted when children are going to be sorted. + +
+ + + + + +**sort_children**\ (\ ) [🔗](#class_Container_signal_sort_children) + +Emitted when sorting the children is needed. + +
+ + + +## Constants + + + + + +**NOTIFICATION_PRE_SORT_CHILDREN** = `50` [🔗](#class_Container_constant_NOTIFICATION_PRE_SORT_CHILDREN) + +Notification just before children are going to be sorted, in case there's something to process beforehand. + + + + + +**NOTIFICATION_SORT_CHILDREN** = `51` [🔗](#class_Container_constant_NOTIFICATION_SORT_CHILDREN) + +Notification for when sorting the children, it must be obeyed immediately. + +
+ + + +## Method Descriptions + + + + + +[PackedInt32Array](class_packedint32array.md) **_get_allowed_size_flags_horizontal**\ (\ ) virtual const [🔗](#class_Container_private_method__get_allowed_size_flags_horizontal) + +Implement to return a list of allowed horizontal [SizeFlags](class_control.md#enum_Control_SizeFlags) for child nodes. This doesn't technically prevent the usages of any other size flags, if your implementation requires that. This only limits the options available to the user in the Inspector dock. + +\ **Note:** Having no size flags is equal to having [Control.SIZE_SHRINK_BEGIN](class_control.md#class_Control_constant_SIZE_SHRINK_BEGIN). As such, this value is always implicitly allowed. + +
+ + + + + +[PackedInt32Array](class_packedint32array.md) **_get_allowed_size_flags_vertical**\ (\ ) virtual const [🔗](#class_Container_private_method__get_allowed_size_flags_vertical) + +Implement to return a list of allowed vertical [SizeFlags](class_control.md#enum_Control_SizeFlags) for child nodes. This doesn't technically prevent the usages of any other size flags, if your implementation requires that. This only limits the options available to the user in the Inspector dock. + +\ **Note:** Having no size flags is equal to having [Control.SIZE_SHRINK_BEGIN](class_control.md#class_Control_constant_SIZE_SHRINK_BEGIN). As such, this value is always implicitly allowed. + +
+ + + + + +`void` **fit_child_in_rect**\ (\ child\: [Control](class_control.md), rect\: [Rect2](class_rect2.md)\ ) [🔗](#class_Container_method_fit_child_in_rect) + +Fit a child control in a given rect. This is mainly a helper for creating custom container classes. + +
+ + + + + +`void` **queue_sort**\ (\ ) [🔗](#class_Container_method_queue_sort) + +Queue resort of the contained children. This is called automatically anyway, but can be called upon request. + diff --git a/docs/Classes/class_control.md b/docs/Classes/class_control.md new file mode 100644 index 00000000..6e5234bd --- /dev/null +++ b/docs/Classes/class_control.md @@ -0,0 +1,3632 @@ + + + + + + + + + +# Control + +**Inherits:** [CanvasItem](class_canvasitem.md) **<** [Node](class_node.md) **<** [Object](class_object.md) + +**Inherited By:** [BaseButton](class_basebutton.md), [ColorRect](class_colorrect.md), [Container](class_container.md), [GraphEdit](class_graphedit.md), [ItemList](class_itemlist.md), [Label](class_label.md), [LineEdit](class_lineedit.md), [MenuBar](class_menubar.md), [NinePatchRect](class_ninepatchrect.md), [Panel](class_panel.md), [Range](class_range.md), [ReferenceRect](class_referencerect.md), [RichTextLabel](class_richtextlabel.md), [Separator](class_separator.md), [TabBar](class_tabbar.md), [TextEdit](class_textedit.md), [TextureRect](class_texturerect.md), [Tree](class_tree.md), [VideoStreamPlayer](class_videostreamplayer.md) + +Base class for all GUI controls. Adapts its position and size based on its parent control. + + + +## Description + +Base class for all UI-related nodes. **Control** features a bounding rectangle that defines its extents, an anchor position relative to its parent control or the current viewport, and offsets relative to the anchor. The offsets update automatically when the node, any of its parents, or the screen size change. + +For more information on Redot's UI system, anchors, offsets, and containers, see the related tutorials in the manual. To build flexible UIs, you'll need a mix of UI elements that inherit from **Control** and [Container](class_container.md) nodes. + +\ **Note:** Since both [Node2D](class_node2d.md) and **Control** inherit from [CanvasItem](class_canvasitem.md), they share several concepts from the class such as the [CanvasItem.z_index](class_canvasitem.md#class_CanvasItem_property_z_index) and [CanvasItem.visible](class_canvasitem.md#class_CanvasItem_property_visible) properties. + +\ **User Interface nodes and input**\ + +Redot propagates input events via viewports. Each [Viewport](class_viewport.md) is responsible for propagating [InputEvent](class_inputevent.md)\ s to their child nodes. As the [SceneTree.root](class_scenetree.md#class_SceneTree_property_root) is a [Window](class_window.md), this already happens automatically for all UI elements in your game. + +Input events are propagated through the [SceneTree](class_scenetree.md) from the root node to all child nodes by calling [Node._input()](class_node.md#class_Node_private_method__input). For UI elements specifically, it makes more sense to override the virtual method [_gui_input()](class_control.md#class_Control_private_method__gui_input), which filters out unrelated input events, such as by checking z-order, [mouse_filter](class_control.md#class_Control_property_mouse_filter), focus, or if the event was inside of the control's bounding box. + +Call [accept_event()](class_control.md#class_Control_method_accept_event) so no other node receives the event. Once you accept an input, it becomes handled so [Node._unhandled_input()](class_node.md#class_Node_private_method__unhandled_input) will not process it. + +Only one **Control** node can be in focus. Only the node in focus will receive events. To get the focus, call [grab_focus()](class_control.md#class_Control_method_grab_focus). **Control** nodes lose focus when another node grabs it, or if you hide the node in focus. + +Sets [mouse_filter](class_control.md#class_Control_property_mouse_filter) to [MOUSE_FILTER_IGNORE](class_control.md#class_Control_constant_MOUSE_FILTER_IGNORE) to tell a **Control** node to ignore mouse or touch events. You'll need it if you place an icon on top of a button. + +\ [Theme](class_theme.md) resources change the control's appearance. The [theme](class_control.md#class_Control_property_theme) of a **Control** node affects all of its direct and indirect children (as long as a chain of controls is uninterrupted). To override some of the theme items, call one of the ``add_theme_*_override`` methods, like [add_theme_font_override()](class_control.md#class_Control_method_add_theme_font_override). You can also override theme items in the Inspector. + +\ **Note:** Theme items are *not* [Object](class_object.md) properties. This means you can't access their values using [Object.get()](class_object.md#class_Object_method_get) and [Object.set()](class_object.md#class_Object_method_set). Instead, use the ``get_theme_*`` and ``add_theme_*_override`` methods provided by this class. + + + +## Tutorials + +- [GUI documentation index](../tutorials/ui/index.md) + +- [Custom drawing in 2D](../tutorials/2d/custom_drawing_in_2d.md) + +- [Control node gallery](../tutorials/ui/control_node_gallery.md) + +- [Multiple resolutions](../tutorials/rendering/multiple_resolutions.md) + +- [All GUI Demos](https://github.com/redot-engine/redot-demo-projects/tree/master/gui) + + + +## Properties + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[Array](class_array.md)\[[NodePath](class_nodepath.md)\][accessibility_controls_nodes](#class_Control_property_accessibility_controls_nodes)`[]`
[Array](class_array.md)\[[NodePath](class_nodepath.md)\][accessibility_described_by_nodes](#class_Control_property_accessibility_described_by_nodes)`[]`
[String](class_string.md)[accessibility_description](#class_Control_property_accessibility_description)`""`
[Array](class_array.md)\[[NodePath](class_nodepath.md)\][accessibility_flow_to_nodes](#class_Control_property_accessibility_flow_to_nodes)`[]`
[Array](class_array.md)\[[NodePath](class_nodepath.md)\][accessibility_labeled_by_nodes](#class_Control_property_accessibility_labeled_by_nodes)`[]`
[AccessibilityLiveMode](class_displayserver.md#enum_DisplayServer_AccessibilityLiveMode)[accessibility_live](#class_Control_property_accessibility_live)`0`
[String](class_string.md)[accessibility_name](#class_Control_property_accessibility_name)`""`
[float](class_float.md)[anchor_bottom](#class_Control_property_anchor_bottom)`0.0`
[float](class_float.md)[anchor_left](#class_Control_property_anchor_left)`0.0`
[float](class_float.md)[anchor_right](#class_Control_property_anchor_right)`0.0`
[float](class_float.md)[anchor_top](#class_Control_property_anchor_top)`0.0`
[bool](class_bool.md)[auto_translate](#class_Control_property_auto_translate)
[bool](class_bool.md)[clip_contents](#class_Control_property_clip_contents)`false`
[Vector2](class_vector2.md)[custom_minimum_size](#class_Control_property_custom_minimum_size)`Vector2(0, 0)`
[FocusBehaviorRecursive](class_control.md#enum_Control_FocusBehaviorRecursive)[focus_behavior_recursive](#class_Control_property_focus_behavior_recursive)`0`
[FocusMode](class_control.md#enum_Control_FocusMode)[focus_mode](#class_Control_property_focus_mode)`0`
[NodePath](class_nodepath.md)[focus_neighbor_bottom](#class_Control_property_focus_neighbor_bottom)`NodePath("")`
[NodePath](class_nodepath.md)[focus_neighbor_left](#class_Control_property_focus_neighbor_left)`NodePath("")`
[NodePath](class_nodepath.md)[focus_neighbor_right](#class_Control_property_focus_neighbor_right)`NodePath("")`
[NodePath](class_nodepath.md)[focus_neighbor_top](#class_Control_property_focus_neighbor_top)`NodePath("")`
[NodePath](class_nodepath.md)[focus_next](#class_Control_property_focus_next)`NodePath("")`
[NodePath](class_nodepath.md)[focus_previous](#class_Control_property_focus_previous)`NodePath("")`
[Vector2](class_vector2.md)[global_position](#class_Control_property_global_position)
[GrowDirection](class_control.md#enum_Control_GrowDirection)[grow_horizontal](#class_Control_property_grow_horizontal)`1`
[GrowDirection](class_control.md#enum_Control_GrowDirection)[grow_vertical](#class_Control_property_grow_vertical)`1`
[LayoutDirection](class_control.md#enum_Control_LayoutDirection)[layout_direction](#class_Control_property_layout_direction)`0`
[bool](class_bool.md)[localize_numeral_system](#class_Control_property_localize_numeral_system)`true`
[MouseBehaviorRecursive](class_control.md#enum_Control_MouseBehaviorRecursive)[mouse_behavior_recursive](#class_Control_property_mouse_behavior_recursive)`0`
[CursorShape](class_control.md#enum_Control_CursorShape)[mouse_default_cursor_shape](#class_Control_property_mouse_default_cursor_shape)`0`
[MouseFilter](class_control.md#enum_Control_MouseFilter)[mouse_filter](#class_Control_property_mouse_filter)`0`
[bool](class_bool.md)[mouse_force_pass_scroll_events](#class_Control_property_mouse_force_pass_scroll_events)`true`
[float](class_float.md)[offset_bottom](#class_Control_property_offset_bottom)`0.0`
[float](class_float.md)[offset_left](#class_Control_property_offset_left)`0.0`
[float](class_float.md)[offset_right](#class_Control_property_offset_right)`0.0`
[float](class_float.md)[offset_top](#class_Control_property_offset_top)`0.0`
[PhysicsInterpolationMode](class_node.md#enum_Node_PhysicsInterpolationMode)physics_interpolation_mode`2` (overrides [Node.physics_interpolation_mode](class_node.md#class_Node_property_physics_interpolation_mode))
[Vector2](class_vector2.md)[pivot_offset](#class_Control_property_pivot_offset)`Vector2(0, 0)`
[Vector2](class_vector2.md)[position](#class_Control_property_position)`Vector2(0, 0)`
[float](class_float.md)[rotation](#class_Control_property_rotation)`0.0`
[float](class_float.md)[rotation_degrees](#class_Control_property_rotation_degrees)
[Vector2](class_vector2.md)[scale](#class_Control_property_scale)`Vector2(1, 1)`
[Node](class_node.md)[shortcut_context](#class_Control_property_shortcut_context)
[Vector2](class_vector2.md)[size](#class_Control_property_size)`Vector2(0, 0)`
**BitField**\[[SizeFlags](class_control.md#enum_Control_SizeFlags)\][size_flags_horizontal](#class_Control_property_size_flags_horizontal)`1`
[float](class_float.md)[size_flags_stretch_ratio](#class_Control_property_size_flags_stretch_ratio)`1.0`
**BitField**\[[SizeFlags](class_control.md#enum_Control_SizeFlags)\][size_flags_vertical](#class_Control_property_size_flags_vertical)`1`
[Theme](class_theme.md)[theme](#class_Control_property_theme)
[StringName](class_stringname.md)[theme_type_variation](#class_Control_property_theme_type_variation)`&""`
[AutoTranslateMode](class_node.md#enum_Node_AutoTranslateMode)[tooltip_auto_translate_mode](#class_Control_property_tooltip_auto_translate_mode)`0`
[String](class_string.md)[tooltip_text](#class_Control_property_tooltip_text)`""`
+ + + +## Methods + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
[String](class_string.md)[_accessibility_get_contextual_info](#class_Control_private_method__accessibility_get_contextual_info)\ (\ ) virtual const
[bool](class_bool.md)[_can_drop_data](#class_Control_private_method__can_drop_data)\ (\ at_position\: [Vector2](class_vector2.md), data\: [Variant](class_variant.md)\ ) virtual const
`void`[_drop_data](#class_Control_private_method__drop_data)\ (\ at_position\: [Vector2](class_vector2.md), data\: [Variant](class_variant.md)\ ) virtual
[String](class_string.md)[_get_accessibility_container_name](#class_Control_private_method__get_accessibility_container_name)\ (\ node\: [Node](class_node.md)\ ) virtual const
[Variant](class_variant.md)[_get_drag_data](#class_Control_private_method__get_drag_data)\ (\ at_position\: [Vector2](class_vector2.md)\ ) virtual
[Vector2](class_vector2.md)[_get_minimum_size](#class_Control_private_method__get_minimum_size)\ (\ ) virtual const
[String](class_string.md)[_get_tooltip](#class_Control_private_method__get_tooltip)\ (\ at_position\: [Vector2](class_vector2.md)\ ) virtual const
`void`[_gui_input](#class_Control_private_method__gui_input)\ (\ event\: [InputEvent](class_inputevent.md)\ ) virtual
[bool](class_bool.md)[_has_point](#class_Control_private_method__has_point)\ (\ point\: [Vector2](class_vector2.md)\ ) virtual const
[Object](class_object.md)[_make_custom_tooltip](#class_Control_private_method__make_custom_tooltip)\ (\ for_text\: [String](class_string.md)\ ) virtual const
[Array](class_array.md)\[[Vector3i](class_vector3i.md)\][_structured_text_parser](#class_Control_private_method__structured_text_parser)\ (\ args\: [Array](class_array.md), text\: [String](class_string.md)\ ) virtual const
`void`[accept_event](#class_Control_method_accept_event)\ (\ )
`void`[accessibility_drag](#class_Control_method_accessibility_drag)\ (\ )
`void`[accessibility_drop](#class_Control_method_accessibility_drop)\ (\ )
`void`[add_theme_color_override](#class_Control_method_add_theme_color_override)\ (\ name\: [StringName](class_stringname.md), color\: [Color](class_color.md)\ )
`void`[add_theme_constant_override](#class_Control_method_add_theme_constant_override)\ (\ name\: [StringName](class_stringname.md), constant\: [int](class_int.md)\ )
`void`[add_theme_font_override](#class_Control_method_add_theme_font_override)\ (\ name\: [StringName](class_stringname.md), font\: [Font](class_font.md)\ )
`void`[add_theme_font_size_override](#class_Control_method_add_theme_font_size_override)\ (\ name\: [StringName](class_stringname.md), font_size\: [int](class_int.md)\ )
`void`[add_theme_icon_override](#class_Control_method_add_theme_icon_override)\ (\ name\: [StringName](class_stringname.md), texture\: [Texture2D](class_texture2d.md)\ )
`void`[add_theme_stylebox_override](#class_Control_method_add_theme_stylebox_override)\ (\ name\: [StringName](class_stringname.md), stylebox\: [StyleBox](class_stylebox.md)\ )
`void`[begin_bulk_theme_override](#class_Control_method_begin_bulk_theme_override)\ (\ )
`void`[end_bulk_theme_override](#class_Control_method_end_bulk_theme_override)\ (\ )
[Control](class_control.md)[find_next_valid_focus](#class_Control_method_find_next_valid_focus)\ (\ ) const
[Control](class_control.md)[find_prev_valid_focus](#class_Control_method_find_prev_valid_focus)\ (\ ) const
[Control](class_control.md)[find_valid_focus_neighbor](#class_Control_method_find_valid_focus_neighbor)\ (\ side\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const
`void`[force_drag](#class_Control_method_force_drag)\ (\ data\: [Variant](class_variant.md), preview\: [Control](class_control.md)\ )
[float](class_float.md)[get_anchor](#class_Control_method_get_anchor)\ (\ side\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const
[Vector2](class_vector2.md)[get_begin](#class_Control_method_get_begin)\ (\ ) const
[Vector2](class_vector2.md)[get_combined_minimum_size](#class_Control_method_get_combined_minimum_size)\ (\ ) const
[CursorShape](class_control.md#enum_Control_CursorShape)[get_cursor_shape](#class_Control_method_get_cursor_shape)\ (\ position\: [Vector2](class_vector2.md) = Vector2(0, 0)\ ) const
[Vector2](class_vector2.md)[get_end](#class_Control_method_get_end)\ (\ ) const
[FocusMode](class_control.md#enum_Control_FocusMode)[get_focus_mode_with_override](#class_Control_method_get_focus_mode_with_override)\ (\ ) const
[NodePath](class_nodepath.md)[get_focus_neighbor](#class_Control_method_get_focus_neighbor)\ (\ side\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const
[Rect2](class_rect2.md)[get_global_rect](#class_Control_method_get_global_rect)\ (\ ) const
[Vector2](class_vector2.md)[get_minimum_size](#class_Control_method_get_minimum_size)\ (\ ) const
[MouseFilter](class_control.md#enum_Control_MouseFilter)[get_mouse_filter_with_override](#class_Control_method_get_mouse_filter_with_override)\ (\ ) const
[float](class_float.md)[get_offset](#class_Control_method_get_offset)\ (\ offset\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const
[Vector2](class_vector2.md)[get_parent_area_size](#class_Control_method_get_parent_area_size)\ (\ ) const
[Control](class_control.md)[get_parent_control](#class_Control_method_get_parent_control)\ (\ ) const
[Rect2](class_rect2.md)[get_rect](#class_Control_method_get_rect)\ (\ ) const
[Vector2](class_vector2.md)[get_screen_position](#class_Control_method_get_screen_position)\ (\ ) const
[Color](class_color.md)[get_theme_color](#class_Control_method_get_theme_color)\ (\ name\: [StringName](class_stringname.md), theme_type\: [StringName](class_stringname.md) = &""\ ) const
[int](class_int.md)[get_theme_constant](#class_Control_method_get_theme_constant)\ (\ name\: [StringName](class_stringname.md), theme_type\: [StringName](class_stringname.md) = &""\ ) const
[float](class_float.md)[get_theme_default_base_scale](#class_Control_method_get_theme_default_base_scale)\ (\ ) const
[Font](class_font.md)[get_theme_default_font](#class_Control_method_get_theme_default_font)\ (\ ) const
[int](class_int.md)[get_theme_default_font_size](#class_Control_method_get_theme_default_font_size)\ (\ ) const
[Font](class_font.md)[get_theme_font](#class_Control_method_get_theme_font)\ (\ name\: [StringName](class_stringname.md), theme_type\: [StringName](class_stringname.md) = &""\ ) const
[int](class_int.md)[get_theme_font_size](#class_Control_method_get_theme_font_size)\ (\ name\: [StringName](class_stringname.md), theme_type\: [StringName](class_stringname.md) = &""\ ) const
[Texture2D](class_texture2d.md)[get_theme_icon](#class_Control_method_get_theme_icon)\ (\ name\: [StringName](class_stringname.md), theme_type\: [StringName](class_stringname.md) = &""\ ) const
[StyleBox](class_stylebox.md)[get_theme_stylebox](#class_Control_method_get_theme_stylebox)\ (\ name\: [StringName](class_stringname.md), theme_type\: [StringName](class_stringname.md) = &""\ ) const
[String](class_string.md)[get_tooltip](#class_Control_method_get_tooltip)\ (\ at_position\: [Vector2](class_vector2.md) = Vector2(0, 0)\ ) const
`void`[grab_click_focus](#class_Control_method_grab_click_focus)\ (\ )
`void`[grab_focus](#class_Control_method_grab_focus)\ (\ )
[bool](class_bool.md)[has_focus](#class_Control_method_has_focus)\ (\ ) const
[bool](class_bool.md)[has_theme_color](#class_Control_method_has_theme_color)\ (\ name\: [StringName](class_stringname.md), theme_type\: [StringName](class_stringname.md) = &""\ ) const
[bool](class_bool.md)[has_theme_color_override](#class_Control_method_has_theme_color_override)\ (\ name\: [StringName](class_stringname.md)\ ) const
[bool](class_bool.md)[has_theme_constant](#class_Control_method_has_theme_constant)\ (\ name\: [StringName](class_stringname.md), theme_type\: [StringName](class_stringname.md) = &""\ ) const
[bool](class_bool.md)[has_theme_constant_override](#class_Control_method_has_theme_constant_override)\ (\ name\: [StringName](class_stringname.md)\ ) const
[bool](class_bool.md)[has_theme_font](#class_Control_method_has_theme_font)\ (\ name\: [StringName](class_stringname.md), theme_type\: [StringName](class_stringname.md) = &""\ ) const
[bool](class_bool.md)[has_theme_font_override](#class_Control_method_has_theme_font_override)\ (\ name\: [StringName](class_stringname.md)\ ) const
[bool](class_bool.md)[has_theme_font_size](#class_Control_method_has_theme_font_size)\ (\ name\: [StringName](class_stringname.md), theme_type\: [StringName](class_stringname.md) = &""\ ) const
[bool](class_bool.md)[has_theme_font_size_override](#class_Control_method_has_theme_font_size_override)\ (\ name\: [StringName](class_stringname.md)\ ) const
[bool](class_bool.md)[has_theme_icon](#class_Control_method_has_theme_icon)\ (\ name\: [StringName](class_stringname.md), theme_type\: [StringName](class_stringname.md) = &""\ ) const
[bool](class_bool.md)[has_theme_icon_override](#class_Control_method_has_theme_icon_override)\ (\ name\: [StringName](class_stringname.md)\ ) const
[bool](class_bool.md)[has_theme_stylebox](#class_Control_method_has_theme_stylebox)\ (\ name\: [StringName](class_stringname.md), theme_type\: [StringName](class_stringname.md) = &""\ ) const
[bool](class_bool.md)[has_theme_stylebox_override](#class_Control_method_has_theme_stylebox_override)\ (\ name\: [StringName](class_stringname.md)\ ) const
[bool](class_bool.md)[is_drag_successful](#class_Control_method_is_drag_successful)\ (\ ) const
[bool](class_bool.md)[is_layout_rtl](#class_Control_method_is_layout_rtl)\ (\ ) const
`void`[release_focus](#class_Control_method_release_focus)\ (\ )
`void`[remove_theme_color_override](#class_Control_method_remove_theme_color_override)\ (\ name\: [StringName](class_stringname.md)\ )
`void`[remove_theme_constant_override](#class_Control_method_remove_theme_constant_override)\ (\ name\: [StringName](class_stringname.md)\ )
`void`[remove_theme_font_override](#class_Control_method_remove_theme_font_override)\ (\ name\: [StringName](class_stringname.md)\ )
`void`[remove_theme_font_size_override](#class_Control_method_remove_theme_font_size_override)\ (\ name\: [StringName](class_stringname.md)\ )
`void`[remove_theme_icon_override](#class_Control_method_remove_theme_icon_override)\ (\ name\: [StringName](class_stringname.md)\ )
`void`[remove_theme_stylebox_override](#class_Control_method_remove_theme_stylebox_override)\ (\ name\: [StringName](class_stringname.md)\ )
`void`[reset_size](#class_Control_method_reset_size)\ (\ )
`void`[set_anchor](#class_Control_method_set_anchor)\ (\ side\: [Side](class_@globalscope.md#enum_@GlobalScope_Side), anchor\: [float](class_float.md), keep_offset\: [bool](class_bool.md) = false, push_opposite_anchor\: [bool](class_bool.md) = true\ )
`void`[set_anchor_and_offset](#class_Control_method_set_anchor_and_offset)\ (\ side\: [Side](class_@globalscope.md#enum_@GlobalScope_Side), anchor\: [float](class_float.md), offset\: [float](class_float.md), push_opposite_anchor\: [bool](class_bool.md) = false\ )
`void`[set_anchors_and_offsets_preset](#class_Control_method_set_anchors_and_offsets_preset)\ (\ preset\: [LayoutPreset](class_control.md#enum_Control_LayoutPreset), resize_mode\: [LayoutPresetMode](class_control.md#enum_Control_LayoutPresetMode) = 0, margin\: [int](class_int.md) = 0\ )
`void`[set_anchors_preset](#class_Control_method_set_anchors_preset)\ (\ preset\: [LayoutPreset](class_control.md#enum_Control_LayoutPreset), keep_offsets\: [bool](class_bool.md) = false\ )
`void`[set_begin](#class_Control_method_set_begin)\ (\ position\: [Vector2](class_vector2.md)\ )
`void`[set_drag_forwarding](#class_Control_method_set_drag_forwarding)\ (\ drag_func\: [Callable](class_callable.md), can_drop_func\: [Callable](class_callable.md), drop_func\: [Callable](class_callable.md)\ )
`void`[set_drag_preview](#class_Control_method_set_drag_preview)\ (\ control\: [Control](class_control.md)\ )
`void`[set_end](#class_Control_method_set_end)\ (\ position\: [Vector2](class_vector2.md)\ )
`void`[set_focus_neighbor](#class_Control_method_set_focus_neighbor)\ (\ side\: [Side](class_@globalscope.md#enum_@GlobalScope_Side), neighbor\: [NodePath](class_nodepath.md)\ )
`void`[set_global_position](#class_Control_method_set_global_position)\ (\ position\: [Vector2](class_vector2.md), keep_offsets\: [bool](class_bool.md) = false\ )
`void`[set_offset](#class_Control_method_set_offset)\ (\ side\: [Side](class_@globalscope.md#enum_@GlobalScope_Side), offset\: [float](class_float.md)\ )
`void`[set_offsets_preset](#class_Control_method_set_offsets_preset)\ (\ preset\: [LayoutPreset](class_control.md#enum_Control_LayoutPreset), resize_mode\: [LayoutPresetMode](class_control.md#enum_Control_LayoutPresetMode) = 0, margin\: [int](class_int.md) = 0\ )
`void`[set_position](#class_Control_method_set_position)\ (\ position\: [Vector2](class_vector2.md), keep_offsets\: [bool](class_bool.md) = false\ )
`void`[set_size](#class_Control_method_set_size)\ (\ size\: [Vector2](class_vector2.md), keep_offsets\: [bool](class_bool.md) = false\ )
`void`[update_minimum_size](#class_Control_method_update_minimum_size)\ (\ )
`void`[warp_mouse](#class_Control_method_warp_mouse)\ (\ position\: [Vector2](class_vector2.md)\ )
+ +
+ + + +## Signals + + + + + +**focus_entered**\ (\ ) [🔗](#class_Control_signal_focus_entered) + +Emitted when the node gains focus. + +
+ + + + + +**focus_exited**\ (\ ) [🔗](#class_Control_signal_focus_exited) + +Emitted when the node loses focus. + +
+ + + + + +**gui_input**\ (\ event\: [InputEvent](class_inputevent.md)\ ) [🔗](#class_Control_signal_gui_input) + +Emitted when the node receives an [InputEvent](class_inputevent.md). + +
+ + + + + +**minimum_size_changed**\ (\ ) [🔗](#class_Control_signal_minimum_size_changed) + +Emitted when the node's minimum size changes. + +
+ + + + + +**mouse_entered**\ (\ ) [🔗](#class_Control_signal_mouse_entered) + +Emitted when the mouse cursor enters the control's (or any child control's) visible area, that is not occluded behind other Controls or Windows, provided its [mouse_filter](class_control.md#class_Control_property_mouse_filter) lets the event reach it and regardless if it's currently focused or not. + +\ **Note:** [CanvasItem.z_index](class_canvasitem.md#class_CanvasItem_property_z_index) doesn't affect, which Control receives the signal. + +
+ + + + + +**mouse_exited**\ (\ ) [🔗](#class_Control_signal_mouse_exited) + +Emitted when the mouse cursor leaves the control's (and all child control's) visible area, that is not occluded behind other Controls or Windows, provided its [mouse_filter](class_control.md#class_Control_property_mouse_filter) lets the event reach it and regardless if it's currently focused or not. + +\ **Note:** [CanvasItem.z_index](class_canvasitem.md#class_CanvasItem_property_z_index) doesn't affect, which Control receives the signal. + +\ **Note:** If you want to check whether the mouse truly left the area, ignoring any top nodes, you can use code like this: + +``` + func _on_mouse_exited(): + if not Rect2(Vector2(), size).has_point(get_local_mouse_position()): + # Not hovering over area. +``` + +
+ + + + + +**resized**\ (\ ) [🔗](#class_Control_signal_resized) + +Emitted when the control changes size. + +
+ + + + + +**size_flags_changed**\ (\ ) [🔗](#class_Control_signal_size_flags_changed) + +Emitted when one of the size flags changes. See [size_flags_horizontal](class_control.md#class_Control_property_size_flags_horizontal) and [size_flags_vertical](class_control.md#class_Control_property_size_flags_vertical). + +
+ + + + + +**theme_changed**\ (\ ) [🔗](#class_Control_signal_theme_changed) + +Emitted when the [NOTIFICATION_THEME_CHANGED](class_control.md#class_Control_constant_NOTIFICATION_THEME_CHANGED) notification is sent. + +
+ + + +## Enumerations + + + + + +enum **FocusMode**: [🔗](#enum_Control_FocusMode) + + + + + +[FocusMode](class_control.md#enum_Control_FocusMode) **FOCUS_NONE** = `0` + +The node cannot grab focus. Use with [focus_mode](class_control.md#class_Control_property_focus_mode). + + + +[FocusMode](class_control.md#enum_Control_FocusMode) **FOCUS_CLICK** = `1` + +The node can only grab focus on mouse clicks. Use with [focus_mode](class_control.md#class_Control_property_focus_mode). + + + +[FocusMode](class_control.md#enum_Control_FocusMode) **FOCUS_ALL** = `2` + +The node can grab focus on mouse click, using the arrows and the Tab keys on the keyboard, or using the D-pad buttons on a gamepad. Use with [focus_mode](class_control.md#class_Control_property_focus_mode). + + + +[FocusMode](class_control.md#enum_Control_FocusMode) **FOCUS_ACCESSIBILITY** = `3` + +The node can grab focus only when screen reader is active. Use with [focus_mode](class_control.md#class_Control_property_focus_mode).
+ + + + + +enum **FocusBehaviorRecursive**: [🔗](#enum_Control_FocusBehaviorRecursive) + + + + + +[FocusBehaviorRecursive](class_control.md#enum_Control_FocusBehaviorRecursive) **FOCUS_BEHAVIOR_INHERITED** = `0` + +Inherits the [focus_behavior_recursive](class_control.md#class_Control_property_focus_behavior_recursive) from the parent control. If there is no parent control, this is the same as [FOCUS_BEHAVIOR_ENABLED](class_control.md#class_Control_constant_FOCUS_BEHAVIOR_ENABLED). + + + +[FocusBehaviorRecursive](class_control.md#enum_Control_FocusBehaviorRecursive) **FOCUS_BEHAVIOR_DISABLED** = `1` + +Prevents the control from getting focused. [get_focus_mode_with_override()](class_control.md#class_Control_method_get_focus_mode_with_override) will return [FOCUS_NONE](class_control.md#class_Control_constant_FOCUS_NONE). + + + +[FocusBehaviorRecursive](class_control.md#enum_Control_FocusBehaviorRecursive) **FOCUS_BEHAVIOR_ENABLED** = `2` + +Allows the control to be focused, depending on the [focus_mode](class_control.md#class_Control_property_focus_mode). This can be used to ignore the parent's [focus_behavior_recursive](class_control.md#class_Control_property_focus_behavior_recursive). [get_focus_mode_with_override()](class_control.md#class_Control_method_get_focus_mode_with_override) will return the [focus_mode](class_control.md#class_Control_property_focus_mode).
+ + + + + +enum **MouseBehaviorRecursive**: [🔗](#enum_Control_MouseBehaviorRecursive) + + + + + +[MouseBehaviorRecursive](class_control.md#enum_Control_MouseBehaviorRecursive) **MOUSE_BEHAVIOR_INHERITED** = `0` + +Inherits the [mouse_behavior_recursive](class_control.md#class_Control_property_mouse_behavior_recursive) from the parent control. If there is no parent control, this is the same as [MOUSE_BEHAVIOR_ENABLED](class_control.md#class_Control_constant_MOUSE_BEHAVIOR_ENABLED). + + + +[MouseBehaviorRecursive](class_control.md#enum_Control_MouseBehaviorRecursive) **MOUSE_BEHAVIOR_DISABLED** = `1` + +Prevents the control from receiving mouse input. [get_mouse_filter_with_override()](class_control.md#class_Control_method_get_mouse_filter_with_override) will return [MOUSE_FILTER_IGNORE](class_control.md#class_Control_constant_MOUSE_FILTER_IGNORE). + + + +[MouseBehaviorRecursive](class_control.md#enum_Control_MouseBehaviorRecursive) **MOUSE_BEHAVIOR_ENABLED** = `2` + +Allows the control to be receive mouse input, depending on the [mouse_filter](class_control.md#class_Control_property_mouse_filter). This can be used to ignore the parent's [mouse_behavior_recursive](class_control.md#class_Control_property_mouse_behavior_recursive). [get_mouse_filter_with_override()](class_control.md#class_Control_method_get_mouse_filter_with_override) will return the [mouse_filter](class_control.md#class_Control_property_mouse_filter).
+ + + + + +enum **CursorShape**: [🔗](#enum_Control_CursorShape) + + + + + +[CursorShape](class_control.md#enum_Control_CursorShape) **CURSOR_ARROW** = `0` + +Show the system's arrow mouse cursor when the user hovers the node. Use with [mouse_default_cursor_shape](class_control.md#class_Control_property_mouse_default_cursor_shape). + + + +[CursorShape](class_control.md#enum_Control_CursorShape) **CURSOR_IBEAM** = `1` + +Show the system's I-beam mouse cursor when the user hovers the node. The I-beam pointer has a shape similar to "I". It tells the user they can highlight or insert text. + + + +[CursorShape](class_control.md#enum_Control_CursorShape) **CURSOR_POINTING_HAND** = `2` + +Show the system's pointing hand mouse cursor when the user hovers the node. + + + +[CursorShape](class_control.md#enum_Control_CursorShape) **CURSOR_CROSS** = `3` + +Show the system's cross mouse cursor when the user hovers the node. + + + +[CursorShape](class_control.md#enum_Control_CursorShape) **CURSOR_WAIT** = `4` + +Show the system's wait mouse cursor when the user hovers the node. Often an hourglass. + + + +[CursorShape](class_control.md#enum_Control_CursorShape) **CURSOR_BUSY** = `5` + +Show the system's busy mouse cursor when the user hovers the node. Often an arrow with a small hourglass. + + + +[CursorShape](class_control.md#enum_Control_CursorShape) **CURSOR_DRAG** = `6` + +Show the system's drag mouse cursor, often a closed fist or a cross symbol, when the user hovers the node. It tells the user they're currently dragging an item, like a node in the Scene dock. + + + +[CursorShape](class_control.md#enum_Control_CursorShape) **CURSOR_CAN_DROP** = `7` + +Show the system's drop mouse cursor when the user hovers the node. It can be an open hand. It tells the user they can drop an item they're currently grabbing, like a node in the Scene dock. + + + +[CursorShape](class_control.md#enum_Control_CursorShape) **CURSOR_FORBIDDEN** = `8` + +Show the system's forbidden mouse cursor when the user hovers the node. Often a crossed circle. + + + +[CursorShape](class_control.md#enum_Control_CursorShape) **CURSOR_VSIZE** = `9` + +Show the system's vertical resize mouse cursor when the user hovers the node. A double-headed vertical arrow. It tells the user they can resize the window or the panel vertically. + + + +[CursorShape](class_control.md#enum_Control_CursorShape) **CURSOR_HSIZE** = `10` + +Show the system's horizontal resize mouse cursor when the user hovers the node. A double-headed horizontal arrow. It tells the user they can resize the window or the panel horizontally. + + + +[CursorShape](class_control.md#enum_Control_CursorShape) **CURSOR_BDIAGSIZE** = `11` + +Show the system's window resize mouse cursor when the user hovers the node. The cursor is a double-headed arrow that goes from the bottom left to the top right. It tells the user they can resize the window or the panel both horizontally and vertically. + + + +[CursorShape](class_control.md#enum_Control_CursorShape) **CURSOR_FDIAGSIZE** = `12` + +Show the system's window resize mouse cursor when the user hovers the node. The cursor is a double-headed arrow that goes from the top left to the bottom right, the opposite of [CURSOR_BDIAGSIZE](class_control.md#class_Control_constant_CURSOR_BDIAGSIZE). It tells the user they can resize the window or the panel both horizontally and vertically. + + + +[CursorShape](class_control.md#enum_Control_CursorShape) **CURSOR_MOVE** = `13` + +Show the system's move mouse cursor when the user hovers the node. It shows 2 double-headed arrows at a 90 degree angle. It tells the user they can move a UI element freely. + + + +[CursorShape](class_control.md#enum_Control_CursorShape) **CURSOR_VSPLIT** = `14` + +Show the system's vertical split mouse cursor when the user hovers the node. On Windows, it's the same as [CURSOR_VSIZE](class_control.md#class_Control_constant_CURSOR_VSIZE). + + + +[CursorShape](class_control.md#enum_Control_CursorShape) **CURSOR_HSPLIT** = `15` + +Show the system's horizontal split mouse cursor when the user hovers the node. On Windows, it's the same as [CURSOR_HSIZE](class_control.md#class_Control_constant_CURSOR_HSIZE). + + + +[CursorShape](class_control.md#enum_Control_CursorShape) **CURSOR_HELP** = `16` + +Show the system's help mouse cursor when the user hovers the node, a question mark.
+ + + + + +enum **LayoutPreset**: [🔗](#enum_Control_LayoutPreset) + + + + + +[LayoutPreset](class_control.md#enum_Control_LayoutPreset) **PRESET_TOP_LEFT** = `0` + +Snap all 4 anchors to the top-left of the parent control's bounds. Use with [set_anchors_preset()](class_control.md#class_Control_method_set_anchors_preset). + + + +[LayoutPreset](class_control.md#enum_Control_LayoutPreset) **PRESET_TOP_RIGHT** = `1` + +Snap all 4 anchors to the top-right of the parent control's bounds. Use with [set_anchors_preset()](class_control.md#class_Control_method_set_anchors_preset). + + + +[LayoutPreset](class_control.md#enum_Control_LayoutPreset) **PRESET_BOTTOM_LEFT** = `2` + +Snap all 4 anchors to the bottom-left of the parent control's bounds. Use with [set_anchors_preset()](class_control.md#class_Control_method_set_anchors_preset). + + + +[LayoutPreset](class_control.md#enum_Control_LayoutPreset) **PRESET_BOTTOM_RIGHT** = `3` + +Snap all 4 anchors to the bottom-right of the parent control's bounds. Use with [set_anchors_preset()](class_control.md#class_Control_method_set_anchors_preset). + + + +[LayoutPreset](class_control.md#enum_Control_LayoutPreset) **PRESET_CENTER_LEFT** = `4` + +Snap all 4 anchors to the center of the left edge of the parent control's bounds. Use with [set_anchors_preset()](class_control.md#class_Control_method_set_anchors_preset). + + + +[LayoutPreset](class_control.md#enum_Control_LayoutPreset) **PRESET_CENTER_TOP** = `5` + +Snap all 4 anchors to the center of the top edge of the parent control's bounds. Use with [set_anchors_preset()](class_control.md#class_Control_method_set_anchors_preset). + + + +[LayoutPreset](class_control.md#enum_Control_LayoutPreset) **PRESET_CENTER_RIGHT** = `6` + +Snap all 4 anchors to the center of the right edge of the parent control's bounds. Use with [set_anchors_preset()](class_control.md#class_Control_method_set_anchors_preset). + + + +[LayoutPreset](class_control.md#enum_Control_LayoutPreset) **PRESET_CENTER_BOTTOM** = `7` + +Snap all 4 anchors to the center of the bottom edge of the parent control's bounds. Use with [set_anchors_preset()](class_control.md#class_Control_method_set_anchors_preset). + + + +[LayoutPreset](class_control.md#enum_Control_LayoutPreset) **PRESET_CENTER** = `8` + +Snap all 4 anchors to the center of the parent control's bounds. Use with [set_anchors_preset()](class_control.md#class_Control_method_set_anchors_preset). + + + +[LayoutPreset](class_control.md#enum_Control_LayoutPreset) **PRESET_LEFT_WIDE** = `9` + +Snap all 4 anchors to the left edge of the parent control. The left offset becomes relative to the left edge and the top offset relative to the top left corner of the node's parent. Use with [set_anchors_preset()](class_control.md#class_Control_method_set_anchors_preset). + + + +[LayoutPreset](class_control.md#enum_Control_LayoutPreset) **PRESET_TOP_WIDE** = `10` + +Snap all 4 anchors to the top edge of the parent control. The left offset becomes relative to the top left corner, the top offset relative to the top edge, and the right offset relative to the top right corner of the node's parent. Use with [set_anchors_preset()](class_control.md#class_Control_method_set_anchors_preset). + + + +[LayoutPreset](class_control.md#enum_Control_LayoutPreset) **PRESET_RIGHT_WIDE** = `11` + +Snap all 4 anchors to the right edge of the parent control. The right offset becomes relative to the right edge and the top offset relative to the top right corner of the node's parent. Use with [set_anchors_preset()](class_control.md#class_Control_method_set_anchors_preset). + + + +[LayoutPreset](class_control.md#enum_Control_LayoutPreset) **PRESET_BOTTOM_WIDE** = `12` + +Snap all 4 anchors to the bottom edge of the parent control. The left offset becomes relative to the bottom left corner, the bottom offset relative to the bottom edge, and the right offset relative to the bottom right corner of the node's parent. Use with [set_anchors_preset()](class_control.md#class_Control_method_set_anchors_preset). + + + +[LayoutPreset](class_control.md#enum_Control_LayoutPreset) **PRESET_VCENTER_WIDE** = `13` + +Snap all 4 anchors to a vertical line that cuts the parent control in half. Use with [set_anchors_preset()](class_control.md#class_Control_method_set_anchors_preset). + + + +[LayoutPreset](class_control.md#enum_Control_LayoutPreset) **PRESET_HCENTER_WIDE** = `14` + +Snap all 4 anchors to a horizontal line that cuts the parent control in half. Use with [set_anchors_preset()](class_control.md#class_Control_method_set_anchors_preset). + + + +[LayoutPreset](class_control.md#enum_Control_LayoutPreset) **PRESET_FULL_RECT** = `15` + +Snap all 4 anchors to the respective corners of the parent control. Set all 4 offsets to 0 after you applied this preset and the **Control** will fit its parent control. Use with [set_anchors_preset()](class_control.md#class_Control_method_set_anchors_preset).
+ + + + + +enum **LayoutPresetMode**: [🔗](#enum_Control_LayoutPresetMode) + + + + + +[LayoutPresetMode](class_control.md#enum_Control_LayoutPresetMode) **PRESET_MODE_MINSIZE** = `0` + +The control will be resized to its minimum size. + + + +[LayoutPresetMode](class_control.md#enum_Control_LayoutPresetMode) **PRESET_MODE_KEEP_WIDTH** = `1` + +The control's width will not change. + + + +[LayoutPresetMode](class_control.md#enum_Control_LayoutPresetMode) **PRESET_MODE_KEEP_HEIGHT** = `2` + +The control's height will not change. + + + +[LayoutPresetMode](class_control.md#enum_Control_LayoutPresetMode) **PRESET_MODE_KEEP_SIZE** = `3` + +The control's size will not change.
+ + + + + +flags **SizeFlags**: [🔗](#enum_Control_SizeFlags) + + + + + +[SizeFlags](class_control.md#enum_Control_SizeFlags) **SIZE_SHRINK_BEGIN** = `0` + +Tells the parent [Container](class_container.md) to align the node with its start, either the top or the left edge. It is mutually exclusive with [SIZE_FILL](class_control.md#class_Control_constant_SIZE_FILL) and other shrink size flags, but can be used with [SIZE_EXPAND](class_control.md#class_Control_constant_SIZE_EXPAND) in some containers. Use with [size_flags_horizontal](class_control.md#class_Control_property_size_flags_horizontal) and [size_flags_vertical](class_control.md#class_Control_property_size_flags_vertical). + +\ **Note:** Setting this flag is equal to not having any size flags. + + + +[SizeFlags](class_control.md#enum_Control_SizeFlags) **SIZE_FILL** = `1` + +Tells the parent [Container](class_container.md) to expand the bounds of this node to fill all the available space without pushing any other node. It is mutually exclusive with shrink size flags. Use with [size_flags_horizontal](class_control.md#class_Control_property_size_flags_horizontal) and [size_flags_vertical](class_control.md#class_Control_property_size_flags_vertical). + + + +[SizeFlags](class_control.md#enum_Control_SizeFlags) **SIZE_EXPAND** = `2` + +Tells the parent [Container](class_container.md) to let this node take all the available space on the axis you flag. If multiple neighboring nodes are set to expand, they'll share the space based on their stretch ratio. See [size_flags_stretch_ratio](class_control.md#class_Control_property_size_flags_stretch_ratio). Use with [size_flags_horizontal](class_control.md#class_Control_property_size_flags_horizontal) and [size_flags_vertical](class_control.md#class_Control_property_size_flags_vertical). + + + +[SizeFlags](class_control.md#enum_Control_SizeFlags) **SIZE_EXPAND_FILL** = `3` + +Sets the node's size flags to both fill and expand. See [SIZE_FILL](class_control.md#class_Control_constant_SIZE_FILL) and [SIZE_EXPAND](class_control.md#class_Control_constant_SIZE_EXPAND) for more information. + + + +[SizeFlags](class_control.md#enum_Control_SizeFlags) **SIZE_SHRINK_CENTER** = `4` + +Tells the parent [Container](class_container.md) to center the node in the available space. It is mutually exclusive with [SIZE_FILL](class_control.md#class_Control_constant_SIZE_FILL) and other shrink size flags, but can be used with [SIZE_EXPAND](class_control.md#class_Control_constant_SIZE_EXPAND) in some containers. Use with [size_flags_horizontal](class_control.md#class_Control_property_size_flags_horizontal) and [size_flags_vertical](class_control.md#class_Control_property_size_flags_vertical). + + + +[SizeFlags](class_control.md#enum_Control_SizeFlags) **SIZE_SHRINK_END** = `8` + +Tells the parent [Container](class_container.md) to align the node with its end, either the bottom or the right edge. It is mutually exclusive with [SIZE_FILL](class_control.md#class_Control_constant_SIZE_FILL) and other shrink size flags, but can be used with [SIZE_EXPAND](class_control.md#class_Control_constant_SIZE_EXPAND) in some containers. Use with [size_flags_horizontal](class_control.md#class_Control_property_size_flags_horizontal) and [size_flags_vertical](class_control.md#class_Control_property_size_flags_vertical).
+ + + + + +enum **MouseFilter**: [🔗](#enum_Control_MouseFilter) + + + + + +[MouseFilter](class_control.md#enum_Control_MouseFilter) **MOUSE_FILTER_STOP** = `0` + +The control will receive mouse movement input events and mouse button input events if clicked on through [_gui_input()](class_control.md#class_Control_private_method__gui_input). The control will also receive the [mouse_entered](class_control.md#class_Control_signal_mouse_entered) and [mouse_exited](class_control.md#class_Control_signal_mouse_exited) signals. These events are automatically marked as handled, and they will not propagate further to other controls. This also results in blocking signals in other controls. + + + +[MouseFilter](class_control.md#enum_Control_MouseFilter) **MOUSE_FILTER_PASS** = `1` + +The control will receive mouse movement input events and mouse button input events if clicked on through [_gui_input()](class_control.md#class_Control_private_method__gui_input). The control will also receive the [mouse_entered](class_control.md#class_Control_signal_mouse_entered) and [mouse_exited](class_control.md#class_Control_signal_mouse_exited) signals. + +If this control does not handle the event, the event will propagate up to its parent control if it has one. The event is bubbled up the node hierarchy until it reaches a non-[CanvasItem](class_canvasitem.md), a control with [MOUSE_FILTER_STOP](class_control.md#class_Control_constant_MOUSE_FILTER_STOP), or a [CanvasItem](class_canvasitem.md) with [CanvasItem.top_level](class_canvasitem.md#class_CanvasItem_property_top_level) enabled. This will allow signals to fire in all controls it reaches. If no control handled it, the event will be passed to [Node._shortcut_input()](class_node.md#class_Node_private_method__shortcut_input) for further processing. + + + +[MouseFilter](class_control.md#enum_Control_MouseFilter) **MOUSE_FILTER_IGNORE** = `2` + +The control will not receive any mouse movement input events nor mouse button input events through [_gui_input()](class_control.md#class_Control_private_method__gui_input). The control will also not receive the [mouse_entered](class_control.md#class_Control_signal_mouse_entered) nor [mouse_exited](class_control.md#class_Control_signal_mouse_exited) signals. This will not block other controls from receiving these events or firing the signals. Ignored events will not be handled automatically. If a child has [MOUSE_FILTER_PASS](class_control.md#class_Control_constant_MOUSE_FILTER_PASS) and an event was passed to this control, the event will further propagate up to the control's parent. + +\ **Note:** If the control has received [mouse_entered](class_control.md#class_Control_signal_mouse_entered) but not [mouse_exited](class_control.md#class_Control_signal_mouse_exited), changing the [mouse_filter](class_control.md#class_Control_property_mouse_filter) to [MOUSE_FILTER_IGNORE](class_control.md#class_Control_constant_MOUSE_FILTER_IGNORE) will cause [mouse_exited](class_control.md#class_Control_signal_mouse_exited) to be emitted.
+ + + + + +enum **GrowDirection**: [🔗](#enum_Control_GrowDirection) + + + + + +[GrowDirection](class_control.md#enum_Control_GrowDirection) **GROW_DIRECTION_BEGIN** = `0` + +The control will grow to the left or top to make up if its minimum size is changed to be greater than its current size on the respective axis. + + + +[GrowDirection](class_control.md#enum_Control_GrowDirection) **GROW_DIRECTION_END** = `1` + +The control will grow to the right or bottom to make up if its minimum size is changed to be greater than its current size on the respective axis. + + + +[GrowDirection](class_control.md#enum_Control_GrowDirection) **GROW_DIRECTION_BOTH** = `2` + +The control will grow in both directions equally to make up if its minimum size is changed to be greater than its current size.
+ + + + + +enum **Anchor**: [🔗](#enum_Control_Anchor) + + + + + +[Anchor](class_control.md#enum_Control_Anchor) **ANCHOR_BEGIN** = `0` + +Snaps one of the 4 anchor's sides to the origin of the node's ``Rect``, in the top left. Use it with one of the ``anchor_*`` member variables, like [anchor_left](class_control.md#class_Control_property_anchor_left). To change all 4 anchors at once, use [set_anchors_preset()](class_control.md#class_Control_method_set_anchors_preset). + + + +[Anchor](class_control.md#enum_Control_Anchor) **ANCHOR_END** = `1` + +Snaps one of the 4 anchor's sides to the end of the node's ``Rect``, in the bottom right. Use it with one of the ``anchor_*`` member variables, like [anchor_left](class_control.md#class_Control_property_anchor_left). To change all 4 anchors at once, use [set_anchors_preset()](class_control.md#class_Control_method_set_anchors_preset).
+ + + + + +enum **LayoutDirection**: [🔗](#enum_Control_LayoutDirection) + + + + + +[LayoutDirection](class_control.md#enum_Control_LayoutDirection) **LAYOUT_DIRECTION_INHERITED** = `0` + +Automatic layout direction, determined from the parent control layout direction. + + + +[LayoutDirection](class_control.md#enum_Control_LayoutDirection) **LAYOUT_DIRECTION_APPLICATION_LOCALE** = `1` + +Automatic layout direction, determined from the current locale. Right-to-left layout direction is automatically used for languages that require it such as Arabic and Hebrew, but only if a valid translation file is loaded for the given language (unless said language is configured as a fallback in [ProjectSettings.internationalization/locale/fallback](class_projectsettings.md#class_ProjectSettings_property_internationalization/locale/fallback)). For all other languages (or if no valid translation file is found by Redot), left-to-right layout direction is used. If using [TextServerFallback](class_textserverfallback.md) ([ProjectSettings.internationalization/rendering/text_driver](class_projectsettings.md#class_ProjectSettings_property_internationalization/rendering/text_driver)), left-to-right layout direction is always used regardless of the language. Right-to-left layout direction can also be forced using [ProjectSettings.internationalization/rendering/force_right_to_left_layout_direction](class_projectsettings.md#class_ProjectSettings_property_internationalization/rendering/force_right_to_left_layout_direction). + + + +[LayoutDirection](class_control.md#enum_Control_LayoutDirection) **LAYOUT_DIRECTION_LTR** = `2` + +Left-to-right layout direction. + + + +[LayoutDirection](class_control.md#enum_Control_LayoutDirection) **LAYOUT_DIRECTION_RTL** = `3` + +Right-to-left layout direction. + + + +[LayoutDirection](class_control.md#enum_Control_LayoutDirection) **LAYOUT_DIRECTION_SYSTEM_LOCALE** = `4` + +Automatic layout direction, determined from the system locale. Right-to-left layout direction is automatically used for languages that require it such as Arabic and Hebrew, but only if a valid translation file is loaded for the given language.. For all other languages (or if no valid translation file is found by Redot), left-to-right layout direction is used. If using [TextServerFallback](class_textserverfallback.md) ([ProjectSettings.internationalization/rendering/text_driver](class_projectsettings.md#class_ProjectSettings_property_internationalization/rendering/text_driver)), left-to-right layout direction is always used regardless of the language. + + + +[LayoutDirection](class_control.md#enum_Control_LayoutDirection) **LAYOUT_DIRECTION_MAX** = `5` + +Represents the size of the [LayoutDirection](class_control.md#enum_Control_LayoutDirection) enum. + + + +[LayoutDirection](class_control.md#enum_Control_LayoutDirection) **LAYOUT_DIRECTION_LOCALE** = `1` + +**Deprecated:** Use [LAYOUT_DIRECTION_APPLICATION_LOCALE](class_control.md#class_Control_constant_LAYOUT_DIRECTION_APPLICATION_LOCALE) instead. + +
+ + + + + +enum **TextDirection**: [🔗](#enum_Control_TextDirection) + + + + + +[TextDirection](class_control.md#enum_Control_TextDirection) **TEXT_DIRECTION_INHERITED** = `3` + +Text writing direction is the same as layout direction. + + + +[TextDirection](class_control.md#enum_Control_TextDirection) **TEXT_DIRECTION_AUTO** = `0` + +Automatic text writing direction, determined from the current locale and text content. + + + +[TextDirection](class_control.md#enum_Control_TextDirection) **TEXT_DIRECTION_LTR** = `1` + +Left-to-right text writing direction. + + + +[TextDirection](class_control.md#enum_Control_TextDirection) **TEXT_DIRECTION_RTL** = `2` + +Right-to-left text writing direction.
+ + + +## Constants + + + + + +**NOTIFICATION_RESIZED** = `40` [🔗](#class_Control_constant_NOTIFICATION_RESIZED) + +Sent when the node changes size. Use [size](class_control.md#class_Control_property_size) to get the new size. + + + + + +**NOTIFICATION_MOUSE_ENTER** = `41` [🔗](#class_Control_constant_NOTIFICATION_MOUSE_ENTER) + +Sent when the mouse cursor enters the control's (or any child control's) visible area, that is not occluded behind other Controls or Windows, provided its [mouse_filter](class_control.md#class_Control_property_mouse_filter) lets the event reach it and regardless if it's currently focused or not. + +\ **Note:** [CanvasItem.z_index](class_canvasitem.md#class_CanvasItem_property_z_index) doesn't affect which Control receives the notification. + +See also [NOTIFICATION_MOUSE_ENTER_SELF](class_control.md#class_Control_constant_NOTIFICATION_MOUSE_ENTER_SELF). + + + + + +**NOTIFICATION_MOUSE_EXIT** = `42` [🔗](#class_Control_constant_NOTIFICATION_MOUSE_EXIT) + +Sent when the mouse cursor leaves the control's (and all child control's) visible area, that is not occluded behind other Controls or Windows, provided its [mouse_filter](class_control.md#class_Control_property_mouse_filter) lets the event reach it and regardless if it's currently focused or not. + +\ **Note:** [CanvasItem.z_index](class_canvasitem.md#class_CanvasItem_property_z_index) doesn't affect which Control receives the notification. + +See also [NOTIFICATION_MOUSE_EXIT_SELF](class_control.md#class_Control_constant_NOTIFICATION_MOUSE_EXIT_SELF). + + + + + +**NOTIFICATION_MOUSE_ENTER_SELF** = `60` [🔗](#class_Control_constant_NOTIFICATION_MOUSE_ENTER_SELF) + +**Experimental:** The reason this notification is sent may change in the future. + +Sent when the mouse cursor enters the control's visible area, that is not occluded behind other Controls or Windows, provided its [mouse_filter](class_control.md#class_Control_property_mouse_filter) lets the event reach it and regardless if it's currently focused or not. + +\ **Note:** [CanvasItem.z_index](class_canvasitem.md#class_CanvasItem_property_z_index) doesn't affect which Control receives the notification. + +See also [NOTIFICATION_MOUSE_ENTER](class_control.md#class_Control_constant_NOTIFICATION_MOUSE_ENTER). + + + + + +**NOTIFICATION_MOUSE_EXIT_SELF** = `61` [🔗](#class_Control_constant_NOTIFICATION_MOUSE_EXIT_SELF) + +**Experimental:** The reason this notification is sent may change in the future. + +Sent when the mouse cursor leaves the control's visible area, that is not occluded behind other Controls or Windows, provided its [mouse_filter](class_control.md#class_Control_property_mouse_filter) lets the event reach it and regardless if it's currently focused or not. + +\ **Note:** [CanvasItem.z_index](class_canvasitem.md#class_CanvasItem_property_z_index) doesn't affect which Control receives the notification. + +See also [NOTIFICATION_MOUSE_EXIT](class_control.md#class_Control_constant_NOTIFICATION_MOUSE_EXIT). + + + + + +**NOTIFICATION_FOCUS_ENTER** = `43` [🔗](#class_Control_constant_NOTIFICATION_FOCUS_ENTER) + +Sent when the node grabs focus. + + + + + +**NOTIFICATION_FOCUS_EXIT** = `44` [🔗](#class_Control_constant_NOTIFICATION_FOCUS_EXIT) + +Sent when the node loses focus. + + + + + +**NOTIFICATION_THEME_CHANGED** = `45` [🔗](#class_Control_constant_NOTIFICATION_THEME_CHANGED) + +Sent when the node needs to refresh its theme items. This happens in one of the following cases: + +- The [theme](class_control.md#class_Control_property_theme) property is changed on this node or any of its ancestors. + +- The [theme_type_variation](class_control.md#class_Control_property_theme_type_variation) property is changed on this node. + +- One of the node's theme property overrides is changed. + +- The node enters the scene tree. + +\ **Note:** As an optimization, this notification won't be sent from changes that occur while this node is outside of the scene tree. Instead, all of the theme item updates can be applied at once when the node enters the scene tree. + +\ **Note:** This notification is received alongside [Node.NOTIFICATION_ENTER_TREE](class_node.md#class_Node_constant_NOTIFICATION_ENTER_TREE), so if you are instantiating a scene, the child nodes will not be initialized yet. You can use it to setup theming for this node, child nodes created from script, or if you want to access child nodes added in the editor, make sure the node is ready using [Node.is_node_ready()](class_node.md#class_Node_method_is_node_ready). + +``` + func _notification(what): + if what == NOTIFICATION_THEME_CHANGED: + if not is_node_ready(): + await ready # Wait until ready signal. + $Label.add_theme_color_override("font_color", Color.YELLOW) +``` + + + + + +**NOTIFICATION_SCROLL_BEGIN** = `47` [🔗](#class_Control_constant_NOTIFICATION_SCROLL_BEGIN) + +Sent when this node is inside a [ScrollContainer](class_scrollcontainer.md) which has begun being scrolled when dragging the scrollable area *with a touch event*. This notification is *not* sent when scrolling by dragging the scrollbar, scrolling with the mouse wheel or scrolling with keyboard/gamepad events. + +\ **Note:** This signal is only emitted on Android or iOS, or on desktop/web platforms when [ProjectSettings.input_devices/pointing/emulate_touch_from_mouse](class_projectsettings.md#class_ProjectSettings_property_input_devices/pointing/emulate_touch_from_mouse) is enabled. + + + + + +**NOTIFICATION_SCROLL_END** = `48` [🔗](#class_Control_constant_NOTIFICATION_SCROLL_END) + +Sent when this node is inside a [ScrollContainer](class_scrollcontainer.md) which has stopped being scrolled when dragging the scrollable area *with a touch event*. This notification is *not* sent when scrolling by dragging the scrollbar, scrolling with the mouse wheel or scrolling with keyboard/gamepad events. + +\ **Note:** This signal is only emitted on Android or iOS, or on desktop/web platforms when [ProjectSettings.input_devices/pointing/emulate_touch_from_mouse](class_projectsettings.md#class_ProjectSettings_property_input_devices/pointing/emulate_touch_from_mouse) is enabled. + + + + + +**NOTIFICATION_LAYOUT_DIRECTION_CHANGED** = `49` [🔗](#class_Control_constant_NOTIFICATION_LAYOUT_DIRECTION_CHANGED) + +Sent when the control layout direction is changed from LTR or RTL or vice versa. This notification is propagated to child Control nodes as result of a change to [layout_direction](class_control.md#class_Control_property_layout_direction). + +
+ + + +## Property Descriptions + + + + + +[Array](class_array.md)\[[NodePath](class_nodepath.md)\] **accessibility_controls_nodes** = `[]` [🔗](#class_Control_property_accessibility_controls_nodes) + + + +- `void` **set_accessibility_controls_nodes**\ (\ value\: [Array](class_array.md)\[[NodePath](class_nodepath.md)\]\ ) +- [Array](class_array.md)\[[NodePath](class_nodepath.md)\] **get_accessibility_controls_nodes**\ (\ ) + +The paths to the nodes which are controlled by this node. + +
+ + + + + +[Array](class_array.md)\[[NodePath](class_nodepath.md)\] **accessibility_described_by_nodes** = `[]` [🔗](#class_Control_property_accessibility_described_by_nodes) + + + +- `void` **set_accessibility_described_by_nodes**\ (\ value\: [Array](class_array.md)\[[NodePath](class_nodepath.md)\]\ ) +- [Array](class_array.md)\[[NodePath](class_nodepath.md)\] **get_accessibility_described_by_nodes**\ (\ ) + +The paths to the nodes which are describing this node. + +
+ + + + + +[String](class_string.md) **accessibility_description** = `""` [🔗](#class_Control_property_accessibility_description) + + + +- `void` **set_accessibility_description**\ (\ value\: [String](class_string.md)\ ) +- [String](class_string.md) **get_accessibility_description**\ (\ ) + +The human-readable node description that is reported to assistive apps. + +
+ + + + + +[Array](class_array.md)\[[NodePath](class_nodepath.md)\] **accessibility_flow_to_nodes** = `[]` [🔗](#class_Control_property_accessibility_flow_to_nodes) + + + +- `void` **set_accessibility_flow_to_nodes**\ (\ value\: [Array](class_array.md)\[[NodePath](class_nodepath.md)\]\ ) +- [Array](class_array.md)\[[NodePath](class_nodepath.md)\] **get_accessibility_flow_to_nodes**\ (\ ) + +The paths to the nodes which this node flows into. + +
+ + + + + +[Array](class_array.md)\[[NodePath](class_nodepath.md)\] **accessibility_labeled_by_nodes** = `[]` [🔗](#class_Control_property_accessibility_labeled_by_nodes) + + + +- `void` **set_accessibility_labeled_by_nodes**\ (\ value\: [Array](class_array.md)\[[NodePath](class_nodepath.md)\]\ ) +- [Array](class_array.md)\[[NodePath](class_nodepath.md)\] **get_accessibility_labeled_by_nodes**\ (\ ) + +The paths to the nodes which label this node. + +
+ + + + + +[AccessibilityLiveMode](class_displayserver.md#enum_DisplayServer_AccessibilityLiveMode) **accessibility_live** = `0` [🔗](#class_Control_property_accessibility_live) + + + +- `void` **set_accessibility_live**\ (\ value\: [AccessibilityLiveMode](class_displayserver.md#enum_DisplayServer_AccessibilityLiveMode)\ ) +- [AccessibilityLiveMode](class_displayserver.md#enum_DisplayServer_AccessibilityLiveMode) **get_accessibility_live**\ (\ ) + +The mode with which a live region updates. A live region is a [Node](class_node.md) that is updated as a result of an external event when the user's focus may be elsewhere. + +
+ + + + + +[String](class_string.md) **accessibility_name** = `""` [🔗](#class_Control_property_accessibility_name) + + + +- `void` **set_accessibility_name**\ (\ value\: [String](class_string.md)\ ) +- [String](class_string.md) **get_accessibility_name**\ (\ ) + +The human-readable node name that is reported to assistive apps. + +
+ + + + + +[float](class_float.md) **anchor_bottom** = `0.0` [🔗](#class_Control_property_anchor_bottom) + + + +- [float](class_float.md) **get_anchor**\ (\ side\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const + +Anchors the bottom edge of the node to the origin, the center, or the end of its parent control. It changes how the bottom offset updates when the node moves or changes size. You can use one of the [Anchor](class_control.md#enum_Control_Anchor) constants for convenience. + +
+ + + + + +[float](class_float.md) **anchor_left** = `0.0` [🔗](#class_Control_property_anchor_left) + + + +- [float](class_float.md) **get_anchor**\ (\ side\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const + +Anchors the left edge of the node to the origin, the center or the end of its parent control. It changes how the left offset updates when the node moves or changes size. You can use one of the [Anchor](class_control.md#enum_Control_Anchor) constants for convenience. + +
+ + + + + +[float](class_float.md) **anchor_right** = `0.0` [🔗](#class_Control_property_anchor_right) + + + +- [float](class_float.md) **get_anchor**\ (\ side\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const + +Anchors the right edge of the node to the origin, the center or the end of its parent control. It changes how the right offset updates when the node moves or changes size. You can use one of the [Anchor](class_control.md#enum_Control_Anchor) constants for convenience. + +
+ + + + + +[float](class_float.md) **anchor_top** = `0.0` [🔗](#class_Control_property_anchor_top) + + + +- [float](class_float.md) **get_anchor**\ (\ side\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const + +Anchors the top edge of the node to the origin, the center or the end of its parent control. It changes how the top offset updates when the node moves or changes size. You can use one of the [Anchor](class_control.md#enum_Control_Anchor) constants for convenience. + +
+ + + + + +[bool](class_bool.md) **auto_translate** [🔗](#class_Control_property_auto_translate) + + + +- `void` **set_auto_translate**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_auto_translating**\ (\ ) + +**Deprecated:** Use [Node.auto_translate_mode](class_node.md#class_Node_property_auto_translate_mode) and [Node.can_auto_translate()](class_node.md#class_Node_method_can_auto_translate) instead. + +Toggles if any text should automatically change to its translated version depending on the current locale. + +
+ + + + + +[bool](class_bool.md) **clip_contents** = `false` [🔗](#class_Control_property_clip_contents) + + + +- `void` **set_clip_contents**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_clipping_contents**\ (\ ) + +Enables whether rendering of [CanvasItem](class_canvasitem.md) based children should be clipped to this control's rectangle. If ``true``, parts of a child which would be visibly outside of this control's rectangle will not be rendered and won't receive input. + +
+ + + + + +[Vector2](class_vector2.md) **custom_minimum_size** = `Vector2(0, 0)` [🔗](#class_Control_property_custom_minimum_size) + + + +- `void` **set_custom_minimum_size**\ (\ value\: [Vector2](class_vector2.md)\ ) +- [Vector2](class_vector2.md) **get_custom_minimum_size**\ (\ ) + +The minimum size of the node's bounding rectangle. If you set it to a value greater than ``(0, 0)``, the node's bounding rectangle will always have at least this size. Note that **Control** nodes have their internal minimum size returned by [get_minimum_size()](class_control.md#class_Control_method_get_minimum_size). It depends on the control's contents, like text, textures, or style boxes. The actual minimum size is the maximum value of this property and the internal minimum size (see [get_combined_minimum_size()](class_control.md#class_Control_method_get_combined_minimum_size)). + +
+ + + + + +[FocusBehaviorRecursive](class_control.md#enum_Control_FocusBehaviorRecursive) **focus_behavior_recursive** = `0` [🔗](#class_Control_property_focus_behavior_recursive) + + + +- `void` **set_focus_behavior_recursive**\ (\ value\: [FocusBehaviorRecursive](class_control.md#enum_Control_FocusBehaviorRecursive)\ ) +- [FocusBehaviorRecursive](class_control.md#enum_Control_FocusBehaviorRecursive) **get_focus_behavior_recursive**\ (\ ) + +Determines which controls can be focused together with [focus_mode](class_control.md#class_Control_property_focus_mode). See [get_focus_mode_with_override()](class_control.md#class_Control_method_get_focus_mode_with_override). Since the default behavior is [FOCUS_BEHAVIOR_INHERITED](class_control.md#class_Control_constant_FOCUS_BEHAVIOR_INHERITED), this can be used to prevent all children controls from getting focused. + +
+ + + + + +[FocusMode](class_control.md#enum_Control_FocusMode) **focus_mode** = `0` [🔗](#class_Control_property_focus_mode) + + + +- `void` **set_focus_mode**\ (\ value\: [FocusMode](class_control.md#enum_Control_FocusMode)\ ) +- [FocusMode](class_control.md#enum_Control_FocusMode) **get_focus_mode**\ (\ ) + +Determines which controls can be focused. Only one control can be focused at a time, and the focused control will receive keyboard, gamepad, and mouse events in [_gui_input()](class_control.md#class_Control_private_method__gui_input). Use [get_focus_mode_with_override()](class_control.md#class_Control_method_get_focus_mode_with_override) to determine if a control can grab focus, since [focus_behavior_recursive](class_control.md#class_Control_property_focus_behavior_recursive) also affects it. See also [grab_focus()](class_control.md#class_Control_method_grab_focus). + +
+ + + + + +[NodePath](class_nodepath.md) **focus_neighbor_bottom** = `NodePath("")` [🔗](#class_Control_property_focus_neighbor_bottom) + + + +- `void` **set_focus_neighbor**\ (\ side\: [Side](class_@globalscope.md#enum_@GlobalScope_Side), neighbor\: [NodePath](class_nodepath.md)\ ) +- [NodePath](class_nodepath.md) **get_focus_neighbor**\ (\ side\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const + +Tells Redot which node it should give focus to if the user presses the down arrow on the keyboard or down on a gamepad by default. You can change the key by editing the [ProjectSettings.input/ui_down](class_projectsettings.md#class_ProjectSettings_property_input/ui_down) input action. The node must be a **Control**. If this property is not set, Redot will give focus to the closest **Control** to the bottom of this one. + +
+ + + + + +[NodePath](class_nodepath.md) **focus_neighbor_left** = `NodePath("")` [🔗](#class_Control_property_focus_neighbor_left) + + + +- `void` **set_focus_neighbor**\ (\ side\: [Side](class_@globalscope.md#enum_@GlobalScope_Side), neighbor\: [NodePath](class_nodepath.md)\ ) +- [NodePath](class_nodepath.md) **get_focus_neighbor**\ (\ side\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const + +Tells Redot which node it should give focus to if the user presses the left arrow on the keyboard or left on a gamepad by default. You can change the key by editing the [ProjectSettings.input/ui_left](class_projectsettings.md#class_ProjectSettings_property_input/ui_left) input action. The node must be a **Control**. If this property is not set, Redot will give focus to the closest **Control** to the left of this one. + +
+ + + + + +[NodePath](class_nodepath.md) **focus_neighbor_right** = `NodePath("")` [🔗](#class_Control_property_focus_neighbor_right) + + + +- `void` **set_focus_neighbor**\ (\ side\: [Side](class_@globalscope.md#enum_@GlobalScope_Side), neighbor\: [NodePath](class_nodepath.md)\ ) +- [NodePath](class_nodepath.md) **get_focus_neighbor**\ (\ side\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const + +Tells Redot which node it should give focus to if the user presses the right arrow on the keyboard or right on a gamepad by default. You can change the key by editing the [ProjectSettings.input/ui_right](class_projectsettings.md#class_ProjectSettings_property_input/ui_right) input action. The node must be a **Control**. If this property is not set, Redot will give focus to the closest **Control** to the right of this one. + +
+ + + + + +[NodePath](class_nodepath.md) **focus_neighbor_top** = `NodePath("")` [🔗](#class_Control_property_focus_neighbor_top) + + + +- `void` **set_focus_neighbor**\ (\ side\: [Side](class_@globalscope.md#enum_@GlobalScope_Side), neighbor\: [NodePath](class_nodepath.md)\ ) +- [NodePath](class_nodepath.md) **get_focus_neighbor**\ (\ side\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const + +Tells Redot which node it should give focus to if the user presses the top arrow on the keyboard or top on a gamepad by default. You can change the key by editing the [ProjectSettings.input/ui_up](class_projectsettings.md#class_ProjectSettings_property_input/ui_up) input action. The node must be a **Control**. If this property is not set, Redot will give focus to the closest **Control** to the top of this one. + +
+ + + + + +[NodePath](class_nodepath.md) **focus_next** = `NodePath("")` [🔗](#class_Control_property_focus_next) + + + +- `void` **set_focus_next**\ (\ value\: [NodePath](class_nodepath.md)\ ) +- [NodePath](class_nodepath.md) **get_focus_next**\ (\ ) + +Tells Redot which node it should give focus to if the user presses :kbd:`Tab` on a keyboard by default. You can change the key by editing the [ProjectSettings.input/ui_focus_next](class_projectsettings.md#class_ProjectSettings_property_input/ui_focus_next) input action. + +If this property is not set, Redot will select a "best guess" based on surrounding nodes in the scene tree. + +
+ + + + + +[NodePath](class_nodepath.md) **focus_previous** = `NodePath("")` [🔗](#class_Control_property_focus_previous) + + + +- `void` **set_focus_previous**\ (\ value\: [NodePath](class_nodepath.md)\ ) +- [NodePath](class_nodepath.md) **get_focus_previous**\ (\ ) + +Tells Redot which node it should give focus to if the user presses :kbd:`Shift + Tab` on a keyboard by default. You can change the key by editing the [ProjectSettings.input/ui_focus_prev](class_projectsettings.md#class_ProjectSettings_property_input/ui_focus_prev) input action. + +If this property is not set, Redot will select a "best guess" based on surrounding nodes in the scene tree. + +
+ + + + + +[Vector2](class_vector2.md) **global_position** [🔗](#class_Control_property_global_position) + + + +- [Vector2](class_vector2.md) **get_global_position**\ (\ ) + +The node's global position, relative to the world (usually to the [CanvasLayer](class_canvaslayer.md)). + +
+ + + + + +[GrowDirection](class_control.md#enum_Control_GrowDirection) **grow_horizontal** = `1` [🔗](#class_Control_property_grow_horizontal) + + + +- `void` **set_h_grow_direction**\ (\ value\: [GrowDirection](class_control.md#enum_Control_GrowDirection)\ ) +- [GrowDirection](class_control.md#enum_Control_GrowDirection) **get_h_grow_direction**\ (\ ) + +Controls the direction on the horizontal axis in which the control should grow if its horizontal minimum size is changed to be greater than its current size, as the control always has to be at least the minimum size. + +
+ + + + + +[GrowDirection](class_control.md#enum_Control_GrowDirection) **grow_vertical** = `1` [🔗](#class_Control_property_grow_vertical) + + + +- `void` **set_v_grow_direction**\ (\ value\: [GrowDirection](class_control.md#enum_Control_GrowDirection)\ ) +- [GrowDirection](class_control.md#enum_Control_GrowDirection) **get_v_grow_direction**\ (\ ) + +Controls the direction on the vertical axis in which the control should grow if its vertical minimum size is changed to be greater than its current size, as the control always has to be at least the minimum size. + +
+ + + + + +[LayoutDirection](class_control.md#enum_Control_LayoutDirection) **layout_direction** = `0` [🔗](#class_Control_property_layout_direction) + + + +- `void` **set_layout_direction**\ (\ value\: [LayoutDirection](class_control.md#enum_Control_LayoutDirection)\ ) +- [LayoutDirection](class_control.md#enum_Control_LayoutDirection) **get_layout_direction**\ (\ ) + +Controls layout direction and text writing direction. Right-to-left layouts are necessary for certain languages (e.g. Arabic and Hebrew). See also [is_layout_rtl()](class_control.md#class_Control_method_is_layout_rtl). + +
+ + + + + +[bool](class_bool.md) **localize_numeral_system** = `true` [🔗](#class_Control_property_localize_numeral_system) + + + +- `void` **set_localize_numeral_system**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_localizing_numeral_system**\ (\ ) + +If ``true``, automatically converts code line numbers, list indices, [SpinBox](class_spinbox.md) and [ProgressBar](class_progressbar.md) values from the Western Arabic (0..9) to the numeral systems used in current locale. + +\ **Note:** Numbers within the text are not automatically converted, it can be done manually, using [TextServer.format_number()](class_textserver.md#class_TextServer_method_format_number). + +
+ + + + + +[MouseBehaviorRecursive](class_control.md#enum_Control_MouseBehaviorRecursive) **mouse_behavior_recursive** = `0` [🔗](#class_Control_property_mouse_behavior_recursive) + + + +- `void` **set_mouse_behavior_recursive**\ (\ value\: [MouseBehaviorRecursive](class_control.md#enum_Control_MouseBehaviorRecursive)\ ) +- [MouseBehaviorRecursive](class_control.md#enum_Control_MouseBehaviorRecursive) **get_mouse_behavior_recursive**\ (\ ) + +Determines which controls can receive mouse input together with [mouse_filter](class_control.md#class_Control_property_mouse_filter). See [get_mouse_filter_with_override()](class_control.md#class_Control_method_get_mouse_filter_with_override). Since the default behavior is [MOUSE_BEHAVIOR_INHERITED](class_control.md#class_Control_constant_MOUSE_BEHAVIOR_INHERITED), this can be used to prevent all children controls from receiving mouse input. + +
+ + + + + +[CursorShape](class_control.md#enum_Control_CursorShape) **mouse_default_cursor_shape** = `0` [🔗](#class_Control_property_mouse_default_cursor_shape) + + + +- `void` **set_default_cursor_shape**\ (\ value\: [CursorShape](class_control.md#enum_Control_CursorShape)\ ) +- [CursorShape](class_control.md#enum_Control_CursorShape) **get_default_cursor_shape**\ (\ ) + +The default cursor shape for this control. Useful for Redot plugins and applications or games that use the system's mouse cursors. + +\ **Note:** On Linux, shapes may vary depending on the cursor theme of the system. + +
+ + + + + +[MouseFilter](class_control.md#enum_Control_MouseFilter) **mouse_filter** = `0` [🔗](#class_Control_property_mouse_filter) + + + +- `void` **set_mouse_filter**\ (\ value\: [MouseFilter](class_control.md#enum_Control_MouseFilter)\ ) +- [MouseFilter](class_control.md#enum_Control_MouseFilter) **get_mouse_filter**\ (\ ) + +Determines which controls will be able to receive mouse button input events through [_gui_input()](class_control.md#class_Control_private_method__gui_input) and the [mouse_entered](class_control.md#class_Control_signal_mouse_entered), and [mouse_exited](class_control.md#class_Control_signal_mouse_exited) signals. Also determines how these events should be propagated. See the constants to learn what each does. Use [get_mouse_filter_with_override()](class_control.md#class_Control_method_get_mouse_filter_with_override) to determine if a control can receive mouse input, since [mouse_behavior_recursive](class_control.md#class_Control_property_mouse_behavior_recursive) also affects it. + +
+ + + + + +[bool](class_bool.md) **mouse_force_pass_scroll_events** = `true` [🔗](#class_Control_property_mouse_force_pass_scroll_events) + + + +- `void` **set_force_pass_scroll_events**\ (\ value\: [bool](class_bool.md)\ ) +- [bool](class_bool.md) **is_force_pass_scroll_events**\ (\ ) + +When enabled, scroll wheel events processed by [_gui_input()](class_control.md#class_Control_private_method__gui_input) will be passed to the parent control even if [mouse_filter](class_control.md#class_Control_property_mouse_filter) is set to [MOUSE_FILTER_STOP](class_control.md#class_Control_constant_MOUSE_FILTER_STOP). + +You should disable it on the root of your UI if you do not want scroll events to go to the [Node._unhandled_input()](class_node.md#class_Node_private_method__unhandled_input) processing. + +\ **Note:** Because this property defaults to ``true``, this allows nested scrollable containers to work out of the box. + +
+ + + + + +[float](class_float.md) **offset_bottom** = `0.0` [🔗](#class_Control_property_offset_bottom) + + + +- `void` **set_offset**\ (\ side\: [Side](class_@globalscope.md#enum_@GlobalScope_Side), offset\: [float](class_float.md)\ ) +- [float](class_float.md) **get_offset**\ (\ offset\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const + +Distance between the node's bottom edge and its parent control, based on [anchor_bottom](class_control.md#class_Control_property_anchor_bottom). + +Offsets are often controlled by one or multiple parent [Container](class_container.md) nodes, so you should not modify them manually if your node is a direct child of a [Container](class_container.md). Offsets update automatically when you move or resize the node. + +
+ + + + + +[float](class_float.md) **offset_left** = `0.0` [🔗](#class_Control_property_offset_left) + + + +- `void` **set_offset**\ (\ side\: [Side](class_@globalscope.md#enum_@GlobalScope_Side), offset\: [float](class_float.md)\ ) +- [float](class_float.md) **get_offset**\ (\ offset\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const + +Distance between the node's left edge and its parent control, based on [anchor_left](class_control.md#class_Control_property_anchor_left). + +Offsets are often controlled by one or multiple parent [Container](class_container.md) nodes, so you should not modify them manually if your node is a direct child of a [Container](class_container.md). Offsets update automatically when you move or resize the node. + +
+ + + + + +[float](class_float.md) **offset_right** = `0.0` [🔗](#class_Control_property_offset_right) + + + +- `void` **set_offset**\ (\ side\: [Side](class_@globalscope.md#enum_@GlobalScope_Side), offset\: [float](class_float.md)\ ) +- [float](class_float.md) **get_offset**\ (\ offset\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const + +Distance between the node's right edge and its parent control, based on [anchor_right](class_control.md#class_Control_property_anchor_right). + +Offsets are often controlled by one or multiple parent [Container](class_container.md) nodes, so you should not modify them manually if your node is a direct child of a [Container](class_container.md). Offsets update automatically when you move or resize the node. + +
+ + + + + +[float](class_float.md) **offset_top** = `0.0` [🔗](#class_Control_property_offset_top) + + + +- `void` **set_offset**\ (\ side\: [Side](class_@globalscope.md#enum_@GlobalScope_Side), offset\: [float](class_float.md)\ ) +- [float](class_float.md) **get_offset**\ (\ offset\: [Side](class_@globalscope.md#enum_@GlobalScope_Side)\ ) const + +Distance between the node's top edge and its parent control, based on [anchor_top](class_control.md#class_Control_property_anchor_top). + +Offsets are often controlled by one or multiple parent [Container](class_container.md) nodes, so you should not modify them manually if your node is a direct child of a [Container](class_container.md). Offsets update automatically when you move or resize the node. + +
+ + + + + +[Vector2](class_vector2.md) **pivot_offset** = `Vector2(0, 0)` [🔗](#class_Control_property_pivot_offset) + + + +- `void` **set_pivot_offset**\ (\ value\: [Vector2](class_vector2.md)\ ) +- [Vector2](class_vector2.md) **get_pivot_offset**\ (\ ) + +By default, the node's pivot is its top-left corner. When you change its [rotation](class_control.md#class_Control_property_rotation) or [scale](class_control.md#class_Control_property_scale), it will rotate or scale around this pivot. Set this property to [size](class_control.md#class_Control_property_size) / 2 to pivot around the Control's center. + +
+ + + + + +[Vector2](class_vector2.md) **position** = `Vector2(0, 0)` [🔗](#class_Control_property_position) + + + +- [Vector2](class_vector2.md) **get_position**\ (\ ) + +The node's position, relative to its containing node. It corresponds to the rectangle's top-left corner. The property is not affected by [pivot_offset](class_control.md#class_Control_property_pivot_offset). + +
+ + + + + +[float](class_float.md) **rotation** = `0.0` [🔗](#class_Control_property_rotation) + + + +- `void` **set_rotation**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_rotation**\ (\ ) + +The node's rotation around its pivot, in radians. See [pivot_offset](class_control.md#class_Control_property_pivot_offset) to change the pivot's position. + +\ **Note:** This property is edited in the inspector in degrees. If you want to use degrees in a script, use [rotation_degrees](class_control.md#class_Control_property_rotation_degrees). + +
+ + + + + +[float](class_float.md) **rotation_degrees** [🔗](#class_Control_property_rotation_degrees) + + + +- `void` **set_rotation_degrees**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_rotation_degrees**\ (\ ) + +Helper property to access [rotation](class_control.md#class_Control_property_rotation) in degrees instead of radians. + +
+ + + + + +[Vector2](class_vector2.md) **scale** = `Vector2(1, 1)` [🔗](#class_Control_property_scale) + + + +- `void` **set_scale**\ (\ value\: [Vector2](class_vector2.md)\ ) +- [Vector2](class_vector2.md) **get_scale**\ (\ ) + +The node's scale, relative to its [size](class_control.md#class_Control_property_size). Change this property to scale the node around its [pivot_offset](class_control.md#class_Control_property_pivot_offset). The Control's tooltip will also scale according to this value. + +\ **Note:** This property is mainly intended to be used for animation purposes. To support multiple resolutions in your project, use an appropriate viewport stretch mode as described in the [documentation](../tutorials/rendering/multiple_resolutions.md) instead of scaling Controls individually. + +\ **Note:** [FontFile.oversampling](class_fontfile.md#class_FontFile_property_oversampling) does *not* take **Control** [scale](class_control.md#class_Control_property_scale) into account. This means that scaling up/down will cause bitmap fonts and rasterized (non-MSDF) dynamic fonts to appear blurry or pixelated. To ensure text remains crisp regardless of scale, you can enable MSDF font rendering by enabling [ProjectSettings.gui/theme/default_font_multichannel_signed_distance_field](class_projectsettings.md#class_ProjectSettings_property_gui/theme/default_font_multichannel_signed_distance_field) (applies to the default project font only), or enabling **Multichannel Signed Distance Field** in the import options of a DynamicFont for custom fonts. On system fonts, [SystemFont.multichannel_signed_distance_field](class_systemfont.md#class_SystemFont_property_multichannel_signed_distance_field) can be enabled in the inspector. + +\ **Note:** If the Control node is a child of a [Container](class_container.md) node, the scale will be reset to ``Vector2(1, 1)`` when the scene is instantiated. To set the Control's scale when it's instantiated, wait for one frame using ``await get_tree().process_frame`` then set its [scale](class_control.md#class_Control_property_scale) property. + +
+ + + + + +[Node](class_node.md) **shortcut_context** [🔗](#class_Control_property_shortcut_context) + + + +- `void` **set_shortcut_context**\ (\ value\: [Node](class_node.md)\ ) +- [Node](class_node.md) **get_shortcut_context**\ (\ ) + +The [Node](class_node.md) which must be a parent of the focused **Control** for the shortcut to be activated. If ``null``, the shortcut can be activated when any control is focused (a global shortcut). This allows shortcuts to be accepted only when the user has a certain area of the GUI focused. + +
+ + + + + +[Vector2](class_vector2.md) **size** = `Vector2(0, 0)` [🔗](#class_Control_property_size) + + + +- [Vector2](class_vector2.md) **get_size**\ (\ ) + +The size of the node's bounding rectangle, in the node's coordinate system. [Container](class_container.md) nodes update this property automatically. + +
+ + + + + +**BitField**\[[SizeFlags](class_control.md#enum_Control_SizeFlags)\] **size_flags_horizontal** = `1` [🔗](#class_Control_property_size_flags_horizontal) + + + +- `void` **set_h_size_flags**\ (\ value\: **BitField**\[[SizeFlags](class_control.md#enum_Control_SizeFlags)\]\ ) +- **BitField**\[[SizeFlags](class_control.md#enum_Control_SizeFlags)\] **get_h_size_flags**\ (\ ) + +Tells the parent [Container](class_container.md) nodes how they should resize and place the node on the X axis. Use a combination of the [SizeFlags](class_control.md#enum_Control_SizeFlags) constants to change the flags. See the constants to learn what each does. + +
+ + + + + +[float](class_float.md) **size_flags_stretch_ratio** = `1.0` [🔗](#class_Control_property_size_flags_stretch_ratio) + + + +- `void` **set_stretch_ratio**\ (\ value\: [float](class_float.md)\ ) +- [float](class_float.md) **get_stretch_ratio**\ (\ ) + +If the node and at least one of its neighbors uses the [SIZE_EXPAND](class_control.md#class_Control_constant_SIZE_EXPAND) size flag, the parent [Container](class_container.md) will let it take more or less space depending on this property. If this node has a stretch ratio of 2 and its neighbor a ratio of 1, this node will take two thirds of the available space. + +
+ + + + + +**BitField**\[[SizeFlags](class_control.md#enum_Control_SizeFlags)\] **size_flags_vertical** = `1` [🔗](#class_Control_property_size_flags_vertical) + + + +- `void` **set_v_size_flags**\ (\ value\: **BitField**\[[SizeFlags](class_control.md#enum_Control_SizeFlags)\]\ ) +- **BitField**\[[SizeFlags](class_control.md#enum_Control_SizeFlags)\] **get_v_size_flags**\ (\ ) + +Tells the parent [Container](class_container.md) nodes how they should resize and place the node on the Y axis. Use a combination of the [SizeFlags](class_control.md#enum_Control_SizeFlags) constants to change the flags. See the constants to learn what each does. + +
+ + + + + +[Theme](class_theme.md) **theme** [🔗](#class_Control_property_theme) + + + +- `void` **set_theme**\ (\ value\: [Theme](class_theme.md)\ ) +- [Theme](class_theme.md) **get_theme**\ (\ ) + +The [Theme](class_theme.md) resource this node and all its **Control** and [Window](class_window.md) children use. If a child node has its own [Theme](class_theme.md) resource set, theme items are merged with child's definitions having higher priority. + +\ **Note:** [Window](class_window.md) styles will have no effect unless the window is embedded. + +
+ + + + + +[StringName](class_stringname.md) **theme_type_variation** = `&""` [🔗](#class_Control_property_theme_type_variation) + + + +- `void` **set_theme_type_variation**\ (\ value\: [StringName](class_stringname.md)\ ) +- [StringName](class_stringname.md) **get_theme_type_variation**\ (\ ) + +The name of a theme type variation used by this **Control** to look up its own theme items. When empty, the class name of the node is used (e.g. ``Button`` for the [Button](class_button.md) control), as well as the class names of all parent classes (in order of inheritance). + +When set, this property gives the highest priority to the type of the specified name. This type can in turn extend another type, forming a dependency chain. See [Theme.set_type_variation()](class_theme.md#class_Theme_method_set_type_variation). If the theme item cannot be found using this type or its base types, lookup falls back on the class names. + +\ **Note:** To look up **Control**'s own items use various ``get_theme_*`` methods without specifying ``theme_type``. + +\ **Note:** Theme items are looked for in the tree order, from branch to root, where each **Control** node is checked for its [theme](class_control.md#class_Control_property_theme) property. The earliest match against any type/class name is returned. The project-level Theme and the default Theme are checked last. + +
+ + + + + +[AutoTranslateMode](class_node.md#enum_Node_AutoTranslateMode) **tooltip_auto_translate_mode** = `0` [🔗](#class_Control_property_tooltip_auto_translate_mode) + + + +- `void` **set_tooltip_auto_translate_mode**\ (\ value\: [AutoTranslateMode](class_node.md#enum_Node_AutoTranslateMode)\ ) +- [AutoTranslateMode](class_node.md#enum_Node_AutoTranslateMode) **get_tooltip_auto_translate_mode**\ (\ ) + +Defines if tooltip text should automatically change to its translated version depending on the current locale. Uses the same auto translate mode as this control when set to [Node.AUTO_TRANSLATE_MODE_INHERIT](class_node.md#class_Node_constant_AUTO_TRANSLATE_MODE_INHERIT). + +\ **Note:** Tooltips customized using [_make_custom_tooltip()](class_control.md#class_Control_private_method__make_custom_tooltip) do not use this auto translate mode automatically. + +
+ + + + + +[String](class_string.md) **tooltip_text** = `""` [🔗](#class_Control_property_tooltip_text) + + + +- `void` **set_tooltip_text**\ (\ value\: [String](class_string.md)\ ) +- [String](class_string.md) **get_tooltip_text**\ (\ ) + +The default tooltip text. The tooltip appears when the user's mouse cursor stays idle over this control for a few moments, provided that the [mouse_filter](class_control.md#class_Control_property_mouse_filter) property is not [MOUSE_FILTER_IGNORE](class_control.md#class_Control_constant_MOUSE_FILTER_IGNORE). The time required for the tooltip to appear can be changed with the [ProjectSettings.gui/timers/tooltip_delay_sec](class_projectsettings.md#class_ProjectSettings_property_gui/timers/tooltip_delay_sec) setting. + +This string is the default return value of [get_tooltip()](class_control.md#class_Control_method_get_tooltip). Override [_get_tooltip()](class_control.md#class_Control_private_method__get_tooltip) to generate tooltip text dynamically. Override [_make_custom_tooltip()](class_control.md#class_Control_private_method__make_custom_tooltip) to customize the tooltip interface and behavior. + +The tooltip popup will use either a default implementation, or a custom one that you can provide by overriding [_make_custom_tooltip()](class_control.md#class_Control_private_method__make_custom_tooltip). The default tooltip includes a [PopupPanel](class_popuppanel.md) and [Label](class_label.md) whose theme properties can be customized using [Theme](class_theme.md) methods with the ``"TooltipPanel"`` and ``"TooltipLabel"`` respectively. For example: + + + + +```gdscript + var style_box = StyleBoxFlat.new() + style_box.set_bg_color(Color(1, 1, 0)) + style_box.set_border_width_all(2) + # We assume here that the `theme` property has been assigned a custom Theme beforehand. + theme.set_stylebox("panel", "TooltipPanel", style_box) + theme.set_color("font_color", "TooltipLabel", Color(0, 1, 1)) +``` + +```csharp + var styleBox = new StyleBoxFlat(); + styleBox.SetBgColor(new Color(1, 1, 0)); + styleBox.SetBorderWidthAll(2); + // We assume here that the `Theme` property has been assigned a custom Theme beforehand. + Theme.SetStyleBox("panel", "TooltipPanel", styleBox); + Theme.SetColor("font_color", "TooltipLabel", new Color(0, 1, 1)); +``` + + + +
+ + + +## Method Descriptions + + + + + +[String](class_string.md) **_accessibility_get_contextual_info**\ (\ ) virtual const [🔗](#class_Control_private_method__accessibility_get_contextual_info) + +Return the description of the keyboard shortcuts and other contextual help for this control. + +
+ + + + + +[bool](class_bool.md) **_can_drop_data**\ (\ at_position\: [Vector2](class_vector2.md), data\: [Variant](class_variant.md)\ ) virtual const [🔗](#class_Control_private_method__can_drop_data) + +Redot calls this method to test if `data` from a control's [_get_drag_data()](class_control.md#class_Control_private_method__get_drag_data) can be dropped at `at_position`. `at_position` is local to this control. + +This method should only be used to test the data. Process the data in [_drop_data()](class_control.md#class_Control_private_method__drop_data). + +\ **Note:** If the drag was initiated by a keyboard shortcut or [accessibility_drag()](class_control.md#class_Control_method_accessibility_drag), `at_position` is set to [Vector2.INF](class_vector2.md#class_Vector2_constant_INF), and the currently selected item/text position should be used as the drop position. + + + + +```gdscript + func _can_drop_data(position, data): + # Check position if it is relevant to you + # Otherwise, just check data + return typeof(data) == TYPE_DICTIONARY and data.has("expected") +``` + +```csharp + public override bool _CanDropData(Vector2 atPosition, Variant data) + { + // Check position if it is relevant to you + // Otherwise, just check data + return data.VariantType == Variant.Type.Dictionary && data.AsGodotDictionary().ContainsKey("expected"); + } +``` + + + +
+ + + + + +`void` **_drop_data**\ (\ at_position\: [Vector2](class_vector2.md), data\: [Variant](class_variant.md)\ ) virtual [🔗](#class_Control_private_method__drop_data) + +Redot calls this method to pass you the `data` from a control's [_get_drag_data()](class_control.md#class_Control_private_method__get_drag_data) result. Redot first calls [_can_drop_data()](class_control.md#class_Control_private_method__can_drop_data) to test if `data` is allowed to drop at `at_position` where `at_position` is local to this control. + +\ **Note:** If the drag was initiated by a keyboard shortcut or [accessibility_drag()](class_control.md#class_Control_method_accessibility_drag), `at_position` is set to [Vector2.INF](class_vector2.md#class_Vector2_constant_INF), and the currently selected item/text position should be used as the drop position. + + + + +```gdscript + func _can_drop_data(position, data): + return typeof(data) == TYPE_DICTIONARY and data.has("color") + + func _drop_data(position, data): + var color = data["color"] +``` + +```csharp + public override bool _CanDropData(Vector2 atPosition, Variant data) + { + return data.VariantType == Variant.Type.Dictionary && data.AsGodotDictionary().ContainsKey("color"); + } + + public override void _DropData(Vector2 atPosition, Variant data) + { + Color color = data.AsGodotDictionary()["color"].AsColor(); + } +``` + + + +
+ + + + + +[String](class_string.md) **_get_accessibility_container_name**\ (\ node\: [Node](class_node.md)\ ) virtual const [🔗](#class_Control_private_method__get_accessibility_container_name) + +Override this method to return a human-readable description of the position of the child `node` in the custom container, added to the [accessibility_name](class_control.md#class_Control_property_accessibility_name). + +
+ + + + + +[Variant](class_variant.md) **_get_drag_data**\ (\ at_position\: [Vector2](class_vector2.md)\ ) virtual [🔗](#class_Control_private_method__get_drag_data) + +Redot calls this method to get data that can be dragged and dropped onto controls that expect drop data. Returns ``null`` if there is no data to drag. Controls that want to receive drop data should implement [_can_drop_data()](class_control.md#class_Control_private_method__can_drop_data) and [_drop_data()](class_control.md#class_Control_private_method__drop_data). `at_position` is local to this control. Drag may be forced with [force_drag()](class_control.md#class_Control_method_force_drag). + +A preview that will follow the mouse that should represent the data can be set with [set_drag_preview()](class_control.md#class_Control_method_set_drag_preview). A good time to set the preview is in this method. + +\ **Note:** If the drag was initiated by a keyboard shortcut or [accessibility_drag()](class_control.md#class_Control_method_accessibility_drag), `at_position` is set to [Vector2.INF](class_vector2.md#class_Vector2_constant_INF), and the currently selected item/text position should be used as the drag position. + + + + +```gdscript + func _get_drag_data(position): + var mydata = make_data() # This is your custom method generating the drag data. + set_drag_preview(make_preview(mydata)) # This is your custom method generating the preview of the drag data. + return mydata +``` + +```csharp + public override Variant _GetDragData(Vector2 atPosition) + { + var myData = MakeData(); // This is your custom method generating the drag data. + SetDragPreview(MakePreview(myData)); // This is your custom method generating the preview of the drag data. + return myData; + } +``` + + + +
+ + + + + +[Vector2](class_vector2.md) **_get_minimum_size**\ (\ ) virtual const [🔗](#class_Control_private_method__get_minimum_size) + +Virtual method to be implemented by the user. Returns the minimum size for this control. Alternative to [custom_minimum_size](class_control.md#class_Control_property_custom_minimum_size) for controlling minimum size via code. The actual minimum size will be the max value of these two (in each axis separately). + +If not overridden, defaults to [Vector2.ZERO](class_vector2.md#class_Vector2_constant_ZERO). + +\ **Note:** This method will not be called when the script is attached to a **Control** node that already overrides its minimum size (e.g. [Label](class_label.md), [Button](class_button.md), [PanelContainer](class_panelcontainer.md) etc.). It can only be used with most basic GUI nodes, like **Control**, [Container](class_container.md), [Panel](class_panel.md) etc. + +
+ + + + + +[String](class_string.md) **_get_tooltip**\ (\ at_position\: [Vector2](class_vector2.md)\ ) virtual const [🔗](#class_Control_private_method__get_tooltip) + +Virtual method to be implemented by the user. Returns the tooltip text for the position `at_position` in control's local coordinates, which will typically appear when the cursor is resting over this control. See [get_tooltip()](class_control.md#class_Control_method_get_tooltip). + +\ **Note:** If this method returns an empty [String](class_string.md) and [_make_custom_tooltip()](class_control.md#class_Control_private_method__make_custom_tooltip) is not overridden, no tooltip is displayed. + +
+ + + + + +`void` **_gui_input**\ (\ event\: [InputEvent](class_inputevent.md)\ ) virtual [🔗](#class_Control_private_method__gui_input) + +Virtual method to be implemented by the user. Override this method to handle and accept inputs on UI elements. See also [accept_event()](class_control.md#class_Control_method_accept_event). + +\ **Example:** Click on the control to print a message: + + + + +```gdscript + func _gui_input(event): + if event is InputEventMouseButton: + if event.button_index == MOUSE_BUTTON_LEFT and event.pressed: + print("I've been clicked D:") +``` + +```csharp + public override void _GuiInput(InputEvent @event) + { + if (@event is InputEventMouseButton mb) + { + if (mb.ButtonIndex == MouseButton.Left && mb.Pressed) + { + GD.Print("I've been clicked D:"); + } + } + } +``` + + + +If the `event` inherits [InputEventMouse](class_inputeventmouse.md), this method will **not** be called when: + +- the control's [mouse_filter](class_control.md#class_Control_property_mouse_filter) is set to [MOUSE_FILTER_IGNORE](class_control.md#class_Control_constant_MOUSE_FILTER_IGNORE); + +- the control is obstructed by another control on top, that doesn't have [mouse_filter](class_control.md#class_Control_property_mouse_filter) set to [MOUSE_FILTER_IGNORE](class_control.md#class_Control_constant_MOUSE_FILTER_IGNORE); + +- the control's parent has [mouse_filter](class_control.md#class_Control_property_mouse_filter) set to [MOUSE_FILTER_STOP](class_control.md#class_Control_constant_MOUSE_FILTER_STOP) or has accepted the event; + +- the control's parent has [clip_contents](class_control.md#class_Control_property_clip_contents) enabled and the `event`'s position is outside the parent's rectangle; + +- the `event`'s position is outside the control (see [_has_point()](class_control.md#class_Control_private_method__has_point)). + +\ **Note:** The `event`'s position is relative to this control's origin. + +
+ + + + + +[bool](class_bool.md) **_has_point**\ (\ point\: [Vector2](class_vector2.md)\ ) virtual const [🔗](#class_Control_private_method__has_point) + +Virtual method to be implemented by the user. Returns whether the given `point` is inside this control. + +If not overridden, default behavior is checking if the point is within control's Rect. + +\ **Note:** If you want to check if a point is inside the control, you can use ``Rect2(Vector2.ZERO, size).has_point(point)``. + +
+ + + + + +[Object](class_object.md) **_make_custom_tooltip**\ (\ for_text\: [String](class_string.md)\ ) virtual const [🔗](#class_Control_private_method__make_custom_tooltip) + +Virtual method to be implemented by the user. Returns a **Control** node that should be used as a tooltip instead of the default one. `for_text` is the return value of [get_tooltip()](class_control.md#class_Control_method_get_tooltip). + +The returned node must be of type **Control** or Control-derived. It can have child nodes of any type. It is freed when the tooltip disappears, so make sure you always provide a new instance (if you want to use a pre-existing node from your scene tree, you can duplicate it and pass the duplicated instance). When ``null`` or a non-Control node is returned, the default tooltip will be used instead. + +The returned node will be added as child to a [PopupPanel](class_popuppanel.md), so you should only provide the contents of that panel. That [PopupPanel](class_popuppanel.md) can be themed using [Theme.set_stylebox()](class_theme.md#class_Theme_method_set_stylebox) for the type ``"TooltipPanel"`` (see [tooltip_text](class_control.md#class_Control_property_tooltip_text) for an example). + +\ **Note:** The tooltip is shrunk to minimal size. If you want to ensure it's fully visible, you might want to set its [custom_minimum_size](class_control.md#class_Control_property_custom_minimum_size) to some non-zero value. + +\ **Note:** The node (and any relevant children) should have their [CanvasItem.visible](class_canvasitem.md#class_CanvasItem_property_visible) set to ``true`` when returned, otherwise, the viewport that instantiates it will not be able to calculate its minimum size reliably. + +\ **Note:** If overridden, this method is called even if [get_tooltip()](class_control.md#class_Control_method_get_tooltip) returns an empty string. When this happens with the default tooltip, it is not displayed. To copy this behavior, return ``null`` in this method when `for_text` is empty. + +\ **Example:** Use a constructed node as a tooltip: + + + + +```gdscript + func _make_custom_tooltip(for_text): + var label = Label.new() + label.text = for_text + return label +``` + +```csharp + public override Control _MakeCustomTooltip(string forText) + { + var label = new Label(); + label.Text = forText; + return label; + } +``` + + + +\ **Example:** Usa a scene instance as a tooltip: + + + + +```gdscript + func _make_custom_tooltip(for_text): + var tooltip = preload("res://some_tooltip_scene.tscn").instantiate() + tooltip.get_node("Label").text = for_text + return tooltip +``` + +```csharp + public override Control _MakeCustomTooltip(string forText) + { + Node tooltip = ResourceLoader.Load("res://some_tooltip_scene.tscn").Instantiate(); + tooltip.GetNode